Skip to content

Write HTML. Render video. Built for agents.

18.8 KB
Raw Blame
/**
 * Mutable document — linkedom Document wrapper for Phase 3 editing.
 *
 * The linkedom Document IS the mutable backing store. All dispatch mutations
 * go here. serialize() walks the live DOM; no separate mutable tree to sync.
 */

import { isFullHtmlDocument, parseHTMLContent } from "@hyperframes/core/compiler/html-document";
import { findTimelineScript } from "@hyperframes/core/gsap-parser-acorn";
import { findVariableDeclaration } from "./variableModel.js";
import {
  ensureHfIds,
  isCompositionTemplate,
  walkCompositionDescendants,
} from "@hyperframes/core/hf-ids";

export interface ParsedDocument {
  document: Document;
  /** True when the input was a fragment (no <html> shell) and was wrapped. */
  wrapped: boolean;
  /** ensureHfIds-stamped original HTML — used as fallback / diff base. */
  stamped: string;
}

export function parseMutable(html: string): ParsedDocument {
  const stamped = ensureHfIds(html);
  const wrapped = !isFullHtmlDocument(stamped);
  const document = parseHTMLContent(stamped);
  return { document, wrapped, stamped };
}

// ─── Element lookup ───────────────────────────────────────────────────────────

export function findById(document: Document, id: string): Element | null {
  // Delegate to resolveScoped so patch replay (undo/redo, override-set apply)
  // resolves an id the SAME way forward dispatch does: canonical-first for an
  // ambiguous bare id, and scoped-path ("hf-host/hf-leaf") aware. Otherwise the
  // two paths disagree on which duplicate a bare id targets and undo reverts the
  // wrong element. (function declaration is hoisted.)
  return resolveScoped(document, id);
}

export function escapeHfId(id: string): string {
  return id.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
}

/**
 * querySelectorAll that also descends into COMPOSITION `<template>` subtrees
 * (`data-composition-id` — the pattern the studio preview unwraps) — linkedom's
 * querySelectorAll does not, so template-based sub-comp content would be
 * unreachable for resolution/dispatch even though buildRoots models it.
 *
 * Implemented as a document-order DOM walk (not qsa + append) so duplicate-id
 * tiebreaks resolve in TRUE document order — appending template matches after
 * all top-level matches would make resolveScoped pick a different duplicate
 * than the preview's unwrapped DOM does. Plain templates (runtime clone
 * sources) are skipped, matching buildChildren and ensureHfIds.
 *
 * Throws like querySelectorAll on an invalid selector (Element.matches).
 */
export function querySelectorAllDeep(root: Document | Element, selector: string): Element[] {
  const out: Element[] = [];
  const start: Element | null =
    "body" in root ? ((root as Document).body ?? null) : (root as Element);
  const walk = (parent: Element): void => {
    for (const child of Array.from(parent.children)) {
      if (child.tagName.toLowerCase() === "template") {
        if (isCompositionTemplate(child)) walk(child);
        continue;
      }
      if (child.matches(selector)) out.push(child);
      walk(child);
    }
  };
  if (start) {
    // When rooted at an Element (scoped-path step), the root itself is the
    // context, not a candidate — only descendants match, like querySelectorAll.
    walk(start);
  }
  return out;
}

/**
 * True when an element lives at the top-level (canonical) scope — i.e. its
 * scopedId equals its bare id because no ancestor opens a sub-composition
 * boundary. This mirrors document.ts's scopedId construction (childPrefix only
 * changes at isNewHostBoundary elements) without rebuilding the snapshot tree.
 */
function isCanonicalScope(el: Element): boolean {
  for (let cur = el.parentElement; cur; cur = cur.parentElement) {
    if (isNewHostBoundary(cur)) return false;
  }
  return true;
}

/**
 * Resolve a bare or scoped hf-id to its DOM element.
 *
 * Bare id ("hf-x"): top-level document search. When the bare id is ambiguous
 * (duplicated across a sub-composition and the top level), prefer the canonical
 * (top-level) instance — the one whose scopedId equals the bare id — falling
 * back to document order when no canonical match exists. This matches
 * getElement()'s resolution rule so removeElement / getElement agree on which
 * instance an ambiguous bare id targets.
 *
 * Scoped id ("hf-HOST/hf-LEAF", any depth): each segment narrows the search
 * into the subtree of the previous match. This unambiguously addresses an
 * element inside a sub-composition even when bare ids collide.
 */
