@jxsuite/studio 4.1.0 → 5.0.0

package/src/services/document-assistant.ts

@@ -21,6 +21,11 @@ import { componentRegistry } from "../files/components";
 import { activeRegistry } from "../commands/active-registry";
 import { registerAiTools } from "./ai-tools";
 import { cancelAsk, registerAskTool, resetAsk } from "./ai-ask";
+import {
+  commandToolBlurbs,
+  composeToolRegistries,
+  createCommandToolRegistry,
+} from "./ai-command-tools";
 import { registerProjectTools } from "./ai-project-tools";
 import { registerImportTools, resetImportGuard } from "./ai-import-tools";
 import { createGatedToolRegistry } from "./gated-registry";
@@ -29,12 +34,14 @@ import { adoptProject } from "./project-adoption";
 import { abortImportRun, resetImportRuns } from "./import-run";
 import { runAgentLoop } from "./tool-executor";
 import { AI_TOOL_TIERS, buildSystemPrompt, toolActive } from "./ai-system-prompt";
+import type { ExtensionCatalogSummary } from "./ai-system-prompt";
 import { getBaseUrl, getOpenAiKey } from "./ai-settings";
 import { preferredModel } from "./ai-models";
 import { pruneOrphanToolMessages, trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
+import { validateDoc } from "./jx-validate";
 import { openFileInTab, reloadFileInTab } from "../files/files";
-import { refreshExtensionUi } from "../format/format-host";
+import { getExtensionCatalog, refreshExtensionUi } from "../format/format-host";
 import * as sessionStore from "./ai-session-store";
 
 /**
@@ -189,7 +196,26 @@ export function createDocumentAssistant() {
       },
     ]),
   );
-  const toolRegistry = createGatedToolRegistry(innerRegistry, availability);
+  /*
+   * The other kind of tool: every command record that declares `aiTool`, as a VIEW over the active
+   * registry (`services/ai-command-tools.ts`). Nothing is registered — the record IS the tool, its
+   * `when` / `enablement` is the gate, `registry.run` is the executor — so `enable_extension`,
+   * `delete_node` and the rest need no row in the tier table and no registrar here. The deps are
+   * the write reporter's, the same three the hand tree tools take, because a bridged document write
+   * is held to the same verdict (new schema errors, the render check, the token hints).
+   */
+  const commandTools = createCommandToolRegistry({
+    getProjectStyle,
+    getTab: () => activeTab.value,
+    renderCheck: renderCheck as (
+      doc: unknown,
+    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    validate: validateDoc,
+  });
+  const toolRegistry = composeToolRegistries(
+    createGatedToolRegistry(innerRegistry, availability),
+    commandTools,
+  );
 
   let controller: AbortController | null = null;
 
@@ -201,6 +227,19 @@ export function createDocumentAssistant() {
           .filter((e) => e.type === "file")
           .map((e) => e.path)
       : undefined;
+    /* The synchronous snapshot beside the async load, exactly as `getExtensions()` sits beside
+       `loadExtensions()`: `buildSystemPrompt` is a pure function and this is called per turn, so
+       the catalogue is read from the ONE cache the Extensions section also reads. Two caches would
+       be two answers to "what can this project turn on". */
+    const catalog: ExtensionCatalogSummary[] = [];
+    for (const entry of getExtensionCatalog()) {
+      catalog.push({
+        name: entry.name,
+        sections: entry.sections.map((section) => section.key),
+        ...(entry.title === undefined ? {} : { title: entry.title }),
+        ...(entry.description === undefined ? {} : { description: entry.description }),
+      });
+    }
     return buildSystemPrompt({
       document: tab ? toRaw(tab.doc.document) : undefined,
       projectConfig: (workspace.projectConfig as ProjectConfig | null) || undefined,
@@ -208,7 +247,16 @@ export function createDocumentAssistant() {
       projectRoot: workspace.projectRoot || undefined,
       hasProject: Boolean(workspace.projectRoot),
       canImport: Boolean(getPlatform().importSite),
+      /* The same reading the gate makes, so the prompt advertises exactly what `execute` will
+         honour. This was never passed: with Project Settings focused the prompt listed the seven
+         hand tree writers while the `document-tree` gate refused every one of them, and the model
+         spent a round learning it. */
+      treeEditable: treeEditable(),
+      /* Read per turn from the live registry — a projected tool the gate will honour this round is
+         listed this round, and one it will not is not. */
+      commandTools: commandToolBlurbs(activeRegistry()),
       ...(inventory && inventory.length > 0 ? { fileInventory: inventory } : {}),
+      ...(catalog.length > 0 ? { extensionCatalog: catalog } : {}),
     });
   }
 

package/src/services/idle.ts

@@ -12,22 +12,29 @@
  * in-flight (gitStatus)"]` — so the slow subsystem identifies itself.
  *
  * Nothing here polls a subsystem it does not own. Each source is a function the owning module
- * already had to write for its own reasons:
+ * already had to write for its own reasons.
+ *
+ * There WAS a seventh, `panel-scheduler.pendingSchedulers()`, and it went with the scheduler. It
+ * reported a panel with an animation frame queued or a render withheld while a field had focus —
+ * both facts about a lit dock repainting itself. The Navigator and the Inspector are documents now
+ * (`surfaces/navigator-dock.json`, `surfaces/inspector-dock.json`): a projection is written
+ * synchronously and a binding whose value did not move writes nothing, so there is no queued frame
+ * to be outstanding and no withheld render to wait for. The panel bodies that ARE still lit are
+ * painted synchronously from the same call.
  *
  * 1. `store.rendersInFlight()` — renderers mid-paint.
- * 2. `panel-scheduler.pendingSchedulers()` — panels with a frame queued or a render withheld.
- * 3. `iframe-host.canvasIdleBlockers()` — per host: unacked generations and patches, plus the frame's
+ * 2. `iframe-host.canvasIdleBlockers()` — per host: unacked generations and patches, plus the frame's
  *    own cross-realm report of fonts, running animations and pending image retries.
- * 4. `platform.platformInFlight()` — unsettled PAL calls, counted at the one seam every adapter and
+ * 3. `platform.platformInFlight()` — unsettled PAL calls, counted at the one seam every adapter and
  *    all thirty-odd `git*`/fs/fetch methods pass through.
- * 5. `layers.overlayIdleBlockers()` — overlays still in transition. Only the SETTLING window counts: a
+ * 4. `layers.overlayIdleBlockers()` — overlays still in transition. Only the SETTLING window counts: a
  *    resting toast is not a blocker, which is what lets `toastsAreHeld()` hold one open for a
  *    capture without `probeIdle()` waiting forever alongside it (plan §13.7's named exception).
- * 6. `activity-panel.activityIdleBlockers()` — operations still RUNNING in the Activity tab. Not a
+ * 5. `activity-panel.activityIdleBlockers()` — operations still RUNNING in the Activity tab. Not a
  *    duplicate of `platform`: an activity spans a whole operation (an install, a deploy, a clone)
  *    across many PAL calls, so the gaps between them look quiet at the seam while the operation is
  *    plainly mid-flight. A finished entry never blocks — the list stays on screen forever.
- * 7. `grid-idle.gridIdleBlockers()` — tables still building, or built but not yet showing the
+ * 6. `grid-idle.gridIdleBlockers()` — tables still building, or built but not yet showing the
  *    selection range `selectableRange: 1` gives them. Nothing else covered Tabulator: a grid
  *    command resolves when the panel mounts, which is several frames before the table is drawn.
  *
@@ -37,7 +44,6 @@
 
 import { rendersInFlight } from "../store";
 import { activityIdleBlockers } from "../panels/activity-panel";
-import { pendingSchedulers } from "../panels/panel-scheduler";
 import { canvasIdleBlockers } from "../canvas/iframe-host";
 import { platformInFlight } from "../platform";
 import { overlayIdleBlockers } from "../ui/layers";
@@ -45,7 +51,7 @@ import { gridIdleBlockers } from "../grid/grid-idle";
 
 /** One subsystem that can be outstanding, and its account of why. */
 export interface IdleSource {
-  /** Stable name — `render`, `panels`, `canvas`, `platform`, `overlay`. */
+  /** Stable name — `render`, `canvas`, `platform`, `overlay`. */
   readonly name: string;
   /** Empty when quiet; otherwise one human-readable line per outstanding item. */
   blockers: () => readonly string[];
@@ -73,7 +79,7 @@ export class NotIdleError extends Error {
 }
 
 /**
- * The seven live sources.
+ * The six live sources.
  *
  * Built per call rather than held in a module constant so a test can substitute one without
  * unpicking the others, and so a second window's hosts are never read through the first window's
@@ -88,10 +94,6 @@ export function defaultIdleSources(): IdleSource[] {
       },
       name: "render",
     },
-    {
-      blockers: () => pendingSchedulers().map((panel) => `panels: ${panel}`),
-      name: "panels",
-    },
     { blockers: canvasIdleBlockers, name: "canvas" },
     {
       blockers: () => {

package/src/services/live-surfaces.ts

@@ -0,0 +1,237 @@
+/**
+ * Live authoring of Studio's own chrome.
+ *
+ * Studio's surfaces are Jx documents (`src/surfaces/*.json`) and its controls are the kit's
+ * (`packages/ui/components/*.json`), so both are things Studio can open and edit. This is what
+ * closes the loop: a saved surface document re-mounts every root drawn from it, and a saved kit
+ * component redefines the element and re-mounts every root that used it, so the edit shows in the
+ * shell the reader is standing in (studio-ui-guidelines.md §9.3, embedding.md §7).
+ *
+ * **The lane is keyed on the saved PATH, and that is the whole of how it stays inert.** A save is
+ * something to act on only when the file, joined to the open project's root, is one of the two
+ * places the chrome comes from. Any other project — a site, a starter, the examples — saves files
+ * this never looks at, and the shipped app never reads its chrome from disk: the document that
+ * re-mounts is the one the tab just wrote, handed over by the save path, never read back.
+ *
+ * Two things are deliberately NOT here. The lane does not watch the filesystem: an edit made
+ * outside Studio reaches the shell on the next reload, as it always did, because a watcher is a
+ * second writer racing the tab. And it does not diff: a saved document is re-registered whole and
+ * every root re-mounted, because a surface's host scope is reused (`SurfaceMount.remount`) and only
+ * the surface-local state resets, which is the contract §9.3 gives the registry.
+ *
+ * A kit redefinition reaches the canvas frames too, with the FILE's URL under the project as its
+ * base: the frame draws a project's elements from the project's own files, so a sibling `$ref` in
+ * the definition must resolve to the project's copy, not to the bundle's. The frame answers the
+ * definition's `jx-ui:` sidecars from the loaders it registered at boot (`iframe-entry.ts`), one
+ * chunk per behaviour on first use.
+ *
+ * @docs extending/ui-kit
+ */
+import { redefineElement } from "@jxsuite/runtime";
+import { KIT_BASE } from "@jxsuite/ui";
+import type { JxDocument } from "@jxsuite/schema/types";
+import { mountsOf, mountsUsing } from "./surface-registry";
+import { registerSurface, surfaceDocument } from "../ui/surface";
+import { documentBase } from "../canvas/canvas-origin";
+
+/** What a saved file IS to the running shell. */
+export type LiveTarget =
+  | { readonly kind: "surface"; readonly name: string }
+  | { readonly kind: "element"; readonly tag: string };
+
+/** Where a surface document lives, from any root that contains it. */
+const SURFACE_PATH = /\/packages\/studio\/src\/surfaces\/([\w-]+)\.json$/;
+/** Where a kit component lives, from any root that contains it. */
+const ELEMENT_PATH = /\/packages\/ui\/components\/(jx-[\w-]+)\.json$/;
+
+/**
+ * Join a project root and a path the way the platform reports them, and normalise the separators so
+ * a Windows root and a POSIX-relative path meet in one spelling.
+ */
+function joined(projectRoot: string, path: string): string {
+  const root = projectRoot.replaceAll("\\", "/").replace(/\/+$/, "");
+  const rel = path.replaceAll("\\", "/").replace(/^\.?\//, "");
+  return `${root}/${rel}`;
+}
+
+/**
+ * Which surface or element a saved path is, or null for every other file.
+ *
+ * Matched by suffix against the root JOINED to the path rather than by which project is open, so
+ * the same answer comes from the kit opened as its own project (`components/jx-tree.json` under
+ * `packages/ui`), from Studio opened as one (`src/surfaces/menu.json` under `packages/studio`), or
+ * from any root above them. A path that is neither — including every file of every other project —
+ * is null, and null is the lane doing nothing.
+ *
+ * @param projectRoot The open project's root, as the platform reports it.
+ * @param path The saved path, relative to that root.
+ */
+export function liveSurfaceTarget(
+  projectRoot: string | null | undefined,
+  path: string | null | undefined,
+): LiveTarget | null {
+  if (!projectRoot || !path) {
+    return null;
+  }
+  const full = joined(projectRoot, path);
+  const surface = SURFACE_PATH.exec(full);
+  if (surface) {
+    return { kind: "surface", name: surface[1]! };
+  }
+  const element = ELEMENT_PATH.exec(full);
+  if (element) {
+    return { kind: "element", tag: element[1]! };
+  }
+  return null;
+}
+
+/** What one save did. */
+export interface LiveSurfaceResult {
+  readonly target: LiveTarget;
+  /** How many roots were re-mounted. Zero is a document nothing on screen was drawn from. */
+  readonly remounted: number;
+  /** How many canvas frames were told of an element's redefinition. Absent for a surface. */
+  readonly canvases?: number;
+  /** Why nothing was applied, when nothing was. */
+  readonly refused?: string;
+}
+
+/**
+ * The URL a frame resolves a saved kit component against: the file's own URL under the project,
+ * which is where the frame fetched the definition it holds and where its sibling `$ref`s live.
+ *
+ * @param projectRoot The open project's root.
+ * @param path The saved path, relative to it.
+ */
+export function canvasBaseFor(projectRoot: string, path: string): string {
+  return new URL(path.replaceAll("\\", "/").replace(/^\.?\//, ""), documentBase(projectRoot)).href;
+}
+
+/**
+ * Apply a saved document to the running shell.
+ *
+ * A surface is re-registered under its name — the same call the bundle makes at boot, so the
+ * runtime's own resolution paths see the new document too — and every root of that name is
+ * re-mounted. An element is redefined through the runtime (embedding.md §7) and every root whose
+ * render instantiated it is re-mounted, which is what turns a redefinition into something visible:
+ * an instance already connected keeps the definition it rendered until it is re-mounted.
+ *
+ * A surface name nothing has registered is refused rather than registered: a new file under
+ * `src/surfaces/` has no adapter to mount it, so registering it would promise a mount nothing will
+ * make. An element whose document names a different tag than its file is refused too — the file is
+ * what the kit's registry keys on, and a document that disagrees with its own name is a mistake to
+ * report, not one to define under either spelling.
+ *
+ * @param target What the saved file is.
+ * @param doc The document the tab just wrote.
+ */
+export async function applyLiveSave(
+  target: LiveTarget,
+  doc: JxDocument,
+): Promise<LiveSurfaceResult> {
+  if (target.kind === "surface") {
+    if (!surfaceDocument(target.name)) {
+      return { refused: `no surface is registered as "${target.name}"`, remounted: 0, target };
+    }
+    registerSurface(target.name, doc);
+    const roots = mountsOf(target.name);
+    await Promise.all(roots.map((m) => m.remount()));
+    return { remounted: roots.length, target };
+  }
+  if (doc.tagName !== target.tag) {
+    return {
+      refused: `the document names <${String(doc.tagName)}>, but the file is ${target.tag}.json`,
+      remounted: 0,
+      target,
+    };
+  }
+  await redefineElement(doc, KIT_BASE);
+  const roots = mountsUsing(target.tag);
+  await Promise.all(roots.map((m) => m.remount()));
+  return { remounted: roots.length, target };
+}
+
+/** The two channels a save's outcome is said on. A refusal is a problem; a re-mount is a toast. */
+export interface LiveSurfaceNotifier {
+  info: (message: string, options: { key: string; source: string }) => void;
+  warn: (message: string, options: { key: string; source: string; tier: "problem" }) => void;
+}
+
+/**
+ * What the lane needs from the shell, as the records themselves rather than closures over them, so
+ * the bootstrap hands over objects it already holds and writes no function of its own.
+ */
+export interface LiveSurfaceDeps {
+  /** The workspace record; `projectRoot` is read at save time, never captured. */
+  workspace: { readonly projectRoot: string | null };
+  notify: LiveSurfaceNotifier;
+  /**
+   * Redefine an element in every live canvas frame and render them; answers how many were told.
+   * `canvas-render.ts`'s `redefineElementOnCanvases`, injected so this module imports no canvas.
+   */
+  redefineOnCanvases: (doc: JxDocument, base: string) => number;
+}
+
+/** The sentence a result is said in. Exported so the wording is tested, not only the branch. */
+export function liveSaveNotice(result: LiveSurfaceResult): {
+  key: string;
+  level: "info" | "warn";
+  message: string;
+} {
+  const what =
+    result.target.kind === "surface" ? `surface ${result.target.name}` : result.target.tag;
+  const key = `live-chrome:${what}`;
+  if (result.refused) {
+    return { key, level: "warn", message: `Not applied to the running shell: ${result.refused}.` };
+  }
+  const canvases =
+    result.canvases === undefined || result.canvases === 0
+      ? ""
+      : result.canvases === 1
+        ? " and on the canvas"
+        : ` and on ${result.canvases} canvases`;
+  if (result.remounted === 0) {
+    return {
+      key,
+      level: "info",
+      message: `${what} saved; nothing in the shell is drawn from it${canvases ? `, redefined${canvases}` : ""}.`,
+    };
+  }
+  const places = result.remounted === 1 ? "1 place" : `${result.remounted} places`;
+  return {
+    key,
+    level: "info",
+    message: `${what} saved and re-mounted in ${places}${canvases}.`,
+  };
+}
+
+/**
+ * The save listener: decide whether the saved file is chrome, and if it is, apply it and say so.
+ *
+ * Returns the result, or null when the save was not chrome, so a caller — and a test — can tell
+ * "nothing to do" from "did nothing".
+ *
+ * @param deps The shell's workspace record and notifier.
+ */
+export function createLiveSurfaceSaver(
+  deps: LiveSurfaceDeps,
+): (path: string | null, doc: JxDocument | null) => Promise<LiveSurfaceResult | null> {
+  return async (path, doc) => {
+    const root = deps.workspace.projectRoot;
+    const target = liveSurfaceTarget(root, path);
+    if (!target || !doc || !root || !path) {
+      return null;
+    }
+    let result = await applyLiveSave(target, doc);
+    if (target.kind === "element" && !result.refused) {
+      result = { ...result, canvases: deps.redefineOnCanvases(doc, canvasBaseFor(root, path)) };
+    }
+    const notice = liveSaveNotice(result);
+    if (notice.level === "warn") {
+      deps.notify.warn(notice.message, { key: notice.key, source: "Studio", tier: "problem" });
+    } else {
+      deps.notify.info(notice.message, { key: notice.key, source: "Studio" });
+    }
+    return result;
+  };
+}

package/src/services/model-uri.ts

@@ -29,3 +29,78 @@ export const ENTRY_SCHEMA_FILES = new Set(["project.schema.json", "document.sche
 export function modelUriFor(path: string): string {
   return ENTRY_SCHEMA_FILES.has(path) ? `file:///.jx/generated/${path}` : `file:///${path}`;
 }
+
+/**
+ * The two model URIs a comparison's Monaco diff editor mounts at.
+ *
+ * **A reserved namespace, because the collision is otherwise unrepresentable-by-luck rather than
+ * unrepresentable.** Two models on one URI throws (`Cannot create model because a model with the
+ * same URI already exists`), and `workspace/pane-derive.ts` refuses a Code lens on a file whose
+ * source editor is already open for exactly that reason. A diff editor is a THIRD claimant on the
+ * same path, and neither existing guard can see it: one asks about panes, the other about presets.
+ * Disjoint URIs make the collision impossible instead of refused.
+ *
+ * **Per pane**, because the primary can hold a comparison in Code while a Diff lens beside it holds
+ * the same file's — two diff editors over one file, four models, all four distinct.
+ *
+ * The cost, stated: a relative `$schema` resolves against the model URI, so the HEAD side gets no
+ * JSON validation. That is correct rather than merely tolerable — a comparison is read-only, and
+ * red squiggles on a git object nobody can edit would be noise. The Code lens on the real URI keeps
+ * its markers.
+ *
+ * @param {string} paneId
+ * @param {string} path - Project-relative file path
+ * @returns {{ head: string; work: string }}
+ */
+export function diffModelUrisFor(paneId: string, path: string): { head: string; work: string } {
+  return {
+    head: `file:///.jx/diff/${paneId}/head/${path}`,
+    work: `file:///.jx/diff/${paneId}/work/${path}`,
+  };
+}
+
+/**
+ * Monaco's language id for a path, for a buffer with no tab and no format class behind it.
+ *
+ * `sourceLang` answers from a Tab's format class, which a comparison may not have: a diff can be
+ * over a `.ts`, a `.css` or a `.gitignore`, none of which opens as a document at all. Unknown
+ * extensions resolve to `plaintext` rather than being forced into a registered language —
+ * `monaco-setup` contributes only JSON, TypeScript and JavaScript, and the red/green line
+ * decorations come from the diff algorithm rather than from a tokenizer, so plaintext loses
+ * highlighting and nothing else.
+ */
+export function monacoLangForPath(path: string): string {
+  const ext = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+  switch (ext) {
+    case "cjs":
+    case "js":
+    case "mjs": {
+      return "javascript";
+    }
+    case "css": {
+      return "css";
+    }
+    case "htm":
+    case "html": {
+      return "html";
+    }
+    case "json": {
+      return "json";
+    }
+    case "md": {
+      return "markdown";
+    }
+    case "cts":
+    case "mts":
+    case "ts": {
+      return "typescript";
+    }
+    case "yaml":
+    case "yml": {
+      return "yaml";
+    }
+    default: {
+      return "plaintext";
+    }
+  }
+}

package/src/services/notify.ts

@@ -14,12 +14,13 @@
  * | `toast`   | the fourth overlay layer   | timed, dismissible | reversible, or needs no action |
  * | `problem` | the Bottom dock's Problems | until it is fixed  | it must be fixed               |
  *
- * §7.1 names a third tier — **inline**, the `error` slot on `ui/field-row.ts`'s `renderFieldRow`.
- * It is deliberately NOT a member of {@link NotificationTier}: an inline error is a value a control
- * renders next to the field the user is editing, not a record the app posts to a host, and it has
- * no store to live in. Declaring a tier here whose only possible outcome is being dropped on the
- * floor would be exactly the silence this module exists to end, so the union has two members and
- * the third tier arrives as `renderFieldRow`'s own parameter (P4.4).
+ * §7.1 names a third tier — **inline**, the refusal a field draws at the control (`jx-field`'s own
+ * `[part="error"]`, projected by whichever inspector document owns the row). It is deliberately NOT
+ * a member of {@link NotificationTier}: an inline error is a value a control renders next to the
+ * field the user is editing, not a record the app posts to a host, and it has no store to live in.
+ * Declaring a tier here whose only possible outcome is being dropped on the floor would be exactly
+ * the silence this module exists to end, so the union has two members and the third tier arrives as
+ * a field's own projected value (P4.4).
  *
  * **Recovery is a command id, not a per-call-site closure.** `notify.error("Save failed", { action:
  * "file.save" })` gives the toast and the Problems row a Retry button whose label, availability,
@@ -254,6 +255,62 @@ export function clearProblems(match?: (record: Notification) => boolean): number
   return removed;
 }
 
+/**
+ * One outstanding problem, as a REPORT hands it to a caller that cannot see the store: the
+ * assistant, whose `check_accessibility` / `check_popovers` / `validate_redirects` tools return the
+ * findings the person sees in the dock as `ToolResult.data`.
+ *
+ * The record's identity and clock are left out on purpose (`id` is a lit key, `at` is for "2m
+ * ago"); what remains is what a reader acts on — the sentence, the long form, the file, how bad it
+ * is, and the repair command a Fix button would run.
+ */
+export interface ProblemFinding {
+  message: string;
+  severity: Severity;
+  detail?: string;
+  path?: string;
+  key?: string;
+  action?: string;
+  actionArgs?: Record<string, unknown>;
+}
+
+/**
+ * The outstanding problems one reporter filed, in the order they were filed — the same read the
+ * Problems tab makes when it groups by `source`, projected to {@link ProblemFinding}.
+ *
+ * @param {string} source - The `source` the reporter files under.
+ * @returns {ProblemFinding[]}
+ */
+export function problemFindings(source: string): ProblemFinding[] {
+  const findings: ProblemFinding[] = [];
+  for (const record of problems) {
+    if (record.source !== source) {
+      continue;
+    }
+    const finding: ProblemFinding = { message: record.message, severity: record.severity };
+    /* Copied key by key rather than spread from the record: `exactOptionalPropertyTypes` refuses
+       an explicit `undefined`, and the model reads the JSON, where an absent key and an undefined
+       one serialise the same but a `undefined`-valued key is a lie about what the row holds. */
+    if (record.detail !== undefined) {
+      finding.detail = record.detail;
+    }
+    if (record.path !== undefined) {
+      finding.path = record.path;
+    }
+    if (record.key !== undefined) {
+      finding.key = record.key;
+    }
+    if (record.action !== undefined) {
+      finding.action = record.action;
+    }
+    if (record.actionArgs !== undefined) {
+      finding.actionArgs = record.actionArgs;
+    }
+    findings.push(finding);
+  }
+  return findings;
+}
+
 /** How many problems are outstanding, optionally of one severity — the badge and the status bar. */
 export function problemCount(severity?: Severity): number {
   return severity === undefined