@venizia/vulcan 0.4.8 → 0.4.9-0

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 (126) hide show
  1. package/base/hooks/antigravity-guards.ts +2 -1
  2. package/base/hooks/codex-guards.ts +2 -1
  3. package/base/hooks/guard-manifest.ts +2 -1
  4. package/base/hooks/guard-package.ts +2 -1
  5. package/base/hooks/guard-remote-hosts.ts +9 -3
  6. package/base/hooks/guard-scripting.ts +2 -1
  7. package/base/hooks/guard-writes.ts +14 -4
  8. package/base/hooks/post-tool.ts +2 -1
  9. package/base/hooks/prompt-submit.ts +2 -1
  10. package/base/hooks/session-start.ts +3 -1
  11. package/base/hooks/stop.ts +2 -1
  12. package/base/make/vulcan.mk +1 -4
  13. package/base/skills/build-a-feature/SKILL.md +1 -1
  14. package/base/skills/docs-update/SKILL.md +11 -5
  15. package/base/skills/docs-update/evals/evals.json +1 -1
  16. package/base/skills/docs-writing/SKILL.md +1 -1
  17. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  18. package/base/skills/ship/SKILL.md +1 -1
  19. package/base/skills/visualize-work/SKILL.md +20 -6
  20. package/base/skills/visualize-work/references/spec.md +16 -5
  21. package/package.json +5 -6
  22. package/src/agents/codex-hooks.ts +11 -10
  23. package/src/agents/common/types.ts +1 -1
  24. package/src/agents/exclude.ts +1 -1
  25. package/src/agents/hooks-json.ts +4 -8
  26. package/src/agents/prompt.ts +2 -2
  27. package/src/agents/render.ts +8 -12
  28. package/src/cli.ts +3 -1
  29. package/src/commands/doctor.command.ts +3 -1
  30. package/src/commands/help.command.ts +11 -9
  31. package/src/commands/init.command.ts +3 -1
  32. package/src/commands/profile.command.ts +1 -1
  33. package/src/commands/upgrade.command.ts +5 -3
  34. package/src/commands/visualize.command.ts +23 -2
  35. package/src/common/index.ts +2 -0
  36. package/src/common/layout-folder.ts +2 -20
  37. package/src/common/record.ts +7 -0
  38. package/src/common/text.ts +7 -0
  39. package/src/config/common/constants.ts +13 -1
  40. package/src/config/common/types.ts +8 -1
  41. package/src/config/loader.ts +4 -2
  42. package/src/config/packages.ts +4 -1
  43. package/src/config/schema.ts +51 -4
  44. package/src/create/add-app.ts +170 -69
  45. package/src/create/add-lib.ts +41 -31
  46. package/src/create/common/constants.ts +1 -0
  47. package/src/create/common/failure.ts +10 -0
  48. package/src/create/common/index.ts +2 -0
  49. package/src/create/common/preset-path.ts +11 -0
  50. package/src/create/common/types.ts +7 -2
  51. package/src/create/init-monorepo.ts +5 -2
  52. package/src/create/lib-preset.ts +22 -17
  53. package/src/create/names.ts +1 -1
  54. package/src/create/next.ts +1 -1
  55. package/src/create/preset-diff.ts +232 -55
  56. package/src/create/preset-menu.ts +3 -3
  57. package/src/create/preset.ts +18 -10
  58. package/src/create/process.ts +4 -2
  59. package/src/create/scratch.ts +3 -1
  60. package/src/create/workspace.ts +37 -20
  61. package/src/doctor/checks.ts +74 -16
  62. package/src/doctor/runner.ts +2 -0
  63. package/src/doctor/tags.ts +2 -4
  64. package/src/hooks/codex-patch.ts +2 -2
  65. package/src/hooks/common/constants.ts +0 -3
  66. package/src/hooks/common/types.ts +15 -1
  67. package/src/hooks/decision.ts +1 -5
  68. package/src/hooks/guard-git.ts +1 -1
  69. package/src/hooks/guard-outside.ts +28 -9
  70. package/src/hooks/guard-package.ts +13 -7
  71. package/src/hooks/guard-scripting.ts +1 -1
  72. package/src/hooks/guard-writes.ts +73 -20
  73. package/src/hooks/owner-reply.ts +1 -1
  74. package/src/hooks/project-guards.ts +39 -4
  75. package/src/hooks/remote-hosts.ts +5 -20
  76. package/src/hooks/session-digest.ts +7 -0
  77. package/src/hooks/shell.ts +13 -4
  78. package/src/hooks/trusted-scripts.ts +80 -4
  79. package/src/init/common/types.ts +1 -1
  80. package/src/init/scaffold.ts +2 -2
  81. package/src/local/clean.ts +1 -1
  82. package/src/local/scan.ts +2 -2
  83. package/src/manifest/render.ts +20 -11
  84. package/src/owner/profile.ts +1 -3
  85. package/src/owner/shape.ts +1 -1
  86. package/src/owner/survey.ts +27 -18
  87. package/src/router.ts +4 -1
  88. package/src/rules/common/types.ts +1 -1
  89. package/src/signals/state.ts +1 -4
  90. package/src/sync/agent-removal.ts +7 -10
  91. package/src/sync/claude-launch.ts +36 -1
  92. package/src/sync/common/constants.ts +4 -0
  93. package/src/sync/common/index.ts +1 -0
  94. package/src/sync/common/symlink.ts +9 -0
  95. package/src/sync/common/types.ts +2 -2
  96. package/src/sync/planner.ts +10 -12
  97. package/src/sync/settings.ts +1 -1
  98. package/src/ui/keyboard.ts +3 -1
  99. package/src/ui/prompt.ts +4 -2
  100. package/src/visualize/assets.ts +370 -195
  101. package/src/visualize/charts.ts +11 -2
  102. package/src/visualize/compare-css.ts +30 -0
  103. package/src/visualize/compare-render.ts +194 -0
  104. package/src/visualize/compare-schema.ts +81 -0
  105. package/src/visualize/compare-validate.ts +126 -0
  106. package/src/visualize/constants.ts +29 -3
  107. package/src/visualize/diagrams.ts +1 -1
  108. package/src/visualize/gate.ts +136 -0
  109. package/src/visualize/icons.ts +5 -2
  110. package/src/visualize/index.ts +2 -0
  111. package/src/visualize/kinds-css.ts +54 -0
  112. package/src/visualize/kinds-render.ts +693 -0
  113. package/src/visualize/kinds-schema.ts +148 -0
  114. package/src/visualize/kinds-validate.ts +184 -0
  115. package/src/visualize/labels-vi.ts +109 -0
  116. package/src/visualize/labels.ts +49 -0
  117. package/src/visualize/layout.ts +10 -5
  118. package/src/visualize/page.ts +99 -61
  119. package/src/visualize/render.ts +48 -7
  120. package/src/visualize/schema.ts +21 -1
  121. package/src/visualize/sections.ts +115 -34
  122. package/src/visualize/sources.ts +270 -0
  123. package/src/visualize/theme.ts +472 -0
  124. package/src/visualize/validate.ts +6 -0
  125. package/src/wiki/anchors.ts +1 -1
  126. package/src/wiki/source-links.ts +3 -5
