@hyperframes/parsers 0.8.181 → 0.8.183

package/dist/mediaTiming.d.ts

@@ -0,0 +1,40 @@
+declare const MEDIA_START_BASIS_ATTR = "data-hf-media-start-basis";
+type MediaStartBasis = "local" | "global";
+declare function readMediaStartBasis(value: string | null | undefined): MediaStartBasis;
+declare function resolveAbsoluteMediaStartSeconds(input: {
+    authoredStart: number;
+    hostStart: number;
+    basis?: string | null;
+}): number;
+/** The one rule for a media element's root-timeline start; the runtime and the CLI both call it.
+ * `hostStart` is the composition's origin. With no literal start, an auto-injected start, or an
+ * origin at 0 there is nothing for the basis to disambiguate, so ordinary resolution applies. */
+declare function resolveMediaStartSeconds(input: MediaStartInput & {
+    ordinaryStart: () => number;
+}): number;
+/** True when the authored start is already root time, so no host offset applies. */
+declare function isRootGlobalMediaStart(input: MediaStartInput): boolean;
+interface MediaStartInput {
+    authoredStart: number | null;
+    hostStart: number;
+    hasAutoStart: boolean;
+    basis?: string | null;
+}
+/** A composition host's in-point; only a host with one shifts or cuts what it holds. */
+declare function hostInPointSeconds(host: Pick<Element, "getAttribute">): number;
+/** Main-timeline time of a sub-composition's local t=0: its host's start minus its in-point. */
+declare function compositionOriginSeconds(hostStart: number, host: Pick<Element, "getAttribute">): number;
+interface HostSlot {
+    start: number;
+    end: number;
+}
+/** Each in-point host cuts the span to its own window. */
+declare function cutToHostSlots(span: {
+    start: number;
+    end: number;
+}, hosts: readonly HostSlot[]): {
+    start: number;
+    end: number;
+};
+
+export { type HostSlot, MEDIA_START_BASIS_ATTR, type MediaStartBasis, type MediaStartInput, compositionOriginSeconds, cutToHostSlots, hostInPointSeconds, isRootGlobalMediaStart, readMediaStartBasis, resolveAbsoluteMediaStartSeconds, resolveMediaStartSeconds };

package/dist/mediaTiming.js

@@ -0,0 +1,79 @@
+// src/compositionContract.ts
+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
+]);
+function parseNumeric(value) {
+  if (value == null || value.trim() === "") return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+// 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;
+}
+
+// src/mediaTiming.ts
+var MEDIA_START_BASIS_ATTR = "data-hf-media-start-basis";
+function readMediaStartBasis(value) {
+  return value?.trim().toLowerCase() === "global" ? "global" : "local";
+}
+function resolveAbsoluteMediaStartSeconds(input) {
+  return readMediaStartBasis(input.basis) === "global" ? input.authoredStart : input.hostStart + input.authoredStart;
+}
+function resolveMediaStartSeconds(input) {
+  if (!hasLiteralNestedStart(input)) return input.ordinaryStart();
+  return resolveAbsoluteMediaStartSeconds({
+    authoredStart: input.authoredStart,
+    hostStart: input.hostStart,
+    basis: input.basis
+  });
+}
+function isRootGlobalMediaStart(input) {
+  return hasLiteralNestedStart(input) && readMediaStartBasis(input.basis) === "global";
+}
+function hasLiteralNestedStart(input) {
+  return !input.hasAutoStart && input.authoredStart != null && input.hostStart !== 0;
+}
+function hostInPointSeconds(host) {
+  return readMediaOffsetSeconds((name) => host.getAttribute(name));
+}
+function compositionOriginSeconds(hostStart, host) {
+  return hostStart - hostInPointSeconds(host);
+}
+function cutToHostSlots(span, hosts) {
+  return hosts.reduce((kept, host) => {
+    const start = Math.max(kept.start, host.start);
+    return { start, end: Math.max(start, Math.min(kept.end, host.end)) };
+  }, span);
+}
+export {
+  MEDIA_START_BASIS_ATTR,
+  compositionOriginSeconds,
+  cutToHostSlots,
+  hostInPointSeconds,
+  isRootGlobalMediaStart,
+  readMediaStartBasis,
+  resolveAbsoluteMediaStartSeconds,
+  resolveMediaStartSeconds
+};

