@hyperframes/core 0.8.206 → 0.8.208

package/dist/removeTree.d.ts

@@ -0,0 +1,24 @@
+declare const RETRY: {
+    readonly recursive: true;
+    readonly force: true;
+    readonly maxRetries: 10;
+    readonly retryDelay: 100;
+};
+type RemoveSync = (path: string, options: typeof RETRY) => void;
+type RemoveAsync = (path: string, options: typeof RETRY) => Promise<void>;
+type Warn = (message: string) => void;
+/** Removes a tree the next step needs gone, riding out transient locks; throws if it still fails. */
+export declare function removeTreeWithRetry(path: string, remove?: RemoveSync): void;
+/** Async twin of {@link removeTreeWithRetry}. */
+export declare function removeTreeWithRetryAsync(path: string, remove?: RemoveAsync): Promise<void>;
+/** Cleans up after finished work: a refusal that outlasts the retries is warned about, never thrown. */
+export declare function removeTreeBestEffort(path: string, options?: {
+    remove?: RemoveSync;
+    warn?: Warn;
+}): void;
+/** Async twin of {@link removeTreeBestEffort}. */
+export declare function removeTreeBestEffortAsync(path: string, options?: {
+    remove?: RemoveAsync;
+    warn?: Warn;
+}): Promise<void>;
+export {};

package/dist/removeTree.js

@@ -0,0 +1,35 @@
+import { rmSync } from "node:fs";
+import { rm } from "node:fs/promises";
+// Windows holds files for a moment after a process exits or while antivirus scans them (EBUSY,
+// EPERM, ENOTEMPTY). Node retries those itself when asked: about 5.5 s in all.
+const RETRY = { recursive: true, force: true, maxRetries: 10, retryDelay: 100 };
+function refusal(path, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return `[cleanup] could not remove ${path}: ${reason}`;
+}
+/** Removes a tree the next step needs gone, riding out transient locks; throws if it still fails. */
+export function removeTreeWithRetry(path, remove = rmSync) {
+    remove(path, RETRY);
+}
+/** Async twin of {@link removeTreeWithRetry}. */
+export async function removeTreeWithRetryAsync(path, remove = rm) {
+    await remove(path, RETRY);
+}
+/** Cleans up after finished work: a refusal that outlasts the retries is warned about, never thrown. */
+export function removeTreeBestEffort(path, options = {}) {
+    try {
+        removeTreeWithRetry(path, options.remove);
+    }
+    catch (error) {
+        (options.warn ?? console.warn)(refusal(path, error));
+    }
+}
+/** Async twin of {@link removeTreeBestEffort}. */
+export async function removeTreeBestEffortAsync(path, options = {}) {
+    try {
+        await removeTreeWithRetryAsync(path, options.remove);
+    }
+    catch (error) {
+        (options.warn ?? console.warn)(refusal(path, error));
+    }
+}

package/dist/runtime/clock.js

@@ -1,5 +1,5 @@
 import { timeAtSourceTime } from "../speedRamp.js";
-import { MEDIA_HARD_SYNC_SECONDS } from "./media.js";
+import { MEDIA_HARD_SYNC_SECONDS } from "./mediaSteer.js";
 import { playRangeHoldTime } from "./protocol.js";
 /** GSAP's own `lagSmoothing` default — see the PR body for why this clock needs its own copy. */
 const STALL_THRESHOLD_MS = 500;

package/dist/runtime/mediaSteer.d.ts

@@ -0,0 +1,11 @@
+/** Drift a playing element may carry before sync pulls it back onto the playhead. */
+export declare const MEDIA_SYNC_TOLERANCE_SECONDS = 0.04;
+export declare const MEDIA_HARD_SYNC_SECONDS = 0.5;
+/** 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): {
+    rate: number;
+    seek: boolean;
+};
+/** Drop `el`'s steering: it was seeked, paused or replaced, so its old offset says nothing. */
+export declare function forgetSteering(el: HTMLMediaElement): void;
+export declare function isSteering(el: HTMLMediaElement): boolean;

package/dist/runtime/mediaSteer.js

