feat(flows): guided creation flows, P1–P9

[georgi]

What changed

All nine phases of docs/creation-flows/tasks.md — the guided creation flows for all five document kinds.

Storyboard (P1–P5). Contracts first: a persisted setupStage and genre, scenes on the screenplay, scene_id and camera equipment on a shot, and a per-version RenderInputs record so a still or clip reads stale against the inputs its shot would use now. Then one shared prompt module both the editor and the headless render tools compose through, the store's eight ordering operations behind a contiguous shot.index, the SetupFlow shell and its steps, the board (scene headers, drag across scenes, staleness, batch reattachment), the full-screen Edit Shot dialog, and the FDX/CSV/DOCX/PDF imports with a custom-style path.

Video, Script, Image, Workflow (P6–P9). Each follows the storyboard's shape: a persisted setup on its document, format/use-case/category cards, a step-2 plan that spends nothing (D4), a look-or-setup step, and a generate that lands in the editor — with headless mirrors and eval cases.

Every schema stays passthrough and every new field defaults, so documents written before this change load unchanged (PRD § 7.7.7).

Notable calls, each argued in its own commit message:

• ←/→ step versions in the Edit dialog, per PRD § 7.5. An earlier pass had them stepping shots, which swapped the shot out from under an open draft.
• Genre stills and style thumbnails live under assets/nodetool-base/, which bundle-backend.mjs copies wholesale — not PACKAGE_RUNTIME_ASSETS, which is for files beside a package's compiled dist/. tasks.md said the latter; it is corrected here, since registering a path with no file behind it fails backend:smoke.
• storyboards.stylePresets is classified gap, not elsewhere: reading the presets is reachable through list_entities, but seedStylePresets runs from that mutation and nowhere else, so a headless run on a fresh account finds none.

Verification

• npm run test:affected
• npm run typecheck — web and electron clean
• npm run lint — exit 0; lint:anti-slop:enforced at zero
• npm run dev:nodetool -- harness gate --base origin/main — 12/12 selfchecks, no capability-mapping violations
• npm run capabilities:check — current at 275 capabilities
• Full web suite — 1,354 suites, 14,942 tests

Three defects CI or the harness caught that local runs did not, all fixed here:

Line ids collided within a millisecond. The prefix was w${Date.now().toString(36)}, so two writes in the same millisecond minted the same ids and a rewrite's new line inherited the takes — generated audio — of the line it replaced. A monotonic counter joins the timestamp, as this repo's other id helpers already do. Both call sites had it. The regression test freezes the clock; against the old prefix it fails with Received array: ["wmjuohs00_line_1", "wmjuohs00_line_2"].

Incomplete multi-character sanitization (CodeQL) in the subtitle parser: one strip pass spliced a nested tag's remains into a new one, so <scr<b>ipt>alert(1)</scr</b>ipt> came out as ipt>alert(1)ipt>. The tag class now excludes < and the replace repeats to a fixed point. A bare < with no > is still left alone — this parser's contract is the spoken words verbatim, and "if x < y" is words, not markup.

edit_timeline advertised four ops no test reached through that surface. The harness said so. The first fix would have added the flow's suite to the attribution pool — but that suite drives the eval bridge's ui_timeline_* tools, a different entry point, so it would have made the check pass without making the coverage real. The actual fix invokes edit_timeline with set_setup, plan_beats and generate_from_beats.

Agent capabilities

Six new capabilities, all in the table with named suites: write_script, refine_image_brief, set_workflow_setup, plan_workflow, update_workflow_plan_step, build_workflow_from_plan. edit_storyboard, edit_script, edit_sketch and edit_timeline re-declare their contracts and carry updated coverage. capabilities:check passes.

The capability-suites selfcheck's command and its filter list were two copies of one string, so timeline-video-flow.test.ts was written, passing, and never run by the gate — they are one constant now, as the script↔storyboard entry already is.

New checks

