@jxsuite/studio 6.1.1 → 8.0.0

package/src/panels/block-action-bar.ts

@@ -34,7 +34,7 @@
  * @docs studio/interface/canvas
  */
 
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isMappedArray, isNonNullObject, isNumber } from "@jxsuite/schema/guards";
 import { focusItem } from "@jxsuite/ui/behaviors/action-group";
 import { draggable } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
 import { disableNativeDragPreview } from "@atlaskit/pragmatic-drag-and-drop/element/disable-native-drag-preview";
@@ -49,6 +49,7 @@ import {
 } from "../store";
 import { activeTab } from "../workspace/workspace";
 import { activeCanvasSurface, stageContaining } from "../canvas/canvas-surface";
+import { stageOf } from "../canvas/surface-registry";
 import { panelOfSurface } from "../canvas/canvas-helpers";
 import { primarySelection, structuralBatch } from "../tabs/selection";
 import {
@@ -229,13 +230,13 @@ function barPosition(anchor: {
      "the stage showing the active tab", which was the same answer only while a tab could be on
      screen in one place; with a document displayed in two panes it picked whichever came first in
      the grid, and clipped the bar against a stage the author is not typing in.
-     …and against the box that SCROLLS, where the stage has one. Edit docks the Document Header
-     card above its scroller, inside the same stage cell, so a node scrolled up under the band is
-     still inside the stage while nobody can see it — and the bar would float over the card,
-     pointing at a node the card is covering. Everywhere else there is no scroller and the stage is
-     the viewport, as it always was. */
+     …and against the box that SCROLLS, where the stage has one: Edit's page scroller. Over a
+     collection entry the writing banner stands above it in the same stage cell, so a node
+     scrolled up under the banner is still inside the stage while nobody can see it — and the bar
+     would float over the banner, pointing at a node it covers. Everywhere else there is no
+     scroller and the stage is the viewport, as it always was. */
   const surface = activeCanvasSurface();
-  const viewport = panelOfSurface(surface)?.scrollContainer ?? surface.wrap;
+  const viewport = panelOfSurface(surface)?.scrollContainer ?? stageOf(surface);
   const box = viewport ? rectOf(viewport) : null;
   if (box && (anchor.top + anchor.height < box.top || anchor.top > box.bottom)) {
     return null;
@@ -243,9 +244,9 @@ function barPosition(anchor: {
   /* ABOVE the anchor where the bar fits above it INSIDE that viewport, and BELOW it where it does
      not. The flip used to be decided against a flat 80 in WINDOW coordinates, the app's own top
      chrome, which is the same answer only while the viewport starts near the top of the window.
-     Edit's scroller starts under a band, so an anchor whose top had scrolled under the card while
-     its bottom was still on screen put the bar ON the card — over the fields it covers, taking
-     their clicks. Flipped is better than hidden: the element is visible, so its bar should be, and
+     Edit's scroller can start under the writing banner, so an anchor whose top had scrolled under
+     it while its bottom was still on screen put the bar ON the banner, taking its clicks. Flipped
+     is better than hidden: the element is visible, so its bar should be, and
      past the clip above the anchor's bottom edge is inside the viewport, so the flipped bar is too.
      The fallback is that same 80px of chrome, for a stage no pass has measured yet. */
   const ceiling = box ? box.top : 80 - BAR_CLEARANCE;
@@ -256,7 +257,7 @@ function barPosition(anchor: {
   /* Below it, and kept INSIDE the viewport: an element taller than what is left of the scroller has
      its bottom edge off screen, and the bar would follow it there — over the status bar, or over
      whatever the pane below is showing. Clamped, it stands on that element's last visible strip,
-     still pointing at it and still off the card. */
+     still pointing at it and still inside the scroller. */
   const below = anchor.top + anchor.height + 4;
   return {
     left: anchor.left,
@@ -324,23 +325,28 @@ export function formatCommands(): AnyCommand[] {
     title: string,
     icon: string,
     keybinding?: string,
-  ): AnyCommand => ({
-    category: "Edit",
-    group: "6_format",
-    icon,
-    id: `format.${command}`,
-    ...(keybinding === undefined ? {} : { keybinding }),
-    keyScope: "caret",
-    level: "selection",
-    menus: ["blockbar/format", "palette"],
-    requires: "a text caret in the canvas",
-    run: () => {
-      postApplyFormat({ command });
-    },
-    title,
-    undo: "document",
-    when: (ctx: CommandContext) => ctx.caret.inCanvas,
-  });
+  ): AnyCommand => {
+    const entry: AnyCommand = {
+      category: "Edit",
+      group: "6_format",
+      icon,
+      id: `format.${command}`,
+      keyScope: "caret",
+      level: "selection",
+      menus: ["blockbar/format", "palette"],
+      requires: "a text caret in the canvas",
+      run: () => {
+        postApplyFormat({ command });
+      },
+      title,
+      undo: "document",
+      when: (ctx: CommandContext) => ctx.caret.inCanvas,
+    };
+    if (keybinding !== undefined) {
+      entry.keybinding = keybinding;
+    }
+    return entry;
+  };
 
   return [
     record("bold", "Bold", "text-b", "mod+b"),
@@ -493,7 +499,7 @@ function structuralTarget(path: JxPath | null = commandTargetPath()): Structural
   }
   const index = childIndex(path);
   const parentPath = parentElementPath(path);
-  if (typeof index !== "number" || !parentPath) {
+  if (!isNumber(index) || !parentPath) {
     return null;
   }
   const parentNode = getNodeAtPath(tab.doc.document, parentPath);
@@ -510,7 +516,7 @@ function structuralTarget(path: JxPath | null = commandTargetPath()): Structural
  * block, not a container, and nesting a block inside it produces invalid markup.
  */
 function isContainerNode(node: JxMutableNode | string | null | undefined): boolean {
-  if (!node || typeof node !== "object") {
+  if (!isNonNullObject(node)) {
     return false;
   }
   if (VOID_ELEMENTS.has((displayTagName(node.tagName) || "div").toLowerCase())) {
@@ -521,11 +527,10 @@ function isContainerNode(node: JxMutableNode | string | null | undefined): boole
     return false;
   }
   if (!Array.isArray(children)) {
-    return (children as unknown as Record<string, unknown>).$prototype === "Array";
+    return isMappedArray(children);
   }
   return (
-    children.length === 0 ||
-    children.some((c) => typeof c === "object" && c !== null && !isInlineElement(c, node))
+    children.length === 0 || children.some((c) => isNonNullObject(c) && !isInlineElement(c, node))
   );
 }
 
@@ -549,7 +554,7 @@ function canMoveOut(): boolean {
   return (
     target !== null &&
     parentElementPath(target.parentPath) !== null &&
-    typeof childIndex(target.parentPath) === "number"
+    isNumber(childIndex(target.parentPath))
   );
 }
 
@@ -598,7 +603,7 @@ function moveTargetOut(): void {
   }
   const grandparent = parentElementPath(target.parentPath);
   const parentIndex = childIndex(target.parentPath);
-  if (!grandparent || typeof parentIndex !== "number") {
+  if (!grandparent || !isNumber(parentIndex)) {
     return;
   }
   transactDoc(target.tab, (t) => mutateMoveNode(t, target.path, grandparent, parentIndex + 1));
@@ -1040,7 +1045,7 @@ export function showCommandOverflow(
     commands.map((command, index) => {
       const chord = registry.keymap.formatBinding(command.id);
       const reason = registry.disabledReason(command.id);
-      return {
+      const row: MenuRowProjection = {
         destructive: command.destructive === true,
         disabled: reason !== undefined,
         dividerAbove: index > 0 && command.destructive === true,
@@ -1049,9 +1054,14 @@ export function showCommandOverflow(
           runCommand(registry, command.id, target);
         },
         title: command.title,
-        ...(chord ? { chord } : {}),
-        ...(reason === undefined ? {} : { requires: reason }),
       };
+      if (chord) {
+        row.chord = chord;
+      }
+      if (reason !== undefined) {
+        row.requires = reason;
+      }
+      return row;
     });
   const rows = target ? withCommandTarget(target, project) : project();
   _overflowHandle = openMenu({
@@ -1079,7 +1089,7 @@ export function showCommandOverflow(
 function returnFocusToCanvas(): void {
   // The FOCUSED pane's stage: the keyboard came from there and is going back there. Resolving it
   // From the active tab answered with whichever pane displays that document first.
-  const stage = activeCanvasSurface().wrap;
+  const stage = stageOf(activeCanvasSurface());
   const iframe = stage?.querySelector<HTMLElement>("iframe.jx-canvas-iframe");
   (iframe ?? stage)?.focus();
 }
@@ -1118,9 +1128,9 @@ export function handleBlockBarEntryKey(e: KeyboardEvent): void {
  * The tags this node may be converted into — empty for a component instance and for a repeater,
  * whose content is a `map` template rather than a tag.
  *
- * @param {JxMutableNode | null} node
+ * @param {JxMutableNode | null | undefined} node
  */
-function convertTargetsFor(node: JxMutableNode | null): SlashCommand[] {
+function convertTargetsFor(node: JxMutableNode | null | undefined): SlashCommand[] {
   if (!node) {
     return [];
   }
@@ -1130,10 +1140,11 @@ function convertTargetsFor(node: JxMutableNode | null): SlashCommand[] {
     return [];
   }
   const children = childList(node);
+  const [first] = children;
   const isEmpty =
     !node.textContent &&
     (children.length === 0 ||
-      (children.length === 1 && typeof children[0] === "object" && children[0]?.tagName === "br"));
+      (children.length === 1 && isNonNullObject(first) && first.tagName === "br"));
   return getConvertTargets((literal || "div").toLowerCase(), isEmpty);
 }
 
@@ -1173,7 +1184,7 @@ function openConvertMenu(anchor: HTMLElement): void {
  */
 function openMergeTagMenu(anchor: HTMLElement): void {
   const tab = activeTab.value;
-  const state = (tab?.doc.document.state ?? {}) as Record<string, unknown>;
+  const state = tab?.doc.document.state ?? {};
   // The live resolved scope lives inside the iframe realm and is not threaded out, so the parent
   // Offers only top-level `state.*` tokens (buildMergeTags tolerates the null scopes).
   const tags = buildMergeTags(state, null, null);
@@ -1186,7 +1197,7 @@ function openMergeTagMenu(anchor: HTMLElement): void {
   if (arrayNode && tab) {
     const tokens = resolveRepeaterItemFields(
       arrayNode,
-      tab.doc.document.state as Record<string, unknown>,
+      tab.doc.document.state,
       projectState?.projectConfig,
     );
     tags.push(...buildRepeaterTagsFromFields(tokens));
@@ -1262,8 +1273,8 @@ function hideBar(): void {
  * The document + selection the bar is currently suppressed FOR, or null while it is free to draw.
  *
  * **Why a key and not a boolean.** The bar is `position: fixed` and clamped into the window, so it
- * can sit over the Document Header card, the pane context bar and the docks; an author working in
- * the Inspector's Logic tab reported it "blocking a part of the interface that the user needs to
+ * can sit over the pane context bar, the Inspector and the docks; an author working in the
+ * Inspector's Logic tab reported it "blocking a part of the interface that the user needs to
  * utilize". Hiding it on a chrome pointerdown is half an answer — {@link dismissBlockActionBar}
  * alone would flash back on the very next repaint, because the bar is re-rendered from the
  * `toolbarRefresh` seam on every selection snapshot and from `renderOnly("overlays")` on zoom/pan.

package/src/panels/bottom-dock.ts

@@ -37,7 +37,7 @@
  * registered from here, like every other tab of this dock.
  */
 
-import { render as litRender, nothing } from "lit-html";
+import { render, nothing } from "lit-html";
 import { effect, effectScope } from "../reactivity";
 import {
   BOTTOM_TAB_IDS,
@@ -141,6 +141,8 @@ export function activeBottomPanel(ctx: CommandContext = panelContext()): PanelRe
  */
 function bottomContext(): NavigatorPanelContext {
   return {
+    /* SAFETY: no Bottom dock panel reads `deps` (see above): Problems and Activity render from their
+       own stores and Logic from `activeTab`, so this empty stand-in is never dereferenced. */
     deps: {} as NavigatorPanelDeps,
     doc: null,
     rerender: renderBottomDock,
@@ -296,7 +298,7 @@ function paintBody(): void {
     return;
   }
   const active = activeBottomPanel();
-  litRender(
+  render(
     active
       ? active.render(bottomContext())
       : emptyState(host, { message: "Nothing to show here yet." }),
@@ -394,7 +396,7 @@ export function unmountBottomDock(): void {
     _host.removeAttribute(REGION_ATTR);
     /* The document's dispose removed its own root; this clears anything a caller left beside it,
        so the host is `:empty` again and the shell's sheet takes the dock out of the grid. */
-    litRender(nothing, _host);
+    render(nothing, _host);
     _host.textContent = "";
     runAfterRender(_host);
     _host = null;

package/src/panels/canvas-dnd-bridge.ts

@@ -25,7 +25,7 @@
  */
 
 import { monitorForElements } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isString } from "@jxsuite/schema/guards";
 import {
   beginDragSession,
   clearDropIndicator,
@@ -42,19 +42,15 @@ import { parentCursorToIframe } from "../canvas/iframe-overlay";
 import { clearDragGhost, moveDragGhost, setDragGhost } from "./drag-ghost";
 import { getNodeAtPath } from "../store";
 import { activeTab } from "../workspace/workspace";
-import type { DragHost } from "../canvas/iframe-host";
+import type { HostState } from "../canvas/iframe-host";
+import type { ElementDragPayload } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
 import type { Tab } from "../tabs/tab";
 import type { DragSrcKind, ParentToIframe } from "../canvas/iframe-protocol";
 import type { JxMutableNode } from "@jxsuite/schema/types";
-
-/** A parent-viewport pointer position (pragmatic's `location.current.input`). */
-interface Cursor {
-  x: number;
-  y: number;
-}
+import type { ViewportPoint } from "../surfaces/menu";
 
 interface MonitorDragArgs {
-  source: { data: Record<string, unknown> };
+  source: { data: ElementDragPayload["data"] };
   location: {
     current: { input: { clientX: number; clientY: number } };
     // Pragmatic resets `current` back to `initial` when a drag is CANCELLED (Escape / dropped on no
@@ -64,6 +60,12 @@ interface MonitorDragArgs {
   };
 }
 
+/** The two leg messages one cursor position yields. */
+export interface DragMessages {
+  move: ParentToIframe;
+  drop: ParentToIframe;
+}
+
 /**
  * PURE: build the `dragMove` + `drop` parent→iframe messages for a cursor, given the session id and
  * the target iframe's EMPIRICAL `scale` + `rect` (both injected so this is testable without a DOM).
@@ -72,11 +74,11 @@ interface MonitorDragArgs {
  * the move-preview and the authoritative drop never use a divergent coordinate transform.
  */
 export function buildDragMessages(
-  cursor: Cursor,
+  cursor: ViewportPoint,
   dragSeq: number,
   scale: number,
   iframeRect: { left: number; top: number },
-): { move: ParentToIframe; drop: ParentToIframe } {
+): DragMessages {
   const local = parentCursorToIframe(cursor, iframeRect, scale);
   return {
     drop: { cursor: local, dragSeq, kind: "drop" },
@@ -85,7 +87,7 @@ export function buildDragMessages(
 }
 
 /** The cursor of a monitor event in parent-viewport coords. */
-function cursorOf(location: MonitorDragArgs["location"]): Cursor {
+function cursorOf(location: MonitorDragArgs["location"]): ViewportPoint {
   return { x: location.current.input.clientX, y: location.current.input.clientY };
 }
 
@@ -97,11 +99,16 @@ function cursorOf(location: MonitorDragArgs["location"]): Cursor {
  * the iframe's `canDrop` rejects ancestor/self targets). Anything else (e.g. a row missing a path)
  * is ignored.
  */
-function dragSrcOf(data: Record<string, unknown>): DragSrcKind | null {
+function dragSrcOf(data: ElementDragPayload["data"]): DragSrcKind | null {
   if (data.type === "block") {
-    return { type: "block" };
+    /* SAFETY: every minter of a "block" payload sets `fragment` to the JxMutableNode it inserts;
+       only a string tag is read off it, and anything else crosses as no tag (placed as a block). */
+    const tag = (data.fragment as JxMutableNode | undefined)?.tagName;
+    return isString(tag) ? { tag, type: "block" } : { type: "block" };
   }
   if (data.type === "tree-node" && Array.isArray(data.path)) {
+    /* SAFETY: both minters of a "tree-node" payload, an Outline row's `getInitialData` and the block
+       action bar's drag handle, set `path` to the dragged node's JxPath. */
     return { path: data.path as (string | number)[], type: "tree-node" };
   }
   return null;
@@ -120,20 +127,22 @@ function dragSrcOf(data: Record<string, unknown>): DragSrcKind | null {
  *
  * @param {Tab | null} tab The document the source path is addressed in.
  * @param {DragSrcKind} src
- * @param {Record<string, unknown>} data
+ * @param {ElementDragPayload["data"]} data
  * @returns {string}
  */
 export function ghostLabel(
   tab: Tab | null,
   src: DragSrcKind,
-  data: Record<string, unknown>,
+  data: ElementDragPayload["data"],
 ): string {
   if (src.type === "block") {
+    /* SAFETY: every "block" payload minter (the palette and component cards in dnd.ts, the asset
+       file drop) sets `fragment` to the JxMutableNode the drop inserts. */
     const fragment = data.fragment as JxMutableNode | undefined;
     return displayTagName(fragment?.tagName) || "block";
   }
-  const doc = tab?.doc.document as JxMutableNode | undefined;
-  const node = doc ? (getNodeAtPath(doc, src.path) as JxMutableNode | undefined) : undefined;
+  const doc = tab?.doc.document;
+  const node = doc ? getNodeAtPath(doc, src.path) : undefined;
   return displayTagName(node?.tagName) || "node";
 }
 
@@ -150,9 +159,9 @@ const DROP_RESULT_TIMEOUT = 250;
  */
 interface CoordSession {
   src: DragSrcKind;
-  srcData: Record<string, unknown>;
+  srcData: ElementDragPayload["data"];
   /** The host whose iframe currently holds the session, or null while off-canvas. */
-  host: DragHost | null;
+  host: HostState | null;
   /** The session id the bound host was started with (for move/drop tagging). */
   seq: number;
   /** The drag ghost's label (computed once at start; the dragged thing doesn't change). */
@@ -161,9 +170,9 @@ interface CoordSession {
 
 /** Begin a session bound to `host`: bump+post dragStart, show the ghost, record the seq. */
 function startSession(
-  host: DragHost,
+  host: HostState,
   src: DragSrcKind,
-  srcData: Record<string, unknown>,
+  srcData: ElementDragPayload["data"],
 ): CoordSession {
   const seq = beginDragSession(host, src, srcData);
   // The label names a node in the TARGET pane's document — `host` is the artboard the cursor is
@@ -180,7 +189,7 @@ function startSession(
  *   new panel's iframe drives the rest.
  * - No host (inside→outside) → dragEnd the old + unbind; the ghost keeps following off-canvas.
  */
-function sessionDrag(session: CoordSession, cursor: Cursor): void {
+function sessionDrag(session: CoordSession, cursor: ViewportPoint): void {
   moveDragGhost(cursor.x, cursor.y);
   const target = liveDragHostAt(cursor);
   if (target === session.host) {
@@ -212,7 +221,7 @@ function sessionDrag(session: CoordSession, cursor: Cursor): void {
  * the affordances if no reply arrives (iframe reloaded mid-drag). Drops off-canvas release retained
  * data.
  */
-function sessionDrop(session: CoordSession, cursor: Cursor): void {
+function sessionDrop(session: CoordSession, cursor: ViewportPoint): void {
   const target = liveDragHostAt(cursor);
   // Migrate first if the drop landed on a different panel than the last move bound.
   if (target && target !== session.host) {
@@ -281,7 +290,7 @@ export function registerCanvasDndBridge(): () => void {
   let session: CoordSession | null = null;
   // The in-flight pragmatic source (set in onDragStart, cleared in onDrop) so a nativeDragEnter can
   // Bind a session for a drag whose cursor entered an iframe before the parent ever bound a host.
-  let pending: { src: DragSrcKind; srcData: Record<string, unknown> } | null = null;
+  let pending: Pick<CoordSession, "src" | "srcData"> | null = null;
 
   // Bind/migrate the live pragmatic session when its NATIVE stream enters an unclaimed iframe:
   // Chromium delivers dragover to the frame under the cursor, so a drag from the palette/layers
@@ -353,7 +362,8 @@ export function registerCanvasDndBridge(): () => void {
         return;
       }
       pending = null;
-      const cursor = location.current.input ? cursorOf(location) : { x: 0, y: 0 };
+      // Pragmatic's DragLocation always carries an `input`, cancelled drags included.
+      const cursor = cursorOf(location);
       if (!session) {
         // Never bound a host (dropped off every canvas) — just hide the ghost; nothing to apply.
         clearDragGhost();

package/src/panels/chat-panel.ts

@@ -19,12 +19,12 @@
  *
  * **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.
+ * `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