@jxsuite/studio 5.0.0 → 5.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -59,23 +59,23 @@
   },
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "^3.1.0",
-    "@atlaskit/pragmatic-drag-and-drop-hitbox": "^2.2.0",
-    "@jxsuite/ai": "^0.37.1",
+    "@atlaskit/pragmatic-drag-and-drop-hitbox": "^2.2.2",
+    "@jxsuite/ai": "^0.37.2",
     "@jxsuite/collab": "^0.9.0",
-    "@jxsuite/create": "^1.3.10",
-    "@jxsuite/formulas": "^0.0.17",
+    "@jxsuite/create": "^1.3.11",
+    "@jxsuite/formulas": "^0.0.18",
     "@jxsuite/markup": "^0.4.10",
-    "@jxsuite/protocol": "^2.3.0",
-    "@jxsuite/runtime": "^4.0.0",
+    "@jxsuite/protocol": "^2.3.1",
+    "@jxsuite/runtime": "^4.0.1",
     "@jxsuite/schema": "^2.2.0",
-    "@jxsuite/site": "^2.0.0",
-    "@jxsuite/ui": "^0.1.0",
-    "@vue/reactivity": "3.5.42",
+    "@jxsuite/site": "^2.0.1",
+    "@jxsuite/ui": "^0.2.0",
+    "@vue/reactivity": "3.5.43",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "lit-html": "^3.3.3",
     "monaco-editor": "^0.56.0",
