@hyperframes/core 0.9.20 → 0.9.22

package/dist/index.d.ts

@@ -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/bridge.js

@@ -1,3 +1,4 @@
+import { wallSetTimeout } from "./wallClock.js";
 import { swallow } from "./diagnostics.js";
 import { inspectRuntimeProtocol, runtimeProtocolFpsToNumber, runtimeProtocolMetadata, } from "./protocol.js";
 let runtimeProtocolFps = 30;
@@ -134,7 +135,7 @@ function flashElements(selectors, duration) {
             const els = document.querySelectorAll(selector);
             els.forEach((el) => {
                 el.classList.add("__hf-flash");
-                setTimeout(() => el.classList.remove("__hf-flash"), duration);
+                wallSetTimeout(() => el.classList.remove("__hf-flash"), duration);
             });
         }
         catch (err) {

package/dist/runtime/clock.d.ts

@@ -30,6 +30,8 @@ export declare class TransportClock {
     private _lastReadMs;
     private _lastNow;
     private _audioStart;
+    private _reading;
+    private _ahead;
     constructor(opts?: {
         initialTime?: number;
         rate?: number;
@@ -38,6 +40,9 @@ export declare class TransportClock {
     });
     now(): number;
     private _elementTimeNeverBehind;
+    private _betweenUpdates;
+    private _runAhead;
+    aheadOf(el: HTMLMediaElement): number;
     private _heldUntilAudioOutputStarts;
     private _pendingAudioStart;
     /** Folds a >500ms gap since the last read into `_playStartMs` so it's never reported as played time. */

package/dist/runtime/clock.js

@@ -6,6 +6,15 @@ const STALL_ADJUSTED_LAG_MS = 33;
 const HAVE_FUTURE_DATA = 3;
 const AUDIO_START_WAIT_MS = 1500;
 const MEDIA_SYNC_STEER_TOLERANCE_SECONDS = 0.04;
+const MAX_MEDIA_STEP_SECONDS = 0.25;
+const MEDIA_STEPS_KEPT = 8;
+const furthestAhead = (reading) => reading ? Math.max(0, ...reading.steps) : 0;
+function noteStep(reading, time) {
+    const step = time - reading.time;
+    if (step > 0 && step <= MAX_MEDIA_STEP_SECONDS)
+        reading.steps = [...reading.steps.slice(1 - MEDIA_STEPS_KEPT), step];
+    reading.time = time;
+}
 export class TransportClock {
     _baseTime = 0;
     _playStartMs = null;
@@ -20,6 +29,8 @@ export class TransportClock {
     _lastReadMs = null;
     _lastNow = 0;
     _audioStart = null;
+    _reading = null;
+    _ahead = null;
     constructor(opts) {
         this._baseTime = opts?.initialTime ?? 0;
         this._rate = opts?.rate ?? 1;
@@ -27,6 +38,7 @@ export class TransportClock {
         this._nowMs = opts?.nowMs ?? (() => performance.now());
     }
     now() {
+        this._ahead = null;
         if (this._playStartMs === null)
             return this._baseTime;
         // Audio-master: drift is impossible because audio IS the clock. Clearing
@@ -63,13 +75,42 @@ export class TransportClock {
         const spec = rate ?? 1;
         const time = timeAtSourceTime(spec, el.currentTime - mediaStart) + compositionStart;
         const held = this._heldUntilAudioOutputStarts(el.seeking, time);
-        if (held !== undefined)
+        if (held !== undefined) {
+            this._reading = null;
             return held;
-        if (time >= this._lastNow)
-            return time;
+        }
+        const between = this._betweenUpdates(el, time);
+        if (between !== null)
+            return between;
         const wrapped = el.loop && this._lastNow - time > timeAtSourceTime(spec, el.duration) / 2;
         return !wrapped && el.readyState < HAVE_FUTURE_DATA ? this._lastNow : null;
     }
+    // Chromium moves currentTime in 10-50 ms steps, so reading it as is holds a frame, then jumps. Run on at the play
+    // rate, kept within [element time, element time + its largest recent step], never back; null when time is behind
+    // the playhead by more than that step (a late clip, not a step).
+    _betweenUpdates(el, time) {
+        const nowMs = this._nowMs();
+        const last = this._reading?.el === el ? this._reading : null;
+        if (time < this._lastNow - furthestAhead(last))
+            return null;
+        if (!last) {
+            this._reading = { el, time, steps: [], from: time, fromMs: nowMs };
+            return this._runAhead(el, time, Math.max(time, this._lastNow));
+        }
+        noteStep(last, time);
+        const run = last.from + ((nowMs - last.fromMs) / 1000) * this._rate;
+        const held = Math.min(Math.max(run, time), time + furthestAhead(last));
+        if (held !== run)
+            Object.assign(last, { from: held, fromMs: nowMs });
+        return this._runAhead(el, time, Math.max(held, this._lastNow));
+    }
+    _runAhead(el, time, now) {
+        this._ahead = { el, seconds: now - time };
+        return now;
+    }
+    aheadOf(el) {
+        return this._ahead?.el === el ? this._ahead.seconds : 0;
+    }
     _heldUntilAudioOutputStarts(seeking, time) {
         const pending = this._pendingAudioStart();
         if (seeking)
@@ -110,6 +151,7 @@ export class TransportClock {
         this._playStartMs = this._nowMs();
         this._audioStart = { sinceMs: this._playStartMs, at: this._baseTime, from: null };
         this._lastNow = this._baseTime;
+        this._reading = null;
         // Not a stall: the gap since the clock was last read (possibly a long
         // paused idle) says nothing about lost playback time, since none was
         // playing. `_applyStallCorrection` treats null as "nothing to compare
@@ -122,6 +164,7 @@ export class TransportClock {
             return false;
         this._baseTime = this.now();
         this._playStartMs = null;
+        this._reading = null;
         return true;
     }
     seek(timeSeconds) {
@@ -130,6 +173,7 @@ export class TransportClock {
             : Math.max(0, timeSeconds);
         this._baseTime = clamped;
         this._lastNow = clamped;
+        this._reading = null;
         if (this._playStartMs !== null) {
             this._playStartMs = this._nowMs();
             this._audioStart = { sinceMs: this._playStartMs, at: clamped, from: null };
@@ -143,6 +187,7 @@ export class TransportClock {
     }
     setRate(rate) {
         const safe = Number.isFinite(rate) && rate > 0 ? Math.max(0.1, Math.min(5, rate)) : 1;
+        this._reading = null;
         if (this._playStartMs !== null) {
             this._baseTime = this.now();
             this._playStartMs = this._nowMs();
@@ -189,6 +234,7 @@ export class TransportClock {
             this._lastReadMs = null;
         }
         this._audioSource = null;
+        this._reading = null;
     }
     /** The element the playhead currently follows, if the source is one. */
     // fallow-ignore-next-line unused-class-member

package/dist/runtime/mediaSteer.d.ts

@@ -3,7 +3,7 @@ export declare const MEDIA_SYNC_TOLERANCE_SECONDS = 0.04;
 export declare const MEDIA_HARD_SYNC_SECONDS = 0.5;
 export declare function markMediaRestarted(el: HTMLMediaElement): void;
 /** Rate or seek for media `offset` s behind (+) or ahead (-); a lag still growing (`settled` false) never seeks. */
-export declare function steerMedia(el: HTMLMediaElement, offset: number, baseRate: number, settled: boolean, audioOnly?: boolean, hidden?: boolean): {
+export declare function steerMedia(el: HTMLMediaElement, offset: number, baseRate: number, settled: boolean, audioOnly?: boolean): {
     rate: number;
     seek: boolean;
 };

package/dist/runtime/mediaSteer.js

@@ -13,8 +13,6 @@ const MEDIA_STEER_RELEASE_SECONDS = 0.01;
 const AUDIO_MAX_STEER = 0.1;
 const AUDIO_STEER_LIMIT_SECONDS = 0.1;
 const WEBKIT_AUDIO_START_LAG_SECONDS = 0.65;
-// A video nobody sees runs up to twice as fast (half as slow) to reach the playhead: the lag in seconds times this.
-const HIDDEN_GAIN = 5;
 /** Direction (+1 fast, -1 slow) an element is being steered in; absent when it plays at its authored rate. */
 const steering = new WeakMap();
 /** Started or seeked, not yet moving in tolerance: its lag is its own output latency, which a seek only renews. */
@@ -23,7 +21,7 @@ export function markMediaRestarted(el) {
     catchingUp.add(el);
 }
 /** Rate or seek for media `offset` s behind (+) or ahead (-); a lag still growing (`settled` false) never seeks. */
-export function steerMedia(el, offset, baseRate, settled, audioOnly = el.tagName === "AUDIO", hidden = false) {
+export function steerMedia(el, offset, baseRate, settled, audioOnly = el.tagName === "AUDIO") {
     const lag = Math.abs(offset);
     if (audioOnly && isWebKit()) {
         steering.delete(el);
@@ -38,8 +36,6 @@ export function steerMedia(el, offset, baseRate, settled, audioOnly = el.tagName
         return { rate: baseRate, seek: true };
     }
     const direction = Math.sign(offset);
-    if (hidden && lag > MEDIA_SYNC_TOLERANCE_SECONDS)
-        return steerHidden(el, direction, lag, baseRate);
     const current = steering.get(el);
     if (lag > MEDIA_SYNC_TOLERANCE_SECONDS)
         steering.set(el, direction);
@@ -51,11 +47,6 @@ export function steerMedia(el, offset, baseRate, settled, audioOnly = el.tagName
     const steer = audioOnly ? Math.min(step, AUDIO_MAX_STEER) : step;
     return { rate: baseRate * (1 + direction * steer), seek: false };
 }
-function steerHidden(el, direction, lag, baseRate) {
-    steering.set(el, direction);
-    const steer = Math.min(direction > 0 ? 1 : 0.5, lag * HIDDEN_GAIN);
-    return { rate: baseRate * (1 + direction * steer), seek: false };
-}
 /** Drop `el`'s steering: it was seeked, paused or replaced, so its old offset says nothing. */
 export function forgetSteering(el) {
     steering.delete(el);

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;
+};