You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a52f00c
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: AGENTS.md
+14Lines changed: 14 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,6 +38,20 @@ The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots co
38
38
- Utility imports use the package-path form `devframe/utils/*`, never relative `../utils/*`.
39
39
- 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`.
40
40
41
+
### Design system
42
+
43
+
All five built-in plugins — and every example under `examples/` — share one design system, `@internal/design`, so they look and feel like one product across frameworks (Git is React/Next, terminals is Svelte, code-server is vanilla DOM, inspect is Vue, a11y is Solid, the examples are Preact/Next/vanilla). It's a private, source-only package — never built or published; consumers import its TypeScript/CSS directly (resolved through `alias.ts` for bundlers and the package `exports` for config loaders), so editing it needs no rebuild.
44
+
45
+
-**Respect the skills.** This design system is built to the `antfu` and `antfu-design` skills (UnoCSS-first, class-based semantic tokens, dual light/dark, anti-slop) — load and follow them when building or changing any UI here. The surfaces deliberately echo the upstream devtools they descend from; reference their UI/UX when in doubt: [`antfu/node-modules-inspector`](https://github.com/antfu/node-modules-inspector), [`antfu/vite-plugin-inspect`](https://github.com/antfu/vite-plugin-inspect), [`eslint/config-inspector`](https://github.com/eslint/config-inspector), and [`vitejs/devtools` → `packages/rolldown`](https://github.com/vitejs/devtools/tree/main/packages/rolldown).
46
+
-**One preset to extend.** Each consumer's `uno.config.ts` is just `presets: [presetDevframe()]` (imported from `@internal/design/preset`). The preset bundles `presetWind4` + `presetIcons` (Phosphor) + the directive/variant-group transformers, the semantic token theme, and the shared `df-*` component shortcuts (which it safelists). Don't re-declare presets, palettes, or shortcuts per consumer.
47
+
-**One token source.** Import `@internal/design/theme.css` once on the page (after the generated UnoCSS stylesheet so its base layer wins). Token *values* (the `--df-*` custom properties, light + dark via the `.dark` class) live only there — never hardcode a palette. The brand primary is devframe's sage green; flip the OS preference onto `<html class="dark">` from the SPA entry.
48
+
-**Shared component vocabulary.** Build UI from the `df-*` classes (`df-btn`, `df-badge`, `df-tab`, `df-navtab`, `df-nav`, `df-nav-brand`, `df-toolbar`, `df-card`, `df-input`, `df-dot`, `df-tag-*`, …) and the semantic token utilities (`bg-primary`, `text-muted-foreground`, `bg-card`, `border-border`, …). Markup differs per framework; the classes resolve identically, which is what keeps the surfaces consistent.
49
+
-**Component builders.** Prefer the framework-neutral recipes from `@internal/design/components` (`button`, `iconButton`, `badge`, `tab`, `tabsList`, `navTab`, `nav`, `navBrand`, `toolbar`, `card`, `panel`, `input`, `link`, `dot`, `spinner`, `tag`) over hand-written class strings — they return the canonical `df-*` classes and read the same in React (`className=`), Svelte/Vue (`class=`), vanilla DOM and Solid. Because these classes are assembled at runtime, the preset safelists the `df-*` vocabulary so UnoCSS always emits it; add new component classes to `DF_SAFELIST` when you extend the set.
50
+
-**One nav, three buttons, one tab selector — strictly.** Every surface opens with the same top bar: `nav()` (a single row, one fixed height) led by `navBrand()` (a primary-tinted `i-ph-*` icon + the product name). Buttons come in exactly three forms and nothing else: a **text button** (`button({ variant, size })`), an **icon button** (`iconButton()` — bordered), and a **borderless icon button** (`iconButton({ variant: 'ghost' })`). Multi-view tools (inspect, git) switch views with the one shared segmented selector — `tabsList()` wrapping `tab()` buttons that carry `data-state="active"` and a leading `i-ph-*` icon per tab. Don't invent bespoke nav bars, button shapes, or tab styles.
51
+
-**Icons** come from the shared Phosphor set (`i-ph-*`, duotone preferred) via `presetIcons` — use them everywhere instead of per-consumer icon libraries or bespoke SVG.
52
+
-**A surface keeping its own component CSS** (inspect, a11y) re-bases its color/radius tokens onto the `--df-*` variables rather than hardcoding a palette, so it tracks the shared theme.
53
+
-**Plain `.ts`/vanilla views** must opt `.ts` into UnoCSS extraction (`content.pipeline.include` for Vite, or `content.filesystem` globs for the `@unocss/postcss` setup Next uses), since UnoCSS only scans framework files by default.
54
+
41
55
### Devframe design principles
42
56
43
57
These reinforce devframe's positioning as "the container for one devtool integration, portable to multiple viewers". When in doubt, err on the side of "devframe provides primitives, the hub provides UX".
Lists the files in the current working directory and renders them through a **Preact** SPA. A node-modules-inspector-style demo that exercises every devframe surface end to end.
-**CLI dev server** — `node bin.mjs` boots an HTTP + WebSocket server backing live RPC.
14
+
-**Static build** — `node bin.mjs build` produces a self-contained directory (SPA + baked RPC dump) deployable to any static host.
15
+
-**Runtime base discovery** — the client is built with `vite.base: './'` and reads `document.baseURI` at runtime, so the same `dist/client` works under any base path without rebuilding.
16
+
-**Two RPC types** — `:list-files` is a `query` baked into the dump; `:get-cwd` is a `static` RPC.
17
+
18
+
## Run it
19
+
20
+
```sh
21
+
pnpm -C examples/files-inspector run build # build the Preact client
22
+
pnpm -C examples/files-inspector run dev # CLI dev server (live RPC)
23
+
pnpm -C examples/files-inspector run cli:build # static deploy → dist/static
24
+
```
25
+
26
+
The dev server prints its URL. Serve `dist/static` from any static host — relative asset paths make it portable.
End-to-end examples that exercise the full adapter surface, each a runnable app in the repository. Like the [built-in plugins](/plugins/), they are written across different UI frameworks on purpose: the node-side definition stays the same while the browser bundle varies, so the set demonstrates that devframe is framework-agnostic at both the plugin and the host level.
8
+
9
+
| Example | UI framework | What it shows |
10
+
|---------|--------------|---------------|
11
+
|[files-inspector](./files-inspector)| Preact | Lists files in the cwd via RPC; exercises the CLI dev / build / spa surfaces. |
12
+
|[streaming-chat](./streaming-chat)| Preact | Streams synthetic chat tokens server → client, with history kept in shared state. |
13
+
|[next-runtime-snapshot](./next-runtime-snapshot)| React (Next.js) | A Next.js App Router SPA over RPC, surfacing the host Node runtime. |
14
+
|[minimal-vite-devframe-hub](./minimal-vite-devframe-hub)| Vanilla TypeScript (Vite) | A ~120-line Vite host wiring `@devframes/hub` end to end. |
15
+
|[minimal-next-devframe-hub](./minimal-next-devframe-hub)| React (Next.js) | The same hub protocol, hosted from a Next.js route handler. |
16
+
17
+
## Two kinds of example
18
+
19
+
The first three are **single-tool devframes** — one `DevframeDefinition` deployed through the [adapters](/adapters/), showing how RPC, streaming, and a chosen SPA framework fit together.
20
+
21
+
The last two are **hub hosts** built on [`@devframes/hub`](/guide/hub). They are protocol witnesses: each is a small host that exercises every hub subsystem (docks, commands, messages, terminals) so you can read one file and see the whole shape. One is a Vite plugin; the other a Next.js route handler — same hub, different host runtime.
22
+
23
+
## Run any example
24
+
25
+
Each example ships its own scripts; from the repository root:
26
+
27
+
```sh
28
+
pnpm install
29
+
pnpm --filter <example-name> dev
30
+
```
31
+
32
+
See the individual pages for the package name, the build / static-deploy commands, and what to look for in the running app.
The same hub protocol as the [Vite host](./minimal-vite-devframe-hub), hosted from a **Next.js** App Router app. It wires [`@devframes/hub`](/guide/hub) by lazily starting a side-car RPC / WebSocket server from a Node route handler — proof that the hub is host-runtime-agnostic.
-`createHubContext()` boots a hub without any Vite-specific code path.
14
+
- A `DevframeHost` implementation plugs the Next host specifics into the hub uniformly.
15
+
-`mountDevframe(ctx, def)` registers any `DevframeDefinition` as a dock.
16
+
- The built-in `hub:commands:execute` RPC dispatches any registered server command, regardless of how the host was constructed.
17
+
- The browser-side `connectDevframe({ baseURL: '/__hub/' })` discovers the WS endpoint via the Next route handler at `/__hub/__connection.json`, which starts the singleton host on demand.
18
+
19
+
## Run it
20
+
21
+
```sh
22
+
pnpm install
23
+
pnpm --filter minimal-next-devframe-hub dev
24
+
```
25
+
26
+
Open the printed URL to see the docks, commands, messages, and terminals lists, plus a button that dispatches a sample command through `hub:commands:execute`.
A protocol-witness host: roughly 120 lines of Vite plugin code that wire [`@devframes/hub`](/guide/hub) into a Vite dev server. The browser UI is plain **vanilla TypeScript**, so nothing distracts from the hub protocol itself. Every framework's hub host follows the same shape.
-`createHubContext()` boots a hub without any Vite-specific code path.
14
+
- A `DevframeHost` implementation plugs framework specifics (storage paths, origin resolution) into the hub uniformly.
15
+
-`mountDevframe(ctx, def)` registers any `DevframeDefinition` as a dock.
16
+
- The built-in `hub:commands:execute` RPC dispatches any registered server command, regardless of how the host was constructed.
17
+
- The browser-side `connectDevframe({ baseURL: '/__hub/' })` discovers the WS endpoint via the kit's `__connection.json` middleware.
18
+
19
+
## Run it
20
+
21
+
```sh
22
+
pnpm install
23
+
pnpm --filter minimal-vite-devframe-hub dev
24
+
```
25
+
26
+
Open the printed URL to see the docks, commands, messages, and terminals lists the hub exposes, plus a button that dispatches a sample command through `hub:commands:execute`.
A **Next.js App Router** SPA over RPC, surfacing the host Node runtime — system info, memory, and environment variables. It shows that a React + Next.js build is a drop-in replacement for a Preact + Vite SPA: devframe serves the static export, and the client calls into the host Node process through the same type-safe RPC.
-`…:system` — a `static` RPC. Runs once at build time when baked into a static dump, otherwise resolved live over WebSocket. Returns Node version, platform / arch, pid, cwd, and start time.
14
+
-`…:memory` — a `query` RPC the UI re-invokes from a refresh button.
15
+
-`…:env` — a `query` with valibot-validated args, listing environment variables matching a regex and redacting keys that look secret.
16
+
- Next.js App Router with `'use client'` components calling `connectDevframe()` once, then sharing the scoped client through React context.
17
+
18
+
The Next.js config carries three non-defaults that each map to a devframe design principle: `output: 'export'` (devframe owns the server), `assetPrefix: '.'` (relative assets so the same build works at any base), and `trailingSlash: true` (composes with devframe's directory-with-index static resolution).
19
+
20
+
## Run it
21
+
22
+
```sh
23
+
pnpm -C examples/next-runtime-snapshot run build # next build → static export
24
+
pnpm -C examples/next-runtime-snapshot run dev # devframe CLI dev server
25
+
pnpm -C examples/next-runtime-snapshot run cli:build # static deploy → dist/static
26
+
```
27
+
28
+
The three cards populate from RPC; the static deploy still works because the `static` and `query` RPCs that opted into the dump are baked at build time.
A **Preact** demo of devframe's [streaming-channel API](/guide/streaming) combined with [shared state](/guide/shared-state) for persistent chat history. The server emits synthesized "tokens" one at a time over a streaming channel, while the conversation log lives in shared state so it survives reloads, syncs across panels, and replays cleanly when a client re-joins mid-stream.
- A scoped context (`ctx.scope('devframe-streaming-chat')`) auto-namespaces every id.
14
+
-`my.rpc.streaming.create('tokens', …)` registers a streaming channel for low-latency token rendering.
15
+
-`my.rpc.sharedState('history', …)` keeps the message log on the server; each `send` appends a user + assistant pair atomically.
16
+
- The producer streams tokens live, then commits the joined content back to shared state when done — so refreshes and new clients see the finished message immediately.
17
+
-`reader.cancel()` aborts mid-stream; the assistant message is marked cancelled with whatever content accumulated.
18
+
-`replayWindow` lets a panel reopened mid-stream replay buffered tokens before resuming live.
19
+
20
+
To wire it to a real LLM, replace the fake token generator in `src/devframe.ts` with anything that yields strings — the stream's `signal` propagates cancellation from the browser all the way to the upstream request.
21
+
22
+
## Run it
23
+
24
+
```sh
25
+
pnpm -C examples/streaming-chat run build
26
+
pnpm -C examples/streaming-chat run dev
27
+
```
28
+
29
+
Open the printed URL, type a prompt, watch tokens stream in, refresh mid-conversation, and cancel a long answer.
0 commit comments