@demlik/tea 0.20.0 → 0.21.0

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/react/index.ts"],"names":[],"mappings":";;AAqGO,SAAS,UAAA,CAOd,SACA,IAAA,EACgC;AAMhC,EAAA,MAAM,MAAM,IAAA,CAAK,GAAA;AACjB,EAAA,MAAM,MAAM,IAAA,CAAK,GAAA;AACjB,EAAA,MAAM,QAAQ,IAAA,CAAK,KAAA;AAInB,EAAA,MAAM,WAAA,GAAc,OAAkC,IAAI,CAAA;AAC1D,EAAA,WAAA,CAAY,OAAA,GAAU,IAAA;AACtB,EAAA,MAAM,QAAA,GAAW,OAAA;AAAA,IACf,OAAO;AAAA,MACL,SAAA,EAAW,WAAA;AAAA,QACT,MAAO,YAAY,OAAA,CAAmC;AAAA,OACxD;AAAA,MACA,SAAA,EAAW,WAAA,CAAY,MAAM,WAAA,CAAY,QAAQ,SAAS;AAAA,KAG5D,CAAA;AAAA,IACA;AAAC,GACH;AAMA,EAAA,MAAM,OAAA,GAAU,OAAA;AAAA,IACd,MACE,IAAI,OAAA,EAAS;AAAA,MACX,GAAA;AAAA,MACA,KAAA;AAAA,MACA,GAAG;AAAA,KAC2B,CAAA;AAAA,IAClC,CAAC,OAAA,EAAS,GAAA,EAAK,GAAA,EAAK,OAAO,QAAQ;AAAA,GACrC;AAeA,EAAA,MAAM,QAAA,GAAW,OAAqC,IAAI,CAAA;AAC1D,EAAA,MAAM,GAAG,UAAU,CAAA,GAAI,WAAW,CAAC,IAAA,KAAiB,IAAA,GAAO,CAAA,EAAG,CAAC,CAAA;AAa/D,EAAA,MAAM,gBAAA,GAAmB,OAAA;AAAA,IACvB,MAAM,OAAA,CAAQ,IAAA,CAAK,IAAA,EAAM,GAAG,EAAE,CAAC,CAAA;AAAA,IAC/B,CAAC,SAAS,GAAG;AAAA,GACf;AAMA,EAAA,MAAM,WAAA,GAAc,MAClB,QAAA,CAAS,OAAA,KAAY,OAAO,QAAA,CAAS,OAAA,CAAQ,UAAS,GAAI,gBAAA;AAE5D,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,OAAA,CAAQ,SAAA;AAAA,IACR,WAAA;AAAA,IACA;AAAA,GACF;AAEA,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,IAAA,GAAO,IAAA;AAMX,IAAA,OAAA,CAAQ,KAAA,CAAM,IAAA;AAAA,MACZ,CAAC,CAAA,KAAM;AACL,QAAA,IAAI,IAAA,EAAM;AACR,UAAA,QAAA,CAAS,OAAA,GAAU,CAAA;AACnB,UAAA,UAAA,EAAW;AAAA,QACb;AAAA,MACF,CAAA;AAAA,MACA,MAAM;AAAA,MAAC;AAAA,KACT;AACA,IAAA,OAAO,MAAM;AACX,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,QAAA,CAAS,OAAA,GAAU,IAAA;AAInB,MAAA,OAAA,CAAQ,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IAC/B,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,OAAO,CAAC,CAAA;AAEZ,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC;AAOA,SAAS,YAAY,OAAA,EAA2C;AAC9D,EAAA,OAAO,IAAI,KAAA;AAAA,IACT,EAAC;AAAA,IACD;AAAA,MACE,KAAK,CAAC,OAAA,EAAS,IAAA,KACZ,OAAA,KAAyD,IAAI;AAAA;AAClE,GACF;AACF;AAgBO,SAAS,WAId,OAAA,EAAmE;AACnE,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,OAAA,CAAQ,SAAA;AAAA,IACR,OAAA,CAAQ,QAAA;AAAA,IACR,OAAA,CAAQ;AAAA,GACV;AACA,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC","file":"index.js","sourcesContent":["/**\n * @packageDocumentation\n * @demlik/tea/react — React host adapter for `@demlik/tea`.\n *\n * The thinnest possible adapter that makes a tea machine consumable from a\n * React component. Three rules (PRD §\"React adapter\"):\n *\n *   1. The runtime is the source of truth, NOT React state. We subscribe via\n *      `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *      runtime.getState)`. React renders are driven by runtime state changes;\n *      React never owns the state.\n *   2. The runtime is memoized per component-mount, not per render. The deps\n *      array is `[machine, opts.ctx, opts.store]` — IDENTITY, not value. See\n *      `README.md` for the ctx-identity footgun + fix.\n *   3. Concurrent React is the design target. `useSyncExternalStore` is the\n *      React-blessed primitive for tearing-free external state.\n *\n * Client-only in v1 — components that call `useMachine` MUST be `\"use client\"`.\n * Server Components consume data via Relay/RSC as today; tea machines own\n * client-side stateful flows. No RSC streaming, no server-side state\n * hydration. Crossing this boundary is a v2 concern.\n */\n\n\"use client\";\n\nimport {\n  useEffect,\n  useMemo,\n  useReducer,\n  useRef,\n  useSyncExternalStore,\n} from \"react\";\nimport type {\n  BootedRunHandle,\n  Cmd,\n  EngineRun,\n  Interpret,\n  Machine,\n  RunHandle,\n  RunHandlers,\n  RunOptions,\n  Store,\n  Sub,\n  Subscribe,\n} from \"../index\";\n\n/**\n * Options passed to `useMachine`. `run` is the engine's `run` — `run` from\n * `@demlik/tea/promise`, or any engine's; the hook imports no engine. `ctx`\n * is required (every machine has one), `store` is optional (omit it for\n * volatile-state machines), and the handlers are the ones `run` takes beside\n * the machine: `interpret` (required once the machine emits a Cmd) and the\n * `subscribe` runners (required once the machine declares a Sub type other\n * than the built-in `timer`) — see {@link RunHandlers}. Same requiredness as\n * `run`, because it is the same type.\n *\n * **The handlers are read fresh, never memoized on.** A handler table written\n * inline in the component is a new object every render; keying the runtime on\n * it would reboot the machine on every render. So `useMachine` hands `run` a\n * table that looks each cell up on the latest render's `interpret` /\n * `subscribe` at the moment a Cmd runs or a Sub starts — a handler may close\n * over props and state freely.\n *\n * **Identity matters.** The runtime is memoized on `[machine, opts.run,\n * opts.ctx, opts.store]`. A new `ctx` reference rebuilds the runtime, and so\n * does a new `run` — pass the engine's own function, not an inline wrapper. Always `useMemo`\n * (or otherwise stabilize) the ctx at the call site. See README.\n *\n * Forgetting to is no longer silent: the replaced runtime's `stop()` reports\n * `RuntimeDiscardedError` under `phase: \"discard\"` when Cmds were still in\n * flight, which the substrate's default sink warns about (issue #365).\n */\nexport type UseMachineOpts<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n> = {\n  run: EngineRun<S, M, C, U, Ctx>;\n  ctx: Ctx;\n  store?: Store<S>;\n} & RunHandlers<M, C, U, Ctx>;\n\n/**\n * Build and own a run of `machine` for the lifetime of the component mount, on\n * the engine whose `run` the caller hands in.\n *\n * - Builds via `useMemo(() => opts.run(machine, opts), [machine, opts.run,\n *   opts.ctx, opts.store])` — the run is recreated when ANY of those\n *   identities change.\n * - Subscribes via `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *   runtime.getState)` — tearing-free under React 18 concurrent rendering.\n * - On unmount (or any dep change), `useEffect` cleanup calls\n *   `runtime.stop()` — drains the queue, runs every active sub cleanup,\n *   flushes state, and — if Cmds were still in flight — reports\n *   `RuntimeDiscardedError` (`phase: \"discard\"`) rather than dropping them\n *   silently.\n *\n * Returns `[state, dispatch]` shaped like `useReducer`.\n */\nexport function useMachine<\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  opts: NoInfer<UseMachineOpts<S, M, C, U, Ctx>>,\n): [S, (msg: M) => Promise<void>] {\n  // Deps are literal: machine, engine, ctx and store identity. NOT `[opts]`\n  // (would rebuild every render — callers pass fresh objects). We pass\n  // explicit fields to `run()` so the closure captures only the deps in the\n  // array — keeps biome's `useExhaustiveDependencies` happy without lying\n  // about what the memo actually depends on.\n  const run = opts.run;\n  const ctx = opts.ctx;\n  const store = opts.store;\n  // The latest render's handlers, read per call (see `UseMachineOpts`). Written\n  // during render on purpose: a Cmd a transition emits runs after the render\n  // that produced it, so the table it reads is never older than that render.\n  const handlersRef = useRef<RunHandlers<M, C, U, Ctx>>(opts);\n  handlersRef.current = opts;\n  const handlers = useMemo(\n    () => ({\n      interpret: latestTable(\n        () => (handlersRef.current as { interpret?: object }).interpret,\n      ) as Interpret<M, C, Ctx>,\n      subscribe: latestTable(() => handlersRef.current.subscribe) as Partial<\n        Subscribe<M, U, Ctx>\n      >,\n    }),\n    [],\n  );\n  // `run()` returns a `RunHandle<S, M>` SYNCHRONOUSLY (issue #45) — exactly\n  // what `useMemo` needs. We never `await` here: awaiting would force an async\n  // memo, a null first-commit state, and a resolved-flag dance. Instead we hold\n  // the booting handle and capture the booted one (the only thing with a total\n  // `getState`) once `ready` resolves.\n  const booting = useMemo<RunHandle<S, M>>(\n    () =>\n      run(machine, {\n        ctx,\n        store,\n        ...handlers,\n      } as RunOptions<S, M, C, U, Ctx>),\n    [machine, run, ctx, store, handlers],\n  );\n\n  // Captures the booted handle once `ready` resolves. Until then it is\n  // `null` and `getSnapshot` serves `preliminaryState`. Reset whenever the\n  // booting handle identity changes (a new machine/ctx/store mount).\n  //\n  // The boot race the paired `bootedTick` bump exists for: the substrate's\n  // boot fanout fires BEFORE `ready` resolves (fireListeners runs inside the\n  // boot step; `ready` chains off the boot promise), so at notification time\n  // this ref is still null and `getSnapshot` returns the same\n  // `preliminaryState` reference — React sees an unchanged snapshot and\n  // skips the re-render. Nothing re-notifies after the ref is set, so a\n  // store-backed mount would stay stuck on the preliminary state until the\n  // next unrelated transition. Bumping a reducer when we capture the booted\n  // runtime forces the render that swaps preliminary → real state.\n  const readyRef = useRef<BootedRunHandle<S, M> | null>(null);\n  const [, markBooted] = useReducer((tick: number) => tick + 1, 0);\n\n  // Preliminary state computed sync from `machine.init(null, ctx)`. This is\n  // the snapshot React sees BEFORE the runtime finishes booting (matters\n  // only when `opts.store` is present — without a store, the substrate\n  // already sets state synchronously inside `run()`, so the boot fanout that\n  // captures `readyRef` lands on the same microtask as the first commit).\n  //\n  // We deliberately recompute on each render but cache by `[machine,\n  // opts.ctx]` — `init` is pure by convention, so cost is negligible. The\n  // cached snapshot is also identity-stable across rerenders when the deps\n  // don't change, which `useSyncExternalStore` rewards (no spurious\n  // re-renders).\n  const preliminaryState = useMemo<S>(\n    () => machine.init(null, ctx)[0],\n    [machine, ctx],\n  );\n\n  // `getSnapshot` reads the booted runtime if `ready` has resolved (the ref is\n  // populated), else falls back to the preliminary state. No try/catch dance\n  // anymore — pre-boot there is simply no booted handle to read from, so\n  // the fallback is structural, not exception-driven.\n  const getSnapshot = (): S =>\n    readyRef.current !== null ? readyRef.current.getState() : preliminaryState;\n\n  const state = useSyncExternalStore(\n    booting.subscribe,\n    getSnapshot,\n    getSnapshot,\n  );\n\n  useEffect(() => {\n    let live = true;\n    // Capture the booted runtime when `ready` resolves, then force the\n    // render that swaps preliminary → real state (see the boot-race note on\n    // `readyRef` — the boot fanout fires too early to do it for us). Boot\n    // rejections are swallowed: a failed boot surfaces on every `dispatch`,\n    // which is where the consumer handles it.\n    booting.ready.then(\n      (r) => {\n        if (live) {\n          readyRef.current = r;\n          markBooted();\n        }\n      },\n      () => {},\n    );\n    return () => {\n      live = false;\n      readyRef.current = null;\n      // Fire-and-forget — `stop()` is async but `useEffect` cleanup is sync.\n      // The runtime swallows in-flight rejections internally, so this never\n      // rejects in practice; we still attach `.catch` for safety.\n      booting.stop().catch(() => {});\n    };\n  }, [booting]);\n\n  return [state, booting.dispatch];\n}\n\n/**\n * A handler table whose every cell is looked up on `current()` at the moment it\n * is read, so `run` — which reads a cell per Cmd / per Sub start — always sees\n * the latest render's handler without the runtime being rebuilt.\n */\nfunction latestTable(current: () => object | undefined): object {\n  return new Proxy(\n    {},\n    {\n      get: (_target, type) =>\n        (current() as Record<PropertyKey, unknown> | undefined)?.[type],\n    },\n  );\n}\n\n/**\n * Lower-level escape hatch: consume an externally-built, booted run — any\n * engine's {@link BootedRunHandle} (the Promise engine's `Runtime` is one).\n *\n * Use this when the runtime is owned by something OTHER than the component —\n * a parent component, a test harness, a singleton. **The component does NOT\n * call `runtime.stop()` on unmount** — the caller owns the lifecycle.\n *\n * Primary use case in this repo: component tests. Build a runtime with\n * `@demlik/tea/mem` and pre-seed it via `replay`, then mount the component with\n * `useRuntime(testRuntime)` to render in any phase.\n *\n * Returns `[state, dispatch]` — same shape as `useMachine`.\n */\nexport function useRuntime<\n  S,\n  M extends { type: string },\n  E extends { type: string } = never,\n>(runtime: BootedRunHandle<S, M, E>): [S, (msg: M) => Promise<void>] {\n  const state = useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getState,\n    runtime.getState,\n  );\n  return [state, runtime.dispatch];\n}\n"]}
+{"version":3,"sources":["../../src/react/index.ts"],"names":[],"mappings":";;AAsGO,SAAS,UAAA,CAOd,SACA,IAAA,EACgC;AAMhC,EAAA,MAAM,MAAM,IAAA,CAAK,GAAA;AACjB,EAAA,MAAM,MAAM,IAAA,CAAK,GAAA;AACjB,EAAA,MAAM,QAAQ,IAAA,CAAK,KAAA;AAInB,EAAA,MAAM,WAAA,GAAc,OAAkC,IAAI,CAAA;AAC1D,EAAA,WAAA,CAAY,OAAA,GAAU,IAAA;AACtB,EAAA,MAAM,QAAA,GAAW,OAAA;AAAA,IACf,OAAO;AAAA,MACL,SAAA,EAAW,WAAA;AAAA,QACT,MAAO,YAAY,OAAA,CAAmC;AAAA,OACxD;AAAA,MACA,SAAA,EAAW,WAAA,CAAY,MAAM,WAAA,CAAY,QAAQ,SAAS;AAAA,KAG5D,CAAA;AAAA,IACA;AAAC,GACH;AAMA,EAAA,MAAM,OAAA,GAAU,OAAA;AAAA,IACd,MACE,IAAI,OAAA,EAAS;AAAA,MACX,GAAA;AAAA,MACA,KAAA;AAAA,MACA,GAAG;AAAA,KAC2B,CAAA;AAAA,IAClC,CAAC,OAAA,EAAS,GAAA,EAAK,GAAA,EAAK,OAAO,QAAQ;AAAA,GACrC;AAeA,EAAA,MAAM,QAAA,GAAW,OAAqC,IAAI,CAAA;AAC1D,EAAA,MAAM,GAAG,UAAU,CAAA,GAAI,WAAW,CAAC,IAAA,KAAiB,IAAA,GAAO,CAAA,EAAG,CAAC,CAAA;AAa/D,EAAA,MAAM,gBAAA,GAAmB,OAAA;AAAA,IACvB,MAAM,OAAA,CAAQ,IAAA,CAAK,IAAA,EAAM,GAAG,EAAE,CAAC,CAAA;AAAA,IAC/B,CAAC,SAAS,GAAG;AAAA,GACf;AAMA,EAAA,MAAM,WAAA,GAAc,MAClB,QAAA,CAAS,OAAA,KAAY,OAAO,QAAA,CAAS,OAAA,CAAQ,UAAS,GAAI,gBAAA;AAE5D,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,OAAA,CAAQ,SAAA;AAAA,IACR,WAAA;AAAA,IACA;AAAA,GACF;AAEA,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,IAAA,GAAO,IAAA;AAMX,IAAA,OAAA,CAAQ,KAAA,CAAM,IAAA;AAAA,MACZ,CAAC,CAAA,KAAM;AACL,QAAA,IAAI,IAAA,EAAM;AACR,UAAA,QAAA,CAAS,OAAA,GAAU,CAAA;AACnB,UAAA,UAAA,EAAW;AAAA,QACb;AAAA,MACF,CAAA;AAAA,MACA,MAAM;AAAA,MAAC;AAAA,KACT;AACA,IAAA,OAAO,MAAM;AACX,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,QAAA,CAAS,OAAA,GAAU,IAAA;AAInB,MAAA,OAAA,CAAQ,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IAC/B,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,OAAO,CAAC,CAAA;AAEZ,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC;AAOA,SAAS,YAAY,OAAA,EAA2C;AAC9D,EAAA,OAAO,IAAI,KAAA;AAAA,IACT,EAAC;AAAA,IACD;AAAA,MACE,KAAK,CAAC,OAAA,EAAS,IAAA,KACZ,OAAA,KAAyD,IAAI;AAAA;AAClE,GACF;AACF;AAgBO,SAAS,WAId,OAAA,EAAmE;AACnE,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,OAAA,CAAQ,SAAA;AAAA,IACR,OAAA,CAAQ,QAAA;AAAA,IACR,OAAA,CAAQ;AAAA,GACV;AACA,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC","file":"index.js","sourcesContent":["/**\n * @packageDocumentation\n * @demlik/tea/react — React host adapter for `@demlik/tea`.\n *\n * The thinnest possible adapter that makes a tea machine consumable from a\n * React component. Three rules (PRD §\"React adapter\"):\n *\n *   1. The runtime is the source of truth, NOT React state. We subscribe via\n *      `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *      runtime.getState)`. React renders are driven by runtime state changes;\n *      React never owns the state.\n *   2. The runtime is memoized per component-mount, not per render. The deps\n *      array is `[machine, opts.ctx, opts.store]` — IDENTITY, not value. See\n *      `README.md` for the ctx-identity footgun + fix.\n *   3. Concurrent React is the design target. `useSyncExternalStore` is the\n *      React-blessed primitive for tearing-free external state.\n *\n * Client-only in v1 — components that call `useMachine` MUST be `\"use client\"`.\n * Server Components consume data via Relay/RSC as today; tea machines own\n * client-side stateful flows. No RSC streaming, no server-side state\n * hydration. Crossing this boundary is a v2 concern.\n */\n\n\"use client\";\n\nimport {\n  useEffect,\n  useMemo,\n  useReducer,\n  useRef,\n  useSyncExternalStore,\n} from \"react\";\nimport type {\n  BootedRunHandle,\n  Cmd,\n  EngineRun,\n  Interpret,\n  Machine,\n  RunHandle,\n  RunHandlers,\n  RunOptions,\n  Store,\n  Sub,\n  Subscribe,\n} from \"../index\";\n\n/**\n * Options passed to `useMachine`. `run` is the engine's `run` — `run` from\n * `@demlik/tea/promise`, or any engine's; the hook imports no engine. `ctx`\n * is required (every machine has one), `store` is optional (omit it for\n * volatile-state machines), and the handlers are the ones `run` takes beside\n * the machine: `interpret` (required once the machine emits a Cmd) and the\n * `subscribe` runners (required once the machine declares a Sub type other\n * than the built-in `timer`) — see {@link RunHandlers}. Same requiredness as\n * `run`, because it is the same type.\n *\n * **The handlers are read fresh, never memoized on.** A handler table written\n * inline in the component is a new object every render; keying the runtime on\n * it would reboot the machine on every render. So `useMachine` hands `run` a\n * table that looks each cell up on the latest render's `interpret` /\n * `subscribe` at the moment a Cmd runs or a Sub starts — a handler may close\n * over props and state freely.\n *\n * **Identity matters.** The runtime is memoized on `[machine, opts.run,\n * opts.ctx, opts.store]`. A new `ctx` reference rebuilds the runtime, and so\n * does a new `run` — pass the engine's own function, not an inline wrapper. Always `useMemo`\n * (or otherwise stabilize) the ctx at the call site. See README.\n *\n * Forgetting to is no longer silent: the replaced runtime's `stop()` reports\n * `RuntimeDiscardedError` under `phase: \"discard\"` when Cmds were still in\n * flight, which the substrate's default sink warns about (issue #365).\n */\nexport type UseMachineOpts<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n> = {\n  run: EngineRun<S, M, C, U, Ctx>;\n  ctx: Ctx;\n  store?: Store<S>;\n} & RunHandlers<M, C, U, Ctx>;\n\n/**\n * Build and own a run of `machine` for the lifetime of the component mount, on\n * the engine whose `run` the caller hands in.\n *\n * - Builds via `useMemo(() => opts.run(machine, opts), [machine, opts.run,\n *   opts.ctx, opts.store])` — the run is recreated when ANY of those\n *   identities change.\n * - Subscribes via `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *   runtime.getState)` — tearing-free under React 18 concurrent rendering.\n * - On unmount (or any dep change), `useEffect` cleanup calls\n *   `runtime.stop()` — drains the queue, up to `disposeTimeoutMs`, runs every\n *   active sub cleanup, flushes state, and — if Cmds were still in flight —\n *   reports `RuntimeDiscardedError` (`phase: \"discard\"`) rather than dropping\n *   them silently. A handler that has not returned by the limit is given up\n *   on and reported as a `DrainTimeoutNotice`.\n *\n * Returns `[state, dispatch]` shaped like `useReducer`.\n */\nexport function useMachine<\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  opts: NoInfer<UseMachineOpts<S, M, C, U, Ctx>>,\n): [S, (msg: M) => Promise<void>] {\n  // Deps are literal: machine, engine, ctx and store identity. NOT `[opts]`\n  // (would rebuild every render — callers pass fresh objects). We pass\n  // explicit fields to `run()` so the closure captures only the deps in the\n  // array — keeps biome's `useExhaustiveDependencies` happy without lying\n  // about what the memo actually depends on.\n  const run = opts.run;\n  const ctx = opts.ctx;\n  const store = opts.store;\n  // The latest render's handlers, read per call (see `UseMachineOpts`). Written\n  // during render on purpose: a Cmd a transition emits runs after the render\n  // that produced it, so the table it reads is never older than that render.\n  const handlersRef = useRef<RunHandlers<M, C, U, Ctx>>(opts);\n  handlersRef.current = opts;\n  const handlers = useMemo(\n    () => ({\n      interpret: latestTable(\n        () => (handlersRef.current as { interpret?: object }).interpret,\n      ) as Interpret<M, C, Ctx>,\n      subscribe: latestTable(() => handlersRef.current.subscribe) as Partial<\n        Subscribe<M, U, Ctx>\n      >,\n    }),\n    [],\n  );\n  // `run()` returns a `RunHandle<S, M>` SYNCHRONOUSLY (issue #45) — exactly\n  // what `useMemo` needs. We never `await` here: awaiting would force an async\n  // memo, a null first-commit state, and a resolved-flag dance. Instead we hold\n  // the booting handle and capture the booted one (the only thing with a total\n  // `getState`) once `ready` resolves.\n  const booting = useMemo<RunHandle<S, M>>(\n    () =>\n      run(machine, {\n        ctx,\n        store,\n        ...handlers,\n      } as RunOptions<S, M, C, U, Ctx>),\n    [machine, run, ctx, store, handlers],\n  );\n\n  // Captures the booted handle once `ready` resolves. Until then it is\n  // `null` and `getSnapshot` serves `preliminaryState`. Reset whenever the\n  // booting handle identity changes (a new machine/ctx/store mount).\n  //\n  // The boot race the paired `bootedTick` bump exists for: the substrate's\n  // boot fanout fires BEFORE `ready` resolves (fireListeners runs inside the\n  // boot step; `ready` chains off the boot promise), so at notification time\n  // this ref is still null and `getSnapshot` returns the same\n  // `preliminaryState` reference — React sees an unchanged snapshot and\n  // skips the re-render. Nothing re-notifies after the ref is set, so a\n  // store-backed mount would stay stuck on the preliminary state until the\n  // next unrelated transition. Bumping a reducer when we capture the booted\n  // runtime forces the render that swaps preliminary → real state.\n  const readyRef = useRef<BootedRunHandle<S, M> | null>(null);\n  const [, markBooted] = useReducer((tick: number) => tick + 1, 0);\n\n  // Preliminary state computed sync from `machine.init(null, ctx)`. This is\n  // the snapshot React sees BEFORE the runtime finishes booting (matters\n  // only when `opts.store` is present — without a store, the substrate\n  // already sets state synchronously inside `run()`, so the boot fanout that\n  // captures `readyRef` lands on the same microtask as the first commit).\n  //\n  // We deliberately recompute on each render but cache by `[machine,\n  // opts.ctx]` — `init` is pure by convention, so cost is negligible. The\n  // cached snapshot is also identity-stable across rerenders when the deps\n  // don't change, which `useSyncExternalStore` rewards (no spurious\n  // re-renders).\n  const preliminaryState = useMemo<S>(\n    () => machine.init(null, ctx)[0],\n    [machine, ctx],\n  );\n\n  // `getSnapshot` reads the booted runtime if `ready` has resolved (the ref is\n  // populated), else falls back to the preliminary state. No try/catch dance\n  // anymore — pre-boot there is simply no booted handle to read from, so\n  // the fallback is structural, not exception-driven.\n  const getSnapshot = (): S =>\n    readyRef.current !== null ? readyRef.current.getState() : preliminaryState;\n\n  const state = useSyncExternalStore(\n    booting.subscribe,\n    getSnapshot,\n    getSnapshot,\n  );\n\n  useEffect(() => {\n    let live = true;\n    // Capture the booted runtime when `ready` resolves, then force the\n    // render that swaps preliminary → real state (see the boot-race note on\n    // `readyRef` — the boot fanout fires too early to do it for us). Boot\n    // rejections are swallowed: a failed boot surfaces on every `dispatch`,\n    // which is where the consumer handles it.\n    booting.ready.then(\n      (r) => {\n        if (live) {\n          readyRef.current = r;\n          markBooted();\n        }\n      },\n      () => {},\n    );\n    return () => {\n      live = false;\n      readyRef.current = null;\n      // Fire-and-forget — `stop()` is async but `useEffect` cleanup is sync.\n      // The runtime swallows in-flight rejections internally, so this never\n      // rejects in practice; we still attach `.catch` for safety.\n      booting.stop().catch(() => {});\n    };\n  }, [booting]);\n\n  return [state, booting.dispatch];\n}\n\n/**\n * A handler table whose every cell is looked up on `current()` at the moment it\n * is read, so `run` — which reads a cell per Cmd / per Sub start — always sees\n * the latest render's handler without the runtime being rebuilt.\n */\nfunction latestTable(current: () => object | undefined): object {\n  return new Proxy(\n    {},\n    {\n      get: (_target, type) =>\n        (current() as Record<PropertyKey, unknown> | undefined)?.[type],\n    },\n  );\n}\n\n/**\n * Lower-level escape hatch: consume an externally-built, booted run — any\n * engine's {@link BootedRunHandle} (the Promise engine's `Runtime` is one).\n *\n * Use this when the runtime is owned by something OTHER than the component —\n * a parent component, a test harness, a singleton. **The component does NOT\n * call `runtime.stop()` on unmount** — the caller owns the lifecycle.\n *\n * Primary use case in this repo: component tests. Build a runtime with\n * `@demlik/tea/mem` and pre-seed it via `replay`, then mount the component with\n * `useRuntime(testRuntime)` to render in any phase.\n *\n * Returns `[state, dispatch]` — same shape as `useMachine`.\n */\nexport function useRuntime<\n  S,\n  M extends { type: string },\n  E extends { type: string } = never,\n>(runtime: BootedRunHandle<S, M, E>): [S, (msg: M) => Promise<void>] {\n  const state = useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getState,\n    runtime.getState,\n  );\n  return [state, runtime.dispatch];\n}\n"]}

