Studio Hathor · Narrative Theory Tooling

Purpose#

Admin lane console for the real @hathor/narrative quest ConditionEvaluator. Given a game-state context and a set of quest/dialogue gating conditions, it evaluates each one (type + operator + value, with optional negate) and combines them with AND or OR to show exactly when a narrative branch unlocks. Admin-scoped and fail-closed.

Entry points#

• Quick-action link from /studio/hathor/game-design-theory-mda (this page links out to game-design-theory-mda)
• Aggregator embed: StudioHathorNarrativeApiWorkspace mounts this workspace inline as its "Narrative Theory Tooling Lane"
• Direct URL / bookmark — yes; alternates.canonical set
• Studio overview — see ../../studio-overview.md

Layout regions#

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

• Workspace <section data-hathor-narrative-theory-tooling-workspace>:
  • <h1> (WorkspaceHeading) "Hathor Narrative Theory Tooling Workspace"
  • Summary <p data-hathor-narrative-theory-tooling-summary>
  • The evaluate form lane: data-hathor-ntt-evaluate-form
• Route Map panel (data-hathor-narrative-theory-tooling-route-map): <h2> "Route Map" + 5 entries from STUDIO_HATHOR_NARRATIVE_THEORY_TOOLING_ROUTE_MAP
• Quick-action lane: two Link.quickAction anchors — Game Design Theory (MDA), Back to Studio workspace index

States#

• Loading — <p data-hathor-ntt-loading>
• Unauthorized — data-hathor-ntt-unauthorized on 401/403 (admin Hathor scope required); fail-closed
• Error — data-hathor-ntt-error on non-OK GET / malformed catalog
• Ready (form) — data-hathor-ntt-evaluate-form once the catalog loads
• Result — data-hathor-ntt-result after a 200 evaluate; data-hathor-ntt-evaluate-error for invalid JSON / non-200

Interactions#

Workspace body (evaluate form lane)#

• Game-state context (JSON) — <textarea data-hathor-ntt-context> (aria-label "context json")
• Conditions (JSON array) — <textarea data-hathor-ntt-conditions> (aria-label "conditions json"); each { type, target, operator, value, value2?, negate?, description? }
• Combine with — <select data-hathor-ntt-logic> (AND / OR)
• Evaluate conditions — <button data-hathor-ntt-evaluate-submit type="submit"> → POST /v1/admin/hathor/narrative-theory-tooling/evaluate
• Result — data-hathor-ntt-verdict plus a data-hathor-ntt-conditions-list of data-hathor-ntt-condition-item rows

Route Map panel#

• 5 route entries — verify match with STUDIO_HATHOR_NARRATIVE_THEORY_TOOLING_ROUTE_MAP

Quick-action lane#

• "Open Hathor Game Design Theory (MDA) workspace" (→ /studio/hathor/game-design-theory-mda)
• "Back to Studio workspace index" (→ /studio)

Data & contracts#

• Reads: GET /v1/admin/hathor/narrative-theory-tooling on mount
• Writes: POST /v1/admin/hathor/narrative-theory-tooling/evaluate
• Realtime: none
• Caching: client fetch on mount, cache: 'no-store'; buildBffAuthHeaders
• Auth/role check: admin-scoped fail-closed (401/403); behind the signed-in
  • studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-hathor-narrative-api.md (aggregator that embeds this workspace), ./studio-hathor-game-design-theory-mda.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorNarrativeTheoryToolingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorNarrativeTheoryToolingRouteMap.ts

Open questions / known gaps#

• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv. Confirm whether the dedicated /studio/hathor/* admin lane consoles ship in V1.
• The lane exposes the quest ConditionEvaluator only; despite the "narrative theory" name, no Aristotelian/MDA framework tooling renders — confirm whether broader theory analysers are planned for this route.
• Route Map advertises frameworks/, arcs/, beats/, and governance/ sub-routes with no page.tsx yet.