Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): HyperframeLintFindingreturn 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[]): HyperframeLintFindfindings.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.tsindex 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.jsonindex 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.jsonindex 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.tssimilarity index 92%rename from packages/core/src/mediaTiming.test.tsrename to packages/parsers/src/mediaTiming.test.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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",