@intentius/behold 0.29.57 → 0.30.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 (46) hide show
  1. package/AGENTS.md +323 -26
  2. package/demos.json +1 -1
  3. package/dist/cli.js +5129 -2040
  4. package/example-choudoufu-estate/chant.workspace.json +1 -1
  5. package/example-terraform-estate/README.md +10 -10
  6. package/example-terraform-estate/chant.workspace.json +1 -1
  7. package/example-three-cloud/README.md +17 -9
  8. package/example-three-cloud/aws/chant.config.ts +1 -1
  9. package/example-three-cloud/aws/site.component.ts +13 -0
  10. package/example-three-cloud/azure/chant.config.ts +1 -1
  11. package/example-three-cloud/azure/src/site.component.ts +13 -0
  12. package/example-three-cloud/azure/src/site.ts +5 -7
  13. package/example-three-cloud/dns/chant.config.ts +1 -1
  14. package/example-three-cloud/dns/src/records.component.ts +14 -0
  15. package/example-three-cloud/dns/src/route53.ts +4 -5
  16. package/example-three-cloud/gcp/chant.config.ts +1 -1
  17. package/example-three-cloud/gcp/src/site.component.ts +13 -0
  18. package/example-three-cloud/gcp/src/site.ts +7 -7
  19. package/example-three-cloud/package-lock.json +19 -19
  20. package/example-three-cloud/package.json +4 -4
  21. package/example-three-cloud/scripts/front-door.ts +89 -15
  22. package/package.json +8 -9
  23. package/web/agent-move.js +60 -0
  24. package/web/agent-move.test.js +55 -0
  25. package/web/app.js +555 -76
  26. package/web/dots-lod.js +1 -1
  27. package/web/embed.d.ts +3 -0
  28. package/web/embed.js +5 -3
  29. package/web/embed.test.js +8 -0
  30. package/web/index.html +64 -9
  31. package/web/panel.js +28 -4
  32. package/web/release.js +6 -4
  33. package/web/release.test.js +2 -2
  34. package/web/search-view.d.ts +27 -0
  35. package/web/search-view.js +213 -0
  36. package/web/search-view.test.js +144 -0
  37. package/web/shot-frame.d.ts +5 -0
  38. package/web/shot-frame.js +116 -0
  39. package/web/shot-frame.test.js +90 -0
  40. package/web/themes.js +1 -1
  41. package/web/view-url.d.ts +18 -0
  42. package/web/view-url.js +153 -6
  43. package/web/view-url.test.js +72 -1
  44. package/example-three-cloud/azure/composites/container-app-site.ts +0 -77
  45. package/example-three-cloud/dns/composites/latency-entry.ts +0 -73
  46. package/example-three-cloud/gcp/composites/public-cloud-run.ts +0 -102
