Help add-in hover help and a detachable help window, exe-run reporting in the harness, and 997 reproducibility bugs

.github/workflows/checks.yml

@@ -97,7 +97,11 @@ jobs:
         # broken link still produces a site worth inspecting -- so the
         # step fails on the exit code: 1 when the check found a problem,
         # 2 when the build could not run.
-        run: node builder/tbdocs.mjs --src docs --no-fetch-assets --check-audit-index
+        #
+        # --no-help-archive: a local build ends by zipping the offline tree
+        # for the IDE help add-in. CI has no use for that archive and must
+        # not spend time on it.
+        run: node builder/tbdocs.mjs --src docs --no-fetch-assets --no-help-archive --check-audit-index
       # The gates both workflows run, in one list: see
       # .github/actions/run-gates/action.yml, which check_ci_workflows.mjs
       # checks against test.bat and check.bat. Each gate is its own group in

.github/workflows/tbdocs-gh-pages.yml

@@ -92,7 +92,11 @@ jobs:
         # baseurl off the config it just built with. Only the
         # online tree gets a base path -- the offline tree's links are all
         # relative after the rewrite.
-        run: node builder/tbdocs.mjs --src docs --url '${{ steps.pages.outputs.origin }}' --baseurl '${{ steps.pages.outputs.base_path }}' --no-fetch-assets --check-audit-index
+        #
+        # --no-help-archive: a local build ends by zipping the offline tree
+        # for the IDE help add-in. CI has no use for that archive and must
+        # not spend time on it.
+        run: node builder/tbdocs.mjs --src docs --url '${{ steps.pages.outputs.origin }}' --baseurl '${{ steps.pages.outputs.base_path }}' --no-fetch-assets --no-help-archive --check-audit-index
       # The gates both workflows run, in one list: see
       # .github/actions/run-gates/action.yml, which check_ci_workflows.mjs
       # checks against test.bat and check.bat. checks.yml runs only on pull

.gitignore

@@ -28,8 +28,9 @@ indexer/.packages/
 # docs/assets/fonts/ -- only the archives are throwaway.
 /.font-cache/
 
-# The help add-in's documentation archive is built by scripts/build_help_archive.mjs
-# from docs/_site-offline, and is too large to commit.
+# The help add-in's documentation archive is written by a local build of the
+# documentation (builder/help-archive-step.mjs) from docs/_site-offline, and is
+# too large to commit.
 /add-in/Resources/HELP/
 
 # A bug reproducer's zip is only for attaching to its GitHub issue (see

WIP.Typography.md

@@ -27,11 +27,12 @@ prefer that shape where the layout allows it.
 **A footnote back-link shows the hazard.** It is a bare inline `<a>` holding a
 single U+21A9 with no padding, so its target is whatever box the font gives that
 glyph: 12.09 x 19 on Segoe UI, 12.09 x 15 on Liberation Sans, 15.97 x 17 on
-Inter. **None of those meets 24 x 24.** It passed on axe's *spacing* exception
---- a 24px circle centred on the target clears its neighbours --- until Inter's
-arrow, 3.9px wider, moved the centre far enough to intersect one. The fix sizes
-the link outright (`display: inline-block; min-width/min-height: 24px`) rather
-than restoring the clearance.
+Inter. **None of those meets 24 x 24.** It can pass on axe's *spacing* exception
+--- a 24px circle centred on the target clears its neighbours --- and a wider
+glyph fails it: Inter's arrow is 3.9px wider than Segoe UI's, enough to move the
+centre far enough to intersect a neighbour. The link is sized outright
+(`display: inline-block; min-width/min-height: 24px`) rather than relying on the
+clearance.
 
 Two rules follow. **Run the full sweep after any change that moves type
 metrics**: the thirteen-page sample stays clean through such a change and would

add-in/Resources/SCRIPTS/hoverhelp.js

