@plasius/gpu-renderer 0.2.50 → 0.2.52

package/README.md

@@ -1,26 +1,5 @@
 # @plasius/gpu-renderer
 
-## Native animated showcase surfaces
-
-`createNativeSceneRenderer({ canvas })` draws interleaved world-space triangles
-with depth testing, four-sample antialiasing, filtered directional shadows and
-animated water with a planar reflection. Call `render({ vertices, camera, time,
-wakes })` from the caller's animation loop and `destroy()` on teardown. Each vertex
-has twelve floats: position XYZ, normal XYZ, linear colour RGB, roughness,
-metalness, and procedural detail kind (0 plain, 1 wood, 2 mineral/cloth, 3 terrain).
-`camera` supplies `eye`, `target` and optional vertical `fov`. At most four wakes
-contain `[x, z, headingRadians]`; water can be disabled with `water: false`.
-
-The input limit defaults to 300,000 vertices. Colour/depth targets are reused and
-render dimensions are capped at 3840 per axis and a 1080p pixel budget. Snapshots identify `webgpu-raster`
-and count submitted frames; they do not claim ray tracing, GPU completion or
-photorealism. Native initialization failures reject; device loss changes
-`available` and calls `onUnavailable`. The existing wavefront APIs are unchanged.
-
-Enable only through the consumer's remote `gpu-demo.scene-fidelity.enabled`
-decision and existing access capability. See [design](docs/design/native-showcase-surfaces.md)
-and [ADR-0030](docs/adrs/adr-0030-native-showcase-surfaces.md) for rollout and limits.
-
 [![npm version](https://img.shields.io/npm/v/@plasius/gpu-renderer.svg)](https://www.npmjs.com/package/@plasius/gpu-renderer)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/Plasius-LTD/gpu-renderer/ci.yml?branch=main&label=build&style=flat)](https://github.com/Plasius-LTD/gpu-renderer/actions/workflows/ci.yml)
 [![coverage](https://img.shields.io/codecov/c/github/Plasius-LTD/gpu-renderer)](https://codecov.io/gh/Plasius-LTD/gpu-renderer)
@@ -29,70 +8,11 @@ and [ADR-0030](docs/adrs/adr-0030-native-showcase-surfaces.md) for rollout and l
 [![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
 [![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)
 
-Framework-agnostic WebGPU renderer runtime for Plasius projects.
-This package is intended to replace Three.js-dependent render orchestration with
-an explicit WebGPU-first runtime that can be consumed from React, vanilla, or
-worker-driven app surfaces.
-
-The package targets Node.js 24, consumes the stable `@plasius/gpu-shared` 1.x
-runtime line (`^1.1.1`), and validates its development tooling against the
-current ESLint 10 and TypeScript 7 baselines.
-
-Apache-2.0. ESM + CJS builds.
-
-## Privacy-Safe Feedback Diagnostics
-
-Approved in-game viewers can explicitly convert a small set of current renderer
-health observations into the closed
-`@plasius/gpu-shared/feedback-diagnostics` packet:
-
-```js
-import { createFeedbackGameDiagnosticSnapshot } from "@plasius/gpu-renderer";
-
-const diagnostics = createFeedbackGameDiagnosticSnapshot({
-  featureEnabled,
-  capabilityGranted,
-  consentConfirmed: true,
-  surfaceId: "site.gpu-demo",
-  renderer: "webgpu",
-  backend: "worker",
-  viewportWidth: 1920,
-  viewportHeight: 1080,
-  frameRate: 59.9,
-  frameTimeMs: 16.7,
-  featureIds: ["renderer.frame-loop"],
-  counters: [{ code: "frame-drop", count: 2 }],
-  errorCodes: [],
-});
-```
+Framework-independent WebGPU rendering for browser applications. Render triangle
+meshes with the wavefront path tracer, draw native raster surfaces, or use the
+frame lifecycle and XR integration APIs in your own rendering pipeline.
 
-The helper returns `null` before reading renderer observations unless the
-remotely evaluated `feedback.game-diagnostics.enabled` flag, the
-`feedback.game-diagnostics.attach` capability, and explicit consent are all
-present. It derives trusted provenance and returns only coarse buckets and
-closed codes.
-
-This API is deliberately separate from general renderer snapshots. It accepts
-no canvas, user-captured pixels, DOM, player object, URL, filename,
-adapter/device detail, coordinate or raw warning, performs no automatic
-diagnostic capture or network/storage operation, and never registers
-`/player-system`. Disabling the flag preserves ordinary structured-only bug
-reporting.
-
-## Adaptive per-pixel implementation status
-
-Per-pixel adaptive rendering is not yet exposed by the public renderer API.
-The internal [metadata foundation](docs/design/adaptive-metadata.md) now provides
-reflected requested/completed count storage and lazy, bounded allocation.
-`@plasius/gpu-shader` validates the final initialization WGSL in development;
-the reflector does not enter browser bundles. The normal `npm test` suite checks
-generated byte constants, count packing, allocation admission and cleanup.
-
-The fixed renderer and its whole-frame budget adjustment are unchanged. Actual
-completed-count normalization, compact primary scheduling, foveation and shared
-integration must land before a site comparison can claim per-pixel adaptation.
-No image-quality, performance or net-memory-saving claim follows from the
-metadata-only WebGPU execution fixture. See [ADR 0029](docs/adrs/adr-0029-reflected-adaptive-metadata-admission.md).
+Apache-2.0 · ESM and CommonJS · TypeScript declarations included.
 
 ## Install
 
@@ -100,667 +20,149 @@ metadata-only WebGPU execution fixture. See [ADR 0029](docs/adrs/adr-0029-reflec
 npm install @plasius/gpu-renderer
 ```
 
-## Permanent Zero-Three boundary
-
-This WebGPU renderer and its complete production, development, test, tooling,
-peer, optional, and artifact dependency graphs permanently prohibit Three.js,
-R3F, TSL, their related packages, and any dependency path reaching them. There
-is no compatibility mode, fallback, waiver, or rollback to those renderers.
-
-Run `npm run zero-three:source` before installing dependencies, or run
-`npm run build && npm run zero-three` after `npm ci` for the installed graph,
-built bundle, actual npm tarball, and generated CycloneDX evidence. The full
-command writes digest-bound package/version evidence to
-`release-artifacts/zero-three-evidence.json`. CI retains it, and production CD
-passes it by immutable artifact ID, verifies it again, attaches it to the
-GitHub release, and attests it.
-
-## Usage
+Use Node.js 24 or later for package tooling and a WebGPU-capable browser over
+HTTPS or localhost for rendering. This is a browser GPU runtime; installing it
+in Node does not provide a GPU device. A bundler resolves the package imports.
+Initialization rejects when WebGPU or the requested resources are unavailable;
+your application should present that error and an appropriate retry/fallback UI.
 
-```js
-import { createGpuRenderer } from "@plasius/gpu-renderer";
+## Quick start: render a mesh
 
-const renderer = await createGpuRenderer({
-  canvas: document.querySelector("#scene"),
-  clearColor: "#102035",
-});
+Add a canvas to your page:
 
-renderer.resize(window.innerWidth, window.innerHeight);
-renderer.start();
+```html
+<canvas id="scene" width="640" height="360" aria-label="Rendered triangle"></canvas>
 ```
 
-## Canonical model ingestion
-
-`createCanonicalWavefrontMeshInputs` adapts decoded primitive geometry and image
-samples from the canonical model pipeline to the renderer's existing
-`WavefrontMeshInput` shape. It maps canonical material factors and standard
-texture bindings, preserves supported material extension data, and rejects
-missing primitive, material, or decoded texture references. It accepts triangle
-primitives; parsing, resource fetching, image decoding, and other topologies stay
-in the upstream conversion layer. Metallic-roughness and unlit workflows are
-supported; workflows without an existing Wavefront mapping fail explicitly.
+The following browser module renders a single emissive triangle:
 
 ```js
-import { createCanonicalWavefrontMeshInputs } from "@plasius/gpu-renderer";
-
-const meshes = createCanonicalWavefrontMeshInputs({
-  document: canonicalDocument,
-  geometry: decodedPrimitives.map(({ primitiveId, positions, indices, normals, texcoords }) => ({
-    primitiveId,
-    positions,
-    indices,
-    normals,
-    texcoords,
-  })),
-  // ReadonlyMap<canonical texture id, decoded RGBA sample>
-  textures: decodedTextureSamples,
-});
-```
-
-The canonical document uses types from `@plasius/gpu-model-core`. Geometry is
-already renderer-ready, normals may be omitted to retain the renderer's existing
-fallback, and texture samples are keyed by canonical texture ID. The consuming
-surface remains responsible for evaluating the remote
-`gpu.model.conversion.enabled` flag: when disabled or rolled back, keep the
-existing rendering path active.
-
-## Adaptive Frame Hooks
-
-`@plasius/gpu-renderer` now exposes frame lifecycle hooks so the app can pass
-negotiated frame targets from `@plasius/gpu-performance` and opt into renderer
-frame sampling for `@plasius/gpu-debug`.
-
-```js
-import { createGpuRenderer, createRendererDebugHooks } from "@plasius/gpu-renderer";
-
-const rendererDebugHooks = createRendererDebugHooks({
-  debugSession,
-  getTargetFrameTimeMs: () => governor.getSnapshot().targetFrameTimeMs,
-});
-
-const renderer = await createGpuRenderer({
-  canvas: "#scene",
-  frameIdFactory: ({ frame, xrActive }) => `scene.${xrActive ? "xr" : "flat"}.${frame}`,
-  ...rendererDebugHooks,
-});
-```
-
-## Worker DAG Manifests
-
-The renderer also publishes worker-facing frame-stage manifests so
-`@plasius/gpu-performance` and `@plasius/gpu-worker` can reason about renderer
-work as a multi-root DAG instead of a flat queue.
-
-```js
-import { getRendererWorkerManifest } from "@plasius/gpu-renderer";
-
-const realtimeManifest = getRendererWorkerManifest();
-const xrManifest = getRendererWorkerManifest("xr");
-
-console.log(realtimeManifest.jobs.map((job) => job.worker.jobType));
-console.log(xrManifest.jobs.find((job) => job.key === "lateLatch"));
-```
-
-- `realtime` publishes `acquire`, `visibility`, `mainEncode`, `postProcess`,
-  and `submit`.
-- `xr` publishes `acquire`, `visibility`, `lateLatch`, `mainEncode`, and
-  `submit`.
-- Jobs include queue class, priority, dependencies, adaptive budget levels, and
-  debug metadata such as allocation tags.
-
-## Ray-Tracing-First Planning
-
-The renderer now publishes a stable-snapshot render plan for the premium
-ray-tracing-first frame model.
-
-```js
-import { createRayTracingRenderPlan } from "@plasius/gpu-renderer";
-
-const plan = createRayTracingRenderPlan({
-  snapshotId: "visual-snapshot-42",
-});
-
-console.log(plan.inputBoundary);
-console.log(plan.renderStages.map((stage) => stage.key));
-console.log(plan.representationBands);
-console.log(plan.wavefront.queueLayout.strategy);
-```
-
-## Authored Material Transport
-
-Wavefront materials support authored `KHR_materials_*` factors and extension
-textures, bounded nested media, Beer-Lambert attenuation, and reference
-transport helpers for reflected/transmitted branching and spectral dispersion.
-GPU rays carry up to four medium identifiers and enqueue one selected
-continuation per hit. Dielectric lobes are weighted by their selection
-probability; total internal reflection retains unit throughput. The standalone
-CPU reference helper can describe both branches, but the fixed GPU path never
-enqueues an untracked sibling into its tile-sized queue. Physically qualified
-nested media, rough dielectric transport and full spectral rendering remain
-separate work. See [the Amber correction](docs/amber-transport-correction.md).
-
-```js
-import {
-  createMediumStack,
-  createTransportBranches,
-  createSpectralSamples,
-} from "@plasius/gpu-renderer";
-
-const stack = createMediumStack([1, 4]);
-const branches = createTransportBranches({
-  mediumStack: stack,
-  mediumId: 7,
-  transmission: 1,
-  ior: 1.5,
-});
-const wavelengths = createSpectralSamples({ ior: 1.5, dispersion: 0.2 });
-```
-
-The plan makes the stable visual snapshot boundary explicit, publishes the
-required RT-first stage ordering, and exposes representation-band plus
-acceleration-structure update policy metadata for downstream lighting and
-performance packages. It now also exposes the renderer-owned wavefront queue
-model, versioned ray/hit/surface/material/medium/accumulation contracts, and
-the termination policy for emissive/environment path completion.
-
-## WebGPU Wavefront Compute Renderer
-
-The package also exposes an executable WebGPU wavefront renderer for active-ray
-debug validation scenes. It is compute-driven, tiled, and breadth-first by
-bounce depth, so queue buffers are bounded by tile size instead of presentation
-resolution. Renderer-owned GPU record sizes are part of the public compute
-limits so ray, hit, triangle, BVH, and accumulation buffers stay aligned with
-their WGSL layouts. Frame submission batching and dispatch diagnostics are kept
-in dedicated runtime helpers so performance-facing integrations can consume
-stable frame stats without inheriting the renderer's shader and pipeline
-assembly internals.
-
-## Animated Scene Renderer
-
-`createAnimatedSceneRenderer` provides the renderer-owned v1 surface for the
-GPU animation adventure demo. It accepts scripted beats, route points, props,
-and a backward-compatible `lagged-follow` camera rig that now resolves through
-the shared `@plasius/gpu-camera` editor, spectator, third-person, and
-first-person rig primitives. The renderer exposes `start`, `resize`,
-`getSnapshot`, `setCamera`, `setCameraViewMode`, `applyCameraControl`, and
-`destroy` for host packages. Third-person distance is clamped by camera
-constraints, first-person resolves from the head anchor, and head-look is
-reported as transient post-animation intent instead of mutating clip data. It
-is implemented inside `gpu-renderer` and does not route animation playback
-through Three.js. When hosts provide
-`modelAsset` and `clipAssets`, the v1 canvas renderer parses the Peasant Girl
-GLB mesh, skin, inverse-bind matrices, and Mixamo-compatible clip channels,
-then CPU-skins the active clip and draws model-derived geometry into the
-adventure canvas. Snapshots expose `modelRenderable`, `fallbackProxyActive`,
-`skinnedVertexCount`, `skinnedJointCount`, `activeClipRenderable`,
-`cameraViewMode`, `cameraTransform`, `targetDistance`, `headLook`,
-`characterVisible`, `characterGroundY`, and `propGroundAnchors` so hosts can
-catch camera, scene grounding, and model-renderability regressions.
-When hosts provide beat `movementRequirement` fields and clip
-`movementProfile` metadata, character displacement is resolved per beat:
-travel/jump beats move between route anchors, while stationary action beats
-hold their current anchor unless the profile explicitly allows authored root
-translation. Snapshots expose movement validation diagnostics so hosts can
-detect mismatched animation motion before accepting playback.
-
-`createProfessionalAnimatedSceneRenderer` is the fail-closed WebGPU entrypoint
-for the professional Animation Adventure path. It requires a WebGPU canvas,
-skinned GLB character metadata with UVs, normals, diffuse and normal textures,
-and root-authored movement profiles for travel beats. It rejects the legacy
-2D proxy path instead of silently falling back, renders through WebGPU, and
-exposes `renderMode: "webgpu-pbr"`, texture counts, normal-map readiness,
-root-motion policy, character position, camera position, and active clip
-diagnostics for host validation. Repeated travel beats accumulate root-motion
-distance from the clip duration and loop count, capped by the declared movement
-requirement and route segment. The current surface establishes the WebGPU
-lifecycle and validation boundary for the PBR animation path; shader-level
-textured character and environment drawing builds on this boundary.
-
-The production transport rollout remains gated by
-`renderer.transport.physicalEstimator`. With the flag enabled, deferred
-continuation vertices carry sanitized physical throughput segments instead of a
-heuristic material-response tint, while the older fallback path remains the
-rollback route during validation.
-Low-SPP physical lighting hardening is separately controlled by the boolean
-`renderer.transport.strictPhysicalLowSppLighting` flag, passed either as
-`strictPhysicalLowSppLighting: true` or through `featureFlags`. When enabled,
-the renderer disables terminal ambient rescue for max-depth/null-throughput
-termination, samples procedural sunlight as an explicit shadow-tested
-directional source, samples procedural sky over the visible hemisphere, and
-selects emissive triangles by area-weighted emission power with matching MIS
-PDFs. Use `denoise: false` when validating this strict path so remaining
-variance is measured in the transport rather than hidden by filtering.
-Strict validation can also enable the Product Studio transport experiment
-matrix through independent boolean feature flags. The flags are composable:
-none, one, several, or all may be requested at once. Flags that depend on strict
-physical transport report as requested but no-op effectively when
-`renderer.transport.strictPhysicalLowSppLighting` is disabled.
-
-- `renderer.transport.stableSampleRouting.enabled`
-- `renderer.transport.strictZeroOverflow.enabled`
-- `renderer.transport.deferLowSppRussianRoulette.enabled`
-- `renderer.transport.deterministicDirectLighting.enabled`
-- `renderer.transport.sourceStableDirectLighting.enabled`
-- `renderer.transport.deterministicLowSppIndirect.enabled`
-- `renderer.environment.productStudioImportance.enabled`
-- `renderer.diagnostics.productTransportTelemetry.enabled`
-
-Renderer config, frame stats, and snapshots expose both the structured
-`transportExperiments` state and the packed `transportExperimentFlags` bitfield
-so Product Studio diagnostics can record the exact active set for each render.
-`renderer.transport.sourceStableDirectLighting.enabled` is intended for
-denoise-off Product Studio validation: in strict physical mode it enables the
-deterministic direct-light path and removes direct-light sample dependence on
-adjacent pixel ids and frame index so low-SPP source routing is stable without
-adding ambient fill. Multi-bounce continuation rays that terminate on emissive
-geometry are MIS-weighted against that direct emissive estimator, so rare
-softbox hits remain physically valid without adding full unbalanced source
-radiance as isolated stippled pixels.
-`renderer.transport.deterministicLowSppIndirect.enabled` is also strict-mode
-only. The flag remains in the public experiment matrix so Product Studio can
-keep reporting requested and effective rollout state, but the strict shader path
-does not inject cached indirect radiance or suppress physical continuation. Any
-future low-SPP indirect stabilizer must be introduced as an auditable transport
-source with measured PDFs, visibility, and validation against high-SPP reference
-renders before it contributes radiance. Until then,
-`transportContributions.cachedIndirectLuminance` should remain zero and
-multi-bounce energy should come from direct explicit lighting, true terminal
-emissive/environment hits, or stochastic BSDF continuation.
-Set `presentationOutput: "linear"` for linear presented validation captures, or
-omit it to keep the default tone-mapped presentation.
-
-```js
-import {
-  createWavefrontPathTracingComputeRenderer,
-} from "@plasius/gpu-renderer";
+import { createWavefrontPathTracingComputeRenderer } from "@plasius/gpu-renderer";
 
 const renderer = await createWavefrontPathTracingComputeRenderer({
-  canvas: document.querySelector("#product-render"),
-  width: 1280,
-  height: 720,
-  maxDepth: 6,
-  samplesPerPixel: 8,
-  displayQuality: true,
-  meshes: [
-    {
-      id: 1,
-      positions: [-1, -1, 0, 1, -1, 0, 0, 1, 0],
-      indices: [0, 1, 2],
-      normals: [0, 0, 1, 0, 0, 1, 0, 0, 1],
-      emission: [8, 7, 5, 1],
-    },
-  ],
+  canvas: "#scene",
+  width: 640,
+  height: 360,
+  maxDepth: 2,
+  samplesPerPixel: 1,
+  meshes: [{
+    id: 1,
+    positions: [-1, -1, 0, 1, -1, 0, 0, 1, 0],
+    indices: [0, 1, 2],
+    normals: [0, 0, 1, 0, 0, 1, 0, 0, 1],
+    emission: [8, 7, 5, 1],
+  }],
 });
 
-renderer.renderOnce();
-```
-
-Existing consumers that still call `renderFrame(...)` or
-`renderWavefrontPathTracingComputeFrame(...)` remain supported as compatibility
-wrappers around the canonical mesh renderer.
-
-Analytic scene objects remain available for debug fixtures:
-
-```js
-const debugRenderer = await createWavefrontPathTracingComputeRenderer({
-  canvas: document.querySelector("#debug-render"),
-  width: 1280,
-  height: 720,
-  maxDepth: 6,
-  sceneObjects: [
-    {
-      type: "sphere",
-      center: [0, 1.8, -0.5],
-      radius: 0.35,
-      emission: [8, 7, 5, 1],
-      materialKind: "emissive",
-    },
-  ],
-});
+await renderer.renderFrame();
 
-debugRenderer.renderOnce();
+// Call this from your route or component cleanup.
+export function dispose() {
+  renderer.destroy();
+}
 ```
 
-Scene objects currently support analytic `sphere` and axis-aligned `box`
-records with colour, emission, roughness, metallic, opacity, IOR, clearcoat,
-sheen colour, specular colour, and transmission fields.
-These records are debug fixtures only. Product Studio visual rendering requires
-the mesh BVH path described in
-`docs/adrs/adr-0007-triangle-mesh-wavefront-path-tracing.md`. This is a
-project-wide display-quality baseline for path-traced rendering, not a
-Product-Studio-only requirement.
-
-Mesh inputs are normalized into triangle records, packed into GPU buffers, and
-uploaded as source buffers for tracing. Vertex normals are preserved for smooth
-shading; when normals are absent the triangle geometric normal is used. The
-display-quality path now defaults to `accelerationBuildMode: "cpu-upload"` so
-CPU-built BVH nodes and triangle records are uploaded once and then reused by
-the GPU tracing passes. Set `accelerationBuildMode: "gpu"` only when you
-explicitly want the experimental GPU-side BVH assembly path for validation or
-development. The `createWavefrontMeshAcceleration(...)` helper is therefore no
-longer debug-only; it is the stable display-quality acceleration builder,
-whereas GPU BVH construction remains available behind the explicit mode switch.
-CPU-upload records still preserve the raw material factors plus atlas rects and
-texture settings expected by the GPU hit-time samplers; they are not meant to
-replace exact UV-driven sampling with CPU-baked triangle averages.
-The GPU BVH path still uses Morton-style centroid keys to sort leaf references
-before sorted leaves and level-concurrent internal nodes are materialized.
-When mesh inputs also carry UVs plus decoded base-colour,
-metallic-roughness, normal, occlusion, or emissive maps, the display-quality
-path now packs them into GPU texture atlases and samples them at the resolved
-hit UV inside the wavefront trace pass. Generic glTF-style material factors
-such as clearcoat, sheen colour, specular colour, transmission, and IOR are
-also preserved through the GPU records so demo validation does not need
-model-name overrides. CPU-side texture work is limited to load-time decode and
-atlas packing; per-hit shading stays on the GPU. Direct and terminal glossy
-response now also samples reflection-aligned environment radiance so leather,
-chrome, and other polished authored materials can read from the active
-environment map or procedural sky instead of relying mostly on a sun-direction
-proxy.
-Authored participating-media inputs can also enter through the same mesh path.
-A mesh may provide an explicit `medium` block or a glTF-style `material.volume`
-block with `thickness`, `attenuationColor`, and `attenuationDistance`; the
-renderer derives the medium-table entry, carries the active medium id on the
-GPU ray, and applies Beer-Lambert transmittance to travelled segments on the
-GPU. Thickness is now preserved in material packing for later shell-volume
-work, but the current renderer still tracks only one active medium id per ray
-and does not yet implement nested media, spectral dispersion, or a branching
-reflection/refraction tree. Invalid medium ids fall back to the current ray
-medium, and entering a second medium while one is already active preserves the
-existing medium id until dedicated stack support is implemented.
-
-`samplesPerPixel` controls how many GPU primary-ray samples are accumulated per
-screen pixel within a single render. This multiplies dispatch work but does not
-increase the tile queue memory footprint, so 720p/1080p/4K targets remain
-bounded by `tileSize`. `maxDepth` is bounded at 32 for offline/reference
-renders, allowing 20-bounce quality checks while keeping path-vertex memory
-explicit and predictable. When `denoise` is enabled the renderer writes raw
-linear radiance to an `rgba16float` texture first, then runs a two-stage
-full-frame GPU denoise through an `rgba16float` scratch texture before final
-tone mapping into the presented `rgba8unorm` output. Filtering in linear
-radiance space lets the denoise pass cross tile boundaries without compressing
-energy/detail before the final resolve. High-SPP wavefront sampling now routes
-camera jitter, BSDF continuation, emissive-light selection, and environment
-selection through named sample dimensions in
-`src/wavefront-sampling-dimensions.js`, using low-discrepancy 2D pairs where
-they improve convergence without adding CPU-side sample tables. The companion
-`src/wavefront-denoise-validation.js` acceptance helper keeps denoise-off
-validation explicit with structural-artifact, invalid-sample, baseline-noise,
-and sheen/chrome/wood detail-retention thresholds so the
-`renderer.denoise.highSppIndependence` rollout can stay reviewable and
-rollbackable. The renderer also stores compact
-emissive-triangle metadata in the existing BVH buffer tail and uses it to guide
-diffuse continuation rays toward finite mesh light geometry. This is not a
-separate shadow/direct-light pass: the active ray still has to hit emissive
-geometry or miss into the environment before radiance is committed. Guided
-emissive hits carry a bounded estimator weight so finite light guidance does not
-over-expose low-sample renders before full material PDFs/MIS are implemented.
-By default, `deferredPathResolve` records
-per-bounce material responses in a tile-bounded path buffer and records the
-terminal emissive/HDRI/environment source in the final path slot. The output
-pass then resolves that recorded path backward and adds the weighted sample to
-the pixel accumulation, so unresolved continuation light is still deferred until
-a terminal source is known. Surface resolution may still add a small
-shadow-tested direct-light term immediately when it has an explicit source and
-visibility result, which keeps true occlusion shadows possible without falling
-back to broad per-bounce ambient fill. Set `deferredPathResolve: false` only
-for legacy forward-accumulation comparison.
-When an `environmentMap` is provided, the wavefront trace shader samples it as
-an equirectangular radiance source for environment misses and uses the same
-mapped radiance for terminal residuals before falling back to static ambient.
-The procedural horizon/zenith/sun model remains the fallback for callers that
-have not supplied an HDRI/radiance texture. `environmentLighting.sunlitBaseline`
-adds a time-of-day daylight floor to terminal and direct environment estimates,
-so bright presets retain colour at the last collision without returning to a
-whitewashed global ambient term. Extremely dark recorded bounce responses are
-also remapped to a small scene-brightness-driven luminance floor so bright
-low-sample scenes do not produce isolated black speckles when a valid terminal
-source was already found. Awaited `renderFrame({ readStats: true })` results now
-keep linear accumulation unclamped, sanitize only invalid or half-float-
-overflow samples before presentation, and expose
-`terminalRadiance.totalLuminance`,
-`terminalRadiance.ambientResidualLuminance`, and
-`terminalRadiance.ambientResidualShare` so validation harnesses can track how
-much of the final resolved image came from terminal ambient residuals.
-The same stats also expose `radianceDiagnostics.invalidSamples` and
-`radianceDiagnostics.legacyClampEquivalentSamples`, so hardening scenes can
-measure NaN/Inf cleanup and legacy-4.0-equivalent fireflies without
-re-introducing a hidden estimator clamp.
-When `strictPhysicalLowSppLighting` is enabled, termination stats also separate
-`absorptionNull`, `russianRoulette`, and `strictMaxDepth` so validation can
-distinguish physically explainable dark samples from legacy ambient fallback.
-For static mesh scenes, the GPU acceleration build is submitted once and then
-reused by subsequent frames. Per-frame tracing writes one dynamic uniform slot
-per tile/sample or post-process pass and batches tile tracing, tile output,
-optional denoise, and presentation into bounded command submissions controlled
-by `maxFramePassesPerSubmission` to keep 4K/high-spp command buffers from
-becoming oversized. `updateCamera(...)` can update the per-frame camera uniforms
-without rebuilding scene buffers. `renderFrame(...)` also accepts an optional
-`frameTimeBudgetMs` plus `minimumSamplesPerPixel`: when present, configured
-`samplesPerPixel` becomes a ceiling instead of a hard requirement, the renderer
-guarantees at least the minimum full-screen pass, and frame stats report both
-configured `samplesPerPixel` and actual `renderedSamplesPerPixel` so realtime
-callers can budget motion frames without overstating delivered quality.
-Before requesting a WebGPU device, the renderer derives the largest scene
-storage binding from the normalized scene, mesh, and BVH records. It requests
-the smallest sufficient `maxStorageBufferBindingSize` (and `maxBufferSize` only
-when the WebGPU default is also exceeded), preserves stricter caller limits,
-and rejects unsupported adapters before device creation. Default-sized scenes
-do not elevate either size limit. `config.memory` and snapshot memory telemetry
-describe the actual persistent GPU buffer descriptors: placeholder records,
-combined BVH/emissive storage, mesh source buffers, aligned frame/build uniform
-buffers, counters, and dispatch arguments are each counted exactly once;
-`materialTableBytes` is zero because material data is packed into mesh and
-triangle records rather than a standalone GPU buffer.
-For consumers that want to hand wavefront SPP adaptation to
-`@plasius/gpu-performance`, `createWavefrontAdaptiveSamplingLevels(...)` exposes
-a bounded low-to-high ladder of per-frame `samplesPerPixel`,
-`frameTimeBudgetMs`, and `minimumSamplesPerPixel` configs that stay aligned
-with the renderer's supported adaptive-sampling surface. Frame stats and
-snapshots expose
-`gpuParallelism` diagnostics with adapter compute limits, configured workgroup
-size, direct compute dispatches, known workgroups/invocations, indirect dispatch
-counts, and upper-bound indirect work estimates. WebGPU does not expose physical
-GPU core counts, so `physicalCoreCount` remains `null`; use
-`exposesMultiWorkgroupParallelism`, `largestDirectWorkgroupsPerDispatch`, and
-`largestEstimatedIndirectWorkgroupsPerDispatch` to confirm the renderer is
-issuing multi-workgroup GPU work. Awaited frame results also expose a
-`transportGuardrails` summary with jobs/frame, jobs/s, jobs/submission, command
-submissions, queue-overflow count, radiance diagnostics, total tracked memory
-bytes, and device-loss status so validation harnesses can gate transport work
-without scraping ad hoc metrics from multiple fields. Treat any sustained >10%
-drop in jobs/submission or jobs/s versus the approved baseline as a
-release-validation failure unless a linked ticket explicitly approves the
-regression; `submission-batching` warns when the renderer falls back to roughly
-one GPU job per submission despite a higher pass ceiling.
-
-Awaited fixed-SPP renders can opt into exact ray and timing evidence:
+Supply decoded triangle geometry and material/texture data through `meshes`.
+The renderer does not fetch glTF files: use a loader such as
+[`@plasius/gpu-shared`](https://www.npmjs.com/package/@plasius/gpu-shared), or adapt
+canonical decoded assets with `createCanonicalWavefrontMeshInputs`.
+For an interactive model viewer with loading, integrity checks, camera gestures
+and quality controls, use the shared package's `model-inspection` entry.
 
-```js
-const frame = await renderer.renderFrame({
-  readStats: true,
-  readOutputProbe: false,
-});
-
-console.log({
-  primaryRays: frame.primaryRays,
-  secondaryRays: frame.secondaryRays,
-  totalPathSegments: frame.totalPathSegments,
-  bounceHistogram: frame.rayCounts.bounceHistogram,
-  gpuTimeMs: frame.timings.totalGpuTimeMs,
-  renderJobTimeMs: frame.timings.totalRenderJobTimeMs,
-  timingSource: frame.timings.source,
-});
-```
+## Choose a rendering API
 
-`primaryRays` is the exact number of camera samples. `secondaryRays` is the
-sum of active continuation records intersected after bounce zero, including
-bounded reflection/transmission branches, and `totalPathSegments` is their sum.
-The renderer copies the existing active-queue counter once per bounce into a
-lazily allocated telemetry buffer; it does not add diagnostic shader atomics or
-change WGSL transport. `rayCounts.status` distinguishes available,
-unavailable, failed, and not-requested evidence. A mismatch between scheduled
-and observed primary rays fails the `ray-count-telemetry` transport guardrail.
-Ray-count reduction uses constant call-stack space, including the supported
-4K/eight-bounce/128-SPP stress envelope where hundreds of thousands of
-tile/sample/depth records collapse into a small per-bounce histogram.
-
-When the adapter exposes `timestamp-query`, the device requests it
-opportunistically and two timestamps measure the GPU span from the first
-primary pass through presentation. Set `gpuTimestamps: false` at renderer
-creation to prevent that optional feature request. Where timestamp queries are
-not exposed or fail, `timings` reports `source: "queue-completion"`, leaves
-`totalGpuTimeMs` null, and retains the awaited
-`totalRenderJobTimeMs`. Classification, compaction, and sampling sub-pass times
-remain null until the corresponding adaptive passes exist. Without
-`readStats: true`, and for `renderOnce()`, the fixed dispatcher creates no
-telemetry buffers, query sets, readbacks, or timestamped pass descriptors.
-
-After each
-primary-ray or compaction pass, the GPU writes the active-ray workgroup count
-into the counter buffer and the encoder copies it into an indirect-dispatch
-argument buffer. Intersection and surface-resolution passes therefore scale
-with active continuation rays instead of the maximum tile capacity, while still
-avoiding CPU readback between bounces. WebGPU
-still preserves ordering between dependent bounce passes, but the renderer
-keeps CPU queue submissions bounded rather than forcing one submission per
-tile/sample. Awaited higher-SPP submission slicing remains tile-major because
-the accumulation buffer is tile-local; changing that order to sample-major
-would mix samples across tiles and corrupt the resolved image.
-Environment-light portals can additionally guide and gate sky/HDRI contribution
-through rectangular openings such as windows. `environmentPortalMode: "guide"`
-biases diffuse continuation rays toward configured openings, while
-`"guide-and-gate"` requires an environment miss to pass through a portal before
-it receives sky radiance; misses outside a portal fall back to the ambient
-residual. This keeps interior rooms from treating the whole sky as visible from
-every bounce.
-Texture sampling, dynamic TLAS updates, higher-grade LBVH/SAH construction,
-runtime execution behind the `@plasius/gpu-worker` lock-free queue, and broader
-material lookup remain follow-up work.
-
-## XR integration
+| API | Purpose |
+| --- | --- |
+| `createWavefrontPathTracingComputeRenderer` | Tiled, mesh-BVH path tracing with material transport, environment lighting and optional progressive accumulation |
+| `createNativeSceneRenderer` | Native raster triangles, authored surface maps, shadows and optional animated water |
+| `createGpuRenderer` | Device/canvas setup, clear pass, frame hooks and XR binding for a host-owned pipeline |
+| `createProfessionalAnimatedSceneRenderer` | The validated WebGPU animation scene path with skinned assets and root-motion requirements |
+| `createAnimatedSceneRenderer` | The existing canvas animation-adventure surface |
+| `createRayTracingRenderPlan` | Rendering plan metadata; it does not draw a scene |
+
+All factories are exported from `@plasius/gpu-renderer`. Keep the import and GPU
+initialization inside the route that needs them. The host owns loading/error UI,
+visibility policy, accessible controls, and disposal when leaving the view.
+
+## Progressive rendering
+
+Set `progressive: true` when creating the wavefront renderer. Its creation-time
+`samplesPerPixel` sets batch capacity; each `renderFrame({ samplesPerPixel })`
+may submit a smaller batch. Await batches serially and stop scheduling when your
+sample target is reached or the view is hidden. `renderFrame()` waits for GPU
+completion by default.
+
+Camera and scene changes reset accumulated radiance. `updateCamera()` preserves
+the loaded meshes, materials and acceleration resources; do not call it between
+refinement passes if the view has not changed. `resetAccumulation()` discards
+history explicitly. Denoising runs after accumulation.
+
+`getSnapshot().accumulatedSamplesPerPixel` counts **submitted** samples. If you
+use synchronous `renderOnce()`, await `renderer.device.queue.onSubmittedWorkDone()`
+before labelling that work complete. Public sampling is fixed per frame;
+experimental per-pixel adaptive metadata does not enable adaptive rendering.
+See the [wavefront guide](https://github.com/Plasius-LTD/gpu-renderer/blob/main/docs/guides/wavefront.md)
+for memory, timing, transport flags and progressive behavior.
+
+## Frame lifecycle without a scene
+
+Use `createGpuRenderer` when your application owns the rendering pipeline. This
+example clears the canvas and runs the frame lifecycle; it does not load or draw
+3D models:
 
 ```js
-import { createXrManager } from "@plasius/gpu-xr";
 import { createGpuRenderer } from "@plasius/gpu-renderer";
 
-const renderer = await createGpuRenderer({ canvas: "#scene" });
-const xr = createXrManager();
-
-renderer.bindXrManager(xr, {
-  onSessionStart: () => console.log("XR active"),
-  onSessionEnd: () => console.log("XR inactive"),
+const renderer = await createGpuRenderer({
+  canvas: "#scene",
+  clearColor: "#102035",
 });
+renderer.resize(640, 360);
+renderer.start();
+
+export function dispose() {
+  renderer.destroy();
+}
 ```
 
-## API
-
-- `supportsWebGpu(options)`
-- `createGpuRenderer(options)`
-- `createRendererDebugHooks(options)`
-- `getRendererWorkerProfile(name?)`
-- `getRendererWorkerManifest(name?)`
-- `createRayTracingRenderPlan(options)`
-- `createWavefrontPathTracingComputeRenderer(options)`
-- `createWavefrontPathTracingComputeConfig(options)`
-- `createWavefrontPathTracingComputeShaderSource(options?)`
-- `renderWavefrontPathTracingComputeFrame(options)`
-- `createWavefrontReferenceRay(config, options?)`
-- `intersectWavefrontReferenceTriangle(ray, triangle, options?)`
-- `traceWavefrontReferenceTriangles(config, ray, triangles, options?)`
-- `normalizeWavefrontMesh(input)`
-- `createWavefrontGpuMeshSource(meshes)`
-- `createWavefrontBvhSortStages(itemCount)`
-- `createWavefrontBvhBuildLevels(triangleCount)`
-- `createWavefrontMeshAcceleration(meshes)`
-- `normalizeWavefrontSceneObject(input)`
-- `packWavefrontSceneObjects(sceneObjects, capacity?)`
-- `packWavefrontTriangles(triangles, capacity?)`
-- `packWavefrontBvhNodes(nodes, capacity?)`
-- `rendererWavefrontComputeMode`
-- `rendererWavefrontComputeWorkgroupSize`
-- `rendererWavefrontComputeStatsStride`
-- `bindRendererToXrManager(renderer, xrManager, options)`
-- `defaultRendererClearColor`
-- `rendererDebugOwner`
-- `rendererWorkerQueueClass`
-- `defaultRendererWorkerProfile`
-- `rendererWorkerProfiles`
-- `rendererWorkerProfileNames`
-- `rendererWorkerManifests`
-
-The reference helpers mirror the renderer WGSL camera and triangle-hit math in
-deterministic JavaScript so tests and downstream tooling can validate primary
-ray generation, barycentrics, nearest-hit selection, and environment misses
-without standing up a WebGPU device.
-
-## Demo
-
-Run the demo server from the repo root:
+## API and integration guides
 
-```sh
-cd gpu-renderer
-npm run demo
-```
+- [Wavefront path tracing, materials and progressive refinement](https://github.com/Plasius-LTD/gpu-renderer/blob/main/docs/guides/wavefront.md).
+- [Native surfaces, texture maps and clearcoat](https://github.com/Plasius-LTD/gpu-renderer/blob/main/docs/guides/native-surfaces.md).
+- [Canonical ingestion, frame hooks, worker manifests, XR and diagnostics](https://github.com/Plasius-LTD/gpu-renderer/blob/main/docs/guides/integration.md). Snippets in this reference use host-provided decoded assets and services.
+- [Animation scene contracts](https://github.com/Plasius-LTD/gpu-renderer/blob/main/docs/guides/animation.md).
+- [Complete public TypeScript declarations](https://github.com/Plasius-LTD/gpu-renderer/blob/main/src/index.d.ts).
+- [Crate material-study implementation notes](https://github.com/Plasius-LTD/gpu-renderer/blob/main/docs/guides/material-study-internals.md). Fixture helpers are internal; mount the study through `@plasius/gpu-shared/material-study`.
 
-Then open `http://localhost:8000/gpu-renderer/demo/`.
+Experimental transport switches use the `featureFlags` options described in the
+wavefront guide. The package consumes supplied decisions; it does not connect to
+an account or remote flag service. Plasius production consumers also apply their
+route capabilities and rollout policy before mounting a scene.
 
-The demo now mounts the mesh BVH WebGPU wavefront renderer directly and passes a
-`@plasius/gpu-lighting` environment preset into the render. It reports the
-active wavefront depth, tile count, triangle/BVH counts, lighting preset, probe
-luminance, and hot buffer memory so it is clear whether the renderer is tracing
-mesh paths rather than only showing planning metadata.
+## Development
 
-## Development Checks
+From a checkout, using the repository's Node.js version:
 
 ```sh
+npm ci --legacy-peer-deps
 npm run lint
 npm run typecheck
 npm run test:coverage
 npm run build
 npm run pack:check
+npm run zero-three
 ```
 
-## Files
-
-- `src/index.js`: public package facade for renderer runtime, render-plan, and
-  wavefront exports.
-- `src/renderer-*.js`: framework-agnostic renderer constants, validation,
-  worker manifests, wavefront render plans, and WebGPU runtime/XR binding
-  helpers.
-- `src/wavefront-compute.js`: canonical WebGPU mesh BVH wavefront renderer
-  lifecycle, live state, and public renderer instance methods.
-- `src/wavefront-acceleration-builder.js`, `src/wavefront-frame-encoder.js`,
-  `src/wavefront-frame-dispatcher.js`, and `src/wavefront-frame-stats.js`:
-  purpose-specific acceleration build, pass encoding, tile/sample dispatch, and
-  frame-stat policy helpers.
-- `src/wavefront-bind-groups.js`, `src/wavefront-pipelines.js`,
-  `src/wavefront-gpu-synchronization.js`, and `src/wavefront-readbacks.js`:
-  WebGPU bind-group construction, pipeline construction, queue synchronization,
-  and readback/probe helpers.
-- `src/wavefront-config.js`: wavefront camera, environment, portal, memory, and
-  scene-source configuration.
-- `src/wavefront-scene-data.js`: compatibility facade for wavefront scene data
-  helpers.
-- `src/wavefront-materials.js`, `src/wavefront-scene-normalizers.js`, and
-  `src/wavefront-mesh-sources.js`: material/medium normalization, scene/mesh
-  normalization, texture-atlas creation, BVH source generation, and GPU mesh
-  source packing.
-- `src/wavefront-shaders.js` and `src/wavefront-shader-*.js`: WGSL assembly
-  and purpose-specific shader source sections for layout, materials, lighting,
-  BVH/intersection, and render kernels.
-- `src/wavefront-gpu-resources.js`, `src/wavefront-packers.js`, and
-  `src/wavefront-runtime-support.js`: GPU resources, binary record packers, and
-  WebGPU runtime/pipeline support.
-- `src/wavefront-reference.js` and `src/wavefront-sampling.js`: deterministic
-  reference transport and sampling helpers used by validation tests.
-- `src/index.d.ts`: public API typings.
-- `scripts/check-source-syntax.cjs`: syntax-checks every JavaScript source file
-  included under `src/`.
-- `tests/package.test.js`: unit tests for renderer lifecycle behavior.
-- `docs/design/worker-manifest-integration.md`: renderer frame-stage DAG model.
-- `docs/adrs/*`: architecture decisions for renderer runtime design.
-- `docs/tdrs/*`: technical direction for frame hook integration.
+`npm run demo` requires Python 3 and serves the parent workspace. With the checkout
+named `gpu-renderer`, visit `http://localhost:8000/gpu-renderer/demo/`.
+See the [development guide](https://github.com/Plasius-LTD/gpu-renderer/blob/main/docs/guides/development.md)
+for sibling-package requirements and source layout, and
+[CONTRIBUTING.md](https://github.com/Plasius-LTD/gpu-renderer/blob/main/CONTRIBUTING.md).
+
+Three.js and dependency paths reaching it are prohibited across runtime,
+development tooling and published artifacts. `npm run zero-three:source` checks
+source admission before installation; `npm run zero-three` validates the installed
+and built package evidence.
 
 <!-- BEGIN PLASIUS RELEASE INTEGRITY -->
 ## Release integrity
@@ -790,204 +192,3 @@ there is no npm write-token fallback. CD remains disabled until the npm trusted
 publisher binding and protected-branch-only production environment are
 independently verified.
 <!-- END PLASIUS RELEASE INTEGRITY -->
-
-### Authored materials in native surfaces
-
-`createNativeSceneRenderer({ canvas, materials })` accepts up to 16 opaque
-materials containing decoded RGBA8 `baseColor`, `normal`, and/or `orm` maps.
-This matches images returned by the `@plasius/gpu-shared` glTF loader. Colour maps
-are sRGB; normals and ORM (occlusion/roughness/metalness) are linear. Optional
-`normalScale` defaults to 1. Maps must be power-of-two, up to 2048 pixels per axis,
-with a 64 MiB combined decoded-source budget. Textures are uploaded once and mip
-filtered; the renderer owns GPU disposal, while callers own image loading.
-
-For textured frames, supply `texcoords` (two floats per vertex) and `surfaces`
-containing `{ firstVertex, vertexCount, materialIndex }`. Ranges must cover the
-whole triangle list in order, refer to the initialization-time materials, and
-contain whole triangles. At most 256 ranges are accepted. Linear vertex colour
-and roughness/metalness factors multiply the maps. Omit both new frame fields to
-retain the existing procedural/untextured path. Main and reflection passes use
-the same authored material; alpha/transmission/skinning are not added here.
-
-See [material design](docs/design/native-textured-surfaces.md) and
-[ADR-0031](docs/adrs/adr-0031-native-authored-materials.md). Rollout inherits
-`gpu-demo.scene-fidelity.enabled`; access remains governed by the site's capability.
-
-For varnished wood, set optional `clearcoat` and `clearcoatRoughness` (both 0–1).
-The coating reflects neutral light using its own smooth geometric normal above
-the coloured, normal-mapped wood; Fresnel layering attenuates the underlying
-material instead of simply adding shine. Strength defaults to zero, preserving
-uncoated callers. Coating roughness defaults to zero and is independent of the
-base roughness map. Optional `clearcoatMap` uses linear RGBA8: red multiplies
-`clearcoat` coverage and green multiplies `clearcoatRoughness`; blue and alpha
-are ignored. Omission uses white, preserving the scalar-only finish. Use a
-nonzero roughness factor (for example 1) to author roughness directly in green.
-The map shares the surface UVs, mip filtering, memory budget and GPU lifetime of
-other maps. Clearcoat normal maps remain unsupported.
-
-For mixed objects, give uncoated parts their own surface ranges with
-`clearcoat: 0`. This keeps rope and hardware uncoated even when they share the
-wood's atlas. The source example [native-crate-finish.js](https://github.com/Plasius-LTD/gpu-shared/tree/main/src/material-study-helpers/native-crate-finish.js)
-provides reviewed crate ranges and a deterministic wear preset combining existing
-roughness/scuff detail with broad UV patches. Its 0–1 wear control changes coat
-coverage and roughness without modifying the underlying colour or source asset.
-See [spatial coating decision](docs/adrs/adr-0032-spatial-native-clearcoat.md) and
-the [fixture/provenance record](docs/design/cc0-demo-asset-review.md). The example
-helper is source-only; the published API is the generic material map.
-
-For subtle rope fraying, the source-demo helper
-[native-rope-fibres.js](https://github.com/Plasius-LTD/gpu-shared/tree/main/src/material-study-helpers/native-rope-fibres.js) exports `createRopeFibres`.
-Pass the expanded native `vertices`, `texcoords` and explicit rope-only
-`{ firstVertex, vertexCount }` ranges. It returns separate triangles/UVs and a
-`fibreCount`; append them once with their own draw range. Generate in metre-scale
-world coordinates after transforms. Sampling is deterministic and area-weighted,
-with short tapered curves in small aligned tufts. `density` controls roots per
-square metre; `maxFibres` caps them at 4,000 (default 1,600). `length` and `radius`
-are in metres. The 21 triangles per strand use ordinary native multisampling,
-depth and lighting; no animated fur or dedicated hair scattering is claimed.
-
-Optional `fray` (0–1, default 0.08) promotes exactly
-`round(fibreCount * fray)` strands to longer curled loose ends, reported as
-`looseEndCount`. Selection is seeded and nested: raising the level keeps earlier
-loose ends, roots and UVs in place. At 0, short fuzz remains. This is a visual
-proportion of generated fibres, not lost rope strength.
-
-Use `createRopeFibreMaterial(ropeMaterial)` for the added range: it keeps the
-rope's colour map and zero clearcoat while omitting the core's baked occlusion
-and normal creases from exposed fibres. Vertex roughness is 1 and metallic is 0.
-The review fixture offers fibre on/off and both rope-detail views. See
-[ADR-0033](docs/adrs/adr-0033-demo-rope-fibres.md). These helpers remain source-only
-and do not add a renderer API, dependency or network request.
-
-### Material ageing review wrapper
-
-[material-ageing.js](https://github.com/Plasius-LTD/gpu-shared/tree/main/src/material-study-helpers/material-ageing.js) validates and freezes a serializable
-version-1 profile. [native-crate-ageing.js](https://github.com/Plasius-LTD/gpu-shared/tree/main/src/material-study-helpers/native-crate-ageing.js) applies it
-through the existing coating/fibre helpers:
-
-```js
-import { createCrateAgeing } from '@plasius/gpu-shared/material-study';
-
-const ageing = createCrateAgeing({ ropeFray: 0.30, varnishWear: 0.90, seed: 7349 });
-const { wood, rope, metal, fibres: fibreMaterial } = ageing.createMaterials(sourceMaps);
-const fibreGeometry = ageing.createFibres({ vertices, texcoords, ranges: ropeRanges, heightOffset: -minY });
-// Append fibreGeometry with fibreMaterial using the existing native draw contract.
-```
-
-Those values are also the review defaults. `varnishWear` is independent visual
-intensity, not coating area removed or elapsed years. Broad scuff patches expose
-wood while sheltered areas retain coating at intermediate wear. Above 70%, the
-remaining islands smoothly erode; at 100%, every coverage texel and the scalar
-coat strength are zero, matching varnish disabled. The original wood maps remain
-unchanged, including their ordinary substrate light response. `seed` controls fibre placement and
-loose-end selection; varnish uses its existing stable UV pattern. The crate adapter
-uses a 4.5 mm fibre length scale and 0.16 mm root radius, with a 4,000-fibre budget;
-loose ends are 1.3–2 times the length scale and taper to a point. Source images and
-geometry remain unchanged; rope, added fibres and metal never acquire clearcoat.
-
-Generate/copy geometry only when the fray channel changes; rebuild finish maps
-only when coating settings change. Camera movement reuses both. The caller still
-owns verified asset ranges, GPU resources and disposal. The local review includes
-fresh/aged presets, fibre/coat toggles and both handle-detail views.
-
-This is a tested source-demo wrapper, not a newly published package or a complete
-damage simulator. [ADR-0034](docs/adrs/adr-0034-material-ageing-profile.md) records
-the proposed `@plasius/material-ageing` boundary after a second asset establishes
-the shared contract. Production adoption retains `gpu-demo.scene-fidelity.enabled`
-and the existing GPU route capability; disabling the feature selects the existing
-site fallback. No package publication or site deployment is implied by this study.
-
-
-For structured nap, `createRopeFibres` accepts optional `guides`: at most eight
-polylines of 2–65 finite 3D points, in the same metre-scale coordinates as the
-input geometry. The nearest guide is projected onto the surface and given a
-consistent helical lay. Without a usable projected guide, a finite tangent
-fallback is used. Four nearby roots form a tuft within 1 mm of its anchor, with
-small angular variation, shallow lift and tapered tips. Sampling remains stable
-when fray changes; changing guides reauthors the groom.
-
-[native-crate-groom.js](https://github.com/Plasius-LTD/gpu-shared/tree/main/src/material-study-helpers/native-crate-groom.js) supplies the hash-verified
-fixture's loop/knot paths. Pass the same `heightOffset` used to ground its vertices
-(default 0 means unmodified asset coordinates); other transforms require matching
-transformed guide coordinates. The crate adapter adds 84,000 triangles: 90,578
-triangles / 271,734 vertices total, within the native default budget. Its final
-fibre arrays occupy 14,112,000 bytes. This deliberate denser nap replaces the
-previous 1,600-strand loose-end study. See [ADR-0035](docs/adrs/adr-0035-groomed-rope-and-bare-coat-endpoint.md).
-
-
-### In-scene material inspection camera
-
-The shared [native-demo-camera.js](https://github.com/Plasius-LTD/gpu-shared/tree/main/src/material-study-helpers/native-demo-camera.js) adapter uses
-released `@plasius/gpu-camera` state/control/projection APIs and the separate
-`@plasius/gpu-camera-controls` pointer gesture runtime/browser normalizer. It maps DOM input to
-orbit, camera-plane truck/pedestal, pan/tilt, dolly and optical zoom; camera math
-is not duplicated in the renderer. The camera and fixture adapters now belong to the isolated gpu-shared material-study
-entry; the renderer root does not load them.
-
-```js
-import { createNativeDemoCamera } from '@plasius/gpu-shared/material-study';
-
-// Supply a focusable canvas with an accessible name and persistent
-// aria-describedby instructions. The visual example is initially hidden,
-// aria-hidden, pointer-events:none and contains no interactive controls.
-const cameraControls = createNativeDemoCamera({
-  canvas,
-  camera: { eye: [-0.7, 0.5, 0.8], target: [0, 0.16, 0], fov: 42 },
-  onChange: () => draw(),
-  onHintChange: visible => { gestureExample.hidden = !visible; },
-});
-// Each draw uses camera: cameraControls.read(). Keep the controls alive across
-// renderer/material rebuilds; defer drawing while the renderer is unavailable.
-// At teardown (also cancels the hint timer):
-cameraControls.destroy();
-```
-
-The material review uses direct manipulation with no persistent camera toolbar.
-The optional `onHintChange` callback shows a brief example on canvas focus and
-hides it after five seconds, on blur, Escape or disposal. Refocus or `?` replays
-it; replay replaces the prior timer. The host owns visual presentation: show
-mouse/touch or keyboard examples, preserve a screen-reader description without a
-time limit, and respect reduced motion. Do not move the camera to demonstrate a
-gesture or let the example intercept input. Keep material controls below the scene.
-
-| Input | Camera action |
-| --- | --- |
-| Left-drag / one finger | Orbit, with the grabbed surface following the drag on both axes |
-| Right/middle/Shift-drag | Truck / pedestal across the current view |
-| Alt-drag | Pan / tilt in place |
-| Scroll / touch pinch | Move closer or farther (dolly) |
-| Shift-scroll | Change the lens (optical zoom) |
-| Two fingers moving together | Truck / pedestal |
-| Arrows / Shift-arrows | Selected keyboard mode / truck |
-| 1–5 | Select orbit, truck, pan, dolly or lens zoom for keyboard arrows |
-| +/− | Dolly (lens zoom in keyboard zoom mode) |
-| Home | Reset view |
-| ? / Escape | Replay / dismiss the brief guide |
-
-Vertical orbit follows the grab direction for mouse, one-finger touch and keyboard
-arrows. The adapter maps single-pointer orbit through gpu-camera; the shared
-gesture runtime retains original pointer coordinates for multi-pointer truck/pinch
-and stable transitions. Keyboard mode selection does not change mouse or touch gestures. The source-only
-`setMode`, `getMode`, `move` and `reset` methods remain available to host code.
-Browser Ctrl/Meta/Alt key shortcuts and keys outside the canvas are left alone.
-Wheel input only belongs to a focused canvas; the surrounding page remains
-scrollable. No inertia or animation loop is introduced. Distances, lens and travel
-are bounded; pointer cancellation/blur/disposal release captures and listeners.
-This is an inspection camera without scene collision detection or object picking.
-
-Native material normal-map degeneracy checks now use normalized screen-space
-position/UV gradients. Valid tiny derivatives in rope macro views no longer disable
-normal maps. Mirrored UV handedness and geometric-normal fallback for degenerate
-UVs are retained in the common direct/reflection shader. The shader contract tests
-require browser rendering evidence as well; Node mocks do not execute WGSL.
-See [ADR-0036](docs/adrs/adr-0036-in-scene-material-inspection.md).
-
-### Shared material-study runtime
-
-Production demo helpers and their regression tests now live in `@plasius/gpu-shared/material-study`. The renderer exposes `validateNativeSurfaceMaterials(materials)` so authoring and GPU creation use identical validation without allocation. See [ADR-0037](docs/adrs/adr-0037-shared-material-study-runtime.md).
-
-## Progressive still-frame refinement
-
-Create the wavefront renderer with `progressive: true` to retain linear radiance across frames. `samplesPerPixel` at creation is the maximum batch capacity; pass a smaller value to `renderOnce({ samplesPerPixel })` or `renderFrame({ samplesPerPixel })`. Submit batches serially. `renderFrame()` awaits completion by default; with `renderOnce()`, await `renderer.device.queue.onSubmittedWorkDone()` before reporting completed samples. `getSnapshot().accumulatedSamplesPerPixel` reports submitted history samples.
-
-Camera or scene updates reset history automatically; `resetAccumulation()` also discards it without reallocating. Do not call `updateCamera()` between refinement passes unless the view changed. Progressive mode uses independent frame seeds, overriding static-frame stable sample routing. Denoising is applied after accumulation. Leave `progressive` unset for the existing independent-frame path. See [ADR 0038](docs/adrs/adr-0038-progressive-linear-radiance.md) for memory costs and host rollout responsibilities.