@simon_he/vue-tui 0.0.7 → 1.0.0-rc.0

package/README.md

@@ -1,526 +1,304 @@
-# Vue Terminal
+# @simon_he/vue-tui
 
-用 Vue 组件语法绘制和交互的终端渲染框架。目标是让 “终端” 具备：
+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.
 
-- 类终端的写入/删除/更新/尺寸调整能力
-- ANSI 样式渲染（颜色、加粗、下划线等）
-- 事件机制（点击、移动、滚动、拖拽）
-- Vue 组件 + 响应式数据驱动终端界面更新
+Use it when you want:
 
-## 快速开始
+- 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.
 
-### 浏览器渲染
-
-```vue
-<script setup lang="ts">
-import { computed, ref } from 'vue'
-import {
-  TerminalProvider,
-  TBox,
-  TInput,
-  TText,
-  useLayout,
-} from '@simon_he/vue-tui'
-
-const layout = useLayout()
-const cols = computed(() => layout.clipRect?.w ?? 80)
-const rows = computed(() => layout.clipRect?.h ?? 24)
-const input = ref('')
-</script>
-
-<template>
-  <TerminalProvider
-    :cols="80"
-    :rows="24"
-    :default-style="{ fg: 'whiteBright' }"
-  >
-    <TBox
-      :x="0"
-      :y="0"
-      :w="80"
-      :h="24"
-      border
-      title="Demo"
-      :padding="1"
-      :style="{ fg: 'blueBright' }"
-    >
-      <TText :x="0" :y="0" :w="78" :value="`cols=${cols} rows=${rows}`" />
-      <TInput :x="0" :y="20" :w="78" v-model="input" placeholder="Type..." />
-    </TBox>
-  </TerminalProvider>
-</template>
-```
-
-## 组件文档与验收标准
-
-- VitePress 文档站点（本地）：`bun run --filter '@simon_he/vue-tui' docs:dev`（入口 `docs/index.md`）
-- 组件使用文档：`docs/components.md`
-- 组件 Props/Events（自动生成）：`docs/generated/components-api.md`（脚本：`scripts/generate-component-api-docs.ts`）
-- 组件验收标准（可信赖组件定义 + 测试范围）：`docs/components-acceptance.md`
-- Terminal 兼容性与颜色一致性：`docs/terminal-compatibility.md`
-- 性能关注点与回归策略：`docs/performance.md`
-
-### 终端（真实 CLI）渲染
-
-内置 `vue-terminal run`，直接在真实终端中跑 UI（stdout renderer + stdin driver）：
+## Install
 
 ```bash
-pnpm build
-node cli.mjs --app basic
+pnpm add @simon_he/vue-tui@rc vue
 ```
 
-## GoatChain（示例应用）
+Vue is a peer dependency. The current package supports Vue `>=3.3.0 <4`.
 
-GoatChain 风格的示例应用放在 `examples/goatchain`（支持 browser + terminal 构建）。
+## Runtime Support
 
-## 示例工程
+The published package supports Node.js `>=16.17` for CLI/runtime consumers.
 
-```bash
-# 浏览器示例（交互测试）
-pnpm -C examples/basic dev
-pnpm -C examples/goatchain dev
+Development, release validation, and documentation builds are run on Node.js 20 in CI because the repository toolchain uses modern build/test tooling.
 
-# 打包 browser
-pnpm build:examples
-
-# 打包成 terminal 产物并运行
-pnpm build:examples:terminal
-pnpm run:basic:terminal
-pnpm run:goatchain:terminal
-```
+## Entry Points
 
