@hypen-space/web 0.5.2 → 0.5.3

package/src/dom/renderer.ts

@@ -8,10 +8,42 @@ import type { Patch } from "@hypen-space/core/types";
 import type { HypenModuleInstance } from "@hypen-space/core/app";
 import type { HypenRouter } from "@hypen-space/core/router";
 import type { HypenGlobalContext } from "@hypen-space/core/context";
-import { frameworkLoggers } from "@hypen-space/core/logger";
+import { frameworkLoggers, isDebugMode } from "@hypen-space/core/logger";
 
 const log = frameworkLoggers.renderer;
 
+/** A compiled piece of a text template: literal text, or an `@{...}` binding. */
+type TemplateSegment = string | { match: string; keys: string[] };
+
+interface TextBinding {
+  element: HTMLElement;
+  template: string;
+  segments: TemplateSegment[];
+}
+
+/**
+ * Split a text template into literal and `@{state.path}` binding segments,
+ * so per-update interpolation walks pre-split paths instead of re-running
+ * the regex over the whole template.
+ */
+function compileTextTemplate(template: string): TemplateSegment[] {
+  const bindingPattern = /@\{([^}]+)\}/g;
+  const segments: TemplateSegment[] = [];
+  let last = 0;
+  let match: RegExpExecArray | null;
+  while ((match = bindingPattern.exec(template)) !== null) {
+    if (match.index > last) {
+      segments.push(template.slice(last, match.index));
+    }
+    segments.push({ match: match[0], keys: match[1]!.split(".") });
+    last = match.index + match[0].length;
+  }
+  if (last < template.length) {
+    segments.push(template.slice(last));
+  }
+  return segments;
+}
+
 /** Element types that treat the "action" prop as an onClick handler */
 const ACTIONABLE_TYPES = new Set(["button", "link", "card"]);
 
@@ -31,20 +63,48 @@ const COMPONENT_HTML_ATTRS: Record<string, Set<string>> = {
   checkbox: new Set(["checked", "disabled", "name"]),
   radio: new Set(["checked", "disabled", "name", "value"]),
   link: new Set(["href", "target", "rel"]),
+  // Route URL changes to the handler so it reconnects the embedded app
+  // instead of the generic text branch overwriting the subtree.
+  hypenapp: new Set(["0", "url"]),
 };
 
 import { ComponentRegistry } from "./components/index.js";
 import { ApplicatorRegistry } from "./applicators/index.js";
+import { applySemantics } from "./semantics.js";
+import {
+  makeKeyboardActivatable,
+  makeFocusTrap,
+  makeRovingTablist,
+  makeRovingListbox,
+  focusDialogOnOpen,
+  restoreDialogFocus,
+  installDialogEscape,
+} from "./operability.js";
+import { findRouteFocusTarget, focusRouteTarget } from "./route-focus.js";
+import type { Semantics } from "@hypen-space/core/types";
 import { canvasHandler, canvasApplicators } from "./canvas/index.js";
 import { CanvasRenderer } from "../canvas/renderer.js";
 import { RerenderTracker, type DebugConfig, defaultDebugConfig } from "./debug.js";
 import { setEngine, disposeHypenElement } from "./element-data.js";
+import { ensureA11yStyles } from "./a11y-styles.js";
 
 // Interface for the engine that renderer needs
 interface IEngine {
   dispatchAction(name: string, payload?: any): void;
 }
 
