@lunora/svelte 0.0.0 → 1.0.0-alpha.2

package/dist/index.d.mts

@@ -0,0 +1,335 @@
+import { LunoraClient, User, ConnectionStatus, Preloaded, FunctionReference, ReturnOf, ArgsOf, MutationCallOptions, SubscriptionErrorCallback } from '@lunora/client';
+export type { ArgsOf, ConnectionStatus, FunctionReference, LunoraClient, MutationCallOptions, Preloaded, ReturnOf } from '@lunora/client';
+import { Readable } from 'svelte/store';
+import { PaginationStatus } from '@lunora/client/pagination';
+import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
+/**
+* Publish a {@link LunoraClient} on the Svelte component context so that
+* descendant components can read it with {@link getLunoraClient} (or implicitly,
+* via the default-client lookups inside `query`/`mutation`/`hydratePreloaded`).
+*
+* Call this once, high in the tree (typically your root `+layout.svelte` or
+* `App.svelte`), during component initialisation — `setContext` must run while
+* the component is being constructed, exactly like React's provider mounts once.
+* This is the Svelte analogue of mounting `LunoraProvider`.
+*/
+declare const setLunoraClient: (client: LunoraClient) => LunoraClient;
+/**
+* Read the {@link LunoraClient} published by {@link setLunoraClient} from the
+* nearest ancestor. Throws if no provider is mounted, mirroring `useLunora`'s
+* "must be used inside a LunoraProvider" guard so the failure is loud and
+* early rather than a confusing `undefined` deref later.
+*
+* Must be called during component initialisation (Svelte's `getContext`
+* constraint); the live stores returned by `query`/`hydratePreloaded` resolve
+* the client eagerly at call time for exactly this reason.
+*/
+declare const getLunoraClient: () => LunoraClient;
+interface AuthStore {
+  /** Set the auth token on the underlying `LunoraClient`. */
+  setToken: (token: string | null) => void;
+  /** Readable store of the auth token (`null` when signed out). */
+  token: Readable<string | null>;
+  /** Readable store of the resolved user (`null` when signed out or still loading). */
+  user: Readable<User | null>;
+}
+/**
+* Create a pair of Svelte readable stores tracking the auth token and the
+* resolved user identity. The stores are lazy: subscriptions open on the first
+* reader and close when the last unsubscribes. Calling `setToken(jwt)` after
+* sign-in refreshes both stores.
+*
+* Pass an explicit client to bypass the ambient context (useful in tests).
+*/
+declare const auth: (explicitClient?: ReturnType<typeof getLunoraClient>) => AuthStore;
+/** The shape held by a {@link connectionStatus} store: the latest aggregate live-socket status. */
+type ConnectionStatusStore = Readable<ConnectionStatus>;
+/**
+* Expose the client's aggregate live-socket status as a Svelte readable store.
+* Read it with the `$store` idiom (`{$status}`) and it stays current: the value
+* transitions through `idle` → `connecting` → `connected` → `offline` as
+* sockets open and drop — the Svelte equivalent of `@lunora/react`'s
+* `useConnectionStatus`. Use it to drive a connection indicator.
+*
+* The status listener attaches inside `readable`'s start callback (on the first
+* `$`-read / `.subscribe()`) and is released by the returned stop function when
+* the last subscriber goes away, so a store that's never read attaches nothing.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client published
+* by `setLunoraClient` (which must therefore be called during component init,
+* before this runs).
+*/
+declare const connectionStatus: (client?: LunoraClient) => ConnectionStatusStore;
+/**
+* Hydrate a query store from a {@link Preloaded} token produced by
+* `preloadQuery` during SSR, then keep it live — the reactive-loader handoff.
+*
+* The store is seeded **synchronously** with `preloaded.value`, so the very
+* first read (`$store` during hydration) returns the server value with no
+* loading flash and no hydration mismatch — there is no `undefined` window and
+* no refetch. When the store gains its first subscriber on the client, a live
+* WS subscription attaches and every subsequent delta re-emits, exactly like a
+* plain `query` store. This is the Svelte equivalent of React's
+* `usePreloadedQuery`.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client published
+* by `setLunoraClient`.
+*
+* Note on SSR: `readable`'s start callback only runs when the store is actually
+* subscribed (the browser), so on the server the store simply holds the seeded
+* value and opens no socket. The token's `value` is the single source of truth
+* for the first paint either way.
+*/
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>, client?: LunoraClient) => Readable<T>;
+/**
+* The reactive handle returned by {@link mutation} — the Svelte counterpart to
+* React's `useMutation`, re-expressed as stores you read with `$`. The surface
+* is identical across the Lunora adapters (`@lunora/solid`, `/vue`):
+* `data`/`error`/`pending` are readable stores and `mutate` is an awaitable.
+*/
+interface MutationHandle<F extends FunctionReference> {
+  /** The latest invocation's resolved value, or `undefined` before the first success. */
+  data: Readable<ReturnOf<F> | undefined>;
+  /** The latest invocation's error, or `undefined`. */
+  error: Readable<Error | undefined>;
+  /**
+  * Run the mutation. Resolves with the server result and rejects on failure
+  * (errors propagate — there is no swallowing). Optimistic updates passed in
+  * `options` are applied and rolled back by the client against the live query
+  * subscriptions, exactly as in the React adapter.
+  */
+  mutate: (args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
+  /**
+  * `true` while any invocation from this handle is in flight. Ref-counted, so
+  * overlapping calls compose and it only flips back to `false` once the last
+  * one settles. Read it with `$pending` in a component to disable a button.
+  */
+  pending: Readable<boolean>;
+  /** Clear `data`/`error` back to idle. */
+  reset: () => void;
+}
+/**
+* Create an optimistic {@link MutationHandle} for a mutation reference. The
+* Svelte counterpart to React's `useMutation`: returns
+* `{ data, error, pending, mutate, reset }` of readable stores plus an awaitable
+* `mutate`. The ref-counted pending + error-normalize orchestration is the
+* shared `createMutationRunner` from `@lunora/client`; only the stores are
+* adapter-specific.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client published
+* by `setLunoraClient`.
+*/
+declare function mutation<F extends FunctionReference>(function_: F): MutationHandle<F>;
+declare function mutation<F extends FunctionReference>(client: LunoraClient, function_: F): MutationHandle<F>;
+/** The args a paginated query exposes minus the framework-supplied page cursor. */
+type PaginatedArgs<F extends FunctionReference> = Omit<ArgsOf<F>, "paginationOpts">;
+/** The element type of the `page` array a paginated query returns. */
+type PageItemOf<F extends FunctionReference> = ReturnOf<F> extends {
+  page: (infer T)[];
+} ? T : unknown;
+interface PaginatedQueryOptions {
+  /** Page size for the first page (and the default for `loadMore`). */
+  initialNumItems: number;
+  shardKey?: string;
+}
+interface PaginatedQueryHandle<T> {
+  /** `true` while the first page or a `loadMore` page is in flight. */
+  isLoading: Readable<boolean>;
+  /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
+  loadMore: (numberItems: number) => void;
+  /** Flattened items across every loaded page, in order. */
+  results: Readable<T[]>;
+  status: Readable<PaginationStatus>;
+}
+interface InfiniteQueryOptions {
+  /** Page size for the first page (and the default for `fetchNextPage`). */
+  initialNumItems: number;
+  shardKey?: string;
+}
+interface InfiniteQueryHandle<T> {
+  /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
+  fetchNextPage: (numberItems?: number) => void;
+  /** `true` when the loaded tail reports it can load another page. */
+  hasNextPage: Readable<boolean>;
+  /** `true` while a `fetchNextPage` page (beyond the first) is in flight. */
+  isFetchingNextPage: Readable<boolean>;
+  /** `true` while the first page is in flight. */
+  isLoading: Readable<boolean>;
+  /** One inner array per loaded page, in order; unresolved pages are omitted. */
+  pages: Readable<T[][]>;
+  status: Readable<PaginationStatus>;
+}
+/**
+* Open a live paginated query as Svelte stores. The first page opens when
+* called; call `loadMore(n)` to append the next page. Results are flattened
+* across all loaded pages.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client from the
+* Svelte context.
+*/
+declare function paginatedQuery<F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: PaginatedQueryOptions): PaginatedQueryHandle<PageItemOf<F>>;
+declare function paginatedQuery<F extends FunctionReference>(client: LunoraClient, function_: F, args: "skip" | PaginatedArgs<F>, options: PaginatedQueryOptions): PaginatedQueryHandle<PageItemOf<F>>;
+/**
+* Open a live paginated query as Svelte stores, keeping each page as its own
+* inner array (TanStack-Query-style `fetchNextPage` / `hasNextPage` shape).
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client from the
+* Svelte context.
+*/
+declare function infiniteQuery<F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: InfiniteQueryOptions): InfiniteQueryHandle<PageItemOf<F>>;
+declare function infiniteQuery<F extends FunctionReference>(client: LunoraClient, function_: F, args: "skip" | PaginatedArgs<F>, options: InfiniteQueryOptions): InfiniteQueryHandle<PageItemOf<F>>;
+/**
+* `presence` — collaborative-awareness stores, the client half of the
+* `@lunora/server` `definePresence` preset.
+*
+* Drives the heartbeat mutation (on call, interval, and tab re-focus) and
+* subscribes to the live `listPresent` query for the given room.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client from the
+* Svelte context.
+*/
+/**
+* A heartbeat mutation reference: takes `{ roomId, sessionId, data? }`.
+*/
+type HeartbeatReference = FunctionReference<"mutation", {
+  data?: Record<string, unknown>;
+  roomId: string;
+  sessionId: string;
+}>;
+/**
+* A listPresent query reference: takes `{ roomId }` and returns the array of
+* present members.
+*/
+type ListPresentReference = FunctionReference<"query", {
+  roomId: string;
+}>;
+interface PresenceOptions<H extends HeartbeatReference, L extends ListPresentReference> {
+  /** Awareness blob for the first heartbeat (selection, cursor, name, color…). */
+  data?: Record<string, unknown>;
+  /** The `api.*` reference for the presence heartbeat mutation. */
+  heartbeat: H;
+  /** Heartbeat cadence in ms. Defaults to 10s. */
+  intervalMs?: number;
+  /** The `api.*` reference for the presence listPresent query. */
+  listPresent: L;
+  /**
+  * Stable id for this presence row. Defaults to a fresh per-mount id.
+  * Pass a user/connection id to control deduping across tabs.
+  */
+  sessionId?: string;
+  /** Forwarded to the heartbeat mutation / listPresent subscription when sharding by room. */
+  shardKey?: string;
+}
+interface PresenceHandle<L extends ListPresentReference> {
+  /** The present members for the room. `undefined` until the first push. */
+  present: Readable<ReturnOf<L> | undefined>;
+  /** This handle's session id. */
+  sessionId: string;
+  /** Replace the awareness `data` sent with subsequent heartbeats, and heartbeat immediately. */
+  setData: (data: Record<string, unknown> | undefined) => void;
+  /** Stop all heartbeats, remove the visibility listener, and unsubscribe. Call in `onDestroy`. */
+  teardown: () => void;
+}
+/**
+* Open a live presence handle.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client from the
+* Svelte context (requires calling inside a component's `&lt;script>` block or
+* inside a function called during component initialisation).
+*
+* Call `teardown()` when the component is destroyed to stop heartbeats and
+* remove the visibility listener (`onDestroy(handle.teardown)`).
+*/
+declare function presence<H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: PresenceOptions<H, L>): PresenceHandle<L>;
+declare function presence<H extends HeartbeatReference, L extends ListPresentReference>(client: LunoraClient, roomId: string, options: PresenceOptions<H, L>): PresenceHandle<L>;
+/** Options accepted by {@link query}. */
+interface QueryStoreOptions {
+  /** Called when the underlying subscription reports an error. */
+  onError?: SubscriptionErrorCallback;
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/**
+* The shape held by a {@link query} store: the latest server value (`undefined`
+* until the first response lands, mirroring React's `useQuery`).
+*/
+type QueryStore<F extends FunctionReference> = Readable<ReturnOf<F> | undefined>;
+/**
+* Open a live query as a Svelte readable store. Read it with the `$store`
+* idiom in a component (`{$messages}`) and it stays current: a WS subscription
+* attaches the moment the store gains its first subscriber and the value
+* re-emits on every server delta — the Svelte equivalent of React's `useQuery`.
+*
+* The subscription is opened lazily (inside `readable`'s start callback, on the
+* first `$`-read / `.subscribe()`) and torn down by the returned stop function
+* when the last subscriber goes away — so a store that's never read opens no
+* socket, and a component that unmounts releases its subscription. Sharing one
+* store across several components shares a single underlying subscription
+* (the `LunoraClient` de-dupes by `(fn, args, shardKey)`).
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client published
+* by `setLunoraClient` (which must therefore be called during component init,
+* before this runs).
+*/
+declare function query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: QueryStoreOptions): QueryStore<F>;
+declare function query<F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F>, options?: QueryStoreOptions): QueryStore<F>;
+interface RateLimitOptions {
+  /** Clock injection for tests. Defaults to `Date.now`. */
+  now?: () => number;
+  /**
+  * Re-evaluation cadence in milliseconds while throttled, so `retryAfter`
+  * ticks down and `disabled` flips back automatically. Defaults to `1000`.
+  */
+  tickMs?: number;
+}
+interface RateLimitHandle {
+  /** Would consuming `count` (default 1) succeed right now? Does not consume. */
+  check: (count?: number) => boolean;
+  /** Optimistically consume `count` (default 1) locally; mirrors the server algorithm. */
+  consume: (count?: number) => RateLimitStatus;
+  /** Readable store: `true` while a single unit cannot be consumed. */
+  disabled: Readable<boolean>;
+  /** Readable store: `true` while a single unit can be consumed. */
+  ok: Readable<boolean>;
+  /** Clear local accounting (e.g. after the server confirms a reset). */
+  reset: () => void;
+  /** Readable store: milliseconds until the next unit is available. `0` when `ok`. */
+  retryAfter: Readable<number>;
+  /** Stop the auto-tick interval. Call from `onDestroy` to prevent leaks. */
+  teardown: () => void;
+}
+/**
+* Client-side mirror of a rate limit for instant UX — disable a button or show
+* a countdown without a round-trip. It runs the same token-bucket / fixed-window
+* math as `@lunora/ratelimit` on the server, so the prediction agrees with the
+* authoritative check; the server remains the source of truth.
+*
+* `config` is read on every call; pass a stable reference (module constant).
+*
+* Call `teardown()` when the component is destroyed to stop the auto-tick
+* interval (`onDestroy(handle.teardown)`).
+*/
+declare const rateLimit: (config: RateLimitConfig, options?: RateLimitOptions) => RateLimitHandle;
+interface SubscriptionStoreOptions {
+  onError?: (error: Error) => void;
+  shardKey?: string;
+}
+interface SubscriptionHandle<T> {
+  /** Svelte readable store of the latest server-pushed value (`undefined` until the first push). */
+  data: Readable<T | undefined>;
+  /** Svelte readable store of the latest subscription error (`undefined` when healthy). */
+  error: Readable<Error | undefined>;
+}
+/**
+* Create a pair of Svelte readable stores that open a live subscription
+* against the Lunora backend. `data` updates on every server push; `error`
+* captures the last subscription error. Both stores are lazy: the subscription
+* opens on the first subscriber to `data` and tears down when it stops.
+*
+* Passing `"skip"` as `args` keeps the stores connected but the subscription
+* dormant (`data` stays `undefined`). Pass an explicit `client` as the first
+* argument to bypass the ambient context (useful in tests).
+*/
+declare function subscription<F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: SubscriptionStoreOptions): SubscriptionHandle<ReturnOf<F>>;
+declare function subscription<F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F> | "skip", options?: SubscriptionStoreOptions): SubscriptionHandle<ReturnOf<F>>;
+export { type AuthStore, type ConnectionStatusStore, type HeartbeatReference, type InfiniteQueryHandle, type InfiniteQueryOptions, type ListPresentReference, type MutationHandle, type PageItemOf, type PaginatedArgs, type PaginatedQueryHandle, type PaginatedQueryOptions, type PresenceHandle, type PresenceOptions, type QueryStore, type QueryStoreOptions, type RateLimitHandle, type RateLimitOptions, type SubscriptionHandle, type SubscriptionStoreOptions, auth, connectionStatus, getLunoraClient, hydratePreloaded, infiniteQuery, mutation, paginatedQuery, presence, query, rateLimit, setLunoraClient, subscription };

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+import { LunoraClient, User, ConnectionStatus, Preloaded, FunctionReference, ReturnOf, ArgsOf, MutationCallOptions, SubscriptionErrorCallback } from '@lunora/client';
+export type { ArgsOf, ConnectionStatus, FunctionReference, LunoraClient, MutationCallOptions, Preloaded, ReturnOf } from '@lunora/client';
+import { Readable } from 'svelte/store';
+import { PaginationStatus } from '@lunora/client/pagination';
+import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
+/**
+* Publish a {@link LunoraClient} on the Svelte component context so that
+* descendant components can read it with {@link getLunoraClient} (or implicitly,
+* via the default-client lookups inside `query`/`mutation`/`hydratePreloaded`).
+*
+* Call this once, high in the tree (typically your root `+layout.svelte` or
+* `App.svelte`), during component initialisation — `setContext` must run while
+* the component is being constructed, exactly like React's provider mounts once.
+* This is the Svelte analogue of mounting `LunoraProvider`.
+*/
+declare const setLunoraClient: (client: LunoraClient) => LunoraClient;
+/**
+* Read the {@link LunoraClient} published by {@link setLunoraClient} from the
+* nearest ancestor. Throws if no provider is mounted, mirroring `useLunora`'s
+* "must be used inside a LunoraProvider" guard so the failure is loud and
+* early rather than a confusing `undefined` deref later.
+*
+* Must be called during component initialisation (Svelte's `getContext`
+* constraint); the live stores returned by `query`/`hydratePreloaded` resolve
+* the client eagerly at call time for exactly this reason.
+*/
+declare const getLunoraClient: () => LunoraClient;
+interface AuthStore {
+  /** Set the auth token on the underlying `LunoraClient`. */
+  setToken: (token: string | null) => void;
+  /** Readable store of the auth token (`null` when signed out). */
+  token: Readable<string | null>;
+  /** Readable store of the resolved user (`null` when signed out or still loading). */
+  user: Readable<User | null>;
+}
+/**
+* Create a pair of Svelte readable stores tracking the auth token and the
+* resolved user identity. The stores are lazy: subscriptions open on the first
+* reader and close when the last unsubscribes. Calling `setToken(jwt)` after
+* sign-in refreshes both stores.
+*
+* Pass an explicit client to bypass the ambient context (useful in tests).
+*/
+declare const auth: (explicitClient?: ReturnType<typeof getLunoraClient>) => AuthStore;
+/** The shape held by a {@link connectionStatus} store: the latest aggregate live-socket status. */
+type ConnectionStatusStore = Readable<ConnectionStatus>;
+/**
+* Expose the client's aggregate live-socket status as a Svelte readable store.
+* Read it with the `$store` idiom (`{$status}`) and it stays current: the value
+* transitions through `idle` → `connecting` → `connected` → `offline` as
+* sockets open and drop — the Svelte equivalent of `@lunora/react`'s
+* `useConnectionStatus`. Use it to drive a connection indicator.
+*
+* The status listener attaches inside `readable`'s start callback (on the first
+* `$`-read / `.subscribe()`) and is released by the returned stop function when
+* the last subscriber goes away, so a store that's never read attaches nothing.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client published
+* by `setLunoraClient` (which must therefore be called during component init,
+* before this runs).
+*/
+declare const connectionStatus: (client?: LunoraClient) => ConnectionStatusStore;
+/**
+* Hydrate a query store from a {@link Preloaded} token produced by
+* `preloadQuery` during SSR, then keep it live — the reactive-loader handoff.
+*
+* The store is seeded **synchronously** with `preloaded.value`, so the very
+* first read (`$store` during hydration) returns the server value with no
+* loading flash and no hydration mismatch — there is no `undefined` window and
+* no refetch. When the store gains its first subscriber on the client, a live
+* WS subscription attaches and every subsequent delta re-emits, exactly like a
+* plain `query` store. This is the Svelte equivalent of React's
+* `usePreloadedQuery`.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client published
+* by `setLunoraClient`.
+*
+* Note on SSR: `readable`'s start callback only runs when the store is actually
+* subscribed (the browser), so on the server the store simply holds the seeded
+* value and opens no socket. The token's `value` is the single source of truth
+* for the first paint either way.
+*/
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>, client?: LunoraClient) => Readable<T>;
+/**
+* The reactive handle returned by {@link mutation} — the Svelte counterpart to
+* React's `useMutation`, re-expressed as stores you read with `$`. The surface
+* is identical across the Lunora adapters (`@lunora/solid`, `/vue`):
+* `data`/`error`/`pending` are readable stores and `mutate` is an awaitable.
+*/
+interface MutationHandle<F extends FunctionReference> {
+  /** The latest invocation's resolved value, or `undefined` before the first success. */
+  data: Readable<ReturnOf<F> | undefined>;
+  /** The latest invocation's error, or `undefined`. */
+  error: Readable<Error | undefined>;
+  /**
+  * Run the mutation. Resolves with the server result and rejects on failure
+  * (errors propagate — there is no swallowing). Optimistic updates passed in
+  * `options` are applied and rolled back by the client against the live query
+  * subscriptions, exactly as in the React adapter.
+  */
+  mutate: (args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
+  /**
+  * `true` while any invocation from this handle is in flight. Ref-counted, so
+  * overlapping calls compose and it only flips back to `false` once the last
+  * one settles. Read it with `$pending` in a component to disable a button.
+  */
+  pending: Readable<boolean>;
+  /** Clear `data`/`error` back to idle. */
+  reset: () => void;
+}
+/**
+* Create an optimistic {@link MutationHandle} for a mutation reference. The
+* Svelte counterpart to React's `useMutation`: returns
+* `{ data, error, pending, mutate, reset }` of readable stores plus an awaitable
+* `mutate`. The ref-counted pending + error-normalize orchestration is the
+* shared `createMutationRunner` from `@lunora/client`; only the stores are
+* adapter-specific.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client published
+* by `setLunoraClient`.
+*/
+declare function mutation<F extends FunctionReference>(function_: F): MutationHandle<F>;
+declare function mutation<F extends FunctionReference>(client: LunoraClient, function_: F): MutationHandle<F>;
+/** The args a paginated query exposes minus the framework-supplied page cursor. */
+type PaginatedArgs<F extends FunctionReference> = Omit<ArgsOf<F>, "paginationOpts">;
+/** The element type of the `page` array a paginated query returns. */
+type PageItemOf<F extends FunctionReference> = ReturnOf<F> extends {
+  page: (infer T)[];
+} ? T : unknown;
+interface PaginatedQueryOptions {
+  /** Page size for the first page (and the default for `loadMore`). */
+  initialNumItems: number;
+  shardKey?: string;
+}
+interface PaginatedQueryHandle<T> {
+  /** `true` while the first page or a `loadMore` page is in flight. */
+  isLoading: Readable<boolean>;
+  /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
+  loadMore: (numberItems: number) => void;
+  /** Flattened items across every loaded page, in order. */
+  results: Readable<T[]>;
+  status: Readable<PaginationStatus>;
+}
+interface InfiniteQueryOptions {
+  /** Page size for the first page (and the default for `fetchNextPage`). */
+  initialNumItems: number;
+  shardKey?: string;
+}
+interface InfiniteQueryHandle<T> {
+  /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
+  fetchNextPage: (numberItems?: number) => void;
+  /** `true` when the loaded tail reports it can load another page. */
+  hasNextPage: Readable<boolean>;
+  /** `true` while a `fetchNextPage` page (beyond the first) is in flight. */
+  isFetchingNextPage: Readable<boolean>;
+  /** `true` while the first page is in flight. */
+  isLoading: Readable<boolean>;
+  /** One inner array per loaded page, in order; unresolved pages are omitted. */
+  pages: Readable<T[][]>;
+  status: Readable<PaginationStatus>;
+}
+/**
+* Open a live paginated query as Svelte stores. The first page opens when
+* called; call `loadMore(n)` to append the next page. Results are flattened
+* across all loaded pages.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client from the
+* Svelte context.
+*/
+declare function paginatedQuery<F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: PaginatedQueryOptions): PaginatedQueryHandle<PageItemOf<F>>;
+declare function paginatedQuery<F extends FunctionReference>(client: LunoraClient, function_: F, args: "skip" | PaginatedArgs<F>, options: PaginatedQueryOptions): PaginatedQueryHandle<PageItemOf<F>>;
+/**
+* Open a live paginated query as Svelte stores, keeping each page as its own
+* inner array (TanStack-Query-style `fetchNextPage` / `hasNextPage` shape).
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client from the
+* Svelte context.
+*/
+declare function infiniteQuery<F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: InfiniteQueryOptions): InfiniteQueryHandle<PageItemOf<F>>;
+declare function infiniteQuery<F extends FunctionReference>(client: LunoraClient, function_: F, args: "skip" | PaginatedArgs<F>, options: InfiniteQueryOptions): InfiniteQueryHandle<PageItemOf<F>>;
+/**
+* `presence` — collaborative-awareness stores, the client half of the
+* `@lunora/server` `definePresence` preset.
+*
+* Drives the heartbeat mutation (on call, interval, and tab re-focus) and
+* subscribes to the live `listPresent` query for the given room.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client from the
+* Svelte context.
+*/
+/**
+* A heartbeat mutation reference: takes `{ roomId, sessionId, data? }`.
+*/
+type HeartbeatReference = FunctionReference<"mutation", {
+  data?: Record<string, unknown>;
+  roomId: string;
+  sessionId: string;
+}>;
+/**
+* A listPresent query reference: takes `{ roomId }` and returns the array of
+* present members.
+*/
+type ListPresentReference = FunctionReference<"query", {
+  roomId: string;
+}>;
+interface PresenceOptions<H extends HeartbeatReference, L extends ListPresentReference> {
+  /** Awareness blob for the first heartbeat (selection, cursor, name, color…). */
+  data?: Record<string, unknown>;
+  /** The `api.*` reference for the presence heartbeat mutation. */
+  heartbeat: H;
+  /** Heartbeat cadence in ms. Defaults to 10s. */
+  intervalMs?: number;
+  /** The `api.*` reference for the presence listPresent query. */
+  listPresent: L;
+  /**
+  * Stable id for this presence row. Defaults to a fresh per-mount id.
+  * Pass a user/connection id to control deduping across tabs.
+  */
+  sessionId?: string;
+  /** Forwarded to the heartbeat mutation / listPresent subscription when sharding by room. */
+  shardKey?: string;
+}
+interface PresenceHandle<L extends ListPresentReference> {
+  /** The present members for the room. `undefined` until the first push. */
+  present: Readable<ReturnOf<L> | undefined>;
+  /** This handle's session id. */
+  sessionId: string;
+  /** Replace the awareness `data` sent with subsequent heartbeats, and heartbeat immediately. */
+  setData: (data: Record<string, unknown> | undefined) => void;
+  /** Stop all heartbeats, remove the visibility listener, and unsubscribe. Call in `onDestroy`. */
+  teardown: () => void;
+}
+/**
+* Open a live presence handle.
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client from the
+* Svelte context (requires calling inside a component's `&lt;script>` block or
+* inside a function called during component initialisation).
+*
+* Call `teardown()` when the component is destroyed to stop heartbeats and
+* remove the visibility listener (`onDestroy(handle.teardown)`).
+*/
+declare function presence<H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: PresenceOptions<H, L>): PresenceHandle<L>;
+declare function presence<H extends HeartbeatReference, L extends ListPresentReference>(client: LunoraClient, roomId: string, options: PresenceOptions<H, L>): PresenceHandle<L>;
+/** Options accepted by {@link query}. */
+interface QueryStoreOptions {
+  /** Called when the underlying subscription reports an error. */
+  onError?: SubscriptionErrorCallback;
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/**
+* The shape held by a {@link query} store: the latest server value (`undefined`
+* until the first response lands, mirroring React's `useQuery`).
+*/
+type QueryStore<F extends FunctionReference> = Readable<ReturnOf<F> | undefined>;
+/**
+* Open a live query as a Svelte readable store. Read it with the `$store`
+* idiom in a component (`{$messages}`) and it stays current: a WS subscription
+* attaches the moment the store gains its first subscriber and the value
+* re-emits on every server delta — the Svelte equivalent of React's `useQuery`.
+*
+* The subscription is opened lazily (inside `readable`'s start callback, on the
+* first `$`-read / `.subscribe()`) and torn down by the returned stop function
+* when the last subscriber goes away — so a store that's never read opens no
+* socket, and a component that unmounts releases its subscription. Sharing one
+* store across several components shares a single underlying subscription
+* (the `LunoraClient` de-dupes by `(fn, args, shardKey)`).
+*
+* Pass `client` explicitly, or omit it to resolve the ambient client published
+* by `setLunoraClient` (which must therefore be called during component init,
+* before this runs).
+*/
+declare function query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: QueryStoreOptions): QueryStore<F>;
+declare function query<F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F>, options?: QueryStoreOptions): QueryStore<F>;
+interface RateLimitOptions {
+  /** Clock injection for tests. Defaults to `Date.now`. */
+  now?: () => number;
+  /**
+  * Re-evaluation cadence in milliseconds while throttled, so `retryAfter`
+  * ticks down and `disabled` flips back automatically. Defaults to `1000`.
+  */
+  tickMs?: number;
+}
+interface RateLimitHandle {
+  /** Would consuming `count` (default 1) succeed right now? Does not consume. */
+  check: (count?: number) => boolean;
+  /** Optimistically consume `count` (default 1) locally; mirrors the server algorithm. */
+  consume: (count?: number) => RateLimitStatus;
+  /** Readable store: `true` while a single unit cannot be consumed. */
+  disabled: Readable<boolean>;
+  /** Readable store: `true` while a single unit can be consumed. */
+  ok: Readable<boolean>;
+  /** Clear local accounting (e.g. after the server confirms a reset). */
+  reset: () => void;
+  /** Readable store: milliseconds until the next unit is available. `0` when `ok`. */
+  retryAfter: Readable<number>;
+  /** Stop the auto-tick interval. Call from `onDestroy` to prevent leaks. */
+  teardown: () => void;
+}
+/**
+* Client-side mirror of a rate limit for instant UX — disable a button or show
+* a countdown without a round-trip. It runs the same token-bucket / fixed-window
+* math as `@lunora/ratelimit` on the server, so the prediction agrees with the
+* authoritative check; the server remains the source of truth.
+*
+* `config` is read on every call; pass a stable reference (module constant).
+*
+* Call `teardown()` when the component is destroyed to stop the auto-tick
+* interval (`onDestroy(handle.teardown)`).
+*/
+declare const rateLimit: (config: RateLimitConfig, options?: RateLimitOptions) => RateLimitHandle;
+interface SubscriptionStoreOptions {
+  onError?: (error: Error) => void;
+  shardKey?: string;
+}
+interface SubscriptionHandle<T> {
+  /** Svelte readable store of the latest server-pushed value (`undefined` until the first push). */
+  data: Readable<T | undefined>;
+  /** Svelte readable store of the latest subscription error (`undefined` when healthy). */
+  error: Readable<Error | undefined>;
+}
+/**
+* Create a pair of Svelte readable stores that open a live subscription
+* against the Lunora backend. `data` updates on every server push; `error`
+* captures the last subscription error. Both stores are lazy: the subscription
+* opens on the first subscriber to `data` and tears down when it stops.
+*
+* Passing `"skip"` as `args` keeps the stores connected but the subscription
+* dormant (`data` stays `undefined`). Pass an explicit `client` as the first
+* argument to bypass the ambient context (useful in tests).
+*/
+declare function subscription<F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: SubscriptionStoreOptions): SubscriptionHandle<ReturnOf<F>>;
+declare function subscription<F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F> | "skip", options?: SubscriptionStoreOptions): SubscriptionHandle<ReturnOf<F>>;
+export { type AuthStore, type ConnectionStatusStore, type HeartbeatReference, type InfiniteQueryHandle, type InfiniteQueryOptions, type ListPresentReference, type MutationHandle, type PageItemOf, type PaginatedArgs, type PaginatedQueryHandle, type PaginatedQueryOptions, type PresenceHandle, type PresenceOptions, type QueryStore, type QueryStoreOptions, type RateLimitHandle, type RateLimitOptions, type SubscriptionHandle, type SubscriptionStoreOptions, auth, connectionStatus, getLunoraClient, hydratePreloaded, infiniteQuery, mutation, paginatedQuery, presence, query, rateLimit, setLunoraClient, subscription };