@aura3d/addons 0.0.0-stage → 5.0.1

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @aura3d/addons
 
-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.
+Optional Aura3D modules for spatial DOM and vector output, alternative visual outputs, procedural objects and generators, editable geometry tools, and bounded worker tasks. Each module is independently authored for Aura3D. These entrypoints are separate from the engine root, and can be imported individually, for example:
+
+```ts
+import { WorkerPool } from "@aura3d/addons/utils/WorkerPool";
+import { fractureConvex } from "@aura3d/addons/tools/Fracture";
+```
+
+Install the package alongside compatible Aura3D packages. Output effects use `@aura3d/rendering`; that package is declared as a dependency. DOM renderers require browser DOM objects when constructed. Each module documents its own input limits, ownership, teardown, and unsupported content. Generated geometry and outputs remain caller-owned unless the API explicitly transfers ownership.
+
+The package provides source implementations; browser and hardware support claims require the applicable runtime evidence.

package/dist/effects/AsciiOutput.d.ts

@@ -0,0 +1,60 @@
+import type { CameraLike, RenderItem, RenderSource, Renderer } from "@aura3d/rendering";
+import type { Scene } from "@aura3d/scene";
+export interface AsciiOutputOptions {
+    /** Character columns and rows, not device pixels. */
+    readonly width: number;
+    readonly height: number;
+    /** Characters ordered from darkest to brightest. Unicode code points are allowed. */
+    readonly characters?: string;
+    readonly invert?: boolean;
+    /** Render resolution per character dimension, from 1 to 16 (default 2). */
+    readonly sampleScale?: number;
+    /** Supplied by and still owned by the caller. Child nodes and attributes are restored on disposal. */
+    readonly element?: HTMLElement;
+    readonly accessibleLabel?: string;
+}
+export interface AsciiPixels {
+    readonly width: number;
+    readonly height: number;
+    readonly pixels: Uint8Array | Uint8ClampedArray;
+    readonly origin?: "top-left" | "bottom-left";
+}
+export interface AsciiOutputFrame {
+    readonly width: number;
+    readonly height: number;
+    readonly text: string;
+}
+export type AsciiSource = RenderSource | Iterable<RenderItem> | Scene;
+/**
+ * A bounded luminance-to-text output. Pixels are interpreted as unpremultiplied
+ * sRGB and composited over black before area averaging. Characters are inserted
+ * as text, never HTML. Rendering captures a private target and requires exclusive
+ * renderer access until the returned promise settles. Captured bytes use the
+ * same straight-alpha interpretation; a renderer with transparent compositing
+ * may have associated RGB, so use an opaque clear for consistent luminance.
+ * The target and optional DOM mutations are released by dispose().
+ */
+export declare class AsciiOutput {
+    private width;
+    private height;
+    private readonly characters;
+    private readonly invert;
+    private readonly scale;
+    private readonly element?;
+    private readonly originalElement?;
+    private target;
+    private targetOwner;
+    private busy;
+    private disposed;
+    constructor(options: AsciiOutputOptions);
+    setSize(width: number, height: number): void;
+    /** Convert caller-supplied pixels. The same conversion is used by render(). */
+    renderPixels(input: AsciiPixels): AsciiOutputFrame;
+    render(renderer: Pick<Renderer, "device" | "render" | "renderAsync">, source: AsciiSource, camera?: CameraLike): Promise<AsciiOutputFrame>;
+    dispose(): void;
+    private ensureTarget;
+    private releaseTarget;
+    private validateCaptureSize;
+    private assertUsable;
+}
+//# sourceMappingURL=AsciiOutput.d.ts.map

package/dist/effects/AsciiOutput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsciiOutput.d.ts","sourceRoot":"","sources":["../../src/effects/AsciiOutput.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAgB,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACtG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,sGAAsG;IACtG,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AACD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,iBAAiB,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC;CAC9C;AACD,MAAM,WAAW,gBAAgB;IAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAC7G,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC;AAKtE;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAkH;IACnJ,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,WAAW,CAAoE;IACvF,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,kBAAkB;IAwBvC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAW5C,+EAA+E;IAC/E,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,gBAAgB;IAsC5C,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2BhJ,OAAO,IAAI,IAAI;IAef,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,mBAAmB;IAC3B,OAAO,CAAC,YAAY;CACrB"}

