@graphty/cytoscape-extensions 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/cytoscape-extensions",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "Graphty layouts, algorithms, graph generators, sample datasets and file import/export as Cytoscape.js extensions",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -71,9 +71,9 @@
   },
   "homepage": "https://github.com/graphty-org/graphty-monorepo/tree/master/cytoscape-extensions#readme",
   "dependencies": {
-    "@graphty/graph-io": "^0.3.35",
-    "@graphty/webgpu-graph-algorithms": "^0.6.45",
-    "@graphty/graph-samples": "^0.1.27"
+    "@graphty/graph-io": "^0.3.36",
+    "@graphty/graph-samples": "^0.1.28",
+    "@graphty/webgpu-graph-algorithms": "^0.6.47"
   },
   "peerDependencies": {
     "@graphty/algorithms": "^3.0.0",
@@ -102,9 +102,9 @@
     "typescript": "^5.9.3",
     "vite": "^7.0.5",
     "vitest": "4.1.11",
-    "@graphty/graph-format": "^1.3.12",
-    "@graphty/layout": "^2.4.0",
-    "@graphty/algorithms": "^3.4.2"
+    "@graphty/algorithms": "^3.4.3",
+    "@graphty/graph-format": "^1.3.13",
+    "@graphty/layout": "^2.4.2"
   },
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && vite build --config vite.bundle.config.ts --mode cdn --logLevel warn && vite build --config vite.bundle.config.ts --logLevel warn",

package/src/algorithms.ts

@@ -136,7 +136,16 @@ import type {
 } from "cytoscape";
 
 import { OPTION_NAMES } from "./algorithm-options.js";
