merman 0.11.0
merman: ^0.11.0 copied to clipboard
Flutter and Dart FFI bindings for merman headless Mermaid rendering.
Changelog #
0.11.0 - 2026-11-21 #
Breaking changes #
- Upgrade the Dart package and its native assets together for ASCII output schema
4. InMermanAsciiOutputPlan, useprimaryOverflowedfor the nullable primary result andemittedOverflowedfor the actual text.primaryWidth,primaryHeight,layoutProfile, andprimaryOverflowedare null together when no primary layout was produced. ASCII report migration, #323
Added #
- Render more families as terminal diagrams, including Gantt timelines, GitGraph branches, and Packet bit grids. Set
ascii.graph_presentationtoadaptivewith Plain output to recover complete text records for supported graphs when routing runs out of search steps or ports. Terminal support matrix, #317, #323, #324 - Replay the Gantt Today Marker through binding options with a captured
fixed_unix_millisandfixed_local_offset_minutes. #312
Changed and fixed #
0.10.0 - 2026-11-12 #
Cumulative changes since the latest stable Flutter/Dart package, 0.9.3. See the stable upgrade guide for the complete migration.
| Upgrading from | Next step |
|---|---|
0.9.3 |
Apply the breaking changes below and refresh output snapshots. |
0.10.0-alpha.1 or alpha.2 |
Review the guide's remaining contract and theme-catalog changes. |
Breaking changes #
- Use Flutter
3.47.7+for Flutter apps; standalone Dart requires3.10+. Upgrade the Dart facade, acquisition manifest, and native assets together; regenerate matching helpers for custom builds. Native ABI remains3, andMerman.open()requires the exact package version. - Migrate Options JSON from schema
2to3: replacepresentationstyling with top-leveltheme, useraster.matteandpdf.page_paintfor custom export backgrounds, and remove retired presentation-profile and host-owned CSS/security fields. ReplacepresentationCatalog()withthemeCatalog(). - Update analysis-facts decoders from schema
2to3for required per-diagramappearancedeclarations with source provenance and UTF-8 byte spans. Render metadata separately usestheme_execution_evidence.version: 2with required nullablematerialized_theme; preserve unknown evidence versions as opaque data. #277 - Custom text measurers must handle
html-line-height(operation22) with a length result or leave it unhandled for fallback. Text-measurement protocol remains1. #249 - For
edge-geometry-json, replace operation-localmax_svg_byteswithmax_geometry_json_bytesand remove SVG-element/backend overrides. The geometry payload remains schema1; see the resource migration. - Handle formula rejection under
constrained, or chooseinteractiveor an appropriate trusted policy with host execution and memory limits. Compiled math does not relax resource admission.
Added #
- Apply optional themes from 11 design groups with 14 concrete presets, including
paper-cut,carbon-copy, andpop-art, or import editable JSON. Core colors and fonts reach all 34 diagram families, respecting source-owned styles and the typography used to measure labels. Presets retain alpha maturity; effects and output support depend on the family, shape, look, and target. See the theme guide and coverage limits. #178, #277, #299 - Keep light and dark appearances in one schema-1 recipe. Editor, Gruvbox, and Ayu are paired designs; catalog consumers read each design's appearances and concrete preset IDs.
exportThemePresetJsonandmaterializeThemeJsonoperations preserve editable recipes and validate every appearance. Resolve Follow-app policy in Dart before requestinglightordark. #284 - Build with a thin Dart package that downloads and verifies only the selected target's native library. Use
native_assets, amirror, orofflinewith prepared assets or a warm cache; deployed apps need no runtime download. The ordinary SVG assets include math, while PNG/JPEG/PDF encoders and system font discovery remain absent. New releases use the matching workspacev<version>Release; historical manifests retain their URLs. See the installation guide. #265, #266, #275
Changed and fixed #
- Refine Cyberpunk with clear neutral text and restrained neon contours, and Ghibli with warm paper, sage surfaces and independent chart inks. Both add dedicated Flowchart, Sequence and XY Chart styling while retaining editable recipe export. #302
- Advance from Mermaid
12.1.0to12.3.0, including timed Flowchart Step edges, numbered badges, ninebpmn-*shapes, and updated Swimlane and Usecase behavior. Static output retains Step edges and badges without browser animation. Review snapshots for ELK0.12.1routing, label clearance, containers, and packing; see the Mermaid migration. #277 - Correct Class, Sequence, and State source handling and label geometry; semantic/layout JSON preserves the selected Mermaid numeric behavior. ASCII Flowchart feedback edges route around occupied geometry, and Sequence accepts
andsections inpar_over. #282, #286, #287, #294, #297
0.10.0-alpha.2 - 2026-11-06 #
Changes since 0.10.0-alpha.1. See the host installation guide for independently verified package availability.
Breaking changes #
- Upgrade the Dart facade and pinned native assets together; regenerate matching Dart helpers for custom builds. Native ABI
3and Options JSON schema3are unchanged, but the JSON contracts below require matching wrapper/runtime artifacts. - Update analysis-facts decoders from schema
2to3. Every diagram requires anappearancesibling ofsyntax, taggedknownorunknown; known theme, font and look declarations include frontmatter/directive provenance and original diagram-local UTF-8 byte spans. Source declarations describe configuration, not the executed render. See the contract migration. #277 - Update custom render-metadata decoders for
theme_execution_evidence.version: 2and required nullablematerialized_theme, which records the Mermaid palette actually used. Preserve unknown evidence versions as opaque data; theme application and output-target admission remain separate checks. #277
Changed #
- Advance Mermaid compatibility from
12.2.0to12.3.0, adding timed Flowchart Step edges and numbered badges, ninebpmn-*Flowchart shapes, updated Swimlane behavior and Usecase Include/Extend labels. Animation is browser-only; static output keeps edges and badges. Review SVG/layout snapshots for the selected ELK0.12.1label clearance, compound-container, self-loop and packing behavior. See the Mermaid migration guide. #277 - Core theme colors and typography reach all 34 diagram families in the complete SVG product, including supported paint on BPMN event rings and annotation brackets. Effects remain specific to the family, shape, look and output; see the theme coverage guide. #277, #278
- Adapt 15 editable designs from the theme design gallery by passing the downloaded JSON as the
themevalue in Options JSON. These five-family examples are independent recipes; the built-in catalog remains at 11 presets. Fonts resolve on the host, and examples do not qualify every diagram or output. #279 - Native asset acquisition follows the manifest packaged with this Dart release. New workspace releases attach assets to the matching
v<version>Merman Release; custom mirrors should serve the manifest's asset names. Existing package versions retain their original download URLs. #275
Fixed #
- Preserve Flowchart source-class precedence over theme colors and fonts, and use supported source font sizes during label measurement. #278
- Avoid false strict-theme rejections when resetting supported Pie text styles or Architecture group colors to their defaults. #278
- Preserve supported inline font sizes, weights and code fonts during HTML-to-SVG conversion; retain Railroad, Cynefin and Wardley label text, and emit valid SVG for State labels with HTML line breaks. #277, #278
- Render Brutalist shadows on supported Classic and Neo Flowchart shapes and match Usecase arrowheads to connector colors. Explicit Sequence theme backgrounds now contain the full lifeline when bottom participants are hidden. #278, #279
0.10.0-alpha.1 - 2026-11-02 #
Changes below are relative to 0.9.3. Install the exact prerelease with flutter pub add 'merman:0.10.0-alpha.1'; see the host installation guide for stable and alpha choices.
Breaking changes #
- Use Flutter
3.47.7+for Flutter apps; native Dart retains its3.10+SDK requirement. Keep the Dart facade and native assets on the same release, and regenerate matching Dart helpers for custom builds. - Custom text measurers must handle
html-line-height(operation22) with a length result or leave it unhandled for fallback measurement. Text-measurement protocol1is unchanged; see the callback contract. #249 - Update saved Options JSON from schema
2to3: replacepresentationstyling inputs with top-leveltheme: {preset: ...}ortheme: {spec: ...}, and useraster.matteandpdf.page_paintfor export backgrounds. Removed presentation-profile and host-owned CSS/security fields are rejected. ReplacepresentationCatalog()withthemeCatalog(). - For
edge-geometry-json, replace operation-localmax_svg_byteswithmax_geometry_json_bytesand remove SVG-element/backend overrides. The geometry payload remains schema1. See the migration guide. - Formulas are rejected under
constrainedeven when math is installed. Handle that rejection, or selectinteractiveor an appropriate trusted policy for permitted workloads with host execution and memory limits.
Added #
- Use a thin Dart package whose build hook downloads and verifies only the selected target's native library. Configure
native_assetsfor local files,mirrorfor another download host orofflinefor network-free builds with prepared assets or a warm cache. The built app carries its library and needs no runtime download. See the installation guide. #265, #266 - Render formulas with the ordinary native SVG product; no custom math-enabled build is needed. Image encoders and system font discovery remain outside this product.
- Apply 11 alpha theme presets or share your own editable JSON recipe.
themeCatalog()lists presets and their intended diagram families; theme authoring operations export recipes and query styling support for your diagram and output. See the theme guide and gallery for examples and alpha limitations. #178, #223, #234, #253
0.9.3 - 2026-10-30 #
These fixes are included in the published 0.9.3 pub.dev package.
- Fix clipped labels, font sizing, literal text, and HTML/entity handling, including wrapped Swimlane edge labels and valid Class-note XML. #245, #247, #250
- Restore Neo shadows in Sequence diagrams and GitGraph tag backgrounds, and prevent Sequence boxes from clipping at the diagram edges. #255
- Honor Gantt
tickInterval, Mindmap root padding/width, and Sequence numbering, participant visibility, and note alignment. When combining init directives, replace legacyconfigwith explicit namespaces or frontmatter. #252 - Preserve
%in Flowchart node IDs and accept brackets in YAML frontmatter comments and block text. Separate Flowchart header directions from the diagram body with a newline or semicolon. #241, #251
Review SVG snapshots after upgrading. See the workspace changelog for the complete release.
0.9.2 - 2026-10-22 #
- Host themes keep C4 boundary contents and relationships visible, color Wardley anchors, and apply a coherent ZenUML palette. Diagram-selected Mermaid palettes retain matching text and fills. #235, issue #229, issue #230, issue #231, issue #232
- Custom artifacts with native font support skip symbolic and pictorial fonts during implicit font and missing-glyph fallback; explicitly named fonts remain selectable. #235, issue #228
- Look selectors and Block/Requirement source CSS are validated before SVG emission. SVG CSS cleanup rejects unterminated strings, comments, and URLs while preserving safe neighboring declarations. #227, #235, #237
- Repeated Flowchart
classDefdeclarations retain earlier styles, and unsupported Unicode characters preserve valid error spans and lexer progress. Malformed Pie/Info headers and empty XYChart sources behave consistently across parser and editor entrypoints. #178, #227, #237
The existing Presentation and binding options contracts are unchanged. Review regenerated SVG and exported-image snapshots; see the workspace changelog for the complete maintenance release.
0.9.1 - 2026-10-18 #
- ER diagram SVG emission reuses prepared entity geometry, avoiding false missing-size errors on larger diagrams.
- Diagram lexers now make progress and honor cancellation while skipping malformed or empty input.
- Generated HTML label IDs are scoped to the diagram root so multiple diagrams can share a document.
0.9.0 - 2026-10-12 #
Version 0.9.0 retains native ABI 3 from 0.8.0. Keep the generated wrapper and native artifacts paired.
Added #
- SVG-capable operations add
edge-geometry-jsonfor Flowchart, Swimlane, and Agentflow clipped edge points and painted label centers.layout-jsonkeeps its pre-paint coordinates; inspect the installed operation catalog. PR #174, PR #177 - Flowchart, Swimlane, and State ASCII/Unicode node padding accepts independent X/Y overrides, including zero, separately from graph spacing. PR #188
Upgrade #
- Host text-measurement protocol 1 adds signed raw bounding-box Y-offset operations 19–21. Update exhaustive callback handlers without changing the protocol number. Native CLI font flags do not enable native font discovery in the default package. PR #193
- Review transparent SVG backgrounds and corrected geometry/wrapping snapshots. Set
svg.root_background_colorthrough the binding options when opaque SVG is required; match the installed runtime catalog rather than assuming every optional operation is compiled.
Fixed #
- Corrected Unicode HTML wrapping and resvg-safe hollow Class/ER markers; SVG leaves the canvas unset unless an explicit background is requested. PR #180, PR #182, PR #192
- Deep input cleanup no longer relies on recursive ownership. Block child metadata and repeated composite declarations follow the pinned Mermaid behavior. PR #191
- ASCII/Unicode output preserves loop-back contacts, transition labels, compound frames, Sequence spacing, and diamond shoulders. Resource ceilings retain their existing meanings. PR #179, PR #188
See the package guide and upgrade guide.
0.8.0 - 2026-10-06 #
This is the cumulative migration from the 0.7.0 package to 0.8.0, including changes introduced during the alphas. Version 0.8.0 was published on pub.dev on 2026-10-06; keep the Dart facade and native artifacts together.
Breaking changes #
- Replace the legacy plugin integration with
package_ffiand Native Assets. Requires Dart 3.10 / Flutter 3.38; package platform minima are Android 24, iOS 13, and macOS 11. Remove plugin registrars andopenMermanLibrary(); useMerman.open(). - Replace
MermanReusableEngine, engine-owning facade instances, anddispose()with a directly constructedMermanEngineandclose(). Supply immutable text-measurement/icon services at construction; mutable callback installation is removed. - The native contract is C ABI 3 with Options JSON schema 2, analysis facts schema 2, and ASCII report schema 3. Upgrade custom FFI/JSON decoders as well as the library; an unchanged ABI does not freeze payload schemas. Rename viewport fields to
container_width/container_heightand adopt requested/effective ASCII layout and structured-text fallback metadata.
Added #
- Added operation controls with cooperative cancellation/deadlines, structured diagnostic/resource details, capability catalogs, richer terminal plans, and bounded
autolayout. Same-isolate timers cannot interrupt a synchronous call.
Changed #
- The selected engine advances from Mermaid 11.15.0 in the previous stable line to Mermaid 12.1.0. Review ELK layout defaults, Redux/Neo appearance, SVG IDs, and geometry; request top-level
layout: dagre,theme: default, andlook: classicwhen those presentation choices are required. This does not preserve every old SVG byte. - Default native artifacts include SVG, Cytoscape/ELK, ASCII, analysis, validation, and document analysis. Math, PNG/JPEG/PDF, and native runtime adapters require a matching custom artifact; query the loaded runtime catalog before using optional operations.
Fixed #
- Corrected C4 and ELK relationship routing/layering, Packet/XYChart presentation, partial theme overrides, and diagnostic locations; restored Usecase/ER styles and prevented malformed Unicode colors from panicking.
- Native Assets replaces legacy platform-wrapper loading and Apple relocation/symlink paths; keep the generated package and all bundled slices aligned.
Further reading #
- Follow the stable upgrade guide and root changelog. Published alpha sections below remain historical contracts; native Rust timings do not measure Dart/Flutter transport performance.
0.8.0-alpha.7 - 2026-09-30 #
Added #
- Added Mermaid 12 Agentflow and Usecase parsing and SVG rendering. Agentflow follows upstream beta syntax; neither family supports ASCII output.
Changed #
- Updated the engine from Mermaid 11.17.2 to 12.0.0, including ELK layout defaults and the new theme/look defaults for supported families. Refresh SVG snapshots; use top-level
layout: dagre,theme: default, andlook: classicwhen the previous presentation is needed. The bundled artifact already included ELK and retains its EPL-2.0 notices. - Safe diagram-local theme variables and fonts are admitted from frontmatter and directives while host security policy remains authoritative.
Breaking changes #
- Added opt-in
autoASCII layout for bounded Flowchart and Sequence output, with a Compact retry before overflow handling. ASCII output reports now use schema3; update custom decoders for requested/effective layout and Compact-attempt fields. - Update the Dart facade and bundled Native Assets together. The C ABI remains
3; an unchanged ABI number does not make old payload decoders compatible with the new ASCII schema.
0.8.0-alpha.6 - 2026-09-02 #
This section describes alpha.6, published to pub.dev on 2026-09-04 after the complete Native Assets matrix passed the tag-triggered release workflow.
Added #
- Added
MermanOperationControlfor reusable cooperative deadlines and cancellation, including structuredMermanCancelledExceptiondetails. Controls are isolate-local; same-isolate timers cannot interrupt a synchronous execution call. - Added
MermanExactResourceErrorDetailsso unsigned 64-bit resource counts remain available as canonical decimal strings. The existing signed-intprojection remains available when both counts fit its compatibility range. - Added
MermanDiagnosticErrorDetailsandMermanDiagnosticSpanso parser and ASCII renderer failures preserve native diagnostic codes, byte spans, fields, and diagram types without parsing human-facing messages.
Breaking changes #
- The current ABI 3 table appends
operation_control_new,operation_control_cancel,operation_control_release, andexecute_collect_controlled; the Dart wrapper now requires the complete table through slot 10 and maps status 17 to structured cancellation details. Upgrade the Dart package and native artifacts together. - Analysis facts now use schema 2 and no longer include the unused Flowchart-only rich graph. Regenerate facts consumers together with the matching native artifact.
- ASCII capability records now expose independent semantic coverage and primary projection fields, and rename
summaryFallbacktostructuredTextFallback. Structured ASCII resource and diagnostic payloads follow the expanded six-phase renderer contract; upgrade Dart and bundled native artifacts together.
0.8.0-alpha.5 - 2026-08-12 #
This is the first pub.dev release of 0.8.0-alpha.5. It is built from the reviewed Flutter release commit rather than the earlier workspace tag.
Breaking changes #
- The native libraries bundled on pub.dev now provide SVG, both layout engines, ASCII, analysis, validation, and document analysis. Math, PNG, JPEG, PDF, and native runtime adapters require a current-contract custom library loaded through
Merman.openPath(...)orMerman.fromDynamicLibrary(...); bundled calls fail with typed missing-capability or unsupported-operation errors. - Replaced the legacy Flutter plugin integration with Dart
package_ffiand Native Assets. The package now requires Dart 3.10 or newer; Flutter consumers require Flutter 3.38 or newer, Android API 24 or newer, iOS 13 or newer, and macOS 11 or newer. The public rendering API remains unchanged, while the platform plugin registrars andopenMermanLibrary()helper are removed. - Replaced the prerelease ABI 2 wrapper with generated ABI 3 table discovery. Upgrade the Dart package and all bundled native artifacts together; direct
merman_*symbol lookup, manually maintained raw FFI records, and partial-table compatibility are no longer supported. - Split the public SDK into a stateless
Mermandiscovery/one-shot facade and a directly constructed, explicitly closeableMermanEngine. ReplaceMermanReusableEngine,Merman.reusableEngine(...), engine-owningMermaninstances,dispose(), and callback-specialized facade constructors. - Moved host text measurement and icon packs into immutable constructor-owned
MermanEngineServices. The post-construction callback API is removed; callback-enabled engines report typedBUSYorREENTRANTfailures, and engine close is retryable and idempotent. - Replaced format-specific option envelopes with generic
optionsJsonand Options JSON schema2. Rename viewport fields tocontainer_width/container_height, move text/math selectors underenvironment, move semantic theme values underpresentation.theme, use top-levelsite_configandsvg, remove the legacy Flowchart ELK selector, and use documented kebab-case values. - Replaced parser-backed document facts with their final schema 1 shape, raw operation metadata maps with typed
MermanOperationMetadata/MermanOutputPlanvalues, and closed operation/resource enums with generated open value objects. Iterate.knownValues, preserve unknown output plans throughrawJson, and usepresentationCatalog()instead ofsupportedHostThemePresets().
Added #
- Added validated
MermanRuntimeCatalogdiscovery plus generated operation, payload, resource, metadata, and constructor-service contracts for the exact loaded artifact. - Added generic execution and named helpers for SVG, PNG, JPEG, PDF, ASCII, semantic/layout/analysis JSON, document analysis, and validation, including typed raster/PDF output plans and result-returning binary helpers.
- Added immutable
MermanIconPack/MermanIconPackSet, generated resource builders for the standard runtime profiles, and typed cached diagram, parser/render, lint, Mermaid-theme, and presentation metadata APIs.
Changed #
- Flutter native builds now consume the shared size-oriented default native artifact recipe, bundle precompiled libraries through one Native Assets hook, and enforce the pub.dev compressed-upload budget during release preflight.
- Added Android
armeabi-v7ato the packaged native matrix alongsidearm64-v8aandx86_64. - Updated the bundled engine to the Mermaid 11.16.1 compatibility baseline and the shared 35-family parser, layout, SVG, theme, editor, and resource-limit contracts.
- Flutter native builds consume the exact artifact recipe; Apple slices compile-check the complete public C headers, and the pub package carries the project license, source provenance, and exact third-party license texts.
Fixed #
- Native Assets removes the legacy macOS dylib relocation, Linux Windows-wrapper linkage, and SwiftPM symlink failure surfaces reported in #55, #56, and #57. Apple install names are normalized before signing, and Flutter performs final framework assembly and signing.
0.8.0-alpha.3 - 2026-07-09 #
- Documented Flutter/Dart host text-measurement guidance for
MermanReusableEnginecallbacks. - Added pub.dev metadata links and README compatibility notes for C ABI release discovery.
- Updated package metadata for the merman workspace
0.8.0-alpha.3release.
0.8.0-alpha.2 - 2026-06-23 #
- Updated package metadata for the merman workspace
0.8.0-alpha.2release.
0.8.0-alpha.1 - 2026-06-10 #
- Updated package metadata for the merman workspace
0.8.0-alpha.1release.
0.7.0 - 2026-06-09 #
- Updated package metadata for the merman workspace
0.7.0release. - Added host theme preset and supported theme discovery through the bundled native bindings.
0.7.0-alpha.2 - 2026-06-08 #
- Updated package metadata for the merman workspace
0.7.0-alpha.2release.
0.7.0-alpha.1 - 2026-06-05 #
- Initial experimental Flutter/Dart FFI package for the merman C ABI, including bundled native artifacts for Android, iOS, macOS, Windows, and Linux.