Epic: modules render their own content, starting with brain-kit-styled diagrams that theme and print #2079

Outcome

A module can draw its own content — a markdown fence or a file type — in the chat, the file viewer and every export path, through a build-time-bundled renderer seam that Mermaid also uses. On that seam, @schlessera/brain-module-diagrams turns a versioned ```diagram spec into editorial figures that look like brain-kit: drawn with --bk-* tokens, switching with the app's light/dark theme, printing on white, with diagram-design's connector rules guaranteed by computed geometry rather than checked afterwards. The module carries a written procedure for reviewing upstream diagram-design for new types and rule changes.

Why now

The maintainer asked for diagram-design's visual quality inside brain-kit with light, dark and print support, and ruled (2026-10-16) for the full module-renderer approach in one epic, with no file-based interim. The measurements in docs/decisions/module-renderers.md showed why the module-only route cannot deliver it:

• An <img>-embedded SVG never sees @media print, so browser print keeps the screen palette.
• WebKit (all iOS browsers) does not reliably theme an <img> SVG (WebKit bug 199134 still NEW).
• An image cannot use the app's fonts under the raw-file CSP.

Inline rendering by a trusted, bundled renderer removes all three problems. The seam also retires Mermaid's three special cases and gives #905 (maps) and #1609 (charts) a path.

Shared context

• Design and ordering: docs/plans/module-renderers.md. Why: docs/decisions/module-renderers.md. Read both before picking up any task.
• Upstream: https://github.com/cathrynlavery/diagram-design (MIT). Reviewed at commit b46c970 (plugin 2.6.107). It is an agent skill, not a renderer: about 9.5k lines of reference prose, 45 type grammars, six connector rules and about 6.2k lines of Python checkers.
• Mermaid now uses the renderer seam: ui-react: Mermaid renders as a content-renderer pack and exports in the print theme #2084/CONTRACT: route Mermaid through content renderers and print tokens #2168 removes its fence/file special cases. Generic fence dispatch is (MarkdownPre, packages/ui-react/src/components/chat/brain-markdown-code.tsx:17-25), file dispatch is (ViewerBody, packages/ui-react/src/components/files/file-viewer.tsx:81-98), and the retained public share helper delegates generic rendering (inlineMermaidDiagrams, packages/ui-react/src/lib/mermaid.ts:282-284). The built-in pack supplies its print contract.
• Precedent for build-time packs: tool renderers (export function registerToolRenderers, packages/ui-sdk/src/client/renderers.ts:171; Runtime plugin loading, packages/ui-react/src/components/chat/renderers/index.ts:3).
• Module contributions are .strict() and now declare package-owned renderer exports (export interface ModuleContribution, packages/core/src/lib/module-types.ts:136-164; ModuleRenderer, same file:122-127). docs/decisions/module-mcp-tools.md is the precedent for adding a contribution kind under the shared compatibility policy.
• Tokens: --bk-diagram-* (--bk-diagram-bg: light-dark, packages/ui-kit/src/tokens.css:782-787) and the generated print theme ([data-theme="print"] {, packages/ui-kit/src/tokens.css:870).
• Example world: Odysseus only (docs/decisions/example-corpus.md). Upstream's example HTML is never vendored.

Constraints and non-goals

• Markdown stays the source of truth. The fence spec is the diagram; any SVG file is derived.
• Packs are registered by the build, never loaded at runtime from config. No renderer receives raw content markup to inject; renderers build elements from data.
• brain-kit's design system wins over upstream's skin (fonts, the 9px floor, no alpha ink, never colour alone). Upstream contributes the method.
• Theme contract: every pack implements light, dark and print. Every artifact leaving the screen uses print (decision ruling 6).
• Contract: the manifest key, the fence spec and new --json shapes are contract additions with CONTRACT: commits.
• Non-goals:
  • automatic whole-diagram layout (dagre or elk)
  • data-chart types that ui-kit's chart components cover
  • upstream's import/export tooling, icons, sketchy and terminal variants, and animation
  • a show_block kind

Breakdown

The sub-issue list carries the work. Its order is this stack plan, under docs/process/github.md § Stacked pull requests. A stack is a linear chain, so the dependency tree is cut into three stacks and some ordinary PRs. Each layer is one issue and one reviewable slice.

Stack plan

• The design/skin prerequisites are delivered. ui-kit: design brief for a free-layout diagram in the brain-kit style (architecture) #2091's revised eight-node desktop/narrow/fallback compositions were explicitly adopted by the maintainer; ui-kit: design brief for an axis diagram in the brain-kit style (sequence) #2092 and modules: diagrams paint with generated brain-kit tokens in light, dark and print #2093 are complete. Preserve their approved direction. The separate common-callout treatment modules: accepted diagram callouts disappear from client and static figures #2242 is delivered by CONTRACT: render readable common diagram callouts #2346 under its adopted N1/N2/N3 and revision 2 R1=A/R2=B rulings, including the fixed-canvas inline compatibility exception.
• Ordinary PRs on main:
  • ui-server: an .svg file previews as an image, and SVG images print light #2086 (.svg image fix): at any time.
  • modules: node-link diagram types (architecture, flowchart, state, tree, ER, dependency) #2095, modules: axis diagram types (sequence, swimlane, timeline, Gantt) #2096, modules: positional diagram types (quadrant, layers, pyramid, loop, Venn) #2097 (type families): in parallel once modules: the diagrams renderer pack draws inline, interactive, accessible figures #2094 lands. They do not depend on each other, so stacking them would invent dependencies.
  • modules: the diagram skill teaches selection, taste and the fence #2098 (skill): after the three families.
• Other repositories: shell: bundle the configured modules' renderer packs into the PWA build brain-hosting-template#33 now waits on that repository's extraction feat: pi backend parity with the Claude backend #15; delivered registration ui-react: a deployment bundles module renderer packs and flags declared-but-unbundled fences #2087 and diagrams pack modules: the diagrams renderer pack draws inline, interactive, accessible figures #2094 do not create its missing host foundation. A stack cannot cross repositories.
• Delivered foundations and module: the approved record, renderer seam/manifest/registry, Mermaid migration, shared static print path and bundling (docs: record the module-renderer decision and the diagrams plan #2080/modules: rule on reproducing upstream's MIT notice, which names a person, against the no-real-names rule #2109, ui-sdk: define the content-renderer seam and its light/dark/print conformance suite #2081–modules: scaffold the diagrams module with upstream provenance and a sync procedure #2088) are delivered. The common spec/geometry/skin/client-static pack (modules: diagrams v1 fence spec and brain diagram check #2089/modules: the diagram geometry builder enforces the connector rules by construction #2090/modules: diagrams paint with generated brain-kit tokens in light, dark and print #2093/modules: the diagrams renderer pack draws inline, interactive, accessible figures #2094), axis/positional/node-link families (modules: node-link diagram types (architecture, flowchart, state, tree, ER, dependency) #2095–modules: positional diagram types (quadrant, layers, pyramid, loop, Venn) #2097), and authoring skill (modules: the diagram skill teaches selection, taste and the fence #2098) are also delivered. Their native child receipts record immutable merge identities and source-qualified proof. The module now checks and renders shipped types. Common callouts are delivered by CONTRACT: render readable common diagram callouts #2346 / 99c67ceca1537b0fc5c6e62eca854546c9e50195: full annotations, shared per-target keys, responsive notes bands, summary indices and the approved fixed-canvas compatibility behavior. modules: brain diagram export and build, plus hygiene for external viewers #2099 is now delivered by CONTRACT: export diagrams and audit external-viewer pairs #2258 / 61c73e2037ae17e9bfe0c1d8bb4722978b2a2fc3: SVG/optional PNG/PDF export, identified GFM light/dark pairs and ownership/freshness hygiene with embedded painted fonts. The full epic definition of done and the generated-host foundation remain open; modules: accepted diagram callouts disappear from client and static figures #2242 is complete.
• Selection: Under process: decide how an issue that depends only on an open lower stack layer becomes selectable #2137 option A, a blocked upper layer is selectable only after every remaining open blocker is verified as an open, non-draft lower PR in this epic's declared stack with complete passing selected proof for its current parent/head candidate. Verify actual membership and the immediate parent before claiming and again before checkout creation; start from that verified head. Any genuine needs: label, non-stack blocker or unavailable/failed/cancelled/unexpectedly skipped proof rejects selection. Preserve canonical Blocked by lines and blocked for open dependencies; a merged parent uses ordinary reconciliation and fetched main. Each layer owner refreshes their own layer bottom-up after parent changes, with explicit ownership handoff when absent. The stack merger verifies each included issue's delivered identities, acceptance/proof and release milestones and closes only completed issues. Native-stack candidate qualification remains separately subject to ci: native stacked PR events do not match contract and candidate identity guards #2141. Its October 22 ruling parks frozen-prefix verification/integrator work until serial candidate confirmation returns as the merge workflow; the earlier B/A policies remain binding only if that work resumes. The declared stack order is delivery history for the now-merged layers, not an instruction to revive the parked native verifier. Remaining work follows its own current brief; ordinary PRs retain their declared dependencies and reconstruct only their own diff after predecessors land.
• Branches and proof: each layer issue names its branch and parent, and its verification runs check:pr --base <parent-ref>.

Current remaining native work — 2026-10-22

#2228 is delivered by #2369 (af0547c): fit frames include computed group/heading extents and fixed/narrow frames report clipped bounds. #2241 is delivered by #2368 (b7a0885): viewer proof selects the actual diagram and requires its expected text population before enforcing the font floor. Both merges are ancestors of inspected main a310317, and the corresponding geometry/viewer guards are present. Consume their original qualified closure receipts; this triage does not rerun or independently re-audit their historical hosted jobs.

The native open child list is now only schlessera/brain-hosting-template#33 (still waiting on that repository’s extraction #15) and #2469 (the existing identical-source free-layout raster-parity investigation, still needs: repro). The fully scoped generated-host work and the missing natural raster-failure evidence remain distinct. Closed foundations, export, bounds and proof fixes do not establish the complete integrated/host outcome below. Preserve the full definition of done and keep this epic open without agent-ready.

Definition of done

• A ```diagram fence written by the agent in chat renders inline in light and dark, follows the theme toggle on Chromium and WebKit, and prints white from the browser and from share → PDF. Each is shown with a capture in the closing comment.
• Mermaid renders identically through the seam, and its old special cases are deleted.
• Every first-party pack (Mermaid, diagrams) passes contentRendererConformance, and a share → PDF holding both a Mermaid chart and a diagram shows one white ground.
• docs/modules.md, docs/extending/README.md and the integration contract describe the seam, the manifest key and the spec.
• packages/module-diagrams/UPSTREAM.md exists, and one dry-run review against upstream HEAD has been recorded in a PR.