-terminal 构建产物会生成 `dist-terminal/terminal.js`，可以直接作为 `bin` 入口使用。
+| 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`, `TLogView`, TLog search/link/minimap companions, append-only log store, and TLog plugins                    |
 
-## LLM 集成（对接指南）
+The stable surface is terminal core, DOM rendering, CLI runtime, basic Vue components, and markdown APIs. High-throughput log and virtualization APIs stay under `/experimental` until their public surface settles; keep those imports isolated in application code.
 
-GoatChain 示例应用目前用的是 mock LLM，但你可以很快替换成任意 LLM SDK（OpenAI/Anthropic/本地模型）。
+Do not deep import from `@simon_he/vue-tui/dist/...`; only the entry points above are part of the supported package contract.
 
-建议做法：
+### Migration: Node Host Adapter Moved To `/cli`
 
-1. 用 ACP 风格的流式协议驱动 UI（支持 `text_delta` / `tool_call_delta` / `tool_call_end` / `tool_result` / `done`）。
-2. tool_call 的执行可以交给 agent 侧（推荐，和 GoatChain CLI 一致），UI 只负责渲染与“暂停→继续”的用户输入。
-3. 在 UI 侧维护 token 统计与 context window（真实 tokenizer 或近似估算均可）。
+Node-specific input host defaults are no longer exported from the browser-safe root entrypoint.
 
-GoatChain 的核心协议定义在：
+Before:
 
-- `apps/goatchain/src/core/acp.ts`
-- `apps/goatchain/src/core/model.ts`
-- `apps/goatchain/src/core/store.ts`
-- `apps/goatchain/src/tools-mock.ts`
-
-你只需要实现一个 `GoatChainAgent`（`receiveMessage(messages, metadata)` → `AsyncGenerator<ACPMessage>`），并传给 `GoatChainShell/GoatChainProvider`，其余 UI 与交互可以复用。
-
-## 核心概念
-
-- Buffer: 以 Cell 网格存储字符与样式，负责最小化更新
-- Renderer: 将 Buffer diff 渲染为 DOM（后续可扩展 canvas）
-- EventManager: DOM 事件 -> cell 坐标 -> 命中测试 -> 派发给组件
-- Vue Layer: 提供 `TerminalProvider` 与内置组件 (TText/TBox/TView)
-- UI Layer: 通用组件与指令（`select`, `v-if`, `v-show` 等）
-- Vue3 对齐: 事件名称/修饰符/行为尽量与浏览器 Vue3 保持一致
-
-## 模块分层（建议结构）
-
-```
-src/
-  core/
-    buffer/       # Cell 网格、dirty 标记、宽字符
-    terminal/     # Terminal API（write/clear/resize/batch/commit）
-    ansi/         # ANSI 解析 -> Style
-  renderer/
-    dom/          # 行/Span 渲染、diff 更新
-  events/
-    manager/      # 坐标映射、hit test、事件派发
-  vue/
-    components/   # TerminalProvider, TText, TBox, TView
-    composables/  # useTerminal, useTerminalNode
-    directives/   # v-if, v-show, v-model, v-focus 等
-    runtime/      # 动态插入、组件工厂、命令式渲染
-```
-
-## 数据流
-
-```
-Vue 组件 -> Terminal API -> Buffer -> Diff -> Renderer -> DOM
-DOM 事件 -> EventManager -> HitTest -> Vue 组件事件回调
+```ts
+import { createDefaultTInputHostAdapter, defaultTInputHostPlugin } from "@simon_he/vue-tui";
 ```
 
-## 核心数据结构（设计草案）
+After:
 
 ```ts
-type Style = {
-  fg?: string
-  bg?: string
-  bold?: boolean
-  dim?: boolean
-  italic?: boolean
-  underline?: boolean
-  inverse?: boolean
-}
-
-type Cell = {
-  ch: string
-  style: Style
-  width: 1 | 2 // 宽字符支持
-}
-
-type Buffer = {
-  rows: Cell[][]
-  cols: number
-  rowsCount: number
-  dirtyRows: boolean[]
-}
+import { createTInputHostPlugin } from "@simon_he/vue-tui";
+import { createDefaultTInputHostAdapter, defaultTInputHostPlugin } from "@simon_he/vue-tui/cli";
 ```
 
