@wcstack/state 1.31.0 → 1.32.0

package/README.ja.md

@@ -769,19 +769,20 @@ export default {
          + this["regions.*.prefectures.*.cities.*.name"];
   },
 
-  // 県レベル — 市からの集約
+  // 県レベル — 市からの集約。`indexes` 省略時はループ文脈（[$1, $2]）が
+  // 既定になるので、この県の市だけが合計される
   get "regions.*.prefectures.*.totalPopulation"() {
-    return this.$getAll("regions.*.prefectures.*.cities.*.population", [])
+    return this.$getAll("regions.*.prefectures.*.cities.*.population")
       .reduce((a, b) => a + b, 0);
   },
 
-  // 地方レベル — 県からの集約
+  // 地方レベル — 県からの集約（文脈 [$1] でこの地方に絞られる）
   get "regions.*.totalPopulation"() {
-    return this.$getAll("regions.*.prefectures.*.totalPopulation", [])
+    return this.$getAll("regions.*.prefectures.*.totalPopulation")
       .reduce((a, b) => a + b, 0);
   },
 
-  // トップレベル — 地方からの集約
+  // トップレベル — ループ文脈なし。[] は「マッチ全件」
   get totalPopulation() {
     return this.$getAll("regions.*.totalPopulation", [])
       .reduce((a, b) => a + b, 0);
@@ -943,6 +944,7 @@ export default {
 | API | 説明 |
 |---|---|
 | `this.$getAll(path, indexes?)` | ワイルドカードパスにマッチする全ての値を取得 |
+| `this.$setAll(path, indexes, value, options?)` | ワイルドカードパスにマッチする全アドレスへ一括書き込み |
 | `this.$resolve(path, indexes, value?)` | ワイルドカードパスを特定のインデックスで解決 |
 | `this.$postUpdate(path)` | 指定パスの更新通知を手動で発行 |
 | `this.$trackDependency(path)` | キャッシュ無効化のための依存関係を手動で登録 |
@@ -967,6 +969,66 @@ export default {
 };
 ```
 
+`indexes` はパスの `*` に対する**前方一致の接頭辞**です。不足した階層は全展開され、`[]` は常に「マッチ全件」を意味します。**省略**した場合はループ文脈の添字（`[$1, $2, ...]`）が既定になり、パスが文脈と共有するワイルドカード階層に敷かれます：
+
+```javascript
+export default {
+  regions: [ /* { prefectures: [ { population: … }, … ] } */ ],
+  // ループ文脈 [$1] — 省略すると現在の地方に絞られる
+  get "regions.*.total"() {
+    return this.$getAll("regions.*.prefectures.*.population").reduce((a, b) => a + b, 0);
+  },
+  // ループ文脈なし — 省略は全展開（[] と同じ）
+  get grandTotal() {
+    return this.$getAll("regions.*.total").reduce((a, b) => a + b, 0);
+  }
+};
+```
+
+文脈がパスより深い分は切り詰められます（`[$1, $2]` の文脈は `*` 1 本のパスを `[$1]` で絞ります）。一方、文脈がループ添字を持っているのにパスと**ワイルドカード階層をまったく共有しない**場合 —— たとえば `regions.*` の getter 内での `$getAll("users.*.name")` —— は、黙って全 users を読む代わりに **throw** します。文脈の添字は別のリストのものであり、流用しても無視しても書き手の意図とは食い違うためです。この形では添字を明示してください（全件なら `[]`）。
+
+#### `$setAll` — 配列要素を作り直さずに一括更新
+
+`$setAll` は `$getAll` の書き側の対称形で、ワイルドカードパスにマッチする全アドレスへ書き込みます。狙いは記述の短さではなく、**配列そのものを保つ**ことです。`this.users = this.users.map(...)` のように作り直すと ListIndex・行 getter のキャッシュ・差分描画がまとめて捨てられますが、`$setAll` は行ごとの in-place な書き込みに分解するのでリストの同一性が保たれます。
+
+```javascript
+export default {
+  users: [{ selected: false }, { selected: false }],
+
+  toggleAll(e) {
+    this.$setAll("users.*.selected", [], e.target.checked);   // ブロードキャスト
+  },
+  invertAll() {
+    this.$setAll("users.*.selected", [], cur => !cur);        // mapper
+  },
+  rankTopThree() {
+    // undefined を返したアドレスはスキップされる（＝この行は変えない）
+    this.$setAll("users.*.score", [], (cur, i) => i < 3 ? cur * 2 : undefined);
+  }
+};
+```
+
+形は 3 つあり、3 番目だけは明示的に要求する必要があります。
+
+| 第 3 引数 | 意味 |
+|---|---|
+| 関数 | **mapper** — マッチしたアドレスごとに `(current, ...indexes)` で呼ばれる |
+| それ以外 | **ブロードキャスト** — 配列も含め、同じ値が全アドレスに書かれる |
+| 配列 ＋ `{ spread: true }` | **spread** — マッチ順に 1 件ずつ配る |
+
+配列が既定でブロードキャストされるのは、対象プロパティ自体が配列型でありうるためです。`$setAll("users.*.tags", [], ["admin"])` は「全員に `["admin"]`」なのか「1 人目に `"admin"`」なのか判別できません。`{ spread: true }` を明示すればこの推測が消え、長さがマッチ件数と噛み合わなければ黙って誤配せずに throw します。
+
+`indexes` の意味は `$getAll` と同じ**前方一致の接頭辞**（不足はその階層を全展開）ですが、**省略はできません**。書き込みには暗黙のループ文脈を与えないため、`for` テンプレートの中でも `this.$setAll("users.*.selected", [], true)` は現在行ではなく**全行**を意味します。
+
+```javascript
+this.$setAll("matrix.*.*", [0], 0);                    // 0 行目だけ全列
+this.$setAll("users.*", [], rows, { spread: true });   // 配列を保ったまま各行を差し替え
+```
+
+`undefined` はどの形でも書き込まれず「このアドレスはスキップ」を意味します。mapper が `return` を忘れて全行を潰す事故を防ぐためで、クリアしたい場合は `null` を使います。戻り値は実際に書き込んだ件数です。
+
+なお `$setAll` は依存解決を一括化する仕組みではありません。描画は 1 バッチに畳まれますが、書き込みは 1 件ずつ登録されるので、コストは置き換え対象の手書きループと同じです。得られるのはリストが保たれることであって、実行回数の削減ではありません。
+
 #### `$resolve` — 明示的なインデックスでのアクセス
 
 `$resolve` は特定のワイルドカードインデックスの値を読み書きします：
@@ -1750,6 +1812,8 @@ $updatedCallback(paths) {
 | ハンドラ間 | `$watch` の宣言順 | **宣言を並べ替える** |
 | 同一パスの行間 | `indexes` 昇順 | 固定 |
 
+**機構間の層を動かす唯一のもの**が、`state` 参加者を受け付ける `<wcs-view-transition>` です。バインディング適用 —— したがって `$updatedCallback` —— がフレームで着地する一方、`$watch` と `$streams` restart は state アドレスを消費し DOM を見ないので、drain がキューされた microtask に留まります。タグがある間の順序は `$watch` → `$streams` restart → `$updatedCallback` です。この層を並べ替えるものはページ上でこれ 1 つだけです。[docs/timing-and-firing-contract.ja.md](https://github.com/wcstack/wcstack/blob/main/docs/timing-and-firing-contract.ja.md) §4.3 を参照してください。
+
 主なルール:
 
 - **自 state のみ** —— パスに `@stateName` は書けません。他の state 要素の watch は宣言時に拒否されます。
@@ -2011,6 +2075,31 @@ export default {
 - `$updatedCallback(paths, indexesListByPath)` は、その drain で live binding が適用された path の一覧を受け取ります。binding のない state 書き込みでは呼ばれず、`paths` にも現れません。ワイルドカードをもつパスが更新された場合は、`indexesListByPath` から対象のインデックス情報も取得可能です。`async` を使用できますが、戻り値は await されません。
 - Web Component を使用している場合は、コンポーネント側に `async $stateReadyCallback(stateProp)` を定義おくことで、`bind-component` でバインドした状態が利用可能になった瞬間にフックとして呼び出されます。
 
+## 遷移アニメーション
+
+入場アニメーションにこのパッケージは要らない。新しい `for` 行も mount する `if` 分岐も「新しく挿入された要素」なので、素の CSS で足りる。
+
+```css
+li {
+  transition: opacity 0.2s, transform 0.2s;
+  @starting-style { opacity: 0; transform: translateY(-4px); }
+}
+```
+
+そこへ届かないのが**退場**と**移動**。削除された行は同期で detach され、並べ替えには中間状態が無い。[`@wcstack/view-transition`](https://github.com/wcstack/wcstack/tree/main/packages/view-transition) を足すと drain の DOM 変更が View Transition の中で行われ、変更前の状態はブラウザがスナップショットしてくれる。
+
+```html
+<script type="module" src="https://esm.run/@wcstack/view-transition/auto"></script>
+<wcs-view-transition naming="auto"></wcs-view-transition>
+```
+
+そのタグが `state` 参加者を受け付けている間、知っておくべき帰結が 2 つある。
+
+- drain は microtask ではなくフレームで着地する。state に書いてから `await Promise.resolve()` で DOM を読むコードは遷移を待つ必要がある。`$updatedCallback` はバインディング適用の直後という*位置*こそ変わらないが、その適用ごと 1 フレーム後ろへずれる。
+- `$watch` と `$streams` restart は元の microtask に留まるため、`$updatedCallback` の**前**に走るようになる。
+
+適用すべきバインディングが実際にあるバッチだけがタグへ渡されるので、headless なパスへの書き込みが遷移を起こすことはない。タグが無ければ drain は従来どおり。[docs/timing-and-firing-contract.ja.md](https://github.com/wcstack/wcstack/blob/main/docs/timing-and-firing-contract.ja.md) §4.3 参照。
+
 ## 診断と失敗の扱い
 
 ### 存在しないパスへの配線は報告されます
@@ -2045,7 +2134,7 @@ dropped. Validate statically: npx @wcstack/lint <file>.
 
 | 診断 | 何を見るか | 直し方 |
 |---|---|---|
-| `wcs/index-arity` | `$resolve(path, indexes)` は `*` の本数と**厳密一致**、`$getAll(path, indexes)` は**上限**（不足は「残りの階層を全展開」という正当な接頭辞） | 本数を合わせる |
+| `wcs/index-arity` | `$resolve(path, indexes)` は `*` の本数と**厳密一致**、`$getAll(path, indexes)` / `$setAll(path, indexes, …)` は**上限**（不足は「残りの階層を全展開」という正当な接頭辞） | 本数を合わせる |
 | `wcs/wildcard-rank` | パスの `*` の本数（と `$N` の N）が、囲む `for` の段数を超えていないか | `for` を足すか、`$resolve(path, indexes)` で行を明示する |
 | `wcs/getter-cycle` | パス getter どうしが循環参照していないか | 循環を断つ |
 
@@ -2102,13 +2191,41 @@ bootstrapState({
 |---|---|---|
 | `bindAttributeName` | `'data-wcs'` | バインディング属性名 |
 | `tagNames.state` | `'wcs-state'` | 状態要素のタグ名 |
-| `locale` | `'en'` | フィルタのデフォルトロケール |
+| `locale` | `<html lang>`、無ければ `'en'` | ロケール依存フィルタ（`locale` / `date` / `time` / `datetime`）のロケール — [ロケール](#ロケール)を参照 |
 | `debug` | `false` | デバッグモード |
 | `enableMustache` | `true` | `{{ }}` 構文の有効化 |
 | `enableDirectionalInitialSync` | `true` | 方向認識のバインディング authority（`#init=` / `#sync=` バインド modifier）— [バインディング authority](#バインディング-authority-init--sync) 参照。既定 on。`false` で opt-out |
 | `enablePropagationContext` | `true` | バインド間の因果伝播トラッキング（echo/diamond のループ防止）。既定 on。`false` で opt-out |
 | `enableContractAnalyzer` | `false` | opt-in の開発時 contract analyzer（`analyzeContract` を公開） |
 
+### ロケール
+
+ロケールで書式化するフィルタは 4 つある — `locale` / `date` / `time` / `datetime`。
+これらは `config.locale` を読み、その既定は **`<html lang>`** である。
+
+```html
+<html lang="ja-JP">
+  <script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+```
+
+他に何も要らない。`<html lang>` はページの言語を書く HTML 標準の場所であり、
+そこを既定にすればロケールの正本が 1 つで済む。同時に、**CDN 一発のページが
+ロケールを設定できるようになる** — `auto` は `bootstrapState()` を引数なしで呼ぶので、
+これが無いと渡す口が無かった。明示指定（`bootstrapState({ locale })`）は常に優先し、
+不正な BCP-47 タグは `Intl` の中で落ちる前に警告して無視する。
+
+**`config.locale` を後から変えても何も再描画されない。** これは state ではなく
+グローバル設定なので、依存グラフに載らない。フィルタ自体はバインド構築時に
+取り込むのではなく**適用のたびに読む**ので、別の理由で再描画されたバインドは新しい値を
+拾う — 起動順序の事故から復帰するには足りるが、ページの言語を切り替えるには足りない。
+言語はページが描画される前に決めること。マークアップに `<html lang>` を書くか、
+`<head>` の同期スクリプトで書けば構造的にそうなる。
+
+呼び出しごとの上書き（`price|locale(fr-FR)`）は従来どおり使え、こちらはバインド式の
+一部なのでバインド時に固定される。リロードなしで言語を切り替えたい場合は
+[docs/i18n-design.md](../../docs/i18n-design.md) を参照。短く言えば、翻訳はフィルタでは
+なくパスに置く。
+
 > この 3 つは **architecture-hardening** 機能で、規範は `docs/architecture-hardening/` に
 > あります。`enablePropagationContext` は**既定 on** — write-path コストは一方向バインドで
 > ほぼゼロ（echo しうる双方向 wire のみ因果 bookkeeping を行う）で、フラグは恒久的な

package/README.md

@@ -769,19 +769,20 @@ export default {
          + this["regions.*.prefectures.*.cities.*.name"];
   },
 
-  // Prefecture level — aggregate from cities
+  // Prefecture level — aggregate from cities. `indexes` omitted: it defaults to
+  // the loop context ([$1, $2]), so only this prefecture's cities are summed
   get "regions.*.prefectures.*.totalPopulation"() {
-    return this.$getAll("regions.*.prefectures.*.cities.*.population", [])
+    return this.$getAll("regions.*.prefectures.*.cities.*.population")
       .reduce((a, b) => a + b, 0);
   },
 
-  // Region level — aggregate from prefectures
+  // Region level — aggregate from prefectures (context [$1] narrows to this region)
   get "regions.*.totalPopulation"() {
-    return this.$getAll("regions.*.prefectures.*.totalPopulation", [])
+    return this.$getAll("regions.*.prefectures.*.totalPopulation")
       .reduce((a, b) => a + b, 0);
   },
 
-  // Top level — aggregate from regions
+  // Top level — no loop context; [] means "every match"
   get totalPopulation() {
     return this.$getAll("regions.*.totalPopulation", [])
       .reduce((a, b) => a + b, 0);
@@ -943,6 +944,7 @@ Inside state objects (getters / methods), the following APIs are available via `
 | API | Description |
 |---|---|
 | `this.$getAll(path, indexes?)` | Get all values matching a wildcard path |
+| `this.$setAll(path, indexes, value, options?)` | Write to every address 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 |
@@ -968,6 +970,66 @@ export default {
 };
 ```
 
+`indexes` is a **prefix** over the path's wildcards: missing levels expand fully, and `[]` always means "every match". When `indexes` is **omitted**, it defaults to the enclosing loop context (`[$1, $2, ...]`), applied to the wildcard levels the path shares with that context:
+
+```javascript
+export default {
+  regions: [ /* { prefectures: [ { population: … }, … ] } */ ],
+  // Loop context [$1] — omission narrows to the current region
+  get "regions.*.total"() {
+    return this.$getAll("regions.*.prefectures.*.population").reduce((a, b) => a + b, 0);
+  },
+  // No loop context — omission expands everything (same as [])
+  get grandTotal() {
+    return this.$getAll("regions.*.total").reduce((a, b) => a + b, 0);
+  }
+};
+```
+
+Context levels deeper than the path needs are dropped (a `[$1, $2]` context narrows a one-wildcard path by `[$1]`). But if the path shares **no** wildcard level with a context that does hold loop indexes — say `$getAll("users.*.name")` inside a `regions.*` getter — `$getAll` **throws** instead of silently reading every user: the context indexes belong to a different list, and neither reusing nor ignoring them is what the author meant. Pass indexes explicitly there (`[]` for every match).
+
+#### `$setAll` — Update Every Array Element In Place
+
+`$setAll` is the write-side counterpart of `$getAll`: it writes to every address a wildcard path matches. The point is not brevity but **keeping the array itself**. Rebuilding it (`this.users = this.users.map(...)`) throws away the list indexes, the per-row getter caches, and the render diff; `$setAll` decomposes into in-place per-row writes instead, so the list identity survives.
+
+```javascript
+export default {
+  users: [{ selected: false }, { selected: false }],
+
+  toggleAll(e) {
+    this.$setAll("users.*.selected", [], e.target.checked);   // broadcast
+  },
+  invertAll() {
+    this.$setAll("users.*.selected", [], cur => !cur);        // mapper
+  },
+  rankTopThree() {
+    // `undefined` skips that address — "leave this row alone"
+    this.$setAll("users.*.score", [], (cur, i) => i < 3 ? cur * 2 : undefined);
+  }
+};
+```
+
+Three forms, and the third one has to be asked for explicitly:
+
+| Third argument | Meaning |
+|---|---|
+| a function | **mapper** — called as `(current, ...indexes)` per matched address |
+| anything else | **broadcast** — the same value is written everywhere, arrays included |
+| an array **plus** `{ spread: true }` | **spread** — one entry handed to each matched address, in match order |
+
+Arrays broadcast by default because the target property may itself be array-valued — `$setAll("users.*.tags", [], ["admin"])` would otherwise be ambiguous. Opting into `{ spread: true }` removes the guesswork, and a length that does not equal the match count throws rather than silently misaligning.
+
+`indexes` works exactly as in `$getAll` — a **prefix**, where missing levels mean "expand all of them" — but it is **required**. Writes get no implicit loop context, so inside a `for` template `this.$setAll("users.*.selected", [], true)` still means *every* user, never the current row.
+
+```javascript
+this.$setAll("matrix.*.*", [0], 0);        // row 0 only, every column
+this.$setAll("users.*", [], rows, { spread: true });   // replace each row, keep the array
+```
+
+`undefined` is never written — it means "skip this address" in all three forms, which keeps a mapper that forgets to `return` from wiping every row. Use `null` to clear. The return value is the number of addresses actually written.
+
+One thing `$setAll` is not: a shortcut for the dependency walk. Rendering still coalesces into a single batch, but each write is enqueued individually, so the cost matches the hand-written loop it replaces. What it buys you is the preserved list, not fewer cycles.
+
 #### `$resolve` — Access by Explicit Index
 
 `$resolve` reads or writes a value at a specific wildcard index:
@@ -1755,6 +1817,8 @@ Firing order is defined in three layers, and only the middle one is yours to ste
 | Between handlers | declaration order in `$watch` | **reorder the declarations** |
 | Between rows of one path | ascending `indexes` | fixed |
 
+**The one thing that moves the mechanism layer** is a `<wcs-view-transition>` that accepts the `state` participant. Binding application — and with it `$updatedCallback` — then lands on a frame, while `$watch` and the `$streams` restart stay on the microtask the drain was queued on, because they consume state addresses and not the DOM. For as long as the tag is present the order is `$watch` → `$streams` restart → `$updatedCallback`. Nothing else on the page reorders this layer; see [docs/timing-and-firing-contract.md](https://github.com/wcstack/wcstack/blob/main/docs/timing-and-firing-contract.md) §4.3.
+
 Key rules:
 
 - **Only its own state** — a path may not carry `@stateName`; watching another state element is rejected at declaration time.
@@ -2016,6 +2080,31 @@ All hooks except `$disconnectedCallback` support `async` — you can use `async/
 - `$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`
 
+## Transition animations
+
+Enter animations need nothing from this package — a new `for` row and a mounting `if` branch are newly inserted elements, so plain CSS covers them:
+
+```css
+li {
+  transition: opacity 0.2s, transform 0.2s;
+  @starting-style { opacity: 0; transform: translateY(-4px); }
+}
+```
+
+**Leaving** and **moving** cannot be reached that way: removed rows are detached synchronously, and a reorder has no intermediate state. Adding [`@wcstack/view-transition`](https://github.com/wcstack/wcstack/tree/main/packages/view-transition) makes the drain apply its DOM changes inside a View Transition, where the browser snapshots the old state for you:
+
+```html
+<script type="module" src="https://esm.run/@wcstack/view-transition/auto"></script>
+<wcs-view-transition naming="auto"></wcs-view-transition>
+```
+
+Two consequences to know while that tag accepts the `state` participant:
+
+- The drain lands on a frame instead of a microtask, so code that writes state and then reads the DOM after `await Promise.resolve()` must wait for the transition. `$updatedCallback` still fires immediately after the bindings are applied — its *position* is unchanged, but it moves a frame later along with them.
+- Because `$watch` and the `$streams` restart stay on the original microtask, they now run **before** `$updatedCallback` instead of after it.
+
+Only a batch that actually has bindings to apply is handed to the tag, so a write to a headless path never starts a transition. Without the tag the drain is exactly what it was. See [docs/timing-and-firing-contract.md](https://github.com/wcstack/wcstack/blob/main/docs/timing-and-firing-contract.md) §4.3.
+
 ## Diagnostics and failure handling
 
 ### Wiring to a path that does not exist is reported
@@ -2050,7 +2139,7 @@ Anything that follows mechanically from the path string is reported at runtime a
 
 | Diagnostic | What it checks | Fix |
 |---|---|---|
-| `wcs/index-arity` | `$resolve(path, indexes)` must match the `*` count **exactly**; `$getAll(path, indexes)` has it as an **upper bound** (fewer is a legitimate prefix meaning "expand the rest") | Match the count |
+| `wcs/index-arity` | `$resolve(path, indexes)` must match the `*` count **exactly**; `$getAll(path, indexes)` / `$setAll(path, indexes, …)` have it as an **upper bound** (fewer is a legitimate prefix meaning "expand the rest") | Match the count |
 | `wcs/wildcard-rank` | The path's `*` count (and the N in `$N`) must not exceed the enclosing `for` nesting | Add a `for`, or name the row with `$resolve(path, indexes)` |
 | `wcs/getter-cycle` | Path getters must not form a dependency cycle | Break the cycle |
 
@@ -2107,13 +2196,43 @@ All options with defaults:
 |---|---|---|
 | `bindAttributeName` | `'data-wcs'` | Binding attribute name |
 | `tagNames.state` | `'wcs-state'` | State element tag name |
-| `locale` | `'en'` | Default locale for filters |
+| `locale` | `<html lang>`, else `'en'` | Locale for the locale-dependent filters (`locale` / `date` / `time` / `datetime`) — see [Locale](#locale) |
 | `debug` | `false` | Debug mode |
 | `enableMustache` | `true` | Enable `{{ }}` syntax |
 | `enableDirectionalInitialSync` | `true` | Direction-aware binding authority (`#init=` / `#sync=` binding modifiers) — see [Binding Authority](#binding-authority-init--sync). Default on; set `false` to opt out |
 | `enablePropagationContext` | `true` | Causal propagation tracking across bindings (echo/diamond loop prevention). Default on; set `false` to opt out |
 | `enableContractAnalyzer` | `false` | Opt-in dev-time contract analyzer (exposes `analyzeContract`) |
 
+### Locale
+
+Four filters format by locale — `locale`, `date`, `time`, `datetime`. They read
+`config.locale`, which **defaults to `<html lang>`**:
+
+```html
+<html lang="ja-JP">
+  <script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+```
+
+Nothing else is needed; `<html lang>` is the standard place to record a page's
+language, and making it the default keeps one source of truth. It also means the
+CDN one-liner can set the locale at all — `auto` calls `bootstrapState()` with no
+arguments, so before this there was no way in. An explicit
+`bootstrapState({ locale })` still wins, and an invalid BCP-47 tag is reported
+and ignored rather than left to throw inside `Intl`.
+
+**Changing `config.locale` later does not re-render anything.** It is a global
+setting, not state, so it is not part of the dependency graph. The filters do
+read it on every application rather than capturing it when the binding is built,
+which means a binding that re-renders for its own reasons will pick up the new
+value — enough to recover from a mis-ordered startup, not enough to switch a
+page's language. Set the language before the page renders: writing `<html lang>`
+in the markup, or from a synchronous `<head>` script, does that structurally.
+
+Per-call overrides stay available and are fixed at bind time, since they are part
+of the binding expression: `price|locale(fr-FR)`. For a page that switches
+language without reloading, see [docs/i18n-design.md](../../docs/i18n-design.md) —
+the short answer is that translations belong on a path, not in a filter.
+
 > These three are **architecture-hardening** features; their normative reference is
 > `docs/architecture-hardening/`. `enablePropagationContext` defaults **on** — its
 > write-path cost is near-zero for one-way bindings (only echo-capable two-way