docs: tighten and warm up the Data Inspector tutorial

Author: antfubot

docs/content/1.guide/1.tutorial.md

@@ -3,48 +3,28 @@ title: 'Tutorial: Build a Data Inspector'
 description: 'Build a small devtool from an empty folder — a live view into your server''s state — then grow it one capability at a time: a dock in a hub, a static build, a standalone server, and a CLI.'
 ---
 
-In this walkthrough you build a real devtool from an empty folder: a **Data Inspector** that shows the shape of your server's live state and lets you read any value out of it. You'll get it working end to end first, then add one capability at a time — a dock inside a hub, a static build, a standalone server, and a CLI.
+Let's build a real devtool from nothing: a **Data Inspector** that shows the shape of your server's live state and lets you read any value out of it. We'll get it working first, then teach it new tricks one at a time — a dock in a hub, a static build, a standalone server, a CLI.
 
-Each step introduces exactly one new idea. Nothing here assumes you've read the rest of the guide; links point to the deeper reference when you want it.
+One new idea per step, nothing assumed. You'll need **Node 24+** (so `node` runs TypeScript directly) and a terminal.
 
-**You'll need** Node 24+ (so `node` runs the TypeScript files directly) and a terminal. Every code block is complete — copy them as you go.
+## The shape of a devframe app
 
-## What we're building
+Two halves talk over a typed connection: a **server** half in your Node process that exposes functions, and a **browser** half that calls them and shows the answers. Devframe is everything in between — the wire, the UI hosting, auth, builds, a CLI. Write the two halves once; run them anywhere.
 
-A devframe app has two halves that talk over a typed connection:
+## Step 1 — Define the tool
 
-- a **server** half that runs in your Node process and exposes functions (here: "what does the state look like?" and "give me the value at this path"),
-- a **browser** half — a small web UI that calls those functions and shows the answers.
-
-Devframe's job is the wire between them, plus everything around it: serving the UI, the live connection, authentication, static builds, a CLI. You write the two halves once; devframe runs them everywhere.
-
-Let's start.
-
-## Step 0 — An empty project
-
-Make a folder and initialize it:
+Everything starts with `defineDevframe`: your tool's name, plus a `setup` where you register what it can do. Create the project and the definition:
 
 ```sh
 mkdir data-inspector && cd data-inspector
-npm init -y
-npm pkg set type=module
-npm install devframe
-npm install -D typescript
+npm init -y && npm pkg set type=module
+npm install devframe && npm install -D typescript
 ```
 
-That's the only dependency for the first milestone. We'll add more as each capability calls for it.
-
-## Step 1 — Define the tool and its first function
-
-Everything begins with one call: `defineDevframe`. It pairs your tool's identity with a `setup` function where you register what it can do.
-
-Create `src/devframe.ts`:
-
 ```ts [src/devframe.ts]
 import { defineDevframe } from 'devframe'
 
-// The live server state our tool inspects. In a real app this might be your
-// config, a cache, a database handle — anything living in the process.
+// Whatever you want to peek at while your app runs — config, a cache, a DB handle.
 const serverState = {
   config: { name: 'Acme', port: 3000, debug: false },
   users: [
@@ -54,7 +34,7 @@ const serverState = {
   featureFlags: { newDashboard: true, betaSearch: false },
 }
 
-// Walk a dot-path like `users.0.name` down into a nested value.
+// Follow a dot-path like `users.0.name` into the state.
 function valueAtPath(root: unknown, path: string): unknown {
   if (!path)
     return root
@@ -75,7 +55,7 @@ export default defineDevframe({
   importMetaUrl: import.meta.url,
 
   setup(ctx) {
-    // A read-only call describing the top-level shape of the state.
+    // What does the state look like?
     ctx.rpc.register({
       name: 'data-inspector:get-meta',
       type: 'query',
@@ -88,7 +68,7 @@ export default defineDevframe({
         })),
     })
 
-    // A read-only call that resolves a dot-path against the live state.
+    // What's at this path?
     ctx.rpc.register({
       name: 'data-inspector:query',
       type: 'query',
@@ -99,24 +79,17 @@ export default defineDevframe({
 })
 ```
 
