@field/cascade 0.4.0 → 0.5.2

package/dist/runtime/pop/state.js

@@ -0,0 +1,283 @@
+import { POSITION_ATTRIBUTE, checkParticleContract, } from "@field/cascade/contracts";
+import { createAttribute } from "../geometry/attributes.js";
+import { GeometryBuilder } from "../geometry/builder.js";
+/**
+ * The state, read through accessors rather than as raw arrays.
+ *
+ * A class rather than a bag of typed arrays because every operator needs the
+ * same four reads and the same bounds discipline, and because `size` — whether
+ * this is a 2D or 3D system — has to be answered once rather than inferred by
+ * each force from the length of an array it was handed.
+ */
+export class ParticleState {
+    count;
+    size;
+    position;
+    velocity;
+    age;
+    life;
+    id;
+    /**
+     * `Cd`, four components, or null for a system with no colour.
+     *
+     * Null rather than a default white array, because the absence is meaningful:
+     * `SvgExport` and every other consumer falls back to its own stroke prop
+     * when a primitive carries no `Cd`, and filling one in here would take that
+     * choice away from the graph.
+     */
+    colour;
+    nextId;
+    /**
+     * Internal, and taking the arrays by reference rather than copying.
+     *
+     * `@internal` rather than `private` because `step` and `select` are module
+     * functions rather than methods — they are the arithmetic, and putting them
+     * on the class would make a state object that can step itself, which is one
+     * short hop from a state object that holds a clock.
+     *
+     * @internal
+     */
+    static of(fields) {
+        return new ParticleState(fields);
+    }
+    constructor(fields) {
+        this.count = fields.count;
+        this.size = fields.size;
+        this.position = fields.position;
+        this.velocity = fields.velocity;
+        this.age = fields.age;
+        this.life = fields.life;
+        this.id = fields.id;
+        this.colour = fields.colour ?? null;
+        this.nextId = fields.nextId;
+    }
+    /** An empty system. `nextId` starts at 0 and only ever increases. */
+    static empty(size = 2) {
+        return new ParticleState({
+            count: 0, size,
+            position: new Float64Array(0), velocity: new Float32Array(0),
+            age: new Float32Array(0), life: new Float32Array(0), id: new Int32Array(0),
+            colour: null,
+            nextId: 0,
+        });
+    }
+    /**
+     * Read a state out of a geometry.
+     *
+     * Refuses rather than repairs. `checkParticleContract` returns every
+     * violation, and a solver handed a geometry without `id` cannot invent one:
+     * inventing ids per frame is precisely the fault the mandatory `id` exists to
+     * prevent, because it would silently make every particle new every step.
+     */
+    static fromGeometry(geometry) {
+        const violations = checkParticleContract(geometry);
+        if (violations.length > 0) {
+            throw new Error(`not a particle geometry: ${violations.map((v) => v.reason).join("; ")}`);
+        }
+        const position = geometry.point[POSITION_ATTRIBUTE];
+        const velocity = geometry.point.v;
+        return new ParticleState({
+            count: geometry.pointCount,
+            size: position.size,
+            position: Float64Array.from(position.data),
+            velocity: Float32Array.from(velocity.data),
+            age: Float32Array.from(geometry.point.age.data),
+            life: Float32Array.from(geometry.point.life.data),
+            id: Int32Array.from(geometry.point.id.data),
+            colour: geometry.point.Cd && geometry.point.Cd.storage !== "string"
+                ? Float32Array.from(geometry.point.Cd.data)
+                : null,
+            nextId: Number(geometry.detail.nextid ?? geometry.pointCount),
+        });
+    }
+    /** Write the state back out as geometry, one point per particle. */
+    toGeometry() {
+        const builder = new GeometryBuilder({ positionSize: this.size });
+        for (let index = 0; index < this.count; index += 1) {
+            builder.addPoint(this.position[index * this.size], this.position[index * this.size + 1], this.size === 3 ? this.position[index * this.size + 2] : 0);
+        }
+        builder.setAttribute("point", "v", { storage: "f32", size: this.size, data: this.velocity });
+        builder.setAttribute("point", "age", { storage: "f32", size: 1, data: this.age });
+        builder.setAttribute("point", "life", { storage: "f32", size: 1, data: this.life });
+        builder.setAttribute("point", "id", { storage: "i32", size: 1, data: this.id });
+        if (this.colour) {
+            builder.setAttribute("point", "Cd", { storage: "f32", size: 4, data: this.colour });
+        }
+        builder.setDetail("nextid", this.nextId);
+        return builder.build();
+    }
+    /** Add particles, handing each a fresh id. Returns the new state; the
+     *  receiver is not mutated, so a source can be applied to a cached frame. */
+    born(points) {
+        const added = points.life.length;
+        if (added === 0)
+            return this;
+        const count = this.count + added;
+        const position = new Float64Array(count * this.size);
+        const velocity = new Float32Array(count * this.size);
+        const age = new Float32Array(count);
+        const life = new Float32Array(count);
+        const id = new Int32Array(count);
+        const wantsColour = this.colour !== null || points.colour !== undefined;
+        const colour = wantsColour ? new Float32Array(count * 4) : null;
+        if (colour) {
+            // White for anything already present without a colour: a ragged
+            // attribute is not representable, and white is what a fallback stroke
+            // multiplies to itself.
+            colour.fill(1, 0, this.count * 4);
+            if (this.colour)
+                colour.set(this.colour);
+        }
+        position.set(this.position);
+        velocity.set(this.velocity);
+        age.set(this.age);
+        life.set(this.life);
+        id.set(this.id);
+        for (let index = 0; index < added; index += 1) {
+            const at = this.count + index;
+            for (let component = 0; component < this.size; component += 1) {
+                position[at * this.size + component] = points.position[index * this.size + component] ?? 0;
+                velocity[at * this.size + component] = points.velocity?.[index * this.size + component] ?? 0;
+            }
+            life[at] = points.life[index];
+            if (colour) {
+                for (let channel = 0; channel < 4; channel += 1) {
+                    colour[at * 4 + channel] = points.colour
+                        ? Number(points.colour[index * 4 + channel] ?? 1)
+                        : 1;
+                }
+            }
+            // Monotonic, and never reused: a trail keyed on an id that came back
+            // would join two unrelated particles into one stroke.
+            id[at] = this.nextId + index;
+        }
+        return ParticleState.of({
+            count, size: this.size, position, velocity, age, life, id, colour,
+            nextId: this.nextId + added,
+        });
+    }
+}
+/**
+ * One step. Forces, then integrate, then age, then kill.
+ *
+ * The order is Houdini's and it matters: a force that read a position already
+ * advanced by this step's velocity would be integrating twice. So every force
+ * sees the same state, their accelerations sum, and integration happens once.
+ */
+export function step(state, forces, options) {
+    const { timestep, maxSpeed = 0, wrap } = options;
+    const { count, size } = state;
+    if (count === 0)
+        return state;
+    const acceleration = new Float32Array(count * size);
+    for (const force of forces) {
+        const contribution = force.accelerate(state, size);
+        if (contribution.length !== count * size) {
+            throw new Error(`force ${force.label} returned ${contribution.length} values for ${count} particles of size ${size}`);
+        }
+        for (let index = 0; index < acceleration.length; index += 1) {
+            acceleration[index] = acceleration[index] + contribution[index];
+        }
+    }
+    const position = Float64Array.from(state.position);
+    const velocity = Float32Array.from(state.velocity);
+    const age = Float32Array.from(state.age);
+    for (let index = 0; index < count; index += 1) {
+        // Semi-implicit Euler: velocity first, then position from the NEW velocity.
+        // Explicit Euler drifts visibly on a curl field at any timestep a sketch
+        // would use, and the cost of the better one is nothing.
+        let speedSquared = 0;
+        for (let component = 0; component < size; component += 1) {
+            const at = index * size + component;
+            velocity[at] = velocity[at] + acceleration[at] * timestep;
+            speedSquared += velocity[at] * velocity[at];
+        }
+        if (maxSpeed > 0 && speedSquared > maxSpeed * maxSpeed) {
+            const scale = maxSpeed / Math.sqrt(speedSquared);
+            for (let component = 0; component < size; component += 1) {
+                velocity[index * size + component] = velocity[index * size + component] * scale;
+            }
+        }
+        for (let component = 0; component < size; component += 1) {
+            const at = index * size + component;
+            position[at] = position[at] + velocity[at] * timestep;
+        }
+        if (wrap) {
+            position[index * size] = wrapInto(position[index * size], wrap[0], wrap[2]);
+            position[index * size + 1] = wrapInto(position[index * size + 1], wrap[1], wrap[3]);
+        }
+        // Seconds, not frames — the one place this departs from the sketch, and
+        // the reason the contract states a unit.
+        age[index] = age[index] + timestep;
+    }
+    return kill(ParticleState.of({
+        count, size: state.size, position, velocity, age,
+        life: Float32Array.from(state.life), id: Int32Array.from(state.id),
+        colour: state.colour ? Float32Array.from(state.colour) : null,
+        nextId: state.nextId,
+    }));
+}
+function wrapInto(value, low, high) {
+    const span = high - low;
+    if (span <= 0)
+        return value;
+    return low + (((value - low) % span) + span) % span;
+}
+/**
+ * Remove particles whose age has reached their life.
+ *
+ * Compacts in place order, which reorders the arrays — and is exactly why `id`
+ * is mandatory. A `life` of zero or less means immortal, following Houdini,
+ * because a source that does not set a life should not birth particles that
+ * die on their first step.
+ */
+export function kill(state) {
+    const keep = [];
+    for (let index = 0; index < state.count; index += 1) {
+        const life = state.life[index];
+        if (life <= 0 || state.age[index] < life)
+            keep.push(index);
+    }
+    if (keep.length === state.count)
+        return state;
+    return select(state, keep);
+}
+/** A new state holding only these particles, in this order. */
+export function select(state, indices) {
+    const count = indices.length;
+    const { size } = state;
+    const position = new Float64Array(count * size);
+    const velocity = new Float32Array(count * size);
+    const age = new Float32Array(count);
+    const life = new Float32Array(count);
+    const id = new Int32Array(count);
+    const colour = state.colour ? new Float32Array(count * 4) : null;
+    indices.forEach((from, to) => {
+        for (let component = 0; component < size; component += 1) {
+            position[to * size + component] = state.position[from * size + component];
+            velocity[to * size + component] = state.velocity[from * size + component];
+        }
+        age[to] = state.age[from];
+        life[to] = state.life[from];
+        id[to] = state.id[from];
+        if (colour && state.colour) {
+            for (let channel = 0; channel < 4; channel += 1) {
+                colour[to * 4 + channel] = state.colour[from * 4 + channel];
+            }
+        }
+    });
+    return ParticleState.of({
+        count, size, position, velocity, age, life, id, colour, nextId: state.nextId,
+    });
+}
+/** A blank particle geometry, for a source to add to. */
+export function emptyParticleGeometry(size = 2) {
+    const builder = new GeometryBuilder({ positionSize: size });
+    builder.setAttribute("point", "v", createAttribute(0, size, "f32"));
+    builder.setAttribute("point", "age", createAttribute(0, 1, "f32"));
+    builder.setAttribute("point", "life", createAttribute(0, 1, "f32"));
+    builder.setAttribute("point", "id", createAttribute(0, 1, "i32"));
+    builder.setDetail("nextid", 0);
+    return builder.build();
+}
+//# sourceMappingURL=state.js.map

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

