chore: merge main into inspected-page bridge

Preserve the endpoint API reference alongside the relay reference and adapt the relay test protocol to the functions namespace introduced upstream.

Author: SaKaNa-Y

.gitattributes

@@ -0,0 +1,3 @@
+# pnpm patch files must stay LF: a CRLF checkout (Windows autocrlf) breaks
+# pnpm's patch parser with ERR_PNPM_INVALID_PATCH.
+*.patch text eol=lf

.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
         uses: oven-sh/setup-bun@v2
       - name: Set up Deno
         if: matrix.runtime == 'deno'
-        uses: denoland/setup-deno@v2
+        uses: denoland/setup-deno@v2.0.5
         with:
           deno-version: v2.x
       - run: pnpm install --frozen-lockfile

docs/app/components/UContentSearch.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import ContentSearch from '@nuxt/ui/components/content/ContentSearch.vue'
+
+defineOptions({ inheritAttrs: false })
+</script>
+
+<template>
+  <ContentSearch
+    v-bind="$attrs"
+    preserve-group-order
+  />
+</template>

docs/content/1.guide/11.client.md

@@ -87,9 +87,11 @@ if (!trusted) {
 
 ### Authenticating with a one-time code
 
-The dev server prints a single-use 6-digit code (expires in five minutes, rotates after repeated wrong attempts); `requestTrustWithCode` exchanges it for a persisted node-issued token shared across sibling tabs:
+The dev server prints a single-use 6-digit code (expires in five minutes, rotates after repeated wrong attempts) when an untrusted RPC client asks for one: call `requestAuthCode()` when your auth UI shows, passing `{ reissue: true }` from a "re-issue" button to rotate the code first. `requestTrustWithCode` then exchanges it for a persisted node-issued token shared across sibling tabs:
 
 ```ts
+await rpc.requestAuthCode()
+// … the developer reads the code from the terminal …
 const ok = await rpc.requestTrustWithCode('047204')
 ```
 

docs/content/1.guide/12.in-page-channel.md

@@ -37,12 +37,22 @@ import type { InPageChannelProtocol } from 'devframe/in-page-channel'
 export const MY_CHANNEL = 'devframes:plugin:my-tool'
 
 export interface MyChannelProtocol extends InPageChannelProtocol {
-  pageScript: { // implemented by the page script, called by panels
-    highlight: (selector: string) => void
-    measure: (selector: string) => { width: number, height: number }
+  functions: {
+    /** implemented by the page script, callable by panels */
+    pageScript: {
+      measure: (selector: string) => { width: number, height: number }
+      reset: () => Promise<void>
+    }
+    /** implemented by panels, callable by the page script */
+    panel: {
+      echo: (message: string) => Promise<string>
+    }
   }
-  panel: { // implemented by panels, called by the page script
-    flash: (message: string) => void
+  events: {
+    /** listened to by the page script, emitted by panels */
+    pageScript: { highlight: (selector: string) => void }
+    /** listened to by panels, emitted by the page script */
+    panel: { flash: (message: string) => void }
   }
   sharedStates: {
     state: { selections: string[] }
@@ -54,37 +64,41 @@ Channel names are namespaced with the devframe id, like RPC ids. Function names
 
 ## The page script endpoint
 
-Functions use the same authoring metadata as `defineRpcFunction` (`type`, Standard-Schema `args`/`returns`, `jsonSerializable`, `handler`), narrowed to the browser. The required `functions` object's keys are the function names, and it implements every function on that endpoint's protocol side. Each handler is contextually typed from its key and the corresponding function in the protocol. `defineChannelFunction` retains the named definition shape for lower-level authoring. Define each side's functions in that side's source files; the shared protocol file carries only types.
+The required `functions` option and optional `events` option declare every incoming name on the endpoint's protocol side; use `{}` for an empty direction. Functions require a `handler`. Events accept an optional `handler`, and `{}` registers an event for runtime subscriptions through `on()`. Handlers are contextually typed from the shared protocol and support Standard-Schema argument validation and `jsonSerializable` metadata. `defineChannelFunction` retains the named definition shape for lower-level authoring.
+
+`call()` accepts names from `functions`, including actions returning `void` or `Promise<void>`: callers can await completion and catch errors or timeouts. `emit()`, its deprecated alias `callEvent()`, and `on()` use the names declared in `events`. Function and event names have separate namespaces.
 
 ```ts
 import type { MyChannelProtocol } from '../shared/protocol'
 // inject/index.ts: runs in the user app's page
 import { createPageScriptChannel } from 'devframe/in-page-channel'
 import { MY_CHANNEL } from '../shared/protocol'
 
-const channel = createPageScriptChannel<MyChannelProtocol>({
+const pageChannel = createPageScriptChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
   functions: {
-    highlight: {
-      type: 'event', // fire-and-forget
-      jsonSerializable: true,
-      handler: selector => drawRing(document.querySelector(selector)),
-    },
+    reset: { type: 'action', handler: async () => clearSelections() },
     measure: { // request/response (the default `query` type)
       handler: (selector) => {
         const rect = document.querySelector(selector)!.getBoundingClientRect()
         return { width: rect.width, height: rect.height }
       },
     },
   },
+  events: {
+    highlight: {
+      jsonSerializable: true,
+      handler: selector => drawRing(document.querySelector(selector)),
+    },
+  },
 })
 
-channel.callEvent('flash', 'scanning…') // fans out to every connected panel
-channel.events.on('panel:connected', panel => console.log(panel.id))
-channel.events.on('panel:disconnected', () => pauseWorkIfNobodyWatches())
+pageChannel.emit('flash', 'scanning…') // received by each panel endpoint
+pageChannel.events.on('panel:connected', panel => console.log(panel.id))
+pageChannel.events.on('panel:disconnected', () => pauseWorkIfNobodyWatches())
 ```
 
-`callEvent` on the page script is 1:N: it fans out to every connected panel, and panels that don't implement the function ignore it. Request/response *to* a panel goes through an explicit peer handle: `channel.panels[0].call('flash', '…')`.
+`emit` on the page-script endpoint fans out to every connected panel endpoint. Functions declared under `functions.panel` are called through a specific `pageChannel.panels[0].call()` peer handle.
 
 ## The panel endpoint
 
@@ -94,19 +108,25 @@ import type { MyChannelProtocol } from '../shared/protocol'
 import { connectPanelChannel } from 'devframe/in-page-channel'
 import { MY_CHANNEL } from '../shared/protocol'
 
-const channel = connectPanelChannel<MyChannelProtocol>({
+const panelChannel = connectPanelChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
-  functions: {
-    flash: {
-      handler: message => showFlash(message),
-    },
+  functions: {},
+  events: {
+    flash: {},
   },
 })
 
-channel.callEvent('highlight', '.hero') // buffered until connected
-const size = await channel.call('measure', '.hero')
+const offFlash = panelChannel.on('flash', message => showFlash(message))
+// defined and received by the page-script endpoint
+panelChannel.emit('highlight', '.hero')
+const size = await panelChannel.call('measure', '.hero')
+await panelChannel.call('reset')
+
+offFlash() // stop listening
 ```
 
+The snippets form one channel pair: `pageChannel.emit('flash', …)` invokes `panelChannel.on('flash', …)`. In the other direction, `panelChannel.emit('highlight', …)` invokes the page-script endpoint's `highlight` handler and any matching `pageChannel.on()` listeners. An endpoint never receives its own emission.
+
 ## Shared state
 
 The channel's shared-state layer mirrors [`rpc.sharedState`](/guide/shared-state) (same `SharedState<T>` handle, same accessor), with the page script playing the server's role as rendezvous and authority. Its first `get` of a key must provide the initial value; panels are seeded automatically on connect (including late joiners and re-connects) and converge through syncId-deduplicated patches.
@@ -133,7 +153,7 @@ Every failure mode is a coded `InPageChannelError` (`error.code`) with a message
 The panel endpoint's connection lifecycle is explicit, so a panel renders a useful fallback instead of hanging:
 
 - `channel.status` is `connecting` → `connected` → (`connecting` on port loss) → `closed`, with `events.on('status:updated', …)` for reactivity.
-- While `connecting`, `call()` is queued (and still subject to its deadline) and `callEvent()` is buffered (up to `eventBufferLimit`, oldest dropped with a warning); both flush on connect.
+- While `connecting`, `call()` is queued (and still subject to its deadline) and `emit()` is buffered (up to `eventBufferLimit`, oldest dropped with a warning); both flush on connect.
 - A page script may legitimately never appear (the panel opened standalone, the user app not instrumented). Race `whenConnected(timeoutMs)` to show a "load the page script" empty state:
 
 ```ts
@@ -157,17 +177,21 @@ import { toRaw } from 'vue'
 const channel = connectPanelChannel<MyChannelProtocol>({
   name: MY_CHANNEL,
   serialize: value => toRawDeep(value), // applied to every outgoing argument and result
+  functions: {},
+  events: { flash: {} },
 })
 ```
 
+These hooks also apply to shared-state subscription snapshots, full-state updates, and patch arrays in both directions. Hooks that restore nested values should traverse objects and arrays, including each patch's `value`.
+
 Declaring a function `jsonSerializable: true` additionally enforces strict JSON on its payloads at the receiving endpoint, turning a would-be silent coercion or cryptic `DataCloneError` into a coded error naming the offending path.
 
 ## Multiple tabs
 
 The same app open in two tabs means two page scripts on one origin. Each page script carries a per-tab instance id (persisted in `sessionStorage`), and handshakes are targeted `postMessage`, so a dock panel always pairs with its own tab's page script. A panel can also pin explicitly:
 
 ```ts
-connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL, instanceId })
+connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL, instanceId, functions: {}, events: { flash: {} } })
 ```
 
 ## Custom transports
@@ -177,7 +201,7 @@ Both endpoints accept a pre-established `MessagePort` that bypasses the handshak
 ```ts
 const { port1, port2 } = new MessageChannel()
 pageScript.addPanelPort(port1)
-const panel = connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL, transport: port2 })
+const panel = connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL, transport: port2, functions: {}, events: { flash: {} } })
 ```
 
 ## When to use the in-page channel vs RPC

docs/content/1.guide/14.security.md

@@ -19,14 +19,14 @@ An RPC handler runs with the full privileges of its Node process (filesystem, ch
 
 ## The pre-trust gate
 
-One rule decides what an untrusted connection may call: **a method is reachable before trust iff its name starts with `anonymous:`** (`isAnonymousRpcMethod`, from `devframe/constants`); only the two handshake methods below qualify.
+One rule decides what an untrusted connection may call: **a method is reachable before trust iff its name starts with `anonymous:`** (`isAnonymousRpcMethod`, from `devframe/constants`); only the handshake and code-request methods below qualify.
 
 The RPC server binding enforces this: pass `auth: authHandler` (its `.authorize` becomes the gate) or your own `authorize(methodName, session)`. Every other call from an untrusted session throws [`DF0036`](/errors/DF0036). `rpc.call` / `rpc.callOptional` / `rpc.callEvent` hold calls issued during the first handshake and release them once it settles.
 
 ## Authentication flow
 
 1. A fresh RPC client calls `anonymous:devframe:auth` with its stored token (empty on first run); the server returns `{ isTrusted: false }` and the UI prompts for a code.
-2. The dev server shows a 6-digit code in the terminal (`auth.printBanner()` once listening).
+2. The auth UI requests a code (`rpc.requestAuthCode()`, sent automatically when the built-in notice view first shows, or by its "re-issue" button with `{ reissue: true }` to rotate the code first); the dev server prints the 6-digit code, its expiry, and the requesting browser in the terminal. An already-authorized page never triggers a print.
 3. The developer enters it; the browser calls `requestTrustWithCode(code)`.
 4. The server verifies the code, mints a high-entropy bearer token, trusts the session, and returns it.
 5. The browser persists the token and presents it on reconnect (or via a `?devframe_auth_token=` query param the connect-time hook checks first); sibling tabs receive it over the `devframe-auth` channel and become trusted.
@@ -51,11 +51,11 @@ Pass `clientAuthTokens` for CI/shared machines to skip the prompt, or a custom `
 
 ### Auth methods
 
