@venizia/vulcan 0.4.4 → 0.4.6

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 (88) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/agents.json +22 -1
  4. package/base/checks/wiki-anchors.ts +8 -0
  5. package/base/checks/wiki-source-links.ts +8 -0
  6. package/base/claude/remote-hosts.json +1 -1
  7. package/base/claude/settings.json +12 -12
  8. package/base/extensions/vulcan-guards.ts +301 -0
  9. package/base/hooks/antigravity-guards.ts +68 -0
  10. package/base/hooks/codex-guards.ts +66 -0
  11. package/base/hooks/guard-git.ts +38 -9
  12. package/base/hooks/guard-outside.ts +29 -9
  13. package/base/hooks/guard-writes.ts +29 -1
  14. package/base/hooks/session-start.ts +14 -4
  15. package/base/make/vulcan.mk +12 -1
  16. package/base/references/delegation-brief.md +5 -4
  17. package/base/rules.md +2 -2
  18. package/base/skills/docs-writing/SKILL.md +1 -1
  19. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  20. package/base/skills/knowledge-sync/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/SKILL.md +1 -1
  22. package/base/skills/report-back/SKILL.md +1 -1
  23. package/base/skills/retro/SKILL.md +1 -1
  24. package/base/skills/review-a-change/SKILL.md +1 -1
  25. package/base/skills/ship/SKILL.md +1 -1
  26. package/base/skills/visualize-work/SKILL.md +33 -11
  27. package/base/skills/visualize-work/references/spec.md +77 -12
  28. package/package.json +4 -4
  29. package/src/agents/codex-hooks.ts +133 -0
  30. package/src/agents/common/constants.ts +54 -0
  31. package/src/agents/common/schema.ts +10 -1
  32. package/src/agents/common/types.ts +3 -1
  33. package/src/agents/exclude.ts +4 -0
  34. package/src/agents/hooks-json.ts +111 -0
  35. package/src/agents/index.ts +2 -0
  36. package/src/agents/render.ts +5 -4
  37. package/src/agents/resolve.ts +24 -9
  38. package/src/config/common/constants.ts +12 -0
  39. package/src/config/common/types.ts +2 -1
  40. package/src/config/packages.ts +2 -1
  41. package/src/config/schema.ts +84 -5
  42. package/src/create/add-app.ts +2 -2
  43. package/src/create/add-lib.ts +21 -8
  44. package/src/create/common/constants.ts +12 -0
  45. package/src/create/common/types.ts +2 -1
  46. package/src/create/preset-diff.ts +4 -2
  47. package/src/create/workspace.ts +13 -9
  48. package/src/doctor/checks.ts +71 -1
  49. package/src/doctor/common/constants.ts +2 -0
  50. package/src/doctor/runner.ts +6 -0
  51. package/src/hooks/codex-patch.ts +47 -0
  52. package/src/hooks/command-view.ts +97 -0
  53. package/src/hooks/common/constants.ts +46 -0
  54. package/src/hooks/common/types.ts +9 -1
  55. package/src/hooks/decision.ts +50 -8
  56. package/src/hooks/guard-git.ts +64 -5
  57. package/src/hooks/guard-manifest.ts +22 -8
  58. package/src/hooks/guard-outside.ts +38 -6
  59. package/src/hooks/guard-package.ts +15 -12
  60. package/src/hooks/guard-writes.ts +72 -21
  61. package/src/hooks/index.ts +5 -0
  62. package/src/hooks/project-guards.ts +123 -0
  63. package/src/hooks/project-tmp.ts +36 -0
  64. package/src/hooks/remote-hosts.ts +38 -14
  65. package/src/hooks/session-digest.ts +5 -0
  66. package/src/hooks/shell.ts +665 -35
  67. package/src/hooks/trusted-scripts.ts +134 -0
  68. package/src/manifest/render.ts +38 -0
  69. package/src/sync/agent-files.ts +122 -4
  70. package/src/sync/agent-removal.ts +118 -4
  71. package/src/sync/claude-launch.ts +48 -0
  72. package/src/sync/index.ts +1 -0
  73. package/src/sync/local-choice.ts +2 -0
  74. package/src/visualize/assets.ts +195 -54
  75. package/src/visualize/charts.ts +235 -0
  76. package/src/visualize/constants.ts +122 -1
  77. package/src/visualize/diagrams.ts +224 -0
  78. package/src/visualize/icons.ts +28 -0
  79. package/src/visualize/layout.ts +58 -8
  80. package/src/visualize/page.ts +151 -145
  81. package/src/visualize/schema.ts +252 -2
  82. package/src/visualize/sections.ts +370 -0
  83. package/src/visualize/validate.ts +100 -7
  84. package/src/wiki/anchors.ts +118 -0
  85. package/src/wiki/command.ts +110 -0
  86. package/src/wiki/constants.ts +30 -0
  87. package/src/wiki/index.ts +4 -0
  88. package/src/wiki/source-links.ts +186 -0
