@woosh/meep-engine 3.16.0 → 3.17.1

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

@@ -0,0 +1,231 @@
+/**
+ * Nodes lifted out of a graph, waiting to be put back into one.
+ *
+ * ## Why a fragment rather than a graph
+ *
+ * What is copied cannot be node ids: ids are pooled, so the ones a fragment was cut from are handed
+ * to unrelated nodes the moment the originals are deleted, and a paste that named them would wire
+ * itself to whatever happened to be holding them. A fragment therefore refers to its own nodes by
+ * **index**, and is a thing in its own right rather than a view onto the graph it came from.
+ *
+ * Nor can it be a live {@link NodeInstance}: the instance would keep pointing at the graph it is in,
+ * and its parameters would be shared with it — an author editing the original after copying it would
+ * be editing what they had copied. Parameters are cloned on the way in for the same reason a group
+ * clones its body on the way out.
+ *
+ * A {@link NodeDescription}, on the other hand, *is* carried by reference. A description is a type,
+ * shared by every instance of it, and there is nothing to copy; it is also the one part of a node
+ * that cannot be written down — a particle node's description carries the closure that is the whole
+ * of what the node does. Which is why this clipboard is an object in the page rather than text on
+ * the system one: what it holds is only meaningful to a canvas that shares its node library.
+ *
+ * ## Who holds one
+ *
+ * A host with several canvases over one document — the particle editor's two phases, and the body of
+ * every group opened inside them — builds one of these and gives it to all of them, so a copy in one
+ * pastes in the next. A canvas built without one gets its own, and copies to itself.
+ */
+
+/**
+ * One node in a fragment.
+ *
+ * @typedef {object} NodeGraphFragmentNode
+ * @property {NodeDescription} description the type, by reference
+ * @property {object} parameters a deep copy, shared with nothing
+ * @property {number} x graph-space position it was copied from
+ * @property {number} y graph-space position it was copied from
+ */
+
+/**
+ * One wire in a fragment, between two of its own nodes.
+ *
+ * @typedef {object} NodeGraphFragmentConnection
+ * @property {number} from index into the fragment's nodes
+ * @property {number} fromPort port id on that node's description
+ * @property {number} to index into the fragment's nodes
+ * @property {number} toPort port id on that node's description
+ */
+
+/**
+ * @typedef {object} NodeGraphFragment
+ * @property {NodeGraphFragmentNode[]} nodes never empty — a fragment with no nodes is `null`
+ * @property {NodeGraphFragmentConnection[]} connections
+ */
+
+/**
+ * How far each repeat paste of the same content steps, in graph-space units.
+ *
+ * Enough to see the copy is a second thing rather than a redraw of the first, and small enough that
+ * it lands next to what it came from rather than somewhere else entirely.
+ *
+ * @type {number}
+ */
+export const NODE_GRAPH_PASTE_STEP = 32;
+
+/**
+ * What was copied, and how many times it has been put down since.
+ */
+export class NodeGraphClipboard {
+    /**
+     * @type {NodeGraphFragment|null}
+     */
+    #fragment = null;
+
+    /**
+     * @type {number}
+     */
+    #pastes = 0;
+
+    /**
+     * How many times what is held has been pasted already.
+     *
+     * A paste lands in the middle of what the author is looking at, so a second one would land
+     * exactly on top of the first and read as nothing having happened. The count is what steps it
+     * aside; see {@link NODE_GRAPH_PASTE_STEP}.
+     *
+     * @returns {number}
+     */
+    get pastes() {
+        return this.#pastes;
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    isEmpty() {
+        return this.#fragment === null;
+    }
+
+    /**
+     * @returns {NodeGraphFragment|null}
+     */
+    read() {
+        return this.#fragment;
+    }
+
+    /**
+     * Replace what is held. New content starts its paste count over, because the first paste of
+     * something new belongs where the author is looking rather than however far the last thing had
+     * walked.
+     *
+     * @param {NodeGraphFragment} fragment
+     */
+    write(fragment) {
+        this.#fragment = fragment;
+        this.#pastes = 0;
+    }
+
+    /**
+     * Record that what is held has been put down. Called by whoever is pasting it, once the paste is
+     * going ahead — a paste a canvas refused must not move the next one aside.
+     */
+    notePaste() {
+        this.#pastes++;
+    }
+
+    clear() {
+        this.#fragment = null;
+        this.#pastes = 0;
+    }
+}
+
+/**
+ * Take a copy of some of a graph.
+ *
+ * The wires that come along are the ones the fragment holds whole — both ends among the copied
+ * nodes. A wire with one end outside cannot be brought back: the node it reached is not part of
+ * what was copied, and a paste elsewhere in the graph, or in another graph entirely, has nothing to
+ * attach it to.
+ *
+ * @param {object} params
+ * @param {NodeGraph} params.graph
+ * @param {NodeGraphVisualData} [params.visual] where the nodes are; without it, everything is at the
+ *        origin and a paste arranges nothing
+ * @param {Iterable<number>} params.nodes ids to copy; ones that are not in the graph are skipped
+ * @param {function(NodeInstance):boolean} [params.copyable] whether a node may be had a second of.
+ *        Everything, by default. A host with node types that exist once per graph — a group body's
+ *        two boundary blocks — says so here, and they are left out rather than the whole copy being
+ *        refused.
+ * @returns {NodeGraphFragment|null} `null` when nothing was copied, so that a copy of nothing can be
+ *          told from a copy of something and left to leave the clipboard alone
+ */
+export function node_graph_fragment_from_nodes({ graph, visual, nodes, copyable = () => true }) {
+    /** @type {Map<number, number>} node id -> its index in the fragment */
+    const index = new Map();
+
+    /** @type {NodeGraphFragmentNode[]} */
+    const records = [];
+
+    for (const id of nodes) {
+        if (index.has(id)) {
+            // a selection should not hold one node twice, and a fragment must not whatever it does
+            continue;
+        }
+
+        const node = graph.getNode(id);
+
+        if (node === undefined || !copyable(node)) {
+            continue;
+        }
+
+        const placed = visual === undefined ? undefined : visual.getNode(id);
+
+        index.set(id, records.length);
+
+        records.push({
+            description: node.description,
+            // deeply: a copy must not share so much as a gradient stop with what it was copied from
+            parameters: structuredClone(node.parameters),
+            x: placed?.dimensions.position.x ?? 0,
+            y: placed?.dimensions.position.y ?? 0,
+        });
+    }
+
+    if (records.length === 0) {
+        return null;
+    }
+
+    /** @type {NodeGraphFragmentConnection[]} */
+    const connections = [];
+
+    graph.traverseConnections(connection => {
+        const from = index.get(connection.source.instance.id);
+        const to = index.get(connection.target.instance.id);
+
+        if (from === undefined || to === undefined) {
+            return;
+        }
+
+        connections.push({
+            from,
+            fromPort: connection.source.port.id,
+            to,
+            toPort: connection.target.port.id,
+        });
+    });
+
+    return { nodes: records, connections };
+}
+
+/**
+ * The middle of a fragment, in the graph space it was copied from.
+ *
+ * What a paste puts where the author is looking, so that what lands is centred on the view rather
+ * than hanging off one corner of it.
+ *
+ * @param {NodeGraphFragment} fragment
+ * @returns {{x: number, y: number}}
+ */
+export function node_graph_fragment_centre(fragment) {
+    let x = 0;
+    let y = 0;
+
+    for (const node of fragment.nodes) {
+        x += node.x;
+        y += node.y;
+    }
+
+    const count = fragment.nodes.length;
+
+    return count === 0 ? { x: 0, y: 0 } : { x: x / count, y: y / count };
+}

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

@@ -28,8 +28,14 @@ export class NodeGraphEditorView extends View {
      *        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, parameterViewFactory, portDataType, minimap, library, readOnly }: NodeGraph);
