@hyperframes/core 0.8.200 → 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";

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";

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/diagnostics.js

@@ -32,11 +32,18 @@ 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.`;
@@ -65,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.js

@@ -27,8 +27,10 @@ export function showHiddenClips(only = () => true) {
 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.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) {

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/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.200",
+  "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/studio-server": "0.8.200",
-    "@hyperframes/parsers": "0.8.200",
-    "@hyperframes/lint": "0.8.200"
+    "@hyperframes/lint": "0.8.201",
+    "@hyperframes/studio-server": "0.8.201",
+    "@hyperframes/parsers": "0.8.201"
   },
   "devDependencies": {
     "@fontsource/archivo-black": "^5.2.8",