@hyperframes/parsers 0.8.50 → 0.8.51

package/dist/index.js

@@ -494,7 +494,16 @@ import * as acorn from "acorn";
 import * as acornWalk from "acorn-walk";
 
 // src/gsapInline.ts
-var SKIP_KEYS = /* @__PURE__ */ new Set(["type", "start", "end", "loc", "range", "__hfProvenance", "__hfOrder"]);
+var SKIP_KEYS = /* @__PURE__ */ new Set([
+  "type",
+  "start",
+  "end",
+  "loc",
+  "range",
+  "__hfProvenance",
+  "__hfOrder",
+  "__hfSiteStart"
+]);
 var FUNCTION_TYPES = /* @__PURE__ */ new Set([
   "ArrowFunctionExpression",
   "FunctionExpression",
@@ -597,6 +606,9 @@ function isTimelineRooted(call, timelineVar) {
   if (timelineRootName(call) !== timelineVar) return false;
   return call.callee?.property?.type === "Identifier" && GSAP_METHODS.has(call.callee.property.name);
 }
+function isAddLabelCall(call, timelineVar) {
+  return timelineRootName(call) === timelineVar && call.callee?.property?.name === "addLabel";
+}
 function containsTimelineCall(node, timelineVar) {
   let found = false;
   walkNodes(node, (n) => {
@@ -803,12 +815,17 @@ function bodyStatements(node) {
 }
 function tagTimelineCalls(stmts, prov, ctx) {
   for (const stmt of stmts) {
+    const calls = [];
     walkNodes(stmt, (n) => {
-      if (n.type === "CallExpression" && isTimelineRooted(n, ctx.timelineVar)) {
-        tagProvenance(n, { ...prov });
-        n.__hfOrder = ctx.order.n++;
-      }
+      if (n.type === "CallExpression" && (isTimelineRooted(n, ctx.timelineVar) || isAddLabelCall(n, ctx.timelineVar)))
+        calls.push(n);
     });
+    calls.sort((a, b) => a.callee.property.start - b.callee.property.start);
+    for (const n of calls) {
+      tagProvenance(n, { ...prov });
+      n.__hfOrder = ctx.order.n++;
+      n.__hfSiteStart = ctx.rootStart;
+    }
   }
 }
 function expandBody(bodyStmts, bindings, prov, ctx) {
@@ -995,10 +1012,14 @@ function inlineComputedTimelines(ast, timelineVar, resolve) {
     resolve,
     depth: 0,
     site: { n: 0 },
-    order: { n: 0 }
+    order: { n: 0 },
+    rootStart: 0
   };
   const body = (ast.body ?? []).filter((stmt) => !isHelperDecl(stmt, helpers));
-  ast.body = expandStatements(body, ctx);
+  ast.body = body.flatMap((stmt) => {
+    ctx.rootStart = stmt.start;
+    return expandStatements([stmt], ctx);
+  });
 }
 
 // src/gsapParserAcorn.ts
@@ -1416,6 +1437,14 @@ function objectExpressionToRecord(node, scope, source) {
 function isGsapTimelineCall(node) {
   return node?.type === "CallExpression" && node.callee?.type === "MemberExpression" && node.callee.object?.name === "gsap" && node.callee.property?.name === "timeline";
 }
+function hasUnknownDuration(varsNode, scope) {
+  if (!varsNode) return false;
+  if (varsNode.type !== "ObjectExpression") return true;
+  const props = varsNode.properties ?? [];
+  if (props.some((p) => p.type === "SpreadElement")) return true;
+  const prop = props.find((p) => isObjectProperty(p) && propKeyName(p) === "duration");
+  return prop !== void 0 && typeof resolveNode(prop.value, scope) !== "number";
+}
 function staticMemberKey(node) {
   if (!node || node.type !== "MemberExpression") return null;
   if (node.computed) {
@@ -1457,7 +1486,10 @@ function extractTimelineDefaults(callNode, scope) {
     const key = propKeyName(prop);
     const val = resolveNode(prop.value, scope);
     if (key === "ease" && typeof val === "string") result.ease = val;
-    if (key === "duration" && typeof val === "number") result.duration = val;
+    if (key === "duration") {
+      if (typeof val === "number") result.duration = val;
+      else result.durationUnresolved = true;
+    }
   }
   return Object.keys(result).length > 0 ? result : void 0;
 }
@@ -1832,6 +1864,7 @@ function tweenCallToAnimation(call, scope, source, identifierBindings) {
   if (duration === void 0 && keyframesData) {
     duration = computeKeyframesTotalDuration(call.varsArg, scope, source);
   }
+  const durationUnresolved = call.method !== "set" && duration === void 0 && hasUnknownDuration(call.varsArg, scope);
   let selector = call.selector;
   let targetIdentity;
   if (selector === "__unresolved__") {
@@ -1879,6 +1912,7 @@ function tweenCallToAnimation(call, scope, source, identifierBindings) {
   if (keyframesData) anim.keyframes = keyframesData;
   if (motionPathResult) anim.arcPath = motionPathResult.arcPath;
   if (hasUnresolvedKeyframes) anim.hasUnresolvedKeyframes = true;
+  if (durationUnresolved) anim.durationUnresolved = true;
   if (selector === "__unresolved__") anim.hasUnresolvedSelector = true;
   if (provenance) anim.provenance = provenance;
   return anim;
@@ -2002,8 +2036,9 @@ function applyTimelineDefaults(anims, defaults) {
   if (!defaults) return;
   for (const anim of anims) {
     if (anim.method === "set") continue;
-    if (anim.duration === void 0 && defaults.duration !== void 0) {
-      anim.duration = defaults.duration;
+    if (anim.duration === void 0 && !anim.durationUnresolved) {
+      if (defaults.duration !== void 0) anim.duration = defaults.duration;
+      else if (defaults.durationUnresolved) anim.durationUnresolved = true;
     }
     if (anim.ease === void 0 && defaults.ease !== void 0) {
       anim.ease = defaults.ease;
@@ -2036,12 +2071,14 @@ function resolveAnimStart(anim, cursor, prevStart, labels) {
 function resolveTimelinePositions(anims, labelDefs = []) {
   let cursor = 0;
   let prevStart = 0;
+  let cursorKnown = true;
   const labels = /* @__PURE__ */ new Map();
   let labelIdx = 0;
   const sortedLabels = [...labelDefs].sort((a, b) => a.order - b.order);
   const defineLabel = (def) => {
     let value;
     if (typeof def.position === "number") value = def.position;
+    else if (!cursorKnown) return;
     else if (typeof def.position === "string") {
       value = resolveLabelPosition(def.position, labels, cursor) ?? cursor;
     } else value = cursor;
@@ -2057,7 +2094,9 @@ function resolveTimelinePositions(anims, labelDefs = []) {
       return;
     }
     const duration = anim.method === "set" ? 0 : anim.duration ?? GSAP_DEFAULT_DURATION;
-    const start = resolveAnimStart(anim, cursor, prevStart, labels);
+    const readsCursor = anim.implicitPosition || typeof anim.position !== "number";
+    const start = cursorKnown || !readsCursor ? resolveAnimStart(anim, cursor, prevStart, labels) : null;
+    if (start == null || anim.durationUnresolved) cursorKnown = false;
     if (start != null) {
       anim.resolvedStart = Math.max(0, start);
       prevStart = anim.resolvedStart;
@@ -2067,7 +2106,15 @@ function resolveTimelinePositions(anims, labelDefs = []) {
   while (labelIdx < sortedLabels.length) defineLabel(sortedLabels[labelIdx++]);
 }
 function collectAddLabelDefs(ast, ref, scope, sortedCalls) {
-  const callLocs = sortedCalls.map((c) => c.node.callee?.property?.loc?.start);
+  const callKeys = sortedCalls.map((c) => ({
+    site: callSiteStart(c),
+    order: c.node.__hfOrder
+  }));
+  const comesAfter = (site, order, labelSite, labelOrder) => {
+    if (site === void 0) return false;
+    if (site !== labelSite) return site > labelSite;
+    return (order ?? -Infinity) > (labelOrder ?? -Infinity);
+  };
   const defs = [];
   acornWalk.simple(ast, {
     // fallow-ignore-next-line complexity
@@ -2081,12 +2128,11 @@ function collectAddLabelDefs(ast, ref, scope, sortedCalls) {
       if (!name) return;
       const posVal = resolveNode(node.arguments?.[1], scope);
       const position = typeof posVal === "number" || typeof posVal === "string" ? posVal : void 0;
-      const labelLoc = callee.property?.loc?.start;
+      const labelStart = node.__hfSiteStart ?? callee.property?.start;
+      const labelOrder = node.__hfOrder;
       let order = sortedCalls.length;
-      if (labelLoc) {
-        order = callLocs.findIndex(
-          (l) => l && (l.line > labelLoc.line || l.line === labelLoc.line && l.column > labelLoc.column)
-        );
+      if (labelStart !== void 0) {
+        order = callKeys.findIndex((k) => comesAfter(k.site, k.order, labelStart, labelOrder));
         if (order === -1) order = sortedCalls.length;
       }
       defs.push({ name, position, order });
@@ -2100,13 +2146,17 @@ function compareByLoc(a, b) {
   if (!aLoc || !bLoc) return 0;
   return aLoc.line - bLoc.line || aLoc.column - bLoc.column;
 }
+function callSiteStart(call) {
+  return call.node.__hfSiteStart ?? call.node.callee?.property?.start;
+}
 function compareCallOrder(a, b) {
+  const aSite = callSiteStart(a);
+  const bSite = callSiteStart(b);
+  if (aSite !== void 0 && bSite !== void 0 && aSite !== bSite) return aSite - bSite;
   const ao = a.node.__hfOrder;
   const bo = b.node.__hfOrder;
-  if (ao === void 0 && bo === void 0) return compareByLoc(a, b);
-  if (ao === void 0) return -1;
-  if (bo === void 0) return 1;
-  return ao - bo;
+  if (ao !== void 0 && bo !== void 0) return ao - bo;
+  return compareByLoc(a, b);
 }
 function sortBySourcePosition(calls) {
   calls.sort(compareCallOrder);
@@ -3428,6 +3478,7 @@ function checkOutputResolutionCompatibility(input) {
 
 // src/gsapUnroll.ts
 import * as acorn2 from "acorn";
+import * as acornWalk3 from "acorn-walk";
 import MagicString2 from "magic-string";
 function propEntries(props) {
   return Object.entries(props).map(([k, v]) => `${safeJsKey(k)}: ${serializeValue(v)}`);
@@ -3486,37 +3537,140 @@ function enclosingTopLevel(statements, start, end) {
   }
   return null;
 }
-function isHelperDeclNamed(stmt, names) {
-  if (stmt.type === "FunctionDeclaration") return names.has(stmt.id?.name);
-  if (stmt.type === "VariableDeclaration") {
-    return (stmt.declarations ?? []).some((d) => names.has(d.id?.name));
+function declaresFunction(stmt) {
+  if (stmt.type === "FunctionDeclaration") return true;
+  return stmt.type === "VariableDeclaration" && (stmt.declarations ?? []).some((d) => isFunctionNode(d.init));
+}
+function declaredNames(stmt) {
+  if (stmt.type === "FunctionDeclaration") return stmt.id?.name ? [stmt.id.name] : [];
+  if (stmt.type !== "VariableDeclaration") return [];
+  return (stmt.declarations ?? []).flatMap((d) => d.id?.name ? [d.id.name] : []);
+}
+function mentionsIdentifier(text, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?<![\\p{ID_Continue}$])${escaped}(?![\\p{ID_Continue}$])`, "u").test(text);
+}
+function unreferencedHelperDecls(statements, script, unrolled, helperNames) {
+  let live = statements.filter((stmt) => !unrolled.has(stmt));
+  const dead = [];
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const decl of live) {
+      const names = declaredNames(decl);
+      if (names.length === 0 || !names.every((n) => helperNames.has(n))) continue;
+      const others = live.filter((s) => s !== decl).map((s) => script.slice(s.start, s.end));
+      if (names.some((n) => others.some((text) => mentionsIdentifier(text, n)))) continue;
+      dead.push(decl);
+      live = live.filter((s) => s !== decl);
+      changed = true;
+    }
   }
-  return false;
+  return dead;
 }
-function unrollComputedTimeline(script) {
-  const parsed = parseGsapScriptAcorn(script);
-  const computed = parsed.animations.filter((a) => isComputed(a) && a.provenance?.sourceRange);
-  if (computed.length === 0) return script;
-  const statements = topLevelStatements(script);
+var EFFECT_NODES = /* @__PURE__ */ new Set([
+  "CallExpression",
+  "NewExpression",
+  "UpdateExpression",
+  "AssignmentExpression"
+]);
+function containsEffect(node) {
+  let hit = false;
+  acornWalk3.full(node, (n) => {
+    if (EFFECT_NODES.has(n.type)) hit = true;
+  });
+  return hit;
+}
+function isPureTweenChain(expr, timelineVar) {
+  let node = expr;
+  while (node?.type === "CallExpression") {
+    if (!isTimelineRooted(node, timelineVar) || node.arguments.some(containsEffect)) return false;
+    node = node.callee?.object;
+  }
+  return node?.type === "Identifier";
+}
+var blockStatements = (block) => block?.type === "BlockStatement" ? block.body : block ? [block] : [];
+function forEachBody(call) {
+  const callback = call.callee?.property?.name === "forEach" ? call.arguments[0] : null;
+  return callback?.body ? blockStatements(callback.body) : null;
+}
+function calledBody(call, helpers) {
+  if (call?.type !== "CallExpression") return null;
+  if (call.callee?.type !== "Identifier") return forEachBody(call);
+  return helpers.get(call.callee.name) ?? null;
+}
+function bodyOf(stmt, helpers) {
+  if (stmt.type === "ExpressionStatement") return calledBody(stmt.expression, helpers);
+  return stmt.body ? blockStatements(stmt.body) : null;
+}
+function onlyAddsTweens(stmts, ctx, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(stmts)) return false;
+  seen.add(stmts);
+  return stmts.every((stmt) => {
+    if (stmt.type === "VariableDeclaration") return !containsEffect(stmt);
+    if (stmt.type === "ExpressionStatement" && isPureTweenChain(stmt.expression, ctx.timelineVar)) {
+      return true;
+    }
+    const nested = bodyOf(stmt, ctx.helpers);
+    return nested !== null && onlyAddsTweens(nested, ctx, seen);
+  });
+}
+function declaredFunctions(stmt) {
+  if (stmt.type === "FunctionDeclaration") {
+    return stmt.id?.name ? [[stmt.id.name, blockStatements(stmt.body)]] : [];
+  }
+  if (stmt.type !== "VariableDeclaration") return [];
+  return stmt.declarations.filter((d) => d.id?.name && isFunctionNode(d.init)).map((d) => [d.id.name, blockStatements(d.init.body)]);
+}
+var collectHelperBodies = (statements) => new Map(statements.flatMap(declaredFunctions));
+function dropStatementsUnsafeToUnroll(byStatement, ctx) {
+  for (const [stmt, anims] of byStatement) {
+    const unknownTiming = anims.some(
+      (a) => a.durationUnresolved || a.resolvedStart === void 0 || a.hasUnresolvedSelector
+    );
+    const bodyStmts = unknownTiming ? null : bodyOf(stmt, ctx.helpers);
+    if (bodyStmts === null || !onlyAddsTweens(bodyStmts, ctx)) byStatement.delete(stmt);
+  }
+}
+function groupByTopLevelStatement(computed, statements) {
   const byStatement = /* @__PURE__ */ new Map();
   const helperNames = /* @__PURE__ */ new Set();
   for (const anim of computed) {
-    if (anim.provenance?.fn) helperNames.add(anim.provenance.fn);
     const [s, e] = anim.provenance.sourceRange;
     const stmt = enclosingTopLevel(statements, s, e);
+    if (stmt && declaresFunction(stmt)) return null;
     if (!stmt) continue;
+    if (anim.provenance?.fn) helperNames.add(anim.provenance.fn);
     const list = byStatement.get(stmt) ?? [];
     list.push(anim);
     byStatement.set(stmt, list);
   }
+  return { byStatement, helperNames };
+}
+function unrollComputedTimeline(script) {
+  const parsed = parseGsapScriptAcorn(script);
+  const computed = parsed.animations.filter((a) => isComputed(a) && a.provenance?.sourceRange);
+  if (computed.length === 0) return script;
+  const statements = topLevelStatements(script);
+  const grouped = groupByTopLevelStatement(computed, statements);
+  if (!grouped) return script;
+  const { byStatement, helperNames } = grouped;
+  dropStatementsUnsafeToUnroll(byStatement, {
+    timelineVar: parsed.timelineVar,
+    helpers: collectHelperBodies(statements)
+  });
   if (byStatement.size === 0) return script;
   const ms = new MagicString2(script);
   for (const [stmt, anims] of byStatement) {
     const literals = anims.map((a) => serializeTweenStatement(parsed.timelineVar, a)).join("\n");
     ms.overwrite(stmt.start, stmt.end, literals);
   }
-  for (const stmt of statements) {
-    if (isHelperDeclNamed(stmt, helperNames)) ms.remove(stmt.start, stmt.end);
+  for (const decl of unreferencedHelperDecls(
+    statements,
+    script,
+    new Set(byStatement.keys()),
+    helperNames
+  )) {
+    ms.remove(decl.start, decl.end);
   }
   return ms.toString();
 }
@@ -3560,6 +3714,201 @@ function trackKindOf(node) {
   return { kind: "graphics", source: "tag" };
 }
 
+// src/timingMismatches.ts
+import { parseHTML as parseHTML2 } from "linkedom";
+var EPSILON = 0.05;
+var NON_RENDERED = /* @__PURE__ */ new Set(["script", "style", "template", "noscript", "link", "meta"]);
+var toNode = (el) => ({
+  tag: el.tagName,
+  attrs: Object.fromEntries(Array.from(el.attributes, (a) => [a.name, a.value])),
+  children: Array.from(el.children, toNode),
+  el
+});
+var numeric = (value) => {
+  if (value == null || value.trim() === "") return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+};
+function queryAll(root, selector) {
+  try {
+    return Array.from(root.querySelectorAll(selector));
+  } catch {
+    return [];
+  }
+}
+var unresolvedReason = (anim) => {
+  if (anim.durationUnresolved) return "duration";
+  if (anim.resolvedStart === void 0) return "position";
+  return anim.extras?.stagger === void 0 ? null : "stagger";
+};
+function rowMembership(root) {
+  const rows = topLevelElements(toNode(root));
+  const rowEls = new Set(rows.map((r) => r.el));
+  const insideRow = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    insideRow.add(row.el);
+    for (const d of Array.from(row.el.querySelectorAll("*"))) insideRow.add(d);
+  }
+  return { rowEls, insideRow };
+}
+var attrNumber = (el, name) => numeric(el.getAttribute(name));
+function windowFinding(el, selector, anim, start, end) {
+  const dataStart = attrNumber(el, "data-start");
+  const duration = attrNumber(el, "data-duration");
+  if (dataStart === null) return null;
+  const dataEnd = duration === null ? null : dataStart + duration;
+  const beforeStart = anim.method !== "set" && start < dataStart - EPSILON;
+  const afterEnd = dataEnd !== null && start > dataEnd + EPSILON;
+  if (!beforeStart && !afterEnd) return null;
+  const elementId = el.getAttribute("id");
+  return {
+    kind: "tween-outside-window",
+    selector,
+    elementId,
+    dataStart,
+    dataEnd,
+    tweenStart: start,
+    tweenEnd: end
+  };
+}
+var tweenEnd = (anim) => anim.resolvedStart + (anim.method === "set" ? 0 : anim.duration ?? 0.5);
+function checkTarget(el, selector, anim, layout, report) {
+  if (!layout.insideRow.has(el)) {
+    if (!NON_RENDERED.has(el.tagName.toLowerCase())) {
+      report.findings.push({
+        kind: "animated-without-timing",
+        selector,
+        elementId: el.getAttribute("id")
+      });
+    }
+    return;
+  }
+  if (!layout.rowEls.has(el) || isSubCompositionHost(toNode(el))) return;
+  if (el.hasAttribute("data-start") && attrNumber(el, "data-start") === null) {
+    report.unresolved.push({ selector, reason: "start-attribute" });
+    return;
+  }
+  const found = windowFinding(el, selector, anim, anim.resolvedStart, tweenEnd(anim));
+  if (found) report.findings.push(found);
+}
+function checkTween(anim, root, layout, seenUntimed, report) {
+  const selector = anim.targetSelector;
+  const targets = queryAll(root, selector).filter((el) => el !== root);
+  const reason = unresolvedReason(anim);
+  if (reason) {
+    if (targets.length > 0) report.unresolved.push({ selector, reason });
+    return null;
+  }
+  for (const el of targets) {
+    const loose = !layout.insideRow.has(el);
+    if (loose && seenUntimed.has(el)) continue;
+    if (loose) seenUntimed.add(el);
+    checkTarget(el, selector, anim, layout, report);
+  }
+  return tweenEnd(anim);
+}
+function timingMismatches(html) {
+  const report = { findings: [], unresolved: [] };
+  const { document } = parseHTML2(html);
+  const root = document.querySelector("[data-composition-id]");
+  if (!root) return report;
+  const layout = rowMembership(root);
+  const seenUntimed = /* @__PURE__ */ new Set();
+  const scripts = Array.from(document.querySelectorAll("script:not([src])"));
+  const anims = scripts.flatMap((s) => parseGsapScriptAcorn(s.textContent ?? "").animations);
+  const ends = anims.filter((anim) => !anim.global && !anim.hasUnresolvedSelector).map((anim) => checkTween(anim, root, layout, seenUntimed, report));
+  const timelineEnd = Math.max(0, ...ends.filter((e) => e !== null));
+  const rootDuration = attrNumber(root, "data-duration");
+  if (rootDuration !== null && timelineEnd > rootDuration + EPSILON) {
+    report.findings.push({ kind: "timeline-exceeds-root-duration", rootDuration, timelineEnd });
+  }
+  return report;
+}
+
+// src/mediaDuration.ts
+var nonNegative = (raw) => {
+  const value = parseNumeric(raw);
+  return value !== null && value >= 0 ? value : null;
+};
+function readMediaOffsetSeconds(getAttr) {
+  return nonNegative(getAttr("data-playback-start")) ?? nonNegative(getAttr("data-media-start")) ?? 0;
+}
+var MIN_PLAYBACK_RATE = 0.1;
+var MAX_PLAYBACK_RATE = 10;
+function clampPlaybackRate(raw) {
+  return Number.isFinite(raw) && raw > 0 ? Math.max(MIN_PLAYBACK_RATE, Math.min(MAX_PLAYBACK_RATE, raw)) : 1;
+}
+function readPlaybackRate(getAttr, fallback = 1) {
+  const authored = Number.parseFloat(getAttr("data-playback-rate") ?? "");
+  return clampPlaybackRate(Number.isFinite(authored) && authored > 0 ? authored : fallback);
+}
+function readDataDurationSeconds(getAttr) {
+  const duration = parseNumeric(getAttr("data-duration"));
+  return duration !== null && duration > 0 ? duration : null;
+}
+function readAuthoredDurationSeconds(getAttr, startSeconds) {
+  const duration = readDataDurationSeconds(getAttr);
+  if (duration !== null) return duration;
+  const end = parseNumeric(getAttr("data-end"));
+  return end !== null ? end - startSeconds : null;
+}
+var DEFAULT_IMAGE_TIMELINE_DURATION_SECONDS = 3;
+function resolveNaturalDurationSeconds(sourceDurationSeconds, mediaStartSeconds, playbackRate) {
+  if (!Number.isFinite(sourceDurationSeconds)) return null;
+  const remaining = Math.max(0, sourceDurationSeconds - mediaStartSeconds);
+  return remaining / clampPlaybackRate(playbackRate);
+}
+function resolveMediaDuration(input) {
+  const { tag, authoredDurationSeconds, sourceDurationSeconds, mediaStartSeconds, playbackRate } = input;
+  if (authoredDurationSeconds !== null && authoredDurationSeconds > 0) {
+    return { seconds: authoredDurationSeconds, source: "authored" };
+  }
+  if (tag === "img") {
+    return { seconds: DEFAULT_IMAGE_TIMELINE_DURATION_SECONDS, source: "default" };
+  }
+  if (sourceDurationSeconds === null) {
+    return { seconds: null, source: "pending", reason: "source duration not yet probed" };
+  }
+  const seconds = resolveNaturalDurationSeconds(
+    sourceDurationSeconds,
+    mediaStartSeconds,
+    playbackRate
+  );
+  if (seconds === null) {
+    return { seconds: null, source: "pending", reason: "source reported a non-finite duration" };
+  }
+  return { seconds, source: "media" };
+}
+var PENDING_MEDIA_DURATION_READERS = [
+  "core/src/runtime/init.ts (visibility end, clock, seek, WebAudio scheduling)",
+  "core/src/compiler/timingCompiler.ts compileTag",
+  "core/src/compiler/htmlCompiler.ts compileHtml",
+  "producer/src/services/htmlCompiler.ts resolveMediaDuration",
+  "engine/src/services/videoFrameExtractor.ts (extraction window)",
+  "engine/src/services/audioMixer.ts",
+  "parsers/src/htmlParser.ts (defaults to 5s, reads only data-media-start)",
+  "studio (timelineDOM.ts, timelineElementHelpers.ts, useTimelineSyncCallbacks.ts)"
+];
+
+// src/compositionDuration.ts
+var isPositiveFinite = (value) => value !== null && Number.isFinite(value) && value > 0;
+function resolveCompositionDuration(input) {
+  const pendingClips = input.clipEndsSeconds.filter((end) => end === null).length;
+  if (isPositiveFinite(input.authoredDurationSeconds)) {
+    return { seconds: input.authoredDurationSeconds, source: "authored", pendingClips };
+  }
+  const known = input.clipEndsSeconds.filter(isPositiveFinite);
+  if (known.length > 0) {
+    return { seconds: Math.max(...known), source: "derived", pendingClips };
+  }
+  return {
+    seconds: null,
+    source: "unresolved",
+    pendingClips,
+    reason: pendingClips > 0 ? "every clip's length is still pending" : "no authored duration and no clip with a length"
+  };
+}
+
 // src/utils/urlPath.ts
 function decodeUrlPathVariants(path) {
   const variants = [path];
@@ -3573,7 +3922,7 @@ function decodeUrlPathVariants(path) {
 
 // src/variableUsage.ts
 import * as acorn3 from "acorn";
-import * as acornWalk3 from "acorn-walk";
+import * as acornWalk4 from "acorn-walk";
 function isGetVariablesCallee(callee) {
   if (callee?.type === "Identifier") return callee.name === "getVariables";
   if (callee?.type === "MemberExpression" && !callee.computed) {
@@ -3650,7 +3999,7 @@ function scanVariableUsage(scriptText) {
     return { usedIds: [], scanIncomplete: true };
   }
   const aliases = /* @__PURE__ */ new Set();
-  acornWalk3.ancestor(ast, {
+  acornWalk4.ancestor(ast, {
     CallExpression(node, _, ancestors) {
       if (!isGetVariablesCallee(node.callee)) return;
       const parent = ancestors[ancestors.length - 2];
@@ -3659,7 +4008,7 @@ function scanVariableUsage(scriptText) {
     }
   });
   if (aliases.size > 0) {
-    acornWalk3.ancestor(ast, {
+    acornWalk4.ancestor(ast, {
       // fallow-ignore-next-line complexity
       Identifier(node, _, ancestors) {
         if (!aliases.has(String(node.name))) return;
@@ -3677,7 +4026,7 @@ function scanVariableUsage(scriptText) {
 
 // src/mediaSrcMutation.ts
 import * as acorn4 from "acorn";
-import * as acornWalk4 from "acorn-walk";
+import * as acornWalk5 from "acorn-walk";
 function parseProgram2(script) {
   try {
     return acorn4.parse(script, { ecmaVersion: "latest", sourceType: "script" });
@@ -3712,7 +4061,7 @@ function extractMediaSrcMutations(script) {
   try {
     const ast = parseProgram2(script);
     const bindings = /* @__PURE__ */ new Map();
-    acornWalk4.simple(ast, {
+    acornWalk5.simple(ast, {
       VariableDeclarator(node) {
         if (node.id?.type !== "Identifier") return;
         const selector = lookupSelector(node.init, bindings);
@@ -3720,7 +4069,7 @@ function extractMediaSrcMutations(script) {
       }
     });
     const mutations = [];
-    acornWalk4.simple(ast, {
+    acornWalk5.simple(ast, {
       AssignmentExpression(node) {
         if (node.operator !== "=" || memberName(node.left) !== "src") return;
         const selector = lookupSelector(node.left.object, bindings);
@@ -3864,6 +4213,7 @@ export {
   ClipTimingWriteError,
   CompositionHtmlParseError,
   DEFAULT_DURATIONS,
+  DEFAULT_IMAGE_TIMELINE_DURATION_SECONDS,
   DERIVED_TIMING_ATTRIBUTES,
   EXCLUDED_TAGS,
   FONT_ALIAS_KEYS,
@@ -3871,6 +4221,9 @@ export {
   HTML_BODY_CSS_HEIGHT_FIRST_RE,
   HTML_BODY_CSS_WIDTH_FIRST_RE,
   LEGACY_TIMING_ATTRIBUTES,
+  MAX_PLAYBACK_RATE,
+  MIN_PLAYBACK_RATE,
+  PENDING_MEDIA_DURATION_READERS,
   PROPERTY_GROUPS,
   SPRING_PRESETS,
   SUPPORTED_EASES,
@@ -3881,6 +4234,7 @@ export {
   addElementToHtml,
   checkOutputResolutionCompatibility,
   checkSubCompositionUsability,
+  clampPlaybackRate,
   classifyPropertyGroup,
   classifyTweenPropertyGroup,
   decodeUrlPathVariants,
@@ -3909,14 +4263,22 @@ export {
   parseNumeric,
   parseStartExpression,
   queryByAttr,
+  readAuthoredDurationSeconds,
   readClipTiming,
+  readDataDurationSeconds,
+  readMediaOffsetSeconds,
+  readPlaybackRate,
   removeElementFromHtml,
   removeElementWithGsapCascade,
   resolveAliasDisplayName,
+  resolveCompositionDuration,
+  resolveMediaDuration,
+  resolveNaturalDurationSeconds,
   resolveResolutionFlagPair,
   scanVariableUsage,
   serializeGsapAnimations,
   suggestMatchingPreset,
+  timingMismatches,
   topLevelElements,
   trackKindOf,
   unrollComputedTimeline,