@venizia/vulcan 0.4.10-2 → 0.4.10-21

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 (208) hide show
  1. package/README.md +30 -23
  2. package/base/checks/wiki-source-links.ts +17 -1
  3. package/base/claude/events.json +1 -11
  4. package/base/claude/settings.json +5 -76
  5. package/base/extensions/vulcan-guards.ts +81 -18
  6. package/base/hooks/guard-git.ts +95 -19
  7. package/base/hooks/guard-outside.ts +163 -43
  8. package/base/hooks/guard-writes.ts +15 -36
  9. package/base/hooks/session-start.ts +1 -1
  10. package/base/make/vulcan.mk +8 -5
  11. package/base/packs/venizia.md +16 -0
  12. package/base/references/delegation-brief.md +3 -5
  13. package/base/references/testing.md +1 -9
  14. package/base/rules.md +33 -38
  15. package/base/skills/build-a-feature/SKILL.md +4 -4
  16. package/base/skills/docs-update/SKILL.md +19 -8
  17. package/base/skills/fix-a-bug/SKILL.md +4 -2
  18. package/base/skills/plan-a-change/SKILL.md +1 -1
  19. package/base/skills/research/SKILL.md +1 -1
  20. package/base/skills/retro/SKILL.md +2 -2
  21. package/base/skills/review-a-change/SKILL.md +1 -1
  22. package/base/skills/visualize-work/SKILL.md +3 -3
  23. package/base/skills/visualize-work/references/spec.md +6 -3
  24. package/base/templates/AGENTS.md +9 -7
  25. package/base/templates/board.html +10 -110
  26. package/package.json +3 -3
  27. package/src/agents/atlas-block.ts +8 -31
  28. package/src/agents/codex-hooks.ts +1 -1
  29. package/src/agents/generated-block.ts +52 -0
  30. package/src/agents/hooks-json.ts +22 -3
  31. package/src/agents/index.ts +2 -0
  32. package/src/agents/render.ts +15 -2
  33. package/src/agents/resolve.ts +1 -0
  34. package/src/agents/rules-block.ts +92 -0
  35. package/src/board/command.ts +92 -30
  36. package/src/board/common/constants.ts +26 -0
  37. package/src/board/common/types.ts +10 -3
  38. package/src/board/fold.ts +1 -1
  39. package/src/board/github.ts +1 -2
  40. package/src/board/gitlab.ts +436 -0
  41. package/src/board/index.ts +1 -0
  42. package/src/board/logo.ts +49 -0
  43. package/src/board/open-file.ts +110 -0
  44. package/src/board/page.ts +57 -5
  45. package/src/board/schema.ts +4 -1
  46. package/src/board/server.ts +87 -3
  47. package/src/board/settings.ts +21 -24
  48. package/src/commands/changelog.command.ts +40 -0
  49. package/src/commands/clean.command.ts +6 -1
  50. package/src/commands/help.command.ts +2 -63
  51. package/src/commands/index.ts +6 -1
  52. package/src/commands/migrate.command.ts +71 -0
  53. package/src/commands/profile.command.ts +1 -1
  54. package/src/commands/runners.command.ts +43 -0
  55. package/src/commands/sync.command.ts +8 -4
  56. package/src/commands/table.ts +362 -0
  57. package/src/commit/check.ts +1 -0
  58. package/src/commit/common/constants.ts +4 -0
  59. package/src/commit/hook.ts +112 -8
  60. package/src/common/constants.ts +11 -9
  61. package/src/common/env-variables.ts +41 -0
  62. package/src/common/index.ts +1 -0
  63. package/src/common/layout-folder.ts +3 -4
  64. package/src/common/record.ts +5 -0
  65. package/src/config/common/constants.ts +28 -22
  66. package/src/config/loader.ts +22 -0
  67. package/src/config/schema.ts +330 -146
  68. package/src/create/add-app.ts +7 -2
  69. package/src/create/add-lib.ts +2 -4
  70. package/src/create/common/constants.ts +5 -3
  71. package/src/create/preset.ts +1 -0
  72. package/src/create/scratch.ts +2 -1
  73. package/src/doctor/checks.ts +277 -448
  74. package/src/doctor/common/constants.ts +27 -19
  75. package/src/doctor/private-values.ts +4 -1
  76. package/src/doctor/runner.ts +5 -12
  77. package/src/doctor/schema.ts +4 -0
  78. package/src/events/common/actor-names.ts +12 -0
  79. package/src/events/common/constants.ts +65 -38
  80. package/src/events/common/index.ts +1 -0
  81. package/src/events/hook.ts +5 -56
  82. package/src/events/text.ts +41 -6
  83. package/src/hooks/command-view.ts +80 -19
  84. package/src/hooks/common/constants.ts +26 -17
  85. package/src/hooks/common/types.ts +13 -24
  86. package/src/hooks/decision.ts +30 -12
  87. package/src/hooks/git-queries.ts +113 -0
  88. package/src/hooks/guard-git.ts +76 -24
  89. package/src/hooks/guard-outside.ts +334 -311
  90. package/src/hooks/guard-runner.ts +206 -0
  91. package/src/hooks/guard-writes.ts +87 -184
  92. package/src/hooks/hook-input.ts +57 -0
  93. package/src/hooks/index.ts +3 -6
  94. package/src/hooks/link-makers.ts +315 -0
  95. package/src/hooks/package-runners.ts +268 -0
  96. package/src/hooks/project-guards.ts +81 -44
  97. package/src/hooks/project-tmp.ts +39 -4
  98. package/src/hooks/runner-scan.ts +257 -0
  99. package/src/hooks/script-runners.ts +400 -0
  100. package/src/hooks/session-digest.ts +27 -117
  101. package/src/hooks/shell-folders.ts +760 -0
  102. package/src/hooks/shell-writes.ts +646 -0
  103. package/src/hooks/shell.ts +1421 -194
  104. package/src/hooks/subagent-card.ts +2 -2
  105. package/src/hooks/write-commands.ts +898 -0
  106. package/src/init/scaffold.ts +2 -3
  107. package/src/local/auto-clean.ts +2 -1
  108. package/src/local/browser-socket.ts +33 -0
  109. package/src/local/clean.ts +37 -6
  110. package/src/local/constants.ts +15 -1
  111. package/src/local/index.ts +1 -0
  112. package/src/local/scan.ts +41 -10
  113. package/src/manifest/render.ts +84 -30
  114. package/src/owner/constants.ts +4 -5
  115. package/src/owner/index.ts +0 -2
  116. package/src/owner/profile.ts +1 -0
  117. package/src/owner/schema.ts +51 -27
  118. package/src/owner/survey.ts +0 -3
  119. package/src/owner/view.ts +0 -9
  120. package/src/router.ts +8 -132
  121. package/src/rules/base.ts +12 -7
  122. package/src/rules/index.ts +1 -0
  123. package/src/rules/packs.ts +44 -0
  124. package/src/runners/check.ts +130 -0
  125. package/src/skills/frontmatter.ts +1 -0
  126. package/src/sync/agents-block.ts +104 -0
  127. package/src/sync/base-rules.ts +3 -3
  128. package/src/sync/claude-launch.ts +12 -12
  129. package/src/sync/common/constants.ts +0 -2
  130. package/src/sync/index.ts +1 -1
  131. package/src/sync/local-choice.ts +32 -3
  132. package/src/sync/planner.ts +2 -15
  133. package/src/sync/settings.ts +0 -17
  134. package/src/theme/index.ts +1 -0
  135. package/src/theme/tokens.ts +410 -0
  136. package/src/ui/prompt.ts +1 -0
  137. package/src/visualize/architecture.ts +504 -0
  138. package/src/visualize/assets.ts +41 -30
  139. package/src/visualize/compare-render.ts +22 -24
  140. package/src/visualize/constants.ts +27 -0
  141. package/src/visualize/diagrams.ts +13 -121
  142. package/src/visualize/kinds-render.ts +2 -2
  143. package/src/visualize/kinds-schema.ts +49 -0
  144. package/src/visualize/labels-vi.ts +25 -0
  145. package/src/visualize/labels.ts +2 -0
  146. package/src/visualize/layout.ts +415 -66
  147. package/src/visualize/page.ts +82 -15
  148. package/src/visualize/render.ts +2 -1
  149. package/src/visualize/schema.ts +29 -1
  150. package/src/visualize/sections.ts +78 -9
  151. package/src/visualize/theme.ts +49 -18
  152. package/src/wiki/anchors.ts +1 -0
  153. package/src/wiki/command.ts +10 -3
  154. package/src/wiki/source-links.ts +57 -18
  155. package/base/ci-global.json +0 -13
  156. package/base/claude/remote-hosts.json +0 -15
  157. package/base/hooks/guard-manifest.ts +0 -27
  158. package/base/hooks/guard-package.ts +0 -30
  159. package/base/hooks/guard-remote-hosts.ts +0 -70
  160. package/base/hooks/guard-scripting.ts +0 -32
  161. package/base/hooks/post-tool.ts +0 -37
  162. package/base/hooks/prompt-submit.ts +0 -54
  163. package/base/hooks/stop.ts +0 -40
  164. package/base/skills/build-a-feature/evals/evals.json +0 -29
  165. package/base/skills/docs-update/evals/evals.json +0 -23
  166. package/base/skills/docs-writing/evals/evals.json +0 -17
  167. package/base/skills/fix-a-bug/evals/evals.json +0 -17
  168. package/base/skills/knowledge-sync/SKILL.md +0 -81
  169. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +0 -291
  170. package/base/skills/knowledge-sync/references/workflow.md +0 -44
  171. package/base/skills/plan-a-change/evals/evals.json +0 -47
  172. package/base/skills/report-back/evals/evals.json +0 -23
  173. package/base/skills/research/evals/evals.json +0 -17
  174. package/base/skills/retro/evals/evals.json +0 -17
  175. package/base/skills/review-a-change/evals/evals.json +0 -17
  176. package/base/skills/ship/evals/evals.json +0 -23
  177. package/base/skills/visualize-work/evals/evals.json +0 -17
  178. package/base/templates/ci/github-actions.yml +0 -75
  179. package/base/templates/ci/gitlab-ci.yml +0 -52
  180. package/base/templates/trusted-hosts.local.example +0 -11
  181. package/src/ci/affected.ts +0 -176
  182. package/src/ci/command.ts +0 -166
  183. package/src/ci/common/constants.ts +0 -76
  184. package/src/ci/common/index.ts +0 -2
  185. package/src/ci/common/types.ts +0 -37
  186. package/src/ci/git.ts +0 -72
  187. package/src/ci/global.ts +0 -48
  188. package/src/ci/graph.ts +0 -43
  189. package/src/ci/index.ts +0 -7
  190. package/src/ci/workspace.ts +0 -119
  191. package/src/commands/ci.command.ts +0 -4
  192. package/src/hooks/guard-manifest.ts +0 -109
  193. package/src/hooks/guard-package.ts +0 -226
  194. package/src/hooks/guard-scripting.ts +0 -36
  195. package/src/hooks/host-pattern.ts +0 -17
  196. package/src/hooks/owner-reply.ts +0 -162
  197. package/src/hooks/post-tool.ts +0 -138
  198. package/src/hooks/remote-hosts.ts +0 -1013
  199. package/src/hooks/trusted-scripts.ts +0 -212
  200. package/src/owner/shape.ts +0 -496
  201. package/src/owner/violations.ts +0 -332
  202. package/src/signals/claims.ts +0 -73
  203. package/src/signals/classify.ts +0 -137
  204. package/src/signals/constants.ts +0 -88
  205. package/src/signals/index.ts +0 -5
  206. package/src/signals/loop.ts +0 -48
  207. package/src/signals/state.ts +0 -271
  208. package/src/sync/atlas-block.ts +0 -56
