Studio overview

Purpose#

The Studio root. Information architecture for OSHUN Studio editorial, asset, taxonomy, generation, governance, and operations flows. Acts as a landing/index for the 50+ studio sub-areas. See V1/features.md ("Oshun Studio" surface).

Entry points#

• Domain card on / — if studio entitled
• Profile menu → Studio — discoverable
• Direct URL / bookmark — yes (entitlement required for sub-routes)
• Operator dashboard link — when an operator switches to author mode
• /lilith-studio cross-link from page body
• Public: /studio/compose and /studio/generation/living-scene are explicitly public (see middleware), Studio root is not

Layout regions#

page.tsx mounts ShellLayout active="studio" (verified in source: the root studio page passes active="studio"), then:

• Header: shell header with the Studio nav state active (active="studio")
• Hero / above-the-fold: StudioInformationArchitectureWorkspace — WorkspaceHeading renders the page <h1> "Studio Information Architecture", followed by the live IA Validation Lane (<h2 data-ia-lane-heading>) that GET/POSTs /v1/admin/studio/ia-tree (analyze via POST /v1/admin/studio/ia-tree/analyze) and renders the issue-code catalog, JSON payload editor, pending/error states, retry control, and result table
• Section 1: Oshun Studio V3 authoring — <section className="panel" data-lilith-studio-v3-entry>
  • Heading <h2>Oshun Studio V3 authoring</h2> (the page <h1> is the workspace heading above; the <title> metadata is "Studio · IA")
  • Paragraph framing V3 authoring next to V1 editorial workflow
  • data-studio-v3-quick-actions data-studio-v3-quick-action-count="5" wraps five Link className="quickAction" links, in source order:
    • "Open Lilith Studio authoring shell" → /lilith-studio
    • "Open Mawu Studio accessibility linter" → /mawu-studio/accessibility (added 2026-06-02)
    • "Open Mawu Studio localization" → /mawu-studio/localization (added 2026-06-02)
    • "Open Tara TTS Voice Consent workspace" → /studio/tara/tts-voice-consent
    • "Open Tara TTS Contract Template" → /studio/tara/tts-voice-contract
