mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 14:27:26 +00:00
576 lines
22 KiB
TypeScript
576 lines
22 KiB
TypeScript
/**
|
|
* Low-level helpers for building and identifying TimelineElement objects.
|
|
*
|
|
* Covers: duration reading, media-element metadata extraction, selector/key/
|
|
* identity builders, and DOM node lookup. These are
|
|
* intentionally dependency-free (no store, no hooks) so they can be used in
|
|
* both the React hook and test environments.
|
|
*/
|
|
|
|
import type { TimelineElement } from "../store/playerStore";
|
|
import type { ClipManifestClip } from "./playbackTypes";
|
|
import { isFinitePositive } from "./playbackAdapter";
|
|
import { getSourceScopedSelectorIndex } from "../../utils/sourceScopedSelectorIndex";
|
|
import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
|
|
import { readElementFades } from "@hyperframes/core/audio-fade";
|
|
import {
|
|
type AttrReader,
|
|
clampPlaybackRate,
|
|
readMediaOffsetSeconds,
|
|
} from "@hyperframes/parsers/media-duration";
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Layer-reveal lift transparency
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Attributes carrying the pre-lift state of a Layers-panel selection reveal
|
|
* (useLayerRevealOverride): while a layer is selected it PAINTS on top via a
|
|
* temporary inline z-index, but the lift is a purely visual, ephemeral studio
|
|
* affordance — every z reader must keep reporting the element's TRUE z
|
|
* (stored here) so menus, badges, the lane mirror, and the panel sort never
|
|
* reason on the lifted value. A z-reorder commit removes the attributes (the
|
|
* commit is the new truth).
|
|
*/
|
|
export const LAYER_REVEAL_PRIOR_Z_ATTR = "data-hf-reveal-prior-z";
|
|
export const LAYER_REVEAL_PRIOR_POSITION_ATTR = "data-hf-reveal-prior-pos";
|
|
|
|
/** The lifted element's true (pre-lift) z, or null when no lift is active. */
|
|
export function readLayerRevealPriorZ(el: Element): number | null {
|
|
const raw = el.getAttribute(LAYER_REVEAL_PRIOR_Z_ATTR);
|
|
if (raw == null) return null;
|
|
const n = Number.parseInt(raw, 10);
|
|
return Number.isFinite(n) ? n : null;
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Duration attribute helpers
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Read a host element's effective CSS stacking order for the timeline's reverse
|
|
* z→lane mapping. Prefers the inline `style.zIndex` (what the canvas context
|
|
* menu and LayersPanel z-edits write via handleDomZIndexReorderCommit), falls
|
|
* back to computed style; "auto" / empty / unparseable ⇒ 0. Works with a
|
|
* detached parse Document (no defaultView) as well as a live iframe. Mirrors
|
|
* canvasContextMenuZOrder.parseZIndex semantics so the two directions agree.
|
|
* Reveal-lift transparent: an active lift reports the stored TRUE z.
|
|
*/
|
|
export function readTimelineElementZIndex(el: Element): number {
|
|
const prior = readLayerRevealPriorZ(el);
|
|
if (prior != null) return prior;
|
|
const html = el as HTMLElement;
|
|
const parseZ = (value: string | null | undefined): number | null => {
|
|
if (value == null || value === "" || value === "auto") return null;
|
|
const n = Number.parseInt(value, 10);
|
|
return Number.isFinite(n) ? n : null;
|
|
};
|
|
const fromInline = parseZ(html.style?.zIndex);
|
|
if (fromInline != null) return fromInline;
|
|
const view = el.ownerDocument?.defaultView;
|
|
if (view?.getComputedStyle) {
|
|
const fromComputed = parseZ(view.getComputedStyle(html).zIndex);
|
|
if (fromComputed != null) return fromComputed;
|
|
}
|
|
return 0;
|
|
}
|
|
|
|
function readDurationAttribute(el: Element | null | undefined): number {
|
|
if (!el) return 0;
|
|
const duration =
|
|
Number.parseFloat(el.getAttribute("data-duration") ?? "") ||
|
|
Number.parseFloat(el.getAttribute("data-hf-authored-duration") ?? "");
|
|
return isFinitePositive(duration) ? duration : 0;
|
|
}
|
|
|
|
export function isTimelineIgnoredElement(el: Element): boolean {
|
|
// An `<hf-audio-group>` is a mixer bus with no timing of its own, drawn as a group row, never a clip.
|
|
if (el.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG) return true;
|
|
return Boolean(
|
|
el.closest(
|
|
[
|
|
"[data-hyperframes-ignore]",
|
|
"[data-hyperframes-picker-ignore]",
|
|
"[data-hf-ignore]",
|
|
"[data-hf-color-grading-canvas]",
|
|
].join(","),
|
|
),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Furthest clip end (start + RAW `data-duration`) over every non-root clip in the
|
|
* document. Reads the authored attribute, NOT any runtime-computed value — so it
|
|
* is immune to the runtime's clamp that truncates a clip's live duration to the
|
|
* composition length. This is the source of truth for content-driven duration:
|
|
* computing it from the store instead would feed the truncated value back in and
|
|
* make the composition length ratchet down (research HANDOFF-3 §6.1 feedback loop).
|
|
*/
|
|
export function furthestClipEndFromDocument(doc: Document | null | undefined): number {
|
|
if (!doc) return 0;
|
|
const root = doc.querySelector("[data-composition-id]");
|
|
let maxEnd = 0;
|
|
for (const node of Array.from(doc.querySelectorAll("[data-start]"))) {
|
|
if (node === root || isTimelineIgnoredElement(node)) continue;
|
|
const start = Number.parseFloat(node.getAttribute("data-start") ?? "");
|
|
const duration = readDurationAttribute(node);
|
|
if (!Number.isFinite(start) || start < 0 || duration <= 0) continue;
|
|
maxEnd = Math.max(maxEnd, start + duration);
|
|
}
|
|
return maxEnd;
|
|
}
|
|
|
|
export function readTimelineDurationFromDocument(doc: Document | null | undefined): number {
|
|
if (!doc) return 0;
|
|
const rootDuration = readDurationAttribute(doc.querySelector("[data-composition-id]"));
|
|
if (rootDuration > 0) return rootDuration;
|
|
return furthestClipEndFromDocument(doc);
|
|
}
|
|
|
|
/**
|
|
* Furthest clip end parsed straight from a composition SOURCE STRING (the HTML
|
|
* being saved). Uses raw `data-duration`, so it is the correct input for syncing
|
|
* the root duration after an edit — reading the store instead would use the
|
|
* runtime-truncated durations and shrink the composition (the feedback loop).
|
|
*/
|
|
export function furthestClipEndFromSource(source: string): number {
|
|
if (!source) return 0;
|
|
return furthestClipEndFromDocument(new DOMParser().parseFromString(source, "text/html"));
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// DOM element type guards
|
|
// ---------------------------------------------------------------------------
|
|
|
|
function isHtmlElement(el: Element): el is HTMLElement {
|
|
const HtmlElementCtor = el.ownerDocument.defaultView?.HTMLElement ?? globalThis.HTMLElement;
|
|
return typeof HtmlElementCtor !== "undefined" && el instanceof HtmlElementCtor;
|
|
}
|
|
|
|
function isCompositionHost(el: Element): boolean {
|
|
return (
|
|
el.hasAttribute("data-composition-id") ||
|
|
el.hasAttribute("data-composition-src") ||
|
|
el.hasAttribute("data-composition-file")
|
|
);
|
|
}
|
|
|
|
export function resolveMediaElement(el: Element): HTMLMediaElement | HTMLImageElement | null {
|
|
const win = el.ownerDocument.defaultView ?? window;
|
|
const MediaElementCtor = win.HTMLMediaElement ?? globalThis.HTMLMediaElement;
|
|
const ImageElementCtor = win.HTMLImageElement ?? globalThis.HTMLImageElement;
|
|
if (el instanceof MediaElementCtor || el instanceof ImageElementCtor) return el;
|
|
// A composition's media belongs to its own timeline, not the clip's: its length would cap a trim.
|
|
if (isCompositionHost(el)) return null;
|
|
const candidate = el.querySelector("video, audio, img");
|
|
return candidate instanceof MediaElementCtor || candidate instanceof ImageElementCtor
|
|
? candidate
|
|
: null;
|
|
}
|
|
|
|
/** The in-point as playback reads it, and the attribute holding it; empty when neither is authored. */
|
|
export function readPlaybackStartAttributes(
|
|
getAttr: AttrReader,
|
|
): Pick<TimelineElement, "playbackStart" | "playbackStartAttr"> {
|
|
const playbackStartAttr =
|
|
getAttr("data-playback-start") != null
|
|
? "playback-start"
|
|
: getAttr("data-media-start") != null
|
|
? "media-start"
|
|
: undefined;
|
|
return playbackStartAttr
|
|
? { playbackStart: readMediaOffsetSeconds(getAttr), playbackStartAttr }
|
|
: {};
|
|
}
|
|
|
|
export function playbackStartAttributeForElement(
|
|
element: Pick<TimelineElement, "kind" | "playbackStartAttr">,
|
|
): "data-media-start" | "data-playback-start" {
|
|
return element.playbackStartAttr === "playback-start" || element.kind === "composition"
|
|
? "data-playback-start"
|
|
: "data-media-start";
|
|
}
|
|
|
|
function applyPlaybackMetadataFromElement(entry: TimelineElement, el: Element): void {
|
|
Object.assign(
|
|
entry,
|
|
readPlaybackStartAttributes((n) => el.getAttribute(n)),
|
|
);
|
|
|
|
const authoredPlaybackRate = Number.parseFloat(el.getAttribute("data-playback-rate") ?? "");
|
|
if (Number.isFinite(authoredPlaybackRate) && authoredPlaybackRate > 0) {
|
|
entry.playbackRate = clampPlaybackRate(authoredPlaybackRate);
|
|
}
|
|
}
|
|
|
|
/** Sets or clears an optional field, so a re-parse after the attribute is removed drops it. */
|
|
function setOptional<K extends keyof TimelineElement>(
|
|
entry: TimelineElement,
|
|
key: K,
|
|
value: TimelineElement[K] | undefined,
|
|
): void {
|
|
if (value === undefined) delete entry[key];
|
|
else entry[key] = value;
|
|
}
|
|
|
|
function readVolume(el: Element, media: Element): number | undefined {
|
|
const volume = Number.parseFloat(
|
|
el.getAttribute("data-volume") ?? media.getAttribute("data-volume") ?? "",
|
|
);
|
|
return Number.isFinite(volume) ? volume : undefined;
|
|
}
|
|
|
|
/** What the mixer gets: the compiler's `data-has-audio` rule, muted and volume. */
|
|
function applyAudioMetadataFromElement(entry: TimelineElement, el: Element): void {
|
|
const media = resolveMediaElement(el) ?? el;
|
|
const muted = el.hasAttribute("muted") || media.hasAttribute("muted");
|
|
const hasAudio = el.getAttribute("data-has-audio");
|
|
const sound = hasAudio === null ? el.tagName === "VIDEO" && !muted : hasAudio === "true";
|
|
setOptional(entry, "hasAudio", sound ? true : undefined);
|
|
setOptional(entry, "muted", muted ? true : undefined);
|
|
setOptional(entry, "volume", readVolume(el, media));
|
|
}
|
|
|
|
function applyFadeMetadataFromElement(entry: TimelineElement, el: Element): void {
|
|
const fades = readElementFades(el);
|
|
setOptional(entry, "fadeIn", fades.fadeIn > 0 ? fades.fadeIn : undefined);
|
|
setOptional(entry, "fadeOut", fades.fadeOut > 0 ? fades.fadeOut : undefined);
|
|
}
|
|
|
|
export function applyMediaMetadataFromElement(entry: TimelineElement, el: Element): void {
|
|
applyPlaybackMetadataFromElement(entry, el);
|
|
applyAudioMetadataFromElement(entry, el);
|
|
applyFadeMetadataFromElement(entry, el);
|
|
|
|
const mediaEl = resolveMediaElement(el);
|
|
if (!mediaEl) return;
|
|
|
|
entry.tag = mediaEl.tagName.toLowerCase();
|
|
const src = mediaEl.getAttribute("src");
|
|
if (src) entry.src = src;
|
|
|
|
const win = mediaEl.ownerDocument.defaultView ?? window;
|
|
const MediaElementCtor = win.HTMLMediaElement ?? globalThis.HTMLMediaElement;
|
|
if (typeof MediaElementCtor === "undefined" || !(mediaEl instanceof MediaElementCtor)) return;
|
|
|
|
const sourceDurationAttr =
|
|
el.getAttribute("data-source-duration") ?? mediaEl.getAttribute("data-source-duration");
|
|
const sourceDuration = sourceDurationAttr ? parseFloat(sourceDurationAttr) : mediaEl.duration;
|
|
if (Number.isFinite(sourceDuration) && sourceDuration > 0) {
|
|
entry.sourceDuration = sourceDuration;
|
|
}
|
|
|
|
const playbackRate = mediaEl.defaultPlaybackRate;
|
|
if (entry.playbackRate == null && Number.isFinite(playbackRate) && playbackRate > 0) {
|
|
entry.playbackRate = clampPlaybackRate(playbackRate);
|
|
}
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Label helpers
|
|
// ---------------------------------------------------------------------------
|
|
|
|
export function getTimelineElementDisplayLabel(input: {
|
|
id?: string | null;
|
|
label?: string | null;
|
|
tag?: string | null;
|
|
}): string {
|
|
const label = input.label?.trim();
|
|
if (label) return label;
|
|
const id = input.id?.trim();
|
|
if (id) return id;
|
|
const tag = input.tag?.trim().toLowerCase();
|
|
return tag ? `${tag} clip` : "Timeline clip";
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Selector / identity / key builders
|
|
// ---------------------------------------------------------------------------
|
|
|
|
export function getTimelineElementSelector(el: Element): string | undefined {
|
|
if (isHtmlElement(el) && el.id) return `#${CSS.escape(el.id)}`;
|
|
const compId = el.getAttribute("data-composition-id");
|
|
if (compId) return `[data-composition-id="${CSS.escape(compId)}"]`;
|
|
if (isHtmlElement(el)) {
|
|
const classes = el.className.split(/\s+/).filter(Boolean);
|
|
const firstClass = classes.find((className) => className !== "clip") ?? classes[0];
|
|
if (firstClass) return `.${CSS.escape(firstClass)}`;
|
|
}
|
|
return undefined;
|
|
}
|
|
|
|
export function getTimelineElementSourceFile(el: Element): string | undefined {
|
|
const ownerRoot = el.parentElement?.closest("[data-composition-id]");
|
|
return (
|
|
ownerRoot?.getAttribute("data-composition-file") ??
|
|
ownerRoot?.getAttribute("data-composition-src") ??
|
|
undefined
|
|
);
|
|
}
|
|
|
|
export function getTimelineElementSelectorIndex(
|
|
doc: Document,
|
|
el: Element,
|
|
selector: string | undefined,
|
|
): number | undefined {
|
|
return getSourceScopedSelectorIndex(
|
|
doc,
|
|
el,
|
|
selector,
|
|
getTimelineElementSourceFile(el),
|
|
getTimelineElementSourceFile,
|
|
);
|
|
}
|
|
|
|
export function buildTimelineElementKey(params: {
|
|
id: string;
|
|
fallbackIndex: number;
|
|
domId?: string;
|
|
selector?: string;
|
|
selectorIndex?: number;
|
|
sourceFile?: string;
|
|
}): string {
|
|
const scope = params.sourceFile ?? "index.html";
|
|
if (params.domId) return `${scope}#${params.domId}`;
|
|
if (params.selector) return `${scope}:${params.selector}:${params.selectorIndex ?? 0}`;
|
|
return `${scope}:${params.id}:${params.fallbackIndex}`;
|
|
}
|
|
|
|
/**
|
|
* Inverse of {@link buildTimelineElementKey} for the `sourceFile#domId` form.
|
|
* A key with no `#` is a bare dom id and carries no source file of its own, so
|
|
* the caller supplies the scope it wants to look that id up in.
|
|
*/
|
|
export function splitTimelineElementKey(key: string): {
|
|
sourceFile: string | null;
|
|
domId: string;
|
|
} {
|
|
const hashIndex = key.lastIndexOf("#");
|
|
if (hashIndex < 0) return { sourceFile: null, domId: key };
|
|
return { sourceFile: key.slice(0, hashIndex), domId: key.slice(hashIndex + 1) };
|
|
}
|
|
|
|
export function buildTimelineElementIdentity(params: {
|
|
preferredId?: string | null;
|
|
label: string;
|
|
fallbackIndex: number;
|
|
domId?: string;
|
|
selector?: string;
|
|
selectorIndex?: number;
|
|
sourceFile?: string;
|
|
}): { id: string; key: string } {
|
|
const id =
|
|
params.preferredId?.trim() ||
|
|
buildTimelineElementKey({
|
|
id: params.label,
|
|
fallbackIndex: params.fallbackIndex,
|
|
domId: params.domId,
|
|
selector: params.selector,
|
|
selectorIndex: params.selectorIndex,
|
|
sourceFile: params.sourceFile,
|
|
});
|
|
const key = buildTimelineElementKey({
|
|
id,
|
|
fallbackIndex: params.fallbackIndex,
|
|
domId: params.domId,
|
|
selector: params.selector,
|
|
selectorIndex: params.selectorIndex,
|
|
sourceFile: params.sourceFile,
|
|
});
|
|
return { id, key };
|
|
}
|
|
|
|
export function getTimelineElementIdentity(element: { key?: string | null; id: string }): string {
|
|
return element.key ?? element.id;
|
|
}
|
|
|
|
/**
|
|
* The id space the RUNTIME matches on — a bare DOM id, never a store key.
|
|
*
|
|
* Studio addresses rows by `buildTimelineElementKey`'s composite
|
|
* `<sourceFile>#<domId>`, but everything audio in `@hyperframes/core` keys off
|
|
* the live document: `resolveAudioGroups` collects `member.id`,
|
|
* `resolveCarveSourceIds` goes through `getElementById`. Anything crossing into
|
|
* that space — a group membership list, a carve source — has to be
|
|
* converted here first; a composite key silently matches nothing.
|
|
*
|
|
* `null` for a row with no DOM id at all (selector-addressed elements): such an
|
|
* element cannot be grouped, because `resolveAudioGroups` skips
|
|
* members without an `id` and would build a group that is half there.
|
|
*/
|
|
export function runtimeAudioId(element: { domId?: string | null }): string | null {
|
|
return element.domId || null;
|
|
}
|
|
|
|
/**
|
|
* Timeline store key for a z-reorder entry built OUTSIDE the timeline
|
|
* expansion (canvas context menu / LayersPanel), so the reorder commit can
|
|
* update the store's zIndex synchronously. Matches buildTimelineElementKey's
|
|
* stable branches (`sourceFile#domId`, else the selector-based key). Undefined
|
|
* when the element has neither a DOM id nor a selector — the timeline's
|
|
* fallback branch needs its own fallbackIndex, which these callers don't have,
|
|
* so such an entry simply skips the synchronous store update.
|
|
*/
|
|
export function deriveTimelineStoreKey(params: {
|
|
domId?: string;
|
|
selector?: string;
|
|
selectorIndex?: number;
|
|
sourceFile?: string;
|
|
}): string | undefined {
|
|
if (!params.domId && !params.selector) return undefined;
|
|
return buildTimelineElementKey({ id: "", fallbackIndex: 0, ...params });
|
|
}
|
|
|
|
/**
|
|
* {@link deriveTimelineStoreKey} for a caller that already has a DOM id in
|
|
* hand (e.g. one it just minted), so the undefined branch never applies.
|
|
*/
|
|
export function deriveTimelineStoreKeyForDomId(domId: string, sourceFile?: string): string {
|
|
return deriveTimelineStoreKey({ domId, sourceFile })!;
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// DOM node querying
|
|
// ---------------------------------------------------------------------------
|
|
|
|
function getTimelineDomNodes(doc: Document): Element[] {
|
|
const rootComp = doc.querySelector("[data-composition-id]");
|
|
return Array.from(doc.querySelectorAll("[data-start]")).filter(
|
|
(node) => node !== rootComp && !isTimelineIgnoredElement(node),
|
|
);
|
|
}
|
|
|
|
function numbersNearlyEqual(a: number, b: number): boolean {
|
|
return Math.abs(a - b) < 0.001;
|
|
}
|
|
|
|
const MANIFEST_CLIP_ATTRS: ReadonlyArray<[string, (clip: ClipManifestClip) => number]> = [
|
|
["data-start", (clip) => clip.start],
|
|
["data-duration", (clip) => clip.duration],
|
|
["data-track-index", (clip) => clip.track],
|
|
];
|
|
|
|
function nodeMatchesClipTag(node: Element, clip: ClipManifestClip): boolean {
|
|
return !clip.tagName || node.tagName.toLowerCase() === clip.tagName.toLowerCase();
|
|
}
|
|
|
|
function nodeMatchesManifestClip(node: Element, clip: ClipManifestClip): boolean {
|
|
if (!nodeMatchesClipTag(node, clip)) return false;
|
|
// An attribute only constrains the match when it parses to a finite number:
|
|
// missing or garbled reads as "unknown", not "mismatch".
|
|
return MANIFEST_CLIP_ATTRS.every(([attr, expected]) => {
|
|
const actual = Number.parseFloat(node.getAttribute(attr) ?? "");
|
|
return !Number.isFinite(actual) || numbersNearlyEqual(actual, expected(clip));
|
|
});
|
|
}
|
|
|
|
/** Whether `node` sits in the composition the clip was read from, the chain the runtime records outermost first
|
|
* (`resolveNearestCompositionContext` in core's runtime/timeline.ts). A clip without that scope accepts any node. */
|
|
function nodeInClipScope(node: Element, clip: ClipManifestClip): boolean {
|
|
const scope = clip.compositionAncestors;
|
|
if (!scope) return true;
|
|
const ids: string[] = [];
|
|
for (let cursor = node.parentElement; cursor; cursor = cursor.parentElement) {
|
|
const id = cursor.getAttribute("data-composition-id");
|
|
if (id) ids.unshift(id);
|
|
}
|
|
return ids.length === scope.length && ids.every((id, index) => id === scope[index]);
|
|
}
|
|
|
|
/** The first match in the clip's composition across `selectors`; a lone match stands only when none is in scope, as a
|
|
* healed host can stale the clip's chain for a pass. An id can repeat in a sub-composition earlier in the document. */
|
|
function findInClipScope(
|
|
doc: Document,
|
|
clip: ClipManifestClip,
|
|
selectors: string[],
|
|
): Element | null {
|
|
let lone: Element | null = null;
|
|
for (const selector of selectors) {
|
|
const nodes = Array.from(doc.querySelectorAll(selector));
|
|
const scoped = nodes.find((node) => nodeInClipScope(node, clip));
|
|
if (scoped) return scoped;
|
|
if (nodes.length === 1) lone ??= nodes[0];
|
|
}
|
|
return lone;
|
|
}
|
|
|
|
export type PreviewTarget = Pick<TimelineElement, "hfId" | "domId" | "id" | "sourceFile">;
|
|
|
|
/** Finds a row's preview element by `data-hf-id`, then id, preferring one in the row's own file: both repeat across
|
|
* files. Indexes the document once, so a pass over every row costs one scan. */
|
|
export function previewElementFinder(
|
|
doc: Document,
|
|
selector = "[data-hf-id], [id]",
|
|
): (target: PreviewTarget) => Element | null {
|
|
const byKey = new Map<string, Element[]>();
|
|
const add = (key: string, node: Element) => {
|
|
const nodes = byKey.get(key);
|
|
if (nodes) nodes.push(node);
|
|
else byKey.set(key, [node]);
|
|
};
|
|
for (const node of doc.querySelectorAll(selector)) {
|
|
const hfId = node.getAttribute("data-hf-id");
|
|
const id = node.getAttribute("id");
|
|
if (hfId) add(`hf:${hfId}`, node);
|
|
if (id) add(`id:${id}`, node);
|
|
}
|
|
return (target) => {
|
|
const matches = [
|
|
...((target.hfId && byKey.get(`hf:${target.hfId}`)) || []),
|
|
...(byKey.get(`id:${target.domId ?? target.id}`) ?? []),
|
|
];
|
|
return (
|
|
matches.find((node) => getTimelineElementSourceFile(node) === target.sourceFile) ??
|
|
matches[0] ??
|
|
null
|
|
);
|
|
};
|
|
}
|
|
|
|
export function findClipElementById(doc: Document, clip: ClipManifestClip): Element | null {
|
|
if (!clip.id) return null;
|
|
const first = doc.getElementById(clip.id);
|
|
if (!first || nodeInClipScope(first, clip)) return first;
|
|
return findInClipScope(doc, clip, [`[id="${CSS.escape(clip.id)}"]`]);
|
|
}
|
|
|
|
function findTimelineDomNode(doc: Document, clip: ClipManifestClip): Element | null {
|
|
if (!clip.id) return null;
|
|
const first = doc.getElementById(clip.id);
|
|
if (first && nodeInClipScope(first, clip)) return first;
|
|
const id = CSS.escape(clip.id);
|
|
const byOtherKeys = [`[data-hf-id="${id}"]`, `[data-composition-id="${id}"]`, `.${id}`];
|
|
return findInClipScope(doc, clip, first ? [`[id="${id}"]`, ...byOtherKeys] : byOtherKeys);
|
|
}
|
|
|
|
export function findTimelineDomNodeForClip(
|
|
doc: Document,
|
|
clip: ClipManifestClip,
|
|
fallbackIndex: number,
|
|
usedNodes = new Set<Element>(),
|
|
getCandidates = () => getTimelineDomNodes(doc),
|
|
): Element | null {
|
|
const byIdentity = findTimelineDomNode(doc, clip);
|
|
if (byIdentity && !usedNodes.has(byIdentity) && nodeMatchesClipTag(byIdentity, clip))
|
|
return byIdentity;
|
|
|
|
const candidates = getCandidates().filter((node) => !usedNodes.has(node));
|
|
const exact = candidates.find((node) => nodeMatchesManifestClip(node, clip));
|
|
if (exact) return exact;
|
|
|
|
const positional = candidates[fallbackIndex];
|
|
return positional && nodeMatchesClipTag(positional, clip) ? positional : null;
|
|
}
|
|
|
|
/** One synchronous hydration pass: snapshot only on a miss, never across reloads. */
|
|
export function createTimelineDomNodeResolver(doc: Document) {
|
|
let candidates: Element[] | undefined;
|
|
const usedNodes = new Set<Element>();
|
|
const getCandidates = () => (candidates ??= getTimelineDomNodes(doc));
|
|
return (clip: ClipManifestClip, index: number): Element | null => {
|
|
const node = findTimelineDomNodeForClip(doc, clip, index, usedNodes, getCandidates);
|
|
if (node) usedNodes.add(node);
|
|
return node;
|
|
};
|
|
}
|