@codexo/exojs 0.9.0 → 0.10.0

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

@@ -0,0 +1,114 @@
+import type { RenderTexture } from '@/rendering/texture/RenderTexture';
+import type { SamplerOptions } from '@/rendering/texture/Sampler';
+import type { Texture } from '@/rendering/texture/Texture';
+import { BlendModes } from '@/rendering/types';
+import type { ShaderSource } from './ShaderSource';
+/**
+ * Value accepted by a material uniform. 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 drawable's
+ * own `texture`.
+ */
+export type UniformValue = number | readonly [number, number] | readonly [number, number, number] | readonly [number, number, number, number] | Float32Array | Int32Array | Texture | RenderTexture;
+/**
+ * Construction options shared by every {@link Material}.
+ *
+ * Only `shader` is required. Textures may be supplied either through the
+ * dedicated `textures` map or as texture-valued entries in `uniforms`;
+ * both are honoured by the bind-key derivation.
+ */
+export interface MaterialOptions {
+    /** GLSL/WGSL source pair backing this material. */
+    readonly shader: ShaderSource;
+    /** Initial uniform values; mutate per frame via {@link Material.uniforms}. */
+    readonly uniforms?: Record<string, UniformValue>;
+    /** Named texture bindings claimed in addition to the drawable's own texture. */
+    readonly textures?: Record<string, Texture | RenderTexture>;
+    /** Compositing blend mode; defaults to {@link BlendModes.Normal}. */
+    readonly blendMode?: BlendModes;
+    /**
+     * Backend-agnostic sampling state descriptor, or `null` to inherit the
+     * backend/texture default. Defaults to `null`.
+     */
+    readonly sampler?: SamplerOptions | null;
+}
+/**
+ * Describes the look of a renderable — shader, uniforms, textures, blend
+ * mode, and sampling state — independent of its geometry.
+ *
+ * A `Material` can be shared across many drawables; renderers cache
+ * compiled programs/pipelines keyed on {@link pipelineKey} and reuse
+ * bindings keyed on {@link bindKey}. Subclasses fix the {@link target}
+ * drawable class. Call {@link destroy} when the material is no longer
+ * needed to release the GPU resources cached on every backend it was used
+ * on.
+ *
+ * Both keys are derived live from the current material state, so they stay
+ * stable across repeated reads and change exactly when the relevant state
+ * changes — even when {@link uniforms}, {@link textures}, {@link blendMode},
+ * or {@link sampler} are mutated in place.
+ * @advanced
+ */
+export declare abstract class Material {
+    /** GLSL/WGSL source pair backing this material. */
+    readonly shader: ShaderSource;
+    /**
+     * Mutable user uniform values. Mutate between frames to drive animated
+     * effects; the renderer reads from this map every draw.
+     *
+     *   material.uniforms.u_time = performance.now() / 1000;
+     *   material.uniforms.u_color = [1, 0.5, 0, 1];
+     */
+    uniforms: Record<string, UniformValue>;
+    /** Named texture bindings claimed in addition to the drawable's own texture. */
+    textures: Record<string, Texture | RenderTexture>;
+    /** Compositing blend mode applied when drawing with this material. */
+    blendMode: BlendModes;
+    /** Backend-agnostic sampling state descriptor, or `null` for the default. */
+    sampler: SamplerOptions | null;
+    /** Which drawable class this material can serve; renderers check compatibility. */
+    abstract readonly target: 'mesh' | 'sprite';
+    private readonly _id;
+    private readonly _disposeCallbacks;
+    protected constructor(options: MaterialOptions);
+    /**
+     * Stable pipeline key: identical ⇒ same GPU pipeline/program can be used.
+     * Derived from shader identity, blend mode, and sampler state, and is
+     * independent of the owning material instance so identically configured
+     * materials share a pipeline. Drives grouping and the pipeline cache.
+     */
+    get pipelineKey(): number;
+    /**
+     * Stable bind key: identical ⇒ same bindings (textures unchanged). Derived
+     * from this material's identity and the identities of its bound textures.
+     * Changes when a texture is swapped; drives bind-group/slot reuse.
+     */
+    get bindKey(): number;
+    /**
+     * Set a uniform value. Equivalent to `material.uniforms[name] = value`,
+     * returned `this` for chaining.
+     */
+    setUniform(name: string, value: UniformValue): this;
+    /**
+     * Bind a named texture. Equivalent to `material.textures[name] = texture`,
+     * returned `this` for chaining.
+     */
+    setTexture(name: string, texture: Texture | RenderTexture): this;
+    /**
+     * Release GPU resources cached against this material on every backend
+     * that has compiled it. Safe to call multiple times. After destroy, the
+     * material can still be re-used — renderers recompile on next draw — but
+     * typical usage is to drop the reference.
+     */
+    destroy(): void;
+    /**
+     * Internal hook for renderers to register a per-material-instance cleanup
+     * callback (release compiled program, pipeline, or bind groups). The
+     * callback fires on {@link destroy}; renderers MUST also tolerate the
+     * material being garbage-collected without destroy ever being called.
+     *
+     * @internal
+     */
+    _onDispose(callback: () => void): void;
+}

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