-Two ideas landed here:
-
-- **The definition** — `id`, `name`, and a bit of metadata identify the tool; `setup(ctx)` is where you wire up its capabilities. (Every field is covered in [Devframe Definition](/guide/devframe-definition).)
-- **RPC functions** — `ctx.rpc.register` publishes a function the browser can call. Each has a namespaced `name`, a `type` (`query` means read-only), and a `handler`. The handler receives the call's arguments and returns a value; `jsonSerializable: true` promises the result is plain JSON. ([RPC](/guide/rpc) covers the other types.)
-
-There's no UI yet, and nothing runs. Both come next.
+`ctx.rpc.register` publishes a function the browser can call: a namespaced `name`, a `type` (`query` is read-only), and a `handler` that takes the call's arguments and returns JSON. That's the whole server. ([RPC](/guide/rpc) has the other types; [Devframe Definition](/guide/devframe-definition) has every field.)
 
-## Step 2 — A browser UI that calls the functions
+## Step 2 — Add a UI
 
-Now the other half. We'll use React with Vite — pick any framework you like; the only devframe-specific part is `connectDevframe`, which opens the typed connection back to the server.
+Now the browser half. We'll use React, but any framework works — the only devframe-specific line is `connectDevframe`, which opens the connection home.
 
 ```sh
 npm install react react-dom @devframes/vite
 npm install -D vite @vitejs/plugin-react @types/react @types/react-dom
 ```
 
-Create the UI in a `client/` folder:
-
 ```html [client/index.html]
 <!doctype html>
 <html>
@@ -152,9 +125,8 @@ export function App() {
   const [result, setResult] = useState<unknown>()
 
   useEffect(() => {
-    // Connect once. With no argument, the client discovers where the server
-    // lives from the page's own URL — so this works unchanged no matter how
-    // the tool ends up hosted (dev server, hub, standalone).
+    // No argument: the client finds the server from the page's own URL, so
+    // this line never changes no matter how the tool is hosted.
     connectDevframe().then(async (client) => {
       setRpc(client)
       const call = client.call as (name: string, ...args: unknown[]) => Promise<any>
@@ -190,15 +162,11 @@ export function App() {
 }
 ```
 
-`connectDevframe()` returns a client whose `.call(name, ...args)` reaches your server functions. (We cast `.call` to call by name for brevity; once you register functions through a typed registry, every call is checked end to end — see [RPC](/guide/rpc).)
-
-Still nothing to run — the two halves aren't connected yet.
-
-## Step 3 — Run it (the MVP)
+`client.call(name, ...args)` reaches your handlers. (We cast `.call` to call by name; wire up a typed registry later and every call is checked end to end — see [RPC](/guide/rpc).)
 
-The server half needs to be served *somewhere*. The quickest way while developing is to let Vite's dev server host the UI and hand the RPC traffic to devframe. `@devframes/vite` provides exactly that bridge.
+## Step 3 — Run it
 
-Create `vite.config.ts`:
+The two halves still need to meet. While developing, let Vite serve the UI and hand RPC traffic to devframe:
 
 ```ts [vite.config.ts]
 import { devframeViteBridge } from '@devframes/vite/single'
@@ -212,53 +180,44 @@ export default defineConfig({
   build: { outDir: '../dist/client', emptyOutDir: true },
   plugins: [
     react(),
-    // Vite serves the UI; this bridge answers the RPC, live connection, and
-    // discovery on the same origin (`base: '/'`), so `connectDevframe()` finds
-    // it with no configuration. `auth: false` keeps this local-only demo
-    // frictionless — see the security note below.
+    // Vite serves the page; the bridge answers RPC on the same origin, so
+    // `connectDevframe()` just finds it. `auth: false` — see the note below.
     devframeViteBridge(devframe, { base: '/', auth: false }),
   ],
 })
 ```
 
-Run it:
-
 ```sh
 npx vite
 ```
 
-Open the printed URL. You should see the three top-level keys with their types, and typing a path like `config.port` or `users.0.name` and pressing **Query** prints the value. That round trip — button → `rpc.call` → your `handler` → back to the page — is a devframe app working.
+Open the printed URL. Three keys with their types show up, and typing `config.port` or `users.0.name` and hitting **Query** prints the value. Button → `call` → your `handler` → back to the page: that's the whole app, working.
 
 > [!WARNING]
