@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/base/render/index.d.ts

@@ -0,0 +1,227 @@
+import { GraphDescribeOutput } from '@graphrefly/pure-ts/graph';
+import { c as LayoutFrame } from '../../layout-types-B5aiHYgk.js';
+
+/**
+ * Internal helpers shared across renderers in `extra/render/`.
+ *
+ * These are pure functions over `GraphDescribeOutput` — no Graph instance
+ * dependency. Extracted from `src/graph/graph.ts` (the consolidated
+ * ex-dumpGraph / ex-graphSpecToMermaid / ex-graphSpecToD2 renderers) per
+ * Tier 2.1 A2.
+ */
+
+/** Direction options for diagram exports. */
+type DiagramDirection = "TD" | "LR" | "BT" | "RL";
+
+/**
+ * Sugiyama-style layered DAG layout on an integer grid.
+ *
+ * Pipeline:
+ *   1. Longest-path layer assignment (sources at layer 0).
+ *   2. Virtual-node splitting — every edge spanning more than one layer
+ *      becomes a chain of synthetic nodes on intermediate layers. Downstream
+ *      passes treat real and virtual nodes identically; crossing
+ *      minimization therefore works on wide + deep DAGs, not only
+ *      adjacent-layer cases.
+ *   3. Crossing minimization — barycenter heuristic with alternating up /
+ *      down sweeps plus an adjacent-transposition polish pass.
+ *   4. Coordinate assignment — greedy median-aligned packing with collision
+ *      resolution. Straightens vertical runs of virtual nodes so long edges
+ *      become straight lines where topology allows.
+ *   5. Orthogonal edge routing — per-gutter x-track assignment; horizontal
+ *      segments sit at endpoint centerlines, vertical segments pack into the
+ *      gutter column range without overlap. Remaining crossings are
+ *      topologically unavoidable and will render as `┼` at draw time.
+ *
+ * Output coordinates are cell-grid integers (LR direction). TD rendering
+ * swaps axes at draw time — the layout is direction-agnostic by
+ * construction.
+ *
+ * Used only by [graph-spec-to-ascii.ts](./graph-spec-to-ascii.ts); not part of the public
+ * `extra/render/index.ts` surface (underscore-prefixed).
+ */
+type LayoutDirection = "LR" | "TD";
+
+/**
+ * `graphSpecToAscii(g, opts?)` — stdout-native DAG flowchart renderer for a
+ * {@link GraphDescribeOutput}.
+ *
+ * Zero external dependencies, graph-size independent via proper Sugiyama
+ * (layer assignment → virtual-node splitting → barycenter crossing
+ * minimization → median-aligned coordinate assignment → per-gutter
+ * track-assigned orthogonal routing). See
+ * [_layout-sugiyama.ts](./_layout-sugiyama.ts) for the layout pipeline and
+ * [_ascii-grid.ts](./_ascii-grid.ts) for the character blitter.
+ *
+ * Pure function over the describe snapshot; no Graph instance dependency.
+ *
+ * @category extra
+ */
+
+type GraphSpecToAsciiOptions = {
+    /**
+     * ASCII layout direction. ASCII grid semantics are meaningful only for
+     * `"LR"` (default) and `"TD"`.
+     */
+    direction?: LayoutDirection;
+    /** Per-box label cell cap; longer labels are truncated with `…`. Default `24`. */
+    maxLabelWidth?: number;
+    /** Glyph set: `"unicode"` (default, box-drawing) or `"ascii"` (`-|+<>v`). */
+    asciiCharset?: "unicode" | "ascii";
+    /** Optional logger hook; fires with the rendered text before return. */
+    logger?: (text: string) => void;
+};
+declare function graphSpecToAscii(g: GraphDescribeOutput, opts?: GraphSpecToAsciiOptions): string;
+
+/**
+ * `graphSpecToD2(g, opts?)` — render a {@link GraphDescribeOutput} as D2
+ * diagram text.
+ *
+ * Pure function over the describe snapshot; no Graph instance dependency.
+ *
+ * @category extra
+ */
+
+type GraphSpecToD2Options = {
+    /** Diagram direction; default `"LR"`. */
+    direction?: DiagramDirection;
+};
+declare function graphSpecToD2(g: GraphDescribeOutput, opts?: GraphSpecToD2Options): string;
+
+/**
+ * `graphSpecToJson(g, opts?)` — render a {@link GraphDescribeOutput} as
+ * deterministic JSON text with sorted keys.
+ *
+ * Pure function over the describe snapshot; no Graph instance dependency.
+ *
+ * @category extra
+ */
+
+type GraphSpecToJsonOptions = {
+    /** Include the Edges section (default `true`). */
+    includeEdges?: boolean;
+    /** Include the Subgraphs section (default `true`). */
+    includeSubgraphs?: boolean;
+    /** JSON indent (default `2`). */
+    indent?: number;
+    /** Optional logger hook; fires with the rendered text before return. */
+    logger?: (text: string) => void;
+};
+declare function graphSpecToJson(g: GraphDescribeOutput, opts?: GraphSpecToJsonOptions): string;
+
+/**
+ * `graphSpecToMermaid(g, opts?)` — render a {@link GraphDescribeOutput} as
+ * Mermaid flowchart text.
+ *
+ * Pure function over the describe snapshot; no Graph instance dependency.
+ * Compose with `derived` for live formatted output:
+ *
+ * ```ts
+ * import { graphSpecToMermaid } from "@graphrefly/graphrefly/extra/render";
+ * import { derived } from "@graphrefly/graphrefly";
+ *
+ * const live = derived(
+ *   [graph.describe({ reactive: true }).node],
+ *   ([g]) => graphSpecToMermaid(g),
+ * );
+ * ```
+ *
+ * @category extra
+ */
+
+type GraphSpecToMermaidOptions = {
+    /** Diagram direction; default `"LR"`. */
+    direction?: DiagramDirection;
+};
+declare function graphSpecToMermaid(g: GraphDescribeOutput, opts?: GraphSpecToMermaidOptions): string;
+
+/**
+ * `graphSpecToMermaidUrl(g, opts?)` — encode a {@link GraphDescribeOutput}
+ * as a `https://mermaid.live/edit#base64:…` deep link.
+ *
+ * Round-trip with the mermaid.live editor's `/edit#base64:` share format —
+ * payload is `base64url(JSON({code, mermaid: {theme}, ...}))`. No network
+ * calls; the payload is encoded into the URL fragment.
+ *
+ * @category extra
+ */
+
+type MermaidLiveTheme = "default" | "dark" | "forest" | "neutral" | "base";
+type GraphSpecToMermaidUrlOptions = GraphSpecToMermaidOptions & {
+    theme?: MermaidLiveTheme;
+    autoSync?: boolean;
+};
+/**
+ * Encode an arbitrary mermaid source string to a `mermaid.live` deep link.
+ * Exported separately so callers that already rendered mermaid text can
+ * upgrade to a live-editor URL without re-rendering.
+ */
+declare function mermaidLiveUrl(mermaidSrc: string, opts?: {
+    theme?: MermaidLiveTheme;
+    autoSync?: boolean;
+}): string;
+declare function graphSpecToMermaidUrl(g: GraphDescribeOutput, opts?: GraphSpecToMermaidUrlOptions): string;
+
+/**
+ * `graphSpecToPretty(g, opts?)` — render a {@link GraphDescribeOutput} as
+ * human-readable plaintext (Node list with values, plus optional Edges and
+ * Subgraphs sections).
+ *
+ * Pure function over the describe snapshot; no Graph instance dependency.
+ *
+ * @category extra
+ */
+
+type GraphSpecToPrettyOptions = {
+    /** Include the Edges section (default `true`). */
+    includeEdges?: boolean;
+    /** Include the Subgraphs section (default `true`). */
+    includeSubgraphs?: boolean;
+    /** Optional logger hook; fires with the rendered text before return. */
+    logger?: (text: string) => void;
+};
+declare function graphSpecToPretty(g: GraphDescribeOutput, opts?: GraphSpecToPrettyOptions): string;
+
+/**
+ * `layoutFrameToSvg(frame, opts?)` — render a {@link LayoutFrame} as an SVG
+ * markup string.
+ *
+ * Universal-safe — emits a string, not a DOM tree. Browser code embeds via
+ * `el.innerHTML = svg`; Node code writes to a file. Cell-grid coordinates from
+ * the layout are scaled by `cellWidth` / `cellHeight` (default 12 × 18 px,
+ * roughly matching a monospace baseline).
+ *
+ * Each box gets `data-id="<path>"` for change-event highlighting; each edge
+ * gets `data-from="<from>" data-to="<to>"` so renderers can animate flowing
+ * data per `LayoutFrame.changes`.
+ *
+ * @category extra
+ */
+
+interface LayoutFrameToSvgOptions {
+    /** Pixel width of one cell. Default: `12`. */
+    readonly cellWidth?: number;
+    /** Pixel height of one cell. Default: `18`. */
+    readonly cellHeight?: number;
+    /** Outer margin in pixels. Default: `16`. */
+    readonly padding?: number;
+    /** Box stroke color. Default: `"#444"`. */
+    readonly boxStroke?: string;
+    /** Box fill color. Default: `"#fff"`. */
+    readonly boxFill?: string;
+    /** Edge stroke color. Default: `"#888"`. */
+    readonly edgeStroke?: string;
+    /** Box label text color. Default: `"#111"`. */
+    readonly textColor?: string;
+    /** Font family. Default: `"ui-monospace, monospace"`. */
+    readonly fontFamily?: string;
+    /** Font size in pixels. Default: `12`. */
+    readonly fontSize?: number;
+}
+/**
+ * Render a {@link LayoutFrame} to SVG markup. Pure function — call from
+ * `derived` to drive a live `<svg>` element from a `topologyView` output.
+ */
+declare function layoutFrameToSvg(frame: LayoutFrame, opts?: LayoutFrameToSvgOptions): string;
+
+export { type DiagramDirection, type GraphSpecToAsciiOptions, type GraphSpecToD2Options, type GraphSpecToJsonOptions, type GraphSpecToMermaidOptions, type GraphSpecToMermaidUrlOptions, type GraphSpecToPrettyOptions, type LayoutDirection, type LayoutFrameToSvgOptions, type MermaidLiveTheme, graphSpecToAscii, graphSpecToD2, graphSpecToJson, graphSpecToMermaid, graphSpecToMermaidUrl, graphSpecToPretty, layoutFrameToSvg, mermaidLiveUrl };

