Compose Multiplatform Markdown renderer. Targets Android, iOS, Desktop (JVM), and wasmJs.

• Current stable minor: 0.13.0
• Maturity: lightweight production-ready core subset (Markdown-first)

• Architecture Overview -- module structure, parsing pipeline, rendering pipeline
• AST Reference -- complete list of all block and inline node types
• Style Guide -- full reference for OrcaStyle configuration
• Cookbook -- practical recipes for common use cases

• Small API surface
• Predictable AST (orca-core) and Compose renderer (orca-compose)
• Safe defaults for links and images
• No mandatory heavy runtime dependencies
• Compose Multiplatform: single codebase for Android, iOS, Desktop, Web

• orca-core
  • Kotlin Multiplatform
  • AST model (common)
  • parser interface + built-in parser (common)
  • backend: org.jetbrains:markdown (intellij-markdown, GFM flavour)
• orca-compose
  • Compose Multiplatform renderer for OrcaDocument
  • Targets: Android, iOS, Desktop (JVM), wasmJs
  • Style model (OrcaStyle)
  • Lightweight base renderer with no mandatory image/network runtime
• orca-compose-material3
  • Optional Material 3 theme adapter for orca-compose
  • Provides rememberOrcaMaterialStyle() without adding Material 3 to the base renderer
• orca-images-coil
  • Optional Coil 3 + Ktor image renderer for trusted Markdown content
  • Provides block and inline image content slots without making chat-only apps pay for them
• orca-math-orcex (optional, Android / Desktop / iOS)
  • Optional Compose Multiplatform LaTeX renderer backed by Orcex
  • Leaves orca-core and orca-compose free from a bundled font or math engine
• sample-app
  • Android demo for manual checks

// Kotlin Multiplatform (commonMain)
implementation("ru.wertik:orca-core:0.13.0")
implementation("ru.wertik:orca-compose:0.13.0")
implementation("ru.wertik:orca-compose-material3:0.13.0") // optional Material 3 theme adapter
implementation("ru.wertik:orca-images-coil:0.13.0") // optional images
implementation("ru.wertik:orca-math-orcex:0.13.0") // optional multiplatform math renderer

Gradle resolves platform-specific artifacts automatically (orca-core-jvm, orca-compose-android, etc.).

import ru.wertik.orca.core.OrcaMarkdownParser
import ru.wertik.orca.core.OrcaParser

val parser: OrcaParser = OrcaMarkdownParser()
val document = parser.parse(markdown)

OrcaMarkdownParser uses org.jetbrains:markdown and is available in commonMain (Android, iOS, Desktop, wasmJs).

val parser = OrcaMarkdownParser()
val document = parser.parseCached(
    key = "message-42",
    input = markdown,
)

Use a stable key per message/item to avoid repeated AST rebuilds across recompositions and list reuse.

val parser = OrcaMarkdownParser(maxTreeDepth = 32)
val result = parser.parseWithDiagnostics(markdown)

val document = result.document
val warnings = result.diagnostics.warnings
val errors = result.diagnostics.errors

import ru.wertik.orca.compose.Orca
import ru.wertik.orca.compose.OrcaRootLayout
import ru.wertik.orca.core.OrcaMarkdownParser
import androidx.compose.runtime.remember

Orca(
    markdown = markdown,
    parser = remember { OrcaMarkdownParser() },
    parseCacheKey = "message-42",
    rootLayout = OrcaRootLayout.COLUMN, // use when parent already controls scrolling
    securityPolicy = OrcaSecurityPolicies.Default,
    onLinkClick = { url ->
        // open via your app policy
    },
    onParseDiagnostics = { diagnostics ->
        // observe warnings/errors if needed
    },
)

import ru.wertik.orca.compose.Orca

Orca(
    document = document,
)

For token-by-token streaming (e.g. LLM responses), use OrcaStreamingState: it accepts deltas and publishes paced snapshots instead of forcing your UI to replace the entire string on every token.

val stream = rememberOrcaStreamingState(frameIntervalMs = 80)
val parser = remember {
    OrcaIncrementalParserSession(OrcaMarkdownParser())
}

LaunchedEffect(messageId) {
    parser.reset()
    stream.clear()
    responseChunks.collect { delta -> stream.append(delta) }
    stream.finish()
}

Orca(
    state = stream,
    parser = parser,
    parseCacheKey = "message-42",
)

OrcaIncrementalParserSession reuses stable completed paragraph blocks and reparses only the active tail for ordinary prose streams. Rich constructs that can affect earlier content (lists, tables, headings, fences, definitions, footnotes, and HTML blocks) conservatively fall back to the full parser. The initial parse and subsequent parses run on Dispatchers.Default.