@@ -1,11 +1,19 @@
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 { HEAD_JS, PAGE_JS, pageCss } from './assets.ts';
3
+ import { NodeStates } from './constants.ts';
4
4
  import type { TChrome } from './constants.ts';
5
5
  import { iconSvg } from './icons.ts';
6
6
  import { stateIcon } 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 { lifecycleSection, sequenceSection, treeSection } from './kinds-render.ts';
11
+ import { chromeOf } from './labels.ts';
7
12
  import { escapeText, FIGURE_FIT } from './layout.ts';
8
13
  import type { TVisualizeSpec } from './schema.ts';
14
+ import { PageTerms, SourceRefs } from './sources.ts';
15
+ import { ProjectTheme } from './theme.ts';
16
+ import type { IResolvedTheme } from './theme.ts';
9
17
  import {
10
18
  architectureSection,
11
19
  beforeAfterSection,
@@ -21,6 +29,8 @@ import {
21
29
  linksSection,
22
30
  logSection,
23
31
  risksSection,
32
+ section,
33
+ sectionLinks,
24
34
  stateWord,
25
35
  tilesHtml,
26
36
  timelineSection,
@@ -29,40 +39,12 @@ import type { ISectionContext } from './sections.ts';
29
39
 
30
40
  const escaped = (value: string): string => escapeText({ value });
31
41
 
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
- }
42
+ /** The mark of the top bar: a diamond in the hot colour. */
43
+ const MARK =
44
+ '<svg class="mark" viewBox="0 0 14 18" aria-hidden="true"><path d="M7 0 14 9 7 18 0 9Z"/></svg>';
51
45
 
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
- };
46
+ /** A figure is drawn at most this much larger than its natural width, so a short flow does not turn into a poster. */
47
+ const FIGURE_MAX = 1.25;
66
48
 
