@codexo/exojs 0.8.4 → 0.10.0

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

@@ -0,0 +1,82 @@
+/**
+ * @internal
+ *
+ * Stable key derivation for {@link Material}. Keys are interned from a
+ * normalized string descriptor, so identical material state always maps to
+ * the exact same integer (no hashing, no collisions), and distinct state
+ * maps to distinct integers. Descriptors are built from scalar fields in a
+ * fixed order and from sorted texture-binding entries — never from
+ * `JSON.stringify` over objects with unstable key order.
+ *
+ * Two key spaces:
+ * - {@link derivePipelineKey}: shader identity + blend + sampler state.
+ *   Drives GPU pipeline/program reuse and material grouping. Independent of
+ *   the owning material instance, so identically configured materials share
+ *   a pipeline key.
+ * - {@link deriveBindKey}: material identity + bound texture identities.
+ *   Drives bind-group/slot reuse; changes when a material swaps a texture.
+ */
+const textureIds = new WeakMap();
+let nextTextureId = 1;
+const getTextureId = (texture) => {
+    const cached = textureIds.get(texture);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const id = nextTextureId++;
+    textureIds.set(texture, id);
+    return id;
+};
+const pipelineKeyRegistry = new Map();
+let nextPipelineKey = 1;
+const bindKeyRegistry = new Map();
+let nextBindKey = 1;
+const intern = (registry, descriptor, allocate) => {
+    const cached = registry.get(descriptor);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const key = allocate();
+    registry.set(descriptor, key);
+    return key;
+};
+const samplerDescriptor = (sampler) => {
+    if (sampler === null) {
+        return '-';
+    }
+    return [sampler.scaleMode, sampler.wrapMode, sampler.premultiplyAlpha ? 1 : 0, sampler.generateMipMap ? 1 : 0, sampler.flipY ? 1 : 0].join(':');
+};
+const isTextureBinding = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) && !ArrayBuffer.isView(value);
+/**
+ * Pipeline key from shader identity, blend mode, and sampler state.
+ * @internal
+ */
+const derivePipelineKey = (shaderId, blendMode, sampler) => {
+    const descriptor = `${shaderId}|${blendMode}|${samplerDescriptor(sampler)}`;
+    return intern(pipelineKeyRegistry, descriptor, () => nextPipelineKey++);
+};
+/**
+ * Bind key from material identity and the identities of every bound
+ * texture, whether declared in the `textures` map or carried as a
+ * texture-valued uniform. Texture entries are sorted before joining so the
+ * descriptor is independent of insertion order.
+ * @internal
+ */
+const deriveBindKey = (materialId, uniforms, textures) => {
+    const entries = [];
+    for (const name of Object.keys(textures)) {
+        entries.push(`t:${name}=${getTextureId(textures[name])}`);
+    }
+    for (const name of Object.keys(uniforms)) {
+        const value = uniforms[name];
+        if (isTextureBinding(value)) {
+            entries.push(`u:${name}=${getTextureId(value)}`);
+        }
+    }
+    entries.sort();
+    const descriptor = `${materialId}|${entries.join(',')}`;
+    return intern(bindKeyRegistry, descriptor, () => nextBindKey++);
+};
+
+export { deriveBindKey, derivePipelineKey };
+//# sourceMappingURL=MaterialKey.js.map

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

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

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

@@ -0,0 +1,16 @@
+import type { MaterialOptions } from './Material';
+import { Material } from './Material';
+/**
+ * Material specialization for {@link Mesh} drawables.
+ *
+ * Carries the mesh contract conceptually: fixed vertex attribute locations
+ * (0 = position, 1 = texcoord, 2 = color), the auto-bound uniforms
+ * `u_projection`/`u_translation`/`u_tint`/`u_texture`, and the WGSL
+ * group(0)=mesh-uniforms / group(1)=texture / group(2)=user binding scheme.
+ * Renderer wiring is added in a later phase.
+ * @advanced
+ */
+export declare class MeshMaterial extends Material {
+    readonly target = "mesh";
+    constructor(options: MaterialOptions);
+}

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

