@avasapp/agent-bridge 0.4.2 → 0.6.0

package/dist/adapters/react-navigation.cjs

@@ -0,0 +1,293 @@
+"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/adapters/react-navigation.ts
+var react_navigation_exports = {};
+__export(react_navigation_exports, {
+  navTools: () => navTools
+});
+module.exports = __toCommonJS(react_navigation_exports);
+
+// src/runtime/screen/settle.ts
+var STATE = /* @__PURE__ */ Symbol.for("@avasapp/agent-bridge/commits");
+var UPDATE_LANES = (1 << 22) - 1;
+var hook = () => globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+var now = () => performance.now();
+function install() {
+  const h = hook();
+  if (!h) return null;
+  const current = h.onCommitFiberRoot;
+  const existing = current?.[STATE];
+  if (existing) return existing;
+  const state = { commits: 0, listeners: /* @__PURE__ */ new Set() };
+  const wrapped = function(...args) {
+    state.commits += 1;
+    for (const listener of state.listeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+    return current?.apply(this, args);
+  };
+  Object.defineProperty(wrapped, STATE, { value: state });
+  h.onCommitFiberRoot = wrapped;
+  return state;
+}
+function busy() {
+  const h = hook();
+  if (!h?.renderers || !h.getFiberRoots) return false;
+  for (const id of h.renderers.keys()) {
+    for (const root of h.getFiberRoots(id)) {
+      const pending = root.pendingLanes;
+      if (typeof pending !== "number") continue;
+      if (pending & ~(root.suspendedLanes ?? 0) & UPDATE_LANES) return true;
+    }
+  }
+  return false;
+}
+var frame = () => new Promise((resolve) => {
+  const raf = globalThis.requestAnimationFrame;
+  if (raf) raf(() => resolve());
+  else setTimeout(resolve, 16);
+});
+async function settle(options = {}) {
+  const maxMs = options.maxMs ?? 500;
+  const t0 = now();
+  const state = install();
+  const start = state?.commits ?? 0;
+  const result = () => ({
+    commits: (state?.commits ?? 0) - start,
+    ms: Math.round((now() - t0) * 100) / 100
+  });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  if (!state) return result();
+  let seen = state.commits;
+  if (seen === start && !busy()) return result();
+  while (now() - t0 < maxMs) {
+    await frame();
+    if (state.commits === seen && !busy()) break;
+    seen = state.commits;
+  }
+  return result();
+}
+
+// src/adapters/react-navigation.ts
+var SETTLE_MS = 500;
+var focused = (state) => state.routes[state.index ?? state.routes.length - 1];
+function read(nav) {
+  if (!nav.isReady()) throw new Error("The navigation container has not mounted yet.");
+  const root = nav.getRootState();
+  const path = [];
+  let holder = root;
+  let stackHolder = root?.type === "stack" ? root : void 0;
+  let leaf = root && focused(root);
+  while (leaf) {
+    path.push(leaf.name);
+    if (!leaf.state?.routes.length) break;
+    holder = leaf.state;
+    if (holder.type === "stack") stackHolder = holder;
+    leaf = focused(holder);
+  }
+  const routes = stackHolder ? stackHolder.routes.slice(0, (stackHolder.index ?? stackHolder.routes.length - 1) + 1) : leaf ? [leaf] : [];
+  const out = {
+    name: leaf?.name ?? "",
+    path,
+    stack: routes.map((r) => r.params ? { name: r.name, params: r.params } : { name: r.name }),
+    canGoBack: nav.canGoBack()
+  };
+  if (leaf?.params) out.params = leaf.params;
+  return out;
+}
+function focusedNavigators(root) {
+  let holder = root;
+  let stack = root?.type === "stack" ? root : void 0;
+  let leaf = root && focused(root);
+  while (leaf?.state?.routes.length) {
+    holder = leaf.state;
+    if (holder.type === "stack") stack = holder;
+    leaf = focused(holder);
+  }
+  return { holder, stack };
+}
+function wantedChain(name, params) {
+  const chain = [name];
+  let p = params;
+  while (p && typeof p.screen === "string") {
+    chain.push(p.screen);
+    p = p.params;
+  }
+  return chain;
+}
+var endsWithChain = (path, chain) => path.some((_, i) => chain.every((n, j) => path[i + j] === n));
+function allRouteNames(state, into = /* @__PURE__ */ new Set()) {
+  if (!state) return into;
+  for (const n of state.routeNames ?? []) into.add(n);
+  for (const r of state.routes) {
+    into.add(r.name);
+    allRouteNames(r.state, into);
+  }
+  return into;
+}
+function nestedNavigate(state) {
+  const route = focused(state);
+  const next = route.state && route.state.routes.length ? nestedNavigate(route.state) : void 0;
+  if (!next) return [route.name, route.params];
+  return [route.name, { ...route.params, screen: next[0], ...next[1] ? { params: next[1] } : {} }];
+}
+function navTools(nav, options = {}) {
+  const parse = options.linking?.getStateFromPath ?? options.getStateFromPath;
+  const wait = (go) => new Promise((resolve, reject) => {
+    let off;
+    const done = () => {
+      off?.();
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(done, nav.addListener ? SETTLE_MS : 0);
+    off = nav.addListener?.("state", done);
+    try {
+      go();
+    } catch (error) {
+      off?.();
+      clearTimeout(timer);
+      reject(error);
+    }
+  });
+  const ready = () => {
+    if (!nav.isReady()) throw new Error("The navigation container has not mounted yet.");
+  };
+  const goTo = async (go, want) => {
+    ready();
+    const before = nav.getRootState();
+    await wait(go);
+    await settle();
+    const route = read(nav);
+    const missed = want && !endsWithChain(route.path, want.chain);
+    if (want && (missed || want.mustChange && nav.getRootState() === before))
+      return {
+        ...route,
+        warning: `asked for ${want.label} but the app is on ${route.path.join(" > ")}; the screen may be in a navigator that is not mounted, or the navigation did not run`
+      };
+    return route;
+  };
+  const checkName = (name) => {
+    ready();
+    if (typeof name !== "string" || !name) throw new Error("give a route name, e.g. nav.navigate Profile");
+    const known = allRouteNames(nav.getRootState());
+    if (!known.has(name))
+      throw new Error(
+        `no route named "${name}". Known routes: ${[...known].join(", ")}. If it is inside a navigator that has not been opened yet, navigate to the parent with {screen: name}.`
+      );
+    return name;
+  };
+  const asPath = (target) => {
+    if (target.startsWith("/")) return target;
+    const prefix = options.linking?.prefixes?.find((p) => target.startsWith(p));
+    return prefix === void 0 ? void 0 : `/${target.slice(prefix.length).replace(/^\/+/, "")}`;
+  };
+  const fromPath = (path) => {
+    if (!parse)
+      throw new Error(
+        "paths need getStateFromPath: navTools(ref, { linking, getStateFromPath }) with getStateFromPath from @react-navigation/native. Or pass a route name."
+      );
+    if (options.linking?.config === void 0)
+      throw new Error(
+        'paths need linking.config (the screens map). With a static config or linking {enabled: "auto"} there is none to pass: use a route name.'
+      );
+    const state = parse(path, options.linking?.config);
+    if (!state || !state.routes.length)
+      throw new Error(`${path} matched no route. Check it against your linking config.`);
+    const [name, nested] = nestedNavigate(state);
+    return [checkName(name), nested];
+  };
+  const needStack = (verb) => {
+    ready();
+    const { holder } = focusedNavigators(nav.getRootState());
+    if (holder?.type && holder.type !== "stack")
+      throw new Error(
+        `the focused navigator is a ${holder.type} navigator, so ${verb} would act on a parent. Use nav.navigate.`
+      );
+  };
+  const action = (type, name, params) => ({
+    type,
+    payload: { name, params }
+  });
+  return {
+    "nav.navigate": {
+      description: "Go to a route by name and params ({screen, params} reaches a nested screen), or by a path like /post/7 (or a URL with one of linking.prefixes) when getStateFromPath and linking.config are set. In a stack it goes back to the screen if that is focused and otherwise pushes (React Navigation 7; v6 reuses a screen already in the stack): use nav.popTo to return to an earlier one. Returns the route it ended on (name, params, path, stack, canGoBack), with a `warning` if the screens asked for are not at the end of the path. Throws on an unknown name.",
+      run: (target, params) => {
+        const path = typeof target === "string" ? asPath(target) : void 0;
+        if (path !== void 0) {
+          const [name2, nested] = fromPath(path);
+          return goTo(() => nav.navigate(name2, nested), {
+            chain: wantedChain(name2, nested),
+            label: target
+          });
+        }
+        const name = checkName(target);
+        const chain = wantedChain(name, params);
+        return goTo(() => nav.navigate(name, params), { chain, label: chain.join(" > ") });
+      }
+    },
+    "nav.push": {
+      description: "Push a route onto the focused stack, even if it is already there. Throws when the focused navigator is tabs or a drawer (use nav.navigate). Same reply as nav.navigate.",
+      run: (target, params) => {
+        const name = checkName(target);
+        needStack("push");
+        return goTo(() => nav.dispatch(action("PUSH", name, params)), { chain: [name], label: name, mustChange: true });
+      }
+    },
+    "nav.replace": {
+      description: "Replace the current screen in its stack. Throws when the focused navigator is tabs or a drawer (use nav.navigate). Same reply as nav.navigate.",
+      run: (target, params) => {
+        const name = checkName(target);
+        needStack("replace");
+        return goTo(() => nav.dispatch(action("REPLACE", name, params)), { chain: [name], label: name, mustChange: true });
+      }
+    },
+    "nav.popTo": {
+      description: "Go back to the nearest earlier screen with this name in the focused stack, or replace the current screen with it if there is none (React Navigation 7 only). Same reply as nav.navigate.",
+      run: (target, params) => {
+        const name = checkName(target);
+        return goTo(() => nav.dispatch({ type: "POP_TO", payload: { name, params } }), { chain: [name], label: name });
+      }
+    },
+    "nav.popToTop": {
+      description: "Pop the nearest stack back to its first screen. If that stack is already at its first screen it does nothing, so a parent stack is never popped. Returns the route it ended on.",
+      run: async () => {
+        ready();
+        const { stack } = focusedNavigators(nav.getRootState());
+        if (stack && (stack.index ?? stack.routes.length - 1) === 0) return read(nav);
+        return goTo(() => nav.dispatch({ type: "POP_TO_TOP" }));
+      }
+    },
+    "nav.back": {
+      description: "Go back once if it can. Returns the route it ended on, or false if it could not. Ignores modals and sheets the app renders itself: close those with the app's own tool.",
+      run: () => {
+        ready();
+        return nav.canGoBack() ? goTo(() => nav.goBack()) : false;
+      }
+    },
+    "nav.current": {
+      description: "The current route: name, params, path (root navigator down to the screen), stack and canGoBack.",
+      run: () => read(nav)
+    }
+  };
+}

package/dist/adapters/react-navigation.d.cts

@@ -0,0 +1,55 @@
+import { T as Tools } from '../types-qlwdcGjt.cjs';
+
+/** The container ref from `createNavigationContainerRef()` or `useNavigationContainerRef()`. Passed in, so this adds no dependency. */
+type NavigationRefLike = {
+    getRootState(): unknown;
+    isReady(): boolean;
+    canGoBack(): boolean;
+    navigate(...args: never[]): void;
+    goBack(): void;
+    dispatch(action: never): void;
+    addListener?(type: 'state', callback: () => void): () => void;
+};
+type StateLike = {
+    type?: string;
+    index?: number;
+    routeNames?: string[];
+    routes: {
+        name: string;
+        params?: Record<string, unknown>;
+        state?: StateLike;
+    }[];
+};
+type GetStateFromPath = (path: string, config?: never) => StateLike | undefined;
+type NavToolsOptions = {
+    /** Your `linking` object; its `config` is how a path like `/post/7` is matched to a screen. */
+    linking?: {
+        config?: unknown;
+        prefixes?: string[];
+        getStateFromPath?: GetStateFromPath;
+    };
+    /** `getStateFromPath` from `@react-navigation/native`, to let the tools take paths. */
+    getStateFromPath?: GetStateFromPath;
+};
+/** Where the app is. */
+type CurrentRoute = {
+    /** The focused screen's name. */
+    name: string;
+    params?: Record<string, unknown>;
+    /** Names from the root navigator down to the focused screen, e.g. `['Main', 'Post']`. */
+    path: string[];
+    /** The screens in the focused navigator, bottom first. */
+    stack: {
+        name: string;
+        params?: Record<string, unknown>;
+    }[];
+    canGoBack: boolean;
+};
+/**
+ * Navigate without taps. Pass the container ref from `createNavigationContainerRef()`
+ * (or `useNavigationContainerRef()`). The tools are named `nav.*`, so they sit
+ * beside `routerTools` from the expo-router adapter without clashing.
+ */
+declare function navTools(nav: NavigationRefLike, options?: NavToolsOptions): Tools;
+
+export { type CurrentRoute, type NavToolsOptions, type NavigationRefLike, navTools };

package/dist/adapters/redux.cjs

@@ -0,0 +1,322 @@
+"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/adapters/redux.ts
+var redux_exports = {};
+__export(redux_exports, {
+  bridgeReducer: () => bridgeReducer,
+  reduxTools: () => reduxTools
+});
+module.exports = __toCommonJS(redux_exports);
+
+// src/runtime/to-json.ts
+function toJson(value) {
+  if (value === void 0) return null;
+  const seen = /* @__PURE__ */ new WeakSet();
+  const text = JSON.stringify(value, (_key, v) => {
+    if (typeof v === "bigint") return v.toString();
+    if (typeof v === "function" || typeof v === "symbol") return void 0;
+    if (v instanceof Error) return { name: v.name, message: v.message };
+    if (v instanceof Map) return Object.fromEntries(v);
+    if (v instanceof Set) return [...v];
+    if (v && typeof v === "object") {
+      if (seen.has(v)) return "[Circular]";
+      seen.add(v);
+    }
+    return v;
+  });
+  return text === void 0 ? null : JSON.parse(text);
+}
+
+// src/adapters/store-common.ts
+var isObject = (value) => typeof value === "object" && value !== null;
+function toPath(part) {
+  if (typeof part === "string") return part === "" ? [] : part.split(".");
+  if (typeof part === "number") return [part];
+  if (Array.isArray(part) && part.every((p) => typeof p === "string" || typeof p === "number"))
+    return part;
+  throw new Error(
+    `A path is a dotted string or an array of segments, got ${JSON.stringify(part)}`
+  );
+}
+function at(value, path) {
+  return path.reduce(
+    (v, k) => v?.[k],
+    value
+  );
+}
+var kindOf = (v) => v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+function readState(state, given, tool = "store.get") {
+  const args = given.filter((a) => a != null);
+  const last = args.at(-1);
+  const isOptions = isObject(last) && !Array.isArray(last);
+  const options = isOptions ? last : {};
+  const unknown = Object.keys(options).filter((k) => k !== "pick" && k !== "keys");
+  if (unknown.length)
+    throw new Error(
+      `Unknown ${tool} option ${unknown.map((k) => `"${k}"`).join(", ")}. Options: pick, keys`
+    );
+  const value = at(state, (isOptions ? args.slice(0, -1) : args).flatMap(toPath));
+  if (options.pick !== void 0) {
+    if (!Array.isArray(options.pick))
+      throw new Error(`${tool} pick is an array of paths`);
+    return Object.fromEntries(
+      options.pick.map((p) => [
+        Array.isArray(p) ? p.join(".") : String(p),
+        at(value, toPath(p))
+      ])
+    );
+  }
+  if (options.keys)
+    return isObject(value) ? Object.fromEntries(Object.entries(value).map(([k, v]) => [k, kindOf(v)])) : kindOf(value);
+  return value;
+}
+var PREVIEW = 200;
+function preview(value) {
+  try {
+    const safe = toJson(value);
+    const text = JSON.stringify(safe);
+    if (text.length <= PREVIEW) return safe;
+    return `${text.slice(0, PREVIEW)}\u2026 (${text.length} chars)`;
+  } catch {
+    return "[unserializable]";
+  }
+}
+function differences(snapshot, current, show, only) {
+  if (!isObject(snapshot) || !isObject(current)) return {};
+  const out = {};
+  for (const k of /* @__PURE__ */ new Set([...Object.keys(snapshot), ...Object.keys(current)])) {
+    if (only && !only.has(k)) continue;
+    const a = snapshot[k];
+    const b = current[k];
+    if (typeof a === "function" || typeof b === "function") continue;
+    if (!Object.is(a, b))
+      out[k] = { snapshot: preview(show(k, a)), current: preview(show(k, b)) };
+  }
+  return out;
+}
+var REDACTED = "[redacted]";
+function redactValue(redact, name, value, path, seen = []) {
+  if (!redact || typeof value === "function") return value;
+  if (typeof redact === "function") {
+    if (path) value = redact(name, path, value);
+  } else if (path && redact[name]?.some((p) => path === p || path.startsWith(`${p}.`))) {
+    return REDACTED;
+  }
+  if (!isObject(value) || seen.includes(value)) return value;
+  const next = [...seen, value];
+  const entries = Object.entries(value).map(([k, v]) => [
+    k,
+    redactValue(redact, name, v, path ? `${path}.${k}` : k, next)
+  ]);
+  return Array.isArray(value) ? entries.map(([, v]) => v) : Object.fromEntries(entries);
+}
+function redactNamed(redact, name, value) {
+  if (!redact) return value;
+  if (typeof redact === "function") {
+    return redactValue(redact, name, redact(name, "", value), "");
+  }
+  const rule = redact[name];
+  if (rule === true) return REDACTED;
+  return rule ? redactValue({ [name]: rule }, name, value, "") : value;
+}
+var warned = /* @__PURE__ */ new Set();
+function warnUnknownRedact(redact, known, adapter) {
+  if (!redact || typeof redact === "function") return;
+  for (const key of Object.keys(redact)) {
+    if (known.includes(key) || warned.has(`${adapter}:${key}`)) continue;
+    warned.add(`${adapter}:${key}`);
+    console.warn(`[agent-bridge] ${adapter} redact key "${key}" matches no ${adapter === "redux" ? "slice" : "atom"}, so it hides nothing. Known: ${known.join(", ")}`);
+  }
+}
+
+// src/adapters/redux.ts
+var REPLACE = "@@agent-bridge/replace";
+var stash;
+var handled = 0;
+function bridgeReducer(reducer) {
+  return ((state, action) => {
+    if (action.type !== REPLACE || !stash) return reducer(state, action);
+    handled += 1;
+    return stash.state;
+  });
+}
+var snapshots = /* @__PURE__ */ new WeakMap();
+var NOT_WRAPPED = "The bridge could not replace the state: wrap the root reducer with bridgeReducer() from @avasapp/agent-bridge/redux (inside redux-persist's persistReducer, and again after store.replaceReducer), so the bridge can set slices and restore.";
+var isRecord = (v) => isObject(v) && !Array.isArray(v);
+var PERSIST = "_persist";
+var withoutPersist = (v) => {
+  if (!isRecord(v) || !(PERSIST in v)) return v;
+  const { [PERSIST]: _, ...rest } = v;
+  return rest;
+};
+function reduxTools(store, options = {}) {
+  const state = () => store.getState();
+  const slices = () => isRecord(state()) ? Object.keys(state()).filter((k) => k !== PERSIST) : [];
+  warnUnknownRedact(options.redact, [...slices(), "state"], "redux");
+  const redacted = (value) => isRecord(value) ? Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactNamed(options.redact, k, v)])) : redactNamed(options.redact, "state", value);
+  const replaceWith = (next) => {
+    const before = handled;
+    stash = { state: next };
+    try {
+      store.dispatch({ type: REPLACE });
+    } finally {
+      stash = void 0;
+    }
+    if (handled === before) throw new Error(NOT_WRAPPED);
+  };
+  const snapshot = () => {
+    let snap = snapshots.get(store);
+    if (!snap) snapshots.set(store, snap = { slices: /* @__PURE__ */ new Map() });
+    return snap;
+  };
+  const empty = (snap) => {
+    if (!snap.slices.size && !snap.whole) snapshots.delete(store);
+  };
+  const slice = (name) => {
+    const s = state();
+    if (!isRecord(s) || !(name in s) || name === PERSIST)
+      throw new Error(`Unknown slice "${name}". Known: ${slices().join(", ")}`);
+    return s;
+  };
+  const changedSlices = (before, after) => {
+    if (!isRecord(before) || !isRecord(after)) return Object.is(before, after) ? [] : ["state"];
+    return [.../* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])].filter(
+      (k) => k !== PERSIST && !Object.is(before[k], after[k])
+    );
+  };
+  const diffOf = (k, before, now) => isRecord(before) && isRecord(now) ? differences(
+    before,
+    now,
+    (key, v) => redactNamed(options.redact, k, { [key]: v })[key]
+  ) : { "(value)": { snapshot: preview(redactNamed(options.redact, k, before)), current: preview(redactNamed(options.redact, k, now)) } };
+  return {
+    "redux.list": { description: "Slice names (the keys of the root state).", maxArgs: 0, run: () => slices() },
+    "redux.get": {
+      description: 'The whole state, or a path inside it, starting at a slice: (), ("auth"), ("auth.user.name"), ("auth", "user", "name") or ("auth", ["user", "name"]). A last { pick: ["a.b", "c"] } returns just those fields; { keys: true } lists keys and their types without values. Slices and paths configured with redact print as "[redacted]".',
+      run: (...rest) => readState(redacted(state()), rest, "redux.get")
+    },
+    "redux.dispatch": {
+      maxArgs: 1,
+      description: `Dispatch a plain action, e.g. { type: "cart/add", payload: "apple" }. Returns { changed: [slices] }. The first redux.dispatch since the last restore snapshots the WHOLE state, so bridge.restore puts all of it back, including what the app changed in other slices after that (redux.set is per slice: prefer it for a state you want to set). redux-persist's _persist is never put back. Thunks and functions cannot be sent.`,
+      run: (action) => {
+        if (!isObject(action) || typeof action.type !== "string")
+          throw new Error("redux.dispatch takes an action as { type, payload }");
+        if (action.type.startsWith("@@agent-bridge/"))
+          throw new Error(`Action types starting with "@@agent-bridge/" are reserved`);
+        const snap = snapshot();
+        const before = state();
+        const first = !snap.whole;
+        if (first) snap.whole = { state: withoutPersist(before) };
+        try {
+          store.dispatch(action);
+        } catch (e) {
+          if (first && Object.is(state(), before)) delete snap.whole;
+          empty(snap);
+          throw e;
+        }
+        const changed = changedSlices(before, state());
+        for (const k of changed) {
+          const entry = snap.slices.get(k);
+          if (entry) entry.after = state()[k];
+        }
+        empty(snap);
+        return { changed };
+      }
+    },
+    "redux.set": {
+      maxArgs: 2,
+      description: `Shallow-merge a partial into an object slice: ("auth", { token: "abc" }). Skips the app's reducers, so no other state moves. Array slices are refused. Returns only the keys you set, with their new values. Each slice is snapshotted on its first redux.set since the last restore (redux.commit drops them); bridge.restore puts that slice back, and leaves alone any slice the app changed after you (returned in {skipped}). Changes made before the first set, e.g. by tapping the UI, are not in the snapshot: run redux.set <slice> {} first to snapshot early, and see bridge.pending. Needs bridgeReducer() around the root reducer.`,
+      run: (name, partial) => {
+        const s = slice(name);
+        const current = s[name];
+        if (Array.isArray(current))
+          throw new Error(`Slice "${name}" is an array, so redux.set cannot merge into it. Use redux.dispatch with one of the app's actions`);
+        if (!isRecord(current)) throw new Error(`Slice "${name}" is not an object, so there is nothing to merge into`);
+        if (!isRecord(partial)) throw new Error("redux.set takes a slice name and an object (not an array)");
+        const snap = snapshot();
+        const track = !snap.whole && !snap.slices.has(name);
+        if (track) snap.slices.set(name, { original: current, after: current });
+        try {
+          replaceWith({ ...s, [name]: { ...current, ...partial } });
+        } catch (e) {
+          if (track) snap.slices.delete(name);
+          empty(snap);
+          throw e;
+        }
+        const now = state()[name];
+        const entry = snap.slices.get(name);
+        if (entry) entry.after = now;
+        return redactNamed(
+          options.redact,
+          name,
+          Object.fromEntries(Object.keys(partial).map((k) => [k, now[k]]))
+        );
+      }
+    },
+    "redux.commit": {
+      maxArgs: 0,
+      description: "Keep the state as it is now: drops the pending snapshots, so bridge.restore leaves it alone and the next redux.set or redux.dispatch snapshots again from here. Returns { committed } (false when nothing was pending).",
+      run: () => ({ committed: snapshots.delete(store) })
+    },
+    "redux.restore": {
+      maxArgs: 0,
+      pending: ({ detail } = {}) => {
+        const snap = snapshots.get(store);
+        if (!snap) return false;
+        if (!detail) return true;
+        const now = state();
+        const out = {};
+        if (snap.whole) {
+          const before = snap.whole.state;
+          for (const k of changedSlices(before, now))
+            out[k] = diffOf(k, isRecord(before) ? before[k] : before, isRecord(now) ? now[k] : now);
+        }
+        for (const [k, e] of snap.slices)
+          if (isRecord(now) && !Object.is(e.original, now[k])) out[k] = diffOf(k, e.original, now[k]);
+        return out;
+      },
+      description: 'Undo the agent: put back each slice changed with redux.set, and, if redux.dispatch was used, the whole state from before its first call (redux.commit drops the snapshots). Returns ["redux"], or [] when nothing was pending. A slice the app changed after the agent set it is left alone and returned as { restored, skipped }. With redux-persist (bridgeReducer inside persistReducer) the saved copy follows. Lost when the JS reloads: restore before app.reload.',
+      run: () => {
+        const snap = snapshots.get(store);
+        if (!snap) return [];
+        const cur = state();
+        let next = cur;
+        if (snap.whole) {
+          next = snap.whole.state;
+          if (isRecord(next) && isRecord(cur) && PERSIST in cur) next = { ...next, [PERSIST]: cur[PERSIST] };
+        }
+        const skipped = [];
+        let any = Boolean(snap.whole);
+        for (const [k, e] of snap.slices) {
+          if (!isRecord(cur) || !Object.is(cur[k], e.after)) {
+            skipped.push(k);
+            if (isRecord(next) && isRecord(cur) && k in cur) next = { ...next, [k]: cur[k] };
+            continue;
+          }
+          next = { ...next, [k]: e.original };
+          any = true;
+        }
+        if (any) replaceWith(next);
+        snapshots.delete(store);
+        return skipped.length ? { restored: any ? ["redux"] : [], skipped } : ["redux"];
+      }
+    }
+  };
+}