refactor(vite,nuxt,next): split each into /dev-spa and /hub scopes

Each framework adapter package now exposes two clearly-scoped subpaths for
the two distinct jobs a consumer does, with a bare root that throws a tip:

  • `.../dev-spa` — build & dev-serve a SINGLE devframe's SPA with the tool
    (Vite: devframeVitePlugin/Bridge/Vite; Next: withDevframe +
    createDevframeNextHandler + `/dev-spa/client` React client; Nuxt: the
    module, `modules: ['@devframes/nuxt/dev-spa']`).
  • `.../hub` — mount a whole @devframes/hub (many integrations) inside the
    tool, defaulting the UI slot to @devframes/hub-ui's createUi()
    (overridable via `ui`, or `ui: false` for headless), with a browser
    client helper at `.../hub/client` over createDevframeClientHost.
  • the bare root (`.`) throws a helpful error pointing at both subpaths.

Vite and Nuxt already have native hub viewers (@vitejs/devtools-kit,
@nuxt/devtools), so `@devframes/vite/hub` and `@devframes/nuxt/hub` still
work but emit a one-time console.warn recommending those (silence with
`{ quiet: true }`); `@devframes/next/hub` has no native counterpart and
warns nothing. @devframes/hub and @devframes/hub-ui are optional peers of
all three; hub-ui loads lazily so it stays optional.

The four hub examples now consume the new `/hub` exports: the full
hub-vite/hub-next hosts pass `ui: false` and keep their hand-rolled
clients (the point of those references), while the minimal ones use the
default @devframes/hub-ui. Docs and the AGENTS.md convention section are
updated; tsnapi snapshots regenerated for the new subpaths (allowing the
intentional breaking rename — these packages have not shipped yet).

This PR was created with the help of an agent.

Author: antfubot

AGENTS.md

@@ -44,6 +44,16 @@ The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots co
 - Utility imports use the package-path form `devframe/utils/*`, never relative `../utils/*`.
 - Dependencies go through the pnpm catalogs in `pnpm-workspace.yaml` (`cli`, `inlined`, `testing`, `types`) - add to a catalog and reference as `catalog:<name>`, don't pin versions in `package.json`.
 