@@ -0,0 +1,76 @@
+var sink = this.parentNode, on = $ON$, site = "$SITE$";
+var old = window.tbDocsHoverHelp;
+if (old) {
+  old.provider.dispose();
+  window.removeEventListener("click", old.click, true);
+  for (var k in old.pending) old.pending[k]("");
+  window.tbDocsHoverHelp = null;
+}
+// The IDE's dock resizers and drop targets lie over the part of a hover that
+// reaches past the code editor, transparent but taking the mouse, so that
+// Monaco takes the mouse reaching them as leaving the editor and hides the
+// hover. Drawn above them, the hover keeps the mouse. This is for every hover,
+// with hover help on or off, until the IDE is fixed (twinbasic/twinbasic#2506).
+if (!document.getElementById("tbDocsHoverStay")) {
+  var stay = document.head.appendChild(document.createElement("style"));
+  stay.id = "tbDocsHoverStay";
+  stay.textContent = ".monaco-editor .monaco-hover { z-index: 100000 !important; }";
+}
+if (on) {
+  var pending = {}, seq = 0;
+  var provider = monaco.languages.registerHoverProvider("twinbasic", {
+    provideHover: function (model, position) {
+      var node;
+      try {
+        if (typeof editor === "undefined" || editor.getModel() !== model) return null;
+        var lang = model.getLanguageId ? model.getLanguageId() : model.getModeId();
+        if (lang !== "twinbasic") return null;
+        node = openEditors.selectedEditorNode;
+        var ws = lspSocket.webSocket;
+        if (!node || !node.fileNode || !ws || !ws.socket || ws.socket.readyState !== 1 || ws.hasErrored) return null;
+      } catch (e) {
+        return null;
+      }
+      return new Promise(function (resolve) {
+        var n = ++seq;
+        var done = function (markdown) {
+          if (!pending[n]) return;
+          delete pending[n];
+          resolve(markdown ? { contents: [{ value: markdown }] } : null);
+        };
+        pending[n] = done;
+        setTimeout(function () { done(""); }, 4000);
+        var line = model.getLineContent(position.lineNumber), column = position.column;
+        lspSocket.request("textDocument/hover", {
+          textDocument: { uri: "twinbasic:" + node.fileNode.getFullPath() },
+          position: { line: position.lineNumber - 1, character: position.column - 1 }
+        }, function (m) {
+          var r = m && m.result;
+          var hover = r && r.contents && typeof r.contents.value === "string" ? r.contents.value : "";
+          try {
+            sink.tbDocsHoverHelp({ kind: "ask", seq: n, line: line, column: column, hover: hover });
+          } catch (e) {
+            done("");
+          }
+        });
+      });
+    }
+  });
+  var click = function (e) {
+    var a = e.target && e.target.closest ? e.target.closest(".monaco-hover a") : null;
+    var href = a ? a.getAttribute("data-href") || "" : "";
+    if (href.indexOf(site + "/") !== 0) return;
+    e.preventDefault();
+    e.stopPropagation();
+    try {
+      sink.tbDocsHoverHelp({ kind: "open", path: decodeURIComponent(href.substring(site.length)) });
+    } catch (x) {}
+  };
+  window.addEventListener("click", click, true);
+  window.tbDocsHoverHelp = {
+    provider: provider,
+    click: click,
+    pending: pending,
+    answer: function (n, markdown) { if (pending[n]) pending[n](markdown); }
+  };
+}

add-in/Resources/SHELL/shell.css

@@ -0,0 +1,139 @@
+/* What the IDE's document gives the help pane and a page of its own does not:
+   the page's margin, height and font, the results list, which here is a
+   plain element holding the same .hit rows the IDE's list view draws, and the
+   title bar, drawn in the style of the IDE's tool-window header. The colours
+   are the IDE theme's custom properties, which the add-in sends as a :root
+   rule (ThemeCss). The plain palettes are for a theme it cannot find, and
+   :where gives them no weight, so the theme's rule wins whichever comes
+   first. */
+:where(:root[data-group="light"]) {
+  --themeToolWindowBodyForeColor: rgb(44, 44, 44);
+  --themeGeneralPanelBackColor: rgb(255, 255, 255);
+  --themePropertySheetValueBorderColor: 1px solid rgb(213, 210, 210);
+  --themeTreeItemHoverBackColor: rgb(219, 219, 219);
+  --themePanelHeaderBackColor: #bfcddb;
+  --themePanelHeaderTextColor: rgb(56, 56, 56);
+  --themePanelHeaderFontSize: 85%;
+  --themePanelHeaderBorderTop: 1px solid #f4f4f4;
+  --themePanelHeaderBorderLeft: 1px solid #a8a8a8;
+}
+
+:where(:root[data-group="dark"]) {
+  --themeToolWindowBodyForeColor: rgb(214, 214, 214);
+  --themeGeneralPanelBackColor: rgb(43, 43, 43);
+  --themePropertySheetValueBorderColor: 1px solid rgb(96, 95, 95);
+  --themeTreeItemHoverBackColor: rgb(113, 113, 113);
+  --themePanelHeaderBackColor: rgb(75, 67, 67);
+  --themePanelHeaderTextColor: rgb(236, 233, 233);
+  --themePanelHeaderFontSize: 100%;
+  --themePanelHeaderBorderTop: 1px solid rgb(100, 98, 98);
+}
+
+html,
+body {
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  overflow: hidden;
+  font: 13px "Segoe UI", system-ui, sans-serif;
+}
+
+#helpResults {
+  overflow-y: auto;
+}
+
+/* The title bar: one row, the IDE's tool-window header (.sectionHeader) with
+   its colours, borders, padding, font and grip, and the window's buttons where
+   the IDE has its close button. The IDE's row is 20px high, the height of its
+   close button with its margins. The whole bar, grip included, drags the
+   window (shell.js). With the Windows title bar (data-chrome="native") the bar
+   is not drawn, and Attach is in the search bar. */
+#helpTitleBar {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  box-sizing: border-box;
+  padding: var(--themePanelHeaderPadding, 2px 0 5px 0);
+  background-color: var(--themePanelHeaderBackColor);
+  color: var(--themePanelHeaderTextColor);
+  font-size: var(--themePanelHeaderFontSize, 100%);
+  font-weight: 600;
+  border-top: var(--themePanelHeaderBorderTop);
+  border-left: var(--themePanelHeaderBorderLeft);
+  border-right: var(--themePanelHeaderBorderRight);
+  border-bottom: var(--themePanelHeaderBorderBottom);
+  cursor: default;
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+html[data-chrome="native"] #helpTitleBar {
+  display: none;
+}
+
+/* The grip is 13px, drawn in the title's colour at about the weight the IDE
+   gives its own, and 5px in from the edge; the title starts 7px after it. */
+#helpGrip {
+  flex: 0 0 auto;
+  width: 13px;
+  height: 13px;
+  margin: 0 2px 0 5px;
+  fill: currentColor;
+  opacity: 0.7;
+}
+
+#helpTitle {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 0 5px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+#helpTitleBar .titleButton {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  width: 24px;
+  height: 20px;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  color: var(--themePanelCloseButtonForeColor, currentColor);
+}
+
+#helpTitleBar .titleButton:hover {
+  background: color-mix(in srgb, currentColor 20%, transparent);
+}
+
+.titleButton svg {
+  width: 12px;
+  height: 12px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1;
+}
+
+.titleButton svg .fill {
+  fill: currentColor;
+  stroke: none;
+}
+
+/* Attach is an icon in the title bar and a word in the search bar. */
+#helpTitleBar #helpAttach .label,
+#helpBar #helpAttach .dock {
+  display: none;
+}
+
+/* The Maximize button shows Restore while the window is maximized. */
+html[data-state="max"] #helpMaximize .maximize,
+html:not([data-state="max"]) #helpMaximize .restore {
+  display: none;
+}

