@field/cascade 0.3.1 → 0.4.0

package/dist/runtime/camera/index.js

@@ -0,0 +1,234 @@
+/**
+ * Everything derived from a `camera`, so that no renderer derives it twice.
+ *
+ * The type stores intent — a transform, a lens, a frame — and every consumer
+ * wants something else: a rasteriser wants matrices, a raymarcher wants the
+ * basis vectors directly, and a UI wants the angle in degrees. Deriving those
+ * here is the same argument as `resolvePropBinding`: one implementation, or the
+ * second one disagrees with the first about handedness in a way that takes an
+ * afternoon to find.
+ *
+ * Houdini's conventions throughout: the camera looks down its own **-Z** with
+ * **+Y** up, rotation is degrees applied in **XYZ** order, and the vertical
+ * aperture is derived from the horizontal one and the frame shape rather than
+ * stored.
+ *
+ * **Matching a frame is one number, never two.** Both angles come from the same
+ * `focal`, `aperture` and resolution ratio, so a `focal` chosen to reproduce a
+ * known horizontal angle reproduces the vertical one at the same time. Worked
+ * example, from converting `cloud-volumes` off its hand-rolled projection on
+ * 2026-09-08: that sketch pinned its **vertical** half-tangent at `0.36` and
+ * scaled the horizontal by aspect, which on a 1098×1512 page gave a 29.3°
+ * horizontal angle; `focal = (aperture / 2) / 0.261 ≈ 79.2 mm` reproduces it,
+ * and the vertical lands back on `0.36` without being asked. Which is also the
+ * reason that sketch's `fit` parameter had to go — it backed the camera off to
+ * win back horizontal coverage a portrait page had lost, and that is the same
+ * compensation this module already does in the projection.
+ */
+const DEG = Math.PI / 180;
+function cross(a, b) {
+    return [
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0],
+    ];
+}
+function normalize(v) {
+    const length = Math.hypot(v[0], v[1], v[2]);
+    if (length === 0)
+        return [0, 0, 0];
+    return [v[0] / length, v[1] / length, v[2] / length];
+}
+function subtract(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+/**
+ * The rotation the camera needs to look at a point, as Houdini's look-at does.
+ *
+ * Returned as degrees in XYZ order so it can be written straight into
+ * `camera.rotate` — which is what makes look-at an override of the transform
+ * rather than a second, parallel way to orient a camera.
+ *
+ * **`up` chooses the roll, and only the roll.** Yaw and pitch are fixed the
+ * moment a direction is given; all an up vector can still decide is the
+ * rotation about that direction. The default `[0, 1, 0]` is Houdini's own
+ * `upvector` default and gives roll zero for any horizontal up, which is why
+ * every ordinary orbit never needs to think about it.
+ *
+ * Written first with `roll = 0` and the parameter ignored, which was wrong in
+ * the way this codebase keeps finding: the node exposes `up` as an input, so a
+ * value set there did nothing at all and nothing said so.
+ */
+export function lookAtRotation(from, to, up = [0, 1, 0]) {
+    const forward = normalize(subtract(to, from));
+    if (forward[0] === 0 && forward[1] === 0 && forward[2] === 0)
+        return [0, 0, 0];
+    // Pitch first, because yaw is measured in the horizontal plane and the
+    // horizontal length is what is left of the vector once pitch is taken out.
+    const horizontal = Math.hypot(forward[0], forward[2]);
+    const pitch = Math.atan2(forward[1], horizontal);
+    // Looking down -Z at rest, so a forward of (0, 0, -1) must give a yaw of 0.
+    const yaw = Math.atan2(-forward[0], -forward[2]);
+    return [pitch / DEG, yaw / DEG, rollTowards(forward, pitch, yaw, up) / DEG];
+}
+/**
+ * The rotation about `forward` that takes the world-up-locked up vector onto
+ * the requested one.
+ *
+ * Only the component of `up` perpendicular to `forward` can be honoured — the
+ * parallel component is asking the camera to look along its own up, which is
+ * not a rotation. So it is projected out, and an up parallel to forward leaves
+ * nothing to aim at and returns zero rather than a NaN.
+ */
+function rollTowards(forward, pitch, yaw, up) {
+    const desired = normalize([
+        up[0] - forward[0] * dot(up, forward),
+        up[1] - forward[1] * dot(up, forward),
+        up[2] - forward[2] * dot(up, forward),
+    ]);
+    if (desired[0] === 0 && desired[1] === 0 && desired[2] === 0)
+        return 0;
+    // The up this camera has with no roll, taken from the basis rather than
+    // rebuilt, so the two cannot drift apart.
+    const locked = cameraBasis({
+        ...CAMERA_ROTATION_ONLY,
+        rotate: [pitch / DEG, yaw / DEG, 0],
+    }).up;
+    // `cross(desired, locked)` rather than the other way round: a positive
+    // `rotate.z` carries the camera's up toward its own -X, so the angle that
+    // takes `locked` onto `desired` runs the opposite way.
+    return Math.atan2(dot(cross(desired, locked), forward), dot(locked, desired));
+}
+/** Only `rotate` is read by `cameraBasis`, so the rest is filler rather than a
+ *  claim about any real camera. */
+const CAMERA_ROTATION_ONLY = {
+    translate: [0, 0, 0],
+    focal: 50,
+    aperture: 41.4214,
+    near: 0.001,
+    far: 10000,
+    resolution: [1, 1],
+    aspect: 1,
+    projection: "perspective",
+    orthowidth: 2,
+};
+/** The camera's axes, applying Houdini's XYZ rotation order to a camera that
+ *  looks down -Z at rest. */
+export function cameraBasis(camera) {
+    const [rx, ry, rz] = camera.rotate;
+    const sx = Math.sin(rx * DEG);
+    const cx = Math.cos(rx * DEG);
+    const sy = Math.sin(ry * DEG);
+    const cy = Math.cos(ry * DEG);
+    const sz = Math.sin(rz * DEG);
+    const cz = Math.cos(rz * DEG);
+    /**
+     * `R = Ry * Rx * Rz` on a column vector: yaw about world +Y, then pitch
+     * about the camera's own right, then roll about its own view direction.
+     *
+     * This is the third order tried and the reason is worth writing down, because
+     * two of them are indistinguishable by almost every test. With `rotate.z` at
+     * zero all three agree exactly — so yaw, pitch, look-at and orthonormality
+     * passed under each, and only the roll separates them. Under `Rz * Ry * Rx`,
+     * written first, `rotate.z` turns the camera about the WORLD z axis, which
+     * looks like a roll for as long as the camera faces -Z and stops being one
+     * the moment it does not. Under `Rx * Ry * Rz` the yaw stops being a yaw
+     * about world up, which is what an orbit needs. This order is the one every
+     * camera rig uses, and it is what banking a camera means.
+     */
+    const m00 = cy * cz + sy * sx * sz;
+    const m01 = -cy * sz + sy * sx * cz;
+    const m02 = sy * cx;
+    const m10 = cx * sz;
+    const m11 = cx * cz;
+    const m12 = -sx;
+    const m20 = -sy * cz + cy * sx * sz;
+    const m21 = sy * sz + cy * sx * cz;
+    const m22 = cy * cx;
+    const right = [m00, m10, m20];
+    const up = [m01, m11, m21];
+    // Its own -Z, which is the whole convention in one line.
+    const forward = [-m02, -m12, -m22];
+    return { eye: camera.translate, forward, right, up };
+}
+/**
+ * The horizontal field of view in degrees, from the lens rather than stored.
+ *
+ * Houdini's defaults of 50 mm and 41.4214 mm are exactly 45°, which is the
+ * check worth having in a test: it is the one value that proves the formula and
+ * the defaults agree.
+ */
+export function horizontalFov(camera) {
+    if (camera.focal === 0)
+        return 0;
+    return (2 * Math.atan(camera.aperture / (2 * camera.focal))) / DEG;
+}
+/**
+ * The VERTICAL field of view in degrees.
+ *
+ * Houdini does not store a vertical aperture; it derives one from the
+ * horizontal aperture, the resolution ratio and the pixel aspect. Which is why
+ * `resolution` is on the camera at all — without it there is no vertical angle
+ * to be had.
+ */
+export function verticalFov(camera) {
+    if (camera.focal === 0)
+        return 0;
+    const [width, height] = camera.resolution;
+    if (width === 0 || camera.aspect === 0)
+        return 0;
+    const verticalAperture = (camera.aperture * height) / (width * camera.aspect);
+    return (2 * Math.atan(verticalAperture / (2 * camera.focal))) / DEG;
+}
+/** Frame aspect — the shape of the picture, pixel aspect included. Distinct
+ *  from `camera.aspect`, which is the aspect of one pixel. */
+export function frameAspect(camera) {
+    const [width, height] = camera.resolution;
+    if (height === 0)
+        return 1;
+    return (width * camera.aspect) / height;
+}
+/** Column-major, GLSL convention, matching `MATRIX_TYPES` in Studio: element 0
+ *  starts the first COLUMN. */
+export function viewMatrix(camera) {
+    const { eye, forward, right, up } = cameraBasis(camera);
+    // The view matrix is the inverse of the camera's transform, and for a
+    // rotation that inverse is the transpose — so the basis vectors become rows.
+    const back = [-forward[0], -forward[1], -forward[2]];
+    return [
+        right[0], up[0], back[0], 0,
+        right[1], up[1], back[1], 0,
+        right[2], up[2], back[2], 0,
+        -(right[0] * eye[0] + right[1] * eye[1] + right[2] * eye[2]),
+        -(up[0] * eye[0] + up[1] * eye[1] + up[2] * eye[2]),
+        -(back[0] * eye[0] + back[1] * eye[1] + back[2] * eye[2]),
+        1,
+    ];
+}
+/** Column-major, and orthographic when the camera says so — `orthowidth` is a
+ *  width in world units, so the height comes from the frame aspect. */
+export function projectionMatrix(camera) {
+    const { near, far } = camera;
+    const aspect = frameAspect(camera);
+    if (camera.projection === "orthographic") {
+        const halfWidth = camera.orthowidth / 2;
+        const halfHeight = aspect === 0 ? halfWidth : halfWidth / aspect;
+        return [
+            1 / halfWidth, 0, 0, 0,
+            0, 1 / halfHeight, 0, 0,
+            0, 0, -2 / (far - near), 0,
+            0, 0, -(far + near) / (far - near), 1,
+        ];
+    }
+    const focalScale = (2 * camera.focal) / camera.aperture;
+    return [
+        focalScale, 0, 0, 0,
+        0, focalScale * aspect, 0, 0,
+        0, 0, -(far + near) / (far - near), -1,
+        0, 0, (-2 * far * near) / (far - near), 0,
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/runtime/definition/architecture.js

@@ -16,9 +16,24 @@ const AMBIENT_STATE = new Set([
 export function validateNodeModuleArchitecture(source, fileName, ts) {
     const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
     const diagnostics = [];
+    const exportsDefinition = file.statements.some((statement) => ts.isVariableStatement(statement) && isDefinition(statement));
     for (const statement of file.statements) {
         if (ts.isVariableStatement(statement) && !isDefinition(statement)) {
-            add(statement, "module-state", "Node modules may not declare module-level values; use a pure function or pass state through ports, props, and declared capabilities");
+            // `icon` and `runsOn` get their own sentence, because the general
+            // message sends you looking for the wrong thing. A dynamic node declares
+            // them at module level and must — they are read by a pass over the
+            // source. A definition-v1 node declares them *inside* the definition,
+            // and the moment it does, the module-level copies become exactly the
+            // module state this rule forbids.
+            //
+            // Found the hard way on 2026-09-08: the first literal stub written for a
+            // converted shared node failed here, and the message talks about pure
+            // functions and capabilities while the actual fix is to move two lines
+            // into the object above them. That is not guessable from the error.
+            const superseded = supersededByDefinition(statement);
+            add(statement, "module-state", superseded
+                ? `\`${superseded}\` belongs inside the definition, not beside it — a definition-v1 node declares it as \`${superseded}: ...\` in \`export const definition\`, and a module-level copy is the module state this rule forbids. A dynamic node without a definition still declares it here.`
+                : "Node modules may not declare module-level values; use a pure function or pass state through ports, props, and declared capabilities");
         }
         else if (ts.isClassDeclaration(statement) ||
             ts.isEnumDeclaration(statement) ||
@@ -62,6 +77,26 @@ export function validateNodeModuleArchitecture(source, fileName, ts) {
             (ts.isMethodDeclaration(parent) && parent.name === node) ||
             (ts.isPropertyDeclaration(parent) && parent.name === node));
     }
+    /**
+     * The name of a declaration a `definition` has taken over, or null.
+     *
+     * Only reported when the file actually exports a definition: without one,
+     * `export const icon` is the correct and only way to state it, and telling
+     * somebody to move it into an object that does not exist would be worse than
+     * the general message.
+     */
+    function supersededByDefinition(statement) {
+        if (!exportsDefinition)
+            return null;
+        const declaration = statement.declarationList.declarations[0];
+        if (statement.declarationList.declarations.length !== 1)
+            return null;
+        if (!declaration || !ts.isIdentifier(declaration.name))
+            return null;
+        return declaration.name.text === "icon" || declaration.name.text === "runsOn"
+            ? declaration.name.text
+            : null;
+    }
     function isDefinition(statement) {
         return Boolean(statement.declarationList.flags & ts.NodeFlags.Const) &&
             Boolean(statement.modifiers?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword)) &&

package/dist/runtime/gpu.d.ts

@@ -0,0 +1,33 @@
+import type { GpuCapability } from "@field/cascade/contracts";
+export interface GpuHostAcquisition {
+    readonly device: GpuCapability["device"];
+    readonly info?: Partial<GpuCapability["adapterInfo"]>;
+    /** May be a getter-backed `GPUSupportedLimits`; normalized by the host. */
+    readonly limits: unknown;
+    /**
+     * Release provider-owned references after the device is no longer usable.
+     * Native providers need this in addition to `GPUDevice.destroy()` so their
+     * bindings can stop background work and allow the process to exit.
+     */
+    readonly release?: () => void | Promise<void>;
+}
+export interface GpuHostOptions {
+    readonly acquire: () => Promise<GpuHostAcquisition>;
+}
+/**
+ * A host-owned GPU device with page/process-wide and per-node cache scopes.
+ *
+ * The runtime can await `ensure()` before a cook while node implementations
+ * continue to receive the synchronous `GpuCapability` contract. Ownership
+ * remains with the injecting host: runtimes and graphs never dispose it.
+ */
+export interface GpuHost extends GpuCapability {
+    ensure(): Promise<void>;
+    forNode(nodeId: string): GpuCapability;
+    dispose(): Promise<void>;
+}
+export declare function isGpuHost(value: unknown): value is GpuHost;
+export declare function createGpuHost(options: GpuHostOptions): GpuHost;
+/** Getter-backed supported-limits objects cannot be normalized with spread. */
+export declare function readGpuLimits(source: unknown): Record<string, number>;
+//# sourceMappingURL=gpu.d.ts.map

package/dist/runtime/gpu.js

@@ -0,0 +1,218 @@
+const HOST_SCOPE = "\u0000host";
+const MISSING_DEVICE = "The gpu capability was used before its device was ready — the host must await ensure() before a cook.";
+const DISPOSED = "The gpu capability has been disposed.";
+export function isGpuHost(value) {
+    return (!!value &&
+        typeof value.ensure === "function" &&
+        typeof value.forNode === "function" &&
+        typeof value.dispose === "function");
+}
+export function createGpuHost(options) {
+    let active = null;
+    let starting = null;
+    let disposal = null;
+    let disposed = false;
+    const caches = new Map();
+    const retiring = new Set();
+    const retirementErrors = [];
+    function dropCaches() {
+        const errors = [];
+        const scopes = [...caches.values()];
+        caches.clear();
+        for (const entries of scopes) {
+            for (const entry of entries.values()) {
+                try {
+                    entry.destroy?.(entry.value);
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+        }
+        return errors;
+    }
+    async function release(acquired, destroyDevice) {
+        if (acquired.released)
+            return [];
+        acquired.released = true;
+        const errors = [];
+        if (destroyDevice) {
+            try {
+                acquired.device.destroy();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        try {
+            await acquired.release?.();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        return errors;
+    }
+    function throwCleanupErrors(errors) {
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            const combined = new Error("GPU host cleanup failed");
+            Object.assign(combined, { errors });
+            throw combined;
+        }
+    }
+    function watchLoss(acquired) {
+        void acquired.device.lost.then(() => {
+            if (disposed || active !== acquired)
+                return;
+            active = null;
+            retirementErrors.push(...dropCaches());
+            const cleanup = release(acquired, false).then((errors) => {
+                retirementErrors.push(...errors);
+            });
+            retiring.add(cleanup);
+            void cleanup.finally(() => retiring.delete(cleanup));
+        }).catch(() => {
+            // A rejected loss notification cannot be acted on safely. The active
+            // device remains usable until WebGPU reports otherwise or the owner
+            // disposes the host.
+        });
+    }
+    async function start() {
+        const result = await options.acquire();
+        const acquired = {
+            device: result.device,
+            info: {
+                vendor: result.info?.vendor ?? "",
+                architecture: result.info?.architecture ?? "",
+                device: result.info?.device ?? "",
+                description: result.info?.description ?? "",
+            },
+            limits: readGpuLimits(result.limits),
+            release: result.release,
+            released: false,
+        };
+        if (disposed) {
+            const errors = await release(acquired, true);
+            throwCleanupErrors(errors);
+            throw new Error(DISPOSED);
+        }
+        active = acquired;
+        watchLoss(acquired);
+    }
+    const host = {
+        get device() {
+            if (!active)
+                throw new Error(MISSING_DEVICE);
+            return active.device;
+        },
+        get adapterInfo() {
+            if (!active)
+                throw new Error(MISSING_DEVICE);
+            return active.info;
+        },
+        get limits() {
+            return active?.limits ?? {};
+        },
+        cache(key, create, destroy) {
+            return host.forNode(HOST_SCOPE).cache(key, create, destroy);
+        },
+        async ensure() {
+            if (disposed)
+                throw new Error(DISPOSED);
+            if (active)
+                return;
+            if (!starting) {
+                const attempt = start();
+                const tracked = attempt.finally(() => {
+                    if (starting === tracked)
+                        starting = null;
+                });
+                starting = tracked;
+            }
+            await starting;
+        },
+        forNode(nodeId) {
+            return {
+                get device() {
+                    if (!active)
+                        throw new Error(MISSING_DEVICE);
+                    return active.device;
+                },
+                get adapterInfo() {
+                    if (!active)
+                        throw new Error(MISSING_DEVICE);
+                    return active.info;
+                },
+                get limits() {
+                    return active?.limits ?? {};
+                },
+                cache(key, create, destroy) {
+                    if (!active)
+                        throw new Error(MISSING_DEVICE);
+                    let entries = caches.get(nodeId);
+                    if (!entries) {
+                        entries = new Map();
+                        caches.set(nodeId, entries);
+                    }
+                    const existing = entries.get(key);
+                    if (existing)
+                        return existing.value;
+                    const value = create(active.device);
+                    entries.set(key, {
+                        value,
+                        destroy: destroy,
+                    });
+                    return value;
+                },
+            };
+        },
+        dispose() {
+            disposal ??= performDispose();
+            return disposal;
+        },
+    };
+    async function performDispose() {
+        disposed = true;
+        const errors = dropCaches();
+        const pending = starting;
+        if (pending) {
+            try {
+                await pending;
+            }
+            catch (error) {
+                if (!(error instanceof Error && error.message === DISPOSED))
+                    errors.push(error);
+            }
+        }
+        const acquired = active;
+        active = null;
+        if (acquired)
+            errors.push(...(await release(acquired, true)));
+        await Promise.all([...retiring]);
+        errors.push(...retirementErrors);
+        retirementErrors.length = 0;
+        throwCleanupErrors(errors);
+    }
+    return host;
+}
+/** Getter-backed supported-limits objects cannot be normalized with spread. */
+export function readGpuLimits(source) {
+    if (!source || typeof source !== "object")
+        return {};
+    const names = new Set(Object.keys(source));
+    for (let cursor = Object.getPrototypeOf(source); cursor && cursor !== Object.prototype; cursor = Object.getPrototypeOf(cursor)) {
+        for (const key of Object.getOwnPropertyNames(cursor)) {
+            if (key !== "constructor")
+                names.add(key);
+        }
+    }
+    const limits = {};
+    for (const key of names) {
+        const value = source[key];
+        if (typeof value === "number")
+            limits[key] = value;
+    }
+    return limits;
+}
+//# sourceMappingURL=gpu.js.map

package/dist/runtime/index.d.ts

@@ -1,7 +1,10 @@
 export { CascadeRuntimeError } from "./error.js";
 export * from "./animation/index.js";
+export * from "./camera/index.js";
+export * from "./series/index.js";
 export * from "./expressions/index.js";
 export * from "./geometry/index.js";
+export * from "./gpu.js";
 export * from "./params/index.js";
 export { createRuntime, PREFLIGHT_WARNING_CODES } from "./runtime.js";
 export type * from "./types.js";

package/dist/runtime/index.js

@@ -1,7 +1,10 @@
 export { CascadeRuntimeError } from "./error.js";
 export * from "./animation/index.js";
+export * from "./camera/index.js";
+export * from "./series/index.js";
 export * from "./expressions/index.js";
 export * from "./geometry/index.js";
+export * from "./gpu.js";
 export * from "./params/index.js";
 export { createRuntime, PREFLIGHT_WARNING_CODES } from "./runtime.js";
 //# sourceMappingURL=index.js.map