@woosh/meep-engine 3.16.0 → 3.17.0

package/editor/particles/effect/ParticleEffectDocument.d.ts

@@ -28,8 +28,14 @@ export type PARTICLE_EFFECT_SOURCE = string;
  * ## Optimizing
  *
  * {@link optimize} runs the compiled program through
- * {@link ../../../src/shade/renderer/particles/optimizer/optimize_particle_program.js the optimizer}
- * before anybody gets it. It is a property of the effect rather than of a view because it changes
+ * {@link ../../../src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js the graph optimizer}
+ * before anybody gets it.
+ *
+ * There are two optimizers and they take the same arguments, so which one an editor runs is a choice
+ * rather than a rewrite. It is this one because it is both better and very much faster: on `curl4`
+ * the pass pipeline needs 3,690 ms against this one's 276, and comes out with 2,828 instructions
+ * against 2,826. A second-and-a-half of that difference is the pipeline running itself twice to
+ * decide about lane peeling. At 3.7 seconds an edit the setting could not be on at all. It is a property of the effect rather than of a view because it changes
  * what runs — the preview, the reference simulation and anything else downstream of {@link compile}
  * all get the optimized program — and a switch that changed what runs while living in one panel
  * would be invisible from the other three.
@@ -130,8 +136,17 @@ export class ParticleEffectDocument {
     /**
      * Whether {@link compile} hands back the optimized program.
      *
-     * Off by default, and off for every effect saved before it existed, because it is a thing an
-     * author turns on to see what it does rather than something done to their effect behind them.
+     * ON by default. It was off while it was new — a thing an author turned on to see what it did —
+     * and what changes that is not confidence but the promise being checkable: a program's meaning
+     * is its final record, its kill flag and its RNG state, and the optimizer is held to leaving all
+     * three identical to the bit over every environment the differential harness runs. An author who
+     * cannot observe the difference should not have to ask for it.
+     *
+     * The one rewrite that is not bit-exact — folding `x * 0`, which gives up the sign of that zero
+     * — is argued where it lives and is on there, not here. A tick-box in the editor is not the
+     * place to quietly widen what the optimizer may do; see {@link #optimized}.
+     *
+     * Turning it OFF still works and is what an author debugging a lowering wants, so the box stays.
      *
      * @type {boolean}
      */
@@ -331,11 +346,11 @@ export class ParticleEffectDocument {
      * on, because `bind_render` throws on one — and an effect that fails to build over a stale
      * binding is a worse thing to hand an author than one that draws without a colour.
      *
-     * @param {{layout: ParticleLayout, program: object}} effect what {@link compile} produced,
+     * @param {{layout: ParticleLayout, program: object}} compiled what {@link compile} produced,
      *   packaged the way `create_particle_effect` does
      * @returns {object}
      */
-    emitterConfig(effect: {
+    emitterConfig({ layout, program }: {
         layout: ParticleLayout;
         program: object;
     }): object;

package/editor/particles/effect/ParticleEffectDocument.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleEffectDocument.d.ts","sourceRoot":"","sources":["../../../../editor/particles/effect/ParticleEffectDocument.js"],"names":[],"mappings":";;;qCAyEU,MAAM;AAvChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;GAGG;AACH;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH;IAEI;;OAEG;IACH,MAFU,MAAM,CAEA;IAEhB;;;;;;;;OAQG;IACH,YAFU,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAShE;IAEF;;;;;;;;;OASG;IACH,QAFU,OAAO,kEAAkE,EAAE,iBAAiB,EAAE,CAE5F;IAEZ;;OAEG;IACH,MAFU,SAAS,CAEI;IAEvB;;OAEG;IACH,QAFU,SAAS,CAEM;IAEzB;;;;OAIG;IACH,aAFU,mBAAmB,CAEW;IAExC;;OAEG;IACH,eAFU,mBAAmB,CAEa;IAE1C;;;;OAIG;IACH,SAFU,MAAM,CAoBd;IAEF;;;OAGG;IACH,QAFU,MAAM,CAEsB;IAEtC;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;;;OAOG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;OAIG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH;QACI;;;;WAIG;;MAEL;IAkGF;;;;;;OAMG;IACH,cASC;IAED;;;;;;;;;;;;;OAaG;IACH,2BAcC;IAED;;;;;;;;OAQG;IACH,qBAHW,MAAM,GACJ,OAAO,wEAAwE,EAAE,uBAAuB,GAAC,SAAS,CAI9H;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,OAAO,kEAAkE,EAAE,iBAAiB,GAAC,SAAS,CAIlH;IAED;;;;;;;;;OASG;IACH,yBAHW,MAAM,GACJ,MAAM,CAalB;IAED;;;;;;OAMG;IACH,gBAJW,OAAO,kEAAkE,EAAE,iBAAiB,GAC1F,IAAI,CAWhB;IAED;;;;;;;;;OASG;IACH,mBAHW,OAAO,kEAAkE,EAAE,iBAAiB,GAC1F,OAAO,CAcnB;IAED;;;;;;;;OAQG;IACH,eAHa,cAAc,CAK1B;IAED;;;;;;;;;;;;OAYG;IACH,WAFa,yBAAyB,CAcrC;IAmLD;;;;;;;;;;OAUG;IACH,0BAJW,cAAc,GAEZ,yBAAyB,CAAC,aAAa,CAAC,CAgBpD;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,mBAHa,yBAAyB,CAsBrC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,2BAHW,yBAAyB,GACvB,MAAM,CAclB;IAED;;;OAGG;IACH,kBAQC;IAED;;;;OAIG;IACH,qBAFW,OAAO,QAUjB;IAED;;;;;;;;OAQG;IACH,mBANW,MAAM,cACN,MAAM,SACN,MAAM,QAchB;IAED;;;;;;;;OAQG;IACH,sBAHW,MAAM,GACJ,OAAO,CAoBnB;IAED;;;;;;;;;;OAUG;IACH,sBAJW;QAAC,MAAM,EAAE,cAAc,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,GAEvC,MAAM,CAiClB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAWlB;IAED;;OAEG;IACH,UAFa,MAAM,CAclB;IAED;;;;;;;OAOG;IACH,eALW,MAAM,kDAGJ,sBAAsB,CAKlC;;CAyDJ;;;;;;;;aAx4Ba,OAAO,8DAA8D,EAAE,eAAe,GAAC,IAAI;;;;;YAE3F,cAAc,GAAC,IAAI;;;;;;iBAEnB,OAAO,8DAA8D,EAAE,eAAe,GAAC,IAAI;;;;;iBAI3F,MAAM;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC;;0BA5FzE,iDAAiD;oCACvC,kEAAkE;+BA6BvE,gEAAgE"}
+{"version":3,"file":"ParticleEffectDocument.d.ts","sourceRoot":"","sources":["../../../../editor/particles/effect/ParticleEffectDocument.js"],"names":[],"mappings":";;;qCA+EU,MAAM;AA7ChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;GAGG;AACH;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH;IAEI;;OAEG;IACH,MAFU,MAAM,CAEA;IAEhB;;;;;;;;OAQG;IACH,YAFU,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAShE;IAEF;;;;;;;;;OASG;IACH,QAFU,OAAO,kEAAkE,EAAE,iBAAiB,EAAE,CAE5F;IAEZ;;OAEG;IACH,MAFU,SAAS,CAEI;IAEvB;;OAEG;IACH,QAFU,SAAS,CAEM;IAEzB;;;;OAIG;IACH,aAFU,mBAAmB,CAEW;IAExC;;OAEG;IACH,eAFU,mBAAmB,CAEa;IAE1C;;;;OAIG;IACH,SAFU,MAAM,CAqBd;IAEF;;;OAGG;IACH,QAFU,MAAM,CAEsB;IAEtC;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;;;;;;;;;;;;OAgBG;IACH,UAFU,OAAO,CAED;IAEhB;;;;OAIG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH;QACI;;;;WAIG;;MAEL;IAkGF;;;;;;OAMG;IACH,cASC;IAED;;;;;;;;;;;;;OAaG;IACH,2BAcC;IAED;;;;;;;;OAQG;IACH,qBAHW,MAAM,GACJ,OAAO,wEAAwE,EAAE,uBAAuB,GAAC,SAAS,CAI9H;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,OAAO,kEAAkE,EAAE,iBAAiB,GAAC,SAAS,CAIlH;IAED;;;;;;;;;OASG;IACH,yBAHW,MAAM,GACJ,MAAM,CAalB;IAED;;;;;;OAMG;IACH,gBAJW,OAAO,kEAAkE,EAAE,iBAAiB,GAC1F,IAAI,CAWhB;IAED;;;;;;;;;OASG;IACH,mBAHW,OAAO,kEAAkE,EAAE,iBAAiB,GAC1F,OAAO,CAcnB;IAED;;;;;;;;OAQG;IACH,eAHa,cAAc,CAK1B;IAED;;;;;;;;;;;;OAYG;IACH,WAFa,yBAAyB,CAcrC;IAmLD;;;;;;;;;;OAUG;IACH,0BAJW,cAAc,GAEZ,yBAAyB,CAAC,aAAa,CAAC,CAgBpD;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,mBAHa,yBAAyB,CAsBrC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,2BAHW,yBAAyB,GACvB,MAAM,CAclB;IAED;;;OAGG;IACH,kBAQC;IAED;;;;OAIG;IACH,qBAFW,OAAO,QAUjB;IAED;;;;;;;;OAQG;IACH,mBANW,MAAM,cACN,MAAM,SACN,MAAM,QAchB;IAED;;;;;;;;OAQG;IACH,sBAHW,MAAM,GACJ,OAAO,CAoBnB;IAED;;;;;;;;;;OAUG;IACH,mCAJW;QAAC,MAAM,EAAE,cAAc,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,GAEvC,MAAM,CAkClB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAWlB;IAED;;OAEG;IACH,UAFa,MAAM,CAclB;IAED;;;;;;;OAOG;IACH,eALW,MAAM,kDAGJ,sBAAsB,CAKlC;;CA6DJ;;;;;;;;aAv5Ba,OAAO,8DAA8D,EAAE,eAAe,GAAC,IAAI;;;;;YAE3F,cAAc,GAAC,IAAI;;;;;;iBAEnB,OAAO,8DAA8D,EAAE,eAAe,GAAC,IAAI;;;;;iBAI3F,MAAM;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC;;0BAlGzE,iDAAiD;oCACvC,kEAAkE;+BA6BvE,gEAAgE"}

package/editor/particles/effect/ParticleEffectDocument.js

@@ -29,7 +29,7 @@ import {
 } from "../../../src/shade/renderer/particles/isa/particle_assembly.js";
 import { PARTICLE_TYPE_COLOR } from "../../../src/shade/renderer/particles/graph/ParticleValueType.js";
 import { ParticleLayout } from "../../../src/shade/renderer/particles/layout/ParticleLayout.js";
-import { optimize_compiled_particle_program } from "../../../src/shade/renderer/particles/optimizer/optimize_particle_program.js";
+import { optimize_particle_program_vector } from "../../../src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js";
 import { EMITTER_RENDER_CHANNELS } from "../../../src/shade/renderer/particles/runtime/ParticleEmitter.js";
 
 /**
@@ -58,8 +58,14 @@ import { EMITTER_RENDER_CHANNELS } from "../../../src/shade/renderer/particles/r
  * ## Optimizing
  *
  * {@link optimize} runs the compiled program through
- * {@link ../../../src/shade/renderer/particles/optimizer/optimize_particle_program.js the optimizer}
- * before anybody gets it. It is a property of the effect rather than of a view because it changes
+ * {@link ../../../src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js the graph optimizer}
+ * before anybody gets it.
+ *
+ * There are two optimizers and they take the same arguments, so which one an editor runs is a choice
+ * rather than a rewrite. It is this one because it is both better and very much faster: on `curl4`
+ * the pass pipeline needs 3,690 ms against this one's 276, and comes out with 2,828 instructions
+ * against 2,826. A second-and-a-half of that difference is the pipeline running itself twice to
+ * decide about lane peeling. At 3.7 seconds an edit the setting could not be on at all. It is a property of the effect rather than of a view because it changes
  * what runs — the preview, the reference simulation and anything else downstream of {@link compile}
  * all get the optimized program — and a switch that changed what runs while living in one panel
  * would be invisible from the other three.
@@ -169,7 +175,8 @@ export class ParticleEffectDocument {
         cull: false,
         bounds_center: [0, 1, 0],
         bounds_radius: 3,
-        atlas_region: [0, 0, 1, 1],
+        /** image to draw with, by URL; null draws against the default atlas, a white texel */
+        texture: null,
         flipbook: [1, 1],
         /** render channel -> attribute name; a channel absent here is not bound */
         render: {
@@ -195,12 +202,21 @@ export class ParticleEffectDocument {
     /**
      * Whether {@link compile} hands back the optimized program.
      *
-     * Off by default, and off for every effect saved before it existed, because it is a thing an
-     * author turns on to see what it does rather than something done to their effect behind them.
+     * ON by default. It was off while it was new — a thing an author turned on to see what it did —
+     * and what changes that is not confidence but the promise being checkable: a program's meaning
+     * is its final record, its kill flag and its RNG state, and the optimizer is held to leaving all
+     * three identical to the bit over every environment the differential harness runs. An author who
+     * cannot observe the difference should not have to ask for it.
+     *
+     * The one rewrite that is not bit-exact — folding `x * 0`, which gives up the sign of that zero
+     * — is argued where it lives and is on there, not here. A tick-box in the editor is not the
+     * place to quietly widen what the optimizer may do; see {@link #optimized}.
+     *
+     * Turning it OFF still works and is what an author debugging a lowering wants, so the box stays.
      *
      * @type {boolean}
      */
-    optimize = false;
+    optimize = true;
 
     /**
      * Bumped on every {@link touch}. A view that caches something derived from the document can
@@ -250,7 +266,7 @@ export class ParticleEffectDocument {
      * A change to a document is seen by three panels and each of them asks what it compiles to, so
      * without this one edit is three compiles. That was affordable when an effect was forty
      * instructions; a graph with a `curl3` group in it lowers to about four thousand, which is 78ms
-     * to compile and another 570ms to optimize on this machine — three times over, on every
+     * to compile and another 214ms to optimize on this machine — three times over, on every
      * keystroke.
      *
      * The key is the {@link version} and the two settings that decide what a compile does, rather
@@ -554,7 +570,7 @@ export class ParticleEffectDocument {
         }
 
         try {
-            return { program: optimize_compiled_particle_program(program), unoptimized: program };
+            return { program: optimize_particle_program_vector(program), unoptimized: program };
         } catch (e) {
             diagnostics.push({
                 scope: "effect",
@@ -849,23 +865,24 @@ export class ParticleEffectDocument {
      * on, because `bind_render` throws on one — and an effect that fails to build over a stale
      * binding is a worse thing to hand an author than one that draws without a colour.
      *
-     * @param {{layout: ParticleLayout, program: object}} effect what {@link compile} produced,
+     * @param {{layout: ParticleLayout, program: object}} compiled what {@link compile} produced,
      *   packaged the way `create_particle_effect` does
      * @returns {object}
      */
-    emitterConfig(effect) {
+    emitterConfig({ layout, program }) {
         const render = {};
 
         for (const channel of EMITTER_RENDER_CHANNELS) {
             const attribute = this.emitter.render[channel];
 
-            if (attribute !== undefined && effect.layout.has(attribute)) {
+            if (attribute !== undefined && layout.has(attribute)) {
                 render[channel] = attribute;
             }
         }
 
         return {
-            effect,
+            layout,
+            program,
             name: this.name,
             spawn_rate: this.emitter.spawn_rate,
             flags: {
@@ -880,7 +897,7 @@ export class ParticleEffectDocument {
                 center: this.emitter.bounds_center,
                 radius: this.emitter.bounds_radius,
             },
-            atlas_region: this.emitter.atlas_region,
+            texture: this.emitter.texture,
             flipbook: this.emitter.flipbook,
             render,
         };
@@ -978,9 +995,13 @@ export class ParticleEffectDocument {
             : PARTICLE_EFFECT_SOURCE.GRAPH;
         this.assembly = json.assembly ?? "";
 
-        // absent reads as off, so an effect saved before the optimizer existed opens as the program
-        // its author last saw
-        this.optimize = json.optimize === true;
+        // Absent reads as ON, which is the default this document is constructed with. An effect
+        // saved before the setting existed therefore opens optimized — which is a change to what
+        // runs for that author, and the reason it is safe is the reason the default moved: the
+        // optimizer leaves the record, the kill flag and the RNG state identical to the bit. What is
+        // stored is a departure from the default in either direction, so an author who turned it off
+        // still gets it off.
+        this.optimize = json.optimize !== false;
 
         this.touch();
 

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

@@ -0,0 +1,186 @@
+/**
+ * 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 }: {
+    graph: NodeGraph;
+    visual?: NodeGraphVisualData;
+    nodes: Iterable<number>;
+    copyable?: (arg0: NodeInstance) => boolean;
+}): NodeGraphFragment | null;
+/**
+ * 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: NodeGraphFragment): {
+    x: number;
+    y: number;
+};
+/**
+ * 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: number;
+/**
+ * What was copied, and how many times it has been put down since.
+ */
+export class NodeGraphClipboard {
+    /**
+     * 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(): number;
+    /**
+     * @returns {boolean}
+     */
+    isEmpty(): boolean;
+    /**
+     * @returns {NodeGraphFragment|null}
+     */
+    read(): NodeGraphFragment | null;
+    /**
+     * 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: NodeGraphFragment): void;
+    /**
+     * 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(): void;
+    clear(): void;
+    #private;
+}
+/**
+ * One node in a fragment.
+ */
+export type NodeGraphFragmentNode = {
+    /**
+     * the type, by reference
+     */
+    description: NodeDescription;
+    /**
+     * a deep copy, shared with nothing
+     */
+    parameters: object;
+    /**
+     * graph-space position it was copied from
+     */
+    x: number;
+    /**
+     * graph-space position it was copied from
+     */
+    y: number;
+};
+/**
+ * One wire in a fragment, between two of its own nodes.
+ */
+export type NodeGraphFragmentConnection = {
+    /**
+     * index into the fragment's nodes
+     */
+    from: number;
+    /**
+     * port id on that node's description
+     */
+    fromPort: number;
+    /**
+     * index into the fragment's nodes
+     */
+    to: number;
+    /**
+     * port id on that node's description
+     */
+    toPort: number;
+};
+export type NodeGraphFragment = {
+    /**
+     * never empty — a fragment with no nodes is `null`
+     */
+    nodes: NodeGraphFragmentNode[];
+    connections: NodeGraphFragmentConnection[];
+};
+//# sourceMappingURL=NodeGraphClipboard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphClipboard.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphClipboard.js"],"names":[],"mappings":"AAmIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAX6B,KAAK;IACM,MAAM;IAEV,KAAK,EAA9B,SAAS,MAAM,CAAC;IACwB,QAAQ,2BAAzB,OAAO;IAI5B,iBAAiB,GAAC,IAAI,CA2DlC;AAED;;;;;;;;GAQG;AACH,qDAHW,iBAAiB;OACX,MAAM;OAAK,MAAM;EAcjC;AAtOD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AAEH;;;;GAIG;AAEH;;;;;;;GAOG;AACH,oCAFU,MAAM,CAEwB;AAExC;;GAEG;AACH;IAWI;;;;;;;;OAQG;IACH,qBAEC;IAED;;OAEG;IACH,WAFa,OAAO,CAInB;IAED;;OAEG;IACH,QAFa,iBAAiB,GAAC,IAAI,CAIlC;IAED;;;;;;OAMG;IACH,gBAFW,iBAAiB,QAK3B;IAED;;;OAGG;IACH,kBAEC;IAED,cAGC;;CACJ;;;;;;;;;;;;gBAhGa,MAAM;;;;OACN,MAAM;;;;OACN,MAAM;;;;;;;;;UAON,MAAM;;;;cACN,MAAM;;;;QACN,MAAM;;;;YACN,MAAM;;;;;;WAKN,qBAAqB,EAAE;iBACvB,2BAA2B,EAAE"}

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 };
+}