@graphty/webgpu-graph-algorithms 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "WebGPU-accelerated graph algorithms and layouts over the @graphty/graph-format snapshot, for Node (Dawn) and browsers",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -60,12 +60,12 @@
   "homepage": "https://github.com/graphty-org/graphty-monorepo/tree/master/webgpu-graph-algorithms#readme",
   "dependencies": {
     "@webgpu/types": "^0.1.72",
-    "@graphty/graph-format": "^1.0.0"
+    "@graphty/graph-format": "^1.0.1"
   },
   "peerDependencies": {
     "@graphty/algorithms": "^1.0.0",
     "@graphty/graph-format": "^1.0.0",
-    "@graphty/layout": "^1.0.0",
+    "@graphty/layout": "^1.6.2",
     "webgpu": ">=0.4.0 <1.0.0"
   },
   "peerDependenciesMeta": {
@@ -89,7 +89,8 @@
     "typescript": "^5.9.3",
     "vite": "^7.0.5",
     "vitest": "^3.2.4",
-    "webgpu": "0.4.0"
+    "webgpu": "0.4.0",
+    "@graphty/layout": "^1.7.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/src/accelerator.ts

@@ -1,7 +1,9 @@
 /**
  * createAccelerator (spec 3.3, 9; contract 3.14): the injectable object that satisfies the CPU packages'
- * AlgorithmAccelerator and LayoutAccelerator interfaces STRUCTURALLY (spec 9.2, 9.3; the mirrors of
- * src/types/accelerator.ts until W1, D27). It carries P3's `forceAtlas2`, `release` and `dispose` and P7's seven
+ * AlgorithmAccelerator and LayoutAccelerator interfaces (spec 9.2, 9.3; D27). Since W1b `LayoutAccelerator` is
+ * the REAL `@graphty/layout` declaration, `import type`d by src/types/accelerator.ts; the AlgorithmAccelerator half
+ * is still satisfied STRUCTURALLY against that file's mirror until M8a gives it something real. It carries P3's
+ * `forceAtlas2`, `release` and `dispose` and P7's seven
  * algorithm members (spec 8.2, 8.3; M8b-T8, PD-14) and nothing else: the CPU-side dispatchers (`accelerated()`,
  * `createSimulation()`) test `acc.betweennessCentrality !== undefined` and route to the CPU when the member is
  * absent (spec 2.4 row "method missing"), so a method the GPU does not implement must not exist here -- never a

package/src/index.ts

@@ -50,7 +50,8 @@ export { createAccelerator } from "./accelerator.js";
 export { createForceAtlas2 } from "./layouts/forceatlas2.js";
 export { seedPositions } from "./layouts/seed.js";
 
-// ==================== types: the accelerator surface and the CPU-package mirrors (spec 9.2, 9.3; D27)
+// ==================== types: the accelerator surface, layout's re-exported declarations (spec 9.3; W1b) and the
+// @graphty/algorithms mirrors (spec 9.2; D27, until M8a)
 export type {
     AcceleratorOptions,
     AlgorithmAccelerator,

package/src/layouts/seed.ts

@@ -2,7 +2,9 @@
  * The CPU port's random number generator, bit for bit, and the NaN-row seeding both paths share (spec 7.2 "Initial
  * positions", 9.3 seedPositions, 7.14 `pos`, 7.19 topology change): a seed gives the same start on the CPU and the
  * GPU because both write the same f32 values in index order. The package carries its own copy of the LCG for its
- * whole life (D27: it cannot import @graphty/layout); W1 cross-tests it against the real RandomNumberGenerator.
+ * whole life (D27: it cannot import @graphty/layout at runtime). The CANONICAL copy is
+ * layout/src/simulation/seed.ts; this one is cross-tested against it, bit for bit, by
+ * test/layouts/seed-cross.test.ts (W1b, Task M5b-T3).
  */
 
 import type { F32, GraphSnapshot } from "@graphty/graph-format";

package/src/types/accelerator.ts

@@ -1,11 +1,13 @@
 /**
- * The structural mirrors of @graphty/layout's LayoutSimulation / LayoutAccelerator (spec 9.3) and of
- * the @graphty/algorithms AlgorithmAccelerator (spec 9.2), plus the package's own accelerator surface (spec 3.3).
- * Until W1 these ARE the mirrors (D27): from W1 the mirrors become `import type` of the real packages and
- * test/types/conformance.test-d.ts asserts mutual assignability. Types only.
+ * The layout half of spec 9.3 and the @graphty/algorithms AlgorithmAccelerator mirror (spec 9.2), plus the
+ * package's own accelerator surface (spec 3.3). D27's two halves are now on different footings: at W1b the LAYOUT
+ * mirrors became `import type` of the real `@graphty/layout` interfaces, re-exported here so this package's public
+ * surface is unchanged; the ALGORITHMS mirrors stay structural until A2/M8a gives them something real to point at.
+ * test/types/conformance.test-d.ts is the cross-compile that holds the layout half honest. Types only.
  */
 
-import type { F32, F64, GraphSnapshot, NodeMask, NumericVector, U32 } from "@graphty/graph-format";
+import type { F32, F64, GraphSnapshot, NumericVector, U32 } from "@graphty/graph-format";
+import type { LayoutAccelerator, LayoutSimulation } from "@graphty/layout";
 
 import type { GpuContext } from "../context.js";
 import type {
@@ -20,33 +22,13 @@ import type {
     PageRankOptions,
 } from "./algorithms.js";
 import type { ForceAtlas2Stats, GpuLayoutSimulation, GpuLayoutTuning } from "./layout.js";
-import type { ForceAtlas2Options, FruchtermanReingoldOptions, SpringElectricalOptions } from "./options.js";
+import type { ForceAtlas2Options } from "./options.js";
 
-// ---- mirrors of @graphty/layout (spec 9.3)
+// ---- the real @graphty/layout interfaces (spec 9.3, D27): imported at W1b, re-exported so the package's public
+// surface is unchanged and src/types/layout.ts keeps resolving them from here. `export type`, never a bare
+// `export { ... }`: isolatedModules makes the bare form TS1205.
 
-/** Design 14.3 LayoutSimulation, verbatim. */
-export interface LayoutSimulation {
-    load(snapshot: GraphSnapshot, positions: F32): void;
-    step(iterations?: number): void | Promise<void>;
-    readonly settled: boolean;
-    setFixed(mask: NodeMask): void;
-    setPosition(index: number, x: number, y: number, z: number): void;
-    dispose(): void;
-}
-
-/**
- * Spec 9.3 LayoutAccelerator, verbatim.
- * Exported: published mirror (spec 3.3, D27); re-exported from src/index.ts at P3-T3.
- * @public
- */
-export interface LayoutAccelerator {
-    readonly kind: string;
-    forceAtlas2?(options?: ForceAtlas2Options): LayoutSimulation;
-    fruchtermanReingold?(options?: FruchtermanReingoldOptions): LayoutSimulation;
-    springElectrical?(options?: SpringElectricalOptions): LayoutSimulation;
-    release?(s: GraphSnapshot): void;
-    dispose?(): void;
-}
+export type { LayoutAccelerator, LayoutSimulation };
 
 // ---- mirrors of @graphty/algorithms (spec 9.2); the option types named there do not exist before A2, so they are
 // mirrored as empty-extensible records

package/src/types/algorithms.ts

@@ -1,8 +1,9 @@
 /**
  * The result and option records of the P7 algorithms (spec 3.3 lines 815-828, 9.7). The `Gpu*Result` shapes are the
  * design's verbatim; the option records are this package's own, spelled MEMBER FOR MEMBER as the CPU seam spells
- * them so one object literal satisfies both sides (the same D27 mirror rule src/types/options.ts follows for the
- * layout options). Types only: this file imports nothing at runtime.
+ * them so one object literal satisfies both sides (the D27 mirror rule src/types/options.ts followed for the
+ * layout options until W1b, when those became `import type` re-exports of `@graphty/layout`'s declarations).
+ * Types only: this file imports nothing at runtime.
  *
  * The CPU counterparts, when phase M8a lands them (plan 2026-09-19-webgpu-m8a-algorithms-seam, Task M8a-T8):
  * `PageRankOptions` here is `IndexedPageRankOptions` there (`{ dampingFactor?, maxIterations?, tolerance?,

package/src/types/layout.ts

@@ -1,6 +1,6 @@
 /**
  * The layout-facing public types (spec 3.3, 7.19): the stats records, the GPU simulation interface that extends the
- * design-14.3 LayoutSimulation mirror, the run options and the GPU-only tuning knobs. Types only.
+ * real `@graphty/layout` LayoutSimulation (design 14.3), the run options and the GPU-only tuning knobs. Types only.
  */
 
 import type { F32, GraphSnapshot, NodeMask } from "@graphty/graph-format";
@@ -50,7 +50,7 @@ export interface RunOptions {
     readonly signal?: AbortSignal | undefined;
 }
 
-/** Spec 3.3 GpuLayoutSimulation, verbatim (LayoutSimulation is the design-14.3 mirror of accelerator.ts). */
+/** Spec 3.3 GpuLayoutSimulation, verbatim (LayoutSimulation is `@graphty/layout`'s, via accelerator.ts). */
 export interface GpuLayoutSimulation<Options, Stats extends LayoutStatsBase> extends LayoutSimulation {
     load(snapshot: GraphSnapshot, positions: F32): void;
     /**

package/src/types/options.ts

@@ -1,60 +1,29 @@
 /**
- * The option records of the layouts (spec 9.3, 7.14): structural mirrors of @graphty/layout's option types (D27),
- * copied field for field so a `ForceAtlas2Options` object the element parses is accepted here without a cast. Types
- * only: this file imports nothing at runtime.
+ * The option records of the layouts (spec 9.3, 7.14). The five layout-owned records come from `@graphty/layout` by
+ * `import type` and are re-exported here, so a `ForceAtlas2Options` object the element parses is not merely
+ * shaped like the one this package takes -- it IS the same declaration (W1b; the D27 mirrors are gone).
+ * `ResolvedForceAtlas2Options` below is this package's own and stays local. Types only: nothing here is a runtime
+ * import.
  */
 
-import type { F32, NodeId, NodeMask } from "@graphty/graph-format";
+import type { F32, NodeId } from "@graphty/graph-format";
+import type {
+    CommonLayoutOptions,
+    ForceAtlas2Options,
+    FruchtermanReingoldOptions,
+    SimulationOptions,
+    SpringElectricalOptions,
+} from "@graphty/layout";
 
-/** Design 14.3 CommonLayoutOptions, mirrored verbatim. */
-export interface CommonLayoutOptions {
-    readonly dim?: 2 | 3 | undefined;
-    readonly scale?: number | undefined;
-    readonly center?: ArrayLike<number> | undefined;
-    readonly seed?: number | null | undefined;
-}
-
-/** Spec 9.3 SimulationOptions, mirrored verbatim (layout-owned; the CPU simulations ignore maxInFlight). */
-export interface SimulationOptions {
-    readonly settleThreshold?: number | undefined;
-    readonly settleWindow?: number | undefined;
-    readonly iterationsPerStep?: number | undefined;
-    readonly maxInFlight?: number | undefined;
-}
-
-/**
- * Spec 9.3 ForceAtlas2Options, mirrored verbatim (same names and defaults as
- * layout/src/layouts/force-directed/forceatlas2.ts lines 26-42).
- */
-export interface ForceAtlas2Options extends CommonLayoutOptions, SimulationOptions {
-    readonly maxIter?: number | undefined;
-    readonly jitterTolerance?: number | undefined;
-    readonly scalingRatio?: number | undefined;
-    readonly gravity?: number | undefined;
-    readonly strongGravity?: boolean | undefined;
-    readonly distributedAction?: boolean | undefined;
-    readonly linlog?: boolean | undefined;
-    readonly nodeMass?: F32 | string | Readonly<Record<NodeId, number>> | null | undefined;
-    readonly nodeSize?: F32 | string | Readonly<Record<NodeId, number>> | null | undefined;
-    readonly weight?: boolean | string | null | undefined;
-    readonly dissuadeHubs?: boolean | undefined;
-}
-
-/** Spec 9.3 FruchtermanReingoldOptions, mirrored for the LayoutAccelerator mirror's method signature (P5 implements it). */
-export interface FruchtermanReingoldOptions extends CommonLayoutOptions, SimulationOptions {
-    readonly k?: number | null | undefined;
-    readonly iterations?: number | undefined;
-    readonly fixed?: NodeMask | string | null | undefined;
-}
-
-/** Spec 9.3 SpringElectricalOptions, mirrored for the LayoutAccelerator mirror's method signature (P5 implements it). */
-export interface SpringElectricalOptions extends CommonLayoutOptions, SimulationOptions {
-    readonly springLength?: number | undefined;
-    readonly springCoefficient?: number | undefined;
-    readonly gravity?: number | undefined;
-    readonly dragCoefficient?: number | undefined;
-    readonly timeStep?: number | undefined;
-}
+// The five layout-owned option records are @graphty/layout's declarations, re-exported so src/index.ts's barrel
+// and the option type tests keep resolving them from here (W1b, Task M5b-T2).
+export type {
+    CommonLayoutOptions,
+    ForceAtlas2Options,
+    FruchtermanReingoldOptions,
+    SimulationOptions,
+    SpringElectricalOptions,
+};
 
 /**
  * The resolved (defaults applied) ForceAtlas2 option record the simulation keeps; every field present.