@graphty/graphty-element 2.3.0 → 2.4.0

package/dist/chunks/paletteRegistry-A63C71Gn.js

@@ -0,0 +1,1155 @@
+import { q as b, G as F } from "./GraphtyLogger-CqOVV13Y.js";
+import { a as T, b as D, d as k } from "./types-C_c53VgR.js";
+import { remapArray as S, INVALID_INDEX as N } from "@graphty/graph-format";
+import { z as O } from "zod/v4";
+import { G as g } from "./GraphtyError-B93WRH3e.js";
+import { c as v } from "./common-DWNKjpH_.js";
+const f = b({
+  kind: "format",
+  idOf: (i) => i.descriptor.id,
+  descriptorOf: (i) => i.descriptor,
+  implementationOf: (i) => i.descriptor,
+  builtInIds: () => T
+});
+function it(i, t) {
+  f.register(i, t);
+}
+function st() {
+  return f.entries();
+}
+function L() {
+  return f.descriptors();
+}
+function $(i) {
+  return f.byId(i);
+}
+function rt() {
+  f.clearForTesting();
+}
+const M = {
+  "edge-list": "Edge List",
+  "node-list": "Node List",
+  "adjacency-list": "Adjacency List",
+  neo4j: "Neo4j Export",
+  gephi: "Gephi Export",
+  cytoscape: "Cytoscape Export",
+  generic: "Generic"
+}, R = [
+  {
+    name: "delimiter",
+    plainName: "Column Separator",
+    technicalName: "delimiter",
+    type: "string",
+    description: "The character between one column and the next. Worked out from the first line (comma, tab, semicolon or pipe) when it is not set."
+  },
+  {
+    name: "variant",
+    plainName: "File Shape",
+    technicalName: "variant",
+    type: "enum",
+    values: Object.entries(M).map(([i, t]) => ({ value: i, label: t })),
+    description: "Which CSV shape to read. Worked out from the header row when it is not set."
+  },
+  {
+    name: "idColumn",
+    plainName: "Node Id Column",
+    technicalName: "idColumn",
+    type: "string",
+    description: "The column holding each node's identity, when the file lists nodes."
+  }
+], h = [
+  {
+    name: "edgeSource",
+    plainName: "Edge Start Field",
+    technicalName: "edgeSource",
+    type: "string",
+    description: "Where to find the node an edge starts at. Left unset, the element looks for source, then src, then from."
+  },
+  {
+    name: "edgeTarget",
+    plainName: "Edge End Field",
+    technicalName: "edgeTarget",
+    type: "string",
+    description: "Where to find the node an edge ends at. Left unset, the element looks for target, then dst, then to."
+  }
+], j = [
+  {
+    name: "nodeIdPath",
+    plainName: "Node Id Field",
+    technicalName: "nodeIdPath",
+    type: "string",
+    description: "An expression selecting each node's identity out of the node record."
+  }
+], _ = [
+  {
+    id: "json",
+    plainName: "JSON",
+    extensions: [".json"],
+    mimeTypes: ["application/json"],
+    canImport: !0,
+    canExport: !1,
+    options: [...j, ...h]
+  },
+  {
+    id: "csv",
+    plainName: "CSV",
+    extensions: [".csv", ".tsv", ".tab", ".edges", ".edgelist"],
+    mimeTypes: ["text/csv", "text/tab-separated-values", "text/plain"],
+    canImport: !0,
+    canExport: !1,
+    options: [...R, ...h]
+  },
+  {
+    id: "graphml",
+    plainName: "GraphML",
+    extensions: [".graphml", ".xml"],
+    mimeTypes: ["application/graphml+xml", "application/xml", "text/xml"],
+    canImport: !0,
+    canExport: !1,
+    options: h
+  },
+  {
+    id: "gexf",
+    plainName: "GEXF",
+    // ".xml" is claimed here as well as by GraphML because both formats are XML and both are
+    // routinely saved under the generic extension. Two claimants is what lets detection ask
+    // each one's content sniffer which of them the file actually is, instead of a private
+    // branch inside the detector hard-coding the two namespace strings -- which is the same
+    // route a third party's XML dialect now takes.
+    extensions: [".gexf", ".xml"],
+    mimeTypes: ["application/gexf+xml", "application/xml", "text/xml"],
+    canImport: !0,
+    canExport: !1,
+    options: h
+  },
+  {
+    id: "gml",
+    plainName: "GML",
+    extensions: [".gml"],
+    mimeTypes: ["text/plain"],
+    canImport: !0,
+    canExport: !1,
+    options: h
+  },
+  {
+    id: "dot",
+    plainName: "DOT",
+    extensions: [".dot", ".gv"],
+    mimeTypes: ["text/vnd.graphviz", "text/plain"],
+    canImport: !0,
+    canExport: !1,
+    options: h
+  },
+  {
+    id: "pajek",
+    plainName: "Pajek NET",
+    extensions: [".net", ".paj"],
+    mimeTypes: ["text/plain"],
+    canImport: !0,
+    canExport: !1,
+    options: h
+  }
+], nt = [
+  { id: "sif", reason: "No data source reads the Cytoscape simple interaction format." },
+  { id: "cx2", reason: "No data source reads the Cytoscape Exchange format." }
+];
+function ot(i) {
+  return _.find((t) => t.id === i) ?? $(i)?.descriptor;
+}
+function at(i) {
+  const t = i.toLowerCase();
+  return [..._, ...L()].filter(
+    (e) => e.extensions.includes(t)
+  );
+}
+const m = b({
+  kind: "layout",
+  idOf: (i) => i.descriptor.id,
+  descriptorOf: (i) => i.descriptor,
+  implementationOf: (i) => i.descriptor,
+  builtInIds: () => D
+});
+function z(i, t) {
+  m.register(i, t);
+}
+function lt() {
+  return m.descriptors();
+}
+function ct(i) {
+  return m.byId(i);
+}
+function ht() {
+  m.clearForTesting();
+}
+const o = 3, B = 1024;
+function p(i, t) {
+  if (!Number.isInteger(i) || i < 0)
+    throw new RangeError(`ElementPositions: ${t} must be a non-negative integer, found ${String(i)}`);
+  return i;
+}
+function d(i) {
+  return Number.isFinite(Math.fround(i));
+}
+class x {
+  /**
+   * Allocate the backing array, every row unplaced and unpinned.
+   * @param capacity - rows to reserve before the first growth; a non-negative integer
+   */
+  constructor(t = B) {
+    this.components = o, this.rows = 0, p(t, "capacity");
+    const e = Math.max(1, t);
+    this.array = new Float32Array(o * e), this.array.fill(Number.NaN), this.pins = new Uint8Array(e);
+  }
+  /**
+   * Rows the backing array can hold without reallocating.
+   * @returns the current capacity in rows
+   */
+  get capacity() {
+    return this.array.length / o;
+  }
+  /**
+   * Rows currently in use. Equals the last snapshot's nodeCount.
+   * @returns the live row count
+   */
+  get count() {
+    return this.rows;
+  }
+  /**
+   * How many live rows carry real coordinates, by the same test {@link ElementPositions.isPlaced}
+   * applies one row at a time.
+   *
+   * The question behind it is "did the file that loaded this graph place every node?", which is
+   * what decides whether the Keep Positions arrangement can be used at all: a fixed layout over a
+   * graph where half the rows are NaN draws half a picture. Compare it against
+   * {@link ElementPositions.count} to answer that -- equal means every node has somewhere to go.
+   *
+   * COUNTED ON EVERY READ, and it has to be. The array is lent to the snapshot as a mutable
+   * column, so a layout, a drag and a GPU readback all write coordinates without passing through
+   * this class; a counter kept up to date by `write()` would miss every one of those and would be
+   * most wrong exactly while a layout was running, which is when somebody is asking. The scan is
+   * one f32 read per node and touches only the x lane.
+   *
+   * This is deliberately NOT on `GraphStatistics`. Those are memoised against the snapshot they
+   * were computed from, and how many nodes carry a coordinate changes while a layout runs WITHIN
+   * one snapshot, so a cached answer would be stale in the one moment it mattered.
+   * @returns how many rows in `[0, count)` carry a storable x
+   */
+  get placedCount() {
+    let t = 0;
+    for (let e = 0; e < o * this.rows; e += o)
+      this.hasStorableX(e) && t++;
+    return t;
+  }
+  /**
+   * The exact view to hand to `snapshot.nodes.set("position", ...)`.
+   *
+   * Bounded by the LIVE ROW COUNT, like every other row accessor here. `subarray` CLAMPS rather
+   * than throwing, so without a check a caller that forgot to `grow()` first would get a short
+   * array: E_COLUMN_LENGTH from inside graph-format if it is attached, and a layout that silently
+   * places only the first `count` nodes if it is not. Bounding by the CAPACITY instead would hand
+   * out a writable window over the spare rows -- rows this class reports unplaced, whose NaN fill
+   * every later `grow()` and `remap()` depends on, and whose contents the next growth erases.
+   * @param nodeCount - the snapshot's node count
+   * @returns a subarray of length `3 * nodeCount` over the same buffer
+   * @throws RangeError when `nodeCount` is not a non-negative integer, or exceeds the live count
+   */
+  view(t) {
+    if (p(t, "nodeCount"), t > this.rows)
+      throw new RangeError(
+        `ElementPositions: view(${t}) needs ${t} live rows but only ${this.rows} exist; call grow(${t}) first`
+      );
+    return this.array.subarray(0, o * t);
+  }
+  /**
+   * Prefix-stable growth: existing rows keep their coordinates, EVERY row at or above the new
+   * count is unplaced -- including the spare capacity, which a later grow() will hand out.
+   *
+   * Past the capacity this REPLACES the array object; see the staleness contract on the class.
+   * @param nodeCount - the new row count; may be smaller than the current one (append-only
+   *     builders never shrink, but a caller that does gets a truncation, not a throw). `grow(0)`
+   *     is how a dataset is discarded while the reserve is kept
+   * @throws RangeError when `nodeCount` is not a non-negative integer
+   */
+  grow(t) {
+    if (p(t, "nodeCount"), t > this.capacity) {
+      const e = Math.max(this.capacity * 2, t), s = new Float32Array(o * e);
+      s.set(this.array), s.fill(Number.NaN, o * this.rows), this.array = s;
+      const r = new Uint8Array(e);
+      r.set(this.pins), r.fill(0, this.rows), this.pins = r;
+    } else t > this.rows ? (this.array.fill(Number.NaN, o * this.rows, o * t), this.pins.fill(0, this.rows, t)) : t < this.rows && (this.array.fill(Number.NaN, o * t, o * this.rows), this.pins.fill(0, t, this.rows));
+    this.rows = t;
+  }
+  /**
+   * Apply a freeze report's `nodeRemap` (previous index space -> new index or INVALID_INDEX).
+   *
+   * `remapArray` ALLOCATES, so this replaces the array object and collapses the capacity to
+   * exactly `nodeCount` (PLAN DECISION 3: a removal is rare and never per frame, so paying one
+   * reallocation on the next growth is cheaper than copying the remapped rows a second time into
+   * a re-reserved array). Every holder of the old object is stale afterwards, which is why
+   * GraphStore re-attaches the column on every freeze and emits `snapshot-replaced`.
+   * @param nodeRemap - the report's nodeRemap
+   * @param nodeCount - the new snapshot's node count
+   * @throws RangeError when `nodeCount` is not a non-negative integer
+   */
+  remap(t, e) {
+    p(e, "nodeCount"), this.array = S(this.array, t, e, Number.NaN, o), this.pins = S(this.pins, t, e, 0, 1), this.rows = e;
+  }
+  /**
+   * Whether the reader has fixed this row's node in place.
+   *
+   * A row outside the live count is UNPINNED, never pinned, for the same reason
+   * {@link ElementPositions.isPlaced} answers false there: a node with no row is a node the
+   * graph builder has not taken, and answering "pinned" for one would freeze a node that does
+   * not exist yet and that nothing could release.
+   * @param index - node index
+   * @returns true when the row is inside the live count AND carries a pin
+   */
+  isPinned(t) {
+    return !Number.isInteger(t) || t < 0 || t >= this.rows ? !1 : this.pins[t] === 1;
+  }
+  /**
+   * Record or release a pin, GROWING the lane to reach the row.
+   *
+   * It grows rather than throwing for the same reason `LayoutEngine.writeNodePosition` does: a
+   * node's index is handed out the moment the graph builder takes its record, but its row only
+   * appears when the graph is next frozen, and a reader who drags a node in between would
+   * otherwise have the pin thrown away in silence.
+   *
+   * It REFUSES rather than throwing for an index that is not a row number at all -- the
+   * `INVALID_INDEX` a record the builder would not take carries for its whole life, or a
+   * negative or fractional number. Pinning happens from a pointer gesture, and a throw on that
+   * path takes the frame with it.
+   * @param index - node index
+   * @param pinned - true to pin, false to release
+   * @returns true when the lane was written, false when the index names no row
+   */
+  setPinned(t, e) {
+    return t === N || !Number.isInteger(t) || t < 0 ? !1 : (t >= this.rows && this.grow(t + 1), this.pins[t] = e ? 1 : 0, !0);
+  }
+  /**
+   * How many live rows are pinned.
+   * @returns the count of pinned rows in `[0, count)`
+   */
+  get pinnedCount() {
+    let t = 0;
+    for (let e = 0; e < this.rows; e++)
+      this.pins[e] === 1 && t++;
+    return t;
+  }
+  /**
+   * The exact view to hand to `snapshot.nodes.set("graphty.pinned", ...)`.
+   *
+   * Bounded by the live row count, like {@link ElementPositions.view} and for the same reasons.
+   * @param nodeCount - the snapshot's node count
+   * @returns a subarray of length `nodeCount` over the same buffer
+   * @throws RangeError when `nodeCount` is not a non-negative integer, or exceeds the live count
+   */
+  pinnedView(t) {
+    if (p(t, "nodeCount"), t > this.rows)
+      throw new RangeError(
+        `ElementPositions: pinnedView(${t}) needs ${t} live rows but only ${this.rows} exist; call grow(${t}) first`
+      );
+    return this.pins.subarray(0, t);
+  }
+  /**
+   * Report whether a row carries real coordinates.
+   *
+   * A row outside the live count is UNPLACED, never placed: this predicate is used to decide
+   * whether an importer seed may be written, and answering "placed" for a row that does not
+   * exist is how a coordinate gets thrown away without an error. So is a row whose x is an
+   * infinity, which only a writer that bypassed `write()` -- that is, one writing through the
+   * column this array is lent to -- can produce; see the class comment.
+   * @param index - node index
+   * @returns true when the row is inside the live count AND carries a storable x
+   */
+  isPlaced(t) {
+    return !Number.isInteger(t) || t < 0 || t >= this.rows ? !1 : this.hasStorableX(o * t);
+  }
+  /**
+   * Read one row into a caller-supplied object (14.4 rule 7: never return a shared vector).
+   * @param index - node index
+   * @param out - the object to fill
+   * @param out.x - receives the scene-unit x
+   * @param out.y - receives the scene-unit y
+   * @param out.z - receives the scene-unit z
+   * @throws RangeError when `index` is not an integer in `[0, count)`
+   */
+  read(t, e) {
+    const s = this.rowBase(t);
+    e.x = this.array[s] ?? Number.NaN, e.y = this.array[s + 1] ?? Number.NaN, e.z = this.array[s + 2] ?? Number.NaN;
+  }
+  /**
+   * Write one row.
+   *
+   * This is the ONE choke point every layout, every drag and (from E1) every GPU readback goes
+   * through, so it is where an unstorable coordinate is stopped. NaN is this class's unplaced
+   * marker: letting one in through here would unplace a placed node from the inside, and an
+   * infinity would be stored and then reported placed. The test is `isStorableCoordinate`, NOT
+   * `Number.isFinite`, because the array is f32: a finite double of 1e39 passes `isFinite` and
+   * lands as Infinity. A caller holding such a coordinate has a bug upstream and must drop the
+   * update, not hand it on.
+   * @param index - node index
+   * @param x - scene-unit x
+   * @param y - scene-unit y
+   * @param z - scene-unit z
+   * @throws RangeError when `index` is not an integer in `[0, count)`. A node added since the
+   *     last freeze has no row yet: freeze first (which grows this array), then write
+   * @throws RangeError when any component is NaN, an infinity, or a double that overflows f32
+   */
+  write(t, e, s, r) {
+    const n = this.rowBase(t);
+    if (!d(e) || !d(s) || !d(r))
+      throw new RangeError(
+        `ElementPositions: row ${String(t)} was written the unstorable coordinate (${String(e)}, ${String(s)}, ${String(r)}); NaN is this class's UNPLACED marker, and an infinity -- including one an f32 overflow produces -- poisons the scene bounds`
+      );
+    this.array[n] = e, this.array[n + 1] = s, this.array[n + 2] = r;
+  }
+  /**
+   * Write a row ONLY when it is unplaced. This is how importer-seeded coordinates reach a new
+   * node without overwriting anything a layout or a drag already produced.
+   *
+   * `false` means exactly one thing -- the row was ALREADY PLACED, by the same test `isPlaced()`
+   * applies. A row that does not exist yet throws instead of returning `false`, so a caller that
+   * seeds before growing finds out rather than losing the coordinate.
+   * @param index - node index
+   * @param x - scene-unit x
+   * @param y - scene-unit y
+   * @param z - scene-unit z
+   * @returns true when the row was written, false when it was already placed
+   * @throws RangeError when `index` is not an integer in `[0, count)`
+   * @throws RangeError when any component is NaN, an infinity, or a double that overflows f32,
+   *     through `write()`
+   */
+  fillUnplaced(t, e, s, r) {
+    const n = this.rowBase(t);
+    return this.hasStorableX(n) ? !1 : (this.write(t, e, s, r), !0);
+  }
+  /**
+   * Whether the row at this offset carries a storable x, which is the one test "placed" means.
+   * @param base - the array offset of the row's x component
+   * @returns true when the stored x is neither NaN nor an infinity
+   */
+  hasStorableX(t) {
+    return d(this.array[t] ?? Number.NaN);
+  }
+  /**
+   * The array offset of a live row, rejecting anything else.
+   * @param index - node index
+   * @returns the offset of the row's x component
+   */
+  rowBase(t) {
+    if (!Number.isInteger(t) || t < 0 || t >= this.rows)
+      throw new RangeError(
+        t === N ? "ElementPositions: INVALID_INDEX is the graph-format 'no node' sentinel, not a row" : `ElementPositions: row ${String(t)} is outside the live range [0, ${this.rows})`
+      );
+    return o * t;
+  }
+}
+const l = /* @__PURE__ */ new Map(), C = Object.freeze([
+  "arf",
+  "bfs",
+  "bipartite",
+  "circular",
+  "d3",
+  "fixed",
+  "forceatlas2",
+  "grid",
+  "kamada-kawai",
+  "multipartite",
+  "ngraph",
+  "planar",
+  "radial",
+  "random",
+  "shell",
+  "spectral",
+  "spiral",
+  "spring",
+  "spring-electrical"
+]), W = F.getLogger(["graphty", "layout"]), P = 1e-6;
+function G(i, t) {
+  return JSON.stringify([i, t]);
+}
+const U = 10;
+function A(i) {
+  return new g({
+    code: "E_DUPLICATE_PLUGIN",
+    message: `"${i}" is a layout engine the element ships, and a built-in name may not be taken: a saved document that named it yesterday has to mean the same thing today`,
+    source: "registry",
+    details: { kind: "layout", name: i, builtIn: !0 }
+  });
+}
+const E = class E {
+  constructor() {
+    this.positionArrayAttached = !1;
+  }
+  /**
+   * Add multiple nodes to the layout engine
+   * @param nodes - Array of nodes to add
+   */
+  addNodes(t) {
+    for (const e of t)
+      this.addNode(e);
+  }
+  /**
+   * Add multiple edges to the layout engine
+   * @param edges - Array of edges to add
+   */
+  addEdges(t) {
+    for (const e of t)
+      this.addEdge(e);
+  }
+  /**
+   * Take a node out of the layout, before the element disposes the mesh that drew it.
+   *
+   * Declared here, with a default that does nothing, because it used to be duck-typed by the
+   * element's data manager and implemented by none of the nineteen engines that ship here: an
+   * author learned it existed by reading the element's source, and got no worked example. An
+   * engine that keeps its own node list must override this, or it holds every removed node --
+   * and everything that node references -- for as long as the engine lives.
+   * @param _n - the node leaving the graph
+   */
+  removeNode(t) {
+  }
+  /**
+   * The edge half of {@link LayoutEngine.removeNode}, with the same default and the same reason.
+   * @param _e - the edge leaving the graph
+   */
+  removeEdge(t) {
+  }
+  /**
+   * Settle nodes that reached the graph after this layout was already running.
+   *
+   * THE DEFAULT IS THE ELEMENT'S OWN FALLBACK -- up to ten steps, stopping early if the engine
+   * settles -- so a simulation behaves exactly as it did before the hook was declared, and an
+   * engine that can place a newcomer without re-running the whole simulation overrides it. It
+   * lives on the base class rather than in the manager because the manager cannot tell "did not
+   * implement it" from "implemented it as a deliberate no-op", and the difference decides
+   * whether ten steps run.
+   * @param _nodes - the nodes that have just arrived
+   */
+  updatePositions(t) {
+    for (let e = 0; e < U; e++) {
+      if (this.isSettled)
+        return;
+      this.step();
+    }
+  }
+  /**
+   * Release whatever this engine holds. The element calls it when the reader switches layouts
+   * and when the graph is torn down, and never uses the engine again afterwards.
+   *
+   * Declared with a do-nothing default for the same reason as {@link LayoutEngine.removeNode}:
+   * it was duck-typed, undeclared and unimplemented by every engine here.
+   */
+  dispose() {
+  }
+  /**
+   * The array this engine publishes node coordinates into.
+   *
+   * Allocated on demand, so reading it is enough to make an engine that has never been handed an
+   * element's array produce one of its own.
+   * @returns the position array in use
+   */
+  get nodePositions() {
+    return this.positionArray ??= new x(0), this.positionArray;
+  }
+  /**
+   * Hand this engine the array it must publish into, and stop it adopting any other.
+   *
+   * This is how a host says "these coordinates are mine": the engine writes into the array the
+   * host already lends to its snapshots, so a layout, a drag and a GPU readback all land in the
+   * one place and a re-freeze loses none of them.
+   * @param positions - the element-owned array
+   */
+  attachPositions(t) {
+    this.positionArray = t, this.positionArrayAttached = !0;
+  }
+  /**
+   * Copy every node's current coordinates out of the engine and into the position array.
+   *
+   * Engines call this at the end of a step, so that by the time anything draws, the array is the
+   * answer rather than a copy of it. The default walks the engine's own nodes through
+   * {@link LayoutEngine.getNodePosition}, which is correct for any engine but allocates one
+   * object per node; an engine that can read its own state without allocating overrides it, and
+   * an engine that already writes straight into the array overrides it to do nothing.
+   */
+  publishPositions() {
+    for (const t of this.nodes) {
+      const e = this.getNodePosition(t);
+      this.writeNodePosition(t, e.x, e.y, e.z ?? 0);
+    }
+  }
+  /**
+   * Read a node's published coordinates into an object the CALLER owns.
+   *
+   * The point of the out parameter is that a renderer can pass the vector it is about to draw
+   * with and allocate nothing per node per frame. A row that no engine has placed answers false
+   * and leaves `out` untouched, so the caller keeps whatever it had rather than being handed a
+   * NaN or an origin it cannot tell from a real coordinate.
+   * @param n - the node to read
+   * @param out - the object to fill; a Babylon `Vector3` is one, which is the point
+   * @param out.x - receives the scene-unit x
+   * @param out.y - receives the scene-unit y
+   * @param out.z - receives the scene-unit z
+   * @returns true when the node has a placed row
+   */
+  readNodePosition(t, e) {
+    const s = this.positionsFor(t);
+    return s.isPlaced(t.index) ? (s.read(t.index, e), !0) : !1;
+  }
+  /**
+   * Publish one node's coordinates, growing the array to reach its row.
+   *
+   * Three things are silently skipped rather than thrown, because this runs inside a layout step
+   * and a throw there kills the frame: a node with no row in the graph (`INVALID_INDEX`, which a
+   * record whose id the graph builder would not take carries for its whole life), a node whose
+   * index is not a row number at all, and a coordinate that cannot be stored. That last one is
+   * the important one -- a force layout that divided by a zero distance produces NaN, and an
+   * overflow of the f32 the array stores produces an infinity. Either one, written, would make
+   * the row read back as a place: the mesh vanishes and the scene bounds and camera framing go
+   * with it. Left alone, the row stays unplaced and the node keeps the coordinates it had.
+   *
+   * The array is GROWN to reach the row rather than the write being refused. A node's index is
+   * handed out the moment its record is taken, but its row only appears when the graph is next
+   * frozen, and a layout that ran in between would otherwise be thrown away in silence. Growth is
+   * prefix-stable and fills what it adds with NaN, so it cannot disturb a row anything else
+   * placed; the one thing it does change is that a node this engine placed before the first
+   * freeze counts as placed, which is what makes a file's own coordinates yield to it.
+   *
+   * A PINNED ROW REFUSES A LAYOUT STEP. This is the whole of "a pin is meaningful under every
+   * arrangement": fourteen of the element's nineteen engines implement `pin()` as a no-op and
+   * `setNodePosition` as a no-op too, so before this guard a reader who dragged a node under a
+   * static layout watched it snap back the next time the layout recomputed. One refusal here
+   * covers every engine, including one written by a third party that has never heard of pinning,
+   * because every engine reaches the shared array through this method.
+   *
+   * A DRAG IS NOT A LAYOUT STEP. `intent: "placement"` writes straight through, so a reader can
+   * move a pinned node and have it stay where they put it; without that distinction the guard
+   * would make a pinned node undraggable, which is the opposite of what a pin is for. The
+   * default is `"layout"` so that an engine written before the parameter existed -- a plugin's
+   * step loop -- is guarded without knowing it, and only the placement paths have to opt out.
+   * @param n - the node being placed
+   * @param x - scene-unit x
+   * @param y - scene-unit y
+   * @param z - scene-unit z
+   * @param intent - `"layout"` for a simulation step, `"placement"` for a drag or a replay
+   * @returns true when the row was written
+   */
+  writeNodePosition(t, e, s, r, n = "layout") {
+    const { index: a } = t;
+    if (a === N || !Number.isInteger(a) || a < 0 || !d(e) || !d(s) || !d(r))
+      return !1;
+    const c = this.positionsFor(t);
+    return n === "layout" && c.isPinned(a) ? !1 : (a >= c.count && c.grow(a + 1), c.write(a, e, s, r), !0);
+  }
+  /**
+   * The weight of every ordered endpoint pair this batch of edges covers, or null when the
+   * graph's weights carry no information.
+   *
+   * WHY A PAIR AND NOT AN EDGE. `@graphty/layout`'s one weight channel is
+   * `graph.getEdgeData(source, target, attr)`, which is asked by endpoint pair, and both layout
+   * functions that read it write the answer into a matrix cell -- `A[i][j]` in ForceAtlas2,
+   * `distances[s][t]` in Kamada-Kawai. There is no cell for a second edge between the same two
+   * nodes, so parallel edges are SUMMED into one number rather than left to last-writer-wins,
+   * where the order the file happened to list them in would decide the arrangement. Summing is
+   * also what the element does when it simplifies a multigraph for an algorithm, so a graph's
+   * weights mean the same thing to a layout and to a metric.
+   *
+   * READ ONCE PER LAYOUT COMPUTATION, not per frame and not per edge: the weights come from the
+   * current snapshot's edge list, indexed by the same logical edge index `Edge.index` holds.
+   *
+   * NULL MEANS "DO NOT ATTACH A CALLBACK". graph-format stores an all-ones graph with no weight
+   * column at all, and a graph whose every weight is 1 carries no information a layout could
+   * arrange by -- so the caller leaves `getEdgeData` off the graph object entirely and the
+   * arrangement is bit-identical to the one the same seed produced before weights existed.
+   *
+   * THIS IS A SLIGHTLY NARROWER QUESTION THAN `statistics().weighted`, deliberately. The status
+   * chip asks whether the SNAPSHOT's weight column carries anything but ones; this asks it of
+   * the edges this engine is actually about to arrange. They answer differently only when the
+   * engine holds a strict subset of the graph's edges whose weights are all 1, and there the
+   * narrower answer is the correct one: a layout cannot be moved by a weight on an edge it is
+   * not laying out. A consumer who sees "weighted" on the status bar and an unmoved arrangement
+   * is looking at that case.
+   * @param edges - the edges this engine is about to lay out
+   * @returns pair key (see {@link pairWeightKey}) to summed weight, or null
+   */
+  pairWeights(t) {
+    if (t.length === 0)
+      return null;
+    const s = t[0].parentGraph?.getDataManager?.()?.getSnapshot?.()?.edgeList().weights ?? null;
+    if (s === null)
+      return null;
+    const r = /* @__PURE__ */ new Map();
+    let n = !1;
+    for (const a of t) {
+      const c = a.index >= 0 && a.index < s.length ? s[a.index] : 1;
+      c !== 1 && (n = !0);
+      const I = G(a.srcId, a.dstId);
+      r.set(I, (r.get(I) ?? 0) + c);
+    }
+    return n ? r : null;
+  }
+  /**
+   * Say once, per layout computation, how many pairs were clamped off zero.
+   *
+   * ONCE PER RUN AND NOT PER EDGE: a graph whose weights are all zero would otherwise produce
+   * one line per edge, which buries every other message in the run it happened during. It is
+   * reported at all because a clamp changes the picture -- a zero-weight edge is drawn as the
+   * weakest connection the solver can express rather than as no connection -- and the record
+   * that carried the zero is the reader's, not the element's, so they are the one who can fix
+   * it.
+   * @param layout - the layout name, for the message
+   * @param weights - the pair weights about to be handed to the layout function
+   */
+  reportClampedWeights(t, e) {
+    let s = 0;
+    for (const r of e.values())
+      r < P && s++;
+    s > 0 && W.warn("Edge weights at or below zero were clamped before the layout read them", {
+      layout: t,
+      clamped: s,
+      epsilon: P
+    });
+  }
+  /**
+   * The array to use for this node: the one its own graph owns, unless a host attached one.
+   *
+   * Resolved on every call rather than cached, because the element REPLACES its array when a
+   * dataset is discarded -- the store and everything keyed into it is thrown away and rebuilt --
+   * and an engine outlives that. A cached reference would keep publishing into the array of a
+   * graph that no longer exists, which is invisible: every write succeeds and nothing draws.
+   * @param n - the node being published or read
+   * @returns the array to write to and read from
+   */
+  positionsFor(t) {
+    if (!this.positionArrayAttached) {
+      const e = t.parentGraph?.getDataManager?.()?.positions;
+      e instanceof x && (this.positionArray = e);
+    }
+    return this.nodePositions;
+  }
+  /**
+   * Get the type identifier for this layout engine
+   * @returns The layout engine type string
+   */
+  get type() {
+    return this.constructor.type;
+  }
+  /**
+   * File a layout engine class under the name it declares, and publish what it says about
+   * itself to the catalogue.
+   *
+   * WHAT CHANGED AND WHY. This used to read `cls.type` through a cast and put the class in a
+   * map, which meant a class with no `static type` registered under the string "undefined", a
+   * second class under a taken name silently replaced the first, and a registered engine
+   * reached no catalogue at all -- so a third party's layout could run but could never be
+   * offered by a picker, described in a reader's language, or found by `layoutIdForEngine`.
+   *
+   * A third party's class must declare a `static descriptor` whose `id` equals its
+   * `static type`. The element's own nineteen are the one exemption, because their arrangements
+   * are authored centrally in the layout catalogue where several engines may sit behind one
+   * public name.
+   * @param cls - The layout engine class.
+   * @returns The same class, so a declaration can register itself in one expression.
+   * @throws A `GraphtyError` with `E_BAD_COMMAND` when the class declares no `static type`, no
+   * `static descriptor`, or a descriptor whose `id` disagrees with its `static type`; or with
+   * `E_DUPLICATE_PLUGIN` when the name or the descriptor id is one the element itself ships.
+   */
+  static register(t) {
+    const e = t, { type: s, descriptor: r } = e;
+    if (typeof s != "string" || s === "")
+      throw new g({
+        code: "E_BAD_COMMAND",
+        message: "a layout engine is filed under its `static type`, and this class declares none",
+        source: "registry",
+        details: { kind: "layout", field: "type" }
+      });
+    if (l.get(s) === t)
+      return t;
+    const n = C.includes(s);
+    if (r === void 0) {
+      if (!n)
+        throw new g({
+          code: "E_BAD_COMMAND",
+          message: `the layout "${s}" declares no \`static descriptor\`, so nothing could offer it: a picker reads the catalogue, and an engine the catalogue does not carry is reachable only by a consumer who already knows its name`,
+          source: "registry",
+          details: { kind: "layout", name: s, field: "descriptor" }
+        });
+      if (l.has(s))
+        throw A(s);
+      return l.set(s, t), t;
+    }
+    if (n)
+      throw A(s);
+    if (r.id !== s)
+      throw new g({
+        code: "E_BAD_COMMAND",
+        message: `the layout "${s}" describes itself as "${r.id}". A layout has ONE key: the name \`setLayout\` takes and the name the catalogue publishes are the same string, so nothing has to be named twice and a saved document means one thing`,
+        source: "registry",
+        details: { kind: "layout", name: s, field: "descriptor.id", id: r.id }
+      });
+    return z({
+      descriptor: { ...r, honoursWeights: e.honoursWeights ?? !1 },
+      type: s
+    }), l.set(s, t), t;
+  }
+  /**
+   * Get a layout engine instance by type
+   * @param type - The layout engine type identifier
+   * @param opts - Configuration options for the layout engine
+   * @returns A new layout engine instance or null if type not found
+   */
+  static get(t, e = {}) {
+    const s = l.get(t);
+    return s ? new s(e) : null;
+  }
+  /**
+   * Get dimension-specific options for this layout
+   * @param dimension - The desired dimension (2 or 3)
+   * @returns Options object for the dimension or null if unsupported
+   */
+  static getOptionsForDimension(t) {
+    return t > this.maxDimensions ? null : {};
+  }
+  /**
+   * Get dimension-specific options for a layout by type
+   * @param type - The layout engine type identifier
+   * @param dimension - The desired dimension (2 or 3)
+   * @returns Options object for the dimension or null if type not found or unsupported
+   */
+  static getOptionsForDimensionByType(t, e) {
+    const s = l.get(t);
+    return s ? s.getOptionsForDimension(e) : null;
+  }
+  /**
+   * Get the Zod-based options schema for this layout
+   * @returns The options schema, or an empty object if no schema defined
+   */
+  static getZodOptionsSchema() {
+    return this.zodOptionsSchema ?? {};
+  }
+  /**
+   * Check if this layout has a Zod-based options schema
+   * @returns true if the layout has options defined
+   */
+  static hasZodOptions() {
+    return this.zodOptionsSchema !== void 0 && Object.keys(this.zodOptionsSchema).length > 0;
+  }
+  /**
+   * Get a list of all registered layout types
+   * @returns Array of registered layout type identifiers
+   */
+  static getRegisteredTypes() {
+    return Array.from(l.keys());
+  }
+  /**
+   * Get a layout class by type
+   * @param type - The layout engine type identifier
+   * @returns The layout engine class or null if not found
+   */
+  static getClass(t) {
+    return l.get(t) ?? null;
+  }
+};
+E.honoursWeights = !1;
+let w = E;
+const V = O.looseObject({
+  scalingFactor: O.number().default(100)
+});
+class dt extends w {
+  /**
+   * Create a simple layout engine
+   * @param opts - Configuration options including scalingFactor
+   */
+  constructor(t = {}) {
+    super(), this._nodes = [], this._edges = [], this.stale = !0, this.positions = {}, this.scalingFactor = 100, this.isSettled = !0;
+    const e = V.parse(t);
+    this.scalingFactor = e.scalingFactor;
+  }
+  /**
+   * Get dimension-specific options for simple layouts
+   * @param dimension - The desired dimension (2 or 3)
+   * @returns Options object with dim parameter or null if unsupported
+   */
+  static getOptionsForDimension(t) {
+    return t > this.maxDimensions ? null : { dim: t };
+  }
+  // basic functionality
+  /**
+   * Initialize the layout engine
+   *
+   * Simple layouts compute positions synchronously and don't require initialization.
+   */
+  async init() {
+  }
+  /**
+   * Add a node to the layout and mark positions as stale
+   * @param n - The node to add
+   */
+  addNode(t) {
+    this._nodes.push(t), this.stale = !0;
+  }
+  /**
+   * Add an edge to the layout and mark positions as stale
+   * @param e - The edge to add
+   */
+  addEdge(t) {
+    this._edges.push(t), this.stale = !0;
+  }
+  /**
+   * Get the position of a node, computing layout if stale
+   *
+   * The coordinates come from the shared position array, which `SimpleLayoutEngine.refresh`
+   * fills from `positions` as soon as the layout is recomputed. They are the same numbers the
+   * record holds, rounded to the f32 the array stores -- so an arrangement never moves, but a
+   * coordinate may differ in its last digit or two from the double the layout function returned.
+   * A node with no row falls back to the record, which is every node in an engine driven by hand.
+   * @param n - The node to get position for
+   * @returns The node's position coordinates
+   */
+  getNodePosition(t) {
+    return this.refresh(), this.publishedOr(t, t.id);
+  }
+  /**
+   * Record where the reader has just put a node.
+   *
+   * A static layout recomputes every coordinate from scratch, so it has no per-node state a
+   * placement could live in -- which is why this used to do nothing at all, and why a drag
+   * under any of the fourteen static arrangements was discarded by the next `refresh()`. The
+   * placement is written into the SHARED array instead, with `"placement"` intent so that it
+   * lands even on a pinned row, and into the computed record so that a read which falls back to
+   * the record (a node with no row of its own) answers the same.
+   * @param n - the node that moved
+   * @param p - where it moved to
+   */
+  setNodePosition(t, e) {
+    const s = e.z ?? 0;
+    this.writeNodePosition(t, e.x, e.y, s, "placement"), this.positions[t.id] = [e.x / this.scalingFactor, e.y / this.scalingFactor, s / this.scalingFactor];
+  }
+  /**
+   * Get the position of an edge based on its endpoints
+   * @param e - The edge to get position for
+   * @returns The edge's source and destination positions
+   */
+  getEdgePosition(t) {
+    return this.refresh(), {
+      src: this.publishedOr(t.srcNode, t.srcId),
+      dst: this.publishedOr(t.dstNode, t.dstId)
+    };
+  }
+  /**
+   * Copy the computed layout into the shared position array, recomputing it first if it is stale.
+   */
+  publishPositions() {
+    if (this.stale) {
+      this.refresh();
+      return;
+    }
+    this.publishRecord();
+  }
+  // for animated layouts
+  /**
+   * Step the layout animation
+   *
+   * Simple layouts are static and don't animate, so stepping has no effect.
+   */
+  step() {
+  }
+  /**
+   * Take a node out of the layout.
+   *
+   * WITHOUT THIS the engine holds the removed node -- and through it the node's Babylon mesh,
+   * its data record and its endpoints -- for as long as the engine lives, and the frame loop
+   * keeps walking it, so a node the reader deleted still draws at wherever it last was.
+   *
+   * The computed record is left alone and the layout is marked stale instead. Every layout
+   * function here returns a WHOLE new record, which `doLayout` assigns over the old one, and
+   * `refresh()` runs before any read -- so the removed node's entry is gone by the time anything
+   * could read it, without this method having to reach into a keyed object by a computed name.
+   * @param n - the node leaving the graph
+   */
+  removeNode(t) {
+    const e = this._nodes.indexOf(t);
+    e >= 0 && this._nodes.splice(e, 1), this.stale = !0;
+  }
+  /**
+   * The edge half of {@link SimpleLayoutEngine.removeNode}, with the same reason.
+   * @param e - the edge leaving the graph
+   */
+  removeEdge(t) {
+    const e = this._edges.indexOf(t);
+    e >= 0 && this._edges.splice(e, 1), this.stale = !0;
+  }
+  /**
+   * Pin a node in place
+   *
+   * A static layout has nothing of its own to hold still -- it recomputes every position from
+   * scratch -- so the pin is kept by the element's position array instead, and
+   * `writeNodePosition` refuses to move a pinned row. That is what makes a
+   * pin mean something under all fourteen of these engines, none of which could hold one.
+   */
+  pin() {
+  }
+  /**
+   * Unpin a node
+   *
+   * The element's position array holds the pin; see {@link SimpleLayoutEngine.pin}.
+   */
+  unpin() {
+  }
+  // properties
+  /**
+   * Get all nodes in the layout
+   * @returns Iterable of nodes
+   */
+  get nodes() {
+    return this._nodes;
+  }
+  /**
+   * Get all edges in the layout
+   * @returns Iterable of edges
+   */
+  get edges() {
+    return this._edges;
+  }
+  /**
+   * Recompute the layout when it is stale, and publish what it produced.
+   *
+   * A simple layout is computed once and then held, so this is the ONE place the shared array is
+   * filled: every reader below goes through here first, which is why a node added after the last
+   * read still gets a row before anything asks for its coordinates.
+   */
+  refresh() {
+    this.stale && (this.doLayout(), this.stale = !1, this.publishRecord());
+  }
+  /**
+   * Write the computed record into the shared array, scaled to scene units.
+   *
+   * A node the layout function returned nothing for is LEFT UNPLACED rather than published at
+   * the origin: the two are indistinguishable once stored, and the origin is a place a reader
+   * would draw at.
+   */
+  publishRecord() {
+    for (const t of this._nodes) {
+      const e = this.positions[t.id];
+      !e || e.length === 0 || this.writeNodePosition(
+        t,
+        e[0] * this.scalingFactor,
+        e[1] * this.scalingFactor,
+        (e[2] ?? 0) * this.scalingFactor
+      );
+    }
+  }
+  /**
+   * A node's published row, or the computed record when it has no row of its own.
+   *
+   * The fallback is not a rare path: an engine driven directly -- by a test, or by a host that
+   * keeps no graph -- has nodes whose index is `INVALID_INDEX`, and none of them is ever
+   * published. Both branches produce the same arrangement; only the rounding differs.
+   * @param n - the node, when the caller has one
+   * @param id - the node's id, which is how the computed record is keyed
+   * @returns a fresh coordinate triple
+   */
+  publishedOr(t, e) {
+    const s = { x: 0, y: 0, z: 0 };
+    return t !== void 0 && this.readNodePosition(t, s) ? s : X(this.positions[e], this.scalingFactor);
+  }
+}
+function X(i, t) {
+  if (!i || i.length === 0)
+    return { x: 0, y: 0, z: 0 };
+  const e = i[0] * t, s = i[1] * t, r = (i[2] ?? 0) * t;
+  return { x: e, y: s, z: r };
+}
+const K = /^#[0-9a-f]{6}$/i;
+function q(i) {
+  if (typeof i != "string" || i.trim() === "")
+    return null;
+  try {
+    const t = v(i.trim());
+    if (t === void 0)
+      return null;
+    const e = t.length === 9 ? t.slice(0, 7) : t;
+    return K.test(e) ? e.toUpperCase() : null;
+  } catch {
+    return null;
+  }
+}
+function H(i) {
+  return JSON.stringify([i.id, i.kind, i.colors, i.capacity, i.colorblindSafe]);
+}
+const y = b({
+  kind: "palette",
+  idOf: (i) => i.id,
+  descriptorOf: (i) => i,
+  implementationOf: H,
+  builtInIds: () => k
+});
+function u(i, t, e) {
+  throw new g({
+    code: "E_BAD_COMMAND",
+    message: e,
+    source: "registry",
+    details: { kind: "palette", name: typeof i == "string" ? i : "", field: t }
+  });
+}
+function ut(i, t) {
+  typeof i != "object" && u("", "descriptor", "registerPalette takes a palette descriptor"), (i.plainName === void 0 || i.plainName === "") && u(i.id, "plainName", `the palette "${String(i.id)}" was registered without a plain name`), i.kind !== "sequential" && i.kind !== "diverging" && i.kind !== "categorical" && u(
+    i.id,
+    "kind",
+    `the palette "${String(i.id)}" must be sequential, diverging or categorical`
+  ), (!Array.isArray(i.colors) || i.colors.length === 0) && u(i.id, "colors", `the palette "${String(i.id)}" was registered with no colours`);
+  const e = [];
+  for (const r of i.colors) {
+    const n = q(r);
+    n === null && u(i.id, "colors", `"${String(r)}" in the palette "${String(i.id)}" is not a colour`), e.push(n);
+  }
+  const s = i.kind === "categorical" ? e.length : null;
+  i.capacity !== void 0 && i.capacity !== s && u(
+    i.id,
+    "capacity",
+    `the palette "${String(i.id)}" is ${i.kind}, so its capacity is ${s === null ? "null" : String(s)} rather than ${String(i.capacity)}`
+  ), y.register(
+    Object.freeze({
+      ...i,
+      colors: Object.freeze(e),
+      capacity: s,
+      colorblindSafe: Object.freeze(i.colorblindSafe ?? [])
+    }),
+    t
+  );
+}
+function pt() {
+  return y.descriptors();
+}
+function gt(i) {
+  return y.byId(i);
+}
+function ft() {
+  y.clearForTesting();
+}
+export {
+  x as E,
+  _ as F,
+  w as L,
+  o as P,
+  V as S,
+  nt as U,
+  P as W,
+  dt as a,
+  ht as b,
+  rt as c,
+  ft as d,
+  L as e,
+  lt as f,
+  pt as g,
+  st as h,
+  ot as i,
+  at as j,
+  G as k,
+  ct as l,
+  gt as m,
+  d as n,
+  it as p,
+  ut as r
+};