# Quality and acceptance criteria

Status: target acceptance specification, 2026-09-08. All five forms have limited-scope implementations and tests; this does not establish quality guarantees for arbitrary inputs or every client.

## Common gates

- Semantic fidelity: preserve identities, endpoints, relation types and directions, groups, and reading order; do not silently omit or truncate content.
- Complete text: no container clipping or unreadable overlap; measure long text and mixed English/Chinese content for the display environment.
- Clear graphics: labels must not obscure arrows, connectors must not cross unrelated nodes, and endpoints must be identifiable. Necessary crossings should be distinguishable; do not promise zero crossings for arbitrary graphs.
- Correct form: layout must not change tree hierarchy, pseudocode branch ownership, or diff addition/deletion semantics.
- Explicit environment: record the renderer, dimensions, fonts, and other conditions affecting the result.
- Terminating repair: the loop has a budget; distinguish passing, failing, and unsupported cases.
- Reproducibility: identical inputs and environments produce stable results; record initial defects, repairs, and final checks.

## Failure examples and existing evidence

| Example | Expected result | Current evidence / gap |
| --- | --- | --- |
| Card ID is `note-1` or `derived-legend` | Arrows point only to the Card | Endpoint-collision regression in `test/render.test.mjs` |
| Relation labels contain `&`, `"`, `|`, or Chinese text | No lost relations or invented nodes | Text-preservation checks for four relation kinds in `test/mermaid.test.mjs` |
| Card/Relation IDs contain surrounding whitespace | Endpoints remain consistent after normalization | Covered by Mermaid regressions |
| Horizontal flow between Cards of different heights | No meaningless short dogleg | `fixtures/horizontal-dogleg-regression.json` and horizontal-connector tests |
| A Stack directly contains another Stack | Reading direction and structure are preserved | The legacy path diagnoses and falls back to PNG; automatic Mermaid repair for this input remains incomplete |
| Complex diagrams reach 176/360 columns | Automatic repair and acceptance in the declared environment | Reproducible with the two complex fixtures; the legacy path only detects width and falls back |
| A label covers an arrow | Automatic avoidance makes both readable | HTML sequence tests in `test/show-me.test.mjs` verify single-call repair and final HTML reinspection; general routing remains incomplete |
| Connectors cross unrelated nodes / nodes overlap | Automatic avoidance, spacing adjustments, and reinspection | Native Mermaid has geometry checks and bounded reflow; path checks are sampled, not a guarantee for arbitrary graphs |
| Long labels, mixed-language widths, deep trees | Full text and hierarchy survive | Text-tree tests cover Unicode grapheme wrapping, hierarchy prefixes, reconstruction, and explicit limit failures |
| Pseudocode branches and long diff lines | No branch-ownership or addition/deletion changes | Pseudocode tests cover nested branches and loops; diff tests cover patch application and a separate wrapped view |
| Complex HTML in narrow and wide windows | No clipping or occlusion; relationships remain clear | Simple HTML sequences are verified; complex responsive layout is not implemented |

Run `npm test`. The current baseline has 31 local tests covering legacy MCP, HTML, the four built-in forms, and delivered files. The full suite requires local Chromium and runs test files serially to prevent browser/rasterizer contention from causing protocol timeouts. Test count is not a completion metric.

## Record for each acceptance run

1. Input fixture, selected form, and required semantic invariants.
2. Display environment and tool versions.
3. Initial defects and reproducible checks.
4. Repairs actually performed and budget consumed.
5. Final artifact, automated checks, and any necessary visual review.
6. Whether the agent had to intervene in layout, plus remaining limitations.

Mark unverified surfaces as UNKNOWN. A PNG file does not establish visual acceptance; a passing Pi parser does not establish an interactive Pi window check; local tests do not establish CI, release, or all-client acceptance.

## Extension acceptance

The following are extension goals. Current tests cover adding/removing the declarative example library, shared validation, discovery, duplicate identities, missing elements, and input schemas. Arbitrary UI components, resource changes, dynamic loading, and cross-client reproduction remain uncovered:

- Register, discover, use, and remove an example library outside the core source without modifying the engine.
- Default and example libraries use the same contract and quality workflow; one artifact can combine elements from both.
- Namespaces distinguish same-named elements. Missing libraries or incompatible versions produce explicit errors rather than substitution.
- Agents can discover custom element meanings, constraints, examples, and supported forms. Unsupported forms are not presented as supported.
- Long labels, font loading, or dimension changes in user components trigger measurement and avoidance again; third-party components cannot bypass final checks.
- Unmeasurable components, unsuccessful repairs, or unsupported environments cannot receive a quality pass.
- Record library, adaptation, and core versions; results must be reproducible for fixed inputs and environments.

## Implementation sequence

1. Complete the failure examples and define supported input sizes and environments. Turn pending examples into checks that can fail. Validate the extension seam with an independent library rather than hard-coding the default catalog.
2. Establish a complete detect → repair → recheck loop for the first selected defects, such as label occlusion, text overflow, or node overlap.
3. Extend each of the five forms with recipes, checks, repair strategies, and final display evidence.
4. Define verifiable Pi and desktop display paths and test client differences.
5. Complete remaining license, package-release, and Pi plugin distribution work. The repository is already public on GitHub.

This specification does not assume one layout engine for every form or PNG/Mermaid as the only artifact format.