-> `auth: false` trusts any connection that can reach the port. It's fine for a localhost demo, but leave it off (devframe gates with a one-time code by default) for anything reachable beyond your machine. See [Security](/guide/security).
-
-That's the **MVP**: one definition, two functions, a UI, live over a dev server. Everything from here reuses this exact `src/devframe.ts` and `client/` — we only change how they're *hosted*.
+> `auth: false` trusts anything that can reach the port — fine for localhost, but leave it out (devframe gates with a one-time code by default) for anything reachable from elsewhere. See [Security](/guide/security).
 
-## Step 4 — Show it as a dock in a hub
+Everything below reuses this exact `src/devframe.ts` and `client/`. We only change where they run.
 
-A [hub](/guide/hub) gathers many devframes behind one interface, each appearing as a **dock** you switch between — the tool's own UI shown in an iframe. Because our client already connects with a bare `connectDevframe()`, it works wherever it's mounted — so this takes just one change to the definition.
+## Step 4 — Dock it in a hub
 
-The hub serves your UI itself (rather than Vite serving it), so it needs the built assets. Tell the definition where they'll be, by adding one field to `defineDevframe` in `src/devframe.ts`:
+A [hub](/guide/hub) puts many devframes behind one interface, each a **dock** you switch between — the tool's own UI in an iframe. Since our client uses a bare `connectDevframe()`, it already works anywhere; the hub just needs the built UI. Point the definition at it:
 
 ```ts [src/devframe.ts]
 import { fileURLToPath } from 'node:url'
 // …
-
 export default defineDevframe({
   id: 'data-inspector',
   // …
-  importMetaUrl: import.meta.url,
-  // The built UI devframe serves when it hosts the SPA itself.
   clientAssets: fileURLToPath(new URL('../dist/client', import.meta.url)),
   setup(ctx) { /* unchanged */ },
 })
 ```
 
-Now build the UI and add a tiny hub host:
+Build the UI and stand up a one-devframe hub:
 
 ```sh
 npm install @devframes/hub @devframes/hub-ui
-npx vite build   # emits client/ → dist/client
+npx vite build
 ```
 
 ```ts [hub.config.ts]
@@ -267,8 +226,6 @@ import { viteDevframeHub } from '@devframes/vite/hub'
 import { defineConfig } from 'vite'
 import devframe from './src/devframe.ts'
 
-// A hub with a single devframe mounted. `viteDevframeHub` wraps the hub, serves
-// each tool's UI as a dock, and provides the reference interface via `createUi`.
 export default defineConfig({
   plugins: [
     viteDevframeHub({
@@ -284,26 +241,22 @@ export default defineConfig({
 npx vite --config hub.config.ts
 ```
 
-Open the printed URL: your Data Inspector now appears as a dock in the hub's rail, its UI running in an iframe. Add more devframes to that `devframes: [...]` array — your own or the [built-in plugins](/plugins) — and each becomes another dock. The hub prints a one-time code on startup; enter it to authorize.
+Your inspector now sits in the hub's rail as a dock. Drop more into `devframes: [...]` — your own or the [built-in plugins](/plugins) — and each gets its own. (The hub prints a code to authorize on first connect.)
 
-## Step 5 — Ship a static build
+## Step 5 — Build a static version
 
-Some tools should be viewable with no server at all — a report you can drop on any static host. `createBuild` renders your UI to a folder and **bakes** the results of read-only calls into it, so the built page answers them without a live process.
-
-Opt a function into the bake by adding `snapshot: true`. In `src/devframe.ts`, mark `get-meta`:
+Some tools should work with no server at all — a report you can drop on any static host. `createBuild` renders the UI and **bakes in** the results of read-only calls. Opt one in with `snapshot: true`:
 
 ```ts
 ctx.rpc.register({
   name: 'data-inspector:get-meta',
   type: 'query',
   jsonSerializable: true,
-  snapshot: true, // bake this call's result into the static build
+  snapshot: true, // bake this call's result into the build
   handler: () => /* … unchanged … */,
 })
 ```
 
-Add a build script:
-
 ```js [scripts/build.mjs]
 import { createBuild } from 'devframe/adapters/build'
 import devframe from '../src/devframe.ts'
@@ -312,15 +265,15 @@ await createBuild(devframe, { outDir: 'dist-static' })
 ```
 
 ```sh
-npx vite build          # refresh dist/client (the UI createBuild copies in)
-node scripts/build.mjs  # → dist-static/, a self-contained deploy
+npx vite build          # refresh dist/client
+node scripts/build.mjs  # → dist-static/
 ```
 