-## 终端语义范围（初版约束）
-
-- `write()` 默认不解析 ANSI，仅做“就地写入”，越界裁剪
-- `writeAnsi()` 解析 ANSI 样式与基础控制序列
-- 光标与换行：`write()` 未提供 `x/y` 时使用内部 cursor，带 `x/y` 不更新全局 cursor
-- `scroll()` 仅滚动可视区域（是否保留 scrollback 由实现决定）
+### Migration: Root Entry Was Narrowed
 
-## Viewport 与 Scrollback（建议）
+The root entrypoint now keeps only stable browser-safe APIs. Extended Vue components and Vue router/composable helpers move to `@simon_he/vue-tui/vue`.
 
-- Buffer 区分 viewport（可视区域）与 scrollback（历史区域）
-- cursor 驱动写入在底部时超出触发滚动
-- `scroll(lines)` 只移动 viewport，不影响 buffer 内容
-- 支持 `scrollTo()` 与 scrollback 上限（内存可控）
+| Before root import | New import              |
+| ------------------ | ----------------------- |
+| `TAnchor`          | `@simon_he/vue-tui/vue` |
+| `TFlow`            | `@simon_he/vue-tui/vue` |
+| `TInputBox`        | `@simon_he/vue-tui/vue` |
+| `TPathPicker`      | `@simon_he/vue-tui/vue` |
+| `TJsonEditor`      | `@simon_he/vue-tui/vue` |
+| `TRenderPlane`     | `@simon_he/vue-tui/vue` |
+| `TRenderLayer`     | `@simon_he/vue-tui/vue` |
+| `TTransition`      | `@simon_he/vue-tui/vue` |
+| router/composables | `@simon_he/vue-tui/vue` |
+| Node host defaults | `@simon_he/vue-tui/cli` |
 
-## Terminal API（设计草案）
+Before:
 
 ```ts
-interface Terminal {
-  resize(cols: number, rows: number): void
-  clear(x?: number, y?: number, w?: number, h?: number): void
-  write(text: string, opts?: { x?: number; y?: number; style?: Style }): void
-  writeAnsi(text: string, opts?: { x?: number; y?: number }): void
-  put(x: number, y: number, ch: string, style?: Style): void
-  fill(
-    x: number,
-    y: number,
-    w: number,
-    h: number,
-    ch?: string,
-    style?: Style,
-  ): void
-  scroll(lines: number): void
-  setCursor(x: number, y: number, visible?: boolean): void
-  batch(fn: () => void): void
-  commit(): void
-  on(event: TerminalEvent, cb: (e: TerminalEventPayload) => void): () => void
-  dispose(): void
-}
+import { TAnchor, TFlow } from "@simon_he/vue-tui";
 ```
 
