Files
marqdo/doc/design/view-reader-botanical.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

65 lines
3.9 KiB
Markdown
Executable File

# View botanical reader
Implemented 2026-11-07 for the shared `marqdo view` and `marqdo view output` shell.
The default is warm paper, serif document text, olive runtime notes, gold accents,
and generated transparent blossom/feather ornaments. The M/book logo is embedded
SVG. Navigation and the floating toolbar are code-native SVG icons and CSS.
`src/view/reader.css` is the final theme layer after notebook component styles;
`src/view/reader.js` owns reader navigation, dialogs and annotation geometry.
Notebook APIs and controls remain available through More → advanced tools.
Welcome files get a larger introduction; ordinary files retain compact titles.
## Runtime notes
Annotations keep their existing owner band, stable IDs, source anchor, call frame
and loop iteration data. Chips serialize source line and byte spans so another
call/iteration frame can find the same source mark without guessing by kind.
On viewports wider than 1000px with 180px available on each side, notes use both
page margins, varying horizontal reach and vertical offset with collision
avoidance. Dense bands that would drift more than 170px retain inline notes.
Compact screens, printing, and expanded overflow bands use ordinary document
flow. A shared SVG overlay draws continuously curved connections from the actual
mark's source-facing lower edge to the annotation title. The default is a full
S-curve with restrained gold/olive gradient; candidate sweeps are checked against
visible source text and already drawn connections. Tight prose uses two joined
curves below the text baseline and through the free margin, with no straight rail.
Notes sit closer to the document with varying horizontal/vertical offsets, rather
than stretching every connector across the entire page. Wrapped source marks use
their actual line fragments. Hover/focus highlights the exact source and connector.
Unresolved source anchors retain inline results instead of inventing a connection.
Clicking a note shows its full captured detail. No explanatory prose or runtime
values are invented.
Layout updates after window/font/structure resize, frame selection and live DOM
replacement. Static HTML includes the same code and embedded assets. All KaTeX
scripts, CSS and fonts are bundled for offline math. Optional syntax highlighting
retains the previous CDN progressive enhancement; code remains readable offline.
`api/session/run_document` now returns prose HTML, bindings and trace JSON from
its own capture. The reader applies that capture without rerunning the program.
Page tokens prevent a changed source from receiving mismatched annotations.
## Navigation
Document returns to prose. Functions/Variables move the real existing panels into
a modal and restore them on close, preserving their existing event handlers.
Memory shows the captured execution report, labeled as a snapshot on exports.
Run navigates to the output section. Search finds document, function and file text.
The floating toolbar labels its icons 刷新 / 设置 / 运行 / 清理 / 更多.
The bottom play button invokes actual live execution; static pages explain how to
start a live view. Static clear hides captured output locally; reload restores it.
Settings control light/dark theme, text size and annotation visibility. More keeps
source, advanced execution controls, file navigation and print within reach.
## Validation
Run `cargo test --offline --lib view::` and `cargo test --offline --test gold view_`.
The browser regression is `tests/view/reader.browser.cjs <URL>`; it accepts
`MARQDO_PLAYWRIGHT_MODULE`, `MARQDO_CHROMIUM`, and optional
`MARQDO_SCREENSHOT_DIR`. It blocks HTTPS resources to exercise offline reading,
checks seven viewport widths, note bounds/collisions, source/label curve endpoints, visible curvature and non-crossing paths,
shared-source frame binding, stable redraw, real panel restoration,
search, frame selection, note inspection and live/static run behavior.