Function handleAddElement

packages/sdk/src/engine/mutate.ts:690–730

(
  parsed: ParsedDocument,
  parent: HfId | null,
  index: number,
  html: string,
)

}

function handleAddElement(
  parsed: ParsedDocument,
  parent: HfId | null,
  index: number,
  html: string,
): MutationResult {
  // Resolve parent element (null → document body). Narrow rather than assert:
  // _dispatch does not run validateOp, so a bad parent id must not crash here.
  const parentEl =
    parent === null
      ? ((parsed.document as Document & { body?: Element | null }).body ?? null)
      : resolveScoped(parsed.document, parent);
  if (!parentEl) return EMPTY;

  const node = parseInsertableFragment(parsed.document, html);
  if (!node) return EMPTY;

  // Mint ids against the LIVE doc's existing id set (the #1 landmine — a fresh
  // ensureHfIds(fragment) is blind to existing doc ids and can collide).
  // Order: mint → capture outerHTML → insert → build patch (id needed for path).
  const assigned = collectDocumentHfIds(parsed.document);
  const newId = mintFragmentIds(node, assigned);
  const stampedHtml = node.outerHTML;

  // Insert at `index` — append if index >= childCount (RFC-6902 insert semantics).
  const ref = Array.from(parentEl.children)[index] ?? null;
  parentEl.insertBefore(node, ref);

  // parentId for the inverse/replay patch: preserve the caller's id verbatim
  // (scoped "hf-host/hf-leaf" path or composition id), not the bare data-hf-id —
  // apply-patches resolves it via findById→resolveScoped, so dropping the host
  // prefix would re-insert under the wrong (canonical) parent on redo/replay.
  const parentId = parent;

  const path = elementPath(newId);
  return {
    forward: [patchAdd(path, { html: stampedHtml, parentId, siblingIndex: index })],
    inverse: [patchRemove(path)],
    meta: { newId },
  };
}

function handleReorderElements(
  parsed: ParsedDocument,