@inditextech/docouture-asciidoc-extensions 0.1.0-SNAPSHOT.40.1

package/lib/kroki-config.js

@@ -0,0 +1,191 @@
+'use strict'
+
+// Shared between the two halves of GH-44's Kroki support — see
+// kroki.js's own header for why there are two halves at all.
+//
+// THE URL IS NOT SITE-CONFIGURABLE, ON PURPOSE. Every other piece of Kroki
+// config here (whether it runs at all, which diagram types) is an authored
+// `asciidoc.attributes` key a site can set — but the endpoint itself is a
+// single fixed value, `http://localhost:8500`, the one
+// @inditextech/docouture-antora-extensions' `kroki-prewarm.js`/`kroki-docker.js`
+// auto-start against, and the one baked into their bundled
+// `resources/kroki-compose.yml`. That was a deliberate call (see GH-44's own
+// thread): letting a site point this at an arbitrary URL turns a
+// same-machine, no-network-egress diagram renderer into an arbitrary
+// outbound HTTP call an author's `asciidoc.attributes` YAML can redirect —
+// not a risk worth taking for a value with exactly one legitimate answer per
+// environment (the loopback Kroki this repo's own tooling starts). 8500
+// rather than Kroki's own factory default (8000) only to keep this
+// project's fixed port away from whatever else a contributor's machine
+// already has bound to 8000 — it carries no other meaning and does not need
+// to match Kroki's upstream docs.
+const KROKI_URL = 'http://localhost:8500'
+
+// Every block style name this extension recognizes, and the exact path
+// segment Kroki's own `/{diagramType}/svg` API expects for it — identical
+// strings for every type Kroki supports, so this is also the full set of
+// values `kroki-diagram-types` accepts.
+//
+// Curated, not Kroki's entire catalogue: each entry here is a type this
+// project has actually verified end to end (see the sibling
+// `kroki-prewarm.js` and `@inditextech/docouture-antora-extensions`'
+// `resources/kroki-compose.yml`). Kroki supports more; add to this list —
+// and to that compose file's companions, for any type that needs one,
+// mermaid, bpmn and excalidraw being the three in Kroki's own catalogue
+// that do (each is its own headless-Chrome/Puppeteer service, on its own
+// fixed port — see that compose file's own header for the port each one
+// actually listens on, verified by inspecting the running container rather
+// than assumed) — before authors can rely on a new one. A site can
+// customize that compose file for itself via `docouture eject kroki` without
+// forking this package.
+const SUPPORTED_TYPES = [
+  'mermaid',
+  'plantuml',
+  'graphviz',
+  'c4plantuml',
+  'excalidraw',
+  'blockdiag',
+  'ditaa',
+  'erd',
+  'nomnoml',
+  'svgbob',
+  'vega',
+  'vegalite',
+  'wavedrom',
+  'bpmn',
+]
+
+// Kroki's own `/{type}/{format}` API rejects a format it doesn't support for
+// that type with a plain 400 rather than degrading — verified against a
+// live server, one `SUPPORTED_TYPES` entry at a time (posting a
+// deliberately-invalid body to every type's own `/png` endpoint: a syntax
+// error means the format itself was accepted, "Unsupported output format"
+// means it wasn't). Five entries are SVG-only in Kroki's own catalogue:
+// `excalidraw`, `nomnoml`, `svgbob`, `wavedrom`, and — despite drawing
+// ordinary rectangles and circles that look no different from any other
+// diagram-as-code output — `bpmn`. The other nine, listed here, all render
+// PNG (and Kroki formats beyond that this package doesn't expose a way to
+// request) the same way they render SVG. `format=png` on an unlisted type
+// falls back to `svg` with a warning — see `resolveFormat` — the same
+// degrade-not-fail posture as an unknown `kroki-diagram-types` entry.
+const PNG_SUPPORTED_TYPES = new Set([
+  'mermaid',
+  'plantuml',
+  'graphviz',
+  'c4plantuml',
+  'blockdiag',
+  'ditaa',
+  'erd',
+  'vega',
+  'vegalite',
+])
+
+const DEFAULT_FORMAT = 'svg'
+
+// The two `asciidoc.attributes` keys a site sets in its playbook. Both are
+// read from the same `document` object on the synchronous (Asciidoctor)
+// side, in kroki.js, and from `playbook.asciidoc.attributes` on the async
+// (Antora pipeline) side, in kroki-prewarm.js — kept together here so the
+// two never drift into checking different key strings.
+const ENABLED_ATTR = 'kroki-enabled'
+const TYPES_ATTR = 'kroki-diagram-types'
+
+/**
+ * Antora/Asciidoctor attribute truthiness: an attribute given as YAML `true`
+ * arrives as the boolean `true`; one written `kroki-enabled: "true"` (or set
+ * via a document `:kroki-enabled: true` line) arrives as the string
+ * `'true'`. Anything else — unset, `false`, `'false'`, empty string — is
+ * off. There is no third state: this package has no other boolean-attribute
+ * precedent to match against, so the two truthy shapes actually reachable
+ * from YAML and from AsciiDoc source are both covered and nothing else is
+ * guessed at.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isTruthy(value) {
+  return value === true || value === 'true'
+}
+
+/**
+ * Resolves which of `SUPPORTED_TYPES` are actually active, given the two
+ * attribute values a site may have set. Shared verbatim by both the sync
+ * block processor (which must not attempt a type that was never prewarmed)
+ * and the async prewarm listener (which must not fetch a type nobody asked
+ * for) — the two have to agree, or a type enabled in one place and not the
+ * other either wastes a network call or never gets rendered.
+ *
+ * @param {unknown} enabledAttr - raw `kroki-enabled` attribute value.
+ * @param {unknown} typesAttr - raw `kroki-diagram-types` attribute value;
+ *   comma-separated, whitespace tolerated. Omitted (or empty) while enabled
+ *   means "every supported type".
+ * @param {(unknown: string) => void} [onUnknownType] - called once per
+ *   comma-separated entry that isn't in `SUPPORTED_TYPES`, so the caller can
+ *   warn with its own node context. Not called when `typesAttr` is absent —
+ *   omitting the attribute is the documented way to mean "all of them", not
+ *   an authoring mistake.
+ * @returns {Set<string>} the active subset of `SUPPORTED_TYPES`; empty when
+ *   `kroki-enabled` is not truthy.
+ */
+function resolveEnabledTypes(enabledAttr, typesAttr, onUnknownType) {
+  if (!isTruthy(enabledAttr)) return new Set()
+  if (typesAttr == null || typesAttr === '') return new Set(SUPPORTED_TYPES)
+
+  const requested = String(typesAttr)
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+
+  const active = new Set()
+  for (const type of requested) {
+    if (SUPPORTED_TYPES.includes(type)) {
+      active.add(type)
+    } else if (onUnknownType) {
+      onUnknownType(type)
+    }
+  }
+  return active
+}
+
+/**
+ * Resolves the actual output format to request from Kroki for one block:
+ * an author writes `[mermaid,format=png]`; omitted, empty, or explicitly
+ * `svg` all mean the existing default. Shared verbatim by the sync block
+ * processor (kroki.js) and the async prewarm scanner (kroki-prewarm.js) for
+ * the same reason `resolveEnabledTypes` is — both derive a cache key from
+ * this value (kroki-instance.js's `keyFor`), so a type this function
+ * silently downgrades in one place and not the other would look up a key
+ * the other side never populated.
+ *
+ * @param {string} type - a `SUPPORTED_TYPES` entry.
+ * @param {unknown} requestedFormat - the block's own `format` attribute,
+ *   however Asciidoctor or the raw-text regex handed it over — anything at
+ *   all, not just `"svg"`/`"png"`, since this is the one place both sides
+ *   actually validate it (kroki-prewarm.js's own regex deliberately doesn't
+ *   restrict the value it captures, for exactly this reason).
+ * @param {(type: string, requestedFormat: string) => void} [onUnsupported] -
+ *   called once for any `requestedFormat` that isn't `svg`/absent and isn't
+ *   a `png` this type's Kroki companion actually supports — an unrecognized
+ *   value (a typo, `format=jpeg`) and a recognized-but-unsupported one
+ *   (`format=png` on `bpmn`) both go through this the same way, so the
+ *   caller can warn with its own node context either way.
+ * @returns {'svg' | 'png'}
+ */
+function resolveFormat(type, requestedFormat, onUnsupported) {
+  if (requestedFormat == null || requestedFormat === '' || requestedFormat === DEFAULT_FORMAT) return DEFAULT_FORMAT
+  if (requestedFormat === 'png' && PNG_SUPPORTED_TYPES.has(type)) return 'png'
+  if (onUnsupported) onUnsupported(type, String(requestedFormat))
+  return DEFAULT_FORMAT
+}
+
+module.exports = {
+  KROKI_URL,
+  SUPPORTED_TYPES,
+  PNG_SUPPORTED_TYPES,
+  DEFAULT_FORMAT,
+  ENABLED_ATTR,
+  TYPES_ATTR,
+  isTruthy,
+  resolveEnabledTypes,
+  resolveFormat,
+}

