@demlik/tea 0.1.0

package/dist/throttle/index.js

@@ -0,0 +1,54 @@
+// src/throttle/index.ts
+function throttle(fn, ms, opts) {
+  const leading = opts?.leading ?? true;
+  const trailing = opts?.trailing ?? true;
+  let handle = null;
+  let pendingArgs = null;
+  function clearHandle() {
+    if (handle !== null) {
+      clearTimeout(handle);
+      handle = null;
+    }
+  }
+  function onWindowExpired() {
+    if (trailing && pendingArgs !== null) {
+      const args = pendingArgs;
+      pendingArgs = null;
+      handle = setTimeout(onWindowExpired, ms);
+      fn(...args);
+    } else {
+      handle = null;
+    }
+  }
+  const throttled = (...args) => {
+    if (handle === null) {
+      if (leading) {
+        fn(...args);
+      } else if (trailing) {
+        pendingArgs = args;
+      }
+      handle = setTimeout(onWindowExpired, ms);
+    } else if (trailing) {
+      pendingArgs = args;
+    }
+  };
+  throttled.cancel = () => {
+    clearHandle();
+    pendingArgs = null;
+  };
+  throttled.flush = () => {
+    if (pendingArgs !== null) {
+      const args = pendingArgs;
+      pendingArgs = null;
+      clearHandle();
+      fn(...args);
+    } else {
+      clearHandle();
+    }
+  };
+  return throttled;
+}
+
+export { throttle };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/throttle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/throttle/index.ts"],"names":[],"mappings":";AAyHO,SAAS,QAAA,CACd,EAAA,EACA,EAAA,EACA,IAAA,EACc;AACd,EAAA,MAAM,OAAA,GAAU,MAAM,OAAA,IAAW,IAAA;AACjC,EAAA,MAAM,QAAA,GAAW,MAAM,QAAA,IAAY,IAAA;AAMnC,EAAA,IAAI,MAAA,GAA+C,IAAA;AAOnD,EAAA,IAAI,WAAA,GAAwB,IAAA;AAE5B,EAAA,SAAS,WAAA,GAAoB;AAC3B,IAAA,IAAI,WAAW,IAAA,EAAM;AACnB,MAAA,YAAA,CAAa,MAAM,CAAA;AACnB,MAAA,MAAA,GAAS,IAAA;AAAA,IACX;AAAA,EACF;AAOA,EAAA,SAAS,eAAA,GAAwB;AAC/B,IAAA,IAAI,QAAA,IAAY,gBAAgB,IAAA,EAAM;AACpC,MAAA,MAAM,IAAA,GAAO,WAAA;AACb,MAAA,WAAA,GAAc,IAAA;AAId,MAAA,MAAA,GAAS,UAAA,CAAW,iBAAiB,EAAE,CAAA;AACvC,MAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,IACZ,CAAA,MAAO;AAEL,MAAA,MAAA,GAAS,IAAA;AAAA,IACX;AAAA,EACF;AAEA,EAAA,MAAM,SAAA,GAAY,IAAI,IAAA,KAAkB;AACtC,IAAA,IAAI,WAAW,IAAA,EAAM;AAEnB,MAAA,IAAI,OAAA,EAAS;AACX,QAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,MACZ,WAAW,QAAA,EAAU;AAInB,QAAA,WAAA,GAAc,IAAA;AAAA,MAChB;AACA,MAAA,MAAA,GAAS,UAAA,CAAW,iBAAiB,EAAE,CAAA;AAAA,IACzC,WAAW,QAAA,EAAU;AAGnB,MAAA,WAAA,GAAc,IAAA;AAAA,IAChB;AAAA,EAEF,CAAA;AAEA,EAAA,SAAA,CAAU,SAAS,MAAY;AAC7B,IAAA,WAAA,EAAY;AACZ,IAAA,WAAA,GAAc,IAAA;AAAA,EAChB,CAAA;AAEA,EAAA,SAAA,CAAU,QAAQ,MAAY;AAI5B,IAAA,IAAI,gBAAgB,IAAA,EAAM;AACxB,MAAA,MAAM,IAAA,GAAO,WAAA;AACb,MAAA,WAAA,GAAc,IAAA;AACd,MAAA,WAAA,EAAY;AACZ,MAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,IACZ,CAAA,MAAO;AAGL,MAAA,WAAA,EAAY;AAAA,IACd;AAAA,EACF,CAAA;AAEA,EAAA,OAAO,SAAA;AACT","file":"index.js","sourcesContent":["/**\n * @demlik/tea/throttle — a timer-based call transformer that caps invocation\n * to at most once per `ms` window.\n *\n * Sibling of `@demlik/tea/debounce` — the two share a SYMMETRIC surface\n * (`Throttled<A>` / `Debounced<A>`, both callable + `.cancel()` + `.flush()`,\n * both `{ leading?, trailing? }`) so they read as a pair. They are kept in\n * separate files with NO cross-import: each is a self-contained timer, and the\n * coalesce-vs-drop policies differ enough that sharing code would hide the\n * distinction. The contrast IS the lesson:\n *\n *   - **debounce** waits for quiet — fires once AFTER a burst settles.\n *   - **throttle** enforces a rate — fires AT MOST once per `ms` while the\n *     burst is ongoing, dropping the calls in between.\n *\n * WHAT THIS IS NOT — and why it lives outside `update`:\n *\n *   - NOT a reducer / Transitions cell. Reducers are PURE (invariant 2 — same\n *     inputs → same outputs, no `Date.now`, no timers). A throttle holds a live\n *     `setTimeout` handle and a window cursor; folding it into `update` would\n *     smuggle a timer into the pure core.\n *   - NOT a Sub. A Sub is a continuous SOURCE of Msgs the substrate reconciles\n *     by id every transition (invariant 4). A throttle is a SINK transformer:\n *     it wraps a `void`-returning handler (the canonical one is\n *     `Runtime.dispatch`) so a high-frequency HOST event is rate-limited BEFORE\n *     it ever becomes a Msg.\n *\n * It is a higher-order function at the host boundary (pattern 14 — TEA owns\n * state, JS owns timing). The host attaches the wrapped function to a\n * high-frequency event source (`mousemove`, `scroll`, `pointermove`, a game\n * loop) and the substrate downstream only ever sees the rate-limited Msg:\n *\n *   const onMoved = throttle(\n *     (e: PointerEvent) =>\n *       runtime.dispatch({ type: \"UserMovedCursor\", x: e.clientX, y: e.clientY }),\n *     16, // ~60fps cap\n *   );\n *   window.addEventListener(\"pointermove\", onMoved);\n *   // cleanup: onMoved.cancel(); window.removeEventListener(\"pointermove\", onMoved);\n *\n * NOT exported from the package root — reached via the `@demlik/tea/throttle`\n * subpath, same one-shape-per-package rule as `rate-limit`, `deadline`, and\n * `work-queue`.\n *\n * Uses the universal `setTimeout` / `clearTimeout` timer idiom (same discipline\n * as `subs/from-timeout.ts`): exactly one live handle at a time, the window\n * timer clears itself on expiry, `cancel` / `flush` clear and null it so a\n * stale callback can never run.\n */\n\n/**\n * A throttled wrapper around `fn`. Callable with the SAME argument tuple as\n * `fn` — `(...args: A) => void` — plus two control methods that share names and\n * shapes with `Debounced<A>` so the two modules read as a symmetric pair.\n */\nexport interface Throttled<A extends readonly unknown[]> {\n  /** Invoke `fn` if the window is open, else record args for the trailing fire. */\n  (...args: A): void;\n  /**\n   * Drop any pending trailing fire WITHOUT invoking `fn`, and close the active\n   * window. Clears the timer, forgets the captured trailing args, and resets\n   * the cursor so the next call fires immediately on the leading edge (if\n   * `leading` is enabled). Idempotent.\n   *\n   * The host-cleanup partner of `removeEventListener`: cancel the pending fire\n   * when the component unmounts / the listener detaches, so a queued\n   * `dispatch` can't land after teardown.\n   */\n  cancel(): void;\n  /**\n   * Fire any pending trailing call IMMEDIATELY with its latest captured args,\n   * then close the window. No-op when nothing is pending. Use to force the last\n   * dropped call out early — e.g. flush the final cursor position when a drag\n   * ends, so the rest state isn't a stale mid-drag sample.\n   */\n  flush(): void;\n}\n\n/**\n * Wrap `fn` so it runs AT MOST once per `ms` window, no matter how often it is\n * called.\n *\n * Leading + trailing (the default): the first call fires `fn` IMMEDIATELY (the\n * leading edge) and opens a `ms` window. Calls during the window are dropped\n * from immediate firing but their args are remembered; when the window closes,\n * `fn` fires ONCE more with the LATEST dropped args (the trailing edge) and a\n * new window opens. A call after the window has already closed leads a fresh\n * window immediately. Spacing every call at least `ms` apart therefore fires\n * each one on its own leading edge.\n *\n * @param fn   The handler to rate-limit. Typically `(...) => runtime.dispatch(...)`,\n *             but any `(...args: A) => void` works. The return value is\n *             ignored — throttle is a fire transformer, not a value pipe.\n * @param ms   Window length in milliseconds. `fn` fires at most once per `ms`.\n * @param opts.leading   Fire on the FIRST call of a window (the leading edge),\n *             immediately. Default `true`.\n * @param opts.trailing  Fire once at window END with the latest args dropped\n *             during the window. Default `true`.\n *\n * Edge combinations (matching lodash's settled semantics, the de-facto\n * standard the ecosystem rediscovered):\n *\n *   - `{ leading: true, trailing: true }` (default): immediate fire + a\n *     trailing fire per window while calls keep arriving. The trailing fire is\n *     SUPPRESSED when no extra call arrived during the window (a lone call\n *     already fired on the leading edge — no stale trailing double-fire).\n *   - `{ leading: true, trailing: false }`: only the immediate fire; everything\n *     in the window is dropped with no catch-up at the end.\n *   - `{ leading: false, trailing: true }`: no immediate fire; the FIRST call\n *     opens a window and `fn` fires at the window's end with the latest args.\n *     Steady \"sample every `ms`\" behavior with no instant response.\n *   - `{ leading: false, trailing: false }`: never fires. Degenerate but legal;\n *     we don't throw — the caller asked for a no-op transformer.\n *\n * WHY a default of leading + trailing both `true`: a throttle's job is \"respond\n * now, then keep responding at a steady rate.\" Leading gives the instant\n * response (the first `mousemove` updates immediately); trailing guarantees the\n * FINAL sample of a window isn't lost (the cursor ends where the user actually\n * left it, not one window-width behind). Dropping either loses one of those two\n * guarantees, so both default on.\n */\nexport function throttle<A extends readonly unknown[]>(\n  fn: (...args: A) => void,\n  ms: number,\n  opts?: { leading?: boolean; trailing?: boolean },\n): Throttled<A> {\n  const leading = opts?.leading ?? true;\n  const trailing = opts?.trailing ?? true;\n\n  // Exactly one live handle at a time (the from-timeout discipline). `null`\n  // when no window is open — the single source of truth for \"is a window\n  // active?\". The window timer arms on a fire and clears itself on expiry; the\n  // call path never stacks overlapping timers.\n  let handle: ReturnType<typeof setTimeout> | null = null;\n  // The latest args seen DURING an open window, held for the trailing fire.\n  // Overwritten by every dropped call (the trailing edge fires with the LAST\n  // args), cleared the instant we fire / cancel. `null` (not `undefined`) is\n  // the empty sentinel because `A` may itself contain `undefined` elements — a\n  // present-but-empty tuple is still a pending call, distinct from \"nothing\n  // pending\".\n  let pendingArgs: A | null = null;\n\n  function clearHandle(): void {\n    if (handle !== null) {\n      clearTimeout(handle);\n      handle = null;\n    }\n  }\n\n  // Window expiry: the `ms` window just closed. If a call arrived during the\n  // window (`pendingArgs !== null`) and trailing is enabled, fire it now and\n  // open a FRESH window so the rate cap continues across a sustained burst.\n  // If nothing was dropped, let the window close (handle → null) so the next\n  // call leads a new window immediately.\n  function onWindowExpired(): void {\n    if (trailing && pendingArgs !== null) {\n      const args = pendingArgs;\n      pendingArgs = null;\n      // Re-arm BEFORE firing so a re-entrant call from inside `fn` sees an open\n      // window (and is correctly dropped/queued) rather than leading a second\n      // window — keeps the \"at most once per `ms`\" invariant under re-entry.\n      handle = setTimeout(onWindowExpired, ms);\n      fn(...args);\n    } else {\n      // No trailing fire owed — close the window.\n      handle = null;\n    }\n  }\n\n  const throttled = (...args: A): void => {\n    if (handle === null) {\n      // Window is closed → this call leads a new window.\n      if (leading) {\n        fn(...args);\n      } else if (trailing) {\n        // No leading fire, but trailing wants the first call's args so the\n        // window's end has something to fire. Without this, a leading:false\n        // throttle would swallow a lone call entirely.\n        pendingArgs = args;\n      }\n      handle = setTimeout(onWindowExpired, ms);\n    } else if (trailing) {\n      // Window is open → drop this call from immediate firing, but remember its\n      // args as the latest candidate for the trailing edge.\n      pendingArgs = args;\n    }\n    // Window open + trailing disabled → pure drop, nothing to remember.\n  };\n\n  throttled.cancel = (): void => {\n    clearHandle();\n    pendingArgs = null;\n  };\n\n  throttled.flush = (): void => {\n    // Force the pending trailing fire out now and close the window. Mirrors\n    // `onWindowExpired`'s fire branch but is caller-driven, so it tears the\n    // timer down rather than re-arming.\n    if (pendingArgs !== null) {\n      const args = pendingArgs;\n      pendingArgs = null;\n      clearHandle();\n      fn(...args);\n    } else {\n      // Nothing pending — still close a lingering window so a post-flush call\n      // leads cleanly.\n      clearHandle();\n    }\n  };\n\n  return throttled;\n}\n"]}

package/dist/trace-replay/index.d.ts

@@ -0,0 +1,52 @@
+import { Cmd, Sub, Machine } from '../index.js';
+import { Trace } from '../recorder/index.js';
+
+/**
+ * The outcome of {@link replayTrace}.
+ *
+ * @typeParam S - the machine's State type.
+ */
+interface ReplayResult<S> {
+    /** `true` iff the recomputed final state deep-equals the trace's `finalState`. */
+    matches: boolean;
+    /** The trace's recorded `finalState` — what the run originally produced. */
+    expected: S;
+    /** The state the current reducer produced for the same input. */
+    actual: S;
+    /**
+     * Present iff `matches` is `false`. The FIRST point of divergence found by
+     * a deterministic pre-order walk:
+     *   - `path`     — a dotted/indexed access path from the state root, e.g.
+     *                  `state.queue[2].status` or `state` for a root-level
+     *                  scalar mismatch.
+     *   - `expected` — the recorded value at that path.
+     *   - `actual`   — the recomputed value at that path.
+     */
+    divergence?: {
+        path: string;
+        expected: unknown;
+        actual: unknown;
+    };
+}
+/**
+ * Replay a recorded {@link Trace} against `machine` and diff the recomputed
+ * final state against the recorded one.
+ *
+ * Runs the core pure fold `replay(machine, { msgs: trace.msgs, ctx,
+ * loaded: trace.loaded })` — init + update only, never `interpret`, never a
+ * `Store`, never a live subscription (see `replay` in ../index). The `ctx` is
+ * supplied fresh by the caller: the trace is the INPUT (loaded + msgs); ctx is
+ * the ENVIRONMENT the reducer runs against now.
+ *
+ * @param machine - the machine to replay against. Mutating its reducer (the
+ *                  whole point of a regression check) is what makes a recorded
+ *                  trace diverge.
+ * @param trace   - a Trace from `../recorder` (live `dump()` or a re-hydrated
+ *                  `parseJSONL(...)`).
+ * @param ctx     - the runtime ctx, supplied fresh at replay time.
+ */
+declare function replayTrace<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, trace: Trace<S, M>, ctx: Ctx): ReplayResult<S>;
+
+export { type ReplayResult, replayTrace };

