@graphrefly/graphrefly 0.21.0 → 0.23.0

package/dist/patterns/reactive-layout/index.d.cts

@@ -1,3 +1,5 @@
-export { B as BlockAdapters, C as CanvasMeasureAdapter, a as CanvasMeasureAdapterOptions, b as CanvasModule, c as CharPosition, d as CliMeasureAdapter, e as CliMeasureAdapterOptions, f as ContentBlock, I as ImageMeasurer, g as ImageSizeAdapter, L as LayoutLine, h as LineBreaksResult, j as MeasuredBlock, M as MeasurementAdapter, N as NodeCanvasMeasureAdapter, P as PositionedBlock, k as PrecomputedAdapter, l as PrecomputedAdapterOptions, m as PreparedSegment, R as ReactiveBlockLayoutBundle, n as ReactiveBlockLayoutOptions, o as ReactiveLayoutBundle, p as ReactiveLayoutOptions, S as SegmentBreakKind, q as SegmentMeasureStats, r as SvgBoundsAdapter, s as SvgMeasurer, t as analyzeAndMeasure, u as computeBlockFlow, v as computeCharPositions, w as computeLineBreaks, x as computeTotalHeight, y as measureBlock, z as measureBlocks, A as reactiveBlockLayout, D as reactiveLayout } from '../../index-VHA43cGP.cjs';
-import '../../meta-BnG7XAaE.cjs';
-import '../../graph-KsTe57nI.cjs';
+export { B as BlockAdapters, C as CanvasMeasureAdapter, a as CanvasMeasureAdapterOptions, b as CanvasModule, c as CharPosition, d as CliMeasureAdapter, e as CliMeasureAdapterOptions, f as ContentBlock, I as ImageMeasurer, g as ImageSizeAdapter, L as LayoutLine, h as LineBreaksResult, j as MeasuredBlock, M as MeasurementAdapter, N as NodeCanvasMeasureAdapter, P as PositionedBlock, k as PrecomputedAdapter, l as PrecomputedAdapterOptions, m as PreparedSegment, R as ReactiveBlockLayoutBundle, n as ReactiveBlockLayoutOptions, o as ReactiveLayoutBundle, p as ReactiveLayoutOptions, S as SegmentBreakKind, q as SegmentMeasureStats, r as SvgBoundsAdapter, s as SvgMeasurer, t as analyzeAndMeasure, u as computeBlockFlow, v as computeCharPositions, w as computeLineBreaks, x as computeTotalHeight, y as measureBlock, z as measureBlocks, A as reactiveBlockLayout, D as reactiveLayout } from '../../index-C59uSJAH.cjs';
+import '../../node-C7PD3sn9.cjs';
+import '../../graph-BtdSRHUc.cjs';
+import '../../meta-B-Lbs4-O.cjs';
+import '../../storage-DIgAr7M_.cjs';

package/dist/patterns/reactive-layout/index.d.ts

@@ -1,3 +1,5 @@
-export { B as BlockAdapters, C as CanvasMeasureAdapter, a as CanvasMeasureAdapterOptions, b as CanvasModule, c as CharPosition, d as CliMeasureAdapter, e as CliMeasureAdapterOptions, f as ContentBlock, I as ImageMeasurer, g as ImageSizeAdapter, L as LayoutLine, h as LineBreaksResult, j as MeasuredBlock, M as MeasurementAdapter, N as NodeCanvasMeasureAdapter, P as PositionedBlock, k as PrecomputedAdapter, l as PrecomputedAdapterOptions, m as PreparedSegment, R as ReactiveBlockLayoutBundle, n as ReactiveBlockLayoutOptions, o as ReactiveLayoutBundle, p as ReactiveLayoutOptions, S as SegmentBreakKind, q as SegmentMeasureStats, r as SvgBoundsAdapter, s as SvgMeasurer, t as analyzeAndMeasure, u as computeBlockFlow, v as computeCharPositions, w as computeLineBreaks, x as computeTotalHeight, y as measureBlock, z as measureBlocks, A as reactiveBlockLayout, D as reactiveLayout } from '../../index-8a605sg9.js';
-import '../../meta-BnG7XAaE.js';
-import '../../graph-mILUUqW8.js';
+export { B as BlockAdapters, C as CanvasMeasureAdapter, a as CanvasMeasureAdapterOptions, b as CanvasModule, c as CharPosition, d as CliMeasureAdapter, e as CliMeasureAdapterOptions, f as ContentBlock, I as ImageMeasurer, g as ImageSizeAdapter, L as LayoutLine, h as LineBreaksResult, j as MeasuredBlock, M as MeasurementAdapter, N as NodeCanvasMeasureAdapter, P as PositionedBlock, k as PrecomputedAdapter, l as PrecomputedAdapterOptions, m as PreparedSegment, R as ReactiveBlockLayoutBundle, n as ReactiveBlockLayoutOptions, o as ReactiveLayoutBundle, p as ReactiveLayoutOptions, S as SegmentBreakKind, q as SegmentMeasureStats, r as SvgBoundsAdapter, s as SvgMeasurer, t as analyzeAndMeasure, u as computeBlockFlow, v as computeCharPositions, w as computeLineBreaks, x as computeTotalHeight, y as measureBlock, z as measureBlocks, A as reactiveBlockLayout, D as reactiveLayout } from '../../index-jEtF4N7L.js';
+import '../../node-C7PD3sn9.js';
+import '../../graph-CEO2FkLY.js';
+import '../../meta-3QjzotRv.js';
+import '../../storage-CHT5WE9m.js';

