@field/cascade 0.4.0 → 0.5.1

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

@@ -0,0 +1,202 @@
+import type { Geometry } from "@field/cascade/contracts";
+import type { ParticleForce } from "./state.js";
+/**
+ * The forces, as plain objects rather than nodes.
+ *
+ * A force reads the state and returns an acceleration. It never moves
+ * anything — integration happens once, in `step`, because two forces that each
+ * integrated would disagree about the order of operations and the result would
+ * depend on wiring order rather than on physics.
+ *
+ * Houdini's names for the parameters, per the standing rule.
+ */
+/** Constant acceleration. Houdini's POP Force, whose parameter is `force`. */
+export declare function gravity(force: readonly number[]): ParticleForce;
+/**
+ * Velocity-opposing drag. Houdini's POP Drag, parameter `airresist`.
+ *
+ * Returned as an acceleration rather than applied as a multiplier on velocity,
+ * which is the same choice as everywhere else here: a drag that scaled velocity
+ * directly would be integrating, and its result would then depend on whether it
+ * ran before or after a force that also scaled velocity.
+ */
+export declare function drag(airresist: number): ParticleForce;
+/**
+ * A heading read from a noise field — the first of the four forces the
+ * living-identity piece applies.
+ *
+ * Value noise on a hashed lattice rather than a gradient noise: it is a few
+ * lines, it is deterministic from `(seed, cell)` with no state, and at the
+ * scales this is used at the difference is not visible. A curl noise belongs in
+ * the same file later and wants the same hash.
+ *
+ * `frequency` is in turns per unit, `amplitude` in units per second squared.
+ */
+export declare function noiseField(options: {
+    readonly seed: number;
+    readonly frequency: number;
+    readonly amplitude: number;
+    /** Advances the field itself, so the flow evolves. Stated by the caller from
+     *  the frame, never read from a clock here. */
+    readonly evolve?: number;
+}): ParticleForce;
+/**
+ * Neighbour separation — the third force, and the expensive one.
+ *
+ * A uniform grid rebuilt every step, which is what the original does and what
+ * `PLAN geometry` says about spatial indexes: they live inside the node that
+ * needs them rather than becoming a type. O(n) for the scales here; a system
+ * large enough to need something better should say so with a measurement.
+ */
+export declare function separation(options: {
+    readonly radius: number;
+    readonly strength: number;
+}): ParticleForce;
+/**
+ * Deterministic value noise. A hash, not a PRNG: the same seed and cell always
+ * give the same number, so nothing carries between particles or frames — the
+ * property that makes re-simulation from frame zero reproduce exactly.
+ */
+export declare function valueNoise(seed: number, x: number, y: number, z?: number): number;
+/**
+ * A force read from a scalar field — the second of the four the
+ * living-identity piece applies, and the one that makes it say something.
+ *
+ * The original renders its word to an offscreen canvas, blurs it, reads the
+ * pixels back and takes central differences to get a gradient. So the target is
+ * a **raster field** rather than a path or an SDF, and that matters: particles
+ * are pulled toward wherever the field is bright, whatever drew it. Text is one
+ * source; a photograph or a noise image would work identically.
+ *
+ * The field arrives as luminance already sampled into a grid, because reading
+ * an `image` port means decoding a file and that belongs in a node rather than
+ * in the arithmetic.
+ */
+export declare function fieldForce(options: {
+    /** Row-major luminance, 0..1, `width * height` values. */
+    readonly field: Float32Array;
+    readonly width: number;
+    readonly height: number;
+    /** The world rectangle the field covers, `[minX, minY, maxX, maxY]`. */
+    readonly bounds: readonly [number, number, number, number];
+    readonly amplitude: number;
+}): ParticleForce;
+/**
+ * Pull particles toward a set of target points. Houdini's POP Attract.
+ *
+ * The composable half of the field idea. `fieldForce` above takes a sampled
+ * raster, which is what the original piece uses; this takes geometry, which is
+ * what a graph can wire without any node doing IO — and turning a word, a
+ * photograph or a shape into target points is upstream work belonging to
+ * whatever node knows about words, photographs or shapes.
+ *
+ * `radius` is what keeps this affordable: beyond it a target is ignored, so
+ * the cost is proportional to nearby targets rather than to all of them. A
+ * radius of 0 means every target pulls every particle, which is occasionally
+ * what you want and is quadratic.
+ */
+export declare function attract(options: {
+    readonly targets: ArrayLike<number>;
+    readonly targetSize: number;
+    readonly targetCount: number;
+    readonly amplitude: number;
+    readonly radius: number;
+}): ParticleForce;
+/**
+ * A flow field carried as geometry: points with a direction on them.
+ *
+ * Marcus's description of the original, 2026-09-09: *"a delicate balance
+ * between a force pulling the particles towards the centre spine of the type
+ * and tangentially around their outlines."* Two components of one field, and
+ * that sentence is the whole specification.
+ *
+ * **Why a blurred field gives you a spine.** A hard letterform's gradient
+ * points at the nearest edge, so attracting up it pins particles to outlines.
+ * Blur the letterform first and each stroke becomes a ridge whose peak runs
+ * down its middle — so the gradient points at the *spine*, and the level sets
+ * run *along* the outline. Which is why the original blurs its text before
+ * reading pixels back: the blur is not softening, it is what turns an outline
+ * into a skeleton.
+ *
+ * So `normal` pulls up the gradient toward the spine, and `tangential` pushes
+ * along the perpendicular — around the outline rather than across it. Balance
+ * those two and you get the original's behaviour; take either away and you get
+ * a clump or a drift.
+ *
+ * The field arrives as points carrying `N`, because that is a vector field in
+ * Cascade's existing vocabulary and it keeps the rasterising upstream in
+ * whatever node knows about type. A core force doing image IO is the thing
+ * that stopped being pure earlier.
+ */
+export declare function flowField(options: {
+    /** Field sample positions, flat, `size` components each. */
+    readonly positions: ArrayLike<number>;
+    readonly positionSize: number;
+    /** The gradient at each sample, same count, 2 components — pointing uphill,
+     *  toward the spine. */
+    readonly directions: ArrayLike<number>;
+    /** The field's value at each sample, 0..1. Optional; without it `hold` can
+     *  do nothing, because there is no level to hold. */
+    readonly levels?: ArrayLike<number>;
+    readonly count: number;
+    /** Along `N`, toward the spine. */
+    readonly normal: number;
+    /** Perpendicular to `N`, around the outline. Sign picks the direction. */
+    readonly tangential: number;
+    /**
+     * Hold this level, rather than climb to the peak.
+     *
+     * Marcus's sharper description, 2026-09-09: *"the lines flow tangentially
+     * around the letters in a bundle … loosely describing the type."* A bundle
+     * is a **contour**, and a contour is a level set — so the way to get one is
+     * not to pull particles toward the spine but to hold them at a chosen
+     * distance from it and let the tangent carry them round.
+     *
+     * Without this, pure tangential flow does produce a bundle and then every
+     * particle converges onto the same level set: measured, and it came out as
+     * one line along the baseline of the whole word rather than a contour per
+     * letter. `hold` is what keeps a particle on the contour it started near.
+     */
+    readonly level?: number;
+    readonly hold?: number;
+    /** Samples beyond this are ignored, and it is also the grid's cell size. */
+    readonly radius: number;
+}): ParticleForce;
+/**
+ * Houdini's POP convention: a force node **accumulates into a `force`
+ * attribute**, and the solver integrates once.
+ *
+ * Added 2026-09-09, when `pop.Simulate` was rebuilt as a network Marcus can
+ * dive into. It is not a refinement — it is the difference between a chain of
+ * force nodes that works and one that is silently wrong.
+ *
+ * The nodes as first written each called `step()` themselves, which integrates.
+ * Chain two of them inside a container and time advances **twice per step**:
+ * the particles move further than the timestep says, the result changes when
+ * you reorder nodes that should commute, and nothing reports an error. Reading
+ * that from a picture is close to impossible, which is why the model has to be
+ * right rather than tested.
+ *
+ * So: `accumulateForce` adds an acceleration to the geometry's `force`
+ * attribute and moves nothing. `forceAttribute` is the force the solver reads
+ * back. The solver integrates and clears it, exactly as a POP network does.
+ */
+export declare function accumulateForce(geometry: Geometry, contribution: Float32Array, size: number): Geometry;
+/**
+ * The accumulated `force` on a geometry, as a force the solver can sum with the
+ * rest.
+ *
+ * Takes the geometry rather than reading through `ParticleState`, because the
+ * state deliberately carries only the attributes the contract makes mandatory —
+ * adding a slot for every attribute a force node might invent is how a state
+ * object becomes a bag. The solver reads this off the geometry it was handed.
+ *
+ * Zero when the attribute is absent, which is the correct reading of "no force
+ * node ran": a solver with nothing wired into it should hold the particles
+ * still rather than refuse to cook.
+ */
+export declare function forceAttribute(geometry: Geometry): ParticleForce;
+/** Drop the accumulated force. The solver calls this after integrating, so a
+ *  step never inherits the previous step's forces. */
+export declare function clearForce(geometry: Geometry): Geometry;
+//# sourceMappingURL=forces.d.ts.map