@absolutejs/rendering 0.2.0 → 0.3.0

package/README.md

@@ -54,3 +54,36 @@ 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.

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,6 +1,6 @@
 {
   "name": "@absolutejs/rendering",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Render-destination coverage policies and callback-preserving material ownership for Three.js applications.",
   "type": "module",
   "main": "./dist/index.js",
@@ -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,48 @@
     "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"
   },
   "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
+    }
   }
 }