@hyperframes/core 0.8.199 → 0.8.200

package/dist/index.d.ts

@@ -49,6 +49,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

@@ -44,6 +44,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/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

@@ -41,6 +41,8 @@ export function recordStartupError(error) {
         `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;

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,8 +21,10 @@ 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)

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

@@ -58,7 +58,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 +353,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 +388,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 +410,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 +432,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.8.199",
+  "version": "0.8.200",
   "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/studio-server": "0.8.200",
+    "@hyperframes/parsers": "0.8.200",
+    "@hyperframes/lint": "0.8.200"
   },
   "devDependencies": {
     "@fontsource/archivo-black": "^5.2.8",