---
path: /studio/hathor/workbench-world-editor
surface: studio
domain: hathor
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/hathor/workbench-world-editor/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-06-25 Playwright real-dev-infra route journey — admin-scoped catalog,
  seeded missing-location verdict, clean export-ready verdict, BFF schema
  validation detail, client-side malformed JSON rejection with no POST, native
  pending submit disablement, non-admin fail-closed state, route-map /
  quick-action affordances, mobile 44px controls, and shared axe gate. Evidence:
  apps/oshun/web/e2e/studio-hathor-workbench-world-editor.spec.ts'
---

# Studio Hathor · Workbench World Editor

## Purpose

Admin lane console that validates a CGI world-scene definition before export.
The lane loads the Hathor issue catalog, lets an operator edit a JSON scene
definition, and returns the real `@hathor/world` readiness verdict: clean
export, blocking issue counts, per-issue detail, or validation errors from the
BFF schema guard.

## Entry points

- **Quick-action link from `/studio/hathor/workbench-worlds`** (verify against
  that page's source)
- **Direct URL / bookmark** — yes; `alternates.canonical` set to
  `/studio/hathor/workbench-world-editor`
- **Studio overview** — see
  [`../../studio-overview.md`](../../studio-overview.md)

## Layout regions

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

- **Workspace** `<StudioHathorWorkbenchWorldEditorWorkspace />`
  (`data-hathor-workbench-world-editor-workspace`):
  - `WorkspaceHeading` `<h1>` — "Hathor Workbench World Editor Workspace"
  - Summary `<p data-hathor-workbench-world-editor-summary>`
  - Catalog strip (`data-hathor-wwe-catalog`) — issue-check count, per-issue
    chips (`data-hathor-wwe-issue-type=<type>`), coordinate origins and up-axis
    enums (`data-hathor-wwe-coordinate-enums`)
  - The scene-validation form lane (loading / unauthorized / error / form /
    pending / result)
- **Route Map panel** `data-hathor-workbench-world-editor-route-map` — `<h2>`
  "Route Map" listing the 5 `STUDIO_HATHOR_WORKBENCH_WORLD_EDITOR_ROUTE_MAP`
  entries (catalog / biomes / revisions / governance child paths)
- **Quick-action lane** — two `Link.quickAction` anchors: Workbench Worlds, Back
  to Studio workspace index

## States

- [x] **Loading** — `data-hathor-wwe-loading` while the GET catalog request is
      in flight
- [x] **Unauthorized (admin-scope 401/403)** — `data-hathor-wwe-unauthorized`
      from real BFF non-admin scope forwarding
- [x] **Error** — `data-hathor-wwe-error`
- [x] **Ready (catalog + form)** — catalog chips, scene-definition textarea, and
      submit
- [x] **Pending submit** — `data-hathor-wwe-submit-state="pending"`, native
      `disabled` submit, text "Validating…" until the BFF response resolves
- [x] **Blocked result** — default seeded scene requires absent location `l9`;
      BFF returns `blocked`, `1 blocking`, and issue `l9:missing-location`
- [x] **Clean result** — edited complete scene returns `ready to export`,
      `0 blocking`, and `data-hathor-wwe-clean`
- [x] **Result structure** — `data-hathor-wwe-result` with
      `data-hathor-wwe-valid` / `data-hathor-wwe-counts` and
      `data-hathor-wwe-issues` (per-issue `data-hathor-wwe-issue-item`) or
      `data-hathor-wwe-clean`
- [x] **BFF validation error** — invalid definition schema surfaces BFF detail,
      e.g. `definition.worldId is required`
- [x] **Client validation error** — malformed JSON renders
      `data-hathor-wwe-validate-error` and does not issue a validate POST

## Interactions

### Scene validation lane

- [x] **CGI scene definition (JSON)** — scene textarea
      (`data-hathor-wwe-definition`), seeded with `requiredLocationIds`
      containing `l1` and absent required location `l9`
- [x] **Submit** — `<button data-hathor-wwe-validate-submit>` "Validate world
      scene" → POST `VALIDATE_ENDPOINT`; mobile target is at least 44px high

### Route Map panel

- [x] **Route entries** — verify match with
      `STUDIO_HATHOR_WORKBENCH_WORLD_EDITOR_ROUTE_MAP` (5 entries)

### Quick-action lane

- [x] **"Open Hathor Workbench Worlds workspace"** →
      `/studio/hathor/workbench-worlds`; mobile target is at least 44px
- [x] **"Back to Studio workspace index"** → `/studio`; mobile target is at
      least 44px

## Data & contracts

- **Reads**: `GET /v1/admin/hathor/workbench-world-editor` (`WWE_ENDPOINT`) —
  the scene-validation catalog: `issueTypes`, `coordinateOrigins`, and `upAxes`
- **Writes**: `POST /v1/admin/hathor/workbench-world-editor/validate`
  (`VALIDATE_ENDPOINT`) with `{ definition }`
- **Realtime**: none
- **Caching**: client `fetch` on mount, `cache: 'no-store'`,
  `buildBffAuthHeaders()`
- **Auth/role check**: admin-scoped, fail-closed on 401/403; route additionally
  gated signed-in + studio by the BFF proxy

## Cross-references

- Parent: [`../../studio-overview.md`](../../studio-overview.md)
- Shell:
  [`../../../shell/04-auth-session.md`](../../../shell/04-auth-session.md)
- Sibling routes:
  [`./studio-hathor-workbench-worlds.md`](./studio-hathor-workbench-worlds.md),
  [`./studio-hathor-workbench-world-editor.md`](./studio-hathor-workbench-world-editor.md)
- Component sources:
  - `apps/oshun/web/src/components/studio/StudioHathorWorkbenchWorldEditorWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioHathorWorkbenchWorldEditorRouteMap.ts`
- Automated coverage:
  - `apps/oshun/web/e2e/studio-hathor-workbench-world-editor.spec.ts`
  - `apps/oshun/web/src/components/__tests__/StudioHathorWorkbenchWorldEditorWorkspace.test.tsx`
  - `apps/oshun/web/src/components/__tests__/StudioHathorWorkbenchWorldEditorWorkspace.integration.test.tsx`
  - `apps/oshun/bff/src/__tests__/admin-hathor-workbench-world-editor-route.test.ts`

## Open questions / known gaps

- [ ] Add an operator-facing schema/reference link beside the JSON editor; the
      BFF schema detail is now surfaced, but the lane still relies on seeded
      JSON as the primary example.