Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Keep preview pixels across clip cuts

Bitti1300eea2a7b1
diff --git a/docs/architecture.md b/docs/architecture.md
index 2bd0f29..da9c60b 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -65,6 +65,8 @@ Continuation archives contain the full cumulative sequence. Slopus streams only
Timeline and Export share `ProgramMonitor`. It keeps the current picture and the next two pictures mounted, loading and seeking upcoming clips before their cuts. Players are keyed by clip so separate trims of one file have separate decoder positions; a lower layer becoming the foreground retains its player. Upcoming players remain paused, hidden and muted. Effect renderers survive play/pause changes, and the timeline clock retains fractional milliseconds and advances continuously across cuts. Leaving the prepared window releases a clip's decoder; blob URLs remain cached until the monitor closes.
+With WebGPU, `ProgramPicture` presents all visible layers through one persistent canvas using the export compositor. Each update captures the required `VideoFrame` handles before clearing or drawing; a loading or seeking source leaves the last complete picture intact. Actual timeline gaps clear to the project background. This avoids the black frame caused by handing off between browser video surfaces at a cut. Frames remain in GPU memory, and effect pipelines are prepared when the compositor starts. Machines without WebGPU retain the native-media preview.
+
## Independently judged slices
1. Foundation: desktop shell, library, portable project persistence, schema, and always-visible agent prompt.
diff --git a/src/components/workspace/ExportView.test.tsx b/src/components/workspace/ExportView.test.tsx
index 8d46415..5621546 100644
--- a/src/components/workspace/ExportView.test.tsx
+++ b/src/components/workspace/ExportView.test.tsx
@@ -50,7 +50,7 @@ describe("the export view where nothing can encode", () => {
// The preview is the same player the timeline uses, and in a browser there
// is no project folder for it to read the footage from.
expect(screen.getByText(/Playback needs the desktop app/i)).toBeTruthy();
- expect(document.querySelector("canvas")).toBeNull();
+ expect(document.querySelector("canvas")?.style.visibility).toBe("hidden");
// The controls are there and are honest about what they can do: there IS
// something on this timeline, so play is offered.
expect((screen.getByRole("button", { name: "Play" }) as HTMLButtonElement).disabled).toBe(false);
diff --git a/src/components/workspace/ProgramLayer.tsx b/src/components/workspace/ProgramLayer.tsx
index cdc300f..caccaf2 100644
--- a/src/components/workspace/ProgramLayer.tsx
+++ b/src/components/workspace/ProgramLayer.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type CSSProperties } from "react";
import { clipFrameStyle, clipVisualSettings, type ClipFrameStyle } from "../../lib/export";
import { PreviewSources } from "../../lib/exportPipeline";
import type { ProjectAsset, TimelineClip } from "../../lib/project";
@@ -6,6 +6,7 @@ import { ChromaKeyPreview } from "./ChromaKeyPreview";
import { VideoEffectsPreview } from "./VideoEffectsPreview";
import { hasVideoEffects } from "../../lib/effectSettings";
import { isTauri } from "../../lib/persistence";
+import type { PreviewMedia } from "../../lib/previewPresentation";
export function previewMediaStyle(frame: ClipFrameStyle): CSSProperties {
const { transform, look, opacity, revealStart, revealEnd } = frame;
@@ -19,7 +20,7 @@ export function previewMediaStyle(frame: ClipFrameStyle): CSSProperties {
}
/** Prepared clips keep their decoder and effect renderer when made visible. */
-export function ProgramLayer({ clip, asset, sources, playheadMs, playing, active, foreground, muted, externalSeek, depth }: {
+export function ProgramLayer({ clip, asset, sources, playheadMs, playing, active, foreground, muted, externalSeek, depth, media, composited }: {
clip: TimelineClip;
asset: ProjectAsset | undefined;
sources: PreviewSources;
@@ -30,12 +31,22 @@ export function ProgramLayer({ clip, asset, sources, playheadMs, playing, active
muted: boolean;
externalSeek: boolean;
depth: number;
+ media: PreviewMedia;
+ composited: boolean;
}) {
const [url, setUrl] = useState<string | null>(null);
const [error, setError] = useState<string | null>(null);
const [ready, setReady] = useState(false);
- const video = useRef<HTMLVideoElement>(null);
- const image = useRef<HTMLImageElement>(null);
+ const video = useRef<HTMLVideoElement | null>(null);
+ const image = useRef<HTMLImageElement | null>(null);
+ const registerVideo = useCallback((element: HTMLVideoElement | null) => {
+ video.current = element;
+ media.set(clip.id, element);
+ }, [media, clip.id]);
+ const registerImage = useCallback((element: HTMLImageElement | null) => {
+ image.current = element;
+ media.set(clip.id, element);
+ }, [media, clip.id]);
const position = useRef({ clip, playheadMs, playing, active, externalSeek });
position.current = { clip, playheadMs, playing, active, externalSeek };
const isImage = asset?.kind === "image" || asset?.mimeType.startsWith("image/");
@@ -80,18 +91,18 @@ export function ProgramLayer({ clip, asset, sources, playheadMs, playing, active
};
const style = previewMediaStyle(clipFrameStyle(clipVisualSettings(clip), playheadMs - clip.startMs));
const effects = hasVideoEffects(clip);
- const sourceStyle: CSSProperties = clip.chromaKey || effects ? { ...style, visibility: "hidden", position: "absolute" } : style;
+ const sourceStyle: CSSProperties = composited || clip.chromaKey || effects ? { ...style, visibility: "hidden", position: "absolute" } : style;
const showStatus = active && foreground && isTauri() && Boolean(asset?.relativePath || asset?.sourcePath);
return <div className="program-layer" data-clip-id={clip.id} data-active={active} aria-hidden={!active}
aria-label={`${foreground ? "Foreground" : "Background"} clip: ${clip.label}`}
style={{ visibility: active ? "visible" : "hidden", zIndex: depth }}>
{url && (isImage
- ? <img ref={image} src={url} alt={clip.label} style={sourceStyle} onError={() => setError(`Could not decode ${clip.label}.`)} />
- : <video key={url} ref={video} src={url} style={sourceStyle} muted={!active || muted} playsInline preload="auto"
+ ? <img ref={registerImage} src={url} alt={clip.label} style={sourceStyle} onError={() => setError(`Could not decode ${clip.label}.`)} />
+ : <video key={url} ref={registerVideo} src={url} style={sourceStyle} muted={!active || muted} playsInline preload="auto"
onLoadedMetadata={loaded} onLoadedData={loaded} onCanPlay={loaded} onSeeked={loaded}
onError={() => setError(`Could not decode ${clip.label}.`)} />)}
- {url && effects && <VideoEffectsPreview source={isImage ? image : video} sourceUrl={url} effects={clip} playing={playing && active && !isImage} style={style} onError={setError} />}
- {url && !effects && clip.chromaKey && <ChromaKeyPreview source={isImage ? image : video} sourceUrl={url} effect={clip.chromaKey} playing={playing && active && !isImage} style={style} onError={setError} />}
+ {!composited && url && effects && <VideoEffectsPreview source={isImage ? image : video} sourceUrl={url} effects={clip} playing={playing && active && !isImage} style={style} onError={setError} />}
+ {!composited && url && !effects && clip.chromaKey && <ChromaKeyPreview source={isImage ? image : video} sourceUrl={url} effect={clip.chromaKey} playing={playing && active && !isImage} style={style} onError={setError} />}
{showStatus && (error
? <div className="program-note program-note--error" role="alert">{error}</div>
: (!url || (!ready && !isImage)) && <div className="program-note"><span>Loading {clip.label}…</span></div>)}
diff --git a/src/components/workspace/ProgramMonitor.tsx b/src/components/workspace/ProgramMonitor.tsx
index e536fa0..b870d13 100644
--- a/src/components/workspace/ProgramMonitor.tsx
+++ b/src/components/workspace/ProgramMonitor.tsx
@@ -1,12 +1,14 @@
import { ProgramLayer } from "./ProgramLayer";
+import { ProgramPicture } from "./ProgramPicture";
import { Film } from "lucide-react";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { clipFrameStyle, clipVisualSettings } from "../../lib/export";
+import { clipFrameStyle, clipVisualSettings, outputDimensions } from "../../lib/export";
import { isTauri } from "../../lib/persistence";
import type { ClipTransform, ProjectAsset, ProjectConfig, TimelineClip } from "../../lib/project";
import { clipEndMs } from "../../lib/timeline";
import { PreviewSources } from "../../lib/exportPipeline";
import { preparedPreviewClips, previewSegmentIndex, previewSegments } from "../../lib/timelinePreview";
+import { PreviewMedia } from "../../lib/previewPresentation";
/* The monitor owns a continuous timeline clock. Each visible or upcoming clip
* owns a persistent media element: loading, decoding the first frame and seeking
@@ -126,6 +128,10 @@ export function ProgramMonitor({ config, folderPath, playheadMs, playing, onSeek
through Tauri as bytes. The cleanup revokes every URL handed out, so
leaving the timeline — or opening another project — gives all of it back. */
const sources = useMemo(() => new PreviewSources(folderPath), [folderPath]);
+ const media = useMemo(() => new PreviewMedia(), [folderPath]);
+ const [composited, setComposited] = useState(false);
+ const dimensions = outputDimensions(config.settings.resolution, config.settings.aspectRatio);
+ const previewScale = Math.min(1, 1280 / Math.max(dimensions.width, dimensions.height));
useEffect(() => () => sources.dispose(), [sources]);
/* The playhead as of this render, readable from inside the animation frame
@@ -298,6 +304,9 @@ export function ProgramMonitor({ config, folderPath, playheadMs, playing, onSeek
onSelectClip(clip.id);
}}
>
+ <ProgramPicture key={folderPath} media={media} layers={layers} playheadMs={playheadMs}
+ width={Math.round(dimensions.width * previewScale)} height={Math.round(dimensions.height * previewScale)}
+ background={config.settings.backgroundColor} onAvailable={setComposited} />
<div className="program-media">{prepared.map(({ clip: layer, prepareAtMs }) => {
const depth = layers.findIndex((visible) => visible.id === layer.id);
return <ProgramLayer
@@ -305,6 +314,8 @@ export function ProgramMonitor({ config, folderPath, playheadMs, playing, onSeek
clip={layer}
asset={assetsById.get(layer.assetId)}
sources={sources}
+ media={media}
+ composited={composited}
playheadMs={depth >= 0 ? playheadMs : prepareAtMs}
playing={playing}
active={depth >= 0}
diff --git a/src/components/workspace/ProgramPicture.test.tsx b/src/components/workspace/ProgramPicture.test.tsx
new file mode 100644
index 0000000..707fc8e
--- /dev/null
+++ b/src/components/workspace/ProgramPicture.test.tsx
@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+import { act, cleanup, render } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { ProgramPicture } from "./ProgramPicture";
+import { PreviewMedia } from "../../lib/previewPresentation";
+import { createPreviewCompositor } from "../../lib/exportPipeline";
+import type { TimelineClip } from "../../lib/project";
+
+vi.mock("../../lib/exportPipeline", () => ({ createPreviewCompositor: vi.fn() }));
+afterEach(() => { cleanup(); vi.resetAllMocks(); });
+
+it("keeps the canvas and GPU compositor through cuts and releases them when the monitor closes", async () => {
+ const compositor = { kind: "webgpu" as const, clear: vi.fn(), draw: vi.fn(), take: vi.fn(), dispose: vi.fn() };
+ vi.mocked(createPreviewCompositor).mockResolvedValue(compositor);
+ const props = { media: new PreviewMedia(), width: 1280, height: 720, background: "#000000", onAvailable: vi.fn() };
+ const clip = { id: "first" } as TimelineClip;
+ const view = render(<ProgramPicture {...props} layers={[clip]} playheadMs={0} />);
+ await act(async () => undefined);
+ const canvas = view.container.querySelector("canvas");
+ view.rerender(<ProgramPicture {...props} layers={[{ ...clip, id: "second" }]} playheadMs={1000} />);
+ expect(view.container.querySelector("canvas")).toBe(canvas);
+ expect(createPreviewCompositor).toHaveBeenCalledTimes(1);
+ expect(compositor.clear).not.toHaveBeenCalled(); // no decoded frames yet
+ view.rerender(<ProgramPicture {...props} layers={[]} playheadMs={2000} />);
+ expect(compositor.clear).toHaveBeenCalledTimes(1); // intentional gap
+ view.unmount();
+ expect(compositor.dispose).toHaveBeenCalledTimes(1);
+});
+
+it("disposes a compositor that finishes initializing after unmount", async () => {
+ const compositor = { kind: "webgpu" as const, clear: vi.fn(), draw: vi.fn(), take: vi.fn(), dispose: vi.fn() };
+ let finish!: (value: typeof compositor) => void;
+ vi.mocked(createPreviewCompositor).mockImplementation(() => new Promise((resolve) => { finish = resolve; }));
+ const view = render(<ProgramPicture media={new PreviewMedia()} width={640} height={360} background="#000000" onAvailable={vi.fn()} layers={[]} playheadMs={0} />);
+ view.unmount();
+ await act(async () => finish(compositor));
+ expect(compositor.clear).not.toHaveBeenCalled();
+ expect(compositor.dispose).toHaveBeenCalledTimes(1);
+});
diff --git a/src/components/workspace/ProgramPicture.tsx b/src/components/workspace/ProgramPicture.tsx
new file mode 100644
index 0000000..4c2bf19
--- /dev/null
+++ b/src/components/workspace/ProgramPicture.tsx
@@ -0,0 +1,57 @@
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPreviewCompositor, type Compositor } from "../../lib/exportPipeline";
+import { presentPreviewFrame, type PreviewMedia } from "../../lib/previewPresentation";
+import type { TimelineClip } from "../../lib/project";
+
+/** A persistent presentation surface: media elements may come and go, but a
+ * cut never removes the canvas containing the last complete picture. */
+export function ProgramPicture({ media, layers, playheadMs, width, height, background, onAvailable }: {
+ media: PreviewMedia;
+ layers: TimelineClip[];
+ playheadMs: number;
+ width: number;
+ height: number;
+ background: string;
+ onAvailable: (available: boolean) => void;
+}) {
+ const canvas = useRef<HTMLCanvasElement>(null);
+ const current = useRef({ layers, playheadMs, onAvailable });
+ current.current = { layers, playheadMs, onAvailable };
+ const redraw = useRef<(() => void) | null>(null);
+ const [available, setAvailable] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+ useEffect(() => {
+ if (!canvas.current) return;
+ let live = true;
+ let compositor: Compositor | null = null;
+ const draw = () => {
+ if (!live || !compositor) return;
+ try { presentPreviewFrame(compositor, media, current.current.layers, current.current.playheadMs); }
+ catch (reason) { setError(String(reason)); }
+ };
+ const unsubscribe = media.subscribe(draw);
+ redraw.current = draw;
+ setError(null);
+ void createPreviewCompositor(canvas.current, width, height, background).then((created) => {
+ if (!live) { created?.dispose(); return; }
+ compositor = created;
+ draw();
+ setAvailable(Boolean(created));
+ current.current.onAvailable(Boolean(created));
+ }, () => {
+ // Preserve the existing native-media preview on machines without WebGPU.
+ if (live) { setAvailable(false); current.current.onAvailable(false); }
+ });
+ return () => {
+ live = false;
+ redraw.current = null;
+ unsubscribe();
+ compositor?.dispose();
+ };
+ }, [media, width, height, background]);
+ useLayoutEffect(() => redraw.current?.(), [layers, playheadMs]);
+ return <>
+ <canvas ref={canvas} className="program-composited-picture" aria-label="Video preview" style={{ visibility: available ? "visible" : "hidden" }} />
+ {available && error && <div className="program-note program-note--error" role="alert">{error}</div>}
+ </>;
+}
diff --git a/src/lib/exportPipeline.ts b/src/lib/exportPipeline.ts
index 771c4c1..7ec2872 100644
--- a/src/lib/exportPipeline.ts
+++ b/src/lib/exportPipeline.ts
@@ -135,7 +135,7 @@ export async function probeAllCodecs(plan: ExportPlan, bitrate: number): Promise
export type CompositorKind = "webgpu" | "canvas2d";
-interface Compositor {
+export interface Compositor {
readonly kind: CompositorKind;
/** Paints the background alone — what a frame with no clip over it looks like. */
clear(): void;
@@ -216,20 +216,22 @@ const NO_GPU_API = "This webview exposes no navigator.gpu at all.";
const NO_ADAPTER =
"navigator.gpu exists but requestAdapter() returned no adapter — the usual causes are a virtual machine, an RDP session, or a driver on Chromium's blocklist.";
-async function createWebGpuCompositor(width: number, height: number, background: string): Promise<GpuAttempt> {
+async function createWebGpuCompositor(width: number, height: number, background: string, target?: HTMLCanvasElement): Promise<GpuAttempt> {
if (typeof navigator === "undefined" || !("gpu" in navigator) || !navigator.gpu) {
return { compositor: null, reason: NO_GPU_API };
}
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) return { compositor: null, reason: NO_ADAPTER };
const device = await adapter.requestDevice();
- const canvas = new OffscreenCanvas(width, height);
- const context = canvas.getContext("webgpu");
+ const canvas = target ?? new OffscreenCanvas(width, height);
+ const context = canvas.getContext("webgpu") as GPUCanvasContext | null;
if (!context) {
device.destroy();
return { compositor: null, reason: "This computer gave no WebGPU context for an OffscreenCanvas." };
}
const format = navigator.gpu.getPreferredCanvasFormat();
+ canvas.width = width;
+ canvas.height = height;
context.configure({ device, format, alphaMode: "opaque" });
const shader = device.createShaderModule({ code: COMPOSITOR_SHADER });
const makePipeline = (module: GPUShaderModule) => device.createRenderPipeline({
@@ -253,7 +255,8 @@ async function createWebGpuCompositor(width: number, height: number, background:
.replace("var source: texture_external;", "var source: texture_2d<f32>;")
.replace("let sampled = textureSampleBaseClampToEdge(source, source_sampler, uv);",
"let premultiplied = textureSampleLevel(source, source_sampler, uv, 0.); let sampled = vec4f(premultiplied.rgb / max(premultiplied.a, .00001), premultiplied.a);") }));
- let effectsProcessor: ReturnType<typeof createVideoEffectsProcessor> | undefined;
+ // Preview must not compile its effect pipelines on the first effected cut.
+ let effectsProcessor = target ? createVideoEffectsProcessor(device) : undefined;
const uniform = device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
const styleUniform = device.createBuffer({ size: 48, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
const sampler = device.createSampler({ magFilter: "linear", minFilter: "linear" });
@@ -341,12 +344,20 @@ async function createWebGpuCompositor(width: number, height: number, background:
},
dispose() {
effectsProcessor?.dispose();
+ context.unconfigure();
device.destroy();
},
};
return { compositor, reason: null };
}
+/** The monitor presents through one canvas for its entire lifetime. Sharing
+ * the export compositor keeps VideoFrames in GPU memory and applies the same
+ * transforms, transitions and effects without swapping browser video surfaces. */
+export async function createPreviewCompositor(canvas: HTMLCanvasElement, width: number, height: number, background: string): Promise<Compositor | null> {
+ return (await createWebGpuCompositor(width, height, background, canvas)).compositor;
+}
+
function createCanvasCompositor(width: number, height: number, background: string): Compositor {
const canvas = new OffscreenCanvas(width, height);
const context = canvas.getContext("2d", { alpha: false });
diff --git a/src/lib/previewPresentation.test.ts b/src/lib/previewPresentation.test.ts
new file mode 100644
index 0000000..1a73f8f
--- /dev/null
+++ b/src/lib/previewPresentation.test.ts
@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { presentPreviewFrame, PreviewMedia } from "./previewPresentation";
+import type { Compositor } from "./exportPipeline";
+import type { TimelineClip } from "./project";
+
+const clip = (id: string): TimelineClip => ({ id, assetId: id, trackId: "video", startMs: 0, durationMs: 1000, sourceStartMs: 0, label: id, color: null, status: "approved" });
+const compositor = (): Compositor => ({ kind: "webgpu", clear: vi.fn(), draw: vi.fn(), take: vi.fn(), dispose: vi.fn() });
+const video = (ready = true) => {
+ const element = document.createElement("video");
+ Object.defineProperties(element, { readyState: { value: ready ? 4 : 1, configurable: true }, videoWidth: { value: 320 }, videoHeight: { value: 180 } });
+ return element;
+};
+afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); });
+
+describe("persistent preview presentation", () => {
+ it("keeps the outgoing pixels until the incoming frame is available, then replaces them in the same surface", () => {
+ const frames: { source: unknown; close: ReturnType<typeof vi.fn> }[] = [];
+ vi.stubGlobal("VideoFrame", class {
+ close = vi.fn();
+ constructor(public source: unknown) { frames.push(this); }
+ });
+ const media = new PreviewMedia();
+ const first = video(), second = video(false);
+ media.set("first", first); media.set("second", second);
+ const output = compositor();
+ expect(presentPreviewFrame(output, media, [clip("first")], 900)).toBe(true);
+ expect(presentPreviewFrame(output, media, [clip("second")], 1000)).toBe(false);
+ // Clearing for a cut before capturing its frame was the black-frame risk.
+ expect(output.clear).toHaveBeenCalledTimes(1);
+ Object.defineProperty(second, "readyState", { value: 4 });
+ expect(presentPreviewFrame(output, media, [clip("second")], 1017)).toBe(true);
+ expect(output.clear).toHaveBeenCalledTimes(2);
+ expect(frames.map((frame) => frame.source)).toEqual([first, second]);
+ frames.forEach((frame) => expect(frame.close).toHaveBeenCalledTimes(1));
+ });
+
+ it("does not clear for a pending trim seek, an absent layer or an undecoded image", () => {
+ const output = compositor();
+ const media = new PreviewMedia();
+ const pending = video();
+ Object.defineProperty(pending, "seeking", { value: true });
+ media.set("seek", pending);
+ media.set("image", document.createElement("img"));
+ for (const id of ["seek", "missing", "image"]) expect(presentPreviewFrame(output, media, [clip(id)], 1000)).toBe(false);
+ expect(output.clear).not.toHaveBeenCalled();
+ });
+
+ it("captures all layers before submitting any pixels and closes partial captures", () => {
+ const close = vi.fn();
+ vi.stubGlobal("VideoFrame", class { close = close; });
+ const media = new PreviewMedia();
+ media.set("top", video());
+ const output = compositor();
+ expect(presentPreviewFrame(output, media, [clip("top"), clip("lower")], 1000)).toBe(false);
+ expect(output.clear).not.toHaveBeenCalled();
+ expect(output.draw).not.toHaveBeenCalled();
+ expect(close).toHaveBeenCalledTimes(1);
+ });
+
+ it("clears intentional timeline gaps instead of holding footage across them", () => {
+ const output = compositor();
+ expect(presentPreviewFrame(output, new PreviewMedia(), [], 1000)).toBe(true);
+ expect(output.clear).toHaveBeenCalledTimes(1);
+ expect(output.draw).not.toHaveBeenCalled();
+ });
+
+ it("redraws when a prepared frame arrives and detaches discarded media", () => {
+ const media = new PreviewMedia();
+ const redraw = vi.fn();
+ const unsubscribe = media.subscribe(redraw);
+ const first = video(), replacement = video();
+ media.set("clip", first);
+ first.dispatchEvent(new Event("loadeddata"));
+ media.set("clip", replacement);
+ first.dispatchEvent(new Event("seeked"));
+ replacement.dispatchEvent(new Event("seeked"));
+ media.set("clip", null);
+ replacement.dispatchEvent(new Event("seeked"));
+ expect(redraw).toHaveBeenCalledTimes(2);
+ unsubscribe();
+ });
+});
diff --git a/src/lib/previewPresentation.ts b/src/lib/previewPresentation.ts
new file mode 100644
index 0000000..beaf687
--- /dev/null
+++ b/src/lib/previewPresentation.ts
@@ -0,0 +1,55 @@
+import { clipFrameStyle, clipVisualSettings } from "./export";
+import type { Compositor } from "./exportPipeline";
+import type { TimelineClip } from "./project";
+
+type PreviewMediaElement = HTMLVideoElement | HTMLImageElement;
+
+/** Prepared decoders belong to clips; the displayed canvas belongs to the
+ * monitor. Media arriving asynchronously requests a redraw of the current cut. */
+export class PreviewMedia {
+ private elements = new Map<string, PreviewMediaElement>();
+ private listeners = new Set<() => void>();
+ private events = ["loadeddata", "seeked", "load"];
+ private changed = () => { this.listeners.forEach((listener) => listener()); };
+
+ set(id: string, element: PreviewMediaElement | null) {
+ const previous = this.elements.get(id);
+ if (previous === element) return;
+ if (previous) this.events.forEach((event) => previous.removeEventListener(event, this.changed));
+ if (element) {
+ this.elements.set(id, element);
+ this.events.forEach((event) => element.addEventListener(event, this.changed));
+ } else this.elements.delete(id);
+ }
+
+ get(id: string) { return this.elements.get(id); }
+
+ subscribe(listener: () => void) {
+ this.listeners.add(listener);
+ return () => { this.listeners.delete(listener); };
+ }
+}
+
+/** Capture every layer BEFORE clearing the display. If any decoder is still
+ * loading/seeking, keep the complete previous picture. A real timeline gap
+ * deliberately clears the canvas. No pixel readback or CPU frame copies. */
+export function presentPreviewFrame(compositor: Compositor, media: PreviewMedia, layers: TimelineClip[], playheadMs: number): boolean {
+ const pictures: { frame: VideoFrame; clip: TimelineClip }[] = [];
+ try {
+ for (const clip of layers) {
+ const element = media.get(clip.id);
+ if (!element) return false;
+ const video = element instanceof HTMLVideoElement;
+ if (video ? element.readyState < 2 || element.seeking || !element.videoWidth || !element.videoHeight
+ : !element.complete || !element.naturalWidth || !element.naturalHeight) return false;
+ pictures.push({ frame: new VideoFrame(element, { timestamp: Math.round(playheadMs * 1000) }), clip });
+ }
+ compositor.clear();
+ for (const { frame, clip } of pictures.reverse()) {
+ compositor.draw(frame, clipFrameStyle(clipVisualSettings(clip), playheadMs - clip.startMs));
+ }
+ return true;
+ } finally {
+ pictures.forEach(({ frame }) => frame.close());
+ }
+}
diff --git a/src/styles/timeline.css b/src/styles/timeline.css
index b868c0a..7a22859 100644
--- a/src/styles/timeline.css
+++ b/src/styles/timeline.css
@@ -1545,5 +1545,6 @@
.clip-effects__picker span { font-size: var(--text-xs); color: var(--text-muted); }
.program-media { position: absolute; inset: 0; z-index: 0; pointer-events: none; }
+.program-composited-picture { position: absolute; inset: 0; pointer-events: none; }
.program-layer { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; pointer-events: none; }
.program-picture > video, .program-picture > img, .program-keyed-picture { position: absolute; inset: 0; }