@graphty/cytoscape-extensions 0.0.0-placeholder.0 → 0.0.2

package/src/lazy.ts

@@ -0,0 +1,35 @@
+/**
+ * Loading the parts of the package that are fetched on first use (the generators and datasets, the file formats, the
+ * WebGPU code), with a warning when one never arrives.
+ */
+
+/** How long a part may take to load before the call warns that it may never load. */
+export const STALL_MS = 5000;
+
+/**
+ * A part of the package loaded on first use, warning on the console when it has not loaded after STALL_MS.
+ *
+ * In a Vite 6 or 7 (Rollup) production build, the part's chunk imports the chunk that holds the consumer's entry
+ * module, because both use @graphty/graph-format and Rollup puts shared code in the chunk that loads first. When that
+ * entry module awaits the call at its top level, the entry chunk is still evaluating, so the part can never run and
+ * the await never settles. ES modules report nothing, and no package layout avoids it (the package's synchronous
+ * methods need @graphty/graph-format up front), so the warning names the cause. A slow network shows it too; the
+ * call then carries on.
+ * @param load - the dynamic import
+ * @param call - what is waiting, as the reader wrote it ("graphtyDataset")
+ * @returns the import
+ */
+export function loadPart<T>(load: Promise<T>, call: string): Promise<T> {
+    const timer = setTimeout(() => {
+        console.warn(
+            `graphty: ${call} has waited ${String(STALL_MS / 1000)} s for part of @graphty/cytoscape-extensions to load. ` +
+                `If a module awaits ${call} at its top level, a Vite 6 or 7 production build never loads it: call it ` +
+                "inside an async function, or with .then(), instead. On a slow network the call carries on.",
+        );
+    }, STALL_MS);
+    const clear = (): void => {
+        clearTimeout(timer);
+    };
+    load.then(clear, clear);
+    return load;
+}

package/src/samples.ts

