@wcstack/state 1.3.17 → 1.3.19

package/README.ja.md

@@ -2,11 +2,65 @@
 
 **もしHTMLにリアクティブなデータバインディングがあったら？**
 
-ブラウザが状態をネイティブに理解する未来を妄想してみる。データをインラインで宣言し、属性でDOMにバインドすれば、すべてが自動で同期する。仮想DOMもコンパイルも不要。ただのHTMLが、勝手にリアクティブになる。
+ブラウザが状態をネイティブに理解する未来を想像してみてください。データをインラインで宣言し、属性でDOMにバインドするだけで、すべてが自動で同期します。仮想DOMもコンパイルも不要。ただのHTMLが、そのままリアクティブになる世界です。
 
-それが `<wcs-state>` と `data-wcs` の探求するもの。CDN一発、依存ゼロ、構文はHTML。
+それが `<wcs-state>` と `data-wcs` の目指すアプローチです。CDNからの読み込みだけで動作し、依存パッケージはゼロ、構文はHTMLそのままです。
 
-CDNスクリプトはカスタム要素の定義を登録するだけ — ロード時にはそれ以外何も起きない。`<wcs-state>` 要素がDOMに接続されたとき、状態ソースを読み取り、兄弟要素の `data-wcs` バインディングを走査し、リアクティビティを構築する。すべての初期化は要素のライフサイクルが駆動する。あなたのコードではなく。
+CDNのスクリプトはカスタム要素の定義を登録するだけで、ロード時にはそれ以外の処理は走りません。`<wcs-state>` 要素がDOMに接続されたときにはじめて、状態ソースを読み取り、同一ルートノード（`document` または `ShadowRoot`）内の `data-wcs` バインディングを走査してリアクティビティを構築します。初期化プロセスはすべて要素のライフサイクルによって駆動されるため、独自の初期化コードを書く必要はありません。
+
+## 設計思想
+
+### パスが唯一の契約
+
+既存の多くのフレームワークでは、**コンポーネント**がUIと状態の結合点になっています。状態ストアを外部に切り出しても、コンポーネント内にフックやセレクタ、リアクティブプリミティブといった**状態を引き込むためのコード**が必ず必要になります。つまり、UIと状態は常にJavaScriptの中で結びついているのです。
+
+`@wcstack/state` はこの結合を完全に排除しました。UIと状態を結びつけているのは**パス文字列**だけです — `user.name` や `cart.items.*.subtotal` のようなドット区切りのアドレスのみが、2つのレイヤー間の唯一の契約（コントラクト）になります:
+
+| レイヤー | 知っていること | 知らないこと |
+|----------|----------------|--------------|
+| **状態** (`<wcs-state>`) | データ構造とビジネスロジック | どのDOM要素がバインドされているか |
+| **UI** (`data-wcs`) | パス文字列と表示意図 | 状態がどう保存・算出されているか |
+| **コンポーネント** (`@name`) | 名前付き状態から必要なパス | 他コンポーネントの内部実装 |
+
+3つのレベルのパス契約が疎結合を実現しています:
+
+1. **UI ↔ 状態** — `data-wcs="textContent: user.name"` という属性がバインディングのすべてです。フックもセレクタもリアクティブプリミティブもありません。コンポーネントのJavaScriptには、状態を参照するコードが**一行も**必要ありません。
+
+2. **コンポーネント ↔ コンポーネント** — コンポーネント間の通信は、名前付き状態の参照（`@stateName`）で行われます。コンポーネント同士がお互いを直接インポートしたり参照したりすることはありません。共有するのはパスの命名規約だけです。
+
+3. **ループコンテキスト** — `for` ループ内では `*` が抽象インデックスとして機能します。`items.*.price` のようなバインディングは自動的に現在の要素へと解決されます。テンプレートは自身の具体的な位置（インデックス）を知る必要がなく、ワイルドカードがその契約となります。
+
+### なぜこれが重要なのか
+
+これはUIと状態の完全な分離を、**JavaScriptのコードを介することなく**実現していることを意味します。つまり:
+
+- UIをすべて作り直しても、状態のロジックに触れる必要がありません。
+- 状態のデータ構造をリファクタリングしても、パス文字列の更新だけで済みます。
+- HTMLを読むだけで、すべてのデータ依存関係を把握できます。
+
+このパスによる契約は、REST APIのURLと同じ発想です — 両者が合意するシンプルな文字列だけが存在し、そこに共有するコードはありません。これはJavaScriptの上に独自のテンプレート言語を発明するのではなく、HTML本来の宣言的な性質をフルに活かした結果として生まれた設計です。
+
+## わずか4ステップで動作
+
+```html
+<!-- 1. CDN を読み込む -->
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+
+<!-- 2. <wcs-state> タグを書く -->
+<wcs-state>
+  <!-- 3. 状態オブジェクトを定義する -->
+  <script type="module">
+    export default {
+      message: "Hello, World!"
+    };
+  </script>
+</wcs-state>
+
+<!-- 4. data-wcs 属性でバインドする -->
+<div data-wcs="textContent: message"></div>
+```
+
+これだけです。ビルドツールも、初期化コードも、重いフレームワークも必要ありません。
 
 ## 特徴
 
