@noego/wood 0.4.9 → 0.5.0

package/README.md

@@ -2,7 +2,9 @@
 
 Declarative Electron desktop apps using the noego ecosystem.
 
-`@noego/wood` provides config parsing, operation/view parsing, IPC routing, runtime wiring, code generation, and CLI utilities for building Electron applications with Svelte-based renderer flows.
+`@noego/wood` provides config parsing, operation/view parsing, IPC routing,
+runtime wiring, code generation, tracing, testing helpers, and CLI utilities for
+building Electron applications with Svelte-based renderer flows.
 
 ## Install
 
@@ -14,14 +16,12 @@ Peer dependencies used by the package include:
 
 - `electron >=28`
 - `svelte ^5`
-- `playwright ^1.40.0` (optional)
-- `better-sqlite3 ^11`
-- `sqlstack`
-- `@noego/proper`
+- `@sveltejs/vite-plugin-svelte ^4` (optional)
+- `playwright ^1.40.0` (optional; required by browser testing and Axe)
 
-## Package Entry Points
+## Package entry points
 
-The package publishes both ESM and CommonJS builds through `exports`.
+The package publishes ESM and CommonJS builds through `exports`.
 
 Primary entry points:
 
@@ -31,9 +31,13 @@ Primary entry points:
 - `@noego/wood/client`
 - `@noego/wood/ipc`
 - `@noego/wood/navigation`
+- `@noego/wood/runtime`
+- `@noego/wood/transport`
+- `@noego/wood/trace-transport`
 - `@noego/wood/stick`
 - `@noego/wood/testing`
 - `@noego/wood/trace-testing`
+- `@noego/wood/dev`
 - `@noego/wood/loader`
 
 Svelte component exports:
@@ -57,12 +61,17 @@ The root package exports the main framework surface, including:
 - `BackendBridge`
 - `WindowManager`
 - `runtime`
-- code generators such as `generatePreload`, `generateRuntime`, `generateRendererApp`, and `generateTypes`
+- code generators such as `generatePreload`, `generateRuntime`,
+  `generateRendererApp`, and `generateTypes`
 
 Example:
 
 ```ts
-import { parseOperationsFile, parseViewsFile, generateRuntime } from '@noego/wood';
+import {
+  generateRuntime,
+  parseOperationsFile,
+  parseViewsFile,
+} from '@noego/wood';
 
 const operations = parseOperationsFile('operations/chat.yaml');
 const views = parseViewsFile('views/app.yaml');
@@ -79,15 +88,15 @@ Controllers may optionally implement `dispose(): void | Promise<void>`.
 
 `WoodRouter` resolves a controller for each dispatch and calls `dispose()` in a
 `finally` block after the action completes or throws. Use `dispose()` to
-unsubscribe from streams, unregister listeners, or release other controller-owned
-resources.
+unsubscribe from streams, unregister listeners, or release other
+controller-owned resources.
 
 ## Tracing
 
-Wood tracing records structured runtime events that describe how a flow ran, not
-just what it returned. Use traces for async pipelines, renderer/main handoffs,
-streaming flows, recovery paths, routing decisions, and any behavior where tests
-need to prove which stages triggered and what each stage produced.
+Wood tracing records structured runtime events that describe how a flow ran,
+not only what it returned. Use traces for async pipelines, renderer/main
+handoffs, streaming flows, recovery paths, routing decisions, and any behavior
+where tests need to prove which stages triggered and what each stage produced.
 
 Application code emits traces through `TraceProvider`:
 
@@ -108,7 +117,7 @@ export class DocumentService {
       payload: { documentId, byteLength },
     });
 
-    // perform the work...
+    // Perform the work...
 
     this.trace.info({
       source: 'document.service',
@@ -144,8 +153,8 @@ Guidelines:
   `thing.failed`.
 - Include identifiers needed to correlate the flow, especially
   `conversationId` for conversation work.
-- Keep payloads structured and small: counts, selected route/model names,
-  decision fields, ids, and sizes are usually better than full data blobs.
+- Keep payloads structured and small. Counts, selected route/model names,
+  decision fields, IDs, and sizes are usually better than full data blobs.
 - Use `info` for normal lifecycle events, `warn` for recoverable surprises, and
   `error` for failures.
 - Trace values before and after any stage that can transform, overwrite, skip,
@@ -153,29 +162,71 @@ Guidelines:
 
 ## CLI
 
-This package includes two executables:
+The package includes three executables:
 
-- `wood`
-- `stick`
+- `wood` — generate and run/build a Wood Electron application;
+- `stick` — render/test a known component or state boundary;
+- `axe` — attach to and drive an already-running Wood development app through
+  Playwright/CDP.
 
-`wood` currently supports:
+### `wood`
 
 ```bash
 wood dev
 wood build
 ```
 
-Both commands generate project artifacts and pass remaining options through to `electron-vite`.
+Both commands generate project artifacts and pass remaining options through to
+`electron-vite`.
+
+### `axe`
+
+Start the app first, then invoke Axe from the same project root:
+
+```bash
+npx wood dev
+
+# In another terminal:
+npx axe targets
+npx axe click '[data-testid="settings-nav"]' --window main
+npx axe screenshot artifacts/settings.png --window main
+```
+
+The currently shipped Axe commands are:
+
+```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>]
+```
+
+Important current boundaries:
+
+- every command reconnects and performs one operation;
+- without `--window`, Axe selects the first discovered page;
+- `defaultRoute` reported by `axe targets` is the window's configured default,
+  not necessarily the currently displayed Wood route;
+- the current `type` command uses Playwright `fill()` semantics;
+- `axe js` is an unrestricted developer debugging escape hatch and does not
+  prove a real UI path.
+
+The planned full-app driver direction adds deterministic target identity,
+current-route introspection, persistent scenarios, semantic locators, explicit
+postconditions, nested and virtual scrolling, structured receipts, and failure
+evidence. See [Axe — Live Wood App Driver](./docs/axe.md) for the current API,
+limitations, and design.
 
 ### Generated client contracts
 
-`wood dev` and `wood build` generate `ui/generated/wood.d.ts` from the
-operation manifest. It exports two project-specific contracts:
+`wood dev` and `wood build` generate `ui/generated/wood.d.ts` from the operation
+manifest. It exports two project-specific contracts:
 
 - `GeneratedApp` matches `@noego/wood/client` `getApp()` and injected `App`
-  instances: controller name -> controller action.
+  instances: controller name → controller action.
 - `GeneratedWoodBridge` matches the raw preload bridge path: operation channel
-  segments -> invoke function.
+  segments → invoke function.
 - `WoodRpcApi` remains as a backward-compatible alias for `GeneratedApp`.
 
 Use `GeneratedApp` when testing renderer services that call the injected client
@@ -211,7 +262,9 @@ Publishing runs the same checks through `prepublishOnly`.
 
 ## Testing
 
-Wood publishes browser-testing helpers from `@noego/wood/testing`.
+### Browser harness
+
+Wood publishes browser-testing helpers from `@noego/wood/testing`:
 
 ```ts
 import { browser } from '@noego/wood/testing';