@@ -2,65 +2,367 @@ import { NodeStates } from './constants.ts';
2
2
  import { IconSet } from './icons.ts';
3
3
  import type { TVisualizeSpec } from './schema.ts';
4
4
 
5
- const CELL_WIDTH = 290;
5
+ type TFlow = NonNullable<TVisualizeSpec['flow']>;
6
+ type TNode = TFlow['nodes'][number];
7
+ type TEdge = TFlow['edges'][number];
6
8
 
7
- const CELL_HEIGHT = 112;
9
+ const MARGIN = 24;
10
+ const MIN_BOX_WIDTH = 176;
11
+ const MAX_BOX_WIDTH = 264;
12
+ const MIN_BOX_HEIGHT = 60;
13
+ const SIDE_PADDING = 24;
14
+ const TOP_PADDING = 26;
15
+ const MIN_COLUMN_GAP = 114;
16
+ const MIN_ROW_GAP = 52;
17
+ const TITLE_SIZE = 15;
18
+ const SUBTITLE_SIZE = 13;
19
+ const EDGE_SIZE = 13;
20
+ const TITLE_LINE = 19;
21
+ const SUBTITLE_LINE = 16;
22
+ const EDGE_LINE = 16;
23
+ const MAX_EDGE_LABEL_WIDTH = 96;
24
+ /** A box does not widen for its second line: a sublabel longer than this wraps. */
25
+ const SUBTITLE_WRAP = 168;
26
+ const LABEL_CLEARANCE = 10;
27
+
28
+ /**
29
+ * The width of a text in pixels, by a per-character estimate that errs wide: the page draws the figure before any
30
+ * script runs, so the boxes and the gaps are sized from the text, never from a measurement.
31
+ */
32
+ const widthOf = (opts: { text: string; size: number; isBold?: boolean }): number =>
33
+ [...opts.text].reduce((sum, char) => {
34
+ const code = char.codePointAt(0) ?? 0;
35
+ const bold = opts.isBold === true;
36
+ // Wide scripts (CJK, Hangul, fullwidth forms) are about one em; a combining mark adds nothing; every Latin
37
+ // letter, Vietnamese with its marks included, is one narrow unit.
38
+ const unit =
39
+ code >= 0x2e80
40
+ ? 1.05
41
+ : code >= 0x300 && code <= 0x36f
42
+ ? 0
43
+ : /[A-Z]/.test(char)
44
+ ? bold
45
+ ? 0.7
46
+ : 0.66
47
+ : bold
48
+ ? 0.58
49
+ : 0.56;
8
50
 
9
- const BOX_WIDTH = 176;
51
+ return sum + unit * opts.size;
52
+ }, 0);
10
53
 
