@1agh/maude 0.39.0 → 0.40.0

package/apps/studio/test/timeline-parse.test.ts

@@ -0,0 +1,127 @@
+// timeline-parse — DDR-148 Timeline sequence/keyframe parser.
+// Pure regex parse of a video-comp's sequence structure + interpolate windows.
+
+import { describe, expect, test } from 'bun:test';
+
+import { parseCompTimeline } from '../client/panels/timeline-parse.js';
+
+const COMP = `
+const A = 45;
+const XF = 15;
+const B = 60;
+const Intro = () => {
+  const frame = useCurrentFrame();
+  const o = interpolate(frame, [0, 14], [0, 1]);
+  const y = interpolate(frame, [10, 30], [24, 0]);
+  return <AbsoluteFill style={{ opacity: o }} />;
+};
+const Payoff = () => {
+  const frame = useCurrentFrame();
+  const s = interpolate(frame, [4, 20], [0.8, 1]);
+  return <AbsoluteFill style={{ transform: 's' }} />;
+};
+function Movie() {
+  return (
+    <TransitionSeries>
+      <TransitionSeries.Sequence durationInFrames={A}><Intro /></TransitionSeries.Sequence>
+      <TransitionSeries.Transition presentation={fade()} timing={linearTiming({ durationInFrames: XF })} />
+      <TransitionSeries.Sequence durationInFrames={B}><Payoff /></TransitionSeries.Sequence>
+    </TransitionSeries>
+  );
+}
+`;
+
+describe('parseCompTimeline', () => {
+  test('parses TransitionSeries sequences with const durations + overlap math', () => {
+    const r = parseCompTimeline(COMP, 90);
+    expect(r.total).toBe(90);
+    expect(r.sequences).toHaveLength(2);
+    expect(r.sequences[0]).toMatchObject({ label: 'Intro', from: 0, duration: 45 });
+    // Payoff starts at 45 - 15 (the transition overlaps back) = 30.
+    expect(r.sequences[1]).toMatchObject({ label: 'Payoff', from: 30, duration: 60 });
+  });
+
+  test('attributes interpolate windows to their sequence, offset to absolute frames', () => {
+    const r = parseCompTimeline(COMP, 90);
+    // Intro's [0,14] + [10,30] stay at from=0.
+    expect(r.sequences[0].keyframes).toEqual([
+      { from: 0, to: 14 },
+      { from: 10, to: 30 },
+    ]);
+    // Payoff's [4,20] is offset by its from=30 → [34,50].
+    expect(r.sequences[1].keyframes).toEqual([{ from: 34, to: 50 }]);
+  });
+
+  test('plain <Sequence from={M} durationInFrames={N}> uses absolute from', () => {
+    const src =
+      'function C(){ return <><Sequence from={20} durationInFrames={40}><Foo/></Sequence></>; }';
+    const r = parseCompTimeline(src, 60);
+    expect(r.sequences[0]).toMatchObject({ label: 'Foo', from: 20, duration: 40 });
+  });
+
+  test('a non-comp / unparseable source yields no sequences (scrub-only)', () => {
+    expect(parseCompTimeline('function C(){ return <div/>; }', 30).sequences).toEqual([]);
+    expect(parseCompTimeline('', 0).sequences).toEqual([]);
+  });
+
+  test('the comp meta total wins over the derived span', () => {
+    const r = parseCompTimeline(COMP, 200);
+    expect(r.total).toBe(200);
+  });
+
+  test('an <Audio> bed becomes its own row spanning the comp (DDR-148 music layer)', () => {
+    const src = `${COMP.replace(
+      '</TransitionSeries>',
+      '</TransitionSeries><Audio src="/.design/assets/music.mp3" />'
+    )}`;
+    const r = parseCompTimeline(src, 90);
+    expect(r.audio).toHaveLength(1);
+    expect(r.audio[0]).toMatchObject({ kind: 'audio', label: 'music.mp3', from: 0, duration: 90 });
+  });
+
+  test('a multi-comp canvas scopes the timeline to the media comp + its total', () => {
+    // Two VideoComps on one canvas: a plain intro (no media) + a reel (has
+    // <Audio>). The parser must show the REEL — its sequences, total, audio.
+    const src = `
+const IT = 40; const RT = 120;
+const Intro = () => <AbsoluteFill/>;
+function Movie(){ return <TransitionSeries><TransitionSeries.Sequence durationInFrames={IT}><Intro/></TransitionSeries.Sequence></TransitionSeries>; }
+const Clip = () => <AbsoluteFill/>;
+function Reel(){ return (<AbsoluteFill><TransitionSeries><TransitionSeries.Sequence durationInFrames={RT}><Clip/></TransitionSeries.Sequence></TransitionSeries><Audio src="/x/song.mp3"/></AbsoluteFill>); }
+export default function Canvas(){ return (<DesignCanvas>
+  <VideoComp component={Movie} durationInFrames={IT} fps={30} width={960} height={540} />
+  <VideoComp component={Reel} durationInFrames={RT} fps={30} width={960} height={540} />
+</DesignCanvas>); }
+`;
+    // The app passes the FIRST comp's duration (the intro, 40) — the parser must
+    // still pick the reel (media) and report its total (120) + audio.
+    const r = parseCompTimeline(src, 40);
+    expect(r.total).toBe(120);
+    expect(r.sequences).toEqual([expect.objectContaining({ label: 'Clip', duration: 120 })]);
+    expect(r.audio).toHaveLength(1);
+    expect(r.audio[0].label).toBe('song.mp3');
+  });
+
+  test('the Timeline scopes to the SELECTED artboard (follows the canvas)', () => {
+    const src = `
+const IT = 40; const RT = 120;
+const Intro = () => <AbsoluteFill/>;
+function Movie(){ return <TransitionSeries><TransitionSeries.Sequence durationInFrames={IT}><Intro/></TransitionSeries.Sequence></TransitionSeries>; }
+const Clip = () => <AbsoluteFill/>;
+function Reel(){ return (<AbsoluteFill><TransitionSeries><TransitionSeries.Sequence durationInFrames={RT}><Clip/></TransitionSeries.Sequence></TransitionSeries><Audio src="/x/song.mp3"/></AbsoluteFill>); }
+export default function Canvas(){ return (<DesignCanvas>
+  <DCArtboard id="intro" width={960} height={540}><VideoComp component={Movie} durationInFrames={IT} fps={30} width={960} height={540} /></DCArtboard>
+  <DCArtboard id="reel" width={960} height={540}><VideoComp component={Reel} durationInFrames={RT} fps={30} width={960} height={540} /></DCArtboard>
+</DesignCanvas>); }
+`;
+    // Selecting the intro artboard shows the INTRO — even though the reel has media.
+    const intro = parseCompTimeline(src, 40, 'intro');
+    expect(intro.total).toBe(40);
+    expect(intro.sequences).toEqual([expect.objectContaining({ label: 'Intro', duration: 40 })]);
+    expect(intro.audio).toHaveLength(0);
+    // Selecting the reel shows the reel + its music.
+    const reel = parseCompTimeline(src, 40, 'reel');
+    expect(reel.total).toBe(120);
+    expect(reel.audio).toHaveLength(1);
+  });
+});

