@codexo/exojs 0.10.0 → 0.11.0

package/dist/esm/rendering/gradient/RadialGradient.js

@@ -4,6 +4,7 @@ import { Gradient } from './Gradient.js';
  * 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) {
@@ -11,6 +12,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;
@@ -19,6 +31,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;
+    }
 }
 
 export { RadialGradient };

package/dist/esm/rendering/gradient/RadialGradient.js.map

@@ -1 +1 @@
-{"version":3,"file":"RadialGradient.js","sources":["../../../../../src/rendering/gradient/RadialGradient.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;AAEG;AACG,MAAO,cAAe,SAAQ,QAAQ,CAAA;AACzB,IAAA,OAAO;AACP,IAAA,OAAO;IAExB,WAAA,CAAmB,KAA8B,EAAE,MAAA,GAAoC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,EAAA;QAC7G,KAAK,CAAC,KAAK,CAAC;AAEZ,QAAA,IAAI,CAAC,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC;IACpC;IAEmB,QAAQ,CAAC,CAAS,EAAE,CAAS,EAAA;AAC9C,QAAA,IAAI,IAAI,CAAC,OAAO,IAAI,QAAQ,EAAE;AAC5B,YAAA,OAAO,CAAC;QACV;QAEA,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9B,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAE9B,QAAA,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO;IACpD;AACD;;;;"}
+{"version":3,"file":"RadialGradient.js","sources":["../../../../../src/rendering/gradient/RadialGradient.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;AAEG;AACG,MAAO,cAAe,SAAQ,QAAQ,CAAA;IAC1B,IAAI,GAAiB,QAAQ;AAErC,IAAA,OAAO;AACP,IAAA,OAAO;IAEf,WAAA,CAAmB,KAA8B,EAAE,MAAA,GAAoC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,EAAA;QAC7G,KAAK,CAAC,KAAK,CAAC;AAEZ,QAAA,IAAI,CAAC,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC;IACpC;;AAGA,IAAA,IAAW,MAAM,GAAA;AACf,QAAA,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3C;;AAGA,IAAA,IAAW,MAAM,GAAA;QACf,OAAO,IAAI,CAAC,OAAO;IACrB;IAEO,KAAK,GAAA;AACV,QAAA,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAS;IAC3E;IAEmB,QAAQ,CAAC,CAAS,EAAE,CAAS,EAAA;AAC9C,QAAA,IAAI,IAAI,CAAC,OAAO,IAAI,QAAQ,EAAE;AAC5B,YAAA,OAAO,CAAC;QACV;QAEA,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9B,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAE9B,QAAA,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO;IACpD;AAEmB,IAAA,aAAa,CAAC,MAAsB,EAAA;AACrD,QAAA,IAAI,CAAC,OAAO,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACrD,QAAA,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO;IAC/B;AAEmB,IAAA,eAAe,CAAC,KAAe,EAAA;AAChD,QAAA,OAAO,KAAK,YAAY,cAAc,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO;IAC1J;AACD;;;;"}

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

@@ -15,7 +15,7 @@ export type { WebGpuShaderFilterOptions } from './filters/WebGpuShaderFilter';
 export { WebGpuShaderFilter } from './filters/WebGpuShaderFilter';
 export { Geometry } from './geometry/Geometry';
 export type { AttributeType, GeometryAttribute, GeometryOptions, GeometryUsage, Topology } from './geometry/GeometryAttribute';
-export type { GradientStop, GradientToTextureOptions } from './gradient/Gradient';
+export type { GradientStop, GradientToTextureOptions, GradientType } from './gradient/Gradient';
 export { Gradient } from './gradient/Gradient';
 export { LinearGradient } from './gradient/LinearGradient';
 export { RadialGradient } from './gradient/RadialGradient';

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

@@ -6,8 +6,8 @@ import type { View } from '../View';
 import type { RenderPassDescriptor, RenderPassLoad } from './RenderPassDescriptor';
 /**
  * Internal, backend-owned owner of render-pass lifecycle: target / view / clear
- * orchestration, the scissor and stencil-clip stacks, and — on WebGPU, from
- * phase 12D — the active `GPURenderPassEncoder`.
+ * orchestration, the scissor and stencil-clip stacks, and — on WebGPU — the
+ * active `GPURenderPassEncoder`.
  *
  * There is no public RenderPass API. This abstraction exists so the WebGL2 and
  * WebGPU backends can share the orchestration shape that geometric stencil

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

@@ -5,7 +5,7 @@ import type { View } from '../View';
  * Whether a render pass carries a stencil attachment.
  *
  * WebGL2 stencil is ambient per-target GL state, so this flag is largely
- * informational there; the WebGPU backend (from phase 12D onwards) uses it to
+ * informational there; the WebGPU backend uses it to
  * decide whether a pass descriptor needs a `depthStencilAttachment`.
  * @internal
  */
@@ -21,7 +21,7 @@ export type RenderPassLoad = 'clear' | 'load';
  * it carries a stencil attachment.
  *
  * WebGL2 maps this onto ambient framebuffer / viewport / scissor / stencil
- * state; WebGPU (phase 12D onwards) maps it onto a `GPURenderPassEncoder`.
+ * state; WebGPU maps it onto a `GPURenderPassEncoder`.
  * @internal
  */
 export interface RenderPassDescriptor {

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

@@ -2,7 +2,7 @@
  * 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
  */

package/dist/esm/rendering/plan/RenderCommand.d.ts

@@ -21,8 +21,8 @@ export declare const enum RenderEntryKind {
  *   group / texture-slot state.
  *
  * When the drawable carries a {@link Material}, both keys are taken
- * directly from `material.pipelineKey` and `material.bindKey` (Phase 4+
- * Material system). When the drawable uses its default path (no material),
+ * directly from `material.pipelineKey` and `material.bindKey` (the Material
+ * system). When the drawable uses its default path (no material),
  * the keys are derived conservatively from renderer identity, blend mode,
  * and texture identity so grouping never accidentally merges draws with
  * incompatible state.
@@ -65,3 +65,22 @@ export interface DrawCommand {
  * @internal
  */
 export declare const makeMaterialKey: (drawable: Drawable, backend: RenderBackend | null) => MaterialKey;
+/**
+ * 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
+ */
+export declare const drawCommandUsesSharedTransform: (command: DrawCommand, backend: RenderBackend) => boolean;

package/dist/esm/rendering/plan/RenderCommand.js

@@ -89,6 +89,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;
+    }
+};
 
-export { RenderEntryKind, makeMaterialKey };
+export { RenderEntryKind, drawCommandUsesSharedTransform, makeMaterialKey };
 //# sourceMappingURL=RenderCommand.js.map

package/dist/esm/rendering/plan/RenderCommand.js.map

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

package/dist/esm/rendering/plan/RenderInstruction.d.ts

@@ -0,0 +1,51 @@
+import { type DrawCommand, type MaterialKey } from './RenderCommand';
+import type { GroupScope } from './RenderScope';
+/**
+ * The canonical, reorderable unit of work in a render plan: a single draw
+ * that the plan player submits to the backend.
+ *
+ * Today a render instruction is exactly a {@link DrawCommand}; the alias
+ * names the concept the plan player consumes and that the batching layer
+ * reorders, independent of how the draw happens to be stored in the scope
+ * tree. Future {@link TransformBuffer} slotting keys on each instruction's
+ * stable {@link DrawCommand.nodeIndex} (within the `[0, plan.nodeCount)`
+ * slot space).
+ *
+ * @internal
+ */
+export type RenderInstruction = DrawCommand;
+/**
+ * A materialized batch unit: a maximal run of consecutive
+ * {@link RenderInstruction}s within a single {@link GroupScope} that share a
+ * GPU pipeline/bind state and may therefore be submitted together.
+ *
+ * The optimizer ({@link RenderPlanOptimizer}) already stamps this grouping
+ * implicitly onto each {@link DrawCommand.groupIndex}; a `RenderGroup` makes
+ * that batch unit explicit as a value without altering playback. The mesh
+ * renderers continue to detect batches by comparing adjacent `groupIndex`es,
+ * so this representation is purely additive.
+ *
+ * @internal
+ */
+export interface RenderGroup {
+    /** Optimizer-assigned batch identity shared by every instruction in the run. */
+    readonly groupIndex: number;
+    /** Pipeline/bind state shared by the run; taken from its first instruction. */
+    readonly material: MaterialKey;
+    /** Draw instructions in submit order. */
+    readonly instructions: readonly RenderInstruction[];
+}
+/**
+ * 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
+ */
+export declare function collectRenderGroups(scope: GroupScope): RenderGroup[];

package/dist/esm/rendering/plan/RenderInstruction.js

@@ -0,0 +1,45 @@
+import { RenderEntryKind } from './RenderCommand.js';
+
+/**
+ * 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;
+}
+
+export { collectRenderGroups };
+//# sourceMappingURL=RenderInstruction.js.map

package/dist/esm/rendering/plan/RenderInstruction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderInstruction.js","sources":["../../../../../src/rendering/plan/RenderInstruction.ts"],"sourcesContent":[null],"names":[],"mappings":";;AA8CA;;;;;;;;;;;;AAYG;AACG,SAAU,mBAAmB,CAAC,KAAiB,EAAA;IACnD,MAAM,MAAM,GAAkB,EAAE;IAChC,IAAI,OAAO,GAA8B,IAAI;AAE7C,IAAA,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE;QACjC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI,EAAE;YACvC,OAAO,GAAG,IAAI;YAEd;QACF;AAEA,QAAA,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO;AAC7B,QAAA,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU;AAErC,QAAA,IAAI,OAAO,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,OAAO,CAAC,UAAU,EAAE;AACrF,YAAA,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC;YAElC;QACF;AAEA,QAAA,OAAO,GAAG;YACR,UAAU,EAAE,UAAU,IAAI,CAAC;YAC3B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,YAAY,EAAE,CAAC,OAAO,CAAC;SACxB;AACD,QAAA,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;AAEpB,QAAA,IAAI,UAAU,KAAK,SAAS,EAAE;;YAE5B,OAAO,GAAG,IAAI;QAChB;IACF;AAEA,IAAA,OAAO,MAAM;AACf;;;;"}

package/dist/esm/rendering/plan/RenderPlanPlayer.d.ts

@@ -5,5 +5,9 @@ import type { RenderScope } from './RenderScope';
 export declare class RenderPlanPlayer {
     static play(plan: RenderPlan, backend: RenderBackend): void;
     static playScope(scope: RenderScope, backend: RenderBackend): void;
+    private static _playScope;
     private static _playGroup;
+    private static _createPlaybackContext;
+    private static _createRenderGroupPlaybackContext;
+    private static _createRenderInstructionSlot;
 }

package/dist/esm/rendering/plan/RenderPlanPlayer.js

@@ -1,5 +1,6 @@
 import { RenderEntryKind } from './RenderCommand.js';
 import { RenderEffectExecutor } from './RenderEffectExecutor.js';
+import { collectRenderGroups } from './RenderInstruction.js';
 
 /** @internal */
 class RenderPlanPlayer {
@@ -17,7 +18,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 {
@@ -25,31 +26,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,
+        });
+    }
 }
 
 export { RenderPlanPlayer };

package/dist/esm/rendering/plan/RenderPlanPlayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"RenderPlanPlayer.js","sources":["../../../../../src/rendering/plan/RenderPlanPlayer.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAcA;MACa,gBAAgB,CAAA;AACpB,IAAA,OAAO,IAAI,CAAC,IAAgB,EAAE,OAAsB,EAAA;QACzD,MAAM,KAAK,GAAG,OAAkD;QAEhE,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC;AAEtC,QAAA,IAAI;AACF,YAAA,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE;AAC9B,gBAAA,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,YAAY,KAAK,IAAI,CAAC,MAAM,EAAE;AAChE,oBAAA,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC;gBACtC;gBAEA,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE;AAC9B,oBAAA,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;gBAC5B;AAEA,gBAAA,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,EAAE;AAC5B,oBAAA,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC;gBAChC;gBAEA,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC;YACpC;QACF;gBAAU;AACR,YAAA,KAAK,CAAC,YAAY,IAAI;QACxB;IACF;AAEO,IAAA,OAAO,SAAS,CAAC,KAAkB,EAAE,OAAsB,EAAA;QAChE,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,OAAO,EAAE;YAC1C,oBAAoB,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,IAAG;AACrD,gBAAA,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,OAAO,CAAC;AACrC,YAAA,CAAC,CAAC;YAEF;QACF;AAEA,QAAA,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;IACjC;AAEQ,IAAA,OAAO,UAAU,CAAC,KAAiB,EAAE,OAAsB,EAAA;QACjE,MAAM,KAAK,GAAG,OAAkD;AAEhE,QAAA,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE;YACjC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI,EAAE;gBACvC,KAAK,CAAC,mBAAmB,GAAG,KAAK,CAAC,OAAO,CAAC;gBAC1C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;YACtC;iBAAO,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,KAAK,EAAE;gBAC/C,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC;YACvC;iBAAO;gBACL,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,IAAG;AAC3D,oBAAA,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,OAAO,CAAC;AACrC,gBAAA,CAAC,CAAC;YACJ;QACF;IACF;AACD;;;;"}
+{"version":3,"file":"RenderPlanPlayer.js","sources":["../../../../../src/rendering/plan/RenderPlanPlayer.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAmCA;MACa,gBAAgB,CAAA;AACpB,IAAA,OAAO,IAAI,CAAC,IAAgB,EAAE,OAAsB,EAAA;QACzD,MAAM,KAAK,GAAG,OAAkD;QAEhE,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC;AAEtC,QAAA,IAAI;AACF,YAAA,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE;AAC9B,gBAAA,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,YAAY,KAAK,IAAI,CAAC,MAAM,EAAE;AAChE,oBAAA,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC;gBACtC;gBAEA,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE;AAC9B,oBAAA,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;gBAC5B;AAEA,gBAAA,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,EAAE;AAC5B,oBAAA,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC;gBAChC;AAEA,gBAAA,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,sBAAsB,EAAE,CAAC;YAC3E;QACF;gBAAU;AACR,YAAA,KAAK,CAAC,YAAY,IAAI;QACxB;IACF;AAEO,IAAA,OAAO,SAAS,CAAC,KAAkB,EAAE,OAAsB,EAAA;QAChE,MAAM,KAAK,GAAG,OAAkD;AAEhE,QAAA,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,sBAAsB,EAAE,CAAC;IACvE;IAEQ,OAAO,UAAU,CAAC,KAAkB,EAAE,OAAsB,EAAE,KAA8B,EAAE,OAAkC,EAAA;QACtI,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,OAAO,EAAE;YAC1C,oBAAoB,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,IAAG;gBACrD,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC;AACtD,YAAA,CAAC,CAAC;YAEF;QACF;QAEA,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC;IACjD;IAEQ,OAAO,UAAU,CAAC,KAAiB,EAAE,OAAsB,EAAE,KAA8B,EAAE,OAAkC,EAAA;AACrI,QAAA,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC;QACzC,IAAI,WAAW,GAAG,CAAC;QACnB,IAAI,YAAY,GAAuB,IAAI;QAC3C,IAAI,uBAAuB,GAAG,CAAC;AAE/B,QAAA,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE;YACjC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI,EAAE;AACvC,gBAAA,IAAI,YAAY,KAAK,IAAI,EAAE;AACzB,oBAAA,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC;oBAClC,uBAAuB,GAAG,CAAC;AAE3B,oBAAA,KAAK,CAAC,iBAAiB,GAAG,YAAY,CAAC;oBACvC,KAAK,CAAC,yBAAyB,GAC7B,YAAY,EACZ,IAAI,CAAC,iCAAiC,CAAC,YAAY,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,cAAc,CAAC,CAC/H;oBACD,OAAO,CAAC,cAAc,EAAE;gBAC1B;;;;;AAMA,gBAAA,IAAI,KAAK,CAAC,6BAA6B,KAAK,SAAS,EAAE;AACrD,oBAAA,MAAM,IAAI,GAAG,IAAI,CAAC,4BAA4B,CAAC,uBAAuB,EAAE,OAAO,CAAC,oBAAoB,CAAC;oBAErG,KAAK,CAAC,6BAA6B,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC;gBAC1D;gBAEA,KAAK,CAAC,mBAAmB,GAAG,KAAK,CAAC,OAAO,CAAC;gBAC1C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;AAEpC,gBAAA,uBAAuB,EAAE;gBACzB,OAAO,CAAC,oBAAoB,EAAE;AAE9B,gBAAA,IAAI,YAAY,KAAK,IAAI,IAAI,uBAAuB,KAAK,YAAY,CAAC,YAAY,CAAC,MAAM,EAAE;AACzF,oBAAA,KAAK,CAAC,eAAe,GAAG,YAAY,CAAC;oBACrC,YAAY,GAAG,IAAI;oBACnB,uBAAuB,GAAG,CAAC;AAC3B,oBAAA,WAAW,EAAE;gBACf;YACF;iBAAO,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,KAAK,EAAE;AAC/C,gBAAA,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC;YACvD;iBAAO;gBACL,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,IAAG;oBAC3D,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC;AACtD,gBAAA,CAAC,CAAC;YACJ;QACF;IACF;AAEQ,IAAA,OAAO,sBAAsB,GAAA;QACnC,OAAO;AACL,YAAA,oBAAoB,EAAE,CAAC;AACvB,YAAA,cAAc,EAAE,CAAC;SAClB;IACH;AAEQ,IAAA,OAAO,iCAAiC,CAC9C,qBAA6B,EAC7B,yBAAiC,EACjC,cAAsB,EAAA;QAEtB,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,qBAAqB;YACrB,yBAAyB;AACzB,YAAA,wBAAwB,EAAE,yBAAyB,GAAG,qBAAqB,GAAG,CAAC;YAC/E,cAAc;AACf,SAAA,CAAC;IACJ;AAEQ,IAAA,OAAO,4BAA4B,CAAC,qBAA6B,EAAE,oBAA4B,EAAA;QACrG,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,qBAAqB;YACrB,oBAAoB;AACrB,SAAA,CAAC;IACJ;AACD;;;;"}

package/dist/esm/rendering/primitives/Graphics.d.ts

@@ -1,32 +1,79 @@
 import { Color } from '@/core/Color';
 import { Vector } from '@/math/Vector';
 import { Container } from '@/rendering/Container';
+import type { Gradient } from '@/rendering/gradient/Gradient';
 import { Mesh } from '@/rendering/mesh/Mesh';
 import type { RenderNode } from '@/rendering/RenderNode';
 /**
  * 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}.
  */
 export declare class Graphics extends Container {
     private _lineWidth;
-    private _lineColor;
-    private _fillColor;
+    private readonly _fillColor;
+    private readonly _lineColor;
+    private _fillStyle;
+    private _strokeStyle;
+    private _fillStyleTexture;
+    private _strokeStyleTexture;
+    private readonly _ownedTextures;
     private _currentPoint;
     get lineWidth(): number;
     set lineWidth(lineWidth: number);
+    /** Solid stroke color slot: the last solid color assigned to the stroke. */
     get lineColor(): Color;
+    /**
+     * 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: Color);
+    /** Solid fill color slot: the last solid color assigned to the fill. */
     get fillColor(): Color;
+    /**
+     * 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: Color);
+    /** Active fill style: a solid {@link Color} or a {@link Gradient}. */
+    get fillStyle(): Color | Gradient;
+    /**
+     * 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: Color | Gradient | null);
+    /** Active stroke style: a solid {@link Color} or a {@link Gradient}. */
+    get strokeStyle(): Color | Gradient;
+    /**
+     * 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: Color | Gradient | null);
     get currentPoint(): Vector;
     getChildAt(index: number): Mesh;
     addChild(child: RenderNode): this;
@@ -64,8 +111,26 @@ export declare class Graphics extends Container {
      * `innerRadius` defaults to half of `radius`.
      */
     drawStar(centerX: number, centerY: number, points: number, radius: number, innerRadius?: number, rotation?: number): 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;
     destroy(): void;
-    private _createMesh;
+    /**
+     * 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.
+     */
+    private _resolveStyle;
+    private _createFillMesh;
+    private _createStrokeMesh;
+    private _createSolidMesh;
+    /**
+     * 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.
+     */
+    private _createGradientMesh;
+    private _rasterizeGradient;
+    private _destroyOwnedTextures;
 }