@lunora/svelte is the Svelte adapter for Lunora. It's a thin layer over the
framework-neutral @lunora/client, which owns the
WebSocket transport, subscription registry, offline queue, and delta-merge. The
adapter re-expresses that contract as Svelte stores you read with the $store
idiom. A live query is a readable store that re-emits on every server delta; an
optimistic mutation is a small bundle of stores plus an awaitable mutate.
The package is plain .ts over Svelte stores; no .svelte component compiler is
required to build or use it.
Preview. The Svelte adapter exists and exposes the same hydrate-then-subscribe handoff as React, but it is preview maturity and not yet proven end-to-end against a running app. The React adapter is the only one verified through the full live-loader path. See Bring your framework.
<!-- +layout.svelte — provide the client once at the root. -->
<script lang="ts">
import { LunoraClient } from "@lunora/client";
import { setLunoraClient } from "@lunora/svelte";
setLunoraClient(new LunoraClient({ url: import.meta.env.VITE_LUNORA_URL }));
</script>
<slot />Exports
| Symbol | Kind | Role |
|---|---|---|
setLunoraClient | function | Publish the shared LunoraClient on Svelte context. Call once high in the tree. |
getLunoraClient | function | Read the LunoraClient from context. Throws if none was set. |
query | function | Live query as a readable store ($store). Sharing one store shares one subscription. |
mutation | function | Optimistic mutation handle: { data, error, pending, mutate, reset } stores. |
action | function | Action handle: { data, error, pending, call, reset } stores. No optimistic options. |
hydratePreloaded | function | Seed a readable store synchronously from an SSR Preloaded token, then attach the socket. |
The table above lists the core handful. The package also exports the live
stores covered under Additional stores: subscription,
paginatedQuery, infiniteQuery, presence, liveTopic, rateLimit, auth,
connectionStatus, stream, mutator, flag, and flags. The agent helpers
are covered under Agent threads.
Re-exported types from @lunora/client: ArgsOf, ConnectionStatus,
FunctionReference, LunoraClient, MutationCallOptions, Preloaded,
ReturnOf, plus the adapter's own QueryStore, QueryStoreOptions,
MutationHandle, and ActionHandle.
Unlike React/Solid/Vue (which use useLunora), the Svelte provider accessor is
the idiomatic getLunoraClient. There is no <LunoraProvider> component; you
publish the client with setLunoraClient during component init.
Provider — setLunoraClient / getLunoraClient
setLunoraClient(client) publishes the LunoraClient on the Svelte component
context. Call it 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. This is the Svelte analogue of mounting React's
LunoraProvider.
getLunoraClient() reads it from the nearest ancestor and throws if no provider
was set, so a missing client fails loudly rather than as a later undefined
dereference. Most code never calls it directly; query / mutation /
hydratePreloaded resolve the ambient client for you.
query(fn, args, options?)
Opens a live query as a Svelte readable store. Read it with the $store
idiom and it stays current: a WebSocket subscription attaches the moment the store
gains its first subscriber, and the value re-emits on every server delta. The
store holds undefined until the first response lands. This is the Svelte
equivalent of React's useQuery.
The subscription is opened lazily (inside readable's start callback, on the
first $-read) and torn down when the last subscriber goes away, so a store
that's never read opens no socket and an unmounting component releases its
subscription. Sharing one store across several components shares a single
underlying subscription (the client de-dupes by (fn, args, shardKey)).
<script lang="ts">
import { query } from "@lunora/svelte";
import { api } from "$lib/_generated/api";
const messages = query(api.messages.list, { channelId: "general" });
</script>
<ul>
{#each $messages ?? [] as m (m._id)}
<li>{m.text}</li>
{/each}
</ul>query is overloaded: pass client explicitly as the first argument, or omit it
to resolve the ambient client published by setLunoraClient.
// Ambient client (default):
query(api.messages.list, { channelId });
// Explicit client:
query(client, api.messages.list, { channelId });options accepts { shardKey } to route to a specific shard when the target
function is .shardBy(...)-partitioned, and { onError }, a callback invoked
when the underlying subscription reports an error.
mutation(fn)
Creates an optimistic MutationHandle for a mutation reference, expressed as
readable stores plus an awaitable mutate:
interface MutationHandle<F> {
data: Readable<ReturnOf<F> | undefined>; // latest resolved value
error: Readable<Error | undefined>; // latest error
pending: Readable<boolean>; // true while any call from this handle is in flight (ref-counted)
mutate: (args, options?) => Promise<ReturnOf<F>>; // awaitable; resolves with the server value, rejects on failure
reset: () => void; // clear data/error back to idle
}pending is ref-counted across overlapping invocations of the same handle, so
read $pending to disable a button until the last concurrent call settles.
mutation is overloaded the same way as query: pass client explicitly or
omit it to use the ambient client.
<script lang="ts">
import { mutation } from "@lunora/svelte";
import { api } from "$lib/_generated/api";
const send = mutation(api.messages.send);
const { mutate, pending, error } = send;
</script>
<button disabled={$pending} on:click={() => mutate({ channelId: "general", text: "hi" })}>Send</button>
{#if $error}<p>{$error.message}</p>{/if}Optimistic updates
Optimistic updates stay client-owned and are passed per call in mutate's
options: the optimistic / optimisticUpdate options are applied and rolled
back by the client against the live query subscriptions, exactly as in the React
adapter. Any query / hydratePreloaded store reading the same data reflects
the change immediately and reverts on failure.
await mutate(
{ channelId, text },
{
optimisticUpdate: (store) => {
const current = store.getQuery(api.messages.list, { channelId }) ?? [];
store.setQuery(api.messages.list, { channelId }, [...current, draft]);
},
},
);action(fn)
Creates an ActionHandle for an action reference — the same shape as
MutationHandle, with call in place of mutate:
interface ActionHandle<F> {
data: Readable<ReturnOf<F> | undefined>; // latest resolved value
error: Readable<Error | undefined>; // latest error
pending: Readable<boolean>; // true while any call from this handle is in flight (ref-counted)
call: (args, options?) => Promise<ReturnOf<F>>; // awaitable; resolves with the server value, rejects on failure
reset: () => void; // clear data/error back to idle
}action is overloaded the same way as query and mutation: pass client
explicitly or omit it to use the ambient client.
<script lang="ts">
import { action } from "@lunora/svelte";
import { api } from "$lib/_generated/api";
const verify = action(api.commands.run);
const { call, pending, error } = verify;
</script>
<button disabled={$pending} on:click={() => call({ command: "lunora", args: ["verify"] })}>Verify</button>
{#if $error}<p>{$error.message}</p>{/if}Per-call options are { shardKey } only. Unlike mutation there are no
optimistic / optimisticUpdate options: an optimistic update patches the
subscription cache on the assumption a write will land, and an action is not a
write — it runs in the Worker, may call a third party, and has no declared
effect on any query.
Reactive loaders — hydratePreloaded
The server-side rendering (SSR) seed-to-live-store handoff, the Svelte equivalent of React's
usePreloadedQuery. Run the query on the server with preloadQuery (from
@lunora/svelte/server) in a SvelteKit +page.ts / +layout.ts load, hand the
serializable Preloaded token to the client, and hydratePreloaded seeds the
readable store synchronously with preloaded.value, so the first $store
read during hydration returns the server value with no loading flash and no
hydration mismatch. 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.
The preloaded value was read for whoever was signed in when the page loaded.
After a sign-out or user switch retires that identity, every hydratePreloaded
on the client — mounted then or later — stops using it and holds undefined
until the live value arrives, so the previous user's rows are never shown to the
next one. A same-user token refresh does not count as a switch. The store is
typed Readable<T | undefined> for that reason, like query.
Pass { onError } as the third argument (after the optional client) to observe
a subscription-scoped error the server pushes after hydration (a session expiry,
a row-level security (RLS) denial). Without it such an error is dropped and the store keeps
rendering the SSR snapshot as if it were live.
<script lang="ts">
import { hydratePreloaded } from "@lunora/svelte";
// `data.preloaded` came from a +page.ts load → preloadQuery
export let data;
const posts = hydratePreloaded(data.preloaded);
</script>
<ul>
{#each $posts ?? [] as p (p._id)}
<li>{p.title}</li>
{/each}
</ul>Pass client as a second argument to override the ambient client. On the server
readable's start callback never runs (no subscriber), so the store only holds
the seeded value and opens no socket; the token's value is the single source
of truth for the first paint.
@lunora/svelte/server
Server-side preload helpers, re-exported from @lunora/client/ssr, the
framework-neutral server contract shared by every adapter. This entry opens no
WebSocket and touches no browser globals, so it is safe to import from a
SvelteKit +page.ts / +layout.ts load.
// src/routes/posts/+page.ts
import { createServerClient, preloadQuery } from "@lunora/svelte/server";
import { api } from "$lib/_generated/api";
export async function load({ fetch }) {
// Forward SvelteKit's fetch so the session cookie rides along.
const client = createServerClient({ url: import.meta.env.VITE_LUNORA_URL, fetch });
const preloaded = await preloadQuery(client, api.posts.list, {});
return { preloaded };
}Exports: createServerClient, preloadQuery, serializePreloaded,
deserializePreloaded, preloadedQueryResult, getServerSession, plus the
Preloaded / ServerClientOptions / ServerSession types.
Single-worker composition
SvelteKit owns its Cloudflare build via @sveltejs/adapter-cloudflare, so
Lunora cannot own the worker entry; instead it injects its realtime plane
into the worker SvelteKit emits, via buildFrameworkWorker on the generated
app (withFrameworkWorker from @lunora/runtime
under the hood): the reserved /_lunora/* endpoints hit Lunora and
everything else delegates to SvelteKit. One worker, one deploy. See
Bring your framework for the full
composition and a working example.
Additional stores
Beyond query / mutation, the package exports the same store-shaped surface
the React adapter exposes as hooks. Each resolves the ambient client by default
or takes an explicit client as its first argument. Stores that own a timer or
listener (presence, rateLimit) return a teardown(); call it from
onDestroy.
subscription(fn, args, options?)
A raw live subscription as a pair of readable stores, { data, error }. data
holds the latest server push (undefined until the first), error holds the
last subscription error (a LunoraError carrying the server code when one was
sent). Pass "skip" as args to keep the handle but leave the
subscription dormant. Options: { shardKey, onError }.
<script lang="ts">
import { subscription } from "@lunora/svelte";
import { api } from "$lib/_generated/api";
const { data, error } = subscription(api.messages.live, { room: "general" });
</script>
{#if $error}<p>{$error.message}</p>{/if}
{#each $data ?? [] as m (m._id)}<li>{m.text}</li>{/each}paginatedQuery(fn, args, { initialNumItems, shardKey?, onError? })
A cursor-paginated live query. args is the function's args minus
paginationOpts (the framework supplies the cursor), or "skip". The handle is
{ results, status, isLoading, loadMore, error }: results is the flattened items
across every loaded page; status is "LoadingFirstPage" | "LoadingMore" | "CanLoadMore" | "Exhausted"; loadMore(n) appends the next page (a no-op unless
status === "CanLoadMore"); error holds the last page subscription error
(undefined when healthy) — a page that fails before its first frame is dropped,
status returns to "CanLoadMore", and loadMore(n) retries it. onError is
called with the same error.
<script lang="ts">
import { paginatedQuery } from "@lunora/svelte";
import { api } from "$lib/_generated/api";
const { results, status, loadMore } = paginatedQuery(api.messages.page, { room: "general" }, { initialNumItems: 20 });
</script>
{#each $results as m (m._id)}<li>{m.text}</li>{/each}
<button disabled={$status !== "CanLoadMore"} on:click={() => loadMore(20)}>Load more</button>infiniteQuery is the TanStack-Query-shaped variant: { pages, status, isLoading, hasNextPage, isFetchingNextPage, fetchNextPage, error }, where pages keeps
each loaded page as its own inner array.
presence(roomId, options)
Collaborative awareness: the client half of the server definePresence preset.
Drives a heartbeat mutation (on call, on an interval, and on tab re-focus) and
subscribes to the room's listPresent query. Options: { heartbeat, listPresent, sessionId?, data?, intervalMs?, shardKey? }, where heartbeat and listPresent
are api.* references. The handle is { present, sessionId, setData, teardown }.
Rooms are per tenant: the server files roomId under the caller's verified
orgId claim (or the app-wide tenant when there is none; definePresence({ tenant })
changes the rule), so the same room name in two organizations is two rooms.
<script lang="ts">
import { onDestroy } from "svelte";
import { presence } from "@lunora/svelte";
import { api } from "$lib/_generated/api";
const room = presence("room-42", {
heartbeat: api.presence.heartbeat,
listPresent: api.presence.listPresent,
data: { name: "Ada" },
});
// `room` is a plain handle, not a store — `present` is the readable on it.
const { present } = room;
onDestroy(room.teardown);
</script>
{#each $present ?? [] as p (p.userId)}<span>{p.data?.name}</span>{/each}liveTopic(topic, options?)
Follows one topic a defineLiveStream declares. Pass the reference
_generated/live.ts hands out; the stream's route is resolved against the
LunoraClient in context, and lastEvent and onEvent are typed by the payload
the topic declares. The readable holds { lastEvent, error }: the last payload
delivered on the topic, and the shard's refusal of the subscription. Nothing opens
until the first subscriber, and the subscription closes when the last one leaves,
so there is no teardown().
Call liveTopic while a component initialises: it reads the client with
getContext, which throws outside that window. topic is a reference or a
Readable of one, and a new topic resubscribes. options are onEvent,
onError, shardKey, sessionKey, and the transport tuning headers,
withCredentials, retryDelay and maxDelayMs. options may be a Readable as
well, e.g. to move to a new sessionKey on sign-out; a new onEvent or onError
is read at call time and does not resubscribe.
<script lang="ts">
import { liveTopic } from "@lunora/svelte";
import { writable } from "svelte/store";
import { live } from "../lunora/_generated/live";
export let postId: string;
// Call `liveTopic` once, during init (it reads the client from context), and hand it a store of the
// reference, so a new `postId` moves the same subscription to the new post's topic.
const topic = writable(live.posts.comments({ postId }));
$: topic.set(live.posts.comments({ postId }));
const comments = liveTopic(topic);
</script>
{#if $comments.lastEvent !== undefined}<p>New comment</p>{/if}stream(fn, args, options?)
A streaming query. It returns three readable stores, chunks, status and
error, plus a cancel() function. chunks holds every chunk the server pushes
so far, in arrival order, and it is the store that drives the stream: the stream
opens on the first subscriber to chunks and is cancelled when the last one
leaves. Subscribing only to status or error does not open it, so subscribe to
chunks (for example $chunks in the template) even when you only show the
status. Pass "skip" as
args to keep the stores connected but leave the stream dormant. fn must be a
stream reference, not a query.
mutator(handle)
Wraps a bound custom-mutator handle from @lunora/db's bindMutators as
{ mutate, pending, error, isError, reset } stores. pending is ref-counted
across overlapping calls to the same handle. Optimistic state is owned by the
bound handle, not by this wrapper.
flag(key, defaultValue) and flags(defaults)
flag returns a readable store of one feature flag, and flags returns a store
of an object of flags. Evaluation uses the caller's verified identity and never throws.
A provider error resolves the default. Pass an explicit client as the first
argument to override the ambient one.
rateLimit(config, options?)
A client-side mirror of a server 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, but the server stays authoritative. The
handle is { ok, disabled, retryAfter, check, consume, reset, teardown }, where
ok / disabled / retryAfter are readable stores; consume(count?) records a
local hit. Pass a stable config reference (a module constant). Options: { now?, tickMs? }.
<script lang="ts">
import { onDestroy } from "svelte";
import { rateLimit } from "@lunora/svelte";
const { disabled, retryAfter, consume, teardown } = rateLimit({ kind: "token bucket", rate: 5, period: 60_000 });
onDestroy(teardown);
</script>
<button disabled={$disabled} on:click={() => consume()}>Send {$disabled ? `(${$retryAfter}ms)` : ""}</button>auth(client?) and connectionStatus(client?)
auth returns { status, user, token, setToken }: status, user and token
are readable stores, and setToken(jwt) sets the token on the client after
sign-in. connectionStatus returns a readable store of the aggregate
live-socket state (idle → connecting → connected → offline), for driving
a connection indicator.
$status is the auth gate — "loading", "authenticated", "unauthenticated"
or "unreachable" (a credential is held but the identity endpoint could not be
reached; gates as authenticated). Branch on it, not on $user: $user is null
both when signed out and when a held credential's identity has not resolved, so
a $user gate shows the sign-in prompt to a signed-in user on an offline
reload. See the @lunora/client reference for the
table. authGate() returns { isAuthenticated, isLoading } derived from the
same status, when a boolean is all a template needs.
<script lang="ts">
import { auth, connectionStatus } from "@lunora/svelte";
const { setToken, status: authStatus, user } = auth();
const connection = connectionStatus();
</script>
{#if $authStatus === "loading"}Checking…{:else if $authStatus === "unauthenticated"}Signed out{:else}Signed in as {$user?.name}{/if}
<span data-status={$connection}>{$connection}</span>Agent threads
Each helper takes an optional leading client, like the stores above.
agent(options)returns anAgentHandlefor one agent thread. It exposesrun(input)to start a turn,cancel()to stop it, and the readable storespendingandstatus.agentChat(options)returns anAgentChatHandlefor the thread's chat. It exposes the approval controls, such asapprove(toolCallId, note?), and the liveapprovalGrantsstore. Pass the same app stream reference asstreamto receive live token deltas.agentState<T>(options)returns{ state, error }stores for the thread's live synced state. The caller declares the typeT.
Agent tool events — agentToolEvents(options)
Observes one agent thread's tool activity, separate from its chat
transcript: which tools the model called, what they returned, which are parked
on a human approval, and any in-flight ctx.reportProgress(...) updates.
options: { api, threadKey, stream?, limit? } — api is the generated api
(it reads api.agents.agentMessages), and stream is the same app stream
reference agentChat takes. Returns { events }, a readable store read with
$events. Like every store here it also accepts an explicit leading client
(agentToolEvents(client, options)) when there is no ambient one.
Each event discriminates on type:
type | Fields | Source |
|---|---|---|
call | toolCallId, toolName, input, seq | durable |
result | toolCallId?, toolName?, output, status?, seq | durable |
awaiting-approval | toolCallId?, toolName?, seq | durable |
progress | toolCallId, data | live stream |
Durable events come first, oldest first by seq, followed by the ephemeral
progress events for the in-flight turn. With no stream reference only the
durable lifecycle is surfaced. The array is rebuilt on every update — treat it
as derived, not identity-stable, and key rendered rows on toolCallId/seq.
<script lang="ts">
import { agentToolEvents } from "@lunora/svelte";
import { api } from "$lib/_generated/api";
export let threadKey: string;
const { events } = agentToolEvents({ api, stream: api.chat.liveEvents, threadKey });
</script>
<ol>
{#each $events as event, index (event.type === "progress" ? `p-${index}` : event.seq)}
<li>{event.type}</li>
{/each}
</ol>Voice agents — voiceAgent(options)
Opens a full-duplex voice call against a voice-enabled agent — the
api.agents.<name>Voice reference codegen emits. Microphone capture goes up the
agent's WebSocket, synthesized speech comes back down, and transcripts plus
barge-in are surfaced along the way.
options: { voice, threadKey, silenceThreshold?, silenceDurationMs?, interruptThreshold?, interruptChunks?, createMicrophone?, createSocket?, createSpeaker? }, with the usual optional leading client. threadKey is
shared with the agent's text turns, so a voice call continues the very same
conversation agentChat renders.
Returns { status, connected, transcript, interimTranscript, audioLevel, isMuted, error, startCall, endCall, sendText, toggleMute }, where every value
is a readable store read with $. status is
"idle" | "listening" | "thinking" | "speaking".
<script lang="ts">
import { onDestroy } from "svelte";
import { voiceAgent } from "@lunora/svelte";
import { api } from "$lib/_generated/api";
const call = voiceAgent({ threadKey: "thread-1", voice: api.agents.supportVoice });
const { audioLevel, status, transcript } = call;
onDestroy(call.endCall);
</script>
<button on:click={() => ($status === "idle" ? call.startCall() : call.endCall())}>
{$status === "idle" ? "Call" : "Hang up"}
</button>
<meter max={1} value={$audioLevel} />
<p>{$transcript}</p>Microphone and audio lifecycle
The part the type signature does not tell you:
- Nothing opens until
startCall(). Creating the handle touches neither the microphone nor the socket.startCallis what callsgetUserMedia, so it has to run from a user gesture — browsers block both the permission prompt andAudioContextresumption outside one. It is idempotent while a call is active, and a denied permission lands inerrorrather than throwing at the call site. - A failed turn drops its partial answer. When the model fails mid-answer (or its
stream is cut short), the text already streamed for that turn is cleared from
interimTranscriptanderroris set; the call returns tolistening. A retried turn starts its text from empty, never from the failed attempt's prefix. endCall()releases everything — the socket, the microphone tracks, and the Web Audio graph — and is idempotent. Svelte has no auto-dispose here. Unlike the other adapters nothing tears the call down for you, so call it yourself:onDestroy(call.endCall).audioLevelis the live input root mean square (RMS, 0–1). It drives a mic meter, and it is also what the heuristics read:silenceThreshold+silenceDurationMsdecide when an utterance auto-commits (defaults0.01/1200ms), andinterruptThreshold+interruptChunksdecide when the user barges in on the agent mid-sentence (defaults0.15/3consecutive chunks). These are room-dependent; tune them against real hardware rather than trusting the defaults.createMicrophone/createSpeaker/createSocketare injection seams for tests and non-DOM hosts. The defaults aregetUserMedia+ Web Audio +new WebSocket(url), so the primitive is inert (and mockable) anywhere those are missing.