@woosh/meep-engine 3.15.0 → 3.16.0

package/editor/view/particles/effect/ParticleGraphEditorView.js

@@ -0,0 +1,1636 @@
+import { Color } from "../../../../src/core/color/Color.js";
+import { PortDirection } from "../../../../src/core/model/node-graph/node/PortDirection.js";
+import { ActionProcessor } from "../../../../src/core/process/undo/ActionProcessor.js";
+import { infer_particle_graph_types } from "../../../../src/shade/renderer/particles/graph/infer_particle_graph_types.js";
+import { particle_group_from_nodes } from "../../../../src/shade/renderer/particles/graph/make_particle_group.js";
+import {
+    particle_group_descriptions,
+} from "../../../../src/shade/renderer/particles/graph/particle_group_json.js";
+import {
+    is_particle_group_description,
+} from "../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js";
+import {
+    particle_node_default_parameters,
+    particle_node_parameters,
+} from "../../../../src/shade/renderer/particles/graph/particle_node_parameters.js";
+import {
+    PARTICLE_NODE_REGISTRY,
+    PARTICLE_VALUE_TYPE,
+} from "../../../../src/shade/renderer/particles/graph/ParticleNodeRegistry.js";
+import {
+    particle_library_descriptions,
+} from "../../../../src/shade/renderer/particles/graph/particle_node_library.js";
+import {
+    PARTICLE_TYPE_COLOR,
+    PARTICLE_TYPE_F32,
+    PARTICLE_TYPE_VEC2,
+    PARTICLE_TYPE_VEC3,
+    PARTICLE_TYPE_VEC4,
+} from "../../../../src/shade/renderer/particles/graph/ParticleValueType.js";
+import KeyboardDevice from "../../../../src/engine/input/devices/KeyboardDevice.js";
+import { KeyCodes } from "../../../../src/engine/input/devices/KeyCodes.js";
+import LabelView from "../../../../src/view/common/LabelView.js";
+import EmptyView from "../../../../src/view/elements/EmptyView.js";
+import View from "../../../../src/view/View.js";
+import { NodeGraphCamera } from "../../node-graph/NodeGraphCamera.js";
+import { NodeGraphEditorView } from "../../node-graph/NodeGraphEditorView.js";
+import { NodeCreateAction } from "../../node-graph/actions/NodeCreateAction.js";
+import { NodeDeleteAction } from "../../node-graph/actions/NodeDeleteAction.js";
+import { ConnectionCreateAction } from "../../node-graph/actions/ConnectionCreateAction.js";
+import { NodesMoveAction } from "../../node-graph/actions/NodesMoveAction.js";
+import { SelectionSetAction } from "../../node-graph/actions/SelectionSetAction.js";
+import { ParticleGroupDefineAction } from "../../../particles/effect/actions/ParticleGroupDefineAction.js";
+import { ParticleNodeParametersView } from "./ParticleNodeParametersView.js";
+
+/**
+ * The graph layer of the particle editor: the two phases of an effect's simulation, authored as
+ * node graphs.
+ *
+ * Built *with* the node-graph editor rather than in it. Everything particle-specific arrives
+ * through the seams the base offers — the node library the canvas's add-node menu offers, a
+ * parameter-view factory that draws vector, enum, attribute and swizzle controls, and a problems
+ * list fed by the document's own compile. The base is left knowing nothing about particles.
+ *
+ * ## Adding a node
+ *
+ * On the canvas, where the node is going. Right-click and the library opens under the cursor with
+ * the caret in a search field; type a few letters and press Enter and the node lands at the point
+ * that was clicked. Drop a wire on open canvas and the same menu opens, narrowed to the types that
+ * have a port to take it, and picking one wires it up as it arrives.
+ *
+ * There is no palette down the side any more. It was a fine list and a bad way to add a node: every
+ * node cost a trip to the edge of the window and back, and the node arrived in the middle of the
+ * view rather than where it was wanted.
+ *
+ * ## Groups
+ *
+ * A {@link ../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js group} is a node made
+ * of nodes, and double-clicking one opens it: the canvas shows the group's own graph and the toolbar
+ * grows a breadcrumb back out. Groups nest, so the breadcrumb does. The groups shipped with the
+ * editor are locked — one body shared by every instance in every effect — and open read-only.
+ *
+ * ## Two phases, two graphs
+ *
+ * INIT runs once when a particle is spawned, UPDATE once per frame per live particle. They are
+ * separate graphs with separate cameras and separate selections, and switching between them is a
+ * matter of which one is visible — both stay built, so a phase comes back exactly where it was
+ * rather than reset to the origin.
+ *
+ * ## What is undoable
+ *
+ * Everything that touches a graph, through the {@link ActionProcessor} the host supplies. Adding a
+ * node from the menu, wiring, moving, deleting, and every parameter edit inside a node all land
+ * on one timeline, so a host editor's global undo covers particle authoring without knowing it
+ * exists.
+ */
+
+/** Height of the phase / action toolbar, px. @type {number} */
+const TOOLBAR_HEIGHT = 32;
+
+/** Height of the problems strip along the bottom, px. @type {number} */
+const PROBLEMS_HEIGHT = 96;
+
+/**
+ * One colour per type a value can have, and one for a port whose value is not known — nothing
+ * wired into it yet, or a parameter that does not describe a width.
+ *
+ * Every port in the library is declared with the one value type; which value it carries is
+ * resolved per node by `infer_particle_graph_types`, and that is what a port is coloured by and a
+ * wire drawn in. A wire meeting a port of another colour is a conversion, which is the point: a
+ * `vec4` literal feeding a `vec3` add shows as a pink wire into an amber port.
+ *
+ * Unresolved is registered rather than left to the default because the default exists for a type
+ * nobody has thought about, and this one has been.
+ *
+ * A colour is a `vec4` and gets a colour of its own anyway. Nothing is converted where the two
+ * meet — they are the same four lanes — so the change of hue along a wire is not a warning about
+ * anything; it is where a raw vector starts being used as a colour, or a colour stops being one,
+ * which is the thing a semantic type exists to make visible.
+ *
+ * @type {Map<number, Color>} data type id -> colour
+ */
+const PARTICLE_TYPE_COLORS = new Map([
+    [PARTICLE_VALUE_TYPE.id, new Color(0.58, 0.62, 0.68)],
+    [PARTICLE_TYPE_F32.id, new Color(0.55, 0.80, 1.0)],
+    [PARTICLE_TYPE_VEC2.id, new Color(0.55, 0.88, 0.50)],
+    [PARTICLE_TYPE_VEC3.id, new Color(1.0, 0.78, 0.35)],
+    [PARTICLE_TYPE_VEC4.id, new Color(0.95, 0.55, 0.80)],
+    [PARTICLE_TYPE_COLOR.id, new Color(0.72, 0.60, 0.98)],
+]);
+
+/**
+ * The categories the add-node menu groups the library into, in the order they are offered. A node
+ * type not named here falls into "other", so the library gaining a type never hides it.
+ *
+ * @type {Array<{name: string, types: string[]}>}
+ */
+const PALETTE_CATEGORIES = [
+    { name: "sources", types: ["const", "color", "builtin", "attribute", "random", "curve"] },
+    { name: "output", types: ["setAttribute", "kill"] },
+    { name: "arithmetic", types: ["add", "sub", "mul", "div", "mad", "scale", "min", "max", "pow", "step", "mix", "clamp", "smoothstep", "remap", "oneMinus"] },
+    { name: "math", types: ["neg", "abs", "floor", "fract", "round", "ceil", "sqrt", "sin", "cos", "exp", "log"] },
+    { name: "vector", types: ["vec2", "vec3", "vec4", "decompose2", "decompose3", "decompose4", "swizzle", "dot", "cross", "length", "normalize", "distance", "angleBetween2", "angleBetween3"] },
+    { name: "logic", types: ["compare", "select"] },
+    { name: "rotation", types: ["quatFromAxisAngle", "quatLookRotation", "quatRotate"] },
+    { name: "sampling", types: ["sampleSphereSurface", "sampleSphereVolume"] },
+    { name: "noise", types: ["simplex3", "simplex4", "curl3", "curl4"] },
+];
+
+/**
+ * Whether a port could take a value of a given type, for the menu that finishes a dropped wire.
+ *
+ * Every port in the library declares the one {@link PARTICLE_VALUE_TYPE} — including a group's, so
+ * that a wire may be dragged between any two ports and the graph model never refuses one on a type
+ * it does not decide. What a particle node reads is decided by what is wired into it, so for a stock
+ * type the answer is always yes, and what the menu is really filtering by is which side the wire came
+ * out of. That is the useful filter anyway: a wire out of an output cannot be finished by a `const`.
+ *
+ * A group *declares* what each of its ports is, separately from the port, and there the answer means
+ * something. A value goes in if the shapes match, if it is a scalar (which broadcasts), or if the
+ * port is wider (the missing lanes read zero). A port narrower than the value is left out: offering
+ * `cross` for a `vec4` would be offering to drop a lane. A group port declared with no type at all
+ * takes the shape of what arrives, and so takes anything.
+ *
+ * @param {Port} port
+ * @param {import("../../../../src/shade/renderer/particles/graph/ParticleValueType.js").ParticleValueType|null} dataType
+ * @param {import("../../../../src/shade/renderer/particles/graph/ParticleNodeDescription.js").ParticleNodeDescription} description
+ * @returns {boolean}
+ */
+function particle_port_accepts(port, dataType, description) {
+    if (dataType === null || dataType.isParticleValueType !== true) {
+        return true;
+    }
+
+    const declared = description.group?.portType(port.name, port.direction) ?? null;
+
+    if (declared === null) {
+        return true;
+    }
+
+    return dataType.is_scalar || declared.components >= dataType.components;
+}
+
+export class ParticleGraphEditorView extends View {
+    /**
+     * @type {Array<{id: string, label: string, editor: NodeGraphEditorView, toggle: View}>}
+     */
+    #phases = [];
+
+    /**
+     * @type {string}
+     */
+    #active = "init";
+
+    /**
+     * @type {EmptyView}
+     */
+    #problems;
+
+    /**
+     * @type {EmptyView}
+     */
+    #body;
+
+    /**
+     * @type {EmptyView}
+     */
+    #toolbar;
+
+    /**
+     * The breadcrumb back out of whatever groups are open, and empty while none is.
+     * @type {EmptyView}
+     */
+    #trail;
+
+    /**
+     * The two commands whose availability depends on what is selected. See {@link #refreshCommands}.
+     * @type {View}
+     */
+    #group_button;
+
+    /**
+     * @type {View}
+     */
+    #ungroup_button;
+
+    /**
+     * The groups currently open, outermost first, each with the canvas showing it. Empty means the
+     * phase graphs are what is on screen.
+     *
+     * @type {Array<{group: import("../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup, editor: NodeGraphEditorView}>}
+     */
+    #open_groups = [];
+
+    /**
+     * Phases whose camera has not yet been pointed at their contents. A graph that has just been
+     * arranged for the first time is somewhere in particular, and it is not the origin.
+     * Discharged by {@link #frameIfNeeded}.
+     * @type {Set<string>}
+     */
+    #needs_framing = new Set();
+
+    /**
+     * The last compile's diagnostics, kept so a node view that appears after them can still be
+     * marked. Nodes arrive from an undo as readily as from the menu.
+     * @type {Array<{scope: string, node: number, severity: string}>}
+     */
+    #diagnostics = [];
+
+    /**
+     * The resolved types of each phase's graph, by phase id, as of the last change to the effect.
+     * Filled on demand — see {@link #typesOf} — and emptied whenever the effect changes, since any
+     * edit may retype ports far from itself.
+     * @type {Map<string, import("../../../../src/shade/renderer/particles/graph/infer_particle_graph_types.js").ParticleGraphTypes>}
+     */
+    #types = new Map();
+
+    /**
+     * The resolved types of each open group's body, by group. See {@link #groupTypes}.
+     * @type {Map<import("../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup, import("../../../../src/shade/renderer/particles/graph/infer_particle_graph_types.js").ParticleGraphTypes>}
+     */
+    #group_types = new Map();
+
+    /**
+     * @param {object} options
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument} options.effect
+     * @param {ActionProcessor} [options.actionProcessor] shared with a host editor for a single undo
+     *        timeline across the whole application
+     */
+    constructor({ effect, actionProcessor = new ActionProcessor({}) }) {
+        super();
+
+        this.el = document.createElement('div');
+
+        this.addClass('ui-particle-graph-editor');
+
+        /**
+         * @type {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument}
+         */
+        this.effect = effect;
+
+        /**
+         * @type {ActionProcessor}
+         */
+        this.actionProcessor = actionProcessor;
+
+        this.#toolbar = new EmptyView({ classList: ['toolbar'] });
+        this.#body = new EmptyView({ classList: ['body'] });
+        this.#problems = new EmptyView({ classList: ['problems'] });
+
+        for (const phase of [{ id: "init", label: "INIT" }, { id: "update", label: "UPDATE" }]) {
+            this.#phases.push(this.#buildPhase(phase.id, phase.label));
+        }
+
+        this.addChild(this.#toolbar);
+        this.addChild(this.#body);
+        this.addChild(this.#problems);
+
+        this.#buildToolbar();
+
+        this.setPhase(this.#active);
+
+        this.#refreshCommands();
+
+        // Before anything else downstream of a change: a node cannot be drawn until every canvas
+        // knows how big its type is, and a group the author just made is a type nothing has seen.
+        this.bindSignal(effect.on.changed, this.#ensureGroupPrototypes, this);
+
+        this.#ensureGroupPrototypes();
+
+        this.bindSignal(effect.on.changed, this.refreshProblems, this);
+        this.on.linked.add(this.refreshProblems, this);
+
+        // a port's type follows the graph, so every change is a chance for every port to differ
+        this.bindSignal(effect.on.changed, this.#refreshTypes, this);
+
+        this.bindSignal(this.size.onChanged, this.layout, this);
+        this.on.linked.add(this.layout, this);
+
+        this.#bindShortcuts();
+    }
+
+    /**
+     * `Ctrl+G` groups the selection and `Ctrl+Shift+G` opens one back up.
+     *
+     * On this view rather than on a canvas, because it is this view that owns both commands and
+     * because a keystroke has to reach them whichever canvas happens to be on screen. The canvases
+     * do not stop key events, so one typed over a graph arrives here.
+     */
+    #bindShortcuts() {
+        this.el.setAttribute('tabindex', '-1');
+
+        const keyboard = new KeyboardDevice(this.el);
+
+        keyboard.on.down.add(event => {
+            if (!event.ctrlKey || event.keyCode !== KeyCodes.g) {
+                return;
+            }
+
+            const target = event.target;
+
+            if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+                // typing into a field — a node's parameter, the search box, a group's name
+                return;
+            }
+
+            event.preventDefault();
+            event.stopPropagation();
+
+            const done = event.shiftKey ? this.ungroupSelection() : this.groupSelection();
+
+            done.catch(e => console.error(event.shiftKey ? "could not ungroup" : "could not group", e));
+        });
+
+        this.on.linked.add(keyboard.start, keyboard);
+        this.on.unlinked.add(keyboard.stop, keyboard);
+    }
+
+    /**
+     * @param {string} id
+     * @param {string} label
+     * @returns {{id: string, label: string, editor: NodeGraphEditorView, toggle: View}}
+     */
+    #buildPhase(id, label) {
+        const effect = this.effect;
+
+        const visual = effect[`${id}_visual`];
+
+        for (const [type_id, color] of PARTICLE_TYPE_COLORS) {
+            visual.addDataColor(type_id, color);
+        }
+
+        // A graph nobody has placed yet — a new effect, or one loaded from a file with no positions
+        // — would otherwise open as a stack of nodes on top of each other at the origin. Checked
+        // before the editor is built, because building it gives every node visual data at 0,0 and
+        // there is then no way to tell "not placed" from "placed at the origin".
+        const unplaced = visual.nodes.size === 0 && effect[id].getNodes().length > 0;
+
+        const editor = this.#buildCanvas({
+            graph: effect[id],
+            visual,
+            types: () => this.#typesOf(id),
+        });
+
+        editor.addClass(`phase-${id}`);
+
+        if (unplaced) {
+            editor.layout();
+
+            // the camera cannot be pointed at the result yet, see #frameIfNeeded
+            this.#needs_framing.add(id);
+        }
+
+        this.bindSignal(editor.on.arranged, () => this.#frameIfNeeded());
+
+        this.#body.addChild(editor);
+
+        // A node's marker cannot be applied off the document's change signal: that fires before the
+        // graph view has built the node's view, because this view's bindings are linked before its
+        // children's. The graph view says when the view exists, which is the only moment that works
+        // — for a node the canvas menu just added and for one an undo brings back alike.
+        this.bindSignal(editor.graphView.on.nodeViewAdded, node => this.#markNode(id, node.id));
+
+        // Two phases, two maps, one opinion about whether a map is wanted. Folding one away and
+        // finding the other still open on the next phase switch would read as the fold not having
+        // worked. Setting a value it already holds announces nothing, so this settles rather than
+        // loops.
+        this.bindSignal(editor.minimap.collapsed.onChanged, collapsed => {
+            for (const phase of this.#phases) {
+                phase.editor.minimap.collapsed.set(collapsed);
+            }
+        });
+
+        const toggle = new EmptyView({ classList: ['phase-toggle'] });
+
+        toggle.addChild(new LabelView(label, { classList: ['label'] }));
+        toggle.el.addEventListener('click', () => this.setPhase(id));
+
+        this.#toolbar.addChild(toggle);
+
+        return { id, label, editor, toggle };
+    }
+
+    /**
+     * One canvas over one graph, with everything particle-specific wired into the base's seams.
+     *
+     * Shared between the two phase graphs and the body of every group that gets opened, because they
+     * differ in exactly two things — which graph, and whether it can be edited — and everything else
+     * about how a particle graph is drawn and added to should not be written twice.
+     *
+     * @param {object} options
+     * @param {NodeGraph} options.graph
+     * @param {NodeGraphVisualData} options.visual
+     * @param {function():import("../../../../src/shade/renderer/particles/graph/infer_particle_graph_types.js").ParticleGraphTypes} options.types
+     * @param {boolean} [options.readOnly]
+     * @returns {NodeGraphEditorView}
+     */
+    #buildCanvas({ graph, visual, types, readOnly = false }) {
+        const effect = this.effect;
+
+        for (const [type_id, color] of PARTICLE_TYPE_COLORS) {
+            visual.addDataColor(type_id, color);
+        }
+
+        const editor = new NodeGraphEditorView({
+            graph,
+            nodeRegistry: PARTICLE_NODE_REGISTRY,
+            visual,
+            camera: new NodeGraphCamera(),
+            actionProcessor: this.actionProcessor,
+            readOnly,
+            library: {
+                // The menu heads each *run* of one category, so the order it is handed decides the
+                // order it shows; sorting here keeps that decision on the particle side of the seam.
+                descriptions: () => [...particle_library_descriptions(), ...effect.groups.map(g => g.description)]
+                    .sort((a, b) => category_rank(a.name) - category_rank(b.name)),
+                categoryOf: description => category_of(description.name),
+                describe: description => description.help,
+                accepts: particle_port_accepts,
+                parametersOf: description => this.#defaultParameters(description),
+            },
+            parameterViewFactory: ({ node, commit }) => {
+                // A group's configuration is its wiring, and its boundary blocks are its edge:
+                // neither declares a parameter, and neither is in the schema to be asked about. A
+                // node with no parameters gets no container at all, rather than an empty one.
+                if (is_particle_group_description(node.description)) {
+                    return null;
+                }
+
+                if (particle_node_parameters(node.description.name).length === 0) {
+                    return null;
+                }
+
+                return new ParticleNodeParametersView({ effect, node, commit });
+            },
+            // What a port carries on this node: its output's type, or for an input the type the
+            // node reads it as — which is what an empty port is waiting for. Unknown falls back to
+            // the declared type, and its colour.
+            portDataType: endpoint => {
+                const resolved = types();
+
+                const type = endpoint.port.direction === PortDirection.Out
+                    ? resolved.output(endpoint.instance.id, endpoint.port.name)
+                    : resolved.input(endpoint.instance.id, endpoint.port.name);
+
+                return type ?? endpoint.port.dataType;
+            },
+        });
+
+        // Before anything is drawn on it: a canvas cannot build a node until its registry knows how
+        // big the type is, and the types this document made are in no shared registry.
+        this.#generateGroupPrototypes(editor);
+
+        // what the commands apply to is what is selected, and that is per canvas
+        for (const signal of [editor.selection.nodes.on.added, editor.selection.nodes.on.removed]) {
+            editor.bindSignal(signal, () => this.#refreshCommands());
+        }
+
+        // Double-click a group to open it. Bound on the canvas rather than on this view, so that
+        // closing a group takes its bindings with it — and bindings are linked before children, so
+        // this is in place before the graph view builds the first node.
+        editor.bindSignal(editor.graphView.on.nodeViewAdded, (node, nodeView) => {
+            if (node.description.isParticleGroupBoundaryDescription === true) {
+                nodeView.addClass('is-group-boundary');
+
+                return;
+            }
+
+            if (node.description.isParticleGroupNodeDescription !== true) {
+                return;
+            }
+
+            nodeView.addClass('is-group');
+
+            nodeView.el.addEventListener('dblclick', event => {
+                event.preventDefault();
+                event.stopPropagation();
+
+                this.openGroup(node.description.group);
+            });
+        });
+
+        return editor;
+    }
+
+    /**
+     * The parameters a node of this type should arrive with.
+     *
+     * @param {import("../../../../src/shade/renderer/particles/graph/ParticleNodeDescription.js").ParticleNodeDescription} description
+     * @returns {object}
+     */
+    #defaultParameters(description) {
+        if (is_particle_group_description(description)) {
+            return {};
+        }
+
+        return particle_node_default_parameters(description.name, { layout: this.#layoutOrNothing() });
+    }
+
+    /**
+     * Give every canvas a box for every node type this document carries of its own.
+     *
+     * A canvas generates the box it draws a node in from the registry it was built with, and throws
+     * when it cannot find one — which is the right behaviour, since the alternative is a node drawn
+     * at nothing by nothing. A group an author has just made is a type that registry has never seen,
+     * so it is told here, on every change, for every canvas.
+     *
+     * Cheap and idempotent: a registry generates a box from port and parameter counts and keys it by
+     * the description's id, so telling it twice about the same type costs an arithmetic pass.
+     */
+    #ensureGroupPrototypes() {
+        for (const canvas of [...this.#phases.map(phase => phase.editor), ...this.#open_groups.map(open => open.editor)]) {
+            this.#generateGroupPrototypes(canvas);
+        }
+    }
+
+    /**
+     * The same, for one canvas — which is what a canvas built after the fact needs, and there is no
+     * change to hang it off: a group's body is opened, not announced.
+     *
+     * @param {NodeGraphEditorView} canvas
+     */
+    #generateGroupPrototypes(canvas) {
+        for (const group of this.effect.groups) {
+            for (const description of particle_group_descriptions(group)) {
+                canvas.visualRegistry.generate(description);
+            }
+        }
+    }
+
+    #buildToolbar() {
+        this.#trail = new EmptyView({ classList: ['group-trail'] });
+
+        this.#toolbar.addChild(this.#trail);
+
+        this.#toolbar.addChild(new EmptyView({ classList: ['spacer'] }));
+
+        this.#group_button = this.#buildButton("Group", () => {
+            this.groupSelection().catch(e => console.error("could not group the selection", e));
+        });
+
+        this.#ungroup_button = this.#buildButton("Ungroup", () => {
+            this.ungroupSelection().catch(e => console.error("could not ungroup", e));
+        });
+
+        this.#toolbar.addChild(this.#group_button);
+        this.#toolbar.addChild(this.#ungroup_button);
+
+        // The auto-layouter moves every node, which is a big enough change to an author's
+        // arrangement that it belongs behind a button rather than happening on its own — and behind
+        // an undo, which is what {@link arrange} adds over calling the layouter directly.
+        this.#toolbar.addChild(this.#buildButton("Arrange", () => this.arrange()));
+    }
+
+    /**
+     * Say whether each command applies to what is selected right now, and why not when it does not.
+     *
+     * Grouping can be refused for a reason that is not obvious from looking at the canvas — a
+     * selection something outside it runs in the middle of cannot become one node — and a button that
+     * looked available and then did nothing would be the worst of both. So the reason is worked out
+     * up front and shown on the button, which is where an author will look for it.
+     *
+     * Cheap: the check is a walk downstream from the selection, over a graph with tens of nodes in
+     * it, run when the selection changes.
+     */
+    #refreshCommands() {
+        const editor = this.activeEditor();
+
+        const selected = editor.selection.nodes.asArray();
+
+        const grouping = this.#whyNotGroup(editor, selected);
+
+        this.#group_button.setClass('disabled', grouping !== null);
+        this.#group_button.el.setAttribute('title', grouping ?? "make one node out of the selection (Ctrl+G)");
+
+        const groups = selected
+            .map(id => editor.graph.getNode(id))
+            .filter(node => node?.description.isParticleGroupNodeDescription === true);
+
+        const ungrouping = editor.readOnly
+            ? "this group is locked"
+            : (groups.length === 0 ? "select a group node" : null);
+
+        this.#ungroup_button.setClass('disabled', ungrouping !== null);
+        this.#ungroup_button.el.setAttribute('title', ungrouping ?? "put back what the group is made of (Ctrl+Shift+G)");
+    }
+
+    /**
+     * Why the selection cannot be grouped, or `null` when it can.
+     *
+     * @param {NodeGraphEditorView} editor
+     * @param {number[]} selected
+     * @returns {string|null}
+     */
+    #whyNotGroup(editor, selected) {
+        if (editor.readOnly) {
+            return "this group is locked";
+        }
+
+        if (selected.length === 0) {
+            return "select something to group";
+        }
+
+        try {
+            // built and thrown away: the question "could this be grouped" and the answer "here is the
+            // group" are the same work, and doing it twice is cheaper than two ways of being wrong
+            particle_group_from_nodes({
+                graph: editor.graph,
+                nodes: selected,
+                name: "__probe",
+            });
+        } catch (e) {
+            return e.message;
+        }
+
+        return null;
+    }
+
+    /**
+     * Turn what is selected into a group, and put the group where the selection was.
+     *
+     * The one gesture that makes a graph smaller. Which wires become ports, what they are called and
+     * what type they are is worked out from the selection — see
+     * {@link ../../../../src/shade/renderer/particles/graph/make_particle_group.js} — so a group
+     * arrives finished rather than as a form to fill in, and its face is the author's to change
+     * afterwards.
+     *
+     * Everything it does is one step on the timeline: the nodes leaving, the group type appearing,
+     * the node that replaces them, and every wire re-made around it. An undo that left a type behind
+     * in the add-node menu would be an undo that did not undo.
+     *
+     * @returns {Promise<NodeInstance|null>} the node that replaced the selection, or null when there
+     *   was nothing selected to group
+     */
+    async groupSelection() {
+        const editor = this.activeEditor();
+
+        if (editor.readOnly) {
+            throw new Error("This group is locked, so what is inside it cannot be re-grouped.");
+        }
+
+        const selected = editor.selection.nodes.asArray().slice();
+
+        if (selected.length === 0) {
+            return null;
+        }
+
+        const graph = editor.graph;
+        const visual = editor.visual;
+
+        const { group, inputs, outputs } = particle_group_from_nodes({
+            graph,
+            visual,
+            visualRegistry: editor.visualRegistry,
+            layout: this.#layoutOrNothing(),
+            nodes: selected,
+            name: this.effect.unusedGroupName(),
+            label: `Group ${this.effect.groups.length + 1}`,
+            help: "a group made from a selection",
+            icon: PARTICLE_GROUP_ICON,
+        });
+
+        const centre = centroid(visual, selected);
+
+        const create = new NodeCreateAction(
+            graph, visual, editor.visualRegistry, group.description, centre.x, centre.y
+        );
+
+        this.actionProcessor.mark('group');
+
+        // The group is defined before the node that uses it is created: creating one needs a box to
+        // draw it in, and that is generated when the document announces the type.
+        await this.actionProcessor.doMany([
+            new SelectionSetAction(editor.selection, [], []),
+            ...selected.map(id => new NodeDeleteAction(graph, visual, id)),
+            new ParticleGroupDefineAction(this.effect, group),
+            create,
+        ]);
+
+        const node = create.node;
+
+        const wires = [];
+
+        for (const entry of inputs) {
+            const port = group.description.findPortByNameAndDirection(entry.port, PortDirection.In);
+
+            wires.push(new ConnectionCreateAction(graph, entry.from.node, entry.from.port, node.id, port.id));
+        }
+
+        for (const entry of outputs) {
+            const port = group.description.findPortByNameAndDirection(entry.port, PortDirection.Out);
+
+            for (const target of entry.to) {
+                wires.push(new ConnectionCreateAction(graph, node.id, port.id, target.node, target.port));
+            }
+        }
+
+        // and what is selected afterwards is the thing the author just made
+        wires.push(new SelectionSetAction(editor.selection, [node.id], []));
+
+        await this.actionProcessor.doMany(wires);
+
+        return node;
+    }
+
+    /**
+     * Replace every selected group node with the nodes it is made of.
+     *
+     * The way out of a grouping made by mistake, and the way in to a library group an author wants to
+     * change one use of: the definition is not touched, only this instance. What lands in the graph
+     * is what compilation would have inlined anyway.
+     *
+     * @returns {Promise<NodeInstance[]>} the nodes that replaced them; empty when nothing applied
+     */
+    async ungroupSelection() {
+        const editor = this.activeEditor();
+
+        if (editor.readOnly) {
+            throw new Error("This group is locked, so what is inside it cannot be changed.");
+        }
+
+        const selected = editor.selection.nodes.asArray()
+            .map(id => editor.graph.getNode(id))
+            .filter(node => node !== undefined && node.description.isParticleGroupNodeDescription === true);
+
+        if (selected.length === 0) {
+            return [];
+        }
+
+        this.actionProcessor.mark('ungroup');
+
+        const opened = [];
+
+        for (const node of selected) {
+            opened.push(...await this.#ungroup(editor, node));
+        }
+
+        await this.actionProcessor.do(new SelectionSetAction(
+            editor.selection,
+            opened.map(node => node.id),
+            []
+        ));
+
+        return opened;
+    }
+
+    /**
+     * One group node, replaced by a copy of its body.
+     *
+     * Built out of the same actions every other edit is, rather than as a bespoke reversible splice:
+     * the nodes arrive through {@link NodeCreateAction}, the wires through
+     * {@link ConnectionCreateAction}, and the group node leaves through {@link NodeDeleteAction}, so
+     * undo already knows what to do with all of it.
+     *
+     * @param {NodeGraphEditorView} editor
+     * @param {NodeInstance} node the group instance
+     * @returns {Promise<NodeInstance[]>}
+     */
+    async #ungroup(editor, node) {
+        const graph = editor.graph;
+        const visual = editor.visual;
+
+        const group = node.description.group;
+        const body = group.graph;
+
+        const placed = visual.getNode(node.id)?.dimensions.position;
+
+        // Where the body sits inside the group, so what comes out of it lands around where the node
+        // was rather than at the origin.
+        const origin = body_origin(group);
+
+        /** @type {Map<number, NodeCreateAction>} body node id -> the action that recreates it */
+        const created = new Map();
+
+        for (const inner of body.getNodes()) {
+            if (inner === group.inputNode || inner === group.outputNode) {
+                continue;
+            }
+
+            const at = group.visual.getNode(inner.id)?.dimensions.position;
+
+            created.set(inner.id, new NodeCreateAction(
+                graph,
+                visual,
+                editor.visualRegistry,
+                inner.description,
+                (placed?.x ?? 0) + (at === undefined ? 0 : at.x - origin.x),
+                (placed?.y ?? 0) + (at === undefined ? 0 : at.y - origin.y),
+                clone_parameters(inner.parameters)
+            ));
+        }
+
+        await this.actionProcessor.doMany(Array.from(created.values()));
+
+        // What the group node was wired to, read before it goes.
+        const sources = new Map();
+        const targets = new Map();
+
+        for (const connection of node.inConnections) {
+            sources.set(connection.target.port.name, {
+                node: connection.source.instance.id,
+                port: connection.source.port.id,
+            });
+        }
+
+        for (const connection of node.outConnections) {
+            const listed = targets.get(connection.source.port.name) ?? [];
+
+            listed.push({ node: connection.target.instance.id, port: connection.target.port.id });
+
+            targets.set(connection.source.port.name, listed);
+        }
+
+        const wires = [];
+
+        for (const connection of body.getConnections()) {
+            const from = connection.source;
+            const to = connection.target;
+
+            const from_boundary = from.instance === group.inputNode;
+            const to_boundary = to.instance === group.outputNode;
+
+            if (from_boundary && to_boundary) {
+                const source = sources.get(from.port.name);
+
+                if (source !== undefined) {
+                    for (const target of targets.get(to.port.name) ?? []) {
+                        wires.push(new ConnectionCreateAction(
+                            graph, source.node, source.port, target.node, target.port
+                        ));
+                    }
+                }
+
+                continue;
+            }
+
+            if (from_boundary) {
+                const source = sources.get(from.port.name);
+
+                if (source !== undefined) {
+                    wires.push(new ConnectionCreateAction(
+                        graph, source.node, source.port, created.get(to.instance.id).node.id, to.port.id
+                    ));
+                }
+
+                continue;
+            }
+
+            if (to_boundary) {
+                for (const target of targets.get(to.port.name) ?? []) {
+                    wires.push(new ConnectionCreateAction(
+                        graph, created.get(from.instance.id).node.id, from.port.id, target.node, target.port
+                    ));
+                }
+
+                continue;
+            }
+
+            wires.push(new ConnectionCreateAction(
+                graph,
+                created.get(from.instance.id).node.id, from.port.id,
+                created.get(to.instance.id).node.id, to.port.id
+            ));
+        }
+
+        // last: deleting the group node takes its own wires with it, and the ones above replace them
+        await this.actionProcessor.doMany([...wires, new NodeDeleteAction(graph, visual, node.id)]);
+
+        return Array.from(created.values()).map(action => action.node);
+    }
+
+    /**
+     * The effect's attribute schema, or nothing when the declarations do not make one.
+     *
+     * @returns {import("../../../../src/shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout|undefined}
+     */
+    #layoutOrNothing() {
+        try {
+            return this.effect.buildLayout();
+        } catch (e) {
+            // a broken attribute schema types the attribute reads as unknown, and nothing else
+            return undefined;
+        }
+    }
+
+    /**
+     * Show the body of a group instead of the graph that holds it.
+     *
+     * Every instance of a group shares one body, so this is the group's own graph and not a copy of
+     * it — which is the point, and is why the ones shipped with the editor are locked: an edit inside
+     * an unlocked group is an edit to every instance of it in every effect. A locked one opens
+     * read-only, and is worth opening anyway to read.
+     *
+     * Groups nest, so this stacks: opening one from inside another pushes onto the trail rather than
+     * replacing it.
+     *
+     * @param {import("../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup} group
+     * @returns {void}
+     */
+    openGroup(group) {
+        const unplaced = group.visual.nodes.size === 0;
+
+        const editor = this.#buildCanvas({
+            graph: group.graph,
+            visual: group.visual,
+            types: () => this.#groupTypes(group),
+            readOnly: group.locked,
+        });
+
+        editor.addClass('group-body');
+
+        this.#open_groups.push({ group, editor });
+
+        // An editable group's body is not part of the document, so nothing in the effect's change
+        // signal says when its types have moved. Its own graph does.
+        for (const signal of [
+            group.graph.on.nodeAdded,
+            group.graph.on.nodeRemoved,
+            group.graph.on.connectionAdded,
+            group.graph.on.connectionRemoved,
+        ]) {
+            editor.bindSignal(signal, () => {
+                this.#group_types.delete(group);
+
+                editor.graphView.refreshPortTypes();
+            });
+        }
+
+        this.#body.addChild(editor);
+
+        if (unplaced) {
+            // A group's body is built in code and has never been arranged, so the first time anybody
+            // looks at one is the moment to do it. The result is kept on the definition, so the
+            // second look is where the first one left it.
+            editor.layout();
+
+            // bound on the canvas rather than on this view, so closing the group takes the binding
+            // with it rather than leaving one pointed at a canvas nobody will draw again
+            editor.bindSignal(editor.on.arranged, final => {
+                if (final) {
+                    editor.cameraContainAll();
+                }
+            });
+        }
+
+        this.#showActive();
+        this.layout();
+
+        if (!editor.isArrangementProvisional()) {
+            editor.cameraContainAll();
+        }
+    }
+
+    /**
+     * Leave the innermost open group. Harmless when none is open.
+     * @returns {void}
+     */
+    closeGroup() {
+        this.openGroupDepth(this.#open_groups.length - 1);
+    }
+
+    /**
+     * Go back to a particular depth in the trail: 0 is the phase graph, 1 the outermost group.
+     *
+     * @param {number} depth
+     * @returns {void}
+     */
+    openGroupDepth(depth) {
+        const target = Math.max(0, Math.min(depth, this.#open_groups.length));
+
+        for (const closing of this.#open_groups.splice(target)) {
+            this.#body.removeChild(closing.editor);
+        }
+
+        this.#showActive();
+        this.layout();
+    }
+
+    /**
+     * The groups currently open, outermost first.
+     *
+     * @returns {import("../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup[]}
+     */
+    openGroups() {
+        return this.#open_groups.map(entry => entry.group);
+    }
+
+    /**
+     * Re-run the automatic layout over the graph on screen, as one undoable step.
+     *
+     * It moves every node in the graph, which makes it the most destructive thing on the toolbar:
+     * an author who does not like the result has lost an arrangement they may have spent a while on.
+     * So the positions before and after are recorded and pushed as a {@link NodesMoveAction}, the
+     * same action a drag lands on the timeline.
+     *
+     * Inside a locked group it does nothing: an arrangement is a change to the group's definition
+     * like any other, and a locked group's definition is not the author's to change.
+     */
+    arrange() {
+        const editor = this.activeEditor();
+
+        if (editor.readOnly) {
+            return;
+        }
+
+        const open = this.#open_groups[this.#open_groups.length - 1];
+
+        const graph = open === undefined ? this.effect[this.#active] : open.group.graph;
+        const visual = open === undefined ? this.effect[`${this.#active}_visual`] : open.group.visual;
+
+        /** @type {{visual: NodeVisualData, from: Vector2}[]} */
+        const before = [];
+
+        for (const node of graph.getNodes()) {
+            const node_visual = visual.getNode(node.id);
+
+            if (node_visual !== undefined) {
+                before.push({ visual: node_visual, from: node_visual.dimensions.position.clone() });
+            }
+        }
+
+        editor.layout();
+
+        const moved = before.filter(entry => !entry.visual.dimensions.position.equals(entry.from));
+
+        if (moved.length === 0) {
+            return;
+        }
+
+        // the nodes are already where the layouter put them; the action records the net change so
+        // the whole arrange lands on the timeline as one entry
+        this.actionProcessor.mark('arrange');
+        this.actionProcessor.do(new NodesMoveAction(moved.map(entry => ({
+            visual: entry.visual,
+            from: entry.from,
+            to: entry.visual.dimensions.position.clone()
+        }))));
+    }
+
+    /**
+     * @param {string} label
+     * @param {function()} action
+     * @returns {View}
+     */
+    #buildButton(label, action) {
+        const button = new EmptyView({ classList: ['toolbar-button'] });
+
+        button.addChild(new LabelView(label));
+
+        button.el.addEventListener('click', () => {
+            if (button.el.classList.contains('disabled')) {
+                // the title says why, and doing nothing is what "disabled" means
+                return;
+            }
+
+            action();
+        });
+
+        return button;
+    }
+
+    /**
+     * Add a node of the given type to the phase being edited, seeded with the defaults its type
+     * declares — so what lands in the graph is a node that compiles rather than one to repair.
+     *
+     * @param {ParticleNodeDescription} description
+     * @param {object} [options] position, see {@link NodeGraphEditorView#addNode}
+     * @returns {Promise<NodeInstance>} the new node, once the action timeline has applied the add
+     */
+    async addNode(description, options = {}) {
+        const editor = this.activeEditor();
+
+        if (editor.readOnly) {
+            // the canvas on screen is a locked group's body, which is not the author's to add to
+            throw new Error(
+                `Cannot add a '${description.name}': `
+                + `the group '${this.#open_groups[this.#open_groups.length - 1].group.name}' is locked.`
+            );
+        }
+
+        return editor.addNode(description, {
+            ...options,
+            parameters: this.#defaultParameters(description),
+        });
+    }
+
+    /**
+     * The resolved types of one group's body, computed on first use and kept.
+     *
+     * A group's body does not change while an effect is being edited — the shipped ones are locked,
+     * and an unlocked one changing is a change to the group rather than to the effect — so unlike a
+     * phase's types these are not thrown away when the document changes. They are keyed on the group
+     * itself, so two effects open on the same group share one answer.
+     *
+     * @param {import("../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup} group
+     * @returns {import("../../../../src/shade/renderer/particles/graph/infer_particle_graph_types.js").ParticleGraphTypes}
+     */
+    #groupTypes(group) {
+        let types = this.#group_types.get(group);
+
+        if (types === undefined) {
+            // No layout: a group has no effect and so no attribute schema of its own. A group that
+            // reads an attribute types that read as unknown, which is honest — what it reads depends
+            // on the effect it is placed in.
+            types = infer_particle_graph_types(group.graph);
+
+            this.#group_types.set(group, types);
+        }
+
+        return types;
+    }
+
+    /**
+     * The resolved types of one phase's graph, computed on first use since the effect last changed.
+     *
+     * @param {string} id `"init"` or `"update"`
+     * @returns {import("../../../../src/shade/renderer/particles/graph/infer_particle_graph_types.js").ParticleGraphTypes}
+     */
+    #typesOf(id) {
+        let types = this.#types.get(id);
+
+        if (types === undefined) {
+            types = infer_particle_graph_types(this.effect[id], { layout: this.#layoutOrNothing() });
+
+            this.#types.set(id, types);
+        }
+
+        return types;
+    }
+
+    /**
+     * Forget the resolved types and have every port in both phases ask again.
+     *
+     * The open groups are asked too. Their own types have not changed — a group's body is not part
+     * of the document — but a group editor's ports are drawn by the same path, and one left showing
+     * the colours it had before a rebuild would be the only stale thing on screen.
+     */
+    #refreshTypes() {
+        this.#types.clear();
+
+        for (const phase of this.#phases) {
+            phase.editor.graphView.refreshPortTypes();
+        }
+
+        for (const open of this.#open_groups) {
+            open.editor.graphView.refreshPortTypes();
+        }
+    }
+
+    /**
+     * The canvas an edit would land on: the innermost open group, or the phase being edited.
+     *
+     * @returns {NodeGraphEditorView}
+     */
+    activeEditor() {
+        const open = this.#open_groups[this.#open_groups.length - 1];
+
+        return open === undefined
+            ? this.#phases.find(phase => phase.id === this.#active).editor
+            : open.editor;
+    }
+
+    /**
+     * @returns {string} `"init"` or `"update"`
+     */
+    activePhase() {
+        return this.#active;
+    }
+
+    /**
+     * Show one phase. Both stay built, so the one being left keeps its camera and its selection.
+     * @param {string} id `"init"` or `"update"`
+     */
+    setPhase(id) {
+        this.#active = id;
+
+        // A group is opened from a graph, so leaving that graph leaves the group. Coming back to
+        // find somebody else's group still open would be the phase switch not having happened.
+        for (const closing of this.#open_groups.splice(0)) {
+            this.#body.removeChild(closing.editor);
+        }
+
+        for (const phase of this.#phases) {
+            phase.toggle.setClass('active', phase.id === id);
+        }
+
+        this.#showActive();
+
+        this.layout();
+        this.refreshProblems();
+    }
+
+    /**
+     * Show exactly one canvas — the innermost open group, or the active phase — and redraw the trail
+     * back out to it.
+     */
+    #showActive() {
+        const active = this.activeEditor();
+
+        for (const phase of this.#phases) {
+            phase.editor.visible = phase.editor === active;
+        }
+
+        for (const open of this.#open_groups) {
+            open.editor.visible = open.editor === active;
+        }
+
+        this.#refreshCommands();
+
+        this.#trail.removeAllChildren();
+
+        if (this.#open_groups.length === 0) {
+            // nothing to find the way back from
+            return;
+        }
+
+        const crumb = (label, depth, group) => {
+            const view = new EmptyView({ classList: ['crumb'] });
+
+            const current = depth === this.#open_groups.length;
+
+            if (current && group !== undefined && !group.locked) {
+                // The group an author is inside, and made: its name is the one thing about it that
+                // wants changing the moment it exists, so it is a field rather than a word.
+                view.addChild(this.#buildGroupNameField(group));
+            } else {
+                // `name` rather than `label`: LabelView puts `label` on every one of its elements,
+                // so the crumb's name and its "locked" tag would be indistinguishable by class
+                view.addChild(new LabelView(label, { classList: ['name'] }));
+            }
+
+            if (group?.locked === true) {
+                view.addChild(new LabelView("locked", { classList: ['locked'] }));
+            }
+
+            view.setClass('current', current);
+
+            view.el.addEventListener('click', event => {
+                if (event.target instanceof HTMLInputElement) {
+                    // renaming the group is not asking to leave it
+                    return;
+                }
+
+                this.openGroupDepth(depth);
+            });
+
+            this.#trail.addChild(view);
+        };
+
+        crumb(this.#active.toUpperCase(), 0, undefined);
+
+        this.#open_groups.forEach((open, index) => crumb(open.group.label, index + 1, open.group));
+    }
+
+    /**
+     * The field that renames the group being edited.
+     *
+     * What it changes is the *label* — what a person reads. The group's name is an address: it is
+     * what a saved graph holds and what a node is resolved by, and renaming that would mean
+     * rewriting every node that used it. Groups an author makes are numbered rather than named, and
+     * this is what makes that all right.
+     *
+     * Committed when the field is left or Enter is pressed, not per keystroke: a rename that fires
+     * on every letter would put a dozen entries on the undo timeline for one edit.
+     *
+     * @param {import("../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup} group
+     * @returns {View}
+     */
+    #buildGroupNameField(group) {
+        const field = document.createElement('input');
+
+        field.setAttribute('type', 'text');
+        field.setAttribute('spellcheck', 'false');
+        field.classList.add('name', 'rename');
+        field.value = group.label;
+
+        field.addEventListener('change', () => this.renameGroup(group, field.value));
+
+        field.addEventListener('keydown', event => {
+            if (event.key === "Enter") {
+                field.blur();
+            }
+        });
+
+        // typing a name is not a graph shortcut, and Delete in here must not delete the selection
+        field.addEventListener('keydown', event => event.stopPropagation());
+
+        return new EmptyView({ el: field });
+    }
+
+    /**
+     * Call a group something else.
+     *
+     * Reaches every node already on screen that is an instance of it: a canvas is not rebuilt for a
+     * word, and one left showing the old name would be the only stale thing in the window.
+     *
+     * @param {import("../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup} group
+     * @param {string} label
+     * @returns {void}
+     */
+    renameGroup(group, label) {
+        const wanted = label.trim();
+
+        if (wanted === "" || wanted === group.label) {
+            return;
+        }
+
+        group.label = wanted;
+        group.description.display_label = wanted;
+
+        for (const canvas of [...this.#phases.map(phase => phase.editor), ...this.#open_groups.map(open => open.editor)]) {
+            for (const nodeView of canvas.graphView.nodeViews.values()) {
+                if (nodeView.node.description === group.description) {
+                    nodeView.refreshLabel();
+                }
+            }
+        }
+
+        this.effect.touch();
+    }
+
+    /**
+     * Rebuild the problems strip from a fresh compile of the effect.
+     *
+     * Everything is listed, whichever phase it belongs to, because a problem in the phase an author
+     * is not looking at is exactly the one they would otherwise hunt for. Nodes carrying a problem
+     * are marked in the graph as well.
+     */
+    refreshProblems() {
+        // The graph's own problems, not the running program's: with the code layer authoritative the
+        // graphs are not compiled at all, and a panel that then said "no problems" about a graph
+        // with a dangling input in plain sight would be lying about the thing it is showing.
+        const diagnostics = this.effect.graphDiagnostics();
+
+        this.#diagnostics = diagnostics;
+
+        this.#problems.removeAllChildren();
+
+        if (diagnostics.length === 0) {
+            this.#problems.addChild(new LabelView("No problems.", { classList: ['none'] }));
+        }
+
+        for (const diagnostic of diagnostics) {
+            const entry = new EmptyView({ classList: ['problem', diagnostic.severity] });
+
+            const where = diagnostic.node >= 0
+                ? `${diagnostic.scope}: node ${diagnostic.node}`
+                : diagnostic.scope;
+
+            entry.addChild(new LabelView(where, { classList: ['where'] }));
+            entry.addChild(new LabelView(diagnostic.message, { classList: ['message'] }));
+
+            if (diagnostic.node >= 0) {
+                entry.el.addEventListener('click', () => this.revealNode(diagnostic.scope, diagnostic.node));
+            }
+
+            this.#problems.addChild(entry);
+        }
+
+        this.#markProblemNodes(diagnostics);
+    }
+
+    /**
+     * Put a class on the view of every node a diagnostic names, so the graph shows where the
+     * problems are and not only the list below it.
+     *
+     * @param {Array<{scope: string, node: number, severity: string}>} diagnostics
+     */
+    #markProblemNodes(diagnostics) {
+        for (const phase of this.#phases) {
+            for (const node_id of phase.editor.graphView.nodeViews.keys()) {
+                this.#markNode(phase.id, node_id, diagnostics);
+            }
+        }
+    }
+
+    /**
+     * Mark one node from the diagnostics in hand.
+     *
+     * @param {string} phase_id
+     * @param {number} node_id
+     * @param {Array<{scope: string, node: number, severity: string}>} [diagnostics]
+     */
+    #markNode(phase_id, node_id, diagnostics = this.#diagnostics) {
+        const phase = this.#phases.find(candidate => candidate.id === phase_id);
+        const nodeView = phase?.editor.graphView.nodeViews.get(node_id);
+
+        if (nodeView === undefined) {
+            return;
+        }
+
+        let severity;
+
+        for (const diagnostic of diagnostics) {
+            if (diagnostic.scope !== phase_id || diagnostic.node !== node_id) {
+                continue;
+            }
+
+            // an error outranks a warning on the same node
+            if (diagnostic.severity === "error" || severity === undefined) {
+                severity = diagnostic.severity;
+            }
+        }
+
+        nodeView.setClass('has-error', severity === "error");
+        nodeView.setClass('has-warning', severity === "warning");
+    }
+
+    /**
+     * Switch to the phase a node is in and centre the view on it.
+     *
+     * @param {string} phase_id `"init"` or `"update"`
+     * @param {number} node_id
+     */
+    revealNode(phase_id, node_id) {
+        const phase = this.#phases.find(candidate => candidate.id === phase_id);
+
+        if (phase === undefined) {
+            return;
+        }
+
+        this.setPhase(phase_id);
+
+        const visual = this.effect[`${phase_id}_visual`].getNode(node_id);
+
+        if (visual === undefined) {
+            return;
+        }
+
+        const camera = phase.editor.camera;
+        const scale = camera.scale.getValue();
+
+        camera.position.set(
+            visual.dimensions.position.x + visual.dimensions.size.x / 2 - (phase.editor.size.x / 2) / scale,
+            visual.dimensions.position.y + visual.dimensions.size.y / 2 - (phase.editor.size.y / 2) / scale
+        );
+
+        phase.editor.selection.nodes.reset();
+        phase.editor.selection.nodes.add(node_id);
+    }
+
+    /**
+     * The add-node menu of the canvas currently on screen — a test's way in, and a host's way to
+     * open it from a menu of its own.
+     *
+     * @returns {import("../../node-graph/NodeGraphSearchMenuView.js").NodeGraphSearchMenuView|null}
+     */
+    searchMenu() {
+        return this.activeEditor().searchMenu;
+    }
+
+    layout() {
+        const width = this.size.x;
+        const height = this.size.y;
+
+        const body_height = Math.max(0, height - TOOLBAR_HEIGHT - PROBLEMS_HEIGHT);
+
+        this.#toolbar.position.set(0, 0);
+        this.#toolbar.size.set(width, TOOLBAR_HEIGHT);
+
+        this.#body.position.set(0, TOOLBAR_HEIGHT);
+        this.#body.size.set(width, body_height);
+
+        // Every canvas takes the whole body — the phases, and any group opened over them — because
+        // exactly one of them is visible at a time.
+        for (const canvas of [...this.#phases.map(phase => phase.editor), ...this.#open_groups.map(open => open.editor)]) {
+            canvas.position.set(0, 0);
+            canvas.size.set(width, body_height);
+        }
+
+        this.#problems.position.set(0, TOOLBAR_HEIGHT + body_height);
+        this.#problems.size.set(width, PROBLEMS_HEIGHT);
+
+        this.#frameIfNeeded();
+    }
+
+    /**
+     * Point the camera of any phase arranged for the first time at what the arranging produced.
+     *
+     * Two things have to have happened, and they arrive in either order — hence trying from both
+     * ends. The editor needs a size, or there is no viewport to fit a graph into. And its
+     * arrangement has to be the final one: a graph arranged before its nodes were drawn is arranged
+     * again from their real sizes, and a camera aimed at the first attempt is aimed at where the
+     * nodes were about to stop being.
+     */
+    #frameIfNeeded() {
+        for (const phase of this.#phases) {
+            if (!this.#needs_framing.has(phase.id)) {
+                continue;
+            }
+
+            const editor = phase.editor;
+
+            if (editor.size.x <= 0 || editor.size.y <= 0) {
+                continue;
+            }
+
+            if (editor.isArrangementProvisional()) {
+                continue;
+            }
+
+            this.#needs_framing.delete(phase.id);
+
+            editor.cameraContainAll();
+        }
+    }
+}
+
+/**
+ * The glyph a group made out of a selection carries: a box with a smaller box inside it, which is
+ * what one is.
+ *
+ * @type {string}
+ */
+const PARTICLE_GROUP_ICON = "M4 5h16v14H4z M9 10h6v4H9z";
+
+/**
+ * The middle of a set of nodes, in graph space, so a group lands where the thing it replaced was.
+ *
+ * @param {NodeGraphVisualData} visual
+ * @param {number[]} nodes
+ * @returns {{x: number, y: number}}
+ */
+function centroid(visual, nodes) {
+    let x = 0;
+    let y = 0;
+    let counted = 0;
+
+    for (const id of nodes) {
+        const placed = visual.getNode(id);
+
+        if (placed === undefined) {
+            continue;
+        }
+
+        x += placed.dimensions.position.x;
+        y += placed.dimensions.position.y;
+
+        counted++;
+    }
+
+    return counted === 0 ? { x: 0, y: 0 } : { x: x / counted, y: y / counted };
+}
+
+/**
+ * The top-left corner of a group's body, so what comes out of an ungrouping keeps its arrangement
+ * relative to where the group node was rather than jumping to wherever the body happens to sit.
+ *
+ * @param {import("../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup} group
+ * @returns {{x: number, y: number}}
+ */
+function body_origin(group) {
+    let x = Infinity;
+    let y = Infinity;
+
+    for (const node of group.graph.getNodes()) {
+        const placed = group.visual.getNode(node.id);
+
+        if (placed === undefined) {
+            continue;
+        }
+
+        x = Math.min(x, placed.dimensions.position.x);
+        y = Math.min(y, placed.dimensions.position.y);
+    }
+
+    return Number.isFinite(x) ? { x, y } : { x: 0, y: 0 };
+}
+
+/**
+ * A node's parameters, deep enough that the copy and the original cannot write through to each
+ * other — an ungrouped node must not share an array with the group's definition.
+ *
+ * @param {object} parameters
+ * @returns {object}
+ */
+function clone_parameters(parameters) {
+    const result = {};
+
+    for (const key of Object.keys(parameters)) {
+        const value = parameters[key];
+
+        result[key] = Array.isArray(value) ? value.slice() : value;
+    }
+
+    return result;
+}
+
+/**
+ * @param {string} type node type name
+ * @returns {string}
+ */
+function category_of(type) {
+    const index = category_rank(type);
+
+    return index === PALETTE_CATEGORIES.length ? "other" : PALETTE_CATEGORIES[index].name;
+}
+
+/**
+ * @param {string} type node type name
+ * @returns {number} index into {@link PALETTE_CATEGORIES}, or its length for an uncategorised type
+ */
+function category_rank(type) {
+    const index = PALETTE_CATEGORIES.findIndex(candidate => candidate.types.includes(type));
+
+    return index === -1 ? PALETTE_CATEGORIES.length : index;
+}