@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,999 @@
+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 {
+    VM_BUILTIN,
+    VM_ISA,
+    VM_MAX_WIDTH,
+    VM_OP,
+    VM_OPERAND,
+    VM_WIDTH,
+    vm_decode_op,
+    vm_decode_width,
+    vm_encode_word0,
+    vm_operation_width,
+    vm_visit_register_operands,
+} 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
+ *   SCALE.2 r1, r1, r2
+ *   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
+ *   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 |
+ * |---|---|---|
+ * | register / destination | `r<slot>` | `r3` |
+ * | 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` |
+ * | swizzle pattern | `.<four of xyzw>` | `.xxyz` |
+ *
+ * `STORE_ATTR` and `KILL` carry a *source* register in the destination slot — the ISA's own
+ * encoding, spelled here the way it is encoded rather than reordered to read like a store.
+ */
+
+/** 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";
+
+/**
+ * Separates a mnemonic from the lane count it spans: `ADD.3`.
+ *
+ * The same character opens a directive and a swizzle pattern, but never in this position — a line
+ * starts with either a directive or a mnemonic, and a swizzle is an operand.
+ *
+ * @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.
+ *
+ * Generous against any real program: an effect's constants are its literals, and the whole
+ * instruction budget is {@link PARTICLE_VM_MAX_INSTRUCTIONS} per section.
+ *
+ * @type {number}
+ */
+export const PARTICLE_ASSEMBLY_MAX_CONSTANTS = 4096;
+
+/**
+ * Lane selector characters, indexed by the 2-bit selector value the `SWIZZLE` opcode packs.
+ * @type {string}
+ */
+const SWIZZLE_LANES = "xyzw";
+
+/**
+ * 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
+ */
+
+/**
+ * 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]}, ${words[base + 4]}]`;
+    }
+
+    const operands = [];
+
+    if (meta.dst) {
+        operands.push(`r${words[base + 1]}`);
+    }
+
+    for (let slot = 0; slot < 3; slot++) {
+        const role = meta.operands[slot];
+
+        if (role === VM_OPERAND.NONE) {
+            continue;
+        }
+
+        operands.push(format_operand(role, words[base + 2 + slot]));
+    }
+
+    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}`;
+}
+
+/**
+ * @param {string} role a {@link VM_OPERAND} value
+ * @param {number} value
+ * @returns {string}
+ */
+function format_operand(role, value) {
+    switch (role) {
+        case VM_OPERAND.REG:
+        case VM_OPERAND.DST:
+            return `r${value}`;
+        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}`;
+        case VM_OPERAND.SWIZZLE:
+            return format_swizzle(value);
+        default:
+            return String(value);
+    }
+}
+
+/**
+ * @param {number} packed four 2-bit lane selectors
+ * @returns {string} `.xyzw` form
+ */
+function format_swizzle(packed) {
+    let result = ".";
+
+    for (let lane = 0; lane < 4; lane++) {
+        result += SWIZZLE_LANES.charAt((packed >>> (lane * 2)) & 3);
+    }
+
+    return result;
+}
+
+/**
+ * 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);
+}
+
+/**
+ * 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, 4 floats per entry */
+    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 arena
+    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, `Register file is ${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 meta = VM_ISA.get(vm_decode_op(words[base]));
+
+        // 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_operands(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`
+            );
+        });
+
+        for (let slot = 0; slot < 3; slot++) {
+            const role = meta.operands[slot];
+            const value = words[base + 2 + slot];
+
+            if (role === VM_OPERAND.CONST) {
+                // The load reads one word per lane, so the whole run has to be inside the pool.
+                const span = vm_operation_width(vm_decode_op(words[base]), vm_decode_width(words[base]));
+
+                if (value + span > constant_word_count) {
+                    report(
+                        line,
+                        `c${value} 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.
+        if (meta.operands[0] === VM_OPERAND.ATTR_OFFSET) {
+            const offset = words[base + 2];
+            const components = words[base + 3];
+
+            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;
+}
+
+/**
+ * @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 opcode = OPCODE_BY_NAME.get(mnemonic);
+
+    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 !== "");
+
+    /** roles the operands fill, in the order they are written */
+    const roles = [];
+
+    if (meta.dst) {
+        roles.push(VM_OPERAND.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;
+    }
+
+    // Word 0 is filled in at the end, once the operands are known: the attribute ops take their
+    // width from their component count.
+    const words = [0, 0, 0, 0, 0];
+
+    let slot_cursor = 0;
+
+    for (let i = 0; i < roles.length; i++) {
+        const role = roles[i];
+        const value = parse_operand(role, tokens[i], line_number, report);
+
+        if (value === null) {
+            return null;
+        }
+
+        if (i === 0 && meta.dst) {
+            words[1] = value;
+        } else {
+            // source slots are written in ISA order, skipping the ones marked NONE
+            while (meta.operands[slot_cursor] === VM_OPERAND.NONE) {
+                slot_cursor++;
+            }
+
+            words[2 + slot_cursor] = value;
+            slot_cursor++;
+        }
+    }
+
+    // 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 = words[3];
+    }
+
+    if (opcode === VM_OP.STORE_ATTR) {
+        if (width_text !== "" && width !== words[3]) {
+            report(line_number, `STORE_ATTR width ${width} must equal its component count ${words[3]}`);
+            return null;
+        }
+
+        width = words[3];
+    }
+
+    words[0] = vm_encode_word0(opcode, width);
+
+    // 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_operands(words, 0, (slot, span) => {
+        if (slot + span > register_reach) {
+            register_reach = slot + span;
+        }
+    });
+
+    return { words, register_reach };
+}
+
+/**
+ * @param {string} role
+ * @param {string} token
+ * @param {number} line_number
+ * @param {function(number, string):void} report
+ * @returns {number|null}
+ */
+function parse_operand(role, token, line_number, report) {
+    switch (role) {
+        case VM_OPERAND.DST:
+        case VM_OPERAND.REG: {
+            const index = parse_prefixed(token, "r");
+
+            if (index === null) {
+                report(line_number, `Expected a register like 'r0', got '${token}'`);
+                return null;
+            }
+
+            return index;
+        }
+
+        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 index;
+        }
+
+        case VM_OPERAND.ATTR_OFFSET: {
+            if (!token.startsWith("@")) {
+                report(line_number, `Expected an attribute offset like '@1', got '${token}'`);
+                return null;
+            }
+
+            const offset = parse_unsigned(token.slice(1));
+
+            if (offset === null) {
+                report(line_number, `Expected an attribute offset like '@1', got '${token}'`);
+                return null;
+            }
+
+            return 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 components;
+        }
+
+        case VM_OPERAND.BUILTIN:
+            return parse_enum_operand(token, VM_BUILTIN, "builtin", line_number, report);
+
+        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 handle;
+        }
+
+        case VM_OPERAND.SWIZZLE: {
+            const packed = parse_swizzle(token);
+
+            if (packed === null) {
+                report(line_number, `Expected a swizzle like '.xyzw', got '${token}'`);
+                return null;
+            }
+
+            return packed;
+        }
+
+        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;
+}
+
+/**
+ * @param {string} token
+ * @returns {number|null} the packed 8-bit pattern
+ */
+function parse_swizzle(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);
+}