Studio Hathor · Game Design Theory (MDA)

Purpose#

Admin lane console for the @hathor/theory MDA framework reference. The lookup lane resolves one of Hunicke's eight aesthetics to its definition and examples, and a canonical mechanic template to its category and a structural summary (rule / input / output / constraint counts). Admin-scoped and fail-closed.

Entry points#

• Direct URL / bookmark — /studio/hathor/game-design-theory-mda; alternates.canonical is set.
• Quick-action from siblings — this page links to Screenplay Compilation; the Hathor Theory aggregator embeds this same lane.
• Studio overview — see ../../studio-overview.md.

Layout regions#

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

• Workspace (StudioHathorGameDesignTheoryMdaWorkspace, data-hathor-game-design-theory-mda-workspace):
  • <h1> WorkspaceHeading — "Hathor Game Design Theory (MDA) Workspace"
  • Summary <p data-hathor-game-design-theory-mda-summary>
  • The catalog state, data-hathor-mda-catalog readiness summary, lookup form with pending state, and result/error region.
• Route Map panel (<section data-hathor-game-design-theory-mda-route-map>, <h2>Route Map</h2>): data-hathor-mda-route-count="5" plus 5 data-hathor-mda-route-map-entry / data-route-path entries from STUDIO_HATHOR_GAME_DESIGN_THEORY_MDA_ROUTE_MAP (path + purpose).
• Quick-action lane (data-hathor-mda-quick-actions, data-hathor-mda-quick-action-count="2"): Screenplay Compilation (data-hathor-mda-quick-action="screenplay-compilation"), Back to Studio workspace index (data-hathor-mda-quick-action="studio-index").

States#

• Loading — <p data-hathor-mda-loading role="status"> "Loading MDA reference…"; the form is absent until catalog resolution.
• Unauthorized — data-hathor-mda-unauthorized role="alert" on 401/403 (admin-scope); the form/result are absent.
• Error — data-hathor-mda-error role="alert" on a non-OK catalog response, malformed catalog, or network failure.
• Ready (form) — data-hathor-mda-catalog reports "8 aesthetics · 10 mechanic templates · 14 categories"; data-hathor-mda-lookup-form carries data-hathor-mda-lookup-state="idle" and aria-busy="false".
• Pending lookup — form state flips to pending, selects are disabled, and data-hathor-mda-lookup-submit becomes disabled with aria-busy="true" and "Looking up…".
• Result — data-hathor-mda-result role="status" with data-hathor-mda-aesthetic-result and/or data-hathor-mda-mechanic-result depending on the selection.
• Lookup error — data-hathor-mda-lookup-error role="alert" when neither field is chosen, the BFF returns a detail reason, or the lookup transport fails.

Interactions#

• data-hathor-mda-aesthetic (select from catalog.aesthetics) — choose an aesthetic (or none).
• data-hathor-mda-mechanic (select from catalog.mechanicTemplateNames) — choose a mechanic template (or none).
• data-hathor-mda-lookup-submit ("Look up") — requires at least one field, then POSTs { aesthetic?, mechanicTemplate? }; on 200 with a valid result renders the definition(s)/structural summary.
• Route Map entries — verified against STUDIO_HATHOR_GAME_DESIGN_THEORY_MDA_ROUTE_MAP (5 entries).
• Quick-action links — Screenplay Compilation (/studio/hathor/screenplay-compilation), Back to Studio (/studio).
• Mobile controls — aesthetic select, mechanic select, lookup submit, and both quick actions are verified at >=44 px without horizontal overflow.

Data & contracts#

• Reads: GET /v1/admin/hathor/game-design-theory-mda (catalog: aesthetics, mechanicTemplateNames, mechanicCategories).
• Writes: POST /v1/admin/hathor/game-design-theory-mda/lookup with the chosen aesthetic and/or mechanic template.
• 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.
• Client validation/parsing: catalog parsing requires aesthetics, mechanicTemplateNames, and mechanicCategories; lookup parsing requires structurally valid aesthetic/mechanic result objects before rendering.

Cross-references#

• Parent: ../../studio-overview.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorGameDesignTheoryMdaWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorGameDesignTheoryMdaRouteMap.ts
• Siblings: ./studio-hathor-theory.md (aggregator that embeds this lane), ./studio-hathor-narrative-theory-tooling.md, ./studio-hathor-screenplay-compilation.md

Automated coverage#

• apps/oshun/web/e2e/studio-hathor-game-design-theory-mda.spec.ts covers: anonymous redirect, Hathor-admin shell entry, live catalog load, exact @hathor/theory output for Challenge + Resource Collection, aesthetic-only and mechanic-only POST bodies, browser bearer propagation, scoped axe, 44 px controls, route map, quick actions, client-only empty selection, BFF invalid_mechanic_template surfacing, transport failure, catalog loading/503/ malformed states, non-admin fail-closed state, pending lookup lockout, mobile no-overflow containment, and direct BFF auth/schema gates.
• Focused component tests: StudioHathorGameDesignTheoryMdaWorkspace.test.tsx, StudioHathorGameDesignTheoryMdaWorkspace.integration.test.tsx, StudioHathorGameDesignTheoryMdaPage.test.tsx, and StudioHathorGameDesignTheoryMdaRouteMap.test.ts.
• Focused BFF route test: apps/oshun/bff/src/__tests__/admin-hathor-game-design-theory-mda-route.test.ts.

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. Confirmed in V1 via V1/TODOS.md §34 and the 2026-05-29 surface inventory.
• The route-map sub-routes are listed but their concrete page.tsx files are not present; confirm whether they remain route-map placeholders or need dedicated deep-link pages.
• Manual assistive-technology pass remains pending; automated scoped axe and keyboard/touch-target assertions pass for this route.