Title: Proposal: terminal UI (TUI) target that renders json-render views · Issue #414 · devframes/devframe · GitHub
Open Graph Title: Proposal: terminal UI (TUI) target that renders json-render views · Issue #414 · devframes/devframe
X Title: Proposal: terminal UI (TUI) target that renders json-render views · Issue #414 · devframes/devframe
Description: Summary Add a terminal UI (TUI) target for devframe. A devframe author defines a view once with createJsonRenderView(). Today that view renders in a browser (Vue SPA, hub dock, React host). With this proposal the same view also renders i...
Open Graph Description: Summary Add a terminal UI (TUI) target for devframe. A devframe author defines a view once with createJsonRenderView(). Today that view renders in a browser (Vue SPA, hub dock, React host). With th...
X Description: Summary Add a terminal UI (TUI) target for devframe. A devframe author defines a view once with createJsonRenderView(). Today that view renders in a browser (Vue SPA, hub dock, React host). With th...
Opengraph URL: https://github.com/devframes/devframe/issues/414
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Proposal: terminal UI (TUI) target that renders json-render views","articleBody":"## Summary\n\nAdd a terminal UI (TUI) target for devframe. A devframe author defines a view once with `createJsonRenderView()`. Today that view renders in a browser (Vue SPA, hub dock, React host). With this proposal the same view also renders in a terminal, with live state and working actions.\n\nIdea credit: @danielroe. Reference: the interactive terminal UI in [nuxt/cli v4](https://github.com/nuxt/cli) (`packages/nuxt-cli/src/dev/tui/`).\n\n## What exists today\n\nThe \"define once\" layer is already in the repo. The TUI is one more renderer of it.\n\n| Layer | Where | Status |\n| --- | --- | --- |\n| View protocol | `@devframes/json-render` (`packages/json-render`) | A view is an `@json-render/core` `Spec`. Base catalog v1 has 17 components with prop schemas. The node side publishes each view as shared state at `devframe:json-render:\u003cscope>:\u003cid>` and lists views at `devframe:json-render:index`. |\n| Browser renderer (Vue) | `@devframes/json-render-ui` (`/spa`, `/hub`) | Shipped. |\n| Browser renderer (React) | `examples/custom-hub-next/src/client/json-render/react-renderer.tsx` | Shipped as a reference. |\n| Actions | `packages/json-render-ui/src/action-bridge.ts` | An element event dispatches `rpc.call(action, params)`. `setState`, `pushState`, `removeState`, `validateForm` stay local. |\n| Coding agent access | `devframe/adapters/mcp` via `@devframes/agentic` | RPC functions with an `agent` field become MCP tools. Shared state becomes MCP resources. |\n| Instance discovery | `devframe connect` (`packages/agentic/src/connect`) | Finds running dev servers through the instance registry and `__connection.json`. |\n| RPC from Node | `devframe/rpc/client` + `devframe/rpc/transports/ws-client` | The WebSocket channel uses the global `WebSocket`. The hub tests already drive it from Node. |\n\nNothing in the repo mentions a TUI, Ink, or OpenTUI today.\n\n## What nuxt/cli v4 does\n\nFacts from the source, for reference:\n\n- The TUI is hand-rolled. It has no TUI framework dependency. It uses `node:util` `styleText` and `@clack/prompts`.\n- `nuxt dev` paints a pinned footer panel (URLs, status, shortcuts) with logs folded above it. Single keys open full-screen overlays: `l` logs, `n` requests, `p` routes, `i` info, `?` help.\n- `PanelSurface` (`dev/tui/surface.ts`) splits two axes, \"who owns the screen\" (`split-footer` or `alternate-screen`) and \"where other output goes\" (`passthrough` or `capture`). The comment credits OpenTUI's `CliRenderer` for this shape.\n- `resolveDevUISupport` (`dev/tui/support.ts`) refuses the TUI when stdout or stdin is not a TTY, `TERM=dumb`, CI, test, an inspector is attached, or the terminal is under 40x10. `--no-tui` and `NUXT_TUI=plain` opt out. `NUXT_TUI=1` forces it on, but never over a pipe.\n- `nuxt curl` and `nuxt task` find the running dev server through a lock file. devframe has the same need and already solves it with the instance registry.\n\n## What upstream json-render offers\n\n[`@json-render/ink`](https://github.com/vercel-labs/json-render/tree/main/packages/ink) (version 0.21.0, same line as the `@json-render/core` we pin) renders a spec in the terminal with [Ink](https://github.com/vadimdemedes/ink). Peers: `ink ^6`, `react ^19`. It ships 24 standard components, `$state` and `$bindState` bindings, `Select`, `MultiSelect`, `TextInput`, `Tabs`, focus handling, and `createRenderer(catalog, components)`.\n\n## Proposal\n\n### 1. New opt-in package `@devframes/tui`\n\nSame pattern as `@devframes/agentic`: `devframe/adapters/tui` is a thin re-export of an optional peer. Core stays dependency-light and headless. `ink` and `react` are dependencies of `@devframes/tui` only. The package must stay validator-neutral (no `zod` in runtime `dependencies`). It reads prop schemas from `@devframes/json-render`, which already carries the upstream `zod` dependency.\n\n### 2. Rendering engine: `@json-render/ink`\n\nImplement the devframe base catalog (17 components) on Ink. Reuse upstream standard components where the shape matches. Write small custom components where it does not.\n\n| devframe component | Ink component | Note |\n| --- | --- | --- |\n| `Stack` | `Box` | `direction` maps to `flexDirection`. |\n| `Card` | `Card` | |\n| `Text` | `Text`, `Heading` | `variant: heading` uses `Heading`. `code` uses inverse text. |\n| `Badge` | `Badge` | |\n| `Button` | custom | Focusable `[ label ]`. Enter fires `press`. Ink has no button. |\n| `Icon` | custom | Name in brackets, or a glyph map for the common `ph:*` names. |\n| `Divider` | `Divider` | |\n| `TextInput` | `TextInput` | Two-way `$bindState` works upstream. |\n| `Switch` | custom | `[x] label`, space toggles. |\n| `KeyValueTable` | `KeyValue` | |\n| `DataTable` | `Table` | |\n| `CodeBlock` | custom on `Box` + `Text` | No highlighting in phase 1. |\n| `Progress` | `ProgressBar` | |\n| `Tree` | custom on `List` | Rendered expanded to a depth limit in phase 1. |\n| `Tabs` | `Tabs` | |\n| `Link` | `Link` | OSC 8 hyperlink when the terminal supports it. |\n| `Select` | `Select` | |\n\nUnknown component types render a placeholder, as the guide for alternative renderers already requires (`docs/content/1.guide/21.build-your-own-json-render-frontend.md`).\n\n### 3. Two ways to start it\n\nAttach mode, the primary path:\n\n```sh\ndevframe tui [--port \u003cn>] [--base \u003cpath>] [--instances-dir \u003cdir>]\n```\n\nThe command lists live instances from the same registry `devframe connect` uses. One instance attaches at once. Several instances show a `Select` prompt. The TUI reads `__connection.json`, opens the RPC client over WebSocket (SSE fallback), subscribes to `devframe:json-render:index`, and renders the views. It reconnects when the dev server restarts.\n\nIn-process mode:\n\n```sh\nmy-app tui\n```\n\n`createCac` gains a `tui` subcommand next to `dev`, `build`, and `mcp`. It starts the devframe and the TUI in one process. It reuses the attach code path against the local origin, so there is one renderer and one action bridge.\n\n### 4. Hub support (first class)\n\nA hub unites many devframes behind one origin. The TUI must work against a hub from the start, because that is how the framework kits (`@devframes/vite/hub`, `@devframes/nuxt/hub`, `@devframes/next/hub`) run.\n\nWhen the attached instance is a hub, the TUI reads the `devframe:docks` shared state (`HUB_EVENTS.sharedState.docks`) instead of the view index. Dock entries of type `json-render` render as tabs, in dock order. Other dock kinds (`iframe`, `launcher`, `action`) list their title and a link that opens them in the browser. The `devframe:docks:active` state follows the selected tab so the browser and the terminal agree.\n\nA single devframe with no hub uses the view index (`devframe:json-render:index`) as before. The attach code detects which one it talks to from `__connection.json`.\n\n### 5. Keys\n\n| Key | Action |\n| --- | --- |\n| `tab`, `shift-tab` | Move focus |\n| `enter`, `space` | Press or toggle the focused element |\n| `1`..`9` | Switch view or dock tab |\n| `?` | Show all shortcuts |\n| `r` | Reconnect |\n| `q`, `ctrl-c` | Quit |\n\n### 6. Terminal support rules\n\nPort `resolveDevUISupport` from nuxt/cli: refuse when stdout or stdin is not a TTY, `TERM=dumb`, CI, or the terminal is under 40x10. The TUI command has no plain fallback because the TUI is the whole command. It exits with a coded `DF` diagnostic that names the reason. Respect `NO_COLOR`. Map semantic variants (`success`, `warning`, `danger`) to a small ANSI palette. The `@antfu/design` tokens have no terminal form, so this palette is the terminal edition of the same vocabulary.\n\n### 7. Mounting into the nuxt/cli v4 TUI\n\nQuestion researched: can the devframe TUI open inside the `nuxt dev` terminal UI with little effort? Facts from the nuxt/cli source:\n\n- nuxt/cli publishes one in-process contract, `TerminalHost`, on `globalThis[Symbol.for('nuxt:terminal-host')]` (`utils/terminal-host.ts`). Its `withTerminal(work)` closes any overlay, releases raw stdin, erases the pinned panel, awaits `work`, then repaints (`dev/tui/index.ts`, `lendTerminal`). An Ink `render()` that resolves on `waitUntilExit()` fits this call with no adapter.\n- The contract is in-process only. `nuxt dev` forks by default. Nuxt modules, so `@devframes/nuxt`, run in the child. The parent never loads Nuxt. `useTerminalHost()` returns `undefined` in the child.\n- Child to parent IPC is a closed union of `nuxt:internal:dev:*` messages (`dev/utils.ts`, `NuxtDevIPCMessage`). No message registers a shortcut or an action. There is no public shortcuts API.\n- `nuxt dev --no-fork` runs Nuxt in the parent. There `useTerminalHost()` works from a module, but nothing gives the module a key to bind. A module could listen on stdin `keypress` beside the CLI, but both would answer the same key.\n\nThree ways to mount, in order of effort:\n\n| Option | Effort | Works today | Note |\n| --- | --- | --- | --- |\n| A. Second terminal: `devframe tui --port \u003cnuxt port> --base /__devframes/` | None beyond phase 1 | Yes | Attach mode over WebSocket. `--base` exists for this since #403. tmux or a split pane. |\n| B. Upstream PR to nuxt/cli: a generic \"dev action\" | Small, about 50 lines upstream, one IPC send in `@devframes/nuxt` | No | The child sends `{ type: 'nuxt:internal:dev:action', key, label, command }` once ready. The parent adds the shortcut to the hint line and, on the key, runs `command` inside `withTerminal` with inherited stdio. Generic: any module can offer a terminal action. The devframe TUI stays a separate process, so no React or Ink enters the CLI module graph. |\n| C. In-process `--no-fork` hook | Small on our side, fragile | Partly | `@devframes/nuxt` calls `useTerminalHost()?.withTerminal(() => renderTui())`. Needs a trigger the CLI does not offer. Not recommended. |\n\nRecommendation: ship A with phase 1, and open option B upstream as a proposal to nuxt/cli after phase 1 proves the TUI. Option B is the \"minimal effort\" mount. The devframe side is one `process.send` call. The design work sits upstream and helps other tools too.\n\n### 8. Rules this must follow\n\n- Headless core: the TUI is an explicit command, never default stdout output (`.agents/01-positioning.md`).\n- Event and state names come from `DEVFRAME_EVENTS` and `HUB_EVENTS`, no re-typed literals.\n- Warnings and errors are `DF` codes via `devframe/utils/nostics`, each with a docs page under `docs/content/6.errors/`.\n- Terms follow `docs/content/8.references/1.terms.md`: \"a devframe\", \"node side\", \"RPC client\", \"dock entry\".\n- Docs land only when the feature ships: a guide page, an adapter page, and the `terms.md` adapter list.\n\n## Phases\n\n### Phase 0: spike (1 to 2 days)\n\nRender the `examples/json-render` dashboard in-process with `@json-render/ink` and a hand-mapped catalog. Prove: all 17 components render, `$state` patches update live, a `Button` press reaches the RPC function. No package yet. Result: a short report on this issue with gaps found.\n\n### Phase 1: `@devframes/tui`, attach mode, single devframe and hub (2 to 3 weeks)\n\n- Package with the full base catalog on Ink.\n- `devframe tui` attach mode with instance discovery, reconnect, and auth.\n- Single devframe: views from the view index. Hub: tabs per `json-render` dock entry, link list for other dock kinds, active dock kept in sync.\n- Action bridge with the same reserved names as the Vue renderer.\n- Terminal support rules and `DF` diagnostics.\n- Tests: catalog components render each prop schema. Action dispatch reaches a fake RPC host. Support rules return the right refusal. Hub and single devframe both attach in an integration test.\n- Docs: guide page and adapter page, with the nuxt/cli second-terminal recipe (option A above).\n- `examples/custom-hub-vite` and `examples/custom-hub-next` both register a json-render dock the TUI can show (parity rule).\n\nAcceptance: `pnpm -C examples/json-render dev` in one terminal and `devframe tui` in another shows the dashboard with live counters and working buttons. `pnpm -C examples/custom-hub-vite dev` in one terminal and `devframe tui --base /__devframes/` in another shows one tab per json-render dock and a link list for the iframe docks.\n\n### Phase 2: in-process command (about 1 week)\n\n- `tui` subcommand on `createCac`, reusing the attach path against the local origin.\n- `initHub` hosts get the same through the `devframe` bin, no new API.\n\n### Phase 3: nuxt/cli mount (upstream, size unknown)\n\n- Open a proposal on nuxt/cli for the generic \"dev action\" IPC message and shortcut (option B in section 7).\n- When it lands, `@devframes/nuxt` sends the action once the hub is ready. No other devframe change.\n\n### Later, not designed here\n\n- A nuxt/cli style status panel for `my-app dev` (URLs, status, log fold, shortcuts).\n- Built-in TUI views that need no json-render view from the author: a shared-state tree and an RPC function list. This makes the TUI useful for any devframe.\n\n## Out of scope\n\n- MCP changes. The coding agent path already exists and does not change.\n- A hand-rolled renderer. If `@json-render/ink` blocks us, we revisit.\n\n## Open questions\n\n1. Auth in attach mode. `devframe connect` reads a bearer token from `DEVFRAME_MCP_AUTH_TOKEN`. The TUI can do the same with its own variable, or run the interactive OTP flow from `devframe/recipes/interactive-auth` in the terminal. Which one first?\n2. Runtime matrix. CI runs Node, Bun, and Deno. Ink runs on Node and Bun. Deno support for Ink 6 needs a check before phase 1.\n3. `connectDevframe()` in `packages/devframe/src/client/index.ts` fetches `./__connection.json` relative to a page. Attach mode needs a Node-side entry that takes an origin. Is that a new export on `devframe/rpc/client` or a helper inside `@devframes/tui`?\n4. Custom components (`Button`, `Switch`, `Tree`, `CodeBlock`): keep them in `@devframes/tui`, or propose them upstream to `@json-render/ink`?\n5. Light and dark terminals. nuxt/cli detects the background and has a `NUXT_TERM_THEME` override. Do we want the same or a fixed palette in phase 1?\n\n## References\n\n- nuxt/cli TUI source: https://github.com/nuxt/cli/tree/main/packages/nuxt-cli/src/dev/tui\n- nuxt/cli TerminalHost contract: https://github.com/nuxt/cli/blob/main/packages/nuxt-cli/src/utils/terminal-host.ts\n- nuxt/cli fork IPC message union: https://github.com/nuxt/cli/blob/main/packages/nuxt-cli/src/dev/utils.ts\n- nuxt/cli `nuxt dev` docs (interactive terminal UI section): https://github.com/nuxt/cli/blob/main/docs/dev.md\n- `@json-render/ink`: https://github.com/vercel-labs/json-render/tree/main/packages/ink\n- OpenTUI (the design nuxt/cli credits): https://github.com/anomalyco/opentui\n- devframe json-render guide: `docs/content/1.guide/8.json-render.md`\n- devframe alternative renderer guide: `docs/content/1.guide/21.build-your-own-json-render-frontend.md`\n\nResearch and draft written with the help of an agent.\n","author":{"url":"https://github.com/antfubot","@type":"Person","name":"antfubot"},"datePublished":"2026-09-30T08:23:05Z","url":"https://github.com/devframes/devframe/issues/414"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react-reconciler,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@d5750093facf |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:79b5693e-69ca-37a8-6794-eccd3a1eb091 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 80AA:ECC72:D7B0B:130186:6AFB67AC |
| html-safe-nonce | d5758e0cfc0383e0485fb065a29fa84766ff9b487786e5013d9b455acf474047 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4MEFBOkVDQzcyOkQ3QjBCOjEzMDE4Njo2QUZCNjdBQyIsInZpc2l0b3JfaWQiOiI3MzAxOTE4NDUzNDIwMjIyMzgwIiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 7187084faeca5e34e1491617415843245237d4a808c495cf14fa6955c68b1c46 |
| hovercard-subject-tag | issue:5643439922 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/devframes/devframe/414/issue_layout |
| twitter:image | https://opengraph.githubassets.com/6c31b2ac1ecb3e83f50c4c1612fb668dee0688e0e0b19c01841441f676fb7812/devframes/devframe/issues/414 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/6c31b2ac1ecb3e83f50c4c1612fb668dee0688e0e0b19c01841441f676fb7812/devframes/devframe/issues/414 |
| og:image:alt | Summary Add a terminal UI (TUI) target for devframe. A devframe author defines a view once with createJsonRenderView(). Today that view renders in a browser (Vue SPA, hub dock, React host). With th... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | antfubot |
| hostname | github.com |
| expected-hostname | github.com |
| None | ea33d13c96d0ff66bd8fa906b193d2213536b78cb06b0c50a4632c58b1418f94 |
| turbo-cache-control | no-preview |
| go-import | github.com/devframes/devframe git https://github.com/devframes/devframe.git |
| octolytics-dimension-user_id | 279879373 |
| octolytics-dimension-user_login | devframes |
| octolytics-dimension-repository_id | 1231722386 |
| octolytics-dimension-repository_nwo | devframes/devframe |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1231722386 |
| octolytics-dimension-repository_network_root_nwo | devframes/devframe |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 59ef97164c52cf59bd10558ddec9c4f482763988 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width