@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -1,8 +1,19 @@
 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 { pack_swizzle, VM_BUILTIN_COMPONENTS, VM_OP } from "../isa/ParticleVMISA.js";
+import { particle_node_presentation } from "./particle_node_presentation.js";
 import { ParticleNodeDescription } from "./ParticleNodeDescription.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
@@ -11,14 +22,36 @@ import { ParticleNodeDescription } from "./ParticleNodeDescription.js";
  *
  * 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.
  */
 
 /**
- * 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.
+ * 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, "vec4");
+export const PARTICLE_VALUE_TYPE = DataType.from(0, "value");
 
 /**
  * Name of the single output port carried by every value-producing node.
@@ -31,6 +64,12 @@ export const PARTICLE_NODE_OUTPUT_PORT = "out";
  */
 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.
@@ -50,9 +89,19 @@ const descriptions_by_name = new Map();
  * @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 } = {}) {
+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}'`);
     }
@@ -62,6 +111,14 @@ function define(name, inputs, emit, { produces_value = true } = {}) {
     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);
     }
@@ -72,6 +129,22 @@ function define(name, inputs, emit, { produces_value = true } = {}) {
 
     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);
 
@@ -79,59 +152,337 @@ function define(name, inputs, emit, { produces_value = true } = {}) {
 }
 
 /** side-effecting sink (no output) */
-function sink(name, inputs, emit) {
-    return define(name, inputs, emit, { produces_value: false });
+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) {
-    return define(name, ["x"], (s, c) => s.emit(opcode, c.out, c.in("x")));
+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) {
-    return define(name, ["a", "b"], (s, c) => s.emit(opcode, c.out, c.in("a"), c.in("b")));
+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);
 }
 
-const COMPARE_OPCODES = {
+/**
+ * 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,
+};
+
+/**
+ * Comparison operators the single `compare` node type covers, and the opcode each lowers to.
+ *
+ * Exported so the authoring metadata in {@link ./particle_node_parameters.js} can offer exactly the
+ * set this lowers, rather than a hand-copied list that goes stale the moment one is added.
+ *
+ * @type {Object<string, number>}
+ */
+export const PARTICLE_COMPARE_OPCODES = Object.freeze({
     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,
-};
+});
+
+/**
+ * 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 — the case `SCALE` covers with no
+ * broadcast — 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 ---
-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));
+// 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),
 });
-define("builtin", [], (s, c) => s.loadBuiltin(c.out, c.parameters.id));
-define("attribute", [], (s, c) => {
+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);
+
+    s.loadAttr(c.out, a.offset, a.components, c.width);
 });
-define("random", [], (s, c) => s.random(c.out, c.parameters.mode));
+// 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,
 });
-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);
+// A vector times a scalar is what `SCALE` is for, and lowering to it here 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.SCALE, c.out, c.in(scalar === "a" ? "b" : "a"), c.in(scalar), 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);
-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")));
+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.SCALE, c.out, c.in("v"), c.in("s"), 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);
@@ -143,30 +494,115 @@ 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);
+unary("normalize", VM_OP.NORMALIZE, WHOLE_VECTOR);
+unary("length", VM_OP.LENGTH, REDUCTION);
 
 // --- vector ---
-binary("dot", VM_OP.DOT);
-binary("cross", VM_OP.CROSS);
-binary("distance", VM_OP.DISTANCE);
+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 = 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]));
+    const p = pattern_of(c.parameters);
+
+    s.emit(VM_OP.SWIZZLE, c.out, c.in("x"), pack_swizzle(p[0] ?? 0, p[1] ?? 0, p[2] ?? 0, p[3] ?? 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 = COMPARE_OPCODES[c.parameters.op];
+    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"));
-});
-define("select", ["a", "b", "condition"], (s, c) => s.emit(VM_OP.SELECT, c.out, c.in("a"), c.in("b"), c.in("condition")));
+    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 ---
-define("curve", ["t"], (s, c) => s.curve(c.out, c.parameters.handle, c.in("t")));
+// 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);
+
+/**
+ * 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.