@woosh/meep-engine 3.15.0 → 3.16.0

package/editor/tools/v2/handle/gizmo_drag_plane.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gizmo_drag_plane.d.ts","sourceRoot":"","sources":["../../../../../editor/tools/v2/handle/gizmo_drag_plane.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,gDARW,OAAO,QACP,MAAM,QACN,MAAM,SACN,MAAM,oCAEN,OAAO,kBACP,OAAO,QAqEjB;AAED;;;;;;;;;;GAUG;AACH,8CARW,OAAO,UACP,OAAO,aACP,OAAO,eACP,OAAO,gBACP,OAAO,GACL,OAAO,CAiBnB;oBA3ImB,sCAAsC"}
+{"version":3,"file":"gizmo_drag_plane.d.ts","sourceRoot":"","sources":["../../../../../editor/tools/v2/handle/gizmo_drag_plane.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,gDARW,OAAO,QACP,MAAM,QACN,MAAM,SACN,MAAM,oCAEN,OAAO,kBACP,OAAO,QAqEjB;AAED;;;;;;;;;;GAUG;AACH,8CARW,OAAO,UACP,OAAO,aACP,OAAO,eACP,OAAO,gBACP,OAAO,GACL,OAAO,CAsBnB;oBAhJmB,sCAAsC"}

package/editor/tools/v2/handle/gizmo_drag_plane.js

@@ -131,7 +131,12 @@ export function gizmo_ray_plane_point(result, origin, direction, plane_point, pl
         return false;
     }
 
-    along.copy(plane_point).sub(origin);
+    // read by index: the plane point may be a transform's translation view, which has no .x
+    along.set(
+        plane_point[0] - origin[0],
+        plane_point[1] - origin[1],
+        plane_point[2] - origin[2]
+    );
 
     const t = along.dot(plane_normal) / denominator;
 

package/editor/view/ecs/components/common/AutoCanvasView.js

@@ -43,6 +43,23 @@ export class AutoCanvasView extends CanvasView {
         this.__renderAt(size.x, size.y);
     }
 
+    /**
+     * Repaint at a size the caller already knows, rather than at the one the observer last reported.
+     *
+     * For a canvas whose size is a decision rather than a measurement — one a parent view sizes
+     * programmatically. {@link #render} asks the DOM how big this is, which is the right question
+     * only when the answer is not already in hand: an element that is not laid out yet, or is
+     * hidden, reports nothing, and a repaint that gave up on that would be a repaint that quietly
+     * did not happen.
+     *
+     * @param {number} width CSS pixels
+     * @param {number} height CSS pixels
+     * @returns {void}
+     */
+    renderAt(width, height) {
+        this.__renderAt(width, height);
+    }
+
     /**
      *
      * @param {number} width CSS pixels

package/editor/view/node-graph/NodeGraphEditorView.d.ts

@@ -7,8 +7,37 @@ export class NodeGraphEditorView extends View {
      * @param {NodeGraphCamera} camera
      * @param {InterfaceCommand[]} [actions]
      * @param {ActionProcessor} [actionProcessor] timeline that all graph edits are routed through, supply a shared one to integrate with a host editor's UNDO/REDO
+     * @param {function({node: NodeInstance, commit: function(string, *)}):View|null} [parameterViewFactory]
+     *        supplies controls for node state the generic parameter mechanism cannot describe, see {@link NodeView}
+     * @param {function(NodeInstancePortReference):DataType} [portDataType]
+     *        the type a port carries on a particular node instance, for a host whose types are
+     *        resolved from the wiring rather than declared on the port; see {@link NodeGraphView}
+     * @param {boolean} [minimap] show the whole graph in a corner, see {@link NodeGraphMinimapView}.
+     *        On by default: a graph is bigger than its viewport almost as soon as it is worth
+     *        editing. Off for a host that puts one somewhere of its own, or has no room for one.
+     * @param {object} [library] the node library, as the canvas's own add-node menu needs it. With
+     *        one, right-clicking the canvas offers the types it names and a wire dropped on open
+     *        canvas offers the ones that could take it; without one, neither gesture does anything.
+     * @param {NodeDescription[]|function():NodeDescription[]} library.descriptions the types to offer
+     * @param {function(NodeDescription):string} [library.categoryOf] group heading for a type
+     * @param {function(NodeDescription):string} [library.describe] one line of help for a type
+     * @param {function(Port, DataType|null, NodeDescription):boolean} [library.accepts] whether a
+     *        port could take a value of a type. The same-type rule by default; a library whose ports
+     *        are typed by what is wired into them supplies its own.
+     * @param {function(NodeDescription):object} [library.parametersOf] starting parameters for a
+     *        type the menu places, so a node arrives ready to compile rather than to repair
+     * @param {boolean} [readOnly] show the graph without offering to change it; see
+     *        {@link NodeGraphView}. Turns off the add-node menu and the editing shortcuts too.
      */
-    constructor({ graph, nodeRegistry, visual, camera, actions, actionProcessor }: NodeGraph);
+    constructor({ graph, nodeRegistry, visual, camera, actions, actionProcessor, parameterViewFactory, portDataType, minimap, library, readOnly }: NodeGraph);
+    /**
+     * @readonly
+     */
+    readonly on: any;
+    /**
+     * @type {boolean}
+     */
+    readOnly: boolean;
     /**
      *
      * @type {ActionProcessor}
@@ -40,16 +69,128 @@ export class NodeGraphEditorView extends View {
      * @type {NodeDescriptionVisualRegistry}
      */
     visualRegistry: NodeDescriptionVisualRegistry;
+    /**
+     * @type {NodeGraphView}
+     */
+    graphView: NodeGraphView;
+    /**
+     * The map of the whole graph, where there is one.
+     *
+     * Composed rather than built in: it reads this editor's graph view and writes its camera,
+     * and nothing else here knows it exists. A host that wants one of its own docks a
+     * {@link NodeGraphMinimapView} elsewhere and turns this off.
+     *
+     * @type {NodeGraphMinimapView|null}
+     */
+    minimap: NodeGraphMinimapView | null;
+    /**
+     * The canvas's own add-node menu, where there is a library to fill it. See
+     * {@link NodeGraphSearchMenuView}.
+     *
+     * @type {NodeGraphSearchMenuView|null}
+     */
+    searchMenu: NodeGraphSearchMenuView | null;
+    /**
+     * The add the canvas menu last started, as a promise of the node it makes; `null` before the
+     * menu has been used.
+     *
+     * Adding a node goes through the {@link ActionProcessor}, which queues, so a node picked
+     * from the menu does not exist when the menu closes. A host that wants to do something with
+     * it — select it, put the camera on it, open its parameters — has to be able to wait for it,
+     * and so does anything testing the gesture.
+     *
+     * @type {Promise<NodeInstance>|null}
+     */
+    menuGesture: Promise<NodeInstance> | null;
+    /**
+     * Add a node and immediately wire one of its ports to an existing one, as a single undoable step.
+     *
+     * What finishes a wire dropped on open canvas. One step rather than two because it was one
+     * gesture: an undo that left a disconnected node behind would be undoing something the author
+     * never did on its own.
+     *
+     * @param {NodeDescription} description
+     * @param {object} options
+     * @param {number} [options.x] graph-space position
+     * @param {number} [options.y] graph-space position
+     * @param {object} [options.parameters] starting parameter values
+     * @param {NodeInstancePortReference} options.endpoint the port the wire came from
+     * @param {Port} options.port the port of the new node to wire it to
+     * @returns {Promise<NodeInstance>} the new node
+     */
+    addNodeWiredTo(description: NodeDescription, { x, y, parameters, endpoint, port }: {
+        x?: number;
+        y?: number;
+        parameters?: object;
+        endpoint: NodeInstancePortReference;
+        port: Port;
+    }): Promise<NodeInstance>;
+    /**
+     * Arrange the nodes and route the wires.
+     *
+     * An arrangement is only as good as the node sizes it is given, and those are facts about drawn
+     * nodes: how wide a host's own control is, how long the text in a picker runs. Until the graph
+     * has been on screen the only sizes anyone has are {@link NodeDescriptionVisualRegistry}'s
+     * estimates from port and parameter counts, which cannot know either.
+     *
+     * So a graph arranged before it has been drawn is arranged twice: once now, because a graph
+     * opened straight into this has to look like something, and once more when the views report
+     * what the browser actually made of them. {@link #on.arranged} says which of the two just
+     * happened.
+     */
     layout(): void;
+    /**
+     * Whether the arrangement in hand was made from estimated node sizes and is still to be redone
+     * from the drawn ones. See {@link #layout}.
+     *
+     * What to consult before doing anything that depends on where the nodes ended up — pointing a
+     * camera at them, most of all, since framing the provisional arrangement leaves it aimed at
+     * where the nodes were about to stop being.
+     *
+     * @returns {boolean}
+     */
+    isArrangementProvisional(): boolean;
+    /**
+     * Add a node of the given type to the graph, as one undoable step.
+     *
+     * With no position, the node lands in the middle of what the author is looking at — where they
+     * will see it — rather than at the graph origin, which may be off screen entirely.
+     *
+     * @param {NodeDescription} description
+     * @param {object} [options]
+     * @param {number} [options.x] graph-space position
+     * @param {number} [options.y] graph-space position
+     * @param {object} [options.parameters] starting parameter values
+     * @returns {Promise<NodeInstance>} the new node, once the timeline has applied the action —
+     *          {@link ActionProcessor} queues, so it does not exist on return
+     */
+    addNode(description: NodeDescription, { x, y, parameters }?: {
+        x?: number;
+        y?: number;
+        parameters?: object;
+    }): Promise<NodeInstance>;
+    /**
+     * Middle of the visible area, in graph space.
+     * @returns {Vector2}
+     */
+    viewCentreInGraphSpace(): Vector2;
     /**
      * Delete everything in the current selection as a single undoable group
+     *
+     * @returns {Promise} settles once the timeline has applied the deletion — {@link ActionProcessor}
+     *          queues, so nothing has been removed on return
      */
-    deleteSelection(): void;
+    deleteSelection(): Promise<any>;
     cameraContainAll(): void;
+    #private;
 }
 import View from "../../../src/view/View.js";
 import { ActionProcessor } from "../../../src/core/process/undo/ActionProcessor.js";
 import { NodeGraphSelection } from "./NodeGraphSelection.js";
 import { NodeGraphCamera } from "./NodeGraphView.js";
 import { NodeDescriptionVisualRegistry } from "../../../src/core/model/node-graph/visual/NodeDescriptionVisualRegistry.js";
