@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -9,16 +9,24 @@
  *
  * Every instruction is a fixed run of {@link PARTICLE_VM_INSTRUCTION_WORDS} `u32` words:
  *
- *     [ op, dst, s0, s1, s2 ]
+ *     [ op | width << 8, dst, s0, s1, s2 ]
  *
  * `dst` is the destination register for value-producing ops. `s0/s1/s2` are usually source register
  * indices, but some opcodes reinterpret them as immediates (constant-pool index, attribute word
- * offset + component count, curve handle, builtin id, random mode, swizzle pattern). The
+ * offset + component count, curve handle, builtin id, swizzle pattern). The
  * `operands` array below documents, per opcode, what each slot means.
  *
- * Registers are `vec4f`; scalars occupy `.x`. There is no control flow: conditionals are expressed
- * with CMP + SELECT and destruction with KILL, which keeps the interpreter a single flat `switch`
- * inside a bounded loop — friendly to both the WGSL emulator and real hardware.
+ * Registers hold single floats. An instruction's `width` says how many consecutive registers the
+ * operation spans, so a `vec3` value is three registers and `ADD` with width 3 adds three lanes.
+ * Widths are what stop every value costing four registers whether or not it has four components:
+ * the register file is the interpreter's dominant register cost, and roughly half the lane work in
+ * a real effect was padding before this existed. A few opcodes ignore the field because their lane
+ * count is fixed (see {@link VM_WIDTH}), and the reductions write a single lane whatever they read
+ * (see {@link VM_DEST}).
+ *
+ * There is no control flow: conditionals are expressed with CMP + SELECT and destruction with KILL,
+ * which keeps the interpreter a single flat `switch` inside a bounded loop — friendly to both the
+ * WGSL emulator and real hardware.
  */
 
 /**
@@ -28,7 +36,7 @@
 export const VM_OPERAND = {
     /** unused slot (must be 0) */
     NONE: "none",
-    /** register index in `[0, PARTICLE_VM_REGISTER_COUNT)` */
+    /** first register slot of an operand, in `[0, PARTICLE_VM_REGISTER_SLOTS)` */
     REG: "reg",
     /** destination register index */
     DST: "dst",
@@ -42,8 +50,6 @@ export const VM_OPERAND = {
     BUILTIN: "builtin",
     /** curve handle (row index into the animation-curve table) */
     CURVE: "curve",
-    /** random mode (see {@link VM_RANDOM_MODE}) */
-    RANDOM_MODE: "random_mode",
     /** packed swizzle pattern: four 2-bit lane selectors, lane i in bits `[2i, 2i+2)` */
     SWIZZLE: "swizzle",
 };
