dsh-model-everything 0.4.0 → 0.5.0

package/src/render/palette.ts

@@ -0,0 +1,164 @@
+/**
+ * Verdict to colour, in the two surfaces the page can be in, and in the scheme a reader prefers.
+ *
+ * A drawing is read before it is parsed, so the first thing it says is the answer. The roles are named rather
+ * than coloured: a scheme maps a role to a value, and every scheme is chosen so the drawing survives both a
+ * light and a dark page - the reader never has to fix a palette to read a result.
+ *
+ * The mode is read at render time from the page's own background (see `client.ts`). The host publishes its
+ * palette as CSS variables whose names are private to it, and a drawing that hard-coded them would break on
+ * the next theme; the luminance of the surface is the one fact that cannot drift.
+ *
+ * Pure, and tested: a wrong role is a wrong verdict shown as a shape.
+ */
+
+export type ColourRole =
+  | 'pass'
+  | 'findings'
+  | 'fail'
+  | 'undecided'
+  | 'muted'
+  | 'text'
+  | 'edge'
+  | 'surface'
+  | 'background'
+
+export type Palette = Record<ColourRole, string>
+
+/** Which surface the drawing will sit on. */
+export type PaletteMode = 'light' | 'dark'
+
+/** A named set of colours. A scheme with both variants follows the page; one with only light does not. */
+export type PaletteScheme = 'default' | 'github' | 'high-contrast' | 'print'
+
+/** Ours: a quiet neutral drawing, with a green/amber/red answer. */
+const NEUTRAL_LIGHT: Palette = {
+  pass: '#2f8f5b',
+  findings: '#b7791f',
+  fail: '#c0392b',
+  undecided: '#6b7280',
+  muted: '#9aa3ad',
+  text: '#1f2933',
+  edge: '#6b7280',
+  surface: 'transparent',
+  background: '#ffffff',
+}
+
+const NEUTRAL_DARK: Palette = {
+  pass: '#4ac486',
+  findings: '#e0b050',
+  fail: '#f2705f',
+  undecided: '#9aa3ad',
+  muted: '#7d8794',
+  text: '#e6e8eb',
+  edge: '#8b949e',
+  surface: 'transparent',
+  background: '#0d1117',
+}
+
+/**
+ * GitHub's own palette, light: the colours a reader already knows from the place they keep the diagram.
+ * Values are Primer's foreground and canvas tokens, not invented for this plugin.
+ */
+const GITHUB_LIGHT: Palette = {
+  pass: '#1a7f37',
+  findings: '#9a6700',
+  fail: '#cf222e',
+  undecided: '#656d76',
+  muted: '#8c959f',
+  text: '#1f2328',
+  edge: '#656d76',
+  surface: 'transparent',
+  background: '#ffffff',
+}
+
+/** GitHub dark default: canvas #0d1117, foreground #e6edf3. */
+const GITHUB_DARK: Palette = {
+  pass: '#3fb950',
+  findings: '#d29922',
+  fail: '#f85149',
+  undecided: '#7d8590',
+  muted: '#6e7681',
+  text: '#e6edf3',
+  edge: '#7d8590',
+  surface: 'transparent',
+  background: '#0d1117',
+}
+
+/** Black on white, for a projector or a poor print. The shape carries the meaning, not the hue. */
+const HIGH_CONTRAST: Palette = {
+  pass: '#0a5c35',
+  findings: '#7a4300',
+  fail: '#a30000',
+  undecided: '#333333',
+  muted: '#444444',
+  text: '#000000',
+  edge: '#000000',
+  surface: 'transparent',
+  background: '#ffffff',
+}
+
+/** Greyscale throughout: a drawing that will be printed on a black-and-white printer. */
+const PRINT: Palette = {
+  pass: '#333333',
+  findings: '#555555',
+  fail: '#000000',
+  undecided: '#666666',
+  muted: '#777777',
+  text: '#000000',
+  edge: '#333333',
+  surface: 'transparent',
+  background: '#ffffff',
+}
+
+interface Scheme {
+  light: Palette
+  /** Absent when the scheme is deliberately the same on both surfaces. */
+  dark?: Palette
+}
+
+const SCHEMES: Record<PaletteScheme, Scheme> = {
+  default: { light: NEUTRAL_LIGHT, dark: NEUTRAL_DARK },
+  github: { light: GITHUB_LIGHT, dark: GITHUB_DARK },
+  'high-contrast': { light: HIGH_CONTRAST },
+  print: { light: PRINT },
+}
+
+export interface PaletteOptions {
+  mode?: PaletteMode
+  scheme?: PaletteScheme
+}
+
+/**
+ * Resolve a palette.
+ *
+ * `overrides` win over everything, so a caller can retheme one role without inventing a scheme. A scheme with
+ * a dark variant follows the surface; one without stays as declared - high-contrast and print are what they
+ * say they are, on purpose. An unknown name falls back to the default palette rather than throwing, because
+ * the value can arrive from a DOM control.
+ */
+export function palette(overrides: Partial<Palette> = {}, options: PaletteOptions = {}): Palette {
+  const scheme = options.scheme ?? 'default'
+  const mode = options.mode ?? 'light'
+  const chosen = SCHEMES[scheme] ?? SCHEMES.default
+  const base = mode === 'dark' ? (chosen.dark ?? chosen.light) : chosen.light
+  return { ...base, ...overrides }
+}
+
+/**
+ * The role a verdict earns.
+ *
+ * `pass_with_findings` is deliberately not `pass`: it reads as the middle band, because a card that paints a
+ * report with warnings the same colour as a clean one has stopped carrying the answer.
+ */
+export function roleForVerdict(verdict: string | undefined): ColourRole {
+  if (verdict === 'pass') return 'pass'
+  if (verdict === 'pass_with_findings') return 'findings'
+  if (verdict === 'fail') return 'fail'
+  return 'undecided'
+}
+
+/** Every scheme by name, so a picker does not hard-code the list. */
+export function schemeNames(): PaletteScheme[] {
+  return Object.keys(SCHEMES) as PaletteScheme[]
+}

