@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
@@ -128,10 +128,19 @@ const lineChart = (opts: { chart: Extract<TChart, { type: 'line' }> }): string =
128
128
 
129
129
  const SLOTS = ['var(--s1)', 'var(--s2)', 'var(--s3)', 'var(--s4)', 'var(--s5)'];
130
130
 
131
+ /** The page colour of a state tone: what waits for the owner is the project's accent, the rest are fixed. */
132
+ const TONE_COLOURS: Record<string, string> = {
133
+ ok: 'var(--ok)',
134
+ warn: 'var(--accent)',
135
+ bad: 'var(--bad)',
136
+ info: 'var(--info)',
137
+ mut: 'var(--muted)',
138
+ };
139
+
131
140
  const donutColour = (opts: { index: number; state?: string }): string =>
132
141
  opts.state === undefined
133
142
  ? (SLOTS[opts.index] ?? 'var(--s5)')
134
- : `var(--${NodeStates.toneOf(opts.state)})`;
143
+ : (TONE_COLOURS[NodeStates.toneOf(opts.state)] ?? 'var(--muted)');
135
144
 
136
145
  const donutChart = (opts: { chart: Extract<TChart, { type: 'donut' }> }): string => {
137
146
  const { parts } = opts.chart;
@@ -226,7 +235,7 @@ export const renderTotals = (opts: {
226
235
  const width = Math.max(2, Math.round((total / opts.max) * plot));
227
236
  const isBest = index === opts.best;
228
237
 
229
- return `<g><title>${escaped(name)}: ${total} ${escaped(opts.chrome.outOf)} ${opts.max}</title><text x="0" y="${y + 19}" class="ct${isBest ? ' strong' : ''}">${escaped(shorten({ value: name, max: 18 }))}</text><rect x="120" y="${y + 5}" width="${plot}" height="20" rx="4" class="ctrack"/><path d="${barPath({ x: 120, y: y + 5, width, height: 20 })}" fill="${isBest ? 'var(--acc)' : 'var(--mut)'}" opacity="${isBest ? 1 : 0.6}"/><text x="${120 + width + 6}" y="${y + 20}" class="cv">${total}</text></g>`;
238
+ return `<g><title>${escaped(name)}: ${total} ${escaped(opts.chrome.outOf)} ${opts.max}</title><text x="0" y="${y + 19}" class="ct${isBest ? ' strong' : ''}">${escaped(shorten({ value: name, max: 18 }))}</text><rect x="120" y="${y + 5}" width="${plot}" height="20" rx="4" class="ctrack"/><path d="${barPath({ x: 120, y: y + 5, width, height: 20 })}" fill="${isBest ? 'var(--accent)' : 'var(--muted)'}" opacity="${isBest ? 1 : 0.6}"/><text x="${120 + width + 6}" y="${y + 20}" class="cv">${total}</text></g>`;
230
239
  })
231
240
  .join('')}</svg>`;
232
241
  };
@@ -0,0 +1,30 @@
1
+ /**
2
+ * The look of the compare view, the sources and the terms. Colours come from the page's tokens only. An arrow that only the
3
+ * second version has is heavy and solid, one that only the first has is dotted, a shared one is plain: the line style and a
4
+ * word tell them apart, never the colour. Appended after the page's own stylesheet, so these rules win on equal weight.
5
+ */
6
+ export const COMPARE_CSS = `.edge.added path{stroke:var(--ink);stroke-width:4.5}
7
+ .edge.added text{fill:var(--ink);font-weight:700}
8
+ .edge.removed path{stroke-dasharray:1 7;stroke-linecap:round;stroke-width:3}
9
+ .legend .edge.added path{stroke-width:4.5}
10
+ .legend .edge.removed path{stroke-width:3}
11
+ .cmp-key{margin-top:18px}
12
+ .path.cmp .cg{margin:22px 0 8px;color:var(--ink);font:650 15px/1.3 var(--font)}
13
+ .path.cmp .cg:first-child{margin-top:0}
14
+ .path.cmp .cg.added{padding-left:10px;border-left:4px solid var(--ink)}
15
+ .path.cmp .cg.removed{padding-left:10px;border-left:3px dotted var(--ink)}
16
+ .path.cmp ol{margin:0;padding:0}
17
+ .verb.added{border:2px solid var(--ink);color:var(--ink);font-weight:600}
18
+ .verb.removed{border:2px dotted var(--ink);color:var(--ink)}
19
+ .src{font:500 13px/1.5 var(--code);color:var(--muted);overflow-wrap:anywhere}
20
+ .path-detail .src,.explain .src{display:block;margin-top:4px}
21
+ .srcs{border-top:1px solid var(--line)}
22
+ .srcs li{display:grid;grid-template-columns:minmax(0,4fr) minmax(0,2fr);gap:6px 36px;align-items:baseline;padding:18px 0;border-bottom:1px solid var(--line)}
23
+ .srcs .src{color:var(--ink);font-size:14px}
24
+ .srcs .by{color:var(--body);font-size:15.5px}
25
+ .terms{display:grid;grid-template-columns:repeat(auto-fit,minmax(250px,1fr));gap:2px;margin:0;border-radius:var(--radius);overflow:hidden}
26
+ .terms div{display:grid;gap:10px;align-content:start;padding:26px 26px 30px;background:var(--bg-soft)}
27
+ .terms dt{color:var(--ink);font-size:19px;font-weight:650;letter-spacing:-.02em}
28
+ .terms dd{margin:0;max-width:52ch;color:var(--body);font-size:16px}
29
+ @media (max-width:700px){.srcs li{grid-template-columns:minmax(0,1fr)}.terms div{padding:22px 22px 26px}}
30
+ `;
@@ -0,0 +1,194 @@
1
+ import { EdgeSides } from './compare-schema.ts';
2
+ import type { TCompare } from './compare-schema.ts';
3
+ import type { TChrome } from './constants.ts';
4
+ import type { IDrawing } from './diagrams.ts';
5
+ import { escapeText, figureWidth, renderFigure } from './layout.ts';
6
+ import { figure, section } from './sections.ts';
7
+ import type { ISectionContext } from './sections.ts';
8
+ import { SourceRefs } from './sources.ts';
9
+
10
+ const escaped = (value: string): string => escapeText({ value });
11
+
12
+ /** The two sides of an arrow that is not in both. */
13
+ const ADDED = 'added';
14
+ const REMOVED = 'removed';
15
+
16
+ type TCompareEdge = TCompare['edges'][number];
17
+
18
+ /** The compare view: two versions of one mechanism as one figure, the arrows that differ drawn and worded apart. */
19
+ export class CompareView {
20
+ /** The side an edge belongs to; absent means both. */
21
+ private static sideOf(opts: { edge: TCompareEdge }): string {
22
+ return opts.edge.in ?? EdgeSides.BOTH;
23
+ }
24
+
25
+ /** The class an arrow is drawn with: heavy for what only the second has, dotted for what only the first has. */
26
+ private static variantOf(opts: { edge: TCompareEdge }): string | undefined {
27
+ const side = CompareView.sideOf(opts);
28
+
29
+ return side === EdgeSides.B ? ADDED : side === EdgeSides.A ? REMOVED : undefined;
30
+ }
31
+
32
+ /** The words that tell a changed arrow from a shared one: a sign and who has it alone. Never colour alone. */
33
+ private static wordOf(opts: { compare: TCompare; chrome: TChrome; side: string }): string {
34
+ const { compare, chrome, side } = opts;
35
+
36
+ return side === EdgeSides.B
37
+ ? `+ ${chrome.onlyHere} ${compare.b}`
38
+ : `- ${chrome.onlyHere} ${compare.a}`;
39
+ }
40
+
41
+ /** A short line of an arrow in the figure: the sign and the verb, so the line style is never the only sign. */
42
+ private static signedLabel(opts: { edge: TCompareEdge }): string {
43
+ const variant = CompareView.variantOf(opts);
44
+
45
+ return variant === ADDED
46
+ ? `+ ${opts.edge.label}`
47
+ : variant === REMOVED
48
+ ? `- ${opts.edge.label}`
49
+ : opts.edge.label;
50
+ }
51
+
52
+ /** A line sample of one kind of arrow, drawn by the same rules as the arrows of the figure. */
53
+ private static swatch(opts: { variant: string }): string {
54
+ return `<svg class="lg" viewBox="0 0 44 12" aria-hidden="true"><g class="edge ${opts.variant}"><path d="M0 6H44"/></g></svg>`;
55
+ }
56
+
57
+ /** The figure: the flow's own grid drawing with the added and removed arrows as their own classes. */
58
+ private static svgOf(opts: { compare: TCompare; chrome: TChrome }): string {
59
+ const { compare, chrome } = opts;
60
+ const svg = renderFigure({
61
+ flow: {
62
+ nodes: compare.nodes,
63
+ edges: compare.edges.map((edge) => ({
64
+ from: edge.from,
65
+ to: edge.to,
66
+ label: CompareView.signedLabel({ edge }),
67
+ ...(CompareView.variantOf({ edge }) === undefined
68
+ ? {}
69
+ : { variant: CompareView.variantOf({ edge }) }),
70
+ })),
71
+ steps: [],
72
+ },
73
+ });
74
+ // A function as the replacement: a string would read `$&`, `$'` and `` $` `` in the spec's text as patterns.
75
+ let named = svg.replace(
76
+ 'aria-label="flow"',
77
+ () => `aria-label="${escaped(chrome.compareView)}"`,
78
+ );
79
+
80
+ // A changed arrow says its words when it is hovered or read by a screen reader, with the verb after them.
81
+ for (const edge of compare.edges) {
82
+ const side = CompareView.sideOf({ edge });
83
+
84
+ if (side !== EdgeSides.BOTH) {
85
+ const name = escaped(`${edge.from}>${edge.to}`);
86
+ const word = escaped(`${CompareView.wordOf({ compare, chrome, side })}: ${edge.label}`);
87
+
88
+ named = named.replace(
89
+ `data-edge="${name}"><title>${escaped(CompareView.signedLabel({ edge }))}</title>`,
90
+ () => `data-edge="${name}"><title>${word}</title>`,
91
+ );
92
+ }
93
+ }
94
+
95
+ // The label of an arrow that runs straight down or up sits on the line, and a heavy line would run through it: beside it.
96
+ named = named.replace(
97
+ /(<path d="M(-?[\d.]+) -?[\d.]+L\2 -?[\d.]+"[^>]*\/><text x=")-?[\d.]+(" y="-?[\d.]+" )text-anchor="middle"/g,
98
+ (_match, before: string, x: string, after: string) =>
99
+ `${before}${Number(x) + 10}${after}text-anchor="start"`,
100
+ );
101
+
102
+ // The page script highlights and describes the flow's boxes by these names: the compare view is its own thing.
103
+ return named
104
+ .replaceAll(' data-node="', ' data-cn="')
105
+ .replaceAll(' data-edge="', ' data-ce="')
106
+ .replace(/ data-detail="[^"]*"/g, '');
107
+ }
108
+
109
+ /** What replaces the figure on a phone: the arrows in three groups, then the boxes that have more to say. */
110
+ private static listOf(opts: { compare: TCompare; chrome: TChrome }): string {
111
+ const { compare, chrome } = opts;
112
+ const names = new Map(compare.nodes.map((node) => [node.id, node.label]));
113
+ const nameOf = (id: string): string => escaped(names.get(id) ?? id);
114
+ const groups: { side: string; head: string; cls: string }[] = [
115
+ { side: EdgeSides.BOTH, head: chrome.inBoth, cls: 'same' },
116
+ {
117
+ side: EdgeSides.B,
118
+ head: CompareView.wordOf({ compare, chrome, side: EdgeSides.B }),
119
+ cls: ADDED,
120
+ },
121
+ {
122
+ side: EdgeSides.A,
123
+ head: CompareView.wordOf({ compare, chrome, side: EdgeSides.A }),
124
+ cls: REMOVED,
125
+ },
126
+ ];
127
+ const lists = groups
128
+ .map((group) => {
129
+ const edges = compare.edges.filter((edge) => CompareView.sideOf({ edge }) === group.side);
130
+
131
+ return edges.length === 0
132
+ ? ''
133
+ : `<p class="cg ${group.cls}">${escaped(group.head)}</p><ol>${edges
134
+ .map(
135
+ (edge) =>
136
+ `<li><b>${nameOf(edge.from)}</b><span class="verb ${group.cls}">${escaped(edge.label)}</span><b>${nameOf(edge.to)}</b></li>`,
137
+ )
138
+ .join('')}</ol>`;
139
+ })
140
+ .join('');
141
+ const details = compare.nodes
142
+ .filter((node) => node.sublabel !== undefined || node.source !== undefined)
143
+ .map(
144
+ (node) =>
145
+ `<li><b>${escaped(node.label)}</b>${node.sublabel === undefined ? '' : escaped(node.sublabel)}${node.source === undefined ? '' : SourceRefs.html({ source: node.source })}</li>`,
146
+ )
147
+ .join('');
148
+
149
+ return `<div class="path cmp">${lists}</div>${details === '' ? '' : `<ul class="path-detail">${details}</ul>`}`;
150
+ }
151
+
152
+ /** The drawing, the width it needs, and what stands in for it: a key on wide screens, the grouped list on a phone. */
153
+ static drawing(opts: { compare: TCompare; chrome: TChrome }): IDrawing {
154
+ const { compare, chrome } = opts;
155
+ const key = [
156
+ { variant: 'main', word: chrome.inBoth },
157
+ { variant: ADDED, word: CompareView.wordOf({ compare, chrome, side: EdgeSides.B }) },
158
+ { variant: REMOVED, word: CompareView.wordOf({ compare, chrome, side: EdgeSides.A }) },
159
+ ]
160
+ .map(
161
+ (item) =>
162
+ `<li>${CompareView.swatch({ variant: item.variant })}<span>${escaped(item.word)}</span></li>`,
163
+ )
164
+ .join('');
165
+
166
+ return {
167
+ svg: CompareView.svgOf(opts),
168
+ width: figureWidth({ cols: Math.max(...compare.nodes.map((node) => node.col)) + 1 }),
169
+ fallback: `<ul class="legend cmp-key">${key}</ul>${CompareView.listOf(opts)}`,
170
+ };
171
+ }
172
+
173
+ /** The `compare` part of the page, after the flow and the architecture. */
174
+ static section(opts: { ctx: ISectionContext }): string {
175
+ const { compare } = opts.ctx.spec;
176
+ const { chrome } = opts.ctx;
177
+
178
+ if (compare === undefined) {
179
+ return '';
180
+ }
181
+
182
+ const count = (side: string): number =>
183
+ compare.edges.filter((edge) => CompareView.sideOf({ edge }) === side).length;
184
+ const caption =
185
+ compare.caption ??
186
+ `${CompareView.wordOf({ compare, chrome, side: EdgeSides.B })} (${count(EdgeSides.B)}), ${CompareView.wordOf({ compare, chrome, side: EdgeSides.A })} (${count(EdgeSides.A)})`;
187
+
188
+ return section({
189
+ id: 'compare',
190
+ title: chrome.compareView,
191
+ body: `<figure class="kfig">${figure({ ctx: opts.ctx, drawing: CompareView.drawing({ compare, chrome }) })}<figcaption>${escaped(caption)}</figcaption></figure>`,
192
+ });
193
+ }
194
+ }
@@ -0,0 +1,81 @@
1
+ import { z } from 'zod';
2
+ import { NodeKinds, NodeStates, VisualizeLimits } from './constants.ts';
3
+ import { SOURCE_SCHEMA } from './sources.ts';
4
+
5
+ /** Which of the two versions an edge belongs to: both, only the first (a), or only the second (b). */
6
+ export class EdgeSides {
7
+ static readonly BOTH = 'both';
8
+ static readonly A = 'a';
9
+ static readonly B = 'b';
10
+ static readonly SCHEME_SET = new Set<string>([this.BOTH, this.A, this.B]);
11
+
12
+ static isValid(value: string): boolean {
13
+ return this.SCHEME_SET.has(value);
14
+ }
15
+ }
16
+
17
+ /** The limits of the compare view; the shared ones come from `VisualizeLimits`. */
18
+ export class CompareLimits {
19
+ /** The name of a side is read in a sentence with `only here`, so it is short. */
20
+ static readonly MAX_SIDE = 24;
21
+ }
22
+
23
+ /** One line of plain text: no markup is interpreted anywhere, it is all escaped. */
24
+ const text = (max: number) =>
25
+ z
26
+ .string()
27
+ .max(max)
28
+ .regex(/^(?=.*\S)[^\p{Cc}‪-‮⁦-⁩]+$/u, 'one line of text, not blank');
29
+ /** A closed set as a pattern, so the printed JSON Schema says the same as the renderer. */
30
+ const choice = (opts: { set: Set<string> }) =>
31
+ z
32
+ .string()
33
+ .regex(new RegExp(`^(${[...opts.set].join('|')})$`), `one of: ${[...opts.set].join(', ')}`);
34
+ const ID = z
35
+ .string()
36
+ .regex(/^[a-z][a-z0-9-]{0,31}$/, 'lowercase letters, digits and -, at most 32');
37
+ const GRID = z
38
+ .number()
39
+ .int()
40
+ .min(0)
41
+ .max(VisualizeLimits.MAX_GRID - 1);
42
+
43
+ /** Two versions of one mechanism as one figure: the boxes they share, and the arrows each has or lacks. */
44
+ export const COMPARE_SCHEMA = z.strictObject({
45
+ /** The name of the first version. */
46
+ a: text(CompareLimits.MAX_SIDE),
47
+ /** The name of the second version. */
48
+ b: text(CompareLimits.MAX_SIDE),
49
+ nodes: z
50
+ .array(
51
+ z.strictObject({
52
+ id: ID,
53
+ label: text(VisualizeLimits.MAX_LABEL),
54
+ sublabel: text(VisualizeLimits.MAX_LABEL).optional(),
55
+ row: GRID,
56
+ col: GRID,
57
+ kind: choice({ set: NodeKinds.SCHEME_SET }).optional(),
58
+ state: choice({ set: NodeStates.SCHEME_SET }).optional(),
59
+ source: SOURCE_SCHEMA.optional(),
60
+ }),
61
+ )
62
+ .min(2)
63
+ .max(VisualizeLimits.MAX_NODES),
64
+ edges: z
65
+ .array(
66
+ z.strictObject({
67
+ from: ID,
68
+ to: ID,
69
+ /** Every arrow says what it does: a verb. */
70
+ label: text(VisualizeLimits.MAX_EDGE_LABEL),
71
+ /** Absent, the arrow is in both versions. */
72
+ in: choice({ set: EdgeSides.SCHEME_SET }).optional(),
73
+ }),
74
+ )
75
+ .min(1)
76
+ .max(VisualizeLimits.MAX_EDGES),
77
+ /** The sentence under the figure; absent, the page counts the changed arrows itself. */
78
+ caption: text(VisualizeLimits.MAX_SENTENCE).optional(),
79
+ });
80
+
81
+ export type TCompare = z.output<typeof COMPARE_SCHEMA>;
@@ -0,0 +1,126 @@
1
+ import { EdgeSides } from './compare-schema.ts';
2
+ import type { TCompare } from './compare-schema.ts';
3
+
4
+ /** The part of a page spec the compare view lives in. */
5
+ export interface ICompareSpec {
6
+ compare?: TCompare | undefined;
7
+ }
8
+
9
+ interface ICell {
10
+ row: number;
11
+ col: number;
12
+ }
13
+
14
+ /** What a schema cannot say about the compare view: ids, ends of arrows, the grid, and that something differs. */
15
+ export class CompareChecks {
16
+ /** The boxes an arrow would cross: along the source's row to the target's column, then along that column. */
17
+ private static blockersOf(opts: {
18
+ from: ICell;
19
+ to: ICell;
20
+ cells: Map<string, string>;
21
+ }): string[] {
22
+ const { from, to, cells } = opts;
23
+ const crossed: ICell[] = [];
24
+ const between = (start: number, end: number): number[] => {
25
+ const sign = end > start ? 1 : -1;
26
+ const found: number[] = [];
27
+
28
+ for (let at = start + sign; start !== end && at !== end; at += sign) {
29
+ found.push(at);
30
+ }
31
+
32
+ return found;
33
+ };
34
+
35
+ for (const col of between(from.col, to.col)) {
36
+ crossed.push({ row: from.row, col });
37
+ }
38
+
39
+ if (from.row !== to.row && from.col !== to.col) {
40
+ crossed.push({ row: from.row, col: to.col });
41
+ }
42
+
43
+ for (const row of between(from.row, to.row)) {
44
+ crossed.push({ row, col: to.col });
45
+ }
46
+
47
+ return crossed.flatMap((cell) => cells.get(`${cell.row},${cell.col}`) ?? []);
48
+ }
49
+
50
+ static check(opts: { spec: ICompareSpec }): string[] {
51
+ const { compare } = opts.spec;
52
+
53
+ if (compare === undefined) {
54
+ return [];
55
+ }
56
+
57
+ const problems: string[] = [];
58
+ const ids = new Set<string>();
59
+ const cells = new Map<string, string>();
60
+ const positions = new Map<string, ICell>();
61
+
62
+ for (const node of compare.nodes) {
63
+ if (ids.has(node.id)) {
64
+ problems.push(`compare.nodes: id '${node.id}' is used twice`);
65
+ }
66
+
67
+ ids.add(node.id);
68
+
69
+ const owner = cells.get(`${node.row},${node.col}`);
70
+
71
+ if (owner !== undefined) {
72
+ problems.push(
73
+ `compare.nodes: '${node.id}' and '${owner}' are both in row ${node.row}, col ${node.col}`,
74
+ );
75
+ }
76
+
77
+ cells.set(`${node.row},${node.col}`, node.id);
78
+ positions.set(node.id, { row: node.row, col: node.col });
79
+ }
80
+
81
+ const names = new Set<string>();
82
+
83
+ for (const edge of compare.edges) {
84
+ const name = `${edge.from}>${edge.to}`;
85
+
86
+ for (const end of [edge.from, edge.to]) {
87
+ if (!ids.has(end)) {
88
+ problems.push(`compare.edges: '${name}' names '${end}', which is not a node`);
89
+ }
90
+ }
91
+
92
+ if (edge.from === edge.to) {
93
+ problems.push(`compare.edges: '${name}' loops to itself`);
94
+ }
95
+
96
+ if (names.has(name)) {
97
+ problems.push(`compare.edges: '${name}' is drawn twice`);
98
+ }
99
+
100
+ if (names.has(`${edge.to}>${edge.from}`)) {
101
+ problems.push(
102
+ `compare.edges: '${name}' and '${edge.to}>${edge.from}' run on the same line - draw one arrow, or put the boxes in another place`,
103
+ );
104
+ }
105
+
106
+ names.add(name);
107
+
108
+ const from = positions.get(edge.from);
109
+ const to = positions.get(edge.to);
110
+
111
+ if (from !== undefined && to !== undefined && edge.from !== edge.to) {
112
+ for (const blocker of CompareChecks.blockersOf({ from, to, cells })) {
113
+ problems.push(
114
+ `compare.edges: '${name}' would be drawn through box '${blocker}' - move a box`,
115
+ );
116
+ }
117
+ }
118
+ }
119
+
120
+ if (!compare.edges.some((edge) => (edge.in ?? EdgeSides.BOTH) !== EdgeSides.BOTH)) {
121
+ problems.push("compare: no edge differs between 'a' and 'b'");
122
+ }
123
+
124
+ return problems;
125
+ }
126
+ }
@@ -156,9 +156,9 @@ export class VisualizeLimits {
156
156
  static readonly MAX_SERIES = 3;
157
157
  static readonly MAX_PARTS = 5;
158
158
  static readonly MAX_LIST = 6;
159
- /** Typical pages are 20-40 KB; a page past `FAIL_BYTES` is refused: two pages, not one dense one. */
160
- static readonly WARN_BYTES = 60 * 1024;
161
- static readonly FAIL_BYTES = 100 * 1024;
159
+ /** Typical pages are 30-60 KB; a page past `FAIL_BYTES` is refused: two pages, not one dense one. */
160
+ static readonly WARN_BYTES = 80 * 1024;
161
+ static readonly FAIL_BYTES = 150 * 1024;
162
162
  static readonly OUTPUT_DIRECTORY = 'prototypes';
163
163
  }
