@field/cascade 0.3.1 → 0.5.1

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/geometry/render.d.ts

@@ -0,0 +1,109 @@
+import { type Camera, type Color, type Geometry } from "@field/cascade/contracts";
+/**
+ * Geometry to a raster, through the camera the render node was given.
+ *
+ * Step 2 of `PLAN viewport.md`, and the half that matters for correctness. The
+ * plan's central rule: **a scene view and a render node must agree, and the
+ * only way to guarantee that is both going through `packages/runtime/src/camera`.**
+ * If a viewport implements its own matrices, the two disagree about framing and
+ * every composition made in one is wrong in the other.
+ *
+ * So this file owns no projection maths at all. `viewMatrix` and
+ * `projectionMatrix` came from the camera module this morning, with Houdini's
+ * conventions already in them — down -Z, +Y up, `focal` and `aperture` rather
+ * than a field of view. All that happens here is the multiply and the raster.
+ *
+ * **Wireframe and points, deliberately, and not because shading is hard.** Every
+ * piece in this vault is lines: `cloud-volumes` is a volume, `particle-type` is
+ * trails, `cloud-plots` is marks. A shaded mode needs normals and a light and
+ * nothing here has a surface to put them on, so it would be a week spent on a
+ * mode with no caller.
+ */
+export interface RenderOptions {
+    readonly camera: Camera;
+    /** Pixels. Independent of the camera's own `resolution`, which describes the
+     *  frame the projection assumes — a preview renders small and frames the
+     *  same. */
+    readonly size: readonly [number, number];
+    readonly background?: Color;
+    /** Fallback stroke for a primitive with no `Cd`. */
+    readonly stroke: Color;
+    readonly strokeWidth: number;
+    readonly opacity: number;
+    /** Radius in pixels for a point with no primitive to belong to. */
+    readonly pointRadius: number;
+    /** Draw unprimitived points at all. A trail system has thousands and they
+     *  are usually noise beside the strokes. */
+    readonly drawPoints: boolean;
+    /** How to make a canvas. The caller has a host; this file does not. */
+    readonly surface: SurfaceFactory;
+}
+/**
+ * The canvas surface this needs, declared rather than imported.
+ *
+ * `packages/runtime` compiles with `lib: ["ES2022"]` and no DOM, deliberately:
+ * it is the host-agnostic half of the system and a `dom` lib would let a DOM
+ * assumption into it by accident. So rather than widening that, this states the
+ * dozen members it actually uses. Both hosts satisfy it — the browser natively,
+ * the headless host through @napi-rs/canvas — and the narrow shape is also the
+ * documentation of what a future host would have to provide.
+ */
+export interface DrawingSurface {
+    readonly width: number;
+    readonly height: number;
+    getContext(kind: "2d"): DrawingContext | null;
+    /** How the raster leaves: both hosts return a PNG blob, and the asset
+     *  capability takes bytes. */
+    convertToBlob(options?: {
+        type?: string;
+    }): Promise<{
+        arrayBuffer(): Promise<ArrayBuffer>;
+    }>;
+}
+export interface DrawingContext {
+    fillStyle: string;
+    strokeStyle: string;
+    lineWidth: number;
+    lineCap: string;
+    lineJoin: string;
+    globalAlpha: number;
+    fillRect(x: number, y: number, width: number, height: number): void;
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    arc(x: number, y: number, radius: number, from: number, to: number): void;
+    stroke(): void;
+    fill(): void;
+}
+/**
+ * Where a surface comes from, injected rather than reached for.
+ *
+ * The first version called `new OffscreenCanvas(...)` directly and it was the
+ * wrong structure twice over. `packages/runtime` is the host-agnostic half of
+ * the system, so a global is exactly the assumption it should not make — and
+ * the test environment proved it immediately with *"OffscreenCanvas is not
+ * defined"*, because the global is installed by the CLI host and by the
+ * browser, not by node.
+ *
+ * So the host assumption lives in the node that has a host, and this file
+ * takes a factory. Which also makes the renderer testable, and a renderer that
+ * cannot be tested without a browser is the thing `PLAN viewport` argues
+ * against building.
+ */
+export type SurfaceFactory = (width: number, height: number) => DrawingSurface;
+/**
+ * A scene onto one surface: the background once, then every geometry through
+ * the same camera.
+ *
+ * Separate from `renderGeometry` only in that it draws N of them. The surface,
+ * the background and the matrices are set up once, which is the reason this is
+ * a function rather than a loop at the call site — a loop there would produce a
+ * surface per geometry and composite them, and compositing straight alpha over
+ * straight alpha darkens every overlap.
+ */
+export declare function renderScene(geometry: readonly Geometry[], options: RenderOptions): DrawingSurface;
+/** One geometry through a camera, on its own surface. */
+export declare function renderGeometry(geometry: Geometry, options: RenderOptions): DrawingSurface;
+/** The raster as PNG bytes, for the asset capability. */
+export declare function renderToPng(surface: DrawingSurface): Promise<Uint8Array>;
+//# sourceMappingURL=render.d.ts.map

