Studio Hathor · Workbench Worlds

Purpose#

Admin lane console for the @hathor/domain-models region geography scorers. The analyze lane describes a world region (terrain coverage, danger level + sources, biome, flora/fauna diversity, exploration status) and returns its coverage-weighted travel speed, composite danger (0–10), estimated biodiversity (0–100), exploration level (0–4), and dominant terrain. Admin-scoped and fail-closed.

Entry points#

• Direct URL / bookmark — /studio/hathor/workbench-worlds; alternates.canonical is set.
• Quick-action from siblings — this page links to the Workbench Dashboard lane.
• Studio overview — see ../../studio-overview.md.

Layout regions#

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

• Workspace (StudioHathorWorkbenchWorldsWorkspace, data-hathor-workbench-worlds-workspace):
  • <h1> WorkspaceHeading — "Hathor Workbench Worlds Workspace"
  • Summary <p data-hathor-workbench-worlds-summary>
  • The catalog state (data-hathor-ww-catalog), then the region form (with a reference <details>) + pending submit state + result.
• Route Map panel (<section data-hathor-workbench-worlds-route-map>, data-hathor-ww-route-count="5", <h2>Route Map</h2>): 5 entries from STUDIO_HATHOR_WORKBENCH_WORLDS_ROUTE_MAP (path + purpose).
• Quick-action lane (<section data-hathor-ww-quick-actions>, data-hathor-ww-quick-action-count="2"): Workbench Dashboard (data-hathor-ww-quick-action="workbench-dashboard"), Back to Studio workspace index (data-hathor-ww-quick-action="studio-index").

States#

• Loading — <p data-hathor-ww-loading> "Loading region engine…".
• Unauthorized — data-hathor-ww-unauthorized on 401/403 (admin-scope).
• Error — data-hathor-ww-error on a non-OK catalog response or network failure.
• Ready (form) — data-hathor-ww-form with the region textarea and the reference disclosure (data-hathor-ww-catalog, data-hathor-ww-terrains, data-hathor-ww-biomes).
• Pending submit — data-hathor-ww-submit-state="pending"; submit is disabled with aria-disabled="true" and aria-busy="true" until the BFF response returns.
• Result — data-hathor-ww-result with data-hathor-ww-name, data-hathor-ww-travel, data-hathor-ww-danger, data-hathor-ww-biodiversity, data-hathor-ww-exploration, and data-hathor-ww-dominant.
• Validation error — data-hathor-ww-analyze-error for malformed JSON or a failed POST.

Interactions#

• data-hathor-ww-region (textarea, aria-label="region json") — edit the region JSON.
• data-hathor-ww-submit ("Analyze region") — parses the JSON and POSTs { region }; on 200 with a valid result renders the metrics.
• Route Map entries — verify against STUDIO_HATHOR_WORKBENCH_WORLDS_ROUTE_MAP (5 entries).
• Quick-action links — Workbench Dashboard (/studio/hathor/workbench-dashboard), Back to Studio (/studio).

Data & contracts#

• Reads: GET /v1/admin/hathor/workbench-worlds (catalog: terrainTypes, dangerLevels, biomes, explorationStatuses).
• Writes: POST /v1/admin/hathor/workbench-worlds/analyze with { region }.
• 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/StudioHathorWorkbenchWorldsWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorWorkbenchWorldsRouteMap.ts
• Siblings: ./studio-hathor-workbench-dashboard.md, ./studio-hathor-workbench-world-editor.md, ./studio-hathor-geography-modeling.md

E2E coverage#

• apps/oshun/web/e2e/studio-hathor-workbench-worlds.spec.ts covers the standalone route against the real dev BFF: direct admin navigation, catalog GET with bearer forwarding, seeded temperate-forest analysis, edited volcanic-wasteland analysis, malformed JSON zero-POST rejection, live BFF 400 detail, catalog loading/error state, pending submit lockout, non-admin fail-closed state, route-map and quick-action affordances, 44px checks for the editor, submit control, and quick-action links, anonymous redirect-before-render, and the shared axe gate.

Open questions / known gaps#

• The analyzer scores a single region; confirm whether multi-region or whole-world aggregation belongs here or in a separate workbench surface.
• Hathor is confirmed in V1 per WALKTHROUGH/matrix/routes.csv and WALKTHROUGH/matrix/coverage.md (product-owner confirmation recorded 2026-05-29 for Bellona / Hathor / Neith).
• Manual screen-reader pass remains for the live browser surface; automated axe and touch-target coverage now pass for the standalone route.