refactor(examples): standardize devframe tool examples to app/ + src/node/ + playgrounds/ by antfubot · Pull Request #341 · devframes/devframe

antfubot · 2026-09-03T07:32:31Z

What

Apply the built-in plugin layout (now on main after #340) to the example projects that define a devframe, so the examples teach the same structure the plugins use:

examples/<tool>/
  app/            # frontend web app (built by the framework)
  src/node/       # node side (definition + rpc)
  playgrounds/    # a host that boots the built tool (the play target)

Each restructured tool gets the convention's run scripts: dev serves the app with HMR while bridging the node side live (RPC + WebSocket/SSE + __connection.json), and play builds then boots the playground against the built output.

Per-example

files-inspector, streaming-chat (Preact): app/ = SPA, src/node/ = definition + rpc/; new playgrounds/server.mjs; dev = Vite + serve-only node bridge, play = build then playground.
sse-basic: extracted the inline definition out of the root vite.config.ts into src/node/, moved the client into app/, kept it SSE-only; added dev/play.
next-runtime-snapshot (Next.js): app/ = the Next app, src/node/ = definition + rpc/; scripts/build-spa.mjs now copies the static export with explicit file modes (Next's export trips node's cpSync); added playgrounds/ + play.
json-render (no own SPA, reuses the prebuilt @devframes/json-render-ui): consolidated the definition, dashboard, and shared code under src/node/ and retargeted the . / ./dashboard exports; its CLI run flow is unchanged since it has no app to serve.

Scope

The framework host examples (hub-vite, hub-next, the minimal Nitro/SvelteKit/Deno/Fastify/Hono/Next/Vite hosts, a11y-messages-playground, demo-dock-client) mount devframes rather than defining one, so they keep their framework-idiomatic layouts (routes/, catch-all handlers, etc.). Only the five tool examples change.

Reconciled

json-render/dashboard alias, tsconfig.base.json paths, and the next-runtime-snapshot knip PostCSS config.

Validation

pnpm typecheck (cold cache): coverage OK + 39/39
pnpm lint, pnpm knip: clean
All five example builds pass (including the Next static export copy)
dev bridge and play host smoke-tested on the restructured tools (panel + __connection.json served)

This PR was created with the help of an agent.

…node/ + playgrounds/ Apply the built-in plugin layout to the five examples that define a devframe: - files-inspector, streaming-chat (Preact): app/ = SPA, src/node/ = definition + rpc, playgrounds/ boots the built tool; dev serves the app with HMR + a live node bridge, play builds then runs the playground - sse-basic: extract the inline definition into src/node/, move the client into app/, keep the SSE-only bridge; add dev/play - next-runtime-snapshot (Next): app/ = the Next app, src/node/ = definition + rpc, scripts/build-spa.mjs uses a mode-explicit recursive copy; add playgrounds/ + play - json-render (no own SPA, reuses the prebuilt UI): consolidate the definition, dashboard, and shared code under src/node/; retarget the ./ and ./dashboard exports - update json-render/dashboard alias, tsconfig.base paths, and the next-runtime-snapshot knip postcss config The framework HOST examples (hub-*, a11y-messages-playground, demo-dock-client) mount devframes rather than defining one, so they keep their framework-idiomatic layouts.

coldtea-pr-lens · 2026-09-03T07:32:35Z

◈ PR Lens

🟢 +8 new · 🟠 ~15 changed · 🔴 -0 removed · 3 flows · 56 files · commit 314bd79

Architecture

23 components touched across 4 lanes.

Open full size

Inside the changed components — 4 views

Component view — Files Inspector Devframe

Internal components of the Files Inspector tool separating the Preact SPA panel, Vite dev bridge plugin, Node RPC service, playground server, and CAC CLI.

Component view — SSE Basic Devframe

Modular decomposition of the SSE-only devframe into a dedicated Node definition, vanilla client SPA, Vite dev bridge, and standalone playground runner.

Component view — Streaming Chat Devframe

Internal architecture of the Streaming Chat tool separating the Preact chat panel, token streaming channels, Vite dev bridge, and playground host.

Component view — Next Runtime Snapshot Devframe

Next.js App Router client SPA, permission-normalizing static build packager, playground host, and runtime metrics RPC service.

Data flow

Vite Dev Server RPC & HMR Bridging · SSE-Only Transport Stream & Action Calls · Standalone Playground Host Execution

Open full size

The other flows — 2 sequences

SSE-Only Transport Stream & Action Calls

Standalone Playground Host Execution

Drill down

Client SPAs ＆ UI Panels — 4 components

🟡 CHANGED Files Inspector SPA

Preact panel interface with client-side routing, theme styling, and RPC bindings.

🟡 CHANGED SSE Basic Vanilla UI

Zero-framework HTML/JS client subscribing to server-sent events and invoking actions via HTTP POST.

🟡 CHANGED Streaming Chat Preact UI

Interactive chat panel reading token streams with real-time markdown display and cancel controls.

🟡 CHANGED Next.js Snapshot UI Panel

Next.js App Router client components displaying live CPU, memory, and environment snapshots.

Example Hosts ＆ Dev Bridges — 13 components

🟡 CHANGED Files Inspector Tool

Standalone file exploration devframe featuring Preact panel SPA, Vite dev bridge, and Node RPC engine.

🟡 CHANGED Streaming Chat Tool

Standalone AI chat devframe streaming synthetic tokens over WebSocket RPC with replay history.

🟡 CHANGED Next Runtime Snapshot Tool

Devframe demo exposing system metrics via Next.js App Router SPA with dev/export configuration.

🟡 CHANGED SSE Basic Tool

Minimal HTTP/SSE devframe serving queries, actions, and a streaming clock without WebSockets.

🟡 CHANGED JSON-Render Tool

Standalone devframe serving declarative JSON dashboard specifications through the prebuilt UI.

🟢 NEW Vite Dev Bridge Plugin

Serve-only Vite plugin bridging node RPC, WebSocket, and connection metadata to the dev server.

examples/files-inspector/app/vite.config.ts:1-50

🟢 NEW Files Inspector Playground

Standalone Node HTTP server hosting the built SPA panel and live WebSocket RPC.

examples/files-inspector/playgrounds/server.mjs:1-65

🟢 NEW Vite SSE Dev Bridge

Vite serve plugin attaching SSE middleware to handle discovery and event streams without WebSockets.

examples/sse-basic/app/vite.config.ts:1-63

🟢 NEW SSE Basic Playground

Standalone H3/Node server serving the compiled SPA and SSE endpoints over pure HTTP.

examples/sse-basic/playgrounds/server.mjs:1-69

🟢 NEW Streaming Chat Vite Bridge

Vite plugin hooking devframe nodeMiddleware onto Vite dev server with WebSocket upgrades.

examples/streaming-chat/app/vite.config.ts:1-53

🟢 NEW Streaming Chat Playground

Standalone demo host serving prebuilt SPA and WebSocket RPC stream.

examples/streaming-chat/playgrounds/server.mjs:1-70

🟢 NEW Snapshot Playground Host

Standalone H3/Node server hosting the static Next.js export and WebSocket RPC endpoint.

examples/next-runtime-snapshot/playgrounds/server.mjs:1-57

🟡 CHANGED Static Export Builder

Build script copying and permission-normalizing Next.js static export files into dist/client.

examples/next-runtime-snapshot/scripts/build-spa.mjs:1-23

Devframe Core ＆ Services — 6 components

🟡 CHANGED Files Inspector RPC Service

Devframe definition registering scoped directory listing and cwd query RPC functions.

🟡 CHANGED Files Inspector CAC CLI

Command-line entry point delegating to devframe CAC adapter for dev and static builds.

examples/files-inspector/bin.mjs:1-14

🟢 NEW SSE Devframe Definition

Devframe definition providing uptime queries, increment actions, and an SSE broadcast clock.

examples/sse-basic/src/node/index.ts:1-46

🟡 CHANGED Streaming Chat Node Service

Devframe definition managing synthetic token generation, streaming channels, and pruned message history.

🟡 CHANGED Streaming Chat CAC CLI

CLI entry point running dev server or exporting static distributions.

examples/streaming-chat/bin.mjs:1-14

🟡 CHANGED Runtime Snapshot RPC Service

Devframe definition registering Node process info, env variables, and memory polling.

View

Architecture lens
Data flow lens
Expand every detail
Show unchanged neighbours

Tip

PR Lens is free for open source. A star on the repository is what keeps it going.

🪧 More tips

Run PR Lens on your own machine: npx skills add coldteadotai/pr-lens installs the agent skill. Then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
Draw a diff before it is even a pull request: npx @coldtea/pr-lens-cli analyze --base origin/main reads the diff with your own model key, and npx @coldtea/pr-lens-cli render .pr-lens/graph.json draws the same lenses on your machine.
The boxes under View are live. Tick Architecture lens or Data flow lens to choose which diagrams appear, or Expand every detail to open every drill-down at once. The comment redraws in place a few seconds later.
Show unchanged neighbours lists the components this change did not touch alongside the ones it did, so the drill-down shows what the changed code sits next to.
GitHub will not let you zoom an image in a comment. The link under each diagram opens it full size on a page of its own, where you can.
The CLI's render picks up .github/pr-lens.yml automatically and applies your corrections (renames, exclusions, lane pins) at draw time.
Would you rather run it from CI on a key of your own? Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and a model key in your repository secrets, say GEMINI_API_KEY. The Action asks Gemini by default, or OpenAI and any endpoint speaking /chat/completions through its provider input.
Push a new commit and the whole comment re-renders for the new head. An older run never overwrites a newer one, so a slow render cannot put a stale diagram back.
The diagrams follow your GitHub theme, so dark mode gets the dark render and light mode the light one, and the moving dots show this pull request's data in motion.

◈ Rendered by PR Lens · crafted with ❤️ by the Coldtea team · Something drawn wrong?

vercel · 2026-09-03T07:32:36Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
devframe	Ready	Preview	Sep 3, 2026 7:34am UTC

vercel Bot deployed to Preview September 3, 2026 07:34 View deployment

antfu merged commit c2bd9c8 into main Sep 3, 2026
14 checks passed

antfu deleted the chore/examples-structure branch September 3, 2026 07:38

Navigation Menu

Uh oh!

refactor(examples): standardize devframe tool examples to app/ + src/node/ + playgrounds/ - #341

refactor(examples): standardize devframe tool examples to app/ + src/node/ + playgrounds/#341
antfu merged 1 commit into
mainfrom
chore/examples-structure

antfubot commented Sep 3, 2026

Uh oh!

coldtea-pr-lens Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

antfubot commented Sep 3, 2026

What

Per-example

Scope

Reconciled

Validation

Uh oh!

coldtea-pr-lens Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

◈ PR Lens

Uh oh!

vercel Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coldtea-pr-lens Bot commented Sep 3, 2026 •

edited

Loading

vercel Bot commented Sep 3, 2026 •

edited

Loading