+    constructor({ graph, nodeRegistry, visual, camera, actions, actionProcessor, parameterViewFactory, portDataType, minimap, library, readOnly, clipboard, copyable }: NodeGraph);
     /**
      * @readonly
      */
@@ -43,6 +49,17 @@ export class NodeGraphEditorView extends View {
      * @type {ActionProcessor}
      */
     actionProcessor: ActionProcessor<any, any>;
+    /**
+     * What a copy is written to and a paste read from. Shared with the host's other canvases
+     * when it supplied one.
+     *
+     * @type {NodeGraphClipboard}
+     */
+    clipboard: NodeGraphClipboard;
+    /**
+     * @type {function(NodeInstance):boolean}
+     */
+    copyable: (arg0: NodeInstance) => boolean;
     /**
      *
      * @type {NodeGraphSelection}
@@ -181,11 +198,52 @@ export class NodeGraphEditorView extends View {
      *          queues, so nothing has been removed on return
      */
     deleteSelection(): Promise<any>;
+    /**
+     * 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(): boolean;
+    /**
+     * 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
+     */
+    paste(): Promise<NodeInstance[]>;
+    /**
+     * 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
+     */
+    duplicateSelection(): Promise<NodeInstance[]>;
     cameraContainAll(): void;
     #private;
 }
 import View from "../../../src/view/View.js";
 import { ActionProcessor } from "../../../src/core/process/undo/ActionProcessor.js";
