@jxsuite/studio 6.1.1 → 8.0.0

package/src/editor/repeater-scope.ts

@@ -12,12 +12,22 @@
  * Pure and DOM-free: deps limited to `@jxsuite/schema` guards/types + {@link getNodeAtPath}.
  */
 
-import { isRef } from "@jxsuite/schema/guards";
-import { getNodeAtPath } from "../state";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import {
+  isJsonObject,
+  isMappedArray,
+  isNonNullObject,
+  isRef,
+  isString,
+} from "@jxsuite/schema/guards";
 
 import type { JxPath } from "../state";
-import type { ContentSectionEntry } from "../types";
-import type { JxMappedArray, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
+import type {
+  JxMappedArray,
+  JxMutableNode,
+  JxStateDefinition,
+  ProjectConfig,
+} from "@jxsuite/schema/types";
 
 /** Cap on how many inferred/declared fields we enumerate (mirrors merge-tags BREADTH_CAP breadth). */
 const FIELD_CAP = 50;
@@ -44,18 +54,16 @@ export function findEnclosingRepeater(
   if (mapIdx <= 0) {
     return null;
   }
-  const node = getNodeAtPath(doc, path.slice(0, mapIdx)) as
-    | (Record<string, unknown> & JxMappedArray)
-    | undefined;
-  return node && node.$prototype === "Array" ? (node as JxMappedArray) : null;
+  const node = getNodeAtPath(doc, path.slice(0, mapIdx));
+  return isMappedArray(node) ? node : null;
 }
 
 /** Strip a `#/state/<name>` JSON-Pointer ref to its bare state name (null when it is not one). */
-function refToStateName(ref: unknown): string | null {
-  if (!isRef(ref)) {
+function refToStateName(binding: JxMappedArray["items"]): string | null {
+  if (!isRef(binding)) {
     return null;
   }
-  const { $ref: target } = ref;
+  const { $ref: target } = binding;
   return target.startsWith("#/state/") ? target.slice("#/state/".length) : null;
 }
 
@@ -85,25 +93,28 @@ function safeFields(names: string[]): string[] {
  */
 export function resolveRepeaterItemFields(
   arrayNode: JxMappedArray,
-  state: Record<string, unknown> | null | undefined,
+  state: Readonly<Record<string, JxStateDefinition>> | null | undefined,
   projectConfig: ProjectConfig | null | undefined,
 ): string[] {
   const base = ["item", "index"];
-  const { items } = arrayNode as { items?: unknown };
+  const { items } = arrayNode;
   const defs = state ?? {};
 
   const stateName = refToStateName(items);
   if (stateName) {
-    const def = defs[stateName] as Record<string, unknown> | undefined;
-    if (def && typeof def === "object") {
+    const def = defs[stateName];
+    if (isJsonObject(def)) {
       // (a) Content collection — `{ contentType: "<name>" }`. Import-aliased `$prototype` still
       // Matches because we detect on the `contentType` string, not the prototype name.
-      if (typeof def.contentType === "string") {
-        const content = (projectConfig?.content ?? {}) as Record<string, ContentSectionEntry>;
-        const ct = content[def.contentType];
-        const props = ct?.schema?.properties;
+      if (isString(def.contentType)) {
+        /* The `content` section is contributed by an extension and absorbed by the project
+           config's index signature, so each level is checked before it is read. */
+        const content = projectConfig?.content;
+        const ct = isJsonObject(content) ? content[def.contentType] : undefined;
+        const ctSchema = isJsonObject(ct) ? ct.schema : undefined;
+        const props = isJsonObject(ctSchema) ? ctSchema.properties : undefined;
         const out = [...base, "item.id", "item.body"];
-        if (props && typeof props === "object") {
+        if (isNonNullObject(props)) {
           for (const f of safeFields(Object.keys(props))) {
             out.push(`item.data.${f}`);
           }
@@ -112,14 +123,14 @@ export function resolveRepeaterItemFields(
       }
 
       // (b) State array — declared object item-schema, or inferred from a sample default[0].
-      const itemsSchema = def.items as Record<string, unknown> | undefined;
-      const declared = itemsSchema?.properties as Record<string, unknown> | undefined;
-      if (declared && typeof declared === "object") {
+      const itemsSchema = def.items;
+      const declared = isJsonObject(itemsSchema) ? itemsSchema.properties : undefined;
+      if (isNonNullObject(declared)) {
         return [...base, ...safeFields(Object.keys(declared)).map((f) => `item.${f}`)];
       }
-      const defaults = def.default as unknown[] | undefined;
-      const sample: unknown = Array.isArray(defaults) ? defaults[0] : undefined;
-      if (sample && typeof sample === "object" && !Array.isArray(sample)) {
+      const defaults = def.default;
+      const sample = Array.isArray(defaults) ? defaults[0] : undefined;
+      if (isJsonObject(sample)) {
         return [...base, ...safeFields(Object.keys(sample)).map((f) => `item.${f}`)];
       }
     }
@@ -128,8 +139,8 @@ export function resolveRepeaterItemFields(
 
   // (c) Inline literal array — infer fields from the first object element.
   if (Array.isArray(items)) {
-    const [first] = items as unknown[];
-    if (first && typeof first === "object" && !Array.isArray(first)) {
+    const [first] = items;
+    if (isJsonObject(first)) {
       return [...base, ...safeFields(Object.keys(first)).map((f) => `item.${f}`)];
     }
   }

package/src/editor/shortcuts.ts

@@ -30,6 +30,7 @@
  * to the code that runs, so a chord and its behaviour cannot drift apart again.
  */
 
+import { isFunction, isNonNullObject } from "@jxsuite/schema/guards";
 import { childIndex, childList, getNodeAtPath, parentElementPath, projectState } from "../store";
 import { activeTab, workspace } from "../workspace/workspace";
 import {
@@ -45,8 +46,8 @@ import {
   mutateDuplicateNodes,
   mutateInsertNode,
   mutateRemoveNodes,
-  redo as tabRedo,
-  undo as tabUndo,
+  redo,
+  undo,
   transactDoc,
 } from "../tabs/transact";
 import {
@@ -81,6 +82,7 @@ import { runReported } from "../commands/run-reported";
 import { pointerAnchor } from "../canvas/iframe-host";
 import type { PointerAnchor } from "../canvas/iframe-host";
 import type { CommandContext } from "../commands/context";
+import type { CommandArgValues } from "../commands/command-args";
 import type { DockId as CommandDockId } from "../commands/defaults";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { DockId, FocusRegion } from "../shell";
@@ -165,11 +167,14 @@ function navigateSelection(direction: -1 | 1): void {
     tab.session.selection = [[]];
     return;
   }
-  if (selected.length < 2) {
+  // `parentElementPath` is null exactly when the path is the document element (length < 2).
+  const parentPath = parentElementPath(selected);
+  if (!parentPath) {
     return;
   }
-  const parentPath = parentElementPath(selected) as JxPath;
   const parent = getNodeAtPath(tab.doc.document, parentPath);
+  // SAFETY: a selection path of length >= 2 addresses a child as `[..., "children", n]`, so its
+  // Last segment is the numeric index `n` (the same invariant `insertSiblingParagraph` relies on).
   const newIndex = (childIndex(selected) as number) + direction;
   if (newIndex >= 0 && newIndex < childList(parent).length) {
     tab.session.selection = [[...parentPath, "children", newIndex]];
@@ -190,14 +195,10 @@ function selectSiblings(): void {
     return;
   }
   const selected = primarySelection(tab.session.selection);
-  const parentPath = (
-    selected && selected.length >= 2 ? parentElementPath(selected) : []
-  ) as JxPath;
+  const parentPath: JxPath = (selected ? parentElementPath(selected) : null) ?? [];
   const parent = getNodeAtPath(tab.doc.document, parentPath);
   const paths = childList(parent).flatMap((child, index) =>
-    typeof child === "object" && child !== null
-      ? [[...parentPath, "children", index] as JxPath]
-      : [],
+    isNonNullObject(child) ? [[...parentPath, "children", index]] : [],
   );
   if (paths.length > 0) {
     tab.session.selection = paths;
@@ -242,10 +243,16 @@ function selectParent(): void {
 function insertSiblingParagraph(): void {
   const tab = activeTab.value;
   const selected = primarySelection(tab?.session.selection);
-  if (!tab || !selected || selected.length < 2) {
+  if (!tab || !selected) {
+    return;
+  }
+  // Null exactly when the selection is the document element, which has no sibling slot.
+  const parentPath = parentElementPath(selected);
+  if (!parentPath) {
     return;
   }
-  const parentPath = parentElementPath(selected) as JxPath;
+  // SAFETY: a selection path of length >= 2 addresses a child as `[..., "children", n]`, so its
+  // Last segment is the numeric child index `n`.
   const index = childIndex(selected) as number;
   const newPath = [...parentPath, "children", index + 1];
   transactDoc(tab, (t) => {
@@ -303,14 +310,14 @@ function closeDocument(): void {
 function undoDocument(): void {
   const tab = activeTab.value;
   if (tab) {
-    tabUndo(tab);
+    undo(tab);
   }
 }
 
 function redoDocument(): void {
   const tab = activeTab.value;
   if (tab) {
-    tabRedo(tab);
+    redo(tab);
   }
 }
 
@@ -349,7 +356,7 @@ function zoomBy(ctx: CommandContext, factor: number, redraw: () => void): void {
     return;
   }
   if (isContentZoom(ctx)) {
-    setEditZoom((tab.session.ui.editZoom ?? 1) * factor);
+    setEditZoom(tab.session.ui.editZoom * factor);
     return;
   }
   // Around the stage's middle, like the zoom pod's buttons.
@@ -397,7 +404,7 @@ function toggleShellDock(registry: CommandRegistry, dock: CommandDockId): void {
  * 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 {
+function runIfPresent(registry: CommandRegistry, id: string, args: CommandArgValues): void {
   if (registry.get(id) && registry.isEnabled(id)) {
     void runReported(registry, id, args, "Keyboard");
   }
@@ -521,15 +528,15 @@ function cycleRegion(direction: 1 | -1): void {
   }
 }
 
-// ─── Panel and inspector focus (⌘1–8, ⌘⇧1–4) ─────────────────────────────────
+// ─── Panel and inspector focus (`panel.focus.*`, ⌘⇧1–4) ──────────────────────
 
 /**
  * Toggle-FOCUS, not toggle-visible.
  *
- * ⌘1 from the canvas reveals Files and puts the caret in it; ⌘1 again — with Files already focused
- * — collapses the dock and hands the caret back to the pane. The distinction matters because the
- * common case is "take me there", and a toggle-visible binding makes that a coin flip on whichever
- * panel happened to be showing.
+ * `Show Files` from the canvas reveals Files and puts the caret in it; running it again — with
+ * Files already focused — collapses the dock and hands the caret back to the pane. The distinction
+ * matters because the common case is "take me there", and a toggle-visible binding makes that a
+ * coin flip on whichever panel happened to be showing.
  *
  * Every panel this can be handed lives in the Navigator. The roster is the rail plus the rail-less
  * NAVIGATOR panels (`panels/navigator-panels.ts`), so a Bottom-dock record cannot reach here — the
@@ -539,14 +546,14 @@ function cycleRegion(direction: 1 | -1): void {
  */
 function focusPanel(panelId: string): void {
   /* THE DOOR. `shell.ts`'s `NAVIGATOR_PANEL_IDS` docstring says the command is what refuses an
-     undeclared id, "at the one door a caller comes through" — this is that door for ⌘1–8, and it
+     undeclared id, "at the one door a caller comes through" — this is that door for `panel.focus.*`, and it
      was the only one of three doors that had no lock. `setActivityTab` now takes a
      `NavigatorPanelId`, so the roster's `string` has to be narrowed somewhere; narrowing HERE keeps
      `commands/defaults.ts` free of shell types, which is the property that lets three CI checks
      load the command set in a bare Bun process.
 
      A throw rather than a silent return: `tests/navigator-panels.test.ts` asserts the enum and the
-     registry agree, so this is unreachable while that passes, and a chord that quietly does nothing
+     registry agree, so this is unreachable while that passes, and a command that quietly does nothing
      is precisely the defect this change is closing. */
   const id = requireNavigatorPanelId(panelId, "panel.focus");
   const alreadyThere =
@@ -647,8 +654,9 @@ function askWhereToOpen(openName: string): Promise<ProjectOpenTarget | "cancel">
 export async function openProjectFlow(hooks: StudioCommandHooks): Promise<void> {
   const platform = hasPlatform() ? getPlatform() : null;
   const canOpenElsewhere =
-    typeof platform?.openProjectInNewWindow === "function" &&
-    typeof platform?.pickProject === "function";
+    platform !== null &&
+    isFunction(platform.openProjectInNewWindow) &&
+    isFunction(platform.pickProject);
   if (!projectState || !canOpenElsewhere) {
     await hooks.openProject("thisWindow");
     return;
@@ -959,7 +967,11 @@ export function initShortcuts(registry: CommandRegistry, stageContext: StageCont
   document.addEventListener(
     "wheel",
     (e: WheelEvent) => {
-      if ((e.ctrlKey || e.metaKey) && !(e.target as Element | null)?.closest(STAGE_SELECTOR)) {
+      const { target } = e;
+      if (
+        (e.ctrlKey || e.metaKey) &&
+        !(target instanceof Element && target.closest(STAGE_SELECTOR))
+      ) {
         e.preventDefault();
       }
     },
@@ -978,7 +990,6 @@ export function initShortcuts(registry: CommandRegistry, stageContext: StageCont
  * scrolled with the wheel at all.
  *
  * - `grid` — a Tabulator viewport with its own virtual scroller.
- * - `manage` — the Library's ordinary overflow container.
  * - `settings` — the Project Settings document (`panels/settings-pane.ts`): an `overflow-y: auto`
  *   section column, plus the Raw JSON `<pre>`'s own box inside it.
  * - `entry` — the Entry editor's `overflow-y: auto` form (`content/entry-editor.ts`).
@@ -988,28 +999,30 @@ export function initShortcuts(registry: CommandRegistry, stageContext: StageCont
  *   there is no artboard here to zoom, either.
  */
 const SELF_SCROLLING_MODES: ReadonlySet<string> = new Set([
+  /* The Content home — `browse/library-pane.ts`. Its own scrolling list, nothing to zoom. */
+  "content-home",
   "entry",
   "grid",
-  "manage",
   /* `media` — the Media viewer's own scrolling column (`media/media-pane.ts`). There is no artboard
      here either: a wheel over an image is a scroll down the page it sits on, not a zoom. */
   "media",
+  /* A workspace's home — `workspace/workspace-home.ts`. A centred column with nothing to zoom. */
+  "media-home",
   "preview",
-  "settings",
+  "publish-home",
 ]);
 
 /**
  * Can a box between `target` and the stage still answer this wheel itself?
  *
- * Edit forwards every wheel to the page's scroller (see the branch below), which was the whole
- * story while the stage cell held nothing but the page. It also holds the Document Header band now,
- * a capped scroll container standing beside the scroller — and a `preventDefault` from an ANCESTOR
- * listener cancels the native scroll of whatever the pointer is over, so a form taller than the cap
- * could not be wheeled at all while the page scrolled underneath it instead. So the stage takes the
- * wheel only when nothing inside it wants one: the walk stops at the stage cell, and it steps over
- * the page's scroller because that box is what the forwarding is FOR — a wheel forwarded out of the
- * cross-origin frame is dispatched on the cell itself and reaches no scrollable element on the way,
- * and letting the browser scroll the page natively would chain out of it into the shell.
+ * Edit forwards every wheel to the page's scroller (see the branch below). A `preventDefault` from
+ * an ANCESTOR listener cancels the native scroll of whatever the pointer is over, so any box in the
+ * stage cell that scrolls itself (a sideways strip, a capped list) would otherwise be unwheelable
+ * while the page scrolled underneath it instead. So the stage takes the wheel only when nothing
+ * inside it wants one: the walk stops at the stage cell, and it steps over the page's scroller
+ * because that box is what the forwarding is FOR — a wheel forwarded out of the cross-origin frame
+ * is dispatched on the cell itself and reaches no scrollable element on the way, and letting the
+ * browser scroll the page natively would chain out of it into the shell.
  *
  * @param {WheelEvent} e
  * @param {HTMLElement} stage The cell the listener is on — the walk's upper bound, exclusive.
@@ -1022,7 +1035,7 @@ function wheelBelongsInside(
 ): boolean {
   const { target } = e;
   let el: Element | null =
-    target instanceof Element ? target : ((target as Node | null)?.parentElement ?? null);
+    target instanceof Element ? target : target instanceof Node ? target.parentElement : null;
   while (el && el !== stage) {
     if (el instanceof HTMLElement && el !== pageScroller && canScrollBy(el, e.deltaX, e.deltaY)) {
       return true;
@@ -1134,8 +1147,8 @@ export function installStageGestures(surface: CanvasSurface): () => void {
         /* The stage's own scroller, by the `part` the stage document draws it with — the same
            attribute every other consumer of the canvas's chrome now addresses it by. */
         const sc = canvasWrap.querySelector<HTMLElement>('[part="edit-canvas"]');
-        /* …unless the pointer is over a box in this cell that scrolls itself — the Document Header
-           band, which Edit docks beside the scroller. See {@link wheelBelongsInside}. */
+        /* …unless the pointer is over a box in this cell that scrolls itself. See
+           {@link wheelBelongsInside}. */
         if (sc && !wheelBelongsInside(e, canvasWrap, sc)) {
           e.preventDefault();
           sc.scrollTop += e.deltaY;
@@ -1219,7 +1232,7 @@ export function installStageGestures(surface: CanvasSurface): () => void {
   canvasWrap.addEventListener(
     "click",
     (e: MouseEvent) => {
-      if (e.target !== canvasWrap && e.target !== surface.panzoomWrap) {
+      if (!isStageBackground(e.target, canvasWrap, surface.panzoomWrap)) {
         return;
       }
       const tab = tabOfPane(surface.paneId);
@@ -1237,6 +1250,27 @@ export function installStageGestures(surface: CanvasSurface): () => void {
   };
 }
 
+/**
+ * Whether a click landed on a stage's BACKGROUND rather than on anything drawn in it: the stage
+ * itself, the pan/zoom surface, or the frame box every view draws its artboards in.
+ *
+ * The frame box is the one that matters in Edit. Edit has no pan/zoom surface; its frame is the
+ * scrolling `[part="edit-canvas"]` that fills the stage around the page column, so the grey margin
+ * beside the page IS that box, and a test that knew only the stage and the pan/zoom surface never
+ * saw a click there. The frame is recognised by its static `data-slot`, which the stage document
+ * stamps on it in every view.
+ */
+export function isStageBackground(
+  target: EventTarget | null,
+  stage: Element,
+  panzoom: Element | null,
+): boolean {
+  if (target === stage || (panzoom !== null && target === panzoom)) {
+    return true;
+  }
+  return target instanceof HTMLElement && target.dataset.slot === "frame" && stage.contains(target);
+}
+
 /** The context a stage answers with before the bootstrap has published a reader. */
 function stageless(): ShortcutPointerContext {
   return {

package/src/editor/slash-menu.ts

@@ -27,14 +27,15 @@
  */
 
 import { openSlashMenuSurface } from "../surfaces/slash-menu";
+import { componentSlashCommands } from "./insert-component";
 import { rectOf } from "../utils/geometry";
-import type { SlashMenuRow, SlashMenuSurface, SlashMenuView } from "../surfaces/slash-menu";
-
-interface SlashCommand {
-  label: string;
-  tag: string;
-  description: string;
-}
+import type {
+  SlashMenuGroup,
+  SlashMenuRow,
+  SlashMenuSurface,
+  SlashMenuView,
+} from "../surfaces/slash-menu";
+import type { SlashCommand } from "./inline-edit";
 
 // ─── Commands ─────────────────────────────────────────────────────────────────
 
@@ -120,9 +121,43 @@ export function showSlashMenuAtRect(
   showAt(rect, filter, cbs);
 }
 
+/**
+ * The standard set: the HTML elements, then the project's components under their own heading
+ * (§5.7), read from the registry at the moment the menu opens so a component saved a moment ago is
+ * on offer.
+ */
+function standardCommands(): SlashCommand[] {
+  return [...SLASH_COMMANDS, ...componentSlashCommands()];
+}
+
 /** Everything on offer right now: what the caller named, or the standard set. */
 function source(): SlashCommand[] {
-  return callbacks?.commands || SLASH_COMMANDS;
+  return callbacks?.commands || standardCommands();
+}
+
+/**
+ * The rows as the panel groups them: consecutive offers with the same heading share a group, and
+ * the first, unheaded group is the HTML elements. Each row keeps its index in the FLAT list, which
+ * is the one the keyboard, the highlight and a pick count in.
+ */
+function groupsOf(rows: readonly SlashMenuRow[], items: readonly SlashCommand[]): SlashMenuGroup[] {
+  const groups: SlashMenuGroup[] = [];
+  for (const [index, row] of rows.entries()) {
+    const label = items[index]?.group ?? "";
+    const last = groups.at(-1);
+    if (last?.label === label) {
+      last.rows.push(row);
+    } else {
+      groups.push({
+        hasLabel: label !== "",
+        key: label || "elements",
+        label,
+        name: label || "Elements",
+        rows: [row],
+      });
+    }
+  }
+  return groups;
 }
 
 /** The offers a filter leaves standing. An empty filter leaves all of them. */
@@ -137,14 +172,17 @@ function matching(filter: string, from: SlashCommand[]): SlashCommand[] {
 /** What the panel should be showing, from the state above. */
 function view(): SlashMenuView {
   const rect = _anchorRect;
+  const rows = filteredItems.map((cmd, index): SlashMenuRow => ({
+    description: cmd.description,
+    index,
+    key: cmd.tag,
+    label: cmd.label,
+  }));
   return {
     activeIndex: activeIdx,
     filter: filterText,
-    rows: filteredItems.map((cmd): SlashMenuRow => ({
-      description: cmd.description,
-      key: cmd.tag,
-      label: cmd.label,
-    })),
+    groups: groupsOf(rows, filteredItems),
+    rows,
     showFilter,
     // The gap between the anchor and the panel is the `--jx-popover-offset` token the element
     // Already applies, so this is the anchor's own edge rather than an edge plus a guess.
@@ -168,7 +206,7 @@ function showAt(
   callbacks = cbs;
   _anchorRect = rect;
 
-  filteredItems = matching(filter, cbs.commands || SLASH_COMMANDS);
+  filteredItems = matching(filter, cbs.commands || standardCommands());
 
   if (filteredItems.length === 0 && !cbs.showFilter) {
     dismissSlashMenu();

package/src/files/asset-versions.ts

@@ -30,13 +30,14 @@
  * paths only — a `.json` or `.md` file is never loaded by URL from the canvas, and leaving them out
  * keeps that message as small as the media set.
  *
- * Pure module state — it imports nothing but path normalization and the reactivity re-export — so
- * the canvas host can import it without dragging in the file layer.
+ * Pure module state — it imports nothing but path normalization, the primitive guards and the
+ * reactivity re-export — so the canvas host can import it without dragging in the file layer.
  *
  * @docs extending/embedding/platform-adapter
  */
 
 import { normalizeProjectPath } from "@jxsuite/schema/asset-paths";
+import { isString } from "@jxsuite/schema/guards";
 import { shallowRef } from "../reactivity";
 import type { DirEntry } from "../types";
 
@@ -161,8 +162,7 @@ export function noteListing(entries: readonly DirEntry[], since: number): void {
     if (path === "" || dirtiedSince(path, since)) {
       continue;
     }
-    const version =
-      typeof entry.version === "string" && entry.version !== "" ? entry.version : null;
+    const version = isString(entry.version) && entry.version !== "" ? entry.version : null;
     const held = versions.get(path);
     if (version === null) {
       if (held === undefined) {