@codexo/exojs 0.9.0 → 0.11.0

package/dist/esm/rendering/{mesh/MeshShader.js → material/ShaderSource.js}

@@ -1,15 +1,18 @@
+let nextShaderSourceId = 1;
 /**
- * Custom shader pair attached to a {@link Mesh}.
+ * Immutable shader source pair shared by {@link Material} instances.
  *
- * One `MeshShader` instance can be shared across many meshes; renderers
- * cache compiled programs/pipelines on the instance reference. Call
- * {@link destroy} when the shader is no longer needed to release the
- * cached GPU resources on every backend the shader was used on.
+ * `ShaderSource` owns only the GLSL/WGSL text and its stable identity;
+ * it carries no uniform/texture state (that lives on the {@link Material}).
+ * One `ShaderSource` can back many materials, and renderers key their
+ * compiled program/pipeline caches on the source identity exposed via
+ * {@link id}.
  *
  * # Vertex layout
  *
- * The vertex layout is fixed and shared with the default mesh shader,
- * so custom vertex shaders MUST pin the standard attribute locations:
+ * The vertex layout for the mesh path is fixed and shared with the default
+ * mesh material, so custom vertex shaders MUST pin the standard attribute
+ * locations:
  *
  * ## GLSL (location-qualified)
  *
@@ -31,16 +34,16 @@
  *
  * # Auto-bound uniforms
  *
- * The renderer auto-binds these when the shader declares them. Declared
- * but unused is fine; absent is fine too. Both backends carry the same
- * logical uniforms, only the binding scheme differs.
+ * Renderers auto-bind these when the source declares them. Declared but
+ * unused is fine; absent is fine too. Both backends carry the same logical
+ * uniforms, only the binding scheme differs.
  *
  * ## GLSL
  *
  * ```glsl
  * uniform mat3 u_projection;   // active view's projection
- * uniform mat3 u_translation;  // mesh's global transform
- * uniform vec4 u_tint;         // mesh.tint as RGBA in 0..1
+ * uniform mat3 u_translation;  // drawable's global transform
+ * uniform vec4 u_tint;         // tint as RGBA in 0..1
  * uniform sampler2D u_texture; // bound to texture slot 0
  * ```
  *
@@ -61,8 +64,9 @@
  *
  * # User uniforms
  *
- * Anything in {@link uniforms} is set after the auto-binds. `Texture`/
- * `RenderTexture` values claim slots 1..N (slot 0 belongs to the mesh).
+ * Anything in {@link Material.uniforms} is set after the auto-binds.
+ * `Texture`/`RenderTexture` values claim slots 1..N (slot 0 belongs to the
+ * drawable's own texture).
  *
  * ## WGSL user-uniform contract
  *
@@ -74,46 +78,37 @@
  *   in declaration order, alongside its sampler at `@binding(N+1)`.
  * @advanced
  */
