@field/cascade 0.3.1 → 0.5.1

package/dist/cli/runtime/gpu.ts

@@ -74,3 +74,74 @@ export const ColorWrite = {
   ALPHA: 0x8,
   ALL: 0xf,
 } as const;
+
+/** Read one single-sample rgba8unorm 2D texture into owned, tightly packed
+ * top-left RGBA bytes. No colour conversion, PNG encoding or graph transport.
+ * The caller owns the source texture and must give it COPY_SRC usage.
+ */
+export async function readTexture(
+  device: GPUDevice,
+  texture: GPUTexture,
+  options: { signal?: {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void, options?: { once?: boolean }): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+  } } = {},
+): Promise<{ data: Uint8Array<ArrayBuffer>; width: number; height: number }> {
+  const { signal } = options;
+  if (signal?.aborted) throw new Error('GPU readback aborted');
+  if (texture.format !== 'rgba8unorm' || texture.dimension !== '2d'
+    || texture.depthOrArrayLayers !== 1 || texture.sampleCount !== 1
+    || !(texture.usage & TextureUsage.COPY_SRC)) {
+    throw new Error('GPU readback requires a single-sample rgba8unorm 2D texture with COPY_SRC usage');
+  }
+  const { width, height } = texture;
+  const rowBytes = width * 4;
+  const bytesPerRow = Math.ceil(rowBytes / 256) * 256;
+  let buffer: GPUBuffer | undefined;
+  let mapped = false;
+  let abort: (() => void) | undefined;
+  let errorScopeOpen = false;
+  try {
+    device.pushErrorScope('validation');
+    errorScopeOpen = true;
+    buffer = device.createBuffer({
+      label: 'Cascade RGBA readback', size: bytesPerRow * height,
+      usage: BufferUsage.COPY_DST | BufferUsage.MAP_READ,
+    });
+    const encoder = device.createCommandEncoder();
+    encoder.copyTextureToBuffer({ texture }, { buffer, bytesPerRow }, [width, height]);
+    device.queue.submit([encoder.finish()]);
+    const validation = device.popErrorScope();
+    errorScopeOpen = false;
+    const completion = Promise.allSettled([buffer.mapAsync(MapMode.READ), validation]);
+    let completed: Awaited<typeof completion>;
+    if (signal) {
+      completed = await Promise.race([completion, new Promise<never>((_, reject) => {
+        abort = () => reject(new Error('GPU readback aborted'));
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted) abort();
+      })]);
+    } else completed = await completion;
+    const mappingResult = completed[0];
+    const validationResult = completed[1];
+    if (validationResult.status === 'rejected') throw validationResult.reason;
+    const validationError = validationResult.value;
+    if (validationError) throw new Error(`GPU readback validation failed: ${validationError.message}`);
+    if (mappingResult.status === 'rejected') throw mappingResult.reason;
+    mapped = true;
+    if (signal?.aborted) throw new Error('GPU readback aborted');
+    const source = new Uint8Array(buffer.getMappedRange());
+    const data = new Uint8Array(rowBytes * height);
+    for (let y = 0; y < height; y++) data.set(source.subarray(y * bytesPerRow, y * bytesPerRow + rowBytes), y * rowBytes);
+    return { data, width, height };
+  } finally {
+    if (abort) signal?.removeEventListener('abort', abort);
+    if (errorScopeOpen) {
+      try { await device.popErrorScope(); }
+      catch { /* Preserve the operation's original failure. */ }
+    }
+    if (mapped) buffer?.unmap();
+    buffer?.destroy();
+  }
+}

package/dist/cli/runtime/io.ts

