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.

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
• 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-memory-system.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.