@@ -227,10 +280,15 @@ const harness = await browser.createHarness({
   },
 });
 
-const mounted = await harness.mountComponent('ui/components/StatusPanel.svelte');
-await mounted.expect.visible('[data-testid="status-panel"]');
+try {
+  const mounted = await harness.mountComponent(
+    'ui/components/StatusPanel.svelte',
+  );
 
-await harness.destroy();
+  await mounted.expect.visible('[data-testid="status-panel"]');
+} finally {
+  await harness.destroy();
+}
 ```
 
 The browser harness starts Vite with the Svelte plugin, launches Playwright,
@@ -238,13 +296,29 @@ installs a controlled Wood bridge fixture, and can mount individual Svelte
 components, layered Wood trees, or Wood routes from a views config.
 
 Use it for renderer behavior that needs real CSS, browser layout, animation
-frames, z-index, clipping, or route/controller wiring without booting Electron.
-Keep pure service and state tests in Node.
+frames, paint order, clipping, hit testing, or route/controller wiring without
+booting Electron. Keep pure service and state tests in Node.
+
+The harness includes geometry and interaction assertions such as visibility,
+viewport containment, clipping, overlap, hit testing, click reachability,
+paint-order front/behind, painted coverage, alignment, spacing, animation
+stability, and screenshots.
+
+See [Browser Testing](./docs/browser-testing.md) for the full API and boundary
+notes.
+
+### Live-app testing
+
+Use Axe when the boundary being tested is the real running Electron app rather
+than an isolated renderer mount. Do not make a broad Axe workflow the only test
+for logic owned by a producer, controller, reducer, service, or persistence
+layer.
+
+See [Axe — Live Wood App Driver](./docs/axe.md).
 
-See [Browser Testing](./docs/browser-testing.md) for the full API shape and
-boundary notes.
+### Trace testing
 
-Wood also publishes trace-testing helpers from `@noego/wood/trace-testing`.
+Wood publishes trace-testing helpers from `@noego/wood/trace-testing`.
 `TraceRecorder` subscribes to the same trace stream as production tracing and
 keeps an in-memory buffer for assertions.
 
@@ -269,7 +343,7 @@ traceRecorder.disable();
 ```
 
 Use trace assertions when the runtime story is part of the contract: branch
-selection, model or route choice, repeated work budgets, emitted payload sizes,
+selection, model or route choice, repeated-work budgets, emitted payload sizes,
 failure/recovery paths, or renderer-to-main ordering. `TraceRecorder` also
 provides `events()` for raw inspection and `waitForTrace(...)` for async browser
 or streaming scenarios.
@@ -281,7 +355,8 @@ Publishing is handled by the `Publish` GitHub Actions workflow.
 Prerequisites:
 
 - Add an npm automation token as the repository secret `NPM_TOKEN`.
-- Bump `package.json` and `package-lock.json` to a version that is not already published.
+- Bump `package.json` and `package-lock.json` to a version that is not already
+  published.
 - Commit the version bump on `main`.
 
 Release flow:
@@ -292,9 +367,10 @@ git push origin main
 git push origin main:release
 ```
 
-The workflow runs when the `release` branch is updated. It runs `prepublishOnly`
-through `npm publish` and publishes the package to npm.
+The workflow runs when the `release` branch is updated. It runs
+`prepublishOnly` through `npm publish` and publishes the package to npm.
 
-## Design Notes
+## Design notes
 
-High-level architecture and config format notes live in [DESIGN.md](./DESIGN.md).
+High-level architecture and config format notes live in
+[DESIGN.md](./DESIGN.md).