@rindle/devtools 0.1.6

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rindle/devtools",
+  "version": "0.1.6",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rindle-sh/rindle.git",
+    "directory": "packages/devtools"
+  },
+  "type": "module",
+  "description": "Framework-agnostic in-browser devtools core for Rindle: mutation timeline, queries inspector, and delta stream built over the client's existing read-only seams (DEBUG-TOOLS-BROWSER-DESIGN.md). Dev-only; no DOM assumptions.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@rindle/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@rindle/client": "0.1.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc --noEmit && node --conditions=@rindle/source --test test/*.test.ts"
+  }
+}

package/src/ast.ts

@@ -0,0 +1,66 @@
+// Read-only AST helpers for the queries inspector (DEBUG-TOOLS-BROWSER-DESIGN §4.2): the table
+// footprint (for the pending-axis intersection) and a one-line human summary. Pure functions over
+// the `@rindle/client` `Ast` — no engine, no side effects.
+
+import type { Ast, Condition, ValuePosition } from "@rindle/client";
+
+/** Every base table this query can read: the root, each `related` subquery, and any correlated
+ *  subquery in the `where` tree (recursively). Mirrors the optimistic backend's `queryTables`
+ *  derivation (DEBUG-TOOLS-BROWSER-DESIGN §4.2 — a `count(comments)` subquery names `comment`, so a
+ *  comment mutation flips this query's pending axis). */
+export function collectTables(ast: Ast, into: Set<string> = new Set()): Set<string> {
+  into.add(ast.table);
+  for (const r of ast.related ?? []) collectTables(r.subquery, into);
+  if (ast.where) collectTablesFromCondition(ast.where, into);
+  return into;
+}
+
+function collectTablesFromCondition(cond: Condition, into: Set<string>): void {
+  if (cond.type === "and" || cond.type === "or") {
+    for (const c of cond.conditions) collectTablesFromCondition(c, into);
+  } else if (cond.type === "correlatedSubquery") {
+    collectTables(cond.related.subquery, into);
+  }
+}
+
+/** A compact, one-line description of a query AST for the inspector header — best-effort and
+ *  truncation-friendly (the full AST is available for a collapsible pretty-print alongside). */
+export function summarizeAst(ast: Ast): string {
+  const parts: string[] = [ast.alias ? `${ast.table} as ${ast.alias}` : ast.table];
+  if (ast.aggregate) parts.push(ast.aggregate === "count" ? "count(*)" : ast.aggregate);
+  if (ast.select?.length) parts.push(`select(${ast.select.join(", ")})`);
+  if (ast.where) parts.push(`where(${summarizeCondition(ast.where)})`);
+  if (ast.orderBy?.length) parts.push(`order(${ast.orderBy.map(([f, d]) => `${f} ${d}`).join(", ")})`);
+  if (ast.limit !== undefined) parts.push(`limit ${ast.limit}`);
+  if (ast.one) parts.push("one");
+  if (ast.related?.length) {
+    const rels = ast.related.map((r) => {
+      const sub = r.subquery;
+      const tag = sub.aggregate ? `${sub.alias ?? sub.table}(count)` : (sub.alias ?? sub.table);
+      return tag;
+    });
+    parts.push(`{ ${rels.join(", ")} }`);
+  }
+  return parts.join(" ");
+}
+
+function summarizeCondition(cond: Condition): string {
+  switch (cond.type) {
+    case "simple":
+      return `${valueStr(cond.left)} ${cond.op} ${valueStr(cond.right)}`;
+    case "and":
+      return cond.conditions.map(summarizeCondition).join(" AND ");
+    case "or":
+      return `(${cond.conditions.map(summarizeCondition).join(" OR ")})`;
+    case "correlatedSubquery":
+      return `${cond.op} ${cond.related.subquery.table}`;
+  }
+}
+
+function valueStr(v: ValuePosition): string {
+  if (v.type === "column") return v.name;
+  const lit = v.value;
+  if (typeof lit === "string") return JSON.stringify(lit);
+  if (Array.isArray(lit)) return `[${lit.length}]`;
+  return String(lit);
+}