package/web/dots-lod.js CHANGED
@@ -84,7 +84,7 @@ export function caption(level) {
84
84
  case "cards-dots":
85
85
  return "cards shrinking to dots: each dot is a resource";
86
86
  case "dots":
87
- return "each dot is a resource, in its estate's box and colour";
87
+ return "each dot is a resource, in its estate's box and color";
88
88
  case "dots-discs":
89
89
  return "each dot is a resource; each disc is an estate, sized by resources";
90
90
  case "discs":
package/web/embed.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ // Types for the tests that hold a host's behold:view to the view keys (behold#922).
2
+ import type { Want } from "./view-url.js";
3
+ export function viewFromMessage(event: { origin?: string; data?: unknown } | null | undefined, host: string | null | undefined): Want | null;
package/web/embed.js CHANGED
@@ -60,13 +60,15 @@ export function viewFromMessage(event, host) {
60
60
  for (const k of VIEW_KEYS) {
61
61
  if (!(k in d)) continue;
62
62
  const v = d[k];
63
- if (k === "radial") {
64
- if (typeof v === "boolean") want.radial = v;
63
+ if (k === "radial" || k === "plan") {
64
+ // plan (behold#922): true is the plan read, false the declared source again.
65
+ if (typeof v === "boolean") want[k] = v;
65
66
  continue;
66
67
  }
67
- if (k === "env" || k === "gates" || k === "focus" || k === "run" || k === "pull") {
68
+ if (k === "env" || k === "gates" || k === "focus" || k === "run" || k === "pull" || k === "q" || k === "snapshot" || k === "countBy") {
68
69
  // env: null or "" is the source graph. gates: null or "" hands the
69
70
  // gate strip back to the graph's env. focus: null or "" brings nothing forward. run: null or "" draws the newest run again.
71
+ // q, snapshot (#913/#914): null or "" clears the question, or reads the env live again.
70
72
  if (v === null || v === "") want[k] = null;
71
73
  else if (typeof v === "string") want[k] = v;
72
74
  continue;
package/web/embed.test.js CHANGED
@@ -90,3 +90,11 @@ describe("the wheel in the kiosk's bare frame", () => {
90
90
  expect(wheelPx({})).toBe(0);
91
91
  });
92
92
  });
93
+
94
+ describe("viewFromMessage q and snapshot (#913, #914)", () => {
95
+ const host = "http://localhost:7777";
96
+ it("takes q and snapshot from the host, null or empty clearing them", () => {
97
+ expect(viewFromMessage({ origin: host, data: { type: "behold:view", q: "kind:Bucket", snapshot: "latest" } }, host)).toEqual({ q: "kind:Bucket", snapshot: "latest" });
98
+ expect(viewFromMessage({ origin: host, data: { type: "behold:view", q: "", snapshot: null } }, host)).toEqual({ q: null, snapshot: null });
99
+ });
100
+ });
package/web/index.html CHANGED
@@ -27,11 +27,11 @@
27
27
  route or an asset: no request, and the exported page keeps it. -->
28
28
  <link
29
29
  rel="icon"
30
- href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ccircle cx='8' cy='8' r='6' fill='none' stroke='%23a6adc8' stroke-width='1.6'/%3E%3Ccircle cx='8' cy='8' r='2.2' fill='%23a6adc8'/%3E%3C/svg%3E"
30
+ href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ccircle cx='8' cy='8' r='6' fill='none' stroke='%23696b6c' stroke-width='1.6'/%3E%3Ccircle cx='8' cy='8' r='2.2' fill='%23696b6c'/%3E%3C/svg%3E"
31
31
  />
32
32
  <style>
33
33
  /* Pre-paint fallback (#229). These are the DEFAULT theme's tokens —
34
- Catppuccin Mocha run through theme.js's tokensFor() — not a palette of
34
+ GitHub Light Colorblind run through theme.js's tokensFor() — not a palette of
35
35
  their own, so the first frame is already the frame initTheme() lands
36
36
  on and there is no flash of a different app. (It used to be GitHub
37
37
  Primer dark, which is why behold's first paint read as every other
@@ -39,11 +39,11 @@
39
39
  live in this block; smoke/ui-smoke.mjs recomputes them from theme.js
40
40
  and fails if the two drift apart. */
41
41
  :root {
42
- --bg: #1e1e2e; --panel: #2e2f40; --line: #3b3c4a; --fg: #cdd6f4; --muted: #9598aa; --ink2: #c4cbe4;
43
- --edge: #7e839b; --managed: #a6e3a1; --foreign: #f9e2af; --pending: #89b4fa;
44
- --degraded: #f38ba8; --neutral: #6d7187; --runtime: #94e2d5;
45
- --rule: #4e4f64; --focus: #a3b4d0; --active: #3d4660; --well: #11101f; --shadow: #050507;
46
- --bar-managed: #a6e3a1; --bar-foreign: #f9e2af; --bar-pending: #89b4fa; --bar-degraded: #f38ba8; --bar-runtime: #94e2d5; --bar-neutral: #9b9fb7;
42
+ --bg: #ffffff; --panel: #ebecec; --line: #dcddde; --fg: #24292f; --muted: #696b6c; --ink2: #41454a;
43
+ --edge: #87898d; --managed: #0550ae; --foreign: #4d2d00; --pending: #0969da;
44
+ --degraded: #b35900; --neutral: #9c9fa1; --runtime: #1b7c83;
45
+ --rule: #999ea3; --focus: #52709b; --active: #c5d6e9; --well: #ebebeb; --shadow: #666666;
46
+ --bar-managed: #0550ae; --bar-foreign: #4d2d00; --bar-pending: #0969da; --bar-degraded: #af5700; --bar-runtime: #167980; --bar-neutral: #6c6f71;
47
47
  }
48
48
  /* The non-colour half of the identity: type and radii. These can't derive
49
49
  from a colour theme, so they're the one static token block — but they
@@ -211,6 +211,7 @@
211
211
  #graph [data-layout-resize] { transition: none; }
212
212
  }
213
213
  #graph g[data-edge-from]:hover .pin-edge-line,
214
+ #graph g[data-edge-from].edge-over .pin-edge-line,
214
215
  #graph g[data-edge-from].edge-hi .pin-edge-line { stroke: var(--pending); stroke-width: 3.2; }
215
216
  /* Edge kind by reason (logical view): a data dependency reads as a dashed
216
217
  "logical link", distinct from the solid network-traffic edges; hover
@@ -443,11 +444,17 @@
443
444
  #zoom-toggle:hover { border-color: var(--focus); color: var(--fg); }
444
445
  /* Hand layout (#228): the escape hatch, beside ⤢ fit. Hidden by app.js
445
446
  until something on this lens is actually hand-placed — it is both the
446
- reset and the only indication that dagre isn't the whole story here. */
447
+ reset and the only sign that cards have been moved by hand. */
447
448
  #layout-reset { position: absolute; top: 8px; right: 66px; z-index: 2; background: var(--panel);
448
449
  color: var(--muted); border: 1px solid var(--rule); border-radius: var(--r-ctl); padding: var(--s1) var(--s3);
449
450
  font: var(--t-caption)/1.3 var(--font-mono); cursor: pointer; }
450
451
  #layout-reset:hover { border-color: var(--focus); color: var(--fg); }
452
+ /* The view features one click away, top-centre of the graph pane, clear of the panel and ⤢ fit. */
453
+ #view-toggles { position: absolute; top: 8px; left: 50%; transform: translateX(-50%); z-index: 2; display: flex; gap: var(--s1); }
454
+ #view-toggles .vt { background: var(--panel); color: var(--fg); border: 1px solid var(--rule); border-radius: var(--r-ctl);
455
+ padding: var(--s1) var(--s3); font: var(--t-caption)/1.3 var(--font-mono); cursor: pointer; }
456
+ #view-toggles .vt:hover { border-color: var(--focus); }
457
+ #view-toggles .vt.active { border-color: var(--focus); background: var(--focus); color: var(--bg); }
451
458
  /* A containment box's title moves it and its corner handle resizes it.
452
459
  The handle carries opacity="0" as a presentation attribute so a static
453
460
  export never shows it — this rule outranks the attribute. */
@@ -663,6 +670,26 @@
663
670
  #panel-collapse:hover { color: var(--fg); }
664
671
  #panel-body { overflow-y: auto; max-height: min(62vh, 540px); padding: var(--s3) var(--s4);
665
672
  font-size: var(--t-body); user-select: text; }
673
+ /* On a phone (web/panel.js): a Done button to fold the panel, a body short
674
+ enough to leave the graph in sight, and the toggles and the inspect
675
+ pane's controls where a thumb finds them. */
676
+ #panel-done { display: none; }
677
+ @media (max-width: 600px) {
678
+ #panel { width: min(272px, calc(100vw - 24px)); }
679
+ #panel-body { max-height: 46vh; }
680
+ #panel-foot { max-height: 4.5em; overflow-y: auto; }
681
+ #panel-done { display: block; margin: var(--s2) var(--s3) var(--s3); padding: var(--s2); border: 1px solid var(--rule);
682
+ border-radius: var(--r-ctl); background: var(--active); color: var(--fg); font: 600 var(--t-body)/1.2 var(--font-ui); cursor: pointer; }
683
+ #panel.collapsed #panel-done { display: none; }
684
+ #panel-collapse { min-width: 36px; font-size: 16px; }
685
+ #view-toggles { top: 56px; }
686
+ #inspect-collapse { top: 8px; right: 8px; padding: 6px 10px; border: 1px solid var(--rule); border-radius: var(--r-ctl); background: var(--panel);
687
+ font: 600 var(--t-caption)/1 var(--font-ui); color: var(--fg); }
688
+ #inspect-collapse .chev { display: none; }
689
+ #inspect-collapse::after { content: "\2715 close"; }
690
+ #inspect-reopen { top: 56px; right: 12px; transform: none; writing-mode: horizontal-tb; border: 1px solid var(--rule);
691
+ border-radius: var(--r-ctl); padding: var(--s2) var(--s3); color: var(--fg); }
692
+ }
666
693
  #panel-body section { display: none; }
