DevelopmentCell UI
Cell UI Overview
Current product constraints, dependencies, and architecture ownership.
HEAD a63778eCell UI 事实白板
本页只登记 Cell UI 当前有效的产品约束、依赖关系和权威入口。交付状态见 Status，交互规则见 Cell-native UI 哲学。被替代的判断只存在于 Git 历史。
产品事实
- 产品是可嵌入普通网页的 React/TypeScript TUI，不是 shell 或终端模拟器。
- Everything is Cell：layout、text、scroll、hit、selection 和 copy 使用整数 column/row；px 只存在于浏览器输入与 Canvas 输出边界。
- Cell 尺寸固定；容器余量是 gutter，不反向拉伸 Cell。
- React Widget Tree 是状态入口；Cell Scene、Semantic Tree、clipboard 和测试快照是同一次 commit 的投影。
- Layout 只产生尺寸；SceneGeometry 拥有 scroll、clip、layer、visibility、paint order 和 hit geometry。
Cell.text是可见前景真值；border、thumb、内容、复制和 Probe 读取相同 Unicode。- renderer 聚合 row/styled run，不创建 DOM-per-cell；Semantic DOM 按 Widget/Item 创建。
- Canvas 与 Semantic DOM 共用 focus/selection/command 权威。
- 一棵 Widget Tree 只使用一个 Layout Engine；Foreign Surface 默认不进入统一 CellBuffer。
- macOS
⌥⌘、其他平台 Alt 加 pointer drag 选择最终可见 Cell rectangle，可复制边框、空白和内容。
当前上游关系
| 上游 | 当前关系 | 本项目边界 | 权威入口或研究 |
|---|---|---|---|
| Yoga | 分层采用 | YogaLayoutEngine 使用官方 yoga-layout，不暴露 Yoga 类型 | Layout engine |
| CodeMirror 6 | 分层采用 | 使用 @codemirror/state，不使用 DOM View | Editor state |
| React Stately | 分层采用 | collection/selection adapter；Semantic DOM 由自有 browser adapter 生成 | Collection adapter |
| OpenTUI、Ink、Ratatui、Textual | 行为参考 | 不进入运行时依赖图 | OpenTUI、Ink、Ratatui、Textual |
| Pretext、R3F、Flutter、egui | 契约参考 | 不复制其 runtime、scene 或状态权威 | Pretext、R3F、Flutter、egui |
上游研究只记录可借鉴机制与不采用边界，不维护外部项目的滚动版本或路线图。字体消费见 @chardesk/fonts；版本与资产以各包 manifest 为准。
架构所有权
| 领域 | 当前权威 | 所有权摘要 |
|---|---|---|
| Domain 与依赖方向 | Domain reference、Ownership | 业务职责与跨包依赖方向 |
| Unicode / Cell width | @chardesk/protocol | grapheme、1/2 Cell width、continuation 与 offset 映射 |
| Cell Core | @chardesk/cell-core | 逻辑 geometry、dense/sparse source、incremental changes、Frame 与字符快照 |
| Widget runtime | Cell Primitives | React descriptors、layout、scene、events、widgets、semantics 与 testing |
| Geometry / composition | Compositor 契约 | root geometry、clips、scroll、paint/hit order 与 invalidation |
| Visual / interaction standard | Classic Macintosh → Cell UI | System 6–7 原则到 Cell-native Web UI 的翻译与边界 |
| Widget behavior | Widget 规范 | 状态语言、keyboard/pointer 和 scroll/editor 行为 |
| Semantics | SemanticSnapshot 契约 | 独立 reading tree、actions 与 DOM projection |
| Canvas presentation | @chardesk/rendering | 标准 CellFrame 到 Canvas px、字体解析与网格审计 |
| Font capability | @chardesk/fonts | display/CJK/Nerd/symbol/emoji 字体路由；Host 与 Cell UI 的已登记 Unicode graphics 使用共享专用绘制器 |
| Editor state | @codemirror/state adapter | UTF-16 document/history；Cell geometry 由 CharDesk 投影 |
| Browser input | @chardesk/cell-ui/browser | textarea、IME、clipboard、pointer、Semantic DOM 与 DPR/resize |
| Delivery status | Status | 已交付、待验证和可实施切片 |
当前运行链路
React descriptors
→ Widget Tree
→ Yoga integer LayoutSnapshot
→ SceneSnapshot + SemanticSnapshot
├─ owner-aware CellBuffer → Canvas2D
└─ Semantic DOM
keyboard / pointer / wheel / AT / textarea
→ EngineInput
→ FocusManager + WidgetCommand
→ Stately or CodeMirror state
→ next commit公开组件门户由 apps/cell-ui 持有；编辑、Overlay、复杂 Widget 与虚拟化 fixture 继续服务自动化回归。