• Each new check was inverted once and observed failing; the failing output is in the commit that adds it
• The R6 app-build case grades the run's output, not only validation — a plan that validates and produces nothing scores 0.67 and fails, pinned by its own test so the check cannot stop examining anything

Not done

• The 14 genre stills and 12 style-preset thumbnails need artwork. Data, paths, seeding and a directory-walking test are in place; cards render a typographic fallback. Adding a JPG plus its id to SHIPPED_GENRE_STILLS turns each one on. No path is registered without a file behind it.
• The Edit Shot dialog's scene-header save writes up to three undo checkpoints where § 7.5 asks for one. The twelve table fields — what criterion 14 measures — are one entry; the header row needs a batched store action.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TL39a2ajm5iVkRrnjbVER4

[georgi]

Review round

Three parallel review agents (correctness, standards, spec) ran over the whole branch. Four findings fixed in 343f1f92 and 5616938d, each with a test proven red against the old code first.

Direct-gen replies settled against the wrong sequence. subscribeDirectGen re-read timeline.getState().sequenceId when the rpc_response arrived, minutes after the send. Switch sequences while a clip is rendering and the original sequence's pending entry is never removed; reopen it inside the 30-minute TTL and reattachment restores it, sets the clip back to generating and subscribes to a request id that already replied — a clip stuck rendering over a paid render that was thrown away. The id is now captured at send time and passed in. The settle also moved above the clips.find lookup: the pending entry belongs to the request, not to whether its clip is still on screen, and the early return was the second half of the same leak. The first diagnosis stopped at the live read; writing the test showed both halves were needed.

writeWorkflowSetup dropped the settings bag on an unparseable setup. A stage outside this build's enum — one a newer client or an agent wrote — sent the whole bag through the {} branch, so hide_ui and every sibling setting were lost on the next write. Unparseable setup now keeps the caller's keys and replaces only setup.

messageChars threw on a schema-valid frame. The wire schema validates a block as { type: string } with passthrough, so { "type": "text" } with no text is legal; reading .length off it threw on the spend-admission path, before anything could refuse the call.

PRD § 10.3 had been relaxed on a misreading of R5. R5 does not forbid model samples — it says they may be fetched on first use instead of shipped, which is what E2's clip tiles already do. E4 dropped the sample and the PRD was rewritten to match, contradicting tasks.md P8. The code was what was wrong. modelSamples.ts moves up a level and takes the sample kind: <video> + loadedmetadata + .mp4 for a clip, <img> + load + .jpg for a still. Both look steps go through it, and the PRD text is restored. A model with no published sample keeps its typographic fallback.

Reported and not acted on, since they are refactors across files this PR only partly touches: five-way duplication of the brief-entry block across the IdeaStep.tsx files, the five start*Flow callbacks in NewProjectSurface, and StudioHome's third copy of the same starters.

origin/main merged in. One conflict, in run-budget.test.ts: both sides had fixed the same fake-timer flake with identical bodies and different comments; main's comment kept.

Verified on the merge result: build:packages 62/62, tsc -p web/tsconfig.json clean, packages/runtime 80/80, packages/protocol 9/9, packages/websocket direct-text-spend 7/7, and 397 web tests across the 48 suites this diff and the merge touch.

The two documented gaps in the PR description — genre and style artwork, and the scene-header save writing up to three undo checkpoints — still stand as written.

---

Generated by Claude Code

[georgi]

Found three actionable bugs in the video creation flow at df0fd0f, detailed inline. F1 prevents recovery of paid renders after a browser reload; F2 ignores the selected output aspect ratio; F3 never submits the music bed.

Validation: executed the PR's generateFromBeats function in isolation with a minimal store and stubbed model/job boundaries. A portrait sequence with a landscape format produced aspectRatio="16:9", and music:true created a music clip without a provider/model while only the video clip was submitted. Traced F1 through the current-head WebSocket subscription, RPC response, and socket delivery paths. The existing reattachment test injects a response after subscribing and therefore does not exercise a closed socket or a completed request.

