@intentius/behold 0.30.1 → 0.31.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 (129) hide show
  1. package/AGENTS.md +475 -16
  2. package/README.md +25 -19
  3. package/demos.json +14 -9
  4. package/dist/cli.js +54900 -26771
  5. package/example-carve/README.md +19 -23
  6. package/example-carve/app/package.json +1 -1
  7. package/example-carve/app/src/carved.ts +3 -3
  8. package/example-carve/carve-report.json +1 -1
  9. package/example-carve/{legacy-tf → tf-root}/terraform.tfstate +1 -1
  10. package/example-choudoufu-estate/README.md +7 -0
  11. package/example-choudoufu-estate/chant.workspace.json +1 -1
  12. package/example-choudoufu-estate/scripts/choudoufu-down.sh +2 -1
  13. package/example-choudoufu-estate/scripts/choudoufu-up.sh +10 -3
  14. package/example-terraform-estate/README.md +32 -5
  15. package/example-terraform-estate/chant.workspace.json +1 -1
  16. package/example-terraform-estate/recorded/adoption/platform.json +72 -0
  17. package/example-terraform-estate/recorded/adoption/prod.json +224 -0
  18. package/example-terralith/README.md +1 -1
  19. package/example-three-cloud/README.md +111 -18
  20. package/example-three-cloud/aws/Pulumi.yaml +15 -0
  21. package/example-three-cloud/aws/index.ts +174 -0
  22. package/example-three-cloud/aws/package-lock.json +2725 -0
  23. package/example-three-cloud/aws/package.json +14 -0
  24. package/example-three-cloud/aws/tsconfig.json +17 -0
  25. package/example-three-cloud/azure/main.tf +48 -0
  26. package/example-three-cloud/azure/site.tf +104 -0
  27. package/example-three-cloud/chant.config.json +9 -0
  28. package/example-three-cloud/chant.workspace.json +30 -4
  29. package/example-three-cloud/dns/chant.config.ts +26 -1
  30. package/example-three-cloud/dns/src/records.component.ts +32 -6
  31. package/example-three-cloud/package-lock.json +48 -27
  32. package/example-three-cloud/package.json +8 -6
  33. package/example-three-cloud/scripts/emulators-up.sh +28 -1
  34. package/example-three-cloud/scripts/front-door.ts +679 -86
  35. package/package.json +13 -6
  36. package/web/adopt-pulumi.js +114 -0
  37. package/web/adopt-pulumi.test.js +28 -0
  38. package/web/adopt.js +203 -0
  39. package/web/adopt.test.js +27 -0
  40. package/web/app.js +614 -19
  41. package/web/carve-steps.js +1 -1
  42. package/web/carve-steps.test.js +2 -2
  43. package/web/change-set-overlay.js +12 -5
  44. package/web/change-set-overlay.test.js +22 -0
  45. package/web/drift-stream.js +241 -0
  46. package/web/drift-stream.test.js +146 -0
  47. package/web/edge-weight.d.ts +1 -1
  48. package/web/edge-weight.js +5 -1
  49. package/web/edge-weight.test.js +19 -0
  50. package/web/embed.js +2 -2
  51. package/web/event-help-modal.js +18 -12
  52. package/web/event-help-modal.test.js +28 -1
  53. package/web/graph-query.js +180 -0
  54. package/web/graph-query.test.js +49 -0
  55. package/web/graph.html +107 -0
  56. package/web/index-diff.js +109 -0
  57. package/web/index-diff.test.js +39 -0
  58. package/web/index.html +55 -0
  59. package/web/kiosk-ask-layout.js +85 -0
  60. package/web/kiosk-ask-layout.test.js +83 -0
  61. package/web/kiosk-ask-tips.js +477 -0
  62. package/web/kiosk-ask-tips.test.js +372 -0
  63. package/web/kiosk-ask.js +774 -0
  64. package/web/kiosk-ask.test.js +593 -0
  65. package/web/kiosk-banner.js +108 -0
  66. package/web/kiosk-banner.test.js +72 -0
  67. package/web/kiosk-center-cards.test.js +110 -0
  68. package/web/kiosk-estate-scene.js +267 -0
  69. package/web/kiosk-estate-scene.test.js +21 -0
  70. package/web/kiosk-event-help.js +4 -1
  71. package/web/kiosk-graph-pane.js +63 -0
  72. package/web/kiosk-graph-pane.test.js +105 -0
  73. package/web/kiosk-light-frame.js +197 -0
  74. package/web/kiosk-light.js +547 -0
  75. package/web/kiosk-light.test.js +297 -0
  76. package/web/kiosk-member-kind.test.js +140 -0
  77. package/web/kiosk-metrics.js +7 -4
  78. package/web/kiosk-modal-sticky.test.js +2 -1
  79. package/web/kiosk-popover.js +4 -1
  80. package/web/kiosk-refit.test.js +81 -0
  81. package/web/kiosk-reset.js +49 -0
  82. package/web/kiosk-reset.test.js +11 -0
  83. package/web/kiosk-shot.js +40 -2
  84. package/web/kiosk-shot.test.js +23 -1
  85. package/web/kiosk-side.js +296 -0
  86. package/web/kiosk-side.test.js +249 -0
  87. package/web/kiosk-vendor.js +85 -7
  88. package/web/kiosk-vendor.test.js +9 -9
  89. package/web/kiosk-watch.js +20 -4
  90. package/web/kiosk-watch.test.js +15 -1
  91. package/web/kiosk.html +153 -1
  92. package/web/kiosk.js +252 -27
  93. package/web/kiosk.test.js +25 -1
  94. package/web/member-kind.js +31 -0
  95. package/web/small-stage.test.js +4 -0
  96. package/web/template-apps.js +245 -0
  97. package/web/template-apps.test.js +252 -0
  98. package/web/templates.js +285 -0
  99. package/web/templates.test.js +155 -0
  100. package/web/terragucci-change.js +30 -13
  101. package/web/terragucci-lifecycle.js +112 -62
  102. package/web/terragucci-lifecycle.test.js +29 -1
  103. package/web/terragucci-timeline.js +39 -2
  104. package/web/terragucci-timeline.test.js +42 -1
  105. package/web/tool-mark.js +4 -4
  106. package/web/tool-mark.test.js +1 -1
  107. package/web/vendors/atmos.svg +1 -0
  108. package/web/vendors/chant.svg +1 -0
  109. package/web/vendors/choudoufu.svg +1 -0
  110. package/web/vendors/terragrunt.svg +9 -0
  111. package/web/vendors/terragucci.svg +1 -0
  112. package/example-three-cloud/aws/chant.config.ts +0 -8
  113. package/example-three-cloud/aws/site.component.ts +0 -13
  114. package/example-three-cloud/aws/src/site.ts +0 -27
  115. package/example-three-cloud/azure/chant.config.ts +0 -1
  116. package/example-three-cloud/azure/src/site.component.ts +0 -13
  117. package/example-three-cloud/azure/src/site.ts +0 -18
  118. package/web/vendors/choudoufu-128.png +0 -0
  119. package/web/vendors/choudoufu-64.png +0 -0
  120. /package/example-carve/{legacy-tf → tf-root}/cdn.tf +0 -0
  121. /package/example-carve/{legacy-tf → tf-root}/compute.tf +0 -0
  122. /package/example-carve/{legacy-tf → tf-root}/floci-override.tf.disabled +0 -0
  123. /package/example-carve/{legacy-tf → tf-root}/modules/cdn/main.tf +0 -0
  124. /package/example-carve/{legacy-tf → tf-root}/naming.tf +0 -0
  125. /package/example-carve/{legacy-tf → tf-root}/network.tf +0 -0
  126. /package/example-carve/{legacy-tf → tf-root}/observability.tf +0 -0
  127. /package/example-carve/{legacy-tf → tf-root}/outputs.tf +0 -0
  128. /package/example-carve/{legacy-tf → tf-root}/storage.tf +0 -0
  129. /package/example-carve/{legacy-tf → tf-root}/versions.tf +0 -0