package/dist/effects/AsciiOutput.js

@@ -0,0 +1,187 @@
+const MAX_CELLS = 20_000;
+const MAX_PIXELS = 4_194_304;
+/**
+ * A bounded luminance-to-text output. Pixels are interpreted as unpremultiplied
+ * sRGB and composited over black before area averaging. Characters are inserted
+ * as text, never HTML. Rendering captures a private target and requires exclusive
+ * renderer access until the returned promise settles. Captured bytes use the
+ * same straight-alpha interpretation; a renderer with transparent compositing
+ * may have associated RGB, so use an opaque clear for consistent luminance.
+ * The target and optional DOM mutations are released by dispose().
+ */
+export class AsciiOutput {
+    width;
+    height;
+    characters;
+    invert;
+    scale;
+    element;
+    originalElement;
+    target = null;
+    targetOwner = null;
+    busy = false;
+    disposed = false;
+    constructor(options) {
+        validateCells(options.width, options.height);
+        this.width = options.width;
+        this.height = options.height;
+        this.characters = [...(options.characters ?? " .:-=+*#%@")];
+        if (this.characters.length < 2 || this.characters.length > 128 || this.characters.some((char) => /[\u0000-\u001f\u007f]/u.test(char)))
+            throw new RangeError("ASCII character ramp must contain 2 to 128 printable characters");
+        this.invert = options.invert ?? false;
+        this.scale = options.sampleScale ?? 2;
+        if (!Number.isInteger(this.scale) || this.scale < 1 || this.scale > 16)
+            throw new RangeError("sampleScale must be an integer in [1, 16]");
+        this.validateCaptureSize();
+        this.element = options.element;
+        if (this.element) {
+            this.originalElement = {
+                children: Array.from(this.element.childNodes),
+                role: this.element.getAttribute("role"),
+                label: this.element.getAttribute("aria-label"),
+                whiteSpace: [this.element.style.getPropertyValue("white-space"), this.element.style.getPropertyPriority("white-space")]
+            };
+            this.element.style.whiteSpace = "pre";
+            this.element.setAttribute("role", "img");
+            this.element.setAttribute("aria-label", options.accessibleLabel ?? "ASCII rendering");
+        }
+    }
+    setSize(width, height) {
+        this.assertUsable();
+        if (this.busy)
+            throw new Error("Cannot resize ASCII output during render");
+        validateCells(width, height);
+        if (width * height * this.scale * this.scale > MAX_PIXELS)
+            throw new RangeError(`ASCII capture may not exceed ${MAX_PIXELS} pixels`);
+        if (width === this.width && height === this.height)
+            return;
+        this.width = width;
+        this.height = height;
+        this.releaseTarget();
+    }
+    /** Convert caller-supplied pixels. The same conversion is used by render(). */
+    renderPixels(input) {
+        this.assertUsable();
+        validatePixels(input);
+        // When a very narrow image is expanded into a wide character grid (or
+        // vice versa), samples are intentionally reused. Bound this work as well
+        // as the two independent input/output allocation sizes.
+        if (Math.max(input.width, this.width) * Math.max(input.height, this.height) > MAX_PIXELS * 2)
+            throw new RangeError("ASCII sampling work exceeds the pixel budget");
+        const rows = [];
+        for (let row = 0; row < this.height; row += 1) {
+            let line = "";
+            const y0 = row * input.height / this.height;
+            const y1 = (row + 1) * input.height / this.height;
+            for (let col = 0; col < this.width; col += 1) {
+                const x0 = col * input.width / this.width;
+                const x1 = (col + 1) * input.width / this.width;
+                let sum = 0;
+                let area = 0;
+                // A boundary may split an input pixel between cells. Weight by the
+                // actual overlap rather than assigning the whole pixel to one cell.
+                for (let y = Math.floor(y0); y < Math.min(input.height, Math.ceil(y1)); y += 1)
+                    for (let x = Math.floor(x0); x < Math.min(input.width, Math.ceil(x1)); x += 1) {
+                        const sy = input.origin === "bottom-left" ? input.height - y - 1 : y;
+                        const offset = (sy * input.width + x) * 4;
+                        const alpha = input.pixels[offset + 3] / 255;
+                        const weight = (Math.min(x + 1, x1) - Math.max(x, x0)) * (Math.min(y + 1, y1) - Math.max(y, y0));
+                        sum += (0.2126 * input.pixels[offset] + 0.7152 * input.pixels[offset + 1] + 0.0722 * input.pixels[offset + 2]) * alpha * weight;
+                        area += weight;
+                    }
+                let brightness = Math.max(0, Math.min(1, sum / (area * 255)));
+                if (this.invert)
+                    brightness = 1 - brightness;
+                line += this.characters[Math.min(this.characters.length - 1, Math.floor(brightness * this.characters.length))];
+            }
+            rows.push(line);
+        }
+        const text = rows.join("\n");
+        if (this.element)
+            this.element.textContent = text;
+        return { width: this.width, height: this.height, text };
+    }
+    async render(renderer, source, camera) {
+        this.assertUsable();
+        if (this.busy)
+            throw new Error("An ASCII render is already in progress");
+        const device = renderer.device;
+        if (!device.getRenderTarget)
+            throw new Error("ASCII output requires getRenderTarget for safe state restoration");
+        const previous = device.getRenderTarget();
+        this.busy = true;
+        try {
+            const target = this.ensureTarget(renderer);
+            const input = { source, camera, target };
+            if (device.kind === "webgpu")
+                await renderer.renderAsync(input);
+            else
+                renderer.render(input);
+            device.setRenderTarget(target);
+            const pixels = device.kind === "webgpu" && device.readPixelsAsync
+                ? await device.readPixelsAsync(0, 0, target.width, target.height)
+                : device.readPixels(0, 0, target.width, target.height);
+            if (this.disposed)
+                throw new Error("ASCII output was disposed during render");
+            return this.renderPixels({ width: target.width, height: target.height, pixels, origin: device.kind === "webgl2" ? "bottom-left" : "top-left" });
+        }
+        finally {
+            try {
+                device.setRenderTarget(previous);
+            }
+            finally {
+                this.busy = false;
+                if (this.disposed)
+                    this.releaseTarget();
+            }
+        }
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (!this.busy)
+            this.releaseTarget();
+        if (this.element && this.originalElement) {
+            this.element.replaceChildren();
+            for (const child of this.originalElement.children)
+                this.element.appendChild(child);
+            restoreAttribute(this.element, "role", this.originalElement.role);
+            restoreAttribute(this.element, "aria-label", this.originalElement.label);
+            const [whiteSpace, priority] = this.originalElement.whiteSpace;
+            if (whiteSpace)
+                this.element.style.setProperty("white-space", whiteSpace, priority);
+            else
+                this.element.style.removeProperty("white-space");
+        }
+    }
+    ensureTarget(renderer) {
+        if (this.target && (this.target.disposed || this.targetOwner !== renderer))
+            this.releaseTarget();
+        if (!this.target) {
+            this.target = renderer.device.createRenderTarget({ width: this.width * this.scale, height: this.height * this.scale, format: "rgba8", depth: true, label: "a3d.ascii" });
+            this.targetOwner = renderer;
+        }
+        return this.target;
+    }
+    releaseTarget() { this.target?.dispose(); this.target = null; this.targetOwner = null; }
+    validateCaptureSize() { if (this.width * this.height * this.scale * this.scale > MAX_PIXELS)
+        throw new RangeError(`ASCII capture may not exceed ${MAX_PIXELS} pixels`); }
+    assertUsable() { if (this.disposed)
+        throw new Error("ASCII output is disposed"); }
+}
+function validateCells(width, height) {
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0 || width * height > MAX_CELLS)
+        throw new RangeError(`ASCII output dimensions must be positive and at most ${MAX_CELLS} cells`);
+}
+function validatePixels(input) {
+    if (!(input.pixels instanceof Uint8Array || input.pixels instanceof Uint8ClampedArray) || !Number.isSafeInteger(input.width) || !Number.isSafeInteger(input.height) || input.width <= 0 || input.height <= 0 || input.width * input.height > MAX_PIXELS || input.pixels.length !== input.width * input.height * 4)
+        throw new RangeError("ASCII pixels must be a bounded, complete RGBA8 image");
+    if (input.origin !== undefined && input.origin !== "top-left" && input.origin !== "bottom-left")
+        throw new RangeError("Invalid pixel origin");
+}
+function restoreAttribute(element, name, value) { if (value === null)
+    element.removeAttribute(name);
+else
+    element.setAttribute(name, value); }
+//# sourceMappingURL=AsciiOutput.js.map

