Skip to content

Write HTML. Render video. Built for agents.

8.2 KB
Raw Blame
/**
 * Document-unique identity for media elements in a compiled render document.
 *
 * Element `id`s are only unique within one composition FILE. The render
 * document is the inlined union of every file, so ids collide there in two
 * ways an author cannot avoid:
 *
 * 1. Two scenes each declare `<video id="clip">` — legal per file, duplicated
 *    once inlined.
 * 2. Two scenes each declare a bare `<video>` — the timing compiler numbers
 *    auto-ids per file, so both become `hf-video-0`.
 *
 * The render pipeline keys media on that id (extract, inject, visibility,
 * bounds), so a collision collapses N elements into one entry and every
 * lookup resolves to whichever element happens to come first in the document.
 * The surviving clip's frames land on the wrong element and the visible scene
 * paints without footage.
 *
 * This module is the single owner of the fix: after inlining, every media
 * element gets a document-unique `data-hf-render-id`. It equals the element's
 * own id whenever that id is already unique, so uncolliding documents keep
 * byte-identical pipeline keys and log output. Author-visible `id` attributes
 * are never rewritten — 158 of the 161 registry blocks reference their own ids
 * from `#id` CSS or `getElementById`, so renaming would break scene styling to
 * fix scene footage.
 */

import { AUDIBLE_VIDEO_QUALIFIER } from "../audibleVideo.js";

export const MEDIA_RENDER_ID_ATTR = "data-hf-render-id";

/**
 * The bus a member belongs to, as a DOCUMENT-unique key.
 *
 * `data-audio-group` names a bus by author id, unique only per composition FILE
 * — so a sub-composition that declares a bus AND its members, used twice, put
 * both instances' members under one key and let the second bus element
 * overwrite the first. The mixer then sub-mixed two independent buses as one,
 * applied instance B's fader, chain and label to instance A's audio, and — with
 * only B muted — dropped BOTH instances from the export. This attribute is that
 * collision resolved at the same boundary the media ids are.
 */
export const AUDIO_GROUP_RENDER_ID_ATTR = "data-hf-group-render-id";

/**
 * Elements the render pipeline addresses by id.
 *
 * `<video>`/`<audio>` are matched even with an empty `src`. Authors assign the
 * URL from the scene script (`el.src = url`); the static parse then skips them
 * and the browser snapshot has to pair the clips. Without a render id on those
 * elements the snapshot keys by raw id and colliding scenes collapse. `<img>`
 * still requires a `src` attribute (empty is enough) so we do not stamp every
 * decorative image.
 */
const MEDIA_SELECTOR = "video, audio, img[src]";

/** Buses, which are addressed by id in exactly the same way and collide the
 *  same way. Only an id'd bus can be joined at all. */
const AUDIO_GROUP_SELECTOR = "hf-audio-group[id]";

interface MediaElementLike {
  readonly tagName?: string;
  getAttribute(name: string): string | null;
  setAttribute(name: string, value: string): void;
}

/** A bus or member, which additionally needs subtree scoping to be paired up. */
interface ScopedElementLike extends MediaElementLike {
  closest?(selector: string): ScopedElementLike | null;
}

interface DocumentLike {
  querySelectorAll(selector: string): Iterable<MediaElementLike>;
}

/**
 * Derive a document-unique render id from an element's own id.
 *
 * `taken` accumulates every id handed out so far, including the plain ids of
 * elements that have not been visited yet is NOT required: a later element
 * whose plain id was already claimed simply gets a suffix. Document order
 * therefore decides who keeps the plain id, which keeps the first (and, in the
 * overwhelmingly common single-occurrence case, only) element stable.
 */
function uniqueRenderId(baseId: string, taken: Set<string>): string {
  if (!taken.has(baseId)) return baseId;
  let suffix = 2;
  while (taken.has(`${baseId}__hf${suffix}`)) suffix += 1;
  return `${baseId}__hf${suffix}`;
}

/**
 * Stamp `data-hf-render-id` on every media element in a compiled document.
 *
 * Preserve unique existing stamps on recompilation. Repair stamps that collide
 * after independently compiled scenes are merged.
 */
