@absolutejs/geometry 0.1.0 → 0.1.1

package/README.md

@@ -75,3 +75,24 @@ Run `bun install --frozen-lockfile` and `bun run check:package`.
 and its development asset tooling; see docs/canopy-audit/README.md.
 
 Licensed under BSL-1.1; see LICENSE for the additional use grant and change date.
+
+## Worker-side alpha preparation (0.1.1)
+
+`alphaFromRgba(rgba, width, height)` copies one alpha byte per RGBA8 texel into an
+owned Uint8Array. It accepts Uint8Array or Uint8ClampedArray and validates the
+exact byte length and the same 4,194,304-texel budget before allocation.
+
+`alphaFromImageBitmap(bitmap)` reads an already decoded bitmap using a temporary
+OffscreenCanvas 2D context with `willReadFrequently: true`. Call it in a worker;
+it performs synchronous CPU readback wherever it is called. The temporary canvas
+is released afterward. It does not create a WebGL context, close the input bitmap,
+or detach any borrowed renderer resource. The caller owns bitmap cleanup.
+Unsupported runtimes, closed/invalid bitmaps and oversized images fail explicitly.
+There is no hidden main-thread fallback.
+
+ImageBitmap supports structured cloning as well as transfer. The browser-worker
+qualification checks exact alpha values and that closing a cloned worker image
+leaves its source usable. Transfer only owned copies if using a transfer list.
+See the [HTML ImageBitmap ownership contract](https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap)
+and [OffscreenCanvas](https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas).
+These helpers prepare raster inputs; they do not assign hydrologic meaning to alpha.

package/dist/alpha.d.ts

@@ -0,0 +1,5 @@
+/** Copy one alpha byte per row-major RGBA8 texel. Does not mutate borrowed pixels. */
+export declare function alphaFromRgba(rgba: Uint8Array | Uint8ClampedArray, width: number, height: number): Uint8Array;
+/** Worker/setup-time CPU readback. The caller owns and closes the bitmap.
+ * This never closes/detaches the caller's image and never creates a WebGL context. */
+export declare function alphaFromImageBitmap(bitmap: ImageBitmap): Uint8Array;

package/dist/alpha.js

@@ -0,0 +1,37 @@
+const MAX_TEXELS = 4_194_304;
+function validateSize(width, height) {
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1 || width * height > MAX_TEXELS)
+        throw Error('Invalid or oversized alpha source');
+}
+/** Copy one alpha byte per row-major RGBA8 texel. Does not mutate borrowed pixels. */
+export function alphaFromRgba(rgba, width, height) {
+    validateSize(width, height);
+    if (!(rgba instanceof Uint8Array || rgba instanceof Uint8ClampedArray) || rgba.length !== width * height * 4)
+        throw Error('Expected tightly packed RGBA8 alpha source');
+    const alpha = new Uint8Array(width * height);
+    for (let i = 0; i < alpha.length; i++)
+        alpha[i] = rgba[i * 4 + 3];
+    return alpha;
+}
+/** Worker/setup-time CPU readback. The caller owns and closes the bitmap.
+ * This never closes/detaches the caller's image and never creates a WebGL context. */
+export function alphaFromImageBitmap(bitmap) {
+    if (typeof ImageBitmap === 'undefined' || !(bitmap instanceof ImageBitmap))
+        throw Error('Expected an available ImageBitmap');
+    validateSize(bitmap.width, bitmap.height);
+    if (typeof OffscreenCanvas === 'undefined')
+        throw Error('OffscreenCanvas is unavailable for alpha readback');
+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+    try {
+        const context = canvas.getContext('2d', { willReadFrequently: true });
+        if (!context)
+            throw Error('Canvas2D is unavailable for alpha readback');
+        context.drawImage(bitmap, 0, 0);
+        const pixels = context.getImageData(0, 0, bitmap.width, bitmap.height);
+        return alphaFromRgba(pixels.data, pixels.width, pixels.height);
+    }
+    finally {
+        canvas.width = 0;
+        canvas.height = 0;
+    }
+}

package/dist/index.d.ts

@@ -1 +1,2 @@
 export { projectAlphaCoverage, type AlphaProjectionInput, type AlphaProjection, } from "./projection.js";
+export { alphaFromRgba, alphaFromImageBitmap } from './alpha.js';

package/dist/index.js

@@ -1 +1,2 @@
 export { projectAlphaCoverage, } from "./projection.js";
+export { alphaFromRgba, alphaFromImageBitmap } from './alpha.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/geometry",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Bounded alpha-aware geometry projection for worker-side asset measurement and web 3D tooling.",
   "type": "module",
   "main": "./dist/index.js",