@jxsuite/studio 6.1.1 → 6.1.2

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;
 }
 
 /**

package/src/services/popover-report.ts

@@ -23,6 +23,7 @@
 
 import { activeTab } from "../workspace/workspace";
 import { clearProblems, notify, problemFindings } from "./notify";
+import type { NotifyOptions } from "./notify";
 import {
   findPopoverDefects,
   popoverDisplayRepair,
@@ -39,7 +40,8 @@ import {
 } from "../tabs/transact";
 import { getNodeAtPath } from "../state";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
-import type { JxElement, JxMutableNode } from "@jxsuite/schema/types";
+import type { CommandArgValues } from "../commands/command-args";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
 import type { PopoverFix, PopoverPath } from "@jxsuite/schema/overlays";
 
@@ -100,7 +102,7 @@ export function reportPopoverProblems(doc: JxElement, path?: string): number {
   const defects = findPopoverDefects(doc, KIT_SCOPE);
   for (const defect of defects) {
     const action = defect.fix === undefined ? undefined : REPAIR_COMMAND[defect.fix];
-    notify(defect.severity, defect.message, {
+    const options: NotifyOptions = {
       detail: defect.detail,
       /* Keyed by RULE AND PATH, not by rule alone: a header with two popovers can carry the same
          defect twice, and a key that collapsed them would report one and silently drop the other.
@@ -109,32 +111,45 @@ export function reportPopoverProblems(doc: JxElement, path?: string): number {
       key: problemKey(seen, "popover", defect.rule, defect.path),
       source: POPOVER_PROBLEM_SOURCE,
       tier: "problem",
-      ...(action === undefined ? {} : { action, actionArgs: { path: defect.path } }),
-      ...(path === undefined ? {} : { path }),
-    });
+    };
+    if (action !== undefined) {
+      options.action = action;
+      options.actionArgs = { path: defect.path };
+    }
+    if (path !== undefined) {
+      options.path = path;
+    }
+    notify(defect.severity, defect.message, options);
   }
   /* The dialog and invoker-command rules (`spec.md` §8.7) file under the same source: one report
      for everything the platform overlays. They carry no repair button yet — the popover repairs
      move `display` into `:popover-open`, and a dialog's open rule is a different selector. */
   const dialogDefects = findDialogDefects(doc, KIT_SCOPE);
   for (const defect of dialogDefects) {
-    notify(defect.severity, defect.message, {
+    const options: NotifyOptions = {
       detail: defect.detail,
       key: problemKey(seen, "dialog", defect.rule, defect.path),
       source: POPOVER_PROBLEM_SOURCE,
       tier: "problem",
-      ...(path === undefined ? {} : { path }),
-    });
+    };
+    if (path !== undefined) {
+      options.path = path;
+    }
+    notify(defect.severity, defect.message, options);
   }
   return defects.length + dialogDefects.length;
 }
 
 /** Read the path argument a repair command was invoked with, or throw naming the command. */