package/apps/studio/test/timeline-snap.test.ts

@@ -0,0 +1,85 @@
+// timeline-snap.test.ts — DDR-150 Task 15 (Polish). The pure snap helpers behind
+// clip move/trim: a dragged edge lands on the nearest second-tick / neighbor edge
+// / playhead within a threshold, and Alt (threshold 0) turns it off.
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  computeSnapTargets,
+  snapFrame,
+  snapThresholdFrames,
+} from '../client/panels/timeline-snap.js';
+
+describe('computeSnapTargets', () => {
+  test('includes 0, comp end, second ticks, neighbor edges, playhead — excludes the moving clip', () => {
+    const targets = computeSnapTargets({
+      fps: 30,
+      totalFrames: 120,
+      clips: [
+        { from: 0, duration: 30 }, // clip 0 — the one being moved (excluded)
+        { from: 45, duration: 30 }, // clip 1 — edges 45 + 75 should appear
+      ],
+      movingIndex: 0,
+      playhead: 88,
+    });
+    expect(targets).toContain(0); // start
+    expect(targets).toContain(120); // comp end
+    expect(targets).toContain(30); // second tick (1s @ 30fps)
+    expect(targets).toContain(60); // second tick (2s)
+    expect(targets).toContain(90); // second tick (3s)
+    expect(targets).toContain(45); // neighbor clip start
+    expect(targets).toContain(75); // neighbor clip end
+    expect(targets).toContain(88); // playhead
+    // the MOVING clip's own edges (0 already a tick; its end 30 is also a tick,
+    // but must not be added as a *clip edge* — dedup keeps it single + sorted)
+    expect(targets).toEqual([...targets].sort((a, b) => a - b));
+    expect(new Set(targets).size).toBe(targets.length); // deduped
+  });
+
+  test('clamps targets to [0, totalFrames]', () => {
+    const targets = computeSnapTargets({
+      fps: 30,
+      totalFrames: 50,
+      clips: [{ from: 40, duration: 40 }], // end 80 is out of range → dropped
+      movingIndex: -1,
+      playhead: 200, // out of range → dropped
+    });
+    expect(Math.max(...targets)).toBeLessThanOrEqual(50);
+    expect(targets).not.toContain(80);
+    expect(targets).not.toContain(200);
+  });
+});
+
+describe('snapFrame', () => {
+  const targets = [0, 30, 45, 60, 90, 120];
+
+  test('snaps to the nearest target within threshold', () => {
+    expect(snapFrame(32, targets, 4)).toBe(30); // 2 away
+    expect(snapFrame(43, targets, 4)).toBe(45); // 2 away
+  });
+
+  test('leaves the candidate unchanged when nothing is in range', () => {
+    expect(snapFrame(52, targets, 4)).toBe(52); // nearest (45/60) is 7/8 away
+  });
+
+  test('picks the CLOSER of two in-range targets', () => {
+    // 47 is 2 from 45 and 13 from 60 → 45.
+    expect(snapFrame(47, targets, 20)).toBe(45);
+  });
+
+  test('threshold 0 (Alt override) never snaps', () => {
+    expect(snapFrame(30, targets, 0)).toBe(30);
+    expect(snapFrame(31, targets, 0)).toBe(31);
+  });
+});
+
+describe('snapThresholdFrames', () => {
+  test('converts an ~8px radius into frames by the row width', () => {
+    // 8px on a 800px row spanning 400 frames → ~4 frames.
+    expect(Math.round(snapThresholdFrames(800, 401, 8))).toBe(4);
+  });
+
+  test('degrades safely on a zero-width row', () => {
+    expect(Number.isFinite(snapThresholdFrames(0, 100))).toBe(true);
+  });
+});

