@noego/wood 0.4.6 → 0.4.7

package/dist/testing/browser.js

@@ -45,7 +45,9 @@ function mergeBridge(base, override) {
       ...base?.events ?? {},
       ...override?.events ?? {}
     },
-    record: override?.record ?? base?.record
+    record: override?.record ?? base?.record,
+    ...override?.transport ?? base?.transport ? { transport: override?.transport ?? base?.transport } : {},
+    ...override?.rpcManifest ?? base?.rpcManifest ? { rpcManifest: override?.rpcManifest ?? base?.rpcManifest } : {}
   };
 }
 async function waitForBoundedClose(promise, timeoutMs = DEFAULT_RESOURCE_CLOSE_TIMEOUT_MS) {
@@ -86,7 +88,9 @@ function createBridgeState(input) {
     initialEvents,
     calls: [],
     emittedEvents: [],
-    record: input?.record ?? true
+    record: input?.record ?? true,
+    ...input?.transport ? { transport: input.transport } : {},
+    ...input?.rpcManifest ? { rpcManifest: input.rpcManifest } : {}
   };
 }
 function createBrowserBridgeFixture(input) {
@@ -94,20 +98,29 @@ function createBrowserBridgeFixture(input) {
 }
 function createBrowserBridgeFixtureWithTrace(input, traceConfig) {
   const state = createBridgeState(input);
-  const manifest = Array.from(state.operations.entries()).map(([channel, handler]) => channelToManifestEntry(channel, handler));
+  const manifest = state.rpcManifest ?? Array.from(state.operations.entries()).map(([channel, handler]) => channelToManifestEntry(channel, handler));
   return {
     state,
     manifest,
-    bridgeInit: buildBridgeInitScript(manifest, traceConfig)
+    bridgeInit: buildBridgeInitScript(manifest, traceConfig, Boolean(state.transport))
   };
 }
-function buildBridgeInitScript(manifest, traceConfig) {
+function buildBridgeInitScript(manifest, traceConfig, transportMode) {
   const traceEnabled = traceConfig?.enabled === true;
   const traceMinLevel = traceConfig?.minLevel ?? "debug";
   return `
 (() => {
   const manifest = ${JSON.stringify(manifest)};
+  const transportMode = ${JSON.stringify(transportMode)};
   const listeners = new Map();
+  window.__woodBrowserTracePending = new Set();
+  window.__woodBrowserTraceFlush = async () => {
+    // Drain in-flight __trace exposeBinding round-trips so the test-process
+    // renderer-trace ack loop can barrier on a definite quiescent point.
+    while (window.__woodBrowserTracePending.size > 0) {
+      await Promise.allSettled(Array.from(window.__woodBrowserTracePending));
+    }
+  };
   const bridge = {
     __rpcManifest: manifest,
     __woodConfig: async () => ({
@@ -115,7 +128,14 @@ function buildBridgeInitScript(manifest, traceConfig) {
       rendererTraceMinLevel: ${JSON.stringify(traceMinLevel)}
     }),
     __log: () => {},
-    __trace: (payload) => window.__woodBrowserTrace?.(payload),
+    __trace: (payload) => {
+      const result = window.__woodBrowserTrace?.(payload);
+      if (result && typeof result.then === 'function') {
+        window.__woodBrowserTracePending.add(result);
+        result.finally(() => window.__woodBrowserTracePending.delete(result));
+      }
+      return result;
+    },
     __window: {
       current: async () => ({ ok: true, windowId: 'wood-browser-harness', defaultRoute: window.__WOOD_BROWSER_DEFAULT_ROUTE__ }),
       open: async () => ({}),
@@ -125,8 +145,13 @@ function buildBridgeInitScript(manifest, traceConfig) {
       maximize: async () => ({}),
     },
     on(channel, callback) {
-      if (!listeners.has(channel)) listeners.set(channel, new Set());
+      const first = !listeners.has(channel);
+      if (first) listeners.set(channel, new Set());
       listeners.get(channel).add(callback);
+      // In real-backend mode, relay the first subscription per channel to the
+      // test process so it can subscribe on the WoodRpcTransport and forward
+      // main-process push events back into __woodBrowserEmit.
+      if (transportMode && first) window.__woodBrowserSubscribe?.(channel);
       return () => listeners.get(channel)?.delete(callback);
     },
   };
@@ -177,6 +202,11 @@ function resolvePackageModule(rootDir, source) {
     }
   }
 }
+function resolveEsmModule(rootDir, source) {
+  const resolved = resolvePackageModule(rootDir, source);
+  const esm = resolved?.endsWith(".cjs") ? resolved.replace(/\.cjs$/, ".js") : resolved;
+  return esm && fs.existsSync(esm) ? viteImport(esm) : source;
+}
 function resolvePackageDir(rootDir, packageName) {
   const packageJson = resolvePackageModule(rootDir, `${packageName}/package.json`);
   return packageJson ? path.dirname(packageJson) : null;
@@ -487,9 +517,22 @@ window.__WOOD_BROWSER_APP__ = mount(NavigationShell, {
 `;
 }
 function buildGeneratedAppEntrySource(input) {
+  const hasRouteContext = Object.keys(input.route.params).length > 0 || Object.keys(input.route.query).length > 0;
+  const rendererTraceEnable = input.enableRendererTrace ? `try {
+  const traceConfiguration = await getContainer().instance(TraceProviderConfiguration);
+  traceConfiguration.configureRuntime('renderer');
+  traceConfiguration.configureMinLevel(${JSON.stringify(input.traceMinLevel)});
+  traceConfiguration.configureEnabled(true);
+} catch (error) { /* best-effort renderer-trace enable */ }` : "";
+  const navigationApply = hasRouteContext ? `getNavigation().replace(${JSON.stringify(input.routeKey)}, ${JSON.stringify(input.route.params)}, ${JSON.stringify(input.route.query)});` : "";
   return `import { app } from '${viteImport(input.generatedApp)}';
+import { getNavigation } from '${input.navigationModule}';
+import { getContainer, TraceProviderConfiguration } from '${input.clientModule}';
 window.__WOOD_BROWSER_DEFAULT_ROUTE__ = ${JSON.stringify(input.routeKey)};
 window.__WOOD_BROWSER_APP__ = await app(document.getElementById('app'));
+window.__WOOD_BROWSER_NAV__ = getNavigation();
+${rendererTraceEnable}
+${navigationApply}
 `;
 }
 function buildComponentEntrySource(input) {
@@ -530,7 +573,7 @@ window.__WOOD_BROWSER_APP__ = mount(WoodRecursiveRender, {
 });
 `;
 }
-async function installBridge(page, bridgeState, manifest, bridgeInit) {
+async function installBridge(page, bridgeState, manifest, bridgeInit, transportCleanups) {
   await page.exposeBinding("__woodBrowserInvoke", async (_source, channel, input) => {
     const call = {
       channel,
@@ -540,17 +583,39 @@ async function installBridge(page, bridgeState, manifest, bridgeInit) {
     if (bridgeState.record) {
       bridgeState.calls.push(call);
     }
+    if (bridgeState.transport && !bridgeState.operations.has(channel)) {
+      return await bridgeState.transport.invoke(channel, input);
+    }
     const handler = bridgeState.operations.get(channel);
     if (typeof handler === "function") {
       return await handler(input, { channel, calls: bridgeState.calls });
     }
     return handler;
   });
+  await installTransportEventForwarding(page, bridgeState, transportCleanups);
   await page.addInitScript(bridgeInit);
   await page.addInitScript((entries) => {
     window.__WOOD_BROWSER_BRIDGE_MANIFEST__ = entries;
   }, manifest);
 }
+async function installTransportEventForwarding(page, bridgeState, transportCleanups) {
+  const transport = bridgeState.transport;
+  if (!transport) return;
+  const subscribed = /* @__PURE__ */ new Set();
+  await page.exposeBinding("__woodBrowserSubscribe", (_source, channel) => {
+    if (subscribed.has(channel)) return;
+    subscribed.add(channel);
+    const unsubscribe = transport.subscribe(channel, (payload) => {
+      void page.evaluate(
+        ({ eventChannel, eventPayload }) => {
+          window.__woodBrowserEmit?.(eventChannel, eventPayload);
+        },
+        { eventChannel: channel, eventPayload: payload }
+      ).catch(() => void 0);
+    });
+    transportCleanups.push(unsubscribe);
+  });
+}
 async function installTraceBinding(page, traceRecorder, context) {
   if (!traceRecorder) {
     return;
@@ -634,6 +699,259 @@ async function elementRect(page, selector) {
     };
   }).catch(() => null);
 }
+async function firstRect(page, selector) {
+  return await page.locator(selector).first().evaluate((element) => {
+    const rect = element.getBoundingClientRect();
+    return {
+      top: rect.top,
+      left: rect.left,
+      right: rect.right,
+      bottom: rect.bottom,
+      width: rect.width,
+      height: rect.height
+    };
+  }).catch(() => null);
+}
+function describeHitElement(hit) {
+  if (!hit.tag) return "<no element at point>";
+  const id = hit.id ? `#${hit.id}` : "";
+  const classes = hit.classes.length > 0 ? `.${hit.classes.join(".")}` : "";
+  return `<${hit.tag.toLowerCase()}${id}${classes}>`;
+}
+async function capturePaintOrders(page, selectors) {
+  const context = page.context?.();
+  if (!context || typeof context.newCDPSession !== "function") {
+    throw new Error(
+      "inFrontOf paint-order comparison requires a Chromium CDP session (page.context().newCDPSession). It is Chromium-only; pass { at } to use the point hit-test form on other browsers."
+    );
+  }
+  const cdp = await context.newCDPSession(page);
+  try {
+    await cdp.send("DOM.enable");
+    const { root } = await cdp.send("DOM.getDocument", { depth: -1 });
+    const backendIds = /* @__PURE__ */ new Map();
+    for (const selector of selectors) {
+      let backendNodeId = null;
+      try {
+        const { nodeId } = await cdp.send("DOM.querySelector", { nodeId: root.nodeId, selector });
+        if (nodeId) {
+          const described = await cdp.send("DOM.describeNode", { nodeId });
+          backendNodeId = described.node?.backendNodeId ?? null;
+        }
+      } catch {
+        backendNodeId = null;
+      }
+      backendIds.set(selector, backendNodeId);
+    }
+    const snapshot = await cdp.send("DOMSnapshot.captureSnapshot", {
+      computedStyles: [],
+      includePaintOrder: true,
+      includeDOMRects: false
+    });
+    const paintByBackend = collectMaxPaintOrders(snapshot);
+    const result = /* @__PURE__ */ new Map();
+    for (const selector of selectors) {
+      const backendId = backendIds.get(selector) ?? null;
+      const paint = backendId == null ? void 0 : paintByBackend.get(backendId);
+      result.set(selector, { paintOrder: paint ?? null, found: paint !== void 0 });
+    }
+    return result;
+  } finally {
+    await cdp.detach().catch(() => void 0);
+  }
+}
+function collectMaxPaintOrders(snapshot) {
+  const paintByBackend = /* @__PURE__ */ new Map();
+  for (const doc of snapshot.documents ?? []) {
+    const backendOfNode = doc.nodes?.backendNodeId ?? [];
+    const nodeIndex = doc.layout?.nodeIndex ?? [];
+    const paintOrders = doc.layout?.paintOrders ?? [];
+    for (let i = 0; i < nodeIndex.length; i += 1) {
+      const paint = paintOrders[i];
+      const backendId = backendOfNode[nodeIndex[i]];
+      if (paint === void 0 || backendId === void 0) continue;
+      const prev = paintByBackend.get(backendId);
+      if (prev === void 0 || paint > prev) paintByBackend.set(backendId, paint);
+    }
+  }
+  return paintByBackend;
+}
+function axisEdges(rect, axis) {
+  return axis === "horizontal" ? { leading: rect.left, trailing: rect.right } : { leading: rect.top, trailing: rect.bottom };
+}
+function axisGap(first, second, axis) {
+  const a = axisEdges(first, axis);
+  const b = axisEdges(second, axis);
+  const [earlier, later] = a.leading <= b.leading ? [a, b] : [b, a];
+  return later.leading - earlier.trailing;
+}
+function describeGapConstraint(constraint) {
+  const parts = [];
+  if (constraint.equals !== void 0) parts.push(`equals ${constraint.equals}`);
+  if (constraint.min !== void 0) parts.push(`min ${constraint.min}`);
+  if (constraint.max !== void 0) parts.push(`max ${constraint.max}`);
+  return parts.join(", ");
+}
+function gapConstraintViolation(gap, constraint, tolerance) {
+  if (constraint.equals !== void 0 && Math.abs(gap - constraint.equals) > tolerance) {
+    return `expected gap to equal ${constraint.equals} (\xB1${tolerance})`;
+  }
+  if (constraint.min !== void 0 && gap < constraint.min - tolerance) {
+    return `expected gap >= ${constraint.min}`;
+  }
+  if (constraint.max !== void 0 && gap > constraint.max + tolerance) {
+    return `expected gap <= ${constraint.max}`;
+  }
+  return null;
+}
+function rectsOverlap(a, b) {
+  return Boolean(
+    a && b && a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top
+  );
+}
+const COVERAGE_STYLE_KEYS = [
+  "opacity",
+  "visibility",
+  "background-color",
+  "background-image",
+  "border-top-width",
+  "border-right-width",
+  "border-bottom-width",
+  "border-left-width"
+];
+function colorAlphaIsZero(color) {
+  if (color === "transparent") return true;
+  const match = color.match(/^rgba?\(([^)]*)\)/);
+  if (!match) return false;
+  const parts = match[1].split(",").map((s) => s.trim());
+  return parts.length >= 4 && parseFloat(parts[3]) === 0;
+}
+function snapshotRectsOverlap(a, b) {
+  return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
+}
+function indexLayoutNodes(doc, strings) {
+  const byNode = /* @__PURE__ */ new Map();
+  const nodeIndex = doc.layout?.nodeIndex ?? [];
+  const bounds = doc.layout?.bounds ?? [];
+  const paintOrders = doc.layout?.paintOrders ?? [];
+  const styleRows = doc.layout?.styles ?? [];
+  for (let k = 0; k < nodeIndex.length; k += 1) {
+    const ni = nodeIndex[k];
+    const paint = paintOrders[k] ?? 0;
+    const existing = byNode.get(ni);
+    if (existing) {
+      if (paint > existing.paint) existing.paint = paint;
+      continue;
+    }
+    const b = bounds[k] ?? [0, 0, 0, 0];
+    const styles = {};
+    const row = styleRows[k] ?? [];
+    COVERAGE_STYLE_KEYS.forEach((key, j) => {
+      styles[key] = row[j] === void 0 ? "" : strings[row[j]];
+    });
+    byNode.set(ni, { rect: { x: b[0], y: b[1], w: b[2], h: b[3] }, paint, styles });
+  }
+  return byNode;
+}
+function nodeIndexForBackendId(nodes, backendId) {
+  const backendIds = nodes.backendNodeId ?? [];
+  for (let i = 0; i < backendIds.length; i += 1) if (backendIds[i] === backendId) return i;
+  return -1;
+}
+function isSnapshotAncestor(parentIndex, a, b) {
+  let cursor = parentIndex[b];
+  while (cursor >= 0) {
+    if (cursor === a) return true;
+    cursor = parentIndex[cursor];
+  }
+  return false;
+}
+function snapshotNodeHasOwnContent(nodes, strings, i) {
+  const tag = (strings[nodes.nodeName[i]] ?? "").toUpperCase();
+  if (["IMG", "SVG", "CANVAS", "VIDEO", "INPUT", "TEXTAREA", "SELECT", "PICTURE"].includes(tag)) return true;
+  const parentIndex = nodes.parentIndex ?? [];
+  const nodeType = nodes.nodeType ?? [];
+  const nodeValue = nodes.nodeValue ?? [];
+  for (let c = 0; c < parentIndex.length; c += 1) {
+    if (parentIndex[c] === i && nodeType[c] === 3) {
+      const v = nodeValue[c];
+      if (v >= 0 && (strings[v] ?? "").trim().length > 0) return true;
+    }
+  }
+  return false;
+}
+function snapshotNodePaintsNothing(styles, hasOwnContent) {
+  if (styles.opacity === "0") return true;
+  if (styles.visibility === "hidden") return true;
+  const noBackground = colorAlphaIsZero(styles["background-color"] ?? "") && (styles["background-image"] === "none" || !styles["background-image"]);
+  const noBorder = ["border-top-width", "border-right-width", "border-bottom-width", "border-left-width"].every((key) => (styles[key] || "0px") === "0px");
+  return noBackground && noBorder && !hasOwnContent;
+}
+function describeSnapshotNode(nodes, strings, i) {
+  const tag = (strings[nodes.nodeName[i]] ?? "").toLowerCase();
+  const attrs = nodes.attributes?.[i] ?? [];
+  let id = "";
+  let classes = "";
+  for (let a = 0; a + 1 < attrs.length; a += 2) {
+    const name = strings[attrs[a]];
+    const value = strings[attrs[a + 1]] ?? "";
+    if (name === "id") id = value ? `#${value}` : "";
+    else if (name === "class") classes = value ? `.${value.trim().split(/\s+/).join(".")}` : "";
+  }
+  const pseudo = nodes.pseudoType?.[i] !== void 0 && nodes.pseudoType[i] !== null ? `::${strings[nodes.pseudoType[i]] ?? "pseudo"}` : "";
+  return `<${tag}${id}${classes}${pseudo}>`;
+}
+function collectCoverageCandidates(doc, strings, targetNodeIndex) {
+  const nodes = doc.nodes;
+  const parentIndex = nodes.parentIndex ?? [];
+  const nodeType = nodes.nodeType ?? [];
+  const layout = indexLayoutNodes(doc, strings);
+  const target = layout.get(targetNodeIndex);
+  if (!target) return { targetPaint: 0, targetRect: { x: 0, y: 0, w: 0, h: 0 }, covers: [] };
+  const covers = [];
+  for (const [ni, rec] of layout) {
+    if (nodeType[ni] !== 1) continue;
+    if (ni === targetNodeIndex) continue;
+    if (isSnapshotAncestor(parentIndex, ni, targetNodeIndex) || isSnapshotAncestor(parentIndex, targetNodeIndex, ni)) continue;
+    if (!snapshotRectsOverlap(rec.rect, target.rect)) continue;
+    const hasContent = snapshotNodeHasOwnContent(nodes, strings, ni);
+    if (snapshotNodePaintsNothing(rec.styles, hasContent)) continue;
+    covers.push({ description: describeSnapshotNode(nodes, strings, ni), paint: rec.paint, rect: rec.rect });
+  }
+  return { targetPaint: target.paint, targetRect: target.rect, covers };
+}
+async function captureCoverage(page, selector) {
+  const context = page.context?.();
+  if (!context || typeof context.newCDPSession !== "function") {
+    throw new Error(
+      "notCovered requires a Chromium CDP session (page.context().newCDPSession); it is Chromium-only."
+    );
+  }
+  const cdp = await context.newCDPSession(page);
+  try {
+    await cdp.send("DOM.enable");
+    const { root } = await cdp.send("DOM.getDocument", { depth: -1 });
+    const { nodeId } = await cdp.send("DOM.querySelector", { nodeId: root.nodeId, selector });
+    if (!nodeId) throw new Error(`Expected "${selector}" to exist for notCovered.`);
+    const described = await cdp.send("DOM.describeNode", { nodeId });
+    const backendId = described.node?.backendNodeId;
+    if (backendId == null) throw new Error(`Could not resolve backendNodeId for "${selector}".`);
+    const snapshot = await cdp.send("DOMSnapshot.captureSnapshot", {
+      computedStyles: [...COVERAGE_STYLE_KEYS],
+      includePaintOrder: true,
+      includeDOMRects: true
+    });
+    const doc = snapshot.documents?.[0];
+    if (!doc) throw new Error("DOMSnapshot returned no documents.");
+    const targetNodeIndex = nodeIndexForBackendId(doc.nodes, backendId);
+    if (targetNodeIndex < 0) {
+      throw new Error(`Expected "${selector}" to be laid out and painted for notCovered, but it was not in the paint tree.`);
+    }
+    return collectCoverageCandidates(doc, snapshot.strings ?? [], targetNodeIndex);
+  } finally {
+    await cdp.detach().catch(() => void 0);
+  }
+}
 function createExpect(page, outputDir) {
   async function waitForVisible(selector) {
     const locator = page.locator(selector).first();
@@ -648,6 +966,64 @@ function createExpect(page, outputDir) {
       throw new Error(`Expected "${selector}" to be visible.`);
     }
   }
+  async function hitTestAtPoint(selector, x, y) {
+    const locator = page.locator(selector).first();
+    const raw = await locator.evaluate((target, coords) => {
+      const hit = document.elementFromPoint(coords.x, coords.y);
+      if (!hit) {
+        return { found: false, tag: null, id: null, classes: [], isTarget: false, isDescendantOfTarget: false, isAncestorOfTarget: false };
+      }
+      return {
+        found: true,
+        tag: hit.tagName,
+        id: hit.id || null,
+        classes: Array.from(hit.classList),
+        isTarget: hit === target,
+        isDescendantOfTarget: hit !== target && target.contains(hit),
+        isAncestorOfTarget: hit !== target && hit.contains(target)
+      };
+    }, { x, y });
+    return {
+      ...raw,
+      point: { x, y },
+      description: describeHitElement(raw)
+    };
+  }
+  async function resolvePoint(selector, point) {
+    if (point && point !== "center") return point;
+    const rect = await firstRect(page, selector);
+    if (!rect) throw new Error(`Expected "${selector}" to exist.`);
+    return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+  }
+  async function inFrontOfByPaintOrder(topSelector, lowerSelector) {
+    const orders = await capturePaintOrders(page, [topSelector, lowerSelector]);
+    const top = orders.get(topSelector);
+    const lower = orders.get(lowerSelector);
+    if (!top.found || top.paintOrder === null) {
+      throw new Error(`Expected "${topSelector}" to have a paint-order entry, but it was not found in the paint tree (not laid out / not painted).`);
+    }
+    if (!lower.found || lower.paintOrder === null) {
+      throw new Error(`Expected "${lowerSelector}" to have a paint-order entry, but it was not found in the paint tree (not laid out / not painted).`);
+    }
+    if (top.paintOrder > lower.paintOrder) return;
+    const topRect = await firstRect(page, topSelector);
+    const lowerRect = await firstRect(page, lowerSelector);
+    const overlapNote = rectsOverlap(topRect, lowerRect) ? "" : ` (Note: the rects do not overlap, so there is no shared pixel where front/behind is visually observable \u2014 this is a global paint-order verdict.)`;
+    throw new Error(
+      `Expected "${topSelector}" (paint order ${top.paintOrder}) to paint in front of "${lowerSelector}" (paint order ${lower.paintOrder}), but it paints at or behind it (higher paint order == on top).${overlapNote}`
+    );
+  }
+  async function inFrontOfAtPoint(topSelector, lowerSelector, at) {
+    const topHit = await hitTestAtPoint(topSelector, at.x, at.y);
+    const lowerHit = await hitTestAtPoint(lowerSelector, at.x, at.y);
+    const hitsTop = topHit.isTarget || topHit.isDescendantOfTarget;
+    const hitsLower = lowerHit.isTarget || lowerHit.isDescendantOfTarget;
+    if (!hitsTop || hitsLower) {
+      throw new Error(
+        `Expected "${topSelector}" to be painted in front of "${lowerSelector}" at (${at.x.toFixed(1)}, ${at.y.toFixed(1)}), but the top-most painted element there was ${topHit.description} (is/descends-from "${topSelector}": ${hitsTop}; is/descends-from "${lowerSelector}": ${hitsLower}).`
+      );
+    }
+  }
   return {
     async visible(selector) {
       await waitForVisible(selector);
@@ -724,6 +1100,135 @@ function createExpect(page, outputDir) {
         throw new Error(`Expected "${topSelector}" z-index (${values.top}) to be above "${lowerSelector}" (${values.lower}).`);
       }
     },
+    async rects(selectors) {
+      const snapshots = [];
+      for (const selector of selectors) {
+        const rect = await firstRect(page, selector);
+        if (!rect) throw new Error(`Expected "${selector}" to exist.`);
+        snapshots.push({ selector, ...rect });
+      }
+      return snapshots;
+    },
+    async hitTest(selector, point = "center") {
+      await waitForVisible(selector);
+      const resolved = await resolvePoint(selector, point);
+      return hitTestAtPoint(selector, resolved.x, resolved.y);
+    },
+    async sharedEdge(a, b, edge, options = {}) {
+      await waitForVisible(a);
+      await waitForVisible(b);
+      const tolerance = options.tolerance ?? 1;
+      const first = await firstRect(page, a);
+      const second = await firstRect(page, b);
+      if (!first || !second) throw new Error(`Expected both "${a}" and "${b}" to exist.`);
+      const delta = Math.abs(first[edge] - second[edge]);
+      if (delta > tolerance) {
+        throw new Error(
+          `Expected "${a}" and "${b}" to share ${edge} edge within ${tolerance}px, but delta was ${delta.toFixed(2)}px ("${a}".${edge}=${first[edge].toFixed(2)}, "${b}".${edge}=${second[edge].toFixed(2)}). Rects: ${a}=${JSON.stringify(first)}, ${b}=${JSON.stringify(second)}`
+        );
+      }
+    },
+    async sharedAxis(a, b, axis, options = {}) {
+      await waitForVisible(a);
+      await waitForVisible(b);
+      const tolerance = options.tolerance ?? 1;
+      const first = await firstRect(page, a);
+      const second = await firstRect(page, b);
+      if (!first || !second) throw new Error(`Expected both "${a}" and "${b}" to exist.`);
+      const center = (rect) => axis === "centerX" ? rect.left + rect.width / 2 : rect.top + rect.height / 2;
+      const firstCenter = center(first);
+      const secondCenter = center(second);
+      const delta = Math.abs(firstCenter - secondCenter);
+      if (delta > tolerance) {
+        throw new Error(
+          `Expected "${a}" and "${b}" to share ${axis} within ${tolerance}px, but delta was ${delta.toFixed(2)}px ("${a}".${axis}=${firstCenter.toFixed(2)}, "${b}".${axis}=${secondCenter.toFixed(2)}). Rects: ${a}=${JSON.stringify(first)}, ${b}=${JSON.stringify(second)}`
+        );
+      }
+    },
+    async unoccluded(selector, options = {}) {
+      await waitForVisible(selector);
+      const resolved = await resolvePoint(selector, options.point ?? "center");
+      const hit = await hitTestAtPoint(selector, resolved.x, resolved.y);
+      if (!hit.found) {
+        throw new Error(`Expected "${selector}" to receive pixels at (${resolved.x.toFixed(1)}, ${resolved.y.toFixed(1)}), but no element was painted there.`);
+      }
+      if (hit.isTarget || hit.isDescendantOfTarget || hit.isAncestorOfTarget) return;
+      throw new Error(
+        `Expected "${selector}" to be unoccluded at (${resolved.x.toFixed(1)}, ${resolved.y.toFixed(1)}), but the painted element there was ${hit.description} \u2014 a foreign element occluding the target.`
+      );
+    },
+    async inFrontOf(topSelector, lowerSelector, options = {}) {
+      await waitForVisible(topSelector);
+      await waitForVisible(lowerSelector);
+      if (options.at) {
+        await inFrontOfAtPoint(topSelector, lowerSelector, options.at);
+        return;
+      }
+      await inFrontOfByPaintOrder(topSelector, lowerSelector);
+    },
+    async notCovered(selector) {
+      await waitForVisible(selector);
+      const coverage = await captureCoverage(page, selector);
+      const covering = coverage.covers.filter((c) => c.paint > coverage.targetPaint);
+      if (covering.length === 0) return;
+      const worst = covering.reduce((a, b) => b.paint > a.paint ? b : a);
+      throw new Error(
+        `Expected "${selector}" (paint order ${coverage.targetPaint}, rect ${JSON.stringify(coverage.targetRect)}) not to be covered, but ${worst.description} paints on top (paint order ${worst.paint}, rect ${JSON.stringify(worst.rect)}). notCovered tracks PAINTED coverage from the real paint tree; a foreign element with a higher paint order that overlaps the target and paints visible pixels (background/border/text/image \u2014 the transparent-wrapper heuristic did not exempt it) fails here.`
+      );
+    },
+    async gapBetween(a, b, axis, options) {
+      if (options.equals === void 0 && options.min === void 0 && options.max === void 0) {
+        throw new Error("gapBetween requires at least one of { equals, min, max }.");
+      }
+      await waitForVisible(a);
+      await waitForVisible(b);
+      const tolerance = options.tolerance ?? 1;
+      const first = await firstRect(page, a);
+      const second = await firstRect(page, b);
+      if (!first || !second) throw new Error(`Expected both "${a}" and "${b}" to exist.`);
+      const gap = axisGap(first, second, axis);
+      const allowsNegative = options.equals !== void 0 && options.equals < 0 || options.min !== void 0 && options.min < 0;
+      const rectsNote = `Rects: ${a}=${JSON.stringify(first)}, ${b}=${JSON.stringify(second)}`;
+      if (gap < -tolerance && !allowsNegative) {
+        throw new Error(
+          `Expected "${a}" and "${b}" to have a non-negative ${axis} gap, but their border boxes overlap by ${(-gap).toFixed(2)}px (gap ${gap.toFixed(2)}px). Pass a negative min/equals to assert an overlap intentionally. ${rectsNote}`
+        );
+      }
+      const violation = gapConstraintViolation(gap, options, tolerance);
+      if (violation) {
+        throw new Error(
+          `Expected "${a}" and "${b}" ${axis} gap to satisfy ${describeGapConstraint(options)} within ${tolerance}px, but ${violation} (actual gap ${gap.toFixed(2)}px). ${rectsNote}`
+        );
+      }
+    },
+    async evenlySpaced(selectors, axis, options = {}) {
+      if (selectors.length < 3) {
+        throw new Error(`evenlySpaced requires at least 3 elements, got ${selectors.length}.`);
+      }
+      const tolerance = options.tolerance ?? 1;
+      const boxes = [];
+      for (const selector of selectors) {
+        await waitForVisible(selector);
+        const rect = await firstRect(page, selector);
+        if (!rect) throw new Error(`Expected "${selector}" to exist.`);
+        boxes.push({ selector, rect });
+      }
+      const sorted = [...boxes].sort((x, y) => axisEdges(x.rect, axis).leading - axisEdges(y.rect, axis).leading);
+      const gaps = sorted.slice(1).map((box, i) => ({
+        from: sorted[i].selector,
+        to: box.selector,
+        gap: axisGap(sorted[i].rect, box.rect, axis)
+      }));
+      const widest = gaps.reduce((acc, g) => g.gap > acc.gap ? g : acc);
+      const narrowest = gaps.reduce((acc, g) => g.gap < acc.gap ? g : acc);
+      const spread = widest.gap - narrowest.gap;
+      if (spread > tolerance) {
+        const list = gaps.map((g) => `${g.from}\u2192${g.to}=${g.gap.toFixed(2)}px`).join(", ");
+        throw new Error(
+          `Expected elements to be evenly spaced along ${axis} within ${tolerance}px, but gap spread was ${spread.toFixed(2)}px (widest ${widest.from}\u2192${widest.to}=${widest.gap.toFixed(2)}px, narrowest ${narrowest.from}\u2192${narrowest.to}=${narrowest.gap.toFixed(2)}px). Gaps: ${list}`
+        );
+      }
+    },
     async stableAfterAnimation(selector = "body", options = {}) {
       const frameCount = options.frameCount ?? 3;
       const timeoutMs = options.timeoutMs ?? 2e3;
@@ -783,7 +1288,13 @@ async function openMountPage(input) {
   const entryPath = writeEntry(input.runtime.tempDir, input.name, input.entrySource);
   const htmlPath = writeHtml(input.runtime.tempDir, input.name, entryPath, input.css);
   await installTraceBinding(input.runtime.page, input.traceRecorder, input.traceContext ?? {});
-  await installBridge(page, input.bridge.state, input.bridge.manifest, input.bridge.bridgeInit);
+  await installBridge(
+    page,
+    input.bridge.state,
+    input.bridge.manifest,
+    input.bridge.bridgeInit,
+    input.runtime.transportCleanups
+  );
   const mountedBridge = createMountedBridge(page, input.bridge.state);
   const context = {
     page,
@@ -858,7 +1369,8 @@ async function createHarness(config = {}) {
     server: workerRuntime.server,
     page,
     tempDir,
-    rootDir
+    rootDir,
+    transportCleanups: []
   };
   const css = (config.css ?? []).map((cssPath) => {
     const resolved = resolveFromRoot(rootDir, cssPath);
@@ -889,7 +1401,15 @@ async function createHarness(config = {}) {
       } else if (config.generatedApp) {
         const generatedApp = resolveFromRoot(rootDir, config.generatedApp);
         assertFileExists(generatedApp, "Generated app");
-        entrySource = buildGeneratedAppEntrySource({ generatedApp, routeKey });
+        entrySource = buildGeneratedAppEntrySource({
+          generatedApp,
+          routeKey,
+          route,
+          navigationModule: resolveEsmModule(rootDir, "@noego/wood/navigation"),
+          clientModule: resolveEsmModule(rootDir, "@noego/wood/client"),
+          enableRendererTrace: config.trace?.enabled === true,
+          traceMinLevel: config.trace?.minLevel ?? "debug"
+        });
       } else {
         throw new Error("mountRoute requires either viewsConfig or generatedApp in browser.createHarness().");
       }
@@ -986,11 +1506,20 @@ async function createHarness(config = {}) {
         hooks: config.page
       });
     },
+    async flushRendererTraces() {
+      await page.evaluate(() => window.__woodBrowserTraceFlush?.()).catch(() => void 0);
+    },
     async destroy() {
       if (destroyed) {
         return;
       }
       destroyed = true;
+      for (const cleanup of runtime.transportCleanups.splice(0)) {
+        try {
+          cleanup();
+        } catch {
+        }
+      }
       await Promise.all([
         waitForBoundedClose(page.close()),
         waitForBoundedClose(context.close())