Skip to content

Commit 67dbcf7

Browse files
feat(studio): preview timeline track insertion (#4907)
* feat(studio): preview new tracks at drop boundaries * fix(studio): preserve group ownership across overlapping moves * refactor(studio): share timeline drop decisions and fixtures * fix(studio): open an empty audio zone below visual tracks * fix(studio): cancel thumbnails when project pages leave * refactor(studio): share thumbnail regression setup * test(studio): gate thumbnail socket release in browser CI * chore(studio): keep optimistic revision comments within ratchet * fix(studio): pin regression proxy requests to its backend * test(studio): bound the proxy origin probe * test(studio): probe proxy origin through the ready document
1 parent f2eb6d9 commit 67dbcf7

50 files changed

Lines changed: 2278 additions & 290 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -958,7 +958,7 @@ jobs:
958958
node packages/studio/tests/e2e/perf-ratchet.mjs check \
959959
packages/studio/tests/e2e/perf-ceilings.json studio-open /tmp/studio-open-counts.json \
960960
/tmp/base-perf-ceilings.json
961-
- name: Measure the fade handle tabs and click every Renders select
961+
- name: Check fade handles, render selects and thumbnail connection release
962962
if: success() || failure()
963963
run: |
964964
set -euo pipefail
@@ -973,12 +973,14 @@ jobs:
973973
echo "FAIL: studio dev server did not start on port 5316"
974974
exit 1
975975
fi
976-
# Both checks run even when the first fails.
976+
# All checks run even when an earlier one fails.
977977
rc=0
978978
STUDIO_URL="http://localhost:5316/#project/fade-handles" \
979979
node packages/studio/tests/e2e/fade-handles.mjs || rc=1
980980
STUDIO_URL="http://localhost:5316/#project/fade-handles?tab=renders" \
981981
node packages/studio/tests/e2e/render-selects.mjs || rc=1
982+
STUDIO_URL="http://localhost:5316/" \
983+
node packages/studio/tests/e2e/thumbnail-save.mjs || rc=1
982984
exit "$rc"
983985
- name: Measure the caret of a text edited in place
984986
if: success() || failure()
Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
<!doctype html>
2+
<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>
3+
:root{color-scheme:light dark;
4+
--bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;
5+
--go:#178a5a;--go-bg:#e8f6ee;--warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;
6+
--mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}
7+
@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;
8+
--go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;--bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}
9+
*{box-sizing:border-box}
10+
body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}
11+
.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}
12+
header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}
13+
header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}
14+
.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}
15+
.strip .sep{opacity:.5}
16+
.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}
17+
.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}
18+
.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}
19+
.pill b{font-size:13px}
20+
section{margin-top:56px}
21+
h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}
22+
.sub{color:var(--dim);margin:0 0 18px;font-size:15px}
23+
.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}
24+
.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}
25+
.breath b{color:var(--go)}
26+
.plain{color:var(--dim);font-size:15px;margin:0 0 10px}
27+
.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}
28+
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}
29+
code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}
30+
.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}
31+
.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}
32+
table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}
33+
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}
34+
td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}
35+
tr:last-child td{border-bottom:0}
36+
td.k{font:13px var(--mono);white-space:nowrap}
37+
.decision{border-left:4px solid var(--info)}
38+
.decision h3{margin:0 0 8px;font-size:17px}
39+
.decision .ask{color:var(--info);font-weight:600}
40+
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}
41+
blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}
42+
ul,ol{padding-left:22px}li{margin:6px 0}
43+
.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}
44+
.flow span{border:1px solid var(--line);padding:12px;border-radius:8px}
45+
footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}
46+
</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>
47+
<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>
48+
<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>
49+
<section><h2>The contract, per boundary</h2>
50+
<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 }) =&gt; ({
51+
element,
52+
start: updates.start,
53+
track: operation === "timing" ? undefined : updates.track,
54+
}))</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>
55+
<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(
56+
original,
57+
target,
58+
toAuthoredStart(change.element, change.start),
59+
change.element.duration,
60+
change.track,
61+
)</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>
62+
<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 };
63+
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>
64+
<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>
65+
<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>
66+
<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>
67+
<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>
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
<!doctype html>
2+
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Thumbnail document lifetime</title><style>
3+
:root{color-scheme:light dark;
4+
--bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;
5+
--go:#178a5a;--go-bg:#e8f6ee;--warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;
6+
--mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}
7+
@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;
8+
--go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;--bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}
9+
*{box-sizing:border-box}
10+
body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}
11+
.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}
12+
header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}
13+
header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}
14+
.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}
15+
.strip .sep{opacity:.5}
16+
.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}
17+
.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}
18+
.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}
19+
.pill b{font-size:13px}
20+
section{margin-top:56px}
21+
h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}
22+
.sub{color:var(--dim);margin:0 0 18px;font-size:15px}
23+
.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}
24+
.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}
25+
.breath b{color:var(--go)}
26+
.plain{color:var(--dim);font-size:15px;margin:0 0 10px}
27+
.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}
28+
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}
29+
code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}
30+
.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}
31+
.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}
32+
table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}
33+
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}
34+
td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}
35+
tr:last-child td{border-bottom:0}
36+
td.k{font:13px var(--mono);white-space:nowrap}
37+
.decision{border-left:4px solid var(--info)}
38+
.decision h3{margin:0 0 8px;font-size:17px}
39+
.decision .ask{color:var(--info);font-weight:600}
40+
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}
41+
blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}
42+
ul,ol{padding-left:22px}li{margin:6px 0}
43+
.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}
44+
.flow span{border:1px solid var(--line);padding:12px;border-radius:8px}
45+
footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}
46+
</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>
47+
<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>
48+
<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>
49+
<section><h2>The verified boundaries</h2><div class="card"><h3>Scheduler owns work</h3><pre>entry.controller = new AbortController();
50+
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>
51+
<div class="card"><h3>Abort and retain</h3><pre>entry.preempted = true;
52+
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>
53+
<div class="card"><h3>The receiving HTTP route</h3><pre>await thumbnailGenerationCoordinator.acquire(
54+
cachePath, c.req.raw.signal, async (signal) =&gt; adapter.generateThumbnail({ signal, ... })
55+
)</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>
56+
<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>
57+
<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>
58+
<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>
59+
<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>

