@hypen-space/web 0.4.81 → 0.4.83

package/src/canvas/paint.ts

@@ -9,6 +9,7 @@ import { renderText } from "./text.js";
 import { ScrollManager, isScrollable } from "./scroll.js";
 import { getVisibleChildren, VIRTUALIZE_THRESHOLD } from "./virtualize.js";
 import type { SelectionManager } from "./selection.js";
+import { cssLengthToPx } from "./utils.js";
 
 /**
  * Module-level reference to the active SelectionManager so paintText
@@ -151,9 +152,20 @@ export function paintNode(ctx: CanvasRenderingContext2D, node: VirtualNode): voi
       })
     : node.children;
 
+  // Paint flow children first, then absolute-positioned overlays on top.
+  // CSS uses `z-index` to order absolute siblings; Canvas just paints in
+  // tree order, so a `position: absolute` header declared FIRST in the
+  // tree (Story uses this for its close button) gets covered by the
+  // following in-flow Image. Push absolute kids to the end so they land
+  // on top — same effect as `z-index: auto` painting absolute after flow.
+  const flowKids: VirtualNode[] = [];
+  const overlayKids: VirtualNode[] = [];
   for (const child of childrenToPaint) {
-    paintNode(ctx, child);
+    if (child.props.position === "absolute") overlayKids.push(child);
+    else flowKids.push(child);
   }
+  for (const child of flowKids) paintNode(ctx, child);
+  for (const child of overlayKids) paintNode(ctx, child);
 
   // Undo scroll translation before drawing scrollbars
   if ((node as any)._scrollRestore) {
@@ -261,14 +273,14 @@ function paintText(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
 
   let text = String(props[0] || props.text || "");
   const color = props.color || "#000000";
-  const fontSize = parseFloat(props.fontSize) || 16;
+  const fontSize = cssLengthToPx(props.fontSize) ?? 16;
   const fontWeight = props.fontWeight || "normal";
   const fontFamily = props.fontFamily || "system-ui, sans-serif";
   const textAlign = props.textAlign || "left";
-  const lineHeight = parseFloat(props.lineHeight) || fontSize * 1.2;
+  const lineHeight = cssLengthToPx(props.lineHeight) ?? fontSize * 1.2;
   const textDecoration = props.textDecoration || "none";
   const textTransform = props.textTransform || "none";
-  const letterSpacing = parseFloat(props.letterSpacing) || 0;
+  const letterSpacing = cssLengthToPx(props.letterSpacing) ?? 0;
 
   // Apply text transform
   if (textTransform === "uppercase") {
@@ -366,13 +378,29 @@ function paintButton(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
     applyShadow(ctx, shadow);
   }
 
-  // Background color based on state
-  let backgroundColor = props.backgroundColor || "#007bff";
+  // Background color based on state.
+  //
+  // Only the default-blue button derives a default hover/focus shade. When a
+  // caller supplies `backgroundColor` (including "transparent" for icon-style
+  // buttons), swap to hover/focus only if they _also_ supply an explicit
+  // hoverColor/focusColor — otherwise the caller's intent wins and we leave
+  // the base colour untouched. Without this, transparent nav buttons would
+  // flash a blue rectangle on hover.
+  const explicitBg = props.backgroundColor !== undefined;
+  let backgroundColor = explicitBg ? props.backgroundColor : "#007bff";
   if (node.hovered) {
-    backgroundColor = props.hoverColor || "#0056b3";
+    if (props.hoverColor !== undefined) {
+      backgroundColor = props.hoverColor;
+    } else if (!explicitBg) {
+      backgroundColor = "#0056b3";
+    }
   }
   if (node.focused) {
-    backgroundColor = props.focusColor || "#004085";
+    if (props.focusColor !== undefined) {
+      backgroundColor = props.focusColor;
+    } else if (!explicitBg) {
+      backgroundColor = "#004085";
+    }
   }
 
   // Support gradients for button background
@@ -441,10 +469,10 @@ function paintInput(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
   const textColor = value ? (props.color || "#000000") : "#999999";
 
   if (text) {
-    const fontSize = parseFloat(props.fontSize) || 16;
+    const fontSize = cssLengthToPx(props.fontSize) ?? 16;
     const fontWeight = props.fontWeight || "normal";
     const fontFamily = props.fontFamily || "system-ui, sans-serif";
-    const lineHeight = parseFloat(props.lineHeight) || fontSize * 1.2;
+    const lineHeight = cssLengthToPx(props.lineHeight) ?? fontSize * 1.2;
 
     renderText(
       ctx,
@@ -478,6 +506,28 @@ const imageFailCache = new Map<string, { failedAt: number; attempts: number }>()
 const IMAGE_FAIL_COOLDOWN_MS = 30_000;
 const IMAGE_MAX_ATTEMPTS = 3;
 
+/**
+ * Cached intrinsic aspect ratios (width / height) for decoded images. The
+ * layout engine reads this to give an Image with only one declared dimension
+ * the right size on the other axis (instead of stretching to Taffy auto).
+ *
+ * Populated when an Image's onload fires; tests can seed it via
+ * `setImageNaturalSize` to assert the layout path without a real DOM.
+ */
+const imageNaturalAspect = new Map<string, number>();
+
+/** Returns width/height of the cached image, or null if unknown. */
+export function getImageNaturalAspect(src: string): number | null {
+  return imageNaturalAspect.get(src) ?? null;
+}
+
+/** Test helper: seed the intrinsic-size cache without loading a real image. */
+export function setImageNaturalSize(src: string, width: number, height: number): void {
+  if (width > 0 && height > 0) {
+    imageNaturalAspect.set(src, width / height);
+  }
+}
+
 /**
  * Evict oldest entries from a Map when it exceeds the given maximum size.
  */
