@wcstack/state 1.26.0 → 1.27.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;
@@ -740,6 +752,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";