fun interface OrcaParser {
    fun parse(input: String): OrcaDocument
    fun parseWithDiagnostics(input: String): OrcaParseResult
    fun parseCached(key: Any, input: String): OrcaDocument
    fun parseCachedWithDiagnostics(key: Any, input: String): OrcaParseResult
}

OrcaMarkdownParser options:

OrcaMarkdownParser(
    maxTreeDepth = 64,
    cacheSize = 64,
    enableSuperscript = true,  // set false to disable ^text^ parsing
    enableSubscript = true,    // set false to disable ~text~ parsing
    onDepthLimitExceeded = { depth ->
        // observe depth truncation if needed
    },
)

Diagnostics model:

data class OrcaParseResult(
    val document: OrcaDocument,
    val diagnostics: OrcaParseDiagnostics,
)

• heading
• paragraph
• bullet list
• ordered list (start number preserved)
• quote
• fenced code block
• indented code block
• thematic break (---)
• standalone image block
• GFM tables
• HTML blocks (styled rendering with tag support)
• footnote definitions
• admonitions / callouts (> [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION])
• definition lists (Term + : Definition)
• details / spoilers (<details>/<summary> — collapsible blocks)

• text
• bold
• italic
• strikethrough
• superscript (^text^)
• subscript (~text~)
• highlight (==text==)
• inline code
• link (with title support)
• inline image rendering (actual images in text flow via InlineTextContent)
• inline HTML (rich styled rendering — <kbd>, <mark>, <b>, <i>, <sup>, <sub>, etc.)
• footnote references
• inline footnotes ^[...]
• soft/hard line breaks (\n)
• emoji shortcodes (:smile:, :rocket:, :fire:, etc.)
• abbreviations (*[ABBR]: Full Title)

