docs: document Canonical vs Visual geometry contract for MMDS#384
Merged
Conversation
MMDS persists Canonical geometry by design — wider, replay-faithful bounds and full bend waypoints — while direct SVG output uses Visual, the tight pixel-faithful projection. The split is intentional: the labeled-edge bend topology (e.g. a reciprocal labeled edge produces a 4+ point polyline) would simplify to a straight L under Visual, so adapters that replay edge routing need Canonical to reproduce the shape faithfully. Without this note, a Mermaid -> MMDS -> SVG round-trip via the CLI surprises consumers: the cluster rect is taller and the node positions shift relative to a direct Mermaid -> SVG render. Adding a "Geometry Contract" subsection under "Geometry Levels" pins the contract distinction, names the trade-off, and points adapter authors at the right output format for their use case. No behavior change.
kevinswiber
force-pushed
the
chore/mmds-canonical-vs-visual-contract-doc
branch
from
6717ecd to
ff52c16
Compare
kevinswiber
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a "Geometry Contract: Canonical (MMDS) vs Visual (SVG)" subsection to
docs/mmds.mdunder "Geometry Levels". Pins the design decision that MMDS persists Canonical geometry (wider, replay-faithful, preserves labeled-edge bend waypoints) while direct SVG output uses Visual (tight, pixel-faithful, simplifies bend topology).Background: a CLI MMDS→SVG replay surprised a consumer with a wider subgraph rect than a direct Mermaid→SVG render. Both code paths use the same engine on the same diagram, but pass different
GraphGeometryContractvalues into the solver (seesrc/runtime/graph_family.rs::geometry_contract_for_format). We experimented with switching MMDS to Visual; it broke the Tier A bent-path preservation tests (a labeled reciprocal edge collapsed from a 4-point polyline bending around its label to a 3-point straight L), confirming that Canonical isn't just padded for cosmetics — it carries informational geometry adapters depend on for replay.No code change, just a doc note that names the trade-off, explains why MMDS uses Canonical, and points adapter authors at
examples/mmds/for replay patterns.Test plan
just spell-check docs/mmds.md