@wcstack/state 1.20.0 → 1.21.1

package/README.ja.md

@@ -324,6 +324,10 @@ property[#modifier]: path[@state][|filter[|filter(args)...]]
 | `#prevent` | イベントハンドラで `event.preventDefault()` を呼び出す |
 | `#stop` | イベントハンドラで `event.stopPropagation()` を呼び出す |
 | `#onchange` | 双方向バインディングで `input` の代わりに `change` イベントを使用 |
+| `#init=<authority>` | バインディングの authority / 初期同期の向き — [バインディング authority](#バインディング-authority-init--sync) 参照 |
+| `#sync=<timing>` | 要素スナップショットの読み取りタイミング — [バインディング authority](#バインディング-authority-init--sync) 参照 |
+
+複数の修飾子は 1 つの `#` の後にカンマ区切りで書きます: `value#ro,init=none: path`
 
 ### 双方向バインディング
 
@@ -338,6 +342,46 @@ property[#modifier]: path[@state][|filter[|filter(args)...]]
 
 `<input type="button">` は除外されます。`#ro` で無効化、`#onchange` でイベントを変更できます。
 
+### バインディング authority (`#init=` / `#sync=`)
+
+`static wcBindable` を宣言したカスタム要素への prop バインディングは、**authority**（そのワイヤをどちら側が所有するか）を解決します。authority は初期値の出所だけでなく、**そのバインディングの生存期間全体で state→element 書き込みが有効かどうか**を決めます。既定はメンバの宣言位置から導出されます（`enableDirectionalInitialSync` で既定 ON）：
+
+| メンバの宣言位置 | 既定 authority | 効果 |
+|---|---|---|
+| `properties` のみ（output-only） | `element` | 要素の値が state に流れる。**state からこのメンバへは書き込まれない** |
+| `inputs` のみ | `state` | state が要素に書き込む |
+| `properties` + `inputs`（双方向） | `state` | 従来挙動 — state が先に書き、以後は要素イベントが state を更新 |
+| —（`wcBindable` 非宣言・素の HTML 要素） | `state` | 従来と不変 |
+
+> **作法：** settable なメンバは **`properties` と `inputs` の両方**に宣言してください。`properties` にしか宣言されていないメンバは output-only 扱いになり、state→element 書き込みがバインディングの生存期間ずっと抑止され、要素側の初期値が state 側のシード値を上書きします（`@wcstack` の I/O ノード Shell と DCC の `$bindables` はこの作法に従っています）。
+
+authority はバインディング単位で `#init=` により上書きできます：
+
+| 値 | authority | 使える宣言 |
+|---|---|---|
+| `init=state` | state 所有：state → element（双方向メンバは要素イベントも引き続き受信） | inputs のみ・双方向 |
+| `init=element` | element 所有：要素のスナップショットとイベント → state。state からの書き込みは抑止 | output-only・双方向 |
+| `init=auto` | state スロットが未初期化なら `element`、それ以外は `state` | 双方向 |
+| `init=none` | 初期同期なし（event バインディングはこの値のみ許可） | すべて |
+
+`#sync=` は element authority のバインディングで要素スナップショットを**いつ**読むかを制御します：
+
+| 値 | 意味 |
+|---|---|
+| `sync=call`（既定） | バインディングの attach 時に即読み取り |
+| `sync=connect` | 要素が document に接続されるまで読み取りを保留 |
+
+```html
+<x-clock  data-wcs="value#init=element: clock.now"></x-clock>
+<x-input  data-wcs="value#init=auto: form.name"></x-input>
+<x-widget data-wcs="value#init=element,sync=connect: widget.snapshot"></x-widget>
+```
+
+注意：
+
+- `enableDirectionalInitialSync: false`（opt-out）のとき `#init=`/`#sync=` を書くと throw します。
+- **1.20 以前からの移行：** output-only メンバに対して state 側に都合のよい初期値（`value: []`、`query: ""` 等）をシードしないでください — 要素側の実初期値（多くは `null`/`undefined`）がシードを置き換えます。シードは要素の実初期値に合わせ、表示用の値は派生 getter で null ガードしてください。
+
 ### ラジオボタンバインディング
 
 `radio` でラジオボタングループを単一の状態値にバインドします：
@@ -1193,7 +1237,7 @@ class MyFetcher extends HTMLElement {
 
 検証ルール（バインディング時に強制）：
 
-- 要素は `protocol: "wc-bindable"` かつ `version: 1` の `static wcBindable` を公開するカスタム要素であること
+- 要素は `protocol: "wc-bindable"` かつ整数 `version` が `1` 以上（現行プロトコルは `1`。1 以上のすべてのバージョンが core 互換）の `static wcBindable` を公開するカスタム要素であること
 - `methodName` は `wcBindable.commands` に（`name` で）現れること
 - バインドされる値は `CommandToken` であること（token 以外の値の代入は throw する —— 例えば未宣言の名前 `$command.typo` は `undefined` に解決され、ここで拒否される）
 
@@ -1352,7 +1396,7 @@ class MyTarget extends HTMLElement {
 
 検証ルール：
 
-- 要素は wc-bindable なカスタム要素であること（`static wcBindable`・`protocol: "wc-bindable"`・`version: 1`）。非 wc-bindable 要素は attach 時に拒否される。
+- 要素は wc-bindable なカスタム要素であること（`static wcBindable`・`protocol: "wc-bindable"`・整数 `version` が 1 以上。1 以上のすべてのバージョンが core 互換）。非 wc-bindable 要素は attach 時に拒否される。
 - `<property>` は `wcBindable.properties` に現れること —— **attach 時** に検証（fail-fast。クラス参照のみで足り、DOM 接続に非依存）。
 - `<tokenName>` は `$eventTokens` で宣言されていること —— **発火時** に検証。state はイベント発火時に要素の live root から解決されるため、attach 時にノードが detached になりうる `for` / `if` ブロック内や SSR ハイドレーション後でも機能する。
 - 修飾子 `#prevent` / `#stop` は通常のイベントバインディングと同様に機能する: `eventToken.error#prevent: createFailed`。
@@ -1454,6 +1498,8 @@ error 時、プロパティは直前の fold 結果を保持し、エラーは `
 
 `wcBindable.inputs` は一方向のプロパティ入力（state → 要素）を宣言します。エントリに `attribute` を設定すると、フレームワークはプロパティを書き込むたびにその値を当該 HTML 属性へも書き込むため、`attributeChangedCallback`・CSS の属性セレクタ・DevTools がすべてプロパティ値と同期し続けます。
 
+`inputs` は属性ミラーのためだけのメタデータではありません。方向認識初期同期（既定 ON）の下では、メンバが **state から settable であること**を示すのが `inputs` です。settable なのに `properties` にしか宣言されていないメンバは output-only 扱いになり、state からの書き込みが抑止されます — [バインディング authority](#バインディング-authority-init--sync) を参照してください。
+
 ```javascript
 class MyChip extends HTMLElement {
   static wcBindable = {
@@ -1552,7 +1598,7 @@ export default {
 
 これにより以下が生成されます：
 
-- クラスの `static wcBindable` — フレームワークアダプタ用のプロトコルメタデータ
+- クラスの `static wcBindable` — フレームワークアダプタ用のプロトコルメタデータ。各 `$bindables` メンバは `properties` と `inputs` の両方に宣言され（双方向）、方向認識初期同期の下でも親 state → DCC の書き込みが機能します — [バインディング authority](#バインディング-authority-init--sync) 参照
 - プロトタイプの getter/setter — リアクティブプロキシ経由で読み書き
 - `CustomEvent` のディスパッチ — 値が変更されるたびに `my-counter:count-changed` が発火
 
@@ -1671,6 +1717,21 @@ bootstrapState({
 | `locale` | `'en'` | フィルタのデフォルトロケール |
 | `debug` | `false` | デバッグモード |
 | `enableMustache` | `true` | `{{ }}` 構文の有効化 |
+| `enableDirectionalInitialSync` | `true` | 方向認識のバインディング authority（`#init=` / `#sync=` バインド modifier）— [バインディング authority](#バインディング-authority-init--sync) 参照。既定 on。`false` で opt-out |
+| `enablePropagationContext` | `true` | バインド間の因果伝播トラッキング（echo/diamond のループ防止）。既定 on。`false` で opt-out |
+| `enableContractAnalyzer` | `false` | opt-in の開発時 contract analyzer（`analyzeContract` を公開） |
+
+> この 3 つは **architecture-hardening** 機能で、規範は `docs/architecture-hardening/` に
+> あります。`enablePropagationContext` は**既定 on** — write-path コストは一方向バインドで
+> ほぼゼロ（echo しうる双方向 wire のみ因果 bookkeeping を行う）で、フラグは恒久的な
+> opt-out として残します。`enableDirectionalInitialSync` も**既定 on**: プロパティ単位で
+> 初期同期の authority を割り当てます（output-only な `wcBindable` メンバは初期値を
+> element→state で読み取り、双方向 / input メンバは state→element を維持）。setup-path
+> コストは初期 render の 5% 未満（producer-value observer は echo しうる双方向 wire にのみ
+> 登録）で、フラグは恒久的な opt-out として残します。`enableContractAnalyzer` は opt-in
+> （既定 `false`・無効時ランタイムコストゼロ）で、有効な場合、公開 API `analyzeContract()`
+> が稼働中の `static wcBindable` サーフェスと sidecar manifest の drift を開発時診断として
+> 報告します。
 
 ## TypeScript サポート
 

package/README.md

@@ -324,6 +324,10 @@ Multiple bindings separated by `;`:
 | `#prevent` | Calls `event.preventDefault()` on event handlers |
 | `#stop` | Calls `event.stopPropagation()` on event handlers |
 | `#onchange` | Uses `change` event instead of `input` for two-way binding |
+| `#init=<authority>` | Binding authority / initial sync direction — see [Binding Authority](#binding-authority-init--sync) |
+| `#sync=<timing>` | Element snapshot timing — see [Binding Authority](#binding-authority-init--sync) |
+
+Multiple modifiers are comma-separated after a single `#`: `value#ro,init=none: path`.
 
 ### Two-Way Binding
 
@@ -338,6 +342,46 @@ Automatically enabled for:
 
 `<input type="button">` is excluded. Use `#ro` to disable, `#onchange` to change the event.
 
+### Binding Authority (`#init=` / `#sync=`)
+
+For custom elements that declare `static wcBindable`, every prop binding resolves an **authority** — which side owns the wire. The authority decides both where the initial value comes from *and* whether state→element writes are enabled, for the binding's whole lifetime. It is derived from where the member is declared (on by default via `enableDirectionalInitialSync`):
+
+| Member declared in | Default authority | Effect |
+|---|---|---|
+| `properties` only (output-only) | `element` | The element's value flows into state; **state never writes this member** |
+| `inputs` only | `state` | State writes the element |
+| `properties` + `inputs` (two-way) | `state` | Classic behavior — state writes first, element events update state afterwards |
+| — (no `wcBindable`; plain HTML elements) | `state` | Unchanged behavior |
+
+> **Authoring rule:** declare every settable member in **both** `properties` and `inputs`. A member declared only in `properties` is output-only — state→element writes are suppressed for the life of the binding, and the element's own initial value overwrites whatever the state seeded. (`@wcstack` I/O node Shells and DCC `$bindables` follow this rule.)
+
+Override the authority per binding with `#init=`:
+
+| Value | Authority | Allowed on |
+|---|---|---|
+| `init=state` | State-owned: state → element (two-way members still receive element events) | inputs-only, two-way |
+| `init=element` | Element-owned: element snapshot and events → state; state writes are suppressed | output-only, two-way |
+| `init=auto` | `element` if the state slot is uninitialized, otherwise `state` | two-way |
+| `init=none` | No initial sync (event bindings accept only this value) | any |
+
+`#sync=` controls **when** the element snapshot is read for element-authority bindings:
+
+| Value | Meaning |
+|---|---|
+| `sync=call` (default) | Read immediately when the binding attaches |
+| `sync=connect` | Defer the read until the element is connected to the document |
+
+```html
+<x-clock  data-wcs="value#init=element: clock.now"></x-clock>
+<x-input  data-wcs="value#init=auto: form.name"></x-input>
+<x-widget data-wcs="value#init=element,sync=connect: widget.snapshot"></x-widget>
+```
+
+Notes:
+
+- With `enableDirectionalInitialSync: false` (opt-out), writing `#init=`/`#sync=` throws.
+- **Migrating from ≤ 1.20:** do not seed state with placeholder values (`value: []`, `query: ""`) for output-only members — the element's real initial value (often `null`/`undefined`) replaces the seed. Match the seed to the element's actual initial value and null-guard display values with a derived getter.
+
 ### Radio Binding
 
 Bind a radio button group to a single state value with `radio`:
@@ -1194,7 +1238,7 @@ class MyFetcher extends HTMLElement {
 
 Validation rules (enforced at binding time):
 
-- The element must be a custom element exposing `static wcBindable` with `protocol: "wc-bindable"` and `version: 1`
+- The element must be a custom element exposing `static wcBindable` with `protocol: "wc-bindable"` and an integer `version` of `1` or later (the current protocol version is `1`; all versions ≥ 1 are core-compatible)
 - `methodName` must appear (by `name`) in `wcBindable.commands`
 - The bound value must be a `CommandToken` (assigning a non-token value throws — for example, an undeclared name like `$command.typo` resolves to `undefined` and is rejected here)
 
@@ -1353,7 +1397,7 @@ class MyTarget extends HTMLElement {
 
 Validation rules:
 
-- The element must be a wc-bindable custom element (`static wcBindable`, `protocol: "wc-bindable"`, `version: 1`). A non-wc-bindable element is rejected at attach time.
+- The element must be a wc-bindable custom element (`static wcBindable`, `protocol: "wc-bindable"`, integer `version` ≥ 1 — all versions ≥ 1 are core-compatible). A non-wc-bindable element is rejected at attach time.
 - `<property>` must appear in `wcBindable.properties` — checked at **attach time** (fail-fast; needs only the class, not DOM connection).
 - `<tokenName>` must be declared in `$eventTokens` — checked at **fire time**. State is resolved from the element's live root node when the event fires, so the binding also works inside `for` / `if` blocks and after SSR hydration, where the node may still be detached at attach time.
 - Modifiers `#prevent` / `#stop` work as on any event binding: `eventToken.error#prevent: createFailed`.
@@ -1455,6 +1499,8 @@ See [docs/streams.md](docs/streams.md) for the full contract — lifecycle and o
 
 `wcBindable.inputs` declares one-way property inputs (state → element). When an entry sets `attribute`, the framework writes the value to that HTML attribute every time it writes the property, so `attributeChangedCallback`, CSS attribute selectors, and DevTools all stay in sync with the property value.
 
+`inputs` is not just attribute-mirroring metadata: under directional initial sync (default on), it is what marks a member as **settable from state**. A settable member declared only in `properties` becomes output-only and state writes to it are suppressed — see [Binding Authority](#binding-authority-init--sync).
+
 ```javascript
 class MyChip extends HTMLElement {
   static wcBindable = {
@@ -1553,7 +1599,7 @@ export default {
 
 This generates:
 
-- `static wcBindable` on the class — protocol metadata for framework adapters
+- `static wcBindable` on the class — protocol metadata for framework adapters. Each `$bindables` member is declared in both `properties` and `inputs` (two-way), so parent-state → DCC writes keep working under directional initial sync — see [Binding Authority](#binding-authority-init--sync)
 - Getter/setter on the prototype — reads/writes go through the reactive proxy
 - `CustomEvent` dispatch — `my-counter:count-changed` fires on every mutation
 
@@ -1672,6 +1718,22 @@ All options with defaults:
 | `locale` | `'en'` | Default locale for filters |
 | `debug` | `false` | Debug mode |
 | `enableMustache` | `true` | Enable `{{ }}` syntax |
+| `enableDirectionalInitialSync` | `true` | Direction-aware binding authority (`#init=` / `#sync=` binding modifiers) — see [Binding Authority](#binding-authority-init--sync). Default on; set `false` to opt out |
+| `enablePropagationContext` | `true` | Causal propagation tracking across bindings (echo/diamond loop prevention). Default on; set `false` to opt out |
+| `enableContractAnalyzer` | `false` | Opt-in dev-time contract analyzer (exposes `analyzeContract`) |
+
+> These three are **architecture-hardening** features; their normative reference is
+> `docs/architecture-hardening/`. `enablePropagationContext` defaults **on** — its
+> write-path cost is near-zero for one-way bindings (only echo-capable two-way
+> wires do the causal bookkeeping) — with the flag kept as a permanent opt-out.
+> `enableDirectionalInitialSync` also defaults **on**: it assigns per-property
+> initial-sync authority (an output-only `wcBindable` member reads its initial value
+> element→state; two-way / input members keep state→element). Its setup-path cost is
+> under 5% of initial render (the producer-value observer is only registered for
+> echo-capable two-way wires), and the flag is a permanent opt-out. `enableContractAnalyzer`
+> is opt-in (default `false`, zero runtime cost when off); when on, the exported
+> `analyzeContract()` API reports drift between a live `static wcBindable` surface and
+> a sidecar manifest for dev-time diagnostics.
 
 ## TypeScript Support
 

package/dist/index.d.ts

@@ -1,3 +1,168 @@
+/**
+ * Interface for hierarchical loop index management in nested loops.
+ * Tracks parent-child relationships, versions, and provides access to index hierarchy.
+ */
+interface IListIndex {
+    readonly parentListIndex: IListIndex | null;
+    readonly uuid: string;
+    readonly position: number;
+    readonly length: number;
+    index: number;
+    readonly version: number;
+    readonly dirty: boolean;
+    readonly indexes: number[];
+    readonly listIndexes: WeakRef<IListIndex>[];
+    readonly varName: string;
+    at(position: number): IListIndex | null;
+}
+interface ILoopContext extends IStateAddress {
+    readonly pathInfo: IPathInfo;
+    readonly listIndex: IListIndex;
+}
+interface ILoopContextStack {
+    createLoopContext(elementStateAddress: IStateAddress, callback: (loopContext: ILoopContext) => void | Promise<void>): void | Promise<void>;
+}
+
+declare const setLoopContextAsyncSymbol: unique symbol;
+declare const setLoopContextSymbol: unique symbol;
+declare const getByAddressSymbol: unique symbol;
+declare const hasByAddressSymbol: unique symbol;
+declare const setByAddressSymbol: unique symbol;
+declare const connectedCallbackSymbol: unique symbol;
+declare const disconnectedCallbackSymbol: unique symbol;
+declare const updatedCallbackSymbol: unique symbol;
+
+interface IStateProxy extends IState {
+    [setLoopContextAsyncSymbol](loopContext: ILoopContext | null, callback: () => Promise<any>): Promise<any>;
+    [setLoopContextSymbol](loopContext: ILoopContext | null, callback: () => any): any;
+    [getByAddressSymbol](address: IStateAddress): any;
+    [hasByAddressSymbol](address: IStateAddress): boolean;
+    [setByAddressSymbol](address: IStateAddress, value: any): void;
+    [connectedCallbackSymbol](): Promise<void>;
+    [disconnectedCallbackSymbol](): void;
+    [updatedCallbackSymbol](updatedAbsAddressList: IAbsoluteStateAddress[]): void;
+}
+type Mutability = "readonly" | "writable";
+
+interface IStateElement {
+    readonly name: string;
+    readonly initializePromise: Promise<void>;
+    readonly connectedCallbackPromise: Promise<void>;
+    readonly listPaths: Set<string>;
+    readonly elementPaths: Set<string>;
+    readonly getterPaths: Set<string>;
+    readonly setterPaths: Set<string>;
+    readonly loopContextStack: ILoopContextStack;
+    readonly dynamicDependency: Map<string, string[]>;
+    readonly staticDependency: Map<string, string[]>;
+    readonly version: number;
+    readonly rootNode: Node;
+    readonly boundComponentStateProp: string | null;
+    readonly bindableEventMap: Record<string, string>;
+    readonly commandTokenNames: ReadonlySet<string>;
+    readonly eventTokenNames: ReadonlySet<string>;
+    /**
+     * state が $updatedCallback を定義しているか。false のとき drain は更新
+     * アドレスの集計と最終の writable createState を丸ごとスキップできる。
+     * optional なのはテスト用モック互換のため（undefined は「不明＝集計する」）。
+     */
+    readonly hasUpdatedCallback?: boolean;
+    /**
+     * 他行を読む getter（隣接項目参照など）が検出されたリストパスの集合。
+     * これらのリストは walkDependency の diff-filter 展開の対象外（全行展開）。
+     * optional なのはテスト用モック互換のため（undefined は「検出なし」扱い）。
+     */
+    readonly crossRowListPaths?: ReadonlySet<string>;
+    addCrossRowListPath?(path: string): void;
+    setPathInfo(path: string, bindingType: BindingType): void;
+    addStaticDependency(parentPath: string, childPath: string): boolean;
+    addDynamicDependency(fromPath: string, toPath: string): boolean;
+    createStateAsync(mutability: Mutability, callback: (state: IStateProxy) => Promise<void>): Promise<void>;
+    createState(mutability: Mutability, callback: (state: IStateProxy) => void): void;
+    nextVersion(): number;
+    bindProperty(prop: string, desc: PropertyDescriptor): void;
+    setInitialState(state: Record<string, any>): void;
+}
+
+interface IPathInfo {
+    readonly id: number;
+    readonly path: string;
+    readonly segments: string[];
+    readonly lastSegment: string;
+    readonly cumulativePaths: string[];
+    readonly cumulativePathSet: Set<string>;
+    readonly cumulativePathInfos: IPathInfo[];
+    readonly cumulativePathInfoSet: Set<IPathInfo>;
+    readonly parentPath: string | null;
+    readonly parentPathInfo: IPathInfo | null;
+    readonly wildcardPaths: string[];
+    readonly wildcardPathSet: Set<string>;
+    readonly indexByWildcardPath: Record<string, number>;
+    readonly wildcardPathInfos: IPathInfo[];
+    readonly wildcardPathInfoSet: Set<IPathInfo>;
+    readonly wildcardParentPaths: string[];
+    readonly wildcardParentPathSet: Set<string>;
+    readonly wildcardParentPathInfos: IPathInfo[];
+    readonly wildcardParentPathInfoSet: Set<IPathInfo>;
+    readonly wildcardPositions: number[];
+    readonly lastWildcardPath: string | null;
+    readonly lastWildcardInfo: IPathInfo | null;
+    readonly wildcardCount: number;
+}
+interface IStateAddress {
+    readonly pathInfo: IPathInfo;
+    readonly listIndex: IListIndex | null;
+    readonly parentAddress: IStateAddress | null;
+}
+interface IAbsolutePathInfo {
+    readonly stateName: string;
+    readonly stateElement: IStateElement;
+    readonly pathInfo: IPathInfo;
+    readonly parentAbsolutePathInfo: IAbsolutePathInfo | null;
+}
+interface IAbsoluteStateAddress {
+    readonly absolutePathInfo: IAbsolutePathInfo;
+    readonly listIndex: IListIndex | null;
+    readonly parentAbsoluteAddress: IAbsoluteStateAddress | null;
+}
+
+/**
+ * Filter/types.ts
+ *
+ * Type definition file for filter functions.
+ *
+ * Main responsibilities:
+ * - Defines types for filter functions (FilterFn) and filter functions with options (FilterWithOptionsFn)
+ * - Type-safe management of filter name-to-function mappings (FilterWithOptions) and filter function arrays (Filters)
+ * - Defines types for retrieving filter functions from built-in filter collections
+ *
+ * Design points:
+ * - Type design enabling flexible filter design and extension
+ * - Supports filters with options and combinations of multiple filters
+ */
+type FilterFn<T = unknown> = (value: unknown) => T;
+
+type BindingType = 'text' | 'prop' | 'event' | 'for' | 'if' | 'elseif' | 'else' | 'radio' | 'checkbox' | 'spread';
+interface IFilterInfo {
+    readonly filterName: string;
+    readonly args: string[];
+    readonly filterFn: FilterFn;
+}
+interface IBindingInfo {
+    readonly propName: string;
+    readonly propSegments: string[];
+    readonly propModifiers: string[];
+    readonly statePathName: string;
+    readonly statePathInfo: IPathInfo;
+    readonly stateName: string;
+    readonly inFilters: IFilterInfo[];
+    readonly outFilters: IFilterInfo[];
+    readonly node: Node;
+    readonly replaceNode: Node;
+    readonly bindingType: BindingType;
+    readonly uuid?: string | null;
+}
+
 interface IState {
     [key: string]: any;
 }
@@ -20,6 +185,25 @@ interface IConfig {
     readonly locale: string;
     readonly debug: boolean;
     readonly enableMustache: boolean;
+    /**
+     * Enables direction-aware initial synchronization (`init=` / `sync=`).
+     * Disabled by default while Phase 2 is evaluated against existing snapshots.
+     */
+    readonly enableDirectionalInitialSync: boolean;
+    /**
+     * Enables causal propagation tracking (transaction / edge provenance /
+     * write receipts). Disabled by default while Phase 3 runs as a shadow of
+     * the primitive same-value guard.
+     */
+    readonly enablePropagationContext: boolean;
+    /**
+     * Enables the opt-in dev-time contract analyzer (Phase 5b). When false
+     * (default), `analyzeContract()` is a no-op with zero cost — runtime
+     * behavior and allocation are unchanged. When true, it checks the actually
+     * loaded `static wcBindable` declarations against a supplied sidecar
+     * manifest and emits `contract:*` drift trace via the DevTools sink.
+     */
+    readonly enableContractAnalyzer: boolean;
     /**
      * 同値ガード（**既定 true**・標準的リアクティブ挙動・`setConfig({ sameValueGuard: false })` で opt-out 可）。
      * primitive 値の set で `Object.is` 同値なら更新を no-op にする
@@ -40,6 +224,9 @@ interface IWritableConfig {
     locale?: string;
     debug?: boolean;
     enableMustache?: boolean;
+    enableDirectionalInitialSync?: boolean;
+    enablePropagationContext?: boolean;
+    enableContractAnalyzer?: boolean;
     sameValueGuard?: boolean;
 }
 
@@ -52,6 +239,13 @@ declare function getConfig(): IConfig;
  */
 declare function getBindingsReady(rootNode: Node): Promise<void>;
 
+/**
+ * Browser builds use the native HTMLElement. Headless runtimes receive an
+ * inert base so the public module can be imported without installing DOM
+ * globals; constructing components remains a browser-only operation.
+ */
+declare const HTMLElementBase: typeof HTMLElement;
+
 interface ISsrElement {
     readonly name: string;
     readonly version: string;
@@ -61,7 +255,7 @@ interface ISsrElement {
     getTemplate(uuid: string): HTMLTemplateElement | null;
     verifyVersion(): boolean;
 }
-declare class Ssr extends HTMLElement implements ISsrElement {
+declare class Ssr extends HTMLElementBase implements ISsrElement {
     private _stateData;
     private _templates;
     private _hydrateProps;
@@ -425,5 +619,141 @@ interface IWcsManifest {
 /** 機械可読な単一正本を返す。vscode-wcs はこれを消費する想定。 */
 declare function getWcsManifest(): IWcsManifest;
 
-export { Ssr, VERSION, WCS_MANIFEST_VERSION, bootstrapState, buildBindings, builtinFilterMeta, defineState, getBindingsReady, getConfig, getWcsManifest };
-export type { FilterArgType, FilterResultType, IFilterMeta, ISsrElement, IWcsManifest, IWritableConfig, IWritableTagNames, WcsPathValue, WcsPaths, WcsStateApi, WcsThis };
+/**
+ * devtools/types.ts
+ *
+ * DevTools Hook Protocol (docs/devtools-hook-protocol.md) の型定義。
+ *
+ * イベント payload はランタイム内部オブジェクト（IAbsoluteStateAddress /
+ * IBindingInfo 等）への生参照を含む（同一 realm・オーバーレイ前提、protocol 原則 4）。
+ * 消費者はこれらを変異してはならない。
+ */
+
+type DevtoolsEvent = {
+    readonly type: "state:element-registered";
+    readonly name: string;
+    readonly rootNode: Node;
+    readonly element: IStateElement;
+} | {
+    readonly type: "state:element-unregistered";
+    readonly name: string;
+    readonly rootNode: Node;
+    readonly element: IStateElement;
+} | {
+    readonly type: "state:write";
+    readonly absoluteAddress: IAbsoluteStateAddress;
+    readonly value: unknown;
+    /** same-value guard が既に取得していた場合のみ意味を持つ（protocol §4.2） */
+    readonly oldValue: unknown;
+    readonly hasOldValue: boolean;
+} | {
+    readonly type: "state:update-batch";
+    readonly addresses: ReadonlySet<IAbsoluteStateAddress>;
+} | {
+    readonly type: "state:binding-added";
+    readonly absoluteAddress: IAbsoluteStateAddress;
+    readonly binding: IBindingInfo;
+} | {
+    readonly type: "state:binding-removed";
+    readonly absoluteAddress: IAbsoluteStateAddress;
+    readonly binding: IBindingInfo;
+} | {
+    readonly type: "state:binding-cleared";
+    readonly absoluteAddress: IAbsoluteStateAddress;
+} | {
+    readonly type: "state:token-emit";
+    readonly kind: "command" | "event";
+    readonly stateName: string | null;
+    readonly tokenName: string;
+    readonly args: readonly unknown[];
+    readonly subscriberCount: number;
+} | {
+    readonly type: "propagation:suppressed";
+    readonly reason: "confirmation" | "visited-edge";
+    readonly transactionId: number;
+    readonly edgeId: number;
+    readonly node: Node;
+    readonly member: string;
+} | {
+    readonly type: "propagation:coalesced";
+    readonly absoluteAddress: IAbsoluteStateAddress;
+    readonly droppedTransactionId: number;
+    readonly winnerTransactionId: number;
+} | {
+    readonly type: "propagation:hop-limit";
+    readonly absoluteAddress: IAbsoluteStateAddress;
+    readonly transactionId: number;
+    readonly hop: number;
+} | {
+    readonly type: "contract:manifest-read";
+    readonly tag: string;
+    /** 実行時に該当タグが登録済みか(未登録なら drift の起点)。 */
+    readonly loaded: boolean;
+} | {
+    readonly type: "contract:unsupported-extension";
+    readonly namespace: string;
+} | {
+    readonly type: "contract:drift";
+    readonly reason: "component-not-loaded" | "missing-member" | "event-mismatch";
+    readonly tag: string;
+    readonly member?: string;
+    /** event-mismatch のとき: sidecar 宣言 event / live event。 */
+    readonly sidecarEvent?: string;
+    readonly liveEvent?: string;
+};
+/** contract analyzer(Phase 5b)が生成しうる event だけの狭い union(公開 API の戻り型)。 */
+type ContractEvent = Extract<DevtoolsEvent, {
+    readonly type: "contract:manifest-read" | "contract:unsupported-extension" | "contract:drift";
+}>;
+
+/**
+ * contract/types.ts
+ *
+ * Phase 5b(dev-time contract analyzer)が読む sidecar manifest の最小 subset。
+ * 完全な JSON-Schema subset 検証は CI 側(vscode-wcs の validator core)の責務であり、
+ * runtime analyzer は「実際に読み込まれた wcBindable 宣言との drift」照合に絞る。
+ *
+ * この型は vscode-wcs の `wcstack.types` を copy-distribution したもの(§14: ランタイム
+ * 依存を導入しない)。CI 側の全量型ではなく drift 照合に必要な形だけを持つ。
+ */
+interface IContractObservable {
+    readonly event?: string;
+}
+interface IContractComponent {
+    readonly observables?: Readonly<Record<string, IContractObservable>>;
+    readonly inputs?: Readonly<Record<string, unknown>>;
+    readonly commands?: Readonly<Record<string, unknown>>;
+}
+interface IContractManifest {
+    readonly manifestExtensions?: {
+        readonly "wcstack.types"?: {
+            readonly components?: Readonly<Record<string, IContractComponent>>;
+        };
+        readonly [namespace: string]: unknown;
+    };
+}
+
+/**
+ * contract/contractAnalyzer.ts
+ *
+ * Phase 5b(09-remediation-design.md §5b / §7.1 dev runtime / §6 contract trace)の
+ * opt-in dev-time analyzer。実際に登録済みの custom element の `static wcBindable`
+ * 宣言(= 実行時の正本)を、利用者が渡した sidecar manifest と突き合わせ、drift を
+ * DevTools trace(`contract:*`)へ流す。
+ *
+ * 完了条件「無効時の runtime 挙動・cost が不変」: `analyzeContract` は
+ * `config.enableContractAnalyzer` が false のとき即 return し、manifest を一切走査
+ * しない(hot path には一切フックしない — 純粋な on-demand API)。
+ *
+ * pure な core(`analyzeManifestContract`)は宣言解決と emit を注入で受けるためテスト可能。
+ */
+
+/**
+ * opt-in dev-time contract analysis。無効時はゼロコスト(即 return・manifest 非走査)。
+ * 有効時は live 宣言と manifest を突き合わせ、`contract:*` trace を返しつつ、DevTools
+ * sink が接続されていれば同時に流す。
+ */
+declare function analyzeContract(manifest: IContractManifest): readonly ContractEvent[];
+
+export { Ssr, VERSION, WCS_MANIFEST_VERSION, analyzeContract, bootstrapState, buildBindings, builtinFilterMeta, defineState, getBindingsReady, getConfig, getWcsManifest };
+export type { ContractEvent, FilterArgType, FilterResultType, IContractManifest, IFilterMeta, ISsrElement, IWcsManifest, IWritableConfig, IWritableTagNames, WcsPathValue, WcsPaths, WcsStateApi, WcsThis };