@hyperframes/core 0.8.206 → 0.8.207

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/media.d.ts

@@ -2,6 +2,7 @@ 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 { MEDIA_SYNC_TOLERANCE_SECONDS } from "./mediaSteer.js";
 export { readElementPlaybackRate, readElementRateSpec, resolveNaturalMediaTimelineDuration, } from "./playbackRate.js";
 export declare function readElementPlaybackStart(el: Element): number;
 export declare const HOLD_CAP_MS = 5000;
@@ -80,10 +81,8 @@ 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 const MEDIA_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;
@@ -120,8 +119,12 @@ export declare function syncRuntimeMedia(params: {
      * unity; do not mistake that transport write for an authored volume edit. */
     isWebAudioRouted?: (el: HTMLMediaElement) => boolean;
     forceSync?: boolean;
+    /** False while the playhead is not moving (audio output has not started): a paused video waits for it. */
+    clockAdvancing?: boolean;
     /** How far the next tick will move the playhead: an audio clip due within it starts now. */
     cueAheadSeconds?: number;
+    /** Seeks a sounding element under a gain dip; false when it has no dip stage and the sync seeks it plainly. */
+    seekUnderDip?: (el: HTMLMediaElement, target: number) => boolean;
     /** 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;

package/dist/runtime/media.js

@@ -13,6 +13,8 @@ import { findInjectedRenderFrame } from "./renderFrameSibling.js";
 import { isRenderFrameVideo } from "./preloadMedia.js";
 import { registerSeekCompletion } from "./adapters/seek-dispatch.js";
 import { cutToHostSlots } from "../mediaTiming.js";
+import { forgetSteering, isSteering, MEDIA_SYNC_TOLERANCE_SECONDS, steerMedia, } from "./mediaSteer.js";
+export { MEDIA_SYNC_TOLERANCE_SECONDS } from "./mediaSteer.js";
 export { readElementPlaybackRate, readElementRateSpec, resolveNaturalMediaTimelineDuration, } from "./playbackRate.js";
 export function readElementPlaybackStart(el) {
     return readMediaStart(el);
@@ -181,7 +183,8 @@ export function evictMediaSyncState(el) {
     strictDriftSamples.delete(el);
     seekLoadRetried.delete(el);
     lastRuntimeAppliedVolume.delete(el);
-    videoSteering.delete(el);
+    forgetSteering(el);
+    heldAhead.delete(el);
 }
 /** Test-only seam: whether any per-source sync state is still tracked for `el`. */
 export function hasMediaSyncStateForTest(el) {
@@ -190,10 +193,10 @@ export function hasMediaSyncStateForTest(el) {
         strictDriftSamples.has(el) ||
         seekLoadRetried.has(el) ||
         lastRuntimeAppliedVolume.has(el) ||
-        videoSteering.has(el));
+        isSteering(el));
 }
 export const MEDIA_HARD_SYNC_SECONDS = 0.5;
-export const VIDEO_PRESEEK_SECONDS = 1.5;
+export const MEDIA_PRESEEK_SECONDS = 1.5;
 export function mediaSourceTimeAt(clip, timeSeconds) {
     const elapsed = Math.max(0, Math.min(timeSeconds, clip.end) - (clip.origin ?? clip.start));
     const target = clip.mediaStart + sourceTimeAt(clip.rate ?? clip.playbackRate, elapsed);
@@ -207,13 +210,12 @@ export function mediaSourceTimeAt(clip, timeSeconds) {
         return Math.min(target, clip.sourceDuration);
     return target;
 }
-function prepareUpcomingVideo(clip, time, playing, rate) {
+function prepareUpcomingMedia(clip, time, playing, rate) {
     const { el } = clip;
     const dueIn = clip.start - time;
     if (!playing ||
-        el.tagName !== "VIDEO" ||
         dueIn <= 0 ||
-        dueIn > VIDEO_PRESEEK_SECONDS * rate ||
+        dueIn > MEDIA_PRESEEK_SECONDS * rate ||
         !el.paused ||
         el.seeking ||
         el.readyState < el.HAVE_METADATA ||
@@ -224,7 +226,7 @@ function prepareUpcomingVideo(clip, time, playing, rate) {
     if (!Number.isFinite(target) || target < 0 || Math.abs(el.currentTime - target) <= 0.001)
         return;
     try {
-        // A trimmed video exposed during its in-point seek has no current frame at the cut.
+        // A trimmed clip seeked as it opens shows no frame and plays late, then is seeked again while it sounds.
         // Hidden preparation must not hold the visible-frame seek barrier.
         el.currentTime = mediaElementTime(target);
     }
@@ -232,35 +234,12 @@ function prepareUpcomingVideo(clip, time, playing, rate) {
         swallow("runtime.media.preseek", err);
     }
 }
-/** Drift a playing audio element may carry before sync pulls it back onto the playhead. */
-export const MEDIA_SYNC_TOLERANCE_SECONDS = 0.04;
 // Chromium refuses a slower playbackRate (NotSupportedError).
 const MIN_NATIVE_PLAYBACK_RATE = 1 / 16;
-// A playing video is steered back by rate, not seeked (a seek resets its decoder).
-// Its rate is written only when steering starts or stops: every write costs a frame.
-const VIDEO_STEER = 0.03;
-// A video that starts a cut late closes its lag over one clip at 3%; a bigger lag steers harder, in steps so the rate is written rarely.
-const VIDEO_STEER_STEPS = [
-    [0.3, 0.25],
-    [0.1, 0.1],
-];
-const VIDEO_STEER_RELEASE_SECONDS = 0.01;
-/** Direction (+1 fast, -1 slow) a video is being steered in; absent when it plays at its authored rate. */
-const videoSteering = new WeakMap();
-/** Rate for a playing video `offset` seconds behind (+) or ahead (-) of the playhead. */
-function steeredVideoRate(el, offset, baseRate) {
-    const direction = Math.sign(offset);
-    const steering = videoSteering.get(el);
-    if (Math.abs(offset) > MEDIA_SYNC_TOLERANCE_SECONDS)
-        videoSteering.set(el, direction);
-    else if (steering !== direction || Math.abs(offset) <= VIDEO_STEER_RELEASE_SECONDS) {
-        videoSteering.delete(el);
-        return baseRate;
-    }
-    const lag = Math.abs(offset);
-    const steer = VIDEO_STEER_STEPS.find(([from]) => lag > from)?.[1] ?? VIDEO_STEER;
-    return baseRate * (1 + direction * steer);
-}
+// A video this far ahead of the playhead, or at its out-point, is held until the playhead reaches it:
+// steering a lead of a few hundred ms takes seconds and shows frames past the cut.
+const VIDEO_LEAD_HOLD_SECONDS = 0.1;
+const heldAhead = new WeakSet();
 // fallow-ignore-next-line complexity
 export function syncRuntimeMedia(params) {
     const forceMuteAll = !!(params.outputMuted || params.userMuted);
@@ -451,12 +430,24 @@ export function syncRuntimeMedia(params) {
                 (el.ended && canSeekEndedMediaBackward && drift > 0.001) ||
                 staleAudioOnFirstTick ||
                 (drift > MEDIA_HARD_SYNC_SECONDS && (firstTickOfClip || offsetJumped || catastrophicDrift));
-            // Playing videos use the browser's decoder for timing. Seeking one resets the decoder: a
-            // ~150ms freeze while it re-buffers, as the monotonic clock advances, which loops into a
-            // seek→freeze→drift→seek stutter. So a playing video skips strict and force sync; only hard
-            // sync (>0.5s) warrants the decoder-reset cost. A paused transport pauses this video below,
-            // so a seek that pauses mid-playback still lands it.
-            const isPlayingVideo = el.tagName === "VIDEO" && !el.paused && playing;
+            // Seeking playing media resets a video's decoder (a ~150ms freeze that loops into a
+            // seek→freeze→drift→seek stutter) and jumps sounding audio (a click). So playing media skips
+            // strict and force sync and is steered by rate; hard sync (>0.5s) and audio past its steer
+            // limit seek. A paused transport pauses it below, so a seek that pauses mid-playback lands it.
+            if (el.tagName === "VIDEO" && !isHeldVideoTail) {
+                // A loop's playhead wraps before its element, so its offset jumps by a lap: steering owns loops.
+                const ahead = !clip.loop &&
+                    (offset < -VIDEO_LEAD_HOLD_SECONDS ||
+                        currentElTime >= mediaSourceTimeAt(clip, clip.end) - MEDIA_SYNC_TOLERANCE_SECONDS);
+                if (!playing || (!ahead && offset >= -MEDIA_SYNC_TOLERANCE_SECONDS))
+                    heldAhead.delete(el);
+                else if (ahead && !el.paused) {
+                    heldAhead.add(el);
+                    el.pause();
+                }
+            }
+            const holdingAhead = heldAhead.has(el);
+            const isPlayingMedia = !el.paused && playing;
             // Only apply strict sync when offset has stabilized (not growing).
             // During initial buffering, offset grows ~16ms/tick as the timeline
             // advances while media stays at 0. Accumulated drift from pause/play
@@ -464,7 +455,8 @@ export function syncRuntimeMedia(params) {
             const heldBelowFloor = params.playing && !playing;
             const offsetStabilized = heldBelowFloor || (prevOffset !== undefined && Math.abs(offset - prevOffset) < 0.004);
             let strictSync = false;
-            if (!isPlayingVideo &&
+            if (!isPlayingMedia &&
+                !holdingAhead &&
                 !hardSync &&
                 !firstTickOfClip &&
                 offsetStabilized &&
@@ -479,12 +471,15 @@ export function syncRuntimeMedia(params) {
             else if (drift <= MEDIA_SYNC_TOLERANCE_SECONDS) {
                 strictDriftSamples.set(el, 0);
             }
-            const forceSync = !isPlayingVideo && params.forceSync && drift > 0.02;
+            const forceSync = !isPlayingMedia && !holdingAhead && params.forceSync && drift > 0.02;
+            const steered = isPlayingMedia && !hardSync ? steerMedia(el, offset, baseRate, offsetStabilized) : null;
+            const steerSeeks = steered?.seek === true;
+            const dipped = steerSeeks && params.seekUnderDip?.(el, relTime) === true;
             try {
-                // A hard sync lands the video on the playhead, so its pre-seek offset says nothing.
-                if (!isPlayingVideo || hardSync)
-                    videoSteering.delete(el);
-                const rate = Math.max(MIN_NATIVE_PLAYBACK_RATE, isPlayingVideo && !hardSync ? steeredVideoRate(el, offset, baseRate) : baseRate);
+                // A hard sync lands the element on the playhead, so its pre-seek offset says nothing.
+                if (!steered)
+                    forgetSteering(el);
+                const rate = Math.max(MIN_NATIVE_PLAYBACK_RATE, steered?.rate ?? baseRate);
                 // Some engines read a rate back at lower precision; an equal-enough rate is not rewritten.
                 if (Math.abs(el.playbackRate - rate) > 1e-6)
                     el.playbackRate = rate;
@@ -493,7 +488,7 @@ export function syncRuntimeMedia(params) {
                 // ignore unsupported playbackRate
                 swallow("runtime.media.site1", err);
             }
-            if (hardSync || strictSync || forceSync) {
+            if (hardSync || strictSync || forceSync || (steerSeeks && !dipped)) {
                 // Skip the per-tick seek (and the `el.load()` drift-recovery retry
                 // below) for `<video>` elements that have a sibling
                 // `<img id="__render_frame_<id>__">`. The sibling is created only
@@ -526,6 +521,7 @@ export function syncRuntimeMedia(params) {
                     holdSeekBarrierUntilVideoLands(el);
                 }
                 playRequested.delete(el);
+                heldAhead.delete(el);
             }
             else if (!playing) {
                 holdSeekBarrierUntilVideoLands(el);
@@ -534,7 +530,12 @@ export function syncRuntimeMedia(params) {
                 if (!el.paused)
                     el.pause();
             }
-            else if (playing && el.paused && !playRequested.has(el) && !isUnplayable(el)) {
+            else if (playing &&
+                !heldAhead.has(el) &&
+                params.clockAdvancing !== false &&
+                el.paused &&
+                !playRequested.has(el) &&
+                !isUnplayable(el)) {
                 // `HTMLMediaElement.play()` is spec'd to queue playback and resolve
                 // once enough data is buffered, so we can unconditionally call it —
                 // no need to gate on `readyState` or defer to a `canplay` listener.
@@ -580,6 +581,6 @@ export function syncRuntimeMedia(params) {
             lastRelativeTime.set(el, relTime);
         if (!el.paused)
             el.pause();
-        prepareUpcomingVideo(clip, params.timeSeconds, params.playing, params.playbackRate);
+        prepareUpcomingMedia(clip, params.timeSeconds, params.playing, params.playbackRate);
     }
 }

package/dist/runtime/mediaSteer.d.ts

@@ -0,0 +1,10 @@
+/** Drift a playing element may carry before sync pulls it back onto the playhead. */
+export declare const MEDIA_SYNC_TOLERANCE_SECONDS = 0.04;
+/** 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,40 @@
+/** Drift a playing element may carry before sync pulls it back onto the playhead. */
+export const MEDIA_SYNC_TOLERANCE_SECONDS = 0.04;
+// 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/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.207",
   "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.207",
+    "@hyperframes/studio-server": "0.8.207",
+    "@hyperframes/parsers": "0.8.207"
   },
   "devDependencies": {
     "@fontsource/archivo-black": "^5.2.8",