@venizia/vulcan 0.4.5 → 0.4.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/checks/wiki-anchors.ts +8 -0
  4. package/base/checks/wiki-source-links.ts +8 -0
  5. package/base/hooks/guard-git.ts +9 -2
  6. package/base/hooks/guard-writes.ts +4 -0
  7. package/base/hooks/session-start.ts +14 -4
  8. package/base/make/vulcan.mk +12 -1
  9. package/base/references/delegation-brief.md +5 -4
  10. package/base/rules.md +2 -2
  11. package/base/skills/docs-writing/SKILL.md +1 -1
  12. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  13. package/base/skills/knowledge-sync/SKILL.md +1 -1
  14. package/base/skills/plan-a-change/SKILL.md +2 -2
  15. package/base/skills/plan-a-change/evals/evals.json +6 -0
  16. package/base/skills/plan-a-change/references/spec-card.md +1 -0
  17. package/base/skills/report-back/SKILL.md +1 -1
  18. package/base/skills/retro/SKILL.md +1 -1
  19. package/base/skills/review-a-change/SKILL.md +1 -1
  20. package/base/skills/ship/SKILL.md +1 -1
  21. package/base/skills/visualize-work/SKILL.md +33 -11
  22. package/base/skills/visualize-work/references/spec.md +77 -12
  23. package/package.json +4 -4
  24. package/src/config/schema.ts +58 -4
  25. package/src/doctor/checks.ts +29 -1
  26. package/src/doctor/runner.ts +2 -0
  27. package/src/hooks/command-view.ts +24 -0
  28. package/src/hooks/common/constants.ts +10 -0
  29. package/src/hooks/guard-git.ts +78 -2
  30. package/src/hooks/guard-outside.ts +20 -3
  31. package/src/hooks/guard-writes.ts +17 -6
  32. package/src/hooks/index.ts +2 -0
  33. package/src/hooks/project-guards.ts +123 -0
  34. package/src/hooks/project-tmp.ts +36 -0
  35. package/src/hooks/session-digest.ts +5 -0
  36. package/src/manifest/render.ts +38 -0
  37. package/src/sync/claude-launch.ts +48 -0
  38. package/src/sync/index.ts +1 -0
  39. package/src/sync/local-choice.ts +2 -0
  40. package/src/visualize/assets.ts +195 -54
  41. package/src/visualize/charts.ts +235 -0
  42. package/src/visualize/constants.ts +106 -1
  43. package/src/visualize/diagrams.ts +224 -0
  44. package/src/visualize/icons.ts +28 -0
  45. package/src/visualize/layout.ts +58 -8
  46. package/src/visualize/page.ts +152 -146
  47. package/src/visualize/schema.ts +246 -0
  48. package/src/visualize/sections.ts +370 -0
  49. package/src/visualize/validate.ts +100 -7
  50. package/src/wiki/anchors.ts +118 -0
  51. package/src/wiki/command.ts +110 -0
  52. package/src/wiki/constants.ts +30 -0
  53. package/src/wiki/index.ts +4 -0
  54. package/src/wiki/source-links.ts +186 -0