+import { NodeGraphClipboard } from "./NodeGraphClipboard.js";
 import { NodeGraphSelection } from "./NodeGraphSelection.js";
 import { NodeGraphCamera } from "./NodeGraphView.js";
 import { NodeDescriptionVisualRegistry } from "../../../src/core/model/node-graph/visual/NodeDescriptionVisualRegistry.js";

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":"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"}
+{"version":3,"file":"NodeGraphEditorView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphEditorView.js"],"names":[],"mappings":"AAmDA;IAyBI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,+KAiSC;IA7VD;;OAEG;IACH,iBAWE;IA+DE;;OAEG;IACH,UAFU,OAAO,CAEO;IAExB;;;OAGG;IACH,2CAAsC;IAEtC;;;;;OAKG;IACH,WAFU,kBAAkB,CAEF;IAE1B;;OAEG;IACH,kCAFiC,OAAO,CAEA;IAExC;;;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;IA4H1B;;;;;;;;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,CAwBjC;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;;;;;;;;;OASG;IACH,iBAJa,OAAO,CAmBnB;IAED;;;;;;;;;;;;;;OAcG;IACH,SAJa,QAAQ,cAAc,CAAC,CAiCnC;IAED;;;;;;;;;;;OAWG;IACH,sBAJa,QAAQ,cAAc,CAAC,CAqBnC;IA+DD,yBAuDC;;CACJ;iBAz1BgB,2BAA2B;gCAHZ,mDAAmD;mCA4B5E,yBAAyB;mCArBG,yBAAyB;gCAFb,oBAAoB;8CAS5D,4EAA4E;8BATpC,oBAAoB;qCAC9B,2BAA2B;wCAexB,8BAA8B;oBALlD,mCAAmC"}

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

@@ -21,8 +21,15 @@ 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 { 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
@@ -96,6 +103,12 @@ export class NodeGraphEditorView extends View {
      *        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,
@@ -108,7 +121,9 @@ export class NodeGraphEditorView extends View {
                     portDataType = undefined,
                     minimap = true,
                     library = undefined,
-                    readOnly = false
+                    readOnly = false,
+                    clipboard = new NodeGraphClipboard(),
+                    copyable = undefined
                 }) {
         super();
 
@@ -123,6 +138,19 @@ export class NodeGraphEditorView extends View {
          */
         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}
@@ -230,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));
             }
         });
 
@@ -419,12 +496,13 @@ export class NodeGraphEditorView extends View {
         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(
+        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
+            outgoing ? port.id : endpoint.port.id,
+            this.visual
         ));
 
         return node;