package/dist/resilience/index.d.ts

@@ -1,12 +1,12 @@
-import { a as CmdOf, b as CmdDef, e as SettledErr, f as TaggedError, d as SettledOk, T as TimerDeps, C as Cmd } from '../core-CtvAyPpH.js';
+import { a as CmdOf, b as CmdDef, e as SettledErr, f as TaggedError, d as SettledOk, T as TimerDeps, C as Cmd } from '../core-BKJW1Kmq.js';
 import { M as MsgType } from '../protocol-ClRZBhHQ.js';
-import { a as DeadlineSub } from '../index-CVU7SK3a.js';
-export { A as ArmTimer, e as CacheEntry, c as CacheEvictMsg, f as CacheEvictionDeps, C as CacheEvictionSub, D as DeadlineExceeded, g as DeadlineMsgType, h as DeadlineOpts, b as DeadlinesSub, T as TtlCache, i as cacheEvictMsg, j as cacheEvictionSub, k as cacheEvictionSubscribe, d as deadlineExceeded, l as deadlineMsgType, m as deadlineSub, n as deadlines, o as deadlinesSub, p as evictExpired, q as get, r as has, t as initCache, u as nextTimer, v as remove, w as set, x as setTimeoutArmTimer, s as subscribeDeadline, y as subscribeWith } from '../index-CVU7SK3a.js';
-import { d as ResilientConfig, b as ResilientState, R as RunCmd, S as SucceedMsg, F as FailMsg, a as ResilientTimerMsg } from '../index-CKtEKGyp.js';
-export { C as CacheConfig, e as CallBudget, f as CallPhase, g as CircuitConfig, h as CircuitPolicy, i as CircuitState, j as DEFAULT_RESILIENT_NAME, k as DeadlineExceededError, c as DeadlineNameOf, D as DefaultResilientName, l as RateLimitConfig, m as ResilientCallDeadlineConfig, n as ResilientDeadlineType, o as ResilientErrType, p as ResilientOkType, q as ResilientRunType, r as RunCmdDef, s as RunErr, t as SettleMsg, u as SettleOutcome, v as SettleResult, w as SlidingWindow, T as TokenBucket, x as canPass, y as createResilientCall, z as defaultCircuitPolicy, A as initBucket, B as initCircuit, E as initWindow, G as liftResilience, H as onFailure, I as onSuccess, J as record, K as refill, L as remaining, M as runCmdDef, N as tryConsume } from '../index-CKtEKGyp.js';
+import { a as DeadlineSub } from '../index-Diyo8WBO.js';
+export { A as ArmTimer, e as CacheEntry, c as CacheEvictMsg, f as CacheEvictionDeps, C as CacheEvictionSub, D as DeadlineExceeded, g as DeadlineMsgType, h as DeadlineOpts, b as DeadlinesSub, T as TtlCache, i as cacheEvictMsg, j as cacheEvictionSub, k as cacheEvictionSubscribe, d as deadlineExceeded, l as deadlineMsgType, m as deadlineSub, n as deadlines, o as deadlinesSub, p as evictExpired, q as get, r as has, t as initCache, u as nextTimer, v as remove, w as set, x as setTimeoutArmTimer, s as subscribeDeadline, y as subscribeWith } from '../index-Diyo8WBO.js';
+import { d as ResilientConfig, b as ResilientState, R as RunCmd, S as SucceedMsg, F as FailMsg, a as ResilientTimerMsg } from '../index-B-VC4qjx.js';
+export { C as CacheConfig, e as CallBudget, f as CallPhase, g as CircuitConfig, h as CircuitPolicy, i as CircuitState, j as DEFAULT_RESILIENT_NAME, k as DeadlineExceededError, c as DeadlineNameOf, D as DefaultResilientName, l as RateLimitConfig, m as ResilientCallDeadlineConfig, n as ResilientDeadlineType, o as ResilientErrType, p as ResilientOkType, q as ResilientRunType, r as RunCmdDef, s as RunErr, t as SettleMsg, u as SettleOutcome, v as SettleResult, w as SlidingWindow, T as TokenBucket, x as canPass, y as createResilientCall, z as defaultCircuitPolicy, A as initBucket, B as initCircuit, E as initWindow, G as liftResilience, H as onFailure, I as onSuccess, J as record, K as refill, L as remaining, M as runCmdDef, N as tryConsume } from '../index-B-VC4qjx.js';
 import { Rng, RetryPolicy } from '../retry-backoff/index.js';
 import '@standard-schema/spec';