package/lib/kroki-instance.js

@@ -0,0 +1,89 @@
+'use strict'
+
+const { createHash } = require('node:crypto')
+
+// Shared cache of prewarmed Kroki renders for an entire Antora build — one
+// entry per distinct (diagram type, source, output format) triple, keyed by
+// a hash of all three.
+//
+// Same split as shiki-instance.js, for the same reason: rendering a diagram
+// means an HTTP round trip to the Kroki service (see kroki-config.js's own
+// header for why that's a fixed loopback URL), which is asynchronous, but
+// `@asciidoctor/core ~2.2`'s Opal conversion loop that actually calls this
+// package's block processor (kroki.js) is fully synchronous and cannot
+// itself await anything. So all the fetching happens up front, for every
+// `[mermaid]`/`[plantuml]`/etc. block the raw content aggregate contains,
+// in `@inditextech/docouture-antora-extensions`' `kroki-prewarm.js` — an Antora
+// PIPELINE extension hooking `contentAggregated`, well before
+// `documentsConverted` ever reaches Asciidoctor. This file is the seam
+// between that async producer and kroki.js's synchronous consumer, exactly
+// as shiki-instance.js is for Shiki — see that file's own header for why a
+// plain module-level variable (a Map, here, since there are many diagrams
+// rather than one highlighter) is enough: one build per process, both
+// packages `require()` the same file, node's module cache doing the rest.
+const cache = new Map()
+
+/**
+ * The cache key for one diagram: its block style (`mermaid`, `plantuml`, …),
+ * its exact source, and its output format, hashed together. Format has to
+ * be part of the key alongside type and source — `[mermaid]` and
+ * `[mermaid,format=png]` over the same source are two different Kroki
+ * fetches (`/mermaid/svg` vs `/mermaid/png`) and two different cached
+ * payloads (see `set`'s own doc), not one. The source is trimmed first so a
+ * trailing blank line an author left in (or Asciidoctor's own line handling
+ * adds) doesn't produce a cache miss for what is, semantically, the same
+ * diagram.
+ *
+ * Both halves of this feature call this with identical inputs: kroki.js
+ * with the block's own style, its reader's joined source (after
+ * kroki-mermaid-theme.js's own transform, for `mermaid`), and its resolved
+ * format; kroki-prewarm.js with the same three, its own raw-file regex
+ * extracted. They have to derive the same key from the same diagram, or a
+ * prewarmed entry is unreachable from the synchronous side.
+ *
+ * @param {string} type - a `SUPPORTED_TYPES` entry (kroki-config.js).
+ * @param {string} source - the raw diagram source, untrimmed is fine.
+ * @param {string} [format] - `resolveFormat`'s return value; defaults to
+ *   `'svg'` so every call site written before `format` existed still keys
+ *   the same way it always did.
+ * @returns {string} a hex digest, opaque beyond being a stable cache key.
+ */
+function keyFor(type, source, format) {
+  return createHash('sha256')
+    .update(type + '\u0000' + String(source).trim() + '\u0000' + (format || 'svg'))
+    .digest('hex')
+}
+
+module.exports = {
+  keyFor,
+  /**
+   * Called once per distinct diagram by kroki-prewarm.js, after its fetch to
+   * Kroki resolves.
+   *
+   * @param {string} key - see `keyFor` below; the same function, called with
+   *   the same inputs, is how kroki.js looks this back up.
+   * @param {{ format: 'svg' | 'png', data: string }} payload - `format` is
+   *   `resolveFormat`'s return value for this diagram; `data` is Kroki's own
+   *   response body — the `<svg>...</svg>` markup verbatim for `svg`, or a
+   *   base64-encoded PNG for `png` (kroki.js embeds the latter as a `data:`
+   *   URI — see that file's own header for why a data URI rather than a
+   *   written-to-disk image file).
+   * @returns {void}
+   */
+  set(key, payload) {
+    cache.set(key, payload)
+  },
+
+  /**
+   * @param {string} key
+   * @returns {{ format: 'svg' | 'png', data: string } | undefined} the
+   *   cached payload, or `undefined` when this diagram was never prewarmed
+   *   — the ui-bundle preview harness (no Antora pipeline at all, so
+   *   kroki-prewarm.js never runs), a build where `kroki-enabled` was off at
+   *   prewarm time, or a Kroki fetch that failed. kroki.js degrades to the
+   *   plain literal-block fallback in every one of these cases.
+   */
+  get(key) {
+    return cache.get(key)
+  },
+}

