@hology/webgpu-renderer 0.1.1 → 0.1.3

package/README.md

@@ -1,144 +1,144 @@
-# @hology/webgpu-renderer
-
-TypeScript-first WebGPU renderer scaffold aimed at teams migrating from an existing three.js codebase.
-
-The current slice keeps three scene/content classes as the authoring surface and adapts them into a small WGSL-first renderer:
-
-- `Mesh`
-- `SkinnedMesh`
-- `InstancedMesh`
-- `BatchedMesh`
-- `BufferGeometry` and `BufferAttribute`
-- `Texture` / `CanvasTexture` / `DataTexture`
-- `Material` via a custom `WGSLShaderMaterial`
-
-## What this version does
-
-- Initializes a raw WebGPU device and canvas context.
-- Traverses a three `Scene`.
-- Skins `SkinnedMesh` content in the WGSL vertex stage from cached GPU bone palettes; CPU work is limited to one palette update per changed skeleton plus conservative bone-envelope culling.
-- Extracts standard meshes, instanced meshes, and batched meshes into a shared per-frame instance buffer.
-- Renders standard meshes, true instanced draws for `InstancedMesh`, and batched draws for `BatchedMesh` without per-draw object-uniform uploads.
-- Runs the frame through an explicit render graph with pass dependencies, resource reads/writes, and ordered execution.
-- Builds a Hi-Z depth pyramid with compute passes.
-- Uses compute to cull indexed opaque draws against the Hi-Z pyramid and write indirect indexed draw arguments on the GPU.
-- Temporally GPU-culls every instance in a `StaticDrawSet`, compacts visible source-instance indices before the static depth prepass, and builds its indirect instance counts without per-frame CPU visibility uploads.
-- Renders directional-light and point-light shadow maps.
-- Exposes a reusable `ComputeKernel` abstraction for general-purpose compute work.
-- Exposes both `render()` and `renderAsync()` so graph passes can opt into async `prepare()` work before execution.
-- Exposes `compile()` and `compileAsync()` so scenes can prewarm geometry, textures, and material pipelines before the first visible frame.
-- Can capture per-pass render-graph timings, with CPU timings everywhere and GPU timestamp-query timings when the device supports them.
-- Supports custom render-graph nodes, including fullscreen post-processing passes that can read the renderer's scene color target and write to a post-process target before presentation.
-- Exposes a higher-level `FrameGraphBuilder` so passes can be wired with named outputs and inputs instead of raw `GPUTextureView` plumbing.
-- Lets you write custom WGSL shaders and pass uniforms/textures through a material that plays the role of a WebGPU-era `ShaderMaterial`.
-- Supports sampled 2D, 2D-array, 3D, cube, compressed, and compressed-array texture uploads, including KTX2-friendly `CompressedTexture`, `CompressedTextureArray`, `CompressedCubeTexture`, `DataArrayTexture`, and `Data3DTexture` paths.
-- Ships with a demo scene that proves the pipeline works with `Mesh`, `BufferAttribute`, `Texture`, `InstancedMesh`, `BatchedMesh`, and dynamic shadows.
-
-## What this version does not do yet
-
-- Built-in PBR or lighting materials.
-- GPU-driven culling for transparent draws or non-indexed draws. The current visibility path targets indexed opaque draws first.
-- GPU compaction into a single `multi_draw_indirect` style stream. The renderer writes one indirect indexed argument record per extracted indexed draw and then submits them individually.
-- Full GPU-driven aggregation for mutable `BatchedMesh` content. Dynamic batches still use the CPU extraction path; immutable batches can use `StaticDrawSet` for per-instance GPU culling and compaction.
-- Cascaded directional shadows, clustered lighting, point-light arrays, shadow atlases, or any of the bigger AAA-scale scheduling systems yet.
-- Storage textures, external textures, and the more specialized renderer-owned texture flows from three's node/WebGPU stack.
-- Post-processing, temporal anti-aliasing/upscaling, terrain, particles, or material-template systems.
-
-## Install and run
-
-```bash
-npm install
-npm run dev
-```
-
-Useful scripts:
-
-- `npm run build`
-- `npm run typecheck`
-- `npm run demo:build`
-
-## Public API
-
-```ts
-import {
-  FrameGraphBuilder,
-  Mesh,
-  Scene,
-  PerspectiveCamera,
-  BoxGeometry,
-  WGSLShaderMaterial,
-  WebGpuRenderer,
-} from "@hology/webgpu-renderer";
-
-const renderer = new WebGpuRenderer({ canvas });
-await renderer.initialize();
-
-const material = new WGSLShaderMaterial({
-  vertexShader: `...`,
-  fragmentShader: `...`,
-  uniforms: {
-    time: { type: "f32", value: 0 },
-  },
-});
-
-const mesh = new Mesh(new BoxGeometry(1, 1, 1), material);
-const scene = new Scene();
-scene.add(mesh);
-
-const camera = new PerspectiveCamera(50, canvas.width / canvas.height, 0.1, 100);
-camera.position.z = 4;
-
-renderer.render(scene, camera);
-
-await renderer.renderAsync(scene, camera);
-
-renderer.compile(scene, camera);
-await renderer.compileAsync(scene, camera);
-```
-
-`compile()` is synchronous and assumes `initialize()` has already completed. `compileAsync()` will initialize on demand if needed and uses async pipeline compilation for WGSL materials.
-
-For incremental migrations, a renderer-wide fallback can draw meshes whose source
-materials have not been ported yet. The source materials remain untouched, and
-native `WGSLShaderMaterial` instances still take precedence:
-
-```ts
-const renderer = new WebGpuRenderer({
-  canvas,
-  fallbackMaterial: diagnosticMaterial,
-  // Disable this for scenes whose callbacks require THREE.WebGLRenderer APIs.
-  invokeObjectRenderCallbacks: false,
-});
-```
-
-The fallback applies to regular, instanced, and batched mesh extraction, including
-static draw sets. For imported `THREE.SkinnedMesh` objects, the renderer instead
-uses its built-in skin-aware lit fallback automatically, so standard Three.js
-materials and their skin attributes work without a WGSL material per submesh. Set
-`fallbackSkinnedMaterial` when a project needs a custom GPU-skinned appearance.
-Batched meshes from both the Three.js r169 `_drawInfo` layout and newer
-`_instanceInfo` layout are supported.
-
-Hi-Z occlusion culling is currently optional and defaults to off while the GPU visibility path is still settling:
-
-```ts
-const renderer = new WebGpuRenderer({
-  canvas,
-  hiZOcclusionCulling: false,
-  sampleCount: 1,
-  renderGraphProfiling: true,
-});
-
-renderer.setHiZOcclusionCullingEnabled(true);
-renderer.setRenderGraphProfilingEnabled(true);
-```
-
-Whether Hi-Z culling is actually active also depends on device support for WebGPU indirect draws with non-zero `firstInstance`:
-
-```ts
-renderer.getHiZOcclusionCullingEnabled(); // requested
-renderer.getHiZOcclusionCullingActive(); // requested + supported on this device
-renderer.getLastFrameProfile(); // latest CPU/GPU pass timings
+# @hology/webgpu-renderer
+
+TypeScript-first WebGPU renderer scaffold aimed at teams migrating from an existing three.js codebase.
+
+The current slice keeps three scene/content classes as the authoring surface and adapts them into a small WGSL-first renderer:
+
+- `Mesh`
+- `SkinnedMesh`
+- `InstancedMesh`
+- `BatchedMesh`
+- `BufferGeometry` and `BufferAttribute`
+- `Texture` / `CanvasTexture` / `DataTexture`
+- `Material` via a custom `WGSLShaderMaterial`
+
+## What this version does
+
+- Initializes a raw WebGPU device and canvas context.
+- Traverses a three `Scene`.
+- Skins `SkinnedMesh` content in the WGSL vertex stage from cached GPU bone palettes; CPU work is limited to one palette update per changed skeleton plus conservative bone-envelope culling.
+- Extracts standard meshes, instanced meshes, and batched meshes into a shared per-frame instance buffer.
+- Renders standard meshes, true instanced draws for `InstancedMesh`, and batched draws for `BatchedMesh` without per-draw object-uniform uploads.
+- Runs the frame through an explicit render graph with pass dependencies, resource reads/writes, and ordered execution.
+- Builds a Hi-Z depth pyramid with compute passes.
+- Uses compute to cull indexed opaque draws against the Hi-Z pyramid and write indirect indexed draw arguments on the GPU.
+- Temporally GPU-culls every instance in a `StaticDrawSet`, compacts visible source-instance indices before the static depth prepass, and builds its indirect instance counts without per-frame CPU visibility uploads.
+- Renders directional-light and point-light shadow maps.
+- Exposes a reusable `ComputeKernel` abstraction for general-purpose compute work.
+- Exposes both `render()` and `renderAsync()` so graph passes can opt into async `prepare()` work before execution.
+- Exposes `compile()` and `compileAsync()` so scenes can prewarm geometry, textures, and material pipelines before the first visible frame.
+- Can capture per-pass render-graph timings, with CPU timings everywhere and GPU timestamp-query timings when the device supports them.
+- Supports custom render-graph nodes, including fullscreen post-processing passes that can read the renderer's scene color target and write to a post-process target before presentation.
+- Exposes a higher-level `FrameGraphBuilder` so passes can be wired with named outputs and inputs instead of raw `GPUTextureView` plumbing.
+- Lets you write custom WGSL shaders and pass uniforms/textures through a material that plays the role of a WebGPU-era `ShaderMaterial`.
+- Supports sampled 2D, 2D-array, 3D, cube, compressed, and compressed-array texture uploads, including KTX2-friendly `CompressedTexture`, `CompressedTextureArray`, `CompressedCubeTexture`, `DataArrayTexture`, and `Data3DTexture` paths.
+- Ships with a demo scene that proves the pipeline works with `Mesh`, `BufferAttribute`, `Texture`, `InstancedMesh`, `BatchedMesh`, and dynamic shadows.
+
+## What this version does not do yet
+
+- Built-in PBR or lighting materials.
+- GPU-driven culling for transparent draws or non-indexed draws. The current visibility path targets indexed opaque draws first.
+- GPU compaction into a single `multi_draw_indirect` style stream. The renderer writes one indirect indexed argument record per extracted indexed draw and then submits them individually.
+- Full GPU-driven aggregation for mutable `BatchedMesh` content. Dynamic batches still use the CPU extraction path; immutable batches can use `StaticDrawSet` for per-instance GPU culling and compaction.
+- Cascaded directional shadows, clustered lighting, point-light arrays, shadow atlases, or any of the bigger AAA-scale scheduling systems yet.
+- Storage textures, external textures, and the more specialized renderer-owned texture flows from three's node/WebGPU stack.
+- Post-processing, temporal anti-aliasing/upscaling, terrain, particles, or material-template systems.
+
+## Install and run
+
+```bash
+npm install
+npm run dev
+```
+
+Useful scripts:
+
+- `npm run build`
+- `npm run typecheck`
+- `npm run demo:build`
+
+## Public API
+
+```ts
+import {
+  FrameGraphBuilder,
+  Mesh,
+  Scene,
+  PerspectiveCamera,
+  BoxGeometry,
+  WGSLShaderMaterial,
+  WebGpuRenderer,
+} from "@hology/webgpu-renderer";
+
+const renderer = new WebGpuRenderer({ canvas });
+await renderer.initialize();
+
+const material = new WGSLShaderMaterial({
+  vertexShader: `...`,
+  fragmentShader: `...`,
+  uniforms: {
+    time: { type: "f32", value: 0 },
+  },
+});
+
+const mesh = new Mesh(new BoxGeometry(1, 1, 1), material);
+const scene = new Scene();
+scene.add(mesh);
+
+const camera = new PerspectiveCamera(50, canvas.width / canvas.height, 0.1, 100);
+camera.position.z = 4;
+
+renderer.render(scene, camera);
+
+await renderer.renderAsync(scene, camera);
+
+renderer.compile(scene, camera);
+await renderer.compileAsync(scene, camera);
+```
+
+`compile()` is synchronous and assumes `initialize()` has already completed. `compileAsync()` will initialize on demand if needed and uses async pipeline compilation for WGSL materials.
+
+For incremental migrations, a renderer-wide fallback can draw meshes whose source
+materials have not been ported yet. The source materials remain untouched, and
+native `WGSLShaderMaterial` instances still take precedence:
+
+```ts
+const renderer = new WebGpuRenderer({
+  canvas,
+  fallbackMaterial: diagnosticMaterial,
+  // Disable this for scenes whose callbacks require THREE.WebGLRenderer APIs.
+  invokeObjectRenderCallbacks: false,
+});
+```
+
+The fallback applies to regular, instanced, and batched mesh extraction, including
+static draw sets. For imported `THREE.SkinnedMesh` objects, the renderer instead
+uses its built-in skin-aware lit fallback automatically, so standard Three.js
+materials and their skin attributes work without a WGSL material per submesh. Set
+`fallbackSkinnedMaterial` when a project needs a custom GPU-skinned appearance.
+Batched meshes from both the Three.js r169 `_drawInfo` layout and newer
+`_instanceInfo` layout are supported.
+
+Hi-Z occlusion culling is currently optional and defaults to off while the GPU visibility path is still settling:
+
+```ts
+const renderer = new WebGpuRenderer({
+  canvas,
+  hiZOcclusionCulling: false,
+  sampleCount: 1,
+  renderGraphProfiling: true,
+});
+
+renderer.setHiZOcclusionCullingEnabled(true);
+renderer.setRenderGraphProfilingEnabled(true);
+```
+
+Whether Hi-Z culling is actually active also depends on device support for WebGPU indirect draws with non-zero `firstInstance`:
+
+```ts
+renderer.getHiZOcclusionCullingEnabled(); // requested
+renderer.getHiZOcclusionCullingActive(); // requested + supported on this device
+renderer.getLastFrameProfile(); // latest CPU/GPU pass timings
 renderer.getSampleCount(); // current MSAA sample count
 ```
 
@@ -169,260 +169,260 @@ manual synchronization rule applies to directional and spot-light targets whose
 `matrixWorldAutoUpdate` has been disabled.
 
 ## Static GPU Visibility
-
-For immutable environment content, snapshot the authored Three objects once and remove
-the source root from the dynamic scene. The static path supports indexed opaque
-`Mesh`, `InstancedMesh`, and `BatchedMesh` content with `WGSLShaderMaterial`:
-
-```ts
-await renderer.initialize();
-
-const staticEnvironment = renderer.createStaticDrawSet(environmentRoot, {
-  label: "environment",
-});
-scene.remove(environmentRoot);
-```
-
-With Hi-Z active, the renderer keeps frozen instance data and per-instance bounds
-on the GPU. It first culls against the previous frame's depth pyramid, compacts the
-survivors, and uses those indirect commands for the static depth prepass. It then
-builds the current pyramid and retests only the initial rejects before forward
-rendering, which keeps camera motion and newly exposed geometry correct. CPU work
-does not scale with the static set's instance count.
-
-The first frame after creation, resize, or toggling Hi-Z is deliberately
-frustum-only because there is no valid depth history yet. Static transforms,
-membership, geometry, materials, and visibility are frozen; dispose and recreate
-the set after changing any of those properties. Material uniforms and textures
-remain live.
-
-MSAA is currently disabled by default. You can enable it with:
-
-```ts
-const renderer = new WebGpuRenderer({
-  canvas,
-  sampleCount: 4,
-});
-```
-
-or update it later with:
-
-```ts
-renderer.setSampleCount(4);
-```
-
-This first slice applies MSAA to the built-in forward pass and resolves back into the normal scene color target, while the rest of the render graph remains single-sampled.
-
-Meshes can also provide `mesh.customDepthMaterial` using `WGSLShaderMaterial`. In this slice, that override is used for directional and spot shadows so vertex-deformed casters can render correctly into the shadow map. The shared depth prepass intentionally skips those meshes for now to keep the prepass on its fast shared pipeline.
-
-Optional renderer hooks:
-
-- `renderer.setRenderGraphBuilder((graph, context) => { ... })`
-- `renderer.setHiZOcclusionCullingEnabled(true | false)`
-- `renderer.getHiZOcclusionCullingActive()`
-- `renderer.setRenderGraphProfilingEnabled(true | false)`
-- `renderer.getLastFrameProfile()`
-- `renderer.createComputeKernel({ ... })`
-
-Inside `setRenderGraphBuilder(...)`, the context can now:
-
-- add the built-in shadow, depth, Hi-Z, visibility, forward, and present passes
-- add a custom pass via `context.addCustomPass({ ... })`
-- choose whether the present pass samples from `sceneColor` or `postProcessColor`
-
-For a simpler authoring layer, use `FrameGraphBuilder`:
-
-```ts
-renderer.setRenderGraphBuilder((_graph, context) => {
-  const frameGraph = new FrameGraphBuilder(context);
-  const vignetteColor = frameGraph.createColorTarget("vignetteColor");
-
-  frameGraph.addStandardScenePasses();
-  frameGraph.addFullscreenPass({
-    name: "VignettePostPass",
-    inputs: {
-      sceneColor: frameGraph.sceneColor,
-    },
-    outputs: vignetteColor,
-    fragmentShader: `...`,
-  });
-  frameGraph.present(vignetteColor);
-});
-```
-
-This keeps the internal renderer explicit, but lets normal usage feel closer to named render targets flowing from one pass to the next.
-
-## Shader contract
-
-The renderer prepends a small WGSL header before your shaders. Your WGSL code is expected to provide `vsMain` and `fsMain`.
-
-For porting existing three.js `ShaderMaterial` code, see [Migrating Three ShaderMaterial Shaders](docs/shader-material-migration.md). For material shaders that write multiple render targets, see [Multiple Render Targets](docs/multiple-render-targets.md). `WGSLShaderMaterial` accepts three-style uniform entries like `{ value }`, infers common WGSL types, and moves texture uniforms into texture bindings automatically.
-
-`WGSLShaderMaterial` also runs a small preprocessor before WebGPU compilation. You can use `defines` plus common GLSL-style directives such as `#define`, `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif` in WGSL shader strings:
-
-```ts
-const material = new WGSLShaderMaterial({
-  defines: {
-    USE_BATCH_PARAMS: true,
-    MAX_LIGHT_STEPS: 8,
-  },
-  vertexShader,
-  fragmentShader,
-});
-```
-
-The preprocessor is a migration helper, not native WGSL. It supports conditional compilation and simple object-like/function-like macro expansion, but it does not provide three's GLSL chunks or convert GLSL syntax to WGSL.
-
-The renderer also provides a small compatibility define set by default:
-
-- `HIGH_PRECISION`
-- `WEBGPU_RENDERER`
-- `WGSL_SHADER_MATERIAL`
-- `USE_BATCHING`
-- `USE_COLOR`
-- `USE_COLOR_ALPHA`
-- `USE_SHADOWMAP` when compiling a shadow-receiving forward variant
-- `DOUBLE_SIDED` or `FLIP_SIDED` from `material.side`
-- texture-name defines such as `USE_MAP`, `USE_NORMALMAP`, and `USE_ALPHAMAP` when matching texture bindings exist
-- light-count constants such as `NUM_DIR_LIGHTS`, `NUM_POINT_LIGHTS`, and `NUM_SPOT_LIGHTS`
-
-You can disable a default compatibility define per material by setting it to `false` in `defines`.
-
-Available frame resources in every shader:
-
-```wgsl
-struct RendererCameraUniforms {
-  viewProj: mat4x4<f32>,
-  cameraPosition: vec4<f32>,
-  viewportAndTime: vec4<f32>,
-  view: mat4x4<f32>,
-  projection: mat4x4<f32>,
-};
-```
-
-Also available:
-
-- `rendererElapsedTime()` — the `timeSeconds` argument passed to `render()`, in seconds
-- `rendererWorldPosition(localPosition, instanceIndex)`
-- `rendererClipPosition(localPosition, instanceIndex)`
-- `rendererWorldNormal(localNormal, instanceIndex)`
-- `rendererObjectColor(instanceIndex)`
-- `rendererBatchingId(instanceIndex)`
-- `modelMatrix(instanceIndex)`
-- `modelViewMatrix(instanceIndex)`
-- `projectionMatrix()`
-- `normalMatrix(instanceIndex)`
-- `cameraPosition()`
-- `rendererDirectionalLightDirection()`
-- `rendererDirectionalLightColor()`
-- `rendererPointLightPosition()`
-- `rendererPointLightRange()`
-- `rendererPointLightColor()`
-- `rendererAmbientLight()`
-- `rendererSampleDirectionalShadow(worldPosition)`
-- `rendererSamplePointShadow(worldPosition)`
-
-If you define material uniforms, they are exposed as:
-
-```wgsl
-@group(1) @binding(0) var<uniform> materialUniforms: MaterialUniforms;
-```
-
-For example, a uniform named `time` is read as `materialUniforms.time` in WGSL rather than as a global `time` variable.
-
-For renderer-wide animation time, prefer `rendererElapsedTime()` over a material
-`time` uniform. The renderer uploads it once per frame through the shared scene
-or shadow-camera bind group, so it works for forward rendering, depth/shadow
-passes, and compatible `StaticDrawSet` render bundles without per-material
-uniform uploads or bundle rebuilds.
-
-For `BatchedMesh`, `rendererBatchingId(instanceIndex)` returns the original three.js batched instance id from `BatchedMesh.addInstance(...)`. This is the migration replacement for shaders that used three's batching id path to look up additional per-batch data from a custom texture or buffer.
-
-If you define textures like `{ albedo: texture }`, they are exposed with the correct WGSL texture type for the bound three.js texture. A regular 2D texture looks like:
-
-```wgsl
-@group(1) @binding(1) var albedoSampler: sampler;
-@group(1) @binding(2) var albedoTexture: texture_2d<f32>;
-```
-
-For array, cube, 3D, integer, or depth textures, the declaration changes automatically to the matching WGSL type such as `texture_2d_array<f32>`, `texture_cube<f32>`, or `texture_3d<f32>`.
-
-Vertex attribute locations are fixed for this first slice:
-
-- `@location(0)` position `vec3<f32>`
-- `@location(1)` normal `vec3<f32>`
-- `@location(2)` uv `vec2<f32>`
-- `@location(3)` color `vec4<f32>`
-- `@builtin(instance_index)` instance index for shared instance-buffer lookups
-
-Missing geometry attributes are auto-filled with defaults.
-
-### GPU skinning contract
-
-`SkinnedMesh` no longer has a CPU-skinned fallback. Imported Three.js meshes use
-the renderer's built-in skin-aware fallback material automatically. For custom
-WGSL, the renderer sets `USE_SKINNING` from the draw object and supplies the two
-GPU vertex streams. The material only needs the conditional shader path; no
-editor-facing skinning setting is required:
-
-```wgsl
-struct VertexInput {
-  @location(0) position: vec3<f32>,
-  @location(1) normal: vec3<f32>,
-#ifdef USE_SKINNING
-  @location(4) skinIndex: vec4<u32>,
-  @location(5) skinWeight: vec4<f32>,
-#endif
-  @builtin(instance_index) instanceIndex: u32,
-};
-
-#ifdef USE_SKINNING
-let skinnedPosition = rendererSkinPosition(input.position, input.skinIndex, input.skinWeight);
-let skinnedNormal = rendererSkinNormal(input.normal, input.skinIndex, input.skinWeight);
-#else
-let skinnedPosition = input.position;
-let skinnedNormal = input.normal;
-#endif
-output.position = rendererClipPosition(skinnedPosition, input.instanceIndex);
-output.worldNormal = rendererWorldNormal(skinnedNormal, input.instanceIndex);
-```
-
-The renderer shares one GPU palette per `THREE.Skeleton`, uploads it only when its bone world matrices or inverses change, and retains a per-mesh bind-matrix uniform. It also culls against a conservative envelope built from each bone's influenced vertices before a palette upload is needed.
-
-## Demo
-
-The demo is wired directly to the source library and shows:
-
-- a regular `Mesh` using a custom `BufferAttribute` color stream
-- a procedural `SkinnedMesh` example with animated bones
-- a realistic 20-character X Bot walking crowd loaded from the supplied FBX mesh and animation
-- a shared texture sampled from WGSL
-- animated material uniforms
-- an `InstancedMesh`
-- a `BatchedMesh`
-- a shadow-casting directional light
-- a shadow-casting point light
-- a render graph that includes depth, Hi-Z, visibility, and forward passes
-- a live HUD that visualizes per-pass frame timings
-- an example picker with both a baseline scene and a custom vignette post-processing example
-- one example module per file under `demo/examples`, so new demos can be added without growing `demo/main.ts`
-
-## Structure
-
-- `src/materials`: WGSL material and uniform packing
-- `src/renderer`: WebGPU renderer core, extraction, pass execution, and shader header generation
-- `src/rendergraph`: frame graph primitives
-- `src/compute`: reusable compute pipeline wrapper
-- `demo/examples`: one file per selectable example, plus shared demo scene helpers
-- `demo/ui`: small reusable demo UI helpers like the profiling HUD
-- `demo`: Vite demo app shell using the library exports directly
-
-## Next steps
-
-Natural follow-ups from here:
-
-- add a three bridge layer explicitly named and documented as the migration boundary
-- compact visible draws into fewer GPU-driven submission streams and reduce CPU draw iteration further
-- add cascaded directional shadows, light arrays, and shadow atlases
-- add material templates and pipeline caches for larger shader families
-- separate extraction, render graph nodes, and resource registries into dedicated modules
+
+For immutable environment content, snapshot the authored Three objects once and remove
+the source root from the dynamic scene. The static path supports indexed opaque
+`Mesh`, `InstancedMesh`, and `BatchedMesh` content with `WGSLShaderMaterial`:
+
+```ts
+await renderer.initialize();
+
+const staticEnvironment = renderer.createStaticDrawSet(environmentRoot, {
+  label: "environment",
+});
+scene.remove(environmentRoot);
+```
+
+With Hi-Z active, the renderer keeps frozen instance data and per-instance bounds
+on the GPU. It first culls against the previous frame's depth pyramid, compacts the
+survivors, and uses those indirect commands for the static depth prepass. It then
+builds the current pyramid and retests only the initial rejects before forward
+rendering, which keeps camera motion and newly exposed geometry correct. CPU work
+does not scale with the static set's instance count.
+
+The first frame after creation, resize, or toggling Hi-Z is deliberately
+frustum-only because there is no valid depth history yet. Static transforms,
+membership, geometry, materials, and visibility are frozen; dispose and recreate
+the set after changing any of those properties. Material uniforms and textures
+remain live.
+
+MSAA is currently disabled by default. You can enable it with:
+
+```ts
+const renderer = new WebGpuRenderer({
+  canvas,
+  sampleCount: 4,
+});
+```
+
+or update it later with:
+
+```ts
+renderer.setSampleCount(4);
+```
+
+This first slice applies MSAA to the built-in forward pass and resolves back into the normal scene color target, while the rest of the render graph remains single-sampled.
+
+Meshes can also provide `mesh.customDepthMaterial` using `WGSLShaderMaterial`. In this slice, that override is used for directional and spot shadows so vertex-deformed casters can render correctly into the shadow map. The shared depth prepass intentionally skips those meshes for now to keep the prepass on its fast shared pipeline.
+
+Optional renderer hooks:
+
+- `renderer.setRenderGraphBuilder((graph, context) => { ... })`
+- `renderer.setHiZOcclusionCullingEnabled(true | false)`
+- `renderer.getHiZOcclusionCullingActive()`
+- `renderer.setRenderGraphProfilingEnabled(true | false)`
+- `renderer.getLastFrameProfile()`
+- `renderer.createComputeKernel({ ... })`
+
+Inside `setRenderGraphBuilder(...)`, the context can now:
+
+- add the built-in shadow, depth, Hi-Z, visibility, forward, and present passes
+- add a custom pass via `context.addCustomPass({ ... })`
+- choose whether the present pass samples from `sceneColor` or `postProcessColor`
+
+For a simpler authoring layer, use `FrameGraphBuilder`:
+
+```ts
+renderer.setRenderGraphBuilder((_graph, context) => {
+  const frameGraph = new FrameGraphBuilder(context);
+  const vignetteColor = frameGraph.createColorTarget("vignetteColor");
+
+  frameGraph.addStandardScenePasses();
+  frameGraph.addFullscreenPass({
+    name: "VignettePostPass",
+    inputs: {
+      sceneColor: frameGraph.sceneColor,
+    },
+    outputs: vignetteColor,
+    fragmentShader: `...`,
+  });
+  frameGraph.present(vignetteColor);
+});
+```
+
+This keeps the internal renderer explicit, but lets normal usage feel closer to named render targets flowing from one pass to the next.
+
+## Shader contract
+
+The renderer prepends a small WGSL header before your shaders. Your WGSL code is expected to provide `vsMain` and `fsMain`.
+
+For porting existing three.js `ShaderMaterial` code, see [Migrating Three ShaderMaterial Shaders](docs/shader-material-migration.md). For material shaders that write multiple render targets, see [Multiple Render Targets](docs/multiple-render-targets.md). `WGSLShaderMaterial` accepts three-style uniform entries like `{ value }`, infers common WGSL types, and moves texture uniforms into texture bindings automatically.
+
+`WGSLShaderMaterial` also runs a small preprocessor before WebGPU compilation. You can use `defines` plus common GLSL-style directives such as `#define`, `#ifdef`, `#ifndef`, `#if`, `#elif`, `#else`, and `#endif` in WGSL shader strings:
+
+```ts
+const material = new WGSLShaderMaterial({
+  defines: {
+    USE_BATCH_PARAMS: true,
+    MAX_LIGHT_STEPS: 8,
+  },
+  vertexShader,
+  fragmentShader,
+});
+```
+
+The preprocessor is a migration helper, not native WGSL. It supports conditional compilation and simple object-like/function-like macro expansion, but it does not provide three's GLSL chunks or convert GLSL syntax to WGSL.
+
+The renderer also provides a small compatibility define set by default:
+
+- `HIGH_PRECISION`
+- `WEBGPU_RENDERER`
+- `WGSL_SHADER_MATERIAL`
+- `USE_BATCHING`
+- `USE_COLOR`
+- `USE_COLOR_ALPHA`
+- `USE_SHADOWMAP` when compiling a shadow-receiving forward variant
+- `DOUBLE_SIDED` or `FLIP_SIDED` from `material.side`
+- texture-name defines such as `USE_MAP`, `USE_NORMALMAP`, and `USE_ALPHAMAP` when matching texture bindings exist
+- light-count constants such as `NUM_DIR_LIGHTS`, `NUM_POINT_LIGHTS`, and `NUM_SPOT_LIGHTS`
+
+You can disable a default compatibility define per material by setting it to `false` in `defines`.
+
+Available frame resources in every shader:
+
+```wgsl
+struct RendererCameraUniforms {
+  viewProj: mat4x4<f32>,
+  cameraPosition: vec4<f32>,
+  viewportAndTime: vec4<f32>,
+  view: mat4x4<f32>,
+  projection: mat4x4<f32>,
+};
+```
+
+Also available:
+
+- `rendererElapsedTime()` — the `timeSeconds` argument passed to `render()`, in seconds
+- `rendererWorldPosition(localPosition, instanceIndex)`
+- `rendererClipPosition(localPosition, instanceIndex)`
+- `rendererWorldNormal(localNormal, instanceIndex)`
+- `rendererObjectColor(instanceIndex)`
+- `rendererBatchingId(instanceIndex)`
+- `modelMatrix(instanceIndex)`
+- `modelViewMatrix(instanceIndex)`
+- `projectionMatrix()`
+- `normalMatrix(instanceIndex)`
+- `cameraPosition()`
+- `rendererDirectionalLightDirection()`
+- `rendererDirectionalLightColor()`
+- `rendererPointLightPosition()`
+- `rendererPointLightRange()`
+- `rendererPointLightColor()`
+- `rendererAmbientLight()`
+- `rendererSampleDirectionalShadow(worldPosition)`
+- `rendererSamplePointShadow(worldPosition)`
+
+If you define material uniforms, they are exposed as:
+
+```wgsl
+@group(1) @binding(0) var<uniform> materialUniforms: MaterialUniforms;
+```
+
+For example, a uniform named `time` is read as `materialUniforms.time` in WGSL rather than as a global `time` variable.
+
+For renderer-wide animation time, prefer `rendererElapsedTime()` over a material
+`time` uniform. The renderer uploads it once per frame through the shared scene
+or shadow-camera bind group, so it works for forward rendering, depth/shadow
+passes, and compatible `StaticDrawSet` render bundles without per-material
+uniform uploads or bundle rebuilds.
+
+For `BatchedMesh`, `rendererBatchingId(instanceIndex)` returns the original three.js batched instance id from `BatchedMesh.addInstance(...)`. This is the migration replacement for shaders that used three's batching id path to look up additional per-batch data from a custom texture or buffer.
+
+If you define textures like `{ albedo: texture }`, they are exposed with the correct WGSL texture type for the bound three.js texture. A regular 2D texture looks like:
+
+```wgsl
+@group(1) @binding(1) var albedoSampler: sampler;
+@group(1) @binding(2) var albedoTexture: texture_2d<f32>;
+```
+
+For array, cube, 3D, integer, or depth textures, the declaration changes automatically to the matching WGSL type such as `texture_2d_array<f32>`, `texture_cube<f32>`, or `texture_3d<f32>`.
+
+Vertex attribute locations are fixed for this first slice:
+
+- `@location(0)` position `vec3<f32>`
+- `@location(1)` normal `vec3<f32>`
+- `@location(2)` uv `vec2<f32>`
+- `@location(3)` color `vec4<f32>`
+- `@builtin(instance_index)` instance index for shared instance-buffer lookups
+
+Missing geometry attributes are auto-filled with defaults.
+
+### GPU skinning contract
+
+`SkinnedMesh` no longer has a CPU-skinned fallback. Imported Three.js meshes use
+the renderer's built-in skin-aware fallback material automatically. For custom
+WGSL, the renderer sets `USE_SKINNING` from the draw object and supplies the two
+GPU vertex streams. The material only needs the conditional shader path; no
+editor-facing skinning setting is required:
+
+```wgsl
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+#ifdef USE_SKINNING
+  @location(4) skinIndex: vec4<u32>,
+  @location(5) skinWeight: vec4<f32>,
+#endif
+  @builtin(instance_index) instanceIndex: u32,
+};
+
+#ifdef USE_SKINNING
+let skinnedPosition = rendererSkinPosition(input.position, input.skinIndex, input.skinWeight);
+let skinnedNormal = rendererSkinNormal(input.normal, input.skinIndex, input.skinWeight);
+#else
+let skinnedPosition = input.position;
+let skinnedNormal = input.normal;
+#endif
+output.position = rendererClipPosition(skinnedPosition, input.instanceIndex);
+output.worldNormal = rendererWorldNormal(skinnedNormal, input.instanceIndex);
+```
+
+The renderer shares one GPU palette per `THREE.Skeleton`, uploads it only when its bone world matrices or inverses change, and retains a per-mesh bind-matrix uniform. It also culls against a conservative envelope built from each bone's influenced vertices before a palette upload is needed.
+
+## Demo
+
+The demo is wired directly to the source library and shows:
+
+- a regular `Mesh` using a custom `BufferAttribute` color stream
+- a procedural `SkinnedMesh` example with animated bones
+- a realistic 20-character X Bot walking crowd loaded from the supplied FBX mesh and animation
+- a shared texture sampled from WGSL
+- animated material uniforms
+- an `InstancedMesh`
+- a `BatchedMesh`
+- a shadow-casting directional light
+- a shadow-casting point light
+- a render graph that includes depth, Hi-Z, visibility, and forward passes
+- a live HUD that visualizes per-pass frame timings
+- an example picker with both a baseline scene and a custom vignette post-processing example
+- one example module per file under `demo/examples`, so new demos can be added without growing `demo/main.ts`
+
+## Structure
+
+- `src/materials`: WGSL material and uniform packing
+- `src/renderer`: WebGPU renderer core, extraction, pass execution, and shader header generation
+- `src/rendergraph`: frame graph primitives
+- `src/compute`: reusable compute pipeline wrapper
+- `demo/examples`: one file per selectable example, plus shared demo scene helpers
+- `demo/ui`: small reusable demo UI helpers like the profiling HUD
+- `demo`: Vite demo app shell using the library exports directly
+
+## Next steps
+
+Natural follow-ups from here:
+
+- add a three bridge layer explicitly named and documented as the migration boundary
+- compact visible draws into fewer GPU-driven submission streams and reduce CPU draw iteration further
+- add cascaded directional shadows, light arrays, and shadow atlases
+- add material templates and pipeline caches for larger shader families
+- separate extraction, render graph nodes, and resource registries into dedicated modules