@thomasfosterau/legation-svelte 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Foster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,391 @@
-# Temporary Holding Version
+# @thomasfosterau/legation-svelte
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Idiomatic Svelte bindings for the
+[`@thomasfosterau/legation`](../effect) engine.
+
+Coming from TanStack Query / SwiftData / SWR? [Coming from TanStack Query](../../docs/comparisons/coming-from-tanstack-query.md) maps those libraries' concepts onto this model.
+
+The package is deliberately thin. Everything the engine can do on its own —
+reads, mutations, hydration — is `@thomasfosterau/legation`; what lives here is the
+Svelte shape of it, plus the two integrations a framework can do that the core
+cannot: **reactive re-subscription** (a read re-runs when the `$state` its
+thunk touches changes) and **SSR hydration** (a server-rendered page's rows
+seeding the first client render).
+
+Two entry points:
+
+| Import                                | What it is                                                                              |
+| ------------------------------------- | --------------------------------------------------------------------------------------- |
+| `@thomasfosterau/legation-svelte`     | `createClient` / `setClient` plus every hook — reads, aggregates, mutations, undo       |
+| `@thomasfosterau/legation-svelte/kit` | the SvelteKit surface: client-group cookie, SSR snapshot `load`, snapshot-hydrated boot |
+
+## Install
+
+```sh
+npm install @thomasfosterau/legation-svelte @thomasfosterau/legation effect svelte
+```
+
+`@sveltejs/kit` is an **optional** peer dependency (`^2.0.0 || ^3.0.0`) — only
+`@thomasfosterau/legation-svelte/kit` needs it, and only as a `Cookies` type, so a non-Kit
+Svelte app pulls nothing.
+
+## Effect version
+
+Peers `effect ^4.0.2`, the floor its dependency `@thomasfosterau/effect-svelte` 0.6.0 requires (it drops to `^4.0.0` once an effect-svelte release peers that). Tested against `4.1.2` (the version CI pins), `4.0.2` (the floor) and `4.0.0` (CI's floor job runs every package's tests there on every PR); install one copy of `effect` in your app (ADR-0003).
+
+## Booting the Client
+
+`createClient` takes `Client.make`'s options and returns a handle; `setClient`
+puts it in context for every hook below it. The app builds no Effect runtime
+and imports nothing from `effect` to boot:
+
+```svelte
+<!-- +layout.svelte -->
+<script lang="ts">
+  import { onDestroy } from "svelte";
+  import { createClient, setClient } from "@thomasfosterau/legation-svelte";
+  import { mutations, nodes } from "$lib/domain";
+
+  // No Client during SSR: the hooks render from their seeds there.
+  const client =
+    typeof document !== "undefined"
+      ? createClient({ nodes, mutations, transport: { url: location.origin } })
+      : undefined;
+  setClient(client);
+  onDestroy(() => void client?.dispose());
+</script>
+```
+
+- **`client.dispose()`** releases the Client: its sync loop stops and its store
+  and transport close. Call it when the app tears down; a second call does
+  nothing more.
+- **On the server, pass no Client** (`setClient(undefined)`). Every hook then
+  renders from its `initial` seed, and only a hook that actually reaches for
+  the Client (a write, a read with no seed) fails, with `ClientUnavailable`.
+  No stand-in runtime is needed.
+- **Custom layers** (an in-page server, a service-worker mirror, a
+  simulated-offline transport, the Kit's snapshot-hydrated `clientRuntime`):
+  build the `ManagedRuntime` yourself and pass `setClient(fromRuntime(runtime))`,
+  or `setClientRuntime(runtime)`, which is the same thing. `getClient()` returns
+  the handle in context (`Option`), and `client.runtime` is the runtime the
+  hooks run over, for Effect code that needs the Client directly.
+
+## The hooks
+
+The package root is the whole read/write surface — the hooks are the API, so
+they are not behind a subpath. Each hook takes its
+inputs as a **thunk** called inside `$effect`, so a read re-subscribes whenever
+the reactive state the thunk touches changes — a paginated read whose cursor
+lives in `$state` just works, and so does a detail read keyed on a route param.
+Results are exposed as a reactive `current`
+[`AsyncResult`](https://effect.website) (the engine's atom vocabulary): while
+re-subscribing the previous value stays visible with `waiting: true`
+(stale-while-revalidate).
+
+- **`useQuery(() => read)`** / **`useNamedQuery(() => ({ name, args }))`** —
+  a declarative `Query.Read`; `include`d edges resolve onto each row's
+  `related`, so a join needs no separate hook. The thunk may return
+  `undefined` to opt out of reading entirely — no window is registered and
+  no request is issued, and `current` stays at its initial state rather than
+  becoming a successful empty result. Every hook below that takes a read
+  thunk (`useConnection`, `useAggregate`, `useAggregateGrouped` included)
+  supports the same opt-out.
+- **`useConnection(() => read, { pageSize })`** — connection-style paging that
+  _grows_ one window rather than jumping between detached pages.
+- **`useAggregate(() => read, agg)`** / **`useAggregateGrouped(() => read, agg, groupBy)`**
+- **`useMutation()`** / **`useMutationWithAck()`** — a promise-returning
+  `mutate(name, args)`, optimistic on resolve; the `WithAck` form settles with
+  the backend's authoritative outcome.
+- **`useMutationState(() => mutator?)`** — every journaled mutation's lifecycle.
+- **`useUndo(manager)`** — `canUndo` / `canRedo` / `undo` / `redo` over an
+  `Undo.UndoManager`.
+- **`setClient(client)`** / **`getClient()`** — the `Client` in Svelte context
+  (see [Booting the Client](#booting-the-client)). Call `setClient` once, high
+  in the tree, before any hook. `setClientRuntime(runtime)` /
+  `getClientRuntime()` are the same over a runtime the app built itself.
+
+Every live hook accepts `{ initial }` to seed a synchronous `Success` before
+the first emission — during SSR (where `$effect` never runs) the seed is what
+renders, and on the client it makes the first render match the server markup
+(no loading flash).
+
+```svelte
+<script lang="ts">
+  import { AsyncResult } from "effect/reactivity";
+  import { useQuery } from "@thomasfosterau/legation-svelte";
+
+  let cursor = $state<string | undefined>(undefined);
+  const page = useQuery(() => ({
+    collection: "products",
+    order: ["id"],
+    first: 20,
+    ...(cursor === undefined ? {} : { after: cursor }),
+  }));
+  const rows = $derived(AsyncResult.getOrElse(page.current, () => []));
+</script>
+```
+
+A read keyed on a selection that starts empty — the common master/detail
+case — opts out by returning `undefined` instead of reaching for a sentinel
+argument that matches nothing:
+
+```svelte
+<script lang="ts">
+  let selectedId = $state<string | undefined>(undefined);
+  const detail = useQuery(() =>
+    selectedId === undefined ? undefined : { collection: "products", where: { id: selectedId } }
+  );
+</script>
+```
+
+While `selectedId` is `undefined`, `detail.current` is `Initial` — no window
+is registered and no request is issued — and selecting a row subscribes just
+as any other reactive input change would.
+
+### Async Svelte
+
+Every live hook also exposes an awaitable **`promise`** for Svelte's
+`experimental.async` mode: it stays pending until the first data arrives —
+so `await` inside a `<svelte:boundary>` renders the boundary's `pending`
+snippet — and is replaced with an already-resolved promise on every
+emission, so awaiting expressions re-run with fresh rows while Svelte keeps
+the previous UI on screen (no pending flash after first load). A failed
+stream rejects it into the boundary's `failed` snippet.
+
+```svelte
+<svelte:boundary>
+  <ul>
+    {#each await page.promise as row (row.id)}
+      <li>{row.value.name}</li>
+    {/each}
+  </ul>
+  {#snippet pending()}<p>Loading…</p>{/snippet}
+</svelte:boundary>
+```
+
+The root entry ships as an uncompiled `.svelte.js` module (compiled by your
+bundler's Svelte plugin, the standard Svelte-library convention — the package
+carries a `svelte` export condition so the plugin picks it up). It requires
+Svelte 5.40+: the hooks are runes, and the runtime context rides Svelte's
+`createContext`. `@thomasfosterau/legation-svelte/kit` is rune-free and server-side, so
+importing it pulls none of this in.
+
+## SvelteKit
+
+`@thomasfosterau/legation-svelte/kit` adds what SvelteKit shapes: the client-group cookie, an
+SSR snapshot for a server `load`, and the snapshot-hydrated Client boot. The
+hydration itself is core (`Hydration` in `@thomasfosterau/legation`) and the wiring is
+`Client.make` — this subpath is the framework's share of it, nothing more.
+It works with SvelteKit 2 and 3. The samples below import app modules through
+Kit 2's `$lib` alias. Kit 3 removes `$lib` in favour of a Node subpath import
+declared in the app's `package.json` (`"imports": { "#lib/*": "./src/lib/*" }`),
+so there write `#lib/domain.js` instead; or keep `$lib` with the (deprecated)
+`alias: { $lib: "src/lib" }` option in the SvelteKit config.
+
+The SSR model (see `Hydration` in `@thomasfosterau/legation`): each server render runs
+a **request-scoped engine** against the app's sync server, under the
+**browser's client group id**, and ships the dehydrated snapshot (rows +
+CVR cookie) in the page data. The client hydrates the snapshot into its
+durable store **only when the store is empty** — a repeat visit's rows,
+cookie, and journalled offline mutations are all fresher — and the first
+client pull continues the CVR conversation where the server left off: no
+refetch, no reset.
+
+### Server
+
+```ts
+// +page.server.ts — with @thomasfosterau/effect-sveltekit's serverLoad (or any
+// Effect-based load), the app's sync server provided as ServerHandler.
+import { Effect } from "effect";
+import { loadSnapshot } from "@thomasfosterau/legation-svelte/kit";
+import { allProducts, nodes } from "$lib/domain";
+
+export const load = serverLoad((event) =>
+  Effect.gen(function* () {
+    const { snapshot, clientGroupId } = yield* loadSnapshot(event.cookies, {
+      nodes,
+      reads: [allProducts],
+    });
+    return { snapshot, clientGroupId };
+  })
+);
+```
+
+- **`clientGroupId(cookies, options?)`** — read-or-mint the browser's client
+  group id (a plain, non-`httpOnly` cookie; it carries no authority — identity
+  is resolved server-side via `IdentityResolver`).
+- **`loadSnapshot(cookies, { nodes, reads })`** — resolve the group id and
+  produce the page's snapshot over a request-scoped engine (a thin wrapper of
+  core's `Hydration.snapshot`).
+
+### Client
+
+```ts
+// $lib/engine.ts — boot once, hand the runtime to the hooks.
+import { clientRuntime } from "@thomasfosterau/legation-svelte/kit";
+import { IndexedDbClientStore } from "@thomasfosterau/legation-browser";
+import { Identity } from "@thomasfosterau/legation";
+import { mutations, nodes, shellReads } from "$lib/domain";
+
+export const boot = (data: {
+  snapshot: Snapshot;
+  clientGroupId: string;
+  identity: Identity.Fingerprint;
+}) =>
+  clientRuntime({
+    nodes,
+    mutations,
+    clientGroupId: data.clientGroupId,
+    store: IndexedDbClientStore.layerWindow({ identity: data.identity }),
+    transport: rpcTransportLayer,
+    snapshot: data.snapshot,
+    subscribe: shellReads,
+  });
+```
+
+> **Pass an `identity`.** A durable replica belongs to exactly one resolved
+> identity, and an identity change is a reset, not a rebase (CONTEXT.md,
+> "Identity boundary"). Without it, a multi-tenant app on a shared device
+> boots the next person onto the last person's private rows — the replica is
+> the freshest thing on the machine, and nothing else in the engine has a
+> reason to distrust it. The value is an **opaque fingerprint** the app
+> computes — a hash of the session subject, never PII and never a credential —
+> and `Identity.anonymous` while nobody is signed in, so the first sign-in is
+> recognised as the one benign upgrade and keeps its warm replica. Call
+> `client.reset(fingerprint)` when the session changes mid-page.
+>
+> For a device with two regular users, `IndexedDbClientStore.layerNamespaced`
+> gives each principal its own replica instead, so switching back costs no
+> re-pull.
+
+```svelte
+<!-- +layout.svelte -->
+<script lang="ts">
+  import { fromRuntime, setClient } from "@thomasfosterau/legation-svelte";
+  const { data, children } = $props();
+  setClient(fromRuntime(boot(data)));
+</script>
+```
+
+Components render SSR markup from the snapshot and hydrate flash-free by
+seeding the rune hooks:
+
+```svelte
+<script lang="ts">
+  import { Hydration } from "@thomasfosterau/legation";
+  import { useQuery } from "@thomasfosterau/legation-svelte";
+  import { allProducts, nodes } from "$lib/domain";
+  const { data } = $props();
+  const products = useQuery(() => allProducts, {
+    initial: Hydration.rowsFor(data.snapshot, nodes, allProducts),
+  });
+</script>
+```
+
+### Form actions run Mutations
+
+A form action that can name the client group runs a named Mutation as one of
+that group's mutations (ADR-0030, amendment #215): the same definition the JS
+path journals, so a write is authored once. The mechanism is core
+(`server.mutate` in `@thomasfosterau/legation`); `/kit` reads the
+group cookie and the form's hidden fields, and gives the enhanced submit.
+
+Each rendered form carries a **form client**: a fresh id with mutation id
+`1`, minted by the page's `load` and rendered in hidden fields. A resubmission
+of the same rendered form is the same mutation, so the ledger applies it once
+and the action answers the original ruling.
+
+```ts
+// +page.server.ts
+import { Effect } from "effect";
+import {
+  FORM_CLIENT_FIELD,
+  FORM_MUTATION_FIELD,
+  RECEIPT_KEY,
+  formMutationTarget,
+  mintFormClient,
+  runFormMutation,
+} from "@thomasfosterau/legation-svelte/kit";
+import { addToCart } from "$lib/domain";
+import { server } from "$lib/server/sync";
+
+export const load = () => ({ form: mintFormClient() });
+
+export const actions = {
+  add: async ({ cookies, request }) => {
+    const data = await request.formData();
+    // The form layer (e.g. effect-forms) validates the fields first.
+    const args = { productId: String(data.get("productId")) };
+    const target = formMutationTarget(cookies, data);
+    if (target === undefined) {
+      // No client-group cookie: an out-of-band writer, as before.
+      return writeThroughApiAndBroadcast(args);
+    }
+    const receipt = await Effect.runPromise(runFormMutation(server, target, addToCart, args));
+    return { [RECEIPT_KEY]: receipt };
+  },
+};
+```
+
+```svelte
+<!-- +page.svelte -->
+<script lang="ts">
+  import { enhance } from "$app/forms";
+  import {
+    FORM_CLIENT_FIELD,
+    FORM_MUTATION_FIELD,
+    enhanceFormMutation,
+  } from "@thomasfosterau/legation-svelte/kit";
+  import { getClientRuntime } from "@thomasfosterau/legation-svelte";
+  import { addToCart } from "$lib/domain";
+  const { data } = $props();
+  const submit = enhanceFormMutation(getClientRuntime(), {
+    mutation: addToCart,
+    args: (form) => ({ productId: String(form.get("productId")) }),
+  });
+</script>
+
+<form method="POST" action="?/add" use:enhance={submit}>
+  <input type="hidden" name={FORM_CLIENT_FIELD} value={data.form.clientId} />
+  <input type="hidden" name={FORM_MUTATION_FIELD} value={data.form.mutationId} />
+  <button name="productId" value="p1">Add</button>
+</form>
+```
+
+- **No JS:** the form posts its rendered form client; the action runs the
+  Mutation and the page re-renders from the server.
+- **Enhanced:** each submit mints a fresh form client into the posted fields
+  and applies the Mutation's local handler to the optimistic overlay under it,
+  **without journaling it** (the action delivers it; a push would apply it
+  twice). On the receipt, `acknowledged` moves the effect to the unpulled
+  tail and `rejected` drops it (`onReceipt` gets the reason). The effect is
+  released only by the pull whose `lastMutationIds` covers the form client,
+  never on the action's response, exactly as for a pushed mutation. The
+  post-action `load` re-run is off by default (`refreshAll: false`); the
+  overlay already shows the write. Offline, the submit fails as the network
+  does (ADR-0030 open point 6).
+- Over a connected host (`Client.connect`, a mirror of a service-worker or
+  elected-host engine) the host's engine holds the overlay for every tab. A
+  host from a release that predates this answers the submit with a
+  `TransportError` rather than leaving it waiting.
+
+**One path per write.** A form-action Mutation and a façade write (#169,
+`@thomasfosterau/legation-jsonapi`) are two interception points for the same
+intent. Both name the mutation by id, neither fabricates a status the server
+did not give, and both release the optimistic effect only when a pull
+observes it. A façade write journals a plain `fetch` on the client and
+answers `202 pending`; a form-action Mutation runs on the server and answers
+the ruling. Write a submission through one of them, never both: the two
+deliveries carry different client ids, so the backend would apply the write
+twice.
+
+### No-JS baseline for other writers
+
+An action that cannot name the client group (no cookie, another service, a
+cron) stays an out-of-band writer (ADR-0019): commit the write through the
+app's API, then `server.broadcast({ collection })` for the touched
+collections so live subscribers pull. The next full-page render re-snapshots.
+
+## License
+
+MIT

package/dist/Runtime-DAQq0HCa.d.ts

@@ -0,0 +1,66 @@
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Option from "effect/Option";
+import { Client } from "@thomasfosterau/legation";
+import * as Schema from "effect/Schema";
+declare const ClientUnavailable_base: Schema.Class<ClientUnavailable, Schema.TaggedStruct<"ClientUnavailable", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/**
+ * A hook reached for the Client where none was set: `setClient(undefined)`,
+ * as on the server, where a hook renders from its `initial` seed and fails
+ * only when it needs the Client itself.
+ */
+declare class ClientUnavailable extends ClientUnavailable_base {}
+/**
+ * A runtime carrying the {@link Client.Client} — ADR-0022's one-per-thread
+ * object. The rune hooks run over it: reads are declarative `Query.Read`s
+ * and where they are answered (replica, host, server fallthrough) is the
+ * Client's business, never the component's.
+ */
+type ClientRuntime = ManagedRuntime.ManagedRuntime<Client.Client, never>;
+/**
+ * The Client an app hands to its component tree (#147): what {@link setClient}
+ * takes, and what {@link createClient} and {@link fromRuntime} build.
+ */
+interface ClientHandle {
+  /** The runtime the hooks run over, for Effect code that needs the Client directly. */
+  readonly runtime: ClientRuntime;
+  /**
+   * Release the Client: stop its sync loop and close its store and transport.
+   * Call it when the app tears down (a root layout's cleanup). Calling it again
+   * does nothing more.
+   */
+  readonly dispose: () => Promise<void>;
+}
+/**
+ * Build the Client a Svelte app boots with (#147): `Client.make`'s options in,
+ * a {@link ClientHandle} out, with no Effect runtime for the app to build. The
+ * Client is built on first use, so creating the handle does no work; with
+ * `transport: { url }` it is the standard remote setup.
+ */
+declare const createClient: (options: Client.MakeOptions) => ClientHandle;
+/**
+ * Wrap a runtime the app built itself, for the custom-layer path: an in-page
+ * server, a service-worker mirror, a simulated-offline transport.
+ */
+declare const fromRuntime: (runtime: ClientRuntime) => ClientHandle;
+/**
+ * Provide the Client to descendant components. Call once, high in the tree,
+ * before any rune hook. `undefined` (on the server, say) renders every hook
+ * from its `initial` seed; a hook that needs the Client then fails with
+ * {@link ClientUnavailable}.
+ */
+declare const setClient: (client?: ClientHandle) => void;
+/** The Client put in context by {@link setClient}: `None` when it was given none. */
+declare const getClient: () => Option.Option<ClientHandle>;
+/**
+ * Provide a Client runtime the app built itself: the escape hatch beside
+ * {@link setClient}, the same as `setClient(fromRuntime(runtime))`.
+ */
+declare const setClientRuntime: (runtime: ClientRuntime) => void;
+/** Read the Client runtime put in context by {@link setClient} or {@link setClientRuntime}. */
+declare const getClientRuntime: () => ClientRuntime;
+export { getClient as a, setClientRuntime as c, fromRuntime as i, ClientUnavailable as l, ClientRuntime as n, getClientRuntime as o, createClient as r, setClient as s, ClientHandle as t };
+//# sourceMappingURL=Runtime-DAQq0HCa.d.ts.map

package/dist/Runtime-DAQq0HCa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Runtime-DAQq0HCa.d.ts","names":[],"sources":["../src/unavailable.ts","../src/Runtime.ts"],"mappings":";;;;;;;WAcoB;;;;;;;cAFP,0BAA0B;;;;;;;KC0B3B,gBAAgB,eAAe,eAAe,OAAO;;;;;UAMhD;;WAEN,SAAS;;;;;;WAMT,eAAe;;;;;;;;cASb,eAAgB,SAAS,OAAO,gBAAc;;;;;cAW9C,cAAe,SAAS,kBAAgB;;;;;;;cAyBxC,YAAa,SAAS;;cAMtB,iBAAgB,OAAO,OAAO;;;;;cAO9B,mBAAoB,SAAS;;cAK7B,wBAAuB"}

package/dist/index.svelte.d.ts

@@ -0,0 +1,177 @@
+import { a as getClient, c as setClientRuntime, i as fromRuntime, l as ClientUnavailable, n as ClientRuntime, o as getClientRuntime, r as createClient, s as setClient, t as ClientHandle } from "./Runtime-DAQq0HCa.js";
+import { Aggregate, Client, Query } from "@thomasfosterau/legation";
+import { AsyncResult } from "effect/reactivity";
+import { ClientEngine, MutationState, Undo } from "@thomasfosterau/legation/internal";
+/** A live result: `current` re-renders whatever reads it on every emission. */
+export interface Live<A, E = never> {
+  /**
+   * The current result. `Initial` until the first emission, then `Success`
+   * per emission; while re-subscribing after an input change the previous
+   * result is kept with `waiting: true` (stale-while-revalidate). An
+   * `initial` seed starts as a non-waiting `Success` — "we have data", no
+   * spinner over server-rendered content — until the first real emission.
+   */
+  readonly current: AsyncResult.AsyncResult<A, E>;
+  /**
+   * The awaitable view of the same result, for Async Svelte
+   * (`experimental.async`): pending until the first data arrives — so
+   * `await rows.promise` in a derived or template suspends the enclosing
+   * `<svelte:boundary>`'s `pending` snippet — then an already-resolved
+   * promise replaced on every emission (and on input change), so awaiting
+   * expressions re-run with fresh rows while Svelte keeps the previous UI
+   * on screen (stale-while-revalidate). A failed stream rejects it, which
+   * the boundary's `failed` snippet catches.
+   */
+  readonly promise: Promise<A>;
+}
+/** Options shared by the live hooks. */
+export interface LiveOptions<A> {
+  /**
+   * Seed `current` with a synchronous `Success` before the first emission —
+   * during SSR (where `$effect` never runs) this is what renders, and on the
+   * client it makes the first render match the server markup (no loading
+   * flash). Compute it from the rows the page's load already fetched.
+   */
+  readonly initial?: A;
+}
+/** The rows a read resolves to: node values with their included edges. */
+export type ResolvedRows = ReadonlyArray<Client.ResolvedRow>;
+/**
+ * Live result of a declarative read, re-subscribing when the thunk's
+ * reactive inputs change. `include`d edges resolve onto each row's
+ * `related`, windowed per the edge's declared order (ADR-0024). Observing
+ * IS subscribing: the read's windows are registered for the hook's
+ * lifetime through the Client's ledger.
+ *
+ * The thunk may return `undefined` to opt out (#141) — "nothing right now",
+ * for a read keyed on a selection that starts empty. No window is
+ * registered and no request is issued; `current` stays `Initial` rather
+ * than becoming a `Success` over zero rows, so an opted-out read stays
+ * distinguishable from one that legitimately matched nothing. The thunk
+ * stays reactive either way: flipping the condition subscribes/unsubscribes
+ * with the same stale-while-revalidate behaviour as any other input change.
+ */
+export declare const useQuery: (read: () => Query.Read | undefined, options?: LiveOptions<ResolvedRows>) => Live<ResolvedRows>;
+/** A live, growing connection over a read's root window (ADR-0024). */
+export interface Connection extends Live<ResolvedRows> {
+  /**
+   * Widen the window by one page. A no-op while a widen is still resolving
+   * or once {@link hasMore} is false — call it freely from a click handler.
+   */
+  readonly loadMore: () => void;
+  /**
+   * Whether another page may exist: `true` while the current window is
+   * saturated (it holds as many rows as it asked for). Reactive. At a dataset
+   * whose size is an exact multiple of the page size this stays `true` for one
+   * more `loadMore`, which then resolves empty and flips it `false` — the
+   * standard cost of limit-based paging without a separate total count.
+   */
+  readonly hasMore: boolean;
+  /** Whether a page (the first or a widen) is currently resolving. Reactive. */
+  readonly loading: boolean;
+  /** Collapse back to the first page. */
+  readonly reset: () => void;
+}
+/** Options for {@link useConnection}. */
+export interface ConnectionOptions extends LiveOptions<ResolvedRows> {
+  /** Rows per page — the window grows by this on each `loadMore`. Default 20. */
+  readonly pageSize?: number;
+}
+/**
+ * Connection-style paging over a read's root window: a live result that
+ * *grows* rather than jumping between detached pages. `loadMore` widens the
+ * one window by a page (ADR-0024 — "load more widens the subset"), so each
+ * page's rows accumulate and the previous ones stay on screen through the
+ * widen (stale-while-revalidate); the engine only ever syncs the current
+ * window, never the whole collection.
+ *
+ * Per-parent paging falls out of instantiating the hook per parent: scope
+ * the read's `where` to a parent id and give each parent its own
+ * `useConnection` (one per `{#each parents}` row), and each parent's list
+ * pages independently, with its own `hasMore` and window. The read thunk
+ * stays reactive — when its base (collection/where/order/include) changes the
+ * connection re-bases to the first page automatically; the window it owns
+ * (`first`/`after`) is ignored on the passed read.
+ *
+ * ```svelte
+ * const reviews = useConnection(() => productReviews(id), { pageSize: 10 });
+ * // {#each await reviews.promise as row (row.value.id)} … {/each}
+ * // <button onclick={reviews.loadMore} disabled={!reviews.hasMore}>More</button>
+ * ```
+ *
+ * The read thunk may return `undefined` to opt out (#141): no window is
+ * registered and no request issued, `current` stays `Initial`, and paging
+ * state (`hasMore`/`loading`) reads as idle until the thunk starts returning
+ * a read again.
+ *
+ * **Engine-level retargeting (#133).** When the read has no `include`d edges
+ * and the view is engine-backed (`ClientView.observeWindow` present — a
+ * `Mirror` has none, see `docs/observing-row-changes.md`), `loadMore`/`reset`
+ * widen or shrink the SAME open observation's window via
+ * `ClientEngine.observeWindow`'s `retarget` — reusing `LiveView`'s maintained
+ * order instead of tearing the stream down and resubscribing wider each page.
+ * The stream itself is still built once per *base* change (collection/where/
+ * order/include), exactly as before; only `pages` no longer forces a rebuild.
+ * A joined read, or a mirror-backed connection, falls back to the original
+ * resubscribe-per-page behavior, unchanged.
+ */
+export declare const useConnection: (read: () => Query.Read | undefined, options?: ConnectionOptions) => Connection;
+/**
+ * Live result of a named query (server-resolved), with reactive name/args.
+ * The thunk may return `undefined` to opt out (#141): see {@link useQuery}.
+ */
+export declare const useNamedQuery: (query: () => {
+  readonly name: string;
+  readonly args: unknown;
+} | undefined, options?: LiveOptions<ReadonlyArray<ClientEngine.LocalRow>>) => Live<ReadonlyArray<ClientEngine.LocalRow>>;
+/**
+ * Live aggregate over a read's root window (count/sum/min/max/avg). Local
+ * tier only — the aggregate sees the rows this client has synced. The read
+ * thunk may return `undefined` to opt out (#141): see {@link useQuery}.
+ */
+export declare const useAggregate: (read: () => Query.Read | undefined, aggregate: Aggregate.Aggregate, options?: LiveOptions<Aggregate.AggregateValue>) => Live<Aggregate.AggregateValue>;
+/**
+ * Live grouped aggregate over a read's root window, keyed by
+ * `String(row.value[groupBy])`. The read thunk may return `undefined` to
+ * opt out (#141): see {@link useQuery}.
+ */
+export declare const useAggregateGrouped: (read: () => Query.Read | undefined, aggregate: Aggregate.Aggregate, groupBy: string, options?: LiveOptions<Record<string, Aggregate.AggregateValue>>) => Live<Record<string, Aggregate.AggregateValue>>;
+/**
+ * A `mutate(mutation, args)` bound to the context Client, resolving on
+ * journal (the write is applied optimistically before the promise settles).
+ */
+export declare const useMutation: () => ((mutation: string, args: unknown) => Promise<void>);
+/**
+ * Like {@link useMutation}, but resolving with the mutation's authoritative
+ * outcome once the backend settles it.
+ */
+export declare const useMutationWithAck: () => ((mutation: string, args: unknown) => Promise<ClientEngine.MutationOutcome>);
+/**
+ * Reactive mutation-state list (#116) — TanStack Query's `useMutationState`
+ * analogue: every journaled mutation's current lifecycle state (`pending` →
+ * `acknowledged` | `rejected`), oldest-journaled first. Pass a `mutator`
+ * thunk to scope to one mutator (reactive, like {@link useQuery}'s `read`);
+ * omit it (or return `undefined`) for every mutation. Works identically over
+ * an owned engine and a connected host (ADR-0021) — the same states either
+ * way.
+ */
+export declare const useMutationState: (mutator?: () => string | undefined) => Live<ReadonlyArray<MutationState.MutationState>>;
+/** Live undo/redo availability plus the two commands. */
+export interface UndoControls {
+  /** Whether an undo is currently possible. Reactive. */
+  readonly canUndo: boolean;
+  /** Whether a redo is currently possible. Reactive. */
+  readonly canRedo: boolean;
+  /** Run the manager's `undo` (a no-op when nothing is undoable). */
+  readonly undo: () => Promise<void>;
+  /** Run the manager's `redo` (a no-op when nothing is redoable). */
+  readonly redo: () => Promise<void>;
+}
+/**
+ * Undo/redo over a manager's history as runes. Build one manager per client
+ * with `Undo.make(handle)` — a `Client` or a `ClientEngine` both work
+ * (issue #223) — and call this during component initialisation.
+ */
+export declare const useUndo: <E>(manager: Undo.UndoManager<E>) => UndoControls;
+export { ClientHandle, ClientRuntime, ClientUnavailable, createClient, fromRuntime, getClient, getClientRuntime, setClient, setClientRuntime };
+//# sourceMappingURL=index.svelte.d.ts.map

package/dist/index.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.svelte.d.ts","names":[],"sources":["../src/hooks.svelte.ts"],"mappings":";;;;;iBAyCiB,KAAK,GAAG;;;;;;;;WAQd,SAAS,YAAY,YAAY,GAAG;;;;;;;;;;;WAWpC,SAAS,QAAQ;;;iBAIX,YAAY;;;;;;;WAOlB,UAAU;;;YAIT,eAAe,cAAc,OAAO;;;;;;;;;;;;;;;;qBAyFnC,WACX,YAAY,MAAM,kBAClB,UAAU,YAAY,kBACrB,KAAK;;iBAYS,mBAAmB,KAAK;;;;;WAK9B;;;;;;;;WAQA;;WAEA;;WAEA;;;iBAIM,0BAA0B,YAAY;;WAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA+CE,gBACX,YAAY,MAAM,kBAClB,UAAU,sBACT;;;;;qBAyGU,gBACX;WAAwB;WAAuB;eAC/C,UAAU,YAAY,cAAc,aAAa,eAChD,KAAK,cAAc,aAAa;;;;;;qBAiBtB,eACX,YAAY,MAAM,kBAClB,WAAW,UAAU,WACrB,UAAU,YAAY,UAAU,oBAC/B,KAAK,UAAU;;;;;;qBAoBL,sBACX,YAAY,MAAM,kBAClB,WAAW,UAAU,WACrB,iBACA,UAAU,YAAY,eAAe,UAAU,qBAC9C,KAAK,eAAe,UAAU;;;;;qBAoBpB,qBAAoB,kBAAkB,kBAAkB;;;;;qBAUxD,4BACX,kBACA,kBACG,QAAQ,aAAa;;;;;;;;;;qBAiBb,mBACX,uCACC,KAAK,cAAc,cAAc;;iBAkBnB;;WAEN;;WAEA;;WAEA,YAAY;;WAEZ,YAAY;;;;;;;qBA4BV,UAAW,GAAG,SAAS,KAAK,YAAY,OAAK"}