Skip to content

Write HTML. Render video. Built for agents.

fix(lint): place each scene's audio at its host's start in the audio overlap check (#6005)

Miguel Ángel18207de1c466
diff --git a/packages/cli/src/utils/lintProject.test.ts b/packages/cli/src/utils/lintProject.test.ts
index d468a66bb3..e78576ae25 100644
--- a/packages/cli/src/utils/lintProject.test.ts
+++ b/packages/cli/src/utils/lintProject.test.ts
@@ -1076,7 +1076,7 @@ describe("duplicate_audio_track", () => {
expect(finding).toBeUndefined();
});
- it("deduplicates same audio found in root + sub-composition", async () => {
+ it("ignores audio in a sub-composition the root never mounts", async () => {
const project = makeProject(validHtmlWithAudio(), {
"scene.html": validHtmlWithAudio("scene"),
});
@@ -1102,7 +1102,7 @@ describe("duplicate_audio_track", () => {
it("formats Infinity end times as 'end' without crashing", async () => {
const html = `<html><body>
- <div data-composition-id="main" data-width="1920" data-height="1080" data-duration="30">
+ <div data-composition-id="main" data-width="1920" data-height="1080">
<audio id="a" src="a.wav" data-track-index="0" data-start="0">
<audio id="b" src="b.wav" data-track-index="0" data-start="5">
</div>
@@ -1117,7 +1117,8 @@ describe("duplicate_audio_track", () => {
});
it("finds audio across multiple HTML sources (g-flag regression)", async () => {
- const project = makeProject(validHtmlWithAudio(), {
+ const mountScene = `</audio><div data-composition-id="scene" data-composition-src="compositions/scene.html" data-start="0"></div>`;
+ const project = makeProject(validHtmlWithAudio().replace("</audio>", mountScene), {
"scene.html": `<html><body>
<div data-composition-id="scene" data-width="1920" data-height="1080">
<audio id="overlap" src="music.wav" data-track-index="0" data-start="5" data-duration="20">
diff --git a/packages/core/src/mediaTiming.ts b/packages/core/src/mediaTiming.ts
index 9061828632..3eb88061fd 100644
--- a/packages/core/src/mediaTiming.ts
+++ b/packages/core/src/mediaTiming.ts
@@ -1,83 +1,2 @@
-import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
-
-export const MEDIA_START_BASIS_ATTR = "data-hf-media-start-basis";
-
-export type MediaStartBasis = "local" | "global";
-
-export function readMediaStartBasis(value: string | null | undefined): MediaStartBasis {
- return value?.trim().toLowerCase() === "global" ? "global" : "local";
-}
-
-/** Resolve authored media time onto the root timeline. Nested media is local
- * by default; only an explicit compatibility marker preserves a legacy
- * root-global value. */
-export function resolveAbsoluteMediaStartSeconds(input: {
- authoredStart: number;
- hostStart: number;
- basis?: string | null;
-}): number {
- return readMediaStartBasis(input.basis) === "global"
- ? input.authoredStart
- : input.hostStart + input.authoredStart;
-}
-
-/** 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. */
-export function resolveMediaStartSeconds(
- input: MediaStartInput & { ordinaryStart: () => number },
-): number {
- if (!hasLiteralNestedStart(input)) return input.ordinaryStart();
- return resolveAbsoluteMediaStartSeconds({
- authoredStart: input.authoredStart,
- hostStart: input.hostStart,
- basis: input.basis,
- });
-}
-
-/** True when the authored start is already root time, so no host offset applies. */
-export function isRootGlobalMediaStart(input: MediaStartInput): boolean {
- return hasLiteralNestedStart(input) && readMediaStartBasis(input.basis) === "global";
-}
-
-export interface MediaStartInput {
- authoredStart: number | null;
- hostStart: number;
- hasAutoStart: boolean;
- basis?: string | null;
-}
-
-function hasLiteralNestedStart(
- input: MediaStartInput,
-): input is MediaStartInput & { authoredStart: number } {
- return !input.hasAutoStart && input.authoredStart != null && input.hostStart !== 0;
-}
-
-/** A composition host's in-point; only a host with one shifts or cuts what it holds. */
-export function hostInPointSeconds(host: Pick<Element, "getAttribute">): number {
- return readMediaOffsetSeconds((name) => host.getAttribute(name));
-}
-
-/** Main-timeline time of a sub-composition's local t=0: its host's start minus its in-point. */
-export function compositionOriginSeconds(
- hostStart: number,
- host: Pick<Element, "getAttribute">,
-): number {
- return hostStart - hostInPointSeconds(host);
-}
-
-export interface HostSlot {
- start: number;
- end: number;
-}
-
-/** Each in-point host cuts the span to its own window. */
-export function cutToHostSlots(
- span: { start: number; end: number },
- hosts: readonly HostSlot[],
-): { start: number; end: number } {
- 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);
-}
+// Kept for existing importers; the rule lives in @hyperframes/parsers.
+export * from "@hyperframes/parsers/media-timing";
diff --git a/packages/engine/src/services/referenceResolver.ts b/packages/engine/src/services/referenceResolver.ts
index 5f9dc516a7..43003925fd 100644
--- a/packages/engine/src/services/referenceResolver.ts
+++ b/packages/engine/src/services/referenceResolver.ts
@@ -1,106 +1,2 @@
-/**
- * Node-side resolver for relative `data-start` timing references, shared by
- * every parser that reads media timing out of compiled HTML — video frames
- * (`parseVideoElements`), images (`parseImageElements`), and audio
- * (`parseAudioElements`). Keeping the resolution in ONE place is load-bearing:
- * if audio and video disagree on what `data-start="intro"` means, a relative
- * reference that renders a video at the right time silently drops the audio
- * track (they used to — audio parsed `parseFloat("intro") = NaN`).
- *
- * Mirrors the browser runtime's startResolver so `snapshot`/`render` agree.
- * DOM access is via a minimal structural shape so it works against linkedom
- * (Node) without pulling in lib.dom types.
- */
-
-import { parseNumeric, parseStartExpression } from "@hyperframes/core";
-
-/** Minimal structural DOM shape the reference resolver needs. */
-export interface RefResolverEl {
- getAttribute(name: string): string | null;
-}
-export interface RefResolverDoc {
- getElementById(id: string): RefResolverEl | null;
- querySelector(selector: string): RefResolverEl | null;
-}
-
-/**
- * Find the element a relative `data-start` reference points at — by `id`
- * first, then by `data-composition-id` (a sub-composition can be referenced).
- * The reference-id grammar (see parseStartExpression) is restricted to
- * `[A-Za-z0-9_.:-]`, none of which need escaping inside a quoted attribute
- * selector, so no CSS.escape (absent in linkedom) is required.
- */
-function findReferenceTargetEl(doc: RefResolverDoc, refId: string): RefResolverEl | null {
- return doc.getElementById(refId) ?? doc.querySelector(`[data-composition-id="${refId}"]`);
-}
-
-/**
- * Resolve an element's absolute start time (seconds) the same way the browser
- * runtime's startResolver does, so `<video data-start="intro">` (a relative
- * reference to another clip's end) renders at the right time instead of
- * producing NaN and compositing blank / dropping audio. Durations come from
- * `data-duration` or `data-end` here; the natural-media-duration fallback isn't
- * known at parse time, so — exactly like the runtime — an unknown-duration
- * reference falls back to the target's start and an unknown target falls back
- * to 0 (never NaN).
- */
-export function resolveReferencedStart(
- doc: RefResolverDoc,
- el: RefResolverEl,
- startCache: Map<RefResolverEl, number>,
- visiting: Set<RefResolverEl>,
-): number {
- const cached = startCache.get(el);
- if (cached !== undefined) return cached;
- if (visiting.has(el)) return 0; // cycle guard (A -> B -> A)
- 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);
- }
-}
-
-/**
- * Duration of a referenced clip, from `data-duration` or `data-end - start`.
- * Returns null when only the natural media duration would settle it (unknown
- * at parse time) — the caller then treats the reference as duration-0.
- */
-export function resolveReferencedDuration(
- doc: RefResolverDoc,
- el: RefResolverEl,
- startCache: Map<RefResolverEl, number>,
- visiting: Set<RefResolverEl>,
-): number | null {
- 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;
-}
+// Kept for existing importers; the resolver lives in @hyperframes/parsers.
+export * from "@hyperframes/parsers/reference-resolver";
diff --git a/packages/lint/src/project.test.ts b/packages/lint/src/project.test.ts
index 78dd7a58cc..980921638d 100644
--- a/packages/lint/src/project.test.ts
+++ b/packages/lint/src/project.test.ts
@@ -1044,6 +1044,51 @@ describe("audio-aware project rules", () => {
);
expect(codes).not.toContain("duplicate_audio_track");
});
+
+ const scene = (id: string, videoDuration = 5) => `<template id="${id}-template">
+ <div data-composition-id="${id}" data-width="1920" data-height="1080">
+ ${video('data-has-audio="true"')
+ .replace('src="a.mp4"', `src="${id}.mp4"`)
+ .replace('data-duration="5"', `data-duration="${videoDuration}"`)}
+ </div>
+</template>`;
+ const host = (id: string, start: number | string, length: number | null) =>
+ `<div data-composition-id="${id}" data-composition-src="compositions/${id}.html" data-start="${start}"${length === null ? "" : ` data-duration="${length}"`} data-track-index="1"></div>`;
+ const scenesCodes = (
+ starts: Array<number | string>,
+ { videoDuration = 5, hostDuration = 5 as number | null } = {},
+ ) => {
+ const ids = starts.map((_, i) => `s${i}`);
+ const project = makeProject(
+ composition(ids.map((id, i) => host(id, starts[i]!, hostDuration)).join("")),
+ Object.fromEntries(ids.map((id) => [`${id}.html`, scene(id, videoDuration)])),
+ );
+ return lintProject(project).then(({ results }) =>
+ results.flatMap((result) => result.result.findings.map((f) => f.code)),
+ );
+ };
+
+ it("places each scene's audio at its host's start, so scenes played one after another pass", async () => {
+ expect(await scenesCodes([0, 5])).not.toContain("duplicate_audio_track");
+ expect(await scenesCodes([0, 5], { hostDuration: null })).not.toContain(
+ "duplicate_audio_track",
+ );
+ });
+
+ it("still warns when two scenes' hosts overlap", async () => {
+ expect(await scenesCodes([0, 2])).toContain("duplicate_audio_track");
+ });
+
+ it("places a scene chained to the one before it with a reference start", async () => {
+ expect(await scenesCodes([0, "s0"])).not.toContain("duplicate_audio_track");
+ expect(await scenesCodes([0, "s0 - 2"])).toContain("duplicate_audio_track");
+ });
+
+ it("cuts a scene's audio at its host's end, as playback does", async () => {
+ expect(await scenesCodes([0, 5], { videoDuration: 10 })).not.toContain(
+ "duplicate_audio_track",
+ );
+ });
});
describe("audio_file_without_element", () => {
diff --git a/packages/lint/src/project.ts b/packages/lint/src/project.ts
index d4b19eb3a9..b20c9e3eb9 100644
--- a/packages/lint/src/project.ts
+++ b/packages/lint/src/project.ts
@@ -4,6 +4,20 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
import { dirname, extname, join, relative, resolve } from "node:path";
import { rewriteAssetPath } from "@hyperframes/parsers/asset-paths";
import { spansOverlap } from "@hyperframes/parsers/time-spans";
+import {
+ compositionOriginSeconds,
+ cutToHostSlots,
+ MEDIA_START_BASIS_ATTR,
+ resolveMediaStartSeconds,
+ type HostSlot,
+} from "@hyperframes/parsers/media-timing";
+import { parseNumeric } from "@hyperframes/parsers/composition-contract";
+import {
+ resolveReferencedDuration,
+ resolveReferencedStart,
+ type RefResolverDoc,
+ type RefResolverEl,
+} from "@hyperframes/parsers/reference-resolver";
import { checkSubCompositionUsability } from "@hyperframes/parsers/sub-composition-validity";
import { parseHTML } from "linkedom";
import {
@@ -31,7 +45,7 @@ import type {
HyperframeLinterOptions,
} from "./types.js";
import type { ParsableDocumentLike } from "@hyperframes/parsers/sub-composition-validity";
-import { isAudibleVideoTag, mediaSrcOf, mediaSrcTagRe, readAttr, readDecodedAttr } from "./utils";
+import { isAudibleVideo, isAudibleVideoTag, mediaSrcOf, mediaSrcTagRe } from "./utils";
/** Adapts linkedom's `parseHTML` to the `checkSubCompositionUsability` contract. */
function parseSubCompHtml(html: string): ParsableDocumentLike {
@@ -265,7 +279,7 @@ export async function lintProject(
...lintTextureMaskAssetNotFound(projectDir, allHtmlSources),
...(!entryFile ? lintMultipleRootCompositions(projectDir) : []),
...(!entryFile ? lintBlankRootWithStandaloneComposition(rootHtml, allHtmlSources) : []),
- ...lintDuplicateAudioTracks(allHtmlSources),
+ ...lintDuplicateAudioTracks(projectDir, rootHtml),
...lintMissingOrEmptySubComposition(projectDir, rootHtml),
...(await lintVideoMediaStartPastEof(projectDir, allHtmlSources)),
...(await lintHevcPreviewCodec(collectLocalVideoCandidates(projectDir, allHtmlSources))),
@@ -552,34 +566,110 @@ function lintMultipleRootCompositions(projectDir: string): HyperframeLintFinding
return findings;
}
-function lintDuplicateAudioTracks(htmlSources: HtmlSource[]): HyperframeLintFinding[] {
- const findings: HyperframeLintFinding[] = [];
- const tracks: Array<{ trackIndex: number; start: number; end: number; src: string }> = [];
- const seen = new Set<string>();
+interface AudioSpan {
+ trackIndex: number;
+ start: number;
+ end: number;
+ src: string;
+}
- for (const { html } of htmlSources) {
- const soundTagRe = /<(?:audio|video)\b[^>]*>/gi;
- let match: RegExpExecArray | null;
- while ((match = soundTagRe.exec(html)) !== null) {
- const tag = match[0];
- if (/^<video/i.test(tag) && !isAudibleVideoTag(tag)) continue;
- const trackStr = readAttr(tag, "data-track-index");
- const startStr = readAttr(tag, "data-start");
- const durStr = readAttr(tag, "data-duration");
- const src = readDecodedAttr(tag, "src") || "unknown";
- if (!trackStr || !startStr) continue;
-
- const trackIndex = parseInt(trackStr, 10);
- const start = parseFloat(startStr);
- const duration = durStr ? parseFloat(durStr) : Infinity;
- const key = `${src}:${start}:${duration}:${trackIndex}`;
- if (seen.has(key)) continue;
- seen.add(key);
-
- tracks.push({ trackIndex, start, end: start + duration, src });
+/** One parsed file: reference starts resolve within it, memoised. */
+interface TimingFile {
+ doc: RefResolverDoc;
+ starts: Map<RefResolverEl, number>;
+}
+
+const timingFile = (doc: RefResolverDoc): TimingFile => ({ doc, starts: new Map() });
+const localStart = (file: TimingFile, el: Element) =>
+ resolveReferencedStart(file.doc, el, file.starts, new Set());
+const localDuration = (file: TimingFile, el: Element) =>
+ resolveReferencedDuration(file.doc, el, file.starts, new Set());
+
+/** Audible media on the main timeline, walked from the root through the scenes it mounts. */
+function collectMainTimelineAudio(projectDir: string, rootHtml: string): AudioSpan[] {
+ const spans: AudioSpan[] = [];
+ type Placement = { file: TimingFile; origin: number; slots: HostSlot[]; mounting: string[] };
+ const mount = (html: string, at: Omit<Placement, "file">) => {
+ const { document } = parseHTML(html);
+ const root = querySelectorAllIncludingTemplates(document, "[data-composition-id]")[0];
+ if (root) visit(root, { ...at, file: timingFile(document) });
+ };
+ const visit = (parent: ParentNode, at: Placement) => {
+ for (const el of parent.children) {
+ if (el.tagName === "TEMPLATE") {
+ visit((el as HTMLTemplateElement).content, at);
+ continue;
+ }
+ const span = audioSpanOf(el, at.file, at.origin, at.slots);
+ if (span) spans.push(span);
+ const scope = nestedScopeOf(el, at.file, at.origin, at.slots);
+ if (!scope) {
+ visit(el, at);
+ continue;
+ }
+ const inner = { ...at, ...scope };
+ const src = el.getAttribute("data-composition-src")?.trim();
+ const file = src && !isUnresolvedAssetPlaceholder(src) && !isRemoteOrInlineUrl(src);
+ const filePath = file ? resolve(projectDir, src) : null;
+ if (filePath && !at.mounting.includes(filePath)) {
+ const read = readProjectFile(filePath);
+ if (read.kind === "file")
+ mount(read.text, { ...inner, mounting: [...at.mounting, filePath] });
+ }
+ visit(el, inner);
}
+ };
+ const { document } = parseHTML(rootHtml);
+ visit(document, { file: timingFile(document), origin: 0, slots: [], mounting: [] });
+ return spans;
+}
+
+/** A composition or scene host: its children's local t=0 sits at the host's start, cut to its window. */
+function nestedScopeOf(
+ el: Element,
+ file: TimingFile,
+ origin: number,
+ slots: HostSlot[],
+): { origin: number; slots: HostSlot[] } | null {
+ if (!el.hasAttribute("data-composition-id") && !el.hasAttribute("data-composition-src")) {
+ return null;
}
+ const start = origin + localStart(file, el);
+ const duration = localDuration(file, el);
+ const window = duration === null ? [] : [{ start, end: start + duration }];
+ return { origin: compositionOriginSeconds(start, el), slots: [...slots, ...window] };
+}
+function audioSpanOf(
+ el: Element,
+ file: TimingFile,
+ origin: number,
+ slots: HostSlot[],
+): AudioSpan | null {
+ const tag = el.tagName.toLowerCase();
+ if (tag !== "audio" && !(tag === "video" && isAudibleVideo((name) => el.getAttribute(name)))) {
+ return null;
+ }
+ const trackStr = el.getAttribute("data-track-index");
+ if (!trackStr || !el.hasAttribute("data-start")) return null;
+ const start = resolveMediaStartSeconds({
+ authoredStart: parseNumeric(el.getAttribute("data-start")),
+ hostStart: origin,
+ hasAutoStart: el.hasAttribute("data-hf-auto-start"),
+ basis: el.getAttribute(MEDIA_START_BASIS_ATTR),
+ ordinaryStart: () => origin + localStart(file, el),
+ });
+ const duration = parseNumeric(el.getAttribute("data-duration")) ?? localDuration(file, el);
+ const kept = cutToHostSlots({ start, end: start + (duration ?? Infinity) }, slots);
+ if (kept.end <= kept.start) return null;
+ return { trackIndex: parseInt(trackStr, 10), ...kept, src: el.getAttribute("src") || "unknown" };
+}
+
+const formatSeconds = (t: number) => (Number.isFinite(t) ? String(Number(t.toFixed(2))) : "end");
+
+function lintDuplicateAudioTracks(projectDir: string, rootHtml: string): HyperframeLintFinding[] {
+ const findings: HyperframeLintFinding[] = [];
+ const tracks = collectMainTimelineAudio(projectDir, rootHtml);
for (let i = 0; i < tracks.length; i++) {
for (let j = i + 1; j < tracks.length; j++) {
const a = tracks[i]!;
@@ -589,7 +679,7 @@ function lintDuplicateAudioTracks(htmlSources: HtmlSource[]): HyperframeLintFind
findings.push({
code: "duplicate_audio_track",
severity: "warning",
- message: `Multiple audible <audio>/<video> elements on track ${a.trackIndex} overlap (${a.src} at ${a.start}-${Number.isFinite(a.end) ? a.end.toFixed(1) : "end"}s, ${b.src} at ${b.start}-${Number.isFinite(b.end) ? b.end.toFixed(1) : "end"}s). This causes layered audio playback.`,
+ message: `Multiple audible <audio>/<video> elements on track ${a.trackIndex} overlap (${a.src} at ${formatSeconds(a.start)}-${formatSeconds(a.end)}s, ${b.src} at ${formatSeconds(b.start)}-${formatSeconds(b.end)}s). This causes layered audio playback.`,
fixHint: "Use non-overlapping time windows or different track indices.",
});
}
diff --git a/packages/lint/src/utils.ts b/packages/lint/src/utils.ts
index 8718529230..4f6c289308 100644
--- a/packages/lint/src/utils.ts
+++ b/packages/lint/src/utils.ts
@@ -228,11 +228,14 @@ export function hasAttrName(tagSource: string, attr: string): boolean {
}
// An explicit data-has-audio is authoritative for the compiler; only the exact value "true" means audible.
+export function isAudibleVideo(attr: (name: string) => string | null): boolean {
+ if (attr("muted") !== null) return false;
+ const declared = attr("data-has-audio");
+ return declared === null || declared === "true";
+}
+
export function isAudibleVideoTag(tagSource: string): boolean {
- if (hasAttrName(tagSource, "muted")) return false;
- if (!hasAttrName(tagSource, "data-has-audio")) return true;
- const declared = readAttr(tagSource, "data-has-audio");
- return declared === "true";
+ return isAudibleVideo((name) => readDecodedAttr(tagSource, name));
}
export function mediaTimeWindow(tagSource: string): { start: number; end: number } | null {
diff --git a/packages/parsers/package-subpaths.json b/packages/parsers/package-subpaths.json
index 11ac5d3d6e..879bb703aa 100644
--- a/packages/parsers/package-subpaths.json
+++ b/packages/parsers/package-subpaths.json
@@ -134,6 +134,18 @@
"types": "./dist/timeSpans.d.ts",
"environments": ["browser", "bun", "node"]
},
+ "./media-timing": {
+ "source": "./src/mediaTiming.ts",
+ "runtime": "./dist/mediaTiming.js",
+ "types": "./dist/mediaTiming.d.ts",
+ "environments": ["browser", "bun", "node"]
+ },
+ "./reference-resolver": {
+ "source": "./src/referenceResolver.ts",
+ "runtime": "./dist/referenceResolver.js",
+ "types": "./dist/referenceResolver.d.ts",
+ "environments": ["browser", "bun", "node"]
+ },
"./composition-duration": {
"source": "./src/compositionDuration.ts",
"runtime": "./dist/compositionDuration.js",
diff --git a/packages/parsers/package.json b/packages/parsers/package.json
index 84eb7439a7..fe68043246 100644
--- a/packages/parsers/package.json
+++ b/packages/parsers/package.json
@@ -142,6 +142,18 @@
"import": "./src/timeSpans.ts",
"types": "./src/timeSpans.ts"
},
+ "./media-timing": {
+ "bun": "./src/mediaTiming.ts",
+ "node": "./dist/mediaTiming.js",
+ "import": "./src/mediaTiming.ts",
+ "types": "./src/mediaTiming.ts"
+ },
+ "./reference-resolver": {
+ "bun": "./src/referenceResolver.ts",
+ "node": "./dist/referenceResolver.js",
+ "import": "./src/referenceResolver.ts",
+ "types": "./src/referenceResolver.ts"
+ },
"./composition-duration": {
"bun": "./src/compositionDuration.ts",
"node": "./dist/compositionDuration.js",
@@ -237,6 +249,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"
diff --git a/packages/core/src/mediaTiming.test.ts b/packages/parsers/src/mediaTiming.test.ts
similarity index 92%
rename from packages/core/src/mediaTiming.test.ts
rename to packages/parsers/src/mediaTiming.test.ts
index ae2be88c16..f0b5e4608c 100644
--- a/packages/core/src/mediaTiming.test.ts
+++ b/packages/parsers/src/mediaTiming.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import { resolveMediaStartSeconds } from "./mediaTiming";
+import { resolveMediaStartSeconds } from "./mediaTiming.js";
const ordinary = () => 99;
const base = { authoredStart: 3, hostStart: 10, hasAutoStart: false, ordinaryStart: ordinary };
diff --git a/packages/parsers/src/mediaTiming.ts b/packages/parsers/src/mediaTiming.ts
new file mode 100644
index 0000000000..3a2125cc23
--- /dev/null
+++ b/packages/parsers/src/mediaTiming.ts
@@ -0,0 +1,81 @@
+import { readMediaOffsetSeconds } from "./mediaDuration.js";
+
+export const MEDIA_START_BASIS_ATTR = "data-hf-media-start-basis";
+
+export type MediaStartBasis = "local" | "global";
+
+export function readMediaStartBasis(value: string | null | undefined): MediaStartBasis {
+ return value?.trim().toLowerCase() === "global" ? "global" : "local";
+}
+
+// Nested media time is local by default; only an explicit compatibility marker keeps a root-global value.
+export function resolveAbsoluteMediaStartSeconds(input: {
+ authoredStart: number;
+ hostStart: number;
+ basis?: string | null;
+}): number {
+ return readMediaStartBasis(input.basis) === "global"
+ ? input.authoredStart
+ : input.hostStart + input.authoredStart;
+}
+
+/** 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. */
+export function resolveMediaStartSeconds(
+ input: MediaStartInput & { ordinaryStart: () => number },
+): number {
+ if (!hasLiteralNestedStart(input)) return input.ordinaryStart();
+ return resolveAbsoluteMediaStartSeconds({
+ authoredStart: input.authoredStart,
+ hostStart: input.hostStart,
+ basis: input.basis,
+ });
+}
+
+/** True when the authored start is already root time, so no host offset applies. */
+export function isRootGlobalMediaStart(input: MediaStartInput): boolean {
+ return hasLiteralNestedStart(input) && readMediaStartBasis(input.basis) === "global";
+}
+
+export interface MediaStartInput {
+ authoredStart: number | null;
+ hostStart: number;
+ hasAutoStart: boolean;
+ basis?: string | null;
+}
+
+function hasLiteralNestedStart(
+ input: MediaStartInput,
+): input is MediaStartInput & { authoredStart: number } {
+ return !input.hasAutoStart && input.authoredStart != null && input.hostStart !== 0;
+}
+
+/** A composition host's in-point; only a host with one shifts or cuts what it holds. */
+export function hostInPointSeconds(host: Pick<Element, "getAttribute">): number {
+ return readMediaOffsetSeconds((name) => host.getAttribute(name));
+}
+
+/** Main-timeline time of a sub-composition's local t=0: its host's start minus its in-point. */
+export function compositionOriginSeconds(
+ hostStart: number,
+ host: Pick<Element, "getAttribute">,
+): number {
+ return hostStart - hostInPointSeconds(host);
+}
+
+export interface HostSlot {
+ start: number;
+ end: number;
+}
+
+/** Each in-point host cuts the span to its own window. */
+export function cutToHostSlots(
+ span: { start: number; end: number },
+ hosts: readonly HostSlot[],
+): { start: number; end: number } {
+ 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);
+}
diff --git a/packages/parsers/src/referenceResolver.ts b/packages/parsers/src/referenceResolver.ts
new file mode 100644
index 0000000000..6679ed0bc5
--- /dev/null
+++ b/packages/parsers/src/referenceResolver.ts
@@ -0,0 +1,77 @@
+// Static resolver for relative `data-start` references (`data-start="intro"`), mirroring the runtime's
+// startResolver so lint, render and `timeline` agree on when a referenced clip starts.
+
+import { parseNumeric, parseStartExpression } from "./compositionContract.js";
+
+/** Minimal structural DOM shape the reference resolver needs. */
+export interface RefResolverEl {
+ getAttribute(name: string): string | null;
+}
+export interface RefResolverDoc {
+ getElementById(id: string): RefResolverEl | null;
+ querySelector(selector: string): RefResolverEl | null;
+}
+
+// By `id`, then `data-composition-id`. The reference grammar allows only `[A-Za-z0-9_.:-]`, so no CSS.escape.
+function findReferenceTargetEl(doc: RefResolverDoc, refId: string): RefResolverEl | null {
+ return doc.getElementById(refId) ?? doc.querySelector(`[data-composition-id="${refId}"]`);
+}
+
+// Natural media length is unknown here, so as in the runtime an unknown-length target
+// resolves to its start and an unknown target to 0, never NaN.
+export function resolveReferencedStart(
+ doc: RefResolverDoc,
+ el: RefResolverEl,
+ startCache: Map<RefResolverEl, number>,
+ visiting: Set<RefResolverEl>,
+): number {
+ const cached = startCache.get(el);
+ if (cached !== undefined) return cached;
+ if (visiting.has(el)) return 0; // cycle guard (A -> B -> A)
+ 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);
+ }
+}
+
+/** From `data-duration` or `data-end - start`; null when only the media's own length would settle it. */
+export function resolveReferencedDuration(
+ doc: RefResolverDoc,
+ el: RefResolverEl,
+ startCache: Map<RefResolverEl, number>,
+ visiting: Set<RefResolverEl>,
+): number | null {
+ 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;
+}
diff --git a/packages/parsers/tsup.config.ts b/packages/parsers/tsup.config.ts
index e8145a2f39..75bd2cf17f 100644
--- a/packages/parsers/tsup.config.ts
+++ b/packages/parsers/tsup.config.ts
@@ -24,6 +24,8 @@ export default defineConfig({
assetResolution: "src/assetResolution.ts",
htmlAttributeSpans: "src/htmlAttributeSpans.ts",
timeSpans: "src/timeSpans.ts",
+ mediaTiming: "src/mediaTiming.ts",
+ referenceResolver: "src/referenceResolver.ts",
},
format: ["esm"],
outDir: "dist",