@wcstack/state 1.24.0 → 1.26.0

package/README.ja.md

@@ -220,6 +220,8 @@
 
 解決順序: `state` → `src` (.json / .js) → `json` → 内包 `<script>` → `setInitialState()` 待機。
 
+> **Content-Security-Policy 下では:** 5 番（内包 `<script type="module">`）は `blob:` URL 経由で評価されるため `script-src blob:` が必要です。ページの nonce では救えません。厳格な CSP を敷く場合は 4 番（`src="./state.js"`）を使ってください。追加ディレクティブは不要です。詳細は [docs/csp.md](../../docs/csp.md)。
+
 ### 名前付き状態
 
 複数の状態要素を `name` 属性で共存できます。バインディングでは `@name` で参照します：
@@ -507,7 +509,42 @@ export default {
 </template>
 ```
 
-`for:` ディレクティブは**値ベースの差分アルゴリズム**を使用します。配列の各要素の値そのものが識別キーとして機能するため、React の `key` や Vue の `:key` のような明示的なキー属性は不要です。配列が再代入されると、差分アルゴリズムが新旧の要素を値で照合し、変更のない要素の DOM ノードを再利用しつつ、追加・削除・並び替えを効率的に処理します。
+`for:` ディレクティブは**値ベースの差分アルゴリズム**を使用します。配列の各要素の値そのものが識別キーとして機能します。配列が再代入されると、差分アルゴリズムが新旧の要素を値で照合し、変更のない要素の DOM ノードを再利用しつつ、追加・削除・並び替えを効率的に処理します。
+
+つまり、**行オブジェクトの参照さえ保たれていれば、行の追加・削除・並べ替えに明示的なキー属性（React の `key` や Vue の `:key`）は不要です**。非破壊の配列メソッド（`toSorted` / `toReversed` / `filter` / `with` / `toSpliced`）はいずれも要素の参照を保つため、ソートやフィルタは構造的に keyed に動作し、「キーの付け方を間違える」種類のバグが原理的に発生しません。
+
+例外は、**新しく生成されたオブジェクトとして届くデータ**です。`fetch(...).json()`、ストレージからの `JSON.parse`、WebSocket / SSE の全件スナップショット、Worker の `postMessage` などがこれにあたります。これらの行は参照で照合できないため、全行が破棄・再構築されます。次の [`$listKeys`](#listkeys--再取得された行の同一性) を参照してください。
+
+#### `$listKeys` — 再取得された行の同一性
+
+行がバインディングの管理外の DOM 状態（フォーカス、IME 変換中の文字列、`<details>` の開閉、行内スクロール位置、`<canvas>` の描画内容、`<video>` の再生位置）を持つ場合、行の再構築でそれらは失われます。キーを宣言すると、リフレッシュをまたいで行を同定できます：
+
+```js
+{
+  items: [],
+  $listKeys: {
+    "items": "id",                        // フィールド名
+    "items.*.children": (row) => row.uid, // 複合キー用の関数も可
+  },
+}
+```
+
+キーを宣言すると、新しい配列を代入しても**既存の行オブジェクトが据え置かれ**、実際に変化したフィールドだけがそこへ書き込まれます。行の DOM は再構築されず再利用されます：
+
+```js
+// 行オブジェクトはすべて新しいが id で照合されるため、DOM・フォーカス・
+// <details> の状態は保たれ、差分のあるフィールドだけが書き込まれる
+this.items = await (await fetch("/api/items")).json();
+```
+
+補足：
+
+- **opt-in かつパス単位**です。宣言していないリストは従来どおりの挙動で、追加コストもありません。
+- **ネストも opt-in** です。宣言されたパスだけがキー照合され、未宣言のネスト配列は従来どおり参照置換されます。リスト単位で段階的に導入できます。
+- **無変化のリフレッシュはゼロコスト**です。何も変わっていなければフィールド書き込みも DOM 操作も一切発生しません。
+- **行は plain object** である必要があり、キーは存在かつ一意でなければなりません。キーの重複・欠落・クラスインスタンスは、静かに劣化させず即座にエラーになります。
+- **行から消えたフィールドは `null` でクリア**されます。`null` はこのパッケージにおける明示的なクリアの語彙です（`undefined` は「状態が値を持たない」を意味し、書き込み自体がスキップされます）。
+- 格納される配列は照合済みの行オブジェクトから組み直されるため、代入後は `this.items !== 代入した配列` になります。
 
 #### ドット省略記法
 
@@ -1156,6 +1193,34 @@ customElements.define("my-component", MyComponent);
 </template>
 ```
 
+### コンポーネント側でリストを描画する
+
+配列をコンポーネントに束ね、`for:` をコンポーネントの内側で回すこともできます。
+値の正本は外側の状態のままで、行の追加・削除・並べ替え・行フィールドの書き込みは双方向に届きます。
+
+```html
+<!-- ホスト側 -->
+<wcs-state json='{"rows":[{"name":"Alice"},{"name":"Bob"}]}'></wcs-state>
+<my-list data-wcs="state.items: rows"></my-list>
+```
+
+```javascript
+// コンポーネント側（Shadow DOM）
+this.shadowRoot.innerHTML = `
+  <wcs-state bind-component="state"></wcs-state>
+  <ul>
+    <template data-wcs="for: items">
+      <li data-wcs="textContent: .name"></li>
+    </template>
+  </ul>
+`;
+```
+
+- ホストが `rows` を差し替えても、行フィールド（`rows.0.name`）だけを書いても、コンポーネント内の行に反映されます
+- コンポーネント側から `items.*.name` を書き戻すと、ホストの `rows` に届きます
+- **制限**: コンポーネント自身がホスト側の `for` の中にあり、さらにコンポーネント内でも `for` を回す
+  入れ子構成には対応していません（内外の行の対応付けが決まらないため）
+
 ## Command Token（メソッドバインディング）
 
 プロパティバインディング（`state.message: user.name`）はコンポーネントへ流れ込むデータを扱いますが、**state からコンポーネントのメソッドを起動する**こと —— `<wcs-fetch>.fetch()`、`<wcs-dialog>.open()` など —— はカバーしません。**command token** は型付きの pub/sub チャネルでこの隙間を埋めます：
@@ -1455,6 +1520,8 @@ event token は command token と同じ `Token` pub/sub プリミティブを共
 
 command token / event token が運ぶのは離散的なやり取りです。**`$streams`** は残る形 —— 連続的なフローをカバーします。非同期 producer（async iterable / async generator / `ReadableStream`）を宣言すると、フレームワークがそれを **fold して単一の reactive プロパティに畳み込みます** —— 各チャンクは通常のパス代入を通るため、バインディング・パス getter・`$updatedCallback` は自分で値を代入した場合とまったく同じように反応します。`args` 関数が読んだ state パスが変化すると、実行中の producer は abort され、新しい引数で source が張り直されます（switchMap 型の依存駆動 restart）。stream は `$connectedCallback` 完了後に eager に起動し、要素の disconnect で abort されます。
 
+`$updatedCallback` は引き続き binding 駆動です。stream 宣言だけでは headless な購読にならず、その value/status/error の live DOM binding が実際に適用されたときだけ callback の path に現れます。現行 API に state-only な `$watch` / `$effects` 宣言はありません。観測契約は [stream リファレンス](docs/streams.md) を参照してください。
+
 ```html
 <wcs-state>
   <script type="module">
@@ -1576,6 +1643,24 @@ chip.payload = null          → element.data = null かつ removeAttribute("dat
 - ミラーはベストエフォート: `setAttribute` の失敗は握りつぶされ（`debug` 警告付き）、プロパティ書き込みをブロックしない
 - ネイティブ HTML 要素は `inputs` を完全に無視する —— ミラーは `static wcBindable` を公開するカスタム要素でのみ有効になる
 
+## コンポーネント機構の選び方
+
+カスタム要素に独自の状態を持たせる機構は 2 つあり、**排他**です。コンポーネントごとにどちらか一方を選びます。
+
+| | [DCC](#宣言的カスタムコンポーネント-dcc) | [`bind-component`](#web-component-バインディング) |
+|---|---|---|
+| 要素の定義方法 | HTML だけ（`data-wc-definition` + Declarative Shadow DOM） | 自分で書く `class extends HTMLElement` |
+| 状態の在処 | テンプレート内のインライン `<script type="module">`（インスタンスごとにロード） | コンポーネントインスタンスのプロパティ（`this.state`） |
+| `static wcBindable` | `$bindables` / `$commands` から生成 | **無し** — wc-bindable の producer ではない |
+| 親から値をバインド | `count: parentCount`（双方向・変更イベントあり） | `state.msg: user.name`（パスマッピング） |
+| 親からメソッド起動 | `command.bumpBy: $command.bump` | 不可 — クラス側に公開して自分で呼ぶ |
+| spread（`...: obj`） | 使える | 使えない（`wcBindable` 宣言が必要） |
+| コンポーネント自身の読み書き | 要素の `this.count` | `this.state.msg` |
+
+判断の目安は「**JavaScript クラスが無いなら DCC、既にクラスを書いているなら `bind-component`**」です。併用はエラーになります。`data-wc-definition` ホストの中に `<wcs-state bind-component>` を置くのは設定ミスです — DCC の状態はテンプレートに属し、インスタンスごとにロードされるためです。
+
+`bind-component` のコンポーネントが wc-bindable プロトコルの外に留まっているのは意図的です。宣言されたプロパティ面ではなく**パス**で配線するのがこの機構だからで、`wcBindable` 宣言を必要とする spread と command token が使えないのはその帰結です。
+
 ## 宣言的カスタムコンポーネント (DCC)
 
 JavaScript のクラス定義なしで、**HTML だけ**でカスタム要素を定義できます。`data-wc-definition` と Declarative Shadow DOM (`<template shadowrootmode>`) を使い、リアクティブな状態を持つ再利用可能なコンポーネントをインラインで宣言します。
@@ -1620,23 +1705,55 @@ JavaScript のクラス定義なしで、**HTML だけ**でカスタム要素を
 [data-wc-definition] { display: none; }
 ```
 
-### `$bindables` と wc-bindable プロトコル
+### `$bindables` / `$commands` と wc-bindable プロトコル
 
-`$bindables` 配列は、変更イベント付きのコンポーネントプロパティとして公開する状態プロパティを宣言します。[wc-bindable プロトコル](https://github.com/nicenemo/nicenemo/blob/main/docs/wc-bindable-protocol.md)に準拠しています：
+`$bindables` は変更イベント付きのコンポーネント**プロパティ**として公開する状態プロパティを、`$commands` は起動可能な**コマンド**として公開する状態メソッドを宣言します。この 2 つで [wc-bindable プロトコル](https://github.com/nicenemo/nicenemo/blob/main/docs/wc-bindable-protocol.md)の宣言が組み立てられます：
 
 ```javascript
 export default {
   count: 0,
-  increment() { this.count++; },
-  $bindables: ["count"]
+  bumpBy(step) { this.count += step; },
+  $bindables: ["count"],
+  $commands: ["bumpBy"]
 };
 ```
 
 これにより以下が生成されます：
 
-- クラスの `static wcBindable` — フレームワークアダプタ用のプロトコルメタデータ。各 `$bindables` メンバは `properties` と `inputs` の両方に宣言され（双方向）、方向認識初期同期の下でも親 state → DCC の書き込みが機能します — [バインディング authority](#バインディング-authority-init--sync) 参照
-- プロトタイプの getter/setter — リアクティブプロキシ経由で読み書き
-- `CustomEvent` のディスパッチ — 値が変更されるたびに `my-counter:count-changed` が発火
+- クラスの `static wcBindable` — フレームワークアダプタ用のプロトコルメタデータ。各 `$bindables` メンバは `properties` と `inputs` の両方に宣言され（双方向）、方向認識初期同期の下でも親 state → DCC の書き込みが機能します — [バインディング authority](#バインディング-authority-init--sync) 参照。各 `$commands` メンバは `commands` エントリになります
+- `$bindables` はプロトタイプの getter/setter、`$commands` はメソッド — いずれもリアクティブプロキシ経由
+- `CustomEvent` のディスパッチ — `$bindables` メンバが変更されるたびに `my-counter:count-changed` が発火
+
+`commands` エントリは常に `async: true` です。DCC のメソッドは内側の `<wcs-state>` の初期化に chain するため、状態側のメソッドが `async` でなくても戻り値は Promise になります。
+
+どちらの宣言もコンポーネント定義時に `$commandTokens` と同じ強度で検証されます。次はいずれもエラーになります。
+
+- 配列でない
+- 非空文字列でないエントリ
+- `$` 始まりのエントリ（内部プロパティはコンポーネントの prototype に公開されません）
+- 重複したエントリ — これは従来サイレントに壊れていました。重複名があると `wcBindable` 宣言全体が読み取り不能になり、その要素が黙って双方向バインド不可になります
+- 状態に存在しないエントリ（自身とプロトタイプチェーンの両方を探索します。`$streams` の名前は値プロパティがインスタンスごとに実体化されるため「存在する」と見なされます）
+- `$bindables` にメソッドを書いた場合、または `$commands` に値プロパティを書いた場合
+
+### DCC のメソッドを起動する
+
+`$commands` メンバは、I/O ノードと同じように親 state から [command token](#command-tokenメソッドバインディング) で起動できます：
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["bump"],
+      fire() { this.$command.bump.emit(3); }
+    };
+  </script>
+</wcs-state>
+
+<button data-wcs="onclick: fire">bump</button>
+<my-counter data-wcs="command.bumpBy: $command.bump"></my-counter>
+```
+
+位置引数はそのまま素通しされるので、`emit(3)` はコンポーネント側の状態の `bumpBy(3)` を呼びます。
 
 ### DCC プロパティへのバインディング
 
@@ -1672,6 +1789,7 @@ export default {
 | プロパティ | 用途 |
 |----------|---------|
 | `$bindables` | 観測可能プロパティの宣言 |
+| `$commands` | 起動可能メソッドの宣言 |
 | `$connectedCallback` | ライフサイクルフック（各インスタンスで実行） |
 | `$disconnectedCallback` | クリーンアップフック |
 | `$updatedCallback` | 状態変更後に呼ばれる |
@@ -1719,14 +1837,14 @@ export default {
 |---|---|---|
 | `$connectedCallback` | 初回接続時は状態初期化後、再接続時は毎回呼び出し | 可（await される） |
 | `$disconnectedCallback` | 要素が DOM から削除された時 | 不可（同期のみ） |
-| `$updatedCallback(paths, indexesListByPath)` | 状態変更が適用された後に呼び出し | 可（await されない） |
+| `$updatedCallback(paths, indexesListByPath)` | live binding に更新が適用された後に呼び出し | 可（await されない） |
 
 `$disconnectedCallback` を除くすべてのフックで `async` を使用できます。リアクティブ Proxy はすべてのプロパティへの代入を変更として検知します。そのため、標準の `async/await` による処理とプロパティへの直接代入だけで非同期ロジックが完結します。ローディングフラグの切り替え、取得したデータの格納、エラーメッセージの更新といった処理もすべて単なるプロパティ代入で行えるため、非同期状態を管理するための複雑な抽象化機能は必要ありません。
 
 - フック内の `this` は読み書き可能な状態プロキシです。
 - `$connectedCallback` は要素が接続される**たびに**呼ばれます（一度削除された後の再接続も含みます）。再確立が必要なセットアップ処理に適しています。
 - `$disconnectedCallback` は同期的に呼び出されます。タイマーのクリア、イベントリスナーの削除、リソースの解放といったクリーンアップ処理に使用してください。
-- `$updatedCallback(paths, indexesListByPath)` は更新された状態パスの一覧を受け取ります。ワイルドカードをもつパスが更新された場合は、`indexesListByPath` から対象のインデックス情報も取得可能です。`async` を使用できますが、戻り値は await されません。
+- `$updatedCallback(paths, indexesListByPath)` は、その drain で live binding が適用された path の一覧を受け取ります。binding のない state 書き込みでは呼ばれず、`paths` にも現れません。ワイルドカードをもつパスが更新された場合は、`indexesListByPath` から対象のインデックス情報も取得可能です。`async` を使用できますが、戻り値は await されません。
 - Web Component を使用している場合は、コンポーネント側に `async $stateReadyCallback(stateProp)` を定義おくことで、`bind-component` でバインドした状態が利用可能になった瞬間にフックとして呼び出されます。
 
 ## 設定

package/README.md

@@ -220,6 +220,8 @@ That's it. No build, no bootstrap code, no framework.
 
 Resolution order: `state` → `src` (.json / .js) → `json` → inner `<script>` → wait for `setInitialState()`.
 
+> **Under a Content-Security-Policy:** form 5 (inline `<script type="module">`) is evaluated through a `blob:` URL and therefore requires `script-src blob:`. A page nonce does not cover it. If you enforce a strict CSP, use form 4 (`src="./state.js"`) instead — it needs no extra directive. See [docs/csp.md](../../docs/csp.md).
+
 ### Named State
 
 Multiple state elements can coexist with the `name` attribute. Bindings reference them with `@name`:
@@ -507,7 +509,42 @@ Structural directives use `<template>` elements:
 </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.
+The `for:` directive uses a **value-based diff algorithm** — each array element's value itself serves as the identity 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.
+
+This means **no explicit `key` attribute is needed for adding, removing, or reordering rows** (like React's `key` or Vue's `:key`) — as long as row objects keep their references. Non-destructive array methods (`toSorted`, `toReversed`, `filter`, `with`, `toSpliced`) all preserve element references, so sorting and filtering are keyed by construction, and the whole class of "wrong key" bugs cannot occur.
+
+The exception is data that arrives as **freshly created objects** — `fetch(...).json()`, `JSON.parse` from storage, a WebSocket/SSE full snapshot, or a Worker `postMessage`. Those rows never match by reference, so every row is torn down and rebuilt. See [`$listKeys`](#listkeys--identity-for-refetched-rows) below.
+
+#### `$listKeys` — identity for refetched rows
+
+When rows carry DOM state the bindings do not own — focus, an in-flight IME composition, `<details>` open state, inner scroll position, `<canvas>` contents, `<video>` playback — rebuilding the rows loses it. Declare a key so the framework can recognize rows across a refresh:
+
+```js
+{
+  items: [],
+  $listKeys: {
+    "items": "id",                        // field name
+    "items.*.children": (row) => row.uid, // or a function, for composite keys
+  },
+}
+```
+
+With a key declared, assigning a new array **keeps the existing row objects** and writes only the fields that actually changed into them. The row's DOM is reused rather than rebuilt:
+
+```js
+// Every row object is new, but rows are matched by id — DOM, focus and
+// <details> state survive, and only the fields that differ are written.
+this.items = await (await fetch("/api/items")).json();
+```
+
+Notes:
+
+- **Opt-in and per-path.** Lists without a declaration behave exactly as before, at no cost.
+- **Nesting is opt-in too.** Only declared paths are matched by key; undeclared nested arrays are replaced by reference as usual. This lets you adopt it one list at a time.
+- **A no-op refresh is free.** If nothing changed, no field is written and no DOM work happens at all.
+- **Rows must be plain objects**, and keys must be present and unique. Duplicate keys, missing keys, and class instances raise an error immediately rather than degrading silently.
+- **Fields dropped from a row are cleared with `null`**, which is this package's vocabulary for an explicit clear (`undefined` means "the state has no opinion" and skips the write).
+- The stored array is rebuilt from matched row objects, so `this.items !== theArrayYouAssigned` afterwards.
 
 #### Dot Shorthand
 
@@ -1157,6 +1194,34 @@ customElements.define("my-component", MyComponent);
 </template>
 ```
 
+### Rendering a List Inside the Component
+
+An array can be bound into a component and iterated with `for:` **inside** it. The outer state
+stays the source of truth; row additions, removals, reordering and row-field writes flow both ways.
+
+```html
+<!-- Host -->
+<wcs-state json='{"rows":[{"name":"Alice"},{"name":"Bob"}]}'></wcs-state>
+<my-list data-wcs="state.items: rows"></my-list>
+```
+
+```javascript
+// Component (Shadow DOM)
+this.shadowRoot.innerHTML = `
+  <wcs-state bind-component="state"></wcs-state>
+  <ul>
+    <template data-wcs="for: items">
+      <li data-wcs="textContent: .name"></li>
+    </template>
+  </ul>
+`;
+```
+
+- Replacing `rows` or writing a single row field (`rows.0.name`) both reach the rows inside the component
+- Writing `items.*.name` from inside the component reaches the host's `rows`
+- **Limitation**: nesting is not supported — a component that sits inside a host `for:` *and* runs its own
+  `for:` over a mapped array has no way to relate the outer row to the inner one
+
 ## Command Token (Method Binding)
 
 Property binding (`state.message: user.name`) covers data flowing into a component, but it does not cover **invoking a method on a component from state** — `<wcs-fetch>.fetch()`, `<wcs-dialog>.open()`, and so on. **Command tokens** fill that gap with a typed pub/sub channel:
@@ -1456,6 +1521,8 @@ Event tokens share the same `Token` pub/sub primitive as command tokens — `nam
 
 Command tokens and event tokens carry discrete interactions. **`$streams`** covers the remaining shape: a continuous flow. Declare an async producer (async iterable / async generator / `ReadableStream`) and the framework **folds it into a single reactive property** — each chunk goes through normal path assignment, so bindings, path getters, and `$updatedCallback` react exactly as if you had assigned the value yourself. When a state path read by the `args` function changes, the running producer is aborted and the source is restarted with the new arguments (switchMap-style dependency-driven restart). Streams start eagerly after `$connectedCallback` completes and are aborted when the element disconnects.
 
+`$updatedCallback` remains binding-driven: a stream declaration alone is not a headless subscription. Its path appears in the callback only when a live DOM binding for that value/status/error is actually applied. There is currently no state-only `$watch` / `$effects` declaration; see the [stream reference](docs/streams.md) for the observation contract.
+
 ```html
 <wcs-state>
   <script type="module">
@@ -1577,6 +1644,24 @@ Notes:
 - Mirror is best-effort: a `setAttribute` failure is swallowed (with a `debug` warning) and does not block the property write
 - Native HTML elements ignore `inputs` entirely — the mirror only activates for custom elements that expose `static wcBindable`
 
+## Choosing a Component Mechanism
+
+Two mechanisms give a custom element its own state, and they are **mutually exclusive** — pick one per component:
+
+| | [DCC](#declarative-custom-components-dcc) | [`bind-component`](#web-component-binding) |
+|---|---|---|
+| How the element is defined | HTML only (`data-wc-definition` + Declarative Shadow DOM) | A JavaScript `class extends HTMLElement` you write |
+| Where the state lives | An inline `<script type="module">` in the template, loaded per instance | A property on the component instance (`this.state`) |
+| `static wcBindable` | Generated from `$bindables` / `$commands` | **None** — the element is not a wc-bindable producer |
+| Parent binds a value | `count: parentCount` (two-way, change events) | `state.msg: user.name` (path mapping) |
+| Parent invokes a method | `command.bumpBy: $command.bump` | Not available — expose it on the class and call it yourself |
+| Spread (`...: obj`) | Available | Not available (requires a `wcBindable` declaration) |
+| Component reads/writes its own state | `this.count` on the element | `this.state.msg` |
+
+The rule of thumb: **if the component has no JavaScript class, use DCC; if you are already writing a class, use `bind-component`.** Combining them raises — a `<wcs-state bind-component>` inside a `data-wc-definition` host is a configuration error, because DCC state belongs to the template and is loaded per instance.
+
+`bind-component` components deliberately stay outside the wc-bindable protocol: they are wired by **path**, not by a declared property surface. That is why spread and command tokens, both of which need a `wcBindable` declaration, do not apply to them.
+
 ## 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.
@@ -1621,23 +1706,55 @@ The definition element is hidden; each instance clones the template into its own
 [data-wc-definition] { display: none; }
 ```
 
-### `$bindables` and wc-bindable Protocol
+### `$bindables` / `$commands` and the 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):
+`$bindables` declares which state **properties** are exposed as component properties with change events. `$commands` declares which state **methods** are exposed as invocable commands. Together they build the [wc-bindable protocol](https://github.com/nicenemo/nicenemo/blob/main/docs/wc-bindable-protocol.md) declaration:
 
 ```javascript
 export default {
   count: 0,
-  increment() { this.count++; },
-  $bindables: ["count"]
+  bumpBy(step) { this.count += step; },
+  $bindables: ["count"],
+  $commands: ["bumpBy"]
 };
 ```
 
 This generates:
 
-- `static wcBindable` on the class — protocol metadata for framework adapters. Each `$bindables` member is declared in both `properties` and `inputs` (two-way), so parent-state → DCC writes keep working under directional initial sync — see [Binding Authority](#binding-authority-init--sync)
-- Getter/setter on the prototype — reads/writes go through the reactive proxy
-- `CustomEvent` dispatch — `my-counter:count-changed` fires on every mutation
+- `static wcBindable` on the class — protocol metadata for framework adapters. Each `$bindables` member is declared in both `properties` and `inputs` (two-way), so parent-state → DCC writes keep working under directional initial sync — see [Binding Authority](#binding-authority-init--sync). Each `$commands` member becomes a `commands` entry
+- Getter/setter on the prototype for `$bindables`, a method for `$commands` — both go through the reactive proxy
+- `CustomEvent` dispatch — `my-counter:count-changed` fires on every mutation of a `$bindables` member
+
+`commands` entries are always declared `async: true`. A DCC method chains on the inner `<wcs-state>`'s initialization, so it returns a Promise whether or not the state method itself was written `async`.
+
+Both declarations are validated when the component is defined, with the same strictness as `$commandTokens`. Each of the following raises:
+
+- not an array
+- an entry that is not a non-empty string
+- an entry starting with `$` (internal properties are never exposed on the component prototype)
+- a duplicated entry — this one used to fail silently: a duplicate name makes the whole `wcBindable` declaration unreadable, so the element would quietly stop being two-way bindable
+- an entry that does not exist on the state (own properties and the prototype chain are both searched; `$streams` names count as existing since their value properties are materialized per instance)
+- a method listed in `$bindables`, or a value property listed in `$commands`
+
+### Driving a DCC Method
+
+A `$commands` member can be invoked from the parent state with a [command token](#command-token-method-binding), exactly like an I/O node:
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["bump"],
+      fire() { this.$command.bump.emit(3); }
+    };
+  </script>
+</wcs-state>
+
+<button data-wcs="onclick: fire">bump</button>
+<my-counter data-wcs="command.bumpBy: $command.bump"></my-counter>
+```
+
+Positional arguments pass through verbatim, so `emit(3)` calls `bumpBy(3)` on the component's state.
 
 ### Binding to DCC Properties
 
@@ -1673,6 +1790,7 @@ Properties prefixed with `$` are internal and not exposed on the component proto
 | Property | Purpose |
 |----------|---------|
 | `$bindables` | Declares observable properties |
+| `$commands` | Declares invocable methods |
 | `$connectedCallback` | Lifecycle hook (runs on each instance) |
 | `$disconnectedCallback` | Cleanup hook |
 | `$updatedCallback` | Called after state mutations |
@@ -1720,14 +1838,14 @@ State objects can define `$connectedCallback`, `$disconnectedCallback`, and `$up
 |---|---|---|
 | `$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) |
+| `$updatedCallback(paths, indexesListByPath)` | After updates are applied to live bindings | 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
+- `$updatedCallback(paths, indexesListByPath)` receives the paths whose live bindings were applied in that drain. Unbound state writes do not invoke it or appear in `paths`. 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