@hyperframes/parsers 0.7.59 → 0.7.61

package/dist/index.js

@@ -22,6 +22,12 @@ var RESOLUTION_ALIASES = {
   "square-1080p": "square",
   "4k-square": "square-4k"
 };
+var ASPECT_AGNOSTIC_RESOLUTION_ALIASES = /* @__PURE__ */ new Set([
+  "1080p",
+  "hd",
+  "4k",
+  "uhd"
+]);
 function normalizeResolutionFlag(input) {
   if (!input) return void 0;
   const lowered = input.toLowerCase();
@@ -30,6 +36,16 @@ function normalizeResolutionFlag(input) {
   }
   return RESOLUTION_ALIASES[lowered];
 }
+function isAspectAgnosticResolutionAlias(input) {
+  if (!input) return false;
+  return ASPECT_AGNOSTIC_RESOLUTION_ALIASES.has(input.toLowerCase());
+}
+function resolveResolutionFlagPair(input) {
+  return {
+    outputResolution: normalizeResolutionFlag(input),
+    outputResolutionAspectAgnostic: isAspectAgnosticResolutionAlias(input)
+  };
+}
 var COMPOSITION_VARIABLE_TYPES = [
   "string",
   "number",
@@ -2232,6 +2248,276 @@ function removeAnimationFromScript(script, animationId) {
   return ms.toString();
 }
 
+// src/compositionContract.ts
+var COMPOSITION_CONTRACT_VERSION = 1;
+var COMPOSITION_ATTRIBUTES = Object.freeze({
+  start: "data-start",
+  duration: "data-duration",
+  trackIndex: "data-track-index",
+  derivedEnd: "data-end",
+  legacyTrack: "data-layer"
+});
+var CANONICAL_AUTHORED_TIMING_ATTRIBUTES = Object.freeze([
+  COMPOSITION_ATTRIBUTES.start,
+  COMPOSITION_ATTRIBUTES.duration,
+  COMPOSITION_ATTRIBUTES.trackIndex
+]);
+var DERIVED_TIMING_ATTRIBUTES = Object.freeze([
+  COMPOSITION_ATTRIBUTES.derivedEnd
+]);
+var LEGACY_TIMING_ATTRIBUTES = Object.freeze([
+  COMPOSITION_ATTRIBUTES.derivedEnd,
+  COMPOSITION_ATTRIBUTES.legacyTrack
+]);
+var ClipTimingWriteError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ClipTimingWriteError";
+    this.code = code;
+  }
+};
+function parseNumeric(value) {
+  if (value == null || value.trim() === "") return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+var REFERENCE_ID_PATTERN = /^[A-Za-z0-9_.:-]+$/;
+function isAsciiDigitAt(value, index) {
+  const code = value.charCodeAt(index);
+  return code >= 48 && code <= 57;
+}
+function skipDigitsLeft(value, start) {
+  let cursor = start;
+  while (cursor >= 0 && isAsciiDigitAt(value, cursor)) cursor--;
+  return cursor;
+}
+function skipWhitespaceLeft(value, start) {
+  let cursor = start;
+  while (cursor >= 0 && (value[cursor] ?? "").trim() === "") cursor--;
+  return cursor;
+}
+function findMagnitudeStart(value) {
+  const last = value.length - 1;
+  if (!isAsciiDigitAt(value, last)) return null;
+  let cursor = skipDigitsLeft(value, last);
+  if (value[cursor] === ".") cursor = skipDigitsLeft(value, cursor - 1);
+  return cursor + 1;
+}
+function parseReferenceOffset(value) {
+  const magnitudeStart = findMagnitudeStart(value);
+  if (magnitudeStart == null) return null;
+  const operatorIndex = skipWhitespaceLeft(value, magnitudeStart - 1);
+  const operator = value[operatorIndex];
+  if (operator !== "+" && operator !== "-") return null;
+  const refId = value.slice(0, operatorIndex).trim();
+  if (!REFERENCE_ID_PATTERN.test(refId)) return null;
+  const magnitude = Number(value.slice(magnitudeStart));
+  if (!Number.isFinite(magnitude)) return null;
+  return { refId, operator, magnitude };
+}
+function parseStartExpression(raw) {
+  const normalized = (raw ?? "").trim();
+  if (!normalized) return null;
+  const absolute = parseNumeric(normalized);
+  if (absolute != null) return { kind: "absolute", value: absolute };
+  if (REFERENCE_ID_PATTERN.test(normalized)) {
+    return { kind: "reference", refId: normalized, offset: 0 };
+  }
+  const reference = parseReferenceOffset(normalized);
+  if (!reference) return null;
+  return {
+    kind: "reference",
+    refId: reference.refId,
+    offset: reference.operator === "-" ? -reference.magnitude : reference.magnitude
+  };
+}
+function pushDiagnostic(diagnostics, code, attribute, value) {
+  diagnostics.push({ code, attribute, value });
+}
+function resolveStart(expression, rawStart, options, diagnostics) {
+  if (rawStart == null || rawStart.trim() === "") {
+    return options.defaultStart === void 0 ? 0 : options.defaultStart;
+  }
+  if (!expression) {
+    pushDiagnostic(diagnostics, "invalid-start", COMPOSITION_ATTRIBUTES.start, rawStart);
+    return null;
+  }
+  if (expression.kind === "absolute") return Math.max(0, expression.value);
+  const referencedEnd = options.resolveReferenceEnd?.(expression.refId);
+  if (referencedEnd == null || !Number.isFinite(referencedEnd)) {
+    pushDiagnostic(
+      diagnostics,
+      "unresolved-start-reference",
+      COMPOSITION_ATTRIBUTES.start,
+      rawStart
+    );
+    return null;
+  }
+  return Math.max(0, referencedEnd + expression.offset);
+}
+function diagnoseDerivedEnd(rawEnd, canonicalEnd, diagnostics) {
+  pushDiagnostic(diagnostics, "deprecated-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
+  const parsedEnd = parseNumeric(rawEnd);
+  if (parsedEnd == null) {
+    pushDiagnostic(diagnostics, "invalid-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
+  } else if (canonicalEnd != null && parsedEnd !== canonicalEnd) {
+    pushDiagnostic(diagnostics, "conflicting-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
+  }
+}
+function readCanonicalDuration(rawDuration, start, diagnostics) {
+  const duration = parseNumeric(rawDuration);
+  if (duration == null || duration < 0) {
+    pushDiagnostic(diagnostics, "invalid-duration", COMPOSITION_ATTRIBUTES.duration, rawDuration);
+    return { duration: null, end: null, durationSource: "invalid" };
+  }
+  return {
+    duration,
+    end: start == null ? null : start + duration,
+    durationSource: "duration"
+  };
+}
+function readLegacyEnd(rawEnd, start, diagnostics) {
+  pushDiagnostic(diagnostics, "deprecated-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
+  const end = parseNumeric(rawEnd);
+  if (end == null) {
+    pushDiagnostic(diagnostics, "invalid-end", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
+    return { duration: null, end: null, durationSource: "invalid" };
+  }
+  if (start == null) return { duration: null, end, durationSource: "legacy-end" };
+  if (end < start) {
+    pushDiagnostic(diagnostics, "end-before-start", COMPOSITION_ATTRIBUTES.derivedEnd, rawEnd);
+    return { duration: null, end: null, durationSource: "invalid" };
+  }
+  return { duration: end - start, end, durationSource: "legacy-end" };
+}
+function readDuration(attributes, start, diagnostics) {
+  const rawDuration = attributes.getAttribute(COMPOSITION_ATTRIBUTES.duration);
+  const rawEnd = attributes.getAttribute(COMPOSITION_ATTRIBUTES.derivedEnd);
+  if (rawDuration == null) {
+    return rawEnd == null ? { duration: null, end: null, durationSource: "missing" } : readLegacyEnd(rawEnd, start, diagnostics);
+  }
+  const canonical = readCanonicalDuration(rawDuration, start, diagnostics);
+  if (rawEnd != null) diagnoseDerivedEnd(rawEnd, canonical.end, diagnostics);
+  return canonical;
+}
+function readTrackValue(rawValue, attribute, source, diagnostics) {
+  const trackIndex = parseNumeric(rawValue);
+  if (trackIndex == null || !Number.isInteger(trackIndex)) {
+    pushDiagnostic(diagnostics, "invalid-track-index", attribute, rawValue);
+    return { trackIndex: 0, trackSource: "invalid" };
+  }
+  return { trackIndex, trackSource: source };
+}
+function readTrack(attributes, diagnostics) {
+  const rawTrack = attributes.getAttribute(COMPOSITION_ATTRIBUTES.trackIndex);
+  const rawLayer = attributes.getAttribute(COMPOSITION_ATTRIBUTES.legacyTrack);
+  if (rawTrack == null && rawLayer == null) return { trackIndex: 0, trackSource: "default" };
+  if (rawTrack == null && rawLayer != null) {
+    pushDiagnostic(diagnostics, "deprecated-layer", COMPOSITION_ATTRIBUTES.legacyTrack, rawLayer);
+    return readTrackValue(
+      rawLayer,
+      COMPOSITION_ATTRIBUTES.legacyTrack,
+      "legacy-layer",
+      diagnostics
+    );
+  }
+  const canonical = readTrackValue(
+    rawTrack ?? "",
+    COMPOSITION_ATTRIBUTES.trackIndex,
+    "track-index",
+    diagnostics
+  );
+  if (rawLayer == null) return canonical;
+  pushDiagnostic(diagnostics, "deprecated-layer", COMPOSITION_ATTRIBUTES.legacyTrack, rawLayer);
+  const parsedLayer = parseNumeric(rawLayer);
+  if (parsedLayer != null && parsedLayer !== canonical.trackIndex) {
+    pushDiagnostic(diagnostics, "conflicting-layer", COMPOSITION_ATTRIBUTES.legacyTrack, rawLayer);
+  }
+  return canonical;
+}
+function readClipTiming(attributes, options = {}) {
+  const diagnostics = [];
+  const rawStart = attributes.getAttribute(COMPOSITION_ATTRIBUTES.start);
+  const startExpression = parseStartExpression(rawStart);
+  const start = resolveStart(startExpression, rawStart, options, diagnostics);
+  const duration = readDuration(attributes, start, diagnostics);
+  const track = readTrack(attributes, diagnostics);
+  return { startExpression, start, ...duration, ...track, diagnostics };
+}
+function serializeStartNumber(start) {
+  if (!Number.isFinite(start)) {
+    throw new ClipTimingWriteError("invalid-start", "start must be finite");
+  }
+  return String(start);
+}
+function serializeStartReference(start) {
+  if (start.kind === "absolute") return serializeStartNumber(start.value);
+  if (!start.refId || !Number.isFinite(start.offset)) {
+    throw new ClipTimingWriteError(
+      "invalid-start",
+      "reference start must have an id and finite offset"
+    );
+  }
+  if (start.offset === 0) return start.refId;
+  return `${start.refId} ${start.offset < 0 ? "-" : "+"} ${Math.abs(start.offset)}`;
+}
+function serializeStart(start) {
+  if (typeof start === "number") return serializeStartNumber(start);
+  if (typeof start === "object" && start != null) return serializeStartReference(start);
+  if (typeof start === "string" && parseStartExpression(start)) return start.trim();
+  throw new ClipTimingWriteError("invalid-start", `invalid start expression: ${start ?? ""}`);
+}
+function writeDuration(attributes, duration, current) {
+  if (duration === null) {
+    attributes.removeAttribute(COMPOSITION_ATTRIBUTES.duration);
+    return;
+  }
+  if (duration === void 0) {
+    if (attributes.getAttribute(COMPOSITION_ATTRIBUTES.duration) == null && current.duration != null) {
+      attributes.setAttribute(COMPOSITION_ATTRIBUTES.duration, String(current.duration));
+    }
+    return;
+  }
+  if (!Number.isFinite(duration) || duration < 0) {
+    throw new ClipTimingWriteError(
+      "invalid-duration",
+      "duration must be a finite, non-negative number"
+    );
+  }
+  attributes.setAttribute(COMPOSITION_ATTRIBUTES.duration, String(duration));
+}
+function writeTrack(attributes, trackIndex, current) {
+  if (trackIndex === null) {
+    attributes.removeAttribute(COMPOSITION_ATTRIBUTES.trackIndex);
+    return;
+  }
+  if (trackIndex === void 0) {
+    if (attributes.getAttribute(COMPOSITION_ATTRIBUTES.trackIndex) == null && current.trackSource === "legacy-layer") {
+      attributes.setAttribute(COMPOSITION_ATTRIBUTES.trackIndex, String(current.trackIndex));
+    }
+    return;
+  }
+  if (!Number.isFinite(trackIndex) || !Number.isInteger(trackIndex)) {
+    throw new ClipTimingWriteError("invalid-track-index", "trackIndex must be a finite integer");
+  }
+  attributes.setAttribute(COMPOSITION_ATTRIBUTES.trackIndex, String(trackIndex));
+}
+function writeClipTiming(attributes, update) {
+  const current = readClipTiming(attributes);
+  if (update.start !== void 0) {
+    attributes.setAttribute(COMPOSITION_ATTRIBUTES.start, serializeStart(update.start));
+  }
+  writeDuration(attributes, update.duration, current);
+  writeTrack(attributes, update.trackIndex, current);
+  const preserveUnresolvedLegacyEnd = update.duration === void 0 && attributes.getAttribute(COMPOSITION_ATTRIBUTES.duration) == null && attributes.getAttribute(COMPOSITION_ATTRIBUTES.derivedEnd) != null && current.duration == null;
+  if (!preserveUnresolvedLegacyEnd) {
+    attributes.removeAttribute(COMPOSITION_ATTRIBUTES.derivedEnd);
+  }
+  attributes.removeAttribute(COMPOSITION_ATTRIBUTES.legacyTrack);
+  return readClipTiming(attributes);
+}
+
 // src/htmlParser.ts
 var MEDIA_TYPES = /* @__PURE__ */ new Set(["video", "image", "audio"]);
 var CompositionHtmlParseError = class extends Error {
@@ -2269,8 +2555,10 @@ function getElementName(el) {
   return el.id || el.className?.toString().split(" ")[0] || "Element";
 }
 function getZIndex(el) {
-  const dataLayer = el.getAttribute("data-layer");
-  if (dataLayer) return parseInt(dataLayer, 10) || 0;
+  const timing = readClipTiming(el);
+  if (timing.trackSource !== "default" && timing.trackSource !== "invalid") {
+    return timing.trackIndex;
+  }
   const style = el.style?.zIndex;
   if (style) return parseInt(style, 10) || 0;
   return 0;
@@ -2357,18 +2645,32 @@ function parseHtml(html) {
       customStyles = customStylesAttr;
     }
   }
-  const timedElements = doc.querySelectorAll("[data-start]");
+  const timedElements = Array.from(doc.querySelectorAll("[data-start]"));
+  const timedById = /* @__PURE__ */ new Map();
+  for (const element of timedElements) {
+    for (const id of [element.id, element.getAttribute("data-hf-id")]) {
+      if (id) timedById.set(id, element);
+    }
+  }
+  const resolveEnd = (refId, visiting) => {
+    if (visiting.has(refId)) return null;
+    const referenced = timedById.get(refId);
+    if (!referenced) return null;
+    const next = new Set(visiting);
+    next.add(refId);
+    return readClipTiming(referenced, {
+      resolveReferenceEnd: (nestedId) => resolveEnd(nestedId, next)
+    }).end;
+  };
   timedElements.forEach((el) => {
     const type = getElementType(el);
     if (!type) return;
-    const start = parseFloat(el.getAttribute("data-start") || "0");
-    const dataEnd = el.getAttribute("data-end");
-    let duration;
-    if (dataEnd) {
-      duration = Math.max(0, parseFloat(dataEnd) - start);
-    } else {
-      duration = 5;
-    }
+    const ownId = el.id || el.getAttribute("data-hf-id");
+    const timing = readClipTiming(el, {
+      resolveReferenceEnd: (refId) => resolveEnd(refId, new Set(ownId ? [ownId] : []))
+    });
+    const start = timing.start ?? 0;
+    const duration = timing.duration ?? 5;
     const id = el.getAttribute("data-hf-id") || el.id || `element-${++idCounter}`;
     const name = getElementName(el);
     const zIndex = getZIndex(el);
@@ -2605,23 +2907,16 @@ function updateElementInHtml(html, elementId, updates) {
   const doc = parser.parseFromString(html, "text/html");
   const el = doc.getElementById(elementId) || queryByAttr(doc, "data-name", elementId);
   if (!el) return html;
-  if (updates.startTime !== void 0) {
-    el.setAttribute("data-start", String(updates.startTime));
-    if (el.hasAttribute("data-end") && updates.duration !== void 0) {
-      el.setAttribute("data-end", String(updates.startTime + updates.duration));
-    }
-  }
-  if (updates.duration !== void 0) {
-    const start = parseFloat(el.getAttribute("data-start") || "0");
-    el.setAttribute("data-end", String(start + updates.duration));
-    el.removeAttribute("data-duration");
+  if (updates.startTime !== void 0 || updates.duration !== void 0 || updates.zIndex !== void 0) {
+    writeClipTiming(el, {
+      start: updates.startTime,
+      duration: updates.duration,
+      trackIndex: updates.zIndex
+    });
   }
   if (updates.name !== void 0) {
     el.setAttribute("data-name", updates.name);
   }
-  if (updates.zIndex !== void 0) {
-    el.setAttribute("data-layer", String(updates.zIndex));
-  }
   if ("src" in updates && updates.src !== void 0) {
     el.setAttribute("src", updates.src);
   }
@@ -2727,9 +3022,11 @@ function addElementToHtml(html, element) {
     }
   }
   newEl.id = id;
-  newEl.setAttribute("data-start", String(element.startTime));
-  newEl.setAttribute("data-end", String(element.startTime + element.duration));
-  newEl.setAttribute("data-layer", String(element.zIndex));
+  writeClipTiming(newEl, {
+    start: element.startTime,
+    duration: element.duration,
+    trackIndex: element.zIndex
+  });
   newEl.setAttribute("data-name", element.name);
   container.appendChild(newEl);
   return {
@@ -3293,14 +3590,20 @@ function resolveAliasDisplayName(alias) {
   return CANONICAL_FONT_DISPLAY_NAMES[slug];
 }
 export {
+  CANONICAL_AUTHORED_TIMING_ATTRIBUTES,
   CANONICAL_FONT_DISPLAY_NAMES,
   CANVAS_DIMENSIONS,
+  COMPOSITION_ATTRIBUTES,
+  COMPOSITION_CONTRACT_VERSION,
   COMPOSITION_VARIABLE_TYPES,
+  ClipTimingWriteError,
   CompositionHtmlParseError,
   DEFAULT_DURATIONS,
+  DERIVED_TIMING_ATTRIBUTES,
   EXCLUDED_TAGS,
   FONT_ALIAS_KEYS,
   FONT_ALIAS_MAP,
+  LEGACY_TIMING_ATTRIBUTES,
   PROPERTY_GROUPS,
   SPRING_PRESETS,
   SUPPORTED_EASES,
@@ -3320,6 +3623,7 @@ export {
   getAnimationsForElementId,
   getDefaultStageZoom,
   gsapAnimationsToKeyframes,
+  isAspectAgnosticResolutionAlias,
   isCompositionElement,
   isCompositionTemplate,
   isMediaElement,
@@ -3331,15 +3635,21 @@ export {
   parseCompositionVariables,
   parseGsapScriptAcorn as parseGsapScript,
   parseHtml,
+  parseNumeric,
+  parseStartExpression,
   queryByAttr,
+  readClipTiming,
   removeElementFromHtml,
   resolveAliasDisplayName,
+  resolveResolutionFlagPair,
   scanVariableUsage,
   serializeGsapAnimations,
+  suggestMatchingPreset,
   unrollComputedTimeline,
   updateElementInHtml,
   validateCompositionGsap,
   validateCompositionHtml,
-  walkCompositionDescendants
+  walkCompositionDescendants,
+  writeClipTiming
 };
 //# sourceMappingURL=index.js.map