@jxsuite/studio 6.1.1 → 8.0.0

package/src/services/jx-validate.ts

@@ -19,21 +19,21 @@
 
 import coreDocumentSchema from "@jxsuite/schema/schema.json";
 import coreProjectSchema from "@jxsuite/schema/project-schema.json";
-
-type ValidateFn = ((doc: unknown) => boolean) & {
-  errors?: { instancePath?: string; message?: string; params?: Record<string, unknown> }[] | null;
-};
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue, ProjectConfig } from "@jxsuite/schema/types";
+import type { ValidateFunction } from "ajv/dist/2020.js";
+import type { CandidateDocument } from "./ai-write-report";
 
 /** Which of the two entry documents a validator covers. */
 type SchemaKind = "document" | "project";
 
-const CORE: Record<SchemaKind, object> = {
-  document: coreDocumentSchema as object,
-  project: coreProjectSchema as object,
+const CORE: Record<SchemaKind, JsonObject> = {
+  document: coreDocumentSchema,
+  project: coreProjectSchema,
 };
 
-const active: Record<SchemaKind, object> = { ...CORE };
-const compiling: Record<SchemaKind, Promise<ValidateFn | null> | null> = {
+const active: Record<SchemaKind, JsonObject> = { ...CORE };
+const compiling: Record<SchemaKind, Promise<ValidateFunction | null> | null> = {
   document: null,
   project: null,
 };
@@ -49,9 +49,9 @@ let reportedFailure = false;
  * unavailable or the schema will not compile.
  *
  * @param {SchemaKind} kind - Which entry document to compile
- * @returns {Promise<ValidateFn | null>} The compiled validator, or null when unavailable
+ * @returns {Promise<ValidateFunction | null>} The compiled validator, or null when unavailable
  */
-function getValidator(kind: SchemaKind): Promise<ValidateFn | null> {
+function getValidator(kind: SchemaKind): Promise<ValidateFunction | null> {
   compiling[kind] ??= (async () => {
     try {
       // The generated schemas are JSON Schema draft 2020-12, so they need Ajv's 2020 build —
@@ -62,7 +62,7 @@ function getValidator(kind: SchemaKind): Promise<ValidateFn | null> {
       const { default: addFormats } = await import("ajv-formats");
       const ajv = new Ajv2020({ allErrors: true, strict: false, allowUnionTypes: true });
       addFormats(ajv);
-      return ajv.compile(active[kind]) as ValidateFn;
+      return ajv.compile(active[kind]);
     } catch (error) {
       if (!reportedFailure) {
         reportedFailure = true;
@@ -78,14 +78,9 @@ function getValidator(kind: SchemaKind): Promise<ValidateFn | null> {
   return compiling[kind];
 }
 
-/** A payload half that is usable as a JSON Schema — a non-empty, non-array object. */
-function asSchema(value: unknown): object | undefined {
-  return typeof value === "object" &&
-    value !== null &&
-    !Array.isArray(value) &&
-    Object.keys(value).length > 0
-    ? (value as object)
-    : undefined;
+/** Whether a payload half is usable as a JSON Schema — a non-empty, non-array object. */
+function isSchemaObject(value: unknown): value is JsonObject {
+  return isJsonObject(value) && Object.keys(value).length > 0;
 }
 
 /**
@@ -107,8 +102,10 @@ export function applyProjectSchemas(
    * an error envelope under `document` would not fail loudly — it would install a validator that
    * calls every document valid, and every consumer would go on trusting it.
    */
-  const document = asSchema(schemas?.document) ?? CORE.document;
-  const project = asSchema(schemas?.project) ?? CORE.project;
+  const documentHalf = schemas?.document;
+  const projectHalf = schemas?.project;
+  const document = isSchemaObject(documentHalf) ? documentHalf : CORE.document;
+  const project = isSchemaObject(projectHalf) ? projectHalf : CORE.project;
   const applied = document !== CORE.document || project !== CORE.project;
   if (document === active.document && project === active.project) {
     return applied;
@@ -140,13 +137,13 @@ const ERROR_PROPERTY_KEYS = ["unevaluatedProperty", "additionalProperty", "missi
  * Format ajv errors the way the agent loop consumes them (see ai-tools.ts
  * `translateValidationError`).
  *
- * @param {ValidateFn} validate - The validator that just ran
+ * @param {ValidateFunction} validate - The validator that just ran
  * @returns {string[]} One formatted string per error
  */
-function formatErrors(validate: ValidateFn): string[] {
+function formatErrors(validate: ValidateFunction): string[] {
   return (validate.errors || []).map((e) => {
-    const key = ERROR_PROPERTY_KEYS.find((name) => typeof e.params?.[name] === "string");
-    const property = key ? ` (${String(e.params?.[key])})` : "";
+    const key = ERROR_PROPERTY_KEYS.find((name) => isString(e.params[name]));
+    const property = key ? ` (${String(e.params[key])})` : "";
     return `${e.instancePath || "(root)"}: ${e.message}${property}`;
   });
 }
@@ -154,10 +151,10 @@ function formatErrors(validate: ValidateFn): string[] {
 /**
  * Validate a Jx document against the active document schema.
  *
- * @param {unknown} doc - Parsed document
+ * @param {CandidateDocument} doc - Parsed document
  * @returns {Promise<string[]>} Formatted error strings; empty when valid or validation unavailable
  */
-export async function validateDoc(doc: unknown): Promise<string[]> {
+export async function validateDoc(doc: CandidateDocument): Promise<string[]> {
   const validate = await getValidator("document");
   if (!validate || validate(doc)) {
     return [];
@@ -176,7 +173,7 @@ export async function validateDoc(doc: unknown): Promise<string[]> {
  * @param doc - Parsed document
  * @returns The errors, `[]` when valid, or `null` when no validator could be compiled
  */
-export async function validateDocOrNull(doc: unknown): Promise<string[] | null> {
+export async function validateDocOrNull(doc: CandidateDocument): Promise<string[] | null> {
   const validate = await getValidator("document");
   if (!validate) {
     return null;
@@ -190,10 +187,10 @@ export async function validateDocOrNull(doc: unknown): Promise<string[] | null>
  * extension's fragment), so this is the only gate that catches a typo'd section key or a misshapen
  * extension section before the write lands.
  *
- * @param {unknown} config - Parsed project.json
+ * @param {ProjectConfig | JsonValue} config - Parsed project.json
  * @returns {Promise<string[]>} Formatted error strings; empty when valid or validation unavailable
  */
-export async function validateProjectConfig(config: unknown): Promise<string[]> {
+export async function validateProjectConfig(config: ProjectConfig | JsonValue): Promise<string[]> {
   const validate = await getValidator("project");
   if (!validate || validate(config)) {
     return [];

package/src/services/live-surfaces.ts

@@ -173,12 +173,15 @@ export interface LiveSurfaceDeps {
   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): {
+/** How a save's result is announced: the toast key it replaces, its level and its sentence. */
+export interface LiveSaveNotice {
   key: string;
   level: "info" | "warn";
   message: string;
-} {
+}
+
+/** The sentence a result is said in. Exported so the wording is tested, not only the branch. */
+export function liveSaveNotice(result: LiveSurfaceResult): LiveSaveNotice {
   const what =
     result.target.kind === "surface" ? `surface ${result.target.name}` : result.target.tag;
   const key = `live-chrome:${what}`;

package/src/services/model-uri.ts

@@ -30,6 +30,14 @@ export function modelUriFor(path: string): string {
   return ENTRY_SCHEMA_FILES.has(path) ? `file:///.jx/generated/${path}` : `file:///${path}`;
 }
 
+/** The two Monaco model URIs one pane's comparison of one file uses. */
+export interface DiffModelUris {
+  /** The committed (HEAD) side. */
+  head: string;
+  /** The working-tree side. */
+  work: string;
+}
+
 /**
  * The two model URIs a comparison's Monaco diff editor mounts at.
  *
@@ -50,9 +58,9 @@ export function modelUriFor(path: string): string {
  *
  * @param {string} paneId
  * @param {string} path - Project-relative file path
- * @returns {{ head: string; work: string }}
+ * @returns {DiffModelUris}
  */
-export function diffModelUrisFor(paneId: string, path: string): { head: string; work: string } {
+export function diffModelUrisFor(paneId: string, path: string): DiffModelUris {
   return {
     head: `file:///.jx/diff/${paneId}/head/${path}`,
     work: `file:///.jx/diff/${paneId}/work/${path}`,

package/src/services/module-preloads.ts

@@ -19,6 +19,11 @@
  * studio's own lazy surfaces runs.
  */
 
+/** A document head carrying the batcher's install flag. */
+interface BatchedHead extends HTMLHeadElement {
+  __modulePreloadsBatched?: boolean;
+}
+
 const QUEUED: HTMLLinkElement[] = [];
 let frame: number | null = null;
 let originalAppend: (<T extends Node>(node: T) => T) | null = null;
@@ -53,15 +58,14 @@ function appendChildPatched<T extends Node>(this: Node, node: T): T {
 }
 
 export function installModulePreloadBatcher(): void {
-  const { head } = document;
-  if (
-    !head ||
-    (head as HTMLElement & { __modulePreloadsBatched?: boolean }).__modulePreloadsBatched
-  ) {
+  /* SAFETY: a widening. The DOM standard declares `document.head` nullable (a document with no head
+     element has none) where lib.dom says it is always there; the install flag is an optional expando
+     this module alone writes. */
+  const head = document.head as BatchedHead | null;
+  if (!head || head.__modulePreloadsBatched) {
     return;
   }
-  const patched = head as HTMLElement & { __modulePreloadsBatched?: boolean };
   originalAppend = Node.prototype.appendChild.bind(head);
-  patched.__modulePreloadsBatched = true;
-  head.appendChild = appendChildPatched as unknown as typeof head.appendChild;
+  head.__modulePreloadsBatched = true;
+  head.appendChild = appendChildPatched;
 }

package/src/services/monaco-buffer.ts

@@ -105,8 +105,10 @@
  * @docs studio/logic/code
  */
 
+import { isFunction, isNonNullObject } from "@jxsuite/schema/guards";
 import { toRaw } from "../reactivity";
 import { notify } from "./notify";
+import type { NotifyOptions } from "./notify";
 import type { Tab } from "../tabs/tab";
 import { view } from "../view";
 import { allCanvasSurfaces } from "../canvas/surface-registry";
@@ -114,7 +116,7 @@ import { allCanvasSurfaces } from "../canvas/surface-registry";
 /** The slice of a Monaco editor this module needs. Both of Studio's Monacos satisfy it. */
 export interface MonacoBuffer {
   getValue: () => string;
-  getModel: () => unknown;
+  getModel: () => object | null;
   hasTextFocus: () => boolean;
   /** The debounced work armed over THIS buffer. Installed by {@link bufferWrites}. */
   _writes?: BufferWrites;
@@ -199,6 +201,19 @@ export interface BufferWrites {
  */
 export const BUFFER_COMMIT = "commit";
 
+/**
+ * Whether a run answered with a promise to wait for, rather than finishing synchronously.
+ *
+ * Asked of the thenable shape, not of `instanceof Promise`, because that is what `await` itself
+ * asks: whatever the armed work handed back is waited on exactly when `await` would wait on it.
+ *
+ * @param {void | Promise<void>} result What an armed run (or a flush of one) returned.
+ * @returns {boolean}
+ */
+function isPending(result: void | Promise<void>): result is Promise<void> {
+  return isNonNullObject(result) && isFunction(result.then);
+}
+
 /**
  * Install (and return) the debounce holder for `buffer`.
  *
@@ -223,10 +238,10 @@ export function bufferWrites(buffer: MonacoBuffer): BufferWrites {
    * report.
    */
   function track(key: string, result: void | Promise<void>): void | Promise<void> {
-    if (typeof (result as Promise<void> | undefined)?.then !== "function") {
+    if (!isPending(result)) {
       return result;
     }
-    const promise = (result as Promise<void>).finally(() => {
+    const promise = result.finally(() => {
       if (inFlight.get(key) === promise) {
         inFlight.delete(key);
       }
@@ -340,18 +355,19 @@ function reportDiscarded(
   const tab = buffer._editingTab ?? null;
   const where = tab?.documentPath ?? "Untitled";
   const { holds, reached, source } = SURFACE[surface];
-  notify.warn(`${holds} was discarded — it was never ${reached} "${where}".`, {
-    ...(failure ? { detail: describeCommitFailure(failure.error) } : {}),
-    key: `buffer-discarded:${surface}:${tab?.id ?? "none"}`,
-    source,
-    ...(tab?.documentPath ? { path: tab.documentPath } : {}),
-  });
+  const options: NotifyOptions = failure ? { detail: describeCommitFailure(failure.error) } : {};
+  options.key = `buffer-discarded:${surface}:${tab?.id ?? "none"}`;
+  options.source = source;
+  if (tab?.documentPath) {
+    options.path = tab.documentPath;
+  }
+  notify.warn(`${holds} was discarded — it was never ${reached} "${where}".`, options);
   return false;
 }
 
 /** What a failed commit is worth showing: the stack when there is one, the value otherwise. */
-function describeCommitFailure(error: unknown): string {
-  return error instanceof Error ? (error.stack ?? error.message) : String(error);
+function describeCommitFailure(cause: unknown): string {
+  return cause instanceof Error ? (cause.stack ?? cause.message) : String(cause);
 }
 
 /**
@@ -428,21 +444,21 @@ export function commitBufferWrites(
      ran, and a live 500ms timer was left over an editor whose container lit was about to replace.
      A timer reading `""` off a detached model is the exact defect this module was created to
      prevent, so the teardown below must happen whatever the commit does. */
-  let pending: Promise<void> | undefined;
+  let pending: void | Promise<void>;
   try {
     // Fire-and-forget on purpose: the disposer is synchronous, and the commit read `getValue()`
     // Before its own first `await`. What is left to await is the write INTO the document, which
     // Does not need this editor to still exist.
-    pending = writes.flush(BUFFER_COMMIT) as Promise<void> | undefined;
+    pending = writes.flush(BUFFER_COMMIT);
   } catch (error) {
     writes.cancel();
     return reportDiscarded(buffer, surface, { error });
   }
   writes.cancel();
-  if (typeof pending?.then === "function") {
+  if (isPending(pending)) {
     void pending.then(
       () => reportDiscarded(buffer, surface, null),
-      (error: unknown) => reportDiscarded(buffer, surface, { error }),
+      (error) => reportDiscarded(buffer, surface, { error }),
     );
     return true;
   }
@@ -512,20 +528,20 @@ export function bufferMovedOn(buffer: MonacoBuffer, expected?: string): boolean
  * @returns {MonacoBuffer[]}
  */
 function buffersForTab(tab: Tab): MonacoBuffer[] {
-  const raw = toRaw(tab as object);
+  const raw = toRaw(tab);
   /* Every stage's source buffer, plus the dock's one function editor.
      The source view is per-PANE now: two Code panes are two Monaco instances over two documents,
      and a close gate that asked only "the" source editor would have missed whichever one it was
      not holding — which is the same half-answer that let ⌘W close a tab over unprompted typing. */
   const mounted: (MonacoBuffer | null)[] = [
-    ...allCanvasSurfaces().map((surface) => surface.monacoEditor as MonacoBuffer | null),
+    ...allCanvasSurfaces().map((surface) => surface.monacoEditor),
     view.functionEditor,
   ];
   return mounted.filter(
     (buffer): buffer is MonacoBuffer =>
       buffer != null &&
       buffer._editingTab != null &&
-      toRaw(buffer._editingTab as object) === raw &&
+      toRaw(buffer._editingTab) === raw &&
       bufferIsLive(buffer),
   );
 }
@@ -598,14 +614,17 @@ export async function commitTabBuffers(tab: Tab): Promise<void> {
     try {
       await buffer._writes?.flush(BUFFER_COMMIT);
     } catch (error) {
+      const options: NotifyOptions = {
+        detail: describeCommitFailure(error),
+        key: `buffer-commit:${tab.id}`,
+        source: "Editor",
+      };
+      if (tab.documentPath) {
+        options.path = tab.documentPath;
+      }
       notify.error(
         `Could not save the editor's contents into "${tab.documentPath ?? "Untitled"}".`,
-        {
-          detail: error instanceof Error ? (error.stack ?? error.message) : String(error),
-          key: `buffer-commit:${tab.id}`,
-          source: "Editor",
-          ...(tab.documentPath ? { path: tab.documentPath } : {}),
-        },
+        options,
       );
     }
   }

package/src/services/monaco-lazy.ts

@@ -26,6 +26,7 @@
    on the object {@link loadMonaco} resolves to — typing this as the root would make five namespaces
    look available that are not. `./editor` is exactly the editor API surface that import returns. */
 import type * as monacoNs from "monaco-editor/editor";
+import type { ProjectSchemasResponse } from "../types";
 
 export type Monaco = typeof monacoNs;
 
@@ -41,7 +42,7 @@ let _loading: Promise<Monaco> | null = null;
  * which is precisely what the lazy path exists to avoid. So the schemas wait here instead, and the
  * loader applies whatever is pending once an editor actually needs one.
  */
-let _pendingSchemas: { project?: unknown; document?: unknown } | null = null;
+let _pendingSchemas: ProjectSchemasResponse | null = null;
 let _pendingSchemasDirty = false;
 
 /**
@@ -54,9 +55,7 @@ let _pendingSchemasDirty = false;
  * @returns Settles once the schemas are in force. Fire-and-forget is a valid use — say so with
  *   `void` at the call site rather than having this hide it.
  */
-export function setProjectSchemasForMonaco(
-  schemas: { project?: unknown; document?: unknown } | null,
-): Promise<void> {
+export function setProjectSchemasForMonaco(schemas: ProjectSchemasResponse | null): Promise<void> {
   _pendingSchemas = schemas;
   _pendingSchemasDirty = true;
   /* Resolves when the schemas have REACHED Monaco, not when they were queued. With Monaco already
@@ -100,7 +99,7 @@ export function loadMonaco(): Promise<Monaco> {
       import("monaco-editor/editor"),
       import("./monaco-setup.js"),
     ]);
-    _monaco = monaco as unknown as Monaco;
+    _monaco = monaco;
     // The project's schemas may have arrived long before now; register them before the first editor
     // Mounts so its very first validation pass uses the right rules.
     await applyPendingSchemas();
@@ -138,15 +137,15 @@ export function loadedMonaco(): Monaco | null {
  * attached to anything, and no URI briefly claimed by a model nobody holds.
  *
  * @param {Element | null | undefined} container Where the editor was going to be created.
- * @param {unknown} existing The surface's editor handle (`view.monacoEditor` /
- *   `view.functionEditor`). Non-null means another mount already won this race.
+ * @param {monacoNs.editor.IEditor | null} existing The surface's editor handle (`view.monacoEditor`
+ *   / `view.functionEditor`). Non-null means another mount already won this race.
  * @param {() => boolean} stillTargeted Whether the app still wants exactly THIS mount — the same
  *   tab, the same mode, the same editing target. Lazy: the two cheap clauses above answer first.
  * @returns {boolean}
  */
 export function mountStillWanted(
   container: Element | null | undefined,
-  existing: unknown,
+  existing: monacoNs.editor.IEditor | null,
   stillTargeted: () => boolean,
 ): boolean {
   if (!container?.isConnected || existing) {

package/src/services/monaco-setup.ts

@@ -80,18 +80,24 @@ import "monaco-editor/languages/definitions/javascript/register";
 import { flattenSchema } from "@jxsuite/schema/project-schemas";
 import jxSchema from "@jxsuite/schema/schema.json";
 import projectSchema from "@jxsuite/schema/project-schema.json";
+import type { JsonObject } from "@jxsuite/schema/types";
+import type { ProjectSchemasResponse } from "../types";
 import { bundleUrl } from "./bundle-base";
 
 /* Re-exported for the modules that already imported it from here. New callers should reach for
    `./model-uri` directly — it is Monaco-free, and importing this module loads the editor. */
 export { modelUriFor } from "./model-uri";
 
-const WORKER_FILES: Record<string, string> = {
-  editorWorkerService: "editor.worker.js",
-  javascript: "ts.worker.js",
-  json: "json.worker.js",
-  typescript: "ts.worker.js",
-};
+/** The worker every label without a language service of its own runs in. */
+const EDITOR_WORKER_FILE = "editor.worker.js";
+
+/** Monaco worker label → the pre-bundled worker file that serves it. */
+const WORKER_FILES = new Map([
+  ["editorWorkerService", EDITOR_WORKER_FILE],
+  ["javascript", "ts.worker.js"],
+  ["json", "json.worker.js"],
+  ["typescript", "ts.worker.js"],
+]);
 
 /**
  * Resolve a Monaco worker to the PRE-BUNDLED copy that ships NEXT TO THE ENTRY — `dist/workers/`
@@ -119,7 +125,7 @@ const WORKER_FILES: Record<string, string> = {
  * @returns {string} Absolute URL of the worker bundle
  */
 export function workerUrl(label: string): string {
-  const file = WORKER_FILES[label] || WORKER_FILES.editorWorkerService!;
+  const file = WORKER_FILES.get(label) ?? EDITOR_WORKER_FILE;
   return bundleUrl(`workers/${file}`);
 }
 
@@ -132,10 +138,13 @@ self.MonacoEnvironment = {
 /* Monaco caches glyph widths when an editor is created. JetBrains Mono is a
    vendored webfont (index.html @font-face) and may finish loading after the
    first editor mounts, so remeasure once all document fonts are ready to keep
-   cursor and selection alignment correct. */
-if (typeof document !== "undefined" && document.fonts?.ready) {
+   cursor and selection alignment correct. `lib.dom` declares `document.fonts` unconditionally, but
+   DOM shims (happy-dom under test) ship without it, so the font set is typed as possibly absent. */
+const documentFonts: FontFaceSet | undefined =
+  typeof document === "undefined" ? undefined : document.fonts;
+if (documentFonts?.ready) {
   // oxlint-disable-next-line unicorn/prefer-top-level-await -- fire-and-forget: awaiting fonts.ready at top level would block module evaluation (and studio startup) until webfonts load
-  void document.fonts.ready.then(async () => {
+  void documentFonts.ready.then(async () => {
     const monaco = await import("monaco-editor/editor");
     monaco.editor.remeasureFonts();
   });
@@ -186,7 +195,7 @@ const DOCUMENT_ENTRY_SCHEMA_ID = "file:///document.schema.json";
  * worse, resolved to an empty schema, so the fileMatch registration never ran and REAL violations
  * went unreported behind that one diagnostic.
  */
-function applyJsonSchemas(documentSchema: unknown, projectJsonSchema: unknown) {
+function applyJsonSchemas(documentSchema: JsonObject, projectJsonSchema: JsonObject) {
   jsonDefaults.setDiagnosticsOptions({
     allowComments: false,
     schemas: [
@@ -212,8 +221,8 @@ function applyJsonSchemas(documentSchema: unknown, projectJsonSchema: unknown) {
    a URI before the `#` by FETCHING it — with `enableSchemaRequest` off that just fails, leaving
    `$paths` reporting an unresolvable ref. Flattening rewrites those refs onto the shipped defaults
    embedded in the same document, which is exactly the right fallback semantics. */
-const FALLBACK_DOCUMENT_SCHEMA = flattenSchema(jxSchema as Record<string, unknown>);
-const FALLBACK_PROJECT_SCHEMA = flattenSchema(projectSchema as Record<string, unknown>);
+const FALLBACK_DOCUMENT_SCHEMA = flattenSchema(jxSchema);
+const FALLBACK_PROJECT_SCHEMA = flattenSchema(projectSchema);
 
 // Bundled core schemas register at module init — the offline fallback every platform starts from.
 applyJsonSchemas(FALLBACK_DOCUMENT_SCHEMA, FALLBACK_PROJECT_SCHEMA);
@@ -232,9 +241,7 @@ applyJsonSchemas(FALLBACK_DOCUMENT_SCHEMA, FALLBACK_PROJECT_SCHEMA);
  * @param {object | null} schemas - Pre-bundled `{ document, project }` payload
  * @returns {boolean} True when per-project schemas were applied; false on fallback
  */
-export function applyProjectSchemas(
-  schemas: { project?: unknown; document?: unknown } | null | undefined,
-): boolean {
+export function applyProjectSchemas(schemas: ProjectSchemasResponse | null | undefined): boolean {
   const { document, project } = schemas ?? {};
   if (!document && !project) {
     return false;

package/src/services/notify.ts

@@ -34,6 +34,7 @@
  * this module learning it exists.
  */
 
+import type { CommandArgValues } from "../commands/command-args";
 import { reactive } from "../reactivity";
 import { announce } from "./announce";
 import { now } from "./clock";
@@ -87,7 +88,7 @@ export interface NotifyOptions {
    */
   action?: string;
   /** Args passed to {@link NotifyOptions.action} when it runs. */
-  actionArgs?: Record<string, unknown>;
+  actionArgs?: CommandArgValues;
   /** The long form — a stack, a captured log, a validator's output. Rendered in Problems only. */
   detail?: string;
   /** Who reported it: "Save", "Source Control", "Canvas", "Assistant". Groups the Problems list. */
@@ -114,7 +115,7 @@ export interface Notification {
   /** Epoch ms from {@link now}, so a pinned clock pins the "2m ago" a Problems row renders. */
   readonly at: number;
   readonly action?: string;
-  readonly actionArgs?: Record<string, unknown>;
+  readonly actionArgs?: CommandArgValues;
   readonly detail?: string;
   readonly source?: string;
   readonly path?: string;
@@ -158,6 +159,45 @@ function storeFor(tier: NotificationTier): Notification[] {
   return tier === "problem" ? problems : toasts;
 }
 
+/** A record's mutable draft: {@link Notification} is frozen to readers, not to its one builder. */
+type NotificationDraft = { -readonly [K in keyof Notification]: Notification[K] };
+
+/**
+ * Build the record for one outcome, copying only the options the caller actually set — so a host
+ * rendering `record.detail` never meets an explicit `undefined` — in the order every record has
+ * always carried its keys.
+ */
+function recordFor(
+  severity: Severity,
+  message: string,
+  tier: NotificationTier,
+  options: NotifyOptions,
+): Notification {
+  const record: NotificationDraft = { at: now(), id: nextId(), message, severity, tier };
+  if (options.action !== undefined) {
+    record.action = options.action;
+  }
+  if (options.actionArgs !== undefined) {
+    record.actionArgs = options.actionArgs;
+  }
+  if (options.detail !== undefined) {
+    record.detail = options.detail;
+  }
+  if (options.source !== undefined) {
+    record.source = options.source;
+  }
+  if (options.path !== undefined) {
+    record.path = options.path;
+  }
+  if (options.key !== undefined) {
+    record.key = options.key;
+  }
+  if (tier === "toast") {
+    record.timeoutMs = options.timeoutMs ?? TOAST_LIFETIME_MS[severity];
+  }
+  return record;
+}
+
 /**
  * Record an outcome and return it.
  *
@@ -170,20 +210,7 @@ export function notify(
   options: NotifyOptions = {},
 ): Notification {
   const tier = options.tier ?? DEFAULT_TIER[severity];
-  const record: Notification = {
-    at: now(),
-    id: nextId(),
-    message,
-    severity,
-    tier,
-    ...(options.action === undefined ? {} : { action: options.action }),
-    ...(options.actionArgs === undefined ? {} : { actionArgs: options.actionArgs }),
-    ...(options.detail === undefined ? {} : { detail: options.detail }),
-    ...(options.source === undefined ? {} : { source: options.source }),
-    ...(options.path === undefined ? {} : { path: options.path }),
-    ...(options.key === undefined ? {} : { key: options.key }),
-    ...(tier === "toast" ? { timeoutMs: options.timeoutMs ?? TOAST_LIFETIME_MS[severity] } : {}),
-  };
+  const record = recordFor(severity, message, tier, options);
 
   const store = storeFor(tier);
   if (record.key !== undefined) {
@@ -273,7 +300,7 @@ export interface ProblemFinding {
   path?: string;
   key?: string;
   action?: string;
-  actionArgs?: Record<string, unknown>;
+  actionArgs?: CommandArgValues;
 }
 
 /**