Skip to content

Write HTML. Render video. Built for agents.

12.4 KB
Raw Blame
/**
 * Composition assembly decisions — the questions both assembly paths answer.
 *
 * A composition is assembled twice in this repo: `compiler/inlineSubCompositions.ts`
 * assembles it for rendering (Node, linkedom, synchronous, emits strings) and
 * `runtime/compositionLoader.ts` assembles it for mounting (browser, fetch, live
 * DOM, executes scripts). Their I/O is genuinely different; their *decisions* are
 * not. This module owns the decisions:
 *
 * - which nodes are a composition's asset sources, and in what order
 * - which `<head>` elements hoist into the host document
 * - the composition's scope identity (CSS scope, script scope, authored root id)
 * - which nodes carry the composition's declared variable defaults
 * - how nested `data-composition-src` hosts are enumerated
 *
 * It is deliberately DOM-free, filesystem-free and network-free: the runtime is
 * bundled by esbuild into the IIFE published to a CDN, so anything reachable
 * from `runtime/entry.ts` ships to every viewer. It takes narrow structural
 * types instead of `Document`/`Element` for the same reason `compositionScoping.ts`
 * takes strings — so both a linkedom document and a live browser document
 * satisfy it without an `as T` cast at either call site.
 */

const COMPOSITION_ID_ATTR = "data-composition-id";
const COMPOSITION_SRC_ATTR = "data-composition-src";
const COMPOSITION_ROOT_SELECTOR = `[${COMPOSITION_ID_ATTR}]`;
const COMPOSITION_HOST_SELECTOR = `[${COMPOSITION_SRC_ATTR}]`;
const STYLE_SELECTOR = "style";
const SCRIPT_SELECTOR = "script";

/**
 * Links both paths hoist into the host document. Stylesheets carry
 * webfonts a composition's CSS depends on; preconnects are their latency hint.
 */
const HOISTED_LINK_SELECTOR = 'link[rel="stylesheet"], link[rel="preconnect"]';

// The HTML spec's JavaScript MIME type essence matches: a script with any of these types runs as classic.
const JAVASCRIPT_TYPES = new Set([
  "",
  "application/ecmascript",
  "application/javascript",
  "application/x-ecmascript",
  "application/x-javascript",
  "text/ecmascript",
  "text/javascript",
  "text/javascript1.0",
  "text/javascript1.1",
  "text/javascript1.2",
  "text/javascript1.3",
  "text/javascript1.4",
  "text/javascript1.5",
  "text/jscript",
  "text/livescript",
  "text/x-ecmascript",
  "text/x-javascript",
]);

const scriptType = (el: AssemblyAttributed) => (el.getAttribute("type") || "").trim().toLowerCase();

export function isJavaScriptType(el: AssemblyAttributed): boolean {
  return JAVASCRIPT_TYPES.has(scriptType(el));
}

/**
 * A data block (application/json, text/template, ...) or a classic nomodule script never runs,
 * so it is mounted as authored.
 */
function isExecutableScript(el: AssemblyAttributed): boolean {
  const type = scriptType(el);
  if (type === "module" || type === "importmap") return true;
  return JAVASCRIPT_TYPES.has(type) && el.getAttribute("nomodule") === null;
}

function inertScripts<TElement extends AssemblyAttributed>(
  node: AssemblyQueryable<TElement> | null | undefined,
): TElement[] {
  return toArray(node?.querySelectorAll(SCRIPT_SELECTOR)).filter((el) => !isExecutableScript(el));
}

export function executableScripts<TElement extends AssemblyAttributed>(
  node: AssemblyQueryable<TElement> | null | undefined,
): TElement[] {
  return toArray(node?.querySelectorAll(SCRIPT_SELECTOR)).filter(isExecutableScript);
}

/** The styles, scripts and links both paths extract, so the mounted copy must drop them. */
export function extractedCompositionAssets<TElement extends AssemblyAttributed>(
  node: AssemblyQueryable<TElement>,
): TElement[] {
  return [
    ...toArray(node.querySelectorAll(`${STYLE_SELECTOR}, ${HOISTED_LINK_SELECTOR}`)),
    ...executableScripts(node),
  ];
}

/**
 * The compiler's nesting cap, enforced against the ancestry chain rather than a
 * counter so a wide tree is not penalised for a deep sibling.
 */