-Serve `dist-static/` with any static file server and the meta list renders from the baked snapshot — no Node process running. `query` takes an argument, so it isn't baked by default; a query needs its live server (next step), or you can bake specific inputs (see [Client Assets](/guide/client-assets)). This is the same result the CLI's `build` command produces in Step 7.
+Serve `dist-static/` anywhere and the meta list renders from the baked snapshot, no Node in sight. `query` takes an argument, so it needs the live server (next) — or bake specific inputs ([Client Assets](/guide/client-assets)).
 
-## Step 6 — Run it standalone (no Vite)
+## Step 6 — Run it standalone
 
-Vite was convenient for development, but the definition doesn't depend on it. `createDevServer` runs your tool as its own server, serving the UI from `clientAssets` and answering RPC live — no host framework involved.
+The definition never depended on Vite. `createDevServer` runs the tool on its own, serving the UI from `clientAssets` and answering RPC live:
 
 ```js [scripts/serve.mjs]
 import { createDevServer } from 'devframe/adapters/dev'
@@ -330,15 +283,15 @@ await createDevServer(devframe, { openBrowser: true })
 ```
 
 ```sh
-npx vite build          # ensure dist/client is current
+npx vite build
 node scripts/serve.mjs
 ```
 
-The same UI and the same live `query`/`get-meta` — now hosted entirely by devframe. This is what you'd embed in your own Node program when you want the tool available without a bundler in the loop.
+Same UI, same live calls — no bundler in the loop. This is what you'd drop into your own Node program.
 
 ## Step 7 — Give it a CLI
 
-Finally, wrap the standalone server in a command shell so anyone can run the tool without writing a script. `createCac` turns your definition into a CLI with `dev`, `build`, and `mcp` subcommands out of the box.
+Finally, wrap that server in a command shell. `createCac` hands you `dev`, `build`, and `mcp` for free:
 
 ```js [bin.mjs]
 #!/usr/bin/env node
@@ -348,38 +301,19 @@ import devframe from './src/devframe.ts'
 createCac(devframe).parse()
 ```
 
-Wire it up as the package's binary:
-
 ```sh
 npm pkg set bin.data-inspector=bin.mjs
-```
-
-Now the three modes from the previous steps are subcommands:
 
-```sh
 node bin.mjs dev     # the standalone server from Step 6
 node bin.mjs build   # the static build from Step 5
 node bin.mjs mcp     # expose the tool to a coding agent over MCP
 ```
 
-Published to npm, that same binary runs with `npx data-inspector`. One definition, five ways to run it — and you never rewrote the tool to get there.
-
-## Where you've been
-
-You wrote two halves once and grew the hosting around them:
-
-| Step | Capability | Key API |
-|------|------------|---------|
-| 1–3 | Live UI + RPC over a dev server | `defineDevframe`, `ctx.rpc.register`, `connectDevframe`, `devframeViteBridge` |
-| 4 | A dock inside a hub | `clientAssets`, `viteDevframeHub`, `createUi` |
-| 5 | Static, serverless build | `snapshot: true`, `createBuild` |
-| 6 | Standalone server | `createDevServer` |
-| 7 | A CLI (`dev`/`build`/`mcp`) | `createCac` |
+Publish it and the same binary runs with `npx data-inspector`. One definition, five ways to run it — and you never rewrote the tool.
 
 ## What's next
 
-- [Devframe Definition](/guide/devframe-definition) — every field of `defineDevframe`
-- [RPC](/guide/rpc) — `query`, `action`, and `event` functions, with end-to-end types and schema validation
-- [Shared State](/guide/shared-state) — push live server changes to the UI without polling
-- [Hub](/guide/hub) — compose many tools, with docks, commands, and terminals
+- [RPC](/guide/rpc) — `action` and `event` calls, end-to-end types, schema validation
+- [Shared State](/guide/shared-state) — push live changes to the UI without polling
+- [Hub](/guide/hub) — docks, commands, terminals across many tools
 - [Agent-Native](/guide/agent-native) — expose your tool to coding agents over MCP