@hyperframes/core 0.8.57 → 0.8.59

package/dist/runtime/timeline.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeTimelineMessage, RuntimeTimelineLike } from "./types";
+import { createRuntimeStartTimeResolver } from "./startResolver";
+export declare function isRuntimeElementVisibleAt(rawNode: HTMLElement, options: {
+    currentTime: number;
+    compositionDuration: number;
+    canonicalFps: number;
+    exportRenderSeek: boolean;
+    timelineRegistry: Record<string, RuntimeTimelineLike | undefined>;
+    resolver: ReturnType<typeof createRuntimeStartTimeResolver>;
+}): boolean;
+export declare function collectRuntimeTimelinePayload(params: {
+    canonicalFps: number;
+}): RuntimeTimelineMessage;
+//# sourceMappingURL=timeline.d.ts.map

package/dist/runtime/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/runtime/timeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,sBAAsB,EAEtB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAgBjB,OAAO,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAQjE,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE;IACP,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,SAAS,CAAC,CAAC;IAClE,QAAQ,EAAE,UAAU,CAAC,OAAO,8BAA8B,CAAC,CAAC;CAC7D,GACA,OAAO,CAiDT;AAmJD,wBAAgB,6BAA6B,CAAC,MAAM,EAAE;IACpD,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,sBAAsB,CAudzB"}

package/dist/runtime/timeline.js