package/src/render/place.ts

@@ -0,0 +1,234 @@
+/**
+ * Where the boxes go.
+ *
+ * Two placements, chosen by the source:
+ *
+ * - **layered** (no groups): breadth-first rows, centred, no containment - 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.
+ *
+ * Split out of the painter so the two questions stay separate: this module decides positions, `paint.ts` decides
+ * what to draw between them. A change to edge routing cannot move a box, and a change to nesting cannot move a
+ * line.
+ */
+
+import { rankStates } from './layout.js'
+import type { Diagram, DiagramGroup, DiagramNode } from './model.js'
+
+/** Geometry of one placed box, before anything is drawn. */
+export type Box = { x: number; y: number; width: number; height: number }
+
+/** What a placement returns: every box, every drawn boundary, and how wide the content is. */
+export interface Placement {
+  boxes: Map<string, Box>
+  groupRects: Map<string, Box>
+  width: number
+}
+
+/** Geometry constants shared by both placements. */
+export const MARGIN = 20
+const NODE_HEIGHT = 34
+const ROW_GAP = 58
+const COLUMN_GAP = 30
+const MIN_NODE_WIDTH = 88
+const MAX_NODE_WIDTH = 220
+const CHAR_WIDTH = 7.2
+/** A boundary's inner padding and the strip its name sits in. */
+const GROUP_PADDING = 10
+const GROUP_HEADER = 16
+/** Between two blocks stacked inside a boundary, and between two top-level blocks. */
+const BLOCK_GAP = 14
+
+/** A box wide enough for its label, clamped so a long id cannot dominate the page. */
+export const nodeWidth = (label: string): number => Math.min(MAX_NODE_WIDTH, Math.max(MIN_NODE_WIDTH, label.length * CHAR_WIDTH + 26))
+
+
+
+/** The layered placement: breadth-first rows, centred, no containment. */
+function placeByRanks(diagram: Diagram, nodes: DiagramNode[], top: number): Placement {
+  const ranked = rankStates(diagram.nodes, diagram.edges, diagram.init)
+  const rows: string[][] = [...ranked.rows]
+  if (ranked.unreachable.length > 0) rows.push(ranked.unreachable)
+
+  const boxes = new Map<string, Box>()
+  let widest = 0
+  rows.forEach((row, index) => {
+    const widths = row.map((id) => nodeWidth(id))
+    widest = Math.max(widest, widths.reduce((total, width) => total + width, 0) + Math.max(0, row.length - 1) * COLUMN_GAP)
+    let x = 0
+    row.forEach((id, position) => {
+      boxes.set(id, { x, y: top + index * (NODE_HEIGHT + ROW_GAP), width: widths[position], height: NODE_HEIGHT })
+      x += widths[position] + COLUMN_GAP
+    })
+  })
+  rows.forEach((row) => {
+    const rowWidth = row.reduce((total, id) => total + (boxes.get(id) as Box).width, 0) + Math.max(0, row.length - 1) * COLUMN_GAP
+    const offset = (widest - rowWidth) / 2
+    for (const id of row) (boxes.get(id) as Box).x += offset + MARGIN
+  })
+  return { boxes, groupRects: new Map(), width: widest + MARGIN * 2 }
+}
+
+/**
+ * Which group each id belongs to, and which group contains which.
+ *
+ * Membership is read from `members`; containment is read from `parent`, because only the parser knows where a
+ * boundary was written. A model assembled by hand may omit `parent`, and then containment is inferred from
+ * member sets - the tightest superset wins - which is the best such a model can offer.
+ *
+ * Guards, because a model is data and data can be wrong: a parent that does not exist is ignored, a group that
+ * contains itself or closes a cycle is treated as a root, and a member claimed by two groups belongs to the
+ * tightest one, so a nested boundary is not drawn around nothing.
+ */
+function groupTree(groups: DiagramGroup[]): { owner: Map<string, string>; children: Map<string, string[]>; roots: string[] } {
+  const byId = new Map(groups.map((group) => [group.id, group] as const))
+
+  const owner = new Map<string, string>()
+  const bySize = [...groups].sort((left, right) => left.members.length - right.members.length)
+  for (const group of bySize) {
+    for (const member of group.members) if (!owner.has(member)) owner.set(member, group.id)
+  }
+
+  const declared = (group: DiagramGroup): string | undefined => {
+    const parent = group.parent
+    if (parent === undefined || parent === group.id) return undefined
+    return byId.has(parent) ? parent : undefined
+  }
+
+  const members = new Map(groups.map((group) => [group.id, new Set(group.members)] as const))
+  const infer = (group: DiagramGroup): string | undefined => {
+    let best: { id: string; size: number } | undefined
+    for (const other of groups) {
+      if (other.id === group.id) continue
+      const outer = members.get(other.id) as Set<string>
+      const inner = members.get(group.id) as Set<string>
+      if (inner.size === 0 || inner.size >= outer.size) continue
+      let contained = true
+      for (const member of inner) {
+        if (!outer.has(member)) {
+          contained = false
+          break
+        }
+      }
+      if (contained && (best === undefined || outer.size < best.size)) best = { id: other.id, size: outer.size }
+    }
+    return best?.id
+  }
+
+  const parentOf = new Map<string, string>()
+  for (const group of groups) {
+    const parent = declared(group) ?? infer(group)
+    if (parent !== undefined) parentOf.set(group.id, parent)
+  }
+  // A cycle would recurse forever: walk up from each group and drop the link that closes the loop.
+  for (const group of groups) {
+    const seen = new Set<string>([group.id])
+    let cursor = parentOf.get(group.id)
+    while (cursor !== undefined) {
+      if (seen.has(cursor)) {
+        parentOf.delete(cursor)
+        break
+      }
+      seen.add(cursor)
+      cursor = parentOf.get(cursor)
+    }
+  }
+
+  const children = new Map<string, string[]>()
+  const roots: string[] = []
+  for (const group of groups) {
+    const parent = parentOf.get(group.id)
+    if (parent === undefined) roots.push(group.id)
+    else children.set(parent, [...(children.get(parent) ?? []), group.id])
+  }
+  return { owner, children, roots }
+}
+
+interface Measured {
+  width: number
+  height: number
+}
+
+/** The tree placement: a boundary is a block, its contents stack inside it, the top level stacks. */
+function placeByGroups(diagram: Diagram, nodes: DiagramNode[], top: number): Placement {
+  const groups = diagram.groups as DiagramGroup[]
+  const byId = new Map(groups.map((group) => [group.id, group] as const))
+  const { owner, children, roots } = groupTree(groups)
+
+  // Nodes that belong to no group, and the first-seen order that keeps a source's own ordering visible.
+  const order = new Map(nodes.map((node, index) => [node.id, index] as const))
+  const loose = nodes.filter((node) => !owner.has(node.id)).map((node) => node.id)
+
+  const nodeIds = new Set(nodes.map((node) => node.id))
+  const rawContents = (groupId: string): string[] => {
+    const group = byId.get(groupId) as DiagramGroup
+    const own = [...new Set(group.members)].filter((member) => owner.get(member) === groupId && nodeIds.has(member))
+    const nested = children.get(groupId) ?? []
+    return [...own, ...nested]
+  }
+  // A boundary with nothing inside it is not drawn: an empty box claims a containment the source never stated.
+  const contents = (groupId: string): string[] => rawContents(groupId).filter((child) => !byId.has(child) || rawContents(child).length > 0)
+
+  const measure = (id: string): Measured => {
+    if (!byId.has(id)) return { width: nodeWidth(id), height: NODE_HEIGHT }
+    const items = contents(id)
+    const sizes = items.map(measure)
+    return {
+      width: Math.max(MIN_NODE_WIDTH, ...sizes.map((size) => size.width)) + GROUP_PADDING * 2,
+      height: GROUP_HEADER + GROUP_PADDING * 2 + sizes.reduce((total, size) => total + size.height, 0) + Math.max(0, items.length - 1) * BLOCK_GAP,
+    }
+  }
+
+  const boxes = new Map<string, Box>()
+  const groupRects = new Map<string, Box>()
+
+  const place = (id: string, x: number, y: number): Measured => {
+    const size = measure(id)
+    if (!byId.has(id)) {
+      boxes.set(id, { x, y, width: size.width, height: NODE_HEIGHT })
+      return size
+    }
+    groupRects.set(id, { x, y, width: size.width, height: size.height })
+    let cursor = y + GROUP_HEADER + GROUP_PADDING
+    const inner = size.width - GROUP_PADDING * 2
+    const ordered = [...contents(id)].sort((left, right) => firstIndex(left) - firstIndex(right))
+    for (const child of ordered) {
+      const childSize = measure(child)
+      place(child, x + GROUP_PADDING + (inner - childSize.width) / 2, cursor)
+      cursor += childSize.height + BLOCK_GAP
+    }
+    return size
+  }
+
+  // Top level: loose nodes and root groups, in the order the source named them.
+  const visibleRoots = roots.filter((id) => contents(id).length > 0)
+  // A block takes the earliest position of anything inside it, so a group is drawn where its first member was
+  // named - not after every loose node, which put a downstream box above the packages it depends on.
+  const firstIndex = (id: string): number => {
+    // `order` holds every node, and a block is only ever asked about when it has contents.
+    if (!byId.has(id)) return order.get(id) as number
+    return Math.min(...contents(id).map(firstIndex))
+  }
+  const topItems = [...loose, ...visibleRoots].sort((left, right) => firstIndex(left) - firstIndex(right))
+  const sizes = topItems.map(measure)
+  const width = Math.max(MIN_NODE_WIDTH, ...sizes.map((size) => size.width))
+  let cursor = top
+  for (const item of topItems) {
+    const size = measure(item)
+    place(item, MARGIN + (width - size.width) / 2, cursor)
+    cursor += size.height + BLOCK_GAP
+  }
+  return { boxes, groupRects, width: width + MARGIN * 2 }
+}
+
+/**
+ * Place every box of a diagram.
+ *
+ * The choice of placement is a property of the source, not of the caller: a drawing that declares boundaries is
+ * read as containers and gets the tree; one that does not is read as a machine and gets the ranks.
+ */
+export function place(diagram: Diagram, top: number): Placement {
+  const groups = diagram.groups ?? []
+  return groups.length > 0 ? placeByGroups(diagram, diagram.nodes, top) : placeByRanks(diagram, diagram.nodes, top)
+}