-The two `anonymous:`-prefixed handshake methods re-authenticate a stored token (`anonymous:devframe:auth`) and exchange a one-time code for a token (`anonymous:devframe:auth:exchange`); `devframe:auth:revoke` self-revokes, and the `devframe:auth:revoked` event drops affected RPC clients to untrusted. Wire shapes are in the [Node-Side API reference](/references/node-api#auth-methods).
+The `anonymous:`-prefixed methods re-authenticate a stored token (`anonymous:devframe:auth`), exchange a one-time code for a token (`anonymous:devframe:auth:exchange`), and ask the server to print its code banner (`anonymous:devframe:auth:request-code`); `devframe:auth:revoke` self-revokes, and the `devframe:auth:revoked` event drops affected RPC clients to untrusted. Wire shapes are in the [Node-Side API reference](/references/node-api#auth-methods).
 
 Node primitives in `devframe/node/auth` (`getTempAuthCode` / `refreshTempAuthCode`, `exchangeTempAuthCode`, `verifyAuthToken`, `buildOtpAuthUrl`, and `revokeAuthToken`) implement the same flow for a host framework wiring its own gate; signatures are in the [reference](/references/node-api#node-auth-primitives).
 
-RPC client methods (`devframe/client`): `requestTrustWithCode(code)`, `requestTrustWithToken(token)`, and `ensureTrusted(timeout?)` / `isTrusted` (the trust gate).
+RPC client methods (`devframe/client`): `requestAuthCode(options?)` (print the code banner; `{ reissue: true }` rotates the code first), `requestTrustWithCode(code)`, `requestTrustWithToken(token)`, and `ensureTrusted(timeout?)` / `isTrusted` (the trust gate).
 
 ### Magic-link authentication
 

docs/content/1.guide/15.agent-native.md

@@ -2,14 +2,14 @@
 title: 'Agent-Native Devframe'
 navigation:
   icon: i-lucide-bot
-description: 'Devframe exposes its browser-side API (RPC functions, resources, shared state) to coding agents over MCP, opt-in per function.'
+description: 'Devframe exposes its API (RPC functions, resources, shared state) to agents, over MCP on the node side and WebMCP on the browser side, opt-in per function.'
 ---
 
-Devframe exposes its browser-side API (RPC functions, resources, shared state) to coding agents over MCP, opt-in per function.
+Devframe exposes its API (RPC functions, resources, shared state) to agents, over MCP on the node side and [WebMCP](#browser-side-tools-over-webmcp) on the browser side, opt-in per function.
 
 ## How it works
 
-Three pieces: the **`agent` field** on `defineRpcFunction`, **`ctx.agent`** (non-RPC tools + resources), and the **MCP adapter** (`devframe/adapters/mcp`) serving an [MCP](https://modelcontextprotocol.io) server.
+Three pieces: the **`agent` field** on `defineRpcFunction`, **`ctx.agent`** (non-RPC tools + resources), and the **MCP adapter** (`devframe/adapters/mcp`) serving an [MCP](https://modelcontextprotocol.io) server. The same `agent` field on a *client* RPC function surfaces it [over WebMCP](#browser-side-tools-over-webmcp) instead.
 
 ## Exposing an RPC function
 
@@ -137,6 +137,29 @@ In `claude_desktop_config.json`:
 
 Restart; tools appear in the drawer, resources as `devframe://resource/<id>` / `devframe://state/<key>` URIs.
 
+## Browser-side tools over WebMCP
+
+The same `agent` signature works on the browser side: a client RPC function (a function the node side calls on the browser, registered on `rpc.client` or through a scoped `client.scope('my-plugin').rpc.register(...)`) carrying an `agent` field is mirrored onto the page's [WebMCP](https://github.com/webmachinelearning/webmcp) model context (`document.modelContext` / `navigator.modelContext`) as a callable tool, so in-page and browser-integrated agents can drive browser-side functionality directly. Wire names, `arg0`/`arg1`/… input schemas, and safety annotations match the MCP projection above.
+
+```ts
+const rpc = await connectDevframe()
+
+rpc.client.register({
+  name: 'my-plugin:highlight-node',
+  type: 'action',
+  jsonSerializable: true,
+  agent: {
+    description: 'Highlight a node in the open inspector view. Use it to point the user at a finding.',
+  },
+  handler: (id: string) => highlightNode(id),
+})
+```
+
+`connectDevframe()` wires this on its own when the browser provides a model context; `webmcp: false` keeps the browser side off the WebMCP surface. `registerWebMcpTools(collector)` (from `devframe/client`) applies the same projection to a hand-built collector and returns a dispose that unregisters every tool.
+
+> [!WARNING]
+> WebMCP is an experimental proposal; `registerWebMcpTools` tracks the current draft (`AbortSignal`-based unregistration) and earlier handle-returning drafts, but the browser API may still change.
+
 ## Writing descriptions agents act on
 
 Describe *when* to use a tool, not just its return:

docs/content/1.guide/3.rpc.md

@@ -193,7 +193,6 @@ Add an `agent` field to expose the function to coding agents over MCP:
 defineRpcFunction({
   name: 'get-modules',
   type: 'query',
-  jsonSerializable: true,
   args: [v.object({ limit: v.number() })],
   returns: v.array(v.object({ id: v.string(), size: v.number() })),
   agent: {
@@ -207,7 +206,7 @@ defineRpcFunction({
 })
 ```
 
-Exposing a function over MCP requires `jsonSerializable: true`.
+The `agent` field implicitly enables strict JSON serialization because MCP consumes JSON-shaped data. Set `jsonSerializable: true` directly when an RPC-only function also benefits from that contract.
 
 ## What's next
 

docs/content/1.guide/4.shared-state.md

@@ -72,7 +72,7 @@ state.mutate((draft) => {
 })
 ```
 
-Devframe applies the recipe to a draft, emits `updated` (with `SharedStatePatch[]` if enabled), and broadcasts to RPC clients; a `syncIds` set keeps mutations idempotent on replay.
+Devframe applies the recipe to a draft. When Immer returns a new state reference, Devframe emits `updated` and broadcasts it to RPC clients. Explicit replacement objects also notify. With patches enabled, `updated` carries `SharedStatePatch[]`. Sync IDs remain recorded for unchanged recipes, so replays stay idempotent.
 
 ## Patches (advanced)
 

docs/content/2.adapters/1.initiate.md

@@ -129,7 +129,7 @@ Fetch handlers only hand over `Request`s, so the host framework binds the RPC so
 
 ## Auth
 
-The running devframe **gates by default**. The interactive OTP handler wires automatically, printing its code/magic-link banner once the public origin is known, whether from the `origin` option or derived from a request whose own origin is loopback or exactly matches an `allowedOrigins` entry. A non-loopback deployment (behind a proxy, on a LAN, on a public host) sets `origin` explicitly so the magic link resolves to the intended address; a raw inbound `Host` header and forwarded headers are never trusted. Pass `auth: false` for single-user localhost, or a `DevframeAuthHandler` for a custom scheme.
+The running devframe **gates by default**. The interactive OTP handler wires automatically, printing its code/magic-link banner when an untrusted browser client asks for a code (`rpc.requestAuthCode()`); an already-authorized page triggers no print. The magic link's origin comes from the `origin` option, or is derived from a request whose own origin is loopback or exactly matches an `allowedOrigins` entry. A non-loopback deployment (behind a proxy, on a LAN, on a public host) sets `origin` explicitly so the magic link resolves to the intended address; a raw inbound `Host` header and forwarded headers are never trusted. Pass `auth: false` for single-user localhost, or a `DevframeAuthHandler` for a custom scheme.
 
 ## Relation to the other adapters