@@ -0,0 +1,273 @@
+/**
+ * `@graphty/cytoscape-extensions/samples`: the seeded generators and the sample datasets of @graphty/graph-samples
+ * as Cytoscape elements. cy.graphtyGenerate() and cy.graphtyDataset() load this module on their first call, and
+ * each bundled dataset is a module of its own, loaded only when it is asked for.
+ */
+
+import { fromEdgeArrays, type GraphSnapshot } from "@graphty/graph-format";
+import { DATASET_NAMES, fetchDataset, type FetchDatasetOptions, type SampleGraph } from "@graphty/graph-samples";
+import * as g from "@graphty/graph-samples/generators";
+import type { ElementDefinition } from "cytoscape";
+
+import { GENERATOR_OPTION_NAMES } from "./algorithm-options.js";
+import { flipY, snapshotToElements } from "./elements.js";
+
+/**
+ * Every generator by its name: the graph-samples function name in kebab case without "Graph". Each takes that
+ * function's options; the random ones take `seed` (default 0) and give the same graph for the same options on
+ * every platform.
+ */
+export const GENERATORS = {
+    ak: g.akGraph,
+    "balanced-tree": g.balancedTreeGraph,
+    "barabasi-albert": g.barabasiAlbertGraph,
+    barbell: g.barbellGraph,
+    "bianconi-barabasi": g.bianconiBarabasiGraph,
+    "bipartite-configuration-model": g.bipartiteConfigurationModelGraph,
+    caveman: g.cavemanGraph,
+    "chung-lu": g.chungLuGraph,
+    "circular-ladder": g.circularLadderGraph,
+    complete: g.completeGraph,
+    "complete-bipartite": g.completeBipartiteGraph,
+    "complete-multipartite": g.completeMultipartiteGraph,
+    "configuration-model": g.configurationModelGraph,
+    "connected-caveman": g.connectedCavemanGraph,
+    cycle: g.cycleGraph,
+    "degree-corrected-sbm": g.degreeCorrectedSbmGraph,
+    "directed-configuration-model": g.directedConfigurationModelGraph,
+    "duplication-divergence": g.duplicationDivergenceGraph,
+    empty: g.emptyGraph,
+    "erdos-renyi": g.erdosRenyiGraph,
+    "erdos-renyi-gnm": g.erdosRenyiGnmGraph,
+    "forest-fire": g.forestFireGraph,
+    genrmf: g.genrmfGraph,
+    grid: g.gridGraph,
+    "grid-3d": g.grid3dGraph,
+    "grid-flow-network": g.gridFlowNetwork,
+    "hexagonal-lattice": g.hexagonalLatticeGraph,
+    hyperbolic: g.hyperbolicGraph,
+    hypercube: g.hypercubeGraph,
+    knn: g.knnGraph,
+    kronecker: g.kroneckerGraph,
+    ladder: g.ladderGraph,
+    "layered-flow-network": g.layeredFlowNetwork,
+    lfr: g.lfrGraph,
+    lollipop: g.lollipopGraph,
+    "mobius-ladder": g.mobiusLadderGraph,
+    named: (o: { name: g.NamedGraphName } & g.WeightOptions) => {
+        // checked here: graph-samples' own error points at a list this package's readers cannot see
+        if (!(g.NAMED_GRAPH_NAMES as readonly string[]).includes(o.name)) {
+            throw unknownName("named graph", o.name, g.NAMED_GRAPH_NAMES);
+        }
+        return g.namedGraph(o.name, o);
+    },
+    "newman-watts": g.newmanWattsGraph,
+    path: g.pathGraph,
+    petersen: g.petersenGraph,
+    "planted-partition": g.plantedPartitionGraph,
+    price: g.priceGraph,
+    "random-apollonian": g.randomApollonianGraph,
+    "random-bipartite": g.randomBipartiteGraph,
+    "random-dag": g.randomDagGraph,
+    "random-geometric": g.randomGeometricGraph,
+    "random-order-dag": g.randomOrderDagGraph,
+    "random-recursive-tree": g.randomRecursiveTreeGraph,
+    "random-regular": g.randomRegularGraph,
+    "random-tree": g.randomTreeGraph,
+    "ring-of-cliques": g.ringOfCliquesGraph,
+    rmat: g.rmatGraph,
+    star: g.starGraph,
+    "stochastic-block-model": g.stochasticBlockModelGraph,
+    "triangular-lattice": g.triangularLatticeGraph,
+    "watts-strogatz": g.wattsStrogatzGraph,
+    waxman: g.waxmanGraph,
+    wheel: g.wheelGraph,
+    "wilson-maze": g.wilsonMazeGraph,
+} as const;
+
+/** A generator name. */
+export type GeneratorName = keyof typeof GENERATORS;
+
+/** The graphs the "named" generator knows, for `graphtyGenerate("named", { name })`. */
+export { NAMED_GRAPH_NAMES } from "@graphty/graph-samples/generators";
+
+/** The options of a generator. */
+export type GeneratorOptions<N extends GeneratorName> = Parameters<(typeof GENERATORS)[N]>[0];
+
+// One static specifier per dataset, so a bundler splits each into a chunk of its own.
+const BUNDLED: Record<string, () => Promise<SampleGraph>> = {
+    karate: () => import("@graphty/graph-samples/datasets/karate").then((m) => m.karate()),
+    "florentine-families": () =>
+        import("@graphty/graph-samples/datasets/florentine-families").then((m) => m.florentineFamilies()),
+    "davis-southern-women": () =>
+        import("@graphty/graph-samples/datasets/davis-southern-women").then((m) => m.davisSouthernWomen()),
+    "les-miserables": () => import("@graphty/graph-samples/datasets/les-miserables").then((m) => m.lesMiserables()),
+    football: () => import("@graphty/graph-samples/datasets/football").then((m) => m.football()),
+    "political-books": () => import("@graphty/graph-samples/datasets/political-books").then((m) => m.politicalBooks()),
+    dolphins: () => import("@graphty/graph-samples/datasets/dolphins").then((m) => m.dolphins()),
+    "contiguous-usa": () => import("@graphty/graph-samples/datasets/contiguous-usa").then((m) => m.contiguousUsa()),
+    "knuth-miles": () => import("@graphty/graph-samples/datasets/knuth-miles").then((m) => m.knuthMiles()),
+    "celegans-neural": () => import("@graphty/graph-samples/datasets/celegans-neural").then((m) => m.celegansNeural()),
+    "political-blogs": () => import("@graphty/graph-samples/datasets/political-blogs").then((m) => m.politicalBlogs()),
+    openflights: () => import("@graphty/graph-samples/datasets/openflights").then((m) => m.openflights()),
+    "yeast-perturbation": () =>
+        import("@graphty/graph-samples/datasets/yeast-perturbation").then((m) => m.yeastPerturbation()),
+    "stelzl-interactome": () =>
+        import("@graphty/graph-samples/datasets/stelzl-interactome").then((m) => m.stelzlInteractome()),
+    "wikipathways-senescence-autophagy": () =>
+        import("@graphty/graph-samples/datasets/wikipathways-senescence-autophagy").then((m) =>
+            m.wikipathwaysSenescenceAutophagy(),
+        ),
+    "go-slim-generic": () => import("@graphty/graph-samples/datasets/go-slim-generic").then((m) => m.goSlimGeneric()),
+};
+
+/** The datasets that ship inside @graphty/graph-samples; the hosted ones (graph-samples' DATASETS) are fetched. */
+export const BUNDLED_DATASET_NAMES: readonly string[] = Object.keys(BUNDLED);
+
+/**
+ * The number of single-character edits that turn one string into the other.
+ * @param a - one string
+ * @param b - the other
+ * @returns the Levenshtein distance
+ */
+function editDistance(a: string, b: string): number {
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = row;
+    }
+    return prev[b.length];
+}
+
+/**
+ * The error for an unknown name, naming the closest known one when one is close and listing them all.
+ * @param kind - what the name names ("dataset", "generator", "named graph")
+ * @param name - the unknown name
+ * @param names - the known names
+ * @returns a RangeError
+ */
+function unknownName(kind: string, name: string, names: readonly string[]): RangeError {
+    let best = "";
+    let bestDistance = Infinity;
+    for (const known of names) {
+        const d = editDistance(name, known);
+        if (d < bestDistance) {
+            best = known;
+            bestDistance = d;
+        }
+    }
+    const hint = bestDistance <= Math.max(2, name.length / 3) ? ` (did you mean ${JSON.stringify(best)}?)` : "";
+    return new RangeError(`unknown ${kind} ${JSON.stringify(name)}${hint}; the ${kind}s are ${names.join(", ")}`);
+}
+
+/** A generated graph or a dataset as Cytoscape element definitions. */
+export interface SampleElements {
+    /** The nodes, then the edges. Node ids are the dataset's names, or "0", "1", ... for a generated graph. */
+    readonly elements: ElementDefinition[];
+    /** Whether the graph is directed: pass it as `directed` to the algorithms. */
+    readonly directed: boolean;
+}
+
+/**
+ * The elements of a graph-samples graph.
+ * @param graph - the graph
+ * @returns the elements and the direction
+ */
+function fromSample(graph: SampleGraph | GraphSnapshot): SampleElements {
+    const snapshot = "src" in graph ? fromEdgeArrays(graph) : graph;
+    return { elements: snapshotToElements(snapshot), directed: snapshot.directed };
+}
+
+/**
+ * A generated graph with its coordinate columns `x` and `y` (the lattices with `positions: true`, and the geometric
+ * generators) as one position column, so they become node positions; `z` stays a data field.
+ * @param graph - the generated graph
+ * @returns the graph, its x and y as a position
+ */
+function withPosition(graph: SampleGraph): SampleGraph {
+    const { x, y, ...rest } = graph.nodeColumns ?? {};
+    if (!ArrayBuffer.isView(x) || !ArrayBuffer.isView(y)) {
+        return graph;
+    }
+    const xs = x as unknown as ArrayLike<number>;
+    const ys = y as unknown as ArrayLike<number>;
+    const xy = new Float64Array(2 * graph.nodeCount);
+    for (let i = 0; i < graph.nodeCount; i++) {
+        xy[2 * i] = xs[i];
+        xy[2 * i + 1] = ys[i];
+    }
+    return {
+        ...graph,
+        nodeColumns: { ...rest, position: { data: xy, decl: { dtype: "f64", components: 2, role: "position" } } },
+    };
+}
+
+/**
+ * Generates a graph. Ground-truth columns (`community`, `side`, `layer`, ...) become node data fields; weights
+ * become `data.weight`; coordinates (`x` and `y`) become node positions. Edge k gets the id "e<k>", so the same
+ * options and seed give the same element ids as well as the same graph.
+ * @param name - the generator
+ * @param options - the generator's options
+ * @returns the elements and the direction
+ * @throws RangeError for an unknown generator name, or an option the generator does not take
+ */
+export function generateElements<N extends GeneratorName>(name: N, options: GeneratorOptions<N>): SampleElements {
+    const make = (GENERATORS as Record<string, ((o: unknown) => SampleGraph) | undefined>)[name];
+    if (make === undefined) {
+        throw unknownName("generator", name, Object.keys(GENERATORS));
+    }
+    // a misspelled option (seeed, position) would otherwise run with the default and give a plausible graph
+    const known = GENERATOR_OPTION_NAMES[name] ?? [];
+    for (const [k, v] of Object.entries(options ?? {})) {
+        if (v !== undefined && !known.includes(k)) {
+            throw new RangeError(
+                `generator ${JSON.stringify(name)}: unknown option ${k}; the options are ${known.join(", ")}`,
+            );
+        }
+    }
+    const r = fromSample(withPosition(make(options)));
+    let k = 0;
+    for (const el of r.elements) {
+        // node ids are "0", "1", ..., so "e<k>" never collides with one
+        if (el.group === "edges") {
+            el.data.id = `e${String(k++)}`;
+        }
+    }
+    return r;
+}
+
+/**
+ * Loads a sample dataset: a bundled one from its own module, any other from graphty.app (see graph-samples'
+ * `DATASETS` for the list, with each one's source, citation and license). A drawn dataset's saved `x` and `y` become
+ * node positions, placed where Cytoscape drew them.
+ * @param name - the dataset name, e.g. "karate"
+ * @param options - for a hosted dataset: the base URL and fetch implementation; for any dataset, an abort signal
+ * @returns the elements and the direction
+ * @throws the signal's reason (an AbortError) when it is aborted before the dataset is decoded
+ * @throws RangeError for a name that is not a known dataset, unless `baseUrl` is given
+ */
+export async function datasetElements(name: string, options: FetchDatasetOptions = {}): Promise<SampleElements> {
+    // checked here too, not only by fetch: a bundled dataset is not fetched, and a custom fetch may ignore the signal
+    options.signal?.throwIfAborted();
+    const load = BUNDLED[name];
+    // only graphty.app's own list is checked: a custom baseUrl may serve any name
+    if (load === undefined && options.baseUrl === undefined && !DATASET_NAMES.includes(name)) {
+        throw unknownName("dataset", name, DATASET_NAMES);
+    }
+    const graph = load === undefined ? await fetchDataset(name, options) : await load();
+    options.signal?.throwIfAborted();
+    const r = fromSample(graph);
+    // a drawn dataset's saved x and y (y growing upward) become the position Cytoscape drew (y growing downward)
+    for (const el of r.elements) {
+        const { x, y } = el.data;
+        if (typeof x === "number" && typeof y === "number") {
+            el.position = { x, y: flipY(y) };
+            delete el.data.x;
+            delete el.data.y;
+        }
+    }
+    return r;
+}

