@noego/wood 0.4.6 → 0.4.7

package/dist/transport/wood_rpc_transport.d.cts

@@ -0,0 +1,44 @@
+/**
+ * The single seam every test-mode RPC path is built on.
+ *
+ * Production uses the Electron preload bridge (`ipcRenderer.invoke` +
+ * `ipcRenderer.on('__event:...')`). Tests use one of the in-process or loopback
+ * implementations. The generated bridge client is built over whichever transport
+ * is supplied, so application code never knows which one is active.
+ *
+ * IMPORTANT (fast-tier isolation): this module and `InProcessRouterTransport`
+ * must never import `electron` or `playwright`. Keep this file dependency-free.
+ */
+interface WoodRpcTransport {
+    /**
+     * Dispatch a request/response call to a channel. `payload` is optional so
+     * inputless operations can be called as `invoke(channel)`.
+     */
+    invoke(channel: string, payload?: unknown): Promise<unknown>;
+    /**
+     * Subscribe to a main-process push channel (the `__event:`-prefixed events
+     * emitted by `WindowEventService`). Returns an unsubscribe function.
+     */
+    subscribe(channel: string, listener: (payload: unknown) => void): () => void;
+}
+/** One channel's input/output contract. The generated channel map is a record of these. */
+interface WoodChannelContract {
+    input: unknown;
+    output: unknown;
+}
+/** Shape a generated channel map conforms to: channel name -> { input, output }. */
+type WoodChannelMapLike = Record<string, WoodChannelContract>;
+/** Extract the input type for a channel in a generated map. */
+type WoodChannelInput<M extends WoodChannelMapLike, C extends keyof M> = M[C]['input'];
+/** Extract the output type for a channel in a generated map. */
+type WoodChannelOutput<M extends WoodChannelMapLike, C extends keyof M> = M[C]['output'];
+/**
+ * A `call()` typed from a generated channel map. Harness `api.call` is this,
+ * parameterized on the app's generated `WoodChannelMap`:
+ *
+ *   const call: TypedCall<WoodChannelMap> = ...;
+ *   await call('messages.send', { threadId, text });  // fully typed
+ */
+type TypedCall<M extends WoodChannelMapLike> = <C extends keyof M & string>(channel: C, ...payload: M[C]['input'] extends void ? [] : [M[C]['input']]) => Promise<M[C]['output']>;
+
+export type { TypedCall, WoodChannelContract, WoodChannelInput, WoodChannelMapLike, WoodChannelOutput, WoodRpcTransport };

package/dist/transport/wood_rpc_transport.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The single seam every test-mode RPC path is built on.
+ *
+ * Production uses the Electron preload bridge (`ipcRenderer.invoke` +
+ * `ipcRenderer.on('__event:...')`). Tests use one of the in-process or loopback
+ * implementations. The generated bridge client is built over whichever transport
+ * is supplied, so application code never knows which one is active.
+ *
+ * IMPORTANT (fast-tier isolation): this module and `InProcessRouterTransport`
+ * must never import `electron` or `playwright`. Keep this file dependency-free.
+ */
+interface WoodRpcTransport {
+    /**
+     * Dispatch a request/response call to a channel. `payload` is optional so
+     * inputless operations can be called as `invoke(channel)`.
+     */
+    invoke(channel: string, payload?: unknown): Promise<unknown>;
+    /**
+     * Subscribe to a main-process push channel (the `__event:`-prefixed events
+     * emitted by `WindowEventService`). Returns an unsubscribe function.
+     */
+    subscribe(channel: string, listener: (payload: unknown) => void): () => void;
+}
+/** One channel's input/output contract. The generated channel map is a record of these. */
+interface WoodChannelContract {
+    input: unknown;
+    output: unknown;
+}
+/** Shape a generated channel map conforms to: channel name -> { input, output }. */
+type WoodChannelMapLike = Record<string, WoodChannelContract>;
+/** Extract the input type for a channel in a generated map. */
+type WoodChannelInput<M extends WoodChannelMapLike, C extends keyof M> = M[C]['input'];
+/** Extract the output type for a channel in a generated map. */
+type WoodChannelOutput<M extends WoodChannelMapLike, C extends keyof M> = M[C]['output'];
+/**
+ * A `call()` typed from a generated channel map. Harness `api.call` is this,
+ * parameterized on the app's generated `WoodChannelMap`:
+ *
+ *   const call: TypedCall<WoodChannelMap> = ...;
+ *   await call('messages.send', { threadId, text });  // fully typed
+ */
+type TypedCall<M extends WoodChannelMapLike> = <C extends keyof M & string>(channel: C, ...payload: M[C]['input'] extends void ? [] : [M[C]['input']]) => Promise<M[C]['output']>;
+
+export type { TypedCall, WoodChannelContract, WoodChannelInput, WoodChannelMapLike, WoodChannelOutput, WoodRpcTransport };

