@jxsuite/studio 6.1.1 → 8.0.0

package/src/panels/tab-strip.ts

@@ -54,6 +54,9 @@ import {
   workspace,
 } from "../workspace/workspace";
 import { gridTabLabel } from "../grid/grid-source";
+import { workspaceTabOrder } from "../workspace/tab-workspace";
+import { workspaceHomeLabel } from "../workspace/workspace-ids";
+import { shell, workspaceDrawsTabStrip } from "../shell";
 import { entryDraftPill } from "../content/entry-editor";
 import { DRAFT_FIELD, isDraftEntry } from "../content/draft-state";
 import { entryFields } from "../content/entry-fields";
@@ -62,6 +65,8 @@ import { activeRegistry } from "../commands/active-registry";
 import { runActiveReported, runReported } from "../commands/run-reported";
 import { PRESET_LABELS } from "../workspace/pane-derive";
 import { localeLabel } from "@jxsuite/schema/locale";
+import { isBoolean } from "@jxsuite/schema/guards";
+import type { CommandArgValues } from "../commands/command-args";
 import { tabOfPane } from "../canvas/canvas-surface";
 import { mediaDisplayName } from "./shared";
 import { mountTabStripSurface } from "../surfaces/tab-strip";
@@ -183,8 +188,8 @@ export function mount(host: HTMLElement) {
       }
       _drag =
         source.data.type === "tab"
-          ? { kind: "tab", tabId: source.data.tabId as string }
-          : { kind: "file", path: source.data.path as string };
+          ? { kind: "tab", tabId: source.data.tabId }
+          : { kind: "file", path: source.data.path };
       // The tail target does not exist until a pane with no tabs is asked to grow one (§14.4's
       // "Between panes" row; `project` draws it).
       render();
@@ -198,6 +203,9 @@ export function mount(host: HTMLElement) {
       }
       const [target] = location.current.dropTargets;
       const data = target?.data;
