# @three-blocks/devtools

## 13.0.0

### Patch Changes

- Updated dependencies [ec85229]
- Updated dependencies [ec85229]
- Updated dependencies [ec85229]
- Updated dependencies [ec85229]
- Updated dependencies [ec85229]
  - three-blocks@0.14.0

## 12.0.0

### Major Changes

- c5cca15: Devtools: The shader watch command, the 186dev Three.js lane and Playwright driver names are gone.

  Removed from `@three-blocks/devtools`: `three-blocks shaders watch`, `watchShaders`, `ShaderWatchQueue` and
  their option types (captures are release artifacts, never edit-loop validation); and
  `createPlaywrightShaderDriver`, `createStaticPlaywrightShaderDriver`,
  `createAttachedPlaywrightShaderDriver` with their `Playwright*` option types — `createShaderDriver()` and
  `ShaderDriverOptions` take the same `serve` / `base` / `url` options, and capture has been Node-native for a release.

  Removed from `three-blocks/shaders`: the pre-release `186dev` lane (`assertThreeWebGPU186Dev`,
  `createThreeWebGPU186DevShaderCompatibility`, `THREE_R186DEV_VERSION`,
  `THREE_WEBGPU_R186DEV_COMPATIBILITY`) and `THREE_BLOCKS_THREE_186DEV_HOOK_TRANSFORM_VERSION` from
  `three-blocks/vite`. Released Three.js 0.186.x is the supported revision and 0.185.x
  stays frozen for one release.

### Minor Changes

- c5cca15: CLI: One check command verifies types, the production build and every scene, with a PNG per scene.

  `npx three-blocks check [--json]` (devtools `runProjectCheck()`) runs the project's own TypeScript, builds
  the production bundle once in `strict` mode (which captures its shaders), and boots every configured
  scene natively in Node. Each route reports its lifecycle, console and page errors, the reported shader
  mode with `injected` / `missed` / `live` counters, and a PNG of its settled frame under
  `.three-blocks/check/`. `BrowserPreviewOptions.screenshots` and `BrowserPreviewRouteReport.shaders` /
  `.screenshot` expose the same to `three-blocks browser preview`. Generated projects gain a `check`
  script and ignore `.three-blocks/check/`.

- c5cca15: Library: Vite builds capture precompiled shaders from the built bundle; nothing to commit.

  When no fresh committed capture exists and `@three-blocks/devtools` is installed, `vite build` loads the
  bundle it has just written natively in Node and writes
  `<outDir>/three-blocks/shaders/<scene>.<backend>.json`. `shaders: { capture: false }` opts out.
  `ThreeBlocksShaderBuildConfig.built` and `ShaderBuildState.built` carry the public path;
  `installShaderCache()` then loads the manifest from there instead of calling `loadManifest`, so
  `registerDevtools()`, the worker shell and `installShaderCache( { state: threeBlocksShaders } )` need no
  change. `InstallShaderCacheOptions.loadManifest` and `CreateWorkerRuntimeOptions.loadShaderManifest`
  become optional: without a loader the manifest is fetched from `<base>three-blocks/shaders/`
  (`InstallShaderCacheOptions.base`), which also serves a committed capture's public twin, so a build
  host without a GPU can keep a committed cache with no template code. For such a bundle `strict`
  fails the build when the capture fails, instead of stopping a stale receipt at `buildStart`; a host
  without a GPU adapter otherwise ships a correct, live-compiling output. `base` must be an absolute path.

  `captureBuiltShaders()` and `three-blocks shaders capture --serve <dir> --built [--base <path>]` run the
  same engine after any bundler's build. A production bundle no longer needs capture instrumentation:
  the shader runtime hands its renderer to the capture host the Node driver injects
  (`offerRendererToShaderCapture`), the Node renderer can run an init script inside worker threads
  (`addInitScript( { content, workers: true } )`), and the static driver injects its runtime that way.
  Capture classification no longer depends on `constructor.name`, which a minified bundle mangles, and
  the Node DOM applies the user-agent defaults for headings, bold and italic text.

