@wcstack/state 1.26.0 → 1.28.0

package/dist/index.d.ts

@@ -140,6 +140,18 @@ interface IStateElement {
      * optional なのはテスト用モック互換のため（undefined は「宣言なし」扱い）。
      */
     readonly listKeys?: ListKeyMap | null;
+    /**
+     * `$watch` 宣言から生成した監視対象パスの集合。
+     * 宣言が無ければ null / undefined で、setByAddress の旧値キャプチャには一切入らない
+     * （docs/state-watch-hook-design.md §10 のゼロコスト契約）。
+     * optional なのはテスト用モック互換のため（undefined は「宣言なし」扱い）。
+     */
+    readonly watchPaths?: ReadonlySet<string> | null;
+    /**
+     * パスを依存グラフへ登録する。DOM バインディング登録（BindingSession）のほか、
+     * `$watch` 宣言（processWatchDeclaration）からも呼ばれる — 静的依存グラフに
+     * 載るのがバインド済みパスだけだと headless 購読が成立しないため（設計書 §8）。
+     */
     setPathInfo(path: string, bindingType: BindingType): void;
     addStaticDependency(parentPath: string, childPath: string): boolean;
     addDynamicDependency(fromPath: string, toPath: string): boolean;
@@ -214,7 +226,12 @@ interface IFilterInfo {
     readonly args: string[];
     readonly filterFn: FilterFn;
 }
-interface IBindingInfo {
+/**
+ * バインディング式のパース結果（DOM 非依存の部分）。`@wcstack/state/parser` の
+ * ParseBindTextResult がこれをそのまま公開するため、Node 等の DOM lib 型を
+ * ここに足してはならない（足すなら IBindingInfo 側へ）。
+ */
+interface IParsedBinding {
     readonly propName: string;
     readonly propSegments: string[];
     readonly propModifiers: string[];
@@ -223,11 +240,13 @@ interface IBindingInfo {
     readonly stateName: string;
     readonly inFilters: IFilterInfo[];
     readonly outFilters: IFilterInfo[];
-    readonly node: Node;
-    readonly replaceNode: Node;
     readonly bindingType: BindingType;
     readonly uuid?: string | null;
 }
+interface IBindingInfo extends IParsedBinding {
+    readonly node: Node;
+    readonly replaceNode: Node;
+}
 
 interface IState {
     [key: string]: any;
@@ -679,6 +698,41 @@ interface IWcsManifest {
         };
         /** 構造ディレクティブ（`<template data-wcs="for: ...">` 等） */
         structuralDirectives: readonly string[];
+        /**
+         * 修飾子（`#` 後）の語彙。flags は値を取らない形（`#prevent`）、keyValue は
+         * `=` で値を取る形（`#init=element`）、eventNamePrefix は `on` + イベント名の形
+         * （`#onchange` — two-way / radio / checkbox のイベント名上書き。README「Modifiers」）。
+         * define.ts の定数が単一正本で、ランタイムの消費箇所も同じ定数に分岐する。
+         */
+        modifiers: {
+            flags: readonly string[];
+            keyValue: readonly string[];
+            eventNamePrefix: string;
+        };
+        /** リストインデックス参照名（`$1`..`$N`）。prefix + 1 始まり連番、maxDepth まで。 */
+        indexParam: {
+            prefix: string;
+            maxDepth: number;
+        };
+        /**
+         * bindingType 判別の語彙（parseBindTextsForElement の分岐と同一の定数から導出）。
+         * 判別順: else → spread → 構造ディレクティブ/radio/checkbox → eventToken・`on*`
+         * （event）→ prop。propNamespaces は左辺先頭セグメントの特殊 namespace で、
+         * apply 層のディスパッチキー集合との一致はテストが強制する。
+         * 既知の未収載: `radio` / `checkbox`（BindingType union のみが正本）。
+         */
+        bindingTypes: {
+            elseKeyword: string;
+            spread: string;
+            eventPropertyPrefix: string;
+            propNamespaces: {
+                eventToken: string;
+                command: string;
+                class: string;
+                attr: string;
+                style: string;
+            };
+        };
     };
     /** 組み込みフィルタ名（builtinFilters から自動導出＝実装が正本） */
     filters: string[];
@@ -740,6 +794,19 @@ type DevtoolsEvent = {
     readonly tokenName: string;
     readonly args: readonly unknown[];
     readonly subscriberCount: number;
+} | {
+    readonly type: "state:watch-error";
+    /** throw 元。cur の評価（getter）とハンドラ本体では原因も直し方も違う */
+    readonly phase: "prime" | "evaluate" | "handler";
+    readonly stateName: string;
+    /** `$watch` の宣言キー（ワイルドカードを含む生のパス） */
+    readonly path: string;
+    readonly error: unknown;
+} | {
+    readonly type: "state:watch-chain-limit";
+    readonly maxDepth: number;
+    /** 打ち切ったバッチに載っていたアドレスのパス（報告用） */
+    readonly paths: readonly string[];
 } | {
     readonly type: "propagation:suppressed";
     readonly reason: "confirmation" | "visited-edge";