@effect-app/vue 4.0.0-beta.272 → 4.0.0-beta.274

package/docs/atom-query-api-redesign.md

@@ -0,0 +1,191 @@
+# Atom query API redesign
+
+This branch can stop treating Effect atoms as an implementation detail hidden behind a TanStack-shaped API. The useful durable primitive is the atom; Vue refs, suspense promises, refetch helpers, and future hydration should all be adapters around it.
+
+## Source findings
+
+Relevant upstream Effect v4 atom APIs checked locally:
+
+- `repos/effect/packages/effect/src/unstable/reactivity/Atom.ts`
+  - `AtomRuntime.atom` turns an `Effect` into `Atom<AsyncResult<A, E>>`.
+  - `Atom.family` gives structural cache identity by input.
+  - `Atom.swr`, `Atom.withRefresh`, `Atom.setIdleTTL`, and `Atom.keepAlive` already model stale reads, polling, idle lifetime, and keep-alive.
+  - `Atom.mapResult` and `Atom.transform` are the right composition layer for `select` and derived queries.
+  - `Atom.optimistic` / `Atom.optimisticFn` can replace our current no-op optimistic `useUpdateQuery` facade.
+  - `Atom.toStreamResult`, `Atom.getResult`, `Atom.refresh`, and `Atom.mount` provide Effect-native conversion points.
+- `repos/effect/packages/effect/src/unstable/reactivity/AtomRegistry.ts`
+  - `getResult(registry, atom, { suspendOnWaiting: true })` is the precise operation we need for awaitable refetch and Vue suspense.
+  - Registries are independent; relying on the module-global `defaultRegistry` leaks a policy decision into the query engine.
+- `repos/effect/packages/effect/src/unstable/reactivity/AtomRpc.ts`
+  - Upstream RPC integration exposes `query(tag, payload)` as an atom and `mutation(tag)` as an atom result function. This is the shape we should mirror for effect-app clients.
+- `repos/effect/packages/effect/src/unstable/reactivity/Hydration.ts`
+  - Serializable atoms support `dehydrate` / `hydrate`; Nuxt SSR can use that later without inventing query-specific prefetch state.
+- `repos/effect/packages/atom/vue/src/index.ts`
+  - Vue integration is intentionally thin: `useAtomValue`, `useAtom`, `injectRegistry`, `registryKey`.
+  - There is no special query abstraction upstream; the app layer should own the ergonomic client API.
+
+## Current problems
+
+- `query.ts` still exposes TanStack vocabulary and types: `UseQueryReturnType`, `QueryObserverResult`, `RefetchOptions`, `initialData`, `placeholderData`, `gcTime`, `refetchInterval`, and tuple returns.
+- The raw query atom is hidden in the fourth tuple slot. That makes composition awkward and encourages helper APIs to tunnel through private handles.
+- Query family identity must be stable by query key plus projection hash, while observer options stay outside the family. Otherwise projected and unprojected clients can accidentally share a base atom.
+- `useUpdateQuery` accepts an updater but cannot apply it because query atoms are read-only derived atoms there; it currently refreshes and ignores the updater.
+- Legacy stream query `.query()` is still collapsed into `Stream.runCollect`, so the compatibility API behaves like a slow normal query. Stream query clients now also expose atom-native `.atom()`, `.family()`, and `.queryNew()` helpers backed by `Atom.pull`, so new call sites can observe incremental pull state without waiting for stream completion.
+- The default atom registry is used in invalidation-await logic. That works for today but blocks scoped registries, SSR hydration, and tests that provide a custom registry.
+
+## Compatibility boundary
+
+Keep the existing public APIs intact while the internals move to atom-native composition:
+
+- `client.X.query(...)` keeps its current tuple return shape.
+- `client.X.suspense(...)` keeps returning a Promise of that tuple shape.
+- Existing options remain accepted on old APIs, but their behavior should be fixed internally. In particular, handler-global base atoms should be shared, while observer-specific behavior such as `select`, polling, SWR/focus policy, and structural sharing is layered on top.
+
+Only expose breaking or meaningfully different APIs under new names:
+
+- `client.X.atom(input, options?)`
+- `client.X.queryNew(input, options?)`
+- `client.X.suspenseNew(input, options?)`
+
+This lets the app test the new shape in real call sites without forcing a broad migration, and lets old API users benefit from the internal option-sharing fix.
+
+## Target client shape
+
+Keep query helpers on the typed clients, like mutations:
+
+```ts
+const atom = client.Carts.List.atom(input, options)
+const query = client.Carts.List.queryNew(input, options)
+const suspense = await client.Carts.List.suspenseNew(input, options)
+```
+
+`suspenseNew` stays a `Promise`, because Vue setup / Suspense wants a Promise boundary.
+
+The proposed breaking return shape is an object:
+
+```ts
+interface QueryView<A, E> {
+  readonly result: ComputedRef<AsyncResult.AsyncResult<A, E>>
+  readonly data: ComputedRef<A | undefined>
+  readonly atom: ComputedRef<Atom.Atom<AsyncResult.AsyncResult<A, E>>>
+  readonly awaitResult: () => Effect.Effect<A, E, never>
+  readonly refetch: () => Effect.Effect<A, E, never>
+  readonly refresh: () => void
+}
+
+interface SuspenseQueryView<A, E> extends Omit<QueryView<A, E>, "data"> {
+  readonly data: ComputedRef<A>
+}
+```
+
+`queryNew()` returns `QueryView<A, E>`. `suspenseNew()` returns `Promise<SuspenseQueryView<A, E>>`.
+
+This removes tuple slot meaning, makes `refetch` obviously awaitable, and exposes the atom for composition.
+
+## Atom-first internals
+
+Split the implementation into two layers:
+
+- `atomQuery.ts`: build and compose atoms.
+  - `queryAtom(handler, input, options)` returns `Atom<AsyncResult<A, E>>`.
+  - `queryFamily(handler)` is stable by query key plus projection hash and does not capture observer options.
+  - `awaitQueryAtom(registry, atom)` delegates to `AtomRegistry.getResult`.
+  - `refreshQueryAtom(registry, atom)` delegates to `registry.refresh`.
+- `query.ts`: Vue adapter only.
+  - Resolve refs/getters/options.
+  - Call `useAtomValue`.
+  - Return `QueryView` / `SuspenseQueryView`.
+  - Convert to Promise only inside `useSuspenseQuery`.
+
+Options that affect a single observer should wrap the shared raw atom rather than mutate handler-family identity:
+
+```ts
+const raw = family(input)
+const selected = select ? Atom.mapResult(raw, select) : raw
+const refreshed = refreshEvery
+  ? Atom.withRefresh(refreshEvery)(selected)
+  : selected
+const viewed = Atom.swr({ staleTime, revalidateOnFocus, focusSignal })(
+  refreshed
+)
+```
+
+TTL is the awkward option. If TTL is part of the base atom, it should be a client/default policy, not the first observer's option. For old APIs, keep accepting `gcTime`, but normalize it into a base-atom policy that cannot be captured accidentally by the first observer. For new APIs, prefer an atom-native `idleTTL` or `timeToLive` name.
+
+## Option names
+
+Use atom-native names on the new APIs. Keep old option names on old APIs:
+
+- `gcTime` -> `idleTTL` or `timeToLive`
+- `refetchInterval` -> `refreshEvery`
+- `refetchOnWindowFocus` -> `revalidateOnFocus`
+- `select` can stay; it is a familiar projection name and maps cleanly to `Atom.mapResult`.
+- Drop `initialData` and `placeholderData` from the new core API. Keep them accepted by old APIs if compatibility requires it, but implement them as wrappers/fallbacks over atoms rather than query-engine state.
+
+## Composition API
+
+Expose enough atoms that app code can compose before Vue refs:
+
+```ts
+const cartsAtom = client.Carts.List.atom(undefined)
+const spotsAtom = client.Spots.List.atom(undefined)
+
+const pageAtom = Atom.make((get) => ({
+  carts: get.result(cartsAtom, { suspendOnWaiting: true }),
+  spots: get.result(spotsAtom, { suspendOnWaiting: true })
+}))
+```
+
+For plain result composition, add an atom-native replacement for `composeQueries`:
+
+```ts
+const combined = composeQueryAtoms({
+  carts: client.Carts.List.atom(undefined),
+  spots: client.Spots.List.atom(undefined)
+})
+```
+
+The existing `composeQueries` can remain as a Vue-ref convenience wrapper during migration.
+
+## Optimistic updates
+
+Replace `useUpdateQuery(query, input, updater)` with atom-level helpers:
+
+```ts
+const carts = client.Carts.List.optimistic(input)
+const updateCart = client.Carts.Update.optimistic(carts, reducer)
+```
+
+Internally this should use `Atom.optimistic` / `Atom.optimisticFn`, not a manual cache patch. The mutation can still invalidate reactivity keys after success; optimistic atoms handle temporary UI state and rollback.
+
+## Registry and full-stack notes
+
+- The frontend plugin should provide an app-level `AtomRegistry` via `registryKey` instead of relying on `@effect/atom-vue`'s fallback `defaultRegistry`.
+- `invalidateAndAwait` should await against the active registry, not a module global. A registry-aware mutation layer is cleaner than hidden global state.
+- Serializable query atoms can unlock Nuxt SSR hydration later:
+  - mark query atoms with `Atom.serializable` using request schema + stable input key,
+  - dehydrate after server setup,
+  - hydrate the client registry before mounting.
+- Stream query clients expose pull atoms for real progress:
+  - `client.Progress.Stream.atom(input)` returns `Atom.Writable<Atom.PullResult<A, E>, void>`,
+  - `client.Progress.Stream.family()` returns the reusable atom family,
+  - `client.Progress.Stream.queryNew(input)` returns a Vue view with `result`, `items`, `latest`, `done`, `pull`, and `pullAndAwait`.
+  - Legacy `.query()` remains collect-to-array compatibility until call sites migrate.
+
+## Migration plan
+
+1. Refactor internals so a base query atom is shared per handler+input, then old and new APIs layer observer options on top. This fixes old API behavior without changing old API shape.
+2. Add `client.X.atom(input, options?)`, `client.X.queryNew(input, options?)`, and `client.X.suspenseNew(input, options?)`. Update type tests to assert atom exposure and object-return typing.
+3. Keep `.query()` and `.suspense()` as compatibility APIs. They can delegate to the new internal engine and adapt the result back to tuple shape.
+4. Add one or two real frontend example conversions to `queryNew` / `suspenseNew`, preferably places that exercise:
+   - a suspense read with `data` and `result`,
+   - an awaitable `refetch`,
+   - optionally `atom` composition if a small call site exists.
+5. Keep most frontend call sites on the old tuple APIs so both surfaces are exercised during the transition.
+6. Replace `useUpdateQuery` call sites with atom refresh or optimistic helpers after the new query surface proves out.
+7. Convert legacy stream query call sites from collect-to-array `.query()` to pull/accumulating `.queryNew()` / `.atom()` APIs.
+8. Add registry provider + hydration experiments after the client API is stable.
+
+## Recommendation
+
+Do direct atom exposure and the breaking object API together, but under additive names first. Keep `suspense()` as the compatibility Promise tuple and add `suspenseNew()` as the Promise object API. The Promise should remain a framework boundary over `AtomRegistry.getResult`, not the internal shape. The API should make the atom visible, because that is where Effect v4 gives us composition, refresh, hydration, streams, and optimistic state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-app/vue",
-  "version": "4.0.0-beta.272",
+  "version": "4.0.0-beta.274",
   "license": "MIT",
   "type": "module",
   "homepage": "https://github.com/effect-ts-app/libs/tree/main/packages/vue",
