@jxsuite/studio 6.1.1 → 6.1.2

package/src/canvas/iframe-slash.ts

@@ -21,7 +21,17 @@ import type { IframeToParent, ParentToIframe } from "./iframe-protocol";
 
 type SlashNavKey = Extract<IframeToParent, { kind: "slashNav" }>["key"];
 
-const NAV_KEYS = new Set(["ArrowUp", "ArrowDown", "Enter", "Escape"]);
+const NAV_KEYS = new Set<string>([
+  "ArrowUp",
+  "ArrowDown",
+  "Enter",
+  "Escape",
+] satisfies SlashNavKey[]);
+
+/** Whether `key` is one of the four keys the parent menu navigates by. */
+function isNavKey(key: string): key is SlashNavKey {
+  return NAV_KEYS.has(key);
+}
 
 /**
  * Register the bridge SlashController for this iframe realm and wire its keyboard/dismissal
@@ -55,28 +65,31 @@ export function startIframeSlashBridge(
       open = true;
       lastPostedFilter = filter;
       const r = rectOf(anchorEl);
-      channel.post({
+      const message: Extract<IframeToParent, { kind: "slashShow" }> = {
         filter,
         kind: "slashShow",
         rect: { height: r.height, width: r.width, x: r.left, y: r.top },
-        /* Carried, because the parent draws the menu and only the FRAME knows why it opened. A
-           menu opened by name has no "/…" run in the document to filter with, so it needs its own
-           field; the "/" gesture needs none, because the author types into the block. This option
-           was dropped at this boundary and the loss was invisible — the menu still appeared, just
-           with no way past fifteen items but scrolling. */
-        ...(cbs.showFilter === true ? { showFilter: true } : {}),
-      });
+      };
+      /* Carried, because the parent draws the menu and only the FRAME knows why it opened. A
+         menu opened by name has no "/…" run in the document to filter with, so it needs its own
+         field; the "/" gesture needs none, because the author types into the block. This option
+         was dropped at this boundary and the loss was invisible — the menu still appeared, just
+         with no way past fifteen items but scrolling. */
+      if (cbs.showFilter === true) {
+        message.showFilter = true;
+      }
+      channel.post(message);
     },
   };
   setSlashController(controller);
 
   const onKeyDown = (e: KeyboardEvent) => {
-    if (!open || !NAV_KEYS.has(e.key)) {
+    if (!open || !isNavKey(e.key)) {
       return;
     }
     e.preventDefault();
     e.stopPropagation();
-    channel.post({ key: e.key as SlashNavKey, kind: "slashNav" });
+    channel.post({ key: e.key, kind: "slashNav" });
   };
   const onMouseDown = () => {
     // The parent menu's outside-click listener can't see iframe clicks — any in-iframe press while

package/src/canvas/iframe-subtree.ts

@@ -12,6 +12,7 @@
  */
 
 import { releaseElementStyles, renderNode, runScoped } from "@jxsuite/runtime";
+import { isNumber, isString } from "@jxsuite/schema/guards";
 import { getNodeAtPath } from "../state";
 import { makeStamper } from "./iframe-render";
 import { prepareForEditMode } from "../utils/edit-display";
@@ -39,11 +40,14 @@ export function renderSubtreeIframe(
   docPath: JxPath,
   ctx: IframeRenderCtx,
 ): HTMLElement | Text {
+  /* SAFETY: a widening of getNodeAtPath's declared return. A patch path addresses an entry of a
+   * `children` array, which the schema types as `JxMutableNode | string`, and a missing step
+   * answers undefined, so those three cases are the whole range. */
   const node = getNodeAtPath(shadowDoc, docPath) as JxMutableNode | string | undefined;
   if (node === undefined) {
     throw new Error(`iframe-patch-node-not-found:${docPath.join("/")}`);
   }
-  const def = typeof node === "string" ? node : prepareForEditMode(stripEventHandlers(node));
+  const def = isString(node) ? node : prepareForEditMode(stripEventHandlers(node));
   const { result: rendered, stop } = runScoped(() =>
     renderNode(def, ctx.defs, {
       _path: docPathToRenderPath(docPath, ctx),
@@ -98,7 +102,7 @@ function docPathToRenderPath(docPath: JxPath, ctx: IframeRenderCtx): (string | n
   const { mapperCtx } = ctx;
   if (mapperCtx.layoutWrapped && mapperCtx.pageContentPrefix && docPath[0] === "children") {
     const [, idx] = docPath;
-    return typeof idx === "number"
+    return isNumber(idx)
       ? [
           ...mapperCtx.pageContentPrefix,
           idx + (mapperCtx.pageContentOffset ?? 0),

package/src/canvas/path-mapping.ts

@@ -11,6 +11,8 @@
  * result for the `data-jx-path` attribute.
  */
 
+import { isJsonObject, isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
 
 /**
@@ -83,22 +85,27 @@ export function wrapsPageContent(path: JxPath, prefix: JxPath | null): boolean {
  * Resolve a runtime render path to a document path (or flag it as layout-originated). Pure — the
  * caller decides whether to record the result in a WeakMap or `data-jx-*` attributes.
  */
-export function classifyRenderNode(path: JxPath, def: unknown, ctx: PathMapCtx): RenderNodeClass {
+export function classifyRenderNode(
+  path: JxPath,
+  def: JxElement | string,
+  ctx: PathMapCtx,
+): RenderNodeClass {
   // Layout-originated nodes have no page-document path; the caller stamps their origin instead
   // (data-jx-layout-path / data-jx-layout-file).
-  const marker =
-    ctx.layoutWrapped && typeof def === "object"
-      ? (def as { $__layout?: unknown } | null)?.$__layout
-      : undefined;
+  const marker = ctx.layoutWrapped && isNonNullObject(def) ? def["$__layout"] : undefined;
   if (marker) {
-    const origin = (typeof marker === "object" ? marker : {}) as Partial<LayoutMarker>;
+    // A legacy bare `true` marker carries no origin, so it reads as an empty one.
+    const origin = isJsonObject(marker) ? marker : {};
+    const { file, path: originPath } = origin;
     return {
       // The root is never chrome even when the layout distributed nothing: it IS the render, and a
       // Dimmed, frozen root would be a canvas nobody can touch.
       chrome: path.length > 0 && !wrapsPageContent(path, ctx.pageContentPrefix),
       kind: "layout",
-      layoutFile: typeof origin.file === "string" ? origin.file : "",
-      layoutPath: Array.isArray(origin.path) ? origin.path : [],
+      layoutFile: isString(file) ? file : "",
+      /* SAFETY: markLayoutNodes (canvas-live-render.ts) is the only writer of `$__layout`, and the
+       * `path` it stamps is a LayoutMarker's JxPath. */
+      layoutPath: Array.isArray(originPath) ? (originPath as JxPath) : [],
     };
   }
 
@@ -112,10 +119,9 @@ export function classifyRenderNode(path: JxPath, def: unknown, ctx: PathMapCtx):
     if (path.length >= pfx.length && pfx.every((seg, i) => path[i] === seg)) {
       const rest = path.slice(pfx.length);
       const [containerIdx] = rest;
-      mappedPath =
-        typeof containerIdx === "number"
-          ? ["children", containerIdx - (ctx.pageContentOffset ?? 0), ...rest.slice(1)]
-          : ["children", ...rest];
+      mappedPath = isNumber(containerIdx)
+        ? ["children", containerIdx - (ctx.pageContentOffset ?? 0), ...rest.slice(1)]
+        : ["children", ...rest];
     }
   }
 
@@ -154,5 +160,6 @@ export function serializeJxPath(path: JxPath): string {
 
 /** Decode a `data-jx-path` attribute back into a document path. */
 export function parseJxPath(serialized: string): JxPath {
+  // SAFETY: only serializeJxPath writes `data-jx-path`, and it is JSON.stringify of a JxPath.
   return JSON.parse(serialized) as JxPath;
 }

package/src/canvas/popover-path.ts

@@ -14,6 +14,7 @@
 import { activeTab } from "../workspace/workspace";
 import { getNodeAtPath } from "../state";
 import { documentHasPopover, isPopover } from "@jxsuite/schema/overlays";
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import { INVOKER_TAGS, POPOVER_TAGS } from "@jxsuite/ui";
 import { primarySelection } from "../tabs/selection";
 import type { JxMutableNode } from "@jxsuite/schema/types";
@@ -49,7 +50,7 @@ export function ancestorPopoverPath(
   for (let end = path.length; end >= 0; end -= 1) {
     const prefix = path.slice(0, end);
     const node = getNodeAtPath(doc, prefix);
-    if (node && typeof node === "object" && isPopover(node, KIT_SCOPE)) {
+    if (isNonNullObject(node) && isPopover(node, KIT_SCOPE)) {
       return prefix;
     }
   }
@@ -72,13 +73,16 @@ export function ancestorPopoverPath(
  * @returns The popover's path, or null.
  */
 export function popoverPathFor(tab: Tab, explicit?: JxPath): JxPath | null {
+  /* SAFETY: a widening, not a narrowing. A tab built by createTab always carries a document, but
+   * the command is a public entry point and the contract (pinned in popover-state.test.ts) is that
+   * a tab record without one answers null rather than throwing inside getNodeAtPath. */
   const doc = tab.doc.document as JxMutableNode | undefined;
   if (!doc) {
     return null;
   }
   if (explicit) {
     const node = getNodeAtPath(doc, explicit);
-    return node && typeof node === "object" && isPopover(node, KIT_SCOPE) ? explicit : null;
+    return isNonNullObject(node) && isPopover(node, KIT_SCOPE) ? explicit : null;
   }
   return ancestorPopoverPath(doc, primarySelection(tab.session.selection));
 }
@@ -101,6 +105,6 @@ export function popoverPathFor(tab: Tab, explicit?: JxPath): JxPath | null {
  * @returns True when the focused document declares at least one popover.
  */
 export function activeDocumentHasPopover(): boolean {
-  const doc = activeTab.value?.doc.document as JxMutableNode | undefined;
+  const doc = activeTab.value?.doc.document;
   return doc ? documentHasPopover(doc, KIT_SCOPE) : false;
 }

package/src/canvas/popover-state.ts

@@ -31,7 +31,6 @@ 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";
 
@@ -59,7 +58,7 @@ export function setOpenPopover(tab: Tab, path: JxPath | null): void {
 
 /** 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);
+  const target = ancestorPopoverPath(tab.doc.document, path);
   if (target === null || samePath(tab.session.ui.openPopover, target)) {
     return false;
   }

package/src/canvas/serialize-scope.ts

@@ -12,6 +12,10 @@
  * Pure and DOM-free — no reactivity/runtime imports — so it stays trivially unit-testable.
  */
 
+import { isFunction } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+
 /**
  * Per-value size cap (in JSON-string chars). A single large content collection can be tens of KB;
  * past this cap we store a small placeholder so one big data source can't bloat every render's
@@ -34,18 +38,21 @@ const LARGE_VALUE_PLACEHOLDER = "[large value omitted]";
  * @param defs The resolved `$defs` scope (may be a Vue reactive proxy).
  * @returns A plain object safe to `postMessage` (every value is JSON-round-trippable).
  */
-export function serializeDataScope(defs: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
+export function serializeDataScope(defs: JxScope): JsonObject {
+  const out: JsonObject = {};
   for (const key of Object.keys(defs)) {
     try {
       // Reading through the reactive proxy auto-unwraps a top-level ref/computed to its value, and
       // Can THROW (a computed getter that throws) — done inside the try so that maps the key to null
       // Rather than aborting the whole snapshot.
       const value = defs[key];
-      if (typeof value === "function") {
+      if (isFunction(value)) {
         continue; // Data sources only — a resolved server/handler fn isn't a "value".
       }
-      const json = JSON.stringify(value);
+      /* SAFETY: a widening of lib.d.ts's `string` to the real range. JSON.stringify answers
+       * undefined for a top-level undefined, a symbol, or a value whose toJSON() returns undefined
+       * (ECMA-262 SerializeJSONProperty), and the branch below depends on seeing that. */
+      const json = JSON.stringify(value) as string | undefined;
       if (json === undefined) {
         // JSON.stringify returns undefined for a bare function/symbol/undefined at the top level.
         out[key] = null;
@@ -55,7 +62,8 @@ export function serializeDataScope(defs: Record<string, unknown>): Record<string
         out[key] = LARGE_VALUE_PLACEHOLDER;
         continue;
       }
-      out[key] = JSON.parse(json) as unknown;
+      // SAFETY: `json` is JSON.stringify's own output above, so it parses back to JSON data.
+      out[key] = JSON.parse(json) as JsonValue;
     } catch {
       // A circular structure or a throwing getter → the key exists but carries no serializable value.
       out[key] = null;

package/src/canvas/stage-scrollbar.ts

@@ -32,6 +32,7 @@
  */
 
 import { PANE_SELECTOR } from "../surfaces/pane-grid";
+import { stageOf } from "./surface-registry";
 import type { CanvasSurface } from "./surface-registry";
 
 /**
@@ -61,7 +62,7 @@ export function scrollbarWidthOf(scroller: HTMLElement): number {
 
 /** The cell a stage belongs to, or the document root when it is outside every cell. */
 function cellOf(surface: CanvasSurface): HTMLElement {
-  return surface.wrap?.closest<HTMLElement>(PANE_SELECTOR) ?? document.documentElement;
+  return stageOf(surface)?.closest<HTMLElement>(PANE_SELECTOR) ?? document.documentElement;
 }
 
 /**

package/src/canvas/surface-registry.ts

@@ -154,7 +154,7 @@ export function surfaceForPane(paneId: string): CanvasSurface {
 
 /** A surface record with nothing in it. One place the per-stage defaults are written down. */
 function freshSurface(paneId: string): CanvasSurface {
-  return {
+  const record: Omit<CanvasSurface, "wrap"> & { wrap: HTMLElement | null } = {
     centerObserver: null,
     monacoDiffEditor: null,
     monacoEditor: null,
@@ -171,8 +171,26 @@ function freshSurface(paneId: string): CanvasSurface {
     renderGeneration: 0,
     sourceCollabCleanup: null,
     stageScrollbar: null,
-    wrap: null as unknown as HTMLElement,
+    wrap: null,
   };
+  /* SAFETY: `wrap` is the only member that differs from CanvasSurface, and it is null only until
+   * registerCanvasSurface attaches the pane's stage. The grid registers a cell's stage as it builds
+   * the cell, before any renderer runs (§18.1 rule 1), and the paths that can run earlier read the
+   * element through stageOf(), which keeps the nullable type. */
+  return record as CanvasSurface;
+}
+
+/**
+ * The surface's stage element, or null before {@link registerCanvasSurface} attaches one.
+ *
+ * `wrap` is typed non-null for the renderers, which only run after registration. The gestures and
+ * teardowns that can reach a surface before its host exists read it through here instead.
+ *
+ * @param {CanvasSurface} surface
+ * @returns {HTMLElement | null}
+ */
+export function stageOf(surface: CanvasSurface): HTMLElement | null {
+  return surface.wrap;
 }
 
 /**
@@ -199,7 +217,7 @@ export function stageContaining(node: Node | null): CanvasSurface | null {
     return null;
   }
   for (const surface of _surfaces.values()) {
-    if (surface.wrap?.contains(node)) {
+    if (stageOf(surface)?.contains(node)) {
       return surface;
     }
   }

package/src/collab/collab-commands.ts

@@ -19,7 +19,12 @@ import { collabState } from "./collab-state";
 import { isCollabEnabled, setCollabEnabled } from "./collab-session";
 import { notify } from "../services/notify";
 import { activeTab } from "../workspace/workspace";
-import { booleanArg, booleanProperty, stringProperty } from "../commands/command-args";
+import {
+  booleanArg,
+  booleanProperty,
+  optionalStringArg,
+  stringProperty,
+} from "../commands/command-args";
 
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { Tab } from "../tabs/tab";
@@ -173,7 +178,7 @@ export function collabCommands(): AnyCommand[] {
         if (!active) {
           return;
         }
-        const login = (args as { login?: string } | undefined)?.login;
+        const login = optionalStringArg("collab.follow", args, "login");
         const { peers } = collabState(active);
         const peer = login ? peers.find((p) => p.state.user.login === login) : peers[0];
         if (!peer) {