Merge remote-tracking branch 'origin/main' into antfu/devframe-hub-eval

# Conflicts:
#	pnpm-lock.yaml

Author: antfu

.github/workflows/ecosystem-ci.yml

@@ -0,0 +1,39 @@
+name: Ecosystem CI
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'vitejs/devtools ref to test against (tag, branch, or commit). Defaults to latest released tag.'
+        required: false
+        type: string
+  schedule:
+    - cron: '0 4 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  vitejs-devtools:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test:ecosystem
+        env:
+          ECOSYSTEM_DEVTOOLS_REF: ${{ inputs.ref }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ecosystem-devtools-logs
+          path: |
+            .ecosystem/devtools/**/*.log
+            .ecosystem/devtools/packages/**/test-results/**
+          retention-days: 7

.gitignore

@@ -19,3 +19,4 @@ test-results
 playwright-report
 playwright/.cache
 blob-report
+.ecosystem

docs/guide/built-with.md

@@ -14,3 +14,4 @@ End-to-end examples in this repo, exercising the full adapter surface:
 
 - [**files-inspector**](https://github.com/devframes/devframe/tree/main/examples/files-inspector) — lists files in cwd via RPC; exercises CLI dev/build/spa surfaces.
 - [**streaming-chat**](https://github.com/devframes/devframe/tree/main/examples/streaming-chat) — streams synthetic chat tokens from server to client via `ctx.rpc.streaming`.
+- [**next-runtime-snapshot**](https://github.com/devframes/devframe/tree/main/examples/next-runtime-snapshot) — Next.js App Router SPA over RPC, surfacing the host Node runtime (system info, memory, env).

docs/guide/standalone-cli.md

@@ -100,6 +100,50 @@ export default defineNuxtConfig({
 
 Build with `nuxt build` and point `cli.distDir` at `./dist/public`. The SPA discovers its effective base at runtime — no `--base` rewrite needed. See the [Nuxt helper docs](/helpers/nuxt) for the full reference.
 
+## Next.js SPA setup
+
+For a Next.js App Router SPA, the integration is plain Next.js static export — devframe owns the HTTP and RPC server, Next.js produces the static bundle and stops there. Three config settings cover the integration:
+
+```js [next.config.mjs]
+/** @type {import('next').NextConfig} */
+export default {
+  output: 'export',
+  assetPrefix: '.',
+  trailingSlash: true,
+  images: { unoptimized: true },
+}
+```
+
+- **`output: 'export'`** emits the SPA as static HTML/JS/CSS — no Next.js runtime is needed at serve time. Server Components are pre-rendered at build; Client Components hydrate against the devframe RPC connection.
+- **`assetPrefix: '.'`** is the setting that makes the build base-agnostic. Assets are referenced as `./_next/...` so the same bundle works at `/`, `/__my-tool/`, and any other mount path the host adapter chooses. Without it, Next.js bakes in `/_next/...` and the build only works at the root.
+- **`trailingSlash: true`** emits `foo/index.html` rather than `foo.html`, which composes cleanly with devframe's static-handler directory-with-index resolution.
+
+`next build` writes the export to `<project>/out/` next to `next.config.mjs`. Copy or move that to wherever you point `cli.distDir`:
+
+```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',
+  cli: {
+    distDir: fileURLToPath(new URL('../dist/client', import.meta.url)),
+  },
+  // …
+})
+```
+
+Inside Client Components, call `connectDevframe()` once and share the result via React context. See [Client](./client) for the full reference — the Next.js side is plain React, with no devframe-specific wrapper.
+
+End-to-end example: [`examples/next-runtime-snapshot`](https://github.com/devframes/devframe/tree/main/examples/next-runtime-snapshot).
+
 ## Connecting from the client
 
 With the Nuxt helper installed, use `$rpc` directly:

eslint.config.js

@@ -6,6 +6,9 @@ export default antfu({
   ignores: [
     'skills',
     '**/dist',
+    '**/.next',
+    '**/out',
+    '**/next-env.d.ts',
     '**/.vitepress/cache',
     '**/.vitepress/dist',
   ],

examples/next-runtime-snapshot/.gitignore

@@ -0,0 +1,6 @@
+.next
+dist
+next-env.d.ts
+node_modules
+out
+.turbo

examples/next-runtime-snapshot/README.md

@@ -0,0 +1,60 @@
+# next-runtime-snapshot
+
+End-to-end devframe demo with a **Next.js App Router** SPA. Shows that any
+React+Next.js build is a drop-in replacement for a Preact+Vite SPA: devframe
+serves the static export, the client calls into the host Node process via
+type-safe RPC.
+
+## What it shows
+
+- `next-runtime-snapshot:system` — a `static` RPC function. Runs once at
+  build time when baked into a static dump, otherwise resolved live over
+  WebSocket. Returns Node version, platform/arch, pid, cwd, start time.
+- `next-runtime-snapshot:memory` — a `query` RPC function. Re-runnable;
+  the UI has a refresh button that re-invokes the handler.
+- `next-runtime-snapshot:env` — a `query` RPC function with valibot-validated
+  args (`pattern`, `limit`). Lists environment variables matching a regex,
+  redacting keys that look secret.
+- Next.js App Router with `'use client'` components calling
+  `connectDevframe()` once and passing the RPC client through React context.
+
+## Run it
+
+```sh
+pnpm -C examples/next-runtime-snapshot run build  # next build → static export → dist/client/
+pnpm -C examples/next-runtime-snapshot run dev    # node bin.mjs → devframe CLI
+```
+
+Open `http://localhost:9899/__next-runtime-snapshot/` — the three cards
+populate from RPC, the env filter is debounced, and the footer shows the
+connection backend.
+
+## Build a static deployment
+
+```sh
+pnpm -C examples/next-runtime-snapshot run cli:build
+```
+
+Output lands in `dist/static/`. Serve it from any static host (`npx serve
+dist/static`) — the `static` and `query` RPCs that opted into the dump still
+work because the snapshot is baked at build time.
+
+## Next.js config — three settings worth knowing
+
+`src/client/next.config.mjs` is short on purpose. The three non-defaults
+each correspond to a devframe design principle:
+
+- **`output: 'export'`** — devframe owns the HTTP server; Next.js produces a
+  fully static SPA. No Next.js runtime is required at serve time, so server
+  components and route handlers are rendered at build time only.
+- **`assetPrefix: '.'`** — relative asset paths so the same build works at
+  `/`, `/__next-runtime-snapshot/`, and any custom base. Devframe's design
+  principle: SPAs own their base path at runtime, discovered from
+  `document.baseURI`.
+- **`trailingSlash: true`** — emits `foo/index.html` rather than `foo.html`,
+  which composes cleanly with devframe's static handler directory-with-index
+  resolution.
+
+The `dist/client/` artifact is a copy of `src/client/out/` (Next.js's
+default export directory) — the `build` script just renames it so the
+example matches the layout used by the other examples in this repo.

