@thomasfosterau/legation-browser 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,656 @@
+import { IndexedDb } from "@effect/platform-browser";
+import { Client, ClientStore, Collection, Identity, Mutation, Node, Query, StoreError, Transport, TransportError } from "@thomasfosterau/legation";
+import * as Layer from "effect/Layer";
+import { ClientEngine, Coverage, EngineHost, HttpCache, Mirror, MirrorChannel, MirrorChannel as MirrorChannel$1, MirrorProtocol } from "@thomasfosterau/legation/internal";
+import * as Effect from "effect/Effect";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as Duration from "effect/Duration";
+import * as Schema from "effect/Schema";
+declare namespace IndexedDbClientStore_d_exports {
+  export { IndexedDbClientStoreOptions, layer, layerNamespaced, layerWindow, namespacedPrefix };
+}
+/** Options for the IndexedDB-backed `ClientStore` layers. */
+interface IndexedDbClientStoreOptions {
+  /** IndexedDB database name. Defaults to platform-browser's default. */
+  readonly database?: string;
+  /** Key namespace inside the store. Defaults to core's `"legation/"`. */
+  readonly prefix?: string;
+  /**
+   * The identity this replica belongs to — an opaque, app-supplied
+   * fingerprint, **never PII and never a credential** (see
+   * {@link Identity.Fingerprint}). Supplying it turns the identity boundary
+   * on: the store compares it with its stamp on open and resets the replica
+   * on a mismatch, quarantining unpushed writes under the superseded
+   * fingerprint. Unset leaves the boundary off.
+   */
+  readonly identity?: Identity.Fingerprint;
+}
+/**
+ * ClientStore over IndexedDB. Requires the `IndexedDb` primitives service;
+ * use {@link layerWindow} where browser globals are available, or provide
+ * `IndexedDb` yourself (tests use fake-indexeddb).
+ *
+ * A pull and a push acknowledgement commit as one IndexedDB transaction (#393),
+ * so a durable pull writes its rows once and writes no release record.
+ */
+declare const layer: (options?: IndexedDbClientStoreOptions) => Layer.Layer<ClientStore.ClientStore, never, IndexedDb.IndexedDb>;
+/** Self-contained layer using the browser's global `indexedDB`. */
+declare const layerWindow: (options?: IndexedDbClientStoreOptions) => Layer.Layer<ClientStore.ClientStore>;
+/**
+ * The key prefix {@link layerNamespaced} derives for a fingerprint:
+ * core's `"legation/"` namespace with a percent-encoded identity segment
+ * under it, so two principals' replicas cannot collide and neither can
+ * collide with an un-namespaced one.
+ */
+declare const namespacedPrefix: (identity: Identity.Fingerprint) => string;
+/**
+ * The namespacing alternative to resetting (#212): one replica per identity
+ * in a single IndexedDB database, keyed by fingerprint.
+ *
+ * A principal's rows are unreachable from another principal's store because
+ * they are under a different key prefix — no comparison, no reset, and a
+ * user who switches back finds their replica still warm. The fingerprint is
+ * still stamped, so a store reached through this layer keeps the same
+ * guarantee if it is ever opened un-namespaced.
+ *
+ * The cost is disk: every identity that has ever signed in on this device
+ * keeps a replica until something clears it. Prefer {@link layerWindow} with
+ * an `identity` where sign-ins are unbounded.
+ *
+ * Pass `database` to isolate at the database level instead of the key level
+ * — a heavier boundary (a whole IndexedDB database per identity, deletable
+ * in one call) for apps that want it.
+ */
+declare const layerNamespaced: (identity: Identity.Fingerprint, options?: Omit<IndexedDbClientStoreOptions, "identity" | "prefix">) => Layer.Layer<ClientStore.ClientStore>;
+declare namespace BroadcastMirrorChannel_d_exports {
+  export { make$1 as make };
+}
+/** A {@link MirrorChannel.MirrorChannel} over a `BroadcastChannel` name. */
+declare const make$1: (name: string) => Effect.Effect<MirrorChannel$1.MirrorChannel, never, Scope.Scope>;
+declare namespace BackgroundSync_d_exports {
+  export { FlushOptions, FlushOutcome, HostNotReady, IdentitySource, ListenOptions$1 as ListenOptions, Listener$1 as Listener, RegisterOnJournalOptions, RegisterOptions, RegisterOutcome, SyncEvent, SyncManager, SyncRegistration, SyncScope, defaultReadyTimeout, defaultTag, flush, identityUnchecked, listen$1 as listen, register, registerOnJournal };
+}
+/**
+ * The tag the library registers and answers. Short on purpose: Chromium
+ * refuses over-long tags.
+ */
+declare const defaultTag = "legation-flush";
+/** How long a `sync` event waits for a host to attach before giving up. */
+declare const defaultReadyTimeout: Duration.Input;
+/** `SyncManager`: absent where the browser has no Background Sync. */
+interface SyncManager {
+  readonly register: (tag: string) => Promise<void>;
+}
+/**
+ * A `ServiceWorkerRegistration`, or any stand-in for one. Typed as `object`
+ * rather than a slice with an optional `sync`, because TypeScript's weak-type
+ * check would then refuse a real registration (whose declared type has no
+ * `sync`); the member is probed at runtime instead (see `syncManagerOf`).
+ */
+type SyncRegistration = object;
+/** The slice of the worker's `SyncEvent` the listener reads. */
+interface SyncEvent {
+  readonly tag: string;
+  /** Chromium: `true` when the browser will not retry this registration again. */
+  readonly lastChance?: boolean;
+  readonly waitUntil: (promise: Promise<unknown>) => void;
+}
+/**
+ * The slice of `ServiceWorkerGlobalScope` the listener needs — `self` in a
+ * worker. `registration` is where the host registers the tag from.
+ */
+interface SyncScope {
+  readonly addEventListener: (type: "sync", listener: (event: SyncEvent) => void) => void;
+  readonly registration?: SyncRegistration | undefined;
+}
+/**
+ * What asking for a sync did. None of these is a failure: registration is
+ * advisory, and the journal flushes on the connectivity path whatever
+ * happens here.
+ *
+ * - `Registered` — the browser will fire the tag's `sync` event.
+ * - `Unsupported` — no service-worker registration, or no `SyncManager` on
+ *   it (Safari, Firefox): the connectivity path flushes.
+ * - `Refused` — the browser declined (permission withheld, no active worker,
+ *   or — from inside a worker — no window of the origin open).
+ */
+type RegisterOutcome = "Registered" | "Unsupported" | "Refused";
+/** Options for {@link register}. */
+interface RegisterOptions {
+  /** Defaults to {@link defaultTag}; must match the listener's. */
+  readonly tag?: string;
+  /**
+   * Where to register. Defaults to the page's own service-worker
+   * registration (`navigator.serviceWorker.getRegistration()` — never
+   * `ready`, which would wait forever on a page no worker controls).
+   */
+  readonly registration?: Effect.Effect<SyncRegistration | undefined>;
+}
+/**
+ * Ask the browser to wake the worker with the library's `sync` event once
+ * connectivity is back. Call it from the page after a journaled mutation, or
+ * let `ServiceWorkerHost` do it from the worker (see {@link ListenOptions}).
+ *
+ * Never fails and never logs above debug level: absence is the common case
+ * (Background Sync is Chromium-only), and the journal still flushes on the
+ * next connectivity signal. Registering a tag that is already pending is a
+ * no-op for the browser, so calling it once per mutation is fine.
+ */
+declare const register: (options?: RegisterOptions) => Effect.Effect<RegisterOutcome>;
+/** Options for {@link registerOnJournal}. */
+interface RegisterOnJournalOptions extends RegisterOptions {
+  /**
+   * Whether the journal cannot drain right now. Defaults to
+   * `navigator.onLine === false` in the worker (`WorkerNavigator.onLine`).
+   */
+  readonly offline?: Effect.Effect<boolean>;
+}
+/**
+ * Register the tag for the scope's lifetime whenever `engine`'s journal
+ * cannot drain now — the host's side of {@link register}, since in the
+ * service-worker topology a page's mutation is journaled in the worker:
+ *
+ * - a mutation is journaled while {@link RegisterOnJournalOptions.offline}
+ *   holds; and
+ * - a push fails terminally (`ClientEngine.syncFailures`, after the retry
+ *   policy is exhausted) — reachable network, unreachable backend.
+ *
+ * Never on an online mutation: the sync loop drains those, debounced and
+ * compacted, and an online registration would fire `sync` at once and push
+ * each write on its own (#246). Chromium only accepts a registration from a
+ * worker while a window of the origin is open; a refusal is a debug line.
+ */
+declare const registerOnJournal: (engine: ClientEngine.ClientEngine, options?: RegisterOnJournalOptions) => Effect.Effect<void, never, Scope.Scope>;
+/**
+ * What a flush did. Each is a settled outcome — the `sync` event resolves and
+ * the browser does not retry:
+ *
+ * - `Flushed` — the push completed (possibly with nothing pending).
+ *   Acknowledged entries are trimmed and their optimistic effects dropped; a
+ *   permanently rejected one settles as `rejected` in `mutationStates`, with
+ *   its reason.
+ * - `IdentityChanged` — the store is not stamped for whoever is signed in now
+ *   (see {@link ListenOptions.identity}); nothing was pushed, and the journal
+ *   waits for the next page boot to apply the boundary's transition.
+ * - `UpdateNeeded` — the server rejected this build's schema version; the
+ *   journal is retained and `onUpdateNeeded` has fired. Retrying cannot help
+ *   until the app updates.
+ */
+type FlushOutcome = "Flushed" | "IdentityChanged" | "UpdateNeeded";
+/**
+ * The explicit opt-out from the flush's identity check, for an app with **no
+ * signed-in identity at all** (every session is the same public principal).
+ * The flush then relies on the store's boundary alone: quarantined entries
+ * are still unreachable from push, but a store still stamped for a user who
+ * signed out in a tab that closed before `Client.reset` ran **would be
+ * pushed**. Never pass this in an app that has sign-in.
+ */
+declare const identityUnchecked: unique symbol;
+/**
+ * Who is signed in now, as the app resolves it inside the worker — or
+ * {@link identityUnchecked}. See {@link ListenOptions.identity}.
+ */
+type IdentitySource = Effect.Effect<Identity.Fingerprint | undefined> | typeof identityUnchecked;
+/** Options for {@link flush}. */
+interface FlushOptions {
+  /** See {@link ListenOptions.identity}. */
+  readonly identity: IdentitySource;
+}
+/**
+ * Flush `engine`'s journal through the ordinary push path, behind the
+ * identity check. A journal larger than half the engine's unpulled bound goes
+ * in chunks with a pull before each chunk after the first, so a flush may
+ * pull (#429); a smaller journal is pushed without pulling. Fails — so the
+ * `sync` event rejects and the browser reschedules — on a transport or store
+ * failure, with the journal intact. A pull between chunks that fails is a
+ * transport failure of the same kind, so the flush never reports `Flushed`
+ * over a journal it stopped short of.
+ */
+declare const flush: (engine: ClientEngine.ClientEngine, options: FlushOptions) => Effect.Effect<FlushOutcome, TransportError | StoreError>;
+declare const HostNotReady_base: Schema.Class<HostNotReady, Schema.TaggedStruct<"HostNotReady", {
+  readonly tag: Schema.String;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** No host attached the listener within its `readyTimeout`. */
+declare class HostNotReady extends HostNotReady_base {}
+/** Options for {@link listen}. */
+interface ListenOptions$1 {
+  /** The tag to answer, and to register from the host. Defaults to {@link defaultTag}. */
+  readonly tag?: string;
+  /** The worker's global scope. Defaults to `globalThis` (`self` in a worker). */
+  readonly scope?: SyncScope;
+  /**
+   * How long a `sync` event waits for a host to attach before rejecting, so
+   * the browser reschedules it. Defaults to {@link defaultReadyTimeout}. A
+   * worker that only boots its host on a page's handshake never attaches on
+   * a tab-less wake; boot the host at worker start for background flushing.
+   */
+  readonly readyTimeout?: Duration.Input;
+  /**
+   * **Required.** The fingerprint of whoever is signed in **now**, as the app
+   * resolves it from inside the worker (e.g. a session-subject hash it keeps
+   * beside its session). A flush pushes only if the store's stamp equals it
+   * exactly; `undefined` means "cannot tell" and skips.
+   *
+   * Required rather than optional because the store's own boundary covers
+   * only a reset that ran: a tab closed before `Client.reset` leaves the old
+   * identity's journal in the pushable keyspace, and a background flush would
+   * send it under whoever's cookies the worker now carries. An app with no
+   * sign-in passes {@link identityUnchecked}, which accepts that risk
+   * explicitly.
+   */
+  readonly identity: IdentitySource;
+  /**
+   * Register the tag from the worker when the attached engine's journal
+   * cannot drain now (see {@link registerOnJournal}). Defaults to `true`;
+   * turn it off when the page registers with {@link register} itself.
+   */
+  readonly registerOnJournal?: boolean;
+  /**
+   * Whether the journal cannot drain now, for {@link registerOnJournal}.
+   * Defaults to `navigator.onLine === false`.
+   */
+  readonly offline?: Effect.Effect<boolean>;
+}
+/**
+ * The worker's `sync` listener, created by {@link listen}. It answers its
+ * tag from the moment it exists; a host attaches an engine with
+ * {@link Listener.serve}, which `ServiceWorkerHost.start` does when given the
+ * listener as `backgroundSync`.
+ */
+interface Listener$1 {
+  /** The tag this listener answers. */
+  readonly tag: string;
+  /**
+   * Attach `engine` for the scope's lifetime: `sync` events for the tag —
+   * including any that arrived before this call — flush its journal, run
+   * under the caller's services (logger, tracer). Closing the scope detaches
+   * it; a later event then waits for the next host.
+   */
+  readonly serve: (engine: ClientEngine.ClientEngine) => Effect.Effect<void, never, Scope.Scope>;
+}
+/**
+ * Install the `sync` listener on the worker's scope — **synchronously, at the
+ * top level of the worker script** (see the module docs for why). Deliberately
+ * a plain function rather than an Effect for that reason.
+ *
+ * ```ts
+ * // service-worker.ts, top level
+ * const backgroundSync = BackgroundSync.listen({ identity: currentFingerprint });
+ * // ... later, once the engine's layers are built:
+ * yield* ServiceWorkerHost.start({ backgroundSync, registry, nodes, urls });
+ * ```
+ */
+declare const listen$1: (options: ListenOptions$1) => Listener$1;
+declare namespace PushPoke_d_exports {
+  export { ListenOptions, Listener, PokeOutcome, PushEvent, PushScope, listen };
+}
+/** The slice of a worker's `PushEvent` the listener reads. */
+interface PushEvent {
+  /** The push's data (`PushMessageData`, or `null` for a push without any). */
+  readonly data: unknown;
+  readonly waitUntil: (promise: Promise<unknown>) => void;
+}
+/** The slice of `ServiceWorkerGlobalScope` the listener needs — `self` in a worker. */
+interface PushScope {
+  readonly addEventListener: (type: "push", listener: (event: PushEvent) => void) => void;
+  readonly registration?: SyncRegistration;
+}
+/**
+ * What a recognised push did.
+ *
+ * - `Registered` / `Unsupported` / `Refused` — the Background Sync
+ *   registration's outcome (`action: "backgroundSync"`, the default).
+ * - `Pulled` / `PullFailed` — the engine pulled, or the pull failed and the
+ *   next connectivity signal pulls instead (`action: "pull"`).
+ * - `IdentityChanged` — the replica is not stamped for whoever is signed in
+ *   now, so nothing was done.
+ */
+type PokeOutcome = RegisterOutcome | "Pulled" | "PullFailed" | "IdentityChanged";
+/** Options for {@link listen}. */
+interface ListenOptions {
+  /**
+   * **Required.** Who is signed in now, as `BackgroundSync.listen` takes it:
+   * a recognised push acts only if the replica's stamp equals it exactly.
+   * An app with no sign-in passes `BackgroundSync.identityUnchecked`.
+   */
+  readonly identity: IdentitySource;
+  /**
+   * What a recognised push does: `"backgroundSync"` (the default) registers the
+   * library's sync tag; `"pull"` pulls at once.
+   */
+  readonly action?: "backgroundSync" | "pull";
+  /** The sync tag to register; defaults to `BackgroundSync.defaultTag`. */
+  readonly tag?: string;
+  /** The worker's global scope. Defaults to `globalThis` (`self` in a worker). */
+  readonly scope?: PushScope;
+  /**
+   * How long a recognised push waits for a host to attach an engine. Defaults
+   * to `BackgroundSync.defaultReadyTimeout`.
+   */
+  readonly readyTimeout?: Duration.Input;
+}
+/** The `push` listener {@link listen} installs; a host attaches its engine with {@link Listener.serve}. */
+interface Listener {
+  /**
+   * Attach `engine` for the scope's lifetime, which `ServiceWorkerHost.start`
+   * does when given the listener as `pushPoke`. A push that arrived before
+   * then waits for it, up to the ready timeout.
+   */
+  readonly serve: (engine: ClientEngine.ClientEngine) => Effect.Effect<void, never, Scope.Scope>;
+}
+/**
+ * Install the `push` listener on the worker's scope, synchronously at the top
+ * level of the worker script.
+ *
+ * ```ts
+ * // service-worker.ts, top level
+ * const backgroundSync = BackgroundSync.listen({ identity: currentFingerprint });
+ * const pushPoke = PushPoke.listen({ identity: currentFingerprint });
+ * // ... once the engine's layers are built:
+ * yield* ServiceWorkerHost.start({ backgroundSync, pushPoke, registry, nodes });
+ * ```
+ */
+declare const listen: (options: ListenOptions) => Listener;
+declare namespace ServiceWorkerHost_d_exports {
+  export { Host, ServiceWorkerHostOptions, defaultChannelName, run$1 as run, start };
+}
+/** Options for {@link start} and {@link run}. */
+interface ServiceWorkerHostOptions {
+  /** BroadcastChannel name shared with the mirrors it serves. */
+  readonly channelName?: string;
+  /**
+   * The collection registry mirrors' `related` registrations resolve against
+   * (forwarded to {@link EngineHost.run}). Pass it whenever mirrors use
+   * relational reads.
+   */
+  readonly registry?: Collection.CollectionRegistry;
+  /**
+   * The node graph and URL-keyed reads for `SubscribeUrl` registrations
+   * (#159): a page with no `Client` posts `{ _tag: "SubscribeUrl",
+   * mirrorId, url }` on the channel and the host pins the URL's windows
+   * under that id — forwarded to {@link EngineHost.run}. Build `urls` with
+   * `JsonApiQuery.urlReads(nodes)` from `@thomasfosterau/legation-jsonapi`.
+   */
+  readonly nodes?: Node.NodeRegistry;
+  readonly urls?: Client.UrlReads;
+  /**
+   * The worker's Background Sync listener (#213), from
+   * `BackgroundSync.listen({ identity })` at the top level of the worker script. The host
+   * attaches its engine for as long as it serves: the listener's `sync`
+   * events — including one that woke the worker before the host had booted —
+   * flush the journal through `push`, and the tag is registered when the
+   * journal cannot drain now (offline, or a terminally failed push). Unset, no listener is served and `sync` events are not flushed.
+   */
+  readonly backgroundSync?: Listener$1;
+  /**
+   * Web Push as a poke carrier (#214): install `PushPoke.listen({ identity })`
+   * at the top level of the worker script and pass it here. The host attaches
+   * its engine, so a recognised push registers the Background Sync (or pulls,
+   * with `action: "pull"`) once the replica's identity checks out. Unset, the
+   * library's push is not answered.
+   */
+  readonly pushPoke?: Listener;
+}
+/** The default channel name; Mirror setups should use the same one. */
+declare const defaultChannelName = "legation";
+/** The serving host: the engine it serves and what it holds for the mirrors. */
+interface Host {
+  /** The engine the host serves — the replica a façade reads (`ClientView.fromEngine(engine)`). */
+  readonly engine: ClientEngine.ClientEngine;
+  /**
+   * The registrations the host holds on its mirrors' behalf at this moment
+   * (`EngineHost.Host.registrations`): the ledger a façade's coverage check
+   * scans, `Coverage.coverageOf(nodes, view.query, host.registrations)`.
+   */
+  readonly registrations: Effect.Effect<ReadonlyArray<Coverage.Entry>>;
+}
+/**
+ * Start the host: serve mirrors over the broadcast channel and start the
+ * engine's sync loop (pull on poke, push+pull on reconnect), then return
+ * the {@link Host}. Both the host and `runSync` fork their fibers into the
+ * surrounding scope, so the caller must keep that scope open for as long
+ * as it serves (`Effect.never`, as {@link run} does); closing it stops
+ * serving.
+ */
+declare const start: (options?: ServiceWorkerHostOptions) => Effect.Effect<Host, never, ClientEngine.ClientEngine | Scope.Scope>;
+/**
+ * Run the host: {@link start}, then serve forever. NEVER returns — both the
+ * host and `runSync` fork their fibers into the surrounding scope, so
+ * returning would let a caller's `Effect.scoped` tear the whole host down
+ * immediately. Interrupt it / close the scope to stop serving.
+ */
+declare const run$1: (options?: ServiceWorkerHostOptions) => Effect.Effect<never, never, ClientEngine.ClientEngine | Scope.Scope>;
+declare namespace ElectedHost_d_exports {
+  export { ElectedHost, ElectedHostOptions, Role, run };
+}
+/** Whether this tab is currently serving the engine or mirroring another tab's. */
+type Role = "host" | "mirror";
+/** Options for {@link run}. */
+interface ElectedHostOptions {
+  /** The Web Lock name AND the sync-protocol client group — one election per group. */
+  readonly clientGroupId: string;
+  readonly nodes: Node.NodeRegistry;
+  readonly mutations: Mutation.MutatorRegistry;
+  /**
+   * `ClientStore` (durable — pair {@link IndexedDbClientStore}) and
+   * `ClientTransport`, composed as a Layer so winning the election is what
+   * triggers connecting: nothing here opens a socket or an IndexedDB
+   * transaction until this tab is actually elected, keeping a losing (or
+   * still-waiting) tab's footprint to the mirror alone.
+   */
+  readonly dependencies: Layer.Layer<ClientStore.ClientStore | Transport.ClientTransport>;
+  /**
+   * The engine's client identity while this tab hosts. Defaults to
+   * `host-${clientGroupId}` — deterministic and shared by construction, so
+   * whichever tab wins resumes the SAME journal/rows/cookie regardless of
+   * which physical tab or random id it happens to be (a fresh random id
+   * per boot would fork the mutation-id sequence and orphan whatever the
+   * old host had already journaled).
+   */
+  readonly hostClientId?: string;
+  /** BroadcastChannel name shared with every tab in this group. Defaults to {@link ServiceWorkerHost.defaultChannelName}. */
+  readonly channelName?: string;
+  /** Forwarded to {@link EngineHost.run} for mirrors' `related` registrations. */
+  readonly registry?: Collection.CollectionRegistry;
+  /**
+   * URL-keyed reads (#159): lets the returned Client `subscribe(url)`, and
+   * — with `nodes` — lets the hosting tab answer `SubscribeUrl` from pages
+   * without a Client (forwarded to {@link EngineHost.run}).
+   */
+  readonly urls?: Client.UrlReads;
+  readonly queries?: Query.QueryRegistry;
+  readonly syncLoop?: ClientEngine.SyncLoopOptions;
+  /** Override for tests/non-browser injection. Defaults to `navigator.locks`. */
+  readonly locks?: LockManager;
+}
+/** What {@link run} returns: one stable Client for the tab, and a stream of its host/mirror role. */
+interface ElectedHost {
+  /**
+   * One stable Client for the tab's whole lifetime: reads and writes go
+   * through the mirror until this tab is elected, and through the owned
+   * engine from that point on — the switch is transparent to callers (a
+   * live `observe`/`related` re-hydrates from the new tier; explicit
+   * `subscribe` pins are replayed onto it).
+   */
+  readonly client: Client.Client;
+  /** Purely observational — devtools/debug UI. Never drives application logic. */
+  readonly role: Stream.Stream<Role>;
+}
+/**
+ * Elect this tab into hosting `clientGroupId`'s engine — full main-thread
+ * host (ADR-0010) while the lock is held, a mirror over the same channel
+ * otherwise — and hand back one `Client` that works unchanged across the
+ * transition, plus a `role` stream for observability.
+ */
+declare const run: (options: ElectedHostOptions) => Effect.Effect<ElectedHost, never, Scope.Scope>;
+declare namespace CacheApiHttpCache_d_exports {
+  export { CacheLike, CacheStorageLike, FetchHandlerOptions, FetchHandlerResult, fetchHandler, make, metaHeader, open };
+}
+/** The subset of the Cache API this store uses. */
+interface CacheLike {
+  readonly match: (request: Request) => Promise<Response | undefined>;
+  readonly put: (request: Request, response: Response) => Promise<void>;
+  readonly delete: (request: Request) => Promise<boolean>;
+  readonly keys: () => Promise<ReadonlyArray<Request>>;
+}
+/** The slice of the Cache API's `CacheStorage` that {@link open} uses (`caches` in a browser). */
+interface CacheStorageLike {
+  readonly open: (name: string) => Promise<CacheLike>;
+}
+/** Header carrying the serialized CachedResponseMeta on stored copies. */
+declare const metaHeader = "x-legation-cache-meta";
+/** ResponseCacheStore over one named Cache API cache. */
+declare const make: (cache: CacheLike) => HttpCache.ResponseCacheStore;
+/** Open a named cache (defaults to the global `caches`). */
+declare const open: (name: string, cacheStorage?: CacheStorageLike) => Effect.Effect<HttpCache.ResponseCacheStore, StoreError>;
+/** Options for {@link fetchHandler}. */
+interface FetchHandlerOptions {
+  readonly store: HttpCache.ResponseCacheStore;
+  /** Per-request policy; `undefined` bypasses the cache entirely. */
+  readonly policy: (request: Request) => HttpCache.HttpCachePolicy | undefined;
+  /** The network. Defaults to the global `fetch`. */
+  readonly fetch?: (request: Request) => Promise<Response>;
+}
+/** What {@link fetchHandler} answers a request with. */
+interface FetchHandlerResult {
+  readonly response: Response;
+  /**
+   * Present when a stale entry was served: refreshes the cache in the
+   * background. Service workers pass it to `event.waitUntil`.
+   */
+  readonly revalidate?: Effect.Effect<void, StoreError | TransportError> | undefined;
+}
+/**
+ * Build the stale-while-revalidate handler: fresh entries are served from
+ * cache, stale-but-unexpired entries are served immediately with a
+ * background revalidation, and expired or missing entries reload from the
+ * network (caching ok GET responses).
+ */
+declare const fetchHandler: (options: FetchHandlerOptions) => (request: Request) => Effect.Effect<FetchHandlerResult, StoreError | TransportError>;
+declare namespace HttpCacheInvalidation_d_exports {
+  export { FINE_TAG_ROW_BUDGET, InvalidateOnChangesOptions, TagsForOptions, TagsForResult, Touched, collectionChanges, defaultFineTagFor, defaultTagFor, invalidateOnChanges, tagsFor, tagsForObserved };
+}
+/** The default coarse tag convention: `collection:{name}` (`HttpCache.tagFor`, shared with the edge, #206). */
+declare const defaultTagFor: (collection: string) => string;
+/** The default fine, per-row tag convention: `collection:{name}:{id}` (`HttpCache.fineTagFor`). */
+declare const defaultFineTagFor: (collection: string, id: string) => string;
+/**
+ * The fine-tag row budget: a response enumerating more rows than this is
+ * tagged coarse-only (see {@link tagsFor}) rather than carrying one fine tag
+ * per row — a document listing thousands of rows cannot carry thousands of
+ * tags on a bounded header.
+ *
+ * Derived against the real ceiling on the header this convention rides on —
+ * `x-legation-cache-meta` (`CacheApiHttpCache.metaHeader`), which carries
+ * `encodeURIComponent(JSON.stringify(meta))` and so must fit under Node's
+ * default `--max-http-header-size` of 16 KiB (16384 bytes) wherever responses are
+ * served by a Node HTTP server:
+ *
+ * - `encodeURIComponent` expands every byte outside its unreserved set to
+ *   `%XX` (3 bytes), so 3x the raw byte length is a safe upper bound on
+ *   encoded size regardless of which characters a collection name or row id
+ *   use.
+ * - Reserve 4096 bytes (16 KiB / 4) for the rest of `CachedResponseMeta` —
+ *   `url`, three numeric timestamps, the coarse tag, and JSON's own
+ *   braces/keys/quotes — leaving `16384 - 4096 = 12288` bytes for fine tags.
+ * - One fine tag, worst case: a JSON array entry `"collection:{name}:{id}",`
+ *   with a 40-char collection name and a 40-char row id (a UUIDv4 is 36
+ *   chars) is `2 (quotes) + 11 ("collection:") + 40 + 1 (":") + 40 + 1 (",")
+ *   = 95` raw bytes, i.e. at most `95 * 3 = 285` encoded bytes.
+ * - `N = floor(12288 / 285) = 43`.
+ */
+declare const FINE_TAG_ROW_BUDGET = 43;
+/** The collections and individual rows one engine event touched (`HttpCache.Touched`). */
+type Touched = HttpCache.Touched;
+/**
+ * Derive the change feed from an engine's event stream: the distinct
+ * collections and rows each `PullCompleted` (always present) and scoped
+ * `ViewRebuilt` (when present) touched, dropping events that touched
+ * nothing. Feed the result to {@link invalidateOnChanges}.
+ */
+declare const collectionChanges: (events: Stream.Stream<ClientEngine.EngineEvent>) => Stream.Stream<Touched>;
+/** Options for {@link invalidateOnChanges}. */
+interface InvalidateOnChangesOptions {
+  readonly store: HttpCache.ResponseCacheStore;
+  /** Touched collections/rows per change (e.g. from {@link collectionChanges}). */
+  readonly changes: Stream.Stream<Touched>;
+  /** Map a collection name to its coarse cache tag; defaults to {@link defaultTagFor}. */
+  readonly tagFor?: (collection: string) => string;
+  /** Map a row to its fine cache tag; defaults to {@link defaultFineTagFor}. */
+  readonly fineTagFor?: (collection: string, id: string) => string;
+}
+/**
+ * Fork a scoped fibre that, per emitted change, evicts every cached response
+ * tagged for the touched collections (coarse) **and** the touched rows
+ * (fine) — `store.invalidateTags`. Invalidation cost stays proportional to
+ * the store's tag enumeration — this scans no more than `invalidateTags`
+ * already does. Runs until the scope closes; a store error is logged and
+ * swallowed, never fatal to the fibre, so a transient cache failure doesn't
+ * stop future invalidations.
+ */
+declare const invalidateOnChanges: (options: InvalidateOnChangesOptions) => Effect.Effect<void, never, Scope.Scope>;
+/** Options for {@link tagsFor}. */
+interface TagsForOptions {
+  /** Map a collection name to its coarse cache tag; defaults to {@link defaultTagFor}. */
+  readonly tagFor?: (collection: string) => string;
+  /** Map a row to its fine cache tag; defaults to {@link defaultFineTagFor}. */
+  readonly fineTagFor?: (collection: string, id: string) => string;
+}
+/** What {@link tagsFor} returns. */
+interface TagsForResult {
+  /** The tags to attach to the response (`HttpCachePolicy.tags`). */
+  readonly tags: ReadonlyArray<string>;
+  /**
+   * `true` when `rowIds.length` exceeded {@link FINE_TAG_ROW_BUDGET}, so
+   * `tags` carries the coarse tag only rather than one fine tag per row.
+   */
+  readonly budgetExceeded: boolean;
+}
+/**
+ * Build the cache tags for a response that enumerates `rowIds` of
+ * `collection`: the coarse tag, plus one fine tag per row when the row count
+ * is within {@link FINE_TAG_ROW_BUDGET} — beyond it, the coarse tag alone
+ * (`budgetExceeded: true`), since a fine tag per row would blow the header
+ * budget the tag rides on. Pure and synchronous, for use building
+ * `HttpCachePolicy.tags`; pair with {@link tagsForObserved} to also record
+ * the fallback when it happens.
+ */
+declare const tagsFor: (collection: string, rowIds: ReadonlyArray<string>, options?: TagsForOptions) => TagsForResult;
+/**
+ * {@link tagsFor}, plus an observable fallback: a response that exceeded the
+ * budget is never silently coarse — it logs a warning and increments
+ * `legation_cache_tag_budget_exceeded_total` (`Telemetry.cacheTagBudgetExceededTotal`),
+ * following the same "safely degraded, but counted" idiom as the engine's
+ * other bounded-hub fallbacks (`legation_hints_dropped_total`,
+ * `legation_change_collapses_total`).
+ */
+declare const tagsForObserved: (collection: string, rowIds: ReadonlyArray<string>, options?: TagsForOptions) => Effect.Effect<TagsForResult>;
+declare namespace BrowserConnectivity_d_exports {
+  export { BrowserConnectivityOptions, withBrowserConnectivity };
+}
+/**
+ * Options for {@link withBrowserConnectivity}.
+ */
+interface BrowserConnectivityOptions {
+  /**
+   * How often a runtime with no `window` (a service worker) reads
+   * `navigator.onLine` to detect a flip, since it has no `online`/`offline`
+   * events. Defaults to `"5 seconds"`. The interval bounds how long a
+   * reconnect takes to reach the sync loop. Ignored where `window` exists.
+   */
+  readonly pollInterval?: Duration.Input | undefined;
+}
+/**
+ * Wrap a `ClientTransport` so its connection status combines
+ * `navigator.onLine` with the transport's own signal, and a return-to-visible
+ * surfaces a poke. Where there is no `window` (a service worker), the
+ * navigator signal is probed every `pollInterval` instead of listened for.
+ * Scoped: forked fibres and DOM listeners are torn down when the scope closes.
+ */
+declare const withBrowserConnectivity: (transport: Transport.ClientTransport, options?: BrowserConnectivityOptions) => Effect.Effect<Transport.ClientTransport, never, Scope.Scope>;
+export { BackgroundSync_d_exports as BackgroundSync, BroadcastMirrorChannel_d_exports as BroadcastMirrorChannel, BrowserConnectivity_d_exports as BrowserConnectivity, CacheApiHttpCache_d_exports as CacheApiHttpCache, ElectedHost_d_exports as ElectedHost, EngineHost, HttpCacheInvalidation_d_exports as HttpCacheInvalidation, IndexedDbClientStore_d_exports as IndexedDbClientStore, Mirror, MirrorChannel, MirrorProtocol, PushPoke_d_exports as PushPoke, ServiceWorkerHost_d_exports as ServiceWorkerHost };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":["make","MirrorChannel","ListenOptions","Listener","listen","BackgroundSync.SyncRegistration","BackgroundSync.RegisterOutcome","BackgroundSync.IdentitySource","BackgroundSync.Listener","PushPoke.Listener","run"],"sources":["../src/IndexedDbClientStore.ts","../src/BroadcastMirrorChannel.ts","../src/BackgroundSync.ts","../src/PushPoke.ts","../src/ServiceWorkerHost.ts","../src/ElectedHost.ts","../src/CacheApiHttpCache.ts","../src/HttpCacheInvalidation.ts","../src/BrowserConnectivity.ts"],"mappings":"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"}