@@ -53,11 +59,11 @@ export const VM_OPERAND = {
  * @enum {number}
  */
 export const VM_BUILTIN = {
-    /** simulation time-step (seconds), broadcast to all lanes */
+    /** simulation time-step (seconds), in `.x` */
     DELTA_TIME: 0,
     /**
-     * Emitter age (seconds). NOT YET POPULATED — the host passes currently supply 0; per-emitter age
-     * tracking on the GPU is pending. Use {@link VM_BUILTIN.TIME} in effects until it lands.
+     * Emitter age (seconds): how long the emitter's table row has been running, as the emitter tick
+     * pass integrates it on the GPU (`data/PARTICLE_EMITTER_STATE.js`). Restarts with the row.
      */
     EMITTER_AGE: 1,
     /** emitter world position, `.xyz` */
@@ -75,19 +81,22 @@ export const VM_BUILTIN = {
 };
 
 /**
- * Random distribution modes for the `RANDOM` opcode.
- * @enum {number}
+ * How many lanes each builtin fills. The lanes past that read zero when a load is wider — see
+ * `vm_load_builtin` in {@link ../vm/chunk_particle_vm.js} — so this is a builtin's type as far as
+ * a program is concerned, and it is what types a `builtin` node in a graph.
+ *
+ * @type {Object<number, number>}
  */
-export const VM_RANDOM_MODE = {
-    /** four independent uniforms in `[0, 1)` */
-    UNIFORM: 0,
-    /** uniform in `[-1, 1)` per lane */
-    UNIFORM_SIGNED: 1,
-    /** a point on the unit sphere in `.xyz` (w = 0) */
-    UNIT_SPHERE: 2,
-    /** a point in the unit disk in `.xy` (z = w = 0) */
-    UNIT_DISK: 3,
-};
+export const VM_BUILTIN_COMPONENTS = Object.freeze({
+    [VM_BUILTIN.DELTA_TIME]: 1,
+    [VM_BUILTIN.EMITTER_AGE]: 1,
+    [VM_BUILTIN.EMITTER_POSITION]: 3,
+    [VM_BUILTIN.EMITTER_DIRECTION]: 3,
+    [VM_BUILTIN.EMITTER_UP]: 3,
+    [VM_BUILTIN.PARTICLE_INDEX]: 1,
+    [VM_BUILTIN.SPAWN_FRACTION]: 1,
+    [VM_BUILTIN.TIME]: 1,
+});
 
 /**
  * Opcodes. Numbers are stable wire values — never renumber, only append.
@@ -145,6 +154,130 @@ export const VM_OP = {
     CURVE: 61,
 };
 
+/**
+ * How an opcode reads the instruction's width field — the lane count it operates on.
+ * @enum {string}
+ */
+export const VM_WIDTH = {
+    /** operates on no lanes at all (`HALT`, `NOP`) */
+    NONE: "none",
+    /** the width field gives the lane count, `1..4` */
+    VARIABLE: "variable",
+    /** always one lane, whatever the field says (`KILL`) */
+    ONE: "one",
+    /** always three lanes (`CROSS`) */
+    THREE: "three",
+};
+
+/**
+ * How many lanes an opcode writes to its destination, relative to the operation's width.
+ * @enum {string}
+ */
+export const VM_DEST = {
+    /** writes nothing (`HALT`, `NOP`, `STORE_ATTR`, `KILL`) */
+    NONE: "none",
+    /** writes as many lanes as the operation is wide */
+    WIDTH: "width",
+    /** reduces to a single lane, whatever the operation's width (`DOT`, `LENGTH`, `DISTANCE`) */
+    ONE: "one",
+};
+
+/**
+ * Widest an operation may be. Registers hold scalars; four is what a `vec4` value needs and what
+ * the two-bit selectors in a `SWIZZLE` pattern can address.
+ * @type {number}
+ */
+export const VM_MAX_WIDTH = 4;
+
+/**
+ * Bit position of the width field inside an instruction's first word.
+ *
+ * The word holds `op | (width << VM_WIDTH_SHIFT)`. Widths ride in the opcode's spare high bits
+ * rather than a sixth instruction word: the code section is read through the same storage binding as
+ * the constants and is fetched every instruction, so a 20% longer stream is the one cost the
+ * interpreter pays on every single dispatch.
+ *
+ * @type {number}
+ */
+export const VM_WIDTH_SHIFT = 8;
+
+/** Mask selecting the opcode out of an instruction's first word. @type {number} */
+export const VM_OP_MASK = 0xff;
+
+/** Mask selecting the width out of an instruction's first word, once shifted down. @type {number} */
+export const VM_WIDTH_MASK = 0x7;
+
+/**
+ * Pack an opcode and its width into an instruction's first word.
+ * @param {number} op
+ * @param {number} width lane count, `0..4`
+ * @returns {number}
+ */
+export function vm_encode_word0(op, width) {
+    return ((op & VM_OP_MASK) | ((width & VM_WIDTH_MASK) << VM_WIDTH_SHIFT)) >>> 0;
+}
+
+/**
+ * @param {number} word0
+ * @returns {number} opcode
+ */
+export function vm_decode_op(word0) {
+    return word0 & VM_OP_MASK;
+}
+
+/**
+ * @param {number} word0
+ * @returns {number} lane count
+ */
+export function vm_decode_width(word0) {
+    return (word0 >> VM_WIDTH_SHIFT) & VM_WIDTH_MASK;
+}
+
+/**
+ * The lane count an opcode actually operates on, given the width its instruction carries.
+ *
+ * Opcodes whose width is fixed ignore the field entirely, so a malformed program cannot talk a
+ * `CROSS` into reading two lanes.
+ *
+ * @param {number} op
+ * @param {number} width the instruction's width field
+ * @returns {number}
+ */
+export function vm_operation_width(op, width) {
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        return 0;
+    }
+
+    switch (meta.width) {
+        case VM_WIDTH.NONE: return 0;
+        case VM_WIDTH.ONE: return 1;
+        case VM_WIDTH.THREE: return 3;
+        default: return width;
+    }
+}
+
+/**
+ * How many lanes an instruction writes to its destination register.
+ * @param {number} op
+ * @param {number} width the instruction's width field
+ * @returns {number}
+ */
+export function vm_dest_width(op, width) {
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        return 0;
+    }
+
+    switch (meta.dest) {
+        case VM_DEST.NONE: return 0;
+        case VM_DEST.ONE: return 1;
+        default: return vm_operation_width(op, width);
+    }
+}
+
 const D = VM_OPERAND.DST;
 const R = VM_OPERAND.REG;
 const _ = VM_OPERAND.NONE;