@@ -0,0 +1,62 @@
+import { type Geometry } from "@field/cascade/contracts";
+/**
+ * Trails, following Houdini's Trail SOP.
+ *
+ * Marcus, 2026-09-09: *"particle trails as geometry is neater"*, and then
+ * *"Caching just needs to be considered. Houdini has a nice trail node for
+ * this."* Both are load-bearing. Trails being geometry rather than a faded
+ * canvas is what keeps one feedback loop instead of two and makes the result
+ * printable; Houdini's Trail is the precedent for how the history is held.
+ *
+ * **The window is passed in, not held here.** Houdini's Trail keeps a rolling
+ * window of previous frames rather than re-cooking backwards to find them, and
+ * that is the shape — but a module-level buffer is exactly the per-cook state
+ * `cascade check` refuses, and it is what would make a cook depend on how many
+ * times it had run. So this function takes the history and returns geometry,
+ * and whoever owns the cache passes it.
+ *
+ * A trail needs `length` frames of positions, not the whole simulation state,
+ * so the window is bounded where a state cache is not — which is why the
+ * plan's *one cache mechanism, two clients* holds.
+ */
+/** One frame of history: a particle id and where it was. */
+export interface TrailFrame {
+    readonly id: Int32Array;
+    readonly position: Float64Array;
+    readonly size: number;
+}
+export type TrailResult = 
+/** The input points, untouched. Houdini's default. */
+"preserve"
+/** One open polyline per particle, oldest to newest. */
+ | "polylines"
+/** Velocity derived from successive positions, written to `v`, no lines. */
+ | "velocity";
+export interface TrailOptions {
+    readonly result?: TrailResult;
+    /** Frames of history to use. Houdini's `length`. */
+    readonly length?: number;
+    /** Use every nth frame. Houdini's `increment`. */
+    readonly increment?: number;
+    /** Weights the derived velocity. Houdini's `velocityscale`. */
+    readonly velocityscale?: number;
+}
+/**
+ * Read one frame of history out of a particle geometry.
+ *
+ * Positions only. A trail does not need velocity, age or life, and copying
+ * them would make the window several times larger for nothing — the size of
+ * the window is the whole reason this is cheaper than a state cache.
+ */
+export declare function trailFrame(geometry: Geometry): TrailFrame;
+/**
+ * Build trails from a history, oldest frame first.
+ *
+ * **Joined on `id`, never on index.** A particle array reorders on every kill,
+ * so index 3 in one frame is not index 3 in the next — joining by position in
+ * the array would draw a stroke from one particle to an unrelated one, which is
+ * the exact fault the mandatory `id` exists to prevent and would look like a
+ * plausible tangle rather than an error.
+ */
+export declare function buildTrails(history: readonly TrailFrame[], current: Geometry, options?: TrailOptions): Geometry;
+//# sourceMappingURL=trail.d.ts.map