-import '../types-CXNzlbAg.js';
+import '../types-BiXj7k_k.js';
 
 /**
  * A minted credential: the opaque `value` to send on the wire, and the absolute

package/dist/resilience/index.js

@@ -1,10 +1,10 @@
-import { createResilientCall } from '../chunk-72CN3VPY.js';
-export { DEFAULT_RESILIENT_NAME, canPass, createResilientCall, defaultCircuitPolicy, initBucket, initCircuit, initWindow, liftResilience, onFailure, onSuccess, record, refill, remaining, runCmdDef, tryConsume } from '../chunk-72CN3VPY.js';
-export { cacheEvictMsg, cacheEvictionSub, cacheEvictionSubscribe, deadlineExceeded, deadlineMsgType, deadlineSub, deadlines, deadlinesSub, evictExpired, get, has, initCache, nextTimer, remove, set, setTimeoutArmTimer, subscribeDeadline, subscribeWith } from '../chunk-TAKPC6SD.js';
+import { createResilientCall } from '../chunk-MBQR3LFW.js';
+export { DEFAULT_RESILIENT_NAME, canPass, createResilientCall, defaultCircuitPolicy, initBucket, initCircuit, initWindow, liftResilience, onFailure, onSuccess, record, refill, remaining, runCmdDef, tryConsume } from '../chunk-MBQR3LFW.js';
+export { cacheEvictMsg, cacheEvictionSub, cacheEvictionSubscribe, deadlineExceeded, deadlineMsgType, deadlineSub, deadlines, deadlinesSub, evictExpired, get, has, initCache, nextTimer, remove, set, setTimeoutArmTimer, subscribeDeadline, subscribeWith } from '../chunk-QIE4Y6BK.js';
 import { defaultRng, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-VBDU4JL6.js';
 import { unchecked } from '../chunk-4LPY67E4.js';
-import '../chunk-DVNXEB7V.js';
-import { Cmd, without } from '../chunk-RKVUVALV.js';
+import '../chunk-VHKDUBXC.js';
+import { Cmd, without } from '../chunk-GAVLND5C.js';
 
 // src/internal/resilience/token-refresh/index.ts
 function initTokenRefresh() {

package/dist/{run-fiBe7pOG.d.ts → run-D0sxbyno.d.ts}

@@ -1,6 +1,6 @@
 import { Effect, Stream, Scope } from 'effect';
-import { P as Port, C as Cmd, E as ErrorsOf, o as OkOfCmd, p as DeclaredErrorsOf, S as Sub, q as BuiltinSubType, B as BuiltinSub, M as Machine } from './core-CtvAyPpH.js';
-import { c as DispatchSettle, C as CtxArg, S as Store, O as OnError, a as Supervision, T as TelemetrySink } from './runtime-types-DEluQgGO.js';
+import { P as Port, C as Cmd, E as ErrorsOf, p as OkOfCmd, q as DeclaredErrorsOf, c as Sub, r as BuiltinSubType, B as BuiltinSub, M as Machine } from './core-BKJW1Kmq.js';
+import { c as DispatchSettle, C as CtxArg, S as Store, O as OnError, a as Supervision, T as TelemetrySink } from './runtime-types-BPKp2bGo.js';
 import * as effect_Cause from 'effect/Cause';
 import * as effect_Types from 'effect/Types';
 
@@ -90,11 +90,13 @@ interface EffectBootingRuntime<S, M extends {
      */
     readonly ready: Effect.Effect<EffectRuntime<S, M, E, Err>, Err | StoreFailed>;
     /**
-     * Stop the run: drain in-flight work, stop its Subs, flush the final State.
-     * Closing the run's Scope stops the run the same way, and `stop()` leaves
-     * that Scope open. So for a child under `spawn` the two differ: `stop()`
-     * does not take the child out of the host's table or tell the parent. Stop
-     * such a child with the `stop` helper.
+     * Stop the run: drain in-flight work, up to `disposeTimeoutMs`, stop its
+     * Subs, flush the final State. `stop()` interrupts every handler still in
+     * flight, so the limit is reached only by a handler that cannot be
+     * interrupted. Closing the run's Scope stops the run the same way, and
+     * `stop()` leaves that Scope open. So for a child under `spawn` the two
+     * differ: `stop()` does not take the child out of the host's table or tell
+     * the parent. Stop such a child with the `stop` helper.
      */
     stop(): Effect.Effect<void>;
 }