@@ -0,0 +1,41 @@
+/** Drift a playing element may carry before sync pulls it back onto the playhead. */
+export const MEDIA_SYNC_TOLERANCE_SECONDS = 0.04;
+export const MEDIA_HARD_SYNC_SECONDS = 0.5;
+// Steered by rate, not seeked (a seek resets a video's decoder and clicks in audio); steps keep rate writes rare.
+const MEDIA_STEER = 0.03;
+const MEDIA_STEER_STEPS = [
+    [0.3, 0.25],
+    [0.1, 0.1],
+];
+const MEDIA_STEER_RELEASE_SECONDS = 0.01;
+// Audio never steers past 10%, where speech changes tempo; a lag held past 100 ms is seeked instead.
+const AUDIO_MAX_STEER = 0.1;
+const AUDIO_STEER_LIMIT_SECONDS = 0.1;
+/** Direction (+1 fast, -1 slow) an element is being steered in; absent when it plays at its authored rate. */
+const steering = new WeakMap();
+/** 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") {
+    const lag = Math.abs(offset);
+    if (audioOnly && settled && lag > AUDIO_STEER_LIMIT_SECONDS) {
+        steering.delete(el);
+        return { rate: baseRate, seek: true };
+    }
+    const direction = Math.sign(offset);
+    const current = steering.get(el);
+    if (lag > MEDIA_SYNC_TOLERANCE_SECONDS)
+        steering.set(el, direction);
+    else if (current !== direction || lag <= MEDIA_STEER_RELEASE_SECONDS) {
+        steering.delete(el);
+        return { rate: baseRate, seek: false };
+    }
+    const step = MEDIA_STEER_STEPS.find(([from]) => lag > from)?.[1] ?? MEDIA_STEER;
+    const steer = audioOnly ? Math.min(step, AUDIO_MAX_STEER) : step;
+    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);
+}
+export function isSteering(el) {
+    return steering.has(el);
+}

package/dist/runtime/protocol.js

@@ -20,7 +20,8 @@ function greatestCommonDivisor(a, b) {
 }
 export function runtimeProtocolFpsFromNumber(value) {
     const safe = Number.isFinite(value) && value > 0 ? value : 30;
-    const denominator = Number.isInteger(safe) ? 1 : 1_000_000;
+    const isNtscRate = Math.abs(safe * 1001 - Math.round(safe * 1001)) < 1e-6;
+    const denominator = Number.isInteger(safe) ? 1 : isNtscRate ? 1001 : 1_000_000;
     const numerator = Math.round(safe * denominator);
     const divisor = greatestCommonDivisor(numerator, denominator);
     return { numerator: numerator / divisor, denominator: denominator / divisor };

package/dist/runtime/state.d.ts

@@ -1,5 +1,4 @@
-import type { RuntimeDeterministicAdapter, RuntimeTimelineLike } from "./types.js";
-import type { RuntimeMediaClip } from "./media.js";
+import type { RuntimeDeterministicAdapter, RuntimeMediaClip, RuntimeTimelineLike } from "./types.js";
 import type { TransportClock } from "./clock.js";
 export type RuntimeState = {
     capturedTimeline: RuntimeTimelineLike | null;

package/dist/runtime/timeline.js

@@ -3,7 +3,7 @@ import { findRootCompositionElement, parseCompositionDimension } from "./composi
 import { AUTHORED_DURATION_ATTR, AUTHORED_END_ATTR, resolveAuthoredTimingWindow, } from "./authoredTiming.js";
 import { swallow } from "./diagnostics.js";
 import { readTimelineDurationSeconds } from "./timelineDuration.js";
-import { readElementPlaybackRate, readElementPlaybackStart } from "./media.js";
+import { readElementPlaybackRate, readMediaStart } from "./playbackRate.js";
 import { parseStrictFiniteTimingNumber, resolveMediaElementDurationSeconds, resolveNaturalMediaTimelineDuration, resolveTimedImageDurationSeconds, } from "./playbackRate.js";
 import { resolveCssStackingContextId } from "./stackingContext.js";
 import { createRuntimeStartTimeResolver } from "./startResolver.js";
@@ -426,7 +426,7 @@ export function collectRuntimeTimelinePayload(params) {
             parentCompositionId: compositionContext.parentCompositionId,
             nodePath: null,
             compositionSrc: toAbsoluteAssetUrl(node.getAttribute("data-composition-src")),
-            playbackStart: readElementPlaybackStart(node),
+            playbackStart: readMediaStart(node),
             playbackRate: readElementPlaybackRate(node),
             assetUrl: resolveNodeAssetUrl(node),
             timelineRole: node.getAttribute("data-timeline-role"),
@@ -560,7 +560,7 @@ export function collectRuntimeTimelinePayload(params) {
                         parentCompositionId: rootCompositionIdForGsap,
                         nodePath: null,
                         compositionSrc: null,
-                        playbackStart: readElementPlaybackStart(el),
+                        playbackStart: readMediaStart(el),
                         playbackRate: readElementPlaybackRate(el),
                         assetUrl: null,
                         timelineRole: el.getAttribute("data-timeline-role"),
@@ -622,7 +622,7 @@ export function collectRuntimeTimelinePayload(params) {
                 parentCompositionId: rootCompositionIdForGsap,
                 nodePath: null,
                 compositionSrc: null,
-                playbackStart: readElementPlaybackStart(el),
+                playbackStart: readMediaStart(el),
                 playbackRate: readElementPlaybackRate(el),
                 assetUrl: null,
                 timelineRole,

package/dist/runtime/types.d.ts

@@ -1,5 +1,8 @@
 import type { HfColorGradingTarget } from "../colorGrading.js";
 import type { RuntimeAnalyticsEvent } from "./analytics.js";
+import type { AudioFades } from "../audioFade.js";
+import type { RateSpec } from "../speedRamp.js";
+import type { VolumeKeyframe } from "./mediaVolumeEnvelope.js";
 export type RuntimeJson = string | number | boolean | null | RuntimeJson[] | {
     [key: string]: RuntimeJson;
 };
@@ -378,4 +381,22 @@ type RuntimeDataControlFields = {
 };
 type RuntimeBridgeControlAction = RuntimeBridgeControlActionBase | "set-runtime-data" | "clear-runtime-data";
 export type RuntimeBridgeControlMessage = RuntimeBridgeControlMessageBase & RuntimeDataControlFields;
+export type RuntimeMediaClip = {
+    el: HTMLVideoElement | HTMLAudioElement;
+    start: number;
+    /** The clip's own t=0 when a host's in-point cut its head; source time, lanes and fades run from it. */
+    origin?: number;
+    mediaStart: number;
+    duration: number;
+    end: number;
+    volume: number | null;
+    playbackRate: number;
+    /** The rate lane when the clip has one; otherwise `playbackRate`. */
+    rate?: RateSpec;
+    loop: boolean;
+    sourceDuration: number | null;
+    /** Probed from the GSAP timeline as the renderer does; when set they drive volume, not `data-volume`. */
+    volumeKeyframes?: VolumeKeyframe[];
+    fades?: AudioFades;
+};
 export {};