export const MAX_SUB_COMPOSITION_DEPTH = 20;

// ---------------------------------------------------------------------------
// Structural inputs
// ---------------------------------------------------------------------------

/** An element this module only ever reads attributes from. */
export interface AssemblyAttributed {
  getAttribute(name: string): string | null;
}

/** A node this module only ever searches with a CSS selector. */
export interface AssemblyQueryable<TElement> {
  querySelectorAll(selectors: string): Iterable<TElement>;
}

export interface CompositionAssemblyInput<TElement extends AssemblyAttributed> {
  /**
   * The composition's content: a `<template>`'s content when the composition is
   * templated, the parsed document's `<body>` otherwise.
   *
   * Asset sources are collected from the WHOLE content node, never from the
   * composition root alone. The canonical authored shape puts `<style>`/`<script>`
   * as SIBLINGS of the root inside `<template>`; scanning only the root dropped a
   * composition's entire stylesheet on mount while its render stayed correct.
   */
  contentNode: AssemblyQueryable<TElement>;

  /**
   * The parsed document's `<head>`, when the composition was loaded as a full
   * HTML document. Omit it for an inline `<template>`, which has no head of its
   * own.
   */
  head?: AssemblyQueryable<TElement> | null;

  /**
   * The parsed document's `<html>` element, when there is one. It is the first
   * variable-default carrier; see `variableDefaultCarriers`.
   */
  documentElement?: TElement | null;

  /**
   * True when `contentNode` came from a `<template>`. A templated composition's
   * `<head>` styles and scripts are not part of the composition — the template
   * already carries everything it needs — so they are not collected.
   */
  hasTemplate: boolean;

  /**
   * The composition id the host asks this composition to mount as, or `null` for
   * an anonymous host.
   */
  compositionId: string | null;
}

export interface CompositionAssemblyPlan<TElement extends AssemblyAttributed> {
  /**
   * The composition root inside `contentNode`. Matched on an EXACT id when the
   * host names one — a template may intentionally use a different local id (a
   * `captions-comp` host mounting a `captions` template), and flattening that
   * fallback root changes the assembled DOM. Anonymous hosts fall back to the
   * first root in the content.
   */
  innerRoot: TElement | null;

  /**
   * The id CSS is scoped to: the host's id when it names one, otherwise the id
   * declared inside the content.
   */
  authoredCompositionId: string | null;

  /**
   * The id composition scripts are scoped to. It differs from
   * `authoredCompositionId` only when a host names an id that no root inside the
   * content declares: CSS stays on the host's id while scripts follow the id the
   * content actually declares, so a script's self-referencing
   * `querySelector('[data-composition-id="X"]')` still resolves.
   */
  scriptCompositionId: string | null;

  /** The `id` attribute authored on the composition root, if any. */
  authoredRootId: string | null;

  /** `<style>` sources in injection order: head-sourced first, then content. */
  styleSources: TElement[];

  /**
   * `<script>` sources in execution order: head-sourced first, then content. A
   * head script (a GSAP CDN tag in a non-templated composition) has to run
   * before the content scripts that call into it.
   */
  scriptSources: TElement[];

  /** Head and content links to hoist into the host document. */
  linkSources: TElement[];

  /** Inert scripts the mounted root would leave behind; both paths mount them next to it. */
  inertScriptsOutsideRoot: TElement[];

  /**
   * Nodes that may declare the composition's variable defaults, in precedence
   * order — later wins. Full-document compositions declare on `<html>`;
   * template/fragment compositions declare on the `[data-composition-id]` root
   * div, because they have no `<html>` of their own. Callers read the declared
   * defaults off each carrier and merge left to right.
   */
  variableDefaultCarriers: TElement[];
}

// ---------------------------------------------------------------------------
// Decisions
// ---------------------------------------------------------------------------

function toArray<TElement>(items: Iterable<TElement> | null | undefined): TElement[] {
  return items ? Array.from(items) : [];
}

/**
 * Answer, for one composition, where its assets come from, in what order, and
 * how it is identified. Pure: it reads attributes and runs selectors, and does
 * not mutate, fetch, or touch a filesystem.
 */
export function planCompositionAssembly<
  TElement extends AssemblyAttributed & AssemblyQueryable<TElement>,
