Studio Hathor · Lore Compilation for Engines

Purpose#

Admin lane console for the real @hathor/lore-compiler QuestCompiler. The operator compiles a batch of source quests (objectives + NPCs) into engine-ready artifacts, then exports the batch to a selected engine-inspection format (json, yaml, xml, binary, or sqlite). The surfaced result includes compile success, quest count, processed/skipped/error/warning counts, error and warning codes, selected format, and the artifact text when available. Admin-scoped and fail-closed.

Entry points#

• Direct URL / bookmark — /studio/hathor/lore-compilation-for-engines; alternates.canonical is set.
• Quick-action from siblings — e.g. the Hathor Lore Compiler aggregator links here; this page links to the Unified Validation Dashboard.
• Studio overview — see ../../studio-overview.md.

Layout regions#

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

• Workspace (StudioHathorLoreCompilationForEnginesWorkspace, data-hathor-lore-compilation-for-engines-workspace):
  • <h1> WorkspaceHeading — "Hathor Lore Compilation for Engines Workspace"
  • Summary <p data-hathor-lore-compilation-for-engines-summary>
  • Quest Compile Lane: catalog state, then the source-quests JSON form, engine-format select, pending state, result, or inline error.
• Route Map panel (<section data-hathor-lore-compilation-for-engines-route-map>, data-hathor-lce-route-count="5", <h2>Route Map</h2>): 5 entries from STUDIO_HATHOR_LORE_COMPILATION_FOR_ENGINES_ROUTE_MAP, each carrying data-hathor-lce-route-map-entry and data-route-path.
• Quick-action lane (data-hathor-lce-quick-actions, data-hathor-lce-quick-action-count="2"): Unified Validation Dashboard and Back to Studio workspace index. Each link carries data-hathor-lce-quick-action.

States#

• Loading — <p data-hathor-lce-loading role="status" aria-live="polite"> "Loading quest compiler…" while the GET catalog request is in flight.
• Unauthorized — data-hathor-lce-unauthorized role="alert" on 401/403 (admin-scope required).
• Error — data-hathor-lce-error role="alert" on a non-OK catalog response, malformed catalog payload, or network failure.
• Ready (form) — data-hathor-lce-compile-form, data-hathor-lce-form-state="idle", and aria-busy="false" with the source-quests textarea and engine-format select.
• Pending compile — data-hathor-lce-form-state="pending", aria-busy="true", disabled textarea/select/submit, data-hathor-lce-submit-state="pending", and "Compiling…" button copy.
• Result — data-hathor-lce-result role="status" aria-live="polite" with data-hathor-lce-verdict and data-hathor-lce-output when the compiler returns artifact text.
• Validation error — data-hathor-lce-compile-error role="alert" for client JSON validation, empty arrays, BFF 400 reason/detail responses, malformed 200 result payloads, or transport failure.

Interactions#

• data-hathor-lce-quests (textarea, aria-label="quests json") — edit the source-quests JSON array; disabled while compilation is pending.
• data-hathor-lce-format (select) — choose the engine export format from catalog.formats; disabled while compilation is pending.
• data-hathor-lce-compile-submit ("Compile for engine" / "Compiling…") — parses JSON, requires a non-empty array, and POSTs { quests, format }; on 200 with a valid result it renders verdict and output, otherwise it sets data-hathor-lce-compile-error from detail, reason, or the fail-closed fallback.
• Route Map entries — verify against STUDIO_HATHOR_LORE_COMPILATION_FOR_ENGINES_ROUTE_MAP (5 entries), with stable data-route-path ordering.
• Quick-action links — Unified Validation Dashboard (data-hathor-lce-quick-action="unified-validation-dashboard" → /studio/hathor/unified-validation-dashboard), Back to Studio (data-hathor-lce-quick-action="studio-index" → /studio).

Data & contracts#

• Reads: GET /v1/admin/hathor/lore-compilation-for-engines (catalog: formats, defaultFormat).
• Writes: POST /v1/admin/hathor/lore-compilation-for-engines/compile with { quests, format }.
• Realtime: none.
• Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders(), AbortController on unmount.
• Auth: admin-scoped, fail-closed (401/403 → unauthorized state); route is behind the signed-in + studio proxy gate.
• Client parsing: GET catalog requires formats: string[] and defaultFormat: string; POST success requires boolean success, numeric questCount, numeric processedElements, numeric skippedElements, numeric errorCount, errorCodes: string[], numeric warningCount, warningCodes: string[], string format, and output: string | null before rendering a result.

Cross-references#

• Parent: ../../studio-overview.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorLoreCompilationForEnginesWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorLoreCompilationForEnginesRouteMap.ts
• Siblings: ./studio-hathor-lore-compiler.md, ./studio-hathor-unified-validation-dashboard.md

Automated coverage#

• apps/oshun/web/e2e/studio-hathor-lore-compilation-for-engines.spec.ts covers: anonymous redirect, Hathor-admin shell entry, live engine-format catalog, seeded JSON compile result, edited three-quest YAML compile result, edited SQLite export result, browser bearer propagation, scoped axe, 44 px controls, route map, quick actions, client-only malformed JSON and empty-array validation with zero POSTs, BFF invalid_quest reason surfacing, malformed success payload handling, transport failure, catalog loading/503/malformed states, non-admin fail-closed state, pending compile lockout, mobile no-overflow containment, and direct BFF auth/schema gates.
• Focused component tests: StudioHathorLoreCompilationForEnginesWorkspace.test.tsx and StudioHathorLoreCompilationForEnginesWorkspace.integration.test.tsx.
• Focused BFF route test: apps/oshun/bff/src/__tests__/admin-hathor-lore-compilation-for-engines-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.
• SQLite export is exercised in-browser and at the BFF contract layer, but downstream round-trip into a Bellona engine artifact pipeline remains outside this route.
• 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 touch-target assertions pass for this route.