Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

33.2 KB
Raw Blame
import { afterAll, describe, expect, it, vi } from 'vitest';
import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { runInNewContext } from 'node:vm';
import { adaptStagedDocumentPreview } from './documentPreviewPlayback.js';
import { installLayeredPreviewPlayback } from './previewPlaybackRuntime.js';

const roots = [];
const templates = fileURLToPath(new URL('./documentTemplates/', import.meta.url));
afterAll(async () => { await Promise.all(roots.map(root => rm(root, { recursive: true, force: true }))); });
async function staged() {
  const root = await mkdtemp(join(tmpdir(), 'preview-playback-contract-')); roots.push(root);
  await cp(join(templates, 'layered'), root, { recursive: true });
  await cp(join(templates, 'shared'), root, { recursive: true });
  await cp(new URL('../../lib/musicVideoImageEffects.js', import.meta.url), join(root, 'musicVideoImageEffects.js'));
  return root;
}

describe('recognized staged composition playback capability', () => {
  it('adapts only the disposable canonical copy, preserving the exact seek body and source template', async () => {
    const root = await staged(), sourcePath = join(templates, 'layered/engine.js');
    const original = await readFile(sourcePath, 'utf8'), index = await readFile(join(root, 'index.html'));
    const receipt = await adaptStagedDocumentPreview(root);
    expect(receipt).toMatchObject({ adapted: true, adapterVersion: 1, mediaTiming: 'staged-output-v1', fps: 30 });
    const adapted = await readFile(join(root, 'engine.js'), 'utf8');
    const exact = original.slice(original.indexOf('    async seek(t,'), original.lastIndexOf('\n})();'));
    expect(adapted).toContain(exact);
    expect(await readFile(sourcePath, 'utf8')).toBe(original);
    expect(await readFile(join(root, 'index.html'))).toEqual(index);
    expect(receipt.originalEngineSha256).not.toBe(receipt.stagedEngineSha256);
    // The serialized bridge is a valid script without loading a browser.
    expect(() => new Function(adapted)).not.toThrow();
  });

  it('preserves custom entrypoints/helpers and leaves every generated document on exact fallback', async () => {
    const custom = await staged();
    await writeFile(join(custom, 'cameraRig.js'), 'globalThis.custom = true;');
    const before = await readFile(join(custom, 'engine.js'));
    expect(await adaptStagedDocumentPreview(custom)).toMatchObject({ adapted: false, reason: 'custom-helper' });
    expect(await readFile(join(custom, 'engine.js'))).toEqual(before);
    const altered = await staged();
    await writeFile(join(altered, 'index.html'), '<script src="engine.js"></script><script>sideEffect()</script>');
    expect(await adaptStagedDocumentPreview(altered)).toMatchObject({ adapted: false, reason: 'custom-entrypoint' });
    const generated = await staged();
    const index = await readFile(join(generated, 'index.html'), 'utf8');
    await writeFile(join(generated, 'index.html'), index.replace('<script src="engine.js"></script>', '<script src="generated.js"></script>\n<script src="engine.js"></script>'));
    await writeFile(join(generated, 'generated.js'), 'window.PORTOS_MV_GENERATED = { sections: {} };');
    expect(await adaptStagedDocumentPreview(generated)).toMatchObject({ adapted: false, reason: 'generated-contract-not-admitted' });
  });

  it('declines unknown or too-slow staged video cadence without rewriting its engine', async () => {
    const root = await staged(), original = await readFile(join(root, 'engine.js'));
    for (const fps of [null, 0, 10]) {
      expect(await adaptStagedDocumentPreview(root, { scenes: [{ media: { kind: 'video', fps } }] }))
        .toMatchObject({ adapted: false, reason: 'unsupported-video-fps' });
      expect(await readFile(join(root, 'engine.js'))).toEqual(original);
    }
    expect(await adaptStagedDocumentPreview(root, { scenes: [{ media: { kind: 'video', fps: 24 } }, { media: { kind: 'image', fps: null } }] }))
      .toMatchObject({ adapted: true });
  });

  it('runs the real staged engine with fail-atomic backbuffer publication and restores exact rendering after a failed draw', async () => {
    const root = await staged();
    const song = { sections: [{ id: 'intro', startSec: 0, endSec: 5 }] };
    expect(await adaptStagedDocumentPreview(root)).toMatchObject({ adapted: true });
    let failDraw = false;
    const canvases = [];
    const makeCanvas = () => {
      const calls = [];
      const context = new Proxy({ calls }, { get(target, key) {
        if (key in target) return target[key];
        if (key === 'createImageData' || key === 'getImageData') return (_x, _y, w, h) => ({ data: new Uint8ClampedArray((w || _x) * (h || _y) * 4) });
        if (key === 'measureText') return text => ({ width: String(text).length * 10 });
        if (key === 'createRadialGradient' || key === 'createLinearGradient') return () => ({ addColorStop() {} });
        if (key === 'createPattern') return () => ({});
        return (...args) => { if (key === 'fillRect' && failDraw) throw 1; calls.push([key, ...args]); };
      } });
      const canvas = { width: 1920, height: 1080, context, getContext: () => context };
      canvases.push(canvas); return canvas;
    };
    const front = makeCanvas(), events = [], finish = [], titles = [];
    const sandbox = { setTimeout, clearTimeout, performance: { now: () => 0 }, requestAnimationFrame: () => 1, cancelAnimationFrame() {},
      document: { getElementById: () => front, createElement: () => makeCanvas(), fonts: { load: () => Promise.resolve() } },
      PORTOS_MV: { render: { width: 1920, height: 1080, fps: 24, durationSec: 5 }, song, composition: {},
        scenes: [{ sceneId: 'code', startSec: 0, endSec: 5, visualLayer: 'code' }] },
      PORTOS_MV_EVENT_STATE: () => ({ t: 0, hold: true, activeEvents: [], reactiveGain: 0 }),
      __portosFilmLook: { frame: t => finish.push(t), playback() {} }, __portosTitleCard: { draw: t => titles.push(t) },
      PORTOS_LYRIC_TYPE: { createLyricType: () => ({ ready: Promise.resolve(), draw() {} }) }, postMessage: message => events.push(message) };
    sandbox.window = sandbox;
    runInNewContext(await readFile(join(root, 'engine.js'), 'utf8'), sandbox);
    const composition = sandbox.portosComposition, api = composition.previewPlayback;
    await api.prepare({ epoch: 1, t: 0 });
    const copies = () => front.context.calls.filter(call => call[0] === 'drawImage').length;
    expect(copies()).toBe(1);
    failDraw = true;
    await expect(api.prepare({ epoch: 2, t: 0.5 })).rejects.toBe(1);
    failDraw = false;
    expect(copies()).toBe(1);
    await api.pause({ epoch: 3 });
    await composition.seek(0);
    expect(front.context.calls.some(call => call[0] === 'fillRect')).toBe(true);
    await api.prepare({ epoch: 3, t: 0.75 });
    expect(finish.at(-1)).toBe(18);
    expect(titles.at(-1)).toBe(0.75);
    expect(copies()).toBeGreaterThan(1);
    const backs = canvases.filter(canvas => canvas.context.calls.some(call => call[0] === 'reset'));
    expect(backs).toHaveLength(1);
    expect(backs[0].context.calls.filter(call => call[0] === 'reset')).toHaveLength(3);
    expect(events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-error', epoch: 2 })]);
    await api.dispose();
  });
});

function player({ hold = false, quantized = false, inSec = 0, outSec = 5, cutAt = null, fps = 30, autoFirst = true } = {}) {
  let clock = 0, frame = null, time = 0, writes = 0, readyResolve, playResolve, autoFrame = false, frameId = 0, presented = 0, drawMs = 0;
  const callbacks = new Map();
  const frameWaiters = [];
  const events = [], paints = [], modes = [], sourceTimes = [], scenes = [{ startSec: 0, endSec: cutAt ?? 5, media: { kind: 'video', inSec, outSec, fps } },
    { startSec: cutAt, endSec: 5, media: { kind: 'video', inSec: 0, outSec: 5, fps } }];
  const present = (metadata = {}, callback = callbacks.values().next().value) => callback?.(clock,
    { mediaTime: Math.floor(time * fps + 1e-6) / fps, presentedFrames: ++presented, ...metadata });
  const video = { duration: 5, paused: true, playbackRate: 1, readyState: 4, seeking: false,
    get currentTime() { return time; }, set currentTime(value) { time = value; writes++; },
    pause() { this.paused = true; }, play() { this.paused = false; autoFrame = true; return playResolve ? new Promise(resolve => { playResolve.resolve = resolve; playResolve.enter(); }) : Promise.resolve(); },
    requestVideoFrameCallback(callback) {
      const id = ++frameId;
      callbacks.set(id, (...args) => { callbacks.delete(id); callback(...args); });
      for (const resolve of frameWaiters.splice(0)) resolve();
      if (autoFirst && autoFrame) {
        autoFrame = false;
        Promise.resolve().then(() => { if (callbacks.has(id)) present({}, callbacks.get(id)); });
      }
      return id;
    },
    cancelVideoFrameCallback(id) { callbacks.delete(id); } };
  const bridge = { duration: 5, fps: 24, ready: Promise.resolve(), videos: () => [video], scene: t => cutAt !== null && t >= cutAt ? scenes[1] : scenes[0], needsSource: () => true, playback: on => modes.push(on),
    state: t => ({ t: hold && t >= 0.2 && t < 0.4 ? 0.2 : quantized ? Math.floor(t * 24) / 24 : t, hold: hold && t >= 0.2 && t < 0.4, activeEvents: [], reactiveGain: 0 }),
    async source(scene, t) {
      sourceTimes.push(t);
      if (readyResolve) await new Promise(resolve => { readyResolve.resolve = resolve; readyResolve.enter(); });
      video.currentTime = Math.min(Math.max(scene.media.inSec + t - scene.startSec, scene.media.inSec), scene.media.outSec - 0.5 / 30);
      return video;
    },
    publish(songTime, t, _scene, _source, _state, valid) { if (drawMs) elapse(clock + drawMs); if (!valid()) return false; paints.push({ songTime, t }); return true; }, dispose() { video.pause(); } };
  const sandbox = { setTimeout, clearTimeout, __bridge: bridge, performance: { now: () => clock }, requestAnimationFrame: callback => { frame = callback; return 1; }, cancelAnimationFrame: () => { frame = null; },
    window: { postMessage: message => events.push(message) }, portosComposition: {} };
  runInNewContext(`(${installLayeredPreviewPlayback.toString()})(__bridge)`, sandbox);
  const elapse = (ms) => { const elapsed = (ms - clock) / 1000; if (!video.paused) time += elapsed * video.playbackRate; clock = ms; };
  return { api: sandbox.portosComposition.previewPlayback, video, events, paints, modes, sourceTimes, present,
    pendingCallback: () => callbacks.values().next().value,
    waitForFrame: () => callbacks.size ? Promise.resolve() : new Promise(resolve => frameWaiters.push(resolve)),
    get pendingCallbacks() { return callbacks.size; },
    get writes() { return writes; },
    elapse,
    drawCost(ms) { drawMs = ms; },
    async step(ms, { withVideo = true } = {}) { elapse(ms); const callback = frame; frame = null; callback?.(); if (withVideo && !video.paused) present(); await Promise.resolve(); },
    deferSource() {
      readyResolve = {};
      const entered = new Promise(resolve => { readyResolve.enter = resolve; });
      return { entered, release: () => { readyResolve.resolve?.(); readyResolve = null; } };
    },
    deferPlay() {
      playResolve = {};
      const entered = new Promise(resolve => { playResolve.enter = resolve; });
      return Object.assign(() => { playResolve.resolve?.(); playResolve = null; }, { entered });
    } };
}

describe('cooperative preview public runtime lifecycle', () => {
  it('publishes each fresh video callback independent of RAF/audio phase and never republishes video on RAF alone', async () => {
    const p = player();
    await p.api.prepare({ epoch: 1, t: 0 });
    await p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    const first = p.paints.length;
    await p.step(16, { withVideo: false }); await p.step(32, { withVideo: false });
    expect(p.paints).toHaveLength(first);
    for (const time of [35, 68, 101]) await p.step(time);
    expect(p.paints).toHaveLength(first + 3);
    expect(p.pendingCallbacks).toBe(1);
    await p.api.pause({ epoch: 2 });
    expect(p.pendingCallbacks).toBe(0);
  });

  it('caps a faster source by source-time bins while preserving native 24 fps and holds', async () => {
    const p = player({ fps: 60 });
    await p.api.prepare({ epoch: 1, t: 0 }); await p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    const first = p.paints.length;
    for (const time of [17, 34, 51, 68]) await p.step(time);
    expect(p.paints).toHaveLength(first + 2);
    await p.api.dispose();

    const held = player({ fps: 24, hold: true });
    await held.api.prepare({ epoch: 1, t: 0 }); await held.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    const before = held.paints.length;
    await held.step(43); await held.step(85);
    expect(held.paints).toHaveLength(before + 2);
    const old = held.pendingCallback();
    await held.step(210);
    expect(held.video.paused).toBe(true);
    expect(held.pendingCallbacks).toBe(0);
    await held.step(250);
    await vi.waitFor(async () => {
      await held.step(300);
      expect(held.paints.at(-1).t).toBe(0.2);
      expect(held.paints.at(-1).songTime).toBeCloseTo(0.3);
    }, { timeout: 500, interval: 1 });
    expect(held.events).toHaveLength(0);
    await vi.waitFor(async () => {
      await held.step(410, { withVideo: false });
      expect(held.pendingCallbacks).toBe(1);
      expect(held.paints.at(-1).songTime).toBeCloseTo(0.41);
    }, { timeout: 500, interval: 1 });
    expect(held.video.paused).toBe(false);
    expect(held.sourceTimes.at(-1)).toBe(0.41);
    const afterHold = held.paints.length;
    held.present({ mediaTime: 0.1, presentedFrames: 0 }, old);
    expect(held.paints).toHaveLength(afterHold);
    expect(held.pendingCallbacks).toBe(1);
    await held.api.dispose();
  });

  it('requires a first qualified publication within its separate deadline and immediately settles cancellation', async () => {
    vi.useFakeTimers();
    try {
      const p = player({ autoFirst: false });
      await p.api.prepare({ epoch: 1, t: 0 });
      const playing = p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
      await p.waitForFrame();
      expect(p.paints).toHaveLength(1);
      await vi.advanceTimersByTimeAsync(100);
      expect(await playing).toMatchObject({ status: 'resync-required' });
      expect(p.pendingCallbacks).toBe(0);
      expect(p.video.paused).toBe(true);
      expect(p.events).toHaveLength(1);
      await p.api.prepare({ epoch: 2, t: 0 });
      const second = p.api.play({ epoch: 2, sequence: 1, t: 0, workerTime: 0 });
      await p.waitForFrame();
      const late = p.pendingCallback();
      const paused = p.api.pause({ epoch: 3 });
      expect(await second).toMatchObject({ status: 'superseded' });
      await paused;
      const paints = p.paints.length;
      p.present({ mediaTime: 0, presentedFrames: 1 }, late);
      expect(p.paints).toHaveLength(paints);
      expect(p.pendingCallbacks).toBe(0);
      await p.api.prepare({ epoch: 3, t: 0 });
      const third = p.api.play({ epoch: 3, sequence: 1, t: 0, workerTime: 0 });
      await p.waitForFrame();
      const disposed = p.api.dispose();
      expect(await third).toMatchObject({ status: 'superseded' });
      await disposed;
      expect(p.pendingCallbacks).toBe(0);
    } finally { vi.useRealTimers(); }
  });

  it('rejects stale metadata even when currentTime advances, and duplicate callbacks do not refresh silence', async () => {
    const p = player();
    await p.api.prepare({ epoch: 1, t: 0 }); await p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    const first = p.paints.length;
    await p.step(80, { withVideo: false });
    p.present({ mediaTime: 0, presentedFrames: 1 });
    expect(p.paints).toHaveLength(first);
    await p.step(101, { withVideo: false });
    expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-resync' })]);
    expect(p.video.paused).toBe(true);
    expect(p.pendingCallbacks).toBe(0);
    await p.api.dispose();

    const stale = player();
    await stale.api.prepare({ epoch: 1, t: 0 }); await stale.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    await stale.step(90, { withVideo: false });
    stale.present({ mediaTime: 0.001, presentedFrames: 2 });
    await stale.step(180, { withVideo: false });
    stale.present({ mediaTime: 0.002, presentedFrames: 3 });
    expect(stale.events).toHaveLength(1); // currentTime is on target; decoded metadata is >100 ms old.
    expect(stale.video.paused).toBe(true);
    await stale.api.dispose();
  });

  it('rejects an expired first or steady callback even if fresh metadata arrives before delayed timers and RAF', async () => {
    vi.useFakeTimers();
    try {
      for (const autoFirst of [false, true]) {
        const p = player({ autoFirst });
        await p.api.prepare({ epoch: 1, t: 0 });
        const playing = p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
        await p.waitForFrame();
        if (autoFirst) expect(await playing).toMatchObject({ status: 'playing' });
        const paints = p.paints.length;
        p.elapse(100); // No RAF or timer queue is flushed before this callback.
        p.present({ mediaTime: 0.1, presentedFrames: 2 });
        if (!autoFirst) expect(await playing).toMatchObject({ status: 'resync-required' });
        expect(p.paints).toHaveLength(paints);
        expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-resync' })]);
        expect(p.pendingCallbacks).toBe(0);
        expect(p.video.paused).toBe(true);
        await p.api.dispose();
      }
    } finally { vi.useRealTimers(); }
  });

  it('enforces anchor silence in a video callback before an overdue RAF can run', async () => {
    const p = player();
    await p.api.prepare({ epoch: 1, t: 0 }); await p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    for (let i = 1; i <= 29; i++) { p.elapse(i * 34); p.present(); }
    const paints = p.paints.length;
    expect(p.events).toHaveLength(0);
    p.elapse(1020); p.present(); // Fresh source and callback gap34ms, but no accepted audio anchor for>1s.
    expect(p.paints).toHaveLength(paints);
    expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-resync' })]);
    expect(p.pendingCallbacks).toBe(0);
    expect(p.video.paused).toBe(true);
    await p.api.dispose();
  });

  it('requests gated resync if RAF reaches another scene before the first qualified video publication', async () => {
    const p = player({ autoFirst: false, cutAt: 0.05 });
    await p.api.prepare({ epoch: 1, t: 0 });
    const playing = p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    await p.waitForFrame();
    await p.step(60, { withVideo: false });
    expect(await playing).toMatchObject({ status: 'resync-required' });
    expect(p.sourceTimes).toEqual([0, 0]); // No hidden second alignment under the pending play.
    expect(p.paints).toHaveLength(1);
    expect(p.pendingCallbacks).toBe(0);
    expect(p.video.paused).toBe(true);
    await p.api.dispose();
  });

  it('rejects invalid metadata and retired callbacks while resetting baselines only for a new scene owner', async () => {
    const p = player({ cutAt: 0.2, autoFirst: false });
    await p.api.prepare({ epoch: 1, t: 0 });
    const playing = p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    await p.waitForFrame(); p.present({ mediaTime: 0, presentedFrames: 100 }); await playing;
    const old = p.pendingCallback();
    await p.step(210, { withVideo: false }); await p.waitForFrame();
    p.present({ mediaTime: 0, presentedFrames: 1 });
    const paints = p.paints.length;
    p.present({ mediaTime: 0.2, presentedFrames: 101 }, old);
    expect(p.paints).toHaveLength(paints);
    expect(p.pendingCallbacks).toBe(1);
    p.present({ mediaTime: 0.001, presentedFrames: 0 });
    expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-resync' })]);
    expect(p.pendingCallbacks).toBe(0);
    await p.api.dispose();

    const missing = player({ autoFirst: false });
    await missing.api.prepare({ epoch: 1, t: 0 });
    const first = missing.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    await missing.waitForFrame(); missing.present({ mediaTime: undefined });
    expect(await first).toMatchObject({ status: 'resync-required' });
    expect(missing.pendingCallbacks).toBe(0);
    expect(missing.video.paused).toBe(true);
    await missing.api.dispose();
  });

  it('does not report exact-safe pause when a superseded scene preparation times out', async () => {
    vi.useFakeTimers();
    try {
      const p = player({ hold: true });
      await p.api.prepare({ epoch: 1, t: 0 });
      await p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
      const gate = p.deferSource();
      await p.step(210); await gate.entered;
      const paused = p.api.pause({ epoch: 2 });
      const rejected = expect(paused).rejects.toMatchObject({ code: 'PLAYBACK_FAILED' });
      await vi.advanceTimersByTimeAsync(3001); await rejected;
      expect(() => p.api.prepare({ epoch: 3, t: 0 })).toThrow('PLAYBACK_FAILED');
      expect(p.video.paused).toBe(true);
      gate.release(); await p.api.dispose();
      expect(p.events).toHaveLength(0); // Superseded epoch does not emit a false current-epoch event.
    } finally { vi.useRealTimers(); }
  });

  it('resynchronizes a stalled transition at100ms despite fresh anchors while retaining owned source retirement', async () => {
    vi.useFakeTimers();
    try {
      const p = player({ hold: true });
      await p.api.prepare({ epoch: 1, t: 0 }); await p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
      const gate = p.deferSource(), paints = p.paints.length;
      await p.step(210); await gate.entered;
      p.elapse(260);
      expect(p.api.sync({ epoch: 1, sequence: 2, t: 0.26, workerTime: 260 })).toMatchObject({ status: 'accepted' });
      p.elapse(310);
      await vi.advanceTimersByTimeAsync(100); // No RAF or source completion is needed to stop stale output.
      expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-resync', epoch: 1, sequence: 2 })]);
      expect(p.video.paused).toBe(true);
      expect(p.pendingCallbacks).toBe(0);
      let retired = false;
      const paused = p.api.pause({ epoch: 2 }).then(result => { retired = true; return result; });
      await Promise.resolve(); expect(retired).toBe(false);
      gate.release(); expect(await paused).toMatchObject({ status: 'paused' });
      expect(p.paints).toHaveLength(paints);
      expect(await p.api.prepare({ epoch: 2, t: 0.4 })).toMatchObject({ status: 'prepared' });
      await p.api.dispose();
    } finally { vi.useRealTimers(); }
  });

  it('starts the shared transition deadline when a video callback observes a new mapping before RAF', async () => {
    vi.useFakeTimers();
    try {
      const p = player({ cutAt: 0.2 });
      await p.api.prepare({ epoch: 1, t: 0 }); await p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
      for (const time of [70, 140]) { p.elapse(time); p.present(); }
      const paints = p.paints.length;
      p.elapse(210); p.present(); // RAF never runs to adopt this mapping change.
      expect(p.video.paused).toBe(true);
      p.elapse(260);
      expect(p.api.sync({ epoch: 1, sequence: 2, t: 0.26, workerTime: 260 })).toMatchObject({ status: 'accepted' });
      p.elapse(310); await vi.advanceTimersByTimeAsync(100);
      expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-resync' })]);
      expect(p.paints).toHaveLength(paints);
      expect(p.sourceTimes).toEqual([0, 0]);
      expect(p.pendingCallbacks).toBe(0);
      await p.api.dispose();
    } finally { vi.useRealTimers(); }
  });

  it('keeps the original transition deadline through a new video first-frame wait', async () => {
    const p = player({ cutAt: 0.2, autoFirst: false });
    await p.api.prepare({ epoch: 1, t: 0 });
    const playing = p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    await p.waitForFrame(); p.present({ mediaTime: 0, presentedFrames: 1 }); await playing;
    const gate = p.deferSource(), paints = p.paints.length;
    await p.step(210, { withVideo: false }); await gate.entered;
    p.elapse(290); gate.release(); await p.waitForFrame();
    p.elapse(310); p.present({ mediaTime: 0.1, presentedFrames: 2 }); // Fresh callback20ms after arm, but transition age100ms.
    expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-resync' })]);
    expect(p.paints).toHaveLength(paints);
    expect(p.pendingCallbacks).toBe(0);
    await p.api.pause({ epoch: 2 }); await p.api.dispose();
  });

  it('refuses a late static transition commit after backbuffer drawing crosses the freshness deadline', async () => {
    const p = player({ hold: true });
    await p.api.prepare({ epoch: 1, t: 0 }); await p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    const paints = p.paints.length;
    p.drawCost(100);
    await p.step(210, { withVideo: false });
    await vi.waitFor(() => expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-resync' })]));
    expect(p.paints).toHaveLength(paints);
    expect(p.video.paused).toBe(true);
    await p.api.pause({ epoch: 2 }); await p.api.dispose();
  });

  it('bounds an unsettled native play, poisons reuse, and pauses a late completion', async () => {
    vi.useFakeTimers();
    try {
      const p = player();
      await p.api.prepare({ epoch: 1, t: 0 });
      const finish = p.deferPlay();
      const playing = p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
      await finish.entered;
      const rejected = expect(playing).rejects.toMatchObject({ code: 'PLAYBACK_TIMEOUT' });
      await vi.advanceTimersByTimeAsync(1501); await rejected;
      expect(p.video.paused).toBe(true);
      expect(() => p.api.prepare({ epoch: 2, t: 0 })).toThrow('PLAYBACK_FAILED');
      finish(); await p.api.dispose();
      expect(p.video.paused).toBe(true);
      expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-error', epoch: 1 })]);
    } finally { vi.useRealTimers(); }
  });

  it('uses native forward playback without per-frame seeks, rejects old anchors, and stops when anchors disappear', async () => {
    const p = player();
    expect(await p.api.prepare({ epoch: 1, t: 0 })).toMatchObject({ status: 'prepared' });
    expect(await p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 })).toMatchObject({ status: 'playing' });
    const initialWrites = p.writes;
    for (const time of [34, 68, 102, 136]) await p.step(time);
    expect(p.paints.length).toBeGreaterThanOrEqual(5);
    expect(p.writes).toBe(initialWrites);
    expect(p.modes).toEqual([false, true]);
    expect(p.api.sync({ epoch: 0, sequence: 999, t: 1, workerTime: 136 })).toMatchObject({ status: 'stale' });
    expect(p.api.sync({ epoch: 1, sequence: 2, t: 0.156, workerTime: 136 })).toMatchObject({ status: 'accepted' });
    expect(p.writes).toBe(initialWrites);
    await p.step(1137);
    expect(p.video.paused).toBe(true);
    expect(p.modes).toEqual([false, true, false]);
    expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-resync', epoch: 1, sequence: 2 })]);
    await p.step(1237); expect(p.events).toHaveLength(1);
  });

  it('retires late preparation/play before exact pause and permits the next client epoch', async () => {
    const p = player(), gate = p.deferSource();
    const preparing = p.api.prepare({ epoch: 2, t: 0.5 });
    // Wait on the actual source-entry handshake rather than guessed microtask counts.
    await gate.entered;
    const paused = p.api.pause({ epoch: 3 }); gate.release();
    expect(await preparing).toMatchObject({ status: 'superseded' });
    expect(await paused).toMatchObject({ status: 'paused' });
    expect(p.paints).toHaveLength(0);
    expect(await p.api.prepare({ epoch: 3, t: 0.75 })).toMatchObject({ status: 'prepared' });
    const finishPlay = p.deferPlay();
    const playing = p.api.play({ epoch: 3, sequence: 1, t: 0.75, workerTime: 0 });
    await finishPlay.entered;
    const stopped = p.api.pause({ epoch: 4 }); finishPlay();
    expect(await playing).toMatchObject({ status: 'superseded' }); await stopped;
    expect(p.video.paused).toBe(true);
    expect(p.modes).toEqual([false]); // A cancelled native play never re-enables motion.
    expect(await p.api.prepare({ epoch: 4, t: 1 })).toMatchObject({ status: 'prepared' });
    await p.api.dispose();
    expect(() => p.api.prepare({ epoch: 5, t: 1 })).toThrow('PLAYBACK_DISPOSED');
  });

  it('aligns the warm live source once to running audio, then starts a fresh clock at native rate', async () => {
    const p = player({ quantized: true, inSec: 1 });
    await p.api.prepare({ epoch: 1, t: 0 });
    const gate = p.deferSource();
    const playing = p.api.play({ epoch: 1, sequence: 1, t: 0.18, workerTime: 0 });
    await gate.entered; await p.step(25); gate.release();
    expect(await playing).toMatchObject({ status: 'playing', t: 0.205 });
    expect(p.sourceTimes).toEqual([0, 0.18]); // Source uses song time; drawing remains on its 24 fps grid.
    expect(p.video.currentTime).toBeCloseTo(1.18);
    expect(p.video.playbackRate).toBe(1);
    expect(p.api.sync({ epoch: 1, sequence: 2, t: 0.205, workerTime: 25 })).toMatchObject({ status: 'accepted', driftSec: 0 });
    const writes = p.writes;
    await p.step(59); await p.step(93);
    expect(p.writes).toBe(writes);
    expect(p.video.playbackRate).toBe(1);
    expect(p.paints.at(-1).songTime).toBeCloseTo(0.273);
    expect(p.paints.at(-1).t).toBe(0.25);
    await p.api.dispose();
  });

  it('rejects slow warm source work without publishing, starting media, or retrying the alignment', async () => {
    const p = player();
    await p.api.prepare({ epoch: 1, t: 0 });
    const gate = p.deferSource();
    const playing = p.api.play({ epoch: 1, sequence: 1, t: 0.18, workerTime: 0 });
    await gate.entered; await p.step(1000); gate.release();
    expect(await playing).toMatchObject({ status: 'resync-required' });
    expect(p.sourceTimes).toEqual([0, 0.18]);
    expect(p.paints).toHaveLength(1);
    expect(p.video.paused).toBe(true);
    expect(p.modes).toEqual([false]);
    expect(p.events).toEqual([expect.objectContaining({ type: 'portos-mv:playback-resync', epoch: 1 })]);
    await p.api.dispose();
  });

  it('requires the aligned scene and decoded media to remain usable through native play completion', async () => {
    const p = player({ cutAt: 0.25 });
    await p.api.prepare({ epoch: 1, t: 0 });
    const finish = p.deferPlay();
    const playing = p.api.play({ epoch: 1, sequence: 1, t: 0.24, workerTime: 0 });
    await finish.entered; await p.step(25); finish();
    expect(await playing).toMatchObject({ status: 'resync-required' });
    expect(p.sourceTimes).toEqual([0, 0.24]);
    expect(p.video.paused).toBe(true);
    expect(p.modes).toEqual([false]);
    expect(p.paints).toHaveLength(1);
    await p.api.dispose();

    const unavailable = player();
    await unavailable.api.prepare({ epoch: 1, t: 0 });
    unavailable.video.readyState = 1;
    expect(await unavailable.api.play({ epoch: 1, sequence: 1, t: 0.18, workerTime: 0 })).toMatchObject({ status: 'resync-required' });
    expect(unavailable.video.paused).toBe(true);
    await unavailable.api.dispose();
  });

  it('retires a canceled warm alignment before exact pause and preserves frozen narrative source time', async () => {
    const p = player({ hold: true, quantized: true });
    await p.api.prepare({ epoch: 1, t: 0 });
    const gate = p.deferSource();
    const playing = p.api.play({ epoch: 1, sequence: 1, t: 0.18, workerTime: 0 });
    await gate.entered;
    const paused = p.api.pause({ epoch: 2 }); gate.release();
    expect(await playing).toMatchObject({ status: 'superseded' });
    expect(await paused).toMatchObject({ status: 'paused' });
    expect(p.video.paused).toBe(true);
    expect(p.modes).toEqual([false]);
    await p.api.prepare({ epoch: 2, t: 0.25 });
    expect(await p.api.play({ epoch: 2, sequence: 1, t: 0.25, workerTime: 0 })).toMatchObject({ status: 'playing' });
    expect(p.sourceTimes.at(-1)).toBe(0.2);
    expect(p.video.paused).toBe(true);
    const writes = p.writes;
    await p.step(34); await p.step(68);
    expect(p.writes).toBe(writes);
    expect(p.paints.at(-1)).toMatchObject({ t: 0.2 });
    expect(p.paints.at(-1).songTime).toBeCloseTo(0.318);
    await p.api.dispose();
  });

  it('uses live song time at the staged output boundary even before the next drawing frame', async () => {
    const p = player({ quantized: true, outSec: 0.11 });
    await p.api.prepare({ epoch: 1, t: 0 });
    await p.api.play({ epoch: 1, sequence: 1, t: 0.085, workerTime: 0 });
    expect(p.video.paused).toBe(false);
    await p.step(10);
    expect(p.video.paused).toBe(true);
    expect(p.sourceTimes.at(-1)).toBeCloseTo(0.095);
    expect(p.video.currentTime).toBeCloseTo(0.11 - 0.5 / 30);
    await p.api.pause({ epoch: 2 });
    expect(p.events).toHaveLength(0);
    await p.api.dispose();
  });

  it('pauses native media for narrative holds and requires gated resync for a large audio mismatch', async () => {
    const p = player({ hold: true });
    await p.api.prepare({ epoch: 1, t: 0 }); await p.api.play({ epoch: 1, sequence: 1, t: 0, workerTime: 0 });
    await p.step(210); await Promise.resolve();
    expect(p.video.paused).toBe(true);
    const writes = p.writes;
    await p.step(250); await p.step(300);
    expect(p.writes).toBe(writes);
    expect(p.api.sync({ epoch: 1, sequence: 2, t: 1, workerTime: 300 })).toMatchObject({ status: 'resync-required' });
    expect(p.writes).toBe(writes);
    expect(p.video.paused).toBe(true);
  });
});