@alloy-js/core 0.24.0-dev.1 → 0.24.0-dev.6

package/dist/src/debug/render.js

@@ -1,355 +1,507 @@
+/**
+ * Debug-render module — bridges the AlloyNode render tree to the
+ * trace-writer SQLite DB and the devtools WebSocket protocol.
+ *
+ * # Tree shape
+ *
+ * The trace tree mirrors the real AlloyNode tree. Component invocations
+ * are recorded separately as canonical metadata (`component_instances`
+ * and `component_roots`) so devtools can derive presentation groupings
+ * without storing UI artifacts as render nodes.
+ *
+ * Real AlloyNodes are exposed as:
+ *
+ *  - `TextNode` → `kind: "text"`, with `value: data`
+ *  - `ElementNode` with a marker `localName` (`alloy:source-file`,
+ *    `alloy:directory`, `alloy:copy-file`) → `kind` set to the marker
+ *  - any other `ElementNode` → `kind: "intrinsic"` with `name: localName`
+ *  - `FragmentNode` → `kind: "fragment"`
+ *  - `CommentNode` (slot/ctx markers) → not exposed (skipped)
+ *
+ * # Hook surface
+ *
+ * Mutation hooks:
+ *  - `nodeAttached(node, parent, before)` — called from
+ *    `render/node.ts::insertBefore`. Emits a `node_added` event for
+ *    `node` (and any descendants it brings with it, e.g. a previously
+ *    built subtree being moved or a fragment splice).
+ *  - `nodeDetached(node, parent)` — called from
+ *    `render/node.ts::detach`. Emits `node_removed` for `node` and all
+ *    descendants.
+ *
+ * Lifecycle hooks:
+ *  - `initialize(root)` — called at the start of each `render` /
+ *    `renderAsync`. Resets module state and emits `render:reset`.
+ *  - `complete()` — emits `render:complete`.
+ *  - `flushJobsComplete()` — emits `flushJobs:complete`.
+ *  - `error(info, stack)` — emits `render:error` and writes a
+ *    `render_errors` row.
+ *
+ * Component hooks:
+ *  - `beginComponent(opts)` — records a component instance and captures
+ *    the real top-level AlloyNodes it emits.
+ *
+ * Each hook short-circuits when neither devtools nor the trace DB
+ * are enabled.
+ */
+
 import { watch } from "@vue/reactivity";
 import * as devalue from "devalue";
 import { isDevtoolsEnabled, registerDevtoolsMessageHandler } from "../devtools/devtools-server.js";
-import { isPrintHook } from "../print-hook.js";
 import { getContext, untrack } from "../reactivity.js";
+import { getContextForNode } from "../render/node-context.js";
+import { AlloyNode, CommentNode, ELEMENT_NODE, FRAGMENT_NODE, setMutationListener, TEXT_NODE } from "../render/node.js";
 import { flushJobsAsync } from "../scheduler.js";
+import { flushAllDirtyFiles, markFileDirtyForNode, reset as resetFileStreaming } from "./file-streaming.js";
 import { sanitizeRecord } from "./serialize.js";
 import { resolveComponentSource } from "./source-map.js";
-import { deleteDirectory, deleteOutputFile, insertDirectory, insertOutputFile, insertRenderError, insertRenderNode, isTraceEnabled, notifyFlushComplete, notifyRenderComplete, notifyRenderReset, deleteRenderNode as traceDeleteRenderNode, updateRenderNodeProps as traceUpdateRenderNodeProps, updateEffectComponentByContext, updateRenderNodeContext } from "./trace-writer.js";
+import { deleteComponentInstance, deleteComponentRoot, insertComponentInstance, insertComponentRoot, insertDirectory, insertOutputFile, insertRenderError, isTraceEnabled, notifyFlushComplete, notifyRenderComplete, notifyRenderReset, deleteRenderNode as traceDeleteRenderNode, insertRenderNode as traceInsertRenderNode, updateComponentInstanceProps, updateEffectComponentByContext } from "./trace-writer.js";
 import { isDebugEnabled, logDevtoolsMessage } from "./trace.js";
 
+// #region Public debug types used by runtime and devtools integration
+
 /** The kind discriminant for render tree nodes. */
 
 /** Information about a render tree node, used when recording nodes to devtools. */
 
-/** Any node tracked by the devtools render tree. */
+export function isRerenderEnabled() {
+  return isDevtoolsEnabled();
+}
+// #endregion
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Module state — reset in initialize()
-// ─────────────────────────────────────────────────────────────────────────────
+// #region Module state
 
+/** Map AlloyNode → trace node id (assigned when first emitted). */
 let nodeIds = new WeakMap();