package/dist/effects/AsciiOutput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsciiOutput.js","sourceRoot":"","sources":["../../src/effects/AsciiOutput.ts"],"names":[],"mappings":"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"}

package/dist/effects/OutlineOutput.d.ts

@@ -0,0 +1,58 @@
+import { type CameraLike, type RenderItem, type Renderer } from "@aura3d/rendering";
+export interface OutlineOutputOptions {
+    /** Normal extrusion distance in the object's local units. */
+    readonly width?: number;
+    readonly color?: readonly [number, number, number] | readonly [number, number, number, number];
+    readonly opacity?: number;
+    /**
+     * The default rejects alpha cutouts, alpha-to-coverage, textured or vertex/
+     * instance alpha on blended materials, unknown shaders or variants, custom
+     * instance attributes, and scissor/stencil/color-write masks. An untextured
+     * hull cannot reproduce these silhouettes. "geometry" explicitly opts into
+     * that approximation (including unknown shader deformation and masks).
+     * Uniform base-color alpha of blended materials is multiplied by outline
+     * opacity in either mode. Opaque materials ignore their base-color alpha.
+     */
+    readonly alphaMode?: "strict" | "geometry";
+    readonly maxVertices?: number;
+    readonly maxIndices?: number;
+    readonly maxItems?: number;
+}
+/**
+ * Inverted-hull, object-space outlines for triangle RenderItems. Each call to
+ * items() snapshots positions and normals, expanding them in local space and
+ * making a front-face-culled unlit shell. Submit both the original items and
+ * the shells (or call render()). Width changes with object transform and
+ * perspective; this is not a constant-pixel screen-space outline.
+ *
+ * Static and instanced geometry is supported. Skinning and morphing are
+ * rejected because CPU snapshots cannot follow GPU deformations. The caller
+ * owns the source geometry/materials; the output owns its generated buffers
+ * and materials, replacing them on the next items() call or dispose().
+ */
+export declare class OutlineOutput {
+    private readonly width;
+    private readonly color;
+    private readonly opacity;
+    private readonly alphaMode;
+    private readonly maxVertices;
+    private readonly maxIndices;
+    private readonly maxItems;
+    private owned;
+    private readonly retiring;
+    private readonly disposalInFlight;
+    private disposed;
+    private building;
+    constructor(options?: OutlineOutputOptions);
+    /** Returned shell resources stay live until the next items() call or disposal. */
+    items(source: Iterable<RenderItem>): readonly RenderItem[];
+    private buildItems;
+    /** Render the source and its shells in a single ordinary renderer frame. */
+    render(renderer: Pick<Renderer, "render">, source: Iterable<RenderItem>, camera?: CameraLike): ReturnType<Renderer["render"]>;
+    dispose(): void;
+    private retireOwned;
+    private cleanupRetired;
+    private cleanupAfterFailure;
+    private assertAlive;
+}
+//# sourceMappingURL=OutlineOutput.d.ts.map