67
49
  const sha256 = (opts: { text: string }): string =>
68
50
  `'sha256-${createHash('sha256').update(opts.text).digest('base64')}'`;
@@ -76,16 +58,19 @@ const BANNER_STATE: Record<string, string> = {
76
58
  };
77
59
 
78
60
  /**
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.
61
+ * For each figure width: the size it may take (never under FIGURE_FIT of its natural width, never past a quarter more),
62
+ * and the rule that swaps the figure for its list below the viewport width at which it would shrink under FIGURE_FIT
63
+ * of its natural size (text under 12 px). The 66 is the page and frame padding.
81
64
  */
82
- export const figureFitCss = (opts: { widths: Set<number> }): string =>
65
+ const figureFitCss = (opts: { widths: Set<number> }): string =>
83
66
  [...opts.widths]
84
67
  .sort((a, b) => a - b)
85
68
  .map((width) => {
86
69
  const at = Math.ceil(width * FIGURE_FIT) + 66;
70
+ const least = Math.ceil(width * FIGURE_FIT);
71
+ const most = Math.ceil(width * FIGURE_MAX);
87
72
 
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}}`;
73
+ 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
74
  })
90
75
  .join('\n');
91
76
 
@@ -121,21 +106,34 @@ const countTiles = (opts: {
121
106
  ];
122
107
  };
123
108
 
124
- const bannerHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
109
+ /** The state of the spec as the page says it: a minimap state for the icon, its tone, and the word. */
110
+ const stateOf = (opts: {
111
+ spec: TVisualizeSpec;
112
+ chrome: TChrome;
113
+ }): { state: string; tone: string; word: string } => {
125
114
  const { spec, chrome } = opts;
126
115
  const state = BANNER_STATE[spec.status.state] ?? 'info';
127
116
  const word =
128
117
  spec.status.label ??
129
118
  chrome.statusStates[spec.status.state as keyof TChrome['statusStates']] ??
130
119
  spec.status.state;
120
+
121
+ return { state, tone: NodeStates.toneOf(state), word };
122
+ };
123
+
124
+ /** The always-dark hero: the state, the title, the verdict, the caption, and the flow when the spec has one. */
125
+ const heroHtml = (opts: { ctx: ISectionContext }): string => {
126
+ const { spec, chrome } = opts.ctx;
127
+ const { state, tone, word } = stateOf({ spec, chrome });
131
128
  const meta = [
132
129
  spec.asOf === undefined ? '' : `<span>${escaped(chrome.asOf)}: ${escaped(spec.asOf)}</span>`,
133
130
  spec.scope === undefined ? '' : `<span>${escaped(chrome.scope)}: ${escaped(spec.scope)}</span>`,
134
131
  ].join('');
135
132
 
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>`;
133
+ return `<div class="banner slab c-${tone}" data-slide data-hero><div class="wrap hero"><p class="state">${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>`}${flowSection({ ctx: opts.ctx })}</div></div>`;
137
134
  };
138
135
 
136
+ /** The minimap as a track: a stripe, a shape and a word for every task. */
139
137
  const stepperHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
140
138
  const { minimap } = opts.spec;
141
139
 
@@ -145,12 +143,12 @@ const stepperHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string =>
145
143
 
146
144
  const { chrome } = opts;
147
145
 
148
- return `<section class="sec" id="minimap" data-slide><h2 class="lab">${escaped(chrome.minimap)}</h2><ol class="strip">${minimap
146
+ return `<section class="part" id="minimap" data-slide><div class="wrap"><h2 class="sh">${escaped(chrome.minimap)}</h2><ol class="strip">${minimap
149
147
  .map(
150
148
  (row) =>
151
149
  `<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>`,
152
150
  )
153
- .join('')}</ol></section>`;
151
+ .join('')}</ol></div></section>`;
154
152
  };
155
153
 
156
154
  /** What the owner has to do and what blocks it: the first thing after the verdict. */
@@ -170,30 +168,50 @@ const ownerHtml = (opts: { spec: TVisualizeSpec; chrome: TChrome }): string => {
170
168
  ? ''
171
169
  : `<ol class="check">${spec.actions.map((action) => `<li>${escaped(action)}</li>`).join('')}</ol>`;
172
170
 
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>`;
171
+ 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">${iconSvg({ name: 'done', size: 18 })}<span><b>${escaped(chrome.healthy)}</b> ${escaped(spec.strip.healthy)}</span></p><p class="fact">${iconSvg({ name: 'info', size: 18 })}<span><b>${escaped(chrome.changed)}</b> ${escaped(spec.strip.changed)}</span></p></div></div></section>`;
174
172
  };