-let idToNode = new Map();
-let entryIds = new WeakMap();
-let nodeKinds = new WeakMap();
+/** AlloyNodes that have been emitted to the trace tree. */
+let tracked = new WeakSet();
+/** Component owner captured while a subtree is built before being rooted. */
+let pendingOwnerComponent = new WeakMap();
+/** Component roots captured while a subtree is built before being rooted. */
+let pendingRootComponents = new WeakMap();
+/** Sidecar metadata per node id — kind + name + source for cleanup re-emit. */
+let nodeKinds = new Map();
+/** Sidecar: nodes that own a file/directory entry in the trace DB. */
 let fileNodes = new Map();
 let directoryNodes = new Map();
+/** Latest props-serialized value per id (for de-duplicated updates). */
 let nodeProps = new Map();
+/** Devtools-side rerender bindings keyed by render-tree node id. */
 let rerenderActions = new Map();
-let nextId = 1;
-let handlerRegistered = false;
+let componentStack = [];
+let componentsById = new Map();
+let componentByContextId = new Map();
+let ownerComponentByNodeId = new Map();
+let childComponentsById = new Map();
+let rootComponentsByNodeId = new Map();
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Props serialization
-// ─────────────────────────────────────────────────────────────────────────────
-
-function serializeRenderTreeProps(input) {
-  return untrack(() => {
-    if (!input) return undefined;
-    const {
-      children: _children,
-      ...rest
-    } = input;
-    const sanitized = sanitizeRecord(rest);
-    if (!sanitized) return undefined;
-    try {
-      return devalue.stringify(sanitized);
-    } catch {
-      return undefined;
+/**
+ * Reverse index: parent render-tree id → set of currently-emitted child
+ * render-tree ids. Maintained by every `insertRenderNode` call in this
+ * module, and used by `emitRemoved` to cascade-remove descendants whose
+ * lifetime is bound to the removed parent.
+ */
+let renderChildIds = new Map();
+function insertRenderNode(id, parentId, kind, name, props, sourceFile, sourceLine, sourceCol, contextId, value) {
+  if (parentId !== null) {
+    let set = renderChildIds.get(parentId);
+    if (!set) {
+      set = new Set();
+      renderChildIds.set(parentId, set);
     }
-  });
+    set.add(id);
+  }
+  traceInsertRenderNode(id, parentId, kind, name, props, sourceFile, sourceLine, sourceCol, contextId, value);
 }
+let nextId = 1;
+let nextErrorId = 1;
+let handlerRegistered = false;
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Node ID management & tree structure
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
 
-function emitNodeRemoved(parentId, id) {
-  clearRenderTreeChildrenForId(id);
-  traceDeleteRenderNode(id);
-  rerenderActions.delete(id);
-  nodeProps.delete(id);
-  idToNode.delete(id);
-  const fileInfo = fileNodes.get(id);
-  if (fileInfo) {
-    deleteOutputFile(fileInfo.path);
-    fileNodes.delete(id);
+// #region Lifecycle
+
+export function initialize(root) {
+  for (const frame of componentsById.values()) {
+    frame.stopWatch?.();
   }
-  const dirInfo = directoryNodes.get(id);
-  if (dirInfo) {
-    deleteDirectory(dirInfo.path);
-    directoryNodes.delete(id);
+  if (!isDebugEnabled()) {
+    setMutationListener(null);
+    return;
   }
+  ensureDevtoolsHandler();
+  nodeIds = new WeakMap();
+  tracked = new WeakSet();
+  pendingOwnerComponent = new WeakMap();
+  pendingRootComponents = new WeakMap();
+  renderChildIds = new Map();
+  nodeKinds = new Map();
+  fileNodes = new Map();
+  directoryNodes = new Map();
+  nodeProps = new Map();
+  rerenderActions = new Map();
+  componentStack = [];
+  componentsById = new Map();
+  componentByContextId = new Map();
+  ownerComponentByNodeId = new Map();
+  childComponentsById = new Map();
+  rootComponentsByNodeId = new Map();
+  nextId = 1;
+  resetFileStreaming();
+  setMutationListener({
+    attached: nodeAttached,
+    detached: nodeDetached
+  });
+  notifyRenderReset();
+  const rootId = getOrCreateNodeId(root);
+  tracked.add(root);
+  nodeKinds.set(rootId, {
+    kind: "root"
+  });
+  insertRenderNode(rootId, null, "root", undefined, undefined, undefined, undefined, undefined, null, undefined);
 }
-function getEntryList(parent) {
-  let list = entryIds.get(parent);
-  if (!list) {
-    list = [];
-    entryIds.set(parent, list);
-  }
-  return list;
+export function complete() {
+  flushAllDirtyFiles();
+  logDevtoolsMessage({
+    type: "render:complete"
+  });
+  notifyRenderComplete();
+}
+export function flushJobsComplete() {
+  logDevtoolsMessage({
+    type: "flushJobs:complete"
+  });
+  notifyFlushComplete();
 }
+
+// #endregion
+
+// #region Node-id management
+
 function getOrCreateNodeId(node) {
   const existing = nodeIds.get(node);
-  if (existing) {
-    // Restore reverse mapping — emitNodeRemoved deletes idToNode but nodeIds
-    // (WeakMap) survives.  Without this, clearRenderTreeChildrenForId can't
-    // find the node on the next cleanup, leaving orphaned children in the DB.
-    idToNode.set(existing, node);
-    return existing;
-  }
+  if (existing !== undefined) return existing;
   const id = nextId++;
   nodeIds.set(node, id);
-  idToNode.set(id, node);
   return id;
 }
 export function getRenderNodeId(node) {
   if (!isDebugEnabled()) return undefined;
-  return getOrCreateNodeId(node);
+  if (!(node instanceof AlloyNode)) return undefined;
+  return nodeIds.get(node);
+}
+
+// #endregion
+
+// #region Kind classification
+
+const SKIPPED_COMMENT_DATAS = new Set(["slot:start", "slot:end", "slot:item:start", "slot:item:end", "ctx:start", "ctx:end", "component:start", "component:end"]);
+function shouldExposeNode(node) {
+  if (node instanceof CommentNode) {
+    // Bookkeeping comments are not part of the render tree.
+    return !SKIPPED_COMMENT_DATAS.has(node.data);
+  }
+  return true;
 }
-function setEntryId(parent, index, id) {
-  const list = getEntryList(parent);
-  list[index] = id;
+function classifyNode(node) {
+  const t = node.nodeType;
+  if (t === TEXT_NODE) {
+    return {
+      kind: "text",
+      value: node.data
+    };
+  }
+  if (t === FRAGMENT_NODE) {
+    return {
+      kind: "fragment"
+    };
+  }
+  if (t === ELEMENT_NODE) {
+    const ln = node.localName;
+    if (ln === "alloy:source-file" || ln === "alloy:directory" || ln === "alloy:copy-file") {
+      return {
+        kind: ln.slice("alloy:".length),
+        name: ln
+      };
+    }
+    return {
+      kind: "intrinsic",
+      name: ln
+    };
+  }
+  // CommentNode that's exposed — generic "comment" kind. Marker
+  // comments are filtered out by `shouldExposeNode`, so this is rare.
+  return {
+    kind: "comment",
+    value: node.data
+  };
 }
-export function initialize(root) {
-  if (!isDebugEnabled()) return;
-  ensureDevtoolsHandler();
-  nodeIds = new WeakMap();
-  idToNode = new Map();
-  entryIds = new WeakMap();
-  nodeKinds = new WeakMap();
-  fileNodes = new Map();
-  directoryNodes = new Map();
-  nodeProps = new Map();
-  rerenderActions = new Map();
-  nextId = 1;
-  notifyRenderReset();
-  const rootId = getOrCreateNodeId(root);
-  insertRenderNode(rootId, null, "root", undefined, undefined, undefined, undefined, undefined, null, undefined);
+
+// #endregion
+
+// #region Component ownership resolution
+
+function currentComponentFrame() {
+  return componentStack[componentStack.length - 1];
 }
-export function registerRenderNodeActions(node, actions) {
-  if (!isDebugEnabled()) return;
-  const id = getOrCreateNodeId(node);
-  rerenderActions.set(id, actions);
+function currentContextComponentFrame() {
+  const ctx = getContext();
+  return ctx ? componentByContextId.get(ctx.id) : undefined;
 }
-export function unregisterRenderNodeActions(node) {
-  if (!isDebugEnabled()) return;
-  const id = nodeIds.get(node);
-  if (id !== undefined) {
-    rerenderActions.delete(id);
+function findRootComponentsForAttach(parent) {
+  const frames = [];
+  for (let i = componentStack.length - 1; i >= 0; i--) {
+    const frame = componentStack[i];
+    if (frame.hostParent === parent) frames.unshift(frame);
   }
+  return frames;
 }
-function ensureDevtoolsHandler() {
-  if (handlerRegistered || !isDevtoolsEnabled()) return;
-  handlerRegistered = true;
-  registerDevtoolsMessageHandler(message => {
-    if (message.type !== "render:rerender" && message.type !== "render:rerenderAndBreak") {
-      return;
+function ownerFrameForAttach(parentId, inheritedOwner) {
+  if (inheritedOwner) return inheritedOwner;
+  const active = currentComponentFrame();
+  if (active) return active;
+  const contextFrame = currentContextComponentFrame();
+  if (contextFrame) return contextFrame;
+  if (parentId !== null) {
+    const parentOwner = ownerComponentByNodeId.get(parentId);
+    if (parentOwner !== undefined) return componentsById.get(parentOwner);
+  }
+  return undefined;
+}
+function recordComponentRoot(frame, renderNodeId) {
+  if (frame.rootSet.has(renderNodeId)) return;
+  frame.rootSet.add(renderNodeId);
+  const ordinal = frame.roots.length;
+  frame.roots.push(renderNodeId);
+  let components = rootComponentsByNodeId.get(renderNodeId);
+  if (!components) {
+    components = new Set();
+    rootComponentsByNodeId.set(renderNodeId, components);
+  }
+  components.add(frame.id);
+  insertComponentRoot(frame.id, renderNodeId, ordinal);
+  if (ordinal === 0) {
+    if (frame.file) {
+      fileNodes.set(renderNodeId, frame.file);
+      insertOutputFile(frame.file.path, frame.file.filetype, renderNodeId);
     }
-    const rawId = message.id;
-    if (typeof rawId !== "number" && typeof rawId !== "string") return;
-    const id = Number(rawId);
-    if (!Number.isFinite(id)) return;
-    const actions = rerenderActions.get(id);
-    if (!actions) return;
-    if (message.type === "render:rerender") {
-      actions.rerender();
-    } else {
-      actions.rerenderAndBreak();
+    if (frame.directory) {
+      directoryNodes.set(renderNodeId, frame.directory);
     }
-    void flushJobsAsync();
-  });
-}
-export function recordTextNode(parent, index, value) {
-  if (!isDebugEnabled()) return;
-  const id = nextId++;
-  setEntryId(parent, index, id);
-  insertRenderNode(id, getOrCreateNodeId(parent), "text", undefined, undefined, undefined, undefined, undefined, null, value);
+  }
+  if (frame.actions) rerenderActions.set(renderNodeId, frame.actions);
 }
-function recordNodeAdded(parent, index, node, info) {
-  if (!isDebugEnabled()) return;
-  const id = getOrCreateNodeId(node);
-  if (info.propsSerialized !== undefined) {
-    nodeProps.set(id, info.propsSerialized);
-  }
-  // Remember the kind and source so cached re-adds preserve them
-  nodeKinds.set(node, {
-    kind: info.kind,
-    name: info.name,
-    source: info.source
-  });
-  setEntryId(parent, index, id);
-  insertRenderNode(id, getOrCreateNodeId(parent), info.kind, info.name, info.propsSerialized, info.source?.fileName, info.source?.lineNumber, info.source?.columnNumber, null, undefined);
+function removeComponentRoot(frame, renderNodeId, deleteWhenEmpty = true) {
+  if (!frame.rootSet.delete(renderNodeId)) return;
+  frame.roots = frame.roots.filter(id => id !== renderNodeId);
+  const components = rootComponentsByNodeId.get(renderNodeId);
+  if (components) {
+    components.delete(frame.id);
+    if (components.size === 0) rootComponentsByNodeId.delete(renderNodeId);
+  }
+  deleteComponentRoot(frame.id, renderNodeId);
+  if (deleteWhenEmpty && frame.rootSet.size === 0) {
+    deleteComponentFrame(frame);
+  }
 }
-function recordSubtreeAdded(parentNode, subtree, info = {
-  kind: "fragment"
-}) {
-  if (!isDebugEnabled()) return;
-  const parentId = getOrCreateNodeId(parentNode);
-  // Check if this node was previously rendered (cached) by seeing if it already has an ID
-  const existingId = nodeIds.get(subtree);
-  const isCached = existingId !== undefined;
-  const id = isCached ? existingId : getOrCreateNodeId(subtree);
-  // Merge source from previously-saved nodeKinds if the caller didn't provide one
-  const savedKind = nodeKinds.get(subtree);
-  const source = info.source ?? savedKind?.source;
-  // Remember the kind and source so cached re-adds preserve them
-  nodeKinds.set(subtree, {
-    kind: info.kind,
-    name: info.name,
-    source
-  });
-  // Track in entryIds so clearRenderTreeChildren can find and remove it
-  if (Array.isArray(parentNode)) {
-    const list = getEntryList(parentNode);
-    list.push(id);
+function deleteComponentFrame(frame) {
+  if (!componentsById.delete(frame.id)) return;
+  const children = childComponentsById.get(frame.id);
+  if (children) {
+    childComponentsById.delete(frame.id);
+    for (const childId of [...children]) {
+      const child = componentsById.get(childId);
+      if (child) deleteComponentFrame(child);
+    }
   }
-  insertRenderNode(id, parentId, info.kind, info.name, info.propsSerialized, source?.fileName, source?.lineNumber, source?.columnNumber, null, undefined);
-
-  // For cached nodes, we need to recursively re-add all their children since
-  // clearRenderTreeChildren removed them when the parent re-rendered
-  if (isCached) {
-    recordCachedSubtreeChildrenRecursively(subtree);
+  for (const rootId of [...frame.roots]) {
+    removeComponentRoot(frame, rootId, false);
+  }
+  if (frame.parentComponentId !== null) {
+    const siblings = childComponentsById.get(frame.parentComponentId);
+    siblings?.delete(frame.id);
+  }
+  if (frame.contextId !== null && componentByContextId.get(frame.contextId)?.id === frame.id) {
+    componentByContextId.delete(frame.contextId);
   }
+  nodeProps.delete(frame.id);
+  frame.stopWatch?.();
+  deleteComponentInstance(frame.id);
 }
 
 /**
- * Recursively re-adds all children of a cached render tree node to devtools.
- * This is needed because clearRenderTreeChildren recursively removes all
- * descendants, but cached nodes aren't re-rendered so their children need
- * to be explicitly re-added.
+ * Decide whether `attachedParent` is currently part of the live trace
+ * tree (rooted at the initialized root), and if so which trace node id
+ * should be the new node's parent.
+ *
+ * Returns `undefined` when `attachedParent` isn't tracked — the caller
+ * should defer emission until the subtree is later attached at a
+ * tracked location.
  */
-function recordCachedSubtreeChildrenRecursively(node) {
-  if (!isDebugEnabled()) return;
-  const parentId = getOrCreateNodeId(node);
-
-  // Clear any previously-recorded children from the DB before re-adding.
-  // The in-memory tree may have changed since the last cached re-add
-  // (e.g., a memo inside the cached subtree re-ran), so old DB children
-  // that are no longer in the tree would become orphans.
-  clearRenderTreeChildren(node);
-
-  // Rebuild the entryIds for this node
-  const list = getEntryList(node);
-  list.length = 0;
-  for (let i = 0; i < node.length; i++) {
-    const child = node[i];
-    if (typeof child === "string") {
-      // Text nodes - re-record them with new IDs
-      if (child !== "") {
-        const id = nextId++;
-        list.push(id);
-        idToNode.set(id, child);
-        insertRenderNode(id, parentId, "text", undefined, undefined, undefined, undefined, undefined, null, child);
-      }
-    } else if (Array.isArray(child)) {
-      // Nested RenderedTextTree - record and recurse, preserving original kind and source
-      const id = getOrCreateNodeId(child);
-      list.push(id);
-      const savedKind = nodeKinds.get(child);
-      insertRenderNode(id, parentId, savedKind?.kind ?? "fragment", savedKind?.name, undefined, savedKind?.source?.fileName, savedKind?.source?.lineNumber, savedKind?.source?.columnNumber, null, undefined);
-      recordCachedSubtreeChildrenRecursively(child);
-    } else if (isPrintHook(child)) {
-      // PrintHook - record and recurse into subtree
-      const id = getOrCreateNodeId(child);
-      list.push(id);
-      insertRenderNode(id, parentId, "printHook", child.name ?? "hook", undefined, undefined, undefined, undefined, null, undefined);
-      if (child.subtree) {
-        const subtreeId = getOrCreateNodeId(child.subtree);
-        const hookList = getEntryList(child);
-        hookList.length = 0;
-        hookList.push(subtreeId);
-        insertRenderNode(subtreeId, id, "fragment", undefined, undefined, undefined, undefined, undefined, null, undefined);
-        recordCachedSubtreeChildrenRecursively(child.subtree);
-      }
-    }
+function resolveParentId(node, attachedParent) {
+  if (tracked.has(attachedParent)) {
+    const id = nodeIds.get(attachedParent);
+    return id === undefined ? null : id;
   }
+  return undefined;
 }
-function recordNodePropsUpdated(node, propsSerialized) {
-  if (!isDebugEnabled()) return;
-  const id = getOrCreateNodeId(node);
-  const previous = nodeProps.get(id);
-  if (previous === propsSerialized) return;
-  nodeProps.set(id, propsSerialized);
-  traceUpdateRenderNodeProps(id, propsSerialized);
-}
-function clearRenderTreeChildren(parent) {
+
+// #endregion
+
+// #region Tree-mutation hooks
+
+/**
+ * Called after `node` is attached as a child of `parent`. Emits an
+ * `added` event for `node` itself (if exposed) and recursively for any
+ * descendants it brought with it (move / fragment splice / cached subtree).
+ *
+ * If `parent` isn't part of the live tree yet, stamps the active component
+ * ownership onto `node` and defers emission until the subtree finally attaches.
+ */
+export function nodeAttached(node, parent) {
   if (!isDebugEnabled()) return;
-  const list = entryIds.get(parent);
-  if (!list || list.length === 0) return;
-  const parentId = getOrCreateNodeId(parent);
-  for (const id of list) {
-    if (id !== undefined) {
-      emitNodeRemoved(parentId, id);
-    }
+  markFileDirtyForNode(parent);
+  const parentId = resolveParentId(node, parent);
+  const ownerFrame = currentComponentFrame() ?? currentContextComponentFrame();
+  let rootFrames = findRootComponentsForAttach(parent);
+  if (rootFrames.length === 0 && ownerFrame !== undefined && parentId !== undefined && (parentId === null || ownerComponentByNodeId.get(parentId) !== ownerFrame.id)) {
+    rootFrames = [ownerFrame];
   }
-  entryIds.set(parent, []);
+  if (parentId === undefined) {
+    if (ownerFrame) pendingOwnerComponent.set(node, ownerFrame);
+    if (rootFrames.length > 0) pendingRootComponents.set(node, rootFrames);
+    return;
+  }
+  attachWithSelf(node, parentId, ownerFrame, rootFrames);
 }
-function clearRenderTreeChildrenForId(id) {
-  const node = idToNode.get(id);
-  if (!node) return;
-  if (Array.isArray(node)) {
-    clearRenderTreeChildren(node);
+function attachWithSelf(node, parentId, inheritedOwner, inheritedRoots) {
+  const pendingOwner = pendingOwnerComponent.get(node);
+  if (pendingOwner !== undefined) {
+    pendingOwnerComponent.delete(node);
+  }
+  const pendingRoots = pendingRootComponents.get(node);
+  if (pendingRoots !== undefined) {
+    pendingRootComponents.delete(node);
+  }
+  const ownerFrame = ownerFrameForAttach(parentId, pendingOwner ?? inheritedOwner);
+  const rootFrames = pendingRoots ?? inheritedRoots;
+  if (!shouldExposeNode(node)) {
+    for (let c = node.firstChild; c !== null; c = c.nextSibling) {
+      attachWithSelf(c, parentId, ownerFrame, rootFrames);
+    }
     return;
   }
-  // For PrintHook nodes: clear the subtree's children, then remove
-  // the subtree node itself (which is a child of this hook).
-  const subtree = node.subtree;
-  if (subtree && Array.isArray(subtree)) {
-    clearRenderTreeChildren(subtree);
-    const subtreeId = nodeIds.get(subtree);
-    if (subtreeId !== undefined) {
-      emitNodeRemoved(id, subtreeId);
+  if (tracked.has(node)) {
+    // Already eagerly emitted (e.g. an alloy:* wrapper pre-emitted via
+    // ensureWrapperHostTracked while inside a thunk body). Don't re-emit;
+    // just walk newly-attached children that may not have been seen yet.
+    const existingId = nodeIds.get(node);
+    for (let c = node.firstChild; c !== null; c = c.nextSibling) {
+      if (!tracked.has(c)) {
+        attachWithSelf(c, existingId, ownerFrame, []);
+      }
     }
+    return;
   }
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// File / directory node tracking
-// ─────────────────────────────────────────────────────────────────────────────
-
-function recordDirectoryNode(node, path) {
-  if (!isDebugEnabled()) return;
   const id = getOrCreateNodeId(node);
-  if (directoryNodes.has(id)) return;
-  directoryNodes.set(id, {
-    path
-  });
-  insertDirectory(path);
+  emitAdded(node, id, parentId);
+  tracked.add(node);
+  if (ownerFrame !== undefined) {
+    ownerComponentByNodeId.set(id, ownerFrame.id);
+  }
+  for (const rootFrame of rootFrames) {
+    recordComponentRoot(rootFrame, id);
+  }
+  for (let c = node.firstChild; c !== null; c = c.nextSibling) {
+    if (!tracked.has(c)) attachWithSelf(c, id, ownerFrame, []);
+  }
 }
-function recordFileNode(node, path, filetype) {
-  if (!isDebugEnabled()) return;
-  const id = getOrCreateNodeId(node);
-  if (fileNodes.has(id)) return;
-  fileNodes.set(id, {
-    path,
-    filetype
-  });
-  insertOutputFile(path, filetype, id);
+function emitAdded(node, id, parentId) {
+  const cls = classifyNode(node);
+  // Stamp metadata so cleanup re-emit (and `error()` stack resolution)
+  // can recover identity.
+  let entry = nodeKinds.get(id);
+  if (!entry) {
+    entry = {
+      kind: cls.kind,
+      name: cls.name
+    };
+    nodeKinds.set(id, entry);
+  } else {
+    entry.kind = cls.kind;
+    if (cls.name !== undefined) entry.name = cls.name;
+  }
+  const props = nodeProps.get(id);
+  insertRenderNode(id, parentId, cls.kind, cls.name, props, entry.source?.fileName, entry.source?.lineNumber, entry.source?.columnNumber, getContextForNode(node)?.id ?? null, cls.value);
 }
-function removeFileEntriesForNode(node) {
+
+/**
+ * Called after `node` has been detached. Emits `node_removed` for
+ * `node` and all of its still-attached descendants in post-order.
+ */
+export function nodeDetached(node, formerParent) {
   if (!isDebugEnabled()) return;
+  markFileDirtyForNode(formerParent);
+  detachRecursive(node);
+}
+function detachRecursive(node) {
+  for (let c = node.firstChild; c !== null; c = c.nextSibling) {
+    detachRecursive(c);
+  }
+  if (!tracked.has(node)) return;
+  tracked.delete(node);
+  if (!shouldExposeNode(node)) return;
   const id = nodeIds.get(node);
   if (id === undefined) return;
-  const fileInfo = fileNodes.get(id);
-  if (fileInfo) {
-    deleteOutputFile(fileInfo.path);
-    fileNodes.delete(id);
+  emitRemoved(id);
+}
+function emitRemoved(id) {
+  const componentIds = rootComponentsByNodeId.get(id);
+  if (componentIds) {
+    for (const componentId of [...componentIds]) {
+      const component = componentsById.get(componentId);
+      if (component) removeComponentRoot(component, id);
+    }
   }
-  const dirInfo = directoryNodes.get(id);
-  if (dirInfo) {
-    deleteDirectory(dirInfo.path);
-    directoryNodes.delete(id);
+  traceDeleteRenderNode(id);
+  rerenderActions.delete(id);
+  nodeProps.delete(id);
+  nodeKinds.delete(id);
+  // Files & directories owned by this node.
+  fileNodes.delete(id);
+  directoryNodes.delete(id);
+  ownerComponentByNodeId.delete(id);
+  // Cascade to any descendants currently registered as children of this id.
+  const children = renderChildIds.get(id);
+  if (children !== undefined) {
+    renderChildIds.delete(id);
+    for (const childId of children) {
+      emitRemoved(childId);
+    }
   }
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Public API — called from render.ts via the debug object
-// ─────────────────────────────────────────────────────────────────────────────
+// #endregion
 
-/** Begin tracking a component render. Returns a session to record files/dirs and dispose watchers. */
+// #region Component lifecycle
+
+function serializeRenderTreeProps(input) {
+  return untrack(() => {
+    if (!input) return undefined;
+    const {
+      children: _children,
+      ...rest
+    } = input;
+    const sanitized = sanitizeRecord(rest);
+    if (!sanitized) return undefined;
+    try {
+      return devalue.stringify(sanitized);
+    } catch {
+      return undefined;
+    }
+  });
+}
 export function beginComponent(options) {
-  const {
-    parent,
-    index,
-    node,
-    component,
-    propsSource,
-    source,
-    isExisting,
-    actions
-  } = options;
   if (!isDebugEnabled()) {
     return {
       recordDirectory() {},
@@ -357,6 +509,13 @@ export function beginComponent(options) {
       dispose() {}
     };
   }
+  const {
+    component,
+    propsSource,
+    source,
+    parent,
+    actions
+  } = options;
   return untrack(() => {
     let componentName = component.component.name;
     if (componentName === "Provider") {
@@ -367,86 +526,114 @@ export function beginComponent(options) {
     }
     const propsSerialized = serializeRenderTreeProps(propsSource);
     const resolvedSource = resolveComponentSource(source);
-    if (isExisting) {
-      clearRenderTreeChildren(node);
-    } else {
-      recordNodeAdded(parent, index, node, {
-        kind: "component",
-        name: componentName,
-        propsSerialized,
-        source: resolvedSource
-      });
-    }
-    if (isTraceEnabled()) {
-      const ctx = getContext();
-      if (ctx) {
-        updateRenderNodeContext(getOrCreateNodeId(node), ctx.id);
-        updateEffectComponentByContext(ctx.id, componentName);
+    const id = nextId++;
+    const ctx = getContext();
+    const parentComponent = componentStack[componentStack.length - 1] ?? (ctx?.owner ? componentByContextId.get(ctx.owner.id) : undefined);
+    const frame = {
+      id,
+      parentComponentId: parentComponent?.id ?? null,
+      hostParent: parent,
+      name: componentName,
+      propsSerialized,
+      source: resolvedSource,
+      contextId: ctx?.id ?? null,
+      roots: [],
+      rootSet: new Set(),
+      actions
+    };
+    componentsById.set(id, frame);
+    if (frame.parentComponentId !== null) {
+      let children = childComponentsById.get(frame.parentComponentId);
+      if (!children) {
+        children = new Set();
+        childComponentsById.set(frame.parentComponentId, children);
       }
+      children.add(id);
+    }
+    componentStack.push(frame);
+    if (ctx) componentByContextId.set(ctx.id, frame);
+    if (propsSerialized !== undefined) nodeProps.set(id, propsSerialized);
+    insertComponentInstance(id, frame.parentComponentId, componentName, propsSerialized, resolvedSource?.fileName, resolvedSource?.lineNumber, resolvedSource?.columnNumber, frame.contextId);
+    if (isTraceEnabled() && ctx) {
+      updateEffectComponentByContext(ctx.id, componentName);
     }
-    recordNodePropsUpdated(node, propsSerialized);
-    registerRenderNodeActions(node, actions);
+
+    // Watch reactive props and re-emit on change.
     let stopWatch;
     if (propsSource) {
-      const propKeys = Object.keys(propsSource).filter(key => key !== "children");
+      const propKeys = Object.keys(propsSource).filter(k => k !== "children");
       if (propKeys.length > 0) {
-        stopWatch = watch(() => propKeys.map(key => propsSource[key]), () => {
-          const nextSerialized = serializeRenderTreeProps(propsSource);
-          recordNodePropsUpdated(node, nextSerialized);
+        stopWatch = watch(() => propKeys.map(k => propsSource[k]), () => {
+          const next = serializeRenderTreeProps(propsSource);
+          const previous = nodeProps.get(id);
+          if (previous === next) return;
+          nodeProps.set(id, next);
+          updateComponentInstanceProps(id, next);
         });
       }
     }
+    frame.stopWatch = stopWatch;
+    let disposed = false;
     return {
       recordDirectory(path) {
-        recordDirectoryNode(node, path);
+        if (frame.directory) return;
+        frame.directory = {
+          path
+        };
+        insertDirectory(path);
       },
       recordFile(path, filetype) {
-        recordFileNode(node, path, filetype);
+        if (frame.file) return;
+        frame.file = {
+          path,
+          filetype
+        };
       },
       dispose() {
-        stopWatch?.();
-        removeFileEntriesForNode(node);
-        unregisterRenderNodeActions(node);
+        if (disposed) return;
+        disposed = true;
+        for (let i = componentStack.length - 1; i >= 0; i--) {
+          if (componentStack[i].id === id) {
+            componentStack.splice(i, 1);
+            break;
+          }
+        }
       }
     };
   });
 }
-export function appendCustomContext(parent, node) {
-  recordSubtreeAdded(parent, node, {
-    kind: "customContext"
-  });
-}
-export function appendPrintHook(parent, index, hook, name, subtree) {
-  recordNodeAdded(parent, index, hook, {
-    kind: "printHook",
-    name
-  });
-  if (subtree) {
-    recordSubtreeAdded(hook, subtree);
-  }
-}
-export function appendFragmentChild(parent, child) {
-  recordSubtreeAdded(parent, child, {
-    kind: "fragment"
-  });
-}
-export function appendTextNode(parent, index, value) {
-  recordTextNode(parent, index, value);
-}
-export function prepareMemoNode(parent, node, isExisting) {
-  if (isExisting) {
-    clearRenderTreeChildren(node);
-    return;
-  }
-  recordSubtreeAdded(parent, node, {
-    kind: "memo"
+
+// #endregion
+
+// #region Devtools rerender bridge
+
+function ensureDevtoolsHandler() {
+  if (handlerRegistered || !isDevtoolsEnabled()) return;
+  handlerRegistered = true;
+  registerDevtoolsMessageHandler(message => {
+    if (message.type !== "render:rerender" && message.type !== "render:rerenderAndBreak") {
+      return;
+    }
+    const rawId = message.id;
+    if (typeof rawId !== "number" && typeof rawId !== "string") return;
+    const id = Number(rawId);
+    if (!Number.isFinite(id)) return;
+    const actions = rerenderActions.get(id);
+    if (!actions) return;
+    if (message.type === "render:rerender") {
+      actions.rerender();
+    } else {
+      actions.rerenderAndBreak();
+    }
+    void flushJobsAsync();
   });
 }
-let nextErrorId = 1;
 
-/** Render error stack entry with optional runtime props (extends protocol type). */
+// #endregion
 
-export function error(error, componentStack) {
+// #region Errors
+
+export function error(err, componentStack) {
   if (!isDebugEnabled()) return;
   const serializedStack = untrack(() => componentStack.map(entry => ({
     name: entry.name,
@@ -457,23 +644,13 @@ export function error(error, componentStack) {
   logDevtoolsMessage({
     type: "render:error",
     id: nextErrorId++,
-    name: error.name,
-    message: error.message,
-    stack: error.stack,
+    name: err.name,
+    message: err.message,
+    stack: err.stack,
     componentStack: serializedStack
   });
-  insertRenderError(error.name, error.message, error.stack, JSON.stringify(serializedStack));
-}
-export function complete() {
-  logDevtoolsMessage({
-    type: "render:complete"
-  });
-  notifyRenderComplete();
-}
-export function flushJobsComplete() {
-  logDevtoolsMessage({
-    type: "flushJobs:complete"
-  });
-  notifyFlushComplete();
+  insertRenderError(err.name, err.message, err.stack, JSON.stringify(serializedStack));
 }
+
+// #endregion
 //# sourceMappingURL=render.js.map