@jxsuite/studio 6.1.0 → 6.1.2

package/src/panels/formula-workspace.ts

@@ -42,10 +42,11 @@
  */
 
 import { nothing } from "lit-html";
-import { getEventBinding, isExpressionDef, isJsonObject } from "@jxsuite/schema/guards";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { getEventBinding, isExpressionDef, isJsonObject, isString } from "@jxsuite/schema/guards";
 
 import { effect, effectScope, shallowRef } from "../reactivity";
-import { getNodeAtPath, updateUi } from "../store";
+import { updateUi } from "../store";
 import { activeTab } from "../workspace/workspace";
 import { mutateAddDef, mutateUpdateDef, mutateUpdateProperty, transactDoc } from "../tabs/transact";
 import { setBottomTab } from "../shell";
@@ -69,14 +70,19 @@ import {
   stringProperty,
 } from "../commands/command-args";
 
-import type { JxNodeValue } from "../tabs/transact";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { PanelBody } from "./panel-registry";
 import type { ExpressionPreview } from "../services/preview-eval";
-import type { FormulaEditDef, FunctionEditDef, JsonValue } from "../types";
+import type { FormulaEditDef, FunctionEditDef } from "../types";
 import type { Tab } from "../tabs/tab";
-import type { JxStateDefinition } from "@jxsuite/schema/types";
+import type {
+  JsonObject,
+  JsonValue,
+  JxEventBinding,
+  JxStateDefinition,
+} from "@jxsuite/schema/types";
 import type { EffectScope } from "@vue/reactivity";
+import type { ScopeValue } from "../editor/merge-tags";
 import type {
   LogicChipView,
   LogicScopeEntryView,
@@ -125,10 +131,10 @@ export function logicTarget(tab: Tab | null = activeTab.value): LogicTarget | nu
     return null;
   }
   if (ui.editingFunction) {
-    return { editing: ui.editingFunction as FunctionEditDef, surface: "function" };
+    return { editing: ui.editingFunction, surface: "function" };
   }
   if (ui.editingFormula) {
-    return { editing: ui.editingFormula as FormulaEditDef, surface: "formula" };
+    return { editing: ui.editingFormula, surface: "formula" };
   }
   return null;
 }
@@ -176,25 +182,35 @@ export function openLogicTarget(target: LogicTarget): void {
   revealLogicPanel();
 }
 
