@hyperframes/core 0.9.20 → 0.9.22

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

@@ -275,6 +275,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/runtime/wallClock.d.ts

@@ -0,0 +1,8 @@
+type TimeoutId = ReturnType<typeof setTimeout>;
+type IntervalId = ReturnType<typeof setInterval>;
+type Handler = (...args: never[]) => void;
+export declare function wallSetTimeout(handler: Handler, timeout?: number, ...args: unknown[]): TimeoutId;
+export declare function wallClearTimeout(id: TimeoutId | null | undefined): void;
+export declare function wallSetInterval(handler: Handler, timeout?: number, ...args: unknown[]): IntervalId;
+export declare function wallClearInterval(id: IntervalId | null | undefined): void;
+export {};

package/dist/runtime/wallClock.js

@@ -0,0 +1,13 @@
+const shim = () => globalThis.__HF_VIRTUAL_TIME__;
+export function wallSetTimeout(handler, timeout, ...args) {
+    return (shim()?.originalSetTimeout ?? setTimeout)(handler, timeout, ...args);
+}
+export function wallClearTimeout(id) {
+    (shim()?.originalClearTimeout ?? clearTimeout)(id ?? undefined);
+}
+export function wallSetInterval(handler, timeout, ...args) {
+    return (shim()?.originalSetInterval ?? setInterval)(handler, timeout, ...args);
+}
+export function wallClearInterval(id) {
+    (shim()?.originalClearInterval ?? clearInterval)(id ?? undefined);
+}

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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.9.20",
+  "version": "0.9.22",
   "description": "",
   "repository": {
     "type": "git",
@@ -437,9 +437,9 @@
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
     "wawoff2": "^2.0.1",
-    "@hyperframes/lint": "0.9.20",
-    "@hyperframes/studio-server": "0.9.20",
-    "@hyperframes/parsers": "0.9.20"
+    "@hyperframes/lint": "0.9.22",
+    "@hyperframes/studio-server": "0.9.22",
+    "@hyperframes/parsers": "0.9.22"
   },
   "devDependencies": {
     "@fontsource/archivo-black": "^5.2.8",