Skip to content

Write HTML. Render video. Built for agents.

8.7 KB
Raw Blame
/**
 * Opaque element handles: the one thing reads mint and writes consume.
 *
 * `TimelineElement.id` cannot do this job. It is a SYNTHESISED identity built
 * from label, index, selector and source file when the clip has no authored id
 * (`timelineElementHelpers.buildTimelineElementIdentity`), so
 * `getElementById(element.id)` misses most elements. The real addressing fields
 * are separate: `hfId` (the `data-hf-id` the codebase calls the stable primary
 * patch target), `domId`, and a `selector` plus occurrence index.
 *
 * Handles are strings so they survive a JSON round trip through the agent
 * untouched. The agent never builds one; it passes back what a read gave it.
 */

import type { TimelineElement } from "../player/store/timelineElement";
import { findElementForSelection } from "../components/editor/domEditingElement";
import type { PatchTarget } from "../utils/sourcePatcher";

const SEPARATOR = ":";
const INDEX_SEPARATOR = "#";

/**
 * How to find one element. `TimelineElement` calls the DOM id `domId` and
 * `PatchTarget` calls it `id`, so both adapt into this rather than the minter
 * knowing about either.
 */
export interface ElementAddress {
  projectId?: string | null;
  hfId?: string;
  domId?: string | null;
  selector?: string;
  selectorIndex?: number;
  sourceFile?: string;
  activeCompositionPath?: string | null;
}

/**
 * Address an element the same way Studio's own patcher does, most stable first.
 * `data-hf-id` survives edits that renumber or reorder; a bare selector does not.
 */
export function mintElementHandle(address: ElementAddress): string | null {
  const scoped = (value: string) => {
    if (!address.sourceFile || !address.activeCompositionPath) return value;
    if (address.projectId) {
      return [
        "v2",
        encodeURIComponent(address.projectId),
        encodeURIComponent(address.activeCompositionPath),
        encodeURIComponent(address.sourceFile),
        encodeURIComponent(value),
      ].join(SEPARATOR);
    }
    return [
      "v1",
      encodeURIComponent(address.activeCompositionPath),
      encodeURIComponent(address.sourceFile),
      encodeURIComponent(value),
    ].join(SEPARATOR);
  };

  if (address.hfId) return `hf${SEPARATOR}${scoped(address.hfId)}`;
  if (address.domId) return `dom${SEPARATOR}${scoped(address.domId)}`;
  if (address.selector) {
    const index = address.selectorIndex ?? 0;
    return `sel${SEPARATOR}${scoped(address.selector)}${INDEX_SEPARATOR}${index}`;
  }
  return null;
}

export function timelineElementAddress(
  element: TimelineElement,
  activeCompositionPath: string | null = "index.html",
  projectId?: string | null,
): ElementAddress {
  const rootFile = activeCompositionPath ?? "index.html";
  return {
    projectId,
    hfId: element.hfId,
    domId: element.domId,
    selector: element.selector,
    selectorIndex: element.selectorIndex,
    sourceFile: element.sourceFile ?? rootFile,
    activeCompositionPath: rootFile,
  };
}

export function patchTargetAddress(
  target: PatchTarget & { sourceFile?: string },
  activeCompositionPath?: string | null,
  projectId?: string | null,
): ElementAddress {
  return {
    projectId,
    hfId: target.hfId,
    domId: target.id,
    selector: target.selector,
    selectorIndex: target.selectorIndex,
    sourceFile: target.sourceFile,
    activeCompositionPath,
  };
}

export interface ParsedHandle {
  scheme: "hf" | "dom" | "sel";
  version: 0 | 1 | 2;
  value: string;
  index: number;
  projectId?: string;
  sourceFile?: string;
  activeCompositionPath?: string;
}

function decodeScopedParts(rest: string, version: "v1" | "v2", count: number) {
  const parts = rest.split(SEPARATOR);
  if (parts[0] !== version || parts.length !== count + 1) return null;
  return parts.slice(1).map(decodeHandlePart);
}

function parseV1ScopedValue(rest: string): Omit<ParsedHandle, "scheme" | "index"> | null {
  const [activeCompositionPath, sourceFile, value] = decodeScopedParts(rest, "v1", 3) ?? [];
  if (!activeCompositionPath || !sourceFile || !value) return null;
  return { version: 1, value, sourceFile, activeCompositionPath };
}

function parseV2ScopedValue(rest: string): Omit<ParsedHandle, "scheme" | "index"> | null {
  const [projectId, activeCompositionPath, sourceFile, value] =
    decodeScopedParts(rest, "v2", 4) ?? [];
  if (!projectId || !activeCompositionPath || !sourceFile || !value) return null;
  return { version: 2, projectId, value, sourceFile, activeCompositionPath };
}

