@jxsuite/studio 4.1.0 → 5.0.0

package/src/canvas/popover-state.ts

@@ -0,0 +1,155 @@
+/// <reference lib="dom" />
+/**
+ * Which popover the canvas draws open, and the one rule that decides it from a selection.
+ *
+ * **Open on selection is one rule, not one per surface.** There is no single WRITER of
+ * `session.selection` — the Outline writes it, the canvas writes it, `transact.ts` writes it after
+ * a structural edit, quick search and problem-jump write it. There IS a single OBSERVER: the
+ * reactive effect the canvas host already runs over every shown pane's selection. So the rule lives
+ * beside that, in an effect of its own, and every door into a popover opens it: clicking the panel,
+ * clicking a row in the Outline, jumping to a Problem inside it, or arriving there through undo.
+ *
+ * The rule is deliberately **asymmetric**: selecting at or inside a popover opens it, and selecting
+ * outside every popover does NOT close the open one. Closing on any stray selection would make a
+ * popover impossible to style — you could not reach a colour swatch in the Inspector without the
+ * panel slamming shut under you. Closing is explicit: the action-bar control, or selecting into a
+ * different popover.
+ *
+ * A separate effect from the host's selection watch rather than a line inside it, because that one
+ * READS the selection and this one WRITES `ui.openPopover`; folding them together would write to a
+ * value inside the effect that tracks it.
+ *
+ * The path arithmetic lives in `popover-path.ts` — see its header for why the split exists.
+ *
+ * @docs studio/interface/canvas
+ */
+
+import { activeTab } from "../workspace/workspace";
+import { ancestorPopoverPath } from "./popover-path";
+import { openDialogFor, reconcileOpenDialog } from "./dialog-state";
+import { effect, pauseTracking, resetTracking } from "../reactivity";
+import { postPopoverOpen, revealCanvasPath } from "./iframe-host";
+import { primarySelection } from "../tabs/selection";
+import { updateSession } from "../store";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JxPath } from "../state";
+import type { Tab } from "../tabs/tab";
+
+/** Whether two paths address the same node. */
+function samePath(a: JxPath | null, b: JxPath | null): boolean {
+  if (a === null || b === null) {
+    return a === b;
+  }
+  return a.length === b.length && a.every((seg, i) => seg === b[i]);
+}
+
+/**
+ * Write `ui.openPopover` and tell every frame showing this tab.
+ *
+ * The single writer. `canvas.setPopoverOpen`, the reveal rule and the trigger click in the canvas
+ * all land here, so the model and the frames cannot disagree about which panel is open.
+ *
+ * @param tab The tab whose canvas is affected.
+ * @param path The popover's path, or null to close whatever is open.
+ */
+export function setOpenPopover(tab: Tab, path: JxPath | null): void {
+  updateSession(tab, { ui: { openPopover: path } });
+  postPopoverOpen(tab, path);
+}
+
+/** Open the popover containing `path`, if any. Returns whether anything changed. */
+function openPopoverFor(tab: Tab, path: JxPath | null): boolean {
+  const target = ancestorPopoverPath(tab.doc.document as JxMutableNode, path);
+  if (target === null || samePath(tab.session.ui.openPopover, target)) {
+    return false;
+  }
+  setOpenPopover(tab, target);
+  return true;
+}
+
+/**
+ * Reconcile one tab's open popover with its current selection.
+ *
+ * Only ever OPENS — see the asymmetry argued in this file's header.
+ *
+ * @param tab The tab to reconcile, or null/undefined for none.
+ */
+export function reconcileOpenPopover(tab: Tab | null | undefined): void {
+  if (tab) {
+    openPopoverFor(tab, primarySelection(tab.session.selection));
+  }
+}
+
+/**
+ * Bring `path` into view in the canvas, opening the popover it is inside first.
+ *
+ * The open message and the subsequent measure travel the same FIFO channel, and
+ * `getBoundingClientRect` forces layout synchronously — so the measure inside `revealCanvasPath`
+ * already sees the panel laid out. No acknowledgement, no await, no timer.
+ *
+ * This replaced `panToElement`, which resolved paths by walking the PARENT realm's DOM. The canvas
+ * element's children have been `[iframe, overlay]` since the canvas became a cross-origin frame, so
+ * that walk returned null for every non-root path: clicking an Outline row had never scrolled the
+ * canvas at all.
+ *
+ * @param path The document path to reveal.
+ */
+export function revealPathInCanvas(path: JxPath): void {
+  const tab = activeTab.value;
+  if (tab) {
+    openPopoverFor(tab, path);
+    openDialogFor(tab, path);
+  }
+  void revealCanvasPath(path);
+}
+
+/** The live reveal watch, or null when none is running. Module-local so a second start is a no-op. */
+let watching: { stop: () => void } | null = null;
+
+/**
+ * Start the reveal watch. Idempotent, like the host's own watches.
+ *
+ * @returns A stop function, for teardown and for tests.
+ */
+export function ensurePopoverRevealWatch(): () => void {
+  if (!watching) {
+    const runner = effect(() => {
+      const tab = activeTab.value;
+      /* TRACKED: the selection, and the document its paths resolve against. Those are what the
+         rule depends on, and a selection move is the only thing that should fire it. The whole
+         SET is read joined, for the reason §6.5 gives: a bare property read would not re-trigger
+         when the selection changes within the array. */
+      void tab?.session.selection.map((path) => path.join("/")).join("|");
+      void tab?.doc.document;
+      /* UNTRACKED: everything that reads or writes `ui.openPopover` and `ui.openDialog`.
+         `openPopoverFor` compares its target against the open path, and reading that inside the
+         tracked scope made this effect depend on the value it writes: closing a panel re-ran the
+         rule, which found the selection still inside the panel and opened it straight back. A
+         Close button INSIDE a dialog is the ordinary shape of one, so that dialog could not be
+         closed at all, and the action-bar control could not close a popover the reader had
+         selected into — both of which studio.md §4.2.2 and §4.2.3 say are the explicit way to
+         close. The file header already warned about writing a value inside the effect that
+         tracks it; the warning was applied to the host's selection watch and not to this. */
+      pauseTracking();
+      try {
+        reconcileOpenPopover(tab);
+        // The dialog rule rides the same effect: one observer of the selection, two overlay kinds.
+        reconcileOpenDialog(tab);
+      } finally {
+        resetTracking();
+      }
+    });
+    watching = {
+      stop: () => {
+        runner.effect.stop();
+      },
+    };
+  }
+  const held = watching;
+  return () => {
+    held.stop();
+    if (watching === held) {
+      watching = null;
+    }
+  };
+}

