@hyperframes/core 0.9.21 → 0.9.23

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { RuntimeTimelineClipIdentity } from "./runtime/types.js";
+export type { PlaybackHeldBy, RuntimeTimelineClipIdentity } from "./runtime/types.js";
 export type { ExecutionMode, Orientation, Asset, TimelineElement, TimelineElementBase, TimelineMediaElement, TimelineTextElement, TimelineCompositionElement, TimelineElementType, MediaElementType, CanvasResolution, Fps, FpsInput, FpsParseResult, MediaFile, CompositionAPI, PlayerAPI, AddElementData, ValidationResult, CompositionAsset, Keyframe, KeyframeProperties, ElementKeyframes, StageZoom, StageZoomKeyframe, CompositionVariableType, CompositionVariableBase, StringVariable, NumberVariable, ColorVariable, BooleanVariable, EnumVariable, CompositionVariable, CompositionSpec, WaveformData, OutputResolutionCompatibility, OutputResolutionIssueKind, } from "./core.types.js";
 export type { SlideshowManifest, SlideRef, SlideHotspot, SlideSequence, ResolvedSlide, ResolvedSlideSequence, ResolvedSlideshow, } from "./slideshow/index.js";
 export { parseSlideshowManifest, resolveSlideshow } from "./slideshow/index.js";