export function assignMediaRenderIds(document: DocumentLike): void {
  const taken = new Set<string>();
  const pending: MediaElementLike[] = [];

  const elements = [
    ...document.querySelectorAll(MEDIA_SELECTOR),
    ...document.querySelectorAll(AUDIO_GROUP_SELECTOR),
  ];
  for (const el of elements) {
    const existing = el.getAttribute(MEDIA_RENDER_ID_ATTR);
    if (existing && !taken.has(existing)) {
      taken.add(existing);
      continue;
    }
    pending.push(el);
  }

  for (const el of pending) {
    const baseId = el.getAttribute("id");
    // An element with no id yet is numbered by the timing compiler before this
    // runs. If one slips through, fall back to a positional id rather than
    // stamping an empty string that every other id-less element would share.
    const renderId = uniqueRenderId(baseId || `hf-media-${taken.size}`, taken);
    taken.add(renderId);
    el.setAttribute(MEDIA_RENDER_ID_ATTR, renderId);
  }

  assignAudioGroupRenderIds(document);
}

/**
 * Give every `<hf-audio-group>` a document-unique render id, and tell each
 * member which INSTANCE of its bus it belongs to.
 *
 * Shares the `taken` set with the media pass, so a bus id and a clip id can
 * never resolve to the same key either.
 *
 * A member is paired to the bus inside its OWN composition subtree. Two
 * instances of the same sub-composition are indistinguishable by
 * `data-composition-id` — both carry the file's own id — so the subtree
 * ELEMENT is the only thing that separates them, which is exactly what
 * `closest()` returns. A member whose bus is not in its subtree (a
 * hand-authored bus in the root composition, members in a scene) falls back to
 * the first bus with that id, which is the pre-existing behaviour and the only
 * sensible reading when there is one bus and several scenes referencing it.
 */
function assignAudioGroupRenderIds(document: DocumentLike): void {
  const busesById = indexAudioGroupBuses(document);
  if (busesById.size === 0) return;

  for (const member of document.querySelectorAll(
    `audio[data-audio-group], video[data-audio-group]${AUDIBLE_VIDEO_QUALIFIER}`,
  ) as Iterable<ScopedElementLike>) {
    const groupId = member.getAttribute("data-audio-group");
    const buses = groupId ? busesById.get(groupId) : undefined;
    if (!groupId || !buses?.length) continue;
    const renderId = busForMember(member, groupId, buses)?.getAttribute(MEDIA_RENDER_ID_ATTR);
    if (renderId) member.setAttribute(AUDIO_GROUP_RENDER_ID_ATTR, renderId);
  }
}

/** Index stamped buses by author id; several share an id when a
 *  sub-composition that declares one is used more than once. */
function indexAudioGroupBuses(document: DocumentLike): Map<string, ScopedElementLike[]> {
  const busesById = new Map<string, ScopedElementLike[]>();
  for (const bus of document.querySelectorAll(
    AUDIO_GROUP_SELECTOR,
  ) as Iterable<ScopedElementLike>) {
    const id = bus.getAttribute("id");
    if (!id) continue;
    const existing = busesById.get(id);
    if (existing) existing.push(bus);
    else busesById.set(id, [bus]);
  }
  return busesById;
}

/**
 * Which instance of a bus a member belongs to: the one in its own composition
 * subtree. Falls back to the first when the bus is not in the member's subtree
 * at all — a hand-authored bus in the root composition with members in scenes —
 * which is the pre-existing reading and the only sensible one there.
 */
function busForMember(
  member: ScopedElementLike,
  groupId: string,
  buses: ScopedElementLike[],
): MediaElementLike | undefined {
  if (buses.length === 1) return buses[0];
  const scope = member.closest?.("[data-composition-id]");
  if (!scope) return buses[0];
  // `scope.querySelectorAll()` also sees buses owned by nested compositions.
  // Compare each bus's own nearest composition instead, so a root member does
  // not bind to a same-named bus inside a child merely because the child comes
  // first in document order.
  return (
    buses.find(
      (candidate) =>
        candidate.getAttribute("id") === groupId &&
        candidate.closest?.("[data-composition-id]") === scope,
    ) ?? buses[0]
  );
}