package/src/core.ts

@@ -0,0 +1,388 @@
+// DevtoolsCore — the framework-agnostic engine (DEBUG-TOOLS-BROWSER-DESIGN.md §6.1). It attaches to
+// a running client through the read-only seams (`Store.__attachDevtools` / `__inspect`, and the
+// optimistic backend's `__inspect`), then maintains the §4 read-model: the mutation TIMELINE
+// (reconstructed by diffing successive pending-stack snapshots), the QUERIES inspector, and the
+// DELTA stream (off the raw per-query `ChangeEvent` tap). No DOM, no app-code changes, no hot path.
+
+import { collectTables, summarizeAst } from "./ast.ts";
+import type {
+  ChangeEvent,
+  DeltaEntry,
+  DeltaKind,
+  DevtoolsBackend,
+  DevtoolsCoreOptions,
+  DevtoolsState,
+  DevtoolsStore,
+  DevtoolsTarget,
+  FlatOp,
+  OptimisticInspect,
+  QueryEntry,
+  QueryId,
+  ResultType,
+  TimelineEntry,
+} from "./types.ts";
+
+/** Narrow a candidate backend to the optimistic capability (the `__inspect` probe, §6.2). */
+function asOptimisticBackend(backend: unknown): DevtoolsBackend | undefined {
+  return backend && typeof (backend as DevtoolsBackend).__inspect === "function"
+    ? (backend as DevtoolsBackend)
+    : undefined;
+}
+
+const EMPTY_STATE: DevtoolsState = {
+  timeline: [],
+  queries: [],
+  deltas: [],
+  optimistic: undefined,
+  capabilities: { optimistic: false },
+};
+
+export class DevtoolsCore {
+  private readonly store: DevtoolsStore;
+  private readonly backend?: DevtoolsBackend;
+  private readonly detachStore: () => void;
+
+  private readonly timelineCap: number;
+  private readonly deltaCap: number;
+  private readonly sampleRows: number;
+  private readonly autoFlush: boolean;
+  private readonly now: () => number;
+  private readonly pollHandle?: ReturnType<typeof setInterval>;
+
+  // Timeline state: entries by stable id + an insertion-ordered id list (newest last).
+  private readonly timeline = new Map<string, TimelineEntry>();
+  private readonly order: string[] = [];
+  /** The pending keys seen at the previous recompute — the diff basis for lifecycle transitions. */
+  private prevPendingKeys = new Set<string>();
+
+  // Delta ring.
+  private deltas: DeltaEntry[] = [];
+  private deltaSeq = 0;
+  /** Set by a `batch` delta, consumed by the next recompute: did view churn coincide with a
+   *  confirmation this turn? (the §4.1 snap-back heuristic). */
+  private churnSeen = false;
+
+  private queries: QueryEntry[] = [];
+  private optimistic?: OptimisticInspect;
+
+  private readonly listeners = new Set<() => void>();
+  private dirty = false;
+  private flushScheduled = false;
+  private snapshot: DevtoolsState = EMPTY_STATE;
+  /** Optional deregistration from the global hub (set by {@link attachDevtools}). */
+  onDetach?: () => void;
+
+  constructor(target: DevtoolsTarget, opts: DevtoolsCoreOptions = {}) {
+    this.store = target.store;
+    this.backend = asOptimisticBackend(target.backend);
+    this.timelineCap = opts.timelineCap ?? 200;
+    this.deltaCap = opts.deltaCap ?? 500;
+    this.sampleRows = opts.sampleRows ?? 25;
+    this.autoFlush = opts.autoFlush ?? true;
+    this.now = opts.now ?? (() => Date.now());
+
+    this.detachStore = this.store.__attachDevtools({
+      onDelta: (qid, ev) => this.onDelta(qid, ev),
+      onResultType: (qid, rt) => this.onResultType(qid, rt),
+    });
+
+    const pollMs = opts.pollMs ?? 0;
+    if (pollMs > 0) {
+      this.pollHandle = setInterval(() => this.refresh(), pollMs);
+      // Don't keep a Node process alive on the poll timer (no-op in the browser).
+      (this.pollHandle as { unref?: () => void }).unref?.();
+    }
+
+    // Seed the initial snapshot from whatever the app already holds (e.g. queries mounted before
+    // the pane attached).
+    this.refresh();
+  }
+
+  // --- public surface ----------------------------------------------------------
+
+  /** The current read-model. Reference-stable between updates (rebuilt only on recompute), so it is
+   *  safe to feed a `useSyncExternalStore`-style binding. */
+  getState(): DevtoolsState {
+    return this.snapshot;
+  }
+
+  /** Subscribe to updates; fires immediately with the current state, then after each recompute. */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    listener();
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Force a synchronous recompute (also used by the safety-net poll and by tests). */
+  refresh(): void {
+    this.dirty = true;
+    this.flush();
+  }
+
+  /** Clear the delta stream ring (a panel "clear" affordance). */
+  clearDeltas(): void {
+    this.deltas = [];
+    this.refresh();
+  }
+
+  /** Drop every SETTLED timeline row (confirmed/dropped), keeping live pending ones + the deltas. */
+  clearHistory(): void {
+    for (let i = this.order.length - 1; i >= 0; i--) {
+      const id = this.order[i];
+      const e = this.timeline.get(id);
+      if (e && e.state !== "pending") {
+        this.timeline.delete(id);
+        this.order.splice(i, 1);
+      }
+    }
+    this.refresh();
+  }
+
+  /** Detach from the client: stop the poll, drop the store tap, deregister from the global hub. */
+  detach(): void {
+    if (this.pollHandle) clearInterval(this.pollHandle);
+    this.detachStore();
+    this.onDetach?.();
+    this.listeners.clear();
+  }
+
+  // --- event taps --------------------------------------------------------------
+
+  private onDelta(qid: QueryId, ev: ChangeEvent): void {
+    this.pushDelta(qid, ev);
+    // A `batch` carrying real changes is view churn — the signal the snap-back heuristic keys on.
+    if (ev.type === "batch" && ev.events.length > 0) this.churnSeen = true;
+    this.markDirty();
+  }
+
+  private onResultType(_qid: QueryId, _rt: ResultType): void {
+    this.markDirty();
+  }
+
+  private markDirty(): void {
+    this.dirty = true;
+    if (this.autoFlush && !this.flushScheduled) {
+      this.flushScheduled = true;
+      queueMicrotask(() => {
+        this.flushScheduled = false;
+        this.flush();
+      });
+    }
+  }
+
+  private flush(): void {
+    if (!this.dirty) return;
+    this.dirty = false;
+    this.recompute();
+    for (const l of this.listeners) l();
+  }
+
+  // --- recompute ---------------------------------------------------------------
+
+  private recompute(): void {
+    let opt: OptimisticInspect | undefined;
+    if (this.backend) {
+      try {
+        opt = this.backend.__inspect();
+      } catch {
+        opt = undefined; // a malformed/throwing dev hook never breaks the pane
+      }
+    }
+    if (opt) this.reconcileTimeline(opt);
+    this.rebuildQueries(opt);
+    this.optimistic = opt;
+    this.churnSeen = false;
+    this.snapshot = {
+      timeline: this.order.map((id) => this.timeline.get(id)).filter((e): e is TimelineEntry => !!e),
+      queries: this.queries,
+      deltas: this.deltas.slice(),
+      optimistic: opt,
+      capabilities: { optimistic: !!this.backend },
+    };
+  }
+
+  /** Reconstruct the fork/rebase lifecycle by diffing this pending snapshot against the previous
+   *  one (DEBUG-TOOLS-BROWSER-DESIGN §4.1): new keys → invoked; vanished keys → confirmed (mid ≤
+   *  confirmedLmid) or dropped; a fold's `f:<foldKey>` → `m:<mid>` transition is linked, not double
+   *  counted. */
+  private reconcileTimeline(opt: OptimisticInspect): void {
+    const now = this.now();
+    const cur = opt.pending;
+    const curKeys = new Set(cur.map((p) => p.key));
+
+    const removed: string[] = [];
+    for (const k of this.prevPendingKeys) if (!curKeys.has(k)) removed.push(k);
+    const added = cur.filter((p) => !this.prevPendingKeys.has(p.key));
+
+    // Fold-flush linking: an `f:<foldKey>` that vanished as an `m:<mid>` of the same (name, args)
+    // appeared is one logical mutation crossing the wire — relabel in place (FOLDED-MUTATIONS §4.1).
+    const linkedF = new Set<string>();
+    const linkedM = new Set<string>();
+    for (const fkey of removed) {
+      if (!fkey.startsWith("f:")) continue;
+      const fEntry = this.timeline.get(fkey);
+      if (!fEntry) continue;
+      const match = added.find(
+        (p) => p.key.startsWith("m:") && !linkedM.has(p.key) && p.name === fEntry.name && argsEqual(p.args, fEntry.args),
+      );
+      if (!match) continue;
+      this.renameEntry(fkey, match.key);
+      const e = this.timeline.get(match.key);
+      if (e) {
+        e.mid = match.mid;
+        e.tables = match.tables;
+        e.folded = true;
+        // A flushed fold has already left `folds`, so the m:<mid> snapshot carries no `fold` window —
+        // keep the one captured while it was debouncing and just mark it flushed.
+        const window = match.fold ?? e.fold;
+        e.fold = window ? { ...window, flushed: true } : undefined;
+      }
+      linkedF.add(fkey);
+      linkedM.add(match.key);
+    }
+
+    // Freshly invoked entries (not the m: side of a link).
+    for (const p of added) {
+      if (linkedM.has(p.key) || this.timeline.has(p.key)) continue;
+      this.addEntry({
+        id: p.key,
+        mid: p.mid,
+        name: p.name,
+        args: p.args,
+        tables: p.tables,
+        state: "pending",
+        folded: !!p.fold,
+        fold: p.fold,
+        invokedAt: now,
+        reconciledWithChurn: false,
+        affectedQueries: [],
+      });
+    }
+
+    // Refresh still-pending entries (a rebase re-invoke can change touched tables / args / mid).
+    for (const p of cur) {
+      const e = this.timeline.get(p.key);
+      if (!e || e.state !== "pending") continue;
+      e.mid = p.mid;
+      e.args = p.args;
+      e.tables = p.tables;
+      if (p.fold) {
+        e.folded = true;
+        e.fold = p.fold;
+      }
+    }
+
+    // Settle vanished entries (those not consumed by a fold link).
+    for (const k of removed) {
+      if (linkedF.has(k)) continue;
+      const e = this.timeline.get(k);
+      if (!e || e.state !== "pending") continue;
+      const confirmed = e.mid != null && e.mid <= opt.confirmedLmid;
+      e.state = confirmed ? "confirmed" : "dropped";
+      e.settledAt = now;
+      e.reconciledWithChurn = confirmed && this.churnSeen;
+    }
+
+    this.prevPendingKeys = curKeys;
+  }
+
+  private rebuildQueries(opt: OptimisticInspect | undefined): void {
+    const pendingTables = new Set(opt?.pendingTables ?? []);
+    const queries: QueryEntry[] = this.store.__inspect(this.sampleRows).queries.map((q) => {
+      const tables = [...collectTables(q.ast)];
+      return {
+        qid: q.qid,
+        ast: q.ast,
+        table: q.ast.table,
+        summary: summarizeAst(q.ast),
+        tables,
+        resultType: q.resultType,
+        rowCount: q.rowCount,
+        sample: q.sample,
+        pending: tables.some((t) => pendingTables.has(t)),
+      };
+    });
+    this.queries = queries;
+
+    // Recompute each timeline entry's affected queries against the CURRENT live views.
+    if (this.timeline.size > 0) {
+      for (const e of this.timeline.values()) {
+        const touched = new Set(e.tables);
+        e.affectedQueries = queries.filter((q) => q.tables.some((t) => touched.has(t))).map((q) => q.qid);
+      }
+    }
+  }
+
+  // --- delta ring --------------------------------------------------------------
+
+  private pushDelta(qid: QueryId, ev: ChangeEvent): void {
+    if (ev.type === "hello") {
+      this.appendDelta(qid, "hello", 0, `hello · ${ev.schema.columns.length} col${ev.schema.columns.length === 1 ? "" : "s"}`);
+    } else if (ev.type === "snapshot") {
+      const n = ev.adds.length;
+      this.appendDelta(qid, "snapshot", 0, `snapshot · +${n} row${n === 1 ? "" : "s"}${ev.last ? "" : " (chunk)"}`);
+    } else {
+      for (const ch of ev.events) {
+        const depth = ch.path.length;
+        this.appendDelta(qid, ch.op.tag, depth, describeOp(ch.op) + (depth > 0 ? `  (child @${depth})` : ""));
+      }
+    }
+  }
+
+  private appendDelta(qid: QueryId, kind: DeltaKind, depth: number, label: string): void {
+    this.deltas.push({ seq: this.deltaSeq++, at: this.now(), qid, kind, depth, label });
+    if (this.deltas.length > this.deltaCap) this.deltas.splice(0, this.deltas.length - this.deltaCap);
+  }
+
+  // --- timeline map bookkeeping ------------------------------------------------
+
+  private addEntry(entry: TimelineEntry): void {
+    this.timeline.set(entry.id, entry);
+    this.order.push(entry.id);
+    // Cap: evict the oldest SETTLED rows first; never drop a live pending row.
+    while (this.order.length > this.timelineCap) {
+      const idx = this.order.findIndex((id) => this.timeline.get(id)?.state !== "pending");
+      if (idx < 0) break;
+      const [evicted] = this.order.splice(idx, 1);
+      this.timeline.delete(evicted);
+    }
+  }
+
+  private renameEntry(oldId: string, newId: string): void {
+    const e = this.timeline.get(oldId);
+    if (!e) return;
+    this.timeline.delete(oldId);
+    e.id = newId;
+    this.timeline.set(newId, e);
+    const i = this.order.indexOf(oldId);
+    if (i >= 0) this.order[i] = newId;
+  }
+}
+
+/** Structural args equality for fold-flush linking (args are JSON-serializable mutator inputs). */
+function argsEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+}
+
+function describeOp(op: FlatOp): string {
+  if (op.tag === "add") return `add ${rowPreview(op.node.row)}`;
+  if (op.tag === "remove") return `remove ${rowPreview(op.row)}`;
+  return `edit ${rowPreview(op.old)} → ${rowPreview(op.new)}`;
+}
+
+function rowPreview(row: readonly unknown[]): string {
+  const head = row.slice(0, 3).map(cellStr).join(", ");
+  return `[${head}${row.length > 3 ? ", …" : ""}]`;
+}
+
+function cellStr(v: unknown): string {
+  if (typeof v === "string") return v.length > 16 ? `"${v.slice(0, 15)}…"` : `"${v}"`;
+  return String(v);
+}

