@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/particles/graph/ParticleNodeRegistry.js

@@ -1,185 +1,720 @@
-import { NodeRegistry } from "../../../../core/model/node-graph/node/NodeRegistry.js";
-import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
-import { DataType } from "../../../../core/model/node-graph/type/DataType.js";
-import { pack_swizzle, VM_OP } from "../isa/ParticleVMISA.js";
-import { ParticleNodeDescription } from "./ParticleNodeDescription.js";
-
-/**
- * Standard particle-node library, expressed as {@link ParticleNodeDescription}s in a
- * {@link NodeRegistry}. Nodes are value-producing operations (constants, builtins, attribute reads,
- * math, curves, random) or sinks (attribute writes, kill).
- *
- * These lower to the same opcodes the JS reference + WGSL interpreter agree on, so any effect
- * authored here is executable and testable end-to-end on the CPU before it ever hits the GPU.
- */
-
-/**
- * Every value the particle VM computes lives in a `vec4f` register, so a single data type describes
- * every port in the library: any output may drive any input.
- * @type {DataType}
- */
-export const PARTICLE_VALUE_TYPE = DataType.from(0, "vec4");
-
-/**
- * Name of the single output port carried by every value-producing node.
- * @type {string}
- */
-export const PARTICLE_NODE_OUTPUT_PORT = "out";
-
-/**
- * @type {NodeRegistry}
- */
-export const PARTICLE_NODE_REGISTRY = new NodeRegistry();
-
-/**
- * Node descriptions are addressed by name while authoring; the registry itself is keyed by the
- * numeric IDs assigned below.
- *
- * IDs are handed out in declaration order rather than by {@link NodeDescription}'s global counter,
- * so they do not drift with unrelated node usage elsewhere in the engine. Appending new node types
- * at the end of the library is therefore safe; reordering or removing existing ones renumbers every
- * node that follows, which would invalidate already-serialized graphs.
- *
- * @type {Map<string, ParticleNodeDescription>}
- */
-const descriptions_by_name = new Map();
-
-/**
- * @param {string} name
- * @param {string[]} inputs input port names, in operand order
- * @param {function} emit see {@link ParticleNodeDescription#emit}
- * @param {object} [options]
- * @param {boolean} [options.produces_value] when false the node is a sink and gets no output port
- * @returns {ParticleNodeDescription}
- */
-function define(name, inputs, emit, { produces_value = true } = {}) {
-    if (descriptions_by_name.has(name)) {
-        throw new Error(`Duplicate particle node type '${name}'`);
-    }
-
-    const description = new ParticleNodeDescription();
-
-    description.name = name;
-    description.id = descriptions_by_name.size;
-
-    for (const input of inputs) {
-        description.createPort(PARTICLE_VALUE_TYPE, input, PortDirection.In);
-    }
-
-    if (produces_value) {
-        description.createPort(PARTICLE_VALUE_TYPE, PARTICLE_NODE_OUTPUT_PORT, PortDirection.Out);
-    }
-
-    description.emit = emit;
-
-    PARTICLE_NODE_REGISTRY.addNode(description);
-    descriptions_by_name.set(name, description);
-
-    return description;
-}
-
-/** side-effecting sink (no output) */
-function sink(name, inputs, emit) {
-    return define(name, inputs, emit, { produces_value: false });
-}
-
-function unary(name, opcode) {
-    return define(name, ["x"], (s, c) => s.emit(opcode, c.out, c.in("x")));
-}
-
-function binary(name, opcode) {
-    return define(name, ["a", "b"], (s, c) => s.emit(opcode, c.out, c.in("a"), c.in("b")));
-}
-
-const COMPARE_OPCODES = {
-    lt: VM_OP.CMP_LT,
-    le: VM_OP.CMP_LE,
-    gt: VM_OP.CMP_GT,
-    ge: VM_OP.CMP_GE,
-    eq: VM_OP.CMP_EQ,
-};
-
-// --- sources ---
-define("const", [], (s, c) => {
-    const v = c.parameters.value ?? [0, 0, 0, 0];
-    s.loadConst(c.out, c.asm.constant(v[0] ?? 0, v[1] ?? 0, v[2] ?? 0, v[3] ?? 0));
-});
-define("builtin", [], (s, c) => s.loadBuiltin(c.out, c.parameters.id));
-define("attribute", [], (s, c) => {
-    const a = c.layout.get(c.parameters.name);
-    s.loadAttr(c.out, a.offset, a.components);
-});
-define("random", [], (s, c) => s.random(c.out, c.parameters.mode));
-
-// --- sinks ---
-sink("setAttribute", ["value"], (s, c) => {
-    const a = c.layout.get(c.parameters.name);
-    s.storeAttr(c.in("value"), a.offset, a.components);
-});
-sink("kill", ["condition"], (s, c) => s.kill(c.in("condition")));
-
-// --- arithmetic (component-wise) ---
-binary("add", VM_OP.ADD);
-binary("sub", VM_OP.SUB);
-binary("mul", VM_OP.MUL);
-binary("div", VM_OP.DIV);
-binary("min", VM_OP.MIN);
-binary("max", VM_OP.MAX);
-binary("pow", VM_OP.POW);
-binary("step", VM_OP.STEP);
-define("mad", ["a", "b", "c"], (s, c) => s.emit(VM_OP.MAD, c.out, c.in("a"), c.in("b"), c.in("c")));
-define("mix", ["a", "b", "t"], (s, c) => s.emit(VM_OP.MIX, c.out, c.in("a"), c.in("b"), c.in("t")));
-define("clamp", ["x", "lo", "hi"], (s, c) => s.emit(VM_OP.CLAMP, c.out, c.in("x"), c.in("lo"), c.in("hi")));
-define("smoothstep", ["e0", "e1", "x"], (s, c) => s.emit(VM_OP.SMOOTHSTEP, c.out, c.in("e0"), c.in("e1"), c.in("x")));
-define("scale", ["v", "s"], (s, c) => s.emit(VM_OP.SCALE, c.out, c.in("v"), c.in("s")));
-
-// --- unary math ---
-unary("neg", VM_OP.NEG);
-unary("abs", VM_OP.ABS);
-unary("floor", VM_OP.FLOOR);
-unary("fract", VM_OP.FRACT);
-unary("sqrt", VM_OP.SQRT);
-unary("sin", VM_OP.SIN);
-unary("cos", VM_OP.COS);
-unary("exp", VM_OP.EXP);
-unary("log", VM_OP.LOG);
-unary("normalize", VM_OP.NORMALIZE);
-unary("length", VM_OP.LENGTH);
-
-// --- vector ---
-binary("dot", VM_OP.DOT);
-binary("cross", VM_OP.CROSS);
-binary("distance", VM_OP.DISTANCE);
-define("swizzle", ["x"], (s, c) => {
-    const p = c.parameters.pattern ?? [0, 1, 2, 3];
-    s.emit(VM_OP.SWIZZLE, c.out, c.in("x"), pack_swizzle(p[0], p[1], p[2], p[3]));
-});
-
-// --- logic ---
-define("compare", ["a", "b"], (s, c) => {
-    const opcode = COMPARE_OPCODES[c.parameters.op];
-    if (opcode === undefined) {
-        throw new Error(`Unknown compare op '${c.parameters.op}'`);
-    }
-    s.emit(opcode, c.out, c.in("a"), c.in("b"));
-});
-define("select", ["a", "b", "condition"], (s, c) => s.emit(VM_OP.SELECT, c.out, c.in("a"), c.in("b"), c.in("condition")));
-
-// --- curves ---
-define("curve", ["t"], (s, c) => s.curve(c.out, c.parameters.handle, c.in("t")));
-
-/**
- * Look up a node type by name.
- * @param {string} name
- * @returns {ParticleNodeDescription}
- * @throws if no such node type exists
- */
-export function get_particle_node_description(name) {
-    const description = descriptions_by_name.get(name);
-
-    if (description === undefined) {
-        throw new Error(`Unknown particle node type '${name}'`);
-    }
-
-    return description;
-}
+import { NodeRegistry } from "../../../../core/model/node-graph/node/NodeRegistry.js";
+import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
+import { DataType } from "../../../../core/model/node-graph/type/DataType.js";
+import {
+    pack_swizzle,
+    VM_BUILTIN_COMPONENTS,
+    VM_OP,
+    VM_SWIZZLE_BROADCAST,
+    vm_immediate,
+    vm_register,
+} from "../isa/ParticleVMISA.js";
+import { PARTICLE_COMPARE_OPCODES } from "./particle_compare_ops.js";
+import { ParticleGroupBuilder } from "./ParticleGroupBuilder.js";
+import { particle_node_presentation } from "./particle_node_presentation.js";
+import { ParticleNodeDescription } from "./ParticleNodeDescription.js";
+import {
+    PARTICLE_GRADIENT_COLOR_COMPONENTS,
+    roll_out_particle_curve,
+    roll_out_particle_gradient,
+} from "./particle_ramp.js";
+import {
+    PARTICLE_ALL_VALUE_TYPES,
+    PARTICLE_TYPE_COLOR,
+    PARTICLE_TYPE_F32,
+    PARTICLE_TYPE_VEC3,
+    particle_semantic_type,
+    particle_value_type,
+    particle_value_type_or_null,
+    particle_widest_type,
+} from "./ParticleValueType.js";
+
+/**
+ * Standard particle-node library, expressed as {@link ParticleNodeDescription}s in a
+ * {@link NodeRegistry}. Nodes are value-producing operations (constants, builtins, attribute reads,
+ * math, curves, random) or sinks (attribute writes, kill).
+ *
+ * These lower to the same opcodes the JS reference + WGSL interpreter agree on, so any effect
+ * authored here is executable and testable end-to-end on the CPU before it ever hits the GPU.
+ *
+ * ## Types
+ *
+ * A value is a float vector of one to four lanes, and which it is is a property of the node
+ * instance rather than of its type: a `builtin` is a scalar or a `vec3` by which builtin it reads,
+ * a `const` is as wide as the literal it holds, an `add` is as wide as the wider of what it adds.
+ * So every port is declared with the one {@link PARTICLE_VALUE_TYPE} — any output may be wired to
+ * any input — and each node type says how it is typed through
+ * {@link ParticleNodeDescription#infer_types}, which {@link ./infer_particle_graph_types.js}
+ * resolves over a whole graph. The types themselves are in {@link ./ParticleValueType.js}, and
+ * registered here so a view can colour by them.
+ *
+ * A type may also say what a value *means* — {@link PARTICLE_TYPE_COLOR} is four lanes that are a
+ * colour — and the rules below never ask. They compare `components` and take the widest, so a
+ * colour is accepted wherever a `vec4` is, produces whatever a `vec4` would, and survives the
+ * arithmetic in between. The two places a colour enters a graph are the `color` node and an
+ * attribute the effect's layout has tagged as one.
+ */
+
+/**
+ * The declared type of every port in the library: a value goes here.
+ *
+ * Which value — one lane or four — is resolved per node instance, see the note on types above.
+ * Declared once for all ports because the graph model connects ports whose declared types are the
+ * same object, and any particle value may drive any particle input; where the widths differ, the
+ * compiler converts and the validator says so.
+ *
+ * @type {DataType}
+ */
+export const PARTICLE_VALUE_TYPE = DataType.from(0, "value");
+
+/**
+ * Name of the single output port carried by every value-producing node.
+ * @type {string}
+ */
+export const PARTICLE_NODE_OUTPUT_PORT = "out";
+
+/**
+ * @type {NodeRegistry}
+ */
+export const PARTICLE_NODE_REGISTRY = new NodeRegistry();
+
+// The resolved types are the registry's too: a view colours a wire by a type's id, and looks the
+// id up here.
+for (const type of PARTICLE_ALL_VALUE_TYPES) {
+    PARTICLE_NODE_REGISTRY.addType(type);
+}
+
+/**
+ * Node descriptions are addressed by name while authoring; the registry itself is keyed by the
+ * numeric IDs assigned below.
+ *
+ * IDs are handed out in declaration order rather than by {@link NodeDescription}'s global counter,
+ * so they do not drift with unrelated node usage elsewhere in the engine. Appending new node types
+ * at the end of the library is therefore safe; reordering or removing existing ones renumbers every
+ * node that follows, which would invalidate already-serialized graphs.
+ *
+ * @type {Map<string, ParticleNodeDescription>}
+ */
+const descriptions_by_name = new Map();
+
+/**
+ * @param {string} name
+ * @param {string[]} inputs input port names, in operand order
+ * @param {function} emit see {@link ParticleNodeDescription#emit}
+ * @param {object} [options]
+ * @param {boolean} [options.produces_value] when false the node is a sink and gets no output port
+ * @param {function} [options.infer_types] see {@link ParticleNodeDescription#infer_types}
+ * @param {function} [options.operation_width] see {@link ParticleNodeDescription#operation_width}
+ * @param {function} [options.input_widths] see {@link ParticleNodeDescription#input_widths}
+ * @param {function} [options.result_width] see {@link ParticleNodeDescription#result_width}
+ * @returns {ParticleNodeDescription}
+ */
+function define(name, inputs, emit, {
+    produces_value = true,
+    infer_types,
+    operation_width,
+    input_widths,
+    result_width,
+} = {}) {
+    if (descriptions_by_name.has(name)) {
+        throw new Error(`Duplicate particle node type '${name}'`);
+    }
+
+    const description = new ParticleNodeDescription();
+
+    description.name = name;
+    description.id = descriptions_by_name.size;
+
+    // what an author reads is decided in one table, away from the lowering; see
+    // ./particle_node_presentation.js
+    const presentation = particle_node_presentation(name);
+
+    description.display_label = presentation.label;
+    description.icon = presentation.icon;
+    description.help = presentation.help;
+
+    for (const input of inputs) {
+        description.createPort(PARTICLE_VALUE_TYPE, input, PortDirection.In);
+    }
+
+    if (produces_value) {
+        description.createPort(PARTICLE_VALUE_TYPE, PARTICLE_NODE_OUTPUT_PORT, PortDirection.Out);
+    }
+
+    description.emit = emit;
+
+    if (infer_types !== undefined) {
+        description.infer_types = infer_types;
+    }
+
+    if (operation_width !== undefined) {
+        description.operation_width = operation_width;
+    }
+
+    if (input_widths !== undefined) {
+        description.input_widths = input_widths;
+    }
+
+    if (result_width !== undefined) {
+        description.result_width = result_width;
+    }
+
+    PARTICLE_NODE_REGISTRY.addNode(description);
+    descriptions_by_name.set(name, description);
+
+    return description;
+}
+
+/** side-effecting sink (no output) */
+function sink(name, inputs, emit, options = {}) {
+    return define(name, inputs, emit, { ...options, produces_value: false });
+}
+
+/**
+ * A source: no inputs, and a type of its own that its parameters (and the layout) decide.
+ *
+ * @param {string} name
+ * @param {function(object, ParticleLayout|undefined):(ParticleValueType|null)} type_of
+ * @param {function} emit
+ * @param {object} [options]
+ * @returns {ParticleNodeDescription}
+ */
+function source(name, type_of, emit, options = {}) {
+    return define(name, [], emit, {
+        ...options,
+        infer_types: ({ parameters, layout }) => ({ output: type_of(parameters, layout), inputs: {} }),
+    });
+}
+
+function unary(name, opcode, options = {}) {
+    return define(name, ["x"], (s, c) => s.emit(opcode, c.out, c.in("x"), 0, 0, c.width), options);
+}
+
+function binary(name, opcode, options = {}) {
+    return define(name, ["a", "b"], (s, c) => s.emit(opcode, c.out, c.in("a"), c.in("b"), 0, c.width), options);
+}
+
+/**
+ * Every input read at one type.
+ *
+ * @param {Object<string, *>} inputs
+ * @param {ParticleValueType|null} type
+ * @returns {Object<string, ParticleValueType|null>}
+ */
+function read_all_as(inputs, type) {
+    const read = {};
+
+    for (const port of Object.keys(inputs)) {
+        read[port] = type;
+    }
+
+    return read;
+}
+
+/**
+ * @param {Object<string, ParticleValueType>} input_types
+ * @returns {number} lanes of the first input, which for the reductions is the lanes of every input
+ */
+function first_input_width(input_types) {
+    return Object.values(input_types)[0].components;
+}
+
+/**
+ * The same lanes, stripped of what they were for.
+ *
+ * A meaning travels through the operations that stay in the value's own space — a colour scaled,
+ * clamped or mixed is still a colour — and stops at the ones that leave it. A comparison of two
+ * colours is a mask, and the lane that chooses between two colours is a mask; calling either of
+ * those a colour would be the type saying something untrue, which is worse than it saying nothing.
+ *
+ * @param {ParticleValueType|null} type
+ * @returns {ParticleValueType|null}
+ */
+function plain_shape(type) {
+    return type === null ? null : particle_value_type(type.components);
+}
+
+/**
+ * An op whose result is a mask or a ramp rather than another value of what it read: it compares in
+ * the operands' own space, and answers in none.
+ */
+const MASK_RESULT = {
+    infer_types: ({ inputs }) => {
+        const wide = particle_widest_type(Object.values(inputs));
+
+        return { output: plain_shape(wide), inputs: read_all_as(inputs, wide) };
+    },
+};
+
+/**
+ * An op that returns one of the values it was given, or something between them, under the control
+ * of a third: `mix`'s `t`, `select`'s `condition`.
+ *
+ * Two questions with different answers. *How wide* is what it has always been — every operand,
+ * widest wins, so a pair of scalars chosen between by a three-lane mask is still three lanes of
+ * result, which is how a vector was assembled before there were constructors for it. *What it
+ * means* comes only from the ends: the control says which side, not what kind, and a result is only
+ * a colour if the things being blended were.
+ *
+ * @param {string} control the port that steers rather than contributes
+ * @returns {object} description options
+ */
+function blend_controlled_by(control) {
+    return {
+        infer_types: ({ inputs }) => {
+            const width_from = particle_widest_type(Object.values(inputs));
+
+            if (width_from === null) {
+                return { output: null, inputs: read_all_as(inputs, null) };
+            }
+
+            const ends = particle_widest_type([inputs.a, inputs.b]);
+
+            const output = ends !== null && ends.semantic && ends.components === width_from.components
+                ? ends
+                : plain_shape(width_from);
+
+            const read = read_all_as(inputs, output);
+
+            read[control] = plain_shape(output);
+
+            return { output, inputs: read };
+        },
+    };
+}
+
+/**
+ * A reduction: reads every lane of its inputs — which are read at one width, the widest among
+ * them — and writes one, whatever is asked of it. The result is a scalar.
+ */
+const REDUCTION = {
+    infer_types: ({ inputs }) => {
+        const wide = particle_widest_type(Object.values(inputs));
+
+        return { output: wide === null ? null : PARTICLE_TYPE_F32, inputs: read_all_as(inputs, wide) };
+    },
+    operation_width: ({ input_types }) => first_input_width(input_types),
+    result_width: () => 1,
+};
+
+/**
+ * An op that has to see the whole vector to compute any lane of it: a `normalize` feeding a
+ * one-component attribute still divides by the length of the whole vector rather than by the
+ * length of its first lane. Its type is its input's; only the width it runs at differs from the
+ * element-wise default.
+ */
+const WHOLE_VECTOR = {
+    operation_width: ({ type }) => type.components,
+};
+
+
+
+/**
+ * Lane names, in lane order: the input ports of the vector constructors, and how a swizzle is
+ * spelled.
+ * @type {string[]}
+ */
+const LANE_NAMES = ["x", "y", "z", "w"];
+
+/**
+ * @param {object} parameters
+ * @returns {number[]} a literal node's value
+ */
+function literal_of(parameters) {
+    return Array.isArray(parameters.value) ? parameters.value : [];
+}
+
+/**
+ * Lower a literal into the constant pool, at the lanes it is being read at.
+ *
+ * Only those lanes: a scalar literal costs one word of the pool — or, read wider, that word
+ * repeated, which is the broadcast for free — and a wide literal read narrow interns only its
+ * leading words. A lane the value does not have reads zero, which is what a `color` written with
+ * too few numbers gets; the validator reports the parameter, and the compiler does not also throw.
+ *
+ * @param {InstructionStream} s
+ * @param {object} c the emit context
+ */
+function emit_literal(s, c) {
+    const v = literal_of(c.parameters);
+
+    const components = [];
+
+    for (let i = 0; i < c.width; i++) {
+        components.push((c.type.is_scalar ? v[0] : v[i]) ?? 0);
+    }
+
+    s.loadConst(c.out, c.asm.constant(...components), c.width);
+}
+
+/**
+ * @param {object} parameters
+ * @returns {number[]} a swizzle's lane selectors, one per output lane
+ */
+function pattern_of(parameters) {
+    const pattern = parameters.pattern;
+
+    return Array.isArray(pattern) && pattern.length > 0 ? pattern : [0, 1, 2, 3];
+}
+
+/**
+ * @param {number[]} pattern
+ * @returns {number} how many lanes of a source the selectors reach into
+ */
+function pattern_span(pattern) {
+    return 1 + Math.max(...pattern);
+}
+
+/**
+ * The attribute a node names, as a type; `null` where there is no layout to look in or the name is
+ * not in it — which the validator reports in its own words.
+ *
+ * An attribute the layout has tagged (`color`, say) is that type rather than the plain shape, which
+ * is how a colour reaches a graph without a node saying so. The tag has to be the shape the
+ * attribute actually is: three words tagged `color` is a mistake, and reading them as a four-lane
+ * colour would be a second one, so the shape wins and the tag is ignored.
+ *
+ * @param {object} parameters
+ * @param {ParticleLayout|undefined} layout
+ * @returns {ParticleValueType|null}
+ */
+function attribute_type(parameters, layout) {
+    if (layout === undefined || !layout.has(parameters.name)) {
+        return null;
+    }
+
+    const attribute = layout.get(parameters.name);
+
+    const semantic = particle_semantic_type(attribute.type);
+
+    if (semantic !== null && semantic.components === attribute.components) {
+        return semantic;
+    }
+
+    return particle_value_type(attribute.components);
+}
+
+/**
+ * Which of a binary op's operands is a scalar meeting a vector — read through `.xxxx` with no
+ * broadcast instruction — or `null` where neither or both are.
+ *
+ * @param {Object<string, ParticleValueType>} source_types
+ * @returns {string|null} `"a"`, `"b"` or `null`
+ */
+function scalar_operand(source_types) {
+    const a = source_types.a.is_scalar;
+    const b = source_types.b.is_scalar;
+
+    if (a === b) {
+        return null;
+    }
+
+    return a ? "a" : "b";
+}
+
+// --- sources ---
+// A source has a type of its own, and it is as wide as that: a literal is as wide as it was
+// written, a builtin as wide as the host fills it, an attribute as wide as the layout says. A
+// consumer wanting more lanes than that is a conversion the compiler makes after the value is
+// produced — except where a source can fill lanes for free, which it then does.
+source("const", parameters => particle_value_type_or_null(literal_of(parameters).length), emit_literal, {
+    operation_width: ({ type, demand }) => type.is_scalar ? demand : Math.min(type.components, demand),
+});
+source(
+    "builtin",
+    parameters => particle_value_type_or_null(VM_BUILTIN_COMPONENTS[parameters.id]),
+    (s, c) => s.loadBuiltin(c.out, c.parameters.id, c.width)
+);
+source("attribute", attribute_type, (s, c) => {
+    const a = c.layout.get(c.parameters.name);
+
+    s.loadAttr(c.out, a.offset, a.components, c.width);
+});
+// One uniform draw in `[0, 1)` per lane, as many lanes as the node says. Shaped distributions are
+// compositions over it rather than modes of it — see ./particle_graph_distributions.js.
+source("random", parameters => particle_value_type_or_null(parameters.components), (s, c) => s.random(c.out, c.width));
+
+// --- sinks ---
+// A store is exactly as wide as the attribute it writes, and that is how it reads its input.
+sink("setAttribute", ["value"], (s, c) => {
+    const a = c.layout.get(c.parameters.name);
+
+    s.storeAttr(c.in("value"), a.offset, a.components);
+}, {
+    infer_types: ({ parameters, layout }) => ({ output: null, inputs: { value: attribute_type(parameters, layout) } }),
+    operation_width: ({ parameters, layout }) => layout.get(parameters.name).components,
+});
+sink("kill", ["condition"], (s, c) => s.kill(c.in("condition")), {
+    infer_types: () => ({ output: null, inputs: { condition: PARTICLE_TYPE_F32 } }),
+    operation_width: () => 1,
+});
+
+// --- arithmetic (component-wise) ---
+binary("add", VM_OP.ADD);
+binary("sub", VM_OP.SUB);
+// A vector times a scalar reads the scalar through `.xxxx`, which is what keeps `velocity * dt` one
+// instruction rather than a broadcast and a multiply.
+define("mul", ["a", "b"], (s, c) => {
+    const scalar = scalar_operand(c.source_types);
+
+    if (scalar === null) {
+        s.emit(VM_OP.MUL, c.out, c.in("a"), c.in("b"), 0, c.width);
+    } else {
+        s.emit(VM_OP.MUL, c.out, c.in(scalar === "a" ? "b" : "a"), vm_register(c.in(scalar), VM_SWIZZLE_BROADCAST), 0, c.width);
+    }
+}, {
+    input_widths: ({ source_types }) => {
+        const scalar = scalar_operand(source_types);
+
+        return scalar === null ? {} : { [scalar]: 1 };
+    },
+});
+binary("div", VM_OP.DIV);
+binary("min", VM_OP.MIN);
+binary("max", VM_OP.MAX);
+binary("pow", VM_OP.POW);
+binary("step", VM_OP.STEP, MASK_RESULT);
+define("mad", ["a", "b", "c"], (s, c) => s.emit(VM_OP.MAD, c.out, c.in("a"), c.in("b"), c.in("c"), c.width));
+define("mix", ["a", "b", "t"], (s, c) => s.emit(VM_OP.MIX, c.out, c.in("a"), c.in("b"), c.in("t"), c.width), blend_controlled_by("t"));
+define("clamp", ["x", "lo", "hi"], (s, c) => s.emit(VM_OP.CLAMP, c.out, c.in("x"), c.in("lo"), c.in("hi"), c.width));
+define("smoothstep", ["e0", "e1", "x"], (s, c) => s.emit(VM_OP.SMOOTHSTEP, c.out, c.in("e0"), c.in("e1"), c.in("x"), c.width), MASK_RESULT);
+// The scalar is one lane; the vector is however wide the result is.
+define("scale", ["v", "s"], (s, c) => s.emit(VM_OP.MUL, c.out, c.in("v"), vm_register(c.in("s"), VM_SWIZZLE_BROADCAST), 0, c.width), {
+    infer_types: ({ inputs }) => ({ output: inputs.v, inputs: { v: inputs.v, s: PARTICLE_TYPE_F32 } }),
+    input_widths: () => ({ s: 1 }),
+});
+
+// --- unary math ---
+unary("neg", VM_OP.NEG);
+unary("abs", VM_OP.ABS);
+unary("floor", VM_OP.FLOOR);
+unary("fract", VM_OP.FRACT);
+unary("sqrt", VM_OP.SQRT);
+unary("sin", VM_OP.SIN);
+unary("cos", VM_OP.COS);
+unary("exp", VM_OP.EXP);
+unary("log", VM_OP.LOG);
+unary("normalize", VM_OP.NORMALIZE, WHOLE_VECTOR);
+unary("length", VM_OP.LENGTH, REDUCTION);
+
+// --- vector ---
+binary("dot", VM_OP.DOT, REDUCTION);
+// A cross product is three lanes in and three out, whatever arrives.
+binary("cross", VM_OP.CROSS, {
+    infer_types: ({ inputs }) => ({ output: PARTICLE_TYPE_VEC3, inputs: read_all_as(inputs, PARTICLE_TYPE_VEC3) }),
+    operation_width: () => 3,
+});
+binary("distance", VM_OP.DISTANCE, REDUCTION);
+// A swizzle is as wide as its pattern, and its source has to cover the lanes the pattern names —
+// which is unrelated to how wide the result is, and is the one place a source's extent is read out
+// of a parameter rather than a width.
+define("swizzle", ["x"], (s, c) => {
+    const p = pattern_of(c.parameters);
+
+    s.emit(VM_OP.MOV, c.out, vm_register(c.in("x"), pack_swizzle(p[0] ?? 0, p[1] ?? 0, p[2] ?? 0, p[3] ?? 0)), 0, 0, c.width);
+}, {
+    infer_types: ({ inputs, parameters }) => {
+        const p = pattern_of(parameters);
+        const output = particle_value_type_or_null(p.length);
+
+        if (output === null) {
+            return { output: null, inputs: { x: null } };
+        }
+
+        const span = pattern_span(p);
+        const source = inputs.x;
+
+        // A source that covers the lanes named is read as itself: picking `.x` out of a vec4 is not
+        // a narrowing. One that does not is read as wide as the pattern reaches, and the lanes it
+        // has not got read zero — a warning, since `.z` of a vec2 is more likely a slip than a plan.
+        const x = source !== null && source.components >= span ? source : particle_value_type_or_null(span);
+
+        return { output, inputs: { x } };
+    },
+    input_widths: ({ operation_width, parameters }) => ({
+        x: pattern_span(pattern_of(parameters).slice(0, operation_width)),
+    }),
+});
+
+// The vector constructors: a value per lane, from scalars. Lowered as one `MOV` per lane into the
+// result's run, which is the only way a lane gets written on its own — every other opcode writes a
+// run from its start.
+for (const components of [2, 3, 4]) {
+    const inputs = LANE_NAMES.slice(0, components);
+    const output = particle_value_type(components);
+
+    define(`vec${components}`, inputs, (s, c) => {
+        const moves = inputs.slice(0, c.width).map((port, lane) => ({ from: c.in(port), to: c.out + lane }));
+
+        // The allocator lets one source sit where the result starts, and nowhere else inside it. A
+        // move into lane 0 would overwrite that source before a later move could read it into its
+        // own lane — so it goes first, and the rest are then free to land in any order.
+        moves.sort((p, q) => Number(q.from === c.out) - Number(p.from === c.out));
+
+        for (const { from, to } of moves) {
+            if (from !== to) {
+                s.mov(to, from, 1);
+            }
+        }
+    }, {
+        infer_types: () => ({ output, inputs: read_all_as(Object.fromEntries(inputs.map(port => [port, null])), PARTICLE_TYPE_F32) }),
+        input_widths: () => Object.fromEntries(inputs.map(port => [port, 1])),
+    });
+}
+
+// --- logic ---
+define("compare", ["a", "b"], (s, c) => {
+    const opcode = PARTICLE_COMPARE_OPCODES[c.parameters.op];
+    if (opcode === undefined) {
+        throw new Error(`Unknown compare op '${c.parameters.op}'`);
+    }
+    s.emit(opcode, c.out, c.in("a"), c.in("b"), 0, c.width);
+}, MASK_RESULT);
+define("select", ["a", "b", "condition"], (s, c) => s.emit(VM_OP.SELECT, c.out, c.in("a"), c.in("b"), c.in("condition"), c.width), blend_controlled_by("condition"));
+
+// --- curves ---
+// One lane of `t` in, one value out — which the opcode writes across every lane it is asked for, so
+// a curve read wider than a scalar is the broadcast for free.
+define("curve", ["t"], (s, c) => s.curve(c.out, c.parameters.handle, c.in("t"), c.width), {
+    infer_types: () => ({ output: PARTICLE_TYPE_F32, inputs: { t: PARTICLE_TYPE_F32 } }),
+    operation_width: ({ demand }) => demand,
+    input_widths: () => ({ t: 1 }),
+});
+
+// --- semantic sources ---
+// Appended rather than filed with the other sources, because a node type's id is its position in
+// this file and the ids are a wire format: inserting one up there renumbers every type below it.
+// Where an author finds it is the palette's business, and the palette lists it among the sources.
+
+// A literal colour. A `const` of four numbers in every respect the compiler sees — it interns the
+// same pool words and loads them with the same instruction — and a colour to everything above:
+// a swatch to edit rather than four fields, and its own colour along the wire to wherever it is
+// written.
+source("color", () => PARTICLE_TYPE_COLOR, emit_literal);
+
+// --- more math ---
+// Appended for the same reason `color` is: these belong with the unary math above and cannot be
+// written there without renumbering every type that follows. The palette files them where they
+// read.
+
+unary("rsqrt", VM_OP.RSQRT);
+unary("tan", VM_OP.TAN);
+unary("asin", VM_OP.ASIN);
+unary("acos", VM_OP.ACOS);
+// The one binary among them, and the one whose ports are not interchangeable: `atan2(y, x)` is the
+// angle of the point, so the ports are named for the axes rather than `a` and `b`.
+define("atan2", ["y", "x"], (s, c) => s.emit(VM_OP.ATAN2, c.out, c.in("y"), c.in("x"), 0, c.width));
+
+// The `clamp` everybody writes, with the bounds written in rather than wired up. Both of them are
+// literals of one lane, so they are immediates in the instruction word: the node costs one
+// instruction and not one register, where a `clamp` between two `const` nodes costs three and as
+// many registers as it is wide. Nothing else in the library takes an immediate this way, because
+// nothing else in the library knows what its operands are before the graph is drawn.
+define("saturate", ["x"], (s, c) => s.emit(VM_OP.CLAMP, c.out, c.in("x"), vm_immediate(0), vm_immediate(1), c.width));
+
+// --- ramps ---
+// A curve and a gradient: authored data, lowered by being written out.
+//
+// These are the library's expanding types. They are made of other nodes, like a
+// {@link ./ParticleNodeGroup.js group} is, but the nodes they are made of come from their own
+// parameters rather than from a body fixed when the library loaded — a gradient with five stops is
+// different arithmetic from a gradient with two, and no one body could be both. So instead of an
+// `emit` they carry an {@link ./ParticleNodeDescription.js#expand}, which
+// {@link ./flatten_particle_graph.js} calls and splices in exactly as it splices a group. What each
+// one expands *to* is in {@link ./particle_ramp.js}, which is also where the reasoning about the
+// arithmetic lives; this is only the declaration.
+
+/**
+ * Declare a type whose body is built from its own parameters.
+ *
+ * @param {string} name
+ * @param {Array<{name: string, type: ParticleValueType|null}>} inputs
+ * @param {ParticleValueType} output what the node produces, and what the expansion's `out` is
+ * @param {function(ParticleGroupBuilder, object):*} body given a builder and the instance's
+ *        parameters, returns the value to expose as `out`
+ * @returns {ParticleNodeDescription}
+ */
+function expanding(name, inputs, output, body) {
+    const description = define(name, inputs.map(port => port.name), () => {
+        throw new Error(
+            `'${name}' reached the compiler. An expanding type is written out before lowering; `
+            + "see flatten_particle_graph.js."
+        );
+    }, {
+        infer_types: ({ inputs: wired }) => ({
+            output,
+            inputs: Object.fromEntries(inputs.map(port => [port.name, port.type ?? wired[port.name]])),
+        }),
+    });
+
+    description.expand = parameters => {
+        const g = new ParticleGroupBuilder({
+            name,
+            label: description.display_label,
+            icon: description.icon,
+            help: description.help,
+            inputs,
+            outputs: [{ name: PARTICLE_NODE_OUTPUT_PORT, type: output }],
+        });
+
+        g.out(PARTICLE_NODE_OUTPUT_PORT, body(g, parameters));
+
+        return g.build();
+    };
+
+    return description;
+}
+
+// One curve, written into the program. Not the `curve` node above: that one samples a row of the
+// host's animation-curve table and this one *is* the curve, the way `color` is a colour rather than
+// the name of one.
+expanding(
+    "curveLiteral",
+    [{ name: "t", type: PARTICLE_TYPE_F32 }],
+    PARTICLE_TYPE_F32,
+    (g, parameters) => roll_out_particle_curve(g, g.in.t, parameters.curve)
+);
+
+// The two gradients. One body, read three lanes wide or four — an RGB gradient still *stores* four
+// channels per stop, so that a gradient copied from one node to the other keeps the alpha it was
+// authored with rather than losing it on the way through.
+expanding(
+    "gradientRGBA",
+    [{ name: "t", type: PARTICLE_TYPE_F32 }],
+    PARTICLE_TYPE_COLOR,
+    (g, parameters) => roll_out_particle_gradient(g, g.in.t, parameters.stops, PARTICLE_GRADIENT_COLOR_COMPONENTS)
+);
+expanding(
+    "gradientRGB",
+    [{ name: "t", type: PARTICLE_TYPE_F32 }],
+    PARTICLE_TYPE_VEC3,
+    (g, parameters) => roll_out_particle_gradient(g, g.in.t, parameters.stops, PARTICLE_TYPE_VEC3.components)
+);
+
+/**
+ * Every node type in the library, in declaration order.
+ *
+ * The registry is keyed by the numeric ids assigned above, so this is the only way to walk the
+ * library by the names authoring uses — which is what a node palette lists.
+ *
+ * @returns {ParticleNodeDescription[]}
+ */
+export function particle_node_descriptions() {
+    return Array.from(descriptions_by_name.values());
+}
+
+/**
+ * Look up a node type by name.
+ * @param {string} name
+ * @returns {ParticleNodeDescription}
+ * @throws if no such node type exists
+ */
+export function get_particle_node_description(name) {
+    const description = descriptions_by_name.get(name);
+
+    if (description === undefined) {
+        throw new Error(`Unknown particle node type '${name}'`);
+    }
+
+    return description;
+}