@jxsuite/studio 6.1.1 → 8.0.0

package/src/canvas/iframe-inline-edit.ts

@@ -51,11 +51,21 @@ import type {
   SerializableRect,
 } from "./iframe-protocol";
 import type { DocPos } from "./iframe-position";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { JxPath } from "../state";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
+/** The commit a block session posts when its text reaches the document. */
+type EditCommitMsg = Extract<IframeToParent, { kind: "editCommit" }>;
+
+/** The commit a prop-bound session posts for its instance's `$props` value. */
+type EditCommitPropMsg = Extract<IframeToParent, { kind: "editCommitProp" }>;
+
+/** The toolbar commands that toggle an inline tag (every intent but `link` and `insertData`). */
+type InlineFormatCommand = Exclude<ApplyFormatIntent["command"], "link" | "insertData">;
+
 /** Toolbar command → inline tag (mirrors the parent's old `cmdToTag`, now iframe-side). */
-const CMD_TO_TAG: Record<string, string> = {
+const CMD_TO_TAG = {
   bold: "strong",
   code: "code",
   italic: "em",
@@ -63,7 +73,19 @@ const CMD_TO_TAG: Record<string, string> = {
   subscript: "sub",
   superscript: "sup",
   underline: "u",
-};
+} satisfies Record<InlineFormatCommand, string>;
+
+/**
+ * The CSS Custom Highlight API as this realm may or may not provide it. lib.dom declares both
+ * members unconditionally, but happy-dom and non-Chromium engines ship neither.
+ */
+interface HighlightRealm {
+  Highlight?: typeof Highlight;
+  CSS?: { highlights?: HighlightRegistry };
+}
+
+/** The global object, read through the optional shape above so the feature probes stay honest. */
+const highlightRealm: HighlightRealm = globalThis;
 
 /** Inline tags whose active state the snapshot reports (everything except `a`, handled via link). */
 const ACTIVE_TAG_PROBES = ["strong", "em", "u", "del", "sub", "sup", "code"];
@@ -125,19 +147,19 @@ function deliveredOutsideProps(node: JxMutableNode | undefined, prop: string): b
   if (!node) {
     return false;
   }
-  const attrs = node.attributes as Record<string, unknown> | undefined;
+  const attrs = node.attributes;
   if (attrs) {
     if (attrs[`props.${prop}`] !== undefined) {
       return true;
     }
     const reflected = new Set([prop.toLowerCase(), camelToKebab(prop).toLowerCase()]);
-    for (const [name, val] of Object.entries(attrs)) {
-      if (val !== undefined && reflected.has(name.toLowerCase())) {
+    for (const name of Object.keys(attrs)) {
+      if (attrs[name] !== undefined && reflected.has(name.toLowerCase())) {
         return true;
       }
     }
     const payload = attrs["data-jx-props"];
-    if (typeof payload === "string" && payloadNames(payload, prop)) {
+    if (isString(payload) && payloadNames(payload, prop)) {
       return true;
     }
   }
@@ -145,14 +167,14 @@ function deliveredOutsideProps(node: JxMutableNode | undefined, prop: string): b
   if (RESERVED_KEYS.has(prop) || prop.startsWith("$")) {
     return false;
   }
-  return (node as Record<string, unknown>)[prop] !== undefined;
+  return node[prop] !== undefined;
 }
 
 /** Whether a `data-jx-props` JSON payload carries `prop`. Unparseable payloads deliver nothing. */
 function payloadNames(payload: string, prop: string): boolean {
   try {
     const parsed: unknown = JSON.parse(payload);
-    return typeof parsed === "object" && parsed !== null && prop in parsed;
+    return isNonNullObject(parsed) && prop in parsed;
   } catch {
     return false;
   }
@@ -238,11 +260,8 @@ export function startIframeInlineEdit(
    * `Highlight`/`CSS.highlights`, so this is a silent no-op there (and in non-Chromium engines).
    */
   const updateHighlight = () => {
-    const HighlightCtor = (globalThis as { Highlight?: unknown }).Highlight as
-      | (new (range: Range) => unknown)
-      | undefined;
-    const highlights = (globalThis.CSS as unknown as { highlights?: Map<string, unknown> })
-      ?.highlights;
+    const HighlightCtor = highlightRealm.Highlight;
+    const highlights = highlightRealm.CSS?.highlights;
     if (!HighlightCtor || !highlights) {
       return;
     }
@@ -256,9 +275,7 @@ export function startIframeInlineEdit(
 
   /** Tear down the Custom Highlight (on teardown / real editEnd). */
   const clearHighlight = () => {
-    const highlights = (globalThis.CSS as unknown as { highlights?: Map<string, unknown> })
-      ?.highlights;
-    highlights?.delete(HIGHLIGHT_NAME);
+    highlightRealm.CSS?.highlights?.delete(HIGHLIGHT_NAME);
   };
 
   /**
@@ -321,13 +338,11 @@ export function startIframeInlineEdit(
       // Optional, so omitting it keeps the message shape unchanged for every non-tick commit.
       onCommit: (p, children, textContent, inPlace) => {
         inputAnnounced = false;
-        channel.post({
-          children,
-          kind: "editCommit",
-          path: p,
-          textContent,
-          ...(inPlace ? { inPlace: true } : {}),
-        });
+        const commit: EditCommitMsg = { children, kind: "editCommit", path: p, textContent };
+        if (inPlace) {
+          commit.inPlace = true;
+        }
+        channel.post(commit);
       },
       onEnd: () => {
         clearHighlight();
@@ -356,11 +371,11 @@ export function startIframeInlineEdit(
     if (!shadowDoc) {
       return true;
     }
-    const node = getNodeAtPath(shadowDoc, hostPath) as JxMutableNode | undefined;
+    const node = getNodeAtPath(shadowDoc, hostPath);
     if (deliveredOutsideProps(node, prop)) {
       return false;
     }
-    const raw = (node?.$props as Record<string, unknown> | undefined)?.[prop];
+    const raw = node?.$props?.[prop];
     if (raw == null) {
       return true; // Unset — editing ADDS the prop, overriding the definition default.
     }
@@ -371,7 +386,7 @@ export function startIframeInlineEdit(
      * Objects were already excluded; the scalar cases were not, and are the ones a component
      * actually declares. They stay editable in the properties panel, which knows their type.
      */
-    if (typeof raw !== "string") {
+    if (!isString(raw)) {
       return false;
     }
     return !raw.includes("${");
@@ -390,13 +405,16 @@ export function startIframeInlineEdit(
       {
         onCommit: (p, _children, textContent, inPlace) => {
           inputAnnounced = false;
-          channel.post({
+          const commit: EditCommitPropMsg = {
             kind: "editCommitProp",
             path: p,
             prop,
             value: textContent ?? "",
-            ...(inPlace ? { inPlace: true } : {}),
-          });
+          };
+          if (inPlace) {
+            commit.inPlace = true;
+          }
+          channel.post(commit);
         },
         onEnd: () => {
           clearHighlight();
@@ -519,6 +537,7 @@ export function startIframeInlineEdit(
     if (start === -1 || end === -1 || end <= start) {
       return false;
     }
+    // SAFETY: `blocksInOrder` selects `[data-jx-path]`, so every block it returns carries the key.
     const between = blocks
       .slice(start + 1, end)
       .map((el) => parseJxPath(el.dataset.jxPath as string));
@@ -573,7 +592,7 @@ export function startIframeInlineEdit(
      owns what a slash MEANS (start of a block or after a space; anywhere else it is punctuation).
      The matching `input` half re-filters the open menu, for the same reason: a contenteditable's
      `input` targets its host, not the block the caret happens to be in. */
-  const onSlashKey = (e: Event) => handleSlashTrigger(e as KeyboardEvent);
+  const onSlashKey = (e: KeyboardEvent) => handleSlashTrigger(e);
   const onSlashInput = () => {
     if (isSlashActive()) {
       refreshSlashMenu();

package/src/canvas/iframe-insert.ts

@@ -17,6 +17,7 @@
  * (happy-dom's `elementFromPoint` returns null) and lives in iframe-interaction.
  */
 
+import { isNumber } from "@jxsuite/schema/guards";
 import { parseJxPath } from "./path-mapping";
 import { rectOf } from "../utils/geometry";
 import { childIndex, parentElementPath } from "../state";
@@ -48,7 +49,7 @@ function isRowLayout(parent: HTMLElement): boolean {
   const isGrid = display === "grid" || display === "inline-grid";
   return (
     (isFlex && style.flexDirection.startsWith("row")) ||
-    (isGrid && (style.gridAutoFlow ?? "").startsWith("column"))
+    (isGrid && style.gridAutoFlow.startsWith("column"))
   );
 }
 
@@ -78,11 +79,11 @@ export function computeInsertZones(
   shadowDoc: JxMutableNode,
 ): InsertZone[] | null {
   void shadowDoc;
-  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);
 
   // Empty container: one centered "+" that inserts as the container's first child.
   if (targetEl.classList.contains(EMPTY_CONTAINER_CLASS)) {
@@ -99,7 +100,7 @@ export function computeInsertZones(
     return null;
   }
   const childIdx = childIndex(targetPath);
-  if (typeof childIdx !== "number") {
+  if (!isNumber(childIdx)) {
     return null;
   }
 

package/src/canvas/iframe-interaction.ts

@@ -7,6 +7,7 @@
  */
 
 import { jxPathSelector, parseJxPath, serializeJxPath } from "./path-mapping";
+import { isFunction } from "@jxsuite/schema/guards";
 import { rectOf } from "../utils/geometry";
 import { computeInsertZones, insertZonesKey } from "./iframe-insert";
 import { getActiveElement, isEditing } from "../editor/inline-edit";
@@ -32,9 +33,10 @@ function isCanvasLeave(e: Event, doc: Document): boolean {
 
 /** Walk up from an element to the nearest ancestor carrying a `data-jx-path`; null if none. */
 function nearestPathEl(start: Element | null): HTMLElement | null {
-  let el = start instanceof Element ? (start as HTMLElement) : null;
+  let el = start instanceof Element ? start : null;
   while (el) {
-    if (el.dataset?.jxPath) {
+    // Only HTML elements are stamped (`makeStamper` skips everything else), so only they can match.
+    if (el instanceof HTMLElement && el.dataset.jxPath) {
       return el;
     }
     el = el.parentElement;
@@ -57,6 +59,7 @@ export function nearestHit(target: EventTarget | null): NodeHit | null {
   if (!el) {
     return null;
   }
+  // SAFETY: nearestPathEl returns only an element whose `data-jx-path` is a non-empty string.
   return measureHit(el, el.dataset.jxPath as string);
 }
 
@@ -75,8 +78,9 @@ export function nearestHit(target: EventTarget | null): NodeHit | null {
  * from a node that is on screen is a worse failure than drawing one for a node that is not.
  */
 function isRendered(el: Element): boolean {
-  const check = (el as { checkVisibility?: (o?: object) => boolean }).checkVisibility;
-  return typeof check === "function" ? check.call(el, { checkVisibilityCSS: true }) : true;
+  // Absent on engines that predate it, whatever lib.dom says.
+  const check: Element["checkVisibility"] | undefined = el.checkVisibility;
+  return isFunction(check) ? check.call(el, { checkVisibilityCSS: true }) : true;
 }
 
 /**
@@ -92,10 +96,7 @@ function isRendered(el: Element): boolean {
  * The serialized path is the same string the renderer stamps, so a stored selection path
  * round-trips back to its element.
  */
-export function measureHits(
-  paths: (string | number)[][],
-  doc: Document = document,
-): { hits: NodeHit[]; hidden: (string | number)[][] } {
+export function measureHits(paths: (string | number)[][], doc: Document = document) {
   const hits: NodeHit[] = [];
   const hidden: (string | number)[][] = [];
   for (const path of paths) {
@@ -119,8 +120,15 @@ export function measureHits(
  * {@link file://./iframe-drop.ts}'s `startGrabDetector` receives its deps rather than reaching for
  * module state.
  */
+type InvokerAction = Extract<IframeToParent, { kind: "popoverTargetClick" }>["action"];
+
 /** The three `popovertargetaction` keywords. Anything else falls back to the HTML default. */
-const INVOKER_ACTIONS = new Set(["toggle", "show", "hide"]);
+const INVOKER_ACTIONS = new Set<string>(["toggle", "show", "hide"] satisfies InvokerAction[]);
+
+/** Whether an attribute value is one of the {@link INVOKER_ACTIONS} keywords. */
+function isInvokerAction(value: string): value is InvokerAction {
+  return INVOKER_ACTIONS.has(value);
+}
 
 /**
  * Report an invoker click, when the click landed on one and it names an addressable popover.
@@ -152,14 +160,14 @@ function postPopoverInvoke(
      need escaping — a rule this file already keeps in exactly one place (`jxPathSelector`) and
      should not gain a second spelling of. The set scanned is the addressable POPOVERS, which is
      also the set the answer has to come from, so the scan is the test. */
-  const panels = invoker.ownerDocument.querySelectorAll("[data-jx-popover]");
-  const panel = [...panels].find((el) => el.id === id) as HTMLElement | undefined;
+  const panels = invoker.ownerDocument.querySelectorAll<HTMLElement>("[data-jx-popover]");
+  const panel = [...panels].find((el) => el.id === id);
   const serialized = panel?.dataset.jxPath;
   if (!serialized) {
     return;
   }
   const raw = invoker.getAttribute("popovertargetaction") ?? "toggle";
-  const action = INVOKER_ACTIONS.has(raw) ? (raw as "toggle" | "show" | "hide") : "toggle";
+  const action = isInvokerAction(raw) ? raw : "toggle";
   channel.post({ action, kind: "popoverTargetClick", targetPath: parseJxPath(serialized) });
 }
 
@@ -190,10 +198,10 @@ function postCommandInvoke(
   }
   // Scanned, not selected, for the reason `postPopoverInvoke` gives; the addressable overlays are
   // The de-popovered panels and the stamped dialogs.
-  const overlays = invoker.ownerDocument.querySelectorAll(
+  const overlays = invoker.ownerDocument.querySelectorAll<HTMLElement>(
     "[data-jx-popover], dialog[data-jx-path]",
   );
-  const overlay = [...overlays].find((el) => el.id === id) as HTMLElement | undefined;
+  const overlay = [...overlays].find((el) => el.id === id);
   const serialized = overlay?.dataset.jxPath;
   if (!serialized) {
     return;
@@ -270,7 +278,7 @@ export function startInteraction(
     channel.post({ kind: "paneFocus" });
   };
 
-  const onClick = (e: Event) => {
+  const onClick = (e: MouseEvent) => {
     /*
      * Preview keeps anchors live, so a click would navigate this iframe and destroy the render (and
      * the editing session with it). Report the intent so the parent can open the real page in a real
@@ -303,9 +311,8 @@ export function startInteraction(
       // Ctrl/Cmd is the accumulate gesture (studio-ui-guidelines.md §8.1). The iframe reports the
       // Modifier and nothing else — it holds no selection state, so what a modified click MEANS is
       // The parent's to decide, exactly as the unmodified click already was.
-      const mouse = e as MouseEvent;
       channel.post({
-        additive: mouse.ctrlKey === true || mouse.metaKey === true,
+        additive: e.ctrlKey === true || e.metaKey === true,
         hit,
         kind: "hit",
       });
@@ -394,11 +401,10 @@ export function startInteraction(
     reportInsertZones(target, { x: moveX, y: moveY });
   };
 
-  const onMove = (e: Event) => {
-    const pe = e as PointerEvent;
+  const onMove = (e: PointerEvent) => {
     moveTarget = e.target;
-    moveX = pe.clientX;
-    moveY = pe.clientY;
+    moveX = e.clientX;
+    moveY = e.clientY;
     if (movePending) {
       return;
     }
@@ -415,8 +421,7 @@ export function startInteraction(
     }
   };
 
-  const onContextMenu = (e: Event) => {
-    const me = e as MouseEvent;
+  const onContextMenu = (e: MouseEvent) => {
     // Preview keeps the NATIVE menu: the Jx element menu's verbs (duplicate, delete, paste, wrap)
     // Are document edits, and preview does not edit. Copy Link Address does what it says instead.
     if (isPreview()) {
@@ -447,8 +452,8 @@ export function startInteraction(
     channel.post({
       kind: "contextMenu",
       path: hit.path,
-      x: me.clientX,
-      y: me.clientY,
+      x: e.clientX,
+      y: e.clientY,
     });
   };
 

package/src/canvas/iframe-keys.ts

@@ -56,6 +56,17 @@ import type { IframeToParent, ParentToIframe, SerializedKey, SyncedChord } from
  */
 export const FRAME_KEY_SCOPES = ["caret", "canvas", "global"] as const;
 
+/**
+ * Commands whose chords the frame never forwards, though their scope is on its stack.
+ *
+ * `pane.backToHome` holds bare Escape in the global scope, and it applies only to a view opened
+ * beside a strip-less workspace's home (a media viewer, a comparison, `project.json` as Code), none
+ * of which is a canvas frame. Projected into the table, it made every frame cancel Escape in
+ * Preview and mid-sentence too, where nothing else claims it, so an author's own `<dialog>` or
+ * popover in the rendered page could no longer be dismissed with it.
+ */
+export const HOST_ONLY_COMMANDS: ReadonlySet<string> = new Set(["pane.backToHome"]);
+
 /** The scope stack a caret session is in — app chords still fire, element-level ones do not. */
 const CARET_STACK = ["caret", "global"] as const;
 /** The stack with a selection but no caret: structural verbs are live. */

package/src/canvas/iframe-overlay.ts

@@ -47,7 +47,7 @@ export function parentCursorToIframe(
   cursor: { x: number; y: number },
   iframeRect: { left: number; top: number },
   scale = 1,
-): { x: number; y: number } {
+) {
   return {
     x: (cursor.x - iframeRect.left) / scale,
     y: (cursor.y - iframeRect.top) / scale,

package/src/canvas/iframe-patch.ts

@@ -15,17 +15,19 @@
  */
 
 import { reapplyStyle } from "@jxsuite/runtime";
-import { getNodeAtPath } from "../state";
+import { isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
 import { applyDocOpToDoc } from "../tabs/doc-op-apply";
 import { parseJxPath, serializeJxPath } from "./path-mapping";
 import { disposeSubtree, renderSubtreeIframe } from "./iframe-subtree";
 import {
   computeEmptyPlaceholderClass,
   EMPTY_PLACEHOLDER_CLASSES,
+  isRowBound,
   templateToEditDisplay,
 } from "../utils/edit-display";
 import type { IframeRenderCtx } from "./iframe-render";
-import type { WireDocOp } from "./iframe-protocol";
+import type { JxDocOp } from "../tabs/patch-ops";
 import type { JxPath } from "../state";
 import type { JxMutableNode, JxStyle } from "@jxsuite/schema/types";
 
@@ -36,7 +38,7 @@ import type { JxMutableNode, JxStyle } from "@jxsuite/schema/types";
  */
 export function applyIframePatch(
   shadowDoc: JxMutableNode,
-  forwardOps: WireDocOp[],
+  forwardOps: JxDocOp[],
   container: HTMLElement,
   ctx?: IframeRenderCtx,
   echoPaths?: JxPath[],
@@ -98,7 +100,7 @@ function requireCtx(ctx: IframeRenderCtx | undefined): IframeRenderCtx {
 
 function applyOpToDom(
   doc: JxMutableNode,
-  op: WireDocOp,
+  op: JxDocOp,
   container: HTMLElement,
   ctx: IframeRenderCtx | undefined,
 ): void {
@@ -138,7 +140,7 @@ function applyOpToDom(
       return;
     }
     default: {
-      // The WireDocOp union is exhaustively handled above; this guards a future op kind.
+      // The JxDocOp union is exhaustively handled above; this guards a future op kind.
       throw new Error(`iframe-patch-unsupported-op:${JSON.stringify(op)}`);
     }
   }
@@ -292,7 +294,7 @@ function remapChildPaths(
       continue;
     }
     const idx = p[depth + 1];
-    if (typeof idx !== "number" || idx < fromIndex) {
+    if (!isNumber(idx) || idx < fromIndex) {
       continue;
     }
     if (!parentPath.every((seg, i) => p[i] === seg)) {
@@ -338,8 +340,10 @@ function patchStyle(
 ): void {
   const el = requireElement(container, path);
   const node = getNodeAtPath(doc, path);
-  const mediaQueries = (ctx?.defs?.["$media"] as Record<string, string> | undefined) ?? {};
-  reapplyStyle(el, editModeStyle(node?.style), mediaQueries);
+  /* SAFETY: buildScope writes `$media` only from the document's own `$media` map or the runtime's
+   * root media map, both Record<string, string>, and the host scope may not supply the key. */
+  const mediaQueries = (ctx?.defs["$media"] as Record<string, string> | undefined) ?? {};
+  reapplyStyle(el, editModeStyle(node?.style), mediaQueries, ctx?.defs ?? {});
 }
 
 /** Write the node's display text, syncing the empty-placeholder class like the full render. */
@@ -368,24 +372,24 @@ function findElement(container: HTMLElement, path: (string | number)[]): HTMLEle
 }
 
 /**
- * Edit-mode style transform — mirrors prepareForEditMode (and the legacy patcher's editModeStyle):
- * top-level template-string values are blanked so no reactive bindings are created for them.
+ * Edit-mode style transform — mirrors prepareForEditMode: bindings are live and resolve against the
+ * render's scope, except a declaration that reads the repeater row, which the perimeter cannot
+ * supply and so is omitted.
  */
 function editModeStyle(style: JxStyle | undefined): JxStyle | undefined {
-  if (!style || typeof style !== "object") {
+  if (!style || !isNonNullObject(style)) {
     return undefined;
   }
-  const out: Record<string, unknown> = {};
+  const out: JxStyle = {};
   for (const [k, v] of Object.entries(style)) {
-    /* OMITTED, not blanked. It used to be written as `""`, which was a silent no-op while a
-       declaration went to `el.style` and is a malformed declaration now that it goes into a rule.
-       Dropping the key is what blanking always meant: the property falls back to the cascade. */
-    if (typeof v === "string" && v.includes("${")) {
+    /* OMITTED, not blanked: `color: ` is a malformed declaration in a rule, and an absent one lets
+       the cascade answer, which is what blanking always meant. */
+    if (isRowBound(v)) {
       continue;
     }
     out[k] = v;
   }
-  return out as JxStyle;
+  return out;
 }
 
 /**
@@ -393,15 +397,15 @@ function editModeStyle(style: JxStyle | undefined): JxStyle | undefined {
  * template-string and $ref display rules (and the legacy patcher's textDisplayValue).
  */
 function textDisplayValue(node: JxMutableNode | undefined): string {
-  const v = (node as { textContent?: unknown } | undefined)?.textContent;
+  const v = node?.textContent;
   if (v == null) {
     return "";
   }
-  if (typeof v === "string") {
+  if (isString(v)) {
     return v.includes("${") ? templateToEditDisplay(v) : v;
   }
-  if (typeof v === "object" && (v as Record<string, unknown>).$ref) {
-    const ref = String((v as Record<string, unknown>).$ref);
+  if (isNonNullObject(v) && v.$ref) {
+    const ref = String(v.$ref);
     const label = ref.startsWith("#/state/") ? ref.slice(8) : ref;
     return `{${label}}`;
   }

package/src/canvas/iframe-position.ts

@@ -33,6 +33,12 @@ export interface DocRange {
   head: DocPos;
 }
 
+/** A live DOM caret position: a node and an offset into it, as a Selection endpoint carries. */
+export interface DomPosition {
+  node: Node;
+  offset: number;
+}
+
 /** Whether an element is a block the caret may live inside. Injected so the editable set is policy. */
 export type EditablePredicate = (el: HTMLElement) => boolean;
 
@@ -91,7 +97,7 @@ export function elementForPath(container: HTMLElement, path: JxPath): HTMLElemen
 
 /** The block's rendered text length — the maximum valid offset within it. */
 export function blockTextLength(block: HTMLElement): number {
-  return block.textContent?.length ?? 0;
+  return block.textContent.length;
 }
 
 /**
@@ -126,11 +132,12 @@ export function offsetOf(block: HTMLElement, node: Node, offset: number): number
  * every offset-based editor carries at a line break, and it is invisible for the paths that use
  * this (caret restore after a patch, and block-boundary edits, which clamp to 0 / length anyway).
  */
-export function domPositionAt(block: HTMLElement, offset: number): { node: Node; offset: number } {
+export function domPositionAt(block: HTMLElement, offset: number): DomPosition {
   const target = Math.max(0, Math.min(offset, blockTextLength(block)));
   const walker = block.ownerDocument.createTreeWalker(block, NodeFilter.SHOW_TEXT);
   let seen = 0;
   let last: Text | null = null;
+  // SAFETY: the walker was created with NodeFilter.SHOW_TEXT, so every node it yields is a Text.
   let current = walker.nextNode() as Text | null;
   while (current) {
     const len = current.length;
@@ -139,6 +146,7 @@ export function domPositionAt(block: HTMLElement, offset: number): { node: Node;
     }
     seen += len;
     last = current;
+    // SAFETY: the same SHOW_TEXT walker as above, so the next node is a Text or the walk's end.
     current = walker.nextNode() as Text | null;
   }
   // No text node reaches the target: either the block has no text at all (caret goes to the element
@@ -169,10 +177,7 @@ export function toDocPos(
  * block whose text shrank under a remote edit lands at the block's new end instead of being
  * dropped.
  */
-export function toDomPosition(
-  container: HTMLElement,
-  pos: DocPos,
-): { node: Node; offset: number } | null {
+export function toDomPosition(container: HTMLElement, pos: DocPos): DomPosition | null {
   const el = elementForPath(container, pos.path);
   return el ? domPositionAt(el, pos.offset) : null;
 }
@@ -246,6 +251,7 @@ export function adjacentBlock(
   const key = serializeJxPath(path);
   const index = blocks.findIndex((el) => el.dataset.jxPath === key);
   const neighbour = index === -1 ? undefined : blocks[index + direction];
+  // SAFETY: blocksInOrder collects only elements matching `[data-jx-path]`, so the attribute is set.
   return neighbour
     ? { el: neighbour, path: parseJxPath(neighbour.dataset.jxPath as string) }
     : null;