@@ -0,0 +1,111 @@
+import { BlendModes } from '../types.js';
+import { derivePipelineKey, deriveBindKey } from './MaterialKey.js';
+
+let nextMaterialId = 1;
+/**
+ * Describes the look of a renderable — shader, uniforms, textures, blend
+ * mode, and sampling state — independent of its geometry.
+ *
+ * A `Material` can be shared across many drawables; renderers cache
+ * compiled programs/pipelines keyed on {@link pipelineKey} and reuse
+ * bindings keyed on {@link bindKey}. Subclasses fix the {@link target}
+ * drawable class. Call {@link destroy} when the material is no longer
+ * needed to release the GPU resources cached on every backend it was used
+ * on.
+ *
+ * Both keys are derived live from the current material state, so they stay
+ * stable across repeated reads and change exactly when the relevant state
+ * changes — even when {@link uniforms}, {@link textures}, {@link blendMode},
+ * or {@link sampler} are mutated in place.
+ * @advanced
+ */
+class Material {
+    /** GLSL/WGSL source pair backing this material. */
+    shader;
+    /**
+     * Mutable user uniform values. Mutate between frames to drive animated
+     * effects; the renderer reads from this map every draw.
+     *
+     *   material.uniforms.u_time = performance.now() / 1000;
+     *   material.uniforms.u_color = [1, 0.5, 0, 1];
+     */
+    uniforms;
+    /** Named texture bindings claimed in addition to the drawable's own texture. */
+    textures;
+    /** Compositing blend mode applied when drawing with this material. */
+    blendMode;
+    /** Backend-agnostic sampling state descriptor, or `null` for the default. */
+    sampler;
+    _id;
+    _disposeCallbacks = new Set();
+    constructor(options) {
+        if (options.shader === undefined || options.shader === null) {
+            throw new Error('Material requires a `shader` ShaderSource.');
+        }
+        this.shader = options.shader;
+        this.uniforms = { ...(options.uniforms ?? {}) };
+        this.textures = { ...(options.textures ?? {}) };
+        this.blendMode = options.blendMode ?? BlendModes.Normal;
+        this.sampler = options.sampler ?? null;
+        this._id = nextMaterialId++;
+    }
+    /**
+     * Stable pipeline key: identical ⇒ same GPU pipeline/program can be used.
+     * Derived from shader identity, blend mode, and sampler state, and is
+     * independent of the owning material instance so identically configured
+     * materials share a pipeline. Drives grouping and the pipeline cache.
+     */
+    get pipelineKey() {
+        return derivePipelineKey(this.shader.id, this.blendMode, this.sampler);
+    }
+    /**
+     * Stable bind key: identical ⇒ same bindings (textures unchanged). Derived
+     * from this material's identity and the identities of its bound textures.
+     * Changes when a texture is swapped; drives bind-group/slot reuse.
+     */
+    get bindKey() {
+        return deriveBindKey(this._id, this.uniforms, this.textures);
+    }
+    /**
+     * Set a uniform value. Equivalent to `material.uniforms[name] = value`,
+     * returned `this` for chaining.
+     */
+    setUniform(name, value) {
+        this.uniforms[name] = value;
+        return this;
+    }
+    /**
+     * Bind a named texture. Equivalent to `material.textures[name] = texture`,
+     * returned `this` for chaining.
+     */
+    setTexture(name, texture) {
+        this.textures[name] = texture;
+        return this;
+    }
+    /**
+     * Release GPU resources cached against this material on every backend
+     * that has compiled it. Safe to call multiple times. After destroy, the
+     * material can still be re-used — renderers 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-material-instance cleanup
+     * callback (release compiled program, pipeline, or bind groups). The
+     * callback fires on {@link destroy}; renderers MUST also tolerate the
+     * material being garbage-collected without destroy ever being called.
+     *
+     * @internal
+     */
+    _onDispose(callback) {
+        this._disposeCallbacks.add(callback);
+    }
+}
+
+export { Material };
+//# sourceMappingURL=Material.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Material.js","sources":["../../../../../src/rendering/material/Material.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAoDA,IAAI,cAAc,GAAG,CAAC;AAEtB;;;;;;;;;;;;;;;;AAgBG;MACmB,QAAQ,CAAA;;AAEZ,IAAA,MAAM;AAEtB;;;;;;AAMG;AACI,IAAA,QAAQ;;AAGR,IAAA,QAAQ;;AAGR,IAAA,SAAS;;AAGT,IAAA,OAAO;AAKG,IAAA,GAAG;AACH,IAAA,iBAAiB,GAAG,IAAI,GAAG,EAAc;AAE1D,IAAA,WAAA,CAAsB,OAAwB,EAAA;AAC5C,QAAA,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE;AAC3D,YAAA,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC;QAC/D;AAEA,QAAA,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM;AAC5B,QAAA,IAAI,CAAC,QAAQ,GAAG,EAAE,IAAI,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE;AAC/C,QAAA,IAAI,CAAC,QAAQ,GAAG,EAAE,IAAI,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE;QAC/C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,MAAM;QACvD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI;AACtC,QAAA,IAAI,CAAC,GAAG,GAAG,cAAc,EAAE;IAC7B;AAEA;;;;;AAKG;AACH,IAAA,IAAW,WAAW,GAAA;AACpB,QAAA,OAAO,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC;IACxE;AAEA;;;;AAIG;AACH,IAAA,IAAW,OAAO,GAAA;AAChB,QAAA,OAAO,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC;IAC9D;AAEA;;;AAGG;IACI,UAAU,CAAC,IAAY,EAAE,KAAmB,EAAA;AACjD,QAAA,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK;AAE3B,QAAA,OAAO,IAAI;IACb;AAEA;;;AAGG;IACI,UAAU,CAAC,IAAY,EAAE,OAAgC,EAAA;AAC9D,QAAA,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO;AAE7B,QAAA,OAAO,IAAI;IACb;AAEA;;;;;AAKG;IACI,OAAO,GAAA;AACZ,QAAA,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,iBAAiB,EAAE;AAC7C,YAAA,QAAQ,EAAE;QACZ;AAEA,QAAA,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE;IAChC;AAEA;;;;;;;AAOG;AACI,IAAA,UAAU,CAAC,QAAoB,EAAA;AACpC,QAAA,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC;IACtC;AACD;;;;"}

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

@@ -0,0 +1,18 @@
+import type { RenderTexture } from '@/rendering/texture/RenderTexture';
+import type { SamplerOptions } from '@/rendering/texture/Sampler';
+import type { Texture } from '@/rendering/texture/Texture';
+import type { BlendModes } from '@/rendering/types';
+import type { UniformValue } from './Material';
+/**
+ * Pipeline key from shader identity, blend mode, and sampler state.
+ * @internal
+ */
+export declare const derivePipelineKey: (shaderId: number, blendMode: BlendModes, sampler: SamplerOptions | null) => number;
+/**
+ * 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
+ */
+export declare const deriveBindKey: (materialId: number, uniforms: Record<string, UniformValue>, textures: Record<string, Texture | RenderTexture>) => number;

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
  *
@@ -109,15 +100,7 @@ export interface MeshShaderOptions {
  *   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;
@@ -125,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
@@ -142,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>;
@@ -165,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;
 }