Skip to content

Write HTML. Render video. Built for agents.

6.9 KB
Raw Blame
// Non-editable / non-visual elements that should never receive a stable id.
export const EXCLUDED_TAGS = new Set([
  "script",
  "style",
  "template",
  "meta",
  "link",
  "noscript",
  "base",
]);

// 32-bit FNV-1a. Pure, deterministic, no crypto, no Math.random.
function fnv1a(str: string): number {
  let h = 0x811c9dc5;
  for (let i = 0; i < str.length; i++) {
    h ^= str.charCodeAt(i);
    h = Math.imul(h, 0x01000193);
  }
  return h >>> 0;
}

// 4 base-36 chars · 36^4 ≈ 1.68M ids per document. Birthday-paradox collision
// ≈ N²/(2·36^4): well under 1% per document after dup rehash at realistic
// clip-model sizes (≤ a few hundred elements). The dup-rehash in mintHfId
// resolves the rare collision; width is deliberately small for readable ids.
function toHfId(hash: number): string {
  const s = (hash >>> 0).toString(36);
  // Use suffix (most-avalanched bits) for better distribution within the 4-char window.
  const four = s.length >= 4 ? s.slice(-4) : s.padStart(4, "0");
  return `hf-${four}`;
}

// Element's own direct text (TEXT_NODE children), not descendants'.
function ownText(el: Element): string {
  let text = "";
  el.childNodes.forEach((n) => {
    if (n.nodeType === 3) text += (n as Text).nodeValue ?? "";
  });
  return text.trim();
}

function getContractAttribute(el: Element, name: string): string | null {
  return Array.from(el.attributes).find((attr) => attr.name.toLowerCase() === name)?.value ?? null;
}

function contentKey(el: Element): string {
  // HTML parsers normalize foreign-content attribute names differently too.
  // Canonicalize only the hash input; retain actual SVG attribute spelling.
  // Exclude all data-hf-* attrs (ids, studio state) — they must not influence the hash.
  // Use \x00 / \x01 separators (invalid in HTML attrs) to prevent ambiguous serialization.
  const attrs = Array.from(el.attributes)
    .filter((a) => !a.name.toLowerCase().startsWith("data-hf-"))
    .map((a) => `${a.name.toLowerCase()}\x00${a.value}`)
    .sort()
    .join("\x01");
  return `${el.tagName.toLowerCase()}|${attrs}|${ownText(el)}`;
}

/**
 * Collision tiebreak for byte-identical siblings: document-order dup counter
 * (`hash(key#N)`). This IS order-dependent — two identical `<span></span>`
 * get different ids based on which comes first in the DOM. This is unavoidable:
 * unique ids for byte-identical elements require a positional signal.
 *
 * Why this is safe in practice: once `data-hf-id` is on disk (stamped at project open, or by the
 * first save) it is bound to its element, so reordering identical siblings carries it along, and
 * `ensureHfIds` skips pinned elements (`if (getContractAttribute(el, "data-hf-id")) continue`).
 * Before that, an outside edit changes what is minted (an element's attributes or own text, or a
 * twin added or removed), so a save carrying an id served before the edit misses or hits the other
 * twin until the watcher reloads the preview.
 */
// WIRE CONTRACT: id minting is content-keyed (FNV1a of tag, sorted attrs, own text). R7's
// preview route relies on mintHfId producing identical ids across mint contexts
// (served copy vs. the source a save parses) — see preview.test.ts
// "bundle returning untagged HTML gets the ids minted from the source file". Any change that adds
// positional, session, or random input to the hash breaks that invariant and
// makes hf- ids diverge between disk and served HTML, silently corrupting
// drag-to-edit targeting.
export function mintHfId(el: Element, assigned: Set<string>): string {
  const key = contentKey(el);
  let id = toHfId(fnv1a(key));
  let dup = 0;
  while (assigned.has(id)) {
    dup += 1;
    // Graceful fallback instead of a hard throw: rehashing only fails to find a
    // free 4-char slot in a pathological document (~1.6M identical elements).
    // Rather than crash the whole parse, widen the id with the dup counter —
    // still deterministic and unique, just longer than the 4-char norm.
    if (dup > 10000) {
      id = `hf-${(fnv1a(key) >>> 0).toString(36)}-${dup}`;
      break;
    }
    id = toHfId(fnv1a(`${key}#${dup}`));
  }
  assigned.add(id);
  return id;
}

/**
 * True for a sub-composition authoring template whose content the studio preview
 * unwraps into the served body. Two accepted forms:
 *   A) `<template data-composition-id="X">…` — the id on the template itself.
 *   B) `<template id="X-template"><div data-composition-id="X">…` — the id on the
 *      wrapped root div (the form `hyperframes add` scaffolds and registry blocks use).
 * Only these are treated as transparent containers for hf-id purposes. A plain
 * `<template>` (runtime clone-source: list item, particle, etc.) must NOT get
 * inner ids — its content is cloned N times into the live DOM, so a persisted
 * inner id would be duplicated across every clone. Form B is distinguished from
 * a clone-source by the presence of a direct `[data-composition-id]` child.
 */
export function getChildElements(parent: Element): Element[] {
  const directChildren = Array.from(parent.children);
  if (directChildren.length || parent.tagName.toLowerCase() !== "template") return directChildren;
  const content = (parent as HTMLTemplateElement).content;
  if (content?.children.length) return Array.from(content.children);
  return directChildren;
}

export function isCompositionTemplate(el: Element): boolean {
  if (el.tagName.toLowerCase() !== "template") return false;
  if (getContractAttribute(el, "data-composition-id") !== null) return true;
  for (const child of getChildElements(el)) {
    if (getContractAttribute(child, "data-composition-id") !== null) return true;
  }
  return false;
}

/**
 * Walk document-order descendants, descending through composition templates
 * while keeping plain templates inert. linkedom's querySelectorAll does not
 * expose template contents, so callers that model the served composition use
 * this traversal instead.
 */
export function walkCompositionDescendants(
  root: Document | Element,
  visit: (el: Element) => void,
): void {
  const rootElement: Element | null =
    root.nodeType === 9 ? (root as Document).documentElement : (root as Element);
  if (!rootElement) return;

  const walk = (parent: Element): void => {
    for (const child of getChildElements(parent)) {
      const isTemplate = child.tagName.toLowerCase() === "template";
      if (isTemplate && !isCompositionTemplate(child)) continue;
      visit(child);
      walk(child);
    }
  };

  walk(rootElement);
}

// Internal DOM-only assignment: callers retain their parser and document identity.
export function assignHfIds(body: Element): void {
  const assigned = new Set<string>();
  walkCompositionDescendants(body, (el) => {
    const existing = getContractAttribute(el, "data-hf-id");
    if (existing) assigned.add(existing);
  });
  walkCompositionDescendants(body, (el) => {
    if (EXCLUDED_TAGS.has(el.tagName.toLowerCase())) return;
    if (getContractAttribute(el, "data-hf-id")) return;
    el.setAttribute("data-hf-id", mintHfId(el, assigned));
  });
}