@@ -37,6 +37,7 @@ export { parseCubeLut, CubeLutParseError, type CubeLut3D, type ParseCubeLutOptio
 export { bakeHfColorGradingCube, type BakeHfColorGradingCubeOptions } from "./colorGradingBake.js";
 export { firstFrameColourArgs, hdrToSdrToneMapFilter, keyframeTransferArgs, parseKeyframeTransfers, readsKeyframeTransfers, toneMapReferenceNits, parseFirstFrameColour, type ToneMapFrameColour, type ToneMapSourceColour, } from "./hdrToneMap.js";
 export { HEAVY_BITRATE, HEAVY_PIXEL_SHARE, PREVIEW_PROXY_BOX_PARAM, PREVIEW_PROXY_LIGHT_PARAM, PREVIEW_PROXY_PRIORITY_HEADER, PREVIEW_PROXY_PROGRESS_HEADER, PREVIEW_PROXY_RETRY_PARAM, PREVIEW_PROXY_STILL_PARAM, PREVIEW_QUALITY_LEVELS, formatPreviewProxyBox, isHeavyForPreview, isPreviewQuality, parsePreviewProxyBox, quantizePreviewProxyBox, scalePreviewProxyBox, type PreviewProxyBox, type PreviewQuality, type PreviewSourceFacts, } from "./previewProxyBox.js";
+export type { PausedVideoFrameProvider, PausedVideoFrameRequest, PausedVideoFrame, } from "./runtime/pausedVideoFrames.js";
 export { HYPERFRAME_RUNTIME_ARTIFACTS, HYPERFRAME_RUNTIME_CONTRACT, loadHyperframeRuntimeSource, type HyperframeRuntimeContract, } from "./inline-scripts/hyperframe.js";
 export { HYPERFRAME_RUNTIME_GLOBALS, HYPERFRAME_BRIDGE_SOURCES, HYPERFRAME_CONTROL_ACTIONS, type HyperframeControlAction, } from "./inline-scripts/runtimeContract.js";
 export { getHyperframeRuntimeScript } from "./generated/runtime-inline.js";

package/dist/previewProxyBox.d.ts

@@ -23,6 +23,8 @@ export type PreviewSourceFacts = {
     bitDepth: number;
     bitrate: number;
     codec?: string;
+    frameRate?: number;
+    variableFrameRate?: boolean;
 };
 export declare const HEAVY_PIXEL_SHARE = 0.5;
 export declare const HEAVY_BITRATE = 40000000;

package/dist/runtime/pausedVideoCallbacks.d.ts

@@ -0,0 +1,10 @@
+type Frame = Pick<VideoFrameCallbackMetadata, "mediaTime" | "width" | "height">;
+/** Install before authored scripts: Three's VideoTexture registers its first callback in its constructor. */
+export declare function installPausedVideoCallbacks(): void;
+export declare function stagePausedVideoCallbacks(video: HTMLVideoElement, frame: Frame): void;
+/** Notify once before composition redraw; callbacks registered from a callback wait for the next frame. */
+export declare function flushPausedVideoCallbacks(video: HTMLVideoElement): void;
+export declare function releasePausedVideoCallbacks(video: HTMLVideoElement): void;
+/** Recovery must observe native frames even while authored callbacks still see staged pixels. */
+export declare function observeNativeVideoFrames(video: HTMLVideoElement, onFrame: () => boolean): () => void;
+export {};

package/dist/runtime/pausedVideoCallbacks.js

@@ -0,0 +1,157 @@
+const registry = () => HTMLVideoElement.prototype.requestVideoFrameCallback?.__hfPausedCallbacks;
+function stateFor(owner, video) {
+    let state = owner.states.get(video);
+    if (!state) {
+        state = {
+            pending: new Map(),
+            frame: null,
+            count: 0,
+            nativeCount: 0,
+            synthetic: false,
+            dirty: false,
+        };
+        owner.states.set(video, state);
+    }
+    return state;
+}
+function requestNative(owner, video, state, pending, id) {
+    return owner.request.call(video, function (now, metadata) {
+        pending.native = null;
+        const advance = Math.max(0, metadata.presentedFrames - state.nativeCount);
+        state.nativeCount = metadata.presentedFrames;
+        if (state.frame)
+            return;
+        state.pending.delete(id());
+        if (!state.synthetic) {
+            state.count = metadata.presentedFrames;
+            pending.callback.call(this, now, metadata);
+            return;
+        }
+        state.count += advance;
+        pending.callback.call(this, now, { ...metadata, presentedFrames: state.count });
+    });
+}
+/** Install before authored scripts: Three's VideoTexture registers its first callback in its constructor. */
+export function installPausedVideoCallbacks() {
+    const proto = HTMLVideoElement.prototype;
+    const request = proto.requestVideoFrameCallback;
+    if (typeof request !== "function" || request.__hfPausedCallbacks)
+        return;
+    const owner = {
+        states: new WeakMap(),
+        request,
+        cancel: proto.cancelVideoFrameCallback,
+    };
+    const patched = function (callback) {
+        const state = stateFor(owner, this);
+        const pending = { callback, native: null };
+        const id = requestNative(owner, this, state, pending, () => id);
+        pending.native = id;
+        state.pending.set(id, pending);
+        return id;
+    };
+    patched.__hfPausedCallbacks = owner;
+    proto.requestVideoFrameCallback = patched;
+    proto.cancelVideoFrameCallback = function (id) {
+        const pending = owner.states.get(this)?.pending.get(id);
+        if (!pending)
+            return owner.cancel.call(this, id);
+        owner.states.get(this)?.pending.delete(id);
+        if (pending.native !== null)
+            owner.cancel.call(this, pending.native);
+    };
+}
+export function stagePausedVideoCallbacks(video, frame) {
+    const owner = registry();
+    if (!owner)
+        return;
+    const state = stateFor(owner, video);
+    state.frame = frame;
+    state.dirty = true;
+}
+/** Notify once before composition redraw; callbacks registered from a callback wait for the next frame. */
+export function flushPausedVideoCallbacks(video) {
+    const owner = registry();
+    const state = owner?.states.get(video);
+    if (!owner || !state?.frame || !state.dirty)
+        return;
+    state.dirty = false;
+    state.synthetic = true;
+    state.count++;
+    const now = performance.now();
+    const metadata = {
+        ...state.frame,
+        presentedFrames: state.count,
+        presentationTime: now,
+        expectedDisplayTime: now,
+        processingDuration: 0,
+    };
+    for (const [id, pending] of [...state.pending]) {
+        if (!state.pending.delete(id))
+            continue;
+        if (pending.native !== null)
+            owner.cancel.call(video, pending.native);
+        try {
+            pending.callback.call(undefined, now, metadata);
+        }
+        catch (error) {
+            reportError(error);
+        }
+    }
+}
+export function releasePausedVideoCallbacks(video) {
+    const owner = registry();
+    const state = owner?.states.get(video);
+    if (!owner || !state)
+        return;
+    state.frame = null;
+    state.dirty = false;
+    for (const [id, pending] of state.pending) {
+        if (pending.native === null)
+            pending.native = requestNative(owner, video, state, pending, () => id);
+    }
+}
+/** Recovery must observe native frames even while authored callbacks still see staged pixels. */
+export function observeNativeVideoFrames(video, onFrame) {
+    const owner = registry();
+    const request = owner?.request ?? video.requestVideoFrameCallback;
+    const cancel = owner?.cancel ?? video.cancelVideoFrameCallback;
+    let handle = null;
+    let stopped = false;
+    let playingAt = video.paused ? null : video.currentTime;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (handle !== null && typeof cancel === "function")
+            cancel.call(video, handle);
+        video.removeEventListener("playing", playing);
+        video.removeEventListener("timeupdate", progress);
+    };
+    const arm = () => {
+        if (!stopped && typeof request === "function")
+            handle = request.call(video, presented);
+    };
+    const presented = () => {
+        handle = null;
+        if (stopped)
+            return;
+        if (onFrame())
+            stop();
+        else
+            arm();
+    };
+    const playing = () => {
+        playingAt = video.currentTime;
+    };
+    const progress = () => {
+        if (stopped || playingAt === null || video.paused || video.currentTime === playingAt)
+            return;
+        if (onFrame())
+            stop();
+    };
+    video.addEventListener("playing", playing);
+    video.addEventListener("timeupdate", progress);
+    arm();
+    return stop;
+}