-## 事件模型（设计草案）
-
-- 事件名称与 Vue3 DOM 事件对齐（`@click`, `@keydown`, `@input` 等）
-- DOM 事件转换为 cell 坐标 (cellX/cellY)
-- hit test 查找当前坐标命中的节点 (支持 zIndex)
+After:
 
 ```ts
-type TerminalEvent =
-  | 'click'
-  | 'dblclick'
-  | 'contextmenu'
-  | 'pointerdown'
-  | 'pointerup'
-  | 'pointermove'
-  | 'pointerenter'
-  | 'pointerleave'
-  | 'mousedown'
-  | 'mouseup'
-  | 'mousemove'
-  | 'mouseenter'
-  | 'mouseleave'
-  | 'wheel'
-  | 'keydown'
-  | 'keyup'
-  | 'input'
-  | 'change'
-  | 'compositionstart'
-  | 'compositionupdate'
-  | 'compositionend'
-  | 'focus'
-  | 'blur'
-  | 'drag'
-
-type TerminalBaseEvent = {
-  type: TerminalEvent
-  target: TerminalNode | null
-  currentTarget: TerminalNode | null
-  bubbles: boolean
-  cancelable: boolean
-  defaultPrevented: boolean
-  timeStamp: number
-  stopPropagation(): void
-  preventDefault(): void
-  nativeEvent?: Event
-}
-
-type TerminalPointerEvent = TerminalBaseEvent & {
-  clientX: number
-  clientY: number
-  cellX: number
-  cellY: number
-  button?: number
-  buttons?: number
-  ctrlKey?: boolean
-  shiftKey?: boolean
-  altKey?: boolean
-  metaKey?: boolean
-  deltaY?: number
-}
-
-type TerminalKeyboardEvent = TerminalBaseEvent & {
-  key: string
-  code: string
-  ctrlKey?: boolean
-  shiftKey?: boolean
-  altKey?: boolean
-  metaKey?: boolean
-  repeat?: boolean
-}
-```
-
-## 事件派发与冒泡（建议）
-
-- 默认冒泡，支持 `stopPropagation()`/`preventDefault()`，语义与 DOM 一致
-- 支持捕获阶段（可选），用于全局拦截（与 `.capture` 对齐）
-- 拖拽使用 pointer capture，保证按下后持续命中
-- 支持 `contextmenu` 事件（右键菜单）
-
-## 事件桥接（建议）
-
-- Terminal 事件与 Vue 组件事件做统一归一化
-- 事件路径包含命中节点链，便于冒泡与拦截
-- `pointer` 事件优先于 `mouse`，便于兼容触控
-
-## Vue3 浏览器事件对齐（约定）
-
-- 事件名称：与浏览器 DOM 事件一致（`click`, `keydown`, `input`, `focus` 等）
-- 事件修饰符：支持 `.stop` `.prevent` `.capture` `.once` `.passive` `.self` `.exact`
-- 键盘修饰符：`.ctrl` `.shift` `.alt` `.meta` `.enter` `.esc` 等与 Vue3 行为一致
-- 指针/鼠标：`pointer*` 优先，`mouse*` 兼容；`clientX/clientY` 保留
-- 事件对象：保留原生字段，并额外提供 `cellX/cellY` 与 `nativeEvent`
-- `v-model`：保持 `modelValue` + `update:modelValue` 的 Vue3 约定
-
-## 事件映射表（核心字段）
-
+import { TAnchor, TFlow } from "@simon_he/vue-tui/vue";
 ```
-DOM Mouse/Pointer Event -> TerminalPointerEvent
-- clientX/clientY 保留，额外提供 cellX/cellY
-- button/buttons/ctrlKey/shiftKey/altKey/metaKey 保留
-DOM Keyboard Event -> TerminalKeyboardEvent
-- key/code/repeat/ctrlKey/shiftKey/altKey/metaKey 保留
-DOM Input/Composition Event -> TerminalBaseEvent
-- inputType/data 通过 nativeEvent 获取
-```
-
-## `@input` / `@change` 触发规则（建议）
 
-- `TInput` 输入过程中触发 `input`，提交时触发 `change`
-- `compositionstart/update/end` 与浏览器一致，结束后触发一次 `input`
-- `v-model` 绑定：`input` 时更新 `modelValue`，`change` 作为提交确认
+### Hyperlinks
 
-## Pointer Capture / Focus / Blur 规则（建议）
+DOM renderer link rendering is opt-in through `domRendererOptions.links`. Once enabled, DOM anchors allow safe absolute and relative targets such as `https:`, `http:`, `mailto:`, `/path`, `./path`, `../path`, `#hash`, and `?q=1`. Link callbacks preserve native browser behavior unless they return `false`.
 
-- `pointerdown` 后启用捕获，直到 `pointerup` 释放
-- `focus` 由点击或 `v-focus` 触发，`blur` 由切换焦点或卸载触发
-- `focusin/focusout` 可选支持，用于冒泡式焦点事件
+CLI/stdout rendering uses OSC8 hyperlinks and keeps a stricter boundary: only safe absolute `https:`, `http:`, and `mailto:` hrefs are emitted by default. `file:` links stay opt-in for terminal-specific providers.
 