• GFMFlavourDescriptor from org.jetbrains:markdown
• GFM tables
• strikethrough
• task list markers
• autolinks (including bare URLs like https://example.com)
• footnotes layer in Orca ([^label] and inline ^[...])

• front matter parsing:
  • YAML (--- ... ---)
  • TOML (+++ ... +++)

• LazyColumn root for long documents
• optional root layout switch: OrcaRootLayout.LAZY_COLUMN or OrcaRootLayout.COLUMN
• initial and subsequent raw-Markdown parsing off main thread (Dispatchers.Default)
• parse failure fallback to previous valid document (UI is not dropped); partial results with errors accepted when blocks are present (avoids streaming freeze on unclosed fences)
• deterministic block keys for better list state retention (FNV-1a hash with 256-char sampling + tail fold)
• full document text selection — all text (headings, paragraphs, lists, quotes, tables) is selectable
• footnotes rendered as superscript markers + numbered definitions block
• footnote navigation:
  • tap reference marker ([n]) to jump to definition
  • tap backlink (↩) to return to source block
• accessibility — semantic roles for headings, content descriptions for images and blocks
• heading anchor links — [link](#heading-text) scrolls to the corresponding heading (auto-generated GitHub-style slugs)
• custom block renderers — override rendering for any block type via blockOverride parameter
• zero-cost optional images — base orca-compose displays fallback/alt text; supply imageContent and inlineImageContent only when image rendering is needed

• GitHub-style callout blocks: NOTE, TIP, IMPORTANT, WARNING, CAUTION
• colored left stripe + icon + title
• full content block rendering inside admonition
• light and dark theme color presets
• collapsible mode — toggle content visibility with animated expand/collapse

• HTML <details>/<summary> blocks rendered as collapsible sections
• animated expand/collapse
• supports <details open> for initially expanded state
• nested markdown content inside details is fully rendered
• styled border + background, configurable via OrcaDetailsStyle

• monospace typography
• rounded container + subtle border
• optional language label (when language exists)
• syntax highlighting (enabled by default, configurable) — supports multiline strings, raw strings, template literals, decorators, type annotations
• selectable code text
• optional line numbers for multiline blocks
• horizontal scroll for long lines (no forced wrap)
• optional copy-to-clipboard button

• shimmer/skeleton placeholder while loading (no more raw text fallback)
• smooth crossfade transition on load
• error state with icon fallback

• auto layout by content width (default)
• fallback fixed layout mode available via style
• horizontal scroll remains for wide tables

• block-level HTML rendered with styled AnnotatedString
• supported tags: <b>, <i>, <s>, <u>, <code>, <a>, <sup>, <sub>, <mark>, <kbd>, <br>, <p>, <h1>-<h6>, <li>, <hr>, <blockquote>, <pre>
• HTML entities decoded (&, <, >, ",  , numeric —, ✔, etc.)
• interleaved/malformed tags handled gracefully (e.g. <b><i></b></i> -- styles popped and re-pushed correctly)
• unknown tags gracefully stripped

Use OrcaStyle as a single configuration object:

• typography
• inline
• layout
• quote
• code
• table
• thematicBreak
• image
• inlineImage
• admonition
• definitionList
• details

// Automatically picks light or dark style based on system theme
val style = OrcaDefaults.adaptiveStyle() // @Composable

For Material 3 apps, derive colors, typography, and shapes directly from the active theme:

import ru.wertik.orca.compose.material3.rememberOrcaMaterialStyle

val style = rememberOrcaMaterialStyle()

Pass the same LazyListState to Orca and your scrollbar or external controls:

val listState = rememberLazyListState()

Orca(
    document = document,
    listState = listState,
    style = rememberOrcaMaterialStyle(),
)

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import ru.wertik.orca.compose.Orca
import ru.wertik.orca.compose.OrcaCodeBlockStyle
import ru.wertik.orca.compose.OrcaStyle

Orca(
    markdown = markdown,
    parser = remember { OrcaMarkdownParser() },
    style = OrcaStyle(
        code = OrcaCodeBlockStyle(
            background = Color(0xFFF8F9FB),
            borderColor = Color(0xFFD0D7DE),
            borderWidth = 1.dp,
        ),
    ),
)

• Default policy allows links using http, https, mailto, and local #fragment targets.
• Images are blocked by default so rendering untrusted Markdown cannot trigger network requests.
• Unsafe URLs are rendered as plain text/fallback instead of clickable/loaded targets.
• You can fully override checks via OrcaSecurityPolicy.

For trusted content that should load remote images, opt into both URL permission and an image renderer. With the optional Coil module:

import ru.wertik.orca.images.coil.OrcaCoilImage
import ru.wertik.orca.images.coil.OrcaCoilInlineImage

Orca(
    document = document,
    securityPolicy = OrcaSecurityPolicies.RemoteImages,
    imageContent = { url, description -> OrcaCoilImage(url, description, style) },
    inlineImageContent = { url, description -> OrcaCoilInlineImage(url, description, style) },
)

Custom policy example:

val policy = OrcaSecurityPolicies.byAllowedSchemes(
    linkSchemes = setOf("https", "myapp"),
    imageSchemes = setOf("https"),
    allowRelativeLinks = true,
    allowRelativeImages = true,
)

Orca(
    markdown = markdown,
    parser = remember { OrcaMarkdownParser() },
    securityPolicy = policy,
)

Always keep your own URL-opening policy in onLinkClick.

Override how specific block types are rendered:

Orca(
    markdown = markdown,
    parser = remember { OrcaMarkdownParser() },
    blockOverride = mapOf(
        OrcaBlock.CodeBlock::class to { block ->
            val code = block as OrcaBlock.CodeBlock
            MyCustomCodeBlock(code = code.code, language = code.language)
        },
    ),
)

orca-compose intentionally ships without an image/network stack. Add orca-images-coil for the provided Coil/Ktor slots, or provide your own slots:

Orca(
    markdown = markdown,
    parser = remember { OrcaMarkdownParser() },
    securityPolicy = OrcaSecurityPolicies.RemoteImages,
    imageContent = { url, contentDescription ->
        GlideImage(model = url, contentDescription = contentDescription)
    },
    inlineImageContent = { url, contentDescription ->
        GlideInlineImage(model = url, contentDescription = contentDescription)
    },
)

Orca(
    markdown = markdown,
    parser = remember { OrcaMarkdownParser() },
    style = OrcaStyle(
        admonition = OrcaAdmonitionStyle(
            collapsible = true,
            collapsedByDefault = false,
        ),
    ),
)

./gradlew --no-daemon --build-cache :orca-core:jvmTest :orca-compose:testDebugUnitTest :orca-compose-material3:testDebugUnitTest :sample-app:assembleDebug

For release-like check:

./gradlew --no-daemon --build-cache :sample-app:assembleRelease :sample-app:bundleRelease

• Stable releases use plain semver tags like 0.9.1
• Pre-releases use -alpha, -beta, -rc
• Maven Central artifacts are immutable after publish

• Stable first layout -- restores synchronous initial Markdown parsing so messages nested in an outer LazyColumn no longer appear empty before gaining their real height and displacing scroll position.
• Streaming preserved -- subsequent text updates remain asynchronously parsed and paced; only the first measured frame is stabilised.

• Multiplatform Orcex math -- migrates orca-math-orcex from the Android Canvas bridge to Orcex 0.4.0's Compose Multiplatform renderer for Android, Desktop, and supported iOS targets.
• Android compatibility -- keeps the existing Typeface convenience overloads so current Android applications can upgrade without rewriting their formula slots.
• Explicit verification -- CI and release builds now compile the math adapter on Desktop and iOS Simulator as well as Android.

• Orcex 0.3.0 -- updates the optional Android native math renderer to the current published Orcex release.

• Valid Maven POM -- removes a redundant versionless AndroidX Compose UI dependency from orca-math-orcex; Compose UI remains supplied transitively by orca-compose.

• Math AST and slots -- parses conservative inline $...$ and display $$...$$ formulas with readable source fallback.
• Optional Orcex renderer -- adds orca-math-orcex for native Android Canvas math rendering; the STIX font remains opt-in.
• Streaming-safe formulas -- incomplete formula delimiters stay text until the closing delimiter arrives.
• Orcex 0.2.1 -- consumes the published renderer release with corrected matrix delimiter layout.

• Ultra-light base renderer -- moves Coil/Ktor image loading from orca-compose into opt-in orca-images-coil.
• Explicit image slots -- block and inline Markdown images render only through imageContent / inlineImageContent; without a loader, safe alt/fallback text remains visible.
• Streaming state API -- rememberOrcaStreamingState() accepts token deltas and publishes paced snapshots for chat rendering without caller-side full-string updates per token.
• Conservative tail parsing -- OrcaIncrementalParserSession reuses completed prose blocks and safely falls back to full parsing for document-scoped/rich Markdown constructs.
• Readable dark tables -- OrcaDefaults.darkStyle() now provides explicit light table body/header colors instead of inheriting black text.

• Smaller Android releases -- removes keep-all consumer rules so R8 strips unused Orca code; in the Fish release APK this reduced output by about 116 KiB.
• Safer image defaults -- remote images are blocked by default; opt in with OrcaSecurityPolicies.RemoteImages or a custom scheme policy.
• No initial UI-thread parse -- raw Markdown is parsed on Dispatchers.Default from the first composition onward.
• Responsive token streaming -- continuous updates are conflated and rendered at the pacing interval instead of waiting for a pause.
• Lighter renderer dependencies -- renderer uses Foundation text instead of Material3 and drops unused direct Android/Ktor dependencies.
• Consumer ABI metadata -- public Compose and Markdown parser types are now published through api dependencies.

• ==highlight== syntax -- inline text highlight with configurable OrcaInlineStyle.highlight (yellow background by default)
• Heading anchor IDs -- headings auto-generate GitHub-style slugs (## My Heading -> id = "my-heading"), duplicate headings get -1, -2 suffixes
• Fragment link scroll -- [link](#heading-slug) clicks auto-scroll to the matching heading in both LAZY_COLUMN and COLUMN layouts
• Fragment URLs allowed -- #fragment URLs now pass security policy (previously blocked as schemeless)

• Inline HTML rendering -- <kbd>, <mark>, <b>, <i>, <sup>, <sub>, <code>, <u>, <s> tags in paragraphs now render with proper styles (previously stripped to plain text)
• <kbd> tag -- keyboard input tag rendered with monospace font + subtle background in both block and inline HTML
• Numeric HTML entities -- —, ✔ and all decimal/hex character references decoded correctly
• Details summary inline markdown -- <summary>**bold** text</summary> now renders rich inline formatting (was plain text)
• KMP fix -- numeric entity decoder uses cross-platform codepoint conversion instead of JVM-only String(IntArray)

• <details>/<summary> support -- collapsible blocks with animated expand/collapse, <details open>, nested markdown content
• Coil warnings fix -- replaced manual when (painter.state) with slot-based loading/error/success parameters
• Kotlin expect/actual warnings -- suppressed beta warnings via compiler opt-in

• Cache lock fix -- OrcaParserCache now parses outside the lock; concurrent callers no longer block each other (eliminates ANR risk on main thread)
• HTML interleaved tags -- malformed tag nesting like <b><i></b></i> is handled correctly by scanning the stack and re-pushing intervening styles
• Table recomposition -- TableRowNode uses rememberUpdatedState for callbacks, preventing unnecessary AnnotatedString rebuilds on every recomposition
• Initial parse diagnostics -- warnings and errors from the synchronous first-frame parse are now reported via onParseDiagnostics
• Streaming freeze fix -- parse results with errors but non-empty blocks are accepted instead of falling back to a stale document (fixes UI freeze on unclosed code fences during streaming)
• Render depth guard -- OrcaBlockNode enforces MAX_RENDER_DEPTH = 32 to prevent stack overflow on deeply nested markdown from custom parsers
• Hash distribution -- stableHash samples 256 characters (was 128) and folds in tail content for strings >256 chars, reducing LazyColumn key collisions for code blocks with identical imports

1. Open an issue for substantial change.
2. Keep PR scope focused.
3. Add tests for parser/render regressions.
4. Update release notes and README support section when behavior changes.

MIT. See LICENSE.