Studio Hathor · Timeline Modeling

Purpose#

Admin lane console for the real @hathor/timeline scene-order validator. Submit a timeline packet and check its story-vs-shoot ordering integrity — causal-event coverage, required scenes, and required world-state tags. Admin-scoped and fail-closed.

Entry points#

• Quick-action links to location-modeling and quest-authoring (both this page's quick actions)
• 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-timeline-modeling-workspace>:
  • <h1> (WorkspaceHeading) "Hathor Timeline Modeling Workspace"
  • Summary <p data-hathor-timeline-modeling-summary>
  • Scene Order Validation Lane (<h2 data-tl-lane-heading>) — the validate form data-tl-form
• Route Map panel (data-hathor-timeline-modeling-route-map): <h2> "Route Map" + 5 entries from STUDIO_HATHOR_TIMELINE_MODELING_ROUTE_MAP
• Quick-action lane: three Link.quickAction anchors — Location Modeling, Quest Authoring, Back to Studio workspace index

States#

• Loading — <p data-tl-loading>
• Unauthorized — data-tl-unauthorized on 401/403 (admin Hathor scope required); fail-closed
• Error — data-tl-error on non-OK GET / malformed catalog
• Ready (form) — data-tl-form once the issue-types catalog loads
• Result — data-tl-result after a 200 validate, with a data-tl-issues list of data-tl-issue-row rows; data-tl-validate-error for invalid JSON / non-200

Interactions#

Scene Order Validation Lane#

• Timeline packet (JSON) — <textarea data-tl-payload> (aria-label "timeline packet json"); accepts { packet:{ packetId, worldId, timelineName, scenes[{ sceneId, eventId, storyOrder, storyYear, causeEventIds[], worldState[] }], requiredSceneIds[], requiredWorldStateTags[], cgiExport } }
• Issue-types reference — data-tl-issue-types
• Validate timeline — <button data-tl-submit type="submit"> → POST /v1/admin/hathor/workbench-timeline/validate
• Result — data-tl-headline plus the issue list (data-tl-issues → data-tl-issue-row)

Route Map panel#

• 5 route entries — verify match with STUDIO_HATHOR_TIMELINE_MODELING_ROUTE_MAP

Quick-action lane#

• "Open Hathor Location Modeling workspace" (→ /studio/hathor/location-modeling)
• "Open Hathor Quest Authoring workspace" (→ /studio/hathor/quest-authoring)
• "Back to Studio workspace index" (→ /studio)

Data & contracts#

• Reads: GET /v1/admin/hathor/workbench-timeline (note: the timeline lane reuses the workbench-timeline endpoint, not a timeline-modeling slug) on mount
• Writes: POST /v1/admin/hathor/workbench-timeline/validate
• 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-workbench-timeline.md (same workbench-timeline validator endpoint), ./studio-hathor-quest-authoring.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorTimelineModelingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorTimelineModelingRouteMap.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.
• This route and workbench-timeline both wire the same workbench-timeline validator endpoint; confirm whether the two routes are intentionally distinct surfaces or duplicates that should converge.
• Route Map advertises timelines/, nested events/ and branches/, and governance/ sub-routes with no page.tsx yet.