@jxsuite/studio 6.1.1 → 8.0.0

package/src/canvas/diff-toolbar.ts

@@ -32,6 +32,7 @@ import {
   setDiffView,
   stepDiff,
 } from "./diff-view";
+import { isString } from "@jxsuite/schema/guards";
 import type { DiffView } from "./diff-view";
 import type { ChangeStep } from "./diff-marks";
 import { panToParentRect } from "./canvas-utils";
@@ -158,7 +159,7 @@ function describeStep(step: ChangeStep, index: number, total: number): string {
  * it is, so a reveal that could not measure leaves a correct toolbar over an unmoved canvas.
  */
 function onStepClick(paneId: string, delta: 1 | -1): void {
-  stepDiffAndReveal(paneId, delta).catch((error: unknown) => {
+  stepDiffAndReveal(paneId, delta).catch((error) => {
     console.warn("stepDiffAndReveal:", error);
   });
 }
@@ -180,8 +181,8 @@ export async function stepDiffAndReveal(paneId: string, delta: 1 | -1): Promise<
   renderDiffToolbar(paneId);
   const step = diffChangeMapOf(paneId)?.steps[landed];
   const { panels } = surfaceForPane(paneId);
-  const original = panels[0]?.canvas as HTMLElement | undefined;
-  const current = panels[1]?.canvas as HTMLElement | undefined;
+  const original = panels[0]?.canvas;
+  const current = panels[1]?.canvas;
   if (!step) {
     return;
   }
@@ -252,10 +253,10 @@ export function diffToolbarView(paneId: string): DiffToolbarView {
   return {
     codeChecked: showing === "code" ? "true" : "false",
     countLabel,
-    degraded: !code && map?.degraded ? "shown" : "hidden",
+    degraded: !code && map.degraded ? "shown" : "hidden",
     nextDisabled: index >= total - 1,
     prevDisabled: index <= 0,
-    rootKeys: !code && map?.rootKeys.length ? "shown" : "hidden",
+    rootKeys: !code && map.rootKeys.length > 0 ? "shown" : "hidden",
     rootKeysTitle: `Changed: ${map?.rootKeys.join(", ") ?? ""}`,
     stepper: total === 0 ? "hidden" : "shown",
     // A file the canvas cannot render arrives with a null map: there is no visual half to offer.
@@ -266,8 +267,8 @@ export function diffToolbarView(paneId: string): DiffToolbarView {
 
 /** The pane a diff verb addresses: named, or the focused one. */
 function paneOfArgs(args: CommandArgValues): string {
-  const { pane } = args as { pane?: unknown };
-  return typeof pane === "string" ? pane : workspace.activePaneId;
+  const { pane } = args;
+  return isString(pane) ? pane : workspace.activePaneId;
 }
 
 const paneProperty = stringProperty("Which pane to act on. Defaults to the focused one.");

package/src/canvas/edit-width-drag.ts

@@ -58,7 +58,7 @@ export function applyEditWidth(surface: CanvasSurface, column: HTMLElement, widt
     return;
   }
   column.style.maxWidth = `${Math.round(width)}px`;
-  if ((tab.session.ui.editZoom ?? 1) !== 1) {
+  if (tab.session.ui.editZoom !== 1) {
     applyEditZoom(surface);
   }
   const rendered = rectOf(column).width || width;
@@ -183,5 +183,8 @@ export function mountEditWidthHandle(
   if (!handle || !column || _wired.has(handle)) {
     return;
   }
+  /* SAFETY: Every caller passes one of the two `jx-split` slots `surfaces/canvas-stage.json` draws
+     beside the column, and a `jx-split` carries the `value`/`min`/`max`/`collapse` share
+     properties `SplitElement` names; `bindSplit` only writes them. */
   _wired.set(handle, bindSplit(handle as SplitElement, editWidthTarget(surface, column, grow)));
 }

package/src/canvas/edit-width.ts

@@ -78,9 +78,7 @@ const _editWidths = new Map<string, EditWidthRecord>();
 
 /** The size breakpoints and base width a tab renders against, site context included. */
 function mediaEntriesOfTab(tab: Tab) {
-  return parseMediaEntries(
-    getEffectiveMedia(tab.doc.document?.$media as Record<string, string> | undefined),
-  );
+  return parseMediaEntries(getEffectiveMedia(tab.doc.document.$media));
 }
 
 /**

package/src/canvas/iframe-channel.ts

@@ -9,6 +9,8 @@
  * plus an in-memory `fakeChannelPair` so cross-frame logic is unit-testable without a live iframe.
  */
 
+import { isNonNullObject } from "@jxsuite/schema/guards";
+
 /**
  * A typed, bidirectional message channel. `TOut` is what this side sends; `TIn` is what it
  * receives. Implementations: a real `postMessage` channel over an `<iframe>` (added with the iframe
@@ -26,8 +28,14 @@ export interface IframeChannel<TOut, TIn> {
 /** Envelope key that tags every cross-frame message so foreign `message` events are ignored. */
 const ENVELOPE = "jx:canvas";
 
-interface PostMessageTarget {
-  postMessage: (message: unknown, targetOrigin: string) => void;
+/** What crosses the frame boundary: the session token beside the typed message it authenticates. */
+export interface CanvasEnvelope<T> {
+  [ENVELOPE]: string;
+  payload: T;
+}
+
+interface PostMessageTarget<TOut> {
+  postMessage: (message: CanvasEnvelope<TOut>, targetOrigin: string) => void;
 }
 
 interface MessageSource {
@@ -46,7 +54,7 @@ interface MessageSource {
  * origin.
  */
 export function postMessageChannel<TOut, TIn>(opts: {
-  target: PostMessageTarget;
+  target: PostMessageTarget<TOut>;
   source: MessageSource;
   targetOrigin: string;
   acceptOrigin: string;
@@ -59,12 +67,15 @@ export function postMessageChannel<TOut, TIn>(opts: {
     if (acceptOrigin !== "*" && event.origin !== acceptOrigin) {
       return;
     }
-    const data = event.data as { [ENVELOPE]?: string; payload?: TIn } | null;
-    if (!data || typeof data !== "object" || data[ENVELOPE] !== token) {
+    const envelope: unknown = event.data;
+    if (!isNonNullObject(envelope) || !(ENVELOPE in envelope) || envelope[ENVELOPE] !== token) {
       return;
     }
+    /* SAFETY: The envelope carries this session's secret token, which only the peer channel holds,
+       and that peer's `post` is typed to send exactly `TIn`; a foreign page cannot forge the token. */
+    const payload = ("payload" in envelope ? envelope.payload : undefined) as TIn;
     for (const handler of handlers) {
-      handler(data.payload as TIn);
+      handler(payload);
     }
   };
   source.addEventListener("message", listener);
@@ -84,19 +95,22 @@ export function postMessageChannel<TOut, TIn>(opts: {
   };
 }
 
+/** Both ends of an in-memory channel, and the controls that deliver what they posted. */
+export interface FakeChannelPair<ParentOut, IframeOut> {
+  parent: IframeChannel<ParentOut, IframeOut>;
+  iframe: IframeChannel<IframeOut, ParentOut>;
+  flush: () => void;
+  /** Number of messages waiting to be delivered (both directions). */
+  pending: () => number;
+}
+
 /**
  * Two in-memory channels wired to each other for tests. A message `parent.post(x)` is delivered to
  * the `iframe` side's handlers (and vice versa) only when `flush()` is called — so tests drive the
  * inherently-async postMessage ordering deterministically. Messages posted _during_ a flush are
  * queued for the next flush, never delivered re-entrantly.
  */
-export function fakeChannelPair<ParentOut, IframeOut>(): {
-  parent: IframeChannel<ParentOut, IframeOut>;
-  iframe: IframeChannel<IframeOut, ParentOut>;
-  flush: () => void;
-  /** Number of messages waiting to be delivered (both directions). */
-  pending: () => number;
-} {
+export function fakeChannelPair<ParentOut, IframeOut>(): FakeChannelPair<ParentOut, IframeOut> {
   let toIframe: ParentOut[] = [];
   let toParent: IframeOut[] = [];
   const iframeHandlers = new Set<(m: ParentOut) => void>();

package/src/canvas/iframe-drop.ts

@@ -17,7 +17,7 @@
  */
 
 import { parseJxPath } from "./path-mapping";
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isNonNullObject } from "@jxsuite/schema/guards";
 import { rectOf, elementAtPoint } from "../utils/geometry";
 import { getNodeAtPath, isAncestor, pathsEqual } from "../state";
 import type { DragSrcKind, DropPreview } from "./iframe-protocol";
@@ -46,15 +46,104 @@ const VOID_TAGS = new Set([
   "wbr",
 ]);
 
+/**
+ * Phrasing content (HTML's content model) that is NOT also an embedded or interactive block an
+ * author drops as its own block: text-level elements. Only these may land inside a paragraph. An
+ * image, a video and a component are phrasing by the letter of HTML, but a card dragged from the
+ * Site panel onto a paragraph means "put it here", not "glue it into this sentence": in Markdown
+ * the latter serialises as an inline directive or image stuck to the text.
+ */
+const TEXT_LEVEL_TAGS = new Set([
+  "a",
+  "abbr",
+  "b",
+  "bdi",
+  "bdo",
+  "br",
+  "cite",
+  "code",
+  "data",
+  "del",
+  "dfn",
+  "em",
+  "i",
+  "ins",
+  "kbd",
+  "mark",
+  "q",
+  "s",
+  "samp",
+  "small",
+  "span",
+  "strong",
+  "sub",
+  "sup",
+  "time",
+  "u",
+  "var",
+  "wbr",
+]);
+
+/** Elements whose content model is phrasing only: a block dropped inside one breaks it. */
+const PHRASING_HOSTS = new Set([
+  ...TEXT_LEVEL_TAGS,
+  "button",
+  "dt",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "label",
+  "legend",
+  "p",
+  "pre",
+  "summary",
+]);
+
+/** A node's tag, lower-cased, `div` when it names none. */
+function tagOf(node: JxMutableNode | null | undefined): string {
+  return (displayTagName(node?.tagName) || "div").toLowerCase();
+}
+
+/** Whether the dragged thing is text-level content, which may be placed inside a paragraph. */
+function isTextLevelSource(src: DragSrcKind, shadowDoc: JxMutableNode): boolean {
+  const tag = src.type === "block" ? (src.tag ?? "") : tagOf(getNodeAtPath(shadowDoc, src.path));
+  return TEXT_LEVEL_TAGS.has(tag.toLowerCase());
+}
+
+/**
+ * The outermost phrasing host at or above `el` (the paragraph around a `<strong>`), or null when
+ * `el` is in none. A block is placed beside that host, never inside it.
+ */
+function phrasingHostOf(el: HTMLElement, shadowDoc: JxMutableNode): HTMLElement | null {
+  let host: HTMLElement | null = null;
+  let current: HTMLElement | null = el;
+  while (current) {
+    const path = parseJxPath(current.dataset.jxPath ?? "");
+    if (path.length === 0) {
+      break;
+    }
+    if (PHRASING_HOSTS.has(tagOf(getNodeAtPath(shadowDoc, path)))) {
+      host = current;
+    }
+    current = nearestPathEl(current.parentElement);
+  }
+  return host;
+}
+
 /**
  * Walk up from an element to the nearest ancestor carrying a `data-jx-path`. Refactored out of the
  * `nearestHit` walk (iframe-interaction.ts) to take an element directly so the hit-test adapter can
  * reuse it. Returns null when no addressable node is found.
  */
 function nearestPathEl(start: Element | null): HTMLElement | null {
-  let el = start instanceof Element ? (start as HTMLElement) : null;
+  // Only an `HTMLElement` is ever stamped (`makeStamper` skips every other node), so the walk
+  // Passes over SVG and other foreign elements on its way up.
+  let el = start;
   while (el) {
-    if (el.dataset?.jxPath) {
+    if (el instanceof HTMLElement && el.dataset.jxPath) {
       return el;
     }
     el = el.parentElement;
@@ -94,15 +183,15 @@ export function computeDropInstruction(
   shadowDoc: JxMutableNode,
   src: DragSrcKind,
 ): DropPreview | null {
-  const serialized = targetEl.dataset?.jxPath;
+  const serialized = targetEl.dataset.jxPath;
   if (serialized == null) {
     return null;
   }
-  const targetPath = parseJxPath(serialized) as JxPath;
+  const targetPath = parseJxPath(serialized);
 
   // Root: pick the nearest child edge among the element's element children.
   if (targetPath.length === 0) {
-    const children = [...targetEl.children] as HTMLElement[];
+    const children = [...targetEl.children];
     if (children.length === 0) {
       return canDrop(src, targetPath)
         ? {
@@ -120,11 +209,30 @@ export function computeDropInstruction(
     return null;
   }
 
-  const node = getNodeAtPath(shadowDoc, targetPath) as JxMutableNode | undefined;
+  /* A block over a paragraph (or anything inside one) lands above or below the paragraph: a
+     component or an image nested in a `<p>` is serialised glued to its text. */
+  const host = isTextLevelSource(src, shadowDoc) ? null : phrasingHostOf(targetEl, shadowDoc);
+  if (host) {
+    const hostPath = parseJxPath(host.dataset.jxPath ?? "");
+    if (!canDrop(src, hostPath)) {
+      return null;
+    }
+    const hostRect = rectFor(host);
+    const hostRelY = hostRect.height === 0 ? 0 : (cursorY - hostRect.y) / hostRect.height;
+    return hostRelY < 0.5
+      ? { edge: "top", instruction: "reorder-above", referenceRect: hostRect, targetPath: hostPath }
+      : {
+          edge: "bottom",
+          instruction: "reorder-below",
+          referenceRect: hostRect,
+          targetPath: hostPath,
+        };
+  }
+
+  const node = getNodeAtPath(shadowDoc, targetPath);
   const tag = (displayTagName(node?.tagName) || "div").toLowerCase();
   const hasElementChildren =
-    Array.isArray(node?.children) &&
-    node.children.some((c: unknown) => c != null && typeof c === "object");
+    Array.isArray(node?.children) && node.children.some((c) => isNonNullObject(c));
   const isLeaf = VOID_TAGS.has(tag) || !hasElementChildren;
 
   const rect = rectFor(targetEl);
@@ -150,7 +258,7 @@ export function computeDropInstruction(
  * parentElementPath(slice(0,-2)) / childIndex(at(-1)) read the same parent + index.
  */
 function nearestChildEdge(
-  children: HTMLElement[],
+  children: Element[],
   cursorY: number,
   parentPath: JxPath,
   src: DragSrcKind,
@@ -175,7 +283,7 @@ function nearestChildEdge(
     }
   }
 
-  const childPath = [...parentPath, "children", closestIdx] as JxPath;
+  const childPath: JxPath = [...parentPath, "children", closestIdx];
   if (!canDrop(src, childPath)) {
     return null;
   }
@@ -192,7 +300,7 @@ function canDrop(src: DragSrcKind, targetPath: JxPath): boolean {
   if (src.type !== "tree-node") {
     return true;
   }
-  const srcPath = src.path as JxPath;
+  const srcPath = src.path;
   if (pathsEqual(srcPath, targetPath)) {
     return false;
   }

package/src/canvas/iframe-editable-root.ts

@@ -35,6 +35,7 @@ import {
   toDomPosition,
 } from "./iframe-position";
 import { serializeJxPath } from "./path-mapping";
+import { isFunction } from "@jxsuite/schema/guards";
 import type { DocPos, DocRange, EditablePredicate } from "./iframe-position";
 import type { JxPath } from "../state";
 
@@ -167,6 +168,14 @@ export interface EditableRootHandle {
   isComposing: () => boolean;
 }
 
+/**
+ * Whether an element carries `dataset`. HTML, SVG and MathML elements all mix in
+ * `HTMLOrSVGElement`; an element from any other namespace has no `dataset` at all.
+ */
+function hasDataset(el: Element): el is Element & HTMLOrSVGElement {
+  return "dataset" in el;
+}
+
 /** Wire the editing host on `container`. */
 export function startEditableRoot(
   container: HTMLElement,
@@ -183,13 +192,13 @@ export function startEditableRoot(
     return mode === undefined || mode === "design" || mode === "edit";
   };
 
-  /** Pending idle-commit timer, or 0 when none is armed. */
-  let commitTimer = 0;
+  /** Pending idle-commit timer, or null when none is armed. */
+  let commitTimer: ReturnType<typeof setTimeout> | null = null;
 
   const cancelCommitTick = () => {
-    if (commitTimer) {
+    if (commitTimer !== null) {
       clearTimeout(commitTimer);
-      commitTimer = 0;
+      commitTimer = null;
     }
   };
 
@@ -202,7 +211,7 @@ export function startEditableRoot(
    * idle commit invisible — without it, typing would jump the caret every time you paused.
    */
   const commitTick = () => {
-    commitTimer = 0;
+    commitTimer = null;
     if (!activeEl || !deps.onCommitTick) {
       return;
     }
@@ -233,7 +242,7 @@ export function startEditableRoot(
       return;
     }
     cancelCommitTick();
-    commitTimer = setTimeout(commitTick, deps.commitDelayMs ?? COMMIT_IDLE_MS) as unknown as number;
+    commitTimer = setTimeout(commitTick, deps.commitDelayMs ?? COMMIT_IDLE_MS);
   };
 
   const onCompositionStart = () => {
@@ -349,7 +358,8 @@ export function startEditableRoot(
   const affectedRange = (
     e: InputEvent,
   ): { from: DocPos; to: DocPos; endEl: HTMLElement } | null => {
-    const [target] = typeof e.getTargetRanges === "function" ? e.getTargetRanges() : [];
+    // Happy-dom ships no `getTargetRanges` at all, so the method's presence is probed, not assumed.
+    const [target] = isFunction(e.getTargetRanges) ? e.getTargetRanges() : [];
     const sel = doc.getSelection();
     const useSelection = sel && sel.rangeCount > 0 && (sel.isCollapsed || !target);
     let startNode: Node | null;
@@ -370,8 +380,7 @@ export function startEditableRoot(
     return from && to && endBlock ? { endEl: endBlock.el, from, to } : null;
   };
 
-  const onBeforeInput = (event: Event) => {
-    const e = event as InputEvent;
+  const onBeforeInput = (e: InputEvent) => {
     if (!editingAllowed()) {
       return;
     }
@@ -435,21 +444,25 @@ export function startEditableRoot(
     if (!editingAllowed() || !deps.onPropActivate) {
       return;
     }
-    let el = e.target instanceof Element ? (e.target as HTMLElement) : null;
+    let el = e.target instanceof Element ? e.target : null;
     while (el && el !== container) {
-      if (el.dataset?.jxBoundProp) {
-        if (el !== activeEl) {
+      if (hasDataset(el) && el.dataset.jxBoundProp) {
+        /* SAFETY: The runtime builds SVG and MathML nodes as `createElementNS(...) as HTMLElement`
+           and stamps `data-jx-bound-prop` through that same `HTMLElement`-typed path, so a
+           foreign-namespace prop host already travels downstream as an `HTMLElement`. */
+        const host = el as HTMLElement;
+        if (host !== activeEl) {
           deactivate();
-          if (deps.onPropActivate(el)) {
+          if (deps.onPropActivate(host)) {
             // Adopt the nested host so the caret landing inside it is not read as a block change.
-            activeEl = el;
+            activeEl = host;
             activeKey = null;
           }
         }
         return;
       }
       // A stamped page block first means this is ordinary page DOM, not component internals.
-      if (el.dataset?.jxPath) {
+      if (hasDataset(el) && el.dataset.jxPath) {
         return;
       }
       el = el.parentElement;
@@ -493,7 +506,7 @@ export function startEditableRoot(
       if (composing) {
         return;
       }
-      if (commitTimer) {
+      if (commitTimer !== null) {
         cancelCommitTick();
         commitTick();
       }