package/dist/effects/OutlineOutput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OutlineOutput.d.ts","sourceRoot":"","sources":["../../src/effects/OutlineOutput.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,UAAU,EAAyB,KAAK,UAAU,EAAE,KAAK,QAAQ,EACvE,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAcD;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4C;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsD;IAC/E,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsD;IACvF,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,GAAE,oBAAyB;IAkB9C,kFAAkF;IAClF,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,SAAS,UAAU,EAAE;IAW1D,OAAO,CAAC,UAAU;IAqFlB,4EAA4E;IAC5E,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAU7H,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,WAAW;CACpB"}

package/dist/effects/OutlineOutput.js

@@ -0,0 +1,274 @@
+import { DEFAULT_INSTANCED_PBR_SHADER_NAME, DEFAULT_INSTANCED_UNLIT_SHADER_NAME, DEFAULT_NORMAL_MAPPED_PBR_SHADER_NAME, DEFAULT_PBR_SHADER_NAME, DEFAULT_TEXTURED_PBR_SHADER_NAME, DEFAULT_TEXTURED_UNLIT_SHADER_NAME, DEFAULT_UNLIT_SHADER_NAME, Geometry, IndexBuffer, UnlitMaterial, VertexBuffer, VertexFormat, isTextureBinding } from "@aura3d/rendering";
+// These built-in shaders expose the standard base color/alpha contract. An
+// arbitrary shader may discard fragments or deform vertices without declaring
+// either through the material's ordinary alpha parameters.
+const KNOWN_OUTLINE_SHADERS = new Set([
+    DEFAULT_UNLIT_SHADER_NAME, DEFAULT_PBR_SHADER_NAME,
+    DEFAULT_INSTANCED_UNLIT_SHADER_NAME, DEFAULT_INSTANCED_PBR_SHADER_NAME,
+    DEFAULT_TEXTURED_UNLIT_SHADER_NAME, DEFAULT_TEXTURED_PBR_SHADER_NAME,
+    DEFAULT_NORMAL_MAPPED_PBR_SHADER_NAME
+]);
+/**
+ * Inverted-hull, object-space outlines for triangle RenderItems. Each call to
+ * items() snapshots positions and normals, expanding them in local space and
+ * making a front-face-culled unlit shell. Submit both the original items and
+ * the shells (or call render()). Width changes with object transform and
+ * perspective; this is not a constant-pixel screen-space outline.
+ *
+ * Static and instanced geometry is supported. Skinning and morphing are
+ * rejected because CPU snapshots cannot follow GPU deformations. The caller
+ * owns the source geometry/materials; the output owns its generated buffers
+ * and materials, replacing them on the next items() call or dispose().
+ */
+export class OutlineOutput {
+    width;
+    color;
+    opacity;
+    alphaMode;
+    maxVertices;
+    maxIndices;
+    maxItems;
+    owned = [];
+    retiring = new Set();
+    disposalInFlight = new Set();
+    disposed = false;
+    building = false;
+    constructor(options = {}) {
+        this.width = options.width ?? 0.03;
+        this.opacity = options.opacity ?? 1;
+        this.alphaMode = options.alphaMode ?? "strict";
+        this.maxVertices = options.maxVertices ?? 1_000_000;
+        this.maxIndices = options.maxIndices ?? 3_000_000;
+        this.maxItems = options.maxItems ?? 16_384;
+        const color = options.color ?? [0, 0, 0, 1];
+        if (!Number.isFinite(this.width) || this.width < 0)
+            throw new RangeError("Outline width must be finite and non-negative");
+        if (!Number.isFinite(this.opacity) || this.opacity < 0 || this.opacity > 1)
+            throw new RangeError("Outline opacity must be in [0, 1]");
+        if (color.length < 3 || color.length > 4 || color.some((value) => !Number.isFinite(value) || value < 0 || value > 1))
+            throw new RangeError("Outline color must contain three or four values in [0, 1]");
+        if (this.alphaMode !== "strict" && this.alphaMode !== "geometry")
+            throw new RangeError("Invalid outline alphaMode");
+        if (!Number.isSafeInteger(this.maxVertices) || this.maxVertices < 1 || this.maxVertices > 1_000_000)
+            throw new RangeError("Outline maxVertices must be in [1, 1000000]");
+        if (!Number.isSafeInteger(this.maxIndices) || this.maxIndices < 1 || this.maxIndices > 3_000_000)
+            throw new RangeError("Outline maxIndices must be in [1, 3000000]");
+        if (!Number.isSafeInteger(this.maxItems) || this.maxItems < 1 || this.maxItems > 16_384)
+            throw new RangeError("Outline maxItems must be in [1, 16384]");
+        this.color = [color[0], color[1], color[2], color[3] ?? 1];
+    }
+    /** Returned shell resources stay live until the next items() call or disposal. */
+    items(source) {
+        this.assertAlive();
+        if (this.building)
+            throw new Error("Outline output is already building items");
+        this.building = true;
+        try {
+            return this.buildItems(source);
+        }
+        finally {
+            this.building = false;
+        }
+    }
+    buildItems(source) {
+        this.cleanupRetired();
+        const allocated = [];
+        const result = [];
+        let count = 0;
+        let indices = 0;
+        let itemCount = 0;
+        try {
+            for (const item of source) {
+                this.assertAlive();
+                itemCount += 1;
+                if (itemCount > this.maxItems)
+                    throw new RangeError("Outline item budget exceeded");
+                const alpha = materialAlpha(item, this.alphaMode) * this.opacity * this.color[3];
+                if (alpha === 0 || this.width === 0)
+                    continue;
+                const geometry = item.geometry;
+                if (geometry.topology !== "triangles")
+                    throw new Error("Object-space outlines require triangle geometry");
+                if (item.skinning || (item.morphTargets?.length ?? 0) > 0 || (item.morphWeights?.length ?? 0) > 0 || (geometry.morphTargets?.length ?? 0) > 0)
+                    throw new Error("Object-space outlines do not support skinned or morphed geometry");
+                const vertices = geometry.vertexBuffer;
+                if (!vertices.format.hasAttribute("normal"))
+                    throw new Error("Object-space outlines require vertex normals");
+                const normalSlot = vertices.format.getAttribute("normal").bufferSlot;
+                if (vertices.format.streams.find((stream) => stream.slot === normalSlot)?.stepMode !== "vertex") {
+                    throw new Error("Object-space outlines require per-vertex normals");
+                }
+                const positions = geometry.getAttributeBuffer("position");
+                const normals = geometry.getAttributeBuffer("normal");
+                count += vertices.vertexCount;
+                if (count > this.maxVertices)
+                    throw new RangeError("Outline vertex budget exceeded");
+                indices += geometry.indexBuffer?.count ?? 0;
+                if (indices > this.maxIndices)
+                    throw new RangeError("Outline index budget exceeded");
+                const expanded = new VertexBuffer(VertexFormat.P3, vertices.vertexCount);
+                let shell;
+                let material;
+                try {
+                    for (let index = 0; index < vertices.vertexCount; index += 1) {
+                        const position = positions.getDecodedAttribute(index, "position");
+                        const normal = normals.getDecodedAttribute(index, "normal");
+                        const length = Math.hypot(normal[0], normal[1], normal[2]);
+                        if (!Number.isFinite(length) || length < 1e-12)
+                            throw new Error(`Outline vertex ${index} has a zero or non-finite normal`);
+                        expanded.setAttribute(index, "position", [position[0] + this.width * normal[0] / length, position[1] + this.width * normal[1] / length, position[2] + this.width * normal[2] / length]);
+                    }
+                    shell = new Geometry(expanded, geometry.indexBuffer ? new IndexBuffer(geometry.indexBuffer.data, vertices.vertexCount) : null);
+                    shell.drawRange = geometry.drawRange;
+                    shell.groups = geometry.groups;
+                    material = new UnlitMaterial({ color: [this.color[0], this.color[1], this.color[2], alpha], renderState: { cullMode: "front", depthTest: true, depthWrite: alpha >= 1, blend: alpha < 1 } });
+                    allocated.push({ geometry: shell, material });
+                }
+                catch (error) {
+                    this.retiring.add(shell ?? expanded);
+                    if (material)
+                        this.retiring.add(material);
+                    throw this.cleanupAfterFailure(error);
+                }
+                result.push({
+                    geometry: shell,
+                    material,
+                    label: item.label ? `${item.label}:outline` : "outline",
+                    drawRange: item.drawRange,
+                    modelMatrix: item.modelMatrix,
+                    geometryMatrix: item.geometryMatrix,
+                    modelViewProjectionMatrix: item.modelViewProjectionMatrix,
+                    instanceTransforms: item.instanceTransforms,
+                    renderOrder: item.renderOrder,
+                    layerMask: item.layerMask,
+                    frustumCulled: item.frustumCulled,
+                    castShadow: false,
+                    receiveShadow: false,
+                    includeInAutoFrame: false
+                });
+            }
+            this.assertAlive();
+        }
+        catch (error) {
+            this.retireOwned(allocated);
+            throw this.cleanupAfterFailure(error);
+        }
+        this.retireOwned(this.owned);
+        this.owned = [];
+        try {
+            this.cleanupRetired();
+            this.assertAlive();
+        }
+        catch (error) {
+            this.retireOwned(allocated);
+            throw this.cleanupAfterFailure(error);
+        }
+        this.owned = allocated;
+        return result;
+    }
+    /** Render the source and its shells in a single ordinary renderer frame. */
+    render(renderer, source, camera) {
+        this.assertAlive();
+        const originals = [];
+        for (const item of source) {
+            if (originals.length >= this.maxItems)
+                throw new RangeError("Outline item budget exceeded");
+            originals.push(item);
+        }
+        return renderer.render([...originals, ...this.items(originals)], camera);
+    }
+    dispose() {
+        if (!this.disposed) {
+            this.disposed = true;
+            this.retireOwned(this.owned);
+            this.owned = [];
+        }
+        this.cleanupRetired();
+    }
+    retireOwned(items) {
+        for (const item of items) {
+            this.retiring.add(item.geometry);
+            this.retiring.add(item.material);
+        }
+    }
+    cleanupRetired() {
+        const errors = [];
+        for (const resource of [...this.retiring]) {
+            if (this.disposalInFlight.has(resource))
+                continue;
+            this.disposalInFlight.add(resource);
+            try {
+                if (!resource.disposed)
+                    resource.dispose();
+                if (!resource.disposed)
+                    throw new Error("Outline resource disposal did not complete");
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            finally {
+                if (resource.disposed)
+                    this.retiring.delete(resource);
+                this.disposalInFlight.delete(resource);
+            }
+        }
+        if (errors.length)
+            throw new AggregateError(errors, "Outline resource cleanup failed");
+    }
+    cleanupAfterFailure(error) {
+        try {
+            this.cleanupRetired();
+            return error;
+        }
+        catch (cleanup) {
+            return new AggregateError([error, cleanup], "Outline operation and cleanup failed");
+        }
+    }
+    assertAlive() { if (this.disposed)
+        throw new Error("Outline output is disposed"); }
+}
+function materialAlpha(item, mode) {
+    if (mode === "strict" && item.instanceAttributes?.length) {
+        throw new Error("Outline cannot reproduce source scissor, stencil, color-write masks or custom instance attributes; use alphaMode: geometry for an approximate silhouette");
+    }
+    const material = item.material;
+    if (!material)
+        return 1;
+    // Package consumers may provide a MaterialInstance from another copy of the
+    // rendering package, where a local instanceof check would not recognize it.
+    const base = "baseMaterial" in material ? material.baseMaterial : material;
+    if (base.disposed)
+        throw new Error("Cannot outline a disposed material");
+    if (mode === "strict" && (!KNOWN_OUTLINE_SHADERS.has(base.shaderKey) || base.shaderVariant !== undefined)) {
+        throw new Error("Outline cannot determine custom shader alpha or deformation; use alphaMode: geometry for an approximate silhouette");
+    }
+    const state = base.renderState;
+    if (mode === "strict" && (state.scissor || state.stencil || state.colorWrite.some((enabled) => !enabled))) {
+        throw new Error("Outline cannot reproduce source scissor, stencil, color-write masks or custom instance attributes; use alphaMode: geometry for an approximate silhouette");
+    }
+    const cutoff = material.getParameter("u_alphaCutoff");
+    if (typeof cutoff === "number" && (!Number.isFinite(cutoff) || cutoff < 0 || cutoff > 1))
+        throw new RangeError("Source material alpha cutoff must be in [0, 1]");
+    // Named blendMode has precedence over the legacy blend boolean.
+    const isBlend = state.blendMode === undefined ? state.blend : state.blendMode !== "opaque";
+    const binding = material.getParameter("u_baseColorTexture");
+    // Some generated shader paths sample a bound map regardless of the legacy
+    // texture-enabled uniform, so a present map must be treated conservatively.
+    const texturedAlpha = isBlend && isTextureBinding(binding) && binding.texture !== null;
+    const format = item.geometry.vertexBuffer.format;
+    const vertexAlpha = isBlend && base.requiredAttributes.includes("a_color") && format.hasAttribute("color") && format.getAttribute("color").components === 4;
+    const instanceAlpha = isBlend && item.instanceTransforms !== undefined && item.instanceColors !== undefined;
+    if (mode === "strict" && ((typeof cutoff === "number" && cutoff > 0) || state.alphaToCoverage || texturedAlpha || vertexAlpha || instanceAlpha)) {
+        throw new Error("Outline alpha cutouts, coverage, or per-pixel/instance alpha require alphaMode: geometry for an approximate silhouette");
+    }
+    const factor = material.getParameter("u_baseColor");
+    if (!isBlend || !(Array.isArray(factor) || ArrayBuffer.isView(factor)))
+        return 1;
+    if (factor.length !== 4)
+        throw new RangeError("Source material base color must contain four channels");
+    const alpha = factor[3];
+    if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1)
+        throw new RangeError("Source material alpha must be in [0, 1]");
+    return alpha;
+}
+//# sourceMappingURL=OutlineOutput.js.map