@@ -0,0 +1,235 @@
1
+ import { iconSvg } from './icons.ts';
2
+ import { NodeStates } from './constants.ts';
3
+ import type { TChrome } from './constants.ts';
4
+ import { escapeText } from './layout.ts';
5
+ import type { TVisualizeSpec } from './schema.ts';
6
+
7
+ type TChart = NonNullable<NonNullable<TVisualizeSpec['findings']>['charts']>[number];
8
+
9
+ const escaped = (value: string): string => escapeText({ value });
10
+
11
+ /** 1234567 as 1,234,567 and 0.5 as 0.5: no locale, so the page reads the same everywhere. */
12
+ export const formatNumber = (opts: { value: number }): string => {
13
+ const rounded = Math.round(opts.value * 100) / 100;
14
+ const [whole = '0', fraction] = String(Math.abs(rounded)).split('.');
15
+ const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
16
+
17
+ return `${rounded < 0 ? '-' : ''}${grouped}${fraction === undefined ? '' : `.${fraction}`}`;
18
+ };
19
+
20
+ const shorten = (opts: { value: string; max: number }): string =>
21
+ opts.value.length <= opts.max ? opts.value : `${opts.value.slice(0, opts.max - 1)}…`;
22
+
23
+ /** A bar anchored to its baseline: square at the base, 4 px round at the data end. */
24
+ const barPath = (opts: { x: number; y: number; width: number; height: number }): string => {
25
+ const { x, y, width, height } = opts;
26
+ const r = Math.min(4, width / 2, height / 2);
27
+
28
+ return `M${x} ${y}h${width - r}a${r} ${r} 0 0 1 ${r} ${r}v${height - 2 * r}a${r} ${r} 0 0 1 ${-r} ${r}h${-(width - r)}z`;
29
+ };
30
+
31
+ /** A readable axis: a step of 1, 2 or 5 times a power of ten, and the bounds that hold the data. */
32
+ const niceScale = (opts: {
33
+ min: number;
34
+ max: number;
35
+ ticks: number;
36
+ }): { low: number; high: number; step: number } => {
37
+ const span = opts.max - opts.min || Math.abs(opts.max) || 1;
38
+ const raw = span / opts.ticks;
39
+ const power = 10 ** Math.floor(Math.log10(raw));
40
+ const unit = raw / power;
41
+ const step = (unit <= 1 ? 1 : unit <= 2 ? 2 : unit <= 5 ? 5 : 10) * power;
42
+
43
+ return { low: Math.floor(opts.min / step) * step, high: Math.ceil(opts.max / step) * step, step };
44
+ };
45
+
46
+ const VIEW_WIDTH = 340;
47
+
48
+ const barChart = (opts: { chart: Extract<TChart, { type: 'bar' }> }): string => {
49
+ const { labels, values } = opts.chart;
50
+ const max = Math.max(...values, 1);
51
+ const rowHeight = 30;
52
+ const left = 120;
53
+ const plot = 150;
54
+
55
+ return `<svg viewBox="0 0 ${VIEW_WIDTH} ${labels.length * rowHeight + 8}" role="img" aria-label="${escaped(opts.chart.title)}">${labels
56
+ .map((label, index) => {
57
+ const y = index * rowHeight + 6;
58
+ const width = Math.max(2, Math.round(((values[index] ?? 0) / max) * plot));
59
+
60
+ return `<g><title>${escaped(label)}: ${formatNumber({ value: values[index] ?? 0 })}${escaped(opts.chart.unit ?? '')}</title><text x="0" y="${y + 16}" class="ct">${escaped(shorten({ value: label, max: 18 }))}</text><rect x="${left}" y="${y + 2}" width="${plot}" height="18" rx="4" class="ctrack"/><path d="${barPath({ x: left, y: y + 2, width, height: 18 })}" fill="var(--s1)"/><text x="${left + width + 6}" y="${y + 16}" class="cv">${formatNumber({ value: values[index] ?? 0 })}${escaped(opts.chart.unit ?? '')}</text></g>`;
61
+ })
62
+ .join('')}</svg>`;
63
+ };
64
+
65
+ const lineChart = (opts: { chart: Extract<TChart, { type: 'line' }> }): string => {
66
+ const { labels, series } = opts.chart;
67
+ const all = series.flatMap((s) => s.values.slice(0, labels.length));
68
+ const scale = niceScale({ min: Math.min(...all), max: Math.max(...all), ticks: 4 });
69
+ const left = 44;
70
+ const right = 64;
71
+ const top = 12;
72
+ const height = 150;
73
+ const plot = VIEW_WIDTH - left - right;
74
+ const x = (index: number): number => left + (index / (labels.length - 1)) * plot;
75
+ const y = (value: number): number =>
76
+ top + height - ((value - scale.low) / (scale.high - scale.low || 1)) * height;
77
+ const ticks: number[] = [];
78
+
79
+ for (let value = scale.low; value <= scale.high + scale.step / 2; value += scale.step) {
80
+ ticks.push(Math.round(value * 1000) / 1000);
81
+ }
82
+
83
+ const every = labels.length > 6 ? Math.ceil(labels.length / 6) : 1;
84
+ // The direct labels sit at the last point of each line; where two would touch, they are pushed apart by 15 px.
85
+ const ends = series
86
+ .map((s, index) => ({ index, y: y(s.values.slice(0, labels.length).at(-1) ?? 0) }))
87
+ .sort((a, b) => a.y - b.y);
88
+
89
+ for (let at = 1; at < ends.length; at += 1) {
90
+ const previous = ends[at - 1];
91
+ const current = ends[at];
92
+
93
+ if (previous !== undefined && current !== undefined && current.y - previous.y < 15) {
94
+ current.y = previous.y + 15;
95
+ }
96
+ }
97
+
98
+ const labelY = new Map(ends.map((end) => [end.index, end.y]));
99
+
100
+ return `<svg viewBox="0 0 ${VIEW_WIDTH} ${top + height + 34}" role="img" aria-label="${escaped(opts.chart.title)}">${ticks
101
+ .map(
102
+ (tick) =>
103
+ `<line x1="${left}" x2="${VIEW_WIDTH - right}" y1="${y(tick)}" y2="${y(tick)}" class="cgrid"/><text x="${left - 6}" y="${y(tick) + 4}" text-anchor="end" class="ct">${formatNumber({ value: tick })}</text>`,
104
+ )
105
+ .join('')}${labels
106
+ .map((label, index) =>
107
+ index % every === 0
108
+ ? `<text x="${x(index)}" y="${top + height + 20}" text-anchor="middle" class="ct">${escaped(shorten({ value: label, max: 8 }))}</text>`
109
+ : '',
110
+ )
111
+ .join('')}${series
112
+ .map((s, index) => {
113
+ const points = s.values.slice(0, labels.length);
114
+ const path = points.map((value, i) => `${i === 0 ? 'M' : 'L'}${x(i)} ${y(value)}`).join('');
115
+ const last = points.at(-1) ?? 0;
116
+
117
+ return `<g><path d="${path}" fill="none" stroke="var(--s${index + 1})" stroke-width="2.5" stroke-linejoin="round" stroke-linecap="round"/>${points
118
+ .map(
119
+ (value, i) =>
120
+ `<circle cx="${x(i)}" cy="${y(value)}" r="4.5" fill="var(--s${index + 1})" class="cring"><title>${escaped(s.name)}, ${escaped(labels[i] ?? '')}: ${formatNumber({ value })}${escaped(opts.chart.unit ?? '')}</title></circle>`,
121
+ )
122
+ .join(
123
+ '',
124
+ )}<text x="${VIEW_WIDTH - right + 8}" y="${(labelY.get(index) ?? y(last)) + 4}" class="cv">${escaped(shorten({ value: s.name, max: 8 }))}</text></g>`;
125
+ })
126
+ .join('')}</svg>`;
127
+ };
128
+
129
+ const SLOTS = ['var(--s1)', 'var(--s2)', 'var(--s3)', 'var(--s4)', 'var(--s5)'];
130
+
131
+ const donutColour = (opts: { index: number; state?: string }): string =>
132
+ opts.state === undefined
133
+ ? (SLOTS[opts.index] ?? 'var(--s5)')
134
+ : `var(--${NodeStates.toneOf(opts.state)})`;
135
+
136
+ const donutChart = (opts: { chart: Extract<TChart, { type: 'donut' }> }): string => {
137
+ const { parts } = opts.chart;
138
+ const total = parts.reduce((sum, part) => sum + part.value, 0) || 1;
139
+ const radius = 54;
140
+ const circumference = 2 * Math.PI * radius;
141
+ let offset = 0;
142
+ const segments = parts
143
+ .map((part, index) => {
144
+ const share = part.value / total;
145
+ const length = Math.max(0, share * circumference - 3);
146
+ const out = `<circle cx="80" cy="80" r="${radius}" fill="none" stroke="${donutColour({ index, state: part.state })}" stroke-width="22" stroke-dasharray="${length.toFixed(2)} ${(circumference - length).toFixed(2)}" stroke-dashoffset="${(-offset).toFixed(2)}" transform="rotate(-90 80 80)"><title>${escaped(part.label)}: ${formatNumber({ value: part.value })}${escaped(opts.chart.unit ?? '')}</title></circle>`;
147
+
148
+ offset += share * circumference;
149
+
150
+ return out;
151
+ })
152
+ .join('');
153
+
154
+ return `<svg viewBox="0 0 160 160" class="donut-svg" role="img" aria-label="${escaped(opts.chart.title)}">${segments}<text x="80" y="82" text-anchor="middle" class="cbig">${formatNumber({ value: total })}</text><text x="80" y="100" text-anchor="middle" class="ct">${escaped(opts.chart.unit ?? 'total')}</text></svg>`;
155
+ };
156
+
157
+ const legend = (opts: { chart: TChart }): string => {
158
+ const { chart } = opts;
159
+
160
+ if (chart.type === 'donut') {
161
+ const total = chart.parts.reduce((sum, part) => sum + part.value, 0) || 1;
162
+
163
+ return `<ul class="clegend">${chart.parts
164
+ .map(
165
+ (part, index) =>
166
+ `<li><i class="sw" ${part.state === undefined ? `data-s="${index + 1}"` : `data-t="${NodeStates.toneOf(part.state)}"`}></i><span>${escaped(part.label)}</span><b>${formatNumber({ value: part.value })}${escaped(chart.unit ?? '')}</b><em>${Math.round((part.value / total) * 100)}%</em></li>`,
167
+ )
168
+ .join('')}</ul>`;
169
+ }
170
+
171
+ if (chart.type === 'line' && chart.series.length > 1) {
172
+ return `<ul class="clegend row">${chart.series.map((s, index) => `<li><i class="sw" data-s="${index + 1}"></i><span>${escaped(s.name)}</span></li>`).join('')}</ul>`;
173
+ }
174
+
175
+ return '';
176
+ };
177
+
178
+ const tableView = (opts: { chart: TChart; chrome: TChrome }): string => {
179
+ const { chart, chrome } = opts;
180
+ const head =
181
+ chart.type === 'line' ? ['', ...chart.series.map((s) => s.name)] : ['', chrome.value];
182
+ const rows =
183
+ chart.type === 'bar'
184
+ ? chart.labels.map((label, index) => [
185
+ label,
186
+ formatNumber({ value: chart.values[index] ?? 0 }),
187
+ ])
188
+ : chart.type === 'line'
189
+ ? chart.labels.map((label, index) => [
190
+ label,
191
+ ...chart.series.map((s) => formatNumber({ value: s.values[index] ?? 0 })),
192
+ ])
193
+ : chart.parts.map((part) => [part.label, formatNumber({ value: part.value })]);
194
+
195
+ return `<details class="tv"><summary>${escaped(chrome.tableView)}</summary><div class="tw"><table><thead><tr>${head.map((cell) => `<th>${escaped(cell)}</th>`).join('')}</tr></thead><tbody>${rows.map((row) => `<tr>${row.map((cell) => `<td>${escaped(cell)}</td>`).join('')}</tr>`).join('')}</tbody></table></div></details>`;
196
+ };
197
+
198
+ /** One chart as a figure: a title, the drawing, a legend when there is more than one thing to tell apart, and its data as a table. */
199
+ export const renderChart = (opts: { chart: TChart; chrome: TChrome }): string => {
200
+ const { chart } = opts;
201
+ const drawing =
202
+ chart.type === 'bar'
203
+ ? barChart({ chart })
204
+ : chart.type === 'line'
205
+ ? lineChart({ chart })
206
+ : donutChart({ chart });
207
+
208
+ return `<figure class="chart ${chart.type}"><figcaption class="lab">${escaped(chart.title)}</figcaption><div class="cbody">${drawing}${legend({ chart })}</div>${tableView({ chart, chrome: opts.chrome })}</figure>`;
209
+ };
210
+
211
+ /** Total scores of a comparison as horizontal bars out of the maximum, the recommendation in the accent. */
212
+ export const renderTotals = (opts: {
213
+ names: string[];
214
+ totals: number[];
215
+ best: number;
216
+ max: number;
217
+ chrome: TChrome;
218
+ }): string => {
219
+ const rowHeight = 34;
220
+ const plot = 150;
221
+
222
+ return `<svg viewBox="0 0 ${VIEW_WIDTH} ${opts.names.length * rowHeight + 6}" role="img" aria-label="${escaped(opts.chrome.total)}: ${opts.names.map((n, i) => `${escaped(n)} ${opts.totals[i]}`).join(', ')}">${opts.names
223
+ .map((name, index) => {
224
+ const y = index * rowHeight + 4;
225
+ const total = opts.totals[index] ?? 0;
226
+ const width = Math.max(2, Math.round((total / opts.max) * plot));
227
+ const isBest = index === opts.best;
228
+
229
+ return `<g><title>${escaped(name)}: ${total} ${escaped(opts.chrome.outOf)} ${opts.max}</title><text x="0" y="${y + 19}" class="ct${isBest ? ' strong' : ''}">${escaped(shorten({ value: name, max: 18 }))}</text><rect x="120" y="${y + 5}" width="${plot}" height="20" rx="4" class="ctrack"/><path d="${barPath({ x: 120, y: y + 5, width, height: 20 })}" fill="${isBest ? 'var(--acc)' : 'var(--mut)'}" opacity="${isBest ? 1 : 0.6}"/><text x="${120 + width + 6}" y="${y + 20}" class="cv">${total}</text></g>`;
230
+ })
231
+ .join('')}</svg>`;
232
+ };
233
+
234
+ export const stateIcon = (opts: { state: string; size?: number }): string =>
235
+ iconSvg({ name: NodeStates.iconOf(opts.state), size: opts.size });
@@ -25,6 +25,60 @@ export class StatusStates {
25
25
  }