package/dist/trace-replay/index.js

@@ -0,0 +1,57 @@
+import { replay } from '../chunk-CMG2KMWX.js';
+
+// src/trace-replay/index.ts
+function replayTrace(machine, trace, ctx) {
+  const result = replay(machine, {
+    msgs: trace.msgs,
+    ctx,
+    loaded: trace.loaded
+  });
+  const actual = result.state;
+  const expected = trace.finalState;
+  const divergence = firstDivergence(expected, actual, "state");
+  if (divergence === null) {
+    return { matches: true, expected, actual };
+  }
+  return { matches: false, expected, actual, divergence };
+}
+function firstDivergence(expected, actual, path) {
+  if (Object.is(expected, actual)) return null;
+  const te = typeOf(expected);
+  const ta = typeOf(actual);
+  if (te !== ta) return { path, expected, actual };
+  if (te === "array") {
+    const ae = expected;
+    const aa = actual;
+    if (ae.length !== aa.length) {
+      return { path, expected, actual };
+    }
+    for (let i = 0; i < ae.length; i++) {
+      const d = firstDivergence(ae[i], aa[i], `${path}[${i}]`);
+      if (d !== null) return d;
+    }
+    return null;
+  }
+  if (te === "object") {
+    const oe = expected;
+    const oa = actual;
+    const keys = [.../* @__PURE__ */ new Set([...Object.keys(oe), ...Object.keys(oa)])].sort();
+    for (const key of keys) {
+      const d = firstDivergence(oe[key], oa[key], `${path}.${key}`);
+      if (d !== null) return d;
+    }
+    return null;
+  }
+  return { path, expected, actual };
+}
+function typeOf(v) {
+  if (v === null) return "null";
+  if (v === void 0) return "undefined";
+  if (Array.isArray(v)) return "array";
+  if (typeof v === "object") return "object";
+  return "primitive";
+}
+
+export { replayTrace };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/trace-replay/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/trace-replay/index.ts"],"names":[],"mappings":";;;AAoEO,SAAS,WAAA,CAOd,OAAA,EACA,KAAA,EACA,GAAA,EACiB;AACjB,EAAA,MAAM,MAAA,GAAS,OAAO,OAAA,EAAS;AAAA,IAC7B,MAAM,KAAA,CAAM,IAAA;AAAA,IACZ,GAAA;AAAA,IACA,QAAQ,KAAA,CAAM;AAAA,GACf,CAAA;AACD,EAAA,MAAM,SAAS,MAAA,CAAO,KAAA;AACtB,EAAA,MAAM,WAAW,KAAA,CAAM,UAAA;AAEvB,EAAA,MAAM,UAAA,GAAa,eAAA,CAAgB,QAAA,EAAU,MAAA,EAAQ,OAAO,CAAA;AAC5D,EAAA,IAAI,eAAe,IAAA,EAAM;AACvB,IAAA,OAAO,EAAE,OAAA,EAAS,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAAA,EAC3C;AACA,EAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,QAAA,EAAU,QAAQ,UAAA,EAAW;AACxD;AAsBA,SAAS,eAAA,CACP,QAAA,EACA,MAAA,EACA,IAAA,EACY;AAIZ,EAAA,IAAI,MAAA,CAAO,EAAA,CAAG,QAAA,EAAU,MAAM,GAAG,OAAO,IAAA;AAExC,EAAA,MAAM,EAAA,GAAK,OAAO,QAAQ,CAAA;AAC1B,EAAA,MAAM,EAAA,GAAK,OAAO,MAAM,CAAA;AAGxB,EAAA,IAAI,OAAO,EAAA,EAAI,OAAO,EAAE,IAAA,EAAM,UAAU,MAAA,EAAO;AAE/C,EAAA,IAAI,OAAO,OAAA,EAAS;AAClB,IAAA,MAAM,EAAA,GAAK,QAAA;AACX,IAAA,MAAM,EAAA,GAAK,MAAA;AACX,IAAA,IAAI,EAAA,CAAG,MAAA,KAAW,EAAA,CAAG,MAAA,EAAQ;AAG3B,MAAA,OAAO,EAAE,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAAA,IAClC;AACA,IAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,EAAA,CAAG,QAAQ,CAAA,EAAA,EAAK;AAClC,MAAA,MAAM,CAAA,GAAI,eAAA,CAAgB,EAAA,CAAG,CAAC,CAAA,EAAG,EAAA,CAAG,CAAC,CAAA,EAAG,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,CAAC,CAAA,CAAA,CAAG,CAAA;AACvD,MAAA,IAAI,CAAA,KAAM,MAAM,OAAO,CAAA;AAAA,IACzB;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,IAAI,OAAO,QAAA,EAAU;AACnB,IAAA,MAAM,EAAA,GAAK,QAAA;AACX,IAAA,MAAM,EAAA,GAAK,MAAA;AAIX,IAAA,MAAM,OAAO,CAAC,uBAAO,GAAA,CAAI,CAAC,GAAG,MAAA,CAAO,IAAA,CAAK,EAAE,CAAA,EAAG,GAAG,OAAO,IAAA,CAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAA,EAAK;AACzE,IAAA,KAAA,MAAW,OAAO,IAAA,EAAM;AACtB,MAAA,MAAM,CAAA,GAAI,eAAA,CAAgB,EAAA,CAAG,GAAG,CAAA,EAAG,EAAA,CAAG,GAAG,CAAA,EAAG,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,GAAG,CAAA,CAAE,CAAA;AAC5D,MAAA,IAAI,CAAA,KAAM,MAAM,OAAO,CAAA;AAAA,IACzB;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAIA,EAAA,OAAO,EAAE,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAClC;AAGA,SAAS,OACP,CAAA,EACyD;AACzD,EAAA,IAAI,CAAA,KAAM,MAAM,OAAO,MAAA;AACvB,EAAA,IAAI,CAAA,KAAM,QAAW,OAAO,WAAA;AAC5B,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,CAAC,CAAA,EAAG,OAAO,OAAA;AAC7B,EAAA,IAAI,OAAO,CAAA,KAAM,QAAA,EAAU,OAAO,QAAA;AAClC,EAAA,OAAO,WAAA;AACT","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// trace-replay — replay a recorded Trace against a machine and diff the state.\n//\n// This is the back half of the record/replay feature. `../recorder` captures\n// a run (`loaded` + `msgs` + `finalState`); this module feeds that input\n// through the core `replay(machine, { msgs, ctx, loaded })` fold and asks:\n//\n//     does the current reducer still produce the SAME final state for this\n//     recorded input?\n//\n// Equal ⇒ the reducer is behavior-compatible with the recording. Diverged ⇒\n// the reducer changed for that input, and the divergence path\n// (`state.queue[2].status`) points at exactly the cell that drifted. This is\n// the regression / production-repro tool: record a prod incident, replay it\n// against the fixed reducer locally, confirm the fix changes the state at the\n// path you expected — or catch an unintended drift before it ships.\n//\n// Standalone by design. It imports ONLY the `Trace` type from `../recorder`\n// and the `replay` engine from `../index`. The deep-equal + first-divergence\n// path finder is self-contained (no external diff lib) — a richer pretty-diff\n// lands in `../devtools` later; trace-replay stays dependency-free so it can\n// run anywhere a machine runs (CI, a Worker, a Node script).\n// ---------------------------------------------------------------------------\n\nimport { type Cmd, type Machine, replay, type Sub } from \"../index\";\nimport type { Trace } from \"../recorder\";\n\n/**\n * The outcome of {@link replayTrace}.\n *\n * @typeParam S - the machine's State type.\n */\nexport interface ReplayResult<S> {\n  /** `true` iff the recomputed final state deep-equals the trace's `finalState`. */\n  matches: boolean;\n  /** The trace's recorded `finalState` — what the run originally produced. */\n  expected: S;\n  /** The state the current reducer produced for the same input. */\n  actual: S;\n  /**\n   * Present iff `matches` is `false`. The FIRST point of divergence found by\n   * a deterministic pre-order walk:\n   *   - `path`     — a dotted/indexed access path from the state root, e.g.\n   *                  `state.queue[2].status` or `state` for a root-level\n   *                  scalar mismatch.\n   *   - `expected` — the recorded value at that path.\n   *   - `actual`   — the recomputed value at that path.\n   */\n  divergence?: { path: string; expected: unknown; actual: unknown };\n}\n\n/**\n * Replay a recorded {@link Trace} against `machine` and diff the recomputed\n * final state against the recorded one.\n *\n * Runs the core pure fold `replay(machine, { msgs: trace.msgs, ctx,\n * loaded: trace.loaded })` — init + update only, never `interpret`, never a\n * `Store`, never a live subscription (see `replay` in ../index). The `ctx` is\n * supplied fresh by the caller: the trace is the INPUT (loaded + msgs); ctx is\n * the ENVIRONMENT the reducer runs against now.\n *\n * @param machine - the machine to replay against. Mutating its reducer (the\n *                  whole point of a regression check) is what makes a recorded\n *                  trace diverge.\n * @param trace   - a Trace from `../recorder` (live `dump()` or a re-hydrated\n *                  `parseJSONL(...)`).\n * @param ctx     - the runtime ctx, supplied fresh at replay time.\n */\nexport function replayTrace<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  trace: Trace<S, M>,\n  ctx: Ctx,\n): ReplayResult<S> {\n  const result = replay(machine, {\n    msgs: trace.msgs,\n    ctx,\n    loaded: trace.loaded,\n  });\n  const actual = result.state;\n  const expected = trace.finalState;\n\n  const divergence = firstDivergence(expected, actual, \"state\");\n  if (divergence === null) {\n    return { matches: true, expected, actual };\n  }\n  return { matches: false, expected, actual, divergence };\n}\n\n// === self-contained deep-equal + first-divergence path finder ===\n//\n// One walk does both jobs: it returns the FIRST point where `expected` and\n// `actual` differ (as a path + the two values), or `null` when they are\n// deeply equal. \"First\" is defined by a deterministic pre-order traversal:\n// the node itself, then its children in a stable key order (array index\n// order; object keys sorted so the result does not depend on insertion\n// order — two states with the same data but different key order are equal,\n// and the reported path for a real mismatch is reproducible run-to-run).\n//\n// Scope: TEA state is plain JSON-shaped data (the substrate's __DEV__ guards\n// reject closures in Cmds, and states are conventionally serializable). So\n// the walk handles: primitives, null/undefined, arrays, and plain objects.\n// It treats other object kinds (Date, Map, Set, class instances) by reference\n// identity + a structural fallback via Object.entries — sufficient for the\n// JSON-shaped states this tool targets; a richer differ lives in ../devtools.\n\n/** A divergence record, or `null` when the two values are deeply equal. */\ntype Divergence = { path: string; expected: unknown; actual: unknown } | null;\n\nfunction firstDivergence(\n  expected: unknown,\n  actual: unknown,\n  path: string,\n): Divergence {\n  // Identity / primitive fast path. Handles same-reference, and equal\n  // primitives. `Object.is` so NaN === NaN and +0 ≠ -0 (matches structural\n  // equality intent better than ===).\n  if (Object.is(expected, actual)) return null;\n\n  const te = typeOf(expected);\n  const ta = typeOf(actual);\n  // Different kinds at this node (e.g. object vs array, number vs string,\n  // present vs null) — this node IS the divergence.\n  if (te !== ta) return { path, expected, actual };\n\n  if (te === \"array\") {\n    const ae = expected as unknown[];\n    const aa = actual as unknown[];\n    if (ae.length !== aa.length) {\n      // Length mismatch reported at the array node itself — the shape differs,\n      // which is more informative than an arbitrary element index.\n      return { path, expected, actual };\n    }\n    for (let i = 0; i < ae.length; i++) {\n      const d = firstDivergence(ae[i], aa[i], `${path}[${i}]`);\n      if (d !== null) return d;\n    }\n    return null;\n  }\n\n  if (te === \"object\") {\n    const oe = expected as Record<string, unknown>;\n    const oa = actual as Record<string, unknown>;\n    // Union of keys, sorted for deterministic traversal. A key present in one\n    // but absent in the other diverges at that child path (its value is\n    // `undefined` on the missing side).\n    const keys = [...new Set([...Object.keys(oe), ...Object.keys(oa)])].sort();\n    for (const key of keys) {\n      const d = firstDivergence(oe[key], oa[key], `${path}.${key}`);\n      if (d !== null) return d;\n    }\n    return null;\n  }\n\n  // Primitives (string/number/boolean/bigint/symbol/function) that failed the\n  // Object.is fast path, or null/undefined that differ — this node diverges.\n  return { path, expected, actual };\n}\n\n/** Coarse type tag used by the divergence walk to decide how to recurse. */\nfunction typeOf(\n  v: unknown,\n): \"null\" | \"undefined\" | \"array\" | \"object\" | \"primitive\" {\n  if (v === null) return \"null\";\n  if (v === undefined) return \"undefined\";\n  if (Array.isArray(v)) return \"array\";\n  if (typeof v === \"object\") return \"object\";\n  return \"primitive\";\n}\n"]}

