---
path: /studio/hathor/npc-emotional-state
surface: studio
domain: hathor
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/hathor/npc-emotional-state/page.tsx
status: walked
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body
  re-derived 2026-06-03 from current source (lane-console architecture)'
---

# Studio Hathor · NPC Emotional State

## Purpose

Admin lane console for the `@hathor/llm-npc` EmotionalStateManager (Plutchik-wheel
affect engine). The lane seeds an NPC from Big-Five personality traits, applies an
ordered list of emotional triggers, and reads back the resulting primary /
secondary emotions, the dominant emotion for dialogue, the compound dyad (e.g. joy
+ trust → love), and mood / energy / stress. Admin-scoped and fail-closed.

## Entry points

- **Direct URL / bookmark** — `/studio/hathor/npc-emotional-state`;
  `alternates.canonical` is set.
- **Quick-action from siblings** — this page links to the NPC Personality System
  lane.
- **Studio overview** — see [`../../studio-overview.md`](../../studio-overview.md).

## Layout regions

`page.tsx` renders inside `<ShellLayout active="studio">`:

- **Workspace** (`StudioHathorNpcEmotionalStateWorkspace`,
  `data-hathor-npc-emotional-state-workspace`):
  - `<h1>` `WorkspaceHeading` — "Hathor NPC Emotional State Workspace"
  - Summary `<p data-hathor-npc-emotional-state-summary>`
  - Catalog state, then **Personality (Big Five)** trait inputs, the
    **Emotional triggers** builder, and the simulate form + result.
- **Route Map panel** (`<section data-hathor-npc-emotional-state-route-map>`,
  `<h2>Route Map</h2>`): 5 entries from
  `STUDIO_HATHOR_NPC_EMOTIONAL_STATE_ROUTE_MAP` (path + purpose).
- **Quick-action lane** (`className="quickAction"` Links): NPC Personality
  System, Back to Studio workspace index.

## States

- [ ] **Loading** — `<p data-hathor-nes-loading>` "Loading emotional-state engine…".
- [ ] **Unauthorized** — `data-hathor-nes-unauthorized` on 401/403 (admin-scope).
- [ ] **Error** — `data-hathor-nes-error` on a non-OK catalog response or network
      failure.
- [ ] **Ready (form)** — the trait inputs (`data-hathor-nes-traits`), the trigger
      builder (`data-hathor-nes-trigger-form` + `data-hathor-nes-trigger-list`),
      and the simulate form.
- [ ] **Result** — `data-hathor-nes-result` with `data-hathor-nes-dominant`,
      `data-hathor-nes-compound`, `data-hathor-nes-mood`, and the
      `data-hathor-nes-secondary-list`.
- [ ] **Trigger error** — `data-hathor-nes-trigger-error` for an out-of-range
      intensity on add.
- [ ] **Simulate error** — `data-hathor-nes-simulate-error` for no triggers, an
      out-of-range trait, or a failed POST.

## Interactions

- [ ] **`data-hathor-nes-trait`** (per-trait inputs, `aria-label="trait <key>"`) —
      one for each Big-Five key (openness, conscientiousness, extraversion,
      agreeableness, neuroticism), values 0–1.
- [ ] **`data-hathor-nes-field-emotion`** (select from `catalog.emotions`) and
      **`data-hathor-nes-field-intensity`** (input) — the draft trigger.
- [ ] **`data-hathor-nes-trigger-add`** ("Add trigger") — appends to the trigger
      list after validating intensity ∈ [0,1].
- [ ] **`data-hathor-nes-clear`** ("Clear") — empties the trigger list and result.
- [ ] **`data-hathor-nes-simulate-submit`** ("Simulate emotional state") —
      requires ≥1 trigger and valid traits, then POSTs `{ traits, triggers }`;
      on 200 with a valid `state` renders the affect read-out.
- [ ] **Route Map entries** — verify against
      `STUDIO_HATHOR_NPC_EMOTIONAL_STATE_ROUTE_MAP` (5 entries).
- [ ] **Quick-action links** — NPC Personality System
      (`/studio/hathor/npc-personality-system`), Back to Studio (`/studio`).

## Data & contracts

- **Reads**: `GET /v1/admin/hathor/npc-emotional-state` (catalog: `emotions`,
  `compoundDyads`).
- **Writes**: `POST /v1/admin/hathor/npc-emotional-state/simulate` with
  `{ traits, triggers }`.
- **Realtime**: none.
- **Caching**: client fetch on mount, `cache: 'no-store'`,
  `buildBffAuthHeaders()`, `AbortController` on unmount.
- **Auth**: admin-scoped, fail-closed (401/403 → unauthorized); route is behind
  the signed-in + studio proxy gate.

## Cross-references

- Parent: [`../../studio-overview.md`](../../studio-overview.md)
- Component sources:
  - `apps/oshun/web/src/components/studio/StudioHathorNpcEmotionalStateWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioHathorNpcEmotionalStateRouteMap.ts`
- Siblings:
  [`./studio-hathor-npc-personality-system.md`](./studio-hathor-npc-personality-system.md),
  [`./studio-hathor-npc-memory-system.md`](./studio-hathor-npc-memory-system.md),
  [`./studio-hathor-npc-world-awareness.md`](./studio-hathor-npc-world-awareness.md)

## Open questions / known gaps

- [ ] Hathor is `unconfirmed-v1` per `WALKTHROUGH/matrix/routes.csv`; confirm
      whether the dedicated `/studio/hathor/*` admin lanes ship V1 or are
      internal-only.