@woosh/meep-engine 3.15.0 → 3.16.0

package/editor/particles/effect/ParticleEffectDocument.js

@@ -0,0 +1,989 @@
+import { NodeGraph } from "../../../src/core/model/node-graph/NodeGraph.js";
+import { NodeGraphVisualData } from "../../../src/core/model/node-graph/visual/NodeGraphVisualData.js";
+import Signal from "../../../src/core/events/signal/Signal.js";
+import {
+    EMITTER_BLEND,
+    EMITTER_PROJECTION,
+    make_emitter_flags,
+} from "../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
+import { compile_particle_effect } from "../../../src/shade/renderer/particles/graph/compile_particle_graph.js";
+import {
+    deserialize_particle_graph,
+    serialize_particle_graph,
+} from "../../../src/shade/renderer/particles/graph/particle_graph_json.js";
+import {
+    deserialize_particle_group,
+    serialize_particle_group,
+} from "../../../src/shade/renderer/particles/graph/particle_group_json.js";
+import {
+    particle_library_description_or_undefined,
+} from "../../../src/shade/renderer/particles/graph/particle_node_library.js";
+import {
+    PARTICLE_GRAPH_ERROR,
+    PARTICLE_GRAPH_PHASE,
+    validate_particle_graph,
+} from "../../../src/shade/renderer/particles/graph/validate_particle_graph.js";
+import {
+    disassemble_particle_program,
+    parse_particle_assembly,
+} from "../../../src/shade/renderer/particles/isa/particle_assembly.js";
+import { PARTICLE_TYPE_COLOR } from "../../../src/shade/renderer/particles/graph/ParticleValueType.js";
+import { ParticleLayout } from "../../../src/shade/renderer/particles/layout/ParticleLayout.js";
+import { optimize_compiled_particle_program } from "../../../src/shade/renderer/particles/optimizer/optimize_particle_program.js";
+import { EMITTER_RENDER_CHANNELS } from "../../../src/shade/renderer/particles/runtime/ParticleEmitter.js";
+
+/**
+ * One particle effect being edited: the thing both layers of the editor point at.
+ *
+ * An effect is four things — the per-particle attribute schema, an INIT graph, an UPDATE graph, and
+ * the emitter settings that say how the result is drawn. The graph editor edits the middle two, the
+ * code editor edits what they compile to, the emitter inspector edits the last, and the preview
+ * watches all of it. Putting them in one object with one change signal is what lets those be four
+ * independent views rather than four copies of the same state.
+ *
+ * ## Which layer is in charge
+ *
+ * The two editing layers are not two views of one representation — the graph compiles to the
+ * program and nothing compiles back. So the document names which one the program comes from:
+ *
+ * - {@link PARTICLE_EFFECT_SOURCE.GRAPH}: the program is compiled from the graphs on every
+ *   {@link compile}. The assembly text is a lowering of them, shown but not read.
+ * - {@link PARTICLE_EFFECT_SOURCE.ASSEMBLY}: the program is assembled from {@link assembly}. The
+ *   graphs are still there and still editable, but they are not what runs.
+ *
+ * {@link lowerToAssembly} moves from the first to the second, seeding the text with what the graphs
+ * compile to. Going back is {@link source} set to GRAPH: the text is kept, so an author who
+ * switches by accident has not lost their edits, but it stops being what runs.
+ *
+ * ## Optimizing
+ *
+ * {@link optimize} runs the compiled program through
+ * {@link ../../../src/shade/renderer/particles/optimizer/optimize_particle_program.js the optimizer}
+ * before anybody gets it. It is a property of the effect rather than of a view because it changes
+ * what runs — the preview, the reference simulation and anything else downstream of {@link compile}
+ * all get the optimized program — and a switch that changed what runs while living in one panel
+ * would be invisible from the other three.
+ *
+ * It applies whichever layer is authoritative, including hand-written assembly, which is a program
+ * like any other. What it never does is rewrite {@link assembly}: the author's text stays the text
+ * they typed, and only the program underneath it changes. See {@link assemblyText}.
+ */
+
+/**
+ * Which representation {@link ParticleEffectDocument#compile} builds the program from.
+ * @enum {string}
+ */
+export const PARTICLE_EFFECT_SOURCE = Object.freeze({
+    GRAPH: "graph",
+    ASSEMBLY: "assembly",
+});
+
+/**
+ * A compile attempt's outcome.
+ *
+ * @typedef {object} ParticleEffectCompilation
+ * @property {import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null} program
+ *   null when anything went wrong
+ * @property {ParticleLayout|null} layout the attribute schema the program was compiled against;
+ *   null when the declarations themselves are not a valid layout
+ * @property {import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null} unoptimized
+ *   what `program` was built from, before the optimizer. The same object as `program` when
+ *   {@link ParticleEffectDocument#optimize} is off, so a caller wanting the comparison can always
+ *   ask for it and gets "no difference" rather than a special case.
+ * @property {Array<{scope: string, node: number, line: number, message: string, severity: string}>} diagnostics
+ *   `scope` is `"init"`, `"update"`, `"assembly"` or `"effect"`; `node` is a node id or -1;
+ *   `line` is a 1-based assembly line or 0
+ */
+
+export class ParticleEffectDocument {
+
+    /**
+     * @type {string}
+     */
+    name = "effect";
+
+    /**
+     * The per-particle attribute declarations, in the order they are packed into a record.
+     *
+     * `type` is optional and says what the words are for rather than how many there are — see
+     * {@link ../../../src/shade/renderer/particles/layout/ParticleLayout.js ParticleLayout}. It is
+     * why reading `color` gives a colour in the graph and reading `position` gives a `vec3`.
+     *
+     * @type {Array<{name: string, components: number, type?: string}>}
+     */
+    attributes = [
+        { name: "position", components: 3 },
+        { name: "velocity", components: 3 },
+        { name: "age", components: 1 },
+        { name: "lifetime", components: 1 },
+        { name: "size", components: 1 },
+        { name: "color", components: 4, type: PARTICLE_TYPE_COLOR.name },
+    ];
+
+    /**
+     * The node groups this document carries of its own — the ones an author made in it.
+     *
+     * A group the library ships is code, is shared by every effect, and is looked up by name. One of
+     * these is a thing in this file: it travels with the effect, it is nobody else's, and it is
+     * always the author's to edit. Two documents may each have a `group.1` and they are different
+     * groups, which is why a document resolves its own names first — see {@link groupNamed}.
+     *
+     * @type {import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup[]}
+     */
+    groups = [];
+
+    /**
+     * @type {NodeGraph}
+     */
+    init = new NodeGraph();
+
+    /**
+     * @type {NodeGraph}
+     */
+    update = new NodeGraph();
+
+    /**
+     * Node positions for the INIT graph. Part of the document, not of the view: an effect whose
+     * arrangement is not saved with it has to be re-arranged every time it is opened.
+     * @type {NodeGraphVisualData}
+     */
+    init_visual = new NodeGraphVisualData();
+
+    /**
+     * @type {NodeGraphVisualData}
+     */
+    update_visual = new NodeGraphVisualData();
+
+    /**
+     * The emitter settings — everything about the effect that is not the simulation itself. Shaped
+     * to be handed straight to {@link ParticleEmitter.from}.
+     * @type {object}
+     */
+    emitter = {
+        spawn_rate: 120,
+        blend: EMITTER_BLEND.ADDITIVE,
+        projection: EMITTER_PROJECTION.BILLBOARD,
+        lighting: false,
+        soft_depth: false,
+        sort: false,
+        cull: false,
+        bounds_center: [0, 1, 0],
+        bounds_radius: 3,
+        atlas_region: [0, 0, 1, 1],
+        flipbook: [1, 1],
+        /** render channel -> attribute name; a channel absent here is not bound */
+        render: {
+            position: "position",
+            size: "size",
+            color: "color",
+        },
+    };
+
+    /**
+     * Which representation the program comes from.
+     * @type {string}
+     */
+    source = PARTICLE_EFFECT_SOURCE.GRAPH;
+
+    /**
+     * The code layer's text buffer. Under {@link PARTICLE_EFFECT_SOURCE.GRAPH} this is a lowering of
+     * the graphs, refreshed by {@link compile}; under ASSEMBLY it is the author's, and what runs.
+     * @type {string}
+     */
+    assembly = "";
+
+    /**
+     * Whether {@link compile} hands back the optimized program.
+     *
+     * Off by default, and off for every effect saved before it existed, because it is a thing an
+     * author turns on to see what it does rather than something done to their effect behind them.
+     *
+     * @type {boolean}
+     */
+    optimize = false;
+
+    /**
+     * Bumped on every {@link touch}. A view that caches something derived from the document can
+     * compare against this instead of recomputing on every frame.
+     * @type {number}
+     */
+    version = 0;
+
+    /**
+     * @readonly
+     */
+    on = {
+        /**
+         * Something about the effect changed. Carries the document.
+         * @readonly
+         * @type {Signal<ParticleEffectDocument>}
+         */
+        changed: new Signal(),
+    };
+
+    /**
+     * Nodes whose parameter signal this document is listening to.
+     * @type {Set<NodeInstance>}
+     */
+    #watched = new Set();
+
+    /**
+     * @type {function}
+     */
+    #on_node_parameter_changed = () => this.touch();
+
+    /**
+     * How many {@link batch} calls are open. Zero means a {@link touch} is announced immediately.
+     * @type {number}
+     */
+    #batch_depth = 0;
+
+    /**
+     * Whether a change happened while a batch was open, and is waiting to be announced.
+     * @type {boolean}
+     */
+    #batch_pending = false;
+
+    /**
+     * The last {@link compile}, against the key that produced it.
+     *
+     * A change to a document is seen by three panels and each of them asks what it compiles to, so
+     * without this one edit is three compiles. That was affordable when an effect was forty
+     * instructions; a graph with a `curl3` group in it lowers to about four thousand, which is 78ms
+     * to compile and another 570ms to optimize on this machine — three times over, on every
+     * keystroke.
+     *
+     * The key is the {@link version} and the two settings that decide what a compile does, rather
+     * than the version alone, because {@link lowerToAssembly} compiles under a temporarily changed
+     * {@link source} without touching — and a cache that could not tell those apart would hand it
+     * back the assembly it was about to replace.
+     *
+     * @type {{key: string, compilation: ParticleEffectCompilation}|null}
+     */
+    #compilation = null;
+
+    /**
+     * The last {@link #lowerGraphs}, against the version and layout it was made for.
+     *
+     * Separate from {@link #compilation} because the graph editor asks what is wrong with the graphs
+     * without asking what they compile to, and under ASSEMBLY authority those are different
+     * questions over the same work.
+     *
+     * @type {{version: number, layout: ParticleLayout, result: object}|null}
+     */
+    #lowering = null;
+
+    constructor() {
+        // A graph edited through the editor's action timeline never passes through this object, so
+        // without this the document would be the last to hear about a change to its own contents —
+        // and every view downstream of `on.changed` would be showing the effect as it was.
+        for (const graph of [this.init, this.update]) {
+            graph.on.nodeAdded.add(node => {
+                this.#watch(node);
+                this.touch();
+            });
+
+            graph.on.nodeRemoved.add(node => {
+                this.#unwatch(node);
+                this.touch();
+            });
+
+            graph.on.connectionAdded.add(this.touch, this);
+            graph.on.connectionRemoved.add(this.touch, this);
+        }
+    }
+
+    /**
+     * @param {NodeInstance} node
+     */
+    #watch(node) {
+        if (this.#watched.has(node)) {
+            return;
+        }
+
+        this.#watched.add(node);
+
+        node.on.parameterChanged.add(this.#on_node_parameter_changed);
+    }
+
+    /**
+     * @param {NodeInstance} node
+     */
+    #unwatch(node) {
+        if (!this.#watched.delete(node)) {
+            return;
+        }
+
+        node.on.parameterChanged.remove(this.#on_node_parameter_changed);
+    }
+
+    /**
+     * Announce a change. Every edit path — a graph action, an attribute added, a parameter set,
+     * assembly typed — ends here, and every view that shows the effect is downstream of it.
+     *
+     * Inside a {@link batch} the announcement is held until the batch ends, and however many changes
+     * it covered arrive as one.
+     */
+    touch() {
+        this.version++;
+
+        if (this.#batch_depth > 0) {
+            this.#batch_pending = true;
+            return;
+        }
+
+        this.on.changed.send1(this);
+    }
+
+    /**
+     * Run a run of edits as one change.
+     *
+     * Loading a document is a hundred and fifty node and connection additions, and every one of them
+     * is a change to the document. Without this the preview would recompile the effect once per
+     * node, and every control in the editor would rebuild as many times.
+     *
+     * Nests, and announces even if the body throws — a half-applied edit is still an edit, and a
+     * view left showing the state before it would be showing something that is not there.
+     *
+     * @template T
+     * @param {function():T} body
+     * @returns {T}
+     */
+    batch(body) {
+        this.#batch_depth++;
+
+        try {
+            return body();
+        } finally {
+            this.#batch_depth--;
+
+            if (this.#batch_depth === 0 && this.#batch_pending) {
+                this.#batch_pending = false;
+
+                this.on.changed.send1(this);
+            }
+        }
+    }
+
+    /**
+     * A node type this document carries of its own, by name; `undefined` for anything else.
+     *
+     * What every path that resolves a type name consults before the standard library, so that a
+     * group made here is found here — see {@link groups}.
+     *
+     * @param {string} name
+     * @returns {import("../../../src/shade/renderer/particles/graph/ParticleNodeDescription.js").ParticleNodeDescription|undefined}
+     */
+    ownDescription(name) {
+        return this.groupNamed(name)?.description;
+    }
+
+    /**
+     * @param {string} name
+     * @returns {import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup|undefined}
+     */
+    groupNamed(name) {
+        return this.groups.find(group => group.name === name);
+    }
+
+    /**
+     * A name no type answers to yet, here or in the standard library.
+     *
+     * Groups an author makes are numbered rather than asked about, because a dialog between wanting
+     * a group and having one is a dialog in the way. The name is an address and stays put; what an
+     * author renames is the label, which is what they read.
+     *
+     * @param {string} [prefix]
+     * @returns {string}
+     */
+    unusedGroupName(prefix = "group") {
+        for (let index = 1; ; index++) {
+            const candidate = `${prefix}.${index}`;
+
+            const taken = this.groupNamed(candidate) !== undefined
+                || particle_library_description_or_undefined(candidate) !== undefined;
+
+            if (!taken) {
+                return candidate;
+            }
+        }
+    }
+
+    /**
+     * Take on a group.
+     *
+     * @param {import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup} group
+     * @returns {void}
+     * @throws if something already answers to that name
+     */
+    addGroup(group) {
+        if (this.ownDescription(group.name) !== undefined) {
+            throw new Error(`This effect already has a group called '${group.name}'.`);
+        }
+
+        this.groups = this.groups.concat([group]);
+
+        this.touch();
+    }
+
+    /**
+     * Give up a group.
+     *
+     * Nodes still using it are left alone and become unresolvable, which is loud and recoverable;
+     * quietly rewriting somebody's graph to remove them would be neither. Callers that remove a group
+     * are expected to have removed its uses first, and the undo of a grouping does exactly that.
+     *
+     * @param {import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup} group
+     * @returns {boolean} false when the document did not have it
+     */
+    removeGroup(group) {
+        const remaining = this.groups.filter(candidate => candidate !== group);
+
+        if (remaining.length === this.groups.length) {
+            return false;
+        }
+
+        this.groups = remaining;
+
+        this.touch();
+
+        return true;
+    }
+
+    /**
+     * The attribute schema as the compiler and the runtime want it.
+     *
+     * Rebuilt on demand rather than held, because {@link attributes} is what an author edits and a
+     * cached layout would be one edit behind. Building one is a walk over a handful of declarations.
+     *
+     * @returns {ParticleLayout}
+     * @throws if the declarations are not a valid layout (duplicate name, too many words)
+     */
+    buildLayout() {
+        return new ParticleLayout(this.attributes);
+    }
+
+    /**
+     * Compile the effect as it stands.
+     *
+     * Never throws: everything that can go wrong comes back as a diagnostic, because every caller is
+     * a view that has to show the author what is wrong rather than fall over. Nor does it change the
+     * document — a compile that quietly rewrote the assembly buffer would be a change no view was
+     * told about.
+     *
+     * Memoized on {@link #compilation}, so the panels that all ask this on the same change pay for
+     * one. The result is shared rather than copied; nobody may write to it.
+     *
+     * @returns {ParticleEffectCompilation}
+     */
+    compile() {
+        const key = `${this.version}:${this.source}:${this.optimize}`;
+
+        if (this.#compilation !== null && this.#compilation.key === key) {
+            return this.#compilation.compilation;
+        }
+
+        const compilation = this.#compile();
+
+        this.#compilation = { key, compilation };
+
+        return compilation;
+    }
+
+    /**
+     * @returns {ParticleEffectCompilation}
+     */
+    #compile() {
+        /** @type {ParticleEffectCompilation['diagnostics']} */
+        const diagnostics = [];
+
+        let layout;
+
+        try {
+            layout = this.#layout();
+        } catch (e) {
+            return {
+                program: null,
+                unoptimized: null,
+                layout: null,
+                diagnostics: [{ scope: "effect", node: -1, line: 0, message: e.message, severity: PARTICLE_GRAPH_ERROR }],
+            };
+        }
+
+        if (this.source === PARTICLE_EFFECT_SOURCE.ASSEMBLY) {
+            const { program, diagnostics: assembly_diagnostics } = parse_particle_assembly(this.assembly);
+
+            for (const diagnostic of assembly_diagnostics) {
+                diagnostics.push({
+                    scope: "assembly",
+                    node: -1,
+                    line: diagnostic.line,
+                    message: diagnostic.message,
+                    severity: PARTICLE_GRAPH_ERROR,
+                });
+            }
+
+            return { ...this.#optimized(program, diagnostics), layout, diagnostics };
+        }
+
+        const lowering = this.#lowerGraphs(layout);
+
+        diagnostics.push(...lowering.diagnostics);
+
+        return { ...this.#optimized(lowering.program, diagnostics), layout, diagnostics };
+    }
+
+    /**
+     * Run a freshly built program through the optimizer, if the effect asks for it.
+     *
+     * Called with no options at all, which is the point: what the optimizer will and will not do to
+     * an author's arithmetic — `x * 0` folded to `+0`, multiply-add not fused — is argued for where
+     * those defaults live, and a tick-box in the editor is not the place to quietly widen it.
+     *
+     * The optimizer is held to leaving the same record, kill flag and RNG state as what it was
+     * given; if it ever throws anyway, that is a bug in it rather than in the effect, so the raw
+     * program keeps running and the author is told rather than left with a dead preview.
+     *
+     * @param {import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null} program
+     * @param {ParticleEffectCompilation['diagnostics']} diagnostics appended to
+     * @returns {{program: object|null, unoptimized: object|null}}
+     */
+    #optimized(program, diagnostics) {
+        if (program === null || !this.optimize) {
+            return { program, unoptimized: program };
+        }
+
+        try {
+            return { program: optimize_compiled_particle_program(program), unoptimized: program };
+        } catch (e) {
+            diagnostics.push({
+                scope: "effect",
+                node: -1,
+                line: 0,
+                message: `optimizer failed, running the unoptimized program: ${e.message}`,
+                severity: PARTICLE_GRAPH_ERROR,
+            });
+
+            return { program, unoptimized: program };
+        }
+    }
+
+    /**
+     * The layout, built once per {@link version}.
+     *
+     * Held rather than rebuilt only so that a compile and a diagnostics run in the same version
+     * share one — {@link #lowerGraphs} caches against the layout it was handed, and two equal
+     * layouts are not the same layout. {@link buildLayout} stays the fresh one.
+     *
+     * @returns {ParticleLayout}
+     * @throws as {@link buildLayout}
+     */
+    #layout() {
+        if (this.#lowering !== null && this.#lowering.version === this.version) {
+            return this.#lowering.layout;
+        }
+
+        const layout = this.buildLayout();
+
+        // parked with a null result: the next #lowerGraphs against this version fills it in, and one
+        // that never comes has cost nothing
+        this.#lowering = { version: this.version, layout, result: null };
+
+        return layout;
+    }
+
+    /**
+     * Check the graphs and, if they hold up, lower them.
+     *
+     * The one place the graphs are turned into a program, so that asking what is wrong with them and
+     * asking what they compile to do the same work rather than two subtly different amounts of it.
+     *
+     * Memoized against the version and the layout it was handed, for the same reason
+     * {@link compile} is: the graph panel asks what is wrong with the graphs on the same change the
+     * code panel and the preview ask what they compile to, and lowering a graph with a noise group
+     * in it is not cheap enough to do three times.
+     *
+     * @param {ParticleLayout} layout
+     * @returns {{program: import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null, diagnostics: ParticleEffectCompilation['diagnostics']}}
+     */
+    #lowerGraphs(layout) {
+        if (this.#lowering !== null
+            && this.#lowering.version === this.version
+            && this.#lowering.layout === layout
+            && this.#lowering.result !== null) {
+            return this.#lowering.result;
+        }
+
+        const result = this.#lowerGraphsUncached(layout);
+
+        this.#lowering = { version: this.version, layout, result };
+
+        return result;
+    }
+
+    /**
+     * @param {ParticleLayout} layout
+     * @returns {{program: import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null, diagnostics: ParticleEffectCompilation['diagnostics']}}
+     */
+    #lowerGraphsUncached(layout) {
+        const diagnostics = [];
+
+        for (const scope of Object.values(PARTICLE_GRAPH_PHASE)) {
+            // The validator is told which phase it is looking at: some of what is wrong with a
+            // graph depends on which of the two it is, and deciding that is its business rather
+            // than this document's.
+            for (const diagnostic of validate_particle_graph(this[scope], { layout, phase: scope })) {
+                diagnostics.push({
+                    scope,
+                    node: diagnostic.node,
+                    line: 0,
+                    message: diagnostic.message,
+                    severity: diagnostic.severity,
+                });
+            }
+        }
+
+        if (diagnostics.some(d => d.severity === PARTICLE_GRAPH_ERROR)) {
+            return { program: null, diagnostics };
+        }
+
+        try {
+            return {
+                program: compile_particle_effect({ init: this.init, update: this.update, layout }),
+                diagnostics,
+            };
+        } catch (e) {
+            // What the validator cannot see from the graph alone — running out of registers, most
+            // of all — surfaces here, against the effect rather than any one node.
+            diagnostics.push({
+                scope: "effect",
+                node: -1,
+                line: 0,
+                message: e.message,
+                severity: PARTICLE_GRAPH_ERROR,
+            });
+
+            return { program: null, diagnostics };
+        }
+    }
+
+    /**
+     * What is wrong with the two graphs, whichever layer is authoritative.
+     *
+     * The graph editor is about the graph. Which representation happens to be running decides what
+     * the preview shows, not whether a dangling input in front of the author is worth saying — so
+     * this is separate from {@link compile}, which reports on the thing that runs.
+     *
+     * @param {ParticleLayout} [layout] the schema to check attribute references against; built from
+     *   the document when not supplied, and skipped when it cannot be built
+     * @returns {ParticleEffectCompilation['diagnostics']}
+     */
+    graphDiagnostics(layout) {
+        let schema = layout;
+
+        if (schema === undefined) {
+            try {
+                schema = this.#layout();
+            } catch (e) {
+                return [{ scope: "effect", node: -1, line: 0, message: e.message, severity: PARTICLE_GRAPH_ERROR }];
+            }
+        }
+
+        // copied, because the array behind it is the cached lowering's and a caller sorting or
+        // filtering what it was handed would be editing what the next caller is told
+        return this.#lowerGraphs(schema).diagnostics.slice();
+    }
+
+    /**
+     * Hand the code layer the graphs' output and make it authoritative.
+     *
+     * A one-way door, and deliberately an explicit one: from here the graphs are no longer what
+     * runs, so nothing silently recompiles over the author's instructions.
+     *
+     * The text is seeded from the *unoptimized* lowering even with {@link optimize} on. The reason
+     * to come here is to write something the node library cannot say, and that is done by editing
+     * what the graph produced — which means reading it. Folded constants, shared subexpressions and
+     * a packed register file are the opposite of readable, and this door does not open the other
+     * way, so seeding from them would spend the author's only copy of the legible program. Nothing
+     * is lost by it: with the box ticked what they type is optimized on its way to the preview all
+     * the same.
+     *
+     * @returns {ParticleEffectCompilation} the compilation the text was seeded from; when it failed,
+     *   the source is left alone and the diagnostics say why
+     */
+    lowerToAssembly() {
+        const previous_source = this.source;
+
+        this.source = PARTICLE_EFFECT_SOURCE.GRAPH;
+
+        const compilation = this.compile();
+
+        if (compilation.program === null) {
+            this.source = previous_source;
+
+            return compilation;
+        }
+
+        this.assembly = disassemble_particle_program(compilation.unoptimized);
+        this.source = PARTICLE_EFFECT_SOURCE.ASSEMBLY;
+
+        this.touch();
+
+        return compilation;
+    }
+
+    /**
+     * What the code layer should show: the author's buffer under ASSEMBLY, and what the graphs
+     * lower to under GRAPH.
+     *
+     * Derived rather than cached, so it cannot be a compile behind the graphs. A graph that does not
+     * compile has no text to show, and says so where the instructions would be.
+     *
+     * Under GRAPH this is the program that runs, so with {@link optimize} on it is the optimized
+     * one — showing the author the lowering while the preview ran something else would make the
+     * panel a lie about the effect. Under ASSEMBLY it stays the author's text whether the box is
+     * ticked or not: it is a live buffer they are typing into, and the one thing worse than not
+     * seeing the optimized program is having your own text replaced by it mid-edit. What the
+     * optimizer made of it shows up in the counts instead.
+     *
+     * @param {ParticleEffectCompilation} [compilation] a compile already in hand, to save repeating one
+     * @returns {string}
+     */
+    assemblyText(compilation) {
+        if (this.source === PARTICLE_EFFECT_SOURCE.ASSEMBLY) {
+            return this.assembly;
+        }
+
+        const result = compilation ?? this.compile();
+
+        if (result.program === null) {
+            return "; the graph does not compile — see the problems below\n";
+        }
+
+        return disassemble_particle_program(result.program);
+    }
+
+    /**
+     * Go back to the graphs being what runs. The assembly text is kept — an author who switched by
+     * accident has not lost it — but it stops being read.
+     */
+    useGraphs() {
+        if (this.source === PARTICLE_EFFECT_SOURCE.GRAPH) {
+            return;
+        }
+
+        this.source = PARTICLE_EFFECT_SOURCE.GRAPH;
+
+        this.touch();
+    }
+
+    /**
+     * Turn the optimizer on or off. Announces, because it changes what runs.
+     *
+     * @param {boolean} enabled
+     */
+    setOptimize(enabled) {
+        if (this.optimize === enabled) {
+            return;
+        }
+
+        this.optimize = enabled;
+
+        this.touch();
+    }
+
+    /**
+     * Add an attribute to the per-particle record.
+     *
+     * @param {string} name
+     * @param {number} components 1..4
+     * @param {string} [type] what the words are for, see {@link attributes}; omitted, they are
+     *   whatever `components` of them means and nothing more
+     * @throws if the name is taken or the record has no room left
+     */
+    addAttribute(name, components, type = undefined) {
+        const candidate = this.attributes.concat([{ name, components, type }]);
+
+        // built rather than assumed: ParticleLayout is where the record's capacity and the
+        // duplicate-name rule live, and a layout that throws must not become the document's
+        new ParticleLayout(candidate);
+
+        this.attributes = candidate;
+
+        this.touch();
+    }
+
+    /**
+     * Remove an attribute, and unbind any render channel that pointed at it.
+     *
+     * Nodes naming it are left alone: they become invalid, which the validator reports against the
+     * node, and that is a better outcome than silently rewriting an author's graph.
+     *
+     * @param {string} name
+     * @returns {boolean} false when there was no such attribute
+     */
+    removeAttribute(name) {
+        const remaining = this.attributes.filter(attribute => attribute.name !== name);
+
+        if (remaining.length === this.attributes.length) {
+            return false;
+        }
+
+        this.attributes = remaining;
+
+        for (const channel of EMITTER_RENDER_CHANNELS) {
+            if (this.emitter.render[channel] === name) {
+                delete this.emitter.render[channel];
+            }
+        }
+
+        this.touch();
+
+        return true;
+    }
+
+    /**
+     * The emitter settings as {@link ParticleEmitter.from} takes them, with the compiled effect.
+     *
+     * Render channels naming an attribute the layout no longer has are dropped rather than passed
+     * on, because `bind_render` throws on one — and an effect that fails to build over a stale
+     * binding is a worse thing to hand an author than one that draws without a colour.
+     *
+     * @param {{layout: ParticleLayout, program: object}} effect what {@link compile} produced,
+     *   packaged the way `create_particle_effect` does
+     * @returns {object}
+     */
+    emitterConfig(effect) {
+        const render = {};
+
+        for (const channel of EMITTER_RENDER_CHANNELS) {
+            const attribute = this.emitter.render[channel];
+
+            if (attribute !== undefined && effect.layout.has(attribute)) {
+                render[channel] = attribute;
+            }
+        }
+
+        return {
+            effect,
+            name: this.name,
+            spawn_rate: this.emitter.spawn_rate,
+            flags: {
+                blend: this.emitter.blend,
+                projection: this.emitter.projection,
+                lighting: this.emitter.lighting,
+                soft_depth: this.emitter.soft_depth,
+                sort: this.emitter.sort,
+                cull: this.emitter.cull,
+            },
+            bounds: {
+                center: this.emitter.bounds_center,
+                radius: this.emitter.bounds_radius,
+            },
+            atlas_region: this.emitter.atlas_region,
+            flipbook: this.emitter.flipbook,
+            render,
+        };
+    }
+
+    /**
+     * The emitter's packed flags word, for anything that wants it without building an emitter.
+     * @returns {number}
+     */
+    emitterFlags() {
+        return make_emitter_flags({
+            blend: this.emitter.blend,
+            projection: this.emitter.projection,
+            lighting: this.emitter.lighting,
+            soft_depth: this.emitter.soft_depth,
+            sort: this.emitter.sort,
+            cull: this.emitter.cull,
+        });
+    }
+
+    /**
+     * @returns {object} the whole document, as JSON
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            attributes: this.attributes.map(attribute => ({ ...attribute })),
+            groups: this.groups.map(serialize_particle_group),
+            init: serialize_particle_graph({ graph: this.init, visual: this.init_visual }),
+            update: serialize_particle_graph({ graph: this.update, visual: this.update_visual }),
+            emitter: structuredClone(this.emitter),
+            source: this.source,
+            assembly: this.assembly,
+            optimize: this.optimize,
+        };
+    }
+
+    /**
+     * Replace this document's contents with what the JSON describes.
+     *
+     * @param {object} json
+     * @param {NodeDescriptionVisualRegistry} visualRegistry needed to place nodes whose saved
+     *        position is missing, and to size the ones that have one
+     * @returns {ParticleEffectDocument} this
+     */
+    fromJSON(json, visualRegistry) {
+        // A load is a hundred and fifty node and connection additions; downstream it is one change
+        return this.batch(() => this.#load(json, visualRegistry));
+    }
+
+    /**
+     * @param {object} json
+     * @param {NodeDescriptionVisualRegistry} visualRegistry
+     * @returns {ParticleEffectDocument} this
+     */
+    #load(json, visualRegistry) {
+        this.name = json.name ?? "effect";
+        this.attributes = (json.attributes ?? []).map(attribute => ({ ...attribute }));
+
+        // `NodeGraph.reset` drops its nodes without announcing them, so the watch list is cleared
+        // here rather than being left holding a graph that no longer exists
+        for (const node of Array.from(this.#watched)) {
+            this.#unwatch(node);
+        }
+
+        // The groups come first: the graphs are written against them by name, and a group's own body
+        // may use one written down before it.
+        this.groups = [];
+
+        const resolve = name => this.ownDescription(name);
+
+        for (const group_json of json.groups ?? []) {
+            this.groups.push(deserialize_particle_group({ json: group_json, visualRegistry, resolve }));
+        }
+
+        deserialize_particle_graph({
+            json: json.init ?? { nodes: [], connections: [] },
+            graph: this.init,
+            visual: this.init_visual,
+            visualRegistry,
+            resolve,
+        });
+
+        deserialize_particle_graph({
+            json: json.update ?? { nodes: [], connections: [] },
+            graph: this.update,
+            visual: this.update_visual,
+            visualRegistry,
+            resolve,
+        });
+
+        this.emitter = { ...this.emitter, ...structuredClone(json.emitter ?? {}) };
+        this.source = json.source === PARTICLE_EFFECT_SOURCE.ASSEMBLY
+            ? PARTICLE_EFFECT_SOURCE.ASSEMBLY
+            : PARTICLE_EFFECT_SOURCE.GRAPH;
+        this.assembly = json.assembly ?? "";
+
+        // absent reads as off, so an effect saved before the optimizer existed opens as the program
+        // its author last saw
+        this.optimize = json.optimize === true;
+
+        this.touch();
+
+        return this;
+    }
+}