package/lib/kroki-mermaid-theme.js

@@ -0,0 +1,93 @@
+'use strict'
+
+// Mermaid is the one SUPPORTED_TYPES entry (kroki-config.js) with a
+// documented, source-level theming mechanism: a `%%{init: {...}}%%`
+// directive as the diagram's own first line, which Mermaid's renderer
+// itself reads before laying anything out — `themeVariables` recolors its
+// built-in palette, `themeCSS` is arbitrary CSS Mermaid inlines into the
+// `<style>` block it already generates. Unlike the CSS-based overrides this
+// package used to apply from the OUTSIDE (ui-bundle's diagram.css, fighting
+// Mermaid's own `#container`-scoped rules with `!important`), this bakes
+// the result INTO the SVG (or PNG — Kroki's mermaid companion renders PNG
+// by literally screenshotting the same themed SVG in headless Chrome, so
+// this applies identically to both) that Kroki returns. Verified against a
+// live render both ways: computed `rx`/`fill` on the resulting `<rect>`
+// match this file's own values, with zero page CSS involved at all.
+//
+// COLORS ARE HARDCODED HEX, NOT `--ids-*` TOKENS — deliberately. This runs
+// server-side, at prewarm/render time, against a plain HTTP POST body; there
+// is no CSS custom-property resolution available there (no page, no
+// cascade, nothing). The values below are IOP DS's own light-theme
+// `--ids-color-{bg,border,content}-default` (ids-tokens.css) copied
+// verbatim — same exception the iop-ds-foundations skill already carves out
+// for `--hljs-*`'s own syntax palette, for the same reason: a value that
+// cannot be expressed as a token in the context it's actually used. DARK
+// MODE IS NOT BAKED HERE: the result is always this fixed, light-theme
+// palette; `ui-bundle/src/css/diagram.css`'s dark-mode `invert()` filter is
+// what flips it for a reader in dark mode — same mechanism every other
+// SUPPORTED_TYPES entry's own baked-in colors already rely on, since this
+// is now one of them rather than a page-CSS-recolored special case.
+const DEFAULT_THEME_INIT = {
+  theme: 'base',
+  themeVariables: {
+    primaryColor: '#ffffff',
+    primaryBorderColor: '#000000',
+    primaryTextColor: '#000000',
+    lineColor: '#000000',
+    textColor: '#000000',
+  },
+  // Selectors and colors copied from a real render's own injected <style>
+  // block (see diagram.css's git history for the CSS-side version this
+  // replaces) — not guessed at, and not Mermaid's documented API surface
+  // (themeCSS accepts arbitrary CSS; these particular selectors are
+  // specific to the `stateDiagram-v2` type this package ships as its own
+  // example). A different Mermaid diagram type (flowchart, sequence, ...)
+  // draws through entirely different classes this won't reach — same
+  // documented limitation the old CSS-based version had.
+  themeCSS:
+    '.node rect,.statediagram-state rect.basic,.statediagram-cluster rect{rx:0!important;ry:0!important;}' +
+    // `.transition` is the edge/connector PATH itself, not an arrowhead —
+    // it always ships its own inline `fill:none` (paths are lines, never
+    // filled shapes). Setting `fill` here too (as a previous version of
+    // this rule did) beats that inline `fill:none` (an `!important`
+    // stylesheet rule always wins over a plain inline declaration,
+    // regardless of specificity) and silently turns any edge whose path
+    // happens to double back on itself — e.g. a self-loop like `G --> G`
+    // in a stateDiagram — into a solid black blob, since the now-closed-ish
+    // curve gets a fill. `stroke` is the only channel `.transition` should
+    // ever touch; arrowheads are separate elements matched below.
+    '.transition{stroke:#000000!important;}' +
+    '.marker,.node circle.state-start,[id$="-barbEnd"]{stroke:#000000!important;fill:#000000!important;}' +
+    '.node circle.state-end{fill:#000000!important;stroke:#ffffff!important;}' +
+    '.nodeLabel,.edgeLabel,.stateLabel,.cluster-label{color:#000000!important;}',
+}
+
+const INIT_DIRECTIVE = '%%{init: ' + JSON.stringify(DEFAULT_THEME_INIT) + ' }%%\n'
+
+/**
+ * Prepends this package's own default Mermaid theme to `source`, UNLESS
+ * the author already opened their diagram with their own `%%{init...}%%`
+ * directive — Mermaid only ever honors the first one, so prepending ours
+ * ahead of an author-supplied one would silently discard whatever theme (or
+ * other init-only setting) they actually asked for. An author who wants
+ * this package's own light-touch styling untouched writes a plain
+ * `stateDiagram-v2`/`flowchart`/... block, same as before this existed; one
+ * who wants their own look opts out simply by writing `%%{init...}%%`
+ * themselves — no separate attribute needed to turn this off.
+ *
+ * Both halves of this feature (kroki.js, synchronous; kroki-prewarm.js,
+ * async) must call this with the SAME input before either computing a
+ * cache key or sending anything to Kroki — the whole point of a shared,
+ * pure function rather than two independent copies.
+ *
+ * @param {string} source - the diagram's raw literal-block content, as
+ *   Asciidoctor's reader or kroki-prewarm.js's own regex handed it over.
+ * @returns {string}
+ */
+function applyDefaultMermaidTheme(source) {
+  const text = String(source)
+  if (text.trimStart().startsWith('%%{init')) return text
+  return INIT_DIRECTIVE + text
+}
+
+module.exports = { applyDefaultMermaidTheme, DEFAULT_THEME_INIT }

