agentic-mermaid 0.1.1 → 0.2.0

package/docs/layout-characterization/properties.md

@@ -1,281 +0,0 @@
-# Load-bearing properties of the layout characterisation
-
-This is the **smallest set of properties that characterise and determine** the
-hand-written ASCII grid + A\* layout algorithm
-(`src/ascii/grid.ts`, `pathfinder.ts`, `edge-routing.ts`, `edge-bundling.ts`).
-Each property is encoded as a property-based test in
-[`src/__tests__/characterization-layout.test.ts`](../../src/__tests__/characterization-layout.test.ts)
-and motivated by a worked example in [`contact-sheet.md`](./contact-sheet.md).
-
-The renderer breadth layer is intentionally smaller and more conservative:
-[`src/__tests__/characterization-families.test.ts`](../../src/__tests__/characterization-families.test.ts)
-extends only the universal assumptions that hold across every diagram family
-and public output surface. It is motivated by
-[`contact-sheet-families.md`](./contact-sheet-families.md).
-
-The visual-quality layer
-([`visual-quality.md`](./visual-quality.md)) is an approval artifact rather than
-part of the minimal property kernel: it records SVG snapshots, SVG/PNG hashes,
-and review metrics for crossings, bends, route length, canvas area, label fit,
-and edge-label overlap risk. After PR 30, the hard route-quality oracle lives in
-`src/layout-rubric.ts` and `src/__tests__/layout-rubric.test.ts`; this document
-does not duplicate those assertions.
-
-"Load-bearing" has a precise operational meaning here (see
-[§ Minimality](#minimality)): a property is load-bearing if removing it lets a
-plausible single-edit mutation of the layout code survive — i.e. it is the
-property that *kills* that class of mutant. Properties that kill no unique
-mutant are redundant and excluded.
-
-These are **characterisation** properties in Michael Feathers' sense (*Working
-Effectively with Legacy Code*, ch. 13): they pin **what the algorithm does
-today**, not what it ideally should do. A passing suite means behaviour is
-unchanged; it is not a correctness oracle. When an intended change flips one of
-them, that is the signal to update the characterisation deliberately.
-
----
-
-## Why there are three tiers
-
-The algorithm is a **best-effort heuristic layout**, not a solver. Empirically
-(over thousands of generated graphs) its guarantees fall into three bands:
-
-- **Tier A — universal invariants.** True for *every* valid flowchart/state
-  input, including cycles, self-loops, and dense graphs. These are the hard
-  contract.
-- **Tier B — structural properties on well-behaved subclasses.** True for
-  trees / DAGs / linear chains, where placement is unambiguous. The algorithm
-  does **not** extend these guarantees to cyclic or dense graphs — and *that
-  boundary is itself a characterisation* (Tier C, P10).
-- **Tier C — metamorphic relations & known limits.** Relations between two
-  renders (BT vs TD, RL vs LR, relabelled vs original) that pin specific design
-  decisions, plus an explicit pin of a place where Tier B *fails*.
-
-This mirrors the literature's split between **invariants** (oracle-grade, exact
-assertions) and **quality heuristics** (graded, only safe to assert as
-metamorphic/monotonic relations). Crossing count, edge length, and compactness
-are quality heuristics and are deliberately **not** asserted here — they are
-brittle golden values, not load-bearing invariants.
-
-PR 30 adds one important refinement to that split: some visual qualities have
-become hard, computable route-contract assertions for graph-projected families
-(flowchart, state, architecture). Hitches, diagonal routed segments,
-off-outline endpoints, edge-through-node routes, label-off-route ambiguity, and
-stale straight-route certificates are no longer mere approval signals there;
-they are correctness failures in `layout-rubric.test.ts` and
-`contact-sheet.test.ts`. The characterisation suite therefore treats those
-tests as the correctness layer and uses this directory to record approved
-observable baselines around it.
-
----
-
-## Tier A — universal invariants
-
-| ID | Property | Statement (holds ∀ valid input) | Kills mutants in |
-|----|----------|----------------------------------|------------------|
-| **P1** | Totality | `render(src)` never throws and is non-empty. | A\* iteration cap (`pathfinder.ts`), multi-pass safety break (`grid.ts:582`), index guards |
-| **P2** | Determinism | `render(src)` is byte-identical across runs. | MinHeap FIFO tie-break (`pathfinder.ts:16-27,60-63`), label/segment tie-breaks (`edge-routing.ts:299-305`), stable root sort (`grid.ts:469-470`) |
-| **P3** | Orthogonality | Output contains no diagonal connector glyphs (`/ \ ╱ ╲`). | A\* move set (`pathfinder.ts:124-129`), `mergePath` (`pathfinder.ts:266-301`) |
-| **P4** | Rectangularity | Every output line has the same display width. | canvas sizing (`canvas.ts setCanvasSizeToGrid`), row/column padding (`grid.ts setColumnWidth`) |
-
-P2 is the **keystone**: it is what makes the golden/approval corpus
-(`src/__tests__/testdata/`) valid at all, and it is the property the whole
-determinism apparatus (FIFO heap `seq`, ELK-free pure code, insertion-ordered
-maps) exists to provide. P3 is the **defining** invariant — "orthogonal A\*
-router" *is* the algorithm; a diagonal is by definition a bug
-(`assertNoDiagonals`, `validate.ts`).
-
-## Tier B — structural properties (trees & chains)
-
-| ID | Property | Statement | Scope | Kills mutants in |
-|----|----------|-----------|-------|------------------|
-| **P5** | Node conservation | Every declared node is drawn. | out-trees | placement multi-pass (`grid.ts:515-583`) |
-| **P6** | Box non-overlap | Drawn node boxes are pairwise disjoint. | out-trees | 3×3 reservation + stride-4 collision shift (`grid.ts:76-104`) |
-| **P7** | Monotone layering | For each forward edge `u→v`, `v`'s box is strictly downstream of `u` on the flow axis (below for TD, right for LR). | trees | layer stride (`grid.ts:539`), flow-axis direction (`grid.ts:496-571`) |
-| **P8** | Structural round-trip | `asciiToMermaid(render(chain))` recovers the same node and edge counts. | linear chains | edge emission (`converter.ts`), routing reaching endpoints (`edge-routing.ts:222-228`) |
-
-P7 is the **Sugiyama layer-assignment essence** in character space: it is the
-single property that says "this is a layered downward/rightward drawing." P8 is
-the only property that checks **edges connect the right endpoints** end-to-end,
-dogfooding the repo's own documented round-trip contract (`reverse.ts`).
-
-## Tier C — metamorphic relations & known limits
-
-| ID | Property | Statement | Pins |
-|----|----------|-----------|------|
-| **P9a** | BT = flip(TD) | An ASCII BT render equals the vertical flip (with arrowhead remap) of the TD render. | `index.ts:179-194` (BT laid out as TD then flipped) |
-| **P9b** | RL = LR | An RL render is byte-identical to the LR render. | `index.ts:179-181` (RL "not yet implemented", treated as LR) |
-| **P9c** | Relabel invariance | Replacing labels with same-length labels leaves the layout skeleton unchanged. | placement depends on label *width*, not identity |
-| **P10** | Known limit | A 2-cycle does **not** conserve all nodes (P5 fails). | placement multi-pass safety break (`grid.ts:582`) — pins that this is *currently* lossy |
-
-P9b and P10 are "canary" characterisations: they currently pin a *limitation*.
-If someone implements real RL support or makes cyclic placement lossless, these
-tests flip — which is exactly when a human should look and re-approve.
-
----
-
-## Renderer-family breadth properties
-
-These properties answer the "all renderers" part of the prompt. They do **not**
-claim that every renderer shares the grid algorithm's structural invariants;
-sequence, class, ER, timeline, journey, xychart, pie, quadrant, and
-architecture each have their own layout strategy. Instead, they pin the
-cross-family contracts that make the render surface usable and refactorable.
-
-| ID | Property | Statement | Scope |
-|----|----------|-----------|-------|
-| **F1** | Dispatch totality | Each of the 12 built-in families renders non-empty text/SVG and a valid PNG signature. | flowchart, state, sequence, class, ER, timeline, gantt, journey, xychart, pie, quadrant, architecture |
-| **F2** | Sentinel label conservation | Representative labels survive on the text and SVG surfaces, proving family dispatch did not fall through to an empty/adjacent renderer. | all 12 families |
-| **F3** | Renderer determinism | Representative text, SVG, and PNG renders are byte-stable across repeated calls. | all 12 families |
-| **F4** | Output hygiene | Plain text has no ANSI escapes when color is disabled, and text/SVG do not leak `NaN`, `Infinity`, or `undefined`. | all 12 families |
-| **F5** | Text orthogonality / block-only output | Generated text renders contain no diagonal connector glyphs. | all non-grid families, with flowchart/state covered by P3 |
-| **F6** | Rectangularity boundary | Rectangular text output holds for box/graph families only; chart/list/architecture families are intentionally ragged. | sequence, class, ER are rectangular; pie pins the ragged boundary |
-
-F1-F4 are finite matrix properties because the renderer surface is a dispatch
-contract: one canonical specimen per family catches missing switch branches,
-misdetected families, broken PNG rasterization, and accidental text/SVG leakage.
-F5-F6 are generated where a family has a compact valid-input generator and the
-invariant is meaningful.
-
----
-
-## Visual-quality approval signals
-
-The graph-drawing literature treats crossings, bends, route length, canvas area,
-and label overlap as aesthetic objectives or optimization costs. They are
-important, but they are not invariant in the same way as totality,
-determinism, or orthogonality. PR 30's route-contract work promoted a subset of
-these signals to hard checks when a clear geometric contract exists; the
-remaining cross-family metrics stay in a generated approval artifact instead of
-being folded into the minimal PBT kernel:
-
-| ID | Signal | What changes mean |
-|----|--------|-------------------|
-| **V1** | SVG snapshots | Human-visible visual drift in any renderer family. |
-| **V2** | SVG/PNG fingerprints | Byte-level drift on both vector and raster public surfaces. |
-| **V3** | Quality metrics | Changes in crossings, bends, route length, area fill, label fit, or edge-label overlap risk. |
-| **V4** | Generator drift check | A stale contact sheet or visual report fails `characterization-generated-artifacts.test.ts` / `bun run characterization:check`. |
-
-These signals should trigger review, not panic. A quality metric can improve,
-degrade, or simply change because a layout strategy changed. The review question
-is whether the new visual behaviour is intended and whether the generated
-artifact was updated deliberately.
-
-The PR 30 rebase is the model case. The generated-artifact check identified
-only the flowchart and state snapshots as stale after the route-contract merge,
-which matches the observed layout surface of that PR in this canonical family
-set. Drift in class, ER, sequence, chart, pie, quadrant, timeline, journey, or
-architecture snapshots would have required a separate explanation unless the PR
-explicitly claimed and reviewed that family. Architecture is graph-projected
-through route contracts, so the important fact here is not that PR 30 could
-never affect it; it is that this rebase did not.
-
----
-
-## <a id="minimality"></a>Minimality: why this set, and no smaller
-
-The target is *the smallest set of properties whose removal lets a previously
-killed mutant survive* (the operational definition of "load-bearing" from
-property-based mutation testing, Bartocci et al. 2023). The reasoning per
-property:
-
-- Drop **P2 (determinism)** → a mutant that swaps the deterministic heap
-  tie-break for an order-dependent one survives every other property (output is
-  still total, orthogonal, rectangular, correctly shaped) but breaks the golden
-  corpus non-reproducibly. Only P2 catches it.
-- Drop **P3 (orthogonality)** → a mutant adding a diagonal A\* move survives P1/P2/P4
-  (still total, deterministic, rectangular) but produces `\`/`/`. Only P3 catches it.
-- Drop **P4 (rectangularity)** → an off-by-one in row/column padding can ragged-edge
-  the canvas while staying total, deterministic, and diagonal-free.
-- Drop **P7 (monotone layering)** → a mutant that flips the flow axis or zeroes the
-  `+4` level stride still renders *something* total/orthogonal/rectangular;
-  P5/P6 (conservation, non-overlap) can still hold. Only P7 sees that children
-  no longer go downstream of parents.
-- Drop **P8 (round-trip)** → a mutant that drops or duplicates an edge keeps every
-  geometric invariant; only the end-to-end node/edge-count check notices.
-- Drop **P5/P6** → conservation and non-overlap are independent failure modes
-  (a node can be dropped *or* two boxes can collide); neither implies the other.
-- Drop **P9a/P9c** → BT-flip and relabel mutants are otherwise invisible: a broken
-  flip still yields a valid TD-shaped diagram; a label leaking into placement
-  still yields a valid diagram for the original labels.
-- **P1 (totality)** is the cheap floor that every other property silently assumes
-  (they can't assert on a throw).
-- Drop **F1/F2** → a renderer-family dispatch branch can disappear, fall through,
-  or return a placeholder while the deep grid tests remain green.
-- Drop **F3/F4** → renderer-specific nondeterminism or leaked layout sentinels can
-  escape outside the grid engine, invalidating contact sheets, snapshots, and PNG
-  raster output.
-- Drop **F5/F6** → the breadth layer stops recording which text renderers share
-  the grid-like contracts and which intentionally do not.
-
-Conversely, the set does **not** include redundant properties:
-
-- "Edges are 4-adjacent paths" is already implied by **P3** at the output level.
-- "Same-level nodes share a flow-axis coordinate" is the converse of **P7** and is
-  not independently load-bearing for trees.
-- Crossing count / edge length / compactness are **quality heuristics**, not
-  invariants — asserting exact values is brittle and they are intentionally
-  left to the visual approval layer, not this kernel.
-
-The unit-level A\* invariants (shortest Manhattan path on an empty grid,
-obstacle avoidance, `mergePath` idempotence, bounded search) are *also*
-load-bearing but already covered by the existing
-[`property-ascii-routing.test.ts`](../../src/__tests__/property-ascii-routing.test.ts);
-this kernel deliberately sits one level up, at the whole-render contract, to
-avoid duplicating them.
-
----
-
-## Academic grounding (one line each)
-
-- **Layered drawing / Sugiyama–Tagawa–Toda (1981); Gansner et al. (1993, `dot`).**
-  The 4-phase model (cycle removal → layer assignment → crossing minimisation →
-  coordinate assignment) this algorithm approximates on a character grid; P7 is
-  the layer-assignment phase made observable.
-- **Brandes–Köpf (2002).** Horizontal coordinate assignment with a hard "≤2
-  bends per edge" bound — an example of an invariant that *is* assertable, vs.
-  crossing count which is not.
-- **Hart, Nilsson & Raphael (1968), A\*.** `f = g + h`; the router's heuristic is
-  Manhattan distance plus a `+1` corner penalty (prefers straight runs).
-- **Tamassia (1968→1987) bend minimisation; Wybrow–Marriott–Stuckey (2009)
-  Orthogonal Connector Routing.** Orthogonality (P3) is a hard invariant of the
-  search space; bend/length minimisation are *objectives* (penalties), not
-  invariants — hence not asserted exactly.
-- **Feathers (2004), characterisation tests; Falco, approval/golden tests.** The
-  whole framing: pin actual behaviour, review diffs, approve changes.
-- **Bartocci et al. (2023), property-based mutation testing.** The "load-bearing
-  = kills a unique mutant" criterion used in [§ Minimality](#minimality);
-  Stryker (`stryker.characterization.config.json` for fast PR evidence,
-  `stryker.ascii.config.json` for the exhaustive run) is the tool that can
-  verify it.
-
-The fast characterization Stryker config is a smoke gate over selected mutation
-ranges, not a substitute for the exhaustive ASCII run. Surviving mutants in the
-smoke report are useful backlog signals for future deeper characterisation; the
-full ASCII config remains the expensive overnight-style audit.
-
-## How to use this
-
-```bash
-# Run the characterisation kernels
-bun test src/__tests__/characterization-layout.test.ts
-bun test src/__tests__/characterization-families.test.ts
-
-# Verify PR 30 route-contract correctness before approving visual drift
-bun test src/__tests__/contact-sheet.test.ts src/__tests__/layout-rubric.test.ts
-bun run track
-
-# Regenerate the worked-examples contact sheets (approval workflow)
-bun run scripts/characterization/contact-sheet.ts
-bun run scripts/characterization/contact-sheet-families.ts
-bun run scripts/characterization/visual-quality.ts
-
-# CI-friendly generated-artifact drift check
-bun run characterization:check
-
-# Quick mutation evidence for the load-bearing ranges
-bun run mutation-test:characterization
-
-# Exhaustive but slow: mutates the whole ASCII layout core
-bun run mutation-test:ascii
-```

package/docs/layout-characterization/visual-quality.md

@@ -1,160 +0,0 @@
-# Visual quality characterisation
-
-> Generated by `scripts/characterization/visual-quality.ts`. Do not edit by hand.
-
-This is the approval layer for visual/layout quality. The SVG files are
-human-inspectable snapshots; the hashes fingerprint the SVG and PNG surfaces;
-the metrics are graph-drawing review signals (crossings, bends, canvas area,
-label fit, and label-overlap risk), not standalone correctness laws.
-For graph-projected route correctness, pair this report with PR 30's hard
-gates: `src/__tests__/contact-sheet.test.ts`,
-`src/__tests__/layout-rubric.test.ts`, and `bun run track`.
-
-| Family | SVG snapshot | SVG SHA | PNG SHA | PNG bytes | SVG size | Layout bounds | Nodes/edges | Crossings | Bends | Route px | Area fill | Label fit | Label overlaps | Edge-label clearance | Aspect |
-|--------|--------------|---------|---------|----------:|----------|---------------|-------------|----------:|------:|---------:|----------:|----------:|---------------:|---------------------:|-------:|
-| Flowchart | [flowchart.svg](./visual-snapshots/flowchart.svg) | `ec1b1ca9443d` | `115eeaf5a982` | 9018 | 279.6835x434.582 | 280x435 | 4/4 | 0 | 0 | 533 | 15.5% | 100.0% | 0 | 7 | 0.64 |
-| State diagram | [state.svg](./visual-snapshots/state.svg) | `8e9deb92ba71` | `171ef8b10734` | 7326 | 241.14266666666668x375.15000000000003 | 241x375 | 5/5 | 0 | 6 | 628 | 11.3% | 100.0% | 0 | n/a | 0.64 |
-| Sequence diagram | [sequence.svg](./visual-snapshots/sequence.svg) | `23717c64433e` | `fc934d1a2e01` | 7135 | 420x280 | 420x280 | 3/4 | 0 | 0 | 560 | 8.2% | 100.0% | 0 | 10 | 1.50 |
-| Class diagram | [class.svg](./visual-snapshots/class.svg) | `d14da80c1cb7` | `ea089943c1dc` | 3950 | 360x237.8 | 360x238 | 3/2 | 0 | 2 | 240 | 20.6% | 100.0% | 0 | n/a | 1.51 |
-| ER diagram | [er.svg](./visual-snapshots/er.svg) | `be65847067be` | `e16cb6c925da` | 9649 | 951.768x136 | 952x136 | 3/2 | 0 | 0 | 452 | 18.2% | 100.0% | 0 | 115 | 7.00 |
-| Timeline | [timeline.svg](./visual-snapshots/timeline.svg) | `c07cd647b657` | `c01793e9745b` | 8031 | 380x286.6 | 380x287 | 4/0 | 0 | 0 | 0 | 13.2% | 100.0% | 0 | n/a | 1.32 |
-| Gantt chart | [gantt.svg](./visual-snapshots/gantt.svg) | `784dedd3d334` | `21ee1716da07` | 9321 | 703x282 | 703x282 | 4/0 | 0 | 0 | 0 | 6.9% | 75.0% | 0 | n/a | 2.49 |
-| User journey | [journey.svg](./visual-snapshots/journey.svg) | `b47e71e142ea` | `3069450b8529` | 15279 | 530x482.3 | 530x482 | 2/0 | 0 | 0 | 0 | 5.9% | 100.0% | 0 | n/a | 1.10 |
-| XY chart | [xychart.svg](./visual-snapshots/xychart.svg) | `bdcb4e4ce1b2` | `d7df7b4f86de` | 15427 | 700x500 | 700x500 | 6/0 | 0 | 0 | 0 | 37.6% | 50.0% | 0 | n/a | 1.40 |
-| Pie chart | [pie.svg](./visual-snapshots/pie.svg) | `fc3f5d7bfc34` | `dde9d49be7a7` | 10784 | 368.79x276 | 369x276 | 3/0 | 0 | 0 | 0 | 4.1% | 100.0% | 0 | n/a | 1.34 |
-| Quadrant chart | [quadrant.svg](./visual-snapshots/quadrant.svg) | `d75d9de8aea3` | `63b16868b93e` | 9305 | 456x492 | 456x492 | 2/0 | 0 | 0 | 0 | 0.1% | 100.0% | 0 | n/a | 0.93 |
-| Architecture diagram | [architecture.svg](./visual-snapshots/architecture.svg) | `56fce2e98409` | `777507a15f7a` | 4182 | 414x188 | 414x188 | 2/1 | 0 | 0 | 78 | 14.8% | 100.0% | 0 | n/a | 2.20 |
-
-## Sources
-
-### Flowchart
-
-```mermaid
-graph TD
-  Start[Start] --> Check{Check}
-  Check -->|yes| Done[Done]
-  Check -->|no| Retry[Retry]
-  Retry --> Check
-```
-
-### State diagram
-
-```mermaid
-stateDiagram-v2
-  [*] --> Idle
-  Idle --> Running
-  Running --> Failed
-  Failed --> Idle
-  Running --> [*]
-```
-
-### Sequence diagram
-
-```mermaid
-sequenceDiagram
-  participant Alice
-  participant Bob
-  participant DB
-  Alice->>Bob: Request
-  Bob->>DB: Query
-  DB-->>Bob: Rows
-  Bob-->>Alice: Response
-```
-
-### Class diagram
-
-```mermaid
-classDiagram
-  class Animal
-  class Dog
-  class Cat
-  Animal <|-- Dog
-  Animal <|-- Cat
-```
-
-### ER diagram
-
-```mermaid
-erDiagram
-  CUSTOMER ||--o{ ORDER : places
-  ORDER ||--|{ LINE_ITEM : contains
-```
-
-### Timeline
-
-```mermaid
-timeline
-  title Release Plan
-  section Build
-    2025 : Prototype
-    2026 : Launch
-```
-
-### Gantt chart
-
-```mermaid
-gantt
-  title Launch plan
-  dateFormat YYYY-MM-DD
-  axisFormat %b %d
-  excludes weekends
-  section Build
-    Spec :done, spec, 2024-01-01, 2d
-    Implement :active, impl, after spec, 3d
-  section Ship
-    QA :crit, qa, after impl, 2d
-    Launch :milestone, launch, after qa, 0d
-    Release line :vert, release, 2024-01-10, 0d
-```
-
-### User journey
-
-```mermaid
-journey
-  title Checkout
-  section Cart
-    Review basket: 4: Shopper
-    Pay: 5: Shopper
-```
-
-### XY chart
-
-```mermaid
-xychart
-  title Sales
-  x-axis [Jan, Feb, Mar]
-  y-axis Revenue 0 --> 10
-  bar [3, 7, 5]
-  line [2, 6, 8]
-```
-
-### Pie chart
-
-```mermaid
-pie title Pets
-  "Cats" : 4
-  "Dogs" : 6
-  "Birds" : 2
-```
-
-### Quadrant chart
-
-```mermaid
-quadrantChart
-  title Priorities
-  x-axis Low --> High
-  y-axis Risk --> Reward
-  quadrant-1 Invest
-  A: [0.7, 0.8]
-  B: [0.3, 0.4]
-```
-
-### Architecture diagram
-
-```mermaid
-architecture-beta
-  group api(cloud)[API]
-  service app(server)[App] in api
-  service db(database)[DB]
-  app:R --> L:db
-```

package/docs/layout-characterization/visual-snapshots/architecture.svg

@@ -1,79 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 414 188" width="414" height="188" style="--bg:#FFFFFF;--fg:#27272A;--font:Inter;background:#FFFFFF">
-<style>
-  text { font-family: var(--font, 'Inter'), system-ui, sans-serif; }
-  svg {
-    /* Derived from --bg and --fg (overridable via --line, --accent, etc.) */
-    --_text:          #27272A;
-    --_text-sec:      #575759;
-    --_text-muted:    #707072;
-    --_text-faint:    #8a8a8c;
-    --_line:          #939395;
-    --_arrow:         #47474a;
-    --_node-fill:     #f9f9f9;
-    --_node-stroke:   #d4d4d4;
-    --_group-fill:    #FFFFFF;
-    --_group-hdr:     #f4f4f4;
-    --_inner-stroke:  #e5e5e5;
-    --_key-badge:     #e9e9ea;
-  }
-</style>
-<style>
-  .architecture-group-frame { fill: #fafafa; stroke: none; }
-  .architecture-group-band { fill: #f6f6f6; stroke: none; }
-  .architecture-group-outline { fill: none; stroke: #d4d4d4; stroke-width: 1; }
-  .architecture-group-label { fill: #575759; }
-  .architecture-service-card { fill: #f9f9f9; stroke: none; }
-  .architecture-service-outline { fill: none; stroke: #d4d4d4; stroke-width: 1; }
-  .architecture-service-label { fill: #27272A; }
-  .architecture-edge { fill: none; stroke: #939395; stroke-width: 1; stroke-linejoin: round; }
-  .architecture-edge-label-bg { fill: #fefefe; stroke: #ececec; stroke-width: 0.75; }
-  .architecture-edge-label-text { fill: #707072; }
-  .architecture-junction-ring { fill: #FFFFFF; stroke: #47474a; stroke-width: 1.25; }
-  .architecture-junction-core { fill: #d3d3d4; stroke: #47474a; stroke-width: 0.75; }
-  .architecture-icon-mark { fill: none; stroke: #47474a; stroke-width: 1.25; stroke-linecap: round; stroke-linejoin: round; }
-  .architecture-icon-glyph { fill: #47474a; }
-</style>
-<defs>
-  <marker id="char-architecture-architecture-arrow-end" markerWidth="8" markerHeight="5" refX="7" refY="2.5" orient="auto">
-    <polygon points="0 0, 8 2.5, 0 5" fill="#47474a" stroke="#47474a" stroke-width="0.75" stroke-linejoin="round" />
-  </marker>
-  <marker id="char-architecture-architecture-arrow-start" markerWidth="8" markerHeight="5" refX="1" refY="2.5" orient="auto-start-reverse">
-    <polygon points="8 0, 0 2.5, 8 5" fill="#47474a" stroke="#47474a" stroke-width="0.75" stroke-linejoin="round" />
-  </marker>
-</defs>
-<g class="architecture-group" data-id="api" data-label="API">
-  <rect class="architecture-group-frame" x="38" y="40" width="156" height="110" rx="0" ry="0" />
-  <path class="architecture-group-band" d="M38,40 H194 V68 H38 Z" />
-  <rect class="architecture-group-outline" x="38" y="40" width="156" height="110" rx="0" ry="0" />
-  <g class="architecture-icon" data-icon="cloud">
-  <circle class="architecture-icon-mark" cx="53.3504" cy="54.2944" r="2.3552" />
-<circle class="architecture-icon-mark" cx="56.2944" cy="52.8224" r="2.9440000000000004" />
-<circle class="architecture-icon-mark" cx="58.944" cy="54.2944" r="2.208" />
-<path class="architecture-icon-mark" d="M 50.9952 56.355199999999996 H 60.8576" />
-</g>
-  <text x="74" y="54" class="architecture-group-label" text-anchor="start" font-size="12" font-weight="600" dy="4.199999999999999">API</text>
-</g>
-<polyline class="architecture-edge" data-from="app" data-to="db" data-from-side="R" data-to-side="L" data-from-boundary="item" data-to-boundary="item" points="176,108 254,108" marker-end="url(#char-architecture-architecture-arrow-end)" />
-<g class="architecture-service" data-id="db" data-label="DB">
-  <rect class="architecture-service-card" x="254" y="84" width="120" height="48" rx="0" ry="0" />
-  <rect class="architecture-service-outline" x="254" y="84" width="120" height="48" rx="0" ry="0" />
-  <g class="architecture-icon" data-icon="database">
-  <ellipse class="architecture-icon-mark" cx="283" cy="105.12" rx="4.32" ry="1.8" />
-<path class="architecture-icon-mark" d="M 278.68 105.12 V 111.6" />
-<path class="architecture-icon-mark" d="M 287.32 105.12 V 111.6" />
-<ellipse class="architecture-icon-mark" cx="283" cy="108.36" rx="4.32" ry="1.8" />
-<ellipse class="architecture-icon-mark" cx="283" cy="111.6" rx="4.32" ry="1.8" />
-</g>
-  <text x="306" y="108" class="architecture-service-label" text-anchor="start" font-size="13" font-weight="500" dy="4.55">DB</text>
-</g>
-<g class="architecture-service" data-id="app" data-label="App">
-  <rect class="architecture-service-card" x="56" y="84" width="120" height="48" rx="0" ry="0" />
-  <rect class="architecture-service-outline" x="56" y="84" width="120" height="48" rx="0" ry="0" />
-  <g class="architecture-icon" data-icon="server">
-  <rect class="architecture-icon-mark" x="81.04" y="103.68" width="7.92" height="8.64" rx="0" ry="0" />
-<path class="architecture-icon-mark" d="M 82.12 106.56 H 87.88" />
-<path class="architecture-icon-mark" d="M 82.12 109.08 H 87.88" />
-</g>
-  <text x="108" y="108" class="architecture-service-label" text-anchor="start" font-size="13" font-weight="500" dy="4.55">App</text>
-</g>
-</svg>

package/docs/layout-characterization/visual-snapshots/class.svg

@@ -1,60 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 237.8" width="360" height="237.8" style="--bg:#FFFFFF;--fg:#27272A;--font:Inter;background:#FFFFFF">
-<style>
-  text { font-family: var(--font, 'Inter'), system-ui, sans-serif; }
-  .mono { font-family: 'JetBrains Mono', 'SF Mono', 'Fira Code', ui-monospace, monospace; }
-  svg {
-    /* Derived from --bg and --fg (overridable via --line, --accent, etc.) */
-    --_text:          #27272A;
-    --_text-sec:      #575759;
-    --_text-muted:    #707072;
-    --_text-faint:    #8a8a8c;
-    --_line:          #939395;
-    --_arrow:         #47474a;
-    --_node-fill:     #f9f9f9;
-    --_node-stroke:   #d4d4d4;
-    --_group-fill:    #FFFFFF;
-    --_group-hdr:     #f4f4f4;
-    --_inner-stroke:  #e5e5e5;
-    --_key-badge:     #e9e9ea;
-  }
-</style>
-<defs>
-  <marker id="char-class-cls-inherit" markerWidth="12" markerHeight="10" refX="12" refY="5" orient="auto-start-reverse">
-    <polygon points="0 0, 12 5, 0 10" fill="#FFFFFF" stroke="#47474a" stroke-width="1.5" />
-  </marker>
-  <marker id="char-class-cls-composition" markerWidth="12" markerHeight="10" refX="0" refY="5" orient="auto-start-reverse">
-    <polygon points="6 0, 12 5, 6 10, 0 5" fill="#47474a" stroke="#47474a" stroke-width="1" />
-  </marker>
-  <marker id="char-class-cls-aggregation" markerWidth="12" markerHeight="10" refX="0" refY="5" orient="auto-start-reverse">
-    <polygon points="6 0, 12 5, 6 10, 0 5" fill="#FFFFFF" stroke="#47474a" stroke-width="1.5" />
-  </marker>
-  <marker id="char-class-cls-arrow" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto-start-reverse">
-    <polyline points="0 0, 8 3, 0 6" fill="none" stroke="#47474a" stroke-width="1.5" />
-  </marker>
-</defs>
-<polyline class="class-relationship" data-from="Animal" data-to="Dog" data-type="inheritance" data-marker-at="from" points="100,88.9 100,148.9" fill="none" stroke="#939395" stroke-width="1" marker-start="url(#char-class-cls-inherit)" />
-<polyline class="class-relationship" data-from="Animal" data-to="Cat" data-type="inheritance" data-marker-at="from" points="140,88.9 140,98.9 260,98.9 260,148.9" fill="none" stroke="#939395" stroke-width="1" marker-start="url(#char-class-cls-inherit)" />
-<g class="class-node" data-id="Animal" data-label="Animal">
-  <rect x="60" y="40" width="120" height="48.900000000000006" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="1" />
-  <path d="M60,40 H180 V72.9 H60 Z" fill="#f4f4f4" stroke="#d4d4d4" stroke-width="1" />
-  <text x="120" y="56.45" text-anchor="middle" font-size="13" font-weight="700" fill="#27272A" dy="4.55">Animal</text>
-  <line x1="60" y1="72.9" x2="180" y2="72.9" stroke="#d4d4d4" stroke-width="0.75" />
-  <line x1="60" y1="80.9" x2="180" y2="80.9" stroke="#d4d4d4" stroke-width="0.75" />
-</g>
-<g class="class-node" data-id="Dog" data-label="Dog">
-  <rect x="40" y="148.9" width="120" height="48.900000000000006" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="1" />
-  <path d="M40,148.9 H160 V181.8 H40 Z" fill="#f4f4f4" stroke="#d4d4d4" stroke-width="1" />
-  <text x="100" y="165.35000000000002" text-anchor="middle" font-size="13" font-weight="700" fill="#27272A" dy="4.55">Dog</text>
-  <line x1="40" y1="181.8" x2="160" y2="181.8" stroke="#d4d4d4" stroke-width="0.75" />
-  <line x1="40" y1="189.8" x2="160" y2="189.8" stroke="#d4d4d4" stroke-width="0.75" />
-</g>
-<g class="class-node" data-id="Cat" data-label="Cat">
-  <rect x="200" y="148.9" width="120" height="48.900000000000006" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="1" />
-  <path d="M200,148.9 H320 V181.8 H200 Z" fill="#f4f4f4" stroke="#d4d4d4" stroke-width="1" />
-  <text x="260" y="165.35000000000002" text-anchor="middle" font-size="13" font-weight="700" fill="#27272A" dy="4.55">Cat</text>
-  <line x1="200" y1="181.8" x2="320" y2="181.8" stroke="#d4d4d4" stroke-width="0.75" />
-  <line x1="200" y1="189.8" x2="320" y2="189.8" stroke="#d4d4d4" stroke-width="0.75" />
-</g>
-
-
-</svg>

package/docs/layout-characterization/visual-snapshots/er.svg

@@ -1,61 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 951.768 136" width="951.768" height="136" style="--bg:#FFFFFF;--fg:#27272A;--font:Inter;background:#FFFFFF">
-<style>
-  text { font-family: var(--font, 'Inter'), system-ui, sans-serif; }
-  .mono { font-family: 'JetBrains Mono', 'SF Mono', 'Fira Code', ui-monospace, monospace; }
-  svg {
-    /* Derived from --bg and --fg (overridable via --line, --accent, etc.) */
-    --_text:          #27272A;
-    --_text-sec:      #575759;
-    --_text-muted:    #707072;
-    --_text-faint:    #8a8a8c;
-    --_line:          #939395;
-    --_arrow:         #47474a;
-    --_node-fill:     #f9f9f9;
-    --_node-stroke:   #d4d4d4;
-    --_group-fill:    #FFFFFF;
-    --_group-hdr:     #f4f4f4;
-    --_inner-stroke:  #e5e5e5;
-    --_key-badge:     #e9e9ea;
-  }
-</style>
-<defs>
-</defs>
-<polyline class="er-relationship" data-entity1="CUSTOMER" data-entity2="ORDER" data-cardinality1="one" data-cardinality2="zero-many" data-identifying="true" data-label="places" points="180,68 401.726,68" fill="none" stroke="#939395" stroke-width="1" />
-<polyline class="er-relationship" data-entity1="ORDER" data-entity2="LINE_ITEM" data-cardinality1="one" data-cardinality2="many" data-identifying="true" data-label="contains" points="541.726,68 771.768,68" fill="none" stroke="#939395" stroke-width="1" />
-<g class="entity" data-id="CUSTOMER" data-label="CUSTOMER">
-  <rect x="40" y="40" width="140" height="56" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="1" />
-  <path d="M40,40 H180 V74 H40 Z" fill="#f4f4f4" stroke="#d4d4d4" stroke-width="1" />
-  <text x="110" y="57" text-anchor="middle" font-size="13" font-weight="700" fill="#27272A" dy="4.55">CUSTOMER</text>
-  <line x1="40" y1="74" x2="180" y2="74" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="110" y="85" text-anchor="middle" dy="0.35em" font-size="11" fill="#8a8a8c" font-style="italic">(no attributes)</text>
-</g>
-<g class="entity" data-id="ORDER" data-label="ORDER">
-  <rect x="401.726" y="40" width="140" height="56" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="1" />
-  <path d="M401.726,40 H541.726 V74 H401.726 Z" fill="#f4f4f4" stroke="#d4d4d4" stroke-width="1" />
-  <text x="471.726" y="57" text-anchor="middle" font-size="13" font-weight="700" fill="#27272A" dy="4.55">ORDER</text>
-  <line x1="401.726" y1="74" x2="541.726" y2="74" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="471.726" y="85" text-anchor="middle" dy="0.35em" font-size="11" fill="#8a8a8c" font-style="italic">(no attributes)</text>
-</g>
-<g class="entity" data-id="LINE_ITEM" data-label="LINE_ITEM">
-  <rect x="771.768" y="40" width="140" height="56" rx="0" ry="0" fill="#f9f9f9" stroke="#d4d4d4" stroke-width="1" />
-  <path d="M771.768,40 H911.768 V74 H771.768 Z" fill="#f4f4f4" stroke="#d4d4d4" stroke-width="1" />
-  <text x="841.768" y="57" text-anchor="middle" font-size="13" font-weight="700" fill="#27272A" dy="4.55">LINE_ITEM</text>
-  <line x1="771.768" y1="74" x2="911.768" y2="74" stroke="#d4d4d4" stroke-width="0.75" />
-  <text x="841.768" y="85" text-anchor="middle" dy="0.35em" font-size="11" fill="#8a8a8c" font-style="italic">(no attributes)</text>
-</g>
-<line x1="184" y1="62" x2="184" y2="74" stroke="#939395" stroke-width="1.25" />
-<line x1="188" y1="62" x2="188" y2="74" stroke="#939395" stroke-width="1.25" />
-<line x1="397.726" y1="75" x2="385.726" y2="68" stroke="#939395" stroke-width="1.25" />
-<line x1="397.726" y1="68" x2="385.726" y2="68" stroke="#939395" stroke-width="1.25" />
-<line x1="397.726" y1="61" x2="385.726" y2="68" stroke="#939395" stroke-width="1.25" />
-<circle cx="381.726" cy="68" r="4" fill="#FFFFFF" stroke="#939395" stroke-width="1.25" />
-<line x1="545.726" y1="62" x2="545.726" y2="74" stroke="#939395" stroke-width="1.25" />
-<line x1="549.726" y1="62" x2="549.726" y2="74" stroke="#939395" stroke-width="1.25" />
-<line x1="767.768" y1="75" x2="755.768" y2="68" stroke="#939395" stroke-width="1.25" />
-<line x1="767.768" y1="68" x2="755.768" y2="68" stroke="#939395" stroke-width="1.25" />
-<line x1="767.768" y1="61" x2="755.768" y2="68" stroke="#939395" stroke-width="1.25" />
-<rect x="270" y="57.85" width="41.726000000000006" height="20.3" rx="2" ry="2" fill="#FFFFFF" stroke="#e5e5e5" stroke-width="0.5" />
-<text x="290.863" y="68" text-anchor="middle" font-size="11" font-weight="400" fill="#707072" dy="3.8499999999999996">places</text>
-<rect x="631.7260000000001" y="57.85" width="50.04200000000001" height="20.3" rx="2" ry="2" fill="#FFFFFF" stroke="#e5e5e5" stroke-width="0.5" />
-<text x="656.7470000000001" y="68" text-anchor="middle" font-size="11" font-weight="400" fill="#707072" dy="3.8499999999999996">contains</text>
-</svg>