This was a focused correctness review of generation and recovery paths, not an exhaustive review of all 349 files. I did not run the full application test suite.

[georgi]

F1 [P1] Recover the server result instead of only registering a local listener

Start a video render, close/reload the browser tab, then reopen the sequence. This code sets the clip to generating and calls subscribeDirectGen, but GlobalWebSocketManager.subscribe only adds a handler to a local Map; it sends no recovery request. generate_media runs through CommandRouter.runRpc, whose rpc_response has neither job_id nor thread_id, so WebSocketClientSession.sendMessage does not put it in a replay session. It goes to the original socket and is dropped once that socket is disconnected. The reopened sequence therefore never receives the result, even if generation finishes after reopening. Persist a server-side request/job result and retrieve or resume it here before marking the clip generating. Add a test where the original socket closes and generation completes before the new client subscribes.

[georgi]

Your trace is right, and I confirmed each hop: runRpc sends { type: "rpc_response", request_id, command, result } with no job_id and no thread_id, so WebSocketClientSession.sendMessage falls past both replay branches to sendToSocket, which returns early on a disconnected socket. Re-subscribing to that id can never produce the reply.

I have not built the server-side resume, and I want to be explicit that this is a deliberate stand-down rather than an oversight.

Why not here. The same limitation is E1's, in this same PR — StoryboardGenerationStore rides the identical generate_media RPC and documents it at PENDING_JOB_TTL_MS: "A reply that landed while the tab was shut is gone, so its entry can never resolve." PRD § 8.4 asks E2 to reattach "through the same job reconciliation as E1", and it does. What neither meets is § 7.4's premise that "batch jobs are server jobs" reconciled by id. Fixing that means giving generate_media a persisted result and a resume path, then moving both flows onto it — a backend feature with its own surface, not something to land inside a 349-file PR as a review fix. I have added it to the PR's Not-done list rather than quietly narrowing the spec to match the code.

What I did fix, because it is the part that actually costs the user something: the clip no longer spins forever. reattachSequenceJobs passes the remainder of the entry's own 30-minute window to subscribeDirectGen, and a subscription that reaches it settles the pending entry and fails the clip. A reply that has not arrived by the end of its window never will, so the clip lands on Retry — the affordance § 8.4 already gives a failed clip — instead of generating over a dead socket. Before this the entry was pruned by TTL while the clip it had already patched stayed generating with nothing behind it.

Two tests, in reattachSequenceJobs.test.ts on a fake clock: one reattaches an entry started 25 minutes ago, asserts generating, advances past the window and asserts failed with the entry gone; the other lets the reply arrive, advances an hour, and asserts the clip kept its asset and was not failed. The first fails without the deadline.

I also corrected the header comment in directGenPending.ts — it said the subscription "dies with the tab", which overstated what reattachment recovers. The boundary is the socket, and it now says so, along with what closing that gap would take.

---

Generated by Claude Code

[georgi]

F2 [P2] Generate clips with the aspect ratio selected in the Look step

The Look step's aspect picker saves the sequence width/height, and its cost estimate uses those dimensions. This function instead stamps every generated clip with the original format's aspectRatio. For example, choose a 16:9 format, switch to 9:16 in Look, then Generate: the timeline is portrait but every paid video request still asks for 16:9. The isolated function reproduction confirms this. Derive the generation aspect from the current sequence dimensions, or pass the selected aspect explicitly, so preview, estimate and provider request agree.

[georgi]

Confirmed and fixed. The generated clips now read aspectOf(store.width, store.height) — the same derivation the estimate uses.

aspectOf moved out of LookStep.tsx into components/storyboard/aspectOptions.ts, beside the ASPECT_OPTIONS it scans, so the picker, the estimate and the request are one function rather than three readings. A hook importing a helper out of a component was the shape that let them drift.