@@ -156,11 +210,11 @@ this.count = 10;               // パス "count"
 this["user.name"] = "Bob";     // パス "user.name"
 ```
 
-ルールはひとつ: **パスに代入すれば、DOMは自動的に更新される。**
+ルールは1つだけです。**「パスに直接代入する」ことで、関連するDOMが自動的に更新されます。**
 
-### なぜ `this.user.name = "Bob"` では動かないのか
+### なぜ `this.user.name = "Bob"` ではDOMが更新されないのか
 
-`this.user.name` は、まず `this.user` で `user` オブジェクトを読み取り（パスの読み取り）、そのプレーンオブジェクトの `.name` に設定します — これはパスへの代入ではないため、変更は検知されません:
+通常のプロパティアクセスの書き方だと、まず `this.user` でプレーンな `user` オブジェクトを読み取り（パスの読み取り）、取得したオブジェクトの `.name` を直接書き換える挙動になります。これは「パスに対するプロパティ代入」というフックを経由していないため、システム側で変更を検知できません：
 
 ```javascript
 // ✅ パスへの代入 — 変更が検知される
@@ -172,7 +226,7 @@ this.user.name = "Bob";
 
 ### 配列
 
-同じルールです: パスに新しい配列を代入します。破壊的メソッド（`push`, `splice`, `sort` 等）はパスへの代入なしに配列をその場で変更するため、非破壊的な代替メソッドを使用します:
+配列についても全く同じルールが適用されます。常に**パスに対して新しい配列を代入**してください。`push` や `splice`、`sort` などの破壊的な配列メソッドは、パスへの代入を介さずに状態をその場で（in-placeに）書き換えてしまうため、変更が検知されません。代わりに、新しい配列を返す非破壊的なメソッドを使用します：
 
 ```javascript
 // ✅ 新しい配列をパスに代入 — 変更が検知される
@@ -840,14 +894,14 @@ export default {
 
 `@wcstack/state` は Shadow DOM または Light DOM を使用したカスタム要素との双方向状態バインディングに対応しています。
 
-多くのフレームワークでは、コンポーネント間の状態共有に props バケツリレー、Context Provider、外部ストア（Redux, Pinia）といったパターンが用いられます。`@wcstack/state` は異なるアプローチを採ります。親子コンポーネントは**パスの契約**で接続されます。親は `data-wcs` で外部の状態パスを子コンポーネントのプロパティにバインドし、子は自身の状態を通常どおり読み書きするだけです：
+多くのフレームワークでは、コンポーネント間の状態共有に props のバケツリレー、Context Provider、あるいは外部ストア（Redux, Pinia など）といったパターンが用いられます。`@wcstack/state` はこれらとは異なるアプローチを採ります。親コンポーネントと子コンポーネントは**パスの契約**によって結びつけられます。親は `data-wcs` 属性を使って外部の状態パスを子コンポーネントのプロパティにバインドし、子は自身の状態として通常通り読み書きを行うだけです：
 
-1. 子コンポーネントは自身の状態プロキシを通じて親の状態を参照・更新します — props もイベントも親の存在を意識する必要もありません。
+1. 子コンポーネントは、自身の状態プロキシを通じて親の状態を参照・更新します。props の受け渡しやイベント発行など、親の存在を意識したコーディングは必要ありません。
 2. 親の状態が変更されると、Proxy の `set` トラップが影響するパスを参照している子のバインディングへ自動的に通知します。
-3. 結合点は**パス名のみ**であるため、双方とも疎結合を保ち、独立してテスト可能です。
-4. コストはパス解決（初回アクセス後はキャッシュにより O(1)）と依存グラフを通じた変更伝播のみです。
+3. 結合点は**パス名のみ**であるため、親と子は完全に疎結合な状態を保ち、それぞれ独立してテスト可能です。
+4. 実行コストは、パスの解決（初回アクセス後はキャッシュされるため O(1) で動作します）と、依存グラフを通じた変更の伝播のみです。
 
-これは、コンポーネントレベルの抽象化ではなくパス解決に基づく、コンポーネント間状態管理への軽量なアプローチです。
+これは、コンポーネントレベルの複雑な抽象化ではなく、「パスの解決」に基づいたコンポーネント間状態管理への軽量なアプローチです。
 
 ### コンポーネント定義（Shadow DOM）
 
@@ -1004,13 +1058,13 @@ customElements.define("my-component", MyComponent);
 | `$disconnectedCallback` | 要素が DOM から削除された時 | 不可（同期のみ） |
 | `$updatedCallback(paths, indexesListByPath)` | 状態変更が適用された後に呼び出し | 戻り値は未使用（待機されない） |
 
-リアクティブ Proxy は全てのプロパティ代入を変更として検知するため、標準の `async/await` とプロパティへの直接代入だけで非同期処理は完結します。ローディングフラグ、取得データ、エラーメッセージの更新は全てプロパティ代入であり、非同期状態管理のための追加の抽象化を必要としません。
+リアクティブ Proxy はすべてのプロパティへの代入を変更として検知します。そのため、標準の `async/await` による処理とプロパティへの直接代入だけで非同期ロジックが完結します。ローディングフラグの切り替え、取得したデータの格納、エラーメッセージの更新といった処理もすべて単なるプロパティ代入で行えるため、非同期状態を管理するための複雑な抽象化機能は必要ありません。
 
-- フック内の `this` は読み書き可能な状態プロキシです
-- `$connectedCallback` は要素が接続される**たびに**呼ばれます（削除後の再接続を含む）。再確立が必要なセットアップ処理に適しています
-- `$disconnectedCallback` は同期的に呼び出されます — タイマーのクリア、イベントリスナーの削除、リソースの解放などのクリーンアップに使用します
-- `$updatedCallback(paths, indexesListByPath)` は更新された状態パスの一覧を受け取ります。ワイルドカードパス更新時は `indexesListByPath` で更新対象インデックスも受け取れます
-- Web Component では `async $stateReadyCallback(stateProp)` を定義すると、`bind-component` でバインドされた状態が利用可能になったタイミングで呼び出されます
+- フック内の `this` は読み書き可能な状態プロキシです。
+- `$connectedCallback` は要素が接続される**たびに**呼ばれます（一度削除された後の再接続も含みます）。再確立が必要なセットアップ処理に適しています。
+- `$disconnectedCallback` は同期的に呼び出されます。タイマーのクリア、イベントリスナーの削除、リソースの解放といったクリーンアップ処理に使用してください。
+- `$updatedCallback(paths, indexesListByPath)` は更新された状態パスの一覧を受け取ります。ワイルドカードをもつパスが更新された場合は、`indexesListByPath` から対象のインデックス情報も取得可能です。
+- Web Component を使用している場合は、コンポーネント側に `async $stateReadyCallback(stateProp)` を定義おくことで、`bind-component` でバインドした状態が利用可能になった瞬間にフックとして呼び出されます。
 
 ## 設定
 
@@ -1077,12 +1131,21 @@ bootstrapState();
 
 ```
 bootstrapState()