package/dist/runtime/pausedVideoFrames.d.ts

@@ -0,0 +1,52 @@
+export interface PausedVideoFrameRequest {
+    video: HTMLVideoElement;
+    source: string;
+    time: number;
+    settled?: boolean;
+}
+export interface PausedVideoFrame {
+    source: CanvasImageSource;
+    timestamp: number;
+    duration: number;
+    width: number;
+    height: number;
+    release(): void;
+}
+/** Decoding lives in the host; core owns composition timing and presentation. */
+export interface PausedVideoFrameProvider {
+    decode(requests: PausedVideoFrameRequest[], signal: AbortSignal): Promise<PausedVideoFrame[]>;
+    suspend?(): Promise<void>;
+    dispose(): void;
+}
+export interface PreparedPausedVideoFrames {
+    valid(): boolean;
+    present(): boolean;
+    refresh(): void;
+    release(): void;
+}
+export declare function getPausedVideoFrame(video: HTMLVideoElement): HTMLCanvasElement | null;
+export declare function ownsPausedVideoTime(video: HTMLMediaElement): boolean;
+export declare function getPausedExternalVideoFrame(video: HTMLVideoElement): VideoFrame | null;
+export declare function captureNativeVideoFrame(video: HTMLVideoElement): HTMLCanvasElement | null;
+export declare function nativeSnapshotStyle(video: HTMLVideoElement): CSSStyleDeclaration | null;
+export declare function releasePausedVideoFrame(video: HTMLVideoElement): void;
+/** Keeps original nodes, URLs, intrinsic sizes and the displayed source clock intact. */
+export declare function createPausedVideoFrames(): {
+    readonly active: boolean;
+    holdNative(videos: HTMLVideoElement[]): () => void;
+    skipped: (el: HTMLMediaElement) => boolean;
+    retained: (el: HTMLMediaElement) => boolean;
+    available: () => boolean;
+    setProvider(next: PausedVideoFrameProvider | null): void;
+    prepare(requests: PausedVideoFrameRequest[], signal: AbortSignal): Promise<{
+        valid: () => boolean;
+        present(): boolean;
+        refresh(): void;
+        release: () => void;
+    } | null>;
+    suspendProvider: () => Promise<void> | undefined;
+    prepareNative(): void;
+    notify(): void;
+    clear: (keep?: Set<HTMLVideoElement>, current?: (video: HTMLVideoElement, presented: boolean) => boolean) => void;
+    destroy(): void;
+};

package/dist/runtime/pausedVideoFrames.js