-## Vue 组件层（设计草案）
+## Browser Usage
 
 ```vue
-<TerminalProvider :cols="80" :rows="24">
-  <TView :x="2" :y="2" :w="20" :h="5" @click="onClick">
-    <TText :value="title" :style="{ fg: 'green' }" />
-    <TBox border />
-  </TView>
-</TerminalProvider>
-```
-
-- `TerminalProvider`: 创建 terminal、绑定 renderer 和 event manager
-- `TView`: 提供局部坐标系、事件区域、zIndex
-- `TText`: 响应式写入文字
-- `TBox`: 绘制边框、标题
-
-## 通用组件与指令
-
-- 通用组件：`TSelect`, `TInput`, `TList`, `TTable`, `TDialog`
-- 指令：
-  - `v-if`: 条件渲染/卸载组件，释放 buffer 区域
-  - `v-show`: 仅隐藏展示，保持节点存在以保留事件与状态
-  - `v-model`: 绑定 `TInput` 文本与光标状态
-  - `v-focus`: 让组件获得焦点（键盘输入）
-
-## 动态插入组件（命令式）
+<script setup lang="ts">
+import { ref } from "vue";
+import { TerminalProvider, TBox, TInput, TText } from "@simon_he/vue-tui";
 
-支持在事件回调中插入组件，例如监听 `input` 后插入 `TSelect`。
-通过 `useTerminalRuntime()` 或 `createPortal()` 提供命令式入口。
+const input = ref("");
+</script>
 
-```ts
-const { mount } = useTerminalRuntime()
-
-function onInputCommit(value: string) {
-  if (value.startsWith('/')) {
-    mount(TSelect, {
-      x: 2,
-      y: 10,
-      w: 20,
-      h: 6,
-      options: ['a', 'b', 'c'],
-      onSelect: (v) => console.log(v),
-    })
-  }
-}
+<template>
+  <TerminalProvider :cols="80" :rows="24" :default-style="{ fg: 'whiteBright' }">
+    <TBox :x="0" :y="0" :w="80" :h="24" border title="Demo" :padding="1">
+      <TText :x="0" :y="0" :w="78" value="Vue TUI is running" />
+      <TInput :x="0" :y="20" :w="78" v-model="input" placeholder="Type..." />
+    </TBox>
+  </TerminalProvider>
+</template>
 ```
 
-约束：
+`TerminalProvider` wires the terminal buffer, DOM renderer, event manager, scheduler, runtime, layout context, and input plugins for browser Vue apps.
 
-- 动态插入的组件必须显式提供布局 (x/y/w/h) 或依赖父容器布局
-- 插入/卸载会触发局部重绘，不影响其它区域
+## CLI Usage
 
-## 命令式渲染协议（建议）
-
-- `mount()` 返回 handle，包含 `update()` / `unmount()` / `move()` 等操作
-- 允许传入 `key` 复用实例，避免频繁销毁
-- `TerminalProvider` 卸载时自动清理所有命令式节点
+For a real terminal, mount a headless Vue app and attach stdout/stdin:
 
 ```ts
-type TerminalHandle = {
-  update: (props: Record<string, unknown>) => void
-  move: (x: number, y: number) => void
-  unmount: () => void
-}
+import {
+  createStdinDriver,
+  createStdoutRenderer,
+  createTerminalApp,
+  installTerminalCleanup,
+  type TerminalCleanupHandle,
+} from "@simon_he/vue-tui/cli";
+import App from "./App.vue";
+
+const app = createTerminalApp({
+  cols: process.stdout.columns || 80,
+  rows: process.stdout.rows || 24,
+  component: App as any,
+  defaultStyle: { fg: "whiteBright" },
+});
+
+app.mount();
+
+const renderer = createStdoutRenderer(app.terminal, {
+  output: process.stdout,
+  hideCursor: true,
+  colorMode: "auto",
+  allowFileUrls: true,
+});
+
+app.scheduler.flush();
+
+let driver: ReturnType<typeof createStdinDriver> | null = null;
+let terminalCleanup: TerminalCleanupHandle | null = null;
+let disposed = false;
+
+const cleanup = () => {
+  if (disposed) return;
+  disposed = true;
+  terminalCleanup?.uninstall();
+  driver?.dispose();
+  renderer.dispose();
+  app.dispose();
+};
+
+const exit = () => {
+  cleanup();
+  process.exit(0);
+};
+
+terminalCleanup = installTerminalCleanup(cleanup, {
+  signalPolicy: "reraise",
+  cleanupOnUnhandledRejection: false,
+});
+driver = createStdinDriver({
+  dispatch(event) {
+    const prevented = app.events.dispatch(event);
+    app.scheduler.flush();
+    return prevented;
+  },
+  enableMouse: true,
+  onExit: exit,
+});
 ```
 