@@ -562,6 +640,171 @@ export class NodeGraphEditorView extends View {
         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() {
         /**
          *

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

@@ -1 +1 @@
-{"version":3,"file":"NodeGraphView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphView.js"],"names":[],"mappings":";AAyGA;IA4GI;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gJA8cC;IA7kBD,mBAAmC;IAEnC;;;;;;;;;OASG;IACH,oBAFU,IAAI,MAAM,EAAE,QAAQ,CAAC,CAET;IAmBtB;;;OAGG;IACH,qBAFmB,yBAAyB,cAE/B;IAEb;;OAEG;IACH,iBA0DE;IAEF;;;;OAIG;IACH,mBAFU,OAAO,CAEA;IAmCb;;;OAGG;IACH,2CAAsC;IAMtC;;;OAGG;IACH,QAFU,eAAe,CAEL;IAEpB;;;OAGG;IACH,iBAAkB;IAElB;;;OAGG;IACH,4BAAoB;IAEpB;;;OAGG;IACH,WAFU,kBAAkB,CAEF;IAma9B;;;;;;;;;OASG;IACH,oBAFa,IAAI,CAgBhB;IAED;;;;;;;;OAQG;IACH,gBAFa,IAAI,CAMhB;IAED;;;;;;;;OAQG;IACH,cAFa,OAAO,CAInB;IAgBD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gCAFa,IAAI,CA+NhB;IAED;;;;;;;;OAQG;IACH,0BAHW,KAAK,GACH,MAAM,EAAE,CAwBpB;IAED;;;;;;;;;;;OAWG;IACH,gCAHW,KAAK,GACH,MAAM,EAAE,CAsBpB;IAED;;;;;;;;;;OAUG;IACH,6BAJW,KAAK,SACL,UAAU,GAAC,YAAY,GACrB,IAAI,CAgDhB;IAED;;;;OAIG;IACH,wBAHW,OAAO,GACL,aAAW,IAAI,CAiC3B;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,GAAC,IAAI,gBACX,MAAM,GAAC,IAAI,SACX,UAAU,GAAC,YAAY,QA8CjC;IAGD;;;;;;;OAOG;IACH,wDAFa,OAAO,CAcnB;IAED;;;;;;;;;OASG;IACH,+CAFa,oBAAoB,CAYhC;IAED;;;;;;OAMG;IACH,oBALW,wBAAwB,QACxB,oBAAoB,iCAEpB,OAAO,QA+DjB;IAED;;;;OAIG;IACH,mCAHW,yBAAyB,UACzB,OAAO,QAiBjB;IAeD;;;;OAIG;IACH,kCAHW,OAAO,UACP,OAAO,QAIjB;IAED;;;;OAIG;IACH,kCAHW,OAAO,UACP,OAAO,QAIjB;;CACJ;iBAn3CgB,2BAA2B;yBAInB,eAAe;0CAIE,sEAAsE;gCAChF,mDAAmD;gCACnD,sBAAsB;mCACnB,yBAAyB;kBAQ1C,yCAAyC;oBAjBvC,mCAAmC;qCAgBlB,mEAAmE"}
+{"version":3,"file":"NodeGraphView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphView.js"],"names":[],"mappings":";AA0GA;IA4GI;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gJAyhBC;IAxpBD,mBAAmC;IAEnC;;;;;;;;;OASG;IACH,oBAFU,IAAI,MAAM,EAAE,QAAQ,CAAC,CAET;IAmBtB;;;OAGG;IACH,qBAFmB,yBAAyB,cAE/B;IAEb;;OAEG;IACH,iBA0DE;IAEF;;;;OAIG;IACH,mBAFU,OAAO,CAEA;IAmCb;;;OAGG;IACH,2CAAsC;IAMtC;;;OAGG;IACH,QAFU,eAAe,CAEL;IAEpB;;;OAGG;IACH,iBAAkB;IAElB;;;OAGG;IACH,4BAAoB;IAEpB;;;OAGG;IACH,WAFU,kBAAkB,CAEF;IA8e9B;;;;;;;;;OASG;IACH,oBAFa,IAAI,CAgBhB;IAED;;;;;;;;OAQG;IACH,gBAFa,IAAI,CAMhB;IAED;;;;;;;;OAQG;IACH,cAFa,OAAO,CAInB;IAgBD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gCAFa,IAAI,CA+NhB;IAED;;;;;;;;OAQG;IACH,0BAHW,KAAK,GACH,MAAM,EAAE,CAwBpB;IAED;;;;;;;;;;;OAWG;IACH,gCAHW,KAAK,GACH,MAAM,EAAE,CAsBpB;IAED;;;;;;;;;;OAUG;IACH,6BAJW,KAAK,SACL,UAAU,GAAC,YAAY,GACrB,IAAI,CAgDhB;IAED;;;;OAIG;IACH,wBAHW,OAAO,GACL,aAAW,IAAI,CAiC3B;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,GAAC,IAAI,gBACX,MAAM,GAAC,IAAI,SACX,UAAU,GAAC,YAAY,QA8CjC;IAGD;;;;;;;OAOG;IACH,wDAFa,OAAO,CAcnB;IAED;;;;;;;;;OASG;IACH,+CAFa,oBAAoB,CAYhC;IAED;;;;;;OAMG;IACH,oBALW,wBAAwB,QACxB,oBAAoB,iCAEpB,OAAO,QA+DjB;IAED;;;;OAIG;IACH,mCAHW,yBAAyB,UACzB,OAAO,QAiBjB;IAeD;;;;OAIG;IACH,kCAHW,OAAO,UACP,OAAO,QAIjB;IAED;;;;OAIG;IACH,kCAHW,OAAO,UACP,OAAO,QAIjB;;CACJ;iBA/7CgB,2BAA2B;yBAInB,eAAe;0CAIE,sEAAsE;gCAChF,mDAAmD;gCACnD,sBAAsB;mCACnB,yBAAyB;kBAS1C,yCAAyC;oBAlBvC,mCAAmC;qCAiBlB,mEAAmE"}