-class MeshShader {
-    /**
-     * Mutable user uniform values. Mutate between frames to drive animated
-     * effects; the renderer reads from this map every draw.
-     *
-     *   shader.uniforms.uTime = performance.now() / 1000;
-     *   shader.uniforms.uColor = [1, 0.5, 0, 1];
-     */
-    uniforms;
+class ShaderSource {
     /** GLSL source pair for the WebGL2 backend, or `null` if not provided. */
     glsl;
     /** WGSL source for the WebGPU backend, or `null` if not provided. */
     wgsl;
-    _disposeCallbacks = new Set();
+    _id;
     constructor(options) {
         if (options.glsl === undefined && options.wgsl === undefined) {
-            throw new Error('MeshShader requires at least one of `glsl` or `wgsl`.');
+            throw new Error('ShaderSource requires at least one of `glsl` or `wgsl`.');
         }
         if (options.glsl !== undefined) {
             if (typeof options.glsl.vertex !== 'string' || options.glsl.vertex.length === 0) {
-                throw new Error('MeshShader.glsl.vertex must be a non-empty string.');
+                throw new Error('ShaderSource.glsl.vertex must be a non-empty string.');
             }
             if (typeof options.glsl.fragment !== 'string' || options.glsl.fragment.length === 0) {
-                throw new Error('MeshShader.glsl.fragment must be a non-empty string.');
+                throw new Error('ShaderSource.glsl.fragment must be a non-empty string.');
             }
         }
         if (options.wgsl !== undefined && (typeof options.wgsl !== 'string' || options.wgsl.length === 0)) {
-            throw new Error('MeshShader.wgsl must be a non-empty string.');
+            throw new Error('ShaderSource.wgsl must be a non-empty string.');
         }
         this.glsl = options.glsl ?? null;
         this.wgsl = options.wgsl ?? null;
-        this.uniforms = { ...(options.uniforms ?? {}) };
+        this._id = nextShaderSourceId++;
     }
     /**
-     * Convenience setter equivalent to `shader.uniforms[name] = value`.
-     * Provided for symmetry with engine APIs that prefer explicit methods
-     * over property mutation.
+     * Stable per-instance identity. Identical `id` ⇒ same compiled program/
+     * pipeline can be reused. Monotonic across the session; never reused.
      */
-    setUniform(name, value) {
-        this.uniforms[name] = value;
+    get id() {
+        return this._id;
     }
     /**
      * Reflect declared uniforms from each language's source. Returns a per-
@@ -124,8 +119,9 @@ class MeshShader {
      *
      * Reflection is best-effort and intended for CI drift-checks and editor
      * tooling, not for runtime uniform binding decisions. The renderers do
-     * NOT consult this map; they bind uniforms by name from {@link uniforms}
-     * and let the underlying API resolve declared-but-unused entries.
+     * NOT consult this map; they bind uniforms by name from
+     * {@link Material.uniforms} and let the underlying API resolve declared-
+     * but-unused entries.
      */
     getDeclaredUniforms() {
         return {
@@ -164,29 +160,6 @@ class MeshShader {
         }
         return { onlyInGlsl, onlyInWgsl };
     }
-    /**
-     * Release GPU resources cached against this `MeshShader` on every
-     * backend that has compiled it. Safe to call multiple times. After
-     * destroy, the shader can still be re-used — renderers will recompile
-     * on next draw — but typical usage is to drop the reference.
-     */
-    destroy() {
-        for (const callback of this._disposeCallbacks) {
-            callback();
-        }
-        this._disposeCallbacks.clear();
-    }
-    /**
-     * Internal hook for renderers to register a per-shader-instance cleanup
-     * callback (release compiled program, pipeline, or bind groups). The
-     * callback fires on {@link destroy}; renderers MUST also tolerate the
-     * shader being garbage-collected without destroy ever being called.
-     *
-     * @internal
-     */
-    _onDispose(callback) {
-        this._disposeCallbacks.add(callback);
-    }
 }
 const autoBoundUniformNames = new Set(['u_projection', 'u_translation', 'u_tint', 'u_texture', 'u_mesh']);
 const glslUniformPattern = /\buniform\s+(?:mediump\s+|highp\s+|lowp\s+|)(\w+)\s+(\w+)[^;]*;/g;
@@ -194,7 +167,7 @@ const wgslUserUniformPattern = /@group\(\s*2\s*\)\s*@binding\(\s*\d+\s*\)\s*var(
 /**
  * Strip line and block comments from a shader source so the uniform
  * regexes don't match commented-out declarations. Conservative: works
- * for both GLSL and WGSL syntax (both use `//` and `/* ... *\/`).
+ * for both GLSL and WGSL syntax (both use `//` and block comments).
  */
 function stripComments(source) {
     return source.replaceAll(/\/\*[\s\S]*?\*\//g, '').replaceAll(/\/\/[^\n]*/g, '');
@@ -228,5 +201,5 @@ function parseWgslUniforms(source) {
     return result;
 }
 
-export { MeshShader };
-//# sourceMappingURL=MeshShader.js.map
+export { ShaderSource };
+//# sourceMappingURL=ShaderSource.js.map

package/dist/esm/rendering/material/ShaderSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShaderSource.js","sources":["../../../../../src/rendering/material/ShaderSource.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/material/SpriteMaterial.d.ts

@@ -0,0 +1,15 @@
+import type { MaterialOptions } from './Material';
+import { Material } from './Material';
+/**
+ * Material specialization for {@link Sprite} drawables.
+ *
+ * API shell for the sprite custom-material path; the renderer integration
+ * and instancing contract are added in a later phase. The base texture
+ * stays on the sprite — this material supplies the fragment program,
+ * uniforms, and additional texture bindings.
+ * @advanced
+ */
+export declare class SpriteMaterial extends Material {
+    readonly target = "sprite";
+    constructor(options: MaterialOptions);
+}

package/dist/esm/rendering/material/SpriteMaterial.js

@@ -0,0 +1,20 @@
+import { Material } from './Material.js';
+
+/**
+ * Material specialization for {@link Sprite} drawables.
+ *
+ * API shell for the sprite custom-material path; the renderer integration
+ * and instancing contract are added in a later phase. The base texture
+ * stays on the sprite — this material supplies the fragment program,
+ * uniforms, and additional texture bindings.
+ * @advanced
+ */
+class SpriteMaterial extends Material {
+    target = 'sprite';
+    constructor(options) {
+        super(options);
+    }
+}
+
+export { SpriteMaterial };
+//# sourceMappingURL=SpriteMaterial.js.map

package/dist/esm/rendering/material/SpriteMaterial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpriteMaterial.js","sources":["../../../../../src/rendering/material/SpriteMaterial.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;;;;AAQG;AACG,MAAO,cAAe,SAAQ,QAAQ,CAAA;IAC1B,MAAM,GAAG,QAAQ;AAEjC,IAAA,WAAA,CAAmB,OAAwB,EAAA;QACzC,KAAK,CAAC,OAAO,CAAC;IAChB;AACD;;;;"}

package/dist/esm/rendering/mesh/Mesh.d.ts

@@ -1,29 +1,43 @@
 import { Drawable } from '@/rendering/Drawable';
-import type { MeshShader } from '@/rendering/mesh/MeshShader';
+import type { Geometry } from '@/rendering/geometry/Geometry';
+import type { MeshMaterial } from '@/rendering/material/MeshMaterial';
 import type { RenderTexture } from '@/rendering/texture/RenderTexture';
 import type { Texture } from '@/rendering/texture/Texture';
 /**
  * Construction-time options for a {@link Mesh}.
  *
- * Vertices are required and must be a flat sequence of (x, y) pairs in
- * local space. UVs and per-vertex colors are optional but, when present,
- * must match the vertex count (UVs as (u, v) pairs, colors as one
- * packed-RGBA8 u32 per vertex). Indices are optional — if absent, the
- * vertex stream is drawn as a flat triangle list (3*N vertices = N
- * triangles). A texture is optional; a textured mesh samples it at the
- * supplied UVs while an untextured mesh paints solid vertex colors only.
+ * Provide the geometry in exactly one of two forms:
+ *
+ * - **Convenience form** — a flat `vertices` array of (x, y) pairs in local
+ *   space, with optional `uvs`, per-vertex `colors`, and `indices`. This is
+ *   the simplest path: `new Mesh({ vertices })`.
+ * - **Geometry form** — a {@link Geometry} object whose standard attributes
+ *   (`a_position`/`position`, `a_texcoord`/`texcoord`, `a_color`/`color`) are
+ *   read into the mesh: `new Mesh({ geometry })`. The geometry must use the
+ *   `triangle-list` topology.
+ *
+ * Supplying both `vertices` and `geometry`, or neither, throws.
+ *
+ * When present, `uvs` must match the vertex count (as (u, v) pairs) and
+ * `colors` must supply one packed-RGBA8 u32 per vertex. `indices` are optional
+ * — if absent, the vertex stream is drawn as a flat triangle list (3*N
+ * vertices = N triangles). A texture is optional; a textured mesh samples it
+ * at the supplied UVs while an untextured mesh paints solid vertex colors only.
  *
  * Validation is enforced at construction; any mismatch throws.
  *
- * For custom shaders, see {@link MeshShader}.
+ * For custom shaders/uniforms/textures, attach a {@link MeshMaterial}.
  */
 export interface MeshOptions {
-    readonly vertices: Float32Array;
+    readonly vertices?: Float32Array;
     readonly indices?: Uint16Array;
     readonly uvs?: Float32Array;
     readonly colors?: Uint32Array;
+    /** Interleaved geometry source; mutually exclusive with `vertices`. */
+    readonly geometry?: Geometry;
     readonly texture?: Texture | RenderTexture | null;
-    readonly shader?: MeshShader;
+    /** Custom look (shader/uniforms/textures/blendMode); `null` uses the default mesh material. */
+    readonly material?: MeshMaterial;
 }
 /**
  * Arbitrary 2D triangle-mesh primitive.
@@ -58,7 +72,10 @@ export declare class Mesh extends Drawable {
     readonly indices: Uint16Array | null;
     readonly uvs: Float32Array | null;
     readonly colors: Uint32Array | null;
-    readonly shader: MeshShader | null;
+    /** Custom material attached to this mesh, or `null` for the default mesh path. */
+    readonly material: MeshMaterial | null;
+    /** Source geometry when constructed from the geometry form, otherwise `null`. */
+    readonly geometry: Geometry | null;
     private _texture;
     constructor(options: MeshOptions);
     /** Number of (x, y) vertex pairs in the mesh (i.e. `vertices.length / 2`). */

package/dist/esm/rendering/mesh/Mesh.js

@@ -33,11 +33,40 @@ class Mesh extends Drawable {
     indices;
     uvs;
     colors;
-    shader;
+    /** Custom material attached to this mesh, or `null` for the default mesh path. */
+    material;
+    /** Source geometry when constructed from the geometry form, otherwise `null`. */
+    geometry;
     _texture;
     constructor(options) {
         super();
-        const { vertices, indices = null, uvs = null, colors = null, texture = null, shader = null } = options;
+        const { texture = null, material = null } = options;
+        let vertices;
+        let indices;
+        let uvs;
+        let colors;
+        let geometry;
+        if (options.geometry !== undefined) {
+            if (options.vertices !== undefined) {
+                throw new Error('Mesh accepts either `vertices` or `geometry`, not both.');
+            }
+            geometry = options.geometry;
+            const data = readGeometry(geometry);
+            vertices = data.vertices;
+            uvs = data.uvs;
+            colors = data.colors;
+            indices = data.indices;
+        }
+        else {
+            if (options.vertices === undefined) {
+                throw new Error('Mesh requires either `vertices` or `geometry`.');
+            }
+            geometry = null;
+            vertices = options.vertices;
+            indices = options.indices ?? null;
+            uvs = options.uvs ?? null;
+            colors = options.colors ?? null;
+        }
         if (vertices.length === 0 || vertices.length % 2 !== 0) {
             throw new Error(`Mesh vertices must be a non-empty flat array of (x,y) pairs (got length ${vertices.length}).`);
         }
@@ -68,7 +97,8 @@ class Mesh extends Drawable {
         this.indices = indices;
         this.uvs = uvs;
         this.colors = colors;
-        this.shader = shader;
+        this.material = material;
+        this.geometry = geometry;
         this._texture = texture;
         this.recomputeLocalBounds();
     }
@@ -114,6 +144,95 @@ class Mesh extends Drawable {
         return this;
     }
 }
+const positionAttributeNames = new Set(['a_position', 'position']);
+const texcoordAttributeNames = new Set(['a_texcoord', 'texcoord', 'a_uv', 'uv']);
+const colorAttributeNames = new Set(['a_color', 'color']);
+const findAttribute = (attributes, names) => attributes.find(attribute => names.has(attribute.name));
+/**
+ * Read a {@link Geometry}'s standard mesh attributes into the flat
+ * `vertices`/`uvs`/`colors` arrays the mesh renderers consume. Only the
+ * `triangle-list` topology and the canonical attribute layout (`f32` position
+ * and texcoord, `u8`/`u32`/`f32` color) are supported — this is the immediate
+ * (non-batched) bridge; shared GPU buffers and instancing arrive later.
+ */
+function readGeometry(geometry) {
+    if (geometry.topology !== 'triangle-list') {
+        throw new Error(`Mesh only supports triangle-list geometry (got "${geometry.topology}").`);
+    }
+    const position = findAttribute(geometry.attributes, positionAttributeNames);
+    if (position === undefined) {
+        throw new Error('Mesh geometry requires a position attribute named `a_position` or `position`.');
+    }
+    if (position.type !== 'f32' || position.size < 2) {
+        throw new Error('Mesh geometry position attribute must be a float vector with at least 2 components.');
+    }
+    const texcoord = findAttribute(geometry.attributes, texcoordAttributeNames);
+    if (texcoord !== undefined && (texcoord.type !== 'f32' || texcoord.size < 2)) {
+        throw new Error('Mesh geometry texcoord attribute must be a float vector with at least 2 components.');
+    }
+    const color = findAttribute(geometry.attributes, colorAttributeNames);
+    const vertexCount = geometry.vertexCount;
+    const { stride } = geometry;
+    const source = geometry.vertexData;
+    const view = source instanceof Float32Array ? new DataView(source.buffer, source.byteOffset, source.byteLength) : new DataView(source);
+    const vertices = new Float32Array(vertexCount * 2);
+    const uvs = texcoord !== undefined ? new Float32Array(vertexCount * 2) : null;
+    const colors = color !== undefined ? new Uint32Array(vertexCount) : null;
+    for (let i = 0; i < vertexCount; i++) {
+        const base = i * stride;
+        vertices[i * 2] = view.getFloat32(base + position.offset, true);
+        vertices[i * 2 + 1] = view.getFloat32(base + position.offset + 4, true);
+        if (uvs !== null && texcoord !== undefined) {
+            uvs[i * 2] = view.getFloat32(base + texcoord.offset, true);
+            uvs[i * 2 + 1] = view.getFloat32(base + texcoord.offset + 4, true);
+        }
+        if (colors !== null && color !== undefined) {
+            colors[i] = readPackedColor(view, base + color.offset, color);
+        }
+    }
+    const indices = readIndices(geometry.indices, vertexCount);
+    return { vertices, uvs, colors, indices };
+}
+/** Pack a geometry color attribute into the mesh's RGBA8 u32 representation. */
+function readPackedColor(view, offset, attribute) {
+    if (attribute.type === 'u32' && attribute.size === 1) {
+        return view.getUint32(offset, true) >>> 0;
+    }
+    if (attribute.type === 'u8' && attribute.size === 4) {
+        const r = view.getUint8(offset);
+        const g = view.getUint8(offset + 1);
+        const b = view.getUint8(offset + 2);
+        const a = view.getUint8(offset + 3);
+        return (r | (g << 8) | (b << 16) | (a << 24)) >>> 0;
+    }
+    if (attribute.type === 'f32' && attribute.size === 4) {
+        const r = Math.round(clamp01(view.getFloat32(offset, true)) * 255);
+        const g = Math.round(clamp01(view.getFloat32(offset + 4, true)) * 255);
+        const b = Math.round(clamp01(view.getFloat32(offset + 8, true)) * 255);
+        const a = Math.round(clamp01(view.getFloat32(offset + 12, true)) * 255);
+        return (r | (g << 8) | (b << 16) | (a << 24)) >>> 0;
+    }
+    throw new Error('Mesh geometry color attribute must be u8x4, u32x1, or f32x4.');
+}
+function readIndices(indices, vertexCount) {
+    if (indices === null) {
+        return null;
+    }
+    if (indices instanceof Uint16Array) {
+        return indices;
+    }
+    if (vertexCount > 0xffff) {
+        throw new Error(`Mesh geometry with ${vertexCount} vertices exceeds the 16-bit index limit.`);
+    }
+    return Uint16Array.from(indices);
+}
+function clamp01(value) {
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
 
 export { Mesh };
 //# sourceMappingURL=Mesh.js.map

package/dist/esm/rendering/mesh/Mesh.js.map

@@ -1 +1 @@
-{"version":3,"file":"Mesh.js","sources":["../../../../../src/rendering/mesh/Mesh.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"Mesh.js","sources":["../../../../../src/rendering/mesh/Mesh.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/pass/RenderPassCoordinator.d.ts

@@ -0,0 +1,63 @@
+import type { Matrix } from '@/math/Matrix';
+import type { Rectangle } from '@/math/Rectangle';
+import type { Geometry } from '../geometry/Geometry';
+import type { RenderTarget } from '../RenderTarget';
+import type { View } from '../View';
+import type { RenderPassDescriptor, RenderPassLoad } from './RenderPassDescriptor';
+/**
+ * Internal, backend-owned owner of render-pass lifecycle: target / view / clear
+ * orchestration, the scissor and stencil-clip stacks, and — on WebGPU — the
+ * active `GPURenderPassEncoder`.
+ *
+ * There is no public RenderPass API. This abstraction exists so the WebGL2 and
+ * WebGPU backends can share the orchestration shape that geometric stencil
+ * clipping needs, while each maps it onto its own state model: WebGL2 onto
+ * ambient GL state (bound framebuffer, viewport, scissor, stencil), WebGPU onto
+ * explicit render passes built up front with their attachments.
+ * @internal
+ */
+export interface RenderPassCoordinator {
+    /** The target the active pass draws into (the backend root when idle). */
+    readonly activeTarget: RenderTarget;
+    /** The view the active pass renders with. */
+    readonly activeView: View;
+    /** Whether a pass is currently open. */
+    readonly hasActivePass: boolean;
+    /** Open a pass for `descriptor`, applying its target / view / clear / stencil state. */
+    beginPass(descriptor: RenderPassDescriptor): void;
+    /** Close the active pass, flushing any pending draws into it. */
+    endPass(): void;
+    /**
+     * Run `body` inside a child pass described by `descriptor`, restoring the
+     * previous target and view afterwards — even if `body` throws. Preserves the
+     * save / restore semantics of {@link RenderTargetPass}.
+     */
+    withChildPass(descriptor: RenderPassDescriptor, body: () => void): void;
+    /** Push an axis-aligned scissor rectangle; nested rectangles intersect. */
+    pushScissorRect(bounds: Rectangle): void;
+    /** Pop the most recently pushed scissor rectangle. */
+    popScissorRect(): void;
+    /** Push a geometric stencil clip — the `shape` silhouette under `transform`. */
+    pushStencilClip(shape: Geometry, transform: Matrix): void;
+    /** Pop the most recently pushed stencil clip. */
+    popStencilClip(): void;
+    /**
+     * Decide whether `target` should be cleared or loaded given an explicit clear
+     * request. Centralizes the clear-vs-load / content-preservation decision so a
+     * render texture's contents survive across multiple passes in one frame.
+     */
+    resolveLoad(target: RenderTarget, clearRequested: boolean): RenderPassLoad;
+}
+/**
+ * Duck-typing host for backends that own a {@link RenderPassCoordinator}.
+ *
+ * Generic, `RenderBackend`-typed orchestration code ({@link RenderTargetPass},
+ * {@link RenderingContext.renderTo}) reaches the coordinator through this
+ * optional accessor and falls back to a legacy inline target/view save-restore
+ * when it is absent (e.g. test stub backends), mirroring the `_beginDrawPlan?`
+ * hook pattern used by `RenderPlanPlayer`.
+ * @internal
+ */
+export interface RenderPassCoordinatorHost {
+    readonly _passCoordinator: RenderPassCoordinator;
+}

package/dist/esm/rendering/pass/RenderPassDescriptor.d.ts

@@ -0,0 +1,48 @@
+import type { Color } from '@/core/Color';
+import type { RenderTarget } from '../RenderTarget';
+import type { View } from '../View';
+/**
+ * Whether a render pass carries a stencil attachment.
+ *
+ * WebGL2 stencil is ambient per-target GL state, so this flag is largely
+ * informational there; the WebGPU backend uses it to
+ * decide whether a pass descriptor needs a `depthStencilAttachment`.
+ * @internal
+ */
+export declare enum StencilAttachmentMode {
+    None = 0,
+    Enabled = 1
+}
+/** Load behaviour for a pass's colour attachment. @internal */
+export type RenderPassLoad = 'clear' | 'load';
+/**
+ * Backend-agnostic description of a single render pass: which target and view
+ * it draws into, whether it clears or loads its colour attachment, and whether
+ * it carries a stencil attachment.
+ *
+ * WebGL2 maps this onto ambient framebuffer / viewport / scissor / stencil
+ * state; WebGPU maps it onto a `GPURenderPassEncoder`.
+ * @internal
+ */
+export interface RenderPassDescriptor {
+    /** Target to draw into. `null` selects the backend's root (canvas) target. */
+    readonly target: RenderTarget | null;
+    /** View to render with. `null` inherits the target's current view. */
+    readonly view: View | null;
+    /** Whether the colour attachment is cleared or preserved when the pass begins. */
+    readonly load: RenderPassLoad;
+    /** Clear colour used when `load === 'clear'`. `null` keeps the backend's current clear colour. */
+    readonly clearColor: Color | null;
+    /** Whether this pass carries a stencil attachment. */
+    readonly stencil: StencilAttachmentMode;
+}
+/**
+ * Snapshot of the pass currently open on a {@link RenderPassCoordinator}. The
+ * WebGPU coordinator exposes the live encoder alongside these fields from phase
+ * 12D; the shared shape lives here so both backends agree on it.
+ * @internal
+ */
+export interface ActiveRenderPass {
+    readonly view: View;
+    readonly stencilEnabled: boolean;
+}

package/dist/esm/rendering/pass/RenderPassDescriptor.js

@@ -0,0 +1,16 @@
+/**
+ * Whether a render pass carries a stencil attachment.
+ *
+ * WebGL2 stencil is ambient per-target GL state, so this flag is largely
+ * informational there; the WebGPU backend uses it to
+ * decide whether a pass descriptor needs a `depthStencilAttachment`.
+ * @internal
+ */
+var StencilAttachmentMode;
+(function (StencilAttachmentMode) {
+    StencilAttachmentMode[StencilAttachmentMode["None"] = 0] = "None";
+    StencilAttachmentMode[StencilAttachmentMode["Enabled"] = 1] = "Enabled";
+})(StencilAttachmentMode || (StencilAttachmentMode = {}));
+
+export { StencilAttachmentMode };
+//# sourceMappingURL=RenderPassDescriptor.js.map

package/dist/esm/rendering/pass/RenderPassDescriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderPassDescriptor.js","sources":["../../../../../src/rendering/pass/RenderPassDescriptor.ts"],"sourcesContent":[null],"names":[],"mappings":"AAKA;;;;;;;AAOG;IACS;AAAZ,CAAA,UAAY,qBAAqB,EAAA;AAC/B,IAAA,qBAAA,CAAA,qBAAA,CAAA,MAAA,CAAA,GAAA,CAAA,CAAA,GAAA,MAAQ;AACR,IAAA,qBAAA,CAAA,qBAAA,CAAA,SAAA,CAAA,GAAA,CAAA,CAAA,GAAA,SAAW;AACb,CAAC,EAHW,qBAAqB,KAArB,qBAAqB,GAAA,EAAA,CAAA,CAAA;;;;"}