export function resolveScoped(document: Document, id: string): Element | null {
  const parts = id.split("/");

  // Bare id: prefer the canonical (top-level) match when one exists, so
  // resolution agrees with getElement (scopedId === id wins over document order).
  if (parts.length === 1) {
    const escaped = escapeHfId(id);
    const matches = querySelectorAllDeep(document, `[data-hf-id="${escaped}"]`);
    if (matches.length > 0) {
      return matches.find((el) => isCanonicalScope(el)) ?? matches[0] ?? null;
    }
    // Fall back to a sub-composition ROOT addressed by its composition id. A
    // host element carries data-hf-id (its own leaf id) AND data-composition-id
    // (the id studio passes when targeting the sub-comp root). data-hf-id takes
    // precedence above; only when no hf-id matches do we treat the bare id as a
    // composition id, making comp-ids first-class resolvable addresses.
    return querySelectorAllDeep(document, `[data-composition-id="${escaped}"]`)[0] ?? null;
  }

  let context: Element | Document = document;
  for (const part of parts) {
    const escaped = escapeHfId(part);
    const found: Element | null =
      querySelectorAllDeep(context, `[data-hf-id="${escaped}"]`)[0] ?? null;
    if (!found) return null;
    context = found;
  }
  return context as Element;
}

/**
 * Bare leaf id from a scoped hf-id ("hf-HOST/hf-LEAF" → "hf-LEAF"; a bare id
 * passes through unchanged). The live DOM's `data-hf-id` attribute never
 * carries the host-chain prefix, so a consumer holding a scopedId (from
 * getElements()/getElement()) needs this to query the rendered DOM directly.
 */
export function bareId(scopedId: string): string {
  const parts = scopedId.split("/");
  // split() always returns >=1 element, so this never actually falls through at
  // runtime — the fallback exists to satisfy noUncheckedIndexedAccess, not as a
  // reachable safety net.
  return parts[parts.length - 1] ?? scopedId;
}

/**
 * Returns true when this element starts a new sub-composition scope — i.e. it
 * is a host element (has data-composition-file) and is NOT the outerHTML
 * innerRoot of the SAME sub-composition (same dcf value as parent).
 *
 * outerHTML case: both host and innerRoot carry data-composition-file="sub.html".
 * The innerRoot has the SAME value as the host (its parent) → not a new boundary.
 * A genuine nested host inside a sub-comp has a DIFFERENT dcf value.
 */
export function isNewHostBoundary(el: Element): boolean {
  const dcf = el.getAttribute("data-composition-file");
  if (!dcf) return false;
  const parentDcf = el.parentElement?.getAttribute("data-composition-file") ?? null;
  return dcf !== parentDcf;
}

/**
 * The elements carrying `data-composition-variables`, in the runtime's merge
 * order: `<html>`, then the composition root, whose entries win a shared id. A
 * wrapped template/fragment comp has a synthetic `<html>` that serialize()
 * strips, so only its root counts.
 */
export function declarationCarriers(document: Document, wrapped: boolean): Element[] {
  const root = findRoot(document);
  const html = wrapped
    ? null
    : (document as Document & { documentElement?: Element }).documentElement;
  const carriers = [html, root].filter(
    (el): el is Element => !!el?.hasAttribute("data-composition-variables"),
  );
  return [...new Set(carriers)];
}

/**
 * Where a declaration op lands: the carrier that declares `id` (the root first,
 * as it wins), else the root if it carries declarations, else `<html>` (the
 * root div for wrapped comps).
 */
export function declarationElement(
  document: Document,
  wrapped: boolean,
  id?: string,
): Element | null {
  const winnerFirst = declarationCarriers(document, wrapped).reverse();
  const owner =
    id === undefined ? undefined : winnerFirst.find((el) => findVariableDeclaration(el, id));
  if (owner) return owner;
  if (wrapped) return findRoot(document);
  return (
    winnerFirst[0] ?? (document as Document & { documentElement?: Element }).documentElement ?? null
  );
}

export function findRoot(document: Document): Element | null {
  return (
    document.querySelector("[data-hf-root]") ??
    document.getElementById("stage") ??
    // Descend into a composition <template> so a wrapped template sub-comp
    // resolves to its inner [data-composition-id] root, not the <template> shell.
    querySelectorAllDeep(document, "[data-composition-id]")[0] ??
    document.body?.firstElementChild ??
    null
  );
}

// ─── Inline style helpers ─────────────────────────────────────────────────────

export function toCamel(prop: string): string {
  if (prop.startsWith("--")) return prop;
  return prop.replace(/-([a-z])/g, (_, c: string) => (c as string).toUpperCase());
}

function toKebab(prop: string): string {
  if (prop.startsWith("--")) return prop;
  return prop.replace(/([A-Z])/g, (c) => `-${c.toLowerCase()}`);
}