@@ -0,0 +1,366 @@
+import { MEDIA_ELEMENT_LEAD_SECONDS } from "./mediaClock.js";
+import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "../colorGrading.js";
+import { installPausedVideoCallbacks, stagePausedVideoCallbacks, flushPausedVideoCallbacks, releasePausedVideoCallbacks, observeNativeVideoFrames, } from "./pausedVideoCallbacks.js";
+import { PREVIEW_VIDEO_FRAME_ATTR as FRAME_ATTR, PREVIEW_VIDEO_SOURCE_ATTR, PREVIEW_VIDEO_CANVAS_ATTR, } from "../studioPreviewMark.js";
+const SURFACE_BUDGET = 128 * 1024 * 1024;
+const presented = new Map();
+const authoredSeeks = new WeakSet();
+export function getPausedVideoFrame(video) {
+    return presented.get(video)?.canvas ?? null;
+}
+export function ownsPausedVideoTime(video) {
+    return presented.get(video)?.driving === true;
+}
+export function getPausedExternalVideoFrame(video) {
+    const entry = presented.get(video);
+    if (!entry || typeof VideoFrame === "undefined")
+        return null;
+    entry.gpuFrame ??= new VideoFrame(entry.canvas, { timestamp: Math.round(entry.time * 1e6) });
+    return entry.gpuFrame;
+}
+export function captureNativeVideoFrame(video) {
+    const canvas = document.createElement("canvas");
+    canvas.width = video.videoWidth;
+    canvas.height = video.videoHeight;
+    const context = canvas.getContext("2d");
+    if (!context)
+        return null;
+    try {
+        context.drawImage(video, 0, 0);
+        return canvas;
+    }
+    catch {
+        return null;
+    }
+}
+export function nativeSnapshotStyle(video) {
+    if (getPausedVideoFrame(video))
+        return null;
+    // Its grading canvas already holds the picture; hiding the source would retire that canvas on refresh.
+    if (video.hasAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR))
+        return null;
+    const css = getComputedStyle(video);
+    if (css.display === "none" || css.visibility === "hidden" || video.readyState < 2)
+        return null;
+    if (!video.videoWidth || !video.videoHeight)
+        return null;
+    return css;
+}
+function virtualTime(entry) {
+    let proto = Object.getPrototypeOf(entry.video);
+    let descriptor;
+    while (proto && !descriptor) {
+        descriptor = Object.getOwnPropertyDescriptor(proto, "currentTime");
+        proto = Object.getPrototypeOf(proto);
+    }
+    const nativeSet = descriptor?.set;
+    Object.defineProperty(entry.video, "currentTime", {
+        configurable: true,
+        get: () => entry.time,
+        set: (value) => {
+            if (Math.abs(value - entry.time) <= MEDIA_ELEMENT_LEAD_SECONDS * 2)
+                return;
+            authoredSeeks.add(entry.video);
+            remove(entry);
+            nativeSet?.call(entry.video, value);
+        },
+    });
+    entry.restoreTime = () => {
+        Reflect.deleteProperty(entry.video, "currentTime");
+    };
+}
+function remove(entry) {
+    entry.stopWaiting?.();
+    entry.restoreTime();
+    releasePausedVideoCallbacks(entry.video);
+    entry.gpuFrame?.close();
+    entry.video.removeAttribute(FRAME_ATTR);
+    entry.video.removeAttribute(PREVIEW_VIDEO_SOURCE_ATTR);
+    entry.canvas.remove();
+    entry.canvas.width = entry.canvas.height = 0;
+    presented.delete(entry.video);
+}
+export function releasePausedVideoFrame(video) {
+    const entry = presented.get(video);
+    if (entry)
+        remove(entry);
+}
+function refresh(entry) {
+    const { video, canvas } = entry;
+    video.removeAttribute(FRAME_ATTR);
+    if (video.hasAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR)) {
+        canvas.remove();
+        return;
+    }
+    const css = getComputedStyle(video);
+    for (const key of Array.from(css)) {
+        const value = css.getPropertyValue(key);
+        if (canvas.style.getPropertyValue(key) !== value)
+            canvas.style.setProperty(key, value);
+    }
+    if (css.position !== "absolute" && css.position !== "fixed") {
+        canvas.style.position = "absolute";
+        canvas.style.inset = "auto";
+        canvas.style.left = `${video.offsetLeft}px`;
+        canvas.style.top = `${video.offsetTop}px`;
+        canvas.style.margin = "0";
+    }
+    canvas.style.setProperty("pointer-events", "none", "important");
+    canvas.style.setProperty("animation", "none", "important");
+    canvas.style.setProperty("transition", "none", "important");
+    if (video.previousElementSibling !== canvas)
+        video.before(canvas);
+    video.setAttribute(FRAME_ATTR, "");
+}
+function markFrameCanvas(canvas) {
+    canvas.setAttribute(PREVIEW_VIDEO_CANVAS_ATTR, "");
+    canvas.setAttribute("data-layout-ignore", "");
+    canvas.setAttribute("data-hyperframes-ignore", "");
+    canvas.setAttribute("data-hyperframes-picker-ignore", "");
+    canvas.setAttribute("data-hf-ignore", "");
+    canvas.setAttribute("aria-hidden", "true");
+}
+function adoptStagedFrame(next, existing) {
+    if (existing) {
+        const { entry, context } = existing;
+        entry.stopWaiting?.();
+        entry.stopWaiting = undefined;
+        entry.gpuFrame?.close();
+        entry.gpuFrame = undefined;
+        context.clearRect(0, 0, entry.canvas.width, entry.canvas.height);
+        context.drawImage(next.canvas, 0, 0);
+        next.canvas.width = next.canvas.height = 0;
+        entry.time = next.time;
+        if (!entry.driving)
+            virtualTime(entry);
+        entry.driving = true;
+        return;
+    }
+    const { video, canvas } = next;
+    releasePausedVideoFrame(video);
+    markFrameCanvas(canvas);
+    presented.set(video, next);
+    video.setAttribute(PREVIEW_VIDEO_SOURCE_ATTR, "");
+    virtualTime(next);
+}
+/** Keeps original nodes, URLs, intrinsic sizes and the displayed source clock intact. */
+export function createPausedVideoFrames() {
+    installPausedVideoCallbacks();
+    let provider = null;
+    const style = document.createElement("style");
+    style.textContent = `[${FRAME_ATTR}] { opacity: 0 !important; }`;
+    const observer = new MutationObserver((records) => {
+        for (const entry of [...presented.values()]) {
+            if (!entry.video.isConnected ||
+                records.some((record) => (record.type === "childList" && record.target === entry.video) ||
+                    (record.type === "attributes" &&
+                        record.attributeName === "src" &&
+                        (record.target === entry.video || record.target.parentElement === entry.video))))
+                remove(entry);
+            else if (records.some((record) => record.target.contains(entry.video)))
+                refresh(entry);
+        }
+    });
+    observer.observe(document.body, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ["src", "style", "class", "hidden", "data-hidden"],
+    });
+    const clear = (keep, current) => {
+        for (const entry of [...presented.values()]) {
+            if (!keep?.has(entry.video)) {
+                remove(entry);
+                continue;
+            }
+            entry.nativeSkipped = true;
+            const reveal = (nativeFrame) => {
+                if (presented.get(entry.video) !== entry)
+                    return true;
+                if (entry.video.readyState < 2 ||
+                    entry.video.seeking ||
+                    (current && !current(entry.video, nativeFrame)))
+                    return false;
+                remove(entry);
+                return true;
+            };
+            const ready = () => {
+                reveal(false);
+            };
+            const events = ["loadeddata", "canplay", "seeked"];
+            entry.stopWaiting?.();
+            for (const event of events)
+                entry.video.addEventListener(event, ready);
+            const stopFrames = observeNativeVideoFrames(entry.video, () => reveal(true));
+            entry.stopWaiting = () => {
+                for (const event of events)
+                    entry.video.removeEventListener(event, ready);
+                stopFrames();
+            };
+        }
+        if (presented.size === 0)
+            style.remove();
+    };
+    return {
+        get active() {
+            // A skipped native clip may keep a fallback picture without owning paused playback.
+            return [...presented.values()].some((entry) => !entry.stopWaiting);
+        },
+        holdNative(videos) {
+            const held = [];
+            for (const video of videos) {
+                if (!nativeSnapshotStyle(video))
+                    continue;
+                const canvas = captureNativeVideoFrame(video);
+                if (!canvas)
+                    continue;
+                const entry = {
+                    video,
+                    canvas,
+                    time: video.currentTime,
+                    driving: false,
+                    restoreTime: () => { },
+                };
+                held.push(entry);
+                markFrameCanvas(canvas);
+                presented.set(video, entry);
+                video.setAttribute(PREVIEW_VIDEO_SOURCE_ATTR, "");
+                if (!style.isConnected)
+                    document.head.append(style);
+                refresh(entry);
+            }
+            return () => {
+                for (const entry of held)
+                    if (presented.get(entry.video) === entry && !entry.driving)
+                        remove(entry);
+            };
+        },
+        skipped: (el) => presented.get(el)?.nativeSkipped === true,
+        retained: (el) => presented.get(el)?.stopWaiting !== undefined,
+        available: () => provider !== null,
+        setProvider(next) {
+            if (provider === next)
+                return;
+            provider?.dispose();
+            provider = next;
+        },
+        async prepare(requests, signal) {
+            if (!provider ||
+                requests.length === 0 ||
+                requests.some(({ video }) => authoredSeeks.has(video) ||
+                    (!presented.has(video) && Object.hasOwn(video, "currentTime"))))
+                return null;
+            const owner = provider;
+            const identity = (video) => JSON.stringify([
+                video.src,
+                ...Array.from(video.querySelectorAll("source"), (source) => source.src),
+            ]);
+            const sources = requests.map(({ video }) => identity(video));
+            const frames = await owner.decode(requests, signal);
+            let released = false;
+            const release = () => {
+                if (released)
+                    return;
+                released = true;
+                for (const frame of frames)
+                    frame.release();
+            };
+            const current = () => !signal.aborted &&
+                provider === owner &&
+                requests.every(({ video }, index) => video.isConnected && identity(video) === sources[index]);
+            if (!current()) {
+                release();
+                return null;
+            }
+            const valid = frames.reduce((sum, frame) => sum + frame.width * frame.height * 4, 0) <= SURFACE_BUDGET &&
+                frames.length === requests.length &&
+                frames.every((frame, index) => {
+                    const time = requests[index].time;
+                    return (frame.width > 0 &&
+                        frame.height > 0 &&
+                        frame.timestamp <= time + 1e-5 &&
+                        time < frame.timestamp + frame.duration + 1e-5);
+                });
+            if (!valid) {
+                release();
+                return null;
+            }
+            return {
+                valid: current,
+                present() {
+                    if (!current()) {
+                        release();
+                        return false;
+                    }
+                    const staged = [];
+                    const reusable = new Map();
+                    try {
+                        frames.forEach((frame, index) => {
+                            const { video, time } = requests[index];
+                            const canvas = document.createElement("canvas");
+                            canvas.width = frame.width;
+                            canvas.height = frame.height;
+                            staged.push({ video, canvas, time, driving: true, restoreTime: () => { } });
+                            const context = canvas.getContext("2d");
+                            if (!context)
+                                throw new Error("Preview canvas unavailable");
+                            context.drawImage(frame.source, 0, 0, canvas.width, canvas.height);
+                            const prior = presented.get(video);
+                            if (prior &&
+                                prior.canvas.width === frame.width &&
+                                prior.canvas.height === frame.height) {
+                                const destination = prior.canvas.getContext("2d");
+                                if (!destination)
+                                    throw new Error("Preview canvas unavailable");
+                                reusable.set(staged[staged.length - 1], { entry: prior, context: destination });
+                            }
+                        });
+                    }
+                    catch {
+                        for (const { canvas } of staged)
+                            canvas.width = canvas.height = 0;
+                        return false;
+                    }
+                    finally {
+                        release();
+                    }
+                    const wanted = new Set(requests.map(({ video }) => video));
+                    for (const entry of [...presented.values()])
+                        if (!wanted.has(entry.video))
+                            remove(entry);
+                    if (!style.isConnected)
+                        document.head.append(style);
+                    for (const [index, next] of staged.entries()) {
+                        adoptStagedFrame(next, reusable.get(next));
+                        const { timestamp, width, height } = frames[index];
+                        stagePausedVideoCallbacks(next.video, { mediaTime: timestamp, width, height });
+                    }
+                    return true;
+                },
+                refresh() {
+                    for (const entry of presented.values())
+                        refresh(entry);
+                },
+                release,
+            };
+        },
+        suspendProvider: () => provider?.suspend?.(),
+        prepareNative() {
+            for (const entry of presented.values()) {
+                entry.driving = false;
+                entry.restoreTime();
+            }
+        },
+        notify() {
+            for (const { video } of presented.values())
+                flushPausedVideoCallbacks(video);
+        },
+        clear,
+        destroy() {
+            observer.disconnect();
+            clear();
+            provider?.dispose();
+            provider = null;
+        },
+    };
+}

