@codexo/exojs 0.10.0 → 0.11.0

package/dist/exo.esm.js

@@ -11828,6 +11828,39 @@ const makeMaterialKey = (drawable, backend) => {
         bindKey,
     };
 };
+/**
+ * Whether a draw command's renderer reads the shared {@link TransformBuffer} /
+ * transform storage. The render-group upload boundary packs each command's
+ * world transform (+ tint) keyed by its `nodeIndex`; only renderers that fetch
+ * those rows back from the buffer need a record written.
+ *
+ * Sprite and Mesh (and their subclasses — {@link AnimatedSprite}, Video,
+ * Graphics' meshes) fetch the transform via `nodeIndex` and therefore consume
+ * it. Text/BitmapText and particle renderers pack their own per-node data into
+ * a private data texture / uniforms and never touch the shared buffer, so they
+ * opt out via `_consumesSharedTransform === false` and their writes are skipped.
+ *
+ * Anything else — a custom renderer, or a drawable with no registered renderer
+ * (resolve throws) — defaults to writing, so behaviour is unchanged for any
+ * path that might still rely on the shared transform.
+ *
+ * @internal
+ */
+const drawCommandUsesSharedTransform = (command, backend) => {
+    const registry = backend.rendererRegistry;
+    if (!registry || typeof registry.resolve !== 'function') {
+        return true;
+    }
+    try {
+        const renderer = registry.resolve(command.drawable);
+        return renderer._consumesSharedTransform !== false;
+    }
+    catch {
+        // No renderer registered for a custom drawable: keep the conservative
+        // write so any consumer of the shared transform keeps working.
+        return true;
+    }
+};
 
 /** @internal */
 class MutableRenderPlan {
@@ -12264,6 +12297,22 @@ class RenderPlanOptimizer {
     }
 }
 
