@hyperframes/core 0.8.199 → 0.8.201

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export { AUDIO_GROUP_RENDER_ID_ATTR, MEDIA_RENDER_ID_ATTR, assignMediaRenderIds,
 export { RENDER_FRAME_ID_PREFIX, RENDER_FRAME_ID_SUFFIX, renderFrameIdForRenderId, } from "./runtime/renderFrameSibling.js";
 export { rewriteAssetPaths, rewriteAssetPath, rewriteCssAssetUrls, rewriteInlineStyleAssetUrls, } from "./compiler/rewriteSubCompPaths.js";
 export { CSS_URL_RE, isNonRelativeUrl, isPathInside } from "./compiler/assetPaths.js";
+export { rewriteSrcsetUrls } from "./compiler/srcset.js";
 export { checkSubCompositionUsability, type ParsableDocumentLike, type SubCompositionValidity, type SubCompositionValidityReason, } from "./compiler/subCompositionValidity.js";
 export { RUNTIME_BOOTSTRAP_ATTR, stripEmbeddedRuntimeScripts } from "./compiler/htmlDocument.js";
 export { COMPOSITION_SOURCE_URL } from "./compiler/scriptRuns.js";
@@ -32,7 +33,7 @@ export { clearGifFramesBeforeNext, gifClearsAfterLeavingFrameInPlace, parseAnima
 export { HF_COLOR_GRADING_ATTR, HF_COLOR_GRADING_ADJUST_KEYS, HF_COLOR_GRADING_ACTIVE_EFFECT_KEYS, HF_COLOR_GRADING_ANIMATABLE_PROPERTIES, HF_COLOR_GRADING_CANVAS_ID_PREFIX, HF_COLOR_GRADING_COLOR_SPACE, HF_COLOR_GRADING_CURVE_KEYS, HF_COLOR_GRADING_DETAIL_KEYS, HF_COLOR_GRADING_EFFECT_APPLY_DEFAULTS, HF_COLOR_GRADING_EFFECT_KEYS, HF_COLOR_GRADING_EFFECT_PRESETS, HF_COLOR_GRADING_GRADE_PRESETS, HF_COLOR_GRADING_HUE_CURVE_KEYS, HF_COLOR_GRADING_LUT_KEYS, HF_COLOR_GRADING_PALETTES, HF_COLOR_GRADING_PRESETS, HF_COLOR_GRADING_TOP_LEVEL_KEYS, HF_COLOR_GRADING_WHEEL_KEYS, getHfColorGradingCapabilities, hasHfColorGradingAuthoredValues, isHfColorGradingActive, normalizeHfColorGrading, normalizeHfColorGradingWithVariables, resolveHfColorGradingVariables, serializeHfColorGrading, type HfColorGrading, type HfColorGradingAdjust, type HfColorGradingAdjustKey, type HfColorGradingAnimatablePath, type HfColorGradingActiveEffectKey, type HfColorGradingDetailKey, type HfColorGradingDetails, type HfColorGradingEffectKey, type HfColorGradingEffects, type HfColorGradingLutRef, type HfColorGradingPreset, type HfColorGradingPresetId, type HfColorGradingTarget, type HfColorGradingVariableMap, type HfColorGradingCapabilities, type HfColorGradingCurveKey, type HfColorGradingCurves, type HfColorGradingHueCurveKey, type HfColorGradingHueCurves, type HfColorGradingHueRange, type HfColorGradingSecondary, type HfColorGradingSecondaryCorrection, type HfColorGradingSoftRange, type HfColorGradingTonalWheel, type HfColorGradingWheelKey, type HfColorGradingWheels, type HfColorCurvePoint, type HfHueCurvePoint, type NormalizedHfColorGrading, type NormalizedHfColorGradingCurves, type NormalizedHfColorGradingHueCurves, type NormalizedHfColorGradingSecondary, type NormalizedHfColorGradingWheels, type ResolvedHfColorGrading, } from "./colorGrading.js";
 export { parseCubeLut, CubeLutParseError, type ParseCubeLutOptions } from "./colorLuts.js";
 export { firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, type ToneMapSourceColour, } from "./hdrToneMap.js";
-export { PREVIEW_PROXY_BOX_PARAM, formatPreviewProxyBox, parsePreviewProxyBox, quantizePreviewProxyBox, type PreviewProxyBox, } from "./previewProxyBox.js";
+export { HEAVY_BITRATE, HEAVY_PIXEL_SHARE, PREVIEW_PROXY_BOX_PARAM, PREVIEW_PROXY_LIGHT_PARAM, PREVIEW_QUALITY_LEVELS, formatPreviewProxyBox, isHeavyForPreview, isPreviewQuality, parsePreviewProxyBox, quantizePreviewProxyBox, scalePreviewProxyBox, type PreviewProxyBox, type PreviewQuality, type PreviewSourceFacts, } from "./previewProxyBox.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";
@@ -49,6 +50,7 @@ export { fitTextFontSize } from "./text/index.js";
 export type { FitTextOptions, FitTextResult } from "./text/index.js";
 export { formatRenderOutputTimestamp } from "./utils/renderOutputTimestamp.js";
 export { getVariables } from "./runtime/getVariables.js";
+export { SCENE_CALLBACK_ERROR_PREFIX } from "./runtime/diagnostics.js";
 export { parseStartExpression, parseNumeric, type ReferenceExpression, } from "./runtime/startExpression.js";
 export { COMPOSITION_CONTRACT_VERSION, COMPOSITION_ATTRIBUTES, CANONICAL_AUTHORED_TIMING_ATTRIBUTES, DERIVED_TIMING_ATTRIBUTES, LEGACY_TIMING_ATTRIBUTES, readClipTiming, writeClipTiming, ClipTimingWriteError, type ClipTiming, type ClipTimingDiagnostic, type ClipTimingDiagnosticCode, type ClipTimingUpdate, } from "./compositionContract.js";
 export { createRuntimeStartTimeResolver } from "./runtime/startResolver.js";

package/dist/index.js

@@ -18,6 +18,7 @@ export { RENDER_FRAME_ID_PREFIX, RENDER_FRAME_ID_SUFFIX, renderFrameIdForRenderI
 // package (which imports core utilities back).
 export { rewriteAssetPaths, rewriteAssetPath, rewriteCssAssetUrls, rewriteInlineStyleAssetUrls, } from "./compiler/rewriteSubCompPaths.js";
 export { CSS_URL_RE, isNonRelativeUrl, isPathInside } from "./compiler/assetPaths.js";
+export { rewriteSrcsetUrls } from "./compiler/srcset.js";
 export { checkSubCompositionUsability, } from "./compiler/subCompositionValidity.js";
 export { RUNTIME_BOOTSTRAP_ATTR, stripEmbeddedRuntimeScripts } from "./compiler/htmlDocument.js";
 export { COMPOSITION_SOURCE_URL } from "./compiler/scriptRuns.js";
@@ -28,7 +29,7 @@ export { clearGifFramesBeforeNext, gifClearsAfterLeavingFrameInPlace, parseAnima
 export { HF_COLOR_GRADING_ATTR, HF_COLOR_GRADING_ADJUST_KEYS, HF_COLOR_GRADING_ACTIVE_EFFECT_KEYS, HF_COLOR_GRADING_ANIMATABLE_PROPERTIES, HF_COLOR_GRADING_CANVAS_ID_PREFIX, HF_COLOR_GRADING_COLOR_SPACE, HF_COLOR_GRADING_CURVE_KEYS, HF_COLOR_GRADING_DETAIL_KEYS, HF_COLOR_GRADING_EFFECT_APPLY_DEFAULTS, HF_COLOR_GRADING_EFFECT_KEYS, HF_COLOR_GRADING_EFFECT_PRESETS, HF_COLOR_GRADING_GRADE_PRESETS, HF_COLOR_GRADING_HUE_CURVE_KEYS, HF_COLOR_GRADING_LUT_KEYS, HF_COLOR_GRADING_PALETTES, HF_COLOR_GRADING_PRESETS, HF_COLOR_GRADING_TOP_LEVEL_KEYS, HF_COLOR_GRADING_WHEEL_KEYS, getHfColorGradingCapabilities, hasHfColorGradingAuthoredValues, isHfColorGradingActive, normalizeHfColorGrading, normalizeHfColorGradingWithVariables, resolveHfColorGradingVariables, serializeHfColorGrading, } from "./colorGrading.js";
 export { parseCubeLut, CubeLutParseError } from "./colorLuts.js";
 export { firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "./hdrToneMap.js";
-export { PREVIEW_PROXY_BOX_PARAM, formatPreviewProxyBox, parsePreviewProxyBox, quantizePreviewProxyBox, } from "./previewProxyBox.js";
+export { HEAVY_BITRATE, HEAVY_PIXEL_SHARE, PREVIEW_PROXY_BOX_PARAM, PREVIEW_PROXY_LIGHT_PARAM, PREVIEW_QUALITY_LEVELS, formatPreviewProxyBox, isHeavyForPreview, isPreviewQuality, parsePreviewProxyBox, quantizePreviewProxyBox, scalePreviewProxyBox, } from "./previewProxyBox.js";
 // Inline scripts
 export { HYPERFRAME_RUNTIME_ARTIFACTS, HYPERFRAME_RUNTIME_CONTRACT, loadHyperframeRuntimeSource, } from "./inline-scripts/hyperframe.js";
 export { HYPERFRAME_RUNTIME_GLOBALS, HYPERFRAME_BRIDGE_SOURCES, HYPERFRAME_CONTROL_ACTIONS, } from "./inline-scripts/runtimeContract.js";
@@ -44,6 +45,7 @@ export { fitTextFontSize } from "./text/index.js";
 export { formatRenderOutputTimestamp } from "./utils/renderOutputTimestamp.js";
 // Runtime helpers (composition-side)
 export { getVariables } from "./runtime/getVariables.js";
+export { SCENE_CALLBACK_ERROR_PREFIX } from "./runtime/diagnostics.js";
 export { parseStartExpression, parseNumeric, } from "./runtime/startExpression.js";
 export { COMPOSITION_CONTRACT_VERSION, COMPOSITION_ATTRIBUTES, CANONICAL_AUTHORED_TIMING_ATTRIBUTES, DERIVED_TIMING_ATTRIBUTES, LEGACY_TIMING_ATTRIBUTES, readClipTiming, writeClipTiming, ClipTimingWriteError, } from "./compositionContract.js";
 // Also exposed via the ./runtime/start-resolver subpath. This root re-export

package/dist/mediaGradeAnalyzer.d.ts

@@ -56,6 +56,7 @@ type NumericStats = Readonly<Record<string, number | undefined>>;
 export declare function parseMediaTreatmentSignalStats(raw: string): GradeSignalFrame[];
 export declare function statsToAdjust(stats: NumericStats): Pick<MediaTreatmentAnalysis, "adjust" | "measured">;
 export declare function summarizeMediaTreatmentAnalysis(probe: GradeMediaProbe, frames: readonly GradeSignalFrame[]): MediaTreatmentAnalysis;
+export declare function gradeSampleTimes(duration: number): number[];
 export declare function analyzeMediaGrade(mediaPath: string, options?: {
     ffmpegPath?: string;
     ffprobePath?: string;

package/dist/mediaGradeAnalyzer.js

@@ -212,43 +212,55 @@ export function summarizeMediaTreatmentAnalysis(probe, frames) {
         warnings,
     };
 }
-export function analyzeMediaGrade(mediaPath, options = {}) {
-    const ffmpegPath = options.ffmpegPath ?? "ffmpeg";
-    const ffprobePath = options.ffprobePath ?? "ffprobe";
+export function gradeSampleTimes(duration) {
+    return Array.from({ length: SAMPLE_FRAMES }, (_, i) => (duration * (i + 0.5)) / SAMPLE_FRAMES);
+}
+function readSignalStats(ffmpegPath, mediaPath, seekSeconds, frames) {
+    const timeoutMs = Number(process.env.HYPERFRAMES_ANALYZE_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS;
+    const keyframeSeek = seekSeconds === null ? [] : ["-noaccurate_seek", "-ss", seekSeconds.toFixed(3)];
     try {
-        const probe = probeMedia(mediaPath, ffprobePath);
-        const isImage = IMAGE_EXTENSIONS.has(extname(mediaPath).toLowerCase());
-        const fps = !isImage && probe.duration
-            ? Math.max(0.1, Math.min(2, SAMPLE_FRAMES / probe.duration))
-            : null;
-        const filters = [
-            fps ? `fps=${fps.toFixed(4)}` : null,
-            "format=yuv444p",
-            "signalstats",
-            "metadata=print:file=-",
-        ]
-            .filter(Boolean)
-            .join(",");
-        const raw = execFileSync(ffmpegPath, [
+        return execFileSync(ffmpegPath, [
             "-hide_banner",
             "-nostdin",
             "-v",
             "error",
+            ...keyframeSeek,
             "-i",
             mediaPath,
             "-vf",
-            filters,
+            `trim=end_frame=${frames},format=yuv444p,signalstats,metadata=print:file=-`,
             "-frames:v",
-            String(SAMPLE_FRAMES),
+            String(frames),
             "-f",
             "null",
             "-",
         ], {
             encoding: "utf8",
-            timeout: Number(process.env.HYPERFRAMES_ANALYZE_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS,
+            timeout: timeoutMs,
             stdio: ["ignore", "pipe", "pipe"],
             windowsHide: true,
         });
+    }
+    catch (error) {
+        if (error.code !== "ETIMEDOUT")
+            throw error;
+        const target = seekSeconds === null
+            ? `the first ${frames} frames`
+            : `the frame at ${seekSeconds.toFixed(1)}s`;
+        throw new Error(`FFmpeg took longer than ${timeoutMs / 1000}s to measure ${target}; set HYPERFRAMES_ANALYZE_TIMEOUT_MS to allow more`);
+    }
+}
+export function analyzeMediaGrade(mediaPath, options = {}) {
+    const ffmpegPath = options.ffmpegPath ?? "ffmpeg";
+    const ffprobePath = options.ffprobePath ?? "ffprobe";
+    try {
+        const probe = probeMedia(mediaPath, ffprobePath);
+        const isImage = IMAGE_EXTENSIONS.has(extname(mediaPath).toLowerCase());
+        const raw = !isImage && probe.duration
+            ? gradeSampleTimes(probe.duration)
+                .map((time) => readSignalStats(ffmpegPath, mediaPath, time, 1))
+                .join("\n")
+            : readSignalStats(ffmpegPath, mediaPath, null, SAMPLE_FRAMES);
         return summarizeMediaTreatmentAnalysis(probe, parseMediaTreatmentSignalStats(raw));
     }
     catch (error) {

package/dist/previewProxyBox.d.ts

@@ -1,5 +1,6 @@
 /** Query parameter carrying the largest box, in device pixels, a preview shows a proxied video at. */
 export declare const PREVIEW_PROXY_BOX_PARAM = "hf-proxy-box";
+export declare const PREVIEW_PROXY_LIGHT_PARAM = "hf-proxy-light";
 export type PreviewProxyBox = {
     width: number;
     height: number;
@@ -9,3 +10,16 @@ export declare function quantizePreviewProxyBox(width: number, height: number):
 export declare function formatPreviewProxyBox(box: PreviewProxyBox): string;
 /** Accepts only ladder rungs, so a client cannot make one cached copy per pixel. */
 export declare function parsePreviewProxyBox(raw: string): PreviewProxyBox | null;
+export declare const PREVIEW_QUALITY_LEVELS: readonly [1, 0.5, 0.25, 0.125];
+export type PreviewQuality = (typeof PREVIEW_QUALITY_LEVELS)[number];
+export declare function isPreviewQuality(value: unknown): value is PreviewQuality;
+export type PreviewSourceFacts = {
+    width: number;
+    height: number;
+    bitDepth: number;
+    bitrate: number;
+};
+export declare const HEAVY_PIXEL_SHARE = 0.5;
+export declare const HEAVY_BITRATE = 40000000;
+export declare function scalePreviewProxyBox(box: PreviewProxyBox, level: PreviewQuality): PreviewProxyBox;
+export declare function isHeavyForPreview(facts: PreviewSourceFacts, copyBox: PreviewProxyBox): boolean;

package/dist/previewProxyBox.js

@@ -1,5 +1,6 @@
 /** Query parameter carrying the largest box, in device pixels, a preview shows a proxied video at. */
 export const PREVIEW_PROXY_BOX_PARAM = "hf-proxy-box";
+export const PREVIEW_PROXY_LIGHT_PARAM = "hf-proxy-light";
 // 256 * 2^(k/4), even: nearby boxes share one cached copy, and a rung overshoots by at most ~19%.
 const RUNGS = [
     256, 304, 362, 430, 512, 608, 724, 862, 1024, 1218, 1448, 1722, 2048, 2436, 2896, 3444, 4096,
@@ -28,3 +29,17 @@ export function parsePreviewProxyBox(raw) {
     const height = Number(match[2]);
     return RUNGS.includes(width) && RUNGS.includes(height) ? { width, height } : null;
 }
+export const PREVIEW_QUALITY_LEVELS = [1, 0.5, 0.25, 0.125];
+export function isPreviewQuality(value) {
+    return PREVIEW_QUALITY_LEVELS.some((level) => level === value);
+}
+export const HEAVY_PIXEL_SHARE = 0.5;
+export const HEAVY_BITRATE = 40_000_000;
+export function scalePreviewProxyBox(box, level) {
+    return quantizePreviewProxyBox(box.width * level, box.height * level) ?? box;
+}
+export function isHeavyForPreview(facts, copyBox) {
+    return (copyBox.width * copyBox.height <= HEAVY_PIXEL_SHARE * facts.width * facts.height ||
+        facts.bitDepth > 8 ||
+        facts.bitrate >= HEAVY_BITRATE);
+}

package/dist/runtime/bridge.d.ts

@@ -22,6 +22,7 @@ type BridgeDeps = {
     onSetRuntimeData?: (channel: string, payload: unknown, requestId?: number) => void;
     onClearRuntimeData?: (channel: string, requestId?: number) => void;
     onSetDisplayScale?: (scale: number) => void;
+    onSetPreviewQuality?: (level: number) => void;
     getCanonicalFps: () => number;
 };
 export declare function setRuntimeProtocolFps(fps: number): void;

package/dist/runtime/bridge.js

@@ -30,6 +30,7 @@ const CONTROL_HANDLERS = new Map(Object.entries({
     "set-playback-rate": (data, deps) => deps.onSetPlaybackRate(Number(data.playbackRate ?? 1)),
     "set-idle-heartbeat": (data, deps) => deps.onSetIdleHeartbeat(Boolean(data.slow)),
     "set-display-scale": (data, deps) => deps.onSetDisplayScale?.(Number(data.scale)),
+    "set-preview-quality": (data, deps) => deps.onSetPreviewQuality?.(Number(data.level)),
     "set-root-duration": (data, deps) => deps.onSetRootDuration(Number(data.durationSeconds ?? 0)),
     "set-play-range": (data, deps) => deps.onSetPlayRange(Number(data.startSeconds ?? 0), data.endSeconds == null ? null : Number(data.endSeconds)),
     "set-color-grading": (data, deps) => deps.onSetColorGrading(data.target ?? null, data.grading ?? null),

package/dist/runtime/clipReveal.d.ts

@@ -1,7 +1,7 @@
 /** The visibility pass's mark on a timed clip it hides; the runtime's rules hide the clip's contents by it. */
 export declare const CLIP_HIDDEN_ATTR = "data-hf-clip-hidden";
 /** Shows a clip the visibility pass hid, contents included; returns a function that puts the mark back. */
-export declare function revealClip(el: HTMLElement, priority?: string): () => void;
+export declare function revealClip(el: Element & ElementCSSInlineStyle, priority?: string): () => void;
 /** Called by shader-transitions builds on load: their revealers go through revealClip. */
 export declare function declareClipRevealAware(): void;
 /** A shader-transitions build is on the page whose revealers predate revealClip. */

package/dist/runtime/diagnostics.d.ts

@@ -1,3 +1,5 @@
 /** The named error readiness waits fail with once start-up or the render-ready publish throws; it stays set. */
 export declare function recordStartupError(error: unknown): void;
+/** Starts the warning for a scene callback that threw; the render log shows it once per render. */
+export declare const SCENE_CALLBACK_ERROR_PREFIX = "[hyperframes] scene timeline callback threw:";
 export declare function swallow(label: string, error?: unknown): void;

package/dist/runtime/diagnostics.js

@@ -32,15 +32,24 @@ import { getDebugSurface } from "./globals.js";
 export function recordStartupError(error) {
     let detail = "unknown error";
     try {
-        detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+        if (error instanceof Error) {
+            detail = `${error.name}: ${error.message}`;
+            detail += startupErrorStack(error, detail);
+        }
+        else {
+            detail = String(error);
+        }
     }
     catch (err) {
         swallow("runtime.startupError", err);
     }
+    detail = detail.replace(/\s+/g, " ").trim();
     window.__hfStartupError =
         `HyperFrames runtime failed: ${detail}. Check the composition's scripts and window.__timelines ` +
             `entries; if they look right, report this as a HyperFrames bug.`;
 }
+/** Starts the warning for a scene callback that threw; the render log shows it once per render. */
+export const SCENE_CALLBACK_ERROR_PREFIX = "[hyperframes] scene timeline callback threw:";
 export function swallow(label, error) {
     if (typeof window === "undefined")
         return;
@@ -63,3 +72,33 @@ export function swallow(label, error) {
         console.debug(`[hyperframes] ${label} swallowed:`, error);
     }
 }
+function isCompositionFrame(frame) {
+    const location = /(?:\(|@|\bat )(\S+?):\d+(?::\d+)?\)?$/.exec(frame)?.[1];
+    if (!location || location.startsWith("hyperframes://"))
+        return false;
+    return (location.startsWith("hyperframes-composition://") ||
+        /\.html?(?:[?#]|$)/i.test(location) ||
+        (typeof document !== "undefined" && location === document.URL));
+}
+function startupErrorStack(error, header) {
+    try {
+        const stack = error.stack;
+        if (typeof stack !== "string")
+            return "";
+        const hasHeader = stack === header || stack.startsWith(`${header}\n`) || stack.startsWith(`${header}\r`);
+        const body = hasHeader ? stack.slice(header.length) : stack;
+        const frames = body
+            .split(/[\r\n]+/)
+            .map((line) => line.trim().replace(/\s+/g, " "))
+            .filter((line) => /^at\s+\S/.test(line) || /^[^@]*@.+:\d+(?::\d+)?$/.test(line));
+        const selected = frames.slice(0, 3);
+        const composition = frames.find(isCompositionFrame);
+        if (composition && !selected.includes(composition))
+            selected.push(composition);
+        return selected.length ? ` [thrown at: ${selected.join(" <- ")}]` : "";
+    }
+    catch (err) {
+        swallow("runtime.startupError.stack", err);
+        return "";
+    }
+}

package/dist/runtime/media.d.ts

@@ -81,6 +81,7 @@ export declare function evictMediaSyncState(el: HTMLMediaElement): void;
 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: {

package/dist/runtime/media.js

@@ -193,6 +193,19 @@ export function hasMediaSyncStateForTest(el) {
 }
 export const MEDIA_HARD_SYNC_SECONDS = 0.5;
 export const VIDEO_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);
+    if (clip.sourceDuration == null)
+        return target;
+    const loopLength = clip.sourceDuration - clip.mediaStart;
+    if (clip.loop && loopLength > 0 && target >= clip.sourceDuration)
+        return clip.mediaStart + ((target - clip.mediaStart) % loopLength);
+    // A non-loop video past its source holds the last frame.
+    if (!clip.loop && clip.el.tagName === "VIDEO")
+        return Math.min(target, clip.sourceDuration);
+    return target;
+}
 function prepareUpcomingVideo(clip, time, playing, rate) {
     const { el } = clip;
     const dueIn = clip.start - time;
@@ -206,15 +219,7 @@ function prepareUpcomingVideo(clip, time, playing, rate) {
         findInjectedRenderFrame(el) ||
         ("__HF_EXPORT_RENDER_SEEK_CONFIG" in window && window.__HF_EXPORT_RENDER_SEEK_CONFIG))
         return;
-    let target = clip.mediaStart +
-        sourceTimeAt(clip.rate ?? clip.playbackRate, clip.start - (clip.origin ?? clip.start));
-    if (clip.sourceDuration != null) {
-        const loopLength = clip.sourceDuration - clip.mediaStart;
-        if (clip.loop && loopLength > 0 && target >= clip.sourceDuration)
-            target = clip.mediaStart + ((target - clip.mediaStart) % loopLength);
-        else if (!clip.loop)
-            target = Math.min(target, clip.sourceDuration);
-    }
+    const target = mediaSourceTimeAt(clip, clip.start);
     if (!Number.isFinite(target) || target < 0 || Math.abs(el.currentTime - target) <= 0.001)
         return;
     try {
@@ -282,13 +287,9 @@ export function syncRuntimeMedia(params) {
             !inWindow &&
             (params.timeSeconds >= clip.end || sameInstant(params.timeSeconds, clip.end)) &&
             isClipVisibleAt(params.timeSeconds, clip.start, clip.end, params.getCompositionDuration());
-        let relTime = sourceTimeAt(clipRate, Math.max(0, Math.min(params.timeSeconds, clip.end) - origin)) +
-            clip.mediaStart;
+        const relTime = mediaSourceTimeAt(clip, params.timeSeconds);
         const isHeldVideoTail = isTerminalVideo ||
             (isNonLoopVideo && clip.sourceDuration != null && relTime >= clip.sourceDuration && inWindow);
-        if (isHeldVideoTail && clip.sourceDuration != null) {
-            relTime = Math.min(relTime, clip.sourceDuration);
-        }
         const previousRelativeTime = lastRelativeTime.get(el);
         const audioReenteredAfterBackwardSeek = el.tagName === "AUDIO" &&
             (previousRelativeTime === undefined || relTime < previousRelativeTime - 0.04);
@@ -308,13 +309,6 @@ export function syncRuntimeMedia(params) {
             (!el.ended || clip.loop || isHeldVideoTail || canSeekEndedMediaBackward);
         if (isActive) {
             lastRelativeTime.set(el, relTime);
-            // Loop wrapping: when media reaches end, restart from mediaStart
-            if (clip.loop && clip.sourceDuration != null && clip.sourceDuration > 0) {
-                const loopLength = clip.sourceDuration - clip.mediaStart;
-                if (loopLength > 0 && relTime >= clip.sourceDuration) {
-                    relTime = clip.mediaStart + ((relTime - clip.mediaStart) % loopLength);
-                }
-            }
             const userVol = clampVolume(params.userVolume ?? 1);
             const fallbackAuthorVolume = clampAudioGain(clip.volume ?? 1);
             const previousRuntimeVolume = lastRuntimeAppliedVolume.get(el);

package/dist/runtime/timedClipHide.d.ts

@@ -1,7 +1,8 @@
 import { CLIP_HIDDEN_ATTR } from "./clipReveal.js";
 export { CLIP_HIDDEN_ATTR };
 export declare const SKIPPED_CLIP = "[data-start]:not(video, audio, img, [data-hf-upcoming], [data-hf-autostamped])[data-hf-clip-hidden]";
-export declare function showHiddenClips(): () => void;
+export declare function showHiddenClips(only?: (el: HTMLElement) => boolean): () => void;
+export declare function showClips(hidden: Array<Element & ElementCSSInlineStyle>): () => void;
 export declare function defersMedia(): boolean;
 /** True in Studio's preview, where hidden clips' images are neither fetched nor decoded until due. */
 export declare function skipsHiddenImages(): boolean;

package/dist/runtime/timedClipHide.js

@@ -21,12 +21,16 @@ const hideHiddenClipContents = (clip) => {
         .join(", ");
     return `${clip} * { visibility: hidden !important; } ${filterOutputLayers} { filter: none !important; }`;
 };
-export function showHiddenClips() {
-    const hidden = Array.from(document.querySelectorAll(`[${CLIP_HIDDEN_ATTR}]`));
+export function showHiddenClips(only = () => true) {
+    return showClips(Array.from(document.querySelectorAll(`[${CLIP_HIDDEN_ATTR}]`)).filter(only));
+}
+export function showClips(hidden) {
     const putMarksBack = hidden.map((el) => revealClip(el));
     return () => {
-        for (const el of hidden)
-            el.style.visibility = "hidden";
+        for (const el of hidden) {
+            if (el.style.getPropertyValue("visibility") !== "hidden")
+                el.style.setProperty("visibility", "hidden", "important");
+        }
         for (const putMarkBack of putMarksBack)
             putMarkBack();
     };

package/dist/runtime/timeline.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeTimelineMessage, RuntimeTimelineLike } from "./types.js";
+import type { RuntimeTimelineClip, RuntimeTimelineMessage, RuntimeTimelineLike } from "./types.js";
 import { createRuntimeStartTimeResolver } from "./startResolver.js";
 export declare function runtimeElementWindow(rawNode: Element, options: {
     timelineRegistry: Record<string, RuntimeTimelineLike | undefined>;
@@ -15,12 +15,19 @@ export declare function isRuntimeElementVisibleAt(rawNode: Element, options: {
     timelineRegistry: Record<string, RuntimeTimelineLike | undefined>;
     resolver: ReturnType<typeof createRuntimeStartTimeResolver>;
 }): boolean;
+export declare function parseElementDurationAttr(element: Element): number | null;
 /**
  * Parse an authored track attribute, honoring 0 (a valid top-lane index).
  * `parseInt(...) || fallback` silently replaced authored track 0 with the
  * synthetic fallback, so track-0 clips drifted to the bottom of the timeline.
  */
 export declare function parseAuthoredTrack(el: Element, fallback: number): number;
+export type ParkedTimelineScene = {
+    name: string;
+    host: () => Element;
+};
 export declare function collectRuntimeTimelinePayload(params: {
     canonicalFps: number;
+    parked?: ParkedTimelineScene[];
+    parkedClips?: Map<string, RuntimeTimelineClip[]>;
 }): RuntimeTimelineMessage;

package/dist/runtime/timeline.js

@@ -40,9 +40,10 @@ export function runtimeElementWindow(rawNode, options) {
             duration = liveDuration;
         }
     }
+    const isRoot = compId !== null && rawNode === findRootCompositionElement(rawNode.ownerDocument);
     return {
         start,
-        end: duration != null && duration > 0 ? start + duration : Number.POSITIVE_INFINITY,
+        end: !isRoot && duration != null && duration > 0 ? start + duration : Number.POSITIVE_INFINITY,
     };
 }
 export function isRuntimeElementVisibleAt(rawNode, options) {
@@ -58,7 +59,7 @@ export function isRuntimeElementVisibleAt(rawNode, options) {
 function parseNum(value) {
     return parseStrictFiniteTimingNumber(value);
 }
-function parseElementDurationAttr(element) {
+export function parseElementDurationAttr(element) {
     const publicDuration = element.getAttribute("data-duration");
     const authoredDuration = element.getAttribute(AUTHORED_DURATION_ATTR);
     const resolved = resolveAuthoredTimingWindow({
@@ -353,13 +354,14 @@ export function collectRuntimeTimelinePayload(params) {
     // as clips — they have no declared timing so the timeline can't show their
     // actual visibility window. They can still appear as scenes via the separate
     // scene collection below.
-    const nodes = Array.from(document.querySelectorAll("[data-start], [data-track-index], [data-composition-id], video, audio, img"));
+    const CLIP_NODES = "[data-start], [data-track-index], [data-composition-id], video, audio, img";
+    const nodes = Array.from(document.querySelectorAll(CLIP_NODES));
     let maxEnd = 0;
-    for (const [i, node] of nodes.entries()) {
+    const clipOf = (node, i) => {
         if (node === root)
-            continue;
+            return null;
         if (["SCRIPT", "STYLE", "LINK", "META", "TEMPLATE", "NOSCRIPT"].includes(node.tagName))
-            continue;
+            return null;
         const compositionContext = resolveNearestCompositionContext(node, root);
         const tag = node.tagName.toLowerCase();
         let start = tag === "video" || tag === "audio"
@@ -387,21 +389,19 @@ export function collectRuntimeTimelinePayload(params) {
             }
         }
         if (duration == null || duration <= 0)
-            continue;
+            return null;
         duration = clampDurationToRootWindow(start, duration);
         if (duration <= 0)
-            continue;
+            return null;
         const slots = startResolver.resolveHostSlotsForElement(node);
         if (slots.length > 0) {
             const played = cutToHostSlots({ start, end: start + duration }, slots);
             const keepZeroLengthSoStudioNestsChildren = isNestedHost;
             if (played.end <= played.start && !keepZeroLengthSoStudioNestsChildren)
-                continue;
+                return null;
             start = played.start;
             duration = played.end - played.start;
         }
-        const end = start + duration;
-        maxEnd = Math.max(maxEnd, end);
         const kind = nodeCompositionId && nodeCompositionId !== rootCompositionId
             ? "composition"
             : tag === "video"
@@ -411,7 +411,7 @@ export function collectRuntimeTimelinePayload(params) {
                     : tag === "img"
                         ? "image"
                         : "element";
-        clips.push({
+        return {
             id: stableClipId(node) ?? nodeCompositionId ?? null,
             label: buildTimelineClipLabel(node, kind, clips.length),
             start,
@@ -433,7 +433,26 @@ export function collectRuntimeTimelinePayload(params) {
             timelineLabel: node.getAttribute("data-timeline-label"),
             timelineGroup: node.getAttribute("data-timeline-group"),
             timelinePriority: parseNum(node.getAttribute("data-timeline-priority")),
-        });
+        };
+    };
+    const addClip = (clip) => {
+        clips.push(clip);
+        maxEnd = Math.max(maxEnd, clip.start + clip.duration);
+    };
+    for (const [i, node] of nodes.entries()) {
+        const clip = clipOf(node, i);
+        if (clip)
+            addClip(clip);
+    }
+    for (const scene of params.parked ?? []) {
+        let parkedClips = params.parkedClips?.get(scene.name);
+        if (!parkedClips) {
+            const offset = nodes.length;
+            parkedClips = Array.from(scene.host().querySelectorAll(CLIP_NODES)).flatMap((node, j) => clipOf(node, offset + j) ?? []);
+            params.parkedClips?.set(scene.name, parkedClips);
+        }
+        for (const clip of parkedClips)
+            addClip(clip);
     }
     // ── GSAP introspection ──────────────────────────────────────────────────
     // Discover elements animated by GSAP that weren't picked up by the DOM query

package/dist/runtime/types.d.ts

@@ -6,7 +6,7 @@ export type RuntimeJson = string | number | boolean | null | RuntimeJson[] | {
 import type { HyperframeControlAction } from "../inline-scripts/runtimeContract.js";
 import type { HyperframePickerElementInfo } from "../inline-scripts/pickerApi.js";
 import type { RuntimeProtocolV1 } from "./protocol.js";
-type RuntimeBridgeControlActionBase = HyperframeControlAction | "tick" | "set-volume" | "set-media-output-muted" | "set-native-media-sync-disabled" | "set-web-audio-media-disabled" | "set-idle-heartbeat" | "set-display-scale" | "set-root-duration" | "set-play-range" | "stop-media" | "flash-elements";
+type RuntimeBridgeControlActionBase = HyperframeControlAction | "tick" | "set-volume" | "set-media-output-muted" | "set-native-media-sync-disabled" | "set-web-audio-media-disabled" | "set-idle-heartbeat" | "set-display-scale" | "set-preview-quality" | "set-root-duration" | "set-play-range" | "stop-media" | "flash-elements";
 type RuntimeBridgeControlMessageBase = {
     source: "hf-parent";
     type: "control";
@@ -21,6 +21,7 @@ type RuntimeBridgeControlMessageBase = {
     disabled?: boolean;
     slow?: boolean;
     scale?: number;
+    level?: number;
     playbackRate?: number;
     target?: HfColorGradingTarget | string | null;
     grading?: RuntimeJson;

package/dist/runtime/validateVariables.js

@@ -1,3 +1,4 @@
+import { isFontValue, isImageValue } from "@hyperframes/parsers/composition";
 /**
  * Compare a flat values map (from `--variables` / `data-variable-values`) to
  * the declared schema (`data-composition-variables`). Returns issues for keys
@@ -86,10 +87,7 @@ function checkType(value, decl) {
                     actual: jsTypeOf(value),
                 };
             }
-            // Object form: require the discriminant fields so a malformed brand-kit
-            // value ({name: 42} / {}) is caught here rather than surfacing as a bogus
-            // font-family at render time.
-            if (typeof value.name !== "string" || typeof value.source !== "string") {
+            if (!isFontValue(value)) {
                 return {
                     kind: "type-mismatch",
                     variableId: decl.id,
@@ -111,13 +109,14 @@ function checkType(value, decl) {
                     actual: jsTypeOf(value),
                 };
             }
-            // Object form: require the discriminant field.
-            if (typeof value.url !== "string") {
+            if (!isImageValue(value)) {
                 return {
                     kind: "type-mismatch",
                     variableId: decl.id,
                     expected: "image object {url: string}",
-                    actual: "object missing string url",
+                    actual: typeof value.url !== "string"
+                        ? "object missing string url"
+                        : "object with invalid alt/fit",
                 };
             }
             return null;

package/dist/studioPreviewMark.d.ts

@@ -5,5 +5,7 @@ export declare const STUDIO_PREVIEW_LAZY_ATTR = "data-hf-preview-lazy";
 export declare const STUDIO_PREVIEW_ERRORS = "__hfPreviewErrors";
 export declare const PREVIEW_RASTER_ATTR = "data-hf-preview-raster";
 export declare const RUNTIME_STAMPED_ATTR = "data-hf-autostamped";
-export declare const PREVIEW_ONLY_ATTRS: readonly ["data-hf-upcoming", "data-hf-preview-lazy", "data-hf-preview-raster", "data-hf-autostamped"];
+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 function applyAuthoredTiming(el: Element, attrs: ReadonlyArray<readonly [name: string, value: string]>): void;

package/dist/studioPreviewMark.js

@@ -5,8 +5,12 @@ export const STUDIO_PREVIEW_LAZY_ATTR = "data-hf-preview-lazy";
 export const STUDIO_PREVIEW_ERRORS = "__hfPreviewErrors";
 export const PREVIEW_RASTER_ATTR = "data-hf-preview-raster";
 export const RUNTIME_STAMPED_ATTR = "data-hf-autostamped";
+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 = [
     STUDIO_PREVIEW_UPCOMING_ATTR,
+    STUDIO_PREVIEW_FAR_SCENE_ATTR,
+    STUDIO_PREVIEW_PARKED_SCENE_ATTR,
     STUDIO_PREVIEW_LAZY_ATTR,
     PREVIEW_RASTER_ATTR,
     RUNTIME_STAMPED_ATTR,

package/dist/variables.d.ts

@@ -5,7 +5,7 @@
  * the Node-only modules reachable from the core/parsers root entries, so
  * browser consumers (SDK, Studio, embedders) can bundle it.
  */
-export type { CompositionVariable, CompositionVariableType, CompositionVariableBase, StringVariable, NumberVariable, ColorVariable, BooleanVariable, EnumVariable, FontVariable, ImageVariable, } from "@hyperframes/parsers/composition";
+export type { CompositionVariable, CompositionVariableType, CompositionVariableBase, StringVariable, NumberVariable, ColorVariable, BooleanVariable, EnumVariable, FontVariable, FontValue, ImageVariable, ImageValue, } from "@hyperframes/parsers/composition";
 export { COMPOSITION_VARIABLE_TYPES, parseCompositionVariables, isCompositionVariable, isScalarVariableValue, scanVariableUsage, } from "@hyperframes/parsers/composition";
 export type { VariableUsageScan } from "@hyperframes/parsers/composition";
 export { getVariables, readDeclaredDefaults } from "./runtime/getVariables.js";

package/package.json

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