@headless-three/renderer 0.1.7 → 0.1.8

package/README.md

@@ -2,7 +2,7 @@
 
 Headless `wgpu` renderer for Three.js scenes in Node.js.
 
-This package exists for Node.js environments where WebGL is not available. You build or load a normal Three.js scene, pass the `THREE.Scene` and `THREE.Camera` to this package, and the native addon renders it with `wgpu`.
+This package exists for Node.js environments where WebGL is not available. You build or load a normal Three.js scene graph, pass the `THREE.Scene` or `THREE.Object3D` root and `THREE.Camera` to this package, and the native addon renders it with `wgpu`.
 
 ```bash
 npm install @headless-three/renderer three
@@ -32,15 +32,14 @@ const imageBuffer = render(scene, camera, {
 fs.writeFileSync('render.png', imageBuffer)
 ```
 
-With `GLTFLoader`, render the loaded Three.js scene directly:
+With local glTF/GLB assets, render the loaded root directly:
 
 ```js
 import fs from 'node:fs'
 import * as THREE from 'three'
-import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
-import { render } from '@headless-three/renderer'
+import { loadGltfFromFile, render } from '@headless-three/renderer'
 
-const gltf = await new GLTFLoader().loadAsync('./model.glb')
+const gltf = await loadGltfFromFile('./model.glb')
 
 const camera = new THREE.PerspectiveCamera(45, 1, 0.01, 100)
 camera.position.set(2, 1.5, 4)
@@ -54,6 +53,11 @@ const imageBuffer = render(gltf.scene, camera, {
 fs.writeFileSync('render.png', imageBuffer)
 ```
 
