diff --git a/doc/design/view-debug.md b/doc/design/view-debug.md index d32a402..cfd2304 100644 --- a/doc/design/view-debug.md +++ b/doc/design/view-debug.md @@ -4,14 +4,14 @@ |---|---| | 状态 | **v1(独立 debug 页)** | | 日期 | 2026-08-05 | -| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) | +| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [view-document-annotations.md](view-document-annotations.md) · [pipeline-debug.md](pipeline-debug.md) | ## 分工 | 命令 | 角色 | |------|------| -| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** | -| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** | +| `marqdo view` | 文档浏览器:**叙述保真文档面** Structure + Execution + Source;函数大纲与搜索;跑后引出标注;**无断点**(见 [view-document-annotations.md](view-document-annotations.md)) | +| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;AST Structure + BP;**仅 live** | 静态 `gh-pages` / `view output` **不能**真断点。 diff --git a/doc/design/view-document-annotations.md b/doc/design/view-document-annotations.md new file mode 100644 index 0000000..de57fee --- /dev/null +++ b/doc/design/view-document-annotations.md @@ -0,0 +1,113 @@ +# 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) · [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 | diff --git a/doc/design/view-execution-trace.md b/doc/design/view-execution-trace.md new file mode 100644 index 0000000..cd07304 --- /dev/null +++ b/doc/design/view-execution-trace.md @@ -0,0 +1,103 @@ +# View:执行轨迹与文档面保真 + +| | | +|---|---| +| 状态 | **Active** | +| 日期 | 2026-10-15 | +| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [view.md](view.md) · [view-markup-surface.md](view-markup-surface.md) | + +--- + +## 1. 目标 + +`marqdo view` Browse Structure 必须同时做到: + +1. **标记面**:变量名 / 可执行语句 / 返回值按表面渲染(无源码定界符字面量)。 +2. **结构块**:GFM 表、循环(`-`)、分支(`1.`)有正确 HTML 与缩进。 +3. **语句后值**:赋值行标注该语句执行后的值,不用入口终态回填。 +4. **执行臂**:高亮实际走的分支臂。 +5. **多调用帧**:同函数多次调用可用下拉切换经历。 +6. **AI 可读**:与 HTML 同源的 `ViewExecutionReport` JSON。 + +Debug 仍用 AST 卡片 + 断点;不做文档 callout。 + +## 2. 标记面 + +| 源标记 | 显示(无定界符) | class | +|--------|------------------|-------| +| `` `名` `` / `` `名`=默认 `` | `名`(默认次要后缀) | `mq-anchor mq-decl` | +| `**…**`(可执行) | 内层文本 | `mq-anchor mq-code` | +| `*…*`(返回) | 内层文本 | `mq-anchor mq-return` | + +`data-byte-start/end` 仍为源码字节偏移(供 CSS L-leader)。软强调不进 anchor。 + +## 3. 结构块 + +| 块 | 呈现 | +|----|------| +| GFM 表 | `