Shot plan — unified UI sketch (scaffold + direction)

Status: Deferred — keep Steps 9 and 10 separate (no in-step tabs). Step 10 display title is Shot direction only.
Goal: One place to work on shots without merging backend steps, locks, or APIs. (Not pursued.)

Problem

Steps 9 (Shot scaffold) and 10 (Shot direction) edit the same shot list but live on separate nav items. Users bounce between /project-plan/scaffold and /project-plan/prompts for one creative unit (“this cut”).

Backend separation stays valuable (structure vs brief, different regen scope, scaffold lock before brief batch). The fix is navigation + row UX, not one DB step.

Proposal: one nav item, two sub-modes, one row component

Sidebar (user-visible)

Internal PlannerStepKey values can stay step_scaffold / step_prompts for migrations; only display and routing change in phase 1.

URL

Primary route (canonical):

/project-plan/shot-plan
/project-plan/shot-plan?tab=structure   # default
/project-plan/shot-plan?tab=brief

Redirects (permanent or soft):

• /project-plan/scaffold → shot-plan?tab=structure
• /project-plan/prompts → shot-plan?tab=brief

Optional deep link per shot (phase 2):

/project-plan/shot-plan/shot/s01?tab=brief

Page layout (wireframe)

┌─────────────────────────────────────────────────────────────────────────┐
│ Shot plan                                                    [How it works] │
│ Structure + generation briefs per cut on the song timeline.              │
├─────────────────────────────────────────────────────────────────────────┤
│ STATUS STRIP (two chips, both always visible)                            │
│  ● Structure  [in progress | locked]     ● Briefs  [3/42 | locked]       │
├─────────────────────────────────────────────────────────────────────────┤
│ [ Structure ]  [ Brief ]          ← segmented control (tab)              │
├─────────────────────────────────────────────────────────────────────────┤
│ TOOLBAR (tab-specific)                                                   │
│  Structure: [Generate scaffold] [Lock structure]                         │
│  Brief:     [Generate all] [Generate missing] [Lock briefs]              │
│             (disabled until structure locked — same gate as today)         │
├─────────────────────────────────────────────────────────────────────────┤
│ ACT 01 — Verse                                    [Regenerate act ▼]     │
│ ┌────┬──────────────────────────────────────────────────────┬──────────┐ │
│ │ s01│ [structure pills / beat / framing]                  │ [Edit ▼] │ │
│ │    │ [brief preview OR “No brief yet” — grey]            │          │ │
│ └────┴──────────────────────────────────────────────────────┴──────────┘ │
│ ...                                                                      │
└─────────────────────────────────────────────────────────────────────────┘

Structure tab: same row body as today’s ScaffoldShotRow; Edit → existing ScaffoldShotEditModal only.

Brief tab: same as today’s PromptShotRow but remove duplicated collapsed scaffold block from every row (optional: one-line “s01 · wide · male · rooftop” + expand). Edit brief → ShotDirectionEditModal only (no vocal-performance fields).

Unified row (phase 2, optional): single list always shows:

1. Timecode column
2. Structure pills + beat line (always)
3. Brief preview line or dashed “No brief” (always, muted until brief exists)
4. Actions: Edit structure | Edit brief | Regen brief (brief actions disabled until structure locked)

Tabs then only change which toolbar actions are prominent, not which rows exist.

Locks and gates (unchanged semantics)

Status strip makes both locks visible so “I locked the page” is unambiguous.

Approve / Next step: after locking briefs, advance to Filming style (same as current step 10 → 11). Locking structure alone does not auto-advance sidebar focus unless user chooses “Continue to briefs” (optional CTA).

Edit modals

Phase 3 (optional): Edit shot combined modal with two sections and one Save that calls both APIs in sequence — only if product wants fewer clicks; not required for phase 1.

Component refactor (implementation map)

ShotPlannerPane
  └─ StepShotPlanPanel (new)
       ├─ ShotPlanStatusStrip
       ├─ ShotPlanTabBar (structure | brief)
       ├─ ShotPlanStructureToolbar  ← from StepScaffoldPanel header actions
       ├─ ShotPlanBriefToolbar      ← from StepPromptsPanel header actions
       └─ ShotPlanActList
            └─ ShotPlanRow (phase 2) OR tab-specific rows (phase 1)

Phase 1: mount existing StepScaffoldPanel / StepPromptsPanel bodies behind tabs (minimal risk).
Phase 2: extract shared act grouping + merge row UI.
Phase 3: combined modal, deep links, docs/screenshots.

STEPS config change (display only)

{
  key: "step_scaffold", // keep key
  index: 9,
  title: "Shot plan",
  blurb: "Shot list on the timeline (structure), then per-shot generation briefs. Lock structure before generating briefs.",
},
// step_prompts: hidden from sidebar OR marked internal-only; tab=brief sets activeStep step_prompts for hooks

activeStep resolution:

• Route shot-plan + tab=structure → render structure toolbar + scaffold rows; hooks that today check step_scaffold unchanged.
• Route shot-plan + tab=brief → render brief toolbar + prompt rows; activeStep for background jobs can remain step_prompts via internal planTab state.

Background jobs & polling

No change: jobKey("prompts", mixSrc) and scaffold generate still use existing endpoints. Tab switch must not clear in-flight brief jobs (already handled by background registry).

Docs & e2e

• User manual: one page Shot plan replacing scaffold + prompts; table of “structure vs brief” preserved.
• Screenshots: one full-page capture with brief tab selected showing mixed filled/empty briefs.
• E2e: navigate /project-plan/shot-plan?tab=brief instead of prompts.

Out of scope (explicit)

• Merging step_scaffold + step_prompts in Prisma / session schema
• Single lock for both
• One LLM call for structure + brief
• Moving filming style before briefs

Rollout

1. Phase 1 — New route + tabs + redirects; duplicate panels behind tabs; status strip. ~1–2 days.
2. Phase 2 — Unified row, drop redundant scaffold collapse on brief tab. ~2–3 days.
3. Phase 3 — Combined edit modal, shot deep links, sidebar renumber. Optional.

Open questions

1. Default tab after opening Shot plan: structure until locked, then auto-switch to brief?
2. Hide step 10 from sidebar entirely or show as disabled “Briefs (part of Shot plan)”?
3. Renumber user-facing steps 10→14 in docs (Filming style becomes 10) — cosmetic but touches many markdown files.