+// Internal dev/diagnostic utilities. Guards are stripped in production builds
+// when false is replaced with `false` by the rollup replace plugin.
+/**
+ * Assert `condition` at dev/test time. Throws with `[ExoJS] message` when the
+ * condition is falsy and `false` is true. No-op in production builds.
+ */
+function assert(condition, message) {
+}
+/**
+ * Print a `console.warn` at most once per unique `key`.
+ * Subsequent calls with the same key are silenced to avoid per-frame spam.
+ * No-op in production builds.
+ */
+function warnOnce(key, message) {
+}
+
 /**
  * A {@link Size} subclass that fires a callback whenever `width` or `height`
  * changes. Used internally by layout-aware types to invalidate cached geometry
@@ -13547,6 +13596,47 @@ class RenderEffectExecutor {
     }
 }
 
+/**
+ * Materialize the {@link RenderGroup} batch units contained directly in
+ * `scope`. Consecutive draw instructions that share a defined `groupIndex`
+ * coalesce into one group; any non-draw entry (a nested group or barrier)
+ * breaks the run, and a draw whose `groupIndex` is still `undefined` (i.e.
+ * the plan has not been optimized) forms its own singleton group — mirroring
+ * the adjacency semantics the mesh renderers already rely on.
+ *
+ * This is a read-only view over an (optimized) scope; it does not mutate the
+ * plan or affect playback order.
+ *
+ * @internal
+ */
+function collectRenderGroups(scope) {
+    const groups = [];
+    let current = null;
+    for (const entry of scope.entries) {
+        if (entry.kind !== RenderEntryKind.Draw) {
+            current = null;
+            continue;
+        }
+        const command = entry.command;
+        const groupIndex = command.groupIndex;
+        if (current !== null && groupIndex !== undefined && groupIndex === current.groupIndex) {
+            current.instructions.push(command);
+            continue;
+        }
+        current = {
+            groupIndex: groupIndex ?? 0,
+            material: command.material,
+            instructions: [command],
+        };
+        groups.push(current);
+        if (groupIndex === undefined) {
+            // Unoptimized / non-batchable draw: never coalesce with the next one.
+            current = null;
+        }
+    }
+    return groups;
+}
+
 /** @internal */
 class RenderPlanPlayer {
     static play(plan, backend) {
@@ -13563,7 +13653,7 @@ class RenderPlanPlayer {
                 if (pass.clearColor !== null) {
                     backend.clear(pass.clearColor);
                 }
-                this.playScope(pass.root, backend);
+                this._playScope(pass.root, backend, hooks, this._createPlaybackContext());
             }
         }
         finally {
@@ -13571,31 +13661,81 @@ class RenderPlanPlayer {
         }
     }
     static playScope(scope, backend) {
+        const hooks = backend;
+        this._playScope(scope, backend, hooks, this._createPlaybackContext());
+    }
+    static _playScope(scope, backend, hooks, context) {
         if (scope.kind === RenderEntryKind.Barrier) {
             RenderEffectExecutor.play(scope, backend, childScope => {
-                this.playScope(childScope, backend);
+                this._playScope(childScope, backend, hooks, context);
             });
             return;
         }
-        this._playGroup(scope, backend);
+        this._playGroup(scope, backend, hooks, context);
     }
-    static _playGroup(scope, backend) {
-        const hooks = backend;
+    static _playGroup(scope, backend, hooks, context) {
+        const groups = collectRenderGroups(scope);
+        let groupCursor = 0;
+        let currentGroup = null;
+        let currentInstructionIndex = 0;
         for (const entry of scope.entries) {
             if (entry.kind === RenderEntryKind.Draw) {
+                if (currentGroup === null) {
+                    currentGroup = groups[groupCursor];
+                    currentInstructionIndex = 0;
+                    hooks._beginRenderGroup?.(currentGroup);
+                    hooks._prepareRenderGroupUpload?.(currentGroup, this._createRenderGroupPlaybackContext(currentGroup.instructions.length, context.passInstructionIndex, context.passGroupIndex));
+                    context.passGroupIndex++;
+                }
+                // Allocate the per-draw instruction slot only when a backend consumes
+                // it. No shipped backend implements `_prepareRenderInstructionSlot`, so
+                // skipping the `Object.freeze` slot allocation removes per-draw garbage
+                // from the playback hot path while preserving the extension point.
+                if (hooks._prepareRenderInstructionSlot !== undefined) {
+                    const slot = this._createRenderInstructionSlot(currentInstructionIndex, context.passInstructionIndex);
+                    hooks._prepareRenderInstructionSlot(entry.command, slot);
+                }
                 hooks._prepareDrawCommand?.(entry.command);
                 backend.draw(entry.command.drawable);
+                currentInstructionIndex++;
+                context.passInstructionIndex++;
+                if (currentGroup !== null && currentInstructionIndex === currentGroup.instructions.length) {
+                    hooks._endRenderGroup?.(currentGroup);
+                    currentGroup = null;
+                    currentInstructionIndex = 0;
+                    groupCursor++;
+                }
             }
             else if (entry.kind === RenderEntryKind.Group) {
-                this._playGroup(entry.scope, backend);
+                this._playGroup(entry.scope, backend, hooks, context);
             }
             else {
                 RenderEffectExecutor.play(entry.scope, backend, childScope => {
-                    this.playScope(childScope, backend);
+                    this._playScope(childScope, backend, hooks, context);
                 });
             }
         }
     }
+    static _createPlaybackContext() {
+        return {
+            passInstructionIndex: 0,
+            passGroupIndex: 0,
+        };
+    }
+    static _createRenderGroupPlaybackContext(groupInstructionCount, firstPassInstructionIndex, passGroupIndex) {
+        return Object.freeze({
+            groupInstructionCount,
+            firstPassInstructionIndex,
+            lastPassInstructionIndex: firstPassInstructionIndex + groupInstructionCount - 1,
+            passGroupIndex,
+        });
+    }
+    static _createRenderInstructionSlot(groupInstructionIndex, passInstructionIndex) {
+        return Object.freeze({
+            groupInstructionIndex,
+            passInstructionIndex,
+        });
+    }
 }
 
 /** @internal — single source of truth for plan build→optimize→play. */
@@ -13615,7 +13755,7 @@ function playRenderTree(node, backend) {
  * 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 (from phase 12D onwards) uses it to
+ * informational there; the WebGPU backend uses it to
  * decide whether a pass descriptor needs a `depthStencilAttachment`.
  * @internal
  */
@@ -16654,6 +16794,7 @@ class BmFont {
     fontData;
     textures;
     constructor(fontData, textures) {
+        assert(textures.length === fontData.pages.length, `BmFont: texture count (${textures.length}) must match page count (${fontData.pages.length})`);
         this.fontData = fontData;
         this.textures = textures;
     }
@@ -16975,7 +17116,7 @@ class TextStyle {
     constructor(options = {}) {
         const explicitFace = typeof FontFace !== 'undefined' && options.font instanceof FontFace ? options.font : null;
         this._fontFamily = explicitFace ? explicitFace.family : (options.fontFamily ?? 'Arial');
-        this._fontWeight = options.fontWeight ?? 'bold';
+        this._fontWeight = options.fontWeight ?? 'normal';
         this._fontStyle = options.fontStyle ?? 'normal';
         this._fontSize = options.fontSize ?? 20;
         this._fillColor = options.fillColor ? options.fillColor.clone() : Color.white.clone();
@@ -17256,11 +17397,14 @@ class BmFontAdapter {
     _scale;
     /** Fallback advance for characters not present in the font (≈ ½ line height). */
     _fallbackAdvance;
+    /** Identifier used as part of the warnOnce key — derived from the first page filename. */
+    _fontId;
     constructor(fontData, textures, scale) {
         this._fontData = fontData;
         this._textures = textures;
         this._scale = scale;
         this._fallbackAdvance = fontData.lineHeight * scale * 0.5;
+        this._fontId = fontData.pages[0] ?? 'unknown';
     }
     getGlyph(char, _fontSize) {
         const cp = char.codePointAt(0) ?? 0;
@@ -17269,7 +17413,9 @@ class BmFontAdapter {
         const lh = this._fontData.lineHeight;
         const base = this._fontData.base;
         if (g === undefined) {
-            // Unknown glyph — return an invisible placeholder with a cursor advance.
+            // Unknown glyph — warn once per font + codepoint, then return an invisible
+            // placeholder with a cursor advance so layout still makes progress.
+            warnOnce(`bitmaptext:${this._fontId}:${cp}`, `BitmapText: missing glyph U+${cp.toString(16).toUpperCase().padStart(4, '0')} ('${char}') in "${this._fontId}"`);
             return {
                 x: 0,
                 y: 0,
@@ -17284,6 +17430,7 @@ class BmFontAdapter {
                 uvBottom: 0,
             };
         }
+        assert(g.page < this._textures.length, `BitmapText: glyph page index ${g.page} is out of range — font "${this._fontId}" has ${this._textures.length} page(s)`);
         const texW = this._textures[g.page]?.width ?? 1;
         const texH = this._textures[g.page]?.height ?? 1;
         return {
@@ -17655,6 +17802,14 @@ class GlyphSdf {
     _radius;
     _cutoff;
     _font;
+    _fontSize;
+    // Font-level ascent/descent — measured once from a reference string so that
+    // all glyph tiles share the same height and baseline position. This avoids
+    // the per-glyph actualBoundingBoxAscent variation that causes baseline jumps
+    // when fontBoundingBoxAscent is unavailable (common for loaded web fonts).
+    _fontAscent = 0;
+    _fontDescent = 0;
+    _metricsReady = false;
     _canvasW = 0;
     _canvasH = 0;
     _canvas;
@@ -17671,18 +17826,19 @@ class GlyphSdf {
         this._buffer = options.buffer ?? 8;
         this._radius = options.radius ?? this._buffer;
         this._cutoff = options.cutoff ?? 0.5;
+        this._fontSize = options.fontSize;
         const stylePart = options.fontStyle && options.fontStyle !== 'normal' ? `${options.fontStyle} ` : '';
         const weight = options.fontWeight ?? 'normal';
         this._font = `${stylePart}${weight} ${options.fontSize}px ${options.fontFamily}`;
         if (typeof OffscreenCanvas !== 'undefined') {
             const c = new OffscreenCanvas(1, 1);
             this._canvas = c;
-            this._ctx = c.getContext('2d');
+            this._ctx = c.getContext('2d', { willReadFrequently: true });
         }
         else {
             const c = document.createElement('canvas');
             this._canvas = c;
-            this._ctx = c.getContext('2d');
+            this._ctx = c.getContext('2d', { willReadFrequently: true });
         }
     }
     /**
@@ -17692,7 +17848,28 @@ class GlyphSdf {
      * fresh `Uint8ClampedArray`; the caller may hold a reference to it safely
      * across subsequent `draw()` calls.
      */
+    /**
+     * Ensure font-level ascent/descent are measured. Called once per GlyphSdf
+     * instance — deferred to the first draw() so the canvas context is ready.
+     * Uses `fontBoundingBoxAscent/Descent` when available; falls back to
+     * `actualBoundingBoxAscent/Descent` measured from a reference string that
+     * covers ascenders ('H'), descenders ('g'), and diacritics ('É').
+     * Either way the same values are used for EVERY glyph so all tiles share a
+     * consistent height and a consistent baseline position within the tile.
+     */
+    _ensureFontMetrics() {
+        if (this._metricsReady)
+            return;
+        const ctx = this._ctx;
+        ctx.font = this._font;
+        ctx.textBaseline = 'alphabetic';
+        const m = ctx.measureText('HgjpqyÉÅ');
+        this._fontAscent = Math.max(1, Math.ceil(m.fontBoundingBoxAscent ?? m.actualBoundingBoxAscent ?? this._fontSize * 0.8));
+        this._fontDescent = Math.max(1, Math.ceil(m.fontBoundingBoxDescent ?? m.actualBoundingBoxDescent ?? this._fontSize * 0.2));
+        this._metricsReady = true;
+    }
     draw(char) {
+        this._ensureFontMetrics();
         const ctx = this._ctx;
         const buf = this._buffer;
         // ── Measure ──────────────────────────────────────────────────────────
@@ -17700,20 +17877,20 @@ class GlyphSdf {
         ctx.textBaseline = 'alphabetic';
         const m = ctx.measureText(char);
         const advance = m.width;
+        // Width uses per-glyph actual bounds — each glyph has a different width.
         // Canvas 2D `actualBoundingBoxLeft` is the distance from the text's
         // left-alignment point going LEFT to the left edge of the glyph bounding
         // box. For most LTR characters this is 0; italic fonts may have a small
         // positive value (left overhang).
         const bbLeft = Math.max(0, Math.ceil(m.actualBoundingBoxLeft ?? 0));
         const bbRight = Math.max(0, Math.ceil(m.actualBoundingBoxRight ?? advance));
-        const bbAscent = Math.max(0, Math.ceil(m.fontBoundingBoxAscent ??
-            m.actualBoundingBoxAscent ??
-            0));
-        const bbDescent = Math.max(0, Math.ceil(m.fontBoundingBoxDescent ??
-            m.actualBoundingBoxDescent ??
-            0));
         const glyphWidth = Math.max(1, bbLeft + bbRight);
-        const glyphHeight = Math.max(1, bbAscent + bbDescent);
+        // Height uses font-level metrics — same for every glyph of this font/size
+        // so that all tiles are the same height and the baseline is always at
+        // buf + _fontAscent from the tile top. If per-glyph actualBoundingBoxAscent
+        // were used here instead, different glyphs would have their baselines at
+        // different positions in world space (the visual baseline-jump bug).
+        const glyphHeight = this._fontAscent + this._fontDescent;
         const tileW = glyphWidth + 2 * buf;
         const tileH = glyphHeight + 2 * buf;
         // ── Resize canvas if the tile dimensions changed ───────────────────────
@@ -17726,8 +17903,8 @@ class GlyphSdf {
         // ── Rasterize white glyph on transparent background ───────────────────
         ctx.clearRect(0, 0, tileW, tileH);
         ctx.fillStyle = '#ffffff';
-        // Position so glyph's left edge lands at x = buf and baseline at y = buf + bbAscent.
-        ctx.fillText(char, buf + bbLeft, buf + bbAscent);
+        // Baseline at buf + _fontAscent — consistent across all glyphs.
+        ctx.fillText(char, buf + bbLeft, buf + this._fontAscent);
         const rgba = ctx.getImageData(0, 0, tileW, tileH).data;
         const n = tileW * tileH;
         // ── Grow working arrays lazily ────────────────────────────────────────
@@ -18814,9 +18991,48 @@ class TransformBuffer {
     _frameHash = hashOffset >>> 0;
     _lastCommittedHash = 0;
     _lastCommittedCount = -1;
+    _writeCount = 0;
+    _skippedWriteCount = 0;
+    _uploadCount = 0;
+    _uploadedRecordCount = 0;
     get count() {
         return this._count;
     }
+    /**
+     * Number of transform rows written into the buffer (via {@link write} /
+     * {@link push}) since the last {@link begin}. Internal stat for profiling and
+     * regression guards; does not affect packing.
+     * @internal
+     */
+    get writeCount() {
+        return this._writeCount;
+    }
+    /**
+     * Number of draw commands whose transform write was skipped since the last
+     * {@link begin} — recorded by the backend for renderers that opt out of the
+     * shared transform storage (`_consumesSharedTransform === false`).
+     * @internal
+     */
+    get skippedWriteCount() {
+        return this._skippedWriteCount;
+    }
+    /**
+     * Number of GPU uploads (texture / storage writes) issued for this buffer
+     * since the last {@link begin}. Recorded by the backend at its upload
+     * boundary; an unchanged frame uploads zero times.
+     * @internal
+     */
+    get uploadCount() {
+        return this._uploadCount;
+    }
+    /**
+     * Total transform rows pushed to the GPU across all uploads since the last
+     * {@link begin}.
+     * @internal
+     */
+    get uploadedRecordCount() {
+        return this._uploadedRecordCount;
+    }
     get capacity() {
         return this._data.length / floatsPerSlot;
     }
@@ -18832,6 +19048,10 @@ class TransformBuffer {
         }
         this._count = 0;
         this._frameHash = hashOffset >>> 0;
+        this._writeCount = 0;
+        this._skippedWriteCount = 0;
+        this._uploadCount = 0;
+        this._uploadedRecordCount = 0;
         return this;
     }
     push(transform, tint) {
@@ -18865,6 +19085,27 @@ class TransformBuffer {
         for (let i = 0; i < floatsPerSlot; i++) {
             this._frameHash = this._mix(this._frameHash, this._hashFloat(data[offset + i]));
         }
+        this._writeCount++;
+        return this;
+    }
+    /**
+     * Record that a draw command's transform write was intentionally skipped
+     * because its renderer opts out of the shared transform storage. Counts
+     * toward {@link skippedWriteCount} only — buffer contents are untouched.
+     * @internal
+     */
+    recordSkippedWrite() {
+        this._skippedWriteCount++;
+        return this;
+    }
+    /**
+     * Record a GPU upload of `recordCount` transform rows. Called by the backend
+     * at its upload boundary after committing a snapshot; affects stats only.
+     * @internal
+     */
+    recordUpload(recordCount) {
+        this._uploadCount++;
+        this._uploadedRecordCount += recordCount;
         return this;
     }
     commitSnapshot(minCount = 0) {
@@ -19809,16 +20050,16 @@ const initialIndexCapacity$2 = 192;
 const initialNodeIndexCapacity = 64;
 const defaultVertexColor = 0xffffffff; // white, full alpha
 const maxCustomTextureSlots$2 = 8;
-const transformTextureUnit = 8;
+const transformTextureUnit$1 = 8;
 class WebGl2MeshRenderer extends AbstractWebGl2Renderer {
     _defaultShader = new Shader(vertexSource$3, fragmentSource$3);
     _customShaders = new Map();
     _compatibilityCache = new Map();
     _textureUnitScratch = new Int32Array([0]);
-    _transformUnitScratch = new Int32Array([transformTextureUnit]);
+    _transformUnitScratch = new Int32Array([transformTextureUnit$1]);
     // Pre-built texture-unit indices used for custom-shader sampler bindings;
     // pre-allocated so the per-frame uniform path stays allocation-free.
-    _slotScratches = Array.from({ length: Math.max(transformTextureUnit + 1, maxCustomTextureSlots$2 + 1) }, (_, i) => new Int32Array([i]));
+    _slotScratches = Array.from({ length: Math.max(transformTextureUnit$1 + 1, maxCustomTextureSlots$2 + 1) }, (_, i) => new Int32Array([i]));
     _vertexCapacity = initialVertexCapacity$2;
     _indexCapacity = initialIndexCapacity$2;
     _nodeIndexCapacity = initialNodeIndexCapacity;
@@ -19972,9 +20213,9 @@ class WebGl2MeshRenderer extends AbstractWebGl2Renderer {
         this._packIndices(draw.mesh, 0);
         const nodeIndex = draw.command?.nodeIndex ?? 0;
         if (draw.command === null) {
-            backend._prepareDrawCommand({
-                ...this._createSyntheticCommand(draw.mesh, nodeIndex),
-            });
+            // The synthetic, non-plan path does not arrive through a render-group
+            // upload boundary, so write its transform into the shared buffer directly.
+            backend._writeTransformCommand(this._createSyntheticCommand(draw.mesh, nodeIndex));
         }
         this._nodeIndexData[0] = nodeIndex >>> 0;
         backend.bindVertexArrayObject(connection.dynamicVao);
@@ -20045,7 +20286,7 @@ class WebGl2MeshRenderer extends AbstractWebGl2Renderer {
             shader.getUniform('u_projection').setValue(backend.view.getTransform().toArray(false));
         }
         if (shader.uniforms.has('u_transforms')) {
-            backend.bindTransformBufferTexture(transformTextureUnit, maxNodeIndex + 1);
+            backend.bindTransformBufferTexture(transformTextureUnit$1, maxNodeIndex + 1);
             shader.getUniform('u_transforms').setValue(this._transformUnitScratch);
         }
         if (shader.uniforms.has('u_texture')) {
@@ -20429,6 +20670,14 @@ const wordsPerInstance$2 = instanceStrideBytes$3 / Uint32Array.BYTES_PER_ELEMENT
 const indicesPerQuad = 6;
 const quadIndices$1 = new Uint16Array([0, 1, 2, 0, 2, 3]);
 class WebGl2ParticleRenderer extends AbstractWebGl2Renderer {
+    /**
+     * The particle system's transform is bound as a `u_systemTransform` uniform and
+     * each particle is positioned system-locally, so this renderer never reads the
+     * shared {@link TransformBuffer}; the render-group upload boundary skips writing
+     * transform records for particle draws.
+     * @internal
+     */
+    _consumesSharedTransform = false;
     _shader;
     _batchSize;
     _instanceData;
@@ -20796,10 +21045,15 @@ class WebGl2PassCoordinator {
  * `WebGl2SpriteRenderer` pairs {@link spriteVertexGlsl} with the material's
  * fragment (ignoring any author-supplied `glsl.vertex`), and
  * `WebGpuSpriteRenderer` prepends {@link spriteVertexWgsl} to the material's
- * fragment WGSL. Both pin the per-instance attribute locations 0–5 and the
+ * fragment WGSL. Both pin the per-instance attribute locations and the
  * projection binding exactly as the default sprite path does, so a custom
  * material keeps the single `drawArraysInstanced` / `drawIndexed` batch.
  *
+ * Both paths (locations 0, 3, 4, 5, 6) fetch each instance's world transform
+ * from the shared transform storage keyed by `a_nodeIndex` / `nodeIndex`: the
+ * WebGL2 path samples the `u_transforms` texture, the WGSL path reads the
+ * `transforms` storage buffer (group(0) binding(1)).
+ *
  * A custom fragment receives the interpolated `v_texcoord` and premultiplied
  * `v_color`, plus the per-batch base texture bound as `u_texture` (WebGL2 unit 0
  * / WGSL group(1) binding 0). Material uniforms and additional textures bind on
@@ -20818,13 +21072,13 @@ precision highp int;
 // to the per-instance buffer; gl_VertexID 0..3 selects which corner of the
 // quad this invocation is computing.
 layout(location = 0) in vec4 a_localBounds;     // left, top, right, bottom (local space)
-layout(location = 1) in vec3 a_transformAB;     // a, b, x — first row of 2D affine
-layout(location = 2) in vec3 a_transformCD;     // c, d, y — second row
 layout(location = 3) in vec4 a_uvBounds;        // uMin, vMin, uMax, vMax (normalised, already flipY-swapped)
 layout(location = 4) in vec4 a_color;           // RGBA tint
 layout(location = 5) in uint a_textureSlot;
+layout(location = 6) in uint a_nodeIndex;       // row into the shared transform buffer
 
 uniform mat3 u_projection;
+uniform sampler2D u_transforms;                 // shared per-frame transform buffer (3 texels/row)
 
 out vec2 v_texcoord;
 out vec4 v_color;
@@ -20839,8 +21093,14 @@ void main(void) {
     float localX = (cornerX == 0) ? a_localBounds.x : a_localBounds.z;
     float localY = (cornerY == 0) ? a_localBounds.y : a_localBounds.w;
 
-    float worldX = (a_transformAB.x * localX) + (a_transformAB.y * localY) + a_transformAB.z;
-    float worldY = (a_transformCD.x * localX) + (a_transformCD.y * localY) + a_transformCD.z;
+    // Fetch the per-instance world transform from the shared buffer (row =
+    // a_nodeIndex): texel 0 = (a, b, c, d), texel 1 = (tx, ty, 0, 0).
+    int row = int(a_nodeIndex);
+    vec4 m0 = texelFetch(u_transforms, ivec2(0, row), 0);
+    vec4 m1 = texelFetch(u_transforms, ivec2(1, row), 0);
+
+    float worldX = (m0.x * localX) + (m0.y * localY) + m1.x;
+    float worldY = (m0.z * localX) + (m0.w * localY) + m1.y;
 
     gl_Position = vec4((u_projection * vec3(worldX, worldY, 1.0)).xy, 0.0, 1.0);
 
@@ -20855,11 +21115,11 @@ void main(void) {
 /**
  * WGSL vertex stage + shared bindings for the custom sprite-material path.
  * Prepend to a material's fragment WGSL: it declares the per-instance
- * `VertexInput` (locations 0–5), the `VertexOutput` a custom `@fragment`
- * consumes, the group(0) projection uniform, the group(1) base texture and
- * sampler (`u_texture` / `u_sampler`), and the `vertexMain` entry point. The
- * fragment author adds their group(2) bindings and a `fragmentMain` reading
- * `VertexOutput`.
+ * `VertexInput` (locations 0, 3, 4, 5, 6), the `VertexOutput` a custom
+ * `@fragment` consumes, the group(0) projection uniform + shared transform
+ * storage buffer, the group(1) base texture and sampler (`u_texture` /
+ * `u_sampler`), and the `vertexMain` entry point. The fragment author adds their
+ * group(2) bindings and a `fragmentMain` reading `VertexOutput`.
  * @internal
  */
 const spriteVertexWgsl = `
@@ -20867,18 +21127,24 @@ struct ProjectionUniforms {
     matrix: mat4x4<f32>,
 };
 
+struct TransformSlot {
+    m0: vec4<f32>,
+    m1: vec4<f32>,
+    m2: vec4<f32>,
+};
+
 @group(0) @binding(0) var<uniform> projection: ProjectionUniforms;
+@group(0) @binding(1) var<storage, read> transforms: array<TransformSlot>;
 
 @group(1) @binding(0) var u_texture: texture_2d<f32>;
 @group(1) @binding(1) var u_sampler: sampler;
 
 struct VertexInput {
     @location(0) localBounds: vec4<f32>,
-    @location(1) transformAB: vec3<f32>,
-    @location(2) transformCD: vec3<f32>,
     @location(3) uvBounds: vec4<f32>,
     @location(4) color: vec4<f32>,
     @location(5) textureSlot: u32,
+    @location(6) nodeIndex: u32,
 };
 
 struct VertexOutput {
@@ -20897,8 +21163,12 @@ fn vertexMain(input: VertexInput, @builtin(vertex_index) vid: u32) -> VertexOutp
     let localX = select(input.localBounds.x, input.localBounds.z, cornerX == 1u);
     let localY = select(input.localBounds.y, input.localBounds.w, cornerY == 1u);
 
-    let worldX = input.transformAB.x * localX + input.transformAB.y * localY + input.transformAB.z;
-    let worldY = input.transformCD.x * localX + input.transformCD.y * localY + input.transformCD.z;
+    // Fetch this instance's world transform from the shared storage buffer,
+    // keyed by nodeIndex: m0 = (a, b, c, d), m1 = (tx, ty, 0, 0). (m2 carries the
+    // node tint, unused here — the sprite keeps its own per-instance color.)
+    let slot = transforms[input.nodeIndex];
+    let worldX = slot.m0.x * localX + slot.m0.y * localY + slot.m1.x;
+    let worldY = slot.m0.z * localX + slot.m0.w * localY + slot.m1.y;
 
     output.position = projection.matrix * vec4<f32>(worldX, worldY, 0.0, 1.0);
 
@@ -20914,7 +21184,7 @@ fn vertexMain(input: VertexInput, @builtin(vertex_index) vid: u32) -> VertexOutp
 
 var fragmentSource$1 = "#version 300 es\nprecision lowp float;\nprecision lowp int;\n\n// Multi-texture sprite batching: up to 8 textures bound per draw call,\n// each fragment selects its source via a flat-interpolated slot index.\n//\n// GLSL ES 3.0 forbids non-constant array-of-sampler indexing unless the\n// expression is dynamically uniform — which a per-vertex slot is not\n// once different triangles in the same batch carry different slots. The\n// if/else chain below dispatches statically and dodges that constraint.\n\nuniform sampler2D u_texture0;\nuniform sampler2D u_texture1;\nuniform sampler2D u_texture2;\nuniform sampler2D u_texture3;\nuniform sampler2D u_texture4;\nuniform sampler2D u_texture5;\nuniform sampler2D u_texture6;\nuniform sampler2D u_texture7;\n\nin vec2 v_texcoord;\nin vec4 v_color;\nflat in uint v_textureSlot;\n\nlayout(location = 0) out vec4 fragColor;\n\nvoid main(void) {\n    vec4 sampleColor;\n\n    if (v_textureSlot == 0u) {\n        sampleColor = texture(u_texture0, v_texcoord);\n    } else if (v_textureSlot == 1u) {\n        sampleColor = texture(u_texture1, v_texcoord);\n    } else if (v_textureSlot == 2u) {\n        sampleColor = texture(u_texture2, v_texcoord);\n    } else if (v_textureSlot == 3u) {\n        sampleColor = texture(u_texture3, v_texcoord);\n    } else if (v_textureSlot == 4u) {\n        sampleColor = texture(u_texture4, v_texcoord);\n    } else if (v_textureSlot == 5u) {\n        sampleColor = texture(u_texture5, v_texcoord);\n    } else if (v_textureSlot == 6u) {\n        sampleColor = texture(u_texture6, v_texcoord);\n    } else {\n        sampleColor = texture(u_texture7, v_texcoord);\n    }\n\n    fragColor = sampleColor * v_color;\n}\n";
 
-var vertexSource$1 = "#version 300 es\nprecision lowp float;\nprecision lowp int;\n\n// Per-instance attributes (divisor = 1). Each Sprite contributes one entry\n// to the per-instance buffer; gl_VertexID 0..3 selects which corner of the\n// quad this invocation is computing.\nlayout(location = 0) in vec4 a_localBounds;     // left, top, right, bottom (local space)\nlayout(location = 1) in vec3 a_transformAB;     // a, b, x — first row of 2D affine\nlayout(location = 2) in vec3 a_transformCD;     // c, d, y — second row\nlayout(location = 3) in vec4 a_uvBounds;        // uMin, vMin, uMax, vMax (normalised, already flipY-swapped)\nlayout(location = 4) in vec4 a_color;           // RGBA tint\nlayout(location = 5) in uint a_textureSlot;\n\nuniform mat3 u_projection;\n\nout vec2 v_texcoord;\nout vec4 v_color;\nflat out uint v_textureSlot;\n\nvoid main(void) {\n    // gl_VertexID 0..3 → corner: 0=TL, 1=TR, 2=BL, 3=BR (TRIANGLE_STRIP order)\n    int vid = gl_VertexID;\n    int cornerX = vid & 1;\n    int cornerY = (vid >> 1) & 1;\n\n    // Local-space corner: pick from the bounds rectangle.\n    float localX = (cornerX == 0) ? a_localBounds.x : a_localBounds.z;\n    float localY = (cornerY == 0) ? a_localBounds.y : a_localBounds.w;\n\n    // Apply the per-instance affine transform: world = M * (localX, localY, 1)\n    float worldX = (a_transformAB.x * localX) + (a_transformAB.y * localY) + a_transformAB.z;\n    float worldY = (a_transformCD.x * localX) + (a_transformCD.y * localY) + a_transformCD.z;\n\n    gl_Position = vec4((u_projection * vec3(worldX, worldY, 1.0)).xy, 0.0, 1.0);\n\n    // UV: pick from the bounds rectangle. The CPU pre-swaps Y bounds when\n    // the texture is flipY, so the shader doesn't have to know.\n    float u = (cornerX == 0) ? a_uvBounds.x : a_uvBounds.z;\n    float v = (cornerY == 0) ? a_uvBounds.y : a_uvBounds.w;\n    v_texcoord = vec2(u, v);\n\n    v_color = vec4(a_color.rgb * a_color.a, a_color.a);\n    v_textureSlot = a_textureSlot;\n}\n";
+var vertexSource$1 = "#version 300 es\nprecision lowp float;\nprecision highp int;\n\n// Per-instance attributes (divisor = 1). Each Sprite contributes one entry\n// to the per-instance buffer; gl_VertexID 0..3 selects which corner of the\n// quad this invocation is computing.\nlayout(location = 0) in vec4 a_localBounds;     // left, top, right, bottom (local space)\nlayout(location = 3) in vec4 a_uvBounds;        // uMin, vMin, uMax, vMax (normalised, already flipY-swapped)\nlayout(location = 4) in vec4 a_color;           // RGBA tint\nlayout(location = 5) in uint a_textureSlot;\nlayout(location = 6) in uint a_nodeIndex;       // row into the shared transform buffer\n\nuniform mat3 u_projection;\nuniform sampler2D u_transforms;                 // shared per-frame transform buffer (3 texels/row)\n\nout vec2 v_texcoord;\nout vec4 v_color;\nflat out uint v_textureSlot;\n\nvoid main(void) {\n    // gl_VertexID 0..3 → corner: 0=TL, 1=TR, 2=BL, 3=BR (TRIANGLE_STRIP order)\n    int vid = gl_VertexID;\n    int cornerX = vid & 1;\n    int cornerY = (vid >> 1) & 1;\n\n    // Local-space corner: pick from the bounds rectangle.\n    float localX = (cornerX == 0) ? a_localBounds.x : a_localBounds.z;\n    float localY = (cornerY == 0) ? a_localBounds.y : a_localBounds.w;\n\n    // Fetch the world transform for this instance from the shared buffer,\n    // keyed by a_nodeIndex. Row layout: texel 0 = (a, b, c, d),\n    // texel 1 = (tx, ty, 0, 0). (texel 2 carries tint, unused here — the\n    // sprite keeps its own per-instance a_color.)\n    int row = int(a_nodeIndex);\n    vec4 m0 = texelFetch(u_transforms, ivec2(0, row), 0); // a, b, c, d\n    vec4 m1 = texelFetch(u_transforms, ivec2(1, row), 0); // tx, ty, 0, 0\n\n    // world = M * (localX, localY, 1)\n    float worldX = (m0.x * localX) + (m0.y * localY) + m1.x;\n    float worldY = (m0.z * localX) + (m0.w * localY) + m1.y;\n\n    gl_Position = vec4((u_projection * vec3(worldX, worldY, 1.0)).xy, 0.0, 1.0);\n\n    // UV: pick from the bounds rectangle. The CPU pre-swaps Y bounds when\n    // the texture is flipY, so the shader doesn't have to know.\n    float u = (cornerX == 0) ? a_uvBounds.x : a_uvBounds.z;\n    float v = (cornerY == 0) ? a_uvBounds.y : a_uvBounds.w;\n    v_texcoord = vec2(u, v);\n\n    v_color = vec4(a_color.rgb * a_color.a, a_color.a);\n    v_textureSlot = a_textureSlot;\n}\n";
 
 /**
  * Instanced sprite renderer for WebGL2.
@@ -20924,21 +21194,23 @@ var vertexSource$1 = "#version 300 es\nprecision lowp float;\nprecision lowp int
  * the quad each invocation is computing. All per-sprite data lives in a
  * single per-instance buffer (divisor = 1).
  *
- * Per-instance layout (56 bytes per sprite, 6 attributes):
+ * Per-instance layout (36 bytes per sprite, 5 attributes):
  * ```
  *   localBounds    f32x4       (offset  0, 16 bytes)  — left, top, right, bottom
- *   transformAB    f32x3       (offset 16, 12 bytes)  — first  row of 2D affine
- *   transformCD    f32x3       (offset 28, 12 bytes)  — second row of 2D affine
- *   uvBounds       u16x4 norm  (offset 40,  8 bytes)  — uMin, vMin, uMax, vMax
- *   color          u8x4  norm  (offset 48,  4 bytes)  — RGBA tint
- *   textureSlot    u32         (offset 52,  4 bytes)  — multi-texture slot
+ *   uvBounds       u16x4 norm  (offset 16,  8 bytes)  — uMin, vMin, uMax, vMax
+ *   color          u8x4  norm  (offset 24,  4 bytes)  — RGBA tint
+ *   textureSlot    u32         (offset 28,  4 bytes)  — multi-texture slot
+ *   nodeIndex      u32         (offset 32,  4 bytes)  — row into the shared TransformBuffer
  * ```
  *
- * vs. the previous per-vertex layout (80 bytes per quad), this saves
- * roughly 30% bandwidth and ~75% of the CPU writes per sprite — the
- * vertex shader expands one instance into four corners on the GPU
- * instead of the CPU duplicating the same color/slot/transform across
- * four vertex entries.
+ * The per-instance world transform no longer lives in this buffer: it is
+ * fetched in the vertex shader from the shared {@link TransformBuffer}
+ * texture (`u_transforms`) keyed by `a_nodeIndex`, exactly like the mesh
+ * renderer. The render-group upload boundary (PR #44) already packs every
+ * draw command's transform into that buffer at its stable `nodeIndex`, so the
+ * sprite just reads it back instead of re-packing 24 bytes of affine rows per
+ * instance. vs. the previous per-vertex layout (80 bytes per quad), the
+ * vertex shader still expands one instance into four corners on the GPU.
  *
  * # Default vs custom-material path
  *
@@ -20952,7 +21224,10 @@ var vertexSource$1 = "#version 300 es\nprecision lowp float;\nprecision lowp int
  * breaks on material instance, base texture, blend mode, or buffer capacity.
  */
 const maxBatchTextures$1 = 8;
-const instanceStrideBytes$2 = 56;
+// Sprite base textures occupy units 0..7; the shared transform buffer texture
+// binds on unit 8, matching the mesh renderer's convention.
+const transformTextureUnit = 8;
+const instanceStrideBytes$2 = 36;
 const wordsPerInstance$1 = instanceStrideBytes$2 / Uint32Array.BYTES_PER_ELEMENT;
 class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
     _shader;
@@ -20969,9 +21244,14 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
     // Texture-unit index scratches reused for sampler-uniform binds so the
     // per-batch path stays allocation-free.
     _slotScratches = Array.from({ length: maxBatchTextures$1 }, (_, i) => new Int32Array([i]));
+    // Pinned unit index for the shared transform buffer sampler.
+    _transformUnitScratch = new Int32Array([transformTextureUnit]);
     _currentMaterial = null;
     _currentBaseTexture = null;
     _instanceCount = 0;
+    // Highest transform-buffer row referenced by the pending batch; drives the
+    // minimum row count uploaded for the transform texture at flush time.
+    _maxNodeIndex = 0;
     _currentBlendMode = null;
     _currentView = null;
     _currentViewId = -1;
@@ -20993,11 +21273,17 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
         }
         const backend = this.getBackend();
         const material = sprite.material;
+        // The transform lives in the shared buffer, keyed by the draw command's
+        // stable nodeIndex (already packed at the render-group upload boundary).
+        // A direct, non-plan `backend.draw(sprite)` has no command — push the
+        // sprite's transform into the buffer and use the freshly-allocated slot.
+        const command = backend.activeDrawCommand;
+        const nodeIndex = command !== null ? command.nodeIndex : backend._pushTransform(sprite);
         if (material === null) {
-            this._renderDefault(sprite, texture, backend);
+            this._renderDefault(sprite, texture, backend, nodeIndex);
         }
         else {
-            this._renderCustom(sprite, texture, material, backend);
+            this._renderCustom(sprite, texture, material, backend, nodeIndex);
         }
         return this;
     }
@@ -21007,6 +21293,7 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
         const vao = this._vao;
         const connection = this._connection;
         if (this._instanceCount === 0 || backend === null || instanceBuffer === null || vao === null || connection === null) {
+            this._maxNodeIndex = 0;
             this._resetSlots();
             return;
         }
@@ -21034,6 +21321,13 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
             }
             this._bindCustomUniforms(shader, material, backend);
         }
+        // Bind the shared transform buffer texture (one row per nodeIndex) on the
+        // dedicated unit and point the sampler at it. Done for both the default and
+        // custom programs — both fetch the world transform via a_nodeIndex.
+        backend.bindTransformBufferTexture(transformTextureUnit, this._maxNodeIndex + 1);
+        if (shader.uniforms.has('u_transforms')) {
+            shader.getUniform('u_transforms').setValue(this._transformUnitScratch);
+        }
         shader.sync();
         backend.bindVertexArrayObject(vao);
         instanceBuffer.upload(this._instanceFloat32.subarray(0, this._instanceCount * wordsPerInstance$1));
@@ -21041,6 +21335,7 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
         backend.stats.batches++;
         backend.stats.drawCalls++;
         this._instanceCount = 0;
+        this._maxNodeIndex = 0;
         this._resetSlots();
     }
     onConnect(backend) {
@@ -21051,11 +21346,10 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
         this._shader.sync();
         this._vao = new WebGl2VertexArrayObject(RenderingPrimitives.TriangleStrip)
             .addAttribute(this._instanceBuffer, this._shader.getAttribute('a_localBounds'), gl.FLOAT, false, instanceStrideBytes$2, 0, false, 1)
-            .addAttribute(this._instanceBuffer, this._shader.getAttribute('a_transformAB'), gl.FLOAT, false, instanceStrideBytes$2, 16, false, 1)
-            .addAttribute(this._instanceBuffer, this._shader.getAttribute('a_transformCD'), gl.FLOAT, false, instanceStrideBytes$2, 28, false, 1)
-            .addAttribute(this._instanceBuffer, this._shader.getAttribute('a_uvBounds'), gl.UNSIGNED_SHORT, true, instanceStrideBytes$2, 40, false, 1)
-            .addAttribute(this._instanceBuffer, this._shader.getAttribute('a_color'), gl.UNSIGNED_BYTE, true, instanceStrideBytes$2, 48, false, 1)
-            .addAttribute(this._instanceBuffer, this._shader.getAttribute('a_textureSlot'), gl.UNSIGNED_INT, false, instanceStrideBytes$2, 52, true, 1)
+            .addAttribute(this._instanceBuffer, this._shader.getAttribute('a_uvBounds'), gl.UNSIGNED_SHORT, true, instanceStrideBytes$2, 16, false, 1)
+            .addAttribute(this._instanceBuffer, this._shader.getAttribute('a_color'), gl.UNSIGNED_BYTE, true, instanceStrideBytes$2, 24, false, 1)
+            .addAttribute(this._instanceBuffer, this._shader.getAttribute('a_textureSlot'), gl.UNSIGNED_INT, false, instanceStrideBytes$2, 28, true, 1)
+            .addAttribute(this._instanceBuffer, this._shader.getAttribute('a_nodeIndex'), gl.UNSIGNED_INT, false, instanceStrideBytes$2, 32, true, 1)
             .connect(this._createVaoRuntime(this._connection));
         // Pin the per-slot sampler uniforms to texture units 0..N-1.
         const samplerUnit = new Int32Array(1);
@@ -21081,13 +21375,14 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
         this._currentView = null;
         this._currentViewId = -1;
         this._instanceCount = 0;
+        this._maxNodeIndex = 0;
     }
     destroy() {
         this.disconnect();
         this._shader.destroy();
     }
     /** Default multi-texture path: rotate the base texture through 8 slots. */
-    _renderDefault(sprite, texture, backend) {
+    _renderDefault(sprite, texture, backend, nodeIndex) {
         const blendMode = sprite.blendMode;
         const batchFull = this._instanceCount >= this._batchSize;
         const blendModeChanged = blendMode !== this._currentBlendMode;
@@ -21109,11 +21404,11 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
             this._activeTextures[slot] = texture;
             backend.bindTexture(texture, slot);
         }
-        this._packInstance(sprite, texture, slot);
+        this._packInstance(sprite, texture, slot, nodeIndex);
         this._instanceCount++;
     }
     /** Custom-material path: single base texture on unit 0, instanced. */
-    _renderCustom(sprite, texture, material, backend) {
+    _renderCustom(sprite, texture, material, backend, nodeIndex) {
         // The material owns its blend mode; the sprite's own blendMode overrides it
         // when set away from the default (Normal).
         const blendMode = sprite.blendMode === BlendModes.Normal ? material.blendMode : sprite.blendMode;
@@ -21131,10 +21426,10 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
         this._currentMaterial = material;
         this._currentBaseTexture = texture;
         // textureSlot word is unused by custom fragments (base binds to unit 0).
-        this._packInstance(sprite, texture, 0);
+        this._packInstance(sprite, texture, 0, nodeIndex);
         this._instanceCount++;
     }
-    _packInstance(sprite, texture, slot) {
+    _packInstance(sprite, texture, slot, nodeIndex) {
         const offset = this._instanceCount * wordsPerInstance$1;
         const f32 = this._instanceFloat32;
         const u32 = this._instanceUint32;
@@ -21144,15 +21439,7 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
         f32[offset + 1] = bounds.top;
         f32[offset + 2] = bounds.right;
         f32[offset + 3] = bounds.bottom;
-        // transform rows (offset 4..6 = AB, 7..9 = CD)
-        const transform = sprite.getGlobalTransform();
-        f32[offset + 4] = transform.a;
-        f32[offset + 5] = transform.b;
-        f32[offset + 6] = transform.x;
-        f32[offset + 7] = transform.c;
-        f32[offset + 8] = transform.d;
-        f32[offset + 9] = transform.y;
-        // uvBounds at offset 10 — 8 bytes = 2 u32 slots, normalised u16x4.
+        // uvBounds at offset 4 — 8 bytes = 2 u32 slots, normalised u16x4.
         // Pack (uMin, vMin, uMax, vMax) into two uint32s, with flipY swap
         // applied at pack time so the shader can stay flip-agnostic.
         const frame = sprite.textureFrame;
@@ -21165,12 +21452,18 @@ class WebGl2SpriteRenderer extends AbstractWebGl2Renderer {
         const vMaxRaw = ((frame.bottom / texHeight) * 0xffff) & 0xffff;
         const vMin = texture.flipY ? vMaxRaw : vMinRaw;
         const vMax = texture.flipY ? vMinRaw : vMaxRaw;
-        u32[offset + 10] = uMin | (vMin << 16);
-        u32[offset + 11] = uMax | (vMax << 16);
-        // color (u8x4 packed) at word 12
-        u32[offset + 12] = sprite.tint.toRgba();
-        // textureSlot (u32) at word 13
-        u32[offset + 13] = slot;
+        u32[offset + 4] = uMin | (vMin << 16);
+        u32[offset + 5] = uMax | (vMax << 16);
+        // color (u8x4 packed) at word 6
+        u32[offset + 6] = sprite.tint.toRgba();
+        // textureSlot (u32) at word 7
+        u32[offset + 7] = slot;
+        // nodeIndex (u32) at word 8 — row into the shared transform buffer.
+        const node = nodeIndex >>> 0;
+        u32[offset + 8] = node;
+        if (node > this._maxNodeIndex) {
+            this._maxNodeIndex = node;
+        }
     }
     _getOrCreateCustomShader(material, gl) {
         const cached = this._customShaders.get(material);
@@ -21499,7 +21792,7 @@ class WebGl2StencilClipper {
 
 var textVertSource = "#version 300 es\nprecision highp float;\n\nlayout(location = 0) in vec2  a_position;\nlayout(location = 1) in vec2  a_texcoord;\nlayout(location = 2) in float a_nodeIndex;\n\nuniform mat3 u_projection;\nuniform sampler2D u_nodeData;\n\nflat out int  v_nodeIndex;\n     out vec2 v_texcoord;\n     out vec2 v_gradUV;\n\nvoid main(void) {\n    int ni = int(a_nodeIndex);\n\n    // texel 0: (a, c, 0, tx)   texel 1: (b, d, 0, ty)\n    vec4 t0 = texelFetch(u_nodeData, ivec2(0, ni), 0);\n    vec4 t1 = texelFetch(u_nodeData, ivec2(1, ni), 0);\n\n    // Reconstruct column-major mat3 from stored components\n    mat3 xf = mat3(\n        t0.x, t0.y, 0.0,   // col 0: (a, c, 0)\n        t1.x, t1.y, 0.0,   // col 1: (b, d, 0)\n        t0.w, t1.w, 1.0    // col 2: (tx, ty, 1)\n    );\n\n    gl_Position = vec4((u_projection * xf * vec3(a_position, 1.0)).xy, 0.0, 1.0);\n    v_texcoord  = a_texcoord;\n    v_nodeIndex = ni;\n\n    // texel 9: (minX, minY, width, height) — text block bounds in local space.\n    // Normalise a_position into [0,1] so fragment shaders can interpolate\n    // gradients across the whole block rather than individual atlas UVs.\n    vec4 tBounds = texelFetch(u_nodeData, ivec2(9, ni), 0);\n    vec2 bSize   = tBounds.zw;\n    v_gradUV = (bSize.x > 0.0 && bSize.y > 0.0)\n        ? clamp((a_position - tBounds.xy) / bSize, 0.0, 1.0)\n        : vec2(0.0);\n}\n";
 
-var textColorFragSource = "#version 300 es\nprecision mediump float;\n\nuniform sampler2D u_texture;   // RGBA colour-font / emoji atlas\nuniform sampler2D u_nodeData;  // RGBA32F per-node data\n\nflat in int  v_nodeIndex;\n     in vec2 v_texcoord;\n\nlayout(location = 0) out vec4 fragColor;\n\nvoid main(void) {\n  // texel 2: fillColor (tint multiplier; (1,1,1,1) = no tint)\n  vec4 tint   = texelFetch(u_nodeData, ivec2(2, v_nodeIndex), 0);\n  vec4 sample = texture(u_texture, v_texcoord);\n  fragColor   = sample * tint;\n}\n";
+var textColorFragSource = "#version 300 es\nprecision mediump float;\n\nuniform sampler2D u_texture;   // RGBA colour-font / emoji atlas\nuniform sampler2D u_nodeData;  // RGBA32F per-node data\n\nflat in int  v_nodeIndex;\n     in vec2 v_texcoord;\n\nlayout(location = 0) out vec4 fragColor;\n\nvoid main(void) {\n  // texel 2: fillColor (tint multiplier; (1,1,1,1) = no tint)\n  vec4 tint   = texelFetch(u_nodeData, ivec2(2, v_nodeIndex), 0);\n  vec4 texel  = texture(u_texture, v_texcoord);\n  fragColor   = texel * tint;\n}\n";
 
 var textMsdfFragSource = "#version 300 es\nprecision mediump float;\n\nuniform sampler2D u_texture;   // RGB MSDF atlas\nuniform sampler2D u_nodeData;  // RGBA32F per-node data (see WebGl2TextRenderer)\nuniform float     u_pageSize;  // atlas page size in px (for shadow UV conversion)\n\nflat in int  v_nodeIndex;\n     in vec2 v_texcoord;\n     in vec2 v_gradUV;\n\nlayout(location = 0) out vec4 fragColor;\n\nfloat median(float r, float g, float b) {\n  return max(min(r, g), min(max(r, g), b));\n}\n\nvoid main(void) {\n  int ni = v_nodeIndex;\n\n  // Same node data layout as text-sdf.frag\n  vec4 tFill    = texelFetch(u_nodeData, ivec2(2, ni), 0);\n  vec4 tOutline = texelFetch(u_nodeData, ivec2(3, ni), 0);\n  vec4 tParams  = texelFetch(u_nodeData, ivec2(4, ni), 0); // (outlineMin, shadowAlpha, softness, gradientEnabled)\n  vec4 tShadow  = texelFetch(u_nodeData, ivec2(5, ni), 0);\n  vec4 tShadow2 = texelFetch(u_nodeData, ivec2(6, ni), 0); // (shadowOffX_px, shadowOffY_px, gradientVertical, 0)\n  vec4 tGradTop = texelFetch(u_nodeData, ivec2(7, ni), 0);\n  vec4 tGradBot = texelFetch(u_nodeData, ivec2(8, ni), 0);\n\n  float outlineMin   = tParams.x;\n  float shadowAlpha  = tParams.y;\n  float soft         = max(tParams.z, 0.001);\n  float gradEnabled  = tParams.w;\n  vec2  shadowOffset = tShadow2.xy / u_pageSize;\n  float gradVertical = tShadow2.z;\n\n  vec3  msd  = texture(u_texture, v_texcoord).rgb;\n  float sd   = median(msd.r, msd.g, msd.b);\n  float fill = smoothstep(0.5 - soft, 0.5 + soft, sd);\n\n  float outline = outlineMin < 0.5\n    ? smoothstep(outlineMin - soft, outlineMin + soft, sd) * (1.0 - fill)\n    : 0.0;\n\n  vec3  shadowMsd = texture(u_texture, v_texcoord - shadowOffset).rgb;\n  float shadowSd  = median(shadowMsd.r, shadowMsd.g, shadowMsd.b);\n  float shadow    = smoothstep(0.5 - soft, 0.5 + soft, shadowSd)\n                    * shadowAlpha * (1.0 - fill) * (1.0 - outline);\n\n  vec4 fillColor;\n  if (gradEnabled > 0.5) {\n    float t = gradVertical > 0.5 ? v_gradUV.y : v_gradUV.x;\n    fillColor = mix(tGradBot, tGradTop, t);\n  } else {\n    fillColor = tFill;\n  }\n\n  fragColor = fillColor * fill\n            + tOutline  * outline\n            + tShadow   * shadow;\n}\n";
 
@@ -21549,6 +21842,13 @@ const initialNodeCapacity$1 = 32;
  * same shader type and atlas page are drawn in a single `drawElements` call.
  */
 class WebGl2TextRenderer extends AbstractWebGl2Renderer {
+    /**
+     * Text packs its world transform into its own per-node data texture and never
+     * reads the shared {@link TransformBuffer}, so the render-group upload boundary
+     * skips writing transform records for text draws.
+     * @internal
+     */
+    _consumesSharedTransform = false;
     _sdfShader = new Shader(textVertSource, textSdfFragSource);
     _msdfShader = new Shader(textVertSource, textMsdfFragSource);
     _colorShader = new Shader(textVertSource, textColorFragSource);
@@ -22138,11 +22438,59 @@ class WebGl2Backend {
         this._drawPlanDepth++;
     }
     /** @internal */
+    _prepareRenderGroupUpload(group) {
+        // Pack the whole render group's world transforms (+ tint) into the shared
+        // transform buffer at the group's upload boundary, keyed by each draw
+        // command's stable nodeIndex. Every draw the player will submit for this
+        // group is covered here, before the group's first draw — so the per-draw
+        // write previously done in `_prepareDrawCommand` is no longer needed and
+        // the buffer is filled one contiguous group slice at a time.
+        //
+        // Renderers that pack their own per-node data (Text, Particle) never read
+        // the shared buffer, so their commands are skipped — no consuming draw ever
+        // references their slots (nodeIndex is unique per command).
+        const instructions = group.instructions;
+        for (let i = 0; i < instructions.length; i++) {
+            const command = instructions[i];
+            if (drawCommandUsesSharedTransform(command, this)) {
+                this._writeTransformCommand(command);
+            }
+            else {
+                this._transformBuffer.recordSkippedWrite();
+            }
+        }
+    }
+    /** @internal */
     _prepareDrawCommand(command) {
+        // Transform packing now happens at the render-group upload boundary
+        // (`_prepareRenderGroupUpload`); this hook only tracks the active draw so
+        // the mesh renderer can read the current command's nodeIndex.
         this._activeDrawCommand = command;
+    }
+    /**
+     * Write a single draw command's world transform (+ tint) into the shared
+     * transform buffer at its `nodeIndex` slot. Used for draws that do not arrive
+     * through a render-group upload boundary — currently the mesh renderer's
+     * synthetic, non-plan instanced path.
+     * @internal
+     */
+    _writeTransformCommand(command) {
         const drawable = command.drawable;
         this._transformBuffer.write(command.nodeIndex, drawable.getGlobalTransform(), drawable.tint);
     }
+    /**
+     * Append a drawable's world transform (+ tint) to the shared transform buffer
+     * and return the slot it was written to. Used by instanced renderers for draws
+     * that arrive without a render-group upload boundary — i.e. a direct
+     * `backend.draw(drawable)` outside the plan player (`activeDrawCommand === null`),
+     * where no stable `nodeIndex` was assigned. Unlike {@link _writeTransformCommand}
+     * (fixed slot) this allocates a fresh slot, so a batch of synthetic draws does
+     * not collide on a single row.
+     * @internal
+     */
+    _pushTransform(drawable) {
+        return this._transformBuffer.push(drawable.getGlobalTransform(), drawable.tint);
+    }
     /** @internal */
     _endDrawPlan() {
         this._activeDrawCommand = null;
@@ -22393,6 +22741,7 @@ class WebGl2Backend {
         }
         if (snapshot.changed || snapshot.count !== this._transformTextureCount || snapshot.hash !== this._transformTextureHash) {
             nextTransformTexture.commitRect(0, 0, 3, snapshot.count);
+            this._transformBuffer.recordUpload(snapshot.count);
             this._transformTextureHash = snapshot.hash;
             this._transformTextureCount = snapshot.count;
         }
@@ -23804,16 +24153,6 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         if (customShader !== null && customShader.shader.wgsl === null) {
             throw new Error('Mesh material shader has no `wgsl` source; cannot render through the WebGPU backend.');
         }
-        if (customShader !== null && backend._passCoordinator.stencilActive) {
-            // The WebGPU geometric stencil MVP supports clipping default-material
-            // Sprites and Mesh/Graphics (which select stencil-enabled pipeline
-            // variants below); a custom MeshMaterial under a Geometry clip would need
-            // its own stencil pipeline variants and is not supported yet. Throw at
-            // collection time (inside the clip scope's try) so the surrounding
-            // push/pop balances cleanly, rather than at flush time where the pop has
-            // not yet run.
-            throw new Error('WebGPU geometry stencil clipping currently supports default-material Sprites, Meshes, and Graphics. A custom-material Mesh under a Geometry clip (RenderNode.clip with a Geometry clipShape) is not supported yet. Use a Rectangle clipShape (scissor) or the WebGL2 backend instead.');
-        }
         const vertexCount = mesh.vertexCount;
         if (vertexCount === 0) {
             return;
@@ -23930,13 +24269,17 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                         this._packedIndexData[start + j] = j;
                     }
                 }
-                // Pack tint+flags for default path.
+                // Pack tint+flags for default path. Color RGB channels are 0..255; the
+                // shader multiplies the sampled texel by this tint, so normalize to
+                // 0..1 (matching TransformBuffer and the WebGL2 mesh shader). Leaving
+                // them at 0..255 scales every non-zero texel channel past 1.0, which
+                // clamps intermediate colors (gradients, photos) to full saturation.
                 if (defaultUniformF32 !== null) {
                     const offsetWords = (defaultUniformIndex * this._uniformAlignment) / Float32Array.BYTES_PER_ELEMENT;
                     const tint = dc.mesh.tint;
-                    defaultUniformF32[offsetWords + 0] = tint.r;
-                    defaultUniformF32[offsetWords + 1] = tint.g;
-                    defaultUniformF32[offsetWords + 2] = tint.b;
+                    defaultUniformF32[offsetWords + 0] = tint.r / 255;
+                    defaultUniformF32[offsetWords + 1] = tint.g / 255;
+                    defaultUniformF32[offsetWords + 2] = tint.b / 255;
                     defaultUniformF32[offsetWords + 3] = tint.a;
                     defaultUniformF32[offsetWords + 4] = dc.premultiplySample ? 1 : 0;
                     defaultUniformF32[offsetWords + 5] = 0;
@@ -23976,7 +24319,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 drawCursor++;
             }
             device.queue.writeBuffer(resources.vertexBuffer, 0, resources.vertexData, 0, resources.totalVertices * vertexStrideBytes$2);
-            device.queue.writeBuffer(resources.indexBuffer, 0, resources.indexData.buffer, resources.indexData.byteOffset, resources.totalIndices * Uint16Array.BYTES_PER_ELEMENT);
+            device.queue.writeBuffer(resources.indexBuffer, 0, resources.indexData.buffer, resources.indexData.byteOffset, (resources.totalIndices * Uint16Array.BYTES_PER_ELEMENT + 3) & -4);
             // Build/refresh user uniform UBO from the material (re-built every frame
             // so mutations to material.uniforms.X are picked up).
             this._uploadUserUniforms(material, resources);
@@ -23984,7 +24327,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         // Phase 4: single writeBuffer per resource for the default path.
         if (defaultVertices > 0) {
             device.queue.writeBuffer(this._vertexBuffer, 0, this._vertexData, 0, defaultVertices * vertexStrideBytes$2);
-            device.queue.writeBuffer(this._indexBuffer, 0, this._packedIndexData.buffer, this._packedIndexData.byteOffset, defaultIndices * Uint16Array.BYTES_PER_ELEMENT);
+            device.queue.writeBuffer(this._indexBuffer, 0, this._packedIndexData.buffer, this._packedIndexData.byteOffset, (defaultIndices * Uint16Array.BYTES_PER_ELEMENT + 3) & -4);
         }
         if (defaultUniformData !== null) {
             device.queue.writeBuffer(this._uniformBuffer, 0, defaultUniformData, 0, defaultUniformBytes);
@@ -23997,10 +24340,9 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         const renderTargetFormat = backend.renderTargetFormat;
         // A clip scope flushes the active renderer on push/pop, so every draw call
         // in this batch shares one stencil state — read it once. While active, the
-        // coordinator's pass carries a depth/stencil attachment, so the default and
-        // static-batch pipelines must select their stencil-enabled variants. The
-        // custom path never reaches here under a clip (render() throws at collection
-        // time), so its pipelines stay stencil-free.
+        // coordinator's pass carries a depth/stencil attachment, so the default,
+        // static-batch, and custom-material pipelines must all select their
+        // stencil-enabled variants to match it.
         const stencil = backend._passCoordinator.stencilActive;
         let lastShader = null;
         let lastBlendMode = null;
@@ -24076,7 +24418,7 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 // batched render pass.
                 pass.pushDebugGroup('MeshMaterial (custom)');
                 if (needsPipeline) {
-                    pass.setPipeline(this._getOrCreateCustomPipeline(resources, dc.blendMode, renderTargetFormat));
+                    pass.setPipeline(this._getOrCreateCustomPipeline(resources, dc.blendMode, renderTargetFormat, stencil));
                     lastShader = dc.customShader;
                     lastBlendMode = dc.blendMode;
                     lastFormat = renderTargetFormat;
@@ -24528,7 +24870,9 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         const vertexFloatView = new Float32Array(vertexData);
         const vertexUintView = new Uint32Array(vertexData);
         this._writeMeshVerticesIntoBuffer(mesh, 0, vertexFloatView, vertexUintView);
-        const indexData = new Uint16Array(mesh.indexCount);
+        // Allocate one extra element when indexCount is odd so the GPU buffer and
+        // writeBuffer byte count can be rounded up to 4 without a buffer overread.
+        const indexData = new Uint16Array(mesh.indexCount + (mesh.indexCount & 1));
         if (mesh.indices !== null) {
             indexData.set(mesh.indices, 0);
         }
@@ -24537,16 +24881,18 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 indexData[i] = i;
             }
         }
+        const indexByteLen = mesh.indexCount * Uint16Array.BYTES_PER_ELEMENT;
+        const alignedIndexByteLen = (indexByteLen + 3) & -4;
         const vertexBuffer = this._device.createBuffer({
             size: vertexData.byteLength,
             usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
         });
         const indexBuffer = this._device.createBuffer({
-            size: indexData.byteLength,
+            size: alignedIndexByteLen,
             usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
         });
         this._device.queue.writeBuffer(vertexBuffer, 0, vertexData, 0, vertexData.byteLength);
-        this._device.queue.writeBuffer(indexBuffer, 0, indexData.buffer, indexData.byteOffset, indexData.byteLength);
+        this._device.queue.writeBuffer(indexBuffer, 0, indexData.buffer, indexData.byteOffset, alignedIndexByteLen);
         const disposeListener = () => {
             const entry = this._staticGeometryCache.get(geometry);
             if (entry === undefined) {
@@ -24585,13 +24931,16 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         }
     }
     _ensureIndexCapacity(indexCount) {
-        const requiredBytes = indexCount * Uint16Array.BYTES_PER_ELEMENT;
-        if (this._packedIndexData.length < indexCount) {
-            this._packedIndexData = new Uint16Array(Math.max(indexCount, this._packedIndexData.length === 0 ? 1 : this._packedIndexData.length * 2));
+        // GPUQueue.writeBuffer requires the byte count to be a multiple of 4.
+        // Round up: odd Uint16 counts (e.g. a 3-index triangle) would otherwise
+        // produce 6-byte writes which the WebGPU validation layer rejects.
+        const requiredBytes = (indexCount * Uint16Array.BYTES_PER_ELEMENT + 3) & -4;
+        if (this._packedIndexData.length * Uint16Array.BYTES_PER_ELEMENT < requiredBytes) {
+            this._packedIndexData = new Uint16Array(Math.max(requiredBytes / Uint16Array.BYTES_PER_ELEMENT, this._packedIndexData.length === 0 ? 2 : this._packedIndexData.length * 2));
         }
         if (requiredBytes > this._indexBufferCapacity) {
             this._indexBuffer?.destroy();
-            this._indexBufferCapacity = Math.max(requiredBytes, this._indexBufferCapacity === 0 ? Uint16Array.BYTES_PER_ELEMENT : this._indexBufferCapacity * 2);
+            this._indexBufferCapacity = Math.max(requiredBytes, this._indexBufferCapacity === 0 ? 4 : this._indexBufferCapacity * 2);
             this._indexBuffer = this._device.createBuffer({
                 size: this._indexBufferCapacity,
                 usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
@@ -24735,14 +25084,14 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                 usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
             });
         }
-        // Index buffer
-        const indexBytes = resources.totalIndices * Uint16Array.BYTES_PER_ELEMENT;
-        if (resources.indexData.length < resources.totalIndices) {
-            resources.indexData = new Uint16Array(Math.max(resources.totalIndices, resources.indexData.length * 2));
+        // Index buffer — capacity must be 4-byte aligned for GPUQueue.writeBuffer.
+        const indexBytes = (resources.totalIndices * Uint16Array.BYTES_PER_ELEMENT + 3) & -4;
+        if (resources.indexData.length * Uint16Array.BYTES_PER_ELEMENT < indexBytes) {
+            resources.indexData = new Uint16Array(Math.max(indexBytes / Uint16Array.BYTES_PER_ELEMENT, resources.indexData.length * 2));
         }
         if (indexBytes > resources.indexBufferCapacity) {
             resources.indexBuffer?.destroy();
-            resources.indexBufferCapacity = Math.max(indexBytes, resources.indexBufferCapacity * 2 || Uint16Array.BYTES_PER_ELEMENT);
+            resources.indexBufferCapacity = Math.max(indexBytes, resources.indexBufferCapacity * 2 || 4);
             resources.indexBuffer = device.createBuffer({
                 size: resources.indexBufferCapacity,
                 usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
@@ -24828,19 +25177,24 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
         data[off + 10] = 1;
         data[off + 11] = 0;
         off += 12;
-        // tint (vec4)
+        // tint (vec4). RGB are 0..255; normalize to 0..1 for the shader multiply
+        // (u_mesh.tint is documented as 0..1, matching the default path above).
         const tint = mesh.tint;
-        data[off + 0] = tint.r;
-        data[off + 1] = tint.g;
-        data[off + 2] = tint.b;
+        data[off + 0] = tint.r / 255;
+        data[off + 1] = tint.g / 255;
+        data[off + 2] = tint.b / 255;
         data[off + 3] = tint.a;
         this._device.queue.writeBuffer(resources.meshUniformBuffer, drawCursor * slotBytes, data);
     }
-    _getOrCreateCustomPipeline(resources, blendMode, format) {
-        const cacheKey = `${blendMode}:${format}`;
+    _getOrCreateCustomPipeline(resources, blendMode, format, stencil) {
+        // The stencil dimension keeps the clip and no-clip variants distinct,
+        // mirroring the default and static-batch caches: a stencil pipeline carries
+        // depth/stencil state and is only valid in a pass with the matching
+        // attachment, so the two are never interchangeable.
+        const cacheKey = `${blendMode}:${format}:${stencil ? 's' : 'n'}`;
         let pipeline = resources.pipelines.get(cacheKey);
         if (pipeline === undefined) {
-            pipeline = this._device.createRenderPipeline({
+            const descriptor = {
                 layout: resources.pipelineLayout,
                 vertex: {
                     module: resources.shaderModule,
@@ -24872,7 +25226,14 @@ class WebGpuMeshRenderer extends AbstractWebGpuRenderer {
                     topology: 'triangle-list',
                     cullMode: 'none',
                 },
-            });
+            };
+            // While a geometric clip is active the coordinator's pass carries a
+            // depth/stencil attachment; the content pipeline must test stencil ==
+            // reference and leave depth/stencil otherwise inert to match it.
+            if (stencil) {
+                descriptor.depthStencil = stencilContentDepthStencilState();
+            }
+            pipeline = this._device.createRenderPipeline(descriptor);
             resources.pipelines.set(cacheKey, pipeline);
         }
         return pipeline;
@@ -25111,6 +25472,13 @@ const initialParticleCapacity = 1;
 const staticVertexData = new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]);
 const staticIndexData = new Uint16Array([0, 1, 2, 0, 2, 3]);
 class WebGpuParticleRenderer extends AbstractWebGpuRenderer {
+    /**
+     * The particle system's transform is bound as a uniform and each particle is
+     * positioned system-locally, so this renderer never reads the shared transform
+     * storage; the plan player skips writing transform records for particle draws.
+     * @internal
+     */
+    _consumesSharedTransform = false;
     _drawCalls = [];
     _drawCallCount = 0;
     _uniformData = new Float32Array(uniformByteLength / Float32Array.BYTES_PER_ELEMENT);
@@ -25135,12 +25503,6 @@ class WebGpuParticleRenderer extends AbstractWebGpuRenderer {
         if (backend === null || !(texture instanceof Texture) || texture.source === null || texture.width === 0 || texture.height === 0 || system.liveCount === 0) {
             return;
         }
-        if (backend._passCoordinator.stencilActive) {
-            // MVP boundary: stencil clipping supports default-material Sprites, Meshes,
-            // and Graphics — not ParticleSystems. Throw at collection time (inside the
-            // clip scope's try) so the push/pop balances.
-            throw new Error('WebGPU geometry stencil clipping currently supports default-material Sprites, Meshes, and Graphics. ParticleSystem content under a Geometry clip (RenderNode.clip with a Geometry clipShape) is not supported yet. Use a Rectangle clipShape (scissor) or the WebGL2 backend instead.');
-        }
         backend.setBlendMode(system.blendMode);
         const drawCallIndex = this._drawCallCount++;
         const drawCall = this._drawCalls[drawCallIndex];
@@ -25199,7 +25561,7 @@ class WebGpuParticleRenderer extends AbstractWebGpuRenderer {
             if (particleCount === 0) {
                 continue;
             }
-            const pipeline = this._getPipeline(drawCall.blendMode, backend.renderTargetFormat);
+            const pipeline = this._getPipeline(drawCall.blendMode, backend.renderTargetFormat, backend._passCoordinator.stencilActive);
             const textureBinding = backend.getTextureBinding(drawCall.texture);
             const textureBindGroup = device.createBindGroup({
                 layout: this._textureBindGroupLayout,
@@ -25499,13 +25861,13 @@ class WebGpuParticleRenderer extends AbstractWebGpuRenderer {
         }
         return { uvMins: mins, uvMaxs: maxs };
     }
-    _getPipeline(blendMode, format) {
-        const pipelineKey = `${blendMode}:${format}`;
+    _getPipeline(blendMode, format, stencil) {
+        const pipelineKey = `${blendMode}:${format}:${stencil ? 's' : 'n'}`;
         const existingPipeline = this._pipelines.get(pipelineKey);
         if (existingPipeline) {
             return existingPipeline;
         }
-        const pipeline = this._device.createRenderPipeline({
+        const descriptor = {
             layout: this._pipelineLayout,
             vertex: {
                 module: this._shaderModule,
@@ -25573,7 +25935,11 @@ class WebGpuParticleRenderer extends AbstractWebGpuRenderer {
             primitive: {
                 topology: 'triangle-list',
             },
-        });
+        };
+        if (stencil) {
+            descriptor.depthStencil = stencilContentDepthStencilState();
+        }
+        const pipeline = this._device.createRenderPipeline(descriptor);
         this._pipelines.set(pipelineKey, pipeline);
         return pipeline;
     }
@@ -25584,8 +25950,8 @@ class WebGpuParticleRenderer extends AbstractWebGpuRenderer {
  * WebGPU implementation of {@link RenderPassCoordinator}.
  *
  * Owns the GPU render-pass mechanics (acquire/end the active
- * `GPURenderPassEncoder`), the clear-vs-load decision, and — from phase 12E —
- * geometric stencil clipping: a per-target `depth24plus-stencil8` attachment
+ * `GPURenderPassEncoder`), the clear-vs-load decision, and geometric stencil
+ * clipping: a per-target `depth24plus-stencil8` attachment
  * shared across the multiple submits of a clip scope (via `stencilLoadOp:'load'`)
  * plus a position-only stencil-write pipeline. Renderers select stencil-enabled
  * content pipelines while {@link stencilActive} is true.
@@ -25849,8 +26215,16 @@ struct ProjectionUniforms {
     matrix: mat4x4<f32>,
 };
 
+struct TransformSlot {
+    m0: vec4<f32>,
+    m1: vec4<f32>,
+    m2: vec4<f32>,
+};
+
 @group(0) @binding(0)
 var<uniform> projection: ProjectionUniforms;
+@group(0) @binding(1)
+var<storage, read> transforms: array<TransformSlot>;
 
 @group(1) @binding(0)
 var spriteTexture0: texture_2d<f32>;
@@ -25886,16 +26260,17 @@ var spriteSampler6: sampler;
 @group(1) @binding(15)
 var spriteSampler7: sampler;
 
-// Per-instance vertex layout (56 bytes per sprite). The four corners
+// Per-instance vertex layout (36 bytes per sprite). The four corners
 // of the quad are derived from @builtin(vertex_index) 0..3 inside the
-// vertex shader — there is no per-vertex stream.
+// vertex shader — there is no per-vertex stream. The world transform is
+// fetched from the shared transform storage buffer keyed by nodeIndex
+// instead of being packed inline.
 struct VertexInput {
     @location(0) localBounds: vec4<f32>,        // left, top, right, bottom (local space)
-    @location(1) transformAB: vec3<f32>,        // first  row of 2D affine
-    @location(2) transformCD: vec3<f32>,        // second row of 2D affine
     @location(3) uvBounds: vec4<f32>,           // uMin, vMin, uMax, vMax (CPU pre-swaps for flipY)
     @location(4) color: vec4<f32>,              // RGBA tint
     @location(5) packedSlotFlags: u32,          // bits 0..7 = slot, bit 8 = premultiply
+    @location(6) nodeIndex: u32,                // row into the shared transform storage buffer
 };
 
 struct VertexOutput {
@@ -25918,8 +26293,12 @@ fn vertexMain(input: VertexInput, @builtin(vertex_index) vid: u32) -> VertexOutp
     let localX = select(input.localBounds.x, input.localBounds.z, cornerX == 1u);
     let localY = select(input.localBounds.y, input.localBounds.w, cornerY == 1u);
 
-    let worldX = input.transformAB.x * localX + input.transformAB.y * localY + input.transformAB.z;
-    let worldY = input.transformCD.x * localX + input.transformCD.y * localY + input.transformCD.z;
+    // Fetch this instance's world transform from the shared storage buffer,
+    // keyed by nodeIndex: m0 = (a, b, c, d), m1 = (tx, ty, 0, 0). (m2 carries the
+    // node tint, unused here — the sprite keeps its own per-instance color.)
+    let slot = transforms[input.nodeIndex];
+    let worldX = slot.m0.x * localX + slot.m0.y * localY + slot.m1.x;
+    let worldY = slot.m0.z * localX + slot.m0.w * localY + slot.m1.y;
 
     output.position = projection.matrix * vec4<f32>(worldX, worldY, 0.0, 1.0);
 
@@ -25979,7 +26358,7 @@ fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
     return resolvedSample * input.color;
 }
 `;
-const instanceStrideBytes = 56;
+const instanceStrideBytes = 36;
 const wordsPerInstance = instanceStrideBytes / Uint32Array.BYTES_PER_ELEMENT;
 const projectionByteLength = 64;
 const initialBatchCapacity = 32;
@@ -25997,7 +26376,10 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
     _textureBindGroupLayout = null;
     _pipelineLayout = null;
     _uniformBuffer = null;
-    _uniformBindGroup = null;
+    // group(0) bind group = projection UBO + shared transform storage buffer.
+    // Recreated whenever the storage buffer identity changes (capacity growth).
+    _transformBindGroup = null;
+    _transformStorageBuffer = null;
     _indexBuffer = null;
     _instanceBuffer = null;
     _instanceCapacity = 0;
@@ -26009,6 +26391,9 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
     _textureSlots = new Map();
     _slotCount = 0;
     _instanceCount = 0;
+    // Highest transform-storage row referenced by the pending batch; drives the
+    // minimum row count uploaded for the storage buffer at flush time.
+    _maxNodeIndex = 0;
     _currentBlendMode = null;
     // Custom-material state. Per-material pipelines/bind groups are cached; the
     // current batch's material/base-texture decide when to flush.
@@ -26031,6 +26416,13 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
                         type: 'uniform',
                     },
                 },
+                {
+                    binding: 1,
+                    visibility: GPUShaderStage.VERTEX,
+                    buffer: {
+                        type: 'read-only-storage',
+                    },
+                },
             ],
         });
         this._textureBindGroupLayout = this._device.createBindGroupLayout({
@@ -26065,17 +26457,9 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
             size: projectionByteLength,
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
-        this._uniformBindGroup = this._device.createBindGroup({
-            layout: this._uniformBindGroupLayout,
-            entries: [
-                {
-                    binding: 0,
-                    resource: {
-                        buffer: this._uniformBuffer,
-                    },
-                },
-            ],
-        });
+        // The group(0) bind group also binds the shared transform storage buffer,
+        // whose identity changes when its capacity grows — so it is built lazily in
+        // flush() once the active storage buffer is known.
         // Static index buffer for the quad. Allocated once at connect; its
         // contents never change.
         this._indexBuffer = this._device.createBuffer({
@@ -26098,7 +26482,8 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         this._pipelines.clear();
         this._instanceBuffer = null;
         this._indexBuffer = null;
-        this._uniformBindGroup = null;
+        this._transformBindGroup = null;
+        this._transformStorageBuffer = null;
         this._uniformBuffer = null;
         this._pipelineLayout = null;
         this._customBaseTextureLayout = null;
@@ -26112,6 +26497,7 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         this._instanceFloat32 = new Float32Array(this._instanceData);
         this._instanceUint32 = new Uint32Array(this._instanceData);
         this._instanceCount = 0;
+        this._maxNodeIndex = 0;
         this._currentBlendMode = null;
         this._currentMaterial = null;
         this._currentBaseTexture = null;
@@ -26129,15 +26515,21 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
             return;
         }
         const material = sprite.material;
+        // The transform lives in the shared storage buffer, keyed by the draw
+        // command's stable nodeIndex (already packed at the draw-command boundary).
+        // A direct, non-plan `backend.draw(sprite)` has no command — push the
+        // sprite's transform into the buffer and use the freshly-allocated slot.
+        const command = backend.activeDrawCommand;
+        const nodeIndex = command !== null ? command.nodeIndex : backend._pushTransform(sprite);
         if (material === null) {
-            this._renderDefault(sprite, texture, backend);
+            this._renderDefault(sprite, texture, backend, nodeIndex);
         }
         else {
-            this._renderCustom(sprite, texture, material, backend);
+            this._renderCustom(sprite, texture, material, backend, nodeIndex);
         }
     }
     /** Default multi-texture path: rotate the base texture through 8 slots. */
-    _renderDefault(sprite, texture, backend) {
+    _renderDefault(sprite, texture, backend, nodeIndex) {
         const blendMode = sprite.blendMode;
         // Flush triggers: blend-mode change, texture-slot exhaustion, or a custom
         // batch still in flight that must drain first.
@@ -26163,20 +26555,14 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         // typed-array writes in _packInstance silently fall off the end of a
         // too-small buffer.
         this._ensureInstanceCapacity(this._instanceCount + 1);
-        this._packInstance(sprite, texture, packedSlotFlags);
+        this._packInstance(sprite, texture, packedSlotFlags, nodeIndex);
         this._instanceCount++;
     }
     /** Custom-material path: single base texture on group(1), instanced. */
-    _renderCustom(sprite, texture, material, backend) {
+    _renderCustom(sprite, texture, material, backend, nodeIndex) {
         if (material.shader.wgsl === null) {
             throw new Error('SpriteMaterial shader has no `wgsl` source; cannot render through the WebGPU backend.');
         }
-        if (backend._passCoordinator.stencilActive) {
-            // MVP boundary: default-material Sprites, Meshes, and Graphics support the
-            // stencil pipeline variants; a custom-material Sprite does not yet. Throw at
-            // collection time so the clip scope's push/pop balances.
-            throw new Error('WebGPU geometry stencil clipping currently supports default-material Sprites, Meshes, and Graphics. A custom-material Sprite under a Geometry clip (RenderNode.clip with a Geometry clipShape) is not supported yet. Use a Rectangle clipShape (scissor) or the WebGL2 backend instead.');
-        }
         // The material owns its blend mode; the sprite's own blendMode overrides it
         // when set away from the default (Normal).
         const blendMode = sprite.blendMode === BlendModes.Normal ? material.blendMode : sprite.blendMode;
@@ -26193,15 +26579,14 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         backend.setBlendMode(blendMode);
         // textureSlot word is unused by custom fragments (base binds to group(1)).
         this._ensureInstanceCapacity(this._instanceCount + 1);
-        this._packInstance(sprite, texture, 0);
+        this._packInstance(sprite, texture, 0, nodeIndex);
         this._instanceCount++;
     }
     flush() {
         const backend = this._backend;
         const device = this._device;
         const uniformBuffer = this._uniformBuffer;
-        const uniformBindGroup = this._uniformBindGroup;
-        if (!backend || !device || !uniformBuffer || !uniformBindGroup) {
+        if (!backend || !device || !uniformBuffer) {
             return;
         }
         if (this._instanceCount === 0 && !backend.clearRequested) {
@@ -26218,13 +26603,19 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         const pass = backend._passCoordinator.acquirePass().pass;
         if (this._instanceCount > 0 && !maskClipsAll && this._instanceBuffer !== null && this._indexBuffer !== null && this._currentBlendMode !== null) {
             device.queue.writeBuffer(this._instanceBuffer, 0, this._instanceData, 0, this._instanceCount * instanceStrideBytes);
+            // Resolve the shared transform storage buffer (rows uploaded up to the
+            // max nodeIndex referenced by this batch) and bind it alongside the
+            // projection UBO on group(0). Both the default and custom programs fetch
+            // the world transform from it via nodeIndex.
+            const storage = backend.getTransformStorageBuffer(this._maxNodeIndex + 1);
+            const transformBindGroup = this._getOrCreateTransformBindGroup(device, uniformBuffer, storage.buffer);
             const material = this._currentMaterial;
             const stencil = backend._passCoordinator.stencilActive;
             if (material === null) {
                 const pipeline = this._getPipeline(this._currentBlendMode, backend.renderTargetFormat, stencil);
                 const textureBindGroup = this._createTextureBindGroup(device, backend);
                 pass.setPipeline(pipeline);
-                pass.setBindGroup(0, uniformBindGroup);
+                pass.setBindGroup(0, transformBindGroup);
                 pass.setBindGroup(1, textureBindGroup);
                 pass.setVertexBuffer(0, this._instanceBuffer);
                 pass.setIndexBuffer(this._indexBuffer, 'uint16');
@@ -26232,7 +26623,7 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
             }
             else {
                 pass.pushDebugGroup('SpriteMaterial (custom)');
-                this._drawCustomBatch(pass, device, backend, material, uniformBindGroup);
+                this._drawCustomBatch(pass, device, backend, material, transformBindGroup, stencil);
                 pass.popDebugGroup();
             }
             backend.stats.batches++;
@@ -26240,11 +26631,31 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         }
         backend._passCoordinator.endPass();
         this._instanceCount = 0;
+        this._maxNodeIndex = 0;
         this._resetSlots();
         this._currentBlendMode = null;
         this._currentMaterial = null;
         this._currentBaseTexture = null;
     }
+    /**
+     * Build (or reuse) the group(0) bind group pairing the fixed projection UBO
+     * with the shared transform storage buffer. Cached against the storage buffer
+     * identity, which changes only when its capacity grows.
+     */
+    _getOrCreateTransformBindGroup(device, uniformBuffer, storageBuffer) {
+        if (this._transformBindGroup !== null && this._transformStorageBuffer === storageBuffer) {
+            return this._transformBindGroup;
+        }
+        this._transformStorageBuffer = storageBuffer;
+        this._transformBindGroup = device.createBindGroup({
+            layout: this._uniformBindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: uniformBuffer } },
+                { binding: 1, resource: { buffer: storageBuffer } },
+            ],
+        });
+        return this._transformBindGroup;
+    }
     destroy() {
         this.disconnect();
     }
@@ -26291,24 +26702,18 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         }
         await Promise.all(promises);
     }
-    _packInstance(sprite, texture, packedSlotFlags) {
+    _packInstance(sprite, texture, packedSlotFlags, nodeIndex) {
         const offset = this._instanceCount * wordsPerInstance;
         const f32 = this._instanceFloat32;
         const u32 = this._instanceUint32;
+        // localBounds: left, top, right, bottom (words 0..3, offset 0)
         const bounds = sprite.getLocalBounds();
         f32[offset + 0] = bounds.left;
         f32[offset + 1] = bounds.top;
         f32[offset + 2] = bounds.right;
         f32[offset + 3] = bounds.bottom;
-        const transform = sprite.getGlobalTransform();
-        f32[offset + 4] = transform.a;
-        f32[offset + 5] = transform.b;
-        f32[offset + 6] = transform.x;
-        f32[offset + 7] = transform.c;
-        f32[offset + 8] = transform.d;
-        f32[offset + 9] = transform.y;
-        // uvBounds: u16x4 normalised, packed into two u32 slots. The CPU
-        // applies the flipY swap so the shader stays orientation-agnostic.
+        // uvBounds: u16x4 normalised, packed into two u32 slots (words 4,5, offset
+        // 16). The CPU applies the flipY swap so the shader stays orientation-agnostic.
         const frame = sprite.textureFrame;
         const texWidth = texture.width;
         const texHeight = texture.height;
@@ -26319,10 +26724,18 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         const flipY = texture instanceof Texture && texture.flipY;
         const vMin = flipY ? vMaxRaw : vMinRaw;
         const vMax = flipY ? vMinRaw : vMaxRaw;
-        u32[offset + 10] = uMin | (vMin << 16);
-        u32[offset + 11] = uMax | (vMax << 16);
-        u32[offset + 12] = sprite.tint.toRgba();
-        u32[offset + 13] = packedSlotFlags;
+        u32[offset + 4] = uMin | (vMin << 16);
+        u32[offset + 5] = uMax | (vMax << 16);
+        // color (u8x4 packed) at word 6 (offset 24)
+        u32[offset + 6] = sprite.tint.toRgba();
+        // packedSlotFlags (u32) at word 7 (offset 28)
+        u32[offset + 7] = packedSlotFlags;
+        // nodeIndex (u32) at word 8 (offset 32) — row into the shared transform buffer.
+        const node = nodeIndex >>> 0;
+        u32[offset + 8] = node;
+        if (node > this._maxNodeIndex) {
+            this._maxNodeIndex = node;
+        }
     }
     _ensureInstanceCapacity(instanceCount) {
         if (!this._device || instanceCount <= this._instanceCapacity) {
@@ -26424,29 +26837,24 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
                                 offset: 0,
                                 format: 'float32x4',
                             },
-                            {
-                                shaderLocation: 1,
-                                offset: 16,
-                                format: 'float32x3',
-                            },
-                            {
-                                shaderLocation: 2,
-                                offset: 28,
-                                format: 'float32x3',
-                            },
                             {
                                 shaderLocation: 3,
-                                offset: 40,
+                                offset: 16,
                                 format: 'unorm16x4',
                             },
                             {
                                 shaderLocation: 4,
-                                offset: 48,
+                                offset: 24,
                                 format: 'unorm8x4',
                             },
                             {
                                 shaderLocation: 5,
-                                offset: 52,
+                                offset: 28,
+                                format: 'uint32',
+                            },
+                            {
+                                shaderLocation: 6,
+                                offset: 32,
                                 format: 'uint32',
                             },
                         ],
@@ -26476,14 +26884,14 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
     // ---------------------------------------------------------------------------
     // Custom-material path
     // ---------------------------------------------------------------------------
-    _drawCustomBatch(pass, device, backend, material, projectionBindGroup) {
+    _drawCustomBatch(pass, device, backend, material, transformBindGroup, stencil) {
         const resources = this._getOrCreateCustomResources(material, device);
         const baseTexture = this._currentBaseTexture ?? Texture.empty;
         // Re-built every frame so mutations to material.uniforms.X are picked up.
         this._uploadUserUniforms(material, resources, device);
-        const pipeline = this._getOrCreateCustomPipeline(resources, this._currentBlendMode, backend.renderTargetFormat, device);
+        const pipeline = this._getOrCreateCustomPipeline(resources, this._currentBlendMode, backend.renderTargetFormat, stencil, device);
         pass.setPipeline(pipeline);
-        pass.setBindGroup(0, projectionBindGroup);
+        pass.setBindGroup(0, transformBindGroup);
         pass.setBindGroup(1, this._getCustomBaseTextureBindGroup(resources, backend, baseTexture, device));
         pass.setBindGroup(2, this._buildUserBindGroup(material, resources, backend, device));
         pass.setVertexBuffer(0, this._instanceBuffer);
@@ -26500,8 +26908,8 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
             throw new Error('SpriteMaterial shader has no `wgsl` source; cannot render through the WebGPU backend.');
         }
         // The engine owns the vertex stage: prepend the canonical sprite vertex
-        // module (VertexInput/VertexOutput, group(0) projection, group(1) base
-        // texture + sampler) to the material's fragment WGSL.
+        // module (VertexInput/VertexOutput, group(0) projection + transform storage,
+        // group(1) base texture + sampler) to the material's fragment WGSL.
         const shaderModule = device.createShaderModule({ code: `${spriteVertexWgsl}\n${wgsl}` });
         const userLayout = this._buildUserBindGroupLayout(device, material);
         const pipelineLayout = device.createPipelineLayout({
@@ -26526,13 +26934,13 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
         });
         return resources;
     }
-    _getOrCreateCustomPipeline(resources, blendMode, format, device) {
-        const cacheKey = `${blendMode}:${format}`;
+    _getOrCreateCustomPipeline(resources, blendMode, format, stencil, device) {
+        const cacheKey = `${blendMode}:${format}:${stencil ? 's' : 'n'}`;
         const existing = resources.pipelines.get(cacheKey);
         if (existing !== undefined) {
             return existing;
         }
-        const pipeline = device.createRenderPipeline({
+        const descriptor = {
             layout: resources.pipelineLayout,
             vertex: {
                 module: resources.shaderModule,
@@ -26543,11 +26951,10 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
                         stepMode: 'instance',
                         attributes: [
                             { shaderLocation: 0, offset: 0, format: 'float32x4' },
-                            { shaderLocation: 1, offset: 16, format: 'float32x3' },
-                            { shaderLocation: 2, offset: 28, format: 'float32x3' },
-                            { shaderLocation: 3, offset: 40, format: 'unorm16x4' },
-                            { shaderLocation: 4, offset: 48, format: 'unorm8x4' },
-                            { shaderLocation: 5, offset: 52, format: 'uint32' },
+                            { shaderLocation: 3, offset: 16, format: 'unorm16x4' },
+                            { shaderLocation: 4, offset: 24, format: 'unorm8x4' },
+                            { shaderLocation: 5, offset: 28, format: 'uint32' },
+                            { shaderLocation: 6, offset: 32, format: 'uint32' },
                         ],
                     },
                 ],
@@ -26566,7 +26973,11 @@ class WebGpuSpriteRenderer extends AbstractWebGpuRenderer {
             primitive: {
                 topology: 'triangle-list',
             },
-        });
+        };
+        if (stencil) {
+            descriptor.depthStencil = stencilContentDepthStencilState();
+        }
+        const pipeline = device.createRenderPipeline(descriptor);
         resources.pipelines.set(cacheKey, pipeline);
         return pipeline;
     }
@@ -26913,6 +27324,13 @@ fn fragmentColor(in: VertexOutput) -> @location(0) vec4<f32> {
  * render pass.
  */
 class WebGpuTextRenderer extends AbstractWebGpuRenderer {
+    /**
+     * Text packs its world transform into its own per-node data buffer and never
+     * reads the shared transform storage, so the plan player skips writing
+     * transform records for text draws.
+     * @internal
+     */
+    _consumesSharedTransform = false;
     _device = null;
     _shaderModule = null;
     _frameBindGroupLayout = null;
@@ -26948,12 +27366,6 @@ class WebGpuTextRenderer extends AbstractWebGpuRenderer {
     render(node) {
         if (!this._device)
             throw new Error('WebGpuTextRenderer is not connected to a backend.');
-        if (this.getBackend()._passCoordinator.stencilActive) {
-            // MVP boundary: stencil clipping supports default-material Sprites, Meshes,
-            // and Graphics — not Text. Throw at collection time (inside the clip scope's
-            // try) so the push/pop balances.
-            throw new Error('WebGPU geometry stencil clipping currently supports default-material Sprites, Meshes, and Graphics. Text content under a Geometry clip (RenderNode.clip with a Geometry clipShape) is not supported yet. Use a Rectangle clipShape (scissor) or the WebGL2 backend instead.');
-        }
         if (node instanceof Text) {
             this._collectText(node);
         }
@@ -27055,6 +27467,7 @@ class WebGpuTextRenderer extends AbstractWebGpuRenderer {
         device.queue.writeBuffer(this._vertexBuffer, 0, this._vertexData, 0, packedV * vertexStrideBytes$1);
         device.queue.writeBuffer(this._indexBuffer, 0, this._indexData.buffer, 0, packedI * 2);
         const format = backend.renderTargetFormat;
+        const stencil = backend._passCoordinator.stencilActive;
         const frameBindGroup = this._getFrameBindGroup(device);
         // The coordinator owns the GPU pass (load/clear resolution, pass count and
         // scissor are applied there) and ends + submits it below.
@@ -27065,7 +27478,7 @@ class WebGpuTextRenderer extends AbstractWebGpuRenderer {
         let lastTexture = null;
         for (const batch of batches) {
             if (batch.shaderType !== lastShaderType) {
-                pass.setPipeline(this._getPipeline(batch.shaderType, format));
+                pass.setPipeline(this._getPipeline(batch.shaderType, format, stencil));
                 pass.setBindGroup(0, frameBindGroup);
                 lastShaderType = batch.shaderType;
             }
@@ -27098,7 +27511,9 @@ class WebGpuTextRenderer extends AbstractWebGpuRenderer {
         const promises = [];
         for (const shaderType of shaderTypes) {
             for (const format of formats) {
-                const key = `${shaderType}:${format}`;
+                // Prewarm only the no-clip variant (matches the _getPipeline cache key
+                // for stencil = false); stencil variants compile lazily under a clip.
+                const key = `${shaderType}:${format}:n`;
                 if (this._pipelines.has(key))
                     continue;
                 promises.push(device.createRenderPipelineAsync(this._buildPipelineDescriptor(shaderType, format)).then(pipeline => {
@@ -27377,16 +27792,16 @@ class WebGpuTextRenderer extends AbstractWebGpuRenderer {
         return group;
     }
     // ── Pipeline helpers ─────────────────────────────────────────────────────
-    _getPipeline(shaderType, format) {
-        const key = `${shaderType}:${format}`;
+    _getPipeline(shaderType, format, stencil) {
+        const key = `${shaderType}:${format}:${stencil ? 's' : 'n'}`;
         const existing = this._pipelines.get(key);
         if (existing)
             return existing;
-        const pipeline = this._device.createRenderPipeline(this._buildPipelineDescriptor(shaderType, format));
+        const pipeline = this._device.createRenderPipeline(this._buildPipelineDescriptor(shaderType, format, stencil));
         this._pipelines.set(key, pipeline);
         return pipeline;
     }
-    _buildPipelineDescriptor(shaderType, format) {
+    _buildPipelineDescriptor(shaderType, format, stencil = false) {
         let fragEntry;
         if (shaderType === 'sdf') {
             fragEntry = 'fragmentSdf';
@@ -27397,7 +27812,7 @@ class WebGpuTextRenderer extends AbstractWebGpuRenderer {
         else {
             fragEntry = 'fragmentColor';
         }
-        return {
+        const descriptor = {
             label: `WebGpuTextRenderer/${shaderType}`,
             layout: this._pipelineLayout,
             vertex: {
@@ -27428,6 +27843,10 @@ class WebGpuTextRenderer extends AbstractWebGpuRenderer {
             },
             primitive: { topology: 'triangle-list' },
         };
+        if (stencil) {
+            descriptor.depthStencil = stencilContentDepthStencilState();
+        }
+        return descriptor;
     }
     // ── Capacity helpers ─────────────────────────────────────────────────────
     _ensureVertexCapacity(vertexCount) {
@@ -27471,6 +27890,14 @@ class WebGpuTransformStorage {
     _storageCapacity = 0;
     _storageHash = 0;
     _storageCount = -1;
+    /**
+     * Underlying shared transform buffer. Exposed for internal stats / tests
+     * (write, skip and upload counters); not part of any public surface.
+     * @internal
+     */
+    get buffer() {
+        return this._buffer;
+    }
     begin(nodeCount) {
         this._buffer.begin(nodeCount);
     }
@@ -27478,27 +27905,51 @@ class WebGpuTransformStorage {
         const drawable = command.drawable;
         this._buffer.write(command.nodeIndex, drawable.getGlobalTransform(), drawable.tint);
     }
+    /**
+     * Record that a draw command's transform write was skipped because its
+     * renderer opts out of the shared transform storage. Stats only.
+     * @internal
+     */
+    recordSkippedWrite() {
+        this._buffer.recordSkippedWrite();
+    }
+    /**
+     * Append a drawable's world transform (+ tint) to the shared buffer and return
+     * the slot it was written to. Used for draws that arrive without a stable
+     * `nodeIndex` — a direct `backend.draw(drawable)` outside the plan player —
+     * so a batch of synthetic draws does not collide on a single row.
+     */
+    push(drawable) {
+        return this._buffer.push(drawable.getGlobalTransform(), drawable.tint);
+    }
+    /**
+     * Pre-allocate (or grow) the GPU storage buffer to hold at least
+     * `recordCount` transform slots. Called once before render-plan playback so
+     * that later per-group flushes never trigger a mid-frame reallocation.
+     *
+     * If the buffer already covers `recordCount` this is a no-op — no GPU
+     * objects are destroyed or re-created. Capacity only grows, never shrinks.
+     * @internal
+     */
+    reserve(device, recordCount) {
+        const minCount = Math.max(1, recordCount);
+        const requiredBytes = minCount * slotFloatCount * Float32Array.BYTES_PER_ELEMENT;
+        if (this._storageBuffer !== null && requiredBytes <= this._storageCapacity) {
+            return;
+        }
+        this._growBuffer(device, requiredBytes);
+    }
     getBuffer(device, minCount) {
         const requiredCount = Math.max(1, minCount);
         const requiredBytes = requiredCount * slotFloatCount * Float32Array.BYTES_PER_ELEMENT;
         const snapshot = this._buffer.commitSnapshot(requiredCount);
         if (this._storageBuffer === null || requiredBytes > this._storageCapacity) {
-            let nextCapacity = Math.max(this._storageCapacity, slotFloatCount * Float32Array.BYTES_PER_ELEMENT);
-            while (nextCapacity < requiredBytes) {
-                nextCapacity *= 2;
-            }
-            this._storageBuffer?.destroy();
-            this._storageBuffer = device.createBuffer({
-                size: nextCapacity,
-                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
-            });
-            this._storageCapacity = nextCapacity;
-            this._storageHash = 0;
-            this._storageCount = -1;
+            this._growBuffer(device, requiredBytes);
         }
         if (snapshot.changed || snapshot.hash !== this._storageHash || snapshot.count !== this._storageCount) {
             const bytes = snapshot.count * slotFloatCount * Float32Array.BYTES_PER_ELEMENT;
             device.queue.writeBuffer(this._storageBuffer, 0, this._buffer.data.buffer, this._buffer.data.byteOffset, bytes);
+            this._buffer.recordUpload(snapshot.count);
             this._storageHash = snapshot.hash;
             this._storageCount = snapshot.count;
         }
@@ -27514,6 +27965,20 @@ class WebGpuTransformStorage {
         this._storageHash = 0;
         this._storageCount = -1;
     }
+    _growBuffer(device, requiredBytes) {
+        let nextCapacity = Math.max(this._storageCapacity, slotFloatCount * Float32Array.BYTES_PER_ELEMENT);
+        while (nextCapacity < requiredBytes) {
+            nextCapacity *= 2;
+        }
+        this._storageBuffer?.destroy();
+        this._storageBuffer = device.createBuffer({
+            size: nextCapacity,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        this._storageCapacity = nextCapacity;
+        this._storageHash = 0;
+        this._storageCount = -1;
+    }
 }
 
 /* eslint-disable max-lines */
@@ -27638,8 +28103,8 @@ class WebGpuBackend {
         return this._activeDrawCommand;
     }
     /**
-     * Internal render-pass coordinator. Owns the clear-vs-load decision and (from
-     * phase 12D) the active render pass; not part of the public
+     * Internal render-pass coordinator. Owns the clear-vs-load decision and the
+     * active render pass; not part of the public
      * {@link RenderBackend} surface.
      * @internal
      */
@@ -27671,14 +28136,46 @@ class WebGpuBackend {
     }
     /** @internal */
     _beginDrawPlan(nodeCount) {
-        this._getTransformStorage().begin(nodeCount);
+        const storage = this._getTransformStorage();
+        storage.begin(nodeCount);
+        // Pre-allocate the GPU storage buffer for the full plan before any group
+        // flush runs. Without this, a later flush with a higher maxNodeIndex would
+        // destroy and replace the buffer mid-frame while earlier command buffers
+        // may still reference the old allocation.
+        if (nodeCount > 0 && this._device !== null && !this._deviceLost) {
+            storage.reserve(this._device, nodeCount);
+        }
         this._activeDrawCommand = null;
         this._drawPlanDepth++;
     }
     /** @internal */
+    _prepareRenderGroupUpload(group) {
+        // Pack the whole render group's world transforms (+ tint) into the shared
+        // transform storage at the group's upload boundary, keyed by each draw
+        // command's stable nodeIndex. Every draw the player will submit for this
+        // group is covered here, before the group's first draw.
+        //
+        // Renderers that pack their own per-node data (Text, Particle) never read
+        // the shared storage, so their commands are skipped — no consuming draw
+        // ever references their slots (nodeIndex is unique per command).
+        const storage = this._getTransformStorage();
+        const instructions = group.instructions;
+        for (let i = 0; i < instructions.length; i++) {
+            const command = instructions[i];
+            if (drawCommandUsesSharedTransform(command, this)) {
+                storage.writeCommand(command);
+            }
+            else {
+                storage.recordSkippedWrite();
+            }
+        }
+    }
+    /** @internal */
     _prepareDrawCommand(command) {
+        // Transform packing now happens at the render-group upload boundary
+        // (`_prepareRenderGroupUpload`); this hook only tracks the active draw so
+        // renderers can read the current command's nodeIndex.
         this._activeDrawCommand = command;
-        this._getTransformStorage().writeCommand(command);
     }
     /** @internal */
     _endDrawPlan() {
@@ -27991,6 +28488,18 @@ class WebGpuBackend {
     getTransformStorageBuffer(minCount) {
         return this._getTransformStorage().getBuffer(this.device, minCount);
     }
+    /**
+     * Append a drawable's world transform (+ tint) to the shared transform storage
+     * and return the slot it was written to. Used by instanced renderers for draws
+     * that arrive without a render-group upload boundary — i.e. a direct
+     * `backend.draw(drawable)` outside the plan player (`activeDrawCommand === null`),
+     * where no stable `nodeIndex` was assigned. Each call allocates a fresh slot, so
+     * a batch of synthetic draws does not collide on a single row.
+     * @internal
+     */
+    _pushTransform(drawable) {
+        return this._getTransformStorage().push(drawable);
+    }
     _setActiveRenderer(renderer) {
         if (this._renderer !== renderer) {
             this._flushActiveRenderer();
@@ -31486,7 +31995,7 @@ class Loader {
         return `id:${this._getTypeId(type)}:${discriminator}`;
     }
     _resolveUrl(path) {
-        if (path.startsWith('http://') || path.startsWith('https://') || path.startsWith('//')) {
+        if (path.startsWith('http://') || path.startsWith('https://') || path.startsWith('//') || path.startsWith('/')) {
             return path;
         }
         return `${this._basePath}${path}`;
@@ -35077,7 +35586,10 @@ const lookupSize$4 = 256;
  */
 class AlphaFadeOverLifetime extends UpdateModule {
     curve;
-    constructor(curve) {
+    constructor(curve = new Curve([
+        { t: 0, v: 1 },
+        { t: 1, v: 0 },
+    ])) {
         super();
         this.curve = curve;
     }
@@ -37407,20 +37919,53 @@ class Geometry {
 
 const sortedStopOffset = (left, right) => left.offset - right.offset;
 /**
- * CPU-rasterized gradient base that can be converted into a {@link DataTexture}.
+ * CPU-rasterized gradient base. A {@link Color}-like paint value (not a
+ * {@link Drawable}): it owns a normalized list of color stops plus subclass
+ * geometry and supports the value-object contract — {@link Gradient.clone},
+ * {@link Gradient.copy}, and {@link Gradient.equals}. Stops are cloned on the
+ * way in, clamped to `0..1`, and kept sorted by offset.
+ *
+ * Convert a gradient into a sampleable {@link DataTexture} with
+ * {@link Gradient.toTexture}; wrap that texture in a `Sprite`/`Mesh` to draw it.
  */
 class Gradient {
     _stops;
     _sample = new Float32Array(4);
     constructor(stops) {
-        if (stops.length < 2) {
-            throw new Error('Gradient requires at least 2 color stops.');
-        }
-        this._stops = [...stops].map(stop => ({ offset: clamp(stop.offset, 0, 1), color: stop.color.clone() })).sort(sortedStopOffset);
+        this._stops = Gradient._normalizeStops(stops);
     }
     get stops() {
         return this._stops;
     }
+    /**
+     * Copy every value (stops and geometry) from a same-type `source` into this
+     * instance, replacing its current state. Returns `this` for chaining.
+     */
+    copy(source) {
+        this._stops = source._stops.map(stop => ({ offset: stop.offset, color: stop.color.clone() }));
+        this._copyGeometry(source);
+        return this;
+    }
+    /**
+     * Structural value equality: same {@link GradientType}, same ordered stops
+     * (offset and {@link Color}), and same subclass geometry.
+     */
+    equals(other) {
+        if (this === other) {
+            return true;
+        }
+        if (this.type !== other.type || this._stops.length !== other._stops.length) {
+            return false;
+        }
+        for (let i = 0; i < this._stops.length; i++) {
+            const own = this._stops[i];
+            const their = other._stops[i];
+            if (own.offset !== their.offset || !own.color.equals(their.color)) {
+                return false;
+            }
+        }
+        return this._geometryEquals(other);
+    }
     toTexture(width, height, options = {}) {
         if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
             throw new Error('Gradient.toTexture() width/height must be positive integers.');
@@ -37463,6 +38008,19 @@ class Gradient {
         out[2] = previousColor.b / 255;
         out[3] = previousColor.a;
     }
+    static _normalizeStops(stops) {
+        if (stops.length < 2) {
+            throw new Error('Gradient requires at least 2 color stops.');
+        }
+        return stops
+            .map(stop => {
+            if (!Number.isFinite(stop.offset)) {
+                throw new Error('Gradient stop offset must be a finite number.');
+            }
+            return { offset: clamp(stop.offset, 0, 1), color: stop.color.clone() };
+        })
+            .sort(sortedStopOffset);
+    }
     _toRgba8Texture(width, height, options) {
         const texture = new DataTexture({
             width,
@@ -37518,6 +38076,7 @@ const toUnorm8 = (value) => (clamp(value, 0, 1) * 255 + 0.5) | 0;
  * Linear gradient in UV space projected from `start` to `end`.
  */
 class LinearGradient extends Gradient {
+    type = 'linear';
     _start;
     _end;
     constructor(stops, start = [0, 0], end = [1, 0]) {
@@ -37525,6 +38084,17 @@ class LinearGradient extends Gradient {
         this._start = [start[0], start[1]];
         this._end = [end[0], end[1]];
     }
+    /** Projection axis start point in UV space. */
+    get start() {
+        return [this._start[0], this._start[1]];
+    }
+    /** Projection axis end point in UV space. */
+    get end() {
+        return [this._end[0], this._end[1]];
+    }
+    clone() {
+        return new LinearGradient(this.stops, this._start, this._end);
+    }
     resolveT(u, v) {
         const axisX = this._end[0] - this._start[0];
         const axisY = this._end[1] - this._start[1];
@@ -37534,12 +38104,24 @@ class LinearGradient extends Gradient {
         }
         return ((u - this._start[0]) * axisX + (v - this._start[1]) * axisY) / lengthSquared;
     }
+    _copyGeometry(source) {
+        this._start = [source._start[0], source._start[1]];
+        this._end = [source._end[0], source._end[1]];
+    }
+    _geometryEquals(other) {
+        return (other instanceof LinearGradient &&
+            this._start[0] === other._start[0] &&
+            this._start[1] === other._start[1] &&
+            this._end[0] === other._end[0] &&
+            this._end[1] === other._end[1]);
+    }
 }
 
 /**
  * Radial gradient in UV space around `center` with normalized radius.
  */
 class RadialGradient extends Gradient {
+    type = 'radial';
     _center;
     _radius;
     constructor(stops, center = [0.5, 0.5], radius = 0.5) {
@@ -37547,6 +38129,17 @@ class RadialGradient extends Gradient {
         this._center = [center[0], center[1]];
         this._radius = Math.max(0, radius);
     }
+    /** Gradient center in UV space. */
+    get center() {
+        return [this._center[0], this._center[1]];
+    }
+    /** Normalized radius (UV units, clamped to be non-negative). */
+    get radius() {
+        return this._radius;
+    }
+    clone() {
+        return new RadialGradient(this.stops, this._center, this._radius);
+    }
     resolveT(u, v) {
         if (this._radius <= 0.000001) {
             return 1;
@@ -37555,6 +38148,13 @@ class RadialGradient extends Gradient {
         const dy = v - this._center[1];
         return Math.sqrt(dx * dx + dy * dy) / this._radius;
     }
+    _copyGeometry(source) {
+        this._center = [source._center[0], source._center[1]];
+        this._radius = source._radius;
+    }
+    _geometryEquals(other) {
+        return other instanceof RadialGradient && this._center[0] === other._center[0] && this._center[1] === other._center[1] && this._radius === other._radius;
+    }
 }
 
 /**
@@ -37979,23 +38579,43 @@ class SpriteMaterial extends Material {
     }
 }
 
+/**
+ * Edge length of the square gradient texture rasterized for gradient paints.
+ * The full 2D UV field is baked so both linear and radial gradients map across
+ * the filled shape's bounding box without per-axis special-casing.
+ */
+const gradientTextureSize = 256;
 /**
  * Immediate-mode 2D shape API backed by {@link Mesh} children.
  *
  * Each draw call (e.g. `drawCircle`, `drawRectangle`, `drawLine`) appends a
- * new {@link Mesh} child colored with the current `fillColor` or `lineColor`.
+ * new {@link Mesh} child painted with the active fill or stroke style. A style
+ * is either a solid {@link Color} or a {@link Gradient}, assigned through
+ * {@link fillStyle} / {@link strokeStyle}. The {@link fillColor} /
+ * {@link lineColor} accessors are color-only conveniences over those styles.
  * The active `lineWidth` controls stroke thickness for path and outline draws.
  * Path commands (`moveTo`, `lineTo`, `quadraticCurveTo`, etc.) track a cursor
  * point and flush a Mesh on each segment.
  *
+ * Gradient styles are rasterized once to a {@link DataTexture} via
+ * {@link Gradient.toTexture} and sampled across each shape's local bounding
+ * box, so {@link LinearGradient} and {@link RadialGradient} render through the
+ * same texture path as a textured Mesh. The textures are owned by the Graphics
+ * and released on {@link clear} / {@link destroy}.
+ *
  * Call {@link clear} to remove all child meshes and reset pen state. Because
  * each shape is a separate Mesh, `Graphics` inherits full filter, blend,
  * tint, and mask support from {@link Container}.
  */
 class Graphics extends Container {
     _lineWidth = 0;
-    _lineColor = new Color();
     _fillColor = new Color();
+    _lineColor = new Color();
+    _fillStyle = this._fillColor;
+    _strokeStyle = this._lineColor;
+    _fillStyleTexture = null;
+    _strokeStyleTexture = null;
+    _ownedTextures = new Set();
     _currentPoint = new Vector(0, 0);
     get lineWidth() {
         return this._lineWidth;
@@ -38003,17 +38623,59 @@ class Graphics extends Container {
     set lineWidth(lineWidth) {
         this._lineWidth = lineWidth;
     }
+    /** Solid stroke color slot: the last solid color assigned to the stroke. */
     get lineColor() {
         return this._lineColor;
     }
+    /**
+     * Convenience solid-color setter for the stroke. Copies `lineColor` into the
+     * color slot and makes it the active {@link strokeStyle}, replacing any
+     * gradient stroke style.
+     */
     set lineColor(lineColor) {
-        this._lineColor.copy(lineColor);
+        this.strokeStyle = lineColor;
     }
+    /** Solid fill color slot: the last solid color assigned to the fill. */
     get fillColor() {
         return this._fillColor;
     }
+    /**
+     * Convenience solid-color setter for the fill. Copies `fillColor` into the
+     * color slot and makes it the active {@link fillStyle}, replacing any
+     * gradient fill style.
+     */
     set fillColor(fillColor) {
-        this._fillColor.copy(fillColor);
+        this.fillStyle = fillColor;
+    }
+    /** Active fill style: a solid {@link Color} or a {@link Gradient}. */
+    get fillStyle() {
+        return this._fillStyle;
+    }
+    /**
+     * Set the fill style. Accepts a solid {@link Color}, a {@link Gradient}
+     * (cloned on assignment and rasterized lazily on first fill), or `null` to
+     * revert to the solid color held by {@link fillColor}. A {@link Color} value
+     * is copied into the {@link fillColor} slot; the most recently assigned style
+     * wins.
+     */
+    set fillStyle(style) {
+        this._fillStyle = this._resolveStyle(style, this._fillColor);
+        this._fillStyleTexture = null;
+    }
+    /** Active stroke style: a solid {@link Color} or a {@link Gradient}. */
+    get strokeStyle() {
+        return this._strokeStyle;
+    }
+    /**
+     * Set the stroke style. Accepts a solid {@link Color}, a {@link Gradient}
+     * (cloned on assignment and rasterized lazily on first stroke), or `null` to
+     * revert to the solid color held by {@link lineColor}. A {@link Color} value
+     * is copied into the {@link lineColor} slot; the most recently assigned style
+     * wins.
+     */
+    set strokeStyle(style) {
+        this._strokeStyle = this._resolveStyle(style, this._lineColor);
+        this._strokeStyleTexture = null;
     }
     get currentPoint() {
         return this._currentPoint;
@@ -38137,19 +38799,19 @@ class Graphics extends Container {
     /** Draw a stroked line between two explicit points, independent of the current pen position. */
     drawLine(startX, startY, endX, endY) {
         const data = buildLine(startX, startY, endX, endY, this._lineWidth);
-        this.addChild(this._createMesh(data, this._lineColor));
+        this.addChild(this._createStrokeMesh(data));
         return this;
     }
     /** Draw a stroked polyline from a flat `[x0,y0, x1,y1, ...]` coordinate array. */
     drawPath(path) {
         const data = buildPath(path, this._lineWidth);
-        this.addChild(this._createMesh(data, this._lineColor));
+        this.addChild(this._createStrokeMesh(data));
         return this;
     }
     /** Fill a closed polygon defined by `[x0,y0, x1,y1, ...]` and optionally stroke its outline. */
     drawPolygon(path) {
         const data = buildPolygon(path);
-        this.addChild(this._createMesh(data, this._fillColor));
+        this.addChild(this._createFillMesh(data));
         if (this._lineWidth > 0) {
             this.drawPath(data.points);
         }
@@ -38158,7 +38820,7 @@ class Graphics extends Container {
     /** Fill a circle and optionally stroke its outline if `lineWidth > 0`. */
     drawCircle(centerX, centerY, radius) {
         const data = buildCircle(centerX, centerY, radius);
-        this.addChild(this._createMesh(data, this._fillColor));
+        this.addChild(this._createFillMesh(data));
         if (this._lineWidth > 0) {
             this.drawPath(data.points);
         }
@@ -38167,7 +38829,7 @@ class Graphics extends Container {
     /** Fill an ellipse and optionally stroke its outline if `lineWidth > 0`. */
     drawEllipse(centerX, centerY, radiusX, radiusY) {
         const data = buildEllipse(centerX, centerY, radiusX, radiusY);
-        this.addChild(this._createMesh(data, this._fillColor));
+        this.addChild(this._createFillMesh(data));
         if (this._lineWidth > 0) {
             this.drawPath(data.points);
         }
@@ -38176,7 +38838,7 @@ class Graphics extends Container {
     /** Fill a rectangle and optionally stroke its outline if `lineWidth > 0`. */
     drawRectangle(x, y, width, height) {
         const data = buildRectangle(x, y, width, height);
-        this.addChild(this._createMesh(data, this._fillColor));
+        this.addChild(this._createFillMesh(data));
         if (this._lineWidth > 0) {
             this.drawPath(data.points);
         }
@@ -38188,18 +38850,23 @@ class Graphics extends Container {
      */
     drawStar(centerX, centerY, points, radius, innerRadius = radius / 2, rotation = 0) {
         const data = buildStar(centerX, centerY, points, radius, innerRadius, rotation);
-        this.addChild(this._createMesh(data, this._fillColor));
+        this.addChild(this._createFillMesh(data));
         if (this._lineWidth > 0) {
             this.drawPath(data.points);
         }
         return this;
     }
-    /** Remove all child meshes and reset pen state (position, colors, line width). */
+    /** Remove all child meshes and reset pen state (position, fill/stroke styles, line width). */
     clear() {
         this.removeChildren();
         this._lineWidth = 0;
-        this._lineColor.copy(Color.black);
         this._fillColor.copy(Color.black);
+        this._lineColor.copy(Color.black);
+        this._fillStyle = this._fillColor;
+        this._strokeStyle = this._lineColor;
+        this._fillStyleTexture = null;
+        this._strokeStyleTexture = null;
+        this._destroyOwnedTextures();
         this._currentPoint.set(0, 0);
         return this;
     }
@@ -38210,7 +38877,38 @@ class Graphics extends Container {
         this._fillColor.destroy();
         this._currentPoint.destroy();
     }
-    _createMesh(data, color) {
+    /**
+     * Resolve an assigned style into the stored paint. A {@link Color} is copied
+     * into the solid `colorSlot` (keeping the {@link fillColor} / {@link lineColor}
+     * convenience getters in sync) and that slot is returned; `null` reverts to
+     * the slot; a {@link Gradient} is cloned so later external mutation cannot
+     * change the stored paint.
+     */
+    _resolveStyle(style, colorSlot) {
+        if (style === null) {
+            return colorSlot;
+        }
+        if (style instanceof Color) {
+            colorSlot.copy(style);
+            return colorSlot;
+        }
+        return style.clone();
+    }
+    _createFillMesh(data) {
+        if (this._fillStyle instanceof Color) {
+            return this._createSolidMesh(data, this._fillStyle);
+        }
+        this._fillStyleTexture ??= this._rasterizeGradient(this._fillStyle);
+        return this._createGradientMesh(data, this._fillStyleTexture);
+    }
+    _createStrokeMesh(data) {
+        if (this._strokeStyle instanceof Color) {
+            return this._createSolidMesh(data, this._strokeStyle);
+        }
+        this._strokeStyleTexture ??= this._rasterizeGradient(this._strokeStyle);
+        return this._createGradientMesh(data, this._strokeStyleTexture);
+    }
+    _createSolidMesh(data, color) {
         const mesh = new Mesh({
             vertices: data.vertices,
             indices: data.indices,
@@ -38218,7 +38916,66 @@ class Graphics extends Container {
         mesh.tint = color;
         return mesh;
     }
-}
+    /**
+     * Build a textured mesh whose UVs span the shape's local bounding box, so the
+     * gradient texture samples across the filled/stroked geometry. The default
+     * white tint and vertex color leave the sampled gradient color unmodulated.
+     */
+    _createGradientMesh(data, texture) {
+        return new Mesh({
+            vertices: data.vertices,
+            indices: data.indices,
+            uvs: computeBoundsUvs(data.vertices),
+            texture,
+        });
+    }
+    _rasterizeGradient(gradient) {
+        const texture = gradient.toTexture(gradientTextureSize, gradientTextureSize, {
+            samplerOptions: { scaleMode: ScaleModes.Linear },
+        });
+        this._ownedTextures.add(texture);
+        return texture;
+    }
+    _destroyOwnedTextures() {
+        for (const texture of this._ownedTextures) {
+            texture.destroy();
+        }
+        this._ownedTextures.clear();
+    }
+}
+/**
+ * Normalize each `(x, y)` vertex into `0..1` UV space relative to the flat
+ * vertex array's axis-aligned bounding box. Degenerate (zero-width/height)
+ * spans collapse to `0` to avoid division by zero.
+ */
+const computeBoundsUvs = (vertices) => {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (let i = 0; i < vertices.length; i += 2) {
+        const x = vertices[i];
+        const y = vertices[i + 1];
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+    }
+    const spanX = maxX - minX;
+    const spanY = maxY - minY;
+    const invX = spanX > 0 ? 1 / spanX : 0;
+    const invY = spanY > 0 ? 1 / spanY : 0;
+    const uvs = new Float32Array(vertices.length);
+    for (let i = 0; i < vertices.length; i += 2) {
+        uvs[i] = (vertices[i] - minX) * invX;
+        uvs[i + 1] = (vertices[i + 1] - minY) * invY;
+    }
+    return uvs;
+};
 
 const defaultClipFps = 12;
 /**