-    "tabulator-tables": "^6.5.2",
+    "tabulator-tables": "^6.5.3",
     "yaml": "^2.9.1"
   },
   "devDependencies": {

package/src/canvas/canvas-utils.ts

@@ -1024,8 +1024,35 @@ export function canvasViewCommands(deps: CanvasCommandDeps): AnyCommand[] {
       group: "3_canvas",
       requires: "an open document",
       when: documentOpen,
-      /* No `aiTool`, by §12.4's first deletion rule: chrome. `open_document` lands on the canvas,
-         and the tree tools key on `editor.kind`, not the mode. */
+      /*
+       * Projected, and it was deleted once under §12.4's first rule (chrome). The rule is about a
+       * verb whose WHOLE effect is what the person is looking at, and this one's is not: the tree
+       * tools are gated on `editor.kind`, which is derived from the mode (`editorKindForMode`), so
+       * a document the person left in Code — or the model itself moved — refuses every tree write
+       * with "requires an open document whose element tree the canvas is editing", and without this
+       * verb the model had no way back to a state it can read. `run` acts on the active tab and
+       * the model reads the result: `after.editor.kind` is the same fact the gate reads.
+       */
+      aiTool: {
+        description:
+          "Switch the active document's editor mode. edit and design put its element tree on " +
+          "the canvas, where the document tools work; preview renders it as a visitor sees it; " +
+          "source shows the JSON; stylebook, grid and git-diff open other editors. Use it to " +
+          "return a document to edit or design when the tree tools are refused.",
+        name: "set_canvas_mode",
+        /* `after.editor.kind` rather than the tab's own field: it is the gate's read (`treeEditable`
+           in `document-assistant.ts` is `editor.kind === "canvas"`), so the sentence and the gate
+           cannot disagree. The mode named is the one requested — `run` resolved, so it is the mode
+           the tab is in. */
+        report: ({ after, args }) => {
+          const mode = enumArg("canvas.setMode", args, "mode", CANVAS_MODES);
+          const reach =
+            after.editor.kind === "canvas"
+              ? "the document tools address its element tree"
+              : "the tree-editing tools are unavailable until it returns to edit or design";
+          return `The active document is in ${mode} mode; ${reach}.`;
+        },
+      },
       run: (_commandCtx, args) => {
         const mode = enumArg("canvas.setMode", args, "mode", CANVAS_MODES);
         const tab = requireTab("canvas.setMode");

package/src/commands/command-args.ts

@@ -72,6 +72,23 @@ export function numberArg(commandId: string, args: CommandArgValues, key: string
   return value;
 }
 
+/**
+ * A required integer argument. `1.5` is a refusal, not a value to round: a caller naming an index
+ * or a count with a fraction in it has said something the app cannot mean.
+ *
+ * Its own reader rather than `numberArg` plus a check in `run`, because `coerceArgs` routes a bare
+ * `type: "integer"` here — without it the row read as a plain number and `1.5` passed the schema
+ * pass to fail, or not, in whatever `run` did with it. `typedArg` already held a type LIST to
+ * integrality; this is the same rule for the bare form.
+ */
+export function integerArg(commandId: string, args: CommandArgValues, key: string): number {
+  const value = args[key];
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw refuse(commandId, key, `expected an integer, got ${describe(value)}`);
+  }
+  return value;
+}
+
 /**
  * A required number argument inside a closed interval.
  *
@@ -330,6 +347,7 @@ export type CoercionRow =
   | "boolean"
   | "bounded-number"
   | "number"
+  | "integer"
   | "string"
   | "path"
   | "path-list"
@@ -373,8 +391,13 @@ export function describeShape(property: object): CoercionRow {
     case "number":
     case "integer": {
       // Both bounds, as `numberProperty` writes them. A half-open interval is not a shape any
-      // Record declares, so it reads as a plain number and `run` owns the bound.
-      return p.minimum !== undefined && p.maximum !== undefined ? "bounded-number" : "number";
+      // Record declares, so it reads as a plain number and `run` owns the bound. A bounded integer
+      // Is the `bounded-number` row too, which holds it to integrality before the interval; only
+      // The BARE integer goes to `integerArg`, whose whole rule is integrality.
+      if (p.minimum !== undefined && p.maximum !== undefined) {
+        return "bounded-number";
+      }
+      return p.type === "integer" ? "integer" : "number";
     }
     case "string": {
       return "string";
@@ -486,6 +509,9 @@ function shapeOf(property: PropertySchema): string {
     case "number": {
       return "a finite number";
     }
+    case "integer": {
+      return "an integer";
+    }
     case "string": {
       return "a non-empty string";
     }
@@ -577,11 +603,20 @@ function coerceProperty(
       return booleanArg(commandId, args, key);
     }
     case "bounded-number": {
+      // Integrality first, so `{ type: "integer", minimum: 1, maximum: 9 }` refuses `1.5` by name
+      // Rather than admitting it as a number inside the interval — the static check's `type` row
+      // Already refused it, and the two passes must agree.
+      if (property.type === "integer") {
+        integerArg(commandId, args, key);
+      }
       return boundedNumberArg(commandId, args, key, property.minimum!, property.maximum!);
     }
     case "number": {
       return numberArg(commandId, args, key);
     }
+    case "integer": {
+      return integerArg(commandId, args, key);
+    }
     case "string": {
       return stringArg(commandId, args, key);
     }

package/src/commands/registry.ts

@@ -27,7 +27,9 @@
  *
  * The registry takes its context by injection (`getContext`), so nothing here imports a state
  * module. That is what lets the CI checks import the command set in a bare Bun process and lets
- * every test build the exact state it wants to assert against.
+ * every test build the exact state it wants to assert against. The one store it reaches is the
+ * notification store, through `run-reported.ts`, and only from `handleKeyEvent`: a chord's refusal
+ * has no caller to hand it to, so the registry files it where every other surface's refusal goes.
  */
 
 import { createKeymap } from "./keymap";
@@ -35,6 +37,7 @@ import type { KeyChordEvent, Keymap, KeymapMatch } from "./keymap";
 import { checkRecordPlacements } from "./levels";
 import type { Category, KeyScope, Level, Placement } from "./levels";
 import { coerceArgs } from "./command-args";
+import { runReported } from "./run-reported";
 import type { CommandContext } from "./context";
 
 /** Arguments as they arrive from a palette prompt, an automation manifest step or an AI tool call. */
@@ -435,13 +438,20 @@ export function createCommandRegistry(options: CommandRegistryOptions): CommandR
       if (!registry.isEnabled(hit.commandId)) {
         return hit.commandId;
       }
-      /* An ARGUMENT refusal is the one throw that still leaves here, on purpose. A chord runs its
-         record with `{}`, and `run` coerces that against the schema first, so a record whose
-         schema requires a key cannot be a chord — every shipped keybinding is held to
-         `required: []` by the sweep in `tests/command-args.test.ts`, and a user's own keymap
-         override that binds one anyway hears about it as a RangeError naming the command and the
-         key, rather than as a chord that silently does nothing. */
-      void registry.run(hit.commandId);
+      /* An ARGUMENT refusal is the one refusal that can still happen here, and it is REPORTED
+         rather than thrown. A chord runs its record with `{}`, and `run` coerces that against the
+         schema first, so a record whose schema requires a key cannot be a chord — every shipped
+         keybinding is held to `required: []` by the sweep in `tests/command-args.test.ts`, and a
+         user's own keymap override that binds one anyway hears about it as a Problems row naming
+         the command and the key, rather than as a chord that silently does nothing. It used to
+         leave as a `RangeError` out of the keydown listener, which named the same things to the
+         console and to nobody; `run-reported.ts` is what catches that shape, and the rejection a
+         `run` body may produce later, for every surface alike. A gate that closes BETWEEN the
+         `isEnabled` above and `run`'s own re-read is reported the same way, and that is a choice:
+         the silent claim above is for a chord the person can see is disabled, while a gate that
+         moved under the chord is state the person cannot see, and the `requires` sentence in
+         Problems is the one account of why nothing happened. */
+      void runReported(registry, hit.commandId, undefined, "Keyboard");
       return hit.commandId;
     },
     context: options.getContext,

package/src/commands/run-reported.ts

@@ -0,0 +1,120 @@
+/**
+ * Run-reported.ts — run a command from a surface, and let a refusal land in Problems.
+ *
+ * `registry.run` refuses in two shapes, and a caller that catches one and not the other still lets
+ * a refusal out. It throws SYNCHRONOUSLY — `CommandUnavailableError` when the gate refuses, a
+ * `RangeError` when `coerceArgs` refuses the received record BEFORE `run` is entered, and whatever
+ * a synchronous `run` body throws — and it REJECTS when an async `run` body does. A bare `void
+ * registry.run(id, args)` lets the first shape out of the click, keydown or notice action it came
+ * from, and a `.catch` on the promise alone catches nothing when `run` has already thrown; a
+ * `Promise.resolve(registry.run(...))` around it is the same mistake with more characters, because
+ * the argument is evaluated first. Three surfaces had grown the same six-line try/catch in reply
+ * (the palette's `runCommand`, the Settings menu's `runRow` and the Languages panel's `runByName`)
+ * while ten others still ran bare, which is the drift issue 333 names: a refusal reached Problems
+ * or the console depending on which surface the person happened to be on.
+ *
+ * This is the one spelling. It catches both shapes, files the sentence in Problems — the tier
+ * `notify.error` chooses, and the right one: a refusal names something the person has to fix or a
+ * schema that drifted from its caller, and neither is a toast that may be taken away — and returns
+ * a promise that never rejects, so a caller may `void` it or `await` it without a `.catch`.
+ *
+ * A refusal is the whole message; a CRASH is not. `CommandUnavailableError` and `RangeError` are
+ * the two shapes the registry and `coerceArgs` refuse with, and each is a sentence written to be
+ * read, so the Problems row is complete. Anything else out of a `run` body — a `TypeError` on a
+ * node that was not there — is a bug, and its stack is the part that matters; the row still names
+ * it, and the error object also goes to the console, where the palette used to send everything and
+ * where a trace can be opened. Without that the helper would have made every surface quieter than
+ * the keydown listener it replaced, which reached `window.onerror`.
+ *
+ * Two spellings, one rule. {@link runReported} takes the registry as a PARAMETER: `editor/
+ * shortcuts.ts`, the block action bar and the registry's own `handleKeyEvent` are handed theirs,
+ * and a helper that resolved the active registry for them would silently do nothing wherever a
+ * test, or a second window kind, ran a registry that is not the published one.
+ * {@link runActiveReported} is the same call for a surface that was spelled `void
+ * activeRegistry()?.run(id, args)` — a footer row, a palette hit, a tab-strip chip — and it keeps
+ * that spelling's one property: before the bootstrap has published a registry there is nothing to
+ * run and nothing to report, exactly as the `?.` was silent.
+ *
+ * The sweep in `tests/run-reported.test.ts` walks `packages/studio/src` for any other `.run(` on a
+ * registry. Two callers own their refusal and are named there as such — `services/automation.ts`
+ * and `services/ai-command-tools.ts`, where the script or the model is the one who reads it — and
+ * the `?.run(` spelling issue 333 did not list survives in a RATCHET of files the sweep names one
+ * by one, each still holding a bare call; the list can only shrink, so a new surface cannot spell
+ * it bare and an existing one converted must drop its entry.
+ *
+ * `runReported` does not pre-check `isEnabled`. A surface that renders a disabled control for a
+ * refused record has already shown the `requires` sentence, and a click that arrives on one anyway
+ * (state moved between the render and the click) is a refusal the person should read, not a
+ * swallowed no-op. The callers that DO pre-check keep doing so for their own reasons — a chord on a
+ * disabled command is claimed silently by `handleKeyEvent`, by design — and route what remains
+ * through here.
+ *
+ * @docs studio/interface/problems-and-progress
+ */
+
+import { errorMessage } from "@jxsuite/schema/parse";
+import { notify } from "../services/notify";
+import { activeRegistry } from "./active-registry";
+import type { CommandArgs, CommandRegistry } from "./registry";
+
+/**
+ * Whether an error is one of the two REFUSAL shapes, whose message is written to be read whole.
+ *
+ * By name rather than `instanceof CommandUnavailableError`: `registry.ts` imports this module for
+ * `handleKeyEvent`, and a value import back would close a cycle for one class whose constructor
+ * sets exactly this name. `RangeError` is the shape `coerceArgs` and a `run` body refuse with.
+ */
+function isRefusal(error: unknown): boolean {
+  return (
+    error instanceof RangeError ||
+    (error instanceof Error && error.name === "CommandUnavailableError")
+  );
+}
+
+/**
+ * Run `id` with `args` on `registry`, and file whatever refuses it in Problems under `source`.
+ *
+ * `source` is the SURFACE the run came from ("Palette", "Keyboard", "Languages"), the column the
+ * Problems panel groups by; it defaults to the command id, which is what the Settings menu filed
+ * under before this helper existed and is still a true answer to "who reported it". The Problems
+ * row is keyed by the command id, so a chord held down on a refusing record is one problem rather
+ * than sixty — the file-watcher rule `services/notify.ts` writes down for `key`.
+ *
+ * The returned promise settles when the command does, and never rejects: an `await` on it is a
+ * wait, not a second place the refusal could escape from.
+ */
+export function runReported(
+  registry: CommandRegistry,
+  id: string,
+  args?: CommandArgs,
+  source: string = id,
+): Promise<void> {
+  const report = (error: unknown) => {
+    if (!isRefusal(error)) {
+      // A crash, not a refusal: the row below carries the sentence, the console keeps the stack.
+      console.error(`${source}: command "${id}" failed`, error);
+    }
+    notify.error(errorMessage(error), { key: `command.run:${id}`, source });
+  };
+  let result: void | Promise<void>;
+  try {
+    result = registry.run(id, args);
+  } catch (error) {
+    report(error);
+    return Promise.resolve();
+  }
+  return Promise.resolve(result).catch(report);
+}
+
+/**
+ * {@link runReported} on this window's registry, or nothing before the bootstrap has published one.
+ *
+ * The `?.` this replaces was the surfaces' answer to `active-registry.ts` returning `null` for the
+ * frame before the bootstrap composes the registry; a click that lands in that frame has no
+ * registry to refuse it, so there is no refusal to file. The resolved promise keeps the caller's
+ * `void` honest either way.
+ */
+export function runActiveReported(id: string, args?: CommandArgs, source?: string): Promise<void> {
+  const registry = activeRegistry();
+  return registry ? runReported(registry, id, args, source) : Promise.resolve();
+}

package/src/editor/shortcuts.ts

@@ -77,7 +77,7 @@ import { clipboardCommands, pasteNode } from "./context-menu";
 import { hasElementSelection, hasSelection, inCanvas, keyScopeStack } from "../commands/context";
 import { defaultCommands } from "../commands/defaults";
 import { setActiveRegistry } from "../commands/active-registry";
-import { CommandUnavailableError } from "../commands/registry";
+import { runReported } from "../commands/run-reported";
 import type { CommandContext } from "../commands/context";
 import type { DockId as CommandDockId } from "../commands/defaults";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
@@ -388,11 +388,12 @@ function toggleShellDock(registry: CommandRegistry, dock: CommandDockId): void {
  *
  * `view.setAssistant` and `view.setRightTab` are `shell.ts`'s, composed into the app's registry by
  * the bootstrap — a reduced registry (a test, a future second window kind) may not carry them, and
- * a missing id must be inert rather than an exception thrown out of a keydown handler.
+ * a missing id must be inert rather than an exception thrown out of a keydown handler. A present
+ * one that refuses its arguments is not inert: `commands/run-reported.ts` files it in Problems.
  */
 function runIfPresent(registry: CommandRegistry, id: string, args: Record<string, unknown>): void {
   if (registry.get(id) && registry.isEnabled(id)) {
-    void registry.run(id, args);
+    void runReported(registry, id, args, "Keyboard");
   }
 }
 
@@ -901,34 +902,21 @@ export function registerStudioCommands(
  *
  * `preventDefault()` iff a command claimed the chord. A command that is VISIBLE but disabled — ⌘Z
  * with nothing to undo, Delete on the document element — still counts as claiming it: the registry
- * throws {@link CommandUnavailableError} from `run`, and swallowing the key is the honest outcome,
- * because the chord is spoken for and letting the browser act on it instead would be a surprise.
- *
- * HANDOFF: `registry.handleKeyEvent` reports the hit and runs it in one step, so a refusal can only
- * be observed by catching. It would be better for it to consult `isEnabled` itself and return the
- * id without running; `commands/registry.ts` is another workstream's file this wave.
+ * consults `isEnabled` itself and returns the id without running, and swallowing the key is the
+ * honest outcome, because the chord is spoken for and letting the browser act on it instead would
+ * be a surprise. Nothing is caught here, because nothing leaves: `handleKeyEvent` runs the hit
+ * through `commands/run-reported.ts`, so a record that refuses its arguments, a gate that closed
+ * between the check and the run, or a `run` body that throws is a Problems row under "Keyboard"
+ * rather than an exception out of the keydown listener.
  */
 function dispatchKey(registry: CommandRegistry, event: KeyboardEvent): string | undefined {
-  const commandId = claimChord(registry, event);
+  const commandId = registry.handleKeyEvent(event, keyScopeStack(registry.context()));
   if (commandId) {
     event.preventDefault();
   }
   return commandId;
 }
 
-/** The id of the command that claimed the chord, whether it ran or refused. */
-function claimChord(registry: CommandRegistry, event: KeyboardEvent): string | undefined {
-  const stack = keyScopeStack(registry.context());
-  try {
-    return registry.handleKeyEvent(event, stack);
-  } catch (error) {
-    if (error instanceof CommandUnavailableError) {
-      return error.commandId;
-    }
-    throw error;
-  }
-}
-
 // ─── Pointer and wheel gestures ───────────────────────────────────────────────
 
 /**

package/src/files/components.ts

@@ -3,6 +3,7 @@
 import { getPlatform } from "../platform";
 import { projectState } from "../store";
 import type { ComponentMeta } from "../types";
+import { componentMetaFrom } from "@jxsuite/schema/component-meta";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
 /** A discovered component: project components carry a file path; package components may not. */
@@ -26,6 +27,44 @@ export async function loadComponentRegistry() {
   }
 }
 
+/**
+ * Bring the registry up to date with a document that was just saved.
+ *
+ * The registry is the snapshot the platform's scan took when the project opened, and a saved
+ * component definition used to leave it behind: give a prop `format: "image"` in the definition and
+ * every instance's Component Settings kept drawing the text box the snapshot knew, until the
+ * project was reopened. The saved document is the same input the scan reads, through the same
+ * extractor (`componentMetaFrom`, shared by all three backends), so the entry is rebuilt from it
+ * here rather than by a rescan of every JSON file in the project. A definition that stopped being a
+ * component (its `tagName` lost its hyphen) leaves the registry by the same rule the scan applies.
+ *
+ * @param {string | null} path - The saved document's project-relative path; `null` for an unsaved
+ *   draft, which no scan would have seen either.
+ * @param {unknown} doc - The saved document.
+ * @returns {boolean} Whether the registry changed, so a caller knows to repaint what reads it.
+ */
+export function noteComponentSaved(path: string | null, doc: unknown): boolean {
+  if (!path) {
+    return false;
+  }
+  const index = componentRegistry.findIndex((c) => c.path === path);
+  const meta = componentMetaFrom(doc, path);
+  if (!meta) {
+    if (index === -1) {
+      return false;
+    }
+    componentRegistry.splice(index, 1);
+    return true;
+  }
+  const entry = meta as ComponentEntry;
+  if (index === -1) {
+    componentRegistry.push(entry);
+  } else {
+    componentRegistry[index] = entry;
+  }
+  return true;
+}
+
 /**
  * Build a fresh instance definition for a component: $props from prop defaults, plus the
  * component's slot fallback children cloned in as starting content so editors can edit from the

package/src/files/files.ts

@@ -60,6 +60,7 @@ import {
 } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
 import { combine } from "@atlaskit/pragmatic-drag-and-drop/combine";
 import {
+  PRIMARY_PANE,
   activateTab,
   moveTabToPane,
   openTab,
@@ -73,6 +74,7 @@ import {
 import { openCsvGridTab, openPagesGrid } from "../grid/grid-open";
 import { isViewableMedia, openMediaTab } from "../media/media-open";
 import { activeRegistry } from "../commands/active-registry";
+import { runActiveReported, runReported } from "../commands/run-reported";
 import { collectionOfPath } from "../content/entry-model";
 import { confirmFileDelete, parseSourceForPath, renamePromptMessage } from "./file-ops";
 import { parseJsonDocument } from "./json-layout";
@@ -404,7 +406,7 @@ export async function openLastSessionOrHome(): Promise<boolean> {
   if (session) {
     const opened = await restoreSession(session, {
       ensureSecondPane: () => {
-        receivingPane();
+        receivingPane(PRIMARY_PANE);
       },
       openFile: (path, paneId) => openFileInTab(path, { focus: false, paneId }),
     });
@@ -1524,6 +1526,11 @@ function fileRowFacts(entry: { path: string; type: string }): Record<string, unk
     }
     return facts;
   }
+  /* Every file row states `file`, because `document.openToSide` takes one and the row is the only
+     thing that knows it — the same reason `content.openEntry`'s `path` is stated here. A command
+     whose required arguments this row cannot answer is skipped, so without this fact the
+     "Open to the Side" row would never render on any file. */
+  facts.file = entry.path;
   if (collectionOfPath(entry.path)) {
     facts.path = entry.path;
   }
@@ -1582,7 +1589,7 @@ function placedFileRows(entry: { path: string; type: string }): MenuRowProjectio
     rows.push(
       reason === undefined
         ? treeMenuRow(command.id, command.title, () => {
-            void registry.run(command.id, args);
+            void runReported(registry, command.id, args, "Files");
           })
         : {
             destructive: false,
@@ -2237,23 +2244,36 @@ export interface OpenFileOpts {
 /**
  * Bring an ALREADY-OPEN tab to where the caller asked for it.
  *
- * Three cases, and the third is the one a following pane depends on:
+ * Three cases, and the third is the one a cross-pane open depends on:
  *
- * | the tab is…                                      | behaviour                                      |
- * | ------------------------------------------------ | ---------------------------------------------- |
- * | in the requested pane (or no pane was requested) | activate it there, honouring `focus`           |
- * | elsewhere, and **not** its pane's active tab     | move it — one tab is one document in one strip |
- * | elsewhere, and **is** its pane's active tab      | **nothing.** You are already looking at it     |
+ * | the tab is…                                                                  | behaviour                                      |
+ * | ---------------------------------------------------------------------------- | ---------------------------------------------- |
+ * | elsewhere, and **not** its pane's active tab                                 | move it — one tab is one document in one strip |
+ * | elsewhere, and **is** its pane's active tab, browsing (`focus: false`)       | **nothing.** You are already looking at it     |
+ * | already in the requested pane, or committing (moving/staying, focus follows) | activate it there, honouring `focus`           |
  *
- * The third exists because moving it would oscillate: a derivation that re-resolves to the document
+ * The first exists because moving it would oscillate: a derivation that re-resolves to the document
  * the author is editing would yank it out of their pane and into the assistant one, and the follow
  * would then re-resolve against whatever landed in its place.
+ *
+ * The third is the first's other half, and it is what "Open to the Side" needs: the tab is
+ * elsewhere and IS its pane's active tab, but the caller asked for it in a DIFFERENT pane with the
+ * focus following — the author asked to go there, so "you are already looking at it" is the wrong
+ * answer. The move is a `moveTabToPane`, which activates nothing and moves no focus; the
+ * `activateTab` below then points the keyboard at the pane it landed in.
+ *
+ * **The guard reads `wanted !== undefined && holder` — not also `holder.id !== wanted`.** A tab
+ * already in the requested pane still passes through: `moveTabToPane` is idempotent for a tab
+ * already in `paneId` (its own doc, next to this call), so entering the block and calling it anyway
+ * costs nothing and reaches the identical final `activateTab`. Naming the extra condition would ask
+ * a reader to verify a distinction that changes nothing — the redundant branch this replaced is
+ * `check-lens-mutants.ts`'s own "delete rather than assert" rule, applied to itself.
  */
 function revealOpenTab(tabId: string, opts: OpenFileOpts): void {
   const wanted = opts.paneId;
   const holder = paneOfTab(tabId);
-  if (wanted !== undefined && holder && holder.id !== wanted) {
-    if (holder.activeTabId === tabId) {
+  if (wanted !== undefined && holder) {
+    if (holder.activeTabId === tabId && opts.focus === false) {
       return;
     }
     moveTabToPane(tabId, wanted);
@@ -2292,7 +2312,7 @@ export async function openFileInTab(path: string, opts: OpenFileOpts = {}) {
    * why a branch anywhere else would send a restored media tab straight back down the error path.
    */
   if (isViewableMedia(path)) {
-    openMediaTab(path);
+    openMediaTab(path, opts);
     if (follows) {
       requireProjectState().selectedPath = path;
     }
@@ -2307,8 +2327,10 @@ export async function openFileInTab(path: string, opts: OpenFileOpts = {}) {
   // CSV files open in the grid editor (source mode remains as the raw-text alternate).
   if (path.toLowerCase().endsWith(".csv")) {
     try {
-      await openCsvGridTab(path);
-      requireProjectState().selectedPath = path;
+      await openCsvGridTab(path, opts);
+      if (follows) {
+        requireProjectState().selectedPath = path;
+      }
       trackRecentFile({
         name: path.split("/").pop() || path,
         path,
@@ -2394,8 +2416,10 @@ export async function openFileInTab(path: string, opts: OpenFileOpts = {}) {
  * Open a file into a NAMED pane, browsing rather than committing, leaving the keyboard behind.
  *
  * The same body as {@link openFileInTab} with the three options a side-open always wants, given a
- * signature that says which pane in the first parameter. It is what "open it beside this" means
- * everywhere it is asked for — drilling into a component, following a layout, `pane.compareWith`.
+ * signature that says which pane in the first parameter. It is what the READS mean by "open it
+ * beside this" — following a layout, `pane.compareWith`. The gestures that open something
+ * (drill-in, Open to the Side) call {@link openFileInTab} directly, because the pane they open into
+ * takes the keyboard.
  *
  * @param {string} paneId
  * @param {string} path
@@ -2498,7 +2522,7 @@ const FILE_ACTIONS: FilesPanelActions = {
     /* The DECLARED command, run through the registry — never a second opener of this surface's own
        (§12.5). It is the one the ⌘O chord, the palette and the status bar's PROJECT field already
        run, and it is the only one that knows about the picker modal and the "new window" target. */
-    void activeRegistry()?.run("project.open");
+    void runActiveReported("project.open", undefined, "Files");
   },
   refresh: () => {
     void refreshFileTree();

package/src/grid/grid-lazy.ts

@@ -0,0 +1,59 @@
+/**
+ * Lazy grid engine.
+ *
+ * `grid-view.ts` is the only module that imports `tabulator-tables`, and as of 6.5.3 Tabulator's
+ * `Row` class runs `document.createElement` in a static field, so the CLASS DEFINITION — not the
+ * table's construction — needs a DOM to exist. That makes `grid-view.ts` unsafe to reach with a
+ * static value-import from any module that must load with no DOM: `app-commands.ts` pulls
+ * `gridViewCommands` from `grid-panel.ts` for the command set `scripts/check-command-levels.ts` and
+ * its siblings read in a bare Bun process (see `commands/defaults.ts`'s note on
+ * `selection.convertToComponent` for the sibling convention this follows).
+ *
+ * So `grid-panel.ts` never has a static value-import of `./grid-view`; it loads the engine through
+ * here instead, exactly as `services/monaco-lazy.ts` defers Monaco. Real usage pays no cost for it
+ * — a grid tab cannot exist before `document` does — and the two accessors mirror Monaco's: one for
+ * code that MOUNTS a grid (async is free there), one for code that can only run with a grid engine
+ * already loaded.
+ */
+import type * as gridViewModule from "./grid-view";
+
+export type GridEngine = typeof gridViewModule;
+
+let _engine: GridEngine | null = null;
+let _loading: Promise<GridEngine> | null = null;
+
+/**
+ * Load the Tabulator-backed grid engine. Memoized — concurrent callers share one import.
+ *
+ * @returns {Promise<GridEngine>}
+ */
+export function loadGridEngine(): Promise<GridEngine> {
+  if (_engine) {
+    return Promise.resolve(_engine);
+  }
+  // Not `async`: an async function wraps the memo in a fresh promise per call, so concurrent
+  // Callers could not observe that they share one in-flight load.
+  _loading ??= import("./grid-view").then((engine) => {
+    _engine = engine;
+    return engine;
+  });
+  return _loading;
+}
+
+/**
+ * The loaded engine, or null before the first grid mount.
+ *
+ * For call sites that can run synchronously once a grid already exists in the session — they must
+ * not force the module to load, only read it if it is already there.
+ *
+ * @returns {GridEngine | null}
+ */
+export function loadedGridEngine(): GridEngine | null {
+  return _engine;
+}
+
+/** Reset the memo (tests only). */
+export function resetGridLazy(): void {
+  _engine = null;
+  _loading = null;
+}