@@ -240,7 +242,18 @@ type EffectRunOptions<S, M extends {
     readonly terminal?: (state: S) => boolean;
     /** A fire-and-forget sink for every applied transition. */
     readonly telemetry?: TelemetrySink;
-    /** How long `stop()` waits for async teardown. Defaults to 5_000ms. */
+    /**
+     * How long `stop()` waits for the queue, and then for async teardown,
+     * before giving up on each. Defaults to 5_000ms. `stop()` interrupts every
+     * handler here, so the first wait ends early unless a handler cannot be
+     * interrupted.
+     *
+     * A store call is not interrupted. tea starts none after `stop()` has
+     * returned, but one already under way when `stop()` gave up can finish
+     * after it. On a plain store that late save can overwrite what a newer
+     * run saved; a fenced store refuses it. So a host that starts a new run on
+     * the same store after a `stop()` that gave up needs a fenced store.
+     */
     readonly disposeTimeoutMs?: number;
 };
 /**
@@ -286,4 +299,4 @@ declare function run<S, M extends {
     type: string;
 } = never>(machine: Machine<S, M, C, U, Ctx>, opts: EffectRunOptions<S, M, C, U, Ctx, E, I, B>): Effect.Effect<EffectBootingRuntime<S, M, E, CellErrors<C, I>>, never, Scope.Scope | InterpretServices<I> | SubscribeServices<B>>;
 
-export { type CellErrors as C, type EffectRuntime as E, type InterpretServices as I, StoreFailed as S, type EffectBootingRuntime as a, type EffectInterpret as b, type EffectInterpretCell as c, type EffectRunOptions as d, type EffectRunner as e, type EffectSubscribe as f, Stopped as g, type SubscribeServices as h, type SubscribeOption as i, run as r };
+export { type CellErrors as C, type EffectInterpret as E, type InterpretServices as I, type SubscribeOption as S, type EffectSubscribe as a, type SubscribeServices as b, type EffectRuntime as c, StoreFailed as d, type EffectBootingRuntime as e, type EffectInterpretCell as f, type EffectRunOptions as g, type EffectRunner as h, Stopped as i, run as r };

package/dist/{runtime-types-DEluQgGO.d.ts → runtime-types-BPKp2bGo.d.ts}

@@ -1,4 +1,4 @@
-import { C as Cmd, S as Sub, M as Machine, R as RunHandlers, P as Port, N as NoCellError, g as Reducer, A as AnyCmdDef, h as Settled, a as CmdOf, i as Transitions, B as BuiltinSub, U as UpdateForm, O as Outcome, j as InterpretDetached, H as HandlerCtx } from './core-CtvAyPpH.js';
+import { C as Cmd, c as Sub, M as Machine, R as RunHandlers, P as Port, N as NoCellError, g as Reducer, A as AnyCmdDef, h as Settled, a as CmdOf, i as Transitions, B as BuiltinSub, U as UpdateForm, O as Outcome, j as InterpretDetached, H as HandlerCtx } from './core-BKJW1Kmq.js';
 
 /**
  * @demlik/tea runtime interface surface + pure helpers — the public types,
@@ -98,12 +98,14 @@ declare function __resetPortRegistry(): void;
  *   run stops — on the Effect engine by closing its Scope with the failure. A
  *   Sub that expects an error maps it to a Msg itself; there is no hook for it
  *   here.
- * - `"discard"` — work lost to a teardown the host asked for. Two witnesses,
- *   both carrying a `RuntimeDiscardNotice`: `stop()` was called while interpret
- *   handlers were still awaiting (`RuntimeDiscardedError`), and a Msg that
- *   arrived DURING `stop()`'s drain and so could not be delivered
- *   (`DispatchDiscardedError`), and teardown work that did not settle inside
- *   `disposeTimeoutMs` (`DisposeTimeoutNotice`). The one phase that is a
+ * - `"discard"` — work lost to a teardown the host asked for. Four witnesses,
+ *   each carrying a `RuntimeDiscardNotice`: `stop()` was called while interpret
+ *   handlers were still awaiting (`RuntimeDiscardedError`), a Msg that
+ *   arrived DURING `stop()`'s drain, or was still queued when `stop()` gave up
+ *   on it, and so could not be delivered (`DispatchDiscardedError`), a drain
+ *   that did not finish inside `disposeTimeoutMs` (`DrainTimeoutNotice`), and
+ *   teardown work that did not settle inside `disposeTimeoutMs`
+ *   (`DisposeTimeoutNotice`). The one phase that is a
  *   LIFECYCLE report rather than a failure: legal, merely lossy.
  * - `"identity-drop"` — the `Identity` filter dropped a message addressed to a
  *   different instance (`IdentityDropNotice`). Its own phase rather than
@@ -237,7 +239,8 @@ declare abstract class RuntimeDiscardNotice extends Error {
 /**
  * Reported to the `OnError` sink under `phase: "discard"` when `stop()` is
  * called while `interpret` handlers are still awaiting. The host is dropping
- * its only handle on that work: `stop()` drains the tail, but the listeners,
+ * its only handle on that work: `stop()` drains the tail, up to
+ * `disposeTimeoutMs`, but the listeners,
  * observers and event handlers that would have consumed the resulting
  * transitions are gone, so the Cmds' results reach nobody.
  *
@@ -294,12 +297,48 @@ declare class DisposeTimeoutNotice extends RuntimeDiscardNotice {
     readonly _tag: "DisposeTimeoutNotice";
     constructor(pendingDisposals: number, timeoutMs: number);
 }
+/**
+ * Reported to the `OnError` sink under `phase: "discard"` when `stop()`'s wait
+ * for the queue hits `disposeTimeoutMs` (ADR 0025): a Cmd handler, a save or
+ * detached work had not returned.
+ *
+ * `stop()` resolves by contract, so it gives up on that work instead of waiting
+ * for it without limit. It then stops the Subs and runs the final save as it
+ * always does. The work it gave up on is not recalled — a Promise cannot be
+ * cancelled — so a handler may still be running after `stop()` has returned.
+ * Whatever it returns later is dropped, and so are the Msgs queued behind it:
+ * each dropped Msg is a `DispatchDiscardedError`. The rest of its step's
+ * Cmds are skipped: no handler starts for them, and they get no notice of
+ * their own. None of it is saved.
+ *
+ * tea starts no store call after `stop()` has returned. A store call already
+ * under way when `stop()` gave up is not cancelled and can finish afterwards;
+ * on a plain store that late save can overwrite what a newer run saved, and a
+ * fenced store refuses it.
+ *
+ * `cmdTypes` names the Cmd of each handler call still awaiting, one entry per
+ * call. `pendingCmds` counts those plus any detached work, the same count
+ * `RuntimeDiscardedError` carries.
+ */
+declare class DrainTimeoutNotice extends RuntimeDiscardNotice {
+    readonly cmdTypes: readonly string[];
+    readonly pendingCmds: number;
+    readonly timeoutMs: number;
+    readonly name = "DrainTimeoutNotice";
+    readonly _tag: "DrainTimeoutNotice";
+    constructor(cmdTypes: readonly string[], pendingCmds: number, timeoutMs: number);
+}
 /**
  * The rejection of a dispatch that arrived DURING `stop()`'s drain — an in-flight
  * interpret handler's follow-up Msg, a detached handler's terminal Msg, or a Sub
  * that is still live because subs are torn down only after the drain. The stop
  * barrier is absolute (the Msg is refused, never folded), so this names the loss.
  *
+ * It is also the rejection of the work `stop()` gave up on (see
+ * `DrainTimeoutNotice`): a Msg a stuck handler produces after `stop()` has
+ * returned, and a Msg that was accepted before `stop()` and was still queued
+ * behind that handler.
+ *
  * It is the SECOND witness of `RuntimeDiscardedError`'s fact, and it is why the
  * drain window is a distinct runtime state rather than a plain `stopped` flag:
  * a Msg refused inside the window was discarded BY the teardown, while the same
@@ -884,4 +923,4 @@ declare function tryFoldMsgs<S, M extends {
  */
 declare function tryInterpret<C extends Cmd, Ok, M, Ctx>(work: (cmd: C, ctx: Ctx) => Promise<Ok>, onOk: (value: Ok, cmd: C) => M, onErr: (error: unknown, cmd: C) => M): (cmd: C, ctx: Ctx) => Promise<M>;
 
