CMP Mermaid

CMP Mermaid is designed for applications that render many diagrams without a WebView per diagram. The production path does not embed Mermaid.js and does not include a network client or require android.permission.INTERNET: parsing, diagram state, layout preparation, SceneGraph generation, and final Compose Canvas painting are owned by the multiplatform libraries.

All 33 implemented families retain repository-controlled tests and corpus data, published Native/Official captures, and passing replacement detail and geometry gates.

Overall Mermaid 12.0.0 support is Stable because all 33 family gates pass. A legal feature that cannot be represented faithfully returns MermaidError.UnsupportedFeature instead of silently drawing a misleading approximation.

The comparisons below use the same Mermaid source, theme, layout mode, and fixed viewport. The goal is equivalent meaning and comparable visual quality, not pixel-identical browser output; platform font metrics may differ.

Flowchart: multi-region failover

CMP Native - Compose Canvas	Official - Mermaid.js 12.0.0

More same-source comparisons

XY Chart: mixed bar and line series

CMP Native - Compose Canvas	Official - Mermaid.js 12.0.0

State Diagram: labels, loops, branches, and terminal states

CMP Native - Compose Canvas	Official - Mermaid.js 12.0.0

The current published report contains 441 independent production comparisons and a separate large-scale matrix with 8,448 unique Mermaid sources: open all 528 visual evidence pages.

All 33 implemented types support Mermaid frontmatter, relevant metadata, Unicode, and the relevant theme variables within their documented compatibility boundaries.

Open the live Kotlin/Wasm demo to browse syntax, render the galleries, switch all 11 themes, and compare CMP Native output with the pinned Mermaid.js reference. Every supported diagram type has an editable Playground with Native/Official preview switching. Mindmap can switch among CoSE-Bilkent, Dagre, and tidy-tree layouts.

The official comparison renderer belongs to mermaid-debug-ui only. mermaid-core and mermaid-compose never use Mermaid.js.

Mermaid source
    -> Kotlin preprocessor and translated parser
    -> translated diagram database and layout preparation
    -> platform-independent MermaidScene
    -> Compose Canvas