‎packages/studio/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@
7878
"test:edit-accuracy": "bun tests/e2e/edit-accuracy/run.mjs",
7979
"test:filmstrip-controls": "node tests/e2e/filmstrip-controls.mjs",
8080
"test:webmcp-edit-loop": "node tests/e2e/webmcp-edit-loop.mjs",
81+
"test:thumbnail-save": "node tests/e2e/thumbnail-save.mjs",
8182
"test:timeline-virtualization": "TIMELINE_ROW_VIRTUALIZATION=on TIMELINE_ELEMENT_COUNT=50000 node tests/e2e/timeline-virtualization.mjs",
8283
"test:watch": "vitest",
8384
"report:sdk-cutover": "bun src/utils/sdkCutoverPolicy.report.ts",

‎packages/studio/src/hooks/timelineEditingHelpers.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,7 @@ export function buildTimelineMoveTimingPatch(
238238
start: number,
239239
duration: number,
240240
track?: number,
241+
audioGroup?: null,
241242
): string {
242243
if (!Number.isFinite(start) || !Number.isFinite(duration)) {
243244
console.warn(
@@ -257,6 +258,12 @@ export function buildTimelineMoveTimingPatch(
257258
value: formatTimelineAttributeNumber(track),
258259
});
259260
}
261+
if (audioGroup === null)
262+
patched = applyPatchByTarget(patched, target, {
263+
type: "attribute",
264+
property: "data-audio-group",
265+
value: null,
266+
});
260267
// Content-driven duration: sync data-duration to the furthest clip end read
261268
// from the PATCHED SOURCE (raw data-duration), so it grows if a clip moved
262269
// past the end and shrinks if the furthest clip moved left. Measured from the

‎packages/studio/src/hooks/timelineMoveAdapter.test.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,18 @@ describe("persistTimelineMoveEditsAtomically", () => {
6868
});
6969
});
7070

71+
it("carries explicit detachment through the atomic move", async () => {
72+
const edit = {
73+
element: { ...element("voice", 1), audioGroup: "group" },
74+
updates: { start: 1, track: 0, audioGroup: null },
75+
};
76+
const handle = await runMove([edit], "move", "track-insert");
77+
expect(handle).toHaveBeenCalledWith(
78+
[{ element: edit.element, start: 1, track: 0, audioGroup: null }],
79+
{ coalesceKey: "move" },
80+
);
81+
});
82+
7183
it("rejects without retrying individual members when the atomic batch fails", async () => {
7284
const failure = new Error("batch failed");
7385
const handleTimelineGroupMove = vi.fn().mockRejectedValue(failure);

0 commit comments

Comments
 (0)