@plasius/gpu-renderer 0.2.46 → 0.2.48

package/CHANGELOG.md

@@ -23,6 +23,57 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
+## [0.2.48] - 2026-10-11
+
+- Expose native material preflight validation and transfer the reviewed demo adapters plus their tests to the shared material-study runtime for production reuse (#230).
+
+- Correct vertical grab direction in the material-review camera for mouse, touch and keyboard orbit; preserve horizontal, pan and zoom directions (#230).
+
+- Replace the material review camera toolbar with a five-second focus gesture guide; keep direct mouse/touch movement independent of keyboard modes, with replay and dismissal (#230).
+
+- Update the existing brace-expansion development override to 5.0.12 for patched denial-of-service advisories (#230).
+
+- Fix native normal maps losing detail at close range; add a source-demo camera adapter using shared orbit, truck, pan, dolly and zoom controls with keyboard/touch support (#230).
+
+- Fix full varnish wear to exactly match the uncoated endpoint; replace random rope strands with shorter, finer guide-aligned tufts and bounded denser nap (#230).
+
+- Add a versioned material-ageing profile and crate adapter with independent 30% rope fraying / 90% varnish-wear review defaults; preserve fibre roots across wear edits and retain coating islands within heavily scuffed wood (#230).
+
+- Add bounded, deterministic curved rope fibres to the chest review fixture, with matte exposed-fibre materials and comparison/detail views (#230).
+
+- Support spatial clearcoat coverage and roughness maps; keep the crate fixture's rope and hardware uncoated and vary its wood varnish with a deterministic wear preset (#230).
+
+- Separate optional neutral varnish/clearcoat reflection from the coloured native surface, with independent roughness and Fresnel attenuation (#230).
+
+- Add bounded, mip-filtered authored colour, normal and ORM materials to native surfaces, with optional UVs and draw ranges shared by the main and reflection passes (#230).
+
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+## [0.2.47] - 2026-10-09
+
+- **Added**
+  - Added `createCanonicalWavefrontMeshInputs` to adapt decoded canonical model
+    geometry, material factors, and texture samples to Wavefront renderer inputs.
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
 ## [0.2.46] - 2026-09-29
 
 - Add native showcase surface drawing with filtered shadows, HDR planar water
@@ -1149,3 +1200,5 @@ All notable changes to this project will be documented in this file.
 [0.2.44]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.44
 [0.2.45]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.45
 [0.2.46]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.46
+[0.2.47]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.47
+[0.2.48]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.48

package/README.md

@@ -129,6 +129,41 @@ renderer.resize(window.innerWidth, window.innerHeight);
 renderer.start();
 ```
 
+## 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.
+
+```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
@@ -751,3 +786,198 @@ 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).