-  ├── registerComponents()    // <wcs-state> カスタム要素を登録
-  └── registerHandler()       // DOMContentLoaded ハンドラ
-        ├── waitForStateInitialize()    // 全 <wcs-state> の読み込み待機
-        ├── convertMustacheToComments() // {{ }} → コメントノードに変換
-        ├── collectStructuralFragments() // for/if テンプレートを収集
-        └── initializeBindings()        // DOM 走査、data-wcs 解析、バインディング設定
+  └── registerComponents()              // <wcs-state> カスタム要素を登録
+
+<wcs-state> connectedCallback
+  ├── _initializeBindWebComponent()     // bind-component: 親コンポーネントから状態を取得
+  ├── _initialize()                     // 状態をロード (state属性 / src / json / script / API)
+  │     └── setStateElementByName()     // WeakMap<Node, Map<name, element>> に登録
+  │           └── (rootNode への初回登録時)
+  │                 └── queueMicrotask → buildBindings()
+  ├── _callStateConnectedCallback()     // $connectedCallback が定義されていれば呼び出し
+
+buildBindings(root)
+  ├── waitForStateInitialize()          // 全 <wcs-state> の initializePromise を待機
+  ├── convertMustacheToComments()       // {{ }} → コメントノードに変換
+  ├── collectStructuralFragments()      // for/if テンプレートを収集
+  └── initializeBindings()              // DOM 走査、data-wcs 解析、バインディング設定
 ```
 
 ### リアクティビティフロー

package/README.md

@@ -6,7 +6,61 @@ Imagine a future where the browser natively understands state — you declare da
 
 That's what `<wcs-state>` and `data-wcs` explore. One CDN import, zero dependencies, pure HTML syntax.
 
-The CDN script only registers the custom element definition — nothing else happens at load time. When a `<wcs-state>` element connects to the DOM, it reads its state source, scans sibling elements for `data-wcs` bindings, and wires up reactivity. All initialization is driven by the element's lifecycle, not by your code.
+The CDN script only registers the custom element definition — nothing else happens at load time. When a `<wcs-state>` element connects to the DOM, it reads its state source, scans all `data-wcs` bindings within the same root node (`document` or `ShadowRoot`), and wires up reactivity. All initialization is driven by the element's lifecycle, not by your code.
+
+## Design Philosophy
+
+### Path as the Universal Contract
+
+In every existing framework, the **component** is the coupling point between UI and state. Components import state hooks, selectors, or reactive primitives, and the binding happens inside JavaScript. No matter how cleanly you separate your state store, there is always glue code in the component that pulls state in.
+
+`@wcstack/state` eliminates that coupling entirely. The **only** thing connecting UI and state is a **path string** — a dot-separated address like `user.name` or `cart.items.*.subtotal`. This is the sole contract between the two layers:
+
+| Layer | What it knows | What it doesn't know |
+|-------|---------------|----------------------|
+| **State** (`<wcs-state>`) | Data structure and business logic | Which DOM nodes are bound |
+| **UI** (`data-wcs`) | Path strings and display intent | How state is stored or computed |
+| **Components** (`@name`) | The path they need from a named state | The other component's internals |
+
+Three levels of path contracts keep everything loosely coupled:
+
+1. **UI ↔ State** — A `data-wcs="textContent: user.name"` attribute is the entire binding. No hooks, no selectors, no reactive primitives. The component's JavaScript doesn't contain a single line that references state.
+
+2. **Component ↔ Component** — Cross-component communication happens through named state references (`@stateName`). Components never import or depend on each other; they share a naming convention, nothing more.
+
+3. **Loop context** — Inside a `for` loop, `*` acts as an abstract index. Bindings like `items.*.price` resolve to the current element automatically. The template doesn't know its concrete position — the wildcard is the contract.
+
+### Why This Matters
+
+This is complete separation of UI and state with **no JavaScript intermediary**. You can:
+
+- Redesign the entire UI without touching state logic
+- Refactor state structure and only update path strings
+- Read the HTML alone and understand every data dependency
+
+The path contract works like a URL in a REST API — a simple string that both sides agree on, with no shared code between them. It's the natural result of building on HTML's declarative nature rather than inventing a template language on top of JavaScript.
+
+## 4 Steps to Reactive HTML
+
+```html
+<!-- 1. Load the CDN -->
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+
+<!-- 2. Write a <wcs-state> tag -->
+<wcs-state>
+  <!-- 3. Define your state object -->
+  <script type="module">
+    export default {
+      message: "Hello, World!"
+    };
+  </script>
+</wcs-state>
+
+<!-- 4. Bind with data-wcs attributes -->
+<div data-wcs="textContent: message"></div>
+```
+
+That's it. No build, no bootstrap code, no framework.
 
 ## Features
 
@@ -1077,12 +1131,21 @@ bootstrapState();
 
 ```
 bootstrapState()
