Studio Hathor · Cinematography Planning

Purpose#

Panel-cluster aggregator and admin reference-planning console for drone-and-virtual-production cinematography. The workspace renders StudioHathorCinematographyReferencePlanner, which calls the real /v1/admin/hathor/cinematography-planning BFF route backed by @hathor/theory, plus ~243 specialist StudioHathor*Panel sub-components covering drone fleet choreography, photogrammetry / Gaussian-splatting / NeRF / LiDAR capture, ICVFX LED-wall simulation, performer / facial / hand capture, virtual-set library, editorial color / VFX, and director comms. A renderMode prop (full | inventory) switches between the full panel cluster and a selector-only inventory; the page renders the default full. It does NOT embed StudioHathorEconomyModelingWorkspace.

Entry points#

• Quick-action link from /studio/hathor/chronicle-parser — "Open Hathor Cinematography Planning workspace" (verify against that page's source)
• Direct URL / bookmark — yes; alternates.canonical set to /studio/hathor/cinematography-planning
• Studio overview — see ../../studio-overview.md

Layout regions#

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

• Workspace <StudioHathorCinematographyPlanningWorkspace /> (default renderMode="full"):
  • WorkspaceHeading <h1> — "Hathor Cinematography Planning Workspace"
  • A long <p data-hathor-cinematography-planning-summary> enumerating the desks (drone shot library, choreography, fleet, role assignment, handoff, battery, timecode, formation, launch/recovery, fleet health, emergency, comms mesh, autonomous framing, shot-type classifier, photogrammetry, NeRF / Gaussian-splat / LiDAR capture, virtual-set library, ICVFX, mocap, facial / hand capture, director comms, editorial color / VFX, and flight-path design)
  • <StudioHathorCinematographyReferencePlanner /> — data-hathor-cinematography-reference-planner; catalog-gated data-hathor-crp-form, visible catalog summary data-hathor-crp-catalog, emotion/mood text inputs, optional camera-angle/color-scheme selects, and data-hathor-crp-submit
  • In renderMode='full': the ~243 individual StudioHathor*Panel children (StudioHathorDroneShotLibraryPanel … StudioHathorDroneFlightPathDesignerPanel)
  • In renderMode='inventory': <StudioHathorCinematographyPlanningPanelInventory /> — a selector-only inventory in place of the panel cluster
• Route Map panel (data-hathor-cinematography-planning-route-map, data-hathor-cp-route-count="247") — <h2> "Route Map" listing the entries from STUDIO_HATHOR_CINEMATOGRAPHY_PLANNING_ROUTE_MAP; each entry is tagged with data-hathor-cinematography-planning-route-map-entry and data-route-path
• Quick-action lane (data-hathor-cinematography-planning-quick-actions, data-hathor-cp-quick-action-count="2") — Narrative Theory Tooling (data-hathor-cinematography-planning-quick-action="narrative-theory-tooling") and Back to Studio workspace index (data-hathor-cinematography-planning-quick-action="studio-index")

States#

• Loading — <p data-hathor-crp-loading> "Loading cinematography reference engine…" while the reference catalog GET is in flight
• Unauthorized — data-hathor-crp-unauthorized "Access restricted." on 401/403 (admin Hathor scope required); fail-closed
• Error — data-hathor-crp-error on non-OK GET or malformed catalog
• Ready (form) — data-hathor-crp-form after the camera-angle and color-scheme catalog loads, with data-hathor-crp-catalog
• Pending submit — data-hathor-crp-plan-state="pending" and data-hathor-crp-submit-state="pending"; emotion, mood, angle, scheme, and submit controls are disabled with aria-busy="true" until the BFF response returns
• Result — data-hathor-crp-result after a 200 plan; validation, non-200, and transport failures surface through data-hathor-crp-plan-error
• Populated (full mode, route default) — ReferencePlanner + every drone / cinematography / director / virtual-set panel renders
• Populated (inventory mode) — only the StudioHathorCinematographyPlanningPanelInventory selector renders (no panel cluster). The page renders full; this is the alternate renderMode
• Error (unrecoverable) — bubbles to nearest error.tsx
• Empty — N/A; hard-coded panel set
• Gated — N/A at this route; entitlement at the proxy/middleware level

Interactions#

Workspace body#

• Heading + summary (non-interactive <h1> + summary <p>)
• Emotion — <input data-hathor-crp-emotion> seeded with heroic power
• Mood — <input data-hathor-crp-mood> seeded with dark dramatic
• Camera angle — <select data-hathor-crp-angle> from catalog camera angles; optional low_angle resolves the reference card
• Color scheme — <select data-hathor-crp-scheme> from catalog color schemes; optional warm resolves the reference card
• Plan cinematography — <button data-hathor-crp-submit type="submit"> → POST /v1/admin/hathor/cinematography-planning/plan with { emotion, mood, cameraAngle?, colorScheme? }
• Result fields — data-hathor-crp-shots, data-hathor-crp-angles, data-hathor-crp-lighting, optional data-hathor-crp-angle-effect, and optional data-hathor-crp-scheme-effect
• Representative cinematography / drone / director / virtual-set panels — the full-mode Playwright pass asserts representative panel selectors from shot planning, fleet choreography, virtual sets, director comms, and VFX. Each specialist panel remains eligible for its own narrower walkthrough as sub-routes materialize.

Route Map panel#

• Route entries (non-interactive <article> listing) — verify match with STUDIO_HATHOR_CINEMATOGRAPHY_PLANNING_ROUTE_MAP (247 entries)

Quick-action lane#

• "Open Hathor Narrative Theory Tooling workspace" → /studio/hathor/narrative-theory-tooling
• "Back to Studio workspace index" → /studio

Data & contracts#

• Reads: GET /v1/admin/hathor/cinematography-planning (camera-angle and color-scheme catalog) on planner mount
• Writes: POST /v1/admin/hathor/cinematography-planning/plan
• Realtime: none at the workspace level (verify any per-panel feeds inside individual panels)
• Caching: client fetch on mount and submit, cache: 'no-store'; buildBffAuthHeaders
• Auth/role check: reference planner is admin-scoped fail-closed (401/403); route is behind the signed-in + studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-hathor-chronicle-parser.md, ./studio-hathor-narrative-theory-tooling.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorCinematographyPlanningWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorCinematographyPlanningRouteMap.ts
  • apps/oshun/web/src/components/studio/StudioHathorCinematographyReferencePlanner.tsx
  • ~243 individual StudioHathorDrone*Panel.tsx, StudioHathorDirector*Panel.tsx, and StudioHathor*SystemPanel.tsx components

E2E coverage#

• apps/oshun/web/e2e/studio-hathor-cinematography-planning.spec.ts covers the standalone route against the real dev BFF: anonymous redirect, admin direct navigation, catalog GET with browser bearer forwarding, exact @hathor/theory shot recommendations / lighting styles / Low Angle / Warm reference-card output, client-only empty emotion/mood rejection, BFF detail surfacing, plan transport failure, catalog loading/503/malformed states, non-admin fail-closed state, pending submit lockout, 247-entry route-map equality, quick-action affordances, representative panel cluster presence, 44 px checks for controls and quick-action links, mobile no-overflow, direct BFF 401/403/400/200 contract gates, neutral fallback planning, and the shared axe gate.

Open questions / known gaps#

• 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).
• Unlike the older sweep note, this workspace does NOT embed StudioHathorEconomyModelingWorkspace; it is a pure panel cluster. Confirm whether an operator-governance surface belongs here.
• The workspace mounts ~243 panel components in full mode. Confirm whether all render at V1 or whether some are scaffolding for future capture/VP pipelines.
• renderMode='inventory' is not exercised from page.tsx. Confirm whether it is a runtime debug toggle, a route variant, or unused scaffolding.
• Per-panel walkthrough files remain for the specialist controls; track under cinematography-planning sub-routes as they materialize.
• Manual screen-reader pass remains for the live browser surface; automated axe and touch-target coverage now pass for the standalone route.