@three-blocks/devtools 12.0.0-alpha.402.g6a35bb19fa05 → 12.0.0-alpha.404.gda4777c53f54

package/CHANGELOG.md

@@ -1,39 +1,154 @@
 # @three-blocks/devtools
 
-## 12.0.0-alpha.402.g6a35bb19fa05
+## 12.0.0-alpha.404.gda4777c53f54
 
-- Library: Three.js r186 is supported, and development always compiles shaders live until previewed.
+- Packages: This alpha contains no user-facing changes.
 
-- Library: Vite builds capture precompiled shaders from the built bundle; nothing to commit.
+- Packages: Built from `da4777c53f54`.
 
-- Devtools: The shader watch command, the 186dev Three.js lane and Playwright driver names are gone.
 
-- Starter: New projects ship no generated shader files; the build captures them.
+## 12.0.0
 
-- CLI: One check command verifies types, the production build and every scene, with a PNG per scene.
+### Major Changes
 
-- Devtools: Development names the shaders that compile after the first frame, once per burst.
+- c5cca15: Devtools: The shader watch command, the 186dev Three.js lane and Playwright driver names are gone.
 
-- Library: Ambient occlusion compiles again with antialiasing on Three.js r186.
+  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.
 
-- Devtools: Interrupted captures and checks no longer leave renderer processes running.
+  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.
 
-- Devtools: Captures and checks deliver pointer and wheel input to listeners on the window.
-
-- Starter: Add a scene by adding a folder; the build captures it and the check command boots it.
-
-- CLI: JSON output of devtools commands no longer starts with a banner line.
-
-- Devtools: Precompiled temporal antialiasing and upscaling jitter the camera again.
-
-- Library: Ambient occlusion loads precompiled on WebGPU instead of compiling at startup.
-
-- Website: The shader precompilation benchmark now measures the official Three.js r186 examples.
+### Minor Changes
 
-- Library: Precompiled ambient occlusion no longer crashes on its first frame on Three.js r186.
+- 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.
 
-- Packages: Built from `6a35bb19fa05`.
+### 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@three-blocks/devtools",
-  "version": "12.0.0-alpha.402.g6a35bb19fa05",
+  "version": "12.0.0-alpha.404.gda4777c53f54",
   "description": "Three Blocks devtools command engine for npx three-blocks; the runtime lives in three-blocks/devtools and the Vite plugin",
   "keywords": [
     "three",
@@ -103,7 +103,7 @@
     "@types/node": "^22.10.0",
     "@types/three": "0.186.0",
     "create-vite": "9.1.1",
-    "three-blocks": "0.13.0-alpha.402.g6a35bb19fa05",
+    "three-blocks": "0.13.0-alpha.404.gda4777c53f54",
     "three-r185": "npm:three@0.185.1",
     "tsup": "^8.0.0",
     "vite": "^7.2.2",
@@ -114,7 +114,7 @@
   },
   "peerDependencies": {
     "three": ">=0.185.0",
-    "three-blocks": "0.13.0-alpha.402.g6a35bb19fa05",
+    "three-blocks": "0.13.0-alpha.404.gda4777c53f54",
     "vite": ">=7.2.2 <9.0.0"
   },
   "peerDependenciesMeta": {