@jxsuite/studio 6.1.1 → 6.1.2

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");
   }
@@ -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();
       }
     },
@@ -1022,7 +1034,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;

package/src/editor/slash-menu.ts

@@ -29,12 +29,7 @@
 import { openSlashMenuSurface } from "../surfaces/slash-menu";
 import { rectOf } from "../utils/geometry";
 import type { SlashMenuRow, SlashMenuSurface, SlashMenuView } from "../surfaces/slash-menu";
-
-interface SlashCommand {
-  label: string;
-  tag: string;
-  description: string;
-}
+import type { SlashCommand } from "./inline-edit";
 
 // ─── Commands ─────────────────────────────────────────────────────────────────
 

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) {

package/src/files/components.ts

@@ -4,7 +4,8 @@ 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";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JsonValue, JxMutableNode } from "@jxsuite/schema/types";
 
 /** A discovered component: project components carry a file path; package components may not. */
 export interface ComponentEntry extends Omit<ComponentMeta, "path"> {
@@ -40,15 +41,17 @@ export async function loadComponentRegistry() {
  *
  * @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.
+ * @param {JxMutableNode} 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 {
+export function noteComponentSaved(path: string | null, doc: JxMutableNode): boolean {
   if (!path) {
     return false;
   }
   const index = componentRegistry.findIndex((c) => c.path === path);
-  const meta = componentMetaFrom(doc, path);
+  /* SAFETY: a saved tab's document was parsed from JSON and has just been written back as JSON
+     (`serializeDocument`), so every value it holds is a JSON value — the model the extractor reads. */
+  const meta = componentMetaFrom(doc as JsonValue, path);
   if (!meta) {
     if (index === -1) {
       return false;
@@ -56,6 +59,8 @@ export function noteComponentSaved(path: string | null, doc: unknown): boolean {
     componentRegistry.splice(index, 1);
     return true;
   }
+  /* SAFETY: `componentMetaFrom` is the extractor every backend's `discoverComponents` scan runs to
+     Produce the registry's entries, so its output has the shape the registry already holds. */
   const entry = meta as ComponentEntry;
   if (index === -1) {
     componentRegistry.push(entry);
@@ -84,7 +89,7 @@ export function buildComponentInstance(comp: ComponentEntry): JxMutableNode {
     for (const child of structuredClone(slot.fallback ?? [])) {
       if (!slot.name) {
         children.push(child);
-      } else if (typeof child === "object" && child !== null && typeof child.tagName === "string") {
+      } else if (isNonNullObject(child) && isString(child.tagName)) {
         // Preserve an author-set slot attribute (slot forwarding inside fallback).
         child.attributes = { slot: slot.name, ...child.attributes };
         children.push(child);
@@ -94,11 +99,11 @@ export function buildComponentInstance(comp: ComponentEntry): JxMutableNode {
       }
     }
   }
-  return {
-    $props,
-    tagName: comp.tagName,
-    ...(children.length > 0 ? { children } : {}),
-  };
+  const instance: JxMutableNode = { $props, tagName: comp.tagName };
+  if (children.length > 0) {
+    instance.children = children;
+  }
+  return instance;
 }
 
 /**

package/src/files/elements.ts

@@ -20,6 +20,7 @@
  * they must not differ on is WHICH entries the list should hold.
  */
 
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { computeRelativePath } from "./components";
 import type { ComponentEntry } from "./components";
 import type { JxElement } from "@jxsuite/schema/types";
@@ -29,9 +30,7 @@ export type ElementsEntry = string | JxElement | { $ref: string };
 
 /** The `$ref` of an entry, when it has one. */
 function refOf(entry: ElementsEntry): string | null {
-  return typeof entry === "object" && entry !== null && typeof entry.$ref === "string"
-    ? entry.$ref
-    : null;
+  return isNonNullObject(entry) && isString(entry.$ref) ? entry.$ref : null;
 }
 
 /**
@@ -81,7 +80,7 @@ export function hasElement(
   const specifier = npmSpecifier(comp);
   if (specifier) {
     return elements.some(
-      (entry) => typeof entry === "string" && (entry === specifier || entry === comp.package),
+      (entry) => isString(entry) && (entry === specifier || entry === comp.package),
     );
   }
   if (!comp.path) {
@@ -132,7 +131,7 @@ export function disableElement(
   if (specifier) {
     // Both spellings: a component ticked off must not stay imported through the package entry.
     return elements.filter(
-      (entry) => !(typeof entry === "string" && (entry === specifier || entry === comp.package)),
+      (entry) => !(isString(entry) && (entry === specifier || entry === comp.package)),
     );
   }
   if (!comp.path) {
@@ -151,7 +150,7 @@ export function removePackageElements(
   pkg: string,
 ): ElementsEntry[] {
   return elements.filter(
-    (entry) => typeof entry !== "string" || !(entry === pkg || entry.startsWith(`${pkg}/`)),
+    (entry) => !isString(entry) || !(entry === pkg || entry.startsWith(`${pkg}/`)),
   );
 }
 

package/src/files/file-ops.ts

@@ -28,6 +28,8 @@ import { showConfirmDialog } from "../ui/layers";
 import { locateDocument } from "../services/code-services";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { notify } from "../services/notify";
+import type { NotifyOptions } from "../services/notify";
+import { isString } from "@jxsuite/schema/guards";
 import { validateComponentSlots } from "../services/cem-export";
 import { reportPopoverProblems } from "../services/popover-report";
 import { getPlatform } from "../platform";
@@ -103,19 +105,66 @@ export async function parseSourceForPath(path: string, source: string) {
 export const parseCollabSource: CollabParser = async (tab, text) => {
   if (tab.documentPath && formatForPath(tab.documentPath)) {
     const parsed = await parseSourceForPath(tab.documentPath, text);
-    return { document: parsed.document as JxMutableNode, frontmatter: parsed.frontmatter };
+    return { document: parsed.document, frontmatter: parsed.frontmatter };
   }
   const parsed = parseJsonDocument(text);
   tab.doc.layout = parsed.layout;
+  /* SAFETY: a co-edited path no format class claims is a `.json` Jx document (every other path
+     `ensureCollab` attaches to is a format file, handled above), and that file's schema makes its
+     Top-level object a node — the object `parseJsonDocument` already states it returns. */
   return { document: parsed.document as JxMutableNode };
 };
 
+/** One `accept` group of a File System Access picker: media type → extensions, with a label. */
+interface FilePickerAcceptType {
+  accept: Record<string, string[]>;
+  description: string;
+}
+
+/**
+ * The File System Access pickers (WICG), which TypeScript's DOM lib does not declare. Only what
+ * this module passes and reads is spelled out.
+ */
+interface FilePickerWindow {
+  showOpenFilePicker: (options: {
+    types: FilePickerAcceptType[];
+  }) => Promise<FileSystemFileHandle[]>;
+  /* Export's single extension is `format.extensions[0]`, absent for a format that declares none —
+     So the save picker is typed with the value it is actually handed. */
+  showSaveFilePicker: (options: {
+    suggestedName?: string | undefined;
+    types: { accept: Record<string, (string | undefined)[]>; description: string }[];
+  }) => Promise<FileSystemFileHandle>;
+}
+
+/** Whether this browser offers `showOpenFilePicker` (Chromium does; Firefox and Safari do not). */
+function hasOpenFilePicker(
+  win: Window,
+): win is Window & Pick<FilePickerWindow, "showOpenFilePicker"> {
+  return "showOpenFilePicker" in win;
+}
+
+/** Whether this browser offers `showSaveFilePicker` (Chromium does; Firefox and Safari do not). */
+function hasSaveFilePicker(
+  win: Window,
+): win is Window & Pick<FilePickerWindow, "showSaveFilePicker"> {
+  return "showSaveFilePicker" in win;
+}
+
+/** Attach the tab's file to a notification's options, when it has one. */
+function atTabPath(tab: Tab, options: NotifyOptions): NotifyOptions {
+  if (tab.documentPath !== null) {
+    options.path = tab.documentPath;
+  }
+  return options;
+}
+
 /** Open a file via the File System Access API (or fallback input). */
 export async function openFile() {
   try {
     await loadFormats();
     const formats = getFormats();
-    const pickerTypes = [
+    const pickerTypes: FilePickerAcceptType[] = [
       {
         accept: { "application/json": [".json"] },
         description: "Jx Component",
@@ -160,12 +209,8 @@ export async function openFile() {
       // Trail; it does not need a message that erases itself.
     };
 
-    if ("showOpenFilePicker" in window) {
-      const [handle] = await (
-        window as unknown as {
-          showOpenFilePicker: (options?: unknown) => Promise<FileSystemFileHandle[]>;
-        }
-      ).showOpenFilePicker({ types: pickerTypes });
+    if (hasOpenFilePicker(window)) {
+      const [handle] = await window.showOpenFilePicker({ types: pickerTypes });
       const file = await handle!.getFile();
       await handleSource(handle!.name, await file.text(), handle!);
     } else {
@@ -230,16 +275,16 @@ function reportSaved(tab: Tab) {
   const doc = tab.doc.document;
   _onDocumentSaved(tab.documentPath, doc);
   const warning =
-    typeof doc.tagName === "string" && doc.tagName.includes("-")
-      ? validateComponentSlots(doc)
-      : null;
+    isString(doc.tagName) && doc.tagName.includes("-") ? validateComponentSlots(doc) : null;
   if (warning) {
-    notify.warn(warning, {
-      key: `slots:${tab.documentPath ?? tab.id}`,
-      ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
-      source: "Components",
-      tier: "problem",
-    });
+    notify.warn(
+      warning,
+      atTabPath(tab, {
+        key: `slots:${tab.documentPath ?? tab.id}`,
+        source: "Components",
+        tier: "problem",
+      }),
+    );
   }
   /* Popover correctness, beside the slot check and for the same reason it is here: a successful
      save is the one chokepoint every edit passes through, whichever surface made it. A render-time
@@ -311,12 +356,11 @@ export async function saveFile(tab: Tab | null = activeTab.value): Promise<boole
     notify.warn(
       `You have read access to this session — changes to ${tab.documentPath ?? "this document"} ` +
         `stay in your browser and cannot be saved.`,
-      {
+      atTabPath(tab, {
         action: "file.save",
         key: `save.readOnly:${tab.documentPath ?? tab.id}`,
-        ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
         source: "Collaboration",
-      },
+      }),
     );
     return false;
   }
@@ -327,11 +371,10 @@ export async function saveFile(tab: Tab | null = activeTab.value): Promise<boole
   if (!hasSerializableDocument(tab)) {
     notify.warn(
       `${tab.documentPath ?? "This file"} is a media file, so there is no document for Save to write.`,
-      {
+      atTabPath(tab, {
         key: `save.notADocument:${tab.documentPath ?? tab.id}`,
-        ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
         source: "Save",
-      },
+      }),
     );
     return false;
   }
@@ -381,13 +424,15 @@ export async function saveFile(tab: Tab | null = activeTab.value): Promise<boole
     notify.warn("This document has no save target — use Export.", { key: "save.noTarget" });
   } catch (error) {
     if (!(error instanceof Error && error.name === "AbortError")) {
-      notify.error(`Could not save ${tab.documentPath ?? tab.id}.`, {
-        action: "file.save",
-        detail: errorMessage(error),
-        key: `save:${tab.documentPath ?? tab.id}`,
-        ...(tab.documentPath === null ? {} : { path: tab.documentPath }),
-        source: "Save",
-      });
+      notify.error(
+        `Could not save ${tab.documentPath ?? tab.id}.`,
+        atTabPath(tab, {
+          action: "file.save",
+          detail: errorMessage(error),
+          key: `save:${tab.documentPath ?? tab.id}`,
+          source: "Save",
+        }),
+      );
     }
   }
   return false;
@@ -418,13 +463,9 @@ export async function exportFile() {
     const description = format ? format.name : "Jx Component";
     const fallbackName = format ? `content${ext}` : "component.json";
 
-    if ("showSaveFilePicker" in window) {
+    if (hasSaveFilePicker(window)) {
       const suggestedName = tab.documentPath ? tab.documentPath.split("/").pop() : fallbackName;
-      const handle = await (
-        window as unknown as {
-          showSaveFilePicker: (options?: unknown) => Promise<FileSystemFileHandle>;
-        }
-      ).showSaveFilePicker({
+      const handle = await window.showSaveFilePicker({
         suggestedName,
         types: [{ accept: { [mimeType]: [ext] }, description }],
       });