@blujosi/rivetkit-svelte 2.1.3 → 2.2.1

package/README.md

@@ -474,7 +474,7 @@ count?.refetch();
 
 #### `createRivetKitHandler(opts)`
 
-Creates SvelteKit request handlers for all HTTP methods.
+Creates SvelteKit request handlers for all HTTP methods. Every incoming request to the catch-all route is forwarded to the RivetKit registry handler.
 
 ```typescript
 import { createRivetKitHandler } from "@blujosi/rivetkit-svelte/sveltekit";
@@ -483,6 +483,247 @@ export const { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS } =
   createRivetKitHandler({ isDev: true, registry, rivetSiteUrl: "http://localhost:5173" });
 ```
 
+**Options:**
+
+| Option | Type | Description |
+|---|---|---|
+| `registry` | `Registry` | Your RivetKit registry instance |
+| `isDev` | `boolean` | Enables auto-engine spawn and runner pool config |
+| `rivetSiteUrl` | `string?` | Base URL for the site. Falls back to `PUBLIC_RIVET_ENDPOINT` env var |
+| `headers` | `Record<string, string>?` | Static headers added to **every** request sent to the registry handler |
+| `getHeaders` | `(event: RequestEvent) => Record<string, string>?` | Dynamic per-request headers. Receives the full SvelteKit `RequestEvent` |
+
+#### Passing Custom Headers (Authentication, JWT Tokens, etc.)
+
+The `headers` and `getHeaders` options let you inject headers into every request forwarded to your RivetKit actors. This is essential for passing JWT tokens, session IDs, or any other authentication data from your SvelteKit application to your actors so they can verify and authorize requests.
+
+Since `getHeaders` receives the full SvelteKit `RequestEvent`, you have access to `locals`, `cookies`, `url`, `params`, and anything else set by your hooks or middleware — making it the ideal place to forward auth context.
+
+**Pass a JWT token from `locals` (set by your auth hook):**
+
+```typescript
+// src/routes/api/rivet/[...rest]/+server.ts
+import { createRivetKitHandler } from "@blujosi/rivetkit-svelte/sveltekit";
+import { dev } from "$app/environment";
+import { registry } from "$backend/registry";
+
+export const { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS } =
+  createRivetKitHandler({
+    isDev: !!dev,
+    registry,
+    rivetSiteUrl: "http://localhost:5173",
+    // Forward auth token from locals (populated in hooks.server.ts)
+    getHeaders: (event) => ({
+      "x-app-token": event.locals.token ?? "",
+    }),
+  });
+```
+
+Your actors can then read `x-app-token` from the incoming request headers to authenticate and authorize the caller.
+
+**Combine static and dynamic headers:**
+
+```typescript
+createRivetKitHandler({
+  isDev: !!dev,
+  registry,
+  rivetSiteUrl: "http://localhost:5173",
+  // Static headers — same on every request
+  headers: {
+    "x-api-version": "2",
+    "x-app-name": "my-app",
+  },
+  // Dynamic headers — per-request, from SvelteKit locals/cookies
+  getHeaders: (event) => ({
+    "x-app-token": event.locals.token ?? "",
+    "x-user-id": event.locals.user?.id ?? "",
+    "x-session-id": event.cookies.get("session_id") ?? "",
+  }),
+});
+```
+
+Static `headers` are applied first, then `getHeaders` — so dynamic headers can override static ones if they share the same key. Both are set on **every** request that passes through the handler.
+
+---
+
+## SSR → Live Query Transport
+
+`@blujosi/rivetkit-svelte` supports server-side rendering of actor data that seamlessly upgrades to live WebSocket subscriptions on the client — **zero loading flash, instant first paint, then real-time forever.**
+
+This uses SvelteKit's built-in [`transport` hook](https://svelte.dev/docs/kit/hooks#Universal-hooks-transport) to serialize actor query results across the SSR boundary.
+
+### How it works
+
+1. **`rivetLoad()`** in your `+page.ts` load function calls an actor action via stateless HTTP on the server
+2. SvelteKit's `transport` hook serializes the result across the SSR boundary
+3. On the client, `transport.decode` creates a live WebSocket subscription with the SSR data as initial state
+4. On client-side navigation, `rivetLoad()` detects the browser and creates the subscription directly
+5. Events from the actor push updates to the reactive query — no manual refresh needed
+
+### Setup
+
+#### 1. Add the transport hook
+
+```typescript
+// src/hooks.ts
+import { encodeRivetLoad, decodeRivetLoad } from "@blujosi/rivetkit-svelte/sveltekit"
+import { rivetClient } from "$lib/actor.client"
+
+export const transport = {
+  RivetLoadResult: {
+    encode: (value) => encodeRivetLoad(value),
+    decode: (encoded) => decodeRivetLoad(encoded, rivetClient),
+  },
+}
+```
+
+#### 2. Use `rivetLoad()` in your load function
+
+```typescript
+// src/routes/+page.ts
+import { rivetLoad } from "@blujosi/rivetkit-svelte/sveltekit"
+import { rivetClient } from "$lib/actor.client"
+
+export const load = async () => ({
+  count: await rivetLoad(rivetClient, {
+    actor: 'counter',
+    key: ['test-counter'],
+    action: 'getCount',
+    event: 'newCount',
+  })
+})
+```
+
+#### 3. Use the data in your component
+
+```svelte
+<!-- src/routes/+page.svelte -->
+<script lang="ts">
+  let { data } = $props()
+
+  // data.count is already a reactive RivetQueryResult
+  // It has SSR data immediately, then upgrades to live updates
+  const count = $derived(data.count.data)
+</script>
+
+{#if data.count.isLoading}
+  <p>Loading...</p>
+{:else}
+  <h1>Counter: {count}</h1>
+{/if}
+```
+
+That's it. The page renders with SSR data on first paint, SvelteKit preloads on link hover, and then the actor connection keeps data live in real-time.
+
+### `rivetLoad(client, options)`
+
+Fetch actor data for use in SvelteKit load functions. Dual-mode:
+
+- **Server (SSR):** calls the action via stateless HTTP, wraps result for transport
+- **Client (navigation):** calls action for initial data, then creates a live subscription immediately
+
+```typescript
+const result = await rivetLoad(rivetClient, {
+  actor: 'counter',
+  key: ['test-counter'],
+  action: 'getCount',
+  event: 'newCount',
+  args: [],                         // optional action arguments
+  params: { authToken: 'jwt-...' }, // optional connection params
+  transform: (current, incoming) => incoming, // optional transform
+})
+```
+
+**Options:**
+
+| Option | Type | Description |
+|---|---|---|
+| `actor` | `string` | Actor name from your registry |
+| `key` | `string \| string[]` | Unique key for the actor instance |
+| `action` | `string` | Action name to call for the initial value |
+| `event` | `string \| string[]` | Event name(s) to subscribe to for live updates |
+| `args` | `unknown[]?` | Optional arguments passed to the action |
+| `params` | `Record<string, string>?` | Optional connection parameters |
+| `createInRegion` | `string?` | Region to create the actor in |
+| `createWithInput` | `unknown?` | Input data for actor creation |
+| `transform` | `(current: T, incoming: unknown) => T?` | Transform incoming event data. Default: full replacement |
+
+**Returns:** `RivetQueryResult<T>` — a reactive object with:
+
+| Property | Type | Description |
+|---|---|---|
+| `data` | `T \| undefined` | The current value |
+| `isLoading` | `boolean` | `true` while loading |
+| `error` | `Error \| undefined` | Error, if any |
+| `isConnected` | `boolean` | Whether the live connection is active |
+
+### `encodeRivetLoad(value)` / `decodeRivetLoad(encoded, client, transform?)`
+
+Transport encode/decode functions for `src/hooks.ts`. Wire them into SvelteKit's `transport` hook to enable SSR → live query upgrade.
+
+```typescript
+// src/hooks.ts
+import { encodeRivetLoad, decodeRivetLoad } from "@blujosi/rivetkit-svelte/sveltekit"
+import { rivetClient } from "$lib/actor.client"
+
+export const transport = {
+  RivetLoadResult: {
+    encode: (value) => encodeRivetLoad(value),
+    decode: (encoded) => decodeRivetLoad(encoded, rivetClient),
+  },
+}
+```
+
+> **Note:** `decodeRivetLoad` accepts an optional third argument `transform` if you need to customize how event data is applied. By default, incoming event data fully replaces the current value.
+
+### Multiple queries in one load
+
+```typescript
+// src/routes/+page.ts
+export const load = async () => ({
+  count: await rivetLoad(rivetClient, {
+    actor: 'counter',
+    key: ['test-counter'],
+    action: 'getCount',
+    event: 'newCount',
+  }),
+  countDouble: await rivetLoad(rivetClient, {
+    actor: 'counter',
+    key: ['test-counter'],
+    action: 'getCountDouble',
+    event: 'newDoubleCount',
+  }),
+})
+```
+
+### Using with `useActor` for mutations
+
+SSR data gives you read access. For mutations (calling actions that change state), combine with `useActor`:
+
+```svelte
+<script lang="ts">
+  import { useActor } from "$lib";
+
+  let { data } = $props();
+
+  // Read: SSR data with live updates
+  const count = $derived(data.count.data);
+
+  // Write: useActor for action calls
+  const counterActor = useActor?.({
+    name: "counter",
+    key: ["test-counter"],
+  });
+
+  const increment = async () => {
+    await counterActor?.current?.connection?.increment(1);
+  };
+</script>
+
+<h1>Counter: {count}</h1>
+<button onclick={increment}>Increment</button>
+```
+
 ---
 
 ## Common Pitfalls

