@wcstack/state 1.7.1 → 1.8.4

package/README.md

@@ -1,1350 +1,1350 @@
-# @wcstack/state
-
-**What if HTML had reactive data binding?**
-
-Imagine a future where the browser natively understands state — you declare data inline, bind it to the DOM with attributes, and everything stays in sync. No virtual DOM, no compilation, no framework. Just HTML that reacts.
-
-That's what `<wcs-state>` and `data-wcs` explore. One CDN import, zero dependencies, pure HTML syntax.
-
-The CDN script only registers the custom element definition — nothing else happens at load time. When a `<wcs-state>` element connects to the DOM, it reads its state source, scans all `data-wcs` bindings within the same root node (`document` or `ShadowRoot`), and wires up reactivity. All initialization is driven by the element's lifecycle, not by your code.
-
-## Design Philosophy
-
-### Path as the Universal Contract
-
-In every existing framework, the **component** is the coupling point between UI and state. Components import state hooks, selectors, or reactive primitives, and the binding happens inside JavaScript. No matter how cleanly you separate your state store, there is always glue code in the component that pulls state in.
-
-`@wcstack/state` eliminates that coupling entirely. The **only** thing connecting UI and state is a **path string** — a dot-separated address like `user.name` or `cart.items.*.subtotal`. This is the sole contract between the two layers:
-
-| Layer | What it knows | What it doesn't know |
-|-------|---------------|----------------------|
-| **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 |
-
-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.
-
-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.
-
-### Why This Matters
-
-This is complete separation of UI and state with **no JavaScript intermediary**. You can:
-
-- Redesign the entire UI without touching state logic
-- Refactor state structure and only update path strings
-- Read the HTML alone and understand every data dependency
-
-The path contract works like a URL in a REST API — a simple string that both sides agree on, with no shared code between them. It's the natural result of building on HTML's declarative nature rather than inventing a template language on top of JavaScript.
-
-## 4 Steps to Reactive HTML
-
-```html
-<!-- 1. Load the CDN -->
-<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
-
-<!-- 2. Write a <wcs-state> tag -->
-<wcs-state>
-  <!-- 3. Define your state object -->
-  <script type="module">
-    export default {
-      message: "Hello, World!"
-    };
-  </script>
-</wcs-state>
-
-<!-- 4. Bind with data-wcs attributes -->
-<div data-wcs="textContent: message"></div>
-```
-
-That's it. No build, no bootstrap code, no framework.
-
-## Features
-
-- **Declarative data binding** — `data-wcs` attribute for property / text / event / structural binding
-- **Reactive Proxy** — ES Proxy-based automatic DOM updates with dependency tracking
-- **Structural directives** — `for`, `if` / `elseif` / `else` via `<template>` elements
-- **Built-in filters** — 40 filters for formatting, comparison, arithmetic, date, and more
-- **Two-way binding** — automatic for `<input>`, `<select>`, `<textarea>`
-- **Web Component binding** — bidirectional state binding with Shadow DOM components
-- **Path getters** — dot-path key getters (`get "users.*.fullName"()`) for virtual properties at any depth in a data tree, all defined flat in one place with automatic dependency tracking and caching
-- **Mustache syntax** — `{{ path|filter }}` in text nodes
-- **Multiple state sources** — JSON, JS module, inline script, API, attribute
-- **SVG support** — full binding support inside `<svg>` elements
-- **Lifecycle hooks** — `$connectedCallback` / `$disconnectedCallback` / `$updatedCallback`, plus `$stateReadyCallback` for Web Components
-- **TypeScript support** — `defineState()` for typed state definitions with dot-path autocompletion ([details](docs/define-state.md))
-- **Server-Side Rendering** — `enable-ssr` attribute + `@wcstack/server` for full SSR with automatic hydration
-- **Zero dependencies** — no runtime dependencies
-
-## Installation
-
-### CDN (recommended)
-
-```html
-<!-- Auto-initialization — this is all you need -->
-<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
-```
-
-### CDN (manual initialization)
-
-```html
-<script type="module">
-  import { bootstrapState } from 'https://esm.run/@wcstack/state';
-  bootstrapState();
-</script>
-```
-
-## Basic Usage
-
-```html
-<wcs-state>
-  <script type="module">
-    export default {
-      count: 0,
-      user: { id: 1, name: "Alice" },
-      users: [
-        { id: 1, name: "Alice" },
-        { id: 2, name: "Bob" },
-        { id: 3, name: "Charlie" }
-      ],
-      countUp() { this.count += 1; },
-      clearCount() { this.count = 0; },
-      get "users.*.displayName"() {
-        return this["users.*.name"] + " (ID: " + this["users.*.id"] + ")";
-      }
-    };
-  </script>
-</wcs-state>
-
-<!-- Text binding -->
-<div data-wcs="textContent: count"></div>
-{{ count }}
-
-<!-- Two-way input binding -->
-<input type="text" data-wcs="value: user.name">
-
-<!-- Event binding -->
-<button data-wcs="onclick: countUp">Increment</button>
-
-<!-- Conditional class -->
-<div data-wcs="textContent: count; class.over: count|gt(10)"></div>
-
-<!-- Loop -->
-<template data-wcs="for: users">
-  <div>
-    <span data-wcs="textContent: .id"></span>:
-    <span data-wcs="textContent: .displayName"></span>
-  </div>
-</template>
-
-<!-- Conditional rendering -->
-<template data-wcs="if: count|gt(0)">
-  <p>The count is positive.</p>
-</template>
-<template data-wcs="elseif: count|lt(0)">
-  <p>The count is negative.</p>
-</template>
-<template data-wcs="else:">
-  <p>The count is zero.</p>
-</template>
-```
-
-## State Initialization
-
-`<wcs-state>` supports multiple ways to load initial state:
-
-```html
-<!-- 1. Reference a <script type="application/json"> by id -->
-<script type="application/json" id="state">
-  { "count": 0 }
-</script>
-<wcs-state state="state"></wcs-state>
-
-<!-- 2. Inline JSON attribute -->
-<wcs-state json='{ "count": 0 }'></wcs-state>
-
-<!-- 3. External JSON file -->
-<wcs-state src="./data.json"></wcs-state>
-
-<!-- 4. External JS module (export default { ... }) -->
-<wcs-state src="./state.js"></wcs-state>
-
-<!-- 5. Inline script module -->
-<wcs-state>
-  <script type="module">
-    export default { count: 0 };
-  </script>
-</wcs-state>
-
-<!-- 6. Programmatic API -->
-<script>
-  const el = document.createElement('wcs-state');
-  el.setInitialState({ count: 0 });
-  document.body.appendChild(el);
-</script>
-```
-
-Resolution order: `state` → `src` (.json / .js) → `json` → inner `<script>` → wait for `setInitialState()`.
-
-### Named State
-
-Multiple state elements can coexist with the `name` attribute. Bindings reference them with `@name`:
-
-```html
-<wcs-state name="cart">...</wcs-state>
-<wcs-state name="user">...</wcs-state>
-
-<div data-wcs="textContent: total@cart"></div>
-<div data-wcs="textContent: name@user"></div>
-```
-
-Default name is `"default"` (no `@` needed).
-
-## Updating State
-
-In `@wcstack/state`, every piece of state has a **path** — like `count`, `user.name`, or `items`. To update state reactively, **assign to the path**:
-
-```javascript
-this.count = 10;               // path "count"
-this["user.name"] = "Bob";     // path "user.name"
-```
-
-That's the one rule: **assign to the path, and the DOM updates automatically.**
-
-### Why `this.user.name = "Bob"` Doesn't Work
-
-`this.user.name` first reads the `user` object via `this.user` (a path read), then sets `.name` on that plain object — this is not a path assignment, so the change is not detected:
-
-```javascript
-// ✅ Path assignment — change detected
-this["user.name"] = "Bob";
-
-// ❌ Not a path assignment — change NOT detected
-this.user.name = "Bob";
-```
-
-### Arrays
-
-The same rule applies: assign a new array to the path. Mutating methods (`push`, `splice`, `sort`, ...) modify the array in place without path assignment, so use non-destructive alternatives:
-
-```javascript
-// ✅ New array assigned to path — change detected
-this.items = this.items.concat({ id: 4, text: "New" });
-this.items = this.items.toSpliced(index, 1);
-this.items = this.items.filter(item => !item.done);
-this.items = this.items.toSorted((a, b) => a.id - b.id);
-this.items = this.items.toReversed();
-this.items = this.items.with(index, newValue);
-
-// ❌ In-place mutation — no path assignment, change NOT detected
-this.items.push({ id: 4, text: "New" });
-this.items.splice(index, 1);
-this.items.sort((a, b) => a.id - b.id);
-```
-
-## Binding Syntax
-
-### `data-wcs` Attribute
-
-```
-property[#modifier]: path[@state][|filter[|filter(args)...]]
-```
-
-Multiple bindings separated by `;`:
-
-```html
-<div data-wcs="textContent: count; class.over: count|gt(10)"></div>
-```
-
-| Part | Description | Example |
-|---|---|---|
-| `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
-
-| Property | Description |
-|---|---|
-| `value` | Element value (two-way for inputs) |
-| `checked` | Checkbox / radio checked state (two-way) |
-| `textContent` | Text content |
-| `text` | Alias for textContent |
-| `html` | innerHTML |
-| `class.NAME` | Toggle a CSS class |
-| `style.PROP` | Set a CSS style property |
-| `attr.NAME` | Set an attribute (supports SVG namespace) |
-| `radio` | Radio button group binding (two-way) |
-| `checkbox` | Checkbox group binding to array (two-way) |
-| `onclick`, `on*` | Event handler binding |
-
-### Modifiers
-
-| Modifier | Description |
-|---|---|
-| `#ro` | Read-only — disables two-way binding |
-| `#prevent` | Calls `event.preventDefault()` on event handlers |
-| `#stop` | Calls `event.stopPropagation()` on event handlers |
-| `#onchange` | Uses `change` event instead of `input` for two-way binding |
-
-### Two-Way Binding
-
-Automatically enabled for:
-
-| Element | Property | Event |
-|---|---|---|
-| `<input type="checkbox/radio">` | `checked` | `input` |
-| `<input>` (other types) | `value`, `valueAsNumber`, `valueAsDate` | `input` |
-| `<select>` | `value` | `change` |
-| `<textarea>` | `value` | `input` |
-
-`<input type="button">` is excluded. Use `#ro` to disable, `#onchange` to change the event.
-
-### Radio Binding
-
-Bind a radio button group to a single state value with `radio`:
-
-```html
-<input type="radio" value="red" data-wcs="radio: selectedColor">
-<input type="radio" value="blue" data-wcs="radio: selectedColor">
-```
-
-The radio button whose `value` matches the state value is automatically checked. When the user selects a different radio button, the state is updated. Use `#ro` for read-only.
-
-Inside a `for` loop:
-
-```html
-<template data-wcs="for: branches">
-  <label>
-    <input type="radio" data-wcs="value: .; radio: currentBranch">
-    {{ . }}
-  </label>
-</template>
-```
-
-### Checkbox Binding
-
-Bind a checkbox group to a state array with `checkbox`:
-
-```html
-<input type="checkbox" value="apple" data-wcs="checkbox: selectedFruits">
-<input type="checkbox" value="banana" data-wcs="checkbox: selectedFruits">
-<input type="checkbox" value="orange" data-wcs="checkbox: selectedFruits">
-```
-
-A checkbox is checked when its `value` is included in the state array. Toggling a checkbox adds or removes the value from the array. Use `|int` to convert string values to numbers, and `#ro` for read-only.
-
-### Mustache Syntax
-
-When `enableMustache` is `true` (default), `{{ expression }}` in text nodes is supported:
-
-```html
-<p>Hello, {{ user.name }}!</p>
-<p>Count: {{ count|locale }}</p>
-```
-
-Internally converted to comment-based bindings (`<!--@@:expression-->`).
-
-## Structural Directives
-
-Structural directives use `<template>` elements:
-
-### Loop (`for`)
-
-```html
-<template data-wcs="for: users">
-  <div>
-    <!-- Full path -->
-    <span data-wcs="textContent: users.*.name"></span>
-    <!-- Shorthand (relative to loop context) -->
-    <span data-wcs="textContent: .name"></span>
-  </div>
-</template>
-```
-
-The `for:` directive uses a **value-based diff algorithm** — each array element's value itself serves as the identity key. There is no need for an explicit `key` attribute (like React's `key` or Vue's `:key`). When the array is reassigned, the differ matches old and new elements by value, reusing existing DOM nodes for unchanged items and efficiently adding, removing, or reordering the rest.
-
-#### Dot Shorthand
-
-Inside a `for` loop, paths starting with `.` are expanded relative to the loop's array path:
-
-| Shorthand | Expanded to | Description |
-|---|---|---|
-| `.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:
-
-```html
-<template data-wcs="for: branches">
-  <label>
-    <input type="radio" data-wcs="value: .; radio: currentBranch">
-    {{ . }}
-  </label>
-</template>
-```
-
-Nested loops are supported with multi-level wildcards. The `.` shorthand in nested `for` directives also expands relative to the parent loop path:
-
-```html
-<template data-wcs="for: regions">
-  <!-- .states → regions.*.states -->
-  <template data-wcs="for: .states">
-    <!-- .name → regions.*.states.*.name -->
-    <span data-wcs="textContent: .name"></span>
-  </template>
-</template>
-```
-
-### Conditional (`if` / `elseif` / `else`)
-
-```html
-<template data-wcs="if: count|gt(0)">
-  <p>Positive</p>
-</template>
-<template data-wcs="elseif: count|lt(0)">
-  <p>Negative</p>
-</template>
-<template data-wcs="else:">
-  <p>Zero</p>
-</template>
-```
-
-Conditions can be chained. `elseif` automatically inverts the previous condition.
-
-## Path Getters (Computed Properties)
-
-**Path getters** are the core feature of `@wcstack/state`. Define computed properties using JavaScript getters with **dot-path string keys** containing wildcards (`*`). They act as **virtual properties that can be attached at any depth in a data tree — all defined flat in one place**. No matter how deeply data is nested, path getters keep definitions at the same level with automatic dependency tracking per loop element.
-
-### Basic Path Getter
-
-```html
-<wcs-state>
-  <script type="module">
-    export default {
-      users: [
-        { id: 1, firstName: "Alice", lastName: "Smith" },
-        { id: 2, firstName: "Bob", lastName: "Jones" }
-      ],
-      // Path getter — runs per-element inside a loop
-      get "users.*.fullName"() {
-        return this["users.*.firstName"] + " " + this["users.*.lastName"];
-      },
-      get "users.*.displayName"() {
-        return this["users.*.fullName"] + " (ID: " + this["users.*.id"] + ")";
-      }
-    };
-  </script>
-</wcs-state>
-
-<template data-wcs="for: users">
-  <div data-wcs="textContent: .displayName"></div>
-</template>
-<!-- Output:
-  Alice Smith (ID: 1)
-  Bob Jones (ID: 2)
--->
-```
-
-Inside a path getter, `this["users.*.firstName"]` automatically resolves to the current loop element — no manual indexing needed.
-
-### Top-Level Computed Properties
-
-Getters without wildcards work as standard computed properties:
-
-```javascript
-export default {
-  price: 100,
-  tax: 0.1,
-  get total() {
-    return this.price * (1 + this.tax);
-  }
-};
-```
-
-### Getter Chaining
-
-Path getters can reference other path getters, forming a dependency chain. The cache is automatically invalidated when any upstream value changes:
-
-```html
-<wcs-state>
-  <script type="module">
-    export default {
-      taxRate: 0.1,
-      cart: {
-        items: [
-          { productId: "P001", quantity: 2, unitPrice: 500 },
-          { productId: "P002", quantity: 1, unitPrice: 1200 }
-        ]
-      },
-      // Per-item subtotal
-      get "cart.items.*.subtotal"() {
-        return this["cart.items.*.unitPrice"] * this["cart.items.*.quantity"];
-      },
-      // Aggregate: sum of all subtotals
-      get "cart.totalPrice"() {
-        return this.$getAll("cart.items.*.subtotal", []).reduce((sum, v) => sum + v, 0);
-      },
-      // Chained: tax derived from totalPrice
-      get "cart.tax"() {
-        return this["cart.totalPrice"] * this.taxRate;
-      },
-      // Chained: grand total
-      get "cart.grandTotal"() {
-        return this["cart.totalPrice"] + this["cart.tax"];
-      }
-    };
-  </script>
-</wcs-state>
-
-<template data-wcs="for: cart.items">
-  <div>
-    <span data-wcs="textContent: .productId"></span>:
-    <span data-wcs="textContent: .subtotal|locale"></span>
-  </div>
-</template>
-<p>Total: <span data-wcs="textContent: cart.totalPrice|locale"></span></p>
-<p>Tax: <span data-wcs="textContent: cart.tax|locale"></span></p>
-<p>Grand Total: <span data-wcs="textContent: cart.grandTotal|locale"></span></p>
-```
-
-Dependency chain: `cart.grandTotal` → `cart.tax` → `cart.totalPrice` → `cart.items.*.subtotal` → `cart.items.*.unitPrice` / `cart.items.*.quantity`. Changing any item's `unitPrice` or `quantity` automatically recomputes the entire chain.
-
-### Nested Wildcard Getters
-
-Multiple wildcards are supported for nested array structures:
-
-```html
-<wcs-state>
-  <script type="module">
-    export default {
-      categories: [
-        {
-          name: "Fruits",
-          items: [
-            { name: "Apple", price: 150 },
-            { name: "Banana", price: 100 }
-          ]
-        },
-        {
-          name: "Vegetables",
-          items: [
-            { name: "Carrot", price: 80 }
-          ]
-        }
-      ],
-      get "categories.*.items.*.label"() {
-        return this["categories.*.name"] + " / " + this["categories.*.items.*.name"];
-      }
-    };
-  </script>
-</wcs-state>
-
-<template data-wcs="for: categories">
-  <h3 data-wcs="textContent: .name"></h3>
-  <template data-wcs="for: .items">
-    <div data-wcs="textContent: .label"></div>
-  </template>
-</template>
-<!-- Output:
-  Fruits
-    Fruits / Apple
-    Fruits / Banana
-  Vegetables
-    Vegetables / Carrot
--->
-```
-
-### Flat Virtual Properties Across Any Depth
-
-A key advantage of path getters is that **no matter how deeply data is nested, all virtual properties are defined flat in one place**. This eliminates the need to split components just to hold computed properties at each nesting level.
-
-```javascript
-export default {
-  regions: [
-    { name: "Kanto", prefectures: [
-      { name: "Tokyo", cities: [
-        { name: "Shibuya", population: 230000, area: 15.11 },
-        { name: "Shinjuku", population: 346000, area: 18.22 }
-      ]},
-      { name: "Kanagawa", cities: [
-        { name: "Yokohama", population: 3750000, area: 437.56 }
-      ]}
-    ]}
-  ],
-
-  // --- All flat, regardless of nesting depth ---
-
-  // City level — virtual properties
-  get "regions.*.prefectures.*.cities.*.density"() {
-    return this["regions.*.prefectures.*.cities.*.population"]
-         / this["regions.*.prefectures.*.cities.*.area"];
-  },
-  get "regions.*.prefectures.*.cities.*.label"() {
-    return this["regions.*.prefectures.*.name"] + " "
-         + this["regions.*.prefectures.*.cities.*.name"];
-  },
-
-  // Prefecture level — aggregate from cities
-  get "regions.*.prefectures.*.totalPopulation"() {
-    return this.$getAll("regions.*.prefectures.*.cities.*.population", [])
-      .reduce((a, b) => a + b, 0);
-  },
-
-  // Region level — aggregate from prefectures
-  get "regions.*.totalPopulation"() {
-    return this.$getAll("regions.*.prefectures.*.totalPopulation", [])
-      .reduce((a, b) => a + b, 0);
-  },
-
-  // Top level — aggregate from regions
-  get totalPopulation() {
-    return this.$getAll("regions.*.totalPopulation", [])
-      .reduce((a, b) => a + b, 0);
-  }
-};
-```
-
-Three levels of nesting, five virtual properties — all defined side by side in a single flat object. Each level can reference values from any depth, and aggregation flows naturally from bottom to top via `$getAll`. In component-based frameworks, the typical approach is to create a separate component for each nesting level and pass computed values through the tree. Path getters offer a different trade-off by keeping all definitions in one place.
-
-### Accessing Sub-Properties of Getter Results
-
-When a path getter returns an object, you can access its sub-properties via dot-path:
-
-```javascript
-export default {
-  products: [
-    { id: "P001", name: "Widget", price: 500, stock: 10 },
-    { id: "P002", name: "Gadget", price: 1200, stock: 3 }
-  ],
-  cart: {
-    items: [
-      { productId: "P001", quantity: 2 },
-      { productId: "P002", quantity: 1 }
-    ]
-  },
-  get productByProductId() {
-    return new Map(this.products.map(p => [p.id, p]));
-  },
-  // Returns the full product object
-  get "cart.items.*.product"() {
-    return this.productByProductId.get(this["cart.items.*.productId"]);
-  },
-  // Access sub-property of the returned object
-  get "cart.items.*.total"() {
-    return this["cart.items.*.product.price"] * this["cart.items.*.quantity"];
-  }
-};
-```
-
-`this["cart.items.*.product.price"]` transparently chains through the object returned by the `cart.items.*.product` getter.
-
-### Path Setters
-
-Custom setter logic can be defined with `set "path"()`:
-
-```javascript
-export default {
-  users: [
-    { firstName: "Alice", lastName: "Smith" },
-    { firstName: "Bob", lastName: "Jones" }
-  ],
-  get "users.*.fullName"() {
-    return this["users.*.firstName"] + " " + this["users.*.lastName"];
-  },
-  set "users.*.fullName"(value) {
-    const [first, ...rest] = value.split(" ");
-    this["users.*.firstName"] = first;
-    this["users.*.lastName"] = rest.join(" ");
-  }
-};
-```
-
-```html
-<template data-wcs="for: users">
-  <input type="text" data-wcs="value: .fullName">
-</template>
-```
-
-Two-way binding works with path setters — editing the input calls the setter, which splits and writes back to `firstName` / `lastName`.
-
-### Supported Path Getter Patterns
-
-| Pattern | Description | Example |
-|---|---|---|
-| `get prop()` | Top-level computed | `get total()` |
-| `get "a.b"()` | Nested computed (no wildcard) | `get "cart.totalPrice"()` |
-| `get "a.*.b"()` | Single wildcard | `get "users.*.fullName"()` |
-| `get "a.*.b.*.c"()` | Multiple wildcards | `get "categories.*.items.*.label"()` |
-| `set "a.*.b"(v)` | Wildcard setter | `set "users.*.fullName"(v)` |
-
-### How It Works
-
-1. **Context resolution** — When a `for:` loop renders, each iteration pushes a `ListIndex` onto the address stack. Inside a path getter, `this["users.*.name"]` resolves the `*` using this stack, so it always points to the current element.
-
-2. **Automatic dependency tracking** — When a getter accesses `this["users.*.name"]`, the system registers a dynamic dependency from `users.*.name` to the getter's path. When `users.*.name` changes, the getter's cache is dirtied.
-
-3. **Caching** — Getter results are cached per concrete address (path + loop index). `users.*.fullName` at index 0 has a separate cache entry from index 1. The cache is invalidated only when dependencies change.
-
-4. **Direct index access** — You can also access specific elements by numeric index: `this["users.0.name"]` resolves as `users[0].name` without needing loop context.
-
-### Loop Index Variables (`$1`, `$2`, ...)
-
-Inside getters and event handlers, `this.$1`, `this.$2`, etc. provide the current loop iteration index (0-based value, 1-based naming):
-
-```javascript
-export default {
-  users: ["Alice", "Bob", "Charlie"],
-  get "users.*.rowLabel"() {
-    return "#" + (this.$1 + 1) + ": " + this["users.*"];
-  }
-};
-```
-
-```html
-<template data-wcs="for: users">
-  <div data-wcs="textContent: .rowLabel"></div>
-</template>
-<!-- Output:
-  #1: Alice
-  #2: Bob
-  #3: Charlie
--->
-```
-
-For nested loops, `$1` is the outer index and `$2` is the inner index.
-
-You can also display the loop index directly in templates:
-
-```html
-<template data-wcs="for: items">
-  <td>{{ $1|inc(1) }}</td>  <!-- 1-based row number -->
-</template>
-```
-
-### Proxy APIs
-
-Inside state objects (getters / methods), the following APIs are available via `this`:
-
-| API | Description |
-|---|---|
-| `this.$getAll(path, indexes?)` | Get all values matching a wildcard path |
-| `this.$resolve(path, indexes, value?)` | Resolve a wildcard path with specific indexes |
-| `this.$postUpdate(path)` | Manually trigger update notification for a path |
-| `this.$trackDependency(path)` | Manually register a dependency for cache invalidation |
-| `this.$stateElement` | Access to the `IStateElement` instance |
-| `this.$1`, `this.$2`, ... | Current loop index (1-based naming, 0-based value) |
-
-#### `$getAll` — Aggregate Across Array Elements
-
-`$getAll` collects all values that match a wildcard path, returning them as an array. Essential for aggregation patterns:
-
-```javascript
-export default {
-  scores: [85, 92, 78, 95, 88],
-  get average() {
-    const all = this.$getAll("scores.*", []);
-    return all.reduce((sum, v) => sum + v, 0) / all.length;
-  },
-  get max() {
-    return Math.max(...this.$getAll("scores.*", []));
-  }
-};
-```
-
-#### `$resolve` — Access by Explicit Index
-
-`$resolve` reads or writes a value at a specific wildcard index:
-
-```javascript
-export default {
-  items: ["A", "B", "C"],
-  swapFirstTwo() {
-    const a = this.$resolve("items.*", [0]);
-    const b = this.$resolve("items.*", [1]);
-    this.$resolve("items.*", [0], b);
-    this.$resolve("items.*", [1], a);
-  }
-};
-```
-
-## Event Handling
-
-Bind event handlers with `on*` properties:
-
-```html
-<button data-wcs="onclick: handleClick">Click me</button>
-<form data-wcs="onsubmit#prevent: handleSubmit">...</form>
-```
-
-Handler methods receive the event and loop indexes:
-
-```javascript
-export default {
-  items: ["A", "B", "C"],
-  handleClick(event) {
-    console.log("clicked");
-  },
-  removeItem(event, index) {
-    // index is the loop context ($1)
-    this.items = this.items.toSpliced(index, 1);
-  }
-};
-```
-
-```html
-<template data-wcs="for: items">
-  <button data-wcs="onclick: removeItem">Delete</button>
-</template>
-```
-
-## Filters
-
-40 built-in filters are available for both input (DOM → state) and output (state → DOM) directions.
-
-### Comparison
-
-| Filter | Description | Example |
-|---|---|---|
-| `eq(value)` | Equal | `count\|eq(0)` → `true/false` |
-| `ne(value)` | Not equal | `count\|ne(0)` |
-| `not` | Boolean NOT | `isActive\|not` |
-| `lt(n)` | Less than | `count\|lt(10)` |
-| `le(n)` | Less than or equal | `count\|le(10)` |
-| `gt(n)` | Greater than | `count\|gt(0)` |
-| `ge(n)` | Greater than or equal | `count\|ge(0)` |
-
-### Arithmetic
-
-| Filter | Description | Example |
-|---|---|---|
-| `inc(n)` | Add | `count\|inc(1)` |
-| `dec(n)` | Subtract | `count\|dec(1)` |
-| `mul(n)` | Multiply | `price\|mul(1.1)` |
-| `div(n)` | Divide | `total\|div(100)` |
-| `mod(n)` | Modulo | `index\|mod(2)` |
-
-### Number Formatting
-
-| Filter | Description | Example |
-|---|---|---|
-| `fix(n)` | Fixed decimal places | `price\|fix(2)` → `"100.00"` |
-| `round(n?)` | Round | `value\|round(2)` |
-| `floor(n?)` | Floor | `value\|floor` |
-| `ceil(n?)` | Ceiling | `value\|ceil` |
-| `locale(loc?)` | Locale number format | `count\|locale` / `count\|locale(ja-JP)` |
-| `percent(n?)` | Percentage format | `ratio\|percent(1)` |
-
-### String
-
-| Filter | Description | Example |
-|---|---|---|
-| `uc` | Upper case | `name\|uc` |
-| `lc` | Lower case | `name\|lc` |
-| `cap` | Capitalize | `name\|cap` |
-| `trim` | Trim whitespace | `text\|trim` |
-| `slice(n)` | Slice string | `text\|slice(5)` |
-| `substr(start, length)` | Substring | `text\|substr(0,10)` |
-| `pad(n, char?)` | Pad start | `id\|pad(5,0)` → `"00001"` |
-| `rep(n)` | Repeat | `text\|rep(3)` |
-| `rev` | Reverse | `text\|rev` |
-
-### Type Conversion
-
-| Filter | Description | Example |
-|---|---|---|
-| `int` | Parse integer | `input\|int` |
-| `float` | Parse float | `input\|float` |
-| `boolean` | To boolean | `value\|boolean` |
-| `number` | To number | `value\|number` |
-| `string` | To string | `value\|string` |
-| `null` | To null | `value\|null` |
-
-### Date / Time
-
-| Filter | Description | Example |
-|---|---|---|
-| `date(loc?)` | Date format | `timestamp\|date` / `timestamp\|date(ja-JP)` |
-| `time(loc?)` | Time format | `timestamp\|time` |
-| `datetime(loc?)` | Date + Time | `timestamp\|datetime(en-US)` |
-| `ymd(sep?)` | YYYY-MM-DD | `timestamp\|ymd` / `timestamp\|ymd(/)` |
-
-### Boolean / Default
-
-| Filter | Description | Example |
-|---|---|---|
-| `truthy` | Truthy check | `value\|truthy` |
-| `falsy` | Falsy check | `value\|falsy` |
-| `defaults(v)` | Fallback value | `name\|defaults(Anonymous)` |
-
-### Filter Chaining
-
-Filters can be chained with `|`:
-
-```html
-<div data-wcs="textContent: price|mul(1.1)|round(2)|locale(ja-JP)"></div>
-```
-
-## Web Component Binding
-
-`@wcstack/state` supports bidirectional state binding with custom elements using Shadow DOM or Light DOM.
-
-Many frameworks use patterns like prop drilling, context providers, or external stores (Redux, Pinia) to share state across components. `@wcstack/state` takes a different approach: parent and child components are connected through **path contracts** — the parent binds an outer state path to an inner component property via `data-wcs`, and the child simply reads and writes its own state as usual:
-
-1. The child references and updates the parent's state through its own state proxy — no props, no events, no awareness of the parent.
-2. When the parent's state changes, the Proxy `set` trap automatically notifies any child bindings that reference the affected path.
-3. Because the only coupling is the **path name**, both sides remain loosely coupled and independently testable.
-4. The cost is path resolution (cached at O(1) after first access) plus change propagation through the dependency graph.
-
-This provides a lightweight approach to cross-component state management based on path resolution rather than component-level abstractions.
-
-### Component Definition (Shadow DOM)
-
-```javascript
-class MyComponent extends HTMLElement {
-  state = { message: "" };
-
-  constructor() {
-    super();
-    this.attachShadow({ mode: "open" });
-    this.shadowRoot.innerHTML = `
-      <wcs-state bind-component="state"></wcs-state>
-      <div>{{ message }}</div>
-      <input type="text" data-wcs="value: message" />
-    `;
-  }
-}
-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.
-
-```javascript
-class MyLightComponent extends HTMLElement {
-  state = { message: "" };
-
-  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" />
-    `;
-  }
-}
-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
-
-### Host Usage
-
-```html
-<wcs-state>
-  <script type="module">
-    export default {
-      user: { name: "Alice" }
-    };
-  </script>
-</wcs-state>
-
-<!-- Bind component's state.message to outer user.name -->
-<my-component data-wcs="state.message: user.name"></my-component>
-```
-
-- `bind-component="state"` maps the component's `state` property to `<wcs-state>`
-- `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
-
-### 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`.
-
-```javascript
-class MyComponent extends HTMLElement {
-  state = Object.freeze({
-    message: "Hello, World!"
-  });
-
-  constructor() {
-    super();
-    this.attachShadow({ mode: "open" });
-  }
-
-  connectedCallback() {
-    this.shadowRoot.innerHTML = `
-      <wcs-state bind-component="state"></wcs-state>
-      <div>{{ message }}</div>
-    `;
-  }
-
-  async $stateReadyCallback(stateProp) {
-    console.log("state ready:", stateProp); // "state"
-  }
-}
-customElements.define("my-component", MyComponent);
-```
-
-- Initial component `state` can be defined with `Object.freeze(...)` (it is replaced with a writable reactive state after injection)
-- `bind-component="state"` exposes `this.state` as a state proxy powered by `@wcstack/state`
-- Assignments like `this.state.message = "..."` immediately update `{{ message }}` inside Shadow DOM
-- `async $stateReadyCallback(stateProp)` is called right after component state becomes ready for use (`stateProp` is the property name from `bind-component`)
-
-### Constraints
-
-- `<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`)
-
-### Loop with Components
-
-```html
-<template data-wcs="for: users">
-  <my-component data-wcs="state.message: .name"></my-component>
-</template>
-```
-
-## Declarative Custom Components (DCC)
-
-Define custom elements **entirely in HTML** — no JavaScript class definition needed. Using `data-wc-definition` and Declarative Shadow DOM (`<template shadowrootmode>`), you can declare reusable components with reactive state inline.
-
-### Basic Definition
-
-```html
-<!-- 1. Define the component (hidden by CSS) -->
-<my-counter data-wc-definition>
-  <template shadowrootmode="open">
-    <p>{{ count }}</p>
-    <button data-wcs="onclick: increment">+1</button>
-    <wcs-state>
-      <script type="module">
-        export default {
-          count: 0,
-          increment() { this.count++; },
-          $bindables: ["count"]
-        };
-      </script>
-    </wcs-state>
-  </template>
-</my-counter>
-
-<!-- 2. Use it — each instance gets its own state -->
-<my-counter></my-counter>
-<my-counter></my-counter>
-```
-
-When `<wcs-state>` detects it is inside a `data-wc-definition` host, it:
-
-1. Loads the state object (from `<script type="module">` or `src="*.js"`)
-2. Generates a custom element class with getter/setter/method properties on the prototype
-3. Registers it via `customElements.define()`
-
-The definition element is hidden; each instance clones the template into its own Shadow DOM and initializes its own `<wcs-state>`.
-
-### Recommended CSS
-
-```css
-:not(:defined) { display: none; }
-[data-wc-definition] { display: none; }
-```
-
-### `$bindables` and wc-bindable Protocol
-
-The `$bindables` array declares which state properties are exposed as component properties with change events, following the [wc-bindable protocol](https://github.com/nicenemo/nicenemo/blob/main/docs/wc-bindable-protocol.md):
-
-```javascript
-export default {
-  count: 0,
-  increment() { this.count++; },
-  $bindables: ["count"]
-};
-```
-
-This generates:
-
-- `static wcBindable` on the class — protocol metadata for framework adapters
-- Getter/setter on the prototype — reads/writes go through the reactive proxy
-- `CustomEvent` dispatch — `my-counter:count-changed` fires on every mutation
-
-### Binding to DCC Properties
-
-Other `<wcs-state>` instances can bind to DCC properties just like any Web Component:
-
-```html
-<my-counter data-wcs="count: parentCount"></my-counter>
-
-<wcs-state>
-  <script type="module">
-    export default { parentCount: 0 };
-  </script>
-</wcs-state>
-<div data-wcs="textContent: parentCount"></div>
-```
-
-### Shadow Root Mode
-
-Both `open` and `closed` modes are supported:
-
-```html
-<my-component data-wc-definition>
-  <template shadowrootmode="closed">
-    <!-- closed shadow DOM -->
-  </template>
-</my-component>
-```
-
-### Internal Properties
-
-Properties prefixed with `$` are internal and not exposed on the component prototype:
-
-| Property | Purpose |
-|----------|---------|
-| `$bindables` | Declares observable properties |
-| `$connectedCallback` | Lifecycle hook (runs on each instance) |
-| `$disconnectedCallback` | Cleanup hook |
-| `$updatedCallback` | Called after state mutations |
-
-## SVG Support
-
-All bindings work inside `<svg>` elements. Use `attr.*` for SVG attributes:
-
-```html
-<svg width="200" height="100">
-  <template data-wcs="for: points">
-    <circle data-wcs="attr.cx: .x; attr.cy: .y; attr.fill: .color" r="5" />
-  </template>
-</svg>
-```
-
-## Lifecycle Hooks
-
-State objects can define `$connectedCallback`, `$disconnectedCallback`, and `$updatedCallback` for initialization, cleanup, and update lifecycle handling.
-
-```html
-<wcs-state>
-  <script type="module">
-    export default {
-      timer: null,
-      count: 0,
-
-      // Called when <wcs-state> is connected to the DOM
-      async $connectedCallback() {
-        const res = await fetch("/api/initial-count");
-        this.count = await res.json();
-        this.timer = setInterval(() => { this.count++; }, 1000);
-      },
-
-      // Called when <wcs-state> is disconnected from the DOM (sync only)
-      $disconnectedCallback() {
-        clearInterval(this.timer);
-      }
-    };
-  </script>
-</wcs-state>
-```
-
-| Hook | Timing | Async |
-|---|---|---|
-| `$connectedCallback` | After state initialization on first connect; on every reconnect thereafter | Yes (awaited) |
-| `$disconnectedCallback` | When the element is removed from the DOM | No (sync only) |
-| `$updatedCallback(paths, indexesListByPath)` | After state updates are applied | Yes (not awaited) |
-
-All hooks except `$disconnectedCallback` support `async` — you can use `async/await` in any of them. Since the reactive proxy detects every property assignment as a change, standard `async/await` with direct property updates is sufficient for asynchronous operations — loading flags, fetched data, and error messages are all just property assignments, without requiring additional abstractions for async state management.
-
-- `this` inside hooks is the state proxy with full read/write access
-- `$connectedCallback` is called **every time** the element is connected (including re-insertion after removal), making it suitable for setup that should be re-established
-- `$disconnectedCallback` is called synchronously — use it for cleanup such as clearing timers, removing event listeners, or releasing resources
-- `$updatedCallback(paths, indexesListByPath)` receives the updated path list. For wildcard updates, `indexesListByPath` contains the updated index sets. Can be `async`, but the return value is not awaited
-- In Web Components, define `async $stateReadyCallback(stateProp)` to receive a hook when the bound state becomes available via `bind-component`
-
-## Configuration
-
-Pass a partial configuration object to `bootstrapState()`:
-
-```javascript
-import { bootstrapState } from '@wcstack/state';
-
-bootstrapState({
-  locale: 'ja-JP',
-  debug: true,
-  enableMustache: false,
-  tagNames: { state: 'my-state' },
-});
-```
-
-All options with defaults:
-
-| Option | Default | Description |
-|---|---|---|
-| `bindAttributeName` | `'data-wcs'` | Binding attribute name |
-| `tagNames.state` | `'wcs-state'` | State element tag name |
-| `locale` | `'en'` | Default locale for filters |
-| `debug` | `false` | Debug mode |
-| `enableMustache` | `true` | Enable `{{ }}` syntax |
-
-## TypeScript Support
-
-`defineState()` wraps your state object and provides type-safe `this` inside methods and getters — with zero runtime cost (identity function).
-
-```typescript
-import { defineState } from '@wcstack/state';
-
-export default defineState({
-  count: 0,
-  users: [] as { name: string; age: number }[],
-
-  increment() {
-    this.count++;            // ✅ number
-    this["users.*.name"];    // ✅ string (dot-path resolution)
-    this.$getAll("users.*.age", []); // ✅ API method
-  },
-
-  get "users.*.ageCategory"() {
-    return this["users.*.age"] < 25 ? "Young" : "Adult";
-  }
-});
-```
-
-Utility types `WcsPaths<T>` and `WcsPathValue<T, P>` are also exported for advanced use cases. See [docs/define-state.md](docs/define-state.md) for full documentation.
-
-## API Reference
-
-### `bootstrapState()`
-
-Initialize the state system. Registers `<wcs-state>` custom element and sets up DOM content loaded handler.
-
-```javascript
-import { bootstrapState } from '@wcstack/state';
-bootstrapState();
-```
-
-### `<wcs-state>` Element
-
-| Attribute | Description |
-|---|---|
-| `name` | State name (default: `"default"`) |
-| `state` | ID of a `<script type="application/json">` element |
-| `src` | URL to `.json` or `.js` file |
-| `json` | Inline JSON string |
-| `bind-component` | Property name for web component binding |
-
-### IStateElement
-
-| 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 |
-| `setterPaths` | Set of paths defined as setters |
-| `createState(mutability, callback)` | Create a state proxy (`"readonly"` or `"writable"`) |
-| `createStateAsync(mutability, callback)` | Async version of `createState` |
-| `setInitialState(state)` | Set state programmatically (before initialization) |
-| `bindProperty(prop, descriptor)` | Define a property on the raw state object |
-| `nextVersion()` | Increment and return version number |
-
-## Architecture
-
-```
-bootstrapState()
-  └── registerComponents()              // Register <wcs-state> custom element
-
-<wcs-state> connectedCallback
-  ├── _initializeBindWebComponent()     // bind-component: get state from parent component
-  ├── _initialize()                     // Load state (state attr / src / json / script / API)
-  │     └── setStateElementByName()     // Register to WeakMap<Node, Map<name, element>>
-  │           └── (first registration per rootNode)
-  │                 └── queueMicrotask → buildBindings()
-  ├── _callStateConnectedCallback()     // Call $connectedCallback if defined
-
-buildBindings(root)
-  ├── waitForStateInitialize()          // Wait for all <wcs-state> initializePromise
-  ├── convertMustacheToComments()       // {{ }} → comment nodes
-  ├── collectStructuralFragments()      // Collect for/if templates
-  └── initializeBindings()              // Walk DOM, parse data-wcs, set up bindings
-```
-
-### Reactivity Flow
-
-1. State changes via Proxy `set` trap → `setByAddress()`
-2. Address resolved → updater enqueues absolute address
-3. Dependency walker invalidates (dirties) downstream caches
-4. Updater applies changes to bound DOM nodes via `applyChangeFromBindings()`
-
-### State Address System
-
-Paths like `users.*.name` are decomposed into:
-
-- **PathInfo** — static path metadata (segments, wildcard count, parent path)
-- **ListIndex** — runtime loop index chain
-- **StateAddress** — combination of PathInfo + ListIndex
-- **AbsoluteStateAddress** — state name + StateAddress (for cross-state references)
-
-## Server-Side Rendering
-
-`@wcstack/state` supports SSR via the companion [`@wcstack/server`](../server/) package. The same templates you write for the client render on the server — no changes needed.
-
-### Quick Setup
-
-1. Add `enable-ssr` to your `<wcs-state>` element:
-
-```html
-<wcs-state enable-ssr>
-  <script type="module">
-    export default {
-      items: [],
-      async $connectedCallback() {
-        const res = await fetch("/api/items");
-        this.items = await res.json();
-      }
-    };
-  </script>
-</wcs-state>
-<template data-wcs="for: items">
-  <div data-wcs="textContent: items.*.name"></div>
-</template>
-```
-
-2. Render on the server:
-
-```javascript
-import { renderToString } from "@wcstack/server";
-
-const html = await renderToString(template, {
-  baseUrl: "http://localhost:3000"
-});
-```
-
-That's it. The client-side `@wcstack/state` automatically detects the `<wcs-ssr>` element, restores state from the JSON snapshot, and resumes reactivity without re-rendering.
-
-### How It Works
-
-| Phase | What happens |
-|-------|-------------|
-| **Server** | `renderToString()` runs your template in happy-dom, executes `$connectedCallback` (including `fetch()`), applies all bindings, and outputs rendered HTML with a `<wcs-ssr>` element containing hydration data |
-| **Client** | `<wcs-state enable-ssr>` loads state from `<wcs-ssr>` JSON, skips `$connectedCallback`, and `hydrateBindings()` wires up reactivity on the existing DOM |
-| **Fallback** | If server/client versions mismatch, the SSR DOM is cleaned up and `buildBindings()` runs a full client-side render |
-
-### What `enable-ssr` Does
-
-| Context | Behavior |
-|---------|----------|
-| **Server** (`renderToString`) | Generates `<wcs-ssr>` with state JSON, template fragments, and property data |
-| **Client** (hydration) | Reads `<wcs-ssr>`, restores state, skips `$connectedCallback`, hydrates bindings on existing DOM |
-
-See [`@wcstack/server` README](../server/README.md) for full API documentation.
-
-## License
-
-MIT
+# @wcstack/state
+
+**What if HTML had reactive data binding?**
+
+Imagine a future where the browser natively understands state — you declare data inline, bind it to the DOM with attributes, and everything stays in sync. No virtual DOM, no compilation, no framework. Just HTML that reacts.
+
+That's what `<wcs-state>` and `data-wcs` explore. One CDN import, zero dependencies, pure HTML syntax.
+
+The CDN script only registers the custom element definition — nothing else happens at load time. When a `<wcs-state>` element connects to the DOM, it reads its state source, scans all `data-wcs` bindings within the same root node (`document` or `ShadowRoot`), and wires up reactivity. All initialization is driven by the element's lifecycle, not by your code.
+
+## Design Philosophy
+
+### Path as the Universal Contract
+
+In every existing framework, the **component** is the coupling point between UI and state. Components import state hooks, selectors, or reactive primitives, and the binding happens inside JavaScript. No matter how cleanly you separate your state store, there is always glue code in the component that pulls state in.
+
+`@wcstack/state` eliminates that coupling entirely. The **only** thing connecting UI and state is a **path string** — a dot-separated address like `user.name` or `cart.items.*.subtotal`. This is the sole contract between the two layers:
+
+| Layer | What it knows | What it doesn't know |
+|-------|---------------|----------------------|
+| **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 |
+
+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.
+
+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.
+
+### Why This Matters
+
+This is complete separation of UI and state with **no JavaScript intermediary**. You can:
+
+- Redesign the entire UI without touching state logic
+- Refactor state structure and only update path strings
+- Read the HTML alone and understand every data dependency
+
+The path contract works like a URL in a REST API — a simple string that both sides agree on, with no shared code between them. It's the natural result of building on HTML's declarative nature rather than inventing a template language on top of JavaScript.
+
+## 4 Steps to Reactive HTML
+
+```html
+<!-- 1. Load the CDN -->
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+
+<!-- 2. Write a <wcs-state> tag -->
+<wcs-state>
+  <!-- 3. Define your state object -->
+  <script type="module">
+    export default {
+      message: "Hello, World!"
+    };
+  </script>
+</wcs-state>
+
+<!-- 4. Bind with data-wcs attributes -->
+<div data-wcs="textContent: message"></div>
+```
+
+That's it. No build, no bootstrap code, no framework.
+
+## Features
+
+- **Declarative data binding** — `data-wcs` attribute for property / text / event / structural binding
+- **Reactive Proxy** — ES Proxy-based automatic DOM updates with dependency tracking
+- **Structural directives** — `for`, `if` / `elseif` / `else` via `<template>` elements
+- **Built-in filters** — 40 filters for formatting, comparison, arithmetic, date, and more
+- **Two-way binding** — automatic for `<input>`, `<select>`, `<textarea>`
+- **Web Component binding** — bidirectional state binding with Shadow DOM components
+- **Path getters** — dot-path key getters (`get "users.*.fullName"()`) for virtual properties at any depth in a data tree, all defined flat in one place with automatic dependency tracking and caching
+- **Mustache syntax** — `{{ path|filter }}` in text nodes
+- **Multiple state sources** — JSON, JS module, inline script, API, attribute
+- **SVG support** — full binding support inside `<svg>` elements
+- **Lifecycle hooks** — `$connectedCallback` / `$disconnectedCallback` / `$updatedCallback`, plus `$stateReadyCallback` for Web Components
+- **TypeScript support** — `defineState()` for typed state definitions with dot-path autocompletion ([details](docs/define-state.md))
+- **Server-Side Rendering** — `enable-ssr` attribute + `@wcstack/server` for full SSR with automatic hydration
+- **Zero dependencies** — no runtime dependencies
+
+## Installation
+
+### CDN (recommended)
+
+```html
+<!-- Auto-initialization — this is all you need -->
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+```
+
+### CDN (manual initialization)
+
+```html
+<script type="module">
+  import { bootstrapState } from 'https://esm.run/@wcstack/state';
+  bootstrapState();
+</script>
+```
+
+## Basic Usage
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      count: 0,
+      user: { id: 1, name: "Alice" },
+      users: [
+        { id: 1, name: "Alice" },
+        { id: 2, name: "Bob" },
+        { id: 3, name: "Charlie" }
+      ],
+      countUp() { this.count += 1; },
+      clearCount() { this.count = 0; },
+      get "users.*.displayName"() {
+        return this["users.*.name"] + " (ID: " + this["users.*.id"] + ")";
+      }
+    };
+  </script>
+</wcs-state>
+
+<!-- Text binding -->
+<div data-wcs="textContent: count"></div>
+{{ count }}
+
+<!-- Two-way input binding -->
+<input type="text" data-wcs="value: user.name">
+
+<!-- Event binding -->
+<button data-wcs="onclick: countUp">Increment</button>
+
+<!-- Conditional class -->
+<div data-wcs="textContent: count; class.over: count|gt(10)"></div>
+
+<!-- Loop -->
+<template data-wcs="for: users">
+  <div>
+    <span data-wcs="textContent: .id"></span>:
+    <span data-wcs="textContent: .displayName"></span>
+  </div>
+</template>
+
+<!-- Conditional rendering -->
+<template data-wcs="if: count|gt(0)">
+  <p>The count is positive.</p>
+</template>
+<template data-wcs="elseif: count|lt(0)">
+  <p>The count is negative.</p>
+</template>
+<template data-wcs="else:">
+  <p>The count is zero.</p>
+</template>
+```
+
+## State Initialization
+
+`<wcs-state>` supports multiple ways to load initial state:
+
+```html
+<!-- 1. Reference a <script type="application/json"> by id -->
+<script type="application/json" id="state">
+  { "count": 0 }
+</script>
+<wcs-state state="state"></wcs-state>
+
+<!-- 2. Inline JSON attribute -->
+<wcs-state json='{ "count": 0 }'></wcs-state>
+
+<!-- 3. External JSON file -->
+<wcs-state src="./data.json"></wcs-state>
+
+<!-- 4. External JS module (export default { ... }) -->
+<wcs-state src="./state.js"></wcs-state>
+
+<!-- 5. Inline script module -->
+<wcs-state>
+  <script type="module">
+    export default { count: 0 };
+  </script>
+</wcs-state>
+
+<!-- 6. Programmatic API -->
+<script>
+  const el = document.createElement('wcs-state');
+  el.setInitialState({ count: 0 });
+  document.body.appendChild(el);
+</script>
+```
+
+Resolution order: `state` → `src` (.json / .js) → `json` → inner `<script>` → wait for `setInitialState()`.
+
+### Named State
+
+Multiple state elements can coexist with the `name` attribute. Bindings reference them with `@name`:
+
+```html
+<wcs-state name="cart">...</wcs-state>
+<wcs-state name="user">...</wcs-state>
+
+<div data-wcs="textContent: total@cart"></div>
+<div data-wcs="textContent: name@user"></div>
+```
+
+Default name is `"default"` (no `@` needed).
+
+## Updating State
+
+In `@wcstack/state`, every piece of state has a **path** — like `count`, `user.name`, or `items`. To update state reactively, **assign to the path**:
+
+```javascript
+this.count = 10;               // path "count"
+this["user.name"] = "Bob";     // path "user.name"
+```
+
+That's the one rule: **assign to the path, and the DOM updates automatically.**
+
+### Why `this.user.name = "Bob"` Doesn't Work
+
+`this.user.name` first reads the `user` object via `this.user` (a path read), then sets `.name` on that plain object — this is not a path assignment, so the change is not detected:
+
+```javascript
+// ✅ Path assignment — change detected
+this["user.name"] = "Bob";
+
+// ❌ Not a path assignment — change NOT detected
+this.user.name = "Bob";
+```
+
+### Arrays
+
+The same rule applies: assign a new array to the path. Mutating methods (`push`, `splice`, `sort`, ...) modify the array in place without path assignment, so use non-destructive alternatives:
+
+```javascript
+// ✅ New array assigned to path — change detected
+this.items = this.items.concat({ id: 4, text: "New" });
+this.items = this.items.toSpliced(index, 1);
+this.items = this.items.filter(item => !item.done);
+this.items = this.items.toSorted((a, b) => a.id - b.id);
+this.items = this.items.toReversed();
+this.items = this.items.with(index, newValue);
+
+// ❌ In-place mutation — no path assignment, change NOT detected
+this.items.push({ id: 4, text: "New" });
+this.items.splice(index, 1);
+this.items.sort((a, b) => a.id - b.id);
+```
+
+## Binding Syntax
+
+### `data-wcs` Attribute
+
+```
+property[#modifier]: path[@state][|filter[|filter(args)...]]
+```
+
+Multiple bindings separated by `;`:
+
+```html
+<div data-wcs="textContent: count; class.over: count|gt(10)"></div>
+```
+
+| Part | Description | Example |
+|---|---|---|
+| `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
+
+| Property | Description |
+|---|---|
+| `value` | Element value (two-way for inputs) |
+| `checked` | Checkbox / radio checked state (two-way) |
+| `textContent` | Text content |
+| `text` | Alias for textContent |
+| `html` | innerHTML |
+| `class.NAME` | Toggle a CSS class |
+| `style.PROP` | Set a CSS style property |
+| `attr.NAME` | Set an attribute (supports SVG namespace) |
+| `radio` | Radio button group binding (two-way) |
+| `checkbox` | Checkbox group binding to array (two-way) |
+| `onclick`, `on*` | Event handler binding |
+
+### Modifiers
+
+| Modifier | Description |
+|---|---|
+| `#ro` | Read-only — disables two-way binding |
+| `#prevent` | Calls `event.preventDefault()` on event handlers |
+| `#stop` | Calls `event.stopPropagation()` on event handlers |
+| `#onchange` | Uses `change` event instead of `input` for two-way binding |
+
+### Two-Way Binding
+
+Automatically enabled for:
+
+| Element | Property | Event |
+|---|---|---|
+| `<input type="checkbox/radio">` | `checked` | `input` |
+| `<input>` (other types) | `value`, `valueAsNumber`, `valueAsDate` | `input` |
+| `<select>` | `value` | `change` |
+| `<textarea>` | `value` | `input` |
+
+`<input type="button">` is excluded. Use `#ro` to disable, `#onchange` to change the event.
+
+### Radio Binding
+
+Bind a radio button group to a single state value with `radio`:
+
+```html
+<input type="radio" value="red" data-wcs="radio: selectedColor">
+<input type="radio" value="blue" data-wcs="radio: selectedColor">
+```
+
+The radio button whose `value` matches the state value is automatically checked. When the user selects a different radio button, the state is updated. Use `#ro` for read-only.
+
+Inside a `for` loop:
+
+```html
+<template data-wcs="for: branches">
+  <label>
+    <input type="radio" data-wcs="value: .; radio: currentBranch">
+    {{ . }}
+  </label>
+</template>
+```
+
+### Checkbox Binding
+
+Bind a checkbox group to a state array with `checkbox`:
+
+```html
+<input type="checkbox" value="apple" data-wcs="checkbox: selectedFruits">
+<input type="checkbox" value="banana" data-wcs="checkbox: selectedFruits">
+<input type="checkbox" value="orange" data-wcs="checkbox: selectedFruits">
+```
+
+A checkbox is checked when its `value` is included in the state array. Toggling a checkbox adds or removes the value from the array. Use `|int` to convert string values to numbers, and `#ro` for read-only.
+
+### Mustache Syntax
+
+When `enableMustache` is `true` (default), `{{ expression }}` in text nodes is supported:
+
+```html
+<p>Hello, {{ user.name }}!</p>
+<p>Count: {{ count|locale }}</p>
+```
+
+Internally converted to comment-based bindings (`<!--@@:expression-->`).
+
+## Structural Directives
+
+Structural directives use `<template>` elements:
+
+### Loop (`for`)
+
+```html
+<template data-wcs="for: users">
+  <div>
+    <!-- Full path -->
+    <span data-wcs="textContent: users.*.name"></span>
+    <!-- Shorthand (relative to loop context) -->
+    <span data-wcs="textContent: .name"></span>
+  </div>
+</template>
+```
+
+The `for:` directive uses a **value-based diff algorithm** — each array element's value itself serves as the identity key. There is no need for an explicit `key` attribute (like React's `key` or Vue's `:key`). When the array is reassigned, the differ matches old and new elements by value, reusing existing DOM nodes for unchanged items and efficiently adding, removing, or reordering the rest.
+
+#### Dot Shorthand
+
+Inside a `for` loop, paths starting with `.` are expanded relative to the loop's array path:
+
+| Shorthand | Expanded to | Description |
+|---|---|---|
+| `.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:
+
+```html
+<template data-wcs="for: branches">
+  <label>
+    <input type="radio" data-wcs="value: .; radio: currentBranch">
+    {{ . }}
+  </label>
+</template>
+```
+
+Nested loops are supported with multi-level wildcards. The `.` shorthand in nested `for` directives also expands relative to the parent loop path:
+
+```html
+<template data-wcs="for: regions">
+  <!-- .states → regions.*.states -->
+  <template data-wcs="for: .states">
+    <!-- .name → regions.*.states.*.name -->
+    <span data-wcs="textContent: .name"></span>
+  </template>
+</template>
+```
+
+### Conditional (`if` / `elseif` / `else`)
+
+```html
+<template data-wcs="if: count|gt(0)">
+  <p>Positive</p>
+</template>
+<template data-wcs="elseif: count|lt(0)">
+  <p>Negative</p>
+</template>
+<template data-wcs="else:">
+  <p>Zero</p>
+</template>
+```
+
+Conditions can be chained. `elseif` automatically inverts the previous condition.
+
+## Path Getters (Computed Properties)
+
+**Path getters** are the core feature of `@wcstack/state`. Define computed properties using JavaScript getters with **dot-path string keys** containing wildcards (`*`). They act as **virtual properties that can be attached at any depth in a data tree — all defined flat in one place**. No matter how deeply data is nested, path getters keep definitions at the same level with automatic dependency tracking per loop element.
+
+### Basic Path Getter
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      users: [
+        { id: 1, firstName: "Alice", lastName: "Smith" },
+        { id: 2, firstName: "Bob", lastName: "Jones" }
+      ],
+      // Path getter — runs per-element inside a loop
+      get "users.*.fullName"() {
+        return this["users.*.firstName"] + " " + this["users.*.lastName"];
+      },
+      get "users.*.displayName"() {
+        return this["users.*.fullName"] + " (ID: " + this["users.*.id"] + ")";
+      }
+    };
+  </script>
+</wcs-state>
+
+<template data-wcs="for: users">
+  <div data-wcs="textContent: .displayName"></div>
+</template>
+<!-- Output:
+  Alice Smith (ID: 1)
+  Bob Jones (ID: 2)
+-->
+```
+
+Inside a path getter, `this["users.*.firstName"]` automatically resolves to the current loop element — no manual indexing needed.
+
+### Top-Level Computed Properties
+
+Getters without wildcards work as standard computed properties:
+
+```javascript
+export default {
+  price: 100,
+  tax: 0.1,
+  get total() {
+    return this.price * (1 + this.tax);
+  }
+};
+```
+
+### Getter Chaining
+
+Path getters can reference other path getters, forming a dependency chain. The cache is automatically invalidated when any upstream value changes:
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      taxRate: 0.1,
+      cart: {
+        items: [
+          { productId: "P001", quantity: 2, unitPrice: 500 },
+          { productId: "P002", quantity: 1, unitPrice: 1200 }
+        ]
+      },
+      // Per-item subtotal
+      get "cart.items.*.subtotal"() {
+        return this["cart.items.*.unitPrice"] * this["cart.items.*.quantity"];
+      },
+      // Aggregate: sum of all subtotals
+      get "cart.totalPrice"() {
+        return this.$getAll("cart.items.*.subtotal", []).reduce((sum, v) => sum + v, 0);
+      },
+      // Chained: tax derived from totalPrice
+      get "cart.tax"() {
+        return this["cart.totalPrice"] * this.taxRate;
+      },
+      // Chained: grand total
+      get "cart.grandTotal"() {
+        return this["cart.totalPrice"] + this["cart.tax"];
+      }
+    };
+  </script>
+</wcs-state>
+
+<template data-wcs="for: cart.items">
+  <div>
+    <span data-wcs="textContent: .productId"></span>:
+    <span data-wcs="textContent: .subtotal|locale"></span>
+  </div>
+</template>
+<p>Total: <span data-wcs="textContent: cart.totalPrice|locale"></span></p>
+<p>Tax: <span data-wcs="textContent: cart.tax|locale"></span></p>
+<p>Grand Total: <span data-wcs="textContent: cart.grandTotal|locale"></span></p>
+```
+
+Dependency chain: `cart.grandTotal` → `cart.tax` → `cart.totalPrice` → `cart.items.*.subtotal` → `cart.items.*.unitPrice` / `cart.items.*.quantity`. Changing any item's `unitPrice` or `quantity` automatically recomputes the entire chain.
+
+### Nested Wildcard Getters
+
+Multiple wildcards are supported for nested array structures:
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      categories: [
+        {
+          name: "Fruits",
+          items: [
+            { name: "Apple", price: 150 },
+            { name: "Banana", price: 100 }
+          ]
+        },
+        {
+          name: "Vegetables",
+          items: [
+            { name: "Carrot", price: 80 }
+          ]
+        }
+      ],
+      get "categories.*.items.*.label"() {
+        return this["categories.*.name"] + " / " + this["categories.*.items.*.name"];
+      }
+    };
+  </script>
+</wcs-state>
+
+<template data-wcs="for: categories">
+  <h3 data-wcs="textContent: .name"></h3>
+  <template data-wcs="for: .items">
+    <div data-wcs="textContent: .label"></div>
+  </template>
+</template>
+<!-- Output:
+  Fruits
+    Fruits / Apple
+    Fruits / Banana
+  Vegetables
+    Vegetables / Carrot
+-->
+```
+
+### Flat Virtual Properties Across Any Depth
+
+A key advantage of path getters is that **no matter how deeply data is nested, all virtual properties are defined flat in one place**. This eliminates the need to split components just to hold computed properties at each nesting level.
+
+```javascript
+export default {
+  regions: [
+    { name: "Kanto", prefectures: [
+      { name: "Tokyo", cities: [
+        { name: "Shibuya", population: 230000, area: 15.11 },
+        { name: "Shinjuku", population: 346000, area: 18.22 }
+      ]},
+      { name: "Kanagawa", cities: [
+        { name: "Yokohama", population: 3750000, area: 437.56 }
+      ]}
+    ]}
+  ],
+
+  // --- All flat, regardless of nesting depth ---
+
+  // City level — virtual properties
+  get "regions.*.prefectures.*.cities.*.density"() {
+    return this["regions.*.prefectures.*.cities.*.population"]
+         / this["regions.*.prefectures.*.cities.*.area"];
+  },
+  get "regions.*.prefectures.*.cities.*.label"() {
+    return this["regions.*.prefectures.*.name"] + " "
+         + this["regions.*.prefectures.*.cities.*.name"];
+  },
+
+  // Prefecture level — aggregate from cities
+  get "regions.*.prefectures.*.totalPopulation"() {
+    return this.$getAll("regions.*.prefectures.*.cities.*.population", [])
+      .reduce((a, b) => a + b, 0);
+  },
+
+  // Region level — aggregate from prefectures
+  get "regions.*.totalPopulation"() {
+    return this.$getAll("regions.*.prefectures.*.totalPopulation", [])
+      .reduce((a, b) => a + b, 0);
+  },
+
+  // Top level — aggregate from regions
+  get totalPopulation() {
+    return this.$getAll("regions.*.totalPopulation", [])
+      .reduce((a, b) => a + b, 0);
+  }
+};
+```
+
+Three levels of nesting, five virtual properties — all defined side by side in a single flat object. Each level can reference values from any depth, and aggregation flows naturally from bottom to top via `$getAll`. In component-based frameworks, the typical approach is to create a separate component for each nesting level and pass computed values through the tree. Path getters offer a different trade-off by keeping all definitions in one place.
+
+### Accessing Sub-Properties of Getter Results
+
+When a path getter returns an object, you can access its sub-properties via dot-path:
+
+```javascript
+export default {
+  products: [
+    { id: "P001", name: "Widget", price: 500, stock: 10 },
+    { id: "P002", name: "Gadget", price: 1200, stock: 3 }
+  ],
+  cart: {
+    items: [
+      { productId: "P001", quantity: 2 },
+      { productId: "P002", quantity: 1 }
+    ]
+  },
+  get productByProductId() {
+    return new Map(this.products.map(p => [p.id, p]));
+  },
+  // Returns the full product object
+  get "cart.items.*.product"() {
+    return this.productByProductId.get(this["cart.items.*.productId"]);
+  },
+  // Access sub-property of the returned object
+  get "cart.items.*.total"() {
+    return this["cart.items.*.product.price"] * this["cart.items.*.quantity"];
+  }
+};
+```
+
+`this["cart.items.*.product.price"]` transparently chains through the object returned by the `cart.items.*.product` getter.
+
+### Path Setters
+
+Custom setter logic can be defined with `set "path"()`:
+
+```javascript
+export default {
+  users: [
+    { firstName: "Alice", lastName: "Smith" },
+    { firstName: "Bob", lastName: "Jones" }
+  ],
+  get "users.*.fullName"() {
+    return this["users.*.firstName"] + " " + this["users.*.lastName"];
+  },
+  set "users.*.fullName"(value) {
+    const [first, ...rest] = value.split(" ");
+    this["users.*.firstName"] = first;
+    this["users.*.lastName"] = rest.join(" ");
+  }
+};
+```
+
+```html
+<template data-wcs="for: users">
+  <input type="text" data-wcs="value: .fullName">
+</template>
+```
+
+Two-way binding works with path setters — editing the input calls the setter, which splits and writes back to `firstName` / `lastName`.
+
+### Supported Path Getter Patterns
+
+| Pattern | Description | Example |
+|---|---|---|
+| `get prop()` | Top-level computed | `get total()` |
+| `get "a.b"()` | Nested computed (no wildcard) | `get "cart.totalPrice"()` |
+| `get "a.*.b"()` | Single wildcard | `get "users.*.fullName"()` |
+| `get "a.*.b.*.c"()` | Multiple wildcards | `get "categories.*.items.*.label"()` |
+| `set "a.*.b"(v)` | Wildcard setter | `set "users.*.fullName"(v)` |
+
+### How It Works
+
+1. **Context resolution** — When a `for:` loop renders, each iteration pushes a `ListIndex` onto the address stack. Inside a path getter, `this["users.*.name"]` resolves the `*` using this stack, so it always points to the current element.
+
+2. **Automatic dependency tracking** — When a getter accesses `this["users.*.name"]`, the system registers a dynamic dependency from `users.*.name` to the getter's path. When `users.*.name` changes, the getter's cache is dirtied.
+
+3. **Caching** — Getter results are cached per concrete address (path + loop index). `users.*.fullName` at index 0 has a separate cache entry from index 1. The cache is invalidated only when dependencies change.
+
+4. **Direct index access** — You can also access specific elements by numeric index: `this["users.0.name"]` resolves as `users[0].name` without needing loop context.
+
+### Loop Index Variables (`$1`, `$2`, ...)
+
+Inside getters and event handlers, `this.$1`, `this.$2`, etc. provide the current loop iteration index (0-based value, 1-based naming):
+
+```javascript
+export default {
+  users: ["Alice", "Bob", "Charlie"],
+  get "users.*.rowLabel"() {
+    return "#" + (this.$1 + 1) + ": " + this["users.*"];
+  }
+};
+```
+
+```html
+<template data-wcs="for: users">
+  <div data-wcs="textContent: .rowLabel"></div>
+</template>
+<!-- Output:
+  #1: Alice
+  #2: Bob
+  #3: Charlie
+-->
+```
+
+For nested loops, `$1` is the outer index and `$2` is the inner index.
+
+You can also display the loop index directly in templates:
+
+```html
+<template data-wcs="for: items">
+  <td>{{ $1|inc(1) }}</td>  <!-- 1-based row number -->
+</template>
+```
+
+### Proxy APIs
+
+Inside state objects (getters / methods), the following APIs are available via `this`:
+
+| API | Description |
+|---|---|
+| `this.$getAll(path, indexes?)` | Get all values matching a wildcard path |
+| `this.$resolve(path, indexes, value?)` | Resolve a wildcard path with specific indexes |
+| `this.$postUpdate(path)` | Manually trigger update notification for a path |
+| `this.$trackDependency(path)` | Manually register a dependency for cache invalidation |
+| `this.$stateElement` | Access to the `IStateElement` instance |
+| `this.$1`, `this.$2`, ... | Current loop index (1-based naming, 0-based value) |
+
+#### `$getAll` — Aggregate Across Array Elements
+
+`$getAll` collects all values that match a wildcard path, returning them as an array. Essential for aggregation patterns:
+
+```javascript
+export default {
+  scores: [85, 92, 78, 95, 88],
+  get average() {
+    const all = this.$getAll("scores.*", []);
+    return all.reduce((sum, v) => sum + v, 0) / all.length;
+  },
+  get max() {
+    return Math.max(...this.$getAll("scores.*", []));
+  }
+};
+```
+
+#### `$resolve` — Access by Explicit Index
+
+`$resolve` reads or writes a value at a specific wildcard index:
+
+```javascript
+export default {
+  items: ["A", "B", "C"],
+  swapFirstTwo() {
+    const a = this.$resolve("items.*", [0]);
+    const b = this.$resolve("items.*", [1]);
+    this.$resolve("items.*", [0], b);
+    this.$resolve("items.*", [1], a);
+  }
+};
+```
+
+## Event Handling
+
+Bind event handlers with `on*` properties:
+
+```html
+<button data-wcs="onclick: handleClick">Click me</button>
+<form data-wcs="onsubmit#prevent: handleSubmit">...</form>
+```
+
+Handler methods receive the event and loop indexes:
+
+```javascript
+export default {
+  items: ["A", "B", "C"],
+  handleClick(event) {
+    console.log("clicked");
+  },
+  removeItem(event, index) {
+    // index is the loop context ($1)
+    this.items = this.items.toSpliced(index, 1);
+  }
+};
+```
+
+```html
+<template data-wcs="for: items">
+  <button data-wcs="onclick: removeItem">Delete</button>
+</template>
+```
+
+## Filters
+
+40 built-in filters are available for both input (DOM → state) and output (state → DOM) directions.
+
+### Comparison
+
+| Filter | Description | Example |
+|---|---|---|
+| `eq(value)` | Equal | `count\|eq(0)` → `true/false` |
+| `ne(value)` | Not equal | `count\|ne(0)` |
+| `not` | Boolean NOT | `isActive\|not` |
+| `lt(n)` | Less than | `count\|lt(10)` |
+| `le(n)` | Less than or equal | `count\|le(10)` |
+| `gt(n)` | Greater than | `count\|gt(0)` |
+| `ge(n)` | Greater than or equal | `count\|ge(0)` |
+
+### Arithmetic
+
+| Filter | Description | Example |
+|---|---|---|
+| `inc(n)` | Add | `count\|inc(1)` |
+| `dec(n)` | Subtract | `count\|dec(1)` |
+| `mul(n)` | Multiply | `price\|mul(1.1)` |
+| `div(n)` | Divide | `total\|div(100)` |
+| `mod(n)` | Modulo | `index\|mod(2)` |
+
+### Number Formatting
+
+| Filter | Description | Example |
+|---|---|---|
+| `fix(n)` | Fixed decimal places | `price\|fix(2)` → `"100.00"` |
+| `round(n?)` | Round | `value\|round(2)` |
+| `floor(n?)` | Floor | `value\|floor` |
+| `ceil(n?)` | Ceiling | `value\|ceil` |
+| `locale(loc?)` | Locale number format | `count\|locale` / `count\|locale(ja-JP)` |
+| `percent(n?)` | Percentage format | `ratio\|percent(1)` |
+
+### String
+
+| Filter | Description | Example |
+|---|---|---|
+| `uc` | Upper case | `name\|uc` |
+| `lc` | Lower case | `name\|lc` |
+| `cap` | Capitalize | `name\|cap` |
+| `trim` | Trim whitespace | `text\|trim` |
+| `slice(n)` | Slice string | `text\|slice(5)` |
+| `substr(start, length)` | Substring | `text\|substr(0,10)` |
+| `pad(n, char?)` | Pad start | `id\|pad(5,0)` → `"00001"` |
+| `rep(n)` | Repeat | `text\|rep(3)` |
+| `rev` | Reverse | `text\|rev` |
+
+### Type Conversion
+
+| Filter | Description | Example |
+|---|---|---|
+| `int` | Parse integer | `input\|int` |
+| `float` | Parse float | `input\|float` |
+| `boolean` | To boolean | `value\|boolean` |
+| `number` | To number | `value\|number` |
+| `string` | To string | `value\|string` |
+| `null` | To null | `value\|null` |
+
+### Date / Time
+
+| Filter | Description | Example |
+|---|---|---|
+| `date(loc?)` | Date format | `timestamp\|date` / `timestamp\|date(ja-JP)` |
+| `time(loc?)` | Time format | `timestamp\|time` |
+| `datetime(loc?)` | Date + Time | `timestamp\|datetime(en-US)` |
+| `ymd(sep?)` | YYYY-MM-DD | `timestamp\|ymd` / `timestamp\|ymd(/)` |
+
+### Boolean / Default
+
+| Filter | Description | Example |
+|---|---|---|
+| `truthy` | Truthy check | `value\|truthy` |
+| `falsy` | Falsy check | `value\|falsy` |
+| `defaults(v)` | Fallback value | `name\|defaults(Anonymous)` |
+
+### Filter Chaining
+
+Filters can be chained with `|`:
+
+```html
+<div data-wcs="textContent: price|mul(1.1)|round(2)|locale(ja-JP)"></div>
+```
+
+## Web Component Binding
+
+`@wcstack/state` supports bidirectional state binding with custom elements using Shadow DOM or Light DOM.
+
+Many frameworks use patterns like prop drilling, context providers, or external stores (Redux, Pinia) to share state across components. `@wcstack/state` takes a different approach: parent and child components are connected through **path contracts** — the parent binds an outer state path to an inner component property via `data-wcs`, and the child simply reads and writes its own state as usual:
+
+1. The child references and updates the parent's state through its own state proxy — no props, no events, no awareness of the parent.
+2. When the parent's state changes, the Proxy `set` trap automatically notifies any child bindings that reference the affected path.
+3. Because the only coupling is the **path name**, both sides remain loosely coupled and independently testable.
+4. The cost is path resolution (cached at O(1) after first access) plus change propagation through the dependency graph.
+
+This provides a lightweight approach to cross-component state management based on path resolution rather than component-level abstractions.
+
+### Component Definition (Shadow DOM)
+
+```javascript
+class MyComponent extends HTMLElement {
+  state = { message: "" };
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: "open" });
+    this.shadowRoot.innerHTML = `
+      <wcs-state bind-component="state"></wcs-state>
+      <div>{{ message }}</div>
+      <input type="text" data-wcs="value: message" />
+    `;
+  }
+}
+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.
+
+```javascript
+class MyLightComponent extends HTMLElement {
+  state = { message: "" };
+
+  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" />
+    `;
+  }
+}
+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
+
+### Host Usage
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      user: { name: "Alice" }
+    };
+  </script>
+</wcs-state>
+
+<!-- Bind component's state.message to outer user.name -->
+<my-component data-wcs="state.message: user.name"></my-component>
+```
+
+- `bind-component="state"` maps the component's `state` property to `<wcs-state>`
+- `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
+
+### 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`.
+
+```javascript
+class MyComponent extends HTMLElement {
+  state = Object.freeze({
+    message: "Hello, World!"
+  });
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: "open" });
+  }
+
+  connectedCallback() {
+    this.shadowRoot.innerHTML = `
+      <wcs-state bind-component="state"></wcs-state>
+      <div>{{ message }}</div>
+    `;
+  }
+
+  async $stateReadyCallback(stateProp) {
+    console.log("state ready:", stateProp); // "state"
+  }
+}
+customElements.define("my-component", MyComponent);
+```
+
+- Initial component `state` can be defined with `Object.freeze(...)` (it is replaced with a writable reactive state after injection)
+- `bind-component="state"` exposes `this.state` as a state proxy powered by `@wcstack/state`
+- Assignments like `this.state.message = "..."` immediately update `{{ message }}` inside Shadow DOM
+- `async $stateReadyCallback(stateProp)` is called right after component state becomes ready for use (`stateProp` is the property name from `bind-component`)
+
+### Constraints
+
+- `<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`)
+
+### Loop with Components
+
+```html
+<template data-wcs="for: users">
+  <my-component data-wcs="state.message: .name"></my-component>
+</template>
+```
+
+## Declarative Custom Components (DCC)
+
+Define custom elements **entirely in HTML** — no JavaScript class definition needed. Using `data-wc-definition` and Declarative Shadow DOM (`<template shadowrootmode>`), you can declare reusable components with reactive state inline.
+
+### Basic Definition
+
+```html
+<!-- 1. Define the component (hidden by CSS) -->
+<my-counter data-wc-definition>
+  <template shadowrootmode="open">
+    <p>{{ count }}</p>
+    <button data-wcs="onclick: increment">+1</button>
+    <wcs-state>
+      <script type="module">
+        export default {
+          count: 0,
+          increment() { this.count++; },
+          $bindables: ["count"]
+        };
+      </script>
+    </wcs-state>
+  </template>
+</my-counter>
+
+<!-- 2. Use it — each instance gets its own state -->
+<my-counter></my-counter>
+<my-counter></my-counter>
+```
+
+When `<wcs-state>` detects it is inside a `data-wc-definition` host, it:
+
+1. Loads the state object (from `<script type="module">` or `src="*.js"`)
+2. Generates a custom element class with getter/setter/method properties on the prototype
+3. Registers it via `customElements.define()`
+
+The definition element is hidden; each instance clones the template into its own Shadow DOM and initializes its own `<wcs-state>`.
+
+### Recommended CSS
+
+```css
+:not(:defined) { display: none; }
+[data-wc-definition] { display: none; }
+```
+
+### `$bindables` and wc-bindable Protocol
+
+The `$bindables` array declares which state properties are exposed as component properties with change events, following the [wc-bindable protocol](https://github.com/nicenemo/nicenemo/blob/main/docs/wc-bindable-protocol.md):
+
+```javascript
+export default {
+  count: 0,
+  increment() { this.count++; },
+  $bindables: ["count"]
+};
+```
+
+This generates:
+
+- `static wcBindable` on the class — protocol metadata for framework adapters
+- Getter/setter on the prototype — reads/writes go through the reactive proxy
+- `CustomEvent` dispatch — `my-counter:count-changed` fires on every mutation
+
+### Binding to DCC Properties
+
+Other `<wcs-state>` instances can bind to DCC properties just like any Web Component:
+
+```html
+<my-counter data-wcs="count: parentCount"></my-counter>
+
+<wcs-state>
+  <script type="module">
+    export default { parentCount: 0 };
+  </script>
+</wcs-state>
+<div data-wcs="textContent: parentCount"></div>
+```
+
+### Shadow Root Mode
+
+Both `open` and `closed` modes are supported:
+
+```html
+<my-component data-wc-definition>
+  <template shadowrootmode="closed">
+    <!-- closed shadow DOM -->
+  </template>
+</my-component>
+```
+
+### Internal Properties
+
+Properties prefixed with `$` are internal and not exposed on the component prototype:
+
+| Property | Purpose |
+|----------|---------|
+| `$bindables` | Declares observable properties |
+| `$connectedCallback` | Lifecycle hook (runs on each instance) |
+| `$disconnectedCallback` | Cleanup hook |
+| `$updatedCallback` | Called after state mutations |
+
+## SVG Support
+
+All bindings work inside `<svg>` elements. Use `attr.*` for SVG attributes:
+
+```html
+<svg width="200" height="100">
+  <template data-wcs="for: points">
+    <circle data-wcs="attr.cx: .x; attr.cy: .y; attr.fill: .color" r="5" />
+  </template>
+</svg>
+```
+
+## Lifecycle Hooks
+
+State objects can define `$connectedCallback`, `$disconnectedCallback`, and `$updatedCallback` for initialization, cleanup, and update lifecycle handling.
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      timer: null,
+      count: 0,
+
+      // Called when <wcs-state> is connected to the DOM
+      async $connectedCallback() {
+        const res = await fetch("/api/initial-count");
+        this.count = await res.json();
+        this.timer = setInterval(() => { this.count++; }, 1000);
+      },
+
+      // Called when <wcs-state> is disconnected from the DOM (sync only)
+      $disconnectedCallback() {
+        clearInterval(this.timer);
+      }
+    };
+  </script>
+</wcs-state>
+```
+
+| Hook | Timing | Async |
+|---|---|---|
+| `$connectedCallback` | After state initialization on first connect; on every reconnect thereafter | Yes (awaited) |
+| `$disconnectedCallback` | When the element is removed from the DOM | No (sync only) |
+| `$updatedCallback(paths, indexesListByPath)` | After state updates are applied | Yes (not awaited) |
+
+All hooks except `$disconnectedCallback` support `async` — you can use `async/await` in any of them. Since the reactive proxy detects every property assignment as a change, standard `async/await` with direct property updates is sufficient for asynchronous operations — loading flags, fetched data, and error messages are all just property assignments, without requiring additional abstractions for async state management.
+
+- `this` inside hooks is the state proxy with full read/write access
+- `$connectedCallback` is called **every time** the element is connected (including re-insertion after removal), making it suitable for setup that should be re-established
+- `$disconnectedCallback` is called synchronously — use it for cleanup such as clearing timers, removing event listeners, or releasing resources
+- `$updatedCallback(paths, indexesListByPath)` receives the updated path list. For wildcard updates, `indexesListByPath` contains the updated index sets. Can be `async`, but the return value is not awaited
+- In Web Components, define `async $stateReadyCallback(stateProp)` to receive a hook when the bound state becomes available via `bind-component`
+
+## Configuration
+
+Pass a partial configuration object to `bootstrapState()`:
+
+```javascript
+import { bootstrapState } from '@wcstack/state';
+
+bootstrapState({
+  locale: 'ja-JP',
+  debug: true,
+  enableMustache: false,
+  tagNames: { state: 'my-state' },
+});
+```
+
+All options with defaults:
+
+| Option | Default | Description |
+|---|---|---|
+| `bindAttributeName` | `'data-wcs'` | Binding attribute name |
+| `tagNames.state` | `'wcs-state'` | State element tag name |
+| `locale` | `'en'` | Default locale for filters |
+| `debug` | `false` | Debug mode |
+| `enableMustache` | `true` | Enable `{{ }}` syntax |
+
+## TypeScript Support
+
+`defineState()` wraps your state object and provides type-safe `this` inside methods and getters — with zero runtime cost (identity function).
+
+```typescript
+import { defineState } from '@wcstack/state';
+
+export default defineState({
+  count: 0,
+  users: [] as { name: string; age: number }[],
+
+  increment() {
+    this.count++;            // ✅ number
+    this["users.*.name"];    // ✅ string (dot-path resolution)
+    this.$getAll("users.*.age", []); // ✅ API method
+  },
+
+  get "users.*.ageCategory"() {
+    return this["users.*.age"] < 25 ? "Young" : "Adult";
+  }
+});
+```
+
+Utility types `WcsPaths<T>` and `WcsPathValue<T, P>` are also exported for advanced use cases. See [docs/define-state.md](docs/define-state.md) for full documentation.
+
+## API Reference
+
+### `bootstrapState()`
+
+Initialize the state system. Registers `<wcs-state>` custom element and sets up DOM content loaded handler.
+
+```javascript
+import { bootstrapState } from '@wcstack/state';
+bootstrapState();
+```
+
+### `<wcs-state>` Element
+
+| Attribute | Description |
+|---|---|
+| `name` | State name (default: `"default"`) |
+| `state` | ID of a `<script type="application/json">` element |
+| `src` | URL to `.json` or `.js` file |
+| `json` | Inline JSON string |
+| `bind-component` | Property name for web component binding |
+
+### IStateElement
+
+| 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 |
+| `setterPaths` | Set of paths defined as setters |
+| `createState(mutability, callback)` | Create a state proxy (`"readonly"` or `"writable"`) |
+| `createStateAsync(mutability, callback)` | Async version of `createState` |
+| `setInitialState(state)` | Set state programmatically (before initialization) |
+| `bindProperty(prop, descriptor)` | Define a property on the raw state object |
+| `nextVersion()` | Increment and return version number |
+
+## Architecture
+
+```
+bootstrapState()
+  └── registerComponents()              // Register <wcs-state> custom element
+
+<wcs-state> connectedCallback
+  ├── _initializeBindWebComponent()     // bind-component: get state from parent component
+  ├── _initialize()                     // Load state (state attr / src / json / script / API)
+  │     └── setStateElementByName()     // Register to WeakMap<Node, Map<name, element>>
+  │           └── (first registration per rootNode)
+  │                 └── queueMicrotask → buildBindings()
+  ├── _callStateConnectedCallback()     // Call $connectedCallback if defined
+
+buildBindings(root)
+  ├── waitForStateInitialize()          // Wait for all <wcs-state> initializePromise
+  ├── convertMustacheToComments()       // {{ }} → comment nodes
+  ├── collectStructuralFragments()      // Collect for/if templates
+  └── initializeBindings()              // Walk DOM, parse data-wcs, set up bindings
+```
+
+### Reactivity Flow
+
+1. State changes via Proxy `set` trap → `setByAddress()`
+2. Address resolved → updater enqueues absolute address
+3. Dependency walker invalidates (dirties) downstream caches
+4. Updater applies changes to bound DOM nodes via `applyChangeFromBindings()`
+
+### State Address System
+
+Paths like `users.*.name` are decomposed into:
+
+- **PathInfo** — static path metadata (segments, wildcard count, parent path)
+- **ListIndex** — runtime loop index chain
+- **StateAddress** — combination of PathInfo + ListIndex
+- **AbsoluteStateAddress** — state name + StateAddress (for cross-state references)
+
+## Server-Side Rendering
+
+`@wcstack/state` supports SSR via the companion [`@wcstack/server`](../server/) package. The same templates you write for the client render on the server — no changes needed.
+
+### Quick Setup
+
+1. Add `enable-ssr` to your `<wcs-state>` element:
+
+```html
+<wcs-state enable-ssr>
+  <script type="module">
+    export default {
+      items: [],
+      async $connectedCallback() {
+        const res = await fetch("/api/items");
+        this.items = await res.json();
+      }
+    };
+  </script>
+</wcs-state>
+<template data-wcs="for: items">
+  <div data-wcs="textContent: items.*.name"></div>
+</template>
+```
+
+2. Render on the server:
+
+```javascript
+import { renderToString } from "@wcstack/server";
+
+const html = await renderToString(template, {
+  baseUrl: "http://localhost:3000"
+});
+```
+
+That's it. The client-side `@wcstack/state` automatically detects the `<wcs-ssr>` element, restores state from the JSON snapshot, and resumes reactivity without re-rendering.
+
+### How It Works
+
+| Phase | What happens |
+|-------|-------------|
+| **Server** | `renderToString()` runs your template in happy-dom, executes `$connectedCallback` (including `fetch()`), applies all bindings, and outputs rendered HTML with a `<wcs-ssr>` element containing hydration data |
+| **Client** | `<wcs-state enable-ssr>` loads state from `<wcs-ssr>` JSON, skips `$connectedCallback`, and `hydrateBindings()` wires up reactivity on the existing DOM |
+| **Fallback** | If server/client versions mismatch, the SSR DOM is cleaned up and `buildBindings()` runs a full client-side render |
+
+### What `enable-ssr` Does
+
+| Context | Behavior |
+|---------|----------|
+| **Server** (`renderToString`) | Generates `<wcs-ssr>` with state JSON, template fragments, and property data |
+| **Client** (hydration) | Reads `<wcs-ssr>`, restores state, skips `$connectedCallback`, hydrates bindings on existing DOM |
+
+See [`@wcstack/server` README](../server/README.md) for full API documentation.
+
+## License
+
+MIT