Merge remote-tracking branch 'origin/main' into feat/assets-plugin

# Conflicts:
#	pnpm-lock.yaml
#	turbo.json
#	vitest.config.ts

Author: antfubot

AGENTS.md

@@ -4,7 +4,7 @@
 
 **`devframe`** is the framework-neutral container for one devtool integration, portable across viewers. Build a single tool (its RPC, its SPA, its diagnostics, its CLI/build/spa/embedded outputs) without caring how it'll be displayed. A devframe app runs standalone (CLI, static deploy, embedded SPA) just as well as it mounts inside a hub.
 
-**`@devframes/hub`** is the framework-neutral hub layer that sits on top of devframe and provides the multi-integration orchestration (docks, terminals, messages, commands). It does not ship UI — implementers (e.g. `@vitejs/devtools-kit`) provide their own UI on top of the hub's RPC + shared-state protocol. It does ship a **headless client runtime** (`createDevframeClientHost()` from `@devframes/hub/client`): booted in the host page, it assembles the shared `DevframeClientContext` (panel, docks, commands, when) and imports each dock entry's client script (`action` / `custom-render` / iframe `clientScript`) into that page — how a plugin like the a11y inspector runs code inside the page being inspected. See `examples/minimal-vite-devframe-hub/` for a working ~120-line Vite host demonstrating the protocol end to end.
+**`@devframes/hub`** is the framework-neutral hub layer that sits on top of devframe and provides the multi-integration orchestration (docks, terminals, messages, commands). It does not ship UI — implementers (e.g. `@vitejs/devtools-kit`) provide their own UI on top of the hub's RPC + shared-state protocol. It does ship a **headless client runtime** (`createDevframeClientHost()` from `@devframes/hub/client`): booted in the host page, it assembles the shared `DevframeClientContext` (panel, docks, commands, when) and imports each dock entry's client script (`action` / `custom-render` / iframe `clientScript`) into that page — how a plugin like the a11y inspector runs code inside the page being inspected. See `examples/vite-devframe-hub/` for a working ~120-line Vite host demonstrating the protocol end to end.
 
 ## Stack & Structure
 

alias.ts

@@ -46,14 +46,16 @@ export const alias = {
   '@devframes/hub': r('hub/src/index.ts'),
   '@devframes/nuxt/runtime/plugin.client': r('nuxt/src/runtime/plugin.client.ts'),
   '@devframes/nuxt': r('nuxt/src/index.ts'),
+  '@devframes/next/client': r('next/src/client.tsx'),
+  '@devframes/next': r('next/src/index.ts'),
   '@devframes/json-render/core': r('json-render/src/core.ts'),
   '@devframes/json-render/hub': r('json-render/src/hub.ts'),
   '@devframes/json-render/node': r('json-render/src/node/index.ts'),
   '@devframes/json-render': r('json-render/src/index.ts'),
   '@devframes/json-render-ui/components': r('json-render-ui/src/components/index.ts'),
   '@devframes/json-render-ui/spa': r('json-render-ui/src/spa.ts'),
   '@devframes/json-render-ui': r('json-render-ui/src/index.ts'),
-  'minimal-json-render/dashboard': fileURLToPath(new URL('./examples/minimal-json-render/src/dashboard.ts', import.meta.url)),
+  'json-render/dashboard': fileURLToPath(new URL('./examples/json-render/src/dashboard.ts', import.meta.url)),
   '@devframes/plugin-code-server/client': p('code-server/src/client/index.ts'),
   '@devframes/plugin-code-server/node': p('code-server/src/node/index.ts'),
   '@devframes/plugin-code-server/constants': p('code-server/src/constants.ts'),
@@ -71,6 +73,7 @@ export const alias = {
   '@devframes/plugin-terminals': p('terminals/src/index.ts'),
   '@devframes/plugin-git': p('git/src/index.ts'),
   'devframe/recipes/interactive-auth': r('devframe/src/recipes/interactive-auth.ts'),
+  'devframe/recipes/common-rpc-functions': r('devframe/src/recipes/common-rpc-functions.ts'),
   'devframe/recipes/open-helpers': r('devframe/src/recipes/open-helpers.ts'),
   'devframe/client': r('devframe/src/client/index.ts'),
   'devframe': r('devframe/src'),

docs/.vitepress/config.ts

@@ -55,7 +55,8 @@ function helpersItems(prefix: string) {
     { text: 'Utilities', link: `${prefix}/helpers/utilities` },
     { text: 'Vite Bridge', link: `${prefix}/helpers/vite-bridge` },
     { text: 'Nuxt Module', link: `${prefix}/helpers/nuxt` },
-    { text: 'Open Helpers', link: `${prefix}/helpers/open-helpers` },
+    { text: 'Next Helper', link: `${prefix}/helpers/next` },
+    { text: 'Common RPC Functions', link: `${prefix}/helpers/common-rpc-functions` },
     { text: 'Interactive Auth', link: `${prefix}/helpers/interactive-auth` },
   ] satisfies DefaultTheme.NavItemWithLink[]
 }
@@ -79,11 +80,11 @@ function examplesItems(prefix: string) {
     { text: 'Overview', link: `${prefix}/examples/` },
     { text: 'Built with Devframe', link: `${prefix}/examples/built-with` },
     { text: 'files-inspector', link: `${prefix}/examples/files-inspector` },
-    { text: 'minimal-json-render', link: `${prefix}/examples/minimal-json-render` },
+    { text: 'json-render', link: `${prefix}/examples/json-render` },
     { text: 'streaming-chat', link: `${prefix}/examples/streaming-chat` },
     { text: 'next-runtime-snapshot', link: `${prefix}/examples/next-runtime-snapshot` },
-    { text: 'minimal-vite-devframe-hub', link: `${prefix}/examples/minimal-vite-devframe-hub` },
-    { text: 'minimal-next-devframe-hub', link: `${prefix}/examples/minimal-next-devframe-hub` },
+    { text: 'vite-devframe-hub', link: `${prefix}/examples/vite-devframe-hub` },
+    { text: 'next-devframe-hub', link: `${prefix}/examples/next-devframe-hub` },
   ] satisfies DefaultTheme.NavItemWithLink[]
 }
 
