mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* fix(core): a composition behind a wrapper takes its host's start Fixes #4334. * fix(core): a composition inside a timed wrapper starts with the wrapper The nearest host or timed wrapper above a mounted root sets its start, so its clock starts when the wrapper shows it, matching how CSS animations already pick their clip. * test(producer): re-pin the test classification digest
232 lines
9.8 KiB
TypeScript
232 lines
9.8 KiB
TypeScript
import type { RuntimeTimelineLike } from "./types";
|
|
import { readTimelineDurationSeconds } from "./timelineDuration";
|
|
import { resolveAuthoredTimingWindow } from "./authoredTiming";
|
|
// Straight from playbackRate, not through media.ts's re-export: media.ts
|
|
// imports mediaVolumeEnvelope, which needs this resolver, and the round trip
|
|
// would be an import cycle.
|
|
import {
|
|
parseStrictFiniteTimingNumber,
|
|
resolveNaturalMediaTimelineDuration,
|
|
resolveTimedImageDurationSeconds,
|
|
} from "./playbackRate";
|
|
import { isMediaElement } from "./domRealm";
|
|
import { parseStartExpression } from "./startExpression";
|
|
import {
|
|
compositionOriginSeconds,
|
|
hostInPointSeconds,
|
|
type HostSlot,
|
|
isRootGlobalMediaStart,
|
|
MEDIA_START_BASIS_ATTR,
|
|
resolveMediaStartSeconds,
|
|
type MediaStartInput,
|
|
} from "../mediaTiming";
|
|
|
|
export function createRuntimeStartTimeResolver(params: {
|
|
timelineRegistry?: Record<string, Pick<RuntimeTimelineLike, "duration"> | undefined>;
|
|
includeAuthoredTimingAttrs?: boolean;
|
|
/**
|
|
* The document that reference lookups (`data-start="intro + 2"`) resolve
|
|
* against. Defaults to the global `document` — the runtime bundle's own
|
|
* realm. Hosts driving a composition in an IFRAME must pass that iframe's
|
|
* document, or every reference silently resolves against the host page.
|
|
*/
|
|
documentRef?: Document;
|
|
}): {
|
|
resolveStartForElement: (element: Element, fallback?: number) => number;
|
|
resolveDurationForElement: (element: Element) => number | null;
|
|
resolveMediaStartForElement: (element: Element) => number;
|
|
resolveHostStartForElement: (element: Element) => number;
|
|
resolveHostSlotsForElement: (element: Element) => HostSlot[];
|
|
isRootGlobalMediaStartForElement: (element: Element) => boolean;
|
|
} {
|
|
const timelineRegistry = params.timelineRegistry ?? {};
|
|
const includeAuthoredTimingAttrs = params.includeAuthoredTimingAttrs ?? false;
|
|
const doc = params.documentRef ?? document;
|
|
const startCache = new WeakMap<Element, number | null>();
|
|
const durationCache = new WeakMap<Element, number | null>();
|
|
const visiting = new Set<Element>();
|
|
|
|
const compositionScopeOf = (element: Element): Element | null =>
|
|
(element.hasAttribute("data-composition-id") ? element.parentElement : element)?.closest(
|
|
"[data-composition-id]",
|
|
) ?? null;
|
|
|
|
const findReferenceTarget = (refId: string, from: Element): Element | null => {
|
|
const scope = compositionScopeOf(from);
|
|
if (scope) {
|
|
for (const candidate of scope.querySelectorAll(`[id="${refId}"]`)) {
|
|
if (compositionScopeOf(candidate) === scope) return candidate;
|
|
}
|
|
}
|
|
const byId = doc.getElementById(refId);
|
|
if (byId) return byId;
|
|
return (
|
|
Array.from(doc.querySelectorAll("[data-composition-id]")).find(
|
|
(element) => element.getAttribute("data-composition-id") === refId,
|
|
) ?? null
|
|
);
|
|
};
|
|
|
|
const authoredAttr = (element: Element, name: string) =>
|
|
includeAuthoredTimingAttrs ? element.getAttribute(name) : null;
|
|
|
|
const resolveAuthoredDuration = (element: Element): number | null =>
|
|
resolveAuthoredTimingWindow({
|
|
start: 0,
|
|
duration: element.getAttribute("data-duration"),
|
|
authoredDuration: authoredAttr(element, "data-hf-authored-duration"),
|
|
})?.duration ??
|
|
resolveAuthoredTimingWindow({
|
|
start: resolveStartForElementInternal(element, 0),
|
|
end: element.getAttribute("data-end"),
|
|
authoredEnd: authoredAttr(element, "data-hf-authored-end"),
|
|
})?.duration ??
|
|
null;
|
|
|
|
const positive = (value: number | null | undefined): number | null =>
|
|
value != null && Number.isFinite(value) && value > 0 ? value : null;
|
|
|
|
const resolveRegisteredTimelineDuration = (element: Element): number | null => {
|
|
const compositionId = element.getAttribute("data-composition-id");
|
|
return compositionId
|
|
? positive(readTimelineDurationSeconds(timelineRegistry[compositionId]))
|
|
: null;
|
|
};
|
|
|
|
const resolveDurationForElement = (element: Element): number | null => {
|
|
const cached = durationCache.get(element);
|
|
if (cached !== undefined) return cached;
|
|
const resolved =
|
|
resolveAuthoredDuration(element) ??
|
|
positive(
|
|
isMediaElement(element)
|
|
? resolveNaturalMediaTimelineDuration(element, element.duration)
|
|
: null,
|
|
) ??
|
|
positive(resolveTimedImageDurationSeconds(element)) ??
|
|
resolveRegisteredTimelineDuration(element);
|
|
durationCache.set(element, resolved);
|
|
return resolved;
|
|
};
|
|
|
|
const COMPOSITION_HOST_SELECTOR =
|
|
"[data-composition-src], [data-composition-id], [data-composition-file]";
|
|
const isCompositionHost = (element: Element): boolean =>
|
|
element.matches(COMPOSITION_HOST_SELECTOR);
|
|
|
|
// A mounted composition root without its own `data-start` takes its timing from the nearest host
|
|
// or timed wrapper above it, the clip that shows it; the host may use another id than the file.
|
|
const inheritedTimingHost = (element: Element): Element | null => {
|
|
if (!element.hasAttribute("data-composition-id")) return null;
|
|
if (parseStartExpression(element.getAttribute("data-start"))) return null;
|
|
return element.parentElement?.closest(`[data-start], ${COMPOSITION_HOST_SELECTOR}`) ?? null;
|
|
};
|
|
|
|
const resolveCompositionOrigin = (compositionRoot: Element, fallback: number): number =>
|
|
compositionOriginSeconds(
|
|
resolveStartForElementInternal(compositionRoot, fallback),
|
|
inheritedTimingHost(compositionRoot) ?? compositionRoot,
|
|
);
|
|
|
|
const resolveHostOffsetForElement = (element: Element, fallback: number): number => {
|
|
const compositionRoot = element.hasAttribute("data-composition-id")
|
|
? element.parentElement?.closest("[data-composition-id]")
|
|
: element.closest("[data-composition-id]");
|
|
return compositionRoot ? resolveCompositionOrigin(compositionRoot, fallback) : 0;
|
|
};
|
|
|
|
const computeStart = (element: Element, fallback: number): number => {
|
|
const expression = parseStartExpression(element.getAttribute("data-start"));
|
|
if (!expression) {
|
|
const host = inheritedTimingHost(element);
|
|
return host ? resolveStartForElementInternal(host, fallback) : fallback;
|
|
}
|
|
if (expression.kind === "absolute") {
|
|
// Negative when a host's in-point is past its start; the host's slot cuts that part.
|
|
return resolveHostOffsetForElement(element, fallback) + Math.max(0, expression.value);
|
|
}
|
|
const target = findReferenceTarget(expression.refId, element);
|
|
if (!target) return fallback;
|
|
const targetStart = resolveStartForElementInternal(target, 0);
|
|
const targetDuration = resolveDurationForElement(target) ?? 0;
|
|
// Clamped at local 0, as a numeric start is, once an in-point puts local 0 before 0.
|
|
const floor = Math.min(0, resolveHostOffsetForElement(element, 0));
|
|
return Math.max(floor, targetStart + targetDuration + expression.offset);
|
|
};
|
|
|
|
const resolveStartForElementInternal = (element: Element, fallback: number): number => {
|
|
const cached = startCache.get(element);
|
|
if (cached !== undefined) {
|
|
return cached == null ? fallback : cached;
|
|
}
|
|
if (visiting.has(element)) {
|
|
return fallback;
|
|
}
|
|
visiting.add(element);
|
|
try {
|
|
const resolved = computeStart(element, fallback);
|
|
startCache.set(element, resolved);
|
|
return resolved;
|
|
} finally {
|
|
visiting.delete(element);
|
|
}
|
|
};
|
|
|
|
/**
|
|
* The ONE owner of "when does this media element start on the root timeline".
|
|
*
|
|
* A media element is not a plain timed clip: `data-hf-media-start-basis`
|
|
* decides whether its `data-start` is composition-local (the default, so the
|
|
* host offset is added) or a legacy root-global timestamp (already absolute,
|
|
* so adding the host offset double-counts it). Anything that derives a media
|
|
* start from attributes — the clip manifest, the visibility pass, the media
|
|
* cache, WebAudio scheduling — must come through here, or the timeline the
|
|
* editor draws stops matching the timeline that plays.
|
|
*/
|
|
const mediaStartInput = (element: Element): MediaStartInput => {
|
|
const compositionRoot = element.closest("[data-composition-id]");
|
|
return {
|
|
authoredStart: parseStrictFiniteTimingNumber(element.getAttribute("data-start")),
|
|
hostStart: compositionRoot ? resolveCompositionOrigin(compositionRoot, 0) : 0,
|
|
hasAutoStart: element.hasAttribute("data-hf-auto-start"),
|
|
basis: element.getAttribute(MEDIA_START_BASIS_ATTR),
|
|
};
|
|
};
|
|
|
|
const resolveMediaStartForElement = (element: Element): number => {
|
|
const input = mediaStartInput(element);
|
|
return resolveMediaStartSeconds({
|
|
...input,
|
|
ordinaryStart: () => resolveStartForElementInternal(element, input.hostStart),
|
|
});
|
|
};
|
|
|
|
// Hosts with an in-point, found by their composition attributes so an anonymous one counts too.
|
|
const resolveHostSlotsForElement = (element: Element): HostSlot[] => {
|
|
const slots: HostSlot[] = [];
|
|
for (let node = element.parentElement; node; node = node.parentElement) {
|
|
if (!isCompositionHost(node) || inheritedTimingHost(node)) continue;
|
|
if (hostInPointSeconds(node) <= 0) continue;
|
|
const start = resolveStartForElementInternal(node, 0);
|
|
const duration = resolveAuthoredDuration(node);
|
|
slots.push({ start, end: duration ? start + duration : Infinity });
|
|
}
|
|
return slots;
|
|
};
|
|
|
|
const isRootGlobalMediaStartForElement = (element: Element): boolean =>
|
|
isMediaElement(element) && isRootGlobalMediaStart(mediaStartInput(element));
|
|
|
|
return {
|
|
resolveStartForElement: (element: Element, fallback = 0) =>
|
|
resolveStartForElementInternal(element, Math.max(0, fallback)),
|
|
resolveDurationForElement: (element: Element) => resolveDurationForElement(element),
|
|
resolveMediaStartForElement,
|
|
resolveHostStartForElement: (element: Element) => resolveHostOffsetForElement(element, 0),
|
|
resolveHostSlotsForElement,
|
|
isRootGlobalMediaStartForElement,
|
|
};
|
|
}
|
|
|
|
export type { RuntimeTimelineLike } from "./types";
|