package/dist/base/render/index.js

@@ -0,0 +1,24 @@
+import {
+  graphSpecToAscii,
+  graphSpecToD2,
+  graphSpecToJson,
+  graphSpecToMermaid,
+  graphSpecToMermaidUrl,
+  graphSpecToPretty,
+  layoutFrameToSvg,
+  mermaidLiveUrl
+} from "../../chunk-PKGQG5QQ.js";
+import "../../chunk-36NMM65U.js";
+import "../../chunk-DMSNO6ZB.js";
+import "../../chunk-AZDQPQ3V.js";
+export {
+  graphSpecToAscii,
+  graphSpecToD2,
+  graphSpecToJson,
+  graphSpecToMermaid,
+  graphSpecToMermaidUrl,
+  graphSpecToPretty,
+  layoutFrameToSvg,
+  mermaidLiveUrl
+};
+//# sourceMappingURL=index.js.map

package/dist/base/render/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/base/sources/browser/index.cjs

@@ -0,0 +1,172 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/base/sources/browser/index.ts
+var browser_exports = {};
+__export(browser_exports, {
+  fromEvent: () => fromEvent,
+  fromIDBRequest: () => fromIDBRequest,
+  fromIDBTransaction: () => fromIDBTransaction,
+  fromRaf: () => fromRaf
+});
+module.exports = __toCommonJS(browser_exports);
+
+// src/base/sources/event/dom.ts
+var import_core = require("@graphrefly/pure-ts/core");
+function sourceOpts(opts) {
+  return { describeKind: "producer", ...opts };
+}
+function fromRaf(opts) {
+  const { signal, ...rest } = opts ?? {};
+  return (0, import_core.node)((_data, a) => {
+    let done = false;
+    let rafId;
+    let fallbackTimer;
+    let abortListenerAdded = false;
+    let visibilityListenerAdded = false;
+    const raf = typeof requestAnimationFrame === "function" ? requestAnimationFrame : void 0;
+    const caf = typeof cancelAnimationFrame === "function" ? cancelAnimationFrame : void 0;
+    const doc = typeof document !== "undefined" ? document : void 0;
+    const clearPending = () => {
+      if (rafId !== void 0 && caf) caf(rafId);
+      if (fallbackTimer !== void 0) clearTimeout(fallbackTimer);
+      rafId = void 0;
+      fallbackTimer = void 0;
+    };
+    const cleanup = () => {
+      done = true;
+      clearPending();
+      if (abortListenerAdded) {
+        signal?.removeEventListener("abort", onAbort);
+        abortListenerAdded = false;
+      }
+      if (visibilityListenerAdded && doc) {
+        doc.removeEventListener("visibilitychange", onVisibilityChange);
+        visibilityListenerAdded = false;
+      }
+    };
+    const onAbort = () => {
+      if (done) return;
+      cleanup();
+      a.down([[import_core.ERROR, signal.reason]]);
+    };
+    const tick = (now) => {
+      if (done) return;
+      a.emit(now);
+      scheduleNext();
+    };
+    const scheduleNext = () => {
+      if (done) return;
+      if (raf && (!doc || doc.visibilityState !== "hidden")) {
+        rafId = raf(tick);
+      } else {
+        fallbackTimer = setTimeout(() => tick(performance.now()), 16);
+      }
+    };
+    const onVisibilityChange = () => {
+      if (done) return;
+      clearPending();
+      scheduleNext();
+    };
+    if (signal?.aborted) {
+      onAbort();
+      return cleanup;
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+    abortListenerAdded = signal !== void 0;
+    if (doc && raf) {
+      doc.addEventListener("visibilitychange", onVisibilityChange);
+      visibilityListenerAdded = true;
+    }
+    scheduleNext();
+    return cleanup;
+  }, sourceOpts(rest));
+}
+function fromEvent(target, type, opts) {
+  const { capture, passive, once, ...rest } = opts ?? {};
+  return (0, import_core.node)((_data, a) => {
+    const handler = (e) => {
+      a.emit(e);
+    };
+    const options = { capture, passive, once };
+    target.addEventListener(type, handler, options);
+    return () => target.removeEventListener(type, handler, options);
+  }, sourceOpts(rest));
+}
+
+// src/base/sources/browser/idb.ts
+var import_core2 = require("@graphrefly/pure-ts/core");
+function fromIDBRequest(req) {
+  return (0, import_core2.node)((_data, a) => {
+    let done = false;
+    const clear = () => {
+      req.onsuccess = null;
+      req.onerror = null;
+    };
+    req.onsuccess = () => {
+      if (done) return;
+      done = true;
+      clear();
+      a.down([[import_core2.DATA, req.result], [import_core2.COMPLETE]]);
+    };
+    req.onerror = () => {
+      if (done) return;
+      done = true;
+      clear();
+      a.down([[import_core2.ERROR, req.error ?? new Error("IndexedDB request failed")]]);
+    };
+    return () => {
+      done = true;
+      clear();
+    };
+  });
+}
+function fromIDBTransaction(tx) {
+  return (0, import_core2.node)((_data, a) => {
+    let done = false;
+    const clear = () => {
+      tx.oncomplete = null;
+      tx.onerror = null;
+      tx.onabort = null;
+    };
+    tx.oncomplete = () => {
+      if (done) return;
+      done = true;
+      clear();
+      a.down([[import_core2.DATA, void 0], [import_core2.COMPLETE]]);
+    };
+    tx.onerror = () => {
+      if (done) return;
+      done = true;
+      clear();
+      a.down([[import_core2.ERROR, tx.error ?? new Error("IndexedDB transaction failed")]]);
+    };
+    tx.onabort = () => {
+      if (done) return;
+      done = true;
+      clear();
+      a.down([[import_core2.ERROR, tx.error ?? new Error("IndexedDB transaction aborted")]]);
+    };
+    return () => {
+      done = true;
+      clear();
+    };
+  });
+}
+//# sourceMappingURL=index.cjs.map

package/dist/base/sources/browser/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/base/sources/browser/index.ts","../../../../src/base/sources/event/dom.ts","../../../../src/base/sources/browser/idb.ts"],"sourcesContent":["/**\n * Browser-only sources — IDB (IndexedDB) reactive adapters, DOM events.\n *\n * All entries in this subpath may use DOM globals.\n * Import via @graphrefly/graphrefly/base/sources/browser.\n *\n * @module\n */\n\nexport * from \"../event/dom.js\";\nexport * from \"./idb.js\";\n","/**\n * DOM-based reactive event sources (browser-layer).\n *\n * Moved from extra/sources/event.ts (fromEvent, fromRaf) during cleave A2.\n */\n\nimport { ERROR, type Node, type NodeOptions, node } from \"@graphrefly/pure-ts/core\";\n\ntype ExtraOpts = Omit<NodeOptions, \"describeKind\">;\ntype AsyncSourceOpts = ExtraOpts & { signal?: AbortSignal };\n\nfunction sourceOpts<T = unknown>(opts?: ExtraOpts): NodeOptions<T> {\n\treturn { describeKind: \"producer\", ...opts } as NodeOptions<T>;\n}\n\n/** DOM-style event target (browser or `node:events`). */\nexport type EventTargetLike = {\n\taddEventListener(\n\t\ttype: string,\n\t\tlistener: (ev: unknown) => void,\n\t\toptions?: boolean | { capture?: boolean; passive?: boolean; once?: boolean },\n\t): void;\n\tremoveEventListener(\n\t\ttype: string,\n\t\tlistener: (ev: unknown) => void,\n\t\toptions?: boolean | { capture?: boolean; passive?: boolean; once?: boolean },\n\t): void;\n};\n\nexport function fromRaf(opts?: AsyncSourceOpts): Node<number> {\n\tconst { signal, ...rest } = opts ?? {};\n\treturn node<number>((_data, a) => {\n\t\tlet done = false;\n\t\tlet rafId: number | undefined;\n\t\tlet fallbackTimer: ReturnType<typeof setTimeout> | undefined;\n\t\tlet abortListenerAdded = false;\n\t\tlet visibilityListenerAdded = false;\n\n\t\tconst raf: typeof requestAnimationFrame | undefined =\n\t\t\ttypeof requestAnimationFrame === \"function\" ? requestAnimationFrame : undefined;\n\t\tconst caf: typeof cancelAnimationFrame | undefined =\n\t\t\ttypeof cancelAnimationFrame === \"function\" ? cancelAnimationFrame : undefined;\n\t\tconst doc: Document | undefined = typeof document !== \"undefined\" ? document : undefined;\n\n\t\tconst clearPending = () => {\n\t\t\tif (rafId !== undefined && caf) caf(rafId);\n\t\t\tif (fallbackTimer !== undefined) clearTimeout(fallbackTimer);\n\t\t\trafId = undefined;\n\t\t\tfallbackTimer = undefined;\n\t\t};\n\t\tconst cleanup = () => {\n\t\t\tdone = true;\n\t\t\tclearPending();\n\t\t\tif (abortListenerAdded) {\n\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t\tabortListenerAdded = false;\n\t\t\t}\n\t\t\tif (visibilityListenerAdded && doc) {\n\t\t\t\tdoc.removeEventListener(\"visibilitychange\", onVisibilityChange);\n\t\t\t\tvisibilityListenerAdded = false;\n\t\t\t}\n\t\t};\n\t\tconst onAbort = () => {\n\t\t\tif (done) return;\n\t\t\tcleanup();\n\t\t\ta.down([[ERROR, signal!.reason]]);\n\t\t};\n\t\tconst tick = (now: number) => {\n\t\t\tif (done) return;\n\t\t\ta.emit(now);\n\t\t\tscheduleNext();\n\t\t};\n\t\tconst scheduleNext = () => {\n\t\t\tif (done) return;\n\t\t\t// Prefer rAF for display-synced ticks when the tab is visible; when\n\t\t\t// hidden, rAF is throttled to ~0 by the browser, so fall back to\n\t\t\t// setTimeout so downstream state continues updating.\n\t\t\tif (raf && (!doc || doc.visibilityState !== \"hidden\")) {\n\t\t\t\trafId = raf(tick);\n\t\t\t} else {\n\t\t\t\tfallbackTimer = setTimeout(() => tick(performance.now()), 16);\n\t\t\t}\n\t\t};\n\t\tconst onVisibilityChange = () => {\n\t\t\tif (done) return;\n\t\t\t// Cancel any pending schedule and re-schedule via the path now\n\t\t\t// appropriate for the current visibility state.\n\t\t\tclearPending();\n\t\t\tscheduleNext();\n\t\t};\n\n\t\tif (signal?.aborted) {\n\t\t\tonAbort();\n\t\t\treturn cleanup;\n\t\t}\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\tabortListenerAdded = signal !== undefined;\n\t\tif (doc && raf) {\n\t\t\tdoc.addEventListener(\"visibilitychange\", onVisibilityChange);\n\t\t\tvisibilityListenerAdded = true;\n\t\t}\n\t\tscheduleNext();\n\t\treturn cleanup;\n\t}, sourceOpts(rest));\n}\n\n/**\n * Wraps a DOM-style `addEventListener` target; each event becomes a `DATA` emission.\n *\n * @param target - Object with `addEventListener` / `removeEventListener`.\n * @param type - Event name (e.g. `\"click\"`).\n * @param opts - Producer options plus listener options (`capture`, `passive`, `once`).\n * @returns `Node<T>` — event payloads; teardown removes the listener.\n *\n * @example\n * ```ts\n * import { fromEvent } from \"@graphrefly/graphrefly-ts\";\n *\n * fromEvent(document.body, \"click\");\n * ```\n *\n * @category extra\n */\nexport function fromEvent<T = unknown>(\n\ttarget: EventTargetLike,\n\ttype: string,\n\topts?: ExtraOpts & { capture?: boolean; passive?: boolean; once?: boolean },\n): Node<T> {\n\tconst { capture, passive, once, ...rest } = opts ?? {};\n\treturn node<T>((_data, a) => {\n\t\tconst handler = (e: unknown) => {\n\t\t\ta.emit(e as T);\n\t\t};\n\t\tconst options = { capture, passive, once };\n\t\ttarget.addEventListener(type, handler, options);\n\t\treturn () => target.removeEventListener(type, handler, options);\n\t}, sourceOpts(rest));\n}\n","/**\n * Browser-only IndexedDB reactive sources.\n *\n * `fromIDBRequest` / `fromIDBTransaction` wrap raw IDB primitives as reactive\n * sources. The old `indexedDbStorage` kv adapter has been replaced by\n * `indexedDbKv` in `./storage-tiers-browser.js` (Audit 4, 2026-04-24).\n *\n * Imports require the DOM lib — not safe to pull into Node-only bundles\n * without `lib: [\"dom\"]` in the consumer's tsconfig.\n *\n * @module\n */\n/// <reference lib=\"dom\" />\n\nimport { COMPLETE, DATA, ERROR, type Node, node } from \"@graphrefly/pure-ts/core\";\n\n// IndexedDbStorageSpec is no longer needed here — it's defined in storage-tiers-browser.ts.\n\n/**\n * Wraps an `IDBRequest` as a one-shot reactive source.\n *\n * @param req - Request whose callbacks are converted to protocol messages.\n * @returns `Node<T>` that emits `DATA` once on success then `COMPLETE`;\n *   emits `ERROR` on failure.\n *\n * @category extra\n */\nexport function fromIDBRequest<T>(req: IDBRequest<T>): Node<T> {\n\treturn node<T>((_data, a) => {\n\t\tlet done = false;\n\t\tconst clear = () => {\n\t\t\treq.onsuccess = null;\n\t\t\treq.onerror = null;\n\t\t};\n\t\treq.onsuccess = () => {\n\t\t\tif (done) return;\n\t\t\tdone = true;\n\t\t\tclear();\n\t\t\ta.down([[DATA, req.result], [COMPLETE]]);\n\t\t};\n\t\treq.onerror = () => {\n\t\t\tif (done) return;\n\t\t\tdone = true;\n\t\t\tclear();\n\t\t\ta.down([[ERROR, req.error ?? new Error(\"IndexedDB request failed\")]]);\n\t\t};\n\t\treturn () => {\n\t\t\tdone = true;\n\t\t\tclear();\n\t\t};\n\t});\n}\n\n/**\n * Wraps an `IDBTransaction` terminal lifecycle as a one-shot reactive source.\n *\n * @param tx - Transaction to observe.\n * @returns `Node<void>` that emits `DATA` (`undefined`) then `COMPLETE` on\n *   success; emits `ERROR` on `error`/`abort`.\n *\n * @category extra\n */\nexport function fromIDBTransaction(tx: IDBTransaction): Node<void> {\n\treturn node<void>((_data, a) => {\n\t\tlet done = false;\n\t\tconst clear = () => {\n\t\t\ttx.oncomplete = null;\n\t\t\ttx.onerror = null;\n\t\t\ttx.onabort = null;\n\t\t};\n\t\ttx.oncomplete = () => {\n\t\t\tif (done) return;\n\t\t\tdone = true;\n\t\t\tclear();\n\t\t\ta.down([[DATA, undefined], [COMPLETE]]);\n\t\t};\n\t\ttx.onerror = () => {\n\t\t\tif (done) return;\n\t\t\tdone = true;\n\t\t\tclear();\n\t\t\ta.down([[ERROR, tx.error ?? new Error(\"IndexedDB transaction failed\")]]);\n\t\t};\n\t\ttx.onabort = () => {\n\t\t\tif (done) return;\n\t\t\tdone = true;\n\t\t\tclear();\n\t\t\ta.down([[ERROR, tx.error ?? new Error(\"IndexedDB transaction aborted\")]]);\n\t\t};\n\t\treturn () => {\n\t\t\tdone = true;\n\t\t\tclear();\n\t\t};\n\t});\n}\n\n// The old `indexedDbStorage` kv adapter has been removed.\n// Use `indexedDbKv` from `./storage-tiers-browser.js` instead (Audit 4, 2026-04-24).\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACMA,kBAAyD;AAKzD,SAAS,WAAwB,MAAkC;AAClE,SAAO,EAAE,cAAc,YAAY,GAAG,KAAK;AAC5C;AAgBO,SAAS,QAAQ,MAAsC;AAC7D,QAAM,EAAE,QAAQ,GAAG,KAAK,IAAI,QAAQ,CAAC;AACrC,aAAO,kBAAa,CAAC,OAAO,MAAM;AACjC,QAAI,OAAO;AACX,QAAI;AACJ,QAAI;AACJ,QAAI,qBAAqB;AACzB,QAAI,0BAA0B;AAE9B,UAAM,MACL,OAAO,0BAA0B,aAAa,wBAAwB;AACvE,UAAM,MACL,OAAO,yBAAyB,aAAa,uBAAuB;AACrE,UAAM,MAA4B,OAAO,aAAa,cAAc,WAAW;AAE/E,UAAM,eAAe,MAAM;AAC1B,UAAI,UAAU,UAAa,IAAK,KAAI,KAAK;AACzC,UAAI,kBAAkB,OAAW,cAAa,aAAa;AAC3D,cAAQ;AACR,sBAAgB;AAAA,IACjB;AACA,UAAM,UAAU,MAAM;AACrB,aAAO;AACP,mBAAa;AACb,UAAI,oBAAoB;AACvB,gBAAQ,oBAAoB,SAAS,OAAO;AAC5C,6BAAqB;AAAA,MACtB;AACA,UAAI,2BAA2B,KAAK;AACnC,YAAI,oBAAoB,oBAAoB,kBAAkB;AAC9D,kCAA0B;AAAA,MAC3B;AAAA,IACD;AACA,UAAM,UAAU,MAAM;AACrB,UAAI,KAAM;AACV,cAAQ;AACR,QAAE,KAAK,CAAC,CAAC,mBAAO,OAAQ,MAAM,CAAC,CAAC;AAAA,IACjC;AACA,UAAM,OAAO,CAAC,QAAgB;AAC7B,UAAI,KAAM;AACV,QAAE,KAAK,GAAG;AACV,mBAAa;AAAA,IACd;AACA,UAAM,eAAe,MAAM;AAC1B,UAAI,KAAM;AAIV,UAAI,QAAQ,CAAC,OAAO,IAAI,oBAAoB,WAAW;AACtD,gBAAQ,IAAI,IAAI;AAAA,MACjB,OAAO;AACN,wBAAgB,WAAW,MAAM,KAAK,YAAY,IAAI,CAAC,GAAG,EAAE;AAAA,MAC7D;AAAA,IACD;AACA,UAAM,qBAAqB,MAAM;AAChC,UAAI,KAAM;AAGV,mBAAa;AACb,mBAAa;AAAA,IACd;AAEA,QAAI,QAAQ,SAAS;AACpB,cAAQ;AACR,aAAO;AAAA,IACR;AACA,YAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;AACzD,yBAAqB,WAAW;AAChC,QAAI,OAAO,KAAK;AACf,UAAI,iBAAiB,oBAAoB,kBAAkB;AAC3D,gCAA0B;AAAA,IAC3B;AACA,iBAAa;AACb,WAAO;AAAA,EACR,GAAG,WAAW,IAAI,CAAC;AACpB;AAmBO,SAAS,UACf,QACA,MACA,MACU;AACV,QAAM,EAAE,SAAS,SAAS,MAAM,GAAG,KAAK,IAAI,QAAQ,CAAC;AACrD,aAAO,kBAAQ,CAAC,OAAO,MAAM;AAC5B,UAAM,UAAU,CAAC,MAAe;AAC/B,QAAE,KAAK,CAAM;AAAA,IACd;AACA,UAAM,UAAU,EAAE,SAAS,SAAS,KAAK;AACzC,WAAO,iBAAiB,MAAM,SAAS,OAAO;AAC9C,WAAO,MAAM,OAAO,oBAAoB,MAAM,SAAS,OAAO;AAAA,EAC/D,GAAG,WAAW,IAAI,CAAC;AACpB;;;AC3HA,IAAAA,eAAuD;AAahD,SAAS,eAAkB,KAA6B;AAC9D,aAAO,mBAAQ,CAAC,OAAO,MAAM;AAC5B,QAAI,OAAO;AACX,UAAM,QAAQ,MAAM;AACnB,UAAI,YAAY;AAChB,UAAI,UAAU;AAAA,IACf;AACA,QAAI,YAAY,MAAM;AACrB,UAAI,KAAM;AACV,aAAO;AACP,YAAM;AACN,QAAE,KAAK,CAAC,CAAC,mBAAM,IAAI,MAAM,GAAG,CAAC,qBAAQ,CAAC,CAAC;AAAA,IACxC;AACA,QAAI,UAAU,MAAM;AACnB,UAAI,KAAM;AACV,aAAO;AACP,YAAM;AACN,QAAE,KAAK,CAAC,CAAC,oBAAO,IAAI,SAAS,IAAI,MAAM,0BAA0B,CAAC,CAAC,CAAC;AAAA,IACrE;AACA,WAAO,MAAM;AACZ,aAAO;AACP,YAAM;AAAA,IACP;AAAA,EACD,CAAC;AACF;AAWO,SAAS,mBAAmB,IAAgC;AAClE,aAAO,mBAAW,CAAC,OAAO,MAAM;AAC/B,QAAI,OAAO;AACX,UAAM,QAAQ,MAAM;AACnB,SAAG,aAAa;AAChB,SAAG,UAAU;AACb,SAAG,UAAU;AAAA,IACd;AACA,OAAG,aAAa,MAAM;AACrB,UAAI,KAAM;AACV,aAAO;AACP,YAAM;AACN,QAAE,KAAK,CAAC,CAAC,mBAAM,MAAS,GAAG,CAAC,qBAAQ,CAAC,CAAC;AAAA,IACvC;AACA,OAAG,UAAU,MAAM;AAClB,UAAI,KAAM;AACV,aAAO;AACP,YAAM;AACN,QAAE,KAAK,CAAC,CAAC,oBAAO,GAAG,SAAS,IAAI,MAAM,8BAA8B,CAAC,CAAC,CAAC;AAAA,IACxE;AACA,OAAG,UAAU,MAAM;AAClB,UAAI,KAAM;AACV,aAAO;AACP,YAAM;AACN,QAAE,KAAK,CAAC,CAAC,oBAAO,GAAG,SAAS,IAAI,MAAM,+BAA+B,CAAC,CAAC,CAAC;AAAA,IACzE;AACA,WAAO,MAAM;AACZ,aAAO;AACP,YAAM;AAAA,IACP;AAAA,EACD,CAAC;AACF;","names":["import_core"]}