/** Parse style attribute string → camelCase map (custom props kept as-is). */
interface StyleDeclarationScan {
  depth: number;
  quote: "'" | '"' | null;
  skip: boolean;
}

function advanceStyleDeclarationScan(scan: StyleDeclarationScan, ch: string, next: string): void {
  if (ch === "\\" && next) {
    scan.skip = true;
    return;
  }
  if (scan.quote) {
    if (ch === scan.quote) scan.quote = null;
    return;
  }
  if (ch === "'" || ch === '"') {
    scan.quote = ch;
    return;
  }
  if (ch === "(") scan.depth++;
  else if (ch === ")") scan.depth = Math.max(0, scan.depth - 1);
}

function splitStyleDeclarations(style: string): string[] {
  const declarations: string[] = [];
  const scan: StyleDeclarationScan = { depth: 0, quote: null, skip: false };
  let start = 0;
  for (let i = 0; i < style.length; i++) {
    if (scan.skip) {
      scan.skip = false;
      continue;
    }
    const ch = style[i] ?? "";
    if (ch === ";" && scan.depth === 0 && scan.quote === null) {
      declarations.push(style.slice(start, i));
      start = i + 1;
    } else {
      advanceStyleDeclarationScan(scan, ch, style[i + 1] ?? "");
    }
  }
  declarations.push(style.slice(start));
  return declarations;
}

function parseStyleAttr(styleAttr: string): Record<string, string> {
  const result: Record<string, string> = {};
  for (const decl of splitStyleDeclarations(styleAttr)) {
    const idx = decl.indexOf(":");
    if (idx === -1) continue;
    const rawProp = decl.slice(0, idx).trim();
    const value = decl.slice(idx + 1).trim();
    if (!rawProp) continue;
    result[toCamel(rawProp)] = value;
  }
  return result;
}

/** Serialize camelCase style map → style attribute string. */
function serializeStyleAttr(styles: Record<string, string>): string {
  return Object.entries(styles)
    .map(([k, v]) => `${toKebab(k)}: ${v}`)
    .join("; ");
}

export function getElementStyles(el: Element): Record<string, string> {
  const attr = el.getAttribute("style") ?? "";
  return parseStyleAttr(attr);
}

export function setElementStyles(el: Element, updates: Record<string, string | null>): void {
  const current = getElementStyles(el);
  for (const [prop, value] of Object.entries(updates)) {
    // Stored map is keyed camelCase (parseStyleAttr); custom props (--foo) stay
    // verbatim. Normalize the incoming key the same way for both set and delete.
    const key = toCamel(prop);
    if (value === null) {
      delete current[key];
    } else {
      current[key] = value;
    }
  }
  const serialized = serializeStyleAttr(current);
  if (serialized) {
    el.setAttribute("style", serialized);
  } else {
    el.removeAttribute("style");
  }
}

// ─── Text helpers ─────────────────────────────────────────────────────────────

function isHTMLElementTarget(el: Element): boolean {
  const HTMLElementCtor = el.ownerDocument.defaultView?.HTMLElement;
  if (HTMLElementCtor) return el instanceof HTMLElementCtor;
  return "style" in el;
}

// Void elements can't hold text, so a lone `<br>`/`<img>`/`<hr>`/… child is
// never the element's text target. Treating one as such made getOwnText read
// "" (→ `text: null`, surfaced as "not editable") and setOwnText write into the
// void element, corrupting it — e.g. a `<br>` gained a text child and
// serialized as invalid `</br>`.
const VOID_TEXT_TARGET_TAGS = new Set([
  "AREA",
  "BASE",
  "BR",
  "COL",
  "EMBED",
  "HR",
  "IMG",
  "INPUT",
  "LINK",
  "META",
  "PARAM",
  "SOURCE",
  "TRACK",
  "WBR",
]);

function isBrElement(node: Node): boolean {
  return node.nodeType === 1 && (node as Element).tagName === "BR";
}

/** A flat text leaf: no element children, or only `<br>` line breaks
 *  (e.g. `<h1>First<br>Second</h1>`). Such an element's entire content is its
 *  own text, so setText owns it end-to-end. Vacuously true for zero children. */
function isTextOrBrLeaf(el: Element): boolean {
  return Array.from(el.children).every((child) => child.tagName === "BR");
}

function resolveSingleChildTextTarget(el: Element): Element | null {
  const inner = el.children.length === 1 ? el.firstElementChild : null;
  if (!inner || !isHTMLElementTarget(inner)) return null;
  if (VOID_TEXT_TARGET_TAGS.has(inner.tagName)) return null;
  return inner;
}

/** Read the text target used by SDK setText. `<br>` line breaks are surfaced as
 *  "\n" so a multi-line leaf round-trips through setOwnText. */
