@venizia/vulcan 0.4.8 → 0.4.9-1

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 (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -1,44 +1,22 @@
1
1
  import { NodeStates } from './constants.ts';
2
- import { iconSvg } from './icons.ts';
2
+ import { IconSet } from './icons.ts';
3
3
  import type { TVisualizeSpec } from './schema.ts';
4
4
 
5
- /** Escapes text for HTML and for an attribute value: everything the spec says is data, never markup. */
6
- export const escapeText = (opts: { value: string }): string =>
7
- opts.value
8
- .replaceAll('&', '&')
9
- .replaceAll('<', '&lt;')
10
- .replaceAll('>', '&gt;')
11
- .replaceAll('"', '&quot;')
12
- .replaceAll("'", '&#39;');
13
-
14
5
  const CELL_WIDTH = 290;
15
- const CELL_HEIGHT = 112;
16
- const BOX_WIDTH = 176;
17
- const BOX_HEIGHT = 60;
18
- const MARGIN = 24;
19
6
 
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;
7
+ const CELL_HEIGHT = 112;
22
8
 
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;
9
+ const BOX_WIDTH = 176;
25
10
 
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;
11
+ const BOX_HEIGHT = 60;
29
12
 
30
- interface IPoint {
31
- x: number;
32
- y: number;
33
- }
13
+ const MARGIN = 24;
34
14
 
35
15
  const centreOf = (opts: { row: number; col: number }): IPoint => ({
36
16
  x: MARGIN + opts.col * CELL_WIDTH + CELL_WIDTH / 2,
37
17
  y: MARGIN + opts.row * CELL_HEIGHT + CELL_HEIGHT / 2,
38
18
  });
39
19
 
40
- const escaped = (value: string): string => escapeText({ value });
41
-
42
20
  /**
43
21
  * The route of an edge between two box centres: straight when they share a row or a column, else an
44
22
  * elbow - along the source's row, then along the target's column. The label sits on the longest run.
@@ -85,73 +63,115 @@ const routeOf = (opts: { from: IPoint; to: IPoint }): { path: string; label: IPo
85
63
  };
86
64
  };
87
65
 
88
- /** The figure: boxes on a grid, arrows between them. Every part carries a `data-` id the page script highlights. */
89
- export const renderFigure = (opts: { flow: NonNullable<TVisualizeSpec['flow']> }): string => {
90
- const { flow } = opts;
91
- const byId = new Map(flow.nodes.map((node) => [node.id, node]));
92
- const width = figureWidth({ cols: columnsOf({ flow }) });
93
- const height = MARGIN * 2 + (Math.max(...flow.nodes.map((node) => node.row)) + 1) * CELL_HEIGHT;
94
- const edges = flow.edges
95
- .map((edge) => {
96
- const from = byId.get(edge.from);
97
- const to = byId.get(edge.to);
98
-
99
- if (from === undefined || to === undefined) {
100
- return '';
101
- }
102
-
103
- const route = routeOf({ from: centreOf(from), to: centreOf(to) });
104
- const name = `${edge.from}>${edge.to}`;
105
-
106
- return `<g class="edge ${escaped(edge.variant ?? 'main')}" data-edge="${escaped(name)}"><title>${escaped(edge.label)}</title><path d="${route.path}" marker-end="url(#${edge.variant === 'error' ? 'e' : 'a'})"/><text x="${route.label.x}" y="${route.label.y}" text-anchor="middle">${escaped(edge.label)}</text></g>`;
107
- })
108
- .join('');
109
- const nodes = flow.nodes
110
- .map((node) => {
111
- const centre = centreOf(node);
112
- const lines = node.sublabel === undefined ? 1 : 2;
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;
66
+ export class FigureLayout {
67
+ private static escaped(value: string): string {
68
+ return FigureLayout.escapeText({ value });
69
+ }
70
+
71
+ /** Escapes text for HTML and for an attribute value: everything the spec says is data, never markup. */
72
+ static escapeText(opts: { value: string }): string {
73
+ return opts.value
74
+ .replaceAll('&', '&amp;')
75
+ .replaceAll('<', '&lt;')
76
+ .replaceAll('>', '&gt;')
77
+ .replaceAll('"', '&quot;')
78
+ .replaceAll("'", '&#39;');
79
+ }
80
+
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;
84
+ }
85
+
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;
89
+ }
90
+
91
+ /** 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 {
93
+ const { flow } = opts;
94
+ 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
+ const edges = flow.edges
98
+ .map((edge) => {
99
+ const from = byId.get(edge.from);
100
+ const to = byId.get(edge.to);
101
+
102
+ if (from === undefined || to === undefined) {
103
+ return '';
104
+ }
105
+
106
+ const route = routeOf({ from: centreOf(from), to: centreOf(to) });
107
+ const name = `${edge.from}>${edge.to}`;
108
+ // 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';
110
+ const head = edge.variant === 'error' ? 'e' : hot ? 'h' : 'a';
111
+
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>`;
113
+ })
114
+ .join('');
115
+ const nodes = flow.nodes
116
+ .map((node) => {
117
+ const centre = centreOf(node);
118
+ const lines = node.sublabel === undefined ? 1 : 2;
119
+ const tone = node.state === undefined ? '' : ` c-${NodeStates.toneOf(node.state)}`;
120
+ const gate = node.state === 'waiting';
121
+ const left = centre.x - BOX_WIDTH / 2;
122
+ const anchor = node.state === undefined ? 'middle' : 'start';
123
+ const textX =
124
+ node.state === undefined ? centre.x : left + (node.state === 'waiting' ? 48 : 40);
125
+ const mark =
126
+ node.state === undefined
127
+ ? ''
128
+ : `${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>`;
129
+
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>`;
131
+ })
132
+ .join('');
133
+
134
+ 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="13" markerHeight="13" markerUnits="userSpaceOnUse" orient="auto"><path class="ah" d="M0 0L10 5L0 10z"/></marker><marker id="e" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="13" markerHeight="13" markerUnits="userSpaceOnUse" orient="auto"><path class="bad" d="M0 0L10 5L0 10z"/></marker><marker id="h" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="15" markerHeight="15" markerUnits="userSpaceOnUse" orient="auto"><path class="hot" d="M0 0L10 5L0 10z"/></marker></defs>${edges}${nodes}</svg>`;
135
+ }
136
+
137
+ /**
138
+ * 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
+ * has a detail. Page CSS shows it only on a narrow screen.
140
+ */
141
+ static renderPathList(opts: { flow: NonNullable<TVisualizeSpec['flow']> }): string {
142
+ const { flow } = opts;
143
+ const byId = new Map(flow.nodes.map((node) => [node.id, node]));
144
+ const nameOf = (id: string): string => {
145
+ const node = byId.get(id);
117
146
  const mark =
118
- node.state === undefined
147
+ node?.state === undefined
119
148
  ? ''
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>`;
149
+ : `<span class="inl c-${NodeStates.toneOf(node.state)}">${IconSet.iconSvg({ name: NodeStates.iconOf(node.state), size: 16 })}</span>`;
121
150
 
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>`;
123
- })
124
- .join('');
151
+ return `${mark}${FigureLayout.escaped(node?.label ?? id)}`;
152
+ };
153
+ const arrows = flow.edges
154
+ .map(
155
+ (edge) =>
156
+ `<li><b>${nameOf(edge.from)}</b><span class="verb ${FigureLayout.escaped(edge.variant ?? 'main')}">${FigureLayout.escaped(edge.label)}</span><b>${nameOf(edge.to)}</b></li>`,
157
+ )
158
+ .join('');
159
+ const details = flow.nodes
160
+ .filter((node) => node.detail !== undefined)
161
+ .map(
162
+ (node) =>
163
+ `<li><b>${FigureLayout.escaped(node.label)}</b> ${FigureLayout.escaped(node.detail ?? '')}</li>`,
164
+ )
165
+ .join('');
166
+
167
+ return `<ol class="path">${arrows}</ol>${details === '' ? '' : `<ul class="path-detail">${details}</ul>`}`;
168
+ }
169
+ }
125
170
 
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>`;
127
- };
171
+ /** Below this share of its natural width the figure is replaced by a list, so no text drops under 12 px. */
172
+ export const FIGURE_FIT = 0.92;
128
173
 
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
- };
174
+ interface IPoint {
175
+ x: number;
176
+ y: number;
177
+ }
@@ -1,68 +1,31 @@
1
1
  import { createHash } from 'node:crypto';
2
- import { PAGE_CSS, PAGE_JS } from './assets.ts';
3
- import { DEFAULT_CHROME, NodeStates } from './constants.ts';
2
+ import { Assets, HEAD_JS, PAGE_JS } from './assets.ts';
3
+ import { NodeStates } from './constants.ts';
4
4
  import type { TChrome } from './constants.ts';
5
- import { iconSvg } from './icons.ts';
6
- import { stateIcon } from './charts.ts';
7
- import { escapeText, FIGURE_FIT } from './layout.ts';
5
+ import { IconSet } from './icons.ts';
6
+ import { SpecCharts } from './charts.ts';
7
+ import { COMPARE_CSS } from './compare-css.ts';
8
+ import { CompareView } from './compare-render.ts';
9
+ import { NEW_KINDS_CSS } from './kinds-css.ts';
10
+ import { KindsRender } from './kinds-render.ts';
11
+ import { GridSpans } from './grid-span.ts';
12
+ import { Labels } from './labels.ts';
13
+ import { FIGURE_FIT, FigureLayout } from './layout.ts';
8
14
  import type { TVisualizeSpec } from './schema.ts';
9
- import {
10
- architectureSection,
11
- beforeAfterSection,
12
- chip,
13
- comparisonSection,
14
- decisionRecordSection,
15
- decisionsSection,
16
- evidenceSection,
17
- explainerSection,
18
- findingsSection,
19
- flowSection,
20
- ideaMapSection,
21
- linksSection,
22
- logSection,
23
- risksSection,
24
- stateWord,
25
- tilesHtml,
26
- timelineSection,
27
- } from './sections.ts';
15
+ import { PageTerms, SourceRefs } from './sources.ts';
16
+ import { ProjectTheme } from './theme.ts';
17
+ import type { IResolvedTheme } from './theme.ts';
18
+ import { SpecSections } from './sections.ts';
28
19
  import type { ISectionContext } from './sections.ts';
29
20
 
30
- const escaped = (value: string): string => escapeText({ value });
31
-
32
- const definedOnly = (opts: {
33
- value: Record<string, string | undefined> | undefined;
34
- }): Record<string, string> =>
35
- Object.fromEntries(
36
- Object.entries(opts.value ?? {}).filter(
37
- (entry): entry is [string, string] => entry[1] !== undefined,
38
- ),
39
- );
40
-
41
- /** The strings of the page: English, with whatever the spec replaces. */
42
- export const chromeOf = (opts: { spec: TVisualizeSpec }): TChrome => {
43
- const given = opts.spec.chrome ?? {};
44
- const merged: Record<string, unknown> = { ...DEFAULT_CHROME };
45
-
46
- for (const [key, value] of Object.entries(given)) {
47
- if (typeof value === 'string') {
48
- merged[key] = value;
49
- }
50
- }
21
+ const escaped = (value: string): string => FigureLayout.escapeText({ value });
51
22
 
52
- return {
53
- ...DEFAULT_CHROME,
54
- ...Object.fromEntries(Object.entries(merged).filter(([, value]) => typeof value === 'string')),
55
- statusStates: { ...DEFAULT_CHROME.statusStates, ...definedOnly({ value: given.statusStates }) },
56
- minimapStates: {
57
- ...DEFAULT_CHROME.minimapStates,
58
- ...definedOnly({ value: given.minimapStates }),
59
- },
60
- evidenceLabels: {
61
- ...DEFAULT_CHROME.evidenceLabels,
62
- ...definedOnly({ value: given.evidenceLabels }),
63
- },
64
- };
65
- };
23
+ /** The mark of the top bar: a diamond in the hot colour. */
24
+ const MARK =
25
+ '<svg class="mark" viewBox="0 0 14 18" aria-hidden="true"><path d="M7 0 14 9 7 18 0 9Z"/></svg>';
26
+
27
+ /** A figure is drawn at most this much larger than its natural width, so a short flow does not turn into a poster. */
28
+ const FIGURE_MAX = 1.25;
66
29
 
67
30
  const sha256 = (opts: { text: string }): string =>
68
31
  `'sha256-${createHash('sha256').update(opts.text).digest('base64')}'`;
@@ -76,16 +39,19 @@ const BANNER_STATE: Record<string, string> = {
76
39
  };
77
40
 
78
41
  /**
79
- * For each figure width, the rule that swaps the figure for its list: below the viewport width at which the figure would
80
- * shrink under FIGURE_FIT of its natural size (text under 12 px). The 66 is the page and frame padding.
42
+ * For each figure width: the size it may take (never under FIGURE_FIT of its natural width, never past a quarter more),
43
+ * and the rule that swaps the figure for its list below the viewport width at which it would shrink under FIGURE_FIT
44
+ * of its natural size (text under 12 px). The 66 is the page and frame padding.
81
45
  */
82
- export const figureFitCss = (opts: { widths: Set<number> }): string =>
46
+ const figureFitCss = (opts: { widths: Set<number> }): string =>
83
47
  [...opts.widths]
84
48
  .sort((a, b) => a - b)
85
49
  .map((width) => {
86
50
  const at = Math.ceil(width * FIGURE_FIT) + 66;
51
+ const least = Math.ceil(width * FIGURE_FIT);
52
+ const most = Math.ceil(width * FIGURE_MAX);
87
53
 
88
- return `@media (max-width:${at}px){.fig.f${width}{display:none}.fig.f${width}~.path,.fig.f${width}~.path-detail{display:block}.fig.f${width}~.bar,.fig.f${width}~#detail,.fig.f${width}~.legend{display:none}}`;
54
+ return `.fig.f${width} svg{min-width:${least}px;max-width:${most}px}\n@media (max-width:${at}px){.fig.f${width}{display:none}.fig.f${width}~.path,.fig.f${width}~.path-detail{display:block}.fig.f${width}~.say,.fig.f${width}~.legend{display:none}.fig.f${width}~.steps .explain{display:block}.fig.f${width}~.steps button{pointer-events:none}}`;
89
55
  })