package/dist/types-CwBC5wMn.d.ts

@@ -0,0 +1,5 @@
+import { Sub } from './index.js';
+
+type SubscribeHandler<S extends Sub, M, Ctx> = (sub: S, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
+
+export type { SubscribeHandler as S };

package/dist/work-queue/index.d.ts

@@ -0,0 +1,56 @@
+import { Store } from '../index.js';
+
+/**
+ * @demlik/tea/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.
+ *
+ * The pure ops live in `./ops` and are NOT exported. Tests and consumers reach
+ * them only through `createQueue(store)`. This mirrors `@demlik/tea/do`'s
+ * one-shape-per-package rule: a single adapter is the public surface.
+ *
+ * The package is generic in the input payload `I` (audit-specific fields go
+ * here in apps/extension). `output` is a free-form side-channel correlation
+ * token (a backend id, URL, trace id) — typed as `string` because that's its
+ * only honest type. Consumers that need structured per-item data persist it in
+ * their own store and put the foreign-key string in `output`.
+ */
+
+type QueueItemStatus = "pending" | "running" | "done" | "failed" | "cancelled";
+interface QueueItem<I> {
+    id: string;
+    status: QueueItemStatus;
+    input: I;
+    enqueuedAt: number;
+    startedAt?: number;
+    finishedAt?: number;
+    output?: string;
+    error?: string;
+}
+/**
+ * Caller-facing enqueue payload. Just `I` today — kept named so future
+ * variants (priority, deferUntil, …) can grow without breaking callers.
+ */
+type EnqueueInput<I> = I;
+/**
+ * Adapter that binds the pure ops to an injected `Store<QueueItem<I>[]>`.
+ *
+ * `load → mutate → save` is the only durability discipline this package
+ * imposes. The store decides what "save" means (chrome.storage, KV, DO
+ * storage, in-memory) — that decision belongs at the caller.
+ *
+ * Ops that don't change the queue (e.g. `markDone` on an unknown id) skip the
+ * save call so the underlying store doesn't observe a write churn.
+ */
+declare function createQueue<I>(store: Store<QueueItem<I>[]>): {
+    enqueue: (input: EnqueueInput<I>) => Promise<QueueItem<I>>;
+    claimNext: () => Promise<QueueItem<I> | null>;
+    markDone: (id: string) => Promise<void>;
+    markFailed: (id: string, error: string) => Promise<void>;
+    markCancelled: (id: string) => Promise<void>;
+    resetRunningToPending: () => Promise<void>;
+    removeItem: (id: string) => Promise<void>;
+    retryItem: (id: string) => Promise<void>;
+    bindOutput: (id: string, value: string) => Promise<void>;
+    list: () => Promise<QueueItem<I>[]>;
+};
+
+export { type EnqueueInput, type QueueItem, type QueueItemStatus, createQueue };

package/dist/work-queue/index.js

@@ -0,0 +1,143 @@
+// src/work-queue/ops.ts
+function enqueueOp(queue, input, now, id) {
+  const item = {
+    id,
+    status: "pending",
+    input,
+    enqueuedAt: now
+  };
+  return { next: [...queue, item], item };
+}
+function claimNextOp(queue, now) {
+  const idx = queue.findIndex((i) => i.status === "pending");
+  if (idx === -1) return null;
+  const claimed = {
+    ...queue[idx],
+    status: "running",
+    startedAt: now
+  };
+  const next = queue.slice();
+  next[idx] = claimed;
+  return { next, claimed };
+}
+function markDoneOp(queue, id) {
+  const next = queue.filter((i) => i.id !== id);
+  return { next, changed: next.length !== queue.length };
+}
+function patchItemOp(queue, id, patch) {
+  const idx = queue.findIndex((i) => i.id === id);
+  if (idx === -1) return { next: queue.slice(), changed: false };
+  const next = queue.slice();
+  next[idx] = patch(queue[idx]);
+  return { next, changed: true };
+}
+function resetRunningOp(queue) {
+  let changed = false;
+  const next = queue.map((i) => {
+    if (i.status !== "running") return i;
+    changed = true;
+    return { ...i, status: "pending", startedAt: void 0 };
+  });
+  return { next, changed };
+}
+function removeOp(queue, id) {
+  const next = queue.filter((i) => i.id !== id);
+  return { next, changed: next.length !== queue.length };
+}
+
+// src/work-queue/index.ts
+function genId() {
+  return globalThis.crypto?.randomUUID?.() ?? `q_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+function createQueue(store) {
+  async function loadParsed() {
+    const raw = await store.load();
+    return store.migrate(raw);
+  }
+  async function list() {
+    return await loadParsed() ?? [];
+  }
+  async function enqueue(input) {
+    const queue = await list();
+    const { next, item } = enqueueOp(queue, input, Date.now(), genId());
+    await store.save(next);
+    return item;
+  }
+  async function claimNext() {
+    const queue = await list();
+    const result = claimNextOp(queue, Date.now());
+    if (!result) return null;
+    await store.save(result.next);
+    return result.claimed;
+  }
+  async function markDone(id) {
+    const queue = await list();
+    const { next, changed } = markDoneOp(queue, id);
+    if (changed) await store.save(next);
+  }
+  async function markFailed(id, error) {
+    const queue = await list();
+    const { next, changed } = patchItemOp(queue, id, (item) => ({
+      ...item,
+      status: "failed",
+      finishedAt: Date.now(),
+      error
+    }));
+    if (changed) await store.save(next);
+  }
+  async function markCancelled(id) {
+    const queue = await list();
+    const { next, changed } = patchItemOp(queue, id, (item) => ({
+      ...item,
+      status: "cancelled",
+      finishedAt: Date.now()
+    }));
+    if (changed) await store.save(next);
+  }
+  async function resetRunningToPending() {
+    const queue = await list();
+    const { next, changed } = resetRunningOp(queue);
+    if (changed) await store.save(next);
+  }
+  async function removeItem(id) {
+    const queue = await list();
+    const { next, changed } = removeOp(queue, id);
+    if (changed) await store.save(next);
+  }
+  async function retryItem(id) {
+    const queue = await list();
+    const { next, changed } = patchItemOp(queue, id, (item) => ({
+      ...item,
+      status: "pending",
+      startedAt: void 0,
+      finishedAt: void 0,
+      error: void 0,
+      output: void 0
+    }));
+    if (changed) await store.save(next);
+  }
+  async function bindOutput(id, value) {
+    const queue = await list();
+    const { next, changed } = patchItemOp(queue, id, (item) => ({
+      ...item,
+      output: value
+    }));
+    if (changed) await store.save(next);
+  }
+  return {
+    enqueue,
+    claimNext,
+    markDone,
+    markFailed,
+    markCancelled,
+    resetRunningToPending,
+    removeItem,
+    retryItem,
+    bindOutput,
+    list
+  };
+}
+
+export { createQueue };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/work-queue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/work-queue/ops.ts","../../src/work-queue/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Pure queue-lifecycle ops over `QueueItem<I>[]`.\n *\n * Each op is `(queue, ...args) => { next, result? }`. No I/O, no Date.now\n * indirection beyond a plain call site — the adapter in `./index.ts` injects\n * `Store<QueueItem<I>[]>` and orchestrates `load → mutate → save`.\n *\n * Substrate-agnostic by construction: nothing here references chrome.storage,\n * Cloudflare, or any concrete persistence layer. The audit-specific shape\n * (journeyId, projectId, ...) is lifted into the caller's `I` parameter.\n *\n * NOT exported from package root. Tests reach this file only through the\n * `createQueue(memoryStore(...))` adapter — same one-shape-per-package rule as\n * `@demlik/tea/do`.\n */\n\nimport type { QueueItem, QueueItemStatus } from \"./index\";\n\n/** Append a new pending item. Returns the new queue and the created item. */\nexport function enqueueOp<I>(\n  queue: readonly QueueItem<I>[],\n  input: I,\n  now: number,\n  id: string,\n): { next: QueueItem<I>[]; item: QueueItem<I> } {\n  const item: QueueItem<I> = {\n    id,\n    status: \"pending\",\n    input,\n    enqueuedAt: now,\n  };\n  return { next: [...queue, item], item };\n}\n\n/**\n * Claim the first pending item by flipping it to `running` and stamping\n * `startedAt`. Returns the new queue and the claimed item, or `null` if no\n * pending item exists.\n */\nexport function claimNextOp<I>(\n  queue: readonly QueueItem<I>[],\n  now: number,\n): { next: QueueItem<I>[]; claimed: QueueItem<I> } | null {\n  const idx = queue.findIndex((i) => i.status === \"pending\");\n  if (idx === -1) return null;\n  // `idx !== -1` guarantees the slot is present.\n  const claimed: QueueItem<I> = {\n    ...queue[idx]!,\n    status: \"running\",\n    startedAt: now,\n  };\n  const next = queue.slice();\n  next[idx] = claimed;\n  return { next, claimed };\n}\n\n/**\n * Done items leave the queue — completed runs live wherever the caller\n * persists their output. Returns the new queue (or the original reference if\n * no item matched, so the adapter can skip a save).\n */\nexport function markDoneOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const next = queue.filter((i) => i.id !== id);\n  return { next, changed: next.length !== queue.length };\n}\n\n/**\n * Generic single-item status transition. Used by `markFailed`,\n * `markCancelled`, `retryItem`, `bindOutput`. The patch closure receives the\n * matched item and returns its replacement; returning the same reference is\n * fine (the adapter only saves on `changed`).\n */\nexport function patchItemOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n  patch: (item: QueueItem<I>) => QueueItem<I>,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const idx = queue.findIndex((i) => i.id === id);\n  if (idx === -1) return { next: queue.slice(), changed: false };\n  const next = queue.slice();\n  // `idx !== -1` guarantees the slot is present.\n  next[idx] = patch(queue[idx]!);\n  return { next, changed: true };\n}\n\n/** Reset every `running` item back to `pending`, clearing `startedAt`. */\nexport function resetRunningOp<I>(queue: readonly QueueItem<I>[]): {\n  next: QueueItem<I>[];\n  changed: boolean;\n} {\n  let changed = false;\n  const next = queue.map((i) => {\n    if (i.status !== \"running\") return i;\n    changed = true;\n    return { ...i, status: \"pending\" as QueueItemStatus, startedAt: undefined };\n  });\n  return { next, changed };\n}\n\n/** Hard-delete an item regardless of status. */\nexport function removeOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const next = queue.filter((i) => i.id !== id);\n  return { next, changed: next.length !== queue.length };\n}\n","/**\n * @demlik/tea/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.\n *\n * The pure ops live in `./ops` and are NOT exported. Tests and consumers reach\n * them only through `createQueue(store)`. This mirrors `@demlik/tea/do`'s\n * one-shape-per-package rule: a single adapter is the public surface.\n *\n * The package is generic in the input payload `I` (audit-specific fields go\n * here in apps/extension). `output` is a free-form side-channel correlation\n * token (a backend id, URL, trace id) — typed as `string` because that's its\n * only honest type. Consumers that need structured per-item data persist it in\n * their own store and put the foreign-key string in `output`.\n */\n\nimport type { Store } from \"../index\";\nimport { claimNextOp, enqueueOp, markDoneOp, patchItemOp, removeOp, resetRunningOp } from \"./ops\";\n\n/**\n * Generate a queue-item id at the adapter boundary. Reads `Date.now()` and\n * `Math.random()` — impure helpers belong in the adapter (`index.ts`),\n * never in `ops.ts` (which is purely-functional by contract). Uses native\n * UUID when available, falls back to timestamp + random for environments\n * without `crypto.randomUUID`.\n */\nfunction genId(): string {\n  return (\n    globalThis.crypto?.randomUUID?.() ?? `q_${Date.now()}_${Math.random().toString(36).slice(2)}`\n  );\n}\n\nexport type QueueItemStatus = \"pending\" | \"running\" | \"done\" | \"failed\" | \"cancelled\";\n\nexport interface QueueItem<I> {\n  id: string;\n  status: QueueItemStatus;\n  input: I;\n  enqueuedAt: number;\n  startedAt?: number;\n  finishedAt?: number;\n  output?: string;\n  error?: string;\n}\n\n/**\n * Caller-facing enqueue payload. Just `I` today — kept named so future\n * variants (priority, deferUntil, …) can grow without breaking callers.\n */\nexport type EnqueueInput<I> = I;\n\n/**\n * Adapter that binds the pure ops to an injected `Store<QueueItem<I>[]>`.\n *\n * `load → mutate → save` is the only durability discipline this package\n * imposes. The store decides what \"save\" means (chrome.storage, KV, DO\n * storage, in-memory) — that decision belongs at the caller.\n *\n * Ops that don't change the queue (e.g. `markDone` on an unknown id) skip the\n * save call so the underlying store doesn't observe a write churn.\n */\nexport function createQueue<I>(store: Store<QueueItem<I>[]>) {\n  // `Store<S>.load()` returns `unknown` (invariant 8 boundary). Route\n  // through `store.migrate(raw)` to get the typed value before any\n  // queue operation reads it — same wiring the substrate's `run()` uses at\n  // boot. The work queue is a substrate-agnostic primitive on top of\n  // `Store<S>`, so it honors the same contract.\n  async function loadParsed(): Promise<QueueItem<I>[] | null> {\n    const raw = await store.load();\n    return store.migrate(raw);\n  }\n\n  async function list(): Promise<QueueItem<I>[]> {\n    return (await loadParsed()) ?? [];\n  }\n\n  async function enqueue(input: EnqueueInput<I>): Promise<QueueItem<I>> {\n    const queue = await list();\n    const { next, item } = enqueueOp<I>(queue, input, Date.now(), genId());\n    await store.save(next);\n    return item;\n  }\n\n  async function claimNext(): Promise<QueueItem<I> | null> {\n    const queue = await list();\n    const result = claimNextOp<I>(queue, Date.now());\n    if (!result) return null;\n    await store.save(result.next);\n    return result.claimed;\n  }\n\n  // `markDone` ignores the optional second arg by design: completed runs leave\n  // the queue, and the consumer is expected to persist any output (auditId,\n  // etc.) wherever those completed records belong. Kept in the signature for\n  // call-site readability and forward-compat with `bindOutput`.\n  async function markDone(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = markDoneOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function markFailed(id: string, error: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"failed\",\n      finishedAt: Date.now(),\n      error,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function markCancelled(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"cancelled\",\n      finishedAt: Date.now(),\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function resetRunningToPending(): Promise<void> {\n    const queue = await list();\n    const { next, changed } = resetRunningOp<I>(queue);\n    if (changed) await store.save(next);\n  }\n\n  async function removeItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = removeOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function retryItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"pending\",\n      startedAt: undefined,\n      finishedAt: undefined,\n      error: undefined,\n      output: undefined,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  // `bindOutput` attaches a side-channel correlation token (string) to a\n  // running item without changing its status. The queue can't reach into\n  // `I` to mutate it (the substrate is domain-agnostic), so callers that\n  // need to thread a backend id / URL / trace id through the lifecycle\n  // route it here. Consumers needing structured payloads should persist\n  // them in their own store and put the foreign-key string in `output`.\n  async function bindOutput(id: string, value: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      output: value,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  return {\n    enqueue,\n    claimNext,\n    markDone,\n    markFailed,\n    markCancelled,\n    resetRunningToPending,\n    removeItem,\n    retryItem,\n    bindOutput,\n    list,\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,184 @@
+{
+  "name": "@demlik/tea",
+  "version": "0.1.0",
+  "description": "TEA-faithful state machine substrate — one package, every host adapter. Core + subs + testing, plus React, Durable Object, Chrome extension, Node, in-memory, work-queue, devtools, and property-testing modules as subpaths.",
+  "keywords": [
+    "tea",
+    "elm-architecture",
+    "state-machine",
+    "reducer",
+    "cloudflare",
+    "durable-objects",
+    "react",
+    "effects-as-data"
+  ],
+  "homepage": "https://demlik.run",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cansirin/monorepo.git",
+    "directory": "packages/tea"
+  },
+  "license": "MIT",
+  "author": "Can Sirin",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./subs": {
+      "types": "./dist/subs/index.d.ts",
+      "import": "./dist/subs/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./do": {
+      "types": "./dist/do/index.d.ts",
+      "import": "./dist/do/index.js"
+    },
+    "./mem": {
+      "types": "./dist/mem/index.d.ts",
+      "import": "./dist/mem/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./devtools": {
+      "types": "./dist/devtools/index.d.ts",
+      "import": "./dist/devtools/index.js"
+    },
+    "./devtools/styles.css": "./dist/devtools/styles.css",
+    "./extension": {
+      "types": "./dist/extension/index.d.ts",
+      "import": "./dist/extension/index.js"
+    },
+    "./extension/react": {
+      "types": "./dist/extension/react.d.ts",
+      "import": "./dist/extension/react.js"
+    },
+    "./extension/subs": {
+      "types": "./dist/extension/subs/index.d.ts",
+      "import": "./dist/extension/subs/index.js"
+    },
+    "./extension/test-utils": {
+      "types": "./dist/extension/test-utils.d.ts",
+      "import": "./dist/extension/test-utils.js"
+    },
+    "./work-queue": {
+      "types": "./dist/work-queue/index.d.ts",
+      "import": "./dist/work-queue/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js"
+    },
+    "./pbt": {
+      "types": "./dist/pbt/index.d.ts",
+      "import": "./dist/pbt/index.js"
+    },
+    "./pbt/arbitraries": {
+      "types": "./dist/pbt/arbitraries/index.d.ts",
+      "import": "./dist/pbt/arbitraries/index.js"
+    },
+    "./pbt/runners": {
+      "types": "./dist/pbt/runners/index.d.ts",
+      "import": "./dist/pbt/runners/index.js"
+    },
+    "./retry-backoff": {
+      "types": "./dist/retry-backoff/index.d.ts",
+      "import": "./dist/retry-backoff/index.js"
+    },
+    "./rate-limit": {
+      "types": "./dist/rate-limit/index.d.ts",
+      "import": "./dist/rate-limit/index.js"
+    },
+    "./idempotency": {
+      "types": "./dist/idempotency/index.d.ts",
+      "import": "./dist/idempotency/index.js"
+    },
+    "./circuit-breaker": {
+      "types": "./dist/circuit-breaker/index.d.ts",
+      "import": "./dist/circuit-breaker/index.js"
+    },
+    "./cache": {
+      "types": "./dist/cache/index.d.ts",
+      "import": "./dist/cache/index.js"
+    },
+    "./deadline": {
+      "types": "./dist/deadline/index.d.ts",
+      "import": "./dist/deadline/index.js"
+    },
+    "./machine-viz": {
+      "types": "./dist/machine-viz/index.d.ts",
+      "import": "./dist/machine-viz/index.js"
+    },
+    "./debounce": {
+      "types": "./dist/debounce/index.d.ts",
+      "import": "./dist/debounce/index.js"
+    },
+    "./throttle": {
+      "types": "./dist/throttle/index.d.ts",
+      "import": "./dist/throttle/index.js"
+    },
+    "./recorder": {
+      "types": "./dist/recorder/index.d.ts",
+      "import": "./dist/recorder/index.js"
+    },
+    "./trace-replay": {
+      "types": "./dist/trace-replay/index.d.ts",
+      "import": "./dist/trace-replay/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "typecheck:examples": "tsc -p examples/tsconfig.json",
+    "prepublishOnly": "tsup"
+  },
+  "dependencies": {
+    "better-result": "^2.5.2"
+  },
+  "peerDependencies": {
+    "fast-check": "^3 || ^4",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19",
+    "vitest": "^2 || ^3",
+    "ws": "^8"
+  },
+  "peerDependenciesMeta": {
+    "fast-check": { "optional": true },
+    "react": { "optional": true },
+    "react-dom": { "optional": true },
+    "vitest": { "optional": true },
+    "ws": { "optional": true }
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "catalog:",
+    "@types/chrome": "catalog:",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "@types/ws": "catalog:",
+    "fast-check": "^3.23.0",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "tsup": "^8.3.5",
+    "typescript": "catalog:",
+    "vitest": "catalog:",
+    "ws": "catalog:"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}