@@ -0,0 +1,85 @@
1
+ // behold#940: where ask mode puts the roots. The graph's own layout packs the
2
+ // roots in one row, which at 1920x1080 leaves the cards small. Here the roots
3
+ // are stacked, upstream on top, and each root's cards wrap into as many columns
4
+ // as make the whole stack fill the room best. Pure: sizes in, positions out.
5
+ // web/app.js applies the positions to the drawn graph (layout deltas), and
6
+ // web/kiosk-estate-scene.js draws a scene at them.
7
+
8
+ export const PAD = 18;
9
+ /** The room a root's title takes at the top of its box. */
10
+ export const TITLE = 36;
11
+ /** Between cards of a box. */
12
+ export const GAP = 18;
13
+ /** Between boxes: room for the state label under each. */
14
+ export const BOX_GAP = 56;
15
+
16
+ /**
17
+ * Upstream first. `edges` are `{from, to}` (from is read by to); a root
18
+ * nothing orders keeps its place. A cycle falls back to the given order.
19
+ */
20
+ export function orderRoots(paths, edges = []) {
21
+ const left = [...paths];
22
+ const out = [];
23
+ while (left.length) {
24
+ const ready = left.find((p) => !edges.some((e) => e.to === p && e.from !== p && left.includes(e.from)));
25
+ const next = ready === undefined ? left[0] : ready;
26
+ out.push(next);
27
+ left.splice(left.indexOf(next), 1);
28
+ }
29
+ return out;
30
+ }
31
+
32
+ /**
33
+ * The stack's positions.
34
+ *
35
+ * `roots`: in order, each `{ id, cards: [{ id, w, h }] }`; a card's `h` counts what hangs under it (its slots).
36
+ * `open`: the room the stack should fill, `{ width, height }` in any one unit (only the ratio is used).
37
+ * Returns `{ cols, scale, width, height, boxes, cards }`: `boxes[id]` and `cards[id]` are `{ x, y, w, h }` with the
38
+ * stack's top left at 0,0; `scale` is how much the stack grows to fill `open`.
39
+ */
40
+ export function askLayout(roots, open) {
41
+ const list = roots.filter((r) => r && r.cards && r.cards.length);
42
+ if (!list.length) return { cols: 0, scale: 1, width: 0, height: 0, boxes: {}, cards: {} };
43
+ const cw = Math.max(...list.flatMap((r) => r.cards.map((c) => c.w)));
44
+ const most = Math.max(...list.map((r) => r.cards.length));
45
+ const rowH = list.map((r) => Math.max(...r.cards.map((c) => c.h)));
46
+ const room = open && open.width > 0 && open.height > 0 ? open : { width: 16, height: 9 };
47
+ const shape = (cols) => {
48
+ let width = 0;
49
+ let height = 0;
50
+ list.forEach((r, i) => {
51
+ const used = Math.min(cols, r.cards.length);
52
+ const rows = Math.ceil(r.cards.length / cols);
53
+ const w = used * cw + (used - 1) * GAP + 2 * PAD;
54
+ const h = TITLE + rows * rowH[i] + (rows - 1) * GAP + PAD;
55
+ width = Math.max(width, w);
56
+ height += h + (i ? BOX_GAP : 0);
57
+ });
58
+ return { width, height, scale: Math.min(room.width / width, room.height / height) };
59
+ };
60
+ let best = { cols: 1, ...shape(1) };
61
+ for (let cols = 2; cols <= most; cols++) {
62
+ const s = shape(cols);
63
+ // A wider stack only when it is a clear gain: ties keep the narrower one.
64
+ if (s.scale > best.scale * 1.02) best = { cols, ...s };
65
+ }
66
+ const boxes = {};
67
+ const cards = {};
68
+ let y = 0;
69
+ list.forEach((r, i) => {
70
+ const used = Math.min(best.cols, r.cards.length);
71
+ const rows = Math.ceil(r.cards.length / best.cols);
72
+ const w = used * cw + (used - 1) * GAP + 2 * PAD;
73
+ const h = TITLE + rows * rowH[i] + (rows - 1) * GAP + PAD;
74
+ // Each box is centred on the widest one, so a stack of unequal boxes does not hug the left edge.
75
+ const x0 = Math.round((best.width - w) / 2);
76
+ boxes[r.id] = { x: x0, y, w, h };
77
+ r.cards.forEach((c, k) => {
78
+ const col = k % best.cols;
79
+ const row = Math.floor(k / best.cols);
80
+ cards[c.id] = { x: x0 + PAD + col * (cw + GAP), y: y + TITLE + row * (rowH[i] + GAP), w: c.w, h: c.h };
81
+ });
82
+ y += h + BOX_GAP;
83
+ });
84
+ return { cols: best.cols, scale: best.scale, width: best.width, height: best.height, boxes, cards };
85
+ }
@@ -0,0 +1,83 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { BOX_GAP, PAD, TITLE, askLayout, orderRoots } from "./kiosk-ask-layout.js";
3
+ import { askDeltas } from "./kiosk-estate-scene.js";
4
+
5
+ const card = (id, w = 200, h = 64) => ({ id, w, h });
6
+
7
+ describe("ask mode's stack of roots (behold#940)", () => {
8
+ it("puts upstream first, and keeps the given order where nothing orders it", () => {
9
+ expect(orderRoots(["edge", "app", "network"], [{ from: "network", to: "app" }, { from: "app", to: "edge" }])).toEqual(["network", "app", "edge"]);
10
+ expect(orderRoots(["b", "a", "c"], [])).toEqual(["b", "a", "c"]);
11
+ // A cycle does not hang: the given order.
12
+ expect(orderRoots(["a", "b"], [{ from: "a", to: "b" }, { from: "b", to: "a" }])).toEqual(["a", "b"]);
13
+ });
14
+
15
+ it("stacks the roots in order, each box holding its cards", () => {
16
+ const l = askLayout([{ id: "n", cards: [card("n1"), card("n2")] }, { id: "a", cards: [card("a1"), card("a2"), card("a3")] }], { width: 1920, height: 760 });
17
+ expect(l.boxes.n.y).toBe(0);
18
+ expect(l.boxes.a.y).toBeGreaterThan(l.boxes.n.y + l.boxes.n.h);
19
+ for (const [id, box] of [["n1", "n"], ["a3", "a"]]) {
20
+ const c = l.cards[id];
21
+ const b = l.boxes[box];
22
+ expect(c.x).toBeGreaterThanOrEqual(b.x + PAD);
23
+ expect(c.x + c.w).toBeLessThanOrEqual(b.x + b.w);
24
+ expect(c.y).toBeGreaterThanOrEqual(b.y + TITLE);
25
+ expect(c.y + c.h).toBeLessThanOrEqual(b.y + b.h);
26
+ }
27
+ });
28
+
29
+ it("uses the height of a 1920x1080 screen: three roots of 3, 6 and 3 cards do not sit in one row", () => {
30
+ const roots = [{ id: "n", cards: ["a", "b", "c"].map((k) => card(`n${k}`)) }, { id: "a", cards: ["a", "b", "c", "d", "e", "f"].map((k) => card(`a${k}`, 200, 110)) }, { id: "e", cards: ["a", "b", "c"].map((k) => card(`e${k}`)) }];
31
+ const room = { width: 1920, height: 740 };
32
+ const stacked = askLayout(roots, room);
33
+ // The graph's own layout: the roots side by side in one row.
34
+ const oneRow = 12 * 218 + 3 * 2 * PAD + 2 * BOX_GAP;
35
+ const rowScale = Math.min(room.width / oneRow, room.height / (TITLE + 110 + PAD));
36
+ expect(stacked.scale).toBeGreaterThan(rowScale * 1.5);
37
+ expect(stacked.height).toBeGreaterThan(stacked.width / 4);
38
+ // Every box is as wide as its cards need, and the stack fits the room's shape.
39
+ expect(stacked.width * stacked.scale).toBeLessThanOrEqual(room.width + 0.5);
40
+ expect(stacked.height * stacked.scale).toBeLessThanOrEqual(room.height + 0.5);
41
+ });
42
+
43
+ it("wraps into columns only when it gains", () => {
44
+ const one = askLayout([{ id: "a", cards: [card("a")] }], { width: 1000, height: 1000 });
45
+ expect(one.cols).toBe(1);
46
+ const tall = askLayout([{ id: "a", cards: Array.from({ length: 8 }, (_, i) => card(`c${i}`)) }], { width: 1900, height: 300 });
47
+ expect(tall.cols).toBeGreaterThan(3);
48
+ });
49
+
50
+ it("leaves room under a card for what hangs from it", () => {
51
+ const l = askLayout([{ id: "a", cards: [card("x", 200, 64 + 66), card("y", 200, 64)] }], { width: 400, height: 1000 });
52
+ // One column: the second card starts below the first's slots.
53
+ expect(l.cols).toBe(1);
54
+ expect(l.cards.y.y).toBeGreaterThanOrEqual(l.cards.x.y + 130);
55
+ });
56
+ });
57
+
58
+ describe("the deltas that stack the drawn graph (behold#940)", () => {
59
+ const roots = [{ member: "m", name: "app", path: "app" }, { member: "m", name: "network", path: "network" }];
60
+ const nodes = new Map([
61
+ ["m/app/a", { rect: { x: 400, y: 100, w: 150, h: 60 } }],
62
+ ["m/app/b", { rect: { x: 560, y: 100, w: 150, h: 60 } }],
63
+ ["m/network/n", { rect: { x: 40, y: 100, w: 150, h: 60 } }],
64
+ ["stray", { rect: { x: 0, y: 0, w: 10, h: 10 } }],
65
+ ]);
66
+ const boxes = new Map([["box:app", { x: 380, y: 60, w0: 350, h0: 120 }], ["box:network", { x: 20, y: 60, w0: 190, h0: 120 }]]);
67
+
68
+ it("moves each root below the one it reads, and each card into its box", () => {
69
+ const got = askDeltas({ roots, nodes, boxes, edges: [{ from: "network", to: "app" }], open: { width: 800, height: 600 } });
70
+ const at = (id, base) => ({ x: base.x + got.deltas[id].dx, y: base.y + got.deltas[id].dy });
71
+ const net = { ...at("box:network", boxes.get("box:network")), w: boxes.get("box:network").w0 + got.deltas["box:network"].dw };
72
+ const app = at("box:app", boxes.get("box:app"));
73
+ expect(net.y).toBeLessThan(app.y);
74
+ const n = at("m/network/n", nodes.get("m/network/n").rect);
75
+ expect(n.x).toBeGreaterThanOrEqual(net.x);
76
+ expect(n.y).toBeGreaterThan(net.y);
77
+ expect(got.deltas.stray).toBeUndefined();
78
+ });
79
+
80
+ it("is null when no root has a box and cards", () => {
81
+ expect(askDeltas({ roots, nodes: new Map(), boxes, open: { width: 1, height: 1 } })).toBeNull();
82
+ });
83
+ });
@@ -0,0 +1,477 @@
1
+ /**
2
+ * The prompt demo's tip cards. The terminal (web/kiosk-ask.js) tells the story; a tip is a short aside that shows only
3
+ * while the terminal has nothing new to say, and gives way the moment it does.
4
+ *
5
+ * The timing is a pure sequencer ({@link createTipSequencer}), tested with fake timers:
6
+ * - a tip may show only while a busy line has been running at least {@link TIP_WAIT_MS} (an apply wait), with no
7
+ * typing and no reply, and not when the line is due to end (`until`: its reply, the next beat, the driver's
8
+ * `next.at`) before the tip could be read; the pane says when a busy line starts or ends (`behold:ask-busy`) and when any new line
9
+ * starts (`behold:ask-line`: a typed prompt, a reply, a busy line, the ready light);
10
+ * - any such terminal event takes an open tip down at once, and no tip starts in the {@link TIP_QUIET_MS} after one;
11
+ * - at most two tips per act (a scenario of a cycle), never at once: the step's own tips, else the act's built-in
12
+ * ones ({@link actTips}). The second needs its own qualifying wait, or what is left of the same wait once the first
13
+ * has held and a quiet gap has passed;
14
+ * - a tip stays its reading time ({@link holdMs}) while the wait lasts, then goes; a tip with a link holds still while
15
+ * it is hovered or focused ({@link LINK_RESUME_MS} left at least on leaving).
16
+ *
17
+ * The card is compact and quiet, docked in a corner of the graph area that no lit box is in (the frame reports where
18
+ * its lit cards are, `behold:lit-rects`), never over the prompt. When no corner is clear, or on a phone, no tip shows.
19
+ */
20
+ import { modalStyle, openEventModal } from "./event-help-modal.js";
21
+
22
+ /** A tip waits for the busy line to have run this long. */
23
+ export const TIP_WAIT_MS = 6_000;
24
+ /** No tip starts this soon after a terminal event. */
25
+ export const TIP_QUIET_MS = 2_000;
26
+ /** A card stays at least this long while the wait lasts; a longer one stays its reading time ({@link holdMs}). */
27
+ export const TIP_MIN_MS = 8_000;
28
+ /** A card fades out in this long. */
29
+ export const TIP_FADE_MS = 150;
30
+ /** A card with a link, left after a hover or focus, has at least this long still to show. */
31
+ export const LINK_RESUME_MS = 3_000;
32
+
33
+ /**
34
+ * A tip's link, or null: only an https URL on intentius.io (or a subdomain) or under github.com/INTENTIUS, with a
35
+ * non-empty label (the default is "Read how"). Anything else is dropped.
36
+ */
37
+ export function safeLink(l) {
38
+ if (!l || typeof l.url !== "string") return null;
39
+ let u;
40
+ try {
41
+ u = new URL(l.url);
42
+ } catch {
43
+ return null;
44
+ }
45
+ if (u.protocol !== "https:" || u.username || u.password || u.port) return null;
46
+ const host = u.hostname.toLowerCase();
47
+ const ok = host === "intentius.io" || host.endsWith(".intentius.io") || (host === "github.com" && (u.pathname === "/INTENTIUS" || u.pathname.startsWith("/INTENTIUS/")));
48
+ if (!ok) return null;
49
+ const label = typeof l.label === "string" && l.label.trim() ? l.label.trim() : "Read how";
50
+ return { label, url: u.href };
51
+ }
52
+
53
+ /**
54
+ * What a busy step with no tips of its own shows, in order: the viewer's takeaways, then where to look next. Minimal
55
+ * and positive, and each linted clean on its own at strictness 3 with the sentences package's destink linter.
56
+ */
57
+ export const DEFAULT_TIPS = [
58
+ { title: "All at once", body: "Every estate plans together. The plan marks where the new subnet's id goes, and the same apply fills it in. With separate state runs, a downstream root sees that id only after its upstream applies.", link: { label: "How it plans across estates", url: "https://intentius.io/choudoufu/how-it-works/across-estates/" } },
59
+ { title: "terragucci", body: "terragucci is CI pipelines for Terraform. Here it puts all three estates into one plan and one apply.", link: { label: "How a composed run works", url: "https://intentius.io/terragucci/concepts/waves-and-approvals/#composed-estates" } },
60
+ { title: "choudoufu", body: "choudoufu is a fork of OpenTofu. A root that calls your estates as modules plans and applies them in one pass, and each estate keeps its own records. Resource-level locking at the cloud level.", link: { label: "How the locking works", url: "https://intentius.io/choudoufu/how-it-works/locking/" } },
61
+ { title: "Free, nothing to host", body: "Both are free and open source. There is no server or database to host. Everything runs in CI pipelines.", link: { label: "choudoufu on GitHub", url: "https://github.com/INTENTIUS/choudoufu" } },
62
+ { title: "Inspect", body: "Open Inspect to explore every resource and the plan behind it." },
63
+ ];
64
+ /**
65
+ * The free card for the Terragrunt and Atmos demos, which have no terragucci in them: it names choudoufu alone.
66
+ * Linted alone at strictness 3.
67
+ */
68
+ export const PLAIN_FREE_TIP = { title: "Free, nothing to host", body: "choudoufu is free and open source. There is no server or database to host. It runs in the CI pipeline you already have.", link: { label: "choudoufu on GitHub", url: "https://github.com/INTENTIUS/choudoufu" } };
69
+ /**
70
+ * The Terragrunt and Atmos demos run their own tool's plain workflow with choudoufu as the binary: no terragucci in
71
+ * them. Each has its own known-after-apply card, since the two apply differently: Terragrunt in one apply, Atmos one
72
+ * component at a time. Each body was linted alone at strictness 3.
73
+ */
74
+ export const TERRAGRUNT_TIP = { title: "Known after apply", body: "Terragrunt plans a unit whose upstream isn't applied yet with mock outputs. With choudoufu, the plan shows the real subnet id as known after apply. One apply fills it in.", link: { label: "Terragrunt's saved plans", url: "https://docs.terragrunt.com/features/stacks/run-queue/#saving-opentofuterraform-plan-output" } };
75
+ export const ATMOS_TIP = { title: "Known after apply", body: "Atmos plans each component against its upstream's last applied outputs, or a mock default. With choudoufu, one plan covers every component. The merge applies each one exactly as reviewed.", link: { label: "Atmos terraform.output", url: "https://atmos.tools/functions/yaml/terraform.output" } };
76
+
77
+ /**
78
+ * The chant demo runs chant's own pull-request pipeline on three CloudFormation stacks: no terragucci and no choudoufu in
79
+ * it. Each body was linted alone at strictness 3 and its claims checked against chant's guide (pull-request-ci,
80
+ * apply-on-merge "A round the first approval covers").
81
+ */
82
+ export const CHANT_TIPS = [
83
+ { title: "One plan, one note", body: "chant plans every stack a pull request changes in one pass and posts one note with one digest. A reviewer approves that digest once.", link: { label: "Generated CI for pull requests", url: "https://intentius.io/chant/guide/pull-request-ci/" } },
84
+ { title: "Known after apply", body: "A stack that reads a new subnet's id is planned with a stand-in for it. The note marks what the stand-in drives as known after apply, and no stand-in is shown as a value.", link: { label: "How CloudFormation stacks are planned", url: "https://intentius.io/chant/guide/pull-request-ci/#cloudformation-stacks" } },
85
+ { title: "One approval", body: "When network has applied, chant plans the other two stacks again. The first approval covers that plan if it only fills in what the preview marked unknown.", link: { label: "How a round is covered", url: "https://intentius.io/chant/guide/apply-on-merge/#a-round-the-first-approval-covers" } },
86
+ { title: "Parameters, not exports", body: "A stack reads another stack's output through a stackOutput input, which chant fills in as a CloudFormation parameter. No exports are involved." },
87
+ { title: "Free, nothing to host", body: "chant is open source under Apache 2.0. The pull request pipeline is a workflow file chant generates for your forge, and it runs in the CI you already have.", link: { label: "chant on GitHub", url: "https://github.com/INTENTIUS/chant" } },
88
+ DEFAULT_TIPS[4],
89
+ ];
90
+
91
+ /** Whether a scenario belongs to the chant demo (chant-compose-edit, chant-compose-create). */
92
+ export const chantScenario = (scenario) => typeof scenario === "string" && /^chant-compose-/.test(scenario);
93
+
94
+ /** Whether a scenario belongs to a plain-workflow demo (Terragrunt or Atmos on choudoufu). */
95
+ export const plainScenario = (scenario) => typeof scenario === "string" && /^(terragrunt|atmos)-/.test(scenario);
96
+
97
+
98
+ /** Whether a scenario is a create act (a new resource whose id is known only after apply). */
99
+ export const createScenario = (scenario) => typeof scenario === "string" && /create/.test(scenario);
100
+
101
+ /**
102
+ * The first built-in tip of an act. A create act gets the known-after-apply card (the Terragrunt and Atmos demos their
103
+ * own); any other act gets the card that says what the tool is (choudoufu's, or chant's "One plan, one note"). The rest of the cards are not shown in the prompt demo: terragucci's, and chant's "One approval",
104
+ * "Parameters, not exports" and "Free, nothing to host". See {@link actTips} for the second card.
105
+ */
106
+ export function actTip(scenario) {
107
+ const create = createScenario(scenario);
108
+ if (chantScenario(scenario)) return create ? CHANT_TIPS[1] : CHANT_TIPS[0];
109
+ if (create && /^terragrunt-/.test(scenario)) return TERRAGRUNT_TIP;
110
+ if (create && /^atmos-/.test(scenario)) return ATMOS_TIP;
111
+ return create ? DEFAULT_TIPS[0] : DEFAULT_TIPS[2];
112
+ }
113
+
114
+ /**
115
+ * The built-in tips of an act, in order, at most two: {@link actTip}, then for an edit act "Free, nothing to host"
116
+ * (choudoufu alone on the Terragrunt and Atmos demos), for a create act "Inspect". The chant demo has just its one.
117
+ */
118
+ export function actTips(scenario) {
119
+ const first = actTip(scenario);
120
+ if (chantScenario(scenario)) return [first];
121
+ if (createScenario(scenario)) return [first, DEFAULT_TIPS[4]];
122
+ return [first, plainScenario(scenario) ? PLAIN_FREE_TIP : DEFAULT_TIPS[3]];
123
+ }
124
+
125
+ /** The act a busy line belongs to: one scenario of one cycle. */
126
+ export const actKey = (d) => (d ? `${d.cycle}|${d.scenario}` : null);
127
+
128
+ /** The phone layout's width (web/kiosk.html, ask mode): no tips there, the graph and the prompt have the screen. */
129
+ const PHONE = "(max-width: 700px)";
130
+
131
+ export const validTips = (v) =>
132
+ Array.isArray(v)
133
+ ? v
134
+ .map((t) => (typeof t === "string" ? { body: t } : t))
135
+ .filter((t) => t && typeof t.body === "string" && t.body.trim() && (t.title === undefined || t.title === null || typeof t.title === "string"))
136
+ .map((t) => {
137
+ const { link, title, ...rest } = t;
138
+ const ok = safeLink(link);
139
+ return { ...rest, ...(title ? { title } : {}), ...(ok ? { link: ok } : {}) };
140
+ })
141
+ : [];
142
+
143
+ /**
144
+ * `show(tip)` puts a card up and returns false when there is no room for it (nothing shown; the act keeps its tip for
145
+ * a later wait). `hide()` takes it down. `enabled()` is the Tips switch. `pick(detail)` is the act's built-in tips (a tip or a list of them).
146
+ * `busy(detail)` takes a `behold:ask-busy` detail, `line()` a `behold:ask-line`; `dismiss()`: the viewer closed it.
147
+ */
148
+ export function createTipSequencer({ show, hide, enabled = () => true, pick = (d) => actTips(d && d.scenario), waitMs = TIP_WAIT_MS, quietMs = TIP_QUIET_MS, minMs = TIP_MIN_MS, setTimer = setTimeout, clearTimer = clearTimeout, now = Date.now }) {
149
+ let id = null;
150
+ let detail = null;
151
+ let since = 0;
152
+ let quietUntil = -Infinity;
153
+ let timer = null;
154
+ let up = false;
155
+ let current = null;
156
+ let due = 0;
157
+ let paused = null;
158
+ // How many tips each act has had.
159
+ const shown = new Map();
160
+ const MAX_PER_ACT = 2;
161
+ const stop = () => {
162
+ if (timer !== null) clearTimer(timer);
163
+ timer = null;
164
+ };
165
+ const down = () => {
166
+ stop();
167
+ if (up) hide();
168
+ up = false;
169
+ current = null;
170
+ paused = null;
171
+ };
172
+ const arm = (ms, f) => {
173
+ due = now() + ms;
174
+ timer = setTimer(() => {
175
+ timer = null;
176
+ f();
177
+ }, ms);
178
+ };
179
+ const eligible = () => id !== null && !up && enabled() && (shown.get(actKey(detail)) || 0) < MAX_PER_ACT;
180
+ const fire = () => {
181
+ if (!eligible() || now() < since + waitMs || now() < quietUntil) return schedule();
182
+ const own = validTips(detail.tips);
183
+ const list = own.length ? own : [].concat(pick(detail) || []);
184
+ const tip = list[shown.get(actKey(detail)) || 0];
185
+ // A wait due to end before the tip could be read shows none (the act keeps its tip): no flash of a card.
186
+ const left = Number.isFinite(detail.until) ? detail.until - now() : Infinity;
187
+ if (!tip || (left > 0 && left < holdMs(tip, minMs)) || show(tip) === false) return;
188
+ up = true;
189
+ current = tip;
190
+ shown.set(actKey(detail), (shown.get(actKey(detail)) || 0) + 1);
191
+ arm(holdMs(tip, minMs), expire);
192
+ };
193
+ // The card's hold is over while the wait goes on: it goes, and the act's next tip, if any, waits out a quiet gap.
194
+ const expire = () => {
195
+ quietUntil = now() + quietMs;
196
+ down();
197
+ schedule();
198
+ };
199
+ function schedule() {
200
+ if (!eligible() || timer !== null) return;
201
+ arm(Math.max(0, Math.max(since + waitMs, quietUntil) - now()), fire);
202
+ }
203
+ // A new terminal line: the tip gives way at once, and none starts for a while.
204
+ const event = () => {
205
+ quietUntil = now() + quietMs;
206
+ down();
207
+ };
208
+ return {
209
+ busy(d) {
210
+ const step = d && d.busy && d.id ? d.id : null;
211
+ if (step === id) return;
212
+ id = step;
213
+ detail = step === null ? null : d;
214
+ event();
215
+ if (id !== null) since = now();
216
+ schedule();
217
+ },
218
+ line() {
219
+ event();
220
+ schedule();
221
+ },
222
+ /** The viewer hovers or focuses the card: a card with a link holds still. */
223
+ pause() {
224
+ if (!up || paused !== null || timer === null || !current || !current.link) return;
225
+ paused = Math.max(0, due - now());
226
+ stop();
227
+ },
228
+ /** The viewer moved away: the card goes on with at least {@link LINK_RESUME_MS} left. */
229
+ resume() {
230
+ if (paused === null) return;
231
+ const left = Math.max(paused, LINK_RESUME_MS);
232
+ paused = null;
233
+ arm(left, expire);
234
+ },
235
+ /** The viewer closed the card. */
236
+ dismiss() {
237
+ if (id !== null) shown.set(actKey(detail), MAX_PER_ACT);
238
+ stop();
239
+ paused = null;
240
+ up = false;
241
+ current = null;
242
+ },
243
+ /** The Tips switch turned off: the card goes. */
244
+ off() {
245
+ down();
246
+ },
247
+ current: () => id,
248
+ };
249
+ }
250
+
251
+ /** How long a card stays: long enough to read its title and body (about 3 words a second, plus 3 s), never under minMs. */
252
+ export function holdMs(tip, minMs = TIP_MIN_MS) {
253
+ const words = `${tip.title || ""} ${tip.body}`.split(/\s+/).filter(Boolean).length;
254
+ return Math.max(minMs, 3_000 + words * 330);
255
+ }
256
+
257
+ /** A press on `target` closes the card unless it is inside the card (or the target is unknown). */
258
+ export function shouldDismiss(target, host) {
259
+ if (!target || !host) return false;
260
+ return !(target.closest && target.closest("#k-ask-tips .eh-modal"));
261
+ }
262
+
263
+ /** Space kept around a lit box (its attribute lines hang under it), and between the card and the area's edges. */
264
+ export const LIT_PAD = 16;
265
+ export const LIT_FOOT = 56;
266
+ export const EDGE = 12;
267
+
268
+ const hits = (a, b) => a.left < b.left + b.width && b.left < a.left + a.width && a.top < b.top + b.height && b.top < a.top + a.height;
269
+
270
+ /**
271
+ * Where the card docks in `area` ({ left, top, width, height }, the graph's room above the prompt) for a card of
272
+ * `w` by `h`: the first corner (top right, top left, bottom right, bottom left) that touches no lit box (`lit`, page
273
+ * rects, each padded by {@link LIT_PAD} and {@link LIT_FOOT} below). Null when none is clear or the card does not fit.
274
+ */
275
+ export function dockCorner(area, w, h, lit = []) {
276
+ if (!area || w + 2 * EDGE > area.width || h + 2 * EDGE > area.height) return null;
277
+ const pads = lit.map((r) => ({ left: r.left - LIT_PAD, top: r.top - LIT_PAD, width: r.width + 2 * LIT_PAD, height: r.height + LIT_PAD + LIT_FOOT }));
278
+ const xs = { r: area.left + area.width - EDGE - w, l: area.left + EDGE };
279
+ const ys = { t: area.top + EDGE, b: area.top + area.height - EDGE - h };
280
+ for (const [corner, x, y] of [["top-right", xs.r, ys.t], ["top-left", xs.l, ys.t], ["bottom-right", xs.r, ys.b], ["bottom-left", xs.l, ys.b]]) {
281
+ const box = { left: x, top: y, width: w, height: h };
282
+ if (!pads.some((p) => hits(box, p))) return { corner, left: x, top: y };
283
+ }
284
+ return null;
285
+ }
286
+
287
+ /**
288
+ * The room a tip may dock in, in page pixels: the shown graph frame (`frame`), less what the prompt pane (`ask`) covers
289
+ * under it and what the side pane (`side`: web/kiosk-side.js, open or folded to its tab) covers at its right. Either
290
+ * may be null (not shown).
291
+ */
292
+ export function tipArea(frame, ask = null, side = null) {
293
+ const bottom = ask ? Math.min(frame.bottom, ask.top) : frame.bottom;
294
+ const right = side && side.left < frame.right && side.right > frame.left && side.top < bottom && side.bottom > frame.top ? Math.max(frame.left, side.left) : frame.right;
295
+ return { left: frame.left, top: frame.top, width: Math.max(0, right - frame.left), height: Math.max(0, bottom - frame.top) };
296
+ }
297
+
298
+ const STYLE_ID = "k-ask-tips-style";
299
+ const STYLE = `
300
+ #k-ask-tips { position: fixed; left: 0; top: 0; width: 0; height: 0; z-index: 50; pointer-events: none; overflow: hidden; }
301
+ #k-ask-tips .eh-modal-wrap { position: absolute; inset: 0; z-index: auto; display: block; background: transparent; pointer-events: auto; }
302
+ #k-ask-tips .eh-modal-wrap.k-tip-out { pointer-events: none; }
303
+ #k-ask-tips .eh-modal { position: absolute; pointer-events: auto; width: min(19em, calc(100% - 24px)); max-height: calc(100% - 24px); padding: 0.55em 2.4em 0.6em 0.8em; font-size: 0.8em; border: 1px solid var(--rule); border-radius: 8px; box-shadow: none;
304
+ background: color-mix(in srgb, var(--surface-pane-b, var(--panel)) 92%, transparent); color: var(--muted); }
305
+ #k-ask-tips .eh-modal-tip { --bar: var(--rule); box-shadow: none; background: color-mix(in srgb, var(--surface-pane-b, var(--panel)) 92%, transparent); }
306
+ #k-ask-tips .eh-modal-mode { display: none; }
307
+ #k-ask-tips .eh-modal-title { font-size: 1.05em; margin: 0 0 0.2em; color: var(--fg); }
308
+ #k-ask-tips .eh-modal-line { color: var(--muted); line-height: 1.4; }
309
+ #k-ask-tips .eh-modal-close { min-width: 36px; min-height: 36px; top: 0; right: 0; font-size: 1.1em; }
310
+ #k-ask-tips .eh-modal-link { display: inline-block; margin-top: 0.3em; font-size: 0.95em; color: var(--muted); text-decoration: underline; }
311
+ @media (prefers-reduced-motion: no-preference) {
312
+ #k-ask-tips .eh-modal-wrap { transition: opacity ${TIP_FADE_MS}ms linear; }
313
+ #k-ask-tips .eh-modal-wrap.k-tip-out { opacity: 0; }
314
+ }
315
+ `;
316
+
317
+ /**
318
+ * Wire the cards to the page: listens for `behold:ask-busy` and `behold:ask-line` on `win`, and for the frame's
319
+ * `behold:lit-rects`. The card docks in the graph's room (the shown graph frame, above `askHost`, the prompt pane).
320
+ * The Tips checkbox turns them off where it shows; where the bar is hidden (ask mode) they are on.
321
+ */
322
+ export function mountAskTips({ win = window, doc = document, askHost, reduced = () => typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches }) {
323
+ if (!askHost || !doc.body) return null;
324
+ if (!doc.getElementById(STYLE_ID)) {
325
+ const st = doc.createElement("style");
326
+ st.id = STYLE_ID;
327
+ st.textContent = STYLE;
328
+ doc.head.appendChild(st);
329
+ }
330
+ modalStyle(doc);
331
+ const host = doc.createElement("div");
332
+ host.id = "k-ask-tips";
333
+ host.setAttribute("aria-live", "polite");
334
+ doc.body.appendChild(host);
335
+ let card = null;
336
+ let measure = null;
337
+ // The lit boxes, in the frame's pixels, from the frame that sent them.
338
+ let lit = { source: null, rects: [] };
339
+ const phone = () => typeof win.matchMedia === "function" && win.matchMedia(PHONE).matches;
340
+ // The graph frame on show is always #view (a frame loading out of sight takes the id when it swaps in).
341
+ const shownFrame = () => {
342
+ const f = doc.getElementById("view");
343
+ return f && f.getClientRects().length > 0 ? f : null;
344
+ };
345
+ /** The graph's room above the prompt and left of the side pane, in page pixels. */
346
+ const area = () => {
347
+ const f = shownFrame();
348
+ if (!f) return null;
349
+ const side = [doc.getElementById("k-side"), doc.getElementById("k-side-tab")].find((n) => n && n.getClientRects().length > 0);
350
+ const room = tipArea(f.getBoundingClientRect(), askHost.hidden ? null : askHost.getBoundingClientRect(), side ? side.getBoundingClientRect() : null);
351
+ return { ...room, frame: f };
352
+ };
353
+ const litRects = (a) => {
354
+ if (!a || !a.frame || lit.source !== a.frame.contentWindow) return [];
355
+ return lit.rects.map(([x, y, w, h]) => ({ left: a.left + x, top: a.top + y, width: w, height: h }));
356
+ };
357
+ /** Dock the card; false when no corner is clear. */
358
+ const place = () => {
359
+ const box = card && host.querySelector(".eh-modal");
360
+ const a = area();
361
+ if (!box || !a) return false;
362
+ host.style.left = `${Math.round(a.left)}px`;
363
+ host.style.top = `${Math.round(a.top)}px`;
364
+ host.style.width = `${Math.round(a.width)}px`;
365
+ host.style.height = `${Math.round(a.height)}px`;
366
+ const b = box.getBoundingClientRect();
367
+ const spot = dockCorner(a, b.width, b.height, litRects(a));
368
+ if (!spot) return false;
369
+ box.style.left = `${Math.round(spot.left - a.left)}px`;
370
+ box.style.top = `${Math.round(spot.top - a.top)}px`;
371
+ box.dataset.corner = spot.corner;
372
+ return true;
373
+ };
374
+ const enabled = () => {
375
+ const box = doc.querySelector(".eh-switch input");
376
+ const seen = box && box.getClientRects().length > 0;
377
+ return !seen || box.checked;
378
+ };
379
+ const linkNode = (l) => {
380
+ const a = doc.createElement("a");
381
+ a.className = "eh-modal-link";
382
+ a.href = l.url;
383
+ a.target = "_blank";
384
+ a.rel = "noopener";
385
+ a.textContent = l.label;
386
+ return a;
387
+ };
388
+ const fading = new Set();
389
+ const stopMeasure = () => {
390
+ if (measure !== null) win.clearInterval(measure);
391
+ measure = null;
392
+ };
393
+ const kill = () => {
394
+ for (const c of fading) c.api.close();
395
+ fading.clear();
396
+ if (card) {
397
+ const c = card;
398
+ card = null;
399
+ c.api.close();
400
+ }
401
+ stopMeasure();
402
+ };
403
+ const hideCard = () => {
404
+ const c = card;
405
+ if (!c) return;
406
+ const wrap = host.querySelector(".eh-modal-wrap");
407
+ if (reduced() || !wrap) return kill();
408
+ wrap.classList.add("k-tip-out");
409
+ card = null;
410
+ fading.add(c);
411
+ stopMeasure();
412
+ win.setTimeout(() => {
413
+ fading.delete(c);
414
+ c.api.close();
415
+ }, TIP_FADE_MS);
416
+ };
417
+ // The boxes moved under the card: dock elsewhere, or go.
418
+ const recheck = () => {
419
+ if (card && !place()) hideCard();
420
+ };
421
+ const seq = createTipSequencer({
422
+ enabled,
423
+ show(tip) {
424
+ kill();
425
+ if (phone()) return false;
426
+ const mine = { api: null };
427
+ mine.api = openEventModal(host, {
428
+ mode: "narrated",
429
+ kind: "tip",
430
+ data: { ...(tip.title ? { title: tip.title } : {}), lines: [{ text: tip.body }], ...(tip.link ? { panel: linkNode(tip.link) } : {}) },
431
+ doc,
432
+ reduced: reduced(),
433
+ onClose: (s) => {
434
+ if (card === mine) {
435
+ card = null;
436
+ stopMeasure();
437
+ if (s.closedBy === "viewer") seq.dismiss();
438
+ }
439
+ },
440
+ });
441
+ card = mine;
442
+ if (!place()) {
443
+ kill();
444
+ return false;
445
+ }
446
+ if (measure === null) measure = win.setInterval(recheck, 250);
447
+ return true;
448
+ },
449
+ hide: hideCard,
450
+ });
451
+ // A card with a link holds still while it is hovered or has focus (the sequencer ignores a card without one).
452
+ const onCard = (e) => e.target && e.target.closest && e.target.closest("#k-ask-tips .eh-modal");
453
+ host.addEventListener("mouseover", (e) => onCard(e) && seq.pause());
454
+ host.addEventListener("focusin", (e) => onCard(e) && seq.pause());
455
+ host.addEventListener("mouseout", (e) => onCard(e) && !(e.relatedTarget && onCard({ target: e.relatedTarget })) && !host.querySelector(".eh-modal:focus-within") && seq.resume());
456
+ host.addEventListener("focusout", (e) => onCard(e) && !(e.relatedTarget && onCard({ target: e.relatedTarget })) && !host.querySelector(".eh-modal:hover") && seq.resume());
457
+ // A click or tap anywhere outside the card closes it, as the X does; one inside (its link) does not. Over the graph
458
+ // (an iframe, which sends the page no events) the card's own sheet takes the press (the modal closes on a click on it);
459
+ // anywhere else on the page, this listener does.
460
+ doc.addEventListener("pointerdown", (e) => {
461
+ if (!card || !shouldDismiss(e.target, host)) return;
462
+ card.api.dismiss();
463
+ }, true);
464
+ win.addEventListener("behold:ask-busy", (e) => seq.busy(e.detail));
465
+ win.addEventListener("behold:ask-line", () => seq.line());
466
+ win.addEventListener("message", (e) => {
467
+ if (!e.data || e.data.type !== "behold:lit-rects" || !Array.isArray(e.data.rects)) return;
468
+ const f = [...doc.querySelectorAll("iframe")].find((x) => x.contentWindow === e.source);
469
+ if (!f) return;
470
+ lit = { source: e.source, rects: e.data.rects.filter((r) => Array.isArray(r) && r.length === 4 && r.every(Number.isFinite)) };
471
+ recheck();
472
+ });
473
+ doc.addEventListener("change", (e) => {
474
+ if (e.target && e.target.matches && e.target.matches(".eh-switch input") && !e.target.checked) seq.off();
475
+ });
476
+ return seq;
477
+ }