+For local Node.js glTF/GLB loading with external buffers or texture files, see
+the [Node loader setup guide](https://github.com/portwatcher/headless-three-renderer/blob/main/docs/node-loader-setup.md).
+The repository also includes a runnable
+[local glTF example](https://github.com/portwatcher/headless-three-renderer/blob/main/examples/render-gltf.mjs).
+
 The module exports a convenience `render(scene, camera, options)` function and a reusable `Renderer` class:
 
 ```js
@@ -62,46 +66,192 @@ const renderer = new Renderer()
 const imageBuffer = renderer.render(scene, camera, { width: 512, height: 512 })
 ```
 
+`Renderer.renderAsync(scene, camera, options)` is a Promise-returning compatibility wrapper around the same scene-output contract.
+
+`Renderer.sortObjects`, `Renderer.opaque`, `Renderer.transparent`, `Renderer.setOpaqueSort(fn)`, `Renderer.setTransparentSort(fn)`, and the matching `render()` options (`sortObjects`, `opaque`, `transparent`, `opaqueSort`, `transparentSort`) control native draw-list sorting and bucket inclusion; invalid option or setter values fail clearly.
+`Renderer.opaque` and `Renderer.transparent` are validated CommonRenderer compatibility flags that gate opaque and transmissive/transparent bucket rendering.
+
+It also exports Node loader helpers:
+
+- `applyVrmAnimation(vrm, vrmAnimation, options)`: creates a VRMA animation clip with `createVRMAnimationClip`, accepting either direct VRM/VRMA objects or the glTF wrappers returned by `loadVrmFromFile()`/`loadVrmAnimationFromFile()`, selects wrapper animations with `options.animationIndex`, seeks a `THREE.AnimationMixer` to `options.time` through `setTime()` or `update()` fallback, and updates the VRM scene for still-frame rendering unless `updateVrm: false` is passed.
+- `loadGltfFromFile(filePath, options)`: loads local `.gltf` or `.glb` files from relative paths, absolute paths, or `file://` URLs with encoded texture handlers and local `file://` buffer support already installed; malformed helper paths, option containers, and glTF image metadata fail clearly.
+- `loadVrmFromFile(filePath, options)`: loads local VRM files with `@pixiv/three-vrm`'s `VRMLoaderPlugin` registered. The Pixiv package remains an optional dependency in your project.
+- `loadVrmAnimationFromFile(filePath, options)`: loads local VRMA files with `@pixiv/three-vrm-animation`'s `VRMAnimationLoaderPlugin` registered. The animation package remains optional.
+- `createNodeGltfLoader(rootDir, options)`: creates a configured `GLTFLoader` bundle for advanced flows, including plugin registration through `options.configureLoader`, encoded-buffer image handlers, local `file://` fetch support, a loader path rooted at `rootDir` for direct `loader.load('model.gltf')` calls, and the narrow WebP `Image` support probe used by `EXT_texture_webp` detection; `rootDir` accepts relative paths, absolute paths, and `file://` URLs, and malformed helper boolean options, callback hooks, and custom managers fail clearly.
+- `createEncodedImageTextureLoader(rootDir, manager)` / `EncodedImageTextureLoader`: a `LoadingManager` image handler with `load()` and `loadAsync()` for local PNG/JPEG/WebP files, PNG/JPEG/WebP data URIs, and PNG/JPEG/WebP Blob URLs that exposes encoded buffers directly to renderer-supported texture slots, reports optional manager item start/end/error hooks, honors `resolveURL()` URL modifiers, and resolves `setPath()` directory prefixes for relative, absolute, and `file://` paths without rewriting data, Blob, absolute, or fully-qualified asset URLs; `rootDir` accepts relative paths, absolute paths, and `file://` URLs, and malformed helper paths, callbacks, and manager objects fail clearly.
+- `installLocalFileFetch()`: a small `file://` fetch bridge for Three.js `FileLoader` when loading local external glTF buffers.
+- `resolveLocalAssetPath(url, rootDir)`: shared path resolution for local loader helpers, covering relative paths under relative, absolute, or `file://` roots plus POSIX/Windows absolute paths and `file://` asset URLs while rejecting remote asset/root URLs.
+
 ## Supported Three.js Surface
 
+See the versioned [compatibility matrix](https://github.com/portwatcher/headless-three-renderer/blob/main/docs/compatibility.md) for the public support contract, known gaps, and platform package status. Scale-test budgets and platform notes are documented in [docs/scale-budgets.md](https://github.com/portwatcher/headless-three-renderer/blob/main/docs/scale-budgets.md).
+
 The public API accepts only Three.js-like objects:
 
-- `scene`: a `THREE.Scene`.
-- `camera`: a `THREE.Camera`, including perspective and orthographic cameras.
-- `options.width` and `options.height`: output pixel size. Defaults to `512 x 512`.
-- `options.background`: `[r, g, b]`, `[r, g, b, a]`, or a `THREE.Color`. Defaults to `scene.background` when it is a color.
-- `options.format`: `'png'` by default, or `'rgba'` for raw RGBA8 bytes.
+- `scene`: a `THREE.Scene` or `THREE.Object3D` root; malformed scene/children containers and visibility flags fail clearly.
+- `camera`: a `THREE.Camera`, including perspective and orthographic cameras. Malformed camera/userData containers, invalid aspect-derived dimensions, clipping distances, and matrix containers or values fail clearly. `THREE.ArrayCamera` composes sub-camera viewports for PNG, raw RGBA, and target output, with malformed sub-camera containers failing clearly. `THREE.CubeCamera` renders six RGBA faces plus optional depth faces into `WebGLCubeRenderTarget.texture.image`/`source.data`, nonzero `activeMipmapLevel` writes the active mip entry, `Renderer.getActiveCubeFace()`/`getActiveMipmapLevel()` expose reusable cube-target state, `CubeCamera.update(renderer, scene)` works with the reusable renderer's minimal target state while preserving inert `Renderer.xr` enabled/cameraAutoUpdate/framebuffer-scale/controller/reference-space/session/base-layer/binding/frame/environment/depth-texture/depth/foveation/camera-texture/event-target dispatch probes, and captured color textures can be reused as cube background/environment inputs; real XR session binding and malformed child-camera containers fail clearly, while exact WebGL face semantics remain limited.
+- `options`: an options object; malformed option containers fail clearly.
+- `options.width` and `options.height`: output pixel size. Defaults to `512 x 512`; invalid explicit dimensions fail clearly.
+- `options.background`: `[r, g, b]`, `[r, g, b, a]`, a CSS color string, a `THREE.Color`, a supported 2D/equirectangular/cube texture, or `null` to clear `scene.background` for one render. Defaults to `scene.background`; option-supplied backgrounds use option-supplied background controls rather than scene background controls, and malformed scene or option background values fail clearly.
+- `options.backgroundIntensity`: overrides `scene.backgroundIntensity` for supported color and texture backgrounds; invalid values fail clearly.
+- `options.backgroundBlurriness`: overrides `scene.backgroundBlurriness` for supported texture backgrounds; invalid values fail clearly.
+- `options.backgroundRotation`: overrides `scene.backgroundRotation` for supported equirectangular and cube texture backgrounds; explicit option rotation values are always validated, and invalid or unsupported rotations fail clearly.
+- `options.environmentIntensity`: overrides `scene.environmentIntensity` or reflection-probe intensity for supported scene environments; invalid values fail clearly.
+- `options.environmentRotation`: overrides `scene.environmentRotation` for supported scene environments; explicit option rotation values are always validated, and invalid values fail clearly.
+- `options.viewport`: `[x, y, width, height]` or `{ x, y, width, height }` output pixel rectangle, using a top-left origin, for viewport-limited draws; invalid rectangles fail clearly.
+- `options.scissor`: `[x, y, width, height]` or `{ x, y, width, height }` output pixel rectangle, using a top-left origin, for scissor-clipped draws; invalid rectangles fail clearly.
+- `options.clippingPlanes`: global world-space clipping planes for the render; reusable `Renderer.clippingPlanes` provides the same value as a renderer-state fallback.
+- `options.localClippingEnabled`: `false` disables material-local clipping planes while preserving global clipping planes; reusable `Renderer.localClippingEnabled` provides the same value as a renderer-state fallback, defaults to `true`, and invalid values fail clearly.
+- `options.format`: `'png'` by default, or `'rgba'` for raw RGBA8 bytes; unsupported values fail clearly.
+- `options.outputColorSpace`: `THREE.SRGBColorSpace` (`'srgb'`, default) or `THREE.LinearSRGBColorSpace` (`'srgb-linear'`, `'linear-srgb'`, `'linearsrgb'`, or `'linear'`) for material and texture background output conversion; reusable `Renderer.outputColorSpace`, `currentColorSpace`, and `_outputColorSpace` provide the same value as a renderer-state fallback, and unsupported values fail clearly.
+- `options.renderMode`: `'color'` by default, `'mask'` for white visible geometry on black, `'object-id'` for flat RGB object IDs, `'normal'` for view-space normal colors, or `'depth'` for normalized grayscale depth; invalid values fail clearly.
+- `options.target`: a non-array target-like object populated for a color output, including actual `THREE.RenderTarget`/`THREE.WebGLRenderTarget` instances, `target.texture`, `target.textures[0]`, one-element `target.texture` arrays, or MRT-shaped targets. `Renderer.setRenderTarget(target); renderer.render(...)` supports the same regular target writeback through minimal reusable-renderer target state, and `Renderer.readRenderTargetPixels()`/`readRenderTargetPixelsAsync()` can copy stored target color data, explicit cube target faces, or selected color attachment indices into caller-provided buffers. Async readback can allocate a matching output buffer and accepts the common-renderer `(target, x, y, width, height, textureIndex, faceIndex)` argument shape. Top-level `target.data` remains raw RGBA8; color textures can also request Alpha/Luminance/LuminanceAlpha/Red/RG/RGB/RGBA and RedIntegerFormat/RGIntegerFormat/RGBIntegerFormat/RGBAIntegerFormat plus normalized `FloatType`, signed/unsigned integer, packed color, or `HalfFloatType` readback arrays. Regular-camera, ArrayCamera, and CubeCamera MRT-shaped targets can populate secondary texture attachments when each secondary texture declares `texture.userData.headlessThreeRenderer.renderMode` as `'color'`, `'mask'`, `'object-id'`, `'normal'`, or `'depth'`; `Renderer.getMRT()` returns `null`, `Renderer.setMRT(null)` is accepted as a clear operation, and non-null `Renderer.setMRT()` fails clearly because native MRT shader outputs are not supported.
+- `options.postProcessing`: built-in post effects (`exposure`, `contrast`, `saturation`, `vignette`, `grayscale`, `invert`); malformed containers and invalid effect values fail clearly.
 
 ### Geometry & Scene
 
-- `THREE.Mesh` and `THREE.SkinnedMesh`
-- `THREE.BufferGeometry` positions, indices, normals, and UV coordinates
-- geometry groups with material arrays
-- mesh world transforms
-- vertex colors
-- scene background color
+- `THREE.Mesh` and `THREE.SkinnedMesh`, including WebGL-style bounding-sphere frustum culling with `frustumCulled=false` opt-out
+- `THREE.InstancedMesh` with `instanceMatrix` and `instanceColor`; invalid explicit instance counts fail clearly
+- `THREE.InstancedBufferGeometry` for mesh, point, line, and dashed-line geometry with common offset/scale/color attributes, selected instanced UV attributes, Three.js' default `instanceCount = Infinity`, and `meshPerAttribute` repeat values; invalid explicit instance counts, per-attribute repeat values, and custom WGSL fragment materials paired with unsupported arbitrary instanced vertex attributes fail clearly
+- `THREE.BatchedMesh` common packed-geometry batches are CPU-expanded with per-instance matrices, colors, visibility flags, deleted/inactive instance entries, deleted/inactive packed geometry ranges, packed geometry groups/material arrays including missing `materialIndex` fallback to material zero, partial range/group intersections, and translated multi-source group offsets, common per-object sphere frustum culling including combined object/instance transforms, range-local internal sorting including transparent material-array groups, `sortObjects=false`, and `customSort` callback context/camera/list handling; malformed batch internals including packed matrix/color texture containers or non-finite packed values, instance table entries, cached culling bounds, culling controls, and sort controls fail clearly, while broader exact culling/source-group edge cases and native batched drawing remain planned
+- `THREE.BufferGeometry` positions, indices, normals, and UV coordinates, with malformed attribute/data/bounding-sphere containers and invalid attribute values failing clearly
+- `THREE.Sprite`/`SpriteMaterial` CPU billboards with center, scale, rotation, perspective size attenuation controls, opacity, texture and alpha maps with sRGB color-space decode plus nearest/linear filtering, `alphaHash` and `alphaToCoverage` opacity cutouts, scene fog, layers, render ordering, frustum culling, main-pass clipping, directional/spot/point shadow casting, directional/spot custom-depth cutouts, point custom-distance shadow cutouts, and custom/source base-map and alpha-map texture transforms on directional custom-depth and point custom-distance shadow paths; invalid billboard scalar and size-attenuation values fail clearly
+- geometry groups with material arrays, with malformed material containers failing clearly
+- mesh world transforms, object visibility and `frustumCulled` flags, and object/camera layer containers/masks, with invalid transform matrix, visibility, culling, or layer values failing clearly
+- `THREE.LOD` camera-distance/zoom level selection, with invalid auto-update flags, camera zoom, or level distance/hysteresis values failing clearly
+- vertex colors, with invalid `material.vertexColors` values failing clearly
+- scene background color plus reusable `Renderer.setClearColor()`/`setClearAlpha()` fallback state with hex, CSS string, and color-like clear-color inputs, CSS string scene/option background colors, and 2D, equirectangular, raw, encoded, CubeUV-mapped readable six-face cube, and packed 2D PMREM/CubeUV sharp-atlas texture backgrounds with `backgroundIntensity`, approximate texture blur, equirectangular/cube `scene.backgroundRotation`/`options.backgroundRotation`, `options.environmentIntensity`, and equirectangular/cube `scene.environmentRotation`/`options.environmentRotation`; invalid background color/control/rotation values, invalid renderer clear-color values, malformed packed PMREM/CubeUV background layouts, and unsupported background rotations fail clearly
+- render-option viewport/scissor rectangles, render-target dimensions and viewport/scissor fields, reusable `Renderer.setSize()`/`getSize()` plus `setDrawingBufferSize()`/`getDrawingBufferSize()` and `setPixelRatio()`/`getPixelRatio()` compatibility state including WebGLRenderer-style `setPixelRatio(undefined)` no-op, inert `Renderer.domElement` output/client-size/style mirror plus style-property, attribute, event-target, and canvas-export probes, `Renderer.outputColorSpace`/`currentColorSpace`/`_outputColorSpace` output-conversion state, read-only `Renderer.coordinateSystem` WebGL coordinate signal, `Renderer.toneMapping`/`currentToneMapping`/`toneMappingExposure` material tone-mapping state plus `Renderer.needsFrameBufferTarget=false` inline-output probe, `Renderer.clippingPlanes` global clipping fallback state, `Renderer.localClippingEnabled` material-local clipping state, `Renderer.info` inert compatibility counters with WebGLInfo- and CommonRenderer-style `update()`/`updateTimestamp()`/`reset()`/`dispose()` and installed Three.js info-surface drift coverage, inert `Renderer.debug` shader-diagnostic state, inert `Renderer.inspector` lifecycle and copy-hook state, conservative `Renderer.capabilities` WebGL limit, reverse-depth, draw-buffer, texture probes, and renderer-level `getMaxAnisotropy()`, and conservative `hasFeature()`/`hasFeatureAsync()`/`hasCompatibility()` plus `isOccluded()` probes, inert `Renderer.extensions`, scratch `Renderer.properties`/`renderLists`/`renderStates` helpers including `renderLists.lighting`, inert `Renderer.state` buffer and state-level setter probes with raw WebGL binding/upload failures, inert `Renderer.xr` enabled/cameraAutoUpdate/framebuffer-scale/controller/reference-space/session/base-layer/binding/frame/environment/depth-texture/depth/foveation/camera-texture/event-target dispatch probes, validated inert WebGLRenderer-style constructor parameters for common context attributes plus read-only `alpha`/`depth`/`stencil`/`logarithmicDepthBuffer` metadata, CommonRenderer-style `isRenderer`/`initialized` probes, `highPrecision=false` metadata with `true` failing clearly, `samples`/`currentSamples`/`isOutputTarget` sample/output-target probes, default `outputBufferType` with `getOutputBufferType()`/`getColorBufferType()`, cloned `getContextAttributes()` readback, and clear `getContext()` unsupported failures, `setViewport()`/`getViewport()`/`getCurrentViewport()` and `setScissor()`/`setScissorTest()` state in output pixel coordinates with default-only common-renderer viewport depth-range validation, `Renderer.shadowMap.enabled` shadow gating plus `shadowMap.autoUpdate`/`needsUpdate`/`type` compatibility state and no-op `shadowMap.render()` probe, clear color/depth/stencil value state, material-set `compile()`/`compileAsync()` compatibility hooks, no-op `init()`/`initRenderTarget()`/`initTexture()`/`initTextureAsync()`/`hasInitialized()`/`clear()`/`clearAsync()`/`clearTarget()`/`clearColor()`/`clearColorAsync()`/`clearDepth()`/`clearDepthAsync()`/`clearStencil()`/`clearStencilAsync()`/`resetState()`/`resetGLState()`/`dispose()`/`forceContextLoss()`/`forceContextRestore()`/`setAnimationLoop()`/`getAnimationLoop()` hooks, and no-op `autoClear`/`autoClearColor`/`autoClearDepth`/`autoClearStencil` flags for pass-owned buffers and object-lifetime native cleanup; `getContext()`, `domElement.getContext()`, `domElement` canvas export/capture APIs, `setRenderTargetTextures()`, `setRenderTargetFramebuffer()`, and real `Renderer.xr.setSession()` binding fail clearly because this package has no browser WebGL/WebXR context or external WebGL texture/framebuffer binding; `copyFramebufferToTexture()` supports source-rectangle CPU copies from the active render target or cube-face readable color data into readable raw texture base or mip levels, including WebGLRenderer legacy position-first argument compatibility, and fails clearly without an active readable target, with out-of-bounds source rectangles, oversized destinations, channel mismatches, FramebufferTexture/DepthTexture/VideoTexture/StorageTexture/compressed destinations, or invalid mip levels; `copyTextureToTexture()` supports base/mip CPU copies from readable raw, canvas-like, or OffscreenCanvas-backed source textures into readable raw destination textures, including WebGLRenderer legacy destination-position-first and single-mip-level argument compatibility, and fails clearly for unreadable, out-of-bounds, channel-mismatched, array/3D texture, compressed texture, FramebufferTexture/DepthTexture/VideoTexture/StorageTexture, non-raw destination, or invalid mip-level inputs. Invalid sizes, size updateStyle flags, pixel ratios, non-default viewport depth ranges, constructor parameters including constructor-level `samples > 1` or non-default `outputBufferType`, output color spaces, tone-mapping constants/exposure values, clipping plane values/booleans, compile material values, info booleans/update/timestamp values, debug values, inspector values, capability/extension/property/render-list/render-state/state probes, DOM style/attribute/event/canvas probes, XR booleans/values/events/controller/reference-space binding, shadow-map booleans/type constants, shadow-map render inputs, clear values/booleans, resource-init targets/textures, external WebGL texture/framebuffer handles, copy targets, unsupported texture-copy inputs, animation-loop callbacks, auto-clear flags, and malformed target scissor flags fail clearly
+- the installed Three.js `WebGLRenderer` and CommonRenderer callable method surfaces are regression-audited so new upstream renderer methods become explicit compatibility work
+- the installed Three.js `WebGLExtensions`, `WebGLCapabilities`, `WebGLProperties`, `WebGLRenderStates`, `WebGLShadowMap`, and `WebXRManager` helper surfaces are regression-audited so new helper probes become explicit compatibility work
+- `Renderer.renderLists` exposes scratch WebGLRenderList-style depth-keyed lists, CommonRenderer-style camera-keyed lists, and a ChainMap-style `renderLists.lists` probe with opaque, transmissive, transparent, transparent double-pass, bundle, light, occlusion-query, clipping-context, render-item, and lighting-node bookkeeping for helper compatibility; installed CommonRenderer node, lighting, render-list, and render-lists surfaces are regression-audited
+- `Renderer.shadowMap.transmitted` is accepted as validated boolean compatibility state alongside `shadowMap.autoUpdate`, `shadowMap.needsUpdate`, `shadowMap.type`, and no-op `shadowMap.render()` input validation
+- `Renderer.debug.getShaderAsync()` validates scene, camera, and object inputs but fails clearly because generated backend shader source is not exposed
+- `Renderer.onDeviceLost` is assignable callback state for CommonRenderer compatibility; `Renderer.isDeviceLost` reports direct/default device-loss callback dispatch state and `forceContextRestore()` clears the diagnostic flag, while native device-loss event delivery remains outside the scene-oriented contract
+- `Renderer.backend` exposes inert CommonRenderer backend probes for backend type flags, coordinate-system/readback metadata, lifecycle begin/finish/update hooks, scissor/occlusion/clear-color probes, disabled timestamp-query setup probes, feature/anisotropy checks, drawing-buffer size, `domElement`/`getDomElement()` access, cleanup/cache-key probes, and scratch backend data; direct backend context, clear, render-pass/framebuffer, render-bundle, draw/program/binding/pipeline/node-builder/texture/attribute/copy, shader-diagnostic, VAO/transform-feedback/uniform-binding, indirect-storage, storage-buffer readback, timestamp resolution, and GPU-sync operations fail clearly, with the installed Three.js CommonRenderer `Backend` method surface regression-audited for coverage drift
+- `Renderer.nodes`, `Renderer.library`, and `Renderer.lighting` expose inert CommonRenderer shader-node registry, DataMap-style node cache, node-frame/output-node, node-library registration, ChainMap-style lighting cache helpers, and lighting-node compatibility state, including clear shader-node lifecycle failures and the shared default QuadMesh lighting-node probe; actual Three.js shader graph translation still requires the documented custom WGSL path
+- `Renderer.setEffects()` is accepted as a validated no-op WebGLRenderer compatibility hook; use `options.postProcessing` for actual effects
+- Three.js examples `Pass` exposes standard base pass state and `FullScreenQuad` renders supported built-in materials through this renderer's normal object/camera render path into active targets
+- Three.js examples `Addons.js` barrel imports in Node and exposes covered helper modules; individual helper behavior remains governed by the documented helper-specific rows rather than by barrel import alone
+- Three.js examples `Projector` can generate CPU render-data objects for supported mesh, line, point, sprite, and light inputs while the source scene objects continue to render through the normal renderer path
+- Three.js examples `CSS2DRenderer` and `CSS3DRenderer` maintain browser DOM overlay sizing, parentage, transforms, z-order, and draggable state for CSS overlay objects when browser-style DOM creation is supplied, with no-browser-document construction covered as a clear dependency failure
+- Three.js examples `SVGRenderer` can serialize supported `Projector` mesh, line, and `SVGObject` paths into browser-style SVG DOM nodes when `document.createElementNS()` is supplied, with no-browser-document construction covered as a clear dependency failure; the package's image output still renders through the native scene path rather than serializing SVG DOM
+- Three.js examples `SVGLoader` requires a browser-style `DOMParser` in plain Node before callers can convert parsed shapes into renderer-supported geometry
+- Three.js examples transpiler utilities can build AST nodes, decode simple GLSL and ShaderToy snippets, and emit Three.js TSL source through `TSLEncoder`/`Transpiler`; this is source-to-source utility coverage rather than renderer shader-material translation support
+- `Renderer.transmissionResolutionScale` is stored as positive finite WebGLRenderer compatibility state and `options.transmissionResolutionScale` can override it for a single render; both scale the scene-color texture sampled by physical transmission
+- `Renderer.isWebGLRenderer` is exposed for Three.js helper branches that use WebGLRenderer-compatible readback signatures, while `Renderer.isWebGPURenderer` is explicitly `false` so WebGPU-only loader/exporter branches do not assume a browser/CommonRenderer backend; covered WebGL-style helper paths include `LightProbeGenerator.fromCubeRenderTarget()` cube-target readback, standard CopyShader `ShaderPass`/`TexturePass`/`SavePass` fullscreen flows, `OutputPass` fullscreen output-copy flow, `StereoEffect`/`PeppersGhostEffect` scissored camera helpers, `AnaglyphEffect`/`ParallaxBarrierEffect` internal shader clear failures, `ShadowMapViewer` depth-unpack shader clear failure coverage, CurveExtras/NURBS generated geometry paths, examples modifier/utility-generated geometry paths, examples ConvexObjectBreaker debris geometry paths, examples LDrawUtils merged geometry paths, examples SceneUtils/MeshSurfaceSampler utility paths, examples SceneOptimizer BatchedMesh output paths, examples Gyroscope transform-helper paths, examples Lut/ColorConverter/noise math utility paths, examples collision math utility geometry paths, examples morph animation helper paths, examples GeometryUtils/TubePainter generated geometry paths, examples SkeletonUtils cloned skinned mesh paths, examples AnimationClipCreator mixer-applied still-frame paths, examples CCDIKSolver helper visualization paths, examples CameraUtils off-axis camera paths, and `EXRExporter`/`KTX2Exporter` render-target export paths, while WebGL context access still fails clearly
+- Three.js examples `AsciiEffect` can delegate `setSize()`/`render()` to this renderer and maintain generated table-based ASCII DOM output when browser-style `document.createElement()` plus canvas 2D image data are supplied; no-browser-document construction is covered as a clear DOM dependency failure
+- Three.js examples WebGL/WebGPU capability helpers report unavailable browser contexts in plain Node and can build browser warning elements or probe caller-provided fake canvas/context objects when `window`/`document` shims are supplied; actual renderer capability state remains exposed through `Renderer.capabilities`, `hasFeature()`, and `hasFeatureAsync()`
+- Three.js examples offscreen demo modules wire their DOM jank toggle with browser-style `document.getElementById()` shims, and their worker/scene entrypoints reach Three.js' browser `ImageBitmapLoader`/offscreen WebGL dependency boundary clearly in plain Node
+- Three.js examples physics helpers import in Node and expose their external-engine boundaries: `AmmoPhysics` requires a browser-style `window` plus global Ammo.js, while `JoltPhysics` and `RapierPhysics` require CDN ESM/WASM imports that Node's default loader rejects unless callers bundle or provide those engines
+- Three.js examples WebXR `ARButton`, `VRButton`, and `XRButton` build DOM fallback messages and session-control buttons with browser-style `document`, `window`, and `navigator.xr` shims; real XR session binding remains outside this renderer's Node scene-output contract
+- Three.js examples WebXR hand/controller helpers can build and update local controller models, primitive hand joint meshes, Oculus hand mesh state, and Oculus hand pointer geometry through supported `Object3D`, `InstancedMesh`, and built-in material paths; remote WebXR input-profile assets remain caller-managed
+- Three.js examples WebXR `XRPlanes` can convert detected plane events into renderable built-in mesh plane geometry, and `XREstimatedLight` maps WebXR light-estimate frames into `LightProbe` plus `DirectionalLight` state while browser XR session and reflection-cubemap binding remain outside the Node renderer contract
+- `KTX2Loader.detectSupport()` stays on Three.js' WebGL extension-probe branch because `Renderer.isWebGPURenderer` is false, while `detectSupportAsync()` reads conservative compression feature probes; both report all compressed texture families unsupported, so decode KTX2/Basis assets to readable 2D texture payloads before rendering
+- Three.js examples `RGBELoader` decodes Radiance HDR buffers into float or half-float data that can be wrapped in renderer-readable 2D `DataTexture` material/background/environment payloads
+- Three.js examples `TGALoader` decodes TGA buffers into RGBA byte data that can be wrapped in renderer-readable 2D `DataTexture` material/background payloads
+- Three.js examples `LUT3dlLoader` and `LUTCubeLoader` parse 3D LUT metadata into `Data3DTexture` outputs, and those outputs fail clearly in material texture slots because this renderer supports 2D readable texture payloads there, not 3D LUT sampling
+- Three.js examples `IESLoader` parses specialized photometric lookup `DataTexture` outputs for IES lighting workflows, and those outputs fail clearly in material texture slots because their payload shape is not a renderer-readable 2D material texture
+- `GPUComputationRenderer` reaches its conservative renderer capability check and returns Three.js' `No support for vertex shader textures.` result because the scene-oriented renderer does not expose GPU texture-ping-pong compute passes
+- Three.js examples `TiledLighting` can split point lights into tiled-light metadata and non-point lights into regular material-light metadata, but its TSL/WebGPU compute update path fails clearly through `Renderer.compute()` because clustered GPU lighting remains outside the scene-oriented renderer contract
+- `CSM` can create its cascaded directional lights and patch materials, then fails clearly on its `onBeforeCompile` shader-chunk injection with guidance to use regular supported lights/shadows, baked cascaded shadowing, or custom WGSL; `CSMFrustum` splits and transforms cascade frusta, `CSMShader` exposes its CSM shader chunks, `CSMShadowNode` can initialize WebGPU cascade-light state, and `CSMHelper` visualization geometry renders through supported built-in line/basic materials
+- Core Three.js helpers using supported line/basic materials render directly, including axes/grid/box/plane/arrow/camera/skeleton and common light helper geometry, with the installed core `THREE.*Helper` export set regression-audited for coverage drift
+- Three.js examples `VertexNormalsHelper` and `VertexTangentsHelper` recompute helper line geometry from source mesh attributes and render through supported `LineSegments` plus `LineBasicMaterial` paths
+- Three.js examples geometry generators `ConvexGeometry`, `RoundedBoxGeometry`, `DecalGeometry`, `ParametricGeometry`, `ParametricGeometries` presets, `InstancedPointsGeometry`, `BoxLineGeometry`, `TeapotGeometry`, and `TextGeometry` produce CPU-side `BufferGeometry`/`InstancedBufferGeometry` that renders through supported built-in mesh and line material paths, including `FontLoader`/`TTFLoader` parsed example fonts
+- Three.js examples geometry modifiers/utilities `EdgeSplitModifier`, `SimplifyModifier`, `TessellateModifier`, `BufferGeometryUtils.mergeGeometries()`, `ConvexObjectBreaker.cutByPlane()`, and `LDrawUtils.mergeObject()` produce CPU-transformed, generated, or merged mesh/line `BufferGeometry` that renders through supported built-in material paths, including preserved merge groups, debris metadata, and LDraw construction-step metadata
+- Three.js examples `GeometryCompressionUtils` packed position, normal, and UV attributes fail clearly with decode guidance because this renderer does not translate the shader-side packed-attribute decode path
+- Three.js examples `CurveModifier.Flow` and `CurveModifier.InstancedFlow` fail clearly on their `onBeforeCompile` shader-injection path with custom WGSL guidance, while `CurveModifierGPU.Flow` can generate packed spline textures and attach TSL material hooks that fail clearly because material node hooks are not translated
+- Three.js examples scene and sampling utilities `SceneUtils.createMeshesFromMultiMaterialMesh()`, `SceneUtils.createMeshesFromInstancedMesh()`, `SceneUtils.reduceVertices()`, visible/ancestor traversal generators, and `MeshSurfaceSampler` produce renderable groups or sampled point geometry through supported mesh and point material paths
+- Three.js examples `SceneOptimizer.toBatchedMesh()` batches compatible mesh children into a `BatchedMesh` that renders through the supported packed-geometry CPU expansion path with per-instance colors
+- Three.js examples `SortUtils.radixSort()` can order renderer-visible `BatchedMesh.customSort` draw lists before rendering
+- Three.js examples `WorkerPool` can coordinate deterministic pre-render work and feed still-frame mesh state that renders through supported built-in material paths
+- Three.js examples `Gyroscope` preserves child world orientation under transformed parents while the child renders through normal scene traversal and built-in material paths
+- Three.js examples `Timer` and `FixedTimer` can drive deterministic still-frame transform state before rendering
+- Three.js examples math utilities `Lut`, `ColorConverter`, `ImprovedNoise`, `SimplexNoise`, `Capsule`, `ConvexHull`, `OBB`, and `Octree` produce `THREE.Color` values, point paths, or collision/bounds-derived line and mesh geometry that render through supported material, vertex-color, line, and mesh paths
+- Three.js examples `ColorSpaces` Display-P3 and Rec.2020 constants fail clearly outside the current `THREE.SRGBColorSpace`/`THREE.LinearSRGBColorSpace` output and texture color-space contract
+- Three.js examples `MorphAnimMesh`, `MorphBlendMesh`, and synthetic post-load `MD2Character`/`MD2CharacterComplex` state update morph target influences, skins, weapons, and movement through their helper APIs, and the resulting meshes render through supported CPU morph-target, built-in material, and transform paths
+- Three.js examples `GeometryUtils.hilbert2D()` produces line point paths and `TubePainter` writes dynamic tube mesh attributes/draw ranges that render through supported line and mesh material paths
+- Three.js examples `XYZLoader`, `GCodeLoader`, `PDBLoader`, `PCDLoader`, `OBJLoader`, `STLLoader`, `PLYLoader`, `VTKLoader`, and `VRMLLoader` synchronous `parse()` paths produce renderable point-cloud, toolpath line, atom point, bond line, mesh `BufferGeometry`/`Group`, and VRML `Scene` outputs, while `MTLLoader` material-library parses create supported `MeshPhongMaterial` instances for OBJ-style mesh paths
+- Three.js examples `SkeletonUtils.clone()` remaps cloned skinned meshes to cloned bones, and the resulting `SkinnedMesh` renders through the supported CPU skinning path
+- Three.js examples `BVHLoader` parses skeleton animation clips into renderable helper state, `MDDLoader` parses morph-target animation clips into renderable still-frame mesh state, `AnimationClipCreator` material color and visibility clips apply through `AnimationMixer` before rendering, and `CCDIKSolver` updates bone chains with `CCDIKHelper` target/effector/link visualization rendering through supported built-in mesh and line material paths
+- Three.js examples `CameraUtils.frameCorners()` writes an off-axis `PerspectiveCamera` projection/quaternion that renders framed scene content through the normal camera path
+- Three.js examples `ArcballControls`, `OrbitControls`, `MapControls`, `TrackballControls`, `FirstPersonControls`, `FlyControls`, and `PointerLockControls` can drive deterministic still-frame camera state before rendering, `DragControls` can move selected objects through pointer listeners before rendering, and `TransformControls` attaches to scene objects and renders its built-in transform gizmo helper through supported mesh and line paths
+- Three.js examples `SelectionBox` can select meshes and `InstancedMesh` instance IDs before rendering, `InteractiveGroup` can dispatch raycast-derived pointer UV events while its child meshes render through normal group traversal, and `SelectionHelper` can maintain DOM-like drag rectangle state against a renderer `domElement` parent when a browser-style `document.createElement("div")` implementation is provided; no-browser-document SelectionHelper and `HTMLMesh` paths are covered as clear DOM dependency failures
+- Three.js examples `OBJExporter`, `STLExporter`, `PLYExporter`, no-texture `GLTFExporter` with a `FileReader`-compatible environment, and no-texture `USDZExporter` `MeshStandardMaterial` paths serialize renderer-visible scene-graph geometry through their CPU exporter paths; `DRACOExporter` fails clearly without the external Draco encoder module
+- Three.js examples `DebugEnvironment` and `RoomEnvironment` generate regular scene graphs with built-in geometry, mesh materials, and lights that render through the normal scene path; CurveExtras, NURBS helpers, and low-level `NURBSUtils` samplers generate curve, surface, and volume-derived geometry that renders through supported mesh, line, and point paths
+- Three.js examples `GroundedSkybox`, `ShadowMesh`, `MarchingCubes`, `RollerCoasterGeometry`, `RollerCoasterLiftersGeometry`, `RollerCoasterShadowGeometry`, `SkyGeometry`, and `TreesGeometry` render generated helper geometry through supported built-in material paths after their normal example-object update steps
+- Three.js examples `NRRDLoader` parses volume data into `Volume` outputs, and `Volume`/`VolumeSlice` can render extracted canvas-backed grayscale slice meshes through supported `MeshBasicMaterial.map` paths when a canvas-like `document.createElement("canvas")` implementation provides readable 2D image data; no-browser-document extraction is covered as a clear DOM dependency failure
+- Three.js examples `UVsDebug` can produce canvas-backed UV debug output that renders through supported `CanvasTexture`/`MeshBasicMaterial.map` paths when a canvas-like `document.createElement("canvas")` implementation provides readable 2D image data; no-browser-document output is covered as a clear DOM dependency failure
+- Three.js examples `FlakesTexture` can generate canvas-backed procedural normal texture data that renders through supported `CanvasTexture` plus `MeshBasicMaterial.map` paths when a canvas-like `document.createElement("canvas")` implementation provides readable 2D image data; no-browser-document output is covered as a clear DOM dependency failure
+- Three.js examples WebXR `Text2D.createText()` can generate canvas-backed text meshes that render through supported `Texture` plus `MeshBasicMaterial.map` paths when a canvas-like `document.createElement("canvas")` implementation provides readable 2D image data; no-browser-document output is covered as a clear DOM dependency failure
+- Three.js WebGPU/TSL examples `SkyMesh`, `WaterMesh`, `Water2Mesh`, `InstancedPoints`, `LensflareMesh`, `ProgressiveLightMapGPU`, and WebGPU `Line2`/`LineSegments2`/`Wireframe` helpers fail clearly on their `NodeMaterial` paths with custom-WGSL guidance; GPU helper modules `ShadowMapViewerGPU`, `WebGPUTextureUtils`, `LightProbeHelperGPU`, and `TextureHelperGPU` are import-time unsupported under the installed Three.js core entrypoint because `NodeMaterial` is not exported there
+- Three.js `RectAreaLightHelper` renders its light outline and fill visualization through supported `LineBasicMaterial` and `MeshBasicMaterial` geometry
+- Three.js examples `RectAreaLightUniformsLib` and `RectAreaLightTexturesLib` initialize LTC float/half `DataTexture` uniforms that remain renderable through normal texture-map reads; native `RectAreaLight` shading still uses this renderer's finite-area approximation rather than exact Three.js LTC lookup parity
+- Three.js `PositionalAudioHelper` renders grouped cone line geometry through supported `Line` material-array groups with `LineBasicMaterial`
+- Three.js `OctreeHelper` renders generated box edges through supported `LineSegments` plus `LineBasicMaterial` paths
+- Three.js `LightProbeHelper` fails clearly on its internal `LightProbeHelperMaterial` shader path with guidance to use native `THREE.LightProbe` lighting, `LightProbeGenerator` readback, or a custom WGSL visualizer
+- Three.js `TextureHelper` fails clearly on its internal `TextureHelperMaterial` shader path with guidance to render supported texture inputs directly or provide a custom WGSL visualizer
+- Three.js examples `WebGLTextureUtils.decompress()` fails clearly on its browser WebGL `ShaderMaterial` blit path when used with this renderer; pass readable texture inputs directly instead of relying on WebGL decompression
+- Three.js examples `Line2`, `LineSegments2`, and `Wireframe` fail clearly on their `LineMaterial` shader path with guidance to use the renderer's supported built-in `Line`/`LineSegments`/`LineLoop` plus `LineBasicMaterial`/`LineDashedMaterial` paths
+- Three.js WebGPU examples `lines/webgpu/Line2`, `LineSegments2`, and `Wireframe` expose their CPU distance-attribute helpers, then fail clearly on their `Line2NodeMaterial`/NodeMaterial render paths with documented custom-WGSL guidance
+- Three.js examples `MeshGouraudMaterial` and `LDrawConditionalLineMaterial` fail clearly on their `ShaderMaterial` paths, `MeshPostProcessingMaterial` fails clearly on its `onBeforeCompile` shader-rewrite path, and `LDrawConditionalLineNodeMaterial` is import-time unsupported under the installed Three.js TSL entrypoint because `NodeMaterial` is not exported there; use supported built-in materials or the documented custom WGSL fragment path instead
+- `ProgressiveLightMap` reaches its renderer target-state setup path and then fails clearly on its internal `onBeforeCompile` shader rewrite with the documented custom-WGSL guidance
+- `Renderer.state` exposes inert `buffers.color`/`color`, `buffers.depth`/`depth`, and `buffers.stencil`/`stencil` no-op setter/lock probes, state-level blending/material/flip-sided/cull-face/line-width/polygon-offset/scissor-test/scissor/viewport probes, `buffers.depth.getReversed()`, no-op `reset()`/`unbindTexture()` hooks, and clear failures for raw WebGL binding/upload state methods, with the installed Three.js `WebGLState` and buffer method surfaces regression-audited for coverage drift
+- `Renderer.renderBufferDirect()`, `Renderer.renderBufferImmediate()`, `Renderer.renderObject()`, non-null `Renderer.setRenderObjectFunction()`, non-null `Renderer.setOutputRenderTarget()`/`setCanvasTarget()`, direct `Renderer.setTexture2D()`/`setTextureCube()`/`setTextureCubeDynamic()`/`setTexture3D()`/`setTexture2DArray()`, current and legacy source-box-first `Renderer.copyTextureToTexture3D()` calls, `Renderer.compute()`/`computeAsync()`, `Renderer.getArrayBufferAsync()`, `Renderer.resolveTimestampsAsync()`, and `Renderer.waitForGPU()` calls fail clearly because direct or legacy-immediate WebGL buffer binding, renderer-internal render-object dispatch, material program dispatch, backend-owned common-renderer output/canvas targets, browser WebGL texture units, direct texture binding, backend texture-layer copies, WebGPU compute pipelines, storage-buffer readback, timestamp query pools, and direct GPU synchronization are outside the scene-oriented API; `Renderer.getRenderObjectFunction()` returns `null`, `Renderer.setRenderObjectFunction(null)` is accepted as a clear operation, `Renderer.getOutputRenderTarget()`/`getCanvasTarget()` return `null`, and `Renderer.setOutputRenderTarget(null)`/`setCanvasTarget(null)` are accepted as clear operations
 - perspective, orthographic, and custom projection matrices
 
 ### Materials & Textures
 
-- material base color and opacity
-- `material.map` (base color texture) — PNG, JPEG, WebP, and raw RGBA8 DataTexture
+- material base color, opacity, and visibility, including CSS string material color inputs, with malformed color containers and invalid color/opacity/visible values failing clearly
+- `material.map` (base color texture) — PNG, JPEG, WebP, and raw one-channel, two-channel, RGB, or RGBA numeric DataTexture inputs, including legacy `LuminanceFormat` grayscale expansion, `AlphaFormat` single-channel alpha swizzle, and `LuminanceAlphaFormat` luminance+alpha expansion, byte, signed/unsigned normalized integer, packed 16-bit color, float, and half-float typed data, with `texture.channel` UV selection plus raw `texture.premultiplyAlpha` and sRGB color-space decode
+- base, sprite/point color and alpha, line/dashed-line, matcap, metallic/roughness, emissive, AO, light, Phong specular, alpha, sheen color, physical scalar RGB maps including anisotropy, iridescence factor/thickness, and thickness, and physical specular color maps honor `THREE.SRGBColorSpace`/`THREE.LinearSRGBColorSpace`, including the documented linear string aliases; unsupported texture color-space/encoding values fail clearly
+- base, 2D background, sprite/point color and alpha, line/dashed-line, matcap, normal/bump, displacement, emissive, metallic/roughness, AO/light, Phong specular, alpha, and current physical-extension maps honor texture UV transforms, including explicit texture matrices for those covered slots and color-space decode after explicit matrices for current color-producing transform slots; malformed transform vector containers and invalid transform or transform-boolean values fail clearly
+- `texture.channel` supports channels 0-3 on supported map slots, with malformed channel values failing clearly; channels 1-3 route selected non-primary UV attributes through the available native UV streams, mesh material draws can share up to two distinct selected texture channels across current supported slots, and draws requiring three or more distinct texture channels fail clearly
+- material and texture background output conversion supports `THREE.SRGBColorSpace` and `THREE.LinearSRGBColorSpace`; texture backgrounds honor `THREE.SRGBColorSpace`/`THREE.LinearSRGBColorSpace`, including the documented linear string aliases, and raw 2D texture backgrounds plus current raw IBL inputs honor `texture.premultiplyAlpha`
+- base/background, sprite/point color and alpha, line/dashed-line color and alpha, normal/bump, displacement, metallic/roughness, emissive, AO/light, alpha, Phong specular, toon gradient, matcap color-map, and packed physical-extension texture-group wrap modes plus `NearestFilter`/`LinearFilter`-family `magFilter` and `minFilter`, including direct coverage for background texture repeat/mirrored wrapping, base color-map repeat/mirrored wrapping plus nearest/linear filtering, normal-map repeat/mirrored wrapping plus nearest/linear filtering, bump-map repeat/mirrored wrapping plus nearest/linear filtering, displacement-map repeat/mirrored wrapping plus nearest/linear filtering, metalness-map repeat/mirrored wrapping plus nearest/linear filtering, roughness-map repeat/mirrored wrapping plus nearest/linear filtering, matcap color-map repeat/mirrored wrapping plus nearest/linear filtering, Phong specular-map repeat/mirrored wrapping plus nearest/linear filtering, AO-map repeat/mirrored wrapping plus nearest/linear filtering, emissive-map repeat/mirrored wrapping plus nearest/linear filtering, light-map repeat/mirrored wrapping plus nearest/linear filtering, alpha-map repeat/mirrored wrapping plus nearest/linear filtering, sprite color-map repeat/mirrored wrapping plus nearest/linear filtering, sprite alpha-map repeat/mirrored wrapping plus nearest/linear filtering, point color-map repeat/mirrored wrapping plus nearest/linear filtering, point alpha-map repeat/mirrored wrapping plus nearest/linear filtering, line color-map repeat/mirrored wrapping plus nearest/linear filtering, line alpha-map repeat/mirrored wrapping plus nearest/linear filtering, dashed-line color-map repeat/mirrored wrapping plus nearest/linear filtering, dashed-line alpha-map repeat/mirrored wrapping plus nearest/linear filtering, toon gradient-map horizontal repeat/mirrored wrapping, current physical-extension map repeat/mirrored wrapping and nearest/linear filtering, generated mip chains for mipmap min filters, raw explicit mip chains for unpacked 2D material/background texture uploads, half-float raw mip level decoding, WebGL-compatible `unpackAlignment` values for tightly packed readable uploads, and clear failures for unsupported sampler constants, invalid mipmap controls, invalid `unpackAlignment`, or invalid anisotropy values
 - PBR metallic/roughness via `MeshStandardMaterial` and `MeshPhysicalMaterial`
-- metallic/roughness map (`material.metalnessMap` / `material.roughnessMap`)
-- normal map with configurable `normalScale`
-- emissive color, intensity, and emissive map
-- occlusion map (`material.aoMap`) applied to indirect lighting
+- `MeshPhysicalMaterial` clearcoat, sheen, anisotropy, scalar iridescence, specular intensity/color, IOR, attenuation, approximate dispersion, and roughness-aware environment-backed or scene-color transmission / refraction; malformed physical specular/sheen/attenuation color containers and invalid physical color/scalar values fail clearly
+- physical material extension maps for clearcoat, clearcoat roughness, clearcoat normals, sheen color/roughness, anisotropy, iridescence factor/thickness, specular color/intensity, transmission, and thickness; all current physical-extension maps include primary/secondary `texture.channel` UV selection, texture transforms including explicit matrices, packed texture-group sampler settings with direct repeat/mirrored wrap and nearest/linear filter coverage across current maps, clear failures for incompatible packed samplers, and sRGB color-space decode for clearcoat, clearcoat roughness, anisotropy, iridescence factor/thickness, transmission, thickness, and sheen/specular color map RGB channels
+- custom WGSL fragment bodies via `material.userData.headlessThreeRenderer.fragmentWgsl`; `ShaderMaterial`, `RawShaderMaterial`, NodeMaterial, and `onBeforeCompile` customizations require this explicit override path except for the narrow built-in Three.js fullscreen CopyShader/OutputShader pass adapters used by covered EffectComposer helpers, named unsupported shader materials include their material name in diagnostics, Three.js `PMREMGenerator` internal shader passes fail clearly with native IBL guidance, `CSM` material shader injection fails clearly with helper guidance, `LineMaterial` plus `AnaglyphEffect`/`ParallaxBarrierEffect`/`AfterimagePass`/`BloomPass`/`FilmPass`/`DotScreenPass`/`GlitchPass`/`HalftonePass`/`LUTPass`/`BokehPass`/`RenderPixelatedPass`/`RenderTransitionPass`/`CubeTexturePass`/`SAOPass`/`SSAOPass`/`GTAOPass`/`UnrealBloomPass`/`SSRPass`/`SMAAPass`/`OutlinePass` internal shader passes plus `OutlineEffect`/`Sky`/`Water`/`Water2`/`Reflector`/`Refractor`/`ReflectorForSSRPass`/`ShadowMapViewer`/`LightProbeHelper`/`TextureHelper` helper-owned shader materials fail clearly with helper-specific guidance, and malformed material userData/renderer hint containers fail clearly
+- metallic/roughness map (`material.metalnessMap` / `material.roughnessMap`) with color-space decode, primary/secondary `texture.channel` UV selection, texture transforms, metalness-map and roughness-map horizontal/vertical repeat/mirrored wrapping, and nearest/linear filtering
+- normal map with configurable `normalScale`, primary/secondary `texture.channel` UV selection, color-space decode, horizontal/vertical repeat/mirrored wrapping, and nearest/linear filtering, plus bump map with `bumpScale`, color-space decode, horizontal/vertical repeat/mirrored wrapping, and nearest/linear filtering; invalid scalar values fail clearly
+- `MeshNormalMaterial` and `MeshMatcapMaterial` normal-map output
+- `material.flatShading` per-face normals for triangle meshes without normal maps
+- `MeshMatcapMaterial.map` color maps with primary/secondary `texture.channel` UV selection, transforms, horizontal/vertical repeat/mirrored wrapping, and nearest/linear filtering
+- displacement map CPU-baked into triangle vertices with `displacementScale`, `displacementBias`, primary/secondary `texture.channel` UV selection, texture color-space decode, texture transforms, horizontal/vertical repeat/mirrored wrapping, and nearest/linear sampler filtering; invalid scale/bias values fail clearly
+- `MeshToonMaterial.gradientMap` red-channel diffuse ramps with sRGB color-space decode, horizontal repeat/mirrored wrapping, and nearest/linear filtering; direct conformance also covers toon normal/bump-map lighting perturbation, base-map UV channels, emissive-map UV channels, light-map secondary UVs, and alpha-map cutouts
+- `MeshDepthMaterial.depthPacking`: basic, RGBA, RGB, and RG packing, with clear failures for unsupported depth-packing constants
+- `MeshDistanceMaterial` `referencePosition`, `nearDistance`, and `farDistance` overrides, with invalid range/reference values and malformed material userData/renderer hint containers failing clearly, plus alpha-map cutouts and CPU-baked displacement
+- main-pass `material.wireframe` output for supported mesh materials, including direct coverage for `MeshBasicMaterial`, `MeshDepthMaterial`, and `MeshDistanceMaterial`; legacy mesh wireframe line hints (`wireframeLinewidth`, `wireframeLinecap`, `wireframeLinejoin`) are validated and accepted as native no-ops
+- `Object3D.customDepthMaterial` and `customDistanceMaterial` for mesh shadow caster alpha-tested inputs, including selected base-map and alpha-map UV channels, base-map and alpha-map texture transforms, displacement maps with selected UV channels, visibility flags, and wireframe material inputs, plus source-material base/alpha maps with selected base-map and alpha-map UV channels, base-map and alpha-map texture transforms, opacity, clipping, displacement maps with selected UV channels, `shadowSide`, and wireframe state on custom shadow casters, alpha-tested sprite/point billboard shadow cutouts, sprite custom-depth/custom-distance source/custom base-map and alpha-map texture transforms, and point-billboard custom-distance base-map/alpha-map cutouts with selected geometry UV channels and texture transforms; malformed custom shadow material containers and visibility values fail clearly
+- emissive color, intensity, and emissive map, with primary/secondary `texture.channel` UV selection, texture transforms, sRGB color-space decode, horizontal/vertical repeat/mirrored wrapping, and nearest/linear filtering; malformed color containers and invalid color/intensity values fail clearly
+- light maps with `lightMapIntensity`, primary/secondary `texture.channel` UV selection, texture transforms, sRGB color-space decode, horizontal/vertical repeat/mirrored wrapping, and nearest/linear filtering; invalid intensity values fail clearly
+- occlusion map (`material.aoMap`) applied to indirect lighting, with color-space decode, primary/secondary `texture.channel` UV selection, texture transforms, horizontal/vertical repeat/mirrored wrapping, and nearest/linear filtering; invalid intensity values fail clearly
+- alpha map (`material.alphaMap`) using Three.js' green-channel opacity convention, with color-space decode, primary/secondary `texture.channel` UV selection, texture transforms, horizontal/vertical repeat/mirrored wrapping, and nearest/linear filtering
+- `MeshPhongMaterial.specularMap` red-channel specular strength, with finite `shininess`, color-space decode, primary/secondary `texture.channel` UV selection, texture transforms, horizontal/vertical repeat/mirrored wrapping, nearest/linear filtering, and masking for scene-level, reflection-probe, and supported material-level environment specular reflections
+- `MeshBasicMaterial`, `MeshLambertMaterial`, and `MeshPhongMaterial` material env maps for one shared material-level reflection or refraction map, including legacy multiply/mix/add combine modes, `reflectivity`, and `refractionRatio`; invalid env-map scalar values fail clearly
 - `MeshStandardMaterial`, `MeshPhysicalMaterial` (PBR), `MeshLambertMaterial` (diffuse-only), and `MeshBasicMaterial` (unlit)
-- `material.side`: `FrontSide`, `BackSide`, `DoubleSide`
-- alpha test (`material.alphaTest`) with fragment discard
-- transparency sorting (back-to-front) with separate no-depth-write pipeline
+- `ShadowMaterial` transparent receiver output with color, opacity, scene fog, Fog/FogExp2 fog opt-out, and output color-space conversion
+- `material.side`: `FrontSide`, `BackSide`, `DoubleSide`, with clear failures for unsupported side constants
+- `material.fog = false` opt-out for scene fog on mesh, shadow, sprite, point, and line material paths; CSS string fog colors are accepted, while malformed fog color containers and invalid fog color/parameter values fail clearly
+- alpha test (`material.alphaTest`) with fragment discard and alpha-to-coverage threshold smoothing on multisampled main-pass renders; invalid values fail clearly
+- native draw ordering honors group order, finite `renderOrder` values and Three.js' `+/-Infinity` render-order sentinel including `Lensflare`, material id, WebGL material variant, transmissive/transparent buckets, projected geometry bounding-sphere z, object/insertion ties, `sortObjects`, and custom opaque/transparent sort callbacks with object/material/geometry/group render-item metadata, including source-object metadata for BatchedMesh-expanded draws; transparency sorting is back-to-front with `material.depthWrite` overrides, including Three.js' default transparent depth writes; invalid `renderOrder` and sort-control values fail clearly
+- renderer-level `opaque` and `transparent` flags can skip opaque or transmissive/transparent render buckets, with invalid flag values failing clearly
+- material render state: `depthTest`, `depthFunc`, `depthWrite`, `colorWrite`, `polygonOffset`, `alphaHash`, `alphaToCoverage` on 4x MSAA renders including output-alpha and alpha-test threshold coverage, `premultipliedAlpha` including unlit sprite/point/line paths, `toneMapped=false` output opt-out including unlit sprite/point/line paths, boolean-validated `dithering`, supported `precision` strings, and mesh wireframe line hints as native no-ops, stencil state, built-in blending modes, `CustomBlending` equations/factors, and clear failures for unsupported render-state constants or invalid boolean/numeric values
+- render-option global clipping planes, reusable `Renderer.clippingPlanes` global fallback planes, and material-local clipping planes, with `options.localClippingEnabled: false` and reusable `Renderer.localClippingEnabled = false` available to ignore material-local planes, alpha-to-coverage smoothing for MSAA main-pass clipping edges, and `material.clipShadows`/group `clipShadows` clipping mesh and line shadow casters; malformed plane containers, invalid plane/control values, invalid clipping control booleans, and over-budget global/group/material combinations beyond eight active planes fail clearly
+- single shared material-level reflection/refraction `envMap` inputs are supported for `MeshBasicMaterial`, `MeshLambertMaterial`, and `MeshPhongMaterial`, and shared reflection `envMap` inputs are supported for `MeshStandardMaterial` and `MeshPhysicalMaterial` through the native IBL path, including CubeUV-mapped six-face cube and packed 2D PMREM/CubeUV sharp/base-atlas env maps; `envMap` properties on material classes that do not consume material environment maps are ignored, while unsupported material classes, unsupported material env-map options, PBR material refraction mappings, malformed packed 2D PMREM/CubeUV mappings, multiple distinct material env maps, and multiple distinct material env-map rotations fail clearly
 - texture wrap modes: repeat, mirror, clamp-to-edge
+- mipmap min filters generate native mip chains from supported material/background texture source levels; raw `DataTexture`-style explicit mipmap arrays upload for unpacked 2D material/background texture slots, while malformed texture source containers plus packed physical-extension maps and environment/reflection-probe/material-envMap explicit mip arrays fail clearly
+- texture anisotropy values greater than 1 use native anisotropic samplers for supported material/background texture slots when the effective sampler is linear-filtered; invalid anisotropy values fail clearly
+- line material arrays honor geometry groups; `LineBasicMaterial.linewidth` and `LineDashedMaterial.linewidth` values greater than 1 expand to camera-facing quads; `linecap`/`linejoin` and unlit `receiveShadow` are accepted as WebGL-compatible no-ops, with invalid cap/join values failing clearly; dashed line material segments honor dash/gap/scale settings, treat `scale=0` as solid like WebGL, and support custom `lineDistance` attributes including descending spans, keep missing `lineDistance` attributes solid like WebGL, and preserve map UV transforms including explicit matrices, selected `texture.channel` UVs, selected instanced map UV attributes, and interpolated vertex colors for common `LineDashedMaterial` cases, including instanced line geometry; invalid negative or non-finite line scalar values fail clearly
 
 Texture image data can be:
 
-- Raw RGBA8 pixels via `THREE.DataTexture` (or any image with `.data`, `.width`, `.height`)
+- Raw one-channel, two-channel, RGB, or RGBA numeric pixels via `THREE.DataTexture` (or any image with `.data`, `.width`, `.height`), including legacy `LuminanceFormat` grayscale expansion, `AlphaFormat` single-channel alpha swizzle, and `LuminanceAlphaFormat` luminance+alpha expansion, `UnsignedByteType`, normalized `ByteType`/`ShortType`/`UnsignedShortType`/`IntType`/`UnsignedIntType`, packed `UnsignedShort4444Type`/`UnsignedShort5551Type`, normalized float arrays, and `HalfFloatType` `Uint16Array` binary16 data
 - Encoded PNG, JPEG, or WebP image buffers (auto-decoded on the native side)
 
+Compressed KTX2/Basis/`THREE.CompressedTexture` inputs and compressed texture format constants are not decoded in-process; pre-decode them to RGB/RGBA data or an encoded PNG/JPEG/WebP image before rendering. `THREE.CanvasTexture` and other canvas-like texture images that expose `getContext("2d").getImageData()` are read directly in Node, and image-like objects can be read through an available `OffscreenCanvas`/2D canvas polyfill that supports `drawImage()` plus `getImageData()`; `THREE.VideoTexture` and `THREE.StorageTexture` inputs fail clearly because live video frames and WebGPU storage texture backing data are not directly readable in Node, and opaque browser `Image`/`ImageBitmap` objects still fail clearly when no readable or drawable pixel path is available. Mismatched-length raw texture payloads fail clearly.
+
 ### Lights
 
 - `THREE.AmbientLight` — uniform ambient illumination
@@ -109,22 +259,28 @@ Texture image data can be:
 - `THREE.PointLight` — omnidirectional light with distance/decay attenuation
 - `THREE.SpotLight` — cone light with angle, penumbra, distance, and decay
 - `THREE.HemisphereLight` — sky/ground gradient ambient light
+- `THREE.RectAreaLight` — one-sided finite-area direct-light approximation
+- `THREE.LightProbe` — summed visible spherical-harmonics indirect lighting plus `LightProbeGenerator.fromCubeRenderTarget()` cube-target readback interop, with invalid coefficient values failing clearly
 
-Lights are automatically extracted from the scene. The shader uses a Cook-Torrance PBR BRDF (GGX/Trowbridge-Reitz distribution, Schlick-GGX geometry, Schlick Fresnel) with Three.js-compatible physically-based attenuation. Up to 16 lights per scene. When no lights are present, meshes render with a hemispherical ambient fallback.
+Lights are automatically extracted from the scene, with CSS string light colors accepted and malformed light color/target containers, invalid light color, numeric controls, transform matrix values, shadow flags, and shadow option containers failing clearly. The shader uses a Cook-Torrance PBR BRDF (GGX/Trowbridge-Reitz distribution, Schlick-GGX geometry, Schlick Fresnel) with Three.js-compatible physically-based attenuation for punctual lights. Up to 64 direct lights per scene are supported. Visible directional, spot, and point lights may cast shadows while their packed native shadow-map usage stays within twelve array layers. When no lights are present, meshes render with a hemispherical ambient fallback.
 
 ### Image-Based Lighting (IBL)
 
-Environment maps set on `scene.environment` are supported for image-based lighting. The renderer CPU-precomputes:
+Environment maps set on `scene.environment` are supported for image-based lighting. A single shared material-level reflection `envMap` can also feed the same native IBL path for `MeshBasicMaterial`, `MeshStandardMaterial`, `MeshPhysicalMaterial`, `MeshPhongMaterial`, and `MeshLambertMaterial`, with per-material intensity and one shared material env-map rotation. Material `envMap` properties on classes that Three.js does not shade with material environment maps are accepted as no-ops. The renderer CPU-precomputes:
 
 - **Diffuse irradiance cubemap** — cosine-weighted hemisphere convolution
 - **Prefiltered specular cubemap** — GGX importance-sampled at multiple roughness mip levels
 - **BRDF integration LUT** — split-sum approximation lookup table
 
-Supported input formats: equirectangular images in RGBA8, Float16 (`HalfFloatType`), or Float32 (`FloatType`). `scene.environmentIntensity` is respected.
+Supported input formats: equirectangular images in RGB/RGBA byte data, Float16 (`HalfFloatType`), or Float32 (`FloatType`), plus raw or encoded six-face cube reflection textures, CubeUV-mapped six-face cube inputs, and packed 2D PMREM/CubeUV sharp/base-atlas inputs routed through the same CPU IBL precompute. Raw scene-environment, reflection-probe, and supported material-level IBL inputs honor `texture.premultiplyAlpha`. Scene-environment, reflection-probe, and supported material-level LDR inputs honor explicit `THREE.SRGBColorSpace` and `THREE.LinearSRGBColorSpace`, including the documented linear string aliases; omitted color space defaults to sRGB for compatibility. `MeshBasicMaterial`, `MeshLambertMaterial`, and `MeshPhongMaterial` env maps support legacy multiply/mix/add combine modes with `reflectivity` plus refraction mappings with `refractionRatio`; malformed scene-environment/reflection-probe values, malformed reflection-probe hint containers, unsupported IBL texture input classes, raw data layouts/types, explicit mipmaps, color-space/legacy-encoding values, PBR material refraction mappings, malformed packed 2D PMREM/CubeUV environment inputs, Three.js `PMREMGenerator` runtime shader passes, multiple distinct material env maps, multiple distinct material env-map rotations, invalid environment intensity values, and invalid material env-map scalar values fail clearly. Exact PMREM prefiltered LOD semantics remain planned beyond decoded sharp/base atlas faces. `scene.environmentIntensity` is respected for scene environments, reflection-probe intensity applies only when `scene.environment` is absent, and `options.environmentIntensity` can override scene or reflection-probe intensity for one render.
+
+Scene-level reflection probes are supported through `scene.userData.headlessThreeRenderer.reflectionProbe` or the first entry in `reflectionProbes`. Probe textures use the same equirectangular and cube texture formats as `scene.environment` and feed the same diffuse/specular IBL path.
+
+`scene.userData` must be an object when present; `scene.userData.headlessThreeRenderer` and the legacy `scene.userData.headlessRenderer` key must also be objects when present.
 
 ### Skinning / Skeletal Animation
 
-`THREE.SkinnedMesh` objects are automatically detected and skinned on the CPU. The renderer reads `skinIndex` and `skinWeight` attributes, computes bone matrices from `skeleton.bones` and `skeleton.boneInverses`, and transforms vertex positions and normals before sending them to the GPU.
+`THREE.SkinnedMesh` objects are automatically detected and skinned on the CPU. The renderer reads `skinIndex` and `skinWeight` attributes, computes bone matrices from `skeleton.bones` and `skeleton.boneInverses`, and transforms vertex positions and normals before sending them to the GPU. Malformed mesh/skeleton containers and invalid bone, inverse bind, and mesh bind matrix values fail clearly.
 
 Compatible with:
 
@@ -132,38 +288,37 @@ Compatible with:
 - **@pixiv/three-vrm** — VRM humanoid avatars
 - **VRMA** — VRM Animation files via `VRMAnimationLoaderPlugin` + `createVRMAnimationClip`
 
-Call `mixer.update(dt)` and `scene.updateMatrixWorld(true)` before `render()` to bake the current pose:
+The repository includes runnable local examples for [glTF/GLB](https://github.com/portwatcher/headless-three-renderer/blob/main/examples/render-gltf.mjs) and [VRM/VRMA](https://github.com/portwatcher/headless-three-renderer/blob/main/examples/render-vrm.mjs) assets. The VRM example resolves optional Pixiv packages from the current working project when they are not installed next to the example script, and accepts `TIME` plus `ANIMATION_INDEX` environment variables for VRMA still-frame selection.
+
+Use `applyVrmAnimation()` or your own `AnimationMixer`, then call `scene.updateMatrixWorld(true)` before `render()` to bake the current pose. `applyVrmAnimation()` accepts the glTF objects returned by the local VRM/VRMA helpers or direct `vrm`/`vrmAnimation` objects; it selects `userData.vrmAnimations[0]` by default for wrappers, accepts `animationIndex` for multi-animation VRMA wrappers, updates the avatar by default, and accepts `updateVrm: false` if your render pipeline performs that update separately.
 
 ```js
 import * as THREE from 'three'
-import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
 import { VRMLoaderPlugin, VRMUtils } from '@pixiv/three-vrm'
 import { VRMAnimationLoaderPlugin, createVRMAnimationClip } from '@pixiv/three-vrm-animation'
-import { render } from '@headless-three/renderer'
-
-const gltfLoader = new GLTFLoader()
-gltfLoader.register((parser) => new VRMLoaderPlugin(parser))
-gltfLoader.register((parser) => new VRMAnimationLoaderPlugin(parser))
+import { applyVrmAnimation, loadVrmAnimationFromFile, loadVrmFromFile, render } from '@headless-three/renderer'
 
 // Load VRM model
-const modelGltf = await gltfLoader.loadAsync('./avatar.vrm')
+const modelGltf = await loadVrmFromFile('./avatar.vrm', { VRMLoaderPlugin })
 const vrm = modelGltf.userData.vrm
 VRMUtils.removeUnnecessaryVertices(vrm.scene)
 VRMUtils.removeUnnecessaryJoints(vrm.scene)
 vrm.scene.rotation.y = Math.PI
 
 // Load VRMA animation
-const animGltf = await gltfLoader.loadAsync('./dance.vrma')
-const vrmAnimation = animGltf.userData.vrmAnimations[0]
-const clip = createVRMAnimationClip(vrmAnimation, vrm)
+const animGltf = await loadVrmAnimationFromFile('./dance.vrma', {
+  VRMLoaderPlugin,
+  VRMAnimationLoaderPlugin,
+})
 
 // Animate to a specific time
-const mixer = new THREE.AnimationMixer(vrm.scene)
-mixer.clipAction(clip).play()
-mixer.update(1.5) // seek to 1.5 seconds
+await applyVrmAnimation(modelGltf, animGltf, {
+  animationIndex: 0,
+  createVRMAnimationClip,
+  time: 1.5,
+})
 
 // Update world matrices then render
-vrm.update(0)
 vrm.scene.updateMatrixWorld(true)
 
 const camera = new THREE.PerspectiveCamera(30, 1, 0.1, 20)
@@ -178,7 +333,7 @@ const imageBuffer = render(vrm.scene, camera, {
 
 ### Morph Targets / Blend Shapes
 
-Morph targets are applied on the CPU before rendering. Both **relative** (glTF default) and **absolute** (legacy Three.js) modes are supported. Position and normal morphs are applied based on `mesh.morphTargetInfluences`. This is compatible with:
+Morph targets are applied on the CPU before rendering. Both **relative** (glTF default) and **absolute** (legacy Three.js) modes are supported. Position and normal morphs are applied based on `mesh.morphTargetInfluences`, with malformed morph attribute containers, invalid influence values, and malformed `geometry.morphTargetsRelative` values failing clearly. This is compatible with:
 
 - glTF morph targets via `GLTFLoader`
 - VRM blend shapes / expressions from `@pixiv/three-vrm`
@@ -186,16 +341,36 @@ Morph targets are applied on the CPU before rendering. Both **relative** (glTF d
 
 ### Shadows
 
-Directional shadow maps are supported. Set `light.castShadow = true` on a `THREE.DirectionalLight`, configure `light.shadow.camera` (orthographic bounds), and mark meshes with `mesh.castShadow = true` / `mesh.receiveShadow = true`. The renderer picks the first shadow-casting directional light, renders a depth-only pass, and samples it with 3×3 PCF and a normal-offset bias.
+Directional, spot, point, and up to four directional cascaded shadow maps are supported across a packed twelve-layer native depth texture array. Directional and spot shadows use one layer, point shadows use six cube-face layers, and directional cascades use one layer per cascade; shadow-light sets that exceed that budget fail clearly. Reusable `Renderer.shadowMap.enabled` defaults to true for the current scene-oriented behavior; set it to false to suppress renderer-owned shadow maps. `shadowMap.autoUpdate` and `shadowMap.needsUpdate` are accepted as compatibility state, `shadowMap.render()` is an input-validated no-op compatibility probe, and `shadowMap.type` selects a single-compare `THREE.BasicShadowMap` path or the current 3×3 PCF path for `THREE.PCFShadowMap`, `THREE.PCFSoftShadowMap`, and `THREE.VSMShadowMap`. Set `light.castShadow = true`, configure `light.shadow.camera`, and mark meshes with `mesh.castShadow = true` / `mesh.receiveShadow = true`. Common shadow options including `light.shadow.bias`, `light.shadow.normalBias`, `light.shadow.radius`, and `light.shadow.intensity` are honored, `light.shadow.blurSamples` adjusts the approximate VSM filtered path and is accepted as compatibility state for PCF-family shadows; `light.shadow.map`, `light.shadow.mapPass`, `light.shadow.matrix`, `light.shadow.autoUpdate`, and `light.shadow.needsUpdate` are validated as per-light compatibility state without persistent cached-shadow-map semantics, explicit mesh `material.shadowSide` values filter shadow-caster faces, and `material.alphaToCoverage` approximates shadow-caster alpha cutouts with a 0.5 cutoff. `Object3D.customDepthMaterial` is honored for directional/spot mesh shadow caster alpha-tested inputs, including selected base-map, alpha-map, and displacement-map UV channels, base-map and alpha-map texture transforms, displacement inputs, and visibility flags, and for sprite/point billboard shadow caster alpha-tested inputs; `customDistanceMaterial` is honored for point-light mesh shadow caster alpha-tested inputs, including selected base-map, alpha-map, and displacement-map UV channels, base-map and alpha-map texture transforms, displacement inputs, and visibility flags, and for sprite/point billboard shadow caster alpha-tested inputs, with sprite custom-depth/custom-distance base/alpha maps honoring texture transforms and point-billboard custom-distance base/alpha maps honoring selected geometry UV channels plus texture transforms. Source-material base/alpha/displacement maps including selected texture UV channels, base-map and alpha-map texture transforms, `alphaHash` and `alphaToCoverage` opacity cutouts, and `shadowSide` are carried onto custom mesh shadow casters, and source-material base/alpha texture transforms are also carried onto the covered sprite custom-depth/custom-distance and point-light point-billboard custom-distance paths. `THREE.Sprite` and `THREE.Points` can cast directional/spot/point shadows from expanded billboard quads, and `receiveShadow` is accepted as a WebGL-compatible no-op on their unlit material paths. Malformed shadow flags/containers, invalid shadow cache/matrix/update-state values, invalid shadow numeric values, invalid renderer shadow-map booleans/type constants, invalid shadow-map render inputs, invalid custom shadow material visibility values, malformed light userData/cascade hint containers/values, over-budget cascade/layer sets, and non-square point-light `light.shadow.mapSize` values fail clearly until true shadow atlas allocation, deeper cascade support, and rectangular cube-face support land. The renderer renders depth-only passes and samples them with a normal-offset bias.
+
+`light.shadow.intensity` scales received shadow darkening from fully suppressed at `0` through the default full-intensity path at `1`.
+
+`shadowMap.transmitted` is stored as compatibility state; it currently does not change scene output because transmitted shadow-map passes are not modeled separately.
+
+Directional cascades can be provided with `light.userData.headlessThreeRenderer.shadowCascades`, where each cascade has finite `{ left, right, top, bottom, near, far, split }` bounds.
+
+`light.userData` must be an object when present before cascade hints are read.
 
 ### Tone Mapping
 
-Output uses the Narkowicz ACES Filmic tone mapping fit with a three.js-compatible `1/0.6` exposure pre-scale, matching `THREE.ACESFilmicToneMapping`.
+Output uses the Narkowicz ACES Filmic tone mapping fit by default with a three.js-compatible `toneMappingExposure / 0.6` exposure pre-scale, matching `THREE.ACESFilmicToneMapping`. Reusable `Renderer.toneMapping` and `currentToneMapping` support `THREE.NoToneMapping`, `THREE.LinearToneMapping`, `THREE.ReinhardToneMapping`, `THREE.CineonToneMapping`, `THREE.ACESFilmicToneMapping`, `THREE.CustomToneMapping`, `THREE.AgXToneMapping`, and `THREE.NeutralToneMapping`; `THREE.CustomToneMapping` uses Three.js' default identity custom function because GLSL shader-chunk customizations are not translated; `Renderer.toneMappingExposure` defaults to `1`; `options.toneMapping` and `options.toneMappingExposure` override reusable state for one render; per-material `toneMapped=false` is honored on mesh, sprite, point, line, and dashed-line material paths; `Renderer.needsFrameBufferTarget` reports `false` because output conversion is inline in the native render pass; unsupported tone-mapping constants and invalid exposure values fail clearly.
 
-### Lines and Points
+### Render Targets & Post-Processing
+
+`renderToTarget(scene, camera, target, options)`, `options.target`, and `Renderer.setRenderTarget(target); renderer.render(scene, camera, options)` populate a target-like object, including actual `THREE.RenderTarget`/`THREE.WebGLRenderTarget` instances, with `{ width, height, data }` plus `target.texture.image.data` when a texture object is present. `Renderer.readRenderTargetPixels()` and `readRenderTargetPixelsAsync()` copy stored CPU color data for regular targets, explicit cube target faces, and selected color attachment indices into caller-provided buffers; async readback can allocate a matching output buffer and accepts the common-renderer `(target, x, y, width, height, textureIndex, faceIndex)` argument shape. Top-level target rendering defaults to raw RGBA8 and `target.data` remains RGBA8 for compatibility; color textures receive Alpha/Luminance/LuminanceAlpha/Red/RG/RGB/RGBA and RedIntegerFormat/RGIntegerFormat/RGBIntegerFormat/RGBAIntegerFormat channel data by requested format, normalized `Float32Array` data for `THREE.FloatType`, signed or unsigned normalized integer arrays for `ByteType`/`ShortType`/`IntType` and `UnsignedShortType`/`UnsignedIntType`, packed `Uint16Array` data for `UnsignedShort4444Type`/`UnsignedShort5551Type`, packed `Uint32Array` RGB9_E5 data for `UnsignedInt5999Type`, packed `Uint32Array` R11F_G11F_B10F data for `UnsignedInt101111Type`, or `Uint16Array` half-float data for `HalfFloatType`, including through target texture arrays, `target.textures`, MRT-shaped targets, and `options.target`. Regular-camera, ArrayCamera, and CubeCamera MRT-shaped targets can populate secondary color textures with explicit multi-pass auxiliary outputs when each secondary texture declares `texture.userData.headlessThreeRenderer.renderMode` as `'color'`, `'mask'`, `'object-id'`, `'normal'`, or `'depth'`; `Renderer.getMRT()` returns `null`, `Renderer.setMRT(null)` is accepted as a clear operation, and arbitrary native MRT shader outputs including non-null `Renderer.setMRT()` remain unsupported. A target `depthTexture` object receives normalized depth readback for the same viewport/scissor and visible depth-tested geometry, including base-texture and alpha-map alpha-tested cutouts, `alphaHash` cutouts, and transparent material default/explicit `depthWrite` behavior; `THREE.FloatType` depth textures receive scalar `Float32Array` data, `HalfFloatType` depth textures receive `Uint16Array` half-float data, `UnsignedByteType`/`UnsignedShortType`/`UnsignedIntType` depth textures receive scalar unsigned typed arrays, `UnsignedInt248Type` receives `Uint32Array` data with normalized depth24 in the high bits and zero stencil bytes, and plain depth target objects receive RGBA8 bytes. 4x MSAA sample counts resolve into target readback buffers; unhinted secondary color attachments, malformed targets, target image containers, nested target texture/mipmap/source containers, malformed target scissor flags, actual array/3D render target classes, array/3D target texture objects, regular-camera cube target texture objects, unsupported sample counts, unsupported color target texture formats/types, compressed target texture objects or compressed target format constants, explicit depth texture types, and depth texture format/type pairings fail clearly.
 
-`THREE.Line`, `THREE.LineSegments`, `THREE.LineLoop`, and `THREE.Points` are supported. Lines and points render as unlit (basic) primitives and ignore lighting / normals.
+Built-in post-processing can be enabled with `options.postProcessing`. Supported effects are exposure, contrast, saturation, vignette, grayscale, and invert; malformed containers and invalid effect values fail clearly.
 
-### Not Yet Implemented
+`options.renderMode` can request flat auxiliary passes. `'mask'` clears to black and writes white for visible geometry. `'object-id'` clears to RGB zero and encodes each object's adapter sort ID plus one into RGB bytes, making `format: 'rgba'` the preferred inspection path. `'normal'` clears to black and writes view-space normal colors matching `MeshNormalMaterial` for visible geometry. `'depth'` clears to black and writes normalized grayscale depth for visible geometry. Target-based object-id renders populate `target.objectIdEntries` and `target.objectIdMap` for reverse lookup from encoded RGB IDs. These modes bypass scene backgrounds, lighting, environment, fog, and post-processing while preserving depth testing, culling, clipping planes, base texture alpha, `material.alphaMap`, `alphaTest`, and `alphaHash`; invalid render modes fail clearly.
+
+### Custom WGSL Fragment Materials
+
+Materials can provide a WGSL fragment body with `material.userData.headlessThreeRenderer.fragmentWgsl`. The body runs inside the renderer's standard vertex, uniform, color, UV, and base-texture setup and returns a `vec4<f32>`.
+
+Three.js `ShaderMaterial`, `RawShaderMaterial`, and NodeMaterial are not translated directly; provide the headless WGSL fragment override above or use a built-in material. The adapter includes narrow recognizers for Three.js' fullscreen CopyShader and OutputShader helper passes used by covered EffectComposer flows.
+
+`material.userData` must be an object when present; `material.userData.headlessThreeRenderer` and the legacy `material.userData.headlessRenderer` key must also be objects when present.
+
+### Lines and Points
 
-Custom shaders, render targets, point/spot-light shadows, cascaded shadow maps, reflection probes, transmission / refraction, clearcoat / sheen, anisotropy, and post-processing effects.
+`THREE.Line`, `LineSegments`, `LineLoop`, and `THREE.Points` are supported. Lines and points render as unlit (basic) primitives, ignore lighting / normals, and honor bounding-sphere frustum culling with `frustumCulled=false` opt-out; point culling also accounts for rendered billboard size. Opacity, line material arrays with geometry groups, scene fog, `material.fog = false`, `alphaHash` opacity cutouts, and 4x-MSAA `alphaToCoverage` opacity cutouts are honored. `LineBasicMaterial.map` samples line UVs, including texture UV transforms, horizontal/vertical repeat/mirrored wrapping, nearest/linear filtering, channel 0-3 `texture.channel` UV selection through one non-primary UV stream, texture RGB with sRGB color-space decode, and alpha-tested texture alpha; line alpha maps honor selected `texture.channel` UVs, horizontal/vertical repeat/mirrored wrapping, nearest/linear filtering, and sRGB color-space decode. Line objects cast directional/spot/point shadows with base-map, alpha-map, `alphaHash`, and `alphaToCoverage` cutouts. `LineBasicMaterial.linewidth` and `LineDashedMaterial.linewidth` values greater than 1 expand to camera-facing quads, while `linecap`, `linejoin`, and unlit `receiveShadow` are accepted as WebGL-compatible no-ops. Dashed lines honor custom `lineDistance` attributes including descending spans, keep `scale=0` or missing `lineDistance` attributes solid like WebGL, and dashed line maps/alpha maps preserve texture UV transforms, horizontal/vertical repeat/mirrored wrapping, nearest/linear filtering, selected `texture.channel` UVs, selected instanced map UV attributes, and sRGB color-space decode while reconstructing dash segments. `PointsMaterial` maps and alpha maps use per-point geometry UVs when present and point-sprite UVs otherwise, keep untextured point-sprite corners square/visible, honor texture UV transforms, horizontal/vertical repeat/mirrored wrapping, and nearest/linear filtering, decode sRGB color and alpha maps, apply `alphaHash` and 4x-MSAA `alphaToCoverage` opacity cutouts, shrink with perspective distance by default, keep orthographic point size independent of camera depth, cast directional/spot/point shadows from the expanded billboard quads, accept `receiveShadow` as a WebGL-compatible no-op, and honor alpha-tested custom depth/distance material cutouts in shadow passes, including selected geometry UV channels for point-light custom-distance base/alpha maps. Invalid point size, point size attenuation, line width, line cap/join strings, and negative or non-finite dashed-line scalar values fail clearly.

package/dist/attributes.d.ts

@@ -1,8 +1,10 @@
 import type { ThreeBufferAttributeLike, ThreeBufferGeometryLike, Color4 } from './types';
 export declare function getAttribute(geometry: ThreeBufferGeometryLike, name: string): ThreeBufferAttributeLike | undefined;
-export declare function readVec3Attribute(attribute: ThreeBufferAttributeLike): number[];
-export declare function readVec2Attribute(attribute: ThreeBufferAttributeLike): number[];
-export declare function readColorAttribute(attribute: ThreeBufferAttributeLike, materialColor: Color4): number[];
-export declare function readIndexAttribute(attribute: ThreeBufferAttributeLike): number[];
-export declare function attributeComponent(attribute: ThreeBufferAttributeLike, index: number, component: number): number;
+export declare function geometryAttributes(geometry: ThreeBufferGeometryLike): Record<string, ThreeBufferAttributeLike | undefined>;
+export declare function readVec3Attribute(attribute: ThreeBufferAttributeLike, label?: string): number[];
+export declare function readVec2Attribute(attribute: ThreeBufferAttributeLike, label?: string): number[];
+export declare function readColorAttribute(attribute: ThreeBufferAttributeLike, _materialColor: Color4, label?: string): number[];
+export declare function readIndexAttribute(attribute: ThreeBufferAttributeLike, label?: string, vertexCount?: number): number[];
+export declare function attributeCount(attribute: ThreeBufferAttributeLike, label: string): number;
+export declare function attributeComponent(attribute: ThreeBufferAttributeLike, index: number, component: number, label?: string): number;
 //# sourceMappingURL=attributes.d.ts.map

package/dist/attributes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../api/attributes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAGxF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,uBAAuB,EAAE,IAAI,EAAE,MAAM,GAAG,wBAAwB,GAAG,SAAS,CAKlH;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,wBAAwB,GAAG,MAAM,EAAE,CAW/E;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,wBAAwB,GAAG,MAAM,EAAE,CAU/E;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,CAUvG;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,wBAAwB,GAAG,MAAM,EAAE,CAMhF;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,wBAAwB,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAoBhH"}
+{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../api/attributes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAKxF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,uBAAuB,EAAE,IAAI,EAAE,MAAM,GAAG,wBAAwB,GAAG,SAAS,CAMlH;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,GAAG,SAAS,CAAC,CAO1H;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,wBAAwB,EAAE,KAAK,SAA0B,GAAG,MAAM,EAAE,CAShH;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,wBAAwB,EAAE,KAAK,SAA0B,GAAG,MAAM,EAAE,CAQhH;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,wBAAwB,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,SAA0B,GAAG,MAAM,EAAE,CAWzI;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,wBAAwB,EACnC,KAAK,SAA0B,EAC/B,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,EAAE,CAcV;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,wBAAwB,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,wBAAwB,EACnC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,KAAK,SAA0B,GAC9B,MAAM,CA2BR"}