slim

docs/README.md

@@ -0,0 +1,117 @@
+# Mandelbrot Deep Zoom v24.2.26
+
+## 目的
+
+v24.2.23〜v24.2.24 系で発生した「品質低下・速度低下」を撤回し、**v24.2.18 の一次描画を基準線として復元**した版です。
+
+この版の合格条件は次の4点です。
+
+1. 一次表示は v24.2.18 より遅くしない。
+2. 補足精密化を停止しても v24.2.18 より品質を下げない。
+3. 通常描画ループで fieldMeta 全体を GPU→CPU readback しない。
+4. 黒い `INTERIOR_LIKELY` の追加判定は一次表示後・アイドル時だけ行う。
+
+## 一次描画
+
+一次描画の以下のWGSLは v24.2.18 と **SHA-256まで一致**しています。
+
+- `DIRECT_F32_WGSL`
+- `FAST_PERTURB_WGSL`
+- `DEEP_PERTURB_WGSL`
+- `COLOR_WGSL`
+
+`maxIter()` も v24.2.18 と同じです。
+
+```text
+baseIter + floor(70*sqrt(zoomExp) + 15*zoomExp)
+```
+
+1920×1080 / 標準負荷の代表条件では内部描画は約 1672×941 = 1,573,352 px です。
+
+| zoom | 一次 iter | 一次描画の最悪 sample-iterations |
+|---:|---:|---:|
+| 10^6 | 611 | 0.961 B |
+| 10^8 | 667 | 1.049 B |
+| 10^12 | 772 | 1.215 B |
+| 10^20 | 963 | 1.515 B |
+
+これは v24.2.18 と同じ計算量です。補足精密化用WGSLも起動時にはコンパイルせず、一次描画完了から320ms後に初めて遅延コンパイルします。
+
+## アイドル補足精密化
+
+一次描画後にだけ `FIELD_INTERIOR_LIKELY` を追加判定します。
+
+### GPU-only queue
+
+全 `fieldMeta` をCPUへ戻しません。GPU上で候補インデックスqueueを作り、CPUへ戻すのは **16 byte のqueue統計だけ**です。
+
+候補は次のように絞ります。
+
+- stage 1: 境界近傍 + 4px間隔 seed
+- stage 2: 境界近傍 + 8px間隔 seed
+- stage 3: 境界近傍 + 16px間隔 seed
+
+境界判定は各候補につき最大8点だけ参照します。広い真内部を毎回全面再計算する方式にはしていません。1920×1080/標準の代表内部解像度では、純粋な疎seedだけなら stage 1/2/3 はそれぞれ約98,648 / 24,662 / 6,195画素です。10^8 の場合、疎seed部分の合計は約0.220B sample-iterationsで、一次描画最悪値約1.049Bの約21%です。境界画素はこれに追加されますが、batch上限と休止でGPU占有を制限します。
+
+### 数値エンジン
+
+高速モードの一次表示は従来のFast経路ですが、**アイドル精密化は高速モードでも guarded Deep を使用**します。精密化用reference bufferは通常描画の `deepCtx / fastCtx` と分離しているため、精密化後もv24.2.18のpan reference再利用を壊しません。
+
+これにより、一次描画で `INTERIOR_LIKELY` だった点だけを保守的に再評価します。精密化シェーダーは実行直前にも対象がまだ `INTERIOR_LIKELY` か確認するため、既存の `ESCAPED` / `INTERIOR_PROVEN` を上書きしません。
+
+### 反復ターゲット
+
+標準モードでは概ね次の3段階です。
+
+| zoom | 一次 | stage 1 | stage 2 | stage 3 |
+|---:|---:|---:|---:|---:|
+| 10^6 | 611 | 1222 | 2444 | 3000 |
+| 10^8 | 667 | 1334 | 2668 | 3600 |
+| 10^12 | 772 | 1544 | 3088 | 4800 |
+| 10^20 | 963 | 1926 | 3852 | 7200 |
+
+### 1 GPU batch の上限
+
+標準モードの補足精密化は **1.8 million sample-iterations / batch 以下**に丸めます。
+
+例: `10^8`
+
+- 1334 iter: 1344 pixels / batch → 1,792,896 sample-iterations
+- 2668 iter: 640 pixels / batch → 1,707,520
+- 3600 iter: 448 pixels / batch → 1,612,800
+
+ユーザー操作が入ると `state.token` が変わり、次batchへ進む前に中断します。また一定時間ごとにGPUを休ませます。
+
+## 品質の単調性
+
+補足精密化前の画像は v24.2.18 と同じです。
+
+精密化は `FIELD_INTERIOR_LIKELY` のみを対象とし、既に確定した画素には触れません。さらに再着色時も一次描画の `baseIter` を色周期正規化に使うため、精密化によって既存の外部色が一斉に変化することを避けています。
+
+## 色操作
+
+v24.2.18 のズーム相対色周期と対数スライダーを維持しています。`色を自動変化` の速度のみ、要求どおり v24.2.18 の **1/10** にしています。
+
+## fallback
+
+JavaScript fallback は v24.2.18 と SHA-256一致です。疑似等高線・縞模様は追加していません。
+
+## 検査
+
+```bash
+npm test
+npm run build
+```
+
+`tests/v24-baseline-idle-refinement-model.mjs` が以下を検査します。
+
+- 一次WGSL 4本の v24.2.18 SHA-256一致
+- fallback の v24.2.18 SHA-256一致
+- `maxIter()` の基準線維持
+- 精密化WGSLの遅延コンパイル
+- 全meta readback不使用
+- 16 byte queue統計readback
+- 既存確定画素を上書きしない契約
+- 各倍率で1batchが予算を超えないこと
+
+実GPUのfpsやdevice-lost有無は、このコンテナでWebGPUが初期化できない場合は保証できません。静的・CPUモデル結果と実機測定は区別します。