@woosh/meep-engine 3.15.0 → 3.17.0

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,73 @@ 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 { connection_bind_actions } from "./actions/connection_bind_actions.js";
+import { NodeGraphSearchMenuView } from "./NodeGraphSearchMenuView.js";
+import { ConnectionCreateAction } from "./actions/ConnectionCreateAction.js";
+import {
+    NODE_GRAPH_PASTE_STEP,
+    NodeGraphClipboard,
+    node_graph_fragment_centre,
+    node_graph_fragment_from_nodes,
+} from "./NodeGraphClipboard.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,16 +82,75 @@ 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.
+     * @param {NodeGraphClipboard} [clipboard] what `Ctrl+C` writes and `Ctrl+V` reads. A host with
+     *        several canvases over one document passes one to all of them, so a copy taken in one
+     *        pastes in the next; on its own, a canvas gets one of its own and copies to itself.
+     * @param {function(NodeInstance):boolean} [copyable] whether a node may be had a second of, for
+     *        a host with types that exist once per graph. See
+     *        {@link node_graph_fragment_from_nodes}.
      */
-    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,
+                    clipboard = new NodeGraphClipboard(),
+                    copyable = undefined
+                }) {
         super();
 
+        /**
+         * @type {boolean}
+         */
+        this.readOnly = readOnly;
+
         /**
          *
          * @type {ActionProcessor}
          */
         this.actionProcessor = actionProcessor;
 
+        /**
+         * What a copy is written to and a paste read from. Shared with the host's other canvases
+         * when it supplied one.
+         *
+         * @type {NodeGraphClipboard}
+         */
+        this.clipboard = clipboard;
+
+        /**
+         * @type {function(NodeInstance):boolean}
+         */
+        this.copyable = copyable ?? (() => true);
+
         /**
          *
          * @type {NodeGraphSelection}
@@ -62,6 +177,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 +199,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 +233,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();
 
@@ -119,11 +258,60 @@ export class NodeGraphEditorView extends View {
                 event.stopPropagation();
 
                 actionProcessor.undo();
-            } else if (event.keyCode === KeyCodes.y) {
+
+                return;
+            }
+
+            if (event.keyCode === KeyCodes.y) {
                 event.preventDefault();
                 event.stopPropagation();
 
                 actionProcessor.redo();
+
+                return;
+            }
+
+            // The clipboard's three want Ctrl and nothing else. `AltGr` is `Ctrl+Alt` on a European
+            // keyboard, so a canvas that answered that combination would copy every time an author
+            // typed one of the characters behind it; and `Ctrl+Shift+C` belongs to the browser.
+            if (event.shiftKey || event.altKey) {
+                return;
+            }
+
+            // Copying reads the graph, so a locked group body offers it: taking a copy of something
+            // out of one of the library's own groups and putting it in a graph of your own is the
+            // point of being able to open them. Putting something *into* one is not.
+            if (event.keyCode === KeyCodes.c) {
+                event.preventDefault();
+                event.stopPropagation();
+
+                this.copySelection();
+
+                return;
+            }
+
+            if (readOnly) {
+                return;
+            }
+
+            // `Ctrl+D` is the browser's bookmark shortcut, so it is swallowed whether or not there
+            // is anything selected to duplicate — leaving it through on an empty selection would
+            // mean the canvas sometimes bookmarked the page instead.
+            if (event.keyCode === KeyCodes.d) {
+                event.preventDefault();
+                event.stopPropagation();
+
+                this.duplicateSelection()
+                    .catch(e => console.error("could not duplicate the selection", e));
+
+                return;
+            }
+
+            if (event.keyCode === KeyCodes.v) {
+                event.preventDefault();
+                event.stopPropagation();
+
+                this.paste().catch(e => console.error("could not paste", e));
             }
         });
 
@@ -144,6 +332,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 +369,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 +401,214 @@ 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.doMany(connection_bind_actions(
+            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,
+            this.visual
+        ));
+
+        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 +627,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 +636,173 @@ export class NodeGraphEditorView extends View {
         });
 
         this.actionProcessor.mark('delete selection');
-        this.actionProcessor.doMany(actions);
+
+        await this.actionProcessor.doMany(actions);
+    }
+
+    /**
+     * Take a copy of the selected nodes, and of every wire they hold whole.
+     *
+     * Reading, not editing, so a read-only canvas offers it: opening one of a library's own groups
+     * to take a copy of what is inside it is the point of being able to open them.
+     *
+     * @returns {boolean} whether anything was copied. A selection with nothing copyable in it leaves
+     *          the clipboard alone rather than emptying it, which is the one outcome an author
+     *          asking for a copy certainly did not want.
+     */
+    copySelection() {
+        const fragment = node_graph_fragment_from_nodes({
+            graph: this.graph,
+            visual: this.visual,
+            nodes: this.selection.nodes.asArray(),
+            copyable: this.copyable,
+        });
+
+        if (fragment === null) {
+            return false;
+        }
+
+        this.clipboard.write(fragment);
+
+        return true;
+    }
+
+    /**
+     * Put what was copied into this graph, in the middle of what the author is looking at.
+     *
+     * Where a paste lands is the one decision here. It goes to the middle of the view rather than
+     * back where it was copied from, for the same reason a node added from the menu with no position
+     * does: what arrives has to be somewhere the author can see it, and the place it was copied from
+     * may be a long way off screen — a copy taken in one phase and pasted in the other has no
+     * meaningful "back where it was" at all. The arrangement inside the fragment is kept exactly; it
+     * is the whole of it that moves. A repeat paste of the same content steps aside by
+     * {@link NODE_GRAPH_PASTE_STEP} so that copies do not hide each other.
+     *
+     * @returns {Promise<NodeInstance[]>} the nodes that landed, once the timeline has applied them;
+     *          empty when there was nothing on the clipboard
+     * @throws if this canvas is read-only
+     */
+    async paste() {
+        if (this.readOnly) {
+            throw new Error("This graph is read-only, so nothing can be pasted into it.");
+        }
+
+        const clipboard = this.clipboard;
+
+        const fragment = clipboard.read();
+
+        if (fragment === null) {
+            return [];
+        }
+
+        const centre = node_graph_fragment_centre(fragment);
+        const target = this.viewCentreInGraphSpace();
+
+        const step = clipboard.pastes * NODE_GRAPH_PASTE_STEP;
+
+        // before the placing rather than after it: the timeline queues, so two pastes issued in one
+        // tick — which is what holding Ctrl+V down is — would otherwise both read the same count and
+        // land on top of each other
+        clipboard.notePaste();
+
+        return this.#placeFragment(
+            fragment,
+            target.x - centre.x + step,
+            target.y - centre.y + step,
+            'paste'
+        );
+    }
+
+    /**
+     * A second of everything selected, beside the originals.
+     *
+     * Beside rather than in the middle of the view, which is where {@link #paste} puts things: a
+     * duplicate is a second of something the author is already looking at, and centring it would
+     * take it away from the thing it is a second of. The clipboard is not touched — `Ctrl+D` is not
+     * a copy, and it must not cost the author whatever they had copied earlier.
+     *
+     * @returns {Promise<NodeInstance[]>} the new nodes; empty when nothing selected could be had a
+     *          second of
+     * @throws if this canvas is read-only
+     */
+    async duplicateSelection() {
+        if (this.readOnly) {
+            throw new Error("This graph is read-only, so nothing in it can be duplicated.");
+        }
+
+        const fragment = node_graph_fragment_from_nodes({
+            graph: this.graph,
+            visual: this.visual,
+            nodes: this.selection.nodes.asArray(),
+            copyable: this.copyable,
+        });
+
+        if (fragment === null) {
+            return [];
+        }
+
+        return this.#placeFragment(fragment, NODE_GRAPH_PASTE_STEP, NODE_GRAPH_PASTE_STEP, 'duplicate');
+    }
+
+    /**
+     * Build a fragment into this graph, offset, as one undoable step, and leave it selected.
+     *
+     * Two batches under one mark, because the wires need ids the creates have not handed out yet —
+     * the same shape an ungrouping has, and for the same reason. What is selected afterwards is what
+     * just arrived, so it can be dragged into place without being hunted for first.
+     *
+     * @param {import("./NodeGraphClipboard.js").NodeGraphFragment} fragment
+     * @param {number} offset_x graph-space
+     * @param {number} offset_y graph-space
+     * @param {string} label what the step is called on the timeline
+     * @returns {Promise<NodeInstance[]>}
+     */
+    async #placeFragment(fragment, offset_x, offset_y, label) {
+        const graph = this.graph;
+        const visual = this.visual;
+
+        // A canvas draws a node in a box generated from its type, and throws when it has none — so a
+        // fragment carrying a type this canvas has never drawn would fail from inside the timeline,
+        // half-way through a step. Which is reachable: the clipboard is shared between canvases, and
+        // a host's canvases need not have been built from the same set of types. Generating a box is
+        // arithmetic over port and parameter counts, keyed by the description, so telling a registry
+        // about a type it already knows costs nothing.
+        for (const record of fragment.nodes) {
+            this.visualRegistry.generate(record.description);
+        }
+
+        const creates = fragment.nodes.map(record => new NodeCreateAction(
+            graph,
+            visual,
+            this.visualRegistry,
+            record.description,
+            record.x + offset_x,
+            record.y + offset_y,
+            // cloned again on the way out: one fragment pasted twice must not hand both copies the
+            // same parameter objects, nor either of them the clipboard's
+            structuredClone(record.parameters)
+        ));
+
+        this.actionProcessor.mark(label);
+
+        await this.actionProcessor.doMany(creates);
+
+        const nodes = creates.map(create => create.node);
+
+        const wires = fragment.connections.map(wire => new ConnectionCreateAction(
+            graph,
+            nodes[wire.from].id,
+            wire.fromPort,
+            nodes[wire.to].id,
+            wire.toPort
+        ));
+
+        // `mark` has not been called again, so this joins the same step
+        wires.push(new SelectionSetAction(this.selection, nodes.map(node => node.id), []));
+
+        await this.actionProcessor.doMany(wires);
+
+        return nodes;
     }
 
     cameraContainAll() {