-  ├── registerComponents()    // Register <wcs-state> custom element
-  └── registerHandler()       // DOMContentLoaded handler
-        ├── waitForStateInitialize()    // Wait for all <wcs-state> to load
-        ├── convertMustacheToComments() // {{ }} → comment nodes
-        ├── collectStructuralFragments() // Collect for/if templates
-        └── initializeBindings()        // Walk DOM, parse data-wcs, set up bindings
+  └── registerComponents()              // Register <wcs-state> custom element
+
+<wcs-state> connectedCallback
+  ├── _initializeBindWebComponent()     // bind-component: get state from parent component
+  ├── _initialize()                     // Load state (state attr / src / json / script / API)
+  │     └── setStateElementByName()     // Register to WeakMap<Node, Map<name, element>>
+  │           └── (first registration per rootNode)
+  │                 └── queueMicrotask → buildBindings()
+  ├── _callStateConnectedCallback()     // Call $connectedCallback if defined
+
+buildBindings(root)
+  ├── waitForStateInitialize()          // Wait for all <wcs-state> initializePromise
+  ├── convertMustacheToComments()       // {{ }} → comment nodes
+  ├── collectStructuralFragments()      // Collect for/if templates
+  └── initializeBindings()              // Walk DOM, parse data-wcs, set up bindings
 ```
 
 ### Reactivity Flow

package/dist/index.esm.js

@@ -1609,6 +1609,35 @@ function attachEventHandler(binding) {
     return true;
 }
 
+const cache = new WeakMap();
+function getCustomElement(node) {
+    const cached = cache.get(node);
+    if (cached !== undefined) {
+        return cached;
+    }
+    let value = null;
+    try {
+        if (node.nodeType !== Node.ELEMENT_NODE) {
+            return value;
+        }
+        const element = node;
+        const tagName = element.tagName.toLowerCase();
+        if (tagName.includes("-")) {
+            return value = tagName;
+        }
+        if (element.hasAttribute("is")) {
+            const is = element.getAttribute("is");
+            if (is.includes("-")) {
+                return value = is;
+            }
+        }
+        return value;
+    }
+    finally {
+        cache.set(node, value);
+    }
+}
+
 const CHECK_TYPES = new Set(['radio', 'checkbox']);
 const DEFAULT_VALUE_PROP_NAMES = new Set(['value', 'valueAsNumber', 'valueAsDate']);
 function isPossibleTwoWay(node, propName) {
@@ -1635,6 +1664,20 @@ function isPossibleTwoWay(node, propName) {
     if (tagName === 'textarea' && propName === 'value') {
         return true;
     }
+    const customTagName = getCustomElement(element);
+    if (customTagName !== null) {
+        const customClass = customElements.get(customTagName);
+        if (typeof customClass === "undefined") {
+            raiseError(`Custom element <${customTagName}> is not defined. Cannot determine if property "${propName}" is suitable for two-way binding.`);
+        }
+        const reactivityInfo = customClass.wcsReactivity;
+        if (reactivityInfo) {
+            if (reactivityInfo.properties?.includes(propName)
+                || (reactivityInfo.propertyMap?.[propName] ?? null) !== null) {
+                return true;
+            }
+        }
+    }
     return false;
 }
 
@@ -1646,7 +1689,26 @@ function getHandlerKey$2(binding, eventName) {
 }
 function getEventName$2(binding) {
     const tagName = binding.node.tagName.toLowerCase();
+    // 1.default event name
     let eventName = (tagName === 'select') ? 'change' : 'input';
+    // 2.protocol 
+    const customTagName = getCustomElement(binding.node);
+    if (customTagName !== null) {
+        const customClass = customElements.get(customTagName);
+        if (typeof customClass === "undefined") {
+            raiseError(`Custom element <${customTagName}> is not defined. Cannot determine event name for two-way binding.`);
+        }
+        const reactivityInfo = customClass.wcsReactivity;
+        if (reactivityInfo) {
+            if (reactivityInfo.properties?.includes(binding.propName)) {
+                eventName = reactivityInfo.defaultEvent;
+            }
+            if (reactivityInfo.propertyMap?.[binding.propName]) {
+                eventName = reactivityInfo.propertyMap[binding.propName];
+            }
+        }
+    }
+    // 3.modifier
     for (const modifier of binding.propModifiers) {
         if (modifier.startsWith('on')) {
             eventName = modifier.slice(2);
@@ -1682,6 +1744,16 @@ const twowayEventHandlerFunction = (stateName, propName, statePathName, inFilter
     });
 };
 function attachTwowayEventHandler(binding) {
+    const customTagName = getCustomElement(binding.node);
+    if (customTagName !== null) {
+        const customClass = customElements.get(customTagName);
+        if (typeof customClass === "undefined") {
+            customElements.whenDefined(customTagName).then(() => {
+                attachTwowayEventHandler(binding);
+            });
+            return;
+        }
+    }
     if (isPossibleTwoWay(binding.node, binding.propName) && binding.propModifiers.indexOf('ro') === -1) {
         const eventName = getEventName$2(binding);
         const key = getHandlerKey$2(binding, eventName);
@@ -1699,9 +1771,7 @@ function attachTwowayEventHandler(binding) {
         else {
             bindingSet.add(binding);
         }
-        return true;
     }
-    return false;
 }
 
 const lastListValueByAbsoluteStateAddress = new WeakMap();
@@ -1909,32 +1979,6 @@ function clearAbsoluteStateAddressByBinding(binding) {
     absoluteStateAddressByBinding.delete(binding);
 }
 
-const cache = new WeakMap();
-function isCustomElement(node) {
-    let value = cache.get(node);
-    if (value !== undefined) {
-        return value;
-    }
-    try {
-        if (node.nodeType !== Node.ELEMENT_NODE) {
-            return value = false;
-        }
-        const element = node;
-        if (element.tagName.includes("-")) {
-            return value = true;
-        }
-        if (element.hasAttribute("is")) {
-            if (element.getAttribute("is")?.includes("-")) {
-                return value = true;
-            }
-        }
-        return value = false;
-    }
-    finally {
-        cache.set(node, value ?? false);
-    }
-}
-
 const completeByStateElementByWebComponent = new WeakMap();
 function markWebComponentAsComplete(webComponent, stateElement) {
     let completeByStateElement = completeByStateElementByWebComponent.get(webComponent);
@@ -2967,9 +3011,9 @@ function applyChange(binding, context) {
     if (binding.bindingType === "event") {
         return;
     }
-    if (isCustomElement(binding.replaceNode)) {
-        const element = binding.replaceNode;
-        if (customElements.get(element.tagName.toLowerCase()) === undefined) {
+    const customTag = getCustomElement(binding.replaceNode);
+    if (customTag) {
+        if (customElements.get(customTag) === undefined) {
             // cutomElement側の初期化を期待
             return;
         }
@@ -5073,7 +5117,8 @@ function getOuterAbsolutePathInfo(webComponent, innerAbsPathInfo) {
     // 内側からのアクセスの場合、ルールがなければプライマリルールから新たにルールとバインディングを生成する
     const primaryMappingRuleSet = primaryMappingRuleSetByElement.get(webComponent);
     if (typeof primaryMappingRuleSet === 'undefined') {
-        raiseError('Primary mapping rule set not found for web component.');
+        // マッピングルールが存在しない場合はnullを返し、ローカル状態へのフォールバックを許可する
+        return null;
     }
     let primaryMappingRule = null;
     for (const currentPrimaryMappingRule of primaryMappingRuleSet) {
@@ -5088,9 +5133,8 @@ function getOuterAbsolutePathInfo(webComponent, innerAbsPathInfo) {
         break;
     }
     if (primaryMappingRule === null) {
-        raiseError(`Mapping rule not found for inner path "${innerAbsPathInfo.pathInfo.path}". ` +
-            `Did you forget to bind this property in the component's data-wcs attribute? ` +
-            `Available mappings: ${Array.from(primaryMappingRuleSet).map(r => r.innerAbsPathInfo.pathInfo.path).join(', ')}`);
+        // マッピングルールに一致しない場合はnullを返し、ローカル状態へのフォールバックを許可する
+        return null;
     }
     // マッチした残りのパスをouterPathInfoに付与して新たなルールを生成
     const primaryBinding = primaryBindingByMappingRule.get(primaryMappingRule);