package/lib/kroki.js

@@ -0,0 +1,165 @@
+'use strict'
+
+const { escapeHtml } = require('./html')
+const warn = require('./warn')
+const kroki = require('./kroki-instance')
+const {
+  SUPPORTED_TYPES,
+  PNG_SUPPORTED_TYPES,
+  ENABLED_ATTR,
+  TYPES_ATTR,
+  resolveEnabledTypes,
+  resolveFormat,
+} = require('./kroki-config')
+const { applyDefaultMermaidTheme } = require('./kroki-mermaid-theme')
+
+// GH-44: renders diagram source — Mermaid, PlantUML, GraphViz, … (see
+// kroki-config.js's `SUPPORTED_TYPES`) — as an actual diagram, via a
+// self-hosted Kroki (https://kroki.io) service, instead of showing the raw
+// source as literal text.
+//
+// SYNTAX
+//
+//   [mermaid]
+//   ....
+//   stateDiagram-v2
+//   [*] --> Started
+//   ....
+//
+// A LITERAL block (four dots, not four hyphens — a `[mermaid]` block on
+// four HYPHENS is a listing block, a different context, and is not
+// intercepted here), styled with one of `SUPPORTED_TYPES`. This is exactly
+// the shape `tools/fumadocs-migrate/lib/emit.mjs` already emits for every
+// migrated `<Mermaid chart={...}>` — this extension is what turns that
+// previously-inert shape into a real diagram, nothing upstream of it
+// changes.
+//
+// `[mermaid,format=png]` renders a transparent PNG instead of inline SVG —
+// see kroki-config.js's `PNG_SUPPORTED_TYPES` for which of `SUPPORTED_TYPES`
+// actually support it (Kroki's own `/{type}/png` rejects the rest with a
+// plain 400); anything else falls back to `svg` with a warning, the same
+// degrade-not-fail posture as an unsupported `kroki-diagram-types` entry.
+//
+// OPT IN, PER SITE, DISABLED BY DEFAULT
+//
+// Every other extension in this package is unconditionally active once the
+// package is listed (see README.md's "the whole set"). This one is not: a
+// site sets two `asciidoc.attributes` in its playbook —
+//
+//   asciidoc:
+//     attributes:
+//       kroki-enabled: true
+//       kroki-diagram-types: mermaid,plantuml   # optional; omitted = every SUPPORTED_TYPES entry
+//
+// — because rendering a diagram means depending on a Kroki service actually
+// running at the fixed local URL kroki-config.js hardcodes (see that file's
+// own header for why the URL itself is NOT one of these attributes), and a
+// site that hasn't set that up should get today's plain, always-worked
+// literal-text rendering, not a build that silently produces broken
+// diagrams. `kroki-diagram-types` lets a site narrow which of
+// `SUPPORTED_TYPES` it actually wants — most sites need only `mermaid`, and
+// each additional type may need its own companion container (see the
+// sibling @inditextech/docouture-antora-extensions package's
+// resources/kroki-compose.yml, which kroki-prewarm.js starts automatically —
+// no manual setup required).
+//
+// WHY THIS BLOCK PROCESSOR NEVER MAKES THE HTTP CALL ITSELF
+//
+// Rendering via Kroki means an HTTP round trip — inherently asynchronous —
+// but `@asciidoctor/core ~2.2`'s Opal conversion loop, which is what
+// actually calls this file's `process()` during a real site build, is fully
+// synchronous (see async-compat.js's own header: a process function cannot
+// simply be `async`, that renders the literal text "[object Promise]").
+// Unlike card-grid.js's or accordion.js's own async work — `parseContent`,
+// which 4.0 makes Promise-returning but 2.2 keeps synchronous — a network
+// call has no synchronous form under EITHER major. So none happens here.
+// All of it happens up front, for the whole build, in
+// `@inditextech/docouture-antora-extensions`' `kroki-prewarm.js` — an Antora
+// PIPELINE extension (`antora.extensions`, not this package's
+// `asciidoc.extensions`) that scans the raw content aggregate for these
+// blocks and fetches every one from Kroki BEFORE Asciidoctor conversion
+// starts. This file only ever reads the result back out of the shared cache
+// (`kroki-instance.js`) — the same seam shiki-syntax-highlighter.js uses for
+// Shiki, and for the identical reason; see that file's own header.
+//
+// DEGRADATION
+//
+// Not enabled, type not requested, or a cache miss (prewarm never ran, or
+// its fetch for this exact diagram failed) all degrade to the same output:
+// the plain `<div class="literalblock">` markup Asciidoctor's own built-in
+// literal-block converter would have produced — i.e. exactly what every one
+// of these blocks already rendered as before this extension existed. A
+// missing/unreachable Kroki service is therefore never a build failure;
+// only a genuine authoring mistake (an unknown entry in
+// `kroki-diagram-types`) is, via `warn()`, per this package's own
+// "Reporting authoring mistakes" convention.
+
+/** What Asciidoctor's own literal-block HTML5 converter emits — reproduced
+ * exactly so a disabled/unavailable Kroki changes nothing an author or a
+ * reader would notice. */
+function literalFallback(source) {
+  return '<div class="literalblock"><div class="content"><pre>' + escapeHtml(source) + '</pre></div></div>'
+}
+
+function renderDiagram(parent, type, source, requestedFormat) {
+  const document = parent.getDocument()
+  const enabledAttr = document.getAttribute(ENABLED_ATTR)
+  const typesAttr = document.getAttribute(TYPES_ATTR)
+  const enabledTypes = resolveEnabledTypes(enabledAttr, typesAttr, (unknown) =>
+    warn(
+      parent,
+      '[' + TYPES_ATTR + '=' + typesAttr + ']',
+      'unknown Kroki diagram type "' + unknown + '"',
+      SUPPORTED_TYPES
+    )
+  )
+  if (!enabledTypes.has(type)) return literalFallback(source)
+
+  const format = resolveFormat(type, requestedFormat, (t, requested) =>
+    warn(
+      parent,
+      '[' + t + ',format=' + requested + ']',
+      'unsupported format "' + requested + '" for a ' + t + ' diagram — falling back to svg',
+      PNG_SUPPORTED_TYPES.has(t) ? ['svg', 'png'] : ['svg']
+    )
+  )
+  // Mermaid gets its own default theme baked in server-side (see that
+  // file's own header for why this happens here rather than via ui-bundle
+  // CSS) — applied to the LOOKUP key only; `literalFallback` below still
+  // shows the author's own original source, untouched, on a cache miss.
+  const effectiveSource = type === 'mermaid' ? applyDefaultMermaidTheme(source) : source
+
+  const payload = kroki.get(kroki.keyFor(type, effectiveSource, format))
+  if (!payload) {
+    warn(
+      parent,
+      '[' + type + ']',
+      'no prewarmed Kroki render for this diagram (service unreachable at build time, or the source changed after prewarm ran); showing raw source instead'
+    )
+    return literalFallback(source)
+  }
+  const body = payload.format === 'png' ? '<img src="data:image/png;base64,' + payload.data + '" alt="">' : payload.data
+  return '<div class="docouture-diagram" data-diagram-type="' + type + '">' + body + '</div>'
+}
+
+function krokiBlock(type) {
+  return function () {
+    this.named(type)
+    this.onContext('literal')
+    this.process((parent, reader, attrs) => {
+      // See card-grid.js's own comment: Opal (2.2) can hand this a bare JS
+      // `null` for a block with no attributes beyond its style.
+      attrs = attrs || {}
+      const source = reader.getLines().join('\n')
+      const html = renderDiagram(parent, type, source, attrs.format)
+      return this.createBlock(parent, 'pass', html, attrs)
+    })
+  }
+}
+
+module.exports = function registerKroki(registry) {
+  for (const type of SUPPORTED_TYPES) {
+    registry.block(krokiBlock(type))
+  }
+}
+module.exports.krokiBlock = krokiBlock