164
164
 
@@ -243,5 +243,31 @@ export const DEFAULT_CHROME = {
243
243
  tableView: 'Table view',
244
244
  value: 'Value',
245
245
  uses: 'Uses',
246
+ /** The theme switch says what a click does. */
247
+ themeToLight: 'Switch to the light theme',
248
+ themeToDark: 'Switch to the dark theme',
249
+ /** The label of the in-page links in the top bar. */
250
+ navLabel: 'On this page',
251
+ sequence: 'Sequence',
252
+ lifecycle: 'Lifecycle',
253
+ tree: 'Structure',
254
+ compareView: 'What differs',
255
+ inBoth: 'in both',
256
+ sources: 'Sources',
257
+ terms: 'Words in this page',
258
+ /** The words that tell an added arrow from a removed one: never colour alone. */
259
+ onlyHere: 'only here',
260
+ addedEdge: 'added',
261
+ removedEdge: 'removed',
262
+ /** The words of the sequence, lifecycle and tree figures: a message kind, a state kind, and the counts in their captions. */
263
+ kindCall: 'call',
264
+ kindReply: 'reply',
265
+ kindAsync: 'async',
266
+ stateStart: 'start',
267
+ stateEnd: 'end',
268
+ countMessages: 'messages',
269
+ countStates: 'states',
270
+ countTransitions: 'transitions',
271
+ countItems: 'items',
246
272
  };