@@ -5152,36 +5196,43 @@ class InnerStateProxyHandler {
                 // Promiseのthenと誤認識されるのを防ぐため、Promiseに存在するプロパティはProxyのgetで処理しない
                 return undefined;
             }
-            if (prop in target) {
-                return Reflect.get(target, prop, receiver);
-            }
             if (prop[0] === '$') {
                 return undefined;
             }
+            // 1. getter完全一致 → ローカル計算（this = receiverで依存自動追跡）
+            if (this._innerStateElement.getterPaths.has(prop) && prop in target) {
+                return Reflect.get(target, prop, receiver);
+            }
+            // 2 & 3. マッピング完全一致 / サブパス → 親の状態
             const innerPathInfo = getPathInfo(prop);
             const innerAbsPathInfo = getAbsolutePathInfo(this._innerStateElement, innerPathInfo);
             const outerAbsPathInfo = getOuterAbsolutePathInfo(this._webComponent, innerAbsPathInfo);
-            if (outerAbsPathInfo === null) {
-                raiseError(`Outer path info not found for inner path "${innerAbsPathInfo.pathInfo.path}" on web component.`);
-            }
-            const loopContext = getLoopContextByNode(this._webComponent);
-            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);
+            if (outerAbsPathInfo !== null) {
+                const loopContext = getLoopContextByNode(this._webComponent);
+                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);
+                        const absStateAddress = createAbsoluteStateAddress(outerAbsPathInfo, listIndex);
+                        setLastValueByAbsoluteStateAddress(absStateAddress, value);
+                    });
                 });