package/src/render/svg.ts

@@ -0,0 +1,127 @@
+/**
+ * Shapes to SVG markup.
+ *
+ * The one module that knows tags, so it is also the one place where a shape can silently disappear if a
+ * writer forgets a case: the writer table has an entry per shape kind, and the caller counts the drops
+ * instead of hiding them.
+ *
+ * Three containers read this output - an inline card, a full-screen view, and a sidebar tab - so the markup
+ * carries no size of its own beyond its `viewBox`: the container decides how large the drawing is, and the
+ * same string serves a thumbnail and a whiteboard.
+ *
+ * Pure, and the output is asserted as text: escaping, geometry, arrowheads, wrapped captions.
+ */
+
+import type { Canvas, Shape } from './paint.js'
+import type { Palette } from './palette.js'
+
+/** One decimal place is enough at any zoom, and it keeps the markup readable. */
+const n = (value: number): string => {
+  const rounded = Math.round(value * 10) / 10
+  return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1)
+}
+
+const escape = (value: string): string =>
+  value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;')
+
+type Writer<K extends Shape['kind']> = (shape: Extract<Shape, { kind: K }>, colours: Palette) => string
+
+const writers: { [K in Shape['kind']]: Writer<K> } = {
+  // A boundary is a dashed rectangle with its name in the top-left corner, drawn under everything else.
+  group: (shape, colours) => {
+    const stroke = colours[shape.colour]
+    // The id travels in the markup so a container can fold a boundary by delegation, without re-deriving which
+    // group a click landed on from its position or its label.
+    return (
+      '<g data-group-id="' + escape(shape.id) + '" style="cursor:pointer">' +
+      '<rect x="' + n(shape.x) + '" y="' + n(shape.y) + '" width="' + n(shape.width) + '" height="' + n(shape.height) +
+      '" rx="8" fill="none" stroke="' + stroke + '" stroke-width="1" stroke-dasharray="4 3" />' +
+      '<text x="' + n(shape.x + 6) + '" y="' + n(shape.y + 12) + '" font-size="10" fill="' + stroke + '">' + escape(shape.label) + '</text>' +
+      '</g>'
+    )
+  },
+  box: (shape, colours) => {
+    const stroke = colours[shape.colour]
+    const width = shape.initial ? 2.5 : 1
+    return (
+      '<rect x="' + n(shape.x) + '" y="' + n(shape.y) + '" width="' + n(shape.width) + '" height="' + n(shape.height) +
+      '" rx="6" fill="' + colours.surface + '" stroke="' + stroke + '" stroke-width="' + n(width) + '" />' +
+      '<text x="' + n(shape.x + shape.width / 2) + '" y="' + n(shape.y + shape.height / 2 + 4) +
+      '" font-size="11" text-anchor="middle" fill="' + stroke + '">' + escape(shape.label) + '</text>'
+    )
+  },
+  link: (shape, colours) => {
+    const stroke = colours[shape.colour]
+    const arrow = arrowHead(shape.x1, shape.y1, shape.x2, shape.y2, stroke)
+    return (
+      '<line x1="' + n(shape.x1) + '" y1="' + n(shape.y1) + '" x2="' + n(shape.x2) + '" y2="' + n(shape.y2) +
+      '" stroke="' + stroke + '" stroke-width="1" />' + arrow + edgeLabel(shape.label, shape.labelX, shape.labelY, colours)
+    )
+  },
+  path: (shape, colours) => {
+    const stroke = colours[shape.colour]
+    const points = shape.points.map((point) => n(point.x) + ',' + n(point.y)).join(' ')
+    const last = shape.points[shape.points.length - 1]
+    const before = shape.points[shape.points.length - 2] ?? last
+    return (
+      '<polyline points="' + points + '" fill="none" stroke="' + stroke + '" stroke-width="1" stroke-linejoin="round" />' +
+      arrowHead(before.x, before.y, last.x, last.y, stroke) + edgeLabel(shape.label, shape.labelX, shape.labelY, colours)
+    )
+  },
+  title: (shape, colours) => {
+    return '<text x="' + n(shape.x) + '" y="' + n(shape.y) + '" font-size="12" fill="' + colours[shape.colour] + '">' + escape(shape.text) + '</text>'
+  },
+  caption: (shape, colours) => {
+    const colour = colours[shape.colour]
+    const lines = shape.lines
+      .map((line, index) => '<tspan x="' + n(shape.x) + '" dy="' + (index === 0 ? 0 : 15) + '">' + escape(line) + '</tspan>')
+      .join('')
+    return '<text x="' + n(shape.x) + '" y="' + n(shape.y + 11) + '" font-size="10" fill="' + colour + '">' + lines + '</text>'
+  },
+}
+
+/** A small filled triangle at the end of a segment, pointing along it. */
+function arrowHead(x1: number, y1: number, x2: number, y2: number, stroke: string): string {
+  const length = Math.hypot(x2 - x1, y2 - y1)
+  if (length < 1) return ''
+  const ux = (x2 - x1) / length
+  const uy = (y2 - y1) / length
+  const size = 7
+  const half = 3.2
+  const baseX = x2 - ux * size
+  const baseY = y2 - uy * size
+  const left = n(baseX - uy * half) + ',' + n(baseY + ux * half)
+  const right = n(baseX + uy * half) + ',' + n(baseY - ux * half)
+  return '<polygon points="' + n(x2) + ',' + n(y2) + ' ' + left + ' ' + right + '" fill="' + stroke + '" />'
+}
+
+/** An edge label, or nothing when the edge carries no event. */
+function edgeLabel(label: string, x: number, y: number, colours: Palette): string {
+  // Total on purpose: a malformed edge must lose its label, not the whole drawing.
+  if (typeof label !== 'string' || label === '') return ''
+  return '<text x="' + n(x) + '" y="' + n(y) + '" font-size="10" fill="' + colours.muted + '">' + escape(label) + '</text>'
+}
+
+export function toSvg(canvas: Canvas, colours: Palette, label?: string): { markup: string; dropped: number } {
+  let dropped = 0
+  const body: string[] = []
+  for (const shape of canvas.shapes) {
+    const writer = writers[shape.kind] as ((shape: Shape, colours: Palette) => string) | undefined
+    if (writer === undefined) {
+      dropped += 1
+      continue
+    }
+    body.push(writer(shape, colours))
+  }
+  const header =
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ' + n(canvas.width) + ' ' + n(canvas.height) +
+    '" width="' + n(canvas.width) + '" height="' + n(canvas.height) + '" role="img"' +
+    (label === undefined ? '' : ' aria-label="' + escape(label) + '"') +
+    ' font-family="system-ui, -apple-system, Segoe UI, sans-serif">'
+  // The surface is part of the drawing, not the container's business: a page that paints its own layers - a
+  // wallpaper, a themed panel - would otherwise change the contrast of a picture it knows nothing about.
+  const background =
+    '<rect x="0" y="0" width="' + n(canvas.width) + '" height="' + n(canvas.height) +
+    '" fill="' + colours.background + '" />'
+  return { markup: header + background + body.join('') + '</svg>', dropped }
+}

