Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
chore: remove committed design notes and ignore docs/contracts (#5107)
Miguel Ángel6308727b8572
diff --git a/.gitignore b/.gitignoreindex 0a72e3b30c..740a461a20 100644--- a/.gitignore+++ b/.gitignore@@ -77,8 +77,9 @@ packages/core/src/generated/*!packages/core/src/generated/position-edits-render-inline.test.tspackages/core/src/fonts/fontData.generated.ts-# Plan documents (working artifacts, not committed)+# Plan and contract documents (working artifacts, not committed)docs/plans/+docs/contracts/# Local proof / test artifactsqa-artifacts/diff --git a/docs/contracts/2026-10-01-timeline-filmstrip.html b/docs/contracts/2026-10-01-timeline-filmstrip.htmldeleted file mode 100644index 1040bbd7b2..0000000000--- a/docs/contracts/2026-10-01-timeline-filmstrip.html+++ /dev/null@@ -1,98 +0,0 @@-<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Filmstrip contract</title><style>-:root{color-scheme:light dark;- --bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;- --go:#178a5a;--go-bg:#e8f6ee;--warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;- --mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}-@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;- --go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;--bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}-*{box-sizing:border-box}-body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}-.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}-header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}-header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}-.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}-.strip .sep{opacity:.5}-.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}-.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}-.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}-.pill b{font-size:13px}-section{margin-top:56px}-h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}-.sub{color:var(--dim);margin:0 0 18px;font-size:15px}-.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}-.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}-.breath b{color:var(--go)}-.plain{color:var(--dim);font-size:15px;margin:0 0 10px}-.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}-pre{background:var(--bg);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow:auto;font:13px/1.55 var(--mono);margin:10px 0}-code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}-.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}-.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}-table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}-th{text-align:left;font:600 11px/1.4 var(--mono);text-transform:uppercase;letter-spacing:.7px;color:var(--faint);border-bottom:1px solid var(--line);padding:8px 10px}-td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}-tr:last-child td{border-bottom:0}-td.k{font:13px var(--mono);white-space:nowrap}-.decision{border-left:4px solid var(--info)}-.decision h3{margin:0 0 8px;font-size:17px}-.decision .ask{color:var(--info);font-weight:600}-blockquote{margin:12px 0;padding:8px 0 8px 16px;border-left:2px solid var(--line);color:var(--dim);font-style:italic;font-size:14.5px}-blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}-ul,ol{padding-left:22px}li{margin:6px 0}-.mermaid{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px;margin:14px 0;overflow:auto}-.mermaid svg{max-width:100%}-footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}-</style></head><body><div class="wrap"><header><h1>Filmstrip timeline clips</h1><p class="what">Frames edge to edge, cropped to fill, with the name in its own 15px band above the picture.</p><div class="strip"><span class="pill go">audited <b>4 boundaries</b></span><span class="pill warn">trusting <b>0</b></span><span class="pill bad">not exercised <b>4</b></span><span class="pill info">decisions <b>0</b></span><span>Studio @ 45b8e171e2792c89cc63b4d136de41eae6194b25</span></div></header>-<section><div class="card breath"><b>In one breath.</b> Studio owns the name and picture wrapper; thumbnail components own cropping; a host can replace the content and override the CSS tokens.</div></section>-<section><h2>Where the value travels</h2><div class="mermaid">flowchart LR-A[App or host] --> B[TimelinePane] --> C[TimelineClip]-C --> D[renderClipChildren]-D --> E[useRenderClipContent]-E --> F[Thumbnail components]-G[Host CSS overrides] --> C-classDef audited fill:#e8f6ee,stroke:#178a5a,color:#0f3d28-class A,B,C,D,E,F,G audited-</div><p class="sub">Source reachability is audited. No running build has been exercised.</p></section>-<section><h2>The contract, per boundary</h2><div class="card"><h3>1. Clip-content callback</h3><p class="plain">The same callback builds picture content for Studio and embedding hosts.</p><pre>renderClipContent(element, clipStyle, context)--if (!pid) return null;--return createElement(CompositionThumbnail, {- previewUrl: buildProjectApiPath(pid, `/preview/comp/${encodePreviewPath(compSrc)}`),- label: "",- labelColor: style.label,</pre><span class="cite">producer: src/hooks/useRenderClipContent.ts:136,166; accepting call: src/player/components/timelineClipChildren.tsx:67; app handoff: src/App.tsx:530; pane: src/components/nle/TimelinePane.tsx:107; package export: src/index.ts:67</span><div class="states"><span class="pill go">exists: yes</span><span class="pill go">reachable: source audited</span><span class="pill go">written/read: yes</span><span class="pill bad">runtime: not exercised</span></div></div><div class="card"><h3>2. Picture wrapper and name</h3><p class="plain">The clip button supplies the name separately. The content wrapper currently fills the whole button.</p><pre>const showLabel = ladder === "labeled";-{showLabel && <span className="timeline-clip__label">{displayLabel}</span>}--<div- className="absolute inset-0 overflow-hidden"- style={{ borderRadius: "inherit", pointerEvents: "none" }}-></pre><span class="cite">name producer and consumer: src/player/components/TimelineClip.tsx:74,212; content consumer: src/player/components/timelineClipChildren.tsx:63; name paint: src/styles/components.css:334</span><div class="states"><span class="pill go">exists: yes</span><span class="pill go">reachable: source audited</span><span class="pill go">written/read: yes</span><span class="pill bad">runtime: not exercised</span></div></div><div class="card"><h3>3. Frame layout and fit</h3><p class="plain">Video and image tiles already fill their rectangles. Composition tiles contain the picture, which leaves letterboxing.</p><pre>const frameW = Math.max(minFrameWidth, Math.round(clipHeight * safeAspect));-const frameCount = measured ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;--// CompositionThumbnail rendered image class:-className="absolute inset-0 h-full w-full object-contain"</pre><span class="cite">layout producer: src/player/components/thumbnailUtils.ts:75; consumer: CompositionThumbnail.tsx:161; image consumer: CompositionThumbnail.tsx:185; video and image fit: VideoThumbnail.tsx:138, ImageThumbnail.tsx:61</span><div class="states"><span class="pill go">exists: yes</span><span class="pill go">reachable: source audited</span><span class="pill go">written/read: yes</span><span class="pill bad">runtime: not exercised</span></div></div><div class="card"><h3>4. Theme and host overrides</h3><p class="plain">Changing the Studio defaults alone does not change an embedding host that writes its own token values or selection styles.</p><pre>--timeline-clip-radius: 8px;---timeline-clip-audio-radius: 21px;--clipRadius: "var(--timeline-clip-radius)",--.timeline-clip.is-selected {- outline: 1.5px solid var(--timeline-clip-selection);- outline-offset: -1.5px;-}</pre><span class="cite">token producer: src/styles/theme.css:122; token consumer: src/player/components/timelineTheme.ts:73, TimelineClip.tsx:109; selection consumer: src/styles/components.css:307; package exports: package.json:39-43. Host override audit is local only; runtime propagation has not been tested.</span><div class="states"><span class="pill go">exists: yes</span><span class="pill go">reachable: source audited</span><span class="pill go">written/read: yes</span><span class="pill bad">runtime: not exercised</span></div></div></section>-<section><h2>How it says no</h2><table><thead><tr><th>Signal</th><th>Owner</th><th>Meaning</th></tr></thead><tbody><tr><td>null</td><td>useRenderClipContent:142</td><td>No active project. No picture returned.</td></tr><tr><td>Hidden thumbnail mode</td><td>useRenderClipContent:148</td><td>Pictures are suppressed; sound content follows the existing waveform path.</td></tr><tr><td>Loading or error snapshot</td><td>Thumbnail component</td><td>A picture is not ready. The band must keep its geometry while the existing loading/error state paints below.</td></tr><tr><td>Under 60px</td><td>clipWidthLadder</td><td>The baseline hides the label. The approved Filmstrip keeps the name band for visual clips; audio retains the width ladder. The full name remains on the button's accessible label and title.</td></tr></tbody></table></section>-<section><h2>Approved specification</h2><div class="card"><p>Match the selected Filmstrip prototype: a dark 15px name band, no picture dimming, zero frame gap, a 1px selection ring, and 12px corners on video and image clips. Audio keeps its current radius. Composition pictures keep contain fitting.</p><p>The band-colour ambiguity is resolved. No open product decision remains.</p></div></section><section><h2>Coverage, honestly</h2><table><tr><th>Audited</th><td>The callback producer, both app and host handoffs, picture wrapper, thumbnail layout, CSS paint, package exports, and host overrides.</td></tr><tr><th>Trusting</th><td>None of the load-bearing claims above rely on comments or mocks.</td></tr><tr><th>Not exercised</th><td>Studio and host rendered builds, browser layout, selection/trim/fade hit targets, light and dark contrast, narrow clips.</td></tr></table></section>-<section><h2>What would prove this page wrong</h2><ul><li>A running fixture whose name overlaps its picture after reserving the band at the clip wrapper.</li><li>A host build still painting 8px corners or its existing 2px plus 3px selection ring after the Studio release. This would expose a missed override.</li><li>A composition picture cropped to fill instead of retaining contain fitting.</li></ul></section>-<footer>Source audit, 2026-10-01. Runtime verification remains outstanding. This page records the pre-implementation boundary audit and the resolved specification.</footer></div><script type="module">-try {- const m = await import("https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs");- const dark = matchMedia("(prefers-color-scheme: dark)").matches;- m.default.initialize({ startOnLoad: false, theme: dark ? "dark" : "neutral", securityLevel: "loose",- themeVariables: { fontFamily: "ui-monospace, Menlo, monospace", fontSize: "13px" } });- await m.default.run({ querySelector: ".mermaid" });-} catch (e) {- for (const el of document.querySelectorAll(".mermaid")) {- const pre = document.createElement("pre"); pre.textContent = el.textContent.trim(); el.replaceWith(pre);- }-}-</script>-</body></html>diff --git a/docs/contracts/2026-10-02-ghost-lane-membership.html b/docs/contracts/2026-10-02-ghost-lane-membership.htmldeleted file mode 100644index dd10721f21..0000000000--- a/docs/contracts/2026-10-02-ghost-lane-membership.html+++ /dev/null@@ -1,67 +0,0 @@-<!doctype html>-<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>New-track membership contract</title><style>-:root{color-scheme:light dark;- --bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;- --go:#178a5a;--go-bg:#e8f6ee;--warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;- --mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}-@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;- --go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;--bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}-*{box-sizing:border-box}-body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}-.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}-header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}-header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}-.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}-.strip .sep{opacity:.5}-.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}-.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}-.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}-.pill b{font-size:13px}-section{margin-top:56px}-h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}-.sub{color:var(--dim);margin:0 0 18px;font-size:15px}-.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}-.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}-.breath b{color:var(--go)}-.plain{color:var(--dim);font-size:15px;margin:0 0 10px}-.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}-pre{background:var(--bg);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow:auto;font:13px/1.55 var(--mono);margin:10px 0}-code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}-.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}-.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}-table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}-th{text-align:left;font:600 11px/1.4 var(--mono);text-transform:uppercase;letter-spacing:.7px;color:var(--faint);border-bottom:1px solid var(--line);padding:8px 10px}-td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}-tr:last-child td{border-bottom:0}-td.k{font:13px var(--mono);white-space:nowrap}-.decision{border-left:4px solid var(--info)}-.decision h3{margin:0 0 8px;font-size:17px}-.decision .ask{color:var(--info);font-weight:600}-blockquote{margin:12px 0;padding:8px 0 8px 16px;border-left:2px solid var(--line);color:var(--dim);font-style:italic;font-size:14.5px}-blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}-ul,ol{padding-left:22px}li{margin:6px 0}-.flow{display:flex;flex-wrap:wrap;gap:10px;align-items:center;background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px;margin:14px 0;overflow:auto}-.flow span{border:1px solid var(--line);padding:12px;border-radius:8px}-footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}-</style></head><body><main class="wrap"><header><h1>New-track drops leave an audio group</h1><p class="what">A clip lands exactly where the ghost showed. One undo restores its track and membership.</p><div class="strip"><span class="pill go">audited 5</span><span class="pill warn">trusting 0</span><span class="pill bad">not exercised 1</span><span class="pill info">open decisions 0</span><span>hyperframes @ de13693179f53c3f625b7b501f1f5fc7b083b6c9, working changes, 2026-10-02</span></div></header>-<section><div class="card breath"><b>In one breath.</b> At the audited base, the move transaction saved track and timing but dropped membership before persistence. Detachment must travel through that transaction, rather than become a second save.</div></section>-<section><h2>Where the value travels</h2><div class="flow" aria-label="One transaction carries drop fields into undo"><span>Drop edits</span> → <span>Move adapter</span> → <span>Source patch</span> → <span>File + history</span> → <span>Undo restore</span></div></section>-<section><h2>The contract, per boundary</h2>-<div class="card"><h3>Move payload</h3><p class="plain">At the audited base, membership was absent from the move payload. The adapter explicitly selects only these fields.</p><pre>edits.map(({ element, updates }) => ({- element,- start: updates.start,- track: operation === "timing" ? undefined : updates.track,-}))</pre><span class="cite">producer src/player/components/timelineClipDragCommit.ts:153; consumer src/hooks/timelineMoveAdapter.ts:37. Paths relative to packages/studio.</span><div class="states"><span class="pill bad">membership: absent</span><span class="pill bad">reachable: no</span><span class="pill bad">written: no</span></div></div>-<div class="card"><h3>Atomic source edit</h3><p class="plain">The group move turns all clip changes into source patches inside one queued file transaction. Track changes bypass the timing-only SDK path.</p><pre>buildTimelineMoveTimingPatch(- original,- target,- toAuthoredStart(change.element, change.start),- change.element.duration,- change.track,-)</pre><span class="cite">producer src/hooks/useTimelineGroupEditing.ts:311; consumer src/hooks/timelineEditingHelpers.ts:235. SDK eligibility src/hooks/useTimelineGroupEditing.ts:299.</span><div class="states"><span class="pill go">track: exists</span><span class="pill go">reachable</span><span class="pill go">written</span></div></div>-<div class="card"><h3>Undo owns whole-file snapshots</h3><p class="plain">One transaction records the complete before and after source. Including membership in the same patch gives undo its original value.</p><pre>snapshots[path] = { before, after };-await recordEdit({ label, coalesceKey, coalesceMs, files: snapshots });</pre><span class="cite">producer src/utils/studioFileHistory.ts:128,144; undo consumer src/hooks/usePersistentEditHistory.ts:81,99; preview sync consumer src/hooks/useEditHistoryActions.ts:112.</span><div class="states"><span class="pill go">snapshots: exist</span><span class="pill go">reachable</span><span class="pill go">written and restored</span></div></div></section>-<section><h2>How it says no</h2><table><tr><th>Signal</th><th>Meaning and response</th></tr><tr><td>Locked shifted clip</td><td>Insertion returns without persistence. Existing permission rules remain the owner.</td></tr><tr><td>Save rejection</td><td>The file transaction restores already-written snapshots and rethrows. The optimistic clip rollback must restore membership alongside timing and track.</td></tr><tr><td>Undo content mismatch</td><td>History refuses to overwrite a file changed since the edit and reports the conflict.</td></tr></table></section>-<section><h2>Decision already supplied</h2><div class="card decision">New tracks outside a group detach the dragged clip. Drops onto member tracks retain existing behavior. Cmd+Z restores membership. There is no open product decision.</div></section>-<section><h2>Coverage, honestly</h2><table><tr><th>Label</th><th>Coverage</th></tr><tr><td>Audited</td><td>Drop edits, adapter, group move, source patch, snapshot and undo consumers opened at the named base.</td></tr><tr><td>Not exercised</td><td>This page records the pre-implementation audit. Runtime proof is reported separately against the implementation head.</td></tr></table></section>-<section><h2>What would prove this page wrong</h2><p>Drop a grouped clip at a group edge, reload the file, then Cmd+Z. The clip must lose membership after the drop, occupy the promised lane, and regain its original track and membership in one undo. A member-track drop must retain membership.</p></section></main></body></html>diff --git a/docs/contracts/2026-10-02-thumbnail-document-lifetime.html b/docs/contracts/2026-10-02-thumbnail-document-lifetime.htmldeleted file mode 100644index 1407a24e4c..0000000000--- a/docs/contracts/2026-10-02-thumbnail-document-lifetime.html+++ /dev/null@@ -1,59 +0,0 @@-<!doctype html>-<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Thumbnail document lifetime</title><style>-:root{color-scheme:light dark;- --bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;- --go:#178a5a;--go-bg:#e8f6ee;--warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;- --mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}-@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;- --go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;--bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}-*{box-sizing:border-box}-body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}-.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}-header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}-header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}-.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}-.strip .sep{opacity:.5}-.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}-.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}-.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}-.pill b{font-size:13px}-section{margin-top:56px}-h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}-.sub{color:var(--dim);margin:0 0 18px;font-size:15px}-.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}-.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}-.breath b{color:var(--go)}-.plain{color:var(--dim);font-size:15px;margin:0 0 10px}-.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}-pre{background:var(--bg);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow:auto;font:13px/1.55 var(--mono);margin:10px 0}-code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}-.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}-.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}-table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}-th{text-align:left;font:600 11px/1.4 var(--mono);text-transform:uppercase;letter-spacing:.7px;color:var(--faint);border-bottom:1px solid var(--line);padding:8px 10px}-td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}-tr:last-child td{border-bottom:0}-td.k{font:13px var(--mono);white-space:nowrap}-.decision{border-left:4px solid var(--info)}-.decision h3{margin:0 0 8px;font-size:17px}-.decision .ask{color:var(--info);font-weight:600}-blockquote{margin:12px 0;padding:8px 0 8px 16px;border-left:2px solid var(--line);color:var(--dim);font-style:italic;font-size:14.5px}-blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}-ul,ol{padding-left:22px}li{margin:6px 0}-.flow{display:flex;flex-wrap:wrap;gap:10px;align-items:center;background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px;margin:14px 0;overflow:auto}-.flow span{border:1px solid var(--line);padding:12px;border-radius:8px}-footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}-</style></head><body><main class="wrap"><header><h1>Thumbnail connections leave with their document</h1><p class="what">Saves must not queue behind media from a document the person already left.</p><div class="strip">2026-10-02 · source 0337620 · audited 4 · trusting 0 · not exercised 1 · decisions 0</div></header>-<section><h2>In one breath</h2><div class="card breath">The scheduler bounds work in one document, but old documents retain thumbnail connections after navigation; the lifecycle actor must abort that work on pagehide and resume retained leases on pageshow.</div></section>-<section><h2>Where the value travels</h2><div class="flow"><span>pagehide / pageshow</span> → <span>One lifecycle actor</span> → <span>Thumbnail scheduler</span> → <span>AbortSignal</span> → <span>fetch / media decoder</span></div></section>-<section><h2>The verified boundaries</h2><div class="card"><h3>Scheduler owns work</h3><pre>entry.controller = new AbortController();-entry.request.load(controller.signal)</pre><span class="cite">Producer packages/studio/src/player/lib/thumbnailScheduler.ts:291-301; consumer packages/studio/src/player/components/CompositionThumbnail.tsx:104-112.</span><p>The controller exists, is passed to the actual fetch, and is already aborted when the final lease leaves. Document navigation currently has no scheduler actor.</p></div>-<div class="card"><h3>Abort and retain</h3><pre>entry.preempted = true;-entry.controller?.abort();</pre><span class="cite">Producer thumbnailScheduler.ts:228-231; consumer catch/requeue/pump at :301-320 and :344-351. Paths relative to packages/studio/src/player/lib.</span><p>Existing preview reload preempts composition jobs and retains leases. Pagehide and document visibility suspension must be a separate cause: pageshow cannot release a preview-reload hold. While suspended, no queued thumbnail kind may start.</p></div>-<div class="card"><h3>The receiving HTTP route</h3><pre>await thumbnailGenerationCoordinator.acquire(- cachePath, c.req.raw.signal, async (signal) => adapter.generateThumbnail({ signal, ... })-)</pre><span class="cite">packages/studio-server/src/routes/thumbnail.ts:227-244; client fetch signal at CompositionThumbnail.tsx:108-110.</span><p>Client abort releases its browser connection. Server cancellation propagation is a separate host concern; the dev HTTP bridge must forward response disconnects into that signal so queued renders lose their leases. The endpoint is a one-shot image response, not a stream or long poll. Its serial queue had no server deadline; the existing client deadline is 30 seconds, but old-document timers may stop after navigation. Lifecycle abort plus propagated disconnect removes abandoned work instead of waiting for that timer.</p></div></section>-<section><h2>How it says no</h2><table><tr><th>Signal</th><th>Meaning</th></tr><tr><td>AbortError</td><td>Requested cancellation; retained leases return to the queue. No thumbnail error state.</td></tr><tr><td>Document hidden</td><td>Abort active work and hold all queued thumbnail kinds.</td></tr><tr><td>Preview reload remains active</td><td>Pageshow permits other thumbnail kinds, but composition work retains its existing hold.</td></tr></table></section>-<section><h2>Decision already supplied</h2><div class="card">Saves never queue behind media. Fix the held connections, preserve a tight persistence bound. No new product decision.</div></section>-<section><h2>Coverage, honestly</h2><p>Audited: scheduler, real composition fetch, preview-reload caller, server consumer. Runtime: Chrome NetLog shows all six sockets occupied by thumbnails, four from previous documents and two current, at a PUT stalled by the per-host socket limit. A real HTTP regression holds render responses open across hidden project documents and verifies a durable drop within 15 seconds. Removing the lifecycle binding fails that exact persistence assertion. Unit checks cover all thumbnail kinds, resumption, independent preview holds and actual HTTP disconnects.</p></section>-<section><h2>What would prove this page wrong</h2><p>Hold real thumbnail render responses open, leave two project documents, then drop a clip. Old-document render requests must cancel before the next document saves; the drop must persist within 15 seconds while current thumbnails remain unfinished. Cache-only poster reads return an image or 404 without entering the render queue. Retained leases must resume and preview-reload holds must survive pageshow.</p></section></main></body></html>diff --git a/docs/contracts/2026-10-05-transcribe-language-progress.html b/docs/contracts/2026-10-05-transcribe-language-progress.htmldeleted file mode 100644index 27caf59991..0000000000--- a/docs/contracts/2026-10-05-transcribe-language-progress.html+++ /dev/null@@ -1,66 +0,0 @@-<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Transcription language and progress contract</title><style>-:root{color-scheme:light dark;- --bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;- --go:#178a5a;--go-bg:#e8f6ee;- --warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;- --mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}-@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;- --go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;- --bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}-*{box-sizing:border-box}-body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}-.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}-header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}-header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}-.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}-.strip .sep{opacity:.5}-.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}-.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}-.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}-.pill b{font-size:13px}-section{margin-top:56px}-h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}-.sub{color:var(--dim);margin:0 0 18px;font-size:15px}-.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}-.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}-.breath b{color:var(--go)}-.plain{color:var(--dim);font-size:15px;margin:0 0 10px}-.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}-pre{background:var(--bg);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow:auto;font:13px/1.55 var(--mono);margin:10px 0}-code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}-.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}-.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}-table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}-th{text-align:left;font:600 11px/1.4 var(--mono);text-transform:uppercase;letter-spacing:.7px;color:var(--faint);border-bottom:1px solid var(--line);padding:8px 10px}-td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}-tr:last-child td{border-bottom:0}-td.k{font:13px var(--mono);white-space:nowrap}-.decision{border-left:4px solid var(--info)}-.decision h3{margin:0 0 8px;font-size:17px}-.decision .ask{color:var(--info);font-weight:600}-blockquote{margin:12px 0;padding:8px 0 8px 16px;border-left:2px solid var(--line);color:var(--dim);font-style:italic;font-size:14.5px}-blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}-ul,ol{padding-left:22px}li{margin:6px 0}-.mermaid{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px;margin:14px 0;overflow:auto}-.mermaid svg{max-width:100%}-footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}-</style></head><body><main class="wrap"><header><h1>Transcription language and progress</h1><p class="what">Carry automatic language detection in the JSON result and emit progress separately so stdout stays parseable.</p><div class="strip">2026-10-05 · hyperframes @ d69eac0cb · 4 boundaries audited · native execution not exercised · decisions approved</div></header>-<section><div class="card breath"><b>In one breath.</b> stdout is one result, stderr carries typed progress records plus diagnostics, and detectedLanguage reports inference rather than a requested language.</div></section>-<section><h2>Where the value travels</h2><pre>Whisper JSON result.language → transcription result → CLI stdout → JSON consumer-HTTP response bytes → download pipeline → model callback → CLI stderr → progress consumer-Whisper words → normalization → transcript.json (word array, unchanged)</pre></section>-<section><h2>The contract, per boundary</h2>-<div class="card"><h3>Language</h3><p class="plain">The native result identifies the language used to decode. Only automatic selection qualifies as detection.</p><pre>result.language: string-Proposed terminal addition: detectedLanguage: string | null</pre><p>Upstream JSON writes result.language from whisper_full_lang_id. Explicit language also sets that state. Existing detection incorrectly searches stdout although the native logger writes stderr; missing detection then omits --language and falls back to native English default.</p><span class="cite">whisper.cpp 60c0be6ac: examples/cli/cli.cpp:84,735-736; src/whisper.cpp:6993-7013,7151-7153,9357-9366. CLI: whisper/transcribe.ts:17-23,466-504,534,560.</span><div class="states"><span class="pill go">exists: native JSON</span><span class="pill bad">reachable: dropped by wrapper</span><span class="pill bad">written: no terminal field</span></div></div>-<div class="card"><h3>Result and artifact</h3><p class="plain">Add metadata to the terminal result and preserve the existing word-array file.</p><pre>{ok:true, engine, model, wordCount, durationSeconds,- speechOnsetSeconds, transcriptPath, detectedLanguage}</pre><p>The existing model field currently reports the requested model even when the wrapper selects a multilingual variant. The wrapper will own the resolved model and return it with the result.</p><span class="cite">commands/transcribe.ts:397 writes Word[]; :400-410 emits stdout. Existing file consumer: commands/transcribe.ts:384 calls loadTranscript. External new-field consumption remains unverified.</span><div class="states"><span class="pill go">exists: result and words</span><span class="pill go">reachable: stdout and file</span><span class="pill warn">read: additions pending</span></div></div>-<div class="card"><h3>Download progress</h3><p class="plain">Count bytes in the existing transfer pipeline. Unknown size stays unknown.</p><pre>{"type":"progress","phase":"download","model":"small",- "receivedBytes":65536,"totalBytes":null}</pre><p>DownloadOptions currently has timeoutMs and maxBytes only. Add a byte callback at the transfer owner, thread it through ensureModel, and serialize it only at the command boundary. Cache hits emit no download events. A known total is bytes, never an invented percentage.</p><span class="cite">utils/download.ts:10-15,113-122; whisper/manager.ts:215-223; commands/transcribe.ts:341,347-354.</span><div class="states"><span class="pill bad">exists: callback absent</span><span class="pill bad">reachable: JSON disables callbacks</span><span class="pill bad">written: no progress records</span></div></div>-<div class="card"><h3>Transcription progress</h3><p class="plain">Indicate work started and completed without inventing numerical progress.</p><pre>{"type":"progress","phase":"transcription","model":"small",- "status":"started"}-{"type":"progress","phase":"transcription","model":"small",- "status":"completed"}</pre><p>Progress records are individual valid JSON lines on stderr. Other stderr diagnostics remain allowed. The terminal stdout result is emitted once. Failure never emits a completed transcription event.</p><span class="cite">whisper/transcribe.ts:488,512-515; whisper/parakeet.ts:294-304; whisper/sherpa.ts:397-413,445. Plain fallback diagnostics: commands/transcribe.ts:370.</span><div class="states"><span class="pill warn">exists: text callbacks</span><span class="pill bad">reachable: JSON disabled</span><span class="pill bad">written: no typed records</span></div></div></section>-<section><h2>How it says no</h2><table><tr><th>Signal</th><th>Meaning and response</th></tr><tr><td>detectedLanguage:null</td><td>No actual automatic inference was reported, including explicit language, English-only model, or an engine without detection. Never infer language from a model label.</td></tr><tr><td>totalBytes:null</td><td>Response has no trustworthy size. Show bytes or indeterminate progress.</td></tr><tr><td>ok:false / nonzero exit</td><td>Operation failed. Diagnostic stderr may explain why. No completion event is evidence of success without the terminal result.</td></tr><tr><td>Progress line without type</td><td>Not part of this progress contract. Consumers filter diagnostics separately.</td></tr></table></section>-<section><h2>Decisions approved</h2><ol><li>detectedLanguage means real automatic detection. Explicit --language and English-only models return null.</li><li>stderr permits diagnostics alongside progress; every progress line is valid JSON with type.</li><li>model reports the actual resolved model. The file stays Word[].</li><li>Transcription progress is phase-only. Download progress reports real bytes with a nullable total.</li><li>--no-runtime-install requires an existing Whisper runtime on all paths, including auto fallback. Model downloads remain allowed. No prior opt-out exists in the inspected CLI source; ensureWhisper owns this policy.</li></ol></section>-<section><h2>Coverage, honestly</h2><p><b>Audited:</b> CLI producer, transfer pipeline, native JSON writer and logger, current terminal/file paths. Installed CLI help executed.</p><p><b>Trusting:</b> arbitrary environment-selected Whisper versions are not pinned to the inspected upstream checkout.</p><p><b>Not exercised:</b> native audio inference, new progress writer and external live consumer. These are contract findings, not execution proof.</p></section>-<section><h2>What would prove this page wrong</h2><ul><li>A public transcribe invocation with a native fixture that emits detection only on stderr must decode automatically and return its language.</li><li>Explicit language and English-only models must return null even if native JSON reports a language.</li><li>Download callbacks must observe actual chunks, including unknown totals, and stdout must parse as one result while stderr records parse independently.</li><li>A switched multilingual model must be the model reported in the final result.</li></ul></section></main></body></html>\ No newline at end of filediff --git a/docs/plans/2026-09-26-image-thumbnails.md b/docs/plans/2026-09-26-image-thumbnails.mddeleted file mode 100644index 5dd345133e..0000000000--- a/docs/plans/2026-09-26-image-thumbnails.md+++ /dev/null@@ -1,49 +0,0 @@-# Bounded timeline JPEG thumbnails--Status: validating. Local only; PR publication authorized, merge/release excluded.-Risk tier 3: image processing across the project file-serving boundary.--## Evidence and goal--Base: main 640e99043, isolated worktree. Timeline image strips request original 2560x1920 photos but budget them as 240x135. A frozen local project exposes 43 original JPEGs in its timeline. No private media will be committed or uploaded.--A client-side resizing experiment passed 35 tests and reduced retained pixel dimensions, but three-run cold-load readiness increased from a median 2.47s to about 3.8s. Offscreen encoding and bitmap resizing did not remove this regression. Reject that approach.--Deliver bounded JPEG thumbnail responses to the existing scheduler, preserving original composition assets and export behavior. Require before/after browser evidence, correct aspect, no missing thumbnails, no material startup regression, cache invalidation, cancellation, and focused negative-path tests before publishing.--## Reviewed plan--1. Add a fixed-size JPEG route using existing project resolution/path containment and Sharp (already a CLI dependency). No arbitrary remote URLs, requested dimensions or output paths. Limit input size/pixels and concurrent work. Keep a bounded in-memory cache, invalidate on file stat changes, deduplicate concurrent requests.-2. Route only same-origin local preview JPEGs through it. Preserve other image types and external sources. Retain scheduler ownership and account for actual thumbnail pixels. Fall back to original sources on unsupported/unavailable thumbnail endpoints.-3. Test unknown projects, traversal/symlink escapes, non-images, corrupt/oversized files, concurrent requests, changed assets and HTTP validation. Test client fallback and cancellation.-4. Repeat frozen-project browser measurements and capture the actual component using synthetic public media. Run types, focused tests, lint/format and changed-file audit; review complete diff.--## Invariants and review--No user composition mutations, export substitution, private uploads or new remote processing. Reuse existing safe path resolution; reject traversal before opening a source. Read bounded input into memory so asynchronous processing does not reopen a retargetable path. Decoder metadata must confirm JPEG; reject other formats despite suffix. Cache is per API host, bounded by bytes and entries, includes file identity, and dies with host. Sharp failures return a bounded error and the client preserves original-image behavior. Cancellation must not leak object URLs. Avoid claiming decoded-pixel estimates equal process RSS. All work is reversible by reverting the PR; no data migration or persisted thumbnail artifacts.--## Non-goals--Photo lookahead, video preloading, PNG/WebP/GIF/SVG conversion, full-resolution rendering changes, server-side remote fetches, and general image transformation APIs are separate work.--## Validation log--Pending implementation and end-to-end comparison. Native dependency loading must be verified in supported CI hosts before merge.--### Measurements and implementation review--Three browser runs per variant, Chrome 147 headless at 1280x720, fixed composition/media, same Vite server and original/changed component alternated. Readiness is the harness threshold of at least 147 mounted timeline images decoded; it is not time-to-first-frame. Runtime clock was read from the actual composition player, after clicking Studio Play. Playback samples last ten seconds. Native-image dimensions are a resource-size estimate; summed Chrome process RSS is a separate noisy measurement.--| Median | Original | Server thumbnails |-| --- | ---: | ---: |-| Readiness | 2342 ms | 2418 ms |-| RAF callbacks / ten seconds | 579 | 593 |-| Largest RAF gap | 208 ms | 58 ms |-| Gaps above 50 ms | 3 | 1 |-| Chrome process RSS | 2205 MiB | 2239 MiB |--All three runs had 52 unique loaded timeline sources. Their decoded-pixel estimate was 956 MiB before and 4.4 MiB after. This is not a measured RAM reduction: RSS did not improve. Startup differs by 76 ms (3.2%); do not claim startup speedup. Frame pacing improved in these samples; machine load remains a limitation, and the measurements do not prove sustained whole-film FPS gains. The first cold server-cache sample in an earlier series took 2903 ms; cached samples took 2657 and 2519 ms. Composition photo downloads remain unchanged.--Public evidence uses a synthetic test chart in the real ImageThumbnail component, with original and thumbnail images at identical display size. User media stays local. Sharp sizing/input-limit semantics checked against https://sharp.pixelplumbing.com/api-resize/ and https://sharp.pixelplumbing.com/api-constructor/.--Review corrections: rejected client resize startup regression; bounded server work/cache and input sizes; preserved non-JPEG/external sources and old-server fallback; extracted path validation to lower route complexity; kept lockfile changes limited to the existing Sharp dependency mapping. Final local validation: 32 client/scheduler tests and 13 server/coordinator tests pass; Studio and studio-server type checks pass; lint/format and changed-file audit pass (duplication warnings remain). Server build passes. Implementation review additionally rejects non-JPEG magic bytes before invoking native decoding. PR CI and cross-platform native dependency checks remain pending.diff --git a/scripts/check-no-main-deletions.mjs b/scripts/check-no-main-deletions.mjsindex 9ba18a9216..5c814ae978 100644--- a/scripts/check-no-main-deletions.mjs+++ b/scripts/check-no-main-deletions.mjs@@ -42,6 +42,9 @@ const STORYBOARD_VIEW_REASON =const SIMULATED_CURSOR_REASON ="owner-directed removal of simulated-cursor; the Cursors section's new pointer animations replace it";+const DESIGN_NOTES_REASON =+ "plan and contract notes are working notes kept out of the repo; docs/contracts/ and docs/plans/ are gitignored";+export const ALLOWED_DELETIONS = new Map([["docs/public/catalog/vendor/BufferGeometryUtils.json",@@ -1127,6 +1130,11 @@ export const ALLOWED_DELETIONS = new Map(["packages/studio-server/src/helpers/atomicFile.test.ts","its tests moved with it to packages/core/src/atomicFile.test.ts",],+ ["docs/contracts/2026-10-01-timeline-filmstrip.html", DESIGN_NOTES_REASON],+ ["docs/contracts/2026-10-02-ghost-lane-membership.html", DESIGN_NOTES_REASON],+ ["docs/contracts/2026-10-02-thumbnail-document-lifetime.html", DESIGN_NOTES_REASON],+ ["docs/contracts/2026-10-05-transcribe-language-progress.html", DESIGN_NOTES_REASON],+ ["docs/plans/2026-09-26-image-thumbnails.md", DESIGN_NOTES_REASON],]);export function parseBase(argv, fallback = "origin/main") {