@codexo/exojs 0.13.0 → 0.14.0

package/dist/esm/rendering/Drawable.d.ts

@@ -1,5 +1,7 @@
 import { Color } from '#core/Color';
+import { type MaterialKey } from '#rendering/plan/RenderCommand';
 import type { RenderPlanBuilder } from '#rendering/plan/RenderPlanBuilder';
+import type { RenderBackend } from '#rendering/RenderBackend';
 import { type PixelSnapMode } from './pixelSnap';
 import { RenderNode } from './RenderNode';
 import { BlendModes } from './types';
@@ -14,6 +16,15 @@ export declare class Drawable extends RenderNode {
     private _tint;
     private _blendMode;
     private _pixelSnapMode;
+    /**
+     * Cached material key (Slice 2b). `null` until first computed or after
+     * {@link invalidateCache}. Bound to {@link _materialKeyBackend} so a backend
+     * switch (multi-app / multi-backend) recomputes rather than returning stale
+     * renderer ids. Drawables that carry their own {@link Material} bypass this
+     * cache entirely (the material can mutate its keys without notifying us).
+     */
+    private _materialKey;
+    private _materialKeyBackend;
     get tint(): Color;
     set tint(tint: Color);
     get blendMode(): BlendModes;
@@ -55,6 +66,19 @@ export declare class Drawable extends RenderNode {
     _isDrawableForRenderPlan(): boolean;
     /** @internal */
     _renderPlanGetBlendMode(): BlendModes;
+    /**
+     * Resolve this drawable's {@link MaterialKey}, reusing a cached key when valid
+     * (Slice 2b). The cache busts on any tint/blend/texture/material/shader/
+     * pixel-snap mutation via {@link invalidateCache}, and on a backend switch.
+     *
+     * Drawables that own a {@link Material} are never cached — the material can
+     * change its `pipelineKey`/`bindKey` internally without notifying the node —
+     * so they recompute into the held key (still zero per-frame allocation).
+     *
+     * @internal
+     */
+    _getOrComputeMaterialKey(backend: RenderBackend): MaterialKey;
+    invalidateCache(): this;
     destroy(): void;
 }
 //# sourceMappingURL=Drawable.d.ts.map

package/dist/esm/rendering/Drawable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Drawable.d.ts","sourceRoot":"","sources":["../../../src/rendering/Drawable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAE3E,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,UAAU;IACtC,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,cAAc,CAAyB;IAE/C,IAAW,IAAI,IAAI,KAAK,CAEvB;IAED,IAAW,IAAI,CAAC,IAAI,EAAE,KAAK,EAE1B;IAED,IAAW,SAAS,IAAI,UAAU,CAEjC;IAED,IAAW,SAAS,CAAC,SAAS,EAAE,UAAU,EAEzC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAW,aAAa,IAAI,aAAa,CAExC;IAED,IAAW,aAAa,CAAC,IAAI,EAAE,aAAa,EAW3C;IAED;;;OAGG;IACI,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IASlC;;;OAGG;IACI,YAAY,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI;IAShD,gBAAgB;cACG,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAIpE,gBAAgB;IACA,wBAAwB,IAAI,OAAO;IAInD,gBAAgB;IACA,uBAAuB,IAAI,UAAU;IAIrC,OAAO,IAAI,IAAI;CAKhC"}
+{"version":3,"file":"Drawable.d.ts","sourceRoot":"","sources":["../../../src/rendering/Drawable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAA0B,KAAK,WAAW,EAAwB,MAAM,+BAA+B,CAAC;AAC/G,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,UAAU;IACtC,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,cAAc,CAAyB;IAE/C;;;;;;OAMG;IACH,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,mBAAmB,CAA8B;IAEzD,IAAW,IAAI,IAAI,KAAK,CAEvB;IAED,IAAW,IAAI,CAAC,IAAI,EAAE,KAAK,EAE1B;IAED,IAAW,SAAS,IAAI,UAAU,CAEjC;IAED,IAAW,SAAS,CAAC,SAAS,EAAE,UAAU,EAEzC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAW,aAAa,IAAI,aAAa,CAExC;IAED,IAAW,aAAa,CAAC,IAAI,EAAE,aAAa,EAW3C;IAED;;;OAGG;IACI,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IASlC;;;OAGG;IACI,YAAY,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI;IAShD,gBAAgB;cACG,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAIpE,gBAAgB;IACA,wBAAwB,IAAI,OAAO;IAInD,gBAAgB;IACA,uBAAuB,IAAI,UAAU;IAIrD;;;;;;;;;;OAUG;IACI,wBAAwB,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW;IAsCpD,eAAe,IAAI,IAAI;IASvB,OAAO,IAAI,IAAI;CAKhC"}

package/dist/esm/rendering/Drawable.js

@@ -1,4 +1,5 @@
 import { Color } from '../core/Color.js';
+import { drawableHasOwnMaterial, writeMaterialKeyInto } from './plan/RenderCommand.js';
 import { isPixelSnapMode } from './pixelSnap.js';
 import { RenderNode } from './RenderNode.js';
 import { BlendModes } from './types.js';
@@ -14,6 +15,15 @@ class Drawable extends RenderNode {
     _tint = Color.white.clone();
     _blendMode = BlendModes.Normal;
     _pixelSnapMode = 'none';
+    /**
+     * Cached material key (Slice 2b). `null` until first computed or after
+     * {@link invalidateCache}. Bound to {@link _materialKeyBackend} so a backend
+     * switch (multi-app / multi-backend) recomputes rather than returning stale
+     * renderer ids. Drawables that carry their own {@link Material} bypass this
+     * cache entirely (the material can mutate its keys without notifying us).
+     */
+    _materialKey = null;
+    _materialKeyBackend = null;
     get tint() {
         return this._tint;
     }
@@ -92,6 +102,50 @@ class Drawable extends RenderNode {
     _renderPlanGetBlendMode() {
         return this._blendMode;
     }
+    /**
+     * Resolve this drawable's {@link MaterialKey}, reusing a cached key when valid
+     * (Slice 2b). The cache busts on any tint/blend/texture/material/shader/
+     * pixel-snap mutation via {@link invalidateCache}, and on a backend switch.
+     *
+     * Drawables that own a {@link Material} are never cached — the material can
+     * change its `pipelineKey`/`bindKey` internally without notifying the node —
+     * so they recompute into the held key (still zero per-frame allocation).
+     *
+     * @internal
+     */
+    _getOrComputeMaterialKey(backend) {
+        const cached = this._materialKey;
+        if (cached !== null) {
+            if (drawableHasOwnMaterial(this)) {
+                // Own-material path: never trust the cache, but reuse the held object.
+                return writeMaterialKeyInto(cached, this, backend);
+            }
+            if (this._materialKeyBackend === backend) {
+                return cached;
+            }
+            // Backend switched: recompute into the held key, rebind to the backend.
+            this._materialKeyBackend = backend;
+            return writeMaterialKeyInto(cached, this, backend);
+        }
+        const key = writeMaterialKeyInto({
+            rendererId: 0,
+            blendMode: this._blendMode,
+            textureId: -1,
+            shaderId: -1,
+            pipelineKey: 0,
+            bindKey: 0,
+        }, this, backend);
+        this._materialKey = key;
+        this._materialKeyBackend = backend;
+        return key;
+    }
+    invalidateCache() {
+        super.invalidateCache();
+        // Bust the cached material key; next emitDraw recomputes it. The held object
+        // is kept and rewritten in place on the next miss (no re-allocation).
+        this._materialKeyBackend = null;
+        return this;
+    }
     destroy() {
         super.destroy();
         this._tint.destroy();

package/dist/esm/rendering/Drawable.js.map

@@ -1 +1 @@
-{"version":3,"file":"Drawable.js","sources":["../../../../src/rendering/Drawable.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAOA;;;;;;AAMG;AACG,MAAO,QAAS,SAAQ,UAAU,CAAA;AAC9B,IAAA,KAAK,GAAU,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE;AAClC,IAAA,UAAU,GAAe,UAAU,CAAC,MAAM;IAC1C,cAAc,GAAkB,MAAM;AAE9C,IAAA,IAAW,IAAI,GAAA;QACb,OAAO,IAAI,CAAC,KAAK;IACnB;IAEA,IAAW,IAAI,CAAC,IAAW,EAAA;AACzB,QAAA,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IACpB;AAEA,IAAA,IAAW,SAAS,GAAA;QAClB,OAAO,IAAI,CAAC,UAAU;IACxB;IAEA,IAAW,SAAS,CAAC,SAAqB,EAAA;AACxC,QAAA,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC;IAC9B;AAEA;;;;;;;;;;;;;;;;;;AAkBG;AACH,IAAA,IAAW,aAAa,GAAA;QACtB,OAAO,IAAI,CAAC,cAAc;IAC5B;IAEA,IAAW,aAAa,CAAC,IAAmB,EAAA;AAC1C,QAAA,IAAI,IAAI,KAAK,IAAI,CAAC,cAAc,EAAE;YAChC;QACF;AAEA,QAAA,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE;YAC1B,MAAM,IAAI,KAAK,CAAC,CAAA,sEAAA,EAAyE,MAAM,CAAC,IAAI,CAAC,CAAA,EAAA,CAAI,CAAC;QAC5G;AAEA,QAAA,IAAI,CAAC,cAAc,GAAG,IAAI;QAC1B,IAAI,CAAC,eAAe,EAAE;IACxB;AAEA;;;AAGG;AACI,IAAA,OAAO,CAAC,KAAY,EAAA;QACzB,IAAI,KAAK,EAAE;AACT,YAAA,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YACtB,IAAI,CAAC,eAAe,EAAE;QACxB;AAEA,QAAA,OAAO,IAAI;IACb;AAEA;;;AAGG;AACI,IAAA,YAAY,CAAC,SAAqB,EAAA;AACvC,QAAA,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE;AACjC,YAAA,IAAI,CAAC,UAAU,GAAG,SAAS;YAC3B,IAAI,CAAC,eAAe,EAAE;QACxB;AAEA,QAAA,OAAO,IAAI;IACb;;AAGmB,IAAA,eAAe,CAAC,OAA0B,EAAA;AAC3D,QAAA,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;IACxB;;IAGgB,wBAAwB,GAAA;AACtC,QAAA,OAAO,IAAI;IACb;;IAGgB,uBAAuB,GAAA;QACrC,OAAO,IAAI,CAAC,UAAU;IACxB;IAEgB,OAAO,GAAA;QACrB,KAAK,CAAC,OAAO,EAAE;AAEf,QAAA,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;IACtB;AACD;;;;"}
+{"version":3,"file":"Drawable.js","sources":["../../../../src/rendering/Drawable.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/GpuResourceAccountant.d.ts

@@ -0,0 +1,65 @@
+import type { RenderStats } from './RenderStats';
+/**
+ * Per-backend GPU resource accountant (Slice 2g — Resource-Accounting).
+ *
+ * The GPU exposes no way to query VRAM usage (neither WebGL2 nor WebGPU report
+ * it — a deliberate security boundary), so the engine keeps its own running
+ * tally by booking every allocation (`+`) and every free (`−`) at the points
+ * where the backend creates or destroys a GPU texture / buffer. The same
+ * bookkeeping runs against the Node fake-context, so it is fully deterministic
+ * and CI-testable.
+ *
+ * The accountant owns the authoritative running total ({@link liveBytes}) and
+ * mirrors it into {@link RenderStats.gpuMemoryBytes}. Unlike the per-frame
+ * counters, that total is **not** zeroed by {@link resetRenderStats} — live
+ * resources outlive frames. The per-frame upload / download accumulators are
+ * written straight into the stats object and reset each tick.
+ *
+ * One accountant per backend instance (never module-global) so that multiple
+ * concurrent {@link Application}s keep independent tallies.
+ *
+ * @internal
+ */
+export declare class GpuResourceAccountant {
+    private readonly _stats;
+    private _liveBytes;
+    constructor(stats: RenderStats);
+    /** Current running total of live GPU resource bytes (textures + buffers). */
+    get liveBytes(): number;
+    /**
+     * Record an allocation of `bytes` GPU memory (texture storage or buffer).
+     * Pass a non-negative value; the running total and the mirrored
+     * `stats.gpuMemoryBytes` both increase.
+     */
+    allocate(bytes: number): void;
+    /**
+     * Record a free of `bytes` GPU memory. Clamped at zero so a double-free or a
+     * missed allocation can never drive the tally negative. To avoid transient
+     * spikes on resize, book the free **before** the matching re-allocation.
+     */
+    free(bytes: number): void;
+    /**
+     * Re-book a resource whose byte size changed in place (e.g. a texture resize):
+     * frees the previous size and allocates the next, never dipping below zero.
+     * Returns the new size so callers can stash it for the next free.
+     */
+    reallocate(previousBytes: number, nextBytes: number): number;
+    /** Record `bytes` of content-texture pixel data uploaded this frame (CPU → GPU). */
+    recordTextureUpload(bytes: number): void;
+    /** Record `bytes` of buffer data uploaded this frame (CPU → GPU). */
+    recordBufferUpload(bytes: number): void;
+    /** Record a GPU → CPU readback of `bytes` this frame (e.g. `mapAsync`, `readPixels`). */
+    recordDownload(bytes: number): void;
+}
+/**
+ * Estimated bytes for a 2D texture of `width × height` at `bytesPerPixel`,
+ * including the mip chain when `mipLevelCount > 1`. A full mip chain adds
+ * roughly ¹⁄₃ over the base level; this sums the exact per-level footprint
+ * (each level a quarter of the previous, floored at 1×1).
+ *
+ * @internal
+ */
+export declare const estimateTextureBytes: (width: number, height: number, bytesPerPixel: number, mipLevelCount?: number) => number;
+/** Bytes per pixel for the {@link DataTexture} formats (shared by both backends). @internal */
+export declare const dataTextureBytesPerPixel: (format: "r8" | "r32f" | "rgba8" | "rgba32f") => number;
+//# sourceMappingURL=GpuResourceAccountant.d.ts.map

package/dist/esm/rendering/GpuResourceAccountant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GpuResourceAccountant.d.ts","sourceRoot":"","sources":["../../../src/rendering/GpuResourceAccountant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,UAAU,CAAK;gBAEJ,KAAK,EAAE,WAAW;IAKrC,6EAA6E;IAC7E,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED;;;;OAIG;IACI,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IASpC;;;;OAIG;IACI,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAShC;;;;OAIG;IACI,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAOnE,oFAAoF;IAC7E,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ/C,qEAAqE;IAC9D,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ9C,yFAAyF;IAClF,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAQ3C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,EAAE,QAAQ,MAAM,EAAE,eAAe,MAAM,EAAE,sBAAiB,KAAG,MAqB9G,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,wBAAwB,GAAI,QAAQ,IAAI,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,KAAG,MAWtF,CAAC"}

package/dist/esm/rendering/GpuResourceAccountant.js

@@ -0,0 +1,130 @@
+/**
+ * Per-backend GPU resource accountant (Slice 2g — Resource-Accounting).
+ *
+ * The GPU exposes no way to query VRAM usage (neither WebGL2 nor WebGPU report
+ * it — a deliberate security boundary), so the engine keeps its own running
+ * tally by booking every allocation (`+`) and every free (`−`) at the points
+ * where the backend creates or destroys a GPU texture / buffer. The same
+ * bookkeeping runs against the Node fake-context, so it is fully deterministic
+ * and CI-testable.
+ *
+ * The accountant owns the authoritative running total ({@link liveBytes}) and
+ * mirrors it into {@link RenderStats.gpuMemoryBytes}. Unlike the per-frame
+ * counters, that total is **not** zeroed by {@link resetRenderStats} — live
+ * resources outlive frames. The per-frame upload / download accumulators are
+ * written straight into the stats object and reset each tick.
+ *
+ * One accountant per backend instance (never module-global) so that multiple
+ * concurrent {@link Application}s keep independent tallies.
+ *
+ * @internal
+ */
+class GpuResourceAccountant {
+    _stats;
+    _liveBytes = 0;
+    constructor(stats) {
+        this._stats = stats;
+        this._stats.gpuMemoryBytes = 0;
+    }
+    /** Current running total of live GPU resource bytes (textures + buffers). */
+    get liveBytes() {
+        return this._liveBytes;
+    }
+    /**
+     * Record an allocation of `bytes` GPU memory (texture storage or buffer).
+     * Pass a non-negative value; the running total and the mirrored
+     * `stats.gpuMemoryBytes` both increase.
+     */
+    allocate(bytes) {
+        if (bytes <= 0) {
+            return;
+        }
+        this._liveBytes += bytes;
+        this._stats.gpuMemoryBytes = this._liveBytes;
+    }
+    /**
+     * Record a free of `bytes` GPU memory. Clamped at zero so a double-free or a
+     * missed allocation can never drive the tally negative. To avoid transient
+     * spikes on resize, book the free **before** the matching re-allocation.
+     */
+    free(bytes) {
+        if (bytes <= 0) {
+            return;
+        }
+        this._liveBytes = Math.max(0, this._liveBytes - bytes);
+        this._stats.gpuMemoryBytes = this._liveBytes;
+    }
+    /**
+     * Re-book a resource whose byte size changed in place (e.g. a texture resize):
+     * frees the previous size and allocates the next, never dipping below zero.
+     * Returns the new size so callers can stash it for the next free.
+     */
+    reallocate(previousBytes, nextBytes) {
+        this.free(previousBytes);
+        this.allocate(nextBytes);
+        return nextBytes;
+    }
+    /** Record `bytes` of content-texture pixel data uploaded this frame (CPU → GPU). */
+    recordTextureUpload(bytes) {
+        if (bytes <= 0) {
+            return;
+        }
+        this._stats.textureUploadBytes += bytes;
+    }
+    /** Record `bytes` of buffer data uploaded this frame (CPU → GPU). */
+    recordBufferUpload(bytes) {
+        if (bytes <= 0) {
+            return;
+        }
+        this._stats.bufferUploadBytes += bytes;
+    }
+    /** Record a GPU → CPU readback of `bytes` this frame (e.g. `mapAsync`, `readPixels`). */
+    recordDownload(bytes) {
+        if (bytes <= 0) {
+            return;
+        }
+        this._stats.downloadBytes += bytes;
+        this._stats.downloadCount++;
+    }
+}
+/**
+ * Estimated bytes for a 2D texture of `width × height` at `bytesPerPixel`,
+ * including the mip chain when `mipLevelCount > 1`. A full mip chain adds
+ * roughly ¹⁄₃ over the base level; this sums the exact per-level footprint
+ * (each level a quarter of the previous, floored at 1×1).
+ *
+ * @internal
+ */
+const estimateTextureBytes = (width, height, bytesPerPixel, mipLevelCount = 1) => {
+    const baseWidth = Math.max(1, Math.floor(width));
+    const baseHeight = Math.max(1, Math.floor(height));
+    const levels = Math.max(1, Math.floor(mipLevelCount));
+    let total = 0;
+    let levelWidth = baseWidth;
+    let levelHeight = baseHeight;
+    for (let level = 0; level < levels; level++) {
+        total += levelWidth * levelHeight * bytesPerPixel;
+        if (levelWidth === 1 && levelHeight === 1) {
+            break;
+        }
+        levelWidth = Math.max(1, levelWidth >> 1);
+        levelHeight = Math.max(1, levelHeight >> 1);
+    }
+    return total;
+};
+/** Bytes per pixel for the {@link DataTexture} formats (shared by both backends). @internal */
+const dataTextureBytesPerPixel = (format) => {
+    switch (format) {
+        case 'r8':
+            return 1;
+        case 'r32f':
+            return 4;
+        case 'rgba8':
+            return 4;
+        case 'rgba32f':
+            return 16;
+    }
+};
+
+export { GpuResourceAccountant, dataTextureBytesPerPixel, estimateTextureBytes };
+//# sourceMappingURL=GpuResourceAccountant.js.map

package/dist/esm/rendering/GpuResourceAccountant.js.map

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

package/dist/esm/rendering/RenderBackend.d.ts

@@ -2,6 +2,7 @@ import type { Color } from '#core/Color';
 import type { Matrix } from '#math/Matrix';
 import type { Rectangle } from '#math/Rectangle';
 import type { Geometry } from '#rendering/geometry/Geometry';
+import type { Mesh } from '#rendering/mesh/Mesh';
 import type { RenderTexture } from '#rendering/texture/RenderTexture';
 import type { Texture } from '#rendering/texture/Texture';
 import type { BackendRenderPass } from './BackendRenderPass';
@@ -28,7 +29,7 @@ import type { View } from './View';
  */
 export interface RenderBackend {
     readonly backendType: RenderBackendType;
-    readonly rendererRegistry: RendererRegistry<any>;
+    readonly rendererRegistry: RendererRegistry<RenderBackend>;
     readonly view: View;
     readonly renderTarget: RenderTarget;
     readonly stats: RenderStats;
@@ -75,6 +76,19 @@ export interface RenderBackend {
      */
     composeWithAlphaMask(content: RenderTexture, mask: Texture | RenderTexture, x: number, y: number, width: number, height: number, blendMode: BlendModes): this;
     draw(drawable: Drawable): this;
+    /**
+     * Submit an explicit instanced batch: draw `mesh`'s geometry once with `count`
+     * per-instance `(transform, tint)` pairs, written into fresh shared transform
+     * slots, as a single instanced draw call. `mesh` carries the geometry,
+     * material, texture and blend mode; its own transform and tint are ignored.
+     * Only the first `count` entries of `transforms` / `tints` are read.
+     *
+     * Used internally by {@link RenderingContext.drawBatch}. The geometry must use
+     * the `triangle-list` topology and the standard mesh attribute layout; a
+     * supplied material must be instancing-compatible (default mesh material, or a
+     * custom shader declaring `a_nodeIndex` + `u_transforms`).
+     */
+    drawInstanced(mesh: Mesh, transforms: readonly Matrix[], tints: readonly Color[], count: number): this;
     execute(pass: BackendRenderPass): this;
     flush(): this;
     destroy(): void;

package/dist/esm/rendering/RenderBackend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderBackend.d.ts","sourceRoot":"","sources":["../../../src/rendering/RenderBackend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IAExC,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,UAAU,IAAI,IAAI,CAAC;IACnB,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IACjC,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAAC;IAEnD;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAEzC;;OAEG;IACH,cAAc,IAAI,IAAI,CAAC;IAEvB;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1D;;;OAGG;IACH,cAAc,IAAI,IAAI,CAAC;IAEvB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC;IACnE,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAEnD;;;;;;OAMG;IACH,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,GAAG,aAAa,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC;IAE9J,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,IAAI,IAAI,CAAC;CACjB"}
+{"version":3,"file":"RenderBackend.d.ts","sourceRoot":"","sources":["../../../src/rendering/RenderBackend.ts"],"names":[],"mappings":"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"}

package/dist/esm/rendering/RenderBatch.d.ts

@@ -0,0 +1,55 @@
+import { Color } from '#core/Color';
+import { Matrix } from '#math/Matrix';
+import type { Geometry } from '#rendering/geometry/Geometry';
+import type { MeshMaterial } from '#rendering/material/MeshMaterial';
+/**
+ * Explicit instanced draw submission: **one** {@link Geometry} + {@link MeshMaterial}
+ * drawn **once** with **N** per-instance `(transform, tint)` pairs — the general
+ * form of the engine's mesh-instancing model, surfaced for data-driven rendering
+ * (thousands of tiles, bullets, grass blades, procedural items as a single draw).
+ *
+ * Build it up with {@link add}, hand it to {@link RenderingContext.drawBatch},
+ * and {@link clear} it to reuse the same instance across frames without
+ * reallocating — the per-instance transform/tint storage grows on demand and is
+ * retained across `clear()`, so a steady-state batch allocates nothing.
+ *
+ * Each {@link add} **copies** the transform and tint into internal storage, so
+ * the caller may mutate or reuse the passed `Matrix`/`Color` immediately
+ * afterwards without affecting the batch.
+ *
+ * This is the explicit instanced submission path — distinct from the internal
+ * automatic sprite batcher: every instance shares the one geometry and material,
+ * and the whole batch is a single instanced draw call.
+ * @stable
+ */
+export declare class RenderBatch {
+    /** The geometry every instance in this batch draws. */
+    readonly geometry: Geometry;
+    /** The shared mesh material, or `null` for the default mesh material. */
+    readonly material: MeshMaterial | null;
+    private readonly _transforms;
+    private readonly _tints;
+    private _count;
+    constructor(geometry: Geometry, material?: MeshMaterial | null);
+    /** Number of instances currently in the batch. */
+    get count(): number;
+    /**
+     * Append one instance. `transform` is the instance's world matrix (taken as
+     * the raw `a,b,c,d,tx,ty`), `tint` modulates the geometry's vertex colors
+     * (defaults to white). Both are copied into the batch.
+     */
+    add(transform: Matrix, tint?: Color | null): this;
+    /** Reset to zero instances for reuse, retaining the pooled storage. */
+    clear(): this;
+    /**
+     * Release the pooled per-instance storage. After this the batch must not be
+     * reused. The {@link geometry} and {@link material} are owned by the caller and
+     * are not destroyed.
+     */
+    destroy(): void;
+    /** Pooled per-instance transforms; only the first {@link count} are valid. @internal */
+    get _instanceTransforms(): readonly Matrix[];
+    /** Pooled per-instance tints; only the first {@link count} are valid. @internal */
+    get _instanceTints(): readonly Color[];
+}
+//# sourceMappingURL=RenderBatch.d.ts.map

package/dist/esm/rendering/RenderBatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderBatch.d.ts","sourceRoot":"","sources":["../../../src/rendering/RenderBatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAW;IACtB,uDAAuD;IACvD,SAAgB,QAAQ,EAAE,QAAQ,CAAC;IAEnC,yEAAyE;IACzE,SAAgB,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAI9C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,MAAM,CAAK;gBAEA,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAE,YAAY,GAAG,IAAW;IAmB3E,kDAAkD;IAClD,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED;;;;OAIG;IACI,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,KAAK,GAAG,IAAW,GAAG,IAAI;IAwB9D,uEAAuE;IAChE,KAAK,IAAI,IAAI;IAMpB;;;;OAIG;IACI,OAAO,IAAI,IAAI;IActB,wFAAwF;IACxF,IAAW,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAElD;IAED,mFAAmF;IACnF,IAAW,cAAc,IAAI,SAAS,KAAK,EAAE,CAE5C;CACF"}

package/dist/esm/rendering/RenderBatch.js

@@ -0,0 +1,107 @@
+import { Color } from '../core/Color.js';
+import { Matrix } from '../math/Matrix.js';
+
+/**
+ * Explicit instanced draw submission: **one** {@link Geometry} + {@link MeshMaterial}
+ * drawn **once** with **N** per-instance `(transform, tint)` pairs — the general
+ * form of the engine's mesh-instancing model, surfaced for data-driven rendering
+ * (thousands of tiles, bullets, grass blades, procedural items as a single draw).
+ *
+ * Build it up with {@link add}, hand it to {@link RenderingContext.drawBatch},
+ * and {@link clear} it to reuse the same instance across frames without
+ * reallocating — the per-instance transform/tint storage grows on demand and is
+ * retained across `clear()`, so a steady-state batch allocates nothing.
+ *
+ * Each {@link add} **copies** the transform and tint into internal storage, so
+ * the caller may mutate or reuse the passed `Matrix`/`Color` immediately
+ * afterwards without affecting the batch.
+ *
+ * This is the explicit instanced submission path — distinct from the internal
+ * automatic sprite batcher: every instance shares the one geometry and material,
+ * and the whole batch is a single instanced draw call.
+ * @stable
+ */
+class RenderBatch {
+    /** The geometry every instance in this batch draws. */
+    geometry;
+    /** The shared mesh material, or `null` for the default mesh material. */
+    material;
+    // Per-instance storage grows with `add` and is reused after `clear` — only the
+    // logical `_count` resets, the pooled Matrix/Color instances are kept.
+    _transforms = [];
+    _tints = [];
+    _count = 0;
+    constructor(geometry, material = null) {
+        // The batch uploads its geometry to the GPU once and caches it by identity,
+        // so the geometry must be static (the default). dynamic/stream geometry has
+        // no persistent GPU buffer and is rejected.
+        if (geometry.usage !== 'static') {
+            throw new Error(`RenderBatch requires geometry with usage='static' (got '${geometry.usage}').`);
+        }
+        // v1 renders batches with the default mesh material; a custom material is not
+        // yet supported on the instanced path. The parameter is accepted (and stored)
+        // for the forthcoming custom-material batch support.
+        if (material !== null && material.target !== 'mesh') {
+            throw new Error(`RenderBatch material must target 'mesh' (got '${String(material.target)}').`);
+        }
+        this.geometry = geometry;
+        this.material = material;
+    }
+    /** Number of instances currently in the batch. */
+    get count() {
+        return this._count;
+    }
+    /**
+     * Append one instance. `transform` is the instance's world matrix (taken as
+     * the raw `a,b,c,d,tx,ty`), `tint` modulates the geometry's vertex colors
+     * (defaults to white). Both are copied into the batch.
+     */
+    add(transform, tint = null) {
+        let matrix = this._transforms[this._count];
+        if (matrix === undefined) {
+            matrix = new Matrix();
+            this._transforms[this._count] = matrix;
+        }
+        matrix.copy(transform);
+        let color = this._tints[this._count];
+        if (color === undefined) {
+            color = new Color();
+            this._tints[this._count] = color;
+        }
+        color.copy(tint ?? Color.white);
+        this._count++;
+        return this;
+    }
+    /** Reset to zero instances for reuse, retaining the pooled storage. */
+    clear() {
+        this._count = 0;
+        return this;
+    }
+    /**
+     * Release the pooled per-instance storage. After this the batch must not be
+     * reused. The {@link geometry} and {@link material} are owned by the caller and
+     * are not destroyed.
+     */
+    destroy() {
+        for (const matrix of this._transforms) {
+            matrix.destroy();
+        }
+        for (const color of this._tints) {
+            color.destroy();
+        }
+        this._transforms.length = 0;
+        this._tints.length = 0;
+        this._count = 0;
+    }
+    /** Pooled per-instance transforms; only the first {@link count} are valid. @internal */
+    get _instanceTransforms() {
+        return this._transforms;
+    }
+    /** Pooled per-instance tints; only the first {@link count} are valid. @internal */
+    get _instanceTints() {
+        return this._tints;
+    }
+}
+
+export { RenderBatch };
+//# sourceMappingURL=RenderBatch.js.map

package/dist/esm/rendering/RenderBatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderBatch.js","sources":["../../../../src/rendering/RenderBatch.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAKA;;;;;;;;;;;;;;;;;;;AAmBG;MACU,WAAW,CAAA;;AAEN,IAAA,QAAQ;;AAGR,IAAA,QAAQ;;;IAIP,WAAW,GAAa,EAAE;IAC1B,MAAM,GAAY,EAAE;IAC7B,MAAM,GAAG,CAAC;IAElB,WAAA,CAAmB,QAAkB,EAAE,QAAA,GAAgC,IAAI,EAAA;;;;AAIzE,QAAA,IAAI,QAAQ,CAAC,KAAK,KAAK,QAAQ,EAAE;YAC/B,MAAM,IAAI,KAAK,CAAC,CAAA,wDAAA,EAA2D,QAAQ,CAAC,KAAK,CAAA,GAAA,CAAK,CAAC;QACjG;;;;QAKA,IAAI,QAAQ,KAAK,IAAI,IAAK,QAAQ,CAAC,MAAiB,KAAK,MAAM,EAAE;AAC/D,YAAA,MAAM,IAAI,KAAK,CAAC,CAAA,8CAAA,EAAiD,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA,GAAA,CAAK,CAAC;QAChG;AAEA,QAAA,IAAI,CAAC,QAAQ,GAAG,QAAQ;AACxB,QAAA,IAAI,CAAC,QAAQ,GAAG,QAAQ;IAC1B;;AAGA,IAAA,IAAW,KAAK,GAAA;QACd,OAAO,IAAI,CAAC,MAAM;IACpB;AAEA;;;;AAIG;AACI,IAAA,GAAG,CAAC,SAAiB,EAAE,IAAA,GAAqB,IAAI,EAAA;QACrD,IAAI,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC;AAE1C,QAAA,IAAI,MAAM,KAAK,SAAS,EAAE;AACxB,YAAA,MAAM,GAAG,IAAI,MAAM,EAAE;YACrB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,MAAM;QACxC;AAEA,QAAA,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;QAEtB,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;AAEpC,QAAA,IAAI,KAAK,KAAK,SAAS,EAAE;AACvB,YAAA,KAAK,GAAG,IAAI,KAAK,EAAE;YACnB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,KAAK;QAClC;QAEA,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC;QAE/B,IAAI,CAAC,MAAM,EAAE;AAEb,QAAA,OAAO,IAAI;IACb;;IAGO,KAAK,GAAA;AACV,QAAA,IAAI,CAAC,MAAM,GAAG,CAAC;AAEf,QAAA,OAAO,IAAI;IACb;AAEA;;;;AAIG;IACI,OAAO,GAAA;AACZ,QAAA,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,WAAW,EAAE;YACrC,MAAM,CAAC,OAAO,EAAE;QAClB;AAEA,QAAA,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE;YAC/B,KAAK,CAAC,OAAO,EAAE;QACjB;AAEA,QAAA,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;AAC3B,QAAA,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;AACtB,QAAA,IAAI,CAAC,MAAM,GAAG,CAAC;IACjB;;AAGA,IAAA,IAAW,mBAAmB,GAAA;QAC5B,OAAO,IAAI,CAAC,WAAW;IACzB;;AAGA,IAAA,IAAW,cAAc,GAAA;QACvB,OAAO,IAAI,CAAC,MAAM;IACpB;AACD;;;;"}

package/dist/esm/rendering/RenderNode.d.ts

@@ -1,7 +1,8 @@
 import { Color } from '#core/Color';
 import { SceneNode } from '#core/SceneNode';
 import { Signal } from '#core/Signal';
-import type { InteractionEvent } from '#input/InteractionEvent';
+import type { InteractionEvent, InteractionEventType } from '#input/InteractionEvent';
+import type { KeyEvent } from '#input/KeyEvent';
 import { Rectangle } from '#math/Rectangle';
 import type { Filter } from '#rendering/filters/Filter';
 import type { Geometry } from '#rendering/geometry/Geometry';
@@ -117,18 +118,57 @@ export declare abstract class RenderNode extends SceneNode {
      * @default null
      */
     clipShape: Rectangle | Geometry | null;
-    readonly onPointerDown: Signal<[InteractionEvent]>;
-    readonly onPointerUp: Signal<[InteractionEvent]>;
-    readonly onPointerMove: Signal<[InteractionEvent]>;
-    readonly onPointerOver: Signal<[InteractionEvent]>;
-    readonly onPointerOut: Signal<[InteractionEvent]>;
-    readonly onPointerTap: Signal<[InteractionEvent]>;
+    private _signals;
+    get onPointerDown(): Signal<[InteractionEvent]>;
+    get onPointerUp(): Signal<[InteractionEvent]>;
+    get onPointerMove(): Signal<[InteractionEvent]>;
+    get onPointerOver(): Signal<[InteractionEvent]>;
+    get onPointerOut(): Signal<[InteractionEvent]>;
+    get onPointerTap(): Signal<[InteractionEvent]>;
     /** Fired once when a drag gesture begins on this node. Does not bubble. */
-    readonly onDragStart: Signal<[InteractionEvent]>;
+    get onDragStart(): Signal<[InteractionEvent]>;
     /** Fired on every pointer-move while this node is being dragged. Does not bubble. */
-    readonly onDrag: Signal<[InteractionEvent]>;
+    get onDrag(): Signal<[InteractionEvent]>;
     /** Fired when the drag gesture ends (pointer-up or cancel). Does not bubble. */
-    readonly onDragEnd: Signal<[InteractionEvent]>;
+    get onDragEnd(): Signal<[InteractionEvent]>;
+    private _interactionSignal;
+    /** @internal — the signal for `type`, or `null` if never materialized (used by the dispatch peek). */
+    _peekInteractionSignal(type: InteractionEventType): Signal<[InteractionEvent]> | null;
+    /**
+     * When `true`, this node can receive keyboard focus — via {@link focus},
+     * Tab traversal, or `app.focus.focus(node)` — and is delivered key events
+     * through {@link onKeyDown} / {@link onKeyUp} while focused.
+     *
+     * @default false
+     */
+    focusable: boolean;
+    /**
+     * Tab-traversal order among focusable nodes in the same focus scope. Lower
+     * values are visited first; equal values keep document (tree) order.
+     *
+     * @default 0
+     */
+    tabIndex: number;
+    private _onFocus;
+    private _onBlur;
+    private _onKeyDown;
+    private _onKeyUp;
+    /** Fired when this node gains keyboard focus. */
+    get onFocus(): Signal<[RenderNode]>;
+    /** Fired when this node loses keyboard focus. */
+    get onBlur(): Signal<[RenderNode]>;
+    /** Fired for each key pressed while this node holds focus. */
+    get onKeyDown(): Signal<[KeyEvent]>;
+    /** Fired for each key released while this node holds focus. */
+    get onKeyUp(): Signal<[KeyEvent]>;
+    /** @internal — the focus/blur signal if materialized, else `null` (dispatch peek). */
+    _peekFocusSignal(type: 'focus' | 'blur'): Signal<[RenderNode]> | null;
+    /** @internal — the keydown/keyup signal if materialized, else `null` (dispatch peek). */
+    _peekKeySignal(type: 'keydown' | 'keyup'): Signal<[KeyEvent]> | null;
+    /** Request keyboard focus for this node through its owning focus service. */
+    focus(): this;
+    /** Release keyboard focus from this node if it currently holds it. */
+    blur(): this;
     private readonly _filters;
     private readonly _cacheBounds;
     private _cacheSprite;