aigpu 0.3.1

package/dist/query-ring.js

@@ -0,0 +1,178 @@
+import { queryReadbackError } from "./errors.js";
+/**
+ * Bytes each resolved query occupies: WebGPU resolveQuerySet writes each result
+ * "into a GPUBuffer ... as a 64-bit unsigned integer" (8 bytes per query).
+ *
+ * @internal
+ */
+export const QUERY_RESULT_BYTES = 8;
+/** GPUMapMode.READ; numeric fallback covers headless/mock runtimes without the global. */
+const MAP_READ = (globalThis.GPUMapMode?.READ ?? 1);
+/** @internal */
+export function createQueryRing(device, options) {
+    return new InternalQueryRing(device, options);
+}
+class InternalQueryRing {
+    querySet;
+    capacity;
+    #label;
+    #resolve;
+    #stagings;
+    #trackSettled;
+    #errorSink;
+    #cursor = 0;
+    #nextSeq = 0;
+    #appliedSeq = -1;
+    #pendingEncode;
+    #inFlight = 0;
+    /** Frames that bound querySet into a pass descriptor and have not been submitted/abandoned yet. */
+    #retained = 0;
+    #disposed = false;
+    #destroyed = false;
+    constructor(device, options) {
+        this.capacity = options.capacity;
+        const label = options.label ?? "aigpu.query-ring";
+        this.#label = label;
+        const byteSize = options.capacity * QUERY_RESULT_BYTES;
+        this.querySet = device.gpu.createQuerySet({ type: options.type, count: options.capacity, label });
+        // Mirrors WebGPU resolveQuerySet requirements: "destination.usage contains QUERY_RESOLVE" and
+        // "destinationOffset + 8 × queryCount ≤ destination.size" (we always resolve at offset 0, a multiple of 256).
+        this.#resolve = device.createBuffer({ size: byteSize, usage: ["query_resolve", "copy_src"], label: `${label}.resolve` });
+        this.#stagings = Array.from({ length: options.depth ?? 3 }, (_, index) => ({
+            buffer: device.createBuffer({ size: byteSize, usage: ["map_read", "copy_dst"], label: `${label}.staging${index}` }),
+            mapPending: false,
+            retired: false,
+        }));
+        this.#trackSettled = options.trackSettled;
+        this.#errorSink = options.errorSink;
+    }
+    encodeResolve(encoder, usedCount) {
+        this.#pendingEncode = undefined;
+        if (this.#disposed || usedCount <= 0)
+            return false;
+        const staging = this.#claimStaging();
+        // Drop, never block: when readbacks lag frames-in-flight past the ring depth, skip this frame's resolve entirely.
+        if (!staging)
+            return false;
+        const count = Math.min(usedCount, this.capacity);
+        encoder.resolveQuerySet(this.querySet, 0, count, this.#resolve.gpu, 0);
+        encoder.copyBufferToBuffer(this.#resolve.gpu, 0, staging.buffer.gpu, 0, count * QUERY_RESULT_BYTES);
+        this.#pendingEncode = { staging, usedCount: count, seq: this.#nextSeq };
+        this.#nextSeq += 1;
+        this.#cursor += 1;
+        return true;
+    }
+    onSubmitted(apply) {
+        const pending = this.#pendingEncode;
+        this.#pendingEncode = undefined;
+        if (!pending)
+            return;
+        pending.staging.mapPending = true;
+        this.#inFlight += 1;
+        const readback = pending.staging.buffer.gpu.mapAsync(MAP_READ)
+            .then(() => {
+            // The buffer is mapped from here on: it must be unmapped before the slot rotates back into
+            // use, even if decoding throws — resolving into a mapped buffer is a validation error.
+            const values = this.#decodeMapped(pending);
+            // Ordered application: a stale readback that lands after a newer one already applied is discarded.
+            if (pending.seq <= this.#appliedSeq)
+                return;
+            this.#appliedSeq = pending.seq;
+            apply(values);
+        })
+            // Non-throwing by contract, but never silent: a dropped readback is reported on gpu.onError.
+            .catch((cause) => { this.#reportDroppedReadback(cause); })
+            .finally(() => {
+            pending.staging.mapPending = false;
+            this.#inFlight -= 1;
+            this.#destroyWhenIdle();
+        });
+        this.#trackSettled?.(readback);
+    }
+    /**
+     * Next staging buffer in rotation, skipping retired slots. Undefined means "drop this resolve":
+     * the slot is still map-pending (readbacks lag the ring depth) or every slot is retired.
+     */
+    #claimStaging() {
+        for (let checked = 0; checked < this.#stagings.length; checked += 1) {
+            const slot = this.#stagings[this.#cursor % this.#stagings.length];
+            if (!slot.retired)
+                return slot.mapPending ? undefined : slot;
+            // Permanently unusable: rotate past it so the remaining buffers keep serving readbacks.
+            this.#cursor += 1;
+        }
+        return undefined;
+    }
+    /**
+     * Copies the mapped range out and unmaps, keeping the slot reusable. A failure here (a lost device
+     * mid-map) still unmaps best-effort; if that fails too the buffer may stay mapped forever, so the
+     * slot is retired instead of being handed back to encodeResolve. Throws so the readback is dropped
+     * and reported like any other failure.
+     */
+    #decodeMapped(pending) {
+        let values;
+        try {
+            values = new BigUint64Array(pending.staging.buffer.gpu.getMappedRange().slice(0, pending.usedCount * QUERY_RESULT_BYTES));
+        }
+        catch (error) {
+            this.#unmapOrRetire(pending.staging);
+            throw error;
+        }
+        try {
+            pending.staging.buffer.gpu.unmap();
+        }
+        catch (error) {
+            pending.staging.retired = true;
+            throw error;
+        }
+        return values;
+    }
+    #unmapOrRetire(staging) {
+        try {
+            staging.buffer.gpu.unmap();
+        }
+        catch {
+            staging.retired = true;
+        }
+    }
+    retain() {
+        this.#retained += 1;
+    }
+    release() {
+        if (this.#retained > 0)
+            this.#retained -= 1;
+        this.#destroyWhenIdle();
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#pendingEncode = undefined;
+        this.#destroyWhenIdle();
+    }
+    /** Destroys once disposed and idle: no in-flight map and no frame still referencing the query set. */
+    #destroyWhenIdle() {
+        if (!this.#disposed || this.#destroyed || this.#inFlight > 0 || this.#retained > 0)
+            return;
+        this.#destroyed = true;
+        this.querySet.destroy();
+        this.#resolve.dispose();
+        for (const staging of this.#stagings)
+            staging.buffer.dispose();
+    }
+    #reportDroppedReadback(cause) {
+        const error = queryReadbackError(this.#label, cause);
+        const sink = this.#errorSink;
+        if (!sink) {
+            console.error(error);
+            return;
+        }
+        try {
+            void Promise.resolve(sink(error)).catch((sinkError) => { console.error(sinkError); });
+        }
+        catch (sinkError) {
+            console.error(sinkError);
+        }
+    }
+}
+//# sourceMappingURL=query-ring.js.map

package/dist/query-ring.js.map

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

package/dist/render-service.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The single lazy render service of a `Gpu`: bind groups, pipelines, shader modules,
+ * pipeline layouts and samplers.
+ *
+ * Every render-family free function (draw, effect, and later scene views) resolves it through
+ * the same token, so they share one cache set and one identity — no duplicated pipeline stores.
+ * It is created on first render use and torn down in the kernel's `service` phase, after
+ * schedulers and resources, before the device.
+ */
+import { type BindGroupCache } from "./bind-cache.ts";
+import { type PipelineLayoutCache, type PipelineStore, type ShaderModuleCache } from "./pipeline-store.ts";
+import { type Kernel } from "./kernel.ts";
+export interface RenderService {
+    readonly binds: BindGroupCache;
+    readonly pipelines: PipelineStore;
+    readonly shaderModules: ShaderModuleCache;
+    readonly pipelineLayouts: PipelineLayoutCache;
+    sampler(desc?: GPUSamplerDescriptor): GPUSampler;
+}
+export declare const renderServiceToken: import("./kernel.ts").ServiceToken<RenderService>;
+/** Lazily creates the render service of this kernel; repeated calls return the same instance. */
+export declare function renderService(kernel: Kernel): RenderService;
+//# sourceMappingURL=render-service.d.ts.map

package/dist/render-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-service.d.ts","sourceRoot":"","sources":["../src/render-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,EAA2E,KAAK,mBAAmB,EAAE,KAAK,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACpL,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,mBAAmB,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,UAAU,CAAC;CAClD;AAED,eAAO,MAAM,kBAAkB,mDAAgD,CAAC;AAEhF,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAE3D"}

package/dist/render-service.js

@@ -0,0 +1,37 @@
+/**
+ * The single lazy render service of a `Gpu`: bind groups, pipelines, shader modules,
+ * pipeline layouts and samplers.
+ *
+ * Every render-family free function (draw, effect, and later scene views) resolves it through
+ * the same token, so they share one cache set and one identity — no duplicated pipeline stores.
+ * It is created on first render use and torn down in the kernel's `service` phase, after
+ * schedulers and resources, before the device.
+ */
+import { createBindGroupCache } from "./bind-cache.js";
+import { createSamplerCache } from "./sampler.js";
+import { createPipelineLayoutCache, createPipelineStore, createShaderModuleCache } from "./pipeline-store.js";
+import { serviceToken } from "./kernel.js";
+export const renderServiceToken = serviceToken("render-service");
+/** Lazily creates the render service of this kernel; repeated calls return the same instance. */
+export function renderService(kernel) {
+    return kernel.service(renderServiceToken, createRenderService);
+}
+function createRenderService(kernel) {
+    const device = kernel.device;
+    const binds = createBindGroupCache();
+    const pipelines = createPipelineStore(device, {
+        errorSink: (error) => kernel.reportError(error),
+        registerSettledSource: (source) => kernel.registerSettledSource(source),
+    });
+    const shaderModules = createShaderModuleCache(device);
+    const pipelineLayouts = createPipelineLayoutCache(device);
+    const samplers = createSamplerCache(device);
+    kernel.own("service", () => {
+        pipelines.dispose();
+        shaderModules.dispose();
+        pipelineLayouts.dispose();
+        binds.dispose();
+    });
+    return { binds, pipelines, shaderModules, pipelineLayouts, sampler: (desc) => samplers.sampler(desc) };
+}
+//# sourceMappingURL=render-service.js.map

package/dist/render-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-service.js","sourceRoot":"","sources":["../src/render-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,oBAAoB,EAAuB,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,uBAAuB,EAAwE,MAAM,qBAAqB,CAAC;AACpL,OAAO,EAAE,YAAY,EAAe,MAAM,aAAa,CAAC;AAUxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAgB,gBAAgB,CAAC,CAAC;AAEhF,iGAAiG;AACjG,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,MAAM,CAAC,OAAO,CAAC,kBAAkB,EAAE,mBAAmB,CAAC,CAAC;AACjE,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAc;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,MAAM,KAAK,GAAG,oBAAoB,EAAE,CAAC;IACrC,MAAM,SAAS,GAAG,mBAAmB,CAAC,MAAM,EAAE;QAC5C,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC;QAC/C,qBAAqB,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC;KACxE,CAAC,CAAC;IACH,MAAM,aAAa,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;IACtD,MAAM,eAAe,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,SAAS,CAAC,OAAO,EAAE,CAAC;QACpB,aAAa,CAAC,OAAO,EAAE,CAAC;QACxB,eAAe,CAAC,OAAO,EAAE,CAAC;QAC1B,KAAK,CAAC,OAAO,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;AACzG,CAAC"}

package/dist/sampler.d.ts

@@ -0,0 +1,19 @@
+import type { Device } from "@aigpu/core";
+import type { Gpu } from "./kernel.ts";
+/**
+ * Cached `GPUSampler` for this gpu: identical descriptors return the identical sampler, so bind
+ * groups keyed on resource identity stay stable across frames.
+ *
+ * The cache lives in the gpu's render service — the same one `draw()` and `effect()` use — and is
+ * created on first use, not at `init()`.
+ */
+export declare function sampler(gpu: Gpu, desc?: GPUSamplerDescriptor): GPUSampler;
+export interface SamplerCache {
+    sampler(desc?: GPUSamplerDescriptor): GPUSampler;
+    identity(sampler: GPUSampler): {
+        readonly kind: "sampler";
+        readonly id: number;
+    };
+}
+export declare function createSamplerCache(device: Device): SamplerCache;
+//# sourceMappingURL=sampler.d.ts.map

package/dist/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../src/sampler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAGvC;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,UAAU,CAEzE;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,UAAU,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAClF;AAID,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAuB/D"}

package/dist/sampler.js

@@ -0,0 +1,46 @@
+import { liveKernel } from "./live-kernel.js";
+import { renderService } from "./render-service.js";
+/**
+ * Cached `GPUSampler` for this gpu: identical descriptors return the identical sampler, so bind
+ * groups keyed on resource identity stay stable across frames.
+ *
+ * The cache lives in the gpu's render service — the same one `draw()` and `effect()` use — and is
+ * created on first use, not at `init()`.
+ */
+export function sampler(gpu, desc) {
+    return renderService(liveKernel(gpu, "sampler")).sampler(desc);
+}
+let nextSamplerId = 1;
+export function createSamplerCache(device) {
+    const byKey = new Map();
+    const ids = new WeakMap();
+    return {
+        sampler(desc = {}) {
+            const key = stableKey(desc);
+            let sampler = byKey.get(key);
+            if (!sampler) {
+                sampler = device.gpu.createSampler(desc);
+                byKey.set(key, sampler);
+                ids.set(sampler, { kind: "sampler", id: nextSamplerId++ });
+            }
+            return sampler;
+        },
+        identity(sampler) {
+            let id = ids.get(sampler);
+            if (!id) {
+                id = { kind: "sampler", id: nextSamplerId++ };
+                ids.set(sampler, id);
+            }
+            return id;
+        },
+    };
+}
+function stableKey(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableKey).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableKey(record[key])}`).join(",")}}`;
+}
+//# sourceMappingURL=sampler.js.map

package/dist/sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.js","sourceRoot":"","sources":["../src/sampler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,GAAQ,EAAE,IAA2B;IAC3D,OAAO,aAAa,CAAC,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAOD,IAAI,aAAa,GAAG,CAAC,CAAC;AAEtB,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC5C,MAAM,GAAG,GAAG,IAAI,OAAO,EAAiE,CAAC;IACzF,OAAO;QACL,OAAO,CAAC,OAA6B,EAAE;YACrC,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAC5B,IAAI,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;gBACzC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;gBACxB,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC;YAC7D,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,QAAQ,CAAC,OAAO;YACd,IAAI,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC1B,IAAI,CAAC,EAAE,EAAE,CAAC;gBACR,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,CAAC;gBAC9C,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACvB,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACvE,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AACtH,CAAC"}

package/dist/scene/camera.d.ts

@@ -0,0 +1,91 @@
+import { type Mat4 } from "./tree/math.ts";
+import { SceneNode, type NodeOptions, type NodeTransformValues } from "./tree/node.ts";
+export type CameraVec3 = readonly [number, number, number] | Float32Array;
+/**
+ * Common contract of scene cameras. Matrices are stable `Float32Array` identities updated
+ * in place, so a binding set once stays fresh across frames.
+ */
+export interface SceneCamera {
+    /** Column-major projection × view matrix. Bind this to your WGSL uniforms. */
+    readonly viewProjection: Float32Array;
+    /** Alias of `viewProjection`, kept for naming continuity. */
+    readonly viewProjectionMatrix: Float32Array;
+    /** Local position (world position for unparented cameras). Mutate via `set()`. */
+    readonly position: Float32Array;
+    readonly view: Float32Array;
+    readonly projection: Float32Array;
+    readonly worldPosition: Float32Array;
+}
+export type Camera = SceneCamera;
+interface CameraSharedOptions extends NodeOptions {
+    readonly near?: number;
+    readonly far?: number;
+    /** World-space point the camera looks at initially. Reorient later with `lookAt()`. */
+    readonly target?: CameraVec3;
+    readonly up?: CameraVec3;
+}
+export interface PerspectiveCameraOptions extends CameraSharedOptions {
+    /** Vertical field of view in degrees. */
+    readonly fov: number;
+    readonly aspect?: number;
+}
+export interface OrthographicCameraOptions extends CameraSharedOptions {
+    readonly left: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly top: number;
+}
+export interface PerspectiveCameraValues extends NodeTransformValues {
+    readonly fov?: number;
+    readonly aspect?: number;
+    readonly near?: number;
+    readonly far?: number;
+}
+export interface OrthographicCameraValues extends NodeTransformValues {
+    readonly left?: number;
+    readonly right?: number;
+    readonly bottom?: number;
+    readonly top?: number;
+    readonly near?: number;
+    readonly far?: number;
+}
+declare abstract class CameraNode extends SceneNode implements SceneCamera {
+    #private;
+    protected _projectionDirty: boolean;
+    get projection(): Mat4;
+    get view(): Mat4;
+    get viewProjection(): Mat4;
+    get viewProjectionMatrix(): Mat4;
+    protected abstract _updateProjection(out: Mat4): void;
+}
+/** Perspective projection camera node. `fov` is in degrees for the public scene API. */
+export declare class PerspectiveCamera extends CameraNode {
+    #private;
+    constructor(options: PerspectiveCameraOptions);
+    set(values: PerspectiveCameraValues): this;
+    get fov(): number;
+    /** Resolved aspect ratio; defaults to 1 until set explicitly. */
+    get aspect(): number;
+    get near(): number;
+    get far(): number;
+    protected _updateProjection(out: Mat4): void;
+}
+/** Orthographic projection camera node. */
+export declare class OrthographicCamera extends CameraNode {
+    #private;
+    constructor(options: OrthographicCameraOptions);
+    set(values: OrthographicCameraValues): this;
+    get left(): number;
+    get right(): number;
+    get bottom(): number;
+    get top(): number;
+    get near(): number;
+    get far(): number;
+    protected _updateProjection(out: Mat4): void;
+}
+/** Creates a stateful perspective camera node using degrees for the public scene API. */
+export declare function perspectiveCamera(options: PerspectiveCameraOptions): PerspectiveCamera;
+/** Creates a stateful orthographic camera node for shaders expecting `viewProjection`. */
+export declare function orthographicCamera(options: OrthographicCameraOptions): OrthographicCamera;
+export {};
+//# sourceMappingURL=camera.d.ts.map

package/dist/scene/camera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../../src/scene/camera.ts"],"names":[],"mappings":"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"}

package/dist/scene/camera.js

@@ -0,0 +1,221 @@
+import { orthographic, perspective } from "./geometry-src/camera-math.js";
+import { degToRad } from "./geometry-src/index.js";
+import { sceneValueError } from "./tree/errors.js";
+import { identityMat4, invertAffineMat4, multiplyMat4 } from "./tree/math.js";
+import { SceneNode } from "./tree/node.js";
+class CameraNode extends SceneNode {
+    #projection = identityMat4(new Float32Array(16));
+    #view = identityMat4(new Float32Array(16));
+    #viewProjection = identityMat4(new Float32Array(16));
+    _projectionDirty = true;
+    #viewWorldVersion = -1;
+    #viewProjectionStale = true;
+    get projection() {
+        if (this._projectionDirty) {
+            this._updateProjection(this.#projection);
+            this._projectionDirty = false;
+            this.#viewProjectionStale = true;
+        }
+        return this.#projection;
+    }
+    get view() {
+        this.#syncView();
+        return this.#view;
+    }
+    get viewProjection() {
+        const projection = this.projection;
+        this.#syncView();
+        if (this.#viewProjectionStale) {
+            multiplyMat4(this.#viewProjection, projection, this.#view);
+            this.#viewProjectionStale = false;
+        }
+        return this.#viewProjection;
+    }
+    get viewProjectionMatrix() {
+        return this.viewProjection;
+    }
+    #syncView() {
+        const world = this.worldMatrix;
+        if (this.#viewWorldVersion !== this._worldVersion) {
+            invertAffineMat4(this.#view, world);
+            this.#viewWorldVersion = this._worldVersion;
+            this.#viewProjectionStale = true;
+        }
+    }
+}
+/** Perspective projection camera node. `fov` is in degrees for the public scene API. */
+export class PerspectiveCamera extends CameraNode {
+    #fov;
+    #aspect;
+    #near;
+    #far;
+    constructor(options) {
+        // Validate before super(): SceneNode's constructor reparents `options.children`, so a
+        // throw after it would strand them on a camera nobody can reach.
+        validateFov("perspectiveCamera", options.fov);
+        if (options.aspect !== undefined)
+            validateAspect("perspectiveCamera", options.aspect);
+        validateRange("perspectiveCamera", options.near ?? 0.1, options.far ?? 100);
+        validateInitialLookAt("perspectiveCamera", options.target, options.up);
+        super("perspective-camera", options);
+        this.#fov = options.fov;
+        this.#aspect = options.aspect;
+        this.#near = options.near ?? 0.1;
+        this.#far = options.far ?? 100;
+        if (options.target)
+            this.lookAt(options.target, options.up);
+    }
+    set(values) {
+        super.set(values);
+        const where = `${this.label ?? this.kind}.set`;
+        if (values.fov !== undefined) {
+            validateFov(where, values.fov);
+            this.#fov = values.fov;
+            this._projectionDirty = true;
+        }
+        if (values.aspect !== undefined) {
+            validateAspect(where, values.aspect);
+            this.#aspect = values.aspect;
+            this._projectionDirty = true;
+        }
+        if (values.near !== undefined || values.far !== undefined) {
+            const near = values.near ?? this.#near;
+            const far = values.far ?? this.#far;
+            validateRange(where, near, far);
+            this.#near = near;
+            this.#far = far;
+            this._projectionDirty = true;
+        }
+        return this;
+    }
+    get fov() {
+        return this.#fov;
+    }
+    /** Resolved aspect ratio; defaults to 1 until set explicitly. */
+    get aspect() {
+        return this.#aspect ?? 1;
+    }
+    get near() {
+        return this.#near;
+    }
+    get far() {
+        return this.#far;
+    }
+    _updateProjection(out) {
+        out.set(perspective(degToRad(this.#fov), this.#aspect ?? 1, this.#near, this.#far));
+    }
+}
+/** Orthographic projection camera node. */
+export class OrthographicCamera extends CameraNode {
+    #left;
+    #right;
+    #bottom;
+    #top;
+    #near;
+    #far;
+    constructor(options) {
+        // Validate before super() so a rejected option bag cannot strand `options.children`.
+        validateExtent("orthographicCamera", "left", options.left, "right", options.right);
+        validateExtent("orthographicCamera", "bottom", options.bottom, "top", options.top);
+        validateRange("orthographicCamera", options.near ?? 0.1, options.far ?? 100);
+        validateInitialLookAt("orthographicCamera", options.target, options.up);
+        super("orthographic-camera", options);
+        this.#left = options.left;
+        this.#right = options.right;
+        this.#bottom = options.bottom;
+        this.#top = options.top;
+        this.#near = options.near ?? 0.1;
+        this.#far = options.far ?? 100;
+        if (options.target)
+            this.lookAt(options.target, options.up);
+    }
+    set(values) {
+        super.set(values);
+        const where = `${this.label ?? this.kind}.set`;
+        let projectionTouched = false;
+        if (values.left !== undefined || values.right !== undefined) {
+            validateExtent(where, "left", values.left ?? this.#left, "right", values.right ?? this.#right);
+        }
+        if (values.bottom !== undefined || values.top !== undefined) {
+            validateExtent(where, "bottom", values.bottom ?? this.#bottom, "top", values.top ?? this.#top);
+        }
+        if (values.left !== undefined) {
+            this.#left = values.left;
+            projectionTouched = true;
+        }
+        if (values.right !== undefined) {
+            this.#right = values.right;
+            projectionTouched = true;
+        }
+        if (values.bottom !== undefined) {
+            this.#bottom = values.bottom;
+            projectionTouched = true;
+        }
+        if (values.top !== undefined) {
+            this.#top = values.top;
+            projectionTouched = true;
+        }
+        if (values.near !== undefined || values.far !== undefined) {
+            const near = values.near ?? this.#near;
+            const far = values.far ?? this.#far;
+            validateRange(where, near, far);
+            this.#near = near;
+            this.#far = far;
+            projectionTouched = true;
+        }
+        if (projectionTouched)
+            this._projectionDirty = true;
+        return this;
+    }
+    get left() { return this.#left; }
+    get right() { return this.#right; }
+    get bottom() { return this.#bottom; }
+    get top() { return this.#top; }
+    get near() { return this.#near; }
+    get far() { return this.#far; }
+    _updateProjection(out) {
+        out.set(orthographic(this.#left, this.#right, this.#bottom, this.#top, this.#near, this.#far));
+    }
+}
+/** Creates a stateful perspective camera node using degrees for the public scene API. */
+export function perspectiveCamera(options) {
+    return new PerspectiveCamera(options);
+}
+/** Creates a stateful orthographic camera node for shaders expecting `viewProjection`. */
+export function orthographicCamera(options) {
+    return new OrthographicCamera(options);
+}
+function validateInitialLookAt(where, target, up) {
+    if (target === undefined)
+        return;
+    if (target.length !== 3)
+        throw sceneValueError(where, "target", "an array of 3 numbers");
+    if (up !== undefined && up.length !== 3)
+        throw sceneValueError(where, "up", "an array of 3 numbers");
+}
+function validateFov(where, fov) {
+    if (!(fov > 0 && fov < 180))
+        throw sceneValueError(where, "fov", "a field of view in degrees between 0 and 180 (exclusive)");
+}
+function validateRange(where, near, far) {
+    if (!(near > 0))
+        throw sceneValueError(where, "near", "a positive near plane distance");
+    if (!(far > near))
+        throw sceneValueError(where, "far", "a far plane distance greater than `near`");
+}
+/** `canvas.width / canvas.height` is 0 or NaN during layout; that must not reach the matrix. */
+function validateAspect(where, aspect) {
+    if (!(aspect > 0) || !Number.isFinite(aspect)) {
+        throw sceneValueError(where, "aspect", "a positive, finite width/height ratio");
+    }
+}
+function validateExtent(where, minName, min, maxName, max) {
+    if (!Number.isFinite(min))
+        throw sceneValueError(where, minName, "a finite number");
+    if (!Number.isFinite(max))
+        throw sceneValueError(where, maxName, "a finite number");
+    // Flipped ranges stay legal (a Y-flip is a real use case); empty ones divide by zero.
+    if (min === max)
+        throw sceneValueError(where, maxName, `a value different from \`${minName}\``);
+}
+//# sourceMappingURL=camera.js.map