@buoy-gg/shared-ui 7.0.32 → 7.0.34

package/lib/module/ui/otto/ottoSheet.js

@@ -0,0 +1,180 @@
+"use strict";
+
+/**
+ * Otto's precomputed animation.
+ *
+ * Every state is a short loop (48 ticks at most). This module renders that
+ * loop once, splits it into a BODY layer and a 7-frame WATER layer (they
+ * composite back pixel-for-pixel: compose() only paints water into empty
+ * cells and blanks a submerged body below the waterline), dedupes the
+ * frames, and turns each distinct frame into merged rectangles. The shipping
+ * <Otto/> mounts those rectangles ONCE as a strip of static Views and slides
+ * a window over the strip on the UI thread.
+ *
+ * Why: the buoy-optimize rounds in OTTO_PERF_PLAN.md showed that any renderer
+ * re-creating Views per tick pegs the JS thread (5 FPS at 34 sprites, dropped
+ * UI frames even at 1 sprite), while "mount once, move a window natively"
+ * costs nothing per tick and keeps moving while JS is blocked.
+ *
+ * Everything here is pure `react-native`-free TypeScript, cached per state.
+ */
+import { OTTO_GRID, OTTO_PALETTE, ottoWaterRows, renderOttoFrame } from "./ottoEngine.js";
+export const CELLS = OTTO_GRID * OTTO_GRID;
+export const WATER_ROW0 = 13;
+export const WATER_ROWS = OTTO_GRID - WATER_ROW0;
+export const WATER_CELLS = WATER_ROWS * OTTO_GRID;
+/** The wave is a function of floor(t/2) mod 7. */
+export const WATER_FRAMES = 7;
+export const TRANSPARENT = "transparent";
+/** Longest state cycle in ticks (idle and sleep are 48). */
+export const MAX_PERIOD = 48;
+export function gridKey(grid) {
+  return grid.map(r => r.join("")).join("|");
+}
+
+/** Flat 256 colours, row-major, `transparent` for empty cells. */
+export function flatColors(grid) {
+  const out = new Array(CELLS);
+  for (let y = 0; y < OTTO_GRID; y++) {
+    const row = grid[y];
+    for (let x = 0; x < OTTO_GRID; x++) out[y * OTTO_GRID + x] = OTTO_PALETTE[row[x]] ?? TRANSPARENT;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- cycle ---
+
+const cycleCache = new Map();
+export function ottoCycle(state, keyline) {
+  const cacheKey = `${state}|${keyline ? 1 : 0}`;
+  const hit = cycleCache.get(cacheKey);
+  if (hit) return hit;
+  const keys = [];
+  const grids = [];
+  for (let t = 0; t < MAX_PERIOD * 2; t++) {
+    const g = renderOttoFrame(state, t, {
+      water: false,
+      keyline
+    });
+    grids.push(g);
+    keys.push(gridKey(g));
+  }
+  let period = MAX_PERIOD;
+  for (let P = 1; P <= MAX_PERIOD; P++) {
+    let ok = true;
+    for (let t = 0; t < MAX_PERIOD; t++) {
+      if (keys[t] !== keys[t + P]) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) {
+      period = P;
+      break;
+    }
+  }
+  const body = grids.slice(0, period).map(flatColors);
+  const water = [];
+  for (let w = 0; w < WATER_FRAMES; w++) {
+    const flat = [];
+    for (const row of ottoWaterRows(w * 2)) for (const k of row) flat.push(OTTO_PALETTE[k] ?? TRANSPARENT);
+    water.push(flat);
+  }
+  const cycle = {
+    period,
+    body,
+    water
+  };
+  cycleCache.set(cacheKey, cycle);
+  return cycle;
+}
+
+/** Frame indexes for a cycle at local tick `t`. */
+export function cycleIndexes(t, period) {
+  const local = Math.max(0, t);
+  return {
+    bi: local % period,
+    wi: Math.floor(local / 2) % WATER_FRAMES
+  };
+}
+
+// ---------------------------------------------------------------- rects ---
+
+/**
+ * Same-colour runs per row, then runs merged with the identical run directly
+ * below them — roughly a third fewer Views than row runs alone. Covers
+ * exactly the non-transparent cells, never overlaps (proved offline over
+ * every frame of every state).
+ */
+export function rectsOf(colors, cols, rows) {
+  const open = [];
+  const done = [];
+  for (let y = 0; y < rows; y++) {
+    const rowRuns = [];
+    let x = 0;
+    while (x < cols) {
+      const color = colors[y * cols + x];
+      let w = 1;
+      while (x + w < cols && colors[y * cols + x + w] === color) w++;
+      if (color !== TRANSPARENT) rowRuns.push({
+        x,
+        y,
+        w,
+        h: 1,
+        color
+      });
+      x += w;
+    }
+    const next = [];
+    for (const r of rowRuns) {
+      const above = open.find(o => o.x === r.x && o.w === r.w && o.color === r.color && o.y + o.h === r.y);
+      if (above) {
+        above.h += 1;
+        next.push(above);
+      } else {
+        next.push(r);
+      }
+    }
+    for (const o of open) if (!next.includes(o)) done.push(o);
+    open.length = 0;
+    open.push(...next);
+  }
+  done.push(...open);
+  return done;
+}
+
+// ---------------------------------------------------------------- sheets --
+
+/** One layer as a strip of distinct frames, and which frame each tick shows. */
+
+const sheetCache = new Map();
+function stripOf(frames, cols, rows) {
+  const keys = frames.map(f => f.join(","));
+  const indexOf = new Map();
+  const distinct = [];
+  keys.forEach((k, i) => {
+    if (!indexOf.has(k)) {
+      indexOf.set(k, distinct.length);
+      distinct.push(rectsOf(frames[i], cols, rows));
+    }
+  });
+  return {
+    colOf: keys.map(k => indexOf.get(k) ?? 0),
+    frames: distinct
+  };
+}
+
+/** Both layers of a state as strips of rectangles. Pure; cached per state. */
+export function ottoSheets(state, keyline) {
+  const key = `${state}|${keyline ? 1 : 0}`;
+  const hit = sheetCache.get(key);
+  if (hit) return hit;
+  const cycle = ottoCycle(state, keyline);
+  const built = {
+    period: cycle.period,
+    body: stripOf(cycle.body, OTTO_GRID, OTTO_GRID),
+    water: stripOf(cycle.water, OTTO_GRID, WATER_ROWS)
+  };
+  sheetCache.set(key, built);
+  return built;
+}

package/lib/module/utils/snapshotProviderKit.js

@@ -0,0 +1,156 @@
+"use strict";
+
+/**
+ * snapshotProviderKit — the parts of a Time Machine `StateSnapshotProvider`
+ * that are the same for every source.
+ *
+ * storage, redux, zustand, jotai and react-query each register a provider
+ * (see stateSnapshotRegistry.ts). What differs is how they read and write
+ * their source. What was copied five times is:
+ *
+ *  - the restore SCOPE gate: `excludeKeys` (touch all but these) and
+ *    `includeKeys` (touch only these), the "N item(s) excluded by you"
+ *    warning, and the empty `StateSnapshotRestoreResult`;
+ *  - the preview VERDICT ladder: removed → added → unchanged → too-large →
+ *    changed, with the 256 KB per-item render cap;
+ *  - the "won't apply" override: a difference restore cannot apply must say
+ *    so instead of rendering as a green change.
+ *
+ * The parts that stay per-tool are the ones that matter: redux verifies the
+ * jump by reference identity, zustand grafts action functions back, jotai
+ * leaves derived atoms to recompute, storage gates MMKV buffers and
+ * biometric keys, react-query diffs a comparable projection.
+ */
+
+import { boundedDeepEqual, jsonLikelyLargerThan } from "../dataViewer/objectDiff.js";
+/** Beyond this a preview item is "too-large": restore still applies it, the diff isn't drawn. */
+export const PREVIEW_ITEM_RENDER_BYTE_LIMIT = 256 * 1024;
+/**
+ * Both option lists use preview item keys, and both mean "leave everything
+ * else untouched in BOTH directions". `includeKeys` wins when present;
+ * `excludeKeys` still applies on top.
+ */
+export function createRestoreScope(options) {
+  const excludedSet = new Set(options?.excludeKeys ?? []);
+  const includedSet = options?.includeKeys ? new Set(options.includeKeys) : null;
+  let excludedHits = 0;
+  const touch = key => !excludedSet.has(key) && (!includedSet || includedSet.has(key));
+  return {
+    touch,
+    allows(key) {
+      if (touch(key)) return true;
+      excludedHits += 1;
+      return false;
+    },
+    countExcluded(n) {
+      excludedHits += n;
+    },
+    get excludedHits() {
+      return excludedHits;
+    },
+    excludedWarning(noun) {
+      return excludedHits > 0 ? `${excludedHits} ${noun} excluded by you` : null;
+    }
+  };
+}
+
+/** A fresh, successful, empty result to accumulate into. */
+export function emptyRestoreResult() {
+  return {
+    ok: true,
+    applied: 0,
+    skipped: [],
+    warnings: []
+  };
+}
+
+/** A failed result with one warning (an empty or unusable snapshot). */
+export function failedRestore(warning) {
+  return {
+    ok: false,
+    applied: 0,
+    skipped: [],
+    warnings: [warning]
+  };
+}
+
+/** A failed result with one skipped item and its reason. */
+export function skippedRestore(id, reason) {
+  return {
+    ok: false,
+    applied: 0,
+    skipped: [{
+      id,
+      reason
+    }],
+    warnings: []
+  };
+}
+/**
+ * The verdict ladder: removed → added → unchanged → too-large → changed.
+ * Callers layer source-specific verdicts (`wont-apply`, `recomputes`) on top
+ * with `wontApply()`.
+ */
+export function classifyPreviewItem(input, options = {}) {
+  const {
+    key,
+    label,
+    oldValue,
+    newValue,
+    inOld,
+    inNew
+  } = input;
+  if (!inNew) return {
+    key,
+    label,
+    verdict: "removed",
+    oldValue
+  };
+  if (!inOld) return {
+    key,
+    label,
+    verdict: "added",
+    newValue
+  };
+  const equal = options.equal ?? boundedDeepEqual;
+  if (equal(oldValue, newValue)) return {
+    key,
+    label,
+    verdict: "unchanged"
+  };
+  const tooLarge = options.tooLarge ?? (value => jsonLikelyLargerThan(value, PREVIEW_ITEM_RENDER_BYTE_LIMIT));
+  if (tooLarge(oldValue) || tooLarge(newValue)) {
+    return {
+      key,
+      label,
+      verdict: "too-large",
+      reason: options.tooLargeReason ?? "value too large to render a diff — restore still applies it"
+    };
+  }
+  return {
+    key,
+    label,
+    verdict: "changed",
+    oldValue,
+    newValue
+  };
+}
+
+/**
+ * Mark an item as something restore cannot apply. An unchanged item is left
+ * alone — there is nothing to apply, so nothing is being refused.
+ */
+export function wontApply(item, reason) {
+  if (item.verdict === "unchanged") return item;
+  return {
+    ...item,
+    verdict: "wont-apply",
+    reason
+  };
+}
+
+/** Every key present in either record, once. */
+export function unionKeys(a, b) {
+  const keysOf = r => r === undefined ? [] : r instanceof Map ? Array.from(r.keys()) : Object.keys(r);
+  return new Set([...keysOf(a), ...keysOf(b)]);
+}

package/lib/module/utils/stateTools.js

@@ -0,0 +1,154 @@
+"use strict";
+
+/**
+ * stateTools — helpers the state tools (redux / zustand / jotai) each carried
+ * a private copy of. Pure functions; no React, no RN.
+ */
+
+// ============================================
+// Entity color
+// ============================================
+
+/**
+ * Consistent color for a named entity (a zustand store, a jotai atom, a redux
+ * slice). Exact match on `known` wins, then a substring match, then a stable
+ * HSL hash of the name rendered as `#rrggbb` so the "color + alpha hex"
+ * pattern works everywhere.
+ */
+export function entityColor(name, known = {}) {
+  const lower = name.toLowerCase();
+  if (known[lower]) return known[lower];
+  for (const [key, color] of Object.entries(known)) {
+    if (lower.includes(key)) return color;
+  }
+  const hash = name.split("").reduce((acc, char) => acc + char.charCodeAt(0), 0);
+  const hue = hash * 137 % 360;
+  const s = 0.7;
+  const l = 0.6;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(hue / 60 % 2 - 1));
+  const m = l - c / 2;
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  if (hue < 60) {
+    r = c;
+    g = x;
+  } else if (hue < 120) {
+    r = x;
+    g = c;
+  } else if (hue < 180) {
+    g = c;
+    b = x;
+  } else if (hue < 240) {
+    g = x;
+    b = c;
+  } else if (hue < 300) {
+    r = x;
+    b = c;
+  } else {
+    r = c;
+    b = x;
+  }
+  const toHex = v => Math.round((v + m) * 255).toString(16).padStart(2, "0");
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+// ============================================
+// Value preview
+// ============================================
+
+/**
+ * One-line preview of an arbitrary value for a list row: strings quoted and
+ * truncated, arrays and objects stringified when short, otherwise collapsed
+ * to `[N items]` / `{ N keys }`. Never throws.
+ */
+export function formatValuePreview(value, options = {}) {
+  const maxLength = options.maxLength ?? 40;
+  if (value === undefined) return options.undefinedLabel ?? "undefined";
+  if (value === null) return "null";
+  try {
+    if (typeof value === "function") return options.functionLabel ?? "(fn)";
+    if (typeof value === "string") {
+      return value.length > maxLength ? `"${value.slice(0, maxLength - 3)}..."` : `"${value}"`;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+      return String(value);
+    }
+    if (Array.isArray(value)) {
+      if (value.length === 0) return "[]";
+      const preview = JSON.stringify(value);
+      return preview.length > maxLength ? `[${value.length} items]` : preview;
+    }
+    if (typeof value === "object") {
+      const keys = Object.keys(value);
+      if (keys.length === 0) return "{}";
+      const preview = JSON.stringify(value);
+      if (preview.length <= maxLength) return preview;
+      return `{ ${keys.length} keys }`;
+    }
+    return String(value).slice(0, maxLength);
+  } catch {
+    return "[complex]";
+  }
+}
+
+// ============================================
+// Shallow diff summary
+// ============================================
+
+/**
+ * Top-level, reference-equality diff between two states. Enough for a list
+ * row ("+1 ~2 keys"); the detail view runs the real tree diff.
+ *
+ * A state object that was REPLACED without any top-level value moving —
+ * exactly what zustand's persist middleware does when it rehydrates — is
+ * reported as `"nested change"` with no keys, never as one changed key with
+ * none named.
+ */
+export function shallowDiffSummary(prev, next) {
+  if (prev === next) {
+    return {
+      summary: "no change",
+      changedKeys: [],
+      changedCount: 0
+    };
+  }
+  if (typeof prev !== "object" || typeof next !== "object" || prev === null || next === null) {
+    return {
+      summary: "changed",
+      changedKeys: [],
+      changedCount: 0
+    };
+  }
+  const prevRecord = prev;
+  const nextRecord = next;
+  const prevKeys = Object.keys(prevRecord);
+  const nextKeys = Object.keys(nextRecord);
+  const added = nextKeys.filter(k => !prevKeys.includes(k));
+  const removed = prevKeys.filter(k => !nextKeys.includes(k));
+  const changed = [];
+  for (const key of prevKeys) {
+    if (nextKeys.includes(key) && prevRecord[key] !== nextRecord[key]) {
+      changed.push(key);
+    }
+  }
+  const changedKeys = [...added, ...removed, ...changed];
+  const parts = [];
+  if (added.length > 0) parts.push(`+${added.length}`);
+  if (removed.length > 0) parts.push(`-${removed.length}`);
+  if (changed.length > 0) parts.push(`~${changed.length}`);
+  if (parts.length === 0) {
+    return {
+      summary: "nested change",
+      changedKeys: [],
+      changedCount: 0
+    };
+  }
+  const total = changedKeys.length;
+  return {
+    summary: `${parts.join(" ")} ${total === 1 ? "key" : "keys"}`,
+    changedKeys,
+    changedCount: total
+  };
+}

package/lib/typescript/commonjs/JsModal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JsModal.d.ts","sourceRoot":"","sources":["../../../src/JsModal.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAUL,SAAS,EAEV,MAAM,OAAO,CAAC;AACf,OAAO,EAML,QAAQ,EAGR,SAAS,EAEV,MAAM,cAAc,CAAC;AAyHtB,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/C,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,UAAU,YAAY;IACpB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,kBAAkB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAED,UAAU,YAAY;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;IAChC;;;+BAG2B;IAC3B,WAAW,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,cAAc,GAAG,YAAY,CAAC;IACtE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,uBAAuB,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAErD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;IAC9C,0EAA0E;IAC1E,sBAAsB,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gIAAgI;IAChI,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iDAAiD;IACjD,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AA6xDD,eAAO,MAAM,OAAO,oDAAyB,CAAC"}
+{"version":3,"file":"JsModal.d.ts","sourceRoot":"","sources":["../../../src/JsModal.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAUL,SAAS,EAEV,MAAM,OAAO,CAAC;AACf,OAAO,EAML,QAAQ,EAGR,SAAS,EAEV,MAAM,cAAc,CAAC;AAyHtB,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/C,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,UAAU,YAAY;IACpB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,kBAAkB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAED,UAAU,YAAY;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC;IAChC;;;+BAG2B;IAC3B,WAAW,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,cAAc,GAAG,YAAY,CAAC;IACtE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,uBAAuB,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAErD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;IAC9C,0EAA0E;IAC1E,sBAAsB,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gIAAgI;IAChI,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iDAAiD;IACjD,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAo0DD,eAAO,MAAM,OAAO,oDAAyB,CAAC"}

package/lib/typescript/commonjs/hooks/index.d.ts

@@ -1,5 +1,7 @@
 export { useFilterManager } from "./useFilterManager";
-export { usePersistedState } from "./usePersistedState";
+export { usePersistedState, resetPersistedStateCache, type PersistedStateOptions, type PersistedStateStorage, } from "./usePersistedState";
+export { useChangeLog, useSubscribedValue, type UseChangeLogOptions, type UseChangeLogResult, } from "./useChangeLog";
+export { useEventStoreEvents, type UseEventStoreEventsOptions, type UseEventStoreEventsResult, } from "./useEventStoreEvents";
 export { useSafeAreaInsets } from "./useSafeAreaInsets";
 export { getSafeAreaInsets } from "./useSafeAreaInsets";
 export { useDeviceInfo, getDeviceInfo, logDeviceInfo, type DeviceInfo, type PlatformInfo, type DisplayInfo, type AccessibilitySettings, type AppearanceInfo, type LocaleInfo, type StatusBarInfo, type KeyboardInfo, type AppStateInfo, type UniqueIdentifiers, type SettingsInfo, } from "./useDeviceInfo";

package/lib/typescript/commonjs/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,GAC/B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC"}

package/lib/typescript/commonjs/hooks/safe-area-impl.d.ts

@@ -1,7 +1,7 @@
 /**
  * Auto-generated safe area implementation
  * Detected: none
- * Generated at: 2026-09-01T17:57:34.045Z
+ * Generated at: 2026-09-04T01:21:28.486Z
  *
  * DO NOT EDIT - This file is generated by scripts/detect-safe-area.js
  *

package/lib/typescript/commonjs/hooks/useChangeLog.d.ts

@@ -0,0 +1,38 @@
+/**
+ * React bindings for `ChangeLog` — what useReduxActions, useZustandStateChanges
+ * and useJotaiAtomChanges each re-derived: seed state from the log, subscribe
+ * for the lifetime of the component, hold a filter, memoize the filtered
+ * list, and expose clear / pause / lookup.
+ *
+ * Tool-specific stats and registries (stores, atoms) compose on top — see
+ * `useSubscribedValue` for the registry half.
+ */
+import type { ChangeLog, Identified } from "../stores/ChangeLog";
+export interface UseChangeLogOptions<T, F> {
+    /** Initial filter value. Default `{}`. */
+    initialFilter?: F;
+    /** Derive the filtered list. Default: identity (no filtering). */
+    filterItems?: (items: T[], filter: F) => T[];
+}
+export interface UseChangeLogResult<T, F> {
+    /** All recorded items, newest first. */
+    items: T[];
+    /** `items` after `filterItems`. */
+    filteredItems: T[];
+    filter: F;
+    setFilter: React.Dispatch<React.SetStateAction<F>>;
+    /** Whether recording is enabled (the pause button's state). */
+    isEnabled: boolean;
+    /** Flip recording on/off. */
+    toggleCapture: () => void;
+    /** Empty the log (fires the desktop mirror's clear forwarding). */
+    clear: () => void;
+    getById: (id: string) => T | undefined;
+}
+export declare function useChangeLog<T extends Identified, F extends object = Record<string, never>>(log: ChangeLog<T>, options?: UseChangeLogOptions<T, F>): UseChangeLogResult<T, F>;
+/**
+ * Hold a value that a store pushes through a `(value) => void` listener —
+ * a registry of stores, atoms, sources. Seeded synchronously from `read`.
+ */
+export declare function useSubscribedValue<V>(read: () => V, subscribe: (listener: (value: V) => void) => () => void): V;
+//# sourceMappingURL=useChangeLog.d.ts.map

package/lib/typescript/commonjs/hooks/useChangeLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChangeLog.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useChangeLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,WAAW,mBAAmB,CAAC,CAAC,EAAE,CAAC;IACvC,0CAA0C;IAC1C,aAAa,CAAC,EAAE,CAAC,CAAC;IAClB,kEAAkE;IAClE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,EAAE,CAAC;IACtC,wCAAwC;IACxC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,mCAAmC;IACnC,aAAa,EAAE,CAAC,EAAE,CAAC;IACnB,MAAM,EAAE,CAAC,CAAC;IACV,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;IACnB,6BAA6B;IAC7B,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,mEAAmE;IACnE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,CAAC;CACxC;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACzF,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,EACjB,OAAO,GAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAM,GACtC,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CA0B1B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,IAAI,EAAE,MAAM,CAAC,EACb,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,GACtD,CAAC,CAIH"}

package/lib/typescript/commonjs/hooks/useEventStoreEvents.d.ts

@@ -0,0 +1,25 @@
+/**
+ * React bindings for a `BaseEventStore` — what useRouteEvents and
+ * useStorageEvents each hand-rolled: subscribe while enabled (which
+ * auto-starts the store's capture), coalesce bursts onto one animation
+ * frame so a storm of writes is one commit instead of one per emission,
+ * select/limit the list, and report whether capture is live.
+ */
+import type { BaseEventStore } from "../stores/BaseEventStore";
+export interface UseEventStoreEventsOptions<T> {
+    /** Subscribe at all? `false` unsubscribes (and lets the store stop capturing). Default true. */
+    enabled?: boolean;
+    /** Cap the list handed to React. Default 500. */
+    maxEvents?: number;
+    /** Narrow the list before capping (a storage-type filter, say). */
+    select?: (events: T[]) => T[];
+}
+export interface UseEventStoreEventsResult<T> {
+    /** Newest first. */
+    events: T[];
+    clearEvents: () => void;
+    /** True while this hook holds a live subscription. */
+    isActive: boolean;
+}
+export declare function useEventStoreEvents<T>(store: BaseEventStore<T>, options?: UseEventStoreEventsOptions<T>): UseEventStoreEventsResult<T>;
+//# sourceMappingURL=useEventStoreEvents.d.ts.map

package/lib/typescript/commonjs/hooks/useEventStoreEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEventStoreEvents.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useEventStoreEvents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,MAAM,WAAW,0BAA0B,CAAC,CAAC;IAC3C,gGAAgG;IAChG,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,oBAAoB;IACpB,MAAM,EAAE,CAAC,EAAE,CAAC;IACZ,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,sDAAsD;IACtD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EACxB,OAAO,GAAE,0BAA0B,CAAC,CAAC,CAAM,GAC1C,yBAAyB,CAAC,CAAC,CAAC,CA8C9B"}

package/lib/typescript/commonjs/hooks/usePersistedState.d.ts

@@ -1,16 +1,45 @@
+/** The two calls a backend needs. `persistentStorage` and AsyncStorage both fit. */
+export interface PersistedStateStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+}
+export interface PersistedStateOptions<T> {
+    /**
+     * Turn the stored string into a value. Return `undefined` to reject it
+     * (corrupt, or a value the UI no longer offers) and keep the default.
+     * Default: `JSON.parse`.
+     */
+    parse?: (raw: string) => T | undefined;
+    /** Turn a value into the stored string. Default: `JSON.stringify`. */
+    serialize?: (value: T) => string;
+    /**
+     * Where the value lives. Default: `persistentStorage` (FileSystem →
+     * AsyncStorage → memory). A tool whose keys were always written straight to
+     * AsyncStorage keeps reading them by passing AsyncStorage here.
+     */
+    storage?: PersistedStateStorage;
+}
 /**
  * `useState` persisted through `persistentStorage` (FileSystem → AsyncStorage
  * → memory). Replaces the load-then-`hasLoaded`-guard `useEffect` pattern
  * every tool used to hand-roll.
  *
- * Values are JSON-serialized; the default is returned until hydration
- * completes (subsequent mounts of the same key hydrate synchronously from an
- * in-memory cache). The third tuple element reports hydration so callers can
- * defer writes that must not clobber a not-yet-loaded value.
+ * Values are JSON-serialized by default; the default is returned until
+ * hydration completes (subsequent mounts of the same key hydrate synchronously
+ * from an in-memory cache). The third tuple element reports hydration so
+ * callers can defer writes that must not clobber a not-yet-loaded value.
  *
  * ```tsx
  * const [tab, setTab, tabHydrated] = usePersistedState("@react_buoy_custom_flags_tab", "flags");
+ *
+ * // A Set, stored as an array:
+ * const [pins, setPins] = usePersistedState(key, new Set<string>(), {
+ *   parse: (raw) => new Set(JSON.parse(raw) as string[]),
+ *   serialize: (set) => JSON.stringify([...set]),
+ * });
  * ```
  */
-export declare function usePersistedState<T>(key: string, defaultValue: T): [T, (next: T | ((prev: T) => T)) => void, boolean];
+export declare function usePersistedState<T>(key: string, defaultValue: T, options?: PersistedStateOptions<T>): [T, (next: T | ((prev: T) => T)) => void, boolean];
+/** Test seam: forget every hydrated value. */
+export declare function resetPersistedStateCache(): void;
 //# sourceMappingURL=usePersistedState.d.ts.map

package/lib/typescript/commonjs/hooks/usePersistedState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePersistedState.d.ts","sourceRoot":"","sources":["../../../../src/hooks/usePersistedState.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,CAoDpD"}
+{"version":3,"file":"usePersistedState.d.ts","sourceRoot":"","sources":["../../../../src/hooks/usePersistedState.ts"],"names":[],"mappings":"AAUA,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,CAAC;IACvC,sEAAsE;IACtE,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,EACf,OAAO,GAAE,qBAAqB,CAAC,CAAC,CAAM,GACrC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,CA+DpD;AAED,8CAA8C;AAC9C,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}