Vellum: make the handoff artifact do the work

Quality-of-life pass on the player: timeline-dot hover cards, keyboard save, and forgiving dot targets.

Leave feedback about the whole scene or the audio at a moment, no element click — via a collapsible left-edge dock.

Reads the composition’s voiceover-captions.vtt to attach the spoken line, clip script, and prev/next clips.

Player POSTs the scene map + dims + audio layout at mount (/api/composition) so the agent can resolve any note’s scene/timing.

Surfaces the captured label/box/data-* + a legend + dims, so the agent acts from the markdown alone.

Temp-file + rename so a crash mid-write can’t truncate annotations.json and wedge the API.

Records current font/color/size on element notes → a style: line, so “make it bigger” is an edit from a known value.

Shows the current VTT cue over the video so VO/visual desync is visible; toggle persists.

One-frame nudges (comp fps, else 1/30s) — finer than the 0.1s arrows. No guessed frame index.

When a note’s element no longer resolves, the drawer shows “unresolved — re-verify” and the dot gets an amber ring.

Give the agent a structured channel — resolution{by,at,summary,edits[]} reconciled on next boot — to record what it changed and flip a note to “addressed” for the human to verify. Turns the one-way handoff into a closed loop, no backend. NOTE_STATUSES already gates status; SKILL.md step 6 must pin the exact shape and readNotes() must tolerate agent-written JSON.

notes/ is fully gitignored, so reviews never travel through normal git. Track them and stamp each with the commit + index.html content-hash it was made against. The made-against commit is the keystone that unblocks real stale-detection and enriches write-back. Best-effort git rev-parse; document the tracked path in .gitignore.

Capture timeEnd so the most common timing edits — “cut 2s”, “hold this beat”, retime — are lossless intervals instead of a single guessed timestamp. I/O keys are cleaner than shift-drag on #scrub (which collides with its oninput). Absent timeEnd = today’s point note (clean back-compat).

The product exists to raise first-pass fix rate and cut time-to-note — yet nothing measures either, though both are computable locally from data already on disk (a note marked addressed→reopened is a failed first pass; create→resolve gap is the round-trip). A small gitignored ledger surfaces “3 of 8 notes needed a second pass.” Without it, every value score on this page is a guess.

fs.watch + iframe reload, reusing mount’s savedT seek to restore the exact frame after the agent edits index.html. Debounce (agents write several files per edit) and guard an open composer / unsaved note. Prefer a “reload” affordance over silent thrash.

A blocker/nit severity is signal the agent can’t derive from prose; clustering notes by selector in writeNotes() stops it from reopening the same scene repeatedly. Keep tagging to severity + clustering — skip “intent recipes,” which duplicate the hyperframes skill.

A pasted layout sketch is directly agent-actionable; writes to notes/attachments/ via resolveInside. Base64-in-JSON blows the 1e6 readBody cap → needs a raised cap or a raw-binary path. Keep it agent-actionable, not a gallery.

Lossless translation for the biggest feedback class (move / resize). Vellum records the element’s current box but encoded only an area, never a direction. Two bounded optional fields (arrow, desiredBox) extend drawMarker and emit the delta a single shared helper phrases identically in annotations.md and the review packet. Shipped — the cleanest large bet, landed first.

vellum-review caches the frame each note was pinned against (keyed by its index.html content-hash); a re-run after the edit pairs before · after in INDEX.md so the agent self-checks its edit. The CLI half shipped (lazy cache + side-by-side table, reuses snapshot()/drawMarker); the in-player onion-skin is still deferred. The “before” must be captured before the edit — run vellum-review first.

Deferred by design in v0.8.0: the safety need is already covered (immutable provenance.indexHash + the shipped stale-flag surface drift as “re-verify”), and before/after subsumes its one genuine bug — a slide is now shown explicitly as a before · after pair rather than a single frame silently relocated to the wrong scene. Sold as “existential,” but the agent reads all absolute times once from static annotations.json before editing, so drift only bites on a human re-open or 2nd pass. Revisit only if a real-drift metric fires; it’s a correctness-sensitive rewrite with an authoritative-time ambiguity to resolve first. Build on the schema-versioned store before attempting.

Two smoke tests: the shipped player loads no external resource (absolute or protocol-relative — verified by a negative control), and a scripts/*.mjs import-scan guarantees a fresh install is complete. Local-first / offline / single curl|sh IS the moat’s physical form, and nothing enforced it before.

The two readers had diverged (server filtered + reconciled; review.mjs did neither). Consolidated into one module: a single read contract (drop non-objects → reconcileNote), an atomic bare-array writer (byte-identical legacy), and a forward-compat {schema_version, notes} envelope tolerated on read but never written. The bare-array on-disk invariant is preserved; the standalone JSON-Schema validator was dropped in simplify as having no consumer (reconcileNote already enforces the shape on read).

Typedefs in vellum-shared.mjs + tsc --noEmit in CI (both workflows) over the library modules catch cross-module signature drift at the .mjs boundaries. Two documented opt-outs: the inline <script> client capture and the smoke-test harness (which pounds dynamic res.json()) stay unchecked.

serveStatic blocked ROOT-escape but happily served /.env and /.git/config, and there was no Host/Origin check → DNS-rebinding risk. Added a loopback Host allowlist + a dotfile denylist (split on both separators, so an encoded %5C backslash can’t bypass it on Windows) + smoke tests with a forged-Host probe.

Shipped in v0.10.0 — the caption-safe-area detector. At mount Vellum flags captions crossing the title-safe margin and surfaces them as a dock + markers the reviewer confirms (Y → a note carrying origin:{by,detector,at}) or dismisses (X); a proposals:{shown,accepted,acceptRate} lift block in the ledger gates whether a second detector is worth it. Pure rule (unit-tested) + drift-guarded inline mirror; precision-first (full-bleed/centered captions and hidden-frame captions don't false-flag), de-duped against existing notes, idempotent confirm. Proposing isn't editing — it never touches the composition. Built design → implement → browser-verified → adversarial review (15 findings fixed) → simplify.