-## 组件生命周期与资源管理（建议）
+Signal cleanup restores terminal state first. `installTerminalCleanup()` returns a cleanup handle: call `handle.uninstall()` to remove process listeners without disposing the app, or `handle.cleanup()` to run cleanup manually. By default, signal handling uses `signalPolicy: "reraise"`: the helper cleans up, removes its own listeners, and re-sends the original signal when no other listener owns that signal. If the host process has other listeners for the same signal, those listeners keep ownership of termination. Set `signalPolicy: "cleanup-only"` only when the host explicitly owns termination, or `signalPolicy: "exit"` when vue-tui should exit with the conventional signal exit code after cleanup.
 
-- 挂载：注册事件节点、占用 buffer 区域、写入初始内容
-- 更新：清理旧区域 + 写入新内容，保持最小 dirty 范围
-- 卸载：释放事件节点、清理 buffer 区域、移除焦点/输入绑定
+Unhandled promise rejections stay host-owned by default. Setting `cleanupOnUnhandledRejection: true` cleans up and rethrows by default. Set `rethrowUnhandledRejection: false` only when the host explicitly wants to suppress the rejection.
 
-对 `v-if`/`v-show` 的行为约定：
+## Core Concepts
 
-- `v-if`: 触发卸载与资源释放（清 buffer、解绑事件）
-- `v-show`: 仅隐藏渲染，保留节点与状态（不解绑事件）
+- `createTerminal({ cols, rows })` owns the cell buffer, cursor, planes, scrollback, and commit events.
+- `createDomRenderer(terminal, container)` renders terminal cells to DOM with row caching and fast paths for plain and styled rows.
+- `createStdoutRenderer(terminal, options)` emits ANSI output for real terminal UIs from `/cli`.
+- `TerminalProvider` is the browser-facing Vue runtime provider.
+- `createTerminalApp()` is the headless runtime for CLI apps and deterministic tests.
+- `TRenderPlane` separates transcript, chrome, input, and overlay surfaces so small updates do not repaint large panes.
 
-## 焦点与输入协议（建议）
+## Components
 