26
26
  }
27
27
 
28
+ /** Where a task stands on the minimap: a shape and a word each, never colour alone. */
29
+ export class MinimapStates {
30
+ static readonly DONE = 'done';
31
+ static readonly IN_PROGRESS = 'in progress';
32
+ static readonly WAITING = 'waiting';
33
+ static readonly NOT_STARTED = 'not started';
34
+ static readonly BLOCKED = 'blocked';
35
+ static readonly DROPPED = 'dropped';
36
+ static readonly SCHEME_SET = new Set<string>([
37
+ this.DONE,
38
+ this.IN_PROGRESS,
39
+ this.WAITING,
40
+ this.NOT_STARTED,
41
+ this.BLOCKED,
42
+ this.DROPPED,
43
+ ]);
44
+ static isValid(value: string): boolean {
45
+ return this.SCHEME_SET.has(value);
46
+ }
47
+
48
+ /** The class and chrome key of a state: the words have spaces, the keys do not. */
49
+ static keyOf(value: string): string {
50
+ return value.replaceAll(' ', '-');
51
+ }
52
+ }
53
+
54
+ /** The state of a box, a milestone or a chart part: a minimap state, or plain information. Never told by colour alone. */
55
+ export class NodeStates {
56
+ static readonly SCHEME_SET = new Set<string>([...MinimapStates.SCHEME_SET, 'info']);
57
+ static isValid(value: string): boolean {
58
+ return this.SCHEME_SET.has(value);
59
+ }
60
+
61
+ /** The colour family of a state: green, blue, amber, red, or neutral. */
62
+ static toneOf(value: string): string {
63
+ const tones: Record<string, string> = {
64
+ done: 'ok',
65
+ 'in progress': 'info',
66
+ waiting: 'warn',
67
+ blocked: 'bad',
68
+ info: 'info',
69
+ };
70
+
71
+ return tones[value] ?? 'mut';
72
+ }
73
+
74
+ /** The icon of a state. */
75
+ static iconOf(value: string): string {
76
+ return MinimapStates.keyOf(value) === 'in-progress'
77
+ ? 'progress'
78
+ : MinimapStates.keyOf(value).replaceAll('-', '');
79
+ }
80
+ }
81
+
28
82
  /** How an edge reads: the main path, a branch, a return, a fan-out or a failure. Never by colour alone. */