@@ -1,19 +1,5 @@
-/**
- * `cascade/io` — the runtime a BROWSER-side node imports.
- *
- * The interop rests on one rule: an image port carries a project-relative PATH,
- * never pixels. A Python node writes a file and emits its path; a WebGL node
- * reads that path as a texture, renders, writes its result back, and emits a
- * path of the same kind. Neither knows or cares which side produced its input,
- * which is what makes the two interchangeable — and it lets the heavy stages
- * stay in Python while the interactive ones run in the page.
- *
- * The counterpart on the server side is the project's own exec bridge
- * (`runStage`), which is per-project because the stages are.
- *
- * This file is compiled into any node module that imports 'cascade/io'; it is
- * not published to npm and has no dependencies.
- */
+/** Shared `cascade/io` helpers. Studio uses project HTTP routes; other hosts
+ * install a bridge. Image ports carry paths rather than ambient pixel buffers. */
 
 export interface MediaOptions {
   /** Ask for a resized copy. Never upscales past the file's own resolution. */
@@ -30,6 +16,8 @@ export interface MediaOptions {
 /** Build the URL that serves a project file to the page. */
 export function mediaUrl(path: string, options: MediaOptions = {}): string {
   if (/^(https?:|data:|blob:)/.test(path)) return path;
+  const bridge = localIo();
+  if (bridge?.url) return bridge.url(path, options);
   const clean = path.replace(/^\.?\//, '');
   const encoded = clean.split('/').map(encodeURIComponent).join('/');
   const params = new URLSearchParams();
@@ -61,6 +49,8 @@ export interface IoBridge {
   read(path: string, options?: MediaOptions): Promise<Uint8Array>;
   /** Write bytes into the project cache. Returns the stored project-relative path. */
   write(path: string, data: Uint8Array): Promise<string>;
+  /** Host-owned display URL, valid until the host releases its stored asset. */
+  url?(path: string, options?: MediaOptions): string;
 }
 
 const IO_BRIDGE_KEY = '__cascadeIoBridge';
@@ -108,20 +98,36 @@ export async function loadBytes(path: string, options: MediaOptions = { raw: tru
 export async function loadImage(path: string, options: MediaOptions = { raw: true }): Promise<HTMLImageElement> {
   const image = new Image();
   const bridge = localIo();
-  if (bridge) {
-    // No origin to resolve a URL against; hand the decoder the bytes.
-    (image as unknown as { src: unknown }).src = new Uint8Array(await loadBytes(path, options));
-  } else {
-    image.crossOrigin = 'anonymous';
-    image.src = mediaUrl(path, options);
+  let temporaryUrl: string | undefined;
+  try {
+    if (bridge?.url) {
+      image.crossOrigin = 'anonymous';
+      image.src = bridge.url(path, options);
+    } else if (bridge) {
+      const bytes = await loadBytes(path, options);
+      if (typeof document === 'undefined') {
+        // The Node canvas Image decoder accepts bytes, not browser Blob URLs.
+        (image as unknown as { src: unknown }).src = new Uint8Array(bytes);
+      } else {
+        temporaryUrl = URL.createObjectURL(new Blob([bytes]));
+        image.src = temporaryUrl;
+      }
+    } else {
+      image.crossOrigin = 'anonymous';
+      image.src = mediaUrl(path, options);
+    }
+    await image.decode();
+    return image;
+  } finally {
+    if (temporaryUrl) URL.revokeObjectURL(temporaryUrl);
   }
-  await image.decode();
-  return image;
 }
 
 /** Same, as an ImageBitmap — the right input for `texImage2D`. */
 export async function loadBitmap(path: string, options: MediaOptions = { raw: true }): Promise<ImageBitmap> {
-  if (localIo()) return createImageBitmap(new Blob([await loadBytes(path, options)]));
+  const bridge = localIo();
+  if (bridge?.url) return createImageBitmap(await loadImage(path, options));
+  if (bridge) return createImageBitmap(new Blob([await loadBytes(path, options)]));
   const response = await fetch(mediaUrl(path, options));
   if (!response.ok) throw new Error(`cascade/io: cannot load ${path} (${response.status})`);
   return createImageBitmap(await response.blob());

package/dist/contracts/camera.d.ts

@@ -0,0 +1,70 @@
+import type { Vec2i, Vec3 } from "./values.js";
+/**
+ * A camera, following Houdini's `/obj/cam`.
+ *
+ * `AGENTS.md` already required following Houdini's parameter names where
+ * Houdini has an equivalent node, and Marcus restated it for this type
+ * specifically on 2026-09-08. It is worth writing down what that costs, because
+ * the obvious design is not the Houdini one and it was proposed first here:
+ *
+ * **There is no field of view.** Houdini has `focal` (a focal length in
+ * millimetres) and `aperture` (the horizontal aperture, also in millimetres),
+ * and the angle is derived from the two. The defaults — 50 mm on a 41.4214 mm
+ * aperture — are a 45° horizontal field of view, which is where that odd
+ * aperture number comes from. Carrying an `fov` instead would be one number
+ * rather than two, and it would also make every lens value a photographer knows
+ * untypeable.
+ *
+ * **The orientation is `translate` and `rotate`, not eye-and-target.** A
+ * Houdini camera is an object with an ordinary transform, looking down its own
+ * **-Z** with **+Y** up, and look-at is a second mechanism layered on top
+ * (`lookatpath` and `upvector`) rather than the primitive. So `lookat` and `up`
+ * are here as the optional override they are in Houdini, and `rotate` is what
+ * the type actually carries.
+ *
+ * **Rotation is degrees, XYZ order** — Houdini's convention, and already the
+ * one `cascade.geo.Transform` uses for its own `rotate`. Note that this is
+ * deliberately unlike expressions, where bare trigonometry is radians; that
+ * divergence is recorded in `AGENTS.md` and is not new here.
+ *
+ * The one place this departs from Houdini's names is **`resolution` in place of
+ * `resx` and `resy`**, because the vault's more specific rule wins: anything
+ * with an x and a y is one `vec2`, and resolutions are named in that rule
+ * explicitly. Two floats that are really one vector cost two Inspector rows and
+ * two keyframes and let a graph carry a width without its height.
+ *
+ * Resolution belongs to the camera rather than to the render target for a
+ * Houdini reason that is easy to miss: the **vertical** aperture is not stored,
+ * it is derived from the horizontal one and the resolution ratio. So the frame
+ * shape participates in the projection, and a camera that did not know it could
+ * not produce a vertical angle at all.
+ */
+export interface Camera {
+    /** World position. Houdini `t`. */
+    readonly translate: Vec3;
+    /** Degrees, XYZ order. Houdini `r`. The camera looks down its own -Z. */
+    readonly rotate: Vec3;
+    /** Focal length in millimetres. Houdini `focal`, default 50. */
+    readonly focal: number;
+    /** Horizontal aperture in millimetres. Houdini `aperture`, default 41.4214. */
+    readonly aperture: number;
+    /** Near clipping plane. Houdini `near`, default 0.001. */
+    readonly near: number;
+    /** Far clipping plane. Houdini `far`, default 10000. */
+    readonly far: number;
+    /** Frame size in pixels. Houdini `resx`/`resy` as one `vec2i`. */
+    readonly resolution: Vec2i;
+    /** PIXEL aspect ratio, not the frame's. Houdini `aspect`, default 1. */
+    readonly aspect: number;
+    /** Houdini `projection`. */
+    readonly projection: "perspective" | "orthographic";
+    /** Width of the orthographic frame in world units. Houdini `orthowidth`. */
+    readonly orthowidth: number;
+}
+/** Houdini's own defaults, so a camera with nothing set matches a fresh
+ *  `/obj/cam` rather than something invented here. */
+export declare const CAMERA_DEFAULTS: Camera;
+/** True for any object carrying the fields this type is identified by. Used at
+ *  the document boundary, where a value arrives as parsed JSON. */
+export declare function isCamera(value: unknown): value is Camera;
+//# sourceMappingURL=camera.d.ts.map

package/dist/contracts/camera.js

@@ -0,0 +1,27 @@
+/** Houdini's own defaults, so a camera with nothing set matches a fresh
+ *  `/obj/cam` rather than something invented here. */
+export const CAMERA_DEFAULTS = Object.freeze({
+    translate: [0, 0, 0],
+    rotate: [0, 0, 0],
+    focal: 50,
+    aperture: 41.4214,
+    near: 0.001,
+    far: 10000,
+    resolution: [1280, 720],
+    aspect: 1,
+    projection: "perspective",
+    orthowidth: 2,
+});
+/** True for any object carrying the fields this type is identified by. Used at
+ *  the document boundary, where a value arrives as parsed JSON. */
+export function isCamera(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return (Array.isArray(candidate.translate) &&
+        Array.isArray(candidate.rotate) &&
+        typeof candidate.focal === "number" &&
+        typeof candidate.aperture === "number");
+}
+//# sourceMappingURL=camera.js.map

package/dist/contracts/capabilities.d.ts

@@ -77,13 +77,13 @@ export interface PythonCapability {
  * anything a graph author would recognise. So a shared device is not a
  * preference, it is the precondition for a chain of GPU nodes at all.
  *
- * **Stage 0 deliberately carries three members and no textures.** Ports still
- * pass `image`, so every picture is byte-identical to before; what this buys is
+ * **The capability carries a device/cache contract, not graph textures.** Ports
+ * still pass `image`; what this buys is
  * one device instead of one per node module, an owner for `device.lost`, and
  * somewhere legitimate to keep a pipeline — which is what lets the
  * `architecture/ambient-state` rule stay strict. The texture store, the
- * generation-stamped handles and the readback are Stage 1, and the shape of
- * this interface is meant to be lived with for a few days first.
+ * generation-stamped handles remain future work. Explicit RGBA8 readback is a
+ * helper in `cascade/gpu`, shared by browser and native hosts without encoding.
  *
  * The `GPUDevice` type comes from `@webgpu/types`, added to this package's
  * `tsconfig.json` as its only `types` entry. Contracts compiles with
@@ -102,7 +102,7 @@ export interface PythonCapability {
  */
 export interface GpuCapability {
     /**
-     * The one device for this page. Shared by every node declaring `gpu`, which
+     * The one device for this host. Shared by every node declaring `gpu`, which
      * is the whole point — see the note above on why two would be useless.
      */
     readonly device: GPUDevice;
@@ -128,7 +128,7 @@ export interface GpuCapability {
      * right answer again.
      *
      * `create` runs once per key. `destroy` is called when the entry is dropped:
-     * when the device is lost, or when the graph disposes. This is the member
+     * when the device is lost, or when the owning host disposes. This is the member
      * that makes `architecture/module-state` keepable — it was previously
      * forbidding the only available way to hold a pipeline.
      */

package/dist/contracts/definition.d.ts

@@ -1,7 +1,7 @@
 import type { CapabilityMap, CascadeAbortSignal, NodeCapabilityName, ProgressReporter } from "./capabilities.js";
 import type { CascadeType, CoreType, JsonValue, NamespacedType, SerializableValueForType, ValueForType } from "./values.js";
 export type RuntimeEnvironment = "portable" | "browser" | "server";
-export type CapabilityForEnvironment<E extends RuntimeEnvironment> = E extends "portable" ? "assets" | "media" : E extends "browser" ? "assets" | "media" | "gpu" : "files" | "assets" | "media" | "python" | "shell";
+export type CapabilityForEnvironment<E extends RuntimeEnvironment> = E extends "portable" ? "assets" | "media" | "gpu" : E extends "browser" ? "assets" | "media" | "gpu" : "files" | "assets" | "media" | "python" | "shell" | "gpu";
 export type DataTypeForEnvironment<E extends RuntimeEnvironment> = E extends "browser" ? CascadeType : Exclude<CascadeType, "texture">;
 type ControlFor<T extends CascadeType> = T extends "float" ? "number" | "slider" | "range" : T extends "int" ? "int" | "slider" | "range" : T extends "bool" ? "boolean" : T extends "string" ? "text" | "textarea" | "select" : T extends "vec2" | "vec3" | "vec4" | "vec2i" | "vec3i" | "vec4i" ? "vector" : T extends "mat2" | "mat3" | "mat4" ? "matrix" : T extends "color" ? "color" : T extends "image" ? "image" : T extends "asset" ? "asset" | "select" : T extends "texture" ? never : "select";
 /**
@@ -41,12 +41,34 @@ type AcceptMetadata<T extends CascadeType> = T extends "image" | "asset" ? {
 } : {
     readonly accept?: never;
 };
+/**
+ * One choice on a select control: the bare value, or the value with the words
+ * a person reads.
+ *
+ * The labelled form exists because losing it cost something real. Converting
+ * `image-superres` turned *"Off (pass through) / Local — Real-ESRGAN /
+ * Magnific — costs money"* into `off` / `local` / `magnific`, and that third
+ * label carried **the only warning that one of the three engines spends money
+ * per call**. A lost display name is a papercut; a lost cost warning is a
+ * bill. Six props across the sketches had lost their labels by the time this
+ * landed, and that one is why it was not deferred any longer.
+ *
+ * A bare value stays legal, and reads as "the value is the label" — which is
+ * true of most enums and is what every existing definition means.
+ */
+export type SelectOption<T extends CascadeType> = SerializableValueForType<T> | Readonly<{
+    value: SerializableValueForType<T>;
+    label: string;
+    /** Greyed out but visible: an option that exists and cannot be picked
+     *  here, which is more informative than one that is simply absent. */
+    disabled?: boolean;
+}>;
 type SelectMetadata<T extends CascadeType> = {
     readonly control?: Exclude<ControlFor<T>, "select">;
     readonly options?: never;
 } | {
     readonly control: Extract<ControlFor<T>, "select">;
-    readonly options?: readonly SerializableValueForType<T>[];
+    readonly options?: readonly SelectOption<T>[];
 };
 export interface TriggerInputDefinition {
     readonly kind: "trigger";
@@ -100,6 +122,23 @@ export type PropDefinition<T extends PropDataType> = {
      * number came from.
      */
     readonly expression?: string;
+    /**
+     * Render this prop as a button that fires a named action, rather than as an
+     * editable field.
+     *
+     * It exists because converting a node removed a button. `observatory-moment`
+     * declared `action: 'panel:observatory-moments'` as a dynamic node, which the
+     * Inspector renders from `parameter.options.action`; the v1 adapter built its
+     * options from `label`, `min`, `max`, `step` and `options` only, so the
+     * Moment picker quietly became a two-step job through the panel menu instead
+     * of one click on the node. Nothing broke — the panel falls back to the
+     * selected node and reads the same prop — which is exactly why nobody would
+     * have noticed from a test.
+     *
+     * The value is the action name the host dispatches. Cascade does not
+     * interpret it; a `panel:` prefix is a Studio convention, not a contract.
+     */
+    readonly action?: string;
 } & NumericMetadata<T> & AcceptMetadata<T> & SelectMetadata<T>;
 export type AnyPropDefinition = {
     [T in PropDataType]: PropDefinition<T>;
@@ -107,8 +146,27 @@ export type AnyPropDefinition = {
 export interface NodeDefinitionForEnvironment<E extends RuntimeEnvironment> {
     readonly apiVersion: 1;
     readonly runsOn: E;
-    /** Declares that authored nodes may use this node as their parent. */
-    readonly container?: "subnet";
+    /**
+     * Declares that authored nodes may use this node as their parent.
+     *
+     * `subnet` is a **grouping**: the children are ordinary nodes in the one flat
+     * graph, cooked once each in the usual dependency order, and the container is
+     * a boundary for display and for `cascade.core.Input`/`Output` to bind to.
+     *
+     * `feedback` is an **evaluation construct**: the children are removed from the
+     * main order and re-run once per step by the container, with the previous
+     * step's result entering through `cascade.core.Previous`. It exists because a
+     * simulation is the one thing a pure DAG cannot express — which is why Houdini
+     * made its Solver SOP special too — and Marcus asked for it on 2026-09-09,
+     * wanting to dive into a particle node and see its forces as nodes.
+     *
+     * The distinction is load-bearing for correctness, not just for scheduling: a
+     * `subnet` child's output is read once and is a function of the graph, while a
+     * `feedback` child's output is read N times and is a function of the graph
+     * *and* the step. Anything that caches on a node's inputs has to know which
+     * kind it is looking at.
+     */
+    readonly container?: "subnet" | "feedback";
     readonly capabilities?: readonly CapabilityForEnvironment<E>[];
     readonly label?: string;
     readonly description?: string;

package/dist/contracts/index.d.ts

@@ -1,9 +1,13 @@
 export * from "./animation.js";
+export * from "./camera.js";
 export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
 export * from "./geometry.js";
+export * from "./particles.js";
+export * from "./scene.js";
+export * from "./series.js";
 export * from "./validate.js";
 export * from "./values.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/contracts/index.js

@@ -1,9 +1,13 @@
 export * from "./animation.js";
+export * from "./camera.js";
 export * from "./capabilities.js";
 export * from "./color.js";
 export * from "./definition.js";
 export * from "./document.js";
 export * from "./geometry.js";
+export * from "./particles.js";
+export * from "./scene.js";
+export * from "./series.js";
 export * from "./validate.js";
 export * from "./values.js";
 //# sourceMappingURL=index.js.map

package/dist/contracts/particles.d.ts

@@ -0,0 +1,54 @@
+import { type AttributeLevel, type AttributeStorage, type Geometry } from "./geometry.js";
+/**
+ * The attribute contract a particle system reads and writes.
+ *
+ * Step 1 of `PLAN particles.md`, and it is deliberately first: **renaming an
+ * attribute after three operators read it is the expensive change.** So the
+ * names, levels and storage are fixed before any node exists, and nothing here
+ * is a node — this file declares a vocabulary and the checks that hold it.
+ *
+ * Houdini's names throughout, per the standing rule. Where Houdini and Cascade
+ * disagree the reason is written down beside the entry rather than left as a
+ * preference.
+ *
+ * **A particle system is geometry.** There is no particle type: points with
+ * these attributes on them are what a solver reads and what `CopyToPoints`,
+ * `SvgExport` and every other geometry node already understand. That is the
+ * whole reason `PLAN geometry` retires `points` to an alias — four names for
+ * one concept, and a fifth for particles would be worse.
+ */
+export interface ParticleAttributeSpec {
+    readonly name: string;
+    readonly level: AttributeLevel;
+    readonly storage: AttributeStorage;
+    /** Components. `P` is 2 or 3, so it is stated as a range rather than a size. */
+    readonly size: number | readonly [number, number];
+    /** Whether a solver may run without it. */
+    readonly required: boolean;
+    readonly units?: "seconds" | "turns";
+    readonly note: string;
+}
+export declare const PARTICLE_ATTRIBUTES: readonly ParticleAttributeSpec[];
+export declare function particleAttribute(name: string): ParticleAttributeSpec | undefined;
+/** The attributes a solver cannot run without. */
+export declare function requiredParticleAttributes(): readonly ParticleAttributeSpec[];
+export interface ParticleContractViolation {
+    readonly attribute: string;
+    readonly reason: string;
+}
+/**
+ * Whether a geometry carries the attributes a solver reads, in the shapes it
+ * reads them in.
+ *
+ * Returns every violation rather than the first, because the answer a caller
+ * wants is *what is wrong with this geometry* and not *what is the first thing
+ * wrong with it* — a source node missing three attributes should say so once.
+ *
+ * Deliberately not a throw: `cascade check` wants to report this statically
+ * alongside its other findings, and a solver wants to fail with a sentence. The
+ * shared thing between them is the list.
+ */
+export declare function checkParticleContract(geometry: Geometry): readonly ParticleContractViolation[];
+/** True when this geometry could be stepped by a solver. */
+export declare function isParticleGeometry(geometry: Geometry): boolean;
+//# sourceMappingURL=particles.d.ts.map

package/dist/contracts/particles.js

@@ -0,0 +1,167 @@
+import { POSITION_ATTRIBUTE, } from "./geometry.js";
+/**
+ * Position. Already `POSITION_ATTRIBUTE`, and `f64` because the Python bridge
+ * writes points as float64 and narrowing would add a lossy step to a boundary
+ * that is lossless today.
+ */
+const P = {
+    name: POSITION_ATTRIBUTE,
+    level: "point",
+    storage: "f64",
+    size: [2, 3],
+    required: true,
+    note: "Position. Shared with every other geometry node, not a particle attribute.",
+};
+export const PARTICLE_ATTRIBUTES = Object.freeze([
+    P,
+    {
+        name: "v",
+        level: "point",
+        storage: "f32",
+        size: [2, 3],
+        required: true,
+        note: "Velocity, in units per second. f32 rather than f64: a velocity is not a coordinate, so the precision argument for P does not carry over.",
+    },
+    {
+        name: "age",
+        level: "point",
+        storage: "f32",
+        size: 1,
+        required: true,
+        units: "seconds",
+        // The one place this departs from the sketch it is modelled on.
+        note: "Seconds, not frames. A frame count changes meaning with fps, and a graph whose particles die at a different point when rendered at 60 is not deterministic in any useful sense.",
+    },
+    {
+        name: "life",
+        level: "point",
+        storage: "f32",
+        size: 1,
+        required: true,
+        units: "seconds",
+        note: "Life expectancy in seconds. A particle dies when age >= life.",
+    },
+    {
+        name: "id",
+        level: "point",
+        storage: "i32",
+        size: 1,
+        required: true,
+        note: "Stable across frames and across kills. Mandatory: a particle array reorders on every kill, so anything durable and per-particle must key on this rather than on an index.",
+    },
+    {
+        name: "nextid",
+        level: "detail",
+        storage: "i32",
+        size: 1,
+        required: true,
+        note: "The next id to hand out. Houdini's own mechanism for keeping id monotonic, and what stops an id being reused after a kill.",
+    },
+    {
+        name: "Cd",
+        level: "point",
+        storage: "f32",
+        size: 4,
+        required: false,
+        note: "Colour. Owned by the style vocabulary in PLAN geometry, which refuses a Cd that is a string or numeric with any size but four.",
+    },
+    {
+        name: "pscale",
+        level: "point",
+        storage: "f32",
+        size: 1,
+        required: false,
+        note: "Not a POP attribute in Houdini's sense. Writing it is what makes CopyToPoints scale its instances, which is how oriented marks get drawn without a new node.",
+    },
+    {
+        name: "N",
+        level: "point",
+        storage: "f32",
+        size: [2, 3],
+        required: false,
+        note: "Orientation, read by CopyToPoints alongside pscale.",
+    },
+]);
+const BY_NAME = new Map(PARTICLE_ATTRIBUTES.map((spec) => [spec.name, spec]));
+export function particleAttribute(name) {
+    return BY_NAME.get(name);
+}
+/** The attributes a solver cannot run without. */
+export function requiredParticleAttributes() {
+    return PARTICLE_ATTRIBUTES.filter((spec) => spec.required);
+}
+function sizeMatches(spec, size) {
+    return typeof spec.size === "number"
+        ? size === spec.size
+        : size >= spec.size[0] && size <= spec.size[1];
+}
+function describeSize(spec) {
+    return typeof spec.size === "number" ? String(spec.size) : `${spec.size[0]} or ${spec.size[1]}`;
+}
+/**
+ * Whether a geometry carries the attributes a solver reads, in the shapes it
+ * reads them in.
+ *
+ * Returns every violation rather than the first, because the answer a caller
+ * wants is *what is wrong with this geometry* and not *what is the first thing
+ * wrong with it* — a source node missing three attributes should say so once.
+ *
+ * Deliberately not a throw: `cascade check` wants to report this statically
+ * alongside its other findings, and a solver wants to fail with a sentence. The
+ * shared thing between them is the list.
+ */
+export function checkParticleContract(geometry) {
+    const violations = [];
+    for (const spec of PARTICLE_ATTRIBUTES) {
+        if (spec.level === "detail") {
+            const value = geometry.detail[spec.name];
+            if (value === undefined) {
+                if (spec.required) {
+                    violations.push({
+                        attribute: spec.name,
+                        reason: `missing detail attribute ${spec.name} — ${spec.note}`,
+                    });
+                }
+                continue;
+            }
+            if (typeof value !== "number") {
+                violations.push({
+                    attribute: spec.name,
+                    reason: `detail ${spec.name} must be a number, not ${typeof value}`,
+                });
+            }
+            continue;
+        }
+        const attribute = geometry.point[spec.name];
+        if (attribute === undefined) {
+            if (spec.required) {
+                violations.push({
+                    attribute: spec.name,
+                    reason: `missing point attribute ${spec.name} — ${spec.note}`,
+                });
+            }
+            continue;
+        }
+        // A string where a number belongs is the failure that would otherwise
+        // reach arithmetic and produce NaN silently.
+        if (attribute.storage === "string") {
+            violations.push({
+                attribute: spec.name,
+                reason: `${spec.name} is a string attribute; a solver reads it as ${spec.storage}`,
+            });
+            continue;
+        }
+        if (!sizeMatches(spec, attribute.size)) {
+            violations.push({
+                attribute: spec.name,
+                reason: `${spec.name} has size ${attribute.size}; expected ${describeSize(spec)}`,
+            });
+        }
+    }
+    return violations;
+}
+/** True when this geometry could be stepped by a solver. */
+export function isParticleGeometry(geometry) {
+    return checkParticleContract(geometry).length === 0;
+}
+//# sourceMappingURL=particles.js.map