- c5cca15: Starter: Add a scene by adding a folder; the build captures it and the check command boots it.

  A generated project grows by `src/scenes/<name>/scene.ts`, opened with `?scene=<name>`. The worker
  resolves it through one registry (`boot.flags.scene`, a new runtime flag relayed by the app shell),
  the shader tool enumerates the same folders, so `vite build` captures the new scene and
  `three-blocks check` boots it and writes its PNG. An unknown `?scene=` fails with the known scenes.

- c5cca15: Library: Three.js r186 is supported, and development always compiles shaders live until previewed.

  `THREE_BLOCKS_SUPPORTED_THREE_RANGE` widens to `>=0.185.0 <0.187.0` and `isSupportedThreeVersion`
  exposes the same gate to the other bundler adapters. `createThreeWebGPUShaderCompatibility` and
  `createThreeWebGLShaderCompatibility` now route to the installed release, so application code
  survives the upgrade unchanged; `createThreeShaderCompatibility` and `threeShaderCompatibilityId`
  select by backend. On an unverified Three.js revision `threeBlocks()` and the non-Vite adapters warn
  once and compile live instead of throwing; strict builds and captures still stop.

  Development always compiles TSL live, because the next edit strands any receipt: the worker shell,
  `registerDevtools()` and the `threeBlocksShaders` export (`mode: 'live'`) hydrate only on an explicit
  preview, and `ShaderBuildState.mode` lets `installShaderCache()` treat live over a fresh receipt as a
  choice (no warning, never strict). The overlay offers "Preview production shaders" / "Back to live
  TSL"; a preview whose receipt goes stale returns to live by itself, and the policy-changed full
  reload is gone. Its toggle is a plain `?tbShaders=live|precompiled` preference instead of the parity
  harness flag that froze the starter after one frame. `readThreeBlocksRuntimeFlags` parses it on the
  page, `WorkerBootState` relays it as `flags`, and `CreateWorkerRuntimeOptions` accepts it, so a
  worker-owned renderer honours the page's shader mode and its `?webgl=1` backend switch.

  Hydration no longer takes retained-input ordinals (an application that rendered before creating its
  inputs, such as `PMREMGenerator.fromScene()` ahead of `bloom()`, bound the wrong uniform); recipes
  cover r186's `highpModelViewMatrix`, `SunLight` cascades and after-object instancing. Parity
  failures now carry a state-oracle verdict (`ShaderCaptureStats.stateOracle`,
  `TestShadersOptions.stateOracle`, the optional `stateOracle` argument of `ShaderBrowserDriver.observe`).
  Receipt transform 65 strands earlier receipts: recapture.

### Patch Changes

- c5cca15: Library: Ambient occlusion loads precompiled on WebGPU instead of compiling at startup.

  Three.js r186 declares a sampler for a gathered texture (`texture.gather()`) even over a depth
  texture. GTAO reads depth that way, and the captured state addressed the view as the pass texture
  node it was cloned from, so the hydrated bind group lacked that sampler and every GTAO pass fell
  back to a live build. A gathered view now gets its own `textureReference` recipe with a `gather`
  flag, and hydration restores the sampler. Recapture to pick this up.

- c5cca15: Devtools: Interrupted captures and checks no longer leave renderer processes running.

  A Node renderer page is a forked process with its own animation loop and GPU device. When the process
  driving it died without closing it (a crash, a kill, Ctrl-C during a capture), the page kept running
  indefinitely and skewed every later timing on the machine. The page process now exits when its IPC
  channel disconnects.

- c5cca15: Devtools: Captures and checks deliver pointer and wheel input to listeners on the window.

  The Node renderer's bubble path ended at the document, so an application listening on `window`
  (the usual place for `pointermove` and `wheel`) never saw driven input, and `DOMContentLoaded`
  never reached `window` either. A bubbling event that leaves the document now reaches `window`
  with its fields and original target.

- c5cca15: Devtools: Precompiled temporal antialiasing and upscaling jitter the camera again.

  Three.js r186 keeps `OnBeforeRenderPipeline` / `OnAfterRenderPipeline` callbacks on the render
  pipeline's context, filled only while a node's `setup()` runs. TRAA, TAAU and temporal
  reprojection jitter the camera there, so a precompiled state that skipped setup rendered every
  frame unjittered and temporal antialiasing silently did nothing. Capture now marks such a scene as
  requiring setup, and binds a texture node whose value the application reassigns (history and
  ping-pong targets) through the node instead of the texture it held at capture time. Recapture to
  pick this up.

