@absolutejs/rendering 0.2.0 → 0.4.0

package/README.md

@@ -54,3 +54,80 @@ neutral state, restores the caller immediately, and returns the exact supplied
 Float32Array on completion. It never restores stale renderer state after await.
 Allocate supported targets and correctly sized buffers before calling these
 helpers. The helpers do not choose formats, sample counts or capture resolution.
+
+## React Spring with demand-rendered Fiber scenes
+
+The optional `@absolutejs/rendering/spring` entry provides `animated.mesh`,
+`animated.group`, `useSpring`, `easings`, and `createFiberSpringHost` for other
+explicit Fiber primitives:
+
+```tsx
+import { animated, useSpring } from '@absolutejs/rendering/spring';
+
+function MovingGroup({ x }: { x: number }) {
+  const motion = useSpring({ x });
+  return <animated.group position-x={motion.x}>{/* scene content */}</animated.group>;
+}
+```
+
+It keeps React Spring's normal scheduler. Three prop updates invalidate the
+owning Fiber root through `applyProps`; DOM-only animation does not render a
+scene and can finish without a mounted Canvas. No `useFrame`, manual animation
+clock, global scheduler replacement, or unconditional render loop is installed.
+
+Do not also runtime-import `@react-spring/three`: that entry installs a global
+Fiber-driven scheduler even when its consuming component is never mounted. This
+adapter does not override or repair another module's global scheduler changes.
+Type-only imports from that package are safe. Test your actual application's
+eager import graph as well as isolated components.
+
+Use `createFiberSpringHost(['instancedMesh', 'meshStandardMaterial'])` to opt into
+additional hosts without registering every Three constructor. React, Fiber and
+React Spring peers are optional for the core material utilities, but required
+when using this subpath. `@react-spring/three` supplies host types only; it is not
+runtime-imported by this entry. The tested versions are React 19.3, Fiber 9.8.2,
+Three 0.186.1 and React Spring 10.1.2.
+
+## Rigid-object triplanar materials
+
+`createObjectTriplanarMaterial` keeps color, normal detail and roughness aligned
+without depending on mesh UVs. Coordinates remain local to the geometry, so a
+moving rigid object does not slide through a world-space texture field.
+
+```ts
+import { createObjectTriplanarMaterial } from '@absolutejs/rendering';
+import { RepeatWrapping, SRGBColorSpace, Vector2 } from 'three';
+
+for (const texture of [albedo, normal, roughness]) {
+  texture.wrapS = texture.wrapT = RepeatWrapping;
+}
+albedo.colorSpace = SRGBColorSpace; // normal and roughness remain non-color data
+const material = createObjectTriplanarMaterial({
+  map: albedo,
+  normalMap: normal,
+  roughnessMap: roughness,
+  normalScale: new Vector2(0.65, 0.65),
+  projection: { scale: 1, offset: [0, 0, 0], sharpness: 4 },
+});
+```
+
+Projection scale is repeats per geometry-local unit; UV texture matrices/repeat
+values are replaced by these controls. Offset and scale are copied at creation.
+Sharpness ranges from 1 to 16; scale must be finite, positive and at most 10,000.
+Color uses the texture's color space; roughness uses its green channel. Tangent
+normal maps, including packed RG and negative normal-Y scale, blend as surface
+slopes before perturbing the local normal. Neutral maps preserve base normals.
+
+Scope is opaque, rigid geometry. Mesh and non-sheared instanced transforms follow
+Three's normal-matrix conventions. Skinning, active morphs, displacement, bump maps,
+object-space normal maps and video albedo are rejected. Transparent, alpha-test,
+alpha-hash and alpha-to-coverage surfaces are rejected because they need matching
+shadow coverage shaders. Other StandardMaterial channels retain their normal Three
+behavior. The helper is for WebGLRenderer; it is not a WebGPU/TSL implementation.
+
+The material borrows textures and does not alter or dispose them. Use
+`cloneRenderMaterial` to retain shader hooks when cloning. Dispose material and
+owned textures separately. Standard lighting, shadows and geometry stay intact.
+With color, normal and roughness present, the shader uses nine texture samples
+instead of three UV samples, with no extra draw or render pass. Hardware cost is
+scene-dependent; the qualification uses software rendering, not a hardware FPS claim.

package/dist/index.d.ts