>(input: CompositionAssemblyInput<TElement>): CompositionAssemblyPlan<TElement> {
  const { contentNode, head, documentElement, hasTemplate, compositionId } = input;

  const compositionRoots = toArray(contentNode.querySelectorAll(COMPOSITION_ROOT_SELECTOR));
  const innerRoot = compositionId
    ? (compositionRoots.find((root) => root.getAttribute(COMPOSITION_ID_ATTR) === compositionId) ??
      null)
    : (compositionRoots[0] ?? null);

  // The id declared inside the content, even when the host asked for a
  // different one. `innerRoot` is preferred so an exact match always wins.
  const declaredCompositionId =
    (innerRoot ?? compositionRoots[0])?.getAttribute(COMPOSITION_ID_ATTR)?.trim() || "";

  // A templated composition's <head> belongs to its host page, not to it.
  const assetHead = hasTemplate ? null : (head ?? null);
  const mountedInert = innerRoot ? inertScripts(innerRoot) : [];

  return {
    innerRoot,
    authoredCompositionId: compositionId || declaredCompositionId || null,
    scriptCompositionId: declaredCompositionId || compositionId || null,
    authoredRootId: innerRoot?.getAttribute("id")?.trim() || null,
    styleSources: [
      ...toArray(assetHead?.querySelectorAll(STYLE_SELECTOR)),
      ...toArray(contentNode.querySelectorAll(STYLE_SELECTOR)),
    ],
    scriptSources: [...executableScripts(assetHead), ...executableScripts(contentNode)],
    linkSources: [
      ...toArray(head?.querySelectorAll(HOISTED_LINK_SELECTOR)),
      ...toArray(contentNode.querySelectorAll(HOISTED_LINK_SELECTOR)),
    ],
    inertScriptsOutsideRoot: [
      ...inertScripts(assetHead),
      ...(innerRoot ? inertScripts(contentNode).filter((el) => !mountedInert.includes(el)) : []),
    ],
    variableDefaultCarriers: [documentElement, innerRoot].filter(
      (carrier): carrier is TElement => carrier != null,
    ),
  };
}

// ---------------------------------------------------------------------------
// Nested hosts
// ---------------------------------------------------------------------------

export type NestedHostSkipReason = "circular composition reference" | "nesting depth exceeded";

export interface NestedCompositionHost<TElement> {
  host: TElement;
  src: string;
}

export interface NestedCompositionHosts<TElement> {
  hosts: NestedCompositionHost<TElement>[];
  skipped: { src: string; reason: NestedHostSkipReason }[];
}

/**
 * Enumerate the sub-composition hosts nested inside a composition that has just
 * been assembled, refusing the two shapes that do not terminate.
 *
 * `ancestry` is the chain down to and including the assembled composition's own
 * `src`, so a top-level host is enumerated with `[itsOwnSrc]`.
 */
export function enumerateNestedCompositionHosts<TElement extends AssemblyAttributed>(
  assembledHost: AssemblyQueryable<TElement>,
  ancestry: readonly string[],
): NestedCompositionHosts<TElement> {
  const hosts: NestedCompositionHost<TElement>[] = [];
  const skipped: { src: string; reason: NestedHostSkipReason }[] = [];

  for (const nestedHost of assembledHost.querySelectorAll(COMPOSITION_HOST_SELECTOR)) {
    const src = nestedHost.getAttribute(COMPOSITION_SRC_ATTR);
    if (!src) continue;
    if (ancestry.includes(src)) {
      skipped.push({ src, reason: "circular composition reference" });
      continue;
    }
    if (ancestry.length >= MAX_SUB_COMPOSITION_DEPTH) {
      skipped.push({ src, reason: "nesting depth exceeded" });
      continue;
    }
    hosts.push({ host: nestedHost, src });
  }

  return { hosts, skipped };
}

/** A mount sharing the page root's id counts as a repeat, so it is numbered instead of taking the root's timeline. */
export function countPageRoot(counts: Map<string, number>, hosts: readonly Element[]): void {
  const root = hosts[0]?.ownerDocument.querySelector("[data-composition-id]");
  const rootId = root && !hosts.includes(root) ? root.getAttribute("data-composition-id") : null;
  const mounts = rootId ? counts.get(rootId) : undefined;
  if (rootId && mounts) counts.set(rootId, mounts + 1);
}