@wcstack/state 1.21.5 → 1.21.7

package/README.ja.md

@@ -867,6 +867,7 @@ export default {
 | `this.$resolve(path, indexes, value?)` | ワイルドカードパスを特定のインデックスで解決 |
 | `this.$postUpdate(path)` | 指定パスの更新通知を手動で発行 |
 | `this.$trackDependency(path)` | キャッシュ無効化のための依存関係を手動で登録 |
+| `this.$untrackDependency(fn)` | fn 実行中の依存追跡を抑止して値を読む（`$trackDependency` と対称） |
 | `this.$stateElement` | `IStateElement` インスタンスへのアクセス |
 | `this.$1`, `this.$2`, ... | 現在のループインデックス（1始まりの命名、0始まりの値） |
 
@@ -1831,6 +1832,47 @@ buildBindings(root)
 - **StateAddress** — PathInfo + ListIndex の組み合わせ
 - **AbsoluteStateAddress** — 状態名 + StateAddress（クロス状態参照用）
 
+## パフォーマンス
+
+リポジトリ同梱の [js-framework-benchmark](https://github.com/krausest/js-framework-benchmark) 流
+ドライバ（`e2e/bench/jsfb-verify.mjs`・`e2e/bench/memory-profile.mjs`）で、標準の
+1,000 / 10,000 行テーブルページを計測（headless Chromium・中央値・両実装を同一
+セッションで連続実行）。`@wcstack/state` は公式の keyed 判定に合格しつつ、行 DOM
+を上限 1,000 行の有界プールでリサイクルします。
+
+| 所要時間（ms・中央値） | `@wcstack/state` | [`@wcstack/signals`](../signals/) |
+|---|---|---|
+| 1,000 行の生成 | 25.2 | 9.5 |
+| 1,000 行の全置換 | 18.8 | 12.5 |
+| 10,000 行の 10 行ごと更新 | 11.4 | 4.7 |
+| 行の選択 | 0.1 | 0.4 |
+| 2 行の入れ替え | 0.9 | 0.4 |
+| 行の削除 | 2.8 | 0.6 |
+| 10,000 行への 1,000 行追加 | 48.6 | 14.2 |
+| 10,000 行のクリア | 54.6 | 52.2 |
+
+| 強制 GC 後のヒープ（MB） | `@wcstack/state` | `@wcstack/signals` |
+|---|---|---|
+| ページ表示直後 | 1.0 | 0.6 |
+| 1,000 行生成後 | 5.6 | 3.5 |
+| 1,000 行×5 回置換後 | 6.4 | 3.7 |
+| 10,000 行生成後 | 35.1 | 18.0 |
+| 10,000 行生成 + クリア後 | 13.2 | 1.9 |
+
+正直な読み方：
+
+- 対話系の操作（選択 / 入れ替え / 削除）は数ミリ秒以下で、巨大リストのクリアは
+  signals 実装と同等です。
+- 行の生成・追加は `@wcstack/signals` の約 2.5〜3.5 倍のコストです。これは本
+  パッケージが行ごとに構築する宣言的バインディング台帳の対価で、`data-wcs` の
+  検査・DevTools の配線表示・SSR ハイドレーションを支えているのは同じ台帳です。
+  両パッケージは相互運用できるため、ホットなリストだけ signals の `For` で描画
+  し、残りのページは宣言的なまま保てます。
+- クリア後に残るヒープは、次のリスト生成を安くする有界の行プールです。
+
+絶対値は 1 台の開発機での計測です（v1.21.6 + PR#87 の clear リーク修正）。
+`e2e/bench/` のドライバで手元のハードウェアでも再現できます。
+
 ## サーバーサイドレンダリング
 
 `@wcstack/state` は [`@wcstack/server`](../server/) パッケージと連携して SSR をサポートしています。クライアント用に書いたテンプレートがそのままサーバーでレンダリングされます — 変更不要。

package/README.md

@@ -867,6 +867,7 @@ Inside state objects (getters / methods), the following APIs are available via `
 | `this.$resolve(path, indexes, value?)` | Resolve a wildcard path with specific indexes |
 | `this.$postUpdate(path)` | Manually trigger update notification for a path |
 | `this.$trackDependency(path)` | Manually register a dependency for cache invalidation |
+| `this.$untrackDependency(fn)` | Read values inside fn without registering dependencies (symmetric to `$trackDependency`) |
 | `this.$command.<name>` | Access a `CommandToken` declared in `$commandTokens` (see [Command Token](#command-token-method-binding)) |
 | `this.$stateElement` | Access to the `IStateElement` instance |
 | `this.$1`, `this.$2`, ... | Current loop index (1-based naming, 0-based value) |
@@ -1833,6 +1834,50 @@ Paths like `users.*.name` are decomposed into:
 - **StateAddress** — combination of PathInfo + ListIndex
 - **AbsoluteStateAddress** — state name + StateAddress (for cross-state references)
 
+## Performance
+
+Measured with the repository's [js-framework-benchmark](https://github.com/krausest/js-framework-benchmark)-style
+drivers (`e2e/bench/jsfb-verify.mjs`, `e2e/bench/memory-profile.mjs`) against the
+standard 1,000 / 10,000-row table page — headless Chromium, medians, both
+implementations measured back-to-back in the same session. `@wcstack/state`
+passes the official keyed-mode classification while recycling row DOM through a
+bounded pool (up to 1,000 rows).
+
+| Duration (ms, median) | `@wcstack/state` | [`@wcstack/signals`](../signals/) |
+|---|---|---|
+| create 1,000 rows | 25.2 | 9.5 |
+| replace all 1,000 rows | 18.8 | 12.5 |
+| update every 10th of 10,000 | 11.4 | 4.7 |
+| select row | 0.1 | 0.4 |
+| swap 2 rows | 0.9 | 0.4 |
+| remove row | 2.8 | 0.6 |
+| append 1,000 to 10,000 | 48.6 | 14.2 |
+| clear 10,000 rows | 54.6 | 52.2 |
+
+| Heap after forced GC (MB) | `@wcstack/state` | `@wcstack/signals` |
+|---|---|---|
+| page ready | 1.0 | 0.6 |
+| after create 1,000 | 5.6 | 3.5 |
+| after 5× replace 1,000 | 6.4 | 3.7 |
+| after create 10,000 | 35.1 | 18.0 |
+| after create 10,000 + clear | 13.2 | 1.9 |
+
+How to read this, honestly:
+
+- Interactive operations (select / swap / remove) run in a few milliseconds or
+  less, and clearing a huge list matches the signals implementation.
+- Creating and appending rows costs ~2.5–3.5× `@wcstack/signals`. That is the
+  price of the declarative binding ledger this package builds per row — the same
+  ledger that powers `data-wcs` inspection, DevTools wiring, and SSR hydration.
+  The two packages interoperate, so a hot list can be rendered with signals'
+  `For` while the rest of the page stays declarative.
+- The heap retained after a clear is the bounded row pool that makes the next
+  list population cheap.
+
+Absolute numbers are from one development machine (v1.21.6 + the clear-leak fix
+in PR#87); the drivers in `e2e/bench/` reproduce the comparison on your own
+hardware.
+
 ## Server-Side Rendering
 
 `@wcstack/state` supports SSR via the companion [`@wcstack/server`](../server/) package. The same templates you write for the client render on the server — no changes needed.

package/dist/index.d.ts

@@ -440,6 +440,13 @@ interface WcsStateApi {
      * computed getter 内で動的にパスを組み立てる場合に使用。
      */
     $trackDependency(path: string): void;
+    /**
+     * コールバック実行中の依存追跡（動的依存・`$1` インデックス依存の登録）を
+     * 抑止して fn を実行し、その戻り値を返す（`$trackDependency` と対称）。
+     * リスト行 getter が「行外の単一値」を読みたいが、その値の変更で全行を
+     * 再評価させたくない場合に使う（該当行へ直接書き込む設計と組で用いる）。
+     */
+    $untrackDependency<T>(fn: () => T): T;
     /** `<wcs-state>` 要素への参照 */
     readonly $stateElement: HTMLElement;
     /**