package/dist/patterns/reactive-layout/index.js

@@ -14,10 +14,13 @@ import {
   measureBlocks,
   reactiveBlockLayout,
   reactiveLayout
-} from "../../chunk-ZTCDY5NQ.js";
-import "../../chunk-2UDLYZHT.js";
-import "../../chunk-7IGHIFTT.js";
-import "../../chunk-4MQ2J6IG.js";
+} from "../../chunk-PX6PDUJ5.js";
+import "../../chunk-32N5A454.js";
+import "../../chunk-CWYPA63G.js";
+import "../../chunk-XRFJJ2IU.js";
+import "../../chunk-HVBX5KIW.js";
+import "../../chunk-7TAQJHQV.js";
+import "../../chunk-NZMBRXQV.js";
 export {
   CanvasMeasureAdapter,
   CliMeasureAdapter,

package/dist/storage-CHT5WE9m.d.ts

@@ -0,0 +1,182 @@
+import { N as Node } from './node-C7PD3sn9.js';
+
+/**
+ * Storage tier primitive — unified persistence surface (roadmap §3.1).
+ *
+ * A {@link StorageTier} is the single abstraction used by:
+ * - {@link Graph.attachStorage} — snapshot cascade with per-tier cadence
+ * - {@link Graph.fromStorage} — hot-boot from the first tier that hits
+ * - {@link cascadingCache} — keyed lookup cache with auto-promotion
+ *
+ * Factory functions cover the common backends: {@link memoryStorage},
+ * {@link dictStorage}, {@link fileStorage}, {@link sqliteStorage} (sync), and
+ * {@link indexedDbStorage} (async). {@link fromIDBRequest} /
+ * {@link fromIDBTransaction} wrap raw IndexedDB primitives as reactive sources
+ * — they belong here as the browser-runtime neighbors of `indexedDbStorage`.
+ */
+
+/**
+ * Single persistence primitive — supports sync and async backends alike via
+ * `void | Promise<void>` returns. `debounceMs` / `compactEvery` / `filter`
+ * are per-tier cadence controls honored by {@link Graph.attachStorage};
+ * {@link cascadingCache} ignores them (it has its own eviction policy).
+ */
+interface StorageTier {
+    /** Read a value. Returns `null` (or resolves to `null`) on miss. */
+    load(key: string): unknown | Promise<unknown>;
+    /** Write a record. Sync tiers return `void`; async tiers return `Promise<void>`. */
+    save(key: string, data: unknown): void | Promise<void>;
+    /** Delete a value. Optional — tiers without `clear` are append/overwrite-only. */
+    clear?(key: string): void | Promise<void>;
+    /**
+     * Debounce saves on this tier (ms). Hot tier: `0` (sync-through).
+     * Warm: `1000`. Cold: `60000`. Each tier holds its own last-save baseline,
+     * so cold flushes aren't penalized by hot flushes.
+     */
+    debounceMs?: number;
+    /**
+     * Every Nth record is a full snapshot; others are diffs against this
+     * tier's own baseline. Default `10`. Set `1` for always-full;
+     * `Number.POSITIVE_INFINITY` is unsafe — WAL replay needs periodic anchors.
+     */
+    compactEvery?: number;
+    /** Pre-save filter — return `false` to skip this record on this tier. */
+    filter?: (key: string, record: unknown) => boolean;
+}
+/** Handle returned by {@link Graph.attachStorage} — dispose to stop observing. */
+interface StorageHandle {
+    dispose(): void;
+}
+/**
+ * In-memory storage tier (process-local; useful for tests and hot tier).
+ *
+ * @returns Sync {@link StorageTier} with JSON-cloned isolation.
+ *
+ * @example
+ * ```ts
+ * import { memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const hot = memoryStorage();
+ * graph.attachStorage([hot]);
+ * ```
+ *
+ * @category extra
+ */
+declare function memoryStorage(): StorageTier;
+/**
+ * Dict-backed storage tier — stores JSON-cloned values under caller keys in
+ * a caller-owned plain object. Useful for embedding in a parent state shape.
+ *
+ * @param storage - Caller-owned object used as the backing store.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { dictStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const state: Record<string, unknown> = {};
+ * graph.attachStorage([dictStorage(state)]);
+ * ```
+ *
+ * @category extra
+ */
+declare function dictStorage(storage: Record<string, unknown>): StorageTier;
+/**
+ * Atomic JSON file storage tier (one file per key in a directory, temp + rename).
+ *
+ * Keys are sanitized to filesystem-safe names (`[^a-zA-Z0-9_-]` → `%<hex>`).
+ * `load` returns `null` for missing files, empty files, or invalid JSON.
+ *
+ * @param dir - Directory where per-key JSON files are written.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { fileStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([memoryStorage(), fileStorage("./checkpoints")]);
+ * ```
+ *
+ * @category extra
+ */
+declare function fileStorage(dir: string): StorageTier;
+/**
+ * SQLite storage tier using Node.js `node:sqlite` ({@link DatabaseSync}).
+ *
+ * Returns a {@link StorageTier} extended with `close()` — the caller owns the
+ * connection and should close it when discarding the tier.
+ *
+ * **Runtime:** Requires Node 22.5+ with `node:sqlite` enabled.
+ *
+ * @param path - SQLite database file path.
+ * @returns Sync {@link StorageTier} with an idempotent `close()` method.
+ *
+ * @example
+ * ```ts
+ * import { sqliteStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const cold = sqliteStorage("./graphs.sqlite");
+ * graph.attachStorage([memoryStorage(), cold]);
+ * // ... later, on shutdown:
+ * cold.close();
+ * ```
+ *
+ * @category extra
+ */
+declare function sqliteStorage(path: string): StorageTier & {
+    close(): void;
+};
+type IndexedDbStorageSpec = {
+    dbName: string;
+    storeName: string;
+    /** Object-store key under which snapshots are written. @default `"graphrefly_checkpoint"`. */
+    key?: string;
+    version?: number;
+};
+/**
+ * Wraps an `IDBRequest` as a one-shot reactive source.
+ *
+ * @param req - Request whose callbacks are converted to protocol messages.
+ * @returns `Node<T>` that emits `DATA` once on success then `COMPLETE`;
+ *   emits `ERROR` on failure.
+ *
+ * @category extra
+ */
+declare function fromIDBRequest<T>(req: IDBRequest<T>): Node<T>;
+/**
+ * Wraps an `IDBTransaction` terminal lifecycle as a one-shot reactive source.
+ *
+ * @param tx - Transaction to observe.
+ * @returns `Node<void>` that emits `DATA` (`undefined`) then `COMPLETE` on
+ *   success; emits `ERROR` on `error`/`abort`.
+ *
+ * @category extra
+ */
+declare function fromIDBTransaction(tx: IDBTransaction): Node<void>;
+/**
+ * IndexedDB-backed async storage tier (browser runtime).
+ *
+ * All three methods return `Promise`s — pairs naturally with a warm/cold
+ * cadence where async writes are debounced per tier via
+ * {@link Graph.attachStorage}. Writes use `readwrite` transactions; reads use
+ * `readonly`. Missing records resolve to `null`.
+ *
+ * @param spec - Database name, store name, optional `key` (default
+ *   `"graphrefly_checkpoint"`) and schema `version` (default `1`).
+ * @returns Async {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { indexedDbStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([
+ *   memoryStorage(),
+ *   indexedDbStorage({ dbName: "myApp", storeName: "checkpoints" }),
+ * ]);
+ * ```
+ *
+ * @category extra
+ */
+declare function indexedDbStorage(spec: IndexedDbStorageSpec): StorageTier;
+
+export { type IndexedDbStorageSpec as I, type StorageHandle as S, type StorageTier as a, fromIDBRequest as b, fromIDBTransaction as c, dictStorage as d, fileStorage as f, indexedDbStorage as i, memoryStorage as m, sqliteStorage as s };

package/dist/storage-DIgAr7M_.d.cts

@@ -0,0 +1,182 @@
+import { N as Node } from './node-C7PD3sn9.cjs';
+
+/**
+ * Storage tier primitive — unified persistence surface (roadmap §3.1).
+ *
+ * A {@link StorageTier} is the single abstraction used by:
+ * - {@link Graph.attachStorage} — snapshot cascade with per-tier cadence
+ * - {@link Graph.fromStorage} — hot-boot from the first tier that hits
+ * - {@link cascadingCache} — keyed lookup cache with auto-promotion
+ *
+ * Factory functions cover the common backends: {@link memoryStorage},
+ * {@link dictStorage}, {@link fileStorage}, {@link sqliteStorage} (sync), and
+ * {@link indexedDbStorage} (async). {@link fromIDBRequest} /
+ * {@link fromIDBTransaction} wrap raw IndexedDB primitives as reactive sources
+ * — they belong here as the browser-runtime neighbors of `indexedDbStorage`.
+ */
+
+/**
+ * Single persistence primitive — supports sync and async backends alike via
+ * `void | Promise<void>` returns. `debounceMs` / `compactEvery` / `filter`
+ * are per-tier cadence controls honored by {@link Graph.attachStorage};
+ * {@link cascadingCache} ignores them (it has its own eviction policy).
+ */
+interface StorageTier {
+    /** Read a value. Returns `null` (or resolves to `null`) on miss. */
+    load(key: string): unknown | Promise<unknown>;
+    /** Write a record. Sync tiers return `void`; async tiers return `Promise<void>`. */
+    save(key: string, data: unknown): void | Promise<void>;
+    /** Delete a value. Optional — tiers without `clear` are append/overwrite-only. */
+    clear?(key: string): void | Promise<void>;
+    /**
+     * Debounce saves on this tier (ms). Hot tier: `0` (sync-through).
+     * Warm: `1000`. Cold: `60000`. Each tier holds its own last-save baseline,
+     * so cold flushes aren't penalized by hot flushes.
+     */
+    debounceMs?: number;
+    /**
+     * Every Nth record is a full snapshot; others are diffs against this
+     * tier's own baseline. Default `10`. Set `1` for always-full;
+     * `Number.POSITIVE_INFINITY` is unsafe — WAL replay needs periodic anchors.
+     */
+    compactEvery?: number;
+    /** Pre-save filter — return `false` to skip this record on this tier. */
+    filter?: (key: string, record: unknown) => boolean;
+}
+/** Handle returned by {@link Graph.attachStorage} — dispose to stop observing. */
+interface StorageHandle {
+    dispose(): void;
+}
+/**
+ * In-memory storage tier (process-local; useful for tests and hot tier).
+ *
+ * @returns Sync {@link StorageTier} with JSON-cloned isolation.
+ *
+ * @example
+ * ```ts
+ * import { memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const hot = memoryStorage();
+ * graph.attachStorage([hot]);
+ * ```
+ *
+ * @category extra
+ */
+declare function memoryStorage(): StorageTier;
+/**
+ * Dict-backed storage tier — stores JSON-cloned values under caller keys in
+ * a caller-owned plain object. Useful for embedding in a parent state shape.
+ *
+ * @param storage - Caller-owned object used as the backing store.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { dictStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const state: Record<string, unknown> = {};
+ * graph.attachStorage([dictStorage(state)]);
+ * ```
+ *
+ * @category extra
+ */
+declare function dictStorage(storage: Record<string, unknown>): StorageTier;
+/**
+ * Atomic JSON file storage tier (one file per key in a directory, temp + rename).
+ *
+ * Keys are sanitized to filesystem-safe names (`[^a-zA-Z0-9_-]` → `%<hex>`).
+ * `load` returns `null` for missing files, empty files, or invalid JSON.
+ *
+ * @param dir - Directory where per-key JSON files are written.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { fileStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([memoryStorage(), fileStorage("./checkpoints")]);
+ * ```
+ *
+ * @category extra
+ */
+declare function fileStorage(dir: string): StorageTier;
+/**
+ * SQLite storage tier using Node.js `node:sqlite` ({@link DatabaseSync}).
+ *
+ * Returns a {@link StorageTier} extended with `close()` — the caller owns the
+ * connection and should close it when discarding the tier.
+ *
+ * **Runtime:** Requires Node 22.5+ with `node:sqlite` enabled.
+ *
+ * @param path - SQLite database file path.
+ * @returns Sync {@link StorageTier} with an idempotent `close()` method.
+ *
+ * @example
+ * ```ts
+ * import { sqliteStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const cold = sqliteStorage("./graphs.sqlite");
+ * graph.attachStorage([memoryStorage(), cold]);
+ * // ... later, on shutdown:
+ * cold.close();
+ * ```
+ *
+ * @category extra
+ */
+declare function sqliteStorage(path: string): StorageTier & {
+    close(): void;
+};
+type IndexedDbStorageSpec = {
+    dbName: string;
+    storeName: string;
+    /** Object-store key under which snapshots are written. @default `"graphrefly_checkpoint"`. */
+    key?: string;
+    version?: number;
+};
+/**
+ * Wraps an `IDBRequest` as a one-shot reactive source.
+ *
+ * @param req - Request whose callbacks are converted to protocol messages.
+ * @returns `Node<T>` that emits `DATA` once on success then `COMPLETE`;
+ *   emits `ERROR` on failure.
+ *
+ * @category extra
+ */
+declare function fromIDBRequest<T>(req: IDBRequest<T>): Node<T>;
+/**
+ * Wraps an `IDBTransaction` terminal lifecycle as a one-shot reactive source.
+ *
+ * @param tx - Transaction to observe.
+ * @returns `Node<void>` that emits `DATA` (`undefined`) then `COMPLETE` on
+ *   success; emits `ERROR` on `error`/`abort`.
+ *
+ * @category extra
+ */
+declare function fromIDBTransaction(tx: IDBTransaction): Node<void>;
+/**
+ * IndexedDB-backed async storage tier (browser runtime).
+ *
+ * All three methods return `Promise`s — pairs naturally with a warm/cold
+ * cadence where async writes are debounced per tier via
+ * {@link Graph.attachStorage}. Writes use `readwrite` transactions; reads use
+ * `readonly`. Missing records resolve to `null`.
+ *
+ * @param spec - Database name, store name, optional `key` (default
+ *   `"graphrefly_checkpoint"`) and schema `version` (default `1`).
+ * @returns Async {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { indexedDbStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([
+ *   memoryStorage(),
+ *   indexedDbStorage({ dbName: "myApp", storeName: "checkpoints" }),
+ * ]);
+ * ```
+ *
+ * @category extra
+ */
+declare function indexedDbStorage(spec: IndexedDbStorageSpec): StorageTier;
+
+export { type IndexedDbStorageSpec as I, type StorageHandle as S, type StorageTier as a, fromIDBRequest as b, fromIDBTransaction as c, dictStorage as d, fileStorage as f, indexedDbStorage as i, memoryStorage as m, sqliteStorage as s };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@graphrefly/graphrefly",
-	"version": "0.21.0",
+	"version": "0.23.0",
 	"packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319",
 	"description": "Reactive harness layer for agent workflows. Describe automations in plain language, trace every decision, enforce policies, persist checkpoints. Zero dependencies.",
 	"repository": {
@@ -257,6 +257,7 @@
 		"@types/node": "^25.5.0",
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
+		"fast-check": "^4.7.0",
 		"jsdom": "^29.0.1",
 		"openai": "^6.34.0",
 		"react": "^19.2.4",