@git-stunts/git-warp 10.1.1 → 10.3.2

package/index.js

@@ -1,5 +1,24 @@
+/* @ts-self-types="./index.d.ts" */
+
 /**
- * @fileoverview Empty Graph - A graph database substrate using Git commits pointing to the empty tree.
+ * @module
+ *
+ * Deterministic WARP graph over Git: graph-native storage, traversal,
+ * and tooling. All graph state lives as Git commits pointing to the
+ * well-known empty tree — invisible to normal Git workflows, but
+ * inheriting content-addressing, cryptographic integrity, and
+ * distributed replication.
+ *
+ * @example
+ * ```ts
+ * import WarpGraph from "@git-stunts/git-warp";
+ *
+ * const graph = await WarpGraph.open({ repo: ".", graphName: "myGraph" });
+ * const patch = await graph.createPatch("writer-1");
+ * patch.addNode("user:alice").setProperty("user:alice", "name", "Alice");
+ * await patch.commit();
+ * const state = await graph.materialize();
+ * ```
  */
 
 import GitGraphAdapter from './src/infrastructure/adapters/GitGraphAdapter.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "10.1.1",
+  "version": "10.3.2",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",
@@ -79,7 +79,12 @@
     "prepare": "patch-package && node scripts/setup-hooks.js",
     "prepack": "npm run lint && npm run test:local",
     "install:git-warp": "bash scripts/install-git-warp.sh",