667
694
  #panel-body section.active { display: block; }
668
695
  #panel h3 { margin: var(--s4) 0 var(--s2); font: 600 var(--t-caption)/1.4 var(--font-ui); color: var(--muted); }
@@ -1022,6 +1049,34 @@
1022
1049
  box-shadow: 0 6px 20px color-mix(in srgb, var(--shadow) 60%, transparent); font: var(--t-body)/1.45 var(--font-ui);
1023
1050
  white-space: pre-line; overflow-wrap: anywhere; pointer-events: none; }
1024
1051
  #b-tip[hidden] { display: none; }
1052
+ /* behold#913: `q`, a chant search query drawn over the graph (web/search-view.js). The matches lit, the
1053
+ cards and edges on their paths at full weight, the rest dimmed; nothing hidden. A no-matches view
1054
+ outlines the near-misses; a row a live read could not observe wears a dashed ring. */
1055
+ #graph [data-node-id][data-q="dim"], #graph g[data-edge-from][data-q="dim"] { opacity: .22; transition: opacity .15s; }
1056
+ #graph [data-node-id][data-q="lit"] rect:first-of-type { stroke: var(--pending); stroke-width: 3; }
1057
+ #graph [data-node-id][data-q="path"] rect:first-of-type { stroke: var(--pending); stroke-width: 1.5; }
1058
+ #graph g[data-edge-from][data-q="path"] path:first-of-type { stroke: var(--pending); stroke-width: 2.5; }
1059
+ #graph [data-node-id][data-q-near] { opacity: .6; }
1060
+ #graph [data-node-id][data-q-near] rect:first-of-type { stroke: var(--ink2); stroke-width: 1.5; stroke-dasharray: 3 2; }
1061
+ #graph [data-node-id][data-q-unobserved] rect:first-of-type { stroke: var(--degraded); stroke-dasharray: 5 3; }
1062
+ /* behold#922: a counts answer: each group's cards outlined in its colour, its first card labelled with chant's count. */
1063
+ #graph [data-node-id][data-q-group] rect:first-of-type { stroke: var(--q-group); stroke-width: 3; }
1064
+ #graph .q-group-label { font: 600 12px var(--font-mono); paint-order: stroke; stroke: var(--bg); stroke-width: 3px; pointer-events: none; }
1065
+ #q-line { position: fixed; top: 12px; left: 12px; z-index: 54; max-width: min(640px, calc(100vw - 32px)); padding: 6px 10px;
1066
+ border: 1px solid var(--rule); border-left: 4px solid var(--pending); border-radius: 6px; background: var(--panel); color: var(--fg);
1067
+ font: 12px/1.4 var(--font-mono); overflow-wrap: anywhere; box-shadow: 0 4px 16px color-mix(in srgb, var(--shadow) 40%, transparent); }
1068
+ #q-line[hidden] { display: none; }
1069
+ #q-line[data-tone="empty"] { border-left-color: var(--neutral); }
1070
+ #q-line[data-tone="failed"] { border-left-color: var(--degraded); color: var(--degraded); }
1071
+ #q-line .q-line-not-searched { color: var(--muted); margin-top: 2px; }
1072
+ /* #914: an agent moved this tab (POST /api/view). Says who asked what, and when, with Back. */
1073
+ #agent-banner { position: fixed; top: 12px; left: 50%; transform: translateX(-50%); z-index: 55; display: flex; align-items: center; gap: 10px;
1074
+ max-width: min(720px, calc(100vw - 32px)); padding: 8px 12px; border: 1px solid var(--rule); border-radius: 6px;
1075
+ background: var(--panel); color: var(--fg); box-shadow: 0 4px 16px var(--shadow); font-size: 13px; }
1076
+ #agent-banner[hidden] { display: none; }
1077
+ #agent-banner .agent-banner-text { overflow-wrap: anywhere; }
1078
+ #agent-banner button { flex: none; font: inherit; color: var(--fg); background: var(--well); border: 1px solid var(--rule); border-radius: 4px; padding: 2px 10px; cursor: pointer; }
1079
+ #agent-banner .agent-banner-close { padding: 2px 6px; background: none; border-color: transparent; }
1025
1080
  /* web/motion.js marks the page while its tab is hidden: every animation holds where it is. */
