@absolutejs/rendering 0.1.0 → 0.3.0

package/README.md

@@ -35,3 +35,55 @@ This retains onBeforeCompile, customProgramCacheKey and onBeforeRender. A regist
 Qualified against Three r186. No React dependency and no animation loop. Runtime cost is a small callback and destination check per affected draw; switching sampling modes can select another cached shader program. Hardware frame-rate improvements are not claimed. Game-specific foliage algorithms, lighting, world generation and simulation remain outside this package.
 
 Use `bun run check:package` to build declarations and run the ownership/policy tests. Browser evidence is retained under docs/.
+
+## Scoped captures and readback
+
+`renderTargetScope(renderer, run)` restores the render target, cube face, mip,
+viewport, scissor and scissor-test state even if synchronous work throws. The
+callback must finish renderer mutations synchronously; do not hold a scope over
+an await.
+
+`readTargetPixelsScoped(renderer, target, width, height, buffer, textureIndex?)`
+submits a byte/float read from a neutral target and restores the caller through
+Three's target setter. This avoids restoring a resolve framebuffer in place of
+its multisample draw attachment, or treating a cube framebuffer array as a single
+framebuffer.
+
+`readFloatTargetScoped(...)` submits asynchronous float readback in the same
+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/index.d.ts

@@ -11,3 +11,4 @@ export declare function bindAlphaToCoverageDestination(material: Material, enabl
  * Destination policy is cloned independently so changing one owner's preference
  * 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";

package/dist/index.js

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

package/dist/renderTargetScope.d.ts

@@ -0,0 +1,18 @@
+import { type WebGLRenderer } from "three";
+/** Synchronous offscreen work; preserve target attachment, viewport and clipping.
+ * The callback must finish its renderer mutations before returning.
+ */
+export declare function renderTargetScope<T>(renderer: WebGLRenderer, run: () => T): T;
+/** Start an async float diagnostic with a neutral current target, then immediately
+ * restore the caller's attachment. Three's async reader restores a raw framebuffer
+ * property before awaiting; cube/mipmap targets store arrays in that property.
+ * Keeping the neutral target only for submission avoids that invalid bind without
+ * holding renderer state across the asynchronous wait.
+ */
+export declare function readFloatTargetScoped(renderer: WebGLRenderer, target: import("three").WebGLRenderTarget, width: number, height: number, buffer: Float32Array, textureIndex?: number): Promise<Float32Array>;
+/** Synchronous authoring/diagnostic read. Three restores the raw resolve
+ * framebuffer, not a current target's multisample attachment, after reading.
+ * Submit from a neutral target and let setRenderTarget restore the actual
+ * attachment; otherwise the next draw can resolve stale samples over new data.
+ * This also avoids restoring cube/mip framebuffer arrays as a framebuffer. */
+export declare function readTargetPixelsScoped(renderer: WebGLRenderer, target: import("three").WebGLRenderTarget, width: number, height: number, buffer: Uint8Array | Float32Array, textureIndex?: number): void;

package/dist/renderTargetScope.js

@@ -0,0 +1,47 @@
+import { Vector4 } from "three";
+/** Synchronous offscreen work; preserve target attachment, viewport and clipping.
+ * The callback must finish its renderer mutations before returning.
+ */
+export function renderTargetScope(renderer, run) {
+    const target = renderer.getRenderTarget(), face = renderer.getActiveCubeFace(), mip = renderer.getActiveMipmapLevel();
+    const viewport = renderer.getViewport(new Vector4()), scissor = renderer.getScissor(new Vector4()), test = renderer.getScissorTest();
+    try {
+        renderer.setScissorTest(false);
+        return run();
+    }
+    finally {
+        renderer.setRenderTarget(target, face, mip);
+        renderer.setViewport(viewport);
+        renderer.setScissor(scissor);
+        renderer.setScissorTest(test);
+    }
+}
+/** Start an async float diagnostic with a neutral current target, then immediately
+ * restore the caller's attachment. Three's async reader restores a raw framebuffer
+ * property before awaiting; cube/mipmap targets store arrays in that property.
+ * Keeping the neutral target only for submission avoids that invalid bind without
+ * holding renderer state across the asynchronous wait.
+ */
+export function readFloatTargetScoped(renderer, target, width, height, buffer, textureIndex = 0) {
+    let pending;
+    renderTargetScope(renderer, () => {
+        renderer.setRenderTarget(null);
+        pending = renderer.readRenderTargetPixelsAsync(target, 0, 0, width, height, buffer, undefined, textureIndex);
+    });
+    return pending.then((value) => {
+        if (value !== buffer)
+            throw new Error("Float target read did not return its buffer");
+        return buffer;
+    });
+}
+/** Synchronous authoring/diagnostic read. Three restores the raw resolve
+ * framebuffer, not a current target's multisample attachment, after reading.
+ * Submit from a neutral target and let setRenderTarget restore the actual
+ * attachment; otherwise the next draw can resolve stale samples over new data.
+ * This also avoids restoring cube/mip framebuffer arrays as a framebuffer. */
+export function readTargetPixelsScoped(renderer, target, width, height, buffer, textureIndex = 0) {
+    renderTargetScope(renderer, () => {
+        renderer.setRenderTarget(null);
+        renderer.readRenderTargetPixels(target, 0, 0, width, height, buffer, undefined, textureIndex);
+    });
+}

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.1.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
+    }
   }
 }