@@ -158,21 +291,61 @@ const _ = VM_OPERAND.NONE;
  */
 export const VM_ISA = new Map();
 
-function def(op, name, dst, s0 = _, s1 = _, s2 = _) {
+/**
+ * @param {number} op
+ * @param {string} name
+ * @param {boolean} dst
+ * @param {string} [s0]
+ * @param {string} [s1]
+ * @param {string} [s2]
+ * @param {object} [options]
+ * @param {string} [options.width] see {@link VM_WIDTH}; variable unless the opcode's lane count is fixed
+ * @param {string} [options.dest] see {@link VM_DEST}; as wide as the operation unless it reduces
+ * @param {number} [options.default_width] width the assembler uses when the text does not say
+ * @param {number} [options.min_width] narrowest the opcode is meaningful at
+ * @param {number[]} [options.scalar_operands] source slots read as a single lane whatever the width
+ */
+function def(op, name, dst, s0 = _, s1 = _, s2 = _, options = {}) {
     if (VM_ISA.has(op)) {
         throw new Error(`Duplicate opcode ${op} (${name})`);
     }
-    VM_ISA.set(op, { name, dst, operands: [s0, s1, s2] });
+
+    const width = options.width ?? VM_WIDTH.VARIABLE;
+    const dest = options.dest ?? (dst ? VM_DEST.WIDTH : VM_DEST.NONE);
+
+    let default_width = options.default_width ?? VM_MAX_WIDTH;
+
+    if (width === VM_WIDTH.NONE) {
+        default_width = 0;
+    } else if (width === VM_WIDTH.ONE) {
+        default_width = 1;
+    } else if (width === VM_WIDTH.THREE) {
+        default_width = 3;
+    }
+
+    VM_ISA.set(op, {
+        name,
+        dst,
+        operands: [s0, s1, s2],
+        width,
+        dest,
+        default_width,
+        min_width: options.min_width ?? 1,
+        scalar_operands: options.scalar_operands ?? [],
+    });
 }
 
-def(VM_OP.HALT, "HALT", false);
-def(VM_OP.NOP, "NOP", false);
+def(VM_OP.HALT, "HALT", false, _, _, _, { width: VM_WIDTH.NONE });
+def(VM_OP.NOP, "NOP", false, _, _, _, { width: VM_WIDTH.NONE });
 def(VM_OP.MOV, "MOV", true, R);
 def(VM_OP.LOAD_CONST, "LOAD_CONST", true, VM_OPERAND.CONST);
 def(VM_OP.LOAD_ATTR, "LOAD_ATTR", true, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP);
-def(VM_OP.STORE_ATTR, "STORE_ATTR", true, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP); // dst slot holds the SOURCE register
+// dst slot holds the SOURCE register; the width must equal the component count, since a store
+// cannot write lanes the register does not hold.
+def(VM_OP.STORE_ATTR, "STORE_ATTR", true, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP, _, { dest: VM_DEST.NONE });
 def(VM_OP.LOAD_BUILTIN, "LOAD_BUILTIN", true, VM_OPERAND.BUILTIN);
-def(VM_OP.KILL, "KILL", true); // dst slot holds the CONDITION register
+// dst slot holds the CONDITION register, read as a single lane
+def(VM_OP.KILL, "KILL", true, _, _, _, { width: VM_WIDTH.ONE, dest: VM_DEST.NONE });
 
 def(VM_OP.ADD, "ADD", true, R, R);
 def(VM_OP.SUB, "SUB", true, R, R);
@@ -183,7 +356,7 @@ def(VM_OP.MIN, "MIN", true, R, R);
 def(VM_OP.MAX, "MAX", true, R, R);
 def(VM_OP.MIX, "MIX", true, R, R, R);
 def(VM_OP.CLAMP, "CLAMP", true, R, R, R);
-def(VM_OP.SCALE, "SCALE", true, R, R);
+def(VM_OP.SCALE, "SCALE", true, R, R, _, { scalar_operands: [1] });
 
 def(VM_OP.NEG, "NEG", true, R);
 def(VM_OP.ABS, "ABS", true, R);
@@ -198,11 +371,16 @@ def(VM_OP.POW, "POW", true, R, R);
 def(VM_OP.STEP, "STEP", true, R, R);
 def(VM_OP.SMOOTHSTEP, "SMOOTHSTEP", true, R, R, R);
 
-def(VM_OP.DOT, "DOT", true, R, R);
-def(VM_OP.CROSS, "CROSS", true, R, R);
-def(VM_OP.LENGTH, "LENGTH", true, R);
-def(VM_OP.NORMALIZE, "NORMALIZE", true, R);
-def(VM_OP.DISTANCE, "DISTANCE", true, R, R);
+// The reductions read `width` lanes and write one. They used to read `.xyz` and broadcast the
+// result over all four lanes; the broadcast is now the compiler's to emit where a wider consumer
+// actually needs it, which is the whole point of tracking widths.
+def(VM_OP.DOT, "DOT", true, R, R, _, { dest: VM_DEST.ONE, default_width: 3 });
+// A cross product is three lanes wide. It may be asked for a fourth, which it writes as zero — the
+// `w` the opcode used to append — but never for fewer, so `MIN_WIDTH` is a floor rather than a fix.
+def(VM_OP.CROSS, "CROSS", true, R, R, _, { default_width: 3, min_width: 3 });
+def(VM_OP.LENGTH, "LENGTH", true, R, _, _, { dest: VM_DEST.ONE, default_width: 3 });
+def(VM_OP.NORMALIZE, "NORMALIZE", true, R, _, _, { default_width: 3 });
+def(VM_OP.DISTANCE, "DISTANCE", true, R, R, _, { dest: VM_DEST.ONE, default_width: 3 });
 def(VM_OP.SWIZZLE, "SWIZZLE", true, R, VM_OPERAND.SWIZZLE);
 
 def(VM_OP.CMP_LT, "CMP_LT", true, R, R);
@@ -212,8 +390,15 @@ def(VM_OP.CMP_GE, "CMP_GE", true, R, R);
 def(VM_OP.CMP_EQ, "CMP_EQ", true, R, R);
 def(VM_OP.SELECT, "SELECT", true, R, R, R);
 
-def(VM_OP.RANDOM, "RANDOM", true, VM_OPERAND.RANDOM_MODE);
-def(VM_OP.CURVE, "CURVE", true, VM_OPERAND.CURVE, R);
+// One independent uniform draw in `[0, 1)` per lane, and nothing else. `RANDOM` used to carry a
+// distribution mode — signed, unit sphere, unit disk — and every one of those is arithmetic over
+// this draw that a program can write for itself: with its constants hoisted, a unit sphere is ten
+// instructions and a unit disk seven. There is no principled place to stop adding distributions, so
+// the ISA does not start. Which means the draw count is now plainly `width`, rather than a per-mode
+// rule a reader has to look up.
+def(VM_OP.RANDOM, "RANDOM", true);
+// `t` is one lane; the sampled value fills the destination's width.
+def(VM_OP.CURVE, "CURVE", true, VM_OPERAND.CURVE, R, _, { scalar_operands: [1] });
 
 /**
  * @param {number} op
@@ -236,3 +421,77 @@ export function vm_op_name(op) {
 export function pack_swizzle(x, y, z, w) {
     return (x & 3) | ((y & 3) << 2) | ((z & 3) << 4) | ((w & 3) << 6);
 }
+
+/**
+ * How many registers a `SWIZZLE` pattern reaches into, counting from the source's base: one past
+ * the largest lane any of its four selectors names.
+ *
+ * A swizzle's source span has nothing to do with the instruction's width — a four-lane broadcast
+ * reads one register and a three-lane reversal reads four — so it is the only operand whose extent
+ * has to be read out of the pattern itself.
+ *
+ * @param {number} pattern
+ * @returns {number}
+ */
+export function swizzle_span(pattern) {
+    let span = 1;
+
+    for (let lane = 0; lane < 4; lane++) {
+        const selector = (pattern >> (2 * lane)) & 3;
+
+        if (selector + 1 > span) {
+            span = selector + 1;
+        }
+    }
+
+    return span;
+}
+
+/**
+ * Visit every register operand of an instruction as the slot it starts at and how many consecutive
+ * slots it reaches from there.
+ *
+ * Registers hold single floats, so an operand's base index says nothing on its own about how much
+ * of the file it touches: a `vec3` at r0 occupies r0, r1 and r2. Anyone sizing a register file or
+ * bounds-checking one needs the reach rather than the base, and the rules for it are not uniform —
+ * so they live here, in one place, instead of being re-derived by each caller until they disagree:
+ *
+ * - a destination reaches as far as the opcode writes, which for the reductions is one lane;
+ * - a source reaches as far as the operation runs, unless the ISA marks that slot scalar;
+ * - a `SWIZZLE` source reaches as far as its pattern names, which the width cannot tell you;
+ * - the source `STORE_ATTR` and `KILL` keep in the destination slot reaches as far as they read.
+ *
+ * @param {ArrayLike<number>} words an instruction stream
+ * @param {number} base index of the instruction's first word
+ * @param {function(number, number):void} visit called `(slot, span)` per register operand
+ */
+export function vm_visit_register_operands(words, base, visit) {
+    const word0 = words[base];
+    const op = vm_decode_op(word0);
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        return;
+    }
+
+    const width = vm_decode_width(word0);
+    const operation_width = vm_operation_width(op, width);
+
+    if (meta.dst) {
+        // For value-producing ops this is the destination; for STORE_ATTR and KILL it is a source
+        // living in the dst slot, and its span is what the instruction READS, not what it writes.
+        visit(words[base + 1], meta.dest === VM_DEST.NONE ? operation_width : vm_dest_width(op, width));
+    }
+
+    for (let slot = 0; slot < 3; slot++) {
+        if (meta.operands[slot] !== VM_OPERAND.REG) {
+            continue;
+        }
+
+        const span = op === VM_OP.SWIZZLE
+            ? swizzle_span(words[base + 3])
+            : (meta.scalar_operands.includes(slot) ? 1 : operation_width);
+
+        visit(words[base + 2 + slot], span);
+    }
+}