90
56
  .join('\n');
91
57
 
@@ -100,42 +66,55 @@ const countTiles = (opts: {
100
66
  return [
101
67
  {
102
68
  value: `${count('done')} / ${rows.length}`,
103
- label: stateWord({ chrome: opts.chrome, state: 'done' }),
69
+ label: SpecSections.stateWord({ chrome: opts.chrome, state: 'done' }),
104
70
  state: 'done',
105
71
  },
106
72
  {
107
73
  value: String(count('in progress')),
108
- label: stateWord({ chrome: opts.chrome, state: 'in progress' }),
74
+ label: SpecSections.stateWord({ chrome: opts.chrome, state: 'in progress' }),
109
75
  state: 'in progress',
110
76
  },
111
77
  {
112
78
  value: String(count('waiting')),
113
- label: stateWord({ chrome: opts.chrome, state: 'waiting' }),
79
+ label: SpecSections.stateWord({ chrome: opts.chrome, state: 'waiting' }),
114
80
  state: 'waiting',
115
81
  },
116
82
  {
117
83
  value: String(count('blocked')),
118
- label: stateWord({ chrome: opts.chrome, state: 'blocked' }),
84
+ label: SpecSections.stateWord({ chrome: opts.chrome, state: 'blocked' }),
119
85
  state: 'blocked',
120
86
  },
121
87
  ];
122
88
  };
123
89
 
124
- const bannerHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
90
+ /** The state of the spec as the page says it: a minimap state for the icon, its tone, and the word. */
91
+ const stateOf = (opts: {
92
+ spec: TVisualizeSpec;
93
+ chrome: TChrome;
94
+ }): { state: string; tone: string; word: string } => {
125
95
  const { spec, chrome } = opts;
126
96
  const state = BANNER_STATE[spec.status.state] ?? 'info';
127
97
  const word =
128
98
  spec.status.label ??
129
99
  chrome.statusStates[spec.status.state as keyof TChrome['statusStates']] ??
130
100
  spec.status.state;
101
+
102
+ return { state, tone: NodeStates.toneOf(state), word };
103
+ };
104
+
105
+ /** The always-dark hero: the state, the title, the verdict, the caption, and the flow when the spec has one. */
106
+ const heroHtml = (opts: { ctx: ISectionContext }): string => {
107
+ const { spec, chrome } = opts.ctx;
108
+ const { state, tone, word } = stateOf({ spec, chrome });
131
109
  const meta = [
132
110
  spec.asOf === undefined ? '' : `<span>${escaped(chrome.asOf)}: ${escaped(spec.asOf)}</span>`,
133
111
  spec.scope === undefined ? '' : `<span>${escaped(chrome.scope)}: ${escaped(spec.scope)}</span>`,
134
112
  ].join('');
135
113
 
136
- return `<header class="banner c-${NodeStates.toneOf(state)}" data-slide data-hero><div class="b-ic">${stateIcon({ state, size: 52 })}</div><div class="b-tx"><p class="meta">${meta}</p><p class="word">${escaped(word)}</p><h1>${escaped(spec.title)}</h1><p class="verdict">${escaped(spec.verdict)}</p>${spec.caption === undefined ? '' : `<p class="cap">${escaped(spec.caption)}</p>`}</div></header>`;
114
+ return `<div class="banner slab c-${tone}" data-slide data-hero><div class="wrap hero"><p class="state">${SpecCharts.stateIcon({ state, size: 22 })}<span class="word">${escaped(word)}</span></p><h1>${escaped(spec.title)}</h1><p class="lede">${escaped(spec.verdict)}</p>${spec.caption === undefined ? '' : `<p class="cap">${escaped(spec.caption)}</p>`}${meta === '' ? '' : `<p class="meta">${meta}</p>`}${SpecSections.flow({ ctx: opts.ctx })}</div></div>`;
137
115
  };
138
116
 
117
+ /** The minimap as a track: a stripe, a shape and a word for every task. */
139
118
  const stepperHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
140
119
  const { minimap } = opts.spec;
141
120
 
@@ -145,12 +124,12 @@ const stepperHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string =>
145
124
 
146
125
  const { chrome } = opts;
147
126
 
148
- return `<section class="sec" id="minimap" data-slide><h2 class="lab">${escaped(chrome.minimap)}</h2><ol class="strip">${minimap
127
+ return `<section class="part" id="minimap" data-slide><div class="wrap"><h2 class="sh">${escaped(chrome.minimap)}</h2><ol class="strip">${minimap
149
128
  .map(
150
129
  (row) =>
151
- `<li class="seg c-${NodeStates.toneOf(row.status)}"><span class="bar"></span><span class="nm">${chip({ chrome, state: row.status })}<span class="tn">${escaped(row.task)}</span></span>${row.note === undefined ? '' : `<span class="nt">${escaped(row.note)}</span>`}</li>`,
130
+ `<li class="seg c-${NodeStates.toneOf(row.status)}"><span class="bar"></span><span class="nm">${SpecSections.chip({ chrome, state: row.status })}<span class="tn">${escaped(row.task)}</span></span>${row.note === undefined ? '' : `<span class="nt">${escaped(row.note)}</span>`}</li>`,
152
131
  )
153
- .join('')}</ol></section>`;
132
+ .join('')}</ol></div></section>`;
154
133
  };
