feat(next): evolve client surface + adopt it in next-runtime-snapshot

- Drop the experimental npm dist-tag (publishConfig); the package stays flagged
  experimental in its description and docs only, matching the other packages.
- RpcProvider now renders children eagerly and exposes live connection state:
  useRpc() returns the client or null, useRpcStatus() returns { status, error }
  (subscribed to the client's connection:status / connection:error events).
- Apply @devframes/next/client to examples/next-runtime-snapshot: its connect
  provider is now a thin adapter over the package (the host/handler adapter
  stays N/A there since devframe owns the server via createCac). Wire the turbo
  build edge and regenerate the client API snapshot.

Author: antfubot

docs/helpers/next.md

@@ -5,7 +5,7 @@ outline: deep
 # Next Helper
 
 > [!WARNING]
-> Experimental. `@devframes/next` is published under the `experimental` npm tag (`npm i @devframes/next@experimental`) while its API settles. Expect changes before a stable release.
+> 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. 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.
 
@@ -95,7 +95,7 @@ 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.
+`@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.
 
 ```tsx [app/providers.tsx]
 'use client'
@@ -106,17 +106,22 @@ export function Providers({ children }: { children: React.ReactNode }) {
 }
 ```
 
+`useRpc()` returns the connected `DevframeRpcClient`, or `null` while connecting; scope it to your tool's namespace. `useRpcStatus()` returns the live `{ status, error }` for a connection indicator.
+
 ```tsx [app/panel.tsx]
 'use client'
-import { useRpc } from '@devframes/next/client'
+import { useRpc, useRpcStatus } from '@devframes/next/client'
 
 export function Panel() {
-  const rpc = useRpc().scope('my-tool:')
-  // rpc.call('get-payload'), rpc.sharedState, …
+  const rpc = useRpc()?.scope('my-tool:')
+  const { status, error } = useRpcStatus()
+  if (!rpc)
+    return <p>{error ? `connection failed — ${error.message}` : 'connecting…'}</p>
+  // rpc.rpc.call('get-payload'), rpc.sharedState, …
 }
 ```
 
-`RpcProvider` renders its `fallback` (default `null`) until the client connects, so `useRpc()` always returns a live client. Theming and layout stay app-owned.
+Both hooks throw outside a `<RpcProvider>`. Theming and layout stay app-owned.
 
 ## Runtime
 

examples/next-runtime-snapshot/package.json

@@ -19,6 +19,7 @@
   },
   "dependencies": {
     "@antfu/design": "catalog:frontend",
+    "@devframes/next": "workspace:*",
     "cac": "catalog:deps",
     "colorjs.io": "catalog:frontend",
     "devframe": "workspace:*",

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

@@ -2,8 +2,8 @@
 
 import type { DevframeScopedClientContext } from 'devframe/client'
 import type { ReactNode } from 'react'
-import { connectDevframe } from 'devframe/client'
-import { createContext, useContext, useEffect, useState } from 'react'
+import { RpcProvider as DevframeRpcProvider, useRpc as useDevframeRpc, useRpcStatus } from '@devframes/next/client'
+import { useMemo } from 'react'
 
 // Inlined (not imported from the server `rpc/index.ts`) so the client
 // bundle stays free of node-only server code.
@@ -16,33 +16,20 @@ interface ConnectionState {
   error: string | null
 }
 
-const RpcContext = createContext<ConnectionState>({ ctx: null, error: null })
-
-export function useRpc(): ConnectionState {
-  return useContext(RpcContext)
-}
-
+/**
+ * Connect to the RPC backend via `@devframes/next/client` — the connect +
+ * status machinery lives in the package now; this file only scopes the client
+ * to this tool's namespace and reshapes the status for the local UI.
+ */
 export function RpcProvider({ children }: { children: ReactNode }) {
-  const [state, setState] = useState<ConnectionState>({ ctx: null, error: null })
-
-  useEffect(() => {
-    let cancelled = false
-    connectDevframe().then(
-      (rpc) => {
-        if (!cancelled)
-          setState({ ctx: rpc.scope(NAMESPACE), error: null })
-      },
-      (err: unknown) => {
-        if (cancelled)
-          return
-        const message = err instanceof Error ? err.message : String(err)
-        setState({ ctx: null, error: message })
-      },
-    )
-    return () => {
-      cancelled = true
-    }
-  }, [])
+  return <DevframeRpcProvider>{children}</DevframeRpcProvider>
+}
 
-  return <RpcContext.Provider value={state}>{children}</RpcContext.Provider>
+export function useRpc(): ConnectionState {
+  const rpc = useDevframeRpc()
+  const { error } = useRpcStatus()
+  // `rpc` is stable once resolved, so memoizing on it keeps `ctx` referentially
+  // stable across renders (the snapshot components depend on `ctx` identity).
+  const ctx = useMemo(() => (rpc ? rpc.scope(NAMESPACE) : null), [rpc])
+  return { ctx, error: error ? error.message : null }
 }

packages/next/package.json

@@ -34,10 +34,6 @@
   "files": [
     "dist"
   ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "experimental"
-  },
   "scripts": {
     "build": "tsdown",
     "watch": "tsdown --watch",

packages/next/src/client.tsx

@@ -1,12 +1,23 @@
 'use client'
 
-import type { DevframeRpcClient } from 'devframe/client'
+import type { DevframeConnectionStatus, DevframeRpcClient } from 'devframe/client'
 import type { ConnectionMeta } from 'devframe/types'
 import type { ReactNode } from 'react'
 import { connectDevframe } from 'devframe/client'
 import { createContext, useContext, useEffect, useState } from 'react'
 
-const RpcContext = createContext<DevframeRpcClient | null>(null)
+export interface DevframeRpcState {
+  /** The connected client, or `null` while the initial connect is in flight. */
+  rpc: DevframeRpcClient | null
+  /** Live connection status — `'connecting'` until the client resolves. */
+  status: DevframeConnectionStatus
+  /** The latest connection error, or `null`. */
+  error: Error | null
+}
+
+const RpcContext = createContext<DevframeRpcState | null>(null)
+
+const INITIAL: DevframeRpcState = { rpc: null, status: 'connecting', error: null }
 
 export interface RpcProviderProps {
   children: ReactNode
@@ -21,21 +32,16 @@ export interface RpcProviderProps {
    * fetch entirely (e.g. when the host already knows the WS endpoint).
    */
   connectionMeta?: ConnectionMeta
-  /**
-   * Rendered while the client is connecting. Children mount only once the RPC
-   * client is ready, so {@link useRpc} always returns a live client. Defaults
-   * to `null`.
-   */
-  fallback?: ReactNode
 }
 
 /**
- * Connect to the devframe RPC backend once and provide the client to the tree.
+ * Connect to the devframe RPC backend once and provide the client — plus live
+ * connection status — to the tree. The React counterpart to `@devframes/nuxt`'s
+ * client plugin.
  *
- * The React counterpart to `@devframes/nuxt`'s client plugin: it calls
- * `connectDevframe()` on mount and exposes the result through {@link useRpc}.
- * Being a client component, drop it into a Next layout or page and read the
- * client from any descendant.
+ * Children render immediately (before the connection resolves), so your shell
+ * and a connection indicator stay visible throughout; read the client with
+ * {@link useRpc} and the status with {@link useRpcStatus}.
  *
  * ```tsx
  * 'use client'
@@ -50,37 +56,66 @@ export function RpcProvider({
   children,
   baseURL = './',
   connectionMeta,
-  fallback = null,
 }: RpcProviderProps): ReactNode {
-  const [rpc, setRpc] = useState<DevframeRpcClient | null>(null)
+  const [state, setState] = useState<DevframeRpcState>(INITIAL)
 
   useEffect(() => {
     let active = true
-    void connectDevframe({ baseURL, connectionMeta }).then((client) => {
-      if (active)
-        setRpc(client)
-    })
+    let client: DevframeRpcClient | undefined
+    const sync = (): void => {
+      if (active && client)
+        setState({ rpc: client, status: client.status, error: client.connectionError })
+    }
+
+    const offs: Array<() => void> = []
+    void connectDevframe({ baseURL, connectionMeta }).then(
+      (c) => {
+        if (!active)
+          return
+        client = c
+        sync()
+        offs.push(c.events.on('connection:status', sync))
+        offs.push(c.events.on('connection:error', sync))
+      },
+      (err: unknown) => {
+        if (active)
+          setState({ rpc: null, status: 'error', error: err instanceof Error ? err : new Error(String(err)) })
+      },
+    )
+
     return () => {
       active = false
+      for (const off of offs)
+        off()
     }
     // `connectionMeta` is a plain descriptor; re-connect only when the base changes.
   }, [baseURL])
 
-  if (!rpc)
-    return fallback
+  return <RpcContext.Provider value={state}>{children}</RpcContext.Provider>
+}
 
-  return <RpcContext.Provider value={rpc}>{children}</RpcContext.Provider>
+function useDevframeState(): DevframeRpcState {
+  const state = useContext(RpcContext)
+  if (!state)
+    throw new Error('[@devframes/next] useRpc()/useRpcStatus() must be called inside a <RpcProvider>.')
+  return state
 }
 
 /**
- * Read the connected {@link DevframeRpcClient} provided by {@link RpcProvider}.
- * Scope it to your tool's RPC namespace with `useRpc().scope('my-tool:…')`.
+ * Read the connected {@link DevframeRpcClient}, or `null` while connecting.
+ * Scope it to your tool's RPC namespace with `useRpc()?.scope('my-tool:')`.
  *
  * Throws when called outside a `<RpcProvider>`.
  */
-export function useRpc(): DevframeRpcClient {
-  const rpc = useContext(RpcContext)
-  if (!rpc)
-    throw new Error('[@devframes/next] useRpc() must be called inside a <RpcProvider>.')
-  return rpc
+export function useRpc(): DevframeRpcClient | null {
+  return useDevframeState().rpc
+}
+
+/**
+ * Read the live connection `status` and latest `error`, for a connection
+ * indicator. Throws when called outside a `<RpcProvider>`.
+ */
+export function useRpcStatus(): { status: DevframeConnectionStatus, error: Error | null } {
+  const { status, error } = useDevframeState()
+  return { status, error }
 }

plans/notes/devframes-next-proposal.md

@@ -133,23 +133,28 @@ STOP condition (contract divergence) does not trip.
    side-car against a temp `distDir` and asserts SPA serving, SPA fallback, the
    WS-port meta, and a bare 404).
 2. **Client surface — implemented** at `@devframes/next/client` (React peer,
-   optional). `RpcProvider` calls `connectDevframe()` once and provides the
-   client; `useRpc()` reads it (throwing outside a provider). The `'use client'`
-   directive is preserved through the browser build. A theme/layout helper was
-   deliberately left out — theming is design-system-specific and stays
-   app-owned.
-3. **Publishing shape — done.** `private` dropped; `publishConfig.tag:
-   "experimental"` publishes under the `experimental` tag, not `latest`. `next`
-   and `react` are optional peers; exports are `.` (Node) + `./client`
-   (browser). tsnapi snapshots generated under
+   optional). `RpcProvider` calls `connectDevframe()` once and renders children
+   eagerly (so a shell + connection indicator stay visible while connecting);
+   `useRpc()` returns the client or `null`, and `useRpcStatus()` exposes the live
+   `{ status, error }` (subscribed to the client's `connection:status` /
+   `connection:error` events). The `'use client'` directive is preserved through
+   the browser build. A theme/layout helper was deliberately left out — theming
+   is design-system-specific and stays app-owned.
+3. **Publishing shape — done.** `private` dropped so the package publishes with
+   the rest of the workspace; it's flagged experimental in its description and
+   the docs (no npm dist-tag). `next` and `react` are optional peers; exports are
+   `.` (Node) + `./client` (browser). tsnapi snapshots generated under
    `tests/__snapshots__/tsnapi/@devframes/next/` (`index` + `client`).
 4. **404 body — parity added.** The host `fetch` normalizes any miss to a
    body-less `404`, matching a plain static server (h3's default JSON error body
    is dropped).