package/dist/studioPreviewMark.d.ts

@@ -3,6 +3,8 @@ export declare const STUDIO_PREVIEW_CAPTURE_MODE = "capture";
 export declare const STUDIO_PREVIEW_UPCOMING_ATTR = "data-hf-upcoming";
 export declare const STUDIO_PREVIEW_LAZY_ATTR = "data-hf-preview-lazy";
 export declare const STUDIO_PREVIEW_ERRORS = "__hfPreviewErrors";
+export declare const refusedPreviewMessage: (status: number) => string;
+export declare function refusedPreviewStatus(message: string): number | null;
 export declare const PREVIEW_RASTER_ATTR = "data-hf-preview-raster";
 export declare const RUNTIME_STAMPED_ATTR = "data-hf-autostamped";
 export declare const CLIP_HIDDEN_ATTR = "data-hf-clip-hidden";

package/dist/studioPreviewMark.js

@@ -3,6 +3,11 @@ export const STUDIO_PREVIEW_CAPTURE_MODE = "capture";
 export const STUDIO_PREVIEW_UPCOMING_ATTR = "data-hf-upcoming";
 export const STUDIO_PREVIEW_LAZY_ATTR = "data-hf-preview-lazy";
 export const STUDIO_PREVIEW_ERRORS = "__hfPreviewErrors";
