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>
146 lines
6.6 KiB
Markdown
146 lines
6.6 KiB
Markdown
# 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 间距加宽 |
|