@simon_he/vue-tui 1.0.1 → 1.1.0

package/README.md

@@ -1,18 +1,47 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./docs/public/brand/vue-tui-logo-on-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="./docs/public/brand/vue-tui-logo-on-light.svg">
+    <img alt="Vue TUI" src="./docs/public/brand/vue-tui-logo-on-light.svg" width="360">
+  </picture>
+</p>
+
 # @simon_he/vue-tui
 
-Vue TUI is a Vue 3 terminal UI toolkit for building terminal-style interfaces that can render in a browser or in a real CLI. It gives you Vue components, terminal cell rendering, event dispatch, markdown rendering, and high-throughput primitives for lists, logs, and streaming transcripts.
+[![npm version](https://img.shields.io/npm/v/@simon_he/vue-tui?style=flat-square)](https://www.npmjs.com/package/@simon_he/vue-tui)
+[![npm downloads](https://img.shields.io/npm/dm/@simon_he/vue-tui?style=flat-square)](https://www.npmjs.com/package/@simon_he/vue-tui)
+[![CI](https://github.com/Simon-He95/vue-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/Simon-He95/vue-tui/actions/workflows/ci.yml)
+[![Runtime compatibility](https://github.com/Simon-He95/vue-tui/actions/workflows/runtime-compat.yml/badge.svg)](https://github.com/Simon-He95/vue-tui/actions/workflows/runtime-compat.yml)
+[![Security](https://github.com/Simon-He95/vue-tui/actions/workflows/security.yml/badge.svg)](https://github.com/Simon-He95/vue-tui/actions/workflows/security.yml)
+![TypeScript types](https://img.shields.io/npm/types/@simon_he/vue-tui?style=flat-square)
+![Node version](https://img.shields.io/node/v/@simon_he/vue-tui?style=flat-square)
+[![MIT License](https://img.shields.io/github/license/Simon-He95/vue-tui?style=flat-square)](./license)
+
+[Docs](https://vue-tui.pages.dev/) | [npm](https://www.npmjs.com/package/@simon_he/vue-tui) | [GitHub](https://github.com/Simon-He95/vue-tui) | [Issues](https://github.com/Simon-He95/vue-tui/issues)
+
+Vue TUI is a Vue 3 terminal UI toolkit for building terminal-style interfaces that render to browser DOM, real CLI stdout, and headless tests.
+
+Use it to build browser terminal dashboards, Vue-powered CLI apps, streaming markdown transcripts, log viewers, virtual lists, and AI agent consoles with one shared component model.
+
+## Why Vue TUI?
+
+- **Vue component model for terminal UIs**: build with `TerminalProvider`, `TBox`, `TInput`, `TList`, `TTable`, and more.
+- **Browser + CLI renderers**: render the same UI model to browser DOM or real stdout.
+- **High-throughput surfaces**: virtual lists, append-only logs, streaming markdown, and agent transcripts.
+- **Clear host boundaries**: browser-safe root entrypoint, CLI-only APIs under `/cli`, sanitized links, and explicit host permissions.
+
+## Agent UI Showcase
 
-Use it when you want:
+A real agent console built on `@simon_he/vue-tui` can stream agent output, markdown content, tool-call status, and input chrome in one terminal surface.
 
-- Browser-hosted terminal interfaces, dashboards, demos, and playgrounds.
-- CLI apps that use Vue component composition instead of imperative stdout drawing.
-- Shared UI code that can run against a DOM renderer, a stdout renderer, or headless tests.
-- Large terminal surfaces such as virtual lists, append-only logs, markdown transcripts, and agent console UIs.
+[![Agent console rendering built with vue-tui](./docs/public/agent-console-rendering-poster.png)](./docs/public/agent-console-rendering.mp4)
+
+[Watch the rendering demo](./docs/public/agent-console-rendering.mp4)
 
 ## Install
 
 ```bash
-pnpm add @simon_he/vue-tui@rc vue
+pnpm add @simon_he/vue-tui vue
 ```
 
 Vue is a peer dependency. The current package supports Vue `>=3.3.0 <4`.
@@ -25,20 +54,72 @@ Development, release validation, and documentation builds are run on Node.js 20
 
 ## Entry Points
 
-| Import                            | Stability    | Use it for                                                                                                                  |
-| --------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- |
-| `@simon_he/vue-tui`               | Public       | Browser-safe terminal core, DOM renderer, stable Vue components, and input host plugin factory                              |
-| `@simon_he/vue-tui/core`          | Public       | Terminal core, buffer-facing types, ANSI/theme/path/hyperlink helpers                                                       |
-| `@simon_he/vue-tui/renderer/dom`  | Public       | DOM renderer factory and renderer capabilities                                                                              |
-| `@simon_he/vue-tui/vue`           | Advanced     | Extended Vue components, composables, router helpers, and Vue runtime internals                                             |
-| `@simon_he/vue-tui/runtime`       | Advanced     | Runtime wiring, selection helpers, and clipboard abstraction                                                                |
-| `@simon_he/vue-tui/observability` | Advanced     | Frame perf store, profiler hooks, and trace helpers                                                                         |
-| `@simon_he/vue-tui/cli`           | Public       | Node-only headless Vue app runtime, stdin driver, stdout renderer, path provider, recording, and terminal clipboard helpers |
-| `@simon_he/vue-tui/markdown`      | Public       | `TMarkdownText`, `TVirtualMarkdown`, markdown parser and layout helpers, streaming markdown block sources                   |
-| `@simon_he/vue-tui/experimental`  | Experimental | `TVirtualList`, `TTranscriptView`, `TLogView`, TLog search/link/minimap companions, append-only log store, and TLog plugins |
-| `@simon_he/vue-tui/agent`         | Experimental | Agent/console transcript, tool-call header, log, markdown, virtual list, render plane, and overlay component aggregation    |
-
-The stable surface is terminal core, DOM rendering, CLI runtime, basic Vue components, and markdown APIs. High-throughput log, virtualization, and agent/console aggregation APIs stay under `/experimental` or `/agent` until their public surface settles; keep those imports isolated in application code.
+| Import                                      | Stability    | Use it for                                                                                                                   |
+| ------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `@simon_he/vue-tui`                         | Public       | Browser-safe terminal core, DOM renderer, stable Vue components, and input host plugin factory                               |
+| `@simon_he/vue-tui/core`                    | Public       | Terminal core, buffer-facing types, ANSI/theme/path/hyperlink helpers                                                        |
+| `@simon_he/vue-tui/renderer/dom`            | Public       | DOM renderer factory and renderer capabilities                                                                               |
+| `@simon_he/vue-tui/vue`                     | Advanced     | Extended Vue components, composables, router helpers, and Vue runtime internals                                              |
+| `@simon_he/vue-tui/runtime`                 | Advanced     | Runtime wiring, selection helpers, and clipboard abstraction                                                                 |
+| `@simon_he/vue-tui/observability`           | Advanced     | Frame perf store, profiler hooks, and trace helpers                                                                          |
+| `@simon_he/vue-tui/cli`                     | Public       | Node-only headless Vue app runtime, stdin driver, stdout renderer, path provider, recording, and terminal clipboard helpers  |
+| `@simon_he/vue-tui/markdown`                | Public       | `TMarkdownText`, `TVirtualMarkdown`, markdown parser and layout helpers, streaming markdown block sources                    |
+| `@simon_he/vue-tui/mermaid`                 | Public       | Optional `beautiful-mermaid` bridge and wrapper for `TMermaidText`                                                           |
+| `@simon_he/vue-tui/experimental`            | Experimental | `T3DViewport`, `TVideo`, charts, `TVirtualList`, `TTranscriptView`, `TLogView`, TLog companions, and append-only log tooling |
+| `@simon_he/vue-tui/experimental/video/node` | Experimental | Node-only lazy FFmpeg frame source plus optional yt-dlp resolver for supported video pages                                   |
+| `@simon_he/vue-tui/experimental/3d/bun`     | Experimental | Bun-only raw WGSL/WebGPU Pull renderers, including the vue-tui terminal badge scene                                          |
+| `@simon_he/vue-tui/agent`                   | Experimental | Agent/console transcript, tool-call header, log, markdown, virtual list, render plane, and overlay component aggregation     |
+| `@simon_he/vue-tui/agent/mermaid`           | Experimental | Agent namespace optional `beautiful-mermaid` bridge and wrapper for `TMermaidText`                                           |
+
+The stable surface is terminal core, DOM rendering, CLI runtime, basic Vue components, markdown APIs, and the optional Mermaid bridge. High-throughput log, virtualization, and agent/console aggregation APIs stay under `/experimental` or `/agent` until their public surface settles; keep those imports isolated in application code. Use `/agent/mermaid` when agent code wants the optional Mermaid wrapper without changing the `/agent` main entrypoint.
+
+Experimental chart components are imported from the `/experimental` entrypoint:
+
+```ts
+import {
+  TCandlestickChart,
+  TContributionGraph,
+  TLineChart,
+  TPieChart,
+} from "@simon_he/vue-tui/experimental";
+```
+
+`T3DViewport` is renderer-agnostic and Pull-based. The bundled WGSL renderer is isolated in the Bun-only entrypoint so browser-safe imports do not load native GPU code:
+
+```ts
+import { T3DViewport } from "@simon_he/vue-tui/experimental";
+import { createTerminalBadge3DRenderer } from "@simon_he/vue-tui/experimental/3d/bun";
+
+const renderer = createTerminalBadge3DRenderer();
+```
+
+Install the optional `bun-webgpu` peer, then run the complete direction-E terminal badge example with `bun run run:3d:terminal`. Drag to orbit and use a two-finger trackpad gesture or mouse wheel to zoom. CLI hover steering requires `createStdinDriver({ enableMouseMotion: true })`.
+
+#### `experimental/3d/bun` platform requirements
+
+| Requirement                 | Detail                                               |
+| --------------------------- | ---------------------------------------------------- |
+| Runtime                     | **Bun only** — Node.js and browser are not supported |
+| `bun-webgpu` peer           | Must be installed manually: `bun add bun-webgpu`     |
+| macOS x64 / arm64           | ✅ Prebuilt binary available                         |
+| Linux x64                   | ✅ Prebuilt binary available                         |
+| Windows x64                 | ✅ Prebuilt binary available                         |
+| Linux arm64 / musl (Alpine) | ❌ No prebuilt binary — must build from source       |
+
+> `T3DViewport` itself (from `/experimental`) has zero native dependencies and works everywhere. Only `experimental/3d/bun` requires Bun and the optional peer. `bun-webgpu` is an experimental library; see [bun-webgpu](https://github.com/kommander/bun-webgpu) for current status.
+
+#### Terminal graphics protocol requirements
+
+`TVideo` and `T3DViewport` automatically negotiate their output format based on the detected terminal:
+
+| Terminal capability                 | Output quality                                 |
+| ----------------------------------- | ---------------------------------------------- |
+| kitty or iTerm2 protocol            | Pixel-accurate frames (PNG)                    |
+| No graphics protocol (any terminal) | `gray8` ASCII art — functional, lower fidelity |
+
+`TAgentTerminalGraphic` (mermaid diagrams, KaTeX math, images) requires kitty, iTerm2, or sixel to render visually; without a protocol it shows the `fallback` text prop. Always provide a meaningful `fallback` value so non-graphical terminals still convey the content.
+
+> sixel terminals get graphics for `TAgentTerminalGraphic` but ASCII art for `TVideo` / `T3DViewport` — only kitty and iTerm2 support pixel-accurate video and 3D frames. See [docs/platform-contracts.md](./docs/platform-contracts.md) for the full degradation table.
 
 Do not deep import from `@simon_he/vue-tui/dist/...`; only the entry points above are part of the supported package contract.
 
@@ -200,36 +281,47 @@ Unhandled promise rejections stay host-owned by default. Setting `cleanupOnUnhan
 
 ## Components
 
-| Area           | Import                           | Components / APIs                                                                                                                                                          |
-| -------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Stable layout  | `@simon_he/vue-tui`              | `TBox`, `TView`                                                                                                                                                            |
-| Stable text    | `@simon_he/vue-tui`              | `TText`, `TLink`, `TLinkifyText`                                                                                                                                           |
-| Stable input   | `@simon_he/vue-tui`              | `TInput`, `TList`, `TSelect`                                                                                                                                               |
-| Stable overlay | `@simon_he/vue-tui`              | `TDialog`                                                                                                                                                                  |
-| Vue extended   | `@simon_he/vue-tui/vue`          | `TAnchor`, `TFlow`, `TRenderPlane`, `TRenderLayer`, `TTransition`, `TInputBox`, `TPathPicker`, `TJsonEditor`, `TMultilineModal`, `TDebugOverlay`, composables, router APIs |
-| Markdown       | `@simon_he/vue-tui/markdown`     | `TMarkdownText`, `TVirtualMarkdown`                                                                                                                                        |
-| Experimental   | `@simon_he/vue-tui/experimental` | `TVirtualList`, `TTranscriptView`, `TLogView`, `TLogSearchBar`, `TLogLinksPanel`, `TLogScrollbar`, `TLogMinimap`                                                           |
-| Agent console  | `@simon_he/vue-tui/agent`        | `TAgentTranscript`, `TToolCallView`, `TToolLogView`, `TVirtualMarkdown`, `TVirtualList`, `TRenderPlane`                                                                    |
-| Runtime        | `@simon_he/vue-tui/runtime`      | runtime, event, and selection APIs                                                                                                                                         |
-| CLI            | `@simon_he/vue-tui/cli`          | `createTerminalApp`, `createStdoutRenderer`, `createStdinDriver`, Node host adapters                                                                                       |
+| Area           | Import                                      | Components / APIs                                                                                                                                                                                |
+| -------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Stable layout  | `@simon_he/vue-tui`                         | `TBox`, `TView`                                                                                                                                                                                  |
+| Stable text    | `@simon_he/vue-tui`                         | `TText`, `TLink`, `TLinkifyText`                                                                                                                                                                 |
+| Stable input   | `@simon_he/vue-tui`                         | `TInput`, `TList`, `TSelect`                                                                                                                                                                     |
+| Stable overlay | `@simon_he/vue-tui`                         | `TDialog`                                                                                                                                                                                        |
+| Vue extended   | `@simon_he/vue-tui/vue`                     | `TAnchor`, `TFlex`, `TFlexItem`, `TFlow`, `TRenderPlane`, `TRenderLayer`, `TTransition`, `TInputBox`, `TPathPicker`, `TJsonEditor`, `TMultilineModal`, `TDebugOverlay`, composables, router APIs |
+| Markdown       | `@simon_he/vue-tui/markdown`                | `TMarkdownText`, `TVirtualMarkdown`                                                                                                                                                              |
+| Mermaid        | `@simon_he/vue-tui/mermaid`                 | `beautifulMermaidRenderer`, `TMermaid`, `TMermaidText`, `TBeautifulMermaidText`                                                                                                                  |
+| Experimental   | `@simon_he/vue-tui/experimental`            | `TVideo`, `TContributionGraph`, `TLineChart`, `TCandlestickChart`, `TPieChart`, `TVirtualList`, `TTranscriptView`, `TLogView`, `TLogSearchBar`, `TLogLinksPanel`, `TLogScrollbar`, `TLogMinimap` |
+| Video adapter  | `@simon_he/vue-tui/experimental/video/node` | `createFfmpegVideoFrameSource`, `createYtDlpVideoFrameSource`                                                                                                                                    |
+| Agent console  | `@simon_he/vue-tui/agent`                   | `TAgentTranscript`, `TToolCallView`, `TToolLogView`, `TVirtualMarkdown`, `TVirtualList`, `TRenderPlane`                                                                                          |
+| Agent Mermaid  | `@simon_he/vue-tui/agent/mermaid`           | `beautifulMermaidRenderer`, `TMermaid`, `TMermaidText`, `TBeautifulMermaidText`                                                                                                                  |
+| Runtime        | `@simon_he/vue-tui/runtime`                 | runtime, event, and selection APIs                                                                                                                                                               |
+| CLI            | `@simon_he/vue-tui/cli`                     | `createTerminalApp`, `createStdoutRenderer`, `createStdinDriver`, Node host adapters                                                                                                             |
+
+For streaming Mermaid source, pass `streaming` with `final`. When `streaming=true` and `final=false`, transient renderer errors do not replace the last successfully rendered diagram; if no diagram has rendered yet, `incompleteText` is shown until the source becomes renderable or `final=true` surfaces the final error.
 
 This table is a category overview. The generated API reference for root, `/vue`, and `/experimental` components lives in [docs/generated/components-api.md](./docs/generated/components-api.md) for humans and [docs/generated/api-manifest.json](./docs/generated/api-manifest.json) for CI, release checks, and README/docs drift checks; the manifest also tracks package entrypoint exports.
 
 ## Documentation
 
-| Page                                                             | Purpose                                                              |
-| ---------------------------------------------------------------- | -------------------------------------------------------------------- |
-| [Docs home](./docs/index.md)                                     | Product overview and reading path                                    |
-| [Examples index](./docs/examples.md)                             | Browser, terminal, and smoke example commands                        |
-| [Core API](./docs/api.md)                                        | Terminal, renderer, events, runtime, planes, and scheduler contracts |
-| [Performance](./docs/performance.md)                             | Practical performance guidance                                       |
-| [Benchmarks](./docs/benchmarks.md)                               | Release benchmark budgets, sample results, and comparison boundaries |
-| [OpenTUI Solid comparison](./docs/compare-opentui-solid.md)      | Same-scenario comparison protocol and public claim boundaries        |
-| [High-throughput rendering](./docs/high-throughput-rendering.md) | Scheduler, dirty rows, mailbox, log, and renderer architecture       |
-| [Component acceptance](./docs/components-acceptance.md)          | Release readiness checks for component API and behavior              |
-| [Agent Console](./docs/agent-console.md)                         | Streaming transcript example stack                                   |
-| [Release candidate](./docs/release-candidate.md)                 | 1.0 RC validation, package export checks, and migration notes        |
-| [Security policy](./SECURITY.md)                                 | Vulnerability reporting and terminal permission boundaries           |
+| Page                                                               | Purpose                                                              |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| [Docs home](./docs/index.md)                                       | Product overview and reading path                                    |
+| [Vue Terminal UI](./docs/guide/vue-terminal-ui.md)                 | English landing page for terminal-style Vue interfaces               |
+| [Vue CLI UI](./docs/guide/vue-cli-ui.md)                           | CLI app model with Vue component composition                         |
+| [CLI stdout renderer](./docs/guide/cli-stdout-renderer.md)         | Stdout renderer, stdin driver, cleanup, and terminal output          |
+| [Terminal log viewer](./docs/guide/terminal-log-viewer.md)         | Append-only logs, retained windows, wrapping, links, and search      |
+| [Markdown transcripts](./docs/guide/markdown-transcript.md)        | Static and streaming markdown transcript rendering                   |
+| [Examples index](./docs/examples.md)                               | Browser, terminal, and smoke example commands                        |
+| [Core API](./docs/api.md)                                          | Terminal, renderer, events, runtime, planes, and scheduler contracts |
+| [Terminal UI best practices](./docs/terminal-ui-best-practices.md) | Cell layout, input focus, render invalidation, transcripts, tests    |
+| [Performance](./docs/performance.md)                               | Practical performance guidance                                       |
+| [Benchmarks](./docs/benchmarks.md)                                 | Release benchmark budgets, sample results, and comparison boundaries |
+| [OpenTUI Solid comparison](./docs/compare-opentui-solid.md)        | Same-scenario comparison protocol and public claim boundaries        |
+| [High-throughput rendering](./docs/high-throughput-rendering.md)   | Scheduler, dirty rows, mailbox, log, and renderer architecture       |
+| [Component acceptance](./docs/components-acceptance.md)            | Release readiness checks for component API and behavior              |
+| [Agent Console](./docs/agent-console.md)                           | Streaming transcript example stack                                   |
+| [Release candidate](./docs/release-candidate.md)                   | 1.0 RC validation, package export checks, and migration notes        |
+| [Security policy](./SECURITY.md)                                   | Vulnerability reporting and terminal permission boundaries           |
 
 Run the docs locally:
 
@@ -306,6 +398,7 @@ pnpm run release:dry-run
 
 - The published package ships `dist` only.
 - Root, core, runtime, DOM renderer, observability, Vue, CLI, markdown, experimental, and agent entrypoints are available as ESM, CJS, and type declarations after build.
+- The Mermaid bridge entrypoints ship ESM, CJS, and type declarations.
 - The root browser/core API does not require a Node runtime, but CLI usage expects a Node-like stdout/stdin environment.
 - Terminal emoji and East Asian width behavior still depends on the user terminal and font.