package/dist/runtime/geometry/render.js

@@ -0,0 +1,145 @@
+import { POSITION_ATTRIBUTE, } from "@field/cascade/contracts";
+import { projectionMatrix, viewMatrix } from "../camera/index.js";
+import { numericAttribute, readElement } from "./attributes.js";
+/**
+ * A canvas the host already has.
+ *
+ * Both hosts supply `OffscreenCanvas` — the browser natively, the headless host
+ * through @napi-rs/canvas — which is why the node is `portable` with no
+ * capability for drawing and only needs `assets` to write the result.
+ */
+function css(colour) {
+    const [r, g, b, a = 1] = colour;
+    return `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${a})`;
+}
+/** Column-major, GLSL convention, matching the camera module's own output. */
+function multiply(matrix, x, y, z) {
+    return [0, 1, 2, 3].map((row) => matrix[row] * x + matrix[4 + row] * y + matrix[8 + row] * z + matrix[12 + row]);
+}
+/**
+ * A scene onto one surface: the background once, then every geometry through
+ * the same camera.
+ *
+ * Separate from `renderGeometry` only in that it draws N of them. The surface,
+ * the background and the matrices are set up once, which is the reason this is
+ * a function rather than a loop at the call site — a loop there would produce a
+ * surface per geometry and composite them, and compositing straight alpha over
+ * straight alpha darkens every overlap.
+ */
+export function renderScene(geometry, options) {
+    const [width, height] = options.size;
+    const canvas = options.surface(Math.max(1, Math.round(width)), Math.max(1, Math.round(height)));
+    const context = canvas.getContext("2d");
+    if (!context)
+        throw new Error("no 2D context on this surface");
+    if (options.background && options.background[3] > 0) {
+        context.fillStyle = css(options.background);
+        context.fillRect(0, 0, canvas.width, canvas.height);
+    }
+    for (const one of geometry)
+        drawGeometry(context, canvas, one, options);
+    return canvas;
+}
+/** One geometry through a camera, on its own surface. */
+export function renderGeometry(geometry, options) {
+    return renderScene([geometry], options);
+}
+/**
+ * Draw one geometry onto a context that is already sized and cleared.
+ *
+ * The matrices are rebuilt per geometry rather than hoisted, and that is
+ * deliberate: it costs two small matrix builds per geometry and it keeps this
+ * function a pure function of its arguments, so a caller cannot pass a view
+ * matrix that disagrees with the camera it also passed.
+ */
+function drawGeometry(context, canvas, geometry, options) {
+    const view = viewMatrix(options.camera);
+    const projection = projectionMatrix(options.camera);
+    const position = geometry.point[POSITION_ATTRIBUTE];
+    if (!position || position.storage === "string")
+        return;
+    const size = position.size;
+    const points = position.data;
+    const projected = [];
+    for (let index = 0; index < geometry.pointCount; index += 1) {
+        const world = multiply(view, Number(points[index * size]), Number(points[index * size + 1]), size >= 3 ? Number(points[index * size + 2]) : 0);
+        const clip = multiply(projection, world[0], world[1], world[2]);
+        // The perspective divide. `w` is kept so a segment with one vertex behind
+        // the camera can be dropped rather than drawn mirrored — which is what
+        // dividing by a negative w produces, and it looks like a plausible line.
+        const w = clip[3];
+        projected.push({
+            x: (clip[0] / w + 1) * 0.5 * canvas.width,
+            y: (1 - (clip[1] / w + 1) * 0.5) * canvas.height,
+            w,
+        });
+    }
+    // Validated to the sizes the style vocabulary declares, so a `Cd` with three
+    // components is refused rather than read as a colour with a missing channel.
+    // That rule is PLAN geometry's and SvgExport already enforces it; a renderer
+    // that was laxer would draw what the exporter refuses.
+    const colours = numericAttribute(geometry.primitive.Cd, "primitive.Cd", [4]);
+    const widths = numericAttribute(geometry.primitive.width, "primitive.width", [1]);
+    context.lineCap = "round";
+    context.lineJoin = "round";
+    context.globalAlpha = options.opacity;
+    const { vertexPoints, offsets, closed } = geometry.topology;
+    const drawn = new Set();
+    for (let primitive = 0; primitive < geometry.primitiveCount; primitive += 1) {
+        const from = offsets[primitive];
+        const to = offsets[primitive + 1];
+        if (to - from < 2)
+            continue;
+        context.strokeStyle = colours
+            ? css(readElement(colours, primitive))
+            : css(options.stroke);
+        context.lineWidth = widths ? readElement(widths, primitive)[0] : options.strokeWidth;
+        context.beginPath();
+        let open = false;
+        for (let vertex = from; vertex < to; vertex += 1) {
+            const point = vertexPoints[vertex];
+            drawn.add(point);
+            const at = projected[point];
+            if (!at || at.w <= 0) {
+                // Behind the camera: break the run rather than joining across it. A
+                // line from an on-screen vertex to a mirrored one is the failure this
+                // avoids, and it draws as a plausible stroke to the wrong place.
+                open = false;
+                continue;
+            }
+            if (open)
+                context.lineTo(at.x, at.y);
+            else {
+                context.moveTo(at.x, at.y);
+                open = true;
+            }
+        }
+        if (closed[primitive] === 1 && open) {
+            const first = projected[vertexPoints[from]];
+            if (first && first.w > 0)
+                context.lineTo(first.x, first.y);
+        }
+        context.stroke();
+    }
+    if (options.drawPoints && options.pointRadius > 0) {
+        context.fillStyle = css(options.stroke);
+        for (let index = 0; index < projected.length; index += 1) {
+            // Only points no primitive claimed. A trail system has thousands of
+            // vertices and drawing a dot on every one buries the strokes.
+            if (drawn.has(index))
+                continue;
+            const at = projected[index];
+            if (at.w <= 0)
+                continue;
+            context.beginPath();
+            context.arc(at.x, at.y, options.pointRadius, 0, Math.PI * 2);
+            context.fill();
+        }
+    }
+}
+/** The raster as PNG bytes, for the asset capability. */
+export async function renderToPng(surface) {
+    const blob = await surface.convertToBlob({ type: "image/png" });
+    return new Uint8Array(await blob.arrayBuffer());
+}
+//# sourceMappingURL=render.js.map