Test: a "ad-15" (16:9) plan on a sequence switched to 1080×1920 asserts every video clip stamps 9:16. Against aspectRatio: format?.aspectRatio it fails with 16:9. A second case pins the unchanged path, so the fix cannot be "always portrait".

---

Generated by Claude Code

[georgi]

F3 [P2] Supply a music model and enqueue the enabled music bed

The actual Look-step caller passes only { voiceover, voice, music: musicOn }; it never supplies musicProvider/musicModel, and there is no music-model picker or fallback. With Music enabled, this function creates a bed with undefined provider/model, then this condition excludes it from the generation queue. The flow finishes with a silent draft placeholder instead of music. Reproduced with the caller's options: musicClipId is returned but startedClipIds contains only the video clip. Resolve a supported music model/provider and enqueue the bed when Music is enabled (or make the unavailable option explicit until that path exists).

[georgi]

Confirmed. Took the second option — made the absence explicit — because the first has nothing to resolve against.

NODETOOL_MODELS carries language, image, video and tts kinds and no music one, and the last-model store's audio bucket holds the TTS voice, so there is no curated music model for the step to pick. useMusicModelsByProvider() would find one only where the user has connected a provider that serves text_to_music, and it pulls a TanStack query into a step that is otherwise static — it broke useVideoSetupFlow.test.tsx with No QueryClient set, which is a fair signal about where that dependency belongs. Which music model NodeTool curates and bills for is a product call, not one to make inside a review fix.

So: MUSIC_AVAILABLE = false in LookStep.tsx, the toggle rendered disabled with "Not available yet — no music model is curated", and generateFromBeats no longer creates a bed it has no model for (if (musicTrack && options.musicModel)). The queue filter you pointed at is gone — a bed that exists is now always queued, which is the invariant that was missing. musicProvider/musicModel stay on the options, so the agent bridge's generate_from_beats can still supply them, and the constant flips to a real lookup when a music model is curated.

Three tests changed count from 6 to 7 as a result: they were pinning the bed's exclusion. The queue test now reads "enqueues every clip it cut, bed included".

---

Generated by Claude Code

[georgi]

Review round 2 — @georgi's F1–F3

All three confirmed by reading the code, and fixed in b4443342. Each fix has a test proven red against the reported behaviour first; details are on the three review threads.

• F2 — generated clips now stamp aspectOf(width, height), the same derivation the cost estimate uses. aspectOf moved beside ASPECT_OPTIONS so the picker, the estimate and the provider request are one function.
• F3 — took the "make the unavailable option explicit" branch: no music model is curated (NODETOOL_MODELS has no music kind), so the bed is only cut when a model is supplied, a bed that exists is always queued, and the toggle is offered disabled naming the gap.
• F1 — the server-side resume is not built; see the thread for the full reasoning. The clip no longer spins forever: a reattached subscription carries the remainder of its own 30-minute window and, on reaching it, fails the clip so it offers Retry.

Not done — added by this round

• A generate_media reply is lost when its socket is. It is an rpc_response with no job_id and no thread_id, so WebSocketClientSession.sendMessage writes it to the asking socket and drops it if that socket has gone. Reattachment therefore recovers a request whose socket outlived the sequence, not one whose reply landed while the browser was shut. This is the storyboard flow's gap too — StoryboardGenerationStore rides the same RPC and documents it at PENDING_JOB_TTL_MS — so PRD § 7.4's "batch jobs are server jobs, reconciled by id" is unmet by both. Closing it means giving generate_media a persisted result and a resume path and moving both flows onto it: a backend change with its own surface, not a review fix inside this PR. Recorded here rather than narrowing the spec to match the code.

Verified: web typecheck exit 0; 894 tests across the 98 suites under hooks/timeline, components/setup, components/storyboard and lib/tools; oxlint and the enforced anti-slop config exit 0 on every changed file.

---

Generated by Claude Code