void 0.22.0 → 0.24.0

package/skills/void/docs/guide/type-safety.md

@@ -4,7 +4,7 @@ outline: deep
 
 # Type Safety
 
-Void provides end-to-end type safety across the stack. Types come from your source code and Drizzle schema, so you are not hand-writing or duplicating interfaces.
+Void infers types from your database schema, route handlers, and page loaders. When you change a field, TypeScript shows which queries, requests, and components need to change.
 
 ## The Type Pipeline
 
@@ -114,7 +114,7 @@ The `action()` helper gets the same type checking. See [Actions & Forms](./pages
 
 ## Serialization
 
-Handler return types are transformed via `Serialize<T>` so the client sees what actually arrives over the wire:
+The client types reflect JSON serialization through `Serialize<T>`:
 
 | Source type                       | Serialized type                                        |
 | --------------------------------- | ------------------------------------------------------ |
@@ -163,17 +163,6 @@ Extend the generated tsconfig in your project:
 }
 ```
 
-If your project already extends another config, use `void init --tsconfig` so Void can patch the file without dropping existing `files` or `compilerOptions.paths` entries. The resulting config may use TypeScript's multi-extends form:
-
-```json
-{
-  "extends": ["./tsconfig.base.json", "./.void/tsconfig.json"],
-  "compilerOptions": {
-    "types": ["void/env"]
-  }
-}
-```
-
-The `.void/tsconfig.json` uses `"files"` and `compilerOptions.paths` for generated declarations such as `routes.d.ts`, `db.d.ts`, and `queues.d.ts`. TypeScript inherits those fields, but `files` and `paths` are replaced rather than deeply merged when another config defines them. `void init --tsconfig` handles the common existing-config cases by adding Void's generated files and aliases directly to the root config when needed.
+If you already have a TypeScript config, run `void init --tsconfig` to add Void types while preserving your settings.
 
 Run `void prepare` in CI or after a fresh clone, or let `vite dev` / `vite build` generate the `.void/` files during normal app workflows.

package/skills/void/docs/guide/typed-fetch.md

@@ -4,7 +4,7 @@ outline: deep
 
 # Typed Fetch
 
-Void ships a typed `fetch` client that knows every route in your app. Import it from `void/client` and get autocomplete for paths, type-checked request bodies, and fully inferred response types.
+Import `fetch` from `void/client` for route autocomplete, checked request bodies, and inferred response types.
 
 ## Basic Usage
 
@@ -26,8 +26,6 @@ const user = await fetch('/api/users/:id', {
 });
 ```
 
-No type annotations needed. Everything is inferred from your route handlers.
-
 ## What Gets Type-Checked
 
 The client constrains every part of the request:
