@inerrata-corporation/errata 2.0.17-dev.3571 → 2.0.17-dev.3577

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inerrata-corporation/errata",
-  "version": "2.0.17-dev.3571",
+  "version": "2.0.17-dev.3577",
   "description": "errata - local-first observation engine for AI coding agents",
   "type": "module",
   "bin": {

package/resources/claude-mods/errata-minimap/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "errata-minimap",
+  "version": "0.1.0",
+  "author": { "name": "inErrata", "url": "https://inerrata.ai" },
+  "description": "Side pane: an errata graph minimap of the latest burst neighborhood that entered the agent's context.",
+  "types": "./types/index.d.ts"
+}

package/resources/claude-mods/errata-minimap/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/resources/claude-mods/errata-minimap/hooks/minimap.ts

@@ -0,0 +1,632 @@
+import type { Burst, BurstNode, MapGraph, MapNode, Scope } from '../types'
+
+export function relPath(path: string, cwd: string): string {
+  const p = path.replace(/\\/g, '/')
+  const root = cwd.replace(/\\/g, '/').replace(/\/$/, '')
+  return p.toLowerCase().startsWith(`${root.toLowerCase()}/`) ? p.slice(root.length + 1) : p
+}
+
+
+/**
+ * Every string leaf of a value: tool results and transcript rows nest their
+ * text differently per door. A string that is itself JSON (a hook's stdout
+ * carrying `hookSpecificOutput.additionalContext`) is kept and also opened.
+ */
+export function textsOf(value: unknown, out: string[] = []): string[] {
+  if (typeof value === 'string') {
+    out.push(value)
+    if (/^\s*[{[]/.test(value)) {
+      try {
+        textsOf(JSON.parse(value), out)
+      } catch {
+        /* not JSON after all */
+      }
+    }
+  } else if (Array.isArray(value)) for (const v of value) textsOf(v, out)
+  else if (value && typeof value === 'object') for (const v of Object.values(value)) textsOf(v, out)
+  return out
+}
+
+/**
+ * The membrane a node lives in, from what a client can see. The daemon's MCP
+ * output drops the cloud's `stratum` attr (dual-burst `searchResultToCloudHits`),
+ * so the salted id prefix is the one project/team/org signal; `provenance` then
+ * only splits local (machine) from cloud (public: collective or corroborated).
+ */
+export function scopeOf(id: string, provenance?: string): Scope | undefined {
+  if (id.startsWith('projn_')) return 'project'
+  if (id.startsWith('teamn_')) return 'team'
+  if (id.startsWith('orgn_')) return 'org'
+  if (provenance === 'collective' || provenance === 'corroborated') return 'public'
+  if (provenance === 'local') return 'machine'
+  return undefined
+}
+
+type BurstJson = {
+  seed?: string
+  results?: { id: string; label?: string; name?: string; score?: number; hops?: number; provenance?: string; via?: { edgeType?: string; parentId?: string } }[]
+}
+
+/** An `errata_burst` result (MCP JSON) → the neighborhood the agent just read. */
+export function parseAgentBurst(texts: string[], seedHint: string): Burst | null {
+  for (const text of texts) {
+    let json: BurstJson
+    try {
+      json = JSON.parse(text) as BurstJson
+    } catch {
+      continue
+    }
+    if (!Array.isArray(json.results)) continue
+    const seedId = json.seed ?? seedHint
+    const nodes: BurstNode[] = json.results.map(r => ({
+      id: r.id,
+      label: r.label ?? 'Node',
+      name: r.name ?? r.id,
+      score: r.score ?? 0,
+      hops: Math.max(1, r.hops ?? 1),
+      parent: r.via?.parentId,
+      edge: r.via?.edgeType,
+      scope: scopeOf(r.id, r.provenance),
+    }))
+    return {
+      origin: 'agent',
+      seed: { id: seedId, label: 'Seed', name: seedHint || seedId },
+      nodes,
+      extra: [],
+      isEnriched: false,
+      at: Date.now(),
+    }
+  }
+  return null
+}
+
+/**
+ * An `errata_search` result → the hits that entered context, ringed around the
+ * query. Merged results carry `score`/`provenance`; local-only hits carry
+ * `pageRank` and no provenance (they are this machine's store).
+ */
+export function parseAgentSearch(texts: string[], query: string): Burst | null {
+  for (const text of texts) {
+    let json: { results?: unknown[]; hits?: unknown[] }
+    try {
+      json = JSON.parse(text) as typeof json
+    } catch {
+      continue
+    }
+    const rows = (json.results ?? json.hits) as { id?: string; label?: string; name?: string; description?: string; score?: number; pageRank?: number; provenance?: string }[] | undefined
+    if (!Array.isArray(rows)) continue
+    const nodes: BurstNode[] = rows
+      .filter(r => typeof r.id === 'string')
+      .map((r, i) => ({
+        id: r.id!,
+        label: r.label ?? 'Node',
+        name: r.name ?? r.description ?? r.id!,
+        // Search ranks by order; a score of 0 (code hits) still keeps its place.
+        score: r.score && r.score > 0 ? r.score : 1 - i / (rows.length + 1),
+        hops: 1,
+        parent: `search:${query}`,
+        edge: 'MATCHES',
+        scope: scopeOf(r.id!, r.provenance ?? 'local'),
+      }))
+    if (nodes.length === 0) return null
+    return {
+      origin: 'agent',
+      seed: { id: `search:${query}`, label: 'Search', name: `“${query}”` },
+      nodes,
+      extra: [],
+      isEnriched: false,
+      at: Date.now(),
+    }
+  }
+  return null
+}
+
+/** `- [Label] description  →  … ([id]) to cite` — the daemon's file-recall block, one prior per line. */
+const RECALL_LINE = /^- \[([A-Za-z]+)(?:;[^\]]*)?\] (.*?)\s+→\s+(.*)$/
+const CITED = /\[([A-Za-z0-9_:.@/+-]+)\]/
+
+/** The daemon's file recall (`N prior(s) recorded on this file`) → the priors it put in context, seeded at the file. */
+export function parseFileRecall(text: string, file: string): Burst | null {
+  if (!/prior\(s\) recorded on this file/.test(text)) return null
+  const nodes: BurstNode[] = []
+  for (const line of text.split('\n')) {
+    const m = RECALL_LINE.exec(line.trim())
+    if (!m) continue
+    const id = CITED.exec(m[3]!)?.[1]
+    if (!id || nodes.some(n => n.id === id)) continue
+    // File recall reads the local store: machine-only unless the id is a salted membrane twin.
+    nodes.push({ id, label: m[1]!, name: m[2]!, score: 0, hops: 1, parent: `file:${file}`, edge: 'RECORDED_ON', scope: scopeOf(id, 'local') })
+  }
+  if (nodes.length === 0) return null
+  nodes.forEach((n, i) => (n.score = 1 - i / (nodes.length + 1)))
+  return {
+    origin: 'daemon-file',
+    seed: { id: `file:${file}`, label: 'File', name: file },
+    nodes,
+    extra: [],
+    isEnriched: false,
+    at: Date.now(),
+  }
+}
+
+export type HandleTable = Record<string, { id?: string; label?: string }>
+
+/** Profile handles (stack, languages, tools) ride the same syntax but are not knowledge that entered context. */
+const KNOWLEDGE = new Set(['Problem', 'Solution', 'RootCause', 'Pattern', 'AntiPattern', 'Technique', 'Vulnerability', 'Constraint'])
+const RAW_ID = /`((?:dprob|dfix|dcause|dsol|projn|teamn|orgn|princ|motif)_[A-Za-z0-9_]+)`/
+const HANDLE = /`\[([a-z0-9-]+)\]`/
+
+/** The prompt-time `## Errata context` block → the priors primed for this prompt, resolved through priming-handles.json. */
+export function parsePromptPrime(text: string, handles: HandleTable): Burst | null {
+  if (!text.includes('## Errata context')) return null
+  const nodes: BurstNode[] = []
+  // Only the Network section is cloud; its `[org · …]` chip names an own-org stratum, no chip = public.
+  let isNetwork = false
+  for (const raw of text.split('\n')) {
+    if (raw.startsWith('### ')) isNetwork = raw.includes('From the Errata Network')
+    const handle = HANDLE.exec(raw)?.[1]
+    const entry = handle ? handles[handle] : undefined
+    const id = entry?.id ?? RAW_ID.exec(raw)?.[1]
+    if (!id || nodes.some(n => n.id === id)) continue
+    const typed = /\*\*([A-Za-z]+):\*\*/.exec(raw)?.[1]
+    const label = entry?.label ?? typed ?? (id.startsWith('dprob') ? 'Problem' : 'Node')
+    if (!KNOWLEDGE.has(label)) continue
+    // `- **title** — \`id\`` (a title may hold its own " — ") or `**Pattern:** text \`[handle]\``.
+    const titled = /^\s*-\s*\*\*(?![A-Za-z]+:\*\*)(.+?)\*\*\s+—\s+`/.exec(raw)?.[1]
+    const name = (titled ?? raw.replace(/^\s*-\s*/, '').replace(/\*\*[A-Za-z]+:\*\*\s*/, '').split(/\s+`/)[0]!)
+      .replace(/\*\*/g, '')
+      .trim()
+    const chip = /`\[(project|team|org)\b/.exec(raw)?.[1] as Scope | undefined
+    const scope = scopeOf(id) ?? chip ?? (isNetwork ? 'public' : 'machine')
+    nodes.push({ id, label, name: name || id, score: 0, hops: 1, parent: 'prompt', edge: 'PRIMED', scope })
+  }
+  if (nodes.length === 0) return null
+  nodes.forEach((n, i) => (n.score = 1 - i / (nodes.length + 1)))
+  return {
+    origin: 'daemon-prompt',
+    seed: { id: 'prompt', label: 'Prompt', name: 'prompt context' },
+    nodes,
+    extra: [],
+    isEnriched: false,
+    at: Date.now(),
+  }
+}
+
+/** `node` of an `errata_neighbors` result: what the queried id is. */
+export function seedNode(texts: string[]): { label: string; name: string } | undefined {
+  for (const text of texts) {
+    try {
+      const node = (JSON.parse(text) as { node?: { label?: string; name?: string } }).node
+      if (node?.name) return { label: node.label ?? 'Node', name: node.name }
+    } catch {
+      continue
+    }
+  }
+  return undefined
+}
+
+/**
+ * How the agent judged a prior in its own reply — the capture protocol's tags:
+ * `([h])` cites it, `(confirm:[h])` says it held, `(refute:[h] …)` says it did
+ * not, `(fix:[h])` says the agent's edit resolved it.
+ */
+export type JudgmentKind = 'cite' | 'confirm' | 'fix' | 'refute'
+export type Judgment = { kind: JudgmentKind; ref: string }
+
+export const JUDGMENT_STYLE: Record<JudgmentKind, { glyph: string; color: number; verb: string }> = {
+  cite: { glyph: '◎', color: 0x56b6c2, verb: 'cited' },
+  confirm: { glyph: '✓', color: 0x98c379, verb: 'confirmed' },
+  fix: { glyph: '✓', color: 0x98c379, verb: 'resolved' },
+  refute: { glyph: '✗', color: 0xe06c75, verb: 'refuted' },
+}
+
+/** A stronger verdict on the same prior wins: refute › confirm/fix › cite. */
+const STRENGTH: Record<JudgmentKind, number> = { cite: 0, confirm: 1, fix: 1, refute: 2 }
+
+const VERDICT_TAG = /\((confirm|refute|fix|cause):\[([^\]\s]+)\]/g
+const BARE_CITE = /\(\[([^\]\s]+)\]\)/g
+const LINK_TAG = /\((?:instance|pattern|aids|builds-on|supersedes|alternative):([^)]*)\)/g
+const BRACKETED = /\[([^\]\s]+)\]/g
+
+/** Every prior the text judges, once each, at its strongest verdict. */
+export function parseJudgments(text: string): Judgment[] {
+  const best = new Map<string, JudgmentKind>()
+  const note = (ref: string, kind: JudgmentKind) => {
+    const prev = best.get(ref)
+    if (!prev || STRENGTH[kind] > STRENGTH[prev]) best.set(ref, kind)
+  }
+  for (const m of text.matchAll(VERDICT_TAG)) {
+    // `(cause:[h] …)` explains a shown problem — it engages the prior, so it reads as a citation.
+    note(m[2]!, m[1] === 'cause' ? 'cite' : (m[1] as JudgmentKind))
+  }
+  for (const m of text.matchAll(BARE_CITE)) note(m[1]!, 'cite')
+  for (const m of text.matchAll(LINK_TAG)) for (const r of m[1]!.matchAll(BRACKETED)) note(r[1]!, 'cite')
+  return [...best].map(([ref, kind]) => ({ ref, kind }))
+}
+
+/** A real node id, not a placeholder like `[id]` or `[its-handle]` in prose about the protocol. */
+const NODE_ID = /^(dprob|dfix|dcause|dsol|dtri|projn|teamn|orgn|princ|pat|motif_community|problem)_[A-Za-z0-9_]{6,}$/
+
+/** The node a judgment names: a primed handle resolves through the table, a raw id stands; anything else is prose. */
+export function resolveJudgmentRef(ref: string, handles: HandleTable): string | null {
+  return handles[ref]?.id ?? (NODE_ID.test(ref) ? ref : null)
+}
+
+/** `{ out, in }` of an `errata_neighbors` result → the ids it touches. */
+export function neighborIds(texts: string[]): { id: string; type: string }[] {
+  for (const text of texts) {
+    try {
+      const json = JSON.parse(text) as { out?: { type: string; to?: { id: string } }[]; in?: { type: string; from?: { id: string } }[] }
+      if (!json.out && !json.in) continue
+      return [
+        ...(json.out ?? []).flatMap(e => (e.to ? [{ id: e.to.id, type: e.type }] : [])),
+        ...(json.in ?? []).flatMap(e => (e.from ? [{ id: e.from.id, type: e.type }] : [])),
+      ]
+    } catch {
+      continue
+    }
+  }
+  return []
+}
+
+/**
+ * Radial layout of one burst: the seed at the centre, one ring per hop, each
+ * node in its parent's angular sector, and within a ring a higher score sits
+ * closer in. Positions are in the unit square.
+ */
+export function layoutBurst(burst: Burst): MapGraph {
+  const nodes: MapNode[] = [{ id: burst.seed.id, label: burst.seed.label, name: burst.seed.name, isSeed: true, score: 1, hops: 0, x: 0.5, y: 0.5 }]
+  const index = new Map<string, number>([[burst.seed.id, 0]])
+  const edges: [number, number, boolean][] = []
+  const maxHops = Math.max(1, ...burst.nodes.map(n => n.hops))
+  const scores = burst.nodes.map(n => n.score)
+  const [lo, hi] = [Math.min(...scores), Math.max(...scores)]
+  const norm = (s: number) => (hi > lo ? (s - lo) / (hi - lo) : 1)
+
+  const sector = new Map<string, [number, number]>([[burst.seed.id, [0, Math.PI * 2]]])
+  const byDepth = [...burst.nodes].sort((a, b) => a.hops - b.hops || b.score - a.score)
+  const childrenOf = new Map<string, BurstNode[]>()
+  for (const n of byDepth) {
+    const parent = n.parent && (n.parent === burst.seed.id || burst.nodes.some(m => m.id === n.parent)) ? n.parent : burst.seed.id
+    childrenOf.set(parent, [...(childrenOf.get(parent) ?? []), n])
+  }
+
+  const place = (parentId: string) => {
+    const kids = childrenOf.get(parentId) ?? []
+    const [a0, a1] = sector.get(parentId) ?? [0, Math.PI * 2]
+    const span = (a1 - a0) / Math.max(1, kids.length)
+    kids.forEach((n, i) => {
+      if (index.has(n.id)) return
+      const angle = a0 + span * (i + 0.5) - Math.PI / 2
+      const ring = n.hops / maxHops
+      const r = 0.48 * ring * (0.72 + 0.28 * (1 - norm(n.score)))
+      const at = nodes.length
+      nodes.push({ id: n.id, label: n.label, name: n.name, isSeed: false, score: n.score, hops: n.hops, scope: n.scope, x: 0.5 + r * Math.cos(angle), y: 0.5 + r * Math.sin(angle) })
+      index.set(n.id, at)
+      edges.push([index.get(parentId) ?? 0, at, true])
+      sector.set(n.id, [a0 + span * i, a0 + span * (i + 1)])
+      place(n.id)
+    })
+  }
+  place(burst.seed.id)
+
+  const seen = new Set(edges.map(([a, b]) => key(a, b)))
+  for (const [s, t] of burst.extra) {
+    const a = index.get(s), b = index.get(t)
+    if (a === undefined || b === undefined || a === b || seen.has(key(a, b))) continue
+    seen.add(key(a, b))
+    edges.push([a, b, false])
+  }
+  return { title: displayName(burst.seed.label, burst.seed.name), seedLabel: burst.seed.label, origin: burst.origin, nodes, edges, at: burst.at }
+}
+
+function key(a: number, b: number): string {
+  return a < b ? `${a},${b}` : `${b},${a}`
+}
+
+const DEFAULT = 0x01000000
+// Bright enough to read on a dark terminal: the first cut's #3a3f4b vanished there.
+const EDGE_WALK = 0x8a96b4
+const EDGE_CROSS = 0x5c6680
+
+/**
+ * An edge takes the colour of the membrane its far end lives in, so the map
+ * reads "how far did this prior travel to reach me": machine-only, the
+ * project / team / org membranes, or the public Errata Network.
+ */
+export const SCOPE_COLOR: Record<Scope, number> = {
+  machine: 0x8a96b4, // slate — never left this machine
+  project: 0x5fa8ff, // blue
+  team: 0x3fc5b0, // teal
+  org: 0xf0b34a, // amber
+  public: 0xd27cf0, // magenta — The Errata Network
+}
+export const SCOPE_ORDER: Scope[] = ['machine', 'project', 'team', 'org', 'public']
+
+/** The tier an edge is coloured by: its non-seed end, the farther-travelled when both say. */
+export function edgeScope(a: MapNode, b: MapNode): Scope | undefined {
+  const ends = [a, b].filter(v => !v.isSeed && v.scope).map(v => v.scope!)
+  return ends.sort((p, q) => SCOPE_ORDER.indexOf(q) - SCOPE_ORDER.indexOf(p))[0]
+}
+
+function dim(color: number): number {
+  return (((color >> 16) & 255) * 0.6) << 16 | (((color >> 8) & 255) * 0.6) << 8 | ((color & 255) * 0.6)
+}
+const NAME = 0x9aa3b5
+
+export const LABEL_COLOR: Record<string, number> = {
+  Problem: 0xe06c75,
+  Vulnerability: 0xff5f87,
+  Solution: 0x98c379,
+  RootCause: 0xd19a66,
+  Pattern: 0xc678dd,
+  AntiPattern: 0xbe5046,
+  Technique: 0x56b6c2,
+  Constraint: 0xe5c07b,
+  File: 0x61afef,
+  Function: 0x7fb8d8,
+  Method: 0x7fb8d8,
+  Module: 0xa9b1c4,
+  Package: 0xa9b1c4,
+  Const: 0x8fbfa0,
+  Variable: 0x8fbfa0,
+  Interface: 0xb4a7d6,
+  Class: 0xb4a7d6,
+  Type: 0xb4a7d6,
+  Comment: 0x7c8494,
+}
+
+export const LABEL_GLYPH: Record<string, number> = {
+  Problem: 0x25c6, // ◆
+  Vulnerability: 0x25c6,
+  Solution: 0x25cf, // ●
+  RootCause: 0x25b2, // ▲
+  Pattern: 0x2726, // ✦
+  AntiPattern: 0x2726,
+  Technique: 0x25c7, // ◇
+  Constraint: 0x25a0, // ■
+  File: 0x25aa, // ▪
+  // Code structure a burst walks through (CALLS / IMPORTS / DEFINES / CONTAINS).
+  Function: 0x0192, // ƒ
+  Method: 0x0192,
+  Module: 0x229e, // ⊞
+  Package: 0x229e,
+  Const: 0x2261, // ≡
+  Variable: 0x2261,
+  Interface: 0x25a1, // □
+  Class: 0x25a1,
+  Type: 0x25a1,
+  Comment: 0x00b6, // ¶
+}
+
+/** The name as the map shows it: a file path by its last two segments, a module by its last. */
+export function displayName(label: string, name: string): string {
+  if (label === 'File' || /^[\w.@-]+(\/[\w.@-]+){2,}$/.test(name)) return name.split('/').slice(-2).join('/')
+  if (label === 'Module' || label === 'Package') return name.split('/').pop() ?? name
+  return name
+}
+
+export function glyphOf(label: string): number {
+  return LABEL_GLYPH[label] ?? 0x2022 // •
+}
+
+export function colorOf(label: string): number {
+  return LABEL_COLOR[label] ?? 0x6b7280
+}
+
+export function hex(color: number): string {
+  return `#${color.toString(16).padStart(6, '0')}`
+}
+
+const ORIGIN_SHORT = { agent: 'burst', 'daemon-file': 'recall', 'daemon-prompt': 'prime' } as const
+
+/**
+ * The minified minimap for the status line, where the pane has no room: the
+ * seed, how much entered context, and a glyph tally by type, knowledge first.
+ * `errata ◉ src/engine.ts · burst 14 · ◆3 ●2 ƒ2 ⊞3 ≡2 □1 ¶1`
+ */
+export function statusLine(graph: MapGraph, max = 100): string | undefined {
+  const delivered = graph.nodes.filter(n => !n.isSeed)
+  if (delivered.length === 0) return undefined
+  const counts = new Map<string, number>()
+  for (const n of delivered) counts.set(n.label, (counts.get(n.label) ?? 0) + 1)
+  const knowledge = (l: string) => (l in LABEL_GLYPH && !(l in CODE_LABELS) ? 0 : 1)
+  const tally = [...counts]
+    .sort((a, b) => knowledge(a[0]) - knowledge(b[0]) || b[1] - a[1])
+    .map(([label, n]) => `${String.fromCodePoint(glyphOf(label))}${n}`)
+    .join(' ')
+  const origin = graph.origin ? ORIGIN_SHORT[graph.origin] : 'burst'
+  const head = `errata ◉ ${graph.title} · ${origin} ${delivered.length} · `
+  const line = head + tally
+  return line.length <= max ? line : `${line.slice(0, max - 1)}…`
+}
+
+const CODE_LABELS = { File: 1, Function: 1, Method: 1, Module: 1, Package: 1, Const: 1, Variable: 1, Interface: 1, Class: 1, Type: 1, Comment: 1 }
+
+/** How far the reveal has run: routes grow out ring by ring (`grow`), then names type out (`type`). Both 0..1. */
+export type Frame = { grow: number; type: number }
+export const FULL: Frame = { grow: 1, type: 1 }
+
+/** What "transparent" fades toward: the background of the terminal theme. */
+export const DARK_BG = 0x1a1b1e
+export const LIGHT_BG = 0xf7f7f5
+
+/** Fraction of a colour kept at the weakest signal: faint, never gone. */
+const FLOOR = 0.28
+
+/** Signal strength per node, 0..1 over this burst's score range; the seed is full strength. */
+export function strengths(graph: MapGraph): number[] {
+  const scores = graph.nodes.filter(v => !v.isSeed).map(v => v.score)
+  const [lo, hi] = [Math.min(...scores), Math.max(...scores)]
+  return graph.nodes.map(v => (v.isSeed ? 1 : hi > lo ? (v.score - lo) / (hi - lo) : 1))
+}
+
+/** Blends `color` toward `bg` as signal weakens: strength 1 keeps it, 0 keeps FLOOR of it. */
+export function fade(color: number, strength: number, bg: number): number {
+  const keep = FLOOR + (1 - FLOOR) * Math.max(0, Math.min(1, strength))
+  const ch = (c: number, shift: number) => Math.round(((c >> shift) & 255) * keep + ((bg >> shift) & 255) * (1 - keep))
+  return (ch(color, 16) << 16) | (ch(color, 8) << 8) | ch(color, 0)
+}
+
+/**
+ * The minimap as Raster cells (`[codePoint, fg, bg]` u32 triplets, row-major,
+ * base64) at one frame of the reveal. Positions and label slots are planned on
+ * the finished map, so an animated frame only ever draws a prefix of it —
+ * nothing jumps as it fills in.
+ */
+export type RasterOptions = {
+  frame?: Frame
+  /** The theme background weak signal fades toward. */
+  bg?: number
+  /** A node the agent is bursting off: drawn inverted, its route to the seed lit. */
+  highlight?: string
+  /** Which half of the highlight's pulse this frame shows. */
+  isPulseOn?: boolean
+  /** Priors the agent just judged: each pulses in its verdict's colour. */
+  marks?: Record<string, JudgmentKind>
+  /** Which half of the marks' pulse this frame shows. */
+  isMarkOn?: boolean
+}
+
+const HIGHLIGHT = 0xffd75f
+
+export function rasterize(graph: MapGraph, columns: number, rows: number, options: RasterOptions = {}): string {
+  const { frame = FULL, bg = DARK_BG, highlight, isPulseOn = true, marks = {}, isMarkOn = true } = options
+  const markColor = (id: string): number | undefined => {
+    const kind = marks[id]
+    return kind ? JUDGMENT_STYLE[kind].color : undefined
+  }
+  const words = new Uint32Array(columns * rows * 3)
+  for (let i = 0; i < columns * rows; i++) words.set([0x20, DEFAULT, DEFAULT], i * 3)
+  const occupied = new Uint8Array(columns * rows)
+  const cx = (x: number) => 1 + Math.round(x * Math.max(0, columns - 3))
+  const cy = (y: number) => Math.round(y * Math.max(0, rows - 1))
+  const put = (x: number, y: number, ch: number, fg: number, weight: number, cellBg = DEFAULT) => {
+    if (x < 0 || y < 0 || x >= columns || y >= rows) return false
+    const i = y * columns + x
+    if (occupied[i]! > weight) return false
+    occupied[i] = weight
+    words.set([ch, fg, cellBg], i * 3)
+    return true
+  }
+
+  const pos: [number, number][] = graph.nodes.map(v => [cx(v.x), cy(v.y)])
+  // Two nodes in one cell: walk the later one outward to the nearest free cell.
+  const taken = new Set<number>()
+  graph.nodes.forEach((_, i) => {
+    let [x, y] = pos[i]!
+    for (let r = 0; taken.has(y * columns + x) && r < 6; r++) {
+      const ring = [[1, 0], [-1, 0], [0, 1], [0, -1], [1, 1], [-1, -1], [1, -1], [-1, 1]].map(([dx, dy]) => [x + dx! * (r + 1), y + dy! * (r + 1)] as const)
+      const free = ring.find(([a, b]) => a >= 0 && b >= 0 && a < columns && b < rows && !taken.has(b * columns + a))
+      if (free) [x, y] = free
+    }
+    taken.add(y * columns + x)
+    pos[i] = [x, y]
+  })
+
+  const strength = strengths(graph)
+  // The highlighted node and the walk edges from it back to the seed.
+  const lit = graph.nodes.findIndex(v => v.id === highlight)
+  const route = new Set<number>()
+  for (let at = lit, guard = 0; at > 0 && guard < 16; guard++) {
+    const k = graph.edges.findIndex(([, c, isWalk]) => isWalk && c === at)
+    if (k < 0) break
+    route.add(k)
+    at = graph.edges[k]![0]
+  }
+  const depth = Math.max(1, ...graph.nodes.map(v => v.hops))
+  // How much of the walk edge INTO node i has grown: ring h fills during the h-th slice of `grow`.
+  const reach = (i: number) => (graph.nodes[i]!.isSeed ? 1 : Math.max(0, Math.min(1, frame.grow * depth - (graph.nodes[i]!.hops - 1))))
+
+  // Label slots, planned on the finished map, best first: nodes and earlier labels block, edges do not.
+  const blocked = new Set(pos.map(([x, y]) => y * columns + x))
+  const labels: { i: number; at: number; text: string }[] = []
+  const ranked = graph.nodes.map((v, i) => [v, i] as const).filter(([v]) => !v.isSeed).sort((p, q) => q[0].score - p[0].score)
+  for (const [v, i] of ranked) {
+    const [x, y] = pos[i]!
+    const free = (from: number, len: number) => {
+      if (from < 0 || from + len > columns) return false
+      for (let k = 0; k < len; k++) if (blocked.has(y * columns + from + k)) return false
+      return true
+    }
+    const fits = (len: number) => (free(x + 2, len) ? x + 2 : free(x - 1 - len, len) ? x - 1 - len : -1)
+    let text = shortName(displayName(v.label, v.name), 18)
+    while (text.length >= 4 && fits(text.length) < 0) text = shortName(text.replace(/~$/, ''), text.length - 2)
+    const at = text.length >= 4 ? fits(text.length) : -1
+    if (at < 0) continue
+    for (let k = 0; k < text.length; k++) blocked.add(y * columns + at + k)
+    labels.push({ i, at, text })
+  }
+
+  // Edges go down at braille resolution — 2×4 dots per cell — so a line of any
+  // slope is one continuous stroke. Per-cell box glyphs could not do that: a
+  // cell is ~2× taller than wide, so a visual diagonal steps two cells sideways
+  // per row and adjacent ╱╱ never join.
+  const dots = new Uint8Array(columns * rows)
+  const tone = new Uint8Array(columns * rows) // 2 = a walk edge crosses the cell, 1 = cross edges only
+  const hue = new Uint32Array(columns * rows) // the colour of the strongest edge through the cell
+  const plot = (px: number, py: number, weight: number, color: number) => {
+    const x = px >> 1, y = py >> 2
+    if (x < 0 || y < 0 || x >= columns || y >= rows) return
+    const i = y * columns + x
+    dots[i] = dots[i]! | BRAILLE_BIT[(py & 3) * 2 + (px & 1)]!
+    if (weight >= tone[i]!) hue[i] = color
+    tone[i] = Math.max(tone[i]!, weight)
+  }
+  for (const [k, [a, b, isWalk]] of graph.edges.entries()) {
+    // A walk edge grows parent → child; a cross edge fades in while names type.
+    const progress = isWalk ? reach(b) : frame.type
+    if (progress <= 0) continue
+    const weaker = graph.nodes[a]!.isSeed ? b : graph.nodes[b]!.isSeed ? a : strength[a]! < strength[b]! ? a : b
+    const scope = edgeScope(graph.nodes[a]!, graph.nodes[b]!)
+    const base = scope ? SCOPE_COLOR[scope] : EDGE_WALK
+    const color = route.has(k) ? HIGHLIGHT : fade(isWalk ? base : scope ? dim(base) : EDGE_CROSS, strength[weaker]!, bg)
+    let x0 = pos[a]![0] * 2 + 1, y0 = pos[a]![1] * 4 + 2
+    const x1 = pos[b]![0] * 2 + 1, y1 = pos[b]![1] * 4 + 2
+    const dx = Math.abs(x1 - x0), dy = -Math.abs(y1 - y0)
+    const sx = x0 < x1 ? 1 : -1, sy = y0 < y1 ? 1 : -1
+    const limit = Math.round(progress * Math.max(dx, -dy))
+    let err = dx + dy
+    // Cross edges are dashed so a walk edge reads as the path taken.
+    for (let step = 0; step <= limit; step++) {
+      if (isWalk || step % 4 < 2) plot(x0, y0, route.has(k) ? 4 : isWalk ? 2 : 1, color)
+      if (x0 === x1 && y0 === y1) break
+      const e2 = 2 * err
+      if (e2 >= dy) { err += dy; x0 += sx }
+      if (e2 <= dx) { err += dx; y0 += sy }
+    }
+  }
+  for (let i = 0; i < columns * rows; i++) {
+    if (dots[i]) put(i % columns, Math.floor(i / columns), 0x2800 + dots[i]!, hue[i]!, tone[i]!)
+  }
+
+  graph.nodes.forEach((v, i) => {
+    if (reach(i) < 1) return
+    const [x, y] = pos[i]!
+    if (v.isSeed) put(x, y, 0x25c9, 0xffd75f, 9) // ◉
+    else if (i === lit) put(x, y, glyphOf(v.label), isPulseOn ? bg : HIGHLIGHT, 10, isPulseOn ? HIGHLIGHT : DEFAULT)
+    else if (markColor(v.id) !== undefined) {
+      const c = markColor(v.id)!
+      put(x, y, glyphOf(v.label), isMarkOn ? bg : c, 10, isMarkOn ? c : DEFAULT)
+    }
+    else put(x, y, glyphOf(v.label), fade(colorOf(v.label), strength[i]!, bg), 8)
+  })
+
+  for (const { i, at, text } of labels) {
+    if (reach(i) < 1) continue
+    const shown = Math.floor(text.length * frame.type)
+    const color = i === lit ? HIGHLIGHT : markColor(graph.nodes[i]!.id) ?? fade(NAME, strength[i]!, bg)
+    for (let k = 0; k < shown; k++) put(at + k, pos[i]![1], text.codePointAt(k)!, color, 3)
+  }
+  return new Uint8Array(words.buffer).toBase64()
+}
+
+/** Unicode braille dot bits, indexed by `row * 2 + column` within the 2×4 cell (U+2800 + bits). */
+const BRAILLE_BIT = [0x01, 0x08, 0x02, 0x10, 0x04, 0x20, 0x40, 0x80]
+
+/** A name short enough to sit on the map: one printable width-1 run, the tail clipped. */
+export function shortName(name: string, max: number): string {
+  const flat = name.replace(/\s+/g, ' ').replace(/[^\x20-\x7e]/g, '').trim()
+  if (max <= 1) return ''
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}~`
+}