@wcstack/devtools 2.6.1 → 3.1.0

package/dist/index.d.ts

@@ -95,6 +95,24 @@ interface IMountOverlaySummaryLike {
     /** マーカーパスに載る getter のキー */
     readonly getterKeys: readonly string[];
 }
+/**
+ * 鍵付き購読（`$eq` / `$eqPath` / `$eqIndex`）の path 1 つ分の要約（keyedSubscriptions の要素 —
+ * protocol v2 追補・要件 D17）。取り出した時点の数え。
+ */
+interface IKeyedSubscriptionSummaryLike {
+    /** `$eq` 系の第 1 引数（選択を持つパス） */
+    readonly path: string;
+    /** path が getter 由来で鍵付きで購読できず、追跡付きの読みに落ちた（変わるたびに読む getter が全部再評価される） */
+    readonly tracked: boolean;
+    /** 行ごとの購読の数 */
+    readonly rows: number;
+    /** 行ごとの購読が使っている鍵の数 */
+    readonly keys: number;
+    /** `$eqIndex` の最内段のリスト単位の監視の数 */
+    readonly lists: number;
+    /** path の最後に見た値（見ていなければ undefined）。生値 */
+    readonly lastValue: unknown;
+}
 /**
  * 宣言レベルのバインディング 1 件（getDeclaredBindings の要素・protocol v1 追補）。
  * ランタイム正本パーサの結果が構造的に流れる。宣言タプルで dedupe 済みの
@@ -232,6 +250,12 @@ interface IDevtoolsSourceLike {
      * v2 より前のランタイムには無いため、無ければ UI はセクションごと出さない。
      */
     overlays?(rootNode: Node): IMountOverlaySummaryLike[];
+    /**
+     * protocol v2 追補 API（optional 扱いで呼ぶ・要件 D17）。rootNode のツリーの鍵付き購読の
+     * path ごとの要約。`$eq` 系が一度も評価されていなければ空配列。3.0 より前の state には無いため、
+     * 無ければ UI はセクションごと出さない。
+     */
+    keyedSubscriptions?(rootNode: Node): IKeyedSubscriptionSummaryLike[];
     read(rootNode: Node, path: string, indexes?: number[]): unknown;
     write(rootNode: Node, path: string, value: unknown, indexes?: number[]): void;
     /**
@@ -405,6 +429,11 @@ declare class DevtoolsCore {
      * 出さない（後方互換）。マウントが無いツリーは空配列。
      */
     overlaysOf(entry: IRosterEntry): IMountOverlaySummaryLike[] | null;
+    /**
+     * roster entry のツリーの鍵付き購読（keyedSubscriptions — protocol v2 追補・要件 D17）。
+     * 実装しないランタイム（3.0 より前の state）では null — UI はセクションごと出さない。
+     */
+    keyedSubscriptionsOf(entry: IRosterEntry): IKeyedSubscriptionSummaryLike[] | null;
     readValue(entry: IRosterEntry, path: string, indexes?: number[]): unknown;
     writeValue(entry: IRosterEntry, path: string, value: unknown, indexes?: number[]): void;
     private _notify;