@@ -0,0 +1,650 @@
+import { stableClipId } from "./clipTree.js";
+import { AUTHORED_DURATION_ATTR, AUTHORED_END_ATTR, resolveAuthoredTimingWindow, } from "./authoredTiming.js";
+import { swallow } from "./diagnostics.js";
+import { readElementPlaybackRate, readElementPlaybackStart } from "./media.js";
+import { parseStrictFiniteTimingNumber, resolveMediaElementDurationSeconds, resolveNaturalMediaTimelineDuration, resolveTimedImageDurationSeconds, } from "./playbackRate.js";
+import { resolveCssStackingContextId } from "./stackingContext.js";
+import { createRuntimeStartTimeResolver } from "./startResolver.js";
+import { isClipVisibleAt } from "./clipWindow.js";
+import { snapTimeToFrameBoundary } from "../inline-scripts/parityContract.js";
+import { isSceneLikeCompositionId } from "../slideshow/index.js";
+import { COMPOSITION_CONTRACT_VERSION } from "../compositionContract.js";
+import { runtimeProtocolMetadata } from "./protocol.js";
+import { isElementNode, isMediaElement } from "./domRealm.js";
+export function isRuntimeElementVisibleAt(rawNode, options) {
+    const tag = rawNode.tagName.toLowerCase();
+    if (tag === "script" || tag === "style" || tag === "link" || tag === "meta") {
+        return false;
+    }
+    const isMedia = tag === "video" || tag === "audio";
+    const start = isMedia
+        ? options.resolver.resolveMediaStartForElement(rawNode)
+        : options.resolver.resolveStartForElement(rawNode, 0);
+    let duration = options.resolver.resolveDurationForElement(rawNode);
+    const compId = rawNode.getAttribute("data-composition-id");
+    if (compId) {
+        const compTimeline = options.timelineRegistry[compId];
+        const liveDuration = compTimeline && typeof compTimeline.duration === "function"
+            ? Number(compTimeline.duration())
+            : null;
+        const hasAuthoredTiming = rawNode.hasAttribute("data-duration") ||
+            rawNode.hasAttribute("data-end") ||
+            rawNode.hasAttribute(AUTHORED_DURATION_ATTR) ||
+            rawNode.hasAttribute(AUTHORED_END_ATTR);
+        if (!hasAuthoredTiming &&
+            (duration == null || duration <= 0) &&
+            liveDuration != null &&
+            Number.isFinite(liveDuration) &&
+            liveDuration > 0) {
+            duration = liveDuration;
+        }
+    }
+    const computedEnd = duration != null && duration > 0 ? start + duration : Number.POSITIVE_INFINITY;
+    // Export seeks snap to frame boundaries; interactive visibility uses authored seconds.
+    const visibilityStart = options.exportRenderSeek
+        ? snapTimeToFrameBoundary(start, options.canonicalFps)
+        : start;
+    const visibilityEnd = options.exportRenderSeek && Number.isFinite(computedEnd)
+        ? snapTimeToFrameBoundary(computedEnd, options.canonicalFps)
+        : computedEnd;
+    return isClipVisibleAt(options.currentTime, visibilityStart, visibilityEnd, options.compositionDuration);
+}
+function parseNum(value) {
+    return parseStrictFiniteTimingNumber(value);
+}
+function parseElementDurationAttr(element) {
+    const publicDuration = element.getAttribute("data-duration");
+    const authoredDuration = element.getAttribute(AUTHORED_DURATION_ATTR);
+    const resolved = resolveAuthoredTimingWindow({
+        start: 0,
+        duration: publicDuration,
+        authoredDuration,
+    })?.duration;
+    if (resolved != null)
+        return resolved;
+    const hasExplicitNonpositive = [publicDuration, authoredDuration]
+        .map(parseNum)
+        .some((duration) => duration != null && duration <= 0);
+    return hasExplicitNonpositive ? 0 : null;
+}
+function parseElementEndAttr(element) {
+    return (resolveAuthoredTimingWindow({
+        start: 0,
+        end: element.getAttribute("data-end"),
+        authoredEnd: element.getAttribute(AUTHORED_END_ATTR),
+    })?.end ?? null);
+}
+function readInlineZIndex(element) {
+    try {
+        const inline = element.style?.zIndex;
+        if (inline && inline !== "auto") {
+            const parsed = parseInt(inline, 10);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+        return 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function maxDefinedNumber(...values) {
+    const finite = values.filter((value) => Number.isFinite(value ?? null));
+    if (finite.length === 0)
+        return null;
+    return Math.max(...finite);
+}
+/**
+ * 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.
+ */
+function parseAuthoredTrack(el, fallback) {
+    const raw = el.getAttribute("data-track-index") ?? el.getAttribute("data-track");
+    if (raw == null)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function toAbsoluteAssetUrl(rawValue) {
+    const raw = String(rawValue ?? "").trim();
+    if (!raw)
+        return null;
+    const lowered = raw.toLowerCase();
+    if (lowered.startsWith("data:") || lowered.startsWith("javascript:"))
+        return null;
+    try {
+        return new URL(raw, document.baseURI).toString();
+    }
+    catch {
+        return raw;
+    }
+}
+function resolveNodeAssetUrl(node) {
+    const src = node.getAttribute("src") ?? node.getAttribute("data-src");
+    if (src)
+        return toAbsoluteAssetUrl(src);
+    const compositionSrc = node.getAttribute("data-composition-src");
+    if (compositionSrc)
+        return toAbsoluteAssetUrl(compositionSrc);
+    const mediaDescendant = node.querySelector("img[src], video[src], audio[src], source[src]");
+    if (!mediaDescendant)
+        return null;
+    return toAbsoluteAssetUrl(mediaDescendant.getAttribute("src"));
+}
+function getFirstClassToken(node) {
+    const className = node.className;
+    if (typeof className !== "string")
+        return null;
+    return (className
+        .split(/\s+/)
+        .map((value) => value.trim())
+        .find((value) => value && value !== "clip" && !value.startsWith("__hf-")) ?? null);
+}
+function filenameFromAssetUrl(url) {
+    if (!url)
+        return null;
+    try {
+        const parsed = new URL(url, document.baseURI);
+        return parsed.pathname.split("/").filter(Boolean).at(-1) ?? null;
+    }
+    catch {
+        return url.split(/[\\/]/).filter(Boolean).at(-1) ?? null;
+    }
+}
+function textPreview(node) {
+    const text = node.textContent?.replace(/\s+/g, " ").trim();
+    if (!text)
+        return null;
+    return text.length > 32 ? `${text.slice(0, 31)}...` : text;
+}
+function humanizeTimelineToken(value) {
+    const normalized = value
+        .replace(/\.[^.]+$/i, "")
+        .replace(/[-_]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!normalized)
+        return value;
+    return normalized.replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function buildTimelineClipLabel(node, kind, ordinal) {
+    const explicit = node.getAttribute("data-timeline-label") ??
+        node.getAttribute("data-label") ??
+        node.getAttribute("aria-label") ??
+        null;
+    if (explicit?.trim())
+        return explicit.trim();
+    const compositionId = node.getAttribute("data-composition-id");
+    if (compositionId)
+        return humanizeTimelineToken(compositionId);
+    const id = node.id;
+    if (id)
+        return humanizeTimelineToken(id);
+    const classToken = getFirstClassToken(node);
+    if (classToken)
+        return humanizeTimelineToken(classToken);
+    const assetName = filenameFromAssetUrl(resolveNodeAssetUrl(node));
+    if (assetName)
+        return humanizeTimelineToken(assetName);
+    const text = textPreview(node);
+    if (text)
+        return text;
+    return `${humanizeTimelineToken(kind)} ${ordinal + 1}`;
+}
+export function collectRuntimeTimelinePayload(params) {
+    const runtimeWindow = window;
+    const timelineRegistry = runtimeWindow.__timelines ?? {};
+    const startResolver = createRuntimeStartTimeResolver({
+        timelineRegistry,
+        includeAuthoredTimingAttrs: true,
+    });
+    const resolveTimelineDurationSeconds = (compositionId) => {
+        if (!compositionId)
+            return null;
+        const timeline = timelineRegistry[compositionId] ?? null;
+        if (!timeline || typeof timeline.duration !== "function")
+            return null;
+        try {
+            const duration = Number(timeline.duration());
+            return Number.isFinite(duration) && duration > 0 ? duration : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const resolveMediaWindowEndSeconds = () => {
+        const mediaNodes = Array.from(document.querySelectorAll("video[data-start], audio[data-start]"));
+        if (mediaNodes.length === 0)
+            return null;
+        let maxWindowEndSeconds = 0;
+        for (const mediaNode of mediaNodes) {
+            const start = startResolver.resolveMediaStartForElement(mediaNode);
+            if (!Number.isFinite(start))
+                continue;
+            const duration = resolveMediaElementDurationSeconds(mediaNode);
+            if (duration == null || duration <= 0)
+                continue;
+            maxWindowEndSeconds = Math.max(maxWindowEndSeconds, Math.max(0, start) + duration);
+        }
+        return maxWindowEndSeconds > 0 ? maxWindowEndSeconds : null;
+    };
+    const resolveNearestCompositionContext = (node, root) => {
+        const ancestors = [];
+        let inheritedStart = null;
+        let inheritedDuration = null;
+        let parentCompositionId = null;
+        let cursor = node.parentElement;
+        while (cursor) {
+            const compositionId = cursor.getAttribute("data-composition-id");
+            if (compositionId) {
+                ancestors.push(compositionId);
+                if (!parentCompositionId && cursor !== root) {
+                    parentCompositionId = compositionId;
+                }
+                if (inheritedStart == null) {
+                    inheritedStart = startResolver.resolveStartForElement(cursor, 0);
+                }
+                if (inheritedDuration == null) {
+                    inheritedDuration =
+                        parseNum(cursor.getAttribute("data-duration")) ??
+                            resolveTimelineDurationSeconds(compositionId) ??
+                            null;
+                }
+            }
+            cursor = cursor.parentElement;
+        }
+        return {
+            parentCompositionId,
+            compositionAncestors: ancestors.reverse(),
+            inheritedStart,
+            inheritedDuration,
+        };
+    };
+    const root = document.querySelector("[data-composition-id]");
+    const compositionNodes = Array.from(document.querySelectorAll("[data-composition-id]"));
+    const rootCompositionId = root?.getAttribute("data-composition-id") ?? null;
+    const rootCompositionStart = root ? startResolver.resolveStartForElement(root, 0) : 0;
+    const mediaWindowEnd = resolveMediaWindowEndSeconds();
+    const mediaWindowDuration = mediaWindowEnd != null ? Math.max(0, mediaWindowEnd - Math.max(0, rootCompositionStart)) : null;
+    const rootDurationFromTimeline = resolveTimelineDurationSeconds(rootCompositionId);
+    const rootDurationFromAttr = parseElementDurationAttr(root ?? document.body);
+    const compositionWindowEnd = maxDefinedNumber(...compositionNodes
+        .filter((node) => node !== root)
+        .map((node) => {
+        const start = startResolver.resolveStartForElement(node, 0);
+        const duration = startResolver.resolveDurationForElement(node) ??
+            resolveTimelineDurationSeconds(node.getAttribute("data-composition-id")) ??
+            null;
+        if (!Number.isFinite(start) || duration == null || duration <= 0)
+            return null;
+        return Math.max(0, start) + duration;
+    }));
+    const compositionWindowDuration = compositionWindowEnd != null
+        ? Math.max(0, compositionWindowEnd - Math.max(0, rootCompositionStart))
+        : null;
+    const timelineDurationCandidate = typeof rootDurationFromTimeline === "number" &&
+        Number.isFinite(rootDurationFromTimeline) &&
+        rootDurationFromTimeline > 0
+        ? rootDurationFromTimeline
+        : null;
+    const attrDurationCandidate = typeof rootDurationFromAttr === "number" &&
+        Number.isFinite(rootDurationFromAttr) &&
+        rootDurationFromAttr > 0
+        ? rootDurationFromAttr
+        : null;
+    const mediaWindowDurationCandidate = typeof mediaWindowDuration === "number" &&
+        Number.isFinite(mediaWindowDuration) &&
+        mediaWindowDuration > 0
+        ? mediaWindowDuration
+        : null;
+    const compositionWindowDurationCandidate = typeof compositionWindowDuration === "number" &&
+        Number.isFinite(compositionWindowDuration) &&
+        compositionWindowDuration > 0
+        ? compositionWindowDuration
+        : null;
+    const finiteWindowFloor = maxDefinedNumber(mediaWindowDurationCandidate, compositionWindowDurationCandidate);
+    const timelineLooksLoopInflated = timelineDurationCandidate != null &&
+        finiteWindowFloor != null &&
+        timelineDurationCandidate > finiteWindowFloor + 1;
+    // Prefer explicit authored root duration first.
+    // If absent, guard against loop-inflated GSAP durations by trusting finite media window.
+    const preferredRootDuration = attrDurationCandidate ??
+        (timelineLooksLoopInflated
+            ? finiteWindowFloor
+            : maxDefinedNumber(timelineDurationCandidate, mediaWindowDurationCandidate, compositionWindowDurationCandidate));
+    const rootCompositionDuration = preferredRootDuration ?? null;
+    const rootCompositionEnd = rootCompositionDuration != null ? rootCompositionStart + rootCompositionDuration : null;
+    const timelineWindowEnd = rootCompositionEnd ??
+        (typeof mediaWindowEnd === "number" && Number.isFinite(mediaWindowEnd) && mediaWindowEnd > 0
+            ? mediaWindowEnd
+            : null);
+    const clampDurationToRootWindow = (start, duration) => {
+        if (!Number.isFinite(duration) || duration <= 0)
+            return 0;
+        if (timelineWindowEnd == null || !Number.isFinite(timelineWindowEnd))
+            return duration;
+        if (!Number.isFinite(start) || start >= timelineWindowEnd)
+            return 0;
+        return Math.max(0, Math.min(duration, timelineWindowEnd - start));
+    };
+    const clips = [];
+    const scenes = [];
+    // Only collect elements that are explicitly part of the timeline:
+    // - Elements with data-start or data-track-index (timed clips)
+    // - Elements with data-composition-id (sub-compositions)
+    // - Media elements (video, audio, img)
+    // Elements without data-start (e.g. GSAP-animated scenes) are not included
+    // 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"));
+    let maxEnd = 0;
+    for (const [i, node] of nodes.entries()) {
+        if (node === root)
+            continue;
+        if (["SCRIPT", "STYLE", "LINK", "META", "TEMPLATE", "NOSCRIPT"].includes(node.tagName))
+            continue;
+        const compositionContext = resolveNearestCompositionContext(node, root);
+        const tag = node.tagName.toLowerCase();
+        const start = tag === "video" || tag === "audio"
+            ? startResolver.resolveMediaStartForElement(node)
+            : startResolver.resolveStartForElement(node, compositionContext.inheritedStart ?? 0);
+        const nodeCompositionId = node.getAttribute("data-composition-id");
+        let duration = parseElementDurationAttr(node);
+        if (duration == null && nodeCompositionId && nodeCompositionId !== rootCompositionId) {
+            duration = resolveTimelineDurationSeconds(nodeCompositionId);
+        }
+        if (duration == null && isMediaElement(node)) {
+            if (Number.isFinite(node.duration)) {
+                duration = resolveNaturalMediaTimelineDuration(node, node.duration);
+            }
+        }
+        if (duration == null)
+            duration = resolveTimedImageDurationSeconds(node, start);
+        if (duration == null) {
+            const inheritedDuration = compositionContext.inheritedDuration;
+            if (inheritedDuration != null && inheritedDuration > 0) {
+                const inheritedStart = compositionContext.inheritedStart ?? 0;
+                const inheritedEnd = inheritedStart + inheritedDuration;
+                duration = Math.max(0, inheritedEnd - start);
+            }
+        }
+        if (duration == null || duration <= 0)
+            continue;
+        duration = clampDurationToRootWindow(start, duration);
+        if (duration <= 0)
+            continue;
+        const end = start + duration;
+        maxEnd = Math.max(maxEnd, end);
+        const kind = nodeCompositionId && nodeCompositionId !== rootCompositionId
+            ? "composition"
+            : tag === "video"
+                ? "video"
+                : tag === "audio"
+                    ? "audio"
+                    : tag === "img"
+                        ? "image"
+                        : "element";
+        clips.push({
+            id: stableClipId(node) ?? nodeCompositionId ?? null,
+            label: buildTimelineClipLabel(node, kind, clips.length),
+            start,
+            duration,
+            track: parseAuthoredTrack(node, i),
+            zIndex: readInlineZIndex(node),
+            stackingContextId: resolveCssStackingContextId(node),
+            kind,
+            tagName: tag,
+            compositionId: node.getAttribute("data-composition-id"),
+            compositionAncestors: compositionContext.compositionAncestors,
+            parentCompositionId: compositionContext.parentCompositionId,
+            nodePath: null,
+            compositionSrc: toAbsoluteAssetUrl(node.getAttribute("data-composition-src")),
+            playbackStart: readElementPlaybackStart(node),
+            playbackRate: readElementPlaybackRate(node),
+            assetUrl: resolveNodeAssetUrl(node),
+            timelineRole: node.getAttribute("data-timeline-role"),
+            timelineLabel: node.getAttribute("data-timeline-label"),
+            timelineGroup: node.getAttribute("data-timeline-group"),
+            timelinePriority: parseNum(node.getAttribute("data-timeline-priority")),
+        });
+    }
+    // ── GSAP introspection ──────────────────────────────────────────────────
+    // Discover elements animated by GSAP that weren't picked up by the DOM query
+    // (e.g. scene divs controlled purely via opacity/display tweens).
+    // Introspect the master timeline's tweens to find their targets and time ranges.
+    // ── GSAP introspection ──────────────────────────────────────────────────
+    // Discover scene-level elements animated by GSAP that weren't picked up by
+    // the DOM query. Introspect the master timeline's tweens, resolve absolute
+    // time ranges, and bubble child tween ranges up to their nearest scene-level
+    // ancestor (direct child of root with an id).
+    const gsapClipIds = new Set(clips.map((c) => c.id));
+    const rootCompositionIdForGsap = root?.getAttribute("data-composition-id") ?? null;
+    const masterTimeline = rootCompositionIdForGsap
+        ? (timelineRegistry[rootCompositionIdForGsap] ?? null)
+        : null;
+    if (masterTimeline && root) {
+        const tlWithChildren = masterTimeline;
+        if (typeof tlWithChildren.getChildren === "function") {
+            try {
+                const tweens = tlWithChildren.getChildren(true, true, false) ?? [];
+                // Build a set of direct children of root that have an id — these are
+                // scene-level containers. Tween ranges on their descendants get bubbled
+                // up to expand the scene's time range.
+                const sceneElements = new Map();
+                for (const child of root.children) {
+                    const childEl = child;
+                    if (!childEl.id)
+                        continue;
+                    const tag = childEl.tagName.toLowerCase();
+                    if (tag === "script" || tag === "style" || tag === "link")
+                        continue;
+                    sceneElements.set(childEl, { id: childEl.id, start: Infinity, end: -Infinity });
+                }
+                // Find the scene-level ancestor for a given element
+                const findSceneAncestor = (el) => {
+                    let cursor = el;
+                    while (cursor) {
+                        if (sceneElements.has(cursor))
+                            return cursor;
+                        if (cursor === root)
+                            return null;
+                        cursor = cursor.parentElement;
+                    }
+                    return null;
+                };
+                // Walk all tweens and accumulate time ranges per scene element
+                for (const tween of tweens) {
+                    if (typeof tween.targets !== "function")
+                        continue;
+                    if (typeof tween.startTime !== "function" || typeof tween.duration !== "function")
+                        continue;
+                    let tweenStart = tween.startTime();
+                    let parent = tween.parent;
+                    while (parent && parent !== masterTimeline && typeof parent.startTime === "function") {
+                        tweenStart += parent.startTime();
+                        parent = parent.parent;
+                    }
+                    const tweenEnd = tweenStart + tween.duration();
+                    if (!Number.isFinite(tweenStart) || !Number.isFinite(tweenEnd))
+                        continue;
+                    for (const target of tween.targets()) {
+                        if (!isElementNode(target))
+                            continue;
+                        // Bubble up to the scene-level ancestor
+                        const scene = findSceneAncestor(target);
+                        if (!scene)
+                            continue;
+                        const range = sceneElements.get(scene);
+                        if (!range)
+                            continue;
+                        range.start = Math.min(range.start, tweenStart);
+                        range.end = Math.max(range.end, tweenEnd);
+                    }
+                }
+                // Create clips for scene elements that have tween ranges
+                const gsapTrack = clips.length > 0 ? Math.max(...clips.map((c) => c.track)) + 1 : 0;
+                for (const [element, range] of sceneElements) {
+                    if (range.start === Infinity || range.end === -Infinity)
+                        continue;
+                    const el = element;
+                    if (gsapClipIds.has(el.id))
+                        continue;
+                    const duration = Math.max(0, range.end - range.start);
+                    if (duration <= 0)
+                        continue;
+                    const clampedDuration = clampDurationToRootWindow(range.start, duration);
+                    if (clampedDuration <= 0)
+                        continue;
+                    maxEnd = Math.max(maxEnd, range.start + clampedDuration);
+                    clips.push({
+                        id: el.id,
+                        label: el.getAttribute("data-timeline-label") ??
+                            el.getAttribute("data-label") ??
+                            el.getAttribute("aria-label") ??
+                            el.id,
+                        start: range.start,
+                        duration: clampedDuration,
+                        track: parseAuthoredTrack(el, gsapTrack),
+                        zIndex: readInlineZIndex(el),
+                        stackingContextId: resolveCssStackingContextId(el),
+                        kind: "element",
+                        tagName: el.tagName.toLowerCase(),
+                        compositionId: el.getAttribute("data-composition-id"),
+                        compositionAncestors: rootCompositionIdForGsap ? [rootCompositionIdForGsap] : [],
+                        parentCompositionId: rootCompositionIdForGsap,
+                        nodePath: null,
+                        compositionSrc: null,
+                        playbackStart: readElementPlaybackStart(el),
+                        playbackRate: readElementPlaybackRate(el),
+                        assetUrl: null,
+                        timelineRole: el.getAttribute("data-timeline-role"),
+                        timelineLabel: el.getAttribute("data-timeline-label"),
+                        timelineGroup: el.getAttribute("data-timeline-group"),
+                        timelinePriority: parseNum(el.getAttribute("data-timeline-priority")),
+                    });
+                    gsapClipIds.add(el.id);
+                }
+            }
+            catch (err) {
+                // GSAP introspection is best-effort — don't break timeline if it fails
+                swallow("runtime.timeline.site1", err);
+            }
+        }
+    }
+    // ── Persistent overlays ─────────────────────────────────────────────────
+    // Direct children of root that are pure structural overlays should only
+    // surface in the timeline when authors explicitly opt them in. Otherwise
+    // background layers like "backdrop" make the whole composition read as a
+    // long clip, which is misleading in Studio.
+    if (root && rootCompositionDuration != null && rootCompositionDuration > 0) {
+        const overlayTrack = clips.length > 0 ? Math.max(...clips.map((c) => c.track)) + 1 : 0;
+        for (const child of root.children) {
+            const el = child;
+            if (!el.id)
+                continue;
+            if (gsapClipIds.has(el.id))
+                continue;
+            const timelineRole = el.getAttribute("data-timeline-role");
+            if (timelineRole !== "overlay" && timelineRole !== "persistent-overlay")
+                continue;
+            const tag = el.tagName.toLowerCase();
+            if (tag === "script" || tag === "style" || tag === "link" || tag === "meta")
+                continue;
+            // Skip elements that are invisible (display:none in their CSS class)
+            const computed = window.getComputedStyle(el);
+            if (computed.display === "none")
+                continue;
+            const clampedDuration = clampDurationToRootWindow(0, rootCompositionDuration);
+            if (clampedDuration <= 0)
+                continue;
+            maxEnd = Math.max(maxEnd, clampedDuration);
+            clips.push({
+                id: el.id,
+                label: el.getAttribute("data-timeline-label") ??
+                    el.getAttribute("data-label") ??
+                    el.getAttribute("aria-label") ??
+                    el.id,
+                start: 0,
+                duration: clampedDuration,
+                track: parseAuthoredTrack(el, overlayTrack),
+                zIndex: readInlineZIndex(el),
+                stackingContextId: resolveCssStackingContextId(el),
+                kind: "element",
+                tagName: tag,
+                compositionId: el.getAttribute("data-composition-id"),
+                compositionAncestors: rootCompositionIdForGsap ? [rootCompositionIdForGsap] : [],
+                parentCompositionId: rootCompositionIdForGsap,
+                nodePath: null,
+                compositionSrc: null,
+                playbackStart: readElementPlaybackStart(el),
+                playbackRate: readElementPlaybackRate(el),
+                assetUrl: null,
+                timelineRole,
+                timelineLabel: el.getAttribute("data-timeline-label"),
+                timelineGroup: el.getAttribute("data-timeline-group"),
+                timelinePriority: parseNum(el.getAttribute("data-timeline-priority")),
+            });
+            gsapClipIds.add(el.id);
+        }
+    }
+    // Track assignment honors the authored data-track-index verbatim: a clip stays
+    // on the track it was placed on, regardless of kind. (Previously mixed-kind
+    // tracks were split onto separate rows, but that renumbered tracks — breaking
+    // "drop a clip onto an existing track" and causing the written track to drift
+    // from the displayed one on every move. Track index is display-only; render
+    // never reads it, so honoring it verbatim is the correct NLE behavior.)
+    for (const compositionNode of compositionNodes) {
+        if (compositionNode === root)
+            continue;
+        const compositionId = compositionNode.getAttribute("data-composition-id");
+        if (!compositionId || !isSceneLikeCompositionId(compositionId))
+            continue;
+        const start = startResolver.resolveStartForElement(compositionNode, 0);
+        let durationFromAttr = parseElementDurationAttr(compositionNode);
+        if ((durationFromAttr == null || durationFromAttr <= 0) &&
+            parseElementEndAttr(compositionNode) != null) {
+            const end = parseElementEndAttr(compositionNode);
+            durationFromAttr = Math.max(0, end - start);
+        }
+        const durationFromTimeline = resolveTimelineDurationSeconds(compositionId);
+        const duration = durationFromAttr && durationFromAttr > 0 ? durationFromAttr : durationFromTimeline;
+        if (duration == null || duration <= 0)
+            continue;
+        const clampedDuration = clampDurationToRootWindow(start, duration);
+        if (clampedDuration <= 0)
+            continue;
+        scenes.push({
+            id: compositionId,
+            label: compositionNode.getAttribute("data-label") ?? compositionId,
+            start,
+            duration: clampedDuration,
+            thumbnailUrl: toAbsoluteAssetUrl(compositionNode.getAttribute("data-thumbnail-url")),
+            avatarName: null,
+        });
+    }
+    // Timeline payload duration should reflect the playable composition window,
+    // not just the furthest currently-surfaced clip. Studio can intentionally
+    // hide structural/background tracks from the timeline UI; if we collapse the
+    // payload duration down to the last visible clip end, the controls jump even
+    // though playback still runs for the full authored root duration.
+    const safeDuration = Math.max(1, maxEnd || 1, rootCompositionDuration ?? 0);
+    const shouldEmitNonDeterministicInf = timelineLooksLoopInflated && attrDurationCandidate == null;
+    const durationInFrames = shouldEmitNonDeterministicInf
+        ? Number.POSITIVE_INFINITY
+        : Math.max(1, Math.ceil(safeDuration * Math.max(1, params.canonicalFps)));
+    return {
+        ...runtimeProtocolMetadata(params.canonicalFps),
+        source: "hf-preview",
+        type: "timeline",
+        compositionContractVersion: COMPOSITION_CONTRACT_VERSION,
+        durationSeconds: shouldEmitNonDeterministicInf ? Number.POSITIVE_INFINITY : safeDuration,
+        durationInFrames,
+        clips,
+        scenes,
+        compositionWidth: parseNum(root?.getAttribute("data-width")) ?? 1920,
+        compositionHeight: parseNum(root?.getAttribute("data-height")) ?? 1080,
+    };
+}
+//# sourceMappingURL=timeline.js.map