-function isExprNode(value: unknown): value is Record<string, unknown> {
-  return isJsonObject(value) && typeof value.operator === "string";
+/** An expression node: a plain object naming its `operator`. */
+function isExprNode(value: JsonValue | undefined): value is JsonObject {
+  return isJsonObject(value) && isString(value.operator);
 }
 
 // ─── Document access ─────────────────────────────────────────────────────────
 
+/**
+ * The `$expression` of an expression entry or binding, as the JSON object it is; null for anything
+ * else. `isExpressionDef` has already checked it is a plain object, and the guard carries that to
+ * the type.
+ */
+function expressionOf(value: JxStateDefinition | JxEventBinding | undefined): JsonObject | null {
+  if (!isExpressionDef(value)) {
+    return null;
+  }
+  const { $expression } = value;
+  return isJsonObject($expression) ? $expression : null;
+}
+
 /** Read the workspace target's current root expression node from the document. */
-export function formulaRoot(tab: Tab, editing: FormulaEditDef): Record<string, unknown> | null {
+export function formulaRoot(tab: Tab, editing: FormulaEditDef): JsonObject | null {
   const { document } = tab.doc;
   if (editing.type === "def" && editing.defName) {
-    const def = document?.state?.[editing.defName];
-    return isExpressionDef(def) ? (def.$expression as unknown as Record<string, unknown>) : null;
+    return expressionOf(document.state?.[editing.defName]);
   }
   if (editing.type === "event" && editing.path && editing.eventKey) {
     const node = getNodeAtPath(document, editing.path);
-    const binding = node ? getEventBinding(node, editing.eventKey) : undefined;
-    return isExpressionDef(binding)
-      ? (binding.$expression as unknown as Record<string, unknown>)
-      : null;
+    return expressionOf(node ? getEventBinding(node, editing.eventKey) : undefined);
   }
   return null;
 }
@@ -203,18 +219,18 @@ export function formulaRoot(tab: Tab, editing: FormulaEditDef): Record<string, u
  * Resolve a chip selection to its editable node: the deepest expression-node prefix of `path` (head
  * chips target ref/literal operands; stale paths fall back toward the root).
  */
-function resolveSelection(
-  root: Record<string, unknown>,
-  path: NodePath,
-): { node: Record<string, unknown>; path: NodePath } {
-  let current: unknown = root;
-  let node: Record<string, unknown> = root;
+function resolveSelection(root: JsonObject, path: NodePath) {
+  let current: JsonValue | undefined = root;
+  let node = root;
   let nodePath: NodePath = [];
   for (const [i, seg] of path.entries()) {
-    if (!current || typeof current !== "object") {
+    if (Array.isArray(current)) {
+      current = current[Number(seg)];
+    } else if (isJsonObject(current)) {
+      current = current[String(seg)];
+    } else {
       break;
     }
-    current = (current as Record<string, unknown>)[seg as keyof typeof current];
     if (isExprNode(current)) {
       node = current;
       nodePath = path.slice(0, i + 1);
@@ -224,30 +240,28 @@ function resolveSelection(
 }
 
 /** Immutably replace the value at `path` within `node` (object keys / array indexes). */
-function replaceAtPath(node: unknown, path: NodePath, value: unknown): unknown {
-  if (path.length === 0) {
+function replaceAtPath(node: JsonValue | undefined, path: NodePath, value: JsonValue): JsonValue {
+  const [head, ...rest] = path;
+  if (head === undefined) {
     return value;
   }
-  const [head, ...rest] = path as [string | number, ...NodePath];
   if (Array.isArray(node)) {
-    const copy = [...(node as unknown[])];
+    const copy = [...node];
     copy[Number(head)] = replaceAtPath(copy[Number(head)], rest, value);
     return copy;
   }
-  const base: Record<string, unknown> = isJsonObject(node) ? node : {};
-  return { ...base, [head]: replaceAtPath(base[head as string], rest, value) };
+  const base: JsonObject = isJsonObject(node) ? node : {};
+  return { ...base, [head]: replaceAtPath(base[head], rest, value) };
 }
 
 /** Write the whole updated root node back to the document position (one undo step). */
-function writeRoot(tab: Tab, editing: FormulaEditDef, newRoot: unknown) {
+function writeRoot(tab: Tab, editing: FormulaEditDef, newRoot: JsonValue) {
   if (editing.type === "def" && editing.defName) {
     const { defName } = editing;
-    transactDoc(tab, (t) => mutateUpdateDef(t, defName, { $expression: newRoot as JsonValue }));
+    transactDoc(tab, (t) => mutateUpdateDef(t, defName, { $expression: newRoot }));
   } else if (editing.type === "event" && editing.path && editing.eventKey) {
     const { eventKey, path } = editing;
-    transactDoc(tab, (t) =>
-      mutateUpdateProperty(t, path, eventKey, { $expression: newRoot } as JxNodeValue),
-    );
+    transactDoc(tab, (t) => mutateUpdateProperty(t, path, eventKey, { $expression: newRoot }));
   }
 }
 
@@ -295,8 +309,8 @@ function selectionKey(editing: FormulaEditDef): string {
 interface Resolved {
   tab: Tab;
   editing: FormulaEditDef;
-  root: Record<string, unknown>;
-  selected: Record<string, unknown>;
+  root: JsonObject;
+  selected: JsonObject;
   selectedPath: NodePath;
   stateEntries: Record<string, JxStateDefinition>;
   preview: ExpressionPreview | null;
@@ -304,19 +318,27 @@ interface Resolved {
   /** Chip key → node path, so a chip click needs no path parsing (a `switch` case may hold "/"). */
   chipPaths: Map<string, NodePath>;
   /** Rail entry name → the value its tree draws. */
-  scopeValues: Map<string, unknown>;
+  scopeValues: Map<string, ScopeValue>;
 }
 
 let _resolved: Resolved | null = null;
 
-/** Replace the selected sub-node inside the root and write the whole root back. */
-function writeSelected(next: unknown): void {
+/**
+ * Replace the selected sub-node inside the root and write the whole root back.
+ *
+ * Typed as the expression editor's own change callback, which is one of its two callers; the other
+ * is a catalog pick's `onChange`.
+ */
+const writeSelected: Parameters<typeof mountExpressionEditor>[2] = (next) => {
   const held = _resolved;
   if (!held) {
     return;
   }
-  writeRoot(held.tab, held.editing, replaceAtPath(held.root, held.selectedPath, next));
-}
+  /* SAFETY: both callers hand back an expression node built of JSON operator/operand values: the
+     expression editor's edited tree, and the node a catalog pick inserts (a JxExpressionNode). */
+  const node = next as JsonValue;
+  writeRoot(held.tab, held.editing, replaceAtPath(held.root, held.selectedPath, node));
+};
 
 // ─── The projection ──────────────────────────────────────────────────────────
 
@@ -354,13 +376,13 @@ function resultOf(
 }
 
 /** The live data context — a SECOND opinion now that the page itself is on screen, not the only one. */
-function railOf(scope: Record<string, unknown> | null | undefined): {
-  entries: LogicScopeEntryView[];
-  values: Map<string, unknown>;
-} {
+function railOf(scope: Tab["session"]["canvas"]["scope"] | undefined) {
   const entries: LogicScopeEntryView[] = [];
-  const values = new Map<string, unknown>();
-  for (const [name, value] of Object.entries(scope ?? {})) {
+  const values = new Map<string, ScopeValue>();
+  /* SAFETY: the canvas scope's one writer (iframe-host.ts, on a `dataScope` message) stores that
+     message's `scope`, a JsonObject of deep-cloned values (serialize-scope.ts). */
+  const snapshot = (scope ?? {}) as JsonObject;
+  for (const [name, value] of Object.entries(snapshot)) {
     entries.push({ key: name, name, type: dataTypeLabel(value) });
     values.set(name, unwrapSignal(value));
   }
@@ -422,7 +444,7 @@ export function workspaceView(): LogicWorkspaceView {
     };
   }
 
-  const stateEntries = (tab.doc.document?.state ?? {}) as Record<string, JxStateDefinition>;
+  const stateEntries = tab.doc.document.state ?? {};
   /* Live-context evaluation in the canvas iframe with snapshot fallback (M6). The canvas is no
      longer unmounted while this surface is open — that is the entire point of the move — so the
      live path is the ORDINARY case now rather than the one that never happened. An event target's
@@ -595,7 +617,10 @@ const ACTIONS: LogicWorkspaceActions = {
 };
 
 /** Vendor a packaged formula's state entry into the document, as one undo step. */
-function insertDef(defName: string, def: unknown): void {
+function insertDef(defName: string, def: JxStateDefinition): void {
+  /* SAFETY: the only def the editor and the catalog insert is a packaged formula's vendored entry
+     (formula-catalog.ts `ensure`): `$description`, `$expression` and `parameters`, all JSON from
+     @jxsuite/formulas. */
   transactDoc(activeTab.value, (t) => mutateAddDef(t, defName, def as Record<string, JsonValue>));
 }
 
@@ -750,7 +775,7 @@ export function formulaEditorCommands(): AnyCommand[] {
         if (!tab) {
           throw new RangeError(`command "formula.editDef" needs an open document`);
         }
-        const defs = tab.doc.document?.state ?? {};
+        const defs = tab.doc.document.state ?? {};
         if (!(defName in defs)) {
           const defined = Object.keys(defs);
           throw new RangeError(

package/src/panels/frontmatter-fields.ts

@@ -20,6 +20,7 @@
  * the two hosts. The Page panel was the last one, and the renderer went with it.
  */
 
+import { isBoolean, isString } from "@jxsuite/schema/guards";
 import { previewAssetSrc } from "../canvas/asset-refs";
 import { IMAGE_EXTENSIONS, extensionOf } from "../files/media-upload";
 import { referenceEntryState } from "../ui/form-controls";
@@ -29,12 +30,14 @@ import { referenceTarget } from "../ui/schema-form";
 import type { JsonValue } from "../types";
 import type { Tab } from "../tabs/tab";
 import type { ProjectConfig } from "@jxsuite/schema/types";
+import type { SurfaceOption } from "../ui/surface";
 
 export interface FmSchemaEntry {
   type?: string;
   enum?: string[];
   format?: string;
-  properties?: Record<string, unknown>;
+  /** A nested object field's own field schemas. */
+  properties?: Record<string, FmSchemaEntry>;
   /** `#/content/<type>` — a relationship to another collection (site-architecture.md §6.1). */
   $ref?: string;
 }
@@ -42,7 +45,8 @@ export interface FmSchemaEntry {
 export interface FmField {
   field: string;
   entry: FmSchemaEntry;
-  value: JsonValue;
+  /** What the document holds under the key; `undefined` for a schema field it does not set. */
+  value: JsonValue | undefined;
 }
 
 export interface FmFieldSet {
@@ -70,8 +74,15 @@ export function collectFmFields(
   projectConfig: ProjectConfig | null | undefined,
   reserved: Set<string>,
 ): FmFieldSet {
-  const fm = tab.doc.content?.frontmatter || {};
+  /* SAFETY: `FormatFrontmatter` holds `JxDocumentValue`, which is the JSON value space seen through
+     the typed interfaces a document's declared keys use (JxRef, JxStatement, CemEvent, ...). Every
+     frontmatter value is parsed from the file by a format class's split or JSON-cloned from one, so
+     each is plain JSON data, and viewing it as JsonValue reads the same data without those views. */
+  const fm = tab.doc.content.frontmatter as Record<string, JsonValue | undefined>;
   const collection = findContentTypeSchema(tab.documentPath, projectConfig);
+  /* SAFETY: a collection schema is JSON Schema, and the only keywords an FmSchemaEntry reads —
+     `type`, `format`, `$ref` (strings) and `enum` (a list of choices) — carry those shapes there;
+     `required` is already typed `string[]` on ContentTypeSchema. */
   const schema = collection?.schema as
     | { properties?: Record<string, FmSchemaEntry>; required?: string[] }
     | undefined;
@@ -84,16 +95,16 @@ export function collectFmFields(
       if (reserved.has(field)) {
         continue;
       }
-      fields.push({ entry: fieldSchema, field, value: fm[field] as JsonValue });
+      fields.push({ entry: fieldSchema, field, value: fm[field] });
     }
     for (const [field, value] of Object.entries(fm)) {
       if (schemaProps[field] || field.startsWith("$") || reserved.has(field)) {
         continue;
       }
       fields.push({
-        entry: { type: typeof value === "boolean" ? "boolean" : "string" },
+        entry: { type: isBoolean(value) ? "boolean" : "string" },
         field,
-        value: value as JsonValue,
+        value,
       });
     }
   } else {
@@ -102,9 +113,9 @@ export function collectFmFields(
         continue;
       }
       fields.push({
-        entry: { type: typeof value === "boolean" ? "boolean" : "string" },
+        entry: { type: isBoolean(value) ? "boolean" : "string" },
         field,
-        value: value as JsonValue,
+        value,
       });
     }
   }
@@ -112,12 +123,6 @@ export function collectFmFields(
   return { collection, fields, hasSchema: Boolean(schemaProps), requiredFields };
 }
 
-/** One choice in a row's picker — the shape `jx-select` reads. */
-export interface FmChoice {
-  value: string;
-  label: string;
-}
-
 /**
  * One frontmatter field as a surface draws it. Every field is present whatever the `kind`, because
  * a document's binding renders a value and its `$switch` chooses on one: a row that omitted
@@ -140,7 +145,7 @@ export interface FmRowView {
   /** A text row's placeholder. Empty draws none. */
   placeholder: string;
   /** A picker's rows, in the order they are offered. Empty on every other kind. */
-  options: FmChoice[];
+  options: SurfaceOption[];
   /** A sentence under the control — an empty collection, or a listing that failed. */
   note: string;
   /** Whether {@link FmRowView.note} has anything in it; `$switch` is a document's conditional. */
@@ -162,8 +167,8 @@ export interface FmRowProjection {
 }
 
 /** A frontmatter value as the text a field shows. An object is not a string and never pretends. */
-function text(value: unknown): string {
-  return typeof value === "string" ? value : "";
+function text(value: JsonValue | undefined): string {
+  return isString(value) ? value : "";
 }
 
 /** A blank row, so every kind carries every field a surface's bindings read. */
@@ -188,7 +193,7 @@ function blankRow(label: string): FmRowView {
  *
  * @param {string} field The frontmatter key.
  * @param {FmSchemaEntry} entry Its schema, or the type inferred from the value it already holds.
- * @param {unknown} value What the document says today.
+ * @param {JsonValue | undefined} value What the document says today.
  * @param {Set<string>} requiredFields The collection's required keys, for the label's marker.
  * @param {{ rerender: () => void }} opts How a surface is repainted when a referenced collection's
  *   entry ids land — the one asynchronous read a row can start.
@@ -197,7 +202,7 @@ function blankRow(label: string): FmRowView {
 export function projectFmField(
   field: string,
   entry: FmSchemaEntry,
-  value: unknown,
+  value: JsonValue | undefined,
   requiredFields: Set<string>,
   opts: { rerender: () => void },
 ): FmRowProjection {

package/src/panels/frontmatter-panel.ts

@@ -66,6 +66,7 @@
  * @docs studio/editing/frontmatter
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { projectState } from "../store";
 import { workspace } from "../workspace/workspace";
 import { tabOfPane } from "../canvas/canvas-surface";
@@ -90,18 +91,18 @@ import { activeRegistry } from "../commands/active-registry";
 import { invalidateLayoutCache } from "../site-context";
 import { mountDocHeaderSurface } from "../surfaces/doc-header";
 
-import type { JxHeadEntry, JxMutableNode } from "@jxsuite/schema/types";
+import type { JsonValue, JxHeadEntry, JxMutableNode } from "@jxsuite/schema/types";
 import type { Tab } from "../tabs/tab";
 import type { FmSchemaEntry } from "./frontmatter-fields";
 import type * as MediaPickerModule from "../ui/media-picker";
 import type {
   DocHeaderActions,
-  DocHeaderChoice,
   DocHeaderRawEntry,
   DocHeaderRow,
   DocHeaderSurface,
   DocHeaderView,
 } from "../surfaces/doc-header";
+import type { SurfaceOption } from "../ui/surface";
 
 /** What one row of the card writes. The document knows the control; this knows the document. */
 interface RowCommit {
@@ -120,7 +121,13 @@ interface RowCommit {
  * drawing a header the second `ref` to fire silently took the card away from the first, leaving one
  * pane's Document Header frozen on the frontmatter of the moment it lost the handle.
  */
-interface HeaderCard {
+interface HeaderCard extends HeaderCardState {
+  /** Handed to the surface once, when it is mounted; every one of them reads `commits`. */
+  actions: DocHeaderActions;
+}
+
+/** Everything a card holds except its actions, which are built over this and read it lazily. */
+interface HeaderCardState {
   /** The pane this card is drawn for. Held rather than looked up: an action has to answer it. */
   paneId: string;
   el: HTMLElement;
@@ -128,8 +135,6 @@ interface HeaderCard {
   surface: DocHeaderSurface | null;
   /** This pane's rows, by key. Rebuilt with each projection. */
   commits: Map<string, RowCommit>;
-  /** Handed to the surface once, when it is mounted; every one of them reads `commits`. */
-  actions: DocHeaderActions;
   /** Text edits waiting out {@link LIVE_PREVIEW}, one per row key. */
   pending: Map<string, { commit: () => void; timer: ReturnType<typeof setTimeout> }>;
 }
@@ -194,15 +199,20 @@ export function attachDocumentHeaderHost(paneId: string, el: HTMLElement | null)
   if (!el) {
     return;
   }
-  const card: HeaderCard = {
-    actions: {} as DocHeaderActions,
+  const state: HeaderCardState = {
     commits: new Map(),
     el,
     paneId,
     pending: new Map(),
     surface: null,
   };
-  card.actions = makeActions(card);
+  /* The same object, not a copy: the actions read `state.commits`, which a projection reassigns.
+     `settle` runs only on a reader's toggle, long after `card` is bound. */
+  const card: HeaderCard = Object.assign(state, {
+    actions: makeActions(state, () => {
+      settle(card);
+    }),
+  });
   _hosts.set(paneId, card);
   paint(paneId, card);
 }
@@ -236,14 +246,12 @@ export function mount() {
         void tab.doc.mode;
         void tab.documentPath;
         void tab.doc.document;
-        void tab.doc.document?.title;
-        void tab.doc.document?.$head;
-        void tab.doc.document?.$layout;
-        const fm = tab.doc.content?.frontmatter;
-        if (fm) {
-          for (const key of Object.keys(fm)) {
-            void fm[key];
-          }
+        void tab.doc.document.title;
+        void tab.doc.document.$head;
+        void tab.doc.document.$layout;
+        const fm = tab.doc.content.frontmatter;
+        for (const key of Object.keys(fm)) {
+          void fm[key];
         }
       }
       render();
@@ -309,12 +317,13 @@ export function render() {
  * @returns {boolean}
  */
 export function hasDocumentHeader(tab: Tab): boolean {
-  const fm = tab.doc.content?.frontmatter ?? {};
+  const fm = tab.doc.content.frontmatter;
   const doc = tab.doc.document;
   if (Object.keys(fm).length > 0) {
     return true;
   }
-  if (typeof doc?.title === "string" || (doc?.$head?.length ?? 0) > 0) {
+  // `title` is typed a string, but a document read off disk may carry any JSON there.
+  if (isString(doc.title) || (doc.$head?.length ?? 0) > 0) {
     return true;
   }
   // A page always has one, even an empty one: Title and Route are the two facts it must state.
@@ -368,7 +377,7 @@ function paint(paneId: string, card: HeaderCard): void {
  */
 function viewFor(tab: Tab, paneId: string, card: HeaderCard): DocHeaderView {
   const isContent = tab.doc.mode === "content";
-  const fm = (tab.doc.content?.frontmatter ?? {}) as Record<string, unknown>;
+  const fm = tab.doc.content.frontmatter;
   // ONE view of the document's head material, whichever realm it lives in: frontmatter keys for a
   // Markdown page, root properties for a JSON one.
   const headDoc = isContent ? buildHeadDoc(tab.doc.document, fm) : tab.doc.document;
@@ -437,7 +446,7 @@ function titleRow(
   applyMutation: (fn: (doc: JxMutableNode) => void) => void,
   commits: Map<string, RowCommit>,
 ): DocHeaderRow {
-  const title = typeof headDoc.title === "string" ? headDoc.title : "";
+  const title = isString(headDoc.title) ? headDoc.title : "";
   commits.set("title", {
     clear: () =>
       applyMutation((d) => {
@@ -485,7 +494,7 @@ function layoutRow(
   const current = headDoc.$layout;
   const defaultPath = projectState?.projectConfig?.defaults?.layout;
   const defaultLabel = defaultPath ? layoutName(defaultPath) : "";
-  const options: DocHeaderChoice[] = [
+  const options: SurfaceOption[] = [
     { label: defaultLabel ? `Default (${defaultLabel})` : "Default", value: "__default__" },
     { label: "None", value: "__none__" },
     ...entries.map((l) => ({ label: l.name, value: l.path })),
@@ -544,7 +553,7 @@ function fieldRow(
   tab: Tab,
   field: string,
   entry: FmSchemaEntry,
-  value: unknown,
+  value: JsonValue | undefined,
   requiredFields: Set<string>,
   commits: Map<string, RowCommit>,
 ): DocHeaderRow {
@@ -564,15 +573,15 @@ function fieldRow(
  * they cannot see, and the Page panel remains the surface that adds and removes them.
  */
 function rawEntries(head: JxHeadEntry[]): DocHeaderRawEntry[] {
-  return head
-    .filter(
-      (e: JxHeadEntry) => !isManagedEntry(e) && !isGoogleFontEntry(e) && !isGoogleFontPreconnect(e),
-    )
-    .map((entry, index) => ({
-      key: `raw:${index}`,
-      label: entryLabel(entry),
-      value: entryValue(entry),
-    }));
+  const rows: DocHeaderRawEntry[] = [];
+  for (const entry of head) {
+    if (isManagedEntry(entry) || isGoogleFontEntry(entry) || isGoogleFontPreconnect(entry)) {
+      continue;
+    }
+    // The key counts the LISTED entries, as the index of the filtered list it replaces did.
+    rows.push({ key: `raw:${rows.length}`, label: entryLabel(entry), value: entryValue(entry) });
+  }
+  return rows;
 }
 
 // ─── The actions ─────────────────────────────────────────────────────────────
@@ -582,8 +591,9 @@ function rawEntries(head: JxHeadEntry[]): DocHeaderRawEntry[] {
  *
  * Made once per host and handed to the surface at mount, so every one of them reads the CURRENT
  * commit table rather than closing over the projection that was standing when the card was drawn.
+ * `settleCard` repaints the whole card, which needs these actions, so it is handed in.
  */
-function makeActions(card: HeaderCard): DocHeaderActions {
+function makeActions(card: HeaderCardState, settleCard: () => void): DocHeaderActions {
   const flush = (key: string): void => {
     const waiting = card.pending.get(key);
     if (waiting) {
@@ -645,7 +655,7 @@ function makeActions(card: HeaderCard): DocHeaderActions {
       } catch {
         // Storage full or unavailable — this card still folds, the next one just opens.
       }
-      settle(card);
+      settleCard();
     },
     setNumber: (key, value) => now(key, value),
     setRawOpen: (open) => {
@@ -660,7 +670,7 @@ function makeActions(card: HeaderCard): DocHeaderActions {
       } else {
         _rawOpen.delete(tab.id);
       }
-      settle(card);
+      settleCard();
     },
     upload: (key) => {
       flush(key);

package/src/panels/git-diff-open.ts

@@ -132,8 +132,8 @@ export function openDiffTab(path: string): Tab {
  *
  * `files/files.ts` is imported dynamically because it imports `cleanupGitPanel` from
  * `panels/git-panel.ts`, which imports this module: a static edge back would close that cycle.
- * `openFileInTab` answers `void` when it reveals a tab that was already open, so the tab is
- * resolved from the workspace either way.
+ * `openFileInTab` answers `void` whether it opens a new tab or reveals one that was already open,
+ * so the tab is resolved from the workspace by its path.
  *
  * Answers null when the file could not be opened at all, which the caller states rather than
  * silently leaving the stage on someone else's document.
@@ -143,6 +143,6 @@ export async function openComparisonTab(path: string): Promise<Tab | null> {
     return openDiffTab(path);
   }
   const files = await import("../files/files");
-  const opened = await files.openFileInTab(path, {});
-  return opened ?? [...workspace.tabs.values()].find((tab) => tab.documentPath === path) ?? null;
+  await files.openFileInTab(path, {});
+  return [...workspace.tabs.values()].find((tab) => tab.documentPath === path) ?? null;
 }