-export { defineMachine as A, type BootingRuntime as B, type CtxArg as C, type DeletableStore as D, type EngineRun as E, type FencedStore as F, definePort as G, isFencedStore as H, IdentityDropNotice as I, noop as J, refuse as K, replay as L, type Migrated as M, schemaMigrate as N, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, type TelemetrySink as T, tryApplyCell as U, tryFoldMsgs as V, tryInterpret as W, wrapDetached as X, __resetPortRegistry as _, type Supervision as a, type BootedRunHandle as b, type DispatchSettle as c, type RunHandle as d, type Branded as e, DispatchDiscardedError as f, DisposeTimeoutNotice as g, DriveFailedError as h, DriveStalledError as i, type FencedRead as j, type FoldRefusal as k, type MachineTypes as l, Refusal as m, type RunOptions as n, RuntimeDiscardNotice as o, RuntimeDiscardedError as p, type RuntimeErrorContext as q, type RuntimeErrorPhase as r, type RuntimeRef as s, type Schema as t, StoreConflictError as u, StoreRefusedError as v, type SupervisionStrategy as w, type TelemetryEvent as x, absurd as y, asReducer as z };
+export { asReducer as A, type BootingRuntime as B, type CtxArg as C, type DeletableStore as D, type EngineRun as E, type FencedStore as F, defineMachine as G, definePort as H, IdentityDropNotice as I, isFencedStore as J, noop as K, refuse as L, type Migrated as M, replay as N, type OnError as O, PortNameCollisionError as P, QuiescenceTimeoutError as Q, type Runtime as R, type Store as S, type TelemetrySink as T, schemaMigrate as U, tryApplyCell as V, tryFoldMsgs as W, tryInterpret as X, wrapDetached as Y, __resetPortRegistry as _, type Supervision as a, type BootedRunHandle as b, type DispatchSettle as c, type RunHandle as d, type Branded as e, DispatchDiscardedError as f, DisposeTimeoutNotice as g, DrainTimeoutNotice as h, DriveFailedError as i, DriveStalledError as j, type FencedRead as k, type FoldRefusal as l, type MachineTypes as m, Refusal as n, type RunOptions as o, RuntimeDiscardNotice as p, RuntimeDiscardedError as q, type RuntimeErrorContext as r, type RuntimeErrorPhase as s, type RuntimeRef as t, type Schema as u, StoreConflictError as v, StoreRefusedError as w, type SupervisionStrategy as x, type TelemetryEvent as y, absurd as z };

