@wcstack/state 1.25.0 → 1.27.0

package/dist/index.esm.js

@@ -82,47 +82,6 @@ function setConfig(partialConfig) {
     }
 }
 
-const bindingPromiseByNode = new WeakMap();
-// resolve 済みマーク。エントリ未生成のまま resolve されたノードは、後から
-// wait された時に「生成して即 resolve」で追いつく。
-const resolvedNodes = new WeakSet();
-let id$1 = 0;
-function getInitializeBindingPromiseByNode(node) {
-    let bindingPromise = bindingPromiseByNode.get(node) || null;
-    if (bindingPromise !== null) {
-        return bindingPromise;
-    }
-    let resolveFn = undefined;
-    const promise = new Promise((resolve) => {
-        resolveFn = resolve;
-    });
-    bindingPromise = {
-        id: ++id$1,
-        promise,
-        resolve: resolveFn
-    };
-    bindingPromiseByNode.set(node, bindingPromise);
-    if (resolvedNodes.has(node)) {
-        bindingPromise.resolve();
-    }
-    return bindingPromise;
-}
-async function waitInitializeBinding(node) {
-    const bindingPromise = getInitializeBindingPromiseByNode(node);
-    await bindingPromise.promise;
-}
-function resolveInitializedBinding(node) {
-    // ホットパス: リスト行では全 subscriber ノードがここを通るが、await する消費者
-    // （boundComponent / shadowRoot host）はほぼ居ない。既存エントリが無ければ
-    // Promise+closure を生成せず resolve 済みマークだけ残す（15 万個級の割り当て削減）。
-    const existing = bindingPromiseByNode.get(node);
-    if (typeof existing !== "undefined") {
-        existing.resolve();
-        return;
-    }
-    resolvedNodes.add(node);
-}
-
 const DELIMITER = '.';
 const WILDCARD = '*';
 const MAX_WILDCARD_DEPTH = 128;
@@ -130,6 +89,23 @@ const MAX_LOOP_DEPTH = 128;
 // 因果伝播（Phase 3）の 1 transaction あたり hop 上限。超過分の未処理 record は
 // quarantine し（適用済みの値は戻さない）、updater から例外は投げない。
 const MAX_PROPAGATION_HOPS = 32;
+// `$watch` ハンドラ起点の書き込み連鎖の打ち切り深さ（docs/state-watch-hook-design.md §7-2）。
+// watch ハンドラ内の書き込みは新しい microtask バッチを作るため MAX_PROPAGATION_HOPS の
+// ガードが効かず、書き込み先が動的なので `$streams` のような静的な自己依存検出もできない。
+// 値は MAX_PROPAGATION_HOPS と同値だが、別の打ち切り機構なので定数は共有しない。
+const MAX_WATCH_CHAIN_DEPTH = 32;
+// updater の drain 終了リスナーの実行順（昇順に呼ばれる。設計書 §3-2 層 1）。
+// watch が先なのは、watch ハンドラの書き込みが同じバッチの stream restart 判定に
+// 影響しないようにするため（watch → restart の一方向）。import 順に順序を持たせると
+// 無関係な import 整理で静かに壊れるため、明示的な優先度で固定する。
+//
+// devtools が最も先なのは、`state:update-batch` が「そのバッチに何が載ったか」の
+// 観測であり、watch / restart の副作用が乗る前の生の集合を報告すべきだから。
+// 既定値 0 のまま暗黙に先頭へ入るのに任せず、意図として定数で固定する
+// （docs/devtools-hook-protocol.md §4.3）。
+const DEVTOOLS_LISTENER_PRIORITY = 0;
+const WATCH_LISTENER_PRIORITY = 10;
+const STREAM_LISTENER_PRIORITY = 20;
 // data-wcs バインディング構文 `[prop][#mod]: [path][@state][|filter...]` の区切り文字（単一正本）。
 // これらは「死守の壁（構文契約）」であり値は不変。manifest.syntax.delimiters で公開される。
 const BINDING_SEPARATOR = ';'; // 複数バインディングの区切り
@@ -158,15 +134,59 @@ const STATE_DISCONNECTED_CALLBACK_NAME = "$disconnectedCallback";
 const STATE_UPDATED_CALLBACK_NAME = "$updatedCallback";
 const WEBCOMPONENT_STATE_READY_CALLBACK_NAME = "$stateReadyCallback";
 const STATE_BINDABLES_NAME = "$bindables";
+const STATE_COMMANDS_NAME = "$commands";
 const STATE_COMMAND_TOKENS_NAME = "$commandTokens";
 const STATE_COMMAND_NAMESPACE_NAME = "$command";
 const STATE_EVENT_TOKENS_NAME = "$eventTokens";
 const STATE_ON_NAME = "$on";
 const STATE_STREAMS_NAME = "$streams";
+const STATE_WATCH_NAME = "$watch";
+const STATE_LIST_KEYS_NAME = "$listKeys";
 const STATE_STREAM_STATUS_NAMESPACE_NAME = "$streamStatus";
 const STATE_STREAM_ERROR_NAMESPACE_NAME = "$streamError";
 const DCC_DEFINITION_ATTRIBUTE = "data-wc-definition";
 