@@ -1,3 +1,19 @@
1
+ import type { TConstValue } from '../common/index.ts';
2
+
3
+ /** Which side of a before/after page a row is on: what was added, what was removed. */
4
+ export class ChangeKinds {
5
+ static readonly ADDED = 'added';
6
+ static readonly REMOVED = 'removed';
7
+
8
+ static readonly SCHEME_SET = new Set<string>([this.ADDED, this.REMOVED]);
9
+
10
+ static isValid(value: string): boolean {
11
+ return this.SCHEME_SET.has(value);
12
+ }
13
+ }
14
+
15
+ export type TChangeKind = TConstValue<typeof ChangeKinds>;
16
+
1
17
  export class StatusStates {
2
18
  static readonly OK = 'ok';
3
19
  static readonly WARN = 'warn';
@@ -9,6 +25,60 @@ export class StatusStates {
9
25
  }
10
26
  }
11
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
+
12
82
  /** How an edge reads: the main path, a branch, a return, a fan-out or a failure. Never by colour alone. */
13
83
  export class EdgeVariants {
14
84
  static readonly MAIN = 'main';
@@ -71,6 +141,21 @@ export class VisualizeLimits {
71
141
  /** An arrow label has to fit the gap between two boxes. */
72
142
  static readonly MAX_EDGE_LABEL = 20;
73
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;
74
159
  /** Typical pages are 20-40 KB; a page past `FAIL_BYTES` is refused: two pages, not one dense one. */
75
160
  static readonly WARN_BYTES = 60 * 1024;
76
161
  static readonly FAIL_BYTES = 100 * 1024;
@@ -91,7 +176,20 @@ export const DEFAULT_CHROME = {
91
176
  healthy: 'Healthy?',
92
177
  blockedBy: 'Blocked by',
93
178
  changed: 'What changed',
94
- 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.',
95
193
  flow: 'How it flows',
96
194
  legend: 'Legend',
97
195
  play: 'Play',
@@ -122,5 +220,28 @@ export const DEFAULT_CHROME = {
122
220
  log: 'Log',
123
221
  links: 'Links',
124
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',
125
246
  };
126
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
+ };
@@ -1,3 +1,5 @@
1
+ import { NodeStates } from './constants.ts';
2
+ import { iconSvg } from './icons.ts';
1
3
  import type { TVisualizeSpec } from './schema.ts';
2
4
 
3
5
  /** Escapes text for HTML and for an attribute value: everything the spec says is data, never markup. */
@@ -9,11 +11,21 @@ export const escapeText = (opts: { value: string }): string =>
9
11
  .replaceAll('"', '&quot;')
10
12
  .replaceAll("'", '&#39;');
11
13
 
12
- const CELL_WIDTH = 300;
13
- const CELL_HEIGHT = 120;
14
- const BOX_WIDTH = 160;
15
- const BOX_HEIGHT = 64;
16
- const MARGIN = 28;
14
+ const CELL_WIDTH = 290;
15
+ const CELL_HEIGHT = 112;
16
+ const BOX_WIDTH = 176;
17
+ const BOX_HEIGHT = 60;
18
+ const MARGIN = 24;
19
+
20
+ /** Below this share of its natural width the figure is replaced by a list, so no text drops under 12 px. */
21
+ export const FIGURE_FIT = 0.92;
22
+
23
+ /** The natural width of a figure of `cols` columns, in pixels. */
24
+ export const figureWidth = (opts: { cols: number }): number => MARGIN * 2 + opts.cols * CELL_WIDTH;
25
+
26
+ /** How many columns a flow spans. */
27
+ export const columnsOf = (opts: { flow: NonNullable<TVisualizeSpec['flow']> }): number =>
28
+ Math.max(...opts.flow.nodes.map((node) => node.col)) + 1;
17
29
 
18
30
  interface IPoint {
19
31
  x: number;
@@ -77,7 +89,7 @@ const routeOf = (opts: { from: IPoint; to: IPoint }): { path: string; label: IPo
77
89
  export const renderFigure = (opts: { flow: NonNullable<TVisualizeSpec['flow']> }): string => {
78
90
  const { flow } = opts;
79
91
  const byId = new Map(flow.nodes.map((node) => [node.id, node]));
80
- const width = MARGIN * 2 + (Math.max(...flow.nodes.map((node) => node.col)) + 1) * CELL_WIDTH;
92
+ const width = figureWidth({ cols: columnsOf({ flow }) });
81
93
  const height = MARGIN * 2 + (Math.max(...flow.nodes.map((node) => node.row)) + 1) * CELL_HEIGHT;
82
94
  const edges = flow.edges
83
95
  .map((edge) => {
@@ -98,10 +110,48 @@ export const renderFigure = (opts: { flow: NonNullable<TVisualizeSpec['flow']> }
98
110
  .map((node) => {
99
111
  const centre = centreOf(node);
100
112
  const lines = node.sublabel === undefined ? 1 : 2;
101
-
102
- return `<g class="node ${escaped(node.kind ?? 'step')}" tabindex="0" role="img" aria-label="${escaped(node.label)}${node.sublabel === undefined ? '' : `, ${escaped(node.sublabel)}`}" data-node="${escaped(node.id)}" data-detail="${escaped(node.detail ?? node.sublabel ?? node.label)}"><title>${escaped(node.label)}</title><rect x="${centre.x - BOX_WIDTH / 2}" y="${centre.y - BOX_HEIGHT / 2}" width="${BOX_WIDTH}" height="${BOX_HEIGHT}" rx="10"/><text x="${centre.x}" y="${centre.y + (lines === 1 ? 5 : -4)}" text-anchor="middle" class="t">${escaped(node.label)}</text>${node.sublabel === undefined ? '' : `<text x="${centre.x}" y="${centre.y + 16}" text-anchor="middle" class="s">${escaped(node.sublabel)}</text>`}</g>`;
113
+ const tone = node.state === undefined ? '' : ` c-${NodeStates.toneOf(node.state)}`;
114
+ const left = centre.x - BOX_WIDTH / 2;
115
+ const anchor = node.state === undefined ? 'middle' : 'start';
116
+ const textX = node.state === undefined ? centre.x : left + 40;
117
+ const mark =
118
+ node.state === undefined
119
+ ? ''
120
+ : `<g class="st" transform="translate(${left + 12} ${centre.y - 10})">${iconSvg({ name: NodeStates.iconOf(node.state), size: 20 }).replace('<svg', '<svg x="0" y="0"')}</g>`;
121
+
122
+ return `<g class="node ${escaped(node.kind ?? 'step')}${tone}" tabindex="0" role="img" aria-label="${escaped(node.label)}${node.sublabel === undefined ? '' : `, ${escaped(node.sublabel)}`}" data-node="${escaped(node.id)}" data-detail="${escaped(node.detail ?? node.sublabel ?? node.label)}"><title>${escaped(node.label)}</title><rect x="${left}" y="${centre.y - BOX_HEIGHT / 2}" width="${BOX_WIDTH}" height="${BOX_HEIGHT}" rx="4"/>${mark}<text x="${textX}" y="${centre.y + (lines === 1 ? 5 : -4)}" text-anchor="${anchor}" class="t">${escaped(node.label)}</text>${node.sublabel === undefined ? '' : `<text x="${textX}" y="${centre.y + 17}" text-anchor="${anchor}" class="s">${escaped(node.sublabel)}</text>`}</g>`;
103
123
  })
104
124
  .join('');
105
125
 
106
126
  return `<svg width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="group" aria-label="flow"><defs><marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="currentColor"/></marker><marker id="e" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path class="bad" d="M0 0L10 5L0 10z"/></marker></defs>${edges}${nodes}</svg>`;
107
127
  };
128
+
129
+ /**
130
+ * The same flow as a list, for a phone where the figure cannot be read: one row per arrow, then one per box that
131
+ * has a detail. Page CSS shows it only on a narrow screen.
132
+ */
133
+ export const renderPathList = (opts: { flow: NonNullable<TVisualizeSpec['flow']> }): string => {
134
+ const { flow } = opts;
135
+ const byId = new Map(flow.nodes.map((node) => [node.id, node]));
136
+ const nameOf = (id: string): string => {
137
+ const node = byId.get(id);
138
+ const mark =
139
+ node?.state === undefined
140
+ ? ''
141
+ : `<span class="inl c-${NodeStates.toneOf(node.state)}">${iconSvg({ name: NodeStates.iconOf(node.state), size: 16 })}</span>`;
142
+
143
+ return `${mark}${escaped(node?.label ?? id)}`;
144
+ };
145
+ const arrows = flow.edges
146
+ .map(
147
+ (edge) =>
148
+ `<li><b>${nameOf(edge.from)}</b><span class="verb ${escaped(edge.variant ?? 'main')}">${escaped(edge.label)}</span><b>${nameOf(edge.to)}</b></li>`,
149
+ )
150
+ .join('');
151
+ const details = flow.nodes
152
+ .filter((node) => node.detail !== undefined)
153
+ .map((node) => `<li><b>${escaped(node.label)}</b> ${escaped(node.detail ?? '')}</li>`)
154
+ .join('');
155
+
156
+ return `<ol class="path">${arrows}</ol>${details === '' ? '' : `<ul class="path-detail">${details}</ul>`}`;
157
+ };