@wcstack/state 1.32.0 → 2.0.0

package/README.md

@@ -46,13 +46,13 @@ In every existing framework, the **component** is the coupling point between UI
 |-------|---------------|----------------------|
 | **State** (`<wcs-state>`) | Data structure and business logic | Which DOM nodes are bound |
 | **UI** (`data-wcs`) | Path strings and display intent | How state is stored or computed |
-| **Components** (`@name`) | The path they need from a named state | The other component's internals |
+| **Components** (`state: path`) | The mount table the host writes | The other component's internals |
 
 Three levels of path contracts keep everything loosely coupled:
 
 1. **UI ↔ State** — A `data-wcs="textContent: user.name"` attribute is the entire binding. No hooks, no selectors, no reactive primitives. The component's JavaScript doesn't contain a single line that references state.
 
-2. **Component ↔ Component** — Cross-component communication happens through named state references (`@stateName`). Components never import or depend on each other; they share a naming convention, nothing more.
+2. **Component ↔ Component** — The host mounts a subtree onto each component (`<my-card data-wcs="state: user">`), and volumes graft extra modules onto the tree (`<wcs-state mount="i18n">`). Components never import or depend on each other; every connection is a path prefix on the single tree, nothing more.
 
 3. **Loop context** — Inside a `for` loop, `*` acts as an abstract index. Bindings like `items.*.price` resolve to the current element automatically. The template doesn't know its concrete position — the wildcard is the contract.
 
@@ -222,19 +222,20 @@ Resolution order: `state` → `src` (.json / .js) → `json` → inner `<script>
 
 > **Under a Content-Security-Policy:** form 5 (inline `<script type="module">`) is evaluated through a `blob:` URL and therefore requires `script-src blob:`. A page nonce does not cover it. If you enforce a strict CSP, use form 4 (`src="./state.js"`) instead — it needs no extra directive. See [docs/csp.md](../../docs/csp.md).
 
-### Named State
+### Mounting Additional State (`mount=`)
 
-Multiple state elements can coexist with the `name` attribute. Bindings reference them with `@name`:
+There is **one state tree per root**. To split state across modules, mount a volume: its data grafts onto the root tree at the mount path, and bindings read it by prefix.
 
 ```html
-<wcs-state name="cart">...</wcs-state>
-<wcs-state name="user">...</wcs-state>
+<wcs-state mount="cart" src="./cart.js"></wcs-state>
+<wcs-state src="./app.js"></wcs-state>
 
-<div data-wcs="textContent: total@cart"></div>
-<div data-wcs="textContent: name@user"></div>
+<div data-wcs="textContent: cart.total"></div>
 ```
 
-Default name is `"default"` (no `@` needed).
+A volume may declare getters, `$watch`, `$listKeys`, `$updatedCallback`, and `$connectedCallback`/`$disconnectedCallback` — all relative to its mount path. Load order does not matter (a volume connected before the root is grafted when the root registers). Mount paths must be static (`*`, `$`, `#`, `@` are rejected).
+
+> **Migrating from v1's named states:** `<wcs-state name="cart">` + `total@cart` becomes `<wcs-state mount="cart">` + `cart.total`. In v2 the `name` attribute fails fast and `@` in a path is a parse error, each with this exact guidance. Migration table: [docs/state-mount-design.md](../../docs/state-mount-design.md) §9.
 
 ## Updating State
 
@@ -287,7 +288,7 @@ this.items.sort((a, b) => a.id - b.id);
 ### `data-wcs` Attribute
 
 ```
-property[#modifier]: path[@state][|filter[|filter(args)...]]
+property[#modifier]: path[|filter[|filter(args)...]]
 ```
 
 Multiple bindings separated by `;`:
@@ -301,7 +302,6 @@ Multiple bindings separated by `;`:
 | `property` | DOM property to bind | `value`, `textContent`, `checked` |
 | `#modifier` | Binding modifier | `#ro`, `#prevent`, `#stop`, `#onchange` |
 | `path` | State property path | `count`, `user.name`, `users.*.name` |
-| `@state` | Named state reference | `@cart`, `@user` |
 | `\|filter` | Transform filter chain | `\|gt(0)`, `\|round\|locale` |
 
 ### Property Types
@@ -486,7 +486,7 @@ Runtime reads `customClass.wcBindable.properties + inputs` and expands each name
 
 - Filters on the spread target (`...: target|filter`) are rejected.
 - The right-hand path may contain `*` anywhere (e.g. `...: stores.*.fetch`).