function parseScopedValue(rest: string): Omit<ParsedHandle, "scheme" | "index"> | null {
  if (rest.startsWith(`v1${SEPARATOR}`)) return parseV1ScopedValue(rest);
  if (rest.startsWith(`v2${SEPARATOR}`)) return parseV2ScopedValue(rest);
  return { value: rest, version: 0 };
}

function decodeHandlePart(value: string): string | null {
  try {
    return decodeURIComponent(value) || null;
  } catch {
    return null;
  }
}

export function parseElementHandle(handle: string): ParsedHandle | null {
  const separatorAt = handle.indexOf(SEPARATOR);
  if (separatorAt <= 0) return null;
  const scheme = handle.slice(0, separatorAt);
  const rest = handle.slice(separatorAt + 1);
  if (!rest) return null;
  if (scheme === "hf" || scheme === "dom") {
    const scoped = parseScopedValue(rest);
    return scoped ? { scheme, ...scoped, index: 0 } : null;
  }
  if (scheme !== "sel") return null;

  // Only the LAST `#` splits the index off: CSS selectors contain `#` themselves.
  const indexAt = rest.lastIndexOf(INDEX_SEPARATOR);
  if (indexAt <= 0) {
    const scoped = parseScopedValue(rest);
    return scoped ? { scheme, ...scoped, index: 0 } : null;
  }
  const index = Number(rest.slice(indexAt + 1));
  if (!Number.isInteger(index) || index < 0) {
    const scoped = parseScopedValue(rest);
    return scoped ? { scheme, ...scoped, index: 0 } : null;
  }
  const scoped = parseScopedValue(rest.slice(0, indexAt));
  return scoped ? { scheme, ...scoped, index } : null;
}

/**
 * Resolve a handle against the preview document.
 *
 * Always re-resolve per call rather than holding an element across calls: a
 * preview reload replaces the document, and a node from the destroyed one is
 * detached but still looks like an element.
 */
export function resolveElementHandle(doc: Document, handle: string): HTMLElement | null {
  const parsed = parseElementHandle(handle);
  if (!parsed) return null;
  return findElementForSelection(
    doc,
    {
      hfId: parsed.scheme === "hf" ? parsed.value : undefined,
      id: parsed.scheme === "dom" ? parsed.value : undefined,
      selector: parsed.scheme === "sel" ? parsed.value : undefined,
      selectorIndex: parsed.scheme === "sel" ? parsed.index : undefined,
      sourceFile: parsed.sourceFile,
    },
    parsed.activeCompositionPath ?? null,
  );
}

/** Legacy read handles remain valid, but a scoped handle must name the active project. */
export function elementHandleMatchesProject(handle: string, projectId: string | null): boolean {
  const parsed = parseElementHandle(handle);
  if (!parsed) return false;
  return parsed.version !== 2 || (!!projectId && parsed.projectId === projectId);
}

export type LiveHandleResolution<T extends { element: HTMLElement }> =
  | { status: "ready"; selection: T }
  | { status: "preview-unavailable" }
  | { status: "not-found" }
  | { status: "unsupported" }
  | { status: "changed" };

/**
 * Resolve and build a selection across one possible preview reload.
 *
 * Building a selection can await a source probe. A thumbnail refresh may
 * replace the preview document during that await, leaving an otherwise valid
 * selection attached to the old document with a truthful-looking 0x0 box.
 * Reacquire once from the current document, then refuse if it moves again.
 */
export async function resolveLiveHandleSelection<T extends { element: HTMLElement }>(
  getPreviewDocument: () => Document | null,
  handle: string,
  buildSelection: (element: HTMLElement) => Promise<T | null>,
): Promise<LiveHandleResolution<T>> {
  let reloadObserved = false;
  for (let attempt = 0; attempt < 2; attempt += 1) {
    const doc = getPreviewDocument();
    if (!doc) return { status: "preview-unavailable" };
    const element = resolveElementHandle(doc, handle);
    if (!element) return { status: reloadObserved ? "changed" : "not-found" };

    const selection = await buildSelection(element);
    const currentDoc = getPreviewDocument();
    const previewChanged =
      currentDoc !== doc ||
      element.ownerDocument !== doc ||
      !element.isConnected ||
      (selection !== null &&
        (selection.element.ownerDocument !== doc || !selection.element.isConnected));
    if (previewChanged) {
      reloadObserved = true;
      continue;
    }
    if (!selection) return { status: "unsupported" };
    return { status: "ready", selection };
  }
  return { status: "changed" };
}