package/dist/transport/wood_rpc_transport.js

@@ -0,0 +1 @@
+//# sourceMappingURL=wood_rpc_transport.js.map

package/dist/transport/wood_rpc_transport.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/docs/browser-testing.md

@@ -257,11 +257,149 @@ await mounted.expect.hidden('.menu');
 await mounted.expect.insideViewport('.composer', { margin: 8 });
 await mounted.expect.notClipped('.popover');
 await mounted.expect.notOverlapping('.toast', '.composer');
-await mounted.expect.zIndexAbove('.modal', '.backdrop');
 await mounted.expect.stableAfterAnimation('.drawer');
 await mounted.expect.screenshot('settings-drawer');
 ```
 
+### Geometry assertion kit
+
+Honest alignment, occlusion, and front/behind primitives. They read real boxes
+(`getBoundingClientRect`), query Chromium's real paint tree (CDP
+`DOMSnapshot.captureSnapshot`), and hit-test real painted pixels
+(`document.elementFromPoint`) rather than trusting computed `z-index`.
+
+**Prefer the whole-element mechanisms.** They answer "which layer is on top" and
+"is any foreign layer painted over this element" for the entire element, with no
+point to pick. The point-sampling forms are the special case for point-specific
+questions ("does a click at THIS spot land here").
+
+The whole-element visibility/stacking hierarchy is:
+
+- `inFrontOf` — paint-order front/behind between two named elements.
+- `notCovered` — paint-order coverage: is ANY foreign element painted over the
+  target's rect. This is the visibility check (replaces the removed
+  `fullyVisible`).
+- `unoccluded` — click-target point check honouring `pointer-events`.
+
+```ts
+// Batch rect reader (one snapshot per selector, in order).
+const [head, value] = await mounted.expect.rects(['.col-head', '.col-value']);
+
+// Alignment: shared edge / shared center axis within a tolerance (default 1px).
+await mounted.expect.sharedEdge('.col-head', '.col-value', 'right', { tolerance: 1 });
+await mounted.expect.sharedAxis('.col-head', '.col-value', 'centerX', { tolerance: 1 });
+
+// Spacing: edge-to-edge gap between two elements along an axis. Order is derived
+// from the rects (leftmost/topmost is the earlier box), not the argument order.
+// At least one of equals/min/max is required; all are within `tolerance` (1px).
+await mounted.expect.gapBetween('.chip-a', '.chip-b', 'horizontal', { equals: 8 });
+await mounted.expect.gapBetween('.row-a', '.row-b', 'vertical', { min: 4, max: 12 });
+
+// Spacing: 3+ elements evenly spaced along an axis (sorted by position, adjacent
+// gaps compared). Passes when max gap - min gap <= tolerance.
+await mounted.expect.evenlySpaced(['.tick-1', '.tick-2', '.tick-3'], 'horizontal', { tolerance: 1 });
+
+// Front/behind (DEFAULT: whole-element paint order via CDP DOMSnapshot).
+// Passes when `.modal` has a strictly greater global paint-order index than
+// `.backdrop` — painted later == on top.
+await mounted.expect.inFrontOf('.modal', '.backdrop');
+
+// Whole-element visibility (DEFAULT): no foreign layer paints over the target.
+// Paint-order coverage via CDP DOMSnapshot — inspectable, not a black box.
+await mounted.expect.notCovered('.primary-button');
+
+// --- Point-specific special cases ---
+
+// "Does a click at this spot land on the target?" (honours pointer-events).
+await mounted.expect.unoccluded('.primary-button');
+
+// Front/behind AT ONE PIXEL: hit-test an explicit point (or the intersection
+// center when omitted). Use only when the question is point-specific.
+await mounted.expect.inFrontOf('.tooltip', '.row', { at: { x: 120, y: 48 } });
+
+// Low-level hit test: describes the top painted element at a point.
+const hit = await mounted.expect.hitTest('.primary-button', 'center');
+// hit.isTarget / hit.isDescendantOfTarget / hit.description
+```
+
+`gapBetween` and `evenlySpaced` (spacing): `gapBetween(a, b, axis, opts)` measures
+the edge-to-edge distance between two elements along the axis. The order is read
+from the rects, not the argument order — the box with the smaller leading edge
+(left for `'horizontal'`, top for `'vertical'`) is the earlier box and the gap is
+`later.leading - earlier.trailing`. At least one of `equals` / `min` / `max` is
+required. A negative gap means the border boxes OVERLAP along the axis; that fails
+with a clear overlap message UNLESS the constraint explicitly allows negatives (a
+negative `equals` or `min`), so you can assert an intentional overlap.
+`evenlySpaced(selectors, axis, opts)` needs 3+ elements, sorts them by position,
+computes adjacent gaps, and passes when `max gap - min gap <= tolerance`; its
+failure message lists every gap and names the widest and narrowest (offending)
+pairs.
+
+> **Border-box caveat.** Both spacing matchers read border boxes
+> (`getBoundingClientRect`), so the gap is the distance between the elements'
+> outer borders and EXCLUDES any padding inside them. A test that cares about
+> visual whitespace between inner content should target the inner content
+> elements, not their padded wrappers.
+
+`inFrontOf` (default) and `zIndexAbove` (deprecated): `zIndexAbove` compares
+numeric computed `z-index` only and therefore lies whenever stacking contexts,
+DOM paint order (auto/equal z-index), or transform/opacity contexts decide the
+real order. `inFrontOf` reads the browser's actual global paint order, so it
+agrees with the painted pixel. Higher paint-order index == painted later == on
+top (verified against the stacking-context trap, where a `z-index:9999`
+descendant of a `z-index:1` parent still paints BEHIND a root-context sibling at
+`z-index:2`). Multiple paint fragments collapse to the element's max index. Paint
+order is Chromium-only (needs a CDP session); pass `{ at }` to use the
+point hit-test form on other browsers. Non-overlapping elements still get a valid
+verdict — the failure message notes there is no shared pixel where front/behind is
+visually observable.
+
+`notCovered` vs `unoccluded`:
+
+- `notCovered` is the **painted-coverage / visibility** check. From the real
+  paint tree (CDP `DOMSnapshot.captureSnapshot` with paint order + computed
+  styles + DOM rects) it finds every element whose rect overlaps the target,
+  excludes the target's own ancestors/descendants, and excludes candidates that
+  paint nothing visible in the overlap per an explicit, documented
+  transparent-wrapper heuristic (`opacity:0`/`visibility:hidden`, or no
+  background-color alpha AND `background-image:none` AND all border widths `0px`
+  AND no own text/replaced content — `box-shadow`/`outline` are NOT counted as
+  coverage). It then fails if any remaining foreign element has a higher paint
+  order than the target, naming that element, its rect, and both paint indices.
+- `unoccluded` is the **click-target** check. It hit-tests one pixel and honours
+  `pointer-events` — a `pointer-events: none` overlay painted on top does NOT
+  fail it, because it does not intercept the click. It is not a general
+  visibility check.
+
+Because `notCovered` tracks PAINTED coverage, a visually-opaque
+`pointer-events: none` overlay DOES fail `notCovered` while `unoccluded` passes —
+the honest, complementary difference between "covered by a painted layer" and
+"reachable by a click". The transparent-wrapper heuristic is the key asymmetry:
+a bare positioning wrapper spanning the target passes `notCovered` (it paints
+nothing), while an opaque overlay fails.
+
+> **Why not IntersectionObserver v2?** `notCovered` replaced an earlier
+> `fullyVisible` matcher built on IOv2 (`{ trackVisibility: true, delay: 100 }`,
+> read via `entry.isVisible`). IOv2's `isVisible` is a black box: Chromium
+> reports `false` not only for distorting ancestor effects (`opacity < 1`,
+> `filter`, `transform`, `mix-blend-mode`) but also for its OCCLUSION pass — ANY
+> element painted later than the target within its rect disqualifies visibility,
+> **even a fully transparent one**, and IOv2 never checks whether the covering
+> pixels are actually opaque. This was pinned empirically against the demo app's
+> global stylesheet: the culprit is a single `#app::after { content:''; inset:0;
+> z-index:9999 }` frame-overlay pseudo-element. Reduced to just
+> `content:''; position:absolute; inset:0` (no background, no shadow, no
+> z-index) it still forced `isVisible:false` for every element beneath it;
+> removing `content` (so no pseudo box is generated) restored `true`. A matcher
+> whose "not visible" verdict can mean either real occlusion or an invisible
+> overlay is untrustworthy — so it was replaced by `notCovered`, whose coverage
+> rule is fully inspectable and exempts transparent layers by construction.
+
+> `elementFromPoint` (used by `unoccluded` and `inFrontOf { at }`) honours
+> `pointer-events`. An element with `pointer-events: none` painted on top is
+> transparent to those point checks — usually the intended contract for a
+> click-target assertion.
+
 Screenshots are written to `test-results/wood-browser`.
 
 ## Lifecycle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/wood",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,6 +49,24 @@
       "import": "./dist/trace-testing/index.js",
       "default": "./dist/trace-testing/index.js"
     },
+    "./transport": {
+      "types": "./dist/transport/index.d.ts",
+      "require": "./dist/transport/index.cjs",
+      "import": "./dist/transport/index.js",
+      "default": "./dist/transport/index.js"
+    },
+    "./trace-transport": {
+      "types": "./dist/trace-transport/index.d.ts",
+      "require": "./dist/trace-transport/index.cjs",
+      "import": "./dist/trace-transport/index.js",
+      "default": "./dist/trace-transport/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "require": "./dist/runtime/index.cjs",
+      "import": "./dist/runtime/index.js",
+      "default": "./dist/runtime/index.js"
+    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "require": "./dist/client/index.cjs",
@@ -100,9 +118,10 @@
   },
   "dependencies": {
     "@noego/ioc": "^0.3.1",
-    "@noego/logger": "^0.0.2",
+    "@noego/logger": "^0.0.4",
     "@noego/stitch": "^1.0.3",
-    "@noego/trace": "^0.0.2",
+    "@noego/telemetry": "^0.0.1",
+    "@noego/trace": "^0.0.6",
     "ajv": "^8.x",
     "ajv-formats": "^3.x",
     "chokidar": "^4.x",

package/src/components/NavigationShell.browser.test.ts

@@ -0,0 +1,236 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, test } from 'vitest';
+import { browser } from '../testing/browser';
+
+type ReproSnapshot = {
+  pageCreateCount: number;
+  layoutCreateCount: number;
+  disposeCounts: Record<string, number>;
+  rendered: string;
+  pageErrors: string[];
+};
+
+describe('NavigationShell failed transition recovery', () => {
+  const harnesses: Array<{ destroy(): Promise<void> }> = [];
+  const tempRoots: string[] = [];
+
+  afterEach(async () => {
+    while (harnesses.length > 0) {
+      await harnesses.pop()?.destroy();
+    }
+    while (tempRoots.length > 0) {
+      rmSync(tempRoots.pop()!, { recursive: true, force: true });
+    }
+  });
+
+  test('does not orphan a controller when a sibling layout creation rejects', async () => {
+    const woodRoot = path.resolve(__dirname, '../..');
+    const rootDir = mkdtempSync(path.join(os.tmpdir(), 'wood-navigation-shell-repro-'));
+    tempRoots.push(rootDir);
+    mkdirSync(path.join(rootDir, 'ui'), { recursive: true });
+
+    writeFileSync(
+      path.join(rootDir, 'ui', 'ReproView.svelte'),
+      `<script lang="ts">
+        let { data = {}, page = {} } = $props<{
+          data?: { id?: string };
+          page?: { params?: { threadId?: string } };
+        }>();
+      </script>
+
+      <main data-repro-view>
+        thread={page.params?.threadId ?? 'missing'};controller={data.id ?? 'missing'}
+      </main>`,
+    );
+
+    writeFileSync(
+      path.join(rootDir, 'ui', 'ReproLayout.svelte'),
+      `<script lang="ts">
+        import type { Snippet } from 'svelte';
+        let { children }: { children: Snippet } = $props();
+      </script>
+
+      <section data-repro-layout>{@render children()}</section>`,
+    );
+
+    writeFileSync(
+      path.join(rootDir, 'ui', 'NavigationShellRepro.svelte'),
+      `<script lang="ts">
+        import '/@fs/${woodRoot}/src/client/global_polyfill.ts';
+        import NavigationShell from '/@fs/${woodRoot}/src/components/NavigationShell.svelte';
+        import { getNavigation } from '/@fs/${woodRoot}/src/navigation/index.ts';
+        import ReproLayout from './ReproLayout.svelte';
+        import ReproView from './ReproView.svelte';
+
+        type ReproState = {
+          pageCreateCount: number;
+          layoutCreateCount: number;
+          disposeCounts: Record<string, number>;
+        };
+
+        const state: ReproState = {
+          pageCreateCount: 0,
+          layoutCreateCount: 0,
+          disposeCounts: {},
+        };
+        (window as unknown as { __WOOD_NAVIGATION_REPRO__: ReproState })
+          .__WOOD_NAVIGATION_REPRO__ = state;
+
+        function createController(id: string) {
+          state.disposeCounts[id] = 0;
+          return {
+            data: { id },
+            dispose() {
+              state.disposeCounts[id] += 1;
+            },
+          };
+        }
+
+        const entry = {
+          key: 'main.chat_dom',
+          windowName: 'main',
+          pageName: 'chat_dom',
+          layoutPaths: ['ui/ReproLayout.svelte'],
+          layoutControllers: ['repro-layout-controller'],
+          layoutPreserve: [false],
+          view: ReproView,
+          layouts: [ReproLayout],
+        };
+        const manifest = { [entry.key]: entry };
+        const initialController = createController('initial-page');
+        const initialLayoutControllers = [createController('initial-layout')];
+
+        async function createViewControllerFn() {
+          state.pageCreateCount += 1;
+          return createController(\`page-\${state.pageCreateCount}\`);
+        }
+
+        async function createLayoutControllersFn() {
+          state.layoutCreateCount += 1;
+          if (state.layoutCreateCount === 1) {
+            await Promise.resolve();
+            throw new Error('controlled layout creation failure');
+          }
+          return [createController(\`layout-\${state.layoutCreateCount}\`)];
+        }
+
+        function getViewManifestEntryFn(viewKey: string) {
+          return manifest[viewKey as keyof typeof manifest] ?? null;
+        }
+
+        const navigation = getNavigation();
+        navigation.replace(entry.key, { threadId: '1' }, {});
+        (window as unknown as {
+          __WOOD_NAVIGATION_REPRO_GO__: (threadId: string) => void;
+        }).__WOOD_NAVIGATION_REPRO_GO__ = (threadId: string) => {
+          navigation.go(entry.key, { threadId }, {});
+        };
+      </script>
+
+      <NavigationShell
+        {manifest}
+        initialEntry={entry}
+        {initialController}
+        {initialLayoutControllers}
+        {createViewControllerFn}
+        {createLayoutControllersFn}
+        {getViewManifestEntryFn}
+      />`,
+    );
+
+    const pageErrors: string[] = [];
+    const consoleErrors: string[] = [];
+    const harness = await browser.createHarness({
+      rootDir: woodRoot,
+      browser: { headless: true },
+      page: {
+        beforeMount({ page }) {
+          page.on('pageerror', (error: Error) => pageErrors.push(error.message));
+          page.on('console', (message: { type(): string; text(): string }) => {
+            if (message.type() === 'error') consoleErrors.push(message.text());
+          });
+        },
+      },
+    });
+    harnesses.push(harness);
+    const mounted = await harness.mountComponent(
+      path.join(rootDir, 'ui', 'NavigationShellRepro.svelte'),
+    );
+    await mounted.locator('[data-repro-view]').waitFor({ state: 'visible', timeout: 5_000 }).catch(
+      async (error: unknown) => {
+        throw new Error(
+          `${error instanceof Error ? error.message : String(error)}\n` +
+          `Page errors: ${pageErrors.join(' | ')}\n` +
+          `Console errors: ${consoleErrors.join(' | ')}\n` +
+          `HTML: ${await mounted.page.content()}`,
+        );
+      },
+    );
+
+    await expect.poll(async () => {
+      return (await mounted.locator('[data-repro-view]').textContent())?.replace(/\s+/g, ' ').trim();
+    }).toBe('thread=1;controller=initial-page');
+
+    await mounted.evaluate(() => {
+      (window as unknown as {
+        __WOOD_NAVIGATION_REPRO_GO__: (threadId: string) => void;
+      }).__WOOD_NAVIGATION_REPRO_GO__('2');
+    });
+    await expect.poll(async () => {
+      return await mounted.evaluate(() => {
+        return (window as unknown as {
+          __WOOD_NAVIGATION_REPRO__: { layoutCreateCount: number };
+        }).__WOOD_NAVIGATION_REPRO__.layoutCreateCount;
+      });
+    }).toBe(1);
+    await expect.poll(() => pageErrors.length + consoleErrors.length).toBeGreaterThan(0);
+
+    await mounted.evaluate(() => {
+      (window as unknown as {
+        __WOOD_NAVIGATION_REPRO_GO__: (threadId: string) => void;
+      }).__WOOD_NAVIGATION_REPRO_GO__('2');
+    });
+    await expect.poll(async () => {
+      return await mounted.evaluate(() => {
+        return (window as unknown as {
+          __WOOD_NAVIGATION_REPRO__: { pageCreateCount: number };
+        }).__WOOD_NAVIGATION_REPRO__.pageCreateCount;
+      });
+    }).toBe(2);
+    await expect.poll(async () => {
+      return (await mounted.locator('[data-repro-view]').textContent())?.replace(/\s+/g, ' ').trim();
+    }).toBe('thread=2;controller=page-2');
+
+    const snapshot = await mounted.evaluate<ReproSnapshot>(() => {
+      const state = (window as unknown as {
+        __WOOD_NAVIGATION_REPRO__: Omit<ReproSnapshot, 'rendered' | 'pageErrors'>;
+      }).__WOOD_NAVIGATION_REPRO__;
+      return {
+        ...state,
+        disposeCounts: { ...state.disposeCounts },
+        rendered: document.querySelector('[data-repro-view]')?.textContent?.replace(/\s+/g, ' ').trim() ?? '',
+        pageErrors: [],
+      };
+    });
+    snapshot.pageErrors = [...pageErrors];
+
+    expect(
+      snapshot,
+      'A failed transition must preserve committed controllers and dispose any staged controller before a retry.',
+    ).toEqual({
+      pageCreateCount: 2,
+      layoutCreateCount: 2,
+      disposeCounts: {
+        'initial-page': 1,
+        'initial-layout': 1,
+        'page-1': 1,
+        'page-2': 0,
+        'layout-2': 0,
+      },
+      rendered: 'thread=2;controller=page-2',
+      pageErrors: [],
+    });
+  }, 30_000);
+});