-    "uninstall:git-warp": "bash scripts/uninstall-git-warp.sh"
+    "uninstall:git-warp": "bash scripts/uninstall-git-warp.sh",
+    "test:node20": "docker compose -f docker-compose.test.yml --profile node20 run --build --rm test-node20",
+    "test:node22": "docker compose -f docker-compose.test.yml --profile node22 run --build --rm test-node22",
+    "test:bun": "docker compose -f docker-compose.test.yml --profile bun run --build --rm test-bun",
+    "test:deno": "docker compose -f docker-compose.test.yml --profile deno run --build --rm test-deno",
+    "test:matrix": "docker compose -f docker-compose.test.yml --profile full up --build --abort-on-container-exit"
   },
   "dependencies": {
     "@git-stunts/alfred": "^0.4.0",

package/src/domain/WarpGraph.js

@@ -178,6 +178,15 @@ export default class WarpGraph {
 
     /** @type {import('./services/TemporalQuery.js').TemporalQuery|null} */
     this._temporalQuery = null;
+
+    /** @type {number|null} */
+    this._seekCeiling = null;
+
+    /** @type {number|null} */
+    this._cachedCeiling = null;
+
+    /** @type {Map<string, string>|null} */
+    this._cachedFrontier = null;
   }
 
   /**
@@ -570,11 +579,16 @@ export default class WarpGraph {
    * When false or omitted (default), returns just the state for backward
    * compatibility with zero receipt overhead.
    *
+   * When a Lamport ceiling is active (via `options.ceiling` or the
+   * instance-level `_seekCeiling`), delegates to a ceiling-aware path
+   * that replays only patches with `lamport <= ceiling`, bypassing
+   * checkpoints, auto-checkpoint, and GC.
+   *
    * Side effects: Updates internal cached state, version vector, last frontier,
    * and patches-since-checkpoint counter. May trigger auto-checkpoint and GC
    * based on configured policies. Notifies subscribers if state changed.
    *
-   * @param {{receipts?: boolean}} [options] - Optional configuration
+   * @param {{receipts?: boolean, ceiling?: number|null}} [options] - Optional configuration
    * @returns {Promise<import('./services/JoinReducer.js').WarpStateV5|{state: import('./services/JoinReducer.js').WarpStateV5, receipts: import('./types/TickReceipt.js').TickReceipt[]}>} The materialized graph state, or { state, receipts } when receipts enabled
    * @throws {Error} If checkpoint loading fails or patch decoding fails
    * @throws {Error} If writer ref access or patch blob reading fails
@@ -583,6 +597,13 @@ export default class WarpGraph {
     const t0 = this._clock.now();
     // ZERO-COST: only resolve receipts flag when options provided
     const collectReceipts = options && options.receipts;
+    // Resolve ceiling: explicit option > instance-level seek ceiling > null (latest)
+    const ceiling = this._resolveCeiling(options);
+
+    // When ceiling is active, delegate to ceiling-aware path (with its own cache)
+    if (ceiling !== null) {
+      return await this._materializeWithCeiling(ceiling, collectReceipts, t0);
+    }
 
     try {
       // Check for checkpoint
@@ -658,6 +679,8 @@ export default class WarpGraph {
       }
 
       await this._setMaterializedState(state);
+      this._cachedCeiling = null;
+      this._cachedFrontier = null;
       this._lastFrontier = await this.getFrontier();
       this._patchesSinceCheckpoint = patchCount;
 
@@ -698,6 +721,124 @@ export default class WarpGraph {
     }
   }
 
+  /**
+   * Resolves the effective ceiling from options and instance state.
+   *
+   * Precedence: explicit `ceiling` in options overrides the instance-level
+   * `_seekCeiling`. Uses the `'ceiling' in options` check, so passing
+   * `{ ceiling: null }` explicitly clears the seek ceiling for that call
+   * (returns `null`), while omitting the key falls through to `_seekCeiling`.
+   *
+   * @param {{ceiling?: number|null}} [options] - Options object; when the
+   *   `ceiling` key is present (even if `null`), its value takes precedence
+   * @returns {number|null} Lamport ceiling to apply, or `null` for latest
+   * @private
+   */
+  _resolveCeiling(options) {
+    if (options && options.ceiling !== undefined) {
+      return options.ceiling;
+    }
+    return this._seekCeiling;
+  }
+
+  /**
+   * Materializes the graph with a Lamport ceiling (time-travel).
+   *
+   * Bypasses checkpoints entirely — replays all patches from all writers,
+   * filtering to only those with `lamport <= ceiling`. Skips auto-checkpoint
+   * and GC since this is an exploratory read.
+   *
+   * Uses a dedicated cache keyed on `ceiling` + frontier snapshot. Cache
+   * is bypassed when the writer frontier has advanced (new writers or
+   * updated tips) or when `collectReceipts` is `true` because the cached
+   * path does not retain receipt data.
+   *
+   * @param {number} ceiling - Maximum Lamport tick to include (patches with
+   *   `lamport <= ceiling` are replayed; `ceiling <= 0` yields empty state)
+   * @param {boolean} collectReceipts - When `true`, return receipts alongside
+   *   state and skip the ceiling cache
+   * @param {number} t0 - Start timestamp for performance logging
+   * @returns {Promise<import('./services/JoinReducer.js').WarpStateV5 |
+   *   {state: import('./services/JoinReducer.js').WarpStateV5,
+   *    receipts: import('./types/TickReceipt.js').TickReceipt[]}>}
+   *   Plain state when `collectReceipts` is falsy; `{ state, receipts }`
+   *   when truthy
+   * @private
+   */
+  async _materializeWithCeiling(ceiling, collectReceipts, t0) {
+    const frontier = await this.getFrontier();
+
+    // Cache hit: same ceiling, clean state, AND frontier unchanged.
+    // Bypass cache when collectReceipts is true — cached path has no receipts.
+    if (
+      this._cachedState && !this._stateDirty &&
+      ceiling === this._cachedCeiling && !collectReceipts &&
+      this._cachedFrontier !== null &&
+      this._cachedFrontier.size === frontier.size &&
+      [...frontier].every(([w, sha]) => this._cachedFrontier.get(w) === sha)
+    ) {
+      return this._cachedState;
+    }
+
+    const writerIds = [...frontier.keys()];
+
+    if (writerIds.length === 0 || ceiling <= 0) {
+      const state = createEmptyStateV5();
+      this._provenanceIndex = new ProvenanceIndex();
+      await this._setMaterializedState(state);
+      this._cachedCeiling = ceiling;
+      this._cachedFrontier = frontier;
+      this._logTiming('materialize', t0, { metrics: '0 patches (ceiling)' });
+      if (collectReceipts) {
+        return { state, receipts: [] };
+      }
+      return state;
+    }
+
+    const allPatches = [];
+    for (const writerId of writerIds) {
+      const writerPatches = await this._loadWriterPatches(writerId);
+      for (const entry of writerPatches) {
+        if (entry.patch.lamport <= ceiling) {
+          allPatches.push(entry);
+        }
+      }
+    }
+
+    let state;
+    let receipts;
+
+    if (allPatches.length === 0) {
+      state = createEmptyStateV5();
+      if (collectReceipts) {
+        receipts = [];
+      }
+    } else if (collectReceipts) {
+      const result = reduceV5(allPatches, undefined, { receipts: true });
+      state = result.state;
+      receipts = result.receipts;
+    } else {
+      state = reduceV5(allPatches);
+    }
+
+    this._provenanceIndex = new ProvenanceIndex();
+    for (const { patch, sha } of allPatches) {
+      this._provenanceIndex.addPatch(sha, patch.reads, patch.writes);
+    }
+
+    await this._setMaterializedState(state);
+    this._cachedCeiling = ceiling;
+    this._cachedFrontier = frontier;
+
+    // Skip auto-checkpoint and GC — this is an exploratory read
+    this._logTiming('materialize', t0, { metrics: `${allPatches.length} patches (ceiling=${ceiling})` });
+
+    if (collectReceipts) {
+      return { state, receipts };
+    }
+    return state;
+  }
+
   /**
    * Joins (merges) another state into the current cached state.
    *
@@ -1010,6 +1151,79 @@ export default class WarpGraph {
     return writerIds.sort();
   }
 
+  /**
+   * Discovers all distinct Lamport ticks across all writers.
+   *
+   * Walks each writer's patch chain from tip to root, reading commit
+   * messages (no CBOR blob deserialization) to extract Lamport timestamps.
+   * Stops when a non-patch commit (e.g. checkpoint) is encountered.
+   * Logs a warning for any non-monotonic lamport sequence within a single
+   * writer's chain.
+   *
+   * @returns {Promise<{
+   *   ticks: number[],
+   *   maxTick: number,
+   *   perWriter: Map<string, {ticks: number[], tipSha: string|null}>
+   * }>} `ticks` is the sorted (ascending) deduplicated union of all
+   *   Lamport values; `maxTick` is the largest value (0 if none);
+   *   `perWriter` maps each writer ID to its ticks in ascending order
+   *   and its current tip SHA (or `null` if the writer ref is missing)
+   * @throws {Error} If reading refs or commit metadata fails
+   */
+  async discoverTicks() {
+    const writerIds = await this.discoverWriters();
+    const globalTickSet = new Set();
+    const perWriter = new Map();
+
+    for (const writerId of writerIds) {
+      const writerRef = buildWriterRef(this._graphName, writerId);
+      const tipSha = await this._persistence.readRef(writerRef);
+      const writerTicks = [];
+      const tickShas = {};
+
+      if (tipSha) {
+        let currentSha = tipSha;
+        let lastLamport = Infinity;
+
+        while (currentSha) {
+          const nodeInfo = await this._persistence.getNodeInfo(currentSha);
+          const kind = detectMessageKind(nodeInfo.message);
+          if (kind !== 'patch') {
+            break;
+          }
+
+          const patchMeta = decodePatchMessage(nodeInfo.message);
+          globalTickSet.add(patchMeta.lamport);
+          writerTicks.push(patchMeta.lamport);
+          tickShas[patchMeta.lamport] = currentSha;
+
+          // Check monotonic invariant (walking newest→oldest, lamport should decrease)
+          if (patchMeta.lamport > lastLamport && this._logger) {
+            this._logger.warn(`[warp] non-monotonic lamport for writer ${writerId}: ${patchMeta.lamport} > ${lastLamport}`);
+          }
+          lastLamport = patchMeta.lamport;
+
+          if (nodeInfo.parents && nodeInfo.parents.length > 0) {
+            currentSha = nodeInfo.parents[0];
+          } else {
+            break;
+          }
+        }
+      }
+
+      perWriter.set(writerId, {
+        ticks: writerTicks.reverse(),
+        tipSha: tipSha || null,
+        tickShas,
+      });
+    }
+
+    const ticks = [...globalTickSet].sort((a, b) => a - b);
+    const maxTick = ticks.length > 0 ? ticks[ticks.length - 1] : 0;
+
+    return { ticks, maxTick, perWriter };
+  }
+
   // ============================================================================
   // Schema Migration Support
   // ============================================================================
@@ -3025,6 +3239,23 @@ export default class WarpGraph {
     return cone;
   }
 
+  /**
+   * Loads a single patch by its SHA.
+   *
+   * @param {string} sha - The patch commit SHA
+   * @returns {Promise<Object>} The decoded patch object
+   * @throws {Error} If the commit is not a patch or loading fails
+   *
+   * @public
+   * @remarks
+   * Thin wrapper around the internal `_loadPatchBySha` helper. Exposed for
+   * CLI/debug tooling (e.g. seek tick receipts) that needs to inspect patch
+   * operations without re-materializing intermediate states.
+   */
+  async loadPatchBySha(sha) {
+    return await this._loadPatchBySha(sha);
+  }
+
   /**
    * Loads a single patch by its SHA.
    *

package/src/domain/entities/GraphNode.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Immutable value object representing a single graph node backed by a
+ * Git commit pointing to the empty tree.
+ *
+ * @module
+ */
+
+/**
+ * Immutable entity representing a graph node.
+ */
+export default class GraphNode {
+  /** Commit SHA */
+  readonly sha: string;
+  /** Author name */
+  readonly author: string | undefined;
+  /** Commit date */
+  readonly date: string | undefined;
+  /** Node message/data */
+  readonly message: string;
+  /** Array of parent SHAs */
+  readonly parents: readonly string[];
+
+  constructor(data: {
+    sha: string;
+    message: string;
+    author?: string;
+    date?: string;
+    parents?: string[];
+  });
+}

package/src/domain/entities/GraphNode.js

@@ -1,3 +1,12 @@
+/* @ts-self-types="./GraphNode.d.ts" */
+
+/**
+ * @module
+ *
+ * Immutable value object representing a single graph node backed by a
+ * Git commit pointing to the empty tree.
+ */
+
 /**
  * Immutable domain entity representing a node in the graph.
  *

package/src/domain/utils/RefLayout.js

@@ -8,6 +8,8 @@
  * - refs/warp/<graph>/writers/<writer_id>
  * - refs/warp/<graph>/checkpoints/head
  * - refs/warp/<graph>/coverage/head
+ * - refs/warp/<graph>/cursor/active
+ * - refs/warp/<graph>/cursor/saved/<name>
  *
  * @module domain/utils/RefLayout
  */
@@ -49,20 +51,22 @@ const PATH_TRAVERSAL_PATTERN = /\.\./;
  * Validates a graph name and throws if invalid.
  *
  * Graph names must not contain:
- * - Path traversal sequences (`../`)
+ * - Path traversal sequences (`..`)
  * - Semicolons (`;`)
  * - Spaces
  * - Null bytes (`\0`)
  * - Empty strings
  *
  * @param {string} name - The graph name to validate
- * @throws {Error} If the graph name is invalid
+ * @throws {Error} If the name is not a string, is empty, or contains
+ *   forbidden characters (`..`, `;`, space, `\0`)
  * @returns {void}
  *
  * @example
- * validateGraphName('events'); // OK
- * validateGraphName('../etc'); // throws
- * validateGraphName('my graph'); // throws
+ * validateGraphName('events');    // OK
+ * validateGraphName('team/proj'); // OK (slashes allowed)
+ * validateGraphName('../etc');    // throws — path traversal
+ * validateGraphName('my graph');  // throws — contains space
  */
 export function validateGraphName(name) {
   if (typeof name !== 'string') {
@@ -94,18 +98,20 @@ export function validateGraphName(name) {
  * Validates a writer ID and throws if invalid.
  *
  * Writer IDs must:
- * - Be ASCII ref-safe: only [A-Za-z0-9._-]
+ * - Be ASCII ref-safe: only `[A-Za-z0-9._-]`
  * - Be 1-64 characters long
  * - Not contain `/`, `..`, whitespace, or NUL
  *
  * @param {string} id - The writer ID to validate
- * @throws {Error} If the writer ID is invalid
+ * @throws {Error} If the ID is not a string, is empty, exceeds 64 characters,
+ *   or contains forbidden characters (`/`, `..`, whitespace, NUL, non-ASCII)
  * @returns {void}
  *
  * @example
- * validateWriterId('node-1'); // OK
- * validateWriterId('a/b'); // throws (contains /)
- * validateWriterId('x'.repeat(65)); // throws (too long)
+ * validateWriterId('node-1');        // OK
+ * validateWriterId('a/b');           // throws — contains forward slash
+ * validateWriterId('x'.repeat(65));  // throws — exceeds max length
+ * validateWriterId('has space');     // throws — contains whitespace
  */
 export function validateWriterId(id) {
   if (typeof id !== 'string') {
@@ -157,7 +163,7 @@ export function validateWriterId(id) {
  *
  * @param {string} graphName - The name of the graph
  * @param {string} writerId - The writer's unique identifier
- * @returns {string} The full ref path
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/writers/<writerId>`
  * @throws {Error} If graphName or writerId is invalid
  *
  * @example
@@ -174,7 +180,7 @@ export function buildWriterRef(graphName, writerId) {
  * Builds the checkpoint head ref path for the given graph.
  *
  * @param {string} graphName - The name of the graph
- * @returns {string} The full ref path
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/checkpoints/head`
  * @throws {Error} If graphName is invalid
  *
  * @example
@@ -190,7 +196,7 @@ export function buildCheckpointRef(graphName) {
  * Builds the coverage head ref path for the given graph.
  *
  * @param {string} graphName - The name of the graph
- * @returns {string} The full ref path
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/coverage/head`
  * @throws {Error} If graphName is invalid
  *
  * @example
@@ -204,10 +210,12 @@ export function buildCoverageRef(graphName) {
 
 /**
  * Builds the writers prefix path for the given graph.
- * Useful for listing all writer refs under a graph.
+ * Useful for listing all writer refs under a graph
+ * (e.g. via `git for-each-ref`).
  *
  * @param {string} graphName - The name of the graph
- * @returns {string} The writers prefix path
+ * @returns {string} The writers prefix path (with trailing slash),
+ *   e.g. `refs/warp/<graphName>/writers/`
  * @throws {Error} If graphName is invalid
  *
  * @example
@@ -219,6 +227,70 @@ export function buildWritersPrefix(graphName) {
   return `${REF_PREFIX}/${graphName}/writers/`;
 }
 
+/**
+ * Builds the active cursor ref path for the given graph.
+ *
+ * The active cursor is a single ref that stores the current time-travel
+ * position used by `git warp seek`. It points to a commit SHA representing
+ * the materialization frontier the user has seeked to.
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/cursor/active`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildCursorActiveRef('events');
+ * // => 'refs/warp/events/cursor/active'
+ */
+export function buildCursorActiveRef(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/cursor/active`;
+}
+
+/**
+ * Builds a saved (named) cursor ref path for the given graph and cursor name.
+ *
+ * Saved cursors are bookmarks created by `git warp seek --save <name>`.
+ * Each saved cursor persists a time-travel position that can be restored
+ * later without re-seeking.
+ *
+ * The cursor name is validated with the same rules as a writer ID
+ * (ASCII ref-safe: `[A-Za-z0-9._-]`, 1-64 characters).
+ *
+ * @param {string} graphName - The name of the graph
+ * @param {string} name - The cursor bookmark name (validated like a writer ID)
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/cursor/saved/<name>`
+ * @throws {Error} If graphName or name is invalid
+ *
+ * @example
+ * buildCursorSavedRef('events', 'before-tui');
+ * // => 'refs/warp/events/cursor/saved/before-tui'
+ */
+export function buildCursorSavedRef(graphName, name) {
+  validateGraphName(graphName);
+  validateWriterId(name);
+  return `${REF_PREFIX}/${graphName}/cursor/saved/${name}`;
+}
+
+/**
+ * Builds the saved cursor prefix path for the given graph.
+ * Useful for listing all saved cursor bookmarks under a graph
+ * (e.g. via `git for-each-ref`).
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The saved cursor prefix path (with trailing slash),
+ *   e.g. `refs/warp/<graphName>/cursor/saved/`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildCursorSavedPrefix('events');
+ * // => 'refs/warp/events/cursor/saved/'
+ */
+export function buildCursorSavedPrefix(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/cursor/saved/`;
+}
+
 // -----------------------------------------------------------------------------
 // Parsers
 // -----------------------------------------------------------------------------

package/src/domain/utils/parseCursorBlob.js

@@ -0,0 +1,51 @@
+/**
+ * Utilities for parsing seek-cursor blobs stored as Git refs.
+ *
+ * @module parseCursorBlob
+ */
+
+/**
+ * Parses and validates a cursor blob (Buffer) into a cursor object.
+ *
+ * The blob must contain UTF-8-encoded JSON representing a plain object with at
+ * minimum a finite numeric `tick` field.  Any additional fields (e.g. `mode`,
+ * `name`) are preserved in the returned object.
+ *
+ * @param {Buffer} buf - Raw blob contents (UTF-8 encoded JSON)
+ * @param {string} label - Human-readable label used in error messages
+ *   (e.g. `"active cursor"`, `"saved cursor 'foo'"`)
+ * @returns {{ tick: number, mode?: string, [key: string]: unknown }}
+ *   The validated cursor object.  `tick` is guaranteed to be a finite number.
+ * @throws {Error} If `buf` is not valid JSON
+ * @throws {Error} If the parsed value is not a plain JSON object (e.g. array,
+ *   null, or primitive)
+ * @throws {Error} If the `tick` field is missing, non-numeric, NaN, or
+ *   Infinity
+ *
+ * @example
+ * const buf = Buffer.from('{"tick":5,"mode":"lamport"}', 'utf8');
+ * const cursor = parseCursorBlob(buf, 'active cursor');
+ * // => { tick: 5, mode: 'lamport' }
+ *
+ * @example
+ * // Throws: "Corrupted active cursor: blob is not valid JSON"
+ * parseCursorBlob(Buffer.from('not json', 'utf8'), 'active cursor');
+ */
+export function parseCursorBlob(buf, label) {
+  let obj;
+  try {
+    obj = JSON.parse(new TextDecoder().decode(buf));
+  } catch {
+    throw new Error(`Corrupted ${label}: blob is not valid JSON`);
+  }
+
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error(`Corrupted ${label}: expected a JSON object`);
+  }
+
+  if (typeof obj.tick !== 'number' || !Number.isFinite(obj.tick)) {
+    throw new Error(`Corrupted ${label}: missing or invalid numeric tick`);
+  }
+
+  return obj;
+}

package/src/visualization/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Visualization module for rendering WARP graph data as ASCII tables,
+ * SVG diagrams, and interactive browser views.
+ *
+ * @module
+ */
+
+// ASCII renderers
+export declare const colors: Record<string, (s: string) => string>;
+export declare const colorsDefault: Record<string, (s: string) => string>;
+export declare function createBox(content: string, options?: Record<string, unknown>): string;
+export declare function createTable(rows: unknown[], options?: Record<string, unknown>): string;
+export declare function progressBar(current: number, total: number, options?: Record<string, unknown>): string;
+export declare function renderInfoView(data: Record<string, unknown>): string;
+export declare function renderCheckView(data: Record<string, unknown>): string;
+export declare function renderMaterializeView(data: Record<string, unknown>): string;
+export declare function renderHistoryView(data: Record<string, unknown>): string;
+export declare function summarizeOps(ops: unknown[]): string;
+export declare function renderPathView(data: Record<string, unknown>): string;
+export declare function renderGraphView(data: Record<string, unknown>): string;
+
+// SVG renderer
+export declare function renderSvg(positionedGraph: Record<string, unknown>, options?: Record<string, unknown>): string;
+
+// Layout engine
+export declare function layoutGraph(graphData: { nodes: unknown[]; edges: unknown[] }, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function queryResultToGraphData(result: Record<string, unknown>): { nodes: unknown[]; edges: unknown[] };
+export declare function pathResultToGraphData(result: Record<string, unknown>): { nodes: unknown[]; edges: unknown[] };
+export declare function rawGraphToGraphData(result: Record<string, unknown>): { nodes: unknown[]; edges: unknown[] };
+export declare function toElkGraph(graphData: { nodes: unknown[]; edges: unknown[] }, options?: Record<string, unknown>): Record<string, unknown>;
+export declare function getDefaultLayoutOptions(): Record<string, string>;
+export declare function runLayout(elkGraph: Record<string, unknown>): Promise<Record<string, unknown>>;
+
+// Utils
+export declare function truncate(str: string, maxWidth: number): string;
+export declare function timeAgo(dateStr: string): string;
+export declare function formatDuration(ms: number): string;
+export declare function padRight(str: string, width: number): string;
+export declare function padLeft(str: string, width: number): string;
+export declare function center(str: string, width: number): string;
+export declare function stripAnsi(str: string): string;

package/src/visualization/index.js

@@ -1,5 +1,11 @@
+/* @ts-self-types="./index.d.ts" */
+
 /**
- * Visualization module - main exports
+ * @module
+ *
+ * Visualization module for rendering WARP graph data as ASCII tables,
+ * SVG diagrams, and interactive browser views. Includes ELK-based
+ * graph layout, ANSI formatting utilities, and CLI renderers.
  */
 
 // ASCII renderers