package/dist/runtime/pop/trail.js

@@ -0,0 +1,142 @@
+import { POSITION_ATTRIBUTE } from "@field/cascade/contracts";
+import { GeometryBuilder } from "../geometry/builder.js";
+/**
+ * Read one frame of history out of a particle geometry.
+ *
+ * Positions only. A trail does not need velocity, age or life, and copying
+ * them would make the window several times larger for nothing — the size of
+ * the window is the whole reason this is cheaper than a state cache.
+ */
+export function trailFrame(geometry) {
+    const position = geometry.point[POSITION_ATTRIBUTE];
+    return {
+        id: Int32Array.from((geometry.point.id?.data ?? new Int32Array(0))),
+        position: Float64Array.from(position.data),
+        size: position.size,
+    };
+}
+/**
+ * Build trails from a history, oldest frame first.
+ *
+ * **Joined on `id`, never on index.** A particle array reorders on every kill,
+ * so index 3 in one frame is not index 3 in the next — joining by position in
+ * the array would draw a stroke from one particle to an unrelated one, which is
+ * the exact fault the mandatory `id` exists to prevent and would look like a
+ * plausible tangle rather than an error.
+ */
+export function buildTrails(history, current, options = {}) {
+    const { result = "polylines", length = 12, increment = 1, velocityscale = 1 } = options;
+    if (result === "preserve")
+        return current;
+    const frames = sampled(history, length, increment);
+    const size = frames[0]?.size ?? 2;
+    // id -> the positions it held, oldest first.
+    const paths = new Map();
+    for (const frame of frames) {
+        for (let index = 0; index < frame.id.length; index += 1) {
+            const id = frame.id[index];
+            const path = paths.get(id) ?? [];
+            path.push(frame.position[index * frame.size], frame.position[index * frame.size + 1]);
+            paths.set(id, path);
+        }
+    }
+    if (result === "velocity") {
+        return withDerivedVelocity(current, paths, velocityscale);
+    }
+    const builder = new GeometryBuilder({ positionSize: 2 });
+    const trailIds = [];
+    for (const [id, path] of paths) {
+        // A single position is a point, not a line. Houdini's Trail emits nothing
+        // for a particle born this frame, and a one-point polyline would be a
+        // primitive that draws as nothing while counting as something.
+        if (path.length < 4)
+            continue;
+        const points = [];
+        for (let at = 0; at < path.length; at += 2) {
+            points.push(builder.addPoint(path[at], path[at + 1]));
+        }
+        // `poly`, open. `PRIMITIVE_KINDS` has no separate polyline: an open poly
+        // IS one, which is Houdini's model too.
+        builder.addPrimitive(points, { closed: false, kind: "poly" });
+        trailIds.push(id);
+    }
+    if (trailIds.length > 0) {
+        // Carried to the primitive level so a downstream node can still tell which
+        // particle a stroke belongs to — a trail that loses its id is back to
+        // being addressed by position in an array.
+        builder.setNumericAttribute("primitive", "id", Int32Array.from(trailIds), 1, "i32");
+        /**
+         * And its colour, looked up by id rather than by index.
+         *
+         * `SvgExport` reads a primitive's `Cd` and falls back to its own stroke
+         * prop without one, so promoting the particle's colour to the stroke is
+         * what makes a per-particle colour visible at all. Looked up in `current`
+         * by id because a trail's history may include a particle that has since
+         * died: that stroke gets white and the export's fallback applies, which is
+         * better than a wrong colour and better than dropping the stroke.
+         */
+        const currentColour = current.point.Cd;
+        if (currentColour && currentColour.storage !== "string") {
+            const byId = new Map();
+            const ids = current.point.id?.data;
+            if (ids) {
+                for (let index = 0; index < current.pointCount; index += 1) {
+                    byId.set(Number(ids[index]), index);
+                }
+            }
+            const source = currentColour.data;
+            const colours = new Float32Array(trailIds.length * 4);
+            colours.fill(1);
+            trailIds.forEach((id, primitive) => {
+                const at = byId.get(id);
+                if (at === undefined)
+                    return;
+                for (let channel = 0; channel < 4; channel += 1) {
+                    colours[primitive * 4 + channel] = Number(source[at * 4 + channel] ?? 1);
+                }
+            });
+            builder.setNumericAttribute("primitive", "Cd", colours, 4, "f32");
+        }
+    }
+    void size;
+    return builder.build();
+}
+/** The frames a trail actually uses: the last `length`, every `increment`th,
+ *  oldest first. */
+function sampled(history, length, increment) {
+    const step = Math.max(1, Math.floor(increment));
+    const window = history.slice(Math.max(0, history.length - length * step));
+    if (step === 1)
+        return window;
+    // Counted back from the newest, so the current frame is always included —
+    // a trail whose head lags the particle reads as the whole system trailing.
+    const picked = [];
+    for (let index = window.length - 1; index >= 0; index -= step)
+        picked.unshift(window[index]);
+    return picked;
+}
+/**
+ * Houdini's *Compute Velocity* result: `v` from successive positions.
+ *
+ * A genuinely separate use of the same history, which is why the plan says the
+ * extra modes cost almost nothing once the window exists — and why `Trail` is
+ * more than a node that draws lines.
+ */
+function withDerivedVelocity(current, paths, velocityscale) {
+    const size = current.point[POSITION_ATTRIBUTE].size;
+    const ids = current.point.id?.data;
+    const velocity = new Float32Array(current.pointCount * size);
+    for (let index = 0; index < current.pointCount; index += 1) {
+        const path = ids ? paths.get(Number(ids[index])) : undefined;
+        if (!path || path.length < 4)
+            continue;
+        const last = path.length;
+        velocity[index * size] = (path[last - 2] - path[last - 4]) * velocityscale;
+        velocity[index * size + 1] = (path[last - 1] - path[last - 3]) * velocityscale;
+    }
+    return {
+        ...current,
+        point: { ...current.point, v: { storage: "f32", size, data: velocity } },
+    };
+}
+//# sourceMappingURL=trail.js.map