package/SKILL.md

@@ -0,0 +1,297 @@
+# @blujosi/rivetkit-svelte — Agent Skill
+
+> Svelte 5 integration for [RivetKit](https://rivet.dev). Reactive actor connections via runes, SvelteKit handler for serverless deployment, and SSR → live query transport.
+
+## Package entry points
+
+| Import path | Purpose |
+|---|---|
+| `@blujosi/rivetkit-svelte` | Client-side: `createClient`, `createRivetKit`, `createRivetKitWithClient`, `useActor` |
+| `@blujosi/rivetkit-svelte/sveltekit` | Server + SSR: `createRivetKitHandler`, `rivetLoad`, `encodeRivetLoad`, `decodeRivetLoad` |
+
+## Core concepts
+
+### Actor model
+RivetKit actors are persistent, stateful server-side entities. Each actor has:
+- **Actions** — stateless HTTP calls (request/response)
+- **Events** — real-time WebSocket broadcasts to subscribed clients
+- **State** — persisted per-instance, keyed by `name` + `key`
+
+### Registry
+A `registry` defines all available actors. Created via `setup({ use: { counter, chat, ... } })` from `rivetkit`. The `Registry` type flows through the entire system for type safety.
+
+### Client
+`Client<Registry>` is the typed RivetKit client. Created via `createClient<Registry>(endpoint)`. Works on both server and browser.
+
+---
+
+## API reference
+
+### `createClient<Registry>(url)`
+Creates a typed RivetKit client.
+
+```ts
+import { createClient } from "@blujosi/rivetkit-svelte";
+import type { Registry } from "$backend/registry";
+
+const client = createClient<Registry>("http://localhost:5173/api/rivet");
+```
+
+### `createRivetKitWithClient<Registry>(client)`
+Creates the `useActor` hook from an existing client.
+
+```ts
+import { createClient, createRivetKitWithClient } from "@blujosi/rivetkit-svelte";
+const client = createClient<Registry>(url);
+export const { useActor } = createRivetKitWithClient(client);
+```
+
+### `createRivetKit<Registry>(url)`
+Shorthand — creates both client and `useActor` in one call.
+
+```ts
+import { createRivetKit } from "@blujosi/rivetkit-svelte";
+export const { useActor } = createRivetKit<Registry>("http://localhost:5173/api/rivet");
+```
+
+### `useActor(options)`
+Connects to a RivetKit actor. Returns reactive state + event/query helpers. **Must be called at top-level of component script** (not inside `onMount`, `$effect`, or callbacks).
+
+```ts
+const actor = useActor({
+  name: "counter",
+  key: ["test-counter"],
+  params: {},              // optional connection params
+  createInRegion: "us-east-1", // optional
+  createWithInput: {},     // optional
+  enabled: true,           // optional, default true
+});
+```
+
+**Returned object:**
+
+| Property/Method | Description |
+|---|---|
+| `actor.current.connection` | Call actions: `actor.current.connection?.increment(1)` |
+| `actor.current.handle` | Low-level actor handle |
+| `actor.current.isConnected` | `boolean` — connection status |
+| `actor.current.isConnecting` | `boolean` — connecting in progress |
+| `actor.current.isError` | `boolean` — error state |
+| `actor.current.error` | `Error \| null` |
+| `actor.useEvent(name, handler)` | Subscribe to actor events (auto-cleanup) |
+| `actor.useQuery(opts)` | Live query: initial fetch + event-driven updates |
+| `actor.useActionQuery(opts)` | Action query: refetches on event (event = invalidation signal) |
+
+### `useEvent(eventName, handler)`
+Registers an event listener. **Call at top-level, not inside `$effect`.**
+
+```ts
+actor?.useEvent("newCount", (value: number) => {
+  count = value;
+});
+```
+
+### `useQuery(opts)`
+Reactive query — fetches initial value via action, then subscribes to event for live updates.
+
+```ts
+const count = actor?.useQuery({
+  action: "getCount",
+  event: "newCount",
+  initialValue: 0,
+  args: [],                // optional
+  transform: (current, incoming) => incoming, // optional
+});
+// count?.value, count?.isLoading, count?.error
+```
+
+**Default transform:** shallow merge for objects, full replacement for primitives/arrays.
+
+### `useActionQuery(opts)`
+Reactive query — fetches via action, re-fetches when event fires. Event data is **ignored** (pure invalidation signal). **Recommended for most use cases.**
+
+```ts
+const count = actor?.useActionQuery({
+  action: "getCount",
+  event: "newCount",         // or ["newCount", "countReset"]
+  initialValue: 0,
+  args: () => [filter, limit], // optional reactive args
+});
+// count?.value, count?.isLoading, count?.error, count?.refetch()
+```
+
+**`useActionQuery` vs `useQuery`:**
+- `useActionQuery` — event triggers action re-call, simpler, always consistent with server state
+- `useQuery` — event data is used directly via transform, better for high-frequency updates
+
+---
+
+## SvelteKit handler
+
+### `createRivetKitHandler(opts)`
+Creates SvelteKit request handlers for a catch-all API route.
+
+```ts
+// src/routes/api/rivet/[...rest]/+server.ts
+import { createRivetKitHandler } from "@blujosi/rivetkit-svelte/sveltekit";
+import { dev } from "$app/environment";
+import { registry } from "$backend/registry";
+
+export const { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS } =
+  createRivetKitHandler({
+    isDev: !!dev,
+    registry,
+    rivetSiteUrl: "http://localhost:5173",
+    headers: { "x-api-version": "2" },               // optional static headers
+    getHeaders: (event) => ({                         // optional dynamic headers
+      "x-app-token": event.locals.token ?? "",
+    }),
+  });
+```
+
+**Options:**
+
+| Option | Type | Description |
+|---|---|---|
+| `registry` | `Registry<any>` | Your RivetKit registry |
+| `isDev` | `boolean` | Auto-starts engine, configures runner pool |
+| `rivetSiteUrl` | `string?` | Base URL of the site |
+| `headers` | `Record<string, string>?` | Static headers on every request |
+| `getHeaders` | `(event: RequestEvent) => Record<string, string>?` | Dynamic per-request headers |
+
+---
+
+## SSR → Live query transport
+
+Server-render actor data that upgrades to live WebSocket on the client. Zero loading flash.
+
+### How it works
+1. `rivetLoad()` in `+page.ts` calls actor action via HTTP during SSR
+2. SvelteKit `transport` hook serializes the result across the SSR boundary
+3. On client, `transport.decode` upgrades to a live WebSocket subscription
+4. On client-side navigation, `rivetLoad()` creates the subscription directly
+5. Events push live updates — no polling
+
+### Setup
+
+**1. Transport hook (`src/hooks.ts`):**
+
+```ts
+import { encodeRivetLoad, decodeRivetLoad } from "@blujosi/rivetkit-svelte/sveltekit";
+import { rivetClient } from "$lib/actor.client";
+
+export const transport = {
+  RivetLoadResult: {
+    encode: (value) => encodeRivetLoad(value),
+    decode: (encoded) => decodeRivetLoad(encoded, rivetClient),
+  },
+};
+```
+
+**2. Load function (`+page.ts`):**
+
+```ts
+import { rivetLoad } from "@blujosi/rivetkit-svelte/sveltekit";
+import { rivetClient } from "$lib/actor.client";
+
+export const load = async () => ({
+  count: await rivetLoad(rivetClient, {
+    actor: "counter",
+    key: ["test-counter"],
+    action: "getCount",
+    event: "newCount",
+  }),
+});
+```
+
+**3. Component (`+page.svelte`):**
+
+```svelte
+<script lang="ts">
+  let { data } = $props();
+  const count = $derived(data.count.data);
+</script>
+
+{#if data.count.isLoading}
+  <p>Loading...</p>
+{:else}
+  <h1>Counter: {count}</h1>
+{/if}
+```
+
+### `rivetLoad(client, options)`
+
+| Option | Type | Description |
+|---|---|---|
+| `actor` | `string` | Actor name from registry |
+| `key` | `string \| string[]` | Actor instance key |
+| `action` | `string` | Action to call for initial data |
+| `event` | `string \| string[]` | Event(s) for live updates |
+| `args` | `unknown[]?` | Action arguments |
+| `params` | `Record<string, string>?` | Connection params |
+| `transform` | `(current, incoming) => T?` | Custom update transform |
+
+**Returns:** `RivetQueryResult<T>` — `{ data, isLoading, error, isConnected }`
+
+### `encodeRivetLoad(value)` / `decodeRivetLoad(encoded, client, transform?)`
+Transport encode/decode for `src/hooks.ts`. Decode accepts optional `transform` third argument.
+
+---
+
+## Client setup pattern
+
+```ts
+// src/lib/actor.client.ts
+import { createClient, createRivetKitWithClient } from "@blujosi/rivetkit-svelte";
+import type { Client } from "rivetkit/client";
+import { browser } from "$app/environment";
+import type { Registry } from "$backend/registry";
+import { PUBLIC_APP_URL } from "$env/static/public";
+
+const endpoint = browser
+  ? `${location.origin}/api/rivet`
+  : `${PUBLIC_APP_URL ?? "http://localhost:5173"}/api/rivet`;
+
+export const rivetClient: Client<Registry> = createClient<Registry>(endpoint);
+const { useActor } = createRivetKitWithClient(rivetClient);
+export { useActor };
+```
+
+> **Important:** `useActor` must only be called in the browser. Guard with `browser` check in components.
+
+---
+
+## Common pitfalls
+
+1. **Don't call `useActor` inside `onMount`** — runes need synchronous component setup:
+   ```ts
+   // BAD:  onMount(() => { const a = useActor(...) })
+   // GOOD: const a = browser ? useActor(...) : undefined
+   ```
+
+2. **Don't call `useEvent` inside `$effect`** — it manages its own effects internally. Wrapping it causes duplicate listeners.
+
+3. **Don't call `.connect()` on the connection** — connections are auto-managed. `.connect()` would send an RPC action named "connect" to the actor.
+
+4. **`useQuery` vs `useActionQuery`** — prefer `useActionQuery` for most cases. Use `useQuery` only when you need to use event payloads directly (high-frequency updates).
+
+5. **SSR client endpoint** — the client must resolve to a valid URL on both server and browser. Use `PUBLIC_APP_URL` env var for the server-side fallback.
+
+6. **Transport hook required for SSR** — `rivetLoad()` results must pass through the `transport` hook in `src/hooks.ts` to upgrade to live subscriptions on the client.
+
+---
+
+## File structure (typical SvelteKit app)
+
+```
+src/
+  hooks.ts                          # transport hook for SSR
+  lib/
+    actor.client.ts                 # client + useActor setup
+  routes/
+    api/rivet/[...rest]/+server.ts  # SvelteKit handler
+    +page.ts                        # load function with rivetLoad()
+    +page.svelte                    # component using reactive data
+backend/
+  registry.ts                       # actor definitions + registry
+```

package/dist/SKILL.md

@@ -0,0 +1,297 @@
+# @blujosi/rivetkit-svelte — Agent Skill
+
+> Svelte 5 integration for [RivetKit](https://rivet.dev). Reactive actor connections via runes, SvelteKit handler for serverless deployment, and SSR → live query transport.
+
+## Package entry points
+
+| Import path | Purpose |
+|---|---|
+| `@blujosi/rivetkit-svelte` | Client-side: `createClient`, `createRivetKit`, `createRivetKitWithClient`, `useActor` |
+| `@blujosi/rivetkit-svelte/sveltekit` | Server + SSR: `createRivetKitHandler`, `rivetLoad`, `encodeRivetLoad`, `decodeRivetLoad` |
+
+## Core concepts
+
+### Actor model
+RivetKit actors are persistent, stateful server-side entities. Each actor has:
+- **Actions** — stateless HTTP calls (request/response)
+- **Events** — real-time WebSocket broadcasts to subscribed clients
+- **State** — persisted per-instance, keyed by `name` + `key`
+
+### Registry
+A `registry` defines all available actors. Created via `setup({ use: { counter, chat, ... } })` from `rivetkit`. The `Registry` type flows through the entire system for type safety.
+
+### Client
+`Client<Registry>` is the typed RivetKit client. Created via `createClient<Registry>(endpoint)`. Works on both server and browser.
+
+---
+
+## API reference
+
+### `createClient<Registry>(url)`
+Creates a typed RivetKit client.
+
+```ts
+import { createClient } from "@blujosi/rivetkit-svelte";
+import type { Registry } from "$backend/registry";
+
+const client = createClient<Registry>("http://localhost:5173/api/rivet");
+```
+
+### `createRivetKitWithClient<Registry>(client)`
+Creates the `useActor` hook from an existing client.
+
+```ts
+import { createClient, createRivetKitWithClient } from "@blujosi/rivetkit-svelte";
+const client = createClient<Registry>(url);
+export const { useActor } = createRivetKitWithClient(client);
+```
+
+### `createRivetKit<Registry>(url)`
+Shorthand — creates both client and `useActor` in one call.
+
+```ts
+import { createRivetKit } from "@blujosi/rivetkit-svelte";
+export const { useActor } = createRivetKit<Registry>("http://localhost:5173/api/rivet");
+```
+
+### `useActor(options)`
+Connects to a RivetKit actor. Returns reactive state + event/query helpers. **Must be called at top-level of component script** (not inside `onMount`, `$effect`, or callbacks).
+
+```ts
+const actor = useActor({
+  name: "counter",
+  key: ["test-counter"],
+  params: {},              // optional connection params
+  createInRegion: "us-east-1", // optional
+  createWithInput: {},     // optional
+  enabled: true,           // optional, default true
+});
+```
+
+**Returned object:**
+
+| Property/Method | Description |
+|---|---|
+| `actor.current.connection` | Call actions: `actor.current.connection?.increment(1)` |
+| `actor.current.handle` | Low-level actor handle |
+| `actor.current.isConnected` | `boolean` — connection status |
+| `actor.current.isConnecting` | `boolean` — connecting in progress |
+| `actor.current.isError` | `boolean` — error state |
+| `actor.current.error` | `Error \| null` |
+| `actor.useEvent(name, handler)` | Subscribe to actor events (auto-cleanup) |
+| `actor.useQuery(opts)` | Live query: initial fetch + event-driven updates |
+| `actor.useActionQuery(opts)` | Action query: refetches on event (event = invalidation signal) |
+
+### `useEvent(eventName, handler)`
+Registers an event listener. **Call at top-level, not inside `$effect`.**
+
+```ts
+actor?.useEvent("newCount", (value: number) => {
+  count = value;
+});
+```
+
+### `useQuery(opts)`
+Reactive query — fetches initial value via action, then subscribes to event for live updates.
+
+```ts
+const count = actor?.useQuery({
+  action: "getCount",
+  event: "newCount",
+  initialValue: 0,
+  args: [],                // optional
+  transform: (current, incoming) => incoming, // optional
+});
+// count?.value, count?.isLoading, count?.error
+```
+
+**Default transform:** shallow merge for objects, full replacement for primitives/arrays.
+
+### `useActionQuery(opts)`
+Reactive query — fetches via action, re-fetches when event fires. Event data is **ignored** (pure invalidation signal). **Recommended for most use cases.**
+
+```ts
+const count = actor?.useActionQuery({
+  action: "getCount",
+  event: "newCount",         // or ["newCount", "countReset"]
+  initialValue: 0,
+  args: () => [filter, limit], // optional reactive args
+});
+// count?.value, count?.isLoading, count?.error, count?.refetch()
+```
+
+**`useActionQuery` vs `useQuery`:**
+- `useActionQuery` — event triggers action re-call, simpler, always consistent with server state
+- `useQuery` — event data is used directly via transform, better for high-frequency updates
+
+---
+
+## SvelteKit handler
+
+### `createRivetKitHandler(opts)`
+Creates SvelteKit request handlers for a catch-all API route.
+
+```ts
+// src/routes/api/rivet/[...rest]/+server.ts
+import { createRivetKitHandler } from "@blujosi/rivetkit-svelte/sveltekit";
+import { dev } from "$app/environment";
+import { registry } from "$backend/registry";
+
+export const { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS } =
+  createRivetKitHandler({
+    isDev: !!dev,
+    registry,
+    rivetSiteUrl: "http://localhost:5173",
+    headers: { "x-api-version": "2" },               // optional static headers
+    getHeaders: (event) => ({                         // optional dynamic headers
+      "x-app-token": event.locals.token ?? "",
+    }),
+  });
+```
+
+**Options:**
+
+| Option | Type | Description |
+|---|---|---|
+| `registry` | `Registry<any>` | Your RivetKit registry |
+| `isDev` | `boolean` | Auto-starts engine, configures runner pool |
+| `rivetSiteUrl` | `string?` | Base URL of the site |
+| `headers` | `Record<string, string>?` | Static headers on every request |
+| `getHeaders` | `(event: RequestEvent) => Record<string, string>?` | Dynamic per-request headers |
+
+---
+
+## SSR → Live query transport
+
+Server-render actor data that upgrades to live WebSocket on the client. Zero loading flash.
+
+### How it works
+1. `rivetLoad()` in `+page.ts` calls actor action via HTTP during SSR
+2. SvelteKit `transport` hook serializes the result across the SSR boundary
+3. On client, `transport.decode` upgrades to a live WebSocket subscription
+4. On client-side navigation, `rivetLoad()` creates the subscription directly
+5. Events push live updates — no polling
+
+### Setup
+
+**1. Transport hook (`src/hooks.ts`):**
+
+```ts
+import { encodeRivetLoad, decodeRivetLoad } from "@blujosi/rivetkit-svelte/sveltekit";
+import { rivetClient } from "$lib/actor.client";
+
+export const transport = {
+  RivetLoadResult: {
+    encode: (value) => encodeRivetLoad(value),
+    decode: (encoded) => decodeRivetLoad(encoded, rivetClient),
+  },
+};
+```
+
+**2. Load function (`+page.ts`):**
+
+```ts
+import { rivetLoad } from "@blujosi/rivetkit-svelte/sveltekit";
+import { rivetClient } from "$lib/actor.client";
+
+export const load = async () => ({
+  count: await rivetLoad(rivetClient, {
+    actor: "counter",
+    key: ["test-counter"],
+    action: "getCount",
+    event: "newCount",
+  }),
+});
+```
+
+**3. Component (`+page.svelte`):**
+
+```svelte
+<script lang="ts">
+  let { data } = $props();
+  const count = $derived(data.count.data);
+</script>
+
+{#if data.count.isLoading}
+  <p>Loading...</p>
+{:else}
+  <h1>Counter: {count}</h1>
+{/if}
+```
+
+### `rivetLoad(client, options)`
+
+| Option | Type | Description |
+|---|---|---|
+| `actor` | `string` | Actor name from registry |
+| `key` | `string \| string[]` | Actor instance key |
+| `action` | `string` | Action to call for initial data |
+| `event` | `string \| string[]` | Event(s) for live updates |
+| `args` | `unknown[]?` | Action arguments |
+| `params` | `Record<string, string>?` | Connection params |
+| `transform` | `(current, incoming) => T?` | Custom update transform |
+
+**Returns:** `RivetQueryResult<T>` — `{ data, isLoading, error, isConnected }`
+
+### `encodeRivetLoad(value)` / `decodeRivetLoad(encoded, client, transform?)`
+Transport encode/decode for `src/hooks.ts`. Decode accepts optional `transform` third argument.
+
+---
+
+## Client setup pattern
+
+```ts
+// src/lib/actor.client.ts
+import { createClient, createRivetKitWithClient } from "@blujosi/rivetkit-svelte";
+import type { Client } from "rivetkit/client";
+import { browser } from "$app/environment";
+import type { Registry } from "$backend/registry";
+import { PUBLIC_APP_URL } from "$env/static/public";
+
+const endpoint = browser
+  ? `${location.origin}/api/rivet`
+  : `${PUBLIC_APP_URL ?? "http://localhost:5173"}/api/rivet`;
+
+export const rivetClient: Client<Registry> = createClient<Registry>(endpoint);
+const { useActor } = createRivetKitWithClient(rivetClient);
+export { useActor };
+```
+
+> **Important:** `useActor` must only be called in the browser. Guard with `browser` check in components.
+
+---
+
+## Common pitfalls
+
+1. **Don't call `useActor` inside `onMount`** — runes need synchronous component setup:
+   ```ts
+   // BAD:  onMount(() => { const a = useActor(...) })
+   // GOOD: const a = browser ? useActor(...) : undefined
+   ```
+
+2. **Don't call `useEvent` inside `$effect`** — it manages its own effects internally. Wrapping it causes duplicate listeners.
+
+3. **Don't call `.connect()` on the connection** — connections are auto-managed. `.connect()` would send an RPC action named "connect" to the actor.
+
+4. **`useQuery` vs `useActionQuery`** — prefer `useActionQuery` for most cases. Use `useQuery` only when you need to use event payloads directly (high-frequency updates).
+
+5. **SSR client endpoint** — the client must resolve to a valid URL on both server and browser. Use `PUBLIC_APP_URL` env var for the server-side fallback.
+
+6. **Transport hook required for SSR** — `rivetLoad()` results must pass through the `transport` hook in `src/hooks.ts` to upgrade to live subscriptions on the client.
+
+---
+
+## File structure (typical SvelteKit app)
+
+```
+src/
+  hooks.ts                          # transport hook for SSR
+  lib/
+    actor.client.ts                 # client + useActor setup
+  routes/
+    api/rivet/[...rest]/+server.ts  # SvelteKit handler
+    +page.ts                        # load function with rivetLoad()
+    +page.svelte                    # component using reactive data
+backend/
+  registry.ts                       # actor definitions + registry
+```

package/dist/sveltekit/handler.server.d.ts

@@ -1,10 +1,15 @@
-import type { RequestHandler } from "@sveltejs/kit";
+import type { RequestEvent, RequestHandler } from "@sveltejs/kit";
 import type { Registry } from "rivetkit";
-export declare const createRivetKitHandler: (opts?: {
+interface RivetKitHandlerOpts {
     registry: Registry<any>;
     isDev: boolean;
     rivetSiteUrl?: string;
-}) => {
+    /** Static headers added to every request sent to the registry handler */
+    headers?: Record<string, string>;
+    /** Dynamic headers resolved per-request. Receives the full SvelteKit RequestEvent. */
+    getHeaders?: (event: RequestEvent) => Record<string, string> | Promise<Record<string, string>>;
+}
+export declare const createRivetKitHandler: (opts?: RivetKitHandlerOpts) => {
     GET: RequestHandler;
     POST: RequestHandler;
     PUT: RequestHandler;
@@ -13,3 +18,4 @@ export declare const createRivetKitHandler: (opts?: {
     HEAD: RequestHandler;
     OPTIONS: RequestHandler;
 };
+export {};

package/dist/sveltekit/handler.server.js

@@ -1,7 +1,7 @@
 import { getLogger } from "rivetkit/log";
 const _devRunnerVersion = Math.floor(Date.now() / 1000);
 const _logger = getLogger("driver-sveltekit");
-const handler = async (request, opts) => {
+const handler = async (request, event, opts) => {
     const _requestUrl = new URL(request.url);
     const rivetSiteUrl = opts?.rivetSiteUrl;
     if (!rivetSiteUrl) {
@@ -42,12 +42,25 @@ const handler = async (request, opts) => {
     const newRequest = new Request(newUrl, request);
     newRequest.headers.set("host", new URL(newUrl).host);
     newRequest.headers.set("accept-encoding", "application/json");
+    // Apply static headers
+    if (opts?.headers) {
+        for (const [key, value] of Object.entries(opts.headers)) {
+            newRequest.headers.set(key, value);
+        }
+    }
+    // Apply dynamic per-request headers
+    if (opts?.getHeaders) {
+        const dynamicHeaders = await opts.getHeaders(event);
+        for (const [key, value] of Object.entries(dynamicHeaders)) {
+            newRequest.headers.set(key, value);
+        }
+    }
     return await registry.handler(newRequest);
     // return fetch(newRequest, { method: request.method, redirect: "manual" })
 };
 export const createRivetKitHandler = (opts) => {
-    const requestHandler = async ({ request }) => {
-        return handler(request, opts);
+    const requestHandler = async (event) => {
+        return handler(event.request, event, opts);
     };
     return {
         GET: requestHandler,

package/dist/sveltekit/index.d.ts

@@ -1 +1,2 @@
-export * from './handler.server';
+export * from "./handler.server";
+export { decodeRivetLoad, encodeRivetLoad, type RivetLoadOptions, RivetLoadResult, type RivetQueryResult, rivetLoad, } from "./transport.svelte";

package/dist/sveltekit/index.js

@@ -1 +1,2 @@
-export * from './handler.server';
+export * from "./handler.server";
+export { decodeRivetLoad, encodeRivetLoad, RivetLoadResult, rivetLoad, } from "./transport.svelte";

package/dist/sveltekit/transport.svelte.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SSR bridge — rivetLoad() + transport encode/decode.
+ *
+ * On the server, rivetLoad fetches via a stateless RivetKit action call.
+ * On the client, transport.decode upgrades it to a live actor subscription.
+ * On client-side navigation, rivetLoad creates a live subscription directly.
+ */
+import type { AnyActorRegistry } from "@rivetkit/framework-base";
+import type { Client } from "rivetkit/client";
+/** Reactive query result returned by rivetLoad (after decode) and on client nav. */
+export interface RivetQueryResult<T = unknown> {
+    readonly data: T | undefined;
+    readonly isLoading: boolean;
+    readonly error: Error | undefined;
+    readonly isConnected: boolean;
+}
+export interface RivetLoadOptions<T = unknown> {
+    /** Actor name from the registry (e.g. 'counter'). */
+    actor: string;
+    /** Unique key for the actor instance. */
+    key: string | string[];
+    /** Action name to call for the initial value. */
+    action: string;
+    /** Arguments to pass to the action. */
+    args?: unknown[];
+    /** Event name(s) to subscribe to for live updates. */
+    event: string | string[];
+    /** Optional connection params (e.g. auth tokens). */
+    params?: Record<string, string>;
+    /** Optional region to create the actor in. */
+    createInRegion?: string;
+    /** Optional input data for actor creation. */
+    createWithInput?: unknown;
+    /** Transform incoming event data into the new value. Default: full replacement. */
+    transform?: (current: T, incoming: unknown) => T;
+}
+/** Marker class for transport.encode to recognize. */
+export declare class RivetLoadResult<T = unknown> {
+    readonly actorName: string;
+    readonly key: string | string[];
+    readonly action: string;
+    readonly args: unknown[];
+    readonly event: string | string[];
+    readonly data: T;
+    readonly params?: Record<string, string> | undefined;
+    readonly createInRegion?: string | undefined;
+    readonly createWithInput?: unknown | undefined;
+    readonly __rivetLoad = true;
+    constructor(actorName: string, key: string | string[], action: string, args: unknown[], event: string | string[], data: T, params?: Record<string, string> | undefined, createInRegion?: string | undefined, createWithInput?: unknown | undefined);
+}
+interface RivetLoadEncoded {
+    actorName: string;
+    key: string | string[];
+    action: string;
+    args: unknown[];
+    event: string | string[];
+    data: unknown;
+    params?: Record<string, string>;
+    createInRegion?: string;
+    createWithInput?: unknown;
+}
+/**
+ * Fetch actor data for use in SvelteKit load functions.
+ *
+ * - **Server (SSR):** calls the action via stateless HTTP, wraps the result in
+ *   a RivetLoadResult. transport.decode upgrades it to a live subscription on
+ *   the client.
+ * - **Client (navigation):** calls the action for initial data, then immediately
+ *   creates a live subscription via createDetachedActorQuery().
+ *
+ * ```ts
+ * // +page.ts
+ * export const load = async () => ({
+ *   count: await rivetLoad(rivetClient, {
+ *     actor: 'counter',
+ *     key: ['test-counter'],
+ *     action: 'getCount',
+ *     event: 'newCount',
+ *   })
+ * })
+ * ```
+ */
+export declare function rivetLoad<Registry extends AnyActorRegistry, T = unknown>(client: Client<Registry>, opts: RivetLoadOptions<T>): Promise<RivetQueryResult<T>>;
+/**
+ * Encode a RivetLoadResult for serialization across the SSR boundary.
+ * Uses duck-type check (`__rivetLoad`) instead of `instanceof` because
+ * Vite HMR can create separate class identities for the same module.
+ */
+export declare function encodeRivetLoad(value: unknown): false | RivetLoadEncoded;
+/**
+ * Decode a serialized RivetLoadResult into a live actor subscription.
+ * Uses createDetachedActorQuery — works outside component context.
+ */
+export declare function decodeRivetLoad<Registry extends AnyActorRegistry>(encoded: RivetLoadEncoded, client: Client<Registry>, transform?: (current: unknown, incoming: unknown) => unknown): RivetQueryResult<unknown>;
+export {};

package/dist/sveltekit/transport.svelte.js

@@ -0,0 +1,183 @@
+/**
+ * SSR bridge — rivetLoad() + transport encode/decode.
+ *
+ * On the server, rivetLoad fetches via a stateless RivetKit action call.
+ * On the client, transport.decode upgrades it to a live actor subscription.
+ * On client-side navigation, rivetLoad creates a live subscription directly.
+ */
+const IS_BROWSER = typeof globalThis.document !== "undefined";
+// ============================================================================
+// RivetLoadResult — the serializable container
+// ============================================================================
+/** Marker class for transport.encode to recognize. */
+export class RivetLoadResult {
+    actorName;
+    key;
+    action;
+    args;
+    event;
+    data;
+    params;
+    createInRegion;
+    createWithInput;
+    __rivetLoad = true;
+    constructor(actorName, key, action, args, event, data, params, createInRegion, createWithInput) {
+        this.actorName = actorName;
+        this.key = key;
+        this.action = action;
+        this.args = args;
+        this.event = event;
+        this.data = data;
+        this.params = params;
+        this.createInRegion = createInRegion;
+        this.createWithInput = createWithInput;
+    }
+}
+// ============================================================================
+// rivetLoad — for load functions
+// ============================================================================
+/**
+ * Fetch actor data for use in SvelteKit load functions.
+ *
+ * - **Server (SSR):** calls the action via stateless HTTP, wraps the result in
+ *   a RivetLoadResult. transport.decode upgrades it to a live subscription on
+ *   the client.
+ * - **Client (navigation):** calls the action for initial data, then immediately
+ *   creates a live subscription via createDetachedActorQuery().
+ *
+ * ```ts
+ * // +page.ts
+ * export const load = async () => ({
+ *   count: await rivetLoad(rivetClient, {
+ *     actor: 'counter',
+ *     key: ['test-counter'],
+ *     action: 'getCount',
+ *     event: 'newCount',
+ *   })
+ * })
+ * ```
+ */
+export async function rivetLoad(client, opts) {
+    const { actor: actorName, key, action, args = [], event, params, createInRegion, createWithInput, } = opts;
+    const normalizedKey = Array.isArray(key) ? key : [key];
+    // Get a stateless handle via ClientRaw.getOrCreate (dynamic name access)
+    const handle = client.getOrCreate(actorName, normalizedKey, {
+        params,
+        createInRegion,
+        createWithInput,
+    });
+    // Call the action by name via ActorHandleRaw.action
+    const data = await handle.action({
+        name: action,
+        args,
+    });
+    if (IS_BROWSER) {
+        // Client-side navigation: create live subscription immediately
+        return createDetachedActorQuery(client, opts, data);
+    }
+    // Server-side: wrap in RivetLoadResult for transport serialization
+    return new RivetLoadResult(actorName, key, action, args, event, data, params, createInRegion, createWithInput);
+}
+// ============================================================================
+// Transport encode/decode — for hooks.ts
+// ============================================================================
+/**
+ * Encode a RivetLoadResult for serialization across the SSR boundary.
+ * Uses duck-type check (`__rivetLoad`) instead of `instanceof` because
+ * Vite HMR can create separate class identities for the same module.
+ */
+export function encodeRivetLoad(value) {
+    if (value instanceof RivetLoadResult ||
+        (value != null && typeof value === "object" && "__rivetLoad" in value)) {
+        const v = value;
+        return {
+            actorName: v.actorName,
+            key: v.key,
+            action: v.action,
+            args: v.args,
+            event: v.event,
+            data: v.data,
+            params: v.params,
+            createInRegion: v.createInRegion,
+            createWithInput: v.createWithInput,
+        };
+    }
+    return false;
+}
+/**
+ * Decode a serialized RivetLoadResult into a live actor subscription.
+ * Uses createDetachedActorQuery — works outside component context.
+ */
+export function decodeRivetLoad(encoded, client, transform) {
+    return createDetachedActorQuery(client, {
+        actor: encoded.actorName,
+        key: encoded.key,
+        action: encoded.action,
+        args: encoded.args,
+        event: encoded.event,
+        params: encoded.params,
+        createInRegion: encoded.createInRegion,
+        createWithInput: encoded.createWithInput,
+        transform,
+    }, encoded.data);
+}
+// ============================================================================
+// createDetachedActorQuery — live subscription outside component context
+// ============================================================================
+/**
+ * Create a live actor subscription outside of Svelte component context.
+ * Used by transport.decode (SSR hydration) and rivetLoad (client navigation).
+ *
+ * Uses raw $state signals — no $effect needed for lifecycle.
+ * Connects to the actor, subscribes to event(s), and keeps data reactive.
+ */
+function createDetachedActorQuery(client, opts, initialData) {
+    const { actor: actorName, key, event, params, createInRegion, createWithInput, transform = (_current, incoming) => incoming, } = opts;
+    let data = $state(initialData);
+    let isLoading = $state(false);
+    let error = $state(undefined);
+    let isConnected = $state(false);
+    const normalizedKey = Array.isArray(key) ? key : [key];
+    // Get a handle via ClientRaw.getOrCreate (dynamic name access)
+    const handle = client.getOrCreate(actorName, normalizedKey, {
+        params,
+        createInRegion,
+        createWithInput,
+    });
+    // Connect for event subscriptions
+    const conn = handle.connect();
+    // Track connection status
+    conn.onOpen(() => {
+        isConnected = true;
+    });
+    conn.onClose(() => {
+        isConnected = false;
+    });
+    conn.onError((err) => {
+        error = err instanceof Error ? err : new Error(String(err));
+    });
+    // Subscribe to event(s) for live updates
+    const events = Array.isArray(event) ? event : [event];
+    for (const evt of events) {
+        conn.on(evt, (...args) => {
+            const incoming = args.length === 1 ? args[0] : args;
+            data = transform(data, incoming);
+            isLoading = false;
+            error = undefined;
+        });
+    }
+    return {
+        get data() {
+            return data;
+        },
+        get isLoading() {
+            return isLoading;
+        },
+        get error() {
+            return error;
+        },
+        get isConnected() {
+            return isConnected;
+        },
+    };
+}

package/package.json

@@ -1,18 +1,19 @@
 {
 	"name": "@blujosi/rivetkit-svelte",
-	"version": "2.1.3",
+	"version": "2.2.1",
 	"scripts": {
 		"build": "vite build && npm run prepack",
 		"preview": "vite preview",
 		"prepare": "svelte-kit sync || echo ''",
-		"prepack": "svelte-kit sync && svelte-package && publint",
+		"prepack": "svelte-kit sync && svelte-package && cp SKILL.md dist/SKILL.md && publint",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
 	},
 	"files": [
 		"dist",
 		"!dist/**/*.test.*",
-		"!dist/**/*.spec.*"
+		"!dist/**/*.spec.*",
+		"SKILL.md"
 	],
 	"sideEffects": [
 		"**/*.css"