@@ -484,6 +513,17 @@ declare class WcsDevtools extends HTMLElement {
     private _rosterKey;
     private _selectedRoster;
     private _renderStatePane;
+    /**
+     * 選択ツリーの鍵付き購読セクション（keyedSubscriptions — protocol v2 追補・要件 D17）。
+     * `$eq` / `$eqPath` / `$eqIndex` の購読は依存グラフの動的な変化で、上の状態ツリーにも
+     * Wiring の台帳にも現れない。path ごとに購読の数と最後の値を出し、getter 由来の path で
+     * 追跡付きの読みに落ちたもの（変わるたびに読む getter が全部再評価される）を warn で目立たせる。
+     * 未提供の旧ランタイム（null）と `$eq` 系が一度も評価されていないツリー（空配列）では出さない。
+     * pull の時機は Overlays と同じく State ペインの再描画に乗る。
+     */
+    private _renderKeyedSection;
+    /** 鍵付き購読 1 path の描画（path・購読の数・最後の値、または追跡付きへの落ち）。 */
+    private _keyedRow;
     /**
      * 選択ツリーのマウント記録セクション（overlays — protocol v2・D20 の可視化）。
      * マウントの私有キー・getter はオーバーレイ専用アドレス空間（マーカー `#m<id>`）に

package/dist/index.esm.js

@@ -561,6 +561,17 @@ class DevtoolsCore {
         }
         return source.overlays(entry.rootNode);
     }
+    /**
+     * roster entry のツリーの鍵付き購読（keyedSubscriptions — protocol v2 追補・要件 D17）。
+     * 実装しないランタイム（3.0 より前の state）では null — UI はセクションごと出さない。
+     */
+    keyedSubscriptionsOf(entry) {
+        const source = this._sources.get(entry.sourceId);
+        if (source === undefined || typeof source.keyedSubscriptions !== "function") {
+            return null;
+        }
+        return source.keyedSubscriptions(entry.rootNode);
+    }
     readValue(entry, path, indexes) {
         const source = this._sources.get(entry.sourceId);
         if (source === undefined) {
@@ -1131,6 +1142,9 @@ header .spacer { flex: 1; }
 .overlay-row .prop { color: #b7f0c0; }
 .overlay-row .path { color: #9fd0ff; }
 .overlay-row .detail { color: #6f88a3; }
+.keyed-row { padding: 1px 0; white-space: nowrap; }
+.keyed-row .path { color: #9fd0ff; }
+.keyed-row .detail { color: #6f88a3; }
 .wiring-tabs { padding: 0 0 4px; }
 .wiring-tabs button { font: inherit; cursor: pointer; margin-right: 4px; opacity: 0.6; }
 .wiring-tabs button.active { opacity: 1; font-weight: bold; }
@@ -1514,12 +1528,67 @@ class WcsDevtools extends HTMLElement {
             body.append(this._emptyRow("no readable keys (runtime without keys() API?)"));
             // keys が読めないランタイムでも overlays は独立に読める可能性があるため出す
             this._renderOverlaysSection(body, selected);
+            this._renderKeyedSection(body, selected);
             return;
         }
         for (const key of keys) {
             this._renderTreeNode(body, selected, { path: key, indexes: [] }, key, 0);
         }
         this._renderOverlaysSection(body, selected);
+        this._renderKeyedSection(body, selected);
+    }
+    /**
+     * 選択ツリーの鍵付き購読セクション（keyedSubscriptions — protocol v2 追補・要件 D17）。
+     * `$eq` / `$eqPath` / `$eqIndex` の購読は依存グラフの動的な変化で、上の状態ツリーにも
+     * Wiring の台帳にも現れない。path ごとに購読の数と最後の値を出し、getter 由来の path で
+     * 追跡付きの読みに落ちたもの（変わるたびに読む getter が全部再評価される）を warn で目立たせる。
+     * 未提供の旧ランタイム（null）と `$eq` 系が一度も評価されていないツリー（空配列）では出さない。
+     * pull の時機は Overlays と同じく State ペインの再描画に乗る。
+     */
+    _renderKeyedSection(body, entry) {
+        const summaries = this._core.keyedSubscriptionsOf(entry);
+        if (summaries === null || summaries.length === 0) {
+            return;
+        }
+        const heading = document.createElement("h3");
+        heading.className = "overlays-heading";
+        heading.textContent = `Keyed selection (${summaries.length} path${summaries.length === 1 ? "" : "s"})`;
+        body.append(heading);
+        for (const summary of summaries) {
+            body.append(this._keyedRow(summary));
+        }
+    }
+    /** 鍵付き購読 1 path の描画（path・購読の数・最後の値、または追跡付きへの落ち）。 */
+    _keyedRow(summary) {
+        const row = document.createElement("div");
+        row.className = "keyed-row";
+        const path = document.createElement("span");
+        path.className = "path";
+        path.textContent = summary.path;
+        row.append(path);
+        if (summary.tracked) {
+            const badge = document.createElement("span");
+            badge.className = "badge-tag warn";
+            badge.textContent = "tracked";
+            badge.title = "the path is a getter or under one, so $eq cannot subscribe by key: every getter that reads it re-evaluates when it changes";
+            row.append(document.createTextNode(" "), badge);
+        }
+        const details = [];
+        // 空になった鍵は台帳から消えるので、鍵があれば行もある
+        if (summary.rows > 0) {
+            details.push(`rows ${summary.rows} · keys ${summary.keys}`);
+        }
+        if (summary.lists > 0) {
+            details.push(`list watchers ${summary.lists}`);
+        }
+        if (!summary.tracked) {
+            details.push(`last ${formatValue(summary.lastValue, 1)}`);
+        }
+        const detail = document.createElement("span");
+        detail.className = "detail";
+        detail.textContent = details.length > 0 ? ` ${details.join(" · ")}` : "";
+        row.append(detail);
+        return row;
     }
     /**
      * 選択ツリーのマウント記録セクション（overlays — protocol v2・D20 の可視化）。