visualproof 0.4.4 → 0.5.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 (48) hide show
  1. package/README.md +16 -7
  2. package/dist/assets/tips/tour-agent.webp +0 -0
  3. package/dist/assets/tips/tour-arrange.webp +0 -0
  4. package/dist/assets/tips/tour-artwork.webp +0 -0
  5. package/dist/assets/tips/tour-checks.webp +0 -0
  6. package/dist/assets/tips/tour-keys.webp +0 -0
  7. package/dist/assets/tips/tour-library.webp +0 -0
  8. package/dist/assets/tips/tour-project.webp +0 -0
  9. package/dist/assets/tips/tour-review.webp +0 -0
  10. package/dist/assets/tips/tour-share.webp +0 -0
  11. package/dist/assets/tips/tour-source.webp +0 -0
  12. package/dist/assets/tips/tour-target.webp +0 -0
  13. package/dist/assets/tips/tour-view.webp +0 -0
  14. package/dist/assets/tips/tour.json +117 -112
  15. package/dist/assets/tips/tour.webp +0 -0
  16. package/dist/server/access.js +3 -1
  17. package/dist/server/accesspage.js +130 -0
  18. package/dist/server/agent.js +6 -1
  19. package/dist/server/buildwatch.js +133 -0
  20. package/dist/server/deploy.js +844 -0
  21. package/dist/server/doctor.js +15 -3
  22. package/dist/server/film.js +1 -1
  23. package/dist/server/historyapi.js +100 -50
  24. package/dist/server/historythread.js +206 -0
  25. package/dist/server/hover.js +8 -0
  26. package/dist/server/live.js +187 -36
  27. package/dist/server/main.js +256 -30
  28. package/dist/server/review.js +27 -7
  29. package/dist/server/status.js +119 -46
  30. package/dist/server/usage.js +51 -0
  31. package/dist/shared/board.js +2 -1
  32. package/dist/shared/deploy.js +35 -0
  33. package/dist/shared/layout.js +297 -70
  34. package/dist/shared/libm.js +366 -0
  35. package/dist/shared/palette.js +1 -1
  36. package/dist/shared/separate.js +556 -32
  37. package/dist/web/bundle/app.js +1972 -826
  38. package/dist/web/bundle/edges.js +2 -1
  39. package/dist/web/bundle/layout.js +1026 -80
  40. package/dist/web/src/canvas.js +47 -34
  41. package/dist/web/src/overview.js +4 -1
  42. package/dist/web/src/scene.js +13 -12
  43. package/dist/web/src/status.js +28 -0
  44. package/dist/web/src/theme.js +108 -0
  45. package/dist/web/style.css +102 -35
  46. package/docs/agent-api/history.md +3 -0
  47. package/docs/agent-api/requests.md +4 -3
  48. package/package.json +1 -1
@@ -10,17 +10,18 @@
10
10
  // folds the reader's selected visitor opens are the reader's alone.
11
11
  import { SITE_BODY, SITE_STMT } from "../../shared/graph.js";
12
12
  import { rgba } from "./gl/gl.js";
13
- import { FLAG_DASHED, FLAG_GLOW, FLAG_HALO, FLAG_RADIAL, FLAG_SHADED, Renderer, UNIT_DOT, UNIT_WORLD, bundle, bundlePath, circle, segment } from "./gl/renderer.js";
13
+ import { BUNDLE_STRIDE, FLAG_DASHED, FLAG_GLOW, FLAG_HALO, FLAG_RADIAL, FLAG_SHADED, Renderer, UNIT_DOT, UNIT_WORLD, bundle, bundlePath, circle, segment } from "./gl/renderer.js";
14
14
  import { joinChains, pathOf } from "./bundles.js";
15
15
  import { EdgeQueue } from "./edgequeue.js";
16
- import { DIM, aim, blendPoints, ease, weightGap, zoomPoint } from "./overview.js";
16
+ import { DIM, OVERVIEW_CROWD, aim, blendPoints, ease, weightGap, zoomPoint } from "./overview.js";
17
17
  import { MODE_SITES } from "../../shared/viewgraph.js";
18
18
  import { escapeHtml } from "./highlight.js";
19
19
  import { ART_DISPLAY, ART_SANS, ART_SERIF, spacedWidth, writeNames } from "./halo.js";
20
20
  import { artNameId } from "../../shared/collab.js";
