mandelbrot/README.md

# Mandelbrot Deep Zoom v24.1.3 — WebGPU

v23のCPU/WASM deep pixel rendererを撤去し、画素計算・field・彩色・再投影・高解像度ExportをWebGPUへ移した版です。

## 数値構成

- ViewState: BigInt固定小数点。深度に応じてbit数を自動拡張。
- Shallow: WebGPU `f32` direct iteration。f32座標分解能に十分な余裕があるviewだけで使用。
- Deep reference: 専用WorkerでBigInt固定小数点orbitを1本生成。referenceはview精度より64 bit高く生成し、さらに+64 bitのguard orbitでcheckpoint照合。
- Deep pixels: WebGPU `guarded rescaled f32 perturbation`。spanはmantissa + exponentへ分離し、`1e-400`級でもpixel offsetをf32 absolute値へ潰さない。
- Error handling: roundoff上界がescape/bounded判定へ影響し得るpixelは `FIELD_UNKNOWN` にする。UNKNOWNを内部点へ偽装しない。
- BLA: **productionでは無効・未搭載**。旧f32量子化BLAで境界pixelのmembership反転を再現したため、再導入していない。

旧v23の`Validated direct`は削除しています。v24.1.3のStrictは誤差許容閾値を厳しくする保守的GPU policyで、任意精度direct全画素証明ではありません。PNG sidecarは常に `membershipCertified:false` です。

## 描画パイプライン

通常表示ではfieldをGPUに保持します。

```text
BigInt ViewState
  └─ deep時: BigInt reference Worker
        ↓
WebGPU direct / guarded perturbation
        ↓
fieldMeta + fieldSmooth GPU buffers
        ↓
GPU color / optional boundary smoothing
        ↓
offscreen texture
        ↓
GPU reprojection / canvas
```

パレット・cycle・shift・HQ変更は数値fieldを再計算せずrecolorします。pan / wheel / pinch操作中は直前frameをGPUで再投影し、settle後に新しい数値frameを計算します。

## Export

高解像度PNGは最大辺16,384 pxです。

- 512×512以下のGPU tileで計算。
- Export用GPU buffers/textures/readback bufferは固定workspaceを再利用し、tileごとの大量生成を避ける。
- 2×2 AAは4 sampleをGPUで計算し、GPUでlinear-light resolveした後、tileにつき1回だけreadback。
- 全画像Canvasを確保せず、scanline bandを`CompressionStream('deflate')`へ送りPNGを構築。
- sidecar JSONへ`unresolvedSamples`を記録。

`unresolvedSamples > 0`は、数値policyがそのsampleを安全に分類できなかったことを意味します。

## WebGPU unavailable

WebGPUが利用できない場合は浅部のみJavaScript f64 fallbackを使います。deep zoomは誤画像を出さず、「このズーム深度はWebGPUが必要です」と表示します。

WebGPU自体が存在しない場合だけ軽量な浅部JavaScript fallbackを使います。**WGSL/shader/pipeline初期化エラー時はCPU全画面fallbackへ自動移行しません**。エラーを表示して停止し、shader不具合を隠したままCPUを占有しない設計です。`webgpu` canvas contextはpipeline作成成功後に取得します。high-performance adapterが得られない場合は通常のadapter requestも再試行します。

## v24.1.3 hotfix

実ブラウザで発覚したWGSL parse errorを修正しました。WGSL 16.2で予約されている`meta` / `smooth`をstorage-buffer変数名に使っていたため、`fieldMeta` / `fieldSmooth`へ変更しています。全shaderをWGSL reserved-word一覧へ照合するNode gate `tests/v24-wgsl-reserved.mjs`も追加しました。

表示負荷も見直し、標準モードのscreen pixel budgetをdesktop約1.5M / 小型端末約0.75Mへ縮小しました（旧版は約4M / 2M）。省電力は約0.5M、精細は最大約3M、Strictは最大約2Mです。WebGPU非対応時のCPU fallbackは約0.25M pixelに制限します。

## Standalone

`index.html`, `gpu-kernels.js`, `script.js`の3ファイルで動作します。外部WGSL fetchはありません。

```text
index.html
gpu-kernels.js
script.js
```

ブラウザが`file://`上でWebGPUを許可しない構成ではlocalhost/HTTPSで開いてください。

## Test

```bash
npm test
npm run build
```

`npm test`は以下を検査します。

- JS syntax / source contracts
- WGSL reserved-word token audit (`meta`, `smooth`, `ref`等を含む仕様予約語)
- 旧C/WASM deep assetがproduction treeに残っていないこと
- BigInt reference Worker + guard checkpoints
- shallow f32 CPU model vs BigInt oracle
- guarded perturbation CPU f32 model vs BigInt oracle
- `swirly-seahorses-z12`高密度回帰と既知3反例
- BLAがproductionから除去されていること
- tile/pixel geometry
- `1e-400` / `1e-1000` coordinate formatting
- streaming PNG structure / CRC / inflate / abort
- real-WebGPU acceptance harnessのJS syntax

### 実GPU acceptance

`tests/webgpu-acceptance.html`をWebGPU対応browserで開きます。これは実adapter上でshader compile / compute / readbackを行い、BigInt oracleと比較します。

必須gate:

- stable corpus scene: sampled `UNKNOWN = 0`
- swirly scene: 25 sample中12以上を確定
- `falseEscaped = 0`
- `falseBounded = 0`
- reference guard mismatch = 0
- 既知dense反例で誤分類しない
- 1× / 2×2 Export smokeの未確定sample = 0
- uncaptured WebGPU validation error = 0

このリポジトリを生成した実行環境では`navigator.gpu`が公開されなかったため、実adapter gateだけは未実行です。静的/CPU-model gateの代替ではありません。