-function repairPath(id: string, args: Record<string, unknown> | undefined): JxPath {
+function repairPath(id: string, args: CommandArgValues | undefined): JxPath {
   const path = args?.path;
   if (!Array.isArray(path)) {
     throw new RangeError(`command "${id}" needs a "path" argument naming the popover`);
   }
+  /* SAFETY: every repair record below declares `path` as an array whose items are
+     `["string", "number"]`, which `coerceArgs` reads as a path argument and checks segment by
+     segment (`pathArg`) before `run` is called — so an array that reached here holds only string
+     keys and numeric indexes. */
   return path as JxPath;
 }
 
@@ -217,7 +232,7 @@ export function popoverCommands(): AnyCommand[] {
         const id = "document.repairPopoverDisplay";
         const tab = repairTab(id);
         const path = repairPath(id, args);
-        const node = getNodeAtPath(tab.doc.document, path) as JxMutableNode | undefined;
+        const node = getNodeAtPath(tab.doc.document, path);
         const repair = popoverDisplayRepair(node?.style);
         if (!repair) {
           throw new RangeError(`command "${id}": nothing to move — this popover sets no display`);

package/src/services/preview-eval.ts

@@ -10,12 +10,15 @@
  */
 
 import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import { toRaw } from "../reactivity";
 // Imported for local use AND re-exported below so existing consumers keep their import site.
 // oxlint-disable-next-line unicorn/prefer-export-from
 import { formatPreviewValue } from "../utils/preview-format";
+import type { PreviewValue } from "../utils/preview-format";
 
-import type { ExpressionNode } from "@jxsuite/runtime/expression";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { JxExpressionNode, JxExpressionOperand } from "@jxsuite/schema/types";
 
 export interface ExpressionPreview {
   /** Path-keyed display values: "" is the root node, "value/target" a nested operand, etc. */
@@ -36,14 +39,14 @@ export { formatPreviewValue };
  * (canvas not yet rendered) — the editor renders no badges rather than wrong ones.
  */
 export function previewExpression(
-  node: unknown,
-  scope?: Record<string, unknown> | null,
+  node: JxExpressionOperand | undefined,
+  scope?: JxScope | null,
 ): ExpressionPreview | null {
-  if (!scope || !node || typeof node !== "object" || !("operator" in node)) {
+  if (!scope || !isNonNullObject(node) || !("operator" in node)) {
     return null;
   }
 
-  let state: Record<string, unknown>;
+  let state: JxScope;
   try {
     // Callers hand over tab.session.canvas.scope, which the reactive session tree wraps in a
     // Proxy — structuredClone rejects proxies, so unwrap to the raw snapshot first.
@@ -54,11 +57,20 @@ export function previewExpression(
   }
 
   const values = new Map<string, string>();
-  const expr = node as ExpressionNode;
+  /* SAFETY: an operand object carrying `operator` is the expression-node member of the operand
+     union (the plain-object member is an options bag, which has no operator), and a node whose
+     other members are malformed throws inside `evaluateExpression`, which this preview reports
+     as its `error` rather than trusting. */
+  const expr = node as JxExpressionNode;
   let errorMessage: string | null = null;
   try {
-    evaluateExpression(expr, state, null, undefined, {
-      report: (path, value) => values.set(path.join("/"), formatPreviewValue(value)),
+    void evaluateExpression(expr, state, null, undefined, {
+      report: (path, value) => {
+        /* SAFETY: the trace reports raw runtime values, and PreviewValue names every category a JS
+           value falls in (primitive, bigint, symbol, function, array, record); formatting relies on
+           nothing beyond what JSON.stringify and String() accept for any value. */
+        values.set(path.join("/"), formatPreviewValue(value as PreviewValue));
+      },
     });
   } catch (error) {
     errorMessage = error instanceof Error ? error.message : String(error);

package/src/services/profile.ts

@@ -40,7 +40,7 @@ export interface StartupProfile {
  * `default` is not a no-op by omission — it is a named state, so "the app started normally" and
  * "the profile was unrecognised" are different outcomes and the second one is loud.
  */
-export const STARTUP_PROFILES: Readonly<Record<string, StartupProfile>> = {
+export const STARTUP_PROFILES = {
   default: {
     description: "Resume whatever was persisted — layout, recents, settings, chat history.",
     id: "default",
@@ -51,7 +51,10 @@ export const STARTUP_PROFILES: Readonly<Record<string, StartupProfile>> = {
     id: "fresh",
     reset: "app-state",
   },
-};
+} satisfies Readonly<Record<string, StartupProfile>>;
+
+/** {@link STARTUP_PROFILES} by id, for a lookup whose id arrives from the query string. */
+const PROFILES_BY_ID = new Map<string, StartupProfile>(Object.entries(STARTUP_PROFILES));
 
 export const DEFAULT_PROFILE_ID = "default";
 
@@ -77,7 +80,8 @@ export function isStudioStorageKey(key: string): boolean {
  * @returns The keys removed, so a caller (Preferences, a test) can report what it did.
  */
 export function clearStudioStorage(): string[] {
-  const store = globalThis.localStorage as Storage | undefined;
+  // `localStorage` is absent outside a browser realm (Bun without a DOM shim), whatever lib.dom says.
+  const store = typeof localStorage === "undefined" ? undefined : localStorage;
   if (!store) {
     return [];
   }
@@ -105,10 +109,10 @@ export function clearStudioStorage(): string[] {
  *   `default` would start the app in the state the caller was trying to avoid.
  */
 export function applyProfile(id: string): StartupProfile {
-  const profile = STARTUP_PROFILES[id];
+  const profile = PROFILES_BY_ID.get(id);
   if (!profile) {
     throw new RangeError(
-      `unknown startup profile "${id}"; declared: ${Object.keys(STARTUP_PROFILES).join(", ")}`,
+      `unknown startup profile "${id}"; declared: ${[...PROFILES_BY_ID.keys()].join(", ")}`,
     );
   }
   if (profile.reset === "app-state") {
@@ -137,7 +141,10 @@ export function applyStartupProfile(search?: string): StartupState {
   if (_startup) {
     return _startup;
   }
-  const query = new URLSearchParams(search ?? globalThis.location?.search ?? "");
+  // `location` is absent outside a browser realm, which is why the tests pass `search` themselves.
+  const query = new URLSearchParams(
+    search ?? (typeof location === "undefined" ? "" : location.search),
+  );
   const profile = applyProfile(query.get("profile") ?? DEFAULT_PROFILE_ID);
   const clockParam = query.get("clock");
   _startup = { clock: clockParam === null ? null : pinClock(clockParam), profile };