package/src/snapshot.ts

@@ -0,0 +1,281 @@
+/**
+ * Conversion between Cytoscape elements and the graph-format snapshot every graphty layout and algorithm takes.
+ *
+ * A snapshot addresses nodes and edges by dense index. Here node index i is `nodes[i]` and edge index e is
+ * `edges[e]`, in the collection order Cytoscape gave, so a result array maps back to elements by position.
+ */
+
+import { fromEdgeArrays, type GraphSnapshot } from "@graphty/graph-format";
+import type { Collection, Core, EdgeCollection, EdgeSingular, NodeCollection } from "cytoscape";
+
+/** How to read a Cytoscape collection as a graph. */
+export interface SnapshotOptions {
+    /** Build a directed snapshot. Default false. */
+    readonly directed?: boolean | undefined;
+    /**
+     * The edge weight: an edge data field (a missing or non-numeric value counts as 1), or a function of the edge
+     * as Cytoscape's built-in algorithms take it. Default: unweighted. A function result is not cached.
+     */
+    readonly weight?: string | ((edge: EdgeSingular) => number) | undefined;
+}
+
+/** A node set given the Cytoscape way: a selector over the collection's nodes, or a collection. */
+export type NodeSelection = string | Collection | NodeCollection;
+
+/** A snapshot of a Cytoscape collection plus the element arrays its indices refer to. */
+export interface CytoscapeSnapshot {
+    readonly snapshot: GraphSnapshot;
+    /** Node index i is `nodes[i]`. */
+    readonly nodes: NodeCollection;
+    /** Edge index e is `edges[e]`: the collection's edges whose two endpoints are both in `nodes`. */
+    readonly edges: EdgeCollection;
+}
+
+interface CacheEntry {
+    readonly key: string;
+    readonly eles: Collection;
+    readonly version: number;
+    readonly value: CytoscapeSnapshot;
+}
+
+interface CoreState {
+    version: number;
+    entries: CacheEntry[];
+    /** Told about every snapshot the cache lets go of (a GPU device releases its upload of it). */
+    dropListeners: Set<(dropped: readonly GraphSnapshot[]) => void>;
+}
+
+const state = new WeakMap<Core, CoreState>();
+/** Runs still using each snapshot; a snapshot the cache drops while it has holds is released when the last ends. */
+const holds = new Map<GraphSnapshot, number>();
+/** Snapshots the cache dropped while held, and the core state whose listeners release them. */
+const deferred = new Map<GraphSnapshot, CoreState>();
+
+/**
+ * The core of a collection. Every collection has `cy()` at run time; Cytoscape's typings declare it only on single
+ * elements.
+ * @param eles - the collection
+ * @returns its core
+ */
+export function coreOf(eles: Collection | NodeCollection | EdgeCollection): Core {
+    return (eles as unknown as { cy(): Core }).cy();
+}
+
+/**
+ * The per-core cache state; the first call subscribes to the events that change the graph.
+ * @param cy - the core
+ * @returns its cache state
+ */
+function coreState(cy: Core): CoreState {
+    let s = state.get(cy);
+    if (s === undefined) {
+        const created: CoreState = { version: 0, entries: [], dropListeners: new Set() };
+        // ponytail: "data" fires for any field, so writing a result into data also invalidates; a per-field
+        // check would need Cytoscape to say which field changed, and it does not.
+        cy.on("add remove data move", () => {
+            created.version++;
+            drop(created, created.entries);
+            created.entries = [];
+        });
+        state.set(cy, created);
+        s = created;
+    }
+    return s;
+}
+
+/**
+ * Tells the drop listeners about entries leaving the cache.
+ * @param cs - the core's cache state
+ * @param gone - the entries
+ */
+function drop(cs: CoreState, gone: readonly CacheEntry[]): void {
+    const now: GraphSnapshot[] = [];
+    for (const { value } of gone) {
+        if (holds.has(value.snapshot)) {
+            deferred.set(value.snapshot, cs);
+        } else {
+            now.push(value.snapshot);
+        }
+    }
+    notify(cs, now);
+}
+
+/**
+ * Tells a core's drop listeners about snapshots to release.
+ * @param cs - the core's cache state
+ * @param snapshots - the snapshots
+ */
+function notify(cs: CoreState, snapshots: readonly GraphSnapshot[]): void {
+    if (snapshots.length > 0) {
+        for (const listener of cs.dropListeners) {
+            listener(snapshots);
+        }
+    }
+}
+
+/**
+ * Keeps a snapshot from being released while a run uses it: when the cache drops it (a data change, say) during
+ * the run, its release waits until every hold on it is let go.
+ * @param s - the snapshot
+ * @returns lets go of the hold; calling it again does nothing
+ */
+export function hold(s: GraphSnapshot): () => void {
+    holds.set(s, (holds.get(s) ?? 0) + 1);
+    let held = true;
+    return () => {
+        if (!held) {
+            return;
+        }
+        held = false;
+        const left = (holds.get(s) ?? 1) - 1;
+        if (left > 0) {
+            holds.set(s, left);
+            return;
+        }
+        holds.delete(s);
+        const cs = deferred.get(s);
+        if (cs !== undefined) {
+            deferred.delete(s);
+            notify(cs, [s]);
+        }
+    };
+}
+
+/**
+ * Subscribes to the snapshots a core's cache lets go of.
+ * @param cy - the core
+ * @param listener - called with the dropped snapshots
+ * @returns the unsubscriber
+ */
+export function onSnapshotsDropped(cy: Core, listener: (dropped: readonly GraphSnapshot[]) => void): () => void {
+    const cs = coreState(cy);
+    cs.dropListeners.add(listener);
+    return () => {
+        cs.dropListeners.delete(listener);
+    };
+}
+
+/**
+ * Builds (or returns the cached) snapshot of a collection. The cache holds one snapshot per option set per core and
+ * is dropped when an element is added, removed, moved to other endpoints, or has its data changed.
+ * @param eles - the collection to read: its nodes, and its edges whose endpoints are both in it
+ * @param options - directed flag and weight field
+ * @returns the snapshot and the element arrays its indices refer to
+ */
+export function toSnapshot(
+    eles: Collection | NodeCollection | EdgeCollection,
+    options: SnapshotOptions = {},
+): CytoscapeSnapshot {
+    const directed = options.directed ?? false;
+    const all = eles as Collection;
+    if (typeof options.weight === "function") {
+        return build(all, directed, options.weight);
+    }
+    const key = `${String(directed)}|${options.weight ?? ""}`;
+    const cs = coreState(coreOf(eles));
+    // the same elements in the same order: indices follow the collection's order, so a reordered one is another snapshot
+    const hit = cs.entries.find((e) => e.key === key && e.version === cs.version && sameOrder(e.eles, all));
+    if (hit !== undefined) {
+        return hit.value;
+    }
+    const value = build(all, directed, options.weight);
+    drop(
+        cs,
+        cs.entries.filter((e) => e.key === key),
+    );
+    cs.entries = [...cs.entries.filter((e) => e.key !== key), { key, eles: all, version: cs.version, value }];
+    return value;
+}
+
+/**
+ * Whether two collections hold the same elements in the same order.
+ * @param a - one collection
+ * @param b - the other
+ * @returns true when they match element by element
+ */
+function sameOrder(a: Collection, b: Collection): boolean {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Builds a snapshot without the cache.
+ * @param eles - the collection
+ * @param directed - whether the snapshot is directed
+ * @param weight - edge data field or function of the weight, or undefined for none
+ * @returns the snapshot and element arrays
+ */
+function build(eles: Collection, directed: boolean, weight: SnapshotOptions["weight"]): CytoscapeSnapshot {
+    const nodes = eles.nodes();
+    const ids: string[] = [];
+    const index = new Map<string, number>();
+    nodes.forEach((n, i) => {
+        ids.push(n.id());
+        index.set(n.id(), i);
+    });
+    const edges = eles.edges().filter((e) => index.has(e.source().id()) && index.has(e.target().id()));
+    const src = new Uint32Array(edges.length);
+    const dst = new Uint32Array(edges.length);
+    const weights = weight === undefined ? undefined : new Float64Array(edges.length);
+    edges.forEach((e, k) => {
+        src[k] = index.get(e.source().id()) ?? 0;
+        dst[k] = index.get(e.target().id()) ?? 0;
+        if (weights !== undefined && weight !== undefined) {
+            const w: unknown = typeof weight === "function" ? weight(e) : e.data(weight);
+            weights[k] = typeof w === "number" && Number.isFinite(w) ? w : 1;
+        }
+    });
+    const snapshot = fromEdgeArrays({ directed, ids, src, dst, weights });
+    return { snapshot, nodes, edges };
+}
+
+/**
+ * Writes one value per element into its data, in one batch (one style pass).
+ * @param elements - `nodes` or `edges` of a CytoscapeSnapshot, in index order
+ * @param values - one value per element
+ * @param field - the data field to write
+ */
+export function writeData(elements: NodeCollection | EdgeCollection, values: ArrayLike<number>, field: string): void {
+    coreOf(elements).batch(() => {
+        elements.forEach((ele, i) => {
+            ele.data(field, values[i]);
+        });
+    });
+}
+
+/**
+ * Indices of the snapshot's nodes in a selection.
+ * @param cs - the snapshot
+ * @param sel - a selector or a collection
+ * @returns the node indices, in collection order
+ */
+export function indicesOf(cs: CytoscapeSnapshot, sel: NodeSelection): number[] {
+    const picked = typeof sel === "string" ? cs.nodes.filter(sel) : cs.nodes.intersection(sel);
+    return picked.map((n) => cs.snapshot.ids.requireIndex(n.id()));
+}
+
+/**
+ * The index of the first node of a selection.
+ * @param cs - the snapshot
+ * @param sel - a selector or a collection, or undefined
+ * @param what - the option name, for the error
+ * @returns the index, or undefined when no selection was given
+ * @throws Error when the selection matches no node of the snapshot
+ */
+export function indexOf(cs: CytoscapeSnapshot, sel: NodeSelection | undefined, what: string): number | undefined {
+    if (sel === undefined) {
+        return undefined;
+    }
+    const [i] = indicesOf(cs, sel);
+    if (i === undefined) {
+        throw new Error(`${what} matches no node of the collection`);
+    }
+    return i;
+}

package/src/webgpu-provider.ts

@@ -0,0 +1,67 @@
+/**
+ * The device provider both platform builds (browser and Node) return: probe, request a context, check that the
+ * device computes correctly, build the accelerator. Everything here happens before any graph work, so a refusal is
+ * detection (the CPU runs and the result says why), never a fallback.
+ *
+ * Only the lazily loaded "#gpu-platform" chunk imports this module, so @graphty/webgpu-graph-algorithms stays out of
+ * the main chunk.
+ */
+
+import { createAccelerator, type GpuContext, type ProbeResult, verifyDevice } from "@graphty/webgpu-graph-algorithms";
+
+import { type GpuProvider, GpuUnavailableError, type WebGpuOptions } from "./gpu.js";
+
+// The GPU package warns once when more than 2 snapshots are resident (its default); the adapter caches one snapshot
+// per directed/weight combination per core and releases each when the cache drops it, so a few are normal.
+const RESIDENT_SNAPSHOTS = 8;
+
+/** How one platform probes for a device and opens a context on it. */
+export interface Platform {
+    probe(rejectSoftware: boolean): Promise<ProbeResult>;
+    open(probe: ProbeResult, rejectSoftware: boolean, residentSnapshots: number): Promise<GpuContext>;
+    /** What the user can do about a refusal code on this platform; codes it does not name have no fix. */
+    readonly fixes: Readonly<Record<string, string>>;
+}
+
+/** The fix of a refused software adapter, on every platform. */
+const SOFTWARE_FIX = "call configureWebGpu({ acceptSoftware: true }) to accept the software adapter";
+
+/**
+ * A provider for a platform.
+ * @param platform - the platform's probe, context factory and fixes
+ * @param options - the options
+ * @returns the provider
+ */
+export function providerFor(platform: Platform, options: WebGpuOptions): GpuProvider {
+    return {
+        acquire: async () => {
+            const rejectSoftware = options.acceptSoftware !== true;
+            const probe = await platform.probe(rejectSoftware);
+            if (!probe.ok) {
+                const fix = probe.code === "E_SOFTWARE_ONLY" ? SOFTWARE_FIX : (platform.fixes[probe.code] ?? null);
+                throw new GpuUnavailableError(probe.code, probe.reason ?? probe.code, fix);
+            }
+            const ctx = await platform.open(probe, rejectSoftware, RESIDENT_SNAPSHOTS);
+            try {
+                // The GPU package's compute entry points refuse a device that fails this check, mid-run. Checking
+                // here decides up front, so such a device means the CPU, not an error from the first call.
+                const check = await verifyDevice(ctx);
+                if (check.mismatch !== null) {
+                    throw new GpuUnavailableError(
+                        "E_DEVICE_INCORRECT",
+                        `the ${check.vendor} device computes a known prefix sum incorrectly (${check.mismatch.where})`,
+                    );
+                }
+                const { caps } = ctx;
+                return {
+                    accelerator: createAccelerator(ctx),
+                    device: `${caps.vendor} ${caps.device === "" ? caps.description : caps.device}`,
+                    lost: ctx.lost.then((info) => (info.message === "" ? info.reason : info.message)),
+                };
+            } catch (error) {
+                ctx.dispose();
+                throw error;
+            }
+        },
+    };
+}