155
134
 
156
135
  /** What the owner has to do and what blocks it: the first thing after the verdict. */
@@ -170,48 +149,95 @@ const ownerHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
170
149
  ? ''
171
150
  : `<ol class="check">${spec.actions.map((action) => `<li>${escaped(action)}</li>`).join('')}</ol>`;
172
151
 
173
- return `<section class="two" data-slide><div class="card action"><p class="lab">${escaped(chrome.next)}</p><h2>${escaped(spec.strip.next)}</h2>${actions}${jump}</div><div class="card blocked"><p class="lab">${escaped(chrome.blockedBy)}</p><p class="bb">${iconSvg({ name: 'waiting', size: 20 })}<span>${escaped(spec.strip.blockedBy)}</span></p><p class="ok-line">${iconSvg({ name: 'done', size: 16 })}<span><b>${escaped(chrome.healthy)}</b> ${escaped(spec.strip.healthy)}</span></p><p class="ok-line">${iconSvg({ name: 'info', size: 16 })}<span><b>${escaped(chrome.changed)}</b> ${escaped(spec.strip.changed)}</span></p></div></section>`;
152
+ return `<section class="two" id="next" data-slide><div class="wrap"><div class="own"><div class="nx"><p class="lab">${escaped(chrome.next)}</p><h2>${escaped(spec.strip.next)}</h2>${actions}${jump}</div><div class="stop"><p class="lab">${escaped(chrome.blockedBy)}</p><p>${escaped(spec.strip.blockedBy)}</p></div></div><div class="facts"><p class="fact">${IconSet.iconSvg({ name: 'done', size: 18 })}<span><b>${escaped(chrome.healthy)}</b> ${escaped(spec.strip.healthy)}</span></p><p class="fact">${IconSet.iconSvg({ name: 'info', size: 18 })}<span><b>${escaped(chrome.changed)}</b> ${escaped(spec.strip.changed)}</span></p></div></div></section>`;
174
153
  };
