dsh-model-everything 0.4.0 → 0.5.0

package/src/render/from-plantuml.ts

@@ -0,0 +1,178 @@
+/**
+ * PlantUML text to a diagram, for the subset this renderer can actually draw.
+ *
+ * PlantUML is a large language, and a renderer that accepted all of it would be a re-implementation of
+ * PlantUML. This one accepts what an architecture document actually contains - boxes, groups and arrows -
+ * and refuses the rest **by line**, because a component diagram that quietly loses a lifeline reads as
+ * complete and is not.
+ *
+ * Supported:
+ *
+ * - `@startuml` / `@enduml` (optional) and `title ...`;
+ * - `component X`, `component "text" as X`, `[text] as X`, `[text]`;
+ * - `package "text" { ... }`, `node`, `folder`, `cloud`, `database` - a group, closed by `}`;
+ * - `X --> Y`, `X ---> Y`, `X ..> Y`, `X --> Y : label`, arrow either direction;
+ * - `state X`, `state "text" as X`, and `[*] --> X` for a start marker;
+ * - `'` comments and `skinparam`/`!theme` directives.
+ *
+ * Refused, by name: `sequence`, `actor`, `participant`, `usecase`, `class`, `object`, `note`, `legend`,
+ * `alt`/`opt`/`loop`/`par` and any other fragment keyword.
+ */
+
+import { emptyDiagram, type Diagram, type DiagramEdge, type DiagramGroup, type DiagramNode } from './model.js'
+
+export interface Parsed {
+  diagram: Diagram
+  /** Lines the parser refused to interpret, with the reason. Empty when the whole source was understood. */
+  refused: string[]
+}
+
+const ARROW = /^(.+?)\s*(<?)(-{2,}|\.{2,})(>?)\s*(.+?)(?:\s*:\s*(.+))?$/
+const DECLARED = /^(component|package|node|folder|cloud|database|state|artifact|frame|rectangle)\s+(.+)$/
+const QUOTED_ALIAS = /^["'](.+?)["']\s+as\s+([A-Za-z_][\w-]*)$/
+const BRACKET_ALIAS = /^\[(.+?)\]\s+as\s+([A-Za-z_][\w-]*)$/
+const BRACKET = /^\[(.+?)\]$/
+const UNSUPPORTED = /^(actor|participant|usecase|class|object|note|legend|alt|opt|loop|par|group\s|ref\s|activate|deactivate|destroy|create|newpage)\b/
+const IGNORED = /^(skinparam|!theme|!define|!include|hide|show|scale|left to right direction|top to bottom direction|together)\b/
+
+interface Builder {
+  nodes: Map<string, DiagramNode>
+  edges: DiagramEdge[]
+  groups: DiagramGroup[]
+  open: DiagramGroup[]
+}
+
+function ensure(builder: Builder, id: string, label?: string): void {
+  const existing = builder.nodes.get(id)
+  if (existing === undefined) {
+    builder.nodes.set(id, { id, role: 'normal', ...(label === undefined ? {} : { label }) })
+    // Membership is decided where the node is first written: the innermost open boundary.
+    const innermost = builder.open[builder.open.length - 1]
+    if (innermost !== undefined && !innermost.members.includes(id)) innermost.members.push(id)
+    return
+  }
+  if (label !== undefined && (existing.label === undefined || existing.label === '')) existing.label = label
+}
+
+/** A component reference: `[text]`, `X`, or a quoted name. Returns the id and the label it carried. */
+function reference(token: string): { id: string; label?: string } {
+  const text = token.trim()
+  const bracket = BRACKET.exec(text)
+  if (bracket !== null) {
+    const label = bracket[1].trim()
+    return { id: label, label }
+  }
+  const quoted = /^["'](.+?)["']$/.exec(text)
+  if (quoted !== null) return { id: quoted[1], label: quoted[1] }
+  return { id: text }
+}
+
+export function fromPlantUml(source: string, title = 'plantuml'): Parsed {
+  const lines = source.split(/\r?\n/)
+  const refused: string[] = []
+  const builder: Builder = { nodes: new Map(), edges: [], groups: [], open: [] }
+  let startId: string | undefined
+  let seenAny = false
+  let groupCount = 0
+
+  lines.forEach((raw, index) => {
+    const line = raw.replace(/'.*$/, '').trim()
+    if (line === '') return
+    const where = 'line ' + String(index + 1) + ': '
+
+    if (/^@(start|end)uml\b/.test(line)) return
+    seenAny = true
+    if (/^title\b/.test(line)) return
+    if (IGNORED.test(line)) return
+    if (UNSUPPORTED.test(line)) {
+      refused.push(where + '`' + (line.split(/\s/)[0] ?? '') + '` is not a diagram this renderer draws')
+      return
+    }
+
+    if (line === '}') {
+      const closing = builder.open.pop()
+      if (closing !== undefined) {
+        const container = builder.open[builder.open.length - 1]
+        if (container !== undefined) closing.parent = container.id
+        builder.groups.push(closing)
+      }
+      return
+    }
+
+    if (line.endsWith('{')) {
+      const declaration = line.slice(0, -1).trim()
+      const declared = DECLARED.exec(declaration)
+      const label = declared === null ? declaration.replace(/^["']|["']$/g, '') : declared[2].replace(/^["']|["']$/g, '')
+      groupCount += 1
+      builder.open.push({ id: 'group-' + String(groupCount), label, members: [] })
+      return
+    }
+
+    const declared = DECLARED.exec(line)
+    if (declared !== null) {
+      const rest = declared[2].trim()
+      const quoted = QUOTED_ALIAS.exec(rest)
+      if (quoted !== null) {
+        ensure(builder, quoted[2], quoted[1])
+        return
+      }
+      const bracketed = BRACKET_ALIAS.exec(rest)
+      if (bracketed !== null) {
+        ensure(builder, bracketed[2], bracketed[1])
+        return
+      }
+      if (/^["'](.+?)["']$/.test(rest)) return // a group heading with no alias: nothing to draw
+      const reference_ = reference(rest)
+      ensure(builder, reference_.id, reference_.label)
+      return
+    }
+
+    if (line === '[*] --> [*]') return
+
+    const startMarker = /^\[\*\]\s*-->\s*(.+)$/.exec(line)
+    if (startMarker !== null) {
+      const target = reference(startMarker[1])
+      ensure(builder, target.id, target.label)
+      if (startId === undefined) startId = target.id
+      return
+    }
+
+    const arrow = ARROW.exec(line)
+    if (arrow !== null) {
+      const left = arrow[2] === '<' ? arrow[5] : arrow[1]
+      const right = arrow[2] === '<' ? arrow[1] : arrow[5]
+      const from = reference(left)
+      const to = reference(right)
+      ensure(builder, from.id, from.label)
+      ensure(builder, to.id, to.label)
+      builder.edges.push({ from: from.id, to: to.id, label: (arrow[6] ?? '').trim(), ...(arrow[3].startsWith('.') ? { dashed: true } : {}) })
+      return
+    }
+
+    const single = BRACKET.exec(line)
+    if (single !== null) {
+      ensure(builder, single[1].trim(), single[1].trim())
+      return
+    }
+
+    refused.push(where + '`' + line + '` is not something this renderer draws')
+  })
+
+  if (!seenAny || builder.nodes.size === 0) {
+    return { diagram: emptyDiagram(title, 'no nodes found'), refused }
+  }
+
+  const diagram: Diagram = {
+    kind: startId === undefined ? 'graph' : 'machine',
+    title,
+    ...(startId === undefined ? {} : { init: startId }),
+    nodes: [...builder.nodes.values()],
+    edges: builder.edges,
+    ...(builder.groups.length === 0 ? {} : { groups: builder.groups }),
+    caption:
+      'plantuml, ' + String(builder.nodes.size) + ' box' + (builder.nodes.size === 1 ? '' : 'es') + ', ' +
+      String(builder.edges.length) + ' arrow' + (builder.edges.length === 1 ? '' : 's') +
+      (refused.length === 0 ? '' : ', ' + String(refused.length) + ' line(s) refused'),
+  }
+  return { diagram, refused }
+}

package/src/render/index.ts

@@ -0,0 +1,73 @@
+/**
+ * The renderer's front door: whatever notation arrived, one drawing comes out.
+ *
+ * Three containers read this - the tool card, the full-screen view and the sidebar whiteboard - and each of
+ * them wants the same two things: shapes to draw and markup to embed. Neither knows which notation produced
+ * them, and neither needs to.
+ *
+ * Pure: no filesystem, because the same module is bundled into the page for the whiteboard.
+ */
+
+import { fromMermaid } from './from-mermaid.js'
+import { collapse } from './collapse.js'
+import { fromPlantUml } from './from-plantuml.js'
+import type { Diagram } from './model.js'
+import { paintWith, type Canvas } from './paint.js'
+import type { Palette, PaletteOptions } from './palette.js'
+import { toSvg } from './svg.js'
+
+export type Notation = 'mermaid' | 'plantuml'
+
+export interface RenderInput {
+  /** The notation, or `auto` to read it off the first non-empty line. */
+  notation?: Notation | 'auto'
+  source: string
+  title?: string
+  /** Groups folded to a single box. Ids nobody declared are ignored. */
+  folded?: Iterable<string>
+}
+
+export interface Rendered {
+  diagram: Diagram
+  canvas: Canvas
+  /** The colours the drawing was made with, so a container can paint the same surface behind it. */
+  colours: Palette
+  /** Ready to embed: an `<svg>` with a viewBox and no fixed pixel size of its own. */
+  markup: string
+  /** Which notation the source turned out to be. */
+  notation: Notation
+  /** Lines the parser refused, with their reason. Empty when the whole source was understood. */
+  refused: string[]
+  /** Shapes the SVG writer had no case for. Must be zero; reported rather than hidden. */
+  dropped: number
+}
+
+/** Read the notation off the source: PlantUML starts with `@startuml` or `@startmindmap`-style markers. */
+export function detectNotation(source: string): Notation {
+  const head = source
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line !== '' && !line.startsWith("'") && !line.startsWith('//'))
+  if (head === undefined) return 'mermaid'
+  return /^@start/.test(head) ? 'plantuml' : 'mermaid'
+}
+
+export function render(input: RenderInput, overrides: Partial<Palette> = {}, options: PaletteOptions = {}): Rendered {
+  const notation = input.notation === undefined || input.notation === 'auto' ? detectNotation(input.source) : input.notation
+  const parsed =
+    notation === 'plantuml'
+      ? fromPlantUml(input.source, input.title ?? 'plantuml')
+      : fromMermaid(input.source, input.title ?? 'mermaid')
+  const diagram = input.folded === undefined ? parsed.diagram : collapse(parsed.diagram, input.folded)
+  const { canvas, colours } = paintWith(diagram, overrides, options)
+  const written = toSvg(canvas, colours, diagram.title + ': ' + diagram.caption)
+  return {
+    diagram,
+    canvas,
+    colours,
+    markup: written.markup,
+    notation,
+    refused: parsed.refused,
+    dropped: written.dropped,
+  }
+}

package/src/render/layout.ts

@@ -0,0 +1,62 @@
+/**
+ * Ranks for a machine, and the order of states within each rank.
+ *
+ * Breadth-first from the initial state decides the row: the layout a reader expects, and the one a layered
+ * drawing asks for - edges mostly flow down, and a state's row is how far it is from the start. A state
+ * nothing reaches goes in a block of its own rather than being dropped.
+ *
+ * Within a row, states keep the order breadth-first found them in: a row is filled by walking the row above
+ * left to right, so a state already sits under the parent that discovered it. A barycentre pass was written
+ * and removed - with breadth-first insertion it could never move a state, so it was complexity without an
+ * observable effect.
+ *
+ * Pure, and asserted on the rows themselves.
+ */
+
+import type { DiagramEdge, DiagramNode } from './model.js'
+
+export interface Ranked {
+  /** The state ids of each row, top to bottom, already ordered left to right. */
+  rows: string[][]
+  /** States no edge reaches from the initial one. */
+  unreachable: string[]
+}
+
+export function rankStates(nodes: DiagramNode[], edges: DiagramEdge[], init: string | undefined): Ranked {
+  const ids = nodes.map((node) => node.id)
+  const known = new Set(ids)
+  const start = init !== undefined && known.has(init) ? init : ids[0]
+
+  const outgoing = new Map<string, string[]>()
+  const incoming = new Map<string, string[]>()
+  for (const edge of edges) {
+    if (!known.has(edge.from) || !known.has(edge.to)) continue
+    outgoing.set(edge.from, [...(outgoing.get(edge.from) ?? []), edge.to])
+    incoming.set(edge.to, [...(incoming.get(edge.to) ?? []), edge.from])
+  }
+
+  const depth = new Map<string, number>()
+  if (start !== undefined) {
+    depth.set(start, 0)
+    const queue: string[] = [start]
+    while (queue.length > 0) {
+      const id = queue.shift() as string
+      const level = depth.get(id) as number
+      for (const target of outgoing.get(id) ?? []) {
+        if (depth.has(target)) continue
+        depth.set(target, level + 1)
+        queue.push(target)
+      }
+    }
+  }
+
+  const rows: string[][] = []
+  for (const id of ids) {
+    const level = depth.get(id)
+    if (level === undefined) continue
+    while (rows.length <= level) rows.push([])
+    rows[level].push(id)
+  }
+
+  return { rows, unreachable: ids.filter((id) => !depth.has(id)) }
+}

package/src/render/model.ts

@@ -0,0 +1,67 @@
+/**
+ * The diagram a renderer draws, in the notation it came from being nobody's business.
+ *
+ * Every source - a verification report, a Mermaid file, a PlantUML component diagram, a dependency scan -
+ * is reduced to this one shape before anything is laid out. A renderer that understood notations would have
+ * to be changed for each of them; a renderer that understands this does not.
+ *
+ * Pure data, no functions: a model can be serialised, compared and asserted.
+ */
+
+/** What a node is, as far as colour is concerned. */
+export type NodeRole = 'normal' | 'error' | 'warning' | 'muted'
+
+export interface DiagramNode {
+  id: string
+  /** The text drawn inside the box. Defaults to the id when a notation labelled it. */
+  label?: string
+  role: NodeRole
+}
+
+export interface DiagramEdge {
+  from: string
+  to: string
+  label: string
+  /** A dashed edge, for notations that distinguish one. */
+  dashed?: boolean
+}
+
+export interface DiagramGroup {
+  id: string
+  label: string
+  /**
+   * The nodes declared directly inside it: a group is a box around boxes, and its own members are the ones a
+   * source named there. A node inside a nested group is that group's member, not this one's.
+   */
+  members: string[]
+  /**
+   * The group that contains this one, when the source said so.
+   *
+   * Only a parser can know this - nesting is a property of where the text put the boundary - so the layout does
+   * not guess it. Left absent, the painter falls back to inferring containment from member sets, which is the
+   * best a hand-written model can offer.
+   */
+  parent?: string
+}
+
+export interface Diagram {
+  kind: 'machine' | 'graph' | 'none'
+  /** The state the machine starts in, when the source declared one. */
+  init?: string
+  title: string
+  nodes: DiagramNode[]
+  edges: DiagramEdge[]
+  groups?: DiagramGroup[]
+  /** One line under the drawing: what was decided, in words the drawing cannot carry. */
+  caption: string
+}
+
+/** An empty drawing, for a source that produced no nodes. */
+export function emptyDiagram(title: string, caption: string): Diagram {
+  return { kind: 'none', title, nodes: [], edges: [], caption }
+}
+
+/** The label to draw for a node: its own label when the notation gave one, else its id. */
+export function labelOf(node: DiagramNode): string {
+  return node.label !== undefined && node.label !== '' ? node.label : node.id
+}

package/src/render/paint.ts

@@ -0,0 +1,290 @@
+/**
+ * Geometry: what a diagram turns into, in coordinates.
+ *
+ * A drawing has to survive three containers - inline in a conversation, full-screen, and a persistent
+ * sidebar tab - so nothing here knows about pixel size. It emits a content-sized canvas and lets the
+ * container scale it: the same numbers serve a 360px card and a 1200px whiteboard.
+ *
+ * Two placements, chosen by the source:
+ *
+ * - **layered** (no groups): breadth-first rows, forward edges dropping straight down, back edges on a side
+ *   channel clear of every box, self loops as small loops. The shape a state machine wants.
+ * - **tree** (groups present): a group is a block, its members stack inside it, a nested group is a block
+ *   inside its parent, and the top level stacks. The shape an architecture diagram wants, because a package
+ *   whose members float somewhere else on the page is not showing containment at all.
+ *
+ * Edges are placed from where the boxes ended up, so neither placement needs to tell the edge code which one
+ * ran: "below" is a straight line, "beside" is horizontal, "above" routes around.
+ *
+ * Pure: a diagram in, shapes out, every decision assertable.
+ */
+
+import { MARGIN, place, type Box } from './place.js'
+import { palette, roleForVerdict, type ColourRole, type Palette, type PaletteOptions } from './palette.js'
+import { labelOf, type Diagram, type DiagramGroup, type DiagramNode } from './model.js'
+
+export interface Point {
+  x: number
+  y: number
+}
+
+export interface BoxShape {
+  kind: 'box'
+  x: number
+  y: number
+  width: number
+  height: number
+  label: string
+  colour: ColourRole
+  initial: boolean
+}
+
+export interface LinkShape {
+  kind: 'link'
+  x1: number
+  y1: number
+  x2: number
+  y2: number
+  label: string
+  labelX: number
+  labelY: number
+  colour: ColourRole
+}
+
+export interface PathShape {
+  kind: 'path'
+  points: Point[]
+  label: string
+  labelX: number
+  labelY: number
+  colour: ColourRole
+}
+
+/** A boundary around several states: a package, a layer, a subgraph. */
+export interface GroupShape {
+  kind: 'group'
+  /** The group's own id, so a container can fold it without guessing from the label. */
+  id: string
+  x: number
+  y: number
+  width: number
+  height: number
+  label: string
+  colour: ColourRole
+}
+
+export interface CaptionShape {
+  kind: 'caption'
+  x: number
+  y: number
+  lines: string[]
+  colour: ColourRole
+}
+
+export interface TitleShape {
+  kind: 'title'
+  x: number
+  y: number
+  text: string
+  colour: ColourRole
+}
+
+export type Shape = GroupShape | BoxShape | LinkShape | PathShape | CaptionShape | TitleShape
+
+export interface Canvas {
+  width: number
+  height: number
+  shapes: Shape[]
+}
+
+/** Geometry constants in one place: a container with different proportions changes these, not the rules. */
+const MIN_NODE_WIDTH = 88
+const MAX_NODE_WIDTH = 220
+const CHAR_WIDTH = 7.2
+
+const nodeWidth = (label: string): number => Math.min(MAX_NODE_WIDTH, Math.max(MIN_NODE_WIDTH, label.length * CHAR_WIDTH + 26))
+
+const TITLE_HEIGHT = 26
+const NODE_HEIGHT = 34
+const CHANNEL_GAP = 16
+const CAPTION_CHARS = 78
+const CAPTION_LINE = 15
+const CAPTION_GAP = 16
+const CAPTION_CHAR_WIDTH = 6.2
+
+/** Which colour a box earns from its role. One mapping, used by every container. */
+export function roleOfNode(node: DiagramNode): ColourRole {
+  if (node.role === 'error') return 'fail'
+  if (node.role === 'warning') return 'findings'
+  if (node.role === 'muted') return 'muted'
+  return 'edge'
+}
+
+/** Wrap on spaces; break a token longer than the line rather than let it overflow the canvas. */
+function wrap(text: string, limit: number): string[] {
+  const lines: string[] = []
+  let line = ''
+  for (const word of text.split(/\s+/).filter((part) => part !== '')) {
+    const candidate = line === '' ? word : line + ' ' + word
+    if (candidate.length <= limit) {
+      line = candidate
+      continue
+    }
+    if (line !== '') lines.push(line)
+    line = ''
+    let rest = word
+    while (rest.length > limit) {
+      lines.push(rest.slice(0, limit))
+      rest = rest.slice(limit)
+    }
+    line = rest
+  }
+  if (line !== '') lines.push(line)
+  return lines.length === 0 ? [''] : lines
+}
+
+/** The colour a caption earns, read from the verdict it quotes. */
+function captionRole(caption: string): ColourRole {
+  return roleForVerdict(caption.split(' — ')[0] as string)
+}
+
+export function paintWith(diagram: Diagram, overrides: Partial<Palette> = {}, options: PaletteOptions = {}): { canvas: Canvas; colours: Palette } {
+  const colours = palette(overrides, options)
+  const shapes: Shape[] = []
+
+  const groups = diagram.groups ?? []
+  const topOffset = MARGIN + TITLE_HEIGHT
+  const placement = place(diagram, topOffset)
+  const { boxes, groupRects } = placement
+
+  // Boundaries first, so everything else is painted on top of them.
+  for (const group of groups) {
+    const rect = groupRects.get(group.id)
+    if (rect === undefined) continue
+    shapes.push({ kind: 'group', id: group.id, x: rect.x, y: rect.y, width: rect.width, height: rect.height, label: group.label, colour: 'muted' })
+  }
+
+  const drawn = new Set<string>()
+  for (const node of diagram.nodes) {
+    // A state id may repeat in a malformed model: the first placement wins and the repeat is skipped.
+    if (drawn.has(node.id)) continue
+    const box = boxes.get(node.id) as Box
+    drawn.add(node.id)
+    shapes.push({
+      kind: 'box',
+      x: box.x,
+      y: box.y,
+      width: box.width,
+      height: box.height,
+      label: labelOf(node),
+      colour: roleOfNode(node),
+      initial: diagram.init === node.id,
+    })
+  }
+
+  const roleById = new Map(diagram.nodes.map((node) => [node.id, roleOfNode(node)] as const))
+  let channel = Math.max(placement.width, ...Array.from(boxes.values(), (box) => box.x + box.width)) + CHANNEL_GAP
+  let channelUses = 0
+
+  for (const edge of diagram.edges) {
+    const source = boxes.get(edge.from)
+    const target = boxes.get(edge.to)
+    if (source === undefined || target === undefined) continue
+    const colour = roleById.get(edge.from) as ColourRole
+    // Placement decided where things are; "below", "beside" and "above" are read from the result.
+    const sameRow = Math.abs(target.y - source.y) < NODE_HEIGHT / 2
+
+    if (edge.from === edge.to) {
+      const x = source.x + source.width
+      const y = source.y + source.height / 2
+      shapes.push({
+        kind: 'path',
+        points: [
+          { x, y: y - 9 },
+          { x: x + 14, y: y - 9 },
+          { x: x + 14, y: y + 9 },
+          { x, y: y + 9 },
+        ],
+        label: edge.label,
+        labelX: x + 20,
+        labelY: y,
+        colour,
+      })
+      continue
+    }
+
+    if (target.y > source.y && !sameRow) {
+      const x1 = source.x + source.width / 2
+      const y1 = source.y + source.height
+      const x2 = target.x + target.width / 2
+      const y2 = target.y
+      shapes.push({ kind: 'link', x1, y1, x2, y2, label: edge.label, labelX: (x1 + x2) / 2 + 7, labelY: (y1 + y2) / 2, colour })
+      continue
+    }
+
+    if (sameRow) {
+      const right = source.x + source.width
+      const left = target.x
+      const y = source.y + source.height / 2
+      const forward = right <= left
+      shapes.push({
+        kind: 'link',
+        x1: forward ? right : source.x,
+        y1: y,
+        x2: forward ? left : target.x + target.width,
+        y2: y,
+        label: edge.label,
+        labelX: (right + left) / 2,
+        labelY: y - 7,
+        colour,
+      })
+      continue
+    }
+
+    // Backward: leave right, run down a lane clear of every box, come back in from the right.
+    const lane = channel + (channelUses % 3) * 8
+    channelUses += 1
+    channel = Math.max(channel, lane)
+    const startY = source.y + source.height / 2
+    const endY = target.y + target.height / 2
+    shapes.push({
+      kind: 'path',
+      points: [
+        { x: source.x + source.width, y: startY },
+        { x: lane, y: startY },
+        { x: lane, y: endY },
+        { x: target.x + target.width, y: endY },
+      ],
+      label: edge.label,
+      labelX: lane + 6,
+      labelY: (startY + endY) / 2,
+      colour,
+    })
+  }
+
+  shapes.push({ kind: 'title', x: MARGIN, y: MARGIN + 12, text: diagram.title, colour: 'text' })
+
+  const contentRight = Math.max(
+    MARGIN,
+    ...Array.from(boxes.values(), (box) => box.x + box.width),
+    ...Array.from(groupRects.values(), (rect) => rect.x + rect.width),
+  )
+  const captionLines = wrap(diagram.caption, CAPTION_CHARS)
+  const captionWidth = Math.max(...captionLines.map((line) => line.length * CAPTION_CHAR_WIDTH)) + MARGIN * 2
+  const width = Math.max(contentRight + MARGIN + (channelUses > 0 ? CHANNEL_GAP * 3 : 0), captionWidth, 240)
+
+  const contentBottom = Math.max(
+    topOffset,
+    ...Array.from(boxes.values(), (box) => box.y + box.height),
+    ...Array.from(groupRects.values(), (rect) => rect.y + rect.height),
+  )
+  const captionTop = contentBottom + CAPTION_GAP
+  shapes.push({ kind: 'caption', x: MARGIN, y: captionTop, lines: captionLines, colour: captionRole(diagram.caption) })
+  const height = captionTop + captionLines.length * CAPTION_LINE + MARGIN / 2
+
+  return { canvas: { width: Math.round(width), height: Math.round(height), shapes }, colours }
+}
+
+export function paint(diagram: Diagram, overrides: Partial<Palette> = {}): Canvas {
+  return paintWith(diagram, overrides).canvas
+}