@noego/wood 0.4.9 → 0.5.0

package/docs/axe.md

@@ -0,0 +1,706 @@
+# Axe — Live Wood App Driver
+
+`axe` is the live-application driver shipped with `@noego/wood`. It connects to
+an already-running Wood Electron app over Playwright/CDP and lets a developer
+inspect or operate the real renderer.
+
+It is not the `axe-core` accessibility scanner.
+
+This document has two explicit parts:
+
+- **Current CLI** — behavior that exists today.
+- **Target driver platform** — the proposed direction for making Axe useful for
+  deterministic full-app testing, including route transitions, window changes,
+  nested scrolling, virtualized content, waits, and failure evidence.
+
+Do not use a proposed command in automation until it has been implemented and
+appears in the current CLI reference.
+
+## Why Axe exists
+
+Wood has several complementary test surfaces:
+
+| Surface | Best use |
+| --- | --- |
+| Node/controller tests | Pure state, service, routing, policy, and producer behavior |
+| `@noego/wood/testing` browser harness | Real Svelte, CSS, browser APIs, routes, layouts, geometry, animation, and controlled bridge fixtures without Electron |
+| `@noego/wood/trace-testing` | Ordered runtime-flow assertions across renderer, main, and test processes |
+| `stick` | Rendering a known component/state boundary |
+| `axe` | Inspecting and driving the actual running Electron application |
+
+Axe is the authoritative surface when the behavior depends on the live app:
+window ownership, actual preload wiring, current HMR state, real IPC, open
+menus, transcript state, or another condition that cannot be recreated honestly
+in an isolated mount.
+
+Axe does not replace the lower test tiers. A live click proving that a screen
+works does not replace producer, controller, or state-machine tests for the
+logic that built the screen.
+
+# Current CLI
+
+## Prerequisites
+
+Start the app with `wood dev` from the project root:
+
+```bash
+npx wood dev
+```
+
+`wood dev` enables a loopback Electron debugging endpoint and writes connection
+metadata to:
+
+```text
+.wood/dev.json
+```
+
+The metadata includes the project, process ID, debug port, and browser URL.
+Axe reads this file from the current working directory, so run Axe from the same
+project root.
+
+Playwright is an optional peer dependency. Install it in the app project before
+using Axe:
+
+```bash
+npm install --save-dev playwright
+```
+
+## Commands available today
+
+```text
+axe targets [--window <windowId>]
+axe js [--window <windowId>]
+axe click <selector> [--window <windowId>]
+axe type <selector> <text> [--window <windowId>]
+axe screenshot [path] [--window <windowId>]
+```
+
+Every command is currently **one-shot**:
+
+1. read `.wood/dev.json`;
+2. connect with `chromium.connectOverCDP(...)`;
+3. discover pages;
+4. perform one operation;
+5. close the Playwright browser connection.
+
+No target generation, route state, trace cursor, or observation is retained
+between commands.
+
+## `axe targets`
+
+Lists pages discovered in every connected browser context:
+
+```bash
+npx axe targets
+```
+
+Output is JSON Lines:
+
+```json
+{"index":0,"windowId":"main","defaultRoute":"chat","title":"Kazibee","url":"http://localhost:5173/"}
+```
+
+Fields:
+
+- `index` is the current enumeration index. It is diagnostic, not durable
+  identity.
+- `windowId` comes from
+  `globalThis.__NOEGO_WOOD_BRIDGE__.__window.current()` when the page has a Wood
+  bridge.
+- `defaultRoute` is the **configured default route for the window**. It is not
+  the route currently displayed after Wood in-app navigation.
+- `title` and `url` come from the current Playwright page.
+
+Pages without a Wood bridge may still appear with `windowId: null`.
+
+When an app has more than one window, always pass `--window`. Without it, the
+current implementation chooses the first discovered page, whose ordering is not
+a stable test contract.
+
+## `axe click`
+
+Uses a Playwright CSS locator and performs a real actionability-checked click:
+
+```bash
+npx axe click '[data-testid="settings-nav"]' --window main
+```
+
+Playwright waits for the target to become actionable and scrolls it into view
+when necessary. The command does not wait for an app route, document, popup, or
+render-settle postcondition after the click.
+
+## `axe type`
+
+Despite the command name, the current implementation calls Playwright
+`locator.fill(...)`:
+
+```bash
+npx axe type '[data-testid="composer-input"]' "hello" --window main
+```
+
+This clears and fills a supported form control. It does **not** emit one keyboard
+character at a time. A future driver must expose `fill` and true keyboard
+`type` as separate actions.
+
+## `axe screenshot`
+
+Captures the selected Playwright page:
+
+```bash
+npx axe screenshot artifacts/current.png --window main
+```
+
+When no path is supplied, Axe writes an `axe-screenshot-<timestamp>.png` file in
+the current directory.
+
+## `axe js`
+
+Reads a JavaScript function body from stdin and evaluates it as an async
+function in the selected renderer:
+
+```bash
+echo 'return document.title' | npx axe js --window main
+```
+
+Use `return` to emit a JSON result.
+
+This is a powerful developer escape hatch. It can inspect or mutate DOM state,
+call bridge operations directly, or bypass the real UI. Therefore:
+
+- use it for diagnosis, not release qualification;
+- do not treat `element.click()` as proof that a user click is reachable;
+- do not call backend bridge operations directly when testing a UI workflow;
+- do not expose this surface as product authority;
+- avoid printing secrets or user content into terminal history and logs.
+
+### Window identity is not current route state
+
+This returns window identity and configured default route:
+
+```bash
+echo '
+const bridge = globalThis.__NOEGO_WOOD_BRIDGE__;
+return await bridge.__window.current();
+' | npx axe js --window main
+```
+
+It does not return Wood's active navigation entry.
+
+For temporary diagnosis only, current Wood navigation is stored on a global
+symbol by the renderer navigation runtime:
+
+```bash
+echo '
+const navigation = globalThis[Symbol.for("@noego/wood.navigation")];
+return navigation?.getCurrent?.() ?? null;
+' | npx axe js --window main
+```
+
+This is an internal debug technique, not a stable Axe API. The target platform
+below adds an explicit versioned route-introspection contract.
+
+### Temporary scrolling diagnosis
+
+Axe has no typed scroll command today. JavaScript can inspect or set a scroll
+container for diagnosis:
+
+```bash
+echo '
+const element = document.querySelector("[data-testid=transcript-scroll-root]");
+if (!(element instanceof HTMLElement)) throw new Error("scroll root missing");
+const before = {
+  top: element.scrollTop,
+  height: element.clientHeight,
+  scrollHeight: element.scrollHeight
+};
+element.scrollBy({ top: 600, behavior: "instant" });
+await new Promise(resolve => requestAnimationFrame(() => resolve()));
+return {
+  before,
+  after: {
+    top: element.scrollTop,
+    height: element.clientHeight,
+    scrollHeight: element.scrollHeight
+  }
+};
+' | npx axe js --window main
+```
+
+This directly mutates page state and bypasses real wheel routing. It is useful
+for inspection, not a substitute for a qualified user-like scroll action.
+
+## Current limitations
+
+The shipped CLI does not yet provide:
+
+- a persistent multi-step connection;
+- deterministic target generations or page-replacement tracking;
+- the actual current Wood route;
+- route, URL, popup, target, trace, or element postcondition waits;
+- semantic locators such as role/name, label, placeholder, or test ID;
+- viewport or named-container scrolling;
+- bounded virtual-list traversal;
+- before/after observations and action receipts;
+- console, page-error, failed-request, and trace evidence;
+- automatic screenshots and diagnostics on failure;
+- a generic multi-window Electron fixture that qualifies Axe itself.
+
+These gaps matter because separate commands cannot reliably prove:
+
+```text
+click → route/window transition → rendering settles → expected UI appears
+```
+
+The second command reconnects from scratch and may select a different page,
+miss a fast transition, observe an intermediate render, or lose the failure
+context from the first command.
+
+# Target driver platform
+
+## Design decision
+
+Move connection, target discovery, actions, waits, scrolling, observations,
+receipts, and evidence out of `bin/axe.js` into typed source. Keep the CLI as a
+thin adapter.
+
+Recommended package shape:
+
+```text
+src/automation/
+  connection.ts
+  target_registry.ts
+  target_identity.ts
+  locator.ts
+  observation.ts
+  actions.ts
+  waits.ts
+  stability.ts
+  scrolling.ts
+  diagnostics.ts
+  evidence.ts
+  scenario.ts
+  receipts.ts
+  errors.ts
+bin/
+  axe.js
+```
+
+Proposed public entry point:
+
+```ts
+import { automation } from '@noego/wood/automation';
+```
+
+The same neutral contracts should be usable by:
+
+- the Axe CLI;
+- Wood's isolated browser harness;
+- app-specific full-Electron tests;
+- deterministic computer-use adapter conformance tests.
+
+Sharing contracts does not share product authority. See
+[Computer Use boundary](#computer-use-boundary).
+
+## Dev/test introspection contract
+
+Add a development/test-only, versioned renderer surface for facts Axe cannot
+infer reliably from a page URL:
+
+```ts
+type WoodAutomationSnapshot = {
+  version: 1;
+  windowId: string;
+  currentRoute: {
+    page: string;
+    params: Record<string, string>;
+    query: Record<string, string>;
+  } | null;
+  rendererReady: boolean;
+  pendingWork: {
+    bridgeCalls: number;
+    renders: number;
+    animations: number;
+  };
+  traceCursor?: string;
+};
+```
+
+Suggested bridge:
+
+```ts
+bridge.__automation.snapshot()
+bridge.__automation.waitForIdle({ timeoutMs })
+bridge.__automation.subscribe(event => ...)
+```
+
+Requirements:
+
+- absent from normal production builds;
+- inspection and synchronization only;
+- versioned schemas;
+- no arbitrary privileged operation dispatch;
+- route, render, target, and stability changes traced through Wood where
+  possible.
+
+## Deterministic target identity
+
+A target needs more than an array index:
+
+```ts
+type WoodLiveTarget = {
+  targetId: string;
+  windowId: string | null;
+  webContentsId?: number;
+  pageGeneration: number;
+  url: string;
+  title: string;
+  currentRoute?: string;
+  configuredDefaultRoute?: string;
+  woodBridgePresent: boolean;
+  eligible: boolean;
+};
+```
+
+Rules:
+
+- reject non-Wood pages by default;
+- require `windowId` when several eligible targets exist;
+- use CDP target identity plus Wood window identity;
+- replace or increment `pageGeneration` after reload or target replacement;
+- fail when the target changes unexpectedly;
+- adopt a popup or replacement only when the scenario declares that
+  transition.
+
+## Semantic locator model
+
+```ts
+type WoodLocator =
+  | { kind: 'test_id'; value: string }
+  | { kind: 'role'; role: string; name?: string; exact?: boolean }
+  | { kind: 'label'; value: string; exact?: boolean }
+  | { kind: 'placeholder'; value: string; exact?: boolean }
+  | { kind: 'text'; value: string; exact?: boolean }
+  | { kind: 'css'; value: string };
+```
+
+Semantic locators should be preferred. CSS remains an escape hatch and should
+be marked as lower stability in receipts.
+
+A locator resolves to exactly one actionable target unless the scenario
+explicitly chooses `first`, `last`, or an index. Failure output should include:
+
+- number of matches;
+- visibility and enabled state;
+- element bounds;
+- actionability failure;
+- center-point hit-test result;
+- likely covering element where available.
+
+## Canonical actions
+
+```ts
+type WoodAutomationAction =
+  | { kind: 'click'; target: WoodLocator }
+  | { kind: 'double_click'; target: WoodLocator }
+  | { kind: 'fill'; target: WoodLocator; value: string }
+  | { kind: 'type'; target: WoodLocator; value: string; delayMs?: number }
+  | { kind: 'press'; target?: WoodLocator; keys: string[] }
+  | { kind: 'select'; target: WoodLocator; option: string }
+  | { kind: 'toggle'; target: WoodLocator; checked: boolean }
+  | { kind: 'scroll'; command: WoodScrollCommand }
+  | { kind: 'back' }
+  | { kind: 'forward' }
+  | { kind: 'reload' }
+  | { kind: 'wait'; condition: WoodWaitCondition };
+```
+
+Every action returns a structured receipt with target and route before/after,
+duration, actionability, document/target/route changes, diagnostics, and evidence
+references.
+
+## Click-through transition contract
+
+A click expected to move the app declares its postcondition. Supported
+transitions should include:
+
+- exact Wood route and route values;
+- URL or origin;
+- document generation;
+- window or popup appeared;
+- current window closed;
+- element visible, hidden, attached, or detached;
+- trace event occurred;
+- explicitly no route/target transition.
+
+Execution order:
+
+1. capture target, route, document, viewport, and trace cursor;
+2. resolve one actionable target;
+3. arm route, target, popup, document, and trace listeners;
+4. perform the Playwright action;
+5. reconcile window and page identity;
+6. wait for the declared postcondition;
+7. wait for bounded app or visual stability where requested;
+8. capture after-state and evidence;
+9. emit one receipt.
+
+Listeners must be armed before the action so an immediate route or popup event
+cannot be missed.
+
+## Scrolling model
+
+```ts
+type WoodScrollContainer =
+  | { kind: 'viewport' }
+  | { kind: 'locator'; target: WoodLocator };
+
+type WoodScrollCommand =
+  | {
+      mode: 'wheel';
+      container: WoodScrollContainer;
+      deltaX?: number;
+      deltaY?: number;
+    }
+  | {
+      mode: 'position';
+      container: WoodScrollContainer;
+      x?: number;
+      y?: number;
+      edge?: 'top' | 'bottom' | 'left' | 'right';
+    }
+  | {
+      mode: 'into_view';
+      target: WoodLocator;
+      block?: 'start' | 'center' | 'end' | 'nearest';
+    }
+  | {
+      mode: 'until';
+      container: WoodScrollContainer;
+      target: WoodLocator;
+      direction: 'up' | 'down' | 'left' | 'right';
+      stepPx: number;
+      maxSteps: number;
+    };
+```
+
+Rules:
+
+- `wheel` proves user-like wheel routing;
+- `position` is deterministic direct state setting and is labelled as such;
+- nested containers are explicit unless there is exactly one provable scroll
+  owner;
+- every step reports `scrollTop`, `scrollLeft`, client size, scroll size, edge
+  state, and whether movement occurred;
+- `until` has a hard step bound and exits on no progress;
+- virtualized scenarios assert both scroll movement and newly materialized item
+  identity;
+- smooth scrolling is opt-in and requires a stability barrier;
+- test helpers may iterate, but each underlying action remains observable.
+
+## Waits and stability
+
+```ts
+type WoodWaitCondition =
+  | { kind: 'route'; page: string; params?: Record<string, string>; query?: Record<string, string> }
+  | { kind: 'url'; value: string; match?: 'exact' | 'glob' | 'regex' }
+  | { kind: 'target'; windowId: string; state: 'present' | 'active' | 'closed' }
+  | { kind: 'visible' | 'hidden' | 'attached' | 'detached' | 'enabled'; target: WoodLocator }
+  | { kind: 'trace'; type: string; source?: string; count?: number }
+  | { kind: 'scroll_edge'; container: WoodScrollContainer; edge: 'top' | 'bottom' | 'left' | 'right' }
+  | { kind: 'visual_stable'; target?: WoodLocator; frames?: number }
+  | { kind: 'app_idle' };
+```
+
+Every wait is bounded and reports its final observed state. Fixed sleeps may be
+an explicit diagnostic operation, but normal scenarios should synchronize on a
+real condition. `networkidle` is not a universal app-idle signal for streaming
+or long-lived connections.
+
+## Persistent scenario mode
+
+Proposed CLI:
+
+```bash
+axe run scenario.json
+axe run --stdin
+```
+
+One scenario keeps one CDP connection, target registry, trace cursor, and
+evidence directory.
+
+Example:
+
+```json
+{
+  "version": 1,
+  "target": { "windowId": "main" },
+  "evidence": {
+    "screenshot": "on-failure",
+    "console": true,
+    "trace": true
+  },
+  "steps": [
+    {
+      "name": "open settings",
+      "action": {
+        "kind": "click",
+        "target": { "kind": "test_id", "value": "settings-nav" }
+      },
+      "wait": {
+        "kind": "route",
+        "page": "settings.general"
+      }
+    },
+    {
+      "name": "reach integrations",
+      "action": {
+        "kind": "scroll",
+        "command": {
+          "mode": "until",
+          "container": {
+            "kind": "locator",
+            "target": { "kind": "test_id", "value": "settings-scroll-root" }
+          },
+          "target": {
+            "kind": "test_id",
+            "value": "integrations-section"
+          },
+          "direction": "down",
+          "stepPx": 500,
+          "maxSteps": 12
+        }
+      }
+    }
+  ]
+}
+```
+
+Scenario output should be JSON Lines, with human-readable rendering built from
+the same receipts.
+
+Defaults:
+
+- fail fast;
+- explicit target when multiple windows exist;
+- no raw JavaScript;
+- no fixed sleeps;
+- bounded observation waits;
+- never retry an action implicitly;
+- redact typed values;
+- capture screenshot and diagnostics on failure.
+
+## Evidence and diagnostics
+
+A failed step should be able to include:
+
+- stable target identity and page generation;
+- current route, route parameters, and route query;
+- title and URL;
+- viewport, scale, focus, and document generation;
+- selected scroll-root metrics;
+- locator match/actionability details;
+- recent console errors;
+- page errors and failed requests;
+- trace events since the step cursor;
+- before and after screenshots;
+- elapsed action and wait timing.
+
+Evidence paths should be returned as artifacts/receipts rather than mixed into
+unstructured command prose.
+
+## Shared assertion kit
+
+The strong assertions currently implemented inside `src/testing/browser.ts`
+should be extracted so mounted browser surfaces and live Axe targets can share
+them where the runtime supports the required capability:
+
+- visible and hidden;
+- inside viewport;
+- not clipped;
+- not overlapping;
+- hit testing and `unoccluded`;
+- CDP paint-order `inFrontOf`;
+- CDP painted-coverage `notCovered`;
+- rects, shared edges, shared axes, gaps, and even spacing;
+- animation/geometry stability;
+- screenshot evidence;
+- route, target, scroll, trace, console, and page-error assertions.
+
+Chromium/CDP-only assertions must report an unsupported-capability error on
+other engines instead of silently substituting a weaker test.
+
+## Required fixture app
+
+Wood should own a small Electron fixture dedicated to the live driver. It must
+include:
+
+- at least two Wood windows;
+- internal Wood routes whose URL does not change;
+- full document navigation and reload;
+- immediate and delayed transitions;
+- popup/new-window behavior;
+- viewport scrolling;
+- a named nested scroll container;
+- virtualized content;
+- top, bottom, and no-progress scroll states;
+- semantic and intentionally ambiguous controls;
+- disabled, covered, clipped, and offscreen controls;
+- modal, popover, and stacking-context cases;
+- console error, page error, failed request, and trace cases;
+- target replacement;
+- deterministic screenshot content.
+
+## Qualification tiers
+
+1. **Automation-core unit tests** — schemas, target reconciliation, scroll
+   calculations, deadlines, redaction, receipts, and error classes.
+2. **Wood browser-harness tests** — shared actions, waits, assertions, scrolling,
+   traces, and evidence in the fastest real-browser tier.
+3. **Axe Electron-fixture tests** — CDP attachment, multi-window identity,
+   internal/full navigation, popup handling, nested/virtual scrolling,
+   diagnostics, and cleanup.
+4. **App full-Electron scenarios** — a deliberately small set of critical live
+   workflows.
+5. **Computer-use adapter conformance** — shared schemas and deterministic
+   fixtures against the dedicated product backend, not the Axe dev session.
+
+## Proposed implementation order
+
+1. Extract the current connection and target code into typed source.
+2. Make multiple-window selection deterministic.
+3. Add versioned current-route and renderer-readiness introspection.
+4. Add persistent `axe run` with click plus explicit route/element waits.
+5. Add viewport, nested-container, edge, into-view, and bounded virtual
+   scrolling.
+6. Add console, page-error, failed-request, trace, and screenshot evidence.
+7. Extract shared browser assertions.
+8. Qualify the generic fixture, then a small set of real app workflows.
+
+# Computer Use boundary
+
+Axe can provide substantial implementation and testing leverage for a managed
+browser Computer Use backend, but it is not the backend itself.
+
+Safe to share:
+
+- action, locator, wait, scroll, observation, receipt, and error schemas;
+- Playwright actionability and scrolling implementations;
+- deterministic fixture controls;
+- screenshot, trace, and diagnostic evidence formats;
+- adapter conformance scenarios;
+- bounded CDP implementation knowledge.
+
+Must remain separate:
+
+| Axe | Product Computer Use |
+| --- | --- |
+| Attaches to a running Wood development app | Launches and owns a dedicated verified browser |
+| Reads `.wood/dev.json` | Receives an authenticated session capability |
+| Developer-local authority | Explicit user-authorized product authority |
+| May retain an explicit debug-JavaScript escape hatch | Never exposes arbitrary JavaScript or raw CDP |
+| May inspect the app's own renderer | Must not target trusted controller/approval surfaces |
+| Produces test evidence | Owns policy, approval, durable ledger, data egress, retention, and independent Stop |
+
+Computer Use should import qualified neutral contracts and primitives. It must
+never inherit Axe's development endpoint, raw evaluation surface, target
+selection policy, or security assumptions.