247
273
  export type TChrome = typeof DEFAULT_CHROME;
@@ -220,5 +220,5 @@ export const renderIdeaMap = (opts: { map: NonNullable<TVisualizeSpec['ideaMap']
220
220
  const left = map.branches.filter((_, index) => index % 2 === 0);
221
221
  const right = map.branches.filter((_, index) => index % 2 === 1);
222
222
 
223
- return `<div class="idea"><ul class="side l">${left.map((branch, i) => cluster(branch, i * 2)).join('')}</ul><div class="centre">${iconSvg({ name: 'star', size: 22 })}<b>${escaped(map.center)}</b></div><ul class="side r">${right.map((branch, i) => cluster(branch, i * 2 + 1)).join('')}</ul></div>`;
223
+ return `<div class="idea"><ul class="side l">${left.map((branch, i) => cluster(branch, i * 2)).join('')}</ul><div class="centre win">${iconSvg({ name: 'star', size: 22 })}<b>${escaped(map.center)}</b></div><ul class="side r">${right.map((branch, i) => cluster(branch, i * 2 + 1)).join('')}</ul></div>`;
224
224
  };
@@ -0,0 +1,136 @@
1
+ /**
2
+ * The last check of a page, on the markup that is about to be written: whatever the renderer did, the page makes no
3
+ * request, has no inline style or handler, and holds exactly the style and the scripts its policy names. The renderer
4
+ * escapes every text, so a spec cannot add markup; this gate says so about the output instead of trusting that.
5
+ */
6
+ export class PageGate {
7
+ /** Tags a page of this kind never has: each one loads something or sends something. */
8
+ static readonly FORBIDDEN_TAGS = new Set([
9
+ 'link',
10
+ 'img',
11
+ 'iframe',
12
+ 'object',
13
+ 'embed',
14
+ 'base',
15
+ 'form',
16
+ 'frame',
17
+ 'frameset',
18
+ 'audio',
19
+ 'video',
20
+ 'source',
21
+ 'track',
22
+ 'picture',
23
+ 'input',
24
+ 'use',
25
+ 'image',
26
+ 'foreignobject',
27
+ ]);
28
+
29
+ /** Attributes that load or run something. */
30
+ static readonly FORBIDDEN_ATTRIBUTES = new Set([
31
+ 'style',
32
+ 'src',
33
+ 'srcset',
34
+ 'formaction',
35
+ 'action',
36
+ 'ping',
37
+ 'poster',
38
+ 'background',
39
+ 'xlink:href',
40
+ ]);
41
+
42
+ /** Presentation attributes that take a `url(...)` and fetch it: they may name a place in the page and nothing else. */
43
+ static readonly LOADING_ATTRIBUTES = new Set([
44
+ 'mask',
45
+ 'fill',
46
+ 'stroke',
47
+ 'filter',
48
+ 'clip-path',
49
+ 'marker-start',
50
+ 'marker-mid',
51
+ 'marker-end',
52
+ 'cursor',
53
+ 'content',
54
+ ]);
55
+
56
+ /** The executable scripts of a page: the head script that applies the saved theme, and the page script. */
57
+ static readonly SCRIPTS = 2;
58
+
59
+ static readonly CHECK =
60
+ 'output gate: no request, no inline style or handler, one style and two scripts, links to https only';
61
+
62
+ /** What is wrong with `html`, one sentence each; empty when it is sound. */
63
+ static problems(opts: { html: string }): string[] {
64
+ const { html } = opts;
65
+ const problems: string[] = [];
66
+ const tags = html.matchAll(/<([a-zA-Z][a-zA-Z0-9:-]*)((?:\s+[^\s=>/]+(?:="[^"]*")?)*)\s*\/?>/g);
67
+ let scripts = 0;
68
+ let styles = 0;
69
+
70
+ for (const [, rawName = '', attributes = ''] of tags) {
71
+ const name = rawName.toLowerCase();
72
+
73
+ if (name === 'script') {
74
+ scripts += /\stype="application\/json"/.test(attributes) ? 0 : 1;
75
+ }
76
+
77
+ if (name === 'style') {
78
+ styles += 1;
79
+ }
80
+
81
+ if (PageGate.FORBIDDEN_TAGS.has(name)) {
82
+ problems.push(`the page has a <${name}> tag`);
83
+ }
84
+
85
+ for (const [, attribute = '', value = ''] of attributes.matchAll(
86
+ /\s+([^\s=>/]+)(?:="([^"]*)")?/g,
87
+ )) {
88
+ const key = attribute.toLowerCase();
89
+
90
+ if (PageGate.FORBIDDEN_ATTRIBUTES.has(key) || key.startsWith('on')) {
91
+ problems.push(`a <${name}> tag has the attribute ${key}`);
92
+ }
93
+
94
+ if (key === 'href' && name === 'a') {
95
+ if (!value.startsWith('#') && !value.startsWith('https://')) {
96
+ problems.push(
97
+ `a link goes to '${value.slice(0, 40)}', not an https address or a place on the page`,
98
+ );
99
+ }
100
+
101
+ continue;
102
+ }
103
+
104
+ if (key === 'href') {
105
+ problems.push(`a <${name}> tag has an href`);
106
+ }
107
+
108
+ // A label, a title or a data attribute is text and may say anything; only an attribute that can fetch is held to it.
109
+ if (
110
+ PageGate.LOADING_ATTRIBUTES.has(key) &&
111
+ (/url\((?!#)/i.test(value) || /(?:^|[\s(])(?:https?:)?\/\//i.test(value))
112
+ ) {
113
+ problems.push(`the ${key} of a <${name}> tag holds an address`);
114
+ }
115
+ }
116
+ }
117
+
118
+ if (scripts !== PageGate.SCRIPTS) {
119
+ problems.push(`the page has ${scripts} scripts; its policy names ${PageGate.SCRIPTS}`);
120
+ }
121
+
122
+ if (styles !== 1) {
123
+ problems.push(`the page has ${styles} style blocks; its policy names 1`);
124
+ }
125
+
126
+ for (const block of html.matchAll(/<style>([\s\S]*?)<\/style>/g)) {
127
+ const css = block[1] ?? '';
128
+
129
+ if (/@import|@font-face|url\((?!#)/i.test(css)) {
130
+ problems.push('the style loads something: @import, @font-face or url()');
131
+ }
132
+ }
133
+
134
+ return [...new Set(problems)];
135
+ }
136
+ }
@@ -19,10 +19,13 @@ const PATHS: Record<string, string> = {
19
19
  quote: '<path d="M9 7H5v6h4l-2 4M19 7h-4v6h4l-2 4"/>',
20
20
  star: '<path d="M12 3l2.7 5.8 6.3.7-4.7 4.3 1.3 6.2L12 17l-5.6 3 1.3-6.2L3 9.5l6.3-.7z"/>',
21
21
  check: '<path d="M5 12.5l4.5 4.5L19 7"/>',
22
+ sun: '<circle cx="12" cy="12" r="4.2"/><path d="M12 2.5v2.2M12 19.3v2.2M4.6 4.6l1.6 1.6M17.8 17.8l1.6 1.6M2.5 12h2.2M19.3 12h2.2M4.6 19.4l1.6-1.6M17.8 6.2l1.6-1.6"/>',
23
+ moon: '<path d="M20.2 14.6A8.4 8.4 0 0 1 9.4 3.8 8.4 8.4 0 1 0 20.2 14.6Z"/>',
22
24
  };
23
25
 
24
- export const iconSvg = (opts: { name: string; size?: number }): string => {
26
+ /** An icon; `className` is added after `ic` for a page rule that targets one icon (the theme switch's sun and moon). */
27
+ export const iconSvg = (opts: { name: string; size?: number; className?: string }): string => {
25
28
  const size = opts.size ?? 20;
26
29
 
27
- return `<svg class="ic" viewBox="0 0 24 24" width="${size}" height="${size}" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${PATHS[opts.name] ?? ''}</svg>`;
30
+ return `<svg class="ic${opts.className === undefined ? '' : ` ${opts.className}`}" viewBox="0 0 24 24" width="${size}" height="${size}" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${PATHS[opts.name] ?? ''}</svg>`;
28
31
  };
@@ -2,5 +2,7 @@ export * from './constants.ts';
2
2
  export * from './schema.ts';
3
3
  export * from './validate.ts';
4
4
  export * from './layout.ts';
5
+ export * from './labels.ts';
5
6
  export * from './page.ts';
6
7
  export * from './render.ts';
8
+ export * from './theme.ts';