package/dist/referenceResolver.d.ts

@@ -0,0 +1,13 @@
+/** Minimal structural DOM shape the reference resolver needs. */
+interface RefResolverEl {
+    getAttribute(name: string): string | null;
+}
+interface RefResolverDoc {
+    getElementById(id: string): RefResolverEl | null;
+    querySelector(selector: string): RefResolverEl | null;
+}
+declare function resolveReferencedStart(doc: RefResolverDoc, el: RefResolverEl, startCache: Map<RefResolverEl, number>, visiting: Set<RefResolverEl>): number;
+/** From `data-duration` or `data-end - start`; null when only the media's own length would settle it. */
+declare function resolveReferencedDuration(doc: RefResolverDoc, el: RefResolverEl, startCache: Map<RefResolverEl, number>, visiting: Set<RefResolverEl>): number | null;
+
+export { type RefResolverDoc, type RefResolverEl, resolveReferencedDuration, resolveReferencedStart };

package/dist/referenceResolver.js

@@ -0,0 +1,125 @@
+// src/compositionContract.ts
+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
+]);
+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
+  };
+}
+
+// src/referenceResolver.ts
+function findReferenceTargetEl(doc, refId) {
+  return doc.getElementById(refId) ?? doc.querySelector(`[data-composition-id="${refId}"]`);
+}
+function resolveReferencedStart(doc, el, startCache, visiting) {
+  const cached = startCache.get(el);
+  if (cached !== void 0) return cached;
+  if (visiting.has(el)) return 0;
+  visiting.add(el);
+  try {
+    const expression = parseStartExpression(el.getAttribute("data-start"));
+    if (!expression) {
+      startCache.set(el, 0);
+      return 0;
+    }
+    if (expression.kind === "absolute") {
+      const value = Math.max(0, expression.value);
+      startCache.set(el, value);
+      return value;
+    }
+    const target = findReferenceTargetEl(doc, expression.refId);
+    if (!target) {
+      startCache.set(el, 0);
+      return 0;
+    }
+    const targetStart = resolveReferencedStart(doc, target, startCache, visiting);
+    const targetDuration = resolveReferencedDuration(doc, target, startCache, visiting);
+    const resolved = targetDuration != null && targetDuration > 0 ? Math.max(0, targetStart + targetDuration + expression.offset) : Math.max(0, targetStart + expression.offset);
+    startCache.set(el, resolved);
+    return resolved;
+  } finally {
+    visiting.delete(el);
+  }
+}
+function resolveReferencedDuration(doc, el, startCache, visiting) {
+  const durationAttr = parseNumeric(el.getAttribute("data-duration"));
+  if (durationAttr != null && durationAttr > 0) return durationAttr;
+  const endAttr = parseNumeric(el.getAttribute("data-end"));
+  if (endAttr != null) {
+    const start = resolveReferencedStart(doc, el, startCache, visiting);
+    const delta = endAttr - start;
+    if (Number.isFinite(delta) && delta > 0) return delta;
+  }
+  return null;
+}
+export {
+  resolveReferencedDuration,
+  resolveReferencedStart
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/parsers",
-  "version": "0.8.181",
+  "version": "0.8.183",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
@@ -100,6 +100,14 @@
       "import": "./dist/timeSpans.js",
       "types": "./dist/timeSpans.d.ts"
     },
+    "./media-timing": {
+      "import": "./dist/mediaTiming.js",
+      "types": "./dist/mediaTiming.d.ts"
+    },
+    "./reference-resolver": {
+      "import": "./dist/referenceResolver.js",
+      "types": "./dist/referenceResolver.d.ts"
+    },
     "./composition-duration": {
       "import": "./dist/compositionDuration.js",
       "types": "./dist/compositionDuration.d.ts"
@@ -123,7 +131,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.0.0",
     "vitest": "^4.1.11",
-    "@hyperframes/core": "0.8.181"
+    "@hyperframes/core": "0.8.183"
   },
   "scripts": {
     "build": "tsup",