-            });
-            return value;
+                return value;
+            }
+            // 4. ローカルデータプロパティ → ローカル値
+            if (prop in target) {
+                return Reflect.get(target, prop, receiver);
+            }
+            // 5. エラー
+            raiseError(`Property "${prop}" not found in inner state: no mapping rule and no local state property.`);
         }
         else {
             return Reflect.get(target, prop, receiver);
@@ -5189,19 +5240,29 @@ class InnerStateProxyHandler {
     }
     set(target, prop, value, receiver) {
         if (typeof prop === 'string') {
+            // 1. setter完全一致 → ローカル処理（this = receiverで親への書き込み可能）
+            if (this._innerStateElement.setterPaths.has(prop) && prop in target) {
+                return Reflect.set(target, prop, value, receiver);
+            }
+            // 2 & 3. マッピング完全一致 / サブパス → 親に書く
             const innerPathInfo = getPathInfo(prop);
             const innerAbsPathInfo = getAbsolutePathInfo(this._innerStateElement, innerPathInfo);
             const outerAbsPathInfo = getOuterAbsolutePathInfo(this._webComponent, innerAbsPathInfo);
-            if (outerAbsPathInfo === null) {
-                raiseError(`Outer path info not found for inner path "${innerAbsPathInfo.pathInfo.path}" on web component.`);
-            }
-            const loopContext = getLoopContextByNode(this._webComponent);
-            outerAbsPathInfo.stateElement.createState("writable", (state) => {
-                state[setLoopContextSymbol](loopContext, () => {
-                    state[outerAbsPathInfo.pathInfo.path] = value;
+            if (outerAbsPathInfo !== null) {
+                const loopContext = getLoopContextByNode(this._webComponent);
+                outerAbsPathInfo.stateElement.createState("writable", (state) => {
+                    state[setLoopContextSymbol](loopContext, () => {
+                        state[outerAbsPathInfo.pathInfo.path] = value;
+                    });
                 });
-            });
-            return true;
+                return true;
+            }
+            // 4. ローカルデータプロパティ → ローカルに書く
+            if (prop in target) {
+                return Reflect.set(target, prop, value, receiver);
+            }
+            // 5. エラー
+            raiseError(`Property "${prop}" not found in inner state: no mapping rule and no local state property.`);
         }
         else {
             return Reflect.set(target, prop, value, receiver);
@@ -5209,19 +5270,26 @@ class InnerStateProxyHandler {
     }
     has(target, prop) {
         if (typeof prop === 'string') {
-            if (prop in target) {
-                return Reflect.has(target, prop);
-            }
             if (prop[0] === '$') {
                 return false;
             }
+            // 1. getter/setter完全一致
+            if ((this._innerStateElement.getterPaths.has(prop) || this._innerStateElement.setterPaths.has(prop)) && prop in target) {
+                return true;
+            }
+            // 2 & 3. マッピング
             const innerPathInfo = getPathInfo(prop);
             const innerAbsPathInfo = getAbsolutePathInfo(this._innerStateElement, innerPathInfo);
             const outerAbsPathInfo = getOuterAbsolutePathInfo(this._webComponent, innerAbsPathInfo);
-            if (outerAbsPathInfo === null) {
-                return false;
+            if (outerAbsPathInfo !== null) {
+                return true;
             }
-            return true;
+            // 4. ローカルデータ
+            if (prop in target) {
+                return true;
+            }
+            // 5. 存在しない
+            return false;
         }
         else {
             return Reflect.has(target, prop);
@@ -5494,7 +5562,8 @@ class State extends HTMLElement {
                 : parentNode instanceof Element
                     ? parentNode
                     : null;
-            if (boundComponent === null || !isCustomElement(boundComponent)) {
+            const customTagName = boundComponent ? getCustomElement(boundComponent) : null;
+            if (boundComponent === null || customTagName === null) {
                 raiseError(`"bind-component" requires <${config.tagNames.state}> to be a direct child of a custom element.`);
             }
             // LightDOMの場合、名前空間が上位スコープと共有されるためnameが必須
@@ -5502,7 +5571,7 @@ class State extends HTMLElement {
                 raiseError(`"bind-component" in Light DOM requires a "name" attribute to avoid namespace conflicts with the parent scope.`);
             }
             const boundComponentStateProp = this.getAttribute("bind-component");
-            await customElements.whenDefined(boundComponent.tagName.toLowerCase());
+            await customElements.whenDefined(customTagName.toLowerCase());
             // data-wcs属性がある場合は、上位の状態によりbinding情報の設定が完了するまで待機する
             if (boundComponent.hasAttribute(config.bindAttributeName)) {
                 await waitInitializeBinding(boundComponent);