@@ -520,6 +570,7 @@ export function clearImageCache(): void {
   imageCache.clear();
   imagePending.clear();
   imageFailCache.clear();
+  imageNaturalAspect.clear();
 }
 
 /**
@@ -536,11 +587,29 @@ function paintImage(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
   const y = layout.y;
   const width = layout.width;
   const height = layout.height;
+  const radius = layout.border.radius;
+
+  // Clip to the rounded box so `rounded-full` avatars actually paint as
+  // circles. Without this, avatars and post-header photos paint as
+  // squares behind their (correctly-rounded) story-ring border.
+  const clipped = radius > 0 && width > 0 && height > 0;
+  if (clipped) {
+    ctx.save();
+    drawRoundedRect(ctx, x, y, width, height, radius);
+    ctx.clip();
+  }
 
   const cached = imageCache.get(src);
   if (cached && cached.complete && cached.naturalWidth > 0) {
-    // Draw the loaded image
-    ctx.drawImage(cached, x, y, width, height);
+    // `objectFit: cover` is the social-feed default — fill the box without
+    // squashing. Anything else (or unspecified) falls back to the prior
+    // stretch behaviour for back-compat.
+    if (props.objectFit === "cover") {
+      drawImageCover(ctx, cached, x, y, width, height);
+    } else {
+      ctx.drawImage(cached, x, y, width, height);
+    }
+    if (clipped) ctx.restore();
     return;
   }
 
@@ -562,11 +631,13 @@ function paintImage(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
   if (failEntry) {
     if (failEntry.attempts >= IMAGE_MAX_ATTEMPTS || Date.now() - failEntry.failedAt < IMAGE_FAIL_COOLDOWN_MS) {
       ctx.fillText("Failed", x + width / 2, y + height / 2);
+      if (clipped) ctx.restore();
       return;
     }
   }
 
   ctx.fillText("Loading...", x + width / 2, y + height / 2);
+  if (clipped) ctx.restore();
 
   // Start loading if not already pending
   if (!imagePending.has(src)) {
@@ -578,6 +649,9 @@ function paintImage(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
     img.onload = () => {
       imageInFlight.delete(src);
       imageCache.set(src, img);
+      if (img.naturalWidth > 0 && img.naturalHeight > 0) {
+        imageNaturalAspect.set(src, img.naturalWidth / img.naturalHeight);
+      }
       imagePending.delete(src);
       imageFailCache.delete(src);
       evictMap(imageCache, MAX_IMAGE_CACHE_SIZE);
@@ -599,7 +673,45 @@ function paintImage(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
 }
 
 /**
- * Draw rounded rectangle path
+ * Draw an image with `object-fit: cover` semantics — fill the entire
+ * destination box without distortion, cropping the longer source axis.
+ */
+function drawImageCover(
+  ctx: CanvasRenderingContext2D,
+  img: HTMLImageElement,
+  dx: number,
+  dy: number,
+  dw: number,
+  dh: number,
+): void {
+  const sw = img.naturalWidth;
+  const sh = img.naturalHeight;
+  if (sw <= 0 || sh <= 0) {
+    ctx.drawImage(img, dx, dy, dw, dh);
+    return;
+  }
+  const srcAspect = sw / sh;
+  const dstAspect = dw / dh;
+  let sx = 0, sy = 0, sWidth = sw, sHeight = sh;
+  if (srcAspect > dstAspect) {
+    // Source is wider — crop horizontally.
+    sWidth = sh * dstAspect;
+    sx = (sw - sWidth) / 2;
+  } else if (srcAspect < dstAspect) {
+    // Source is taller — crop vertically.
+    sHeight = sw / dstAspect;
+    sy = (sh - sHeight) / 2;
+  }
+  ctx.drawImage(img, sx, sy, sWidth, sHeight, dx, dy, dw, dh);
+}
+
+/**
+ * Draw rounded rectangle path.
+ *
+ * Clamps the radius to half the smallest side — Tailwind's `rounded-full`
+ * lands on the engine as `border-radius: 9999px`, and without clamping the
+ * arcs wrap outside the box and fill a giant area (a 20×20 badge with
+ * radius 9999 paints as ~470×250 of background colour, swamping the row).
  */
 function drawRoundedRect(
   ctx: CanvasRenderingContext2D,
@@ -609,21 +721,23 @@ function drawRoundedRect(
   height: number,
   radius: number
 ): void {
-  if (radius <= 0) {
+  if (radius <= 0 || width <= 0 || height <= 0) {
     ctx.rect(x, y, width, height);
     return;
   }
 
+  const r = Math.min(radius, width / 2, height / 2);
+
   ctx.beginPath();
-  ctx.moveTo(x + radius, y);
-  ctx.lineTo(x + width - radius, y);
-  ctx.arcTo(x + width, y, x + width, y + radius, radius);
-  ctx.lineTo(x + width, y + height - radius);
-  ctx.arcTo(x + width, y + height, x + width - radius, y + height, radius);
-  ctx.lineTo(x + radius, y + height);
-  ctx.arcTo(x, y + height, x, y + height - radius, radius);
-  ctx.lineTo(x, y + radius);
-  ctx.arcTo(x, y, x + radius, y, radius);
+  ctx.moveTo(x + r, y);
+  ctx.lineTo(x + width - r, y);
+  ctx.arcTo(x + width, y, x + width, y + r, r);
+  ctx.lineTo(x + width, y + height - r);
+  ctx.arcTo(x + width, y + height, x + width - r, y + height, r);
+  ctx.lineTo(x + r, y + height);
+  ctx.arcTo(x, y + height, x, y + height - r, r);
+  ctx.lineTo(x, y + r);
+  ctx.arcTo(x, y, x + r, y, r);
   ctx.closePath();
 }
 
@@ -847,7 +961,7 @@ function paintDivider(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
 
   const orientation = props.orientation || "horizontal";
   const color = props.color || props.backgroundColor || "#e0e0e0";
-  const thickness = parseFloat(props.thickness) || 1;
+  const thickness = cssLengthToPx(props.thickness) ?? 1;
 
   ctx.strokeStyle = color;
   ctx.lineWidth = thickness;
@@ -881,7 +995,7 @@ function paintCheckbox(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
   const checkedValue = props.checked !== undefined ? props.checked : props.value;
   const checked = checkedValue === true || checkedValue === "true" || (checkedValue !== false && checkedValue !== "false" && !!checkedValue);
 
-  const radius = parseFloat(props.borderRadius) || 2;
+  const radius = cssLengthToPx(props.borderRadius) ?? 2;
 
   // Background
   const bgColor = checked ? (props.checkedColor || "#007bff") : (props.backgroundColor || "#ffffff");
@@ -1017,8 +1131,8 @@ function paintSlider(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
   const value = parseFloat(props.value) || min;
   const percentage = (value - min) / (max - min);
 
-  const trackHeight = parseFloat(props.trackHeight) || 4;
-  const thumbSize = parseFloat(props.thumbSize) || 16;
+  const trackHeight = cssLengthToPx(props.trackHeight) ?? 4;
+  const thumbSize = cssLengthToPx(props.thumbSize) ?? 16;
   const trackY = y + (height - trackHeight) / 2;
 
   // Track background
@@ -1118,7 +1232,7 @@ function paintSpinner(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
   const centerX = layout.x + size / 2;
   const centerY = layout.y + size / 2;
   const radius = size / 2 - 4;
-  const thickness = parseFloat(props.thickness) || 4;
+  const thickness = cssLengthToPx(props.thickness) ?? 4;
   const color = props.color || "#007bff";
 
   // Use timestamp for animation if available
@@ -1387,7 +1501,7 @@ function paintLink(ctx: CanvasRenderingContext2D, node: VirtualNode): void {
 
   const text = String(props[0] || props.text || "");
   const color = node.hovered ? (props.hoverColor || "#0056b3") : (props.color || "#007bff");
-  const fontSize = parseFloat(props.fontSize) || 16;
+  const fontSize = cssLengthToPx(props.fontSize) ?? 16;
   const fontWeight = props.fontWeight || "normal";
   const fontFamily = props.fontFamily || "system-ui, sans-serif";
   const textDecoration = props.textDecoration !== undefined ? props.textDecoration : "underline";

package/src/canvas/props.ts

@@ -0,0 +1,117 @@
+/**
+ * Canvas applicator-prop normalisation.
+ *
+ * The engine emits props using the applicator-argument naming scheme:
+ *   - single-positional:   `flex.0`, `padding.0`, `width.0`
+ *   - multi-argument:      `onClick.0`, `onClick.to`, `onClick.postId`
+ *
+ * The DOM renderer groups these at apply time via ApplicatorRegistry so
+ * downstream code can read `style.flex`, handler payloads, etc. The canvas
+ * layout (`layout.ts`) and paint (`paint.ts`) expect the same flat / aggregate
+ * shape but don't run an applicator pipeline, so without normalisation every
+ * size/flex/padding arriving from the engine is silently ignored — nodes
+ * collapse to Taffy auto sizing and images paint at full canvas bounds.
+ *
+ * We mirror the DOM grouping here: keep the raw `"base.key"` entries on the
+ * node (so follow-up SetProp patches can re-derive the aggregate) and
+ * additionally populate the bare `base` key with either the scalar value
+ * (single `.0`) or an aggregate object (multiple args).
+ */
+
+/** Return the applicator base name for a namespaced key, or null if it's flat. */
+export function parseApplicatorBase(name: string): string | null {
+  const dot = name.indexOf(".");
+  if (dot <= 0) return null;
+  return name.slice(0, dot);
+}
+
+/**
+ * Rebuild the derived flat/aggregate entry for `baseName` from all
+ * `"baseName.*"` keys currently on `props`. Mutates `props` in place.
+ *
+ * - Zero matching dotted keys: delete `props[baseName]` (any previously
+ *   derived value is now stale).
+ * - Exactly one key, numeric (`baseName.0`): flatten to the scalar value.
+ * - Anything else: store as an object keyed by the arg names.
+ */
+export function refreshApplicator(props: Record<string, any>, baseName: string): void {
+  const prefix = baseName + ".";
+  const args: Record<string, any> = {};
+  let count = 0;
+  for (const key of Object.keys(props)) {
+    if (!key.startsWith(prefix)) continue;
+    args[key.slice(prefix.length)] = props[key];
+    count++;
+  }
+  if (count === 0) {
+    delete props[baseName];
+    return;
+  }
+  const keys = Object.keys(args);
+  if (keys.length === 1 && /^\d+$/.test(keys[0])) {
+    props[baseName] = args[keys[0]];
+  } else {
+    props[baseName] = args;
+  }
+}
+
+/**
+ * Walk every key in `props`, collect the set of applicator base names,
+ * and refresh each one. Used on the initial Create patch where the whole
+ * prop bag arrives at once.
+ */
+export function normalizeAllApplicators(props: Record<string, any>): void {
+  const bases = new Set<string>();
+  for (const key of Object.keys(props)) {
+    const base = parseApplicatorBase(key);
+    if (base !== null) bases.add(base);
+  }
+  for (const base of bases) refreshApplicator(props, base);
+}
+
+/**
+ * Strip the engine's DSL prefixes from an action name. The Hypen DSL writes
+ * `@router.push` / `@actions.toggleLike`; the engine wants `router.push` /
+ * `toggleLike` on the wire. Mirrors the DOM renderer's
+ * `extractActionDetails` in `dom/applicators/events.ts`.
+ */
+function stripActionPrefixes(raw: string): string {
+  if (!raw.startsWith("@")) return raw;
+  let name = raw.substring(1);
+  if (name.startsWith("actions.")) name = name.substring(8);
+  return name;
+}
+
+/**
+ * Resolve an event applicator value into `(actionName, payload)`.
+ *
+ * After normalisation, `onClick` is either:
+ *   - a string:   `"@router.push"` (single positional, no extra args)
+ *   - an object:  `{ "0": "@router.push", to: "/notifications" }`
+ *
+ * Strips the leading `@` and the `actions.` namespace prefix so the wire
+ * format matches what the DOM renderer sends — without this, `@router.push`
+ * went out verbatim and the engine ignored it because it expects the
+ * stripped form (`router.push`).
+ *
+ * Returns `null` if no dispatchable action name could be found.
+ */
+export function resolveEventAction(
+  spec: unknown,
+): { actionName: string; payload: Record<string, any> } | null {
+  if (typeof spec === "string") {
+    if (!spec.startsWith("@")) return null;
+    return { actionName: stripActionPrefixes(spec), payload: {} };
+  }
+  if (spec && typeof spec === "object") {
+    const obj = spec as Record<string, any>;
+    const raw = obj["0"];
+    if (typeof raw !== "string" || !raw.startsWith("@")) return null;
+    const payload: Record<string, any> = {};
+    for (const [k, v] of Object.entries(obj)) {
+      if (k !== "0") payload[k] = v;
+    }
+    return { actionName: stripActionPrefixes(raw), payload };
+  }
+  return null;
+}

package/src/canvas/renderer.ts

@@ -30,6 +30,11 @@ import { ScrollManager } from "./scroll.js";
 import { SelectionManager } from "./selection.js";
 import { setSelectionManager } from "./paint.js";
 import { DirtyRectTracker } from "./dirty.js";
+import {
+  normalizeAllApplicators,
+  refreshApplicator,
+  parseApplicatorBase,
+} from "./props.js";
 
 const DEFAULT_OPTIONS: CanvasRendererOptions = {
   devicePixelRatio: typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1,
@@ -104,6 +109,29 @@ export class CanvasRenderer implements Renderer {
       this.options.enableAccessibility || false
     );
 
+    // Bridge focus changes from the hit-tester to the HTML input overlay.
+    // Without this, `Input`/`Textarea` painted on the canvas but clicking
+    // one did nothing — the overlay never got mounted.
+    this.eventManager.setFocusChangeHandler((next) => {
+      const t = next ? next.type.toLowerCase() : null;
+      if (next && (t === "input" || t === "textarea")) {
+        const rect = this.canvas.getBoundingClientRect();
+        this.inputOverlay.showInput(
+          next,
+          rect,
+          (value) => {
+            // Local mirror so the next paint sees the typed text even
+            // before the engine echoes it back via SetProp.
+            next.props.value = value;
+            this.scheduleRedraw();
+          },
+          this.engine,
+        );
+      } else {
+        this.inputOverlay.hideInput();
+      }
+    });
+
     // Listen for redraw requests from event manager
     this.canvas.addEventListener("hypen:redraw", () => this.scheduleRedraw());
 
@@ -203,6 +231,14 @@ export class CanvasRenderer implements Renderer {
       case "remove":
         this.onRemove(patch.id!);
         break;
+
+      case "detach":
+        this.onDetach(patch.id!);
+        break;
+
+      case "attach":
+        this.onInsert(patch.parentId!, patch.id!, patch.beforeId);
+        break;
     }
   }
 
@@ -210,17 +246,33 @@ export class CanvasRenderer implements Renderer {
    * Create new virtual node
    */
   private onCreate(id: string, elementType: string, props: Record<string, any>): void {
+    // Engine may send a Map (from WASM) or a plain object. Copy either way so
+    // we own the prop bag and can mutate it during applicator normalisation.
+    const rawProps: Record<string, any> =
+      props instanceof Map ? Object.fromEntries(props) : { ...props };
+    normalizeAllApplicators(rawProps);
+
+    // Engine emits the element type capitalised (`"Button"`, `"Text"`, …);
+    // every per-type comparison downstream lowercases it, so do the same
+    // for clickable/focusable. Without this, Buttons weren't flagged as
+    // clickable (so hover/cursor barely fired) and Inputs/Textareas
+    // weren't focusable (caret never landed).
+    const lowerType = elementType.toLowerCase();
     const node: VirtualNode = {
       id,
       type: elementType,
-      props: props instanceof Map ? Object.fromEntries(props) : props,
+      props: rawProps,
       children: [],
       parent: null,
       visible: true,
-      opacity: parseFloat(props.opacity) || 1,
-      clickable: elementType === "button" || !!props.onclick || !!props.action,
+      opacity: parseFloat(rawProps.opacity) || 1,
+      clickable:
+        lowerType === "button" ||
+        rawProps.onClick != null ||
+        rawProps.onclick != null ||
+        rawProps.action != null,
       hoverable: true,
-      focusable: elementType === "input" || elementType === "textarea" || elementType === "button",
+      focusable: lowerType === "input" || lowerType === "textarea" || lowerType === "button",
       focused: false,
       hovered: false,
     };
@@ -242,15 +294,30 @@ export class CanvasRenderer implements Renderer {
 
     node.props[name] = value;
 
-    // Update computed properties
+    // If this is an applicator-namespaced key (e.g. `flex.0`, `onClick.to`),
+    // rebuild the derived flat/aggregate entry under the base name so layout,
+    // paint, and event dispatch see the updated value.
+    const base = parseApplicatorBase(name);
+    if (base !== null) {
+      refreshApplicator(node.props, base);
+    }
+
+    // Update computed properties — check both the direct key and the
+    // post-refresh derived key so setProp on `opacity.0` still updates opacity.
     if (name === "visible") {
       node.visible = !!value;
     }
-    if (name === "opacity") {
-      node.opacity = parseFloat(value) || 1;
+    if (name === "opacity" || base === "opacity") {
+      node.opacity = parseFloat(node.props.opacity) || 1;
     }
-    if (name === "action" || name === "onclick") {
-      node.clickable = !!value;
+    if (
+      name === "onClick" || name === "onclick" || name === "action" ||
+      base === "onClick" || base === "onclick" || base === "action"
+    ) {
+      node.clickable =
+        node.props.onClick != null ||
+        node.props.onclick != null ||
+        node.props.action != null;
     }
 
     // Mark dirty after prop change (new bounds will be captured after layout)
@@ -275,11 +342,25 @@ export class CanvasRenderer implements Renderer {
 
     delete node.props[name];
 
+    const base = parseApplicatorBase(name);
+    if (base !== null) {
+      refreshApplicator(node.props, base);
+    }
+
     if (name === "visible") {
       node.visible = true;
     }
-    if (name === "opacity") {
-      node.opacity = 1;
+    if (name === "opacity" || base === "opacity") {
+      node.opacity = parseFloat(node.props.opacity) || 1;
+    }
+    if (
+      name === "onClick" || name === "onclick" || name === "action" ||
+      base === "onClick" || base === "onclick" || base === "action"
+    ) {
+      node.clickable =
+        node.props.onClick != null ||
+        node.props.onclick != null ||
+        node.props.action != null;
     }
 
     if (this.options.enableDirtyRects) {
@@ -384,6 +465,46 @@ export class CanvasRenderer implements Renderer {
     this.onInsert(parentId, id, beforeId);
   }
 
+  /**
+   * Detach a subtree from its parent without destroying it.
+   *
+   * The VirtualNode and its descendants stay in `this.nodes`, just
+   * unlinked from the visible tree (removed from the parent's
+   * `children` array and `node.parent = null`). A subsequent
+   * `attach` patch reinserts it — scroll offsets, focus state,
+   * layout caches, and any other per-node derived state survive.
+   *
+   * Used by the engine's Router cache to keep off-screen route
+   * subtrees alive between navigations so re-entry is instant.
+   */
+  private onDetach(id: string): void {
+    const node = this.nodes.get(id);
+    if (!node) return;
+
+    // Mark dirty so the next paint doesn't leave stale pixels behind.
+    if (this.options.enableDirtyRects) {
+      this.dirtyTracker.markNodeDirty(node);
+    }
+
+    if (node.parent) {
+      const idx = node.parent.children.indexOf(node);
+      if (idx >= 0) {
+        node.parent.children.splice(idx, 1);
+        if (this.options.enableDirtyRects) {
+          this.dirtyTracker.markNodeDirty(node.parent);
+        }
+      }
+      node.parent = null;
+    }
+
+    if (this.rootNode === node) {
+      this.rootNode = null;
+      this.eventManager.setRootNode(null);
+      this.scrollManager.setRootNode(null);
+      this.selectionManager.setRootNode(null);
+    }
+  }
+
   /**
    * Remove node from tree
    */