@@ -114,17 +115,21 @@ export function devframeSidebar(prefix = ''): DefaultTheme.SidebarItem[] {
 
 export function devframeNav(prefix = ''): DefaultTheme.NavItem[] {
   return [
-    { text: 'Guide', items: guideItems(prefix) },
-    { text: 'Adapters', items: adaptersItems(prefix) },
     {
-      text: 'Resources',
+      text: 'Guide',
+      items: [
+        ...guideItems(prefix),
+        { text: 'Examples', items: examplesItems(prefix) },
+      ],
+    },
+    {
+      text: 'Adapters',
       items: [
-        { text: 'Examples', link: `${prefix}/examples/` },
-        { text: 'Built with Devframe', link: `${prefix}/examples/built-with` },
+        ...adaptersItems(prefix),
         { text: 'Helpers', items: helpersItems(prefix) },
-        { text: 'Plugins', items: pluginsItems(prefix) },
       ],
     },
+    { text: 'Plugins', items: pluginsItems(prefix) },
     { text: 'Errors', link: `${prefix}/errors/` },
     {
       text: `v${pkg.version}`,

docs/examples/index.md

@@ -9,11 +9,11 @@ End-to-end examples that exercise the full adapter surface, each a runnable app
 | Example | UI framework | What it shows |
 |---------|--------------|---------------|
 | [files-inspector](./files-inspector) | Preact | Lists files in the cwd via RPC; exercises the CLI dev / build / spa surfaces. |
-| [minimal-json-render](./minimal-json-render) | Vue | A server-authored JSON-render view rendered by `@devframes/json-render-ui`, with live state and an action bridge. |
+| [json-render](./json-render) | Vue | A server-authored JSON-render view rendered by `@devframes/json-render-ui`, with live state and an action bridge. |
 | [streaming-chat](./streaming-chat) | Preact | Streams synthetic chat tokens server → client, with history kept in shared state. |
 | [next-runtime-snapshot](./next-runtime-snapshot) | React (Next.js) | A Next.js App Router SPA over RPC, surfacing the host Node runtime. |
-| [minimal-vite-devframe-hub](./minimal-vite-devframe-hub) | Vanilla TypeScript (Vite) | A ~120-line Vite host wiring `@devframes/hub` end to end. |
-| [minimal-next-devframe-hub](./minimal-next-devframe-hub) | React (Next.js) | The same hub protocol, hosted from a Next.js route handler. |
+| [vite-devframe-hub](./vite-devframe-hub) | Vanilla TypeScript (Vite) | A ~120-line Vite host wiring `@devframes/hub` end to end. |
+| [next-devframe-hub](./next-devframe-hub) | React (Next.js) | The same hub protocol, hosted from a Next.js route handler. |
 
 ## Run any example
 

docs/examples/minimal-json-render.md docs/examples/json-render.mddocs/examples/minimal-json-render.md renamed to docs/examples/json-render.md

@@ -2,13 +2,13 @@
 outline: deep
 ---
 
-# minimal-json-render
+# json-render
 
 A standalone devframe that serves a **JSON-render view**: the server authors an
 `@json-render/core` spec once, and the prebuilt `@devframes/json-render-ui` SPA
 renders it — the app ships no client build of its own.
 
-Package: `minimal-json-render` · frontend: **prebuilt `@devframes/json-render-ui/spa`**
+Package: `json-render` · frontend: **prebuilt `@devframes/json-render-ui/spa`**
 
 ## What it shows
 
@@ -29,12 +29,12 @@ Package: `minimal-json-render` · frontend: **prebuilt `@devframes/json-render-u
 ## Run it
 
 ```sh
-pnpm --filter minimal-json-render dev         # CLI dev server (live RPC)
-pnpm --filter minimal-json-render cli:build   # static deploy → dist/static
+pnpm --filter json-render dev         # CLI dev server (live RPC)
+pnpm --filter json-render cli:build   # static deploy → dist/static
 ```
 
-The dev server serves the SPA at `/__minimal-json-render/`.
+The dev server serves the SPA at `/__json-render/`.
 
 ## Source
 
-[`examples/minimal-json-render`](https://github.com/devframes/devframe/tree/main/examples/minimal-json-render)
+[`examples/json-render`](https://github.com/devframes/devframe/tree/main/examples/json-render)

…cs/examples/minimal-next-devframe-hub.md docs/examples/next-devframe-hub.mddocs/examples/minimal-next-devframe-hub.md renamed to docs/examples/next-devframe-hub.md docs/examples/minimal-next-devframe-hub.md renamed to docs/examples/next-devframe-hub.md

@@ -2,16 +2,16 @@
 outline: deep
 ---
 
-# minimal-next-devframe-hub
+# next-devframe-hub
 
-The same hub protocol as the [Vite host](./minimal-vite-devframe-hub), hosted from a **Next.js** App Router app. It wires [`@devframes/hub`](/guide/hub) by lazily starting a side-car RPC / WebSocket server from a Node route handler — proof that the hub is host-runtime-agnostic.
+The same hub protocol as the [Vite host](./vite-devframe-hub), hosted from a **Next.js** App Router app. It wires [`@devframes/hub`](/guide/hub) by lazily starting a side-car RPC / WebSocket server from a Node route handler — proof that the hub is host-runtime-agnostic.
 
-Package: `minimal-next-devframe-hub` · framework: **React (Next.js)**
+Package: `next-devframe-hub` · framework: **React (Next.js)**
 
 ## What it proves
 
 - `createHubContext()` boots a hub without any Vite-specific code path.
-- A `DevframeHost` implementation plugs the Next host specifics into the hub uniformly.
+- The [`@devframes/next`](/helpers/next) bridge supplies the `DevframeHost` and a single `fetch` handler both route handlers delegate to — serving every mounted SPA and its connection meta through devframe's own static handler.
 - `mountDevframe(ctx, def)` registers any `DevframeDefinition` as a dock.
 - The built-in `hub:commands:execute` RPC dispatches any registered server command, regardless of how the host was constructed.
 - The browser-side `connectDevframe({ baseURL: '/__hub/' })` discovers the WS endpoint via the Next route handler at `/__hub/__connection.json`, which starts the singleton host on demand.
@@ -22,11 +22,15 @@ Package: `minimal-next-devframe-hub` · framework: **React (Next.js)**
 
 ```sh
 pnpm install
-pnpm --filter minimal-next-devframe-hub dev
+pnpm --filter next-devframe-hub dev
 ```
 
 Open the printed URL to see the docks, commands, messages, and terminals lists, plus a button that dispatches a sample command through `hub:commands:execute`.
 
+## See also
+
+- [Next Helper](/helpers/next) — the `@devframes/next` host bridge this example runs on
+
 ## Source
 
-[`examples/minimal-next-devframe-hub`](https://github.com/devframes/devframe/tree/main/examples/minimal-next-devframe-hub)
+[`examples/next-devframe-hub`](https://github.com/devframes/devframe/tree/main/examples/next-devframe-hub)

docs/examples/streaming-chat.md

@@ -10,7 +10,7 @@ Package: `streaming-chat-example` · framework: **Preact + Vite**
 
 ## What it shows
 
-- A scoped context (`ctx.scope('devframe-streaming-chat')`) auto-namespaces every id.
+- A scoped context (`ctx.scope('example:streaming-chat')`) auto-namespaces every id.
 - `my.rpc.streaming.create('tokens', …)` registers a streaming channel for low-latency token rendering.
 - `my.rpc.sharedState('history', …)` keeps the message log on the server; each `send` appends a user + assistant pair atomically.
 - The producer streams tokens live, then commits the joined content back to shared state when done — so refreshes and new clients see the finished message immediately.

…cs/examples/minimal-vite-devframe-hub.md docs/examples/vite-devframe-hub.mddocs/examples/minimal-vite-devframe-hub.md renamed to docs/examples/vite-devframe-hub.md docs/examples/minimal-vite-devframe-hub.md renamed to docs/examples/vite-devframe-hub.md

@@ -2,11 +2,11 @@
 outline: deep
 ---
 
-# minimal-vite-devframe-hub
+# vite-devframe-hub
 
 A protocol-witness host: roughly 120 lines of Vite plugin code that wire [`@devframes/hub`](/guide/hub) into a Vite dev server. The browser UI is plain **vanilla TypeScript**, so nothing distracts from the hub protocol itself. Every framework's hub host follows the same shape.
 
-Package: `minimal-vite-devframe-hub` · framework: **Vanilla TypeScript (Vite)**
+Package: `vite-devframe-hub` · framework: **Vanilla TypeScript (Vite)**
 
 ## What it proves
 
@@ -22,11 +22,11 @@ Package: `minimal-vite-devframe-hub` · framework: **Vanilla TypeScript (Vite)**
 
 ```sh
 pnpm install
-pnpm --filter minimal-vite-devframe-hub dev
+pnpm --filter vite-devframe-hub dev
 ```
 
 Open the printed URL to see the docks, commands, messages, and terminals lists the hub exposes, plus a button that dispatches a sample command through `hub:commands:execute`.
 
 ## Source
 
-[`examples/minimal-vite-devframe-hub`](https://github.com/devframes/devframe/tree/main/examples/minimal-vite-devframe-hub)
+[`examples/vite-devframe-hub`](https://github.com/devframes/devframe/tree/main/examples/vite-devframe-hub)

docs/guide/client-context.md

@@ -186,4 +186,4 @@ state.domElements.iframe = iframeEl
 state.events.emit('dom:iframe:mounted', iframeEl)
 ```
 
-That announcement is what the adapter attaches to. Both minimal hubs wire this end to end — see the "Tabbed Tool" in [`examples/minimal-vite-devframe-hub`](https://github.com/devframes/devframe/tree/main/examples/minimal-vite-devframe-hub) and [`examples/minimal-next-devframe-hub`](https://github.com/devframes/devframe/tree/main/examples/minimal-next-devframe-hub), including the SPA's `postMessage` shim.
+That announcement is what the adapter attaches to. Both minimal hubs wire this end to end — see the "Tabbed Tool" in [`examples/vite-devframe-hub`](https://github.com/devframes/devframe/tree/main/examples/vite-devframe-hub) and [`examples/next-devframe-hub`](https://github.com/devframes/devframe/tree/main/examples/next-devframe-hub), including the SPA's `postMessage` shim.

docs/guide/hub.md

@@ -152,7 +152,7 @@ Each mounted SPA is served at `/__<id>/` and references its assets relatively (`
 export default { skipTrailingSlashRedirect: true }
 ```
 
-[`examples/minimal-next-devframe-hub/`](https://github.com/devframes/devframe/tree/main/examples/minimal-next-devframe-hub) is a working Next.js App Router host that mounts the built-in plugins this way.
+[`examples/next-devframe-hub/`](https://github.com/devframes/devframe/tree/main/examples/next-devframe-hub) is a working Next.js App Router host that mounts the built-in plugins this way.
 
 ### Duplicate devframes
 
@@ -260,8 +260,8 @@ The hub also ships a headless browser runtime, `createDevframeClientHost()` from
 
 Two minimal, copyable hubs mount every built-in plugin (git, terminals, code-server, inspect, a11y) behind an icon dock — the same shape [vite-devtools](https://github.com/vitejs/devtools) wears as the full Vite viewer, shrunk to the smallest thing you can build your own viewer from:
 
-- [`examples/minimal-vite-devframe-hub/`](https://github.com/devframes/devframe/tree/main/examples/minimal-vite-devframe-hub) — a ~120-line Vite plugin host with a vanilla DOM UI.
-- [`examples/minimal-next-devframe-hub/`](https://github.com/devframes/devframe/tree/main/examples/minimal-next-devframe-hub) — the same protocol hosted from a Next.js App Router app.
+- [`examples/vite-devframe-hub/`](https://github.com/devframes/devframe/tree/main/examples/vite-devframe-hub) — a ~120-line Vite plugin host with a vanilla DOM UI.
+- [`examples/next-devframe-hub/`](https://github.com/devframes/devframe/tree/main/examples/next-devframe-hub) — the same protocol hosted from a Next.js App Router app.
 
 Both also mount a "Tabbed Tool" that demonstrates [shared-iframe soft navigation](./client-context#shared-iframe-soft-navigation) — one SPA whose tabs surface as separate docks sharing a single iframe.