@intentius/behold 0.29.18 → 0.29.20

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.
package/web/kiosk.js CHANGED
@@ -14,7 +14,7 @@
14
14
  // Nothing here is all-or-nothing, and nothing says so.
15
15
 
16
16
  import { PICK_HOLD_MS, annMark, mergeRun, startRuns } from "./kiosk-runs.js";
17
- import { PANEL_STEPS, PANEL_TITLE, approvalModel, cycleRuns, rowFacts, shortDigest } from "./kiosk-approval.js";
17
+ import { PANEL_STEPS, PANEL_TITLE, approvalModel, cycleRuns, digestHex, rowFacts } from "./kiosk-approval.js";
18
18
  import { getThemeName, mountThemePicker, onThemeChange } from "./theme.js";
19
19
  import { cssString, hoverCss, hoverFromMessage, hoverLinks, hoverMessage, isLightBg, rootSegments, rootText } from "./kiosk-roots.js";
20
20
  import { creditLines, filterIndex, keepRun, liveEstimate, liveFor, namesOther, notRunRepo, notRunWords, replayAt, replayBanner, replayIndex, rootNoun, rootWord, runAsOf, scrubDemo, servesRepo, vendorOf } from "./kiosk-vendor.js";
@@ -408,23 +408,88 @@ export function kioskView(demo, { components = false, pick = null, now = Date.no
408
408
  return { view: demo ? stepView(demo.step) : "components", pinned: false, secs: null };
409
409
  }
410
410
 
411
- /** The line under the view saying how to read it, for the view shown. */
412
- export function legendWords(view, tool = null) {
411
+ /** behold#571: the static frame's title, over the legend; collapsed, its one line. */
412
+ export const READ_TITLE = "How to read this";
413
+
414
+ /** behold#571: where a viewer's choice to fold "How to read this" is kept, in their own browser. */
415
+ export const READ_STORE = "behold.kiosk.read";
416
+
417
+ /**
418
+ * behold#571: the legend of the view shown, one row per mark: what a card, a
419
+ * box, a solid arrow and a dashed arrow are, the waves' order, and what the
420
+ * forge and tool marks name. `[{ mark, words }]`, `mark` one of card, box,
421
+ * solid, dashed, order, marks. Short items, two to a line, so the open
422
+ * frame stays a few lines over the graph. Its words follow the view and the
423
+ * tool alone, never the step.
424
+ */
425
+ export function readingRows(view, tool = null) {
413
426
  const root = rootWord(tool);
414
427
  const n = rootNoun(tool);
415
- // A tool whose pipeline writes no reports: behold's own graph of its components, boxed by the wave each applies in.
416
428
  if (reportless(vendorOf(tool))) {
417
- return view === "components"
418
- ? `Components shows the project's components, in a box per wave. Each card is ${root} with its own state, and an arrow is one component reading another's outputs.`
419
- : `Each box is ${root} with its own state.`;
429
+ if (view !== "components") return [{ mark: "box", words: `Box: ${root} with its own state.` }];
430
+ return [
431
+ { mark: "card", words: `Card: ${root} with its own state.` },
432
+ { mark: "box", words: "Box: a wave of components that apply together." },
433
+ { mark: "solid", words: "Arrow: a component reading another's outputs." },
434
+ ];
420
435
  }
421
- const rest = `an arrow is one ${n.one} reading another's outputs, dashed while it reads planned values. A wave applies its ${n.many} together, after the waves it reads.`;
436
+ const arrows = [
437
+ { mark: "solid", words: "Solid arrow: a read of applied outputs." },
438
+ { mark: "dashed", words: "Dashed arrow: planned values, before they apply." },
439
+ ];
422
440
  if (view === "components") {
423
- return `Components shows the pipeline's jobs and waves. Each card is ${root} with its own state, in a box per wave titled with the job that applies it; ${rest}`;
441
+ return [
442
+ { mark: "card", words: `Card: ${root} with its own state.` },
443
+ { mark: "box", words: "Box: a wave, titled with the job that applies it." },
444
+ ...arrows,
445
+ { mark: "order", words: `Waves apply in order, ${n.many} in a wave together.` },
446
+ { mark: "marks", words: "Marks: the forge and the tools a job runs." },
447
+ ];
424
448
  }
425
- return `Each box is ${root} with its own state; ${rest}`;
449
+ return [
450
+ { mark: "box", words: `Box: ${root} with its own state.` },
451
+ { mark: "card", words: "Card: one of its resources." },
452
+ ...arrows,
453
+ { mark: "marks", words: "Marks: the tools each job runs, in the jobs pane." },
454
+ ];
426
455
  }
427
456
 
457
+ /**
458
+ * behold#571: "How to read this", the graph pane's static frame. A header
459
+ * that folds it, and the legend of the view shown. Drawn again only when the
460
+ * view or the tool changes (the caller keys it), never per step.
461
+ */
462
+ export function renderReading(host, view, tool, { open = true, onToggle = () => {} } = {}) {
463
+ if (!host) return;
464
+ host.replaceChildren();
465
+ host.hidden = false;
466
+ const head = el("button", "k-read-head", READ_TITLE);
467
+ head.type = "button";
468
+ if (head.setAttribute) head.setAttribute("aria-expanded", String(open));
469
+ if (head.addEventListener) head.addEventListener("click", () => onToggle(!open));
470
+ host.appendChild(head);
471
+ if (host.classList) host.classList.toggle("k-read-open", open);
472
+ if (!open) return;
473
+ const list = el("ul", "k-read-rows");
474
+ for (const r of readingRows(view, tool)) {
475
+ const li = el("li", "k-read-row");
476
+ const mark = el("span", `k-read-mark k-read-${r.mark}`);
477
+ if (mark.setAttribute) mark.setAttribute("aria-hidden", "true");
478
+ li.append(mark, el("span", "k-read-words", r.words));
479
+ list.appendChild(li);
480
+ }
481
+ host.appendChild(list);
482
+ }
483
+
484
+ /** behold#571: the viewer's fold of "How to read this": true open, false folded, null when they never chose. */
485
+ export function readStored(store) {
486
+ try {
487
+ const v = store && store.getItem(READ_STORE);
488
+ return v === "open" ? true : v === "closed" ? false : null;
489
+ } catch {
490
+ return null;
491
+ }
492
+ }
428
493
 
429
494
  /** Whether a tool's pipeline writes no terragucci reports or run view (VENDORS' `reports: false`). */
430
495
  export function reportless(vendor) {
@@ -511,16 +576,61 @@ const elRoots = (tag, cls, text, s) => {
511
576
  return n;
512
577
  };
513
578
 
514
- /** Draw the bar and the foot from what the kiosk holds. Pure over its arguments, but for the DOM. */
515
- export function renderKiosk(bar, s, now = new Date(), foot = null) {
579
+ /**
580
+ * Draw the header from what the kiosk holds. Pure over its arguments, but for
581
+ * the DOM. behold#571: the lead block on the left (the scenario, its two
582
+ * beats, its progress, the pull request's facts and, on a tool's page, the
583
+ * credit), the hold panel on the right. The page has no footer: the legend is
584
+ * the graph pane's "How to read this". `_foot` is ignored, kept for callers.
585
+ */
586
+ export function renderKiosk(bar, s, now = new Date(), _foot = null) {
516
587
  bar.replaceChildren();
517
- if (foot) foot.replaceChildren();
518
- drawBar(bar, s, now, foot);
519
- // behold#571: a tool's page ends with who makes the tool, and that they don't endorse the demo.
520
- if (foot && vendorOf(s.vendor)) drawCredit(foot, s.vendor);
588
+ if (_foot) _foot.replaceChildren();
589
+ drawBar(bar, s, now);
590
+ }
591
+
592
+ /** behold#571: the card's first beat, as the lead block labels it. */
593
+ export const BEAT_CHANGES = "What changes";
594
+
595
+ /** behold#571: the lead block's line of the pull request's facts: factLines, as one line. */
596
+ export function factsLine(demo, answer, tool = null) {
597
+ return factLines(demo, answer, tool).join(" · ");
598
+ }
599
+
600
+ /**
601
+ * behold#571: the hold panel's head: its wave, its run and its plan, as
602
+ * "Wave 2 · run #3605 · plan 02812a1b". Without a wave, the pull request or
603
+ * the commit the note is about. Null when it knows none of these.
604
+ */
605
+ export function holdHead({ wave = null, run = null, digest = null, pull = null, commit = null } = {}) {
606
+ const parts = [];
607
+ if (Number.isInteger(wave)) parts.push(`Wave ${wave}`);
608
+ if (Number.isInteger(run)) parts.push(`run #${run}`);
609
+ if (digest && digestHex(digest)) parts.push(`plan ${digestHex(digest).slice(0, 8)}`);
610
+ if (!parts.length && pull !== null && pull !== undefined && pull !== "") parts.push(`Pull request #${pull}`);
611
+ if (!parts.length && commit) parts.push(`Merge ${String(commit).slice(0, 8)}`);
612
+ return parts.length ? parts.join(" · ") : null;
521
613
  }
522
614
 
523
- function drawBar(bar, s, now, foot) {
615
+ /**
616
+ * behold#571: what the hold panel holds, or null for nothing: how the hold
617
+ * ends (from the records), else the driver's approval, else the run's note.
618
+ * `{ kind, wave, head, … }`; `wave` is the wave it lights, when it has one.
619
+ */
620
+ export function holdModel(s, demo) {
621
+ const vendor = vendorOf(s.vendor);
622
+ if (s.approval) return { kind: "approval", wave: s.approval.wave, head: holdHead({ wave: s.approval.wave, run: s.approval.run, digest: s.approval.digest }), model: s.approval };
623
+ const appr = pendingApproval(demo, s.progress);
624
+ if (appr) return { kind: "driver", wave: appr.wave, head: holdHead({ wave: appr.wave, digest: appr.digest }), appr };
625
+ if (s.noReports || reportless(vendor || vendorOf(demo.tool))) return null;
626
+ const panel = runPanel(demo, s.answer, s.progress);
627
+ const lines = panel.note ? [{ cls: "k-note", text: panel.note }] : panel.stage === "pull-request" ? unreviewedLines(s.answer).map((u) => ({ cls: "k-note k-unknown", text: u })) : [];
628
+ if (!lines.length) return null;
629
+ const head = holdHead(panel.stage === "pull-request" ? { pull: demo.pull } : { commit: demo.commit });
630
+ return { kind: "note", wave: null, head, lines };
631
+ }
632
+
633
+ function drawBar(bar, s, now) {
524
634
  const vendor = vendorOf(s.vendor);
525
635
  if (vendor && s.mode === "none") {
526
636
  // behold#571: the tool's scenario has no cycle yet: its name, its link, and a calm line.
@@ -529,6 +639,7 @@ function drawBar(bar, s, now, foot) {
529
639
  const title = el("h1", "k-title");
530
640
  title.append(brandEl(vendor), el("span", "k-title-text", words.title));
531
641
  box.append(title, el("p", "k-muted", words.text));
642
+ drawCredit(box, s.vendor);
532
643
  bar.appendChild(box);
533
644
  return;
534
645
  }
@@ -539,6 +650,7 @@ function drawBar(bar, s, now, foot) {
539
650
  title.appendChild(el("span", "k-title-text", "Waiting for the demo"));
540
651
  box.appendChild(title);
541
652
  box.appendChild(el("p", "k-muted", s.demo ? s.demo.error || s.demo.absent : "Reading demo.json…"));
653
+ if (vendor) drawCredit(box, s.vendor);
542
654
  bar.appendChild(box);
543
655
  return;
544
656
  }
@@ -550,8 +662,8 @@ function drawBar(bar, s, now, foot) {
550
662
  if (vendor && s.noReports && (s.mode === "live" || s.mode === "replay")) bar.appendChild(el("p", "k-nograph-note", NO_GRAPH_WORDS));
551
663
  const intro = introText(demo);
552
664
 
553
- // behold#571: the left column in fixed boxes: the title, the card (the intro between scenarios), the step.
554
- const left = el("div", "k-left");
665
+ // behold#571: the lead block, in fixed boxes: the title, the two beats (what changes, and the step), the progress, the rest of the card, the facts.
666
+ const left = el("div", "k-left k-lead");
555
667
  const titleBox = box("title", "k-box-title");
556
668
  const title = el("h1", "k-title");
557
669
  // behold#571: /kiosk names the tool each scenario runs on, as its own page does.
@@ -561,70 +673,96 @@ function drawBar(bar, s, now, foot) {
561
673
  if (title.setAttribute) title.setAttribute("title", `${head.kicker} · ${head.title || ""}`);
562
674
  titleBox.appendChild(title);
563
675
  left.appendChild(titleBox);
564
- const cardBox = box("card");
676
+
677
+ // The first beat: what changes; between scenarios, what the demo is about.
565
678
  const rows = aboutRows(demo);
679
+ const changes = rows.find((r) => r.label === BEAT_CHANGES);
680
+ const beatBox = box("changes", "k-box-beat");
566
681
  if (demo.step === "reset" && intro) {
567
- // Between scenarios nothing else happens: the card's box says what the demo is about.
568
682
  const p = el("p", "k-intro");
569
683
  p.append(el("span", "k-intro-head", INTRO_HEAD), intro);
570
- cardBox.appendChild(p);
571
- } else if (rows.length) {
572
- const card = el("dl", "k-about");
573
- for (const r of rows) card.append(el("dt", "k-about-label", r.label), elRoots("dd", "k-about-text", r.text, s));
574
- cardBox.appendChild(card);
684
+ beatBox.appendChild(p);
685
+ } else if (changes) {
686
+ const p = el("p", "k-beat");
687
+ p.append(el("span", "k-beat-label", changes.label), elRoots("span", "k-beat-text", changes.text, s));
688
+ beatBox.appendChild(p);
575
689
  }
576
- left.appendChild(cardBox);
690
+ left.appendChild(beatBox);
691
+
692
+ // The second beat: the step, what just happened and why it stands where it does.
577
693
  const said = el("p", `k-step k-step-${demo.step}`);
578
694
  said.append(el("span", "k-step-word", STEP_WORDS[demo.step] || demo.step), elRoots("span", "k-label", demo.label, s));
579
- const stepBox = box("step");
695
+ const stepBox = box("step", "k-box-step");
580
696
  stepBox.appendChild(said);
581
697
  left.appendChild(stepBox);
582
- bar.appendChild(left);
583
698
 
584
- const right = el("div", "k-right");
699
+ // The scenario's progress, with the step: the strip, and the driver's next action with its countdown.
700
+ const progress = el("div", "k-progress");
585
701
  const strip = el("ol", "k-strip");
586
702
  for (const stop of stripStops(demo.step)) strip.appendChild(el("li", `k-stop k-${stop.state}`, stop.words));
587
- const where = el("div", "k-where");
588
- where.appendChild(strip);
589
- right.appendChild(where);
590
-
703
+ progress.appendChild(strip);
591
704
  const nx = nextWords(demo, now);
592
705
  const next = el("div", "k-next");
593
706
  next.appendChild(el("span", "k-next-word", "next, by the driver"));
594
707
  next.appendChild(elRoots("span", "k-action", nx.action, s));
595
708
  next.appendChild(el("span", "k-when", nx.when));
596
- next.appendChild(el("span", "k-cycle", cycleWords(demo, now)));
597
- right.appendChild(next);
709
+ // Short of room the action ends in an ellipsis; the whole line is its title.
710
+ if (next.setAttribute) next.setAttribute("title", `next, by the driver: ${nx.action}`);
711
+ progress.appendChild(next);
712
+ left.appendChild(progress);
713
+
714
+ // The rest of the card, quieter: watch for, and what the scenario shows.
715
+ const moreBox = box("card", "k-box-more");
716
+ const more = demo.step === "reset" && intro ? [] : rows.filter((r) => r !== changes);
717
+ if (more.length) {
718
+ // One quieter paragraph, each field after its label, so two short fields share a line.
719
+ const card = el("p", "k-about");
720
+ for (const r of more) card.append(el("span", "k-about-label", r.label), elRoots("span", "k-about-text", r.text, s), " ");
721
+ moreBox.appendChild(card);
722
+ }
723
+ left.appendChild(moreBox);
724
+
725
+ // The pull request's facts, as one line. behold#571: no line on where the narration was read from.
726
+ const factsBox = box("facts", "k-box-facts");
727
+ const facts = s.noReports ? "" : factsLine(demo, s.answer, nounTool(s));
728
+ if (facts) {
729
+ const p = elRoots("p", "k-facts", facts, s);
730
+ if (p.setAttribute) p.setAttribute("title", facts);
731
+ factsBox.appendChild(p);
732
+ }
733
+ left.appendChild(factsBox);
734
+ // behold#571: a tool's page ends its lead block with who makes the tool, and that they don't endorse the demo.
735
+ if (vendor) drawCredit(left, s.vendor);
736
+ for (const b of [beatBox, moreBox, factsBox]) if (!b.children.length) b.className += " k-box-empty";
737
+ bar.appendChild(left);
598
738
 
599
- // behold#571: the hold's box: how the hold ends, from the records; else the driver's approval, or the run's note.
600
- const holdBox = box("hold");
601
- const appr = pendingApproval(demo, s.progress);
602
- if (s.approval) {
603
- holdBox.appendChild(approvalPanel(s.approval, s));
604
- } else if (appr) {
605
- const a = el("div", "k-approve");
606
- a.appendChild(elRoots("p", "k-approve-gloss", approveGloss(appr), s));
607
- a.appendChild(el("code", "k-command", appr.approve));
608
- const then = el("p", "k-approve-then");
609
- then.append(`then comments `, el("code", "k-inline", appr.comment), ` on ${appr.on}, and the waves run again.`);
610
- a.appendChild(then);
611
- holdBox.appendChild(a);
612
- } else if (!s.noReports && !reportless(vendor || vendorOf(demo.tool))) {
613
- const panel = runPanel(demo, s.answer, s.progress);
614
- if (panel.note) holdBox.appendChild(elRoots("p", "k-note", panel.note, s));
615
- else if (panel.stage === "pull-request") for (const u of unreviewedLines(s.answer)) holdBox.appendChild(elRoots("p", "k-note k-unknown", u, s));
739
+ // behold#571: the hold panel, headed with its wave and run, lit as its job row and its wave box are.
740
+ const right = el("div", "k-right");
741
+ // The cycle, quiet over the hold panel: how long this run of the scenario has gone.
742
+ right.appendChild(el("p", "k-cycle", cycleWords(demo, now)));
743
+ const holdBox = box("hold", "k-box-hold");
744
+ const hold = holdModel(s, demo);
745
+ if (hold) {
746
+ // A wave held lights in the waiting tone; a run's note stays quiet.
747
+ holdBox.className += hold.wave !== null ? " k-hold k-hold-wave" : " k-hold";
748
+ if (hold.wave !== null && holdBox.dataset) holdBox.dataset.kWave = String(hold.wave);
749
+ if (hold.head) holdBox.appendChild(el("p", "k-hold-head", hold.head));
750
+ if (hold.kind === "approval") holdBox.appendChild(approvalPanel(hold.model, s));
751
+ else if (hold.kind === "driver") {
752
+ const appr = hold.appr;
753
+ const a = el("div", "k-approve");
754
+ a.appendChild(elRoots("p", "k-approve-gloss", approveGloss(appr), s));
755
+ a.appendChild(el("code", "k-command", appr.approve));
756
+ const then = el("p", "k-approve-then");
757
+ then.append(`then comments `, el("code", "k-inline", appr.comment), ` on ${appr.on}, and the waves run again.`);
758
+ a.appendChild(then);
759
+ holdBox.appendChild(a);
760
+ } else for (const l of hold.lines) holdBox.appendChild(elRoots("p", l.cls, l.text, s));
616
761
  }
617
762
  // behold#571: render what's present: an empty hold keeps its place (nothing moves when one comes) but draws no box.
618
763
  if (!holdBox.children.length) holdBox.className += " k-box-empty";
619
764
  right.appendChild(holdBox);
620
765
  bar.appendChild(right);
621
-
622
- if (foot) {
623
- // The legend reads the graph; with no graph shown there is nothing for it to explain.
624
- if (!s.noReports) foot.appendChild(el("span", "k-legend", legendWords(s.view || "resources", nounTool(s))));
625
- // behold#571: no line on where the narration was read from: a viewer new to the demo reads the facts.
626
- if (!s.noReports) for (const f of factLines(demo, s.answer, nounTool(s))) foot.appendChild(elRoots("span", "k-fact", f, s));
627
- }
628
766
  }
629
767
 
630
768
  /** behold#571: the head over the intro, in the card's box between scenarios, and the title of "What is this?". */
@@ -644,10 +782,8 @@ function box(name, cls = "") {
644
782
  */
645
783
  export function approvalPanel(model, s = {}) {
646
784
  const wrap = el("div", "k-ap");
647
- const head = el("p", "k-ap-head", `${PANEL_TITLE} · wave ${model.wave} `);
648
- if (model.digest) head.appendChild(el("span", "k-ap-plan", `plan ${shortDigest(model.digest)}`));
649
- head.append(" · times in UTC");
650
- wrap.appendChild(head);
785
+ // behold#571: the hold panel's head names the wave, the run and the plan; this one says what the rows are.
786
+ wrap.appendChild(el("p", "k-ap-head", `${PANEL_TITLE} · times in UTC`));
651
787
  const list = el("ol", "k-ap-rows");
652
788
  for (const r of model.rows) {
653
789
  const li = el("li", `k-ap-row k-ap-${r.state}`);
@@ -693,9 +829,12 @@ function brandEl(vendor) {
693
829
  return a;
694
830
  }
695
831
 
696
- /** behold#571: the footer's credit on a tool's page, its names linked to their official sites. */
697
- function drawCredit(foot, tool) {
698
- for (const line of creditLines(tool)) {
832
+ /** behold#571: the credit on a tool's page, one quiet line at the lead block's foot, its names linked to their official sites. */
833
+ function drawCredit(host, tool) {
834
+ const lines = creditLines(tool);
835
+ if (!lines.length) return;
836
+ const wrap = el("p", "k-credits");
837
+ for (const line of lines) {
699
838
  const p = el("span", "k-credit");
700
839
  for (const seg of line) {
701
840
  if (!seg.url) {
@@ -708,13 +847,16 @@ function drawCredit(foot, tool) {
708
847
  a.rel = "noopener";
709
848
  p.appendChild(a);
710
849
  }
711
- foot.appendChild(p);
850
+ wrap.append(p, " ");
712
851
  }
852
+ host.appendChild(wrap);
713
853
  }
714
854
 
715
855
  /** behold#571: how a hovered root's name and wave's job row light. A background and a shadow: nothing moves. */
716
856
  export const HOVER_ROOT_RULE = "background: color-mix(in srgb, var(--focus) 32%, transparent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--focus) 32%, transparent); border-radius: 3px;";
717
857
  export const HOVER_JOB_RULE = "background: color-mix(in srgb, var(--focus) 24%, transparent); box-shadow: inset 4px 0 0 var(--focus);";
858
+ /** behold#571: how the held wave's job row lights while the hold panel shows it: the waiting tone its wave box and the panel carry. */
859
+ export const HELD_JOB_RULE = "background: color-mix(in srgb, var(--foreign) 14%, transparent); box-shadow: inset 4px 0 0 var(--foreign);";
718
860
 
719
861
  /** behold#571: how often the approval panel reads the cycle's runs, and the gate ledger (which the server caches 30 s). */
720
862
  export const APPROVAL_POLL_MS = 4_000;
@@ -737,14 +879,14 @@ function fade(b) {
737
879
  export const DEMO_POLL_MS = 3_000;
738
880
 
739
881
  /**
740
- * Boot the kiosk: the bar, the frame and the foot. Ask demo.json every few
882
+ * Boot the kiosk: the bar, the frame and the graph pane's legend. Ask demo.json every few
741
883
  * seconds, the reports and the run view when the step, cycle or commit moves
742
884
  * or the event stream says they did, and redraw every second for the
743
885
  * countdown. When the roots the step is about change, move the framed view
744
886
  * with a `behold:view` message; the frame takes them only from this origin.
745
887
  */
746
- export function startKiosk({ bar, frame, foot, side, main, views, tools = null }, { fetchJson = defaultFetch, now = () => new Date(), origin = location.origin, tool = null } = {}) {
747
- const s = { demo: null, answer: null, progress: null, components: false, pick: null, view: "resources", roots: [], waves: [], light: false, hover: null, frameHover: null };
888
+ export function startKiosk({ bar, frame, side, main, views, read = null, tools = null }, { fetchJson = defaultFetch, now = () => new Date(), origin = location.origin, tool = null } = {}) {
889
+ const s = { demo: null, answer: null, progress: null, components: false, pick: null, view: "resources", roots: [], waves: [], light: false, hover: null, frameHover: null, held: null };
748
890
  // behold#571: on a tool's page, `live` while its scenario runs, `replay` of its latest cycle otherwise, `none` before it has one.
749
891
  const vendor = vendorOf(tool);
750
892
  s.vendor = vendor ? tool : null;
@@ -801,6 +943,7 @@ export function startKiosk({ bar, frame, foot, side, main, views, tools = null }
801
943
  if (!force && key === lastFocus) return;
802
944
  lastFocus = key;
803
945
  if (frame && frame.contentWindow) frame.contentWindow.postMessage({ type: "behold:view", member: null, focus, run, zoom }, origin);
946
+ tellHover(s.hover);
804
947
  };
805
948
  const pickView = (view) => {
806
949
  s.pick = { view, at: now().getTime() };
@@ -819,12 +962,16 @@ export function startKiosk({ bar, frame, foot, side, main, views, tools = null }
819
962
  const b = hoverLinks(s.frameHover, s.waves);
820
963
  const links = { roots: [...new Set([...a.roots, ...b.roots])], waves: [...new Set([...a.waves, ...b.waves])] };
821
964
  style.textContent = [
965
+ // behold#571: the held wave's job row, lit as the hold panel is; a hover's light comes after it and wins.
966
+ Number.isInteger(s.held) ? `.r-job[data-k-wave="${s.held}"] { ${HELD_JOB_RULE} }` : "",
822
967
  hoverCss({ roots: links.roots, waves: [] }, { root: (r) => `.k-root[data-k-root=${cssString(r)}]` }, HOVER_ROOT_RULE),
823
968
  hoverCss({ roots: [], waves: links.waves }, { wave: (w) => `.r-job[data-k-wave="${w}"]` }, HOVER_JOB_RULE),
824
969
  ].join("\n");
825
970
  };
971
+ // behold#571: with nothing pointed at, the frame lights the held wave's box, as the hold panel and its job row are lit.
826
972
  const tellHover = (h) => {
827
- if (frame && frame.contentWindow) frame.contentWindow.postMessage(hoverMessage(h), origin);
973
+ const lit = h || (Number.isInteger(s.held) ? { wave: s.held } : null);
974
+ if (frame && frame.contentWindow) frame.contentWindow.postMessage(hoverMessage(lit), origin);
828
975
  };
829
976
  const hoverAt = (target) => {
830
977
  const t = target && target.closest ? target.closest("[data-k-root],[data-k-wave]") : null;
@@ -857,6 +1004,35 @@ export function startKiosk({ bar, frame, foot, side, main, views, tools = null }
857
1004
  });
858
1005
  }
859
1006
 
1007
+ // behold#571: "How to read this", folded until a viewer opens it, then as they last left it.
1008
+ const store = typeof localStorage !== "undefined" ? (() => { try { return localStorage; } catch { return null; } })() : null;
1009
+ let readOpen = readStored(store) === true;
1010
+ let readKey = null;
1011
+ const drawReading = (view, ok, force = false) => {
1012
+ if (!read) return;
1013
+ const t = nounTool(s);
1014
+ const key = `${view}|${t}|${ok}|${readOpen}`;
1015
+ if (!force && key === readKey) return;
1016
+ readKey = key;
1017
+ if (!ok) {
1018
+ read.replaceChildren();
1019
+ read.hidden = true;
1020
+ return;
1021
+ }
1022
+ renderReading(read, view, t, {
1023
+ open: readOpen,
1024
+ onToggle: (open) => {
1025
+ readOpen = open;
1026
+ try {
1027
+ if (store) store.setItem(READ_STORE, open ? "open" : "closed");
1028
+ } catch {
1029
+ /* private mode: the fold lasts this visit */
1030
+ }
1031
+ drawReading(view, ok, true);
1032
+ },
1033
+ });
1034
+ };
1035
+
860
1036
  // behold#571: the titles and names demo.json has carried, by scenario, for the runs' subtitles.
861
1037
  const titles = {};
862
1038
  const names = {};
@@ -900,14 +1076,23 @@ export function startKiosk({ bar, frame, foot, side, main, views, tools = null }
900
1076
  s.approval = approvalNow();
901
1077
  // behold#571: the header's boxes redraw every second; each keeps where a viewer scrolled it.
902
1078
  const scrolled = Object.fromEntries([...bar.querySelectorAll(".k-box")].map((b) => [b.dataset.box, b.scrollTop]));
903
- renderKiosk(bar, s, shownNow(), foot);
1079
+ renderKiosk(bar, s, shownNow());
904
1080
  for (const b of bar.querySelectorAll(".k-box")) {
905
1081
  if (scrolled[b.dataset.box]) b.scrollTop = scrolled[b.dataset.box];
906
1082
  fade(b);
907
1083
  b.addEventListener("scroll", () => fade(b), { passive: true });
908
1084
  }
1085
+ // behold#571: the wave the hold panel shows, whose job row lights with it.
1086
+ const hold = s.demo && s.demo.demo ? holdModel(s, s.demo.demo) : null;
1087
+ const held = hold && Number.isInteger(hold.wave) ? hold.wave : null;
1088
+ if (held !== s.held) {
1089
+ s.held = held;
1090
+ glow();
1091
+ tellHover(s.hover);
1092
+ }
909
1093
  whatText();
910
1094
  renderViewToggle(views, shown, { components: s.components && ok, onPick: pickView });
1095
+ drawReading(shown.view, ok);
911
1096
  // behold#571: with no graph to show, the graph pane folds away and the runs and the log take its width.
912
1097
  if (typeof document !== "undefined" && document.body && document.body.classList) {
913
1098
  document.body.classList.toggle("k-nograph", !!vendor && !ok);