package/lib/label-macro.js

@@ -0,0 +1,69 @@
+'use strict'
+
+const firstPositional = require('./first-positional')
+const warn = require('./warn')
+
+// IDS Label variants shipped in `label.css` (@inditex/sewingiopdsweb-react-
+// components), already vendored into ui-bundle's ids-components.css — see
+// .opencode/skills/iop-ds-components. Anything outside this list is an
+// authoring mistake, not a themeable extension point, so it fails the build
+// (see the logger call below) instead of silently rendering unstyled.
+const VARIANTS = ['white', 'grey', 'red', 'orange', 'green', 'blue', 'purple', 'pink', 'teal']
+
+// The Datagrid cell's own default (Figma 2735:55639 light / 2735:56411
+// dark) — the one variant a table cell actually uses. Every other variant
+// exists so `label:` is useful outside a table too.
+const DEFAULT_VARIANT = 'grey'
+
+// Asciidoctor's built-in "long format" inline macro regex requires a
+// non-empty target (`\S+?` between `:` and `[`) — verified empirically
+// against both Asciidoctor versions this repo runs (2.2 for site builds,
+// 4.0 for the ui-bundle preview harness, see reference/extensions.md): a
+// bare `label:[String]` with the colour omitted never reaches `process`
+// at all under the default regex, it renders as literal text. Overriding
+// the match regexp (`self.match`, the DSL's documented escape hatch for
+// this) with our own — target group `([a-z]*)`, zero or more — is what
+// makes the empty-colour form work.
+const MACRO_RX = /\blabel:([a-z]*)\[((?:\\\]|[^\]])*?)\]/
+
+/**
+ * `label:red[Blocked]` / `label:[String]` (colour omitted → grey, the
+ * table default) →
+ *
+ *   <span class="ids-label ids-label--grey">
+ *     <span class="ids-label__content">String</span>
+ *   </span>
+ *
+ * Exactly the DS's own BEM markup (label/label.css) — every colour, every
+ * theme, comes free from the component already vendored into
+ * ids-components.css. This macro emits markup only, no styling of its own.
+ */
+module.exports = function registerLabelMacro(registry) {
+  registry.inlineMacro('label', function () {
+    // `self` is captured so `self.createInline(...)` below can still reach
+    // the processor instance from inside the nested `process` callback,
+    // where `this` is rebound to the macro's runtime context instead —
+    // Asciidoctor's own extension DSL idiom (see extend/extensions/
+    // inline-macro-processor/), not an avoidable local alias.
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this
+    self.match(MACRO_RX)
+    self.process(function (parent, target, attrs) {
+      const variant = target || DEFAULT_VARIANT
+      if (VARIANTS.indexOf(variant) === -1) {
+        warn(parent, 'label:' + target + '[]', 'unknown IDS Label variant "' + variant + '"', VARIANTS)
+      }
+      // The bracket content has already been through Asciidoctor's own
+      // `specialcharacters` substitution by the time macros run (verified:
+      // `label:[A & B <x>]` arrives here as `A &amp; B &lt;x&gt;`, both
+      // Asciidoctor versions), so it is already safe to place inside HTML
+      // without a second escaping pass. See lib/html.js's own header for the
+      // full inline-vs-block table this is one row of — an inline macro's
+      // attributes are substituted, a BLOCK's are not.
+      const text = firstPositional(attrs) || ''
+      const html =
+        '<span class="ids-label ids-label--' + variant + '"><span class="ids-label__content">' + text + '</span></span>'
+      return self.createInline(parent, 'quoted', html)
+    })
+  })
+}