package/src/shade/renderer/particles/isa/particle_assembly.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 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: ParticleProgram, { indent }?: {
+    indent?: string;
+}): string;
+/**
+ * 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: string): {
+    program: ParticleProgram | null;
+    diagnostics: ParticleAssemblyDiagnostic[];
+};
+/**
+ * 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: string): ParticleProgram;
+/**
+ * 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: string;
+/** Section directive introducing the UPDATE stream. @type {string} */
+export const PARTICLE_ASSEMBLY_SECTION_UPDATE: string;
+/** Directive pinning the register-file size. @type {string} */
+export const PARTICLE_ASSEMBLY_DIRECTIVE_REGISTERS: string;
+/** Directive declaring one constant-pool entry. @type {string} */
+export const PARTICLE_ASSEMBLY_DIRECTIVE_CONST: string;
+/**
+ * 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: string;
+/**
+ * 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: number;
+/**
+ * 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.
+ */
+export type ParticleAssemblyDiagnostic = {
+    /**
+     * 1-based source line, or 0
+     */
+    line: number;
+    message: string;
+};
+import { ParticleProgram } from "./ParticleProgram.js";
+//# sourceMappingURL=particle_assembly.d.ts.map

package/src/shade/renderer/particles/isa/particle_assembly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_assembly.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/particle_assembly.js"],"names":[],"mappings":"AAkJA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,sDALW,eAAe;IAEE,MAAM,GAAvB,MAAM;IACJ,MAAM,CAmClB;AAwID;;;;;;;;;;;GAWG;AACH,8CAHW,MAAM;aACM,eAAe,GAAC,IAAI;iBAAe,0BAA0B,EAAE;EA8IrF;AAED;;;;;;;;GAQG;AACH,gDAJW,MAAM,GACJ,eAAe,CAkB3B;AA9eD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,oEAAoE;AACpE,6CAD0D,MAAM,CACV;AAEtD,sEAAsE;AACtE,+CAD4D,MAAM,CACR;AAE1D,+DAA+D;AAC/D,oDADqD,MAAM,CACO;AAElE,kEAAkE;AAClE,gDADwD,MAAM,CACJ;AAE1D;;;;;;;GAOG;AACH,gDAFU,MAAM,CAEqC;AAErD;;;;;;;;;;;;GAYG;AACH,8CAFU,MAAM,CAEoC;;;;;;;;;;UAyCtC,MAAM;aACN,MAAM;;gCAnJY,sBAAsB"}