package/dist/base/sources/browser/index.d.cts

@@ -0,0 +1,84 @@
+import { NodeOptions, Node } from '@graphrefly/pure-ts/core';
+
+/**
+ * DOM-based reactive event sources (browser-layer).
+ *
+ * Moved from extra/sources/event.ts (fromEvent, fromRaf) during cleave A2.
+ */
+
+type ExtraOpts = Omit<NodeOptions, "describeKind">;
+type AsyncSourceOpts = ExtraOpts & {
+    signal?: AbortSignal;
+};
+/** DOM-style event target (browser or `node:events`). */
+type EventTargetLike = {
+    addEventListener(type: string, listener: (ev: unknown) => void, options?: boolean | {
+        capture?: boolean;
+        passive?: boolean;
+        once?: boolean;
+    }): void;
+    removeEventListener(type: string, listener: (ev: unknown) => void, options?: boolean | {
+        capture?: boolean;
+        passive?: boolean;
+        once?: boolean;
+    }): void;
+};
+declare function fromRaf(opts?: AsyncSourceOpts): Node<number>;
+/**
+ * Wraps a DOM-style `addEventListener` target; each event becomes a `DATA` emission.
+ *
+ * @param target - Object with `addEventListener` / `removeEventListener`.
+ * @param type - Event name (e.g. `"click"`).
+ * @param opts - Producer options plus listener options (`capture`, `passive`, `once`).
+ * @returns `Node<T>` — event payloads; teardown removes the listener.
+ *
+ * @example
+ * ```ts
+ * import { fromEvent } from "@graphrefly/graphrefly-ts";
+ *
+ * fromEvent(document.body, "click");
+ * ```
+ *
+ * @category extra
+ */
+declare function fromEvent<T = unknown>(target: EventTargetLike, type: string, opts?: ExtraOpts & {
+    capture?: boolean;
+    passive?: boolean;
+    once?: boolean;
+}): Node<T>;
+
+/**
+ * Browser-only IndexedDB reactive sources.
+ *
+ * `fromIDBRequest` / `fromIDBTransaction` wrap raw IDB primitives as reactive
+ * sources. The old `indexedDbStorage` kv adapter has been replaced by
+ * `indexedDbKv` in `./storage-tiers-browser.js` (Audit 4, 2026-04-24).
+ *
+ * Imports require the DOM lib — not safe to pull into Node-only bundles
+ * without `lib: ["dom"]` in the consumer's tsconfig.
+ *
+ * @module
+ */
+
+/**
+ * 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>;
+
+export { type EventTargetLike, fromEvent, fromIDBRequest, fromIDBTransaction, fromRaf };

package/dist/base/sources/browser/index.d.ts

@@ -0,0 +1,84 @@
+import { NodeOptions, Node } from '@graphrefly/pure-ts/core';
+
+/**
+ * DOM-based reactive event sources (browser-layer).
+ *
+ * Moved from extra/sources/event.ts (fromEvent, fromRaf) during cleave A2.
+ */
+
+type ExtraOpts = Omit<NodeOptions, "describeKind">;
+type AsyncSourceOpts = ExtraOpts & {
+    signal?: AbortSignal;
+};
+/** DOM-style event target (browser or `node:events`). */
+type EventTargetLike = {
+    addEventListener(type: string, listener: (ev: unknown) => void, options?: boolean | {
+        capture?: boolean;
+        passive?: boolean;
+        once?: boolean;
+    }): void;
+    removeEventListener(type: string, listener: (ev: unknown) => void, options?: boolean | {
+        capture?: boolean;
+        passive?: boolean;
+        once?: boolean;
+    }): void;
+};
+declare function fromRaf(opts?: AsyncSourceOpts): Node<number>;
+/**
+ * Wraps a DOM-style `addEventListener` target; each event becomes a `DATA` emission.
+ *
+ * @param target - Object with `addEventListener` / `removeEventListener`.
+ * @param type - Event name (e.g. `"click"`).
+ * @param opts - Producer options plus listener options (`capture`, `passive`, `once`).
+ * @returns `Node<T>` — event payloads; teardown removes the listener.
+ *
+ * @example
+ * ```ts
+ * import { fromEvent } from "@graphrefly/graphrefly-ts";
+ *
+ * fromEvent(document.body, "click");
+ * ```
+ *
+ * @category extra
+ */
+declare function fromEvent<T = unknown>(target: EventTargetLike, type: string, opts?: ExtraOpts & {
+    capture?: boolean;
+    passive?: boolean;
+    once?: boolean;
+}): Node<T>;
+
+/**
+ * Browser-only IndexedDB reactive sources.
+ *
+ * `fromIDBRequest` / `fromIDBTransaction` wrap raw IDB primitives as reactive
+ * sources. The old `indexedDbStorage` kv adapter has been replaced by
+ * `indexedDbKv` in `./storage-tiers-browser.js` (Audit 4, 2026-04-24).
+ *
+ * Imports require the DOM lib — not safe to pull into Node-only bundles
+ * without `lib: ["dom"]` in the consumer's tsconfig.
+ *
+ * @module
+ */
+
+/**
+ * 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>;
+
+export { type EventTargetLike, fromEvent, fromIDBRequest, fromIDBTransaction, fromRaf };