package/dist/runtime/geometry/svg.d.ts

@@ -53,6 +53,35 @@ export interface SvgExportOptions {
     readonly height?: number;
     /** Added around the derived bounds, in geometry units. */
     readonly margin?: number;
+    /**
+     * An explicit world rectangle, `[minX, minY, maxX, maxY]`, replacing the
+     * derived bounds.
+     *
+     * **A frame sequence needs this and cannot work without it.** The bounds are
+     * derived per export, so in an animation every frame gets its own viewBox —
+     * and as the drawing grows the content appears to scale and drift, which
+     * reads as a camera move nobody asked for. Rendering 110 frames of a
+     * particle system is what surfaced it: the early frames are sparse, so their
+     * bounds are tight, so the first strokes fill the screen and then zoom out
+     * for the rest of the sequence.
+     *
+     * `margin` still applies, so a fixed rectangle can breathe the same way a
+     * derived one does.
+     */
+    readonly bounds?: readonly [number, number, number, number];
+    /**
+     * A ground behind the drawing, or absent for a transparent document.
+     *
+     * Absent by default, because plotter work wants paper and a filled rectangle
+     * is a rectangle a pen would draw. It exists for the other case: a piece
+     * framed on screen has a ground, and every preview of one was otherwise
+     * hand-editing a `<rect>` into the file afterwards — which is the sort of
+     * step that says a prop is missing.
+     *
+     * Emitted at the viewBox rather than at the document size, so it fills the
+     * frame however the drawing is fitted inside it.
+     */
+    readonly background?: Color;
     /** Fallback stroke colour for a primitive with no `Cd`. */
     readonly stroke?: Color;
     /** Fallback stroke width for a primitive with no `width`. */

package/dist/runtime/geometry/svg.js

@@ -7,11 +7,14 @@ const BLACK = [0, 0, 0, 1];
 export function geometryToSvg(geometry, options = {}) {
     validateOptions(options);
     const margin = options.margin ?? 0;
-    const bounds = geometryBounds(geometry);
-    const minX = bounds === undefined ? 0 : bounds.min[0] - margin;
-    const minY = bounds === undefined ? 0 : bounds.min[1] - margin;
-    const maxX = bounds === undefined ? 1 : bounds.max[0] + margin;
-    const maxY = bounds === undefined ? 1 : bounds.max[1] + margin;
+    // An explicit rectangle wins over the geometry's own, because the caller
+    // stating a frame is a stronger signal than the content filling one.
+    const explicit = options.bounds;
+    const bounds = explicit ? undefined : geometryBounds(geometry);
+    const minX = explicit ? explicit[0] - margin : bounds === undefined ? 0 : bounds.min[0] - margin;
+    const minY = explicit ? explicit[1] - margin : bounds === undefined ? 0 : bounds.min[1] - margin;
+    const maxX = explicit ? explicit[2] + margin : bounds === undefined ? 1 : bounds.max[0] + margin;
+    const maxY = explicit ? explicit[3] + margin : bounds === undefined ? 1 : bounds.max[1] + margin;
     const spanX = Math.max(maxX - minX, Number.EPSILON);
     const spanY = Math.max(maxY - minY, Number.EPSILON);
     const width = options.width && options.width > 0 ? options.width : spanX;
@@ -91,6 +94,9 @@ export function geometryToSvg(geometry, options = {}) {
     }
     const root = [
         `<svg xmlns="http://www.w3.org/2000/svg" width="${number(width)}" height="${number(height)}" viewBox="${number(minX)} ${number(-maxY)} ${number(spanX)} ${number(spanY)}">`,
+        ...(options.background
+            ? [indent(`<rect x="${number(minX)}" y="${number(-maxY)}" width="${number(spanX)}" height="${number(spanY)}" fill="${Color.toHex(options.background)}" />`, 1)]
+            : []),
         indent("<!-- Geometry is +Y up; SVG is +Y down. This is the one flip. -->", 1),
         indent(`<g transform="scale(1,-1)" fill="${filled ? Color.toHex(fill) : "none"}"${filled && Color.alpha(fill) < 1
             ? ` fill-opacity="${number(Color.alpha(fill))}"`

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