@blujosi/rivetkit-svelte 2.2.0 → 2.3.2

package/README.md

@@ -24,6 +24,7 @@ npm i @blujosi/rivetkit-svelte rivetkit
 - **Svelte 5 Runes** — Built for `$state`, `$effect`, and `$derived`
 - **Real-time Actor Connections** — Connect to RivetKit actors with automatic state sync
 - **Event Handling** — `useEvent` with automatic cleanup
+- **CRUD Transforms** — Pre-built transform factories for managing lists via create/update/delete events
 - **Type Safety** — Full TypeScript support with registry type inference
 - **SSR Compatible** — Browser guard for SvelteKit SSR
 - **SvelteKit Handler** — Run RivetKit serverless inside your SvelteKit app
@@ -470,6 +471,139 @@ count?.refetch();
 | **Best for** | Most use-cases | High-frequency events where refetch would be wasteful |
 | **Refetch** | `.refetch()` available | Not available |
 
+---
+
+### CRUD Transforms (`@blujosi/rivetkit-svelte`)
+
+Pre-built `transform` factories for managing lists of items via create/update/delete events. Use with `useQuery` or `rivetLoad`.
+
+```typescript
+import {
+  crudTransform,
+  createTransform,
+  updateTransform,
+  deleteTransform,
+} from "@blujosi/rivetkit-svelte";
+```
+
+#### `crudTransform<T>(opts?)`
+
+A unified transform that handles all three CRUD operations in a single function. The actor broadcasts events wrapped in a `CrudEvent<T>`:
+
+```typescript
+// In the actor:
+c.broadcast("taskChanged", { type: "created", data: newTask });
+c.broadcast("taskChanged", { type: "updated", data: updatedTask });
+c.broadcast("taskChanged", { type: "deleted", data: deletedTask });
+```
+
+```svelte
+<script lang="ts">
+  import { crudTransform } from "@blujosi/rivetkit-svelte";
+
+  interface Task { id: string; title: string; done: boolean }
+
+  // With useQuery (client-side)
+  const tasks = actor?.useQuery({
+    action: "getTasks",
+    event: "taskChanged",
+    initialValue: [] as Task[],
+    transform: crudTransform<Task>({ key: "id" }),
+  });
+</script>
+```
+
+```typescript
+// With rivetLoad (SSR + live)
+const tasks = await rivetLoad(client, {
+  actor: "taskList",
+  key: ["my-list"],
+  action: "getTasks",
+  event: "taskChanged",
+  transform: crudTransform<Task>({ key: "id" }),
+});
+```
+
+If the incoming payload is **not** wrapped in `{ type, data }`, `crudTransform` falls back to an **upsert** — it updates the item if it exists, or appends it otherwise.
+
+**Options (`CrudTransformOptions<T>`):**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `key` | `keyof T \| (item: T) => unknown` | `"id"` | Property name or accessor used to uniquely identify items |
+
+**`CrudEvent<T>` shape:**
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | `"created" \| "updated" \| "deleted"` | The operation type |
+| `data` | `T` | The item (or key value for deletes) |
+
+#### Individual Transforms
+
+Use these when you have **separate events** for each operation:
+
+##### `createTransform<T>(opts?)`
+
+Appends the incoming item to the list. Duplicates (same key) are ignored.
+
+```typescript
+const tasks = actor?.useQuery({
+  action: "getTasks",
+  event: "taskCreated",
+  initialValue: [],
+  transform: createTransform<Task>({ key: "id" }),
+});
+```
+
+##### `updateTransform<T>(opts?)`
+
+Replaces the matching item in-place. If no match is found, the list is returned unchanged.
+
+```typescript
+const tasks = actor?.useQuery({
+  action: "getTasks",
+  event: "taskUpdated",
+  initialValue: [],
+  transform: updateTransform<Task>({ key: "id" }),
+});
+```
+
+##### `deleteTransform<T>(opts?)`
+
+Removes the matching item. Accepts either a full object or a raw key value.
+
+```typescript
+const tasks = actor?.useQuery({
+  action: "getTasks",
+  event: "taskDeleted",
+  initialValue: [],
+  transform: deleteTransform<Task>({ key: "id" }),
+});
+
+// The actor can broadcast just the key:
+c.broadcast("taskDeleted", taskId);
+// Or the full object:
+c.broadcast("taskDeleted", task);
+```
+
+#### Custom Key Functions
+
+For items keyed by something other than a single property:
+
+```typescript
+const items = actor?.useQuery({
+  action: "getItems",
+  event: "itemChanged",
+  initialValue: [],
+  transform: crudTransform<Item>({
+    key: (item) => `${item.type}:${item.slug}`,
+  }),
+});
+```
+
+---
+
 ### SvelteKit Exports (`@blujosi/rivetkit-svelte/sveltekit`)
 
 #### `createRivetKitHandler(opts)`

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/svelte/crud-transforms.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Generic CRUD transform factories for use with `useQuery` and `rivetLoad`.
+ *
+ * These produce `transform` functions that handle incoming create/update/delete
+ * events against a list of items, keyed by an identifier field.
+ *
+ * @example
+ * ```ts
+ * const tasks = await rivetLoad(client, {
+ *   actor: "taskList",
+ *   key: ["my-list"],
+ *   action: "getTasks",
+ *   event: "taskChanged",
+ *   transform: crudTransform<Task>({ key: "id" }),
+ * });
+ * ```
+ */
+/**
+ * An incoming event payload that carries a CRUD operation type.
+ *
+ * Actors should broadcast events in this shape:
+ * ```ts
+ * c.broadcast("todoListUpdate", { data: todo, type: "created" })
+ * ```
+ */
+export interface CrudEvent<T> {
+    data: T;
+    type: "created" | "updated" | "deleted";
+}
+/** Options shared by all CRUD transform factories. */
+export interface CrudTransformOptions<T> {
+    /**
+     * Property name (or accessor) used to uniquely identify items.
+     * Defaults to `"id"`.
+     */
+    key?: keyof T | ((item: T) => unknown);
+}
+/**
+ * Transform for a **create** event.
+ * - **Array:** appends the incoming item; duplicates (same key) are ignored.
+ * - **Single item:** replaces the current value with the incoming item.
+ */
+export declare function createTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: unknown) => C;
+/**
+ * Transform for an **update** event.
+ * - **Array:** replaces the matching item in-place; returns unchanged if no match.
+ * - **Single item:** replaces the current value with the incoming item.
+ */
+export declare function updateTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: unknown) => C;
+/**
+ * Transform for a **delete** event.
+ * - **Array:** removes the matching item. `incoming` can be the full item or just the key value.
+ * - **Single item:** returns the current value unchanged (cannot delete a scalar).
+ */
+export declare function deleteTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: unknown) => C;
+/**
+ * A single transform that handles create, update, and delete events.
+ *
+ * Incoming payloads must be a `CrudEvent<T>` with `{ data, type }`:
+ * ```ts
+ * { data: item, type: "created" }
+ * { data: item, type: "updated" }
+ * { data: item, type: "deleted" }
+ * ```
+ *
+ * Actors should broadcast in this shape:
+ * ```ts
+ * c.broadcast("todoListUpdate", { data: todo, type: "created" })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const users = todoActor?.useQuery({
+ *   action: "getUsers",
+ *   event: "userListUpdate",
+ *   initialValue: [],
+ *   transform: crudTransform<User>({ key: "id" }),
+ * });
+ * ```
+ */
+export declare function crudTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: CrudEvent<T>) => C;