+import { NodeGraphView } from "./NodeGraphView.js";
+import { NodeGraphMinimapView } from "./NodeGraphMinimapView.js";
+import { NodeGraphSearchMenuView } from "./NodeGraphSearchMenuView.js";
+import Vector2 from "../../../src/core/geom/Vector2.js";
 //# sourceMappingURL=NodeGraphEditorView.d.ts.map

package/editor/view/node-graph/NodeGraphEditorView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeGraphEditorView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphEditorView.js"],"names":[],"mappings":"AAmBA;IACI;;;;;;;;OAQG;IACH,0FA8IC;IA3IG;;;OAGG;IACH,2CAAsC;IAEtC;;;OAGG;IACH,WAFU,kBAAkB,CAEa;IAEzC;;;OAGG;IACH,QAFU,eAAe,CAEL;IACpB;;;OAGG;IACH,4BAAoB;IAEpB;;;OAGG;IACH,iBAAkB;IAElB,mBAAuC;IAUvC;;;OAGG;IACH,gBAFU,6BAA6B,CAEH;IAkGxC,eAGC;IAED;;OAEG;IACH,wBA6BC;IAED,yBAuDC;CACJ;iBAvQgB,2BAA2B;gCAHZ,mDAAmD;mCAMhD,yBAAyB;gCADb,oBAAoB;8CAO5D,4EAA4E"}
+{"version":3,"file":"NodeGraphEditorView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphEditorView.js"],"names":[],"mappings":"AA4CA;IAyBI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,0JAiOC;IAvRD;;OAEG;IACH,iBAWE;IAuDE;;OAEG;IACH,UAFU,OAAO,CAEO;IAExB;;;OAGG;IACH,2CAAsC;IAEtC;;;OAGG;IACH,WAFU,kBAAkB,CAEa;IAEzC;;;OAGG;IACH,QAFU,eAAe,CAEL;IACpB;;;OAGG;IACH,4BAAoB;IAEpB;;;OAGG;IACH,iBAAkB;IAElB,mBAAuC;IAYvC;;;OAGG;IACH,gBAFU,6BAA6B,CAEH;IAepC;;OAEG;IACH,WAFU,aAAa,CAEG;IA2E1B;;;;;;;;OAQG;IACH,SAFU,oBAAoB,GAAC,IAAI,CAEhB;IA4BnB;;;;;OAKG;IACH,YAFU,uBAAuB,GAAC,IAAI,CAEhB;IAEtB;;;;;;;;;;OAUG;IACH,aAFU,qBAAqB,GAAC,IAAI,CAEb;IAgF3B;;;;;;;;;;;;;;;OAeG;IACH;QAP4B,CAAC,GAAlB,MAAM;QACW,CAAC,GAAlB,MAAM;QACW,UAAU,GAA3B,MAAM;QAC6B,QAAQ;QAC7B,IAAI;QAChB,qBAAqB,CAuBjC;IAED;;;;;;;;;;;;OAYG;IACH,eAWC;IAED;;;;;;;;;OASG;IACH,4BAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;OAaG;IACH;QAN4B,CAAC,GAAlB,MAAM;QACW,CAAC,GAAlB,MAAM;QACW,UAAU,GAA3B,MAAM;QACJ,qBAAqB,CA6BjC;IAED;;;OAGG;IACH,0BAFa,OAAO,CAQnB;IAED;;;;;OAKG;IACH,gCA8BC;IAED,yBAuDC;;CACJ;iBAtmBgB,2BAA2B;gCAHZ,mDAAmD;mCAOhD,yBAAyB;gCAFb,oBAAoB;8CAS5D,4EAA4E;8BATpC,oBAAoB;qCAC9B,2BAA2B;wCAexB,8BAA8B;oBALlD,mCAAmC"}

