Files
marqdo/doc/design/view-document-annotations.md
T
cflmyandCursor 58ec2172d6 fix(view): mid-to-mid annot leaders and prose chip density
Unify frame chip ids with marks, reorder chips under anchors, and draw
SVG leaders from underline mid-bottom to chip mid-top so crowded bands
stay readable.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 20:36:12 +08:00

114 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# View:文档面与结果引出标注
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view.md](view.md) · [view-debug.md](view-debug.md) · [view-markup-surface.md](view-markup-surface.md) · [view-execution-trace.md](view-execution-trace.md) · [view-frame-selection.md](view-frame-selection.md) · [view-prose-annot-gaps.md](view-prose-annot-gaps.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
---
## 1. 动机
`.mq.md` 是叙述与程序的同一载体。`marqdo view` 的 Structure 必须**保真叙述**,并在可执行标记旁展示运行结果。
旧 Browse Structure 用 AST 卡片重建语句,并用 `emit_comments` 只插入**语句行之前**的注释。当叙述与 `**…**` / `*…*` / `` `名` `` 在同一行时,该行被 Stmt 占用,叙述被丢弃——信息密度接近 debug,不适合文档浏览。
## 2. 模式分工
| 命令 | Structure | 叙述 | 结果 |
|------|-----------|------|------|
| `marqdo view`(Browse) | **文档面** | 保留并为主 | 跑后引出标注(callout + CSS L-leader) |
| `marqdo debug` | AST 卡片 + BP gutter | 弱化/可折叠 | Variables / 步进;不做文档 callout |
断点与逐步执行**仅**在 debug。静态 `view output` 与 live view **共用** Browse 文档面渲染。
## 3. 视觉语法
```
文本段…… `变量` …… **语句** …… *返回*
━━━━━
│
└──→ 结果标注
```
1. 叙述正文正常排版(Markdown)。
2. 可执行片段高亮,并带底部分割线(underline)。
3. 段落下方 **annotation band** 放结果 callout。
4. **CSS L-leader**(绝对定位小盒 + `border-left` + `border-bottom`)连接锚点与 callout。**不使用 SVG。**
5. 拥挤 / 极窄屏 / `prefers-reduced-motion`:取消长横折,改为编号 keyed 列表。
关联强度(递减):同色 underline + callout 色条 + label → CSS L-leader → keyed 编号。
对齐 [view.md](view.md) HIG:系统字体、无外链、浅色、克制装饰。
## 4. 文档面渲染
实现:`src/view/document.rs`;Browse 入口经 `render_module_structure` 调用。
| 源内容 | 呈现 |
|--------|------|
| 纯叙述段 | Markdown HTML;无 `comment` badge / 厚卡片 |
| 含 `ProseBit` 的行 | 原文保留;Decl / BoldCode / ItalicReturn 包 `mark.mq-anchor`(字节偏移来自 `scan_prose_line`) |
| 整行结构(`#` / `>` / `-` / `1.` / 表) | 表面语法保真(见 [view-markup-surface.md](view-markup-surface.md));整句可作锚点 |
| 函数标题 | 轻量 heading + `id="fn-{line}"`(大纲跳转不变) |
Debug 仍走 `render_module_structure_mode(..., Debug)` 的 AST 卡片路径。
## 5. ViewAnnot
跑后(或 `--no-exec` 时为空)组装标注集,嵌入文档面 `data-*` 与 band HTML。
| 字段 | 含义 |
|------|------|
| `id` | 稳定短 id(页内唯一) |
| `kind` | `bind` · `return` · `call` · `expr` · `branch` · `loop` · `writeback` |
| `anchor_line` | 1-based 源行 |
| `anchor_byte_start` / `anchor_byte_end` | 行内字节范围(可选;整行锚点可省略 end) |
| `label` | 短标题(名 / return / arm / loop) |
| `value` | 截断显示 |
| `detail` | 完整文本(inspect) |
| kind | 数据来源 | 锚点 |
|------|----------|------|
| `bind` | **StmtEvent post-stmt**(赋值执行后的值);禁止用入口终态回填初始化行 | 该赋值行 |
| `return` | 返回事件或入口返回 | ItalicReturn / Return |
| `call` / `expr` / `writeback` | writeback 槽、调用摘要 | 语句行或 BoldCode |
| `branch` | `ViewTrace`:命中 arm、次数 | 条件 / arm |
| `loop` | `ViewTrace`:迭代次数、末次 item | While / ForEach 头 |
标记面、结构块、多调用帧与 AI JSON 见 [view-execution-trace.md](view-execution-trace.md)。
`ViewTrace` 由 tree 解释器在 capture 时静默收集,**不**写入 stderr;与 `trace_eval` 调试轨迹分离。Bytecode 后端可暂无 trace(标注降级为 writeback)。
## 6. 布局与密度
- 每段默认最多 **4** 个常显 callout;其余 hover / 「show more」。
- Leader:按锚点 x 排序 callout,避免交叉;窄屏改为短竖线 + 堆叠。
- 客户端:`ResizeObserver` 重算 leader 盒的 `left/top/width/height`。
- 静态导出:页载 JS 跑一次布局。
右侧 **Variables** 仍为全集绑定;callout 为就地摘要,点击可打开同一 inspect。
## 7. 非目标
- 不在 view 内做断点 / 单步(见 [view-debug.md](view-debug.md))。
- 不新增作者侧标注 DSL / frontmatter 指令。
- 不引入外链字体、npm 组件或 SVG leader。
- 不把 DB/auth 等塞进 view 壳层。
## 8. 验收
1. `inc-prose.mq.md`:叙述「对于输入变量…」完整可见;`n` / `n=n+1` / 返回高亮。
2. 跑完后:值经 underline + CSS L-leader 连到下方标注(无 SVG)。
3. 分支/循环样例:可见命中 arm 与迭代次数(有 ViewTrace 时)。
4. `marqdo debug` 仍为 AST + 断点;叙述不抢主视觉。
5. 无外链字体/新依赖;`view output` 可离线打开。
## 9. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:文档面、ViewAnnot、CSS L-leader、与 debug 分工 |
| 2026-10-15 | bind = post-stmt;交叉链 view-execution-trace |