package/dist/runtime/types.d.ts

@@ -229,6 +229,13 @@ export type RuntimePreviewCopiesMessage = {
         error: string | null;
     } | null;
 };
+export type FetchNotSeenToStart = null;
+export type PlaybackHeldBy = {
+    kind: "audio" | "video";
+    readyState: number;
+    networkState: number;
+    fetchMs: number | FetchNotSeenToStart;
+};
 export type RuntimePreviewHealthMessage = {
     source: "hf-preview";
     type: "preview-health";
@@ -245,6 +252,7 @@ export type RuntimePreviewHealthMessage = {
         gapP50Ms: number;
         gapP95Ms: number;
         clockSource: "audio" | "webaudio" | "monotonic";
+        heldBy: PlaybackHeldBy | null;
         mode: "play";
     } | null;
 };
@@ -275,6 +283,7 @@ export type RuntimePlayer = {
     pause: () => void;
     seek: (timeSeconds: number, options?: {
         keepPlaying?: boolean;
+        settled?: boolean;
     }) => HeldSeek;
     renderSeek: (timeSeconds: number, options?: RuntimeSeekOptions) => void;
     getTime: () => number;

package/dist/studioPreviewMark.d.ts

@@ -1,4 +1,8 @@
 export declare const STUDIO_PREVIEW_MARK_META = "hyperframes-studio-preview";
+export declare const PREVIEW_SEEK_HOLD_ATTR = "data-hf-preview-seek-hold";
+export declare const PREVIEW_VIDEO_FRAME_ATTR = "data-hf-preview-video-frame";
+export declare const PREVIEW_VIDEO_SOURCE_ATTR = "data-hf-preview-video-source";
+export declare const PREVIEW_VIDEO_CANVAS_ATTR = "data-hf-preview-video-canvas";
 export declare const STUDIO_PREVIEW_CAPTURE_MODE = "capture";
 export declare const PLAYER_FRAME_ATTR = "data-hf-player-frame";
 export declare function inPlayerFrame(doc: Document): boolean;
@@ -14,6 +18,6 @@ export declare const RUNTIME_STAMPED_ATTR = "data-hf-autostamped";
 export declare const CLIP_HIDDEN_ATTR = "data-hf-clip-hidden";
 export declare const STUDIO_PREVIEW_FAR_SCENE_ATTR = "data-hf-far-scene";
 export declare const STUDIO_PREVIEW_PARKED_SCENE_ATTR = "data-hf-parked-scene";
-export declare const PREVIEW_ONLY_ATTRS: readonly ["data-hf-upcoming", "data-hf-far-scene", "data-hf-parked-scene", "data-hf-preview-lazy", "data-hf-preview-raster", "data-hf-autostamped"];
+export declare const PREVIEW_ONLY_ATTRS: readonly ["data-hf-preview-video-frame", "data-hf-preview-video-source", "data-hf-preview-video-canvas", "data-hf-upcoming", "data-hf-far-scene", "data-hf-parked-scene", "data-hf-preview-lazy", "data-hf-preview-raster", "data-hf-autostamped"];
 export declare const isClipHiddenByRuntime: (el: HTMLElement) => boolean;
 export declare function applyAuthoredTiming(el: Element, attrs: ReadonlyArray<readonly [name: string, value: string]>): void;

package/dist/studioPreviewMark.js

@@ -1,5 +1,9 @@
 import { isWebKit } from "./runtime/mediaClock.js";
 export const STUDIO_PREVIEW_MARK_META = "hyperframes-studio-preview";
+export const PREVIEW_SEEK_HOLD_ATTR = "data-hf-preview-seek-hold";
+export const PREVIEW_VIDEO_FRAME_ATTR = "data-hf-preview-video-frame";
+export const PREVIEW_VIDEO_SOURCE_ATTR = "data-hf-preview-video-source";
+export const PREVIEW_VIDEO_CANVAS_ATTR = "data-hf-preview-video-canvas";
 export const STUDIO_PREVIEW_CAPTURE_MODE = "capture";
 export const PLAYER_FRAME_ATTR = "data-hf-player-frame";
 export function inPlayerFrame(doc) {
@@ -23,6 +27,9 @@ export const CLIP_HIDDEN_ATTR = "data-hf-clip-hidden";
 export const STUDIO_PREVIEW_FAR_SCENE_ATTR = "data-hf-far-scene";
 export const STUDIO_PREVIEW_PARKED_SCENE_ATTR = "data-hf-parked-scene";
 export const PREVIEW_ONLY_ATTRS = [
+    PREVIEW_VIDEO_FRAME_ATTR,
+    PREVIEW_VIDEO_SOURCE_ATTR,
+    PREVIEW_VIDEO_CANVAS_ATTR,
     STUDIO_PREVIEW_UPCOMING_ATTR,
     STUDIO_PREVIEW_FAR_SCENE_ATTR,
     STUDIO_PREVIEW_PARKED_SCENE_ATTR,