-- `@stateName` propagates to every expanded entry (`...: fetchX@store`).
+- The right-hand side is a plain tree path (`...: fetchX` or `...: stores.*.fetch`).
 - If the custom element class is not yet registered, expansion is deferred until `customElements.whenDefined(tag)` resolves — autoloader-style late registration is supported.
 - Elements **without** a `wcBindable` declaration are rejected (write bindings explicitly). Spread requires the contract to know what to expand.
 
@@ -555,7 +555,6 @@ Inside a `for` loop, paths starting with `.` are expanded relative to the loop's
 | `.name` | `users.*.name` | Property of the current element |
 | `.` | `users.*` | The current element itself |
 | `.name\|uc` | `users.*.name\|uc` | Filters are preserved |
-| `.name@state` | `users.*.name@state` | State name is preserved |
 
 For primitive arrays, `.` refers to the element value directly:
 
@@ -1203,7 +1202,7 @@ customElements.define("my-component", MyComponent);
 
 ### Component Definition (Light DOM)
 
-Light DOM components do not use Shadow DOM. The state namespace is shared with the parent scope (just like CSS), so a `name` attribute is required.
+Light DOM components do not use Shadow DOM. In v2 the form is identical to the Shadow form — the component's bindings are translated onto the host's tree at its mount point, so **no name and no `@` selectors are needed**, and the same component can sit on every row of a list:
 
 ```javascript
 class MyLightComponent extends HTMLElement {
@@ -1211,30 +1210,20 @@ class MyLightComponent extends HTMLElement {
 
   connectedCallback() {
     this.innerHTML = `
-      <wcs-state bind-component="state" name="my-light"></wcs-state>
-      <div data-wcs="text: message@my-light"></div>
-      <input type="text" data-wcs="value: message@my-light" />
+      <wcs-state bind-component="state"></wcs-state>
+      <div data-wcs="text: message"></div>
+      <input type="text" data-wcs="value: message" />
     `;
   }
 }
 customElements.define("my-light-component", MyLightComponent);
 ```
 
-- `name` attribute is **required** for Light DOM components (namespace is shared with the parent scope)
-- Bindings must explicitly reference the state name with `@my-light`
 - `<wcs-state>` must be a direct child of the component element