package/editor/view/node-graph/NodeGraphEditorView.js

@@ -1,3 +1,4 @@
+import Signal from "../../../src/core/events/signal/Signal.js";
 import { clamp } from "../../../src/core/math/clamp.js";
 import { min2 } from "../../../src/core/math/min2.js";
 import { ActionProcessor } from "../../../src/core/process/undo/ActionProcessor.js";
@@ -6,18 +7,66 @@ import { KeyCodes } from "../../../src/engine/input/devices/KeyCodes.js";
 import View from "../../../src/view/View.js";
 import { NODE_GRAPH_SCALE_MAX, NODE_GRAPH_SCALE_MIN } from "./NodeGraphCamera.js";
 import { NodeGraphCamera, NodeGraphView } from "./NodeGraphView.js";
+import { NodeGraphMinimapView } from "./NodeGraphMinimapView.js";
 import { NodeGraphSelection } from "./NodeGraphSelection.js";
 import { ConnectionDeleteAction } from "./actions/ConnectionDeleteAction.js";
+import { NodeCreateAction } from "./actions/NodeCreateAction.js";
 import { NodeDeleteAction } from "./actions/NodeDeleteAction.js";
 import { SelectionSetAction } from "./actions/SelectionSetAction.js";
 import {
     NodeDescriptionVisualRegistry
 } from "../../../src/core/model/node-graph/visual/NodeDescriptionVisualRegistry.js";
 import AABB2 from "../../../src/core/geom/2d/aabb/AABB2.js";