package/dist/svelte/crud-transforms.js

@@ -0,0 +1,127 @@
+/**
+ * Generic CRUD transform factories for use with `useQuery` and `rivetLoad`.
+ *
+ * These produce `transform` functions that handle incoming create/update/delete
+ * events against a list of items, keyed by an identifier field.
+ *
+ * @example
+ * ```ts
+ * const tasks = await rivetLoad(client, {
+ *   actor: "taskList",
+ *   key: ["my-list"],
+ *   action: "getTasks",
+ *   event: "taskChanged",
+ *   transform: crudTransform<Task>({ key: "id" }),
+ * });
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function getKey(item, key) {
+    return typeof key === "function" ? key(item) : item[key];
+}
+// ---------------------------------------------------------------------------
+// Individual transforms
+// ---------------------------------------------------------------------------
+/**
+ * Transform for a **create** event.
+ * - **Array:** appends the incoming item; duplicates (same key) are ignored.
+ * - **Single item:** replaces the current value with the incoming item.
+ */
+export function createTransform(opts = {}) {
+    const keyProp = opts.key ?? "id";
+    return ((current, incoming) => {
+        const item = incoming;
+        if (Array.isArray(current)) {
+            const id = getKey(item, keyProp);
+            if (current.some((c) => getKey(c, keyProp) === id))
+                return current;
+            return [...current, item];
+        }
+        return item;
+    });
+}
+/**
+ * Transform for an **update** event.
+ * - **Array:** replaces the matching item in-place; returns unchanged if no match.
+ * - **Single item:** replaces the current value with the incoming item.
+ */
+export function updateTransform(opts = {}) {
+    const keyProp = opts.key ?? "id";
+    return ((current, incoming) => {
+        const item = incoming;
+        if (Array.isArray(current)) {
+            const id = getKey(item, keyProp);
+            const idx = current.findIndex((c) => getKey(c, keyProp) === id);
+            if (idx === -1)
+                return current;
+            const next = [...current];
+            next[idx] = item;
+            return next;
+        }
+        return item;
+    });
+}
+/**
+ * Transform for a **delete** event.
+ * - **Array:** removes the matching item. `incoming` can be the full item or just the key value.
+ * - **Single item:** returns the current value unchanged (cannot delete a scalar).
+ */
+export function deleteTransform(opts = {}) {
+    const keyProp = opts.key ?? "id";
+    return ((current, incoming) => {
+        if (Array.isArray(current)) {
+            const id = typeof incoming === "object" && incoming !== null
+                ? getKey(incoming, keyProp)
+                : incoming;
+            return current.filter((c) => getKey(c, keyProp) !== id);
+        }
+        return current;
+    });
+}
+// ---------------------------------------------------------------------------
+// Unified CRUD transform
+// ---------------------------------------------------------------------------
+/**
+ * A single transform that handles create, update, and delete events.
+ *
+ * Incoming payloads must be a `CrudEvent<T>` with `{ data, type }`:
+ * ```ts
+ * { data: item, type: "created" }
+ * { data: item, type: "updated" }
+ * { data: item, type: "deleted" }
+ * ```
+ *
+ * Actors should broadcast in this shape:
+ * ```ts
+ * c.broadcast("todoListUpdate", { data: todo, type: "created" })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const users = todoActor?.useQuery({
+ *   action: "getUsers",
+ *   event: "userListUpdate",
+ *   initialValue: [],
+ *   transform: crudTransform<User>({ key: "id" }),
+ * });
+ * ```
+ */
+export function crudTransform(opts = {}) {
+    const create = createTransform(opts);
+    const update = updateTransform(opts);
+    const del = deleteTransform(opts);
+    return ((current, incoming) => {
+        switch (incoming.type) {
+            case "created":
+                return create(current, incoming.data);
+            case "updated":
+                return update(current, incoming.data);
+            case "deleted":
+                return del(current, incoming.data);
+            default:
+                return current;
+        }
+    });
+}

package/dist/svelte/index.d.ts

@@ -1 +1,2 @@
+export * from "./crud-transforms";
 export * from "./rivet.svelte.js";

package/dist/svelte/index.js

@@ -1 +1,2 @@
+export * from "./crud-transforms";
 export * from "./rivet.svelte.js";

package/package.json

@@ -1,18 +1,19 @@
 {
 	"name": "@blujosi/rivetkit-svelte",
-	"version": "2.2.0",
+	"version": "2.3.2",
 	"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"