@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/particles/isa/particle_assembly.js

@@ -0,0 +1,1214 @@
+import {
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_VM_INSTRUCTION_WORDS,
+    PARTICLE_VM_MAX_INSTRUCTIONS,
+    PARTICLE_VM_REGISTER_SLOTS,
+} from "../ParticleConstants.js";
+import { ParticleProgram } from "./ParticleProgram.js";
+import {
+    pack_swizzle,
+    swizzle_selector,
+    VM_BUILTIN,
+    VM_ISA,
+    VM_KIND,
+    VM_MAX_WIDTH,
+    VM_OP,
+    VM_OPERAND,
+    VM_SWIZZLE_BROADCAST,
+    VM_WIDTH,
+    vm_decode_dst,
+    vm_decode_kind,
+    vm_decode_op,
+    vm_decode_width,
+    vm_f32_bits,
+    vm_f32_value,
+    vm_operand_base,
+    vm_operand_pattern,
+    vm_operation_width,
+    vm_pack_instruction,
+    vm_register,
+    vm_visit_register_runs,
+} from "./ParticleVMISA.js";
+
+/**
+ * The textual form of a {@link ParticleProgram} — the particle VM's assembly language.
+ *
+ * A compiled effect is otherwise two opaque `Uint32Array`s. This module gives them a syntax that
+ * reads back exactly what {@link ./ParticleVMISA.js} defines, so a program can be looked at, edited
+ * by hand, diffed, and pasted between sessions. It is the level below the node graph: the graph
+ * compiler lowers to instructions, and this is what those instructions look like.
+ *
+ * Encode and decode live in one file on purpose. They are one language, and a divergence between
+ * them is the failure mode that matters — {@link ./particle_assembly.spec.js} pins the round trip in
+ * both directions.
+ *
+ * ## Syntax
+ *
+ * ```
+ * ; a comment, or // a comment
+ * .registers 6                  ; register file size in slots, optional (derived from use when absent)
+ * .const c0 0                   ; one word of the constant pool; indices must be dense from 0
+ * .const c1 2
+ *
+ * .init                         ; section — everything until the next section directive
+ *   LOAD_BUILTIN.3 r0, EMITTER_POSITION
+ *   RANDOM.2 r1
+ *   MUL.2 r1, r1, #0.5          ; a literal where a register could stand
+ *   STORE_ATTR r1, @1, 3        ; store r1 into the 3-component attribute at record word 1
+ *
+ * .update
+ *   LOAD_ATTR.1 r0, @7, 1
+ *   CMP_GE.1 r0, r0, r1
+ *   MOV.3 r2, r0.xxx            ; a register read through a swizzle: lane 0 three times
+ *   KILL r0
+ * ```
+ *
+ * The `.n` on a mnemonic is the lane count the instruction spans — `ADD.3` adds three lanes. It is
+ * written for every opcode that reads the width field, which is all of them bar the handful whose
+ * lane count is fixed (`HALT`, `NOP`, `KILL`, `CROSS`) and `STORE_ATTR`, whose width is by
+ * definition the component count it already spells as an operand. Left off, it falls back to the
+ * opcode's natural width, so text typed by hand need not carry one.
+ *
+ * Operand spelling follows the slot's role in {@link VM_ISA}, so every token is unambiguous where it
+ * stands:
+ *
+ * | role | spelling | example |
+ * |---|---|---|
+ * | destination | `r<slot>` | `r3` |
+ * | register source | `r<slot>`, optionally `.<selectors>` | `r3`, `r3.yyy`, `r0.zyx` |
+ * | literal source | `#<float>` | `#1.5` |
+ * | constant-pool word | `c<word>` | `c0` |
+ * | attribute word offset | `@<word>` | `@7` |
+ * | attribute component count | a bare integer `1..4` | `3` |
+ * | builtin | a {@link VM_BUILTIN} name | `EMITTER_POSITION` |
+ * | curve handle | `k<handle>` | `k2` |
+ *
+ * A register source's selectors say which lane of the value each lane of the instruction reads, one
+ * letter of `xyzw` per lane the instruction spans; left off, lane `c` reads lane `c`. A literal is
+ * the same value in every lane. The destination is only ever a plain register.
+ *
+ * ## What older text still means
+ *
+ * Two mnemonics that were opcodes are now spellings of an operand, and documents that carry them read
+ * as the instruction they meant: `SWIZZLE.n rd, rs, .xyzw` is `MOV.n rd, rs.xyzw`, and `SCALE.n rd,
+ * rv, rs` is `MUL.n rd, rv, rs.xxxx`. The disassembler never writes either.
+ */
+
+/** Section directive introducing the INIT stream. @type {string} */
+export const PARTICLE_ASSEMBLY_SECTION_INIT = ".init";
+
+/** Section directive introducing the UPDATE stream. @type {string} */
+export const PARTICLE_ASSEMBLY_SECTION_UPDATE = ".update";
+
+/** Directive pinning the register-file size. @type {string} */
+export const PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS = ".registers";
+
+/** Directive declaring one constant-pool entry. @type {string} */
+export const PARTICLE_ASSEMBLY_DIRECTIVE_CONST = ".const";
+
+/** Opens a literal in a register slot: `#1.5`. @type {string} */
+export const PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX = "#";
+
+/**
+ * Separates a mnemonic from the lane count it spans: `ADD.3`. Also separates a register from its
+ * selectors: `r3.yyy`. The same character opens a directive, but never in either of those positions.
+ *
+ * @type {string}
+ */
+export const PARTICLE_ASSEMBLY_WIDTH_SEPARATOR = ".";
+
+/**
+ * Largest constant-pool word index this will read.
+ *
+ * The pool is dense, so a declaration at index N implies a pool of N + 1 words — and this text is
+ * being typed into a live editor, where `c900000000` is one slipped keystroke away from `c9`. Without
+ * a bound the parser tries to allocate that pool and takes the page with it, which is a worse answer
+ * to a typo than a marker on the line.
+ *
+ * @type {number}
+ */
+export const PARTICLE_ASSEMBLY_MAX_CONSTANTS = 4096;
+
+/** Lane selector characters, indexed by the 2-bit selector value a swizzle packs. @type {string} */
+const SWIZZLE_LANES = "xyzw";
+
+/**
+ * Mnemonics that were opcodes and are now operand spellings, read for the documents that carry them.
+ * @type {Map<string, {op: number, form: string}>}
+ */
+const LEGACY_MNEMONICS = new Map([
+    ["SWIZZLE", { op: VM_OP.MOV, form: "swizzle" }],
+    ["SCALE", { op: VM_OP.MUL, form: "scale" }],
+]);
+
+/**
+ * Mnemonic -> opcode, derived from {@link VM_ISA} so the two cannot drift.
+ * @type {Map<string, number>}
+ */
+const OPCODE_BY_NAME = new Map();
+
+for (const [opcode, meta] of VM_ISA) {
+    OPCODE_BY_NAME.set(meta.name, opcode);
+}
+
+/**
+ * Invert a numeric enum for name lookup by value.
+ * @param {Object<string, number>} enumeration
+ * @returns {Map<number, string>}
+ */
+function invert(enumeration) {
+    const result = new Map();
+
+    for (const name of Object.keys(enumeration)) {
+        result.set(enumeration[name], name);
+    }
+
+    return result;
+}
+
+const BUILTIN_NAME_BY_ID = invert(VM_BUILTIN);
+
+/**
+ * One problem found while reading assembly text. Carries the source line so an editor can put a
+ * marker on it; `line` is 1-based, and 0 for a problem that belongs to the program as a whole
+ * rather than to any one line.
+ *
+ * @typedef {object} ParticleAssemblyDiagnostic
+ * @property {number} line 1-based source line, or 0
+ * @property {string} message
+ */
+
+// ---------------------------------------------------------------------------------------------
+// Disassembly
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Render a compiled program as assembly text.
+ *
+ * The output is exactly what {@link parse_particle_assembly} reads back: a program disassembled and
+ * reassembled is the same program, word for word, including a register count larger than the
+ * instructions themselves imply.
+ *
+ * @param {ParticleProgram} program
+ * @param {object} [options]
+ * @param {string} [options.indent] leading whitespace for instruction lines
+ * @returns {string}
+ */
+export function disassemble_particle_program(program, { indent = "    " } = {}) {
+    const lines = [];
+
+    lines.push(`${PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS} ${program.register_count}`);
+
+    const constants = program.constants;
+
+    // The pool is a flat run of words that instructions index into at whatever width they read, so
+    // there are no "entries" to print — one word per line, named by its index, is the only rendering
+    // that survives a round trip whatever widths the program reads it at.
+    if (constants.length > 0) {
+        lines.push("");
+
+        for (let i = 0; i < constants.length; i++) {
+            lines.push(`${PARTICLE_ASSEMBLY_DIRECTIVE_CONST} c${i} ${format_float(constants[i])}`);
+        }
+    }
+
+    for (const section of [
+        { directive: PARTICLE_ASSEMBLY_SECTION_INIT, words: program.init },
+        { directive: PARTICLE_ASSEMBLY_SECTION_UPDATE, words: program.update },
+    ]) {
+        lines.push("");
+        lines.push(section.directive);
+
+        const instruction_count = section.words.length / PARTICLE_VM_INSTRUCTION_WORDS;
+
+        for (let i = 0; i < instruction_count; i++) {
+            lines.push(indent + disassemble_instruction(section.words, i * PARTICLE_VM_INSTRUCTION_WORDS));
+        }
+    }
+
+    return lines.join("\n") + "\n";
+}
+
+/**
+ * Render one instruction.
+ * @param {Uint32Array} words
+ * @param {number} base word index of the instruction
+ * @returns {string}
+ */
+function disassemble_instruction(words, base) {
+    const word0 = words[base];
+    const op = vm_decode_op(word0);
+    const width = vm_decode_width(word0);
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        // Not reachable from a validated program, but a disassembler that throws is useless for
+        // looking at the thing that went wrong.
+        return `; unknown opcode ${op} [${words[base + 1]}, ${words[base + 2]}, ${words[base + 3]}]`;
+    }
+
+    const operation_width = vm_operation_width(op, width);
+    const operands = [];
+
+    if (meta.dst) {
+        operands.push(`r${vm_decode_dst(word0)}`);
+    }
+
+    for (let slot = 0; slot < 3; slot++) {
+        const role = meta.operands[slot];
+
+        if (role === VM_OPERAND.NONE) {
+            continue;
+        }
+
+        const word = words[base + 1 + slot];
+
+        if (role !== VM_OPERAND.REG) {
+            operands.push(format_operand(role, word));
+        } else if (vm_decode_kind(word0, slot) === VM_KIND.IMM) {
+            operands.push(`${PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX}${format_float(vm_f32_value(word))}`);
+        } else {
+            operands.push(format_register(word, meta.scalar_operands.includes(slot) ? 1 : operation_width));
+        }
+    }
+
+    const mnemonic = meta.name + format_width_suffix(op, meta, width);
+
+    return operands.length === 0 ? mnemonic : `${mnemonic} ${operands.join(", ")}`;
+}
+
+/**
+ * The `.n` a mnemonic wears to say how many lanes it spans.
+ *
+ * Only the opcodes that actually read the width field get one. `STORE_ATTR` is the exception among
+ * those: its width is defined to be its component count, which is already written as an operand, so
+ * a suffix there would be a second copy of one number and a chance to write them contradicting each
+ * other.
+ *
+ * @param {number} op
+ * @param {object} meta the opcode's {@link VM_ISA} entry
+ * @param {number} width
+ * @returns {string}
+ */
+function format_width_suffix(op, meta, width) {
+    if (meta.width !== VM_WIDTH.VARIABLE || op === VM_OP.STORE_ATTR) {
+        return "";
+    }
+
+    return `${PARTICLE_ASSEMBLY_WIDTH_SEPARATOR}${width}`;
+}
+
+/**
+ * A register source: its slot, and the selectors of the lanes read wherever they are not the lane
+ * itself.
+ *
+ * @param {number} word a register operand
+ * @param {number} lanes lanes the instruction reads of it
+ * @returns {string}
+ */
+function format_register(word, lanes) {
+    const pattern = vm_operand_pattern(word);
+
+    let identity = true;
+    let selectors = "";
+
+    for (let lane = 0; lane < lanes; lane++) {
+        const selector = swizzle_selector(pattern, lane);
+
+        identity = identity && selector === lane;
+        selectors += SWIZZLE_LANES.charAt(selector);
+    }
+
+    return `r${vm_operand_base(word)}${identity ? "" : PARTICLE_ASSEMBLY_WIDTH_SEPARATOR + selectors}`;
+}
+
+/**
+ * @param {string} role a {@link VM_OPERAND} value other than the register one
+ * @param {number} value
+ * @returns {string}
+ */
+function format_operand(role, value) {
+    switch (role) {
+        case VM_OPERAND.CONST:
+            return `c${value}`;
+        case VM_OPERAND.ATTR_OFFSET:
+            return `@${value}`;
+        case VM_OPERAND.COMP:
+            return String(value);
+        case VM_OPERAND.BUILTIN:
+            return BUILTIN_NAME_BY_ID.get(value) ?? String(value);
+        case VM_OPERAND.CURVE:
+            return `k${value}`;
+        default:
+            return String(value);
+    }
+}
+
+/**
+ * A float spelled so it reads back as itself.
+ *
+ * `Number.prototype.toString` round-trips an `f64` exactly, and these values came out of a
+ * `Float32Array`, so what it prints parses back to the same `f32`. It is often not pretty —
+ * `2.200000047683716` is what an author's `2.2` became on its way through the pool — but that is the
+ * number the program holds, and rounding it for the page would make the text a different program
+ * from the one it claims to be.
+ *
+ * @param {number} value
+ * @returns {string}
+ */
+function format_float(value) {
+    if (Number.isNaN(value)) {
+        return "nan";
+    }
+
+    if (value === Infinity) {
+        return "inf";
+    }
+
+    if (value === -Infinity) {
+        return "-inf";
+    }
+
+    if (Object.is(value, -0)) {
+        // String(-0) is "0", and a pool holding -0 is not element-wise equal to one holding +0
+        return "-0";
+    }
+
+    return String(value);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Read assembly text into a program, reporting every problem rather than stopping at the first.
+ *
+ * An editor wants all of them at once — one marker per bad line, not a single exception — so this
+ * is the form both the tool and {@link assemble_particle_program} are built on.
+ *
+ * `program` is `null` when anything was wrong. It is never a partially-formed program: a caller
+ * that gets one back can hand it straight to the runtime.
+ *
+ * @param {string} text
+ * @returns {{program: ParticleProgram|null, diagnostics: ParticleAssemblyDiagnostic[]}}
+ */
+export function parse_particle_assembly(text) {
+    /** @type {ParticleAssemblyDiagnostic[]} */
+    const diagnostics = [];
+
+    const report = (line, message) => diagnostics.push({ line, message });
+
+    /** @type {number[]} flat constant pool, one float per word */
+    const constants = [];
+    /** @type {Set<number>} constant indices a `.const` directive has already claimed */
+    const declared_constants = new Set();
+
+    /** @type {{words: number[], lines: number[]}} */
+    const sections = {
+        init: { words: [], lines: [] },
+        update: { words: [], lines: [] },
+    };
+
+    /** @type {{words: number[], lines: number[]}|null} */
+    let section = null;
+
+    /** @type {number} explicit `.registers`, or -1 when it should be derived from use */
+    let declared_register_count = -1;
+
+    /** end of the furthest-reaching register operand any instruction writes down */
+    let register_high_water = 0;
+
+    const source_lines = String(text).split(/\r\n|\r|\n/);
+
+    for (let i = 0; i < source_lines.length; i++) {
+        const line_number = i + 1;
+        const line = strip_comment(source_lines[i]).trim();
+
+        if (line === "") {
+            continue;
+        }
+
+        if (line.startsWith(".")) {
+            const directive = parse_directive(line, line_number, report);
+
+            if (directive === null) {
+                continue;
+            }
+
+            if (directive.kind === "section") {
+                section = sections[directive.section];
+            } else if (directive.kind === "registers") {
+                if (declared_register_count !== -1) {
+                    report(line_number, `Duplicate ${PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS} directive`);
+                }
+
+                declared_register_count = directive.count;
+            } else if (directive.kind === "const") {
+                if (directive.index >= PARTICLE_ASSEMBLY_MAX_CONSTANTS) {
+                    // checked before anything is sized off it — see PARTICLE_ASSEMBLY_MAX_CONSTANTS
+                    report(
+                        line_number,
+                        `Constant c${directive.index} is beyond the largest pool this reads `
+                        + `(${PARTICLE_ASSEMBLY_MAX_CONSTANTS} entries)`
+                    );
+                } else if (declared_constants.has(directive.index)) {
+                    report(line_number, `Constant c${directive.index} is declared more than once`);
+                } else {
+                    declared_constants.add(directive.index);
+
+                    // sparse declarations are caught below; the gaps read as zero until then
+                    while (constants.length < directive.index + 1) {
+                        constants.push(0);
+                    }
+
+                    constants[directive.index] = directive.value;
+                }
+            }
+
+            continue;
+        }
+
+        if (section === null) {
+            report(
+                line_number,
+                `Instruction outside a section — open one with ${PARTICLE_ASSEMBLY_SECTION_INIT} or ${PARTICLE_ASSEMBLY_SECTION_UPDATE}`
+            );
+            continue;
+        }
+
+        const instruction = parse_instruction(line, line_number, report);
+
+        if (instruction === null) {
+            continue;
+        }
+
+        if (instruction.register_reach > register_high_water) {
+            register_high_water = instruction.register_reach;
+        }
+
+        section.words.push(...instruction.words);
+        section.lines.push(line_number);
+    }
+
+    // dense constant indices: c0..cN-1 with nothing missing, so a pool index means the same thing
+    // here as it does in the heap
+    for (let i = 0; i < constants.length; i++) {
+        if (!declared_constants.has(i)) {
+            report(0, `Constant c${i} is referenced by the pool's length but never declared`);
+        }
+    }
+
+    const register_count = declared_register_count === -1 ? register_high_water : declared_register_count;
+
+    if (register_count > PARTICLE_VM_REGISTER_SLOTS) {
+        report(0, `A VM instruction can address ${PARTICLE_VM_REGISTER_SLOTS} slots, the program asks for ${register_count}`);
+    }
+
+    const constant_word_count = constants.length;
+
+    for (const [name, stream] of [["init", sections.init], ["update", sections.update]]) {
+        const instruction_count = stream.words.length / PARTICLE_VM_INSTRUCTION_WORDS;
+
+        if (instruction_count > PARTICLE_VM_MAX_INSTRUCTIONS) {
+            report(
+                0,
+                `${name} has ${instruction_count} instructions, the budget is ${PARTICLE_VM_MAX_INSTRUCTIONS}`
+            );
+        }
+
+        check_stream_references(stream, register_count, constant_word_count, report);
+    }
+
+    if (diagnostics.length > 0) {
+        return { program: null, diagnostics };
+    }
+
+    return {
+        program: new ParticleProgram({
+            init: new Uint32Array(sections.init.words),
+            update: new Uint32Array(sections.update.words),
+            constants: new Float32Array(constants),
+            register_count,
+        }),
+        diagnostics,
+    };
+}
+
+/**
+ * Read assembly text into a program, throwing on the first problem.
+ *
+ * The convenience form for tests and tooling that has no way to show a list of markers.
+ *
+ * @param {string} text
+ * @returns {ParticleProgram}
+ * @throws {Error} carrying every diagnostic, `.diagnostics` holding them individually
+ */
+export function assemble_particle_program(text) {
+    const { program, diagnostics } = parse_particle_assembly(text);
+
+    if (program === null) {
+        const error = new Error(
+            "Particle assembly failed:\n"
+            + diagnostics.map(d => (d.line > 0 ? `  line ${d.line}: ${d.message}` : `  ${d.message}`)).join("\n")
+        );
+
+        error.diagnostics = diagnostics;
+
+        throw error;
+    }
+
+    return program;
+}
+
+/**
+ * Cross-check every operand against the pool and register file the program declares. Done as a pass
+ * over the parsed stream rather than per line so a `.registers` directive below the code it governs
+ * still applies to it.
+ *
+ * @param {{words: number[], lines: number[]}} stream
+ * @param {number} register_count
+ * @param {number} constant_word_count
+ * @param {function(number, string):void} report
+ */
+function check_stream_references(stream, register_count, constant_word_count, report) {
+    const words = stream.words;
+    const instruction_count = words.length / PARTICLE_VM_INSTRUCTION_WORDS;
+
+    for (let i = 0; i < instruction_count; i++) {
+        const base = i * PARTICLE_VM_INSTRUCTION_WORDS;
+        const line = stream.lines[i];
+        const op = vm_decode_op(words[base]);
+        const meta = VM_ISA.get(op);
+
+        // An operand of width w occupies w consecutive slots, so it is the END of the run that has
+        // to be inside the file: `MOV.4 r30` starts inside a 32-slot file and finishes outside one.
+        vm_visit_register_runs(words, base, (index, span) => {
+            if (index + span <= register_count) {
+                return;
+            }
+
+            report(
+                line,
+                span === 1
+                    ? `r${index} is outside the ${register_count}-register file this program declares`
+                    : `r${index} spans ${span} slots [${index}, ${index + span}), past the end of the `
+                    + `${register_count}-register file this program declares`
+            );
+        });
+
+        if (op === VM_OP.LOAD_CONST) {
+            // The load reads one word per lane, so the whole run has to be inside the pool.
+            const first = words[base + 1];
+            const span = vm_operation_width(op, vm_decode_width(words[base]));
+
+            if (first + span > constant_word_count) {
+                report(
+                    line,
+                    `c${first} reads ${span} word${span === 1 ? "" : "s"}, past the end of the `
+                    + `${constant_word_count}-word constant pool`
+                );
+            }
+        }
+
+        // An attribute access past the end of a record is not caught by GPU robustness: the address
+        // still lands inside the pool buffer, and reads or corrupts the NEXT particle's record.
+        const offset_slot = meta.operands.indexOf(VM_OPERAND.ATTR_OFFSET);
+
+        if (offset_slot !== -1) {
+            const offset = words[base + 1 + offset_slot];
+            const components = words[base + 2 + offset_slot];
+
+            if (offset + components > PARTICLE_RECORD_WORD_COUNT) {
+                report(
+                    line,
+                    `attribute access [${offset}, ${offset + components}) runs past the ${PARTICLE_RECORD_WORD_COUNT}-word particle record`
+                );
+            }
+        }
+    }
+}
+
+/**
+ * @param {string} line
+ * @returns {string} the line with any trailing comment removed
+ */
+function strip_comment(line) {
+    const semicolon = line.indexOf(";");
+    const slashes = line.indexOf("//");
+
+    let cut = -1;
+
+    if (semicolon !== -1) {
+        cut = semicolon;
+    }
+
+    if (slashes !== -1 && (cut === -1 || slashes < cut)) {
+        cut = slashes;
+    }
+
+    return cut === -1 ? line : line.slice(0, cut);
+}
+
+/**
+ * @param {string} line already stripped of comments and trimmed, starting with `.`
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {{kind: string, [key: string]: *}|null}
+ */
+function parse_directive(line, line_number, report) {
+    const tokens = line.split(/[\s,]+/).filter(t => t !== "");
+    const head = tokens[0].toLowerCase();
+
+    if (head === PARTICLE_ASSEMBLY_SECTION_INIT || head === PARTICLE_ASSEMBLY_SECTION_UPDATE) {
+        if (tokens.length > 1) {
+            report(line_number, `${head} takes no arguments`);
+        }
+
+        return { kind: "section", section: head === PARTICLE_ASSEMBLY_SECTION_INIT ? "init" : "update" };
+    }
+
+    if (head === PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS) {
+        const count = parse_unsigned(tokens[1]);
+
+        if (count === null) {
+            report(line_number, `${PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS} needs a register count, got '${tokens[1] ?? ""}'`);
+            return null;
+        }
+
+        return { kind: "registers", count };
+    }
+
+    if (head === PARTICLE_ASSEMBLY_DIRECTIVE_CONST) {
+        const index = parse_prefixed(tokens[1], "c");
+
+        if (index === null) {
+            report(line_number, `${PARTICLE_ASSEMBLY_DIRECTIVE_CONST} needs a pool index like 'c0', got '${tokens[1] ?? ""}'`);
+            return null;
+        }
+
+        // One word per directive. The pool is indexed by word and read at whatever width the
+        // instruction asks for, so a "constant" has no width of its own to declare.
+        const token = tokens[2];
+
+        if (token === undefined) {
+            report(line_number, `${PARTICLE_ASSEMBLY_DIRECTIVE_CONST} needs a value`);
+            return null;
+        }
+
+        const value = parse_float(token);
+
+        if (value === null) {
+            report(line_number, `'${token}' is not a number`);
+            return null;
+        }
+
+        if (tokens.length > 3) {
+            report(line_number, `${PARTICLE_ASSEMBLY_DIRECTIVE_CONST} declares one word; give each its own index`);
+            return null;
+        }
+
+        return { kind: "const", index, value };
+    }
+
+    report(line_number, `Unknown directive '${tokens[0]}'`);
+
+    return null;
+}
+
+/**
+ * @typedef {object} ParsedOperand
+ * @property {number} kind a {@link VM_KIND}: `REG` or `IMM` for a register-role slot, `NONE` for any other
+ * @property {number} word the operand word
+ * @property {number} [selectors] for a register written with selectors, how many the text spelled
+ * @property {string} [token] the text the operand was read from, for messages
+ */
+
+/**
+ * @param {string} line already stripped of comments and trimmed
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {{words: number[], register_reach: number}|null} `register_reach` is one past the last
+ *          slot the instruction touches — what a register file has to hold for it
+ */
+function parse_instruction(line, line_number, report) {
+    const space = line.search(/\s/);
+    const head = (space === -1 ? line : line.slice(0, space)).toUpperCase();
+    const rest = space === -1 ? "" : line.slice(space);
+
+    // `ADD.3` — mnemonic, then the lane count it spans.
+    const separator = head.indexOf(PARTICLE_ASSEMBLY_WIDTH_SEPARATOR);
+    const mnemonic = separator === -1 ? head : head.slice(0, separator);
+    const width_text = separator === -1 ? "" : head.slice(separator + 1);
+
+    const legacy = LEGACY_MNEMONICS.get(mnemonic) ?? null;
+    const opcode = legacy === null ? OPCODE_BY_NAME.get(mnemonic) : legacy.op;
+
+    if (opcode === undefined) {
+        report(line_number, `Unknown instruction '${mnemonic}'`);
+        return null;
+    }
+
+    const meta = VM_ISA.get(opcode);
+
+    let width = meta.default_width;
+
+    if (width_text !== "") {
+        if (meta.width !== VM_WIDTH.VARIABLE) {
+            report(
+                line_number,
+                `${meta.name} has a fixed width of ${meta.default_width} and cannot be given one`
+            );
+            return null;
+        }
+
+        if (!/^[1-4]$/.test(width_text)) {
+            report(line_number, `'${width_text}' is not a width; widths run from 1 to ${VM_MAX_WIDTH}`);
+            return null;
+        }
+
+        width = Number(width_text);
+
+        if (width < meta.min_width) {
+            report(line_number, `${meta.name} width must be >= ${meta.min_width}, got ${width}`);
+            return null;
+        }
+    }
+
+    const tokens = rest.split(",").map(t => t.trim()).filter(t => t !== "");
+
+    const parsed = legacy === null
+        ? parse_operands(meta, tokens, line_number, report)
+        : parse_legacy_operands(legacy.form, mnemonic, tokens, line_number, report);
+
+    if (parsed === null) {
+        return null;
+    }
+
+    const { dst, sources } = parsed;
+
+    // The attribute ops measure themselves in components unless the text says otherwise: a load may
+    // be widened past its attribute (the lanes beyond read zero), a store may not — it writes one
+    // record word per lane, so its width IS the component count.
+    if (opcode === VM_OP.LOAD_ATTR && width_text === "") {
+        width = sources[1].word;
+    }
+
+    if (opcode === VM_OP.STORE_ATTR) {
+        if (width_text !== "" && width !== sources[2].word) {
+            report(line_number, `STORE_ATTR width ${width} must equal its component count ${sources[2].word}`);
+            return null;
+        }
+
+        width = sources[2].word;
+    }
+
+    // Selectors are written one per lane read, and the lane count is known only now that the width
+    // is: `r6.xx` on a three-lane read would otherwise quietly be `r6.xxz`.
+    const operation_width = vm_operation_width(opcode, width);
+
+    for (let slot = 0; slot < sources.length; slot++) {
+        const source = sources[slot];
+        const lanes = meta.scalar_operands.includes(slot) ? 1 : operation_width;
+
+        if (source.kind === VM_KIND.REG && source.selectors !== undefined && source.selectors > 0 && source.selectors !== lanes) {
+            report(
+                line_number,
+                `${meta.name} reads ${lanes} lane${lanes === 1 ? "" : "s"} of '${source.token}', `
+                + `which names ${source.selectors} selector${source.selectors === 1 ? "" : "s"}; write one per lane`
+            );
+            return null;
+        }
+    }
+
+    const words = vm_pack_instruction(
+        opcode,
+        width,
+        dst,
+        sources.map(source => source.kind),
+        sources.map(source => source.word)
+    );
+
+    // Registers are scalar slots, so what the file has to hold is where the widest operand ENDS.
+    // Sizing it by the largest index written down leaves a `RANDOM.3 r0` writing r1 and r2 outside
+    // the file it derived, which the interpreter reads back as zero and the reference as nothing.
+    let register_reach = 0;
+
+    vm_visit_register_runs(words, 0, (slot, span) => {
+        if (slot + span > register_reach) {
+            register_reach = slot + span;
+        }
+    });
+
+    return { words, register_reach };
+}
+
+/**
+ * The operands of an ordinary instruction, in the order they are written: the destination when the
+ * opcode has one, then every source whose role is not `NONE`.
+ *
+ * @param {object} meta the opcode's {@link VM_ISA} entry
+ * @param {string[]} tokens
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {{dst: number, sources: ParsedOperand[]}|null}
+ */
+function parse_operands(meta, tokens, line_number, report) {
+    /** roles the written operands fill, in order */
+    const roles = [];
+
+    if (meta.dst) {
+        roles.push("dst");
+    }
+
+    for (let slot = 0; slot < 3; slot++) {
+        if (meta.operands[slot] !== VM_OPERAND.NONE) {
+            roles.push(meta.operands[slot]);
+        }
+    }
+
+    if (tokens.length !== roles.length) {
+        report(
+            line_number,
+            `${meta.name} takes ${roles.length} operand${roles.length === 1 ? "" : "s"}` +
+            ` (${roles.join(", ")}), got ${tokens.length}`
+        );
+        return null;
+    }
+
+    let dst = 0;
+    const sources = [none(), none(), none()];
+    let slot_cursor = 0;
+
+    for (let i = 0; i < roles.length; i++) {
+        if (roles[i] === "dst") {
+            dst = parse_destination(tokens[i], line_number, report);
+
+            if (dst === null) {
+                return null;
+            }
+
+            continue;
+        }
+
+        // source slots are written in ISA order, skipping the ones marked NONE
+        while (meta.operands[slot_cursor] === VM_OPERAND.NONE) {
+            slot_cursor++;
+        }
+
+        const operand = roles[i] === VM_OPERAND.REG
+            ? parse_register_operand(tokens[i], line_number, report)
+            : parse_plain_operand(roles[i], tokens[i], line_number, report);
+
+        if (operand === null) {
+            return null;
+        }
+
+        sources[slot_cursor] = operand;
+        slot_cursor++;
+    }
+
+    return { dst, sources };
+}
+
+/**
+ * The operands of a legacy mnemonic, rewritten as the instruction it now spells.
+ *
+ * `SWIZZLE rd, rs, .xyzw` reads its pattern into `rs`'s swizzle; `SCALE rd, rv, rs` reads `rs`
+ * through `.xxxx`. A literal in either source position is what it is — one value in every lane —
+ * and the pattern or broadcast changes nothing about it.
+ *
+ * @param {string} form `"swizzle"` or `"scale"`
+ * @param {string} mnemonic as written, for messages
+ * @param {string[]} tokens
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {{dst: number, sources: ParsedOperand[]}|null}
+ */
+function parse_legacy_operands(form, mnemonic, tokens, line_number, report) {
+    if (tokens.length !== 3) {
+        report(line_number, `${mnemonic} takes 3 operands, got ${tokens.length}`);
+        return null;
+    }
+
+    const dst = parse_destination(tokens[0], line_number, report);
+
+    if (dst === null) {
+        return null;
+    }
+
+    if (form === "swizzle") {
+        const source = parse_register_operand(tokens[1], line_number, report);
+        const pattern = parse_swizzle_pattern(tokens[2]);
+
+        if (source === null) {
+            return null;
+        }
+
+        if (pattern === null) {
+            report(line_number, `Expected a swizzle like '.xyzw', got '${tokens[2]}'`);
+            return null;
+        }
+
+        return { dst, sources: [with_pattern(source, pattern), none(), none()] };
+    }
+
+    const vector = parse_register_operand(tokens[1], line_number, report);
+    const scalar = parse_register_operand(tokens[2], line_number, report);
+
+    if (vector === null || scalar === null) {
+        return null;
+    }
+
+    return { dst, sources: [vector, with_pattern(scalar, VM_SWIZZLE_BROADCAST), none()] };
+}
+
+/** @returns {ParsedOperand} the operand of an unused slot */
+function none() {
+    return { kind: VM_KIND.NONE, word: 0 };
+}
+
+/**
+ * @param {ParsedOperand} operand
+ * @param {number} pattern
+ * @returns {ParsedOperand} a register operand read through `pattern`; a literal, unchanged
+ */
+function with_pattern(operand, pattern) {
+    return operand.kind === VM_KIND.REG
+        ? { kind: VM_KIND.REG, word: vm_register(vm_operand_base(operand.word), pattern), token: operand.token }
+        : operand;
+}
+
+/**
+ * @param {string} token
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {number|null} the destination register
+ */
+function parse_destination(token, line_number, report) {
+    const index = parse_prefixed(token, "r");
+
+    if (index === null) {
+        report(line_number, `A destination is a register like 'r0', got '${token}'`);
+        return null;
+    }
+
+    return index;
+}
+
+/**
+ * An operand in a register slot: a register, optionally read through selectors, or a literal.
+ *
+ * @param {string} token
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {ParsedOperand|null}
+ */
+function parse_register_operand(token, line_number, report) {
+    const register = /^r(\d+)(?:\.([xyzw]{1,4}))?$/i.exec(token);
+
+    if (register !== null) {
+        const selectors = register[2] ?? "";
+        const lanes = [0, 1, 2, 3].map(lane => (lane < selectors.length
+            ? SWIZZLE_LANES.indexOf(selectors.charAt(lane).toLowerCase())
+            : lane));
+
+        return {
+            kind: VM_KIND.REG,
+            word: vm_register(Number.parseInt(register[1], 10), pack_swizzle(lanes[0], lanes[1], lanes[2], lanes[3])),
+            selectors: selectors.length,
+            token,
+        };
+    }
+
+    if (token.startsWith(PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX)) {
+        const value = parse_float(token.slice(PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX.length));
+
+        if (value === null) {
+            report(line_number, `Expected a literal like '${PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX}1.5', got '${token}'`);
+            return null;
+        }
+
+        // The word IS the f32: what a Float32Array would hold for this value, read back as bits.
+        return { kind: VM_KIND.IMM, word: vm_f32_bits(value) };
+    }
+
+    report(
+        line_number,
+        `Expected a register like 'r0' or 'r0.xxy', or a literal like `
+        + `'${PARTICLE_ASSEMBLY_IMMEDIATE_PREFIX}1.5', got '${token}'`
+    );
+
+    return null;
+}
+
+/**
+ * @param {string} role a role other than the register one
+ * @param {string} token
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {ParsedOperand|null}
+ */
+function parse_plain_operand(role, token, line_number, report) {
+    switch (role) {
+        case VM_OPERAND.CONST: {
+            const index = parse_prefixed(token, "c");
+
+            if (index === null) {
+                report(line_number, `Expected a constant like 'c0', got '${token}'`);
+                return null;
+            }
+
+            return { kind: VM_KIND.NONE, word: index };
+        }
+
+        case VM_OPERAND.ATTR_OFFSET: {
+            const offset = token.startsWith("@") ? parse_unsigned(token.slice(1)) : null;
+
+            if (offset === null) {
+                report(line_number, `Expected an attribute offset like '@1', got '${token}'`);
+                return null;
+            }
+
+            return { kind: VM_KIND.NONE, word: offset };
+        }
+
+        case VM_OPERAND.COMP: {
+            const components = parse_unsigned(token);
+
+            if (components === null || components < 1 || components > 4) {
+                report(line_number, `Component count must be 1, 2, 3 or 4, got '${token}'`);
+                return null;
+            }
+
+            return { kind: VM_KIND.NONE, word: components };
+        }
+
+        case VM_OPERAND.BUILTIN: {
+            const id = parse_enum_operand(token, VM_BUILTIN, "builtin", line_number, report);
+
+            return id === null ? null : { kind: VM_KIND.NONE, word: id };
+        }
+
+        case VM_OPERAND.CURVE: {
+            const handle = parse_prefixed(token, "k");
+
+            if (handle === null) {
+                report(line_number, `Expected a curve handle like 'k0', got '${token}'`);
+                return null;
+            }
+
+            return { kind: VM_KIND.NONE, word: handle };
+        }
+
+        default:
+            report(line_number, `Unsupported operand role '${role}'`);
+            return null;
+    }
+}
+
+/**
+ * Accept either the name of an enum member or its raw numeric value — the second so a program using
+ * an id this build has no name for still round-trips.
+ *
+ * @param {string} token
+ * @param {Object<string, number>} enumeration
+ * @param {string} label
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {number|null}
+ */
+function parse_enum_operand(token, enumeration, label, line_number, report) {
+    const upper = token.toUpperCase();
+
+    if (Object.hasOwn(enumeration, upper)) {
+        return enumeration[upper];
+    }
+
+    const numeric = parse_unsigned(token);
+
+    if (numeric !== null) {
+        return numeric;
+    }
+
+    report(line_number, `Unknown ${label} '${token}', expected one of ${Object.keys(enumeration).join(", ")}`);
+
+    return null;
+}
+
+/**
+ * A legacy `SWIZZLE` pattern: exactly four selectors behind a dot.
+ *
+ * @param {string} token
+ * @returns {number|null} the packed pattern
+ */
+function parse_swizzle_pattern(token) {
+    if (token.length !== 5 || !token.startsWith(".")) {
+        return null;
+    }
+
+    let packed = 0;
+
+    for (let lane = 0; lane < 4; lane++) {
+        const selector = SWIZZLE_LANES.indexOf(token.charAt(1 + lane).toLowerCase());
+
+        if (selector === -1) {
+            return null;
+        }
+
+        packed |= selector << (lane * 2);
+    }
+
+    return packed;
+}
+
+/**
+ * @param {string|undefined} token
+ * @param {string} prefix single character
+ * @returns {number|null}
+ */
+function parse_prefixed(token, prefix) {
+    if (token === undefined || token.length < 2 || token.charAt(0).toLowerCase() !== prefix) {
+        return null;
+    }
+
+    return parse_unsigned(token.slice(1));
+}
+
+/**
+ * @param {string|undefined} token
+ * @returns {number|null}
+ */
+function parse_unsigned(token) {
+    if (token === undefined || !/^\d+$/.test(token)) {
+        return null;
+    }
+
+    return Number.parseInt(token, 10);
+}
+
+/**
+ * @param {string} token
+ * @returns {number|null}
+ */
+function parse_float(token) {
+    const lower = token.toLowerCase();
+
+    if (lower === "nan") {
+        return Number.NaN;
+    }
+
+    if (lower === "inf" || lower === "+inf") {
+        return Infinity;
+    }
+
+    if (lower === "-inf") {
+        return -Infinity;
+    }
+
+    if (!/^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i.test(token)) {
+        return null;
+    }
+
+    return Number.parseFloat(token);
+}