-import { type Backend, backendOf, checkGpuMode, gpuFor, type GpuMode, recording, warnIfFixable } from "./gpu.js";
+import {
+    type Backend,
+    backendOf,
+    checkGpuMode,
+    coreDestroyedError,
+    gpuFor,
+    type GpuMode,
+    recording,
+    warnIfFixable,
+} from "./gpu.js";
 import {
     coreOf,
     type CytoscapeSnapshot,
@@ -1859,7 +1868,12 @@ function runSync(eles: Collection, key: keyof Impls, options: AlgorithmOptions =
  */
 async function runAsync(eles: Collection, key: keyof Impls, options: AlgorithmOptions = {}): Promise<unknown> {
     checkGpuMode(`${methodName(key)}Async`, options?.gpu);
-    const d = await gpuFor(coreOf(eles), options.gpu);
+    const cy = coreOf(eles);
+    const d = await gpuFor(cy, options.gpu);
+    // destroyed while the device was acquired: its device is disposed and its elements are gone with it
+    if (cy.destroyed()) {
+        throw coreDestroyedError();
+    }
     const rec = d.gpu === null ? null : recording(d.gpu.accelerator);
     warnIfFixable(d, eles.nodes().length);
     const { result, snapshot } = run(eles, key, options, accelerated(rec?.accelerator ?? null));
@@ -1868,6 +1882,9 @@ async function runAsync(eles: Collection, key: keyof Impls, options: AlgorithmOp
     let value: object;
     try {
         value = (await result) as object;
+    } catch (e) {
+        // destroyed mid-run, the device fails with "GpuContext is disposed"; the cause is the destroy
+        throw cy.destroyed() ? coreDestroyedError() : e;
     } finally {
         unhold();
         if (d.gpu !== null && typeof options.weight === "function") {

package/src/elements.ts

@@ -23,29 +23,6 @@ function plain(v: unknown): unknown {
     return ArrayBuffer.isView(v) ? Array.from(v as unknown as ArrayLike<number>) : v;
 }
 
-/**
- * RGB(A) channels in 0..1 as a CSS color: `#rrggbb` when opaque, `rgba(r, g, b, a)` otherwise.
- * @param c - the channels
- * @returns the color
- */
-function cssColor(c: ArrayLike<number>): string {
-    const ch = (i: number): number => Math.max(0, Math.min(255, Math.round(c[i] * 255)));
-    const a = c.length > 3 ? Math.round(c[3] * 1000) / 1000 : 1;
-    if (a === 1) {
-        return `#${[0, 1, 2].map((i) => ch(i).toString(16).padStart(2, "0")).join("")}`;
-    }
-    return `rgba(${ch(0)}, ${ch(1)}, ${ch(2)}, ${a})`;
-}
-
-/**
- * Whether a column is a color: the role "color" with 3 or 4 numeric components (GEXF's viz:color).
- * @param c - the column
- * @returns true for a color column
- */
-function isColor(c: Column): boolean {
-    return c.meta.role === "color" && (c.meta.components === 3 || c.meta.components === 4) && c.dtype !== "json";
-}
-
 /**
  * A y coordinate between Cytoscape (y grows downward) and graph-io (y grows upward, so a Cytoscape-family file's
  * screen y is negated on import and negated back on export). Never yields -0.
@@ -56,9 +33,6 @@ export function flipY(y: number): number {
     return y === 0 ? 0 : -y;
 }
 
-/** Reads a CSS color as RGBA channels in 0..1, or undefined when it cannot. */
-type ColorParser = (text: string) => [number, number, number, number] | undefined;
-
 /** A column that arrives under another data field name, because Cytoscape reserves its own. */
 interface RenamedColumn {
     readonly domain: "node" | "edge";
@@ -70,7 +44,6 @@ interface RenamedColumn {
  * Cytoscape element definitions for a snapshot. Node ids are the snapshot's ids as strings. Every node and edge
  * column becomes a data field of the same name, except that one named `id`, `source`, `target` or `parent` (which
  * Cytoscape reserves) becomes `<name>#<the attribute's id in the file>`, or `<name>#2` when it has none, and:
- * - a column with the role "color" (GEXF's viz:color) becomes a CSS color string, `#rrggbb` or `rgba(r, g, b, a)`;
  * - a node column with the role "position" becomes the node's position (x and y; a z is dropped);
  * - a node column with the role "parent" (a compound parent, as Cytoscape JSON, GraphML nested graphs and DOT
  *   clusters carry it) becomes `data.parent`;
@@ -153,8 +126,7 @@ function rowData(cols: readonly Column[], row: number, fieldOf: (c: Column) => s
     const data: Record<string, unknown> = {};
     for (const c of cols) {
         if (c.isSet(row)) {
-            const v = c.value(row);
-            data[fieldOf(c)] = isColor(c) ? cssColor(v as ArrayLike<number>) : plain(v);
+            data[fieldOf(c)] = plain(c.value(row));
         }
     }
     return data;
@@ -287,30 +259,12 @@ function column(values: unknown[], label: boolean): ColumnInput | undefined {
     return { data: values.map((v) => v ?? undefined), decl: { dtype: "json" } };
 }
 
-/**
- * A string column of CSS colors as a color column (role "color", RGBA in 0..1), which GEXF writes as viz:color.
- * @param c - the column
- * @param parse - reads one color
- * @returns the color column, or undefined when it is not a string column or a value is not a color `parse` reads
- */
-function colorColumn(c: ColumnInput, parse: ColorParser): ColumnInput | undefined {
-    if (c.decl.dtype !== "string") {
-        return undefined;
-    }
-    const rows = (c.data as (string | null)[]).map((v) => (v === null ? null : parse(v)));
-    if (rows.includes(undefined)) {
-        return undefined;
-    }
-    return { data: rows, decl: { dtype: "f32", components: 4, role: "color" } };
-}
-
 /**
  * The columns of a set of elements' data, one per field, skipping the reserved ones.
  * @param records - each element's data
- * @param colors - when given, a `color` field whose every value it reads is written as the role "color"
  * @returns the columns by name
  */
-function columns(records: readonly Record<string, unknown>[], colors?: ColorParser): Record<string, ColumnInput> {
+function columns(records: readonly Record<string, unknown>[]): Record<string, ColumnInput> {
     const names = new Set<string>();
     for (const r of records) {
         for (const k of Object.keys(r)) {
@@ -326,7 +280,7 @@ function columns(records: readonly Record<string, unknown>[], colors?: ColorPars
             name === "label",
         );
         if (c !== undefined) {
-            out[name] = colors !== undefined && name === "color" ? (colorColumn(c, colors) ?? c) : c;
+            out[name] = c;
         }
     }
     return out;
@@ -342,8 +296,6 @@ function columns(records: readonly Record<string, unknown>[], colors?: ColorPars
  * @param eles - the collection
  * @param options - the direction and the id type
  * @param options.directed - write a directed graph (default false)
- * @param options.colors - reads a CSS color as RGBA in 0..1; when given, a `color` data field whose every value it
- * reads is written as the role "color", for a format with a color slot of its own (GEXF's viz:color)
  * @param options.integerIds - when every node id is a non-negative integer written plainly ("0", "17"), give the
  * snapshot number ids, so a format that holds only integer ids (GML, CX2) writes them as they are (default false)
  * @returns the snapshot
@@ -353,7 +305,6 @@ export function elementsToSnapshot(
     options: {
         readonly directed?: boolean | undefined;
         readonly integerIds?: boolean | undefined;
-        readonly colors?: ColorParser | undefined;
     } = {},
 ): GraphSnapshot {
     const nodes = eles.nodes();
@@ -378,10 +329,7 @@ export function elementsToSnapshot(
         xy[2 * i + 1] = flipY(p.y);
     });
     const parents = nodes.map((n) => index.get(n.parent().first().id()) ?? null);
-    const edgeColumns = columns(
-        edges.map((e) => e.data() as Record<string, unknown>),
-        options.colors,
-    );
+    const edgeColumns = columns(edges.map((e) => e.data() as Record<string, unknown>));
     let weights: Float64Array<ArrayBuffer> | undefined;
     const w = edgeColumns.weight;
     if (w?.decl.dtype === "f64" && (w.data as unknown[]).every((v) => v !== null)) {
@@ -395,10 +343,7 @@ export function elementsToSnapshot(
         dst,
         weights,
         nodeColumns: {
-            ...columns(
-                nodes.map((n) => n.data() as Record<string, unknown>),
-                options.colors,
-            ),
+            ...columns(nodes.map((n) => n.data() as Record<string, unknown>)),
             position: { data: xy, decl: { dtype: "f64", components: 2, role: "position" } },
             ...(parents.some((p) => p !== null)
                 ? { parent: { data: parents, decl: { dtype: "u32", role: "parent", refersTo: "node" } } }

package/src/gpu.ts

@@ -57,6 +57,14 @@ export class GpuUnavailableError extends Error {
     }
 }
 
+/**
+ * The error a call on a destroyed Cytoscape core rejects with, or a layout run started on one emits as layouterror.
+ * @returns the error, `code` "E_CORE_DESTROYED"
+ */
+export function coreDestroyedError(): Error & { readonly code: "E_CORE_DESTROYED" } {
+    return Object.assign(new Error("graphty: the Cytoscape core was destroyed"), { code: "E_CORE_DESTROYED" as const });
+}
+
 /** Probes, constructs and verifies a device, or throws GpuUnavailableError. */
 export interface GpuProvider {
     acquire(): Promise<AcquiredGpu>;
@@ -333,7 +341,7 @@ export async function gpuFor(cy: Core, mode: GpuMode = "auto"): Promise<Decision
             d = { gpu: null, ...src };
         } else {
             if (g.destroyed) {
-                throw new Error("graphty: the Cytoscape core was destroyed");
+                throw coreDestroyedError();
             }
             if (g.decision === null || g.by !== src) {
                 disposeWhenDecided(g.decision);

package/src/graph-data.ts

@@ -8,6 +8,7 @@ import type { ImportInput, ImportReport } from "@graphty/graph-io";
 import type { FetchDatasetOptions } from "@graphty/graph-samples";
 import type { Collection, CollectionReturnValue, Core, ElementDefinition } from "cytoscape";
 
+import { coreDestroyedError } from "./gpu.js";
 import type { ExportFormat, ExportOptions, ImportFormat, ImportOptions } from "./io.js";
 import { loadPart } from "./lazy.js";
 import type { GeneratorName, GeneratorOptions } from "./samples.js";
@@ -108,8 +109,13 @@ export class IdTakenError extends Error {
  * @param elements - the definitions; edge data may be changed
  * @returns the added elements
  * @throws IdTakenError naming the first node id the core already holds; nothing is added
+ * @throws Error coded E_CORE_DESTROYED when the core was destroyed (before the call or while it loaded); nothing
+ * is added
  */
 function addTo(cy: Core, elements: ElementDefinition[]): CollectionReturnValue {
+    if (cy.destroyed()) {
+        throw coreDestroyedError();
+    }
     for (const el of elements) {
         if (el.group === "nodes" && el.data.id !== undefined && cy.getElementById(el.data.id).nonempty()) {
             throw new IdTakenError(el.data.id);

package/src/io.ts

@@ -163,46 +163,6 @@ function lostForCytoscape(n: LossNote): boolean {
     return !(n.code === "W_ROLE_DROPPED" && n.column === "label");
 }
 
-/**
- * A CSS color as RGBA channels in 0..1: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()` and
- * `hsla()` with comma-separated arguments. A named color ("red") is not read.
- * @param text - the color
- * @returns the channels, or undefined when the text is not one of those forms
- */
-function parseCssColor(text: string): [number, number, number, number] | undefined {
-    const s = text.trim().toLowerCase();
-    const hex = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.exec(s)?.[1];
-    if (hex !== undefined) {
-        const pairs = hex.length <= 4 ? Array.from(hex, (h) => h + h) : (hex.match(/../g) ?? []);
-        const [r, g, b, a = 255] = pairs.map((h) => Number.parseInt(h, 16) / 255);
-        return [r, g, b, a === 255 ? 1 : a];
-    }
-    const fn = /^(rgba?|hsla?)\(([^)]*)\)$/.exec(s);
-    const args = fn?.[2].split(",").map((a) => a.trim());
-    if (fn === undefined || fn === null || args === undefined || (args.length !== 3 && args.length !== 4)) {
-        return undefined;
-    }
-    // each argument: a number, or a percentage of `full`
-    const num = (a: string, full: number): number =>
-        a.endsWith("%") ? (Number(a.slice(0, -1)) / 100) * full : Number(a);
-    const alpha = args.length === 4 ? num(args[3], 1) : 1;
-    let rgb: number[];
-    if (fn[1].startsWith("rgb")) {
-        rgb = args.slice(0, 3).map((a) => num(a, 255) / 255);
-    } else {
-        const h = Number(args[0].replace(/deg$/, ""));
-        const sat = num(args[1], 1);
-        const l = num(args[2], 1);
-        const k = (n: number): number => (n + h / 30) % 12;
-        const c = sat * Math.min(l, 1 - l);
-        rgb = [0, 8, 4].map((n) => l - c * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1)));
-    }
-    const out = [...rgb, alpha];
-    return out.every((v) => Number.isFinite(v) && v >= 0 && v <= 1)
-        ? (out as [number, number, number, number])
-        : undefined;
-}
-
 /** The formats that hold only integer node ids: a graph whose ids are all integers is written with them as they are. */
 const INTEGER_ID_FORMATS: ReadonlySet<ExportFormat> = new Set(["gml", "cx2"]);
 
@@ -229,8 +189,6 @@ export async function exportElements(
     const snapshot = elementsToSnapshot(eles, {
         directed,
         integerIds: INTEGER_ID_FORMATS.has(format),
-        // GEXF owns the name "color" for viz:color: a plain "color" field would read back renamed
-        colors: format === "gexf" ? parseCssColor : undefined,
     });
     const graphOptions = {
         sanitizeIds: "mangle" as const,

package/src/layouts.ts

@@ -55,7 +55,16 @@ import type {
     Position,
 } from "cytoscape";
 
-import { type Backend, backendOf, checkGpuMode, cpuWithoutAsking, gpuFor, type GpuMode, warnIfFixable } from "./gpu.js";
+import {
+    type Backend,
+    backendOf,
+    checkGpuMode,
+    coreDestroyedError,
+    cpuWithoutAsking,
+    gpuFor,
+    type GpuMode,
+    warnIfFixable,
+} from "./gpu.js";
 import { type CytoscapeSnapshot, hold, indexOf, indicesOf, type NodeSelection, toSnapshot } from "./snapshot.js";
 
 /**
@@ -363,7 +372,10 @@ export const LAYOUT_NAMES: readonly string[] = [...Object.keys(STATIC), ...Objec
  */
 function box(bb: BoundingBox12 | BoundingBoxWH | undefined, cy: Core): BoundingBoxWH {
     if (bb === undefined) {
-        return { x1: 0, y1: 0, w: cy.width(), h: cy.height() };
+        // a container detached from the page reads NaN (its computed padding is empty); use Cytoscape's own size
+        // for a core without a container, 1 x 1
+        const finite = (v: number): number => (Number.isFinite(v) ? v : 1);
+        return { x1: 0, y1: 0, w: finite(cy.width()), h: finite(cy.height()) };
     }
     return "w" in bb ? bb : { x1: bb.x1, y1: bb.y1, w: bb.x2 - bb.x1, h: bb.y2 - bb.y1 };
 }
@@ -567,7 +579,7 @@ function runStatic(layout: LayoutThis, fn: StaticLayout): void {
  * @returns a promise only when the simulation is asynchronous
  */
 function stepToEnd(sim: LayoutSimulation, layout: LayoutThis): void | Promise<void> {
-    while (!sim.settled && !layout.stopped) {
+    while (!sim.settled && !layout.stopped && !layout.options.cy.destroyed()) {
         const r = sim.step(50);
         if (r instanceof Promise) {
             return r.then(() => stepToEnd(sim, layout));
@@ -610,7 +622,7 @@ function runSimulation(layout: LayoutThis, type: SimulationType): void {
             layout.looping = false;
             layout.backend = backendOf(d, d.gpu !== null, "");
             warnIfFixable(d, o.eles.nodes().length);
-            if (layout.stopped) {
+            if (layout.stopped || o.cy.destroyed()) {
                 layout.emit({ type: "layoutstop", layout });
                 return;
             }
@@ -618,7 +630,10 @@ function runSimulation(layout: LayoutThis, type: SimulationType): void {
         })
         .catch((error: unknown) => {
             layout.looping = false;
-            layout.emit("layouterror", [error]);
+            // the core destroyed meanwhile ends the run as stop() would
+            if (!o.cy.destroyed()) {
+                layout.emit("layouterror", [error]);
+            }
             layout.emit({ type: "layoutstop", layout });
         });
 }
@@ -658,12 +673,7 @@ function simulate(layout: LayoutThis, type: SimulationType, accelerator: LayoutA
             `graphty-spring-electrical has no CPU simulation and runs only on the GPU; no GPU ran because ${reason}`,
         );
         // reported as gpu: "require" reports it, after run() returns, whether or not the GPU was asked for
-        layout.looping = true;
-        void Promise.resolve().then(() => {
-            layout.looping = false;
-            layout.emit("layouterror", [error]);
-            layout.emit({ type: "layoutstop", layout });
-        });
+        failLater(layout, error);
         return;
     }
     const cs = layoutSnapshot(o);
@@ -735,10 +745,14 @@ function simulate(layout: LayoutThis, type: SimulationType, accelerator: LayoutA
 
     // Fitted to the box as a static result is; with a locked node, the free nodes are scaled about the locked ones
     const xy = (): ArrayLike<number> => (anyLocked ? fitAroundLocked(pos, fixed, n, b) : fitRows(pos, 3, n, b));
+    // A core destroyed mid-run ends the run as stop() would: its device is gone with it ("GpuContext is disposed"),
+    // and a write to it fails in Cytoscape ("reading 'notify'" of its null renderer).
     const fail = (error: unknown): void => {
         layout.looping = false;
         dispose();
-        layout.emit("layouterror", [error]);
+        if (!o.cy.destroyed()) {
+            layout.emit("layouterror", [error]);
+        }
         layout.emit({ type: "layoutstop", layout });
     };
 
@@ -746,7 +760,11 @@ function simulate(layout: LayoutThis, type: SimulationType, accelerator: LayoutA
         const done = (): void => {
             layout.looping = false;
             dispose();
-            finishDiscrete(layout, cs.nodes, xy());
+            if (o.cy.destroyed()) {
+                layout.emit({ type: "layoutstop", layout });
+            } else {
+                finishDiscrete(layout, cs.nodes, xy());
+            }
         };
         const r = stepToEnd(sim, layout);
         if (r === undefined) {
@@ -766,7 +784,19 @@ function simulate(layout: LayoutThis, type: SimulationType, accelerator: LayoutA
         typeof requestAnimationFrame === "function"
             ? requestAnimationFrame
             : (f: () => void): unknown => setTimeout(f, 16);
+    const end = (): void => {
+        layout.looping = false;
+        dispose();
+        if (o.stop !== undefined) {
+            layout.one("layoutstop", o.stop);
+        }
+        layout.emit({ type: "layoutstop", layout });
+    };
     const draw = (): void => {
+        if (o.cy.destroyed()) {
+            end();
+            return;
+        }
         cs.nodes.positions(positionOf(xy()));
         if (o.fit !== false) {
             o.cy.fit(o.eles, o.padding);
@@ -779,18 +809,13 @@ function simulate(layout: LayoutThis, type: SimulationType, accelerator: LayoutA
             layout.emit({ type: "layoutready", layout });
         }
         if (sim.settled || layout.stopped) {
-            layout.looping = false;
-            dispose();
-            if (o.stop !== undefined) {
-                layout.one("layoutstop", o.stop);
-            }
-            layout.emit({ type: "layoutstop", layout });
+            end();
         } else {
             schedule(tick);
         }
     };
     const tick = (): void => {
-        if (layout.stopped) {
+        if (layout.stopped || o.cy.destroyed()) {
             draw();
             return;
         }
@@ -810,15 +835,33 @@ function simulate(layout: LayoutThis, type: SimulationType, accelerator: LayoutA
     tick();
 }
 
+/**
+ * Ends a run that never started: layouterror with the error, then layoutstop, after run() returns.
+ * @param layout - the layout
+ * @param error - the error
+ */
+function failLater(layout: LayoutThis, error: Error): void {
+    layout.looping = true;
+    void Promise.resolve().then(() => {
+        layout.looping = false;
+        layout.emit("layouterror", [error]);
+        layout.emit({ type: "layoutstop", layout });
+    });
+}
+
 /** Each layout object's run body, set by its registrant's constructor. */
 const RUN_BODIES = new WeakMap<LayoutThis, (layout: LayoutThis) => void>();
 
 /**
- * A registrant's run(): runs the layout's body.
+ * A registrant's run(): runs the layout's body, or refuses a destroyed core with E_CORE_DESTROYED.
  * @returns the layout
  */
 function runLayout(this: LayoutThis): LayoutThis {
-    RUN_BODIES.get(this)?.(this);
+    if (this.options.cy.destroyed()) {
+        failLater(this, coreDestroyedError());
+    } else {
+        RUN_BODIES.get(this)?.(this);
+    }
     return this;
 }