-5. **`next-runtime-snapshot` needs no bridge.** It uses Next only as a static-SPA
-   builder while devframe owns the server via `createCac`/`createBuild`; the
-   bridge doesn't apply. Left as-is (recorded so a future reader doesn't try to
-   "unify" the two Next examples).
+5. **`next-runtime-snapshot` — client surface adopted; host part N/A.** It uses
+   Next only as a static-SPA builder while devframe owns the server via
+   `createCac`/`createBuild`, so the host/handler adapter (route handlers) still
+   doesn't apply. Its hand-rolled connect provider, however, was migrated onto
+   `@devframes/next/client`: `connect.tsx` is now a thin adapter that delegates
+   connect + status to the package and only scopes the client to the example's
+   namespace — a second consumer that validated the eager-render + status API.
 
 ## Files
 

pnpm-lock.yaml

@@ -2,15 +2,23 @@
  * Generated by tsnapi — public API snapshot of `@devframes/next/client`
  */
 // #region Interfaces
+export interface DevframeRpcState {
+  rpc: DevframeRpcClient | null;
+  status: DevframeConnectionStatus;
+  error: Error | null;
+}
 export interface RpcProviderProps {
   children: ReactNode;
   baseURL?: string;
   connectionMeta?: ConnectionMeta;
-  fallback?: ReactNode;
 }
 // #endregion
 
 // #region Functions
-export declare function RpcProvider({ children, baseURL, connectionMeta, fallback }: RpcProviderProps): ReactNode;
-export declare function useRpc(): DevframeRpcClient;
+export declare function RpcProvider({ children, baseURL, connectionMeta }: RpcProviderProps): ReactNode;
+export declare function useRpc(): DevframeRpcClient | null;
+export declare function useRpcStatus(): {
+  status: DevframeConnectionStatus;
+  error: Error | null;
+};
 // #endregion

tests/__snapshots__/tsnapi/@devframes/next/client.snapshot.d.ts

@@ -4,4 +4,5 @@
 // #region Functions
 export function RpcProvider(_) {}
 export function useRpc() {}
+export function useRpcStatus() {}
 // #endregion

tests/__snapshots__/tsnapi/@devframes/next/client.snapshot.js

@@ -110,7 +110,7 @@
     },
     "next-runtime-snapshot-example#build": {
       "outputLogs": "new-only",
-      "dependsOn": ["devframe#build"],
+      "dependsOn": ["devframe#build", "@devframes/next#build"],
       "outputs": ["dist/**"]
     },
     "@devframes/plugin-git#build": {