--- path: /studio/hathor/game-design-theory-mda surface: studio domain: hathor auth: signed-in + studio entitlement source: apps/oshun/web/src/app/studio/hathor/game-design-theory-mda/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)' - '2026-07-03 focused real-dev-infra walk — apps/oshun/web/e2e/studio-hathor-game-design-theory-mda.spec.ts drove the live Next Studio shell and real local BFF for anonymous redirect, Hathor-admin catalog load, browser bearer propagation, exact Hunicke aesthetic and mechanic-template lookup output, aesthetic-only and mechanic-only lookups, client/BFF/transport failures, loading/503/malformed catalog states, non-admin fail-closed state, pending lockout, route map, quick actions, mobile 44px controls, scoped axe, and direct BFF auth/schema gates. Evidence: WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md §271.' --- # 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`](../../studio-overview.md). ## Layout regions `page.tsx` renders inside ``: - **Workspace** (`StudioHathorGameDesignTheoryMdaWorkspace`, `data-hathor-game-design-theory-mda-workspace`): - `

` `WorkspaceHeading` — "Hathor Game Design Theory (MDA) Workspace" - Summary `

` - The catalog state, `data-hathor-mda-catalog` readiness summary, lookup form with pending state, and result/error region. - **Route Map panel** (`

`, `

Route Map

`): `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 - [x] **Loading** — `

` "Loading MDA reference…"; the form is absent until catalog resolution. - [x] **Unauthorized** — `data-hathor-mda-unauthorized role="alert"` on 401/403 (admin-scope); the form/result are absent. - [x] **Error** — `data-hathor-mda-error role="alert"` on a non-OK catalog response, malformed catalog, or network failure. - [x] **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"`. - [x] **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…". - [x] **Result** — `data-hathor-mda-result role="status"` with `data-hathor-mda-aesthetic-result` and/or `data-hathor-mda-mechanic-result` depending on the selection. - [x] **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 - [x] **`data-hathor-mda-aesthetic`** (select from `catalog.aesthetics`) — choose an aesthetic (or none). - [x] **`data-hathor-mda-mechanic`** (select from `catalog.mechanicTemplateNames`) — choose a mechanic template (or none). - [x] **`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. - [x] **Route Map entries** — verified against `STUDIO_HATHOR_GAME_DESIGN_THEORY_MDA_ROUTE_MAP` (5 entries). - [x] **Quick-action links** — Screenplay Compilation (`/studio/hathor/screenplay-compilation`), Back to Studio (`/studio`). - [x] **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`](../../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`](./studio-hathor-theory.md) (aggregator that embeds this lane), [`./studio-hathor-narrative-theory-tooling.md`](./studio-hathor-narrative-theory-tooling.md), [`./studio-hathor-screenplay-compilation.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 - [x] 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.