• mermaid-core owns parsing, diagram state, layout adapters, typed errors, themes, and the platform-independent SceneGraph.
• mermaid-compose owns Canvas painting, text measurement, assets, interactions, and pan/zoom behavior.
• mermaid-debug-ui owns documentation, galleries, Playground, official comparison, and load-test screens. It is optional and should remain outside production release variants.
• sample/* contains thin Android, iOS, Desktop, and Web launchers around the shared debug UI.

The production libraries contain no JavaScript engine or bundled JavaScript algorithm. Pure Kotlin Dagre is the default unified layout. ELK names and flowchart-elk are recognized as upstream inputs but return MermaidError.UnsupportedFeature("ELK layout"); they are never silently substituted with another layout.

The current publication coordinates are:

Current Kotlin Multiplatform projects:

dependencies {
    implementation("io.github.swithun-liu:mermaid-compose:0.1.8")
}

Android projects pinned to Kotlin 1.7.21 use the isolated Android artifact:

dependencies {
    implementation(
        "io.github.swithun-liu:mermaid-compose-android-kotlin17:0.1.8",
    )
}

The Kotlin 1.7.21 artifacts are Android-only, target JVM 1.8, and require Android API 24 or newer. Their artifact names are intentionally distinct from the current KMP modules, so a consumer cannot accidentally resolve Kotlin 2.x metadata.

Android View-based hosts can use the same Compose renderer without compiling Compose source:

val diagramView = CMPMermaidView(context).apply {
    setMermaidSource("flowchart LR\n  A --> B")
    setMermaidContentDescription("Example Mermaid diagram")
    setMermaidErrorListener { error ->
        reportRenderFailure(error.type, error.message, error.source)
    }
}
container.addView(diagramView)

CMPMermaidView is available from both the current Android target and the Kotlin 1.7.21 Android artifact.

iOS projects can consume the precompiled static XCFramework through CocoaPods:

pod 'CMPMermaid', '0.1.8'

The binary exposes CMPMermaidViewControllerFactory.makeViewController(...) to Swift and includes all renderer font resources. It supports iOS device arm64 and simulator arm64/x86_64 with a deployment target of iOS 14.

CMPMermaidViewControllerFactory().makeViewController(
    source: source,
    contentDescription: "Mermaid diagram",
    onContentSizeChanged: nil,
    onError: { error in
        reportRenderFailure(error.type, error.message, error.source)
    }
)

For a source checkout:

dependencies {
    implementation(project(":mermaid-compose"))
    debugImplementation(project(":mermaid-debug-ui"))
}

Basic Compose usage:

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import com.swithun.cmpmermaid.compose.MermaidDiagram
import com.swithun.cmpmermaid.core.MermaidTheme
import com.swithun.cmpmermaid.core.MermaidThemePreset

@Composable
fun Diagram(source: String) {
    MermaidDiagram(
        source = source,
        modifier = Modifier.fillMaxWidth(),
        theme = MermaidTheme.preset(MermaidThemePreset.Default),
        contentDescription = "Mermaid diagram",
        onError = { error ->
            reportRenderFailure(error.type, error.message, error.source)
        },
    )
}

The error callback receives MermaidRenderErrorInfo, including the original source passed to the renderer. CONTENT_ERROR represents structured parse, configuration, resource-limit, or unsupported-content failures. UNEXPECTED_EXCEPTION represents an ordinary exception caught inside the render pipeline or Compose drawing boundary. The Compose surface renders Mermaid.js 12.0.0's standard error diagram while the callback and onRenderResult retain the detailed typed diagnostic. The published source-mutation corpus verifies Official accept/reject outcome parity for all 8,448 cases. Native rejected inputs remain typed CONTENT_ERROR; exact diagnostic-message equality is reported separately for 1,798/6,292 paired errors and is not manufactured as a compatibility requirement. Coroutine cancellation and fatal process errors continue to propagate.

Generate all KMP publications under build/maven-repository:

./gradlew \
  :mermaid-core:publishAllPublicationsToBuildRepository \
  :mermaid-compose:publishAllPublicationsToBuildRepository

Generate the Kotlin 1.7.21 Android artifacts with JDK 11:

./android-legacy-build/gradlew -p android-legacy-build \
  assembleRelease \
  verifyLegacyPublicationCoordinates \
  publishLegacyToReleaseRepository

Generate and verify the static iOS binary with JDK 17:

./gradlew :mermaid-compose:podPublishReleaseXCFramework
tools/release/verify-ios-xcframework.sh

The Quality Gate builds and verifies the iOS XCFramework once and preserves it with its exact source commit. Pushing a v* tag then builds the modern KMP and Kotlin 1.7.21 Android artifacts in parallel while reusing only the successful verified iOS artifact from the successful main push Quality Gate for that immutable tag commit. All outputs are joined and verified again before any public registry is updated.

An interrupted publication keeps its prerelease and verified workflow artifact for 14 days. Re-run the failed jobs, or manually run the Release workflow with the same immutable tag. Maven Central and CocoaPods are checked before each write, so an already-published version is verified and skipped instead of being uploaded again.

All 11 Mermaid 12.0.0 presets are included: default, dark, forest, neutral, base, neo, neo-dark, redux, redux-color, redux-dark, and redux-dark-color.

Business themes can start from a preset with Kotlin copy, or consume Mermaid-compatible themeVariables through MermaidTheme.withVariables(...). Invalid external values are returned as GMResult.Err.

val brandTheme = MermaidTheme.preset(MermaidThemePreset.ReduxColor).copy(
    background = SceneColor(0xFF101820),
    nodeFill = SceneColor(0xFFF2AA4C),
    nodeText = SceneColor(0xFF101820),
    edge = SceneColor(0xFFF2AA4C),
)

Arbitrary themeCSS depends on browser DOM/CSS semantics and returns MermaidError.UnsupportedFeature. Portable styling uses typed Kotlin theme objects and MermaidFontFamilyResolver.

CMP Mermaid follows a source-mapped translation workflow rather than reimplementing behavior from screenshots:

1. Pin Mermaid, Jison, D3, Marked, Dagre, CoSE-Bilkent, and tidy-tree versions.
2. Map every Kotlin parser, DB, layout, shape, theme, and renderer boundary to its upstream Mermaid source.
3. Generate parser tables, rules, entities, fixtures, and debug-only reference assets from pinned inputs.
4. Translate only the upstream delta for a Mermaid upgrade.
5. Re-run the complete parity and platform gates.

Source maps: Flowchart · XY Chart · Quadrant Chart · Timeline · Kanban · Sequence · Class · State · ER · Gantt · Pie · User Journey · Requirement · Git Graph · Mindmap · Packet · Radar · Sankey · Treemap · Venn · Ishikawa · Cynefin · Event Modeling · Agentflow · Block

Run the JVM and publication gates:

./gradlew \
  :mermaid-core:jvmTest \
  :mermaid-compose:jvmTest \
  verifyPublicationCoordinates

Run the samples:

./gradlew :sample:androidApp:installDebug
./gradlew :sample:desktopApp:run
./gradlew :sample:webApp:wasmJsBrowserDevelopmentRun

The Stable test report contains the complete cross-platform build and Native/Official visual reproduction commands.

CMP Mermaid is released under the MIT License. Translated Mermaid behavior and development-only reference assets retain their upstream notices in THIRD_PARTY_NOTICES.md.