package/dist/testing/effect/index.d.ts

@@ -1,9 +1,9 @@
-import { D as DriveRoundsExceededError, a as DriveNoHandlerError, b as DriveOptions, c as DriveResult } from '../../drive-loop-Dw1sGSsW.js';
-export { d as DEFAULT_MAX_ROUNDS, e as DriveCtxArg, f as DriveTraceEntry, g as driveTraceOf } from '../../drive-loop-Dw1sGSsW.js';
+import { D as DriveRoundsExceededError, a as DriveNoHandlerError, b as DriveOptions, c as DriveResult } from '../../drive-loop-Dc6Z8Vbs.js';
+export { d as DEFAULT_MAX_ROUNDS, e as DriveCtxArg, f as DriveTraceEntry, g as driveTraceOf } from '../../drive-loop-Dc6Z8Vbs.js';
 import { Effect } from 'effect';
-import { C as CellErrors, i as SubscribeOption, b as EffectInterpret, f as EffectSubscribe, I as InterpretServices, h as SubscribeServices } from '../../run-fiBe7pOG.js';
-import { C as Cmd, S as Sub, M as Machine } from '../../core-CtvAyPpH.js';
-import '../../runtime-types-DEluQgGO.js';
+import { C as CellErrors, S as SubscribeOption, E as EffectInterpret, a as EffectSubscribe, I as InterpretServices, b as SubscribeServices } from '../../run-D0sxbyno.js';
+import { C as Cmd, c as Sub, M as Machine } from '../../core-BKJW1Kmq.js';
+import '../../runtime-types-BPKp2bGo.js';
 import 'effect/Cause';
 import 'effect/Types';
 import '@standard-schema/spec';