@@ -11,7 +11,7 @@
     "@vueuse/core": "^14.3.0",
     "change-case": "^5.4.4",
     "query-string": "^9.4.0",
-    "effect-app": "4.0.0-beta.272"
+    "effect-app": "4.0.0-beta.274"
   },
   "peerDependencies": {
     "@effect/atom-vue": "^4.0.0-beta.84",

package/src/atomQuery.ts

@@ -0,0 +1,361 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Shared atom core for the query/mutation engine (used by query.ts + mutate.ts).
+ *
+ * Replaces the @tanstack/vue-query engine with Effect `Atom`, keeping the public
+ * `.query()/.suspense()/.mutate()` contract unchanged:
+ *   - cache identity   = the atom reference (one per [handler, input], via Atom.family)
+ *   - invalidation key = reactivity keys (= the app's existing namespace query keys)
+ *   - SWR + focus      = Atom.swr (+ windowFocusSignal)
+ *   - gcTime           = Atom.setIdleTTL / Atom.keepAlive
+ *   - retry            = Effect.retry inside the atom effect
+ *
+ * Built over the app's RPC client through the existing `RequestHandlerWithInput`
+ * abstraction (mirrors AtomRpc's recipe; see docs/atom-query-plan.md).
+ */
+import { defaultRegistry } from "@effect/atom-vue"
+import { makeQueryKey } from "effect-app/client"
+import type { ClientForOptions } from "effect-app/client/clientFor"
+import { ServiceUnavailableError } from "effect-app/client/errors"
+import * as Effect from "effect-app/Effect"
+import * as Option from "effect-app/Option"
+import * as S from "effect-app/Schema"
+import * as Cause from "effect/Cause"
+import * as Duration from "effect/Duration"
+import * as Equal from "effect/Equal"
+import * as Hash from "effect/Hash"
+import type * as Layer from "effect/Layer"
+import * as Stream from "effect/Stream"
+import { isHttpClientError } from "effect/unstable/http/HttpClientError"
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
+import * as Atom from "effect/unstable/reactivity/Atom"
+import * as AtomRegistry from "effect/unstable/reactivity/AtomRegistry"
+import * as Reactivity from "effect/unstable/reactivity/Reactivity"
+import { reportRuntimeError } from "./lib.ts"
+
+/** All non-empty prefixes of a key, longest last. `[a,b,c]` -> `[[a],[a,b],[a,b,c]]`. */
+const prefixesOf = (key: ReadonlyArray<unknown>): ReadonlyArray<ReadonlyArray<unknown>> =>
+  key.map((_, i) => key.slice(0, i + 1))
+
+const uniqueKeys = (keys: ReadonlyArray<ReadonlyArray<unknown>>): ReadonlyArray<ReadonlyArray<unknown>> => {
+  const out: Array<ReadonlyArray<unknown>> = []
+  const seen = new Set<number>()
+  for (const key of keys) {
+    const hash = Hash.hash(key)
+    if (seen.has(hash)) continue
+    seen.add(hash)
+    out.push(key)
+  }
+  return out
+}
+
+// --- awaitable invalidation -------------------------------------------------------------------
+// keyHash -> live query atoms registered under that key. A query atom is tracked while it is alive
+// in the registry (mounted OR cached within idle-ttl) and removed on GC, so invalidation reaches
+// cached-but-unmounted queries too (e.g. a list you navigated away from).
+const keyAtoms = new Map<number, Set<Atom.Atom<AsyncResult.AsyncResult<any, any>>>>()
+
+const trackByKeys =
+  (keys: ReadonlyArray<ReadonlyArray<unknown>>) =>
+  <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>): Atom.Atom<AsyncResult.AsyncResult<A, E>> =>
+    Atom.transform(atom, (get) => {
+      for (const key of keys) {
+        const h = Hash.hash(key)
+        let set = keyAtoms.get(h)
+        if (!set) keyAtoms.set(h, set = new Set())
+        set.add(atom)
+        get.addFinalizer(() => {
+          set.delete(atom)
+          if (set.size === 0) keyAtoms.delete(h)
+        })
+      }
+      return get(atom)
+    }, { initialValueTarget: atom })
+
+const trackWritableByKeys =
+  (keys: ReadonlyArray<ReadonlyArray<unknown>>) =>
+  <A, E, W>(atom: Atom.Writable<AsyncResult.AsyncResult<A, E>, W>): Atom.Writable<AsyncResult.AsyncResult<A, E>, W> => {
+    const tracked = trackByKeys(keys)(atom)
+    return Atom.writable(
+      (get) => get(tracked),
+      (ctx, value) => ctx.set(atom, value),
+      (refresh) => refresh(tracked)
+    )
+  }
+
+const atomsForKeys = (keys: ReadonlyArray<unknown>): ReadonlyArray<Atom.Atom<AsyncResult.AsyncResult<any, any>>> => {
+  const atoms = new Set<Atom.Atom<AsyncResult.AsyncResult<any, any>>>()
+  for (const key of keys) {
+    const set = keyAtoms.get(Hash.hash(key))
+    if (set) { for (const a of set) atoms.add(a) }
+  }
+  return [...atoms]
+}
+
+/**
+ * Invalidate the given keys and AWAIT the result. The invalidation (refetch trigger) goes through
+ * the built-in `Reactivity` service — the same one query atoms register against via
+ * `factory.withReactivity`, shared via the runtime memoMap. The await uses our own `keyAtoms`
+ * tracking + `awaitAtomResult`, since `Reactivity.invalidate` returns void and can't be awaited.
+ *
+ * Resolves once the affected queries have settled, so a mutation can `yield*` this and know the
+ * affected queries are fresh. (The await reads via the module-global default registry — the one the
+ * vue composables resolve via `injectRegistry`'s fallback.)
+ */
+export const invalidateAndAwait = (keys: ReadonlyArray<unknown>): Effect.Effect<void, never, Reactivity.Reactivity> =>
+  Effect.gen(function*() {
+    yield* Reactivity.invalidate(keys) // invalidates everything but only refreshes what's mounted
+    const atoms = atomsForKeys(keys)
+    //    for (const a of atoms) defaultRegistry.refresh(a) // refreshes everything even when not mounted
+    if (atoms.length === 0) return
+    yield* Effect.forEach(atoms, (a) => awaitAtomResult(defaultRegistry, a).pipe(Effect.exit))
+  })
+
+const isPlainObject = (o: unknown): o is Record<string, unknown> => {
+  if (typeof o !== "object" || o === null) return false
+  const proto = Object.getPrototypeOf(o)
+  return proto === Object.prototype || proto === null
+}
+
+/**
+ * Structural sharing (tanstack `replaceEqualDeep`): walk `next` against `prev` and reuse `prev`'s
+ * reference for any unchanged array/object sub-tree, so unchanged data keeps referential identity
+ * (Vue skips re-rendering it). Leaves — including decoded Schema CLASS INSTANCES — are compared with
+ * Effect `Equal.equals` (structural), which reuses equal instances that tanstack's `===` could not.
+ */
+const replaceEqualDeep = (prev: any, next: any): any => {
+  if (prev === next) return prev
+  const bothArrays = Array.isArray(prev) && Array.isArray(next)
+  if (bothArrays || (isPlainObject(prev) && isPlainObject(next))) {
+    const a: Record<PropertyKey, any> = prev
+    const b: Record<PropertyKey, any> = next
+    const copy: Record<PropertyKey, any> = bothArrays ? [] : {}
+    const nextKeys: Array<PropertyKey> = bothArrays ? (b as Array<any>).map((_, i) => i) : Object.keys(b)
+    const nextSize = nextKeys.length
+    const prevSize = bothArrays ? (a as Array<any>).length : Object.keys(a).length
+    let equalItems = 0
+    for (let i = 0; i < nextSize; i++) {
+      const key = nextKeys[i]!
+      copy[key] = replaceEqualDeep(a[key], b[key])
+      if (copy[key] === a[key] && a[key] !== undefined) equalItems++
+    }
+    return prevSize === nextSize && equalItems === prevSize ? prev : copy
+  }
+  return Equal.equals(prev, next) ? prev : next
+}
+
+/** Atom combinator: share each new `Success` value structurally against the previous one. */
+const structuralShare = <A, E>(
+  self: Atom.Atom<AsyncResult.AsyncResult<A, E>>
+): Atom.Atom<AsyncResult.AsyncResult<A, E>> =>
+  Atom.transform(self, (get) => {
+    const next = get(self)
+    if (next._tag !== "Success") return next
+    const prev = Option.flatMap(get.self<AsyncResult.AsyncResult<A, E>>(), AsyncResult.value)
+    if (Option.isNone(prev)) return next
+    const shared = replaceEqualDeep(prev.value, next.value)
+    return shared === next.value
+      ? next
+      : AsyncResult.success(shared, { waiting: next.waiting, timestamp: next.timestamp })
+  }, { initialValueTarget: self })
+
+export interface AtomClientRuntime {
+  readonly runtime: Atom.AtomRuntime<any, never>
+  readonly factory: Atom.RuntimeFactory
+}
+
+/**
+ * Build one AtomRuntime (and its factory) from an already-built app context.
+ * Shares the ManagedRuntime's `memoMap` so layers are not built twice, and so
+ * query-registration and mutation-invalidation resolve the SAME `Reactivity`.
+ */
+export const makeAtomClientRuntime = (
+  getContext: () => Layer.Layer<any, never, never>,
+  memoMap: Layer.MemoMap
+): AtomClientRuntime => {
+  const factory = Atom.context({ memoMap })
+  const runtime = factory((_get) => getContext())
+  return { runtime, factory }
+}
+
+const isRetryable = (e: unknown): boolean =>
+  isHttpClientError(e)
+  || S.is(ServiceUnavailableError)(e)
+  || (typeof e === "object" && e !== null && (e as any)._tag === "RpcClientError")
+
+export interface AtomQueryOptions {
+  /** background-refresh threshold (TanStack staleTime; default 5s) */
+  readonly staleTime?: Duration.Input
+  /** dispose-when-idle (TanStack gcTime; default 5min). "infinity" => keepAlive */
+  readonly gcTime?: Duration.Input | "infinity"
+  /**
+   * Revalidate a stale query on window focus AND on network reconnect (default on, matching
+   * tanstack refetchOnWindowFocus + refetchOnReconnect).
+   */
+  readonly revalidateOnFocus?: boolean
+  /**
+   * Reuse references of unchanged sub-trees across refetches (default on, matching tanstack
+   * structuralSharing). Uses Effect `Equal` so decoded Schema instances share too — more effective
+   * than tanstack's `===`, but a deep compare per refetch (O(rows·fields)). Set `false` for very
+   * large or mostly-changing result sets where the compare costs more than the saved re-renders.
+   */
+  readonly structuralSharing?: boolean
+  /** poll: re-fetch every N ms (tanstack refetchInterval). */
+  readonly refetchInterval?: number
+}
+
+const defaults = { staleTime: Duration.seconds(5), gcTime: Duration.minutes(5) }
+
+/** Exported so the vue hook can do refetch-on-mount-per-observer with the same rule as swr. */
+export const isStaleResult = (r: AsyncResult.AsyncResult<any, any>, staleTimeMs: number): boolean => {
+  if (r.waiting) return false
+  const ts = r._tag === "Success"
+    ? r.timestamp
+    : r._tag === "Failure"
+    ? Option.getOrUndefined(Option.map(r.previousSuccess, (s) => s.timestamp))
+    : undefined
+  if (ts === undefined) return r._tag !== "Initial"
+  return Date.now() - ts >= staleTimeMs
+}
+
+export const staleTimeMsOf = (opts: AtomQueryOptions): number =>
+  Duration.toMillis(Duration.fromInputUnsafe(opts.staleTime ?? defaults.staleTime))
+
+export const withQueryOptions = <A, E>(
+  self: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
+  opts: AtomQueryOptions = {}
+): Atom.Atom<AsyncResult.AsyncResult<A, E>> => {
+  const staleTime: Duration.Input = opts.staleTime ?? defaults.staleTime
+  const gcTime = opts.gcTime === "infinity"
+    ? "infinity" as const
+    : Duration.fromInputUnsafe(opts.gcTime ?? defaults.gcTime)
+  let atom = self
+  const revalidateOnFocus = opts.revalidateOnFocus ?? true
+  atom = Atom.swr({
+    staleTime,
+    revalidateOnFocus,
+    focusSignal: revalidateOnFocus ? focusOrReconnectSignal : undefined
+  })(atom)
+  if (opts.refetchInterval) atom = Atom.withRefresh(Duration.millis(opts.refetchInterval))(atom)
+  if (opts.structuralSharing ?? true) atom = structuralShare(atom)
+  return gcTime === "infinity" ? Atom.keepAlive(atom) : Atom.setIdleTTL(atom, gcTime)
+}
+
+/** Constant atom for disabled / `mode:"optional"`-None queries: stays Initial, never fetches. */
+export const disabledQueryAtom: Atom.Atom<AsyncResult.AsyncResult<any, any>> = Atom.readable(() =>
+  AsyncResult.initial(false)
+)
+
+/**
+ * Bumps when the browser regains connectivity (the `online` event) — the tanstack
+ * `refetchOnReconnect` trigger. One shared listener (module-level). SSR-guarded.
+ */
+const onlineSignal: Atom.Atom<number> = Atom.readable((get) => {
+  let count = 0
+  if (typeof window === "undefined") return count
+  const update = () => {
+    if (navigator.onLine) get.setSelf(++count)
+  }
+  window.addEventListener("online", update)
+  get.addFinalizer(() => window.removeEventListener("online", update))
+  return count
+})
+
+/**
+ * Focus OR reconnect, as a single signal for `swr` — both should stale-revalidate a query.
+ * swr takes one `focusSignal`, so we fold window-focus + reconnect into one derived atom;
+ * a bump from either triggers swr's stale check.
+ */
+const focusOrReconnectSignal: Atom.Atom<number> = Atom.make((get) => get(Atom.windowFocusSignal) + get(onlineSignal))
+
+/**
+ * Build the per-input atom family for a request handler — the query CACHE IDENTITY.
+ *
+ * This is the TanStack `queryKey = [handler, input]` equivalent and the piece that makes
+ * caching cross-component: `Atom.family` memoizes one atom per structurally-distinct input
+ * (v4 hashes the input via Hash/Equal), so every component querying the same handler+input
+ * reads the SAME atom instance => one fetch, one shared result in the global registry,
+ * ref-counted and GC'd on idle ttl. (The registry + ttl give lifetime; reactivity keys give
+ * invalidation; the family gives identity/sharing — all three are needed.)
+ *
+ * The family is created once per handler (see query.ts's per-handler cache), so it is shared
+ * process-wide via the registry.
+ *
+ * Invalidation is hierarchical: each atom registers under EVERY prefix of its full key
+ * `[...makeQueryKey(self), input]`. Since reactivity matches keys by exact hash, registering
+ * all prefixes means `invalidate(P)` refreshes every atom whose key starts with `P` — e.g.
+ * `["$X"]` refreshes all inputs, `["$X","$List",input]` only that input. (`makeQueryKey`'s
+ * collapsed form `getQueryKey` — what mutations invalidate by default — is one of the prefixes.)
+ */
+export const buildQueryFamily = <I, A, E>(
+  rt: AtomClientRuntime,
+  self: {
+    readonly id: string
+    readonly handler: (i: I) => Effect.Effect<A, E, any>
+    readonly options?: ClientForOptions
+    readonly queryKeyProjectionHash?: string
+  }
+) => {
+  const baseKey = makeQueryKey(self) // hierarchical, input-independent
+
+  return Atom.family((input: I) => {
+    let atom: Atom.Atom<AsyncResult.AsyncResult<A, E>> = rt.runtime.atom(
+      self
+        .handler(input)
+        .pipe(
+          Effect.retry({ times: 5, while: isRetryable }),
+          Effect.tapCauseIf(Cause.hasDies, (cause) => reportRuntimeError(cause)),
+          Effect.withSpan(`query ${self.id}`, {}, { captureStackTrace: false })
+        )
+    )
+    // Register under every prefix of the full key => hierarchical (prefix) invalidation. Two roles:
+    //   - withReactivity: `Reactivity.invalidate(key)` refreshes this atom (the actual refetch).
+    //   - trackByKeys:    records the atom in `keyAtoms` so the mutation can AWAIT its settle.
+    const fullKey = [...baseKey, input]
+    const projectedFullKey = self.queryKeyProjectionHash === undefined
+      ? fullKey
+      : [...baseKey, self.queryKeyProjectionHash, input]
+    const reactivityKeys = uniqueKeys([...prefixesOf(fullKey), ...prefixesOf(projectedFullKey)])
+    atom = rt.factory.withReactivity(reactivityKeys)(atom)
+    atom = trackByKeys(reactivityKeys)(atom)
+    // gcTime LAST so the whole chain (incl. the registration + tracking) stays alive through the
+    // idle window, letting invalidation reach a cached-but-unmounted query.
+    atom = Atom.setIdleTTL(atom, defaults.gcTime)
+    return Atom.withLabel(`query:${self.id}`)(atom)
+  })
+}
+
+export const buildStreamQueryFamily = <I, A, E>(
+  rt: AtomClientRuntime,
+  self: {
+    readonly id: string
+    readonly handler: (i: I) => Stream.Stream<A, E, any>
+    readonly options?: ClientForOptions
+    readonly queryKeyProjectionHash?: string
+  }
+) => {
+  const baseKey = makeQueryKey(self)
+
+  return Atom.family((input: I) => {
+    let atom = rt.runtime.pull(
+      self.handler(input).pipe(
+        Stream.tapCause((cause) => Cause.hasDies(cause) ? reportRuntimeError(cause) : Effect.void)
+      )
+    )
+    const fullKey = [...baseKey, input]
+    const projectedFullKey = self.queryKeyProjectionHash === undefined
+      ? fullKey
+      : [...baseKey, self.queryKeyProjectionHash, input]
+    const reactivityKeys = uniqueKeys([...prefixesOf(fullKey), ...prefixesOf(projectedFullKey)])
+    atom = rt.factory.withReactivity(reactivityKeys)(atom)
+    atom = trackWritableByKeys(reactivityKeys)(atom)
+    atom = Atom.setIdleTTL(atom, defaults.gcTime)
+    return Atom.withLabel(`stream-query:${self.id}`)(atom)
+  })
+}
+
+/** Await the first resolved (non-Waiting) result of an atom. Failing query results fail the Effect. */
+export const awaitAtomResult = <A, E>(
+  registry: AtomRegistry.AtomRegistry,
+  atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>
+) => AtomRegistry.getResult(registry, atom, { suspendOnWaiting: true })