-- 引入 focus manager，维护当前焦点组件
-- `v-focus`/`focus()` 触发焦点切换，自动更新光标样式
-- 键盘事件仅派发给焦点组件
-- `TInput` 需要处理：
-  - 文本插入、删除、移动光标
-  - 组合输入（IME）阶段的暂存显示
-  - Enter/Escape 行为（提交/取消）
+| Area           | Import                           | Components / APIs                                                                                                                                                          |
+| -------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Stable layout  | `@simon_he/vue-tui`              | `TBox`, `TView`                                                                                                                                                            |
+| Stable text    | `@simon_he/vue-tui`              | `TText`                                                                                                                                                                    |
+| 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`, `TLogView`, `TLogSearchBar`, `TLogLinksPanel`, `TLogScrollbar`, `TLogMinimap`                                                                              |
+| Runtime        | `@simon_he/vue-tui/runtime`      | runtime, event, and selection APIs                                                                                                                                         |
+| CLI            | `@simon_he/vue-tui/cli`          | `createTerminalApp`, `createStdoutRenderer`, `createStdinDriver`, Node host adapters                                                                                       |
 
-## 键盘与快捷键（建议）
+See [docs/components.md](./docs/components.md) and [docs/generated/components-api.md](./docs/generated/components-api.md) for props and events.
 
-- 统一规范化键名（如 `Enter`/`Esc`/`ArrowUp`）
-- 仅焦点组件接收输入，支持全局快捷键注册
-- 支持组合键与平台差异（macOS/Windows/Linux）
+## 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                                       |
+| [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           |
 
-- `TSelect`:
-  - 上下键切换选项，Enter 确认，Esc 取消
-  - `onOpen`/`onClose` 用于显示/隐藏下拉
-- `TList`:
-  - 支持滚动、虚拟化（列表过长时）
-- `TDialog`:
-  - 居中布局、遮罩区域、阻止底层事件
+Run the docs locally:
 
-## 响应式与尺寸变化（建议）
-
-- `TerminalProvider` 监听容器尺寸变化，触发 `resize(cols, rows)` 并广播 `resize` 事件
-- 组件接收 `onResize` 或 `useTerminalSize()` 响应尺寸变化
-- 布局建议：
-  - `TView` 支持 `w/h` 为百分比或 `auto`（依赖父容器）
-  - resize 时触发局部重排，避免全量重绘
-
-## 布局与坐标系统（建议）
-
-- 坐标系基于 cell 网格，所有位置/尺寸以整数为主
-- 布局模式：
-  - `absolute`: `x/y/w/h` 明确指定
-  - `flow`: 垂直/水平流布局（简化版）
-  - `anchor`: 支持 `left/right/top/bottom` 锚定
-- 约束：`minW/maxW/minH/maxH`，超出时裁剪
-- 容器提供 `padding` 与 `clip`，子组件默认裁剪到内容区域
-
-## 布局计算（简版规则）
-
-- 先计算父容器 contentRect，再计算子组件布局
-- `absolute` 优先：有明确 `x/y/w/h` 时直接裁剪
-- `anchor` 次之：根据边距计算剩余空间
-- `flow` 最后：按方向累积尺寸，支持 `gap` 与 `wrap`
-- `auto` 尺寸：基于内容测量（文本/子组件）得到
-
-## 带边框 Box 的内容保护
-
-当 `TBox` 带边框时，需要保护内容区域不被破坏：
-
-- 外框占 1 cell 边距，内容区域为 `(x+1, y+1, w-2, h-2)`
-- 内容写入必须裁剪到内容区域，避免覆盖边框
-- 当内容超出时，支持 `overflow: clip | scroll`
-- 建议 `TBox` 内部提供 `padding` 与 `contentRect`，子组件写入基于 `contentRect`
+```bash
+pnpm run docs:dev
+pnpm run docs:build
+```
 
-## 渲染策略（初版）
+## Examples
 
-- 以行 (row) 为单位进行 dirty 标记
-- 每行合并相同样式为 span，减少 DOM 节点数
-- `batch()` + `commit()` 合并更新
+```bash
+pnpm -C examples/basic dev
+pnpm run build:examples
+pnpm run build:examples:terminal
+pnpm run run:basic:terminal
+pnpm run example:tlog-view-lab
+pnpm run example:agent-console
+pnpm run example:agent-console:smoke
+pnpm run example:agent-console:terminal:smoke
+```
 
-## 渲染调度（建议）
+The smoke commands are deterministic and avoid real LLM APIs, real TTY dependencies, and timing-only pass/fail gates.
 
-- 所有写入走调度器聚合到下一帧（`requestAnimationFrame`）
-- `batch()` 在同一帧内合并多个写入，减少 diff 次数
-- 支持 `flush()` 立即渲染（用于调试或关键交互）
+## Performance Notes
 
-## 字体度量与像素映射（建议）
+- Use `TVirtualList` instead of rendering thousands of row components.
+- Use `TLogView` with `createAppendOnlyLogStore({ maxLines })` for retained streaming logs.
+- Provide stable line keys for custom `TLogView` sources; mutable rows should change keys or call the explicit invalidation APIs.
+- Split high-volume content and frequently changing chrome into different `TRenderPlane`s.
+- Style objects are treated as immutable. Reuse stable style objects on hot paths, but pass a new object when a style changes.
 
-- 统一使用等宽字体，测量 `cellWidth`/`cellHeight`
-- 设备像素比变化时重新测量并触发重排
-- 支持固定 `cellSize` 覆盖测量结果（用于稳定布局）
+Useful checks:
 
-## ANSI 支持
+```bash
+pnpm run bench:dom-renderer
+pnpm run bench:scroll-mailbox
+pnpm run bench:phase2
+```
 
-- `writeAnsi()` 接受 ANSI 字符串，解析后写入 Buffer
-- 可先实现轻量解析器，后续切换到更完整的 ANSI 样式库（如 `ansis`）
+## Issues And Feedback
 
-## 文本分段与宽字符策略（建议）
+- Report bugs: [new bug report](https://github.com/Simon-He95/vue-tui/issues/new?template=bug_report.yml)
+- Request features: [new feature request](https://github.com/Simon-He95/vue-tui/issues/new?template=feature_request.yml)
+- Report documentation issues: [new docs issue](https://github.com/Simon-He95/vue-tui/issues/new?template=docs.yml)
+- Report vulnerabilities privately: [Security policy](./SECURITY.md)
+- Browse existing issues: [GitHub issues](https://github.com/Simon-He95/vue-tui/issues)
 
-- 使用 grapheme 分段，避免组合字符被拆分
-- 宽字符占用 2 cell，后续 cell 标记为 continuation
-- 无法渲染的字符使用占位符（如 `?`）并记录告警
+For renderer, scheduler, or terminal behavior bugs, include the renderer target (`DOM`, `stdout`, or headless), the relevant command, and a minimal reproduction when possible.
 
-## 主题与样式系统（建议）
+## Development
 
-- 提供 `Theme` 对象（默认 fg/bg、16/256 色板、字体设置）
-- ANSI 颜色映射依赖主题，可热更新
-- 允许组件局部覆盖主题（如 `TDialog`）
+Use Node.js 20 for repository development, release validation, and documentation builds. This is a toolchain requirement, not the runtime requirement for the published package.
 
-## 光标、选择与剪贴板（建议）
+```bash
+pnpm install
+pnpm run format:check
+pnpm run lint
+pnpm run typecheck
+pnpm run test
+pnpm run build
+```
 
-- 光标形态：`block`/`underline`/`bar`，支持闪烁
-- 选择：鼠标拖拽选区，支持跨行
-- 剪贴板：复制/粘贴基于 Buffer 内容而非 DOM 文本
+Release validation:
 
-## 设计注意事项
+```bash
+pnpm run release:dry-run
+```
 
-- 文本宽度：需支持 grapheme + wcwidth，避免 emoji/组合字符错位
-- 组合模型：建议引入容器裁剪与 zIndex，避免组件相互覆盖
-- 调度机制：统一 batch/commit，避免组件更新引发频繁重绘
-- 事件映射：需基于字体度量映射 cell 坐标，resize 时重算
-- 滚动与 resize：需要明确 scrollback 与重排策略
+`release:dry-run` runs checks, tests, docs build, benchmarks, examples smoke, and packed package install smoke.
+`release:ci` aliases `release:dry-run` for validation-only CI usage. The GitHub Release workflow is preferred because it publishes the already-verified tarball with npm provenance. If workflow token/provenance is unavailable, `release:local:dry-run` and `release:local` publish the locally verified tarball with the `rc` dist-tag. `release` and `release:workflow-only` intentionally fail to avoid accidental direct publishing.
 
-## 后续计划（草案）
+## Package Notes
 
-- 基础组件库完善 (TList/TInput/TTable)
-- Canvas 渲染器
-- 虚拟滚动和大 buffer 支持
+- The published package ships `dist` only.
+- Root, core, runtime, DOM renderer, observability, Vue, CLI, markdown, and experimental entrypoints are available as ESM, CJS, and type declarations after build.
+- 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.
 
 ## License