obsidian-plugin/jacobinwwey_obsidian-NotEMD
1
0
Fork 0
mirror of https://github.com/jacobinwwey/obsidian-NotEMD.git synced 2026-07-22 05:48:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

test(slidev-export): cover component fence image boundaries

Browse source
This commit is contained in:
Jacobinwwey 2026-06-20 19:02:23 -05:00
parent 117133a649
commit a2cbf4e37c
8 changed files with 287 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
docs/SLIDEV_SOLUTION.md
View file

@ -172,6 +172,8 @@ The current render-feedback loop is now:
Mermaid handling has a stricter content-preservation rule than tables, code, or prose. A user-provided Mermaid fence remains one diagram. When the preserved diagram is low-zoom, low-font, or too tight to prove presentation quality automatically, the workflow records `fits`, `source-preserved-fit-review`, or `manual-review` evidence instead of rewriting the source graph into several diagrams.
Operationally this is a hard invariant, not a preference: automated export must not split one source Mermaid fence, rewrite its body, change its fence metadata, or reorder it. The automatic path may only fit the rendered diagram, move non-Mermaid neighboring content, or expose review evidence; changing Mermaid content requires an explicit human source edit.
This is now enforced before the prepared deck is written, not only after export verification: both one-shot LLM deck generation and outline-continuation LLM generation compare every source Mermaid fence against the candidate deck and fall back to deterministic source-preserving preparation if the candidate changes count, order, fence metadata, or body text.
The verifier now enforces that rule with `mermaidSourcePreservation`: each exported Mermaid fence is compared to the corresponding source fence. A block-count-only match is not enough.
@ -182,7 +184,7 @@ That rule is also covered by a unit regression now: even if a Mermaid slide is m
Mixed component/prose slides now follow the same readability-first shape without changing the Mermaid rule: when a custom layout contains one complete component/Vue surface and one Markdown prose/list content block, the patcher separates them into two presentation surfaces before whole-slide zoom is considered. The next rendered audit pass can then wrap only the component block in a measured local `<Transform>`, while the prose page remains readable. If the mixed component slide contains a fence, table, image, directive, existing Transform, or unstable component/prose/component ordering, the patcher blocks the zoom/manual-review path instead of silently shrinking prose.
Stage 13 moves that unsupported-boundary rule into the production fixture runner. `unsupported-component-table-boundary-stress` is an expected-failure fixture: when selected explicitly, the verifier should end with `ok = false`, while native standalone export, browser loading, generated-artifact visibility, the failure-review fingerprint, and Mermaid source preservation all still pass. The default `verify:slidev-layout-fixtures` run remains success-only; use `--fixture unsupported-component-table-boundary-stress` or `--include-expected-failures` to audit fail-transparent boundaries.
Stage 13/14 move that unsupported-boundary rule into the production fixture runner. `unsupported-component-table-boundary-stress`, `unsupported-component-fence-boundary-stress`, and `unsupported-component-image-boundary-stress` are expected-failure fixtures: when selected explicitly, the verifier should end with `ok = false`, while native standalone export, browser loading, generated-artifact visibility, the failure-review fingerprint, and Mermaid source preservation all still pass. The image fixture also proves that its local SVG asset survives in both the prepared deck and final standalone export. The default `verify:slidev-layout-fixtures` run remains success-only; use a concrete `--fixture ...` or `--include-expected-failures` to audit fail-transparent boundaries.
The clean-room reference from `ref/infinite-canvas` is still the world-rect and viewport-transform idea: nodes have `{ position, width, height }`, the viewport has `{ x, y, k }`, and visible bounds are derived from transform math. For NoteMD export, that becomes an export-layout camera for a fixed Slidev safe rectangle, not an interactive infinite canvas. Because the reference project is AGPL-3.0 and NoteMD is MIT, implementation must be independent.
@ -224,10 +226,14 @@ Current landed state:
27. the Stage 13 expected-failure fixture archive is `/home/jacob/slidev-export-review/2026-06-20-stage13-unsupported-component-boundary-fixture/`: `unsupported-component-table-boundary-stress` is correct only when verifier `ok = false`, `hardOverflowCount > 0`, and the blocked reason says mixed component plus primary Markdown content cannot be repaired with whole-slide `zoom`, while its single source Mermaid fence remains byte-stable in the exported deck.
28. the Stage 13 default success fixture archive is `/home/jacob/slidev-export-review/2026-06-20-stage13-success-fixtures/`: all 9 converging production fixtures pass, and expected-failure fixtures are not included in the default green path.
29. the Stage 13 real `architecture.zh-CN.md` strict standalone output is archived at `/home/jacob/slidev-export-review/2026-06-20-stage13-real/`; `architecture.zh-CN.stage13.slidev.md` is the reviewable exported deck and `architecture.zh-CN-slides/index-standalone.html` is the native standalone output. The report is `ok = true`, uses the local Slidev fork and 52 skill references, preserves all 3 Mermaid fences with `changedFenceIndexes = []`, and closes with `hardOverflowCount = 0` and `lowEffectiveFontCount = 0`.
30. the Stage 14 component/fence expected-failure fixture archive is `/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-fence-boundary-fixture/`: `unsupported-component-fence-boundary-stress` is correct only when verifier `ok = false`, the blocked reason says mixed component plus primary Markdown content cannot be repaired with whole-slide `zoom`, no whole-slide zoom is introduced, and its single source Mermaid fence remains byte-stable.
31. the Stage 14 component/image expected-failure fixture archive is `/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-image-boundary-fixture/`: `unsupported-component-image-boundary-stress` proves the same fail-transparent behavior and also verifies `assets/boundary-image.svg` in the prepared deck and final standalone export.
32. the Stage 14 default success fixture archive is `/home/jacob/slidev-export-review/2026-06-20-stage14-success-fixtures/`: all 9 converging production fixtures still pass, and the three expected-failure fixtures stay out of the default green path.
33. the Stage 14 real `architecture.zh-CN.md` strict standalone output is archived at `/home/jacob/slidev-export-review/2026-06-20-stage14-real/`; `architecture.zh-CN.stage14.slidev.md` is the reviewable exported deck and `architecture.zh-CN-slides/index-standalone.html` is the native standalone output. The report is `ok = true`, uses the local Slidev fork and 52 skill references, preserves all 3 Mermaid fences with `changedFenceIndexes = []`, and closes with `hardOverflowCount = 0` and `lowEffectiveFontCount = 0`.
Current gap:
1. richer custom/component-heavy Slidev layouts beyond the current supported structural set still fall back to conservative/manual-review behavior, especially when there is no stable owner, the content contains fences/images inside a component surface, the component/prose order is ambiguous, or a single non-Mermaid component surface cannot be structurally split or transformed within the font floor; component/table and component/directive boundaries now have explicit blocking coverage;
1. richer custom/component-heavy Slidev layouts beyond the current supported structural set still fall back to conservative/manual-review behavior, especially when there is no stable owner, the component/prose order is ambiguous, or a single non-Mermaid component surface cannot be structurally split or transformed within the font floor; component/table/directive/fence/image boundaries now have explicit blocking coverage;
2. standalone export now has a strict native gate and the real architecture fixture passes it, but correctness still depends on post-build sanity detection; server-script fallback remains a compatibility lane for future bad bundles, not evidence that native standalone passed;
3. full-deck Playwright verification is now more correct, but noticeably slower, so future work should improve patch convergence instead of weakening the audit back to representative sampling;
4. the Obsidian CLI can dispatch `notemd:export-slides`, but it does not expose an export-complete handshake, so host-command smoke is still weaker than the maintainer verifier.

10
docs/SLIDEV_SOLUTION.zh-CN.md
View file