@@ -90,7 +88,7 @@ try {
 
 ## Isomorphic Fetch During SSR
 
-`fetch()` from `void/client` works during server-side rendering and inside route handlers without an HTTP round-trip. In the worker environment, it calls your Hono app directly through `app.fetch()` and skips the network entirely.
+`fetch()` also works in server-side rendering and route handlers. Calls to your app run without an HTTP round-trip.
 
 ```ts
 // src/main.ssr.tsx
@@ -108,6 +106,4 @@ export default defineRender(async (c, assetTags) => {
 });
 ```
 
-**Automatic header forwarding**: `cookie` and `authorization` headers from the incoming request are automatically forwarded to subrequests, so authentication context is preserved. If you pass these headers explicitly, your values take precedence.
-
-**How it works**: In the browser, `fetch()` uses the normal HTTP client. In the worker, Void redirects the import to a virtual module that calls `app.fetch()` directly using the Hono app instance. AsyncLocalStorage threads the outer request context so headers and `waitUntil()` work correctly.
+Server-side calls forward the incoming request's `cookie` and `authorization` headers. Explicit headers take precedence.

package/skills/void/docs/guide/websockets.md

@@ -8,11 +8,9 @@ outline: deep
 Typed WebSocket routes currently work in native Void apps. They aren't available in meta-framework mode yet.
 :::
 
-Create a `.ws.ts` route to add a typed WebSocket endpoint. Void runs each route instance in a Cloudflare Durable Object, which coordinates the clients connected to it. These routes require the Cloudflare target; Node.js, Bun, and Deno builds reject them.
+Create a `.ws.ts` route to send typed messages between your server and connected clients. Each route instance has its own Cloudflare Durable Object for shared state. WebSocket routes require the Cloudflare target.
 
-New WebSocket route classes use SQLite-backed Durable Objects on both deployment platforms.
-
-For example, a chat route at `/rooms/[id]` gives each room its own instance. Use it for chat, presence, collaborative documents, or notifications.
+For example, `/rooms/[id]` gives each chat room its own instance. Use it for chat, presence, collaborative documents, or notifications.
 
 ## Route files
 
@@ -115,6 +113,28 @@ export default defineWebSocket({
 });
 ```
 
+## Client
+
+Use `connect()` from `void/ws` on the client:
+
+```ts
+import { connect } from 'void/ws';
+
+const socket = connect('/chat/:room', {
+  params: { room: 'general' },
+});
+
+socket.on('message', (event) => {
+  if (event.type === 'chat.message') {
+    console.log(event.text);
+  }
+});
+
+socket.send({ type: 'chat.message', text: 'hello' });
+```
+
+`connect()` resolves relative URLs against the current origin and automatically uses `ws:` or `wss:`. It also buffers messages until the socket opens and reconnects by default.
+
 ## Typed messages
 
 Define schemas for messages sent by the client and server:
@@ -125,19 +145,11 @@ Define schemas for messages sent by the client and server:
 - `ctx.room.broadcast()`, `ctx.connection.send()`, and `ctx.socket.send()` are typed from `messages.server`
 - `connect()` infers route params, outgoing client messages, and incoming server messages from generated route types
 
-The default protocol is JSON events. Raw string or binary framing is not the primary API.
-
-## Ambient auth
+Messages are JSON events. Raw string and binary messages are not supported.
 
-WebSocket hooks use the same built-in session resolution as HTTP auth. When Void auth is enabled, `ctx.user` is available in:
+## Authentication
 
-- `onBeforeConnect`
-- `onConnect`
-- `onMessage`
-- `onClose`
-- `onRequest`
-
-This makes cookie-authenticated sockets work without re-parsing the session manually.
+When Void auth is enabled, every WebSocket hook receives the current user as `ctx.user`, or `null` for an anonymous connection. Use `onBeforeConnect` to reject unauthenticated clients.
 
 ## Hooks
 
@@ -149,6 +161,9 @@ Both `defineRoom()` and `defineWebSocket()` support:
 - `onClose(ctx, details)`: receives `{ code, reason, wasClean }`
 - `onRequest(ctx)`: handles ordinary HTTP requests to the same path
 
+Void completes the WebSocket close handshake automatically. Use `onClose` for application cleanup;
+you do not need to close the socket again in this hook.
+
 Every hook receives a context with:
 
 - `ctx.id`: deterministic route instance id
@@ -160,42 +175,55 @@ Every hook receives a context with:
 
 If a route does not define `onRequest()`, non-WebSocket requests return `426 Upgrade Required`.
 
-## Client
+## Move a route while keeping its state
 
-Use `connect()` from `void/ws` on the client:
+Before moving a deployed route, run `void info`. For `routes/chat/[room].ws.ts`, the output includes:
 
-```ts
-import { connect } from 'void/ws';
+```text
+To preserve this resource when moving its code, add this to 'defineRoom':
+  name: "chat-room",
+```
 
-const socket = connect('/chat/:room', {
-  params: { room: 'general' },
-});
+Add the displayed name to your existing definition:
 
-socket.on('message', (event) => {
-  if (event.type === 'chat.message') {
-    console.log(event.text);
-  }
+```ts
+export default defineRoom({
+  name: 'chat-room',
+  messages: { client: ClientMessage, server: ServerMessage },
+  // Keep your existing hooks.
 });
-
-socket.send({ type: 'chat.message', text: 'hello' });
 ```
 
-`connect()` resolves relative URLs against the current origin and automatically uses `ws:` or `wss:`. It also buffers messages until the socket opens and reconnects by default.
+Move the file to `routes/rooms/[room].ws.ts`, update clients to connect to `/rooms/:room`, and deploy normally. Keep the same parameter names and values: room `general` still uses its existing storage. The Worker class, binding, and migration history stay the same on both Cloudflare and Void platform deployments.
 
-## Constraints
+Both `defineRoom()` and `defineWebSocket()` accept optional `name`. Use a static string, inline or in a local `const`. Each route must produce a distinct Worker class; changing the name selects a different resource. If you already moved a route, `void info` also shows unmatched identities recorded in `void.lock.json`. Identify the original resource before adopting its suggested name; otherwise restore the original source and discover the name there.
 
-WebSocket routes currently support:
+### Rename a route parameter
 
-- Cloudflare-only
-- one route-derived connection target per socket
-- no Socket.IO-style dynamic room join/leave API
-- no global pub/sub abstraction
-- JSON event messages only
+By default, the instance key includes parameter names. `/chat/:room` with `room: 'general'` uses `room=general`; a route without parameters uses `default`. Multiple parameters are joined in route order, for example `team=acme&room=general`. If a multi-parameter route has a value containing `&`, its key uses a versioned encoding to keep rooms separate.
 
-Each socket connects to one route instance. Applications that need to switch rooms should manage that connection change explicitly.
+When upgrading an existing multi-parameter route with `&` in its parameter values, those rooms start with isolated storage. The previous storage is retained, but may have been shared by multiple rooms. Migrate only data whose ownership you have verified into each new room. Single-parameter rooms and multi-parameter rooms without `&` keep their existing identities.
 
-## Deployment
+If you also rename `[room]` to `[id]`, preserve the old key explicitly:
+
+```ts
+// routes/rooms/[id].ws.ts
+export default defineRoom({
+  name: 'chat-room',
+  key: ({ params }) => `room=${params.id}`,
+  messages: { client: ClientMessage, server: ServerMessage },
+  // Keep your existing hooks.
+});
+```
+
+Clients now connect to `/rooms/:id` with `params: { id: 'general' }`. The key remains `room=general`, so storage and `ctx.id` stay the same. Returning only `params.id` would select a different instance.
 
-`void deploy --platform cloudflare` persists the required binding and append-only SQLite class migration in `void.lock.json`, then deploys the generated Worker directly to your account. Commit this migration history and never delete or reorder a step after deployment.
+`key` is optional on both WebSocket helpers. It must return a string synchronously and consistently for the same parameters. Preserve the complete old key when migrating multiple parameters. Keep the callback stable after deployment.
+
+## Constraints
+
+Each socket connects to one route instance. To switch rooms, close the current connection and open another. For publishing to multiple topics, see [Live Event Streams](./live.md).
+
+## Deployment
 
-`void deploy --platform void` uses the same shared migration planner in the hosted uploader. Existing hosted WebSocket classes created on legacy storage remain there; only genuinely new classes use SQLite.
+WebSocket routes work on Cloudflare and Void platform deployments. Commit `void.lock.json` when Void adds a binding or migration. Do not delete or reorder deployed migration steps.

package/skills/void/docs/integrations/agents.md

@@ -10,7 +10,7 @@ outline: deep
 npx void init --agents
 ```
 
-This always creates or updates `AGENTS.md` with four brief bullets covering Void, deployment targets, the development workflow, and where to find the docs. It preserves your existing content outside the versioned Void block and leaves other instruction files untouched. There is no coding-agent selection prompt.
+Void updates `AGENTS.md` with development guidance and links to the docs, preserving your existing instructions.
 
 The complete Markdown docs ship with the installed package at `node_modules/void/skills/void/docs/`. Agents can read them directly, even without a linked skill.
 
@@ -20,7 +20,7 @@ Skills point your agent to the commands and docs it needs for the task. They lin
 
 Void ships two skills:
 
-- **`void`:** main development skill. Routes agent requests to the right documentation for CLI commands, routing, pages, database, auth, deployment, and more.
+- **`void`:** commands and docs for app development.
 - **`migrate-vite-cloudflare-to-void`:** migration skill for converting existing `@cloudflare/vite-plugin` apps to Void.
 
-Skills are linked automatically by `void init --agents` when it detects a supported agent's configuration. For Claude Code, they are symlinked into `.claude/skills/`. Other detected agents have them linked to their respective directories. If no agent is detected, skill linking is skipped and `AGENTS.md` points directly to the bundled docs.
+Skills are linked automatically by `void init --agents` when it detects a supported agent's configuration. For example, Claude Code uses `.claude/skills/`. If no agent is detected, skill linking is skipped and `AGENTS.md` points directly to the bundled docs.