Files
marqdo/doc/design/view-prose-annot-gaps.md
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

146 lines
6.6 KiB
Markdown
Raw Permalink 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:叙述面标注缺口(prose annot gaps)
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [view-frame-selection.md](view-frame-selection.md) · [view-execution-trace.md](view-execution-trace.md) |
> **定位**:对既有文档面设计的**缺口专章**——写清用户可见的四类问题、根因(文件:行)与验收口径。不改写 ADR;不发明作者侧标注 DSL。
---
## 1. 为何「改了却几乎没变化」
| 原因 | 说明 |
|------|------|
| 错二进制 | PATH 上的 `marqdo` 可能仍是旧版(如 1.3.0);改动在源码 / `./target/debug/marqdo`。验收必须用 `cargo build && ./target/debug/marqdo view …` |
| Chip 被溢出藏掉 | 同 band 堆多帧 return/print/who;`MAX_VISIBLE_ANNOTS=4` 把当前帧的 `who` 打成 `annot-chip-overflow`(`display:none`);帧切换不重算溢出 |
| L-leader 几何错位 | `initAnnotLeaders` 里 `y0=0` 只在 `.annot-band` 顶画短折,**连不到**上方 underline;窄屏或 chip>4 时整段关掉 leaders |
| 旧静态快照 | gh-pages / 旧 `view output` 不会自动刷新 |
---
## 2. 目标视觉语法(既有,不新造)
锚定 [view-document-annotations.md](view-document-annotations.md) §3:
```
文本段…… `变量` …… **语句** …… *返回*
━━━━━
│
└──→ 结果标注 chip
```
- underline:`mark.mq-anchor.mq-{decl|code|return}`
- band:段落下方 `.annot-band` → leaders + chips
- L-leader:CSS `border-left` + `border-bottom`(禁止 SVG)
- 公式/代码:[view-static-interactive.md](view-static-interactive.md) G3 **一层主视觉**;卡下不叠 Bind dump
- 帧:[view-frame-selection.md](view-frame-selection.md) **源码常显、只滤 chip**;默认末帧
---
## 3. 管线
```mermaid
flowchart LR
CLI["marqdo view / view output"] --> build["build_file_view"]
build --> cap["run_file_capture"]
cap --> annot["build_view_annots"]
annot --> doc["document::render_module_document"]
doc --> page["html.rs page_file"]
page --> js["initAnnotLeaders + initCallPickers"]
```
| 步骤 | 位置 |
|------|------|
| CLI / 导出 | `src/main.rs` · `src/view/mod.rs` · `src/view/output.rs` |
| Capture + Call 事件 | `src/interp.rs` |
| Annot 组装 | `src/view/annot.rs` `build_view_annots` |
| 文档面 HTML | `src/view/document.rs` |
| 卡片 chrome | `src/view/render.rs` `render_*_assign_card` |
| CSS / leader JS | `src/view/html.rs` |
---
## 4. 四条用户问题 → 根因 → 验收
复现源:`public/00-welcome.mq.md` · `public/00-欢迎.mq.md`
对照金样:`tests/view/document-annot-demo.mq.md` · `tests/markup-v03/inc-prose.mq.md`
### P1 — 叙述与代码同段时信息不显示
| | |
|---|---|
| 现象 | underline 在,chip / 连线弱或无 |
| 根因 | `html.rs` `initAnnotLeaders`:`y0=0` 相对 band;`document.rs` `MAX_VISIBLE_ANNOTS` 把当前帧 chip 溢出;PATH 旧 CLI |
| 目标 | 同 `inc-prose`:underline + L-leader(从锚点底到 chip)+ 可见 chip |
| 验收 | `./target/debug/marqdo view public/00-welcome.mq.md`:主文 `**greet…**` 与 `## greet` 体内均有可见 chip 与接到 underline 的 leader(宽屏) |
### P2 — 函数内变量不显示
| | |
|---|---|
| 现象 | `` `who` `` 有浅蓝 underline,无值 chip |
| 根因 | bind chip 存在但带 `annot-chip-overflow`;`applyCallFrame` 只 `hidden` 非选中帧,不解除当前帧 overflow |
| 目标 | 选中调用帧时常显 `who` · `print` · `return` 各一枚 |
| 验收 | 切换「调用」下拉,三枚 chip 随帧变且默认可见(无需点 +N) |
### P3 — ` ```text ` 渲染不一致
| | |
|---|---|
| 现象 | 变成内联 `text marqdo ext add…`,无卡片 |
| 根因 | Comment 围栏若进 `flush_para` → `join(" ")` → pulldown 当 inline code;应走 `render_narrative_fence` |
| 目标 | 与 bound python 同 `.code-card` chrome(badge + `pre.code-body`),**无** Run/foot |
| 验收 | welcome install 段:`data-lang="text"` + 两行 `marqdo ext add`;无 `<code>text marqdo` |
### P4 — 函数引用 / 代码卡未渲染
| | |
|---|---|
| 现象 | `**greet who=…**` 无结果;或 `hi` python 只见头/Run、不见源码 |
| 根因 | 同行多 Call 未与 BoldCode zip;或 Run 挤在 head;静态假 Run;错看 Debug 路径 |
| 目标 | 主文两 greet 各有 call chip(stdout 摘要);`hi` = `render_code_assign_card` head→body→foot;静态藏 Run |
| 验收 | 两枚 greet mark 均有非空 `data-annot-id`;`code-body` 含 `hello-from-python`;`MARQDO_VIEW_LIVE=false` 无 Run 按钮 |
### call_id 语义(写死)
| 位置 | call_id |
|------|---------|
| 主文 `**greet…**` 的 call chip | 入口帧(`# main` 的 call);结果为 stdout/返回摘要 |
| `## greet` 体内 print / who / return | callee 的 CallFrame id;跟函数标题旁 picker |
---
## 5. 修复约定(实现红线)
1. **帧感知密度**:band 内按选中 `call_id` 计可见 chip;默认末帧;同帧最多 4 枚常显;溢出只藏非当前帧或多余 kind。切换后客户端重算 overflow + `layoutAll()`。
2. **Leader 容器**:提升到 `.doc-block`(prose + band);`y0` = 锚点底相对 block;按锚点 x 排序再画线。
3. **卡片**:只复用 Browse `render_*_assign_card` / `render_narrative_fence` + `html.rs` `.code-*` / `.formula-card`;本波不改 Debug AST 路径(除非回归红)。
4. **静态 Run**:`MARQDO_VIEW_LIVE=false` 时隐藏 Run,不留禁用假按钮(对齐 view-static-interactive D5)。
5. **非目标**:不做 debug 断点;不发明作者标注 DSL;不用 SVG leader;不单独发版/推 gh-pages(除非另嘱)。
---
## 6. 验收命令
```bash
cargo build -q
./target/debug/marqdo version # 须为当前工作树版本
./target/debug/marqdo view public/00-welcome.mq.md --no-open
./target/debug/marqdo view tests/view/document-annot-demo.mq.md --no-open
cargo test -q --lib view::
```
---
## 7. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:四问题、错二进制/溢出/leader 根因、帧感知密度与 leader 几何约定 |
| 2026-10-15 | L-leader 拥挤/消失:同跨度多帧 chip **共用 annot id**;可见 chip 按锚点 x 重排;leader 挂 doc-block |
| 2026-10-15 | L-leader 黑线碎段:JS `border*: "1.5px solid"` 无色覆盖 class → 改为 kind 色写入 shorthand;chip SSR/DOM 按锚点 L→R |
| 2026-10-15 | L-leader 改为 SVG:描述底边中点 → 轨道 → 短竖线 → 值 chip 顶边中点;chip 间距加宽 |