@ -161,6 +161,8 @@ npm run verify:slidev-export
Mermaid 的规则比 table/code/prose 更严格：用户提供的一个 Mermaid fence 仍然是一张图。若保留源图后出现低 zoom、低字号或边距过紧，流程记录 `fits`、`source-preserved-fit-review` 或 `manual-review` 证据，而不是把原图静默拆成多张图。
工程上这条是硬约束，不是偏好：自动导出不得拆分一个源 Mermaid fence，不得重写图体，不得改 fence metadata，也不得重排 Mermaid fence。自动路径只能对渲染后的图做 fit，移动非 Mermaid 邻近内容，或暴露 review 证据；要改变 Mermaid 内容必须来自明确的人工源文档编辑。
这条规则现在不只靠导出后 verifier 兜底：一次性 LLM deck 生成和基于 outline 继续生成两个入口，都会在写 prepared deck 之前逐个比较源 Mermaid fence 与候选 deck fence。数量、顺序、fence metadata 或正文任一变化，都会拒绝该 LLM 候选并回退到保留源图的 deterministic deck。
verifier 现在用 `mermaidSourcePreservation` 强制这条规则：导出 deck 会逐个 Mermaid fence 与源 fence 对比。只有 block 数一致不够，任何内容变化、顺序变化或 fence metadata 变化都应失败。
@ -171,7 +173,7 @@ Mermaid/prose 混排页不能套用 Mermaid-only 页的低整页 zoom 策略，
混合 component/prose 页采用同一类“先保护正文可读性”的策略，但不触碰 Mermaid 规则：当自定义 layout 中只有一个完整 component/Vue surface 与一个 Markdown prose/list 主内容块时，patcher 会先把它们分成两个 presentation surfaces；下一轮 rendered audit 可以只对组件页的组件块套 measured local `<Transform>`，正文页不继承整页 `zoom`。如果组件混排里含 fence/table/image/directive/已有 Transform，或出现 component/prose/component 这类不稳定顺序，patcher 会 blocked/manual-review，而不是静默缩小正文。
Stage 13 把这类“不应自动修”的边界纳入生产 fixture runner：`unsupported-component-table-boundary-stress` 是 expected-failure fixture，显式运行时应让 verifier `ok = false`，但必须同时证明 native standalone、浏览器加载、Git 可见性、失败指纹和 Mermaid source-preservation 都成立。默认 `verify:slidev-layout-fixtures` 仍只跑可收敛 fixtures；需要审查失败边界时显式传 `--fixture unsupported-component-table-boundary-stress` 或 `--include-expected-failures`。
Stage 13/14 把这类“不应自动修”的边界纳入生产 fixture runner：`unsupported-component-table-boundary-stress`、`unsupported-component-fence-boundary-stress` 与 `unsupported-component-image-boundary-stress` 都是 expected-failure fixtures，显式运行时应让 verifier `ok = false`，但必须同时证明 native standalone、浏览器加载、Git 可见性、失败指纹和 Mermaid source-preservation 都成立。image fixture 还要求本地 SVG 资产在 prepared deck 与最终 standalone export 中都存在。默认 `verify:slidev-layout-fixtures` 仍只跑可收敛 fixtures；需要审查失败边界时显式传具体 `--fixture ...` 或 `--include-expected-failures`。
最新真实 strict run 的 Mermaid fit 计数为 `mermaidSlideCount = 3`、`mermaidFitReviewCount = 3`、`mermaidLowZoomCount = 2`、`mermaidManualReviewCount = 1`。这说明当前流程已经把低 zoom 风险显性化，但没有改写原 Mermaid 内容。
@ -204,10 +206,14 @@ Stage 13 把这类“不应自动修”的边界纳入生产 fixture runner：`u
14. Stage 13 expected-failure fixture 验收包位于 `/home/jacob/slidev-export-review/2026-06-20-stage13-unsupported-component-boundary-fixture/`：`unsupported-component-table-boundary-stress` 的正确结果是 verifier `ok = false`，`hardOverflowCount > 0`，blocked reason 指向 mixed component + primary Markdown 不能用整页 `zoom` 修，同时 1 个源 Mermaid fence 与导出 deck Mermaid fence byte-stable。
15. Stage 13 默认成功 fixture suite 归档到 `/home/jacob/slidev-export-review/2026-06-20-stage13-success-fixtures/`：9 个可收敛生产 fixtures 均通过，expected-failure fixture 不进入默认成功套件。
16. Stage 13 真实 `architecture.zh-CN.md` strict standalone 输出归档到 `/home/jacob/slidev-export-review/2026-06-20-stage13-real/`；其中 `architecture.zh-CN.stage13.slidev.md` 是可直接审查的输出 deck，`architecture.zh-CN-slides/index-standalone.html` 是 native standalone 输出。报告为 `ok = true`，使用本地 Slidev fork 与 52 个 skill references，3 个 Mermaid fence 均保持 `changedFenceIndexes = []`，`hardOverflowCount = 0`，`lowEffectiveFontCount = 0`。
17. Stage 14 component/fence expected-failure fixture 验收包位于 `/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-fence-boundary-fixture/`：`unsupported-component-fence-boundary-stress` 的正确结果是 verifier `ok = false`，blocked reason 指向 mixed component + primary Markdown 不能用整页 `zoom` 修，同时 source Mermaid fence 仍保持一个源 fence 对应一个导出 fence。
18. Stage 14 component/image expected-failure fixture 验收包位于 `/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-image-boundary-fixture/`：`unsupported-component-image-boundary-stress` 证明 image 混排同样 fail transparent，并额外证明 `assets/boundary-image.svg` 在 prepared deck 和最终 standalone export 中都存在。
19. Stage 14 默认成功 fixture suite 归档到 `/home/jacob/slidev-export-review/2026-06-20-stage14-success-fixtures/`：9 个可收敛生产 fixtures 继续全部通过，三个 expected-failure fixtures 不进入默认成功套件。
20. Stage 14 真实 `architecture.zh-CN.md` strict standalone 输出归档到 `/home/jacob/slidev-export-review/2026-06-20-stage14-real/`；其中 `architecture.zh-CN.stage14.slidev.md` 是可直接审查的输出 deck，`architecture.zh-CN-slides/index-standalone.html` 是 native standalone 输出。报告为 `ok = true`，使用本地 Slidev fork 与 52 个 skill references，3 个 Mermaid fence 均保持 `changedFenceIndexes = []`，`hardOverflowCount = 0`，`lowEffectiveFontCount = 0`。
当前仍存在的边界：
1. 更复杂的自定义 Vue layout 仍可能需要保守处理或人工复查，尤其是没有稳定 owner、无法安全分页、又不能在字体下限内缩放的单个 component surface。混入 table/directive 的 component surface 已经有阻断证据；混入 fence/image 或 component/prose/component 顺序不稳定的情况仍需要继续沉淀真实 fixture。
1. 更复杂的自定义 Vue layout 仍可能需要保守处理或人工复查，尤其是没有稳定 owner、无法安全分页、又不能在字体下限内缩放的单个 component surface。混入 table/directive/fence/image 的 component surface 已经有阻断证据；component/prose/component 顺序不稳定或多个 owner 竞争的情况仍需要继续沉淀真实 fixture。
2. Standalone 正确性依赖 post-build sanity detection；fallback 通过不能当作 native standalone 通过。
3. 全 deck Playwright 审计更正确但更慢，后续应优化收敛效率，而不是削弱审计范围。
4. Obsidian CLI 可以派发 `notemd:export-slides`，但缺少导出完成握手，所以宿主命令烟测弱于 verifier。

17
docs/brainstorms/2026-06-20-slidev-layout-quality-and-canvas-roadmap.md
View file

@ -3,7 +3,7 @@ date: 2026-06-20
last_updated: 2026-06-20
topic: slidev-layout-quality-and-canvas-roadmap
canonical: false
status: stage13-unsupported-component-boundary-fail-transparent
status: stage14-unsupported-component-fence-image-boundaries
---
# Slidev Layout Quality And Canvas Roadmap
@ -26,7 +26,7 @@ Current landed facts:
8. `SlideLayoutPlan` is injected into deterministic outline generation, one-shot deck generation, and outline-continuation generation.
9. The real `docs/architecture.zh-CN.md` strict standalone run is the recurring acceptance source for actual export behavior.
The current slice adds Stage 13 fail-transparent unsupported component/table boundary coverage on top of Stage 12 mixed component/prose convergence, Stage 11 Mermaid source-boundary hardening, the Stage 10 bounded Vue component tree convergence fixture, Mermaid measured-fit ownership, font-safe slot/code convergence, explicit CSS asset dependency graph copying, and Stage 9 custom single-surface convergence:
The current slice adds Stage 14 fail-transparent unsupported component/fence and component/image boundary coverage on top of Stage 13 unsupported component/table expected-failure coverage, Stage 12 mixed component/prose convergence, Stage 11 Mermaid source-boundary hardening, the Stage 10 bounded Vue component tree convergence fixture, Mermaid measured-fit ownership, font-safe slot/code convergence, explicit CSS asset dependency graph copying, and Stage 9 custom single-surface convergence:
1. Markdown images, HTML media/link/srcset attributes, and Slidev frontmatter local file keys are copied into the prepared deck workspace.
2. Local CSS files explicitly referenced by the deck are parsed for local `url(...)` dependencies and local `@import` stylesheet chains.
@ -46,7 +46,8 @@ The current slice adds Stage 13 fail-transparent unsupported component/table bou
16. Bounded component-only Vue tree surfaces with multiline component openers, multiline props, nested components, and named template slots can now receive the same measured local `<Transform>` path. Mixed Markdown prose/table/fence/directive content is intentionally rejected from this path.
17. Mermaid preservation tests now cover inline fence metadata: mixed Mermaid/prose repair may move only non-Mermaid content, and source preparation rejects LLM deck candidates that change only a Mermaid fence opener option.
18. Clear-boundary mixed component/prose slides can now be separated into component and prose presentation surfaces before whole-slide zoom is considered. The component page can then receive a measured local `<Transform>` while the prose page stays readable. Mixed component surfaces with fences, tables, images, directives, existing Transform wrappers, or component/prose/component ordering fail transparent instead of silently shrinking prose.
19. Unsupported component/table production fixtures can now be represented as expected failures. These fixtures pass only when the verifier fails for the intended layout reason while native standalone export, browser load, generated-artifact visibility, failure fingerprints, and Mermaid source preservation remain intact. They are excluded from the default success fixture suite unless explicitly selected or `--include-expected-failures` is passed.
19. Unsupported component/table/fence/image production fixtures can now be represented as expected failures. These fixtures pass only when the verifier fails for the intended layout reason while native standalone export, browser load, generated-artifact visibility, failure fingerprints, and Mermaid source preservation remain intact. They are excluded from the default success fixture suite unless explicitly selected or `--include-expected-failures` is passed.
20. The component/image expected-failure path also checks that explicit local image assets are still copied into both the prepared deck and final standalone output, so fail-transparent layout handling does not hide asset regressions.
Closeout evidence:
@ -69,6 +70,10 @@ Closeout evidence:
17. Stage 13 expected-failure archive: `/home/jacob/slidev-export-review/2026-06-20-stage13-unsupported-component-boundary-fixture/`. `unsupported-component-table-boundary-stress` deliberately ends with verifier `ok = false`, `hardOverflowCount > 0`, and a blocked reason for mixed component plus primary Markdown content. That is the correct result: the workflow refuses whole-slide zoom for an unsafe component/table boundary while keeping the review fingerprint and a source Mermaid fence byte-stable.
18. Stage 13 default success fixture archive: `/home/jacob/slidev-export-review/2026-06-20-stage13-success-fixtures/`. The default suite still includes only converging fixtures and all 9 pass; expected-failure fixtures are explicit opt-in coverage.
19. Real Stage 13 `architecture.zh-CN.md` strict native standalone archive: `/home/jacob/slidev-export-review/2026-06-20-stage13-real/`. The report is `ok = true`, uses `/home/jacob/slidev/packages/slidev/bin/slidev.mjs`, loads `/home/jacob/slidev/skills/slidev` with 52 references, outputs native standalone HTML, preserves 3/3 Mermaid fences with `changedFenceIndexes = []`, and closes with `slideCount = 27`, `hardOverflowCount = 0`, `lowEffectiveFontCount = 0`, `mermaidFitReviewCount = 3`, `mermaidLowZoomCount = 2`, and `mermaidManualReviewCount = 1`. The reviewable deck is `architecture.zh-CN.stage13.slidev.md`.
20. Stage 14 component/fence expected-failure archive: `/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-fence-boundary-fixture/`. `unsupported-component-fence-boundary-stress` ends with verifier `ok = false`, native standalone and browser checks passing, the intended mixed component/primary Markdown blocked reason, no whole-slide zoom, and one source Mermaid fence preserved byte-stable.
21. Stage 14 component/image expected-failure archive: `/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-image-boundary-fixture/`. `unsupported-component-image-boundary-stress` has the same fail-transparent layout result and also proves `assets/boundary-image.svg` exists in both the prepared deck and final standalone export.
22. Stage 14 default success fixture archive: `/home/jacob/slidev-export-review/2026-06-20-stage14-success-fixtures/`. The default suite still includes only the 9 converging production fixtures; all pass and the three expected-failure fixtures remain opt-in.
23. Real Stage 14 `architecture.zh-CN.md` strict native standalone archive: `/home/jacob/slidev-export-review/2026-06-20-stage14-real/`. The report is `ok = true`, uses `/home/jacob/slidev/packages/slidev/bin/slidev.mjs`, loads `/home/jacob/slidev/skills/slidev` with 52 references, outputs native standalone HTML, preserves 3/3 Mermaid fences with `changedFenceIndexes = []`, and closes with `slideCount = 27`, `hardOverflowCount = 0`, `lowEffectiveFontCount = 0`, `mermaidFitReviewCount = 3`, `mermaidLowZoomCount = 2`, and `mermaidManualReviewCount = 1`. The reviewable deck is `architecture.zh-CN.stage14.slidev.md`.
## Mermaid Boundary
@ -94,7 +99,7 @@ Mermaid-only slides may use measured low zoom to keep the full preserved diagram
| Mixed Mermaid/prose must not use low whole-slide zoom | Only non-Mermaid content may move; Mermaid fence opener, metadata, body, and closer remain byte-stable | Improve outer layout and prose movement only |
| Local assets must not disappear in standalone output | Markdown, HTML, frontmatter, CSS `url(...)`, CSS `@import`, and local media dependencies are copied explicitly; rejected local CSS references are sanitized in copied CSS | Extend only through explicit dependency parsing, not whole-directory copying |
| Remote fonts must not be required for verification | Prepared decks default to `fonts.provider: none` | Use explicit local assets for branded fonts |
| Custom component surfaces without stable slot owners need convergence evidence | Bounded raw HTML/component single-surface slides, bounded component-only Vue tree surfaces, and clear-boundary mixed component/prose slides can now converge without whole-slide zoom; component/table now has an expected-failure production fixture, and component/directive blocking is covered by unit tests | Keep component surfaces with fences/images or ambiguous owner ordering conservative until a fixture proves a safe boundary |
| Custom component surfaces without stable slot owners need convergence evidence | Bounded raw HTML/component single-surface slides, bounded component-only Vue tree surfaces, and clear-boundary mixed component/prose slides can now converge without whole-slide zoom; component/table/fence/image now have expected-failure production fixtures, and component/directive blocking is covered by unit tests | Keep ambiguous owner ordering conservative until a fixture proves a safe boundary |
## Architecture Direction
@ -131,11 +136,13 @@ Required verification before closing a slice:
The next useful slices are:
1. Add more real failure fixtures for unsupported layouts without stable owners, component surfaces that contain fence/image syntax, and custom layouts that need pagination without an explicit surface boundary; Stage 13 covers component/table fail-transparent behavior and unit-tests component/directive blocking, not arbitrary component trees.
1. Add more real failure fixtures for unsupported layouts without stable owners, ambiguous component/prose/component ordering, and custom layouts that need pagination without an explicit surface boundary; Stage 14 covers component/table/fence/image fail-transparent behavior and unit-tests component/directive blocking, not arbitrary component trees.
2. Keep Mermaid source-preserved fit review as a first-class report surface; automatic repair may move only non-Mermaid content and must not split the diagram, rewrite the body, alter opener metadata, or reorder fences.
3. Extend parser-light code splitting only where it preserves semantic blocks better than line budgets.
4. Consider an upstream Slidev skill PR only for general guardrails: complete references, source-preserved Mermaid fit review, browser-check expectations, standalone/fallback distinction, and no automatic user-diagram splitting.
Any later canvas or viewport strategy must work around Mermaid source preservation: unless a human edits the source file, one source Mermaid fence maps to one exported Mermaid fence with unchanged opener, metadata, body, closer, and order.
Avoid these directions:
1. Copying `ref/infinite-canvas` implementation code.

22
docs/brainstorms/2026-06-20-slidev-layout-quality-and-canvas-roadmap.zh-CN.md
View file

@ -3,7 +3,7 @@ date: 2026-06-20
last_updated: 2026-06-20
topic: slidev-layout-quality-and-canvas-roadmap
canonical: true
status: stage13-unsupported-component-boundary-fail-transparent
status: stage14-unsupported-component-fence-image-boundaries
---
# Slidev 布局质量与画布规划路线
@ -26,7 +26,7 @@ status: stage13-unsupported-component-boundary-fail-transparent
1. 分支：`main`
2. 远端：`origin/main`
3. 本批次实现内容：rendered quality gate + clean-room `SlideLayoutPlan` 第一切片 + Mermaid 源图保持 fit 审计 + JS/TS/Python/Rust tokenizer + Mermaid 不拆图回归契约 + Stage 5 full-deck/export fixture、文本 glyph rect 测量、slot Transform 去整页 zoom 叠加、mixed Mermaid/prose 非图内容移动、相对图片资产镜像、local Slidev fork standalone loader 边界修复、Stage 6 frontmatter/cross-dir 资产镜像、CSS `url(...)` 与本地 `@import` 依赖图、HTML export 后资产同步、本地媒体 fixture 与离线字体 provider、Stage 7 font-safe slot/code convergence、Stage 8 Mermaid measured-fit ownership、Stage 9 custom single-surface local Transform fixture、Stage 10 bounded Vue component tree surface fixture、Stage 11 Mermaid fence metadata 保持回归约束、Stage 12 mixed component/prose 清晰边界分离与标题+组件局部 Transform、Stage 13 unsupported component/table/directive boundary fail-transparent fixture
3. 本批次实现内容：rendered quality gate + clean-room `SlideLayoutPlan` 第一切片 + Mermaid 源图保持 fit 审计 + JS/TS/Python/Rust tokenizer + Mermaid 不拆图回归契约 + Stage 5 full-deck/export fixture、文本 glyph rect 测量、slot Transform 去整页 zoom 叠加、mixed Mermaid/prose 非图内容移动、相对图片资产镜像、local Slidev fork standalone loader 边界修复、Stage 6 frontmatter/cross-dir 资产镜像、CSS `url(...)` 与本地 `@import` 依赖图、HTML export 后资产同步、本地媒体 fixture 与离线字体 provider、Stage 7 font-safe slot/code convergence、Stage 8 Mermaid measured-fit ownership、Stage 9 custom single-surface local Transform fixture、Stage 10 bounded Vue component tree surface fixture、Stage 11 Mermaid fence metadata 保持回归约束、Stage 12 mixed component/prose 清晰边界分离与标题+组件局部 Transform、Stage 13 unsupported component/table/directive boundary fail-transparent fixture、Stage 14 unsupported component/fence/image expected-failure fixtures
4. 真实源文件：`docs/architecture.zh-CN.md`
5. 本批次真实导出证据包：`/home/jacob/slidev-export-review/2026-06-20-quality/`
6. 本批次最终 source-preserved-fit 输出归档：`/home/jacob/slidev-export-review/2026-06-20-source-preserved-fit-final/`
@ -50,6 +50,10 @@ status: stage13-unsupported-component-boundary-fail-transparent
24. Stage 13 unsupported component boundary expected-failure fixture 验收包：`/home/jacob/slidev-export-review/2026-06-20-stage13-unsupported-component-boundary-fixture/`
25. Stage 13 正常成功 fixture suite 验收包：`/home/jacob/slidev-export-review/2026-06-20-stage13-success-fixtures/`
26. Stage 13 真实 `architecture.zh-CN.md` strict native standalone 验收包：`/home/jacob/slidev-export-review/2026-06-20-stage13-real/`
27. Stage 14 component/fence expected-failure fixture 验收包：`/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-fence-boundary-fixture/`
28. Stage 14 component/image expected-failure fixture 验收包：`/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-image-boundary-fixture/`
29. Stage 14 默认成功 fixture suite 验收包：`/home/jacob/slidev-export-review/2026-06-20-stage14-success-fixtures/`
30. Stage 14 真实 `architecture.zh-CN.md` strict native standalone 验收包：`/home/jacob/slidev-export-review/2026-06-20-stage14-real/`
当前已落地事实：
@ -97,11 +101,15 @@ status: stage13-unsupported-component-boundary-fail-transparent
42. Stage 13 expected-failure fixture 特意包含一个 Mermaid fence，证明失败路径也必须遵守源图保持：report 为 `mermaidSourcePreservation.passed = true`，`sourceFenceCount = 1`，`deckFenceCount = 1`，`changedFenceIndexes = []`。这不是把 Mermaid 拆成多图的替代方案，而是证明不安全 component/table 边界会显性失败，同时不改 Mermaid 图体、metadata 或 fence 数量。
43. Stage 13 正常成功 fixture suite 默认仍只跑可收敛 fixtures，归档到 `/home/jacob/slidev-export-review/2026-06-20-stage13-success-fixtures/`：9 个生产 fixtures 全部通过，`unsupported-component-table-boundary-stress` 不进入默认成功套件，避免把预期失败混入普通绿色路径。
44. Stage 13 真实 `architecture.zh-CN.md` strict native standalone rerun 已通过并归档到 `/home/jacob/slidev-export-review/2026-06-20-stage13-real/`：`ok = true`，继续使用 `/home/jacob/slidev/packages/slidev/bin/slidev.mjs` 与 `/home/jacob/slidev/skills/slidev` 的 52 个 references，`actualMode = "standalone"`，`requiresLocalServer = false`，`standaloneGate.passed = true`，`slideCount = 27`，`hardOverflowCount = 0`，`lowEffectiveFontCount = 0`，`mermaidSourcePreservation.passed = true`，3 个 Mermaid fence 均保持 `changedFenceIndexes = []`，`mermaidFitReviewCount = 3`，`mermaidLowZoomCount = 2`，`mermaidManualReviewCount = 1`，最终 deck 仍只有 rendered audit 推导的 `zoomLines = ["0.285", "0.384"]`；可审查 deck 为 `architecture.zh-CN.stage13.slidev.md`。
45. Stage 14 把 unsupported component/fence 与 component/image 边界提升为 production expected-failure fixtures：`unsupported-component-fence-boundary-stress` 与 `unsupported-component-image-boundary-stress` 显式运行时都必须让 verifier `ok = false`，但 standalone gate、浏览器加载、失败指纹、Git 可见性与 Mermaid source-preservation 均通过；最终 deck 不允许引入整页 `zoom`。
46. Stage 14 image expected-failure 还额外验证失败路径里的本地图片资产不会丢失：`assets/boundary-image.svg` 同时存在于 prepared deck 与最终 standalone export。这个 slice 没有扩大自动修复范围，只把“component surface 混入 fence/image 必须 fail transparent”变成真实导出契约。
47. Stage 14 默认成功 fixture suite 归档到 `/home/jacob/slidev-export-review/2026-06-20-stage14-success-fixtures/`：9 个可收敛生产 fixtures 继续全部通过，三个 expected-failure fixtures 均不进入默认成功路径。
48. Stage 14 真实 `architecture.zh-CN.md` strict native standalone rerun 已通过并归档到 `/home/jacob/slidev-export-review/2026-06-20-stage14-real/`：`ok = true`，继续使用本地 Slidev fork 与 `/home/jacob/slidev/skills/slidev` 的 52 个 references，`actualMode = "standalone"`，`requiresLocalServer = false`，`standaloneGate.passed = true`，`slideCount = 27`，`hardOverflowCount = 0`，`lowEffectiveFontCount = 0`，`mermaidSourcePreservation.passed = true`，3 个 Mermaid fence 均保持 `changedFenceIndexes = []`；可审查 deck 为 `architecture.zh-CN.stage14.slidev.md`，native standalone 输出为 `architecture.zh-CN-slides/index-standalone.html`。
当前未完成事实：
1. semantic split 仍只覆盖当前已有 table/code/text 支持集；Mermaid 源图保持后，过密原图只能通过布局/zoom/Transform 或人工复核处理，不能把一个源 Mermaid fence 自动拆成多个图，也不能把 fence metadata 当作可由 LLM 重写的格式化细节；
2. effective font 现在会把文本节点到 slide root 之间的局部 CSS `transform` / `scale` / `zoom` 乘入逐样本字号；full-deck slot fixture 已覆盖复杂 Vue/slot、嵌套 slot、component-heavy Transform、unsafe competing slot 自动分页、bounded raw HTML/component single-surface local Transform、bounded component-only Vue tree surface，以及清晰边界 mixed component/prose 的真实收敛链路；混入 table/directive 的 component surface 已有 fail-transparent fixture 或单元测试覆盖，混入 fence/image、多个不稳定 surface owner 或不可安全分页的 custom layout 仍需继续加 fixture；
2. effective font 现在会把文本节点到 slide root 之间的局部 CSS `transform` / `scale` / `zoom` 乘入逐样本字号；full-deck slot fixture 已覆盖复杂 Vue/slot、嵌套 slot、component-heavy Transform、unsafe competing slot 自动分页、bounded raw HTML/component single-surface local Transform、bounded component-only Vue tree surface，以及清晰边界 mixed component/prose 的真实收敛链路；混入 table/directive/fence/image 的 component surface 已有 fail-transparent fixture 或单元测试覆盖，多个不稳定 surface owner 或不可安全分页的 custom layout 仍需继续加 fixture；
3. `SlideLayoutPlan` 是生成前预算，不替代 Playwright rendered audit；
4. 真实 `architecture.zh-CN.md` 仍需要每批次跑 strict standalone 验收，不能用单测替代；
5. 当前真实 deck 仍可能在 rendered audit 之后出现 `zoom` 小于 `0.72` 的 Mermaid-only 页面；在“不改原 Mermaid 图内容”的约束下，低 zoom 有时是保留源图的代价，但不能由 source preparation 的固定参数或 LLM 主观决定，也不能扩散到 prose/table/code。混合 Mermaid/prose 页只能先迁移非图内容，不能拆 Mermaid 原图，也不能把正文一起缩小。
@ -123,7 +131,7 @@ status: stage13-unsupported-component-boundary-fail-transparent
| standalone 验证不能依赖外网字体 | 未显式配置 `fonts:` 的 prepared deck 注入 `fonts.provider: none`；显式字体配置保持用户选择 | 已落地 | 后续若需要品牌字体，应走本地 `public/` 或明确的 support asset，而不是默认拉远程字体 |
| 完整支持 Slidev skill references | skill root 与 reference count 已进入 verifier | 已落地 | 可考虑上游 skill PR，但只放通用 guardrails |
| 参考无限画布优化图/表/画布可见范围 | 已新增 clean-room `SlideLayoutPlan`，按 world-rect / viewport-fit 思想做生成前预算 | 已落地第一切片 | 后续加强语义拆分算法，不复制 AGPL 代码 |
| custom component surface 无稳定 slot owner 时仍需收敛 | bounded raw HTML/component single-surface、bounded component-only Vue tree surface、以及清晰边界 mixed component/prose 现在可以收敛：mixed 场景先分离正文，再让组件页走 measured local `<Transform>`；已有 Transform 会阻止整页 zoom 叠加；混入 table/directive 的 component surface 已有 expected-failure 生产 fixture 或单元测试覆盖，证明会阻断整页 zoom 并保留复核材料；混入 fence/image 或 component/prose/component 的 surface 仍回到 fail-transparent 路径 | 已落地 Stage 13 切片 | 继续沉淀真实 unsupported layout；不要扩大到无法证明 owner surface 的任意组件树 |
| custom component surface 无稳定 slot owner 时仍需收敛 | bounded raw HTML/component single-surface、bounded component-only Vue tree surface、以及清晰边界 mixed component/prose 现在可以收敛：mixed 场景先分离正文，再让组件页走 measured local `<Transform>`；已有 Transform 会阻止整页 zoom 叠加；混入 table/directive/fence/image 的 component surface 已有 expected-failure 生产 fixture 或单元测试覆盖，证明会阻断整页 zoom 并保留复核材料；component/prose/component 或多 owner surface 仍回到 fail-transparent 路径 | 已落地 Stage 14 切片 | 继续沉淀真实 unsupported layout；不要扩大到无法证明 owner surface 的任意组件树 |
## 4. 现有架构推进进度
@ -626,14 +634,18 @@ interface SlideLayoutPlan {
23. Stage 12 mixed component/prose 清晰边界已收敛并通过真实验收：`mixed-component-prose-stress` 证明一个完整 component surface 与 Markdown prose/list 可以先拆成 presentation surfaces，组件页再走 measured local `<Transform>`；真实 `architecture.zh-CN.md` strict native standalone 归档到 `/home/jacob/slidev-export-review/2026-06-20-stage12-mixed-component-prose-real/`。
24. Stage 13 unsupported component boundary fail-transparent 已落地：`unsupported-component-table-boundary-stress` 是 expected-failure fixture，显式运行时 verifier 必须 `ok = false`，但 standalone、浏览器加载、Git 可见性、Mermaid source-preservation 都必须通过；blocked reason 必须说明 mixed component + primary Markdown 不能用整页 zoom 修。默认成功 fixture suite 仍排除 expected-failure fixture，归档到 `/home/jacob/slidev-export-review/2026-06-20-stage13-success-fixtures/`。
25. Stage 13 真实 `architecture.zh-CN.md` strict native standalone 已重新验收并归档到 `/home/jacob/slidev-export-review/2026-06-20-stage13-real/`；报告继续证明本地 Slidev fork、52 个 skill references、native standalone、3 个 Mermaid fence byte-stable、`changedFenceIndexes = []`、0 hard overflow 与 0 low effective font。该切片没有引入任何 Mermaid 源图拆分或改写。
26. Stage 14 unsupported component/fence 与 component/image fail-transparent fixtures 已落地：两个显式 fixture 都必须 verifier `ok = false` 且 blocked reason 指向 mixed component + primary Markdown 不能用整页 zoom 修，同时 standalone、浏览器加载、Mermaid source-preservation 与失败指纹通过；image fixture 额外验证 prepared/export 两层都保留本地 SVG 资产。
27. Stage 14 真实 `architecture.zh-CN.md` strict native standalone 已重新验收并归档到 `/home/jacob/slidev-export-review/2026-06-20-stage14-real/`；报告继续证明本地 Slidev fork、52 个 skill references、native standalone、3 个 Mermaid fence byte-stable、`changedFenceIndexes = []`、0 hard overflow 与 0 low effective font。该切片没有引入任何 Mermaid 源图拆分或改写。
建议下一批实现顺序：
1. 继续把更多真实失败样本沉淀为 full-deck/export fixtures，尤其是多个不稳定 owner、component surface 内混入 fence/image、custom layout 需要分页但没有明确 surface boundary 的 unsupported layout；Stage 13 只证明 component/table 会 fail transparent、component/directive 会阻断整页 zoom，不代表任意 Vue component tree 都可安全 Transform；
1. 继续把更多真实失败样本沉淀为 full-deck/export fixtures，尤其是多个不稳定 owner、component/prose/component 顺序、custom layout 需要分页但没有明确 surface boundary 的 unsupported layout；Stage 14 已证明 component/table/fence/image 会 fail transparent、component/directive 会阻断整页 zoom，不代表任意 Vue component tree 都可安全 Transform；
2. 对 Mermaid 继续只做源图保持的 fit/zoom/Transform 与人工复核边界；自动路径只允许移动非 Mermaid 内容，不允许拆原图、改 body、改 opener metadata 或重排 fence；
3. 继续增强更多语言专用 splitter；Python/Rust 当前是 parser-light，不是完整 AST；
4. 评估是否把 source-preserved Mermaid fit review、mixed Mermaid/prose 仅移动非图内容的 guardrail、browser-check 与“不要拆用户原图”抽成通用 Slidev skill PR 建议。
后续任何 canvas 或 viewport 策略都必须围绕 Mermaid source preservation 工作：除非人工编辑源文件，一个源 Mermaid fence 必须对应一个导出 Mermaid fence，opener、metadata、body、closer 与顺序都不变。
不要先做：
1. 大规模 UI 画布编辑器；

16
docs/maintainer/slidev-export-workflow.md
View file

@ -85,13 +85,15 @@ The current Stage 12 fixture archive is:
It adds `mixed-component-prose-stress`, proving that a custom `dashboard-shell` slide with one complete Vue component surface and one Markdown prose/list content block can first be separated into independent presentation surfaces. The component page can then converge through measured local `<Transform>`, while the prose page does not inherit whole-slide `zoom`. The suite still requires Mermaid fences to remain byte-stable, must not split one source Mermaid diagram into several diagrams, and must not rewrite fence metadata or diagram bodies.
Stage 13 adds an expected-failure fixture for unsafe component/table boundaries:
Stage 13/14 add expected-failure fixtures for unsafe component/table, component/fence, and component/image boundaries:
```bash
npm run verify:slidev-layout-fixtures -- --fixture unsupported-component-table-boundary-stress --archive /home/jacob/slidev-export-review/2026-06-20-stage13-unsupported-component-boundary-fixture --timeout-ms 300000
npm run verify:slidev-layout-fixtures -- --fixture unsupported-component-fence-boundary-stress --archive /home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-fence-boundary-fixture --timeout-ms 300000
npm run verify:slidev-layout-fixtures -- --fixture unsupported-component-image-boundary-stress --archive /home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-image-boundary-fixture --timeout-ms 300000
```
This fixture passes only when the production verifier reports `ok = false`, the blocked reason includes `mixed component and primary Markdown content cannot be fixed with whole-slide zoom`, and native standalone export, browser loading, Git-visible artifacts, the failure fingerprint, and Mermaid source preservation all remain valid. The default fixture suite excludes expected failures; pass `--include-expected-failures` only when explicitly auditing fail-transparent boundaries.
These fixtures pass only when the production verifier reports `ok = false`, the blocked reason includes `mixed component and primary Markdown content cannot be fixed with whole-slide zoom`, and native standalone export, browser loading, Git-visible artifacts, the failure fingerprint, and Mermaid source preservation all remain valid. The image fixture also requires the local SVG asset to exist in both the prepared deck and final standalone export. The default fixture suite excludes expected failures; pass `--include-expected-failures` only when explicitly auditing fail-transparent boundaries.
For a live desktop-session smoke against the real Obsidian command path:
@ -218,7 +220,7 @@ Current landed truth as of 2026-06-20:
10. hard overflow findings still use the rendered slide root as the pass/fail boundary, while `safeRect` remains the fit target for measured scale recommendations; this keeps edge-aligned layouts from being over-rejected while still letting the patcher derive conservative shrink factors;
11. the shared `convergeSlidevDeckLayout()` workflow now runs inside `exportSlidesCommand()` and the maintainer verifier, so HTML/PDF/PNG/MP4 export all reuse the same converged prepared deck;
12. the HTML exporter now returns a structured outcome with `requestedMode`, `actualMode`, fallback state, and standalone sanity details; known-bad native attempts are preserved as `index-standalone.failed.html` before compatibility fallback;
13. the real `docs/architecture.zh-CN.md` strict native standalone workflow now closes with `ok: true`, `actualMode: "standalone"`, `requiresLocalServer: false`, `standaloneGate.passed: true`, `27` audited slides, and zero hard overflow / unreadable scale / low effective font / quality margin warning / low utilization findings with `retryCount = 4`; the preserve-Mermaid run kept the source and exported deck at `3` Mermaid fences, and current verifier reports must also show `mermaidSourcePreservation.passed = true`; the current Stage 13 evidence package is stored at `/home/jacob/slidev-export-review/2026-06-20-stage13-real/`;
13. the real `docs/architecture.zh-CN.md` strict native standalone workflow now closes with `ok: true`, `actualMode: "standalone"`, `requiresLocalServer: false`, `standaloneGate.passed: true`, `27` audited slides, and zero hard overflow / unreadable scale / low effective font / quality margin warning / low utilization findings with `retryCount = 4`; the preserve-Mermaid run kept the source and exported deck at `3` Mermaid fences, and current verifier reports must also show `mermaidSourcePreservation.passed = true`; the current Stage 14 evidence package is stored at `/home/jacob/slidev-export-review/2026-06-20-stage14-real/`;
14. `PDF` and `PNG` verification on the same source also return `ok: true`, and now export from the same converged deck instead of the raw prepared source;
15. rendered layout audit now reports effective minimum font, SVG text font, table/code minimum font, quality margins, and content-area ratio alongside hard overflow;
16. low effective font, tight margin, and low content utilization findings now carry structural `recommendedPatch` values for table/code/prose; Mermaid low-font metrics are recorded while preserving the source fence instead of automatically splitting one diagram into several diagrams;
@ -254,18 +256,22 @@ Current landed truth as of 2026-06-20:
46. the Stage 13 expected-failure fixture archive is `/home/jacob/slidev-export-review/2026-06-20-stage13-unsupported-component-boundary-fixture/`; `unsupported-component-table-boundary-stress` proves an unsupported component/table boundary is not silently repaired with whole-slide `zoom`, while one source Mermaid fence remains one exported Mermaid fence.
47. the Stage 13 default success fixture suite is archived at `/home/jacob/slidev-export-review/2026-06-20-stage13-success-fixtures/`; all 9 converging production fixtures pass, and expected-failure fixtures are excluded by default.
48. the Stage 13 real `architecture.zh-CN.md` strict native standalone archive is `/home/jacob/slidev-export-review/2026-06-20-stage13-real/`; the report is `ok = true`, uses the local Slidev fork and 52 skill references, reports `actualMode = "standalone"`, `requiresLocalServer = false`, `standaloneGate.passed = true`, preserves all 3 Mermaid fences with `changedFenceIndexes = []`, closes with `hardOverflowCount = 0` and `lowEffectiveFontCount = 0`, and archives the reviewable `architecture.zh-CN.stage13.slidev.md` plus `architecture.zh-CN-slides/index-standalone.html`.
49. the Stage 14 component/fence expected-failure fixture archive is `/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-fence-boundary-fixture/`; `unsupported-component-fence-boundary-stress` proves an unsupported component/fence boundary is not silently repaired with whole-slide `zoom`, while one source Mermaid fence remains one exported Mermaid fence.
50. the Stage 14 component/image expected-failure fixture archive is `/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-image-boundary-fixture/`; `unsupported-component-image-boundary-stress` proves the image boundary also fails transparently and verifies `assets/boundary-image.svg` in both the prepared deck and final standalone export.
51. the Stage 14 default success fixture suite is archived at `/home/jacob/slidev-export-review/2026-06-20-stage14-success-fixtures/`; all 9 converging production fixtures pass, and the three expected-failure fixtures are excluded by default.
52. the Stage 14 real `architecture.zh-CN.md` strict native standalone archive is `/home/jacob/slidev-export-review/2026-06-20-stage14-real/`; the report is `ok = true`, uses the local Slidev fork and 52 skill references, reports `actualMode = "standalone"`, `requiresLocalServer = false`, `standaloneGate.passed = true`, preserves all 3 Mermaid fences with `changedFenceIndexes = []`, closes with `hardOverflowCount = 0` and `lowEffectiveFontCount = 0`, and archives the reviewable `architecture.zh-CN.stage14.slidev.md` plus `architecture.zh-CN-slides/index-standalone.html`.
Current limitation:
1. effective font measurement now accounts for common local CSS transform/scale/zoom chains, but the browser rendered audit remains the authority for complex Vue layouts; do not replace it with static Markdown estimates;
2. richer custom/component-heavy Slidev layouts beyond the current supported structural set still remain conservative/manual-review paths, especially when no stable owner surface exists, when fence/image syntax is mixed into a component surface, when component/prose/component ordering is unstable, or when content cannot be safely paginated. Stage 13 covers component/table fail-transparent behavior and component/directive zoom blocking; it is not proof that arbitrary Vue component trees can be transformed safely;
2. richer custom/component-heavy Slidev layouts beyond the current supported structural set still remain conservative/manual-review paths, especially when no stable owner surface exists, when component/prose/component ordering is unstable, or when content cannot be safely paginated. Stage 14 covers component/table/fence/image fail-transparent behavior and component/directive zoom blocking is covered by unit tests; it is not proof that arbitrary Vue component trees can be transformed safely;
3. native standalone export now has a strict gate and the real architecture fixture passes it, but correctness still depends on post-build sanity detection; server-script fallback remains a compatibility lane and must not be counted as native standalone success;
4. full-deck Playwright verification is deliberately slower than representative sampling, so future work should improve convergence rather than weaken the audit;
5. `obsidian command id=notemd:export-slides` is still only a dispatch-level smoke because the Obsidian CLI does not expose an export-complete handshake.
6. Mermaid `manual-review` evidence is not a hard gate failure. It is the correct fail-transparent outcome when preserving the original Mermaid source and guaranteeing projector-level readability cannot both be proven automatically.
7. code splitting is still parser-light. TypeScript/JavaScript/Python/Rust now have top-level tokenizers, but full AST splitting and more language-specific splitters remain future work.
8. The Mermaid no-split constraint does not mean Mermaid presentation quality automatically passes. If a very large source diagram can only remain complete at low zoom, the workflow should surface `source-preserved-fit-review` or `manual-review` instead of silently rewriting or splitting the diagram.
9. the current full-deck fixtures cover long-table, wide-table, mixed-code, Mermaid source-preserved fit, component-heavy slot Transform boundaries, mixed Mermaid/prose non-diagram content movement, local image assets, nested slot components, ultra-wide tables, frontmatter background/image/favicon assets, cross-directory assets, CSS `url(...)` image/font dependencies, local CSS `@import` chains, local video/audio/track assets, offline font-provider boundaries, bounded raw HTML/component single-surface slides, bounded component-only Vue tree surfaces, clear-boundary mixed component/prose, and unsupported component/table expected failure, but they are not exhaustive; add more fixture sources for complex Vue components and unsupported layouts as they fail in real documents.
9. the current full-deck fixtures cover long-table, wide-table, mixed-code, Mermaid source-preserved fit, component-heavy slot Transform boundaries, mixed Mermaid/prose non-diagram content movement, local image assets, nested slot components, ultra-wide tables, frontmatter background/image/favicon assets, cross-directory assets, CSS `url(...)` image/font dependencies, local CSS `@import` chains, local video/audio/track assets, offline font-provider boundaries, bounded raw HTML/component single-surface slides, bounded component-only Vue tree surfaces, clear-boundary mixed component/prose, and unsupported component/table/fence/image expected failures, but they are not exhaustive; add more fixture sources for complex Vue components and unsupported layouts as they fail in real documents.
## Output Policy

16
docs/maintainer/slidev-export-workflow.zh-CN.md
View file

@ -85,13 +85,15 @@ npm run verify:slidev-layout-fixtures -- --archive /home/jacob/slidev-export-rev
其中新增 `mixed-component-prose-stress`，用于证明自定义 `dashboard-shell` 中一个完整 Vue component surface 与 Markdown prose/list 主内容块可以先被分离为独立 presentation surfaces，后续组件页通过 measured local `<Transform>` 收敛，正文页不继承整页 `zoom`。该套件仍要求 Mermaid fence byte-stable，不允许把一个源 Mermaid 图拆成多个图，也不允许改写 fence metadata 或图体内容。
Stage 13 新增 expected-failure fixture，用于验证不安全 component/table 边界会显性失败而不是被整页 `zoom` 静默修掉：
Stage 13/14 新增 expected-failure fixtures，用于验证不安全 component/table、component/fence 与 component/image 边界会显性失败而不是被整页 `zoom` 静默修掉：
```bash
npm run verify:slidev-layout-fixtures -- --fixture unsupported-component-table-boundary-stress --archive /home/jacob/slidev-export-review/2026-06-20-stage13-unsupported-component-boundary-fixture --timeout-ms 300000
npm run verify:slidev-layout-fixtures -- --fixture unsupported-component-fence-boundary-stress --archive /home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-fence-boundary-fixture --timeout-ms 300000
npm run verify:slidev-layout-fixtures -- --fixture unsupported-component-image-boundary-stress --archive /home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-image-boundary-fixture --timeout-ms 300000
```
这个 fixture 的成功含义是生产 verifier 报告 `ok = false`，blocked reason 指向 `mixed component and primary Markdown content cannot be fixed with whole-slide zoom`，同时 standalone gate、浏览器加载、Git 可见性、失败指纹和 Mermaid source-preservation 都通过。默认 fixture suite 不包含 expected-failure；若要一起审查，显式传 `--include-expected-failures`。
这些 fixtures 的成功含义是生产 verifier 报告 `ok = false`，blocked reason 指向 `mixed component and primary Markdown content cannot be fixed with whole-slide zoom`，同时 standalone gate、浏览器加载、Git 可见性、失败指纹和 Mermaid source-preservation 都通过。image fixture 还要求本地 SVG 资产同时存在于 prepared deck 和最终 standalone export。默认 fixture suite 不包含 expected-failure；若要一起审查，显式传 `--include-expected-failures`。
如果本机已有真实 Obsidian 桌面会话，也应补一层真实命令路径 smoke：
@ -218,7 +220,7 @@ mermaidSourcePreservation.changedFenceIndexes
10. pass/fail 的 hard overflow 仍以渲染后的 slide root 为边界，而 `safeRect` 继续只承担 measured scale 的保守拟合目标；这样既不会放过真正裁剪，也不会把合理的 edge-aligned layout 过度误杀；
11. 共享的 `convergeSlidevDeckLayout()` 现在已经进入 `exportSlidesCommand()` 与维护者 verifier，因此 HTML/PDF/PNG/MP4 都会复用同一个收敛后的 prepared deck；
12. HTML exporter 现在会返回结构化 outcome，包含 `requestedMode`、`actualMode`、fallback 状态与 standalone sanity 细节；已知坏掉的 native attempt 会先保留为 `index-standalone.failed.html`，再进入兼容 fallback；
13. 真实 `docs/architecture.zh-CN.md` 严格 native standalone workflow 现在已经收敛到 `ok: true`、`actualMode: "standalone"`、`requiresLocalServer: false`、`standaloneGate.passed: true`、`27` 个审计页，hard overflow / unreadable scale / low effective font / quality margin warning / low utilization 均为零，`retryCount = 4`；preserve-Mermaid rerun 保持源文档与导出 deck 均为 `3` 个 Mermaid fence，且当前 verifier 必须报告 `mermaidSourcePreservation.passed = true`；当前 Stage 13 证据包位于 `/home/jacob/slidev-export-review/2026-06-20-stage13-real/`；
13. 真实 `docs/architecture.zh-CN.md` 严格 native standalone workflow 现在已经收敛到 `ok: true`、`actualMode: "standalone"`、`requiresLocalServer: false`、`standaloneGate.passed: true`、`27` 个审计页，hard overflow / unreadable scale / low effective font / quality margin warning / low utilization 均为零，`retryCount = 4`；preserve-Mermaid rerun 保持源文档与导出 deck 均为 `3` 个 Mermaid fence，且当前 verifier 必须报告 `mermaidSourcePreservation.passed = true`；当前 Stage 14 证据包位于 `/home/jacob/slidev-export-review/2026-06-20-stage14-real/`；
14. 同一真实源文件的 `PDF` 与 `PNG` 验证也返回 `ok: true`，而且现在导出自同一个收敛后的 deck，而不是 raw prepared source；
15. rendered layout audit 现在会同时报告 effective minimum font、SVG text font、table/code minimum font、quality margins 与 content-area ratio；
16. low effective font、tight margin 与 low content utilization finding 现在会对 table/code/prose 携带结构化 `recommendedPatch`；Mermaid 低字号指标会被记录，但默认保持源 fence，不把一张原图自动拆成多张图；
@ -254,18 +256,22 @@ mermaidSourcePreservation.changedFenceIndexes
46. Stage 13 expected-failure fixture 验收包位于 `/home/jacob/slidev-export-review/2026-06-20-stage13-unsupported-component-boundary-fixture/`；`unsupported-component-table-boundary-stress` 证明 unsupported component/table boundary 不会被整页 `zoom` 静默修掉，同时保留一个源 Mermaid fence 为一个导出 Mermaid fence。
47. Stage 13 默认成功 fixture suite 归档到 `/home/jacob/slidev-export-review/2026-06-20-stage13-success-fixtures/`；9 个可收敛生产 fixtures 均通过，expected-failure fixture 默认排除。
48. Stage 13 真实 `architecture.zh-CN.md` strict native standalone 验收包位于 `/home/jacob/slidev-export-review/2026-06-20-stage13-real/`；报告为 `ok = true`，使用本地 Slidev fork 与 52 个 skill references，`actualMode = "standalone"`，`requiresLocalServer = false`，`standaloneGate.passed = true`，3 个 Mermaid fence 均保持 `changedFenceIndexes = []`，`hardOverflowCount = 0`，`lowEffectiveFontCount = 0`，并归档了可审查的 `architecture.zh-CN.stage13.slidev.md` 与 `architecture.zh-CN-slides/index-standalone.html`。
49. Stage 14 component/fence expected-failure fixture 验收包位于 `/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-fence-boundary-fixture/`；`unsupported-component-fence-boundary-stress` 证明 unsupported component/fence boundary 不会被整页 `zoom` 静默修掉，同时保留一个源 Mermaid fence 为一个导出 Mermaid fence。
50. Stage 14 component/image expected-failure fixture 验收包位于 `/home/jacob/slidev-export-review/2026-06-20-stage14-unsupported-component-image-boundary-fixture/`；`unsupported-component-image-boundary-stress` 证明 image 混排边界同样 fail transparent，并验证 `assets/boundary-image.svg` 在 prepared deck 和最终 standalone export 两层都存在。
51. Stage 14 默认成功 fixture suite 归档到 `/home/jacob/slidev-export-review/2026-06-20-stage14-success-fixtures/`；9 个可收敛生产 fixtures 均通过，三个 expected-failure fixtures 默认排除。
52. Stage 14 真实 `architecture.zh-CN.md` strict native standalone 验收包位于 `/home/jacob/slidev-export-review/2026-06-20-stage14-real/`；报告为 `ok = true`，使用本地 Slidev fork 与 52 个 skill references，`actualMode = "standalone"`，`requiresLocalServer = false`，`standaloneGate.passed = true`，3 个 Mermaid fence 均保持 `changedFenceIndexes = []`，`hardOverflowCount = 0`，`lowEffectiveFontCount = 0`，并归档了可审查的 `architecture.zh-CN.stage14.slidev.md` 与 `architecture.zh-CN-slides/index-standalone.html`。
当前限制：
1. effective font measurement 现在已经覆盖常见局部 CSS transform / scale / zoom 链，但复杂 Vue layout 仍必须以浏览器 rendered audit 为准，不能退回静态 Markdown 估算；
2. 超出当前支持集的 richer custom/component-heavy Slidev layout 仍保持保守/manual-review 路径，尤其是缺少稳定 owner surface、component surface 内混入 fence/image、component/prose/component 顺序不稳定或不能安全分页的情况；Stage 13 已覆盖 component/table fail-transparent 与 component/directive 阻断，不证明任意 Vue component tree 都能安全 Transform；多个 named slot 竞争且 unsafe 的路径已由 slot 分页 fixture 覆盖；
2. 超出当前支持集的 richer custom/component-heavy Slidev layout 仍保持保守/manual-review 路径，尤其是缺少稳定 owner surface、component/prose/component 顺序不稳定或不能安全分页的情况；Stage 14 已覆盖 component/table/fence/image fail-transparent，component/directive 阻断由单测覆盖，不证明任意 Vue component tree 都能安全 Transform；多个 named slot 竞争且 unsafe 的路径已由 slot 分页 fixture 覆盖；
3. native standalone 现在已有严格 gate，且真实 architecture fixture 已通过；但正确性仍依赖 post-build sanity detection，server-script fallback 只是兼容通道，不能再被算作 native standalone 成功；
4. full-deck Playwright 验证故意比代表性抽样更慢，后续优化方向应是提高 patch 收敛能力，而不是退回弱审计；
5. `obsidian command id=notemd:export-slides` 目前仍只能算 dispatch-level smoke，因为 Obsidian CLI 没有暴露导出完成握手信号。
6. Mermaid `manual-review` 证据不是 hard gate failure。它是在“不修改原 Mermaid 内容”和“自动保证投影级可读”不能同时被证明时，正确暴露给维护者的透明结果。
7. code splitting 仍是 parser-light；TypeScript/JavaScript/Python/Rust 已有 top-level tokenizer，但完整 AST 拆分与更多语言专用 splitter 仍是后续工作。
8. Mermaid 不拆图约束不等于 Mermaid 演示质量自动合格。超大源图如果只能靠低 zoom 保持完整，流程应暴露 `source-preserved-fit-review` 或 `manual-review`，而不是静默改图或拆图。
9. 当前 full-deck fixtures 已覆盖长表、宽表、混合代码、Mermaid 源图保持 fit、component-heavy slot Transform 边界、Mermaid/prose 非图内容移动、本地图片资产、嵌套 slot component、超宽表、frontmatter background/image/favicon、跨目录资产、CSS `url(...)` 图片/字体依赖、本地 CSS `@import` 链、本地 video/audio/track 资产、离线字体边界、bounded raw HTML/component single-surface、bounded component-only Vue tree surface、清晰边界 mixed component/prose 与 unsupported component/table expected-failure，但仍不是 exhaustive；后续真实文档若出现复杂 Vue component 或 unsupported layout 失败，应继续沉淀为 fixture。
9. 当前 full-deck fixtures 已覆盖长表、宽表、混合代码、Mermaid 源图保持 fit、component-heavy slot Transform 边界、Mermaid/prose 非图内容移动、本地图片资产、嵌套 slot component、超宽表、frontmatter background/image/favicon、跨目录资产、CSS `url(...)` 图片/字体依赖、本地 CSS `@import` 链、本地 video/audio/track 资产、离线字体边界、bounded raw HTML/component single-surface、bounded component-only Vue tree surface、清晰边界 mixed component/prose 与 unsupported component/table/fence/image expected-failure，但仍不是 exhaustive；后续真实文档若出现复杂 Vue component 或 unsupported layout 失败，应继续沉淀为 fixture。
## 输出策略

213
scripts/verify-slidev-layout-fixtures.cjs
View file

@ -390,6 +390,168 @@ function createUnsupportedComponentTableBoundaryStressDeck() {
].join('\n');
}
function createUnsupportedComponentFenceBoundaryStressDeck() {
return [
'---',
'theme: default',
'mdc: true',
'---',
'',
'# Unsupported Component Fence Boundary Stress',
'',
'```mermaid',
'flowchart LR',
' Source[One source Mermaid fence] --> Deck[One exported Mermaid fence]',
' Deck --> Review[Source-preserved review]',
'```',
'',
'---',
'layout: dashboard-shell',
'---',
'',
'## Unsupported Component Fence Surface',
'',
'<DashboardGrid class="stage14-dashboard">',
' <MetricPanel label="Queue A" value="128" tone="teal" />',
' <MetricPanel label="Queue B" value="256" tone="blue" />',
' <MetricPanel label="Queue C" value="512" tone="amber" />',
' <MetricPanel label="Queue D" value="1024" tone="violet" />',
'</DashboardGrid>',
'',
'```ts',
'const unsupportedComponentFenceBoundary = "Unsupported component fence boundary regression fingerprint";',
'export function shouldFailTransparent() {',
' return unsupportedComponentFenceBoundary;',
'}',
'```',
'',
].join('\n');
}
function createUnsupportedComponentImageBoundaryStressDeck() {
return [
'---',
'theme: default',
'mdc: true',
'---',
'',
'# Unsupported Component Image Boundary Stress',
'',
'```mermaid',
'flowchart LR',
' Source[One source Mermaid fence] --> Deck[One exported Mermaid fence]',
' Deck --> Review[Source-preserved review]',
'```',
'',
'---',
'layout: dashboard-shell',
'---',
'',
'## Unsupported Component Image Surface',
'',
'<DashboardGrid class="stage14-dashboard">',
' <MetricPanel label="Queue A" value="128" tone="teal" />',
' <MetricPanel label="Queue B" value="256" tone="blue" />',
' <MetricPanel label="Queue C" value="512" tone="amber" />',
' <MetricPanel label="Queue D" value="1024" tone="violet" />',
'</DashboardGrid>',
'',
'![Unsupported component image boundary regression fingerprint](./assets/boundary-image.svg)',
'',
].join('\n');
}
function createUnsupportedComponentBoundarySupportFiles(panelText) {
return [
{
path: 'layouts/dashboard-shell.vue',
content: [
'<template>',
' <main class="notemd-dashboard-shell">',
' <slot />',
' </main>',
'</template>',
'',
'<style>',
'.notemd-dashboard-shell {',
' height: 100%;',
' padding: 54px 62px;',
' overflow: hidden;',
'}',
'</style>',
].join('\n'),
},
{
path: 'components/DashboardGrid.vue',
content: [
'<template>',
' <section class="stage14-grid">',
' <slot />',
' </section>',
'</template>',
'',
'<style>',
'.stage14-grid {',
' width: 1680px;',
' min-height: 510px;',
' display: grid;',
' grid-template-columns: repeat(4, 365px);',
' gap: 24px;',
' border: 1px solid #475569;',
' padding: 26px;',
' background: #f8fafc;',
' color: #0f172a;',
'}',
'</style>',
].join('\n'),
},
{
path: 'components/MetricPanel.vue',
content: [
'<template>',
' <article class="stage14-panel" :class="`stage14-panel--${tone}`">',
' <h2>{{ label }}</h2>',
' <strong>{{ value }}</strong>',
` <p>${panelText}</p>`,
' </article>',
'</template>',
'',
'<script setup>',
'defineProps({',
' label: { type: String, required: true },',
' value: { type: String, required: true },',
' tone: { type: String, required: true },',
'});',
'</script>',
'',
'<style>',
'.stage14-panel {',
' border-left: 5px solid #0f766e;',
' padding-left: 16px;',
'}',
'.stage14-panel--blue { border-left-color: #2563eb; }',
'.stage14-panel--amber { border-left-color: #b45309; }',
'.stage14-panel--violet { border-left-color: #7c3aed; }',
'.stage14-panel h2 {',
' font-size: 30px;',
' margin: 0 0 14px;',
'}',
'.stage14-panel strong {',
' display: block;',
' font-size: 38px;',
' margin-bottom: 12px;',
'}',
'.stage14-panel p {',
' font-size: 20px;',
' line-height: 1.35;',
' margin: 0;',
'}',
'</style>',
].join('\n'),
},
];
}
function createCompetingSlotZonesStressDeck() {
return [
'---',
@ -1027,6 +1189,37 @@ const FIXTURES = [
reasonIncludes: 'mixed component and primary Markdown content',
},
},
{
id: 'unsupported-component-fence-boundary-stress',
sourcePath: 'unsupported-component-fence-boundary-stress.md',
sourceMarkdown: createUnsupportedComponentFenceBoundaryStressDeck(),
files: createUnsupportedComponentBoundarySupportFiles('Unsupported component fence boundary must not be repaired with whole-slide zoom.'),
expectNoWholeSlideZoom: true,
expectedMermaidBlocks: 1,
expectedFailure: {
expectedHardOverflow: true,
expectedFingerprint: 'Unsupported component fence boundary regression fingerprint',
reasonIncludes: 'mixed component and primary Markdown content',
},
},
{
id: 'unsupported-component-image-boundary-stress',
sourcePath: 'unsupported-component-image-boundary-stress.md',
sourceMarkdown: createUnsupportedComponentImageBoundaryStressDeck(),
files: [
...createUnsupportedComponentBoundarySupportFiles('Unsupported component image boundary must not be repaired with whole-slide zoom.'),
{ path: 'assets/boundary-image.svg', content: createFixtureSvg('Unsupported component image boundary', '#eff6ff', '#2563eb') },
],
expectNoWholeSlideZoom: true,
expectedMermaidBlocks: 1,
expectedCopiedAssets: ['assets/boundary-image.svg'],
expectedExportAssets: ['assets/boundary-image.svg'],
expectedFailure: {
expectedHardOverflow: true,
expectedFingerprint: 'Unsupported component image boundary regression fingerprint',
reasonIncludes: 'mixed component and primary Markdown content',
},
},
{
id: 'competing-slot-zones-stress',
sourcePath: 'competing-slot-zones-stress.md',
@ -1420,6 +1613,26 @@ function assertExpectedFailureFixtureReport(fixture, report, sourceMarkdown) {
if (expectedFailure.expectedFingerprint) {
assert(deckMarkdown.includes(expectedFailure.expectedFingerprint), `${fixture.id}: failure-review fingerprint disappeared from prepared deck`);
}
if (fixture.expectedCopiedAssets) {
const preparedDeckDirectory = path.dirname(report.deck.path);
for (const relativeAssetPath of fixture.expectedCopiedAssets) {
assert(fs.existsSync(path.join(preparedDeckDirectory, relativeAssetPath)), `${fixture.id}: prepared workspace is missing ${relativeAssetPath}`);
}
assert(!fs.existsSync(path.join(preparedDeckDirectory, 'outside.svg')), `${fixture.id}: prepared workspace copied an out-of-scope asset`);
assert(!fs.existsSync(path.join(preparedDeckDirectory, 'outside.css')), `${fixture.id}: prepared workspace copied an out-of-scope imported stylesheet`);
assertNoRejectedCssReferences(fixture.id, preparedDeckDirectory, 'prepared workspace');
}
if (fixture.expectedExportAssets) {
const outputDirectory = fs.statSync(report.output.path).isDirectory()
? report.output.path
: path.dirname(report.output.path);
for (const relativeAssetPath of fixture.expectedExportAssets) {
assert(fs.existsSync(path.join(outputDirectory, relativeAssetPath)), `${fixture.id}: final export is missing ${relativeAssetPath}`);
}
assert(!fs.existsSync(path.join(outputDirectory, 'outside.svg')), `${fixture.id}: final export copied an out-of-scope asset`);
assert(!fs.existsSync(path.join(outputDirectory, 'outside.css')), `${fixture.id}: final export copied an out-of-scope imported stylesheet`);
assertNoRejectedCssReferences(fixture.id, outputDirectory, 'final export');
}
}
function collectBlockedReasons(report) {

7
src/tests/slidevLayoutAudit.test.ts
View file

@ -2604,6 +2604,13 @@ describe('slidevLayoutAudit', () => {
],
fingerprint: 'Directive content is an unsupported component/prose boundary.',
},
{
name: 'image',
lines: [
'![Unsupported component image boundary regression fingerprint](./assets/boundary-image.svg)',
],
fingerprint: 'Unsupported component image boundary regression fingerprint',
},
])('blocks whole-slide zoom for mixed component and $name content when separation is unsafe', ({ lines, fingerprint }) => {
const audit: SlidevLayoutAudit = {
slide: 2,