package/src/canvas/surface-registry.ts

@@ -25,16 +25,8 @@
  */
 
 import type { CanvasPanel } from "../types";
-import type { MonacoSurface } from "../view";
-
-/**
- * The class name every pane's stage element carries.
- *
- * Declared here rather than in the grid because it is what the two genuinely document-level
- * gestures test with `closest()` — "is this event over SOME stage" is a question about surfaces,
- * not about the reconciler that happens to build them.
- */
-export const STAGE_CLASS = "pane-stage";
+import type { CanvasStageHandle } from "../surfaces/canvas-stage";
+import type { DiffSurface, MonacoSurface } from "../view";
 
 /** One pane's stage: where it renders, what it mounted there, and what it last drew. */
 export interface CanvasSurface {
@@ -64,6 +56,15 @@ export interface CanvasSurface {
    * last, so a fit computed for one pane wrote a transform onto the other's artboards.
    */
   panzoomWrap: HTMLElement | null;
+  /**
+   * The mounted stage document drawing this pane's artboards, or null in the modes that own the
+   * stage themselves (grid, library, entry, media, settings) and before the first pass.
+   *
+   * Per-surface for the reason every field here is, and it OUTLIVES a repaint: every artboard holds
+   * a live iframe, so keeping the mount across a content-only render is the difference between a
+   * repaint and a reload. `canvas/canvas-render.ts` ends it on a real mode transition.
+   */
+  stage: CanvasStageHandle | null;
   /** The observer that re-centres this stage until the author pans it. One per stage. */
   centerObserver: ResizeObserver | null;
   /** Whether this stage still wants re-centring — cleared by the first deliberate pan. */
@@ -72,6 +73,14 @@ export interface CanvasSurface {
   panY: number;
   /** The source view's Monaco, mounted into THIS stage. Two Code panes are two models. */
   monacoEditor: MonacoSurface | null;
+  /**
+   * The Code view of a comparison, mounted into THIS stage.
+   *
+   * Its own slot rather than a widening of {@link monacoEditor}, for the reason {@link DiffSurface}
+   * gives: it is a different Monaco type with no buffer to commit, and sharing the slot would put
+   * it in front of every code-editor API that reads from there.
+   */
+  monacoDiffEditor: DiffSurface | null;
   /**
    * The Stylebook filter and Customized flag THIS stage's catalogue was last built for.
    *
@@ -141,6 +150,7 @@ export function surfaceForPane(paneId: string): CanvasSurface {
 function freshSurface(paneId: string): CanvasSurface {
   return {
     centerObserver: null,
+    monacoDiffEditor: null,
     monacoEditor: null,
     needsCenter: true,
     panX: 0,
@@ -148,6 +158,7 @@ function freshSurface(paneId: string): CanvasSurface {
     panels: [],
     paneId,
     panzoomWrap: null,
+    stage: null,
     prevCanvasMode: null,
     prevStylebookCustomizedOnly: null,
     prevStylebookFilter: null,

package/src/collab/presence-chips.ts

@@ -2,8 +2,8 @@
  * Presence chips — who else is in this co-editing session, the sync-status pill that replaces the
  * dirty dot for collab tabs, and the two states co-editing had no way to announce (§7.4).
  *
- * Pure lit templates over `collabState(tab)`; the toolbar includes them and its render effect
- * tracks the underlying reactive state.
+ * Pure projections of `collabState(tab)`: the Command Bar surface draws the cluster and the pane's
+ * own chrome draws the banner, and both are documents, so nothing here renders.
  *
  * **What was invisible.** Three things:
  *
@@ -12,7 +12,10 @@
  *   precisely what a bug looks like. It gets a persistent indicator, so the refusal has a visible
  *   cause standing beside it for as long as it is true.
  * - **Read-only guests.** Their edits applied locally and were dropped at the publish gate. They now
- *   get a banner that says so before they type, not a silence after.
+ *   get a banner that says so before they type, not a silence after. The banner itself lives in
+ *   `surfaces/pane-context.json`, drawn from `collabState(tab)` by the pane's own chrome: the
+ *   sentence has to stand above the editing surface and inside the band the stage is offset by, and
+ *   that band is a document now. What stays here is everything the TOOLBAR draws.
  * - **A failed attach.** It set `status = "detached"` — the same value a solo document carries — so a
  *   dead relay was indistinguishable from nobody having shared the file. `"failed"` and
  *   `"unavailable"` are now separate states with separate sentences.
@@ -23,8 +26,6 @@
  * precisely because silently undoing someone else's work is worse than not undoing.
  */
 
-import { html, nothing } from "lit-html";
-import type { TemplateResult } from "lit-html";
 import { collabState } from "./collab-state";
 import type { CollabTabStatus, PeerPresence } from "./collab-state";
 import type { Tab } from "../tabs/tab";
@@ -71,81 +72,58 @@ export function statusTitle(status: CollabTabStatus, attachError: string): strin
   return STATUS_LABEL[status];
 }
 
-/** Chips + status pill for the toolbar; `nothing` while the tab has no collaboration to report. */
-export function presenceChipsTemplate(tab: Tab | null): TemplateResult | typeof nothing {
-  if (!tab) {
-    return nothing;
-  }
-  const state = collabState(tab);
-  /* "unavailable" is the only silent state: this build has no collaboration, so there is nothing to
-     be honest ABOUT. Every other state — including solo and failed — says which one it is. */
-  if (state.status === "unavailable") {
-    return nothing;
-  }
-  const label = STATUS_LABEL[state.status] || state.status;
-  return html`
-    <div class="jx-presence" title=${statusTitle(state.status, state.attachError)}>
-      <span class="jx-presence-status" data-status=${state.status}>${label}</span>
-      ${
-        state.readOnly
-          ? html`<span
-              class="jx-presence-flag"
-              data-flag="read-only"
-              title="You have read access to this session. Your edits show here but are not published to the others."
-              >Read-only</span
-            >`
-          : nothing
-      }
-      ${
-        state.sourceCanonical
-          ? html`<span
-              class="jx-presence-flag"
-              data-flag="frozen"
-              title="Someone is editing the code view. Structural edits are paused until they stop — this is not an error."
-              >Code view held</span
-            >`
-          : nothing
-      }
-      ${state.peers.map(
-        (peer) => html`
-          <span
-            class="jx-presence-chip"
-            style="background:${peer.state.user.color}"
-            title=${titleOf(peer, tab.documentPath)}
-            >${
-              peer.state.user.avatarUrl
-                ? html`<img src=${peer.state.user.avatarUrl} alt=${initialOf(peer)} />`
-                : initialOf(peer)
-            }</span
-          >
-        `,
-      )}
-    </div>
-  `;
+/** One peer, as the Command Bar draws it: a coloured chip with the person's initial or avatar. */
+export interface PresencePeerProjection {
+  /** The awareness client id, the row key. */
+  key: number;
+  color: string;
+  /** Who, and where they are when it is not this document. */
+  title: string;
+  initial: string;
+  avatarUrl: string;
+  hasAvatar: boolean;
+}
+
+/** The presence cluster, projected for the `commandbar` surface. */
+export interface PresenceProjection {
+  status: CollabTabStatus;
+  /** The status word: Live, Solo, Offline… */
+  label: string;
+  /** The sentence behind the cluster, from {@link statusTitle}. */
+  title: string;
+  readOnly: boolean;
+  /** Someone holds the code view, so structural edits are paused. */
+  frozen: boolean;
+  peers: PresencePeerProjection[];
 }
 
 /**
- * The read-only banner — a standing statement, not an after-the-fact refusal.
+ * The presence cluster for a tab, or null when there is nothing to say.
  *
- * A guest without write access used to watch their edits apply locally and be dropped silently at
- * the publish gate, which reads as the app losing work. The sentence has to be there before the
- * first keystroke, so it is rendered by the PANE CHROME (`panels/pane-context.ts`) rather than by
- * the toolbar the chips ride in: the chrome is per-pane and per-document, it sits directly above
- * the editing surface, and the stage is offset by the band it lives in — so the banner pushes the
- * document down instead of covering it.
+ * "unavailable" is the only silent state: this build has no collaboration, so there is nothing to
+ * be honest ABOUT. Every other state — including solo and failed — says which one it is.
  */
-export function readOnlyBannerTemplate(tab: Tab | null): TemplateResult | typeof nothing {
+export function presenceProjection(tab: Tab | null): PresenceProjection | null {
   if (!tab) {
-    return nothing;
+    return null;
   }
   const state = collabState(tab);
-  if (!state.active || !state.readOnly) {
-    return nothing;
+  if (state.status === "unavailable") {
+    return null;
   }
-  return html`
-    <div class="jx-collab-banner" role="status" data-kind="read-only">
-      You have read access to this session. You can explore and edit locally, but your changes are
-      not published to the other people in it.
-    </div>
-  `;
+  return {
+    frozen: state.sourceCanonical,
+    label: STATUS_LABEL[state.status] || state.status,
+    peers: state.peers.map((peer) => ({
+      avatarUrl: peer.state.user.avatarUrl ?? "",
+      color: peer.state.user.color,
+      hasAvatar: Boolean(peer.state.user.avatarUrl),
+      initial: initialOf(peer),
+      key: peer.clientId,
+      title: titleOf(peer, tab.documentPath),
+    })),
+    readOnly: state.readOnly,
+    status: state.status,
+    title: statusTitle(state.status, state.attachError),
+  };
 }

package/src/commands/app-commands.ts

@@ -36,16 +36,19 @@ import { createCommandRegistry } from "./registry";
 import { emptyContext } from "./context";
 import { DEFAULT_INSPECTOR_TAB, shellViewCommands } from "../shell";
 import { canvasViewCommands } from "../canvas/canvas-utils";
+import { diffCommands } from "../canvas/diff-toolbar";
 import { selectionCommands } from "../canvas/canvas-render";
 import { inspectorCommands } from "../panels/properties-panel";
 import { dataExplorerCommands } from "../panels/data-explorer";
 import { seoCommands } from "../panels/seo-modal";
 import { a11yCommands } from "../services/a11y-report";
+import { popoverCommands } from "../services/popover-report";
 import { liveElementCommands } from "../editor/context-menu";
 import { signalsCommands } from "../panels/signals-panel";
 import { formulaEditorCommands } from "../panels/formula-workspace";
 import { styleCommands } from "../panels/style-panel";
 import { gridCommands } from "../grid/grid-open";
+import { extensionCommands } from "../settings/extension-commands";
 import { settingsCommands } from "../settings/settings-document";
 import { collabCommands } from "../collab/collab-commands";
 import { assistantCommands } from "../panels/ai-panel";
@@ -119,12 +122,16 @@ export function appCommandSet(): AnyCommand[] {
       getCanvasMode: () => "design",
       renderPane: NO_OP,
       setCanvasMode: NO_OP,
+      setOpenPopover: NO_OP,
+      setOpenDialog: NO_OP,
       setResolvingOpen: NO_OP,
     }),
+    ...diffCommands(),
     ...selectionCommands(),
     ...inspectorCommands(),
     ...seoCommands(),
     ...a11yCommands(),
+    ...popoverCommands(),
     // The element menu's eight verbs. Every one declares `menus: ["context/element", "palette"]`
     // And none reached the palette, because they were registered ONLY into the private registry
     // `editor/context-menu.ts` builds for its popover — a registry whose own docstring said it
@@ -136,6 +143,9 @@ export function appCommandSet(): AnyCommand[] {
     ...formulaEditorCommands(),
     ...gridCommands(),
     ...settingsCommands(),
+    // The three verbs over project.json `extensions[]` — palette-only, and projected here so the
+    // Level check, the chrome budget and the generated keyboard sheet all see them.
+    ...extensionCommands(),
     ...collabCommands(),
     ...assistantCommands(),
     ...preferencesCommands(),

package/src/commands/budget.ts

@@ -40,6 +40,18 @@ export const CHROME_BUDGET = {
    * verb is a design decision that has to be made here rather than by appending to a data file.
    */
   blockbarFormat: 8,
+  /**
+   * Tools the assistant may be advertised in its richest state — the hand-registered rows of
+   * `AI_TOOL_TIERS` plus every command record that declares `aiTool`.
+   *
+   * A prompt is chrome for a model: every tool costs attention, and issue 273's finding was that a
+   * naive projection of every declaration would have taken the list from 22 to 67. Thirty is
+   * headroom over today's 28 (19 hand + 9 projected), not a target. Asserted in
+   * `tests/ai-command-tools.test.ts` rather than `scripts/check-chrome-budget.ts`, because the hand
+   * table lives in `ai-system-prompt.ts`, which imports `../store.js` and is not bare-Bun loadable;
+   * the number lives here either way, and raising it is a design decision.
+   */
+  assistantTools: 30,
 } as const;
 
 /** One tabbed region and what it currently hosts. */