11
- const BOX_HEIGHT = 60;
54
+ /** The lines a text breaks into at `max` pixels: at spaces, and inside a word only when the word alone is wider. */
55
+ const breakLines = (opts: {
56
+ text: string;
57
+ size: number;
58
+ isBold?: boolean;
59
+ max: number;
60
+ }): string[] => {
61
+ const lines: string[] = [];
62
+ let line = '';
12
63
 
13
- const MARGIN = 24;
64
+ for (const word of opts.text.split(/\s+/).filter((item) => item !== '')) {
65
+ const next = line === '' ? word : `${line} ${word}`;
66
+
67
+ if (widthOf({ ...opts, text: next }) <= opts.max) {
68
+ line = next;
69
+ continue;
70
+ }
71
+
72
+ if (line !== '') {
73
+ lines.push(line);
74
+ line = '';
75
+ }
76
+
77
+ let rest = word;
78
+
79
+ while (widthOf({ ...opts, text: rest }) > opts.max && rest.length > 1) {
80
+ let cut = rest.length - 1;
81
+
82
+ while (cut > 1 && widthOf({ ...opts, text: rest.slice(0, cut) }) > opts.max) {
83
+ cut -= 1;
84
+ }
85
+
86
+ // Break at a hyphen, dot, slash, comma or a capital letter after a small one (resolve|Update|Operations)
87
+ // near the middle when the word has one, else wherever it fits.
88
+ const marks = [...rest.slice(0, cut)]
89
+ .map((char, index) =>
90
+ ['-', '.', '/', '_', ','].includes(char) ||
91
+ (/[a-z0-9]/.test(char) && /[A-Z]/.test(rest[index + 1] ?? ''))
92
+ ? index + 1
93
+ : 0,
94
+ )
95
+ .filter((index) => index >= 2 && index < rest.length);
96
+ const soft = marks.sort(
97
+ (first, second) => Math.abs(first - rest.length / 2) - Math.abs(second - rest.length / 2),
98
+ )[0];
99
+
100
+ if (soft !== undefined) {
101
+ cut = soft;
102
+ }
103
+
104
+ lines.push(rest.slice(0, cut));
105
+ rest = rest.slice(cut);
106
+ }
107
+
108
+ line = rest;
109
+ }
110
+
111
+ return line === '' ? lines : [...lines, line];
112
+ };
113
+
114
+ /** The same lines, balanced: no last line of one short word. The width is narrowed while the line count stays. */
115
+ const wrap = (opts: { text: string; size: number; isBold?: boolean; max: number }): string[] => {
116
+ const lines = breakLines(opts);
117
+ let best = lines;
118
+
119
+ // Never narrower than the widest word: balancing moves a break, it does not split a word.
120
+ const widest = Math.max(
121
+ ...opts.text.split(/\s+/).map((word) => widthOf({ ...opts, text: word })),
122
+ );
123
+
124
+ if (lines.length > 1) {
125
+ for (let max = opts.max - 4; max >= widest; max -= 4) {
126
+ const tighter = breakLines({ ...opts, max });
127
+
128
+ if (tighter.length !== lines.length) {
129
+ break;
130
+ }
131
+
132
+ best = tighter;
133
+ }
134
+ }
135
+
136
+ return best;
137
+ };
138
+
139
+ interface IPoint {
140
+ x: number;
141
+ y: number;
142
+ }
143
+
144
+ interface IBox {
145
+ node: TNode;
146
+ width: number;
147
+ height: number;
148
+ titleLines: string[];
149
+ subtitleLines: string[];
150
+ /** Where the text starts inside the box, from its left edge. */
151
+ textLeft: number;
152
+ }
153
+
154
+ interface IPlaced extends IBox {
155
+ centre: IPoint;
156
+ }
157
+
158
+ interface IGeometry {
159
+ width: number;
160
+ height: number;
161
+ boxes: Map<string, IPlaced>;
162
+ columnGaps: number[];
163
+ rowGaps: number[];
164
+ columnLefts: number[];
165
+ columnWidths: number[];
166
+ rowTops: number[];
167
+ rowHeights: number[];
168
+ }
169
+
170
+ interface IRoute {
171
+ path: string;
172
+ /** Where the label goes: `x` is the middle for a horizontal run and the left edge for a vertical one. */
173
+ label: IPoint;
174
+ isVertical: boolean;
175
+ lines: string[];
176
+ }
177
+
178
+ const boxOf = (opts: { node: TNode }): IBox => {
179
+ const { node } = opts;
180
+ const isActor = node.kind === 'actor';
181
+ const textLeft =
182
+ node.state === undefined ? (isActor ? 22 : 14) : node.state === 'waiting' ? 48 : 40;
183
+ const textRight = isActor ? 22 : 14;
184
+ const wanted =
185
+ Math.max(
186
+ widthOf({ text: node.label, size: TITLE_SIZE, isBold: true }),
187
+ node.sublabel === undefined
188
+ ? 0
189
+ : Math.min(widthOf({ text: node.sublabel, size: SUBTITLE_SIZE }), SUBTITLE_WRAP),
190
+ ) +
191
+ textLeft +
192
+ textRight;
193
+ const width = Math.min(Math.max(Math.ceil(wanted), MIN_BOX_WIDTH), MAX_BOX_WIDTH);
194
+ const inner = width - textLeft - textRight;
195
+ const titleLines = wrap({ text: node.label, size: TITLE_SIZE, isBold: true, max: inner });
196
+ const subtitleLines =
197
+ node.sublabel === undefined
198
+ ? []
199
+ : wrap({ text: node.sublabel, size: SUBTITLE_SIZE, max: inner });
200
+ const text =
201
+ titleLines.length * TITLE_LINE +
202
+ (subtitleLines.length === 0 ? 0 : 4 + subtitleLines.length * SUBTITLE_LINE);
203
+
204
+ return {
205
+ node,
206
+ width,
207
+ height: Math.max(MIN_BOX_HEIGHT, 20 + text),
208
+ titleLines,
209
+ subtitleLines,
210
+ textLeft,
211
+ };
212
+ };
213
+
214
+ const edgeLinesOf = (opts: { edge: TEdge }): string[] =>
215
+ wrap({ text: opts.edge.label, size: EDGE_SIZE, max: MAX_EDGE_LABEL_WIDTH });
14
216
 