• Section 2: workspace catalog — a single unlabeled <section className="panel" data-studio-catalog-entry> labeled by <h2 data-studio-catalog-heading>Studio workspace catalog</h2> and containing one flat quickAction link list (data-studio-catalog-quick-actions, ~466 links) covering every studio sub-area in a single column (no nested per-domain headings/sections in the DOM). The link families, in source order, are: design system + platform workspaces (/studio/design-language, /studio/typography, /studio/color-system, /studio/spacing-layout, … through /studio/launch-readiness-governance), then domain-bridge studios — Bellona (/studio/bellona/*), Hathor (/studio/hathor/*), Yemaya (/studio/yemaya/*), Aja (/studio/aja/*), Isis (/studio/isis/*, plus one /studio/neith/inverse-modeling) — and finally "Open Concordia Workbench" → /studio/concordia-workbench and a "Back to Explore" link to WEB_SHELL_ROUTE_PATHS.explore. (Governance/operations workspaces such as /studio/accessibility-governance and /studio/audit-compliance-surfaces live inline in this same flat list — they are not broken out into a separate DOM section.)

States#

• Anonymous direct URL — /studio redirects away to welcome/login before the Studio root renders.
• Signed-in, non-admin user — the Studio root renders, the IA lane shows data-ia-unauthorized with the BFF reason "Studio admin scope required", and the form/result are absent. The V3 quick-action group and catalog remain visible as links.
• Signed-in studio admin — the page renders inside the admin shell (data-shell-kind="admin") with the Admin Studio Home nav active by route, the IA catalog loads from the live BFF (4 IA issue codes), V3 quick actions render with five stable selectors, and the root catalog exposes hundreds of internal workspace anchors.
• Loading — while the IA catalog GET is held, data-ia-loading displays "Loading IA validator…" and the form is absent.
• IA catalog failure — non-OK catalog responses render data-ia-error, keep the form/result absent, and expose button[data-ia-retry].
• IA retry — clicking data-ia-retry returns to the live BFF catalog and restores the form.
• IA transport failure — analyze transport aborts fail closed with "Could not reach the IA validator." and no stale result.
• Malformed IA response — a malformed 200 analyze response fails closed with "IA analysis response was malformed." and no result.
• Pending analyze — submit changes data-ia-form-state / data-ia-submit-state to analyzing, sets aria-busy="true", disables the button, and restores idle after the response.
• Mobile viewport — 390px mobile viewport has no horizontal overflow; the IA editor, submit button, V3 quick actions, and sentinel catalog links meet the 44×44 px touch target.
• Standalone PWA / offline cached Studio root — not asserted in this pass. The IA lane's network-failure branch is covered, but service-worker offline cache semantics for the Studio root remain a separate PWA coverage item.

Interactions#

StudioInformationArchitectureWorkspace#

This component is a live validator for proposed IA tree JSON, not a persisted IA editor.

• Diagnostics panel — data-ia-enums shows the live issue-code catalog, data-ia-result renders the summary, and data-ia-node-row rows expose node id, depth, child count, and issue codes.
• Default payload analysis — clicking data-ia-submit sends the seeded invalid tree to /v1/admin/studio/ia-tree/analyze; the real BFF reports 9 nodes, 5 violations, and rows for breadth_exceeded, depth_exceeded, duplicate sibling slugs, and orphaned nodes.
• Edited clean payload — replacing the JSON with a clean three-node tree returns IA valid, 0 violations, and three valid rows from the live BFF.
• Client JSON validation — malformed JSON displays "Payload must be valid JSON." without sending a POST.
• BFF schema validation — invalid structured JSON sends one POST and surfaces the BFF 400 detail text.
• Retry control — catalog errors expose data-ia-retry; retry restores the live catalog/form.
• Keyboard / SR / a11y — submit is keyboard-focusable, errors use role="alert", results use role="status", and the new spec runs through the shared Playwright auto-axe fixture.

V3 Lilith Studio quick-action group#

data-lilith-studio-v3-entry

• "Open Lilith Studio authoring shell" (link)
  • Function: navigates to /lilith-studio
  • SR: "Open Lilith Studio authoring shell"
  • Telemetry: plain next/link navigation — no click telemetry is wired on these quick-action links in page.tsx
• "Open Mawu Studio accessibility linter" (link) → /mawu-studio/accessibility (the V7 accessibility workspace; out-of-v1 — see future/mawu-studio-accessibility.md)
• "Open Mawu Studio localization" (link) → /mawu-studio/localization (the V7 localization workspace; out-of-v1 — see future/mawu-studio-localization.md)
• "Open Tara TTS Voice Consent workspace" (link) → /studio/tara/tts-voice-consent
• "Open Tara TTS Contract Template" (link) → /studio/tara/tts-voice-contract

Design system workspaces#

• Each root catalog anchor has a real internal target — Playwright collects all data-studio-catalog-quick-actions a.quickAction anchors, asserts 450+ entries, non-empty "Open…" / "Back to…" text, internal /studio or /explore hrefs, and no hash-only targets.
• Sentinel catalog links — exact hrefs are asserted for Design Language, Observability and Operational Dashboards, Bellona Format Registry, Concordia Workbench, and Back to Explore.
• Keyboard — V3 quick actions and data-ia-submit are focusable; the catalog uses native anchors for Enter activation.
• Mobile — links wrap without horizontal overflow; sentinel links and V3 quick actions meet ≥44×44 px.

Cross-section navigation#

• Section labels — the catalog section is labeled by data-studio-catalog-heading; no in-page section anchors are present.
• Breadcrumb — no page-local breadcrumb is rendered in page.tsx; shell navigation exposes the active Studio domain instead.

Data & contracts#

• Reads: studio IA aggregate (via StudioInformationArchitectureWorkspace)
• Writes: no persisted IA edits on the root page; the only browser POST is the stateless analyze request to /v1/admin/studio/ia-tree/analyze
• Realtime: no presence/collaboration overlay is mounted on the root page
• Caching: server-rendered shell plus client-side IA GET/POST with cache: 'no-store'
• Auth/role check: anonymous users are redirected from /studio; signed-in users can render the root; the IA BFF endpoints require admin:* or admin:studio; per-sub-route entitlements remain under middleware/domain boundary policy
• Direct BFF contract: Playwright request coverage asserts missing auth 401, non-admin 403, admin issue catalog, valid clean analysis, seeded violation analysis, invalid-payload 400, and non-admin analyze 403.

Cross-references#

• Shell: shell/01-app-shell.md, shell/04-auth-session.md
• Studio sub-areas: see folder index
  • authoring/, generation/, governance/, operations/, design/, collaboration/, domain-bridges/
• Cross-links from page body:
  • /lilith-studio
• Feature spec: V1/features.md
• Architecture: V1/ARCHITECTURE.md

Open questions / known gaps#

• Studio root passes active="studio" to ShellLayout; real-infra Playwright asserts the admin-shell route chrome for an admin-scoped session. The page <h1> is "Studio Information Architecture" from StudioInformationArchitectureWorkspace (WorkspaceHeading), with the V3 <h2> and labeled quick-action catalog below it.
• Map every Studio sub-area to a domain owner (Sophia / Isis / Lilith / Iris / domain-bridges) and place each file in the right sub-folder
• Confirm middleware policy for /studio root vs. each sub-route
• Product boundary: root-page IA bulk recovery controls, persisted IA edits, optimistic updates, and audit trail links are not present in StudioInformationArchitectureWorkspace; document those flows only when a real editor/endpoint exists.
• Standalone PWA + service-worker offline cache behavior for /studio remains separate from the covered IA network-failure branch.
• Add per-sub-area walkthrough files (~326 routes)

E2E evidence#

• apps/oshun/web/e2e/studio-overview.spec.ts covers the Studio root against the real Next shell + BFF, with deterministic mocks only for explicit fail-closed branches that are impractical to trigger live.
• Direct BFF request coverage in the same spec proves /v1/admin/studio/ia-tree auth and schema gates independent of the browser shell.
• The shared ./fixtures Playwright wrapper runs auto-axe for DOM tests; the spec also asserts mobile overflow and touch targets.