@wcstack/state 1.26.0 → 1.28.0

package/README.ja.md

@@ -95,7 +95,7 @@
 - **宣言的データバインディング** — `data-wcs` 属性によるプロパティ / テキスト / イベント / 構造バインディング
 - **リアクティブ Proxy** — ES Proxy による依存追跡付き自動 DOM 更新
 - **構造ディレクティブ** — `<template>` 要素による `for`, `if` / `elseif` / `else`
-- **組み込みフィルタ** — フォーマット、比較、算術、日付など 40 種類
+- **組み込みフィルタ** — フォーマット、比較、算術、日付など 46 種類
 - **双方向バインディング** — `<input>`, `<select>`, `<textarea>` で自動有効
 - **Web Component バインディング** — Shadow DOM コンポーネントとの双方向状態バインディング
 - **command token** — pub/sub チャネル（`command.<method>: tokenName`）で state から wc-bindable カスタム要素のメソッドを起動
@@ -220,7 +220,7 @@
 
 解決順序: `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)。
+> **Content-Security-Policy 下では:** 5 番（内包 `<script type="module">`）は `blob:` URL 経由で評価されるため `script-src blob:` が必要です。ページの nonce では救えません。厳格な CSP を敷く場合は 4 番（`src="./state.js"`）を使ってください。追加ディレクティブは不要です。詳細は [docs/csp.ja.md](../../docs/csp.ja.md)。
 
 ### 名前付き状態
 
@@ -394,7 +394,7 @@ authority はバインディング単位で `#init=` により上書きできま
 
 - `enableDirectionalInitialSync: false`（opt-out）のとき `#init=`/`#sync=` を書くと throw します。
 - **1.20 以前からの移行：** output-only メンバに対して state 側に都合のよい初期値（`value: []`、`query: ""` 等）をシードしないでください — 要素側の実初期値（多くは `null`/`undefined`）がシードを置き換えます。シードは要素の実初期値に合わせ、表示用の値は派生 getter で null ガードしてください。
-- **1.21.x まで**、`init=element` / `init=auto` / `init=none` はバインディングの生存期間全体で state→element 書き込みを抑止しており、真に双方向なメンバには使えませんでした。現在は authority は初期同期のみを支配します（`docs/architecture-hardening/09-remediation-design.md` §3.6）。
+- **1.21.x まで**、`init=element` / `init=auto` / `init=none` はバインディングの生存期間全体で state→element 書き込みを抑止しており、真に双方向なメンバには使えませんでした。現在は authority は初期同期のみを支配します（`docs/architecture-hardening/09-remediation-design.ja.md` §3.6）。
 
 ### ラジオボタンバインディング
 