+- The host **must wire it** (`<my-light-component data-wcs="state.message: user.name">` or `state: user`) — a plain, unwired Light DOM `bind-component` cannot exist in v2 (an independent tree cannot share the parent's root). It fails loudly with the migration guidance: attach a shadow root, or mount it from the host.
 
-- Binding from the host (`<my-light-component data-wcs="state.message: user.name">`) works just as it
-  does for Shadow DOM. The component's subtree is treated as an **independent binding scope** and is
-  wired once the component's own state has registered its name
-
-> **Note**: Light DOM shares its namespace with the parent scope, so **two instances carrying the same
-> `name` cannot live in one scope**. Use Shadow DOM for shapes that place a component on every row of
-> a list.
->
-> Also, `State.getBindingsReady(root)` does not cover the component's scope — the same as the Shadow
-> DOM form, where the child lives in a different rootNode. Await the component's own `<wcs-state>`
-> initialization when you need to wait for its contents to render.
+> **Note**: `State.getBindingsReady(root)` covers mounted scopes once the mount record resolves; await
+> the component's own `<wcs-state>` initialization when you need its contents rendered.
 
 ### Host Usage
 
@@ -1255,6 +1244,54 @@ customElements.define("my-light-component", MyLightComponent);
 - `data-wcs="state.message: user.name"` on the host element binds outer state paths to inner component state properties
 - Changes propagate bidirectionally between the component and the outer state
 
+### Whole-object Mount (`state: path`)
+
+Instead of wiring the component's state property by property, the host can mount a **whole subtree** of its state as the component's root. Inside the component every path is then relative to the mount point:
+
+```html
+<!-- Host -->
+<wcs-state json='{"user":{"name":"Alice","email":"alice@example.com"},"theme":{"mode":"light"}}'></wcs-state>
+<user-card data-wcs="state: user"></user-card>
+```
+
+```javascript
+// Component (Shadow DOM)
+class UserCard extends HTMLElement {
+  state = {
+    // a getter computed over the mount — `this.name` is the tree's `user.name`
+    get display() { return `${this.name} <${this.email}>`; },
+  };
+  constructor() {
+    super();
+    this.attachShadow({ mode: "open" });
+  }
+  connectedCallback() {
+    this.shadowRoot.innerHTML = `
+      <wcs-state bind-component="state"></wcs-state>
+      <span data-wcs="textContent: name"></span>
+      <span data-wcs="textContent: display"></span>
+      <input data-wcs="value: name">
+    `;
+  }
+}
+customElements.define("user-card", UserCard);
+```
+
+- `state: user` mounts the component's root at the tree path `user`: `name` inside the component **is** `user.name`. Reads, writes (`value: name`, `this.state.name = ...`), getters and `for:` all resolve against the tree; the host's `this.user = {...}` replacement and `this["user.name"] = ...` writes both reach the component.
+- A partial mount can sit next to it: `state: user; state.theme: theme` mounts `theme` as a second entry point (longest prefix wins, so `theme.mode` inside the component reads the tree's `theme.mode`).
+- In a loop, mount **the row itself**: `<template data-wcs="for: users"><user-row data-wcs="state: ."></user-row></template>`. Inside the row component `name` is `users.*.name`, and its own `for: tags` runs over `users.*.tags.*`.
+- **Own keys are private** (rule R1 in [docs/state-mount-design.md](../../docs/state-mount-design.md) §4-3): a data key the component declares itself (`state = { mode: "view" }`) belongs to that element and is never written to the tree. If it hides a key that exists at the mount point (`state = { name: "" }` mounted over `user.name`), the runtime warns once (`wcs/mount-own-key-shadow`) — remove the default to read the tree, or rename it to keep it private.
+- Mounting an array as the root (`state: rows` with `for` over it inside) is not supported; mount the row (`state: .`) or the object that holds the array (`state: group` with `for: children` inside). Both forms are contract-tested; mounts are the only way to extend the tree.
+
+> The per-property form (`state.message: user.name`) keeps working — it is a partial mount on
+> the same machinery. R1 is strict for every mount form — a component that declares a default
+> for a mapped key (`state = { message: "" }` together with `state.message: ...`) keeps its
+> own key **private**, hiding the host value (a one-time `wcs/mount-own-key-shadow` warning
+> points at it). Drop the default to read the tree. The mounted `<wcs-state>` needs no `name`
+> in Light DOM, and `$getAll` / `$setAll` / `$resolve` / `$postUpdate` on `element.state`
+> (and on `this` inside getters/methods) speak the component's own vocabulary — paths are
+> translated onto the mount and the host row's indexes are prepended automatically.
+
 ### Standalone Web Component Injection (`__e2e__/single-component`)
 
 Even when a component is independent from outer host state, you can inject reactive state with `bind-component`.
@@ -1293,8 +1330,7 @@ customElements.define("my-component", MyComponent);
 
 - `<wcs-state>` with `bind-component` must be a **direct child** of the component element (top-level)
 - The parent element must be a **custom element** (tag name containing a hyphen)
-- Light DOM components **require** a `name` attribute to avoid namespace conflicts with the parent scope
-- Light DOM bindings must reference the state name explicitly (e.g., `@my-light`)
+- Light DOM components must be wired from the host (the plain, unwired form was removed in v2)
 
 ### Loop with Components
 
@@ -1302,6 +1338,11 @@ customElements.define("my-component", MyComponent);
 <template data-wcs="for: users">
   <my-component data-wcs="state.message: .name"></my-component>
 </template>
+
+<!-- or mount the row itself: inside the component, `name` is `users.*.name` -->
+<template data-wcs="for: users">
+  <user-row data-wcs="state: ."></user-row>
+</template>
 ```
 
 ### Rendering a List Inside the Component
@@ -1821,13 +1862,13 @@ Firing order is defined in three layers, and only the middle one is yours to ste
 
 Key rules:
 
-- **Only its own state** — a path may not carry `@stateName`; watching another state element is rejected at declaration time.
+- **Paths of the tree only** — a path may not contain `@` (the v1 name selector); such a declaration is rejected loudly.
 - **Intermediate values are not observable** — a batch that goes `a → b → c` fires once with `cur = c`, `prev = a`, the same contract as binding updates.
 - **Row-level diffs want `$listKeys`** — without it, assigning a whole array fires the row watch for *every* row with `prev === undefined`, because no row went through a path write. With `$listKeys` declared, the key match decomposes the assignment into per-field writes, so only changed rows fire and `prev` is a real scalar.
 - **A headless row watch requires `$listKeys`** — this is the one place `$watch` is *not* headless on its own. Expanding `items` into `items.*.price` is driven by the list's `for` binding, and declaring a watch deliberately does not register the path as a list. So with neither a `for` binding nor `$listKeys`, assigning the array fires the row watch **zero** times. Add `$listKeys` (the key match writes each field by path, bypassing the expansion) or render the list. Scalar paths — including nested ones like `user.name` — are headless with no such condition.
 - **Handler exceptions are isolated** — a throw is reported to the console and the remaining watches (and stream restarts) still run. This differs from `$connectedCallback` / `$updatedCallback`, which fail loudly.
 - **Write chains are bounded** — a handler's writes form a new batch, so mutually-writing watches would loop forever; the chain is cut off after 32 links with a console error. Values and DOM are not rolled back.
-- **Not available on a mapped `bind-component` child** — its state is wrapped in a proxy that blanks out every `$`-prefixed property, so the declaration never arrives. This applies to `$streams` too. A plain (unmapped) child can declare it.
+- **Not run on a mounted `bind-component` scope** — mounted components do not execute declaration surfaces: the `$watch` declaration is ignored with a one-time console warning that points to the root state (or a volume — `<wcs-state mount>` hosts `$watch` / `$listKeys` / `$updatedCallback`). This applies to `$streams` too. A plain (unwired Shadow) child owns an independent tree and can declare it.
 - **SSR does not run watches** — handler side effects would otherwise execute on both server and client.
 
 ## Inputs and Attribute Mirror
@@ -2128,7 +2169,7 @@ The check **under-approximates**: it stays silent for anything it cannot decide
 - A `null` / `undefined` parent (the "seed as `null`, assign later" shape)
 - Row fields of a list that starts empty (the row shape is unknown)
 - Sub-properties of an intermediate getter's return value
-- Mapped `bind-component` child scopes (the parent owns the path)
+- Marker paths of mounted components (`#m…` — private keys and getters live on the mount overlay, not the raw state)
 - Reserved `$` namespaces (`$command.*` and friends)
 
 So **no warning is not a proof of correctness.** For exhaustive checking, run `npx @wcstack/lint <file>`.
@@ -2246,6 +2287,122 @@ the short answer is that translations belong on a path, not in a filter.
 > `analyzeContract()` API reports drift between a live `static wcBindable` surface and
 > a sidecar manifest for dev-time diagnostics.
 
+## Testing Your Page
+
+A page built on `<wcs-state>` is plain DOM, so it can be tested headlessly with [happy-dom](https://github.com/capricorn86/happy-dom) — no browser, no build step, no test-only API. Three recipes follow; every one of them runs as written (recipe 1 is pinned by [`__tests__/readme.testingRecipe.test.ts`](__tests__/readme.testingRecipe.test.ts), which executes the same lines).
+
+Want it as one import? [`@wcstack/testing`](../testing/README.md) packages recipe 1 as `mount()` / `settle()` / `fire()` (and waits for `<wcs-router>` too). The bare recipes below stay valid without it.
+
+### 1. vitest + happy-dom
+
+`vitest.config.ts`:
+
+```ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { environment: "happy-dom", setupFiles: ["./tests/setup.ts"] },
+});
+```
+
+`tests/setup.ts` — register the elements once, and route inline `<script type="module">` state through the `data:` URL loader (Node cannot import `blob:` URLs; without this line an inline-script state never finishes loading):
+
+```ts
+import { bootstrapState } from "@wcstack/state";
+
+bootstrapState();
+URL.createObjectURL = undefined as any;
+```
+
+A test:
+
+```ts
+import { expect, it } from "vitest";
+import { getBindingsReady } from "@wcstack/state";
+
+const settle = () => new Promise<void>((r) => setTimeout(r, 0));
+
+it("renders, re-renders, and runs handlers", async () => {
+  // 1. Mount the fragment under test
+  document.body.innerHTML = `
+    <wcs-state json='{"count": 1, "items": ["apple", "banana"]}'></wcs-state>
+    <p id="count" data-wcs="textContent: count"></p>
+    <ul id="items">
+      <template data-wcs="for: items">
+        <li data-wcs="textContent: items.*"></li>
+      </template>
+    </ul>
+  `;
+
+  // 2. Wait for the state element, then for every binding under `document`
+  const stateEl = document.querySelector("wcs-state") as any;
+  await stateEl.connectedCallbackPromise;
+  await getBindingsReady(document);
+
+  // 3. Assert the initial render
+  expect(document.querySelector("#count")!.textContent).toBe("1");
+  expect(document.querySelectorAll("#items li").length).toBe(2);
+
+  // 4. Write through a writable proxy — exactly what a handler does
+  await stateEl.createStateAsync("writable", async (state: any) => {
+    state.count = 42;
+    state.items = [...state.items, "cherry"];
+  });
+  await settle();
+
+  // 5. Assert the re-render
+  expect(document.querySelector("#count")!.textContent).toBe("42");
+  expect(document.querySelectorAll("#items li").length).toBe(3);
+});
+```
+
+To drive the page the way a user does, keep the state inline (methods included) and dispatch DOM events; a `data-wcs="onclick: up"` handler runs on `button.click()`, and the DOM reflects the write after one `settle()`.
+
+- `getBindingsReady(root)` resolves once every binding under `root` (a `document` or a shadow root) is built, and rejects if binding initialization fails (v1.26+).
+- Updates settle on the microtask queue; a single `setTimeout(0)` after a write is enough.
+- `state.items = [...state.items, "cherry"]` is the reactive form — `state.items.push()` is not observed (same rule as in handlers).
+- Under happy-dom, `customElements.define` upgrades existing nodes by **replacing** them; "a value reaches the same node after a late define" cannot be asserted headlessly. Event timing differences between happy-dom and real browsers are the other blind spot — keep one browser e2e (Playwright) for those.
+- happy-dom's `textContent` setter turns a numeric `0` into an empty string (browsers render `"0"`), so a `textContent: count` binding reads `""` at zero in this recipe. Assert on the state value, or use `@wcstack/testing`, whose `mount()` shims the setter.
+
+### 2. Bare Node (no vitest)
+
+`@wcstack/server` already exports the globals swap it uses for SSR; reuse it. **Import `@wcstack/state` dynamically after `installGlobals`** — the element classes pick their base class when the module is evaluated, so a static import at the top of the file registers elements that happy-dom cannot construct:
+
+```js
+import { Window } from "happy-dom";
+import { installGlobals } from "@wcstack/server";
+
+const window = new Window({ url: "http://localhost/" });
+const restore = installGlobals(window);   // document, customElements, HTMLElement, ... (GLOBALS_KEYS)
+try {
+  const { bootstrapState, getBindingsReady } = await import("@wcstack/state");
+  bootstrapState();
+  // ... the same mount / await / assert steps as recipe 1
+} finally {
+  restore();
+  await window.happyDOM.close();
+}
+```
+
+`installGlobals` also disables `URL.createObjectURL` for you, so inline-script state loads the same way as in recipe 1.
+
+### 3. Snapshot the rendered HTML
+
+[`renderToString()`](../server/README.md) from `@wcstack/server` returns the fully rendered markup as a string; compare it against a stored snapshot:
+
+```ts
+import { expect, it } from "vitest";
+import { renderToString } from "@wcstack/server";
+
+it("matches the rendered snapshot", async () => {
+  const html = await renderToString(`
+    <wcs-state json='{"items": ["apple", "banana"]}' enable-ssr></wcs-state>
+    <ul><template data-wcs="for: items"><li data-wcs="textContent: items.*"></li></template></ul>
+  `);
+  expect(html).toMatchSnapshot();
+});
+```
+
 ## TypeScript Support
 
 `defineState()` wraps your state object and provides type-safe `this` inside methods and getters — with zero runtime cost (identity function).
@@ -2286,7 +2443,7 @@ bootstrapState();
 
 | Attribute | Description |
 |---|---|
-| `name` | State name (default: `"default"`) |
+| `mount` | Static tree path to graft this state onto the root tree as a **volume** (v2 — replaces the removed `name` attribute; one state tree per root) |
 | `state` | ID of a `<script type="application/json">` element |
 | `src` | URL to `.json` or `.js` file |
 | `json` | Inline JSON string |
@@ -2296,7 +2453,6 @@ bootstrapState();
 
 | Property / Method | Description |
 |---|---|
-| `name` | State name |
 | `initializePromise` | Resolves when state is fully initialized |
 | `listPaths` | Set of paths used in `for` loops |
 | `getterPaths` | Set of paths defined as getters |