@jxsuite/studio 5.1.0 → 5.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -59,31 +59,31 @@
   },
   "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.11",
     "@jxsuite/formulas": "^0.0.18",
     "@jxsuite/markup": "^0.4.10",
-    "@jxsuite/protocol": "^2.3.0",
+    "@jxsuite/protocol": "^2.3.1",
     "@jxsuite/runtime": "^4.0.1",
     "@jxsuite/schema": "^2.2.0",
     "@jxsuite/site": "^2.0.1",
-    "@jxsuite/ui": "^0.2.0",
-    "@vue/reactivity": "3.5.42",
+    "@jxsuite/ui": "^0.3.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": {
     "@happy-dom/global-registrator": "^20.14.5",
     "@types/mdast": "^4.0.4",
-    "@webref/css": "^8.7.4",
-    "@webref/elements": "^2.8.0",
-    "@webref/idl": "^3.83.1"
+    "@webref/css": "^8.7.5",
+    "@webref/elements": "^2.9.0",
+    "@webref/idl": "^3.84.0"
   },
   "//vue-reactivity": "Exact pin required — must match @jxsuite/runtime to avoid cross-boundary proxy bugs"
 }

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,
@@ -405,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 }),
     });
@@ -1525,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;
   }
@@ -2238,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);
@@ -2293,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;
     }
@@ -2308,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,
@@ -2395,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

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;
+}

package/src/grid/grid-open.ts

@@ -30,11 +30,25 @@ import type { AnyCommand, CommandRegistry } from "../commands/registry";
 /** Placeholder document for grid tabs — the grid never reads it; save routes to the controller. */
 const GRID_STUB_DOCUMENT = { children: [], tagName: "div" };
 