29
83
  export class EdgeVariants {
30
84
  static readonly MAIN = 'main';
@@ -87,6 +141,21 @@ export class VisualizeLimits {
87
141
  /** An arrow label has to fit the gap between two boxes. */
88
142
  static readonly MAX_EDGE_LABEL = 20;
89
143
  static readonly MAX_DETAIL = 600;
144
+ static readonly MAX_COMPARE_OPTIONS = 6;
145
+ static readonly MAX_CRITERIA = 8;
146
+ static readonly MAX_BRANCHES = 8;
147
+ static readonly MAX_BRANCH_ITEMS = 6;
148
+ static readonly MAX_EXPLAINER_STEPS = 8;
149
+ static readonly MAX_LAYERS = 5;
150
+ static readonly MAX_LAYER_BOXES = 6;
151
+ static readonly MAX_LINKS = 20;
152
+ static readonly MAX_TIMELINE = 20;
153
+ static readonly MAX_TILES = 6;
154
+ static readonly MAX_CHARTS = 4;
155
+ static readonly MAX_POINTS = 12;
156
+ static readonly MAX_SERIES = 3;
157
+ static readonly MAX_PARTS = 5;
158
+ static readonly MAX_LIST = 6;
90
159
  /** Typical pages are 20-40 KB; a page past `FAIL_BYTES` is refused: two pages, not one dense one. */
91
160
  static readonly WARN_BYTES = 60 * 1024;
92
161
  static readonly FAIL_BYTES = 100 * 1024;
@@ -107,7 +176,20 @@ export const DEFAULT_CHROME = {
107
176
  healthy: 'Healthy?',
108
177
  blockedBy: 'Blocked by',
109
178
  changed: 'What changed',
110
- next: 'What needs action',
179
+ next: 'What you need to do',
180
+ minimap: 'Where things stand',
181
+ task: 'Task',
182
+ minimapStates: {
183
+ done: 'done',
184
+ 'in-progress': 'in progress',
185
+ waiting: 'waiting',
186
+ 'not-started': 'not started',
187
+ blocked: 'blocked',
188
+ dropped: 'dropped',
189
+ info: 'for information',
190
+ },
191
+ actions: 'Do these, in order',
192
+ footer: 'Static page by vulcan visualize; it loads nothing.',
111
193
  flow: 'How it flows',
112
194
  legend: 'Legend',
113
195
  play: 'Play',
@@ -138,5 +220,28 @@ export const DEFAULT_CHROME = {
138
220
  log: 'Log',
139
221
  links: 'Links',
140
222
  theme: 'Theme',
223
+ present: 'Present',
224
+ exitPresent: 'Exit',
225
+ slide: 'Slide',
226
+ slideOf: 'of',
227
+ comparison: 'Comparison',
228
+ total: 'Total score',
229
+ outOf: 'out of',
230
+ pros: 'For',
231
+ cons: 'Against',
232
+ ideaMap: 'Idea map',
233
+ explainer: 'How it works',
234
+ architecture: 'Architecture',
235
+ timeline: 'Timeline',
236
+ findings: 'Findings',
237
+ decisionRecord: 'Decision record',
238
+ context: 'Context',
239
+ optionsConsidered: 'Options considered',
240
+ decision: 'Decision',
241
+ chosen: 'Chosen',
242
+ consequences: 'Consequences',
243
+ tableView: 'Table view',
244
+ value: 'Value',
245
+ uses: 'Uses',
141
246
  };
142
247
  export type TChrome = typeof DEFAULT_CHROME;
@@ -0,0 +1,224 @@
1
+ import { NodeStates } from './constants.ts';
2
+ import type { TChrome } from './constants.ts';
3
+ import { stateIcon } from './charts.ts';
4
+ import { iconSvg } from './icons.ts';
5
+ import { escapeText } from './layout.ts';
6
+ import type { TVisualizeSpec } from './schema.ts';
7
+
8
+ type TDiagram = NonNullable<NonNullable<TVisualizeSpec['explainer']>['steps'][number]['diagram']>;
9
+ type TArchitecture = NonNullable<TVisualizeSpec['architecture']>;
10
+
11
+ /** A drawing, the width it needs to keep its text readable, and the list that replaces it on a phone. */
12
+ export interface IDrawing {
13
+ svg: string;
14
+ width: number;
15
+ fallback: string;
16
+ }
17
+
18
+ const escaped = (value: string): string => escapeText({ value });
19
+
20
+ const box = (opts: {
21
+ x: number;
22
+ y: number;
23
+ width: number;
24
+ height: number;
25
+ label: string;
26
+ sub?: string;
27
+ tone?: string;
28
+ icon?: string;
29
+ }): string => {
30
+ const { x, y, width, height } = opts;
31
+ const text = opts.icon === undefined ? 14 : 38;
32
+
33
+ return `<g class="dbox${opts.tone === undefined ? '' : ` c-${opts.tone}`}"><rect x="${x}" y="${y}" width="${width}" height="${height}" rx="4"/>${opts.icon === undefined ? '' : `<g class="st" transform="translate(${x + 10} ${y + height / 2 - 10})">${opts.icon.replace('<svg', '<svg x="0" y="0"')}</g>`}<text class="t" x="${opts.icon === undefined ? x + width / 2 : x + text}" y="${y + height / 2 + (opts.sub === undefined ? 5 : -3)}" text-anchor="${opts.icon === undefined ? 'middle' : 'start'}">${escaped(opts.label)}</text>${opts.sub === undefined ? '' : `<text class="s" x="${opts.icon === undefined ? x + width / 2 : x + text}" y="${y + height / 2 + 15}" text-anchor="${opts.icon === undefined ? 'middle' : 'start'}">${escaped(opts.sub)}</text>`}</g>`;
34
+ };
35
+
36
+ const arrowHead = (opts: { x: number; y: number }): string =>
37
+ `<path d="M${opts.x - 7} ${opts.y - 5}L${opts.x} ${opts.y}L${opts.x - 7} ${opts.y + 5}" fill="none" class="dline"/>`;
38
+
39
+ /** An explainer step's diagram: a row of boxes joined by labelled arrows, or stacked layers. */
40
+ export const renderDiagram = (opts: { diagram: TDiagram }): IDrawing => {
41
+ const { diagram } = opts;
42
+
43
+ if (diagram.type === 'row') {
44
+ const longest = Math.max(
45
+ ...diagram.nodes.flatMap((node) => [node.label.length * 8.2, (node.sub?.length ?? 0) * 7.6]),
46
+ );
47
+ const bw = Math.max(124, Math.ceil(longest) + 24);
48
+ const gap = 78;
49
+ const width = diagram.nodes.length * bw + (diagram.nodes.length - 1) * gap + 16;
50
+ const parts = diagram.nodes
51
+ .map((node, index) => {
52
+ const x = 8 + index * (bw + gap);
53
+ const label = diagram.arrows?.[index];
54
+ const arrow =
55
+ index < diagram.nodes.length - 1
56
+ ? `<path d="M${x + bw + 4} 40H${x + bw + gap - 4}" class="dline"/>${arrowHead({ x: x + bw + gap - 4, y: 40 })}${label === undefined ? '' : `<text class="dl" x="${x + bw + gap / 2}" y="30" text-anchor="middle">${escaped(label)}</text>`}`
57
+ : '';
58
+
59
+ return `${box({ x, y: 12, width: bw, height: 56, label: node.label, sub: node.sub })}${arrow}`;
60
+ })
61
+ .join('');
62
+
63
+ return {
64
+ svg: `<svg width="${width}" viewBox="0 0 ${width} 80" role="group" aria-label="diagram">${parts}</svg>`,
65
+ width,
66
+ fallback: `<ol class="path">${diagram.nodes
67
+ .map(
68
+ (node, index) =>
69
+ `<li><b>${escaped(node.label)}</b>${node.sub === undefined ? '' : ` <span class="mut">${escaped(node.sub)}</span>`}${index < diagram.nodes.length - 1 && diagram.arrows?.[index] !== undefined ? `<span class="verb">${escaped(diagram.arrows[index] ?? '')}</span>` : ''}</li>`,
70
+ )
71
+ .join('')}</ol>`,
72
+ };
73
+ }
74
+
75
+ const most = Math.max(...diagram.layers.map((layer) => layer.items.length));
76
+ const label = Math.max(
77
+ 112,
78
+ Math.ceil(Math.max(...diagram.layers.map((layer) => layer.label.length)) * 8.8) + 30,
79
+ );
80
+ const iw = Math.max(
81
+ 112,
82
+ Math.ceil(
83
+ Math.max(...diagram.layers.flatMap((layer) => layer.items.map((item) => item.length))) * 8,
84
+ ) + 24,
85
+ );
86
+ const width = label + most * (iw + 10) + 14;
87
+ const parts = diagram.layers
88
+ .map((layer, row) => {
89
+ const y = 8 + row * 62;
90
+
91
+ return `<g><rect x="4" y="${y}" width="${width - 8}" height="54" rx="4" class="dband"/><text class="dlab" x="14" y="${y + 31}">${escaped(layer.label)}</text>${layer.items.map((item, col) => box({ x: label + col * (iw + 10), y: y + 8, width: iw, height: 38, label: item })).join('')}</g>`;
92
+ })
93
+ .join('');
94
+
95
+ return {
96
+ svg: `<svg width="${width}" viewBox="0 0 ${width} ${diagram.layers.length * 62 + 12}" role="group" aria-label="layers">${parts}</svg>`,
97
+ width,
98
+ fallback: `<ul class="path">${diagram.layers.map((layer) => `<li><b>${escaped(layer.label)}</b>: ${layer.items.map(escaped).join(', ')}</li>`).join('')}</ul>`,
99
+ };
100
+ };
101
+
102
+ /** The layered view: bands from top to bottom, boxes in each, and an elbow line for every link. */
103
+ export const renderArchitecture = (opts: {
104
+ architecture: TArchitecture;
105
+ chrome: TChrome;
106
+ }): IDrawing => {
107
+ const { architecture } = opts;
108
+ const most = Math.max(...architecture.layers.map((layer) => layer.boxes.length));
109
+ const label = 120;
110
+ const bw = 176;
111
+ const bh = 68;
112
+ const gap = 64;
113
+ const rowHeight = 190;
114
+ const width = label + most * (bw + gap) + 4;
115
+ const height = architecture.layers.length * rowHeight + 8;
116
+ const positions = new Map<string, { x: number; y: number; row: number }>();
117
+
118
+ architecture.layers.forEach((layer, row) => {
119
+ const total = layer.boxes.length * (bw + gap) - gap;
120
+ const start = label + (most * (bw + gap) - gap - total) / 2;
121
+
122
+ layer.boxes.forEach((boxSpec, col) =>
123
+ positions.set(boxSpec.id, { x: start + col * (bw + gap), y: 4 + row * rowHeight + 34, row }),
124
+ );
125
+ });
126
+
127
+ const bands = architecture.layers
128
+ .map(
129
+ (layer, row) =>
130
+ `<rect x="2" y="${4 + row * rowHeight}" width="${width - 4}" height="${rowHeight - 14}" rx="4" class="dband"/><text class="dlab" x="14" y="${4 + row * rowHeight + 24}">${escaped(layer.label)}</text>`,
131
+ )
132
+ .join('');
133
+ // Links that cross the same gap between two layers get their own horizontal run, so no two lines share one.
134
+ const lanes = new Map<number, number>();
135
+ const across = new Map<number, number>();
136
+
137
+ for (const link of architecture.links) {
138
+ const from = positions.get(link.from);
139
+ const to = positions.get(link.to);
140
+
141
+ if (from !== undefined && to !== undefined && from.row !== to.row) {
142
+ across.set(Math.min(from.row, to.row), (across.get(Math.min(from.row, to.row)) ?? 0) + 1);
143
+ }
144
+ }
145
+
146
+ const links = architecture.links
147
+ .map((link) => {
148
+ const a = positions.get(link.from);
149
+ const b = positions.get(link.to);
150
+
151
+ if (a === undefined || b === undefined) {
152
+ return '';
153
+ }
154
+
155
+ if (a.row === b.row) {
156
+ const sign = a.x < b.x ? 1 : -1;
157
+ const x1 = sign === 1 ? a.x + bw : a.x;
158
+ const x2 = sign === 1 ? b.x : b.x + bw;
159
+ const y = a.y + bh / 2;
160
+
161
+ return `<g class="dlink"><path d="M${x1} ${y}H${x2}" class="dline"/><path d="M${x2 - sign * 7} ${y - 5}L${x2} ${y}L${x2 - sign * 7} ${y + 5}" fill="none" class="dline"/>${link.label === undefined ? '' : `<text class="dl" x="${(x1 + x2) / 2}" y="${y - 8}" text-anchor="middle">${escaped(link.label)}</text>`}</g>`;
162
+ }
163
+
164
+ const down = a.row < b.row;
165
+ const gapIndex = Math.min(a.row, b.row);
166
+ const lane = lanes.get(gapIndex) ?? 0;
167
+
168
+ lanes.set(gapIndex, lane + 1);
169
+
170
+ const top = 4 + gapIndex * rowHeight + 34 + bh;
171
+ const bottom = 4 + (gapIndex + 1) * rowHeight + 34;
172
+ const ym = top + 14 + ((bottom - top - 28) * (lane + 1)) / ((across.get(gapIndex) ?? 1) + 1);
173
+ const shift = lane % 3 === 1 ? 10 : lane % 3 === 2 ? -10 : 0;
174
+ const x1 = a.x + bw / 2 + shift;
175
+ const x2 = b.x + bw / 2 + shift;
176
+ const y1 = down ? a.y + bh : a.y;
177
+ const y2 = down ? b.y : b.y + bh;
178
+ const tip = down ? -7 : 7;
179
+
180
+ return `<g class="dlink"><path d="M${x1} ${y1}V${ym}H${x2}V${y2}" class="dline"/><path d="M${x2 - 5} ${y2 + tip}L${x2} ${y2}L${x2 + 5} ${y2 + tip}" fill="none" class="dline"/>${link.label === undefined ? '' : `<text class="dl" x="${(x1 + x2) / 2}" y="${ym - 5}" text-anchor="middle">${escaped(link.label)}</text>`}</g>`;
181
+ })
182
+ .join('');
183
+ const boxes = architecture.layers
184
+ .flatMap((layer) => layer.boxes)
185
+ .map((spec) => {
186
+ const p = positions.get(spec.id);
187
+
188
+ return p === undefined
189
+ ? ''
190
+ : box({
191
+ x: p.x,
192
+ y: p.y,
193
+ width: bw,
194
+ height: bh,
195
+ label: spec.label,
196
+ sub: spec.sub,
197
+ tone: spec.state === undefined ? undefined : NodeStates.toneOf(spec.state),
198
+ icon: spec.state === undefined ? undefined : stateIcon({ state: spec.state, size: 20 }),
199
+ });
200
+ })
201
+ .join('');
202
+ const names = new Map(
203
+ architecture.layers.flatMap((layer) =>
204
+ layer.boxes.map((spec) => [spec.id, spec.label] as const),
205
+ ),
206
+ );
207
+
208
+ return {
209
+ svg: `<svg width="${width}" viewBox="0 0 ${width} ${height}" role="group" aria-label="${escaped(opts.chrome.architecture)}">${bands}${links}${boxes}</svg>`,
210
+ width,
211
+ fallback: `<ul class="path">${architecture.layers.map((layer) => `<li><b>${escaped(layer.label)}</b>: ${layer.boxes.map((spec) => `${spec.state === undefined ? '' : `<span class="c-${NodeStates.toneOf(spec.state)} inl">${stateIcon({ state: spec.state, size: 16 })}</span>`}${escaped(spec.label)}`).join(', ')}</li>`).join('')}${architecture.links.map((link) => `<li>${escaped(names.get(link.from) ?? link.from)} <span class="verb">${escaped(link.label ?? opts.chrome.uses)}</span> ${escaped(names.get(link.to) ?? link.to)}</li>`).join('')}</ul>`,
212
+ };
213
+ };
214
+
215
+ /** The idea map: the centre between two columns of branches, each branch a cluster of ideas. */
216
+ export const renderIdeaMap = (opts: { map: NonNullable<TVisualizeSpec['ideaMap']> }): string => {
217
+ const { map } = opts;
218
+ const cluster = (branch: (typeof map.branches)[number], index: number): string =>
219
+ `<li class="branch" data-s="${(index % 5) + 1}"><h3><i class="sw" data-s="${(index % 5) + 1}"></i>${escaped(branch.label)}</h3><ul class="chips">${branch.items.map((item) => `<li>${escaped(item)}</li>`).join('')}</ul>${branch.note === undefined ? '' : `<p class="mut">${escaped(branch.note)}</p>`}</li>`;
220
+ const left = map.branches.filter((_, index) => index % 2 === 0);
221
+ const right = map.branches.filter((_, index) => index % 2 === 1);
222
+
223
+ return `<div class="idea"><ul class="side l">${left.map((branch, i) => cluster(branch, i * 2)).join('')}</ul><div class="centre">${iconSvg({ name: 'star', size: 22 })}<b>${escaped(map.center)}</b></div><ul class="side r">${right.map((branch, i) => cluster(branch, i * 2 + 1)).join('')}</ul></div>`;
224
+ };
@@ -0,0 +1,28 @@
1
+ /** Inline SVG icons, 24 by 24, drawn in `currentColor`: the page loads no icon font and no image. */
2
+ const PATHS: Record<string, string> = {
3
+ done: '<circle cx="12" cy="12" r="9"/><path d="M8 12.5l3 3 5-6"/>',
4
+ progress:
5
+ '<circle cx="12" cy="12" r="9"/><path d="M12 3a9 9 0 0 1 0 18z" fill="currentColor" stroke="none"/>',
6
+ waiting: '<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/>',
7
+ blocked: '<path d="M8.5 3h7L21 8.5v7L15.5 21h-7L3 15.5v-7z"/><path d="M9 9l6 6M15 9l-6 6"/>',
8
+ notstarted: '<circle cx="12" cy="12" r="9" stroke-dasharray="3.2 3.2"/>',
9
+ dropped: '<circle cx="12" cy="12" r="9"/><path d="M8 12h8"/>',
10
+ info: '<circle cx="12" cy="12" r="9"/><path d="M12 11v5M12 8h.01"/>',
11
+ arrow: '<path d="M5 12h14M13 6l6 6-6 6"/>',
12
+ plus: '<path d="M12 5v14M5 12h14"/>',
13
+ minus: '<path d="M5 12h14"/>',
14
+ verified:
15
+ '<path d="M12 3l8 3v6c0 5-3.5 8-8 9-4.5-1-8-4-8-9V6z"/><path d="M8.5 12l2.5 2.5 4.5-5"/>',
16
+ inferred: '<path d="M3 15c3-6 5-6 9 0s6 6 9 0"/>',
17
+ guess:
18
+ '<circle cx="12" cy="12" r="9"/><path d="M9.5 9.5a2.5 2.5 0 1 1 3.5 2.3c-.7.4-1 1-1 1.7M12 17h.01"/>',
19
+ quote: '<path d="M9 7H5v6h4l-2 4M19 7h-4v6h4l-2 4"/>',
20
+ star: '<path d="M12 3l2.7 5.8 6.3.7-4.7 4.3 1.3 6.2L12 17l-5.6 3 1.3-6.2L3 9.5l6.3-.7z"/>',
21
+ check: '<path d="M5 12.5l4.5 4.5L19 7"/>',
22
+ };
23
+
24
+ export const iconSvg = (opts: { name: string; size?: number }): string => {
25
+ const size = opts.size ?? 20;
26
+
27
+ return `<svg class="ic" viewBox="0 0 24 24" width="${size}" height="${size}" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${PATHS[opts.name] ?? ''}</svg>`;
28
+ };