@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
@@ -3,13 +3,25 @@ import { lstatSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs
3
3
  import { basename, join } from 'node:path';
4
4
  import { z } from 'zod';
5
5
  import { ProjectLayout } from '../common/index.ts';
6
- import { localRootOf } from '../local/index.ts';
6
+ import { LocalScan } from '../local/index.ts';
7
7
  import { VisualizeLimits } from './constants.ts';
8
- import { renderPage } from './page.ts';
8
+ import { PageGate } from './gate.ts';
9
+ import { PageShell } from './page.ts';
9
10
  import { VISUALIZE_SCHEMA } from './schema.ts';
10
- import { checkSpec } from './validate.ts';
11
+ import { PageTerms } from './sources.ts';
12
+ import { ProjectTheme } from './theme.ts';
13
+ import type { IThemeInput } from './theme.ts';
14
+ import { SpecValidation } from './validate.ts';
15
+
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
+ }
11
23
 
12
- export interface IRendered {
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 = [
@@ -27,135 +39,167 @@ const CHECKS = [
27
39
  "no network, no font, no image, a policy that allows only the page's own style and script",
28
40
  ];
29
41
 
30
- /** Spec text to a page: parse, validate, cross-check, render, size gate. Nothing is written here. */
31
- export const renderSpecText = (opts: { text: string }): TRenderResult => {
32
- let payload: unknown;
42
+ export class SpecPage {
43
+ /** Spec text to a page: parse, validate, cross-check, render, size gate. Nothing is written here. */
44
+ static renderText(opts: { text: string; context?: IRenderContext }): TRenderResult {
45
+ let payload: unknown;
33
46
 
34
- try {
35
- payload = JSON.parse(opts.text);
36
- } catch (error) {
37
- return {
38
- ok: false,
39
- problems: [
40
- `the spec is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
41
- ],
42
- };
43
- }
47
+ try {
48
+ payload = JSON.parse(opts.text);
49
+ } catch (error) {
50
+ return {
51
+ ok: false,
52
+ problems: [
53
+ `the spec is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
54
+ ],
55
+ };
56
+ }
44
57
 
45
- const parsed = VISUALIZE_SCHEMA.safeParse(payload);
58
+ const parsed = VISUALIZE_SCHEMA.safeParse(payload);
46
59
 
47
- if (!parsed.success) {
48
- return {
49
- ok: false,
50
- problems: parsed.error.issues.map(
51
- (issue) => `${issue.path.join('.') || 'spec'}: ${issue.message}`,
52
- ),
53
- };
54
- }
60
+ if (!parsed.success) {
61
+ return {
62
+ ok: false,
63
+ problems: parsed.error.issues.map(
64
+ (issue) => `${issue.path.join('.') || 'spec'}: ${issue.message}`,
65
+ ),
66
+ };
67
+ }
55
68
 
56
- const problems = checkSpec({ spec: parsed.data });
69
+ const problems = SpecValidation.check({ spec: parsed.data });
57
70
 
58
- if (problems.length > 0) {
59
- return { ok: false, problems };
60
- }
71
+ if (problems.length > 0) {
72
+ return { ok: false, problems };
73
+ }
61
74
 
62
- const html = renderPage({ spec: parsed.data });
63
- const bytes = Buffer.byteLength(html, 'utf8');
75
+ const { accent, accentDark, accentText } = parsed.data;
76
+ const themed = ProjectTheme.resolve({
77
+ spec:
78
+ accent === undefined
79
+ ? undefined
80
+ : {
81
+ accent,
82
+ ...(accentDark === undefined ? {} : { accentDark }),
83
+ ...(accentText === undefined ? {} : { accentText }),
84
+ },
85
+ project: opts.context?.project,
86
+ });
87
+
88
+ if (!themed.ok) {
89
+ return { ok: false, problems: themed.problems.map((problem) => `colour: ${problem}`) };
90
+ }
64
91
 
65
- if (bytes > VisualizeLimits.FAIL_BYTES) {
66
- return {
67
- ok: false,
68
- problems: [
69
- `the page is ${Math.round(bytes / 1024)} KB; the limit is ${VisualizeLimits.FAIL_BYTES / 1024} KB - a handoff that does not fit is two pages, not one dense page`,
70
- ],
71
- };
72
- }
92
+ const language = parsed.data.language ?? opts.context?.language ?? 'en';
93
+ const html = PageShell.render({ spec: parsed.data, language, theme: themed.theme });
94
+ const bytes = Buffer.byteLength(html, 'utf8');
95
+ const gate = PageGate.problems({ html });
73
96
 
74
- return {
75
- ok: true,
76
- page: {
77
- html,
78
- bytes,
79
- checks: [
80
- ...CHECKS,
81
- `size ${(bytes / 1024).toFixed(1)} KB, within ${VisualizeLimits.FAIL_BYTES / 1024} KB`,
82
- ],
83
- warnings:
84
- bytes > VisualizeLimits.WARN_BYTES
85
- ? [
86
- `the page is ${Math.round(bytes / 1024)} KB, past the ${VisualizeLimits.WARN_BYTES / 1024} KB a page should stay under: consider two pages`,
87
- ]
88
- : [],
89
- },
90
- };
91
- };
92
-
93
- /** The spec's JSON Schema, for an agent that wants to check a spec before it runs the renderer. */
94
- export const specSchemaText = (): string =>
95
- `${JSON.stringify(z.toJSONSchema(VISUALIZE_SCHEMA, { io: 'input' }), null, 2)}\n`;
96
-
97
- /** A page name as a file name: lowercase letters, digits and dashes. */
98
- export const pageNameOf = (opts: { name: string }): string | undefined => {
99
- const base = basename(opts.name).replace(/\.[^.]*$/, '');
100
- const cleaned = base
101
- .toLowerCase()
102
- .replace(/[^a-z0-9-]+/g, '-')
103
- .slice(0, 64)
104
- .replace(/^-+|-+$/g, '');
105
-
106
- return cleaned === '' ? undefined : cleaned;
107
- };
108
-
109
- /**
110
- * Writes the page to `.agents/local/prototypes/<name>.html` of the project: beside its place and moved in
111
- * last, so a failed render never replaces the last good page. Only a trusted `.agents/local/` is used.
112
- */
113
- export const writePage = (opts: {
114
- root: string;
115
- name: string;
116
- html: string;
117
- }): { ok: true; path: string } | { ok: false; error: string } => {
118
- const local = localRootOf({ root: opts.root });
97
+ if (gate.length > 0) {
98
+ return { ok: false, problems: gate.map((problem) => `output gate: ${problem}`) };
99
+ }
100
+
101
+ if (bytes > VisualizeLimits.FAIL_BYTES) {
102
+ return {
103
+ ok: false,
104
+ problems: [
105
+ `the page is ${Math.round(bytes / 1024)} KB; the limit is ${VisualizeLimits.FAIL_BYTES / 1024} KB - a handoff that does not fit is two pages, not one dense page`,
106
+ ],
107
+ };
108
+ }
119
109
 
120
- if (local === undefined) {
121
110
  return {
122
- ok: false,
123
- error: `no .agents/local/ in ${opts.root} (or it is a symlink, or resolves outside the project) - run vulcan sync first`,
111
+ ok: true,
112
+ page: {
113
+ html,
114
+ bytes,
115
+ checks: [
116
+ ...CHECKS,
117
+ PageGate.CHECK,
118
+ `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`,
119
+ ...themed.theme.notes,
120
+ `size ${(bytes / 1024).toFixed(1)} KB, within ${VisualizeLimits.FAIL_BYTES / 1024} KB`,
121
+ ],
122
+ warnings: [
123
+ ...themed.theme.warnings,
124
+ ...PageTerms.warnings({ html, terms: parsed.data.terms }),
125
+ ...(bytes > VisualizeLimits.WARN_BYTES
126
+ ? [
127
+ `the page is ${Math.round(bytes / 1024)} KB, past the ${VisualizeLimits.WARN_BYTES / 1024} KB a page should stay under: consider two pages`,
128
+ ]
129
+ : []),
130
+ ],
131
+ },
124
132
  };
125
133
  }
126
134
 
127
- const directory = join(local, VisualizeLimits.OUTPUT_DIRECTORY);
135
+ /** The spec's JSON Schema, for an agent that wants to check a spec before it runs the renderer. */
136
+ static specSchemaText(): string {
137
+ return `${JSON.stringify(z.toJSONSchema(VISUALIZE_SCHEMA, { io: 'input' }), null, 2)}\n`;
138
+ }
128
139
 
129
- const refusal = (error: string) => ({ ok: false as const, error });
130
- const place = `${ProjectLayout.LOCAL_DIRECTORY}/${VisualizeLimits.OUTPUT_DIRECTORY}`;
140
+ /** A page name as a file name: lowercase letters, digits and dashes. */
141
+ static pageNameOf(opts: { name: string }): string | undefined {
142
+ const base = basename(opts.name).replace(/\.[^.]*$/, '');
143
+ const cleaned = base
144
+ .toLowerCase()
145
+ .replace(/[^a-z0-9-]+/g, '-')
146
+ .slice(0, 64)
147
+ .replace(/^-+|-+$/g, '');
131
148
 
132
- try {
133
- const kind = lstatSync(directory, { throwIfNoEntry: false });
149
+ return cleaned === '' ? undefined : cleaned;
150
+ }
134
151
 
135
- if (kind?.isSymbolicLink()) {
136
- return refusal(`${place} is a symlink - refusing to write through it`);
152
+ /**
153
+ * Writes the page to `.agents/local/prototypes/<name>.html` of the project: beside its place and moved in
154
+ * last, so a failed render never replaces the last good page. Only a trusted `.agents/local/` is used.
155
+ */
156
+ static write(opts: {
157
+ root: string;
158
+ name: string;
159
+ html: string;
160
+ }): { ok: true; path: string } | { ok: false; error: string } {
161
+ const local = LocalScan.localRootOf({ root: opts.root });
162
+
163
+ if (local === undefined) {
164
+ return {
165
+ ok: false,
166
+ error: `no .agents/local/ in ${opts.root} (or it is a symlink, or resolves outside the project) - run vulcan sync first`,
167
+ };
137
168
  }
138
169
 
139
- if (kind === undefined) {
140
- mkdirSync(directory, { recursive: true });
141
- } else if (!kind.isDirectory()) {
142
- return refusal(`${place} is not a folder`);
143
- }
170
+ const directory = join(local, VisualizeLimits.OUTPUT_DIRECTORY);
144
171
 
145
- const path = join(directory, `${opts.name}.html`);
146
- const partial = `${path}.${randomBytes(6).toString('hex')}.partial`;
172
+ const refusal = (error: string) => ({ ok: false as const, error });
173
+ const place = `${ProjectLayout.LOCAL_DIRECTORY}/${VisualizeLimits.OUTPUT_DIRECTORY}`;
147
174
 
148
175
  try {
149
- writeFileSync(partial, opts.html, { flag: 'wx' });
150
- renameSync(partial, path);
151
- } finally {
152
- rmSync(partial, { force: true });
176
+ const kind = lstatSync(directory, { throwIfNoEntry: false });
177
+
178
+ if (kind?.isSymbolicLink()) {
179
+ return refusal(`${place} is a symlink - refusing to write through it`);
180
+ }
181
+
182
+ if (kind === undefined) {
183
+ mkdirSync(directory, { recursive: true });
184
+ } else if (!kind.isDirectory()) {
185
+ return refusal(`${place} is not a folder`);
186
+ }
187
+
188
+ const path = join(directory, `${opts.name}.html`);
189
+ const partial = `${path}.${randomBytes(6).toString('hex')}.partial`;
190
+
191
+ try {
192
+ writeFileSync(partial, opts.html, { flag: 'wx' });
193
+ renameSync(partial, path);
194
+ } finally {
195
+ rmSync(partial, { force: true });
196
+ }
197
+
198
+ return { ok: true, path };
199
+ } catch (error) {
200
+ return refusal(
201
+ `could not write the page: ${error instanceof Error ? error.message : String(error)}`,
202
+ );
153
203
  }
154
-
155
- return { ok: true, path };
156
- } catch (error) {
157
- return refusal(
158
- `could not write the page: ${error instanceof Error ? error.message : String(error)}`,
159
- );
160
204
  }
161
- };
205
+ }
@@ -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) })