@@ -985,7 +985,7 @@ export default {
 
 ## フィルタ
 
-40 種類の組み込みフィルタが入力（DOM → 状態）と出力（状態 → DOM）の両方向で利用できます。
+46 種類の組み込みフィルタが入力（DOM → 状態）と出力（状態 → DOM）の両方向で利用できます。
 
 ### 比較
 
@@ -1008,6 +1008,8 @@ export default {
 | `mul(n)` | 乗算 | `price\|mul(1.1)` |
 | `div(n)` | 除算 | `total\|div(100)` |
 | `mod(n)` | 剰余 | `index\|mod(2)` |
+| `abs` | 絶対値 | `delta\|abs` |
+| `clamp(min, max)` | 範囲内に丸める | `ratio\|clamp(0,100)` |
 
 ### 数値フォーマット
 
@@ -1019,6 +1021,7 @@ export default {
 | `ceil(n?)` | 切り上げ | `value\|ceil` |
 | `locale(loc?)` | ロケール数値フォーマット | `count\|locale` / `count\|locale(ja-JP)` |
 | `percent(n?)` | パーセンテージフォーマット | `ratio\|percent(1)` |
+| `unit(u)` | 単位（任意の接尾辞）を付加 | `width\|unit(px)` → `"40px"` |
 
 ### 文字列
 
@@ -1033,6 +1036,8 @@ export default {
 | `pad(n, char?)` | 先頭パディング | `id\|pad(5,0)` → `"00001"` |
 | `rep(n)` | 繰り返し | `text\|rep(3)` |
 | `rev` | 反転 | `text\|rev` |
+| `truncate(n, suffix?)` | 切り詰めて省略記号を付加 | `title\|truncate(20)` → `"…"` 付き |
+| `join(sep?)` | 配列を連結（既定 `", "`） | `tags\|join` / `tags\|join(/)` |
 
 ### 型変換
 
@@ -1053,6 +1058,7 @@ export default {
 | `time(loc?)` | 時刻フォーマット | `timestamp\|time` |
 | `datetime(loc?)` | 日付 + 時刻 | `timestamp\|datetime(en-US)` |
 | `ymd(sep?)` | YYYY-MM-DD | `timestamp\|ymd` / `timestamp\|ymd(/)` |
+| `hms(sep?)` | HH:MM:SS | `timestamp\|hms` / `timestamp\|hms(-)` |
 
 ### 真偽値 / デフォルト
 
@@ -1125,6 +1131,18 @@ customElements.define("my-light-component", MyLightComponent);
 - バインディングでは `@my-light` のように状態名を明示的に参照する必要があります
 - `<wcs-state>` はコンポーネント要素の直下に配置する必要があります
 
+- ホスト側からのバインド（`<my-light-component data-wcs="state.message: user.name">`）も
+  Shadow DOM 形と同様に使えます。コンポーネントのサブツリーは**独立したバインディングスコープ**
+  として扱われ、コンポーネント側の状態が名前登録を終えてから配線されます
+
+> **注意**: Light DOM は名前空間を上位スコープと共有するため、**同じ `name` を持つインスタンスを
+> 同一スコープに複数置くことはできません**。リストの行ごとにコンポーネントを配置するような形は
+> Shadow DOM を使ってください。
+>
+> また `State.getBindingsReady(root)` はコンポーネントのスコープを含みません（Shadow DOM 形で
+> 子が別 rootNode にあるのと同じ扱いです）。コンポーネント内部の描画完了まで待ちたい場合は、
+> コンポーネント側の `<wcs-state>` の初期化を待ってください。
+
 ### ホスト側の使用方法
 
 ```html
@@ -1218,8 +1236,20 @@ this.shadowRoot.innerHTML = `
 
 - ホストが `rows` を差し替えても、行フィールド（`rows.0.name`）だけを書いても、コンポーネント内の行に反映されます
 - コンポーネント側から `items.*.name` を書き戻すと、ホストの `rows` に届きます
-- **制限**: コンポーネント自身がホスト側の `for` の中にあり、さらにコンポーネント内でも `for` を回す
-  入れ子構成には対応していません（内外の行の対応付けが決まらないため）
+
+#### 入れ子とスコープの重ね方
+
+コンポーネント自身がホスト側の `for` の中にあり、**さらにコンポーネント内でも `for` を回す**入れ子構成にも対応しています。外側の行と内側の行の対応はフレームワークが保ちます：
+
+```html
+<template data-wcs="for: groups">
+  <my-list data-wcs="state.items: groups.*.children"></my-list>
+</template>
+```
+
+コンポーネントの中にさらにコンポーネントを置いて、**スコープを重ねる**こともできます。途中のコンポーネントが配列を素通しするだけで自分では `for` を回さなくても、正本スコープ起点の行フィールド書き込みは最下層の行まで届きます。
+
+コンポーネントの作者が自分の置かれる深さを意識する必要はありません。`$1` / イベントハンドラのインデックス / `$updatedCallback` / `$getAll` はいずれも**自分のスコープ内の位置**を報告します。
 
 ## Command Token（メソッドバインディング）
 
@@ -1520,7 +1550,7 @@ 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) を参照してください。
+`$updatedCallback` は引き続き binding 駆動です。stream 宣言だけでは headless な購読にならず、その value/status/error の live DOM binding が実際に適用されたときだけ callback の path に現れます。描画せずに stream の値へ反応したい場合は、そのパスに [`$watch`](#watch-watch) を宣言してください。観測契約は [stream リファレンス](docs/streams.md) を参照してください。
 
 ```html
 <wcs-state>
@@ -1597,6 +1627,68 @@ $streams: {
 
 完全な契約 —— ライフサイクルと所有権・restart セマンティクス・flush 粒度・スコープ外リスト —— は [docs/streams.ja.md](docs/streams.ja.md) を参照してください。
 
+## Watch（`$watch`）
+
+`$updatedCallback` は **binding 駆動** です。その更新で live DOM binding が実際に適用された path だけを報告するため、**描画していない値の変化は見えません**。**`$watch`** はその headless 版で、ページ上でそのパスがバインドされているかどうかに関わらず、state の変化で発火します（**ワイルドカードの行パスだけは例外**で、headless に成立させるには `$listKeys` が要ります。後述）。
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      isLoading: false,
+      items: [],
+      startedAt: 0,
+
+      $watch: {
+        // 立ち上がり検出は cur/prev を自分で比較する
+        isLoading(cur, prev) {
+          if (cur === true && prev === false) { this.startedAt = Date.now(); }
+        },
+
+        // ワイルドカードパスは変化した行ごとに 1 回発火する
+        //（リストを `for` で描画しているか、`$listKeys` の宣言が要る。後述）
+        "items.*.price"(cur, prev, index) {
+          this.lastPriceChange = `#${index}: ${prev} → ${cur}`;
+        },
+      },
+    };
+  </script>
+</wcs-state>
+```
+
+ハンドラの `this` は **writable** な state proxy なので書き戻せます。その書き込みは次の更新バッチに乗ります。戻り値は無視され、await もされません。
+
+| 引数 | 契約 |
+|---|---|
+| `cur` | drain 時点の値（そのバッチの確定値） |
+| `prev` | **バッチ開始時点**の値（first-write-wins）。意味を持つのは**スカラのときだけ**（下記） |
+| `...indexes` | ワイルドカードパスのときのみ。そのスコープ自身のループ添字（`$1` / `$2` と同じ規約） |
+
+**`prev` はスカラ限定です。** same-value guard が既に読んでいる旧値を再利用するため watch のための追加読みは発生せず、その帰結として参照型（in-place 変異では同じ参照になるため）・`$postUpdate` 経由・`config.sameValueGuard` オフのときは `undefined` になります。
+
+**`$watch` は独自の発火条件を持ちません。** 更新バッチに載ったものをそのまま発火します。これはうまく噛み合っていて、同値の primitive 書き込みは enqueue 前に落ちている（＝実質的に変化時のみ発火）一方、occurrence（`semantics: "event"` の property）は**意図的に**落とされないので `cur === prev` で発火します。エッジ検出が要るならハンドラ内で `cur` と `prev` を比較してください。
+
+**getter を watch すると eager になります。** computed は本来 lazy で、依存は評価時にしか記録されません —— つまり描画していない getter は本来一度も発火しません。`$watch` に宣言すると接続時に 1 回評価され、以後は依存に触れたバッチの終端で毎回評価されます。`prev` は前回の評価値です。重い computed を watch すればその評価コストが毎バッチ乗り、getter 内の例外は watch 経由で表面化します。ワイルドカード getter（`items.*.tax`）は eager 化**しません**（初回評価がリスト全体を舐めることになるため）。この形は DOM にバインドされている場合にのみ発火し、`prev` は常に `undefined` です（行ごとの評価値を保持しないため）。
+
+発火順序は 3 層に分かれ、利用者が意思を持てるのは真ん中の層だけです。
+
+| 層 | 順序 | 制御 |
+|---|---|---|
+| 機構間 | `$updatedCallback` → `$watch` → `$streams` restart | 固定 |
+| ハンドラ間 | `$watch` の宣言順 | **宣言を並べ替える** |
+| 同一パスの行間 | `indexes` 昇順 | 固定 |
+
+主なルール:
+
+- **自 state のみ** —— パスに `@stateName` は書けません。他の state 要素の watch は宣言時に拒否されます。
+- **中間値は観測できません** —— 1 バッチ内の `a → b → c` は `cur = c` / `prev = a` で 1 回だけ発火します（binding 更新と同じ契約）。
+- **行単位の差分を見たいなら `$listKeys`** —— 未宣言のまま配列全体を代入すると、行 watch は**全行**について `prev === undefined` で発火します（どの行もパス書き込みを通っていないため）。`$listKeys` を宣言すればキー突合が per-field 書き込みに分解するので、変化した行だけが発火し `prev` もスカラで取れます。
+- **headless な行 watch には `$listKeys` が必要** —— `$watch` が単独では headless にならない唯一の箇所です。`items` から `items.*.price` への展開はリストの `for` バインディングが駆動しており、watch を宣言してもそのパスをリストとしては登録しません（意図的）。したがって `for` バインドも `$listKeys` も無い状態で配列を代入すると、行 watch は**一度も**発火しません。`$listKeys` を宣言する（キー突合がフィールドごとにパス書き込みするので展開を経由しない）か、リストを描画してください。スカラーパスは `user.name` のようなネストしたものも含め、この条件なしに headless で発火します。
+- **ハンドラの例外は隔離されます** —— throw はコンソールに報告され、残りの watch（と stream の restart）は続行します。loud fail する `$connectedCallback` / `$updatedCallback` とは異なる扱いです。
+- **書き込みの連鎖には上限があります** —— ハンドラの書き込みは新しいバッチを作るため、相互に書き合う watch は無限ループになり得ます。32 段で打ち切り、コンソールに報告します（値と DOM は巻き戻しません）。
+- **mapped な `bind-component` の子では使えません** —— 子の state は `$` 始まりのプロパティを遮る proxy に包まれるため、宣言が届きません（`$streams` も同様）。plain な（マップされていない）子では宣言できます。
+- **SSR では実行されません** —— ハンドラの副作用がサーバーとクライアントで二重に走るためです。
+
 ## Inputs と属性ミラー
 
 `wcBindable.inputs` は一方向のプロパティ入力（state → 要素）を宣言します。エントリに `attribute` を設定すると、フレームワークはプロパティを書き込むたびにその値を当該 HTML 属性へも書き込むため、`attributeChangedCallback`・CSS の属性セレクタ・DevTools がすべてプロパティ値と同期し続けます。
@@ -1707,7 +1799,7 @@ JavaScript のクラス定義なしで、**HTML だけ**でカスタム要素を
 
 ### `$bindables` / `$commands` と wc-bindable プロトコル
 
-`$bindables` は変更イベント付きのコンポーネント**プロパティ**として公開する状態プロパティを、`$commands` は起動可能な**コマンド**として公開する状態メソッドを宣言します。この 2 つで [wc-bindable プロトコル](https://github.com/nicenemo/nicenemo/blob/main/docs/wc-bindable-protocol.md)の宣言が組み立てられます：
+`$bindables` は変更イベント付きのコンポーネント**プロパティ**として公開する状態プロパティを、`$commands` は起動可能な**コマンド**として公開する状態メソッドを宣言します。この 2 つで [wc-bindable プロトコル](https://github.com/wc-bindable-protocol/wc-bindable-protocol/blob/main/README.md)の宣言が組み立てられます：
 
 ```javascript
 export default {

package/README.md

@@ -95,7 +95,7 @@ That's it. No build, no bootstrap code, no framework.
 - **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
+- **Built-in filters** — 46 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
 - **Command tokens** — invoke methods on wc-bindable custom elements from state via a pub/sub channel (`command.<method>: tokenName`)
@@ -443,7 +443,7 @@ Internally converted to comment-based bindings (`<!--@@:expression-->`).
 
 ### Spread Binding (`...`)
 
-For custom elements that declare the [`wc-bindable` protocol](#wcbindable-protocol), `...: target` wires all of the element's **properties + inputs** to a single state object in one line:
+For custom elements that declare the [`wc-bindable` protocol](#bindables--commands-and-the-wc-bindable-protocol), `...: target` wires all of the element's **properties + inputs** to a single state object in one line:
 
 ```html
 <wcs-fetch data-wcs="...: usersFetch"></wcs-fetch>
@@ -986,7 +986,7 @@ export default {
 
 ## Filters
 
-40 built-in filters are available for both input (DOM → state) and output (state → DOM) directions.
+46 built-in filters are available for both input (DOM → state) and output (state → DOM) directions.
 
 ### Comparison
 
@@ -1009,6 +1009,8 @@ export default {
 | `mul(n)` | Multiply | `price\|mul(1.1)` |
 | `div(n)` | Divide | `total\|div(100)` |
 | `mod(n)` | Modulo | `index\|mod(2)` |
+| `abs` | Absolute value | `delta\|abs` |
+| `clamp(min, max)` | Constrain to a range | `ratio\|clamp(0,100)` |
 
 ### Number Formatting
 
@@ -1020,6 +1022,7 @@ export default {
 | `ceil(n?)` | Ceiling | `value\|ceil` |
 | `locale(loc?)` | Locale number format | `count\|locale` / `count\|locale(ja-JP)` |
 | `percent(n?)` | Percentage format | `ratio\|percent(1)` |
+| `unit(u)` | Append a unit (any suffix) | `width\|unit(px)` → `"40px"` |
 
 ### String
 
@@ -1034,6 +1037,8 @@ export default {
 | `pad(n, char?)` | Pad start | `id\|pad(5,0)` → `"00001"` |
 | `rep(n)` | Repeat | `text\|rep(3)` |
 | `rev` | Reverse | `text\|rev` |
+| `truncate(n, suffix?)` | Shorten and append an ellipsis | `title\|truncate(20)` |
+| `join(sep?)` | Join an array (default `", "`) | `tags\|join` / `tags\|join(/)` |
 
 ### Type Conversion
 
@@ -1054,6 +1059,7 @@ export default {
 | `time(loc?)` | Time format | `timestamp\|time` |
 | `datetime(loc?)` | Date + Time | `timestamp\|datetime(en-US)` |
 | `ymd(sep?)` | YYYY-MM-DD | `timestamp\|ymd` / `timestamp\|ymd(/)` |
+| `hms(sep?)` | HH:MM:SS | `timestamp\|hms` / `timestamp\|hms(-)` |
 
 ### Boolean / Default
 
@@ -1126,6 +1132,18 @@ customElements.define("my-light-component", MyLightComponent);
 - Bindings must explicitly reference the state name with `@my-light`
 - `<wcs-state>` must be a direct child of the component element
 
+- Binding from the host (`<my-light-component data-wcs="state.message: user.name">`) works just as it
+  does for Shadow DOM. The component's subtree is treated as an **independent binding scope** and is
+  wired once the component's own state has registered its name
+
+> **Note**: Light DOM shares its namespace with the parent scope, so **two instances carrying the same
+> `name` cannot live in one scope**. Use Shadow DOM for shapes that place a component on every row of
+> a list.
+>
+> Also, `State.getBindingsReady(root)` does not cover the component's scope — the same as the Shadow
+> DOM form, where the child lives in a different rootNode. Await the component's own `<wcs-state>`
+> initialization when you need to wait for its contents to render.
+
 ### Host Usage
 
 ```html
@@ -1219,8 +1237,24 @@ this.shadowRoot.innerHTML = `
 
 - 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
+
+#### Nesting and stacking scopes
+
+A component that sits inside a host `for:` *and* runs its own `for:` over the array it was handed
+is supported. The framework keeps the outer row and the inner row related:
+
+```html
+<template data-wcs="for: groups">
+  <my-list data-wcs="state.items: groups.*.children"></my-list>
+</template>
+```
+
+Components can also be placed inside components, **stacking scopes**. An intermediate component
+that only passes the array through — running no `for:` of its own — still lets a row-field write
+from the owning scope reach the rows at the bottom.
+
+A component's author never has to know how deeply it is placed. `$1`, event-handler indexes,
+`$updatedCallback` and `$getAll` all report positions **within the component's own scope**.
 
 ## Command Token (Method Binding)
 
@@ -1521,7 +1555,7 @@ 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.
+`$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. To react to a stream's value without rendering it, declare [`$watch`](#watch-watch) on that path; see the [stream reference](docs/streams.md) for the observation contract.
 
 ```html
 <wcs-state>
@@ -1598,6 +1632,68 @@ Key rules:
 
 See [docs/streams.md](docs/streams.md) for the full contract — lifecycle and ownership, restart semantics, flush granularity, and the out-of-scope list.
 
+## Watch (`$watch`)
+
+`$updatedCallback` is **binding-driven**: it reports the paths whose live DOM bindings were actually applied in that update, so a value you never render is invisible to it. **`$watch`** is the headless counterpart — it fires on state changes whether or not anything on the page is bound to the path. (One exception, spelled out below: a *wildcard* row path needs `$listKeys` to work headlessly.)
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      isLoading: false,
+      items: [],
+      startedAt: 0,
+
+      $watch: {
+        // rising-edge detection: you compare cur/prev yourself
+        isLoading(cur, prev) {
+          if (cur === true && prev === false) { this.startedAt = Date.now(); }
+        },
+
+        // wildcard paths fire once per changed row
+        // (needs the list rendered with `for`, or `$listKeys` declared — see below)
+        "items.*.price"(cur, prev, index) {
+          this.lastPriceChange = `#${index}: ${prev} → ${cur}`;
+        },
+      },
+    };
+  </script>
+</wcs-state>
+```
+
+The handler runs with `this` bound to a **writable** state proxy, so it can write back; those writes land in the next update batch. The return value is ignored and never awaited.
+
+| Argument | Contract |
+|---|---|
+| `cur` | The value at drain time (the settled value for the batch) |
+| `prev` | The value at the **start of the batch** (first-write-wins). Meaningful **for scalars only** — see below |
+| `...indexes` | Only for wildcard paths: this scope's own loop indexes, same convention as `$1`, `$2` |
+
+**`prev` is scalar-only.** It reuses the old value the same-value guard already reads, so watch costs no extra read — and it is `undefined` for reference types (an in-place mutation would give you the same reference anyway), for `$postUpdate`, and when `config.sameValueGuard` is off.
+
+**Watch adds no firing condition of its own.** It fires for whatever landed in the update batch. That falls out well: an equal primitive write is already dropped before it is enqueued (so you effectively get change-only firing), while an occurrence write — a `semantics: "event"` property — is deliberately *not* dropped, and still fires with `cur === prev`. If you need edge detection, compare `cur` and `prev` in the handler.
+
+**Watching a getter makes it eager.** A computed getter is normally lazy, and its dependencies are only recorded when it is evaluated — so an unrendered getter would never fire at all. Declaring one in `$watch` evaluates it once at connect and again at the end of every batch that touches its dependencies. Its `prev` is the previous evaluation. Watch a heavy computed and you pay that evaluation on every batch; exceptions inside it surface through the watch instead of staying dormant. Wildcard getters (`items.*.tax`) are **not** made eager — priming one would sweep the whole list — so that form fires only when it is also bound to the DOM, and its `prev` is always `undefined` (no per-row evaluation is remembered).
+
+Firing order is defined in three layers, and only the middle one is yours to steer:
+
+| Layer | Order | Your control |
+|---|---|---|
+| Mechanisms | `$updatedCallback` → `$watch` → `$streams` restart | fixed |
+| Between handlers | declaration order in `$watch` | **reorder the declarations** |
+| Between rows of one path | ascending `indexes` | fixed |
+
+Key rules:
+
+- **Only its own state** — a path may not carry `@stateName`; watching another state element is rejected at declaration time.
+- **Intermediate values are not observable** — a batch that goes `a → b → c` fires once with `cur = c`, `prev = a`, the same contract as binding updates.
+- **Row-level diffs want `$listKeys`** — without it, assigning a whole array fires the row watch for *every* row with `prev === undefined`, because no row went through a path write. With `$listKeys` declared, the key match decomposes the assignment into per-field writes, so only changed rows fire and `prev` is a real scalar.
+- **A headless row watch requires `$listKeys`** — this is the one place `$watch` is *not* headless on its own. Expanding `items` into `items.*.price` is driven by the list's `for` binding, and declaring a watch deliberately does not register the path as a list. So with neither a `for` binding nor `$listKeys`, assigning the array fires the row watch **zero** times. Add `$listKeys` (the key match writes each field by path, bypassing the expansion) or render the list. Scalar paths — including nested ones like `user.name` — are headless with no such condition.
+- **Handler exceptions are isolated** — a throw is reported to the console and the remaining watches (and stream restarts) still run. This differs from `$connectedCallback` / `$updatedCallback`, which fail loudly.
+- **Write chains are bounded** — a handler's writes form a new batch, so mutually-writing watches would loop forever; the chain is cut off after 32 links with a console error. Values and DOM are not rolled back.
+- **Not available on a mapped `bind-component` child** — its state is wrapped in a proxy that blanks out every `$`-prefixed property, so the declaration never arrives. This applies to `$streams` too. A plain (unmapped) child can declare it.
+- **SSR does not run watches** — handler side effects would otherwise execute on both server and client.
+
 ## Inputs and Attribute Mirror
 
 `wcBindable.inputs` declares one-way property inputs (state → element). When an entry sets `attribute`, the framework writes the value to that HTML attribute every time it writes the property, so `attributeChangedCallback`, CSS attribute selectors, and DevTools all stay in sync with the property value.
@@ -1708,7 +1804,7 @@ The definition element is hidden; each instance clones the template into its own
 
 ### `$bindables` / `$commands` and the wc-bindable Protocol
 
-`$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:
+`$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/wc-bindable-protocol/wc-bindable-protocol/blob/main/README.md) declaration:
 
 ```javascript
 export default {