21
21
  import { dragKeyHeld, dragMoves, menuClick } from "./drag.js";
22
22
  import { Motion } from "./motion.js";
23
- import { ST_APPROVED, ST_BUILDING, ST_COMMENTED, ST_FAILED, ST_SORRY, ST_TRUSTED, ST_UNREVIEWED, STATUSES } from "./status.js";
23
+ import { onThemeChange, reducedMotion } from "./theme.js";
24
+ import { clusterTroubles, ST_APPROVED, ST_COMMENTED, ST_TRUSTED, ST_UNREVIEWED, STATUSES } from "./status.js";
24
25
  import { LEAF_R, Scene } from "./scene.js";
25
26
  import { AXIOM_AT, AXIOM_OUT, AXIOM_W, kindDot, LIT, outside, pickRadius, ringed } from "./axiomring.js";
26
27
  import { markWords, PAST_CHANGED, PAST_GHOST, PAST_RENAMED } from "./past.js";
@@ -86,6 +87,7 @@ export function themeOf(v) {
86
87
  pin: rgba(v("--label")),
87
88
  edgeFrom: rgba(v("--edge-from")),
88
89
  edgeTo: rgba(v("--edge-to")),
90
+ edgeCrowd: Math.max(0, parseFloat(v("--edge-crowd")) || 0),
89
91
  kind,
90
92
  ext: rgba(v("--k-external")),
91
93
  lit: rgba(v("--accent")),
@@ -109,6 +111,14 @@ function sameTarget(a, b) {
109
111
  return a.c === b.c;
110
112
  return a.k === b.k;
111
113
  }
114
+ /** How much fainter each of `n` edges drawn at once is, beyond what every theme does, where more than
115
+ * `from` are: (from / n)^crowd, the theme's `crowd` (Theme.edgeCrowd; 1 for a crowd of 0). Edges
116
+ * that cross add up towards the colour of their mix, at full opacity once enough of them do: on the
117
+ * light ground a dense bundle reads as ink, on the dark one as light — the orange and the blue of
118
+ * hundreds of edges a pink-white haze. The dark theme has them step back as they grow many. */
119
+ export function crowdFade(n, from, crowd) {
120
+ return crowd > 0 && n > from ? (from / n) ** crowd : 1;
121
+ }
112
122
  /** A colour at `k` of its opacity. */
113
123
  const fade = (c, k) => [c[0], c[1], c[2], c[3] * k];
114
124
  /** How many lit declarations the board gives a card at zoom `k`: a card's name is what an artwork
@@ -120,22 +130,6 @@ const CARD_CAP = 180;
120
130
  /** position ids kept past the scene's for the visitors and their temporary clusters, whose edges are
121
131
  * bundled through them (web/src/visits.ts, visitChain) */
122
132
  const VISIT_SLOTS = 256;
123
- /** A file cluster's own build trouble, as a Status code (failed, building, sorry), or -1: what its
124
- * outline shows in the Status scheme. Trouble inherited from below (blocked, out of date because
125
- * something under it changed) is left out, so that one failure does not ring every file above it. */
126
- function troubleOf(f) {
127
- switch (f?.state) {
128
- case "failed":
129
- case "unbuilt":
130
- return ST_FAILED;
131
- case "building":
132
- return ST_BUILDING;
133
- case "sorry":
134
- return ST_SORRY;
135
- default:
136
- return -1;
137
- }
138
- }
139
133
  /** A late zoom point is caught up at up to this many times the zoom's own pace: the drawn blend moves
140
134
  * by at most CATCH_UP · |Δz| of weight in a frame where the camera zoomed by Δz zoom points. */
141
135
  const CATCH_UP = 2;
@@ -204,7 +198,8 @@ export class GraphCanvas {
204
198
  sceneDirty = true;
205
199
  anim = null;
206
200
  repSeen = -1;
207
- /** each file cluster's own build trouble (troubleOf), for its outline in the Status scheme */
201
+ /** each cluster's own build trouble (status.ts, clusterTroubles), -1 for none: its outline in the
202
+ * Status scheme */
208
203
  clusterTrouble = new Int8Array(0);
209
204
  files = new Map();
210
205
  /** how the layout on show clusters: a file's own build trouble outlines its cluster only when
@@ -303,6 +298,8 @@ export class GraphCanvas {
303
298
  overviewStyled = "";
304
299
  overviewStyle = 0;
305
300
  overviewDrawn = "";
301
+ /** counts the themes the board has been drawn in (setTheme): the overview's drawing is of one */
302
+ themeSerial = 0;
306
303
  /** the reader's visitors (setVisitors), and those of them selected (ringed as a selected point is) */
307
304
  visitors = [];
308
305
  visitorSel = [];
@@ -343,11 +340,9 @@ export class GraphCanvas {
343
340
  return;
344
341
  }
345
342
  this.theme = readTheme();
346
- // light or dark changed (the reader's choice, or the system's): the colours are read again
347
- new MutationObserver(() => {
348
- this.theme = readTheme();
349
- this.invalidate();
350
- }).observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme"] });
343
+ // light or dark changed (the reader's choice, the system's, an artwork's look): the colours are
344
+ // read again
345
+ onThemeChange(() => this.setTheme(readTheme()));
351
346
  new ResizeObserver(() => this.resize()).observe(this.canvas);
352
347
  this.resize();
353
348
  this.bindInput();
@@ -377,6 +372,13 @@ export class GraphCanvas {
377
372
  request() {
378
373
  this.dirty = true;
379
374
  }
375
+ /** The board's colours are `th` now (the theme on show changed): everything is drawn again in them,
376
+ * the overview's edges too, whose drawing is otherwise kept while what it shows is the same. */
377
+ setTheme(th) {
378
+ this.theme = th;
379
+ this.themeSerial++;
380
+ this.invalidate();
381
+ }
380
382
  /** Without a browser (ExportSpec decision 21): draw until nothing more comes — the scene at rest,
381
383
  * the overview's points chosen and blended, nothing asking for another frame — at most `most`
382
384
  * frames; whether it came to rest. */
@@ -610,12 +612,9 @@ export class GraphCanvas {
610
612
  recomputeStates() {
611
613
  if (!this.layout)
612
614
  return;
613
- this.clusterTrouble = new Int8Array(this.layout.clusters.length);
614
- // in the file layout a cluster is a module (or a directory of them); under namespaces a
615
- // cluster's key is a namespace, which can read like a module's name without being its file
616
- if (this.clustering !== "module")
617
- return;
618
- this.layout.clusters.forEach((c, k) => (this.clusterTrouble[k] = troubleOf(this.files.get(c.key))));
615
+ // in the file layout a cluster is a module (or a directory of them); under namespaces none has
616
+ // an outline of its own
617
+ this.clusterTrouble = clusterTroubles(this.layout.clusters, this.clustering, this.files);
619
618
  }
620
619
  setLayout(layout, places, foldedKeys, clustering) {
621
620
  this.layout = layout;
@@ -1483,8 +1482,11 @@ export class GraphCanvas {
1483
1482
  }
1484
1483
  this.animate({ x, y, k }, dur);
1485
1484
  }
1486
- /** The camera carried to `goal` over `dur` ms, easing in and out. */
1485
+ /** The camera carried to `goal` over `dur` ms, easing in and out; with reduced motion there at
1486
+ * once (theme.ts, reducedMotion): a flight, a fit, the zoom buttons, an artwork's frame closing in. */
1487
1487
  animate(goal, dur) {
1488
+ if (reducedMotion())
1489
+ return this.jumpTo(goal);
1488
1490
  if (this.anim)
1489
1491
  cancelAnimationFrame(this.anim);
1490
1492
  const { x, y, k } = goal;
@@ -2051,7 +2053,9 @@ export class GraphCanvas {
2051
2053
  sel.clear();
2052
2054
  if (act && this.edges.length && this.art?.edges !== "none") {
2053
2055
  const count = this.edges.length / 3;
2054
- const fade = count < 250 ? 1 : Math.max(0.25, Math.sqrt(250 / count));
2056
+ // the theme's own fading (crowdFade) from fewer: a selection's edges are bundled into few
2057
+ // trunks, a hundred of them already one bright band
2058
+ const fade = (count < 250 ? 1 : Math.max(0.25, Math.sqrt(250 / count))) * crowdFade(count, 100, th.edgeCrowd);
2055
2059
  const width = count > 4000 ? 1 : 1.6;
2056
2060
  const rep = S.nodeRep;
2057
2061
  const id = (i) => (rep[i] >= 0 ? rep[i] : S.nc + i);
@@ -2501,7 +2505,7 @@ export class GraphCanvas {
2501
2505
  const p = Q.points.get(point);
2502
2506
  return { looks: p.looks, index: Q.indexOf(p), w, scale: dimNow / (p.dim ? DIM : 1) };
2503
2507
  });
2504
- const drawn = `${this.overviewStyle}|${dim}|${W.map((x) => `${Q.points.get(x.point).serial}:${x.w.toFixed(3)}`).join(",")}`;
2508
+ const drawn = `${this.themeSerial}|${this.overviewStyle}|${dim}|${W.map((x) => `${Q.points.get(x.point).serial}:${x.w.toFixed(3)}`).join(",")}`;
2505
2509
  if (drawn === this.overviewDrawn)
2506
2510
  return;
2507
2511
  this.overviewDrawn = drawn;
@@ -2516,6 +2520,15 @@ export class GraphCanvas {
2516
2520
  [c1[0], c1[1], c1[2], c1[3]] = [to[0], to[1], to[2], (styled ? to[3] : 1) * alpha];
2517
2521
  bundlePath(L, P.path, 8 * j, P.len[j], beta, width, c0, c1);
2518
2522
  });
2523
+ // the theme's own fading with their number (crowdFade), from the number at which the overview's
2524
+ // choice starts fading them (web/src/overview.ts, looksOf)
2525
+ const k = crowdFade(L.count, OVERVIEW_CROWD, this.theme.edgeCrowd);
2526
+ if (k < 1)
2527
+ for (let n = 0; n < L.count; n++) {
2528
+ const o = n * BUNDLE_STRIDE;
2529
+ L.data[o + 15] *= k;
2530
+ L.data[o + 19] *= k;
2531
+ }
2519
2532
  }
2520
2533
  /** The colours of a bundled edge from `a` to `b` (ids of the scene's clusters, and of its
2521
2534
  * declarations past them), from the end that uses: the theme's; an artwork's cells', from one
@@ -237,7 +237,7 @@ export class OverviewModel {
237
237
  const Y = (id) => (id < nc ? S.cwy[id] : S.nwy[id - nc]);
238
238
  // many bundles share the screen: the more there are, the fainter each; with a selection the
239
239
  // overview steps back so the selection's own edges read
240
- const crowd = Math.min(1, Math.sqrt(400 / Math.max(1, n)));
240
+ const crowd = Math.min(1, Math.sqrt(OVERVIEW_CROWD / Math.max(1, n)));
241
241
  const fade = (ask.dim ? DIM : 1) * crowd;
242
242
  // few edges in view (zoomed in): even a single one clearly visible
243
243
  const floor = 0.05 + 0.3 * Math.min(1, Math.max(0, (1200 - nIn) / 900));
@@ -265,6 +265,9 @@ export class OverviewModel {
265
265
  return looks;
266
266
  }
267
267
  }
268
+ /** The number of bundles past which the more there are, the fainter each (looksOf); a theme's own
269
+ * fading with their number starts there too (web/src/canvas.ts, crowdFade). */
270
+ export const OVERVIEW_CROWD = 400;
268
271
  /** How much a selection dims the overview, so that its own edges read, the rest still seen faintly:
269
272
  * on the board and in an artwork alike (the owner's decision of 2026-10-15; 0.12 before). */
270
273
  export const DIM = 0.3;
@@ -16,6 +16,7 @@
16
16
  // The scene may hold room for what is not the board's: the discs the reader's visitors and their
17
17
  // temporary clusters take (ViewSpec decision 27; web/src/visits.ts). What they cover makes way, as
18
18
  // from a drop; they are never pins, and when they go everything is where it was.
19
+ import { hypot } from "../../shared/libm.js";
19
20
  import { Separator } from "../../shared/separate.js";
20
21
  /** collision radius of a declaration, as the server packs them */
21
22
  export const LEAF_R = 5;
@@ -423,7 +424,7 @@ export class Scene {
423
424
  if (p < 0)
424
425
  return [lx, ly];
425
426
  const room = Math.max(0, this.homeR[p] - this.padOf(p) - r);
426
- const d = Math.hypot(lx, ly);
427
+ const d = hypot(lx, ly);
427
428
  return d > room ? [(lx * room) / d, (ly * room) / d] : [lx, ly];
428
429
  }
429
430
  /** Room between a cluster's contents and its circle, for its label. */
@@ -520,9 +521,9 @@ export class Scene {
520
521
  const DENSITY = 0.72;
521
522
  let area = 0;
522
523
  for (const it of (shrunk ? items : []).filter((x) => !x.pinned).sort((a, b) => a.hx * a.hx + a.hy * a.hy - (b.hx * b.hx + b.hy * b.hy))) {
523
- const len = Math.hypot(it.hx, it.hy);
524
+ const len = hypot(it.hx, it.hy);
524
525
  const ux = len > 1e-6 ? it.hx / len : 1, uy = len > 1e-6 ? it.hy / len : 0;
525
- area += (Math.PI * (it.r + GAP / 2) ** 2) / DENSITY;
526
+ area += (Math.PI * ((it.r + GAP / 2) * (it.r + GAP / 2))) / DENSITY;
526
527
  const d = Math.min(len, Math.max(0, Math.sqrt(area / Math.PI) - it.r));
527
528
  it.x = ux * d;
528
529
  it.y = uy * d;
@@ -545,7 +546,7 @@ export class Scene {
545
546
  const inward = shrunk && !grown && !pinned;
546
547
  const room = self >= 0 ? homeR - this.padOf(self) : Infinity;
547
548
  const limit = Float64Array.from(items, (it) => {
548
- const len = Math.hypot(it.hx, it.hy);
549
+ const len = hypot(it.hx, it.hy);
549
550
  return inward ? len : Math.max(len, room - it.r);
550
551
  });
551
552
  const sep = this.separator;
@@ -585,7 +586,7 @@ export class Scene {
585
586
  });
586
587
  let extent = 0;
587
588
  for (const it of items) {
588
- extent = Math.max(extent, Math.hypot(it.x, it.y) + it.r);
589
+ extent = Math.max(extent, hypot(it.x, it.y) + it.r);
589
590
  if (it.c >= 0) {
590
591
  this.ancCX[it.c] = it.x;
591
592
  this.ancCY[it.c] = it.y;
@@ -629,17 +630,17 @@ export class Scene {
629
630
  const idx = Array.from({ length: n }, (_, j) => j);
630
631
  const B = { n, x, y, r, pinned, seq, big: Int32Array.from(idx.filter((j) => r[j] > LEAF_R + 0.1)), small: Int32Array.from(idx.filter((j) => r[j] <= LEAF_R + 0.1)) };
631
632
  const room = self >= 0 ? homeR - this.padOf(self) : Infinity;
632
- const limit = Float64Array.from(idx, (j) => Math.max(Math.hypot(x[j], y[j]), room - r[j]));
633
+ const limit = Float64Array.from(idx, (j) => Math.max(hypot(x[j], y[j]), room - r[j]));
633
634
  // how far the children reach before they make way: the circle grows by what they are pushed out
634
635
  let reach = 0;
635
636
  for (let j = 0; j < nk; j++)
636
- reach = Math.max(reach, Math.hypot(x[j], y[j]) + r[j]);
637
+ reach = Math.max(reach, hypot(x[j], y[j]) + r[j]);
637
638
  // only what a held disc covers makes way: overlaps the board's own arrangement has are its own
638
639
  // (a layout may hold some), and stay as they are where the held discs cover nothing
639
640
  let covers = false;
640
641
  for (let h = nk; h < n && !covers; h++)
641
642
  for (let j = 0; j < n && !covers; j++)
642
- if (j !== h && Math.hypot(x[j] - x[h], y[j] - y[h]) < r[j] + r[h] - 0.5)
643
+ if (j !== h && hypot(x[j] - x[h], y[j] - y[h]) < r[j] + r[h] - 0.5)
643
644
  covers = true;
644
645
  const sep = this.separator;
645
646
  if (covers) {
@@ -665,7 +666,7 @@ export class Scene {
665
666
  return 0;
666
667
  let pushed = 0, own = 0;
667
668
  for (let j = 0; j < n; j++) {
668
- const d = Math.hypot(x[j], y[j]) + r[j];
669
+ const d = hypot(x[j], y[j]) + r[j];
669
670
  if (j < nk)
670
671
  pushed = Math.max(pushed, d);
671
672
  else
@@ -783,17 +784,17 @@ export class Scene {
783
784
  let reach = 0;
784
785
  const x = this.cwx[c], y = this.cwy[c];
785
786
  for (const k of this.kidsC[c])
786
- reach = Math.max(reach, Math.hypot(this.cwx[k] - x, this.cwy[k] - y) + this.drawnR[k]);
787
+ reach = Math.max(reach, hypot(this.cwx[k] - x, this.cwy[k] - y) + this.drawnR[k]);
787
788
  for (const i of this.kidsN[c]) {
788
789
  if (this.nodeRep[i] >= 0)
789
790
  continue;
790
- reach = Math.max(reach, Math.hypot(this.nwx[i] - x, this.nwy[i] - y) + LEAF_R);
791
+ reach = Math.max(reach, hypot(this.nwx[i] - x, this.nwy[i] - y) + LEAF_R);
791
792
  }
792
793
  // what is held in it is inside it too: a visitor's temporary clusters (setHeld)
793
794
  const held = this.held.get(c), at = this.heldAt.get(c);
794
795
  if (held && at)
795
796
  for (let j = 0; j < held.length; j++)
796
- reach = Math.max(reach, (Math.hypot(at[2 * j], at[2 * j + 1]) + held[j].r) * this.scale[c]);
797
+ reach = Math.max(reach, (hypot(at[2 * j], at[2 * j + 1]) + held[j].r) * this.scale[c]);
797
798
  this.drawnR[c] = Math.max(this.curR[c], reach > 0 ? reach + MARGIN : 0);
798
799
  }
799
800
  }
@@ -80,3 +80,31 @@ export function statusCounts(codes, counted = () => true) {
80
80
  n[codes[i]]++;
81
81
  return n;
82
82
  }
83
+ /** A file cluster's own build trouble, as a Status code (failed, building, sorry), or -1: what its
84
+ * outline shows in the Status scheme. Trouble inherited from below (blocked, out of date because
85
+ * something under it changed) is left out, so that one failure does not ring every file above it. */
86
+ export function fileTrouble(f) {
87
+ switch (f?.state) {
88
+ case "failed":
89
+ case "unbuilt":
90
+ return ST_FAILED;
91
+ case "building":
92
+ return ST_BUILDING;
93
+ case "sorry":
94
+ return ST_SORRY;
95
+ default:
96
+ return -1;
97
+ }
98
+ }
99
+ /** Each cluster's outline in the Status scheme (CanvasSpec, "Files and clusters"): its file's own
100
+ * trouble (fileTrouble) where the clusters are files, -1 (none, the plain outline) for every other
101
+ * cluster. Under namespaces a cluster's key is a namespace, which can read like a module's name
102
+ * without being its file: none has an outline there. -1, not 0, is "none": 0 is failed's code, and
103
+ * an array left at zeros ringed every namespace in failed's colour (the owner's report of
104
+ * 2026-10-18). */
105
+ export function clusterTroubles(clusters, clustering, files) {
106
+ const out = new Int8Array(clusters.length).fill(-1);
107
+ if (clustering === "module")
108
+ clusters.forEach((c, k) => (out[k] = fileTrouble(files.get(c.key))));
109
+ return out;
110
+ }
@@ -0,0 +1,108 @@
1
+ // Light, dark, or as the system is: the reader's choice, kept for every project in this browser;
2
+ // light unless they chose otherwise, on every platform (the owner's decision of 2026-10-14). The
3
+ // page's colours follow `data-theme` on <html> (style.css); a script in index.html's <head> sets it
4
+ // before the first paint, from the same stored choice, so a dark page never flashes light.
5
+ //
6
+ // What draws in the theme's colours itself — the board's canvas, the linear form — reads them from
7
+ // the page's custom properties as it draws, and keeps what it drew: it draws again when the theme on
8
+ // show changes (onThemeChange), whoever changed it, in either direction.
9
+ //
10
+ // The system's other preference the page follows is reduced motion (reducedMotion): nothing on the
11
+ // page glides then — style.css's one rule for its transitions and animations, and here for what
12
+ // moves by itself (the board's camera, the linear form coming and going).
13
+ const KEY = "visualproof:theme";
14
+ // none without a browser: the artwork command reads the board's module, which reads this one
15
+ const dark = typeof matchMedia === "function" ? matchMedia("(prefers-color-scheme: dark)") : null;
16
+ /** the theme something holds on show over the reader's choice (holdTheme), or none */
17
+ let held = null;
18
+ /** Whether the system asks for reduced motion: what would glide is where it goes at once (GuideSpec
19
+ * decision 4; the camera, web/src/canvas.ts animate; the linear form, web/src/linear.ts). Read as
20
+ * it is asked, so that a change of the setting holds from the next motion. */
21
+ export const reducedMotion = () => typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
22
+ export function themeChoice() {
23
+ try {
24
+ const v = localStorage.getItem(KEY);
25
+ if (v === "dark" || v === "system")
26
+ return v;
27
+ }
28
+ catch {
29
+ // storage blocked: the default
30
+ }
31
+ return "light";
32
+ }
33
+ /** Put the choice in force: what <html> says, now and (for "system") whenever the system changes;
34
+ * while a theme is held (holdTheme), that one. */
35
+ export function applyTheme(choice = themeChoice()) {
36
+ const t = held ?? (choice === "system" ? (dark?.matches ? "dark" : "light") : choice);
37
+ if (document.documentElement.dataset.theme !== t)
38
+ document.documentElement.dataset.theme = t;
39
+ }
40
+ /** Show `t` whatever the reader chose, until it is let go (null): the artwork mode's theme (web/src/
41
+ * main.ts, drawLook), which a change of the system's, followed by "As the system", must not undo
42
+ * while the mode is on. Let go, the reader's choice is in force again. */
43
+ export function holdTheme(t) {
44
+ held = t;
45
+ applyTheme();
46
+ }
47
+ const followers = [];
48
+ let watching = null;
49
+ let shown;
50
+ /** Call `f` whenever the theme on show changes, light to dark or back: by the reader's choice, the
51
+ * system's while it is followed, an artwork's look. It is read from <html> itself, so that no way of
52
+ * changing it is missed; setting it to what it is already is no change. */
53
+ export function onThemeChange(f) {
54
+ followers.push(f);
55
+ if (watching || typeof MutationObserver === "undefined")
56
+ return;
57
+ shown = document.documentElement.dataset.theme;
58
+ watching = new MutationObserver(() => {
59
+ const now = document.documentElement.dataset.theme;
60
+ if (now === shown)
61
+ return;
62
+ shown = now;
63
+ for (const g of followers)
64
+ g();
65
+ });
66
+ watching.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme"] });
67
+ }
68
+ export function setTheme(choice) {
69
+ try {
70
+ // the default is kept as nothing, so that a later change of the default reaches whoever never chose
71
+ if (choice === "light")
72
+ localStorage.removeItem(KEY);
73
+ else
74
+ localStorage.setItem(KEY, choice);
75
+ }
76
+ catch {
77
+ // not kept: in force for this page only
78
+ }
79
+ applyTheme(choice);
80
+ }
81
+ dark?.addEventListener("change", () => {
82
+ if (themeChoice() === "system")
83
+ applyTheme("system");
84
+ });
85
+ const ICONS = {
86
+ light: `<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><circle cx="8" cy="8" r="3"/><path d="M8 1.5v1.5M8 13v1.5M1.5 8H3M13 8h1.5M3.4 3.4l1 1M11.6 11.6l1 1M3.4 12.6l1-1M11.6 4.4l1-1"/></svg>`,
87
+ dark: `<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M13 9.5A5.5 5.5 0 0 1 6.5 3a5.5 5.5 0 1 0 6.5 6.5Z"/></svg>`,
88
+ system: `<svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><rect x="2" y="3" width="12" height="8.5" rx="1.5"/><path d="M6 14h4M8 11.5V14"/></svg>`,
89
+ };
90
+ const LABELS = { light: "Light", dark: "Dark", system: "As the system" };
91
+ /** The theme's three choices side by side, in the eyes' ⋯ menu at the bottom right (since
92
+ * 2026-10-08; a switch of its own under the zoom buttons before). */
93
+ export function themeChoices(el) {
94
+ const render = () => {
95
+ const c = themeChoice();
96
+ el.innerHTML = ["light", "dark", "system"]
97
+ .map((k) => `<button data-theme-choice="${k}" class="${k === c ? "on" : ""}" role="radio" aria-checked="${k === c}" title="${LABELS[k]}" aria-label="${LABELS[k]}">${ICONS[k]}</button>`)
98
+ .join("");
99
+ };
100
+ render();
101
+ el.addEventListener("click", (e) => {
102
+ const b = e.target.closest("[data-theme-choice]");
103
+ if (!b)
104
+ return;
105
+ setTheme(b.dataset.themeChoice);
106
+ render();
107
+ });
108
+ }