package/apps/studio/test/video-asset.test.ts

@@ -0,0 +1,163 @@
+// POST /_api/asset — DDR-148 video/audio widening of the Phase 23 asset route.
+//
+// Two layers (mirroring asset-api.test.ts):
+//   (1) the pure magic-byte sniff (`sniffAssetType`) — the ONE gate that decides
+//       the stored type AND category (→ which cap applies); a header lie / SVG /
+//       script is caught here;
+//   (2) the streaming POST endpoint (boots a real server) — video/audio happy
+//       path, per-category cap (image 10 MB stays tight; video honors the
+//       MAUDE_ASSET_MAX_VIDEO_BYTES override), content-addressed dedupe.
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { assetCapForCategory, sniffAssetType } from '../api.ts';
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+// ── Minimal valid magic-byte headers (padded so the ≥12-byte sniff has data). ──
+const pad = (header: number[], len = 64): Uint8Array => {
+  const out = new Uint8Array(len);
+  out.set(header, 0);
+  return out;
+};
+const ascii = (s: string): number[] => [...s].map((c) => c.charCodeAt(0));
+
+const MP4 = pad([0, 0, 0, 0x18, ...ascii('ftyp'), ...ascii('isom')]);
+const MOV = pad([0, 0, 0, 0x14, ...ascii('ftyp'), ...ascii('qt  ')]);
+const M4A = pad([0, 0, 0, 0x18, ...ascii('ftyp'), ...ascii('M4A ')]);
+const WEBM = pad([0x1a, 0x45, 0xdf, 0xa3]);
+const MP3_ID3 = pad([...ascii('ID3'), 0x03, 0x00]);
+const MP3_SYNC = pad([0xff, 0xfb, 0x90, 0x00]);
+const WAV = pad([...ascii('RIFF'), 0, 0, 0, 0, ...ascii('WAVE')]);
+const PNG = pad([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const SVG = new TextEncoder().encode('<svg xmlns="http://www.w3.org/2000/svg"><script/></svg>');
+
+describe('video-asset / sniffAssetType (the widened type gate)', () => {
+  test('recognizes video containers by magic bytes', () => {
+    expect(sniffAssetType(MP4)).toEqual({ ext: 'mp4', category: 'video' });
+    expect(sniffAssetType(MOV)).toEqual({ ext: 'mov', category: 'video' });
+    expect(sniffAssetType(WEBM)).toEqual({ ext: 'webm', category: 'video' });
+  });
+
+  test('recognizes audio containers by magic bytes', () => {
+    expect(sniffAssetType(M4A)).toEqual({ ext: 'm4a', category: 'audio' });
+    expect(sniffAssetType(MP3_ID3)).toEqual({ ext: 'mp3', category: 'audio' });
+    expect(sniffAssetType(MP3_SYNC)).toEqual({ ext: 'mp3', category: 'audio' });
+    expect(sniffAssetType(WAV)).toEqual({ ext: 'wav', category: 'audio' });
+  });
+
+  test('images still resolve through the same superset sniff', () => {
+    expect(sniffAssetType(PNG)).toEqual({ ext: 'png', category: 'image' });
+  });
+
+  test('rejects SVG / script / text / empty (no script-bearing vector rides in)', () => {
+    expect(sniffAssetType(SVG)).toBeNull();
+    expect(sniffAssetType(new TextEncoder().encode('not media at all'))).toBeNull();
+    expect(sniffAssetType(new Uint8Array(0))).toBeNull();
+    // "RIFF" without "WAVE" (or "WEBP") must NOT match a media/image type.
+    expect(sniffAssetType(pad([...ascii('RIFF'), 0, 0, 0, 0, ...ascii('AVI ')]))).toBeNull();
+  });
+
+  test('caps: image 10 MB tight, video/audio share the larger cap', () => {
+    expect(assetCapForCategory('image')).toBe(10 * 1024 * 1024);
+    expect(assetCapForCategory('video')).toBeGreaterThan(assetCapForCategory('image'));
+    expect(assetCapForCategory('audio')).toBe(assetCapForCategory('video'));
+  });
+});
+
+describe('video-asset / POST /_api/asset (streaming endpoint)', () => {
+  async function withServer(
+    fn: (port: number, designRoot: string) => Promise<void>,
+    extraEnv?: Record<string, string>
+  ) {
+    const sandbox = makeSandbox();
+    const port = nextPort();
+    const proc = await bootServer(sandbox.root, port, extraEnv);
+    try {
+      await fn(port, sandbox.designRoot);
+    } finally {
+      await killProc(proc);
+    }
+  }
+
+  const postAsset = (port: number, body: Uint8Array) =>
+    fetch(`http://localhost:${port}/_api/asset`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/octet-stream' },
+      body,
+    });
+
+  test('writes valid mp4/mov/webm/mp3/wav/m4a with the sniffed ext', async () => {
+    await withServer(async (port, designRoot) => {
+      for (const [bytes, ext] of [
+        [MP4, 'mp4'],
+        [MOV, 'mov'],
+        [WEBM, 'webm'],
+        [MP3_ID3, 'mp3'],
+        [WAV, 'wav'],
+        [M4A, 'm4a'],
+      ] as const) {
+        const res = await postAsset(port, bytes);
+        expect(res.status).toBe(201);
+        const json = (await res.json()) as { path: string };
+        expect(json.path).toMatch(new RegExp(`^assets/[0-9a-f]{8}\\.${ext}$`));
+        expect(existsSync(join(designRoot, json.path))).toBe(true);
+      }
+    });
+  });
+
+  test('bytes decide the ext, never the (octet-stream) upload header', async () => {
+    await withServer(async (port) => {
+      const res = await postAsset(port, MP4);
+      expect(res.status).toBe(201);
+      const json = (await res.json()) as { path: string };
+      expect(json.path.endsWith('.mp4')).toBe(true);
+    });
+  });
+
+  test('rejects an SVG upload (script-bearing) with 415 even on the media route', async () => {
+    await withServer(async (port) => {
+      expect((await postAsset(port, SVG)).status).toBe(415);
+    });
+  });
+
+  test('honors the MAUDE_ASSET_MAX_VIDEO_BYTES per-file cap (streamed → 413)', async () => {
+    await withServer(
+      async (port) => {
+        const big = new Uint8Array(2048);
+        big.set([0, 0, 0, 0x18, ...ascii('ftyp'), ...ascii('isom')], 0); // valid mp4 head
+        expect((await postAsset(port, big)).status).toBe(413);
+        // A small mp4 under the cap still writes.
+        expect((await postAsset(port, MP4)).status).toBe(201);
+      },
+      { MAUDE_ASSET_MAX_VIDEO_BYTES: '1024' }
+    );
+  });
+
+  test('identical media bytes dedupe to ONE content-addressed file', async () => {
+    await withServer(async (port, designRoot) => {
+      const a = await (await postAsset(port, MP4)).json();
+      const b = await (await postAsset(port, MP4)).json();
+      expect(a.path).toBe(b.path);
+      const files = readdirSync(join(designRoot, 'assets')).filter((f) => !f.startsWith('.tmp-'));
+      expect(files.length).toBe(1);
+    });
+  });
+
+  test('a rejected oversize upload leaves NO temp file behind (clean disk)', async () => {
+    await withServer(
+      async (port, designRoot) => {
+        const big = new Uint8Array(2048);
+        big.set([0, 0, 0, 0x18, ...ascii('ftyp'), ...ascii('isom')], 0);
+        expect((await postAsset(port, big)).status).toBe(413);
+        const assetsDir = join(designRoot, 'assets');
+        const leftover = existsSync(assetsDir)
+          ? readdirSync(assetsDir).filter((f) => f.startsWith('.tmp-'))
+          : [];
+        expect(leftover).toEqual([]);
+      },
+      { MAUDE_ASSET_MAX_VIDEO_BYTES: '1024' }
+    );
+  });
+});

package/apps/studio/test/video-comp-fixture.test.ts

@@ -0,0 +1,50 @@
+// video-comp-fixture — DDR-148 end-to-end build guard (CI-safe, no browser).
+//
+// The heavy render/scrub/export path is verified live via agent-browser + the
+// determinism smoke; here we lock the CI-cheap invariant the whole feature
+// rests on: a real video-comp canvas (the canonical fixture) BUILDS through the
+// production canvas pipeline (buildCanvasModule) with `remotion`,
+// `@remotion/transitions`, and the `fade` presentation externalised to the
+// importmap (RUNTIME_PACKAGES) — never inlined (which would resolve against a
+// non-existent user node_modules on an npm/marketplace install) — and with the
+// <VideoComp> wrapper inlined from @maude/canvas-lib.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+
+import { buildCanvasModule } from '../canvas-build.ts';
+
+const FIXTURE = new URL('./fixtures/video-comp-fixture.tsx', import.meta.url).pathname;
+
+describe('video-comp fixture — production build guard', () => {
+  test('builds through buildCanvasModule with the Remotion runtime externalised', async () => {
+    const src = readFileSync(FIXTURE, 'utf8');
+    const r = await buildCanvasModule(FIXTURE, src);
+    expect(r.js.length).toBeGreaterThan(1000);
+
+    const externals = new Set(
+      [...r.js.matchAll(/from\s*["']([^"'.][^"']*)["']/g)].map((m) => m[1])
+    );
+    // The comp's Remotion imports MUST stay external (importmap → pre-built
+    // /_canvas-runtime bundles), or an end-user install can't resolve them.
+    expect(externals.has('remotion')).toBe(true);
+    expect(externals.has('@remotion/transitions')).toBe(true);
+    expect(externals.has('@remotion/transitions/fade')).toBe(true);
+    expect(externals.has('react')).toBe(true);
+
+    // <VideoComp> (+ the seek-bridge) is inlined from @maude/canvas-lib.
+    expect(r.js).toContain('VideoComp');
+    expect(r.js).toContain('__maude_seek__');
+  });
+
+  test('every Remotion specifier the fixture imports is a known RUNTIME_PACKAGE', async () => {
+    const { RUNTIME_PACKAGES } = await import('../runtime-bundle.ts');
+    const known = new Set<string>(RUNTIME_PACKAGES);
+    const src = readFileSync(FIXTURE, 'utf8');
+    const imported = [...src.matchAll(/from\s*["'](@?remotion[^"']*)["']/g)].map((m) => m[1]);
+    expect(imported.length).toBeGreaterThan(0);
+    for (const spec of imported) {
+      expect(known.has(spec)).toBe(true);
+    }
+  });
+});

package/apps/studio/test/video-comp.test.ts

@@ -0,0 +1,168 @@
+// video-comp — DDR-148 seek-bridge unit coverage.
+//
+// The Remotion Player's actual frame render needs a real browser (rAF, layout,
+// media) — that determinism ("two seeks to frame N → identical pixels") is an
+// agent-browser live check (Task 11). What IS pure + testable here is the seek
+// BRIDGE the capture spine + Timeline panel drive: the comp registry, the
+// clamped seek routing to each Player, and the serializable snapshot. We stand
+// up happy-dom, install the bridge without mounting a Player, register a fake
+// Player handle (a seekTo/pause spy), and assert the routing contract.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+
+import { installMaudeSeekBridge } from '../video-comp.tsx';
+
+interface FakePlayer {
+  seekTo: (frame: number) => void;
+  pause: () => void;
+  seeks: number[];
+  pauses: number;
+}
+
+interface SeekWindow {
+  __maudeVideoComps?: Map<
+    string,
+    {
+      id: string;
+      fps: number;
+      durationInFrames: number;
+      width: number;
+      height: number;
+      ref: { current: FakePlayer | null };
+    }
+  >;
+  __maude_seek__?: (frame: number, opts?: { fps?: number }) => Promise<void>;
+  __maude_comps__?: () => Array<{
+    id: string;
+    fps: number;
+    durationInFrames: number;
+    width: number;
+    height: number;
+  }>;
+}
+
+function makeFakePlayer(): FakePlayer {
+  const p: FakePlayer = {
+    seeks: [],
+    pauses: 0,
+    seekTo(frame) {
+      p.seeks.push(frame);
+    },
+    pause() {
+      p.pauses += 1;
+    },
+  };
+  return p;
+}
+
+function registerComp(
+  id: string,
+  meta: { fps: number; durationInFrames: number; width: number; height: number },
+  player: FakePlayer
+): void {
+  const w = window as unknown as SeekWindow;
+  if (!w.__maudeVideoComps) w.__maudeVideoComps = new Map();
+  w.__maudeVideoComps.set(id, { id, ...meta, ref: { current: player } });
+}
+
+beforeAll(() => {
+  GlobalRegistrator.register();
+});
+
+afterAll(async () => {
+  await GlobalRegistrator.unregister();
+});
+
+beforeEach(() => {
+  const w = window as unknown as SeekWindow;
+  w.__maudeVideoComps = undefined;
+  w.__maude_seek__ = undefined;
+  w.__maude_comps__ = undefined;
+});
+
+describe('video-comp seek bridge', () => {
+  test('installs window.__maude_seek__ + __maude_comps__ idempotently', () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    const seek1 = w.__maude_seek__;
+    const comps1 = w.__maude_comps__;
+    expect(typeof seek1).toBe('function');
+    expect(typeof comps1).toBe('function');
+    installMaudeSeekBridge();
+    // Second install must NOT replace the functions (idempotent).
+    expect(w.__maude_seek__).toBe(seek1);
+    expect(w.__maude_comps__).toBe(comps1);
+  });
+
+  test('__maude_comps__ reflects the live registry (serializable, no functions)', () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    registerComp(
+      'intro',
+      { fps: 30, durationInFrames: 90, width: 640, height: 360 },
+      makeFakePlayer()
+    );
+    const comps = w.__maude_comps__?.() ?? [];
+    expect(comps).toHaveLength(1);
+    expect(comps[0]).toEqual({
+      id: 'intro',
+      fps: 30,
+      durationInFrames: 90,
+      width: 640,
+      height: 360,
+    });
+    // No ref/functions leak into the snapshot.
+    expect(Object.keys(comps[0])).not.toContain('ref');
+  });
+
+  test('seek routes to every registered Player, paused first', async () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    const a = makeFakePlayer();
+    const b = makeFakePlayer();
+    registerComp('a', { fps: 30, durationInFrames: 90, width: 640, height: 360 }, a);
+    registerComp('b', { fps: 24, durationInFrames: 48, width: 320, height: 240 }, b);
+    await w.__maude_seek__?.(30);
+    expect(a.seeks).toEqual([30]);
+    expect(b.seeks).toEqual([30]);
+    expect(a.pauses).toBe(1);
+    expect(b.pauses).toBe(1);
+  });
+
+  test('seek clamps into [0, durationInFrames-1] per comp + rounds', async () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    const a = makeFakePlayer();
+    registerComp('a', { fps: 30, durationInFrames: 90, width: 640, height: 360 }, a);
+    await w.__maude_seek__?.(999); // past the end → clamp to 89
+    await w.__maude_seek__?.(-5); // before the start → clamp to 0
+    await w.__maude_seek__?.(12.6); // fractional → round to 13
+    expect(a.seeks).toEqual([89, 0, 13]);
+  });
+
+  test('two seeks to the same frame issue identical Player calls (determinism contract)', async () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    const a = makeFakePlayer();
+    registerComp('a', { fps: 30, durationInFrames: 90, width: 640, height: 360 }, a);
+    await w.__maude_seek__?.(42);
+    await w.__maude_seek__?.(42);
+    expect(a.seeks).toEqual([42, 42]);
+  });
+
+  test('a Player ref that is not yet ready (null) does not throw', async () => {
+    const w = window as unknown as SeekWindow;
+    installMaudeSeekBridge();
+    if (!w.__maudeVideoComps) w.__maudeVideoComps = new Map();
+    w.__maudeVideoComps.set('pending', {
+      id: 'pending',
+      fps: 30,
+      durationInFrames: 90,
+      width: 640,
+      height: 360,
+      ref: { current: null },
+    });
+    await expect(w.__maude_seek__?.(10)).resolves.toBeUndefined();
+  });
+});