@@ -0,0 +1,21 @@
+import { Material } from './Material.js';
+
+/**
+ * Material specialization for {@link Mesh} drawables.
+ *
+ * Carries the mesh contract conceptually: fixed vertex attribute locations
+ * (0 = position, 1 = texcoord, 2 = color), the auto-bound uniforms
+ * `u_projection`/`u_translation`/`u_tint`/`u_texture`, and the WGSL
+ * group(0)=mesh-uniforms / group(1)=texture / group(2)=user binding scheme.
+ * Renderer wiring is added in a later phase.
+ * @advanced
+ */
+class MeshMaterial extends Material {
+    target = 'mesh';
+    constructor(options) {
+        super(options);
+    }
+}
+
+export { MeshMaterial };
+//# sourceMappingURL=MeshMaterial.js.map

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

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

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

@@ -1,22 +1,12 @@
-import type { RenderTexture } from '@/rendering/texture/RenderTexture';
-import type { Texture } from '@/rendering/texture/Texture';
 /**
- * Uniform value passed to a custom mesh shader. Scalars and small tuples
- * auto-marshal to the appropriate `Float32Array`/`Int32Array` for the
- * backend's uniform call. `Texture`/`RenderTexture` values are bound to
- * texture slots starting at slot 1 — slot 0 is reserved for the mesh's
- * own `texture`.
- */
-export type MeshShaderUniformValue = number | readonly [number, number] | readonly [number, number, number] | readonly [number, number, number, number] | Float32Array | Int32Array | Texture | RenderTexture;
-/**
- * Construction options for {@link MeshShader}.
+ * Construction options for {@link ShaderSource}.
  *
  * At least one language must be supplied. Provide `glsl` for WebGL2,
- * `wgsl` for WebGPU, or both for backend-portable meshes. The shader
+ * `wgsl` for WebGPU, or both for backend-portable materials. The source
  * is compiled lazily on first use against the active backend; an
  * unsupported backend at draw time throws with a clear error.
  */
-export interface MeshShaderOptions {
+export interface ShaderSourceOptions {
     /**
      * GLSL ES 3.00 sources for the WebGL2 backend. Both `vertex` and
      * `fragment` are required when `glsl` is supplied.
@@ -30,21 +20,21 @@ export interface MeshShaderOptions {
      * points live in the same source file (WGSL convention).
      */
     readonly wgsl?: string;
-    /** Initial uniform values; mutate per frame via {@link MeshShader.uniforms}. */
-    readonly uniforms?: Record<string, MeshShaderUniformValue>;
 }
 /**
- * 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)
  *
@@ -66,16 +56,16 @@ export interface MeshShaderOptions {
  *
  * # 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
  * ```
  *
@@ -96,8 +86,9 @@ export interface MeshShaderOptions {
  *
  * # 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
  *
@@ -107,16 +98,9 @@ export interface MeshShaderOptions {
  *   for the packed scalar/vector/matrix uniforms.
  * - `@group(2) @binding(N)` for each `Texture`/`RenderTexture` uniform,
  *   in declaration order, alongside its sampler at `@binding(N+1)`.
+ * @advanced
  */
-export declare 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: Record<string, MeshShaderUniformValue>;
+export declare class ShaderSource {
     /** GLSL source pair for the WebGL2 backend, or `null` if not provided. */
     readonly glsl: {
         readonly vertex: string;
@@ -124,14 +108,13 @@ export declare class MeshShader {
     } | null;
     /** WGSL source for the WebGPU backend, or `null` if not provided. */
     readonly wgsl: string | null;
-    private readonly _disposeCallbacks;
-    constructor(options: MeshShaderOptions);
+    private readonly _id;
+    constructor(options: ShaderSourceOptions);
     /**
-     * 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: string, value: MeshShaderUniformValue): void;
+    get id(): number;
     /**
      * Reflect declared uniforms from each language's source. Returns a per-
      * language map of uniform-name → declared type, parsed from the shader
@@ -141,8 +124,9 @@ export declare 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(): {
         glsl: Record<string, string>;
@@ -164,20 +148,4 @@ export declare class MeshShader {
         onlyInGlsl: readonly string[];
         onlyInWgsl: readonly string[];
     };
-    /**
-     * 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(): void;
-    /**
-     * 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: () => void): void;
 }

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
  *
@@ -72,47 +76,39 @@
  *   for the packed scalar/vector/matrix uniforms.
  * - `@group(2) @binding(N)` for each `Texture`/`RenderTexture` uniform,
  *   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-
@@ -123,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 {
@@ -163,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;
@@ -193,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, '');
@@ -227,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`). */