package/dist/testing/effect/index.js

@@ -1,11 +1,11 @@
-import { CellFailure, builtinRunners, cellResult, settleCellExit } from '../../chunk-AIXC33SE.js';
-import { driveLoop, DEFAULT_MAX_ROUNDS, driveContractOf, DriveRoundsExceededError, DriveNoHandlerError, annotateTrace, driveTraceOf, desiredSubs } from '../../chunk-XWIE5V7R.js';
-export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, driveTraceOf } from '../../chunk-XWIE5V7R.js';
-import '../../chunk-HX3C6LDK.js';
-import '../../chunk-UHAQ4PI6.js';
-import '../../chunk-A73IJ27X.js';
-import '../../chunk-DVNXEB7V.js';
-import '../../chunk-RKVUVALV.js';
+import { CellFailure, builtinRunners, cellResult, settleCellExit } from '../../chunk-HU3Y2AZY.js';
+import { driveLoop, DEFAULT_MAX_ROUNDS, driveContractOf, DriveRoundsExceededError, DriveNoHandlerError, annotateTrace, driveTraceOf, desiredSubs } from '../../chunk-BFSZ4L6Y.js';
+export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, driveTraceOf } from '../../chunk-BFSZ4L6Y.js';
+import '../../chunk-7Z2IDZ7R.js';
+import '../../chunk-VM7PMFV5.js';
+import '../../chunk-Z7IL735U.js';
+import '../../chunk-VHKDUBXC.js';
+import '../../chunk-GAVLND5C.js';
 import { Effect, Stream, Exit, Cause, Fiber } from 'effect';
 
 var DriveInterrupted = class {

package/dist/testing/index.d.ts

@@ -1,5 +1,5 @@
-import { C as Cmd, S as Sub, M as Machine, B as BuiltinSub } from '../core-CtvAyPpH.js';
-import { R as Runtime } from '../runtime-types-DEluQgGO.js';
+import { C as Cmd, c as Sub, M as Machine, B as BuiltinSub } from '../core-BKJW1Kmq.js';
+import { R as Runtime } from '../runtime-types-BPKp2bGo.js';
 import '@standard-schema/spec';
 
 /**

package/dist/testing/index.js

@@ -1,6 +1,6 @@
-export { bindMachine } from '../chunk-HX3C6LDK.js';
-import '../chunk-DVNXEB7V.js';
-import { replay } from '../chunk-RKVUVALV.js';
+export { bindMachine } from '../chunk-7Z2IDZ7R.js';
+import '../chunk-VHKDUBXC.js';
+import { replay } from '../chunk-GAVLND5C.js';
 import { expect, vi } from 'vitest';
 
 function expectFinalState(machine, opts, expected) {

package/dist/testing/promise/index.d.ts

@@ -1,7 +1,7 @@
-import { b as DriveOptions, c as DriveResult } from '../../drive-loop-Dw1sGSsW.js';
-export { d as DEFAULT_MAX_ROUNDS, e as DriveCtxArg, a as DriveNoHandlerError, D as DriveRoundsExceededError, f as DriveTraceEntry, g as driveTraceOf } from '../../drive-loop-Dw1sGSsW.js';
-import { C as Cmd, S as Sub, M as Machine, I as Interpret } from '../../core-CtvAyPpH.js';
-import '../../runtime-types-DEluQgGO.js';
+import { b as DriveOptions, c as DriveResult } from '../../drive-loop-Dc6Z8Vbs.js';
+export { d as DEFAULT_MAX_ROUNDS, e as DriveCtxArg, a as DriveNoHandlerError, D as DriveRoundsExceededError, f as DriveTraceEntry, g as driveTraceOf } from '../../drive-loop-Dc6Z8Vbs.js';
+import { C as Cmd, c as Sub, M as Machine, I as Interpret } from '../../core-BKJW1Kmq.js';
+import '../../runtime-types-BPKp2bGo.js';
 import '@standard-schema/spec';
 
 /**

package/dist/testing/promise/index.js

@@ -1,8 +1,8 @@
-import { driveContractOf, driveLoop, DEFAULT_MAX_ROUNDS } from '../../chunk-XWIE5V7R.js';
-export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, driveTraceOf } from '../../chunk-XWIE5V7R.js';
-import '../../chunk-HX3C6LDK.js';
-import '../../chunk-DVNXEB7V.js';
-import { cmdEdge, Outcome } from '../../chunk-RKVUVALV.js';
+import { driveContractOf, driveLoop, DEFAULT_MAX_ROUNDS } from '../../chunk-BFSZ4L6Y.js';
+export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, driveTraceOf } from '../../chunk-BFSZ4L6Y.js';
+import '../../chunk-7Z2IDZ7R.js';
+import '../../chunk-VHKDUBXC.js';
+import { cmdEdge, Outcome } from '../../chunk-GAVLND5C.js';
 
 // src/testing/promise/drive.ts
 async function drive(machine, initial, msg, handlers, ...[opts]) {

package/dist/timing/index.d.ts

@@ -1,9 +1,9 @@
 export { D as Debounced, d as debounce } from '../index-DHSUmQTR.js';
-import { C as Cmd } from '../core-CtvAyPpH.js';
-import { T as TtlCache, a as DeadlineSub } from '../index-CVU7SK3a.js';
-export { D as ThrottledInputSettled, s as subscribeThrottledInput, d as throttledInputSettled } from '../index-CVU7SK3a.js';
+import { C as Cmd } from '../core-BKJW1Kmq.js';
+import { T as TtlCache, a as DeadlineSub } from '../index-Diyo8WBO.js';
+export { D as ThrottledInputSettled, s as subscribeThrottledInput, d as throttledInputSettled } from '../index-Diyo8WBO.js';
 import '@standard-schema/spec';
-import '../types-CXNzlbAg.js';
+import '../types-BiXj7k_k.js';
 
 /**
  * internal/timing/throttle — a timer-based call transformer that caps invocation

package/dist/timing/index.js

@@ -1,8 +1,8 @@
 export { debounce } from '../chunk-LFZUK6J2.js';
-import { deadlineSub, initCache, get, set } from '../chunk-TAKPC6SD.js';
-export { subscribeDeadline as subscribeThrottledInput, deadlineExceeded as throttledInputSettled } from '../chunk-TAKPC6SD.js';
-import '../chunk-DVNXEB7V.js';
-import '../chunk-RKVUVALV.js';
+import { deadlineSub, initCache, get, set } from '../chunk-QIE4Y6BK.js';
+export { subscribeDeadline as subscribeThrottledInput, deadlineExceeded as throttledInputSettled } from '../chunk-QIE4Y6BK.js';
+import '../chunk-VHKDUBXC.js';
+import '../chunk-GAVLND5C.js';
 
 // src/internal/timing/throttle/index.ts
 function throttle(fn, ms, opts) {

package/dist/{types-CXNzlbAg.d.ts → types-BiXj7k_k.d.ts}

@@ -1,4 +1,4 @@
-import { S as Sub, D as Dispose } from './core-CtvAyPpH.js';
+import { c as Sub, D as Dispose } from './core-BKJW1Kmq.js';
 
 /**
  * A Sub runner: given the Sub, the `ctx` and a `dispatch`, it opens the

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

@@ -1,7 +1,7 @@
-import { Q as QueueItem } from '../index-D3NY3VCN.js';
-export { E as EnqueueInput, a as QueueItemStatus, c as createQueue } from '../index-D3NY3VCN.js';
-import '../runtime-types-DEluQgGO.js';
-import '../core-CtvAyPpH.js';
+import { Q as QueueItem } from '../index-Cuy1_xTh.js';
+export { E as EnqueueInput, a as QueueItemStatus, c as createQueue } from '../index-Cuy1_xTh.js';
+import '../runtime-types-BPKp2bGo.js';
+import '../core-BKJW1Kmq.js';
 import '@standard-schema/spec';
 
 /**

package/dist/work-queue/index.js

@@ -1,7 +1,7 @@
 import { enqueueOp, claimNextOp, markDoneOp, patchItemOp, resetRunningOp, removeOp } from '../chunk-TXN2KFHF.js';
 export { claimNextOp, enqueueOp, markDoneOp, patchItemOp, queueAdapter, removeOp, resetRunningOp } from '../chunk-TXN2KFHF.js';
-import { restore } from '../chunk-A73IJ27X.js';
-import '../chunk-RKVUVALV.js';
+import { restore } from '../chunk-Z7IL735U.js';
+import '../chunk-GAVLND5C.js';
 
 // src/internal/work-queue/index.ts
 function genId() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demlik/tea",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "TEA-faithful state machine substrate — one package, every host adapter. Core + subs + testing, plus React, Durable Object, Chrome extension, Node, in-memory, devtools, and property-testing modules as subpaths.",
   "keywords": [
     "tea",
@@ -193,7 +193,8 @@
     "vite": "^8.2.1",
     "vitest": "~5.0.1",
     "ws": "^8.21.0",
-    "zod": "^4.5.4"
+    "zod": "^4.5.4",
+    "@demlik/code-graph": "0.8.0"
   },
   "publishConfig": {
     "access": "public"
@@ -212,6 +213,7 @@
     "typecheck:consumers": "tsc -p tsconfig.consumers.json",
     "docs:reference": "TEA_DOCS_WRITE=1 vitest run src/docs/reference/generate-reference.test.ts",
     "docs:reference:strays": "vitest run src/docs/reference/generate-reference.test.ts -t 'holds nothing the generator does not write'",
+    "api:ratchet": "node scripts/api-ratchet.mjs",
     "docs:reference:check": "pnpm run docs:reference:strays && pnpm run docs:reference && git diff --exit-code -- docs/reference",
     "verify:exports": "node scripts/verify-exports.mjs",
     "verify-optional-peer-install": "node scripts/verify-optional-peer-install.mjs"