15
- const centreOf = (opts: { row: number; col: number }): IPoint => ({
16
- x: MARGIN + opts.col * CELL_WIDTH + CELL_WIDTH / 2,
17
- y: MARGIN + opts.row * CELL_HEIGHT + CELL_HEIGHT / 2,
18
- });
217
+ const edgeWidthOf = (opts: { lines: string[] }): number =>
218
+ Math.max(...opts.lines.map((line) => widthOf({ text: line, size: EDGE_SIZE })));
19
219
 
20
220
  /**
21
- * The route of an edge between two box centres: straight when they share a row or a column, else an
22
- * elbow - along the source's row, then along the target's column. The label sits on the longest run.
221
+ * The boxes of a figure on its grid, sized from their text: a column is as wide as its widest box, a row as tall as
222
+ * its tallest, and the gap after a column is as wide as the widest arrow label that sits in it, so a label has the
223
+ * free part of its arrow to itself.
23
224
  */
24
- const routeOf = (opts: { from: IPoint; to: IPoint }): { path: string; label: IPoint } => {
25
- const { from, to } = opts;
225
+ const geometryOf = (opts: { nodes: TNode[]; edges: TEdge[] }): IGeometry => {
226
+ const boxes = opts.nodes.map((node) => boxOf({ node }));
227
+ const columns = Math.max(...opts.nodes.map((node) => node.col)) + 1;
228
+ const rows = Math.max(...opts.nodes.map((node) => node.row)) + 1;
229
+ const columnWidths = Array.from({ length: columns }, (_, column) =>
230
+ Math.max(
231
+ MIN_BOX_WIDTH,
232
+ ...boxes.filter((box) => box.node.col === column).map((box) => box.width),
233
+ ),
234
+ );
235
+ const rowHeights = Array.from({ length: rows }, (_, row) =>
236
+ Math.max(
237
+ MIN_BOX_HEIGHT,
238
+ ...boxes.filter((box) => box.node.row === row).map((box) => box.height),
239
+ ),
240
+ );
241
+ const byId = new Map(opts.nodes.map((node) => [node.id, node]));
242
+ const columnGaps = Array.from({ length: columns }, () => MIN_COLUMN_GAP);
26
243
 
27
- if (from.y === to.y) {
28
- const sign = to.x > from.x ? 1 : -1;
29
- const start = { x: from.x + (sign * BOX_WIDTH) / 2, y: from.y };
30
- const end = { x: to.x - (sign * BOX_WIDTH) / 2, y: to.y };
244
+ for (const edge of opts.edges) {
245
+ const from = byId.get(edge.from);
246
+ const to = byId.get(edge.to);
247
+
248
+ if (from === undefined || to === undefined || from.col === to.col) {
249
+ continue;
250
+ }
251
+
252
+ const gap = to.col > from.col ? from.col : from.col - 1;
253
+ const need = Math.ceil(edgeWidthOf({ lines: edgeLinesOf({ edge }) })) + 2 * LABEL_CLEARANCE;
254
+
255
+ columnGaps[gap] = Math.max(columnGaps[gap] ?? MIN_COLUMN_GAP, need);
256
+ }
257
+
258
+ const rowGaps = Array.from({ length: rows }, () => MIN_ROW_GAP);
259
+ const columnLefts: number[] = [];
260
+ const rowTops: number[] = [];
261
+ let x = MARGIN + SIDE_PADDING;
262
+ let y = MARGIN + TOP_PADDING;
263
+
264
+ for (const [column, width] of columnWidths.entries()) {
265
+ columnLefts.push(x);
266
+ x += width + (columnGaps[column] ?? 0);
267
+ }
268
+
269
+ for (const [row, height] of rowHeights.entries()) {
270
+ rowTops.push(y);
271
+ y += height + (rowGaps[row] ?? 0);
272
+ }
273
+
274
+ const boxesById = new Map<string, IPlaced>();
275
+
276
+ for (const box of boxes) {
277
+ boxesById.set(box.node.id, {
278
+ ...box,
279
+ centre: {
280
+ x: (columnLefts[box.node.col] ?? 0) + (columnWidths[box.node.col] ?? 0) / 2,
281
+ y: (rowTops[box.node.row] ?? 0) + (rowHeights[box.node.row] ?? 0) / 2,
282
+ },
283
+ });
284
+ }
285
+
286
+ return {
287
+ width: Math.ceil(x - (columnGaps[columns - 1] ?? 0) + MARGIN + SIDE_PADDING),
288
+ height: Math.ceil(y - (rowGaps[rows - 1] ?? 0) + MARGIN + TOP_PADDING),
289
+ boxes: boxesById,
290
+ columnGaps,
291
+ rowGaps,
292
+ columnLefts,
293
+ columnWidths,
294
+ rowTops,
295
+ rowHeights,
296
+ };
297
+ };
298
+
299
+ /**
300
+ * The route of an edge between two boxes: straight when they share a row or a column, else an elbow - along the
301
+ * source's row, then along the target's column. The label sits in the free part of the arrow next to the source: in
302
+ * the gap after the source's column for a horizontal run (centred, above the line), in the gap after its row for a
303
+ * vertical one (beside the line).
304
+ */
305
+ const routeOf = (opts: {
306
+ from: IPlaced;
307
+ to: IPlaced;
308
+ edge: TEdge;
309
+ geometry: IGeometry;
310
+ }): IRoute => {
311
+ const { from, to, geometry } = opts;
312
+ const lines = edgeLinesOf({ edge: opts.edge });
313
+ const right = to.centre.x > from.centre.x ? 1 : -1;
314
+ const down = to.centre.y > from.centre.y ? 1 : -1;
315
+ const columnGapMiddle = (): number => {
316
+ const column = right === 1 ? from.node.col : from.node.col - 1;
317
+
318
+ return (
319
+ (geometry.columnLefts[column] ?? 0) +
320
+ (geometry.columnWidths[column] ?? 0) +
321
+ (geometry.columnGaps[column] ?? 0) / 2
322
+ );
323
+ };
324
+ const rowGapMiddle = (): number => {
325
+ const row = down === 1 ? from.node.row : from.node.row - 1;
326
+
327
+ return (
328
+ (geometry.rowTops[row] ?? 0) +
329
+ (geometry.rowHeights[row] ?? 0) +
330
+ (geometry.rowGaps[row] ?? 0) / 2
331
+ );
332
+ };
333
+
334
+ if (from.centre.y === to.centre.y) {
335
+ const start = { x: from.centre.x + (right * from.width) / 2, y: from.centre.y };
336
+ const end = { x: to.centre.x - (right * to.width) / 2, y: to.centre.y };
31
337
 
32
338
  return {
33
339
  path: `M${start.x} ${start.y}L${end.x} ${end.y}`,
34
- label: { x: (start.x + end.x) / 2, y: start.y - 6 },
340
+ label: { x: columnGapMiddle(), y: start.y - 6 },
341
+ isVertical: false,
342
+ lines,
35
343
  };
36
344
  }
37
345
 
38
- if (from.x === to.x) {
39
- const sign = to.y > from.y ? 1 : -1;
40
- const start = { x: from.x, y: from.y + (sign * BOX_HEIGHT) / 2 };
41
- const end = { x: to.x, y: to.y - (sign * BOX_HEIGHT) / 2 };
346
+ if (from.centre.x === to.centre.x) {
347
+ const start = { x: from.centre.x, y: from.centre.y + (down * from.height) / 2 };
348
+ const end = { x: to.centre.x, y: to.centre.y - (down * to.height) / 2 };
42
349
 
43
350
  return {
44
351
  path: `M${start.x} ${start.y}L${end.x} ${end.y}`,
45
- label: { x: start.x + 6, y: (start.y + end.y) / 2 },
352
+ label: { x: start.x + 10, y: rowGapMiddle() },
353
+ isVertical: true,
354
+ lines,
46
355
  };
47
356
  }
48
357
 
49
- const horizontal = to.x > from.x ? 1 : -1;
50
- const vertical = to.y > from.y ? 1 : -1;
51
- const start = { x: from.x + (horizontal * BOX_WIDTH) / 2, y: from.y };
52
- const corner = { x: to.x, y: from.y };
53
- const end = { x: to.x, y: to.y - (vertical * BOX_HEIGHT) / 2 };
54
- const horizontalRun = Math.abs(corner.x - start.x);
55
- const verticalRun = Math.abs(end.y - corner.y);
358
+ const start = { x: from.centre.x + (right * from.width) / 2, y: from.centre.y };
359
+ const corner = { x: to.centre.x, y: from.centre.y };
360
+ const end = { x: to.centre.x, y: to.centre.y - (down * to.height) / 2 };
361
+ const path = `M${start.x} ${start.y}L${corner.x} ${corner.y}L${end.x} ${end.y}`;
56
362
 
57
- return {
58
- path: `M${start.x} ${start.y}L${corner.x} ${corner.y}L${end.x} ${end.y}`,
59
- label:
60
- horizontalRun >= verticalRun
61
- ? { x: (start.x + corner.x) / 2, y: start.y - 6 }
62
- : { x: corner.x + 6, y: (corner.y + end.y) / 2 },
63
- };
363
+ return Math.abs(corner.x - start.x) >= Math.abs(end.y - corner.y)
364
+ ? { path, label: { x: columnGapMiddle(), y: start.y - 6 }, isVertical: false, lines }
365
+ : { path, label: { x: corner.x + 10, y: rowGapMiddle() }, isVertical: true, lines };
64
366
  };
65
367
 
66
368
  export class FigureLayout {
@@ -78,56 +380,108 @@ export class FigureLayout {
78
380
  .replaceAll("'", '&#39;');
79
381
  }
80
382
 
81
- /** The natural width of a figure of `cols` columns, in pixels. */
82
- static figureWidth(opts: { cols: number }): number {
83
- return MARGIN * 2 + opts.cols * CELL_WIDTH;
383
+ /**
384
+ * The class name of a figure by its fit key: the width, then the space beside it that goes when the page is one
385
+ * column (`i`), then the padding of its frame (`p`).
386
+ */
387
+ static fitName(opts: { key: string }): string {
388
+ const [width = '0', inset = '0', frame = '0'] = opts.key.split(':');
389
+
390
+ return `f${width}${Number(inset) === 0 ? '' : `i${inset}`}${Number(frame) === 0 ? '' : `p${frame}`}`;
391
+ }
392
+
393
+ /** The width of a text in pixels, by the same estimate the figure uses for its boxes and its arrow labels. */
394
+ static textWidth(opts: { text: string; size: number; isBold?: boolean }): number {
395
+ return widthOf(opts);
396
+ }
397
+
398
+ /** The lines a text wraps into at `max` pixels, balanced: the same breaking the boxes of a flow use. */
399
+ static wrapText(opts: { text: string; size: number; isBold?: boolean; max: number }): string[] {
400
+ return wrap(opts);
84
401
  }
85
402
 
86
- /** How many columns a flow spans. */
87
- static columnsOf(opts: { flow: NonNullable<TVisualizeSpec['flow']> }): number {
88
- return Math.max(...opts.flow.nodes.map((node) => node.col)) + 1;
403
+ /** The natural width of a figure, in pixels: its columns as wide as their boxes need, and the gaps as wide as their arrow labels need. */
404
+ static widthOf(opts: { nodes: TNode[]; edges: TEdge[] }): number {
405
+ return geometryOf(opts).width;
406
+ }
407
+
408
+ /** The `<text>` of an arrow label: one line, or the lines it wraps into, stacked above the line or beside it. */
409
+ private static edgeText(opts: { route: IRoute }): string {
410
+ const { route } = opts;
411
+ const [first = ''] = route.lines;
412
+ const anchor = route.isVertical ? 'start' : 'middle';
413
+ const top = route.isVertical
414
+ ? route.label.y - ((route.lines.length - 1) * EDGE_LINE) / 2
415
+ : route.label.y - (route.lines.length - 1) * EDGE_LINE;
416
+
417
+ if (route.lines.length === 1) {
418
+ return `<text x="${route.label.x}" y="${top}" text-anchor="${anchor}">${FigureLayout.escaped(first)}</text>`;
419
+ }
420
+
421
+ return `<text x="${route.label.x}" y="${top}" text-anchor="${anchor}">${route.lines
422
+ .map(
423
+ (line, index) =>
424
+ `<tspan x="${route.label.x}"${index === 0 ? '' : ` dy="${EDGE_LINE}"`}>${FigureLayout.escaped(line)}</tspan>`,
425
+ )
426
+ .join('')}</text>`;
89
427
  }
90
428
 
91
429
  /** The figure: boxes on a grid, arrows between them. Every part carries a `data-` id the page script highlights. */
92
- static render(opts: { flow: NonNullable<TVisualizeSpec['flow']> }): string {
430
+ static render(opts: { flow: TFlow }): string {
93
431
  const { flow } = opts;
432
+ const geometry = geometryOf({ nodes: flow.nodes, edges: flow.edges });
433
+ const { width, height } = geometry;
94
434
  const byId = new Map(flow.nodes.map((node) => [node.id, node]));
95
- const width = FigureLayout.figureWidth({ cols: FigureLayout.columnsOf({ flow }) });
96
- const height = MARGIN * 2 + (Math.max(...flow.nodes.map((node) => node.row)) + 1) * CELL_HEIGHT;
97
435
  const edges = flow.edges
98
436
  .map((edge) => {
99
- const from = byId.get(edge.from);
100
- const to = byId.get(edge.to);
437
+ const from = geometry.boxes.get(edge.from);
438
+ const to = geometry.boxes.get(edge.to);
439
+ const source = byId.get(edge.from);
101
440
 
102
- if (from === undefined || to === undefined) {
441
+ if (from === undefined || to === undefined || source === undefined) {
103
442
  return '';
104
443
  }
105
444
 
106
- const route = routeOf({ from: centreOf(from), to: centreOf(to) });
445
+ const route = routeOf({ from, to, edge, geometry });
107
446
  const name = `${edge.from}>${edge.to}`;
108
447
  // What the owner starts is drawn in the hot colour; a failure keeps its own red.
109
- const hot = from.state === 'waiting' && edge.variant !== 'error';
448
+ const hot = source.state === 'waiting' && edge.variant !== 'error';
110
449
  const head = edge.variant === 'error' ? 'e' : hot ? 'h' : 'a';
111
450
 
112
- return `<g class="edge ${FigureLayout.escaped(edge.variant ?? 'main')}${hot ? ' hot' : ''}" data-edge="${FigureLayout.escaped(name)}"><title>${FigureLayout.escaped(edge.label)}</title><path d="${route.path}" marker-end="url(#${head})"/><text x="${route.label.x}" y="${route.label.y}" text-anchor="middle">${FigureLayout.escaped(edge.label)}</text></g>`;
451
+ return `<g class="edge ${FigureLayout.escaped(edge.variant ?? 'main')}${hot ? ' hot' : ''}" data-edge="${FigureLayout.escaped(name)}"><title>${FigureLayout.escaped(edge.label)}</title><path d="${route.path}" marker-end="url(#${head})"/>${FigureLayout.edgeText({ route })}</g>`;
113
452
  })
114
453
  .join('');
115
- const nodes = flow.nodes
116
- .map((node) => {
117
- const centre = centreOf(node);
118
- const lines = node.sublabel === undefined ? 1 : 2;
454
+ const nodes = [...geometry.boxes.values()]
455
+ .map((box) => {
456
+ const { node, centre } = box;
119
457
  const tone = node.state === undefined ? '' : ` c-${NodeStates.toneOf(node.state)}`;
120
458
  const gate = node.state === 'waiting';
121
- const left = centre.x - BOX_WIDTH / 2;
459
+ const left = centre.x - box.width / 2;
460
+ const top = centre.y - box.height / 2;
122
461
  const anchor = node.state === undefined ? 'middle' : 'start';
123
- const textX =
124
- node.state === undefined ? centre.x : left + (node.state === 'waiting' ? 48 : 40);
462
+ const textX = node.state === undefined ? centre.x : left + box.textLeft;
463
+ const textHeight =
464
+ box.titleLines.length * TITLE_LINE +
465
+ (box.subtitleLines.length === 0 ? 0 : 4 + box.subtitleLines.length * SUBTITLE_LINE);
466
+ const first = centre.y - textHeight / 2;
125
467
  const mark =
126
468
  node.state === undefined
127
469
  ? ''
128
470
  : `${gate ? `<circle class="halo" cx="${left + 22}" cy="${centre.y}" r="20"/><circle class="core" cx="${left + 22}" cy="${centre.y}" r="13"/>` : ''}<g class="st" transform="translate(${left + 12} ${centre.y - 10})">${IconSet.iconSvg({ name: NodeStates.iconOf(node.state), size: 20 }).replace('<svg', '<svg x="0" y="0"')}</g>`;
471
+ const titles = box.titleLines
472
+ .map(
473
+ (line, index) =>
474
+ `<text x="${textX}" y="${first + 14 + index * TITLE_LINE}" text-anchor="${anchor}" class="t">${FigureLayout.escaped(line)}</text>`,
475
+ )
476
+ .join('');
477
+ const subtitles = box.subtitleLines
478
+ .map(
479
+ (line, index) =>
480
+ `<text x="${textX}" y="${first + box.titleLines.length * TITLE_LINE + 16 + index * SUBTITLE_LINE}" text-anchor="${anchor}" class="s">${FigureLayout.escaped(line)}</text>`,
481
+ )
482
+ .join('');
129
483
 
130
- return `<g class="node ${FigureLayout.escaped(node.kind ?? 'step')}${tone}${gate ? ' gate' : ''}" tabindex="0" role="img" aria-label="${FigureLayout.escaped(node.label)}${node.sublabel === undefined ? '' : `, ${FigureLayout.escaped(node.sublabel)}`}" data-node="${FigureLayout.escaped(node.id)}" data-detail="${FigureLayout.escaped(node.detail ?? node.sublabel ?? node.label)}"><title>${FigureLayout.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">${FigureLayout.escaped(node.label)}</text>${node.sublabel === undefined ? '' : `<text x="${textX}" y="${centre.y + 17}" text-anchor="${anchor}" class="s">${FigureLayout.escaped(node.sublabel)}</text>`}</g>`;
484
+ return `<g class="node ${FigureLayout.escaped(node.kind ?? 'step')}${tone}${gate ? ' gate' : ''}" tabindex="0" role="img" aria-label="${FigureLayout.escaped(node.label)}${node.sublabel === undefined ? '' : `, ${FigureLayout.escaped(node.sublabel)}`}" data-node="${FigureLayout.escaped(node.id)}" data-detail="${FigureLayout.escaped(node.detail ?? node.sublabel ?? node.label)}"><title>${FigureLayout.escaped(node.label)}</title><rect x="${left}" y="${top}" width="${box.width}" height="${box.height}" rx="4"/>${mark}${titles}${subtitles}</g>`;
131
485
  })
132
486
  .join('');
133
487
 
@@ -138,7 +492,7 @@ export class FigureLayout {
138
492
  * The same flow as a list, for a phone where the figure cannot be read: one row per arrow, then one per box that
139
493
  * has a detail. Page CSS shows it only on a narrow screen.
140
494
  */
141
- static renderPathList(opts: { flow: NonNullable<TVisualizeSpec['flow']> }): string {
495
+ static renderPathList(opts: { flow: TFlow }): string {
142
496
  const { flow } = opts;
143
497
  const byId = new Map(flow.nodes.map((node) => [node.id, node]));
144
498
  const nameOf = (id: string): string => {
@@ -170,8 +524,3 @@ export class FigureLayout {
170
524
 
171
525
  /** Below this share of its natural width the figure is replaced by a list, so no text drops under 12 px. */
172
526
  export const FIGURE_FIT = 0.92;
173
-
174
- interface IPoint {
175
- x: number;
176
- y: number;
177
- }