package/lib/mono-macro.js

@@ -0,0 +1,41 @@
+'use strict'
+
+const firstPositional = require('./first-positional')
+
+// No variant, no target — `mono:[text]` always renders the same way, so
+// unlike `label:` there is nothing to capture before the bracket. The
+// regex still needs two groups (an empty, unused one for "target") because
+// Asciidoctor 4.0's inline-macro engine (the ui-bundle preview harness)
+// unconditionally tries to parse a second group as an attribute list and
+// throws if it's missing — verified empirically; 2.2 (site builds) doesn't
+// care either way, so the two-group shape is what's portable.
+const MACRO_RX = /\bmono:()\[((?:\\\]|[^\]])*?)\]/
+
+/**
+ * `mono:[className]` →
+ *
+ *   <code class="ids-mono">className</code>
+ *
+ * Plain monospaced text with none of the GH-12 inline-code chip
+ * (background, padding) — for a property/table cell whose ENTIRE content
+ * is a name or token (Figma 2735:55589's `className` column) where the
+ * chip would otherwise apply to literally every cell and read as noise.
+ * `` `backtick code` `` keeps its chip; this is the deliberate opt-out.
+ * The `.ids-mono` class is doc.css's own — nothing in the DS itself models
+ * "code with no surrounding treatment", so this one rule is ours to own,
+ * not a component skipped.
+ */
+module.exports = function registerMonoMacro(registry) {
+  registry.inlineMacro('mono', function () {
+    // See label-macro.js's own comment on this same pattern.
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this
+    self.match(MACRO_RX)
+    self.process(function (parent, target, attrs) {
+      // Already specialcharacters-substituted by the time macros run
+      // (verified, same as label-macro.js) — safe to place directly.
+      const text = firstPositional(attrs) || ''
+      return self.createInline(parent, 'quoted', '<code class="ids-mono">' + text + '</code>')
+    })
+  })
+}