export function getOwnText(el: Element): string {
  const singleChild = resolveSingleChildTextTarget(el);
  if (singleChild) return singleChild.textContent ?? "";
  let text = "";
  el.childNodes.forEach((n) => {
    if (n.nodeType === 3) text += (n as Text).nodeValue ?? "";
    else if (isBrElement(n)) text += "\n";
  });
  return text;
}

/** Replace the SDK text target without destroying multi-child element structure. */
export function setOwnText(el: Element, text: string): void {
  const singleChild = resolveSingleChildTextTarget(el);
  if (singleChild) {
    singleChild.textContent = text;
    return;
  }

  const doc = el.ownerDocument;

  // Flat text leaf (text and/or `<br>` only): rebuild the text/`<br>` run from
  // the "\n"-separated value — the inverse of getOwnText. Existing `<br>` nodes
  // are reused in order so their identity (data-hf-id, etc.) survives an edit
  // that keeps the line, and a new one is only minted when a line is added.
  // Never writes text into a `<br>`, so no `</br>` corruption.
  if (isTextOrBrLeaf(el)) {
    const spareBrs = Array.from(el.children).filter((child) => child.tagName === "BR");
    while (el.firstChild) el.removeChild(el.firstChild);
    const lines = text.split("\n");
    lines.forEach((line, index) => {
      if (index > 0) el.appendChild(spareBrs.shift() ?? doc.createElement("br"));
      if (line) el.appendChild(doc.createTextNode(line));
    });
    return;
  }

  const children = Array.from(el.childNodes);
  // Track original position of the first text node so we restore there, not at firstChild.
  let firstTextIdx = -1;
  for (let i = 0; i < children.length; i++) {
    if (children[i]?.nodeType === 3) {
      firstTextIdx = i;
      break;
    }
  }
  for (const child of children) {
    if (child.nodeType === 3) el.removeChild(child);
  }
  if (text) {
    // No text nodes before firstTextIdx (it's the first one), so index is stable.
    const current = Array.from(el.childNodes);
    const ref = firstTextIdx >= 0 ? (current[firstTextIdx] ?? null) : null;
    el.insertBefore(doc.createTextNode(text), ref);
  }
}

// ─── CSS style helpers ────────────────────────────────────────────────────────

function findStyleElement(document: Document): Element | null {
  return document.querySelector("style") as unknown as Element | null;
}

export function getStyleSheet(document: Document): string {
  return findStyleElement(document)?.textContent ?? "";
}

export function setStyleSheet(document: Document, css: string): void {
  const existing = findStyleElement(document);
  if (!css) {
    existing?.remove();
    return;
  }
  let el = existing;
  if (!el) {
    el = document.createElement("style") as unknown as Element;
    const head =
      (document.querySelector("head") as unknown as Element | null) ??
      (document.body as unknown as Element);
    (head as any).appendChild(el);
  }
  el.textContent = css;
}

// ─── GSAP script helpers ──────────────────────────────────────────────────────

function findScriptElementsDeep(document: Document): Element[] {
  const scripts: Element[] = [];
  walkCompositionDescendants(document, (child) => {
    if (child.tagName.toLowerCase() === "script") scripts.push(child);
  });
  return scripts;
}

function isGsapScriptText(text: string): boolean {
  return text.includes("gsap") || text.includes("__timelines") || text.includes("ScrollTrigger");
}

export function getGsapScripts(document: Document): string[] {
  return findScriptElementsDeep(document)
    .map((script) => script.textContent ?? "")
    .filter(isGsapScriptText);
}

export function findGsapScriptElement(document: Document): Element | null {
  const scripts = findScriptElementsDeep(document);
  return (
    findTimelineScript(scripts) ??
    scripts.find((s) => isGsapScriptText(s.textContent ?? "")) ??
    null
  );
}

export function getGsapScript(document: Document): string | null {
  const el = findGsapScriptElement(document);
  return el ? (el.textContent ?? "") : null;
}

export function setGsapScript(document: Document, newScript: string): void {
  const existing = findGsapScriptElement(document);
  if (!newScript) {
    existing?.remove();
    return;
  }
  let el = existing;
  if (!el) {
    el = document.createElement("script") as unknown as Element;
    const head =
      (document.querySelector("head") as unknown as Element | null) ??
      (document.body as unknown as Element);
    (head as any).appendChild(el);
  }
  el.textContent = newScript;
}

// ─── Sibling index ────────────────────────────────────────────────────────────

export function getSiblingIndex(el: Element): number {
  const parent = el.parentElement;
  if (!parent) return 0;
  return Array.from(parent.children).indexOf(el);
}