- c5cca15: Library: Ambient occlusion compiles again with antialiasing on Three.js r186.

  Three.js r186's `GTAONode` reads its centre depth with `gather()`, and WGSL has no `textureGather()`
  overload for multisampled textures, so `ao( scenePass.getTextureNode( 'depth' ), … )` on an
  `antialias: true` renderer failed to compile (it worked on r185). The r186 in-memory patch lane, shared
  by `threeBlocks()` and the webpack, Rollup, esbuild and Next.js adapters, now carries
  [three.js #34609](https://github.com/mrdoob/three.js/pull/34609) verbatim: `generateTextureGather()`
  falls back to four `textureLoad()` calls for multisampled textures. It is removed when a supported
  release contains that pull request. The lane identifier moves to `r186-provider-v2`; receipts are
  unaffected, because no shader that needed this fix could be captured before.

- Updated dependencies [53ea952]
- Updated dependencies [c5cca15]
- Updated dependencies [c5cca15]
- Updated dependencies [c5cca15]
- Updated dependencies [c5cca15]
- Updated dependencies [c5cca15]
- Updated dependencies [c5cca15]
- Updated dependencies [c5cca15]
- Updated dependencies [c5cca15]
- Updated dependencies [c5cca15]
  - three-blocks@0.13.0

## 11.1.0

### Minor Changes

- 02f3072: Devtools: Run shader captures and project checks in Node with fewer dependencies.

### Patch Changes

- Updated dependencies [02f3072]
  - three-blocks@0.12.1

## 11.0.0

### Patch Changes

- Updated dependencies [aa1d655]
- Updated dependencies [aa1d655]
- Updated dependencies [aa1d655]
- Updated dependencies [aa1d655]
- Updated dependencies [aa1d655]
- Updated dependencies [aa1d655]
  - three-blocks@0.12.0

## 10.0.0

### Patch Changes

- 88a9a83: Devtools: Shader checks bound browser startup and shutdown before the next verification.
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
- Updated dependencies [88a9a83]
  - three-blocks@0.11.0

## 9.0.0

### Patch Changes

- 9ba758a: Packages: Material environments capture reliably and transmission types expose surface distortion.
- c3506b4: Starter: New projects install compatible devtools and run status without missing dependencies.
- Updated dependencies [0c96f1c]
- Updated dependencies [9ba758a]
- Updated dependencies [9d18636]
- Updated dependencies [d91a3ba]
- Updated dependencies [c3506b4]
  - three-blocks@0.10.0

## 8.0.0

### Patch Changes

- 16993c6: Devtools: Development defers shader capture and keeps automated browser checks headless.
- Updated dependencies [16993c6]
- Updated dependencies [83e3068]
- Updated dependencies [b14d448]
  - three-blocks@0.9.0

## 7.0.0

### Patch Changes

- Updated dependencies [be95dab]
  - three-blocks@0.8.0

## 6.0.0

### Patch Changes

- Updated dependencies [5455df6]
- Updated dependencies [8e830ad]
- Updated dependencies [8e830ad]
- Updated dependencies [8e830ad]
  - three-blocks@0.7.0

## 5.0.0

### Minor Changes

- Devtools: Vite asset config and inspection handle HDR files and report exact GPU memory.

### Patch Changes

- efb3a0a: Devtools: Loading no longer spins the status chip or terminal progress indicator.
- Updated dependencies [efb3a0a]
- Updated dependencies
- Updated dependencies [efb3a0a]
  - three-blocks@0.6.0

## 4.0.0

### Minor Changes

- efb3a0a: Devtools: Asset optimization compresses models and textures and tracks reusable outputs.

### Patch Changes

- efb3a0a: Devtools: Long-running commands now show static progress instead of a spinning indicator.
- Updated dependencies [efb3a0a]
- Updated dependencies [efb3a0a]
- Updated dependencies [57aa2a0]
- Updated dependencies [efb3a0a]
  - three-blocks@0.5.0

## 3.0.0

### Patch Changes

- 073d727: Devtools: Headless shader checks ignore automatic favicon misses and allow slow screenshots.
- fd0c70f: Devtools: Development stays available when compatible shader receipts predate a version bump.
- Updated dependencies [b6c53aa]
- Updated dependencies [8036dab]
- Updated dependencies [fd0c70f]
- Updated dependencies [c9fa239]
- Updated dependencies [fd0c70f]
  - three-blocks@0.4.0

## 2.0.0

### Minor Changes

- beb026f: Packages: Shader tools now capture both backends by default and show backend tests and sizes.

### Patch Changes

- a59c7b8: Packages: Documentation now matches the shipped commands, versions, and ports.
- a59c7b8: Devtools: Shader precompilation now hydrates minified builds without preserving constructor names.
- b328fab: Packages: Precompiled shaders now preserve deterministic output across more Three.js examples.
- 0ca530e: Devtools: Shader capture now respects each scene's supported renderer backends.
- beb026f: Devtools: Precompiled indirect batches now skip redundant shader setup.
- e8e7e30: Devtools: Shader precompilation now isolates backends and replays shared texture recipes.
- beb026f: Starter: Fresh projects now avoid unstyled flashes and hydrate every captured startup shader.
- 9daa49d: Packages: Three.js 186dev now uses upstream asynchronous compute compilation.
- Updated dependencies [beb026f]
- Updated dependencies [967a0ee]
- Updated dependencies [967a0ee]
- Updated dependencies [96be509]
- Updated dependencies [96be509]
- Updated dependencies [967a0ee]
- Updated dependencies [96be509]
- Updated dependencies [96be509]
- Updated dependencies [96be509]
- Updated dependencies [967a0ee]
- Updated dependencies [96be509]
- Updated dependencies [967a0ee]
- Updated dependencies [beb026f]
- Updated dependencies [0c23333]
- Updated dependencies [e8e7e30]
- Updated dependencies [a59c7b8]
- Updated dependencies [beb026f]
- Updated dependencies [967a0ee]
- Updated dependencies [8bd64d6]
- Updated dependencies [a59c7b8]
- Updated dependencies [967a0ee]
- Updated dependencies [b328fab]
- Updated dependencies [0ca530e]
- Updated dependencies [beb026f]
- Updated dependencies [8bd64d6]
- Updated dependencies [e8e7e30]
- Updated dependencies [967a0ee]
- Updated dependencies [0ca530e]
- Updated dependencies [967a0ee]
- Updated dependencies [9daa49d]
- Updated dependencies [9daa49d]
- Updated dependencies [beb026f]
- Updated dependencies [9daa49d]
- Updated dependencies [967a0ee]
- Updated dependencies [967a0ee]
- Updated dependencies [74a7597]
- Updated dependencies [0c23333]
- Updated dependencies [e8e7e30]
  - three-blocks@0.3.0

## 1.0.0

### Minor Changes

- 623e341: Measure and report the shader-precompilation win across the runtime overlay, Vite receipts, and CLI. Dev sessions now observe first-load TSL build time without changing the shader-provider closure, while `shaders test` records a warmup-discarded median-of-N A/B with spread and optional hardware-labelled committed evidence.

  Make shader claims follow runtime truth: unhydrated caches no longer claim skipped work, adopted apps can run `three-blocks status` without scaffold metadata, page-owned stats panels visibly follow their shared controls, and production bundles continue to erase the observer and overlay.

### Patch Changes

- 803708b: Devtools: Compute shaders now warm asynchronously and ocean shaders hydrate without setup.
- 9f20a06: Make Three Blocks devtools a one-line renderer registration across Vite, Next.js, webpack, and bare browser modules. Existing Vite apps now get page ownership and shader inspection from `three-blocks.shaders.json` automatically, the runtime mounts its fallback overlay, and production-aware bundlers select an import-free no-op that preserves both stable devtools exports. The overlay reports real registered shader builds from the renderer hook for page- and worker-owned apps; timing remains attributed to the matching local A/B receipt.

  When a first shader capture lands, the Vite plugin invalidates transforms that were cached while the manifest glob was empty before reloading the page, so the same running dev session hydrates the new precompiled artifact.

  Align CLI and Vite shader inspection on one metadata precedence: explicit plugin options, then scaffold-owned `three-blocks.json`, then custom-app `three-blocks.shaders.json`. Projects containing both files therefore report and capture the same authoritative scene matrix.

  Unify public commands under `npx three-blocks`, remove the legacy capture endpoint and `precompile.config.mjs` reader, and keep built-in text fonts checksum-pinned without shipping their binary payload in the devtools package archive. Custom worker shells can now reuse the `three-blocks/app` stats controllers and structural smoke bridge instead of maintaining parallel page/worker implementations.

- 3693904: Move stats panels into the dev overlay, add page-owned renderer adoption through `three-blocks/devtools`, and remove scaffold-owned stats code. Page-owned Vite setups are inferred automatically when scaffold metadata is absent; worker texture previews also keep working when `WebGPURenderer` uses its WebGL fallback backend.

  The browser verifier now activates stats through the public smoke controls, proves texture transfer stops after disable, classifies recovered text-fallback errors across both browser channels, and preloads its synthetic probe dependencies to avoid Vite optimizer reload races.

  `stats: true` now enables stats only for the development server. Production stats require the explicit object form: `stats: { production: true }`.

- 35c7bd9: Website: Release pages show the exact version with a short changelog.
- acb4ece: Align package and generated-project notices with the lifetime per-Project commercial license, identify the legal licensor, and ship complete third-party attributions with the core package.
- 9f20a06: Precompiled shader capture now preserves distinct storage access views that share one underlying buffer, so a read-only WGSL binding hydrates as read-only instead of collapsing onto its read-write owner. Hydration also verifies storage-buffer and storage-texture access modes against the captured WGSL before a pipeline is created. WebGPU validates the shader/layout pairing asynchronously, so an access drift between capture and replay used to escape the non-strict live fallback and re-submit an invalid pipeline every frame (observed as `GPUValidationError: The buffer type in the shader (ReadOnlyStorage) is not compatible with the type in the layout (Storage)` spam on `compute_csr_raster`). The provider now replicates three r185's `WebGPUBindingUtils` layout rules per binding slot and turns any remaining mismatch into a synchronous hydration failure, which falls back to live TSL compilation for that key exactly as the fail-soft contract promises.
- 803708b: Devtools: Shader traces now measure replay, skip PMREM setup, and support Three.js r186dev.
- 4c4eab8: Tools: Example optimization now retries browser startup and times out stalled parity checks.
- ece8639: Define devtools as a WebGPU-only shader precompilation workflow. Runtime registration now rejects `WebGLRenderer`, the docs lead with stable shader registration, capture, manifest injection, and parity verification, and shader capture uses the consuming project's Vite runtime for Vite 8 compatibility.
- Updated dependencies [72bbb71]
- Updated dependencies [803708b]
- Updated dependencies [dc934a2]
- Updated dependencies [e67d56b]
- Updated dependencies [acb4ece]
- Updated dependencies [3693904]
- Updated dependencies [e67d56b]
- Updated dependencies [e67d56b]
- Updated dependencies [e67d56b]
- Updated dependencies [72bbb71]
- Updated dependencies [623e341]
- Updated dependencies [9f20a06]
- Updated dependencies [3693904]
- Updated dependencies [e67d56b]
- Updated dependencies [acb4ece]
- Updated dependencies [35c7bd9]
- Updated dependencies [72bbb71]
- Updated dependencies [acb4ece]
- Updated dependencies [e8b569c]
- Updated dependencies [e67d56b]
- Updated dependencies [e67d56b]
- Updated dependencies [623e341]
- Updated dependencies [72bbb71]
- Updated dependencies [72bbb71]
- Updated dependencies [e8b569c]
- Updated dependencies [9f20a06]
- Updated dependencies [623e341]
- Updated dependencies [4eb273d]
- Updated dependencies [623e341]
- Updated dependencies [37e7f64]
- Updated dependencies [803708b]
- Updated dependencies [623e341]
- Updated dependencies [72bbb71]
- Updated dependencies [9811acd]
- Updated dependencies [5feae2c]
- Updated dependencies [ece8639]
- Updated dependencies [5e3cc44]
- Updated dependencies [803708b]
  - three-blocks@0.2.0

This changelog is generated from Changesets.

## 0.1.0

- Initial WebGPU shader precompilation and verification toolchain.