@absolutejs/rendering 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,88 @@
+# Business Source License 1.1
+
+**Licensor:** Alex Kahn
+
+**Licensed Work:** @absolutejs/rendering (https://github.com/absolutejs/rendering)
+
+**Change Date:** November 1, 2030
+
+**Change License:** Apache License, Version 2.0
+
+---
+
+## Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, permitting limited production use.
+
+### Additional Use Grant
+
+You may use the Licensed Work in production, provided your use does not include
+any of the following:
+
+1. **Offering a Competing Service.** You may not offer the Licensed Work, or
+   any derivative or substantial portion of it, to third parties as a hosted or
+   managed service that competes with a hosted rendering or 3D authoring service. This includes any
+   product whose primary value to its users is the functionality the Licensed
+   Work provides.
+
+2. **Resale or Redistribution as a Standalone Product.** You may not sell,
+   license, or distribute the Licensed Work, or any derivative or fork of it,
+   as a standalone commercial product.
+
+3. **Removal of Attribution.** Any derivative work, fork, or redistribution of
+   the Licensed Work must prominently credit AbsoluteJS and include a link to
+   the original project repository (https://github.com/absolutejs/rendering).
+
+For clarity, the following uses are expressly permitted:
+
+- Using the Licensed Work to build and operate your own applications, websites,
+  internal tools, or SaaS products (whether commercial or non-commercial), so
+  long as the Licensed Work itself is not the primary product you are selling.
+- Using the Licensed Work as a dependency in commercial software you build and
+  sell, as long as the software is not itself a competing managed service of
+  the kind described in clause 1.
+- Providing consulting, development, or professional services to clients using
+  the Licensed Work.
+- Forking and modifying the Licensed Work for your own internal use, provided
+  attribution is maintained.
+
+### Change Date and Change License
+
+On the Change Date specified above, or on such other date as the Licensor may
+specify by written notice, the Licensed Work will be made available under the
+Change License (Apache License, Version 2.0). Until the Change Date, the terms
+of this Business Source License 1.1 apply.
+
+### Trademark
+
+This license does not grant you any rights to use the "AbsoluteJS" or
+"@absolutejs" name, logo, or any related trademarks. Forks and derivative works
+must not be named or branded in a manner that suggests endorsement by or
+affiliation with AbsoluteJS or the Licensor.
+
+### Notices
+
+You must not remove or obscure any licensing, copyright, or other notices
+included in the Licensed Work.
+
+### No Warranty
+
+THE LICENSED WORK IS PROVIDED "AS IS". THE LICENSOR HEREBY DISCLAIMS ALL
+WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR
+IN CONNECTION WITH THE LICENSED WORK OR THE USE OR OTHER DEALINGS IN THE
+LICENSED WORK.
+
+---
+
+## Contact
+
+For commercial licensing inquiries or additional permissions, contact:
+
+- **Alex Kahn**
+- alexkahndev@gmail.com
+- alexkahndev.github.io

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @absolutejs/rendering
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Small Three.js material-lifecycle utilities for AbsoluteJS applications and 3D authoring tools. These complement R3F and drei; they do not provide a scene graph, camera controls, effects composer or renderer replacement.
+
+## Coverage follows the destination
+
+A multisampled canvas does not make a reflection texture multisampled. An alpha-to-coverage shader used unchanged in a single-sample target can draw partially covered foliage as solid pixels.
+
+```ts
+import { bindAlphaToCoverageDestination } from '@absolutejs/rendering';
+material.alphaToCoverage = true;
+const unbind = bindAlphaToCoverageDestination(material);
+// On every draw, the policy selects coverage from the active render destination.
+// Call unbind() when removing the policy while retaining the material.
+```
+
+The policy runs after the previous material callback and before Three selects the program. It updates the material only when the effective coverage mode changes. Three can cache the corresponding program variants. It does not inject shaders, allocate textures, traverse the scene, monkey-patch a renderer, or call synchronous GPU queries per draw.
+
+Shader customizations must retain their non-ALPHA_TO_COVERAGE fallback. The policy uses declared render-target sample counts, bounded by renderer support; callers must create targets with supported attachment formats. Canvas antialias attributes are cached per renderer, but a lost context is not cached as a permanent capability result. Disabled preferences remain disabled on all destinations. Shadow passes that call renderBufferDirect require their own depth-material policy; this callback targets normal material draws.
+
+Rebinding updates the existing preference without stacking callbacks. The returned disposer is idempotent and restores the original flag and callback only while it still owns the callback slot; it will not overwrite a later owner.
+
+## Clone customized materials safely
+
+```ts
+import { cloneRenderMaterial } from '@absolutejs/rendering';
+const owned = cloneRenderMaterial(source);
+// Textures remain borrowed. Dispose the clone, not the source's textures.
+```
+
+This retains onBeforeCompile, customProgramCacheKey and onBeforeRender. A registered destination policy is cloned independently, including when the source was last drawn into a non-MSAA target. Changing the clone's preference cannot affect the source. This does not clone arbitrary object callbacks, custom depth materials or scene state.
+
+## Compatibility and scope
+
+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.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import type { Material, WebGLRenderer } from "three";
+/** Resolve the destination's declared sample count without a synchronous GPU
+ * query per draw. Render targets must have a supported attachment configuration. */
+export declare function destinationIsMultisampled(renderer: WebGLRenderer): boolean;
+/** Select coverage before program selection for each draw, including captures.
+ * Shader hooks must retain their non-ALPHA_TO_COVERAGE fallback. Rebinding is
+ * idempotent; disposal restores the previous callback/state while still owned.
+ * No global renderer monkey patch, traversal, texture allocation or shader text. */
+export declare function bindAlphaToCoverageDestination(material: Material, enabled?: boolean): () => void;
+/** Own the clone, borrow its textures, preserve authored shader/render hooks.
+ * 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

@@ -0,0 +1,78 @@
+const bindings = new WeakMap();
+const canvasSampling = new WeakMap();
+function setCoverage(material, enabled) {
+    if (material.alphaToCoverage === enabled)
+        return;
+    material.alphaToCoverage = enabled;
+    material.needsUpdate = true;
+}
+/** Resolve the destination's declared sample count without a synchronous GPU
+ * query per draw. Render targets must have a supported attachment configuration. */
+export function destinationIsMultisampled(renderer) {
+    const target = renderer.getRenderTarget();
+    if (target)
+        return target.samples > 0 && renderer.capabilities.maxSamples > 0;
+    let sampled = canvasSampling.get(renderer);
+    if (sampled === undefined) {
+        const attributes = renderer.getContextAttributes();
+        if (!attributes)
+            return false; // Do not cache context loss as a permanent capability.
+        sampled = attributes.antialias === true;
+        canvasSampling.set(renderer, sampled);
+    }
+    return sampled;
+}
+/** Select coverage before program selection for each draw, including captures.
+ * Shader hooks must retain their non-ALPHA_TO_COVERAGE fallback. Rebinding is
+ * idempotent; disposal restores the previous callback/state while still owned.
+ * No global renderer monkey patch, traversal, texture allocation or shader text. */
+export function bindAlphaToCoverageDestination(material, enabled = material.alphaToCoverage) {
+    if (typeof enabled !== "boolean")
+        throw Error("Invalid coverage preference");
+    const existing = bindings.get(material);
+    if (existing && material.onBeforeRender === existing.callback) {
+        existing.enabled = enabled;
+        return existing.dispose;
+    }
+    const previous = material.onBeforeRender, originalCoverage = material.alphaToCoverage;
+    let disposed = false;
+    const state = {
+        enabled,
+        previous,
+        callback: function (...args) {
+            previous.apply(this, args);
+            setCoverage(this, state.enabled && destinationIsMultisampled(args[0]));
+        },
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            if (material.onBeforeRender === state.callback) {
+                material.onBeforeRender = previous;
+                setCoverage(material, originalCoverage);
+            }
+            if (bindings.get(material) === state)
+                bindings.delete(material);
+        },
+    };
+    material.onBeforeRender = state.callback;
+    bindings.set(material, state);
+    return state.dispose;
+}
+/** Own the clone, borrow its textures, preserve authored shader/render hooks.
+ * Destination policy is cloned independently so changing one owner's preference
+ * cannot alter another. No source material is mutated. */
+export function cloneRenderMaterial(source) {
+    const copy = source.clone();
+    copy.onBeforeCompile = source.onBeforeCompile;
+    copy.customProgramCacheKey = source.customProgramCacheKey;
+    const binding = bindings.get(source);
+    if (binding && source.onBeforeRender === binding.callback) {
+        copy.onBeforeRender = binding.previous;
+        bindAlphaToCoverageDestination(copy, binding.enabled);
+    }
+    else
+        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/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@absolutejs/rendering",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Render-destination coverage policies and callback-preserving material ownership for Three.js applications.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "license": "BSL-1.1",
+  "author": "Alex Kahn",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/absolutejs/rendering.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "bun test ./tests",
+    "check:package": "bun run build && bun run test",
+    "test:browser": "bun scripts/verify-browser.cjs"
+  },
+  "peerDependencies": {
+    "three": ">=0.186.0 <0.187.0"
+  },
+  "devDependencies": {
+    "three": "0.186.1",
+    "@types/three": "0.186.0",
+    "@types/bun": "1.4.2",
+    "typescript": "5.9.3",
+    "playwright": "1.61.1"
+  }
+}