+import Vector2 from "../../../src/core/geom/Vector2.js";
 import ButtonView from "../../../src/view/elements/button/ButtonView.js";
 import EmptyView from "../../../src/view/elements/EmptyView.js";
+import { PortDirection } from "../../../src/core/model/node-graph/node/PortDirection.js";
+import { ConnectionCreateAction } from "./actions/ConnectionCreateAction.js";
+import { NodeGraphSearchMenuView } from "./NodeGraphSearchMenuView.js";
+
+/**
+ * Whether a port could take a value of this type, knowing nothing about the graph's domain: the same
+ * type, or a port that declares none.
+ *
+ * The default for {@link NodeGraphEditorView}'s `library.accepts`. A host whose ports are all
+ * declared with one type — because what a port carries is resolved from the wiring rather than
+ * declared, which is how the particle library works — supplies its own and gets a real answer. The
+ * node's type comes along for a host whose answer is not on the port itself.
+ *
+ * @param {Port} port
+ * @param {DataType|null} dataType
+ * @param {NodeDescription} description the type the port belongs to
+ * @returns {boolean}
+ */
+function port_accepts_type(port, dataType, description) {
+    return dataType === null || port.dataType === null || port.dataType === dataType;
+}
 
 export class NodeGraphEditorView extends View {
+    /**
+     * @readonly
+     */
+    on = {
+        ...this.on,
+
+        /**
+         * The graph has been arranged. Carries whether the arrangement is the final one, or the
+         * provisional one described on {@link #layout}.
+         *
+         * @readonly
+         * @type {Signal<boolean>}
+         */
+        arranged: new Signal()
+    };
+
+    /**
+     * The arrangement in hand was made from estimated node sizes, and is to be made again when the
+     * real ones arrive. See {@link #layout}.
+     *
+     * @type {boolean}
+     */
+    #arrangement_provisional = false;
+
     /**
      *
      * @param {NodeGraph} graph
@@ -26,10 +75,48 @@ export class NodeGraphEditorView extends View {
      * @param {NodeGraphCamera} camera
      * @param {InterfaceCommand[]} [actions]
      * @param {ActionProcessor} [actionProcessor] timeline that all graph edits are routed through, supply a shared one to integrate with a host editor's UNDO/REDO
+     * @param {function({node: NodeInstance, commit: function(string, *)}):View|null} [parameterViewFactory]
+     *        supplies controls for node state the generic parameter mechanism cannot describe, see {@link NodeView}
+     * @param {function(NodeInstancePortReference):DataType} [portDataType]
+     *        the type a port carries on a particular node instance, for a host whose types are
+     *        resolved from the wiring rather than declared on the port; see {@link NodeGraphView}
+     * @param {boolean} [minimap] show the whole graph in a corner, see {@link NodeGraphMinimapView}.
+     *        On by default: a graph is bigger than its viewport almost as soon as it is worth
+     *        editing. Off for a host that puts one somewhere of its own, or has no room for one.
+     * @param {object} [library] the node library, as the canvas's own add-node menu needs it. With
+     *        one, right-clicking the canvas offers the types it names and a wire dropped on open
+     *        canvas offers the ones that could take it; without one, neither gesture does anything.
+     * @param {NodeDescription[]|function():NodeDescription[]} library.descriptions the types to offer
+     * @param {function(NodeDescription):string} [library.categoryOf] group heading for a type
+     * @param {function(NodeDescription):string} [library.describe] one line of help for a type
+     * @param {function(Port, DataType|null, NodeDescription):boolean} [library.accepts] whether a
+     *        port could take a value of a type. The same-type rule by default; a library whose ports
+     *        are typed by what is wired into them supplies its own.
+     * @param {function(NodeDescription):object} [library.parametersOf] starting parameters for a
+     *        type the menu places, so a node arrives ready to compile rather than to repair
+     * @param {boolean} [readOnly] show the graph without offering to change it; see
+     *        {@link NodeGraphView}. Turns off the add-node menu and the editing shortcuts too.
      */
-    constructor({ graph, nodeRegistry, visual, camera, actions = [], actionProcessor = new ActionProcessor({}) }) {
+    constructor({
+                    graph,
+                    nodeRegistry,
+                    visual,
+                    camera,
+                    actions = [],
+                    actionProcessor = new ActionProcessor({}),
+                    parameterViewFactory = undefined,
+                    portDataType = undefined,
+                    minimap = true,
+                    library = undefined,
+                    readOnly = false
+                }) {
         super();
 
+        /**
+         * @type {boolean}
+         */
+        this.readOnly = readOnly;
+
         /**
          *
          * @type {ActionProcessor}
@@ -62,6 +149,8 @@ export class NodeGraphEditorView extends View {
         this.el = document.createElement('div');
         this.addClass('ui-node-graph-editor-view');
 
+        this.setClass('read-only', readOnly);
+
 
         const visualRegistry = new NodeDescriptionVisualRegistry();
         //generate visual descriptions for registry nodes
@@ -82,12 +171,27 @@ export class NodeGraphEditorView extends View {
             camera,
             nodeVisualRegistry: visualRegistry,
             actionProcessor,
-            selection: this.selection
+            selection: this.selection,
+            parameterViewFactory,
+            portDataType,
+            readOnly
         });
 
+        /**
+         * @type {NodeGraphView}
+         */
+        this.graphView = graphView;
+
         this.size.onChanged.add((x, y) => graphView.size.set(x, y));
         this.addChild(graphView);
 
+        // the second half of the deal struck in #layout
+        this.bindSignal(graphView.on.measured, () => {
+            if (this.#arrangement_provisional) {
+                this.layout();
+            }
+        });
+
         // keyboard shortcuts, the element must be focusable to receive key events
         this.el.setAttribute('tabindex', '-1');
 
@@ -101,7 +205,14 @@ export class NodeGraphEditorView extends View {
                 return;
             }
 
-            if (event.keyCode === KeyCodes.delete || event.keyCode === KeyCodes.backspace) {
+            // Deleting is an edit to *this* graph, and a read-only canvas has none to offer. Undo and
+            // redo are not: they move a timeline this canvas shares with everything else the host is
+            // editing, and swallowing them here would mean drilling into a locked group quietly took
+            // undo away.
+            if (
+                !readOnly
+                && (event.keyCode === KeyCodes.delete || event.keyCode === KeyCodes.backspace)
+            ) {
                 event.preventDefault();
                 event.stopPropagation();
 
@@ -144,6 +255,23 @@ export class NodeGraphEditorView extends View {
 
         vUserInterface.addChild(vActionBar);
 
+        /**
+         * The map of the whole graph, where there is one.
+         *
+         * Composed rather than built in: it reads this editor's graph view and writes its camera,
+         * and nothing else here knows it exists. A host that wants one of its own docks a
+         * {@link NodeGraphMinimapView} elsewhere and turns this off.
+         *
+         * @type {NodeGraphMinimapView|null}
+         */
+        this.minimap = null;
+
+        if (minimap) {
+            this.minimap = new NodeGraphMinimapView({ graphView });
+
+            vUserInterface.addChild(this.minimap);
+        }
+
         this.addChild(vUserInterface);
 
         vActionBar.addChild(new ButtonView({
@@ -164,6 +292,31 @@ export class NodeGraphEditorView extends View {
             vActionBar.addChild(b);
         });
 
+        /**
+         * The canvas's own add-node menu, where there is a library to fill it. See
+         * {@link NodeGraphSearchMenuView}.
+         *
+         * @type {NodeGraphSearchMenuView|null}
+         */
+        this.searchMenu = null;
+
+        /**
+         * The add the canvas menu last started, as a promise of the node it makes; `null` before the
+         * menu has been used.
+         *
+         * Adding a node goes through the {@link ActionProcessor}, which queues, so a node picked
+         * from the menu does not exist when the menu closes. A host that wants to do something with
+         * it — select it, put the camera on it, open its parameters — has to be able to wait for it,
+         * and so does anything testing the gesture.
+         *
+         * @type {Promise<NodeInstance>|null}
+         */
+        this.menuGesture = null;
+
+        if (library !== undefined && !readOnly) {
+            this.#buildSearchMenu(library);
+        }
+
         // ensure pointer events are enabled; suppress the focus ring of the keyboard-focusable element
         this.css({
             pointerEvents: 'auto',
@@ -171,15 +324,213 @@ export class NodeGraphEditorView extends View {
         });
     }
 
+    /**
+     * Wire the two canvas gestures that ask for a node to the menu that answers them.
+     *
+     * @param {object} library see the constructor
+     */
+    #buildSearchMenu(library) {
+        const accepts = library.accepts ?? port_accepts_type;
+        const parametersOf = library.parametersOf ?? (() => ({}));
+
+        const menu = new NodeGraphSearchMenuView({
+            descriptions: library.descriptions,
+            categoryOf: library.categoryOf,
+            describe: library.describe,
+        });
+
+        this.searchMenu = menu;
+
+        this.addChild(menu);
+
+        this.bindSignal(this.graphView.on.canvasContextMenu, ({ x, y, graph_x, graph_y }) => {
+            menu.open({
+                x, y,
+                onPick: description => {
+                    this.menuGesture = this.addNode(description, {
+                        x: graph_x,
+                        y: graph_y,
+                        parameters: parametersOf(description),
+                    });
+
+                    // fire and forget: the timeline applies the add, and a failure is the menu
+                    // offering a type the library cannot build, which is worth a console entry
+                    this.menuGesture.catch(e => console.error("could not add node", e));
+                },
+            });
+        });
+
+        this.bindSignal(this.graphView.on.connectionDropped, ({ endpoint, x, y, graph_x, graph_y }) => {
+            // the wire came out of one side, so what is wanted is a type with a port on the other
+            const wanted = endpoint.port.direction === PortDirection.Out ? PortDirection.In : PortDirection.Out;
+
+            const dataType = this.graphView.portDataType(endpoint);
+
+            const first_port = description => description
+                .getPortsByDirection(wanted)
+                .find(port => accepts(port, dataType, description)) ?? null;
+
+            menu.open({
+                x, y,
+                predicate: description => first_port(description) !== null,
+                heading: wanted === PortDirection.In
+                    ? `takes a ${dataType?.name ?? "value"}`
+                    : `produces a ${dataType?.name ?? "value"}`,
+                onPick: description => {
+                    this.menuGesture = this.addNodeWiredTo(description, {
+                        x: graph_x,
+                        y: graph_y,
+                        parameters: parametersOf(description),
+                        endpoint,
+                        port: first_port(description),
+                    });
+
+                    this.menuGesture.catch(e => console.error("could not add node", e));
+                },
+            });
+        });
+    }
+
+    /**
+     * Add a node and immediately wire one of its ports to an existing one, as a single undoable step.
+     *
+     * What finishes a wire dropped on open canvas. One step rather than two because it was one
+     * gesture: an undo that left a disconnected node behind would be undoing something the author
+     * never did on its own.
+     *
+     * @param {NodeDescription} description
+     * @param {object} options
+     * @param {number} [options.x] graph-space position
+     * @param {number} [options.y] graph-space position
+     * @param {object} [options.parameters] starting parameter values
+     * @param {NodeInstancePortReference} options.endpoint the port the wire came from
+     * @param {Port} options.port the port of the new node to wire it to
+     * @returns {Promise<NodeInstance>} the new node
+     */
+    async addNodeWiredTo(description, { x, y, parameters = {}, endpoint, port }) {
+        const node = await this.addNode(description, { x, y, parameters });
+
+        if (port === null || port === undefined) {
+            // nothing on the new node can take the wire; the node still lands, since that is what
+            // was picked
+            return node;
+        }
+
+        const outgoing = endpoint.port.direction === PortDirection.Out;
+
+        // `addNode` marked the timeline and has not marked it again, so this joins the same step
+        await this.actionProcessor.do(new ConnectionCreateAction(
+            this.graph,
+            outgoing ? endpoint.instance.id : node.id,
+            outgoing ? endpoint.port.id : port.id,
+            outgoing ? node.id : endpoint.instance.id,
+            outgoing ? port.id : endpoint.port.id
+        ));
+
+        return node;
+    }
+
+    /**
+     * Arrange the nodes and route the wires.
+     *
+     * An arrangement is only as good as the node sizes it is given, and those are facts about drawn
+     * nodes: how wide a host's own control is, how long the text in a picker runs. Until the graph
+     * has been on screen the only sizes anyone has are {@link NodeDescriptionVisualRegistry}'s
+     * estimates from port and parameter counts, which cannot know either.
+     *
+     * So a graph arranged before it has been drawn is arranged twice: once now, because a graph
+     * opened straight into this has to look like something, and once more when the views report
+     * what the browser actually made of them. {@link #on.arranged} says which of the two just
+     * happened.
+     */
     layout() {
         this.visual.ensure(this.graph, this.visualRegistry);
         this.visual.layout(this.graph);
+
+        // Laying out re-routes every wire, and a layout that happened to move no node at all would
+        // announce nothing the map is listening for. See NodeGraphMinimapView#invalidate.
+        this.minimap?.invalidate();
+
+        this.#arrangement_provisional = !this.graphView.isMeasured();
+
+        this.on.arranged.send1(!this.#arrangement_provisional);
+    }
+
+    /**
+     * Whether the arrangement in hand was made from estimated node sizes and is still to be redone
+     * from the drawn ones. See {@link #layout}.
+     *
+     * What to consult before doing anything that depends on where the nodes ended up — pointing a
+     * camera at them, most of all, since framing the provisional arrangement leaves it aimed at
+     * where the nodes were about to stop being.
+     *
+     * @returns {boolean}
+     */
+    isArrangementProvisional() {
+        return this.#arrangement_provisional;
+    }
+
+    /**
+     * Add a node of the given type to the graph, as one undoable step.
+     *
+     * With no position, the node lands in the middle of what the author is looking at — where they
+     * will see it — rather than at the graph origin, which may be off screen entirely.
+     *
+     * @param {NodeDescription} description
+     * @param {object} [options]
+     * @param {number} [options.x] graph-space position
+     * @param {number} [options.y] graph-space position
+     * @param {object} [options.parameters] starting parameter values
+     * @returns {Promise<NodeInstance>} the new node, once the timeline has applied the action —
+     *          {@link ActionProcessor} queues, so it does not exist on return
+     */
+    async addNode(description, { x, y, parameters = {} } = {}) {
+        let place_x = x;
+        let place_y = y;
+
+        if (place_x === undefined || place_y === undefined) {
+            const centre = this.viewCentreInGraphSpace();
+
+            place_x = place_x ?? centre.x;
+            place_y = place_y ?? centre.y;
+        }
+
+        const action = new NodeCreateAction(
+            this.graph,
+            this.visual,
+            this.visualRegistry,
+            description,
+            place_x,
+            place_y,
+            parameters
+        );
+
+        this.actionProcessor.mark(`add ${description.name}`);
+
+        await this.actionProcessor.do(action);
+
+        return action.node;
+    }
+
+    /**
+     * Middle of the visible area, in graph space.
+     * @returns {Vector2}
+     */
+    viewCentreInGraphSpace() {
+        const result = new Vector2(this.size.x / 2, this.size.y / 2);
+
+        this.camera.canvasToGraph(result, result);
+
+        return result;
     }
 
     /**
      * Delete everything in the current selection as a single undoable group
+     *
+     * @returns {Promise} settles once the timeline has applied the deletion — {@link ActionProcessor}
+     *          queues, so nothing has been removed on return
      */
-    deleteSelection() {
+    async deleteSelection() {
         const selection = this.selection;
 
         if (selection.isEmpty()) {
@@ -198,7 +549,7 @@ export class NodeGraphEditorView extends View {
             const connection = graph.getConnection(id);
 
             if (connection !== undefined) {
-                actions.push(new ConnectionDeleteAction(graph, connection));
+                actions.push(new ConnectionDeleteAction(graph, connection, this.visual));
             }
         });
 
@@ -207,7 +558,8 @@ export class NodeGraphEditorView extends View {
         });
 
         this.actionProcessor.mark('delete selection');
-        this.actionProcessor.doMany(actions);
+
+        await this.actionProcessor.doMany(actions);
     }
 
     cameraContainAll() {