175
154
 
176
- /** The whole page: one file, no network, a content-security policy that allows only the page's own style and script by hash. */
177
- export const renderPage = (opts: { spec: TVisualizeSpec }): string => {
178
- const { spec } = opts;
179
- const chrome = chromeOf({ spec });
180
- const ctx: ISectionContext = { spec, chrome, fits: new Set<number>() };
181
- const state = BANNER_STATE[spec.status.state] ?? 'info';
182
- const word =
183
- spec.status.label ??
184
- chrome.statusStates[spec.status.state as keyof TChrome['statusStates']] ??
185
- spec.status.state;
186
- const tiles =
187
- spec.tiles ?? (spec.minimap === undefined ? undefined : countTiles({ spec, chrome }));
188
- const body = [
189
- bannerHtml({ spec, chrome }),
190
- tiles === undefined
191
- ? ''
192
- : `<div data-slide class="slide-tiles">${tilesHtml({ tiles, chrome })}</div>`,
193
- stepperHtml({ spec, chrome }),
194
- ownerHtml({ spec, chrome }),
195
- flowSection({ ctx }),
196
- architectureSection({ ctx }),
197
- comparisonSection({ ctx }),
198
- ideaMapSection({ ctx }),
199
- explainerSection({ ctx }),
200
- timelineSection({ ctx }),
201
- findingsSection({ ctx }),
202
- beforeAfterSection({ ctx }),
203
- decisionRecordSection({ ctx }),
204
- decisionsSection({ ctx }),
205
- evidenceSection({ ctx }),
206
- risksSection({ ctx }),
207
- logSection({ ctx }),
208
- linksSection({ ctx }),
209
- ].join('');
210
- const css = `${PAGE_CSS}\n${figureFitCss({ widths: ctx.fits })}`;
211
- const policy = `default-src 'none'; style-src ${sha256({ text: css })}; script-src ${sha256({ text: PAGE_JS })}; base-uri 'none'; form-action 'none'`;
212
- const mini = `<div class="mini c-${NodeStates.toneOf(state)}" role="banner">${chip({ chrome, state, size: 18, label: word })}<b>${escaped(spec.title)}</b></div>`;
213
- const tools = `<div class="tools"><button id="present" type="button" data-on="${escaped(chrome.present)}" data-off="${escaped(chrome.exitPresent)}">${escaped(chrome.present)}</button><button id="theme" type="button">${escaped(chrome.theme)}</button></div>`;
214
- const deck = `<nav class="deck" aria-label="${escaped(chrome.slide)}"><button id="slide-prev" type="button">${escaped(chrome.previous)}</button><span id="slide-count" aria-live="polite"></span><button id="slide-next" type="button">${escaped(chrome.following)}</button></nav>`;
155
+ /** The neutral theme of a page that is given none. */
156
+ const NEUTRAL = ((): IResolvedTheme => {
157
+ const resolved = ProjectTheme.resolve({});
215
158
 
216
- return `<!doctype html><html lang="${escaped(spec.language)}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="${escaped(policy)}"><meta name="generator" content="vulcan visualize"><title>${escaped(spec.title)}</title><style>${css}</style></head><body>${mini}<main class="wrap">${tools}${body}<footer>${escaped(chrome.footer)}</footer></main>${deck}<script>${PAGE_JS}</script></body></html>`;
217
- };
159
+ if (!resolved.ok) {
160
+ throw new Error(
161
+ `the neutral theme does not pass its own checks: ${resolved.problems.join('; ')}`,
162
+ );
163
+ }
164
+
165
+ return resolved.theme;
166
+ })();
167
+
168
+ export class PageShell {
169
+ /** The whole page: one file, no network, a content-security policy that allows only the page's own style and scripts by hash. */
170
+ static render(opts: {
171
+ spec: TVisualizeSpec;
172
+ /** The page's language: the spec's, else the owner's profile, else English. */
173
+ language?: string;
174
+ /** The checked colours of the page; the stylesheet takes its tokens from them. */
175
+ theme?: IResolvedTheme;
176
+ }): string {
177
+ const { spec } = opts;
178
+ const language = opts.language ?? spec.language ?? 'en';
179
+ const chrome = Labels.chromeOf({ spec, language });
180
+ const ctx: ISectionContext = {
181
+ spec,
182
+ chrome,
183
+ fits: new Set<number>(),
184
+ spans: new Set<number>(),
185
+ };
186
+ const { state, tone, word } = stateOf({ spec, chrome });
187
+ const sources = SourceRefs.entries({ spec, chrome });
188
+ const tiles =
189
+ spec.tiles ?? (spec.minimap === undefined ? undefined : countTiles({ spec, chrome }));
190
+ const body = [
191
+ heroHtml({ ctx }),
192
+ tiles === undefined
193
+ ? ''
194
+ : `<div data-slide class="slide-tiles"><div class="wrap">${SpecSections.tilesHtml({ tiles, chrome })}</div></div>`,
195
+ stepperHtml({ spec, chrome }),
196
+ ownerHtml({ spec, chrome }),
197
+ SpecSections.architecture({ ctx }),
198
+ CompareView.section({ ctx }),
199
+ KindsRender.sequenceSection({ ctx }),
200
+ KindsRender.lifecycleSection({ ctx }),
201
+ KindsRender.treeSection({ ctx }),
202
+ SpecSections.comparison({ ctx }),
203
+ SpecSections.ideaMap({ ctx }),
204
+ SpecSections.explainer({ ctx }),
205
+ SpecSections.timeline({ ctx }),
206
+ SpecSections.findings({ ctx }),
207
+ SpecSections.beforeAfter({ ctx }),
208
+ SpecSections.decisionRecord({ ctx }),
209
+ SpecSections.decisions({ ctx }),
210
+ SpecSections.evidence({ ctx }),
211
+ SpecSections.risks({ ctx }),
212
+ SpecSections.log({ ctx }),
213
+ spec.terms === undefined
214
+ ? ''
215
+ : SpecSections.section({
216
+ id: 'terms',
217
+ title: chrome.terms,
218
+ body: PageTerms.listHtml({ terms: spec.terms }),
219
+ }),
220
+ sources.length === 0
221
+ ? ''
222
+ : SpecSections.section({
223
+ id: 'sources',
224
+ title: chrome.sources,
225
+ body: SourceRefs.listHtml({ entries: sources }),
226
+ }),
227
+ SpecSections.links({ ctx }),
228
+ ].join('');
229
+ const css = `${Assets.pageCss({ tokens: ProjectTheme.tokensCss({ theme: opts.theme ?? NEUTRAL }) })}\n${NEW_KINDS_CSS}\n${COMPARE_CSS}\n${GridSpans.css({ spans: ctx.spans })}\n${figureFitCss({ widths: ctx.fits })}`;
230
+ const policy = `default-src 'none'; style-src ${sha256({ text: css })}; script-src ${sha256({ text: HEAD_JS })} ${sha256({ text: PAGE_JS })}; base-uri 'none'; form-action 'none'`;
231
+ const links = SpecSections.sectionLinks({ spec, chrome })
232
+ .map((link) => `<a href="#${link.id}">${escaped(link.title)}</a>`)
233
+ .join('');
234
+ const stamp =
235
+ spec.asOf === undefined
236
+ ? ''
237
+ : `<span class="sep" aria-hidden="true"></span><span class="stamp">${escaped(spec.asOf)}</span>`;
238
+ const bar = `<header class="top slab c-${tone}"><div class="wrap">${MARK}<b class="ttl">${escaped(spec.title)}</b>${SpecSections.chip({ chrome, state, size: 18, label: word })}<nav aria-label="${escaped(chrome.navLabel)}"><span class="links">${links}</span>${stamp}<span class="sep" aria-hidden="true"></span><button class="btn js-only" id="present" type="button" data-on="${escaped(chrome.present)}" data-off="${escaped(chrome.exitPresent)}">${escaped(chrome.present)}</button><button class="theme" id="theme" type="button" aria-label="${escaped(chrome.themeToDark)}" data-to-light="${escaped(chrome.themeToLight)}" data-to-dark="${escaped(chrome.themeToDark)}">${IconSet.iconSvg({ name: 'sun', size: 20, className: 'sun' })}${IconSet.iconSvg({ name: 'moon', size: 20, className: 'moon' })}<span class="tip" aria-hidden="true"></span></button></nav></div></header>`;
239
+ const deck = `<nav class="deck" aria-label="${escaped(chrome.slide)}"><button class="btn" id="slide-prev" type="button">${escaped(chrome.previous)}</button><span id="slide-count" aria-live="polite"></span><button class="btn" id="slide-next" type="button">${escaped(chrome.following)}</button></nav>`;
240
+
241
+ return `<!doctype html><html lang="${escaped(language)}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><meta http-equiv="Content-Security-Policy" content="${escaped(policy)}"><meta name="generator" content="vulcan visualize"><title>${escaped(spec.title)}</title><script>${HEAD_JS}</script><style>${css}</style></head><body>${bar}<main>${body}</main><footer class="slab foot"><div class="wrap"><p>${escaped(chrome.footer)}</p></div></footer>${deck}<script>${PAGE_JS}</script></body></html>`;
242
+ }
243
+ }