@field/cascade 0.4.0 → 0.5.2

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

@@ -6,6 +6,7 @@ export * from "./expressions/index.js";
 export * from "./geometry/index.js";
 export * from "./gpu.js";
 export * from "./params/index.js";
+export * from "./scene/index.js";
 export { createRuntime, PREFLIGHT_WARNING_CODES } from "./runtime.js";
 export type * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -6,5 +6,6 @@ export * from "./expressions/index.js";
 export * from "./geometry/index.js";
 export * from "./gpu.js";
 export * from "./params/index.js";
+export * from "./scene/index.js";
 export { createRuntime, PREFLIGHT_WARNING_CODES } from "./runtime.js";
 //# sourceMappingURL=index.js.map

package/dist/runtime/pop/cache.d.ts

@@ -0,0 +1,27 @@
+import { ParticleState } from "./state.js";
+interface Checkpoint {
+    readonly frame: number;
+    readonly state: ParticleState;
+}
+/**
+ * The best checkpoint at or before `frame`, or null to start from scratch.
+ *
+ * Never *after* the frame: a state from frame 90 says nothing about frame 40,
+ * and the temptation to interpolate backwards is how a cache stops being an
+ * accelerator and becomes a second implementation.
+ */
+export declare function checkpointAtOrBefore(key: string, fingerprint: string, frame: number): Checkpoint | null;
+/** Offer a state for keeping. Ignored unless it lands on the stride, so a
+ *  caller can offer every frame without thinking about it. */
+export declare function offerCheckpoint(key: string, fingerprint: string, frame: number, state: ParticleState, stride?: number): void;
+/** Forget everything. For a test that needs a cold seek, and for a host that
+ *  wants to reclaim the memory. */
+export declare function clearCheckpoints(): void;
+/** What is held, for a test or a panel. Not for making decisions with: a caller
+ *  that branched on the cache's contents would be depending on an accelerator. */
+export declare function checkpointStats(): {
+    keys: number;
+    checkpoints: number;
+};
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/runtime/pop/cache.js

@@ -0,0 +1,123 @@
+import { ParticleState } from "./state.js";
+/**
+ * Bounded, process-local simulation checkpoints. Clearing them must not change
+ * outputs: cold simulation is the reference, including the full trail window.
+ * The caller fingerprints every stepping prop and wired geometry value; a
+ * mismatch invalidates that entry. Copies on both boundaries isolate mutable
+ * particle arrays. Studio and CLI frame sequences reuse these checkpoints;
+ * separate CLI processes do not share them.
+ */
+/** Every `stride` frames, plus the newest. Sparse on purpose: a checkpoint per
+ *  frame would hold the whole history, and the point of a checkpoint is that it
+ *  is cheaper than the thing it replaces. */
+const DEFAULT_STRIDE = 8;
+/** Total checkpoints kept across all keys. A simulation of a few thousand
+ *  particles is a few hundred kilobytes a frame, so this is the memory bound
+ *  rather than a count anyone should tune. */
+const MAX_CHECKPOINTS = 64;
+const entries = new Map();
+let clock = 0;
+function cloneState(state) {
+    return ParticleState.of({
+        count: state.count,
+        size: state.size,
+        position: Float64Array.from(state.position),
+        velocity: Float32Array.from(state.velocity),
+        age: Float32Array.from(state.age),
+        life: Float32Array.from(state.life),
+        id: Int32Array.from(state.id),
+        ...(state.colour ? { colour: Float32Array.from(state.colour) } : {}),
+        nextId: state.nextId,
+    });
+}
+/**
+ * The best checkpoint at or before `frame`, or null to start from scratch.
+ *
+ * Never *after* the frame: a state from frame 90 says nothing about frame 40,
+ * and the temptation to interpolate backwards is how a cache stops being an
+ * accelerator and becomes a second implementation.
+ */
+export function checkpointAtOrBefore(key, fingerprint, frame) {
+    const entry = entries.get(key);
+    if (!entry)
+        return null;
+    if (entry.fingerprint !== fingerprint) {
+        // Cleared, not reconciled. Anything that changed the fingerprint changed
+        // what the simulation is.
+        entries.delete(key);
+        return null;
+    }
+    entry.touched = clock += 1;
+    let best = null;
+    for (const checkpoint of entry.checkpoints) {
+        if (checkpoint.frame > frame)
+            break;
+        best = checkpoint;
+    }
+    return best ? { frame: best.frame, state: cloneState(best.state) } : null;
+}
+/** Offer a state for keeping. Ignored unless it lands on the stride, so a
+ *  caller can offer every frame without thinking about it. */
+export function offerCheckpoint(key, fingerprint, frame, state, stride = DEFAULT_STRIDE) {
+    if (frame % stride !== 0)
+        return;
+    let entry = entries.get(key);
+    if (!entry || entry.fingerprint !== fingerprint) {
+        entry = { fingerprint, checkpoints: [], touched: clock += 1 };
+        entries.set(key, entry);
+    }
+    if (entry.checkpoints.some((checkpoint) => checkpoint.frame === frame))
+        return;
+    entry.checkpoints.push({ frame, state: cloneState(state) });
+    entry.checkpoints.sort((a, b) => a.frame - b.frame);
+    entry.touched = clock += 1;
+    evict();
+}
+/**
+ * Drop the least recently used key, then the oldest checkpoints in the one
+ * remaining key, until the total is under the cap.
+ *
+ * Whole-key eviction preserves the most useful simulation when several are
+ * active. The final key is trimmed from its oldest edge rather than exempted:
+ * checkpoints are independent snapshots and lookup already accepts gaps, so
+ * retaining the newest bounded window is correct and useful.
+ */
+function evict() {
+    let total = 0;
+    for (const entry of entries.values())
+        total += entry.checkpoints.length;
+    while (total > MAX_CHECKPOINTS && entries.size > 1) {
+        let oldest = null;
+        let oldestTouched = Infinity;
+        for (const [key, entry] of entries) {
+            if (entry.touched < oldestTouched) {
+                oldestTouched = entry.touched;
+                oldest = key;
+            }
+        }
+        if (oldest === null)
+            return;
+        total -= entries.get(oldest).checkpoints.length;
+        entries.delete(oldest);
+    }
+    if (total > MAX_CHECKPOINTS) {
+        const remaining = entries.values().next().value;
+        if (!remaining)
+            return;
+        remaining.checkpoints.splice(0, total - MAX_CHECKPOINTS);
+    }
+}
+/** Forget everything. For a test that needs a cold seek, and for a host that
+ *  wants to reclaim the memory. */
+export function clearCheckpoints() {
+    entries.clear();
+}
+/** What is held, for a test or a panel. Not for making decisions with: a caller
+ *  that branched on the cache's contents would be depending on an accelerator. */
+export function checkpointStats() {
+    let checkpoints = 0;
+    for (const entry of entries.values())
+        checkpoints += entry.checkpoints.length;
+    return { keys: entries.size, checkpoints };
+}
+//# sourceMappingURL=cache.js.map