175
173
 
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 => {
174
+ /** The neutral theme of a page that is given none. */
175
+ const NEUTRAL = ((): IResolvedTheme => {
176
+ const resolved = ProjectTheme.resolve({});
177
+
178
+ if (!resolved.ok) {
179
+ throw new Error(
180
+ `the neutral theme does not pass its own checks: ${resolved.problems.join('; ')}`,
181
+ );
182
+ }
183
+
184
+ return resolved.theme;
185
+ })();
186
+
187
+ /** The whole page: one file, no network, a content-security policy that allows only the page's own style and scripts by hash. */
188
+ export const renderPage = (opts: {
189
+ spec: TVisualizeSpec;
190
+ /** The page's language: the spec's, else the owner's profile, else English. */
191
+ language?: string;
192
+ /** The checked colours of the page; the stylesheet takes its tokens from them. */
193
+ theme?: IResolvedTheme;
194
+ }): string => {
178
195
  const { spec } = opts;
179
- const chrome = chromeOf({ spec });
196
+ const language = opts.language ?? spec.language ?? 'en';
197
+ const chrome = chromeOf({ spec, language });
180
198
  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;
199
+ const { state, tone, word } = stateOf({ spec, chrome });
200
+ const sources = SourceRefs.entries({ spec, chrome });
186
201
  const tiles =
187
202
  spec.tiles ?? (spec.minimap === undefined ? undefined : countTiles({ spec, chrome }));
188
203
  const body = [
189
- bannerHtml({ spec, chrome }),
204
+ heroHtml({ ctx }),
190
205
  tiles === undefined
191
206
  ? ''
192
- : `<div data-slide class="slide-tiles">${tilesHtml({ tiles, chrome })}</div>`,
207
+ : `<div data-slide class="slide-tiles"><div class="wrap">${tilesHtml({ tiles, chrome })}</div></div>`,
193
208
  stepperHtml({ spec, chrome }),
194
209
  ownerHtml({ spec, chrome }),
195
- flowSection({ ctx }),
196
210
  architectureSection({ ctx }),
211
+ CompareView.section({ ctx }),
212
+ sequenceSection({ ctx }),
213
+ lifecycleSection({ ctx }),
214
+ treeSection({ ctx }),
197
215
  comparisonSection({ ctx }),
198
216
  ideaMapSection({ ctx }),
199
217
  explainerSection({ ctx }),
@@ -205,13 +223,33 @@ export const renderPage = (opts: { spec: TVisualizeSpec }): string => {
205
223
  evidenceSection({ ctx }),
206
224
  risksSection({ ctx }),
207
225
  logSection({ ctx }),
226
+ spec.terms === undefined
227
+ ? ''
228
+ : section({
229
+ id: 'terms',
230
+ title: chrome.terms,
231
+ body: PageTerms.listHtml({ terms: spec.terms }),
232
+ }),
233
+ sources.length === 0
234
+ ? ''
235
+ : section({
236
+ id: 'sources',
237
+ title: chrome.sources,
238
+ body: SourceRefs.listHtml({ entries: sources }),
239
+ }),
208
240
  linksSection({ ctx }),
209
241
  ].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>`;
242
+ const css = `${pageCss({ tokens: ProjectTheme.tokensCss({ theme: opts.theme ?? NEUTRAL }) })}\n${NEW_KINDS_CSS}\n${COMPARE_CSS}\n${figureFitCss({ widths: ctx.fits })}`;
243
+ 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'`;
244
+ const links = sectionLinks({ spec, chrome })
245
+ .map((link) => `<a href="#${link.id}">${escaped(link.title)}</a>`)
246
+ .join('');
247
+ const stamp =
248
+ spec.asOf === undefined
249
+ ? ''
250
+ : `<span class="sep" aria-hidden="true"></span><span class="stamp">${escaped(spec.asOf)}</span>`;
251
+ const bar = `<header class="top slab c-${tone}"><div class="wrap">${MARK}<b class="ttl">${escaped(spec.title)}</b>${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)}">${iconSvg({ name: 'sun', size: 20, className: 'sun' })}${iconSvg({ name: 'moon', size: 20, className: 'moon' })}<span class="tip" aria-hidden="true"></span></button></nav></div></header>`;
252
+ 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>`;
215
253
 
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>`;
254
+ 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>`;
217
255
  };
@@ -5,11 +5,23 @@ import { z } from 'zod';
5
5
  import { ProjectLayout } from '../common/index.ts';
6
6
  import { localRootOf } from '../local/index.ts';
7
7
  import { VisualizeLimits } from './constants.ts';
8
+ import { PageGate } from './gate.ts';
8
9
  import { renderPage } from './page.ts';
9
10
  import { VISUALIZE_SCHEMA } from './schema.ts';
11
+ import { PageTerms } from './sources.ts';
12
+ import { ProjectTheme } from './theme.ts';
13
+ import type { IThemeInput } from './theme.ts';
10
14
  import { checkSpec } from './validate.ts';
11
15
 
12
- export interface IRendered {
16
+ /** What the page takes from the project it is made in: the owner's language and the project's colour. */
17
+ export interface IRenderContext {
18
+ /** The language a spec without `language` gets: the owner's profile language. */
19
+ language?: string;
20
+ /** The project's `theme` from the manifest. */
21
+ project?: IThemeInput;
22
+ }
23
+
24
+ interface IRendered {
13
25
  html: string;
14
26
  bytes: number;
15
27
  /** What was checked and passed, for the report: nothing is silent. */
@@ -17,7 +29,7 @@ export interface IRendered {
17
29
  warnings: string[];
18
30
  }
19
31
 
20
- export type TRenderResult = { ok: true; page: IRendered } | { ok: false; problems: string[] };
32
+ type TRenderResult = { ok: true; page: IRendered } | { ok: false; problems: string[] };
21
33
 
22
34
  /** The checks the renderer runs on its own; a browser check is the caller's. */
23
35
  const CHECKS = [
@@ -28,7 +40,7 @@ const CHECKS = [
28
40
  ];
29
41
 
30
42
  /** Spec text to a page: parse, validate, cross-check, render, size gate. Nothing is written here. */
31
- export const renderSpecText = (opts: { text: string }): TRenderResult => {
43
+ export const renderSpecText = (opts: { text: string; context?: IRenderContext }): TRenderResult => {
32
44
  let payload: unknown;
33
45
 
34
46
  try {
@@ -59,8 +71,31 @@ export const renderSpecText = (opts: { text: string }): TRenderResult => {
59
71
  return { ok: false, problems };
60
72
  }
61
73
 
62
- const html = renderPage({ spec: parsed.data });
74
+ const { accent, accentDark, accentText } = parsed.data;
75
+ const themed = ProjectTheme.resolve({
76
+ spec:
77
+ accent === undefined
78
+ ? undefined
79
+ : {
80
+ accent,
81
+ ...(accentDark === undefined ? {} : { accentDark }),
82
+ ...(accentText === undefined ? {} : { accentText }),
83
+ },
84
+ project: opts.context?.project,
85
+ });
86
+
87
+ if (!themed.ok) {
88
+ return { ok: false, problems: themed.problems.map((problem) => `colour: ${problem}`) };
89
+ }
90
+
91
+ const language = parsed.data.language ?? opts.context?.language ?? 'en';
92
+ const html = renderPage({ spec: parsed.data, language, theme: themed.theme });
63
93
  const bytes = Buffer.byteLength(html, 'utf8');
94
+ const gate = PageGate.problems({ html });
95
+
96
+ if (gate.length > 0) {
97
+ return { ok: false, problems: gate.map((problem) => `output gate: ${problem}`) };
98
+ }
64
99
 
65
100
  if (bytes > VisualizeLimits.FAIL_BYTES) {
66
101
  return {
@@ -78,14 +113,20 @@ export const renderSpecText = (opts: { text: string }): TRenderResult => {
78
113
  bytes,
79
114
  checks: [
80
115
  ...CHECKS,
116
+ PageGate.CHECK,
117
+ `colour from the ${themed.theme.source === 'spec' ? "spec's accent" : themed.theme.source === 'project' ? "project's theme" : 'neutral default'}: every text, mark and fill pair checked`,
118
+ ...themed.theme.notes,
81
119
  `size ${(bytes / 1024).toFixed(1)} KB, within ${VisualizeLimits.FAIL_BYTES / 1024} KB`,
82
120
  ],
83
- warnings:
84
- bytes > VisualizeLimits.WARN_BYTES
121
+ warnings: [
122
+ ...themed.theme.warnings,
123
+ ...PageTerms.warnings({ html, terms: parsed.data.terms }),
124
+ ...(bytes > VisualizeLimits.WARN_BYTES
85
125
  ? [
86
126
  `the page is ${Math.round(bytes / 1024)} KB, past the ${VisualizeLimits.WARN_BYTES / 1024} KB a page should stay under: consider two pages`,
87
127
  ]
88
- : [],
128
+ : []),
129
+ ],
89
130
  },
90
131
  };
91
132
  };
@@ -11,6 +11,9 @@ import {
11
11
  VisualizeLimits,
12
12
  } from './constants.ts';
13
13
  import type { TChangeKind } from './constants.ts';
14
+ import { COMPARE_SCHEMA } from './compare-schema.ts';
15
+ import { LIFECYCLE_SCHEMA, SEQUENCE_SCHEMA, TREE_SCHEMA } from './kinds-schema.ts';
16
+ import { SOURCE_SCHEMA, TERMS_SCHEMA } from './sources.ts';
14
17
 
15
18
  /** One line of plain text: no markup is interpreted anywhere, it is all escaped. */
16
19
  const text = (max: number) =>
@@ -36,6 +39,7 @@ const HTTPS = z
36
39
  .string()
37
40
  .max(500)
38
41
  .regex(/^https:\/\/[^\s"'<>\p{Cc}]+$/u, 'an https URL');
42
+ const HEX_COLOUR = z.string().regex(/^#[0-9a-fA-F]{6}$/, 'a six-digit hex colour like #3f5266');
39
43
  const rows = <T extends z.ZodType>(item: T) =>
40
44
  z.array(item).min(1).max(VisualizeLimits.MAX_ROWS_PER_TABLE);
41
45
 
@@ -50,6 +54,8 @@ const NODE = z.strictObject({
50
54
  col: GRID,
51
55
  kind: choice({ set: NodeKinds.SCHEME_SET }).optional(),
52
56
  state: STATE.optional(),
57
+ /** Where the box comes from: shown as `repo@commit:path:lines` in its detail. */
58
+ source: SOURCE_SCHEMA.optional(),
53
59
  });
54
60
 
55
61
  const EDGE = z.strictObject({
@@ -69,6 +75,7 @@ const STEP = z.strictObject({
69
75
  .array(z.string().regex(/^[a-z][a-z0-9-]*>[a-z][a-z0-9-]*$/))
70
76
  .max(VisualizeLimits.MAX_EDGES)
71
77
  .default([]),
78
+ source: SOURCE_SCHEMA.optional(),
72
79
  });
73
80
 
74
81
  const SIDE = (changed: TChangeKind) =>
@@ -325,10 +332,17 @@ export const VISUALIZE_SCHEMA = z.strictObject({
325
332
  schemaVersion: z.literal(VisualizeLimits.SCHEMA_VERSION),
326
333
  /** The takeaway, not a topic. */
327
334
  title: text(VisualizeLimits.MAX_TITLE),
335
+ /** The page's language; absent, it is the owner's profile language, else English. */
328
336
  language: z
329
337
  .string()
330
338
  .regex(/^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/)
331
- .default('en'),
339
+ .optional(),
340
+ /** The accent of this page; it wins over the project's `theme`. A six-digit hex colour. */
341
+ accent: HEX_COLOUR.optional(),
342
+ /** The accent on dark grounds; derived from `accent` when absent. */
343
+ accentDark: HEX_COLOUR.optional(),
344
+ /** A darker accent for text, when `accent` is too light to be read as text. */
345
+ accentText: HEX_COLOUR.optional(),
332
346
  status: z.strictObject({
333
347
  state: choice({ set: StatusStates.SCHEME_SET }),
334
348
  label: text(VisualizeLimits.MAX_LABEL).optional(),
@@ -384,6 +398,12 @@ export const VISUALIZE_SCHEMA = z.strictObject({
384
398
  explainer: EXPLAINER.optional(),
385
399
  timeline: TIMELINE.optional(),
386
400
  findings: FINDINGS.optional(),
401
+ sequence: SEQUENCE_SCHEMA.optional(),
402
+ lifecycle: LIFECYCLE_SCHEMA.optional(),
403
+ tree: TREE_SCHEMA.optional(),
404
+ compare: COMPARE_SCHEMA.optional(),
405
+ /** The words of the page a reader may not know; one that never appears in the page is a warning. */
406
+ terms: TERMS_SCHEMA.optional(),
387
407
  decisionRecord: DECISION_RECORD.optional(),
388
408
  beforeAfter: z
389
409
  .strictObject({ before: SIDE(ChangeKinds.REMOVED), after: SIDE(ChangeKinds.ADDED) })