examples/next-runtime-snapshot/bin.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import process from 'node:process'
+import { createCli } from 'devframe/adapters/cli'
+import devframe from './src/devframe.ts'
+
+async function main() {
+  const cli = createCli(devframe)
+  await cli.parse()
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

examples/next-runtime-snapshot/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "next-runtime-snapshot-example",
+  "type": "module",
+  "version": "0.4.1",
+  "private": true,
+  "description": "End-to-end devframe demo — Next.js App Router SPA over RPC, exposing the host Node runtime snapshot (system info, memory, env).",
+  "main": "src/devframe.ts",
+  "bin": {
+    "next-runtime-snapshot": "./bin.mjs"
+  },
+  "scripts": {
+    "build": "next build src/client && rm -rf dist/client && mkdir -p dist && cp -r src/client/out dist/client",
+    "cli:build": "node bin.mjs build --out-dir dist/static",
+    "dev": "node bin.mjs",
+    "next:dev": "next dev src/client",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "devframe": "workspace:*",
+    "next": "catalog:frontend",
+    "react": "catalog:frontend",
+    "react-dom": "catalog:frontend"
+  },
+  "devDependencies": {
+    "@types/react": "catalog:types",
+    "@types/react-dom": "catalog:types",
+    "get-port-please": "catalog:deps",
+    "h3": "catalog:deps",
+    "vitest": "catalog:testing",
+    "ws": "catalog:deps"
+  }
+}

examples/next-runtime-snapshot/src/client/app/components/connect.tsx

@@ -0,0 +1,42 @@
+'use client'
+
+import type { DevToolsRpcClient } from 'devframe/client'
+import type { ReactNode } from 'react'
+import { connectDevframe } from 'devframe/client'
+import { createContext, useContext, useEffect, useState } from 'react'
+
+interface ConnectionState {
+  rpc: DevToolsRpcClient | null
+  error: string | null
+}
+
+const RpcContext = createContext<ConnectionState>({ rpc: null, error: null })
+
+export function useRpc(): ConnectionState {
+  return useContext(RpcContext)
+}
+
+export function RpcProvider({ children }: { children: ReactNode }) {
+  const [state, setState] = useState<ConnectionState>({ rpc: null, error: null })
+
+  useEffect(() => {
+    let cancelled = false
+    connectDevframe().then(
+      (rpc) => {
+        if (!cancelled)
+          setState({ rpc, error: null })
+      },
+      (err: unknown) => {
+        if (cancelled)
+          return
+        const message = err instanceof Error ? err.message : String(err)
+        setState({ rpc: null, error: message })
+      },
+    )
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  return <RpcContext.Provider value={state}>{children}</RpcContext.Provider>
+}