+      /* SAFETY: a `tab-slot` record comes only from this module's own two `getData` closures (a
+         chip's in `adoptChip`, the tail's in `adoptStrip`), and both write a numeric `index` and a
+         string `paneId` beside that type. */
       _over =
         data?.type === "tab-slot"
           ? {
@@ -241,7 +249,11 @@ export function mount(host: HTMLElement) {
            so a fact about a pane it does not draw — or about a tab in another pane's strip — has
            no reader inside this effect. */
       }
+      // The strip draws the workspace on screen's tabs alone, so a switch repaints every strip.
+      void shell.workspace;
       for (const tab of workspace.tabs.values()) {
+        // A tab's workspace follows its editor (`project.json` is Styles' in its stylebook only).
+        void tab.session.ui.canvasMode;
         void tab.doc.dirty;
         void tab.documentPath;
         void tab.pinned;
@@ -249,7 +261,7 @@ export function mount(host: HTMLElement) {
         void tab.session.openedFrom;
         // The draft pill is on the chip, so the chip has to repaint when the flag changes — reading
         // The absent key tracks its ADDITION too, which is the transition that matters most.
-        void tab.doc.content?.frontmatter?.[DRAFT_FIELD];
+        void tab.doc.content.frontmatter[DRAFT_FIELD];
       }
       // An edit is a commitment: a preview tab with unsaved changes is no longer disposable, and
       // The dirty flags this effect already tracks are exactly the signal.
@@ -260,6 +272,7 @@ export function mount(host: HTMLElement) {
 }
 
 export function unmount() {
+  cancelMeasures();
   dismissOverflowMenu();
   dismissTabContextMenu();
   _scope?.stop();
@@ -296,6 +309,14 @@ function releaseHostDnD(host: HTMLElement): void {
 }
 
 function render() {
+  /* A workspace that draws no strip (Media, Styles, Publish) has its strips out of the grid
+     (`TAB_STRIP_HIDDEN_CLASS`), so painting them would be work nobody sees, and measuring a strip
+     that is not laid out reads zeros that flip the overflow chevron on every switch. They are left
+     standing as they were and repainted on the way back: this effect tracks `shell.workspace`.
+     A DERIVED pane is the exception. It follows the author into every workspace, and its row is
+     its derivation chip there (no tab of its own is the workspace's), which the frame keeps drawn
+     because it names the pane and holds the ✕ that closes it. So it is painted everywhere. */
+  const strips = workspaceDrawsTabStrip();
   /* One host draws ONE pane. While the shell has a single strip, both panes resolve to the same
      div — and the one whose tabs are on screen is the focused one, so it wins the tie. Without
      that rule the answer was render order, which is how the strip came to mark a tab active in a
@@ -309,7 +330,10 @@ function render() {
   }
   const drawn = new Set<string>();
   for (const [host, pane] of claims) {
-    paint(pane, host);
+    if (strips || pane.derived) {
+      paint(pane, host);
+    }
+    // Counted as drawn either way: a strip left standing is kept, not taken down below.
     _hosts.set(pane.id, host);
     drawn.add(pane.id);
   }
@@ -354,27 +378,81 @@ function paint(pane: Pane, host: HTMLElement): void {
 
   /* The strip is HELD — `surfaces/tab-strip.ts` takes it as the element is created — so this is an
      imperative USE of a node this module owns rather than a re-find of one it renders
-     (studio-ui-guidelines.md §9.4). The chip is asked for by the state the KIT puts on it, which is
-     the accessibility tree's own answer to "which tab is current".
+     (studio-ui-guidelines.md §9.4).
 
      THE REVEAL IS RECORDED ONLY WHEN THERE WAS A STRIP TO REVEAL IT IN. A mount is asynchronous,
      so the first paint into a fresh host has no document yet — and moving `_lastActive` there
      anyway would consume the transition and leave the chip off-screen with nothing left to notice.
      That is exactly the case a derived pane produces: its strip is created the moment its one tab
-     comes back. */
+     comes back.
+
+     The DECISION is taken here, in the paint that saw the transition, and only the scroll waits
+     for the frame: several paints can land in one task (a derivation and its return), and the
+     frame sees only the last of them, which may name the very tab `_lastActive` already held. */
   const strip = _strips.get(host)?.strip();
   if (strip && pane.activeTabId !== _lastActive.get(pane.id)) {
     _lastActive.set(pane.id, pane.activeTabId);
+    _revealPending.add(host);
+  }
+  scheduleMeasure(host);
+}
+
+/**
+ * The frame each host's strip is next read in: one per host, however many paints ask for it.
+ *
+ * Both reads the strip owes after a paint (bringing the active chip into view, and whether the
+ * chevron is needed) need LAYOUT, and both used to run inline at the tail of {@link paint}. A paint
+ * is never the last write of its task: a workspace switch or a tab activation goes on to swap the
+ * stage, the docks and the Inspector, so an inline read paid for a style recalculation of the whole
+ * half-written document (10 to 27 ms each, on every tab or workspace change in the perf trace), and
+ * the frame then paid again once the rest of the task had dirtied it. Read in the next frame, the
+ * strip shares the one layout the frame does anyway. The chevron already tolerated a lag (see
+ * {@link syncOverflow}), and the reveal still lands before that frame paints.
+ */
+const _measureFrames = new Map<HTMLElement, number>();
+
+/** Hosts whose active chip changed since their last frame, so the frame scrolls it into view. */
+const _revealPending = new Set<HTMLElement>();
+
+function scheduleMeasure(host: HTMLElement): void {
+  if (_measureFrames.has(host)) {
+    return;
+  }
+  _measureFrames.set(
+    host,
+    requestAnimationFrame(() => {
+      _measureFrames.delete(host);
+      const pane = drawnPane(host);
+      if (pane && workspaceDrawsTabStrip()) {
+        measureStrip(pane, host);
+      }
+      _revealPending.delete(host);
+    }),
+  );
+}
+
+/** Drop every pending read: the strips they would measure are going away. */
+function cancelMeasures(): void {
+  for (const frame of _measureFrames.values()) {
+    cancelAnimationFrame(frame);
+  }
+  _measureFrames.clear();
+  _revealPending.clear();
+}
+
+/** The reads {@link scheduleMeasure} runs for one host, in a frame of their own. */
+function measureStrip(pane: Pane, host: HTMLElement): void {
+  const strip = _strips.get(host)?.strip();
+  if (strip && _revealPending.has(host)) {
     /* Found by the id the DOCUMENT stamped, not by `aria-selected`. The kit is the single writer
        of a tab's selected state and it writes it on a MutationObserver when the tab SET moved — a
-       microtask later — so a strip whose one tab has just come back has no tab marked current at
-       the instant this runs. The flow already knows which chip it wants; asking the tree instead
-       is asking a question we have the answer to, and getting it one tick early. */
-    ([...strip.children] as HTMLElement[])
-      .find((chip) => chip.dataset.tab === pane.activeTabId)
+       microtask later — so a strip whose one tab has just come back may have no tab marked current
+       yet. The flow already knows which chip it wants; asking the tree instead is asking a
+       question we have the answer to. */
+    [...strip.children]
+      .find((chip) => chip instanceof HTMLElement && chip.dataset.tab === pane.activeTabId)
       ?.scrollIntoView({ block: "nearest", inline: "nearest" });
   }
-
   syncOverflow(pane, host);
 }
 
@@ -513,23 +591,31 @@ function project(pane: Pane): TabStripValues {
      that could put one there (`moveTabToPane`, through `revealOpenTab`) is reached solely by
      `openFileInPane`, which the follow calls for COMPANIONS. So the second disjunct is already
      total over a lens and the first chose nothing. */
-  if (derived && pane.tabOrder.length === 0) {
+  /* The tabs of the workspace on screen, in strip order. A pane's other tabs are another
+     workspace's: they keep their slots in `pane.tabOrder` and are simply not drawn. */
+  const visible = workspaceTabOrder(pane);
+  /* A derived pane none of whose tabs is in the workspace on screen draws its derivation chip too.
+     A COMPANION owns real tabs, and after a switch to Media or Publish the one it follows is
+     another workspace's: filtered away, it left a stage drawing a document under a blank row, with
+     no chip, no ✕ and no way out of the derivation. */
+  if (derived && visible.length === 0) {
     /* A COMPANION whose rule has not resolved reaches this too, and it has to. Its `tabOrder` is
        empty for a different reason than a lens's — the document it wants is not open YET, or the
        selection has nothing under it — and the branch below drew nothing: a pane with no chip,
        no ✕ and no way out, which `paneIsEmpty` will not collapse because the derivation counts as
        a subject. The chip is the pane's name and its exit.
        NO `_lastActive` / `_overflowing` RESET HERE, and both were, until each was shown to be a
-       write nothing can read. `_overflowing` is measured by {@link syncOverflow} at the end of
-       every ordinary render, inside the same synchronous call, so a stale `true` carried through a
-       derivation is corrected before any frame sees it. `_lastActive` cannot survive the round trip
+       write nothing can read. `_overflowing` is measured by {@link syncOverflow} in the frame
+       after every ordinary render, before that frame paints, so a stale `true` carried through a
+       derivation is corrected before anybody sees it. `_lastActive` cannot survive the round trip
        either: a tab can only come back through `insertIntoPane` and then `activateTab`, which are
        two reactive writes and therefore two renders, and the first of them lands here with
        `tabOrder` full and `activeTabId` still `null` — which resets the field anyway. Both were
        written as bookkeeping and both were unfalsifiable; the branch below owns the answer. */
     return derivationValues(pane, derived);
   }
-  if (pane.tabOrder.length === 0) {
+  // A non-derived pane whose every tab belongs elsewhere draws the same blank row an empty one does.
+  if (visible.length === 0) {
     /* An empty, non-derived pane WHILE A DRAG IS LIVE draws a `tabs` row with no chips instead of
        going blank: `blankValues` hides the row outright, and a hidden row has no `jx-tabs` element
        for `adoptStrip` to make a target of — so a tab dragged toward the empty primary beside a
@@ -564,7 +650,8 @@ function project(pane: Pane): TabStripValues {
     preset: "",
     stripLabel: stripLabel(pane),
     subject: "",
-    tabs: pane.tabOrder.flatMap((id, index) => chipView(pane, id, index, labels)),
+    // The chip's index is its slot in the pane's FULL order, which is what a drop is measured in.
+    tabs: visible.flatMap((id) => chipView(pane, id, pane.tabOrder.indexOf(id), labels)),
     trailing: _overflowing.get(pane.id) === true,
     trailingGlyph: "⌄",
     // ONE accessible name (`studio-ui-guidelines.md` §10): the glyph is hidden, so `title` is both
@@ -753,11 +840,11 @@ function syncDrag(): void {
 /**
  * Re-measure a pane's strip and re-project once if the chevron's presence changed.
  *
- * Measurement can only happen after the document has written the DOM, so this runs at the tail of
- * {@link paint} and guards its own re-entry on the boolean actually flipping — the chevron cannot
- * oscillate. Before the mount resolves there is no strip to measure and nothing to correct: the
- * next repaint measures it, and a strip that overflows on its first frame has no hidden tab a
- * reader could be looking for yet.
+ * Measurement can only happen after the document has written the DOM, so this runs in the frame
+ * after a {@link paint} ({@link scheduleMeasure}) and guards its own re-entry on the boolean
+ * actually flipping — the chevron cannot oscillate. Before the mount resolves there is no strip to
+ * measure and nothing to correct: the next repaint measures it, and a strip that overflows on its
+ * first frame has no hidden tab a reader could be looking for yet.
  */
 function syncOverflow(pane: Pane, host: HTMLElement) {
   const surface = _strips.get(host);
@@ -801,8 +888,8 @@ function onWheel(e: WheelEvent) {
   if (e.ctrlKey) {
     return;
   }
-  const el = e.currentTarget as HTMLElement;
-  if (el.scrollWidth <= el.clientWidth) {
+  const el = e.currentTarget;
+  if (!(el instanceof HTMLElement) || el.scrollWidth <= el.clientWidth) {
     return;
   }
   const delta = Math.abs(e.deltaX) > Math.abs(e.deltaY) ? e.deltaX : e.deltaY;
@@ -832,9 +919,13 @@ export function hiddenTabIds(paneId: string = workspace.activePaneId): string[]
   const left = strip.scrollLeft;
   const right = left + strip.clientWidth;
   const hidden: string[] = [];
-  const chips = [...strip.querySelectorAll('[part="tab"]')] as HTMLElement[];
+  /* Typed, not filtered: a chip's position is what pairs it with the strip's drawn order, so dropping
+     a node here would shift every later chip onto the wrong tab id. The drawn order is the
+     workspace's tabs alone, which is what `project` drew. */
+  const drawn = workspaceTabOrder(pane);
+  const chips = [...strip.querySelectorAll<HTMLElement>('[part="tab"]')];
   for (const [index, chip] of chips.entries()) {
-    const id = pane.tabOrder[index];
+    const id = drawn[index];
     if (id && (chip.offsetLeft < left || chip.offsetLeft + chip.offsetWidth > right)) {
       hidden.push(id);
     }
@@ -870,7 +961,7 @@ export function dismissOverflowMenu() {
 function openOverflowMenu(pane: Pane, labels: Map<string, string>, anchorEl: HTMLElement | null) {
   dismissOverflowMenu();
   const hidden = hiddenTabIds(pane.id);
-  const ids = hidden.length > 0 ? hidden : [...pane.tabOrder];
+  const ids = hidden.length > 0 ? hidden : workspaceTabOrder(pane);
   const anchor = rectOf(anchorEl ?? document.body);
   _overflowHandle = openMenu({
     /* The trigger says "Show hidden tabs" and this is the panel it opens, so it takes the same
@@ -889,8 +980,8 @@ function openOverflowMenu(pane: Pane, labels: Map<string, string>, anchorEl: HTM
     place: (box) => ({ x: Math.max(4, anchor.right - box.width), y: anchor.bottom }),
     placement: "block-end span-inline-start",
     region: "tab-overflow",
-    rows: ids.map((id) => ({
-      checked: (id === pane.activeTabId ? "true" : "false") as "true" | "false",
+    rows: ids.map((id): MenuRowProjection => ({
+      checked: id === pane.activeTabId ? "true" : "false",
       destructive: false,
       disabled: false,
       dividerAbove: false,
@@ -931,8 +1022,8 @@ export function dismissTabContextMenu() {
  * where it lands (`content/draft-state.ts` says why), so the row offers the flip of what is true
  * now and {@link statedChecked} reads the current state back out of it for the checkmark.
  */
-function tabRowFacts(tab: Tab): Record<string, unknown> {
-  const facts: Record<string, unknown> = {};
+function tabRowFacts(tab: Tab): CommandArgValues {
+  const facts: CommandArgValues = {};
   if (collectionOfPath(tab.documentPath)) {
     facts.draft = !isDraftEntry(entryFields(tab));
   }
@@ -961,14 +1052,14 @@ function tabRowFacts(tab: Tab): Record<string, unknown> {
  * already knows how to announce — and the five rows that carry no state stay plain `menuitem`s,
  * which `selects` on the old menu would have made impossible.
  */
-function statedChecked(args: Record<string, unknown>): "true" | "false" | undefined {
+function statedChecked(args: CommandArgValues): "true" | "false" | undefined {
   const entries = Object.entries(args);
-  const only = entries.length === 1 ? entries[0] : undefined;
-  if (!only || typeof only[1] !== "boolean") {
+  const value = entries.length === 1 ? entries[0]?.[1] : undefined;
+  if (!isBoolean(value)) {
     return undefined;
   }
   // The fact is the state the row would REACH, so the state it is in now is the negation.
-  return only[1] ? "false" : "true";
+  return value ? "false" : "true";
 }
 
 /**
@@ -989,13 +1080,11 @@ function placedTabItems(tab: Tab): MenuRowProjection[] {
   const items: MenuRowProjection[] = [];
   let group: string | undefined;
   for (const command of registry.forPlacement("context/tab")) {
-    const schema = command.args as
-      | { properties?: Record<string, unknown>; required?: readonly string[] }
-      | undefined;
+    const schema = command.args;
     if (!(schema?.required ?? []).every((key) => key in facts)) {
       continue;
     }
-    const args: Record<string, unknown> = {};
+    const args: CommandArgValues = {};
     for (const key of Object.keys(schema?.properties ?? {})) {
       if (key in facts) {
         args[key] = facts[key];
@@ -1005,21 +1094,26 @@ function placedTabItems(tab: Tab): MenuRowProjection[] {
     ({ group } = command);
     const reason = registry.disabledReason(command.id);
     const checked = statedChecked(args);
-    items.push({
+    const row: Omit<MenuRowProjection, "disabled"> = {
       destructive: command.destructive === true,
       dividerAbove,
       id: command.id,
       title: command.title,
-      ...(checked === undefined ? {} : { checked }),
-      ...(reason === undefined
+    };
+    if (checked !== undefined) {
+      row.checked = checked;
+    }
+    items.push(
+      reason === undefined
         ? {
+            ...row,
             disabled: false,
             run: () => {
               void runReported(registry, command.id, args, "Tabs");
             },
           }
-        : { disabled: true, requires: reason }),
-    });
+        : { ...row, disabled: true, requires: reason },
+    );
   }
   return items;
 }
@@ -1193,7 +1287,7 @@ function tabLabels(pane: Pane): Map<string, string> {
         ? [
             {
               documentPath: tab.documentPath,
-              fallback: gridTabLabel(tab.id) ?? "Untitled",
+              fallback: gridTabLabel(tab.id) ?? workspaceHomeLabel(tab.id) ?? "Untitled",
               id,
             },
           ]
@@ -1209,7 +1303,7 @@ function tabLabels(pane: Pane): Map<string, string> {
  * @returns {string}
  */
 function tabTooltip(tab: Tab): string {
-  const base = tab.documentPath || gridTabLabel(tab.id) || "Untitled";
+  const base = tab.documentPath || gridTabLabel(tab.id) || workspaceHomeLabel(tab.id) || "Untitled";
   const origin = tab.session.openedFrom;
   const withOrigin = origin?.documentPath ? `${base}\nOpened from ${origin.documentPath}` : base;
   return tab.preview ? `${withOrigin}\nPreview — double-click to keep open` : withOrigin;
@@ -1270,7 +1364,7 @@ export function shouldWarnOnClose(tab: Tab): boolean {
   if (residue) {
     return true;
   }
-  const peersHere = state.peers.filter((p) => p.state?.focusedPath === tab.documentPath);
+  const peersHere = state.peers.filter((p) => p.state.focusedPath === tab.documentPath);
   return peersHere.length === 0;
 }
 

package/src/platform-errors.ts

@@ -14,6 +14,8 @@
 
 import { problemSlug } from "@jxsuite/protocol";
 import type { OfferedAction, RetryHint } from "@jxsuite/protocol";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
 
 export interface PlatformErrorInfo {
   code?: string;
@@ -32,36 +34,44 @@ const RETRY_HINTS = new Set<string>(["reload", "repeat", "none"]);
  * The offered actions a wire value holds, each one checked: an action needs an `id` and a `label`
  * to be drawn at all, and anything else it carries is kept only when it has the right type. A
  * malformed entry is dropped rather than drawn as a button that does nothing.
+ *
+ * A typed `OfferedAction[]` is accepted too, and checked the same way: it is what a response body
+ * cast to its protocol type holds, and nothing has verified that cast.
  */
-export function offeredActions(value: unknown): OfferedAction[] {
+export function offeredActions(
+  value: JsonValue | readonly OfferedAction[] | undefined,
+): OfferedAction[] {
   if (!Array.isArray(value)) {
     return [];
   }
-  return value.flatMap((entry): OfferedAction[] => {
-    const raw = entry as Partial<Record<keyof OfferedAction, unknown>> | null;
-    if (
-      !raw ||
-      typeof raw.id !== "string" ||
-      !raw.id ||
-      typeof raw.label !== "string" ||
-      !raw.label
-    ) {
+  const entries: readonly (JsonValue | OfferedAction)[] = value;
+  return entries.flatMap((entry): OfferedAction[] => {
+    if (!isJsonObject(entry)) {
+      return [];
+    }
+    const { href, id, label, primary } = entry;
+    if (!isString(id) || !id || !isString(label) || !label) {
       return [];
     }
-    return [
-      {
-        id: raw.id,
-        label: raw.label,
-        ...(typeof raw.href === "string" && raw.href ? { href: raw.href } : {}),
-        ...(raw.primary === true ? { primary: true } : {}),
-      },
-    ];
+    const action: OfferedAction = { id, label };
+    if (isString(href) && href) {
+      action.href = href;
+    }
+    if (primary === true) {
+      action.primary = true;
+    }
+    return [action];
   });
 }
 
+/** Whether a value names one of the retry hints this client knows. */
+function isRetryHint(value: JsonValue | undefined): value is RetryHint {
+  return isString(value) && RETRY_HINTS.has(value);
+}
+
 /** The retry hint a wire value names, or undefined when it names none we know. */
-export function retryHint(value: unknown): RetryHint | undefined {
-  return typeof value === "string" && RETRY_HINTS.has(value) ? (value as RetryHint) : undefined;
+export function retryHint(value: JsonValue | undefined): RetryHint | undefined {
+  return isRetryHint(value) ? value : undefined;
 }
 
 /**
@@ -74,33 +84,37 @@ function normalizeCode(value: string): string {
 }
 
 /** Machine-readable fields carried by a thrown platform error (empty object when none). */
-export function platformErrorInfo(error: unknown): PlatformErrorInfo {
-  if (!error || typeof error !== "object") {
+export function platformErrorInfo(cause: unknown): PlatformErrorInfo {
+  /* An Error carrying the members an adapter assigned onto it passes as a JSON object here: every
+     member below is read through a check that accepts any value, so nothing trusts that typing. */
+  if (!isJsonObject(cause)) {
     return {};
   }
-  const { actions, code, heading, installUrl, retry, type } = error as {
-    actions?: unknown;
-    code?: unknown;
-    heading?: unknown;
-    installUrl?: unknown;
-    retry?: unknown;
-    type?: unknown;
-  };
-  const hint = retryHint(retry);
+  const { actions, code, heading, installUrl, retry, type } = cause;
+  const info: PlatformErrorInfo = {};
   // A problem type wins over a legacy code: it is the shape the backend is migrating toward.
-  const derived = problemSlug(type) ?? (typeof code === "string" ? normalizeCode(code) : null);
-  return {
-    ...(derived === null ? {} : { code: derived }),
-    ...(typeof installUrl === "string" ? { installUrl } : {}),
-    ...(actions === undefined ? {} : { actions: offeredActions(actions) }),
-    ...(typeof heading === "string" && heading ? { heading } : {}),
-    ...(hint === undefined ? {} : { retry: hint }),
-  };
+  const derived = problemSlug(type) ?? (isString(code) ? normalizeCode(code) : null);
+  if (derived !== null) {
+    info.code = derived;
+  }
+  if (isString(installUrl)) {
+    info.installUrl = installUrl;
+  }
+  if (actions !== undefined) {
+    info.actions = offeredActions(actions);
+  }
+  if (isString(heading) && heading) {
+    info.heading = heading;
+  }
+  if (isRetryHint(retry)) {
+    info.retry = retry;
+  }
+  return info;
 }
 
 /** The GitHub-App install link when the error is the structured needs-installation 403. */
-export function installUrlOf(error: unknown): string | null {
-  const info = platformErrorInfo(error);
+export function installUrlOf(cause: unknown): string | null {
+  const info = platformErrorInfo(cause);
   return info.code === "needs-installation-access" && info.installUrl ? info.installUrl : null;
 }
 
@@ -108,6 +122,6 @@ export function installUrlOf(error: unknown): string | null {
  * True when the error is an `action-required` refusal (HTTP 403, desktop.md §10.4) — whether the
  * backend sent the problem type or the legacy `action_required` code.
  */
-export function isActionRequired(error: unknown): boolean {
-  return platformErrorInfo(error).code === "action-required";
+export function isActionRequired(cause: unknown): boolean {
+  return platformErrorInfo(cause).code === "action-required";
 }