@hyperframes/parsers 0.7.60 → 0.7.62

package/dist/assetResolution.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared local-asset resolution helpers for every package that maps
+ * composition asset URLs to files on disk (lint project rules, the HEVC
+ * preview check, studio-server's media codec scan). Import via the
+ * `@hyperframes/parsers/asset-resolution` subpath.
+ */
+declare function isRemoteOrInlineUrl(url: string): boolean;
+declare function cleanAssetUrl(url: string): string;
+declare function isWithinProjectRoot(projectDir: string, candidate: string): boolean;
+declare function resolveLocalAssetCandidates(projectDir: string, url: string): string[];
+declare function resolveExistingLocalAsset(projectDir: string, url: string): {
+    resolved: string;
+    rootRelativePath: string;
+} | null;
+/** Blanks out comments, `<style>`, and `<script>` bodies so tag-scanning
+ * regexes don't false-positive on commented-out or scripted markup. */
+declare function maskNonScannableRanges(html: string): string;
+
+export { cleanAssetUrl, isRemoteOrInlineUrl, isWithinProjectRoot, maskNonScannableRanges, resolveExistingLocalAsset, resolveLocalAssetCandidates };

package/dist/assetResolution.js

@@ -0,0 +1,87 @@
+// src/assetResolution.ts
+import { existsSync } from "fs";
+import { isAbsolute, posix, relative, resolve } from "path";
+
+// src/utils/urlPath.ts
+function decodeUrlPathVariants(path) {
+  const variants = [path];
+  try {
+    const decoded = decodeURIComponent(path);
+    if (decoded !== path) variants.unshift(decoded);
+  } catch {
+  }
+  return variants;
+}
+
+// src/assetResolution.ts
+function isRemoteOrInlineUrl(url) {
+  return /^(https?:|data:|blob:|\/\/|#)/i.test(url);
+}
+function cleanAssetUrl(url) {
+  return url.trim().split(/[?#]/, 1)[0] ?? "";
+}
+function isWithinProjectRoot(projectDir, candidate) {
+  const projectRoot = resolve(projectDir);
+  const relativePath = relative(projectRoot, candidate);
+  return relativePath === "" || !relativePath.startsWith("..") && !isAbsolute(relativePath);
+}
+function addCandidate(candidates, candidate) {
+  if (!candidates.includes(candidate)) candidates.push(candidate);
+}
+function resolveLocalAssetCandidates(projectDir, url) {
+  const cleanUrl = cleanAssetUrl(url);
+  const projectRoot = resolve(projectDir);
+  const candidates = [];
+  for (const variant of decodeUrlPathVariants(cleanUrl)) {
+    const projectRelative = variant.startsWith("/") ? variant.slice(1) : variant;
+    const resolved = resolve(projectRoot, projectRelative);
+    if (isWithinProjectRoot(projectRoot, resolved)) {
+      addCandidate(candidates, resolved);
+      continue;
+    }
+    const normalized = posix.normalize(projectRelative.replace(/\\/g, "/"));
+    const clamped = normalized.replace(/^(\.\.\/)+/, "");
+    if (clamped && !clamped.startsWith("..")) {
+      addCandidate(candidates, resolve(projectRoot, clamped));
+    }
+  }
+  return candidates;
+}
+function resolveExistingLocalAsset(projectDir, url) {
+  const projectRoot = resolve(projectDir);
+  const resolved = resolveLocalAssetCandidates(projectRoot, url).find(existsSync);
+  if (!resolved) return null;
+  return { resolved, rootRelativePath: relative(projectRoot, resolved) };
+}
+function maskRange(src, pattern) {
+  return src.replace(pattern, (m) => " ".repeat(m.length));
+}
+function maskHtmlComments(src) {
+  const chunks = [];
+  let cursor = 0;
+  while (true) {
+    const start = src.indexOf("<!--", cursor);
+    if (start === -1) break;
+    const end = src.indexOf("-->", start + 4);
+    if (end === -1) break;
+    const afterComment = end + 3;
+    chunks.push(src.slice(cursor, start), " ".repeat(afterComment - start));
+    cursor = afterComment;
+  }
+  return chunks.length === 0 ? src : chunks.join("") + src.slice(cursor);
+}
+function maskNonScannableRanges(html) {
+  let out = maskHtmlComments(html);
+  out = maskRange(out, /<style\b[^>]*>[\s\S]*?<\/style\b[^>]*>/gi);
+  out = maskRange(out, /<script\b[^>]*>[\s\S]*?<\/script\b[^>]*>/gi);
+  return out;
+}
+export {
+  cleanAssetUrl,
+  isRemoteOrInlineUrl,
+  isWithinProjectRoot,
+  maskNonScannableRanges,
+  resolveExistingLocalAsset,
+  resolveLocalAssetCandidates
+};
+//# sourceMappingURL=assetResolution.js.map

package/dist/assetResolution.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/assetResolution.ts","../src/utils/urlPath.ts"],"sourcesContent":["import { existsSync } from \"node:fs\";\nimport { isAbsolute, posix, relative, resolve } from \"node:path\";\nimport { decodeUrlPathVariants } from \"./composition.js\";\n\n/**\n * Shared local-asset resolution helpers for every package that maps\n * composition asset URLs to files on disk (lint project rules, the HEVC\n * preview check, studio-server's media codec scan). Import via the\n * `@hyperframes/parsers/asset-resolution` subpath.\n */\n\nexport function isRemoteOrInlineUrl(url: string): boolean {\n  return /^(https?:|data:|blob:|\\/\\/|#)/i.test(url);\n}\n\nexport function cleanAssetUrl(url: string): string {\n  return url.trim().split(/[?#]/, 1)[0] ?? \"\";\n}\n\nexport function isWithinProjectRoot(projectDir: string, candidate: string): boolean {\n  const projectRoot = resolve(projectDir);\n  const relativePath = relative(projectRoot, candidate);\n  return relativePath === \"\" || (!relativePath.startsWith(\"..\") && !isAbsolute(relativePath));\n}\n\nfunction addCandidate(candidates: string[], candidate: string): void {\n  if (!candidates.includes(candidate)) candidates.push(candidate);\n}\n\nexport function resolveLocalAssetCandidates(projectDir: string, url: string): string[] {\n  const cleanUrl = cleanAssetUrl(url);\n  const projectRoot = resolve(projectDir);\n  const candidates: string[] = [];\n\n  for (const variant of decodeUrlPathVariants(cleanUrl)) {\n    const projectRelative = variant.startsWith(\"/\") ? variant.slice(1) : variant;\n    const resolved = resolve(projectRoot, projectRelative);\n    if (isWithinProjectRoot(projectRoot, resolved)) {\n      addCandidate(candidates, resolved);\n      continue;\n    }\n\n    const normalized = posix.normalize(projectRelative.replace(/\\\\/g, \"/\"));\n    const clamped = normalized.replace(/^(\\.\\.\\/)+/, \"\");\n    if (clamped && !clamped.startsWith(\"..\")) {\n      addCandidate(candidates, resolve(projectRoot, clamped));\n    }\n  }\n\n  return candidates;\n}\n\nexport function resolveExistingLocalAsset(\n  projectDir: string,\n  url: string,\n): { resolved: string; rootRelativePath: string } | null {\n  const projectRoot = resolve(projectDir);\n  const resolved = resolveLocalAssetCandidates(projectRoot, url).find(existsSync);\n  if (!resolved) return null;\n  return { resolved, rootRelativePath: relative(projectRoot, resolved) };\n}\n\nfunction maskRange(src: string, pattern: RegExp): string {\n  return src.replace(pattern, (m) => \" \".repeat(m.length));\n}\n\nfunction maskHtmlComments(src: string): string {\n  const chunks: string[] = [];\n  let cursor = 0;\n\n  while (true) {\n    const start = src.indexOf(\"<!--\", cursor);\n    if (start === -1) break;\n    const end = src.indexOf(\"-->\", start + 4);\n    if (end === -1) break;\n    const afterComment = end + 3;\n    chunks.push(src.slice(cursor, start), \" \".repeat(afterComment - start));\n    cursor = afterComment;\n  }\n\n  return chunks.length === 0 ? src : chunks.join(\"\") + src.slice(cursor);\n}\n\n/** Blanks out comments, `<style>`, and `<script>` bodies so tag-scanning\n * regexes don't false-positive on commented-out or scripted markup. */\nexport function maskNonScannableRanges(html: string): string {\n  let out = maskHtmlComments(html);\n  out = maskRange(out, /<style\\b[^>]*>[\\s\\S]*?<\\/style\\b[^>]*>/gi);\n  out = maskRange(out, /<script\\b[^>]*>[\\s\\S]*?<\\/script\\b[^>]*>/gi);\n  return out;\n}\n","export function decodeUrlPathVariants(path: string): string[] {\n  const variants = [path];\n  try {\n    const decoded = decodeURIComponent(path);\n    if (decoded !== path) variants.unshift(decoded);\n  } catch {\n    // Malformed percent sequences may be literal filesystem names.\n  }\n\n  return variants;\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AAC3B,SAAS,YAAY,OAAO,UAAU,eAAe;;;ACD9C,SAAS,sBAAsB,MAAwB;AAC5D,QAAM,WAAW,CAAC,IAAI;AACtB,MAAI;AACF,UAAM,UAAU,mBAAmB,IAAI;AACvC,QAAI,YAAY,KAAM,UAAS,QAAQ,OAAO;AAAA,EAChD,QAAQ;AAAA,EAER;AAEA,SAAO;AACT;;;ADCO,SAAS,oBAAoB,KAAsB;AACxD,SAAO,iCAAiC,KAAK,GAAG;AAClD;AAEO,SAAS,cAAc,KAAqB;AACjD,SAAO,IAAI,KAAK,EAAE,MAAM,QAAQ,CAAC,EAAE,CAAC,KAAK;AAC3C;AAEO,SAAS,oBAAoB,YAAoB,WAA4B;AAClF,QAAM,cAAc,QAAQ,UAAU;AACtC,QAAM,eAAe,SAAS,aAAa,SAAS;AACpD,SAAO,iBAAiB,MAAO,CAAC,aAAa,WAAW,IAAI,KAAK,CAAC,WAAW,YAAY;AAC3F;AAEA,SAAS,aAAa,YAAsB,WAAyB;AACnE,MAAI,CAAC,WAAW,SAAS,SAAS,EAAG,YAAW,KAAK,SAAS;AAChE;AAEO,SAAS,4BAA4B,YAAoB,KAAuB;AACrF,QAAM,WAAW,cAAc,GAAG;AAClC,QAAM,cAAc,QAAQ,UAAU;AACtC,QAAM,aAAuB,CAAC;AAE9B,aAAW,WAAW,sBAAsB,QAAQ,GAAG;AACrD,UAAM,kBAAkB,QAAQ,WAAW,GAAG,IAAI,QAAQ,MAAM,CAAC,IAAI;AACrE,UAAM,WAAW,QAAQ,aAAa,eAAe;AACrD,QAAI,oBAAoB,aAAa,QAAQ,GAAG;AAC9C,mBAAa,YAAY,QAAQ;AACjC;AAAA,IACF;AAEA,UAAM,aAAa,MAAM,UAAU,gBAAgB,QAAQ,OAAO,GAAG,CAAC;AACtE,UAAM,UAAU,WAAW,QAAQ,cAAc,EAAE;AACnD,QAAI,WAAW,CAAC,QAAQ,WAAW,IAAI,GAAG;AACxC,mBAAa,YAAY,QAAQ,aAAa,OAAO,CAAC;AAAA,IACxD;AAAA,EACF;AAEA,SAAO;AACT;AAEO,SAAS,0BACd,YACA,KACuD;AACvD,QAAM,cAAc,QAAQ,UAAU;AACtC,QAAM,WAAW,4BAA4B,aAAa,GAAG,EAAE,KAAK,UAAU;AAC9E,MAAI,CAAC,SAAU,QAAO;AACtB,SAAO,EAAE,UAAU,kBAAkB,SAAS,aAAa,QAAQ,EAAE;AACvE;AAEA,SAAS,UAAU,KAAa,SAAyB;AACvD,SAAO,IAAI,QAAQ,SAAS,CAAC,MAAM,IAAI,OAAO,EAAE,MAAM,CAAC;AACzD;AAEA,SAAS,iBAAiB,KAAqB;AAC7C,QAAM,SAAmB,CAAC;AAC1B,MAAI,SAAS;AAEb,SAAO,MAAM;AACX,UAAM,QAAQ,IAAI,QAAQ,QAAQ,MAAM;AACxC,QAAI,UAAU,GAAI;AAClB,UAAM,MAAM,IAAI,QAAQ,OAAO,QAAQ,CAAC;AACxC,QAAI,QAAQ,GAAI;AAChB,UAAM,eAAe,MAAM;AAC3B,WAAO,KAAK,IAAI,MAAM,QAAQ,KAAK,GAAG,IAAI,OAAO,eAAe,KAAK,CAAC;AACtE,aAAS;AAAA,EACX;AAEA,SAAO,OAAO,WAAW,IAAI,MAAM,OAAO,KAAK,EAAE,IAAI,IAAI,MAAM,MAAM;AACvE;AAIO,SAAS,uBAAuB,MAAsB;AAC3D,MAAI,MAAM,iBAAiB,IAAI;AAC/B,QAAM,UAAU,KAAK,0CAA0C;AAC/D,QAAM,UAAU,KAAK,4CAA4C;AACjE,SAAO;AACT;","names":[]}

package/dist/composition.d.ts

@@ -1,5 +1,6 @@
-import { C as CompositionVariable } from './types-CaeOJXdW.js';
-export { A as AddElementData, b as Asset, B as BooleanVariable, c as CANVAS_DIMENSIONS, d as COMPOSITION_VARIABLE_TYPES, a as CanvasResolution, e as ColorVariable, f as CompositionAPI, g as CompositionAsset, h as CompositionSpec, i as CompositionVariableBase, j as CompositionVariableType, D as DEFAULT_DURATIONS, E as ElementKeyframes, k as EnumVariable, F as FontVariable, I as ImageVariable, K as Keyframe, l as KeyframeProperties, M as MediaElementType, m as MediaFile, N as NumberVariable, P as PlayerAPI, n as StageZoom, S as StageZoomKeyframe, o as StringVariable, p as TIMELINE_COLORS, q as TimelineCompositionElement, T as TimelineElement, r as TimelineElementBase, s as TimelineElementType, t as TimelineMediaElement, u as TimelineTextElement, v as VALID_CANVAS_RESOLUTIONS, V as ValidationResult, W as WaveformData, w as getDefaultStageZoom, x as isCompositionElement, y as isMediaElement, z as isTextElement, G as normalizeResolutionFlag } from './types-CaeOJXdW.js';
+import { C as CompositionVariable } from './types-ewozML_N.js';
+export { A as AddElementData, b as Asset, B as BooleanVariable, c as CANVAS_DIMENSIONS, d as COMPOSITION_VARIABLE_TYPES, a as CanvasResolution, e as ColorVariable, f as CompositionAPI, g as CompositionAsset, h as CompositionSpec, i as CompositionVariableBase, j as CompositionVariableType, D as DEFAULT_DURATIONS, E as ElementKeyframes, k as EnumVariable, F as FontVariable, I as ImageVariable, K as Keyframe, l as KeyframeProperties, M as MediaElementType, m as MediaFile, N as NumberVariable, P as PlayerAPI, R as ResolvedResolutionFlag, n as StageZoom, S as StageZoomKeyframe, o as StringVariable, p as TIMELINE_COLORS, q as TimelineCompositionElement, T as TimelineElement, r as TimelineElementBase, s as TimelineElementType, t as TimelineMediaElement, u as TimelineTextElement, v as VALID_CANVAS_RESOLUTIONS, V as ValidationResult, W as WaveformData, w as getDefaultStageZoom, x as isAspectAgnosticResolutionAlias, y as isCompositionElement, z as isMediaElement, G as isTextElement, H as normalizeResolutionFlag, J as resolveResolutionFlagPair } from './types-ewozML_N.js';
+export { CANONICAL_AUTHORED_TIMING_ATTRIBUTES, COMPOSITION_ATTRIBUTES, COMPOSITION_CONTRACT_VERSION, ClipAttributeReader, ClipAttributeWriter, ClipTiming, ClipTimingDiagnostic, ClipTimingDiagnosticCode, ClipTimingUpdate, ClipTimingWriteError, DERIVED_TIMING_ATTRIBUTES, LEGACY_TIMING_ATTRIBUTES, ReadClipTimingOptions, ReferenceExpression, parseNumeric, parseStartExpression, readClipTiming, writeClipTiming } from './compositionContract.js';
 
 /**
  * Browser-safe parser for the `data-composition-variables` schema attribute.

package/dist/composition.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",
@@ -334,17 +350,294 @@ function scanVariableUsage(scriptText) {
   }
   return { usedIds, scanIncomplete };
 }
+
+// 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);
+}
 export {
+  CANONICAL_AUTHORED_TIMING_ATTRIBUTES,
   CANONICAL_FONT_DISPLAY_NAMES,
   CANVAS_DIMENSIONS,
+  COMPOSITION_ATTRIBUTES,
+  COMPOSITION_CONTRACT_VERSION,
   COMPOSITION_VARIABLE_TYPES,
+  ClipTimingWriteError,
   DEFAULT_DURATIONS,
+  DERIVED_TIMING_ATTRIBUTES,
   FONT_ALIAS_KEYS,
   FONT_ALIAS_MAP,
+  LEGACY_TIMING_ATTRIBUTES,
   TIMELINE_COLORS,
   VALID_CANVAS_RESOLUTIONS,
   decodeUrlPathVariants,
   getDefaultStageZoom,
+  isAspectAgnosticResolutionAlias,
   isCompositionElement,
   isCompositionVariable,
   isMediaElement,
@@ -352,7 +645,12 @@ export {
   isTextElement,
   normalizeResolutionFlag,
   parseCompositionVariables,
+  parseNumeric,
+  parseStartExpression,
+  readClipTiming,
   resolveAliasDisplayName,
-  scanVariableUsage
+  resolveResolutionFlagPair,
+  scanVariableUsage,
+  writeClipTiming
 };
 //# sourceMappingURL=composition.js.map