add-in/Resources/SHELL/shell.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html data-group="light" data-chrome="custom" data-state="normal">
+<head>
+<meta charset="utf-8">
+<title>twinBASIC Help</title>
+<style>$PANE_CSS$</style>
+<style>$SHELL_CSS$</style>
+<style id="theme"></style>
+</head>
+<body>
+<div id="helpWrap">
+  <div id="helpTitleBar">
+    <svg id="helpGrip" viewBox="0 0 13 13" aria-hidden="true"><rect x="2.4" y="1.8" width="3.2" height="3.2" rx="0.7"/><rect x="7.2" y="1.8" width="3.2" height="3.2" rx="0.7"/><rect x="2.4" y="5.8" width="3.2" height="3.2" rx="0.7"/><rect x="7.2" y="5.8" width="3.2" height="3.2" rx="0.7"/><rect x="2.4" y="9.8" width="3.2" height="3.2" rx="0.7"/><rect x="7.2" y="9.8" width="3.2" height="3.2" rx="0.7"/></svg>
+    <div id="helpTitle">TWINBASIC HELP</div>
+    <button id="helpAttach" class="titleButton" title="Attach to the IDE" aria-label="Attach to the IDE"><svg class="dock" viewBox="0 0 12 12" aria-hidden="true"><path d="M1.5 2.5h9v7h-9z"/><path class="fill" d="M1.5 2.5h3.5v7h-3.5z"/></svg><span class="label">Attach</span></button>
+    <button id="helpMinimize" class="titleButton" title="Minimize" aria-label="Minimize"><svg viewBox="0 0 12 12" aria-hidden="true"><path d="M2 6.5h8"/></svg></button>
+    <button id="helpMaximize" class="titleButton" title="Maximize" aria-label="Maximize"><svg class="maximize" viewBox="0 0 12 12" aria-hidden="true"><path d="M2.5 2.5h7v7h-7z"/></svg><svg class="restore" viewBox="0 0 12 12" aria-hidden="true"><path d="M2.5 4.5h5v5h-5zM4.5 4.5v-2h5v5h-2"/></svg></button>
+    <button id="helpClose" class="titleButton" title="Close" aria-label="Close"><svg viewBox="0 0 12 12" aria-hidden="true"><path d="M2.5 2.5l7 7M9.5 2.5l-7 7"/></svg></button>
+  </div>
+  <div id="helpBar">
+    <input id="helpSearch" type="search" placeholder="Search the documentation">
+    <button id="helpBrowser">Open in browser</button>
+    <label id="helpHoverLabel"><input id="helpHover" type="checkbox"><span id="helpHoverText">Hover help</span></label>
+  </div>
+  <div id="helpResults" style="display: none"></div>
+  <div id="helpSummary" style="display: none"></div>
+  <iframe id="helpPage"></iframe>
+</div>
+<script>$SCRIPT$</script>
+</body>
+</html>