+export const refusedPreviewMessage = (status) => `The preview page could not be loaded (HTTP ${status}).`;
+export function refusedPreviewStatus(message) {
+    const status = /^The preview page could not be loaded \(HTTP (\d{3})\)\.$/.exec(message)?.[1];
+    return status ? Number(status) : null;
+}
 export const PREVIEW_RASTER_ATTR = "data-hf-preview-raster";
 export const RUNTIME_STAMPED_ATTR = "data-hf-autostamped";
 export const CLIP_HIDDEN_ATTR = "data-hf-clip-hidden";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.8.206",
+  "version": "0.8.208",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,6 +60,10 @@
       "import": "./dist/atomicFile.js",
       "types": "./dist/atomicFile.d.ts"
     },
+    "./remove-tree": {
+      "import": "./dist/removeTree.js",
+      "types": "./dist/removeTree.d.ts"
+    },
     "./project-folders": {
       "import": "./dist/projectFolders.js",
       "types": "./dist/projectFolders.d.ts"
@@ -273,6 +277,10 @@
       "import": "./dist/runtime/mediaClock.js",
       "types": "./dist/runtime/mediaClock.d.ts"
     },
+    "./runtime/media-steer": {
+      "import": "./dist/runtime/mediaSteer.js",
+      "types": "./dist/runtime/mediaSteer.d.ts"
+    },
     "./runtime/clip-reveal": {
       "import": "./dist/runtime/clipReveal.js",
       "types": "./dist/runtime/clipReveal.d.ts"
@@ -409,9 +417,9 @@
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
     "wawoff2": "^2.0.1",
-    "@hyperframes/lint": "0.8.206",
-    "@hyperframes/studio-server": "0.8.206",
-    "@hyperframes/parsers": "0.8.206"
+    "@hyperframes/lint": "0.8.208",
+    "@hyperframes/studio-server": "0.8.208",
+    "@hyperframes/parsers": "0.8.208"
   },
   "devDependencies": {
     "@fontsource/archivo-black": "^5.2.8",

package/dist/runtime/adapters/seek-dispatch.d.ts

@@ -1,37 +0,0 @@
-export interface HfSeekEventDetail {
-    time: number;
-    waitUntil: (promise: PromiseLike<unknown>) => void;
-}
-/**
- * Join `promise` to the seek-completion barrier: `waitForSeekCompletion` will
- * not resolve until it settles, and its rejection (the first one) becomes the
- * barrier's.
- *
- * Exported because the `"hf-seek"` event's synchronous `waitUntil()` is not
- * the only asynchronous seek work a frame can owe. `runtime/vfx.ts` registers
- * its preview-side capture here, so the CLI seek paths that already await this
- * barrier wait for a `self` chain's paint instead of racing it.
- */
-export declare function registerSeekCompletion(promise: Promise<unknown>, kind?: "video-frame"): void;
-export declare function dispatchSeekEvent(time: number): void;
-/**
- * Force-dispatch a `"hf-seek"` event even if `time` equals the last dispatched
- * time, bypassing the dedup guard.
- *
- * Needed for the post-video-injection GPU re-render: the engine seeks to time
- * T (GPU adapters render once, before video frames are injected), then injects
- * the decoded `__render_frame__` images, then must re-render GPU compositions
- * at the *same* T so they re-upload textures from the now-present frames. The
- * normal dedup would swallow that second dispatch.
- */
-export declare function forceDispatchSeekEvent(time: number): void;
-export declare function isSeekCompletionBarrierActive(): boolean;
-/** Settles with every pending completion, without consuming a failure the barrier reports. */
-export declare function seekCompletionsSettled(): Promise<void>;
-export declare function hasPendingSeekCompletion(): boolean;
-/** `videoFrames: false` skips only the video-frame holds: a geometry read needs every other completion. */
-export declare function waitForSeekCompletion(options?: {
-    videoFrames?: boolean;
-}): Promise<void>;
-/** Reset internal state — used in tests to prevent cross-test contamination. */
-export declare function resetSeekDispatchState(): void;

package/dist/runtime/adapters/seek-dispatch.js

@@ -1,143 +0,0 @@
-import { swallow } from "../diagnostics.js";
-/**
- * Shared, deduplicated `"hf-seek"` CustomEvent dispatcher for GPU adapters.
- *
- * Both the Three.js and TypeGPU adapters dispatch the same `"hf-seek"` event
- * so that compositions need not know which GPU library they're paired with.
- * Without deduplication, a seek to time T would fire two events (one from each
- * adapter), doubling per-scrub work in any composition that has both present.
- *
- * This module deduplicates by tracking the last dispatched time. If the same
- * time value is dispatched twice in the same synchronous call stack (e.g. two
- * adapters both calling `dispatchSeekEvent(5.0)` without yielding), only the
- * first call fires the event.
- *
- * The deduplication is intentionally coarse (exact float equality). Adapter
- * seek paths clamp and normalise time before calling this function, so the
- * values that arrive here are already stable.
- */
-let _lastDispatchedTime = -1;
-let _pendingCompletions = new Set();
-let _videoFrameCompletions = new WeakSet();
-let _pendingFailure;
-let _activeCompletionBarriers = 0;
-function dispatch(time) {
-    const pending = [];
-    let accepting = true;
-    const detail = {
-        time,
-        waitUntil: (promise) => {
-            if (!accepting) {
-                throw new Error("hf-seek waitUntil() must be called synchronously from the event listener");
-            }
-            pending.push(promise);
-        },
-    };
-    try {
-        window.dispatchEvent(new CustomEvent("hf-seek", { detail }));
-    }
-    catch (err) {
-        swallow("runtime.adapters.seek-dispatch.site1", err);
-    }
-    finally {
-        accepting = false;
-    }
-    if (pending.length === 0)
-        return;
-    registerSeekCompletion(Promise.all(pending));
-}
-/**
- * Join `promise` to the seek-completion barrier: `waitForSeekCompletion` will
- * not resolve until it settles, and its rejection (the first one) becomes the
- * barrier's.
- *
- * Exported because the `"hf-seek"` event's synchronous `waitUntil()` is not
- * the only asynchronous seek work a frame can owe. `runtime/vfx.ts` registers
- * its preview-side capture here, so the CLI seek paths that already await this
- * barrier wait for a `self` chain's paint instead of racing it.
- */
-export function registerSeekCompletion(promise, kind) {
-    const completion = promise
-        .then(() => ({ status: "fulfilled" }))
-        .catch((reason) => ({ status: "rejected", reason }));
-    _pendingCompletions.add(completion);
-    if (kind === "video-frame")
-        _videoFrameCompletions.add(completion);
-    void completion.then((result) => {
-        if (!_pendingCompletions.delete(completion))
-            return;
-        if (result.status === "rejected" && _pendingFailure === undefined) {
-            _pendingFailure = { reason: result.reason };
-        }
-    });
-}
-export function dispatchSeekEvent(time) {
-    if (time === _lastDispatchedTime)
-        return;
-    _lastDispatchedTime = time;
-    dispatch(time);
-}
-/**
- * Force-dispatch a `"hf-seek"` event even if `time` equals the last dispatched
- * time, bypassing the dedup guard.
- *
- * Needed for the post-video-injection GPU re-render: the engine seeks to time
- * T (GPU adapters render once, before video frames are injected), then injects
- * the decoded `__render_frame__` images, then must re-render GPU compositions
- * at the *same* T so they re-upload textures from the now-present frames. The
- * normal dedup would swallow that second dispatch.
- */
-export function forceDispatchSeekEvent(time) {
-    _lastDispatchedTime = time;
-    dispatch(time);
-}
-export function isSeekCompletionBarrierActive() {
-    return _activeCompletionBarriers > 0;
-}
-/** Settles with every pending completion, without consuming a failure the barrier reports. */
-export async function seekCompletionsSettled() {
-    for (let pending = [..._pendingCompletions]; pending.length > 0; pending = [..._pendingCompletions]) {
-        await Promise.all(pending);
-    }
-}
-export function hasPendingSeekCompletion() {
-    return _pendingCompletions.size > 0;
-}
-/** `videoFrames: false` skips only the video-frame holds: a geometry read needs every other completion. */
-export async function waitForSeekCompletion(options) {
-    const awaited = () => [..._pendingCompletions].filter((completion) => options?.videoFrames !== false || !_videoFrameCompletions.has(completion));
-    _activeCompletionBarriers += 1;
-    let failed = _pendingFailure;
-    try {
-        // Let concurrently started barriers snapshot the same retained failure
-        // before either one consumes it.
-        await Promise.resolve();
-        for (let pending = awaited(); pending.length > 0; pending = awaited()) {
-            const results = await Promise.all(pending);
-            const rejected = results.find((result) => result.status === "rejected");
-            if (failed === undefined && rejected?.status === "rejected") {
-                failed = { reason: rejected.reason };
-            }
-        }
-        const retainedFailure = _pendingFailure;
-        if (failed === undefined) {
-            failed = retainedFailure;
-        }
-        if (_pendingFailure === retainedFailure) {
-            _pendingFailure = undefined;
-        }
-        if (failed)
-            throw failed.reason;
-    }
-    finally {
-        _activeCompletionBarriers -= 1;
-    }
-}
-/** Reset internal state — used in tests to prevent cross-test contamination. */
-export function resetSeekDispatchState() {
-    _lastDispatchedTime = -1;
-    _pendingCompletions = new Set();
-    _videoFrameCompletions = new WeakSet();
-    _pendingFailure = undefined;
-    _activeCompletionBarriers = 0;
-}

package/dist/runtime/media.d.ts

@@ -1,128 +0,0 @@
-import { type VolumeKeyframe } from "./mediaVolumeEnvelope.js";
-import { type AudioFades } from "../audioFade.js";
-import { type RateSpec } from "../speedRamp.js";
-import { type HostSlot } from "../mediaTiming.js";
-export { readElementPlaybackRate, readElementRateSpec, resolveNaturalMediaTimelineDuration, } from "./playbackRate.js";
-export declare function readElementPlaybackStart(el: Element): number;
-export declare const HOLD_CAP_MS = 5000;
-/**
- * Resolve a media element's timeline window without conflating a video's
- * authored display slot with the amount of source left to decode.
- *
- * An explicit video slot may outlive its source and holds the final frame.
- * Audio remains source-bounded because it has no visual hold state.
- */
-export declare function resolveRuntimeMediaClipDuration(params: {
-    isVideo: boolean;
-    sourceDuration: number | null;
-    hostRemaining: number | null;
-    explicitDuration: number | null;
-}): number | null;
-export type RuntimeMediaClip = {
-    el: HTMLVideoElement | HTMLAudioElement;
-    start: number;
-    /** The clip's own t=0 when a host's in-point cut its head; source time, lanes and fades run from it. */
-    origin?: number;
-    mediaStart: number;
-    duration: number;
-    end: number;
-    volume: number | null;
-    playbackRate: number;
-    /** The rate lane when the clip has one; otherwise `playbackRate`. */
-    rate?: RateSpec;
-    loop: boolean;
-    /** Source media duration in seconds (from el.duration). Used for loop wrapping. */
-    sourceDuration: number | null;
-    /**
-     * Probed volume keyframes from the GSAP timeline (same probe the renderer
-     * uses). When present, `syncRuntimeMedia` drives volume from the envelope
-     * rather than from `data-volume` + GSAP-change tracking, eliminating the
-     * race between the 60 Hz transport tick and GSAP's own seek.
-     */
-    volumeKeyframes?: VolumeKeyframe[];
-    /** Clip-edge fades from `data-fade-in` / `data-fade-out`; see audioFade.ts. */
-    fades?: AudioFades;
-};
-export declare function refreshRuntimeMediaCache(params?: {
-    resolveStartSeconds?: (element: Element) => number;
-    resolveDurationSeconds?: (element: HTMLVideoElement | HTMLAudioElement) => number | null;
-    resolveHostSlots?: (element: HTMLVideoElement | HTMLAudioElement) => HostSlot[];
-    shouldIncludeElement?: (element: HTMLVideoElement | HTMLAudioElement) => boolean;
-    /**
-     * Build clips for exactly these elements instead of scanning the document for
-     * them. For a caller that already knows which media it needs this pass — the
-     * per-seek sync only touches the clips whose active state can change — and so
-     * should not pay to re-derive the window of every clip in the composition.
-     *
-     * Every field is still read FRESH from the element. This narrows which
-     * elements are visited, never how current the answer is: `el.duration` can be
-     * reset under the caller by an `el.load()` it did not make.
-     */
-    elements?: Array<HTMLVideoElement | HTMLAudioElement>;
-}): {
-    timedMediaEls: Array<HTMLVideoElement | HTMLAudioElement>;
-    mediaClips: RuntimeMediaClip[];
-    videoClips: RuntimeMediaClip[];
-    maxMediaEnd: number;
-};
-export declare function isUnplayable(el: HTMLMediaElement): boolean;
-/**
- * Drop every per-source sync baseline tracked for `el` — offset drift
- * samples, the seek-past-buffered-range retry latch, and the last
- * runtime-applied volume — so the next `syncRuntimeMedia` tick treats it as
- * a first tick (hard resync, fresh drift baseline) instead of comparing
- * against state computed for a different file. Used both when a clip leaves
- * its active window (below) and by the runtime's proxy-swap helper
- * (mediaProxy.ts) right after an in-place `src` swap, which points the same
- * element at a different file without ever leaving its active window.
- */
-export declare function evictMediaSyncState(el: HTMLMediaElement): void;
-/** Test-only seam: whether any per-source sync state is still tracked for `el`. */
-export declare function hasMediaSyncStateForTest(el: HTMLMediaElement): boolean;
-export declare const MEDIA_HARD_SYNC_SECONDS = 0.5;
-export declare const VIDEO_PRESEEK_SECONDS = 1.5;
-export declare function mediaSourceTimeAt(clip: RuntimeMediaClip, timeSeconds: number): number;
-/** Drift a playing audio element may carry before sync pulls it back onto the playhead. */
-export declare const MEDIA_SYNC_TOLERANCE_SECONDS = 0.04;
-export declare function syncRuntimeMedia(params: {
-    clips: RuntimeMediaClip[];
-    timeSeconds: number;
-    playing: boolean;
-    playbackRate: number;
-    /** Force-mute every element (parent-frame proxy owns all audio). Asserted per
-     *  tick so sub-composition media added mid-playback inherits the silence. */
-    outputMuted?: boolean;
-    /**
-     * User's explicit mute preference (set via `onSetMuted`). Symmetric to
-     * `outputMuted` — also asserted per tick — so a sub-composition that
-     * activates after the user mutes doesn't briefly play at author volume
-     * before the next bridge message lands.
-     */
-    userMuted?: boolean;
-    /**
-     * User's volume preference (0–1, set via `onSetVolume`). Multiplied with the
-     * per-clip author volume so `data-volume="0.5"` at user volume 0.8 yields 0.4.
-     */
-    userVolume?: number;
-    /**
-     * Invoked at most once when a media element's `play()` promise rejects with
-     * `NotAllowedError`. The caller is expected to latch and post a single
-     * outbound message; further invocations are suppressed by the caller.
-     */
-    onAutoplayBlocked?: () => void;
-    /** `clipGain` is `data-volume` for a routed clip, played ahead of its FX; 1 otherwise. */
-    onElementVolume?: (el: HTMLMediaElement, effectiveVolume: number, authorVolume: number, clipGain: number, unfadedVolume?: number) => void;
-    /** Is THIS element owned by the Web Audio transport? Owned → mute it (transport
-     *  plays it); not owned → leave audible (HTMLMedia fallback). Per-element, not a
-     *  global flag, so a not-yet-claimed track isn't muted by other tracks. */
-    isWebAudioOwned?: (el: HTMLMediaElement) => boolean;
-    /** Native media routed through WebAudio keeps its upstream element volume at
-     * unity; do not mistake that transport write for an authored volume edit. */
-    isWebAudioRouted?: (el: HTMLMediaElement) => boolean;
-    forceSync?: boolean;
-    /** How far the next tick will move the playhead: an audio clip due within it starts now. */
-    cueAheadSeconds?: number;
-    /** Lets a video clip that runs to the composition end hold its last frame at the terminal time.
-     *  A thunk, because deriving the duration is only worth it for a clip past its own end. */
-    getCompositionDuration: () => number;
-}): void;