@codexo/exojs 0.8.4 → 0.10.0

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

@@ -1,6 +1,7 @@
 /**
  * Per-frame rendering counters collected by the backend each tick.
  * Expose live performance data for debugging and profiling tools.
+ * @advanced
  */
 export interface RenderStats {
     /** Monotonically increasing frame index, incremented by {@link resetRenderStats}. */
@@ -19,6 +20,14 @@ export interface RenderStats {
     renderTargetChanges: number;
     /** Wall-clock duration of the frame in milliseconds. */
     frameTimeMs: number;
+    /**
+     * Raw wall-clock delta between this frame and the previous one, in
+     * milliseconds. May exceed the clamped simulation delta when the engine's
+     * internal `MAX_DELTA_MS` guard activates (e.g. after a debugger pause or
+     * device sleep/resume). Use this for profiling to distinguish actual elapsed
+     * time from the clamped simulation delta passed to update recipients.
+     */
+    rawFrameDeltaMs: number;
 }
 /**
  * Allocate a zeroed {@link RenderStats} object for the first frame.

package/dist/esm/rendering/RenderStats.js

@@ -10,6 +10,7 @@ const createRenderStats = () => ({
     renderPasses: 0,
     renderTargetChanges: 0,
     frameTimeMs: 0,
+    rawFrameDeltaMs: 0,
 });
 /**
  * Advance the frame counter and zero all per-frame accumulators in place.
@@ -24,6 +25,7 @@ const resetRenderStats = (stats) => {
     stats.renderPasses = 0;
     stats.renderTargetChanges = 0;
     stats.frameTimeMs = 0;
+    stats.rawFrameDeltaMs = 0;
     return stats;
 };
 

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

@@ -1 +1 @@
-{"version":3,"file":"RenderStats.js","sources":["../../../../src/rendering/RenderStats.ts"],"sourcesContent":[null],"names":[],"mappings":"AAuBA;;AAEG;AACI,MAAM,iBAAiB,GAAG,OAAoB;AACnD,IAAA,KAAK,EAAE,CAAC;AACR,IAAA,cAAc,EAAE,CAAC;AACjB,IAAA,WAAW,EAAE,CAAC;AACd,IAAA,SAAS,EAAE,CAAC;AACZ,IAAA,OAAO,EAAE,CAAC;AACV,IAAA,YAAY,EAAE,CAAC;AACf,IAAA,mBAAmB,EAAE,CAAC;AACtB,IAAA,WAAW,EAAE,CAAC;AACf,CAAA;AAED;;;AAGG;AACI,MAAM,gBAAgB,GAAG,CAAC,KAAkB,KAAiB;IAClE,KAAK,CAAC,KAAK,EAAE;AACb,IAAA,KAAK,CAAC,cAAc,GAAG,CAAC;AACxB,IAAA,KAAK,CAAC,WAAW,GAAG,CAAC;AACrB,IAAA,KAAK,CAAC,SAAS,GAAG,CAAC;AACnB,IAAA,KAAK,CAAC,OAAO,GAAG,CAAC;AACjB,IAAA,KAAK,CAAC,YAAY,GAAG,CAAC;AACtB,IAAA,KAAK,CAAC,mBAAmB,GAAG,CAAC;AAC7B,IAAA,KAAK,CAAC,WAAW,GAAG,CAAC;AAErB,IAAA,OAAO,KAAK;AACd;;;;"}
+{"version":3,"file":"RenderStats.js","sources":["../../../../src/rendering/RenderStats.ts"],"sourcesContent":[null],"names":[],"mappings":"AAgCA;;AAEG;AACI,MAAM,iBAAiB,GAAG,OAAoB;AACnD,IAAA,KAAK,EAAE,CAAC;AACR,IAAA,cAAc,EAAE,CAAC;AACjB,IAAA,WAAW,EAAE,CAAC;AACd,IAAA,SAAS,EAAE,CAAC;AACZ,IAAA,OAAO,EAAE,CAAC;AACV,IAAA,YAAY,EAAE,CAAC;AACf,IAAA,mBAAmB,EAAE,CAAC;AACtB,IAAA,WAAW,EAAE,CAAC;AACd,IAAA,eAAe,EAAE,CAAC;AACnB,CAAA;AAED;;;AAGG;AACI,MAAM,gBAAgB,GAAG,CAAC,KAAkB,KAAiB;IAClE,KAAK,CAAC,KAAK,EAAE;AACb,IAAA,KAAK,CAAC,cAAc,GAAG,CAAC;AACxB,IAAA,KAAK,CAAC,WAAW,GAAG,CAAC;AACrB,IAAA,KAAK,CAAC,SAAS,GAAG,CAAC;AACnB,IAAA,KAAK,CAAC,OAAO,GAAG,CAAC;AACjB,IAAA,KAAK,CAAC,YAAY,GAAG,CAAC;AACtB,IAAA,KAAK,CAAC,mBAAmB,GAAG,CAAC;AAC7B,IAAA,KAAK,CAAC,WAAW,GAAG,CAAC;AACrB,IAAA,KAAK,CAAC,eAAe,GAAG,CAAC;AAEzB,IAAA,OAAO,KAAK;AACd;;;;"}

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

@@ -13,6 +13,19 @@ import { View } from './View';
  * the underlying canvas / texture dimensions change.
  */
 export declare class RenderTarget {
+    /**
+     * Whether this target needs a stencil attachment for geometric stencil
+     * clipping ({@link RenderNode.clip} with a `Geometry` `clipShape`). Set by the
+     * WebGL2 backend when such a clip is rendered into an offscreen
+     * {@link RenderTexture}, so its framebuffer gets a depth/stencil renderbuffer;
+     * the WebGL2 on-screen root uses the default framebuffer's stencil (requested
+     * at context creation), so the flag only affects offscreen WebGL2 targets.
+     *
+     * The WebGPU backend does not consult this flag: it allocates a separate
+     * `depth24plus-stencil8` attachment per clipped target (root included) on
+     * demand, sized to the colour attachment's physical pixels.
+     */
+    needsStencil: boolean;
     private readonly _root;
     private readonly _destroyListeners;
     private _version;

package/dist/esm/rendering/RenderTarget.js

@@ -14,6 +14,19 @@ import { View } from './View.js';
  * the underlying canvas / texture dimensions change.
  */
 class RenderTarget {
+    /**
+     * Whether this target needs a stencil attachment for geometric stencil
+     * clipping ({@link RenderNode.clip} with a `Geometry` `clipShape`). Set by the
+     * WebGL2 backend when such a clip is rendered into an offscreen
+     * {@link RenderTexture}, so its framebuffer gets a depth/stencil renderbuffer;
+     * the WebGL2 on-screen root uses the default framebuffer's stencil (requested
+     * at context creation), so the flag only affects offscreen WebGL2 targets.
+     *
+     * The WebGPU backend does not consult this flag: it allocates a separate
+     * `depth24plus-stencil8` attachment per clipped target (root included) on
+     * demand, sized to the colour attachment's physical pixels.
+     */
+    needsStencil = false;
     _root;
     _destroyListeners = new Set();
     _version = 0;

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

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

package/dist/esm/rendering/RenderTargetPass.js

@@ -1,3 +1,5 @@
+import { StencilAttachmentMode } from './pass/RenderPassDescriptor.js';
+
 /**
  * A {@link RenderPass} that redirects rendering into an off-screen {@link RenderTarget}.
  *
@@ -17,6 +19,21 @@ class RenderTargetPass {
         this._clearColor = options.clearColor ?? null;
     }
     execute(backend) {
+        const coordinator = backend._passCoordinator;
+        if (coordinator) {
+            coordinator.withChildPass({
+                target: this._target,
+                view: this._view,
+                load: this._clearColor !== null ? 'clear' : 'load',
+                clearColor: this._clearColor,
+                stencil: StencilAttachmentMode.None,
+            }, () => {
+                this._callback(backend);
+            });
+            return;
+        }
+        // Legacy fallback for backends without a pass coordinator (e.g. test stubs):
+        // save the target/view, run the callback, then restore — even if it throws.
         const previousTarget = backend.renderTarget;
         const previousView = backend.view;
         backend.setRenderTarget(this._target);

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

@@ -1 +1 @@
-{"version":3,"file":"RenderTargetPass.js","sources":["../../../../src/rendering/RenderTargetPass.ts"],"sourcesContent":[null],"names":[],"mappings":"AAiBA;;;;;;AAMG;MACU,gBAAgB,CAAA;AACV,IAAA,SAAS;AACT,IAAA,OAAO;AACP,IAAA,KAAK;AACL,IAAA,WAAW;IAE5B,WAAA,CAAmB,QAA0C,EAAE,OAAA,GAAmC,EAAE,EAAA;AAClG,QAAA,IAAI,CAAC,SAAS,GAAG,QAAQ;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI;QACrC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI;IAC/C;AAEO,IAAA,OAAO,CAAC,OAAsB,EAAA;AACnC,QAAA,MAAM,cAAc,GAAG,OAAO,CAAC,YAAY;AAC3C,QAAA,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI;AAEjC,QAAA,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;AACrC,QAAA,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;AAE3B,QAAA,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE;AAC7B,YAAA,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC;QACjC;AAEA,QAAA,IAAI;AACF,YAAA,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QACzB;gBAAU;AACR,YAAA,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC;AACvC,YAAA,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC;QAC/B;IACF;AACD;;;;"}
+{"version":3,"file":"RenderTargetPass.js","sources":["../../../../src/rendering/RenderTargetPass.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAmBA;;;;;;AAMG;MACU,gBAAgB,CAAA;AACV,IAAA,SAAS;AACT,IAAA,OAAO;AACP,IAAA,KAAK;AACL,IAAA,WAAW;IAE5B,WAAA,CAAmB,QAA0C,EAAE,OAAA,GAAmC,EAAE,EAAA;AAClG,QAAA,IAAI,CAAC,SAAS,GAAG,QAAQ;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI;QACrC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI;IAC/C;AAEO,IAAA,OAAO,CAAC,OAAsB,EAAA;AACnC,QAAA,MAAM,WAAW,GAAI,OAA8D,CAAC,gBAAgB;QAEpG,IAAI,WAAW,EAAE;YACf,WAAW,CAAC,aAAa,CACvB;gBACE,MAAM,EAAE,IAAI,CAAC,OAAO;gBACpB,IAAI,EAAE,IAAI,CAAC,KAAK;AAChB,gBAAA,IAAI,EAAE,IAAI,CAAC,WAAW,KAAK,IAAI,GAAG,OAAO,GAAG,MAAM;gBAClD,UAAU,EAAE,IAAI,CAAC,WAAW;gBAC5B,OAAO,EAAE,qBAAqB,CAAC,IAAI;AACpC,aAAA,EACD,MAAK;AACH,gBAAA,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;AACzB,YAAA,CAAC,CACF;YAED;QACF;;;AAIA,QAAA,MAAM,cAAc,GAAG,OAAO,CAAC,YAAY;AAC3C,QAAA,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI;AAEjC,QAAA,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;AACrC,QAAA,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;AAE3B,QAAA,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE;AAC7B,YAAA,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC;QACjC;AAEA,QAAA,IAAI;AACF,YAAA,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QACzB;gBAAU;AACR,YAAA,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC;AACvC,YAAA,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC;QAC/B;IACF;AACD;;;;"}

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

@@ -13,6 +13,7 @@ import type { DrawableConstructor, Renderer } from './Renderer';
  *
  * Used internally by backend managers. Exposed publicly for advanced
  * custom renderer registration.
+ * @advanced
  */
 export declare class RendererRegistry<Runtime extends RenderBackend> {
     private readonly _renderers;

package/dist/esm/rendering/RendererRegistry.js

@@ -10,6 +10,7 @@
  *
  * Used internally by backend managers. Exposed publicly for advanced
  * custom renderer registration.
+ * @advanced
  */
 class RendererRegistry {
     _renderers = new Map();

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

@@ -1 +1 @@
-{"version":3,"file":"RendererRegistry.js","sources":["../../../../src/rendering/RendererRegistry.ts"],"sourcesContent":[null],"names":[],"mappings":"AAIA;;;;;;;;;;;;AAYG;MACU,gBAAgB,CAAA;AACV,IAAA,UAAU,GAAG,IAAI,GAAG,EAA0C;IACvE,QAAQ,GAAmB,IAAI;AAEvC;;;;;;;;AAQG;IACI,gBAAgB,CAA0B,YAAyC,EAAE,QAAmC,EAAA;QAC7H,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE;YACrC,MAAM,IAAI,KAAK,CAAC,CAAA,qCAAA,EAAwC,YAAY,CAAC,IAAI,CAAA,CAAA,CAAG,CAAC;QAC/E;;;QAIA,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,EAAE,QAAQ,CAAC;AAE3C,QAAA,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE;AACzB,YAAA,QAA8B,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;QACxD;IACF;AAEA;;;;AAIG;IACI,SAAS,GAAA;AACd,QAAA,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE;IACjC;AAEA;;;;;;AAMG;AACI,IAAA,OAAO,CAAC,QAAkB,EAAA;AAC/B,QAAA,IAAI,WAAW,GAAG,QAAQ,CAAC,WAAyC;AACpE,QAAA,IAAI,QAAuC;AAE3C,QAAA,OAAO,WAAW,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE;YACxC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC;YAE3C,IAAI,CAAC,QAAQ,EAAE;gBACb,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC,SAAS,CAAiD;AAE9G,gBAAA,WAAW,GAAG,SAAS,EAAE,WAAW,IAAI,IAAI;YAC9C;QACF;QAEA,IAAI,CAAC,QAAQ,EAAE;AACb,YAAA,MAAM,IAAI,KAAK,CACb,CAAA,2BAAA,EAA8B,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAA,EAAA,CAAI,GAAG,2EAA2E,CAC1I;QACH;AAEA,QAAA,OAAO,QAAQ;IACjB;AAEA;;AAEG;AACI,IAAA,OAAO,CAAC,OAAgB,EAAA;AAC7B,QAAA,IAAI,CAAC,QAAQ,GAAG,OAAO;QAEvB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE;AAC/C,YAAA,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC;QAC3B;IACF;AAEA;;AAEG;IACI,UAAU,GAAA;QACf,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE;YAC/C,QAAQ,CAAC,UAAU,EAAE;QACvB;AAEA,QAAA,IAAI,CAAC,QAAQ,GAAG,IAAI;IACtB;AAEA;;AAEG;IACI,OAAO,GAAA;QACZ,IAAI,CAAC,UAAU,EAAE;QAEjB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE;YAC/C,IAAI,SAAS,IAAI,QAAQ,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE;gBAClE,QAAoD,CAAC,OAAO,EAAE;YACjE;QACF;AAEA,QAAA,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE;IACzB;AACD;;;;"}
+{"version":3,"file":"RendererRegistry.js","sources":["../../../../src/rendering/RendererRegistry.ts"],"sourcesContent":[null],"names":[],"mappings":"AAIA;;;;;;;;;;;;;AAaG;MACU,gBAAgB,CAAA;AACV,IAAA,UAAU,GAAG,IAAI,GAAG,EAA0C;IACvE,QAAQ,GAAmB,IAAI;AAEvC;;;;;;;;AAQG;IACI,gBAAgB,CAA0B,YAAyC,EAAE,QAAmC,EAAA;QAC7H,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE;YACrC,MAAM,IAAI,KAAK,CAAC,CAAA,qCAAA,EAAwC,YAAY,CAAC,IAAI,CAAA,CAAA,CAAG,CAAC;QAC/E;;;QAIA,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,EAAE,QAAQ,CAAC;AAE3C,QAAA,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE;AACzB,YAAA,QAA8B,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;QACxD;IACF;AAEA;;;;AAIG;IACI,SAAS,GAAA;AACd,QAAA,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE;IACjC;AAEA;;;;;;AAMG;AACI,IAAA,OAAO,CAAC,QAAkB,EAAA;AAC/B,QAAA,IAAI,WAAW,GAAG,QAAQ,CAAC,WAAyC;AACpE,QAAA,IAAI,QAAuC;AAE3C,QAAA,OAAO,WAAW,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE;YACxC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC;YAE3C,IAAI,CAAC,QAAQ,EAAE;gBACb,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC,SAAS,CAAiD;AAE9G,gBAAA,WAAW,GAAG,SAAS,EAAE,WAAW,IAAI,IAAI;YAC9C;QACF;QAEA,IAAI,CAAC,QAAQ,EAAE;AACb,YAAA,MAAM,IAAI,KAAK,CACb,CAAA,2BAAA,EAA8B,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAA,EAAA,CAAI,GAAG,2EAA2E,CAC1I;QACH;AAEA,QAAA,OAAO,QAAQ;IACjB;AAEA;;AAEG;AACI,IAAA,OAAO,CAAC,OAAgB,EAAA;AAC7B,QAAA,IAAI,CAAC,QAAQ,GAAG,OAAO;QAEvB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE;AAC/C,YAAA,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC;QAC3B;IACF;AAEA;;AAEG;IACI,UAAU,GAAA;QACf,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE;YAC/C,QAAQ,CAAC,UAAU,EAAE;QACvB;AAEA,QAAA,IAAI,CAAC,QAAQ,GAAG,IAAI;IACtB;AAEA;;AAEG;IACI,OAAO,GAAA;QACZ,IAAI,CAAC,UAAU,EAAE;QAEjB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE;YAC/C,IAAI,SAAS,IAAI,QAAQ,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE;gBAClE,QAAoD,CAAC,OAAO,EAAE;YACjE;QACF;AAEA,QAAA,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE;IACzB;AACD;;;;"}

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

@@ -0,0 +1,87 @@
+import type { Color } from '@/core/Color';
+import { type RenderBackend } from '@/rendering/RenderBackend';
+import { type RenderNode } from '@/rendering/RenderNode';
+import { type RenderStats } from '@/rendering/RenderStats';
+import { RenderTexture } from '@/rendering/texture/RenderTexture';
+import { View } from '@/rendering/View';
+import { Camera } from './Camera';
+export interface RenderToOptions {
+    width: number;
+    height: number;
+    clearColor?: Color;
+}
+export interface RenderOptions {
+    /** Override the view used for this render call. Defaults to the context's active camera. */
+    view?: View;
+}
+/**
+ * Owns rendering orchestration: builds, optimizes and plays the internal
+ * RenderPlan for a RenderNode subtree, manages render-target/view state for
+ * off-screen capture, and exposes the low-level backend as an escape hatch.
+ *
+ * The conceptual model is "the context renders the node":
+ *   context.render(node)            // into the active target (canvas by default)
+ *   context.render(node, { view })  // override view (camera, screenView, etc.)
+ *   context.renderTo(node, opts)    // into an off-screen RenderTexture
+ * @stable
+ */
+export declare class RenderingContext {
+    private readonly _backend;
+    private _camera;
+    private readonly _screenView;
+    constructor(backend: RenderBackend);
+    /**
+     * The active camera. Defaults to a camera that matches the initial
+     * backend view. Replace with a custom `Camera` instance for follow,
+     * zoom, bounds, or split-screen viewport behavior.
+     */
+    get camera(): Camera;
+    set camera(camera: Camera);
+    /**
+     * A RenderingContext-managed screen-space {@link View} suitable for UI
+     * overlays. Center and size are reset to match canvas logical dimensions
+     * on each {@link resize} call. The returned reference is stable (the same
+     * View object across frames), but its properties may change.
+     *
+     * Never follows, shakes, or rotates by default.
+     */
+    get screenView(): View;
+    /** Backward-compatible alias — returns the active {@link camera}. */
+    get view(): View;
+    /**
+     * Advance follow, shake, and bounds-constraint animations on the
+     * active camera. Call once per frame before rendering.
+     */
+    update(deltaMs: number): void;
+    /**
+     * Resize the camera and screen view to match new canvas dimensions.
+     * Preserves the camera's center and zoom; only the visible area size changes.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Render `node` into the active render target.
+     *
+     * Sets the backend's active view to `options.view` (or the default camera)
+     * before building and playing the render plan. This is the recommended
+     * high-level rendering entry point.
+     */
+    render(node: RenderNode, options?: RenderOptions): void;
+    /**
+     * Renders `node` into an off-screen {@link RenderTexture} and returns it.
+     *
+     * The View is centered at `(width / 2, height / 2)` so that the origin
+     * of the node's local space sits at the center of the render texture.
+     *
+     * Saves and restores the active render target and view so the caller's
+     * rendering state is undisturbed.
+     */
+    renderTo(node: RenderNode, options: RenderToOptions): RenderTexture;
+    /** Per-frame render counters. Convenience over backend.stats. */
+    get stats(): RenderStats;
+    /**
+     * Low-level backend (draw primitives, flush, target/scissor/stencil state,
+     * GPU specifics). Escape hatch for custom passes / custom renderers.
+     * @advanced
+     */
+    get backend(): RenderBackend;
+}

package/dist/esm/rendering/RenderingContext.js

@@ -0,0 +1,157 @@
+import '../core/Color.js';
+import '../core/SceneNode.js';
+import '../core/Time.js';
+import '../math/Size.js';
+import '../math/Rectangle.js';
+import { playRenderTree } from './plan/playRenderTree.js';
+import './plan/RenderCommand.js';
+import './plan/RenderScope.js';
+import { StencilAttachmentMode } from './pass/RenderPassDescriptor.js';
+import { RenderTexture } from './texture/RenderTexture.js';
+import './types.js';
+import { View } from './View.js';
+import { Camera } from './Camera.js';
+
+/**
+ * Owns rendering orchestration: builds, optimizes and plays the internal
+ * RenderPlan for a RenderNode subtree, manages render-target/view state for
+ * off-screen capture, and exposes the low-level backend as an escape hatch.
+ *
+ * The conceptual model is "the context renders the node":
+ *   context.render(node)            // into the active target (canvas by default)
+ *   context.render(node, { view })  // override view (camera, screenView, etc.)
+ *   context.renderTo(node, opts)    // into an off-screen RenderTexture
+ * @stable
+ */
+class RenderingContext {
+    _backend;
+    _camera;
+    _screenView;
+    constructor(backend) {
+        this._backend = backend;
+        const viewWidth = backend.view?.width ?? 0;
+        const viewHeight = backend.view?.height ?? 0;
+        const viewCenterX = backend.view?.center?.x ?? viewWidth / 2;
+        const viewCenterY = backend.view?.center?.y ?? viewHeight / 2;
+        this._camera = new Camera({
+            center: { x: viewCenterX, y: viewCenterY },
+            size: { width: viewWidth, height: viewHeight },
+        });
+        this._screenView = new View(viewCenterX, viewCenterY, viewWidth, viewHeight);
+    }
+    /**
+     * The active camera. Defaults to a camera that matches the initial
+     * backend view. Replace with a custom `Camera` instance for follow,
+     * zoom, bounds, or split-screen viewport behavior.
+     */
+    get camera() {
+        return this._camera;
+    }
+    set camera(camera) {
+        const previousCamera = this._camera;
+        this._camera = camera;
+        if (previousCamera !== camera) {
+            previousCamera.destroy();
+        }
+    }
+    /**
+     * A RenderingContext-managed screen-space {@link View} suitable for UI
+     * overlays. Center and size are reset to match canvas logical dimensions
+     * on each {@link resize} call. The returned reference is stable (the same
+     * View object across frames), but its properties may change.
+     *
+     * Never follows, shakes, or rotates by default.
+     */
+    get screenView() {
+        return this._screenView;
+    }
+    /** Backward-compatible alias — returns the active {@link camera}. */
+    get view() {
+        return this._camera;
+    }
+    /**
+     * Advance follow, shake, and bounds-constraint animations on the
+     * active camera. Call once per frame before rendering.
+     */
+    update(deltaMs) {
+        this._camera.update(deltaMs);
+    }
+    /**
+     * Resize the camera and screen view to match new canvas dimensions.
+     * Preserves the camera's center and zoom; only the visible area size changes.
+     */
+    resize(width, height) {
+        this._camera.resize(width, height);
+        this._screenView.resize(width, height);
+        this._screenView.setCenter(width / 2, height / 2);
+    }
+    /**
+     * Render `node` into the active render target.
+     *
+     * Sets the backend's active view to `options.view` (or the default camera)
+     * before building and playing the render plan. This is the recommended
+     * high-level rendering entry point.
+     */
+    render(node, options = {}) {
+        const view = options.view ?? this._camera;
+        this._backend.setView(view);
+        playRenderTree(node, this._backend);
+    }
+    /**
+     * Renders `node` into an off-screen {@link RenderTexture} and returns it.
+     *
+     * The View is centered at `(width / 2, height / 2)` so that the origin
+     * of the node's local space sits at the center of the render texture.
+     *
+     * Saves and restores the active render target and view so the caller's
+     * rendering state is undisturbed.
+     */
+    renderTo(node, options) {
+        const target = new RenderTexture(options.width, options.height);
+        const view = new View(options.width / 2, options.height / 2, options.width, options.height);
+        const coordinator = this._backend._passCoordinator;
+        if (coordinator) {
+            coordinator.withChildPass({
+                target,
+                view,
+                load: options.clearColor !== undefined ? 'clear' : 'load',
+                clearColor: options.clearColor ?? null,
+                stencil: StencilAttachmentMode.None,
+            }, () => {
+                playRenderTree(node, this._backend);
+            });
+            return target;
+        }
+        // Legacy fallback for backends without a pass coordinator (e.g. test stubs).
+        const previousTarget = this._backend.renderTarget;
+        const previousView = this._backend.view;
+        this._backend.setRenderTarget(target);
+        this._backend.setView(view);
+        if (options.clearColor !== undefined) {
+            this._backend.clear(options.clearColor);
+        }
+        try {
+            playRenderTree(node, this._backend);
+        }
+        finally {
+            this._backend.setRenderTarget(previousTarget);
+            this._backend.setView(previousView);
+        }
+        return target;
+    }
+    /** Per-frame render counters. Convenience over backend.stats. */
+    get stats() {
+        return this._backend.stats;
+    }
+    /**
+     * Low-level backend (draw primitives, flush, target/scissor/stencil state,
+     * GPU specifics). Escape hatch for custom passes / custom renderers.
+     * @advanced
+     */
+    get backend() {
+        return this._backend;
+    }
+}
+
+export { RenderingContext };
+//# sourceMappingURL=RenderingContext.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RenderingContext.js","sources":["../../../../src/rendering/RenderingContext.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;;;;;;;AAuBA;;;;;;;;;;AAUG;MACU,gBAAgB,CAAA;AACV,IAAA,QAAQ;AACjB,IAAA,OAAO;AACE,IAAA,WAAW;AAE5B,IAAA,WAAA,CAAmB,OAAsB,EAAA;AACvC,QAAA,IAAI,CAAC,QAAQ,GAAG,OAAO;QAEvB,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC;QAC1C,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;AAC5C,QAAA,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,IAAI,SAAS,GAAG,CAAC;AAC5D,QAAA,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,IAAI,UAAU,GAAG,CAAC;AAE7D,QAAA,IAAI,CAAC,OAAO,GAAG,IAAI,MAAM,CAAC;YACxB,MAAM,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE;YAC1C,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE;AAC/C,SAAA,CAAC;AACF,QAAA,IAAI,CAAC,WAAW,GAAG,IAAI,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC;IAC9E;AAEA;;;;AAIG;AACH,IAAA,IAAW,MAAM,GAAA;QACf,OAAO,IAAI,CAAC,OAAO;IACrB;IAEA,IAAW,MAAM,CAAC,MAAc,EAAA;AAC9B,QAAA,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO;AAEnC,QAAA,IAAI,CAAC,OAAO,GAAG,MAAM;AAErB,QAAA,IAAI,cAAc,KAAK,MAAM,EAAE;YAC7B,cAAc,CAAC,OAAO,EAAE;QAC1B;IACF;AAEA;;;;;;;AAOG;AACH,IAAA,IAAW,UAAU,GAAA;QACnB,OAAO,IAAI,CAAC,WAAW;IACzB;;AAGA,IAAA,IAAW,IAAI,GAAA;QACb,OAAO,IAAI,CAAC,OAAO;IACrB;AAEA;;;AAGG;AACI,IAAA,MAAM,CAAC,OAAe,EAAA;AAC3B,QAAA,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;IAC9B;AAEA;;;AAGG;IACI,MAAM,CAAC,KAAa,EAAE,MAAc,EAAA;QACzC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;QAClC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;AACtC,QAAA,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,KAAK,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IACnD;AAEA;;;;;;AAMG;AACI,IAAA,MAAM,CAAC,IAAgB,EAAE,OAAA,GAAyB,EAAE,EAAA;QACzD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO;AAEzC,QAAA,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;AAC3B,QAAA,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC;IACrC;AAEA;;;;;;;;AAQG;IACI,QAAQ,CAAC,IAAgB,EAAE,OAAwB,EAAA;AACxD,QAAA,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC;QAC/D,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC;AAC3F,QAAA,MAAM,WAAW,GAAI,IAAI,CAAC,QAA+D,CAAC,gBAAgB;QAE1G,IAAI,WAAW,EAAE;YACf,WAAW,CAAC,aAAa,CACvB;gBACE,MAAM;gBACN,IAAI;AACJ,gBAAA,IAAI,EAAE,OAAO,CAAC,UAAU,KAAK,SAAS,GAAG,OAAO,GAAG,MAAM;AACzD,gBAAA,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;gBACtC,OAAO,EAAE,qBAAqB,CAAC,IAAI;AACpC,aAAA,EACD,MAAK;AACH,gBAAA,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC;AACrC,YAAA,CAAC,CACF;AAED,YAAA,OAAO,MAAM;QACf;;AAGA,QAAA,MAAM,cAAc,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY;AACjD,QAAA,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI;AAEvC,QAAA,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC;AACrC,QAAA,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;AAE3B,QAAA,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE;YACpC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACzC;AAEA,QAAA,IAAI;AACF,YAAA,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC;QACrC;gBAAU;AACR,YAAA,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,cAAc,CAAC;AAC7C,YAAA,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC;QACrC;AAEA,QAAA,OAAO,MAAM;IACf;;AAGA,IAAA,IAAW,KAAK,GAAA;AACd,QAAA,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK;IAC5B;AAEA;;;;AAIG;AACH,IAAA,IAAW,OAAO,GAAA;QAChB,OAAO,IAAI,CAAC,QAAQ;IACtB;AACD;;;;"}

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

@@ -0,0 +1,38 @@
+import type { Color } from '@/core/Color';
+import type { Matrix } from '@/math/Matrix';
+/** @internal */
+export interface TransformBufferFrameSnapshot {
+    readonly count: number;
+    readonly hash: number;
+    readonly changed: boolean;
+    readonly version: number;
+}
+/**
+ * Internal per-frame transform+tint storage for draw-command node indices.
+ *
+ * Slot layout (12 floats):
+ * - 0..3:  (a, b, c, d)
+ * - 4..7:  (tx, ty, 0, 0)
+ * - 8..11: (tintR, tintG, tintB, tintA) with RGB in 0..1
+ *
+ * @internal
+ */
+export declare class TransformBuffer {
+    private _data;
+    private _count;
+    private _version;
+    private _frameHash;
+    private _lastCommittedHash;
+    private _lastCommittedCount;
+    get count(): number;
+    get capacity(): number;
+    get data(): Float32Array;
+    get version(): number;
+    begin(expectedCount?: number): this;
+    push(transform: Matrix, tint: Color): number;
+    write(slot: number, transform: Matrix, tint: Color): this;
+    commitSnapshot(minCount?: number): TransformBufferFrameSnapshot;
+    private _ensureCapacity;
+    private _hashFloat;
+    private _mix;
+}

package/dist/esm/rendering/TransformBuffer.js

@@ -0,0 +1,116 @@
+const floatsPerSlot = 12;
+const initialCapacity = 16;
+const hashPrime = 0x01000193;
+const hashOffset = 0x811c9dc5;
+const hashFloatScratch = new Float32Array(1);
+const hashUintScratch = new Uint32Array(hashFloatScratch.buffer);
+/**
+ * Internal per-frame transform+tint storage for draw-command node indices.
+ *
+ * Slot layout (12 floats):
+ * - 0..3:  (a, b, c, d)
+ * - 4..7:  (tx, ty, 0, 0)
+ * - 8..11: (tintR, tintG, tintB, tintA) with RGB in 0..1
+ *
+ * @internal
+ */
+class TransformBuffer {
+    _data = new Float32Array(initialCapacity * floatsPerSlot);
+    _count = 0;
+    _version = 0;
+    _frameHash = hashOffset >>> 0;
+    _lastCommittedHash = 0;
+    _lastCommittedCount = -1;
+    get count() {
+        return this._count;
+    }
+    get capacity() {
+        return this._data.length / floatsPerSlot;
+    }
+    get data() {
+        return this._data;
+    }
+    get version() {
+        return this._version;
+    }
+    begin(expectedCount = 0) {
+        if (expectedCount > 0) {
+            this._ensureCapacity(expectedCount);
+        }
+        this._count = 0;
+        this._frameHash = hashOffset >>> 0;
+        return this;
+    }
+    push(transform, tint) {
+        const slot = this._count;
+        this.write(slot, transform, tint);
+        return slot;
+    }
+    write(slot, transform, tint) {
+        if (!Number.isInteger(slot) || slot < 0) {
+            throw new Error(`TransformBuffer slot must be a non-negative integer (got ${slot}).`);
+        }
+        this._ensureCapacity(slot + 1);
+        const offset = slot * floatsPerSlot;
+        const data = this._data;
+        data[offset + 0] = transform.a;
+        data[offset + 1] = transform.b;
+        data[offset + 2] = transform.c;
+        data[offset + 3] = transform.d;
+        data[offset + 4] = transform.x;
+        data[offset + 5] = transform.y;
+        data[offset + 6] = 0;
+        data[offset + 7] = 0;
+        data[offset + 8] = tint.r / 255;
+        data[offset + 9] = tint.g / 255;
+        data[offset + 10] = tint.b / 255;
+        data[offset + 11] = tint.a;
+        if (slot >= this._count) {
+            this._count = slot + 1;
+        }
+        this._frameHash = this._mix(this._frameHash, slot);
+        for (let i = 0; i < floatsPerSlot; i++) {
+            this._frameHash = this._mix(this._frameHash, this._hashFloat(data[offset + i]));
+        }
+        return this;
+    }
+    commitSnapshot(minCount = 0) {
+        const count = Math.max(this._count, minCount);
+        const hash = this._mix(this._frameHash, count);
+        const changed = hash !== this._lastCommittedHash || count !== this._lastCommittedCount;
+        if (changed) {
+            this._version++;
+            this._lastCommittedHash = hash;
+            this._lastCommittedCount = count;
+        }
+        return {
+            count,
+            hash,
+            changed,
+            version: this._version,
+        };
+    }
+    _ensureCapacity(requiredSlots) {
+        const current = this.capacity;
+        if (requiredSlots <= current) {
+            return;
+        }
+        let next = Math.max(current, initialCapacity);
+        while (next < requiredSlots) {
+            next *= 2;
+        }
+        const nextData = new Float32Array(next * floatsPerSlot);
+        nextData.set(this._data);
+        this._data = nextData;
+    }
+    _hashFloat(value) {
+        hashFloatScratch[0] = value;
+        return hashUintScratch[0] >>> 0;
+    }
+    _mix(hash, value) {
+        return Math.imul((hash ^ value) >>> 0, hashPrime) >>> 0;
+    }
+}
+
+export { TransformBuffer };
+//# sourceMappingURL=TransformBuffer.js.map

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

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

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

@@ -2,6 +2,7 @@ import { SceneNode } from '@/core/SceneNode';
 import { Matrix } from '@/math/Matrix';
 import { ObservableSize } from '@/math/ObservableSize';
 import { ObservableVector } from '@/math/ObservableVector';
+import type { PointLike } from '@/math/PointLike';
 import { Rectangle } from '@/math/Rectangle';
 /**
  * Dirty-flag bits for lazy {@link View} transform and bounds recalculation.
@@ -48,6 +49,7 @@ export interface ViewShakeOptions {
  * matrices, a follow-target system for tracking scene nodes, and a procedural
  * screen-shake effect. Call {@link update} once per frame to advance follow and
  * shake animations.
+ * @stable
  */
 export declare class View {
     private readonly _center;
@@ -152,6 +154,27 @@ export declare class View {
      * Use this to convert screen-space coordinates (e.g. mouse position) to world space.
      */
     getInverseTransform(): Matrix;
+    /**
+     * Convert a canvas pixel coordinate to a world-space position for this view.
+     * Accounts for the view's viewport rectangle, so it works correctly in
+     * multi-view / split-screen setups.
+     *
+     * @param screenX     - X pixel relative to the canvas top-left corner.
+     * @param screenY     - Y pixel relative to the canvas top-left corner.
+     * @param canvasWidth - Canvas width in pixels (e.g. `app.canvas.width`).
+     * @param canvasHeight - Canvas height in pixels (e.g. `app.canvas.height`).
+     */
+    screenToWorld(screenX: number, screenY: number, canvasWidth: number, canvasHeight: number): PointLike;
+    /**
+     * Convert a world-space position to canvas pixel coordinates for this view.
+     * Accounts for the view's viewport rectangle.
+     *
+     * @param worldX      - World X coordinate.
+     * @param worldY      - World Y coordinate.
+     * @param canvasWidth - Canvas width in pixels (e.g. `app.canvas.width`).
+     * @param canvasHeight - Canvas height in pixels (e.g. `app.canvas.height`).
+     */
+    worldToScreen(worldX: number, worldY: number, canvasWidth: number, canvasHeight: number): PointLike;
     /**
      * Return the world-space bounding rectangle of the currently visible area, recalculating if dirty.
      * Used for frustum culling by {@link Drawable.render}.