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

6.6 KiB
Raw Blame History

View:叙述面标注缺口(prose annot gaps)

状态 Active
日期 2026-10-15
相关 view-document-annotations.md · view-static-interactive.md · view-frame-selection.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 §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 G3 一层主视觉;卡下不叠 Bind dump
  • 帧:view-frame-selection.md 源码常显、只滤 chip;默认末帧

3. 管线

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. 验收命令

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 间距加宽