package/src/render/viewmodel.ts

@@ -0,0 +1,136 @@
+/**
+ * What a tool card shows, reduced to a drawing.
+ *
+ * The input is what the host hands a settled tool view: a phase and a block whose shape differs per phase.
+ * A settled call carries the paired call's arguments as a **lazy view** (`PartialArguments`) and the result
+ * as content blocks, so nothing here reads `block.args.model`: the view is asked, and the report text is
+ * parsed for the two facts a drawing needs. Every reader is total - an absent field removes a shape rather
+ * than throwing, because the same view renders during streaming.
+ *
+ * Pure. Everything decided here is a fact a test can assert: which nodes exist, which edges, why they are
+ * coloured the way they are.
+ */
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined
+
+const array = (value: unknown): unknown[] => (Array.isArray(value) ? value : [])
+
+const text = (value: unknown): string | undefined => (typeof value === 'string' && value !== '' ? value : undefined)
+
+/** The report text a settled call carries, joined: a card reads words, not blocks. */
+function reportText(content: unknown): string {
+  const parts: string[] = []
+  for (const entry of array(content)) {
+    const block = record(entry)
+    const body = text(block?.text)
+    if (body !== undefined) parts.push(body)
+  }
+  return parts.join(String.fromCharCode(10))
+}
+
+/** Two facts out of this plugin's own report format: the verdict, and the first error it named. */
+function readReport(content: unknown): { verdict?: string; code?: string; message?: string } {
+  const body = reportText(content)
+  if (body === '') return {}
+  const verdict = /verdict=(\w+)/.exec(body)?.[1]
+  const named = /\[error\/([A-Z0-9_]+)\]\s*(.*)/.exec(body)
+  if (named !== null) return { verdict, code: named[1], message: named[2] }
+  const first = /first error:\s*([A-Z0-9_]+)/.exec(body)
+  return first === null ? { verdict } : { verdict, code: first[1] }
+}
+
+/**
+ * The `model` argument out of the host's lazy arguments view.
+ *
+ * A settled call exposes `value(key)`; a plain object (a test, or an older shape) is read directly. The
+ * view answers `undefined` until the field closes, which is exactly when a drawing should be attempted.
+ */
+function readModel(args: unknown): Record<string, unknown> | undefined {
+  const view = record(args)
+  if (view === undefined) return undefined
+  const read = view.value
+  if (typeof read === 'function') return record((read as (key: string) => unknown)('model'))
+  return record(view.model)
+}
+
+/** The states of a model: a machine, or nothing when the call carried none. */
+function machineOf(model: Record<string, unknown> | undefined): { nodes: DiagramNode[]; edges: DiagramEdge[]; init?: string } | undefined {
+  if (model === undefined) return undefined
+  const states = array(model.states).map(record).filter((entry): entry is Record<string, unknown> => entry !== undefined && typeof entry.id === 'string')
+  if (states.length === 0) return undefined
+  const edges = array(model.transitions)
+    .map(record)
+    .filter((entry): entry is Record<string, unknown> => entry !== undefined && typeof entry.from === 'string' && typeof entry.to === 'string')
+    .map((entry) => ({ from: String(entry.from), to: String(entry.to), label: text(entry.event) ?? '' }))
+  return {
+    nodes: states.map((state) => ({ id: String(state.id), role: 'normal' as const })),
+    edges,
+    ...(typeof model.init === 'string' ? { init: model.init } : {}),
+  }
+}
+
+/** The caption: the verdict, then the first error's code and message when the report named one. */
+function captionOf(report: { verdict?: string; code?: string; message?: string }): string {
+  const verdict = report.verdict ?? 'no report yet'
+  if (report.code === undefined) return verdict
+  const message = report.message ?? ''
+  return verdict + ' — ' + report.code + (message === '' ? '' : ': ' + message)
+}
+
+/**
+ * Which nodes the report blames.
+ *
+ * A finding names a state inside its message as `"x"`; matching that is a heuristic, so it only ever *adds*
+ * emphasis and never decides the verdict.
+ */
+function blame(nodes: DiagramNode[], report: { message?: string }): DiagramNode[] {
+  if (report.message === undefined) return nodes
+  const message = report.message
+  // Whole words only: a report does not quote the state, and a state called `do` must not match `done`.
+  const named = nodes
+    .filter((node) => {
+      const escaped = node.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      return new RegExp('(?<![A-Za-z0-9_])' + escaped + '(?![A-Za-z0-9_])').test(message)
+    })
+    .map((node) => node.id)
+  if (named.length === 0) return nodes
+  return nodes.map((node) => (named.includes(node.id) ? { ...node, role: 'error' as const } : node))
+}
+
+import type { Diagram, DiagramEdge, DiagramNode } from './model.js'
+
+export interface ViewInput {
+  phase?: unknown
+  toolName?: unknown
+  /** The whole block the host hands a view; its shape depends on the phase. */
+  block?: unknown
+}
+
+export function viewModel(input: ViewInput): Diagram {
+  const block = record(input.block)
+  const title = text(block?.name) ?? text(input.toolName) ?? 'tool'
+  const report = readReport(block?.content)
+  // A shape that still carries a parsed report object is read from there; it is what older callers pass.
+  const parsed = record(block?.result)
+  const findings = array(parsed?.findings).map(record)
+  const firstError = findings.find((finding) => finding?.severity === 'error')
+  const merged = {
+    verdict: text(parsed?.verdict) ?? report.verdict,
+    ...(report.code === undefined && typeof firstError?.code === 'string' ? { code: firstError.code } : { code: report.code }),
+    ...(report.message === undefined && typeof firstError?.message === 'string' ? { message: firstError.message } : { message: report.message }),
+  }
+  const caption = captionOf(merged)
+  const machine = machineOf(readModel(block?.args))
+  if (machine === undefined) {
+    return { kind: 'none', title, nodes: [], edges: [], caption }
+  }
+  return {
+    kind: 'machine',
+    title,
+    ...(machine.init === undefined ? {} : { init: machine.init }),
+    nodes: blame(machine.nodes, merged),
+    edges: machine.edges,
+    caption,
+  }
+}

package/src/render/write.ts

@@ -0,0 +1,17 @@
+/**
+ * Writing a drawing to disk: the CLI's job, kept out of the renderer.
+ *
+ * `render/index.ts` is bundled into the page as well as run in Node, so it may not import a filesystem;
+ * everything that touches one lives here, where only the host reaches it.
+ */
+
+import { writeFileSync } from 'node:fs'
+import { render, type RenderInput, type Rendered } from './index.js'
+import type { Palette, PaletteOptions } from './palette.js'
+
+/** Write the drawing where a document can link to it. Returns the path, the byte count and the render. */
+export function writeSvg(input: RenderInput, path: string, overrides: Partial<Palette> = {}, options: PaletteOptions = {}): { path: string; bytes: number; rendered: Rendered } {
+  const rendered = render(input, overrides, options)
+  writeFileSync(path, rendered.markup, 'utf8')
+  return { path, bytes: rendered.markup.length, rendered }
+}