Skip to content

Commit 0b1f597

Browse files
feat(studio): give timeline clips a Filmstrip name band (#4897)
* docs(studio): map filmstrip clip rendering contract * feat(studio): give timeline clips a separate filmstrip name band * test(studio): require the filmstrip picture wrapper * fix(studio): keep fallback clip warnings clear of menu badges * fix(studio): reserve clip text space beside status badges * fix(studio): separate clip FX and fade hit areas * fix(studio): separate clip tool pointer targets * fix(studio): reserve FX space without lowering fades * refactor(studio): trim fade geometry measurement * test(studio): refresh fade target after closing FX menu * test(studio): collapse keyframe lanes before pointer witness * test(studio): register filmstrip control browser gate
1 parent 5aa3c8f commit 0b1f597

15 files changed

Lines changed: 593 additions & 96 deletions
Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
<!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>
2+
:root{color-scheme:light dark;
3+
--bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;
4+
--go:#178a5a;--go-bg:#e8f6ee;--warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;
5+
--mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}
6+
@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;
7+
--go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;--bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}
8+
*{box-sizing:border-box}
9+
body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}
10+
.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}
11+
header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}
12+
header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}
13+
.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}
14+
.strip .sep{opacity:.5}
15+
.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}
16+
.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}
17+
.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}
18+
.pill b{font-size:13px}
19+
section{margin-top:56px}
20+
h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}
21+
.sub{color:var(--dim);margin:0 0 18px;font-size:15px}
22+
.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}
23+
.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}
24+
.breath b{color:var(--go)}
25+
.plain{color:var(--dim);font-size:15px;margin:0 0 10px}
26+
.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}
27+
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}
28+
code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}
29+
.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}
30+
.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}
31+
table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}
32+
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}
33+
td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}
34+
tr:last-child td{border-bottom:0}
35+
td.k{font:13px var(--mono);white-space:nowrap}
36+
.decision{border-left:4px solid var(--info)}
37+
.decision h3{margin:0 0 8px;font-size:17px}
38+
.decision .ask{color:var(--info);font-weight:600}
39+
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}
40+
blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}
41+
ul,ol{padding-left:22px}li{margin:6px 0}
42+
.mermaid{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px;margin:14px 0;overflow:auto}
43+
.mermaid svg{max-width:100%}
44+
footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}
45+
</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>
46+
<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>
47+
<section><h2>Where the value travels</h2><div class="mermaid">flowchart LR
48+
A[App or host] --> B[TimelinePane] --> C[TimelineClip]
49+
C --> D[renderClipChildren]
50+
D --> E[useRenderClipContent]
51+
E --> F[Thumbnail components]
52+
G[Host CSS overrides] --> C
53+
classDef audited fill:#e8f6ee,stroke:#178a5a,color:#0f3d28
54+
class A,B,C,D,E,F,G audited
55+
</div><p class="sub">Source reachability is audited. No running build has been exercised.</p></section>
56+
<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)
57+
58+
if (!pid) return null;
59+
60+
return createElement(CompositionThumbnail, {
61+
previewUrl: buildProjectApiPath(pid, `/preview/comp/${encodePreviewPath(compSrc)}`),
62+
label: &quot;&quot;,
63+
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 === &quot;labeled&quot;;
64+
{showLabel &amp;&amp; &lt;span className=&quot;timeline-clip__label&quot;&gt;{displayLabel}&lt;/span&gt;}
65+
66+
&lt;div
67+
className=&quot;absolute inset-0 overflow-hidden&quot;
68+
style={{ borderRadius: &quot;inherit&quot;, pointerEvents: &quot;none&quot; }}
69+
&gt;</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));
70+
const frameCount = measured ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
71+
72+
// CompositionThumbnail rendered image class:
73+
className=&quot;absolute inset-0 h-full w-full object-contain&quot;</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;
74+
--timeline-clip-audio-radius: 21px;
75+
76+
clipRadius: &quot;var(--timeline-clip-radius)&quot;,
77+
78+
.timeline-clip.is-selected {
79+
outline: 1.5px solid var(--timeline-clip-selection);
80+
outline-offset: -1.5px;
81+
}</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>
82+
<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>
83+
<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>
84+
<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>
85+
<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">
86+
try {
87+
const m = await import("https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs");
88+
const dark = matchMedia("(prefers-color-scheme: dark)").matches;
89+
m.default.initialize({ startOnLoad: false, theme: dark ? "dark" : "neutral", securityLevel: "loose",
90+
themeVariables: { fontFamily: "ui-monospace, Menlo, monospace", fontSize: "13px" } });
91+
await m.default.run({ querySelector: ".mermaid" });
92+
} catch (e) {
93+
for (const el of document.querySelectorAll(".mermaid")) {
94+
const pre = document.createElement("pre"); pre.textContent = el.textContent.trim(); el.replaceWith(pre);
95+
}
96+
}
97+
</script>
98+
</body></html>