2026-10-16: the breakdown became a stack plan (stacked PRs, #1997). #2109 was added for the licence ruling and #2137 for stack selection.

2026-10-16 triage at main 8822aedeeac8b824bafe120c20a9b58c4cd1f4e6: replaced unavailable main links with the inspected immutable #2102 proposal and updated the resolved-versus-undelivered stack-policy distinction. The content-renderer decision is proposed documentation awaiting merge, not shipped renderer capability; preserve the existing stack plan, native membership and full definition of done.

2026-10-16 triage at main 80e028d84b7686d6cf864d8166029b1142de8756: replaced proposal-only links with the delivered decision identity and folded verified foundation deliveries into the current breakdown. Existing Mermaid fallback special cases remain until #2084; generic dispatch does not complete their migration. Preserved design revisions/final sign-off, ordinary delivery fallback, stack dependencies and the complete definition of done. Recorded focused/native receipts are not a new independent full-main CI audit.

2026-10-16 delivery reconciliation: #2089 delivered the common v1 spec, check command and contract in #2167. The next Stack B layer #2090 uses fetched main; the remaining definition of done and declared dependencies are unchanged.

2026-10-16 triage at main 4ba792473152c89eb74c286fc914e54ca1dae8fc: reconciled the active specification with closed child outputs and merged source, replacing obsolete Mermaid special-case and pending-foundation statements. The approved design/skin/families/skill are delivered; dedicated exports, common callout treatment, generated-host foundation and complete integrated proof remain separate. Local/source-qualified receipts are not an independent full current hosted audit; preserve the original definition of done and epic-not-ready status.

2026-10-17 triage at main ecb87487d714956b0fcef520debe9dfa885b234f: folded the closed export/build child into the active delivery summary after reading its closure, immutable delivery and qualified artifact/font receipts. #2242 retains its newly documented crowded/semantic-only fallback design gap and approved N1/N2/N3 rulings; no annotation approval or complete epic outcome is inferred. Existing source-qualified proof is not a new independent hosted audit.

2026-10-22 native-output reconciliation: folded the two delivered bounds/viewer-proof repairs and current native open-child scope into the active brief. Original failure and qualification receipts retain their actual source identities; no new renderer runtime, generated-host result or epic-completion proof is claimed.

2026-10-24 continued triage at main dc5d3c73282c29a3f0098306d398743ee18ec791: Reconciled the active #2141 reference with its later parked-workflow ruling. All renderer/diagram deliveries and the remaining generated-host #33 and raster-attribution #2469 outcomes remain distinct. No native candidate support, stack action, new renderer proof or epic completion is claimed.