1026
1081
  :root[data-motion="paused"] *, :root[data-motion="paused"] *::before, :root[data-motion="paused"] *::after { animation-play-state: paused !important; }
1027
1082
  </style>
@@ -1037,7 +1092,7 @@
1037
1092
  <div id="ws-gates" hidden></div>
1038
1093
  <aside id="inspect">
1039
1094
  <div id="inspect-resize" title="Drag to resize"></div>
1040
- <button id="inspect-collapse" title="Collapse panel">›</button>
1095
+ <button id="inspect-collapse" title="Collapse panel"><span class="chev">›</span></button>
1041
1096
  <div id="inspect-body"><h2>Inspect</h2><p style="color:var(--ink2)">Click a node</p></div>
1042
1097
  </aside>
1043
1098
  <button id="inspect-reopen" title="Show inspect panel">Inspect ‹</button>
package/web/panel.js CHANGED
@@ -170,9 +170,23 @@ export function isPanelCollapsed() {
170
170
  return !!state.collapsed;
171
171
  }
172
172
 
173
- export function initPanel({ embed = false, phone = false } = {}) {
173
+ // On a phone the open panel covers most of the graph, and a chevron in its
174
+ // corner was the only way to fold it. There it also folds on a tap on the
175
+ // graph or the inspect pane, on a tap on the tab that is already open, on its
176
+ // own Done button, and once a pick has changed what the graph shows.
177
+ let phoneQuery = null;
178
+ function onPhone() {
179
+ return !!phoneQuery && typeof matchMedia === "function" && matchMedia(phoneQuery).matches;
180
+ }
181
+ /** Fold the panel when on a phone, so the graph a pick just changed is in view. */
182
+ export function foldPanelOnPhone() {
183
+ if (onPhone() && !state.collapsed) setCollapsed(true);
184
+ }
185
+
186
+ export function initPanel({ embed = false, phone = false, phoneQuery: query = null } = {}) {
174
187
  panel = document.getElementById("panel");
175
188
  if (!panel) return;
189
+ phoneQuery = query;
176
190
  if (embed) {
177
191
  STORE_KEY = "behold.panel.embed";
178
192
  state.collapsed = true;
@@ -187,11 +201,21 @@ export function initPanel({ embed = false, phone = false } = {}) {
187
201
  const bar = document.getElementById("panel-tabs");
188
202
  initDrag(bar);
189
203
  bar.addEventListener("dblclick", (e) => {
190
- if (!e.target.closest("#panel-collapse, #hintk")) togglePanelCollapsed();
204
+ // On a phone two taps on a tab are a double-click, and the taps already open and fold it.
205
+ if (!e.target.closest("#panel-collapse, #hintk") && !onPhone()) togglePanelCollapsed();
191
206
  });
192
207
  document.getElementById("panel-collapse").addEventListener("click", () => togglePanelCollapsed());
193
- // Clicking a tab while collapsed expands (setPanelTab's default).
194
- for (const b of panel.querySelectorAll("#panel-tabs button[data-tab]")) b.addEventListener("click", () => setPanelTab(b.dataset.tab));
208
+ // Clicking a tab while collapsed expands (setPanelTab's default); on a phone, the open tab folds.
209
+ for (const b of panel.querySelectorAll("#panel-tabs button[data-tab]"))
210
+ b.addEventListener("click", () => (onPhone() && !state.collapsed && state.tab === b.dataset.tab ? setCollapsed(true) : setPanelTab(b.dataset.tab)));
211
+ const done = document.createElement("button");
212
+ done.id = "panel-done";
213
+ done.textContent = "Done";
214
+ done.addEventListener("click", () => setCollapsed(true));
215
+ panel.appendChild(done);
216
+ document.addEventListener("pointerdown", (e) => {
217
+ if (onPhone() && !state.collapsed && e.target.closest && e.target.closest("#graph, #inspect")) setCollapsed(true);
218
+ });
195
219
  const known = [...panel.querySelectorAll("#panel-tabs button[data-tab]")].map((b) => b.dataset.tab);
196
220
  setCollapsed(state.collapsed);
197
221
  const hidden = embed ? ["deploy"] : [];
package/web/release.js CHANGED
@@ -7,9 +7,8 @@
7
7
  import { approvalLink } from "./operator.js";
8
8
  import { waitingFor } from "./run-playhead.js";
9
9
 
10
- /** How the pane names each id space. `laptop` for a local mint: "local" would
11
- * read as a place, and the point is that there is nowhere to go. */
12
- export const FORGE_LABEL = { github: "GitHub Actions", gitlab: "GitLab CI", op: "an Op run", local: "a laptop run", unknown: "an unlinked run" };
10
+ /** How the pane names each id space. A local mint is a run outside CI: there is nowhere to go. */
11
+ export const FORGE_LABEL = { github: "GitHub Actions", gitlab: "GitLab CI", op: "an Op run", local: "a run outside CI", unknown: "an unlinked run" };
13
12
 
14
13
  /** The one line that says why there is no link, or null when there is one.
15
14
  * Never a placeholder link, never a guessed forge: the three id spaces a
@@ -55,7 +54,10 @@ export function releaseRows(release, now = Date.now()) {
55
54
  const why = unlinkedReason(release);
56
55
  if (why) rows.push(["", why]);
57
56
  rows.push(["commit", release.gitSha]);
58
- rows.push(["digest", release.digest]);
57
+ // A plan or deploy-input digest names no artifact (chant#4274), so the row
58
+ // says which it is rather than letting it read as an image digest.
59
+ const kind = release.digestKind;
60
+ rows.push([kind ? `digest (${kind})` : "digest", release.digest]);
59
61
  const ago = release.timestamp ? waitingFor(release.timestamp, now) : null;
60
62
  rows.push(["recorded", ago ? `${release.timestamp} (${ago} ago)` : release.timestamp]);
61
63
  rows.push(["actor", release.actor]);
@@ -22,12 +22,12 @@ describe("release rows (#165)", () => {
22
22
  expect(releaseRows(r, NOW)[0]).toEqual(["run", "18234771902 · an unlinked run"]);
23
23
  });
24
24
 
25
- it("a laptop run says there is nowhere to go — whether the record said local or the id's spelling did", () => {
25
+ it("a run outside CI says there is nowhere to go — whether the record said local or the id's spelling did", () => {
26
26
  const said = { ...base, runId: "local-1756726200000", forge: "local", originSource: "record" };
27
27
  const spelled = { ...base, runId: "local-1756726200000", forge: "local", originSource: "inferred" };
28
28
  expect(unlinkedReason(said)).toMatch(/the record says so/);
29
29
  expect(unlinkedReason(spelled)).toMatch(/a local- id/);
30
- expect(runText(said)).toBe("local-1756726200000 · a laptop run");
30
+ expect(runText(said)).toBe("local-1756726200000 · a run outside CI");
31
31
  });
32
32
 
33
33
  it("an inferred origin never yields a link even if a url is somehow present", () => {
@@ -0,0 +1,27 @@
1
+ // Types for src/count-by-plan.test.ts, which holds the page's drawing of a search answer to chant's document (behold#913, #922).
2
+ export interface Counts {
3
+ by: string;
4
+ total: number;
5
+ groups: Array<{ group: string; count: number; ids: string[] | null }>;
6
+ }
7
+ export interface GroupMark {
8
+ group: string;
9
+ count: number;
10
+ colour: string;
11
+ drawn: string[];
12
+ label: string | null;
13
+ ids: string[] | null;
14
+ }
15
+ export const GROUP_COLOURS: string[];
16
+ export function searchUrl(view: Record<string, unknown>): string;
17
+ export function searchKey(view: Record<string, unknown>): string | null;
18
+ export function queryMarks(
19
+ answer: unknown,
20
+ cards: Set<string> | string[],
21
+ edges: Array<{ from: string; to: string }>,
22
+ ): { cardMarks: Map<string, string>; near: Map<string, string>; unobserved: Set<string>; edgeMarks: Array<string | null>; state: string; litDrawn: number; litTotal: number };
23
+ export function groupMarks(answer: unknown, cards: Set<string> | string[]): { groups: GroupMark[]; cardGroup: Map<string, number>; total: number; by: string };
24
+ export function groupLabel(g: { group: string; count: number }): string;
25
+ export function countsLine(counts: Counts | null | undefined): string;
26
+ export function queryLine(view: Record<string, unknown>, answer: unknown, marks?: unknown): { text: string; tone: string; notSearched: string };
27
+ export function uncapturedLine(q: string, queries: unknown[]): string;
@@ -0,0 +1,213 @@
1
+ import { PLAN_DEPTH_NOTE } from "./shot-frame.js";
2
+
3
+ // behold#913: `q`, a chant search query drawn over the graph.
4
+ //
5
+ // The server runs the query through chant (GET /api/search, src/search.ts)
6
+ // and answers chant's document plus `draw`, the projection of it the page
7
+ // draws: the matched ids, the ids and edges on their paths, the rows a live
8
+ // read could not observe, the near-misses, the provenance line, a failure,
9
+ // and the members chant did not search. This module decides, from that answer
10
+ // and what is on screen, what each card and edge looks like and what the one
11
+ // query line says. No DOM: app.js applies it.
12
+
13
+ /** The read a view's query asks for. The keys are the ones the export captures it under (canonicalKey). */
14
+ export function searchUrl(view) {
15
+ const v = view || {};
16
+ const p = new URLSearchParams();
17
+ if (v.countBy) p.set("countBy", v.countBy); // behold#922
18
+ if (v.env) p.set("env", v.env);
19
+ if (v.plan) p.set("plan", "1"); // behold#922
20
+ p.set("q", v.q || "");
21
+ if (v.env && v.snapshot && !v.plan) p.set("snapshot", v.snapshot);
22
+ return `/api/search?${p}`;
23
+ }
24
+
25
+ /** What identifies one answer: a new query, env, snapshot, grouping or plan is a new read. A grouping alone counts the whole graph. */
26
+ export function searchKey(view) {
27
+ const v = view || {};
28
+ return v.q || v.countBy ? JSON.stringify([v.q || "", v.env || null, (v.env && !v.plan && v.snapshot) || null, v.countBy || null, !!v.plan]) : null;
29
+ }
30
+
31
+ /** behold#922: the colours a group is drawn in, in chant's group order, repeating past the last. */
32
+ export const GROUP_COLOURS = ["#58a6ff", "#f0883e", "#3fb950", "#d2a8ff", "#ff7b72", "#e3b341", "#39c5cf", "#f778ba"];
33
+
34
+ /**
35
+ * A stack card (`attrs._stackOf`, src/stack-lens.ts) stands for the cards it
36
+ * holds, so a match inside it lights the stack. Member id -> the drawn stack
37
+ * card's id, for the stacks among `cards`. chant answers member ids; at the
38
+ * default zoom most of a large estate sits in stacks (found in #908's stage 3
39
+ * run: 180 of terralith-4-stock's 195 resources).
40
+ */
41
+ export function stackIndex(nodes, cards) {
42
+ const drawn = cards instanceof Set ? cards : new Set(cards || []);
43
+ const out = new Map();
44
+ for (const n of nodes || []) {
45
+ const held = n && n.attrs && n.attrs._stackOf;
46
+ if (!Array.isArray(held) || !drawn.has(n.id)) continue;
47
+ for (const m of held) {
48
+ const id = typeof m === "string" ? m : m && m.id;
49
+ if (id) out.set(id, n.id);
50
+ }
51
+ }
52
+ return out;
53
+ }
54
+
55
+ /**
56
+ * behold#922: how a counts answer (chant's `--count-by`, src/search.ts
57
+ * `drawnOf`'s `counts`) is drawn against the cards on screen. One entry per
58
+ * chant group, in chant's order: its name, chant's count, its colour, the ids
59
+ * of its cards that are drawn, and `label`, the first of them, where the
60
+ * group's label goes. `cardGroup` maps each drawn card to its group's index.
61
+ * A group whose cards are all stacked or elided at this zoom has no label
62
+ * card; the line still lists it. Groups behold can't light (an older chant
63
+ * listed no ids) have `ids: null`.
64
+ */
65
+ export function groupMarks(answer, cards, stackOf = new Map()) {
66
+ const drawnIds = cards instanceof Set ? cards : new Set(cards || []);
67
+ const d = (answer && answer.draw) || null;
68
+ const out = { groups: [], cardGroup: new Map(), total: 0, by: "" };
69
+ if (!d || !d.counts) return out;
70
+ out.total = d.counts.total;
71
+ out.by = d.counts.by;
72
+ const labelled = new Set();
73
+ d.counts.groups.forEach((g, i) => {
74
+ // A stack holding cards of several groups takes the first of them, in chant's order.
75
+ const drawn = [...new Set((g.ids || []).map((id) => stackOf.get(id) || id))].filter((id) => drawnIds.has(id));
76
+ for (const id of drawn) if (!out.cardGroup.has(id)) out.cardGroup.set(id, i);
77
+ const label = drawn.find((id) => !labelled.has(id)) || drawn[0] || null;
78
+ if (label) labelled.add(label);
79
+ out.groups.push({ group: g.group, count: g.count, colour: GROUP_COLOURS[i % GROUP_COLOURS.length], drawn, label, ids: g.ids });
80
+ });
81
+ return out;
82
+ }
83
+
84
+ /** behold#922: the label a group's first card wears: its name and chant's count. */
85
+ export function groupLabel(g) {
86
+ return `${one(g.group)} · ${g.count}`;
87
+ }
88
+
89
+ /** behold#922: the line's account of a counts answer: each group and its count in chant's order, then the total. */
90
+ export function countsLine(counts) {
91
+ if (!counts) return "";
92
+ const shown = counts.groups.slice(0, 12).map((g) => `${one(g.group)} ${g.count}`);
93
+ const more = counts.groups.length > 12 ? `, and ${counts.groups.length - 12} more` : "";
94
+ const noIds = counts.groups.some((g) => !g.ids) ? "; this chant lists no ids per group, so no group is lit (chant 0.124.46 does)" : "";
95
+ return `${counts.groups.length} group${counts.groups.length === 1 ? "" : "s"} by ${one(counts.by)}: ${shown.join(", ")}${more} · ${counts.total} total${noIds}`;
96
+ }
97
+
98
+ const one = (s) => String(s == null ? "" : s).replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
99
+
100
+ /**
101
+ * How the page draws one answer, against what is on screen. `cards` is the
102
+ * set of drawn card ids, `edges` the drawn edges as `{from, to}`.
103
+ *
104
+ * `cardMarks`: id -> "lit" | "path" | "dim" (every drawn card gets one, or
105
+ * none when nothing is to be dimmed: a grammar error or a refusal). `near`:
106
+ * id -> the term it fails, for the no-matches view. `unobserved`: the lit ids
107
+ * a live read could not observe. `edgeMarks`: one entry per drawn edge, in
108
+ * order: "path" (a hop on a match's path), "lit" (both ends lit), or "dim".
109
+ * `state`: drawn | no-matches | failed | refused, as the shot reports it.
110
+ */
111
+ export function queryMarks(answer, cards, edges, stackOf = new Map()) {
112
+ const drawnIds = cards instanceof Set ? cards : new Set(cards || []);
113
+ const edgeList = edges || [];
114
+ const a = answer || {};
115
+ const d = a.draw || null;
116
+ const out = { cardMarks: new Map(), near: new Map(), unobserved: new Set(), edgeMarks: edgeList.map(() => null), state: "refused", litDrawn: 0, litTotal: 0 };
117
+ if (!d) return out; // a refusal: nothing lit, nothing dimmed
118
+ if (d.failure && d.failure.kind === "query") {
119
+ out.state = "failed";
120
+ return out; // chant refused the query: nothing lit and nothing dimmed
121
+ }
122
+ // A match inside a drawn stack lights the stack (stackIndex).
123
+ const card = (id) => stackOf.get(id) || id;
124
+ const litIds = d.lit || [];
125
+ const lit = new Set(litIds.map(card));
126
+ const onPath = new Set((d.onPath || []).map(card).filter((id) => !lit.has(id)));
127
+ out.litTotal = new Set(litIds).size;
128
+ for (const id of drawnIds) out.cardMarks.set(id, lit.has(id) ? "lit" : onPath.has(id) ? "path" : "dim");
129
+ out.litDrawn = new Set(litIds.filter((id) => drawnIds.has(card(id)))).size;
130
+ for (const id of Object.keys(d.unobserved || {})) if (drawnIds.has(card(id))) out.unobserved.add(card(id));
131
+ const hops = new Set();
132
+ for (const h of d.edges || []) {
133
+ const from = card(h.from);
134
+ const to = card(h.to);
135
+ hops.add(`${from}\u0000${to}`);
136
+ hops.add(`${to}\u0000${from}`); // behold may draw the edge the other way round
137
+ }
138
+ out.edgeMarks = edgeList.map((e) => {
139
+ if (hops.has(`${e.from}\u0000${e.to}`)) return "path";
140
+ if (lit.has(e.from) && lit.has(e.to)) return "lit";
141
+ return "dim";
142
+ });
143
+ if (!lit.size) for (const n of d.nearMisses || []) if (drawnIds.has(card(n.id))) out.near.set(card(n.id), n.fails);
144
+ out.state = d.failure ? "failed" : lit.size || (d.counts && d.counts.total) ? "drawn" : "no-matches";
145
+ return out;
146
+ }
147
+
148
+ /** The universe count `--explain` gives, summed over the plain or the workspace form. */
149
+ function universe(doc) {
150
+ const sum = { matched: 0, of: 0, seen: false };
151
+ const add = (ex) => {
152
+ const u = ex && ex.universe;
153
+ if (u && typeof u.matched === "number" && typeof u.of === "number") {
154
+ sum.matched += u.matched;
155
+ sum.of += u.of;
156
+ sum.seen = true;
157
+ }
158
+ };
159
+ if (doc) {
160
+ add(doc.explain);
161
+ for (const m of Array.isArray(doc.members) ? doc.members : []) add(m && m.explain);
162
+ }
163
+ return sum.seen ? sum : null;
164
+ }
165
+
166
+ /**
167
+ * The one line the view shows for a query: what was asked, what came back,
168
+ * and chant's provenance. `{text, tone, notSearched}`: tone is "ok",
169
+ * "empty" or "failed"; notSearched is a second line naming the members chant
170
+ * did not search, or "".
171
+ */
172
+ export function queryLine(view, answer, marks) {
173
+ const q = view && view.q ? `"${one(view.q)}"` : "the whole graph";
174
+ const a = answer || {};
175
+ const d = a.draw;
176
+ if (!d) {
177
+ // A refusal (an old chant, a loose estate, an export that didn't capture this query) or a failed request.
178
+ return { text: `${q} not searched: ${one(a.error || "the search failed")}${a.remedy ? ` ${one(a.remedy)}` : ""}`, tone: "failed", notSearched: "" };
179
+ }
180
+ const notSearched = (d.notSearched || []).length
181
+ ? `not searched: ${d.notSearched.map((m) => `${one(m.member)} (${one(m.code || m.status)}${m.message ? `: ${one(m.message)}` : ""})`).join("; ")}`
182
+ : "";
183
+ if (d.failure && d.failure.kind === "query") {
184
+ return { text: `${q} was refused by chant: ${one(d.failure.message)}${d.failure.hint ? `. ${one(d.failure.hint)}` : ""}`, tone: "failed", notSearched };
185
+ }
186
+ const prov = d.provenance ? one(d.provenance) : "";
187
+ const m = marks || queryMarks(answer, [], []);
188
+ const parts = [];
189
+ if (d.failure && d.failure.kind === "live") parts.push(one(d.failure.message));
190
+ if (d.counts) {
191
+ // behold#922: chant's groups and total, and how many lit cards are drawn at this zoom.
192
+ const hidden = (d.lit || []).length - m.litDrawn;
193
+ parts.push(`${q}: ${countsLine(d.counts)}${hidden > 0 ? `; ${hidden} not drawn at this zoom` : ""}`);
194
+ } else if (!(d.lit || []).length) {
195
+ const u = universe(a.document);
196
+ parts.push(`no matches for ${q}${u ? `, 0 of ${u.of} nodes` : ""}${m.near.size ? `; near misses outlined (${m.near.size})` : ""}`);
197
+ } else {
198
+ const n = d.lit.length;
199
+ const hidden = n - m.litDrawn;
200
+ parts.push(`${q}: ${n} match${n === 1 ? "" : "es"}${hidden > 0 ? `, ${hidden} not drawn at this zoom` : ""}${(d.edges || []).length ? `, path edges drawn` : ""}`);
201
+ }
202
+ if (prov) parts.push(prov);
203
+ if (view && view.plan) parts.push(PLAN_DEPTH_NOTE);
204
+ const tone = d.failure ? "failed" : (d.lit || []).length || (d.counts && d.counts.total) ? "ok" : "empty";
205
+ return { text: parts.join(" · "), tone, notSearched };
206
+ }
207
+
208
+ /** The line a static export shows for a query it didn't capture. Lights nothing. */
209
+ export function uncapturedLine(q, queries) {
210
+ const list = (queries || []).filter((x) => typeof x === "string");
211
+ if (!list.length) return `"${one(q)}" not searched: this export captured no queries (behold export --q "<query>" captures one).`;
212
+ return `"${one(q)}" not searched: this export answers ${list.length} captured quer${list.length === 1 ? "y" : "ies"}, and this is not one of them: ${list.map((x) => `"${one(x)}"`).join(", ")}.`;
213
+ }