‎packages/studio/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@
7676
"typecheck": "tsc --noEmit",
7777
"test": "vitest run",
7878
"test:edit-accuracy": "bun tests/e2e/edit-accuracy/run.mjs",
79+
"test:filmstrip-controls": "node tests/e2e/filmstrip-controls.mjs",
7980
"test:webmcp-edit-loop": "node tests/e2e/webmcp-edit-loop.mjs",
8081
"test:timeline-virtualization": "TIMELINE_ROW_VIRTUALIZATION=on TIMELINE_ELEMENT_COUNT=50000 node tests/e2e/timeline-virtualization.mjs",
8182
"test:watch": "vitest",

‎packages/studio/src/player/components/ClipBadges.tsx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,21 +44,21 @@ export const ClipBadges = memo(function ClipBadges({
4444
};
4545
return (
4646
<span
47-
className="pointer-events-none absolute right-1.5 top-0.5 z-[3] flex gap-1"
47+
className="pointer-events-none absolute right-1.5 top-0.5 z-[31] flex max-w-[calc(100%-12px)] gap-1 overflow-hidden"
4848
data-testid="clip-badges"
4949
>
5050
{volume && (
5151
<span
52-
className={`${BADGE_CLASS} border-white/20 text-white/90`}
52+
className={`${BADGE_CLASS} min-w-0 overflow-hidden border-white/20 text-white/90`}
5353
title={volume}
5454
data-badge="volume"
5555
>
5656
<SpeakerGlyph muted={volume === "Muted"} />
57-
{volume === "Muted" ? null : <span>{volume}</span>}
57+
{volume === "Muted" ? null : <span className="truncate">{volume}</span>}
5858
</span>
5959
)}
6060
<span
61-
className={`${BADGE_CLASS} pointer-events-auto cursor-pointer ${hasEffects ? FX_ON : FX_OFF}`}
61+
className={`${BADGE_CLASS} pointer-events-auto shrink-0 cursor-pointer ${hasEffects ? FX_ON : FX_OFF}`}
6262
title={hasEffects ? effects.join(" · ") : "No effects"}
6363
data-badge="fx"
6464
data-fx-active={hasEffects ? "true" : "false"}
Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
// @vitest-environment happy-dom
2+
3+
import React, { act } from "react";
4+
import { compile } from "tailwindcss";
5+
import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
6+
import { loadStylesheet, STYLES_DIR } from "../../styles/styleSources";
7+
import { cleanupMounted, trackedRoot } from "../../components/ui/mountHost.testHelpers";
8+
import { TimelineClip } from "./TimelineClip";
9+
import { renderClipChildren } from "./timelineClipChildren";
10+
import { usePlayerStore, type TimelineElement } from "../store/playerStore";
11+
12+
let css: string;
13+
14+
beforeAll(async () => {
15+
css = (
16+
await compile('@import "tailwindcss";\n@import "./theme.css";\n@import "./components.css";', {
17+
base: STYLES_DIR,
18+
loadStylesheet: async (id, base) => loadStylesheet(id, base),
19+
})
20+
).build(["absolute", "inset-0", "overflow-hidden"]);
21+
});
22+
23+
afterEach(() => {
24+
cleanupMounted();
25+
usePlayerStore.getState().setLintFindingsByElement(new Map());
26+
document.body.innerHTML = "";
27+
});
28+
29+
function render(tag: string, overrides: Partial<TimelineElement> = {}, picture = true) {
30+
const host = document.createElement("div");
31+
document.body.append(host);
32+
const root = trackedRoot(host);
33+
const element: TimelineElement = {
34+
id: "clip",
35+
label: "City",
36+
tag,
37+
start: 0,
38+
duration: 1,
39+
track: 0,
40+
...overrides,
41+
};
42+
const renderContent = picture ? () => <img alt="" /> : undefined;
43+
act(() => {
44+
root.render(
45+
<TimelineClip
46+
el={element}
47+
pps={200}
48+
clipY={0}
49+
clipHeight={42}
50+
isSelected
51+
isHovered={false}
52+
hasCustomContent={picture}
53+
capabilities={{ canMove: true, canTrimStart: true, canTrimEnd: true }}
54+
isComposition={false}
55+
onHoverStart={vi.fn()}
56+
onHoverEnd={vi.fn()}
57+
onClick={vi.fn()}
58+
onDoubleClick={vi.fn()}
59+
>
60+
{renderClipChildren(
61+
element,
62+
{ clip: "#222", label: "#fff", accent: "#fff" },
63+
renderContent,
64+
undefined,
65+
)}
66+
</TimelineClip>,
67+
);
68+
});
69+
return host;
70+
}
71+
72+
describe("Filmstrip clips", () => {
73+
it.each(["video", "img"])("reserves a 15px name band above %s pictures", (tag) => {
74+
const host = render(tag);
75+
const name = host.querySelector(".timeline-clip__name");
76+
const picture = host.querySelector(".timeline-clip__content");
77+
expect(name?.textContent).toBe("City");
78+
expect(picture).not.toBeNull();
79+
expect(picture?.querySelector("img")).not.toBeNull();
80+
expect(css).toMatch(/--timeline-clip-band-height:\s*15px;/);
81+
expect(css).toMatch(
82+
/\.timeline-clip:not\(\.is-audio\) \.timeline-clip__label\s*\{[^}]*height:\s*var\(--timeline-clip-band-height\)/,
83+
);
84+
expect(css).toMatch(
85+
/\.timeline-clip:not\(\.is-audio\) \.timeline-clip__content\s*\{[^}]*top:\s*var\(--timeline-clip-band-height\);[^}]*border-top-left-radius:\s*0;/,
86+
);
87+
});
88+
89+
it("keeps applied-state badges above the opaque name band", () => {
90+
const host = render("video", { hasAudio: true, volume: 1.8 });
91+
expect(host.querySelector('[data-badge="volume"]')?.textContent).toBe("180%");
92+
const badges = host.querySelector('[data-testid="clip-badges"]');
93+
expect(badges?.classList.contains("z-[31]")).toBe(true);
94+
expect(badges?.classList.contains("max-w-[calc(100%-12px)]")).toBe(true);
95+
expect(badges?.classList.contains("overflow-hidden")).toBe(true);
96+
expect(badges?.parentElement?.classList.contains("timeline-clip__label")).toBe(true);
97+
expect(css).toMatch(
98+
/\.timeline-clip:not\(\.is-audio\) \.timeline-clip__name\s*\{[^}]*flex:\s*1;[^}]*min-width:\s*0;[^}]*overflow:\s*hidden;/,
99+
);
100+
expect(css).toMatch(
101+
/\.timeline-clip:not\(\.is-audio\) \.timeline-clip__label\s*\{[^}]*z-index:\s*auto;/,
102+
);
103+
});
104+
105+
it("keeps fallback lint warnings clear of the name band and menu badge", () => {
106+
usePlayerStore
107+
.getState()
108+
.setLintFindingsByElement(new Map([["clip", { count: 1, messages: ["Lint warning"] }]]));
109+
const host = render("div", { duration: 0.3 }, false);
110+
const name = host.querySelector(".timeline-clip__name");
111+
const warning = host.querySelector<HTMLElement>('[title="Lint warning"]');
112+
expect(warning).not.toBeNull();
113+
expect(warning?.style.bottom).toBe("7px");
114+
expect(warning?.style.top).toBe("");
115+
expect(css).toMatch(/\.timeline-clip__timecode\s*\{[^}]*right:\s*16px;/);
116+
expect(
117+
(name?.compareDocumentPosition(warning!) ?? 0) & Node.DOCUMENT_POSITION_FOLLOWING,
118+
).toBeTruthy();
119+
expect(css).toMatch(
120+
/\.timeline-clip:not\(\.is-audio\) \.timeline-clip__label\s*\{[^}]*z-index:\s*auto;/,
121+
);
122+
});
123+
124+
it.each([0.02, 0.295])(
125+
"keeps the name band without badge targets on a narrow visual clip (%ss)",
126+
(duration) => {
127+
const host = render("video", { duration, hasAudio: true, volume: 1.8 });
128+
expect(host.querySelector(".timeline-clip__name")?.textContent).toBe("City");
129+
expect(host.querySelector('[data-testid="clip-badges"]')).toBeNull();
130+
expect(css).toMatch(/padding:\s*0 min\(6px,\s*25%\);/);
131+
expect(css).toMatch(/padding-left:\s*min\(8px,\s*25%\);/);
132+
},
133+
);
134+
135+
it("lets audio keep its full-height content and pill radius", () => {
136+
const host = render("audio");
137+
const clip = host.querySelector(".timeline-clip");
138+
const picture = host.querySelector(".timeline-clip__content");
139+
expect(clip?.classList.contains("is-audio")).toBe(true);
140+
expect(picture?.classList.contains("inset-0")).toBe(true);
141+
expect(css).toMatch(/--timeline-clip-audio-radius:\s*21px;/);
142+
expect(clip instanceof HTMLElement && clip.style.borderRadius).toBe(
143+
"var(--timeline-clip-audio-radius)",
144+
);
145+
});
146+
147+
it("exports a single 1px selection ring around a 12px visual clip", () => {
148+
const clip = render("video").querySelector(".timeline-clip");
149+
expect(clip?.classList.contains("is-selected")).toBe(true);
150+
expect(css).toMatch(/--timeline-clip-radius:\s*12px;/);
151+
expect(css).toMatch(
152+
/\.timeline-clip\.is-selected,\s*\.timeline-clip\[data-active\]\.is-selected\s*\{[^}]*outline:\s*1px solid var\(--timeline-clip-selection\);[^}]*outline-offset:\s*0;/,
153+
);
154+
expect(css).toMatch(/\.timeline-clip:not\(\.is-audio\)\s*\{\s*border-width:\s*0;/);
155+
});
156+
});

0 commit comments

Comments
 (0)