package/src/global.ts

@@ -0,0 +1,79 @@
+// The opt-in global registry (DEBUG-TOOLS-BROWSER-DESIGN.md §6.2). The client core stays clean —
+// no global mutable singleton lives in `@rindle/client`/`@rindle/optimistic`. Instead a dev build
+// calls `attachDevtools(app)`, which constructs a {@link DevtoolsCore} and registers it on
+// `globalThis.__RINDLE_DEVTOOLS__`, the same discovery pattern TanStack/Redux DevTools use. A panel
+// finds the hub with {@link getDevtoolsHub} and subscribes — so it works whether it mounts before or
+// after the app attaches.
+
+import { DevtoolsCore } from "./core.ts";
+import type { DevtoolsCoreOptions, DevtoolsTarget } from "./types.ts";
+
+const GLOBAL_KEY = "__RINDLE_DEVTOOLS__";
+
+/** The discovery surface a panel binds to: the set of attached cores + a change subscription. */
+export interface DevtoolsHub {
+  readonly version: number;
+  readonly cores: readonly DevtoolsCore[];
+  /** Fires whenever a core attaches or detaches (so a panel can pick one up). */
+  subscribe(listener: () => void): () => void;
+  /** Register a core; returns its deregistration function. */
+  register(core: DevtoolsCore): () => void;
+}
+
+class Hub implements DevtoolsHub {
+  readonly version = 1;
+  readonly cores: DevtoolsCore[] = [];
+  private readonly listeners = new Set<() => void>();
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  register(core: DevtoolsCore): () => void {
+    this.cores.push(core);
+    this.emit();
+    return () => {
+      const i = this.cores.indexOf(core);
+      if (i >= 0) {
+        this.cores.splice(i, 1);
+        this.emit();
+      }
+    };
+  }
+
+  private emit(): void {
+    for (const l of this.listeners) l();
+  }
+}
+
+function globalSlot(): Record<typeof GLOBAL_KEY, Hub | undefined> {
+  return globalThis as unknown as Record<typeof GLOBAL_KEY, Hub | undefined>;
+}
+
+/** Get (creating on first use) the global devtools hub. A panel calls this to discover attached
+ *  clients; it is safe to call before any `attachDevtools`. */
+export function getDevtoolsHub(): DevtoolsHub {
+  const slot = globalSlot();
+  return (slot[GLOBAL_KEY] ??= new Hub());
+}
+
+/** The most recently attached core, or `undefined` — the common single-app convenience a panel uses. */
+export function getDevtoolsCore(): DevtoolsCore | undefined {
+  const cores = getDevtoolsHub().cores;
+  return cores[cores.length - 1];
+}
+
+/** Attach a devtools pane to a running client (DEBUG-TOOLS-BROWSER-DESIGN §6.2). Call this ONLY in a
+ *  dev build (e.g. behind `import.meta.env.DEV` with a dynamic `import("@rindle/devtools")`) so the
+ *  pane, its core, and this registration tree-shake out of production. Returns the {@link DevtoolsCore}
+ *  (also discoverable via {@link getDevtoolsHub}); call `core.detach()` to unwind. */
+export function attachDevtools(target: DevtoolsTarget, opts?: DevtoolsCoreOptions): DevtoolsCore {
+  // Default the safety-net poll on for real apps (a fold's debounced flush / a pending flip on an
+  // already-`complete` query move state with no event); tests construct DevtoolsCore directly.
+  const core = new DevtoolsCore(target, { pollMs: 500, ...opts });
+  core.onDetach = getDevtoolsHub().register(core);
+  return core;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// @rindle/devtools — the framework-agnostic in-browser devtools core (DEBUG-TOOLS-BROWSER-DESIGN.md).
+// Attaches to a running client over the read-only seams and maintains the §4 read-model: a mutation
+// TIMELINE (the fork/rebase loop made visible), a QUERIES inspector, and a DELTA stream. Dev-only;
+// pair it with a panel (`@rindle/react-devtools`) or read `getDevtoolsCore().getState()` directly.
+
+export { DevtoolsCore } from "./core.ts";
+export { attachDevtools, getDevtoolsCore, getDevtoolsHub } from "./global.ts";
+export type { DevtoolsHub } from "./global.ts";
+
+export { collectTables, summarizeAst } from "./ast.ts";
+
+export type {
+  DeltaEntry,
+  DeltaKind,
+  DevtoolsBackend,
+  DevtoolsCoreOptions,
+  DevtoolsState,
+  DevtoolsStore,
+  DevtoolsTarget,
+  FoldInspect,
+  MutationState,
+  OptimisticInspect,
+  PendingInspect,
+  QueryEntry,
+  TimelineEntry,
+} from "./types.ts";
+
+// Re-export the client types a panel or a custom attach target needs, so it can depend on
+// `@rindle/devtools` alone.
+export type { Ast, ChangeEvent, QueryId, ResultType, StoreDevObserver, StoreInspect } from "@rindle/client";