-/** Open (or activate) a `.csv` file as a grid tab. */
-export async function openCsvGridTab(path: string): Promise<Tab> {
+/**
+ * Open (or activate) a `.csv` file as a grid tab.
+ *
+ * The options are `openFileInTab`'s own, passed straight through: `paneId` says which pane the tab
+ * lands in (defaulting to the focused one), `focus: false` browses without moving the keyboard, and
+ * `preview` opens a disposable tab. An existing tab is activated with the caller's `focus` — the
+ * same rule the document path follows.
+ *
+ * @param {string} path - Project-relative path of the `.csv`
+ * @param {{ paneId?: string; focus?: boolean; preview?: boolean }} [opts]
+ * @returns {Promise<Tab>}
+ */
+export async function openCsvGridTab(
+  path: string,
+  opts: { paneId?: string; focus?: boolean; preview?: boolean } = {},
+): Promise<Tab> {
   const existing = workspace.tabs.get(path);
   if (existing) {
-    activateTab(path);
+    activateTab(path, { focus: opts.focus !== false });
     return existing;
   }
 
@@ -52,6 +66,9 @@ export async function openCsvGridTab(path: string): Promise<Tab> {
     documentPath: path,
     id: path,
     sourceFormat: formatForPath(path)?.name ?? null,
+    ...(opts.paneId !== undefined && { paneId: opts.paneId }),
+    ...(opts.preview === true && { preview: true }),
+    ...(opts.focus === false && { focus: false }),
   });
   const controller = createGridController(tab, source);
   void controller.load();

package/src/grid/grid-panel.ts

@@ -39,7 +39,7 @@ import { rectOf } from "../utils/geometry";
 import { activeTab, workspace } from "../workspace/workspace";
 import { createGridController, getGridController } from "./grid-controller";
 import { createCsvFileSource } from "./sources/csv-file-source";
-import { createGridView } from "./grid-view";
+import { loadedGridEngine, loadGridEngine } from "./grid-lazy";
 import { parseGridTabId } from "./grid-source";
 import { mountGridPanelSurface } from "../surfaces/grid-panel";
 import { openGridViewsSurface } from "../surfaces/grid-views";
@@ -473,12 +473,45 @@ export function renderGridMode(surface: CanvasSurface, tab: Tab) {
   const engine = controller;
   let hostEl: HTMLElement | null = null;
 
+  /**
+   * (Re)build the Tabulator engine over `host`, destroying whatever view is live first.
+   *
+   * Synchronous when `tabulator-tables` is already loaded — true for every mount after the
+   * session's first, so every existing caller keeps seeing `panel.view` set before this returns. On
+   * a cold first load it goes through `loadGridEngine()` instead (see `grid-lazy.ts`) and `onReady`
+   * — and, symmetrically with the `ready` handling below, `panel.bump()` — run once the import
+   * resolves, guarded against the pane having moved on in the meantime.
+   */
+  function rebuildView(onReady?: (view: GridView) => void) {
+    panel.view?.destroy();
+    panel.view = null;
+    if (!hostEl) {
+      return;
+    }
+    const requestedHost = hostEl;
+    const loaded = loadedGridEngine();
+    if (loaded) {
+      const view = loaded.createGridView(requestedHost, engine);
+      panel.view = view;
+      onReady?.(view);
+      return;
+    }
+    void loadGridEngine().then(({ createGridView }) => {
+      if (activeIn(paneId) !== panel || hostEl !== requestedHost || panel.view) {
+        return;
+      }
+      const view = createGridView(requestedHost, engine);
+      panel.view = view;
+      onReady?.(view);
+      panel.bump();
+    });
+  }
+
   const panel: ActiveGridPanel = {
     applyLayout(layout) {
       void engine.setSort(layout?.sort ?? null);
       engine.setGrouping(layout?.groupBy ?? null);
-      panel.remount();
-      panel.view?.setSearch(layout?.filter ?? "");
+      rebuildView((view) => view.setSearch(layout?.filter ?? ""));
       panel.bump();
     },
     bump() {
@@ -486,8 +519,7 @@ export function renderGridMode(surface: CanvasSurface, tab: Tab) {
     },
     paneId,
     remount() {
-      panel.view?.destroy();
-      panel.view = hostEl ? createGridView(hostEl, engine) : null;
+      rebuildView();
     },
     replace: null,
     scope,
@@ -576,14 +608,16 @@ export function renderGridMode(surface: CanvasSurface, tab: Tab) {
 
       // Create the engine once the columns exist and the host div is in the DOM.
       if (!panel.view && !engine.state.loading && engine.state.columns.length > 0 && hostEl) {
-        panel.view = createGridView(hostEl, engine);
-        if (!restored) {
+        rebuildView((view) => {
+          if (restored) {
+            return;
+          }
           restored = true;
           const layout = loadGridLayout(engine.source.id);
           void engine.setSort(layout?.sort ?? null);
           engine.setGrouping(layout?.groupBy ?? null);
-          panel.view.setSearch(layout?.filter ?? "");
-        }
+          view.setSearch(layout?.filter ?? "");
+        });
       }
     });
   });

package/src/media/media-open.ts

@@ -39,13 +39,22 @@ export function mediaTabModes(path: string): string[] {
 /**
  * Open (or activate) a media file's viewer tab.
  *
+ * The options are `openFileInTab`'s own, passed straight through: `paneId` says which pane the tab
+ * lands in (defaulting to the focused one), `focus: false` browses without moving the keyboard, and
+ * `preview` opens a disposable tab. An existing tab is activated with the caller's `focus` — the
+ * same rule the document path follows.
+ *
  * @param {string} path - Project-relative path of the file
+ * @param {{ paneId?: string; focus?: boolean; preview?: boolean }} [opts]
  * @returns {Tab}
  */
-export function openMediaTab(path: string): Tab {
+export function openMediaTab(
+  path: string,
+  opts: { paneId?: string; focus?: boolean; preview?: boolean } = {},
+): Tab {
   const existing = workspace.tabs.get(path);
   if (existing) {
-    activateTab(path);
+    activateTab(path, { focus: opts.focus !== false });
     return existing;
   }
   return openTab({
@@ -54,5 +63,8 @@ export function openMediaTab(path: string): Tab {
     documentPath: path,
     id: path,
     sourceFormat: null,
+    ...(opts.paneId !== undefined && { paneId: opts.paneId }),
+    ...(opts.preview === true && { preview: true }),
+    ...(opts.focus === false && { focus: false }),
   });
 }

package/src/panels/chat-panel.ts

@@ -12,10 +12,19 @@
  * in `ui/regions.ts`'s shell table — the assistant no longer has a shell host to name. Three
  * screenshot shots address that id and none of them changed.
  *
- * Hosts the assistant UI from ai-panel.ts unconditionally: with no project (welcome screen), with a
- * project but no open document, and with a document open. The panel is mounted once at studio boot
- * and never tears down on tab switches — the assistant's module state and DOM (composer draft,
- * scroll position) persist.
+ * Hosts the assistant machinery from ai-panel.ts unconditionally: with no project (welcome screen),
+ * with a project but no open document, and with a document open. The machinery is mounted once at
+ * studio boot and never tears down on tab switches — the assistant's module state (composer draft,
+ * scroll position, transcript) persists.
+ *
+ * **The assistant's SURFACE document is what this module defers.** Mounting `surfaces/ai-chat.ts`
+ * costs a traced 100–290 ms of connectedCallback at boot (its island projections; see
+ * `scripts/perf/REPORT.md`), paid on every window open although the document is invisible until
+ * the tab is picked. Binding is the same seam (`bindAiPanelHost`) and it is now deferred to the
+ * first time the Assistant tab is actually shown or revealed: `renderAiPanel` no-ops while the
+ * surface is null, and the surface's own watcher projects whatever the machinery wrote before that
+ * point, so a prompt seeded into a boot the reader never spends in the tab is not lost — it is one
+ * more message waiting when the body first appears.
  *
  * **This module is the SEAM, and it has no markup of its own.** The assistant is a Jx document
  * (`surfaces/ai-chat.json`), and a document CLEARS the host it is given — so it needs a container
@@ -32,6 +41,7 @@ import { effect, effectScope } from "../reactivity";
 import { workspace } from "../workspace/workspace";
 import { consumePendingAgentPrompt, hasPendingAgentPrompt } from "../services/agent-seed";
 import { REGION_ATTR } from "../ui/regions";
+import { inspectorTab } from "./right-panel";
 import {
   bindAiPanelHost,
   mountAiPanel,
@@ -48,6 +58,23 @@ const ASSISTANT_REGION = "inspector.assistant";
 let _host: HTMLElement | null = null;
 let _container: HTMLElement | null = null;
 let _scope: EffectScope | null = null;
+/** Whether the surface document has been bound. One bind per host; a remount resets it. */
+let _surfaceBound = false;
+
+/**
+ * Bind the assistant's surface document the first time its tab is shown or revealed.
+ *
+ * The container, the region attribute and every prompt path are ready before this; the surface is
+ * the expensive part and is invisible until the tab is picked, so this is the earliest moment its
+ * cost is worth paying. A restore that lands on the Assistant tab binds on the same tick.
+ */
+function ensureAssistantSurface(): void {
+  if (_surfaceBound || !_container) {
+    return;
+  }
+  _surfaceBound = true;
+  bindAiPanelHost(_container);
+}
 
 /**
  * Mount the assistant into the host the Inspector hands it. Idempotent per host: the persistent
@@ -68,11 +95,18 @@ export function mount(host: HTMLElement | null) {
   host.append(_container);
 
   mountAiPanel();
-  bindAiPanelHost(_container);
+  _surfaceBound = false;
 
   _scope?.stop();
   _scope = effectScope();
   _scope.run(() => {
+    effect(() => {
+      // The surface's bind follows the TAB: a session restored onto the Assistant is bound by
+      // One re-run of this effect, not by anyone remembering to call the seam directly.
+      if (inspectorTab() === "assistant") {
+        ensureAssistantSurface();
+      }
+    });
     effect(() => {
       // A pending agent prompt (stored by the New Project flow, possibly from another window) is
       // Keyed by the absolute project root — consume it as soon as this window adopts that root.
@@ -98,6 +132,7 @@ export function mount(host: HTMLElement | null) {
 export function unmount() {
   _scope?.stop();
   _scope = null;
+  _surfaceBound = false;
   // `null` unbinds the surface: the document is disposed and the chat-state watcher stopped.
   bindAiPanelHost(null);
   if (_host) {

package/src/panels/pane-context.ts

@@ -500,10 +500,11 @@ export interface PresetRow {
    *
    * The previous round made the row's ANSWER a pure function of the pane and left its ACTION
    * resolving the focus: every one of these three commands takes the focused pane as its subject
-   * (`pane.derive`'s `activePane()`/`sidePane()`, `pane.unsplit`'s `workspace.activePaneId`), so a
-   * row read off the secondary pane's menu derived from the primary. Reachable by keyboard and only
-   * by keyboard, which is why it survived a browser pass: `panels/pane-grid.ts` focuses a pane on
-   * POINTERDOWN, and a keyboard activation of a menu item fires `click` alone.
+   * (`pane.derive`'s `activePane()`/`paneBeside(source.id)`, `pane.unsplit`'s
+   * `workspace.activePaneId`), so a row read off the secondary pane's menu derived from the
+   * primary. Reachable by keyboard and only by keyboard, which is why it survived a browser pass:
+   * `panels/pane-grid.ts` focuses a pane on POINTERDOWN, and a keyboard activation of a menu item
+   * fires `click` alone.
    *
    * Carried on the row rather than passed as a command argument. A pane id in `args` would make
    * "which pane" a public input of `pane.derive` — a third property on a record the palette already