---
title: Introduction
navigation:
  icon: i-lucide-book-open
description: Devframe is a framework-neutral foundation for building a devtool once and running it everywhere - inside any host framework, as a standalone tool, or through a coding agent.
---

**Devframe is a framework-neutral foundation for building a devtool once and running it everywhere - inside any host framework, as a standalone tool, or through a coding agent.** A devtool here is anything that makes a program's implicit state visible and interactive: an inspector, a build or bundle analyzer, an asset viewer, a state or data explorer, a terminal. You describe such a tool one time, and the same definition mounts almost anywhere. Think of it as [`unplugin`](https://unplugin.unjs.io/) for devtools.

## Why it exists

Most devtools rebuild the same plumbing (node–browser communication, state synchronization, serialization, static-asset hosting, a web interface) and wire it to one framework's dev server. The same idea then gets rebuilt, slightly differently, for the next framework, so effort fragments across the ecosystem instead of compounding.

Devframe moves that boundary. A capability is defined once against a stable interface and runs on every supported host framework, so a good tool can be built once, travel further, and improve through the work of more communities.

## Who it's for

- **Devtool authors** who want one tool to run standalone, embed in a host framework, ship as a CLI or static report, and answer to a coding agent, without maintaining a separate version per environment.
- **Framework and build-tool teams** who want to offer devtools without rebuilding shared infrastructure, and to inherit capabilities other communities already built.
- **Anyone** who wants a tool's state and actions available to both a human UI and a coding agent from one source of truth.

With a coding agent to scaffold the boilerplate, Devframe is also a fast foundation for standing up a bespoke, specific-need, or even one-off devtool.

New here? [Answer a few questions about your devtool](/guide/getting-started) and get a reading list tailored to it. For the story behind Devframe, read [Pluggable, Extensible, and Playful DevTools](/posts/pluggable-extensible-playful-devtools).

## One definition, one standard handler

Every devframe starts with [`defineDevframe()`](/guide/devframe-definition), pairing a tool's identity with its capabilities.

```ts
import { defineDevframe } from 'devframe'
import { inspectProject } from './rpc'

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  /** package metadata and client entry omitted… */
  setup(ctx) {
    ctx.scope('my-tool').rpc.register(inspectProject)
  },
})
```

[`initDevframe()`](/adapters/initiate) turns the definition into a live instance whose `handler` is a Web Standard `(request: Request) => Promise<Response>`:

```ts
import { initDevframe } from 'devframe/initiate'
import devframe from './devframe'

const devtools = initDevframe(devframe, { base: '/__my-tool/' })

devtools.handler
// (request: Request) => Promise<Response>

devtools.nodeMiddleware
// (req, res, next) => void, for Connect-style servers (Vite, Rsbuild)
```

The handler serves the web interface, connection metadata, live RPC, authentication, and optional MCP endpoint under one namespace. Hono and Nitro take Web Standard requests directly; Next.js and SvelteKit expose route handlers; Vite and Rsbuild accept its `nodeMiddleware`. The live RPC connection attaches via a shared HTTP server, upgrade events, or a side-car server, advertised through `__connection.json`. See [The Standard Handler](/adapters/initiate).

## Adapters as conveniences

[Higher-level adapters](/adapters) package the foundation as a standalone CLI, dev server, Vite DevTools plugin, MCP server, or static report:

```ts
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { createBuild } from 'devframe/adapters/build'
import { createCac } from 'devframe/adapters/cac'
import { createDevServer } from 'devframe/adapters/dev'
import { createMcpServer } from 'devframe/adapters/mcp'
import devframe from './devframe'

/** Pick the entry points your package ships: */
export const runCli = () => createCac(devframe).parse()
export const startServer = () => createDevServer(devframe)
export const vitePlugin = createPluginFromDevframe(devframe)
export const startMcp = () => createMcpServer(devframe, { transport: 'stdio' })
export const buildReport = () => createBuild(devframe, { outDir: 'dist-static' })
```

## Visual and agentic

One source of truth feeds a visual panel and programmatic consumers. RPC functions stay private by default and opt into agent exposure explicitly: the [MCP adapter](/adapters/mcp) translates functions, readable resources, and selected shared state into an agent-consumable interface. See [Agent-Native](/guide/agent-native).

## From one devframe to a hub

[`@devframes/hub`](/guide/hub) is the composition layer, providing shared concepts (docks, commands, messages, terminals) against a shared context. [`initHub()`](/guide/hub-initiate) puts many devframes behind one Web Standard handler:

```ts
import { createUi } from '@devframes/hub-ui'
import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
import { createDataInspectorDevframe } from '@devframes/plugin-data-inspector'
import { createTerminalsDevframe } from '@devframes/plugin-terminals'

const hub = initHub({
  base: DEVFRAMES_HUB_BASE,
  devframes: [createDataInspectorDevframe(), createTerminalsDevframe()],
  ui: createUi(),
})

hub.handler
// the whole devtools collection as Request → Response
```

The mounted devframes share one RPC registry, state store, connection, auth gate, and optional aggregate MCP endpoint. The hub is headless: [`@devframes/hub-ui`](/guide/build-your-own-hub-ui) is a reference hub UI provider a product can replace.

## Inheriting the ecosystem

[Vite DevTools](https://devtools.vite.dev/) is the first flagship hub UI provider, using `initHub()` alongside its own Vite, Rolldown, Vitest, and Oxc tooling. The [framework kits](/frameworks) ([`@devframes/vite`](/frameworks/vite), [`@devframes/nuxt`](/frameworks/nuxt), [`@devframes/next`](/frameworks/next)) add conventions over the same handler. See the [Ecosystem](/ecosystem) page.

## Install

```sh
pnpm add devframe
```

`devframe` ships ESM-only, no Vite dependency. The CLI adapter's optional peer (`cac`) surfaces its requirement at import time.

## Hello, Devframe

A minimal devframe with a CLI entry point:

```ts
import { defineDevframe, defineRpcFunction } from 'devframe'
import { createCac } from 'devframe/adapters/cac'

const devframe = defineDevframe({
  id: 'my-devframe',
  name: 'My Devframe',
  version: '1.0.0',
  packageName: 'my-devframe',
  homepage: 'https://github.com/me/my-devframe',
  description: 'A one-line summary of what the tool does.',
  icon: 'ph:gauge-duotone',
  clientAssets: 'client/dist',
  setup(ctx) {
    ctx.rpc.register(defineRpcFunction({
      name: 'my-devframe:hello',
      type: 'static',
      jsonSerializable: true,
      handler: () => ({ message: 'hello' }),
    }))
  },
})

await createCac(devframe).parse()
```

Run it:

```sh
node ./my-devframe.js        # dev server on http://localhost:9999/
node ./my-devframe.js build  # self-contained static deploy in dist-static/
node ./my-devframe.js mcp    # stdio MCP server
```

The CLI adapter serves the SPA at `/`; embedded in a host framework (`vite`, `embedded`) the default becomes `/__my-devframe/`. Override via `defineDevframe({ basePath })`.

## What Devframe provides

| Subsystem                                             | What it does                                                                                                                         |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **[Devframe Definition](/guide/devframe-definition)** | One `defineDevframe` call describes your tool; adapters deploy it anywhere.                                                          |
| **[RPC](/guide/rpc)**                                 | Type-safe bidirectional calls on birpc, validated against any Standard Schema validator. `query`, `static`, `action`, `event` types. |
| **[Shared State](/guide/shared-state)**               | Observable, patch-synced state surviving reconnects, node side ↔ browser side.                                                       |
| **[JSON-Render](/guide/json-render)**                 | Opt-in data-driven UI: a serializable view spec, rendered standalone or in a hub dock.                                               |
| **[Diagnostics](/guide/diagnostics)**                 | Coded warnings/errors via `nostics`, in the host framework's shared lookup.                                                          |
| **[Streaming](/guide/streaming)**                     | One-way (RPC streaming) and two-way (uploads) channel primitives.                                                                    |
| **[When Clauses](/references/when-clauses)**          | VS Code-style conditional expressions for docks, commands, and custom UI.                                                            |
| **[The Standard Handler](/adapters/initiate)**        | `initDevframe()`: the Web Standard `Request → Response` boundary.                                                                    |
| **[Client](/guide/client)**                           | Browser RPC client (`connectDevframe`), auto-auth, WebSocket / static modes.                                                         |
| **[Agent-Native](/guide/agent-native)**               | Opt-in exposure of your tool's capabilities to coding agents over MCP.                                                               |

## What's next

- [Tutorial: Build a Server Data Inspector](/guide/tutorial-server-data-inspector): go from an empty folder to a shippable devtool, one capability at a time
- [Devframe Definition](/guide/devframe-definition): `defineDevframe` and `DevframeNodeContext`
- [The Standard Handler](/adapters/initiate): mount into any host framework
- [Adapters](/adapters): convenience entry points
- [Hub](/guide/hub): compose many devframes
- [Pluggable, Extensible, and Playful DevTools](/posts/pluggable-extensible-playful-devtools): the vision and story behind Devframe

---
title: Getting Started
navigation:
  icon: i-lucide-rocket
description: Answer a few questions about the devtool you want to build and get a reading list tailored to it.
---

Devframe is a framework-neutral foundation for building a devtool once and running it everywhere: inside any host framework, as a standalone tool, or through a coding agent. See the [Introduction](/guide) for the full picture, or read [Pluggable, Extensible, and Playful DevTools](/posts/pluggable-extensible-playful-devtools) for the story behind it.

Devframe provides a lot of features to build DevTools with various needs. It could be overwhelming to start with. Here we have the wizard to help you get started. Answer a few questions about the devtool you want to build and get a reading list tailored to it.

::getting-started-wizard
::

None of this is a required reading order. [`defineDevframe()`](/guide/devframe-definition) and [the tutorial](/guide/tutorial-server-data-inspector) are worth reading regardlessly.

---
title: 'Tutorial: Build a Server Data Inspector'
navigation:
  icon: i-lucide-graduation-cap
description: Build a devtool that displays and queries live server-side data, then ship it as a hub dock entry, a static build, a standalone dev server, and a CLI.
---

Let's build a real devtool from scratch: a **Data Inspector** that shows the shape of live server-side state and lets you read any value out of it. We'll get it working first, then teach it new tricks one at a time: a dock entry in a hub, a static build, a standalone dev server, and a CLI.

You'll need [Node 24+](https://nodejs.org/) and a terminal. Every code block is complete, so you can copy them as you go.

## The shape of a devframe

A devframe is two halves talking over a typed connection: the **node side** exposes functions, and the **browser side** calls them and renders the results. Devframe is everything in between: the wire, the UI hosting, auth, builds, and a CLI.

The two halves live in their own folders: the node side under `src/node/`, the web app under `app/`. A `playgrounds/` folder holds hosts that boot the built tool. We'll fill these in as we go.

## Step 1: Define the tool

Everything starts with `defineDevframe`: your tool's name, plus a `setup` where you register what it can do. Create the project and the definition:

```sh
mkdir data-inspector && cd data-inspector
npm init -y && npm pkg set type=module
npm install devframe && npm install -D typescript
```

```ts [src/node/data-inspector.ts]
import { defineDevframe } from 'devframe'

// Some example server-side data, whatever you want to peek at while your
// user app runs: config, a cache, a DB handle.
const serverState = {
  config: { name: 'Acme', port: 3000, debug: false },
  users: [
    { id: 1, name: 'Ada', admin: true },
    { id: 2, name: 'Lin', admin: false },
  ],
  featureFlags: { newDashboard: true, betaSearch: false },
}

// A tiny query helper that follows a dot-path like `users.0.name` into the state.
function valueAtPath(root: unknown, path: string): unknown {
  if (!path)
    return root
  return path.split('.').reduce<unknown>((value, key) => {
    if (value == null || typeof value !== 'object')
      return undefined
    return (value as Record<string, unknown>)[key]
  }, root)
}

const dataInspectorFrame = defineDevframe({
  id: 'data-inspector',
  name: 'Data Inspector',
  version: '0.0.0',
  packageName: 'data-inspector',
  description: 'Inspect live server state.',
  homepage: 'https://example.com',
  importMetaUrl: import.meta.url,

  setup(ctx) {
    // What does the state look like?
    ctx.rpc.register({
      name: 'data-inspector:get-meta',
      type: 'query',
      jsonSerializable: true,
      handler: () =>
        Object.entries(serverState).map(([key, value]) => ({
          key,
          type: Array.isArray(value) ? 'array' : typeof value,
          length: Array.isArray(value) ? value.length : undefined,
        })),
    })

    // What's at this path?
    ctx.rpc.register({
      name: 'data-inspector:query',
      type: 'query',
      jsonSerializable: true,
      handler: (path: string) => valueAtPath(serverState, path),
    })
  },
})

export default dataInspectorFrame
```

`ctx.rpc.register` publishes a function the browser side can call: a namespaced `name`, a `type` (`query` is read-only), and a `handler` that takes the call's arguments and returns JSON. That's the whole node side. ([RPC](/guide/rpc) has the other types; [Devframe Definition](/guide/devframe-definition) has every field.)

## Step 2: Add a UI

Now the browser side. We'll use React here, but any framework works; the only devframe-specific line is `connectDevframe`, which opens the connection back to the node side.

```sh
npm install react react-dom @devframes/vite
npm install -D vite @vitejs/plugin-react @types/react @types/react-dom
```

```html [app/index.html]
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Data Inspector</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="./main.tsx"></script>
  </body>
</html>
```

```tsx [app/main.tsx]
import { createRoot } from 'react-dom/client'
import { App } from './App'

createRoot(document.getElementById('app')!).render(<App />)
```

```tsx [app/App.tsx]
import type { DevframeRpcClient } from 'devframe/client'
import { connectDevframe } from 'devframe/client'
import { useEffect, useState } from 'react'

interface MetaEntry { key: string, type: string, length?: number }

export function App() {
  const [rpc, setRpc] = useState<DevframeRpcClient>()
  const [meta, setMeta] = useState<MetaEntry[]>([])
  const [path, setPath] = useState('config')
  const [result, setResult] = useState<unknown>()

  useEffect(() => {
    // No argument: the RPC client finds the node side from the page's own
    // URL, so this line never changes no matter how the tool is hosted.
    connectDevframe().then(async (client) => {
      setRpc(client)
      const call = client.call as (name: string, ...args: unknown[]) => Promise<any>
      setMeta(await call('data-inspector:get-meta'))
    })
  }, [])

  async function runQuery() {
    if (!rpc)
      return
    const call = rpc.call as (name: string, ...args: unknown[]) => Promise<any>
    setResult(await call('data-inspector:query', path))
  }

  return (
    <main style={{ fontFamily: 'sans-serif', maxWidth: 640, margin: '2rem auto' }}>
      <h1>Data Inspector</h1>
      <ul>
        {meta.map(m => (
          <li key={m.key}>
            <code>{m.key}</code>
            {' - '}
            {m.type}
            {m.length != null ? ` (${m.length})` : ''}
          </li>
        ))}
      </ul>
      <input value={path} onChange={e => setPath(e.target.value)} placeholder="config.port" />
      <button type="button" onClick={runQuery}>Query</button>
      <pre>{JSON.stringify(result, null, 2)}</pre>
    </main>
  )
}
```

`client.call(name, ...args)` reaches your handlers. (We cast `.call` and call by name here; wire up a typed registry and every call is checked end to end; see [RPC](/guide/rpc).)

## Step 3: Run it in development

To try what we've built, let Vite serve the UI and hand RPC traffic to devframe:

```ts [app/vite.config.ts]
import { devframeViteBridge } from '@devframes/vite/single'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
import dataInspectorFrame from '../src/node/data-inspector.ts'

export default defineConfig({
  base: './', // relative asset URLs, so the built UI works under any mount path
  build: { outDir: '../dist/client', emptyOutDir: true },
  plugins: [
    react(),
    // Vite serves the page; the bridge answers RPC on the same origin, so
    // `connectDevframe()` just finds it. `auth: false`, see the note below.
    devframeViteBridge(dataInspectorFrame, { base: '/', auth: false }),
  ],
})
```

```sh
npx vite --config app/vite.config.ts
```

Open the printed URL. The three keys and their types show up, and typing `config.port` or `users.0.name` and hitting **Query** prints the value. Button → `call` → your `handler` → back to the page: that's the whole devframe working.

> [!WARNING]
> `auth: false` trusts anything that can reach the port. It's off here to keep the tutorial simple; turn it on for anything you publish or expose beyond localhost. See [Security](/guide/security).

From here on we reuse this same `src/node/data-inspector.ts` and `app/` unchanged; all that changes is where they run.

## Step 4: Dock it in a hub

A [hub](/guide/hub) puts many devframes behind one interface, each a **dock entry** you switch between, the tool's own UI in an iframe. Since our SPA uses a bare `connectDevframe()`, it already works anywhere; the hub just needs the built UI, so point the definition at it:

```ts [src/node/data-inspector.ts]
import { fileURLToPath } from 'node:url'
// …
const dataInspectorFrame = defineDevframe({
  id: 'data-inspector',
  /** … */
  clientAssets: fileURLToPath(new URL('../../dist/client', import.meta.url)),
  setup(ctx) { /* unchanged */ },
})
```

Build the UI and stand up a one-devframe hub:

```sh
npm install @devframes/hub @devframes/hub-ui
npx vite build --config app/vite.config.ts
```

```ts [playgrounds/hub.config.ts]
import { createUi } from '@devframes/hub-ui'
import { viteDevframeHub } from '@devframes/vite/hub'
import { defineConfig } from 'vite'
import dataInspectorFrame from '../src/node/data-inspector.ts'

export default defineConfig({
  plugins: [
    viteDevframeHub({
      devframes: [dataInspectorFrame],
      ui: createUi({ branding: { productName: 'My Devtools' } }),
    }),
  ],
})
```

```sh
npx vite --config playgrounds/hub.config.ts
```

Your inspector now sits in the hub's dock rail as a dock entry. Add more to `devframes: [...]` (your own or the [built-in devframes](/add-ons)) and each gets its own. (The hub prints a code to authorize on first connect.)

## Step 5: Build a static version

Some tools should work with no node side at all: a report you can drop on any static hosting. `createBuild` renders the UI and **bakes in** the results of read-only calls. Opt one in with `snapshot: true`:

```ts
ctx.rpc.register({
  name: 'data-inspector:get-meta',
  type: 'query',
  jsonSerializable: true,
  snapshot: true, // bake this call's result into the build
  handler: () => {
    /* … unchanged … */
  }
})
```

```js [scripts/build.mjs]
import { createBuild } from 'devframe/adapters/build'
import dataInspectorFrame from '../src/node/data-inspector.ts'

await createBuild(dataInspectorFrame, { outDir: 'dist-static' })
```

```sh
npx vite build --config app/vite.config.ts   # refresh dist/client
node scripts/build.mjs                        # → dist-static/
```

Serve `dist-static/` anywhere and the meta list renders from the baked snapshot, no Node in sight. `query` takes an argument, so it still needs the live node side (next), or you can bake specific inputs ([Client Assets](/guide/client-assets)).

## Step 6: Run it standalone

The definition never depended on Vite. `createDevServer` runs the tool on its own, serving the UI from `clientAssets` and answering RPC live:

```js [playgrounds/serve.mjs]
import { createDevServer } from 'devframe/adapters/dev'
import dataInspectorFrame from '../src/node/data-inspector.ts'

await createDevServer(dataInspectorFrame, { openBrowser: true })
```

```sh
npx vite build --config app/vite.config.ts
node playgrounds/serve.mjs
```

Same UI, same live calls, no bundler in the loop: this is what you'd drop into your own Node program.

## Step 7: Give it a CLI

Finally, wrap that dev server in a CLI. `devframe/adapters/cac` turns a devframe into a CLI with `dev`, `build`, and `mcp` commands:

```js [bin.mjs]
#!/usr/bin/env node
import { createCac } from 'devframe/adapters/cac'
import dataInspectorFrame from './src/node/data-inspector.ts'

createCac(dataInspectorFrame).parse()
```

```sh
npm pkg set bin.data-inspector=bin.mjs

node bin.mjs dev     # the standalone dev server from Step 6
node bin.mjs build   # the static build from Step 5
node bin.mjs mcp     # expose the tool to a coding agent over MCP
```

You can also assemble your own CLI from the adapter functions used above.

That's it for this tutorial. For a full-featured version, there's a ready-to-use [Data Inspector built-in devframe](/add-ons/devframes/data-inspector) to use or read for reference.

## What's next

- [RPC](/guide/rpc): `action` and `event` calls, end-to-end types, schema validation
- [Shared State](/guide/shared-state): push live changes to the UI without polling
- [Hub](/guide/hub): docks, commands, terminals across many tools
- [Agent-Native](/guide/agent-native): expose your tool to coding agents over MCP

---
title: Devframe Definition
navigation:
  icon: i-lucide-file-code
description: One defineDevframe call returns a portable DevframeDefinition any adapter consumes.
---

One `defineDevframe` call returns a portable `DevframeDefinition` any [adapter](/adapters) consumes.

## Minimal definition

```ts
import { defineDevframe, defineRpcFunction } from 'devframe'
import * as v from 'valibot' // npm i valibot

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  version: '1.0.0',
  packageName: 'my-tool',
  importMetaUrl: import.meta.url,
  homepage: 'https://github.com/me/my-tool',
  description: 'A one-line summary of what the tool does.',
  icon: 'ph:gauge-duotone',
  setup(ctx) {
    // A scoped context auto-namespaces ids with your devframe `id`.
    const my = ctx.scope('my-tool')

    // Register your RPC functions, shared state, etc. here.
    my.rpc.register(defineRpcFunction({
      name: 'hello', // stored as `my-tool:hello`
      type: 'static',
      jsonSerializable: true,
      handler: () => ({ message: 'hello' }),
    }))
  },
})
```

## Definition fields

`id`, `name`, `version`, `packageName`, `homepage`, `description`, and `setup` are required; pass `importMetaUrl: import.meta.url` so [remote assets](/guide/client-assets) and declared [services](/guide/services#wire-services) resolve against the devframe's own dependencies. The remaining fields cover display (`icon`, [Icon values](/references/node-api#icon-values)), mounting (`basePath`, `duplicationStrategy`, `capabilities`), what the devframe consumes and serves (`services`, `clientAssets`, `rpc.snapshot`), and [CLI defaults](#cli-options) (`cli`). Every field is listed in the [Node-Side API reference](/references/node-api#definition-fields).

### Sourcing metadata from `package.json`

Import metadata from `package.json` (`name` → `packageName`; devframe `name` is a separate display label):

```ts
import pkg from '../package.json' with { type: 'json' }

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool', // display label
  version: pkg.version,
  packageName: pkg.name,
  importMetaUrl: import.meta.url,
  homepage: pkg.homepage,
  description: pkg.description,
  setup(ctx) { /* … */ },
})
```

### Resolving against the devframe's own dependencies

`importMetaUrl` resolves companion packages against the devframe's **own** dependencies:

```ts
export default defineDevframe({
  /** …metadata as above */
  importMetaUrl: import.meta.url,
  /**
   * Served from the locally installed `my-tool--assets`, resolved via
   * `importMetaUrl`; it works under pnpm's strict layout with zero network.
   */
  clientAssets: { package: `${pkg.name}--assets`, version: pkg.version },
  /** Imported from `my-tool`'s own dependency graph. */
  services: [{ package: '@scope/my-service', version: pkg.version }],
  setup(ctx) { /* … */ },
})
```

For remote assets, `importMetaUrl` is the default `resolveFrom`; a per-source value wins; `resolveFrom: null` opts out.

### Serving the UI with `clientAssets`

```ts
import { fileURLToPath } from 'node:url'

export default defineDevframe({
  /** …metadata as above */
  importMetaUrl: import.meta.url,
  /**
   * A local build resolved from the module; it works from source and the
   * published package.
   */
  clientAssets: fileURLToPath(new URL('../dist/spa', import.meta.url)),
  setup(ctx) { /* … */ },
})
```

For assets you host yourself, call `ctx.views.hostStatic` in `setup`; see [Client Assets](/guide/client-assets#programmatic-hosting-from-setup).

### Runtime flags

`ctx.mode` (`'dev'`/`'build'`) gates runtime-specific work:

```ts
defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  setup(ctx) {
    if (ctx.mode === 'build') {
      // Static-only work, baked into the RPC dump.
      ctx.rpc.addFunctions(staticFunctions)
    }
    else {
      // Dev-mode wiring, file watchers, etc.
      watchProject(ctx)
    }
  },
})
```

The CLI dev server sets `mode: 'dev'`; `createBuild`, `'build'`.

## The setup context

`setup(ctx)` receives a `DevframeNodeContext`:

```ts
interface DevframeNodeContext {
  readonly cwd: string
  readonly workspaceRoot: string
  readonly mode: 'dev' | 'build'

  host: DevframeHost // runtime abstraction (mountStatic / resolveOrigin / getStorageDir)
  rpc: RpcFunctionsHost // register + broadcast + sharedState
  views: DevframeViewHost // static file hosting (`hostStatic`)
  diagnostics: DevframeDiagnosticsHost
  agent: DevframeAgentHost // expose tools + resources to coding agents
  services: DevframeServicesHost // typed cross-devframe service registry
  staticConfig: Partial<DevframeConnectionConfigsRegistry> // this context's own ConnectionMeta.configs

  scope: (id) => DevframeScopedNodeContext // namespaced view (preferred)
}
```

### Cross-devframe services

`ctx.services` is a typed, namespaced registry: one devframe exposes a capability, others consume it ([Cross-Devframe Services](/guide/services)).

```ts
ctx.services.provide('my-plugin:sources', sources)

ctx.services.whenAvailable('my-plugin:sources', (sources) => {
  sources.register(/* ... */)
})
```

### Static connection configs

`ctx.staticConfig` is this context's own `ConnectionMeta.configs`: read-only boot-time data from the connection handshake; write it during `setup(ctx)`. Contrast `ctx.scope(id).settings` (mutable, synced).

```ts
declare module 'devframe/types' {
  interface DevframeConnectionConfigsRegistry {
    'my-plugin': { featureFlag: boolean }
  }
}

ctx.staticConfig['my-plugin'] = { featureFlag: true }
```

### Storage scopes

`ctx.host.getStorageDir(scope)` places persisted state in three classes: `workspace` is committable and team-shared (saved presets, config), `project` is per-checkout (caches, personal settings), and `global` is per-user (auth tokens, machine-wide prefs). Placements are in the [Node-Side API reference](/references/node-api#storage-scopes).

`ctx.scope(id)` returns a namespace-scoped view ([Scoped Context](/guide/scoped-context)) auto-prefixing every RPC id, shared-state key, and streaming channel, plus a persisted `settings` store (`project`/`global` scopes use the matching storage classes).

Hosted adapters can augment `ctx`, e.g. the [`vite` adapter](/adapters/vite)'s dock, command, message, and terminal hosts.

## CLI options

`cli` sets CLI-adapter defaults and plugs flags/commands into CAC:

```ts
defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  clientAssets: './client/dist', // built SPA served as the UI
  cli: {
    command: 'my-tool', // binary name; default: the `id`
    port: 9876, // preferred port; default: 9999
    portRange: [9876, 10000], // forwarded to get-port-please
    random: false, // forwarded to get-port-please
    host: 'localhost', // default host; --host overrides
    open: true, // auto-open the browser on dev start; embeds the current OTP so the tab lands authenticated
    configure(cli) { // contribute capability flags/commands
      cli
        .option('--my-flag <value>', 'Tool-specific flag')
    },
  },
  setup(ctx, { flags }) {
    // `flags` carries the parsed cac bag: the built-in flags
    // (`--port`, `--host`, `--open`, `--no-open`) and anything you added
    // in `configure`.
  },
})
```

Beyond the fields shown, `random` prefers a random open port and `auth: false` disables the WS trust flow for localhost-only, single-user tools. Every field is listed in the [Node-Side API reference](/references/node-api#cli-options).

## Multiple runtimes, one definition

Wire the definition into multiple adapters from one file:

```ts
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { createBuild } from 'devframe/adapters/build'
import { createCac } from 'devframe/adapters/cac'

const myDevframe = defineDevframe({ id: 'my-tool', name: 'My Tool', setup() {} })

// 1. Standalone CLI:
await createCac(myDevframe).parse()

// 2. Offline snapshot:
await createBuild(myDevframe, { outDir: 'dist-static' })

/** 3. Mount into a host framework (Vite DevTools shown; others can implement equivalents): */
export const myPlugin = () => createPluginFromDevframe(myDevframe)
```

## What's next

- [Adapters](/adapters): deployment targets
- [RPC](/guide/rpc): register node-side functions
- [`vite` adapter](/adapters/vite): mount into a host framework

---
title: RPC
navigation:
  icon: i-lucide-repeat
description: Type-safe, bidirectional RPC built on birpc, validated against any Standard Schema validator. Dev runs over WebSocket; build/SPA serves a pre-computed static dump.
---

Type-safe, bidirectional RPC built on [`birpc`](https://github.com/antfu/birpc), validated against any [Standard Schema](https://standardschema.dev/) validator. Dev runs over WebSocket; build/SPA serves a pre-computed static dump.

## Defining a function

```ts
import { defineRpcFunction } from 'devframe'
import * as v from 'valibot' // npm i valibot (or use zod / arktype)

export const getModules = defineRpcFunction({
  name: 'get-modules', // bare: the scope namespaces it to `my-tool:get-modules`
  type: 'query',
  args: [v.object({ limit: v.number() })],
  returns: v.array(v.object({ id: v.string(), size: v.number() })),
  setup: ctx => ({
    handler: async ({ limit }) => {
      // `ctx` is the full DevframeNodeContext.
      return loadModules().slice(0, limit)
    },
  }),
})
```

Register it via a [scoped context](/guide/scoped-context); `ctx.scope(id)` auto-namespaces ids:

```ts
import { defineDevframe } from 'devframe'
import { getModules } from './rpc/functions/get-modules'

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  setup(ctx) {
    const my = ctx.scope('my-tool')
    my.rpc.register(getModules)
  },
})
```

### Naming convention

Scope with your devframe id, then a kebab-case action: `my-tool:get-modules`.

### Function types

A function's `type` sets its caching and [static-dump](#static-dumps) behavior: `query` for reads that change over time (caching opt-in via `cacheable`, dumping via an explicit `dump`), `static` for data fixed per input (cached indefinitely, dumped automatically), `action` for mutations, and `event` for fire-and-forget notifications. The full matrix is in the [Node-Side API reference](/references/node-api#rpc-function-types).

### Handler arguments

Handlers accept any serializable arguments. Declared `args` and `returns` schemas are enforced at runtime; extra object fields still reach the handler.

### Setup vs handler

Use `setup(ctx)` (returns `{ handler, dump? }`) when the handler needs `DevframeNodeContext`; otherwise the `handler(...)` shorthand.

## Broadcasting

`rpc.broadcast` sends to every connected RPC client; a scoped context namespaces the method:

```ts
defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  setup(ctx) {
    const my = ctx.scope('my-tool')
    watcher.on('change', (file) => {
      void my.rpc.broadcast({
        method: 'on-file-changed', // -> my-tool:on-file-changed
        args: [{ file }],
      })
    })
  },
})
```

Beyond `method` and `args`, `optional` skips throwing when no RPC client is listening, `event` makes the broadcast fire-and-forget, and `filter` skips specific RPC clients; see the [Node-Side API reference](/references/node-api#broadcast-options).

## Streaming

For node-side→browser-side chunk feeds, use [streaming channels](/guide/streaming):

```ts
const channel = ctx.rpc.streaming.create<string>('my-tool:chat', {
  replayWindow: 256,
})
const stream = channel.start()
sourceReadable.pipeTo(stream.writable)
```

## Local invocation

A scoped `rpc.call` invokes a node-side function directly, skipping the transport:

```ts
const my = ctx.scope('my-tool')
const modules = await my.rpc.call('get-modules', { limit: 10 })
```

It wraps `ctx.rpc.invokeLocal(...)`; a fully-qualified name (with `:`) calls another tool's function.

## Browser-side calls

From the browser, [`connectDevframe`](/guide/client) (or `getDevframeRpcClient`) returns an RPC client:

```ts
import { connectDevframe } from 'devframe/client'

const client = await connectDevframe()
const my = client.scope('my-tool')

const modules = await my.rpc.call('get-modules', { limit: 10 })
```

Browser-side registration (node side → browser side) uses `my.rpc.register()`.

## Type-safe RPC-client registry

Two augmentable interfaces, `DevframeRpcServerFunctions` (client→server) and `DevframeRpcClientFunctions` (server→client), type each registered name on the RPC client via `declare module 'devframe'`. Feed a const array through `RpcDefinitionsToFunctionsWithNamespace`, which prefixes each bare name with your id:

```ts
import type { RpcDefinitionsToFunctionsWithNamespace } from 'devframe/rpc'
import { getFile, getModules } from './rpc'

const serverFunctions = [getModules, getFile] as const

declare module 'devframe' {
  interface DevframeRpcServerFunctions
    extends RpcDefinitionsToFunctionsWithNamespace<'my-tool', typeof serverFunctions> {}
}
```

For fully namespaced names, use `RpcDefinitionsToFunctions<typeof serverFunctions>` (no namespace argument) with the unscoped `ctx.rpc.register`. For a one-off, declare a single key with `RpcFunctionDefinitionToFunction<typeof getModules>`.

Augment these interfaces where they live (`devframe` or `devframe/types`); a renamed re-export won't merge into the base.

## Static dumps

For `static` functions, Devframe records the handler output during `createBuild`:

```ts
defineRpcFunction({
  name: 'build-meta',
  type: 'static',
  args: [],
  returns: v.object({ version: v.string(), builtAt: v.number() }),
  setup: () => ({
    handler: async () => ({ version: '1.0.0', builtAt: Date.now() }),
  }),
})
```

For `query` functions, an explicit `dump` enumerates argument sets to pre-compute:

```ts
defineRpcFunction({
  name: 'get-session',
  type: 'query',
  setup: ctx => ({
    handler: async (id: string) => loadSession(id),
    dump: {
      inputs: [['session-a'], ['session-b']],
      fallback: { id: 'unknown', data: null },
    },
  }),
})
```

Static RPC clients resolve from the baked dump; unmatched arguments hit `dump.fallback` (or throw).

## JSON-serializable declaration

The WS transport picks one of two encoders per function:

| `jsonSerializable` | Encoder                 | Wire prefix    | Round-trips                                             |
| ------------------ | ----------------------- | -------------- | ------------------------------------------------------- |
| `false` (default)  | `structured-clone-es`   | `s:`           | `Map`, `Set`, `Date`, `BigInt`, cycles, class instances |
| `true` (opt-in)    | strict `JSON.stringify` | *(unprefixed)* | JSON-only                                               |

When every function is JSON-flagged, the wire stays plain JSON. A `jsonSerializable: true` handler must return JSON-only values; `Map`, `Date`, and friends won't round-trip.

## Agent exposure

Add an `agent` field to expose the function to coding agents over MCP:

```ts
defineRpcFunction({
  name: 'get-modules',
  type: 'query',
  args: [v.object({ limit: v.number() })],
  returns: v.array(v.object({ id: v.string(), size: v.number() })),
  agent: {
    description: 'List the N largest modules in the current build. Safe to call freely.',
    title: 'List modules',
    // safety inferred from type: 'query' → 'read'
  },
  setup: () => ({
    handler: async ({ limit }) => loadModules().slice(0, limit),
  }),
})
```

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

- [Shared State](/guide/shared-state): state synced across RPC clients
- [Client](/guide/client): connecting from the browser
- [Agent-Native](/guide/agent-native): exposing RPCs to coding agents

---
title: Shared State
navigation:
  icon: i-lucide-database-zap
description: 'Shared state is observable, immutable-by-default state synced between the node side and every RPC client, surviving reconnects: a new RPC client gets the snapshot.'
---

Shared state is observable, immutable-by-default state synced between the node side and every RPC client, surviving reconnects: a new RPC client gets the snapshot.

## Overview

```mermaid {theme="zinc-light" theme-dark="zinc-dark"}
flowchart LR
  subgraph ClientA["RPC client A"]
    A["state.value()"]
  end
  subgraph Server["Node side"]
    S["state.mutate(fn)"]
  end
  subgraph ClientB["RPC client B"]
    B["state.value()"]
  end
  S <-->|RPC sync| A
  S <-->|RPC sync| B

```

## Creating state

A [scoped context](/guide/scoped-context)'s `rpc.sharedState(key, options)` namespaces it:

```ts
import { defineDevframe } from 'devframe'

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  async setup(ctx) {
    const my = ctx.scope('my-tool')

    const state = await my.rpc.sharedState('state', { // -> my-tool:state
      initialValue: {
        count: 0,
        items: [] as { id: string, name: string }[],
      },
    })

    console.log(state.value().count) // 0
  },
})
```

The scope prefixes `<devframe-id>:` (wrapping `ctx.rpc.sharedState.get(...)`), so pass a bare key.

## Reading

`state.value()` returns an immutable snapshot.

```ts
const current = state.value()
console.log(current.count)
// current.count = 1 // ✗ TypeScript error: snapshot is Immutable<T>
```

## Mutating

Pass a recipe to `state.mutate()`:

```ts
state.mutate((draft) => {
  draft.count += 1
  draft.items.push({ id: 'a', name: 'Alpha' })
})
```

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)

Enable patches for minimal network diffs; `updated` then carries `Patch[]`:

```ts
const state = await ctx.rpc.sharedState.get('my-tool:big-state', {
  initialValue: largeTree,
  /** sharedState-level enablePatches is opt-in: */
  sharedState: createSharedState({ initialValue: largeTree, enablePatches: true }),
})
```

## Subscribing

```ts
state.on('updated', (fullState, patches, syncId) => {
  // `patches` is populated only when enablePatches is set.
})
```

## Client-side access

The same key is on the browser RPC client, scoped identically; browser-side mutations round-trip the node side, keeping `state.value()` authoritative.

```ts
import { connectDevframe } from 'devframe/client'

const my = (await connectDevframe()).scope('my-tool')

const state = await my.rpc.sharedState('state') // -> my-tool:state

console.log(state.value().count)

state.mutate((draft) => {
  draft.count += 1
})
```

## Enumerating keys

Both sides expose `keys()` and `onKeyAdded`:

```ts
for (const key of ctx.rpc.sharedState.keys()) {
  console.log(key)
}

const unsubscribe = ctx.rpc.sharedState.onKeyAdded((key) => {
  console.log('new shared-state key:', key)
})
```

Protocol adapters (e.g. [MCP](/guide/agent-native)) surface shared state as dynamic resources.

## Type-safe keys

Augment `DevframeRpcSharedStates` to type each key once; lookups stay typed:

```ts
declare module 'devframe' {
  interface DevframeRpcSharedStates {
    'my-tool:state': {
      count: number
      items: { id: string, name: string }[]
    }
  }
}
```

## When to use shared state vs RPC

| Use shared state for                                      | Use RPC for                                      |
| --------------------------------------------------------- | ------------------------------------------------ |
| Long-lived UI state (selections, filters, expanded nodes) | One-shot queries (`get-modules`, `read-file`)    |
| Coordination across RPC clients                           | Commands / actions with side effects             |
| Data that should reappear after reconnect                 | Event streams (prefer `broadcast` / `callEvent`) |

For actions and events, use `ctx.rpc.register` + `broadcast` ([RPC](/guide/rpc)).

---
title: Streaming
navigation:
  icon: i-lucide-radio
description: Streaming channels push chunk-style data from the node side to the browser side over the RPC socket.
---

Streaming channels push chunk-style data from the node side to the browser side over the RPC socket.

## Overview

```mermaid {theme="zinc-light" theme-dark="zinc-dark"}
sequenceDiagram
  participant Producer as Producer (node side)
  participant Channel as ctx.rpc.streaming<br/>channel
  participant Browser as Subscriber (browser)

  Producer->>Channel: start({ id })
  Channel-->>Browser: chunk(seq=1, "...")
  Channel-->>Browser: chunk(seq=2, "...")
  Producer->>Channel: close()
  Channel-->>Browser: end()

```

A **channel** owns a wire namespace; each `channel.start()` makes one **stream** keyed by an id (auto unless passed), joined by `(channelName, id)`.

## Defining a channel

```ts
import { defineDevframe, defineRpcFunction } from 'devframe'
import * as v from 'valibot' // npm i valibot

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  async setup(ctx) {
    const my = ctx.scope('my-tool')

    const channel = my.rpc.streaming.create<string>('chat', { // -> my-tool:chat
      replayWindow: 256,
    })

    my.rpc.register(defineRpcFunction({
      name: 'start-chat', // -> my-tool:start-chat
      type: 'action',
      jsonSerializable: true,
      args: [v.object({ prompt: v.string() })],
      returns: v.object({ streamId: v.string() }),
      handler: async ({ prompt }) => {
        const stream = channel.start()
        ;(async () => {
          for await (const token of fakeLLM(prompt, { signal: stream.signal })) {
            stream.write(token)
          }
          stream.close()
        })()
        return { streamId: stream.id }
      },
    }))
  },
})
```

## Producing: three APIs, one stream

```ts
const stream = channel.start({ id: 'optional-explicit-id' })

// Imperative: minimal, hand-rolled producers
stream.write(chunk)
stream.error(err) // terminal failure
stream.close() // terminal success
stream.signal // AbortSignal: flips when consumers cancel
stream.id // string: what RPC clients subscribe to

// Web Streams: pipe any ReadableStream<T> in:
sourceReadable.pipeTo(stream.writable, { signal: stream.signal })

// Convenience: start + pipe in one call:
const stream = await channel.pipeFrom(sourceReadable)
```

### Node stream interop

Node 17+ converters:

```ts
import { Readable, Writable } from 'node:stream'

// Pipe a Node Readable into the streaming channel
sourceNodeReadable.pipe(Writable.fromWeb(stream.writable))

// Pipe the channel out to a Node Writable
Readable.fromWeb(reader.readable).pipe(targetNodeWritable)
```

## Consuming: `for await` or `pipeTo`

The reader is an `AsyncIterable<T>` also exposing `.readable` (`ReadableStream<T>`), one per reader.

```ts
import { connectDevframe } from 'devframe/client'

const my = (await connectDevframe()).scope('my-tool')
const { streamId } = await my.rpc.call('start-chat', {
  prompt: 'Hello',
})

const reader = my.rpc.streaming.subscribe<string>('chat', streamId) // -> my-tool:chat

// Async iterable: the simplest consumer pattern
for await (const token of reader)
  appendToken(token)

// Or pipe to a DOM-side WritableStream
await reader.readable.pipeTo(downloadWritable)

reader.cancel() // sends cancel upstream; the node-side stream.signal flips
```

## Lifecycle and cancellation

`stream.close()` / `stream.error(err)` broadcast `end`, resolving (or throwing inside) the browser-side `for await`. Cancellation flows upstream: `reader.cancel()`, or the **last** subscriber's WS dropping, aborts `stream.signal`; a disconnected reader survives and resubscribes on re-trust. The event-by-event matrix is in the [Node-Side API reference](/references/node-api#streaming-lifecycle).

## Browser-to-node uploads

In reverse: an RPC call allocates the id; events carry chunks.

```ts
// Node side: typically inside an action handler
ctx.rpc.register(defineRpcFunction({
  name: 'my-tool:upload-file',
  type: 'action',
  args: [v.object({ name: v.string() })],
  returns: v.object({ uploadId: v.string() }),
  handler: async ({ name }) => {
    const reader = channel.openInbound()

    // Process chunks asynchronously; the action returns immediately
    // so the browser side can start uploading.
    ;(async () => {
      const file = createWriteStream(name)
      for await (const chunk of reader)
        file.write(chunk)
      file.close()
    })()

    return { uploadId: reader.id }
  },
}))
```

```ts
// Browser side
const { uploadId } = await my.rpc.call('upload-file', {
  name: 'capture.bin',
})
const upload = my.rpc.streaming.upload<Uint8Array>('files', uploadId) // -> my-tool:files

// Imperative
upload.write(chunk1)
upload.write(chunk2)
upload.close()

// Or pipe a Web ReadableStream straight in:
fileReadable.pipeTo(upload.writable, { signal: upload.signal })
```

Lifecycle mirrors outbound: `upload.signal` aborts on `reader.cancel()` (broadcasting `upload-cancel`), `upload.error(err)` throws inside its `for await`, and an RPC-client disconnect exits with `UploadDisconnected`. Each `openInbound()` id is point-to-point: one producer, no fan-in or replay.

## Replay on reconnect

With `replayWindow: N`, the node side keeps the last `N` chunks; a resubscribing RPC client sends its highest seen sequence and the node side replays newer ones.

```ts
my.rpc.streaming.create<string>('chat', { // -> my-tool:chat
  replayWindow: 256, // chunks to retain per stream id
  closedStreamRetention: 30_000, // ms to hold closed streams for late subscribers
})
```

`closedStreamRetention` defaults to 30 s when `replayWindow > 0`.

## Backpressure

The RPC client keeps a bounded queue per subscription (`highWaterMark`, default 256); when the consumer falls behind, the oldest chunk drops, logging [`DF0029`](/errors/DF0029).

```ts
const reader = my.rpc.streaming.subscribe('chat', id, { // -> my-tool:chat
  highWaterMark: 1024, // raise if you expect bursts the consumer can recover from
})
```

## Streaming vs events vs shared state

| Streaming                            | `event`-typed RPC                               | Shared state                  |
| ------------------------------------ | ----------------------------------------------- | ----------------------------- |
| Token/chunk feeds (LLM deltas, logs) | Payload-less notifications (`refresh`, `clear`) | Long-lived UI state           |
| Per-call lifecycles, cancellation    | Cross-cutting signals                           | Snapshots surviving reconnect |
| Replay on reconnect                  | Fire-and-forget                                 | Diff-based sync               |
| Browser→node uploads (files, mic)    |                                                 |                               |

## Reference

- `RpcStreamingHost`, `RpcStreamingChannel<T>`, `StreamSink<T>`, `StreamReader<T>` in `devframe/types`.
- [`examples/streaming-chat`](https://github.com/devframes/devframe/tree/main/examples/streaming-chat).
- Errors: [`DF0029`](/errors/DF0029) (overflow), [`DF0030`](/errors/DF0030) (unknown id), [`DF0031`](/errors/DF0031) (write to closed), [`DF0032`](/errors/DF0032) (name collision).

---
title: Client Assets
navigation:
  icon: i-lucide-folder
description: 'A devframe''s UI is a built SPA; clientAssets says where it lives: a local directory or published npm package.'
---

A devframe's UI is a built SPA; `clientAssets` says where it lives: a **local directory** or **published npm package**.

## Mounting a local build

Point `clientAssets` at your SPA build directory, resolved from the module:

```ts
import { fileURLToPath } from 'node:url'
import { defineDevframe } from 'devframe'
import pkg from '../package.json' with { type: 'json' }

export default defineDevframe({
  id: 'my-tool',
  version: pkg.version,
  packageName: pkg.name,
  clientAssets: fileURLToPath(new URL('../dist/spa', import.meta.url)),
  setup(ctx) {
    // …
  },
})
```

devframe serves it with SPA fallback (unknown paths → `index.html`) and no-store dev caching. Build the SPA with a relative base (`vite: { base: './' }`); it reads its runtime base from `document.baseURI`.

The [`dev`](/adapters/dev), [`build`](/adapters/build), and [Vite](/frameworks/vite) adapters all read `clientAssets`.

## Programmatic hosting from `setup`

To host assets beyond the *primary* UI, use `ctx.views.hostStatic`:

```ts
export default defineDevframe({
  id: 'my-tool',
  version: pkg.version,
  packageName: pkg.name,
  importMetaUrl: import.meta.url,
  clientAssets: fileURLToPath(new URL('../dist/spa', import.meta.url)),
  setup(ctx) {
    // Serve an extra static bundle at a sibling base.
    ctx.views.hostStatic(
      '/docs/',
      fileURLToPath(new URL('../dist/docs', import.meta.url)),
    )

    // A remote source works here too, same shape as `clientAssets`.
    ctx.views.hostStatic('/legacy/', {
      package: '@acme/my-tool-legacy-ui',
      version: pkg.version,
    })
  },
})
```

`hostStatic(baseUrl, source, defaultResolveFrom?)` takes `clientAssets`'s `StaticAssetsSource`; `dev` registers middleware live, `build` copies into the static output.

## Remote assets

Give `clientAssets` a `RemoteAssets` object naming a **published npm package** and exact version:

```ts
import type { RemoteAssets } from 'devframe'
import { defineDevframe } from 'devframe'
import pkg from '../package.json' with { type: 'json' }

const clientAssets: RemoteAssets = {
  package: '@acme/my-tool-assets',
  version: pkg.version,
}

export default defineDevframe({
  id: 'my-tool',
  version: pkg.version,
  packageName: pkg.name,
  importMetaUrl: import.meta.url,
  clientAssets,
  setup(ctx) {
    // …
  },
})
```

The definition's [`importMetaUrl`](/guide/devframe-definition#resolving-against-the-devframes-own-dependencies) is the resolution base.

### How assets resolve

Per request, resolution tries in order:

1. **Locally installed package**: resolved from `resolveFrom` (default `importMetaUrl`); served with no network.
2. **On-disk cache**: files already fetched, under the project's storage directory.
3. **CDN back-proxy**: [jsDelivr](https://www.jsdelivr.com/) by default; exact-version URLs are immutable, so caches never stale.

### Options

`package` and `version` (exact) name the published assets; `resolveFrom`, `path`, `provider`, and `offline` tune resolution; every field is in the [Node-Side API reference](/references/node-api#remote-assets-options).

An invalid npm name or non-exact version throws [`DF0065`](/errors/DF0065).

### Offline and air-gapped use

Install the assets package explicitly; step 1 serves it locally. Set `offline: true` to never contact the CDN, or point `provider` at a mirror:

```sh
npm install @acme/my-tool-assets
```

### When the assets can't be reached

A file absent from local install and cache, with the provider unreachable, raises [`DF0060`](/errors/DF0060); an HTML navigation gets a self-contained error page.

It also posts the failure to `window.parent` (`DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE` from `devframe/constants`, payload `RemoteAssetsErrorMessage`) for an embedding hub UI provider like [`@devframes/hub-ui`](/guide/build-your-own-hub-ui).

### Custom provider

A custom provider supplies the file URL, optionally a listing:

```ts
const clientAssets: RemoteAssets = {
  package: '@acme/my-tool-assets',
  version: pkg.version,
  provider: {
    fileUrl: (name, version, file) =>
      `https://npm.internal.acme.com/${name}@${version}/${file}`,
  },
}
```

### Publishing the assets

An ordinary npm package ships the built UI under `path` (default `dist`) and exposes its `package.json` for the resolver:

```json
{
  "name": "@acme/my-tool-assets",
  "version": "1.0.0",
  "exports": { "./package.json": "./package.json" },
  "files": ["dist"]
}
```

Keep its version in lockstep with the tool.

---
title: Scoped Context
navigation:
  icon: i-lucide-box
description: 'A scoped context is a namespaced view of the context: it auto-prefixes every RPC id, shared-state key, and streaming channel with your tool''s id, and adds a typed, persisted settings store, used from a single tool''s code.'
---

A scoped context is a namespaced view of the context: it auto-prefixes every RPC id, shared-state key, and streaming channel with your tool's id, and adds a typed, persisted `settings` store, used from a single tool's code.

## Node side

`setup(ctx)` receives the full `DevframeNodeContext`; scope it with `ctx.scope(id)`, conventionally your devframe `id`:

```ts
import { defineDevframe, defineRpcFunction } from 'devframe'

export default defineDevframe({
  id: 'my-plugin',
  name: 'My Plugin',
  setup(ctx) {
    const my = ctx.scope('my-plugin')

    my.rpc.register(defineRpcFunction({
      name: 'get-modules', // bare name: stored as `my-plugin:get-modules`
      type: 'query',
      handler: () => loadModules(),
    }))
  },
})

declare function loadModules(): { id: string }[]
```

`ctx.scope(id)` is stable per id, re-exposing unscoped APIs (`views`, `diagnostics`, `agent`, `host`, `cwd`, `mode`), swapping in the auto-namespaced `rpc`, and keeping the original as `my.base`.

## Browser side

`(await connectDevframe()).scope(id)` gives the matching view: `my.rpc` carries `call` / `callEvent` / `callOptional`, `register`, `sharedState`, and `streaming`, plus `my.settings`.

## Auto-namespacing

Bare names are prefixed `<namespace>:` (`call('get-modules')` → `my-plugin:get-modules`); a name with `:` passes through unchanged to another tool (`call('other-plugin:status')`).

`register` accepts only bare names; an already-namespaced one throws [`DF0034`](/errors/DF0034); use `ctx.base.rpc.register`.

Bare names stay typed: `call('get-modules')` resolves to your [RPC registry](/guide/rpc#type-safe-rpc-client-registry) entry, `sharedState('selection')` to the matching [`DevframeRpcSharedStates`](/guide/shared-state#type-safe-keys) key.

## Settings

`my.settings` is a persisted key-value store (alongside `my.rpc`), with two scopes:

- **`project`**: per-checkout values, under the `workspace` storage dir.
- **`global`**: per-user values, under the `global` storage dir.

Both are file-backed and synced to the browser over the shared-state protocol; a `set` propagates to peers, surviving restarts.

```ts
const { settings } = my

await settings.project.set('theme', 'dark')
await settings.project.get('theme') // => 'dark'
await settings.project.all() // => theme is 'dark'
await settings.project.delete('theme')

const off = await settings.global.onChange((value) => {
  console.log('global settings changed', value)
})
```

Every method is async; the store resolves on first access.

### Typed settings

Augment `DevframeSettingsRegistry` to type a namespace's settings once; the scope types `settings.global` and `settings.project`:

```ts
declare module 'devframe' {
  interface DevframeSettingsRegistry {
    'my-plugin': {
      theme: 'light' | 'dark'
      recentFiles: string[]
    }
  }
}
```

```ts
const my = ctx.scope('my-plugin')
await my.settings.project.set('theme', 'dark') // ✓ typed
await my.settings.project.set('theme', 'blue') // ✗ not assignable
```

Unaugmented namespaces fall back to an open record.

## What's next

- [RPC](/guide/rpc)
- [Shared State](/guide/shared-state)
- [Client](/guide/client)

---
title: JSON-Render
navigation:
  icon: i-lucide-braces
description: 'JSON-render describes a UI as data: a serializable component spec any frontend renders. Opt-in: a plain devframe pulls zero JSON-render dependencies. Two packages:'
---

JSON-render describes a UI as **data**: a serializable component spec any
frontend renders. **Opt-in**: a plain devframe pulls zero JSON-render
dependencies. Two packages:

- **`@devframes/json-render`**: framework-neutral protocol layer (spec/catalog
types, prop schemas, view refs, node runtime), built on
[`@json-render/core`](https://www.npmjs.com/package/@json-render/core).
- **`@devframes/json-render-ui`**: reference Vue frontend implementing the
base catalog with [`@antfu/design`](https://github.com/antfu/design).

## Authoring a view

`createJsonRenderView` registers the spec as shared state, returning a handle:

```ts
import { createJsonRenderView } from '@devframes/json-render/node'

export default defineDevframe({
  /** … */
  setup(ctx) {
    const view = createJsonRenderView(ctx, {
      id: 'metrics', // stable, unique within the scope
      spec: {
        root: 'root',
        elements: {
          root: { type: 'Card', props: { title: 'Live metrics' }, children: ['count'] },
          count: { type: 'Text', props: { text: { $state: '/count' } }, children: [] },
        },
        state: { count: 0 },
      },
    })

    // A structural change replaces the whole spec…
    view.update(nextSpec)
    // …while state travels as JSON-Pointer patches (only the changed path crosses the wire).
    view.patchState([{ op: 'replace', path: '/count', value: 3 }])

    // Unregisters the shared state and its listeners.
    // view.dispose()
  },
})
```

The view id is scoped `devframe:json-render:<scope>:<id>`, `scope` defaulting to
the namespace or `global`. Diagnostics fire on invalid props
([DF0038](/errors/DF0038)), duplicate id ([DF0039](/errors/DF0039)), disposed-view
use ([DF0040](/errors/DF0040)), non-serializable spec
([DF0041](/errors/DF0041)).

## The base catalog

Catalog v1 ships fourteen components: `Stack`, `Card`, `Text`, `Badge`,
`Button`, `Icon`, `Divider`, `TextInput`, `Switch`, `KeyValueTable`,
`DataTable`, `CodeBlock`, `Progress`, `Tree`. A spec **is** an `@json-render/core`
`Spec` plus a per-component Zod prop schema (`basePropSchemas`), validated at
ingress (node side) and render time (browser side); `$state` / `$bindState`
bindings work on scalar props.

## Actions and state

- **State** is a JSON-serializable `Record<string, unknown>` addressed by JSON
Pointer.
- **Actions** are unrestricted: an element event dispatches an RPC call of the
same name, with no allowlist.
- **Reserved built-ins** (`setState`, `pushState`, `removeState`,
`validateForm`) are handled client-side, never bridged to RPC.

## Rendering standalone

### Out-of-box SPA (no client build)

`createJsonRenderDevframe` points `clientAssets` at the prebuilt
`@devframes/json-render-ui/spa` renderer:

```ts
import { createJsonRenderDevframe } from '@devframes/json-render-ui/spa'
import { createJsonRenderView } from '@devframes/json-render/node'

export default createJsonRenderDevframe({
  id: 'my-app',
  name: 'My App',
  version,
  packageName,
  homepage,
  description,
  cli: { command: 'my-app', port: 9800 },
  setup(ctx) {
    createJsonRenderView(ctx, { id: 'main', title: 'Dashboard', spec })
  },
})
```

The SPA discovers views from the **view index** (`JSON_RENDER_INDEX_KEY`); one
view renders full-bleed, multiple get a `title`-labeled switcher.

### Custom frontend

A custom frontend renders from shared state: connect with `connectDevframe()`,
read the view's state (keyed `devframe:json-render:<scope>:<id>`), subscribe to
`updated` events, and render with your registry; the [Next
hub example](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next) has a React renderer. In a
**static** build spec + state are read-only: actions unavailable, local
state and bindings still work.

### The reference frontend

`@devframes/json-render-ui` ships prebuilt `/spa` and `/hub` bundles.

## Rendering inside a hub

`@devframes/json-render/hub` adds a `json-render` dock type:

```ts
// node side: register a dock entry carrying the view's serializable reference,
// and compose the frontend as a prebuilt renderer module
import { jsonRenderUiRenderer } from '@devframes/json-render-ui/hub'
import { toJsonRenderDockEntry } from '@devframes/json-render/hub'

initHub({
  ui: createUi(),
  renderers: [jsonRenderUiRenderer()],
  configure(ctx) {
    ctx.docks.register(toJsonRenderDockEntry(view, {
      id: 'metrics',
      title: 'Metrics',
      icon: 'ph:chart-bar-duotone',
    }))
  },
})
```

The hub publishes the module in the [renderer
manifest](/guide/hub-initiate#renderer-modules), lazily imported on first mount (else a
missing-renderer fallback). A host page can register a
`JsonRenderDockRenderer` **locally** instead, overriding the manifest:

```ts
// host page: a locally-bundled frontend wins over the manifest module
import { createDevframeClientRuntime } from '@devframes/hub/client'
import { myJsonRenderDockRenderer } from './my-renderer'

const host = await createDevframeClientRuntime({
  renderers: { 'json-render': myJsonRenderDockRenderer },
})

// the hub UI provider mounts the active dock entry into a container it owns
const result = await host.context.renderers.mount(entry, container)
if (result.status === 'mounted')
  result.dispose // tear down when the hub UI provider decides; deactivation disposes too
```

The dock entry carries a serializable `JsonRenderViewRef` in two shapes: `{ stateKey }`
points at live shared state (`createJsonRenderView`); `{ spec }` embeds it inline
for a browser-synthesized [client-only dock](/guide/client-context#client-only-docks).

## Swapping the frontend

`@devframes/json-render/hub` exports the contract, `JsonRenderDockRenderer` and
`JsonRenderDockMountOptions`; `@devframes/json-render-ui` is the pluggable
reference implementation.
See [Build your own JSON-Render frontend](/guide/build-your-own-json-render-frontend)
and the [`json-render` example](https://github.com/devframes/devframe/tree/main/examples/json-render).

---
title: Structured Diagnostics
navigation:
  icon: i-lucide-stethoscope
description: ctx.diagnostics is a thin layer over nostics for author-defined coded diagnostics, each with a stable code, docs URL, and structured payload.
---

`ctx.diagnostics` is a thin layer over [`nostics`](https://www.npmjs.com/package/nostics) for author-defined coded diagnostics, each with a stable code, docs URL, and structured payload.

| Surface                                                  | Purpose                                                          | Example                              |
| -------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------ |
| `ctx.diagnostics`                                        | Coded errors and warnings emitted from node-side code            | `MYP0001: Plugin foo not configured` |
| [`ctx.messages`](https://devtools.vite.dev/kit/messages) | Free-form, user-facing notifications shown in the Messages panel | `'Audit complete: 3 issues found'`   |

## Shape

```ts
interface DevframeDiagnosticsHost {
  /** Proxy-backed lookup over every registered code. */
  readonly logger: Record<string, DiagnosticHandle>

  /** Register additional diagnostic definitions. */
  register: (definitions: Record<string, unknown>) => void

  /** Build a typed diagnostics object with devframe's ANSI reporter pre-wired. */
  defineDiagnostics: typeof defineDiagnostics
}
```

The diagnostics host ships pre-seeded with devframe's `DF*` codes plus the host framework's own (`DTK*`, etc.); call `register()` to add your own.

## Register your own codes

```ts
export function MyPlugin(): PluginWithDevTools {
  return {
    name: 'my-plugin',
    devtools: {
      setup(ctx) {
        const myDiagnostics = ctx.diagnostics.defineDiagnostics({
          docsBase: 'https://example.com/errors',
          codes: {
            MYP0001: {
              why: (p: { name: string }) => `Plugin "${p.name}" is not configured`,
              fix: 'Add the plugin to your `vite.config.ts` and pass an options object.',
            },
            MYP0002: {
              why: 'Cache directory missing; running cold.',
            },
          },
        })

        ctx.diagnostics.register(myDiagnostics)

        // Emit through the host framework's shared reporter:
        myDiagnostics.MYP0002()
      },
    },
  }
}
```

## Code conventions

Codes are a 4-letter prefix + 4-digit number (e.g. `MYP0001`); pick one distinctive enough to avoid collisions.

`DF` belongs to `devframe` itself; the `@vitejs/devtools` packages own `DTK`, `RDDT`, and `VDT`. The prefixes in use are listed in the [Node-Side API reference](/references/node-api#diagnostic-code-prefixes).

A definition takes a `why` (message) and optional `fix` (resolution), string or function; `docsBase` auto-attaches the URL to each diagnostic.

## Emit a diagnostic

Each registered code becomes a callable `DiagnosticHandle`: call it to report, or `throw` to raise.

```ts
// Throw: control flow stops here
throw myDiagnostics.MYP0001({ name: 'foo' })

// Report without throwing (default console method: `warn`)
myDiagnostics.MYP0002()

// Override the console method per call
myDiagnostics.MYP0002({}, { method: 'error' })

// Attach a `cause`: merged into the params object
throw myDiagnostics.MYP0001({ name: 'foo', cause: error })
```

The returned `Diagnostic` extends `Error`, so `throw` narrows following lines as unreachable.

## Typed handle reference

`ctx.diagnostics.logger` is loosely typed over all registered codes; for autocompletion, keep and call the typed result of `defineDiagnostics()` directly, whose pre-wired ANSI reporter gives it and the lookup identical output.

## Document your codes

Pair each code with a documentation page:

```
docs/errors/
  index.md            # Table of all codes
  MYP0001.md          # One page per code
  MYP0002.md
```

Each page covers message, cause, example, and fix; see any [DF code page](https://devfra.me/errors/) for the template.

## When to use what

**`ctx.diagnostics`** covers coded, docs-backed conditions, targeting tool authors and CI; **`ctx.messages`** covers user-facing UI activity, targeting the human at the panel.

---
title: Standalone CLI with Devframe
navigation:
  icon: i-lucide-terminal
description: npx my-tool starts a dev server serving a Vue/Nuxt/React SPA over type-safe RPC, plus build/mcp.
---

`npx my-tool` starts a dev server serving a Vue/Nuxt/React SPA over type-safe RPC, plus `build`/`mcp`.

## What you ship

```
my-tool/
├── bin.mjs                  # shebang + import './dist/cli.mjs'
├── src/
│   ├── cli.ts               # defineDevframe + createCac
│   ├── rpc.ts               # your RPC function definitions
│   └── data.ts              # your domain-specific logic
├── app/                     # Nuxt / Vue / React SPA source
├── dist/
│   ├── public/              # built SPA output (served at /)
│   └── cli.mjs              # bundled node entry
└── package.json
```

## Minimal CLI

```ts [src/cli.ts]
import process from 'node:process'
import { defineDevframe, defineRpcFunction } from 'devframe'
import { createCac } from 'devframe/adapters/cac'
import { colors as c } from 'devframe/utils/colors'
import { resolve } from 'pathe'

const clientAssets = resolve(import.meta.dirname, '../dist/public')

const myDevframe = defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  clientAssets,
  cli: {
    command: 'my-tool',
    port: 7777,
    portRange: [7777, 9000],
    open: true, // auth defaults to on; `--open` embeds the current OTP so the tab lands authenticated
    configure(cli) {
      cli
        .option('--config <file>', 'Config file path')
        .option('--base-path <dir>', 'Base directory for resolution')
    },
  },
  async setup(ctx, { flags }) {
    const my = ctx.scope('my-tool')
    my.rpc.register(defineRpcFunction({
      name: 'get-payload', // -> my-tool:get-payload
      type: 'query',
      async handler() {
        return await loadPayload({
          configPath: flags.config,
          basePath: flags.basePath,
        })
      },
    }))
  },
})

await createCac(myDevframe, {
  onReady({ origin }) {
    console.log(c.green`My Tool ready at ${origin}`)
  },
}).parse(process.argv)
```

Run:

```sh
my-tool                                     # dev server at http://localhost:7777/
my-tool --config ./my.config.mjs
my-tool --port 8080 --no-open
my-tool build --out-dir dist-static         # self-contained static deploy
my-tool build --out-dir dist-static --base /tool/  # …under a custom base
my-tool mcp                                 # agent exposure
```

## Nuxt SPA setup

The Nuxt helper sets `app.baseURL: './'` / `vite.base: './'` and wires `connectDevframe()` into `$rpc` ([Nuxt docs](/frameworks/nuxt)).

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  ssr: false,
  modules: ['@devframes/nuxt/single'],
  nitro: {
    preset: 'static',
    output: { dir: './dist' }, // matches the definition's clientAssets of ./dist/public
  },
})
```

## Next.js SPA setup

For a Next.js App Router SPA, static export needs:

```js [next.config.mjs]
/** @type {import('next').NextConfig} */
export default {
  output: 'export',
  assetPrefix: '.',
  trailingSlash: true,
  images: { unoptimized: true },
}
```

`assetPrefix: '.'` keeps assets base-agnostic; `trailingSlash: true` emits `foo/index.html` for directory-with-index resolution. Copy `next build`'s `out/` to `clientAssets`:

```json [package.json]
{
  "scripts": {
    "build": "next build src/client && rm -rf dist/client && mkdir -p dist && cp -r src/client/out dist/client"
  }
}
```

```ts [src/cli.ts]
import { fileURLToPath } from 'node:url'

defineDevframe({
  id: 'my-tool',
  clientAssets: fileURLToPath(new URL('../dist/client', import.meta.url)),
  // …
})
```

Call `connectDevframe()` in a Client Component; see [Client](/guide/client) and [`examples/next-runtime-snapshot`](https://github.com/devframes/devframe/tree/main/examples/next-runtime-snapshot).

## Connecting from the browser side

With the Nuxt helper, use `$rpc`:

```ts [app/composables/payload.ts]
export async function fetchPayload() {
  const { $rpc } = useNuxtApp()
  return $rpc.call('my-tool:get-payload')
}
```

Otherwise call `connectDevframe()`, which auto-resolves the connection descriptor relative to the page, whether dev (WebSocket) or static snapshot:

```ts
import { connectDevframe } from 'devframe/client'

const my = (await connectDevframe()).scope('my-tool')
const payload = await my.rpc.call('get-payload')
```

## Typed CLI flags

Declare tool flags with any [Standard Schema](https://standardschema.dev/) validator (valibot/zod/arktype), validated at parse and typed at the call site:

```ts
import type { InferCliFlags } from 'devframe/adapters/cac'
import { defineDevframe } from 'devframe'
import { defineCliFlags } from 'devframe/adapters/cac'
import * as v from 'valibot' // npm i valibot

const appFlags = defineCliFlags({
  depth: v.pipe(v.number(), v.integer()),
  config: v.optional(v.string()),
  verbose: v.optional(v.boolean()),
})

defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  clientAssets,
  cli: {
    flags: appFlags,
  },
  setup(ctx, info) {
    const flags = info.flags as InferCliFlags<typeof appFlags>
    flags.depth // number
    flags.config // string | undefined
  },
})
```

Booleans become `--verbose` / `--no-verbose`, else `--depth <value>`; keys are camelCase in TS, kebab-case on the CLI (`configFile` → `--config-file`). Flags outside the schema pass through.

## Snapshot queries for static builds

For an RPC function returning one payload per build, set `snapshot: true`; the build adapter runs the handler once, baking the result in:

```ts
defineRpcFunction({
  name: 'my-tool:get-payload',
  type: 'query',
  snapshot: true,
  handler() {
    return scanPackages(flags.root)
  },
})
```

It's the no-args fallback for any deployed `rpc.call('my-tool:get-payload', …)`; a normal `query` in dev.

## On-disk caching

Persistence is your tool's job ([`unstorage`](https://unstorage.unjs.io/) recommended); keep cache paths under `node_modules/.cache/<your-devtool-id>/` to rotate with `pnpm install`.

```ts
import { resolve } from 'pathe'
import { createStorage } from 'unstorage'
import fsDriver from 'unstorage/drivers/fs'

const cache = createStorage({
  driver: fsDriver({
    base: resolve(process.cwd(), 'node_modules/.cache/my-tool'),
  }),
})

defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  async setup(ctx) {
    ctx.scope('my-tool').rpc.register(defineRpcFunction({
      name: 'get-npm-meta', // -> my-tool:get-npm-meta
      type: 'query',
      async handler(spec: string) {
        return (await cache.getItem(spec))
          ?? await fetchAndCache(spec, cache)
      },
    }))
  },
})
```

## Live-reload on config changes

Filesystem watching is your tool's job: wire chokidar, signal the browser side via shared state.

```ts [src/cli.ts]
defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  async setup(ctx, { flags }) {
    const my = ctx.scope('my-tool')
    my.rpc.register(defineRpcFunction({
      name: 'get-payload', // -> my-tool:get-payload
      type: 'query',
      cacheable: true,
      handler: () => loadPayload({ configPath: flags.config }),
    }))

    if (ctx.mode === 'dev') {
      const version = await my.rpc.sharedState('version', { initialValue: { ts: 0 } })
      const { default: chokidar } = await import('chokidar')
      const watcher = chokidar.watch(flags.config ?? [], { ignoreInitial: true })
      watcher.on('change', () => {
        version.mutate((draft) => {
          draft.ts = Date.now()
        })
      })
    }
  },
})
```

On the browser side:

```ts
const my = (await connectDevframe()).scope('my-tool')
const version = await my.rpc.sharedState('version')
version.on('updated', () => fetchPayload().then(setData))
```

## Use your own CLI framework

Own a CLI framework (commander, yargs, oclif)? Use the three factories `createCac` wraps against one `DevframeDefinition`: `createDevServer` (`devframe/adapters/dev`), `createBuild` (`devframe/adapters/build`), and `createMcpServer` (`devframe/adapters/mcp`); see the [CLI adapter](/adapters/cac#use-your-own-cli-framework).

```ts [src/cli.ts]
import process from 'node:process'
import { Command } from 'commander'
import { defineDevframe } from 'devframe'
import { createBuild } from 'devframe/adapters/build'
import { createDevServer } from 'devframe/adapters/dev'

const myDevframe = defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  clientAssets: './dist/public',
  cli: { port: 7777 },
  setup(ctx, { flags }) { /* ... */ },
})

const program = new Command('my-tool')

program
  .command('dev', { isDefault: true })
  .option('-p, --port <port>', 'Port', '7777')
  .option('--config <file>', 'Config file path')
  .action(async (opts) => {
    const handle = await createDevServer(myDevframe, {
      port: Number(opts.port),
      flags: { config: opts.config },
      onReady: ({ origin }) => console.log(`Ready at ${origin}`),
    })
    process.on('SIGINT', () => handle.close().then(() => process.exit(0)))
  })

program
  .command('build')
  .option('--out-dir <dir>', 'Output directory', 'dist-static')
  .action(opts => createBuild(myDevframe, { outDir: opts.outDir }))

await program.parseAsync()
```

`createDevServer` returns a `StartedServer` handle (`origin`, `port`, `app`, `ws`, `rpcGroup`, `connectionMeta()`, `close()`). For typed flags, `parseCliFlags(schema, rawBag)` (`devframe/adapters/cac`) validates a commander/yargs bag against the `cli.flags` `CliFlagsSchema`.

## See also

- [Devframe Definition](/guide/devframe-definition)
- [Adapters → CLI (cac)](/adapters/cac): `configureCli`, mount-path rules
- [Adapters → Dev](/adapters/dev)
- [Client](/guide/client)
- [Agent-Native](/guide/agent-native)

---
title: Client
navigation:
  icon: i-lucide-globe
description: The RPC client connects any surface (dock iframe, remote page, standalone SPA) to a devframe's node side with type-safe RPC, shared state, and a trust handshake.
---

The RPC client connects any surface (dock iframe, remote page, standalone SPA) to a devframe's node side with type-safe RPC, shared state, and a trust handshake.

## Connecting

`devframe/client` exports `connectDevframe` (an alias of `getDevframeRpcClient`):

```ts
import { connectDevframe } from 'devframe/client'

const rpc = await connectDevframe()

const modules = await rpc.call('my-tool:get-modules', { limit: 10 })
```

At the default mount path, `connectDevframe` needs no arguments; it auto-detects the backend via `__devframe/__connection.json`.

### Runtime basePath discovery

One SPA artifact serves at `/`, `/__<id>/`, or any subpath, no rebuild. Build with relative asset paths: Vite `base: './'`, Nuxt `vite.base: './'` + `app.baseURL: './'`.

### Sharing a connection with an external viewer

`setupDevframeConnection()` prepares a serializable connection for an external viewer:

```ts
import { setupDevframeConnection } from 'devframe/client'

const connection = await setupDevframeConnection({
  baseURL: '/__devframe/',
})
```

In the external viewer:

```ts
import { connectDevframe } from 'devframe/client'

const rpc = await connectDevframe({ connection })
```

The RPC client retains it as `rpc.connection`; cross-realm viewers read it via `getDevframeConnection()` or `DEVFRAME_CONNECTION_KEY` (`devframe/constants`).

An external viewer registers its origin before the WebSocket opens (needs `viewerOriginToken` in the host framework's connection metadata; see [External viewer origins](/guide/security#external-viewer-origins)):

```ts
import { registerDevframeViewerOrigin } from 'devframe/client'

await registerDevframeViewerOrigin(connection)
```

### Options

`baseURL` points at the mount path to probe for `__connection.json` (default `'./'`, relative to `document.baseURI`); `connection` adopts one prepared by `setupDevframeConnection()`. The rest cover auth (`authToken`), [caching](#caching) (`cacheOptions`), timeouts (`callTimeout`), transport hooks (`wsOptions`), `birpc` passthrough (`rpcOptions`), and discovery override (`connectionMeta`); every option is in the [Browser-Side API reference](/references/browser-api#connectdevframe-options).

## Modes

Per the `__devframe/__connection.json` backend:

| Backend     | When                        | Capabilities                                                       |
| ----------- | --------------------------- | ------------------------------------------------------------------ |
| `websocket` | Dev mode (`createCac`, Kit) | Full read/write, broadcasts, shared-state mutation. Requires auth. |
| `static`    | Build / SPA output          | Read-only: all calls resolve against the baked RPC dump.           |

## Trust & auth (WebSocket mode)

`ensureTrusted()` resolves once the node side trusts the RPC client's stored token:

```ts
const rpc = await connectDevframe()

// Blocks until the node side trusts this RPC client (default timeout 60s)
const trusted = await rpc.ensureTrusted()

if (!trusted) {
  console.warn('Not authenticated yet')
}
```

`connectDevframe()` starts the handshake without blocking; `rpc.call` / `rpc.callOptional` / `rpc.callEvent` hold anything issued before it settles.

### 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) 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')
```

A host framework can embed the code in a link (`buildOtpAuthUrl(origin)`); `connectDevframe` reads the `devframe_otp` fragment, exchanges it, and strips the URL. Rename it with `otpParam`, or set `otpParam: false` to drive it yourself via `authenticateWithUrlOtp(rpc)` / `consumeOtpFromUrl()`.

### Re-using an existing token

Authenticate with a token obtained elsewhere, without reloading:

```ts
const ok = await rpc.requestTrustWithToken('a1b2c3…')
```

### Broadcast-channel sync

`connectDevframe` listens on a shared `BroadcastChannel` (`devframe-auth`) for `auth-update` messages; one tab authenticating trusts every open RPC client.

## Calling functions

Derive a [scoped client](/guide/scoped-context) for namespaced ids:

```ts
const my = (await connectDevframe()).scope('my-tool')

// Standard call: awaits a response or throws.
const modules = await my.rpc.call('get-modules', { limit: 10 })

// Optional: returns undefined when no handler responds (useful while HMR is restarting).
const maybe = await my.rpc.callOptional('get-modules', { limit: 10 })

// Event: fire-and-forget, no response expected.
my.rpc.callEvent('notify', { message: 'hello' })
```

Types flow from the node side's `defineRpcFunction` definitions.

## Registering client functions

Register functions the node side calls via `rpc.broadcast`:

```ts
import { defineRpcFunction } from 'devframe'

my.rpc.register(defineRpcFunction({
  name: 'on-file-changed', // -> my-tool:on-file-changed
  type: 'event',
  setup: () => ({
    handler: async ({ file }: { file: string }) => {
      console.log('server says:', file, 'changed')
    },
  }),
}))
```

## Shared state

```ts
const state = await my.rpc.sharedState('state') // -> my-tool:state

console.log(state.value())

state.mutate((draft) => {
  draft.count += 1
})

state.on('updated', (next) => {
  console.log('new state', next)
})
```

See [Shared State](/guide/shared-state).

## Services

`rpc.services` mirrors the node side's wire-service advertisements:

```ts
if (rpc.services.has('@devframes/service-open'))
  await rpc.services.get('@devframes/service-open')!.rpc.call('open-in-editor', { path })
```

See [Cross-Devframe Services](/guide/services#wire-services).

## Settings

A scoped client exposes a persisted `settings` store, per-user (`global`) or per-checkout (`project`):

```ts
await my.settings.project.set('theme', 'dark')
const theme = await my.settings.project.get('theme')
```

See [Scoped Context](/guide/scoped-context#settings).

## Caching

Set `cacheOptions: true` (or an object):

```ts
const rpc = await connectDevframe({ cacheOptions: true })
```

`query` / `static` responses are memoized per argument hash; the `rpc:cache:invalidate` broadcast clears entries after a mutation.

## Discovery (`__connection.json`)

Devframe writes a JSON descriptor at `<base>/__connection.json`. The socket shares the HTTP port, binding to `<base>__ws` (advertised relative):

```json
{
  "backend": "websocket",
  "websocket": { "path": "__ws" }
}
```

The RPC client resolves it against its origin (`http`→`ws` / `https`→`wss`). The field also accepts a `number` (port on the page's host), a full `ws://`/`wss://` URL, or `{ port }` / `{ host }` for a cross-origin side-car server.

For static mode:

```json
{ "backend": "static" }
```

Override discovery with `connectionMeta`:

```ts
await connectDevframe({
  connectionMeta: { backend: 'static' },
})
```

## Remote docks

Supporting host frameworks (Vite DevTools; see [its remote-client docs](https://devtools.vite.dev/kit/remote-client)) inject a connection descriptor into the iframe URL that `connectDevframe` auto-detects:

```ts
import { connectDevframe } from 'devframe/client'

const rpc = await connectDevframe()
// Already wired to the local dev server via the injected descriptor.
```

The descriptor's session-only, pre-approved token makes `ensureTrusted()` resolve immediately. An external hub builds an external-viewer URL from a trusted connection with `buildRemoteDevframeUrl()`, keeping the token in the URL fragment:

```ts
import {
  buildRemoteDevframeUrl,
  stripRemoteConnectionFromUrl,
} from '@devframes/hub/client'

const viewerUrl = buildRemoteDevframeUrl('/viewer/', connection)
const displayUrl = stripRemoteConnectionFromUrl(viewerUrl)
```

## Events

Four events arrive over `rpc.events`: `rpc:is-trusted:updated` when trust is granted, denied, or revoked; `connection:status` when the [connection status](#handling-connection-and-auth-errors) changes; `connection:error` on a connection-level failure; and `rpc:error` when an `rpc.call` rejects. Payloads are in the [Browser-Side API reference](/references/browser-api#rpc-client-events).

```ts
rpc.events.on('rpc:is-trusted:updated', (isTrusted) => {
  if (isTrusted)
    console.log('server trusts this client')
  else
    console.log('trust revoked or denied')
})
```

`rpc.isTrusted` is the synchronous read.

## Handling connection and auth errors

### Connection status

`rpc.status` collapses transport and trust into one value; `rpc.connectionError` holds the last connection-level `Error` (`null` when healthy). It moves through `connecting` (calls queue until open), `connected` (calls are served), `unauthorized` (socket open, trust refused; prompt for [authentication](#authenticating-with-a-one-time-code)), `disconnected`, and `error`; each value's meaning is in the [Browser-Side API reference](/references/browser-api#connection-statuses).

A `static` backend has no live socket, so `rpc.status` stays `connected`.

### Calls fail fast

When the socket closes or trust is refused, in-flight and new `rpc.call` promises reject with a `DevframeConnectionError`, its `kind`:

- `'connection'`: the transport is down (`disconnected` / `error`).
- `'auth'`: the RPC client is `unauthorized`.
- `'timeout'`: the call outlived `callTimeout`.

Set `callTimeout` to cap an unresponsive node side:

```ts
const rpc = await connectDevframe({ callTimeout: 10_000 })
```

### Putting it together

Gate the UI on `connection:status` and wrap calls to branch on failure:

```ts
import { connectDevframe, DevframeConnectionError } from 'devframe/client'

const rpc = await connectDevframe()

// 1. Render from the live status.
function render() {
  switch (rpc.status) {
    case 'connected': return renderApp()
    case 'connecting': return renderSpinner('Connecting…')
    case 'unauthorized': return renderMessage('Not authorized. Reopen the link from your dev server.')
    case 'disconnected': return renderMessage('Disconnected.', { onRetry: reconnect })
    case 'error': return renderMessage(rpc.connectionError?.message ?? 'Connection failed.', { onRetry: reconnect })
  }
}
rpc.events.on('connection:status', render)
render()

// 2. Handle a failing call.
async function loadModules() {
  try {
    return await rpc.call('my-tool:get-modules', { limit: 10 })
  }
  catch (error) {
    if (error instanceof DevframeConnectionError) {
      // 'connection' | 'auth' | 'timeout': the UI already reflects rpc.status.
      return null
    }
    throw error // a real server-side error; surface it.
  }
}
```

### Recovering

The RPC client doesn't reconnect on its own; reload or re-run your connect routine:

```ts
async function reconnect() {
  rpc = await connectDevframe() // a new RPC client; re-subscribe your listeners
  render()
}
```

In a hub, a hub UI provider reads this status from [`context.connection`](/guide/client-context#the-client-context).

---
title: In-Page Channel
navigation:
  icon: i-lucide-message-square-code
description: 'The in-page channel connects a devframe''s page script to its panels entirely in the browser: typed events, calls, and page-script-authoritative shared state, with no server involved.'
---

The in-page channel (`devframe/in-page-channel`) connects a devframe's page script to its panels entirely in the browser: typed events, calls, and page-script-authoritative shared state, with no server involved. It is how a live inspect-the-page loop (like the [a11y inspector](/add-ons/devframes/a11y)'s scan/highlight cycle) works identically in dev and in a static build.

## Overview

```mermaid {theme="zinc-light" theme-dark="zinc-dark"}
flowchart LR
  subgraph Host["User app's page"]
    PS["Page script<br/>createPageScriptChannel()"]
  end
  subgraph Dock["Dock iframe"]
    PA["Panel<br/>connectPanelChannel()"]
  end
  subgraph PiP["Popup / Document PiP"]
    PB["Panel<br/>connectPanelChannel()"]
  end
  PA <-->|"MessageChannel port"| PS
  PB <-->|"MessageChannel port"| PS

```

The panel finds the page script with a same-origin `postMessage` handshake: it posts a versioned hello to its ancestor chain and `opener`, retrying with backoff until the page script answers by transferring a dedicated `MessageChannel` port. Boot order never matters, a reload of either side is just a re-handshake, and each connected panel gets its own port, so a dock iframe and a picture-in-picture window can watch the same page script at once.

## The protocol

Declare the contract once, in a shared file both sides import: a pure type plus the channel-name constant:

```ts
// shared/protocol.ts
import type { InPageChannelProtocol } from 'devframe/in-page-channel'

export const MY_CHANNEL = 'devframes:plugin:my-tool'

export interface MyChannelProtocol extends InPageChannelProtocol {
  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>
    }
  }
  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[] }
  }
}
```

Channel names are namespaced with the devframe id, like RPC ids. Function names stay bare; the channel name already scopes them.

## The page script endpoint

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. A function with `agent` metadata is available to coding agents through MCP; the field implicitly enables strict JSON serialization (an explicit `jsonSerializable: false` conflicts). `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()` 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 pageChannel = createPageScriptChannel<MyChannelProtocol>({
  name: MY_CHANNEL,
  functions: {
    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)),
    },
  },
})

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())
```

`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

```ts
import type { MyChannelProtocol } from '../shared/protocol'
// spa/main.ts: the devtools SPA (dock iframe, popup, or PiP)
import { connectPanelChannel } from 'devframe/in-page-channel'
import { MY_CHANNEL } from '../shared/protocol'

const panelChannel = connectPanelChannel<MyChannelProtocol>({
  name: MY_CHANNEL,
  functions: {},
  events: {
    flash: {},
  },
})

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.

```ts
// Page script (the authority):
const state = await channel.sharedState.get('state', { initialValue: { selections: [] } })
state.mutate((draft) => {
  draft.selections.push('.hero')
})

// Panel (a live mirror):
const state = await channel.sharedState.get('state')
state.on('updated', fullState => render(fullState))
state.value() // Immutable<T> snapshot
```

Without an `initialValue`, a panel's `get` resolves once the first replay arrives, so `render(state.value())` never sees a half-initialized value. Keep values serializable: they cross a structured-clone boundary on every sync.

## Errors and fallbacks

Every failure mode is a coded `InPageChannelError` (`error.code`) with a message that explains itself: `timeout` (a call or `whenConnected(ms)` outlived its deadline), `closed` (endpoint torn down with calls pending), `not-serializable` / `not-cloneable` (a payload the port can't carry; the message names the offending path), `invalid-args` (Standard-Schema validation failed), and `state-uninitialized` (a shared state read before its `initialValue`). Causes and fixes per code are in the [Browser-Side API reference](/references/browser-api#in-page-channel-error-codes).

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 `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
try {
  await channel.whenConnected(3000)
}
catch {
  renderEmptyState('Add the page script to your app to see live data.')
}
```

Recovery is automatic: a dead port (detected by the port's `close` event or the built-in heartbeat) returns the panel to `connecting` and resumes the handshake, so a host-page reload reconnects a popup panel by itself.

## Reactivity and serialization

Payloads cross the port with structured clone. Framework reactivity wrappers don't survive it; unwrap them before sending, either in handlers or once per endpoint with the `serialize`/`deserialize` hooks:

```ts
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, functions: {}, events: { flash: {} } })
```

## Custom transports

Both endpoints accept a pre-established `MessagePort` that bypasses the handshake, for custom topologies and tests:

```ts
const { port1, port2 } = new MessageChannel()
pageScript.addPanelPort(port1)
const panel = connectPanelChannel<MyChannelProtocol>({ name: MY_CHANNEL, transport: port2, functions: {}, events: { flash: {} } })
```

## When to use the in-page channel vs RPC

| Use the in-page channel for                          | Use [RPC](/guide/rpc) for                                    |
| ---------------------------------------------------- | ------------------------------------------------------------ |
| Page script ↔ panel loops (highlight, scan, measure) | Anything involving the node side (files, processes, storage) |
| Working identically in dev and static builds         | Data that must survive the tab (server owns it)              |
| Same-tab, same-origin surfaces                       | Cross-origin external viewers, remote panels                 |

The a11y inspector uses both: the scan/highlight loop rides the in-page channel, while `get-config` is a `static` RPC resolved over WebSocket in dev and from the baked dump in a static build.

---
title: Transports
navigation:
  icon: i-lucide-cable
description: Devframe serves live RPC over two interchangeable transports, WebSocket and SSE, so an RPC client connects even where the WebSocket upgrade is unavailable (serverless, buffering proxies). Both speak the identical birpc wire protocol, transparent to your RPC code.
---

Devframe serves live RPC over two interchangeable transports, WebSocket and SSE, so an RPC client connects even where the WebSocket upgrade is unavailable (serverless, buffering proxies). Both speak the identical birpc wire protocol, transparent to your RPC code.

## What the node side binds

A live instance binds both by default:

- **WebSocket** at `<base>__ws`: primary, one full-duplex socket.
- **SSE** at `<base>__sse`, one method-dispatched route: `GET` opens the server→client stream, `POST` carries client→server frames. It rides the same HTTP routes as `__connection.json`, so wherever discovery works SSE works, including middleware-only host frameworks (the Vite bridge, `initDevframe`'s `handler` / `nodeMiddleware`).

`__connection.json` advertises what's bound; `backend` is the primary:

```json
{
  "backend": "websocket",
  "websocket": { "path": "__ws" },
  "sse": { "path": "__sse" }
}
```

The SSE stream sends a keep-alive comment every 30 seconds. Both endpoints share one session space, identical for auth, shared-state, and streaming replay.

### Configuring

```ts
// SSE-only: host frameworks/proxies where the upgrade can't happen.
// RPC clients connect over SSE automatically (backend: 'sse').
initDevframe(def, { base: '/__my-tool/', ws: false })

// WebSocket-only: opt out of the SSE endpoint.
initDevframe(def, { base: '/__my-tool/', server, sse: false })

// Rename the SSE route.
initDevframe(def, { base: '/__my-tool/', server, sse: { route: '__events' } })
```

`ws: false` + `sse: false` runs RPC-less (`backend: 'none'`); the SPA, discovery, and MCP routes still serve. The same options apply to `createDevServer`, `initHub`, and `cli.ws` / `cli.sse` defaults.

## What the RPC client picks

`connectDevframe` connects over the declared primary, preferring WebSocket when both are present; a socket-less server advertises SSE as primary, so the RPC client lands there directly.

Pin a transport when you know better, e.g. an intermediary that silently strips WS upgrades:

```ts
const client = await connectDevframe({ transport: 'sse' })

client.transport // 'websocket' | 'sse' | 'static': what actually connected
```

Pinning an unadvertised transport rejects. SSE follows the same proxy-safe rules as WebSocket: relative paths against `__connection.json`'s URL, explicit `host`/`port` only for a cross-origin endpoint.

A dropped SSE stream ends the RPC client like a closed socket: pending calls reject, status moves to `disconnected`, reconnect via `connectDevframe`.

---
title: Security
navigation:
  icon: i-lucide-shield-check
description: 'Devframe tools are secure by default: connections bind to localhost, and dev-mode RPC requires a trust handshake before accepting a browser.'
---

Devframe tools are secure by default: connections bind to `localhost`, and dev-mode RPC requires a trust handshake before accepting a browser.

## Trust model

An RPC handler runs with the full privileges of its Node process (filesystem, child processes, network), and a trusted connection can call any registered function. The boundary that matters is *who may connect*:

- **Authenticated (default).** `auth` defaults to `true`; the browser authenticates before calls are accepted, then reconnects with a node-issued bearer token. `createInteractiveAuth` (`devframe/recipes/interactive-auth`) packages the protocol into one `DevframeAuthHandler` the adapters wire for you (pass it to `initDevframe` / `initHub` via `auth`).
- **Unauthenticated opt-out.** `auth: false` starts the server with an auto-trust handshake, for single-user tools on their own `localhost`.

> [!WARNING]
> `auth: false` trusts every connection that can reach the port. Only use it when the endpoint is reachable solely by the local developer. Never combine it with a non-loopback bind host, a tunnelled port, or a shared/CI environment.

## 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 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 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.

The 6-digit code is single-use, expires after five minutes, is compared in constant time, and rotates after repeated wrong attempts. Show it only in a trusted channel (the terminal), never over the network.

The bearer token is a secret. It travels to the server on the WebSocket URL (`?devframe_auth_token=…`), so serve over `wss://`/`https://` whenever the endpoint is reachable beyond loopback. An RPC client self-revokes (`devframe:auth:revoke`) or the node side revokes it (`revokeAuthToken`); affected RPC clients drop to untrusted via `devframe:auth:revoked`.

### The ready-made layer

```ts
import { createInteractiveAuth } from 'devframe/recipes/interactive-auth'

// The adapters gate with this layer by default. Construct it yourself only to
// tune it (e.g. CI tokens) and hand it to `initDevframe` / `initHub` as `auth`.
const auth = createInteractiveAuth(ctx, {
  clientAuthTokens: process.env.CI ? [process.env.DEVFRAME_CI_TOKEN!] : undefined,
})
```

Pass `clientAuthTokens` for CI/shared machines to skip the prompt, or a custom `banner`/`serverUrl`.

### 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`): `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

The standalone CLI (`createCac` / `createDevServer`) prints a link embedding the code for `--open`, so the launched tab lands authenticated with no prompt. Build it yourself with `buildOtpAuthUrl(origin)`:

```
Devtools ready. Authenticate this browser: http://localhost:3000/#devframe_otp=123456
```

The code rides the URL **fragment** (`#devframe_otp=…`), which browsers never send to the server, keeping the single-use code out of access logs and `Referer` headers. `connectDevframe` reads it, exchanges it, and strips it from the URL. Because the link grants trust to whoever opens it within the code's lifetime, print it only to a trusted channel (the terminal).

The link points at the **public origin**. A standalone dev server derives it from its own bound address; an owned listener uses that address regardless of any inbound `Host` header. A handler or middleware without an explicit `origin` derives one from a request only when the request's own origin is loopback or exactly matches an `allowedOrigins` entry; a raw inbound authority and forwarded headers are never trusted. Set `origin` explicitly for non-loopback handler deployments (behind a proxy, on a LAN, or on a public host) so the magic link always resolves to the address you intend.

For your own auth UI, disable built-in handling with `otpParam: false`, then call `authenticateWithUrlOtp(rpc)` or `consumeOtpFromUrl()` from `devframe/client`.

## Practices for tools built on devframe

- **Stay on loopback.** Bind to a routable address only intentionally, and require authentication when you do.
- **Keep `auth: false` local.** The hosted bridges (`devframeViteBridge`, `@devframes/next`'s handler) gate their side-car by default; opt out with an explicit `auth: false` only when the host framework owns the trust boundary another way.
- **Gate the socket in a listener you own.** The `server` option binds its `upgrade` listener after async setup, so a guard that wraps the listeners present at startup misses it. To run your own check first, such as the peer address from `req.socket.remoteAddress` or a session cookie, leave `server` unset and own the listener. It sees every upgrade on the server, so act only on requests to `<base>__ws` and leave the rest to the host framework. For those, attach an `error` handler to the socket, then call `devtools.handleUpgrade(req, socket, head)` when the check passes, or write a `403` response and destroy the socket when it fails. The built-in socket gate checks `Origin` and lets `Origin`-less clients through, so with `auth: false` on a non-loopback bind any client that reaches the port can open the socket.
- **The MCP route trusts same-machine callers, harden it when that's not your boundary.** Two gates enforce that default: an origin gate (loopback-only, `Origin`-less rejected) is browser DNS-rebinding hardening, and a peer-address gate rejects a non-loopback caller even with a forged loopback `Origin` (the socket address can't be forged the way a header can). So the `'auto'` default - which mounts the route once agent tools exist - and `mcp: true` are enough for a local dev tool. Neither gate proves *which* caller it is, though, so to intentionally reach the route beyond loopback (a widened `allowedOrigins`, a hosted app) or to expose destructive tools, add an identity check with `mcp: { authorization }` (a bearer from an env var, or a callback), which also lifts the loopback-peer restriction - or turn the route off with `mcp: false`. See [MCP](/adapters/mcp).
- **Treat tokens as secrets.** Never log the bearer token or the one-time code, or bake either into build output.
- **Authorize every handler.** Validate inputs, and mark state-changing functions `type: 'destructive'` so MCP and agent clients prompt before invoking them.
- **Origin-lock remote docks.** When a hub embeds a remote-UI dock, keep `originLock` on (the default) so its session token is only honored on a connection whose `Origin` matches the dock's own.

## External viewer origins

WebSocket handshakes from browser extensions and other external viewers carry the viewer's own `Origin` header, authorized through a live registry:

```ts
import { attachWsRpcTransport, createWsOriginRegistry } from 'devframe/rpc/transports/ws-server'

const viewerOrigins = createWsOriginRegistry({
  validateOrigin: origin => origin.startsWith('chrome-extension://')
    || origin.startsWith('moz-extension://'),
})

attachWsRpcTransport(rpc, {
  server,
  allowedOrigins: viewerOrigins,
})
```

Include `viewerOrigins.token` as `viewerOriginToken` in the connection metadata. In the metadata handler, call `viewerOrigins.registerFromUrl(request.url)`; when it returns an origin, set `Access-Control-Allow-Origin` to it. The external viewer then calls `registerDevframeViewerOrigin(connection)` before connecting.

The registration token grants access through the transport's origin check; RPC authentication still authorizes the session and every non-anonymous method. Keep metadata carrying this token same-origin until the registration is verified.

---
title: Agent-Native Devframe
navigation:
  icon: i-lucide-bot
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 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. The same `agent` field on a *client* RPC function surfaces it [over WebMCP](#browser-side-tools-over-webmcp) instead.

## Exposing an RPC function

```ts
import { defineRpcFunction } from 'devframe'

export const getSessionSummary = defineRpcFunction({
  name: 'rolldown-get-session-summary',
  type: 'query',
  args: [v.object({ sessionId: v.string() })],
  returns: v.object({ durationMs: v.number(), chunkCount: v.number() }),
  agent: {
    description: 'Summarize a Rolldown build session. Safe to call freely.',
    title: 'Build summary',
    // safety inferred from `type: 'query'` → 'read'
  },
  setup: ctx => ({
    handler: async ({ sessionId }) => {
      // ...
    },
  }),
})
```

## Tool ids and wire names

- **The id** registers/invokes in devframe, colon-namespaced: `devframes:plugin:<slug>:<fn>` (built-in devframe RPCs), `devframe:<area>:<fn>` (built-ins), command ids.
- **The wire name** is what MCP clients call, constrained to `^[a-zA-Z0-9_-]{1,128}$`; runs outside that set collapse to `_`, truncated to 128.

```
devframe:state:read          → devframe_state_read
devframes:plugin:git:status  → devframes_plugin_git_status
my-plugin:summarize          → my-plugin_summarize
```

`toAgentToolName` (`devframe/utils/agent-tool-name`, client-safe) predicts a wire name; two ids sanitizing alike keep the first, the later hidden with `DF0047`.

## Registering a devframe tool

Tools without a matching RPC register directly.

```ts
export default defineDevframe({
  id: 'my-plugin',
  setup(ctx) {
    ctx.agent.registerTool({
      id: 'my-plugin:summarize',
      description: 'Plain-text summary of the current build state.',
      safety: 'read',
      handler: async () => ({
        markdown: buildSummary(),
      }),
    })
  },
})
```

## Deriving tools from other state

Register a **provider** for tools derived from state, queried at list/invoke time:

```ts
const handle = ctx.agent.registerToolProvider(() =>
  currentCommands()
    .filter(command => command.agent)
    .map(command => toAgentTool(command)),
)

// After the underlying state changes, nudge connected MCP clients:
handle.notifyChanged() // fires tools/list_changed
```

## Registering a resource

Readable snapshots by URI:

```ts
ctx.agent.registerResource({
  id: 'current-session',
  name: 'Current Rolldown session',
  description: 'Markdown snapshot of the active build session.',
  mimeType: 'text/markdown',
  read: () => ({ text: renderMarkdown(currentSession) }),
})
```

Every `ctx.rpc.sharedState` key is exposed as a `devframe://state/<key>` resource and via the **`devframe:state:read` tool** (wire `devframe_state_read`): no args → key list, `key` → its value. `exposeSharedState: false` (or a filter) on `createMcpServer` opts out.

## Starting the MCP server

The dev server serves the agent surface over HTTP on its own: the `mcp: 'auto'` default mounts the route at `/__mcp` once anything above exists (an `agent`-flagged RPC, a registered tool or resource) and the optional [`@devframes/agentic`](/adapters/mcp) peer is installed - one flagged function plus one install is the whole setup. See the [MCP adapter](/adapters/mcp#route-based-server) for forcing it on or off and hardening the route.

For a stdio server instead, via the CLI:

```sh
# Run your devtool with an MCP stdio server attached.
devframe mcp
```

Programmatically:

```ts
import { defineDevframe } from 'devframe'
import { createMcpServer } from 'devframe/adapters/mcp'

const myDevframe = defineDevframe({ /* … */ })

await createMcpServer(myDevframe, { transport: 'stdio' })
```

## Connecting Claude Desktop

In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "my-tool": {
      "command": "pnpm",
      "args": ["--filter", "my-tool", "exec", "devframe", "mcp"]
    }
  }
}
```

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:

<!-- eslint-skip -->

```ts
// ✗ Bad: describes the mechanism
agent: { description: 'Returns the session summary object.' }
// ✓ Good: tells the agent when and why
agent: { description: 'Summarize the current build session: durations, chunk counts, warnings. Call this before proposing any build-config change.' }
```

## Gateway tools

A gateway tool returns *instructions and locations*, not work agents do better:

```ts
ctx.agent.registerTool({
  id: 'my-plugin:docs',
  description: 'Locate the version-accurate docs for this tool. Call before answering questions about its config format.',
  safety: 'read',
  handler: () => ({
    docsPath: resolveInstalledDocsDir(),
    hint: 'Read the file matching your topic; do not rely on training-data knowledge of this config format.',
  }),
})
```

## Structured errors

A coded diagnostic thrown from a handler crosses the MCP boundary as JSON:

```json
{ "error": { "code": "DF0017", "message": "…", "fix": "…", "docs": "https://devfra.me/errors/df0017" } }
```

Prefer coded diagnostics anywhere agent-reachable: agents act on `fix` and follow `docs`.

## Safety model

- **`safety`**: `'read'`, `'action'`, or `'destructive'`. Inferred from the RPC `type` (`static`/`query` → `read`, `action`/`event` → `action`), overridable.
- The adapter maps `safety` to tool annotations (`readOnlyHint`, `destructiveHint`).

## CLI

`<your-app> mcp` starts the MCP server on `stdio`; `<your-app> dev --mcp` serves the agent-consumable API on `/__mcp`; `devframe connect` discovers running devframes and proxies their tools ([MCP adapter](/adapters/mcp#discovery-devframe-connect)). The command table is in the [Node-Side API reference](/references/node-api#mcp-cli-commands).

---
title: Hub
navigation:
  icon: i-lucide-layout-dashboard
description: '@devframes/hub orchestrates many devtools sharing a UI: a dock registry, terminal aggregation, message/toast queue, and command palette. It ships no UI; hub UI providers provide their own atop the hub''s RPC + shared-state protocol.'
---

`@devframes/hub` orchestrates many devtools sharing a UI: a dock registry, terminal aggregation, message/toast queue, and command palette. It ships no UI; hub UI providers provide their own atop the hub's RPC + shared-state protocol.

![Hub screenshot](/screenshots/hub-1.png)

*Orchestrating multiple devtools (from [A Playground](https://github.com/devframes/devframe/tree/main/examples/custom-hub-vite))*

## What the hub adds

`DevframeHubContext` adds four subsystems to `DevframeNodeContext`: `ctx.docks` registers dock entries and groups and [activates docks](#cross-iframe-dock-activation); `ctx.terminals` aggregates terminal sessions with streaming output ([Terminals](/add-ons/devframes/terminals#hub-aggregation)); `ctx.messages` is the server-side toast/notification queue; `ctx.commands` is the hierarchical command palette with keybindings and `when` clauses. Each subsystem's API is in the [Hub API reference](/references/hub-api#hub-subsystems).

Data-driven UI panels are an opt-in [JSON-Render](/guide/json-render) package (a `json-render` dock type).

## Built-in RPC

Every hub context auto-registers these functions, callable from any RPC client:

- `hub:commands:execute`: invoke a server command by id.
- `hub:docks:activate`: switch the active dock ([Cross-iframe dock activation](#cross-iframe-dock-activation)).
- `hub:messages:add` / `update` / `remove` / `clear`: write the messages feed.
- `hub:terminals:write` / `resize`: drive a PTY session by id.

Host-framework-specific capabilities (open in editor, reveal in finder) ship as kit-registered functions.

## Commands as agent tools

A server command with an `agent` field ([agent-consumable API](/guide/agent-native)) becomes a `ctx.agent` MCP tool:

```ts
ctx.commands.register({
  id: 'app:build',
  title: 'Run build',
  agent: {
    description: 'Run the production build. Call after config or dependency changes to verify the app still builds.',
    args: [v.object({ configFile: v.optional(v.string()) })],
  },
  handler: (opts?: { configFile?: string }) => runBuild(opts),
})
```

`args` takes positional [Standard Schema](https://standardschema.dev/) schemas (a single `v.object(...)` unwraps into the input); omit for zero-arg. `safety` defaults to `'action'`; `when` clauses are unenforced for agent calls.

## Localized titles

A dock entry, a command, and a launcher each carry a plain `title` and an optional `titleLocales` map of translations by BCP 47 tag. The plain `title` stays the default, so a hub UI that ignores the map still shows it. The reference hub UI picks the translation closest to its own language setting (`zh-HK` falls back to `zh-TW`, `pt-PT` to `pt-BR`, `en-GB` to `en`):

```ts
ctx.docks.register({
  type: 'iframe',
  id: 'app:build',
  title: 'Build',
  titleLocales: { 'zh-CN': '构建', 'ja': 'ビルド' },
  icon: 'ph:hammer-duotone',
  url: '/__build/',
})
```

A devframe localizes the dock a hub synthesizes for it through `dock: { titleLocales }` in its definition. A hub UI provider resolves a title with `resolveTitle(entry, locale)` from `@devframes/hub/client`.

## Nested commands

A command's `children` nest arbitrarily deep. The palette drills into each level, and every command in the tree is bindable at any depth: a shortcut assigned to a leaf several levels down fires as directly as one on a top-level command, and each appears as its own row under **Settings → Shortcuts**, indented by nesting level.

```ts
ctx.commands.register({
  id: 'app:cache',
  title: 'Cache',
  children: [
    { id: 'app:cache:clear', title: 'Clear', keybindings: [{ key: 'Mod+Shift+K' }], handler: clearCache },
  ],
})
```

Set `showInPalette: 'without-children'` on a parent to keep its whole subtree out of root search while leaving it reachable by drilling down.

## Cross-iframe dock activation

A mounted devframe's iframe uses `hub:docks:activate` to switch the active dock.

```ts
// From inside a mounted devframe's iframe (its own RPC client):
await rpc.call('hub:docks:activate', {
  dockId: 'devframes_plugin_terminals',
  params: { sessionId }, // opaque bag the target dock interprets
})
```

It mirrors into the `devframe:docks:active` shared-state slot; the [terminals dock](/add-ons/devframes/terminals#focusing-a-session) reads `params.sessionId`, unknown ids no-op ([DF8107](/errors/DF8107)). Server-side: `ctx.docks.activate(dockId, params?)`.

## Process-control launchers

A `type: 'launcher'` dock entry is a one-click action tile. Three optional `launcher` fields make it a live process controller: `command` binds a command id dispatched via `hub:commands:execute`, `terminalSessionId` links a tracked session for a "view in terminal" action, and `digest` shows the latest progress line inline ([Hub API reference](/references/hub-api#launcher-fields)).

`onLaunch` lets a same-process host framework invoke directly; provide `command`, `onLaunch`, or both.

```ts
ctx.commands.register({ id: 'app:build', title: 'Run build', handler: runBuild })

const launcher = ctx.docks.register({
  type: 'launcher',
  id: 'app:build',
  title: 'Build',
  icon: 'ph:hammer-duotone',
  launcher: { title: 'Run build', command: 'app:build', status: 'idle' },
})

async function runBuild() {
  const session = await ctx.terminals.startChildProcess(
    { command: 'vite', args: ['build'] },
    { id: 'app:build-session', title: 'vite build' },
  )
  launcher.update({ launcher: { title: 'Run build', command: 'app:build', status: 'loading', terminalSessionId: session.id } })

  // A child-process session keeps its `status` live: `running` → `stopped` on a
  // clean exit, `error` on a non-zero exit or spawn failure. Map it onto the
  // launcher and read the exit code from getResult().
  const { exitCode } = await session.getResult()
  launcher.update({ launcher: {
    title: 'Run build',
    command: 'app:build',
    terminalSessionId: session.id,
    status: exitCode === 0 ? 'success' : 'error',
    error: exitCode === 0 ? undefined : `vite build exited ${exitCode}`,
  } })
}
```

## Mounting a devframe into a hub

`ctx.install(def)` registers a `DevframeDefinition` as a dock and runs its `setup(ctx)`, the imperative counterpart to `initHub`'s `devframes` list.

```ts
import { createHubContext } from '@devframes/hub/node'

const ctx = await createHubContext({ cwd, host, mode: 'dev' })
await ctx.install(myDevframe)
```

Framework kits and hub UI providers wrap this (e.g. `@vitejs/devtools-kit`'s `createPluginFromDevframe`).

### Connecting embedded SPAs

A mounted SPA loads at `/__<id>/` and calls `connectDevframe()`, which fetches `./__connection.json`, served by the host framework's `mountConnectionMeta(base)`:

```ts
const host: DevframeHost = {
  mountStatic(base, distDir) { /* serve files */ },
  mountConnectionMeta(base) {
    // serve `${base}__connection.json` → { backend: 'websocket', websocket: port }
  },
  resolveOrigin() { /* … */ },
  getStorageDir(scope) {
    // workspace = committable, team-shared; project = per-checkout; global = per-user
    if (scope === 'workspace')
      return join(cwd, '.devframe')
    if (scope === 'project')
      return join(cwd, 'node_modules/.my-hub')
    return join(homedir(), '.my-hub')
  },
}
```

Omitting `mountConnectionMeta` (with servable `clientAssets`) triggers [`DF8106`](https://devfra.me/errors/DF8106) and falls back to same-origin inheritance.

### Bundled host frameworks (Next.js)

Load node-side built-in devframe packages via dynamic `import()` with `webpackIgnore`/`turbopackIgnore` comments:

```ts
const pkgs = ['@devframes/plugin-git', '@devframes/plugin-terminals']
const defs = await Promise.all(
  pkgs.map(p => import(/* webpackIgnore: true */ /* turbopackIgnore: true */ p)),
  // Each package's default export is its `create<X>Devframe` factory, not a
  // pre-built instance; call it to get one.
).then(mods => mods.map(m => m.default()))

for (const def of defs)
  await ctx.install(def)
```

SPAs serve at `/__<id>/` with relative assets; set `skipTrailingSlashRedirect`:

```js
/** next.config.mjs */
export default { skipTrailingSlashRedirect: true }
```

### Duplicate devframes

When a devframe shares an already-mounted `id`, `duplicationStrategy` decides: `'warn'` (the default) keeps the first and drops the later with [`DF8105`](/errors/DF8105), `'silent'` drops it quietly, `'throw'` raises, and `'duplicate'` lets every instance coexist under disambiguated dock ids ([Hub API reference](/references/hub-api#duplication-strategies)).

```ts
defineDevframe({
  id: 'my-tool',
  /** … */
  duplicationStrategy: 'duplicate',
})
```

## Grouping dock entries

Related dock entries collapse under one dock-rail button (a `type: 'group'` entry); an entry whose `groupId` matches the group's `id` joins it.

```ts
ctx.docks.register({
  type: 'group',
  id: 'nuxt',
  title: 'Nuxt',
  icon: 'logos:nuxt-icon',
  category: 'framework',
  defaultChildId: 'nuxt:overview', // optional; see "Activating a group" below
})

ctx.docks.register({
  type: 'iframe',
  id: 'nuxt:overview',
  title: 'Overview',
  icon: 'ph:gauge-duotone',
  url: '/__nuxt-overview/',
  groupId: 'nuxt', // joins the group above
})
```

Group and members stay independent top-level entries in `devframe:docks`. Grouping affects the dock rail, not iframes; to share **one** soft-navigated iframe, give docks a shared `frameId` and mark the anchor with `subTabs` ([Shared-iframe soft navigation](/guide/client-context#shared-iframe-soft-navigation)).

### Activating a group

Activating a group resolves to one of its members.

The dock rail button reopens the member last opened in the group (remembered per tab), then `defaultChildId`; with neither, it reveals the member popover.

A group command, activated by its keyboard shortcut or a command-palette pick, opens that same remembered or default member, then the only visible member when there is exactly one. With several visible peers and no preferred member, it opens the command palette scoped to those members, so the choice stays with the user. Pressing the same shortcut again closes that palette.

The first time any member of a group opens in a session, the hub also loads the group's `defaultChildId` member, then navigates to the requested member. A group that mixes server and client docks therefore always mounts its default member, even when the last opened member is a server dock.

`hub:docks:activate` follows programmatic dock switching: it opens the remembered or default member, then the first registered member.

Declare `defaultChildId` when one member is the natural landing spot; leave it off when the members are peers.

### The dual role of `category`

`category` (ordered by `DEFAULT_CATEGORIES_ORDER`, default `'default'`) sets an **ungrouped** entry's outer dock-rail bucket. A **grouped** entry takes its outer bucket from the **group's** `category`, and its own `category` becomes an **in-group sub-category**; a member whose `groupId` never resolves renders top-level under its own `category`.

#### Known categories

`DEFAULT_CATEGORIES_ORDER` (from `@devframes/hub`, `/node`, `/client`, `/constants`) names the default buckets, running from `framework` (weight `-100`) through `default`, `app`, `ui`, `data`, `web`, `performance`, `advanced`, and `docs` to `~builtin` (always last). The weight table is in the [Hub API reference](/references/hub-api#dock-categories).

Framework kits can interleave category ids or override weights; an unknown category sorts as `0`.

## The hub UI protocol

A hub UI provider imports no hub classes; it renders from four shared-state slots and dispatches through two RPC methods. The slots are `devframe:docks` (every registered dock entry), `devframe:commands` (the serializable command list), `devframe:user-settings` (persisted hub settings), and `devframe:docks:active` (the most recent [dock activation](#cross-iframe-dock-activation) request); the methods are `hub:commands:execute` and `hub:docks:activate`. Types and payloads are in the [Hub API reference](/references/hub-api#hub-ui-protocol).

Broadcast notifications (`devframe:docks:activate`, `devframe:terminals:updated`, `devframe:messages:updated`) arrive via `rpc.client.register(...)`; the client runtime registers `devframe:docks:activate` for you ([Events Reference](/references/events)).

## Running a devframe's code in the host page

The hub ships a headless client runtime, `createDevframeClientRuntime()` (`@devframes/hub/client`): booted in the host page, it assembles the client context and imports each dock entry's client script ([Client Scripts & Client Context](/guide/client-context)).

## Example

Two minimal hubs mount every built-in devframe behind an icon dock, plus a "Tabbed Tool" demonstrating [shared-iframe soft navigation](/guide/client-context#shared-iframe-soft-navigation):

- [`examples/custom-hub-vite/`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-vite): a \~120-line Vite host with a vanilla DOM UI.
- [`examples/custom-hub-next/`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next): the same, from a Next.js App Router app.

## Diagnostics

Hub-side diagnostic codes live in the `DF8xxx` range; see the [error reference](/errors).

---
title: Client Scripts & Client Context
navigation:
  icon: i-lucide-square-code
description: A dock client script runs a devframe's code inside the host page; the client context is how client scripts reach the hub.
---

A dock **client script** runs a devframe's code inside the **host page**; the **client context** is how client scripts reach the hub.

> [!WARNING]
> Experimental
> The hub API is still being refined. Names may change before 1.0.

## The client runtime

`createDevframeClientRuntime()` (`@devframes/hub/client`) boots the host page: it connects (or adopts) an RPC client, publishes the `DevframeClientContext`, and imports each dock's client script:

```ts
// main.ts: the host page's browser entry
import { connectDevframe, createDevframeClientRuntime } from '@devframes/hub/client'

const rpc = await connectDevframe({ baseURL: '/__hub/' })
const { context, dispose } = await createDevframeClientRuntime({ rpc })
```

### Options

Pass an already-connected `rpc` (or `connect` options for `connectDevframe`), the page's `clientType` (`'standalone'` by default, `'embedded'` inside a user app), `loadClientScripts: false` to skip dock client scripts, and boot-time `renderers` (which win over the hub's [renderer manifest](/guide/hub-initiate#renderer-modules)); see the [Hub API reference](/references/hub-api#client-runtime-options).

A second boot replaces the context and warns; `dispose()` tears down listeners and unpublishes it.

## The client context

The context carries the [RPC client](/guide/client) (`rpc`) and the page's `clientType`, plus six hub facets: `docks` (entries, selection, [client-only registration](#client-only-docks)), `panel` (dock panel state), `commands` (the command palette), `renderers` (the dock-renderer registry), `when` (the [when-clause](/references/when-clauses) context), and `connection` (live [connection status](/guide/client#handling-connection-and-auth-errors)). Every property is in the [Hub API reference](/references/hub-api#client-context-properties).

### Accessing the context

`getDevframeClientContext()` returns the context anywhere; `undefined` before boot.

### Tracking panel state

`ctx.panel.state` is the current dock panel snapshot. It contains `state: 'open' | 'closed' | 'hidden'` and includes `selectedDockId` while a dock is selected. Subscribe to [`ctx.panel.events`](/references/events#client-context-events) for later changes:

```ts
import type { DockClientScriptContext } from '@devframes/hub/client'
import { HUB_EVENTS } from '@devframes/hub/constants'

export default function setup(context: DockClientScriptContext) {
  const reportPanelState = (panelState: typeof context.panel.state) => {
    void context.rpc.call('my-devframe:panel-state', panelState).catch(error => console.error(error))
  }

  reportPanelState(context.panel.state)
  context.panel.events.on(
    HUB_EVENTS.client.docksPanelStateChanged,
    reportPanelState,
  )
}
```

The custom RPC keeps node-side reporting opt-in.

### Client-only docks

A client runtime can register a dock local to the host page (unlike [node hub context](/guide/hub) docks synced via `devframe:docks`). `ctx.docks.register(entry)` (e.g. `type: 'custom-render'` with `renderer: { importFrom }`) returns a handle whose `update({ badge })` patches in place (id immutable) and `dispose()` removes it. One sharing a server dock's id overrides it locally; re-registering an owned id throws unless you pass `register(entry, true)`.

A client-only dock can also carry `type: 'json-render'` with an inline [JSON-render](/guide/json-render) `view: { spec }` (a `DevframeJsonRenderSpec` built in-browser), rendered when a `json-render` renderer is registered at boot. `view` also accepts `{ stateKey }` for live shared state (from `createJsonRenderView`).

## Dock client scripts

A client script is a `ClientScriptEntry`: `{ importFrom, importName?, eager? }`. `importName` defaults to `'default'` and `eager` defaults to `false`. An `iframe` entry's optional `clientScript` runs inside the host page when the dock entry is first activated. An `action` entry runs its `action` on each activation, while a `custom-render` entry initializes its `renderer` after selection so it can mount into the panel.

Set `eager: true` on an `iframe` `clientScript` or an `action` to initialize it as soon as the RPC connection is trusted, before opening a dock panel. This suits background subscriptions and page commands, such as an `action` that registers page commands or subscribes to `entry:activated` before its first click. A `custom-render` `renderer` needs its mounted panel, so it always initializes on activation. Both the reference hub UI and `createDevframeClientRuntime()` honor these settings ([Hub API reference](/references/hub-api#dock-client-script-fields)).

The exported function (`DockClientScriptContext`) receives the client context and two dock-scoped extras:

- **`current`** holds this entry's state: `entryMeta`, `isActive`, `domElements`, `events` (`entry:activated`, `entry:deactivated`, `entry:updated`, `dom:panel:mounted`, `dom:iframe:mounted`).
- **`messages`**: an entry-scoped messages client (`category` defaults to the entry id; `info`/`warn`/`error`/`success`/`debug` shortcuts for `add()`).

Failed setup retries on the next activation, or on a dock update for eager scripts. Setup is cached per RPC connection, dock and import descriptor. Action clicks always execute again.

### Shipping a client script

`importFrom` accepts three shapes:

- **A URL served by the host framework**: a self-contained ES module; works on every host framework.
- **A bare npm specifier** (`'vite-plugin-vue-tracer/client/vite-devtools'`): resolved through the host framework.
- **An absolute filesystem path**, declared on the definition's `dock.clientScript`. The hub serves its directory under `<base>__page-script/` and rewrites `importFrom` to that URL, so mounting by package name needs no host wiring.

Per-mount, attach a URL via `ctx.install(myDevframe, { dock: { clientScript: { importFrom } } })`; under Vite `/@fs/<absolute path>` serves it, and other host frameworks mount the directory statically.

### Bare npm specifiers

Resolving a bare specifier is the **host framework's capability**: a host framework advertises a resolution template at `ConnectionMeta.configs.dock.clientModuleResolution` (loaders replace `{specifier}` before import). A Vite host declares this by default (`@devframes/vite/hub`) as `initHub({ clientModuleResolution: '/@id/{specifier}' })`; then use the specifier alone as `importFrom`. A host framework with no template (Next.js) supports the URL shape only, warning [`DF8111`](/errors/DF8111) on a specifier. A hub UI provider can override with `createDevframeClientRuntime({ resolveClientModule })`.

Client scripts execute in the user app's page realm (`window`); anchor shared state on `globalThis`.

### Dual boots

One bundle can serve as both a client script (default export) and, via a globally-guarded self-boot, a standalone page script ([a11y inspector](/add-ons/devframes/a11y)).

## Iframe panels

Dock iframes are their own documents: the panel calls `connectDevframe()`, discovering `./__connection.json` from its base. A client script and an iframe panel share the node side via RPC and shared state, or talk directly (server-free, static-build-friendly) over the [in-page channel](/guide/in-page-channel).

## Shared-iframe soft navigation

A tool with many internal views (Nuxt DevTools' tabs) can surface each as a hub dock sharing **one** live iframe: the **anchor** owns a `frameId` and opts in via `ctx.install(…, { dock: { frameId, subTabs: { protocol: 'postmessage' } } })`. On mount, the client runtime attaches a **frame-nav adapter** speaking an origin-locked `postMessage` protocol on `devframe:frame-nav`: the iframe reports its tab list (`ready` / `manifest`), the host page requests a view (`navigate`), and the iframe reports internal navigation back (`navigated`). Message shapes are in the [Hub API reference](/references/hub-api#frame-nav-messages).

It materializes a [client-only dock](#client-only-docks) per tab (id `<frameId>:<tabId>`) sharing the anchor's `frameId` and a `navTarget`, independent of [`groupId`](/guide/hub#grouping-dock-entries).

### The hub UI provider's part

A hub UI provider keeps one iframe alive per `frameId` (shown/hidden); on mount, it sets the element on the anchor's `docks.getStateById(anchorId)` state (`domElements.iframe`) and emits `dom:iframe:mounted`. See the "Tabbed Tool" in [`examples/custom-hub-vite`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-vite) / [`custom-hub-next`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next).

---
title: Serve a Hub Anywhere
navigation:
  icon: i-lucide-server
description: initHub() from @devframes/hub/initiate serves a whole multi-devframe devtools install from one web-standard handler on a catch-all route.
---

`initHub()` from `@devframes/hub/initiate` serves a whole multi-devframe devtools install from one web-standard handler on a catch-all route.

```ts
import { createUi } from '@devframes/hub-ui'
import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
import { createInspectDevframe } from '@devframes/plugin-inspect'
import { createTerminalsDevframe } from '@devframes/plugin-terminals'

export const hub = initHub({
  base: DEVFRAMES_HUB_BASE, // required: the conventional `/__devframes/`
  devframes: [createInspectDevframe(), createTerminalsDevframe()],
  ui: createUi(),
  configure(ctx) {
    ctx.commands.register({ id: 'app:hello', title: 'Hello', handler: () => 'hi' })
  },
})
```

`base` is required (echoed as `hub.base`); each mounted devframe runs `setup()` against the **shared hub context**. The instance mirrors `initDevframe`'s API; see [The Standard Handler](/adapters/initiate#mount-the-handler).

## The shared socket

One transport serves the namespace, chosen in precedence: `ws.port` pins a side-car; `server` shares the host framework's `node:http` upgrade at `<base>__ws`; `ws: { sidecar: true }` takes a free port; none leaves the socket to the host framework: Node uses `hub.attach(server)`, Bun/Deno `attachBunWsTransport` / `attachDenoWsTransport`.

The advertised path is hub-base-absolute (`/__devframes/__ws`). Dev-reevaluated host frameworks (Next, Nitro) memoize it on `globalThis`.

## The namespace

The namespace serves the hub UI at `/` (the `ui.viewer` SPA, or an index document when headless) and each devframe's SPA at `<id>/` with its own `__connection.json` pointing at the shared socket. Hub-level endpoints sit alongside: `embedded.js` (the `ui.embedded` bootstrap), `__connection.json`, `__ws`, `__index.json`, `__client-imports.js`, and `__mcp` (mounted by the `'auto'` default once agent tools exist). The route table is in the [Hub API reference](/references/hub-api#hub-namespace-routes).

Devframe ids become URL segments, validated: reserved names throw `DF8000`, non-route-safe `DF8004`.

## The `ui` slot

The hub is headless; `DevframeHubUi` is pure data:

```ts
interface DevframeHubUi {
  viewer?: { distDir: string } // a standalone SPA served at the namespace root
  embedded?: { entry: string } // a prebuilt bootstrap served at <base>embedded.js
  assets?: Record<string, () => string | Uint8Array> // extra UI-owned files
  setup?: (ctx) => void | Promise<void> // publish static config via ctx.staticConfig
}
```

`@devframes/hub-ui`'s `createUi()` is the reference (standalone `viewer` SPA + floating dock); its `setup(ctx)` publishes config to `ctx.staticConfig.ui` (`ConnectionMeta.configs.ui`):

- **`viewer`**: set to `false` to disable the standalone viewer.
- **`branding`**: rebrand the UI (logo, name, primary color). `background` accepts any CSS `background` value (color, gradient, image, or `transparent`) or `{ light, dark }` variants. These flat forms apply everywhere. Use `{ standalone, iframe? }` to specialize the framed viewer; an omitted `iframe` value falls back to `standalone`. Built-in devframe panels read `branding.primaryColor` from the existing connection metadata at startup and map it to CSS primary tokens. Standalone SPAs keep their default accent; status and preview palettes remain independent. Reload panels after changing startup branding.
- **`dockPreferences`** tunes the dock rail: `categoryOrder`, floating-dock `maxVisibleItems`, first-run `defaultMode` (`'float'`/`'edge'`) and `defaultPosition`.
- **`embeddedVisibility`** sets the floating dock's reveal policy:
  - `'normal'` (default): shows immediately.
  - `'passive'`: hidden until `Shift+Alt+D`, then persisted per-origin (later browser sessions start shown).
  - `'hidden'`: hidden until `Shift+Alt+D`, that browser session only.
- **`locale`** sets the default UI language, one of the tags in `HUB_UI_LOCALES` (`en`, `zh-CN`, `zh-TW`, `ja`, `ko`, `es`, `fr`, `de`, `pt-BR`, `ru`). Without it the UI follows the browser language and falls back to English. A visitor's own pick in Settings → Appearance wins and persists per browser. The hub UI writes the language it resolved back into `ConnectionMeta.configs.ui.locale` on its window, so a same-origin frame that inherits the connection (see [Client](/guide/client)) reads the effective language at boot.

To add a language, add its tag and native name to `packages/hub-ui/src/locales.ts`, translate a copy of `packages/hub-ui/src/client/i18n/locales/en.json` under that tag, and register the file in the `messages` map in `packages/hub-ui/src/client/i18n/index.ts`. The i18n test fails on a missing key or a changed `{slot}`.

## Renderer modules

A dock type's renderer (e.g. [JSON-Render](/guide/json-render)) composes via `initHub({ renderers })`. Each registration `{ type, file, importName? }` (`file` = a prebuilt ES module exporting a `DockRenderer`) is served at `<base>__renderers/<type>.mjs` and published into the `devframe:dock-renderers` manifest; client runtimes import it lazily on first mount:

```ts
import { createUi } from '@devframes/hub-ui'
import { jsonRenderUiRenderer } from '@devframes/json-render-ui/hub'

initHub({
  ui: createUi(),
  renderers: [jsonRenderUiRenderer()],
})
```

A renderer registered at boot (`createDevframeClientRuntime({ renderers })`) overrides the manifest; an uncovered type shows the hub UI provider's missing-renderer fallback.

Registrations are validated fail-fast: one module per type (`DF8108`), an existing bundle (`DF8109`), a route-safe type name (`DF8110`).

## One Auth for the hub

The hub's **single Auth** is one gate at the shared transport for every mounted devframe, built-ins, and the MCP route; one handshake (OTP, magic link, or pre-shared token) unlocks the namespace; `auth: false` disables it for localhost.

The aggregate MCP route mounts through the `'auto'` default once any mounted devframe (or an agent-flagged hub command) exposes agent tools; `mcp: true` forces it on, `mcp: false` off. It has its own origin gate, independent of this RPC Auth: the mounted route trusts same-machine callers, and `mcp: { authorization }` adds an identity check when the hub is reachable beyond loopback. The hub exposes one aggregate route over every mounted devframe's tools.

## Singular vs hub mounting

A devframe's SPA and RPC client are byte-identical in both cases; only the environment differs:

| What the SPA / RPC client sees | Singular (`/__git/`)                 | Hub (`/__devframes/git/`)                                                 |
| ------------------------------ | ------------------------------------ | ------------------------------------------------------------------------- |
| Runtime base                   | `/__git/`                            | `/__devframes/git/` (transparent)                                         |
| `__connection.json`            | own meta, own socket                 | per-devframe meta → shared hub socket                                     |
| RPC registry                   | this devframe's functions            | merged: all mounted devframes + hub built-ins, cross-devframe             |
| Shared state                   | own context's slots                  | all mounted devframes' slots + hub slots                                  |
| Auth                           | own gate, own token                  | the single hub Auth                                                       |
| Hub subsystems                 | none                                 | docks, terminals, messages, commands; the devframe is also an iframe dock |
| MCP                            | `<base>__mcp`, this devframe's tools | the hub-level aggregate                                                   |
| Isolation                      | hard (own context, own transport)    | cooperative (shared context)                                              |

## Static builds

`buildHub()` from `@devframes/hub/build` is the hub counterpart of the [build adapter](/adapters/build): it bakes the whole hub into a directory any static file server can serve. Each devframe's SPA is copied to `<outDir>/<id>/` (absolute-path page scripts alongside at `<id>/__page-script/`), the UI slot's viewer and `embedded.js` next to them, and `__connection.json` (`backend: 'static'`) plus a shared [RPC dump](/adapters/build) at the hub base, with a snapshot of every shared-state key (docks, commands, renderer manifest) baked in - so `createDevframeClientRuntime()` and every panel boot from the dump with no live server.

```ts
import { buildHub } from '@devframes/hub/build'

await buildHub({
  outDir: 'dist/__devframes', // corresponds to `base` at serve time
  devframes: [createA11yDevframe(), createMessagesDevframe()],
  ui: createUi(),
})
```

A mount served outside the hub base writes to `outDir`'s parent (the deploy root) by its absolute path, so a host can keep the hub at `/__devtools/` while its devframe SPAs and assets stay top-level siblings (`/__inspect/`, `/__devtools-assets/`) rather than children of the hub base. `outDir` holds the hub subtree, its parent holds the whole deploy root, and either directory serves as-is.

Browser-side tools keep working in full: a page script still loads into the host page and talks to its panel over the [in-page channel](/guide/in-page-channel) (the a11y inspector scans a production app exactly as it does in dev). Reads resolve from the baked dump (`static`/`snapshot` RPCs, shared-state snapshots); live writes (messages, command execution) have no server, so the browser clients degrade to local no-ops, and a panel's dock-activation deep links ride a same-origin `BroadcastChannel` instead of the RPC relay.

A devframe whose value is inherently live declares `capabilities.build: false` and silently stays out of the build entirely - no dock, no SPA copy, no RPCs in the dump. The built-in terminals, code-server, and assets devframes declare it, so a hub mounting every built-in bakes only the tools that mean something statically. See the [buildHub options](/references/hub-api#buildhub-options) reference, and [`examples/a11y-messages-playground`](https://github.com/devframes/devframe/tree/main/examples/a11y-messages-playground) for a Vite host whose `vite build` output ships the hub.

## Bring your own context

Host frameworks that assemble `createHubContext` + `ctx.install` themselves pass the context instead of a `devframes` list:

```ts
const hub = initHub({ base: DEVFRAMES_HUB_BASE, context: ctx })
```

It then serves only hub-level endpoints and transport; serve each mounted devframe's meta from `hub.connectionMeta()` yourself.

The same `context` option works for a static build: `buildHub({ context: ctx, outDir })` bakes an already-mounted context instead of a `devframes` list, reading `ctx.frames` and `ctx.views.buildStaticDirs` for what to emit, so a host that mounted its own context reuses `buildHub` rather than reimplementing it. Pass `clean: false` to bake beside an app's own build output.

---
title: Cross-Devframe Services
navigation:
  icon: i-lucide-share-2
description: 'ctx.services lets one devframe expose a typed, namespaced capability visible to every devframe. Two tiers: in-process services (provide/get) share live objects between devframes; wire services also register RPC and advertise to RPC clients.'
---

`ctx.services` lets one devframe expose a typed, namespaced capability visible to every devframe. Two tiers: in-process services (`provide`/`get`) share live objects between devframes; [wire services](#wire-services) also register RPC and advertise to RPC clients.

The [Node-Side API reference](/references/node-api#devframeserviceshost) collects the host methods and the definition/descriptor fields as lookup tables.

## Providing a service

Augment `DevframeServicesRegistry` with your id and type, then provide in setup:

```ts
export interface SourcesService {
  register: (entry: SourceEntry) => () => void
}

declare module 'devframe' {
  interface DevframeServicesRegistry {
    'my-plugin:sources': SourcesService
  }
}

export function setup(ctx: DevframeNodeContext) {
  ctx.services.provide('my-plugin:sources', createSourcesService())
}
```

Service ids prefix the provider's id (`<devframe-id>:<service>`), unique per context; a second `provide()` under a taken id throws [`DF0037`](https://devfra.me/errors/DF0037). `provide()` returns a revoke; guard idempotent setup with `has(id)`.

## Consuming a service

A consumer loads it with a types-only import (`import type {} from '@my-org/my-plugin'`), then reaches it in `setup`:

```ts
ctx.services.whenAvailable('my-plugin:sources', (sources) => {
  sources.register({ id: 'other-plugin:state', data: () => state })
})
```

Prefer `whenAvailable` over `get`: it fires immediately if provided, else on `provide`, and re-fires on revoke/re-provide. `get(id)` returns the implementation or `undefined` (ids without an augmentation as `unknown`).

## The `DevframeServicesHost` API

`DevframeServicesHost` exposes `provide(id, service) => revoke`, `get(id)`, `has(id)`, `whenAvailable(id, cb) => unsubscribe`, and `keys()`; plus a wire tier `install(input, options?) => Promise<api | undefined>` and `ready() => Promise<void>`.

## Wire services

A **wire service** is a shared node-side capability, an npm module.

### Shipping one

A service package's default export is a factory returning `DevframeServiceDefinition`:

```ts
export default function createOpenService(options?: OpenServiceOptions): DevframeServiceDefinition<OpenServiceApi, OpenServiceOptions> {
  return {
    package: '@devframes/service-open', // the registry key
    version: '1.0.0', // advertised; checked against declared ranges
    scope: 'devframes:service:open', // RPC namespace
    options,
    setup(ctx, { options }) {
      // `ctx` is pre-scoped: this registers `devframes:service:open:open-in-editor`
      ctx.rpc.register({ name: 'open-in-editor', handler: input => api.openInEditor(input) })
      return api // the node API served from ctx.services.get(package)
    },
  }
}
```

Two declaration merges type it: RPC ids into `DevframeRpcServerFunctions`, package → scope into `DevframeServicesScopeRegistry`.

### Declaring

Services are **declarative**: a devframe lists what it consumes; a hub, shared ones on `initHub`. The adapter resolves each package: for a devframe, **against its own dependencies** via [`importMetaUrl`](/guide/devframe-definition#resolving-against-the-devframes-own-dependencies).

```ts
// devframe side: on the definition
defineDevframe({
  importMetaUrl: import.meta.url, // resolution base for the declared packages
  services: [
    { package: '@devframes/service-open' },
    { package: '@devframes/service-shiki', version: '^1', options: { langs: ['vue'] } },
  ],
})
```

A hub lists shared, constructed services on `initHub({ services: [createShikiService(opts)] })`.

Entries are optional; uninstalled packages are skipped (`has() === false`). Mark one `required: true` to fail hard: [`DF0067`](https://devfra.me/errors/DF0067) on a missing package, [`DF0068`](https://devfra.me/errors/DF0068) on an unsatisfied `version` range (otherwise a range mismatch only warns, [`DF0069`](https://devfra.me/errors/DF0069)).

### Lifecycle: ready before setup

The hub constructs every declared service (all devframes plus `initHub`) **once**, deep-merging option sets (objects recurse, arrays union-dedupe, scalars later-win; override with `mergeOptions`), **before any `setup(ctx)` runs**, so setup consumes services synchronously via `ctx.services.get(pkg)`.

For a runtime-only service, `ctx.services.install(input)` builds immediately; re-installing a constructed package returns the existing API, warning [`DF0066`](https://devfra.me/errors/DF0066) if options can't merge.

### Feature-detecting on the RPC client

Installed services are advertised via `devframe:services` [shared state](/guide/shared-state), mirrored on the RPC client's `rpc.services`:

```ts
const rpc = await connectDevframe()

if (rpc.services.has('@devframes/service-open')) {
  const open = rpc.services.get('@devframes/service-open')!
  await open.rpc.call('open-in-editor', { path })
}
```

A reactive UI subscribes via `rpc.services.state()`. `has()`/`get()`/`keys()` are synchronous snapshots, empty before the first sync; each handle carries the `version` and `meta`.

### Built-in services

Three first-party wire services ship ready to install, each with its own page under [Add-ons › Services](/add-ons/services):

- **[`@devframes/service-open`](/add-ons/services/open)** (`devframes:service:open`): open files in an editor or OS explorer, refusing paths outside the workspace root.
- **[`@devframes/service-git`](/add-ons/services/git)** (`devframes:service:git`): typed read/write git operations on one repo.
- **[`@devframes/service-shiki`](/add-ons/services/shiki)** (`devframes:service:shiki`): node-side [Shiki](https://shiki.style) highlighting, LRU-cached and dual-theme.

## Services, RPC, or shared state?

- **Services**: node-to-node in-process live references, never crossing a wire.
- **[RPC](/guide/rpc)**: browser-to-node calls to a named function.
- **[Shared state](/guide/shared-state)**: serializable data synced node side ↔ RPC clients.

A service serves *other devframes*, RPC *surfaces or coding agents*, a [wire service](#wire-services) both.

---
title: Deep Linking
navigation:
  icon: i-lucide-link
description: 'Send a user to a view inside a devframe (from another dock, a coding agent, or a copied URL) two ways: the hub relays a dock activation to focus a dock in place; a standalone SPA reads its URL hash to restore the view.'
---

Send a user to a view inside a devframe (from another dock, a coding agent, or a copied URL) two ways: the hub relays a **dock activation** to focus a dock in place; a standalone SPA reads its **URL hash** to restore the view.

## Focusing a dock inside a hub

The active dock is state local to the host page. A mounted devframe, in its own iframe and RPC client, reaches it via the hub: `hub:docks:activate` switches the active dock, carrying an opaque `params` bag the target reads:

```ts
await rpc.call('hub:docks:activate', {
  dockId: 'devframes:plugin:data-inspector',
  params: { sourceId: 'my-plugin:store' },
})
```

The hub broadcasts the request and mirrors it into the [`devframe:docks:active`](/guide/shared-state) slot, so a dock mounting *because* of the switch converges on it. The target subscribes, filters on its `dockId`, and reads `params`; see [Cross-iframe dock activation](/guide/hub#cross-iframe-dock-activation).

Focus is one-shot: the [terminals dock](/add-ons/devframes/terminals#focusing-a-session) reads `params.sessionId`, the [Data Inspector](/add-ons/devframes/data-inspector#deep-linking) `params.sourceId`; a target naming something unregistered waits, then fires once. An id that never arrives is a no-op; an unknown `dockId` warns ([DF8107](/errors/DF8107)).

## Standalone URL deep links

Standalone, a devframe SPA owns its own URL. Encode the shareable view in the **hash** (`#…`): it round-trips a copied link, survives reload, and stays clear of the handshake query string (`?devframe_auth_token=`). Parse with `URLSearchParams`:

```ts
// read on load
const params = new URLSearchParams(location.hash.replace(/^#/, ''))
const sourceId = params.get('source')

// write back, without stacking history entries
history.replaceState(history.state, '', `#${params.toString()}`)

// react to back/forward and manual edits
window.addEventListener('hashchange', applyState)
```

The [terminals dock](/add-ons/devframes/terminals#deep-linking) keys a selection as `#id=<sessionId>`; the [Data Inspector](/add-ons/devframes/data-inspector#deep-linking) encodes its workbench (`#source=…&query=…` plus filter/auto-rerun flags). `replaceState` writes never fire `hashchange`, so boot read, live listener, and write-back don't loop.

Keep credentials out of anything shareable: a handshake token belongs in the query string, scrubbed once read (as the Data Inspector does), never in a copyable hash.

---
title: Build Your Own JSON-Render Frontend
navigation:
  icon: i-lucide-paintbrush
description: '@devframes/json-render-ui is the reference frontend, not the protocol; any implementation of the renderer contract replaces it. The Next hub witness ships a React one at src/client/json-render/.'
---

`@devframes/json-render-ui` is the reference frontend, not the protocol; any
implementation of the renderer contract replaces it. The [Next hub witness](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next) ships a React one at
`src/client/json-render/`.

## The contract

`@devframes/json-render/hub` owns the types:

```ts
import type { JsonRenderDockRenderer } from '@devframes/json-render/hub'

// a hub DockRenderer narrowed to the json-render dock entry
const renderer: JsonRenderDockRenderer = async ({ entry, container, context }) => {
  // mount your framework's root into `container`, render `entry.view`
  return { dispose() { /* unmount, unsubscribe */ } }
}
```

Resolve the entry's `view`:

- `{ stateKey }`: subscribe via `context.rpc.sharedState.get(stateKey)`, render
it as the live spec, re-render on `'updated'`. **Unsubscribe in `dispose`.**
- `{ spec }`: render the embedded spec directly.

Detect static output via `context.rpc.connectionMeta.backend === 'static'`,
disabling action dispatch there.

## Behavior expectations

- **Actions**: a spec action name dispatches the same-named RPC call. Never
bridge the reserved built-ins (`setState`, `pushState`, `removeState`,
`validateForm`) or promise probes (`then`/`catch`/`finally`); surface failures
to the view.
- **Validation**: validate element props against `basePropSchemas` from
`@devframes/json-render`; swap an invalid element for an error placeholder.
- **Unknown components**: a component your registry lacks renders as a
placeholder (type + prop-key gist) with a `console.warn`; the rest renders.
- **State reset**: reseed spec state only when the view identity changes, not
on every update.

## Plugging it in

- **Local registration**: a hub UI provider bundling its own client runtime passes
`createDevframeClientRuntime({ renderers: { 'json-render': myRenderer } })`;
local registrations win over the manifest.
- **A prebuilt renderer module**: bundle your renderer as one self-contained
browser ES module (framework and styles included), default-exporting the
renderer, plus a node helper returning the registration:
  ```ts
  import type { DockRendererRegistration } from '@devframes/hub/initiate'

  export function myRenderer(): DockRendererRegistration {
    return { type: 'json-render', file: myPrebuiltModulePath }
  }
  ```

  Compose it with `initHub({ renderers: [myRenderer()] })`; the hub serves
  the module and hub UI providers import it lazily (see [renderer
  modules](/guide/hub-initiate#renderer-modules)).

A prebuilt module must be **self-styling and shadow-root-safe**: deliver your
stylesheet into the mount subtree, which may be a shadow root. Read the theme
from the container's live `dark` class, brand color from the inherited
`--devframe-primary`.

---
title: Build Your Own Hub UI
navigation:
  icon: i-lucide-palette
description: A hub UI provider implements two contracts, the node-side ui slot and the browser-side context. @devframes/hub-ui is the reference.
---

A hub UI provider implements two contracts, the node-side `ui` slot and the browser-side context. `@devframes/hub-ui` is the reference.

## The node seam: `DevframeHubUi`

`initHub({ ui })` takes pure data (see [the `ui`
slot](/guide/hub-initiate#the-ui-slot)):

```ts
interface DevframeHubUi {
  viewer?: { distDir: string } // a standalone SPA served at the hub base
  embedded?: { entry: string } // a self-contained bootstrap at <base>embedded.js
  assets?: Record<string, () => string | Uint8Array> // extra UI-owned files
  setup?: (ctx) => void | Promise<void> // publish static config via ctx.staticConfig
}
```

Ship a function returning this object (`createUi()`) with prebuilt assets using
relative paths.

`setup(ctx)` runs once at hub init: config in `ctx.staticConfig` is serialized
into `ConnectionMeta.configs` and read by the RPC client at handshake.

## The browser-side contracts

A hub UI provider renders from the hub's shared state via
[`createDevframeClientRuntime()`](/guide/client-context), which assembles the
`DevframeClientContext` (docks, commands, renderers, when-clauses, connection)
and loads dock client scripts. Honor:

### Dock entry types

Render the built-in variants of the open dock union
(`DevframeDockEntryRegistry`, `@devframes/hub/types`): `iframe` (the entry's
`url` in a kept-alive iframe, honoring `subTabs` soft nav), `action` (a
dock-rail button running its client script), `custom-render` (a container its
client script mounts into), `launcher` (a launch call-to-action reflecting
`launcher.status`), `group` (one dock-rail button collapsing its members), and
`~builtin` (your native views for reserved ids). What to render per type is in
the [Hub API reference](/references/hub-api#dock-entry-types).

Honor `when` / `visibility`, `category` grouping (order from
`DEFAULT_CATEGORIES_ORDER`, `@devframes/hub/constants`), and the
`hub:docks:activate` broadcast. Show titles through
`resolveTitle(entry, locale)` so a registrant's `titleLocales` translations
reach the user.

An `iframe` entry serving a [remote assets package](/guide/client-assets) can
report it unreachable: its fallback page posts a `RemoteAssetsErrorMessage`
(`DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE`, `@devframes/hub/constants`) to
`window.parent`. Match it against the iframe's `contentWindow` to offer install + retry.

### The renderer registry and its fallback

**Every other dock type routes through the dock-renderer registry**: build it
with `createDockRenderersContext()` (`@devframes/hub/client`), wiring local
registrations and the hub's [renderer manifest](/guide/hub-initiate#renderer-modules):

```ts
import { createDockRenderersContext } from '@devframes/hub/client'

const renderers = createDockRenderersContext({
  context: () => context,
  manifest: () => manifestState.value(), // the devframe:dock-renderers slot
})

const result = await renderers.mount(entry, container)
```

Show a state per mount-result variant:

- `{ status: 'mounted', dispose }`: the renderer owns the container; call
`dispose` on unmount.
- `{ status: 'missing-renderer' }`: render a fallback (`renderers.has(type)`
answers up front).
- `{ status: 'load-error', error }`: import failed or the renderer threw;
render the error with retry.

### The theme contract for renderers

Renderer modules self-style (sometimes via a shadow root). Keep a live
`dark` class on the mount container and let CSS custom properties inherit; a
`--devframe-primary` ancestor rebrands rendered content.

## Reference points

- `packages/hub-ui`: the full reference hub UI provider (Vue, `@antfu/design`).
- [`examples/custom-hub-vite`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-vite) and
[`examples/custom-hub-next`](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next): hand-rolled
hub UI providers in vanilla DOM and React.

---
title: Adapters
navigation:
  icon: i-lucide-plug
description: 'The lowest-level path is the standard handler, initDevframe(def, { base }): a Web Standard (request: Request) => Promise<Response> for any catch-all route. Every path below builds on it.'
---

The lowest-level path is [the standard handler](/adapters/initiate), `initDevframe(def, { base })`: a Web Standard `(request: Request) => Promise<Response>` for any catch-all route. Every path below builds on it.

Adapters wrap it as `createXxx(def, options?)` at `devframe/adapters/<name>`. `cac` needs an optional peer ([`cac`](https://github.com/cacjs/cac)).

## Comparison

| Entry point                            | Module                       | Factory                        | Best for         |
| -------------------------------------- | ---------------------------- | ------------------------------ | ---------------- |
| [Standard Handler](/adapters/initiate) | `devframe/initiate`          | `initDevframe(def, { base })`  | Raw handler      |
| [`cac`](/adapters/cac)                 | `devframe/adapters/cac`      | `createCac()`                  | Standalone tools |
| [`dev`](/adapters/dev)                 | `devframe/adapters/dev`      | `createDevServer()`            | Dev server       |
| [`build`](/adapters/build)             | `devframe/adapters/build`    | `createBuild()`                | Static snapshots |
| [`vite`](/adapters/vite)               | `@vitejs/devtools-kit/node`  | `createPluginFromDevframe()`   | Vite DevTools    |
| [`embedded`](/adapters/embedded)       | `devframe/adapters/embedded` | `createEmbedded(def, { ctx })` | Runtime          |
| [`mcp`](/adapters/mcp)                 | `devframe/adapters/mcp`      | `createMcpServer()`            | Coding agents    |

## Mount paths

SPA basePath depends on the adapter:

| Adapter kind                | Default basePath | Reason                            |
| --------------------------- | ---------------- | --------------------------------- |
| `cli`, `build` (standalone) | `/`              | Owns the origin.                  |
| `vite`, `embedded` (hosted) | `/__<id>/`       | Shares a host framework's origin. |

Override with `DevframeDefinition.basePath`:

```ts
defineDevframe({
  id: 'my-tool',
  basePath: '/devframes/', // force this base regardless of adapter
  setup(ctx) { /* … */ },
})
```

The SPA discovers its base at runtime; see [Client](/guide/client#runtime-basepath-discovery).

---
title: The Standard Handler
navigation:
  icon: i-lucide-webhook
description: 'initDevframe() turns a DevframeDefinition into a running devframe whose .handler (a Web Standard (request: Request) => Promise<Response>) carries everything a devframe serves (SPA, __connection.json discovery, RPC socket, auth gate, MCP route) under one mount base. Every other serving path (adapters,…'
---

`initDevframe()` turns a `DevframeDefinition` into a running devframe whose `.handler` (a Web Standard `(request: Request) => Promise<Response>`) carries everything a devframe serves (SPA, `__connection.json` discovery, RPC socket, auth gate, MCP route) under one mount base. Every other serving path ([adapters](/adapters), [framework kits](/frameworks), [hub](/guide/hub-initiate)) is assembled from it. Mount it with a catch-all route.

```ts
import { initDevframe } from 'devframe/initiate'
import myDevframe from './my-tool'

const devtools = initDevframe(myDevframe, { base: '/__my-tool/' })
// devtools.base, devtools.handler, devtools.nodeMiddleware, devtools.attach,
// devtools.handleUpgrade, devtools.ready, devtools.context,
// devtools.connectionMeta(), devtools.close()
```

`base` is required: pass `resolveBasePath(def, 'hosted')` (`def.basePath ?? /__<id>/`) to default it, and the running devframe echoes it back as `devtools.base`. `handler`/`nodeMiddleware` await readiness internally. The running devframe binds no port, so [the WebSocket binding](#the-websocket-binding) is the host framework's call.

## Mount the handler

::code-group
```ts [Vite]
// vite.config.ts
// connect-style middleware + Vite's own server for the socket
import { initDevframe } from 'devframe/initiate'
import { defineConfig } from 'vite'
import myDevframe from './my-tool'

export default defineConfig({
  plugins: [{
    name: 'my-tool',
    apply: 'serve',
    configureServer(server) {
      const devtools = initDevframe(myDevframe, {
        base: '/__my-tool/',
        server: server.httpServer ?? undefined,
      })
      server.middlewares.use(devtools.nodeMiddleware)
    },
  }],
})
```

```ts [Nitro]
// routes/__my-tool/[...path].ts
// routes/__my-tool/index.ts
// for the namespace root, since a catch-all doesn't match its own empty path.
import { defineHandler } from 'nitro'
import { devtools } from '../../devtools'

export default defineHandler(event => devtools.handler(event.req))
```

```ts [Hono]
// server.ts
// `serve()` hands back the node server the socket rides on
import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import { devtools } from './devtools'

const app = new Hono()
app.all('/__my-tool/*', c => devtools.handler(c.req.raw))
devtools.attach(serve({ fetch: app.fetch, port: 3000 }))
```

```ts [Next.js]
// app/%5F_my-tool/[[...path]]/route.ts
// Next reserves `_`-prefixed folders, so the segment is URL-encoded (`%5F_` decodes to `__`).
import { initDevframe } from 'devframe/initiate'
import myDevframe from '@/my-tool'

export const runtime = 'nodejs'
export const dynamic = 'force-dynamic'

// Route handlers never see upgrades, so the socket asks for a side-car; the
// globalThis memo keeps a dev-time reload from starting a second one.
const g = globalThis as { devtools?: ReturnType<typeof initDevframe> }
const devtools = g.devtools ??= initDevframe(myDevframe, {
  base: '/__my-tool/',
  ws: { sidecar: true },
})
export const GET = devtools.handler
```

```ts [Nuxt]
// server/middleware/devtools.ts
import { devtools } from '../devtools'

export default defineEventHandler((event) => {
  const { pathname } = new URL(toWebRequest(event).url)
  // `devtools.base` is the normalized mount base; no repeated string.
  if (pathname.startsWith(devtools.base) || pathname === devtools.base.slice(0, -1))
    return devtools.handler(toWebRequest(event))
})
```

```ts [SvelteKit]
// src/routes/%5F_my-tool/[...path]/+server.ts
import myDevframe from '$lib/my-tool'
import { initDevframe } from 'devframe/initiate'

const g = globalThis as { devtools?: ReturnType<typeof initDevframe> }
const devtools = g.devtools ??= initDevframe(myDevframe, {
  base: '/__my-tool/',
  ws: { sidecar: true },
})
export const GET = ({ request }) => devtools.handler(request)
```
::

Host frameworks with dev-time module reloading (Next, Nitro, SvelteKit) re-evaluate the calling module, so memoize the running devframe on `globalThis` to avoid leaking a socket per reload. `@devframes/next`'s `createDevframeNextHandler` handles this.

## The WebSocket binding

Fetch handlers only hand over `Request`s, so the host framework binds the RPC socket. The **local binding** resolves in this order:

1. **`ws.port`**: a side-car server on that exact port.
2. **`server`**: share the host framework's `node:http` server; the upgrade binds at `<base>__ws`. No extra ports.
3. **`ws: { sidecar: true }`**: a side-car server on a free port, for host frameworks whose handlers never see upgrades (Next.js route handlers, Nitro, Rsbuild).
4. **The host framework's own upgrades.** With none set, the socket waits: `devtools.attach(server)` routes a server's `upgrade` events (returning a detach fn); `devtools.handleUpgrade(req, socket, head)` completes a single one from a listener you own. To run your own check before the socket opens, own the listener, match the `<base>__ws` path first (the listener sees every upgrade on the server, including the host framework's own), and call `handleUpgrade` once the check passes; the `server` option attaches its listener asynchronously, after any guard that wraps the listeners present at startup.

`ws.url` controls the *advertisement* instead, so the browser dials it verbatim. Alone, an external WebSocket server owns the transport and its auth (wire the running devframe's `context` via `createContextRpcServer` + a WS transport); alongside a local binding it overrides only the advertisement (the tunnel pattern).

`__connection.json` describes the active combination. Asking a configured running devframe to take over the host framework's upgrades reports `DF0055` (a local binding owns the socket) or `DF0056` (`ws.url` handed it off).

## Auth

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

`createDevServer`, `devframeViteBridge` (`@devframes/vite`), and `@devframes/next` are assembled from it internally. To host **many** devframes, use [`initHub`](/guide/hub-initiate).

---
title: CLI (cac)
navigation:
  icon: i-lucide-terminal
description: 'A cac CLI around a DevframeDefinition with dev, build, and mcp commands. cac is an optional peer:'
---

A [`cac`](https://github.com/cacjs/cac) CLI around a `DevframeDefinition` with `dev`, `build`, and `mcp` commands. `cac` is an optional peer:

```sh
npm install devframe cac
```

The [lower-level factories](#use-your-own-cli-framework) need no `cac`.

```ts
import { defineDevframe } from 'devframe'
import { createCac } from 'devframe/adapters/cac'

const myDevframe = defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  clientAssets: './client/dist',
  setup(ctx) { /* register docks, RPC, etc. */ },
})

await createCac(myDevframe).parse()
```

```sh
my-tool                         # dev server at http://localhost:9999/
my-tool --port 8080
my-tool build --out-dir dist-static
my-tool build --out-dir dist-static --base /my-tool/
my-tool mcp                     # stdio MCP server
```

The SPA serves at `/` standalone, `/__my-tool/` hosted ([Mount paths](/adapters/#mount-paths)).

## Options

`createCac(def, options?)`:

| Option         | Default                     | Description                                                                      |
| -------------- | --------------------------- | -------------------------------------------------------------------------------- |
| `defaultPort`  | `9999` (or `def.cli?.port`) | Dev port if `--port` unset.                                                      |
| `configureCli` | none                        | `(cli: CAC) => void` to add commands/flags.                                      |
| `onReady`      | none                        | `(info: { origin, port, app }) => void \| Promise<void>`, called once listening. |

Returns a `CacHandle`:

```ts
interface CacHandle {
  cli: CAC // raw cac instance; mutate before calling parse()
  parse: (argv?: string[]) => Promise<void>
}
```

## Definition-level `cli` fields

```ts
defineDevframe({
  id: 'my-tool',
  clientAssets: './client/dist', // built SPA served as the UI
  cli: {
    command: 'mytool', // binary name; default: the id
    port: 7777, // preferred port
    portRange: [7777, 9000], // passed through to get-port-please
    random: false, // passed through to get-port-please
    host: '127.0.0.1', // default bind host; --host overrides
    open: true, // auto-open the browser on dev start; embeds the current OTP so the tab lands authenticated
    configure(cli) { // contribute capability flags/commands
      cli.option('--config <file>', 'Custom config file')
        .option('--no-files', 'Skip file matching')
    },
  },
  setup(ctx, { flags }) {
    // `flags` is the parsed cac flag bag, holding both devframe's
    // built-ins (`--port`, `--host`, `--open`) and anything declared in
    // `cli.configure` or `configureCli`.
  },
})
```

`configure` runs *before* `createCac`'s `configureCli`.

## Headless logging

Print a banner via `onReady`:

```ts
await createCac(myDevframe, {
  onReady({ origin }) {
    console.log(`ESLint Config Inspector ready at ${origin}`)
  },
}).parse()
```

## Use your own CLI framework

Peer factories for a commander/yargs program:

| Building block                       | Entry                     | Purpose                           |
| ------------------------------------ | ------------------------- | --------------------------------- |
| [`createDevServer()`](/adapters/dev) | `devframe/adapters/dev`   | h3 + WebSocket RPC + SPA mount    |
| [`createBuild()`](/adapters/build)   | `devframe/adapters/build` | Static deploy                     |
| [`createMcpServer()`](/adapters/mcp) | `devframe/adapters/mcp`   | stdio MCP server                  |
| `parseCliFlags(schema, raw)`         | `devframe/adapters/cac`   | Validate flags (`CliFlagsSchema`) |

See the [Standalone CLI guide](/guide/standalone-cli#use-your-own-cli-framework).

---
title: Dev
navigation:
  icon: i-lucide-server-cog
description: 'createCac''s building block: h3 + WebSocket RPC + the SPA at the resolved base path.'
---

`createCac`'s building block: h3 + WebSocket RPC + the SPA at the resolved base path.

```ts
import { createDevServer } from 'devframe/adapters/dev'
import myDevframe from './my-tool'

const handle = await createDevServer(myDevframe, {
  port: 7777,
  onReady: ({ origin }) => console.log(`Ready at ${origin}`),
})

// graceful shutdown: SIGINT, hot reload, test teardown
process.on('SIGINT', () => handle.close().then(() => process.exit(0)))
```

Returns a `StartedServer`: origin, port, h3 app, WS server, RPC group, `close()`.

| Option        | Default                                      | Description                       |
| ------------- | -------------------------------------------- | --------------------------------- |
| `host`        | `def.cli?.host ?? 'localhost'`               | Bind host.                        |
| `port`        | resolved via `resolveDevServerPort`          | Listen port.                      |
| `flags`       | `{}`                                         | To `setup(ctx, { flags })`.       |
| `distDir`     | `def.clientAssets`                           | SPA dist; unset = bridge mode.    |
| `basePath`    | `resolveBasePath(def, 'standalone')`         | Mount override.                   |
| `app`         | fresh h3 app                                 | Mount onto.                       |
| `openBrowser` | resolves from `flags.open` / `def.cli?.open` | `false` off; string opens a path. |
| `ws`          | `def.cli?.ws`                                | RPC WebSocket; see below.         |
| `onReady`     | none                                         | WS-bind callback.                 |

## WebSocket endpoint

The RPC socket shares the HTTP port at `__ws`, advertised *relative*. Configure `def.cli.ws`:

| Field   | Scenario                 | Advertised `websocket`    |
| ------- | ------------------------ | ------------------------- |
| `route` | same server, other route | `{ path: <route> }`       |
| `port`  | different port           | `{ port, path: <route> }` |
| `url`   | remote origin            | URL verbatim              |

Precedence `url` > `port` > `route`; `url` keeps the socket local on `route`.

## Port resolution

`resolveDevServerPort(def, opts?)` resolves a port before start.

```ts
import { resolveDevServerPort } from 'devframe/adapters/dev'

const port = await resolveDevServerPort(myDevframe, { host: '127.0.0.1' })
// honors def.cli?.port / portRange / random
```

| Option        | Default                        | Description                              |
| ------------- | ------------------------------ | ---------------------------------------- |
| `host`        | `def.cli?.host ?? 'localhost'` | Bind host (`get-port-please` detection). |
| `defaultPort` | `def.cli?.port ?? 9999`        | Preferred-port override.                 |

---
title: Build
navigation:
  icon: i-lucide-package
description: 'Produces a static deploy:'
---

Produces a static deploy:

1. Copies the SPA dist into `<outDir>`.
2. Runs `setup(ctx)` with `mode: 'build'`.
3. Collects RPC dumps for every `'static'` and `'query'` with `dump.inputs` / `snapshot: true`.
4. Writes `__connection.json` (`{ backend: 'static' }`) and sharded dumps under `__rpc-dump/`.

```ts
import { createBuild } from 'devframe/adapters/build'
import myDevframe from './my-tool'

await createBuild(myDevframe, {
  outDir: 'dist-static',
})
```

| Option    | Default            | Description                                                   |
| --------- | ------------------ | ------------------------------------------------------------- |
| `outDir`  | `dist-static`      | Output directory (cleared).                                   |
| `distDir` | `def.clientAssets` | SPA dist override (or [remote assets](/guide/client-assets)). |
| `pretty`  | `false`            | Pretty-print dump JSON.                                       |

The RPC client runs read-only. For a custom URL base, build with relative asset paths (`vite.base: './'`).

`buildHub()` from `@devframes/hub/build` produces the same kind of deploy for a whole hub: [Static builds](/guide/hub-initiate#static-builds).

---
title: Vite
navigation:
  icon: i-simple-icons-vite
description: Wraps a DevframeDefinition so Vite DevTools' kit plugin-scan picks it up. The factory lives in @vitejs/devtools-kit/node, keeping devframe Vite-free.
---

Wraps a `DevframeDefinition` so Vite DevTools' kit plugin-scan picks it up. The factory lives in `@vitejs/devtools-kit/node`, keeping devframe Vite-free.

```ts
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import myDevframe from './my-tool'

export default function myVitePlugin() {
  return createPluginFromDevframe(myDevframe)
}
```

The returned object has the shape `{ name, devtools: { setup, capabilities } }`. See [DevTools Plugin](https://devtools.vite.dev/kit/devtools-plugin).

| Option  | Default                    | Description                                                               |
| ------- | -------------------------- | ------------------------------------------------------------------------- |
| `name`  | `devframe:<id>`            | Plugin name.                                                              |
| `base`  | `def.basePath ?? /.${id}/` | Mount path override.                                                      |
| `dock`  | `{}`                       | Overrides for the iframe dock entry (category, icon, when).               |
| `setup` | none                       | Setup hook run only in the Vite host; receives the kit-augmented context. |

---
title: Embedded
navigation:
  icon: i-lucide-box
description: 'Register a devframe into an already-running context at runtime: dynamic, post-startup registration (unlike vite''s plugin-scan). Inherits the hosted /__<id>/ default.'
---

Register a devframe into an already-running context at runtime: dynamic, post-startup registration (unlike [`vite`](/adapters/vite)'s plugin-scan). Inherits the hosted `/__<id>/` default.

```ts
import { createEmbedded } from 'devframe/adapters/embedded'
import myDevframe from './my-tool'

await createEmbedded(myDevframe, { ctx: existingCtx })
```

| Option | Required | Description                                    |
| ------ | -------- | ---------------------------------------------- |
| `ctx`  | ✓        | Target `DevframeNodeContext` to register into. |

---
title: MCP
navigation:
  icon: i-lucide-bot
description: 'Exposes a devframe''s agent-facing API as a Model Context Protocol server: coding agents call flagged RPCs and read resources.'
---

Exposes a devframe's agent-facing API as a [Model Context Protocol](https://modelcontextprotocol.io) server: coding agents call flagged RPCs and read resources.

The implementation (and the MCP SDK behind it) lives in **`@devframes/agentic`**, an optional peer of `devframe`: install it to enable the agent surface, and keep importing everything from `devframe/adapters/mcp` - the peer is loaded for you, never imported directly. A devframe without an agent surface ships with neither the peer nor the SDK installed:

```sh
npm install @devframes/agentic
```

```ts
import { createMcpServer } from 'devframe/adapters/mcp'
import myDevframe from './my-tool'

await createMcpServer(myDevframe, { transport: 'stdio' })
```

`createMcpServer` serves `stdio` through the MCP SDK's `serveStdio`, pinning one server instance per connection.

## Route-based server

The dev server exposes the same MCP API over HTTP, live. The default setting is **`'auto'`**: the route mounts once the devframe exposes an agent surface (an `agent`-flagged RPC, a registered tool or resource) *and* `@devframes/agentic` is installed - flag your first function, install the peer, and the agent view is on. A devframe with nothing flagged mounts no route and loads no MCP code; an agent surface without the peer warns once ([DF0078](/errors/DF0078)) and mounts nothing, while an explicit `mcp` setting without the peer throws ([DF0079](/errors/DF0079)). `mcp: false` stays silent either way.

Pin the behavior where you host the tool - it's a hosting decision, so pass `mcp` to `createCac` when you assemble the CLI (or to `createDevServer` / `initDevframe` / `initHub` when you host it programmatically): `true` always mounts, `false` never mounts, an object customises the route:

```ts
import { createCac } from 'devframe/adapters/cac'
import myDevframe from './my-tool'

createCac(myDevframe, { mcp: true }).parse() // force on; `false` forces off; omit for 'auto'
```

The endpoint speaks Streamable-HTTP at `/__mcp` (`/__<id>/__mcp` under a host framework), sharing its origin/port. `--mcp` / `--no-mcp` override per run; `__connection.json` advertises the mounted route.

The endpoint is **stateless**: it serves the [2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28) per request through the SDK's `createMcpHandler`, building a fresh MCP server for each request, so every HTTP request stands alone, with no `Mcp-Session-Id` to correlate. 2025-era clients are still served through the SDK's stateless legacy path.

### Origin gate, and opt-in identity

The **origin gate** guards every request: `Origin` must be loopback (or allow-listed), and `Origin`-less requests are rejected (a disallowed origin gets `403`). This is DNS-rebinding hardening that keeps a browser from reaching the route across origins. It is **not** a network-locality check: `Origin` is a request header, so a non-browser client (curl, a script) sends any value it likes.

Same-machine locality is instead proven from the **connected peer**: on the origin-only default (the `'auto'` default and `mcp: true`, with no widened `allowedOrigins` and no identity check), a request whose peer address is not loopback gets `403` even with a loopback `Origin`. The peer address comes from the socket, not a header, so a remote client cannot forge it. This is what makes "trusts same-machine callers" hold, and it's all a local dev tool needs. (A host that can't resolve a peer address, such as a serverless route, keeps the origin-only behavior; harden it with `authorization`.)

`Origin` still proves nothing about *who* is calling, and the peer check only proves *where from*. When same-machine isn't your trust boundary (a LAN/tunnel origin, a shared/CI host, a destructive tool surface), layer on an **identity check** with `authorization` - which also lifts the loopback-peer restriction, so authenticated callers may be remote:

```ts
createCac(myDevframe, {
  mcp: { authorization: process.env.MY_TOKEN },
}).parse()
```

`authorization` takes a bearer token (backed by an env var, never a literal), a `(request) => boolean` callback that governs identity only and cannot relax the origin gate, or `false` for the explicit origin-only default.

A request presents the bearer as `Authorization: Bearer <token>`, matched in constant time; a missing or wrong bearer gets `401` with a `WWW-Authenticate: Bearer` challenge. The origin gate always runs first, so a disallowed origin is `403` regardless of the credential. Widen the origin allow-list for a tunnel/LAN reach with `mcp: { authorization: process.env.MY_TOKEN, allowedOrigins: ['https://tunnel.example.com'] }`.

Never place the token in a URL, in `__connection.json`, in the instance registry, in logs, or on the command line; it belongs only in configuration and the `Authorization` header.

### Hosted bridges

Both bridges forward the setting to their side-car dev server, advertising the mounted endpoint in `__connection.json`:

```ts
// Vite (@devframes/vite)
devframeViteBridge(myDevframe, { mcp: true })

// Next.js (@devframes/next)
createDevframeNextHandler(myDevframe, { mcp: true })
```

Both honor the same contract: omitted is `'auto'`, `true` forces the origin-only route on; add `mcp: { authorization }` to harden.

## Custom host frameworks

`createMcpFetchHandler(ctx, options)` returns the endpoint as a `Request → Response` handler plus a `dispose()`; mount it on any fetch server.

```ts
import { createMcpFetchHandler } from 'devframe/adapters/mcp'

const mcp = createMcpFetchHandler(ctx, {
  serverName: 'my-tool (devframe)',
  serverVersion: '1.0.0',
  exposeSharedState: true,
  // Optional identity check on top of the origin gate; omit for origin-only.
  // authorization: process.env.MY_TOKEN,
})
// route every method on /__mcp to mcp.fetch(request)
```

## Discovery: `devframe connect`

The `devframe` bin ships an MCP **connector** ([next-devtools-mcp](https://github.com/vercel/next-devtools-mcp)-style) that finds every running devframe. Configure once:

```json
{
  "mcpServers": {
    "devframe": { "command": "npx", "args": ["devframe", "connect"] }
  }
}
```

Two gateway tools (`devframe:connect:*` ids; see [tool ids and wire names](/guide/agent-native#tool-ids-and-wire-names)):

- **`devframe_connect_list-instances`**: list running dev servers and their MCP tools.
- **`devframe_connect_call-tool`**: invoke one tool on a running devframe (`{ port, tool, args }`) over Streamable-HTTP.

Discovery reads the **instance registry**: every `createDevServer` writes `~/.devframe/instances/<pid>-<port>.json`, dialed with a loopback origin. In-process host frameworks register via `registerDevframeInstance` (`devframe/node`). `--port <n>` probes a port for `__connection.json` at its root; add `--base <path>` for a devframe mounted below the root (e.g. `devframe connect --port 5173 --base /__devtools/` for Vite DevTools). A probe only counts a JSON object as connection meta, so an SPA fallback page on the wrong path reads as "no instance". `DEVFRAME_INSTANCES_DIR` relocates the registry, `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` opts out.

The connector needs the same optional `@devframes/agentic` peer as the adapter; `devframe connect` without it throws [DF0046](/errors/DF0046).

Most instances trust same-machine callers, so the connector reaches them with no credential. For an instance you *hardened* with a bearer, the connector reads `DEVFRAME_MCP_AUTH_TOKEN` and presents it (never a CLI flag, since command-line arguments are visible to other processes).

See [Agent-Native](/guide/agent-native) for the API and safety model.

---
title: Frameworks
navigation:
  icon: i-lucide-layers
description: 'The framework kits (@devframes/vite, @devframes/nuxt, @devframes/next) integrate devframe with a meta-framework''s dev server. Two subpaths:'
---

The framework kits ([`@devframes/vite`](/frameworks/vite), [`@devframes/nuxt`](/frameworks/nuxt), [`@devframes/next`](/frameworks/next)) integrate devframe with a meta-framework's dev server. Two **subpaths**:

| Scope      | Subpath      | You are…                                                                 |
| ---------- | ------------ | ------------------------------------------------------------------------ |
| **single** | `.../single` | building & dev-serving a **single devframe's SPA** with that tool        |
| **hub**    | `.../hub`    | mounting a whole **[hub](/guide/hub)** (many devframes) inside that tool |

The bare package root throws, pointing to the two subpaths.

| Package                               | single                                                            | hub                                   |
| ------------------------------------- | ----------------------------------------------------------------- | ------------------------------------- |
| [`@devframes/vite`](/frameworks/vite) | `devframeVitePlugin` / `devframeViteBridge` / `devframeVite`      | `viteDevframeHub` (+ `/hub/client`)   |
| [`@devframes/nuxt`](/frameworks/nuxt) | the Nuxt module (`modules: ['@devframes/nuxt/single']`)           | the hub Nuxt module (+ `/hub/client`) |
| [`@devframes/next`](/frameworks/next) | `withDevframe` + `createDevframeNextHandler` (+ `/single/client`) | `nextDevframeHub` (+ `/hub/client`)   |

## single: author one devframe

For framework-neutral CLI/build/embedded outputs, use the [adapters](/adapters) instead.

## hub: mount a hub

Each `hub` scope wraps [`initHub`](/guide/hub-initiate) and defaults the UI to [`@devframes/hub-ui`](/guide/build-your-own-hub-ui)'s `createUi()` (`ui` to override, `ui: false` for headless). Per tool: **[Vite](/frameworks/vite#mounting-a-hub)**, **[Nuxt](/frameworks/nuxt#mounting-a-hub)**, **[Next](/frameworks/next#mounting-a-hub)**.

`@devframes/vite/hub` and `@devframes/nuxt/hub` recommend the native hub UI providers ([Vite DevTools](https://devtools.vite.dev), [Nuxt DevTools](https://devtools.nuxt.com)) once (silence with `{ quiet: true }`). Next has none, so `@devframes/next/hub` stays quiet.

---
title: Vite
navigation:
  icon: i-simple-icons-vite
description: '@devframes/vite splits into @devframes/vite/single (dev-serve one devframe''s SPA) and @devframes/vite/hub (mount a hub); the bare import throws.'
---

`@devframes/vite` splits into **`@devframes/vite/single`** (dev-serve one devframe's SPA) and [**`@devframes/vite/hub`**](#mounting-a-hub) (mount a hub); the bare import throws.

`single` exports `devframeVitePlugin`, `devframeViteBridge`, and `devframeVite`; also used by [`@devframes/nuxt`](/frameworks/nuxt).

```ts
import { devframeViteBridge, devframeVitePlugin } from '@devframes/vite/single'
import { defineConfig } from 'vite'
import myDevframe from './my-tool'

export default defineConfig({
  /** Statically mounts the built SPA at `/__<id>/`, with no RPC server: */
  plugins: [devframeVitePlugin(myDevframe)],
  // Or bridge the RPC/WS backend into this dev server instead, so the
  // user app owns the SPA:
  // plugins: [devframeViteBridge(myDevframe)],
})
```

## `devframeVitePlugin`: static mount

Mounts `def.clientAssets` at `options.base` (`/__<id>/` default) with SPA fallback. `clientAssets` accepts a local directory or [remote assets](/guide/client-assets).

| Option | Default                      | Description |
| ------ | ---------------------------- | ----------- |
| `base` | `def.basePath ?? '/__<id>/'` | Mount path. |

## `devframeViteBridge`: RPC bridge

Devframe spawns a separate RPC + WS server and registers Vite middleware at `<base>__connection.json`. To share Vite's port, pass its HTTP server to [`initDevframe`](/adapters/initiate) / `initHub` via `server`.

| Option           | Default                        | Description                                                                                                                                                                                                       |
| ---------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base`           | `def.basePath ?? '/__<id>/'`   | Mount path.                                                                                                                                                                                                       |
| `port`           | share Vite's HTTP server       | Pin a side-car RPC port instead.                                                                                                                                                                                  |
| `host`           | `def.cli?.host ?? 'localhost'` | Bind host for a pinned side-car.                                                                                                                                                                                  |
| `flags`          | none                           | To `def.setup(ctx, { flags })`.                                                                                                                                                                                   |
| `auth`           | gated (interactive OTP)        | `false` to opt out, or a `DevframeAuthHandler` for a custom scheme.                                                                                                                                               |
| `mcp`            | `'auto'`                       | Expose the MCP route at `<base>__mcp`. `'auto'` mounts once agent tools exist; `true` forces the origin-only route on (trusts same-machine callers); `McpRouteOptions` can add an `authorization` identity check. |
| `allowedOrigins` | loopback-only                  | Widen the WS origin check for a `vite --host` / container / tunnel origin: extra origins, a `WsOriginRegistry`, or `false` to disable (the auth gate stays the trust boundary).                                   |

## `devframeVite`: convenience wrapper

`devframeVite(def, { bridge, ...opts })` forwards to `devframeViteBridge` when `bridge: true`, else `devframeVitePlugin`; use them directly when a devframe needs both.

## Mounting a hub

`@devframes/vite/hub` mounts a [hub](/guide/hub) with `viteDevframeHub()`: wraps `initHub`, shares Vite's HTTP server, defaults dock UI to `@devframes/hub-ui`.

```ts
import { viteDevframeHub } from '@devframes/vite/hub'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [viteDevframeHub({ devframes: [] })],
})
```

Pass `ui` to swap the hub UI provider, `ui: false` for headless (via `@devframes/vite/hub/client`'s `mountDevframeHubClient()`). Vite DevTools (`@vitejs/devtools-kit`) supports this natively; recommended once (`{ quiet: true }` to silence).

`build: true` also bakes the hub into `vite build` output: [`buildHub`](/guide/hub-initiate#static-builds) writes the static hub subtree into `<outDir><base>` and the UI's `embedded.js` tag is injected into the built HTML, so the deployed app ships working devtools against a `static` backend (baked reads, no live server).

---
title: Nuxt
navigation:
  icon: i-simple-icons-nuxtdotjs
description: '@devframes/nuxt splits into @devframes/nuxt/single (author one devframe) and @devframes/nuxt/hub (mount a hub); the bare import throws.'
---

`@devframes/nuxt` splits into `@devframes/nuxt/single` (author one devframe) and [`@devframes/nuxt/hub`](#mounting-a-hub) (mount a hub); the bare import throws.

The `single` module wires a Nuxt SPA as a devframe's browser side and types `useNuxtApp().$rpc` as `DevframeRpcClient`.

## Install

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@devframes/nuxt/single'],
})
```

## Using `$rpc`

```vue [app.vue]
<script setup>
const { $rpc } = useNuxtApp()
const payload = await $rpc.call('my-tool:get-payload')
</script>
```

Or a composable:

```ts [composables/usePayload.ts]
export function usePayload() {
  const { $rpc } = useNuxtApp()
  return useAsyncData('payload', () => $rpc.call('my-tool:get-payload'))
}
```

## Options

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@devframes/nuxt/single'],
  devframe: {
    baseURL: './', // where the devframe snapshot lives, relative to the page
    skipAppDefaults: false, // opt out of the app.baseURL / vite.base defaults
  },
})
```

- **`baseURL`** resolves against `document.baseURI` at runtime.
- **`skipAppDefaults: true`** ships absolute asset paths.

## Dev-time RPC bridge

Pass a devframe definition:

```ts [nuxt.config.ts]
import myDevframe from './src/my-tool' // defineDevframe(...) export

export default defineNuxtConfig({
  modules: [['@devframes/nuxt/single', { devframe: myDevframe }]],
})
```

`nuxt dev` now:

- Starts a WebSocket RPC server on a [`get-port-please`](https://github.com/unjs/get-port-please) port (respects `devframe.cli.port` / `portRange` / `random`).
- Registers Vite middleware at `${baseURL}__connection.json`.
- Runs `devframe.setup(ctx, { flags })`.
- Cleans up on Vite restart, `nuxt dev` shutdown, and bundle close.

On by default when `devframe` is set; disable it (browser side only) with `devMiddleware: false`.

### Customizing the bridge

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [['@devframes/nuxt/single', {
    devframe: myDevframe,
    devMiddleware: {
      port: 7777,
      host: '0.0.0.0',
      flags: { config: process.env.MY_CONFIG },
    },
  }]],
})
```

- **`port`** pins the bridge port (else `get-port-please` picks one).
- **`host`** defaults to `nuxt.options.devServer.host ?? devframe.cli?.host ?? 'localhost'`.
- **`flags`** → `devframe.setup(ctx, { flags })`.

### Relationship to `createCac`

Production uses `createCac` (or `createBuild`), producing a static `__connection.json` + `__rpc-dump/` snapshot from `clientAssets`:

```
my-tool/
├── bin.mjs               # createCac(myDevframe).parse()
├── src/
│   ├── my-tool.ts        # defineDevframe + setup(ctx) { ctx.rpc.register(...) }
│   └── app/              # Nuxt SPA, uses `@devframes/nuxt`
└── dist/
    ├── cli.mjs           # bundled Node entry
    └── public/           # Nuxt build output, pointed at by clientAssets
```

## How it works

At build time it sets the `app.baseURL` / `vite.base` defaults, merges `{ devframe: { baseURL } }` into `runtimeConfig.public`, and injects a client-only plugin (`helpers/nuxt/runtime/plugin.client`):

```ts
const rpc = await connectDevframe({ baseURL: config.public.devframe.baseURL })
return { provide: { rpc } }
```

At runtime the SPA fetches `./__connection.json` and branches on `backend`: `websocket` in dev, `static` from a `createBuild` snapshot.

## Mounting a hub

`@devframes/nuxt/hub` mounts a whole [hub](/guide/hub) alongside `nuxt dev`, injecting `@devframes/hub-ui`'s dock. `ui` swaps the default; `ui: false` gives a headless hub via `@devframes/nuxt/hub/client`.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [['@devframes/nuxt/hub', { devframes: [] }]],
})
```

Nuxt DevTools (`@nuxt/devtools`) integrates the same protocol natively; this module recommends it once (silence with `{ quiet: true }`).

## See also

- [Standalone CLI recipe](/guide/standalone-cli)
- [Client](/guide/client): `connectDevframe` reference
- [Adapters](/adapters)

---
title: Next
navigation:
  icon: i-simple-icons-nextdotjs
description: '@devframes/next hosts devframes from a Next.js App Router app via a route handler: one fetch handler serves each SPA and its __connection.json via serveStaticHandler.'
---

> [!WARNING]
> Experimental. `@devframes/next`'s API is still settling; expect changes before a stable release.

`@devframes/next` hosts devframes from a Next.js App Router app via a route handler: one `fetch` handler serves each SPA and its `__connection.json` via [`serveStaticHandler`](/adapters/dev).

It splits into `@devframes/next/single` and [`@devframes/next/hub`](#mounting-a-hub); the bare import throws. `single` gives **`withDevframe()`**, **`createDevframeNextHandler()`**, and a React RPC-client helper (`@devframes/next/single/client`).

## Config

```ts [next.config.mjs]
import { withDevframe } from '@devframes/next/single'

export default withDevframe({
  // ...your own Next config
})
```

`withDevframe` sets `skipTrailingSlashRedirect: true`, keeping the rest.

## Hosting a single devframe

`createDevframeNextHandler(definition)` serves the SPA and starts a side-car RPC/WS server:

```ts [app/__my-tool/[[...path\\]\\]/route.ts]
import { createDevframeNextHandler } from '@devframes/next/single'
import myDevframe from '@/my-tool'

export const runtime = 'nodejs'
export const dynamic = 'force-dynamic'

const handler = createDevframeNextHandler(myDevframe)
export const GET = handler.fetch
```

`close()` stops the side-car; `ready` resolves when listening.

| Option           | Default                        | Description                                                                                                                                                                                                  |
| ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `base`           | `def.basePath ?? '/__<id>/'`   | SPA mount path.                                                                                                                                                                                              |
| `host`           | `def.cli?.host ?? 'localhost'` | Side-car bind host.                                                                                                                                                                                          |
| `port`           | from `def.cli?.port`           | Side-car port.                                                                                                                                                                                               |
| `flags`          | none                           | Passed to `def.setup(ctx, { flags })`.                                                                                                                                                                       |
| `auth`           | `false`                        | `true` for the OTP gate, or a handler.                                                                                                                                                                       |
| `mcp`            | `'auto'`                       | Expose the MCP route. `'auto'` mounts once agent tools exist; `true` forces the origin-only route on (trusts same-machine callers); `McpRouteOptions` can add an `authorization` identity check.             |
| `allowedOrigins` | loopback-only                  | Widen the side-car WS origin check for a remotely-accessed dev server (container / Codespace / tunnel): extra origins, a `WsOriginRegistry`, or `false` to disable (the auth gate stays the trust boundary). |
| `key`            | `@devframes/next:<id>:<base>`  | `globalThis` memoization key.                                                                                                                                                                                |

## Hosting a hub

[`@devframes/hub`](/guide/hub)'s `initHub` mounts every devframe under `<base><id>/` behind one `handler` (memoize on `globalThis`; see `examples/custom-hub-next`):

```ts [devframe/host.ts]
import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'

// Next route handlers can't accept WS upgrades, so the socket asks for a
// side-car of its own; the browser discovers it via `__connection.json`.
const hub = initHub({
  base: DEVFRAMES_HUB_BASE,
  devframes: [myDevframe],
  ws: { sidecar: true },
  auth: false,
})

export const { handler } = hub // mount on a `[[...path]]` route handler
```

```ts [app/__devframes/[[...path\\]\\]/route.ts]
export const runtime = 'nodejs'
export const dynamic = 'force-dynamic'

export async function GET(request: Request): Promise<Response> {
  return handler(request) // serves every mounted SPA + connection meta
}
```

## React RPC client

```tsx [app/providers.tsx]
'use client'
import { RpcProvider } from '@devframes/next/single/client'

export function Providers({ children }: { children: React.ReactNode }) {
  return <RpcProvider baseURL="/__my-tool/">{children}</RpcProvider>
}
```

`useRpc()` returns the `DevframeRpcClient` (`null` while connecting), `useRpcStatus()` the live `{ status, error }`; both throw outside `<RpcProvider>`.

```tsx [app/panel.tsx]
'use client'
import { useRpc, useRpcStatus } from '@devframes/next/single/client'

export function Panel() {
  const rpc = useRpc()?.scope('my-tool:')
  const { error } = useRpcStatus()
  if (!rpc)
    return <p>{error ? `connection failed: ${error.message}` : 'connecting…'}</p>
  // rpc.rpc.call('get-payload'), rpc.sharedState, …
}
```

## Runtime

Handlers calling `fetch` pin `runtime = 'nodejs'` (Node side-car).

## Mounting a hub

`@devframes/next/hub`'s `nextDevframeHub()` is a `globalThis`-memoized handle; `createNextDevframeHub()` is the builder. UI defaults to `@devframes/hub-ui`; `ui` swaps it, `ui: false` gives a headless hub via `@devframes/next/hub/client`'s `useDevframeHubClient()`.

```ts [app/__devframes/[[...path\\]\\]/route.ts]
import { nextDevframeHub } from '@devframes/next/hub'

export const runtime = 'nodejs'
export const dynamic = 'force-dynamic'

const hub = nextDevframeHub({ devframes: [] })
export const GET = (req: Request) => hub.handler(req)
export const POST = (req: Request) => hub.handler(req)
export const DELETE = (req: Request) => hub.handler(req)
```

The aggregate MCP route mounts by default once any mounted devframe exposes agent tools (the `'auto'` setting). Force it on with `mcp: true` (origin-only, trusting same-machine callers), off with `mcp: false`, or add `mcp: { authorization }` for an identity check when the app is reachable beyond localhost.

No native hub UI provider here, so this scope stays quiet; `createDevframeNextHost()` is the low-level `DevframeHost`.

## See also

- [Vite](/frameworks/vite)
- [Hub](/guide/hub)
- [custom-hub-next](https://github.com/devframes/devframe/tree/main/examples/custom-hub-next)

---
title: Ecosystem
description: Devtools, hosts and services built on Devframe by the community and the core team.
navigation:
  layout: page
  icon: i-lucide-blocks
seo:
  title: 'Devframe ecosystem: devtools, hosts and services'
  description: Browse devtools built on Devframe, the hub UI providers that host them, wire services, and real products running Devframe in production.
---

::ecosystem-list
```yaml [props]
packages:
  - name: ESLint Config Inspector
    description: Inspects ESLint flat configs
    author: eslint
    repo: eslint/config-inspector
    category: Devframes
    image: /images/ecosystem/logos/eslint-config-inspector.svg
    color: '#4b32c3'
  - name: node-modules-inspector
    description: Visualizes the node_modules dependency graph
    author: antfu
    repo: antfu/node-modules-inspector
    category: Devframes
    image: /images/ecosystem/logos/node-modules-inspector.svg
    color: '#3f8f4a'
  - name: vite-plugin-inspect
    description: Inspects the intermediate state of Vite plugins
    author: antfu-collective
    repo: antfu-collective/vite-plugin-inspect
    category: Devframes
    icon: i-carbon-search-advanced
    color: '#646cff'
  - name: medula
    description: Lets AI agents inspect and mutate live app state over MCP
    author: posva
    repo: posva/medula
    category: Devframes
    icon: i-octicon-mcp-24
    color: '#d97706'
  - name: pulls.review
    description: Groups pull request changes and reviews them one scope at a time
    author: antfu
    repo: antfu/pulls.review
    category: Devframes
    image: /images/ecosystem/logos/pulls-review.svg
    color: '#3fb982'
  - name: Pinia Colada devtools
    description: Inspects Pinia Colada queries and mutations
    author: posva
    url: https://github.com/posva/pinia-colada/tree/main/devtools
    category: Devframes
    image: /images/ecosystem/logos/pinia-colada.svg
    color: '#e0b000'
  - name: UnoCSS Inspector
    description: Inspects generated utility classes and matched rules
    author: unocss
    url: https://github.com/unocss/unocss/tree/main/packages-integrations/inspector
    category: Devframes
    image: /images/ecosystem/logos/unocss-inspector.svg
  - name: Vite DevTools
    description: Hosts many devframes in one dock for any Vite app
    author: vitejs
    url: https://devtools.vite.dev
    category: Hosts
    image: /images/ecosystem/logos/vite-devtools.svg
    color: '#8b5cf6'
  - name: Nuxt DevTools
    description: Nuxt DevTools v4, built on Devframe and Vite DevTools
    author: nuxt
    url: https://devtools.nuxt.com
    category: Hosts
    image: /images/ecosystem/logos/nuxt-devtools.svg
    color: '#00dc82'
  - name: '@devframes/plugin-data-inspector'
    description: Queries live server objects with jora
    author: devframes
    url: /add-ons/devframes/data-inspector
    category: Devframes
    icon: i-ph:crosshair-duotone
    official: true
  - name: '@devframes/plugin-inspect'
    description: Browses RPC, shared state and the agent surface of a connection
    author: devframes
    url: /add-ons/devframes/inspect
    category: Devframes
    icon: i-ph:stethoscope-duotone
    official: true
  - name: '@devframes/plugin-og'
    description: Inspects Open Graph metadata and previews social cards
    author: devframes
    url: /add-ons/devframes/og
    category: Devframes
    icon: i-ph:image-square-duotone
    official: true
  - name: '@devframes/plugin-a11y'
    description: Runs axe-core and highlights accessibility issues in the page
    author: devframes
    url: /add-ons/devframes/a11y
    category: Devframes
    icon: i-ph:person-simple-circle-duotone
    official: true
  - name: '@devframes/plugin-git'
    description: Git dashboard for status, log, branches and diffs
    author: devframes
    url: /add-ons/devframes/git
    category: Devframes
    icon: i-ph:git-branch-duotone
    official: true
  - name: '@devframes/plugin-terminals'
    description: Terminal panels for streamed output and interactive PTY shells
    author: devframes
    url: /add-ons/devframes/terminals
    category: Devframes
    icon: i-ph:terminal-window-duotone
    official: true
  - name: '@devframes/plugin-code-server'
    description: Runs VS Code in the browser as an embedded editor panel
    author: devframes
    url: /add-ons/devframes/code-server
    category: Devframes
    icon: i-ph:code-duotone
    official: true
  - name: '@devframes/plugin-assets'
    description: Browses, previews, uploads and manages static assets
    author: devframes
    url: /add-ons/devframes/assets
    category: Devframes
    icon: i-ph:images-duotone
    official: true
  - name: '@devframes/plugin-messages'
    description: Browses, filters and dismisses the hub message feed
    author: devframes
    url: https://github.com/devframes/devframe/tree/main/plugins/messages
    category: Devframes
    icon: i-ph:chat-circle-dots-duotone
    official: true
  - name: '@devframes/service-open'
    description: Opens files in the editor or reveals them in the file explorer
    author: devframes
    url: /add-ons/services/open
    category: Services
    icon: i-ph:file-arrow-up-duotone
    official: true
  - name: '@devframes/service-git'
    description: Read and write git operations over RPC
    author: devframes
    url: /add-ons/services/git
    category: Services
    icon: i-ph:git-branch-duotone
    official: true
  - name: '@devframes/service-shiki'
    description: Server-side Shiki highlighting shared by every devframe
    author: devframes
    url: /add-ons/services/shiki
    category: Services
    icon: i-ph:paint-brush-duotone
    official: true
```
::

::ecosystem-showcase
```yaml [props]
addUrl: https://github.com/devframes/devframe/edit/main/docs/content/4.ecosystem.md
sites:
  - name: Vite DevTools
    description: One dock for any Vite app, with Rolldown bundle analysis, Vitest UI, Oxc tooling and the devframes you mount.
    author: vitejs
    url: https://devtools.vite.dev
    screenshot: /images/ecosystem/vite-devtools.webp
  - name: Nuxt DevTools
    description: Nuxt DevTools v4 builds on Devframe and Vite DevTools and adds Nuxt-specific panels.
    author: nuxt
    url: https://devtools.nuxt.com
    screenshot: /images/ecosystem/nuxt-devtools.webp
  - name: ESLint Config Inspector
    description: Visualizes ESLint flat configs, the rules each file gets and where they come from.
    author: eslint
    url: https://github.com/eslint/config-inspector
    screenshot: /images/ecosystem/eslint-config-inspector.webp
  - name: node-modules-inspector
    description: Interactive dependency graph of node_modules with versions, duplicates and module types.
    author: antfu
    url: https://github.com/antfu/node-modules-inspector
    screenshot: /images/ecosystem/node-modules-inspector.webp
  - name: vite-plugin-inspect
    description: Shows how each Vite plugin transforms a module, step by step.
    author: antfu-collective
    url: https://github.com/antfu-collective/vite-plugin-inspect
    screenshot: /images/ecosystem/vite-plugin-inspect.webp
  - name: pulls.review
    description: Groups changed files, summarizes what matters and reviews pull requests one scope at a time.
    author: antfu
    url: https://github.com/antfu/pulls.review
    screenshot: /images/ecosystem/pulls-review.webp
  - name: Pinia Colada devtools
    description: Inspects Pinia Colada queries and mutations, with refetch, invalidate and simulated errors.
    author: posva
    url: https://github.com/posva/pinia-colada/tree/main/devtools
    screenshot: /images/ecosystem/pinia-colada-devtools.webp
  - name: weapp-vite DevTools
    description: Analyzes WeChat mini-program bundles, tracks build and HMR events, and compares source files with generated output.
    author: weapp-vite
    url: https://github.com/weapp-vite/weapp-vite/tree/main/packages/dashboard
    screenshot: /images/ecosystem/weapp-vite-devtools.webp
```
#title
Built with Devframe

#description
Devtools that run Devframe in production
::

::ecosystem-cta
#title
Add your project

#description
Building on Devframe? Open a pull request that adds a card, or open an issue first if you are not sure it fits.

#ctas
  :::u-button
  ```yaml [props]
  to: https://github.com/devframes/devframe/edit/main/docs/content/4.ecosystem.md
  icon: i-lucide-plus
  target: _blank
  color: neutral
  ```
  Add your project
  :::

  :::u-button
  ```yaml [props]
  to: https://github.com/devframes/devframe/issues/new
  target: _blank
  color: neutral
  variant: outline
  ```
  Open an issue
  :::
::

---
title: Add-ons
navigation:
  icon: i-lucide-blocks
description: 'Ready-to-run packages built on Devframe: built-in devframes you can run, compose, or learn from, and wire services that share one node-side capability across every devframe on a host.'
---

Ready-to-run packages built on Devframe, in two families:

- **[Devframes](/add-ons/devframes)** are complete built-in devtools (`@devframes/plugin-*`). Run one standalone, compose several into your own DevTools, or read one as a reference for building your own.
- **[Services](/add-ons/services)** are wire services (`@devframes/service-*`): one node-side capability installed once per host and consumed by every devframe and RPC client, without re-bundling it.

## Devframes

Complete tools, each picking its own UI framework yet sharing one node-side API: [RPC](/guide/rpc), [shared state](/guide/shared-state), and `connectDevframe`.

| Devframe                                            | UI framework    | What it does                                             |
| --------------------------------------------------- | --------------- | -------------------------------------------------------- |
| [Data Inspector](/add-ons/devframes/data-inspector) | Vue             | Query live server-side objects with jora.                |
| [Devframe Inspector](/add-ons/devframes/inspect)    | Vue             | Browse RPC, shared state, and agent exposure.            |
| [Open Graph Viewer](/add-ons/devframes/og)          | Vue             | Inspect Open Graph / Twitter metadata and card previews. |
| [Accessibility Inspector](/add-ons/devframes/a11y)  | Solid           | Run axe-core; list WCAG violations.                      |
| [Git](/add-ons/devframes/git)                       | React (Next.js) | Repository dashboard: status, graph, branches, diffs.    |
| [Terminals](/add-ons/devframes/terminals)           | Svelte          | Stream output and run interactive PTY shells.            |
| [Code Server](/add-ons/devframes/code-server)       | Vue             | Run VS Code in the browser.                              |
| [Assets](/add-ons/devframes/assets)                 | Vue             | Browse, preview, upload, rename, and delete files.       |

## Services

Shared node-side capabilities other devframes install and consume; see [Cross-Devframe Services](/guide/services) for the mechanism, and the [Node-Side API reference](/references/node-api#devframeserviceshost) for the host API.

| Service                                                       | Scope                     | What it does                                                                       |
| ------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------- |
| [Open](/add-ons/services/open) (`@devframes/service-open`)    | `devframes:service:open`  | Open files in an editor or the OS explorer, with workspace-root containment.       |
| [Git](/add-ons/services/git) (`@devframes/service-git`)       | `devframes:service:git`   | Typed read/write git operations over RPC on one repo.                              |
| [Shiki](/add-ons/services/shiki) (`@devframes/service-shiki`) | `devframes:service:shiki` | Node-side [Shiki](https://shiki.style) syntax highlighting, cached and dual-theme. |

## Running a built-in devframe

Most built-in devframes publish a `bin`:

```sh
pnpx @devframes/plugin-inspect      # the Devframe Inspector, standalone
pnpx @devframes/plugin-og           # inspect Open Graph metadata and social cards
pnpx @devframes/plugin-git          # the Git dashboard against the current repo
pnpx @devframes/plugin-assets       # manage the files under <cwd>/public
```

Each also exports a `create…Devframe` factory; see each page for options.

---
title: Devframes
navigation:
  icon: i-lucide-palette
description: Ready-to-run built-in example devframes. Compose your own DevTools solution from them, run one standalone, or read one as a reference for building your own.
---

Ready-to-run built-in example devframes (`@devframes/plugin-*`). Compose your own DevTools solution from them, run one standalone, or read one as a reference for building your own.

| Devframe                                            | UI framework    | What it does                                             |
| --------------------------------------------------- | --------------- | -------------------------------------------------------- |
| [Data Inspector](/add-ons/devframes/data-inspector) | Vue             | Query live server-side objects with jora.                |
| [Devframe Inspector](/add-ons/devframes/inspect)    | Vue             | Browse RPC, shared state, and agent exposure.            |
| [Open Graph Viewer](/add-ons/devframes/og)          | Vue             | Inspect Open Graph / Twitter metadata and card previews. |
| [Accessibility Inspector](/add-ons/devframes/a11y)  | Solid           | Run axe-core; list WCAG violations.                      |
| [Git](/add-ons/devframes/git)                       | React (Next.js) | Repository dashboard: status, graph, branches, diffs.    |
| [Terminals](/add-ons/devframes/terminals)           | Svelte          | Stream output and run interactive PTY shells.            |
| [Code Server](/add-ons/devframes/code-server)       | Vue             | Run VS Code in the browser.                              |
| [Assets](/add-ons/devframes/assets)                 | Vue             | Browse, preview, upload, rename, and delete files.       |

## One RPC client, any framework

Each devframe picks its own UI framework yet shares one node-side API: [RPC](/guide/rpc), [shared state](/guide/shared-state), and `connectDevframe`.

## Running a built-in devframe

Most built-in devframes publish a `bin`:

```sh
pnpx @devframes/plugin-inspect      # the Devframe Inspector, standalone
pnpx @devframes/plugin-og           # inspect Open Graph metadata and social cards
pnpx @devframes/plugin-git          # the Git dashboard against the current repo
pnpx @devframes/plugin-assets       # manage the files under <cwd>/public
```

Each also exports a `create…Devframe` factory; see each page for options.

---
title: Data Inspector
navigation:
  icon: i-ph:crosshair-duotone
description: 'A Vue query workbench for live server-side objects: register data sources, then compose jora queries in the owning process.'
---

A **Vue** query workbench for live server-side objects: register **data sources**, then compose [jora](https://discoveryjs.github.io/jora/) queries in the owning process.

Package: `@devframes/plugin-data-inspector` · **Vue + Vite**

![Data Inspector screenshot](/screenshots/plugin-data-inspector-1.png)

*Query workbench with results and data shape panel*

![Data Inspector screenshot](/screenshots/plugin-data-inspector-2.png)

*Query data with advanced Jora syntax*

## What it does

- **Query workbench**: a CodeMirror jora editor with server-computed autocomplete; queries auto-run as you type, [state in the URL hash](#deep-linking).
- **Auto rerun**: optional poller (`auto rerun every N seconds`).
- **Result viewer**: normalizes to strict JSON (circulars → `$ref`; Maps, Sets, class instances, functions, Dates get type badges) plus per-query stats.
- **Expansion, shape & filters**: deep nodes fetch lazily via `load deeper`; a shape panel shows a one-level skeleton; filters drop functions and `_`/`$` properties.
- **Saved queries**: recipes (`query` + title/description + filters) in the **workspace scope** (committable) and the **project scope** (per-checkout).

A built-in **example source** registers by default; opt out with `exampleSource: false` (`--no-example`; `DEVFRAME_DATA_INSPECTOR_EXAMPLE=0` when injected).

## Providing data sources

The registry is **process-global**; register anywhere, before or after mount.

```ts
import { registerDataSource } from '@devframes/plugin-data-inspector/registry'

registerDataSource({
  id: 'my-plugin:store', // namespace with your devframe id
  title: 'My plugin store',
  description: 'The live state store',
  icon: 'i-ph:database-duotone',
  data: () => store,
  queries: [
    { title: 'Active sessions', query: 'sessions.mapEntries().value.[active]' },
    { title: 'Config (data only)', query: 'config', excludeFunctions: true },
  ],
})
```

`data` is a plain value or sync/async factory; `static: true` resolves it once; `queries` show read-only beside saved ones; `registerDataSource` returns an unregister callback. Zero-dependency devframes `register` through the typed [context service](/guide/devframe-definition#cross-devframe-services) `ctx.services.whenAvailable('devframes:plugin:data-inspector:sources', …)`.

> [!WARNING]
> Queries are eval-grade: jora invokes any function reachable as an own property and fires own getters. Register live objects accordingly, and keep endpoints on loopback.

## Deep linking

Workbench state lives in the URL hash (`#source=<id>&query=<jora>`, filters); the handshake token rides the query string (`?devframe_auth_token=`), scrubbed on read.

In a hub, another dock jumps to a source via [dock activation](/guide/deep-linking#focusing-a-dock-inside-a-hub): `rpc.call('hub:docks:activate', { dockId: 'devframes:plugin:data-inspector', params: { sourceId } })` (waits for registration).

## Standalone

```sh
pnpx @devframes/plugin-data-inspector                      # the example source
pnpx @devframes/plugin-data-inspector stats.json log.jsonl # one static source per data file
pnpx @devframes/plugin-data-inspector build stats.json     # self-contained static export
pnpx @devframes/plugin-data-inspector attach               # attach to a process running the inject endpoint
```

`.json` parses whole; `.jsonl` / `.ndjson` as a record array. `build` embeds the dataset in a static site.

## Mount into a Vite host

For [Vite DevTools](https://devtools.vite.dev):

```ts
// vite.config.ts
import createDataInspectorDevframe from '@devframes/plugin-data-inspector'
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    createPluginFromDevframe(createDataInspectorDevframe()),
  ],
})
```

Register sources with `registerDataSource`, or mount via `devframeVite(createDataInspectorDevframe())` from `@devframes/vite/single`.

## Programmatic

```ts
import { createDataInspectorDevframe } from '@devframes/plugin-data-inspector'

export default createDataInspectorDevframe({
  exampleSource: false,
})
```

## Attach to another Node process

The target starts the inject endpoint:

```ts
import { exposeDataInspector } from '@devframes/plugin-data-inspector/inject'

await exposeDataInspector({
  sources: [{ id: 'app:store', title: 'App store', data: () => store }],
})
```

`sources` pre-registers entries; call it empty to expose whatever's registered. Or code-free:

```sh
DEVFRAME_DATA_INSPECTOR=1 node --import @devframes/plugin-data-inspector/inject server.js
```

This auto-registers a **`globalThis`** source:

```ts
// somewhere in the running process
globalThis.store = store
globalThis.cache = cache
```

It reads `globalThis` at query time, so later assignments appear next run (opt out: `DEVFRAME_DATA_INSPECTOR_GLOBAL=0`).

The inject endpoint binds `127.0.0.1`, requires the trust handshake with a per-run token, and advertises itself in `node_modules/.data-inspector/discovery.json`, which `attach` reads (or pass `ws://…` + `--token`).

## RPC

All `devframes:plugin:data-inspector:*`:

| Function                                     | Type               | Returns                                            |
| -------------------------------------------- | ------------------ | -------------------------------------------------- |
| `sources`                                    | `query`            | Every registered source (meta, suggested queries). |
| `query`                                      | `query`            | Runs a jora query; normalized result with stats.   |
| `queryPath`                                  | `query`            | Depth-limited subtree slice (lazy expansion).      |
| `skeleton`                                   | `query`            | A source's type skeleton, honoring filters.        |
| `suggest`                                    | `query`            | Autocomplete candidates at the cursor.             |
| `saved:list` / `saved:save` / `saved:delete` | `query` / `action` | Saved-query recipes (`workspace`, `project`).      |

## Source

[`plugins/data-inspector`](https://github.com/devframes/devframe/tree/main/plugins/data-inspector)

---
title: Devframe Inspector
navigation:
  icon: i-ph:stethoscope-duotone
description: 'A self-inspector for any devframe connection, including the host framework''s: a Vue SPA.'
---

A self-inspector for any devframe connection, including the host framework's: a **Vue** SPA.

Package: `@devframes/plugin-inspect` · framework: **Vue + Vite**

![Inspector](/screenshots/plugin-inspect-1.png)

*RPC functions list*

![Inspector](/screenshots/plugin-inspect-2.png)

*Agent tools*

![Inspector](/screenshots/plugin-inspect-3.png)

*History panels*

## What it does

- **Functions**: type, flags, JSON Schema, agent exposure; read-only `query` / `static` invokable inline.
- **Client**: the browser side of the connection: client RPC functions (invoked locally in the page) and the page's WebMCP tools, live from the model context's `getTools()` when the browser supports discovery, otherwise projected from `agent`-flagged client functions.
- **State**: shared-state keys in a live JSON tree that flashes changes.
- **Agent**: tools and resources for agents.
- **History**: a timeline of RPC calls and shared-state updates.

## Standalone

```sh
pnpx @devframes/plugin-inspect
```

## Mount into a Vite host

For a [Vite DevTools](https://devtools.vite.dev) app:

```ts
// vite.config.ts
import createInspectDevframe from '@devframes/plugin-inspect'
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    createPluginFromDevframe(createInspectDevframe()),
  ],
})
```

Or mount directly with `devframeVite` from `@devframes/vite/single`:

```ts
// vite.config.ts
import createInspectDevframe from '@devframes/plugin-inspect'
import { devframeVite } from '@devframes/vite/single'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    devframeVite(createInspectDevframe()),
  ],
})
```

## Programmatic

`createInspectDevframe(options)` returns a definition for any adapter:

```ts
import { createInspectDevframe } from '@devframes/plugin-inspect'
import { createCac } from 'devframe/adapters/cac'

await createCac(createInspectDevframe({ port: 9100 })).parse()
```

## RPC

All functions are namespaced `devframes:plugin:inspect:*`:

| Function          | Type               | Returns                                                           |
| ----------------- | ------------------ | ----------------------------------------------------------------- |
| `list-functions`  | `query` (snapshot) | RPC functions with metadata.                                      |
| `invoke`          | `action`           | Invokes a read-only `query` / `static`; refuses `action`/`event`. |
| `list-state-keys` | `query` (snapshot) | Shared-state keys.                                                |
| `describe-agent`  | `query` (snapshot) | Agent manifest: tools and resources.                              |

## Source

[`plugins/inspect`](https://github.com/devframes/devframe/tree/main/plugins/inspect)

---
title: Open Graph Viewer
navigation:
  icon: i-ph:image-square-duotone
description: Inspect a page's Open Graph / Twitter metadata and social cards, built as a Vue + Vite SPA.
---

Inspect a page's Open Graph / Twitter metadata and social cards, built as a **Vue + Vite** SPA.

Package: `@devframes/plugin-og`

## What it does

Enter any HTTP/HTTPS URL. It resolves relative image/icon URLs, renders social cards for Twitter, Facebook, LinkedIn, and Telegram, and flags missing metadata with a Nuxt `useSeoMeta()` snippet.

The standalone server requires devframe's trust handshake; set `auth: false` only for isolated local use.

## Standalone

```sh
pnpx @devframes/plugin-og
```

## Mount into a Vite host

With [Vite DevTools](https://devtools.vite.dev):

```ts
// vite.config.ts
import createOgDevframe from '@devframes/plugin-og'
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    createPluginFromDevframe(createOgDevframe()),
  ],
})
```

Or use `devframeVite(createOgDevframe())` from `@devframes/vite/single`.

## Programmatic

`createOgDevframe(options)` returns a definition for any adapter:

```ts
import { createOgDevframe } from '@devframes/plugin-og'

export default createOgDevframe({
  defaultUrl: 'http://localhost:3000/about',
})
```

`defaultUrl` sets the initial target and bakes it into the static build.

## RPC

Namespaced `devframes:plugin:og:*`:

| Function           | Type    | Returns                                                                      |
| ------------------ | ------- | ---------------------------------------------------------------------------- |
| `resolve-metadata` | `query` | Fetches a page; returns title, language, Open Graph, Twitter, link metadata. |

## Source

[`plugins/og`](https://github.com/devframes/devframe/tree/main/plugins/og)

---
title: Accessibility Inspector
navigation:
  icon: i-ph:person-simple-circle-duotone
description: Runs axe-core against the user app, lists WCAG A/AA violations in a Solid panel, and highlights the element on hover.
---

Runs [axe-core](https://github.com/dequelabs/axe-core) against the user app, lists WCAG A/AA violations in a **Solid** panel, and highlights the element on hover.

Package: `@devframes/plugin-a11y` · framework: **Solid + Vite**

![Accessibility Inspector screenshot](/screenshots/plugin-a11y-1.png)

*Hover to highlight the offending element*

![Accessibility Inspector screenshot](/screenshots/plugin-a11y-copy-prompts.png)

*Generate prompts to fix issues*

## What it does

Three pieces, two browser-side:

| Piece           | Runs in             | Role                                                           |
| --------------- | ------------------- | -------------------------------------------------------------- |
| **Page script** | the user app's page | runs axe-core, owns the report state, draws the highlight ring |
| **Panel**       | the devtools iframe | Solid SPA: lists violations, highlights on hover               |
| **Node side**   | the Node process    | the `get-config` RPC (impact taxonomy), baked in static builds |

The page script and the panel talk over the [in-page channel](/guide/in-page-channel), so the loop works live or static. The page script is the author-provided bridge (the panel has no reach into the user app's DOM): one module script scans, reports, and highlights.

## In a hub

The definition declares the page script as its dock [client script](/guide/client-context), so mounting by package name just works:

```ts
initHub({ devframes: ['@devframes/plugin-a11y'] })
```

The hub serves the bundle same-origin and a client runtime imports it into the host page. Each scan also mirrors into the hub's messages feed: a summary plus one per rule.

A host can also mount the module itself, for example a Vite host via `/@fs/`:

```ts
import createA11yDevframe, { a11yClientScriptBundlePath } from '@devframes/plugin-a11y'

await ctx.install(createA11yDevframe(), {
  dock: { clientScript: { importFrom: `/@fs/${a11yClientScriptBundlePath}` } },
})
```

Outside a hub, a `<script type="module">` boots the page script (no feed mirror).

## Standalone

```sh
pnpx @devframes/plugin-a11y
```

Runs the panel alone at `/__devframes_plugin_a11y/`; load the page script into a real page.

## Mount into a Vite host

In [Vite DevTools](https://devtools.vite.dev):

```ts
// vite.config.ts
import createA11yDevframe from '@devframes/plugin-a11y'
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    createPluginFromDevframe(createA11yDevframe()),
  ],
})
```

Or swap in `devframeVite(createA11yDevframe())` from `@devframes/vite/single`.

## Programmatic

`createA11yDevframe(options)` returns a definition for any adapter:

```ts
import { createA11yDevframe } from '@devframes/plugin-a11y'

export default createA11yDevframe({
  port: 9899,
})
```

## RPC

Namespaced `devframes:plugin:a11y:*`:

| Function     | Type     | Returns                                                  |
| ------------ | -------- | -------------------------------------------------------- |
| `get-config` | `static` | The impact taxonomy and the in-page channel coordinates. |

## Run the demo

The demo serves a broken page and panel from one origin:

```sh
pnpm -C plugins/a11y build       # build the panel + the page-script bundle
pnpm -C plugins/a11y demo        # dev: live WebSocket RPC
pnpm -C plugins/a11y cli:build   # bake the static deploy (dist/static)
pnpm -C plugins/a11y demo:build  # static: baked RPC dump, no server
```

Hover a row to highlight the matching element.

## Source

[`plugins/a11y`](https://github.com/devframes/devframe/tree/main/plugins/a11y)

---
title: Git
navigation:
  icon: i-ph:git-branch-duotone
description: 'A repository dashboard: a Next.js + shadcn/ui SPA that shells out to git. The same bundle runs live or static.'
---

A repository dashboard: a **Next.js + shadcn/ui** SPA that shells out to `git`. The same bundle runs live or static.

Package: `@devframes/plugin-git`

![Git devframe](/screenshots/plugin-git-1.png)

*Status and graph*

## What it does

Read views are read-only; write mode adds staging, unstaging, and commits (gated by write permission).

## Standalone

```sh
pnpx @devframes/plugin-git         # dev server (live RPC over WebSocket)
pnpx @devframes/plugin-git --write # also enable staging / committing from the UI
pnpx @devframes/plugin-git build   # static deploy → dist-static/
```

## Programmatic

`createGitDevframe(options)` returns a definition for any adapter.

```ts
import { createGitDevframe } from '@devframes/plugin-git'
import { createCac } from 'devframe/adapters/cac'

await createCac(createGitDevframe({ repoRoot: process.cwd() })).parse()
```

| Option     | Default            | Description                           |
| ---------- | ------------------ | ------------------------------------- |
| `repoRoot` | the devframe `cwd` | Repo to inspect.                      |
| `port`     | `9710`             | Dev-server port.                      |
| `write`    | `false`            | Enable staging / unstaging / commits. |

## RPC

Namespaced `devframes:plugin:git:*`. Reads are `query` (`snapshot: true`): `status`, `log` (+ parent hashes), `branches` (ahead / behind), and `diff` (unified patch), live in dev, baked static, `isRepo: false` outside a repo. Write `stage` / `unstage` / `commit` are write-mode `action`s.

For a repo capability shared across devframes rather than this dashboard's own RPC, see the [`@devframes/service-git`](/add-ons/services/git) wire service.

## Source

[`plugins/git`](https://github.com/devframes/devframe/tree/main/plugins/git)

---
title: Terminals
navigation:
  icon: i-ph:terminal-window-duotone
description: 'A terminal panel: a Svelte SPA on xterm.js.'
---

A terminal panel: a **Svelte** SPA on [xterm.js](https://xtermjs.org/).

Package: `@devframes/plugin-terminals`

![Terminals screenshot](/screenshots/plugin-terminals-1.png)

*Interactive and read-only sessions in the browser*

## What it does

- **Read-only output**: via devframe's [streaming channels](/guide/streaming).
- **Interactive shells**: PTY-backed terminal sessions you can type into, including full-screen TUI programs.
- **Presets**: named commands launchable in one click.

Interactive shells use [`zigpty`](https://github.com/pithings/zigpty)'s prebuilt native bindings (Linux/macOS/Windows, x64/arm64), falling back to pipe-based emulation where they can't load.

## Standalone

```sh
pnpx @devframes/plugin-terminals
```

## Mount into a Vite host

```ts
// vite.config.ts
import { terminalsVite } from '@devframes/plugin-terminals/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    terminalsVite(),
  ],
})
```

## Programmatic

`createTerminalsDevframe(options)` returns a definition; declare presets to seed the launcher:

```ts
import { createTerminalsDevframe } from '@devframes/plugin-terminals'

export default createTerminalsDevframe({
  presets: [
    { id: 'dev', title: 'pnpm dev', command: 'pnpm', args: ['dev'] },
  ],
})
```

## Hub aggregation

Mounted into a hub, the devframe spawns on its own channel (`devframes:plugin:terminals:output`) and mirrors every session into `ctx.terminals` (the hub's registry, on `devframe:terminals`); foreign hub sessions render read-only.

`ctx.terminals` is the source of truth; the devframe, the sole PTY provider, duck-types a minimal `register` / `update` / `events` shape to run without `@devframes/hub`.

Both spawned terminal session types carry a `getResult()` accessor. A `startChildProcess()` result is an `await`able `{ stdout, stderr, exitCode }` with live process getters and `kill()`. A `startPtySession()` result captures its merged terminal stream as an `await`able `{ output, exitCode, signal }` with live `pid`, `exitCode`, and `killed` getters. `killed` is the portable termination indicator; `signal` is present when the PTY backend reports one.

## Focusing a session

Via the hub's [cross-iframe dock activation](/guide/hub#cross-iframe-dock-activation), an activation with a `sessionId` selects that session:

```ts
// e.g. right after ctx.terminals.startChildProcess(..., { id: sessionId, ... })
await rpc.call('hub:docks:activate', {
  dockId: 'devframes_plugin_terminals',
  params: { sessionId },
})
```

Focus is one-shot; an unknown id waits for the session.

## Deep linking

Standalone, the panel keeps the selected session in the URL hash (`#id=<sessionId>`), so a copied link reopens it ([deep-linking guide](/guide/deep-linking)).

## RPC

Namespaced `devframes:plugin:terminals:*`:

| Function       | Type               | Purpose                                 |
| -------------- | ------------------ | --------------------------------------- |
| `list`         | `query` (snapshot) | Sessions (status, mode, command).       |
| `presets`      | `query` (snapshot) | Declared launcher presets.              |
| `spawn`        | `action`           | Start from a preset id or command+mode. |
| `write`        | `action`           | Input to an interactive session.        |
| `resize`       | `action`           | Resize the PTY (columns × rows).        |
| `restart`      | `action`           | Restart, keeping scrollback.            |
| `rename`       | `action`           | Rename a session.                       |
| `terminate`    | `action`           | End the process; keep the session.      |
| `remove`       | `action`           | Kill and discard.                       |
| `clear-exited` | `action`           | Discard stopped sessions.               |

Status and mutations mirror into shared state, keeping panels in sync.

## Source

[`plugins/terminals`](https://github.com/devframes/devframe/tree/main/plugins/terminals)

---
title: Code Server
navigation:
  icon: i-ph:code-duotone
description: 'Run VS Code in the browser as a devframe panel: detect a local editor, launch on demand, embed in an auto-authenticated iframe.'
---

Run VS Code in the browser as a devframe panel: detect a local editor, launch on demand, embed in an auto-authenticated iframe.

Package: `@devframes/plugin-code-server` · framework: **Vue**

![Code Server](/screenshots/plugin-code-server-1.png)

*Launcher before start*

![Code Server](/screenshots/plugin-code-server-2.png)

*The embedded editor in the browser*

## What it does

- **Detection**: probes with `--version`; if absent, shows install info.
- **Launch**: a managed child process on a free port, readiness-probed.
- **Auto-auth**: fresh auth per launch; the editor opens signed in.

## Backends

`mode: 'local'` (default) auto-detects `code-server`, else `code serve-web`.

| `backend`             | Binary                                                                      | Auth handoff               |
| --------------------- | --------------------------------------------------------------------------- | -------------------------- |
| `'code-server'`       | [`code-server`](https://github.com/coder/code-server)                       | password + session cookie  |
| `'ms-code-serve-web'` | [`code serve-web`](https://code.visualstudio.com/docs/remote/vscode-server) | connection token (`?tkn=`) |

## Tunnel mode

`mode: 'tunnel'` runs `code tunnel` and embeds `vscode.dev`; first launch prompts a device login (`code` CLI).

## Standalone

```sh
pnpx @devframes/plugin-code-server
```

## Mount into a Vite host

```ts
// vite.config.ts
import { codeServerVite } from '@devframes/plugin-code-server/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    codeServerVite(),
  ],
})
```

## Programmatic

```ts
import { createCodeServerDevframe } from '@devframes/plugin-code-server'

export default createCodeServerDevframe({
  // backend: 'code-server',    // default: auto-detect
  // mode: 'local',             // 'local' | 'tunnel'
  // serverPort: 8080,          // default: free port near 8080
  // startOnBoot: true,         // launch during setup
  // reuseExistingServer: true, // adopt a server on the port
  // tunnel: { name: 'my-box' },
})
```

## RPC

Namespaced `devframes:plugin:code-server:*`:

| Function | Type     | Purpose                                               |
| -------- | -------- | ----------------------------------------------------- |
| `detect` | `query`  | Re-probe; returns installed/version/bin/backend/mode. |
| `status` | `query`  | Current status; connect descriptor if running.        |
| `start`  | `action` | Launch and await readiness.                           |
| `stop`   | `action` | Stop the process.                                     |

Status (minus connect descriptor) mirrors into `…:state`.

## Source

[`plugins/code-server`](https://github.com/devframes/devframe/tree/main/plugins/code-server)

---
title: Assets
navigation:
  icon: i-ph:image-square-duotone
description: Browse, preview, and manage files in a directory, porting Nuxt DevTools' Assets tab.
---

Browse, preview, and manage files in a directory, porting Nuxt DevTools' Assets tab.

Package: `@devframes/plugin-assets` · framework: **Vue + @antfu/design**

![Assets devframe screenshot](/screenshots/plugin-assets-1.png)

*File browser and details panel*

## What it does

Search by name, filter by type, view as a thumbnail grid or tree, and open a details panel: live preview (image, video, audio, font, text), metadata, and copy-ready snippets (`<img>`, `background-image`, `@font-face`). Upload via toolbar or drag-and-drop, multi-select to delete; a watcher keeps listings synced.

The standalone server requires devframe's trust handshake; write is on by default (`{ write: false }` / `--read-only` for browse-only).

## Standalone

```sh
pnpx @devframes/plugin-assets             # manages <cwd>/public
pnpx @devframes/plugin-assets --read-only # disable upload / rename / delete / mkdir
```

## Mount into a Vite host

For a [Vite DevTools](https://devtools.vite.dev) app:

```ts
// vite.config.ts
import createAssetsDevframe from '@devframes/plugin-assets'
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    createPluginFromDevframe(createAssetsDevframe()),
  ],
})
```

Or use `devframeVite` from `@devframes/vite/single`.

## Programmatic

`createAssetsDevframe(options)` returns a definition for any adapter:

```ts
import { createAssetsDevframe } from '@devframes/plugin-assets'

export default createAssetsDevframe({
  dir: 'static',
  baseURL: '/',
  write: true,
  uploadExtensions: ['png', 'jpg', 'svg', 'webp'], // or '*' for any
})
```

| Option             | Default                   | Description                                                         |
| ------------------ | ------------------------- | ------------------------------------------------------------------- |
| `dir`              | `<cwd>/public`            | Directory to manage.                                                |
| `baseURL`          | `/`                       | URL base the user app serves `dir` at (e.g. Nuxt `app.baseURL`).    |
| `write`            | `true`                    | Enable upload, rename, delete, mkdir.                               |
| `uploadExtensions` | Nuxt DevTools' allow-list | Extensions `upload` accepts, or `'*'`.                              |
| `serveStatic`      | `false`                   | Serve the directory's bytes; on for the standalone CLI.             |
| `build`            | `false`                   | Registers the `build` subcommand ([Static export](#static-export)). |

## How previews are served

Previews load by **public URL** (`baseURL` + path).

## RPC

Namespaced `devframes:plugin:assets:*`:

| Function                              | Type                      | Notes                                                                                                                     |
| ------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `list`                                | `query`, `snapshot: true` | Every file: type, size, mtime.                                                                                            |
| `capabilities`                        | `query`, `snapshot: true` | Write-enabled flag; the allow-list.                                                                                       |
| `read-image-meta`                     | `query`                   | Width/height/orientation.                                                                                                 |
| `read-text`                           | `query`                   | Truncated preview text; server-highlighted via [`@devframes/service-shiki`](/add-ons/services/shiki), else plain `<pre>`. |
| `upload`                              | `action`                  | Streaming upload slot; the SPA pipes bytes.                                                                               |
| `rename`                              | `action`                  | Renames one (keeps extension).                                                                                            |
| `delete`                              | `action`                  | Deletes one or more.                                                                                                      |
| `mkdir`                               | `action`                  | Creates a folder + parents.                                                                                               |
| `open-in-editor` / `reveal-in-folder` | `action`                  | Open/reveal via [`@devframes/service-open`](/add-ons/services/open); always registered.                                   |

`upload` / `rename` / `delete` / `mkdir` register only with `write`.

## Static export

The `build` subcommand is disabled by default (`capabilities: { build: false }`). Pass `{ build: true }` (or `{ force: true }` to `createBuild()`) to bake the listing.

## Source

[`plugins/assets`](https://github.com/devframes/devframe/tree/main/plugins/assets)

---
title: Services
navigation:
  icon: i-lucide-share-2
description: 'Built-in wire services (@devframes/service-*): one node-side capability installed once per host and consumed by every devframe and RPC client, without re-implementing or re-bundling it.'
---

Built-in [wire services](/guide/services#wire-services) (`@devframes/service-*`) each package one node-side capability, installed once per host and consumed by every devframe and RPC client, without re-implementing or re-bundling it. See [Cross-Devframe Services](/guide/services) for the mechanism and the [Node-Side API reference](/references/node-api#devframeserviceshost) for the host API.

| Service                          | Scope                     | RPC functions                                                                                 | What it does                                                                                     |
| -------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [Open](/add-ons/services/open)   | `devframes:service:open`  | `open-in-editor`, `open-in-finder`                                                            | Open files in an editor or reveal them in the OS explorer, refusing paths outside the workspace. |
| [Git](/add-ons/services/git)     | `devframes:service:git`   | `status`, `log`, `show`, `readFile`, `diff`, `branches`, `tags`, `stage`, `unstage`, `commit` | Typed read/write git operations over RPC on one repo.                                            |
| [Shiki](/add-ons/services/shiki) | `devframes:service:shiki` | `highlight`, `code-to-hast`, `code-to-tokens`                                                 | Node-side [Shiki](https://shiki.style) syntax highlighting, LRU-cached and dual-theme.           |

## Installing a service

Services are **declarative**: a devframe lists what it consumes on its definition; a hub lists shared ones on `initHub`:

```ts
defineDevframe({
  importMetaUrl: import.meta.url, // resolution base for the declared packages
  services: [
    { package: '@devframes/service-open' },
    { package: '@devframes/service-shiki', version: '^1', options: { langs: ['vue'] } },
  ],
})
```

The host constructs each declared service **once**, before any `setup(ctx)` runs, so setup consumes it synchronously via `ctx.services.get(pkg)`. On the RPC client, feature-detect with `rpc.services.has(pkg)`.

---
title: Open
navigation:
  icon: i-ph:file-arrow-up-duotone
description: 'The @devframes/service-open wire service: open files in an editor or reveal them in the OS explorer over RPC, with workspace-root path containment and editor gating.'
---

Open files in an editor or reveal them in the OS explorer, shared over RPC by every devframe on the host. Replaces per-devframe registration of the (deprecated) `devframe/recipes/common-rpc-functions` recipe with one install, feature-detectable from RPC clients, adding workspace-root path containment on top of editor gating.

Package: `@devframes/service-open` · Scope: `devframes:service:open`

## Installing

```ts
defineDevframe({
  importMetaUrl: import.meta.url,
  services: [
    { package: '@devframes/service-open', options: { editor: 'code' } },
  ],
})
```

A hub installs a shared instance with `initHub({ services: [createOpenService(options)] })`.

## Options

`OpenServiceOptions`: later installer wins on `editor`; `roots` union-merged.

| Option   | Type          | Description                                                                                                                             |
| -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `editor` | `KnownEditor` | Preferred editor command (one of `KNOWN_EDITORS`). Auto-detected via `LAUNCH_EDITOR` and common defaults when omitted.                  |
| `roots`  | `string[]`    | Extra directories files may be opened from, on top of the context's `workspaceRoot` (e.g. a managed storage dir outside the workspace). |

## RPC functions

Registered under `devframes:service:open:*`, both `action`s. Paths may be absolute or relative to the `workspaceRoot`; the service refuses paths outside the workspace root plus the configured `roots` (`DS_OPEN_0002`), and gates `editor` to the `KNOWN_EDITORS` picklist so the surface can't spawn an arbitrary command.

| Function         | Args                                | Purpose                                                         |
| ---------------- | ----------------------------------- | --------------------------------------------------------------- |
| `open-in-editor` | `{ path, line?, column?, editor? }` | Open a file, optionally at a line/column, in the user's editor. |
| `open-in-finder` | `{ path }`                          | Reveal a path in the OS file explorer.                          |

## Node API

`ctx.services.get('@devframes/service-open')` returns the in-process `OpenServiceApi` (no RPC hop server-side): `openInEditor(input)` and `openInFinder({ path })`.

## On the RPC client

```ts
const rpc = await connectDevframe()

if (rpc.services.has('@devframes/service-open')) {
  const open = rpc.services.get('@devframes/service-open')!
  await open.rpc.call('open-in-editor', { path: 'src/main.ts', line: 42, column: 7 })
  await open.rpc.call('open-in-finder', { path: 'public' })
}
```

## Source

[`services/open`](https://github.com/devframes/devframe/tree/main/services/open)

---
title: Git
navigation:
  icon: i-ph:git-branch-duotone
description: 'The @devframes/service-git wire service: typed read/write git operations over RPC on one repository, shared by every devframe on the host.'
---

Typed read/write git operations shared over RPC by every devframe on the host, generalizing the utilities that used to live inside the [Git devframe](/add-ons/devframes/git). The exec wrapper and output parsers stay internal; consumers get the typed `GitServiceApi` in-process (`ctx.services.get`) and the same ops over `devframes:service:git:*` RPC.

Package: `@devframes/service-git` · Scope: `devframes:service:git`

## Installing

```ts
defineDevframe({
  importMetaUrl: import.meta.url,
  services: [
    { package: '@devframes/service-git', options: { cwd: process.cwd() } },
  ],
})
```

A hub installs a shared instance with `initHub({ services: [createGitService(options)] })`.

## Options

`GitServiceOptions`: `cwd` merges as a scalar (later installer wins).

| Option | Type     | Description                                                                                                                                       |
| ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cwd`  | `string` | Repository directory to operate on. Defaults to the context's `cwd`; the repo root is discovered once (`rev-parse --show-toplevel`) and memoized. |

## RPC functions

Registered under `devframes:service:git:*`. Reads are `query`; writes are `action`. Write ops are **always exposed**; authorization is the host's connection-trust boundary. The service defines no `dump`/`snapshot`; a devframe bakes what it needs via `snapshotRpc`.

| Function   | Type     | Args                              | Returns                                                                     |
| ---------- | -------- | --------------------------------- | --------------------------------------------------------------------------- |
| `status`   | `query`  | none                              | Working-tree status: branch, ahead/behind, staged/unstaged/untracked files. |
| `log`      | `query`  | `{ limit?, skip?, ref?, paths? }` | Commit history, newest first (paginated).                                   |
| `show`     | `query`  | `{ hash, patch? }`                | Full detail of one commit: metadata, files, unified patch.                  |
| `readFile` | `query`  | `{ path, ref? }`                  | Contents of a file at a commit-ish (default HEAD).                          |
| `diff`     | `query`  | `{ path?, staged? }`              | Unified diff of uncommitted changes.                                        |
| `branches` | `query`  | none                              | Local branches with tracking state and the current branch.                  |
| `tags`     | `query`  | none                              | Tags (newest first) with target SHA, date, and subject.                     |
| `stage`    | `action` | `{ … }`                           | Stage paths; returns the new status.                                        |
| `unstage`  | `action` | `{ … }`                           | Unstage paths; returns the new status.                                      |
| `commit`   | `action` | `{ … }`                           | Create a commit; returns the result.                                        |

The read `query` functions carry agent metadata, so they surface as tools to a [coding agent](/guide/agent-native).

## Node API

`ctx.services.get('@devframes/service-git')` returns the in-process `GitServiceApi`: the same operations without an RPC hop.

## On the RPC client

```ts
const rpc = await connectDevframe()

if (rpc.services.has('@devframes/service-git')) {
  const git = rpc.services.get('@devframes/service-git')!
  const status = await git.rpc.call('status')
  console.log(status)
}
```

## Source

[`services/git`](https://github.com/devframes/devframe/tree/main/services/git)

---
title: Shiki
navigation:
  icon: i-ph:paint-brush-duotone
description: 'The @devframes/service-shiki wire service: node-side Shiki syntax highlighting shared over RPC, LRU-cached and dual-theme, so client bundles stop shipping their own grammars and themes.'
---

Server-side [Shiki](https://shiki.style) syntax highlighting shared over RPC by every devframe on the host, so client bundles stop shipping their own grammars and themes. Shiki itself loads lazily on first use; results are LRU-cached per `(code, lang, themes)` and every RPC function is `cacheable` on the client too.

Package: `@devframes/service-shiki` · Scope: `devframes:service:shiki`

## Installing

```ts
defineDevframe({
  importMetaUrl: import.meta.url,
  services: [
    { package: '@devframes/service-shiki', options: { langs: ['vue', 'ts'] } },
  ],
})
```

A hub installs a shared instance with `initHub({ services: [createShikiService(options)] })`.

## Options

`ShikiServiceOptions`: later installer wins on `themes` (deep-merged per key); `langs` union-merged.

| Option   | Type              | Description                                                                                                                   |
| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `themes` | `{ light, dark }` | Dual light/dark theme pair every request uses unless it carries its own. Defaults to `vitesse-light` / `vitesse-dark`.        |
| `langs`  | `string[]`        | Languages to eagerly load at setup. Others load on demand per request; unknown ids degrade to plain text instead of throwing. |

## RPC functions

Registered under `devframes:service:shiki:*`, all `query` and `cacheable`. Each takes `{ code, lang?, themes? }`.

| Function         | Returns                                                                          |
| ---------------- | -------------------------------------------------------------------------------- |
| `highlight`      | `{ html }`: dual-theme HTML (light values inline, dark via `--shiki-dark` vars). |
| `code-to-hast`   | A HAST tree, for surfaces that render their own DOM.                             |
| `code-to-tokens` | Themed tokens, for line-oriented renderers (e.g. diff views).                    |

## Node API

`ctx.services.get('@devframes/service-shiki')` returns the in-process `ShikiServiceApi`: `highlight`, `codeToHast`, and `codeToTokens`.

## On the RPC client

```ts
const rpc = await connectDevframe()

if (rpc.services.has('@devframes/service-shiki')) {
  const shiki = rpc.services.get('@devframes/service-shiki')!
  const { html } = await shiki.rpc.call('highlight', { code, lang: 'ts' })
  element.innerHTML = html
}
```

## Source

[`services/shiki`](https://github.com/devframes/devframe/tree/main/services/shiki)

---
title: Error Reference
description: 'Devframe surfaces warnings and errors as structured diagnostics: each with a unique code, a human-readable message, and a link to this documentation.'
---

Devframe surfaces warnings and errors as structured diagnostics: each with a unique code, a human-readable message, and a link to this documentation.

## How error codes work

- Codes follow the pattern **`DF` + a 4-digit number**. Core `devframe` uses `DF00xx`–`DF07xx`; the hub reserves `DF8xxx`.
- Every page carries the message, cause, recommended fix, and the source file that emits it.
- **Level** is the diagnostic's severity: **error** or **warn**.
- Diagnostics are powered by [`nostics`](https://www.npmjs.com/package/nostics): structured codes with docs URLs, ANSI console output, and pluggable reporters.

## Devframe (DF)

Emitted by `devframe`: the framework-neutral host, RPC, streaming, assets, services, and JSON-render surfaces.

| Code                     | Level | Title                                              |
| ------------------------ | ----- | -------------------------------------------------- |
| [DF0006](/errors/DF0006) | error | RPC Function Not Registered                        |
| [DF0007](/errors/DF0007) | error | AsyncLocalStorage Not Set                          |
| [DF0008](/errors/DF0008) | error | View distDir Not Found                             |
| [DF0012](/errors/DF0012) | warn  | Storage Parse Failed                               |
| [DF0013](/errors/DF0013) | error | Shared State Not Found                             |
| [DF0014](/errors/DF0014) | error | Invalid Agent Field                                |
| [DF0015](/errors/DF0015) | error | Agent Tool Already Registered                      |
| [DF0016](/errors/DF0016) | error | Agent Resource Already Registered                  |
| [DF0017](/errors/DF0017) | error | MCP Server Start Failure                           |
| [DF0019](/errors/DF0019) | error | Agent Requires JSON-Serializable RPC               |
| [DF0020](/errors/DF0020) | error | Non-JSON Value in JSON-Serializable RPC            |
| [DF0021](/errors/DF0021) | error | RPC Function Already Registered                    |
| [DF0022](/errors/DF0022) | error | RPC Function Not Registered (Update)               |
| [DF0023](/errors/DF0023) | error | RPC Function Not Registered (Get)                  |
| [DF0024](/errors/DF0024) | error | Missing RPC Handler                                |
| [DF0025](/errors/DF0025) | error | Function Not in Dump Store                         |
| [DF0026](/errors/DF0026) | error | No Dump Match                                      |
| [DF0027](/errors/DF0027) | error | Invalid Dump Configuration                         |
| [DF0028](/errors/DF0028) | error | Snapshot Type Mismatch                             |
| [DF0029](/errors/DF0029) | warn  | Stream Buffer Overflow                             |
| [DF0030](/errors/DF0030) | error | Unknown Stream ID                                  |
| [DF0031](/errors/DF0031) | error | Write to Closed Stream                             |
| [DF0032](/errors/DF0032) | error | Streaming Channel Already Registered               |
| [DF0033](/errors/DF0033) | warn  | Dev RPC Bridge Failed to Start                     |
| [DF0034](/errors/DF0034) | error | Already-Namespaced Scoped Registration             |
| [DF0035](/errors/DF0035) | error | Storage File Persist Failed                        |
| [DF0036](/errors/DF0036) | error | RPC Call Rejected, Not Authorized                  |
| [DF0037](/errors/DF0037) | error | Duplicate Service Provider                         |
| [DF0038](/errors/DF0038) | error | Invalid JSON-Render Element Props                  |
| [DF0039](/errors/DF0039) | error | Duplicate JSON-Render View                         |
| [DF0040](/errors/DF0040) | error | JSON-Render View Used After Disposal               |
| [DF0041](/errors/DF0041) | error | JSON-Render Spec Is Not JSON-Serializable          |
| [DF0042](/errors/DF0042) | error | Static Build Disabled By The Definition            |
| [DF0043](/errors/DF0043) | error | Invalid RPC Argument                               |
| [DF0044](/errors/DF0044) | error | Invalid RPC Return Value                           |
| [DF0045](/errors/DF0045) | warn  | Instance Registry Update Failed                    |
| [DF0046](/errors/DF0046) | error | Connector Requires @devframes/agentic              |
| [DF0047](/errors/DF0047) | warn  | Agent Tool Wire-Name Collision                     |
| [DF0048](/errors/DF0048) | error | Unknown Shared-State Key                           |
| [DF0049](/errors/DF0049) | error | Connector Call Requires Port and Tool              |
| [DF0050](/errors/DF0050) | error | No Devframe Instance on Port                       |
| [DF0051](/errors/DF0051) | error | Instance Has No MCP Endpoint                       |
| [DF0052](/errors/DF0052) | error | HTTP Server Failed to Listen                       |
| [DF0054](/errors/DF0054) | error | connectionMeta() Before Instance Ready             |
| [DF0055](/errors/DF0055) | error | Instance Already Owns Its WebSocket Transport      |
| [DF0056](/errors/DF0056) | error | Instance Advertises an External WebSocket Endpoint |
| [DF0057](/errors/DF0057) | error | WebSocket Transport Disabled                       |
| [DF0058](/errors/DF0058) | error | Dev Server Disabled By The Definition              |
| [DF0059](/errors/DF0059) | warn  | Remote Assets File Listing Failed                  |
| [DF0060](/errors/DF0060) | error | Remote Asset Fetch Failed                          |
| [DF0061](/errors/DF0061) | warn  | Installed Assets Package Major Version Mismatch    |
| [DF0062](/errors/DF0062) | warn  | Installed Assets Package Version Skew              |
| [DF0063](/errors/DF0063) | warn  | Remote Asset Cache Write Failed                    |
| [DF0064](/errors/DF0064) | error | Remote Assets Materialization Failed               |
| [DF0065](/errors/DF0065) | error | Invalid Remote Assets Package Or Version           |
| [DF0066](/errors/DF0066) | warn  | Service Already Installed                          |
| [DF0067](/errors/DF0067) | error | Required Service Package Not Importable            |
| [DF0068](/errors/DF0068) | error | Required Service Version Range Not Satisfied       |
| [DF0069](/errors/DF0069) | warn  | Service Version Range Not Satisfied                |
| [DF0070](/errors/DF0070) | error | Invalid Service                                    |
| [DF0072](/errors/DF0072) | warn  | Snapshot Names Unknown RPC Method                  |
| [DF0073](/errors/DF0073) | error | JSON-Render Spec Does Not Match Its Schema         |
| [DF0074](/errors/DF0074) | error | JSON-Render Schema Is Asynchronous                 |
| [DF0075](/errors/DF0075) | warn  | No RPC Transport On This Runtime                   |
| [DF0076](/errors/DF0076) | error | WebSocket Upgrade Unsupported On This Runtime      |
| [DF0077](/errors/DF0077) | error | In-Page Channel Function Not Registered            |
| [DF0078](/errors/DF0078) | warn  | Agent Surface Without @devframes/agentic           |
| [DF0079](/errors/DF0079) | error | MCP Enabled Without @devframes/agentic             |

## Hub: context & lifecycle (DF80xx)

Emitted by `@devframes/hub` while assembling and mounting the unified surface.

| Code                     | Level | Title                                         |
| ------------------------ | ----- | --------------------------------------------- |
| [DF8000](/errors/DF8000) | error | Devframe Id Collides With a Reserved Hub Path |
| [DF8002](/errors/DF8002) | error | Both devframes and context Passed to initHub  |
| [DF8003](/errors/DF8003) | error | connectionMeta() Before Hub Instance Ready    |
| [DF8004](/errors/DF8004) | error | Devframe Id Is Not a Mountable URL Segment    |

## Hub: docks & mounting (DF81xx)

| Code                     | Level | Title                                                |
| ------------------------ | ----- | ---------------------------------------------------- |
| [DF8100](/errors/DF8100) | error | Dock Already Registered                              |
| [DF8101](/errors/DF8101) | error | Cannot Change Dock Id                                |
| [DF8102](/errors/DF8102) | error | Dock Not Registered                                  |
| [DF8103](/errors/DF8103) | error | Dock Entry Cannot Group Itself                       |
| [DF8104](/errors/DF8104) | error | Nested Dock Groups Unsupported                       |
| [DF8105](/errors/DF8105) | error | Devframe Already Mounted                             |
| [DF8106](/errors/DF8106) | warn  | Connection Meta Not Served                           |
| [DF8107](/errors/DF8107) | warn  | Unknown Dock Activation Target                       |
| [DF8108](/errors/DF8108) | error | Duplicate Renderer Module Type                       |
| [DF8109](/errors/DF8109) | error | Renderer Module File Missing                         |
| [DF8110](/errors/DF8110) | error | Renderer Type Is Not URL-Safe                        |
| [DF8111](/errors/DF8111) | warn  | Bare-Specifier Client Script Without Host Resolution |

## Hub: terminals (DF82xx)

| Code                     | Level | Title                                     |
| ------------------------ | ----- | ----------------------------------------- |
| [DF8200](/errors/DF8200) | error | Terminal Session Already Registered       |
| [DF8201](/errors/DF8201) | error | Terminal Session Not Registered           |
| [DF8202](/errors/DF8202) | error | Terminal Session Does Not Accept Input    |
| [DF8203](/errors/DF8203) | error | Failed To Spawn PTY Session               |
| [DF8204](/errors/DF8204) | error | Terminal Session Cannot Be Controlled     |
| [DF8205](/errors/DF8205) | error | Terminal Session Is Not Restartable       |
| [DF8206](/errors/DF8206) | error | Terminal Session Restart on Closed Stream |

## Hub: commands (DF84xx)

| Code                     | Level | Title                          |
| ------------------------ | ----- | ------------------------------ |
| [DF8400](/errors/DF8400) | error | Command Already Registered     |
| [DF8401](/errors/DF8401) | error | Cannot Change Command Id       |
| [DF8402](/errors/DF8402) | error | Command Not Registered         |
| [DF8403](/errors/DF8403) | error | Duplicate Command Id           |
| [DF8404](/errors/DF8404) | error | Agent Exposure Without Handler |

---
title: 'DF0006: RPC Function Not Registered'
description: RPC function "{name}" is not registered
---

## Message

> RPC function "`{name}`" is not registered

## Cause

`RpcFunctionsHost.invokeLocal()` was called with a method name that has not been registered on this host.

## Fix

Register the function with `ctx.rpc.register(defineRpcFunction({ name }))` before invoking it.

## Source

- [`packages/devframe/src/node/host-functions.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-functions.ts): `RpcFunctionsHost.invokeLocal()` throws `DF0006` when the requested method has not been registered on this host.

---
title: 'DF0007: AsyncLocalStorage Not Set'
description: AsyncLocalStorage is not set, it likely to be an internal bug of the Devframe foundation
---

## Message

> AsyncLocalStorage is not set, it likely to be an internal bug of the Devframe foundation

## Cause

`getCurrentRpcSession()` was called outside the RPC dispatch context. Usually indicates the RPC server hasn't been composed with the context transport binding (`createContextRpcServer`) or the caller is running before the async context is established.

## Fix

Only call `getCurrentRpcSession()` from RPC handlers executed by the server. Report as a bug if you hit this inside a handler.

## Source

- [`packages/devframe/src/node/host-functions.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-functions.ts): `getCurrentRpcSession()` throws `DF0007` when called outside the RPC dispatch async context.

---
title: 'DF0008: View distDir Not Found'
description: distDir {distDir} does not exist
---

## Message

> distDir `{distDir}` does not exist

## Cause

`DevframeViewHost.hostStatic()` was asked to mount a directory that doesn't exist on disk.

## Fix

Verify the `distDir` path resolves correctly (run your SPA build first, and check the resolved absolute path).

## Source

- [`packages/devframe/src/node/host-views.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-views.ts): `DevframeViewHost.hostStatic()` throws `DF0008` when the resolved `distDir` does not exist on disk.

---
title: 'DF0012: Storage Parse Failed'
description: 'Failed to parse storage file: {filepath}, falling back to defaults.'
---

## Message

> Failed to parse storage file: `{filepath}`, falling back to defaults.

## Cause

The persisted storage file (e.g. `auth.json`) could not be parsed as JSON. Storage falls back to the initial value so the devtool can continue.

## Fix

Delete the file to reset to defaults, or investigate how it became malformed.

## Source

- [`packages/devframe/src/node/storage.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/storage.ts): `createStorage()` catches `JSON.parse` errors and logs `DF0012` (with the cause attached) before falling back to `initialValue`.

---
title: 'DF0013: Shared State Not Found'
description: Shared state of "{key}" is not found, please provide an initial value for the first time
---

## Message

> Shared state of "`{key}`" is not found, please provide an initial value for the first time

## Cause

`RpcSharedStateHost.get()` was called for a key that has no stored state yet, and no `initialValue` was passed.

## Fix

Pass `initialValue` on the first call: `ctx.rpc.sharedState.get(key, { initialValue: ... })`.

## Source

- [`packages/devframe/src/node/rpc-shared-state.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/rpc-shared-state.ts): `RpcSharedStateHost.get()` throws `DF0013` when neither an existing entry nor an `initialValue` is provided for a key.

---
title: 'DF0014: Invalid Agent Field'
description: 'RPC function "{name}" has an invalid agent field: description must be a non-empty string.'
---

## Message

> RPC function "`{name}`" has an invalid `agent` field: `description` must be a non-empty string.

## Cause

An RPC function opts into agent exposure with an `agent` field, but its required `description` is missing or empty. Agents rely on the description to decide when to invoke a tool.

## Example

```ts
defineRpcFunction({
  name: 'rolldown-get-session-summary',
  type: 'query',
  agent: {
    description: '', // ❌ empty
  },
  // ...
})
```

## Fix

Provide a non-empty `description` (\~1–3 sentences) explaining what the tool does and when agents should invoke it, or remove the `agent` field to keep it RPC-only.

```ts
defineRpcFunction({
  name: 'rolldown-get-session-summary',
  type: 'query',
  agent: {
    description: 'Summarize a Rolldown build session by its id. Safe to call freely.',
  },
  // ...
})
```

## Source

- [`packages/devframe/src/node/host-agent.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-agent.ts): agent registration throws `DF0014` when a tool's `agent.description` is missing or empty.

---
title: 'DF0015: Agent Tool Already Registered'
description: Agent tool "{id}" is already registered.
---

## Message

> Agent tool "`{id}`" is already registered.

## Cause

`ctx.agent.registerTool()` was called with an `id` that collides with:

- an already-registered agent tool, or
- an RPC function whose `agent` field already exposes it under the same id.

Agent tool ids must be unique across both sources so that `invoke(id, args)` has an unambiguous target.

## Fix

Pick a distinct id or unregister the existing tool before re-registering:

```ts
const handle = ctx.agent.registerTool({ id: 'my-tool', /* ... */ })
// later...
handle.unregister()
ctx.agent.registerTool({ id: 'my-tool', /* new config */ })
```

## Source

- [`packages/devframe/src/node/host-agent.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-agent.ts): `ctx.agent.registerTool()` throws `DF0015` when the tool id collides with an existing agent tool or an RPC function's `agent` exposure.

---
title: 'DF0016: Agent Resource Already Registered'
description: Agent resource "{id}" is already registered.
---

## Message

> Agent resource "`{id}`" is already registered.

## Cause

`ctx.agent.registerResource()` was called with an `id` that already exists on the host.

## Fix

Pick a distinct id or unregister the existing resource first via the handle returned from the previous call.

## Source

- [`packages/devframe/src/node/host-agent.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-agent.ts): `ctx.agent.registerResource()` throws `DF0016` when the resource id is already registered on the host.

---
title: 'DF0017: MCP Server Start Failure'
description: 'Failed to start MCP server ({transport}): {reason}'
---

## Message

> Failed to start MCP server (`{transport}`): `{reason}`

## Cause

The MCP server failed while initializing. Common reasons:

- The stdio transport threw during `connect()` (e.g. stdin/stdout unavailable).
- The MCP adapter module could not be loaded (e.g. a corrupted install missing `@modelcontextprotocol/server`).

## Fix

- **Transport failure**: inspect the underlying error attached as `cause`.
- **Broken install**: reinstall dependencies so `@modelcontextprotocol/server` (a dependency of `devframe`) resolves.

## Source

- [`packages/devframe/src/adapters/mcp/build-server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/mcp/build-server.ts): `createMcpServer()` throws `DF0017` when the stdio transport fails to `connect()`.
- [`packages/devframe/src/adapters/dev.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/dev.ts): `createDevServer()` throws `DF0017` (transport `http`) when the route-based MCP server can't load its transport module.

---
title: 'DF0019: Agent Requires JSON-Serializable RPC'
description: RPC function "{name}" has agent set but jsonSerializable is false; MCP requires JSON-serializable data.
---

## Message

> RPC function "`{name}`" has `agent` set but `jsonSerializable` is `false`; MCP requires JSON-serializable data.

## Cause

The `agent` field exposes an RPC function as an MCP tool and implicitly enables strict JSON serialization. An explicit `jsonSerializable: false` conflicts with MCP's JSON-shaped data.

## Example

```ts
defineRpcFunction({
  name: 'my-plugin:summary',
  agent: { description: 'Returns a summary' },
  jsonSerializable: false, // ✗ throws DF0019
  handler: () => ({ items: [1, 2, 3] }),
})
```

## Fix

Remove `jsonSerializable: false` to use the implicit JSON contract, or remove `agent` to keep the function RPC-only.

```ts
defineRpcFunction({
  name: 'my-plugin:summary',
  jsonSerializable: true,
  agent: { description: 'Returns a summary' },
  handler: () => ({ items: [1, 2, 3] }),
})
```

## Source

- [`packages/devframe/src/rpc/agent-json-serialization.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/agent-json-serialization.ts): `ensureAgentJsonSerializable()` throws `DF0019` when a definition combines `agent` with `jsonSerializable: false` during registration or static dump collection.

---
title: 'DF0020: Non-JSON Value in JSON-Serializable RPC'
description: 'RPC function "{name}" declares jsonSerializable: true but the value at "{path}" is a {type}.'
---

## Message

> RPC function "`{name}`" declares `jsonSerializable: true` but the value at "`{path}`" is a `{type}`.

## Cause

A `jsonSerializable: true` function encodes its args and return value with strict `JSON.stringify` (on the wire and in build dumps). The serializer throws at the offending value rather than emit a corrupt payload when it hits anything JSON cannot round-trip losslessly:

- `Map`, `Set`, `WeakMap`, `WeakSet`
- `Date` (JSON coerces it to an ISO string)
- `BigInt`, `Symbol`, `Function`
- circular references
- non-plain class instances
- `undefined` leaves

## Example

```ts
defineRpcFunction({
  name: 'my-plugin:graph',
  jsonSerializable: true,
  handler: () => ({
    nodes: new Map([['a', 1]]), // ✗ throws DF0020: type=Map, path="nodes"
  }),
})
```

## Fix

Drop `jsonSerializable: true` to fall back to `structured-clone-es` (round-trips `Map`, `Set`, etc.), or convert the payload to a JSON-safe shape before returning. Keeping `agent` exposure requires the JSON-safe shape.

## Source

- [`packages/devframe/src/rpc/serialization.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/serialization.ts): the strict JSON serializer throws `DF0020` (with the offending path and runtime type) when a `jsonSerializable: true` payload contains a non-JSON value.

---
title: 'DF0021: RPC Function Already Registered'
description: RPC function "{name}" is already registered
---

## Message

> RPC function "`{name}`" is already registered

## Cause

`ctx.rpc.register()` was called twice with the same `name`. RPC names must be unique within a devtool.

## Fix

Either give the second registration a distinct name, or pass `force: true` to overwrite the previous one (e.g. during HMR-driven re-registration).

```ts
ctx.rpc.register(defineRpcFunction({ name: 'my-plugin:fn', handler: () => 1 }), true /* force */)
```

## Source

- [`packages/devframe/src/rpc/collector.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/collector.ts): `RpcFunctionsCollectorBase.register()` throws `DF0021` when an RPC name is already registered and `force` is not set.

---
title: 'DF0022: RPC Function Not Registered (Update)'
description: RPC function "{name}" is not registered. Use register() to add new functions.
---

## Message

> RPC function "`{name}`" is not registered. Use register() to add new functions.

## Cause

`ctx.rpc.update()` was called for a function that was never registered. `update()` is for replacing an existing definition.

## Fix

Call `ctx.rpc.register()` first, or pass `force: true` to `update()` to register-or-replace in one call.

## Source

- [`packages/devframe/src/rpc/collector.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/collector.ts): `RpcFunctionsCollectorBase.update()` throws `DF0022` when the named function was never registered.

---
title: 'DF0023: RPC Function Not Registered (Get)'
description: RPC function "{name}" is not registered
---

## Message

> RPC function "`{name}`" is not registered

## Cause

A consumer asked for the schema or handler of a function that has never been registered with `ctx.rpc.register()`.

## Fix

Confirm the function name matches a registration. RPC names are namespaced, so typos in the prefix are a common cause.

## Source

- [`packages/devframe/src/rpc/collector.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/collector.ts): collector `get()`/lookup paths throw `DF0023` when consumers ask for a function that has not been registered.

---
title: 'DF0024: Missing RPC Handler'
description: Either handler or setup function must be provided for RPC function "{name}"
---

## Message

> Either handler or setup function must be provided for RPC function "`{name}`"

## Cause

The RPC definition has neither a `handler` nor a `setup` returning `{ handler }`. devframe has nothing to invoke when the function is called.

## Fix

Add either `handler: ...` directly on the definition, or `setup: ctx => ({ handler: ... })` if the handler depends on context.

## Source

- [`packages/devframe/src/rpc/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/handler.ts): invocation throws `DF0024` when neither `handler` nor a `setup` returning `{ handler }` is provided.
- [`packages/devframe/src/rpc/dump/index.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/dump/index.ts): dump generation also requires a handler and throws `DF0024` if the definition is incomplete.

---
title: 'DF0025: Function Not in Dump Store'
description: Function "{name}" not found in dump store
---

## Message

> Function "`{name}`" not found in dump store

## Cause

A static-mode client called an RPC function that was not baked into the build dump. This usually means the function was added after the dump was generated, or its name changed between build and runtime.

## Fix

Re-run `createBuild` to regenerate the dump, or check that the call site uses the same name registered on the server.

## Source

- [`packages/devframe/src/rpc/dump/index.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/dump/index.ts): the static-mode dump resolver throws `DF0025` when a client calls a function name that is not present in the baked dump store.

---
title: 'DF0026: No Dump Match'
description: 'No dump match for "{name}" with args: {args}'
---

## Message

> No dump match for "`{name}`" with args: `{args}`

## Cause

A static-mode client called an RPC function with arguments that don't match any pre-computed record, and no `fallback` was set on the dump.

## Fix

Either widen the function's `dump.inputs` to cover the requested arguments, or provide `dump.fallback` so unmatched calls resolve to a default value instead of throwing.

```ts
defineRpcFunction({
  name: 'my-plugin:get',
  dump: {
    inputs: [['known-id']],
    fallback: null,
  },
})
```

## Source

- [`packages/devframe/src/rpc/dump/index.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/dump/index.ts): the static-mode dump resolver throws `DF0026` when none of the pre-computed inputs matches the call's args and no `fallback` was configured.

---
title: 'DF0027: Invalid Dump Configuration'
description: Function "{name}" with type "{type}" cannot have dump configuration. Only "static" and "query" types support dumps.
---

## Message

> Function "`{name}`" with type "`{type}`" cannot have dump configuration. Only "static" and "query" types support dumps.

## Cause

A `dump` field was attached to an `'action'` or `'event'` function. These types perform side effects rather than returning queryable data, so there is nothing meaningful to pre-compute.

## Fix

Drop the `dump` field, or change the function `type` to `'static'` / `'query'` if pre-computation is appropriate.

## Source

- [`packages/devframe/src/rpc/validation.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/validation.ts): definition validation throws `DF0027` when a `dump` field is attached to an `'action'` or `'event'` function.

---
title: 'DF0028: Snapshot Type Mismatch'
description: 'Function "{name}" with type "{type}" cannot use snapshot: true. Only "query" functions support this sugar; "static" functions have equivalent default behavior already.'
---

## Message

> Function "`{name}`" with type "`{type}`" cannot use `snapshot: true`. Only "query" functions support this sugar; "static" functions have equivalent default behavior already.

## Cause

`snapshot: true` is sugar for "query in dev, single baked snapshot in build". It is only meaningful on `'query'` functions: `'static'` already has equivalent default behavior, and `'action'` / `'event'` have nothing to snapshot.

## Fix

Remove `snapshot: true`, or change the function `type` to `'query'`.

## Source

- [`packages/devframe/src/rpc/validation.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/validation.ts): definition validation throws `DF0028` when `snapshot: true` is set on a function whose type is not `'query'`.

---
title: 'DF0029: Stream Buffer Overflow'
description: Stream "{channel}#{id}" dropped {dropped} chunk(s) after exceeding the client high-water mark.
---

## Message

> Stream "`{channel}#{id}`" dropped `{dropped}` chunk(s) after exceeding the client high-water mark.

## Cause

The consumer is slower than the producer, so the subscriber's queue grew past its `highWaterMark` and the oldest chunks were dropped to keep memory bounded. The stream keeps running and remaining chunks still flow.

## Fix

- Raise `highWaterMark` on `rpc.streaming.subscribe(channel, id, { highWaterMark })` if the consumer can occasionally catch up.
- Slow the producer by throttling, debouncing, or batching chunks server-side.
- Use `sharedState` if you only need the latest value rather than every chunk.

## Source

- [`packages/devframe/src/client/rpc-streaming.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/client/rpc-streaming.ts): the client subscription queue logs `DF0029` (with the dropped chunk count) when buffered chunks exceed `highWaterMark`.

---
title: 'DF0030: Unknown Stream ID'
description: 'Stream "{channel}#{id}" is unknown; no producer has called channel.start({ id: "{id}" }).'
---

## Message

> Stream "`{channel}#{id}`" is unknown; no producer has called `channel.start({ id: "{id}" })`.

## Cause

A client subscribed to a stream id no server-side producer has started. Either the producer never called `channel.start({ id })`, it already ended the stream and `replayWindow` is `0`, or the client passed the wrong id.

## Fix

- Run the producer before clients subscribe; typically await `rpc.call('your-action')` and use the returned id.
- Bump `replayWindow` on `ctx.rpc.streaming.create(name, { replayWindow })` to let clients resume after the producer finishes.
- Verify the id propagates correctly (action return → component prop → subscribe call).

## Source

- [`packages/devframe/src/node/rpc-streaming.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/rpc-streaming.ts): the streaming subscribe/unsubscribe paths log `DF0030` when a client references an `id` that no producer has started (and no replay buffer covers).

---
title: 'DF0031: Write to Closed Stream'
description: Cannot write to closed stream "{channel}#{id}".
---

## Message

> Cannot write to closed stream "`{channel}#{id}`".

## Cause

`stream.write(chunk)` was called after the stream was closed via `stream.close()` / `stream.error()` or after the consumer cancelled (which aborts `stream.signal`).

## Fix

Producers should poll `stream.signal.aborted` and exit cleanly:

```ts
const stream = channel.start({ id })
try {
  for (const chunk of source) {
    if (stream.signal.aborted)
      return
    stream.write(chunk)
  }
  stream.close()
}
catch (err) {
  stream.error(err)
}
```

## Source

- [`packages/devframe/src/utils/streaming-channel.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/streaming-channel.ts): `stream.write()` throws `DF0031` when called after the stream has been closed, errored, or aborted by the consumer.

---
title: 'DF0032: Streaming Channel Already Registered'
description: Streaming channel "{channel}" is already registered.
---

## Message

> Streaming channel "`{channel}`" is already registered.

## Cause

Two calls to `ctx.rpc.streaming.create(name, ...)` used the same channel name. Each name owns a wire namespace and must be unique within a context.

## Fix

- Reuse the existing channel handle rather than creating a new one with the same name.
- If two devtools want isolated streams, give each a distinct namespaced name (`my-devtool:chat-stream`, `other-devtool:logs-stream`).

## Source

- [`packages/devframe/src/node/rpc-streaming.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/rpc-streaming.ts): `ctx.rpc.streaming.create()` throws `DF0032` when the requested channel name is already registered on the context.

---
title: 'DF0033: Dev RPC Bridge Failed to Start'
description: 'Failed to start dev RPC bridge for "{id}": {reason}'
---

## Message

> Failed to start dev RPC bridge for "`{id}`": `{reason}`

## Cause

`devframeViteBridge()` (from `@devframes/vite`) could not bring up the bridge dev server that pairs a host-served SPA with devframe's RPC backend, usually because the preferred port is taken with no fallback range, or `def.setup(ctx)` threw. The surrounding Vite dev server keeps running, but the SPA's `__connection.json` lookup fails until the bridge starts.

## Fix

- Pin a port via `cli.port` / `cli.portRange` on the definition, or `port` on `devframeViteBridge`.
- Inspect `reason` (or the attached `cause`) to fix the setup function or free the port.

## Source

- [`packages/vite/src/index.ts`](https://github.com/devframes/devframe/blob/main/packages/vite/src/index.ts): `devframeViteBridge()` logs `DF0033` when port resolution or `createDevServer` throws during `configureServer`.

---
title: 'DF0034: Already-Namespaced Scoped Registration'
description: Scoped RPC registration for namespace "{namespace}" received an already-namespaced function name "{name}".
---

## Message

> Scoped RPC registration for namespace "`{namespace}`" received an already-namespaced function name "`{name}`".

## Cause

A [scoped context](/guide/scoped-context) auto-namespaces the ids you pass it. `ctx.scope('my-plugin').rpc.register(...)` therefore expects a **bare** function name and stores it as `my-plugin:<name>`. Passing a name that already contains a `:` separator would produce a double-prefixed id, so registration throws instead.

## Example

```ts
const my = ctx.scope('my-plugin')

// ✗ Bad: already namespaced
my.rpc.register(defineRpcFunction({ name: 'my-plugin:get-cwd', type: 'query', handler }))

// ✓ Good: bare name, stored as `my-plugin:get-cwd`
my.rpc.register(defineRpcFunction({ name: 'get-cwd', type: 'query', handler }))
```

## Fix

- Pass a bare name (no `:` separator) to the scoped `register`.
- To register a fully-qualified name on purpose, use the unscoped host: `ctx.base.rpc.register(...)` (server) or `client.scope(...).base.client.register(...)` (browser).

## Source

- [`packages/devframe/src/node/scope.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/scope.ts): `register()` / `update()` throw this when the supplied definition name is already namespaced.

---
title: 'DF0035: Storage File Persist Failed'
description: 'Failed to persist storage file: {filepath}'
---

## Message

> Failed to persist storage file: `{filepath}`

## Cause

A shared-state store's debounced write to disk failed: the directory could not be created, or the temp-file write / atomic rename threw. Usually the storage directory is not writable or the disk is full.

## Fix

Check that the storage directory is writable and has free space.

## Source

- [`packages/devframe/src/node/storage.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/storage.ts): the debounced `updated` handler reports this when writing the temp file or renaming it into place fails.

---
title: 'DF0036: RPC Call Rejected, Not Authorized'
description: 'RPC call to "{name}" was rejected: the caller is not authorized.'
---

## Message

> RPC call to "`{name}`" was rejected: the caller is not authorized.

## Cause

An `authorize` gate (set directly or via an [`auth` handler](/guide/security)) rejected the call: the session is untrusted and the method is not `anonymous:`-prefixed (see `isAnonymousRpcMethod`).

## Example

```ts
// Handshake methods stay reachable before auth completes…
await client.call('anonymous:devframe:auth', { authToken: '', ua, origin })

// …but trusted methods throw until the handshake succeeds.
await client.call('some-plugin:do-something') // ✗ throws DF0036
```

## Fix

- Complete the auth handshake before calling a trusted method.
- Connect with a static/pre-shared token (`createInteractiveAuth`'s `clientAuthTokens`) for CI or shared machines.
- With a custom `authorize`, confirm it allows the method; it receives the method name and the session's `meta`.

## Source

- [`packages/devframe/src/node/rpc-core.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/rpc-core.ts): `createContextRpcServer`'s resolver throws this when `authorize`/`auth.authorize` rejects a call.

---
title: 'DF0037: Duplicate Service Provider'
description: A service is already provided under "{id}".
---

## Message

> A service is already provided under "`{id}`".

## Cause

`ctx.services` holds exactly one provider per service id. A second `provide()` under the same id throws instead of silently replacing a service another devframe may already hold a reference to.

## Example

```ts
// ✗ Bad: provided twice
ctx.services.provide('my-plugin:sources', hostA)
ctx.services.provide('my-plugin:sources', hostB)

// ✓ Good: revoke the previous provider first
const revoke = ctx.services.provide('my-plugin:sources', hostA)
revoke()
ctx.services.provide('my-plugin:sources', hostB)
```

## Fix

- Revoke the existing provider first; `provide()` returns a revoke function.
- If the collision is between two unrelated devframes, namespace the id with your devframe id (`<plugin-id>:<service>`), the same rule RPC function names follow.
- Guard idempotent setup paths with `ctx.services.has(id)`.

## Source

- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts): `provide()` throws this when the id is already taken.

---
title: 'DF0038: Invalid JSON-Render Element Props'
description: 'JSON-render view "{id}" received invalid props on element "{key}": {issues}'
---

## Message

> JSON-render view "`{id}`" received invalid props on element "`{key}`": `{issues}`

## Cause

`@devframes/json-render` validates every element's props against the base catalog's per-component schema at spec ingress (`createJsonRenderView` / `view.update`). An element whose props don't match its component's schema is rejected here.

## Example

```ts
createJsonRenderView(ctx, {
  id: 'toolbar',
  /** ✗ throws DF0038: `variant` is not a Button variant */
  spec: { root: 'a', elements: { a: { type: 'Button', props: { variant: 'nope' }, children: [] } } },
})
```

## Fix

Match the element props to the base catalog's prop schema for that component. Dynamic `$state` / `$bindState` expressions are accepted wherever a scalar prop is expected.

## Source

- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts): `validateElementProps()` throws this at ingress and on `update`.

---
title: 'DF0039: Duplicate JSON-Render View'
description: A JSON-render view with id "{id}" already exists in scope "{scope}".
---

## Message

> A JSON-render view with id "`{id}`" already exists in scope "`{scope}`".

## Cause

An author-supplied id forms each view's shared-state key `devframe:json-render:<scope>:<id>`, so ids must be unique within a scope for the client to keep a stable subscription across reconnects. A second view with the same scoped id throws instead of clobbering the first.

## Example

```ts
createJsonRenderView(ctx, { id: 'metrics', spec })
createJsonRenderView(ctx, { id: 'metrics', spec }) // ✗ throws DF0039
```

## Fix

Give each view a stable id unique within its scope, or dispose the previous view before recreating it. Scope defaults to the context namespace (or `global`); pass `scope` to isolate ids explicitly.

## Source

- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts): `createJsonRenderView()` throws this when the scoped id is already live.

---
title: 'DF0040: JSON-Render View Used After Disposal'
description: JSON-render view "{id}" was used after it was disposed.
---

## Message

> JSON-render view "`{id}`" was used after it was disposed.

## Cause

`view.dispose()` unregisters the view's shared state and its broadcast listeners. Calling `update` or `patchState` on a disposed handle is a lifecycle bug: the shared state it targeted no longer exists.

## Example

```ts
const view = createJsonRenderView(ctx, { id: 'metrics', spec })
view.dispose()
view.update(nextSpec) // ✗ throws DF0040
```

## Fix

Create a fresh view with `createJsonRenderView` instead of reusing a disposed handle. The id is free to reuse once disposed.

## Source

- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts): `update` / `patchState` throw this after `dispose()`.

---
title: 'DF0041: JSON-Render Spec Is Not JSON-Serializable'
description: 'JSON-render view "{id}" spec is not JSON-serializable: {reason}'
---

## Message

> JSON-render view "`{id}`" spec is not JSON-serializable: `{reason}`

## Cause

Specs and state travel across the RPC / static boundary as strict JSON. A spec containing functions, symbols, class instances, `Map`/`Set`, or circular references cannot cross that boundary, so it is rejected at ingress.

## Example

```ts
const spec: any = { root: 'a', elements: {} }
spec.self = spec // circular reference
createJsonRenderView(ctx, { id: 'x', spec }) // ✗ throws DF0041
```

## Fix

Keep specs and state strict JSON: remove functions, symbols, class instances, `Map`/`Set`, or circular references.

## Source

- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts): `assertJsonSerializable()` throws this at ingress and on `update`.

---
title: 'DF0042: Static Build Disabled By The Definition'
description: '"{id}" declares capabilities.build: false; its static export is not meaningful (writes are excluded and any live-served data won''t be there).'
---

## Message

> "`{id}`" declares `capabilities.build: false`; its static export is not meaningful (writes are excluded and any live-served data won't be there).

## Cause

The definition opted out of static export via `capabilities.build: false`, typically because it is inherently live (manages real files, spawns a process) and a build export would only produce a write-less shell. `createCac` already hides the `build` subcommand for such a definition; this covers a caller invoking `createBuild()` directly.

## Example

```ts
// ✗ Bad: builds a devframe that opted out of static export
await createBuild(assetsDevframe) // throws DF0042

// ✓ Good: the degraded export is still useful to you
await createBuild(assetsDevframe, { force: true })
```

## Fix

- Pass `{ force: true }` to `createBuild()` if the degraded export is still useful to you.
- Otherwise, drop `capabilities.build: false` on the definition if a static export should be supported after all.

## Source

- [`packages/devframe/src/adapters/build.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/build.ts): `createBuild()` throws this when `capabilities.build` is `false` and `force` isn't set.

---
title: 'DF0043: Invalid RPC Argument'
description: 'RPC function "{name}" received an invalid argument at position {index}: {issues}'
---

## Message

> RPC function "`{name}`" received an invalid argument at position `{index}`: `{issues}`

## Cause

Each declared `args` schema validates its argument before the handler runs, on every path: local, over-the-wire, and the agent/MCP bridge. The argument at `{index}` failed its schema. Validation guards without rewriting, so unmentioned object fields still reach the handler.

## Example

```ts
const greet = defineRpcFunction({
  name: 'greet',
  args: [v.string()],
  returns: v.string(),
  handler: name => `hi ${name}`,
})

// ✓ Good
await ctx.rpc.functions.greet('ada')

// ✗ Bad: a number where a string is required → DF0043 at position 0
await ctx.rpc.functions.greet(42 as never)
```

## Fix

Pass a value that satisfies the `args` schema declared for the function, or widen the schema if the value is legitimately allowed.

## Source

- [`packages/devframe/src/rpc/validate-io.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/validate-io.ts): `validateRpcArgs()` throws `DF0043` on the first argument that fails its declared schema.

---
title: 'DF0044: Invalid RPC Return Value'
description: 'RPC function "{name}" returned a value that failed its returns schema: {issues}'
---

## Message

> RPC function "`{name}`" returned a value that failed its `returns` schema: `{issues}`

## Cause

A declared `returns` schema validates the handler's resolved value before it goes back to the caller. The value failed the schema, whether from a bug in the handler or a schema narrower than the real result. Validation guards without rewriting, so a value carrying extra object fields is accepted.

## Example

```ts
const count = defineRpcFunction({
  name: 'count',
  args: [],
  returns: v.number(),
  /** ✗ Bad: returns a string where a number is declared → DF0044 */
  handler: () => 'twelve' as never,
})
```

## Fix

Make the handler return a value that satisfies the `returns` schema, or relax the schema so it describes the value the handler actually produces.

## Source

- [`packages/devframe/src/rpc/validate-io.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/rpc/validate-io.ts): `validateRpcReturn()` throws `DF0044` when the handler's resolved value fails its declared schema.

---
title: 'DF0045: Instance Registry Update Failed'
description: 'Failed to update the devframe instance registry at "{file}": {reason}'
---

## Message

> Failed to update the devframe instance registry at "`{file}`": `{reason}`

## Cause

A dev server (or a host calling `registerDevframeInstance`) could not write or remove its record in the instance registry directory (`~/.devframe/instances/` by default, or `$DEVFRAME_INSTANCES_DIR`), usually a read-only home, missing permissions, or a full disk. The server keeps running; only discovery is affected, so `devframe connect` won't see this instance.

## Fix

- Check that the registry directory is writable and the disk has free space.
- Point `DEVFRAME_INSTANCES_DIR` at a writable directory.
- Set `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` to opt out of registration entirely.

## Source

- [`packages/devframe/src/node/instance-registry.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/instance-registry.ts): `registerDevframeInstance()` reports this on a failed write and its `unregister()` on a failed removal.

---
title: 'DF0046: Connector Requires @devframes/agentic'
description: 'devframe connect requires the optional peer dependency @devframes/agentic: {reason}'
---

## Message

> `devframe connect` requires the optional peer dependency @devframes/agentic: `{reason}`

## Cause

`devframe connect` was started but `@devframes/agentic/connect` could not be imported. The connector lives in `@devframes/agentic` (together with the MCP SDK), an optional peer dependency of `devframe`: only agent-facing features need the package installed.

## Fix

Install the package next to devframe and run the connector again:

```sh
npm install @devframes/agentic
devframe connect
```

## Source

- [`packages/devframe/src/cli/main.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/main.ts): the `connect` subcommand throws this when the dynamic `@devframes/agentic/connect` import fails.

---
title: 'DF0047: Agent Tool Wire-Name Collision'
description: 'Agent tool "{id}" is hidden from the MCP surface: its wire name "{name}" collides with the tool "{existing}".'
---

## Message

> Agent tool "`{id}`" is hidden from the MCP surface: its wire name "`{name}`" collides with the tool "`{existing}`".

## Cause

MCP clients constrain tool names to `^[a-zA-Z0-9_-]{1,128}$`, so the MCP adapter derives each tool's wire name from its id (runs of characters outside `[a-zA-Z0-9_-]` become a single `_`). Two registered ids sanitized to the same wire name, for example `demo:greet` and `demo_greet`. The first registration keeps the name; the later tool is hidden from `tools/list`.

## Example

```ts
ctx.agent.registerTool({ id: 'demo:greet', description: '…', handler })
ctx.agent.registerTool({ id: 'demo_greet', description: '…', handler }) // hidden: same wire name
```

## Fix

Rename one of the two ids so they sanitize to distinct wire names. Namespaced ids (`devframes:plugin:<slug>:<fn>`, `devframe:<area>:<fn>`) collide only when they differ solely in separator characters.

## Source

- [`packages/devframe/src/adapters/mcp/build-server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/mcp/build-server.ts): the `tools/list` handler reports this once per hidden tool when deduplicating wire names.

---
title: 'DF0048: Unknown Shared-State Key'
description: Unknown shared-state key "{key}".
---

## Message

> Unknown shared-state key "`{key}`".

## Cause

The built-in `devframe_state_read` MCP tool was called with a `key` the host doesn't publish (or that the `exposeSharedState` filter excludes).

## Example

```ts
// The host publishes only `my-plugin:counter`; an agent calls:
// devframe_state_read({ key: 'my-plugin:cuonter' }) → DF0048
```

## Fix

Call the `devframe_state_read` tool without arguments to list the available keys, then retry with one of them.

## Source

- [`packages/devframe/src/adapters/mcp/build-server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/mcp/build-server.ts): `readStateResult()` throws this when the requested key is absent from the filtered key list.

---
title: 'DF0049: Connector Call Requires Port and Tool'
description: 'The devframe_connect_call-tool tool requires { port: number, tool: string }.'
---

## Message

> The devframe_connect_call-tool tool requires .

## Cause

The `devframe connect` gateway tool `devframe_connect_call-tool` was invoked without a numeric `port` or a string `tool` name, the two fields that identify which instance to dial and which of its tools to call.

## Example

```ts
// devframe_connect_call-tool({ tool: 'devframe_state_read' }) → DF0049 (missing port)
```

## Fix

Call `devframe_connect_list-instances` first (its result carries each instance's `port` and tool names), then retry with both fields.

## Source

- [`packages/devframe/src/cli/connect.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/connect.ts): `call()` throws this when the gateway arguments fail validation.

---
title: 'DF0050: No Devframe Instance on Port'
description: No running devframe instance on port {port}.
---

## Message

> No running devframe instance on port `{port}`.

## Cause

The `devframe connect` gateway tool `devframe_connect_call-tool` targeted a port with no live devframe instance behind it: neither the registry nor a direct probe found one serving `__connection.json`. The instance may have stopped, restarted on a different port, or never existed.

## Example

```ts
// No dev server on 5199:
// devframe_connect_call-tool({ port: 5199, tool: 'devframe_state_read' }) → DF0050
```

## Fix

Call `devframe_connect_list-instances` for the current instance list and retry with a live port.

## Source

- [`packages/devframe/src/cli/connect.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/connect.ts): `call()` throws this when neither the registry nor the port probe finds an instance.

---
title: 'DF0051: Instance Has No MCP Endpoint'
description: The devframe instance on port {port} has no MCP endpoint.
---

## Message

> The devframe instance on port `{port}` has no MCP endpoint.

## Cause

The `devframe connect` gateway tool `devframe_connect_call-tool` targeted a live instance running without an MCP route: its `__connection.json` advertises no `mcp` entry, so there is no endpoint to proxy the tool call to.

## Example

```ts
// The instance on 5173 was started without --mcp:
// devframe_connect_call-tool({ port: 5173, tool: 'devframe_state_read' }) → DF0051
```

## Fix

Restart the instance with the `--mcp` flag (or pass `mcp: true` to `createCac` / its programmatic host) to expose its tools, then list instances again.

## Source

- [`packages/devframe/src/cli/connect.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/connect.ts): `call()` throws this when the targeted instance's record carries `mcp: null`.

---
title: 'DF0052: HTTP Server Failed to Listen'
description: 'Failed to listen on {host}:{port}: {reason}'
---

## Message

> Failed to listen on `{host}:{port}`: `{reason}`

## Cause

The instance shell's HTTP server failed to bind `host:port`, most commonly `EADDRINUSE` (another process, often a previously running devframe, holds the port) or `EACCES` (insufficient permissions on a privileged port). The WS RPC transport is torn down before this surfaces, so nothing leaks.

## Example

```ts
// A previous instance is still bound to 4096:
// await createDevServer(def, { host: 'localhost', port: 4096 }) → DF0052
```

## Fix

- Free the port, or pick another via `--port`, `cli.port` / `cli.portRange` on the definition, or `port` on `devframeViteBridge` (`@devframes/vite`).
- The original node error is available as `error.cause`; check `error.cause.code` (e.g. `'EADDRINUSE'`) to branch on the failure kind programmatically.

## Source

- [`packages/devframe/src/node/instance-shell.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/instance-shell.ts): the instance shell's HTTP+WS binding throws this when its owned HTTP server's `listen()` fails.

---
title: 'DF0054: connectionMeta() Before Instance Ready'
description: connectionMeta() was called before initDevframe("{id}") finished initializing.
---

## Message

> connectionMeta() was called before initDevframe("`{id}`") finished initializing.

## Cause

`initDevframe` is a synchronous factory that kicks off asynchronous initialization eagerly, running `def.setup`, binding the WebSocket tier, and mounting the routes. `connectionMeta()` describes the WebSocket binding, which only exists once that initialization completes; calling it earlier has nothing correct to return.

## Example

```ts
import { initDevframe } from 'devframe/initiate'

const devtools = initDevframe(def, { base: '/__my-tool/' })
devtools.connectionMeta() // ✗ throws DF0054: init is still in flight

await devtools.ready
devtools.connectionMeta() // ✓ { backend: 'websocket', websocket: { … } }
```

## Fix

Await `instance.ready` (or any request through `instance.handler`, which awaits readiness internally) before reading `connectionMeta()`.

## Source

- [`packages/devframe/src/adapters/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/initiate.ts): `initDevframe`'s `connectionMeta()` throws this while initialization is still pending.

---
title: 'DF0055: Instance Already Owns Its WebSocket Transport'
description: This instance already owns its WebSocket transport ({tier}), so it cannot take over the host's upgrade events.
---

## Message

> This instance already owns its WebSocket transport (`{tier}`), so it cannot take over the host's upgrade events.

## Cause

`attach(server)` / `handleUpgrade(req, socket, head)` exist for the tier where the instance binds nothing and waits for the host to hand upgrade events over. When the options already name a local binding (`ws.port` or `ws.sidecar` (`tier: 'sidecar'`) or `server` (`tier: 'server'`)), that transport already serves the socket, so routing a second server's upgrades into it would give the same RPC group two conflicting bindings.

## Example

```ts
import { initHub } from '@devframes/hub/initiate'

const hub = initHub({ base: '/__devframes/', ws: { sidecar: true } })
hub.attach(myServer) // ✗ throws DF0055: the side-car already serves `__ws`
```

## Fix

Drop the `attach` / `handleUpgrade` call and let the configured transport serve the socket, or remove `server` / `ws.port` / `ws.sidecar` so the instance leaves the binding to you.

## Source

- [`packages/devframe/src/node/instance-shell.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/instance-shell.ts): the shared instance shell throws this from `attach` / `handleUpgrade` when the resolved tier is `sidecar` or `server`, for both `initDevframe` and `initHub`.

---
title: 'DF0056: Instance Advertises an External WebSocket Endpoint'
description: This instance advertises an external WebSocket endpoint ({url}), so it serves no socket of its own.
---

## Message

> This instance advertises an external WebSocket endpoint (`{url}`), so it serves no socket of its own.

## Cause

`ws.url` alone is the advertise-only tier: `__connection.json` names a fully-qualified endpoint the browser dials verbatim, and the server behind that URL owns the transport and its auth. This instance builds neither, so there is no socket for `attach(server)` / `handleUpgrade(req, socket, head)` to feed.

## Example

```ts
import { initDevframe } from 'devframe/initiate'

const relayed = initDevframe(def, {
  base: '/__my-tool/',
  ws: { url: 'wss://devtools.example.com/relay/__ws' },
})
relayed.attach(myServer) // ✗ throws DF0056: an external server owns the socket

// ✓ Serve the socket here, advertised through the relay (the tunnel pattern).
const tunnelled = initDevframe(def, {
  base: '/__my-tool/',
  ws: { url: 'wss://devtools.example.com/relay/__ws', sidecar: true },
})
```

## Fix

Drop `ws.url` to have the instance serve the socket, or pair it with `server` / `ws.port` / `ws.sidecar` for the tunnel pattern: a local binding that the advertised relay forwards to.

## Source

- [`packages/devframe/src/node/instance-shell.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/instance-shell.ts): the shared instance shell throws this from `attach` / `handleUpgrade` when the resolved tier is `external`, for both `initDevframe` and `initHub`.

---
title: 'DF0057: WebSocket Transport Disabled'
description: 'This instance disables its WebSocket transport (ws: false), so there is no socket to drive upgrades into.'
---

## Message

> This instance disables its WebSocket transport (`ws: false`), so there is no socket to drive upgrades into.

## Cause

`ws: false` runs the instance without a WebSocket, so clients connect over the SSE endpoint instead (`backend: 'sse'`). There is no socket for `attach(server)` / `handleUpgrade(req, socket, head)` to feed.

## Example

```ts
import { initDevframe } from 'devframe/initiate'

const sseOnly = initDevframe(def, {
  base: '/__my-tool/',
  ws: false,
})
sseOnly.attach(myServer) // ✗ throws DF0057: there is no socket

// ✓ SSE needs no upgrade wiring; serve the HTTP surface and you're done.
myServer.on('request', (req, res) => sseOnly.nodeMiddleware(req, res))
```

## Fix

Drop the `attach` / `handleUpgrade` wiring; the SSE endpoint rides the instance's ordinary HTTP surface (`handler` / `nodeMiddleware`), so serving requests is all a host needs. Remove `ws: false` if the instance should serve a WebSocket after all.

## Source

- [`packages/devframe/src/node/instance-shell.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/instance-shell.ts): the shared instance shell throws this from `attach` / `handleUpgrade` when the WebSocket tier is `disabled`, for both `initDevframe` and `initHub`.

---
title: 'DF0058: Dev Server Disabled By The Definition'
description: '"{id}" declares capabilities.dev: false; it does not support a live dev server (its value is a static export only).'
---

## Message

> "`{id}`" declares `capabilities.dev: false`; it does not support a live dev server (its value is a static export only).

## Cause

A definition opts out of the live dev server via `capabilities.dev: false` when its value is inherently static (e.g. a report generator with nothing to serve live). Calling `createDevServer()` on such a definition throws.

## Example

```ts
await createDevServer(reportDevframe) // ✗ throws DF0058

// Run it anyway:
await createDevServer(reportDevframe, { force: true })
```

## Fix

- Pass `{ force: true }` to `createDevServer()` to run it anyway.
- Otherwise, drop `capabilities.dev: false` on the definition if a live dev server should be supported after all.

## Source

- [`packages/devframe/src/adapters/dev.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/dev.ts): `createDevServer()` throws this when `capabilities.dev` is `false` and `force` isn't set.

---
title: 'DF0059: Remote Assets File Listing Failed'
description: 'Failed to fetch the file listing for "{package}@{version}" from {provider}: {reason}'
---

## Message

> Failed to fetch the file listing for "`{package}`@`{version}`" from `{provider}`: `{reason}`

## Cause

A remote-assets source resolves request paths against the CDN provider's file-listing API (`data.jsdelivr.com` for jsDelivr, `?meta` for unpkg, or a custom provider's `listFiles`). That listing request failed, usually because the provider is unreachable or returned an error status.

## Fix

Requests fall back to probing each candidate path against the provider directly. To resolve it:

- Check network access to the configured provider, or switch providers (`provider: 'unpkg'` or a custom mirror).
- Install the assets package locally (`npm install <package>`); a local copy is served with zero network and needs no listing.

## Source

- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts): `createRemoteAssetsStore()` reports this (once per store) when the provider's file listing cannot be fetched or parsed.

---
title: 'DF0060: Remote Asset Fetch Failed'
description: 'Failed to fetch a remote asset of "{package}" ({url}): {reason}'
---

## Message

> Failed to fetch a remote asset of "`{package}`" (`{url}`): `{reason}`

## Cause

A requested file is in neither the locally installed assets package nor the on-disk cache, and streaming it through the CDN provider failed: the request errored, the provider returned a non-OK status, or the source is `offline: true` with the file missing from the cache.

## Fix

- Install the assets package locally (`npm install <package>`) to serve it with zero network, best for offline and air-gapped machines.
- Otherwise check network access to the configured provider, or point `provider` at a reachable mirror.

## Source

- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts): `createRemoteAssetsStore()`'s `serve()` throws this when a provider fetch fails, returns a non-OK status, or an `offline` store misses its cache.

---
title: 'DF0061: Installed Assets Package Major Version Mismatch'
description: The locally installed "{package}@{installed}" is a different major version than the required "{required}".
---

## Message

> The locally installed "`{package}`@`{installed}`" is a different major version than the required "`{required}`".

## Cause

A locally installed copy of the assets package (resolved from the declaration's `resolveFrom` module) differs from the declared version by a **major**. Assets and node code are published in lockstep, so across a major boundary the served UI can be incompatible with its node backend, and devframe refuses to serve it.

## Fix

Install the assets package at the version its node package declares (they are published in lockstep):

```sh
npm install @devframes/plugin-git-client@2.0.0
```

Or uninstall the stale local copy so the assets stream from the CDN back-proxy at the exact declared version.

## Source

- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts): `resolveInstalledRemoteAssets()` throws this when the installed package's major version differs from the declared one.

---
title: 'DF0062: Installed Assets Package Version Skew'
description: The locally installed "{package}@{installed}" differs from the required "{required}"; serving the installed one.
---

## Message

> The locally installed "`{package}`@`{installed}`" differs from the required "`{required}`"; serving the installed one.

## Cause

A locally installed copy of the assets package differs from the declared version within the same major. The local install wins (keeping offline and air-gapped setups working), but the served assets are not byte-identical to the declared release, so the skew is surfaced.

## Fix

Install the exact declared version to serve byte-identical assets:

```sh
npm install @devframes/plugin-git-client@1.2.3
```

A major-version mismatch is rejected instead; see [DF0061](/errors/DF0061).

## Source

- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts): `resolveInstalledRemoteAssets()` reports this when the installed version differs from the declared one within the same major.

---
title: 'DF0063: Remote Asset Cache Write Failed'
description: 'Failed to persist a remote asset into the cache at "{filepath}": {reason}'
---

## Message

> Failed to persist a remote asset into the cache at "`{filepath}`": `{reason}`

## Cause

A remote asset streamed through the CDN back-proxy to the browser, but writing the teed copy into the local cache directory (`<project storage>/.remote-assets/<package>@<version>/…`) failed, usually from a permissions problem, a full disk, or a removed `node_modules`. The response was still served; only caching failed, so the file streams through the provider again next request.

## Fix

Check that the project storage directory (conventionally `node_modules/.<app>/devframe/`) is writable and has free space.

## Source

- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts): `createRemoteAssetsStore()`'s background cache write reports this when persisting a fetched file fails.

---
title: 'DF0064: Remote Assets Materialization Failed'
description: 'Failed to materialize the remote assets of "{package}@{version}": {reason}'
---

## Message

> Failed to materialize the remote assets of "`{package}`@`{version}`": `{reason}`

## Cause

A static build (`createBuild`) with remote-assets `clientAssets` needs every asset file up front so the output is self-contained. Materialization walks the provider's file listing and downloads each file; one of those steps failed: the provider has no `listFiles`, the listing request failed, or a file download errored.

## Fix

- Install the assets package locally (`npm install <package>@<version>`); builds copy from the local install and touch no network.
- Otherwise ensure the provider and its file-listing API are reachable during the build, or configure a custom provider that implements `listFiles`.

## Source

- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts): `createRemoteAssetsStore()`'s `materialize()` throws this when the file listing is unavailable or a download fails.

---
title: 'DF0065: Invalid Remote Assets Package Or Version'
description: Invalid remote-assets {field} "{value}".
---

## Message

> Invalid remote-assets `{field}` "`{value}`".

## Cause

A remote-assets source's `package` and `version` are interpolated into CDN URLs (`https://cdn.jsdelivr.net/npm/<package>@<version>/…`) and the on-disk cache path (`.remote-assets/<package>@<version>/`). So `package` must be a valid npm package name and `version` an exact semver version; a value carrying path separators, `@`, whitespace, or traversal segments (`..`) is rejected.

## Example

```ts
defineDevframe({
  clientAssets: {
    package: '@devframes/plugin-git-client',
    version: '../etc', // ✗ not a semver version
  },
})
```

## Fix

Use a valid npm package name and an exact version:

```ts
defineDevframe({
  clientAssets: {
    package: '@devframes/plugin-git-client',
    version: '1.2.3',
  },
})
```

## Source

- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts): `resolveStaticAssetsSource()` validates a remote source before resolving it.

---
title: 'DF0066: Service Already Installed'
description: Service "{package}" is already installed; keeping the first installation and ignoring this one's options.
---

## Message

> Service "`{package}`" is already installed; keeping the first installation and ignoring this one's options.

## Cause

Wire services are deduplicated by npm package name: the first installation wins and later installs return the existing node API. Options only merge before `ctx.services.ready()` fires, when declared services are constructed. A later `ctx.services.install()` for an already-constructed package can no longer influence its configuration, so its options are dropped with this warning.

## Example

```ts
// The package is already declared (and constructed pre-setup) elsewhere.
// ✗ This late install can't merge; { themes } is ignored.
ctx.services.install(createShikiService({ themes }))
```

## Fix

Declare the service so its options join the pre-setup merge: on the devframe's `DevframeDefinition.services`, or hub-wide via `initHub({ services })`:

```ts
initHub({
  services: [createShikiService({ themes })], // ✓ merges before setup
  devframes: [/* … */],
})
```

## Source

- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts): `installPackage` warns when an already-installed package is installed again.

---
title: 'DF0067: Required Service Package Not Importable'
description: 'Failed to import the required service package "{package}": {reason}'
---

## Message

> Failed to import the required service package "`{package}`": `{reason}`

## Cause

A service descriptor marked `required: true` names a package that could not be resolved and imported when services are constructed before setup. Descriptors resolve against the declaring devframe's own dependencies first (then the workspace root), so the package is usually missing from the declarer's `dependencies` or isn't installed. Descriptors without `required` degrade instead: the missing service is skipped and consumers observe `services.has(pkg) === false`.

## Example

```ts
defineDevframe({
  services: [
    // ✗ Throws before setup when the package isn't installed.
    { package: '@devframes/service-shiki', required: true },
  ],
})
```

## Fix

Install the service package next to whoever declares it (a devframe declaring it in `services` lists it in its own `dependencies` or `peerDependencies`), or drop `required: true` and let the consuming UI fall back when the service is absent.

## Source

- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts): the pre-setup construction throws when a `required` descriptor's package fails to import.

---
title: 'DF0068: Required Service Version Range Not Satisfied'
description: The installed service "{package}@{installed}" does not satisfy the required range "{required}".
---

## Message

> The installed service "`{package}`@`{installed}`" does not satisfy the required range "`{required}`".

## Cause

A service descriptor marked `required: true` declares a `version` range, and the resolved service's own `version` falls outside it. The range is checked when services are constructed before setup. Without `required`, the same mismatch installs the service anyway and warns with [`DF0069`](/errors/DF0069).

## Example

```ts
defineDevframe({
  services: [
    // ✗ Throws when @devframes/service-shiki@2.x is what's installed.
    { package: '@devframes/service-shiki', version: '^1', required: true },
  ],
})
```

## Fix

Align the installed service package with the declared range (update whichever side is stale), or drop `required: true` to downgrade the mismatch to a warning; the advertised meta carries the real version, so clients can gate on it.

## Source

- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts): the pre-setup construction checks each descriptor's `version` range against the resolved definition.

---
title: 'DF0069: Service Version Range Not Satisfied'
description: The installed service "{package}@{installed}" does not satisfy the declared range "{required}"; installing it anyway.
---

## Message

> The installed service "`{package}`@`{installed}`" does not satisfy the declared range "`{required}`"; installing it anyway.

## Cause

A service descriptor declares a `version` range, and the resolved service's own `version` falls outside it. The descriptor isn't marked `required`, so the service still installs: the range is a compatibility hint and this warning surfaces the drift. The advertised meta carries the real version, so client UIs can gate features on it. The `required: true` variant throws [`DF0068`](/errors/DF0068) instead.

## Example

```ts
defineDevframe({
  services: [
    // Installed: @devframes/service-shiki@2.0.0 → warns, still installs.
    { package: '@devframes/service-shiki', version: '^1' },
  ],
})
```

## Fix

Align the installed service package with the declared range to silence the warning, or widen the declared range when the newer service is actually fine.

## Source

- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts): the pre-setup construction checks each descriptor's `version` range against the resolved definition.

---
title: 'DF0070: Invalid Service'
description: 'Invalid service "{package}": {reason}'
---

## Message

> Invalid service "`{package}`": `{reason}`

## Cause

A wire service failed structural validation at install time. The `reason` names the specific gap:

- the install input has no `package` name,
- a definition is missing its `version` or its RPC `scope` namespace,
- an imported service package's default export is not a factory function,
- the factory didn't return a definition with a `setup` function.

## Example

```ts
/** ✗ A pre-built instance as the default export, not a factory. */
export default createShikiService()

/** ✓ The factory itself. */
export default createShikiService
```

## Fix

A service package's default export must be its `create<X>Service` factory, returning a `DevframeServiceDefinition`: an object with `package`, `version`, `scope`, and a `setup` function. See [Cross-Devframe Services](/guide/services#wire-services) for the full shape.

## Source

- [`packages/devframe/src/node/host-services.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-services.ts): `install()` validates its input; the pre-setup construction validates imported factories and the definitions they return.

---
title: 'DF0072: Snapshot Names Unknown RPC Method'
description: rpc.snapshot names "{method}", but no RPC function is registered under that id, so there is nothing to bake into the static build.
---

## Message

> `rpc.snapshot` names "`{method}`", but no RPC function is registered under that id, so there is nothing to bake into the static build.

## Cause

A `rpc.snapshot` entry references a method id the context has no RPC function for, so the static collector has nothing to dump. Typically the id is misspelled, or the service/devframe that registers it isn't installed when the build runs.

## Fix

Check the method id, and ensure the service/devframe that registers it is installed (e.g. declared in `services`) before the build collects the dump.

## Source

- [`packages/devframe/src/adapters/build.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/build.ts): `applySnapshotRpc()` reports this when a `snapshot` entry's method id is missing from `ctx.rpc.definitions`.

---
title: 'DF0073: JSON-Render Spec Does Not Match Its Schema'
description: 'JSON-render view "{id}" does not match its configured schema: {issues}'
---

## Message

> JSON-render view "`{id}`" does not match its configured schema: `{issues}`

## Cause

The spec failed the optional Standard Schema supplied when the JSON-render view was created. The same schema guards the initial spec and every update.

## Fix

Match the authored spec to the configured schema before creating or updating the view.

## Source

- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts): `validateSpec()` throws this before shared state changes.

---
title: 'DF0074: JSON-Render Schema Is Asynchronous'
description: JSON-render view "{id}" uses an asynchronous Standard Schema.
---

## Message

> JSON-render view "`{id}`" uses an asynchronous Standard Schema.

## Cause

JSON-render view creation and updates are synchronous, while the configured Standard Schema returned a promise.

## Fix

Use a synchronous Standard Schema for JSON-render specs.

## Source

- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts): `validateSpec()` rejects promise-returning validators.

---
title: 'DF0075: No RPC Transport On This Runtime'
description: On Bun/Deno a shared server needs crossws Node adapter and SSE is disabled, so no RPC transport is advertised.
---

## Message

> On  the shared server's WebSocket upgrade needs crossws's Node adapter, which refuses to run off Node, and SSE is disabled, so this instance advertises no RPC transport at all.

## Cause

Sharing a host's `node:http` server (the `server` tier) drives the WebSocket upgrade through crossws's Node adapter, which runs only on Node. On Bun and Deno the socket falls back to the SSE endpoint, but here `sse: false` turned that endpoint off too, so the instance has no way for a client to reach its RPC surface.

## Example

```ts
import { initHub } from '@devframes/hub/initiate'

// Running on Bun/Deno, sharing the host's node:http server:
const hub = initHub({
  server: viteHttpServer,
  sse: false, // ✗ removes the only transport left on Bun/Deno
})
```

## Fix

Keep the SSE endpoint enabled (drop `sse: false`) so clients connect over it on Bun/Deno, or move the socket to a side-car: `ws: { sidecar: true }` binds the native WebSocket adapter (`Bun.serve` / `Deno.serve`) on its own port, where a real WebSocket works.

## Source

- [`packages/devframe/src/node/instance-shell.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/instance-shell.ts): the shared instance shell warns this when a shared-server WebSocket binding falls back on Bun/Deno and the SSE endpoint is disabled, for both `initDevframe` and `initHub`.

---
title: 'DF0076: WebSocket Upgrade Unsupported On This Runtime'
description: attach / handleUpgrade drive a raw node:http upgrade into crossws Node adapter, which refuses to run on Bun/Deno.
---

## Message

> `attach` / `handleUpgrade` drive a raw `node:http` upgrade into crossws's Node adapter, which refuses to run on .

## Cause

`attach(server)` and `handleUpgrade(req, socket, head)` hand a raw `node:http` upgrade socket to crossws's Node adapter. That adapter runs only on Node: Bun and Deno expose WebSockets as `fetch` upgrades through `Bun.serve` / `Deno.serve` instead, so there is no `node:http` upgrade socket for the adapter to take over.

## Example

```ts
import { initHub } from '@devframes/hub/initiate'

// Running on Bun/Deno:
const hub = initHub({ base: '/__devframes/' })
hub.attach(myNodeHttpServer) // ✗ throws DF0076 on Bun/Deno
```

## Fix

On Bun/Deno, serve the advertised `__ws` route from `Bun.serve` / `Deno.serve` and complete the upgrade with `attachBunWsTransport` / `attachDenoWsTransport` (see the `hub-deno` example), or connect over the SSE endpoint instead; it rides the instance's ordinary HTTP surface and needs no upgrade wiring. A side-car (`ws: { sidecar: true }`) also binds the native WebSocket adapter for you on its own port.

## Source

- [`packages/devframe/src/node/instance-shell.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/instance-shell.ts): the shared instance shell throws this from `attach` / `handleUpgrade` on Bun/Deno, for both `initDevframe` and `initHub`.

---
title: 'DF0077: In-Page Channel Function Not Registered'
description: An in-page channel call names a function that is not registered on its endpoint.
---

## Message

> In-page channel function "" is not registered on this endpoint.

## Cause

The two endpoints disagree about their channel contract. The calling endpoint names a function that the receiving endpoint did not register in its `functions` option. This usually means the page script and panel use different protocol declarations or incompatible devframe versions.

## Example

```ts
import { connectPanelChannel, createPageScriptChannel } from 'devframe/in-page-channel'

interface PanelProtocol {
  functions: {
    pageScript: {
      inspect: () => void
    }
  }
}

const pageScript = createPageScriptChannel({
  name: 'devframes:example',
  functions: {},
})
pageScript.addPanelPort(port1)

const panel = connectPanelChannel<PanelProtocol>({
  name: 'devframes:example',
  functions: {},
})

await panel.call('inspect') // ✗ The page script did not register `inspect`.
```

## Fix

Import one shared protocol declaration into both endpoints, then register every function from the receiving side of that protocol in its `functions` option.

## Source

- [`packages/devframe/src/in-page-channel/internal.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/in-page-channel/internal.ts): `createLocalFunctionRegistry().resolve()` throws this when no local function definition matches the call name.

---
title: 'DF0078: Agent Surface Without @devframes/agentic'
description: 'This devframe exposes agent tools, but the MCP endpoint stays off: the optional peer "@devframes/agentic" is not installed.'
---

## Message

> This devframe exposes agent tools, but the MCP endpoint stays off: the optional peer "@devframes/agentic" is not installed.

## Cause

The devframe (or hub) left a non-empty agent surface (RPC functions with an `agent` field, registered agent tools, resources, or providers) and the `mcp` setting is the omitted `'auto'` default, which would mount the MCP route. But `@devframes/agentic`, the optional peer carrying the MCP adapter and the MCP SDK, is not installed, so no route can be served.

The warning is reported once per process; the instance keeps running without an MCP endpoint.

## Fix

Install the peer so the agent surface is served over MCP:

```sh
npm install @devframes/agentic
```

Or, if the tools should deliberately stay unexposed, set `mcp: false` to opt out silently.

## Source

- [`packages/devframe/src/adapters/_shared.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/_shared.ts): `loadAutoMcpAdapter()` reports this (once) when the agent surface is non-empty but the peer probe fails.

---
title: 'DF0079: MCP Enabled Without @devframes/agentic'
description: 'The mcp option is enabled, but the optional peer "@devframes/agentic" could not be loaded: {reason}'
---

## Message

> The `mcp` option is enabled, but the optional peer "@devframes/agentic" could not be loaded: `{reason}`

## Cause

An explicit `mcp` setting (`true`, a route options object, the `--mcp` flag, or the `mcp` CLI subcommand) asked for an MCP surface, but the implementation could not be loaded from the optional `@devframes/agentic` peer, typically because it is not installed. Unlike the omitted `'auto'` default (which degrades to a one-time [DF0078](/errors/DF0078) warning), an explicit opt-in fails fast rather than silently running without MCP.

## Fix

Install the peer next to devframe:

```sh
npm install @devframes/agentic
```

Or remove the explicit `mcp` setting (or pass `mcp: false`) if the endpoint isn't wanted. The underlying import error is attached as `cause`.

## Source

- [`packages/devframe/src/node/agentic.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/agentic.ts): `importAgenticMcp()` maps a failed load of `@devframes/agentic/mcp` to this error.

---
title: 'DF0080: Agent In-Page Function Not JSON-Serializable'
description: An in-page channel function sets `agent` but `jsonSerializable` is `false`.
---

## Message

> In-page channel function "" has `agent` set but `jsonSerializable` is `false`; MCP requires JSON-serializable data.

## Cause

The `agent` field exposes an in-page function over the browser-to-node agent bridge and MCP, which only consumes JSON-shaped data, so it implicitly enables strict JSON serialization. An explicit `jsonSerializable: false` conflicts with that contract.

## Example

```ts
import { createPageScriptChannel } from 'devframe/in-page-channel'

createPageScriptChannel({
  name: 'devframes:example',
  functions: {
    addTodo: {
      agent: { description: 'Add a todo item.' },
      jsonSerializable: false, // ✗ throws DF0080
      handler: (text: string) => ({ added: text }),
    },
  },
})
```

## Fix

Remove `jsonSerializable: false` to use the implicit JSON contract, or remove `agent` to keep the function channel-only.

```ts
const addTodo = {
  agent: { description: 'Add a todo item.' }, // jsonSerializable is inferred true
  handler: (text: string) => ({ added: text }),
}
```

## Source

- [`packages/devframe/src/in-page-channel/internal.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/in-page-channel/internal.ts): `createLocalFunctionRegistry().register()` throws this when a definition combines `agent` with `jsonSerializable: false`, and infers `jsonSerializable: true` otherwise.

---
title: 'DF8000: Devframe Id Collides With a Reserved Hub Path'
description: Devframe id "{id}" collides with a reserved hub path; it cannot be mounted directly under the hub base.
---

## Message

> Devframe id "`{id}`" collides with a reserved hub path; it cannot be mounted directly under the hub base.

## Cause

`initHub` mounts every devframe at `<base><id>/`, directly under the hub base. The filenames that live at that same level (`__connection.json`, `__ws`, `__index.json`, `__client-imports.js`, `__mcp`, and `embedded.js`) are the hub protocol's own endpoints, so a devframe id equal to one of them would shadow the endpoint.

## Example

```ts
import { initHub } from '@devframes/hub/initiate'

initHub({
  base: '/__devframes/',
  devframes: [defineDevframe({ id: '__mcp', /* … */ })], // ✗ throws DF8000
})
```

## Fix

Rename the devframe id, or mount it at a non-colliding path via `basePath` on the definition.

## Source

- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts): `initHub` throws this while mounting the `devframes` list.

---
title: 'DF8002: Both devframes and context Passed to initHub/buildHub'
description: initHub/buildHub received both devframes and context; the two assembly modes are mutually exclusive.
---

## Message

> `initHub`/`buildHub` received both `devframes` and `context`; the two assembly modes are mutually exclusive.

## Cause

`initHub` (and `buildHub`) assembles a hub two ways: **declaratively** (`devframes: [...]`, where it creates the hub context and mounts each devframe under `<base><id>/`), or **from a pre-built context** (`context: ctx`, where your host framework already mounted the devframes). A `devframes` list cannot be mounted into a context it doesn't own, so passing both contradicts.

## Example

```ts
// ✗ Bad
initHub({ base: '/__devframes/', devframes: [git], context: myCtx })

// ✓ Good, declarative:
initHub({ base: '/__devframes/', devframes: [git] })

// ✓ Good, bring your own context:
const ctx = await createHubContext({ host: myHost, cwd })
await ctx.install(git)
initHub({ base: '/__devframes/', context: ctx })
```

## Fix

Pick one mode. Use `configure(ctx)` on the declarative mode when you need post-mount registrations (docks, commands, terminals) on the instance-created context.

## Source

- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts): `initHub` throws this during initialization when both options are present.
- [`packages/hub/src/node/build.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/build.ts): `buildHub` throws this when both options are present.

---
title: 'DF8003: connectionMeta() Before Hub Instance Ready'
description: connectionMeta() was called before initHub finished initializing.
---

## Message

> connectionMeta() was called before initHub finished initializing.

## Cause

`initHub` is a synchronous factory that kicks off asynchronous initialization eagerly, creating the hub context, mounting every frame, and binding the WebSocket tier. `connectionMeta()` describes the WebSocket binding, which only exists once that initialization completes; calling it earlier has nothing correct to return.

## Example

```ts
import { initHub } from '@devframes/hub/initiate'

const hub = initHub({ base: '/__devframes/', devframes: [git] })
hub.connectionMeta() // ✗ throws DF8003: init is still in flight

await hub.ready
hub.connectionMeta() // ✓ { backend: 'websocket', websocket: { … } }
```

## Fix

Await `instance.ready` (or any request through `instance.handler`, which awaits readiness internally) before reading `connectionMeta()`.

## Source

- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts): `initHub`'s `connectionMeta()` throws this while initialization is still pending.

---
title: 'DF8004: Devframe Id Is Not a Mountable URL Segment'
description: Devframe id "{id}" is not a mountable URL segment; the hub mounts each frame at <base><id>/.
---

## Message

> Devframe id "`{id}`" is not a mountable URL segment; the hub mounts each frame at `<base><id>/`.

## Cause

`initHub` derives each frame's mount base from its id (`/__devframes/<id>/`), and that segment is routed by h3, where `:` and `*` are route-pattern markers and `/` ends the segment. An id carrying those characters either crashes route registration or matches the wrong paths.

## Example

```ts
import { initHub } from '@devframes/hub/initiate'

initHub({
  base: '/__devframes/',
  devframes: [defineDevframe({ id: 'devframes:plugin:my-tool', /* … */ })], // ✗ throws DF8004
})

// ✓ Good, route-safe id (letters, digits, `_`, `-`, `.`):
defineDevframe({ id: 'devframes_plugin_my-tool', /* … */ })
```

## Fix

Set a route-safe `id` on the definition: letters, digits, `_`, `-`, and `.` only (e.g. `my_plugin` instead of `my:plugin`). This constraint applies to the devframe id alone; RPC function ids (the colon-namespaced `devframes:plugin:<slug>:<fn>` convention) are unaffected.

## Source

- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts): `initHub` throws this while mounting the `devframes` list.

---
title: 'DF8006: Static Build Mount Base Is Not Absolute'
description: A static hub build writes each mount either under its base ("{base}") or as an absolute-path sibling of it, but "{urlBase}" is neither.
---

## Message

> A static hub build writes each mount either under its base ("`{base}`") or as an absolute-path sibling of it, but "`{urlBase}`" is neither

## Cause

`buildHub` maps a mount under the hub `base` into its `outDir` (the hub subtree), and any other mount to the deploy root (`outDir`'s parent) by its absolute path, so a devframe SPA or asset dir served as a sibling of the hub base still lands beside it. A mount base that is neither under the hub base nor an absolute path has no on-disk location in the output.

## Example

```ts
await buildHub({
  outDir: 'dist/__devframes',
  async configure(ctx) {
    // ✓ Good: under the hub base, written into `outDir`
    await ctx.install(a, { base: '/__devframes/a/' })
    // ✓ Good: an absolute sibling, written to the deploy root beside the hub
    await ctx.install(b, { base: '/tools/b/' })
    // ✗ Bad: a relative base resolves against neither
    await ctx.install(c, { base: 'tools/c/' })
  },
})
```

## Fix

Give the mount an absolute base (starting with `/`): a base under the hub base writes into `outDir`, and any other absolute base writes to the deploy root by its path.

## Source

- [`packages/hub/src/node/build.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/build.ts): `buildHub()`'s mount-to-disk mapping throws this for a mount base that is not absolute.

---
title: 'DF8100: Dock Already Registered'
description: Dock with id "{id}" is already registered
---

## Message

> Dock with id "`{id}`" is already registered

## Cause

`ctx.docks.register(view)` was called with an `id` another dock already owns. Dock ids are unique per hub context.

## Fix

- Pick a different dock id (namespace under your tool's id, e.g. `my-tool:overview`).
- To overwrite intentionally (e.g. hot reload), use the `force` parameter: `ctx.docks.register(view, true)`.

## Source

- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts): `DevframeDocksHost.register()` throws when `views.has(view.id) && !force`.

---
title: 'DF8101: Cannot Change Dock Id'
description: Cannot change the id of dock "{id}" to "{attempted}". Dock ids are immutable once registered
---

## Message

> Cannot change the id of dock "`{id}`" to "`{attempted}`". Dock ids are immutable once registered

## Cause

The `update` handle returned by `ctx.docks.register(view)` received a patch whose `id` differs from the original. Dock ids are immutable post-registration: they key the dock list and any shared-state references.

## Fix

- Drop `id` from your patch; only pass the fields you actually want to mutate.
- To replace one dock with a different one: call `ctx.docks.register(newView)` (or `register(newView, true)` to overwrite an existing id).

## Source

- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts): `DevframeDocksHost.register()` returns an `update` callable that throws this when the patch carries a different `id`.

---
title: 'DF8102: Dock Not Registered'
description: Dock with id "{id}" is not registered and cannot be updated
---

## Message

> Dock with id "`{id}`" is not registered and cannot be updated

## Cause

`ctx.docks.update(view)` was called with an `id` that has no prior registration. `update` is for mutating existing entries; new entries must go through `register`.

## Fix

- Use `ctx.docks.register(view)` for new entries.
- Verify the id matches a previously registered dock; typos / case mismatches are the usual cause.

## Source

- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts): `DevframeDocksHost.update()` throws when `views.has(view.id) === false`.

---
title: 'DF8103: Dock Entry Cannot Group Itself'
description: Dock entry "{id}" cannot set groupId to its own id
---

## Message

> Dock entry "`{id}`" cannot set groupId to its own id

## Cause

A dock entry registered with `groupId` pointing at its own `id`. `groupId` is a pointer to a *different* group entry the entry belongs to, so a self-reference would describe an entry that collapses under itself.

## Fix

- Point `groupId` at the `id` of a `type: 'group'` entry, such as `groupId: 'nuxt'`.
- Omit `groupId` entirely to keep the entry as a normal top-level dock entry.

## Source

- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts): `DevframeDocksHost.register()` and `update()` throw this when `view.groupId === view.id`.

---
title: 'DF8104: Nested Dock Groups Unsupported'
description: Dock group "{id}" cannot itself belong to a group (nested groups are unsupported)
---

## Message

> Dock group "`{id}`" cannot itself belong to a group (nested groups are unsupported)

## Cause

A `type: 'group'` entry was registered with `groupId` set. Dock grouping is one level deep: a group collects member entries, but a group cannot itself be a member of another group.

## Fix

- Remove `groupId` from the group entry so it stays a top-level dock-rail button.
- Keep members one level under their group; place each member's `groupId` on the leaf entry, not on another group.

## Source

- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts): `DevframeDocksHost.register()` and `update()` throw this when `view.type === 'group'` and `view.groupId` is set.

---
title: 'DF8105: Devframe Already Mounted'
description: Devframe "{name}" (id "{id}") is already mounted on this hub
---

## Message

> Devframe "`{name}`" (id "`{id}`") is already mounted on this hub

## Cause

`ctx.install(def)` was called with a devframe whose `id` already belongs to another devframe on the same hub. Devframes are deduplicated by `id`.

## Fix

Set `duplicationStrategy` on the definition to choose how duplicates are handled:

- `'duplicate'`: let every instance coexist under a disambiguated dock id (`my-tool`, `my-tool-2`, …).
- `'silent'`: drop duplicates quietly.
- `'throw'`: surface duplicates as errors.

Otherwise, remove the redundant `ctx.install` call (or duplicate `devframes` entry) so each devframe mounts once.

## Source

- [`packages/hub/src/node/install-devframe.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/install-devframe.ts): `ctx.install()` emits this when a devframe sharing an already-mounted `id` is installed and the strategy is not `'duplicate'`.

---
title: 'DF8106: Connection Meta Not Served'
description: The host cannot serve the RPC connection meta for devframe "{name}" (id "{id}") at "{base}"; its DevframeHost does not implement mountConnectionMeta.
---

## Message

> The host cannot serve the RPC connection meta for devframe "`{name}`" (id "`{id}`") at "`{base}`"; its `DevframeHost` does not implement `mountConnectionMeta`.

## Cause

A mounted devframe's SPA fetches `./__connection.json` relative to its base to discover the RPC endpoint, and `ctx.install` serves that file by calling the host's `mountConnectionMeta(base)`. A devframe with servable `clientAssets` was installed on a `DevframeHost` that does not implement it, so the SPA connects only when it shares an origin with the hub UI (inheriting meta from the parent window); cross-origin, sandboxed, or directly-opened iframes stay disconnected.

## Fix

Implement `mountConnectionMeta(base)` on your `DevframeHost` to serve `__connection.json` at each mounted base:

```ts
const host: DevframeHost = {
  mountStatic(base, distDir) { /* serve files */ },
  mountConnectionMeta(base) {
    // serve `${base}__connection.json` → { backend: 'websocket', websocket: port }
  },
  resolveOrigin() { /* … */ },
  getStorageDir(scope) { /* … */ },
}
```

A static-snapshot host that bakes `__connection.json` into its served files can implement it as a no-op to acknowledge this intentionally.

## Source

- [`packages/hub/src/node/install-devframe.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/install-devframe.ts): `ctx.install()` emits this when a devframe with servable `clientAssets` is installed on a host lacking `mountConnectionMeta`.

---
title: 'DF8107: Unknown Dock Activation Target'
description: Dock activation requested for unknown dock id "{id}"
---

## Message

> Dock activation requested for unknown dock id "`{id}`"

## Cause

`ctx.docks.activate(dockId)`, reached via the `hub:docks:activate` RPC, was called with a `dockId` that no registered dock entry owns. The activation is still broadcast, but no hub UI provider will switch to it.

## Fix

Pass a `dockId` that matches a registered dock entry. Ids are case-sensitive, so check for typos and ensure the target dock is registered before activating it. For the terminals dock the id is `devframes_plugin_terminals`:

```ts
await rpc.call('hub:docks:activate', {
  dockId: 'devframes_plugin_terminals',
  params: { sessionId },
})
```

## Source

- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts): `DevframeDocksHost.activate()` reports this when the requested dock id isn't in `views`.

---
title: 'DF8108: Duplicate Renderer Module Type'
description: A renderer module is already registered for dock type "{type}"
---

## Message

> A renderer module is already registered for dock type "`{type}`"

## Cause

`initHub({ renderers })` received two registrations carrying the same `type`. Each dock type resolves to exactly one renderer module in the hub's renderer manifest (the module served at `<base>__renderers/<type>.mjs`), so a second registration for the same type would be unreachable.

## Example

```ts
initHub({
  renderers: [
    jsonRenderUiRenderer(),
    { type: 'json-render', file: myOtherRenderer }, // ✗ duplicate type
  ],
})
```

## Fix

- Keep one registration per dock type: pick the implementation you want the manifest to serve.
- To override a manifest module for one specific client, register a renderer locally instead (`createDevframeClientRuntime({ renderers })`); local registrations take precedence.

## Source

- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts): `resolveRendererRegistrations()` throws when a `type` repeats.

---
title: 'DF8109: Renderer Module File Missing'
description: The renderer module registered for dock type "{type}" does not exist at "{file}"
---

## Message

> The renderer module registered for dock type "`{type}`" does not exist at "`{file}`"

## Cause

An `initHub({ renderers })` registration points at a file that isn't on disk. Renderer modules are prebuilt, self-contained browser ES modules the hub serves verbatim at `<base>__renderers/<type>.mjs`; a missing bundle would make every client's lazy import 404 at mount time, so the hub fails fast at startup instead.

## Example

```ts
initHub({
  renderers: [
    { type: 'json-render', file: '/path/that/was/never/built.mjs' }, // ✗
  ],
})
```

## Fix

- Build the renderer package first; the bundle is a build artifact (e.g. `@devframes/json-render-ui`'s `dist/renderer/json-render.mjs`).
- Prefer the package's registration helper over a hand-written path; `jsonRenderUiRenderer()` from `@devframes/json-render-ui/hub` resolves the shipped bundle for you.

## Source

- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts): `resolveRendererRegistrations()` throws when the resolved `file` fails the existence probe.

---
title: 'DF8110: Renderer Type Is Not URL-Safe'
description: Dock type "{type}" is not a servable renderer-module name; the hub serves each module at <base>__renderers/<type>.mjs
---

## Message

> Dock type "`{type}`" is not a servable renderer-module name; the hub serves each module at `<base>__renderers/<type>.mjs`

## Cause

An `initHub({ renderers })` registration carries a `type` that can't become a URL segment. The hub derives each module's serving path (and the manifest's `importFrom`) from the type, so `:` and `*` (route-pattern markers to the underlying router) or separators like `/` would break the route.

## Example

```ts
initHub({
  renderers: [
    { type: 'my:renderer', file: bundle }, // ✗ `:` is a route-param marker
  ],
})
```

## Fix

Use a route-safe dock type: letters, digits, `_`, `-`, and `.` only (e.g. `json-render`, `my-renderer`). The dock entries' `type` discriminator must match, so pick the safe name once, in the package that declares the type.

## Source

- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts): `resolveRendererRegistrations()` rejects a `type` failing the `[\w.-]+` segment check.

---
title: 'DF8111: Bare-Specifier Client Script Without Host Resolution'
description: Dock "{id}" declares the bare-specifier client script "{specifier}", but this host advertises no client-module resolution; the browser cannot resolve a bare npm specifier natively, so the script will fail to load.
---

## Message

> Dock "`{id}`" declares the bare-specifier client script "`{specifier}`", but this host advertises no client-module resolution; the browser cannot resolve a bare npm specifier natively, so the script will fail to load.

## Cause

A dock entry's client script (`clientScript`, `action`, `renderer`) names a bare npm specifier as its `importFrom`. Client scripts load with a native browser `import()`, which resolves only URL specifiers; a bare specifier needs the host runtime to resolve it, advertised as `clientModuleResolution`. This host advertises none, so the script fails to load.

## Example

```ts
initHub({
  base: '/__devframes/',
  configure(ctx) {
    ctx.docks.register({
      type: 'action',
      id: 'vue-tracer',
      title: 'Vue Tracer',
      icon: 'ph:crosshair-simple-duotone',
      /** ✗ Bare specifier on a host with no `clientModuleResolution` */
      action: { importFrom: 'vite-plugin-vue-tracer/client/vite-devtools' },
    })
  },
})
```

## Fix

Pick whichever side you control:

- **Run under a host framework that resolves bare specifiers**: declare `initHub({ clientModuleResolution })` (e.g. Vite's `'/@id/{specifier}'`). `@devframes/vite/hub` sets this by default.
- **Ship the script as a self-contained bundle** served by URL, and pass that URL as `importFrom` (after `ctx.host.mountStatic(...)`).
- **Resolve it in the hub UI provider** via `createDevframeClientRuntime({ resolveClientModule })`; then disregard this warning.

## Source

- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts): `DevframeDocksHost.register()` warns when a bare-specifier client script registers on a host whose `staticConfig.dock` declares no `clientModuleResolution`.

---
title: 'DF8200: Terminal Session Already Registered'
description: Terminal session with id "{id}" already registered
---

## Message

> Terminal session with id "`{id}`" already registered

## Cause

`ctx.terminals.register(session)` or `ctx.terminals.startChildProcess(opts, terminal)` was called with an `id` that another session already owns. Terminal ids are unique per hub context.

## Fix

- Pick a different session id (namespace under your tool: `my-tool:build-server`, `my-tool:tests`, …).
- If you want to reuse an existing session's slot, `ctx.terminals.remove(session)` first.

## Source

- [`packages/hub/src/node/host-terminals.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-terminals.ts): `DevframeTerminalsHost.register()` and `startChildProcess()` throw when the id is already taken.

---
title: 'DF8201: Terminal Session Not Registered'
description: Terminal session with id "{id}" not registered
---

## Message

> Terminal session with id "`{id}`" not registered

## Cause

`ctx.terminals.update(patch)` was called with an `id` for which no session has been registered.

## Fix

- Use `ctx.terminals.register(session)` to add new sessions.
- Verify the id matches an existing session; a common cause is updating after `remove()`.

## Source

- [`packages/hub/src/node/host-terminals.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-terminals.ts): `DevframeTerminalsHost.update()` throws when `sessions.has(patch.id) === false`.

---
title: 'DF8202: Terminal Session Does Not Accept Input'
description: Terminal session "{id}" does not accept input
---

## Message

> Terminal session "`{id}`" does not accept input

## Cause

`hub:terminals:write` or `hub:terminals:resize` was called for an output-only session. Sessions started with `ctx.terminals.startChildProcess()` are pipe-backed and read-only; only PTY sessions accept keystrokes and resize.

## Fix

Spawn it via `ctx.terminals.startPtySession()` to get an interactive, writable session.

## Source

- [`packages/hub/src/node/rpc-builtins.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/rpc-builtins.ts): the `hub:terminals:write` / `hub:terminals:resize` handlers throw this when the resolved session has no `write` handle.

---
title: 'DF8203: Failed To Spawn PTY Session'
description: 'Failed to spawn PTY session for "{command}": {reason}'
---

## Message

> Failed to spawn PTY session for "`{command}`": `{reason}`

## Cause

`ctx.terminals.startPtySession()` could not launch the requested command in a
pseudo-terminal: for example the executable was not found, the working
directory does not exist, or spawning was denied by the OS.

## Fix

- Verify the `command` resolves on `PATH` (or pass an absolute path) and that
`cwd` exists.
- Check the accompanying `reason` for the underlying spawn error.

## Source

- [`packages/hub/src/node/host-terminals.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-terminals.ts): `DevframeTerminalsHost.startPtySession()` throws this when an initial or restart `zigpty` spawn fails.

---
title: 'DF8204: Terminal Session Cannot Be Controlled'
description: Terminal session "{id}" cannot be controlled (no lifecycle handle)
---

## Message

> Terminal session "`{id}`" cannot be controlled (no lifecycle handle)

## Cause

`hub:terminals:terminate` or `hub:terminals:restart` was called for a session with no lifecycle handle. Sessions added with a bare `ctx.terminals.register()` are just a descriptor plus an output stream; only sessions spawned via `startChildProcess()` or `startPtySession()` own a process the hub can control.

## Fix

Spawn it via `ctx.terminals.startChildProcess()` or `startPtySession()`; sessions added with a bare `register()` expose no terminate/restart handle. A bare session's lifecycle is driven by whatever owns its process; `hub:terminals:remove` still drops it from the registry.

## Source

- [`packages/hub/src/node/rpc-builtins.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/rpc-builtins.ts): the `hub:terminals:terminate` / `hub:terminals:restart` handlers throw this when the resolved session has no `terminate` handle.

---
title: 'DF8205: Terminal Session Is Not Restartable'
description: Terminal session "{id}" is not restartable
---

## Message

> Terminal session "`{id}`" is not restartable

## Cause

`hub:terminals:restart` was called for a session registered with `restartable: false`, a flag for sessions whose lifecycle is owned elsewhere (a one-shot build, or a server like code-server restarted through its own controls).

## Fix

It was registered with `restartable: false`; restart it through its owner's controls, or spawn it with `restartable: true` (the default) to allow in-place restarts.

## Source

- [`packages/hub/src/node/rpc-builtins.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/rpc-builtins.ts): the `hub:terminals:restart` handler throws this when the resolved session has `restartable: false`.

---
title: 'DF8206: Terminal Session Restart on Closed Stream'
description: Terminal session "{id}" cannot be restarted; its output stream is already closed
---

## Message

> Terminal session "`{id}`" cannot be restarted; its output stream is already closed

## Cause

`restart()` was called on a `startChildProcess()` or `startPtySession()` session whose output stream is already closed. The stream closes irreversibly on a natural process exit or after `terminate()`: it backs a single-use `ReadableStream` controller that cannot be reopened, so restarting in place is not possible once it has closed.

## Fix

Drop the spent session with `ctx.terminals.remove(session)`, then spawn a replacement via `ctx.terminals.startChildProcess()` or `ctx.terminals.startPtySession()` with a fresh id.

## Source

- [`packages/hub/src/node/host-terminals.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-terminals.ts): the `restart()` handle returned by `startChildProcess()` and `startPtySession()` throws this once the session's stream has closed.

---
title: 'DF8400: Command Already Registered'
description: Command "{id}" is already registered
---

## Message

> Command "`{id}`" is already registered

## Cause

`ctx.commands.register(command)` was called with an `id` that another command already owns. Command ids are unique per hub context.

## Fix

- Pick a different command id (namespace under your tool: `my-tool:reload`, `my-tool:open-settings`, …).
- To replace, call `ctx.commands.unregister(id)` first.

## Source

- [`packages/hub/src/node/host-commands.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-commands.ts): `DevframeCommandsHost.register()` throws when `commands.has(command.id)`.

---
title: 'DF8401: Cannot Change Command Id'
description: Cannot change the id of a command. Use register() to add new commands
---

## Message

> Cannot change the id of a command. Use register() to add new commands

## Cause

The `update` handle returned by `ctx.commands.register(cmd)` received a patch with an `id` key. Command ids are immutable post-registration.

## Fix

- Drop `id` from the patch object.
- To register a new command, call `ctx.commands.register(newCmd)`.

## Source

- [`packages/hub/src/node/host-commands.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-commands.ts): `DevframeCommandsHost.register()` returns a `update` callable that throws when `'id' in patch`.

---
title: 'DF8402: Command Not Registered'
description: Command "{id}" is not registered
---

## Message

> Command "`{id}`" is not registered

## Cause

`ctx.commands.execute(id, …)` (or the `update()` handle returned by `register()`) was called with an `id` that has no registration. The command was either never registered or has already been `unregister()`'d.

## Fix

- Register the command first via `ctx.commands.register({ id, title, handler })`.
- Verify the id; typos and stale references are the usual cause.
- If invoking client-side, register the command on the client via `ctx.commands.register` in the dock client script.

## Source

- [`packages/hub/src/node/host-commands.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-commands.ts): `DevframeCommandsHost.execute()` and the `update` handle throw when the id is missing.

---
title: 'DF8403: Duplicate Command Id'
description: Command id "{id}" is already used by another command or child command
---

## Message

> Command id "`{id}`" is already used by another command or child command

## Cause

`ctx.commands.register(command)` or a command handle `update()` received a command tree where at least one id is already owned by another top-level command or child command. Command ids are globally unique per hub context, including child commands.

## Fix

- Namespace every command id under your tool, such as `my-tool:reload` or `my-tool:open-settings`.
- Give each child command its own id instead of reusing the parent id.
- Unregister the previous command before replacing it with a different command tree.

## Source

- [`packages/hub/src/node/host-commands.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-commands.ts): `DevframeCommandsHost.register()` and command handle `update()` throw when a command id is duplicated.

---
title: 'DF8404: Agent Exposure Without Handler'
description: Command "{id}" declares agent exposure but has no handler
---

## Message

> Command "`{id}`" declares agent exposure but has no handler

## Cause

`ctx.commands.register(command)` or a command handle `update()` received a command carrying an `agent` field but no `handler`. Agent-exposed commands are projected into `ctx.agent` as callable tools (reaching MCP clients through the devframe MCP adapter), so they must be executable server-side; a handler-less command is a palette group and cannot run.

## Example

```ts
// ✗ Bad: group-only command opting into the agent surface
ctx.commands.register({
  id: 'my-tool:group',
  title: 'My tool',
  agent: { description: 'Run my tool.' },
  children: [/* … */],
})

// ✓ Good: the executable child carries the agent field
ctx.commands.register({
  id: 'my-tool:group',
  title: 'My tool',
  children: [
    {
      id: 'my-tool:reload',
      title: 'Reload',
      agent: { description: 'Reload my tool\'s state. Call after changing its config.' },
      handler: () => reload(),
    },
  ],
})
```

## Fix

- Add a `handler` to the command carrying the `agent` field.
- Or move the `agent` field to an executable child command.

## Source

- [`packages/hub/src/node/host-commands.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-commands.ts): `DevframeCommandsHost.register()` and command handle `update()` validate agent exposure across the command tree.

---
title: Migrations
description: Version-by-version upgrade guides for devframe and @devframes/hub. Each release below has a drop-in path from the previous one.
---

Upgrade guides for devframe and `@devframes/hub`, newest first. Each one lists every breaking change with its drop-in replacement.

| Version                                         | What changed                                                                                                                                                |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Migrating to 1.0](/migrations/migration-1.0)   | Stabilizes the public API established in 0.10.1; no breaking changes, no code changes required.                                                             |
| [Migrating to 0.10](/migrations/migration-0.10) | Moves the MCP implementation and the MCP SDK into `@devframes/agentic`, a new optional peer; imports are unchanged.                                         |
| [Migrating to 0.9](/migrations/migration-0.9)   | Removes the compatibility shims deprecated across the 0.7 series, trims the public API, and moves the MCP surface to the stateless MCP 2026-07-28 protocol. |
| [Migrating to 0.8](/migrations/migration-0.8)   | Makes RPC schemas validator-neutral and runtime-validated, and adds the agent-native MCP API.                                                               |
| [Migrating to 0.7](/migrations/migration-0.7)   | Makes `cac` an optional peer and moves json-render into an opt-in package.                                                                                  |
| [Migrating to 0.6](/migrations/migration-0.6)   | Tightens `defineDevframe`'s metadata, replaces the terminal and WebSocket transports, and adds enforced auth.                                               |

For the full changelog of every release, see the [release notes on GitHub](https://github.com/devframes/devframe/releases).

---
title: Migrating to 1.0
description: '1.0 stabilizes the public API established in 0.10.1: no breaking changes, no code changes required.'
---

1.0 stabilizes the public API as it stood in 0.10.1.

There are no breaking changes and no code changes required - upgrade the version and go.

---
title: Migrating to 0.10
description: '0.10 moves the MCP implementation and the MCP SDK into @devframes/agentic, a new optional peer: install it to serve agent tools over MCP; imports are unchanged.'
---

0.10 moves the MCP implementation and the MCP SDK out of `devframe` into [`@devframes/agentic`](/adapters/mcp), a new **optional peer**. A devframe without an agent surface ships slimmer (no MCP SDK installed at all); one that exposes agent tools adds a single install. Your imports do not change.

## MCP requires `@devframes/agentic`

`devframe/adapters/mcp` stays the user-facing API and now lazy-loads its implementation from the `@devframes/agentic` peer; the peer itself is never imported directly. Install it wherever an MCP surface should be served:

```sh
npm install @devframes/agentic
```

Every surface reacts to the missing peer the same way:

| `mcp` setting                 | peer installed                             | peer missing                                                                                                       |
| ----------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| omitted / `'auto'`            | mounts once the agent surface is non-empty | non-empty surface: warns once ([DF0078](/errors/DF0078)), mounts nothing; empty surface: silent, no MCP code loads |
| `true` / route options object | always mounts                              | throws [DF0079](/errors/DF0079)                                                                                    |
| `false`                       | never mounts, never probes                 | same                                                                                                               |

This applies everywhere the `mcp` setting exists: `createCac` / `--mcp`, `createDevServer`, `initDevframe`, `initHub`'s aggregate endpoint, and the framework kits.

The exports are unchanged - `createMcpServer`, `createMcpFetchHandler`, `mountMcpHttp`, and their option types (also importable from `devframe/types`). Importing `devframe/adapters/mcp` without the peer installed throws the usual module-not-found error, exactly like `devframe/adapters/cac` with its optional `cac` peer. The `<your-app> mcp` stdio subcommand keeps working with the peer installed.

## `devframe connect` requires `@devframes/agentic`

The connector's gateway moved into the same peer, replacing the former `@modelcontextprotocol/client` optional peer. `devframe connect` without it throws [DF0046](/errors/DF0046):

| 0.9.x                                                                             | 0.10                             |
| --------------------------------------------------------------------------------- | -------------------------------- |
| `npm install @modelcontextprotocol/client` (optional peer for `devframe connect`) | `npm install @devframes/agentic` |

## `devframe` no longer depends on the MCP SDK

`@modelcontextprotocol/server` left `devframe`'s dependencies and `@modelcontextprotocol/client` left its optional peers; both are now regular dependencies of `@devframes/agentic`, so installing the peer is the whole story. If you had installed `@modelcontextprotocol/client` only for `devframe connect`, you can drop it:

```sh
npm uninstall @modelcontextprotocol/client
npm install @devframes/agentic
```

Code that imported SDK types directly for devframe's MCP options no longer needs to: the full option surface is typed on `devframe/adapters/mcp` and `devframe/types` without any SDK types.

## Removed deprecated APIs

0.10 drops the symbols deprecated during the 0.9 line. Each has a drop-in replacement:

| Removed                                                                                                    | Use instead                                                                                  |
| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `cli.mcp` on a definition                                                                                  | Pass `mcp` to the host (`createCac` / `--mcp`, `createDevServer`, `initDevframe`, `initHub`) |
| `cli.distDir` on a definition                                                                              | Top-level `clientAssets` on the definition                                                   |
| `resolveClientAssets` (from `devframe`)                                                                    | Read `definition.clientAssets` directly                                                      |
| `createDevframeClientHost`, `DevframeClientHost`, `DevframeClientHostOptions` (`@devframes/hub/client`)    | `createDevframeClientRuntime`, `DevframeClientRuntime`, `DevframeClientRuntimeOptions`       |
| `coerceAgentPositionalArgs`, `AgentArgsFallback` (`devframe/internal`)                                     | `toolInputToRpcArgs` / `toolInputToCommandArgs`                                              |
| `openInEditor`, `openInFinder`, `commonRpcFunctions` (`devframe/recipes/common-rpc-functions`)             | The [`@devframes/service-open`](/add-ons/services/open) wire service                         |
| `callEvent()` on an in-page channel                                                                        | `emit()`                                                                                     |
| `a11yPageScriptBundlePath`, `a11yAgentBundlePath` (`@devframes/plugin-a11y`)                               | `a11yClientScriptBundlePath`                                                                 |
| `AGENT_DISCOVERY_FILE`, `AgentDiscovery`, `DataInspectorAgent` (`@devframes/plugin-data-inspector/inject`) | `DISCOVERY_FILE`, `InjectDiscovery`, `DataInspectorEndpoint`                                 |

Dropping `cli.mcp` also removes the hub's `DF8005` warning: a hub's aggregate MCP route already covers every mounted devframe's tools, so a per-devframe MCP request no longer exists to conflict with it.

---
title: Migrating to 0.9
description: 0.9 removes the compatibility shims deprecated across the 0.7 series, trims the public API of devframe and @devframes/hub, and moves the MCP surface to the stateless MCP 2026-07-28 protocol.
---

0.9 removes the compatibility shims deprecated across the 0.7 series and trims the public API of `devframe` and `@devframes/hub`. Each change has a drop-in replacement. It also moves the [MCP](/adapters/mcp) surface to the stateless [MCP 2026-07-28 protocol](https://modelcontextprotocol.io/specification/2026-07-28). The devframe API is unchanged; see [The MCP endpoints are stateless](#the-mcp-endpoints-are-stateless).

## `devframe/adapters/cli` is removed

The `devframe/adapters/cli` entry is gone; import from `devframe/adapters/cac`:

| 0.8.x                                               | 0.9                                                 |
| --------------------------------------------------- | --------------------------------------------------- |
| `import { createCli } from 'devframe/adapters/cli'` | `import { createCac } from 'devframe/adapters/cac'` |
| `CreateCliOptions`                                  | `CreateCacOptions`                                  |
| `CliHandle`                                         | `CacHandle`                                         |

```ts
// 0.8.x
import { createCli } from 'devframe/adapters/cli'

await createCli(myDevframe).parse()
```

```ts
// 0.9
import { createCac } from 'devframe/adapters/cac'

await createCac(myDevframe).parse()
```

Typed-flag helpers `defineCliFlags` and `parseCliFlags` live on `devframe/adapters/cac` too.

## `devframe/recipes/open-helpers` is removed

Renamed to `common-rpc-functions` in 0.7.16. Import `commonRpcFunctions`:

```ts
// 0.8.x
import { openHelpers } from 'devframe/recipes/open-helpers'
```

```ts
// 0.9
import { commonRpcFunctions } from 'devframe/recipes/common-rpc-functions'
```

`openInEditor` and `openInFinder` are unchanged.

## RPC dump re-exports move to `devframe/rpc/dump`

Static-dump re-exports from the `devframe/rpc` barrel are removed; import from `devframe/rpc/dump`:

```ts
// 0.8.x
import { createClientFromDump, dumpFunctions } from 'devframe/rpc'

// 0.9
import { createClientFromDump, dumpFunctions } from 'devframe/rpc/dump'
```

This covers every dump export: `collectStaticRpcDump`, `createClientFromDump`, `dumpFunctions`, `getDefinitionsWithDumps`, `reviveDumpError`, `serializeDumpError`, and the `StaticRpcDump*` types.

## `@devframes/hub` json-render shims are removed

json-render moved into the opt-in [`@devframes/json-render`](/guide/json-render) package in 0.7; the hub-local shims are removed:

| 0.8.x (`@devframes/hub`)       | 0.9 (`@devframes/json-render`)                                                 |
| ------------------------------ | ------------------------------------------------------------------------------ |
| `defineJsonRenderSpec(spec)`   | Pass the spec directly to `createJsonRenderView(ctx, { id, spec })`            |
| `ctx.createJsonRenderer(spec)` | `createJsonRenderView(ctx, { id, spec })` (from `@devframes/json-render/node`) |
| `JsonRenderSpec`               | `DevframeJsonRenderSpec`                                                       |
| `JsonRenderElement`            | element shape of `DevframeJsonRenderSpec`                                      |
| `JsonRenderer`                 | `JsonRenderView`                                                               |
| `DevframeViewJsonRender`       | `DevframeJsonRenderDockEntry` (from `@devframes/json-render/hub`)              |

```ts
// 0.8.x
import { defineJsonRenderSpec } from '@devframes/hub'

const spec = defineJsonRenderSpec({ root: 'panel', elements: { /* ... */ } })
const renderer = ctx.createJsonRenderer(spec)
```

```ts
// 0.9
import { createJsonRenderView } from '@devframes/json-render/node'

const view = createJsonRenderView(ctx, {
  id: 'panel',
  spec: { root: 'panel', elements: { /* ... */ } },
})
```

`createJsonRenderView` returns a view with a serializable `ref`. Project it onto a hub dock via `toJsonRenderDockEntry` (`@devframes/json-render/hub`), which contributes the `'json-render'` dock type.

## `defineDevframe` moves to the package root

`defineDevframe` lives on `devframe` alongside `defineRpcFunction`; `devframe/types` is type-only. Import values and types from `devframe`:

| 0.8.x                                                       | 0.9                                                   |
| ----------------------------------------------------------- | ----------------------------------------------------- |
| `import { defineDevframe } from 'devframe/types'`           | `import { defineDevframe } from 'devframe'`           |
| `import type { DevframeNodeContext } from 'devframe/types'` | `import type { DevframeNodeContext } from 'devframe'` |

```ts
import type { DevframeNodeContext } from 'devframe'
// 0.9
import { defineDevframe, defineRpcFunction } from 'devframe'
```

## `devframe/utils/{promise,scope}` are removed

Two unused utility subpaths are removed:

| Removed                                                               | Replacement                             |
| --------------------------------------------------------------------- | --------------------------------------- |
| `import { promiseWithResolver } from 'devframe/utils/promise'`        | `Promise.withResolvers()` (native)      |
| `import { isQualifiedName, qualifyName } from 'devframe/utils/scope'` | Inline the check (`name.includes(':')`) |

## `devframe/node` is slimmed to the context API

`devframe/node` keeps only the context API: `createHostContext`, `createStorage` (with their options types), and `RpcFunctionsHost`. Serve via the adapters or [`devframe/initiate`](/adapters/initiate).

Internal host implementations and factories are no longer exported:

| Removed from `devframe/node`                                                        | Notes                                                                                             |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `DevframeDiagnosticsHost`, `DevframeServicesHostImpl`, `DevframeViewHost` (classes) | Internal host implementations. The same-named **types** remain on `devframe/types`.               |
| `createRpcSharedStateServerHost`, `createRpcStreamingServerHost`                    | Wired internally by `createContextRpcServer`.                                                     |
| `createScopedNodeContext`, `createNodeSettings`                                     | Internal to context assembly.                                                                     |
| `toDialableHost`, `formatHostForUrl`, `isObject`                                    | Internal helpers (`isObject` is removed entirely - inline `typeof x === 'object' && x !== null`). |

## Cross-package internals move to `devframe/internal`

Low-level primitives shared between `devframe` and the `@devframes/*` packages move from `devframe/node` to the new **unstable** `devframe/internal` entry point:

| Moved                                                                                                                 | From            | To                  |
| --------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------- |
| `createH3DevframeHost` (+ `CreateH3DevframeHostOptions`)                                                              | `devframe/node` | `devframe/internal` |
| `StartedServer` (the `createDevServer` return handle)                                                                 | `devframe/node` | `devframe/internal` |
| `DevframeAgentHost` (class)                                                                                           | `devframe/node` | `devframe/internal` |
| `coerceAgentPositionalArgs` (+ `AgentArgsFallback`)                                                                   | `devframe/node` | `devframe/internal` |
| `registerDevframeInstance` / `listLiveDevframeInstances` (+ `DevframeInstanceRecord`, `DevframeInstanceRegistration`) | `devframe/node` | `devframe/internal` |
| `normalizeHttpServerUrl`                                                                                              | `devframe/node` | `devframe/internal` |

## `startHttpAndWs` is removed

`startHttpAndWs` is gone; `createDevServer`, `initDevframe`, and `initHub` own the binding internally. `StartHttpAndWsOptions` is removed; `StartedServer` stays (re-exported from `devframe/internal`).

| 0.8.x                                                          | 0.9                                                           |
| -------------------------------------------------------------- | ------------------------------------------------------------- |
| `startHttpAndWs({ context, port, ... })` for a standalone tool | `createDevServer(def, { port, ... })`                         |
| `startHttpAndWs(...)` inside a host framework                  | `initDevframe(def, { base, ... })` / `initHub({ base, ... })` |

Bind your own transport with `createContextRpcServer` (`devframe/internal`) plus a transport from `devframe/rpc/transports/*`:

```ts
// 0.9 - bind the RPC socket onto a server you own
import { createServer } from 'node:http'
import { createContextRpcServer } from 'devframe/internal'
import { attachWsRpcTransport } from 'devframe/rpc/transports/ws-server'

const httpServer = createServer()
const { rpcGroup, onConnected, onDisconnected } = createContextRpcServer({ context, auth: false })
attachWsRpcTransport(rpcGroup, { server: httpServer, onConnected, onDisconnected })
httpServer.listen(port)
```

## `@devframes/hub`'s `mountDevframe` is removed - use `ctx.install`

| 0.8.x                                                 | 0.9                                                   |
| ----------------------------------------------------- | ----------------------------------------------------- |
| `import { mountDevframe } from '@devframes/hub/node'` | removed - call `ctx.install`                          |
| `await mountDevframe(ctx, def, opts)`                 | `await ctx.install(def, opts)`                        |
| `MountDevframeOptions`                                | `InstallDevframeOptions` (from `@devframes/hub/node`) |

```ts
// 0.8.x
import { createHubContext, mountDevframe } from '@devframes/hub/node'

const ctx = await createHubContext({ host, cwd, mode: 'dev' })
await mountDevframe(ctx, myDevframe)
```

```ts
// 0.9
import { createHubContext } from '@devframes/hub/node'

const ctx = await createHubContext({ host, cwd, mode: 'dev' })
await ctx.install(myDevframe)
```

## `@devframes/hub` category order lives only on `/constants`

`DEFAULT_CATEGORIES_ORDER` now lives only on `@devframes/hub/constants`; re-exports from `@devframes/hub`, `@devframes/hub/node`, and `@devframes/hub/client` are removed:

```ts
// 0.9
import { DEFAULT_CATEGORIES_ORDER } from '@devframes/hub/constants'
```

## The Vite bridge moves to `@devframes/vite`

`devframe/helpers/vite` is its own package `@devframes/vite`. `viteDevBridge` becomes three purpose-named Vite plugins on `@devframes/vite/single`:

| 0.8.x                                                          | 0.9                                                     |
| -------------------------------------------------------------- | ------------------------------------------------------- |
| `import { viteDevBridge } from 'devframe/helpers/vite'`        | `import { devframeVite } from '@devframes/vite/single'` |
| `viteDevBridge(def)` (static mount)                            | `devframeVitePlugin(def)`                               |
| `viteDevBridge(def, { devMiddleware: true })` (RPC bridge)     | `devframeViteBridge(def)`                               |
| `viteDevBridge(def, { devMiddleware: { port, host, flags } })` | `devframeViteBridge(def, { port, host, flags })`        |

The `devMiddleware` option is gone; bridge options flatten to the top level (`port`, `host`, `flags`, `auth`, `mcp`). `devframeVite(def, { bridge })` picks between the two plugins.

```ts
// 0.8.x
import { viteDevBridge } from 'devframe/helpers/vite'

export default defineConfig({
  plugins: [viteDevBridge(myDevframe, { devMiddleware: true })],
})
```

```ts
// 0.9
import { devframeViteBridge } from '@devframes/vite/single'

export default defineConfig({
  plugins: [devframeViteBridge(myDevframe)],
})
```

`@devframes/vite` (and `@devframes/nuxt` / `@devframes/next`) take `@devframes/hub` and `@devframes/hub-ui` as **optional** peers; only the `/hub` scope needs them.

## Built-in devframes' `/vite` subpath is removed

Each built-in devframe's `@devframes/plugin-<name>/vite` export is removed. For Vite, mount into [Vite DevTools](https://devtools.vite.dev) with `createPluginFromDevframe` (`@vitejs/devtools-kit/node`):

```ts
// 0.8.x
import { a11yVitePlugin } from '@devframes/plugin-a11y/vite'

export default defineConfig({
  plugins: [a11yVitePlugin()],
})
```

```ts
// 0.9
import createA11yDevframe from '@devframes/plugin-a11y'
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'

export default defineConfig({
  plugins: [createPluginFromDevframe(createA11yDevframe())],
})
```

Without Vite DevTools, call `devframeVite` against the built-in devframe's default-export instance:

```ts
import createA11yDevframe from '@devframes/plugin-a11y'
import { devframeVite } from '@devframes/vite/single'

export default defineConfig({
  plugins: [devframeVite(createA11yDevframe())],
})
```

`codeServerVite` and `terminalsVite` are unaffected.

## Built-in devframes' default export is now the factory, not an instance

The default export is now the `create<X>Devframe` factory, not a pre-built `DevframeDefinition`; call it to get an instance:

```ts
// 0.8.x
import a11yDevframe from '@devframes/plugin-a11y'

await ctx.install(a11yDevframe)
```

```ts
// 0.9
import createA11yDevframe from '@devframes/plugin-a11y'

await ctx.install(createA11yDevframe())
```

## `@devframes/nuxt` and `@devframes/next` split into `/single` and `/hub`

Both serve their single-devframe API from `.../single`; the bare root throws.

Nuxt: register the module by its subpath:

```ts
/** 0.8.x [nuxt.config.ts] */
export default defineNuxtConfig({ modules: ['@devframes/nuxt'] })

/** 0.9 [nuxt.config.ts] */
export default defineNuxtConfig({ modules: ['@devframes/nuxt/single'] })
```

Next: helpers and the React RPC client move down a level:

| 0.8.x                                                          | 0.9                                                                   |
| -------------------------------------------------------------- | --------------------------------------------------------------------- |
| `import { withDevframe } from '@devframes/next'`               | `import { withDevframe } from '@devframes/next/single'`               |
| `import { createDevframeNextHandler } from '@devframes/next'`  | `import { createDevframeNextHandler } from '@devframes/next/single'`  |
| `import { RpcProvider, useRpc } from '@devframes/next/client'` | `import { RpcProvider, useRpc } from '@devframes/next/single/client'` |

## Mounting a hub: the new `/hub` scope

`@devframes/vite/hub`, `@devframes/nuxt/hub`, and `@devframes/next/hub` mount a whole `@devframes/hub`, wrapping `initHub` and defaulting the UI to `@devframes/hub-ui`'s `createUi()` (override with `ui`, or `ui: false` for headless).

```ts
// Vite
import { viteDevframeHub } from '@devframes/vite/hub'

export default defineConfig({ plugins: [viteDevframeHub({ devframes: [] })] })
```

```ts
// Next: app/__devframes/[[...path]]/route.ts
import { nextDevframeHub } from '@devframes/next/hub'

export const runtime = 'nodejs'
const hub = nextDevframeHub({ devframes: [] })
export const GET = (req: Request) => hub.handler(req)
export const POST = (req: Request) => hub.handler(req)
export const DELETE = (req: Request) => hub.handler(req)
```

`@devframes/vite/hub` and `@devframes/nuxt/hub` recommend the native [Vite DevTools](https://devtools.vite.dev) / [Nuxt DevTools](https://devtools.nuxt.com) once (silence with `{ quiet: true }`); `@devframes/next/hub` stays quiet.

## The MCP endpoints are stateless

The [MCP](/adapters/mcp) surface serves the stateless [2026-07-28 protocol](https://modelcontextprotocol.io/specification/2026-07-28). The devframe API you author against (`createMcpServer`, `createMcpFetchHandler`, `mountMcpHttp`, `cli.mcp`, and the agent host) is unchanged; the change is in how the endpoints serve requests on the wire.

- **HTTP** serves each request through the SDK's `createMcpHandler`, building a fresh server per request. There is no `Mcp-Session-Id` and no `initialize` handshake to open a session, so a request reaches any server instance without affinity. A `GET` or `DELETE` (the 2025 session operations) is answered `405`. 2025-era clients keep listing and calling tools and resources through the SDK's stateless legacy path; the live server-push channel for `list_changed` notifications is available to modern clients over the `subscriptions/listen` stream they open.
- **stdio** serves the connection through the SDK's `serveStdio`, pinning one server instance per connection and negotiating the 2026-07-28 era (falling back to the 2025 handshake for a 2025-era opening).
- **`devframe connect`** probes each instance with `server/discover` and negotiates the modern era, falling back to the 2025 handshake for a 2025-only instance.

A client that connects to devframe's HTTP endpoint should negotiate the modern era to use the stateless protocol; one left on the default (2025-era) negotiation is still served through the stateless legacy path:

```ts
import { Client } from '@modelcontextprotocol/client'

const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  { versionNegotiation: { mode: 'auto' } },
)
await client.connect(transport)
```

---
title: Migrating to 0.8
description: 0.8 makes RPC schemas validator-neutral and runtime-validated, upgrades the MCP adapter to @modelcontextprotocol/sdk v2, and adds the agent-native MCP API. See the v0.8.0 release notes.
---

0.8 makes RPC schemas validator-neutral and runtime-validated, upgrades the MCP adapter to `@modelcontextprotocol/sdk` v2, and adds the agent-native MCP API. See the [v0.8.0 release notes](https://github.com/devframes/devframe/releases/tag/v0.8.0).

## RPC schemas are Standard Schema and validated at runtime

`args` and `returns` on `defineRpcFunction` are now typed against [Standard Schema](https://standardschema.dev/), not valibot's `GenericSchema`. Any Standard-Schema validator works (valibot, zod, arktype); existing valibot schemas keep compiling.

**Devframe no longer bundles a validator.** `valibot` was dropped from runtime dependencies; install one:

```sh
npm install valibot # or: zod / arktype
```

If your app already uses zod, reuse it. For zero-dep code, devframe ships a minimal builder at `devframe/utils/simple-schema`:

```ts
// Bring your own validator …
import { defineRpcFunction } from 'devframe'
import * as v from 'valibot'

export const rename = defineRpcFunction({
  name: 'devframes:plugin:terminals:rename',
  type: 'action',
  args: [v.object({ id: v.string(), title: v.string() })],
  returns: v.void(),
  setup: ctx => ({ handler: ({ id, title }) => { /* … */ } }),
})
```

```ts
// … or use the built-in zero-dep builder
import { defineRpcFunction } from 'devframe'
import { s } from 'devframe/utils/simple-schema'

export const rename = defineRpcFunction({
  name: 'devframes:plugin:terminals:rename',
  type: 'action',
  args: [s.object({ id: s.string(), title: s.string() })],
  returns: s.void(),
  setup: ctx => ({ handler: ({ id, title }) => { /* … */ } }),
})
```

**Declared schemas are now enforced.** Each argument is validated before the handler runs, and the resolved return value on the way out; a mismatch is rejected with a coded diagnostic. Audit schemas that were more type hint than contract: inputs that slipped through now throw.

## MCP adapter upgraded to `@modelcontextprotocol/sdk` v2

The MCP adapter targets the v2 SDK (scoped `@modelcontextprotocol/server`/`@modelcontextprotocol/client`). Swap the peer:

| 0.7.x                          | 0.8                               |
| ------------------------------ | --------------------------------- |
| `@modelcontextprotocol/sdk@^1` | `@modelcontextprotocol/server@^2` |

```sh
npm uninstall @modelcontextprotocol/sdk
npm install @modelcontextprotocol/server
```

`@modelcontextprotocol/server` remains an optional peer via `devframe/adapters/mcp`. `devframe connect` also needs `@modelcontextprotocol/client`.

SDK types imported directly moved from deep `@modelcontextprotocol/sdk/...` subpaths to flat entries on the scoped packages (`@modelcontextprotocol/sdk/server/stdio.js` → `@modelcontextprotocol/server/stdio`).

## Agent-native MCP API

0.8 adds the agent-facing API on `ctx.agent` (`registerTool`, `registerToolProvider`, `registerResource`), plus an instance registry and the `devframe connect` MCP connector. Existing `agent`-flagged RPCs keep working.

One type sharpens: a `handler` (and its `dump`) now returns `Thenable<returns>`, where `returns` describes the *resolved* value and the runtime always awaits, so an `async` handler whose `returns` is the unwrapped value type-checks correctly.

See [Agent-Native](/guide/agent-native) and [MCP → `devframe connect`](/adapters/mcp#discovery-devframe-connect).

---
title: Migrating to 0.7
description: 0.7 makes cac an optional peer and moves json-render out of @devframes/hub into an opt-in package.
---

0.7 makes `cac` an optional peer and moves json-render out of `@devframes/hub` into an opt-in package.

## `cac` is now an optional peer dependency

`devframe` no longer bundles [`cac`](https://github.com/cacjs/cac); it's an optional `peerDependency`. Projects using `createCac` (formerly `createCli`) install `cac`:

```sh
npm install devframe cac
```

Tools not using the CLI adapter (Vite plugins, embedded devframes, the [lower-level factories](/guide/standalone-cli#use-your-own-cli-framework)) never need `cac`.

## `devframe/adapters/cli` → `devframe/adapters/cac`

| 0.6.x                                               | 0.7                                                 |
| --------------------------------------------------- | --------------------------------------------------- |
| `import { createCli } from 'devframe/adapters/cli'` | `import { createCac } from 'devframe/adapters/cac'` |
| `CreateCliOptions`                                  | `CreateCacOptions`                                  |
| `CliHandle`                                         | `CacHandle`                                         |

```ts
// 0.6.x
import { createCli } from 'devframe/adapters/cli'

await createCli(myDevframe).parse()
```

```ts
// 0.7
import { createCac } from 'devframe/adapters/cac'

await createCac(myDevframe).parse()
```

`devframe/adapters/cli` still exports the old names as deprecated aliases (imports keep compiling), but you still need the `cac` peer; removed in a future major.

## json-render moves out of `@devframes/hub`

The hub is now json-render-agnostic: `defineJsonRenderSpec`, `ctx.createJsonRenderer`, and the JSON-render types move to the opt-in [`@devframes/json-render`](/guide/json-render).

| 0.6.x (`@devframes/hub`)       | 0.7 (`@devframes/json-render`)                                                 |
| ------------------------------ | ------------------------------------------------------------------------------ |
| `defineJsonRenderSpec(spec)`   | Pass the spec directly to `createJsonRenderView(ctx, { id, spec })`            |
| `JsonRenderSpec`               | `DevframeJsonRenderSpec`                                                       |
| `ctx.createJsonRenderer(spec)` | `createJsonRenderView(ctx, { id, spec })` (from `@devframes/json-render/node`) |

```ts
// 0.6.x
import { defineJsonRenderSpec } from '@devframes/hub'

const spec = defineJsonRenderSpec({ root: 'panel', elements: { /* ... */ } })
const renderer = ctx.createJsonRenderer(spec)
```

```ts
// 0.7
import { createJsonRenderView } from '@devframes/json-render/node'

const view = createJsonRenderView(ctx, {
  id: 'panel',
  spec: { root: 'panel', elements: { /* ... */ } },
})
```

`@devframes/hub` still exports `defineJsonRenderSpec` (deprecated) and runs `ctx.createJsonRenderer`, so 0.7 call sites keep working, but nothing registers with the dock union or gains `registerRenderer()`; removed in 0.8.

---
title: Migrating to 0.6
description: 0.6 tightens defineDevframe's metadata, replaces terminal and WebSocket transports, and adds enforced auth.
---

0.6 tightens `defineDevframe`'s metadata, replaces terminal and WebSocket transports, and adds enforced auth.

## `defineDevframe` requires four more fields

`version`, `packageName`, `homepage`, `description` are now required alongside `id`/`name`, sourced from `package.json`:

```ts
import pkg from '../package.json' with { type: 'json' }

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool', // display label
  version: pkg.version,
  packageName: pkg.name, // maps from package.json's `name`
  homepage: pkg.homepage,
  description: pkg.description,
  setup(ctx) { /* … */ },
})
```

See [Devframe Definition](/guide/devframe-definition#sourcing-metadata-from-packagejson) for the full reference and the optional `duplicationStrategy`.

## Auth handshake methods are renamed

The two pre-trust RPC methods moved under the `anonymous:` prefix, so `isAnonymousRpcMethod` covers them:

| 0.5.x                     | 0.6                                |
| ------------------------- | ---------------------------------- |
| `devframe:anonymous:auth` | `anonymous:devframe:auth`          |
| `devframe:auth:exchange`  | `anonymous:devframe:auth:exchange` |

RPC client calls (`requestTrustWithToken()`, `requestTrustWithCode()`) are unchanged; update only node-side handlers or `authorize` gates using the old names.

## WebSocket connections now enforce origin and (optionally) trust

Two gates landed on the RPC socket:

- **Cross-origin upgrades rejected by default.** Only loopback origins (`localhost`/`127.0.0.1`/`::1`) and `Origin`-less requests are accepted; another origin needs an explicit allowlist:
  ```ts
  await startHttpAndWs({
    context: ctx,
    port: 9999,
    allowedOrigins: ['https://my-tunnel.example.com'],
  })
  ```

  Pass `allowedOrigins: false` to disable the check (not recommended).
- **Real authorization enforcement, opt-in.** `auth: true` (default) stays permissive. A `DevframeAuthHandler` turns on the [pre-trust gate](/guide/security#the-pre-trust-gate): untrusted callers reach only `anonymous:` methods, else [`DF0036`](/errors/DF0036) throws. The [Interactive Auth](/references/interactive-auth) recipe builds one:
  ```ts
  import { startHttpAndWs } from 'devframe/node'
  import { createInteractiveAuth } from 'devframe/recipes/interactive-auth'

  const auth = createInteractiveAuth(ctx)
  const server = await startHttpAndWs({ context: ctx, port: 9999, auth })
  auth.printBanner()
  ```

## Terminals run on `zigpty`, not the `node-pty` peer

PTY sessions (`ctx.terminals.startPtySession()`) now spawn through [`zigpty`](https://github.com/pithings/zigpty)'s bindings, bundled with `@devframes/hub`; drop the optional `node-pty` peer.

## `StartedServer.wss` is now `StartedServer.ws`

The RPC transport moved from `ws` to [`crossws`](https://crossws.unjs.io/); the `startHttpAndWs`/`createDevServer` handle changed shape:

```ts
// 0.5.x
const server = await startHttpAndWs({ context: ctx, port: 9999 })
server.wss.clients // ws.WebSocketServer

// 0.6
const server = await startHttpAndWs({ context: ctx, port: 9999 })
server.ws // crossws NodeAdapter
```

Code reaching into `.wss` needs the `crossws` `NodeAdapter` API.

## `devframe/utils/human-id` is gone

Removed. Use `devframe/utils/nanoid` for a short random ID, or `devframe/utils/crypto-token`'s `randomToken()` / `randomDigits()` for security-sensitive values:

```ts
// 0.5.x
import { humanId } from 'devframe/utils/human-id'

humanId() // 'bright-orange-tiger'
```

```ts
// 0.6
import { nanoid } from 'devframe/utils/nanoid'

nanoid() // short URL-safe ID, no word-list dependency
```

---
title: References
navigation:
  icon: i-lucide-book-marked
description: 'Lookup pages the guides link into: the canonical terms, the when-clause contexts, every event name on the wire, the API tables for the node side, the browser side, and the hub.'
---

Lookup pages the guides link into:

- [Terms](/references/terms): the canonical vocabulary of these docs, one name per concept, with its anchoring API.
- [When Clauses](/references/when-clauses): the contexts and operators that gate docks, commands, and custom UI.
- [Events Reference](/references/events): every event, broadcast, shared-state key, and channel name, by direction and reach.
- [Node-Side API](/references/node-api): `DevframeDefinition` fields, CLI options, storage scopes, RPC function types, broadcast options, streaming lifecycle, remote assets, the `ctx.services` host and wire-service fields, diagnostics prefixes, and the auth surface.
- [Browser-Side API](/references/browser-api): `connectDevframe` options, RPC client events, connection statuses, and in-page channel error codes.
- [Hub API](/references/hub-api): hub subsystems, launcher fields, duplication strategies, dock categories, the hub UI protocol, the namespace routes, the client runtime, the client context, and dock entry types.
- [Utilities](/references/utilities): the small, stable helpers under `devframe/utils/*`, bundled into `devframe`.
- [Interactive Auth](/references/interactive-auth): the OTP auth recipe: handshake, resolver gate, connect-time trust, banner.

The [error reference](/errors) documents each `DF*` diagnostic code, and [migrations](/migrations) each version step. The adapter, framework-kit, and add-on pages each carry their own package's options and RPC tables.

---
title: Terms
navigation:
  icon: i-lucide-book-a
description: 'The canonical vocabulary of these docs: one name per concept, the API or package that anchors it, and how the pieces talk to each other.'
---

Every concept in these docs has exactly one name. This page fixes that vocabulary: when a term below appears anywhere in the documentation, it carries the meaning defined here.

## Core

| Term                  | Meaning                                                                                                                                                                                                                              | Anchor                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| **Devframe**          | The product: a framework-neutral foundation for building a devtool once and running it everywhere.                                                                                                                                   | none                                                    |
| `devframe`            | The npm package the foundation ships as.                                                                                                                                                                                             | `devframe`                                              |
| **a devframe**        | One tool: a definition plus its SPA, mountable anywhere.                                                                                                                                                                             | `defineDevframe()`, `DevframeDefinition`                |
| **built-in devframe** | A ready-to-run devframe shipped from this repo (data inspector, inspect, OG, a11y, git, terminals, code-server, assets). The `plugin-` npm prefix only sets these packages apart from core packages; Devframe has no plugin concept. | `@devframes/plugin-*`                                   |
| **adapter**           | A deployment entry point under `devframe/adapters/*`: cli (cac), dev, build, vite, embedded, mcp.                                                                                                                                    | `devframe/adapters/*`                                   |
| **framework kit**     | Framework conventions over the standard handler, each split into a `/single` and a `/hub` scope.                                                                                                                                     | `@devframes/vite`, `@devframes/nuxt`, `@devframes/next` |
| **opt-in package**    | A capability shipped as its own package and added when needed.                                                                                                                                                                       | `@devframes/json-render`                                |
| **hub**               | The composition layer that puts many devframes behind one handler; *a hub* is one `initHub()` instance.                                                                                                                              | `@devframes/hub`, `initHub()`                           |
| **hub UI provider**   | A hub UI implementation: the node-side `ui` slot plus the browser-side context contract. `@devframes/hub-ui` is the reference hub UI provider.                                                                                       | `initHub({ ui })`                                       |

## Node side

A devframe has two halves: the **node side** registers RPC functions and owns state; the **browser side** renders and calls them.

| Term                             | Meaning                                                                                                                                                                  | Anchor                 |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
| **node side**                    | The half of a devframe running in the Node process.                                                                                                                      | `setup(ctx)`           |
| **host framework**               | The environment a devframe or hub mounts into: a Vite dev server, a Next.js app, a Hono server. Named forms (*the Vite host*, *a Next.js host*) refer to a specific one. | `DevframeHost`         |
| **dev server**                   | The standalone HTTP server the dev adapter starts.                                                                                                                       | `createDevServer()`    |
| **side-car server**              | The separate RPC/WebSocket process used when a host framework's handlers never see upgrade requests.                                                                     | none                   |
| **hosted / standalone adapters** | The two mount contexts: hosted adapters (vite, embedded) default the base path to `/__<id>/`; standalone adapters (cli, build) default to `/`.                           | `resolveBasePath()`    |
| **workspace scope**              | Committable per-repository storage.                                                                                                                                      | `DevframeStorageScope` |
| **project scope**                | Per-checkout storage, gitignored.                                                                                                                                        | `DevframeStorageScope` |
| **global scope**                 | Per-user storage.                                                                                                                                                        | `DevframeStorageScope` |

## Browser side

| Term                | Meaning                                                                                                                          | Anchor                           |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| **browser side**    | The half of a devframe running in a page.                                                                                        | `devframe/client`                |
| **user app**        | The application being developed and inspected.                                                                                   | none                             |
| **host page**       | The browser document where the client runtime boots; in dev, usually the user app's own page.                                    | none                             |
| **client runtime**  | The headless runtime booted once per host page: it connects RPC, assembles the client context, and imports client scripts.       | `createDevframeClientRuntime()`  |
| **client context**  | The shared object client scripts receive: panel, docks, commands, when-clauses.                                                  | `DevframeClientContext`          |
| **client script**   | A dock entry's script, imported into the host page by the client runtime.                                                        | `clientScript`                   |
| **page script**     | A devframe's script running in the user app's page, loaded as a client script or standalone. The a11y page script runs axe-core. | none                             |
| **RPC client**      | The typed connection a browser surface gets.                                                                                     | `connectDevframe()`              |
| **SPA**             | A devframe's built web interface; `clientAssets` says where it lives.                                                            | `clientAssets`                   |
| **panel**           | A devframe's SPA as a rendered surface, in a dock panel or standalone.                                                           | none                             |
| **surface**         | Any rendered browser view: a panel, a dock iframe, a standalone SPA.                                                             | none                             |
| **external viewer** | A cross-origin surface (a browser extension, a separate devtools page) connecting from its own origin.                           | `registerDevframeViewerOrigin()` |
| **coding agent**    | An agent consuming a devframe over MCP, the only agent in these docs.                                                            | `createMcpServer()`              |

## Hub

| Term                 | Meaning                                                                  | Anchor                   |
| -------------------- | ------------------------------------------------------------------------ | ------------------------ |
| **mounted devframe** | A devframe served inside a hub under `<base><id>/`.                      | `initHub({ devframes })` |
| **dock entry**       | A registry item: iframe, launcher, custom-render, group, or json-render. | `ctx.docks`              |
| **dock rail**        | The bar listing every mounted tool.                                      | none                     |
| **dock panel**       | The open drawer rendering the active dock entry.                         | none                     |

## Communication paths

Three distinct paths connect the pieces; each has its own name.

| Path                | Between                         | Transport                                                                                                                                |
| ------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **RPC**             | browser side ↔ node side        | WebSocket or static snapshot, via `connectDevframe()`                                                                                    |
| **client context**  | client scripts ↔ client runtime | a shared object inside the host page                                                                                                     |
| **in-page channel** | page script ↔ panel             | same-origin, entirely in-browser: a handshaken `MessageChannel` port per panel, via [`devframe/in-page-channel`](/guide/in-page-channel) |

---
title: When Clauses
navigation:
  icon: i-lucide-git-branch
description: When clauses gate visibility and executability of docks, commands, and custom UI via VS Code's when-clause contexts. The evaluator whenexpr re-exports at devframe/utils/when.
---

When clauses gate visibility and executability of docks, commands, and custom UI via [VS Code's when-clause contexts](https://code.visualstudio.com/api/references/when-clause-contexts). The evaluator [`whenexpr`](https://github.com/antfu/whenexpr) re-exports at `devframe/utils/when`.

## Usage

### On commands

Gates palette visibility and shortcuts.

```ts
ctx.commands.register({
  id: 'my-devtool:embedded-only',
  title: 'Embedded-Only Action',
  when: 'clientType == embedded',
  handler: async () => { /* … */ },
})
```

### On dock entries

Gates dock-rail visibility.

```ts
ctx.docks.register({
  id: 'my-devtool:inspector',
  title: 'Inspector',
  type: 'action',
  icon: 'ph:cursor-duotone',
  when: 'clientType == embedded',
  action: { importFrom: 'my-devtool/inspector' },
})
```

### Render-only visibility on dock entries

A dock entry also takes `visibility`, a second expression that hides only its dock-rail button while keeping the entry registered and reachable (e.g. a `subTabs` anchor).

```ts
ctx.docks.register({
  id: 'my-devtool:anchor',
  title: 'My Devtool',
  type: 'iframe',
  icon: 'ph:squares-four-duotone',
  url: '/__my-devtool/',
  subTabs: { protocol: 'postmessage' },
  visibility: 'false', // hide the anchor's own button; its tabs still render
})
```

## Expression syntax

### Operators

| Category    | Operators                         | Example                    |
| ----------- | --------------------------------- | -------------------------- |
| Bare truthy | identifier                        | `dockOpen`                 |
| Literals    | `true`, `false`, numbers, strings | `42`, `'dev'`              |
| Unary       | `!`, `-`, `+`                     | `!paletteOpen`             |
| Logical     | `&&`, `\|\|`                      | `dockOpen && !paletteOpen` |
| Equality    | `==`, `!=`, `===`, `!==`          | `clientType == embedded`   |
| Relational  | `<`, `<=`, `>`, `>=`              | `count >= 10`              |
| Arithmetic  | `+`, `-`, `*`, `/`, `%`           | `(a + b) * c`              |
| Grouping    | `( … )`                           | `(a \|\| b)`               |

### Precedence (low → high)

`||` → `&&` → equality → relational → `+ -` → `* / %` → unary → primary.

### `==` vs `===`

- **`==` / `!=`**: VS Code idiom; RHS a single token, compared as a string.
- **`===` / `!==`**: JS strict equality; full expressions both sides, no coercion.

```ts
evaluateWhen('clientType == embedded', ctx) // string-style
evaluateWhen('count === 1', { count: 1 }) // true
evaluateWhen('count === 1', { count: '1' }) // false
```

### Examples

```ts
when: 'true' // always visible
when: 'false' // never visible
when: 'clientType == embedded' // only embedded
when: 'dockOpen && !paletteOpen' // dock open and palette closed
when: '(clientType == embedded && dockOpen) || clientType == standalone'
when: 'my-devtool.ready' // custom devframe context
```

## Built-in context variables

| Variable         | Type                         | Description                                                               |
| ---------------- | ---------------------------- | ------------------------------------------------------------------------- |
| `clientType`     | `'embedded' \| 'standalone'` | `embedded` in the host page's overlay, `standalone` in a separate window. |
| `dockOpen`       | `boolean`                    | Dock panel open.                                                          |
| `paletteOpen`    | `boolean`                    | Command palette open.                                                     |
| `dockSelectedId` | `string`                     | Selected dock entry ID; `''` if none.                                     |

## Namespaced context keys

Devframes add keys with `.` or `:`:

```ts
context['my-devtool.ready'] = true
context['my-devtool:step'] = 'build'
context.myDevtool = { ready: true, step: 'build' } // nested form
```

```ts
when: 'my-devtool.ready'
when: 'my-devtool:step == build'
when: 'myDevtool.ready'
```

### Lookup order

Resolves the exact key `ctx['my-devtool.ready']` first, then nested `ctx['my-devtool']?.ready`; flat wins.

## Type-safe `when` clauses

`defineCommand` and `defineDockEntry` type-check `when:` against `WhenContext`.

```ts
import { defineCommand } from 'devframe'

defineCommand({
  id: 'my-devtool:toggle',
  title: 'Toggle',
  when: 'dockOpen && !paletteOpen', // ✓ ok
  handler: async () => {},
})

defineCommand({
  id: 'my-devtool:broken',
  title: 'Broken',
  when: 'dockOpen &&& !paletteOpen',
  /** ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Type error: syntax error */
  handler: async () => {},
})
```

### Key validation with devframe contexts

The default `WhenContext` leaves devframe keys open-ended (`[key: string]: unknown`). To validate names, declare a narrower context and wrapper:

```ts
import type { WhenContext, WhenExpression } from 'devframe/utils/when'

interface MyPluginContext extends Omit<WhenContext, keyof any> {
  'clientType': 'embedded' | 'standalone'
  'dockOpen': boolean
  'paletteOpen': boolean
  'dockSelectedId': string
  'my-devtool.ready': boolean
}

function defineMyCommand<const W extends string>(cmd: {
  id: string
  title: string
  when?: WhenExpression<MyPluginContext, W>
  handler: (...args: any[]) => Promise<unknown>
}): typeof cmd {
  return cmd
}

defineMyCommand({
  id: 'my-devtool:toggle',
  title: 'Toggle',
  when: 'my-devtool.ready && dockOpen', // ✓ ok
  handler: async () => {},
})

defineMyCommand({
  id: 'my-devtool:broken',
  title: 'Broken',
  when: 'my-devtool.read', // ← typo
  //    ^^^^^^^^^^^^^^^^^^^ Type error: Unknown context key
  handler: async () => {},
})
```

## API reference

```ts
import type { WhenContext } from 'devframe/utils/when'
import { evaluateWhen, resolveContextValue } from 'devframe/utils/when'

const ctx: WhenContext = {
  'clientType': 'embedded',
  'dockOpen': true,
  'paletteOpen': false,
  'dockSelectedId': 'my-dock',
  'my-devtool.ready': true,
}

evaluateWhen('dockOpen && my-devtool.ready', ctx) // true
evaluateWhen('clientType == standalone', ctx) // false

resolveContextValue('my-devtool.ready', ctx) // true
```

### `evaluateWhen(expression, ctx, options?)`

Returns `boolean`; `{ strict: true }` throws on unknown keys.

### `resolveContextValue(key, ctx)`

Returns one (possibly namespaced) key's value.

### `WhenExpression<Ctx, S>`

The branded `whenexpr` expression type for typed `define*` helpers ([above](#key-validation-with-devframe-contexts)).

---
title: Events Reference
navigation:
  icon: i-lucide-radio-tower
description: Devframe carries change notifications through client contexts, node event buses, RPC, broadcasts, and shared state.
---

Devframe carries change notifications through client contexts, node event buses, RPC, broadcasts, and shared state.

Two prefixes mark the wire protocol: `hub:` for hub-layer server RPC (client → server), `devframe:` for the client-facing protocol (server → client). The internal event bus mirrors the subsystem vocabulary (`docks`, `terminals`, `messages`, `commands`): `docks:activate` fans out to `devframe:docks:activate`.

Each name lives in code: [`HUB_EVENTS`](https://github.com/devframes/devframe/blob/main/packages/hub/src/events.ts) (`@devframes/hub/constants`) backs the hub tables, [`DEVFRAME_EVENTS`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/events.ts) (`devframe/constants`) the core ones.

## Hub events

### Client-context events

Client scripts subscribe to these events on the client context inside the host page.

| Event                 | Emitter            | Payload                  |
| --------------------- | ------------------ | ------------------------ |
| `panel:state:changed` | `ctx.panel.events` | `DevframeDockPanelState` |

`ctx.panel.state` supplies the current snapshot when a client script loads. Later open, close, dock selection, and hub UI provider visibility changes emit `panel:state:changed`. The snapshot contains `state: 'open' | 'closed' | 'hidden'` and an optional `selectedDockId`.

### Internal node event bus

Each subsystem emits on `ctx.<subsystem>.events`, consumed **inside the same node process** by `createHubContext`, which fans them onto the wire.

| Event                                                                           | Emitted by                                                 | Consumed by                                                    | Payload                   |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------- | ------------------------- |
| `docks:entry:updated`                                                           | `DocksHost.register` / `update`                            | context → `devframe:docks` shared state                        | `DevframeDockUserEntry`   |
| `docks:activate`                                                                | `DocksHost.activate()`                                     | context → broadcast + `devframe:docks:active`                  | `DevframeDockActivation`  |
| `terminals:session:updated`                                                     | `TerminalsHost` register / update / remove / status change | context → `devframe:terminals:updated`; the terminals devframe | `DevframeTerminalSession` |
| `messages:added` / `messages:updated` / `messages:removed` / `messages:cleared` | `MessagesHost` mutations                                   | context → `devframe:messages:updated`; the messages devframe   | entry / entry / id / none |
| `commands:registered` / `commands:unregistered`                                 | `CommandsHost` register / update / unregister              | context → `devframe:commands` shared state                     | entry / id                |

### Server RPC methods (client → server)

| Method                    | Signature                                          | Purpose                                                                                     |
| ------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `hub:docks:activate`      | `({ dockId, params? }) => void`                    | Ask the hub UI provider to switch its active dock; see [Deep Linking](/guide/deep-linking). |
| `hub:commands:execute`    | `(id, ...args) => unknown`                         | Invoke a registered server command by id.                                                   |
| `hub:messages:add`        | `(input) => DevframeMessageEntry`                  | Add a message to the feed (marked `from: 'browser'`).                                       |
| `hub:messages:update`     | `(id, patch) => DevframeMessageEntry \| undefined` | Patch a message by id.                                                                      |
| `hub:messages:remove`     | `(id) => void`                                     | Remove a message by id.                                                                     |
| `hub:messages:clear`      | `() => void`                                       | Remove every message.                                                                       |
| `hub:terminals:write`     | `(id, data) => void`                               | Send input to an interactive PTY session.                                                   |
| `hub:terminals:resize`    | `(id, cols, rows) => void`                         | Resize an interactive PTY session.                                                          |
| `hub:terminals:terminate` | `(id) => void`                                     | Kill a session's process, keeping it registered.                                            |
| `hub:terminals:restart`   | `(id) => void`                                     | Re-run a session's command in place.                                                        |
| `hub:terminals:remove`    | `(id) => void`                                     | Kill a session's process and drop it from the registry.                                     |

### Broadcasts & shared state (server → client)

A hub-aware RPC client reads or subscribes via `rpc.client.register(...)`; the [client runtime](/guide/client-context) registers the `devframe:docks:activate` handler for you.

| Name                         | Kind              | Carries                                                                                        |
| ---------------------------- | ----------------- | ---------------------------------------------------------------------------------------------- |
| `devframe:docks:activate`    | broadcast         | Live "switch active dock" request; the client runtime calls its local `switchEntry`.           |
| `devframe:terminals:updated` | broadcast         | Terminal sessions changed; re-read terminal state.                                             |
| `devframe:messages:updated`  | broadcast         | Message list changed; re-read message state.                                                   |
| `devframe:docks`             | shared state      | Projected dock entry list (`DevframeDockEntry[]`).                                             |
| `devframe:docks:active`      | shared state      | Most recent `DevframeDockActivation`, so a dock that mounts in response still converges on it. |
| `devframe:commands`          | shared state      | Serializable command list, handlers stripped (`DevframeServerCommandEntry[]`).                 |
| `devframe:user-settings`     | shared state      | Persisted project-scope hub settings (`DevframeDocksUserSettings`).                            |
| `devframe:terminals`         | streaming channel | Live terminal output stream, keyed by session id.                                              |

### Same-origin `BroadcastChannel`s

Used on a `static` backend, where no live server can relay a client's request to its sibling browsing contexts.

| Name                      | Posted by                                                   | Carries                                                                                              |
| ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `devframe:docks:activate` | a panel iframe (e.g. the messages panel's activate actions) | The `{ dockId, params? }` activation; the client runtime in the host page switches the dock locally. |

## Core devframe events

This map covers notifications only; request/response RPC endpoints (`devframe:rpc:server-state:*`, `devframe:streaming:subscribe`, `anonymous:devframe:auth`, …) are typed in `types/rpc-augments.ts`, not events.

### Node event bus

Emitted on `ctx.agent.events`; adapters (e.g. the MCP server) re-publish their manifest.

| Event                                                       | Emitted by                                | Payload              |
| ----------------------------------------------------------- | ----------------------------------------- | -------------------- |
| `agent:manifest:changed`                                    | any tool/resource/provider change         | none                 |
| `agent:tool:registered` / `agent:tool:unregistered`         | `registerTool` / `unregisterTool`         | `AgentTool` / id     |
| `agent:resource:registered` / `agent:resource:unregistered` | `registerResource` / `unregisterResource` | `AgentResource` / id |

### RPC client connection events

Emitted on the RPC client's `rpc.events` (`RpcClientEvents`) to track connection lifecycle and errors.

| Event                    | Carries                                                         |
| ------------------------ | --------------------------------------------------------------- |
| `rpc:is-trusted:updated` | Trust gate flipped (`boolean`).                                 |
| `rpc:error`              | An RPC call rejected (`error`, `method`).                       |
| `connection:status`      | Connection status changed (`status`, `previous`).               |
| `connection:error`       | A connection-level error (WebSocket errored, or trust refused). |

### Broadcasts (server → client)

Pushed to subscribed RPC clients, wired by the core node side.

| Name                                | Carries                                                                        |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| `devframe:auth:revoked`             | This connection's bearer token was revoked; the RPC client drops to untrusted. |
| `devframe:rpc:client-state:updated` | Full shared-state snapshot for a key.                                          |
| `devframe:rpc:client-state:patch`   | Incremental shared-state patch for a key.                                      |
| `devframe:streaming:chunk`          | A streaming chunk for a subscribed channel/id.                                 |
| `devframe:streaming:end`            | A streaming terminator (optionally an error).                                  |
| `devframe:streaming:upload-cancel`  | Server-side cancel of an in-flight upload.                                     |

### In-page channel notifications (page script → panel)

Pushed over each panel's [in-page channel](/guide/in-page-channel) port; the paired request methods (`devframe:in-page:page-state:subscribe`/`set`/`patch`) are call endpoints defined at their handlers, not events.

| Name                                   | Carries                                           |
| -------------------------------------- | ------------------------------------------------- |
| `devframe:in-page:panel-state:updated` | Full channel shared-state snapshot for a key.     |
| `devframe:in-page:panel-state:patch`   | Incremental channel shared-state patch for a key. |

### `postMessage` channels

| Name                           | Posted by                                                                          | Carries                                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `devframe:remote-assets-error` | the remote-assets fallback page, to `window.parent`                                | The failed package/version/reason, so an embedding hub UI provider can replace the 502 page. |
| `devframe:in-page-channel`     | both [in-page channel](/guide/in-page-channel) endpoints, across window boundaries | The versioned handshake envelope (panel hello, page-script port grant).                      |

---
title: Node-Side API
navigation:
  icon: i-lucide-server-cog
description: 'Lookup tables for the node side: DevframeDefinition fields, CLI options, storage scopes, RPC function types, broadcast options, streaming lifecycle, remote assets, the cross-devframe services surface, diagnostics prefixes, and the auth surface.'
---

Lookup tables for a devframe's node side. Each section links the guide page that teaches the concept.

## Definition fields

The fields of a `DevframeDefinition`: [Devframe Definition](/guide/devframe-definition).

| Field                 | Type                                              | Description                                                                                                                                                                                                                                                   |
| --------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | `string`                                          | **Required.** Unique namespaced id (kebab-case); prefixes RPC/dock/MCP-tool names.                                                                                                                                                                            |
| `name`                | `string`                                          | **Required.** Display name (dock, agent manifests).                                                                                                                                                                                                           |
| `version`             | `string`                                          | **Required.** Semver; shown in hub UIs, diagnostics.                                                                                                                                                                                                          |
| `packageName`         | `string`                                          | **Required.** npm package (`@scope/my-tool`).                                                                                                                                                                                                                 |
| `importMetaUrl`       | `string`                                          | **Recommended.** Pass `import.meta.url`, the deps resolution base: default `resolveFrom` for [remote assets](/guide/client-assets) and declared [services](/guide/services#wire-services).                                                                    |
| `homepage`            | `string`                                          | **Required.** Homepage/docs URL.                                                                                                                                                                                                                              |
| `description`         | `string`                                          | **Required.** One-line summary.                                                                                                                                                                                                                               |
| `icon`                | `string \| { light, dark }`                       | Optional Iconify name, image URL, light/dark pairs, etc. See [Icon values](#icon-values).                                                                                                                                                                     |
| `basePath`            | `string`                                          | Optional mount-path override. Default `/` standalone (`cli`/`build`), `/__<id>/` hosted (`vite`/`embedded`).                                                                                                                                                  |
| `duplicationStrategy` | `'warn' \| 'silent' \| 'throw' \| 'duplicate'`    | Hub reaction when another devframe shares this `id`. Default `'warn'`. See [Duplication strategies](/references/hub-api#duplication-strategies); standalone adapters ignore it.                                                                               |
| `capabilities`        | `{ dev?, build? }`                                | Per-runtime feature flags. `boolean` = whole runtime; object = individual features.                                                                                                                                                                           |
| `services`            | `DevframeServiceInput[]`                          | Wire services consumed: descriptors (`{ package, version?, required?, options? }`) imported against the devframe's own deps, or ready definitions. See [Cross-Devframe Services](/guide/services#wire-services).                                              |
| `clientAssets`        | `string \| RemoteAssets`                          | Built SPA served as the UI: local dist dir or [remote assets](/guide/client-assets). Read by every UI-serving adapter (`dev`, `build`, `vite`, `next`, hub).                                                                                                  |
| `rpc`                 | `{ snapshot?: (string \| { method, inputs })[] }` | RPC config. `rpc.snapshot` opts an RPC this devframe doesn't own into the static dump. Bare method id bakes the no-arg call; `{ method, inputs }` bakes one record per argument-tuple (`inputs` = tuples or async `(ctx) => tuples`). First tuple = fallback. |
| `setup`               | `(ctx, info?) => void \| Promise<void>`           | **Required.** Server-side entry point, run in every runtime. Optional 2nd arg carries runtime metadata, notably parsed CLI `flags` under `createCac`.                                                                                                         |
| `cli`                 | `DevframeCliOptions`                              | CLI adapter defaults. See [CLI options](#cli-options).                                                                                                                                                                                                        |

## Icon values

The `icon` field, and every dock entry, command, and terminal icon, accept the same string forms. A `{ light, dark }` pair picks the matching variant per active color scheme, and each side takes any of these forms:

| Form            | Example                                                      | Rendered as                                                                      |
| --------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Iconify name    | `ph:gauge-duotone`, `logos:nuxt-icon`                        | the `collection:icon` glyph, fetched from Iconify as inline SVG                  |
| Image URL       | `/icons/logo.svg`, `https://example.com/logo.png`            | an `<img>`; relative URLs resolve against the supplying hub                      |
| Data URL        | `data:image/svg+xml,%3Csvg…%3E`                              | an inline `<img>` from the embedded data                                         |
| SVG mask        | `mask:/icons/logo.svg`, `mask:data:image/svg+xml,%3Csvg…%3E` | an alpha mask tinted with `currentColor`, following the surrounding text color   |
| Light/dark pair | `{ light: './logo-light.svg', dark: './logo-dark.svg' }`     | the variant matching the active color scheme; each side is any string form above |

The reference hub UI and terminal SPA render `mask:` icons with the surrounding text color, preserving the image's shape and opacity, so a bundled monochrome SVG follows the dock's foreground color through selected and dimmed states. For a bundled SVG, use ```mask:data:image/svg+xml,${encodeURIComponent(svg)}```. A mask produces one color; use an ordinary image URL for multicolor artwork. Relative mask URLs on dock entries resolve against the supplying hub's URL. Custom hub UI providers implement this string convention in their own icon renderer.

## CLI options

The `cli` field's `DevframeCliOptions`: [CLI options](/guide/devframe-definition#cli-options).

| Field       | Type                 | Description                                                                                          |
| ----------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
| `command`   | `string`             | Binary name in `--help`. Default: the `id`.                                                          |
| `port`      | `number`             | Preferred dev-server port.                                                                           |
| `portRange` | `[number, number]`   | Port scan range (`get-port-please`).                                                                 |
| `random`    | `boolean`            | Prefer a random open port.                                                                           |
| `host`      | `string`             | Default bind host.                                                                                   |
| `open`      | `boolean \| string`  | `true` = origin, string = a path, `false` = off (`--open`/`--no-open`). With `auth`, embeds the OTP. |
| `auth`      | `boolean`            | Disable WS trust flow when localhost-only, single-user. Default `true`.                              |
| `configure` | `(cli: CAC) => void` | Contribute flags/commands before `createCac`'s `configureCli`.                                       |

## Storage scopes

The three classes `ctx.host.getStorageDir(scope)` places persisted state in: [Storage scopes](/guide/devframe-definition#storage-scopes).

| Scope       | Placement                                           | For                                |
| ----------- | --------------------------------------------------- | ---------------------------------- |
| `workspace` | committable, `<workspaceRoot>/.devframe/`           | team-shared: saved presets, config |
| `project`   | per-checkout, `<cwd>/node_modules/.<app>/devframe/` | caches, personal settings          |
| `global`    | per-user, `~/.<app>/devframe/`                      | auth tokens, machine-wide prefs    |

## RPC function types

The `type` field of `defineRpcFunction`: [RPC](/guide/rpc).

| Type     | Description                                | Cached                 | Static Dump             |
| -------- | ------------------------------------------ | ---------------------- | ----------------------- |
| `query`  | Read operation that can change over time.  | Opt-in via `cacheable` | Manual (declare `dump`) |
| `static` | Data that never changes for a given input. | Indefinitely           | Automatic               |
| `action` | Mutation with side effects.                | Never                  | Never                   |
| `event`  | Fire-and-forget; no response.              | Never                  | Never                   |

## Broadcast options

The options of `rpc.broadcast`: [Broadcasting](/guide/rpc#broadcasting).

| Option     | Type                  | Description                                |
| ---------- | --------------------- | ------------------------------------------ |
| `method`   | browser-side RPC name | Browser-side function to call.             |
| `args`     | any                   | Arguments for the browser-side function.   |
| `optional` | `boolean`             | Don't throw if no RPC client is listening. |
| `event`    | `boolean`             | Fire-and-forget.                           |
| `filter`   | `(client) => boolean` | Skip specific RPC clients.                 |

## Streaming lifecycle

How each lifecycle event lands on both sides of a streaming channel: [Streaming](/guide/streaming#lifecycle-and-cancellation).

| Event                                  | Node side                                            | Browser side                              |
| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| `stream.close()` / `stream.error(err)` | broadcasts `end`                                     | `for await` resolves or throws            |
| `reader.cancel()`                      | aborts `stream.signal` on **last**-subscriber cancel | `for await` ends                          |
| WS disconnects                         | aborts `stream.signal` on **last**-subscriber drop   | reader survives, resubscribes on re-trust |
| `chat` panel closes                    | cancels upstream                                     | none                                      |

## Remote assets options

The fields of a `RemoteAssets` source for `clientAssets` and `hostStatic`: [Remote assets](/guide/client-assets#remote-assets).

| Field         | Purpose                                                                               |
| ------------- | ------------------------------------------------------------------------------------- |
| `package`     | npm package with the built assets.                                                    |
| `version`     | Exact version, usually your `pkg.version`.                                            |
| `resolveFrom` | Local-path resolution base. Defaults to `importMetaUrl`; `null` skips to cache + CDN. |
| `path`        | Subpath the assets live under (default `dist`).                                       |
| `provider`    | `'jsdelivr'` (default), `'unpkg'`, or a custom provider (internal mirror).            |
| `offline`     | `true` serves only from local install or cache, never network.                        |

## `DevframeServicesHost`

The methods on `ctx.services`: [Cross-Devframe Services](/guide/services#the-devframeserviceshost-api).

| Method          | Signature                                        | Role                                                                                                                                                                                        |
| --------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provide`       | `(id, service) => revoke`                        | Publish an in-process service under a namespaced id. Throws [`DF0037`](/errors/DF0037) if the id is taken.                                                                                  |
| `get`           | `(id) => service \| undefined`                   | The service currently provided under `id` (augmented type, else `unknown`).                                                                                                                 |
| `has`           | `(id) => boolean`                                | Whether a service is provided under `id`.                                                                                                                                                   |
| `whenAvailable` | `(id, cb) => unsubscribe`                        | Run `cb` as soon as the service exists (now if provided, else on `provide`), and re-fire on revoke/re-provide.                                                                              |
| `keys`          | `() => string[]`                                 | Ids of every currently-provided service.                                                                                                                                                    |
| `install`       | `(input, options?) => Promise<api \| undefined>` | Install a [wire service](#wire-service-definition-fields) at runtime (the dynamic escape hatch; the common path is declarative). `options.resolveFrom` is the descriptor's resolution base. |
| `ready`         | `() => Promise<void>`                            | **Internal.** Construct every queued wire service before any `setup` runs. Adapters call it; application code uses declarative `services`.                                                  |

## Service tiers

The two tiers a service can take: [Cross-Devframe Services](/guide/services).

| Tier                                                                               | Shared how                  | Registers RPC          | Advertised to clients                     |
| ---------------------------------------------------------------------------------- | --------------------------- | ---------------------- | ----------------------------------------- |
| In-process service (`provide`/`get`)                                               | live object, node side only | No                     | No                                        |
| [Wire service](/guide/services#wire-services) (`install` / declarative `services`) | npm package, node API + RPC | Yes, under its `scope` | Yes, via `devframe:services` shared state |

## Wire-service definition fields

The fields of a `DevframeServiceDefinition` returned by a service package's `create<X>Service` factory: [Shipping a wire service](/guide/services#shipping-one).

| Field          | Type                           | Description                                                                                                                        |
| -------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `package`      | `string`                       | **Required.** npm package name, also its registry key (`ctx.services.has(pkg)`).                                                   |
| `version`      | `string`                       | **Required.** Semver; advertised to clients, checked against declared ranges.                                                      |
| `scope`        | `string`                       | **Required.** RPC namespace its functions register under (e.g. `devframes:service:open`); `setup` gets a context pre-scoped to it. |
| `meta`         | `Record<string, unknown>`      | Extra advertised metadata (feature flags, defaults). Must be JSON-serializable.                                                    |
| `options`      | `Options`                      | This instance's own option set, baked in by its factory; joins the merge.                                                          |
| `mergeOptions` | `(sets: Options[]) => Options` | Merge multiple installers' option sets. Default: shallow, later wins.                                                              |
| `setup`        | `(ctx, info) => api`           | **Required.** Register RPC on the pre-scoped context; return the node API served from `ctx.services.get(package)`.                 |

## Wire-service descriptor fields

The declarative reference form on `DevframeDefinition.services` / `initHub({ services })`: [Declaring services](/guide/services#declaring).

| Field      | Type      | Description                                                                                                                                                        |
| ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `package`  | `string`  | **Required.** npm package name; its default export is the factory the host imports.                                                                                |
| `version`  | `string`  | Accepted semver range. Unsatisfied warns ([`DF0069`](/errors/DF0069)), or throws ([`DF0068`](/errors/DF0068)) when `required`.                                     |
| `required` | `boolean` | Fail hard on a missing package ([`DF0067`](/errors/DF0067)) or unsatisfied range. Default `false`: a missing service is skipped and clients see `has() === false`. |
| `options`  | `Options` | Option set this installer contributes to the merge.                                                                                                                |

## Advertised service meta

Each installed service's entry in the `devframe:services` [shared state](/guide/shared-state), mirrored to RPC clients as `rpc.services`: [Feature-detecting on the RPC client](/guide/services#feature-detecting-on-the-rpc-client).

| Field     | Description                             |
| --------- | --------------------------------------- |
| `package` | npm package name, the registry key.     |
| `version` | Installed version of the service.       |
| `scope`   | RPC namespace its functions live under. |
| `meta`    | Extra service-declared metadata.        |

## Diagnostic code prefixes

Prefixes in use across the ecosystem: [Structured Diagnostics](/guide/diagnostics#code-conventions).

| Prefix | Owner                              |
| ------ | ---------------------------------- |
| `DF`   | `devframe`                         |
| `DTK`  | `@vitejs/devtools` (Vite-specific) |
| `RDDT` | `@vitejs/devtools-rolldown`        |
| `VDT`  | `@vitejs/devtools-vite` (reserved) |

## Auth methods

The wire-level RPC methods of the trust handshake: [Security](/guide/security#authentication-flow).

| RPC method                             | Direction       | Shape                                                                                                              |
| -------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------ |
| `anonymous:devframe:auth`              | client → server | `{ authToken, ua, origin }` → `{ isTrusted }`: re-authenticate a stored token                                      |
| `anonymous:devframe:auth:exchange`     | client → server | `{ code, ua, origin }` → `{ authToken \| null }`: exchange a code for a token                                      |
| `anonymous:devframe:auth:request-code` | client → server | `{ ua, origin, reissue? }` → print the code banner in the server terminal (`reissue: true` rotates the code first) |
| `devframe:auth:revoke`                 | client → server | self-revoke the caller's own token                                                                                 |
| `devframe:auth:revoked`                | server → client | event: token revoked                                                                                               |

## Node auth primitives

The building blocks in `devframe/node/auth`: [Security](/guide/security#the-ready-made-layer).

| Function                                                       | Role                                                                            |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `getTempAuthCode()` / `refreshTempAuthCode()`                  | read / rotate the one-time code                                                 |
| `exchangeTempAuthCode(code, session, { ua, origin }, storage)` | verify a code, mint + store the token, trust the session, return it (or `null`) |
| `verifyAuthToken(token, session, storage)`                     | trust a session presenting a known token                                        |
| `buildOtpAuthUrl(origin, code?)`                               | build a magic-link URL embedding the code                                       |
| `revokeAuthToken(context, storage, token)`                     | delete a token and disconnect sessions using it                                 |

## MCP CLI commands

The agent-facing CLI surface: [Agent-Native Devframe](/guide/agent-native).

| Command                | Description                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| `<your-app> mcp`       | Start the MCP server on `stdio`.                                                                               |
| `<your-app> dev --mcp` | Serve the agent-consumable API on `/__mcp`.                                                                    |
| `devframe connect`     | Discover running devframes and proxy their tools; see [MCP adapter](/adapters/mcp#discovery-devframe-connect). |

---
title: Browser-Side API
navigation:
  icon: i-lucide-globe
description: 'Lookup tables for the browser side: connectDevframe options, RPC client events, connection statuses, and in-page channels error codes.'
---

Lookup tables for a devframe's browser side. Each section links the guide page that teaches the concept.

## connectDevframe options

The options of `connectDevframe()` / `getDevframeRpcClient()`: [Client](/guide/client).

| Option           | Description                                                                                                                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection`     | Connection prepared by `setupDevframeConnection()`.                                                                                                                                                                                               |
| `baseURL`        | Mount path to probe for `__connection.json` (array = fallback). Default `'./'` (relative to `document.baseURI`); use an absolute path (`'/__devframe/'`) from outside the SPA.                                                                    |
| `authToken`      | Override the auth token (default: a locally-persisted id).                                                                                                                                                                                        |
| `cacheOptions`   | `true` for default caching, or an options object.                                                                                                                                                                                                 |
| `callTimeout`    | Ms before a pending `rpc.call` rejects with a `'timeout'` `DevframeConnectionError`; `0`/omit = wait forever.                                                                                                                                     |
| `wsOptions`      | Transport overrides: `onConnected` / `onError` / `onDisconnected` hooks, socket URL.                                                                                                                                                              |
| `rpcOptions`     | Forwarded to `birpc`.                                                                                                                                                                                                                             |
| `connectionMeta` | Descriptor that skips the `__connection.json` fetch.                                                                                                                                                                                              |
| `webmcp`         | Mirror `agent`-flagged client RPC functions onto the page's WebMCP model context as tools; `false` opts out. Default `true` (applies only when the browser provides one). See [Agent-Native](/guide/agent-native#browser-side-tools-over-webmcp). |

## RPC client events

Emitted over `rpc.events`: [Events](/guide/client#events).

| Event                    | Fires when                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| `rpc:is-trusted:updated` | Trust granted, denied, or revoked. Carries the new `isTrusted` boolean.                    |
| `connection:status`      | The [connection status](#connection-statuses) changes. Carries `(status, previous)`.       |
| `connection:error`       | A connection-level failure: socket error or trust refused. Carries the `Error`.            |
| `rpc:error`              | An `rpc.call` rejects, from the node side or a down connection. Carries `(error, method)`. |

## Connection statuses

The values of `rpc.status`: [Handling connection and auth errors](/guide/client#handling-connection-and-auth-errors).

| Status         | Meaning                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `connecting`   | Establishing socket / handshake. Calls queue until open.                                                    |
| `connected`    | Socket open and trusted; calls are served.                                                                  |
| `unauthorized` | Socket open, trust refused. Prompt for [authentication](/guide/client#authenticating-with-a-one-time-code). |
| `disconnected` | Socket closed (dropped mid-session or never opened).                                                        |
| `error`        | Fatal: the socket errored or connection meta couldn't load.                                                 |

## In-page channel endpoints

The browser-only endpoint methods of the [in-page channel](/guide/in-page-channel). `emit()` sends to the opposite endpoint; `on()` handles events arriving from that endpoint.

`InPageChannelProtocol` separates `functions` and `events`. Each section has optional `pageScript` and `panel` maps naming the receiving direction. Endpoint options require a complete `functions` map with handlers; `events` is optional, and when provided can include optional handlers (use `{}` to declare an event without a handler for `channel.on()`). `call()` uses function names regardless of return type, while `emit()` and `on()` use event names. A function returning `void` or `Promise<void>` remains an awaitable request/response call.

| Method or property    | Page-script endpoint                                                      | Panel endpoint                                                                    |
| --------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `emit(name, ...args)` | Fans an event out to every connected panel.                               | Sends an event to the page script, buffering while connecting.                    |
| `on(name, listener)`  | Subscribes to events emitted by a panel. Returns an unsubscribe function. | Subscribes to events emitted by the page script. Returns an unsubscribe function. |
| `call(name, ...args)` | Available through a specific `PanelPeer`.                                 | Calls a page-script function and awaits its result.                               |
| `events`              | Local `panel:connected` / `panel:disconnected` lifecycle events.          | Local `status:updated` lifecycle event.                                           |
| `sharedState`         | Owns the authoritative state.                                             | Mirrors the page-script state.                                                    |

## In-page channel error codes

The `error.code` values of `InPageChannelError`: [Errors and fallbacks](/guide/in-page-channel#errors-and-fallbacks).

| Code                  | When                                                                          | What to do                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `timeout`             | A call outlived `callTimeoutMs` (default 15s), or `whenConnected(ms)` expired | The message carries the endpoint status: `connecting` usually means the page script isn't loaded in this context |
| `closed`              | The endpoint was closed with calls pending                                    | Expected during teardown                                                                                         |
| `not-serializable`    | A `jsonSerializable: true` payload contained a non-JSON value                 | The message names the offending path (e.g. `its arguments[0].nodes[2]` is a Map)                                 |
| `not-cloneable`       | The port refused to clone a payload (`DataCloneError`)                        | Strip functions/DOM nodes/reactivity proxies, or declare `jsonSerializable: true` for the precise error above    |
| `invalid-args`        | Incoming arguments failed their Standard-Schema validation                    | The message lists the schema issues                                                                              |
| `state-uninitialized` | The page script read a shared state before providing its `initialValue`       | Initialize on first access                                                                                       |

---
title: Hub API
navigation:
  icon: i-lucide-layout-dashboard
description: 'Lookup tables for the hub: subsystems, launcher fields, duplication strategies, dock categories, the hub UI protocol, the namespace routes, the client runtime, the client context, and dock entry types.'
---

Lookup tables for `@devframes/hub`: its node-side subsystems and its browser-side client runtime. Each section links the guide page that teaches the concept.

## Hub subsystems

What `DevframeHubContext` adds to `DevframeNodeContext`: [Hub](/guide/hub).

| Subsystem       | API                                              | Purpose                                                                                                                                                                                  |
| --------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ctx.docks`     | `register / update / values / activate`          | Dock entries (iframes, launchers, custom-render) and groups; `activate(dockId, params?)` sets the active dock ([Cross-iframe dock activation](/guide/hub#cross-iframe-dock-activation)). |
| `ctx.terminals` | `register / startChildProcess / startPtySession` | Aggregate terminal sessions, streaming output ([Terminals](/add-ons/devframes/terminals#hub-aggregation)).                                                                               |
| `ctx.messages`  | `add / update / remove / clear`                  | Server-side toast/notification queue (FIFO, capped at 1000).                                                                                                                             |
| `ctx.commands`  | `register / execute / list`                      | Hierarchical command palette with keybindings and `when` clauses.                                                                                                                        |

## Launcher fields

The optional `launcher` fields that make a `type: 'launcher'` dock entry a live process controller: [Process-control launchers](/guide/hub#process-control-launchers).

| Field               | Purpose                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `command`           | Bound command id; out-of-process hub UI providers dispatch via `hub:commands:execute` (register a handler via `ctx.commands`). |
| `terminalSessionId` | Tracked session id; a "view in terminal" action calls `hub:docks:activate` with the terminals dock id and `{ sessionId }`.     |
| `digest`            | Latest progress line, shown inline; patch via `docks.update()`.                                                                |

## Duplication strategies

The `duplicationStrategy` values deciding what happens when a devframe shares an already-mounted `id`: [Duplicate devframes](/guide/hub#duplicate-devframes).

| Strategy           | Behavior                                                                           |
| ------------------ | ---------------------------------------------------------------------------------- |
| `'warn'` (default) | Keep the first, drop the later, emit `DF8105`.                                     |
| `'silent'`         | Drop the later one without warning.                                                |
| `'throw'`          | Throw `DF8105`.                                                                    |
| `'duplicate'`      | Every instance coexists under a disambiguated dock id (`my-tool`, `my-tool-2`, …). |

## Dock categories

`DEFAULT_CATEGORIES_ORDER` (from `@devframes/hub`, `/node`, `/client`, `/constants`) names the default dock-rail buckets: [The dual role of `category`](/guide/hub#the-dual-role-of-category).

| Category      | Weight | Typical use                  |
| ------------- | ------ | ---------------------------- |
| `framework`   | `-100` | Framework internals.         |
| `default`     | `0`    | Uncategorized.               |
| `app`         | `100`  | App tools.                   |
| `ui`          | `150`  | Components, styling.         |
| `data`        | `250`  | State, storage, queries.     |
| `web`         | `300`  | Network, platform, a11y.     |
| `performance` | `350`  | Profiling, metrics.          |
| `advanced`    | `400`  | Power-user tools.            |
| `docs`        | `500`  | Documentation.               |
| `~builtin`    | `1000` | Built-in views; always last. |

## Hub UI protocol

The shared-state keys and RPC methods a hub UI provider renders from: [The hub UI protocol](/guide/hub#the-hub-ui-protocol).

| Channel                               | Type                            | What it carries                                                                 |
| ------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------- |
| `devframe:docks` shared state         | `DevframeDockEntry[]`           | Every registered dock entry.                                                    |
| `devframe:commands` shared state      | `DevframeServerCommandEntry[]`  | Serializable command list (handlers stripped).                                  |
| `devframe:user-settings` shared state | `DevframeDocksUserSettings`     | Persisted project-scope hub settings.                                           |
| `devframe:docks:active` shared state  | `DevframeDocksActiveState`      | Most recent [dock activation](/guide/hub#cross-iframe-dock-activation) request. |
| `hub:commands:execute` RPC            | `(id, ...args) => unknown`      | Server-side command dispatch.                                                   |
| `hub:docks:activate` RPC              | `({ dockId, params? }) => void` | Switch the active dock.                                                         |

## Hub namespace routes

What `initHub()` serves under its `base`: [The namespace](/guide/hub-initiate#the-namespace).

| Path                  | Serves                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `/`                   | the `ui.viewer` SPA, or index document when headless                                                  |
| `<id>/`               | each devframe's SPA + own `__connection.json` → shared socket                                         |
| `embedded.js`         | the `ui.embedded` bootstrap (`404` if none)                                                           |
| `__connection.json`   | meta for the shared RPC socket                                                                        |
| `__ws`                | WebSocket upgrade route                                                                               |
| `__index.json`        | machine-readable index: mounted devframes, endpoints                                                  |
| `__client-imports.js` | dock client-script import map for hub UI providers                                                    |
| `__mcp`               | aggregate MCP endpoint over the tool registry (`mcp: 'auto'` default: mounted once agent tools exist) |

## `buildHub` options

The options of `buildHub()` from `@devframes/hub/build`: [Static builds](/guide/hub-initiate#static-builds). `devframes`, `services`, `rpcDeclarations`, `configure`, `ui`, `renderers`, `name`, `version`, `cwd`, and `getStorageDir` carry the same contracts as their `initHub` counterparts.

| Option    | Purpose                                                                                                                                                                                                                                                                                                    |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outDir`  | Output directory for the hub subtree; corresponds to `base` at serve time (build `base: '/__devframes/'` into `dist/__devframes`). A mount served outside the hub base (a devframe SPA or asset dir kept as a sibling of it) is written to this directory's parent (the deploy root) by its absolute path. |
| `base`    | Mount base baked into every absolute URL the build emits. Default `/__devframes/`.                                                                                                                                                                                                                         |
| `context` | An already-mounted `DevframeHubContext` to bake instead of `devframes` (the build counterpart of `initHub({ context })`); reads `ctx.frames` and `ctx.views.buildStaticDirs`. Mutually exclusive with `devframes`.                                                                                         |
| `clean`   | Remove `outDir` before writing. Default `true`; set `false` to bake beside an app's own build output.                                                                                                                                                                                                      |
| `pretty`  | Pretty-print RPC dump JSON shards. Default `false` (minified).                                                                                                                                                                                                                                             |

## Client runtime options

The options of `createDevframeClientRuntime()`: [The client runtime](/guide/client-context#the-client-runtime).

| Option              | Description                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `rpc`               | An already-connected `DevframeRpcClient`; when omitted, created via `connectDevframe(connect)`.                                               |
| `connect`           | Forwarded to `connectDevframe` when `rpc` is omitted (e.g. `baseURL`).                                                                        |
| `clientType`        | `'standalone'` (default) owns the page; `'embedded'` runs inside a user app alongside a panel.                                                |
| `loadClientScripts` | Import and run dock client scripts (default `true`).                                                                                          |
| `renderers`         | Dock renderers registered at boot, keyed by dock `type`; local wins over the hub's [renderer manifest](/guide/hub-initiate#renderer-modules). |

## Client context properties

The properties of `DevframeClientContext`: [The client context](/guide/client-context#the-client-context).

| Property     | Description                                                                                                                                                                                                                                                                                                                  |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rpc`        | The [RPC client](/guide/client): server/client functions, shared state.                                                                                                                                                                                                                                                      |
| `clientType` | `'embedded'` (inside the user app) or `'standalone'` (independent hub page).                                                                                                                                                                                                                                                 |
| `docks`      | `entries`, `selected`, `groupedEntries`, `switchEntry()`, `toggleEntry()`, `getStateById()`, `register()` / `update()` for [client-only docks](/guide/client-context#client-only-docks).                                                                                                                                     |
| `panel`      | Current `state`, local `events`, session, position, size, and drag/resize state for the dock panel.                                                                                                                                                                                                                          |
| `commands`   | Command palette: `register()`, `execute()`, `getKeybindings()`, `paletteOpen`, `paletteScopeId`, `openPalette(atCommandId?)`. Passing an id opens the palette drilled into that command's children ([Activating a group](/guide/hub#activating-a-group)).                                                                    |
| `renderers`  | Dock-renderer registry: `register()`, `get()`, `has()`, `mount(entry, container)`. Routes a dock `type` to a renderer (local boot or the hub's [manifest](/guide/hub-initiate#renderer-modules); local wins). `mount()` resolves a `status`: `mounted` (with `dispose`), `missing-renderer`, or `load-error` (with `error`). |
| `when`       | The [when-clause](/references/when-clauses) context.                                                                                                                                                                                                                                                                         |
| `connection` | Live [connection status](/guide/client#handling-connection-and-auth-errors): `status`, `error`, `events`.                                                                                                                                                                                                                    |

## Dock client script fields

Which `ClientScriptEntry` field carries an entry's client script, and when it runs: [Dock client scripts](/guide/client-context#dock-client-scripts).

| Entry kind      | Field                     | Runs                                     |
| --------------- | ------------------------- | ---------------------------------------- |
| `action`        | `action`                  | when the dock button is activated        |
| `custom-render` | `renderer`                | to render the entry's panel              |
| `iframe`        | `clientScript` (optional) | inside the host page on first activation |

`ClientScriptEntry.eager` defaults to `false`. Set it to `true` on an `iframe` `clientScript` or an `action` to initialize it after RPC trust, before dock activation. A `custom-render` `renderer` needs its mounted panel, so it always initializes on activation regardless of `eager`. Setup is cached per RPC connection and dock; action clicks execute on every activation.

## Frame-nav messages

The origin-locked `postMessage` protocol on `devframe:frame-nav`: [Shared-iframe soft navigation](/guide/client-context#shared-iframe-soft-navigation).

| Message              | Direction          | Meaning                                                               |
| -------------------- | ------------------ | --------------------------------------------------------------------- |
| `ready` / `manifest` | iframe → host page | tab list (`{ tabs, current }`), on load and change                    |
| `navigate`           | host page → iframe | show a view (`{ tabId, navTarget }`); the SPA routes client-side      |
| `navigated`          | iframe → host page | the SPA navigated internally; the hub UI provider highlights the dock |

## Dock entry types

The built-in variants of the open dock union (`DevframeDockEntryRegistry`, `@devframes/hub/types`) a hub UI provider renders: [Build Your Own Hub UI](/guide/build-your-own-hub-ui). Each entry's `icon` takes any of the [icon values](/references/node-api#icon-values). Each entry's `title` has an optional `titleLocales` map of translations, resolved with `resolveTitle(entry, locale)` from `@devframes/hub/client`; commands and launchers carry the same pair.

| Type            | The hub UI provider renders                                                                                                                                                                                                             |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iframe`        | the entry's `url` in a kept-alive iframe (per `frameId` when shared); honor `subTabs` soft nav; show the existing address bar with `addressBar: true`, or configure Back, Reload, and Open externally by passing an `addressBar` object |
| `action`        | a dock-rail button; activating runs its client script                                                                                                                                                                                   |
| `custom-render` | a container its client script mounts into                                                                                                                                                                                               |
| `launcher`      | a launch call-to-action reflecting `launcher.status`                                                                                                                                                                                    |
| `group`         | one dock-rail button collapsing its member entries                                                                                                                                                                                      |
| `~builtin`      | your native views (settings, feeds) for reserved ids                                                                                                                                                                                    |

---
title: Utilities
navigation:
  icon: i-lucide-wrench
description: Small, stable helpers under devframe/utils/*, bundled in, no npm install.
---

Small, stable helpers under `devframe/utils/*`, bundled in, no `npm install`.

## Reference

### `devframe/utils/colors`

Terminal ANSI colors.

```ts
import { colors as c } from 'devframe/utils/colors'

console.log(c.green('Server ready'))
console.log(c.cyan`listening on port ${port}`)
console.log(`${c.bold(c.red('fatal:'))} something went wrong`)
```

Exports `colors` (`blue`, `cyan`, `gray`, `green`, `red`, `yellow`, `bold`, `dim`, `reset`, `underline`).

### `devframe/utils/open`

Open a URL, file, or target in the OS handler.

```ts
import { open } from 'devframe/utils/open'

await open('https://localhost:7777')
await open('./report.html', { wait: true })
```

### `devframe/utils/launch-editor`

Open a file in the editor. Target accepts `file`, `file:line`, or `file:line:column`; an editor command (e.g. `'code'`) overrides auto-detection.

```ts
import { launchEditor } from 'devframe/utils/launch-editor'

launchEditor('src/main.ts:42:7')
launchEditor('src/main.ts:42:7', 'code')
```

Auto-detection reads `LAUNCH_EDITOR`, else defaults; most reach it through the [`open` service](/add-ons/services/open).

### `devframe/utils/hash`

Deterministic hash of any structured-cloneable value.

```ts
import { hash } from 'devframe/utils/hash'

const key = hash({ functionName, args })
```

### `devframe/utils/structured-clone`

JSON-safe structured-clone serialization; round-trips `Map`, `Set`, `Date`, `BigInt`, cycles, class instances.

```ts
import {
  structuredCloneDeserialize,
  structuredCloneParse,
  structuredCloneSerialize,
  structuredCloneStringify,
} from 'devframe/utils/structured-clone'

const wire = structuredCloneStringify(new Map([['a', 1]]))
const value = structuredCloneParse<Map<string, number>>(wire)
```

### `devframe/utils/nanoid`

URL-safe random ID generator (vendored, zero-dep).

```ts
import { nanoid } from 'devframe/utils/nanoid'

nanoid() // 21 chars
nanoid(10) // 10 chars
```

### `devframe/utils/crypto-token`

Cryptographically-secure token helpers on WebCrypto (browser + Node).

```ts
import { randomDigits, randomToken, timingSafeEqual } from 'devframe/utils/crypto-token'

randomToken() // 32-char hex, 128 bits of entropy; use as a bearer token
randomDigits(6) // '047204', uniform, leading zeros preserved
timingSafeEqual(input, secret) // constant-time string comparison
```

### `devframe/utils/debounce`

Promise-aware debounce, bundled in so integrations reuse it without adding a `perfect-debounce` dependency.

```ts
import { debounce } from 'devframe/utils/debounce'

const save = debounce((state: State) => write(state), 100)
save(next) // coalesces bursts; returns a promise, plus `.cancel()` / `.flush()` / `.isPending()`
```

### `devframe/utils/events`

Typed event emitter.

```ts
import { createEventEmitter } from 'devframe/utils/events'

const events = createEventEmitter<{ change: (n: number) => void }>()
const off = events.on('change', n => console.log(n))
events.emit('change', 42)
off()
```

### `devframe/utils/shared-state`

The immutable state container behind `ctx.rpc.sharedState` ([Shared State](/guide/shared-state)); usable outside a running devframe.

```ts
import { createSharedState } from 'devframe/utils/shared-state'

const state = createSharedState({ initialValue: { count: 0 } })
state.mutate((draft) => {
  draft.count += 1
})
state.value() // => count is 1
```

### `devframe/utils/url`

URL path-joining and slash-normalization helpers (browser-safe, zero-dep).

```ts
import { joinURL, withBase, withProtocol, withTrailingSlash } from 'devframe/utils/url'

joinURL('/__devframe', '__renderers', 'vue.mjs') // '/__devframe/__renderers/vue.mjs'
withBase('meta.json', '/__devframe/') // '/__devframe/meta.json'
withProtocol('http://localhost:7777/ws', 'ws://') // 'ws://localhost:7777/ws'
```

Also exports `withLeadingSlash`, `withoutLeadingSlash`, `withoutTrailingSlash`, and `cleanDoubleSlashes`.

### `devframe/utils/streaming-channel`

Sink/reader primitives for streamed RPC payloads, via `ctx.rpc.streaming`; see [Streaming](/guide/streaming).

### `devframe/utils/when`

Statically-validated when-clause expressions for conditional visibility; runtime + types ship here, consumer `when` fields are kit-side (see [When Clauses](/references/when-clauses)).

## Why a `utils/*` subpath

The utilities are **stable wrappers**, not bare re-exports, so devframe can swap implementations freely.

---
title: Interactive Auth
navigation:
  icon: i-lucide-key-round
description: An OTP auth layer over devframe's node-side primitives (exchangeTempAuthCode / verifyAuthToken / revokeAuthToken), so a host framework needn't re-implement the protocol.
---

An OTP auth layer over devframe's node-side primitives (`exchangeTempAuthCode` / `verifyAuthToken` / `revokeAuthToken`), so a host framework needn't re-implement the protocol.

Adapters gate with this layer by default via `createDevServer(def)` / `initDevframe` / `initHub` (`auth: true`). Use `createInteractiveAuth` only for a custom transport:

```ts
import { createContextRpcServer } from 'devframe/internal'
import { createInteractiveAuth } from 'devframe/recipes/interactive-auth'
import { attachWsRpcTransport } from 'devframe/rpc/transports/ws-server'

const auth = createInteractiveAuth(ctx, {
  clientAuthTokens: process.env.CI ? [process.env.DEVFRAME_CI_TOKEN!] : undefined,
})

const { rpcGroup, onConnected, onDisconnected } = createContextRpcServer({ context: ctx, auth })
attachWsRpcTransport(rpcGroup, { server, onConnected, onDisconnected })
auth.printBanner()
```

As `auth` it wires `rpcFunctions`, `authorize`, and `onConnect`; see [Security](/guide/security).

## `createInteractiveAuth(context, options?)`

| Option             | Default                        | Purpose                                                                                                                                                                          |
| ------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientAuthTokens` | `undefined`                    | Pre-shared bearer tokens, always trusted.                                                                                                                                        |
| `banner`           | a small boxed console message  | Called with `{ code, url, expireAt, requester? }` (`requester` is the asking browser client's `{ ua, origin }`, present on client-requested prints); prints via `printBanner()`. |
| `onTrusted`        | `undefined`                    | Called with `{ session, authToken }` (the trust session and its token) once a code exchange succeeds, so a host framework rendering its own banner can retract it.               |
| `serverUrl`        | `context.host.resolveOrigin()` | Magic-link base URL.                                                                                                                                                             |

Returns a `DevframeAuthHandler`:

| Field                            | Purpose                                                                                                                                                                                                                           |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rpcFunctions`                   | `anonymous:devframe:auth` + `anonymous:devframe:auth:exchange` (handshake), `anonymous:devframe:auth:request-code` (client-requested banner print, `reissue: true` rotates the code first), `devframe:auth:revoke` (self-revoke). |
| `authorize(methodName, session)` | Resolver gate: allows `anonymous:` methods, else requires `session.meta.isTrusted`.                                                                                                                                               |
| `onConnect(peer, session)`       | Connect-time trust from a bearer on the WS upgrade URL (`?devframe_auth_token=`).                                                                                                                                                 |
| `printBanner()`                  | Prints the code + magic-link URL, at most once per code.                                                                                                                                                                          |

## Using the pieces directly

Without `createContextRpcServer`, wire the pieces directly:

```ts
const auth = createInteractiveAuth(ctx)
auth.rpcFunctions.forEach(fn => ctx.rpc.register(fn))
auth.printBanner()

// in your resolver:
if (!auth.authorize(methodName, session))
  throw new Error('not authorized')

// on each new WS peer:
auth.onConnect(peer, session)
```

The banner prints on demand: an untrusted browser client requests it over `anonymous:devframe:auth:request-code` (the RPC client's `requestAuthCode()`, sent when an auth UI first shows or its "re-issue" action runs), or the host calls `auth.printBanner()` itself. An exchange rotates the code silently, and `onTrusted` fires so a host framework rendering a sticky notice can retract it.

Auth storage is internal, not `devframe/node/hub-internals`.

---
title: Pluggable, Extensible, and Playful DevTools
date: '2026-09-16T00:00:00Z'
lang: en
duration: 15min
description: Introduction to Devframe, a framework for building pluggable, extensible, and playful DevTools.
author: Anthony Fu
---

September 16, 2026 {.prose-date}

::post-author{author="Anthony Fu" handle="@antfu" href="https://github.com/antfu"}
::

Over the years, we have built quite a few DevTools: [UnoCSS Inspector](https://unocss.dev/tools/inspector#inspector), [Vite Plugin Inspect](https://github.com/antfu-collective/vite-plugin-inspect), [Vitest UI](https://vitest.dev/guide/ui), [Nuxt DevTools](https://github.com/nuxt/devtools), [ESLint Config Inspector](https://github.com/eslint/config-inspector), and [Node Modules Inspector](https://github.com/antfu/node-modules-inspector), among others.

They look quite different, but fundamentally they all try to do the same thing: make implicit state visible. Instead of guessing why a CSS utility was generated, how a module was transformed, or which configuration applies to a file, we can see the process directly and interact with it.

Despite their different purposes, these tools share a surprising amount of infrastructure: RPC, state synchronization, serialization, static asset hosting, and a web interface. Each one also needs to decide how it is packaged, distributed, and mounted into a host framework. In practice, every tool ends up rebuilding many of the same pieces in isolation.

The same pattern appears across the ecosystem. Frameworks and build tools are building their own DevTools, often with overlapping capabilities such as data inspectors, asset viewers, build analyzers, terminals, and editor tooling. Yet most of them are tied to a specific framework and to the details of its development server: how it serves assets, handles requests, and upgrades connections. As a result, similar features are rebuilt and improved separately.

What if we could **free DevTools from those boundaries**? If each capability were reusable and modular, it could benefit every supported host framework. Instead of spreading the work across several versions of the same idea, communities could join forces on one tool and make it much better together.

This is the vision of a **Universal DevTools Ecosystem** we started sharing back in 2023, in [Now, and the Future of Nuxt DevTools](https://github.com/antfu/talks/tree/main/2023-10-18) and [Anthony's Roads to Open Source - The Set Theory](https://github.com/antfu/talks/tree/main/2023-10-28):

::universal-dev-tools-ecosystem
::

The diagram was aspirational. The direction felt right, but finding the boundary that could make it work was much harder.

The idea stayed with us as the work moved from Nuxt DevTools to Vite DevTools. When we started working on Vite DevTools at Vercel, we had the opportunity to explore it on a broader scale. Vite gave us a concrete home to prove the experience, but the goal was always to open it to other build toolchains. Each iteration taught us something new, while LLMs made it much faster to explore and validate the design. Gradually, the right boundary started to emerge.

Today, the vision is finally within reach. Let us introduce you to **Devframe**.

## Devframe

[**Devframe**](/) is a framework-neutral foundation for defining a devtool once, then bringing it to different host frameworks, standalone adapters, and coding agents.

<img src="/images/devframe/devframe-with-title.svg" alt="Devframe Logo" style="width: 500px; max-width: 100%; margin: 50px auto;" />

You can think of Devframe as a framework for building DevTools, in the same way Nuxt or Next.js provides a framework for building web applications. At the adapter layer, it plays a role similar to [`unplugin`](https://github.com/unjs/unplugin): while `unplugin` gives bundler plugins a common interface, Devframe gives devframes a common definition across host frameworks.

A devframe definition describes one tool: its capabilities, RPC functions, shared state, SPA, diagnostics, and coding-agent interface. From that definition, Devframe creates a Web Standard request handler that can be mounted almost anywhere.

### One Definition, One Standard Handler, Many Adapters

Every Devframe starts with [`defineDevframe()`](/guide/devframe-definition). At its core, it associates a tool's identity with the capabilities it provides:

```ts
// my-tool.ts
import { defineDevframe } from 'devframe'
import { inspectProject } from './rpc'

export default defineDevframe({
  id: 'my-tool',
  name: 'My Tool',
  /** Package metadata and browser entry omitted... */
  setup(ctx) {
    ctx.scope('my-tool').rpc.register(inspectProject)
  },
})
```

The definition is independent of its presentation. [`initDevframe()`](/adapters/initiate) turns it into a live instance:

```ts
// server.ts
import { initDevframe } from 'devframe/initiate'
import myDevframe from './my-tool'

const myTool = initDevframe(myDevframe, {
  base: '/__my-tool/',
})

myTool.handler
// Web Standard Request -> Response handler
// (request: Request) => Promise<Response)

myTool.nodeMiddleware
// Traditional connect-style middleware
// (req: IncomingMessage, res: ServerResponse, next: () => void) => void
```

The handler becomes the tool's boundary. Behind it, Devframe serves the SPA, connection metadata, live RPC, authentication, and optional MCP endpoint under one namespace. The Web Standard `Request` and `Response` free the tool from any particular development server API. *This handler-first model is greatly inspired by [Comark Content](https://content.comark.dev/getting-started/installation#mount-the-handler).*

Modern frameworks, runtimes, and build tools already converge around this boundary. Hono and Nitro work with Web Standard requests directly. Next.js and SvelteKit expose route handlers. Vite and Rsbuild accept Connect-style middleware, for which the same instance provides `nodeMiddleware`:

::devframe-mount-examples
::

That is almost the entire portability trick. Any framework or build tool that supports Web Standard handlers or Connect-style middleware can mount the same Devframe and gain access to the same ecosystem.

### Adapters as Conveniences

The handler is the smallest common denominator. For common entry points, [higher-level adapters](/adapters/) package it into familiar forms. The same definition can become a standalone CLI, a dedicated dev server, a Vite DevTools plugin, an MCP server, or a static report:

```ts
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { createBuild } from 'devframe/adapters/build'
import { createCac } from 'devframe/adapters/cac'
import { createDevServer } from 'devframe/adapters/dev'
import { createMcpServer } from 'devframe/adapters/mcp'
import myDevframe from './my-tool'

/** Pick the entry points your package needs: */
export const runCli = () => createCac(myDevframe).parse()
export const startServer = () => createDevServer(myDevframe)
export const vitePlugin = createPluginFromDevframe(myDevframe)
export const startMcp = () => createMcpServer(myDevframe, { transport: 'stdio' })
export const buildReport = () => createBuild(myDevframe, { outDir: 'dist-static' })
```

A package can ship several of these entry points at once. For example, a build inspector could offer a standalone CLI for any project, generate static reports in CI, appear as a dock entry inside Vite DevTools, and let a coding agent query the active build, all backed by the same definition.

We are already using this model in [Node Modules Inspector](https://github.com/antfu/node-modules-inspector), [ESLint Config Inspector](https://github.com/eslint/config-inspector), and [Vite Plugin Inspect](https://github.com/antfu-collective/vite-plugin-inspect). They remain focused tools with their own interfaces, while sharing Devframe underneath. You can find more examples on the [Ecosystem](/ecosystem) page.

The browser side is up to each tool as well. Devframe handles the protocol and runtime, while the tool can choose whichever UI framework and design system suits it. To dogfood that promise, the [built-in devframes](#built-in-devframes) span Vue, Svelte, Solid, React, and Next.js.

::devframe-architecture
::

### Visual and Coding-Agent Interfaces

As coding agents become part of our development workflows, a devframe can pair its panel for people with a structured interface to its internal state and capabilities.

The two interfaces play to different strengths. Visualizations are effective for exploration, overview, and comparison. Coding agents can retrieve focused context, correlate it with the codebase, and carry out multi-step actions. The presentation changes, but the source of truth stays the same.

In Devframe, RPC functions stay private by default and must be explicitly exposed to coding agents. The [MCP adapter](/adapters/mcp) translates those functions, readable resources, and selected shared state into a coding-agent interface. Descriptions, schemas, and safety metadata help coding agents understand when and how each capability should be used.

There is another interesting piece here. Devframe integrates with Vercel's [`json-render`](https://github.com/vercel-labs/json-render), allowing a UI to be described as serializable data from a constrained component catalog. This makes it easier for coding agents to generate dashboards and interactive tools while keeping the output predictable.

The same mechanism also enables **node-side-provided UI**: a devframe publishes the view and its state, while the consuming UI provides the renderer. The [prebuilt reference UI](/guide/json-render) gives a tool a ready starting point. The protocol remains renderer-agnostic, so each hub UI provider can render the same view with its own framework, components, and design system.

We are still exploring the APIs and practices around discoverability, permissions, context usage, and the relationship between visual and coding-agent workflows. We would love to hear ideas and advice from the community as these patterns evolve through real devframes.

::devframe-dual-surface
::

### Built-in Devframes

Real tools make the abstraction convincing. To test Devframe's capabilities and framework-neutral design, we ship a few [built-in devframes](/add-ons) as reusable working examples. They intentionally use **different UI frameworks**, and each can run through a standalone adapter or mount into a supported host framework.

Here are a few examples:

#### Data Inspector

[`@devframes/plugin-data-inspector`](/add-ons/devframes/data-inspector) is built with Vue and provides an interactive workbench for live node-side objects. A tool can register an object as a data source, then explore and query it with [Jora](https://discoveryjs.github.io/jora/) inside the process that owns it.

Through its standalone adapters, it can inspect JSON or JSONL files, build a self-contained report, or attach to a running Node.js process. This is useful for inspecting stores, caches, framework contexts, build metadata, or other states that usually require custom logging.

You can run its standalone CLI with:

```bash
pnpx @devframes/plugin-data-inspector
```

<figure class="my-4">
<img src="/images/devframe/data-inspector.png" class="scale-105" alt="Data Inspector exploring a live data source" />

<figcaption class="text-center text-sm text-muted">
Data Inspector exploring a live data source
</figcaption>
</figure>

When mounted, other tools contribute data sources. A Vite plugin could expose its plugin container, a host framework could expose runtime state, and a test runner could expose its test graph. All of them can reuse the same query workbench and data viewer across host frameworks.

#### Terminals

[`@devframes/plugin-terminals`](/add-ons/devframes/terminals) is built with Svelte and provides a browser-based terminal panel supporting read-only process output and interactive PTY sessions.

This separates the process-running capability from the tool that renders it. A DevTools host can give multiple tools a consistent place for subprocess output and interactive commands while keeping the user's main terminal focused.

<figure class="my-4">
<img src="/images/devframe/terminals-in-vite-devtools.png" class="rounded-xl border border-default shadow-lg" alt="Terminals devframe running in Vite DevTools" />

<figcaption class="text-center text-sm text-muted mt-2">
Terminals devframe running in Vite DevTools
</figcaption>
</figure>

It also ships a standalone CLI:

```bash
pnpx @devframes/plugin-terminals
```

<figure class="my-4">
<img src="/images/devframe/terminals-standalone.png" class="scale-105" alt="Terminals devframe running as a standalone page" />

<figcaption class="text-center text-sm text-muted">
Terminals devframe running as a standalone page
</figcaption>
</figure>

This opens the interactive terminal directly in your browser. You can use it to manage processes, run commands, or run coding agents like Claude Code from the browser.

#### Accessibility Inspector

[`@devframes/plugin-a11y`](/add-ons/devframes/a11y) is built with Solid. Its page script scans the user app with [axe-core](https://github.com/dequelabs/axe-core), lists WCAG violations, and highlights the corresponding elements on the page. It can also turn the findings into fix prompts for coding agents, connecting visual inspection with a coding-agent workflow.

With a standalone adapter, its panel and page script can inspect any page. Inside a DevTools host, the same findings can also be mirrored into the shared message feed.

It is heavily inspired by [`@nuxt/a11y`](https://github.com/nuxt/a11y), which brought real-time accessibility feedback into Nuxt DevTools. Extracting the idea into a built-in devframe makes the same capability available beyond Nuxt.

<figure class="my-4">
<img src="/images/devframe/a11y.png" class="scale-105" alt="Accessibility Inspector highlighting violations in the user app" />

<figcaption class="text-center text-sm text-muted">
Accessibility Inspector highlighting violations in the user app
</figcaption>
</figure>

#### More Built-in Devframes

Other built-in devframes cover a [VS Code editor on the web](/add-ons/devframes/code-server), [asset management](/add-ons/devframes/assets), a [Git panel](/add-ons/devframes/git), [Open Graph previews](/add-ons/devframes/og), and [Devframe's own RPC and state inspector](/add-ons/devframes/inspect). They share the devframe definition and protocol while each chooses its own UI framework.

These built-in devframes show what Devframe can support and offer starting points for communities to build their own. We believe many more interesting DevTools will emerge over time. You can follow the growing list on the [Ecosystem](/ecosystem) page.

## From One Devframe to a DevTools Host

So far, we have one portable devframe. Once several devframes are active together, another problem appears: **discovery**. How do users find and move between them?

Many DevTools log their own URL to the console:

::terminal-window
```ansi
~ pnpm dev

  VITE v8.2.1  ready in 32 ms

  ➜  Local:  http://localhost:3333/
UnoCSS Inspector: http://localhost:3333/__unocss/

> Visualized ESLint Config: http://127.0.0.1:3333/.eslint-config/
  ➜  Vite Inspect: http://localhost:3333/__inspect/
```
::

Sometimes DevTools also inject floating buttons into the user app:

<figure class="my-4">
<img src="/images/devframe/floating-devtools.png" class="rounded-lg border border-default shadow-lg" alt="Floating buttons injected into the user app" />

<figcaption class="text-center text-sm text-muted mt-2">
Floating buttons from multiple DevTools injected into the user app.<br /><span class="italic opacity-50">(this is a made-up example to demonstrate the problem)</span>
</figcaption>
</figure>

As more tools join the project, the console becomes a directory of URLs and the page gains a collection of unrelated floating buttons. Each devtool also has to build and maintain its own discovery mechanism.

To improve this, Devframe also provides a **composition layer**: the [hub](/guide/hub).

[`@devframes/hub`](/guide/hub) is headless and framework-neutral. Multiple devframes mount into it and contribute docks, commands, messages, terminals, and shared state. To users, they appear through one consistent entry point. To the tools, the hub provides a shared context in which they can discover and collaborate with one another.

The same mounting model scales from one devframe to the whole collection. [`initHub()`](/guide/hub-initiate) puts the hub and all of its mounted devframes behind one Web Standard handler:

```ts
import { initHub } from '@devframes/hub/initiate'
import { createTerminalsDevframe } from '@devframes/plugin-terminals'
import { createXxxDevframe } from '...'

const hub = initHub({
  /**
   * The common base path for all mounted devframes.
   * `/__my-tool/` becomes `/__devframes/__my-tool/`.
   */
  base: '/__devframes/',
  /** The devframes are mounted into the hub. */
  devframes: [
    createTerminalsDevframe(),
    createXxxDevframe(),
    // ...
  ],
  /**
   * We ship a reference UI to make it easy to get started,
   * but you can provide your own layer to match
   * your product's design system and interaction model.
   */
  ui: await import('@devframes/hub-ui').then(m => m.createUi()),
})

// The same handler/middleware API as a standalone devframe.
hub.handler
hub.nodeMiddleware
```

<figure class="my-4">
<img src="/images/devframe/floating-devtools-with-devframes-hub.png" class="rounded-lg border border-default shadow-lg" alt="DevTools collected under one hub entry" />

<figcaption class="text-center text-sm text-muted mt-2">
With the hub, devframes appear under one consistent entry.<br /><span class="italic opacity-50">(this is a made-up example for demonstration)</span>
</figcaption>
</figure>

Mounted devframes share one RPC registry, state store, connection, authentication gate, and optional aggregate MCP endpoint. The hub remains headless: [`@devframes/hub-ui`](/guide/hub-initiate#the-ui-slot) provides the reference hub UI provider, while a product can supply another hub UI provider independently of the underlying tools.

Like a single devframe, a hub can mount into almost any host framework through the standard handler. The repository includes working reference projects for [Vite](https://github.com/devframes/devframe/tree/main/examples/hub-vite), [Next.js](https://github.com/devframes/devframe/tree/main/examples/hub-next), [Hono](https://github.com/devframes/devframe/tree/main/examples/hub-hono), [Nitro](https://github.com/devframes/devframe/tree/main/examples/hub-nitro), and [Rsbuild](https://github.com/devframes/devframe/tree/main/examples/hub-rsbuild). Each example connects the same handler and UI entry to its host framework's native server API. A complete DevTools host can build its own design system and interaction model on top of the hub's foundation.

### Vite DevTools

[Vite DevTools](https://devtools.vite.dev/) is the first flagship DevTools host built on this foundation. It brings a Vite-focused interface and Vite-native capabilities while using `initHub()` for composition and serving. Alongside Vite and Rolldown analysis, Vitest UI, and Oxc tooling, it gives independent devframes a common place to work together.

<figure class="my-4">
<img src="/images/devframe/vite-devtools-vite-plus.png" class="!-my-10 scale-[0.8] rounded-lg border border-default shadow-lg" alt="Vite Plus dock entry in Vite DevTools" />

<figcaption class="text-center text-sm text-muted mt-2">
Vite Plus dock entry in Vite DevTools
</figcaption>
</figure>

<figure class="my-4">
<img src="/images/devframe/vite-devtools-rolldown.png" class="rounded-lg border border-default shadow-lg" alt="Rolldown DevTools in Vite DevTools" />

<figcaption class="text-center text-sm text-muted mt-2">
Rolldown DevTools in Vite DevTools
</figcaption>
</figure>

A devframe can join Vite DevTools through an adapter. A regular Vite plugin can also contribute directly through the new `devtools.setup` entry:

```ts
// vite.config.ts
import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
import { createMyDevframe } from 'my-devframe-tool'
import { defineConfig } from 'vite'

const myDevframe = createMyDevframe()

export default defineConfig({
  devtools: true,
  plugins: [
    // Helper to turn a devframe into a Vite plugin.
    createPluginFromDevframe(myDevframe),
    // A regular Vite plugin can also contribute directly.
    {
      name: 'vite-plugin-my-tool',
      devtools: {
        setup(ctx) {
          // Devframe context with Vite-specific augmentations.
        },
      },
    },
  ],
})
```

The adapter turns an existing devframe into a Vite plugin. The `devtools.setup` entry lets Vite plugins use the same context directly. This makes adoption incremental: tools can start where they are and still participate in the shared ecosystem.

### Nuxt DevTools

The new [Nuxt DevTools](https://github.com/nuxt/devtools) v4 builds on top of both Devframe and Vite DevTools. It now would inherits the ecosystem of both of them.

<figure class="my-4">
<img src="/images/devframe/nuxt-devtools-v4.png" class="rounded-lg border border-default shadow-lg" alt="Nuxt DevTools v4" />

<figcaption class="text-center text-sm text-muted mt-2">
Nuxt DevTools v4
</figcaption>
</figure>

Here are the stacking layers to demonstrate this better:

::dev-tools-stack
::

[Vue DevTools](https://devtools.vuejs.org/) is also migrating to the Vite DevTools foundation. Vue capabilities such as component and reactivity inspection can then coexist with Vite-native capabilities and framework-neutral devframes in the same DevTools host.

In a way, the story has come full circle: the wish that started with Nuxt DevTools now returns with a concrete foundation underneath. Nuxt DevTools v4 is expected to ship with Nuxt v5 and will also be available as a manual opt-in for Nuxt 4.

### Next.js DevTools (Prototype)

We are also experimenting with the integrations of bringing Devframes to Next.js DevTools, and internally, we have a working prototype to have Devframes Hub working inside Next.js DevTools without any modifications to the installed devframe plugins.

<figure class="my-4">
<video class="rounded-lg border border-default shadow-lg" alt="Next.js DevTools with Devframes prototype" autoplay muted loop>
<source src="/images/devframe/nextjs-devtools-with-devframes-demo.mp4" type="video/mp4" />

<img src="/images/devframe/nextjs-devtools-with-devframes-demo.png" alt="Next.js DevTools with Devframes prototype" />
</video>

<figcaption class="text-center text-sm text-muted mt-2">
Next.js DevTools with Devframes prototype<br /><span class="italic opacity-50">(this is an internal prototype, it's not yet available and does not represent the final state)</span>
</figcaption>
</figure>

## Inheriting the Ecosystem

Framework-specific layers keep their own look and can be much richer because they understand their framework's conventions and runtime. The infrastructure stays shared while the final experience remains specific.

Devframe itself remains independent of Vite and any framework. A future framework-specific DevTools host can mount the same hub and devframes, then add its own knowledge and presentation on top of the shared foundation:

::devframe-ecosystem-map
::

## Build Your Own DevTools

Devframe supports framework authors and established tooling teams as well as project-specific DevTools and one-off visualizations. With built-in coding-agent skills and a growing collection of real-world examples, we are exploring a future where you might ask a coding agent:

> "Build me a one-off devframe to visualize my app's network request flow and highlight the bottlenecks."

A useful devtool might exist only long enough to answer one question. We will keep improving Devframe and its ecosystem so these pluggable, extensible, and playful tools become practical for more people to build.

## What's Next

Devframe v1.0 stabilizes the interface for the community to build on and experiment with. Vite DevTools will follow with a stable release, while Nuxt DevTools v4 and the Vue DevTools migration continue testing the model at the framework level.

This is the first credible implementation toward the modular DevTools infrastructure we imagined years ago. There are more host frameworks to connect, mounting conventions to refine, and coding-agent practices to discover.

What excites us is the possibility that a good tool can be built once, travel further, and become better as more communities contribute to it: shared infrastructure underneath, specific and playful experiences on top, and structured capabilities available to both people and coding agents.

We are still exploring the best practices, especially around coding-agent interfaces, permissions, and cross-tool collaboration. Any kind of contribution is welcome: devframes, experiments, design ideas, use cases, feedback, or simply trying the tools and sharing what you find.

If this direction sounds interesting to you, check out the [Devframe](https://github.com/devframes/devframe) repository, try building something with it, and leave us some feedback. We are looking forward to seeing what we can build together!

## Thanks

This vision has come a long way with the help of many people.

A huge thank you to :github-user[webfansplz]{username="webfansplz"}, who has put a tremendous amount of work into Vite DevTools. We also owe a lot to :github-user[Akryum]{username="Akryum"}: his work on Vue DevTools and testing framework UIs has inspired us for years, and he spent a great deal of time brainstorming and prototyping these DevTools ideas with us. :github-user[hyfdev]{username="hyfdev"} helped coordinate with Rolldown and shape the APIs that made Vite DevTools possible. :github-user[Atinux]{username="Atinux"} planted the seed of Nuxt DevTools, invested so much in building it, and now continues that investment in Vite DevTools. :github-user[danielroe]{username="danielroe"} provided valuable feedback on Nuxt DevTools and kept motivating us to push further on bundle size *(the installed size of Vite DevTools core dropped by 30 MB from v0.1 to v0.5)*. :github-user[posva]{username="posva"} for providing great feedback on Devframe's documentation and helping on the integrations.

Thanks also to :github-user[yuyinws]{username="yuyinws"} for donating Oxc Inspector to Vite Plus DevTools and continuing to maintain it; and to :github-user[SaKaNa-Y]{username="SaKaNa-Y"} and :github-user[dvcolomban]{username="dvcolomban"} for being early adopters and contributing extensively to both Vite DevTools and Devframe.

And, of course, thanks to everyone who has contributed to Vite DevTools, Nuxt DevTools, and Vue DevTools along the way. This work is built on top of all those contributions.

And thanks to [Vercel](https://vercel.com) for supporting these projects and bringing our ambitious plan for unified DevTools within reach.

::callout{icon="i-lucide-star"}
Enjoying Devframe? [Give the repo a star on GitHub](https://github.com/devframes/devframe) and [join us on Discord](/chat){target="_blank"} to follow along and take part in the discussion.
::