creator-editing-studio 1.2.4 → 1.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "creator-editing-studio",
-  "version": "1.2.4",
+  "version": "1.2.8",
   "description": "Scaffolds a Creator Editing OS studio — components, scripts and rules for editing video from a plain-English brief.",
   "license": "UNLICENSED",
   "type": "module",

package/template/CLAUDE.md

@@ -48,6 +48,92 @@ Everything else in `src/design/` is the system and should be left alone. If a vi
 a colour or a size that is not in tokens.ts, the answer is to add it to tokens.ts, never to
 type it into a component.
 
+## The order of work — the plan is approved before anything is cut
+
+**Never render an edit the owner has not agreed to in writing first.** A render is the last
+step, not the first. Rebuilding a rejected edit costs more than every minute the plan takes.
+
+Every edit runs in this order. Do not skip a step, and do not collapse two into one.
+
+**1. Watch and probe.** `npm run prep -- <name>`. Get the real duration, fps and resolution
+of every clip. Never assume them.
+
+**2. Transcribe with word-level timings.** The transcript is the truth — not the script, not
+what the owner remembers saying. Every beat you place later is anchored to a word index, and
+every word index comes from this file.
+
+**3. Read the owner's style first, in this order:** `STYLE.md` §9 Rejected, then §8 Approved,
+then `references/references.md` and the contact sheets in `work/refs/`. Rejected comes first
+because removing options is faster than adding them. A reference beats a default wherever
+they disagree.
+
+**4. Write the plan, and hand it over.** Two things. Neither is a markdown file for them to
+open — a plan only gets corrected if it is in front of them.
+
+**The plan goes in the reply, as a table**, one row per beat:
+
+| # | In | Out | Trigger word (frame) | What is on screen | Audio under it |
+|---|---|---|---|---|---|
+
+Followed by the total runtime, the caption script, and a short list of what you chose not to do
+and why. In the reply, not attached.
+
+**The motion sheet is a PNG of real rendered frames** — one tile per beat, numbered, each
+labelled with its timecode, the words that trigger it, and the approved beat it comes from. Build
+the graphics, render one still per beat with `npm run stills`, and lay them out as a contact
+sheet composition. A graphic that cannot name its beat is not approved and does not go on the
+sheet. Describing motion in prose does not work: they cannot see it, so they cannot correct it.
+They point at a tile number and say what to change.
+
+Then stop and ask. Say plainly: *here is the plan, change anything that is off, say go ahead
+and I will cut it.* **Wait for a yes.** "Go ahead", "approved", "ship it" is a yes. Silence is
+not, and neither is a reply about something else.
+
+**5. Only then cut, render, and verify.** Verification is not optional and is not a claim —
+see below.
+
+If the owner says "just edit it" and skips the plan, write the plan anyway, in one short
+message, and cut immediately after. It costs thirty seconds and it is the only record of
+what was intended.
+
+## Verify the render before you call it done
+
+You have not seen the video. The timeline in your head is not evidence. Before you say an
+edit is finished, pull real frames out of the **rendered file** and look at them:
+
+```
+npm run stills -- --file out/<name>.mp4 --at 2,5,8,11,14,17,20
+```
+
+Put a still on **both sides of every cut** in the plan, and on any beat you are unsure of.
+Then say what you saw. Never write "this is fixed" about something you have not looked at.
+
+## Faults that keep recurring — check for these every time
+
+**Slivers of footage between graphics.** When two full-screen graphics run back to back, the
+second must start on the exact frame the first ends — `out` of one *is* `in` of the next.
+A gap of even one frame flashes the talking head for 30ms and reads as a broken edit, not a
+cut. Assert it in code: walk the beat list and fail if any `in` is greater than the previous
+`out`.
+
+**A caption word left alone on screen.** A word-by-word caption holds until the next word
+arrives. If the speaker pauses for a second mid-phrase, one word sits there alone and the
+viewer reads it as a stutter or a repeat. Cap any single word's hold at about 0.5s — after
+that, show the rest of the line greyed ahead, or drop the line and start the next one.
+
+**A graphic that renders invisible.** `zIndex` on one child creates a stacking context and can
+hide every sibling painted after it. Prefer paint order to `zIndex`. If a beat is in the plan
+and not in the stills, it did not render — find out why before shipping.
+
+**A nested video restarting.** Inside a `Sequence`, `useCurrentFrame()` is local. An
+`OffthreadVideo` placed in one starts from its own frame 0 and plays its own audio over the
+live line. Pass an explicit `startFrom`, and mute it unless its sound is wanted.
+
+**Repetition the owner can hear but you cannot.** If the owner says a line repeats, transcribe
+the rendered output over that exact window before arguing. If the audio is clean, the repeat
+is visual — a held caption, a reused graphic, or a duplicated framing — and that is still a
+real fault worth fixing, not a misunderstanding to explain away.
+
 ## Non-negotiables
 
 1. **No magic numbers.** Durations, curves, springs, staggers, blur come from `src/design/motion.ts`.