@hyperframes/core 0.8.201 → 0.8.203

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export type { SlideshowManifest, SlideRef, SlideHotspot, SlideSequence, Resolved
 export { parseSlideshowManifest, resolveSlideshow } from "./slideshow/index.js";
 export type { AuthoredTimingValue, RawAuthoredTiming, AuthoredTimingWindow, } from "./runtime/authoredTiming.js";
 export { resolveAuthoredTimingWindow } from "./runtime/authoredTiming.js";
-export { CANVAS_DIMENSIONS, VALID_CANVAS_RESOLUTIONS, normalizeResolutionFlag, isAspectAgnosticResolutionAlias, resolveResolutionFlagPair, checkOutputResolutionCompatibility, suggestMatchingPreset, parseFps, parseFpsWithDefault, toFps, fpsToNumber, fpsToFfmpegArg, TIMELINE_COLORS, DEFAULT_DURATIONS, COMPOSITION_VARIABLE_TYPES, isTextElement, isMediaElement, isCompositionElement, getDefaultStageZoom, } from "./core.types.js";
+export { CANVAS_DIMENSIONS, VALID_CANVAS_RESOLUTIONS, normalizeResolutionFlag, isAspectAgnosticResolutionAlias, resolveResolutionFlagPair, checkOutputResolutionCompatibility, outputResolutionForSize, suggestMatchingPreset, parseFps, parseFpsWithDefault, toFps, fpsToNumber, fpsToFfmpegArg, TIMELINE_COLORS, DEFAULT_DURATIONS, COMPOSITION_VARIABLE_TYPES, isTextElement, isMediaElement, isCompositionElement, getDefaultStageZoom, } from "./core.types.js";
 export { DISTRIBUTED_FPS, type DistributedFps, isDistributedFps } from "./distributedFps.js";
 export { generateBaseHtml, getStageStyles } from "./templates/base.js";
 export { GSAP_CDN, BASE_STYLES, ELEMENT_BASE_STYLES, MEDIA_STYLES, TEXT_STYLES, ZOOM_CONTAINER_STYLES, } from "./templates/constants.js";
@@ -33,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 { 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 { HEAVY_BITRATE, HEAVY_PIXEL_SHARE, PREVIEW_PROXY_BOX_PARAM, PREVIEW_PROXY_LIGHT_PARAM, PREVIEW_PROXY_PROGRESS_HEADER, PREVIEW_PROXY_RETRY_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

@@ -1,6 +1,6 @@
 export { parseSlideshowManifest, resolveSlideshow } from "./slideshow/index.js";
 export { resolveAuthoredTimingWindow } from "./runtime/authoredTiming.js";
-export { CANVAS_DIMENSIONS, VALID_CANVAS_RESOLUTIONS, normalizeResolutionFlag, isAspectAgnosticResolutionAlias, resolveResolutionFlagPair, checkOutputResolutionCompatibility, suggestMatchingPreset, parseFps, parseFpsWithDefault, toFps, fpsToNumber, fpsToFfmpegArg, TIMELINE_COLORS, DEFAULT_DURATIONS, COMPOSITION_VARIABLE_TYPES, isTextElement, isMediaElement, isCompositionElement, getDefaultStageZoom, } from "./core.types.js";
+export { CANVAS_DIMENSIONS, VALID_CANVAS_RESOLUTIONS, normalizeResolutionFlag, isAspectAgnosticResolutionAlias, resolveResolutionFlagPair, checkOutputResolutionCompatibility, outputResolutionForSize, suggestMatchingPreset, parseFps, parseFpsWithDefault, toFps, fpsToNumber, fpsToFfmpegArg, TIMELINE_COLORS, DEFAULT_DURATIONS, COMPOSITION_VARIABLE_TYPES, isTextElement, isMediaElement, isCompositionElement, getDefaultStageZoom, } from "./core.types.js";
 export { DISTRIBUTED_FPS, isDistributedFps } from "./distributedFps.js";
 // Templates
 export { generateBaseHtml, getStageStyles } from "./templates/base.js";
@@ -29,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 { 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";
+export { HEAVY_BITRATE, HEAVY_PIXEL_SHARE, PREVIEW_PROXY_BOX_PARAM, PREVIEW_PROXY_LIGHT_PARAM, PREVIEW_PROXY_PROGRESS_HEADER, PREVIEW_PROXY_RETRY_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/previewProxyBox.d.ts

@@ -1,6 +1,8 @@
 /** 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 declare const PREVIEW_PROXY_RETRY_PARAM = "hf-proxy-retry";
+export declare const PREVIEW_PROXY_PROGRESS_HEADER = "X-HF-Proxy-Progress";
 export type PreviewProxyBox = {
     width: number;
     height: number;
@@ -18,6 +20,7 @@ export type PreviewSourceFacts = {
     height: number;
     bitDepth: number;
     bitrate: number;
+    codec?: string;
 };
 export declare const HEAVY_PIXEL_SHARE = 0.5;
 export declare const HEAVY_BITRATE = 40000000;

package/dist/previewProxyBox.js

@@ -1,6 +1,8 @@
 /** 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";
+export const PREVIEW_PROXY_RETRY_PARAM = "hf-proxy-retry";
+export const PREVIEW_PROXY_PROGRESS_HEADER = "X-HF-Proxy-Progress";
 // 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,

package/dist/runtime/bridge.d.ts

@@ -23,6 +23,8 @@ type BridgeDeps = {
     onClearRuntimeData?: (channel: string, requestId?: number) => void;
     onSetDisplayScale?: (scale: number) => void;
     onSetPreviewQuality?: (level: number) => void;
+    onRetryPreviewCopies?: () => void;
+    onRequestPreviewFacts?: () => void;
     getCanonicalFps: () => number;
 };
 export declare function setRuntimeProtocolFps(fps: number): void;

package/dist/runtime/bridge.js

@@ -31,6 +31,8 @@ const CONTROL_HANDLERS = new Map(Object.entries({
     "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)),
+    "retry-preview-copies": (_d, deps) => deps.onRetryPreviewCopies?.(),
+    "request-preview-facts": (_d, deps) => deps.onRequestPreviewFacts?.(),
     "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/media.d.ts

@@ -111,7 +111,7 @@ export declare function syncRuntimeMedia(params: {
      */
     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) => void;
+    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. */

package/dist/runtime/media.js

@@ -375,6 +375,7 @@ export function syncRuntimeMedia(params) {
                 authorVolume = fallbackAuthorVolume;
             }
             // Clip-local fade on top of the resolved level, matching render's afade-after-volume.
+            const unfadedVolume = authorVolume;
             const fades = clip.fades ?? NO_FADES;
             if (fades.fadeIn > 0 || fades.fadeOut > 0) {
                 authorVolume *= fadeGain(params.timeSeconds - origin, clip.duration + clip.start - origin, fades);
@@ -392,7 +393,10 @@ export function syncRuntimeMedia(params) {
             if (Math.abs(el.volume - effectiveVolume) > 1e-6)
                 el.volume = effectiveVolume;
             lastRuntimeAppliedVolume.set(el, effectiveVolume);
-            params.onElementVolume?.(el, effectiveVolume, authorVolume, preFxGain);
+            if (unfadedVolume === authorVolume)
+                params.onElementVolume?.(el, effectiveVolume, authorVolume, preFxGain);
+            else
+                params.onElementVolume?.(el, effectiveVolume, authorVolume, preFxGain, unfadedVolume);
             // Mute only when force-muted or the transport owns this element; an unclaimed
             // track stays audible via the HTMLMedia fallback.
             if ((forceMuteAll || params.isWebAudioOwned?.(el)) && !el.muted)

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-preview-quality" | "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" | "retry-preview-copies" | "request-preview-facts" | "set-root-duration" | "set-play-range" | "stop-media" | "flash-elements";
 type RuntimeBridgeControlMessageBase = {
     source: "hf-parent";
     type: "control";
@@ -212,7 +212,51 @@ export type RuntimeGroupLevelsMessage = {
         clipped: boolean;
     }>;
 };
-export type RuntimeOutboundMessage = RuntimeStateMessage | RuntimeTimelineMessage | RuntimeDiagnosticMessage | RuntimePickerHoveredMessage | RuntimePickerCandidatesMessage | RuntimePickerPickedMessage | RuntimePickerPickedManyMessage | RuntimePickerCancelledMessage | RuntimeStageSizeMessage | RuntimeMediaAutoplayBlockedMessage | RuntimeReadyMessage | RuntimeAssetsReadyMessage | RuntimeDataErrorMessage | RuntimeDataAppliedMessage | RuntimeAnalyticsMessage | RuntimePerformanceMessage | RuntimeGroupLevelsMessage;
+export type RuntimePreviewCopiesMessage = {
+    source: "hf-preview";
+    type: "preview-copies";
+    /** The lighter copies wanted at the current quality; null when none are. */
+    copies: {
+        total: number;
+        ready: number;
+        failed: number;
+        progress: number;
+        error: string | null;
+    } | null;
+};
+export type RuntimePreviewHealthMessage = {
+    source: "hf-preview";
+    type: "preview-health";
+    /** How playback went over the last few seconds of play; null while paused, seeking or warming up. */
+    health: {
+        droppedShare: number;
+        seconds: number;
+        choppy: boolean;
+        fps: number;
+        worstFrameMs: number;
+        mode: "play";
+    } | null;
+};
+export type RuntimePreviewFactsMessage = {
+    source: "hf-preview";
+    type: "preview-facts";
+    facts: {
+        sceneCount: number;
+        mountedElementCount: number;
+        durationSeconds: number;
+        videos: Array<{
+            codec: string;
+            width: number;
+            height: number;
+            bitDepth: number;
+            count: number;
+        }>;
+        /** The lower levels at which at least one video gets a lighter copy. */
+        lighterAt: number[];
+        copiesReady: boolean;
+    };
+};
+export type RuntimeOutboundMessage = RuntimeStateMessage | RuntimePreviewCopiesMessage | RuntimePreviewHealthMessage | RuntimePreviewFactsMessage | RuntimeTimelineMessage | RuntimeDiagnosticMessage | RuntimePickerHoveredMessage | RuntimePickerCandidatesMessage | RuntimePickerPickedMessage | RuntimePickerPickedManyMessage | RuntimePickerCancelledMessage | RuntimeStageSizeMessage | RuntimeMediaAutoplayBlockedMessage | RuntimeReadyMessage | RuntimeAssetsReadyMessage | RuntimeDataErrorMessage | RuntimeDataAppliedMessage | RuntimeAnalyticsMessage | RuntimePerformanceMessage | RuntimeGroupLevelsMessage;
 export type HeldSeek = Promise<void> | void;
 export type RuntimePlayer = {
     _timeline: RuntimeTimelineLike | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.8.201",
+  "version": "0.8.203",
   "description": "",
   "repository": {
     "type": "git",
@@ -96,6 +96,10 @@
       "import": "./dist/motionBlurSettings.js",
       "types": "./dist/motionBlurSettings.d.ts"
     },
+    "./preview-quality": {
+      "import": "./dist/previewProxyBox.js",
+      "types": "./dist/previewProxyBox.d.ts"
+    },
     "./gsap-cdn": {
       "import": "./dist/gsapCdn.js",
       "types": "./dist/gsapCdn.d.ts"
@@ -397,9 +401,9 @@
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
     "wawoff2": "^2.0.1",
-    "@hyperframes/lint": "0.8.201",
-    "@hyperframes/studio-server": "0.8.201",
-    "@hyperframes/parsers": "0.8.201"
+    "@hyperframes/parsers": "0.8.203",
+    "@hyperframes/studio-server": "0.8.203",
+    "@hyperframes/lint": "0.8.203"
   },
   "devDependencies": {
     "@fontsource/archivo-black": "^5.2.8",