@@ -12,3 +12,5 @@ export declare function bindAlphaToCoverageDestination(material: Material, enabl
  * cannot alter another. No source material is mutated. */
 export declare function cloneRenderMaterial<T extends Material>(source: T): T;
 export { renderTargetScope, readTargetPixelsScoped, readFloatTargetScoped, } from "./renderTargetScope.js";
+export { createObjectTriplanarMaterial } from "./objectTriplanar.js";
+export type { ObjectTriplanarProjection, ObjectTriplanarMaterialParameters, } from "./objectTriplanar.js";

package/dist/index.js

@@ -76,3 +76,4 @@ export function cloneRenderMaterial(source) {
     return copy;
 }
 export { renderTargetScope, readTargetPixelsScoped, readFloatTargetScoped, } from "./renderTargetScope.js";
+export { createObjectTriplanarMaterial } from "./objectTriplanar.js";

package/dist/objectTriplanar.d.ts

@@ -0,0 +1,18 @@
+import { MeshStandardMaterial, type MeshStandardMaterialParameters } from "three";
+export type ObjectTriplanarProjection = {
+    /** Repeats per geometry-local unit; does not swim when an object moves. */
+    scale?: number;
+    /** Stable geometry-local phase, shared by color, normal and roughness. */
+    offset?: readonly [number, number, number];
+    /** Axis blending exponent. One is broad; larger values favor the dominant axis. */
+    sharpness?: number;
+};
+export type ObjectTriplanarMaterialParameters = MeshStandardMaterialParameters & {
+    projection?: ObjectTriplanarProjection;
+};
+/** UV-independent color, tangent-normal and roughness projection for rigid meshes.
+ * Borrows textures. Uses MeshStandardMaterial lighting/shadows and one draw.
+ * Instancing follows Three's non-sheared instance normal transform. Skinning,
+ * active morphs and displacement are outside this material's rigid-object scope.
+ * Use cloneRenderMaterial when cloning so the authored shader hooks are retained. */
+export declare function createObjectTriplanarMaterial(options?: ObjectTriplanarMaterialParameters): MeshStandardMaterial;

package/dist/objectTriplanar.js

@@ -0,0 +1,149 @@
+import { MeshStandardMaterial, TangentSpaceNormalMap, Vector3, } from "three";
+const revision = "absolute-object-triplanar-1";
+function replaceOnce(source, anchor, replacement) {
+    if (source.split(anchor).length !== 2)
+        throw Error(`Unsupported Three shader anchor: ${anchor}`);
+    return source.replace(anchor, replacement);
+}
+const varying = `
+varying vec3 absTriPosition;
+varying vec3 absTriObjectNormal;
+varying mat3 absTriNormalToView;
+`;
+const functions = `
+${varying}
+uniform float absTriScale;
+uniform vec3 absTriOffset;
+uniform float absTriSharpness;
+vec4 absTriSample(sampler2D tex, vec3 p, vec3 dx, vec3 dy, vec3 w) {
+ return textureGrad(tex,p.yz,dx.yz,dy.yz)*w.x
+      +textureGrad(tex,p.xz,dx.xz,dy.xz)*w.y
+      +textureGrad(tex,p.xy,dx.xy,dy.xy)*w.z;
+}
+#ifdef USE_NORMALMAP_TANGENTSPACE
+vec2 absTriSlope(vec3 encoded) {
+ vec3 n=encoded*2.-1.;
+ #ifdef USE_PACKED_NORMALMAP
+ n.z=sqrt(max(0.,1.-dot(n.xy,n.xy)));
+ #endif
+ return -n.xy*normalScale/max(n.z,.1);
+}
+vec3 absTriGradient(vec3 p,vec3 dx,vec3 dy,vec3 w) {
+ vec2 x=absTriSlope(textureGrad(normalMap,p.yz,dx.yz,dy.yz).xyz);
+ vec2 y=absTriSlope(textureGrad(normalMap,p.xz,dx.xz,dy.xz).xyz);
+ vec2 z=absTriSlope(textureGrad(normalMap,p.xy,dx.xy,dy.xy).xyz);
+ return vec3(0.,x.x,x.y)*w.x+vec3(y.x,0.,y.y)*w.y+vec3(z.x,z.y,0.)*w.z;
+}
+#endif
+`;
+const prepare = `
+vec3 absTriN=normalize(absTriObjectNormal);
+#ifdef FLAT_SHADED
+vec3 absTriArea=cross(dFdx(absTriPosition),dFdy(absTriPosition));
+if(dot(absTriArea,absTriArea)>1e-20) {
+ absTriArea=normalize(absTriArea);
+ absTriN=dot(absTriArea,absTriN)<0.?-absTriArea:absTriArea;
+}
+#endif
+vec3 absTriW=pow(abs(absTriN),vec3(absTriSharpness));
+absTriW/=max(dot(absTriW,vec3(1.)),1e-20);
+vec3 absTriP=absTriPosition*absTriScale+absTriOffset;
+vec3 absTriDx=dFdx(absTriP),absTriDy=dFdy(absTriP);
+`;
+/** UV-independent color, tangent-normal and roughness projection for rigid meshes.
+ * Borrows textures. Uses MeshStandardMaterial lighting/shadows and one draw.
+ * Instancing follows Three's non-sheared instance normal transform. Skinning,
+ * active morphs and displacement are outside this material's rigid-object scope.
+ * Use cloneRenderMaterial when cloning so the authored shader hooks are retained. */
+export function createObjectTriplanarMaterial(options = {}) {
+    const { projection = {}, ...parameters } = options;
+    const scale = projection.scale ?? 1;
+    const sharpness = projection.sharpness ?? 4;
+    const offset = [...(projection.offset ?? [0, 0, 0])];
+    if (!Number.isFinite(scale) || scale <= 0 || scale > 10000)
+        throw Error("Invalid triplanar scale");
+    if (!Number.isFinite(sharpness) || sharpness < 1 || sharpness > 16)
+        throw Error("Invalid triplanar sharpness");
+    if (offset.length !== 3 ||
+        offset.some((v) => !Number.isFinite(v) || Math.abs(v) > 1e6))
+        throw Error("Invalid triplanar offset");
+    if (parameters.bumpMap ||
+        parameters.displacementMap ||
+        (parameters.normalMapType !== undefined &&
+            parameters.normalMapType !== TangentSpaceNormalMap) ||
+        parameters.map?.isVideoTexture)
+        throw Error("Unsupported object-triplanar map type");
+    if (parameters.transparent ||
+        parameters.alphaHash ||
+        parameters.alphaToCoverage ||
+        (parameters.alphaTest ?? 0) > 0)
+        throw Error("Object triplanar mapping requires opaque coverage");
+    const material = new MeshStandardMaterial(parameters);
+    material.customProgramCacheKey = () => revision;
+    material.onBeforeRender = function (_renderer, _scene, _camera, _geometry, object) {
+        if (this.transparent ||
+            this.alphaHash ||
+            this.alphaToCoverage ||
+            this.alphaTest > 0)
+            throw Error("Object triplanar mapping requires opaque coverage");
+        if (this.bumpMap ||
+            this.displacementMap ||
+            this.normalMapType !== TangentSpaceNormalMap ||
+            this.map?.isVideoTexture)
+            throw Error("Unsupported object-triplanar map type");
+        const mesh = object;
+        if (mesh.isSkinnedMesh ||
+            mesh.morphTargetInfluences?.some((value) => value !== 0))
+            throw Error("Object triplanar mapping requires rigid geometry");
+    };
+    material.onBeforeCompile = (shader) => {
+        shader.uniforms.absTriScale = { value: scale };
+        shader.uniforms.absTriSharpness = { value: sharpness };
+        shader.uniforms.absTriOffset = {
+            value: new Vector3(offset[0], offset[1], offset[2]),
+        };
+        shader.vertexShader = replaceOnce(shader.vertexShader, "#include <common>", `#include <common>\n${varying}`);
+        shader.vertexShader = replaceOnce(shader.vertexShader, "#include <defaultnormal_vertex>", `#include <defaultnormal_vertex>
+mat3 absTriFrame=mat3(1.);
+#ifdef USE_BATCHING
+absTriFrame=mat3(bm[0]/dot(bm[0],bm[0]),bm[1]/dot(bm[1],bm[1]),bm[2]/dot(bm[2],bm[2]))*absTriFrame;
+#endif
+#ifdef USE_INSTANCING
+absTriFrame=mat3(im[0]/dot(im[0],im[0]),im[1]/dot(im[1],im[1]),im[2]/dot(im[2],im[2]))*absTriFrame;
+#endif
+absTriNormalToView=normalMatrix*absTriFrame;
+absTriObjectNormal=objectNormal;
+`);
+        shader.vertexShader = replaceOnce(shader.vertexShader, "#include <begin_vertex>", "#include <begin_vertex>\nabsTriPosition=transformed;");
+        // Normal-map declarations precede helper functions that use their uniforms.
+        shader.fragmentShader = replaceOnce(shader.fragmentShader, "#include <normalmap_pars_fragment>", `#include <normalmap_pars_fragment>\n${functions}`);
+        shader.fragmentShader = replaceOnce(shader.fragmentShader, "#include <map_fragment>", `${prepare}
+#ifdef USE_MAP
+diffuseColor*=absTriSample(map,absTriP,absTriDx,absTriDy,absTriW);
+#endif
+`);
+        shader.fragmentShader = replaceOnce(shader.fragmentShader, "#include <roughnessmap_fragment>", `
+float roughnessFactor=roughness;
+#ifdef USE_ROUGHNESSMAP
+roughnessFactor*=absTriSample(roughnessMap,absTriP,absTriDx,absTriDy,absTriW).g;
+#endif
+`);
+        shader.fragmentShader = replaceOnce(shader.fragmentShader, "#include <normal_fragment_maps>", `
+#ifdef USE_NORMALMAP_TANGENTSPACE
+vec3 absTriG=absTriGradient(absTriP,absTriDx,absTriDy,absTriW);
+vec3 absTriSurfaceG=absTriG-absTriN*dot(absTriG,absTriN);
+if(dot(absTriSurfaceG,absTriSurfaceG)>1e-20) {
+ vec3 absTriBumped=normalize(absTriNormalToView*(absTriN-absTriSurfaceG));
+ #ifdef FLIP_SIDED
+ absTriBumped=-absTriBumped;
+ #endif
+ #ifdef DOUBLE_SIDED
+ absTriBumped*=faceDirection;
+ #endif
+ normal=absTriBumped;
+}
+#endif
+`);
+    };
+    return material;
+}

package/dist/spring.d.ts

@@ -0,0 +1,10 @@
+import { type ThreeElements } from "@react-three/fiber";
+import type { WithAnimated } from "@react-spring/three";
+/** Explicit Three hosts driven by React Spring's normal scheduler. Updating a
+ * Three prop invalidates its Fiber root; DOM-only springs do not render a scene.
+ * Does not install a global clock, call useFrame, or repair another module's
+ * scheduler changes. Avoid runtime imports of @react-spring/three alongside it. */
+export declare function createFiberSpringHost<T extends keyof ThreeElements>(primitives: readonly T[]): Pick<WithAnimated, T>;
+/** Small default host; opt into other Fiber primitives with createFiberSpringHost. */
+export declare const animated: Pick<WithAnimated, "group" | "mesh">;
+export { useSpring, easings } from "@react-spring/web";

package/dist/spring.js

@@ -0,0 +1,13 @@
+import { applyProps } from "@react-three/fiber";
+import { createHost } from "@react-spring/animated";
+/** Explicit Three hosts driven by React Spring's normal scheduler. Updating a
+ * Three prop invalidates its Fiber root; DOM-only springs do not render a scene.
+ * Does not install a global clock, call useFrame, or repair another module's
+ * scheduler changes. Avoid runtime imports of @react-spring/three alongside it. */
+export function createFiberSpringHost(primitives) {
+    return createHost([...primitives], { applyAnimatedValues: applyProps })
+        .animated;
+}
+/** Small default host; opt into other Fiber primitives with createFiberSpringHost. */
+export const animated = createFiberSpringHost(["mesh", "group"]);
+export { useSpring, easings } from "@react-spring/web";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@absolutejs/rendering",
-  "version": "0.2.0",
-  "description": "Render-destination coverage policies and callback-preserving material ownership for Three.js applications.",
+  "version": "0.4.0",
+  "description": "Three.js material ownership, destination coverage, rigid-object triplanar mapping and isolated React Spring hosts.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,6 +10,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./spring": {
+      "types": "./dist/spring.d.ts",
+      "import": "./dist/spring.js",
+      "default": "./dist/spring.js"
     }
   },
   "files": [
@@ -31,16 +36,49 @@
     "build": "tsc -p tsconfig.json",
     "test": "bun test ./tests",
     "check:package": "bun run build && bun run test",
-    "test:browser": "bun scripts/verify-browser.cjs"
+    "test:browser": "bun scripts/verify-browser.cjs",
+    "test:spring:browser": "bun scripts/verify-spring.cjs",
+    "test:triplanar:browser": "bun scripts/verify-triplanar.cjs"
   },
   "peerDependencies": {
-    "three": ">=0.186.0 <0.187.0"
+    "three": ">=0.186.0 <0.187.0",
+    "react": ">=19.3.0 <20",
+    "@react-three/fiber": ">=9.8.2 <10",
+    "@react-spring/animated": ">=10.1.2 <11",
+    "@react-spring/web": ">=10.1.2 <11",
+    "@react-spring/three": ">=10.1.2 <11"
   },
   "devDependencies": {
     "three": "0.186.1",
     "@types/three": "0.186.0",
     "@types/bun": "1.4.2",
     "typescript": "5.9.3",
-    "playwright": "1.61.1"
+    "playwright": "1.61.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@react-three/fiber": "9.8.2",
+    "@react-spring/animated": "10.1.2",
+    "@react-spring/web": "10.1.2",
+    "@react-spring/three": "10.1.2",
+    "@react-spring/shared": "10.1.2"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@react-three/fiber": {
+      "optional": true
+    },
+    "@react-spring/animated": {
+      "optional": true
+    },
+    "@react-spring/web": {
+      "optional": true
+    },
+    "@react-spring/three": {
+      "optional": true
+    }
   }
 }