+export interface DOMRendererOptions {
+  /**
+   * Route-change focus contract (route-focus.ts). `"auto"` (default) moves
+   * focus to the incoming route's first heading / `main` landmark / subtree
+   * root on every navigation. `"off"` skips `focusIncomingRoute` entirely —
+   * the escape hatch for authors who own focus management themselves (custom
+   * transition choreography, embedded shells) and would otherwise fight the
+   * renderer for focus on every navigation.
+   */
+  routeFocus?: "auto" | "off";
+}
+
 export class DOMRenderer {
   private container: HTMLElement;
   private nodes: Map<string, HTMLElement> = new Map();
@@ -58,20 +118,68 @@ export class DOMRenderer {
   private componentInstances = new Map<string, HypenModuleInstance>();
   private debugTracker: RerenderTracker;
 
+  /**
+   * Text elements whose template contains an `@{...}` binding, with the
+   * template pre-compiled into segments. Only these nodes are visited on
+   * state changes — static text never re-interpolates.
+   */
+  private textBindings = new Map<string, TextBinding>();
+
   // Canvas subtree routing — Canvas components get their own CanvasRenderer
   // and all descendant patches are forwarded to it instead of the DOM.
   private canvasRenderers = new Map<string, CanvasRenderer>();
   private canvasSubtreeMap = new Map<string, string>(); // nodeId → canvasRootId
+  // Parent/child links within canvas subtrees, so removes can prune the
+  // routing maps without scanning every entry ever recorded.
+  private canvasNodeChildren = new Map<string, Set<string>>();
+  private canvasNodeParent = new Map<string, string>();
   private canvasElements = new Map<string, HTMLCanvasElement>();
   /** Props stashed at create-time so we can forward them to CanvasRenderer */
   private pendingCreateProps = new Map<string, { elementType: string; props: Record<string, any> }>();
 
-  constructor(container: HTMLElement, engine: IEngine, debugConfig?: Partial<DebugConfig>) {
+  /**
+   * Focus-restore memory for the Router subtree cache, keyed by detached
+   * subtree root id: the element that held focus when the route was
+   * detached, restored on cached re-`attach`. Entries are dropped on
+   * `remove` (Router LRU eviction) so focus restore can never target an
+   * evicted NodeId — the route-focus contract (see route-focus.ts).
+   */
+  private routeFocusMemory = new Map<string, HTMLElement>();
+
+  /** See `DOMRendererOptions.routeFocus` — `"off"` disables `focusIncomingRoute`. */
+  private routeFocus: "auto" | "off";
+
+  /** Ids created with `semantics.role === "dialog"`, so insert/remove hooks can act. */
+  private dialogIds = new Set<string>();
+  /**
+   * Open dialog id → the element that held focus before the dialog took it
+   * (the trigger), restored on dialog remove/detach when still connected.
+   * Presence of an entry means "already focused" — re-inserts (moves) of an
+   * open dialog never re-run the mount focus.
+   */
+  private dialogOpeners = new Map<string, HTMLElement | null>();
+  /**
+   * Dialog ids inserted during the current batch. Mount focus runs after the
+   * whole batch, because a dialog's focusable children may be inserted after
+   * the dialog's own insert patch.
+   */
+  private pendingDialogMounts: string[] = [];
+
+  constructor(
+    container: HTMLElement,
+    engine: IEngine,
+    debugConfig?: Partial<DebugConfig>,
+    options?: DOMRendererOptions,
+  ) {
     this.container = container;
     this.engine = engine;
     this.components = new ComponentRegistry();
     this.applicators = new ApplicatorRegistry();
     this.debugTracker = new RerenderTracker({ ...defaultDebugConfig, ...debugConfig });
+    this.routeFocus = options?.routeFocus ?? "auto";
+
+    // Inject the global reduced-motion + focus-visible stylesheet once.
+    ensureA11yStyles();
 
     // Match the canvas/iOS/Android renderers: text without an explicit
     // `.color()` defaults to black. Without this, DOM text would inherit
@@ -104,35 +212,76 @@ export class DOMRenderer {
    * the DOMRenderer or the owning CanvasRenderer.
    */
   applyPatches(patches: Patch[]): void {
-    // Phase 1: scan inserts to discover new canvas-subtree members
-    for (const patch of patches) {
-      if (patch.type === "insert" || patch.type === "move") {
-        const parentId = patch.parentId;
-        const childId = patch.id;
-        if (!parentId || !childId) continue;
-
-        // Is the parent a canvas root or inside a canvas subtree?
-        const canvasRootId =
-          this.canvasRenderers.has(parentId) ? parentId
-          : this.canvasSubtreeMap.get(parentId);
+    // Canvas routing only matters once a canvas root exists; the common
+    // no-canvas case applies the batch directly with no extra passes.
+    let canvasBatches: Map<string, Patch[]> | null = null;
+    let domPatches = patches;
+
+    if (this.canvasRenderers.size > 0 || this.canvasSubtreeMap.size > 0) {
+      // Phase 1: scan inserts to discover new canvas-subtree members
+      for (const patch of patches) {
+        if (patch.type === "insert" || patch.type === "move") {
+          const parentId = patch.parentId;
+          const childId = patch.id;
+          if (!parentId || !childId) continue;
+
+          // Is the parent a canvas root or inside a canvas subtree?
+          const canvasRootId =
+            this.canvasRenderers.has(parentId) ? parentId
+            : this.canvasSubtreeMap.get(parentId);
+          if (canvasRootId) {
+            this.registerCanvasMember(childId, parentId, canvasRootId);
+          }
+        }
+      }
+
+      // Phase 2: route patches
+      canvasBatches = new Map<string, Patch[]>();
+      domPatches = [];
+
+      for (const patch of patches) {
+        const canvasRootId = this.getCanvasRouteTarget(patch);
         if (canvasRootId) {
-          this.canvasSubtreeMap.set(childId, canvasRootId);
+          let batch = canvasBatches.get(canvasRootId);
+          if (!batch) { batch = []; canvasBatches.set(canvasRootId, batch); }
+          batch.push(patch);
+          if (patch.type === "remove" && patch.id) {
+            // Removed canvas nodes never come back (engine node ids are
+            // never reused), so drop their routing entries now.
+            this.pruneCanvasSubtree(patch.id);
+          }
+        } else {
+          domPatches.push(patch);
         }
       }
     }
 
-    // Phase 2: route patches
-    const canvasBatches = new Map<string, Patch[]>();
-    const domPatches: Patch[] = [];
-
-    for (const patch of patches) {
-      const canvasRootId = this.getCanvasRouteTarget(patch);
-      if (canvasRootId) {
-        let batch = canvasBatches.get(canvasRootId);
-        if (!batch) { batch = []; canvasBatches.set(canvasRootId, batch); }
-        batch.push(patch);
-      } else {
-        domPatches.push(patch);
+    // Route-change detection for the focus contract: a batch with a detach
+    // (route leaving) plus incoming subtree roots (attach of a cached route,
+    // or a fresh top-level create+insert) is a navigation. Initial renders
+    // have no detach, so they never steal focus.
+    const isNavigation = domPatches.some((p) => p.type === "detach");
+    const incomingRoots: string[] = [];
+    if (isNavigation) {
+      const createdInBatch = new Set<string>();
+      for (const p of domPatches) {
+        if (p.type === "create" && p.id) {
+          createdInBatch.add(p.id);
+        }
+      }
+      for (const p of domPatches) {
+        if (p.type === "attach" && p.id) {
+          incomingRoots.push(p.id);
+        } else if (
+          p.type === "insert" &&
+          p.id &&
+          createdInBatch.has(p.id) &&
+          (!p.parentId || !createdInBatch.has(p.parentId))
+        ) {
+          // A freshly-built subtree root: created in this batch, inserted
+          // under a parent that predates the batch (the router's slot).
+          incomingRoots.push(p.id);
+        }
       }
     }
 
@@ -142,12 +291,59 @@ export class DOMRenderer {
     }
 
     // Forward canvas-subtree patches to their CanvasRenderer instances
-    for (const [rootId, batch] of canvasBatches) {
-      const renderer = this.canvasRenderers.get(rootId);
-      if (renderer) {
-        renderer.applyPatches(batch);
+    if (canvasBatches) {
+      for (const [rootId, batch] of canvasBatches) {
+        const renderer = this.canvasRenderers.get(rootId);
+        if (renderer) {
+          renderer.applyPatches(batch);
+        }
       }
     }
+
+    if (isNavigation && incomingRoots.length > 0 && this.routeFocus !== "off") {
+      this.focusIncomingRoute(incomingRoots[0]!);
+    }
+
+    // Dialog mount focus runs last: a dialog opened by this batch takes
+    // focus even when the batch was also a navigation (modal wins).
+    this.flushDialogMounts();
+  }
+
+  /**
+   * Apply the dialog focus contract to dialogs inserted by the finished
+   * batch: focus the first focusable descendant, else the dialog itself, and
+   * remember the previously-focused element (the trigger) for restore on
+   * close. Deferred to batch end so descendants inserted after the dialog's
+   * own insert patch are visible to the focus search.
+   */
+  private flushDialogMounts(): void {
+    if (this.pendingDialogMounts.length === 0) return;
+    const pending = this.pendingDialogMounts;
+    this.pendingDialogMounts = [];
+    for (const id of pending) {
+      if (this.dialogOpeners.has(id)) continue; // already open — a move, not a mount
+      const dialog = this.nodes.get(id);
+      if (!dialog) continue;
+      this.dialogOpeners.set(id, focusDialogOnOpen(dialog));
+    }
+  }
+
+  /**
+   * Apply the route-focus contract to a freshly-shown route subtree: restore
+   * the remembered focus of a cached route when it is still inside the
+   * subtree, otherwise land on the first heading / main landmark / the
+   * subtree root (see route-focus.ts for the full contract).
+   */
+  private focusIncomingRoute(rootId: string): void {
+    const root = this.nodes.get(rootId);
+    if (!root) return;
+
+    const remembered = this.routeFocusMemory.get(rootId);
+    const target =
+      remembered && (root === remembered || root.contains?.(remembered))
+        ? remembered
+        : findRouteFocusTarget(root);
+    focusRouteTarget(target);
   }
 
   /**
@@ -182,6 +378,46 @@ export class DOMRenderer {
     }
   }
 
+  /**
+   * Record a node as a member of a canvas subtree, tracking its parent link
+   * so a later `remove` can prune the whole subtree from the routing maps.
+   */
+  private registerCanvasMember(childId: string, parentId: string, canvasRootId: string): void {
+    this.canvasSubtreeMap.set(childId, canvasRootId);
+    const prevParent = this.canvasNodeParent.get(childId);
+    if (prevParent !== undefined && prevParent !== parentId) {
+      this.canvasNodeChildren.get(prevParent)?.delete(childId);
+    }
+    this.canvasNodeParent.set(childId, parentId);
+    let siblings = this.canvasNodeChildren.get(parentId);
+    if (!siblings) {
+      siblings = new Set();
+      this.canvasNodeChildren.set(parentId, siblings);
+    }
+    siblings.add(childId);
+  }
+
+  /**
+   * Drop a removed canvas node and all of its descendants from the canvas
+   * routing maps. The engine emits `remove` only for the subtree root, so
+   * descendants are walked via the tracked child links.
+   */
+  private pruneCanvasSubtree(id: string): void {
+    const children = this.canvasNodeChildren.get(id);
+    if (children) {
+      this.canvasNodeChildren.delete(id);
+      for (const childId of children) {
+        this.pruneCanvasSubtree(childId);
+      }
+    }
+    this.canvasSubtreeMap.delete(id);
+    const parentId = this.canvasNodeParent.get(id);
+    if (parentId !== undefined) {
+      this.canvasNodeParent.delete(id);
+      this.canvasNodeChildren.get(parentId)?.delete(id);
+    }
+  }
+
   /**
    * Update state and interpolate text content
    */
@@ -201,42 +437,64 @@ export class DOMRenderer {
   }
 
   /**
-   * Interpolate state values in all text elements
+   * Interpolate state values in all binding-bearing text elements
    */
   private interpolateAllText(): void {
-    for (const [id, element] of this.nodes.entries()) {
-      if (element.dataset.hypenType === "text" && element.dataset.textTemplate) {
-        const template = element.dataset.textTemplate;
-        const interpolated = this.interpolateText(template, this.currentState);
-
-        // Track re-render if text actually changed
-        const currentText = element.textContent;
-        if (currentText !== interpolated) {
-          this.debugTracker.trackRerender(id, element, "interpolate");
-        }
-
+    for (const [id, binding] of this.textBindings) {
+      const interpolated = this.interpolateSegments(binding.segments, this.currentState);
+      const element = binding.element;
+      if (element.textContent !== interpolated) {
+        this.debugTracker.trackRerender(id, element, "interpolate");
         element.textContent = interpolated;
       }
     }
   }
 
   /**
-   * Interpolate state values in text template.
+   * Resolve a compiled template against the current state.
    *
-   * Bindings use the `@{state.path}` syntax (matching the engine's parser).
+   * Bindings use the `@{state.path}` syntax (matching the engine's parser);
+   * unresolvable bindings render as their original `@{...}` text.
    */
-  private interpolateText(template: string, state: Record<string, any>): string {
-    return template.replace(/@\{([^}]+)\}/g, (match, path) => {
+  private interpolateSegments(segments: TemplateSegment[], state: Record<string, any>): string {
+    let result = "";
+    for (const segment of segments) {
+      if (typeof segment === "string") {
+        result += segment;
+        continue;
+      }
       try {
-        const value = path.split('.').reduce((obj: any, key: string) => {
-          if (key === 'state') return state;
-          return obj?.[key];
-        }, state);
-        return value !== undefined ? String(value) : match;
+        let value: any = state;
+        for (const key of segment.keys) {
+          value = key === "state" ? state : value?.[key];
+        }
+        result += value !== undefined ? String(value) : segment.match;
       } catch {
-        return match;
+        result += segment.match;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Keep the binding index in sync with the element's stored template:
+   * register text elements whose template contains an `@{...}` binding,
+   * drop everything else.
+   */
+  private syncTextBinding(id: string, element: HTMLElement): void {
+    const template = element.dataset.textTemplate;
+    if (element.dataset.hypenType === "text" && template && template.includes("@{")) {
+      const existing = this.textBindings.get(id);
+      if (!existing || existing.template !== template || existing.element !== element) {
+        this.textBindings.set(id, {
+          element,
+          template,
+          segments: compileTextTemplate(template),
+        });
       }
-    });
+    } else {
+      this.textBindings.delete(id);
+    }
   }
 
   /**
@@ -250,7 +508,7 @@ export class DOMRenderer {
 
     switch (patch.type) {
       case "create":
-        this.onCreate(id!, elementType ?? "container", patch.props || {});
+        this.onCreate(id!, elementType ?? "container", patch.props || {}, patch.semantics);
         break;
       case "setProp":
         this.onSetProp(id!, patch.name!, patch.value);
@@ -276,13 +534,33 @@ export class DOMRenderer {
       case "attach":
         this.onInsert(parentId!, id!, beforeId);
         break;
+      case "setSemantics":
+        this.onSetSemantics(id!, patch.semantics);
+        break;
+    }
+  }
+
+  /**
+   * Reactive accessibility update: re-run the create-time semantics
+   * translation on the live element with the node's complete re-resolved
+   * block. `applySemantics` is idempotent and clears attributes it set on a
+   * previous pass that the new block no longer produces. This is the sole
+   * ARIA writer for bound self-state — the SetProp that accompanies a bound
+   * `.expanded(@state.open)` change does not touch ARIA attributes.
+   */
+  private onSetSemantics(id: string, semantics?: Semantics): void {
+    const element = this.nodes.get(id);
+    if (!element) {
+      log.warn(`setSemantics: element ${id} not found`);
+      return;
     }
+    applySemantics(element, semantics);
   }
 
   /**
    * Create a new element
    */
-  private onCreate(id: string, elementType: string, props: Record<string, any> | Map<string, any>): void {
+  private onCreate(id: string, elementType: string, props: Record<string, any> | Map<string, any>, semantics?: Semantics): void {
     const propsObj = props instanceof Map ? Object.fromEntries(props) : props;
 
     let element = this.components.createElement(elementType, propsObj);
@@ -302,14 +580,60 @@ export class DOMRenderer {
     element.dataset.hypenId = id;
     setEngine(element, this.engine);
 
+    // Slot marker: `.slot("name")` lowers to the `slot.0` prop. The engine
+    // resolves slots during component expansion, but container components
+    // that own their children natively (HypenApp's loading/error slots)
+    // need to identify slotted children at the DOM level.
+    const slotName = propsObj["slot.0"] ?? propsObj.slot;
+    if (typeof slotName === "string" && slotName) {
+      element.dataset.hypenSlot = slotName;
+    }
+
+    // Apply engine-derived accessibility semantics (role, …) before styling
+    // props, so a redundant-role check sees the final host tag.
+    applySemantics(element, semantics);
+
+    // Dialog-like containers trap keyboard focus so Tab cycles within the
+    // dialog rather than escaping to the page behind it. Mount focus and
+    // restore-to-trigger run on insert/remove (tracked via dialogIds) — the
+    // element isn't in the document yet at create time. Escape closes only
+    // when the author declared an onClose action; without one, closing is
+    // app state and Escape does nothing.
+    if (semantics?.role === "dialog") {
+      makeFocusTrap(element);
+      this.dialogIds.add(id);
+      const onClose = propsObj.onClose ?? propsObj["onClose.0"];
+      if (onClose) {
+        installDialogEscape(element, onClose);
+      }
+    }
+
+    // Tablists get the WAI-ARIA roving-tabindex keyboard contract: arrows
+    // move focus among the role="tab" children, Home/End jump to the ends,
+    // only the focused tab stays in the page Tab order, and printable
+    // characters typeahead to the next matching tab.
+    if (semantics?.role === "tablist") {
+      makeRovingTablist(element);
+    }
+
+    // Listboxes get the same roving + typeahead contract over their
+    // role="option" children (no-op on a native <select> host, where the
+    // browser owns the keyboard behaviour).
+    if (semantics?.role === "listbox") {
+      makeRovingListbox(element);
+    }
+
     this.applicators.applyAll(element, propsObj);
 
-    // Actionable components: wire "action" prop as onClick
+    // Actionable components: wire "action" prop as onClick, and make
+    // non-native hosts (e.g. an actionable Card div) keyboard-operable.
     if (propsObj.action && ACTIONABLE_TYPES.has(elementType.toLowerCase())) {
       this.applicators.apply(element, "onClick", propsObj.action);
+      makeKeyboardActivatable(element, propsObj.action);
     }
 
     this.nodes.set(id, element);
+    this.syncTextBinding(id, element);
     this.debugTracker.trackRerender(id, element, `create:${elementType}`);
 
     // Canvas component: create a CanvasRenderer for its subtree
@@ -391,6 +715,7 @@ export class DOMRenderer {
         // If current template isn't a template, keep it in sync.
         element.dataset.textTemplate = nextText;
       }
+      this.syncTextBinding(id, element);
       log.debug(`Updated text content: "${value}"`);
       return;
     }
@@ -398,6 +723,7 @@ export class DOMRenderer {
     // Actionable components: wire "action" prop as onClick
     if (name === "action" && ACTIONABLE_TYPES.has(element.dataset.hypenType || "")) {
       this.applicators.apply(element, "onClick", value);
+      makeKeyboardActivatable(element, value);
       return;
     }
 
@@ -455,11 +781,16 @@ export class DOMRenderer {
     const parent = parentId === "root" ? this.container : this.nodes.get(parentId);
     const child = this.nodes.get(id);
 
-    log.debug(`Inserting ${id} into ${parentId}`, {
-      parent: parent ? `${parent.tagName}#${parent.id || 'no-id'}` : 'null',
-      child: child ? `${child.tagName}#${child.id || 'no-id'}` : 'null',
-      childText: child?.textContent?.substring(0, 20)
-    });
+    // Gated up front: building the payload reads `textContent`, which
+    // serializes the whole subtree's text — too costly to pay when debug
+    // logging is off.
+    if (isDebugMode()) {
+      log.debug(`Inserting ${id} into ${parentId}`, {
+        parent: parent ? `${parent.tagName}#${parent.id || 'no-id'}` : 'null',
+        child: child ? `${child.tagName}#${child.id || 'no-id'}` : 'null',
+        childText: child?.textContent?.substring(0, 20)
+      });
+    }
 
     if (!parent || !child) return;
 
@@ -479,6 +810,13 @@ export class DOMRenderer {
         parent.appendChild(child);
       }
     }
+
+    // Dialog entering the document (insert or cached re-attach): queue mount
+    // focus for the end of the batch (flushDialogMounts). Already-open
+    // dialogs are filtered there, so moves never re-focus.
+    if (this.dialogIds.has(id)) {
+      this.pendingDialogMounts.push(id);
+    }
   }
 
   /**
@@ -509,10 +847,26 @@ export class DOMRenderer {
     const element = this.nodes.get(id);
     if (!element) return;
 
+    // Remember where focus was inside the leaving route, so a cached
+    // re-`attach` of this subtree can restore it (route-focus contract).
+    const active = (element.ownerDocument?.activeElement ??
+      (typeof document !== "undefined" ? document.activeElement : null)) as HTMLElement | null;
+    if (active && (element === active || element.contains?.(active))) {
+      this.routeFocusMemory.set(id, active);
+    }
+
     if (element.parentNode) {
       element.parentNode.removeChild(element);
     }
 
+    // Any open dialog inside the detached subtree just left the document:
+    // restore its trigger (a trigger detached along with it fails the
+    // connectivity check and is skipped — the route-focus contract owns
+    // focus for the incoming route). Runs after the DOM unlink so the
+    // connectivity check reflects the detach. dialogIds keeps the id — a
+    // cached re-attach re-runs mount focus.
+    this.restoreDialogsWithin(element);
+
     // If the root gets detached (unlikely but defensible), clear
     // rootId so a later attach can re-root cleanly.
     if (this.rootId === id) {
@@ -520,6 +874,23 @@ export class DOMRenderer {
     }
   }
 
+  /**
+   * Close-side of the dialog focus contract: every open dialog at-or-under
+   * `subtree` has left the document — restore focus to its remembered
+   * trigger (when still connected) and drop the open entry so a later
+   * insert/attach counts as a fresh mount.
+   */
+  private restoreDialogsWithin(subtree: HTMLElement): void {
+    if (this.dialogOpeners.size === 0) return;
+    for (const [dialogId, opener] of this.dialogOpeners) {
+      const dialog = this.nodes.get(dialogId);
+      if (!dialog || subtree === dialog || subtree.contains?.(dialog)) {
+        this.dialogOpeners.delete(dialogId);
+        if (dialog) restoreDialogFocus(dialog, opener);
+      }
+    }
+  }
+
   /**
    * Remove an element from the tree
    */
@@ -533,8 +904,12 @@ export class DOMRenderer {
       this.canvasRenderers.delete(id);
       this.canvasElements.delete(id);
       // Remove all subtree entries pointing to this canvas root
-      for (const [nodeId, rootId] of this.canvasSubtreeMap) {
-        if (rootId === id) this.canvasSubtreeMap.delete(nodeId);
+      const members = this.canvasNodeChildren.get(id);
+      if (members) {
+        this.canvasNodeChildren.delete(id);
+        for (const childId of members) {
+          this.pruneCanvasSubtree(childId);
+        }
       }
     }
 
@@ -545,7 +920,17 @@ export class DOMRenderer {
       element.parentNode.removeChild(element);
     }
 
+    // Restore-to-trigger for any open dialog in the removed subtree, before
+    // the node map forgets it. The removed subtree is gone for good, so the
+    // dialog id is dropped too.
+    this.restoreDialogsWithin(element);
+
     this.nodes.delete(id);
+    this.textBindings.delete(id);
+    this.dialogIds.delete(id);
+    // Router LRU eviction: this subtree is gone for good — focus restore
+    // must never target it again (route-focus contract).
+    this.routeFocusMemory.delete(id);
 
     if (this.rootId === id) {
       this.rootId = null;
@@ -570,6 +955,8 @@ export class DOMRenderer {
     this.canvasRenderers.clear();
     this.canvasElements.clear();
     this.canvasSubtreeMap.clear();
+    this.canvasNodeChildren.clear();
+    this.canvasNodeParent.clear();
 
     // Dispose all element resources before clearing
     for (const element of this.nodes.values()) {
@@ -577,7 +964,12 @@ export class DOMRenderer {
     }
     this.container.innerHTML = "";
     this.nodes.clear();
+    this.textBindings.clear();
     this.rootId = null;
+    this.dialogIds.clear();
+    this.dialogOpeners.clear();
+    this.pendingDialogMounts = [];
+    this.routeFocusMemory.clear();
   }
 
   /**