@woosh/meep-engine 3.15.0 → 3.17.0

package/src/core/binary/allocator/OffsetAllocator.js

@@ -47,7 +47,16 @@ const NODE_FIELD_NEIGHBOR_PREV = 4;
 const NODE_FIELD_NEIGHBOR_NEXT = 5;
 const NODE_FIELD_FLAGS = 6;
 
-class Allocation {
+/**
+ * One range handed out by {@link OffsetAllocator#allocate}: where it starts, plus the allocator's
+ * own handle on it. A caller keeps the whole object to give back to {@link OffsetAllocator#free},
+ * or keeps {@link Allocation#metadata} alone and releases it through
+ * {@link OffsetAllocator#free_node}.
+ *
+ * An {@link Allocation} whose `offset` is {@link ALLOCATOR_NO_SPACE} is a failed allocation, not a
+ * range at offset zero — the allocator is out of space, or out of nodes to describe one with.
+ */
+export class Allocation {
     offset = ALLOCATOR_NO_SPACE;
     metadata = ALLOCATOR_NO_SPACE;
 

package/src/core/collection/array/typed/float32_array_hash.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hash of a float32 range, in the terms `===` compares floats in — the counterpart to
+ * {@link uint32_array_hash} for arrays that hold values rather than words.
+ *
+ * The hash reads each element's raw IEEE-754 word, because a float carries distinctions no
+ * integer conversion keeps: `0.5` and `0.25` are different weights and truncate to the same
+ * integer. The one place where the bits say more than the value does is the sign of a zero, and
+ * there the bits are wrong for this purpose: `-0 === +0`, so anything hashing them apart would
+ * disagree with the equality it is meant to accompany. The zero is folded onto `+0`, and every
+ * other value keeps its exact bit pattern.
+ *
+ * A NaN hashes by its bits and so hashes equal to itself, which `===` does not — that direction
+ * is free, as unequal values are always allowed to collide.
+ *
+ * @param {Float32Array} array
+ * @param {number} offset first index to hash
+ * @param {number} length index to stop before, matching {@link uint32_array_hash}
+ * @return {number}
+ */
+export function float32_array_hash(array: Float32Array, offset: number, length: number): number;
+//# sourceMappingURL=float32_array_hash.d.ts.map

package/src/core/collection/array/typed/float32_array_hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"float32_array_hash.d.ts","sourceRoot":"","sources":["../../../../../../src/core/collection/array/typed/float32_array_hash.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,0CALW,YAAY,UACZ,MAAM,UACN,MAAM,GACL,MAAM,CAoBjB"}

package/src/core/collection/array/typed/float32_array_hash.js

@@ -0,0 +1,38 @@
+/**
+ * Hash of a float32 range, in the terms `===` compares floats in — the counterpart to
+ * {@link uint32_array_hash} for arrays that hold values rather than words.
+ *
+ * The hash reads each element's raw IEEE-754 word, because a float carries distinctions no
+ * integer conversion keeps: `0.5` and `0.25` are different weights and truncate to the same
+ * integer. The one place where the bits say more than the value does is the sign of a zero, and
+ * there the bits are wrong for this purpose: `-0 === +0`, so anything hashing them apart would
+ * disagree with the equality it is meant to accompany. The zero is folded onto `+0`, and every
+ * other value keeps its exact bit pattern.
+ *
+ * A NaN hashes by its bits and so hashes equal to itself, which `===` does not — that direction
+ * is free, as unequal values are always allowed to collide.
+ *
+ * @param {Float32Array} array
+ * @param {number} offset first index to hash
+ * @param {number} length index to stop before, matching {@link uint32_array_hash}
+ * @return {number}
+ */
+export function float32_array_hash(array, offset, length) {
+    // a Float32Array is 4-byte aligned by construction, so this view always exists
+    const bits = new Uint32Array(array.buffer, array.byteOffset, array.length);
+
+    let hash = length;
+
+    for (let i = offset; i < length; ++i) {
+
+        const value = array[i];
+
+        // `value === 0` is true for both zeroes and for nothing else
+        const word = value === 0 ? 0 : bits[i];
+
+        hash = ((hash << 5) - hash) + word;
+
+    }
+
+    return hash;
+}

package/src/core/geom/3d/shape/PosedShape3D.d.ts

@@ -46,6 +46,23 @@ export class PosedShape3D extends AbstractShape3D {
         z: number;
         w: number;
     }): void;
+    /**
+     * The same, from loose components.
+     *
+     * A pose does not always arrive as a pair of objects: a `Transform64` keeps its translation and
+     * rotation as numbers inside one buffer, and reading them through its view accessors would build
+     * two throwaway arrays per call, in a loop that runs per collider per step.
+     *
+     * @param {AbstractShape3D} shape
+     * @param {number} px
+     * @param {number} py
+     * @param {number} pz
+     * @param {number} qx
+     * @param {number} qy
+     * @param {number} qz
+     * @param {number} qw
+     */
+    setup_components(shape: AbstractShape3D, px: number, py: number, pz: number, qx: number, qy: number, qz: number, qw: number): void;
     compute_bounding_box(result: any): void;
     /**
      * Signed distance from a WORLD-space point to the posed shape's boundary.

package/src/core/geom/3d/shape/PosedShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CAClB;IAEb,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IAEP;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAM1D;IAyED,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;IAGL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;gCAvL+B,sBAAsB"}
+{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CAClB;IAEb,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IAEP;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAe1D;IAED;;;;;;;;;;;;;;;OAeG;IACH,wBATW,eAAe,MACf,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAMhB;IAyED,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;IAGL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;gCAtN+B,sBAAsB"}

package/src/core/geom/3d/shape/PosedShape3D.js

@@ -1,3 +1,4 @@
+import { assert } from "../../../assert.js";
 import { aabb3_transform_oriented } from "../aabb/aabb3_transform_oriented.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 
@@ -46,9 +47,40 @@ export class PosedShape3D extends AbstractShape3D {
      * @param {Quaternion|{x:number,y:number,z:number,w:number}} rotation
      */
     setup(shape, position, rotation) {
+        // An array-shaped pose - a Float64Array triple, a Transform64's translation view, a literal
+        // [x, y, z] - reads back as undefined here and quietly poses the shape at NaN, where every
+        // support query answers "no hit". Two call sites had done exactly that. Arrays go through
+        // setup_components instead, and this says so rather than silently disappearing.
+        assert.isNumber(position.x, 'position.x');
+        assert.isNumber(rotation.w, 'rotation.w');
+
+        this.setup_components(
+            shape,
+            position.x, position.y, position.z,
+            rotation.x, rotation.y, rotation.z, rotation.w
+        );
+    }
+
+    /**
+     * The same, from loose components.
+     *
+     * A pose does not always arrive as a pair of objects: a `Transform64` keeps its translation and
+     * rotation as numbers inside one buffer, and reading them through its view accessors would build
+     * two throwaway arrays per call, in a loop that runs per collider per step.
+     *
+     * @param {AbstractShape3D} shape
+     * @param {number} px
+     * @param {number} py
+     * @param {number} pz
+     * @param {number} qx
+     * @param {number} qy
+     * @param {number} qz
+     * @param {number} qw
+     */
+    setup_components(shape, px, py, pz, qx, qy, qz, qw) {
         this.shape = shape;
-        this.px = position.x; this.py = position.y; this.pz = position.z;
-        this.qx = rotation.x; this.qy = rotation.y; this.qz = rotation.z; this.qw = rotation.w;
+        this.px = px; this.py = py; this.pz = pz;
+        this.qx = qx; this.qy = qy; this.qz = qz; this.qw = qw;
     }
 
     /**

package/src/core/graph/csr/CSRGraph.d.ts

@@ -149,7 +149,14 @@ export class CSRGraph {
      */
     clone(): CSRGraph;
     /**
-     * Structural equality — same shape and same buffer contents.
+     * Structural equality — same shape and same contents.
+     *
+     * The three integer arrays compare as words. `edge_weights` compares as floats, by value: a
+     * weight is a measurement, and every consumer of it — `sum_of_edge_weights`, the distance-field
+     * and shortest-path relaxations, metis partitioning — only ever adds or compares it, so `-0` and
+     * `+0` are one weight and no graph behaves differently for holding one rather than the other.
+     * {@link CSRGraph#hash} folds them together to match.
+     *
      * @param {CSRGraph} other
      * @returns {boolean}
      */

package/src/core/graph/csr/CSRGraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CSRGraph.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/csr/CSRGraph.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAkQI;;;;;;;;;;;;;OAaG;IACH,gCAPW,MAAM,kBACN,UAAU,MAAM,CAAC,aACjB,UAAU,MAAM,CAAC,gBACjB,UAAU,MAAM,CAAC,mBACjB,UAAU,MAAM,CAAC,GACf,QAAQ,CAgBpB;IA7RD;;;;OAIG;IACH,0BAJW,MAAM,oBACN,MAAM,EAgEhB;IAzDG,qBAAqB;IACrB,cADW,MAAM,CACe;IAChC,qBAAqB;IACrB,kBADW,MAAM,CACuB;IAOxC;;;;OAIG;IACH,sBAA4D;IAI5D;;;;OAIG;IACH,gBAFU,WAAW,CAEmE;IAGxF;;;OAGG;IACH,WAFU,WAAW,CAE8D;IAGnF;;;;;OAKG;IACH,cAFU,YAAY,CAEiE;IAGvF;;;;;OAKG;IACH,gBAFU,WAAW,CAE+D;IAGpF;;;OAGG;IACH,qBAFU,MAAM,CAEuB;IAG3C;;;;OAIG;IACH,+BAEC;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,uBAFa,MAAM,CAUlB;IAED;;OAEG;IACH,oCAQC;IAED;;;;;;;;;;;;;;;OAeG;IACH,yCAFW,MAAM,QA6ChB;IAED;;;;;;;;;OASG;IACH,YAFW,QAAQ,QASlB;IAED;;;OAGG;IACH,SAFa,QAAQ,CAMpB;IAED;;;;OAIG;IACH,cAHW,QAAQ,GACN,OAAO,CAyBnB;IAED;;;;;OAKG;IACH,QAFa,MAAM,CAiBlB;IAiCL;;;;;OAKG;IACH,qBAFU,OAAO,CAEY;CAR5B"}
+{"version":3,"file":"CSRGraph.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/csr/CSRGraph.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAyQI;;;;;;;;;;;;;OAaG;IACH,gCAPW,MAAM,kBACN,UAAU,MAAM,CAAC,aACjB,UAAU,MAAM,CAAC,gBACjB,UAAU,MAAM,CAAC,mBACjB,UAAU,MAAM,CAAC,GACf,QAAQ,CAgBpB;IApSD;;;;OAIG;IACH,0BAJW,MAAM,oBACN,MAAM,EAgEhB;IAzDG,qBAAqB;IACrB,cADW,MAAM,CACe;IAChC,qBAAqB;IACrB,kBADW,MAAM,CACuB;IAOxC;;;;OAIG;IACH,sBAA4D;IAI5D;;;;OAIG;IACH,gBAFU,WAAW,CAEmE;IAGxF;;;OAGG;IACH,WAFU,WAAW,CAE8D;IAGnF;;;;;OAKG;IACH,cAFU,YAAY,CAEiE;IAGvF;;;;;OAKG;IACH,gBAFU,WAAW,CAE+D;IAGpF;;;OAGG;IACH,qBAFU,MAAM,CAEuB;IAG3C;;;;OAIG;IACH,+BAEC;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,uBAFa,MAAM,CAUlB;IAED;;OAEG;IACH,oCAQC;IAED;;;;;;;;;;;;;;;OAeG;IACH,yCAFW,MAAM,QA6ChB;IAED;;;;;;;;;OASG;IACH,YAFW,QAAQ,QASlB;IAED;;;OAGG;IACH,SAFa,QAAQ,CAMpB;IAED;;;;;;;;;;;OAWG;IACH,cAHW,QAAQ,GACN,OAAO,CAyBnB;IAED;;;;;OAKG;IACH,QAFa,MAAM,CAiBlB;IAiCL;;;;;OAKG;IACH,qBAFU,OAAO,CAEY;CAR5B"}

package/src/core/graph/csr/CSRGraph.js

@@ -1,4 +1,5 @@
 import { assert } from "../../assert.js";
+import { float32_array_hash } from "../../collection/array/typed/float32_array_hash.js";
 import { is_typed_array_equals } from "../../collection/array/typed/is_typed_array_equals.js";
 import { uint32_array_hash } from "../../collection/array/typed/uint32_array_hash.js";
 
@@ -241,7 +242,14 @@ export class CSRGraph {
     }
 
     /**
-     * Structural equality — same shape and same buffer contents.
+     * Structural equality — same shape and same contents.
+     *
+     * The three integer arrays compare as words. `edge_weights` compares as floats, by value: a
+     * weight is a measurement, and every consumer of it — `sum_of_edge_weights`, the distance-field
+     * and shortest-path relaxations, metis partitioning — only ever adds or compares it, so `-0` and
+     * `+0` are one weight and no graph behaves differently for holding one rather than the other.
+     * {@link CSRGraph#hash} folds them together to match.
+     *
      * @param {CSRGraph} other
      * @returns {boolean}
      */
@@ -284,11 +292,11 @@ export class CSRGraph {
         // adjacency_length); otherwise two logically-equal graphs with differently-sized buffers hash unequally.
         h = ((h << 5) - h) + uint32_array_hash(this.edge_addresses, 0, this.edge_addresses.length);
         h = ((h << 5) - h) + uint32_array_hash(this.adjacency, 0, this.adjacency.length);
-        // edge_weights is float32; hash its raw IEEE-754 bit pattern via a uint32 view over the
-        // exact same bytes (its own buffer/offset, which need not be __data_buffer if the view was
-        // re-pointed) so fractional weights are distinguished and equal graphs hash equally.
-        const edge_weight_bits = new Uint32Array(this.edge_weights.buffer, this.edge_weights.byteOffset, this.edge_weights.length);
-        h = ((h << 5) - h) + uint32_array_hash(edge_weight_bits, 0, edge_weight_bits.length);
+        // edge_weights is float32, and `equals` compares it as float32 — by value, because a weight
+        // is a measurement. Hashing it must speak the same language: `float32_array_hash` keeps the
+        // bits that carry a value (so fractional weights stay distinct) and folds the one bit that
+        // does not, the sign of a zero, which `-0 === +0` makes invisible to `equals`.
+        h = ((h << 5) - h) + float32_array_hash(this.edge_weights, 0, this.edge_weights.length);
         h = ((h << 5) - h) + uint32_array_hash(this.vertex_weights, 0, this.vertex_weights.length);
         return h | 0;
     }

package/src/core/graph/format/graphviz/graphviz_escape_html_label.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Escapes a string for use inside a GraphViz **HTML-like** label, that is `label=<...>` rather than
+ * `label="..."`.
+ *
+ * The two label syntaxes have nothing in common. Inside `<...>` the text is parsed as markup, so a
+ * bare `&`, `<` or `>` is a syntax error that makes graphviz refuse **the whole file** rather than
+ * the one node — which is exactly when a pass gets named something descriptive. And the
+ * backslash escapes {@link graphviz_escape_string} produces are not processed there at all: they
+ * render as literal backslashes.
+ *
+ * @param {string} input The raw string to be escaped.
+ * @returns {string} The escaped string, safe to interpolate into an HTML-like label.
+ * @see graphviz_escape_string for the `label="..."` / quoted-attribute case
+ * @see https://graphviz.org/doc/info/shapes.html#html
+ */
+export function graphviz_escape_html_label(input: string): string;
+//# sourceMappingURL=graphviz_escape_html_label.d.ts.map

package/src/core/graph/format/graphviz/graphviz_escape_html_label.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphviz_escape_html_label.d.ts","sourceRoot":"","sources":["../../../../../../src/core/graph/format/graphviz/graphviz_escape_html_label.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,kDALW,MAAM,GACJ,MAAM,CAWlB"}

package/src/core/graph/format/graphviz/graphviz_escape_html_label.js

@@ -0,0 +1,25 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * Escapes a string for use inside a GraphViz **HTML-like** label, that is `label=<...>` rather than
+ * `label="..."`.
+ *
+ * The two label syntaxes have nothing in common. Inside `<...>` the text is parsed as markup, so a
+ * bare `&`, `<` or `>` is a syntax error that makes graphviz refuse **the whole file** rather than
+ * the one node — which is exactly when a pass gets named something descriptive. And the
+ * backslash escapes {@link graphviz_escape_string} produces are not processed there at all: they
+ * render as literal backslashes.
+ *
+ * @param {string} input The raw string to be escaped.
+ * @returns {string} The escaped string, safe to interpolate into an HTML-like label.
+ * @see graphviz_escape_string for the `label="..."` / quoted-attribute case
+ * @see https://graphviz.org/doc/info/shapes.html#html
+ */
+export function graphviz_escape_html_label(input) {
+    assert.isString(input, 'input');
+
+    return input
+        .replace(/&/g, '&amp;')  // first, or it would escape the ampersands introduced below
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}

package/src/core/graph/format/graphviz/graphviz_escape_quoted.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Escapes a string for use inside a plain **quoted attribute**, such as `tooltip="..."` or a
+ * cluster's `label="..."` — anywhere the value is text rather than a record label.
+ *
+ * Only the two characters that would end or corrupt the quoted string, plus newlines.
+ * {@link graphviz_escape_string} additionally backslash-escapes `|`, `{` and `}`, which is right
+ * for `shape=record` label syntax and wrong everywhere else: in an ordinary attribute those are
+ * ordinary characters, and the escapes are rendered as literal backslashes.
+ *
+ * @param {string} input The raw string to be escaped.
+ * @returns {string} The escaped string, safe to sit inside double quotes.
+ * @see graphviz_escape_string for the record-label case
+ * @see https://graphviz.org/docs/attr-types/escString/
+ */
+export function graphviz_escape_quoted(input: string): string;
+//# sourceMappingURL=graphviz_escape_quoted.d.ts.map

package/src/core/graph/format/graphviz/graphviz_escape_quoted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphviz_escape_quoted.d.ts","sourceRoot":"","sources":["../../../../../../src/core/graph/format/graphviz/graphviz_escape_quoted.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,8CALW,MAAM,GACJ,MAAM,CAWlB"}

package/src/core/graph/format/graphviz/graphviz_escape_quoted.js

@@ -0,0 +1,24 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * Escapes a string for use inside a plain **quoted attribute**, such as `tooltip="..."` or a
+ * cluster's `label="..."` — anywhere the value is text rather than a record label.
+ *
+ * Only the two characters that would end or corrupt the quoted string, plus newlines.
+ * {@link graphviz_escape_string} additionally backslash-escapes `|`, `{` and `}`, which is right
+ * for `shape=record` label syntax and wrong everywhere else: in an ordinary attribute those are
+ * ordinary characters, and the escapes are rendered as literal backslashes.
+ *
+ * @param {string} input The raw string to be escaped.
+ * @returns {string} The escaped string, safe to sit inside double quotes.
+ * @see graphviz_escape_string for the record-label case
+ * @see https://graphviz.org/docs/attr-types/escString/
+ */
+export function graphviz_escape_quoted(input) {
+    assert.isString(input, 'input');
+
+    return input
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n');
+}

package/src/core/model/node-graph/NodeGraph.d.ts

@@ -43,6 +43,18 @@ export class NodeGraph {
      */
     readonly get version(): number;
     /**
+     * Changes to the graph's structure, announced once the graph is consistent again.
+     *
+     * A connection is not one fact but three — an entry in {@link #connections}, and a link on each
+     * of the two endpoints it joins — and everything that asks what is wired to a port reads the
+     * endpoint links rather than the list. These signals are the list's own, so the endpoint links
+     * are written before a connection joins the list and erased before it leaves: a listener always
+     * sees a whole edit rather than the middle of one.
+     *
+     * Without that, a validator run from `connectionRemoved` would still find the wire that was
+     * just cut, and one run from `connectionAdded` would not find the wire that was just made — so
+     * every diagnostic in the editor would describe the graph as it was one edit ago.
+     *
      * @readonly
      */
     readonly on: {

package/src/core/model/node-graph/NodeGraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeGraph.d.ts","sourceRoot":"","sources":["../../../../../src/core/model/node-graph/NodeGraph.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IAEI;;;;OAIG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,6BAAyB;IAEzB;;;;;OAKG;IACH,4BAA0B;IAE1B;;;;;OAKG;IACH,kCAAgC;IAQhC;;;;;OAKG;IACH,+BAEC;IAED;;OAEG;IACH;QACI;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;MAEL;IAEF;;OAEG;IACH,cAQC;IAED;;;OAGG;IACH,YAFW,SAAS,QAYnB;IAED;;;OAGG;IACH,SAFa,SAAS,CAQrB;IAED;;;;;;OAMG;IACH,aAHW,SAAS,GACP;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAe5D;IAED;;;;;;;;OAQG;IACH,sCAJW,YAAY,EAAE,GAEZ;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAmF5D;IAED;;;;OAIG;IACH,8BAHoB,YAAY,+BAK/B;IAED;;;;OAIG;IACH,oCAHoB,UAAU,+BAK7B;IAED;;;;OAIG;IACH,YAFY,YAAY,EAAE,CAIzB;IAED;;;;OAIG;IACH,kBAFY,UAAU,EAAE,CAIvB;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAgBnB;IAED;;;;OAIG;IACH,qDAFa,YAAY,EAAE,CAsB1B;IAED;;;;OAIG;IACH,0DAFa,YAAY,EAAE,CAqB1B;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,YAAY,GAAC,SAAS,CAkBlC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,GACJ,YAAY,CAWxB;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,UAAU,GAAC,SAAS,CAgBhC;IAED;;;;;OAKG;IACH,+BAJW,MAAM,WACN,MAAM,GACJ,4BAA0B,SAAS,CAY/C;IAED;;;;OAIG;IACH,mCAFa,MAAM,CAclB;IAED;;;OAGG;IACH,cAFW,YAAY,QAkBtB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;;OAQG;IACH,uCANW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAqClB;IAED;;;;;;;;OAQG;IACH,6BAPW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAuDlB;IAED;;;;;;;OAOG;IACH,0BAHW,UAAU,GACR,MAAM,CA2BlB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,OAAO,CA4BnB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,UACN,MAAM,EAAE,GACN,MAAM,CAyBlB;IAED,mBAEC;IAGL;;;;;;;;OAQG;IACH,sBAFU,OAAO,CAEc;;CAX9B;6BAhtB4B,wBAAwB;2BAD1B,iBAAiB"}
+{"version":3,"file":"NodeGraph.d.ts","sourceRoot":"","sources":["../../../../../src/core/model/node-graph/NodeGraph.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IAEI;;;;OAIG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,6BAAyB;IAEzB;;;;;OAKG;IACH,4BAA0B;IAE1B;;;;;OAKG;IACH,kCAAgC;IAQhC;;;;;OAKG;IACH,+BAEC;IAED;;;;;;;;;;;;;;OAcG;IACH;QACI;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;MAEL;IAEF;;OAEG;IACH,cAQC;IAED;;;OAGG;IACH,YAFW,SAAS,QAYnB;IAED;;;OAGG;IACH,SAFa,SAAS,CAQrB;IAED;;;;;;OAMG;IACH,aAHW,SAAS,GACP;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAe5D;IAED;;;;;;;;OAQG;IACH,sCAJW,YAAY,EAAE,GAEZ;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAmF5D;IAED;;;;OAIG;IACH,8BAHoB,YAAY,+BAK/B;IAED;;;;OAIG;IACH,oCAHoB,UAAU,+BAK7B;IAED;;;;OAIG;IACH,YAFY,YAAY,EAAE,CAIzB;IAED;;;;OAIG;IACH,kBAFY,UAAU,EAAE,CAIvB;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAgBnB;IAED;;;;OAIG;IACH,qDAFa,YAAY,EAAE,CAsB1B;IAED;;;;OAIG;IACH,0DAFa,YAAY,EAAE,CAqB1B;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,YAAY,GAAC,SAAS,CAkBlC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,GACJ,YAAY,CAWxB;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,UAAU,GAAC,SAAS,CAgBhC;IAED;;;;;OAKG;IACH,+BAJW,MAAM,WACN,MAAM,GACJ,4BAA0B,SAAS,CAY/C;IAED;;;;OAIG;IACH,mCAFa,MAAM,CAclB;IAED;;;OAGG;IACH,cAFW,YAAY,QAkBtB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;;OAQG;IACH,uCANW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAqClB;IAED;;;;;;;;OAQG;IACH,6BAPW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAwDlB;IAED;;;;;;;OAOG;IACH,0BAHW,UAAU,GACR,MAAM,CA4BlB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,OAAO,CA6BnB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,UACN,MAAM,EAAE,GACN,MAAM,CAyBlB;IAED,mBAEC;IAGL;;;;;;;;OAQG;IACH,sBAFU,OAAO,CAEc;;CAX9B;6BA/tB4B,wBAAwB;2BAD1B,iBAAiB"}

package/src/core/model/node-graph/NodeGraph.js

@@ -66,6 +66,18 @@ export class NodeGraph {
     }
 
     /**
+     * Changes to the graph's structure, announced once the graph is consistent again.
+     *
+     * A connection is not one fact but three — an entry in {@link #connections}, and a link on each
+     * of the two endpoints it joins — and everything that asks what is wired to a port reads the
+     * endpoint links rather than the list. These signals are the list's own, so the endpoint links
+     * are written before a connection joins the list and erased before it leaves: a listener always
+     * sees a whole edit rather than the middle of one.
+     *
+     * Without that, a validator run from `connectionRemoved` would still find the wire that was
+     * just cut, and one run from `connectionAdded` would not find the wire that was just made — so
+     * every diagnostic in the editor would describe the graph as it was one edit ago.
+     *
      * @readonly
      */
     on = {
@@ -608,8 +620,6 @@ export class NodeGraph {
         const id = this.__idpConnections.get();
         connection.id = id;
 
-        this.connections.add(connection);
-
         // add connection links to the nodes
         sourceNodeInstance.connections.addUnique(connection);
         targetNodeInstance.connections.addUnique(connection);
@@ -617,6 +627,9 @@ export class NodeGraph {
         array_push_if_unique(sourceEndpoint.connections, connection);
         array_push_if_unique(targetEndpoint.connections, connection);
 
+        // last, because this is what announces the addition: see the note on #on
+        this.connections.add(connection);
+
         this.#version++;
 
         return id;
@@ -643,8 +656,6 @@ export class NodeGraph {
         const sourceEndpoint = connection.source;
         const targetEndpoint = connection.target;
 
-        this.connections.add(connection);
-
         // add connection links to the nodes
         sourceEndpoint.instance.connections.addUnique(connection);
         targetEndpoint.instance.connections.addUnique(connection);
@@ -652,6 +663,9 @@ export class NodeGraph {
         array_push_if_unique(sourceEndpoint.connections, connection);
         array_push_if_unique(targetEndpoint.connections, connection);
 
+        // last, because this is what announces the addition: see the note on #on
+        this.connections.add(connection);
+
         this.#version++;
 
         return connection.id;
@@ -670,8 +684,6 @@ export class NodeGraph {
             return false;
         }
 
-        this.connections.removeOneOf(connection);
-
         // remove from end-point nodes
         const sourceEndpoint = connection.source;
         const targetEndpoint = connection.target;
@@ -682,6 +694,9 @@ export class NodeGraph {
         array_remove_first(sourceEndpoint.connections, connection);
         array_remove_first(targetEndpoint.connections, connection);
 
+        // last, because this is what announces the removal: see the note on #on
+        this.connections.removeOneOf(connection);
+
         //release id, mirroring deleteNode
         this.__idpConnections.release(id);
 

package/src/core/model/node-graph/node/NodeDescription.d.ts

@@ -11,6 +11,32 @@ export class NodeDescription {
      * @type {string}
      */
     name: string;
+    /**
+     * What to call this node type in front of a person, where that is not what {@link #name} is.
+     *
+     * A library's names are addresses: they are what a graph serializes, what code looks a type up
+     * by, and so they are terse and they do not change. `div`, `mad`, `setAttribute`. None of those
+     * is what an author reads them as, and a graph that only ever shows them makes every reader
+     * translate — so a view shows this and the model keeps the name.
+     *
+     * Empty means the name is already what to show, which is the honest answer for a type called
+     * `clamp`. Read it through {@link #getDisplayLabel} rather than directly.
+     *
+     * @type {string}
+     */
+    display_label: string;
+    /**
+     * A glyph for this node type: SVG path data drawn in a 24x24 box, or an empty string for a type
+     * with no icon.
+     *
+     * Path data rather than an image because an icon here is small, is drawn at several sizes, and
+     * has to take the colour of whatever it is sitting in — and because a library of node types
+     * that ships as source has nowhere to put a hundred PNGs. `stroke` and `currentColor` are the
+     * view's business; this is the shape.
+     *
+     * @type {string}
+     */
+    icon: string;
     /**
      * A unique identifier in the scope of a single registry
      * If two nodes belong to the same registry - they must have different IDs
@@ -44,6 +70,16 @@ export class NodeDescription {
          */
         readonly portRemoved: any;
     };
+    /**
+     * What to show a person for this node type: {@link #display_label} where there is one, and
+     * {@link #name} otherwise.
+     *
+     * The one place the fallback lives, so every view that puts a node type in front of somebody —
+     * the node itself, a palette, a search result, a diagnostic — agrees on what it is called.
+     *
+     * @returns {string}
+     */
+    getDisplayLabel(): string;
     /**
      * Perform additional processing on the node instance
      * This gives us an opportunity to add/change ports based on current state of a specific node instance

package/src/core/model/node-graph/node/NodeDescription.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/core/model/node-graph/node/NodeDescription.js"],"names":[],"mappings":"AAwCA;IAsXI;;;;;OAKG;IACH,iDAFa,eAAe,CAQ3B;IAjYD;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,IAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,iBAFU,IAAI,EAAE,CAEL;IAEX;;;OAGG;IACH,YAFU,wBAAwB,EAAE,CAEpB;IAEhB;;OAEG;IACH;QACI;;;WAGG;;QAEH;;;WAGG;;MAEL;IAEF;;;;OAIG;IACH,4CAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;;;;OAMG;IACH,sBALW,MAAM,QACN,qBAAqB,iBACrB,MAAM,GAAC,OAAO,GAAC,MAAM,GACnB,MAAM,CA0ClB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,wBAAwB,GAAC,IAAI,CAiBzC;IAGD;;;;;;OAMG;IACH,oDAHW,aAAa,GACX,MAAM,CA2BlB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CAuBnB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,IAAI,GAAC,IAAI,CAgBrB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACL,IAAI,EAAE,CAwBjB;IAED;;;;;OAKG;IACH,+BAHW,aAAa,GACZ,OAAO,CAiBlB;IAED;;;;OAIG;IACH,+BAHW,aAAa,GACZ,IAAI,EAAE,CAuBjB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,aACN,aAAa,GACZ,IAAI,GAAC,SAAS,CAmBzB;IAED;;;OAGG;IACH,YAFa,IAAI,EAAE,CAIlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,cAHW,eAAe,GACb,OAAO,CAYnB;IAED,mBAEC;IAED;;;;MAMC;IAgBD;;;;;;OAMG;IACH,8BALW,EAAE,gCAaZ;IAKL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAR1C;;;;qBArboB,WAAW;yCADS,yCAAyC;sCAD5C,sCAAsC;8BAG9C,oBAAoB"}
+{"version":3,"file":"NodeDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/core/model/node-graph/node/NodeDescription.js"],"names":[],"mappings":"AAwCA;IA+ZI;;;;;OAKG;IACH,iDAFa,eAAe,CAQ3B;IA1aD;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;OAYG;IACH,eAFU,MAAM,CAEG;IAEnB;;;;;;;;;;OAUG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,IAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,iBAFU,IAAI,EAAE,CAEL;IAEX;;;OAGG;IACH,YAFU,wBAAwB,EAAE,CAEpB;IAEhB;;OAEG;IACH;QACI;;;WAGG;;QAEH;;;WAGG;;MAEL;IAEF;;;;;;;;OAQG;IACH,mBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,4CAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,sBAEC;IAED;;;;;;OAMG;IACH,sBALW,MAAM,QACN,qBAAqB,iBACrB,MAAM,GAAC,OAAO,GAAC,MAAM,GACnB,MAAM,CA0ClB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,wBAAwB,GAAC,IAAI,CAiBzC;IAGD;;;;;;OAMG;IACH,oDAHW,aAAa,GACX,MAAM,CA2BlB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CAuBnB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,IAAI,GAAC,IAAI,CAgBrB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACL,IAAI,EAAE,CAwBjB;IAED;;;;;OAKG;IACH,+BAHW,aAAa,GACZ,OAAO,CAiBlB;IAED;;;;OAIG;IACH,+BAHW,aAAa,GACZ,IAAI,EAAE,CAuBjB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,aACN,aAAa,GACZ,IAAI,GAAC,SAAS,CAmBzB;IAED;;;OAGG;IACH,YAFa,IAAI,EAAE,CAIlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,cAHW,eAAe,GACb,OAAO,CAYnB;IAED,mBAEC;IAED;;;;MAMC;IAgBD;;;;;;OAMG;IACH,8BALW,EAAE,gCAaZ;IAKL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAR1C;;;;qBA9doB,WAAW;yCADS,yCAAyC;sCAD5C,sCAAsC;8BAG9C,oBAAoB"}

package/src/core/model/node-graph/node/NodeDescription.js

@@ -45,6 +45,34 @@ export class NodeDescription {
      */
     name = "";
 
+    /**
+     * What to call this node type in front of a person, where that is not what {@link #name} is.
+     *
+     * A library's names are addresses: they are what a graph serializes, what code looks a type up
+     * by, and so they are terse and they do not change. `div`, `mad`, `setAttribute`. None of those
+     * is what an author reads them as, and a graph that only ever shows them makes every reader
+     * translate — so a view shows this and the model keeps the name.
+     *
+     * Empty means the name is already what to show, which is the honest answer for a type called
+     * `clamp`. Read it through {@link #getDisplayLabel} rather than directly.
+     *
+     * @type {string}
+     */
+    display_label = "";
+
+    /**
+     * A glyph for this node type: SVG path data drawn in a 24x24 box, or an empty string for a type
+     * with no icon.
+     *
+     * Path data rather than an image because an icon here is small, is drawn at several sizes, and
+     * has to take the colour of whatever it is sitting in — and because a library of node types
+     * that ships as source has nowhere to put a hundred PNGs. `stroke` and `currentColor` are the
+     * view's business; this is the shape.
+     *
+     * @type {string}
+     */
+    icon = "";
+
     /**
      * A unique identifier in the scope of a single registry
      * If two nodes belong to the same registry - they must have different IDs
@@ -82,6 +110,19 @@ export class NodeDescription {
         portRemoved: new Signal()
     };
 
+    /**
+     * What to show a person for this node type: {@link #display_label} where there is one, and
+     * {@link #name} otherwise.
+     *
+     * The one place the fallback lives, so every view that puts a node type in front of somebody —
+     * the node itself, a palette, a search result, a diagnostic — agrees on what it is called.
+     *
+     * @returns {string}
+     */
+    getDisplayLabel() {
+        return this.display_label !== "" ? this.display_label : this.name;
+    }
+
     /**
      * Perform additional processing on the node instance
      * This gives us an opportunity to add/change ports based on current state of a specific node instance