+const bindingPromiseByNode = new WeakMap();
+// resolve 済みマーク。エントリ未生成のまま resolve されたノードは、後から
+// wait された時に「生成して即 resolve」で追いつく。
+const resolvedNodes = new WeakSet();
+let id$1 = 0;
+function getInitializeBindingPromiseByNode(node) {
+    let bindingPromise = bindingPromiseByNode.get(node) || null;
+    if (bindingPromise !== null) {
+        return bindingPromise;
+    }
+    let resolveFn = undefined;
+    const promise = new Promise((resolve) => {
+        resolveFn = resolve;
+    });
+    bindingPromise = {
+        id: ++id$1,
+        promise,
+        resolve: resolveFn
+    };
+    bindingPromiseByNode.set(node, bindingPromise);
+    if (resolvedNodes.has(node)) {
+        bindingPromise.resolve();
+    }
+    return bindingPromise;
+}
+async function waitInitializeBinding(node) {
+    const bindingPromise = getInitializeBindingPromiseByNode(node);
+    await bindingPromise.promise;
+}
+function resolveInitializedBinding(node) {
+    // ホットパス: リスト行では全 subscriber ノードがここを通るが、await する消費者
+    // （boundComponent / shadowRoot host）はほぼ居ない。既存エントリが無ければ
+    // Promise+closure を生成せず resolve 済みマークだけ残す（15 万個級の割り当て削減）。
+    const existing = bindingPromiseByNode.get(node);
+    if (typeof existing !== "undefined") {
+        existing.resolve();
+        return;
+    }
+    resolvedNodes.add(node);
+}
+
 const _cache$4 = new Map();
 let id = 0;
 function getPathInfo(path) {
@@ -612,15 +632,6 @@ function getBindingsByNode(node) {
 function setBindingsByNode(node, bindings) {
     bindingsByNode.set(node, bindings);
 }
-function addBindingByNode(node, binding) {
-    const bindings = getBindingsByNode(node);
-    if (bindings === null) {
-        setBindingsByNode(node, [binding]);
-    }
-    else {
-        bindings.push(binding);
-    }
-}
 
 const STRUCTURAL_BINDING_TYPE_SET = new Set([
     "if",
@@ -690,6 +701,15 @@ function valueMustBeBoolean(fnName) {
 function valueMustBeDate(fnName) {
     raiseError(`filter ${fnName} requires a date value`);
 }
+/**
+ * Throws error when filter requires array value but non-array provided.
+ *
+ * @param fnName - Name of the filter function
+ * @returns Never returns (always throws)
+ */
+function valueMustBeArray(fnName) {
+    raiseError(`filter ${fnName} requires an array value`);
+}
 
 /**
  * builtinFilters.ts
@@ -702,7 +722,7 @@ function valueMustBeDate(fnName) {
  * - Designed for common use as both input and output filters
  *
  * Design points:
- * - Comprehensive coverage of diverse filters: eq, ne, lt, gt, inc, fix, locale, uc, lc, cap, trim, slice, pad, int, float, round, date, time, ymd, falsy, truthy, defaults, boolean, number, string, null, etc.
+ * - Comprehensive coverage of diverse filters: eq, ne, lt, gt, inc, abs, clamp, fix, locale, uc, lc, cap, trim, slice, pad, truncate, join, int, float, round, percent, unit, date, time, ymd, hms, falsy, truthy, defaults, boolean, number, string, null, etc.
  * - Rich type checking and error handling for option values
  * - Centralized management of filter functions with FilterWithOptions type, easy to extend
  * - Dynamic retrieval of filter functions from filter names and options via builtinFilterFn
@@ -935,6 +955,48 @@ const mod = (options) => {
         return value % Number(opt);
     };
 };
+/**
+ * Absolute value filter - returns the magnitude of a number.
+ *
+ * @param options - Unused
+ * @returns Filter function that returns the absolute value
+ */
+const abs = (_options) => {
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('abs');
+        }
+        return Math.abs(value);
+    };
+};
+/**
+ * Clamp filter - constrains a number to the inclusive range [min, max].
+ *
+ * Saturating conversion in the same family as round/floor/ceil, so it stays on
+ * the wire rather than in state. Pairs with `unit` for style bindings:
+ * `style.width: ratio|clamp(0,1)|percent(0)`.
+ *
+ * @param options - Array with minimum as first element and maximum as second (both required)
+ * @returns Filter function that returns the clamped number
+ */
+const clamp = (options) => {
+    const opt1 = options?.[0] ?? optionsRequired('clamp');
+    if (!validateNumberString(opt1)) {
+        optionMustBeNumber('clamp');
+    }
+    const opt2 = options?.[1] ?? optionsRequired('clamp');
+    if (!validateNumberString(opt2)) {
+        optionMustBeNumber('clamp');
+    }
+    const min = Number(opt1);
+    const max = Number(opt2);
+    return (value) => {
+        if (typeof value !== 'number') {
+            valueMustBeNumber('clamp');
+        }
+        return Math.min(Math.max(value, min), max);
+    };
+};
 /**
  * Fixed decimal filter - formats number to fixed decimal places.
  *
@@ -1201,6 +1263,76 @@ const percent = (options) => {
         return `${(value * 100).toFixed(Number(opt))}%`;
     };
 };
+/**
+ * Unit filter - appends a CSS unit (or any suffix) to the value.
+ *
+ * A number alone does nothing in CSS, so without this the unit has to be built in
+ * state — which drags presentation into the source of truth, and in the worst case
+ * forces a whole derived array just to carry `"42%"` strings.
+ * `style.height: samples.*.cpu|clamp(0,100)|fix(0)|unit(%)` keeps it on the wire.
+ *
+ * Accepts strings as well as numbers **on purpose**: the useful chains run through
+ * `fix` / `percent`, which already return strings. Rejecting non-numbers here would
+ * break exactly the combination this filter exists for.
+ *
+ * `null` / `undefined` pass through untouched rather than becoming `"undefinedpx"`,
+ * so the binding layer's "undefined skips the write, null clears" semantics survive.
+ *
+ * @param options - Array with the unit/suffix as first element (required)
+ * @returns Filter function that returns the value with the unit appended
+ */
+const unit = (options) => {
+    const opt = options?.[0] ?? optionsRequired('unit');
+    return (value) => {
+        if (value === null || typeof value === 'undefined') {
+            return value;
+        }
+        return String(value) + opt;
+    };
+};
+/**
+ * Join filter - joins array elements into a string.
+ *
+ * The default separator is `", "` rather than `","`: a bare comma is what `String()`
+ * already produces without any filter, so defaulting to it would make `|join` a no-op.
+ *
+ * @param options - Array with separator as first element (default: ', ')
+ * @returns Filter function that returns the joined string
+ */
+const join = (options) => {
+    const opt = options?.[0] ?? ', ';
+    return (value) => {
+        if (!Array.isArray(value)) {
+            valueMustBeArray('join');
+        }
+        return value.join(opt);
+    };
+};
+/**
+ * Truncate filter - shortens a string and appends an ellipsis.
+ *
+ * The length option counts **kept characters**, not the total including the suffix,
+ * matching the existing `slice(0, n)` reading. A string at or below the limit is
+ * returned untouched (no suffix).
+ *
+ * @param options - Array with max kept length as first element and suffix as second (default: '…')
+ * @returns Filter function that returns the truncated string
+ */
+const truncate = (options) => {
+    const opt1 = options?.[0] ?? optionsRequired('truncate');
+    if (!validateNumberString(opt1)) {
+        optionMustBeNumber('truncate');
+    }
+    const maxLength = Number(opt1);
+    const suffix = options?.[1] ?? '…';
+    return (value) => {
+        const v = String(value);
+        if (v.length <= maxLength) {
+            return v;
+        }
+        return v.slice(0, maxLength) + suffix;
+    };
+};
 /**
  * Date filter - formats Date object as localized date string.
  *
@@ -1264,6 +1396,27 @@ const ymd = (options) => {
         return `${year}${opt}${month}${opt}${day}`;
     };
 };
+/**
+ * Hour-Minute-Second filter - formats Date object as HH:MM:SS string.
+ *
+ * The counterpart of `ymd`: a fixed, zero-padded, locale-independent rendering with a
+ * configurable separator, for when `time` (locale-formatted) is not stable enough.
+ *
+ * @param options - Array with separator string as first element (default: ':')
+ * @returns Filter function that returns formatted time string
+ */
+const hms = (options) => {
+    const opt = options?.[0] ?? ':';
+    return (value) => {
+        if (!(value instanceof Date)) {
+            valueMustBeDate('hms');
+        }
+        const hours = value.getHours().toString().padStart(2, '0');
+        const minutes = value.getMinutes().toString().padStart(2, '0');
+        const seconds = value.getSeconds().toString().padStart(2, '0');
+        return `${hours}${opt}${minutes}${opt}${seconds}`;
+    };
+};
 /**
  * Falsy filter - checks if value is falsy.
  *
@@ -1354,6 +1507,8 @@ const builtinFilters = {
     "mul": mul,
     "div": div,
     "mod": mod,
+    "abs": abs,
+    "clamp": clamp,
     "fix": fix,
     "locale": locale,
     "uc": uc,
@@ -1365,16 +1520,20 @@ const builtinFilters = {
     "pad": pad,
     "rep": rep,
     "rev": rev,
+    "truncate": truncate,
+    "join": join,
     "int": int,
     "float": float,
     "round": round,
     "floor": floor,
     "ceil": ceil,
     "percent": percent,
+    "unit": unit,
     "date": date,
     "time": time,
     "datetime": datetime,
     "ymd": ymd,
+    "hms": hms,
     "falsy": falsy,
     "truthy": truthy,
     "defaults": defaults,
@@ -1404,11 +1563,44 @@ const builtinFilterFn = (name, options) => (filters) => {
     return filter(options);
 };
 
+/**
+ * フィルタ引数リストのパース。`filter(a, b)` の `a, b` 部分を受け取る。
+ *
+ * トリムの規則は「**クォートの外側だけ**」。`fix( 2 )` のような書き癖を吸収するために
+ * 素の引数は前後をトリムするが、クォートは「ここは literal」という宣言なので中身の
+ * 空白は残す。両方まとめてトリムしていたため `pad(5, ' ')` が空文字パディング
+ * （＝無変化）に化けており、空白区切りの `join(' / ')` も指定できなかった。
+ */
+/** 引数 1 つを確定する。クォート由来の文字が入った範囲より外側だけをトリムする。 */
+function finalizeArg(text, firstQuoteStart, lastQuoteEnd) {
+    // 先頭側: 最初のクォート文字より前だけが削れる（クォートが無ければ全体が対象）
+    const startLimit = firstQuoteStart === -1 ? text.length : firstQuoteStart;
+    let start = 0;
+    while (start < startLimit && /\s/.test(text[start])) {
+        start++;
+    }
+    // 末尾側: 最後のクォート文字より後ろだけが削れる（クォートが無ければ全体が対象）
+    const endLimit = lastQuoteEnd === -1 ? 0 : lastQuoteEnd;
+    let end = text.length;
+    while (end > endLimit && /\s/.test(text[end - 1])) {
+        end--;
+    }
+    return text.slice(start, end);
+}
 function parseFilterArgs(argsText) {
     const args = [];
     let current = '';
     let inQuote = null;
     let hasQuote = false;
+    let firstQuoteStart = -1;
+    let lastQuoteEnd = -1;
+    const flush = () => {
+        args.push(finalizeArg(current, firstQuoteStart, lastQuoteEnd));
+        current = '';
+        hasQuote = false;
+        firstQuoteStart = -1;
+        lastQuoteEnd = -1;
+    };
     for (let i = 0; i < argsText.length; i++) {
         const char = argsText[i];
         if (inQuote) {
@@ -1416,7 +1608,11 @@ function parseFilterArgs(argsText) {
                 inQuote = null;
             }
             else {
+                if (firstQuoteStart === -1) {
+                    firstQuoteStart = current.length;
+                }
                 current += char;
+                lastQuoteEnd = current.length;
             }
         }
         else if (char === '"' || char === "'") {
@@ -1424,15 +1620,13 @@ function parseFilterArgs(argsText) {
             hasQuote = true;
         }
         else if (char === ',') {
-            args.push(current.trim());
-            current = '';
-            hasQuote = false;
+            flush();
         }
         else {
             current += char;
         }
     }
-    const last = current.trim();
+    const last = finalizeArg(current, firstQuoteStart, lastQuoteEnd);
     if (last || hasQuote) {
         args.push(last);
     }
@@ -1785,13 +1979,97 @@ function getParseBindTextResults(node) {
     return [];
 }
 
+/**
+ * bindings/lightDomComponentScope.ts — Light DOM の mapped `bind-component` を
+ * 「ホストとは別のバインディングスコープ」として扱うための判定
+ * （docs/architecture-hardening/15-state-component-mechanism-consistency.md §1.13）。
+ *
+ * Shadow DOM 形では、コンポーネントの `<wcs-state>` が**別 rootNode** にいることで
+ * 2 つのことが同時に成立している。
+ *
+ * 1. ホスト root の `waitForStateInitialize` の走査集合に入らない
+ * 2. 子スコープのバインディングがホストとは別の `buildBindings` パスで処理される
+ *
+ * Light DOM では両方が失われる。1 が失われると、
+ * 「ホストの `waitForStateInitialize` が子 state を待つ →
+ *   子 state は自分を束ねるホスト binding を待つ →
+ *   その binding を作る `initializeBindings` は `waitForStateInitialize` の後」
+ * という循環になり、初期化が永久に解決しない。2 が失われると、子スコープの
+ * `@name` 参照がホストと同じパスで解決されてしまい、子 state の名前登録より
+ * 先に評価される。
+ *
+ * このモジュールはその 2 つを明示的に復元するための判定だけを持つ。
+ *
+ * **plain（ホストからバインドしない state 注入）は対象外**であることに注意。
+ * plain は `waitInitializeBinding` を通らないので循環せず、従来どおりホストと
+ * 同じパスで初期化して問題ない。ここで一律に切り出すと、成立している plain 形が
+ * 「子 state の登録前に `@name` を解決する」形に退行する。
+ */
+/** `<wcs-state bind-component>` が Light DOM の mapped 形（＝別スコープ扱い）か。 */
+function isLightDomMappedStateElement(stateElement) {
+    if (!stateElement.hasAttribute("bind-component")) {
+        return false;
+    }
+    const parentNode = stateElement.parentNode;
+    // Shadow DOM 形では parentNode が ShadowRoot になる（かつホスト root の
+    // querySelectorAll にはそもそも出てこない）
+    if (!(parentNode instanceof Element)) {
+        return false;
+    }
+    // ホストからバインドされていなければ plain。従来どおりの扱いに任せる
+    return parentNode.hasAttribute(config.bindAttributeName);
+}
+/**
+ * `root` の内側にある Light DOM mapped コンポーネント要素を集める。
+ *
+ * `root` 自身は**含めない**。子スコープが自分のパスとして
+ * `initializeBindings(componentElement)` を呼ぶとき、その要素自身まで prune すると
+ * 何も初期化されなくなるため。
+ */
+function findNestedLightDomComponents(root) {
+    const components = [];
+    const stateElements = root.querySelectorAll(`${config.tagNames.state}[bind-component]`);
+    for (const stateElement of stateElements) {
+        if (!isLightDomMappedStateElement(stateElement)) {
+            continue;
+        }
+        const component = stateElement.parentNode;
+        if (component === root) {
+            continue;
+        }
+        components.push(component);
+    }
+    return components;
+}
+/** `node` が、いずれかのコンポーネント要素の**真の**子孫か。 */
+function isInsideAnyComponent(node, components) {
+    for (let i = 0; i < components.length; i++) {
+        const component = components[i];
+        if (component !== node && component.contains(node)) {
+            return true;
+        }
+    }
+    return false;
+}
+
 /**
  * data-wcs 属性または埋め込みノード<!--{{}}-->を持つノードをすべて取得する
+ *
+ * Light DOM の mapped コンポーネントの**内側**は除外する（§1.13）。そのサブツリーの
+ * `@name` 参照は、コンポーネント側の state が名前登録を済ませてからでないと解決できず、
+ * ホストと同じパスで拾うと登録前に評価されてしまう。除外したぶんは、その state が
+ * 初期化を終えた時点で自分のスコープとして `initializeBindings(componentElement)` を
+ * 呼び直す（Shadow DOM 形で rootNode ごとにパスが分かれるのと同じ形にする）。
+ *
+ * コンポーネント要素**自身**は除外しない。ホスト側の `data-wcs`（`state.msg: user.name`）
+ * はホストのスコープに属し、それが張られることで子側の待ちが解ける。
+ *
  * @param root
  * @returns
  */
 function getSubscriberNodes(root) {
     const subscriberNodes = [];
+    const nestedComponents = findNestedLightDomComponents(root);
     const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_COMMENT, {
         acceptNode(node) {
             if (node.nodeType === Node.ELEMENT_NODE) {
@@ -1810,7 +2088,14 @@ function getSubscriberNodes(root) {
         }
     });
     while (walker.nextNode()) {
-        subscriberNodes.push(walker.currentNode);
+        const node = walker.currentNode;
+        // TreeWalker の acceptNode は「自分は拾うが子孫は辿らない」を表現できないため、
+        // コンポーネント要素自身を拾ったうえで、その子孫をここで落とす。
+        // nestedComponents が空（＝圧倒的多数）のときは contains 走査ごと発生しない。
+        if (nestedComponents.length > 0 && isInsideAnyComponent(node, nestedComponents)) {
+            continue;
+        }
+        subscriberNodes.push(node);
     }
     return subscriberNodes;
 }
@@ -2058,6 +2343,56 @@ function calcWildcardLen(pathInfo, targetPathInfo) {
     return len;
 }
 
+/**
+ * list/wildcardLevel.ts
+ *
+ * 「パス上のワイルドカード位置」→「listIndex チェーン上の段」の変換を 1 箇所に集める。
+ *
+ * チェーンの長さは常に `Δ + W`（W = そのパスの wildcardCount、Δ = そのスコープの
+ * base 深さ）である。通常の state スコープは Δ=0 なので「位置 i ＝ 段 i」で済んでいたが、
+ * `bind-component` の子スコープがホストの `for` の内側にいる場合は Δ>0 になる
+ * （docs/state-bind-component-nested-for-design.md）。
+ *
+ * そこで**先頭ではなく末尾を基準に数える**。`IListIndex.at()` は負値を受けるので:
+ *
+ *     at(i)  →  at(i - W)      // listIndexes[(Δ+W) + (i-W)] = listIndexes[Δ+i]
+ *
+ * Δ=0 のときは両者が同じ要素を指すため、この書き換えは既存スコープに対して
+ * 意味論を変えない。Δ の値を呼び出し側へ配管する必要も無い。
+ */
+/**
+ * ワイルドカード位置 `wildcardPos`（先頭から 0 始まり）に対応する listIndex を返す。
+ * `wildcardCount` は `wildcardPos` が属するパスのワイルドカード総数。
+ *
+ * 範囲外（`wildcardPos >= wildcardCount`）は null。Δ=0 では `at(pos)` が
+ * チェーン長を超えて null を返していたのと同じ結果になる。**このガードは必須**で、
+ * 落とすと「1 段ループの中で `$2` を読む」が黙って `$1` を返す
+ * （末尾起点では `at(1-1)=at(0)` に化けるため）。
+ */
+function listIndexAtWildcard(listIndex, wildcardPos, wildcardCount) {
+    if (wildcardPos < 0 || wildcardPos >= wildcardCount) {
+        return null;
+    }
+    return listIndex.at(wildcardPos - wildcardCount);
+}
+/**
+ * ユーザーランドへ渡すインデックス列。チェーンの先頭 Δ 段（base）を落とし、
+ * **そのスコープ自身のループ分だけ**にする。
+ *
+ * コンポーネントの作者は、自分がリストの中に置かれるかどうかを知らずに書く。
+ * `$1` や `onClick(event, index)` の意味が設置場所で変わってはいけないので、
+ * Δ は境界の内側に閉じ込める。`$resolve(path, indexes)` は台帳の配列位置で
+ * 引くため、ここで返した列がそのまま往復で使える。
+ */
+function getScopedIndexes(listIndex, wildcardCount) {
+    // indexes は型上は必須だが、防御的フォールバックを既存挙動として持っている
+    const indexes = listIndex.indexes ?? [];
+    if (indexes.length === wildcardCount) {
+        return indexes;
+    }
+    return indexes.slice(indexes.length - wildcardCount);
+}
+
 const listIndexByBindingInfoByLoopContext = new WeakMap();
 function getListIndexByBindingInfo(bindingInfo) {
     const loopContext = getLoopContextByNode(bindingInfo.node);
@@ -2079,7 +2414,7 @@ function getListIndexByBindingInfo(bindingInfo) {
     try {
         const wildcardLen = calcWildcardLen(loopContext.pathInfo, bindingInfo.statePathInfo);
         if (wildcardLen > 0) {
-            listIndex = loopContext.listIndex.at(wildcardLen - 1);
+            listIndex = listIndexAtWildcard(loopContext.listIndex, wildcardLen - 1, loopContext.pathInfo.wildcardCount);
         }
         return listIndex;
     }
@@ -2599,12 +2934,12 @@ class EventToken extends Token {
     }
 }
 
-const registryByStateElement$2 = new WeakMap();
+const registryByStateElement$3 = new WeakMap();
 function getOrCreateEventToken(stateElement, name) {
-    let registry = registryByStateElement$2.get(stateElement);
+    let registry = registryByStateElement$3.get(stateElement);
     if (typeof registry === "undefined") {
         registry = new Map();
-        registryByStateElement$2.set(stateElement, registry);
+        registryByStateElement$3.set(stateElement, registry);
     }
     let token = registry.get(name);
     if (typeof token === "undefined") {
@@ -2614,7 +2949,7 @@ function getOrCreateEventToken(stateElement, name) {
     return token;
 }
 function clearEventTokenRegistry(stateElement) {
-    registryByStateElement$2.delete(stateElement);
+    registryByStateElement$3.delete(stateElement);
 }
 
 /**
@@ -2702,7 +3037,8 @@ function attachEventTokenHandler(binding) {
         const loopContext = getLoopContextByNode(element);
         stateElement.createStateAsync("writable", async (state) => {
             const results = state[setLoopContextSymbol](loopContext, () => {
-                const indexes = loopContext?.listIndex.indexes ?? [];
+                const indexes = loopContext !== null
+                    ? getScopedIndexes(loopContext.listIndex, loopContext.pathInfo.wildcardCount) : [];
                 const token = getOrCreateEventToken(stateElement, tokenName);
                 return token.emit(state, event, ...indexes);
             });
@@ -2787,7 +3123,8 @@ const stateEventHandlerFunction = (stateName, handlerName, modifiers, statePathI
     const isCommand = isCommandTokenPath(handlerName);
     stateElement.createStateAsync("writable", async (state) => {
         const results = state[setLoopContextSymbol](loopContext, () => {
-            const indexes = loopContext?.listIndex.indexes ?? [];
+            const indexes = loopContext !== null
+                ? getScopedIndexes(loopContext.listIndex, loopContext.pathInfo.wildcardCount) : [];
             if (isCommand) {
                 // command token を解決して emit。引数はハンドラ呼び出しと同じく (event, ...listIndexes) を透過する。
                 const token = state[getByAddressSymbol](createStateAddress(statePathInfo, null));
@@ -3356,33 +3693,482 @@ function detachTwowayEventHandler(binding) {
     }
 }
 
-// framework 自身が detach し明示的に解体（deactivate/unmount）したノード。
-// BindingOwner の MutationObserver は削除サブツリー走査でこれらをスキップする。
-//
-// 根拠: 削除時の handleRemovedNode は binding を dispose するだけ（DOM 構造変更も
-// connect-snapshot 依存も無い）で、framework が unmount 経路で既に dispose 済みの
-// content に対しては純粋な冗長走査（forEachInclusive で削除サブツリー全体を歩く）に
-// なる。create（追加）経路は two-way の connect-time snapshot を observer に依存する
-// ため対象外だが、削除は依存が無いため安全に飛ばせる。
-//
-// マークは observer が削除を配送した時点で消費（削除）する。マーク〜配送の間隔は
-// 単一 microtask であり、その間に外部 DOM 変異は割り込めない（framework の drain は
-// 同期）ため、マークは framework 由来の削除にしか一致しない。
-const observerSkipNodes = new WeakSet();
-function markObserverSkipOnRemove(node) {
-    observerSkipNodes.add(node);
+const stateElementByWebComponent = new WeakMap();
+function setStateElementByWebComponent(webComponent, stateName, stateElement) {
+    let stateMap = stateElementByWebComponent.get(webComponent);
+    if (!stateMap) {
+        stateMap = new Map();
+        stateElementByWebComponent.set(webComponent, stateMap);
+    }
+    stateMap.set(stateName, stateElement);
 }
-// マーク済みなら true を返しつつマークを消費する。未マークなら false。
-function consumeObserverSkipOnRemove(node) {
-    if (!observerSkipNodes.has(node)) {
-        return false;
+function getStateElementByWebComponent(webComponent, stateName) {
+    const stateMap = stateElementByWebComponent.get(webComponent);
+    if (!stateMap) {
+        return null;
     }
-    observerSkipNodes.delete(node);
-    return true;
+    return stateMap.get(stateName) ?? null;
 }
-// framework 自身がマウント（Content.appendTo / mountAfter）したノード。
-// 追加サブツリー走査の実質の仕事は connect-snapshot 待ち（observationPending）の
-// record への配送だけで、record 自体は同期マウント（activateContent → start）で
+/**
+ * コンポーネントが mapped されている「1 つ外のスコープ」の state 要素。
+ * `buildPrimaryMappingRule` がプライマリ規則から記録する
+ * （規則の outer 側が属する state 要素 ＝ 値の正本を持つスコープそのもの）。
+ *
+ * 用途は Δ（base listIndex）の境界越え合成（§1.12）。`getLoopContextByNode` は
+ * `parentNode` しか辿らず shadow 境界を越えないため、Δ を外へ引き継ぐには
+ * 「1 つ外のスコープ」への明示的なリンクが要る。
+ *
+ * この台帳を MappingRule ではなくここに置くのは循環参照を避けるため
+ * （baseListIndex → MappingRule → BindingSession → outerListPath → baseListIndex）。
+ */
+const outerStateElementByWebComponent = new WeakMap();
+function setOuterStateElementByWebComponent(webComponent, stateElement) {
+    outerStateElementByWebComponent.set(webComponent, stateElement);
+}
+function getOuterStateElementByWebComponent(webComponent) {
+    return outerStateElementByWebComponent.get(webComponent) ?? null;
+}
+
+/**
+ * webComponent/baseListIndex.ts
+ *
+ * mapped な `bind-component` の子スコープが「親スコープのどの行の内側にいるか」。
+ *
+ * ホストのコンポーネント要素が親スコープの `for` の中に置かれている場合、
+ * 子スコープは実際には**ネストしたループの内側**にいる。その深さ Δ を表すのが
+ * base listIndex で、子が作る listIndex はすべてこれを親に持つ。
+ * 結果として `groups[i].children` の listIndex 台帳は arity Δ+1 になり、
+ * これは親が `groups.*.children.*` に対して要求するものと同一になる
+ * （台帳 `listIndexesByList` は配列オブジェクト同一性の WeakMap なので、
+ * 1 つの配列につき 1 組しか持てない。親子で同じ組を使うのが唯一の整合手段）。
+ *
+ * 詳細は docs/state-bind-component-nested-for-design.md。
+ *
+ * **キャッシュしてはいけない。** 行 content はプールで再利用されるため、同じ
+ * コンポーネント要素が別の行に付け替わる。要素をキーにした memo は §1.9 で
+ * 踏んだ罠そのもので、再接続後に古い行を指し続ける。
+ * 通常の state（`hasMappedComponentState` が偽）は最初の 1 行で抜けるので、
+ * ホットパスに walk は載らない。
+ */
+function getBaseListIndex(stateElement) {
+    let current = stateElement;
+    for (;;) {
+        if (current == null || current.hasMappedComponentState !== true) {
+            return null;
+        }
+        const component = current.boundComponent;
+        if (component == null) {
+            return null;
+        }
+        const listIndex = getLoopContextByNode(component)?.listIndex;
+        if (listIndex != null) {
+            return listIndex;
+        }
+        // このスコープには囲むループが無い。コンポーネントがさらに別の mapped な
+        // コンポーネントの shadow の中にいるなら、Δ は外側スコープから引き継ぐ（§1.12）。
+        //
+        // `getLoopContextByNode` は `parentNode` しか辿らず、ShadowRoot の parentNode は
+        // null なので shadow 境界で必ず止まる。境界 1 枚なら外側は素の文書スコープで
+        // Δ=0 が正しいが、2 枚重なっていると中間スコープの Δ が丸ごと落ちて
+        // 子の listIndex が正本スコープより浅い arity で作られる。
+        //
+        // 外側が mapped でない（＝値の正本がそのスコープにある）なら、そこから先の
+        // ループはこの子のリストとは無関係なので次の周回の先頭ガードで止まる。
+        current = getOuterStateElementByWebComponent(component);
+    }
+}
+/** base の段数 Δ。base が無ければ 0。 */
+function getBaseDepth(stateElement) {
+    return getBaseListIndex(stateElement)?.length ?? 0;
+}
+/**
+ * そのスコープでそのパスに実際に使われる listIndex の arity。
+ *
+ * パス自身のワイルドカード段数に、そのスコープが外側のループの内側にいる分（Δ）を
+ * 足したもの。`items.*` は子スコープから見れば 1 段でも、そのスコープが Δ=1 の位置に
+ * あれば台帳の listIndex は arity 2 になる（§1.10）。
+ *
+ * **境界を跨ぐ照合はこの実 arity どうしで行うこと**（§1.12）。片側だけ Δ を足すと、
+ * 境界が 2 枚以上あるときに中間スコープの Δ を二重計上して不一致になる。
+ */
+function getScopeArity(stateElement, pathInfo) {
+    return pathInfo.wildcardCount + getBaseDepth(stateElement);
+}
+/**
+ * リストの行を生成するときの親 listIndex。
+ *
+ * コンテナのアドレスがワイルドカードを持つ（＝囲むループがある）ならその listIndex、
+ * 持たない（＝そのスコープのトップレベルのリスト）なら base。後者を null のままに
+ * すると、子スコープのリストだけ arity 1 で作られて親の台帳と食い違う。
+ *
+ * **リストの行を作りうる全経路で使うこと。** 既存台帳があれば `createListDiff` は
+ * 再利用するので初期描画では食い違いが見えず、**行を追加したときだけ**
+ * `createListIndex(parentListIndex, i)` が新しい arity で作られて混在する。
+ */
+function getListParentListIndex(stateElement, containerListIndex) {
+    return containerListIndex ?? getBaseListIndex(stateElement);
+}
+
+const innerMappingByElement = new WeakMap();
+const outerMappingByElement = new WeakMap();
+const primaryMappingRuleSetByElement = new WeakMap();
+const primaryBindingByMappingRule = new WeakMap();
+function createMappingRuleByBinding(innerState, binding) {
+    const innerPathInfo = getPathInfo(binding.propSegments.slice(1).join(DELIMITER));
+    const innerAbsPathInfo = getAbsolutePathInfo(innerState, innerPathInfo);
+    const outerAbsStateAddress = getAbsoluteStateAddressByBinding(binding);
+    const outerAbsPathInfo = outerAbsStateAddress.absolutePathInfo;
+    return { innerAbsPathInfo, outerAbsPathInfo };
+}
+function buildPrimaryMappingRule(webComponent, stateName, bindings) {
+    if (bindings.length === 0) {
+        return;
+    }
+    const innerState = getStateElementByWebComponent(webComponent, stateName);
+    if (innerState === null) {
+        raiseError('State element not found for web component.');
+    }
+    const innerMappingRule = new Map();
+    const outerMappingRule = new Map();
+    for (const binding of bindings) {
+        const mappingRule = createMappingRuleByBinding(innerState, binding);
+        let primaryMappingRuleSet = primaryMappingRuleSetByElement.get(webComponent);
+        if (typeof primaryMappingRuleSet === 'undefined') {
+            primaryMappingRuleSetByElement.set(webComponent, new Set([mappingRule]));
+        }
+        else {
+            primaryMappingRuleSet.add(mappingRule);
+        }
+        const innerAbsPathInfo = mappingRule.innerAbsPathInfo;
+        const outerAbsPathInfo = mappingRule.outerAbsPathInfo;
+        primaryBindingByMappingRule.set(mappingRule, binding);
+        innerMappingRule.set(innerAbsPathInfo, outerAbsPathInfo);
+        outerMappingRule.set(outerAbsPathInfo, innerAbsPathInfo);
+        // 1 つ外のスコープへのリンク。Δ の境界越え合成（§1.12）が引く。
+        // プライマリ規則はすべて同じホスト要素の data-wcs 由来なので、どの規則から
+        // 採っても同じスコープを指す。
+        setOuterStateElementByWebComponent(webComponent, outerAbsPathInfo.stateElement);
+    }
+    innerMappingByElement.set(webComponent, innerMappingRule);
+    outerMappingByElement.set(webComponent, outerMappingRule);
+}
+/**
+ * プライマリ規則だけを残して、遅延導出された派生規則の memo を捨てる（§1.9）。
+ *
+ * 派生規則は導出と同時に「親スコープの購読者」を立てる。その購読者は子の切断で
+ * teardown されるが、memo は要素をキーに残り続けるため、再接続後は**導出が二度と
+ * 走らず購読者も張り直されない** — 親がサブパスへ書いても子に届かなくなる。
+ * リスト行の content 再利用で実際に踏む（行を差し替えると、その行の子だけが
+ * 以後の行フィールド書き込みを受け取れない）。
+ *
+ * `buildPrimaryMappingRule` は再バインド時に同じことをしている（台帳を作り直す）。
+ * 再接続では bindWebComponent が走らないので、ここで同じ状態に戻す。
+ */
+function resetDerivedMappingRules(webComponent) {
+    const primaryMappingRuleSet = primaryMappingRuleSetByElement.get(webComponent);
+    if (typeof primaryMappingRuleSet === 'undefined') {
+        return;
+    }
+    const innerMappingRule = new Map();
+    const outerMappingRule = new Map();
+    for (const rule of primaryMappingRuleSet) {
+        innerMappingRule.set(rule.innerAbsPathInfo, rule.outerAbsPathInfo);
+        outerMappingRule.set(rule.outerAbsPathInfo, rule.innerAbsPathInfo);
+    }
+    innerMappingByElement.set(webComponent, innerMappingRule);
+    outerMappingByElement.set(webComponent, outerMappingRule);
+}
+/**
+ * このコンポーネントに張られたプライマリ規則の**内側パス**を列挙する。
+ *
+ * 切断 → 再接続を跨いだ子（行 content の再利用で起きる）は、切断中に親で起きた変更の
+ * 通知を受け取れていない。再接続時に「束ねているパスを読み直せ」と撃つための入力で、
+ * 何が変わったかは分からないのでプライマリ規則の粒度で丸ごと読み直す（§1.9）。
+ */
+function getPrimaryInnerPaths(webComponent) {
+    const primaryMappingRuleSet = primaryMappingRuleSetByElement.get(webComponent);
+    if (typeof primaryMappingRuleSet === 'undefined') {
+        return [];
+    }
+    const paths = [];
+    for (const rule of primaryMappingRuleSet) {
+        paths.push(rule.innerAbsPathInfo.pathInfo.path);
+    }
+    return paths;
+}
+/**
+ * 内側のパスを外側のパスへ翻訳する。規則が無ければプライマリ規則から導出する。
+ *
+ * `registerSubscriber` は導出に**副作用を持たせるか**の切り替え。既定（子の read /
+ * write からの呼び出し）では導出した規則を台帳に memo し、対応するバインディングを
+ * 親スコープの購読者として登録する。`false` を渡すと**参照専用**になり、台帳にも
+ * 購読者にも触れない。
+ *
+ * 参照専用が要るのは、バインディング登録の最中（`BindingSession.registerAddress` →
+ * `setPathInfo` / 行の相乗り登録）に翻訳だけしたい場合。ここで購読者登録まで走ると
+ * `session.initialize` がセッション操作の内側から再入する。
+ *
+ * 参照専用の結果を台帳に memo しないのは、後から来た**本物の read が memo に当たって
+ * 購読者登録を永久に飛ばしてしまう**ため。導出のやり直しは初回だけで、以降は本物の
+ * read が張った memo に当たる（行 2 本目以降の登録は先頭行の read が埋めた台帳を引く）。
+ */
+function getOuterAbsolutePathInfo(webComponent, innerAbsPathInfo, registerSubscriber = true) {
+    let innerMapping = innerMappingByElement.get(webComponent);
+    if (typeof innerMapping === 'undefined') {
+        innerMapping = new Map();
+        innerMappingByElement.set(webComponent, innerMapping);
+    }
+    if (innerMapping.has(innerAbsPathInfo)) {
+        return innerMapping.get(innerAbsPathInfo);
+    }
+    let outerMapping = outerMappingByElement.get(webComponent);
+    if (typeof outerMapping === 'undefined') {
+        outerMapping = new Map();
+        outerMappingByElement.set(webComponent, outerMapping);
+    }
+    // 内側からのアクセスの場合、ルールがなければプライマリルールから新たにルールとバインディングを生成する
+    const primaryMappingRuleSet = primaryMappingRuleSetByElement.get(webComponent);
+    if (typeof primaryMappingRuleSet === 'undefined') {
+        // マッピングルールが存在しない場合はnullを返し、ローカル状態へのフォールバックを許可する
+        return null;
+    }
+    let primaryMappingRule = null;
+    for (const currentPrimaryMappingRule of primaryMappingRuleSet) {
+        // innerPathInfoがprimaryMappingRuleのinnerPathInfoを包含しているか
+        if (!innerAbsPathInfo.pathInfo.cumulativePathInfoSet.has(currentPrimaryMappingRule.innerAbsPathInfo.pathInfo)) {
+            continue;
+        }
+        if (currentPrimaryMappingRule.innerAbsPathInfo.pathInfo.segments.length === innerAbsPathInfo.pathInfo.segments.length) {
+            raiseError('Duplicate mapping rule for web component.');
+        }
+        primaryMappingRule = currentPrimaryMappingRule;
+        break;
+    }
+    if (primaryMappingRule === null) {
+        // マッピングルールに一致しない場合はnullを返し、ローカル状態へのフォールバックを許可する
+        return null;
+    }
+    // マッチした残りのパスをouterPathInfoに付与して新たなルールを生成
+    const primaryBinding = primaryBindingByMappingRule.get(primaryMappingRule);
+    /* c8 ignore start */
+    if (typeof primaryBinding === 'undefined') {
+        raiseError('Binding not found for primary mapping rule on web component.');
+    }
+    /* c8 ignore stop */
+    const outerRemainingSegments = innerAbsPathInfo.pathInfo.segments.slice(primaryMappingRule.innerAbsPathInfo.pathInfo.segments.length);
+    const outerSegments = primaryMappingRule.outerAbsPathInfo.pathInfo.segments.concat(outerRemainingSegments);
+    const outerPathInfo = getPathInfo(outerSegments.join(DELIMITER));
+    const rootNode = webComponent.getRootNode();
+    const outerStateElement = getStateElementByName(rootNode, primaryBinding.stateName);
+    if (outerStateElement === null) {
+        raiseError(`State element with name "${primaryBinding.stateName}" not found for web component.`);
+    }
+    const outerAbsPathInfo = getAbsolutePathInfo(outerStateElement, outerPathInfo);
+    if (!registerSubscriber) {
+        // 参照専用: 台帳にも購読者にも触れず、翻訳結果だけ返す
+        return outerAbsPathInfo;
+    }
+    innerMapping.set(innerAbsPathInfo, outerAbsPathInfo);
+    outerMapping.set(outerAbsPathInfo, innerAbsPathInfo);
+    // ルールに対応するバインディングを生成し、親スコープの購読者として登録する。
+    //
+    // 子が読んだサブパス（inner "user.name" ＝ outer "person.name"）は、子が
+    // そのパスに関心を宣言したということ。親がそこへ書いたときに子へ再読込通知が
+    // 届くよう、プライマリと同じ形のバインディングを立てて絶対アドレス台帳に載せる。
+    //
+    // propSegments は stateProp（プライマリの先頭セグメント）を保つ必要がある。
+    // 適用側は先頭セグメントで束ね先の state 要素を引く（apply/applyChangeToWebComponent.ts）
+    // ため、inner パスだけにすると通知先を解決できない。
+    //
+    // 登録はプライマリを所有する BindingSession 経由で行う。台帳登録・teardown・
+    // ノード削除時の破棄（MutationObserver 配送）が既存のライフサイクルにそのまま乗り、
+    // 絶対アドレス台帳のエントリが component を強参照したまま残るのを防ぐ。
+    // node 台帳（addBindingByNode）へは積まない — stateProp を保った結果、
+    // 再バインド時に buildPrimaryMappingRule のプライマリ抽出フィルタへ混入するため。
+    const propSegments = [primaryBinding.propSegments[0], ...innerAbsPathInfo.pathInfo.segments];
+    const newBinding = {
+        ...primaryBinding,
+        propName: propSegments.join(DELIMITER),
+        propSegments,
+        statePathName: outerAbsPathInfo.pathInfo.path,
+        statePathInfo: outerAbsPathInfo.pathInfo,
+    };
+    // 登録できないケースは登録だけ諦める。ここは翻訳が本務なので read を落とさない
+    // ＝ この機構が入る前と同じ挙動に留める（debug 時のみ観測可能にする）。2 通りある。
+    //
+    // (a) セッションが引けない: 内部的な想定外（プライマリは親スコープの収集で必ず
+    //     session.initialize を通っている）。
+    // (b) 導出した outer パスがワイルドカードを含むのに listIndex が決まらない:
+    //     子が配列マッピングの上で for を回している場合（規則 state.items: rows に対し
+    //     子の行が items.*.name を読む → outer は rows.*.name）。派生バインディングの
+    //     node は親スコープにあるコンポーネント要素で、ループは子の Shadow 内なので
+    //     コンポーネントからは行を特定できない ＝ この 1 本では行を表現できない。
+    //     ここで登録を試みると getAbsoluteStateAddressByBinding が raiseError する。
+    //     この形の親→子配送は派生バインディングではなく、子の行バインディング自身を
+    //     親のパターン台帳（(absolutePathInfo, listIndex)）へ相乗りさせて成立させる
+    //     （BindingSession.registerAddress / webComponent/outerListPath.ts、§1.8）。
+    const skipRegistration = (reason) => {
+        if (config.debug) {
+            console.warn(`parent→child notification for "${outerAbsPathInfo.pathInfo.path}" is not registered: ${reason}.`, { webComponent, primaryBinding });
+        }
+    };
+    const session = getBindingSession(primaryBinding);
+    if (session === null) {
+        skipRegistration('no binding session for the primary mapping rule');
+        return outerAbsPathInfo;
+    }
+    if (outerAbsPathInfo.pathInfo.wildcardCount > 0 && getListIndexByBindingInfo(newBinding) === null) {
+        skipRegistration('the derived outer path is a wildcard path but no list index resolves from the component');
+        return outerAbsPathInfo;
+    }
+    // 戻り値（初期 apply 対象）は使わない。この導出は子の read の最中に起きるので、
+    // 子は既に最新値を読んでおり、ここでの再通知は冗長かつ再入になる。
+    session.initialize([newBinding], { registerAddress: true });
+    return outerAbsPathInfo;
+}
+
+/**
+ * webComponent/outerListPath.ts
+ *
+ * mapped な `bind-component` の子スコープが宣言した「リスト」を、値の正本を持つ
+ * 親スコープ側へ伝えるための翻訳ヘルパ
+ * （docs/architecture-hardening/15-state-component-mechanism-consistency.md §1.8）。
+ *
+ * 子の `for: items` が登録するのは子の state 要素の listPaths / elementPaths だけで、
+ * 配列の実体を持つ親 state 要素は `rows` がリストであることを知らないままだった。
+ * 親が `rows` を書いたときの依存 walk は `rows → rows.*` の静的子展開を
+ * listPaths で判定するため、未登録だと行ごとの listIndex に展開されず
+ * 「listIndex null のワイルドカードアドレス」1 本に潰れる（誰にも届かない）。
+ * `rows.*` が elementPaths に無いと、行そのものへの代入（swap イディオム）も
+ * listIndex 台帳の付け替えを伴わない素の代入に落ちる。
+ */
+/**
+ * 子スコープの `for:` パスに対応する親スコープのパスへ「これはリストだ」を伝える。
+ * マッピング規則が無い（plain なコンポーネント / ローカル state のリスト）場合は何もしない。
+ *
+ * 親がさらに別コンポーネントの mapped state であれば、その親の `setPathInfo` から
+ * 再びここへ入って外向きに伝播する。各段で必ず外側の state 要素へ進むので停止する。
+ */
+function propagateListPathToOuterState(innerStateElement, innerPath) {
+    const outerAbsPathInfo = resolveOuterAbsolutePathInfo(innerStateElement, getPathInfo(innerPath));
+    if (outerAbsPathInfo === null || outerAbsPathInfo.stateElement === innerStateElement) {
+        return;
+    }
+    outerAbsPathInfo.stateElement.setPathInfo(outerAbsPathInfo.pathInfo.path, "for");
+}
+/**
+ * 子スコープのリスト行パス（`items.*.name`）に対応する親スコープの絶対パス情報を返す。
+ *
+ * 呼び出し側（`BindingSession.registerAddress`）は、行バインディングを**この外側パスと
+ * 子スコープの listIndex の組**で親のパターン台帳に相乗りさせる。したがって成立条件は
+ * 「子の listIndex が外側パスの段数をちょうど満たすこと」＝
+ * `Δ + innerW === outerW`（Δ = base 深さ）。
+ *
+ * - コンポーネントが親の `for` の外（Δ=0）: `outerW === innerW`（§1.8）
+ * - コンポーネントが親の `for` の中（Δ>0）: 子の listIndex は base を親に持つので
+ *   チェーン長が Δ+innerW になり、そのまま外側パスの段数と一致する
+ *   （docs/state-bind-component-nested-for-design.md）
+ */
+function getOuterRowPathInfo(innerStateElement, innerPathInfo) {
+    if (innerPathInfo.wildcardCount === 0) {
+        return null;
+    }
+    return stepOuterRowPathInfo(innerStateElement, innerPathInfo);
+}
+/**
+ * `getOuterRowPathInfo` の 2 段目以降。境界が 2 枚以上重なっている（コンポーネントの
+ * shadow の中にさらに mapped な `bind-component` がある）場合、値の正本は 1 つ外では
+ * なく**最も外のスコープ**にある。1 段目だけに相乗りしていると、中間スコープは
+ * 素通しで自分の行バインディングを持たないため、正本スコープ起点の行フィールド
+ * 書き込みを購読する者が誰もいなくなる（§1.11）。
+ *
+ * 1 段目が成立したときだけ呼ばれる（＝mapped な行バインディング限定）ので、
+ * 通常のリストはこの walk を一切踏まない。返り値は 2 段目以降が無ければ `null` で、
+ * 圧倒的多数である深さ 1 の行では配列を確保しない。
+ *
+ * 各段で必ず外側の state 要素へ進む（`resolveOuterAbsolutePathInfo` は
+ * `boundComponent` の属するスコープを返す＝DOM 上の真の祖先）ので停止する。
+ * `propagateListPathToOuterState` の外向き伝播と同じ論拠。
+ */
+function getOuterRowPathInfosBeyond(firstOuterAbsPathInfo) {
+    let rest = null;
+    let stateElement = firstOuterAbsPathInfo.stateElement;
+    let pathInfo = firstOuterAbsPathInfo.pathInfo;
+    for (;;) {
+        const outerAbsPathInfo = stepOuterRowPathInfo(stateElement, pathInfo);
+        if (outerAbsPathInfo === null) {
+            return rest;
+        }
+        (rest ??= []).push(outerAbsPathInfo);
+        stateElement = outerAbsPathInfo.stateElement;
+        pathInfo = outerAbsPathInfo.pathInfo;
+    }
+}
+/**
+ * 境界 1 枚分の外向き解決。成立条件の判定を含む。
+ *
+ * 判定は**両側の実 arity（`getScopeArity` = パスの段数 + そのスコープの Δ）が
+ * 一致すること**。相乗り登録は子の listIndex をそのまま鍵に使うので、外側スコープが
+ * その arity で台帳を引けなければ意味がない。
+ *
+ * 境界 1 枚なら外側は Δ=0 なので、これは従来の `Δ + innerW === outerW` と同値。
+ * 2 枚以上あるときに外側の Δ を数えないと、中間スコープの Δ を二重計上して
+ * 成立するはずの段を落とす（§1.12）。
+ */
+function stepOuterRowPathInfo(innerStateElement, innerPathInfo) {
+    const outerAbsPathInfo = resolveOuterAbsolutePathInfo(innerStateElement, innerPathInfo);
+    if (outerAbsPathInfo === null || outerAbsPathInfo.stateElement === innerStateElement) {
+        return null;
+    }
+    const innerArity = getScopeArity(innerStateElement, innerPathInfo);
+    const outerArity = getScopeArity(outerAbsPathInfo.stateElement, outerAbsPathInfo.pathInfo);
+    if (innerArity !== outerArity) {
+        return null;
+    }
+    return outerAbsPathInfo;
+}
+function resolveOuterAbsolutePathInfo(innerStateElement, innerPathInfo) {
+    if (innerStateElement.hasMappedComponentState !== true) {
+        return null;
+    }
+    const component = innerStateElement.boundComponent;
+    if (component == null) {
+        return null;
+    }
+    const innerAbsPathInfo = getAbsolutePathInfo(innerStateElement, innerPathInfo);
+    // 参照専用で引く。ここはバインディング登録の最中（registerAddress → setPathInfo /
+    // 行の相乗り登録）から呼ばれるので、翻訳のついでに購読者登録まで走らせると
+    // `session.initialize` がセッション操作の内側から再入する。
+    return getOuterAbsolutePathInfo(component, innerAbsPathInfo, false);
+}
+
+// framework 自身が detach し明示的に解体（deactivate/unmount）したノード。
+// BindingOwner の MutationObserver は削除サブツリー走査でこれらをスキップする。
+//
+// 根拠: 削除時の handleRemovedNode は binding を dispose するだけ（DOM 構造変更も
+// connect-snapshot 依存も無い）で、framework が unmount 経路で既に dispose 済みの
+// content に対しては純粋な冗長走査（forEachInclusive で削除サブツリー全体を歩く）に
+// なる。create（追加）経路は two-way の connect-time snapshot を observer に依存する
+// ため対象外だが、削除は依存が無いため安全に飛ばせる。
+//
+// マークは observer が削除を配送した時点で消費（削除）する。マーク〜配送の間隔は
+// 単一 microtask であり、その間に外部 DOM 変異は割り込めない（framework の drain は
+// 同期）ため、マークは framework 由来の削除にしか一致しない。
+const observerSkipNodes = new WeakSet();
+function markObserverSkipOnRemove(node) {
+    observerSkipNodes.add(node);
+}
+// マーク済みなら true を返しつつマークを消費する。未マークなら false。
+function consumeObserverSkipOnRemove(node) {
+    if (!observerSkipNodes.has(node)) {
+        return false;
+    }
+    observerSkipNodes.delete(node);
+    return true;
+}
+// framework 自身がマウント（Content.appendTo / mountAfter）したノード。
+// 追加サブツリー走査の実質の仕事は connect-snapshot 待ち（observationPending）の
+// record への配送だけで、record 自体は同期マウント（activateContent → start）で
 // observer flush より先に active 済み。よって待ちがグローバルに 1 つも無ければ
 // 追加側走査も冗長であり丸ごとスキップできる（削除側スキップの対称形）。
 // マーク〜配送が単一 microtask で外部変異が割り込めない前提も削除側と同じ。
@@ -4154,6 +4940,8 @@ class BindingSession {
                 address: null,
                 patternPathInfo: null,
                 patternListIndex: null,
+                outerPatternPathInfo: null,
+                outerPatternPathInfosRest: null,
                 pendingDefinitions: 0,
                 initialPolicy: slot.policy,
                 resolvedAuthority: slot.authority,
@@ -4269,6 +5057,8 @@ class BindingSession {
             address: null,
             patternPathInfo: null,
             patternListIndex: null,
+            outerPatternPathInfo: null,
+            outerPatternPathInfosRest: null,
             pendingDefinitions: 0,
             initialPolicy: null,
             resolvedAuthority: null,
@@ -4477,6 +5267,26 @@ class BindingSession {
             addBindingByPattern(absolutePathInfo, listIndex, binding);
             record.patternPathInfo = absolutePathInfo;
             record.patternListIndex = listIndex;
+            // mapped な bind-component の子スコープが回している行は、値の正本が親 state に
+            // ある。親が行へ書いたときの enqueue は親の絶対パス情報で起きるので、同じ
+            // listIndex（親子で共有されている）で親側のパターン台帳にも購読者として載せる。
+            // これが無いと親起点の行フィールド書き込みが子に一切届かない（§1.8）。
+            const outerPathInfo = getOuterRowPathInfo(stateElement, binding.statePathInfo);
+            if (outerPathInfo !== null) {
+                addBindingByPattern(outerPathInfo, listIndex, binding);
+                record.outerPatternPathInfo = outerPathInfo;
+                // 境界が 2 枚以上重なっていると、値の正本は 1 つ外ではなく最も外のスコープに
+                // ある。中間スコープは配列を素通しするだけで自分の行バインディングを持たない
+                // ため、1 段目だけでは正本スコープ起点の行フィールド書き込みが誰にも届かない
+                // （§1.11）。成立する段すべてに載せる。
+                const restPathInfos = getOuterRowPathInfosBeyond(outerPathInfo);
+                if (restPathInfos !== null) {
+                    for (let i = 0; i < restPathInfos.length; i++) {
+                        addBindingByPattern(restPathInfos[i], listIndex, binding);
+                    }
+                    record.outerPatternPathInfosRest = restPathInfos;
+                }
+            }
         }
         else {
             const address = getAbsoluteStateAddressByBinding(binding, knownRoot);
@@ -4533,6 +5343,29 @@ class BindingSession {
             }
         }
         else if (record.patternListIndex !== null) {
+            // 親スコープへの相乗り分は独立した資源なので、子側の解除が失敗しても取り残さない
+            if (record.outerPatternPathInfo !== null) {
+                try {
+                    removeBindingByPattern(record.outerPatternPathInfo, record.patternListIndex, binding);
+                }
+                catch {
+                    // Cleanup is best-effort.
+                }
+                record.outerPatternPathInfo = null;
+            }
+            // 3 段目以降（§1.11）。各段も互いに独立した資源なので 1 つずつ守る
+            if (record.outerPatternPathInfosRest !== null) {
+                const restPathInfos = record.outerPatternPathInfosRest;
+                for (let i = 0; i < restPathInfos.length; i++) {
+                    try {
+                        removeBindingByPattern(restPathInfos[i], record.patternListIndex, binding);
+                    }
+                    catch {
+                        // Cleanup is best-effort.
+                    }
+                }
+                record.outerPatternPathInfosRest = null;
+            }
             try {
                 removeBindingByPattern(record.patternPathInfo, record.patternListIndex, binding);
                 record.patternPathInfo = null;
@@ -4590,21 +5423,35 @@ function getBindingSession(binding) {
     return recordByBinding.get(binding)?.session ?? null;
 }
 
-const completeByStateElementByWebComponent = new WeakMap();
-function markWebComponentAsComplete(webComponent, stateElement) {
-    let completeByStateElement = completeByStateElementByWebComponent.get(webComponent);
-    if (!completeByStateElement) {
-        completeByStateElement = new WeakMap();
-        completeByStateElementByWebComponent.set(webComponent, completeByStateElement);
+/**
+ * `bind-component` の配線が完了した (webComponent, stateProp) の台帳。
+ *
+ * 完了前は state プロパティがまだ素のオブジェクトなので、親からの適用は
+ * `applyChangeToProperty` がそこへ値を積み、`bindWebComponent` が melt して取り込む。
+ * 完了後は公開プロパティが outerState proxy に差し替わっているため、親からの適用は
+ * 値を運ばない内部通知チャネル（`applyChangeToWebComponent`）へ切り替わる。
+ * その切り替え判定がこの台帳。
+ *
+ * キーは「state プロパティ名」であって state 要素ではない。完了はプロパティ単位の
+ * 事実（`defineProperty(component, stateProp, ...)` が済んだか）であり、
+ * 1 つの要素に複数の state プロパティを束ねられる以上、粒度もプロパティ単位が正しい。
+ * 以前は内側の `IStateElement` をキーにしていたが、照会側（apply/applyChange.ts）が
+ * 手にしているのは *親スコープ* の `IStateElement` であり、どちらも同じ型なので
+ * TypeScript が取り違えを検出できず、判定が恒久的に false になっていた
+ * （＝親 state 起点の変更が子コンポーネントへ届かない。
+ * docs/architecture-hardening/15-state-component-mechanism-consistency.md §1.7）。
+ */
+const completedStatePropsByWebComponent = new WeakMap();
+function markWebComponentAsComplete(webComponent, stateProp) {
+    let completedStateProps = completedStatePropsByWebComponent.get(webComponent);
+    if (!completedStateProps) {
+        completedStateProps = new Set();
+        completedStatePropsByWebComponent.set(webComponent, completedStateProps);
     }
-    completeByStateElement.set(stateElement, true);
+    completedStateProps.add(stateProp);
 }
-function isWebComponentComplete(webComponent, stateElement) {
-    const completeByStateElement = completeByStateElementByWebComponent.get(webComponent);
-    if (!completeByStateElement) {
-        return false;
-    }
-    return completeByStateElement.get(stateElement) === true;
+function isWebComponentComplete(webComponent, stateProp) {
+    return completedStatePropsByWebComponent.get(webComponent)?.has(stateProp) === true;
 }
 
 function applyChangeToAttribute(binding, _context, newValue) {
@@ -5783,7 +6630,8 @@ function applyChangeToFor(bindingInfo, context, newValue) {
     const listIndex = getListIndexByBindingInfo(bindingInfo);
     const absAddress = getAbsoluteStateAddressByBinding(bindingInfo);
     const lastValue = getLastListValueByAbsoluteStateAddress(absAddress);
-    const diff = createListDiff(listIndex, lastValue, newValue);
+    // 子スコープのトップレベルのリストは base を親に持つ（webComponent/baseListIndex.ts）
+    const diff = createListDiff(getListParentListIndex(context.stateElement, listIndex), lastValue, newValue);
     context.newListValueByAbsAddress.set(absAddress, Array.isArray(newValue) ? newValue : []);
     const fullDelete = Array.isArray(lastValue)
         && lastValue.length === diff.deleteIndexSet.size
@@ -5916,6 +6764,10 @@ function applyChangeToFor(bindingInfo, context, newValue) {
             if (content === null) {
                 raiseError(`Content not found for ListIndex: ${index.index} at path "${listPathInfo.path}"`);
             }
+            // 祖先の unmount（if の非表示など）で解体された行は、ここで物理的に
+            // 戻されるだけでは binding が dispose 済みのまま復活しない。位置合わせの
+            // 前に判定しておき（mountAfter が mounted を立てる）、戻した後に再活性化する。
+            const unmountedByAncestor = !content.mounted;
             // Stable contents are already in correct relative order — but only
             // trust that after physical verification (see isPhysicallyAfter).
             // Contents out of order (and everything unverifiable) settle via the
@@ -5925,6 +6777,16 @@ function applyChangeToFor(bindingInfo, context, newValue) {
             if (!stable && lastNode.nextSibling !== content.firstNode) {
                 content.mountAfter(lastNode);
             }
+            if (unmountedByAncestor) {
+                // 再活性化しないと、行の同一性が保たれる更新が以後すべて無視される
+                // （docs/state-deactivated-content-stale-update.md）。activate は
+                // disposed record の再構築を含むので、プール再利用と同じ経路で戻る。
+                const revivedContent = content;
+                const stateAddress = createStateAddress(elementPathInfo, index);
+                loopContextStack.createLoopContext(stateAddress, (loopContext) => {
+                    activateContent(revivedContent, loopContext, context);
+                });
+            }
         }
         lastNode = content.lastNode || lastNode;
         if (typeof contentMap === 'undefined') {
@@ -6304,18 +7166,58 @@ function applyChangeToText(binding, _context, newValue) {
     }
 }
 
-function applyChangeToWebComponent(binding, _context, newValue) {
-    const element = binding.node;
+/**
+ * 親 state → `bind-component` 済みコンポーネントの再読込通知（内部チャネル）。
+ *
+ * 値そのものは運ばない。バインドされたパスの正本は親 state 側にあり、子は
+ * innerState proxy のマッピング経由で親を読みに行くため、必要なのは
+ * 「そのパスを読み直せ」という通知だけ。
+ *
+ * 以前は `element[stateProp][path] = value` と、コンポーネントの公開プロパティを
+ * 経由してこの通知を送っていた。受け側の proxy が値を捨てて `$postUpdate` を呼ぶ
+ * 作りだったのはそのためだが、同じ proxy が `this.state` として作者にも見えていたので、
+ * 公開 API 側の書き込みまで no-op になっていた。通知はここで state element を直接
+ * 引く形に分離し、公開 proxy は素通し意味論に統一した
+ * （docs/architecture-hardening/15-state-component-mechanism-consistency.md §1.1 / G1）。
+ *
+ * この関数が選ばれるのは `isWebComponentComplete` が真のときだけなので
+ * （apply/applyChange.ts）、`bindWebComponent` は完了済み ＝ state element は登録済み。
+ * ただし**登録済みと使用可能は別**で、切断済みの state element が台帳に残っている
+ * 窓がある（§1.9）。下の使用可能判定を参照。
+ */
+function applyChangeToWebComponent(binding, _context, _newValue) {
+    const element = binding.node;
     const propSegments = binding.propSegments;
     if (propSegments.length <= 1) {
-        raiseError(`Invalid propSegments for web component binding: ${propSegments.join(".")}`);
+        raiseError(`Invalid propSegments for web component binding: ${propSegments.join(DELIMITER)}`);
     }
     const [firstSegment, ...restSegments] = propSegments;
-    const subObject = element[firstSegment];
-    if (typeof subObject === "undefined") {
-        raiseError(`Property "${firstSegment}" not found on web component.`);
+    const innerStateElement = getStateElementByWebComponent(element, firstSegment);
+    if (innerStateElement === null) {
+        raiseError(`State element not bound to "${firstSegment}" on web component.`);
+    }
+    // 切断済みの state element には送らない。
+    //
+    // リスト行にコンポーネントがあるとき、行の再生成では **DOM に戻る前に** apply が走る。
+    // 行の content（と中のコンポーネント要素）は再利用されるので、要素をキーにした
+    // 台帳 `stateElementByWebComponent` は前回の state element を指したままで、
+    // その要素は既に切断されている（`rootNode` を失っている）。そこへ `createState` すると
+    // raiseError し、**updater の drain も applyChangeToFor の行ループも例外を捕まえない**ため、
+    // 1 つの行が同じバッチの残り全部を道連れにする — 実測では for が空になったまま、
+    // 以後どんな更新でも復帰しなくなる（§1.9）。
+    //
+    // ここは値を運ばない再読込通知なので、切断中の子に送る意味がそもそも無い。
+    // 子が DOM に戻れば、子のバインディングが innerState 経由で親をライブ読みするため
+    // 現在値はそのとき正しく入る（初期配送と同じ経路）。よって no-op で落として良い。
+    if (innerStateElement.hasRootNode === false) {
+        if (config.debug) {
+            console.debug(`[@wcstack/state] skipped parent→child notification for a disconnected state element on <${element.tagName.toLowerCase()}>.`, { element, stateProp: firstSegment, path: restSegments.join(DELIMITER) });
+        }
+        return;
     }
-    subObject[restSegments.join(".")] = newValue;
+    innerStateElement.createState("readonly", (state) => {
+        state.$postUpdate(restSegments.join(DELIMITER));
+    });
 }
 
 // indexName ... $1, $2, ...
@@ -6327,7 +7229,7 @@ function getIndexValueByLoopContext(loopContext, indexName) {
     if (typeof indexPos === "undefined") {
         raiseError(`Invalid index name: ${indexName}`);
     }
-    const listIndex = loopContext.listIndex.at(indexPos);
+    const listIndex = listIndexAtWildcard(loopContext.listIndex, indexPos, loopContext.pathInfo.wildcardCount);
     if (listIndex === null) {
         raiseError(`Index not found at position ${indexPos} for loopContext:`);
     }
@@ -6417,6 +7319,23 @@ const deferredSelectBindingByBinding = new WeakMap();
 // 一度確認したら以後は不変（define は不可逆）なので apply 毎の getCustomElement /
 // registry 照会を省略できる。scoped registry を導入する場合はこの不可逆前提を再検討。
 const definedApplyVerifiedByBinding = new WeakMap();
+/**
+ * このバインディングを「値を運ばない親→子の再読込通知」（applyChangeToWebComponent）へ
+ * 回してよいか。
+ *
+ * 長さ 1 の propSegments を除くのが要点。`data-wcs="state: user"` のように
+ * bind-component の stateProp をそのままプロパティ名に書いた形は、完了台帳のキーが
+ * stateProp 名になった以上ゲートを通ってしまうが、applyChangeToWebComponent は
+ * 「先頭セグメント＝束ね先の state 要素、残り＝子側のパス」を前提にしており
+ * 残余が空だと raiseError する。updater の drain は例外を捕まえないので、
+ * 誤設定タグ 1 つが同じバッチの無関係な更新まで巻き添えにしてしまう。
+ * ここで弾いておけば従来どおり applyChangeToProperty に落ち、挙動は変わらない
+ * （getter だけの公開プロパティへの代入が握り潰される ＝ 無言の no-op）。
+ */
+function isWebComponentCompleteForBinding(binding) {
+    return binding.propSegments.length > 1
+        && isWebComponentComplete(binding.replaceNode, binding.propSegments[0]);
+}
 function _applyChange(binding, context) {
     const value = getValue(context.state, binding);
     const filteredValue = getFilteredValue(value, binding.outFilters);
@@ -6430,7 +7349,7 @@ function _applyChange(binding, context) {
         return;
     }
     if (fnByBinding.has(binding)) {
-        if (isWebComponentComplete(binding.replaceNode, context.stateElement)) {
+        if (isWebComponentCompleteForBinding(binding)) {
             fn = applyChangeToWebComponent;
             fnByBinding.set(binding, fn); // 確定したのでキャッシュ
         }
@@ -6448,7 +7367,7 @@ function _applyChange(binding, context) {
         if (typeof fn === 'undefined') {
             const customTag = getCustomElement(binding.replaceNode);
             if (customTag) {
-                if (isWebComponentComplete(binding.replaceNode, context.stateElement)) {
+                if (isWebComponentCompleteForBinding(binding)) {
                     fn = applyChangeToWebComponent;
                     fnByBinding.set(binding, fn); // 確定したのでキャッシュ
                 }
@@ -6949,9 +7868,17 @@ function _getFragmentInfo(rootNode, fragment, parseBindingTextResult, forPath) {
 }
 function collectStructuralFragments(rootNode, walkRoot, forPath) {
     const elseKeyword = config.commentElsePrefix;
+    // Light DOM の mapped コンポーネントの内側は、その子スコープが自分で処理する（§1.13）。
+    // fragment info は rootNode + state 名で登録されるため、ホストのパスでここを拾うと
+    // コンポーネント側の state がまだ名前登録を済ませておらず解決に失敗する。
+    // コンポーネント要素自身は template ではないので、REJECT でサブツリーごと落として問題ない。
+    const nestedComponents = findNestedLightDomComponents(walkRoot);
     const walker = document.createTreeWalker(walkRoot, NodeFilter.SHOW_ELEMENT, {
         acceptNode(node) {
             const element = node;
+            if (nestedComponents.length > 0 && nestedComponents.indexOf(element) !== -1) {
+                return NodeFilter.FILTER_REJECT;
+            }
             if (element.tagName.toLowerCase() === 'template') {
                 const bindText = element.getAttribute(config.bindAttributeName) || '';
                 if (bindText.length > 0) {
@@ -7072,6 +7999,13 @@ async function waitForStateInitialize(root) {
     const promises = [];
     await customElements.whenDefined(config.tagNames.state);
     for (const element of elements) {
+        // Light DOM の mapped コンポーネントの state は待たない。それはこの root の
+        // バインディングが張られてからでないと初期化できず（自分を束ねるホスト binding を
+        // 待つ）、ここで待つと循環する（§1.13）。Shadow DOM 形では別 rootNode にいるので
+        // そもそもこの集合に現れず、plain 形は循環しないので従来どおり待つ。
+        if (isLightDomMappedStateElement(element)) {
+            continue;
+        }
         const stateElement = element;
         promises.push(stateElement.initializePromise);
     }
@@ -7102,7 +8036,7 @@ async function buildBindings(root) {
     }
 }
 
-var version = "1.25.0";
+var version = "1.27.0";
 var pkg = {
 	version: version};
 
@@ -7877,28 +8811,47 @@ function setStateElementByName(rootNode, name, element) {
             // 初めてルートノードに登録する場合
             // enable-ssr 属性があり、サーバーサイドでない場合はハイドレーション
             const enableSsr = !inSsr() && element.hasAttribute?.('enable-ssr');
+            // instanceof ではなく constructor.name で判定するのは意図的。SSR では
+            // @wcstack/server の installGlobals が happy-dom の一部だけを globalThis に載せるが、
+            // そのリスト（GLOBALS_KEYS）に `Document` は入っていない。Node にも `Document` は
+            // 無いので `rootNode instanceof Document` は ReferenceError になる。
+            // `ShadowRoot` はリストに含まれるため他所では instanceof を使っている
+            // （docs/architecture-hardening/15-state-component-mechanism-consistency.md §3.3）。
+            // reject を配管しないと、バインディング初期化中の例外は unhandled rejection として
+            // 漏れるだけで ready が永久に未解決のまま残り、await getBindingsReady() の先が
+            // 無言でハングする（docs/state-bind-component-nested-for-design.md §8.2）。
             if (rootNode.constructor.name === 'HTMLDocument' || rootNode.constructor.name === 'Document') {
-                const ready = new Promise((resolve) => {
+                const ready = new Promise((resolve, reject) => {
                     queueMicrotask(async () => {
-                        if (enableSsr) {
-                            const success = await hydrateBindings(rootNode);
-                            if (!success) {
+                        try {
+                            if (enableSsr) {
+                                const success = await hydrateBindings(rootNode);
+                                if (!success) {
+                                    await buildBindings(rootNode);
+                                }
+                            }
+                            else {
                                 await buildBindings(rootNode);
                             }
+                            resolve();
                         }
-                        else {
-                            await buildBindings(rootNode);
+                        catch (error) {
+                            reject(error);
                         }
-                        resolve();
                     });
                 });
                 bindingsReadyByNode.set(rootNode, ready);
             }
             else if (rootNode.constructor.name === 'ShadowRoot') {
-                const ready = new Promise((resolve) => {
+                const ready = new Promise((resolve, reject) => {
                     queueMicrotask(async () => {
-                        await buildBindings(rootNode);
-                        resolve();
+                        try {
+                            await buildBindings(rootNode);
+                            resolve();
+                        }
+                        catch (error) {
+                            reject(error);
+                        }
                     });
                 });
                 bindingsReadyByNode.set(rootNode, ready);
@@ -7918,27 +8871,89 @@ function setStateElementByName(rootNode, name, element) {
     }
 }
 
-const updateBatchListeners = new Set();
+/**
+ * watch/chainDepth.ts
+ *
+ * `$watch` ハンドラ起点の書き込み連鎖の深さを数える台帳
+ * （docs/state-watch-hook-design.md §7-2）。
+ *
+ * watch ハンドラ内の書き込みは新しい microtask バッチを作るため、伝播 context の
+ * hop 上限（MAX_PROPAGATION_HOPS）のガードが効かない。かつ書き込み先が動的なので、
+ * `$streams` のような「宣言時の自己依存検出」も使えない。よって実行時に数える。
+ *
+ * updater（enqueue 側）と watchRuntime（発火側）の両方から参照されるため、
+ * **依存ゼロの葉モジュール**にして循環 import を避ける（devtools/sink.ts と同じ方針）。
+ *
+ * 数え方: ハンドラ実行中に enqueue が起きたときだけ「次のバッチはこの連鎖の続き」と
+ * マークする。ハンドラが何も書かなければ次のバッチは深さ 0 に戻るので、利用者操作が
+ * 何度続いても深さは伸びない。
+ */
+/** ハンドラ実行中に立つ「今の連鎖の深さ + 1」。0 なら watch 起点ではない */
+let firingDepth = 0;
+/** 次に drain されるバッチの深さ */
+let pendingDepth = 0;
+/** watch の発火フェーズ開始（watchRuntime 専用） */
+function beginWatchFiring(depth) {
+    firingDepth = depth + 1;
+}
+/** watch の発火フェーズ終了（watchRuntime 専用。必ず finally で呼ぶ） */
+function endWatchFiring() {
+    firingDepth = 0;
+}
+/**
+ * 書き込みの enqueue を記録する（updater 専用）。
+ * ハンドラ実行中でなければ何もしない ＝ 通常の書き込みに深さは付かない。
+ */
+function noteEnqueueForWatchChain() {
+    if (firingDepth > pendingDepth) {
+        pendingDepth = firingDepth;
+    }
+}
+/** 次バッチの深さを消費する（watchRuntime 専用。読んだらリセット） */
+function consumeWatchChainDepth() {
+    const depth = pendingDepth;
+    pendingDepth = 0;
+    return depth;
+}
+
+const updateBatchListeners = [];
 /**
  * drain 終了リスナーを登録する。
+ *
+ * `priority` の昇順に呼ばれる（同値は登録順）。機構間の実行順序
+ * （`$watch` → `$streams` restart、docs/state-watch-hook-design.md §3-2 層 1）は
+ * この優先度で固定する — import 順に順序を持たせると、無関係な import 整理で
+ * 静かに壊れるため。定数は define.ts の `*_LISTENER_PRIORITY` を使うこと。
  */
-function registerUpdateBatchListener(listener) {
-    updateBatchListeners.add(listener);
+function registerUpdateBatchListener(listener, priority = 0) {
+    // 挿入ソート: 同値優先度の中では登録順を保つ（find は最初の「より大きい」要素を指す）
+    const index = updateBatchListeners.findIndex((registered) => registered.priority > priority);
+    const entry = { listener, priority };
+    if (index === -1) {
+        updateBatchListeners.push(entry);
+    }
+    else {
+        updateBatchListeners.splice(index, 0, entry);
+    }
 }
 /**
  * drain 終了リスナーを解除する（テスト間の分離用）。
  */
 function unregisterUpdateBatchListener(listener) {
-    updateBatchListeners.delete(listener);
+    const index = updateBatchListeners.findIndex((registered) => registered.listener === listener);
+    if (index !== -1) {
+        updateBatchListeners.splice(index, 1);
+    }
 }
 /**
- * 全リスナーに drain のバッチを通知する。
+ * 全リスナーに drain のバッチを優先度順で通知する。
  * リスナーの throw は握りつぶさない（内部バグの隠蔽防止）。
- * stream 側リスナーが entry ごとに自前で try/catch する契約（設計書 §3-2）。
+ * stream / watch 側リスナーが entry ごとに自前で try/catch する契約（設計書 §3-2）。
  */
 function notifyUpdateBatchListeners(batch) {
-    for (const listener of updateBatchListeners) {
-        listener(batch);
+    // 反復中の register / unregister（ハンドラ内の切断・再 set）に耐えるためコピーする
+    for (const registered of updateBatchListeners.slice()) {
+        registered.listener(batch);
     }
 }
 class Updater {
@@ -7946,6 +8961,9 @@ class Updater {
     constructor() {
     }
     enqueueAbsoluteAddress(absoluteAddress, context = null) {
+        // `$watch` ハンドラ実行中の書き込みだけを連鎖としてマークする（watch/chainDepth.ts）。
+        // ハンドラ実行中でなければ即 return する葉モジュール呼び出し 1 個のコスト。
+        noteEnqueueForWatchChain();
         const requireStartProcess = this._queueUpdateRecords.length === 0;
         this._queueUpdateRecords.push({ absoluteAddress, context });
         if (requireStartProcess) {
@@ -8172,7 +9190,9 @@ function setSink(sink) {
     setDevtoolsSink(sink);
     const isActive = sink !== null;
     if (isActive && !wasActive) {
-        registerUpdateBatchListener(onUpdateBatch);
+        // `$watch` / `$streams` restart より先に流す（protocol §4.3）。優先度を省略しても
+        // 既定 0 で結果は同じだが、それは偶然なので定数で意図を固定する。
+        registerUpdateBatchListener(onUpdateBatch, DEVTOOLS_LISTENER_PRIORITY);
     }
     else if (!isActive && wasActive) {
         unregisterUpdateBatchListener(onUpdateBatch);
@@ -8280,26 +9300,67 @@ function registerDevtoolsSource() {
     getOrCreateHookRegistry().register(source);
 }
 
+const CSP_GUIDE = "https://github.com/wcstack/wcstack/blob/main/docs/csp.md";
+/**
+ * インライン `<script>` の評価失敗を、原因の分かるメッセージに変換する。
+ *
+ * CSP にブロックされた動的 import の rejection は
+ * "Failed to fetch dynamically imported module" としか言わず、CSP には一切言及しない。
+ * ブロックされた事実は securitypolicyviolation イベントでしか観測できないため、
+ * その観測結果を `cspBlocked` で受け取る。
+ *
+ * 真ならブロック確定として対処方法まで書く。偽のときは構文エラー等と区別できないので、
+ * 元のエラーを主にして CSP は参照先を添えるに留める（誤誘導を避ける）。
+ */
+function describeImportFailure(name, error, cspBlocked) {
+    const detail = error?.message ?? String(error);
+    if (cspBlocked) {
+        return `The inline <script> of state "${name}" was blocked by Content-Security-Policy. ` +
+            `Inline state is evaluated through a blob: URL, so script-src must allow blob:. ` +
+            `Prefer moving the state into an external file and loading it with src="./state.js", ` +
+            `which requires no extra CSP directive. See ${CSP_GUIDE}`;
+    }
+    return `Failed to evaluate the inline <script> of state "${name}": ${detail}. ` +
+        `If this page sets a Content-Security-Policy, see ${CSP_GUIDE}`;
+}
 async function loadFromInnerScript(script, name) {
     let scriptModule = null;
     const uniq_comment = `\n//# sourceURL=${name}\n`;
-    if (typeof URL.createObjectURL === 'function') {
-        // Create a blob URL for the script and dynamically import it
-        const blob = new Blob([script.text + uniq_comment], { type: "application/javascript" });
-        const url = URL.createObjectURL(blob);
-        try {
-            scriptModule = await import(url);
+    // import() が失敗した理由が CSP かどうかを判別するために、評価の間だけ違反を購読する。
+    let cspBlocked = false;
+    const onViolation = (event) => {
+        if (event.effectiveDirective.startsWith("script-src")) {
+            cspBlocked = true;
         }
-        finally {
-            // Clean up blob URL to prevent memory leak
-            URL.revokeObjectURL(url);
+    };
+    document.addEventListener("securitypolicyviolation", onViolation);
+    try {
+        if (typeof URL.createObjectURL === 'function') {
+            // Create a blob URL for the script and dynamically import it
+            const blob = new Blob([script.text + uniq_comment], { type: "application/javascript" });
+            const url = URL.createObjectURL(blob);
+            try {
+                scriptModule = await import(url);
+            }
+            finally {
+                // Clean up blob URL to prevent memory leak
+                URL.revokeObjectURL(url);
+            }
+        }
+        else {
+            // Fallback: Base64 encoding method (for test environment)
+            // Convert script to Base64 and import via data: URL
+            const b64 = btoa(String.fromCodePoint(...new TextEncoder().encode(script.text + uniq_comment)));
+            scriptModule = await import(`data:application/javascript;base64,${b64}`);
         }
     }
-    else {
-        // Fallback: Base64 encoding method (for test environment)
-        // Convert script to Base64 and import via data: URL
-        const b64 = btoa(String.fromCodePoint(...new TextEncoder().encode(script.text + uniq_comment)));
-        scriptModule = await import(`data:application/javascript;base64,${b64}`);
+    catch (e) {
+        // 呼び出し元（State._initialize / _initializeDCC）が raiseError で
+        // `[@wcstack/state]` を付けるため、ここでは prefix を重ねない。
+        throw new Error(describeImportFailure(name, e, cspBlocked), { cause: e });
+    }
+    finally {
+        document.removeEventListener("securitypolicyviolation", onViolation);
     }
     return (scriptModule && typeof scriptModule.default === 'object') ? scriptModule.default : {};
 }
@@ -8346,6 +9407,10 @@ function loadFromScriptJson(id) {
 class LoopContextStack {
     _loopContextStack = Array(MAX_LOOP_DEPTH).fill(undefined);
     _length = 0;
+    _getBaseDepth;
+    constructor(getBaseDepth) {
+        this._getBaseDepth = getBaseDepth;
+    }
     createLoopContext(elementStateAddress, callback) {
         if (elementStateAddress.listIndex === null) {
             raiseError(`Cannot create loop context for a state address that does not have a list index.`);
@@ -8367,13 +9432,21 @@ class LoopContextStack {
         }
         else {
             // With no active loop context the address must be self-contained: the
-            // listIndex chain supplies one index per wildcard. Top-level lists
-            // (wildcardCount 1) always satisfy this. A nested list re-rendered
-            // directly (e.g. replaced via $resolve from outside the loop) also
-            // satisfies it — the for binding's listIndex carries the full ancestor
-            // chain.
+            // listIndex chain supplies one index per wildcard, plus this scope's base
+            // depth Δ. Top-level lists (wildcardCount 1) always satisfy this. A nested
+            // list re-rendered directly (e.g. replaced via $resolve from outside the
+            // loop) also satisfies it — the for binding's listIndex carries the full
+            // ancestor chain. Δ is non-zero only for a mapped bind-component child
+            // whose host sits inside a parent-scope `for`
+            // (docs/state-bind-component-nested-for-design.md).
+            // ここは行ごとに通る（applyChangeToFor は追加行ごとに createLoopContext する）。
+            // Δ=0 の判定を先に置き、通れば base 深さの解決（DOM の親走査を含む）に
+            // 一切触れない — 通常の state に追加コストを載せないため。
             if (loopContext.listIndex.length !== loopContext.pathInfo.wildcardCount) {
-                raiseError(`Cannot push loop context when there is no active loop context: the list index chain (length ${loopContext.listIndex.length}) does not cover the wildcard path (wildcard count ${loopContext.pathInfo.wildcardCount}).`);
+                const baseDepth = this._getBaseDepth();
+                if (loopContext.listIndex.length !== loopContext.pathInfo.wildcardCount + baseDepth) {
+                    raiseError(`Cannot push loop context when there is no active loop context: the list index chain (length ${loopContext.listIndex.length}) does not cover the wildcard path (wildcard count ${loopContext.pathInfo.wildcardCount}, base depth ${baseDepth}).`);
+                }
             }
         }
         this._loopContextStack[this._length] = loopContext;
@@ -8397,8 +9470,8 @@ class LoopContextStack {
         return retValue;
     }
 }
-function createLoopContextStack() {
-    return new LoopContextStack();
+function createLoopContextStack(getBaseDepth = () => 0) {
+    return new LoopContextStack(getBaseDepth);
 }
 
 /**
@@ -8436,12 +9509,12 @@ function processCommandTokensDeclaration(state) {
     return names;
 }
 
-const registryByStateElement$1 = new WeakMap();
+const registryByStateElement$2 = new WeakMap();
 function getOrCreateCommandToken(stateElement, name) {
-    let registry = registryByStateElement$1.get(stateElement);
+    let registry = registryByStateElement$2.get(stateElement);
     if (typeof registry === "undefined") {
         registry = new Map();
-        registryByStateElement$1.set(stateElement, registry);
+        registryByStateElement$2.set(stateElement, registry);
     }
     let token = registry.get(name);
     if (typeof token === "undefined") {
@@ -8451,7 +9524,7 @@ function getOrCreateCommandToken(stateElement, name) {
     return token;
 }
 function clearCommandTokenRegistry(stateElement) {
-    registryByStateElement$1.delete(stateElement);
+    registryByStateElement$2.delete(stateElement);
 }
 
 /**
@@ -8686,24 +9759,24 @@ function invalidateLastNotified(stateElement, name) {
  *   設計書 §3-2 の「未接続（disconnect 済み）の stateElement の entry は restart
  *   しない」はこの不変条件で担保される。
  */
-const activeStateElements = new Set();
+const activeStateElements$1 = new Set();
 /**
  * 起動中 stateElement として登録する（startStreams 専用。不変条件はモジュールヘッダ参照）。
  */
 function addActiveStateElement(stateElement) {
-    activeStateElements.add(stateElement);
+    activeStateElements$1.add(stateElement);
 }
 /**
  * 起動中 stateElement から外す（abortAllStreams / clearStreamRegistry 専用）。
  */
 function deleteActiveStateElement(stateElement) {
-    activeStateElements.delete(stateElement);
+    activeStateElements$1.delete(stateElement);
 }
 /**
  * 起動中 stateElement を列挙する（drain リスナーの交差判定用）。
  */
 function getActiveStateElements() {
-    return activeStateElements;
+    return activeStateElements$1;
 }
 
 /**
@@ -8716,18 +9789,18 @@ function getActiveStateElements() {
  * - disconnect 時は abortAllStreams（abort のみ・registry 保持）、
  *   `_state` 再 set 時のみ clearStreamRegistry（abort ＋ 全削除）。
  */
-const registryByStateElement = new WeakMap();
+const registryByStateElement$1 = new WeakMap();
 /**
  * stream entry 群を置換登録する（`_state` セッターからの再構築で丸ごと差し替える）。
  */
 function setStreamEntries(stateElement, entries) {
-    registryByStateElement.set(stateElement, entries);
+    registryByStateElement$1.set(stateElement, entries);
 }
 /**
  * 登録済みの stream entry 群を返す。未登録なら空 Map を返す（registry への登録はしない）。
  */
 function getStreamEntries(stateElement) {
-    return registryByStateElement.get(stateElement) ?? new Map();
+    return registryByStateElement$1.get(stateElement) ?? new Map();
 }
 /**
  * 全 stream を abort して idle に戻す（設計書 §5-1）。registry は保持する。
@@ -8747,7 +9820,7 @@ function abortAllStreams(stateElement) {
     // 設計書 §3-2。add 側は startStreams — stream/activeStateElements.ts の
     // リーク防止不変条件を参照）。registry の有無に関わらず必ず外す。
     deleteActiveStateElement(stateElement);
-    const entries = registryByStateElement.get(stateElement);
+    const entries = registryByStateElement$1.get(stateElement);
     if (typeof entries === "undefined") {
         return;
     }
@@ -8767,7 +9840,7 @@ function clearStreamRegistry(stateElement) {
     // abortAllStreams が既に delete 済みだが、「clear = 全削除でも必ず restart 対象から
     // 外れる」不変条件を将来の abortAllStreams の変更から独立に保証するため明示的に呼ぶ。
     deleteActiveStateElement(stateElement);
-    registryByStateElement.delete(stateElement);
+    registryByStateElement$1.delete(stateElement);
 }
 
 /**
@@ -8880,6 +9953,77 @@ function processStreamsDeclaration(stateElement, state) {
     pruneLastNotified(stateElement, new Set(entries.keys()));
 }
 
+/**
+ * list/listKeys.ts
+ *
+ * `$listKeys: { <listPath>: <fieldName | (row) => key> }` 宣言マップを解析し、
+ * 「リストパス → キー指定」表を構築する（docs/state-list-key-design.md §3）。
+ *
+ * この表が存在するリストパスへの配列代入は、setByAddress でキー突合され、
+ * 一致行は旧オブジェクトを据え置いたまま変化フィールドだけが per-path 書き込みで
+ * 流し込まれる（§2）。未宣言なら書き込み経路は従来と完全に同一。
+ *
+ * 「そのパスが実際にリストか」は宣言時には判定できない（listPaths は
+ * バインディング収集時に確定する）。実行時に配列でなければ経路に入らないだけで、
+ * 宣言自体はエラーにしない。
+ */
+/**
+ * `$listKeys` 宣言を検証して Map 化する。宣言が無ければ null（＝ゼロコスト経路）。
+ *
+ * 検証内容（§3.1）:
+ * - `$listKeys` はオブジェクト
+ * - パスは非空文字列 / 空セグメント・先頭末尾の `.` を禁止
+ * - パス末尾が `*` であることを禁止（リストパスであって要素パスではない）
+ * - キー指定は非空文字列か関数
+ * - 文字列キーは `.` / `*` を含まないフラットなフィールド名
+ * - `Object.prototype` 継承名を禁止（`__proto__` / `constructor` 等）
+ */
+function processListKeysDeclaration(state) {
+    const declared = state[STATE_LIST_KEYS_NAME];
+    if (typeof declared === "undefined") {
+        return null;
+    }
+    if (typeof declared !== "object" || declared === null) {
+        raiseError(`${STATE_LIST_KEYS_NAME} must be an object mapping list paths to key specs.`);
+    }
+    const entries = new Map();
+    for (const [path, spec] of Object.entries(declared)) {
+        if (path.length === 0) {
+            raiseError(`${STATE_LIST_KEYS_NAME} entry path must be a non-empty string.`);
+        }
+        const segments = path.split(DELIMITER);
+        if (segments.some((segment) => segment.length === 0)) {
+            raiseError(`${STATE_LIST_KEYS_NAME} entry "${path}" must not contain empty path segments.`);
+        }
+        if (segments[segments.length - 1] === WILDCARD) {
+            raiseError(`${STATE_LIST_KEYS_NAME} entry "${path}" must be the list path itself, not the element path ` +
+                `(drop the trailing "${DELIMITER}${WILDCARD}").`);
+        }
+        if (typeof spec === "function") {
+            entries.set(path, spec);
+            continue;
+        }
+        if (typeof spec !== "string") {
+            raiseError(`${STATE_LIST_KEYS_NAME} entry "${path}" key spec must be a field name (string) or a function.`);
+        }
+        if (spec.length === 0) {
+            raiseError(`${STATE_LIST_KEYS_NAME} entry "${path}" key field name must be a non-empty string.`);
+        }
+        if (spec.includes(DELIMITER) || spec.includes(WILDCARD)) {
+            raiseError(`${STATE_LIST_KEYS_NAME} entry "${path}" key field name "${spec}" must be a flat property name ` +
+                `("${DELIMITER}" / "${WILDCARD}" are not allowed).`);
+        }
+        // own key でなくても `in` 判定が真になる継承名は、キー抽出が prototype 由来の
+        // 値（constructor など）を拾って全行同一キー扱いになるため名前の防衛線で落とす。
+        if (spec in Object.prototype) {
+            raiseError(`${STATE_LIST_KEYS_NAME} entry "${path}" key field name "${spec}" must not be a property name ` +
+                `inherited from Object.prototype (e.g. "__proto__", "constructor").`);
+        }
+        entries.set(path, spec);
+    }
+    return entries.size > 0 ? entries : null;
+}
+
 /**
  * stream/streamNamespace.ts
  *
@@ -9422,117 +10566,746 @@ function restartStreamsOnUpdateBatch(batch) {
         }
     }
 }
-registerUpdateBatchListener(restartStreamsOnUpdateBatch);
+// 優先度で `$watch` の後に固定する（設計書 §3-2 層 1）。import 順には依存しない。
+registerUpdateBatchListener(restartStreamsOnUpdateBatch, STREAM_LISTENER_PRIORITY);
 
-function getterFn(name) {
-    return function () {
-        const stateEl = this.stateElement;
-        if (!stateEl)
-            return undefined;
-        let value;
-        try {
-            stateEl.createState("readonly", (state) => {
-                value = state[name];
-            });
-        }
-        catch (e) {
-            console.warn(`[@wcstack/state] DCC getter "${name}" failed:`, e);
-            return undefined;
-        }
-        return value;
-    };
+/**
+ * watch/watchRegistry.ts
+ *
+ * `$watch` の registry と、drain リスナーの走査元になる「発火対象の stateElement 集合」
+ * （docs/state-watch-hook-design.md §9）。
+ *
+ * `$streams` は registry（delete 側）と runtime（add 側）が相互に依存するため
+ * active 集合を stream/activeStateElements.ts へ切り出しているが、`$watch` は
+ * **add が State のライフサイクル側、delete が registry 側**で、runtime は読むだけの
+ * 一方向依存になる。よって循環せず、1 モジュールにまとめられる。
+ *
+ * リーク防止の不変条件（strong Set が切断済み要素の GC を妨げないための連動）:
+ * - add は `startWatch`（`State.connectedCallback` の $connectedCallback 完了後、および
+ *   接続中の `_state` 再 set）だけが行い、**宣言が 1 つも無い stateElement は入れない**。
+ * - delete は `deactivateWatch`（disconnectedCallback）／`clearWatchRegistry`（`_state`
+ *   再 set）だけが行う。
+ * どちらの経路も必ずここを通るため「Set に居る = 接続中かつ宣言済み」が保たれる。
+ * この「宣言済み」の側が崩れると、`$watch` 未使用アプリの drain にも収集ループが乗る
+ * （ゼロコスト契約、docs/state-watch-hook-design.md §10）。
+ */
+const registryByStateElement = new WeakMap();
+const activeStateElements = new Set();
+/**
+ * 未登録時に返す共有の空 Map。
+ *
+ * ここで毎回 `new Map()` すると、drain の収集ループが「バッチのアドレス 1 個につき
+ * Map を 1 個」アロケートすることになる（発火対象だが宣言を持たない stateElement を
+ * 通る経路）。読み出ししかしない返り値なので 1 個を使い回す。
+ */
+const EMPTY_ENTRIES = new Map();
+/**
+ * watch entry 群を置換登録する（`_state` セッターからの再構築で丸ごと差し替える）。
+ */
+function setWatchEntries(stateElement, entries) {
+    registryByStateElement.set(stateElement, entries);
 }
-function setterFn(name) {
-    return function (value) {
-        const stateEl = this.stateElement;
-        if (!stateEl)
-            return;
-        stateEl.initializePromise.then(() => {
-            stateEl.createState("writable", (state) => {
-                state[name] = value;
-            });
-        });
-    };
+/**
+ * 登録済みの watch entry 群を返す。未登録なら共有の空 Map を返す
+ * （registry への登録はしない。返り値は読み出し専用）。
+ */
+function getWatchEntries(stateElement) {
+    return registryByStateElement.get(stateElement) ?? EMPTY_ENTRIES;
 }
-function callFn(name, isAsync) {
-    if (isAsync) {
-        return function (...args) {
-            const stateEl = this.stateElement;
-            if (!stateEl)
-                return undefined;
-            return stateEl.initializePromise.then(() => {
-                let result;
-                return stateEl.createStateAsync("writable", async (state) => {
-                    result = await state[name](...args);
-                }).then(() => result);
-            });
-        };
+/**
+ * 発火対象として登録する（`startWatch` 専用。不変条件はモジュールヘッダ参照）。
+ */
+function addActiveWatchStateElement(stateElement) {
+    activeStateElements.add(stateElement);
+}
+/**
+ * 発火対象を列挙する（drain リスナーの early return 判定用）。
+ */
+function getActiveWatchStateElements() {
+    return activeStateElements;
+}
+/**
+ * 発火対象から外す（切断時）。**registry は保持する。**
+ *
+ * `$streams` の abortAllStreams と同じ二段構えで、切断は「発火しなくなる」だけにする。
+ * registry まで捨てると、再接続（connectedCallback → startWatch）で宣言を作り直す経路が
+ * 無い（`_state` セッターは初回ロード時にしか走らない）ため、watch が二度と発火しない。
+ */
+function deactivateWatch(stateElement) {
+    activeStateElements.delete(stateElement);
+}
+/**
+ * registry から削除し、発火対象からも外す（`_state` 再 set 時の再配線用）。
+ */
+function clearWatchRegistry(stateElement) {
+    activeStateElements.delete(stateElement);
+    registryByStateElement.delete(stateElement);
+}
+
+/**
+ * watch/processWatchDeclaration.ts
+ *
+ * `$watch: { "<path>": (cur, prev, ...indexes) => void }` 宣言マップを解析し、
+ * IWatchEntry を構築して watchRegistry に一括登録する
+ * （docs/state-watch-hook-design.md §2-2 / §8）。
+ *
+ * `$streams` の processStreamsDeclaration と対称だが、**キーが宣言名ではなくパス**である
+ * ぶん検証が異なる（`.` / `*` を許可し、代わりにパスとしての妥当性を見る）。
+ *
+ * 依存グラフ登録（§8）がこの関数の要点:
+ * `setPathInfo` は BindingSession（＝ DOM バインディング登録）からしか呼ばれないため、
+ * 静的依存グラフに載るのは「バインドされたパス」だけである。watch を宣言しただけでは
+ * walkDependency がそのパスを知らず、`items` への代入で `items.*.price` がバッチに載らない
+ * ＝ ハンドラが黙って一度も発火しない。宣言時に自分で登録することでこれを塞ぐ。
+ *
+ * 呼び出しは stateElement の `_pathSet` クリア後・getterPaths 確定後であること
+ * （State の `_state` セッターが順序を保証する）。
+ */
+/**
+ * `$watch` 宣言を registry へ反映し、監視対象パスの集合を返す。
+ *
+ * 宣言が無い（または空）なら **null** を返す。呼び出し側（State）はこれを
+ * `watchPaths` に保持し、setByAddress のホットパスは `!== null` の分岐 1 個で
+ * 抜けられる（ゼロコスト契約、§10）。
+ */
+function processWatchDeclaration(stateElement, state) {
+    const declared = state[STATE_WATCH_NAME];
+    if (typeof declared === "undefined") {
+        return null;
     }
-    return function (...args) {
-        const stateEl = this.stateElement;
-        if (!stateEl)
-            return undefined;
-        return stateEl.initializePromise.then(() => {
-            let result;
-            stateEl.createState("writable", (state) => {
-                result = state[name](...args);
-            });
-            return result;
+    if (typeof declared !== "object" || declared === null) {
+        raiseError(`${STATE_WATCH_NAME} must be an object mapping state paths to handler functions.`);
+    }
+    const entries = new Map();
+    const paths = new Set();
+    let order = 0;
+    for (const [path, handler] of Object.entries(declared)) {
+        if (typeof handler !== "function") {
+            raiseError(`${STATE_WATCH_NAME} entry "${path}" must be a function.`);
+        }
+        if (path.length === 0) {
+            raiseError(`${STATE_WATCH_NAME} entry name must be a non-empty state path.`);
+        }
+        if (path.startsWith("$")) {
+            raiseError(`${STATE_WATCH_NAME} entry "${path}" must not start with "$" (reserved namespace).`);
+        }
+        // 越境 watch は不採用（設計 D8）。他 state のアドレスは発火対象にしないため、
+        // `@stateName` 付きのパスは受け取った時点で落とす（黙って発火しないより良い）。
+        if (path.includes(STATE_NAME_SEPARATOR)) {
+            raiseError(`${STATE_WATCH_NAME} entry "${path}" must not target another state ("${STATE_NAME_SEPARATOR}" is not allowed); watch only paths of its own state.`);
+        }
+        // Object.prototype の継承名は `path in state` 系の判定を汚すため一律拒否する
+        // （processStreamsDeclaration と同じ防衛線）。
+        if (path in Object.prototype) {
+            raiseError(`${STATE_WATCH_NAME} entry "${path}" must not be a property name inherited from Object.prototype (e.g. "__proto__", "constructor").`);
+        }
+        const pathInfo = getPathInfo(path);
+        // 空セグメント（"a..b" / 先頭・末尾の "."）は getPathInfo が黙って受理してしまうため、
+        // ここで落とす。放置すると解決不能なアドレスを依存グラフへ登録することになる。
+        for (const segment of pathInfo.segments) {
+            if (segment.length === 0) {
+                raiseError(`${STATE_WATCH_NAME} entry "${path}" has an empty path segment.`);
+            }
+        }
+        if (pathInfo.wildcardCount > MAX_WILDCARD_DEPTH) {
+            raiseError(`${STATE_WATCH_NAME} entry "${path}" exceeds the maximum wildcard depth (${MAX_WILDCARD_DEPTH}).`);
+        }
+        entries.set(path, {
+            path,
+            pathInfo,
+            handler: handler,
+            order: order++,
         });
-    };
-}
-function isInternalProperty(name) {
-    return name.startsWith("$");
+        paths.add(path);
+        // 依存グラフ登録（§8）。"for" 以外の bindingType は親 → 子の staticDependency
+        // チェーンを生やすだけで listPaths / elementPaths を触らない（State.setPathInfo 参照）。
+        stateElement.setPathInfo(path, "prop");
+    }
+    setWatchEntries(stateElement, entries);
+    return paths.size > 0 ? paths : null;
 }
 
-function createWcBindable(tagName, bindables) {
-    const properties = bindables.map((propName) => ({
-        name: propName,
-        event: `${tagName}:${propName}-changed`,
-    }));
-    // Every $bindables member gets both a getter and a setter on the DCC prototype,
-    // so declare it in inputs as well — a property declared only in `properties` is
-    // output-only under directional initial sync, which would permanently block
-    // parent-state → DCC writes.
-    const inputs = bindables.map((propName) => ({
-        name: propName,
-    }));
-    return {
-        protocol: "wc-bindable",
-        version: 1,
-        properties,
-        inputs,
-    };
+/**
+ * watch/computedSnapshots.ts
+ *
+ * watch 対象の computed（getter）の「前回評価値」台帳
+ * （docs/state-watch-hook-design.md §5）。
+ *
+ * getter は `setByAddress` を通らないので、スカラ書き込み用の旧値台帳
+ * （watch/prevValues.ts）には載らない。`prev` を渡すには前回の評価値を
+ * **バッチを跨いで**保持する必要があり、こちらは drain ごとにクリアしない。
+ *
+ * 寿命は stateElement 単位（WeakMap）。`_state` 再 set では宣言ごと作り直すため
+ * 破棄する。切断では破棄しない —— 再接続時の初回評価が上書きするので、
+ * 残っていても害がなく、registry を保持する扱いとも揃う。
+ */
+const snapshotsByStateElement = new WeakMap();
+function getComputedSnapshot(stateElement, absAddress) {
+    return snapshotsByStateElement.get(stateElement)?.get(absAddress);
 }
-function createBindableEventMap(tagName, bindables) {
-    const map = {};
-    for (const propName of bindables) {
-        map[propName] = `${tagName}:${propName}-changed`;
+function setComputedSnapshot(stateElement, absAddress, value) {
+    let snapshots = snapshotsByStateElement.get(stateElement);
+    if (typeof snapshots === "undefined") {
+        snapshots = new Map();
+        snapshotsByStateElement.set(stateElement, snapshots);
     }
-    return map;
+    snapshots.set(absAddress, value);
+}
+/** `_state` 再 set で宣言ごと作り直すときに破棄する */
+function clearComputedSnapshots(stateElement) {
+    snapshotsByStateElement.delete(stateElement);
 }
 
-function defineDCC(hostElement, shadowRoot, state) {
-    const tagName = hostElement.tagName.toLowerCase();
-    // バリデーション
-    if (!tagName.includes("-")) {
-        raiseError(`DCC: "${tagName}" is not a valid custom element name (must contain a hyphen).`);
+/**
+ * watch/prevValues.ts
+ *
+ * `$watch` ハンドラへ渡す `prev`（バッチ開始時点の値）の台帳
+ * （docs/state-watch-hook-design.md §4-1）。
+ *
+ * 記録するのは **watch 宣言済みパスへの書き込みだけ**、かつ **バッチ内で最初の 1 回だけ**
+ * （first-write-wins）。したがって `prev` は「そのバッチが始まる前の値」、`cur` は
+ * drain 時点の確定値になる。同一バッチ内の中間値は観測できない（§3-4）。
+ *
+ * 値の出どころは same-value guard が既に読んでいる旧値であり、watch のために
+ * 追加の getByAddress は行わない（§10）。その帰結として:
+ * - 参照型（object / array）は guard が素通しするので `prev` は undefined
+ * - `config.sameValueGuard = false` でも undefined
+ * - `$postUpdate` / stream の status 通知は setByAddress を通らないので undefined
+ *
+ * 台帳は drain 終端（watchRuntime）でクリアされる。drain の外で書き込まれた分が
+ * 次のバッチへ持ち越されることはない。
+ */
+const prevValueByAbsoluteStateAddress = new Map();
+/**
+ * バッチ内で最初の書き込みのときだけ旧値を記録する（first-write-wins）。
+ */
+function recordPrevValue(absAddress, oldValue) {
+    if (prevValueByAbsoluteStateAddress.has(absAddress)) {
+        return;
     }
-    if (customElements.get(tagName)) {
-        // 既に登録済みならスキップ（重複定義の検知のため警告は出す）
-        console.warn(`[@wcstack/state] DCC: "${tagName}" is already registered. Skipping redefinition.`);
+    prevValueByAbsoluteStateAddress.set(absAddress, oldValue);
+}
+/**
+ * 記録済みの旧値を返す。記録が無ければ undefined（§4-1 の「prev を保証しない」経路）。
+ */
+function getPrevValue(absAddress) {
+    return prevValueByAbsoluteStateAddress.get(absAddress);
+}
+/**
+ * 台帳をクリアする（drain 終端で必ず呼ぶ）。
+ */
+function clearPrevValues() {
+    prevValueByAbsoluteStateAddress.clear();
+}
+
+/**
+ * watch/watchRuntime.ts
+ *
+ * `$watch` の発火（docs/state-watch-hook-design.md §3 / §7）。
+ *
+ * updater の drain 終了フックに 1 つだけリスナーを登録し、バッチに載った絶対アドレスと
+ * 宣言済み watch パスを突き合わせて発火する。**binding の有無に関係なくバッチへ載る**ので、
+ * これが headless 購読の実体になる（binding 駆動の `$updatedCallback` との違い）。
+ *
+ * 実行順序（設計書 §3-2）:
+ * - 機構間は優先度で固定（`$updatedCallback` → `$watch` → `$streams` restart）。
+ *   `$updatedCallback` が先なのは binding 適用ループの内側で呼ばれる構造的必然。
+ * - watch ハンドラ間は `$watch` の宣言順（entry.order）。利用者が順序に意思を持てる唯一の層。
+ * - 同一パスの複数行は indexes 昇順。
+ *
+ * 収集と発火を 2 相に分ける理由:
+ * 1. ハンドラ内の書き込みが registry / active 集合を同期的に変えうる（`_state` 再 set・切断）
+ *    ため、発火直前に live 再チェックが要る（`$streams` の restart hits と同型）。
+ * 2. 上記の順序規約のために hits をソートする必要がある（バッチの反復順は enqueue 順）。
+ */
+/**
+ * この stateElement の `$watch` を有効化する（`State.connectedCallback` ／接続中の
+ * `_state` 再 set から呼ばれる。無効化は `clearWatchRegistry`）。
+ *
+ * `addActiveWatchStateElement` の薄いラッパではなく、**State が runtime を import する
+ * 経路をここに一本化する**意味がある: drain リスナーの登録はこのモジュールの
+ * 初期化副作用なので、registry だけを import すると発火機構ごと落ちる。
+ * `$streams` の `startStreams` と対称の位置づけ。
+ *
+ * **宣言が 1 つも無ければ active 集合に入れない**（`startStreams` の
+ * `entries.size === 0` early return と同型）。ここを無条件にすると active 集合が
+ * 「接続中の全 `<wcs-state>`」になり、`fireWatchOnUpdateBatch` の early return が
+ * 実アプリで効かなくなる ＝ `$watch` 未使用アプリの drain にも収集ループが乗る
+ * （ゼロコスト契約、設計書 §10 ／ 実装計画 P16）。
+ */
+function startWatch(stateElement) {
+    if (getWatchEntries(stateElement).size === 0) {
         return;
     }
+    addActiveWatchStateElement(stateElement);
+    primeComputedWatches(stateElement);
+}
+/**
+ * watch 対象の computed（getter）を 1 回評価する（設計書 §5-2 の eager 化、C-3）。
+ *
+ * これが要るのは、getter の依存（dynamicDependency）が**評価時にしか張られない**ため。
+ * 一度も評価されていない getter は依存グラフに載らず、依存の書き込みが walkDependency で
+ * そのパスへ到達しないので、バッチにも載らず watch が永久に発火しない。ここで 1 回
+ * 読むことで依存が張られ、同時に `prev` の初期スナップショットが埋まる。
+ *
+ * **これが「watch した getter は lazy でなくなる」の実体**であり、設計書 §5-2 で
+ * 規範として明記している副作用（毎バッチ評価・例外の表面化・依存の再登録）の起点。
+ *
+ * ワイルドカードを含む getter パス（`items.*.tax` など）は対象外: 初回評価に行ごとの
+ * indexes が要り、全行評価は宣言しただけでリスト全体を舐めることになる。この形は
+ * 「DOM にバインドされていれば発火する」ままとし、§5-3 に制約として書く。
+ */
+function primeComputedWatches(stateElement) {
+    // 宣言が 1 つ以上あることは startWatch が保証済み
+    const targets = [];
+    for (const entry of getWatchEntries(stateElement).values()) {
+        if (isScalarComputed(stateElement, entry)) {
+            targets.push(entry);
+        }
+    }
+    if (targets.length === 0) {
+        // getter を watch していないなら createState ごと省く（宣言の大半はこちら）
+        return;
+    }
+    stateElement.createState("readonly", (state) => {
+        for (const entry of targets) {
+            try {
+                setComputedSnapshot(stateElement, absoluteAddressOf(stateElement, entry), state[entry.path]);
+            }
+            catch (e) {
+                // 初回評価の throw は接続を巻き添えにしない（発火時と同じ隔離方針、§7-1）
+                reportWatchError(stateElement, entry.path, "prime", e);
+            }
+        }
+    });
+}
+/** ワイルドカードを含まない watch パスの絶対アドレス（listIndex は常に null） */
+function absoluteAddressOf(stateElement, entry) {
+    return createAbsoluteStateAddress(getAbsolutePathInfo(stateElement, entry.pathInfo), null);
+}
+/**
+ * 前回評価値のスナップショット台帳（computedSnapshots）に載せる entry か。
+ *
+ * ワイルドカードを含む getter を**除く**のが要点。除かないと台帳のキーが行ごとの
+ * 絶対アドレス（＝ listIndex を強参照）になり、prune 経路が `_state` 再 set しか
+ * 無いため、行が入れ替わり続けるページで単調増加する（リスト置換 5 回で 2→10 件を実測）。
+ * そもそもワイルドカード getter は eager 化の対象外（設計書 §5-3）なので、
+ * 「初回評価もしない・前回値も持たない」で primeComputedWatches と対称になる。
+ * この形の `prev` は常に undefined（getter は setByAddress を通らない）。
+ */
+function isScalarComputed(stateElement, entry) {
+    return entry.pathInfo.wildcardCount === 0 && stateElement.getterPaths.has(entry.path);
+}
+/**
+ * throw を報告する（設計書 §7-1）。
+ *
+ * `console.error` だけだと **devtools からは「静かに握られた失敗」が見えない**。
+ * watch は drain フックを `$streams` と共有しており、例外を watch 側で閉じるのが
+ * 前提なので、閉じた事実をここで観測可能にしておく必要がある。
+ * イベント生成は必ず `devtoolsSink !== null` の内側で行う（sink のコスト規範）。
+ */
+const WATCH_ERROR_SUBJECT = {
+    prime: "initial evaluation of",
+    evaluate: "evaluation of",
+    handler: "handler for",
+};
+function reportWatchError(stateElement, path, phase, error) {
+    console.error(`[@wcstack/state] $watch ${WATCH_ERROR_SUBJECT[phase]} "${path}" threw.`, error);
+    if (devtoolsSink !== null) {
+        devtoolsSink({
+            type: "state:watch-error",
+            phase,
+            stateName: stateElement.name,
+            path,
+            error,
+        });
+    }
+}
+function fireWatchOnUpdateBatch(batch) {
+    const activeStateElements = getActiveWatchStateElements();
+    try {
+        if (activeStateElements.size === 0) {
+            // watch 未使用アプリの drain に配列・イテレータ割り当てのコストを載せない。
+            // ここも finally を通す: 宣言済みの state が切断されている間（active からは
+            // 外れるが watchPaths は残る）の書き込みで台帳に旧値が積まれるため、
+            // クリアを早期 return の外に置くと次のバッチどころか永久に残る。
+            return;
+        }
+        const depth = consumeWatchChainDepth();
+        if (depth > MAX_WATCH_CHAIN_DEPTH) {
+            // 打ち切るのは watch の発火のみ。値と binding 適用は巻き戻さない
+            // （伝播 hop 上限超過時の quarantine と同じ姿勢、§7-2）。
+            const paths = Array.from(batch, (absAddress) => absAddress.absolutePathInfo.pathInfo.path);
+            console.error(`[@wcstack/state] $watch chain depth limit exceeded; watch handlers for this batch were skipped.`, { maxDepth: MAX_WATCH_CHAIN_DEPTH, paths });
+            if (devtoolsSink !== null) {
+                devtoolsSink({ type: "state:watch-chain-limit", maxDepth: MAX_WATCH_CHAIN_DEPTH, paths });
+            }
+            return;
+        }
+        // --- 収集フェーズ ---
+        const hits = [];
+        for (const absAddress of batch) {
+            // stateName 文字列ではなく stateElement 参照で引く。AbsolutePathInfo は
+            // stateElement 単位でキャッシュされるので、同名 state が複数の rootNode に
+            // 居ても取り違えない（address/AbsolutePathInfo.ts）。他 state のアドレスは
+            // ここで自然に落ちる ＝ 越境しない（設計 D8）。
+            const stateElement = absAddress.absolutePathInfo.stateElement;
+            if (!activeStateElements.has(stateElement)) {
+                continue;
+            }
+            const entry = getWatchEntries(stateElement).get(absAddress.absolutePathInfo.pathInfo.path);
+            if (typeof entry === "undefined") {
+                continue;
+            }
+            let indexes = [];
+            if (entry.pathInfo.wildcardCount > 0) {
+                if (absAddress.listIndex === null) {
+                    // ワイルドカードパスなのに行が特定できないヒット（リストの依存展開で載る
+                    // 中間アドレス等）。indexes を空のまま発火すると cur の解決（$resolve）が
+                    // 「indexes 不足」で throw し、例外隔離に落ちて console.error だけが残る。
+                    // 行が定まらない以上ハンドラに渡せる意味が無いので、収集段階で落とす。
+                    continue;
+                }
+                indexes = getScopedIndexes(absAddress.listIndex, entry.pathInfo.wildcardCount);
+            }
+            hits.push({ stateElement, entry, absAddress, indexes });
+        }
+        if (hits.length === 0) {
+            return;
+        }
+        hits.sort(compareHits);
+        // --- 発火フェーズ ---
+        beginWatchFiring(depth);
+        try {
+            for (const hit of hits) {
+                // 先行ハンドラが同期的に切断や `_state` 再 set を行い得るため、発火直前に
+                // 「まだ active か」「entry が現行 registry のものか」を再確認する。
+                if (!activeStateElements.has(hit.stateElement) ||
+                    getWatchEntries(hit.stateElement).get(hit.entry.path) !== hit.entry) {
+                    continue;
+                }
+                fireOne(hit);
+            }
+        }
+        finally {
+            endWatchFiring();
+        }
+    }
+    finally {
+        // 旧値台帳はこの drain 限りのもの。次のバッチへ持ち越さない（§4-1）。
+        clearPrevValues();
+    }
+}
+/**
+ * 層 2（宣言順）→ 層 3（indexes 昇順）の順に比較する（設計書 §3-3）。
+ */
+function compareHits(a, b) {
+    if (a.entry.order !== b.entry.order) {
+        return a.entry.order - b.entry.order;
+    }
+    const length = Math.min(a.indexes.length, b.indexes.length);
+    for (let i = 0; i < length; i++) {
+        if (a.indexes[i] !== b.indexes[i]) {
+            return a.indexes[i] - b.indexes[i];
+        }
+    }
+    return a.indexes.length - b.indexes.length;
+}
+/**
+ * ハンドラ 1 つを発火する。**例外はここで閉じる**（設計書 §7-1）。
+ *
+ * drain リスナーの throw は握りつぶさない契約（updater.ts）なので、watch 側で捕まえないと
+ * 1 つのユーザー例外が他の watch と `$streams` の restart を巻き添えにする。
+ * `$connectedCallback` / `$updatedCallback` の loud fail とは意図的に異なる扱い。
+ *
+ * 報告は throw 元で分ける: `cur` の解決（watch した getter の強制評価 ＝ §5-2 の副作用 b）と
+ * ハンドラ本体では原因も直し方も違うため、同じ文言に丸めない。
+ */
+function fireOne(hit) {
+    const { stateElement, entry, absAddress, indexes } = hit;
+    // スカラ getter は setByAddress を通らないので旧値台帳に載らない。前回評価値の
+    // スナップショット（バッチを跨いで生きる別台帳）から prev を取る（§5-2）。
+    const isComputed = isScalarComputed(stateElement, entry);
+    try {
+        stateElement.createState("writable", (state) => {
+            let cur;
+            try {
+                // 強制評価はここ。dirty なら再計算され、その結果が cur になる
+                cur = readCurrentValue(state, entry, indexes);
+            }
+            catch (e) {
+                // cur が得られない以上ハンドラは呼べない。次の hit へ進む
+                reportWatchError(stateElement, entry.path, "evaluate", e);
+                return;
+            }
+            const prev = isComputed ? getComputedSnapshot(stateElement, absAddress) : getPrevValue(absAddress);
+            if (isComputed) {
+                // ハンドラ本体が throw しても次回の prev は「今回の評価値」であるべきなので、
+                // handler 呼び出しより前に更新する
+                setComputedSnapshot(stateElement, absAddress, cur);
+            }
+            entry.handler.call(state, cur, prev, ...indexes);
+        });
+    }
+    catch (e) {
+        reportWatchError(stateElement, entry.path, "handler", e);
+    }
+}
+function readCurrentValue(state, entry, indexes) {
+    if (entry.pathInfo.wildcardCount === 0) {
+        return state[entry.path];
+    }
+    // ワイルドカードを含むパスは素の読みでは解決できない。getScopedIndexes が返した列は
+    // そのまま $resolve の引数として使える（list/wildcardLevel.ts の往復契約）。
+    return state.$resolve(entry.path, indexes);
+}
+// 優先度で `$streams` の restart より先に固定する（設計書 §3-2 層 1）。import 順には依存しない。
+registerUpdateBatchListener(fireWatchOnUpdateBatch, WATCH_LISTENER_PRIORITY);
+
+function getterFn(name) {
+    return function () {
+        const stateEl = this.stateElement;
+        if (!stateEl)
+            return undefined;
+        // state のロード前は「まだ値が無い」だけで異常ではない。行がまだ fragment 上にある間の
+        // 初期スナップショット読み（BindingSession.readProducerSnapshot）は必ずここを通るので、
+        // warn を出すと通常フローが騒がしくなる
+        // （docs/architecture-hardening/15-state-component-mechanism-consistency.md §2.2）。
+        if (stateEl.initialized !== true)
+            return undefined;
+        let value;
+        try {
+            stateEl.createState("readonly", (state) => {
+                value = state[name];
+            });
+        }
+        catch (e) {
+            console.warn(`[@wcstack/state] DCC getter "${name}" failed:`, e);
+            return undefined;
+        }
+        return value;
+    };
+}
+function setterFn(name) {
+    return function (value) {
+        const stateEl = this.stateElement;
+        if (!stateEl)
+            return;
+        // 初期化済みなら同期で書く。getter は同期なので、ここを常に initializePromise 経由に
+        // すると `el.count = 5; el.count` が旧値を返す（§2.2）。未初期化のときだけ遅延させる
+        // ＝ 未接続の行に書かれた値が捨てられないための経路（§1.4）はそのまま残る。
+        if (stateEl.initialized === true) {
+            stateEl.createState("writable", (state) => {
+                state[name] = value;
+            });
+            return;
+        }
+        stateEl.initializePromise.then(() => {
+            stateEl.createState("writable", (state) => {
+                state[name] = value;
+            });
+        });
+    };
+}
+function callFn(name, isAsync) {
+    // 戻り値は常に Promise。state 側のメソッドが同期でも初期化待ちが挟まりうるため、
+    // 呼び出し側から見た型を揃える（wcBindable.commands が一律 `async: true` を宣言するのと対）。
+    if (isAsync) {
+        return function (...args) {
+            const stateEl = this.stateElement;
+            if (!stateEl)
+                return undefined;
+            return stateEl.initializePromise.then(() => {
+                let result;
+                return stateEl.createStateAsync("writable", async (state) => {
+                    result = await state[name](...args);
+                }).then(() => result);
+            });
+        };
+    }
+    return function (...args) {
+        const stateEl = this.stateElement;
+        if (!stateEl)
+            return undefined;
+        return stateEl.initializePromise.then(() => {
+            let result;
+            stateEl.createState("writable", (state) => {
+                result = state[name](...args);
+            });
+            return result;
+        });
+    };
+}
+function isInternalProperty(name) {
+    return name.startsWith("$");
+}
+
+function getAllPropertyDescriptors(obj) {
+    const chain = [];
+    let proto = obj;
+    while (proto && proto !== Object.prototype) {
+        chain.push(proto);
+        proto = Object.getPrototypeOf(proto);
+    }
+    const descriptors = {};
+    for (let i = chain.length - 1; i >= 0; i--) {
+        Object.assign(descriptors, Object.getOwnPropertyDescriptors(chain[i]));
+    }
+    return descriptors;
+}
+
+/**
+ * DCC の `$bindables` / `$commands` 宣言を解析・検証する。
+ *
+ * 検証の強度は `$commandTokens` / `$eventTokens` と揃える
+ * （docs/architecture-hardening/15-state-component-mechanism-consistency.md §1.5 / §2.3 / §1.6）。
+ * 従来 `$bindables` は `Array.isArray(...) ? ... : []` だけで、
+ *
+ *   - 非配列を無言で空扱いにする
+ *   - 重複名をそのまま `createWcBindable` に流す
+ *   - `$` 始まりの名前を通す
+ *   - state に存在しない名前を通す
+ *
+ * という 4 つの穴があった。特に重複は害が大きい: `readNamedList`（protocol/wcBindableReader.ts）は
+ * 重複名を見つけると `null` を返すため、`readBindableDeclaration()` が宣言全体を棄却し、
+ * 双方向バインド・spread・initialSync の bindable 判定が**警告なしで**丸ごと死ぬ。
+ * 自前のファクトリが自前の reader に棄却される状態なので、生成前に落とす。
+ */
+function readNameList(state, declarationName) {
+    const declared = state[declarationName];
+    if (typeof declared === "undefined") {
+        return null;
+    }
+    if (!Array.isArray(declared)) {
+        raiseError(`${declarationName} must be an array of strings.`);
+    }
+    const names = [];
+    const seen = new Set();
+    for (const name of declared) {
+        if (typeof name !== "string" || name.length === 0) {
+            raiseError(`${declarationName} entries must be non-empty strings.`);
+        }
+        if (name.startsWith("$")) {
+            raiseError(`${declarationName} entry "${name}" must not start with "$" (internal properties are not exposed on the component).`);
+        }
+        if (seen.has(name)) {
+            raiseError(`${declarationName} entry "${name}" is duplicated.`);
+        }
+        seen.add(name);
+        names.push(name);
+    }
+    return names;
+}
+/**
+ * `$streams` が宣言している名前。値プロパティはインスタンス側の実体化まで state 上に
+ * 現れないため、存在検査ではここも「実在する名前」として扱う（§2.3）。
+ * 宣言そのものの妥当性検査は processStreamsDeclaration の責務なので、ここでは
+ * キーの取り出しだけを行い、形が違えば黙って空集合を返す。
+ */
+function getStreamNames(state) {
+    const declared = state[STATE_STREAMS_NAME];
+    if (typeof declared !== "object" || declared === null) {
+        return new Set();
+    }
+    return new Set(Object.keys(declared));
+}
+function processDccDeclarations(state) {
+    const bindables = readNameList(state, STATE_BINDABLES_NAME) ?? [];
+    const commands = readNameList(state, STATE_COMMANDS_NAME) ?? [];
+    const descriptors = getAllPropertyDescriptors(state);
+    const streamNames = getStreamNames(state);
+    const streamBackedBindables = [];
+    for (const name of bindables) {
+        const descriptor = descriptors[name];
+        if (typeof descriptor === "undefined") {
+            // `$streams` 由来なら実体化後に現れるので通す。アクセサはこちらで補う。
+            if (streamNames.has(name)) {
+                streamBackedBindables.push(name);
+                continue;
+            }
+            raiseError(`${STATE_BINDABLES_NAME} entry "${name}" is not declared on the state.`);
+        }
+        if (typeof descriptor.value === "function") {
+            raiseError(`${STATE_BINDABLES_NAME} entry "${name}" is a method. Declare it in ${STATE_COMMANDS_NAME} instead.`);
+        }
+    }
+    for (const name of commands) {
+        const descriptor = descriptors[name];
+        if (typeof descriptor === "undefined") {
+            raiseError(`${STATE_COMMANDS_NAME} entry "${name}" is not declared on the state.`);
+        }
+        if (typeof descriptor.value !== "function") {
+            raiseError(`${STATE_COMMANDS_NAME} entry "${name}" is not a method. Declare it in ${STATE_BINDABLES_NAME} instead.`);
+        }
+    }
+    return { bindables, commands, streamBackedBindables };
+}
+
+function createWcBindable(tagName, bindables, commands = []) {
+    const properties = bindables.map((propName) => ({
+        name: propName,
+        event: `${tagName}:${propName}-changed`,
+        // Read the member off the element instead of trusting event.detail. The event is a
+        // notification, not a carrier: a sub-path write (`user.name = "x"` against a `user`
+        // member) has no single value to put in detail, and a state-side setter may normalize
+        // what was written. Both cases are correct through the property.
+        getter: (event) => event.target[propName],
+    }));
+    // Every $bindables member gets both a getter and a setter on the DCC prototype,
+    // so declare it in inputs as well — a property declared only in `properties` is
+    // output-only under directional initial sync, which would permanently block
+    // parent-state → DCC writes.
+    const inputs = bindables.map((propName) => ({
+        name: propName,
+    }));
+    const declaration = {
+        protocol: "wc-bindable",
+        version: 1,
+        properties,
+        inputs,
+    };
+    if (commands.length === 0) {
+        return declaration;
+    }
+    // `async: true` is uniform on purpose: dccPropertyFactories.callFn always chains on the
+    // inner <wcs-state>'s initializePromise, so a DCC command returns a Promise whether or not
+    // the underlying state method was declared `async`. Reporting the state method's own
+    // asyncness would describe something callers never observe.
+    const declaredCommands = commands.map((name) => ({
+        name,
+        async: true,
+    }));
+    return { ...declaration, commands: declaredCommands };
+}
+function createBindableEventMap(tagName, bindables) {
+    const map = {};
+    for (const propName of bindables) {
+        map[propName] = `${tagName}:${propName}-changed`;
+    }
+    return map;
+}
+
+function defineDCC(hostElement, shadowRoot, state) {
+    const tagName = hostElement.tagName.toLowerCase();
+    // バリデーション
+    if (!tagName.includes("-")) {
+        raiseError(`DCC: "${tagName}" is not a valid custom element name (must contain a hyphen).`);
+    }
+    if (customElements.get(tagName)) {
+        // 重複定義は authoring error として落とす。従来は warn してスキップしていたが、
+        // 先勝ちで別テンプレートのインスタンスが生えるため「動いているように見えて中身が違う」
+        // 状態になる。state 名の重複（stateElementByName）が raiseError なのと作法を揃える
+        // （docs/architecture-hardening/15-state-component-mechanism-consistency.md §3.4）。
+        raiseError(`DCC: "${tagName}" is already registered. A custom element name can only be defined once.`);
+    }
     // ShadowRoot は cloneNode 不可のため、template 経由で内容をクローン
     const template = document.createElement("template");
     template.innerHTML = shadowRoot.innerHTML;
     const shadowRootMode = shadowRoot.mode;
-    // $bindables から wcBindable + bindableEventMap を生成
-    const bindables = Array.isArray(state[STATE_BINDABLES_NAME])
-        ? state[STATE_BINDABLES_NAME]
-        : [];
-    const wcBindable = bindables.length > 0
-        ? createWcBindable(tagName, bindables)
+    // $bindables / $commands から wcBindable + bindableEventMap を生成
+    const { bindables, commands, streamBackedBindables } = processDccDeclarations(state);
+    const wcBindable = (bindables.length > 0 || commands.length > 0)
+        ? createWcBindable(tagName, bindables, commands)
         : null;
     const bindableEventMap = bindables.length > 0
         ? createBindableEventMap(tagName, bindables)
@@ -9545,27 +11318,79 @@ function defineDCC(hostElement, shadowRoot, state) {
         static wcBindable = wcBindable;
         static bindableEventMap = bindableEventMap;
         _shadow = null;
-        connectedCallback() {
+        /**
+         * shadow を遅延構築する。定義要素（`data-wc-definition`）では null を返す。
+         *
+         * connectedCallback ではなくここで張るのは、**接続前にアクセサが呼ばれる**ため
+         * （§1.4）。`for` の全追加パスは行を fragment に組み立ててからバインドを適用し、
+         * fragment を DOM に挿すのは最後なので、`element.count = v` の時点で行はまだ未接続。
+         * shadow が無いと `stateElement` が null になり、setterFn が無言で書き込みを捨てていた。
+         * ここで構築しておけば、書き込みは inner `<wcs-state>` の initializePromise に
+         * 積まれ、接続・state ロード後に適用される。
+         *
+         * 冪等なので再接続でも張り直さない。shadow tree は host の切断後も保持され、
+         * 2 回目の attachShadow は NotSupportedError になる（§1.3）。`if` の false→true
+         * 再マウントと `for` の行プーリングはどちらも同一ノードを unmount → mount する。
+         * closed mode では `this.shadowRoot` が null なので判定はフィールド側で行う。
+         *
+         * G4 は「constructor へ前倒し」で決着したが、実装は constructor ではなく
+         * この遅延構築を採った。目的（未接続でもアクセサが動く）は同じで、constructor 版だと
+         * (1) 定義要素の判定に属性を読む必要があり constructor の作法に反する、
+         * (2) 同一タグの `data-wc-definition` が 2 つある場合、DSD の shadow を既に持つ
+         * 2 つ目に attachShadow して throw する、の 2 点を踏むため。
+         */
+        _ensureShadow() {
+            if (this._shadow !== null)
+                return this._shadow;
             if (this.hasAttribute(DCC_DEFINITION_ATTRIBUTE))
-                return;
+                return null;
             this._shadow = this.attachShadow({ mode: DCCElement.shadowRootMode });
             this._shadow.appendChild(DCCElement.template.content.cloneNode(true));
-            // bindableEventMap の設定
+            // template.content は inert なテンプレート所有ドキュメントに属するため、その clone は
+            // カスタム要素として upgrade されていない。ホストが接続済みなら appendChild の時点で
+            // upgrade されるが、未接続の shadow に挿した場合は upgrade 契機が無く、内側の
+            // <wcs-state> が素の HTMLElement のまま残って createState が生えない。明示的に upgrade する。
+            const registry = getCustomElementRegistry();
+            if (registry !== null) {
+                upgradeCustomElement(registry, this._shadow);
+            }
+            return this._shadow;
+        }
+        connectedCallback() {
+            const shadow = this._ensureShadow();
+            if (shadow === null)
+                return;
+            // bindableEventMap の設定。
+            // initializePromise は待たない。待つと state のロード完了まで map が空のままで、
+            // $connectedCallback 内で行った初期変更が変更イベントを出さない
+            // （docs/architecture-hardening/15-state-component-mechanism-consistency.md §2.7）。
+            // setBindableEventMap はフィールド代入だけで state を参照しないので、
+            // <wcs-state> の初期化前に呼んでも安全。
             if (Object.keys(DCCElement.bindableEventMap).length > 0) {
-                const stateEl = this._shadow.querySelector(stateTagSelector);
+                const stateEl = shadow.querySelector(stateTagSelector);
                 if (stateEl) {
-                    stateEl.initializePromise.then(() => {
-                        stateEl.setBindableEventMap(DCCElement.bindableEventMap);
-                    });
+                    stateEl.setBindableEventMap(DCCElement.bindableEventMap);
+                }
+                else {
+                    // $bindables を宣言しているのに束ねる先が無い。stateTagSelector は
+                    // `:not([name])` なので name 付きの <wcs-state> は一致せず、この分岐に落ちると
+                    // 変更イベントが一切出ないまま静かに壊れる
+                    // （docs/architecture-hardening/15-state-component-mechanism-consistency.md §2.5）。
+                    console.warn(`[@wcstack/state] DCC: "${tagName}" declares ${STATE_BINDABLES_NAME} but its template has no <${config.tagNames.state}> without a "name" attribute. Change events will not be dispatched.`);
                 }
             }
         }
         get stateElement() {
-            return this._shadow?.querySelector(stateTagSelector);
+            // 未接続でも shadow を構築して解決する（§1.4）。
+            return (this._ensureShadow()?.querySelector(stateTagSelector) ?? null);
         }
     };
-    // state プロパティを走査して DCC クラスのプロトタイプにgetter/setter/methodを定義
-    const descriptors = Object.getOwnPropertyDescriptors(state);
+    // state プロパティを走査して DCC クラスのプロトタイプにgetter/setter/methodを定義。
+    // 走査範囲は State の getterPaths / setterPaths 収集と同じ「自身＋プロトタイプチェーン」に
+    // 揃える。own descriptor だけを見ていた頃は、クラスインスタンスや Object.create(proto) の
+    // state で「getterPaths には載るのにアクセサが生えない」乖離が出ていた
+    // （docs/architecture-hardening/15-state-component-mechanism-consistency.md §2.4）。
+    const descriptors = getAllPropertyDescriptors(state);
     for (const [name, desc] of Object.entries(descriptors)) {
         if (isInternalProperty(name))
             continue;
@@ -9580,6 +11405,17 @@ function defineDCC(hostElement, shadowRoot, state) {
         }
         Object.defineProperty(DCCElement.prototype, name, newDesc);
     }
+    // `$streams` の値プロパティはインスタンス側の processStreamsDeclaration で実体化されるため、
+    // defineDCC の時点では state 上に descriptor が無い。$bindables に載っているのに
+    // アクセサが生えないと宣言だけが生きて要素側が expando を掴むので、ここで補う（§2.3）。
+    for (const name of streamBackedBindables) {
+        Object.defineProperty(DCCElement.prototype, name, {
+            configurable: true,
+            enumerable: true,
+            get: getterFn(name),
+            set: setterFn(name),
+        });
+    }
     // カスタム要素登録
     customElements.define(tagName, DCCElement);
 }
@@ -9747,6 +11583,56 @@ function dirtyCacheEntryByAbsoluteStateAddress(address) {
     }
 }
 
+/**
+ * webComponent/crossBoundaryAddress.ts
+ *
+ * mapped な `bind-component` の state は innerState proxy を target に持つ。
+ * そこへの読み書きは `Reflect.get/set(target, path)` で行われるため、Proxy の
+ * トラップに渡るのは**パス文字列だけ**で、解決済みの listIndex が落ちる。
+ *
+ * 子スコープが `for:` でマップ先の配列を回している場合、行バインディングが読む
+ * `items.*.name` は親スコープの `rows.*.name` に翻訳されるが、どの行かは listIndex
+ * にしか無い。ループ文脈はコンポーネント要素（親スコープ側）にぶら下がっており、
+ * 子スコープのループはコンポーネントの内側なので `getLoopContextByNode` では引けない
+ * （docs/architecture-hardening/15-state-component-mechanism-consistency.md §1.8）。
+ *
+ * そこで越境直前のアドレスを動的スコープで受け渡す。push/pop するのは
+ * `hasMappedComponentState` が真の state 要素の読み書きだけで、通常の state の
+ * ホットパス（getByAddress / setByAddress）には一切載らない。
+ */
+// 行ごとの読み書きで通るため、エントリオブジェクトを割り当てずに 2 本の並行配列で持つ
+// （リスト描画は「行数 × 行内バインディング数」回ここを通る）。
+const stateElementStack = [];
+const addressStack = [];
+let depth = 0;
+function pushCrossBoundaryAddress(stateElement, address) {
+    stateElementStack[depth] = stateElement;
+    addressStack[depth] = address;
+    depth++;
+}
+function popCrossBoundaryAddress() {
+    depth--;
+    // 参照を残さない（state 要素・listIndex を保持し続けないため）
+    stateElementStack[depth] = undefined;
+    addressStack[depth] = undefined;
+}
+/**
+ * 越境直前のアドレスを取り出す。スタック最上位が「この state 要素の、このパスの
+ * 読み書き」であるときだけ返す。ネストしたコンポーネントでは最内の越境が
+ * 最上位になるため、同一性の照合だけで取り違えを防げる。
+ */
+function getCrossBoundaryAddress(stateElement, path) {
+    if (depth === 0) {
+        return null;
+    }
+    const top = depth - 1;
+    const address = addressStack[top];
+    if (stateElementStack[top] !== stateElement || address?.pathInfo.path !== path) {
+        return null;
+    }
+    return address;
+}
+
 function checkDependency(handler, address) {
     // $untrackDependency スコープ中／setter 実行中は依存を張らない
     if (handler.untracking) {
@@ -9770,9 +11656,18 @@ function checkDependency(handler, address) {
                 if (address.pathInfo.wildcardCount > 0 && lastInfo.wildcardCount > 0) {
                     const sharedLen = calcWildcardLen(address.pathInfo, lastInfo);
                     if (sharedLen > 0) {
+                        // 共有ワイルドカード段の突き合わせ。base 深さ Δ を持つ子スコープでは
+                        // 先頭起点だと Δ 段目（＝親子で常に同一の base）を比べてしまい、
+                        // 本物の他行読み取りを取りこぼす。末尾起点で数える（list/wildcardLevel.ts）
                         let crossRow = false;
+                        const hereChain = address.listIndex ?? null;
+                        const thereChain = lastAddress.listIndex ?? null;
                         for (let level = 0; level < sharedLen; level++) {
-                            if (address.listIndex?.at(level) !== lastAddress.listIndex?.at(level)) {
+                            const here = hereChain !== null
+                                ? listIndexAtWildcard(hereChain, level, address.pathInfo.wildcardCount) : null;
+                            const there = thereChain !== null
+                                ? listIndexAtWildcard(thereChain, level, lastInfo.wildcardCount) : null;
+                            if (here !== there) {
                                 crossRow = true;
                                 break;
                             }
@@ -9789,6 +11684,28 @@ function checkDependency(handler, address) {
     }
 }
 
+/**
+ * このアドレスの値をキャッシュしてよいか（getByAddress / setByAddress 共通の判定）。
+ *
+ * ワイルドカードを含むパス（リスト行）と宣言済み getter は再評価が高くつくため
+ * キャッシュする。ただし mapped な `bind-component` の state は例外で、丸ごと外す。
+ *
+ * mapped な state は値を持たず、読みも書きも親スコープの state へ解決される
+ * （innerState proxy）。同じ値は親側のキャッシュにも載り、その無効化は親の依存 walk が
+ * 担う。子側にもう一段キャッシュを置くと、正本でない複製を親の無効化が届かない場所に
+ * 作ることになり、親起点の書き込みのあと子だけが旧値を読み続ける。二重に持たないのが
+ * 唯一の整合手段なので、mapped な state 要素ではキャッシュ層を持たない — 親の
+ * キャッシュがそのまま効くので、失うのは重複していた一段だけ
+ * （docs/architecture-hardening/15-state-component-mechanism-consistency.md §1.8）。
+ */
+function isCacheable(stateElement, address) {
+    if (stateElement.hasMappedComponentState === true) {
+        return false;
+    }
+    return address.pathInfo.wildcardCount > 0 ||
+        stateElement.getterPaths.has(address.pathInfo.path);
+}
+
 /**
  * getByAddress.ts
  *
@@ -9856,6 +11773,17 @@ function _getByAddress(target, address, receiver, handler, stateElement) {
                 handler.popAddress();
             }
         }
+        else if (stateElement.hasMappedComponentState === true) {
+            // target は innerState proxy。get トラップにはパス文字列しか渡らないので、
+            // 解決済みの listIndex を動的スコープで越境させる（§1.8）
+            pushCrossBoundaryAddress(stateElement, address);
+            try {
+                return Reflect.get(target, address.pathInfo.path);
+            }
+            finally {
+                popCrossBoundaryAddress();
+            }
+        }
         else {
             return Reflect.get(target, address.pathInfo.path);
         }
@@ -9863,6 +11791,20 @@ function _getByAddress(target, address, receiver, handler, stateElement) {
     else {
         const parentAddress = address.parentAddress ?? raiseError(`address.parentAddress is undefined path: ${address.pathInfo.path}`);
         const parentValue = getByAddress(target, parentAddress, receiver, handler);
+        // 親が居ないパスの読みは undefined（＝「state に意見が無い」）。`Reflect.get` に
+        // そのまま渡すと生の `TypeError: Reflect.get called on non-object` になり、
+        // updater の drain も行ループも捕まえないので **1 本の stale な読みが同じバッチの
+        // 無関係な更新まで道連れにする**（§1.7 / §1.9 と同じ構図）。
+        //
+        // 実際に踏むのは「消えた行を指すバインディングが、その行を消す `for` より先に
+        // 適用される」形。同一スコープならトポロジカル順で `for` が先に来るので起きないが、
+        // bind-component は親スコープの通知と子スコープの `for` が別経路で流れるため
+        // 順序が保証されない（docs/state-bind-component-nested-for-design.md）。
+        // undefined はプロパティ書き込みがスキップされる値なので DOM は触られず、
+        // 直後に `for` が行ごと外して整合する。
+        if (parentValue === null || typeof parentValue === "undefined") {
+            return undefined;
+        }
         const lastSegment = address.pathInfo.segments[address.pathInfo.segments.length - 1];
         if (lastSegment === WILDCARD) {
             const index = address.listIndex?.index ?? raiseError(`address.listIndex?.index is undefined path: ${address.pathInfo.path}`);
@@ -9892,8 +11834,7 @@ function getByAddress(target, address, receiver, handler) {
     // $streams の args トレース中のみ絶対アドレスを捕捉（collector 非活性なら即 return）
     collectStreamDependency(handler.stateElement, address);
     const stateElement = handler.stateElement;
-    const cacheable = address.pathInfo.wildcardCount > 0 ||
-        stateElement.getterPaths.has(address.pathInfo.path);
+    const cacheable = isCacheable(stateElement, address);
     if (cacheable) {
         return _getByAddressWithCache(target, address, receiver, handler, stateElement);
     }
@@ -9931,7 +11872,181 @@ function getContextListIndex(handler, structuredPath) {
     if (typeof index === "undefined") {
         return null;
     }
-    return address.listIndex?.at(index) ?? null;
+    if (address.listIndex === null) {
+        return null;
+    }
+    return listIndexAtWildcard(address.listIndex, index, address.pathInfo.wildcardCount);
+}
+
+/**
+ * DCC の `$bindables` メンバの変更イベントを host に dispatch する。
+ *
+ * 対応するのは 3 通り。
+ *
+ *   1. **完全一致** — `count = 1` が `count` メンバを撃つ。`detail` は書き込んだ値。
+ *   2. **サブパス** — `user.name = "x"` や `items.0.done = true` が `user` / `items` メンバを撃つ。
+ *      `$bindables` のエントリは常にフラットなトップレベル名（dotted 名は
+ *      processDccDeclarations の存在検査で落ちる）なので、先頭セグメントを見れば足りる。
+ *      この場合 `detail` は付かない — メンバ全体ではない値を載せると誤解を招くため。
+ *   3. **`$postUpdate`** — in-place 変異を通知する正規の idiom。書き込んだ値が無いので `detail` は付かない。
+ *
+ * `detail` に頼らないのが正しい読み方で、`createWcBindable` は各 property に
+ * `getter: (event) => event.target[name]` を宣言している。observer はイベントを
+ * 「変わった」という通知として受け取り、値は要素から読む。
+ *
+ * 従来は完全一致しか見ておらず、`$bindables: ["user"]` で `user.name` を書いても
+ * 発火しなかった。wc-bindable の `properties[].event` は「変更で発火する」契約なので乖離していた
+ * （docs/architecture-hardening/15-state-component-mechanism-consistency.md §2.1）。
+ *
+ * 配列の in-place 変異（`items.push(...)`）は set トラップを通らないため、ここでも捕まらない。
+ * これはリアクティブコア全体の規範（in-place 変異は `$postUpdate` で通知する）と同じで、
+ * 正しい idiom を踏めば 3 で発火する。
+ *
+ * `$listKeys` を宣言したリストは、配列代入がキー突合後に per-path 書き込みへ分解されるため
+ * （docs/state-list-key-design.md §2）、1 回の代入で `1 + 変化行数` 回発火する。値は要素から
+ * 読む契約なので結果は変わらない。詳細は上記 §2.1 の「`$listKeys` との相互作用」。
+ */
+function dispatchBindableEvent(stateElement, pathInfo, detail) {
+    const map = stateElement.bindableEventMap;
+    const exactEventName = map[pathInfo.path];
+    const isExact = typeof exactEventName === "string";
+    const eventName = isExact
+        ? exactEventName
+        : (pathInfo.segments.length > 1 ? map[pathInfo.segments[0]] : undefined);
+    if (typeof eventName !== "string") {
+        return;
+    }
+    const rootNode = stateElement.rootNode;
+    if (!(rootNode instanceof ShadowRoot)) {
+        return;
+    }
+    rootNode.host.dispatchEvent(new CustomEvent(eventName, {
+        // 完全一致のときだけ、書き込んだ値をそのまま載せる（従来互換）。
+        detail: isExact && typeof detail !== "undefined" ? detail.value : undefined,
+        bubbles: true,
+    }));
+}
+
+/**
+ * list/mergeKeyedList.ts
+ *
+ * `$listKeys` 宣言済みリストパスへの配列代入で、キーが一致する行の
+ * 「オブジェクト強制・値展開」を行う（docs/state-list-key-design.md §2）。
+ *
+ * - キー突合し、一致行は**旧オブジェクトを据え置いた**ハイブリッド配列を作る
+ *   → 配列要素の参照が変わらないので for は行を再利用する（DOM・フォーカス・
+ *     非バインド DOM 状態が保存される）
+ * - 一致行の「変化したフィールド」だけを列挙して返す
+ *   → 呼び出し側が per-path 書き込みとして発行する（§7.0 の穴を塞ぐ正典イディオム）
+ *
+ * このモジュールは純粋な計算のみで、state への書き込みは行わない。
+ */
+/**
+ * 値展開は own enumerable データプロパティのコピーなので、プロトタイプや
+ * アクセサを持つオブジェクトでは意味論が保てない。plain object 以外は即エラー（§5）。
+ */
+function assertPlainRow(row, path, side, position) {
+    if (typeof row !== "object" || row === null) {
+        raiseError(`${STATE_LIST_KEYS_NAME} list "${path}": ${side} row at index ${position} must be a plain object ` +
+            `(got ${row === null ? "null" : typeof row}).`);
+    }
+    const proto = Object.getPrototypeOf(row);
+    if (proto !== Object.prototype && proto !== null) {
+        raiseError(`${STATE_LIST_KEYS_NAME} list "${path}": ${side} row at index ${position} must be a plain object ` +
+            `(class instances and exotic objects cannot be value-expanded).`);
+    }
+}
+function keyOf(row, spec, path, side, position) {
+    const key = typeof spec === "function" ? spec(row) : row[spec];
+    if (key === undefined || key === null) {
+        raiseError(`${STATE_LIST_KEYS_NAME} list "${path}": ${side} row at index ${position} has no key ` +
+            `(${typeof spec === "function" ? "key function" : `field "${spec}"`} returned ${String(key)}).`);
+    }
+    return key;
+}
+/** 行を検証しつつキーを抽出する。キー重複は即エラー（§5）。 */
+function extractKeys(list, spec, path, side) {
+    const keys = new Array(list.length);
+    const seen = new Set();
+    for (let i = 0; i < list.length; i++) {
+        const row = list[i];
+        assertPlainRow(row, path, side, i);
+        const key = keyOf(row, spec, path, side, i);
+        if (seen.has(key)) {
+            raiseError(`${STATE_LIST_KEYS_NAME} list "${path}": duplicate key ${JSON.stringify(key)} in ${side} list.`);
+        }
+        seen.add(key);
+        keys[i] = key;
+    }
+    return keys;
+}
+/**
+ * キー突合してハイブリッド配列を組む。値展開すべき一致行が 1 つも無ければ null
+ * （呼び出し側は従来どおりの書き込みへ倒す）。
+ *
+ * 突合対象の旧配列は「最後に適用された配列」ではなく**現在格納されている配列**。
+ * ハイブリッド構築が格納配列の参照を保存するため、同一マイクロタスク内の連続
+ * 書き込みでも適用時の diff と transitive に整合する（§6）。
+ */
+function mergeKeyedList(path, spec, oldValue, newList) {
+    // 宣言済みパスなら初回代入（旧配列なし）でも新配列を検証する。
+    // 「2 回目の代入で初めて重複キーが露見する」という不連続を避けるため。
+    const newKeys = extractKeys(newList, spec, path, "new");
+    if (!Array.isArray(oldValue) || oldValue.length === 0 || newList.length === 0) {
+        return null;
+    }
+    const oldList = oldValue;
+    const oldKeys = extractKeys(oldList, spec, path, "current");
+    const oldRowByKey = new Map();
+    for (let i = 0; i < oldList.length; i++) {
+        oldRowByKey.set(oldKeys[i], oldList[i]);
+    }
+    const list = new Array(newList.length);
+    const matched = [];
+    for (let i = 0; i < newList.length; i++) {
+        const newRow = newList[i];
+        const oldRow = oldRowByKey.get(newKeys[i]);
+        if (typeof oldRow === "undefined" || oldRow === newRow) {
+            // 追加行、または既に同一オブジェクト（生配列 in-place 変異 + コピー再代入の
+            // イディオム）。後者は従来どおり walkDependency の全行フォールバックが担う。
+            list[i] = newRow;
+            continue;
+        }
+        list[i] = oldRow;
+        matched.push({ position: i, oldRow, newRow });
+    }
+    return matched.length > 0 ? { list, matched } : null;
+}
+/**
+ * 一致行について per-path 書き込みすべきフィールドを列挙する。
+ *
+ * - 変化したフィールドのみ（同値は書かない。無変化リフレッシュを完全なゼロコストに
+ *   するため — 全フィールド無条件書き込みだと §2.2 の利得が消える）
+ * - 新行から消えた旧フィールドは **null** を書く（undefined ではない）
+ *
+ * 同値判定は Object.is。setByAddress の same-value guard と同じ基準にすることで、
+ * 「発行したが guard に落とされる」無駄な書き込みを作らない。
+ *
+ * 消えたフィールドに null を使うのは、この処理系では undefined が
+ * 「状態が値を持たない＝無意見」であり applyChangeToProperty が書き込みごと
+ * スキップするため（明示的なクリアの語彙は null）。undefined を書くと state 側は
+ * 更新されるのに DOM だけ旧値のまま残り、まさに本機能が塞ごうとしている
+ * stale を再導入してしまう。既に null / undefined のフィールドは DOM 上も
+ * 空なので、クリア書き込み自体を発行しない。
+ */
+function collectFieldWrites(oldRow, newRow) {
+    const writes = [];
+    for (const field of Object.keys(newRow)) {
+        if (!Object.is(oldRow[field], newRow[field])) {
+            writes.push({ field, value: newRow[field] });
+        }
+    }
+    for (const field of Object.keys(oldRow)) {
+        if (!Object.hasOwn(newRow, field) && oldRow[field] != null) {
+            writes.push({ field, value: null });
+        }
+    }
+    return writes;
 }
 
 /**
@@ -10100,7 +12215,7 @@ function _walkExpandWildcard(context, currentWildcardIndex, parentListIndex) {
     const parentAbsAddress = createAbsoluteStateAddress(parentAbsPathInfo, parentListIndex);
     const lastValue = getLastListValueByAbsoluteStateAddress(parentAbsAddress);
     const newValue = context.stateProxy[getByAddressSymbol](parentAddress);
-    const listDiff = createListDiff(parentAddress.listIndex, lastValue, newValue);
+    const listDiff = createListDiff(getListParentListIndex(context.stateElement, parentAddress.listIndex), lastValue, newValue);
     const loopIndexes = getIndexes(listDiff, context.searchType);
     if (currentWildcardIndex === context.wildcardPaths.length - 1) {
         context.targetListIndexes.push(...loopIndexes);
@@ -10130,6 +12245,12 @@ function selectExpansionIndexes(context, sourcePath, _lastValue, _newValue, list
     if (listDiff.addIndexSet.size === 0 && listDiff.changeIndexSet.size === 0) {
         // 追加も移動も無い。削除も無ければ「変化が見えない再代入」= リフレッシュ意図
         if (listDiff.deleteIndexSet.size === 0) {
+            // ただしキー突合による値展開が成立した書き込みでは、変化フィールドは
+            // per-path 書き込みで個別に dirty 化済み。全行展開は純粋な無駄になる
+            // （無変化ポーリングをゼロコストにする — 設計書 §2.2）。
+            if (context.keyedMergePath === sourcePath) {
+                return { fullRows: EMPTY_INDEXES, movedRows: null };
+            }
             return { fullRows: listDiff.newIndexes, movedRows: null };
         }
         // 削除のみ: 残存行は位置も値も不変なので展開しない
@@ -10140,13 +12261,22 @@ function selectExpansionIndexes(context, sourcePath, _lastValue, _newValue, list
 const EMPTY_PATH_INFOS = [];
 /**
  * 位置だけが変わった行（movedRows）で展開すべきパス群を求める。
- * `${listPath}.*` の静的 subtree を辿り、$1 等を読んだ実績のある getter
+ * `${listPath}.*` 配下にある、$1 等を読んだ実績のある getter
  * （indexDependentGetterPaths）だけを返す。行の同一性・listIndex は保たれ
  * index 以外の入力が不変なので、index を読まない getter / 値パスは再評価不要。
  * 戻り値:
  * - IPathInfo[]（空可）: この各パスだけを行の listIndex で展開する
  * - null: ネストしたワイルドカード配下に index 依存 getter がある
  *   （listIndex の階数が合わず個別展開できない）→ 呼び出し側で行全体展開に倒す
+ *
+ * 配下判定は staticMap の subtree 走査ではなく indexDependentGetterPaths 側の
+ * プレフィックス照合で行う。静的依存グラフは `State.setPathInfo` が
+ * 「バインドされたパスから親方向へ」張るため、DOM にバインドされていない中間
+ * getter（`.label` だけを描画し `.rank` は `.label` からしか読まれない綴り）は
+ * subtree に現れない。そこを走査すると index 依存 getter を取りこぼし、
+ * 「index を読む getter が subtree に無い＝位置のみ変わった行の値は不変」という
+ * 呼び出し側の判断が偽になって、移動行の getter が古い値のまま残る。
+ * この集合は $1 を読んだ getter の数しか持たないので、走査コストも subtree より小さい。
  */
 function getMovedRowExpansionPaths(context, wildcardPath, depPathInfo) {
     const indexGetters = context.stateElement.indexDependentGetterPaths;
@@ -10154,26 +12284,16 @@ function getMovedRowExpansionPaths(context, wildcardPath, depPathInfo) {
         return EMPTY_PATH_INFOS;
     }
     let result = null;
-    const queue = [wildcardPath];
-    const seen = new Set(queue);
-    for (let i = 0; i < queue.length; i++) {
-        const path = queue[i];
-        if (indexGetters.has(path)) {
-            const pathInfo = getPathInfo(path);
-            if (pathInfo.wildcardCount !== depPathInfo.wildcardCount) {
-                return null;
-            }
-            (result ??= []).push(pathInfo);
-        }
-        const children = context.staticMap.get(path);
-        if (children) {
-            for (const child of children) {
-                if (!seen.has(child)) {
-                    seen.add(child);
-                    queue.push(child);
-                }
-            }
+    const prefix = wildcardPath + DELIMITER;
+    for (const path of indexGetters) {
+        if (path !== wildcardPath && !path.startsWith(prefix)) {
+            continue;
         }
+        const pathInfo = getPathInfo(path);
+        if (pathInfo.wildcardCount !== depPathInfo.wildcardCount) {
+            return null;
+        }
+        (result ??= []).push(pathInfo);
     }
     return result ?? EMPTY_PATH_INFOS;
 }
@@ -10238,7 +12358,7 @@ function _collectDependencies(context, address, nextEntries) {
                 const absPathInfo = getAbsolutePathInfo(context.stateElement, address.pathInfo);
                 const absAddress = createAbsoluteStateAddress(absPathInfo, address.listIndex);
                 const lastValue = getLastListValueByAbsoluteStateAddress(absAddress);
-                const listDiff = createListDiff(address.listIndex, lastValue, newValue);
+                const listDiff = createListDiff(getListParentListIndex(context.stateElement, address.listIndex), lastValue, newValue);
                 const selection = selectExpansionIndexes(context, sourcePath, lastValue, newValue, listDiff);
                 for (const listIndex of selection.fullRows) {
                     const depAddress = createStateAddress(depPathInfo, listIndex);
@@ -10311,7 +12431,7 @@ function _collectDependencies(context, address, nextEntries) {
                         if (address.listIndex === null) {
                             raiseError(`Cannot expand dynamic dependency with wildcard for non-list address: ${address.pathInfo.path}`);
                         }
-                        listIndex = address.listIndex.at(wildcardLen - 1);
+                        listIndex = listIndexAtWildcard(address.listIndex, wildcardLen - 1, address.pathInfo.wildcardCount);
                     }
                     else {
                         // selectedIndex => items.*.selected
@@ -10336,7 +12456,7 @@ function _collectDependencies(context, address, nextEntries) {
                     if (address.listIndex === null) {
                         raiseError(`Cannot expand dynamic dependency with wildcard for non-list address: ${address.pathInfo.path}`);
                     }
-                    const listIndex = address.listIndex.at(wildcardLen - 1);
+                    const listIndex = listIndexAtWildcard(address.listIndex, wildcardLen - 1, address.pathInfo.wildcardCount);
                     listIndexes.push(listIndex);
                 }
             }
@@ -10378,6 +12498,7 @@ function walkDependency(stateName, stateElement, startAddress, staticDependency,
         stateProxy: stateProxy,
         searchType: searchType,
         listExpansion: options?.listExpansion ?? "full",
+        keyedMergePath: options?.keyedMergePath ?? null,
     };
     _walkDependency(context, startAddress, callback);
     return Array.from(context.result);
@@ -10400,11 +12521,26 @@ function walkDependency(stateName, stateElement, startAddress, staticDependency,
  * - finallyで必ず更新情報を登録し、再描画や依存解決に利用
  * - getter/setter経由のスコープ切り替えも考慮した設計
  */
+/**
+ * `$watch` の `prev` 台帳へ旧値を記録する（docs/state-watch-hook-design.md §4-1）。
+ *
+ * same-value guard が既に読んだ旧値だけを使い、watch のための追加読みはしない。
+ * `$watch` 未宣言時のコストは `watchPaths` の null 判定 1 個に収める（§10）。
+ */
+function recordWatchPrevValue(stateElement, path, absAddress, oldValue, hasOldValue) {
+    const watchPaths = stateElement.watchPaths;
+    if (watchPaths == null || !hasOldValue) {
+        return;
+    }
+    if (watchPaths.has(path)) {
+        recordPrevValue(absAddress, oldValue);
+    }
+}
 // Phase 3: 書き込み時点の因果 context を update record に付与する。
 // binding 経由の書き込みは呼び出し元の dynamic scope から context を引き継ぎ、
 // binding 外からの API update は新しい transaction を開始する（設計書 §4 規則 1）。
 // 依存 walk で enqueue される派生アドレスも同じ書き込みの因果に属する。
-function notifyWrite(address, absAddress, receiver, handler) {
+function notifyWrite(address, absAddress, receiver, handler, keyedMergePath) {
     const propagationContext = config.enablePropagationContext
         ? (getCurrentPropagationContext() ?? beginPropagationTransaction(-1))
         : null;
@@ -10423,9 +12559,9 @@ function notifyWrite(address, absAddress, receiver, handler) {
     }, 
     // リスト置換時は追加行・位置変更行のみ展開する（未変更行の再訪を省く。
     // $postUpdate の手動リフレッシュは従来通り全行展開のまま）
-    { listExpansion: "diff" });
+    { listExpansion: "diff", keyedMergePath });
 }
-function _setByAddress(target, address, absAddress, value, receiver, handler) {
+function _setByAddress(target, address, absAddress, value, receiver, handler, keyedMergePath) {
     try {
         if (address.pathInfo.path in target) {
             if (handler.stateElement.setterPaths.has(address.pathInfo.path)) {
@@ -10444,6 +12580,17 @@ function _setByAddress(target, address, absAddress, value, receiver, handler) {
                     handler.popAddress();
                 }
             }
+            else if (handler.stateElement.hasMappedComponentState === true) {
+                // target は innerState proxy。set トラップにはパス文字列しか渡らないので、
+                // 解決済みの listIndex を動的スコープで越境させる（§1.8）
+                pushCrossBoundaryAddress(handler.stateElement, address);
+                try {
+                    return Reflect.set(target, address.pathInfo.path, value);
+                }
+                finally {
+                    popCrossBoundaryAddress();
+                }
+            }
             else {
                 return Reflect.set(target, address.pathInfo.path, value);
             }
@@ -10465,10 +12612,10 @@ function _setByAddress(target, address, absAddress, value, receiver, handler) {
         }
     }
     finally {
-        notifyWrite(address, absAddress, receiver, handler);
+        notifyWrite(address, absAddress, receiver, handler, keyedMergePath);
     }
 }
-function _setByAddressWithSwap(target, address, absAddress, value, receiver, handler) {
+function _setByAddressWithSwap(target, address, absAddress, value, receiver, handler, keyedMergePath) {
     // elementsの場合はswapInfoを準備
     let parentAddress = address.parentAddress ?? raiseError(`address.parentAddress is undefined path: ${address.pathInfo.path}`);
     let swapInfo = getSwapInfoByAddress(parentAddress);
@@ -10481,7 +12628,7 @@ function _setByAddressWithSwap(target, address, absAddress, value, receiver, han
         setSwapInfoByAddress(parentAddress, swapInfo);
     }
     try {
-        return _setByAddress(target, address, absAddress, value, receiver, handler);
+        return _setByAddress(target, address, absAddress, value, receiver, handler, keyedMergePath);
     }
     finally {
         const index = swapInfo.value.indexOf(value);
@@ -10504,7 +12651,80 @@ function _setByAddressWithSwap(target, address, absAddress, value, receiver, han
         }
     }
 }
+/**
+ * `$listKeys` 宣言済みリストパスへの配列代入を「キー一致行のオブジェクト値展開」に
+ * 変換する（docs/state-list-key-design.md §2）。
+ *
+ * 1. キー突合して、一致行は旧オブジェクトを据え置いたハイブリッド配列を作る
+ * 2. ハイブリッド配列を通常の書き込み経路で格納する
+ * 3. createListDiff で listIndex を確定し、変化フィールドだけを per-path 書き込みで発行
+ *
+ * 3 を格納後に行うのが要点。フィールド書き込みは `list.*.field` を親経由で解決する
+ * ため、親（ハイブリッド配列）が既に格納されていなければ正しい行に届かない。
+ * また per-path 書き込みは再び setByAddress に入るので、ネストしたリストパスが
+ * 宣言されていればそのレベルのキー突合が再帰的に走る（§4）。
+ *
+ * 未宣言時のコストは stateElement.listKeys の null 判定 1 回のみ（§7-1）。
+ */
+function setKeyedListByAddress(target, address, merge, oldList, receiver, handler) {
+    const listPath = address.pathInfo.path;
+    // diff の基準は「マージ相手にした配列」= 書き込み直前に格納されていた配列。
+    // 読み手（applyChangeToFor / $getAll / resolve）は現在格納されている配列の
+    // listIndex 台帳（listIndexesByList）へ収束するため、同じ基準で引くことで
+    // 書き込みが dirty 化・キャッシュするアドレスと読み手のアドレスが一致する。
+    // lastValue（最後に *適用* された配列）を基準にすると、for が未マウントで
+    // lastValue が空のときに別台帳を作ってしまい、値は入っているのにワイルドカード
+    // 読みだけ旧値のまま残る（設計書 §8.1）。
+    // 格納より前に引くのは、格納時の walkDependency（listExpansion: "diff"）が
+    // 先にハイブリッド配列の台帳を作ってしまうと、後から上書きした台帳との間で
+    // 同じ分裂が起きるため。先に確定させておけば以降は全経路がこれに合流する。
+    const listParentListIndex = getListParentListIndex(handler.stateElement, address.listIndex);
+    if (getListIndexesByList(oldList) === null) {
+        // 一度も描画されていないリストは台帳自体が無い。先に生やしておかないと
+        // isSameList 経路が空の oldIndexes をそのまま新台帳にしてしまう。
+        createListDiff(listParentListIndex, null, oldList);
+    }
+    const diff = createListDiff(listParentListIndex, oldList, merge.list);
+    const result = setByAddressCore(target, address, merge.list, receiver, handler, listPath);
+    const elementPathInfo = getPathInfo(listPath + DELIMITER + WILDCARD);
+    for (const match of merge.matched) {
+        const fieldWrites = collectFieldWrites(match.oldRow, match.newRow);
+        if (fieldWrites.length === 0) {
+            continue;
+        }
+        // createListDiff の契約上 newIndexes の長さはハイブリッド配列と一致するため
+        // 通常 undefined にはならない。仮に不変条件が破れても、per-path 書き込みを
+        // 諦めるだけで値そのものは行オブジェクトへ反映する（skip すると state だけが
+        // 旧値のまま残り、本機能が塞ごうとしている stale を作ってしまう）。
+        const listIndex = diff.newIndexes[match.position];
+        for (const write of fieldWrites) {
+            if (typeof listIndex === "undefined") {
+                match.oldRow[write.field] = write.value;
+                continue;
+            }
+            const fieldPathInfo = getPathInfo(elementPathInfo.path + DELIMITER + write.field);
+            const fieldAddress = createStateAddress(fieldPathInfo, listIndex);
+            setByAddress(target, fieldAddress, write.value, receiver, handler);
+        }
+    }
+    return result;
+}
 function setByAddress(target, address, value, receiver, handler) {
+    const listKeys = handler.stateElement.listKeys;
+    if (listKeys != null && Array.isArray(value)) {
+        const keySpec = listKeys.get(address.pathInfo.path);
+        if (typeof keySpec !== "undefined") {
+            const oldValue = getByAddress(target, address, receiver, handler);
+            const merge = mergeKeyedList(address.pathInfo.path, keySpec, oldValue, value);
+            if (merge !== null) {
+                // merge が非 null なのは oldValue が非空配列のときだけ（mergeKeyedList 参照）
+                return setKeyedListByAddress(target, address, merge, oldValue, receiver, handler);
+            }
+        }
+    }
+    return setByAddressCore(target, address, value, receiver, handler, null);
+}
+function setByAddressCore(target, address, value, receiver, handler, keyedMergePath) {
     const stateElement = handler.stateElement;
     const path = address.pathInfo.path;
     // occurrence（wc-bindable の `semantics: "event"`）由来の書き込みは、同値でも
@@ -10537,8 +12757,7 @@ function setByAddress(target, address, value, receiver, handler) {
                 devOldValue = oldValue;
                 devHasOldValue = true;
             }
-            const cacheable = address.pathInfo.wildcardCount > 0 ||
-                stateElement.getterPaths.has(path);
+            const cacheable = isCacheable(stateElement, address);
             const absPathInfo = getAbsolutePathInfo(stateElement, address.pathInfo);
             const absAddress = createAbsoluteStateAddress(absPathInfo, address.listIndex);
             if (devtoolsSink !== null) {
@@ -10550,6 +12769,7 @@ function setByAddress(target, address, value, receiver, handler) {
                     hasOldValue: devHasOldValue,
                 });
             }
+            recordWatchPrevValue(stateElement, path, absAddress, devOldValue, devHasOldValue);
             try {
                 if (key === undefined) {
                     raiseError(`address.listIndex?.index is undefined path: ${path}`);
@@ -10557,24 +12777,15 @@ function setByAddress(target, address, value, receiver, handler) {
                 return Reflect.set(parentValue, key, value);
             }
             finally {
-                notifyWrite(address, absAddress, receiver, handler);
+                notifyWrite(address, absAddress, receiver, handler, keyedMergePath);
                 if (cacheable) {
                     setCacheEntryByAbsoluteStateAddress(absAddress, {
                         value: value,
                         dirty: false
                     });
                 }
-                // DCC bindable イベントディスパッチ
-                const eventName = stateElement.bindableEventMap[path];
-                if (eventName) {
-                    const rootNode = stateElement.rootNode;
-                    if (rootNode instanceof ShadowRoot) {
-                        rootNode.host.dispatchEvent(new CustomEvent(eventName, {
-                            detail: value,
-                            bubbles: true,
-                        }));
-                    }
-                }
+                // DCC bindable イベントディスパッチ（完全一致 ＋ サブパス → 先頭セグメント、§2.1）
+                dispatchBindableEvent(stateElement, address.pathInfo, { value });
             }
         }
     }
@@ -10597,8 +12808,7 @@ function setByAddress(target, address, value, receiver, handler) {
     }
     // --- end same-value guard ---
     const isSwappable = stateElement.elementPaths.has(address.pathInfo.path);
-    const cacheable = address.pathInfo.wildcardCount > 0 ||
-        stateElement.getterPaths.has(address.pathInfo.path);
+    const cacheable = isCacheable(stateElement, address);
     const absPathInfo = getAbsolutePathInfo(stateElement, address.pathInfo);
     const absAddress = createAbsoluteStateAddress(absPathInfo, address.listIndex);
     if (devtoolsSink !== null) {
@@ -10610,12 +12820,13 @@ function setByAddress(target, address, value, receiver, handler) {
             hasOldValue: devHasOldValue,
         });
     }
+    recordWatchPrevValue(stateElement, path, absAddress, devOldValue, devHasOldValue);
     try {
         if (isSwappable) {
-            return _setByAddressWithSwap(target, address, absAddress, value, receiver, handler);
+            return _setByAddressWithSwap(target, address, absAddress, value, receiver, handler, keyedMergePath);
         }
         else {
-            return _setByAddress(target, address, absAddress, value, receiver, handler);
+            return _setByAddress(target, address, absAddress, value, receiver, handler, keyedMergePath);
         }
     }
     finally {
@@ -10625,17 +12836,8 @@ function setByAddress(target, address, value, receiver, handler) {
                 dirty: false
             });
         }
-        // DCC bindable イベントディスパッチ
-        const eventName = stateElement.bindableEventMap[address.pathInfo.path];
-        if (eventName) {
-            const rootNode = stateElement.rootNode;
-            if (rootNode instanceof ShadowRoot) {
-                rootNode.host.dispatchEvent(new CustomEvent(eventName, {
-                    detail: value,
-                    bubbles: true,
-                }));
-            }
-        }
+        // DCC bindable イベントディスパッチ（完全一致 ＋ サブパス → 先頭セグメント、§2.1）
+        dispatchBindableEvent(stateElement, address.pathInfo, { value });
     }
 }
 
@@ -10683,8 +12885,10 @@ function resolve(target, _prop, receiver, handler) {
                 raiseError(`ListIndexes not found: ${wildcardParentPathInfo.path}`);
             }
             const index = indexes[i];
+            // 範囲外 index はリスト自体の不在と別原因なので index を含める
+            // （docs/state-bind-component-nested-for-design.md §8.4）
             listIndex = listIndexes[index] ??
-                raiseError(`ListIndex not found: ${wildcardParentPathInfo.path}`);
+                raiseError(`ListIndex not found at index ${index} of ${wildcardParentPathInfo.path}`);
         }
         // ToDo:WritableかReadonlyかを判定して適切なメソッドを呼び出す
         const address = createStateAddress(pathInfo, listIndex);
@@ -10726,7 +12930,7 @@ function getAll(target, prop, receiver, handler) {
                 const wildcardPattern = pathInfo.wildcardParentPathInfos[i];
                 const listIndex = getContextListIndex(handler, wildcardPattern.path);
                 if (listIndex) {
-                    indexes = listIndex.indexes;
+                    indexes = getScopedIndexes(listIndex, listIndex.length - getBaseDepth(handler.stateElement));
                     break;
                 }
             }
@@ -10743,7 +12947,7 @@ function getAll(target, prop, receiver, handler) {
             const wildcardAddress = createStateAddress(wildcardParentPathInfo, listIndex);
             const oldValue = lastValueByListAddress.get(wildcardAddress);
             const newValue = getByAddress(target, wildcardAddress, receiver, handler);
-            const listDiff = createListDiff(listIndex, oldValue, newValue);
+            const listDiff = createListDiff(getListParentListIndex(handler.stateElement, listIndex), oldValue, newValue);
             const listIndexes = listDiff.newIndexes;
             const index = indexes[indexPos] ?? null;
             newValueByAddress.set(wildcardAddress, newValue);
@@ -10754,8 +12958,10 @@ function getAll(target, prop, receiver, handler) {
                 }
             }
             else {
+                // 範囲外 index はリスト自体の不在と別原因なので index を含める
+                // （docs/state-bind-component-nested-for-design.md §8.4）
                 const listIndex = listIndexes[index] ??
-                    raiseError(`ListIndex not found: ${wildcardParentPathInfo.path}`);
+                    raiseError(`ListIndex not found at index ${index} of ${wildcardParentPathInfo.path}`);
                 if ((wildcardIndexPos + 1) < wildcardParentPathInfos.length) {
                     walkWildcardPattern(wildcardParentPathInfos, wildcardIndexPos + 1, listIndex, indexes, indexPos + 1, parentIndexes.concat(listIndex.index), results);
                 }
@@ -10817,8 +13023,11 @@ function getListIndex(target, resolvedAddress, receiver, handler) {
                     raiseError(`ListIndex not found: ${wildcardParentPathInfo.path}`);
                 const wildcardIndex = resolvedAddress.wildcardIndexes[i] ??
                     raiseError(`wildcardIndex is null: ${resolvedAddress.pathInfo.path}`);
+                // 範囲外 index はリスト自体の不在と別原因なので、メッセージに index を含める。
+                // 親パスだけを名指しすると「リスト自体が見つからない」と誤読させる
+                // （docs/state-bind-component-nested-for-design.md §8.4）。
                 parentListIndex = wildcardParentListIndexes[wildcardIndex] ??
-                    raiseError(`ListIndex not found: ${wildcardParentPathInfo.path}`);
+                    raiseError(`ListIndex not found at index ${wildcardIndex} of ${wildcardParentPathInfo.path}`);
             }
             return parentListIndex;
         }
@@ -10847,6 +13056,10 @@ function postUpdate(target, _prop, receiver, handler) {
             // 更新対象として登録
             updater.enqueueAbsoluteAddress(absDepAddress);
         });
+        // DCC bindable イベントディスパッチ。$postUpdate は in-place 変異を通知する正規の idiom で、
+        // set トラップを通らない変更が観測面に出る唯一の経路なので、ここでも撃つ
+        // （docs/architecture-hardening/15-state-component-mechanism-consistency.md §2.1）。
+        dispatchBindableEvent(stateElement, address.pathInfo);
     };
 }
 
@@ -10951,7 +13164,7 @@ function updatedCallback(target, refs, receiver, handler) {
             }
             paths.add(pathName);
             if (pathInfo.wildcardCount > 0) {
-                const indexes = ref.listIndex.indexes ?? [];
+                const indexes = getScopedIndexes(ref.listIndex, pathInfo.wildcardCount);
                 const indexesList = indexesListByPath[pathName];
                 if (typeof indexesList === "undefined") {
                     indexesListByPath[pathName] = [indexes];
@@ -11068,7 +13281,13 @@ function get(target, prop, receiver, handler) {
             handler.stateElement.addIndexDependentGetterPath?.(lastInfo.path);
         }
         const listIndex = lastAddress?.listIndex;
-        return listIndex?.indexes[index] ?? raiseError(`ListIndex not found: ${prop.toString()}`);
+        if (typeof listIndex === "undefined" || listIndex === null) {
+            raiseError(`ListIndex not found: ${prop.toString()}`);
+        }
+        // `$1` は「このスコープの」1 段目。base 深さ Δ を持つ子スコープでも
+        // 番号がずれないよう末尾から数える（list/wildcardLevel.ts）
+        const indexListIndex = listIndexAtWildcard(listIndex, index, lastAddress.pathInfo.wildcardCount);
+        return indexListIndex?.index ?? raiseError(`ListIndex not found: ${prop.toString()}`);
     }
     if (typeof prop === "string") {
         if (prop[0] === '$') {
@@ -11305,138 +13524,6 @@ function createStateProxy(rootNode, state, stateName, mutability) {
     return stateProxy;
 }
 
-// WebComponent専用のキャッシュ
-// outerState.tsからのアクセスで、これを返す
-const lastValueByAbsoluteStateAddress = new WeakMap();
-function setLastValueByAbsoluteStateAddress(absoluteStateAddress, value) {
-    lastValueByAbsoluteStateAddress.set(absoluteStateAddress, value);
-}
-function getLastValueByAbsoluteStateAddress(absoluteStateAddress) {
-    return lastValueByAbsoluteStateAddress.get(absoluteStateAddress);
-}
-
-const stateElementByWebComponent = new WeakMap();
-function setStateElementByWebComponent(webComponent, stateName, stateElement) {
-    let stateMap = stateElementByWebComponent.get(webComponent);
-    if (!stateMap) {
-        stateMap = new Map();
-        stateElementByWebComponent.set(webComponent, stateMap);
-    }
-    stateMap.set(stateName, stateElement);
-}
-function getStateElementByWebComponent(webComponent, stateName) {
-    const stateMap = stateElementByWebComponent.get(webComponent);
-    if (!stateMap) {
-        return null;
-    }
-    return stateMap.get(stateName) ?? null;
-}
-
-const innerMappingByElement = new WeakMap();
-const outerMappingByElement = new WeakMap();
-const primaryMappingRuleSetByElement = new WeakMap();
-const primaryBindingByMappingRule = new WeakMap();
-function createMappingRuleByBinding(innerState, binding) {
-    const innerPathInfo = getPathInfo(binding.propSegments.slice(1).join(DELIMITER));
-    const innerAbsPathInfo = getAbsolutePathInfo(innerState, innerPathInfo);
-    const outerAbsStateAddress = getAbsoluteStateAddressByBinding(binding);
-    const outerAbsPathInfo = outerAbsStateAddress.absolutePathInfo;
-    return { innerAbsPathInfo, outerAbsPathInfo };
-}
-function buildPrimaryMappingRule(webComponent, stateName, bindings) {
-    if (bindings.length === 0) {
-        return;
-    }
-    const innerState = getStateElementByWebComponent(webComponent, stateName);
-    if (innerState === null) {
-        raiseError('State element not found for web component.');
-    }
-    const innerMappingRule = new Map();
-    const outerMappingRule = new Map();
-    for (const binding of bindings) {
-        const mappingRule = createMappingRuleByBinding(innerState, binding);
-        let primaryMappingRuleSet = primaryMappingRuleSetByElement.get(webComponent);
-        if (typeof primaryMappingRuleSet === 'undefined') {
-            primaryMappingRuleSetByElement.set(webComponent, new Set([mappingRule]));
-        }
-        else {
-            primaryMappingRuleSet.add(mappingRule);
-        }
-        const innerAbsPathInfo = mappingRule.innerAbsPathInfo;
-        const outerAbsPathInfo = mappingRule.outerAbsPathInfo;
-        primaryBindingByMappingRule.set(mappingRule, binding);
-        innerMappingRule.set(innerAbsPathInfo, outerAbsPathInfo);
-        outerMappingRule.set(outerAbsPathInfo, innerAbsPathInfo);
-    }
-    innerMappingByElement.set(webComponent, innerMappingRule);
-    outerMappingByElement.set(webComponent, outerMappingRule);
-}
-function getOuterAbsolutePathInfo(webComponent, innerAbsPathInfo) {
-    let innerMapping = innerMappingByElement.get(webComponent);
-    if (typeof innerMapping === 'undefined') {
-        innerMapping = new Map();
-        innerMappingByElement.set(webComponent, innerMapping);
-    }
-    if (innerMapping.has(innerAbsPathInfo)) {
-        return innerMapping.get(innerAbsPathInfo);
-    }
-    let outerMapping = outerMappingByElement.get(webComponent);
-    if (typeof outerMapping === 'undefined') {
-        outerMapping = new Map();
-        outerMappingByElement.set(webComponent, outerMapping);
-    }
-    // 内側からのアクセスの場合、ルールがなければプライマリルールから新たにルールとバインディングを生成する
-    const primaryMappingRuleSet = primaryMappingRuleSetByElement.get(webComponent);
-    if (typeof primaryMappingRuleSet === 'undefined') {
-        // マッピングルールが存在しない場合はnullを返し、ローカル状態へのフォールバックを許可する
-        return null;
-    }
-    let primaryMappingRule = null;
-    for (const currentPrimaryMappingRule of primaryMappingRuleSet) {
-        // innerPathInfoがprimaryMappingRuleのinnerPathInfoを包含しているか
-        if (!innerAbsPathInfo.pathInfo.cumulativePathInfoSet.has(currentPrimaryMappingRule.innerAbsPathInfo.pathInfo)) {
-            continue;
-        }
-        if (currentPrimaryMappingRule.innerAbsPathInfo.pathInfo.segments.length === innerAbsPathInfo.pathInfo.segments.length) {
-            raiseError('Duplicate mapping rule for web component.');
-        }
-        primaryMappingRule = currentPrimaryMappingRule;
-        break;
-    }
-    if (primaryMappingRule === null) {
-        // マッピングルールに一致しない場合はnullを返し、ローカル状態へのフォールバックを許可する
-        return null;
-    }
-    // マッチした残りのパスをouterPathInfoに付与して新たなルールを生成
-    const primaryBinding = primaryBindingByMappingRule.get(primaryMappingRule);
-    /* c8 ignore start */
-    if (typeof primaryBinding === 'undefined') {
-        raiseError('Binding not found for primary mapping rule on web component.');
-    }
-    /* c8 ignore stop */
-    const outerRemainingSegments = innerAbsPathInfo.pathInfo.segments.slice(primaryMappingRule.innerAbsPathInfo.pathInfo.segments.length);
-    const outerSegments = primaryMappingRule.outerAbsPathInfo.pathInfo.segments.concat(outerRemainingSegments);
-    const outerPathInfo = getPathInfo(outerSegments.join(DELIMITER));
-    const rootNode = webComponent.getRootNode();
-    const outerStateElement = getStateElementByName(rootNode, primaryBinding.stateName);
-    if (outerStateElement === null) {
-        raiseError(`State element with name "${primaryBinding.stateName}" not found for web component.`);
-    }
-    const outerAbsPathInfo = getAbsolutePathInfo(outerStateElement, outerPathInfo);
-    innerMapping.set(innerAbsPathInfo, outerAbsPathInfo);
-    outerMapping.set(outerAbsPathInfo, innerAbsPathInfo);
-    // ルールに対応するバインディングを生成
-    const newBinding = {
-        ...primaryBinding,
-        propName: innerAbsPathInfo.pathInfo.path,
-        propSegments: innerAbsPathInfo.pathInfo.segments,
-        statePathName: outerAbsPathInfo.pathInfo.path,
-        statePathInfo: outerAbsPathInfo.pathInfo,
-    };
-    addBindingByNode(webComponent, newBinding);
-    return outerAbsPathInfo;
-}
-
 function cloneWithDescriptors(obj) {
     const proto = Object.getPrototypeOf(obj);
     const clone = Object.create(proto);
@@ -11461,6 +13548,44 @@ class InnerStateProxyHandler {
         this._webComponent = webComponent;
         this._innerStateElement = getStateElementByWebComponent(webComponent, stateName) ?? raiseError('State element not found for web component.');
     }
+    /**
+     * 親スコープで読み書きするときのループ文脈を決める。候補は 2 つある。
+     *
+     * 1. **越境直前のアドレスの listIndex**。子スコープの `for` が回している行
+     *    （§1.8）。子の listIndex は base（＝ホストの親スコープ行）を親に持つので
+     *    チェーン長は Δ+W_inner ＝ W_outer になり、そのまま外側の文脈として使える
+     *    （docs/state-bind-component-nested-for-design.md）。
+     * 2. **コンポーネント要素のノードループ文脈**。コンポーネント自身が親の `for` の
+     *    中にいるが、読んでいるパスは子スコープのループの外という形（`state.row: rows.*`）。
+     *
+     * 1 を先に見るのは、内側ほど具体的だから。入れ子形では 2 も非 null（＝Δ 段だけ）に
+     * なるが、それでは外側パスの段数に足りない。段数が一致する候補だけを採るのが
+     * 判定の本体で、両方外れたら null（親側の解決に委ね、解けなければ raiseError。
+     * 無言の取り違えを作らない）。
+     */
+    _outerLoopContext(innerPathInfo, outerAbsPathInfo) {
+        const outerWildcardCount = outerAbsPathInfo.pathInfo.wildcardCount;
+        // 段数の照合は外側スコープの**実 arity**（パスの段数 + そのスコープの Δ）で行う。
+        // 境界 1 枚なら外側は Δ=0 で従来と同値、2 枚以上あるときに中間スコープの Δ を
+        // 数えないと候補が両方とも外れて loopContext が null になる（§1.12）。
+        // 添字（wildcardPaths）に使うのは Δ を含まない段数のままであることに注意。
+        const outerArity = getScopeArity(outerAbsPathInfo.stateElement, outerAbsPathInfo.pathInfo);
+        const nodeLoopContext = getLoopContextByNode(this._webComponent);
+        if (nodeLoopContext !== null && nodeLoopContext.listIndex.length === outerArity) {
+            return nodeLoopContext;
+        }
+        if (outerWildcardCount > 0) {
+            const address = getCrossBoundaryAddress(this._innerStateElement, innerPathInfo.path);
+            const listIndex = address?.listIndex ?? null;
+            if (listIndex !== null && listIndex.length === outerArity) {
+                const outerWildcardPath = outerAbsPathInfo.pathInfo.wildcardPaths[outerWildcardCount - 1];
+                return createStateAddress(getPathInfo(outerWildcardPath), listIndex);
+            }
+        }
+        // どちらも段数が合わない。従来どおりノードの文脈へフォールバックし、
+        // 解けなければ後段が raiseError する（無言の取り違えを作らない）
+        return nodeLoopContext;
+    }
     get(target, prop, receiver) {
         if (typeof prop === 'string') {
             if (prop === "then") {
@@ -11479,21 +13604,11 @@ class InnerStateProxyHandler {
             const innerAbsPathInfo = getAbsolutePathInfo(this._innerStateElement, innerPathInfo);
             const outerAbsPathInfo = getOuterAbsolutePathInfo(this._webComponent, innerAbsPathInfo);
             if (outerAbsPathInfo !== null) {
-                const loopContext = getLoopContextByNode(this._webComponent);
+                const loopContext = this._outerLoopContext(innerPathInfo, outerAbsPathInfo);
                 let value = undefined;
                 outerAbsPathInfo.stateElement.createState("readonly", (state) => {
                     state[setLoopContextSymbol](loopContext, () => {
                         value = state[outerAbsPathInfo.pathInfo.path];
-                        let listIndex = null;
-                        if (loopContext !== null && loopContext.listIndex !== null) {
-                            if (outerAbsPathInfo.pathInfo.wildcardCount > 0) {
-                                // wildcardPathSetとloopContextのpathInfoSetのintersectionのうち、segment数が最も多いものをouterAbsPathInfoにする
-                                // 例: outerPathInfoが "todos.*.name"で、loopContextのpathInfoSetに "todos.0.name", "todos.1.name"がある場合、"todos.0.name"や"todos.1.name"をouterAbsPathInfoにする
-                                listIndex = loopContext.listIndex.at(outerAbsPathInfo.pathInfo.wildcardCount - 1);
-                            }
-                        }
-                        const absStateAddress = createAbsoluteStateAddress(outerAbsPathInfo, listIndex);
-                        setLastValueByAbsoluteStateAddress(absStateAddress, value);
                     });
                 });
                 return value;
@@ -11520,7 +13635,7 @@ class InnerStateProxyHandler {
             const innerAbsPathInfo = getAbsolutePathInfo(this._innerStateElement, innerPathInfo);
             const outerAbsPathInfo = getOuterAbsolutePathInfo(this._webComponent, innerAbsPathInfo);
             if (outerAbsPathInfo !== null) {
-                const loopContext = getLoopContextByNode(this._webComponent);
+                const loopContext = this._outerLoopContext(innerPathInfo, outerAbsPathInfo);
                 outerAbsPathInfo.stateElement.createState("writable", (state) => {
                     state[setLoopContextSymbol](loopContext, () => {
                         state[outerAbsPathInfo.pathInfo.path] = value;
@@ -11588,42 +13703,24 @@ function createInnerState(webComponent, stateName) {
     return new Proxy(meltFrozenObject(state), handler);
 }
 
+/**
+ * コンポーネントの `bind-component` プロパティとして露出する proxy。
+ * read / write とも子の state proxy へ素通しする。
+ *
+ * mapped（親から `<prop>.*` をバインドされている）ケースでは、素通し先の
+ * innerState proxy がマッピング規則に従って親 state へ解決するので、
+ * `this.state.msg` の読みは親の現在値になり、書きは親 state へ届く。
+ * plain（親からのバインドなし）ケースでは子のローカル state に解決する。
+ * **どちらでも同じ意味論になる**のが要点
+ * （docs/architecture-hardening/15-state-component-mechanism-consistency.md §1.1 / G1）。
+ *
+ * 以前は mapped 専用に「read = 最後に観測した値のキャッシュ／write = 値を捨てて
+ * `$postUpdate` 通知のみ」という別 proxy を当てていた。あれは親 → 子の再読込通知という
+ * **内部チャネル**としては正しかったが、それが公開 API を兼ねていたため、同じ
+ * コンポーネント実装が親ページの書き方で挙動を変えていた。内部チャネルは
+ * `applyChangeToWebComponent` が state element を直接引く形へ分離した。
+ */
 class OuterStateProxyHandler {
-    _innerStateElement;
-    constructor(webComponent, stateName) {
-        this._innerStateElement = getStateElementByWebComponent(webComponent, stateName) ?? raiseError('State element not found for web component.');
-    }
-    get(target, prop, receiver) {
-        if (typeof prop === 'string') {
-            const innerPathInfo = getPathInfo(prop);
-            const innerAbsPathInfo = getAbsolutePathInfo(this._innerStateElement, innerPathInfo);
-            const absStateAddress = createAbsoluteStateAddress(innerAbsPathInfo, null);
-            return getLastValueByAbsoluteStateAddress(absStateAddress);
-        }
-        else {
-            return Reflect.get(target, prop, receiver);
-        }
-    }
-    set(target, prop, value, receiver) {
-        if (typeof prop === 'string') {
-            const innerPathInfo = getPathInfo(prop);
-            const innerAbsPathInfo = getAbsolutePathInfo(this._innerStateElement, innerPathInfo);
-            this._innerStateElement.createState("readonly", (state) => {
-                state.$postUpdate(innerAbsPathInfo.pathInfo.path);
-            });
-            return true;
-        }
-        else {
-            return Reflect.set(target, prop, value, receiver);
-        }
-    }
-}
-function createOuterState(webComponent, stateName) {
-    const handler = new OuterStateProxyHandler(webComponent, stateName);
-    return new Proxy({}, handler);
-}
-
-class PlainOuterStateProxyHandler {
     _innerStateElement;
     constructor(webComponent, stateName) {
         this._innerStateElement = getStateElementByWebComponent(webComponent, stateName) ?? raiseError('State element not found for web component.');
@@ -11652,36 +13749,44 @@ class PlainOuterStateProxyHandler {
         }
     }
 }
-function createPlainOuterState(webComponent, stateName) {
-    const handler = new PlainOuterStateProxyHandler(webComponent, stateName);
+function createOuterState(webComponent, stateName) {
+    const handler = new OuterStateProxyHandler(webComponent, stateName);
     return new Proxy({}, handler);
 }
 
 const getOuter = (outerState) => () => outerState;
 function bindWebComponent(innerStateElement, component, stateProp, state) {
     setStateElementByWebComponent(component, stateProp, innerStateElement);
-    if (component.hasAttribute(config.bindAttributeName)) {
-        const bindings = (getBindingsByNode(component) ?? []).filter(binding => binding.propSegments[0] === stateProp);
+    // 分岐は「data-wcs 属性の有無」ではなく「<stateProp>.* バインドが 1 件以上あるか」で決める。
+    // 属性はあってもマッピング対象が 0 件（例: data-wcs="class.on: flag" だけ）の場合、
+    // buildPrimaryMappingRule は primaryMappingRule を 1 件も作らないまま return するため、
+    // outerState の lastValue / $postUpdate 意味論だけが残る。その状態では
+    // component[stateProp] の read が常に undefined・write が完全な no-op になる
+    // （docs/architecture-hardening/15-state-component-mechanism-consistency.md §1.2）。
+    const bindings = component.hasAttribute(config.bindAttributeName)
+        ? (getBindingsByNode(component) ?? []).filter(binding => binding.propSegments[0] === stateProp)
+        : [];
+    // 分岐が決めるのは「子の state の中身」だけ。mapped なら親 state へ解決する
+    // innerState proxy、plain なら melt 済みのローカル state。
+    if (bindings.length > 0) {
         buildPrimaryMappingRule(component, stateProp, bindings);
-        const outerState = createOuterState(component, stateProp);
-        const innerState = createInnerState(component, stateProp);
-        innerStateElement.setInitialState(innerState);
-        Object.defineProperty(component, stateProp, {
-            get: getOuter(outerState),
-            enumerable: true,
-            configurable: true,
-        });
+        // 値の正本が親スコープにあることを state 要素に記録する。越境アドレスの受け渡しと
+        // リストパスの外向き伝播はこのフラグでのみ有効になる（§1.8）。
+        innerStateElement.markComponentStateMapped?.();
+        innerStateElement.setInitialState(createInnerState(component, stateProp));
     }
     else {
         innerStateElement.setInitialState(meltFrozenObject(state));
-        const outerState = createPlainOuterState(component, stateProp);
-        Object.defineProperty(component, stateProp, {
-            get: getOuter(outerState),
-            enumerable: true,
-            configurable: true,
-        });
     }
-    markWebComponentAsComplete(component, innerStateElement);
+    // 外向きに露出する proxy は両者で同一。mapped でも read はライブ・write は
+    // innerState 経由で親 state に届く（§1.1 / G1）。
+    const outerState = createOuterState(component, stateProp);
+    Object.defineProperty(component, stateProp, {
+        get: getOuter(outerState),
+        enumerable: true,
+        configurable: true,
+    });
+    markWebComponentAsComplete(component, stateProp);
     if (WEBCOMPONENT_STATE_READY_CALLBACK_NAME in component) {
         const func = component[WEBCOMPONENT_STATE_READY_CALLBACK_NAME];
         if (typeof func === 'function') {
@@ -11695,15 +13800,6 @@ function bindWebComponent(innerStateElement, component, stateProp, state) {
     }
 }
 
-function getAllPropertyDescriptors(obj) {
-    let descriptors = {};
-    let proto = obj;
-    while (proto && proto !== Object.prototype) {
-        Object.assign(descriptors, Object.getOwnPropertyDescriptors(proto));
-        proto = Object.getPrototypeOf(proto);
-    }
-    return descriptors;
-}
 function getStateInfo(state) {
     const getterPaths = new Set();
     const setterPaths = new Set();
@@ -11739,22 +13835,27 @@ class State extends HTMLElementBase {
     _resolveInitialize = null;
     _connectedCallbackPromise;
     _resolveConnectedCallback = null;
+    _rejectConnectedCallback = null;
     _loadingPromise;
     _resolveLoading = null;
     _setStatePromise = null;
     _resolveSetState = null;
     _listPaths = new Set();
+    _listKeys = null;
     _elementPaths = new Set();
     _getterPaths = new Set();
     _setterPaths = new Set();
-    _loopContextStack = createLoopContextStack();
+    _loopContextStack = createLoopContextStack(() => getBaseDepth(this));
     _dynamicDependency = new Map();
     _staticDependency = new Map();
     _pathSet = new Set();
+    // `$watch` 宣言の監視対象パス。宣言が無ければ null（setByAddress のゼロコスト契約）
+    _watchPaths = null;
     _version = 0;
     _rootNode = null;
     _boundComponent = null;
     _boundComponentStateProp = null;
+    _hasMappedComponentState = false;
     _bindableEventMap = {};
     _commandTokenNames = new Set();
     _eventTokenNames = new Set();
@@ -11774,8 +13875,9 @@ class State extends HTMLElementBase {
         this._initializePromise = new Promise((resolve) => {
             this._resolveInitialize = resolve;
         });
-        this._connectedCallbackPromise = new Promise((resolve) => {
+        this._connectedCallbackPromise = new Promise((resolve, reject) => {
             this._resolveConnectedCallback = resolve;
+            this._rejectConnectedCallback = reject;
         });
         this._loadingPromise = new Promise((resolve) => {
             this._resolveLoading = resolve;
@@ -11825,10 +13927,24 @@ class State extends HTMLElementBase {
         clearStreamNamespace(this);
         clearStreamRegistry(this);
         processStreamsDeclaration(this, value);
+        // $listKeys: 宣言が無ければ null のままで、setByAddress のキー突合経路には
+        // 一切入らない（docs/state-list-key-design.md §7-1）。再 set で必ず置き換える。
+        this._listKeys = processListKeysDeclaration(value);
+        // $watch: 旧宣言のハンドラが残らないよう registry を落としてから新宣言を解析する。
+        // _pathSet.clear() の後であること（依存グラフ登録をやり直す必要がある、
+        // docs/state-watch-hook-design.md §8）。宣言が無ければ watchPaths は null で、
+        // setByAddress の旧値キャプチャには一切入らない（§10 のゼロコスト契約）。
+        clearWatchRegistry(this);
+        // computed の前回評価値も宣言と寿命を共にする（旧宣言の値を新しい watch の
+        // prev として渡さない）。切断では消さない — 再接続の初回評価が上書きする。
+        clearComputedSnapshots(this);
+        this._watchPaths = processWatchDeclaration(this, value);
         // 接続中の再 set（S13）は新宣言で即再起動する。
         // 初回（_initialize 中）は _initialized が false なのでここでは起動されず、
         // connectedCallback 側の startStreams（$connectedCallback 完了後）が担う。
         if (this._initialized && this._rootNode !== null && !inSsr()) {
+            // watch は stream より先に有効化する（stream の起動時書き込みを観測できるように）
+            startWatch(this);
             startStreams(this);
             // $connectedCallback 実行中の再 set（setInitialState）では、ここで新宣言が
             // 起動済みのため connectedCallback 末尾の startStreams を skip させる。
@@ -11935,6 +14051,19 @@ class State extends HTMLElementBase {
             if (!(parentNode instanceof ShadowRoot) && !this.hasAttribute("name")) {
                 raiseError(`"bind-component" in Light DOM requires a "name" attribute to avoid namespace conflicts with the parent scope.`);
             }
+            // bind-component はコンポーネント側の state プロパティを唯一のソースにする。
+            // state / src / json / inner <script> と併記すると、この後の _initialize が
+            // そちらを採用して _setStatePromise を await しないため、bindWebComponent が
+            // setInitialState で渡した innerState proxy ごと捨てられ、親↔子マッピングが
+            // 無言で死ぬ。併記は必ず設定ミスなので fail-fast させる
+            // （docs/architecture-hardening/15-state-component-mechanism-consistency.md §2.6）。
+            const conflicting = ["state", "src", "json"].filter((name) => this.hasAttribute(name));
+            if (this.querySelector('script[type="module"]') !== null) {
+                conflicting.push('<script type="module">');
+            }
+            if (conflicting.length > 0) {
+                raiseError(`"bind-component" cannot be combined with ${conflicting.join(", ")}. The component's "${this.getAttribute("bind-component")}" property is the only state source.`);
+            }
             const boundComponentStateProp = this.getAttribute("bind-component");
             await customElements.whenDefined(customTagName.toLowerCase());
             // data-wcs属性がある場合は、上位の状態によりbinding情報の設定が完了するまで待機する
@@ -11953,6 +14082,64 @@ class State extends HTMLElementBase {
             bindWebComponent(this, this._boundComponent, this._boundComponentStateProp, state);
         }
     }
+    /**
+     * Light DOM の mapped コンポーネントが、自分のサブツリーのバインディングを張る（§1.13）。
+     *
+     * Shadow DOM 形では子スコープが別 rootNode にあり、`setStateElementByName` の初回登録から
+     * その root ぶんの `buildBindings` が別パスとして起動する。Light DOM ではホストと同じ root に
+     * いるためそのパスが存在せず、かといってホストのパスに混ぜると `@name` の解決が
+     * この要素の名前登録より先に来てしまう。そこで `getSubscriberNodes` がホスト側の走査から
+     * このサブツリーを外し、名前登録が済んだここで同じことを自前で行う。
+     *
+     * `{{ }}` の変換だけはホストのパスが root 全体に対して済ませている（純粋にテキスト操作で
+     * state に依存しないため）。構造フラグメントの収集は fragment info を rootNode + state 名で
+     * 登録するので state 依存であり、ホストのパスからは外してここで走らせる。
+     *
+     * ループ文脈を null で渡すのは Shadow DOM 形（`initializeBindings(shadowRoot, null)`）と
+     * 揃えるため —— 子孫の `getLoopContextByNode` はコンポーネント要素まで遡って
+     * 親スコープの行を見つける。
+     */
+    _initializeLightDomComponentScope() {
+        const component = this._boundComponent;
+        if (component === null || this.parentNode !== component) {
+            // Shadow DOM 形（parentNode が ShadowRoot）は対象外
+            return;
+        }
+        if (!component.hasAttribute(config.bindAttributeName)) {
+            // plain 形はホストのパスに含まれたままなので、ここで張ると二重になる
+            return;
+        }
+        collectStructuralFragments(this._rootNode, component);
+        initializeBindings(component, null);
+    }
+    /**
+     * mapped な `bind-component` が切断 → 再接続したときに、束ねているパスを読み直させる（§1.9）。
+     *
+     * リスト行の content は再利用されるので、行が作り直されると子はこの経路を通る
+     * （`_initialized` が真なので `_initializeBindWebComponent` / `_initialize` は走らず、
+     * 子のバインディングは張り直されない）。切断中に親で起きた変更の通知は
+     * `applyChangeToWebComponent` が切断済みを理由に落としているため、ここで読み直さないと
+     * 子のビューだけが古い値のまま取り残される。何が変わったかは分からないので、
+     * プライマリ規則の粒度で丸ごと読み直す。
+     *
+     * 読み直しの前に派生規則の memo を捨てる。派生規則の購読者（親スコープに立つ
+     * バインディング）は切断で teardown されており、memo が残っていると導出が二度と
+     * 走らないため購読者も張り直されない ＝ 以後この子だけがサブパスの書き込みを
+     * 受け取れなくなる。捨てておけば、直後の読み直しで導出と購読者登録が走る。
+     */
+    _reloadMappedPathsAfterReconnect() {
+        if (!this._hasMappedComponentState || this._boundComponent === null) {
+            return;
+        }
+        // mapped ＝ プライマリ規則が 1 件以上あることと同義（bindWebComponent の分岐）
+        const innerPaths = getPrimaryInnerPaths(this._boundComponent);
+        resetDerivedMappingRules(this._boundComponent);
+        this.createState("readonly", (state) => {
+            for (const path of innerPaths) {
+                state.$postUpdate(path);
+            }
+        });
+    }
     async _callStateConnectedCallback() {
         await this.createStateAsync("writable", async (state) => {
             // stateに"$connectedCallback"があるか確認し、connectedCallbackAPIを呼び出す
@@ -12013,12 +14200,22 @@ class State extends HTMLElementBase {
             const parentNode = this.parentNode;
             if (parentNode instanceof ShadowRoot &&
                 parentNode.host.hasAttribute(DCC_DEFINITION_ATTRIBUTE)) {
+                // DCC と bind-component は排他。DCC の state はテンプレートに属し、
+                // インスタンスごとにロードされるので、定義時点のホストのプロパティを
+                // ソースにする bind-component とは両立しない。従来はこの return で
+                // 無言に無視していた（docs/architecture-hardening/15 §3.1）。
+                if (this.hasAttribute("bind-component")) {
+                    raiseError(`"bind-component" cannot be used inside a [${DCC_DEFINITION_ATTRIBUTE}] host. DCC state comes from the template, not from a component property.`);
+                }
                 await this._initializeDCC(parentNode.host, parentNode);
                 return;
             }
             await this._initializeBindWebComponent();
             await this._initialize();
             this._initialized = true;
+            // 名前登録（_initialize の末尾）が済んだこの時点でなければ、子スコープの
+            // `@name` 参照が解決できない（§1.13）
+            this._initializeLightDomComponentScope();
             this._resolveInitialize?.();
         }
         else if (!this._dcc && getStateElementByName(this._rootNode, this._name) !== this) {
@@ -12026,6 +14223,7 @@ class State extends HTMLElementBase {
             // createState が rootNode 経由でこの要素を解決できるようにするために必要
             // （$connectedCallback の再実行と $streams の initial からの再起動が依存する、設計書 §2-3）。
             setStateElementByName(this._rootNode, this._name, this);
+            this._reloadMappedPathsAfterReconnect();
         }
         // enable-ssr (クライアント側): SSR で $connectedCallback 済みなのでスキップ
         // inSsr() (サーバー側): レンダリング中なので実行する
@@ -12034,14 +14232,24 @@ class State extends HTMLElementBase {
         }
         // サーバーモード + enable-ssr: バインディング完了後に <wcs-ssr> を生成
         if (inSsr() && this.hasAttribute('enable-ssr')) {
-            await getBindingsReady(this.rootNode);
-            const name = this.getAttribute('name') || 'default';
-            const stateData = Ssr.extractStateData(this);
-            const ssrEl = document.createElement(config.tagNames.ssr);
-            ssrEl.setAttribute('name', name);
-            ssrEl.setAttribute('version', VERSION);
-            Ssr.buildContent(ssrEl, stateData);
-            this.parentNode?.insertBefore(ssrEl, this);
+            try {
+                await getBindingsReady(this.rootNode);
+                const name = this.getAttribute('name') || 'default';
+                const stateData = Ssr.extractStateData(this);
+                const ssrEl = document.createElement(config.tagNames.ssr);
+                ssrEl.setAttribute('name', name);
+                ssrEl.setAttribute('version', VERSION);
+                Ssr.buildContent(ssrEl, stateData);
+                this.parentNode?.insertBefore(ssrEl, this);
+            }
+            catch (error) {
+                // reject を配管しないと _connectedCallbackPromise が永久に未解決になり、
+                // renderToString が mutex を握ったまま connectedCallbackPromise 待ちで
+                // 無言ハングする。getBindingsReady の reject 化（設計書 §8.2）を
+                // SSR の消費者（render.ts）まで届けるための対。
+                this._rejectConnectedCallback?.(error);
+                throw error;
+            }
         }
         // $streams の eager 起動（$connectedCallback 完了後、設計書 §2-3）。
         // inSsr() 時は起動しない（SSR 出力には initial が乗る、§7-1）。
@@ -12059,6 +14267,19 @@ class State extends HTMLElementBase {
         // _streamsStartedGeneration ガード: $connectedCallback 内の setInitialState
         // （接続中の再 set）で _state セッター側が新宣言を起動済みの場合は skip する
         // （skip しないと同一 connect サイクルで source が 2 回起動する、設計書 §2-3）。
+        // $watch の有効化（$connectedCallback 完了後 ＝ 初期化中の書き込みは購読対象外）。
+        // ガードは startStreams と同じ理由で必要（await 中の切断・再接続）。SSR では
+        // 走らせない — ハンドラの副作用がサーバとクライアントで二重に実行されるため
+        // （docs/state-watch-hook-design.md §11）。
+        // startStreams より先に呼ぶ: stream の起動時書き込み（initial リセット・status 遷移）は
+        // watch から観測できるべきで、逆向きは要らない。
+        // 再入不要: 接続中の _state 再 set は _state セッター側で startWatch 済みだが、
+        // startWatch は Set への add で冪等なので $streams のような世代ガードは要らない。
+        if (!inSsr() &&
+            this._rootNode !== null &&
+            connectGeneration === this._connectGeneration) {
+            startWatch(this);
+        }
         if (!inSsr() &&
             this._rootNode !== null &&
             connectGeneration === this._connectGeneration &&
@@ -12088,10 +14309,17 @@ class State extends HTMLElementBase {
                 // registry は残るため再接続後の初回アクセスで同内容の proxy が再生成される）。
                 abortAllStreams(this);
                 clearStreamNamespace(this);
+                // watch は発火対象から外すだけで registry は保持する（stream の abortAllStreams と
+                // 同じ二段構え、設計書 §9）。registry まで捨てると、_state セッターが再度走らない
+                // 再接続で宣言を作り直せず watch が二度と発火しない。
+                deactivateWatch(this);
                 this._rootNode = null;
             }
         }
     }
+    get initialized() {
+        return this._initialized;
+    }
     get initializePromise() {
         return this._initializePromise;
     }
@@ -12101,6 +14329,12 @@ class State extends HTMLElementBase {
     get listPaths() {
         return this._listPaths;
     }
+    get listKeys() {
+        return this._listKeys;
+    }
+    get watchPaths() {
+        return this._watchPaths;
+    }
     get elementPaths() {
         return this._elementPaths;
     }
@@ -12128,9 +14362,29 @@ class State extends HTMLElementBase {
         }
         return this._rootNode;
     }
+    /**
+     * `rootNode` を保持しているか ＝ `createState` を呼んでよいか（§1.9）。
+     * disconnect で落ち、connect の冒頭で復活する。
+     */
+    get hasRootNode() {
+        return this._rootNode !== null;
+    }
     get boundComponentStateProp() {
         return this._boundComponentStateProp;
     }
+    get boundComponent() {
+        return this._boundComponent;
+    }
+    get hasMappedComponentState() {
+        return this._hasMappedComponentState;
+    }
+    /**
+     * この state の実体が innerState proxy であることを記録する。唯一の呼び手は
+     * `bindWebComponent` の mapped 分岐（§1.8）。
+     */
+    markComponentStateMapped() {
+        this._hasMappedComponentState = true;
+    }
     get bindableEventMap() {
         return this._bindableEventMap;
     }
@@ -12187,8 +14441,15 @@ class State extends HTMLElementBase {
     }
     setPathInfo(path, bindingType) {
         if (bindingType === "for") {
+            const isNewListPath = !this._listPaths.has(path);
             this._listPaths.add(path);
             this._elementPaths.add(path + '.' + WILDCARD);
+            // mapped な bind-component の子が回している for は、配列の実体を親スコープが
+            // 持っている。親の依存 walk / swap 判定はどちらも「その state 要素の」
+            // listPaths・elementPaths を見るので、マップ先のパスにも同じ宣言を届ける（§1.8）。
+            if (isNewListPath && this._hasMappedComponentState) {
+                propagateListPathToOuterState(this, path);
+            }
         }
         if (!this._pathSet.has(path)) {
             const pathInfo = getPathInfo(path);
@@ -12385,6 +14646,8 @@ const builtinFilterMeta = {
     mul: { description: "乗算", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 1, maxArgs: 1, argTypes: ["number"] },
     div: { description: "除算", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 1, maxArgs: 1, argTypes: ["number"] },
     mod: { description: "剰余", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 1, maxArgs: 1, argTypes: ["number"] },
+    abs: { description: "絶対値", hasArgs: false, resultType: "number", acceptTypes: ["number"], minArgs: 0, maxArgs: 0 },
+    clamp: { description: "範囲内に丸める (min,max)", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 2, maxArgs: 2, argTypes: ["number", "number"] },
     // 数値フォーマット
     fix: { description: "固定小数点表記", hasArgs: true, resultType: "string", acceptTypes: ["number"], minArgs: 0, maxArgs: 1, argTypes: ["number"] },
     locale: { description: "ロケール形式で数値フォーマット", hasArgs: true, resultType: "string", acceptTypes: ["number"], minArgs: 0, maxArgs: 1, argTypes: ["string"] },
@@ -12398,6 +14661,8 @@ const builtinFilterMeta = {
     pad: { description: "パディング (length[,char])", hasArgs: true, resultType: "string", acceptTypes: ["string"], minArgs: 1, maxArgs: 2, argTypes: ["number", "string"] },
     rep: { description: "繰り返し (count)", hasArgs: true, resultType: "string", acceptTypes: ["string"], minArgs: 1, maxArgs: 1, argTypes: ["number"] },
     rev: { description: "文字順を反転", hasArgs: false, resultType: "string", acceptTypes: ["string"], minArgs: 0, maxArgs: 0 },
+    truncate: { description: "切り詰めて省略記号 (length[,suffix])", hasArgs: true, resultType: "string", acceptTypes: ["string"], minArgs: 1, maxArgs: 2, argTypes: ["number", "string"] },
+    join: { description: "配列を連結 ([separator])", hasArgs: true, resultType: "string", acceptTypes: ["array"], minArgs: 0, maxArgs: 1, argTypes: ["string"] },
     // 数値パース・丸め
     int: { description: "整数にパース", hasArgs: false, resultType: "number", acceptTypes: ["string", "number"], minArgs: 0, maxArgs: 0 },
     float: { description: "浮動小数点数にパース", hasArgs: false, resultType: "number", acceptTypes: ["string", "number"], minArgs: 0, maxArgs: 0 },
@@ -12405,11 +14670,15 @@ const builtinFilterMeta = {
     floor: { description: "切り下げ", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 0, maxArgs: 1, argTypes: ["number"] },
     ceil: { description: "切り上げ", hasArgs: true, resultType: "number", acceptTypes: ["number"], minArgs: 0, maxArgs: 1, argTypes: ["number"] },
     percent: { description: "パーセンテージ形式", hasArgs: true, resultType: "string", acceptTypes: ["number"], minArgs: 0, maxArgs: 1, argTypes: ["number"] },
+    // number だけでなく string も受ける。実用チェーンは fix / percent の後ろに繋がり、
+    // それらは既に string を返すため（builtinFilters.ts の unit を参照）
+    unit: { description: "単位（接尾辞）を付加", hasArgs: true, resultType: "string", acceptTypes: ["number", "string"], minArgs: 1, maxArgs: 1, argTypes: ["string"] },
     // 日付・時刻
     date: { description: "ロケール形式の日付", hasArgs: false, resultType: "string", acceptTypes: "any", minArgs: 0, maxArgs: 0 },
     time: { description: "ロケール形式の時刻", hasArgs: false, resultType: "string", acceptTypes: "any", minArgs: 0, maxArgs: 0 },
     datetime: { description: "ロケール形式の日時", hasArgs: false, resultType: "string", acceptTypes: "any", minArgs: 0, maxArgs: 0 },
     ymd: { description: "YYYY-MM-DD 形式", hasArgs: true, resultType: "string", acceptTypes: "any", minArgs: 0, maxArgs: 1, argTypes: ["string"] },
+    hms: { description: "HH:MM:SS 形式", hasArgs: true, resultType: "string", acceptTypes: "any", minArgs: 0, maxArgs: 1, argTypes: ["string"] },
     // 真偽値・変換
     falsy: { description: "偽値か判定", hasArgs: false, resultType: "boolean", acceptTypes: "any", minArgs: 0, maxArgs: 0 },
     truthy: { description: "真値か判定", hasArgs: false, resultType: "boolean", acceptTypes: "any", minArgs: 0, maxArgs: 0 },
@@ -12465,11 +14734,14 @@ function getWcsManifest() {
         ],
         reservedStateApi: [
             STATE_BINDABLES_NAME,
+            STATE_COMMANDS_NAME,
             STATE_COMMAND_TOKENS_NAME,
             STATE_COMMAND_NAMESPACE_NAME,
             STATE_EVENT_TOKENS_NAME,
             STATE_ON_NAME,
             STATE_STREAMS_NAME,
+            STATE_WATCH_NAME,
+            STATE_LIST_KEYS_NAME,
             STATE_STREAM_STATUS_NAMESPACE_NAME,
             STATE_STREAM_ERROR_NAMESPACE_NAME,
         ],