+### Framework adapter packages: two scopes, one shape
+
+The framework adapter packages - `@devframes/vite`, `@devframes/nuxt`, `@devframes/next` - each split their surface into **two clearly-scoped subpaths**, because a consumer is always doing one of two distinct jobs. Keep all three parallel:
+
+- **`.../dev-spa`** - **build & dev-serve a single devframe's SPA** with that tool (the "I'm authoring one devframe" scope). Vite: the `devframeVitePlugin` / `devframeViteBridge` / `devframeVite` plugins. Next: `withDevframe` + `createDevframeNextHandler`, with its React client at `.../dev-spa/client`. Nuxt: the Nuxt module (registered as `modules: ['@devframes/nuxt/dev-spa']`).
+- **`.../hub`** - **mount a whole `@devframes/hub` (many integrations) inside that tool** (the "I'm standing up devtools" scope). Wraps `initHub`, defaults the UI slot to `@devframes/hub-ui`'s `createUi()` (overridable via `ui`, or `ui: false` for headless), and ships a browser client helper at `.../hub/client` (a thin, lifecycle-managing wrapper over `@devframes/hub/client`'s `createDevframeClientHost`). `@devframes/hub` and `@devframes/hub-ui` are **optional peers** of these packages; `hub-ui` is loaded lazily (a bundler-ignored dynamic `import()` in the Next hub) so it stays optional and its `import.meta.url` asset lookups resolve at request time.
+- **The bare root (`.`) throws** a helpful error pointing at the two subpaths - never put real code on it.
+- **Vite and Nuxt already have native hub viewers** (`@vitejs/devtools-kit`, `@nuxt/devtools`), so `@devframes/vite/hub` and `@devframes/nuxt/hub` still work but emit a one-time `console.warn` recommending those (silence with `{ quiet: true }`). `@devframes/next/hub` has no native counterpart, so it warns nothing.
+- The **full hub examples** (`examples/hub-vite`, `examples/hub-next`) consume `.../hub` for the server but keep hand-rolling their own client UI against `@devframes/hub/client` with `ui: false` - that hand-rolled client is the whole point of those reference hosts. The **minimal** ones (`examples/hub-*-minimal`) consume `.../hub` with the default `@devframes/hub-ui` and inject its `embedded.js`, needing no client code.
+
 ### Design system
 
 All five built-in plugins - and every example under `examples/` - share one design system, [`@antfu/design`](https://github.com/antfu/design), so they look and feel like one product across frameworks (Git is React/Next, terminals is Svelte, code-server is Vue, inspect is Vue, a11y is Solid, the examples are Preact/Next/vanilla). It's a dev dependency consumed at build time: its UnoCSS preset and shipped styles drive every surface, and its Vue components are the canonical reference every framework matches. There is no shared internal design package - each app wires the preset itself and owns its own component ports.

alias.ts

@@ -50,9 +50,18 @@ export const alias = {
   '@devframes/hub': r('hub/src/index.ts'),
   '@devframes/hub-ui': r('hub-ui/src/index.ts'),
   '@devframes/nuxt/runtime/plugin.client': r('nuxt/src/runtime/plugin.client.ts'),
+  '@devframes/nuxt/dev-spa': r('nuxt/src/dev-spa.ts'),
+  '@devframes/nuxt/hub/client': r('nuxt/src/hub-client.ts'),
+  '@devframes/nuxt/hub': r('nuxt/src/hub.ts'),
   '@devframes/nuxt': r('nuxt/src/index.ts'),
-  '@devframes/next/client': r('next/src/client.tsx'),
+  '@devframes/next/dev-spa/client': r('next/src/client.tsx'),
+  '@devframes/next/dev-spa': r('next/src/dev-spa.ts'),
+  '@devframes/next/hub/client': r('next/src/hub-client.tsx'),
+  '@devframes/next/hub': r('next/src/hub.ts'),
   '@devframes/next': r('next/src/index.ts'),
+  '@devframes/vite/dev-spa': r('vite/src/dev-spa.ts'),
+  '@devframes/vite/hub/client': r('vite/src/hub-client.ts'),
+  '@devframes/vite/hub': r('vite/src/hub.ts'),
   '@devframes/vite': r('vite/src/index.ts'),
   '@devframes/json-render/core': r('json-render/src/core.ts'),
   '@devframes/json-render/hub': r('json-render/src/hub.ts'),

docs/guide/standalone-cli.md

@@ -90,7 +90,7 @@ For the Nuxt side, add the devframe helper module — it sets `app.baseURL: './'
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   ssr: false,
-  modules: ['@devframes/nuxt'],
+  modules: ['@devframes/nuxt/dev-spa'],
   nitro: {
     preset: 'static',
     output: { dir: './dist' }, // matches createCac's distDir of ./dist/public

docs/helpers/next.md

@@ -9,18 +9,19 @@ outline: deep
 
 `@devframes/next` hosts devframes from a Next.js App Router app. Next runs on webpack/Turbopack rather than Vite, so it hosts through a route handler instead of the [Vite Bridge](./vite-bridge): the package serves each devframe's SPA and its `__connection.json` from a single `fetch` handler your catch-all route delegates to, reusing devframe's own [`serveStaticHandler`](/adapters/dev) for SPA fallback, content types, and path-traversal guarding.
 
-It comes in three parts:
+`@devframes/next` splits into two scopes: `@devframes/next/dev-spa` (author one devframe with Next) and [`@devframes/next/hub`](#mounting-a-hub) (mount a whole devframes-hub). The bare `@devframes/next` import throws with a pointer to both.
+
+The `dev-spa` scope comes in two parts:
 
 1. **`withDevframe()`** — applies the one Next config setting a devframe host needs.
 2. **`createDevframeNextHandler()`** — hosts a single devframe (the common case).
-3. **`createDevframeNextHost()`** — the lower-level primitive for a hub mounting many devframes at once.
 
-Plus a React client surface at `@devframes/next/client`.
+Plus a React client surface at `@devframes/next/dev-spa/client`.
 
 ## Config
 
 ```ts [next.config.mjs]
-import { withDevframe } from '@devframes/next'
+import { withDevframe } from '@devframes/next/dev-spa'
 
 export default withDevframe({
   // ...your own Next config
@@ -34,7 +35,7 @@ export default withDevframe({
 `createDevframeNextHandler(definition)` statically serves the devframe's built SPA and starts a side-car RPC/WebSocket server, advertising it at `<base>/__connection.json`. Delegate your catch-all route to its `fetch`:
 
 ```ts [app/__my-tool/[[...path]]/route.ts]
-import { createDevframeNextHandler } from '@devframes/next'
+import { createDevframeNextHandler } from '@devframes/next/dev-spa'
 import myDevframe from '@/devframe'
 
 export const runtime = 'nodejs'
@@ -87,11 +88,11 @@ export async function GET(request: Request): Promise<Response> {
 
 ## React client
 
-`@devframes/next/client` connects to the RPC backend and provides the client to your component tree — the React counterpart to `@devframes/nuxt`'s `$rpc` plugin. Children render immediately, so your shell and a connection indicator stay visible while the client connects.
+`@devframes/next/dev-spa/client` connects to the RPC backend and provides the client to your component tree — the React counterpart to `@devframes/nuxt`'s `$rpc` plugin. Children render immediately, so your shell and a connection indicator stay visible while the client connects.
 
 ```tsx [app/providers.tsx]
 'use client'
-import { RpcProvider } from '@devframes/next/client'
+import { RpcProvider } from '@devframes/next/dev-spa/client'
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <RpcProvider baseURL="/__my-tool/">{children}</RpcProvider>
@@ -102,7 +103,7 @@ export function Providers({ children }: { children: React.ReactNode }) {
 
 ```tsx [app/panel.tsx]
 'use client'
-import { useRpc, useRpcStatus } from '@devframes/next/client'
+import { useRpc, useRpcStatus } from '@devframes/next/dev-spa/client'
 
 export function Panel() {
   const rpc = useRpc()?.scope('my-tool:')
@@ -119,6 +120,24 @@ Both hooks throw outside a `<RpcProvider>`. Theming and layout stay app-owned.
 
 Route handlers that call `fetch` pin `export const runtime = 'nodejs'`: the static handler streams built SPA files from disk, and the side-car RPC/WS server is a Node process.
 
+## Mounting a hub
+
+`@devframes/next/hub` mounts a whole [devframes-hub](/guide/hub) — many integrations under one namespace — from a single catch-all route. `nextDevframeHub()` returns a route handle memoized on `globalThis` (so Next's dev-time route re-evaluation reuses one instance); `createNextDevframeHub()` is the underlying builder. The UI defaults to `@devframes/hub-ui` (loaded through a bundler-ignored dynamic `import()` so its asset lookups resolve at request time); pass `ui` to swap it or `ui: false` for a headless hub you drive with the React client at `@devframes/next/hub/client` (`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)
+```
+
+Unlike Vite and Nuxt, Next has no native hub viewer, so this scope prints no recommendation. `createDevframeNextHost()` remains available from `@devframes/next/hub` as the lower-level "bring your own `DevframeHost`" seam for `initHub({ context })`.
+
 ## See also
 
 - [Vite Bridge](./vite-bridge) — the equivalent for Vite-based hosts

docs/helpers/nuxt.md

@@ -4,7 +4,9 @@ outline: deep
 
 # Nuxt Helper
 
-The `@devframes/nuxt` module wires a Nuxt-built SPA as a devframe client, and optionally serves the dev-time RPC bridge alongside `nuxt dev`. It runs inside the Nuxt app that consumes your devframe.
+The `@devframes/nuxt/dev-spa` module wires a Nuxt-built SPA as a devframe client, and optionally serves the dev-time RPC bridge alongside `nuxt dev`. It runs inside the Nuxt app that consumes your devframe.
+
+`@devframes/nuxt` splits into two scopes: `@devframes/nuxt/dev-spa` (this page — author one devframe with Nuxt) and [`@devframes/nuxt/hub`](#mounting-a-hub) (mount a whole devframes-hub). The bare `@devframes/nuxt` import throws with a pointer to both.
 
 It handles the four things every Nuxt-powered standalone devtool needs:
 
@@ -17,7 +19,7 @@ It handles the four things every Nuxt-powered standalone devtool needs:
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
-  modules: ['@devframes/nuxt'],
+  modules: ['@devframes/nuxt/dev-spa'],
 })
 ```
 
@@ -45,7 +47,7 @@ export function usePayload() {
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
-  modules: ['@devframes/nuxt'],
+  modules: ['@devframes/nuxt/dev-spa'],
   devframe: {
     baseURL: './', // where the devframe snapshot lives, relative to the page
     skipAppDefaults: false, // opt out of the app.baseURL / vite.base defaults
@@ -64,7 +66,7 @@ Pass your devframe definition to wire `nuxt dev` up to the RPC backend:
 import devframe from './src/devframe' // defineDevframe(...) export
 
 export default defineNuxtConfig({
-  modules: [['@devframes/nuxt', { devframe }]],
+  modules: [['@devframes/nuxt/dev-spa', { devframe }]],
 })
 ```
 
@@ -81,7 +83,7 @@ The bridge is **on by default** whenever `devframe` is set. Skip it (back to cli
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
-  modules: [['@devframes/nuxt', {
+  modules: [['@devframes/nuxt/dev-spa', {
     devframe,
     devMiddleware: {
       port: 7777,
@@ -128,6 +130,18 @@ At build time the module:
 
 At runtime the built SPA fetches `./__connection.json` (resolved against `document.baseURI`) and branches on the `backend` field — `websocket` in dev, `static` from a `createBuild` snapshot.
 
+## Mounting a hub
+
+`@devframes/nuxt/hub` mounts a whole [devframes-hub](/guide/hub) — many integrations under one namespace — alongside `nuxt dev`, wiring `@devframes/vite`'s hub plugin into Nuxt's Vite dev server and injecting `@devframes/hub-ui`'s floating dock. The UI defaults to `@devframes/hub-ui`; pass `ui` to swap it or `ui: false` for a headless hub you drive with `@devframes/nuxt/hub/client`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: [['@devframes/nuxt/hub', { devframes: [] }]],
+})
+```
+
+Nuxt DevTools (`@nuxt/devtools`) integrates the same hub protocol natively and is the recommended path for a Nuxt app, so this module prints a one-time recommendation to that effect (silence it with `{ quiet: true }`).
+
 ## See also
 
 - [Standalone CLI recipe](/guide/standalone-cli) — end-to-end walk-through

docs/helpers/vite-bridge.md

@@ -4,12 +4,14 @@ outline: deep
 
 # @devframes/vite
 
-Two Vite plugins for mounting a devframe inside an existing Vite dev server — `devframeVitePlugin` (static mount) and `devframeViteBridge` (RPC bridge) — plus `devframeVite`, a convenience wrapper that picks between them. Used by [`@devframes/nuxt`](./nuxt) and available for any Vite-based host (Astro, SolidStart, plain Vite apps).
+`@devframes/vite` splits into two scopes: **`@devframes/vite/dev-spa`** (this page — dev-serve one devframe's SPA with Vite) and [**`@devframes/vite/hub`**](#mounting-a-hub) (mount a whole devframes-hub inside a Vite app). The bare `@devframes/vite` import throws with a pointer to both.
+
+The `dev-spa` scope exports two Vite plugins for mounting a single devframe inside an existing Vite dev server — `devframeVitePlugin` (static mount) and `devframeViteBridge` (RPC bridge) — plus `devframeVite`, a convenience wrapper that picks between them. Used by [`@devframes/nuxt`](./nuxt) and available for any Vite-based host (Astro, SolidStart, plain Vite apps).
 
 This sits below the [`vite` adapter](/adapters/vite) on the abstraction ladder: the adapter targets the full Vite DevTools dock; these are the lower-level Vite plugins you reach for when you want a devframe to ride along with an existing app's dev server without the DevTools dock.
 
 ```ts
-import { devframeViteBridge, devframeVitePlugin } from '@devframes/vite'
+import { devframeViteBridge, devframeVitePlugin } from '@devframes/vite/dev-spa'
 import { defineConfig } from 'vite'
 import devframe from './devframe'
 
@@ -50,3 +52,18 @@ To mount the RPC socket onto the Vite server's own port instead of a side-car 
 ## `devframeVite` — convenience wrapper
 
 `devframeVite(def, { bridge, ...bridgeOptions })` forwards to `devframeViteBridge` when `bridge: true`, or `devframeVitePlugin` otherwise — handy when a single call site needs to switch between the two modes. Reach for the two plugins directly when a devframe needs both mounted at once (e.g. a bridge for RPC alongside a static mount serving its own bundled UI, as the built-in `terminals`/`code-server` plugins do).
+
+## Mounting a hub
+
+`@devframes/vite/hub` mounts a whole [devframes-hub](/guide/hub) — many integrations under one namespace, one merged RPC registry — inside a Vite dev server with one `viteDevframeHub()` plugin. It wraps `initHub`, shares Vite's HTTP server for the WebSocket, defaults the dock UI to `@devframes/hub-ui` (injecting its `embedded.js` bootstrap into the host page), and mounts everything as connect middleware.
+
+```ts
+import { viteDevframeHub } from '@devframes/vite/hub'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [viteDevframeHub({ devframes: [] })],
+})
+```
+
+Pass `ui` to swap the viewer or `ui: false` for a headless hub you drive with the client helper at `@devframes/vite/hub/client` (`mountDevframeHubClient()`). Vite DevTools (`@vitejs/devtools-kit`) integrates the same hub protocol natively and is the recommended path for a Vite app, so this plugin prints a one-time recommendation to that effect (silence it with `{ quiet: true }`).

examples/hub-next-minimal/src/client/hub.ts

@@ -1,10 +1,9 @@
-import type { createUi as CreateUi } from '@devframes/hub-ui'
 import type { HubInstance } from '@devframes/hub/initiate'
 import type { DevframeJsonRenderSpec } from '@devframes/json-render'
 import type { jsonRenderUiRenderer as JsonRenderUiRenderer } from '@devframes/json-render-ui/hub'
 import type { DevframeJsonRenderDockEntry } from '@devframes/json-render/hub'
 import type { DevframeDefinition } from 'devframe'
-import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
+import { createNextDevframeHub } from '@devframes/next/hub'
 
 // A server-authored JSON-render dock: the whole view is this serializable
 // spec — no client build. It renders through whatever `'json-render'`
@@ -52,8 +51,7 @@ const BUILTIN_PLUGIN_PACKAGES = [
 ] as const
 
 async function loadHub(): Promise<HubInstance> {
-  const [hubUi, jsonRenderUi, dataInspector, assets, ...builtins] = await Promise.all([
-    import(/* webpackIgnore: true */ /* turbopackIgnore: true */ '@devframes/hub-ui'),
+  const [jsonRenderUi, dataInspector, assets, ...builtins] = await Promise.all([
     import(/* webpackIgnore: true */ /* turbopackIgnore: true */ '@devframes/json-render-ui/hub'),
     import(/* webpackIgnore: true */ /* turbopackIgnore: true */ '@devframes/plugin-data-inspector'),
     import(/* webpackIgnore: true */ /* turbopackIgnore: true */ '@devframes/plugin-assets'),
@@ -70,13 +68,12 @@ async function loadHub(): Promise<HubInstance> {
     (dataInspector.createDataInspectorDevframe as (options: { id: string }) => DevframeDefinition)({ id: 'devframes_plugin_data-inspector' }),
     (assets.createAssetsDevframe as (options: { watch: boolean }) => DevframeDefinition)({ watch: false }),
   ]
-  // Next route handlers can't accept WebSocket upgrades, so the socket asks
-  // for a side-car server of its own, advertised via `__connection.json`.
-  return initHub({
-    base: DEVFRAMES_HUB_BASE,
-    ws: { sidecar: true },
+  // `@devframes/next/hub` runs the socket on a side-car (Next routes can't
+  // accept WS upgrades) and defaults the UI to `@devframes/hub-ui` (loaded
+  // through its own bundler-ignored dynamic import) — the minimal host needs
+  // no client code, just the injected `embedded.js`.
+  return createNextDevframeHub({
     devframes,
-    ui: (hubUi.createUi as typeof CreateUi)(),
     // Serve the reference json-render frontend as a prebuilt renderer module
     // — the one-liner that makes `'json-render'` docks render in the prebuilt
     // viewer. Swap it for any community implementation of the same contract.

examples/hub-next-minimal/src/client/next.config.mjs

@@ -1,4 +1,4 @@
-import { withDevframe } from '@devframes/next'
+import { withDevframe } from '@devframes/next/dev-spa'
 
 // `withDevframe` applies the settings a devframe host requires (currently
 // `skipTrailingSlashRedirect: true`, so mounted SPAs' relative assets under