@jxsuite/studio 6.1.1 → 8.0.0

package/src/editor/inline-format.ts

@@ -1,4 +1,5 @@
 /// <reference lib="dom" />
+/// <reference lib="dom.iterable" />
 /**
  * Inline-format.js — Inline formatting engine for contenteditable editing
  *
@@ -22,6 +23,25 @@ const FORMAT_TAGS = new Set([
   "span",
 ]);
 
+/** Whether `node` is an element. Decided by node type, so it holds for a node of any realm. */
+function isElementNode(node: Node): node is Element {
+  return node.nodeType === Node.ELEMENT_NODE;
+}
+
+/** Whether `node` is a text node (`CDATASection` has its own node type and is excluded). */
+function isTextNode(node: Node): node is Text {
+  return node.nodeType === Node.TEXT_NODE;
+}
+
+/** One edge-whitespace move {@link liftEdgeWhitespace} applies after its scan. */
+interface EdgeWhitespaceLift {
+  type: "lift-leading" | "lift-trailing";
+  el: Element;
+  /** The wrapper's first (leading) or last (trailing) child, whose edge whitespace moves out. */
+  text: Text;
+  ws: string;
+}
+
 /**
  * Check whether `tag` is currently active on both ends of the selection. Walks from anchor and
  * focus nodes up to editableRoot looking for the tag. Returns false if selection is outside
@@ -59,10 +79,7 @@ export function isTagActiveInSelection(tag: string, editableRoot: HTMLElement |
   const hasTag = (node: Node | null) => {
     let current = node;
     while (current && current !== editableRoot) {
-      if (
-        current.nodeType === Node.ELEMENT_NODE &&
-        (current as Element).tagName.toLowerCase() === tag
-      ) {
+      if (isElementNode(current) && current.tagName.toLowerCase() === tag) {
         return true;
       }
       current = current.parentNode;
@@ -121,20 +138,11 @@ export function toggleInlineFormat(tag: string, editableRoot: HTMLElement | null
  */
 function findIntersectingElements(tag: string, range: Range, root: HTMLElement) {
   const matches: Element[] = [];
-  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, {
-    /**
-     * @param {Node} node
-     * @returns {number}
-     */
-    acceptNode(node: Node) {
-      if ((node as Element).tagName.toLowerCase() === tag && range.intersectsNode(node)) {
-        return NodeFilter.FILTER_ACCEPT;
-      }
-      return NodeFilter.FILTER_SKIP;
-    },
-  });
-  while (walker.nextNode()) {
-    matches.push(walker.currentNode as Element);
+  // Every descendant element, in document order: the same set a SHOW_ELEMENT tree walk visits.
+  for (const el of root.querySelectorAll("*")) {
+    if (el.tagName.toLowerCase() === tag && range.intersectsNode(el)) {
+      matches.push(el);
+    }
   }
   return matches;
 }
@@ -343,21 +351,19 @@ export function normalizeInlineContent(root: HTMLElement | null) {
  */
 function mergeAdjacentSiblings(root: HTMLElement) {
   let changed = false;
-  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
   const toMerge: [Element, Element][] = [];
 
   // Collect pairs first to avoid mutation during walk
-  while (walker.nextNode()) {
-    const el = walker.currentNode as Element;
+  for (const el of root.querySelectorAll("*")) {
     const next = el.nextSibling;
     if (
       next &&
-      next.nodeType === Node.ELEMENT_NODE &&
-      (next as Element).tagName === el.tagName &&
+      isElementNode(next) &&
+      next.tagName === el.tagName &&
       FORMAT_TAGS.has(el.tagName.toLowerCase()) &&
-      attributesMatch(el, next as Element)
+      attributesMatch(el, next)
     ) {
-      toMerge.push([el, next as Element]);
+      toMerge.push([el, next]);
     }
   }
 
@@ -383,27 +389,31 @@ function mergeAdjacentSiblings(root: HTMLElement) {
  */
 function collapseRedundantNesting(root: HTMLElement) {
   let changed = false;
-  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
   const toCollapse: Element[] = [];
 
-  while (walker.nextNode()) {
-    const el = walker.currentNode as Element;
+  for (const el of root.querySelectorAll("*")) {
     if (!FORMAT_TAGS.has(el.tagName.toLowerCase())) {
       continue;
     }
     // Check if only child is an element with the same tag
+    const only = el.firstChild;
     if (
       el.childNodes.length === 1 &&
-      el.firstChild !== null &&
-      el.firstChild.nodeType === Node.ELEMENT_NODE &&
-      (el.firstChild as Element).tagName === el.tagName
+      only !== null &&
+      isElementNode(only) &&
+      only.tagName === el.tagName
     ) {
       toCollapse.push(el);
     }
   }
 
   for (const el of toCollapse) {
-    const inner = el.firstChild as Element;
+    const inner = el.firstChild;
+    if (inner === null) {
+      /* Three or more nested identical wrappers: collapsing the outer pair moved this wrapper's only
+         child out, leaving it empty. That has always failed here, and is kept rather than changed. */
+      throw new TypeError("collapseRedundantNesting: an earlier collapse emptied this wrapper");
+    }
     // Replace outer with inner's children
     while (inner.firstChild) {
       inner.before(inner.firstChild);
@@ -422,11 +432,9 @@ function collapseRedundantNesting(root: HTMLElement) {
  */
 function removeEmptyInlines(root: HTMLElement) {
   let changed = false;
-  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
   const toRemove: Element[] = [];
 
-  while (walker.nextNode()) {
-    const el = walker.currentNode as Element;
+  for (const el of root.querySelectorAll("*")) {
     if (!FORMAT_TAGS.has(el.tagName.toLowerCase())) {
       continue;
     }
@@ -451,12 +459,9 @@ function removeEmptyInlines(root: HTMLElement) {
  */
 function liftEdgeWhitespace(root: HTMLElement) {
   let changed = false;
-  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
-  /** @type {{ type: string; el: Element; ws: string }[]} */
-  const ops = [];
+  const ops: EdgeWhitespaceLift[] = [];
 
-  while (walker.nextNode()) {
-    const el = walker.currentNode as Element;
+  for (const el of root.querySelectorAll("*")) {
     if (!FORMAT_TAGS.has(el.tagName.toLowerCase())) {
       continue;
     }
@@ -465,36 +470,36 @@ function liftEdgeWhitespace(root: HTMLElement) {
     }
 
     const first = el.firstChild;
-    if (first && first.nodeType === Node.TEXT_NODE) {
-      const text = first.textContent ?? "";
+    if (first && isTextNode(first)) {
+      const text = first.textContent;
       const m = text.match(/^(\s+)/);
       if (m && text.length > m[1]!.length) {
-        ops.push({ el, type: "lift-leading", ws: m[1]! });
+        ops.push({ el, text: first, type: "lift-leading", ws: m[1]! });
       }
     }
 
     const last = el.lastChild;
-    if (last && last.nodeType === Node.TEXT_NODE && last !== first) {
-      const text = last.textContent ?? "";
+    if (last && isTextNode(last) && last !== first) {
+      const text = last.textContent;
       const m = text.match(/(\s+)$/);
       if (m && text.length > m[1]!.length) {
-        ops.push({ el, type: "lift-trailing", ws: m[1]! });
+        ops.push({ el, text: last, type: "lift-trailing", ws: m[1]! });
       }
     }
   }
 
+  /* Each recorded text node is still its wrapper's edge child when its move runs: a move only edits
+     a text node's data and inserts a sibling OUTSIDE its own wrapper, and a wrapper whose edge child
+     is an element (the only place a nested move could insert) never recorded a move on that edge. */
   for (const op of ops) {
     if (op.type === "lift-leading") {
-      const firstChild = op.el.firstChild as Text;
-      firstChild.textContent = (firstChild.textContent ?? "").slice(op.ws.length);
+      op.text.textContent = op.text.textContent.slice(op.ws.length);
       op.el.parentNode?.insertBefore(document.createTextNode(op.ws), op.el);
-      changed = true;
-    } else if (op.type === "lift-trailing") {
-      const lastChild = op.el.lastChild as Text;
-      lastChild.textContent = (lastChild.textContent ?? "").slice(0, -op.ws.length);
+    } else {
+      op.text.textContent = op.text.textContent.slice(0, -op.ws.length);
       op.el.parentNode?.insertBefore(document.createTextNode(op.ws), op.el.nextSibling);
-      changed = true;
     }
+    changed = true;
   }
   return changed;
 }
@@ -508,11 +513,9 @@ function liftEdgeWhitespace(root: HTMLElement) {
  */
 function unwrapBareSpans(root: HTMLElement) {
   let changed = false;
-  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
   const toUnwrap: Element[] = [];
 
-  while (walker.nextNode()) {
-    const el = walker.currentNode as Element;
+  for (const el of root.querySelectorAll("*")) {
     if (el.tagName.toLowerCase() !== "span") {
       continue;
     }

package/src/editor/inline-link.ts

@@ -8,32 +8,57 @@
  * it here (Phase 4b-2).
  *
  * `document.execCommand` is uncoverable under happy-dom (no implementation), so it is wrapped in a
- * one-line shim {@link exec} that the branch logic calls; tests stub `document.execCommand` and
- * assert at the stub level (documented as stub-level, not behavioral).
+ * one-line shim {@link execEditingCommand} that the branch logic calls; tests stub
+ * `document.execCommand` and assert at the stub level (documented as stub-level, not behavioral).
  */
 
 import { normalizeInlineContent } from "./inline-format";
 
-/** The one uncoverable call, isolated so the surrounding branch logic stays unit-testable. */
-const exec = (cmd: string, val?: string): boolean => document.execCommand(cmd, false, val);
+/**
+ * The one uncoverable call, isolated so the surrounding branch logic stays unit-testable, and the
+ * one place Studio reaches `document.execCommand`. It is deprecated, and NOT kept for the native
+ * undo stack: Studio owns history (`edit.undo` is forwarded out of the frame and a `historyUndo`
+ * `beforeinput` is rejected, studio.md §8.2.1). It is kept because it is the only script entry into
+ * the browser's editing engine, which a Range rewrite would not reproduce: `insertText` rebalances
+ * whitespace into ` ` runs (and back) around the caret, and `createLink` splits the anchor at
+ * inline-formatting boundaries it only partly covers.
+ */
+export const execEditingCommand = (cmd: string, val?: string): boolean =>
+  // oxlint-disable-next-line typescript/no-deprecated -- no successor API exists: execCommand is the only script entry into the browser's editing engine (whitespace rebalancing, anchor splitting), see the doc comment above
+  document.execCommand(cmd, false, val);
+
+/** The link the selection sits in, as the format toolbar's Link field shows it. */
+export interface LinkState {
+  /** Whether the selection anchor is inside an `<a>`. */
+  active: boolean;
+  /** The author-entered URL of that `<a>`, or null when there is none. */
+  href: string | null;
+}
+
+/**
+ * Whether `node` is an `<a>` element. Decided by node type and name rather than `instanceof`, so it
+ * holds for nodes of another realm; for an element, `nodeName` is its tag name.
+ */
+function isAnchorNode(node: Node): node is HTMLAnchorElement | SVGAElement {
+  return node.nodeType === Node.ELEMENT_NODE && node.nodeName.toLowerCase() === "a";
+}
 
 /**
  * Read the link state of the current selection relative to `root`: walk the selection's anchor node
  * up to `root` looking for an `<a>`. Returns the author-entered `href` attribute (NOT the resolved
  * `.href` property), so relative/templated URLs round-trip unchanged.
  */
-export function linkStateForSelection(root: HTMLElement): { active: boolean; href: string | null } {
+export function linkStateForSelection(root: HTMLElement): LinkState {
   const sel = window.getSelection();
   if (!sel || !sel.rangeCount) {
     return { active: false, href: null };
   }
   let node: Node | null = sel.anchorNode;
   while (node && node !== root) {
-    if (node.nodeType === Node.ELEMENT_NODE && (node as Element).tagName.toLowerCase() === "a") {
+    if (isAnchorNode(node)) {
       // Design/edit renders anchors de-linked, with the URL on `data-jx-href` — so the toolbar's
       // Link field must read that first or it shows an empty URL for every existing link.
-      const el = node as HTMLElement;
-      return { active: true, href: el.dataset.jxHref ?? el.getAttribute("href") };
+      return { active: true, href: node.dataset.jxHref ?? node.getAttribute("href") };
     }
     node = node.parentNode;
   }
@@ -44,17 +69,17 @@ export function linkStateForSelection(root: HTMLElement): { active: boolean; hre
  * Find the `<a>` that contains the selection anchor (up to `root`), if any.
  *
  * @param {HTMLElement} root
- * @returns {HTMLAnchorElement | null}
+ * @returns {HTMLAnchorElement | SVGAElement | null}
  */
-function anchorInSelection(root: HTMLElement): HTMLAnchorElement | null {
+function anchorInSelection(root: HTMLElement): HTMLAnchorElement | SVGAElement | null {
   const sel = window.getSelection();
   if (!sel || !sel.rangeCount) {
     return null;
   }
   let node: Node | null = sel.anchorNode;
   while (node && node !== root) {
-    if (node.nodeType === Node.ELEMENT_NODE && (node as Element).tagName.toLowerCase() === "a") {
-      return node as HTMLAnchorElement;
+    if (isAnchorNode(node)) {
+      return node;
     }
     node = node.parentNode;
   }
@@ -80,13 +105,13 @@ export function applyLink(root: HTMLElement, href: string | null): void {
       existing.replaceWith(frag);
     }
   } else if (href) {
-    exec("createLink", href);
+    execEditingCommand("createLink", href);
   }
   normalizeInlineContent(root);
 }
 
-/** Insert a `${token}` template expression at the caret inside `root` (joins the native undo stack). */
+/** Insert a `${token}` template expression at the caret inside `root`, through the editing engine. */
 export function insertTemplateToken(root: HTMLElement, token: string): void {
   root.focus();
-  exec("insertText", `\${${token}}`);
+  execEditingCommand("insertText", `\${${token}}`);
 }

package/src/editor/insert-component.ts

@@ -0,0 +1,91 @@
+/**
+ * Inserting a component has one meaning everywhere (`specs/studio.md` §5.7, §9.1.3).
+ *
+ * A component instance is only a usable element in a document that imports it: the canvas drop did
+ * that, and the Insert panel's click, the slash menu and the canvas `+` did not, so a component
+ * clicked in rendered as an element the page could not resolve. This module is the one rule the
+ * four doors share — the instance comes from `buildComponentInstance`, and the import from the one
+ * `$elements` service, `files/elements.ts`'s `enableElement`.
+ *
+ * @docs studio/design/components
+ */
+
+import { isString } from "@jxsuite/schema/guards";
+import { buildComponentInstance, componentRegistry } from "../files/components";
+import { enableElement } from "../files/elements";
+import { mutateUpdateProperty } from "../tabs/transact";
+import type { JxNodeValue } from "../tabs/transact";
+import type { ElementsEntry } from "../files/elements";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { Tab } from "../tabs/tab";
+import type { SlashCommand } from "./inline-edit";
+
+/** The slash menu's group heading for the project's components. */
+export const COMPONENTS_GROUP = "Components";
+
+/**
+ * Import the component a node is an instance of into `tab`'s document, when it is one and is not
+ * imported yet. A node whose tag has no hyphen is an HTML element and is left alone, and a
+ * component the registry cannot name (an npm entry with no package, a local one with no path)
+ * changes nothing, so a document that had no `$elements` is not handed an empty one.
+ *
+ * A computed tag (`{ $expression }`) names no registered component, so it is left alone too.
+ *
+ * This is a MUTATION: call it inside the transaction that inserts the instance, so the instance and
+ * its import are one undo step. As a transaction of its own after the insert, the first ⌘Z took
+ * back only the import and left a document using a component it no longer imported, which saves as
+ * an instance the page cannot resolve.
+ *
+ * @param tab The document the node was inserted into, inside a `transactDoc`.
+ * @param tagName The inserted node's tag.
+ */
+export function mutateImportComponent(tab: Tab, tagName: JxMutableNode["tagName"]): void {
+  const after = elementsImporting(tab, tagName);
+  if (after) {
+    /* Through the recorded mutator, not a bare assignment: a transaction that records ops is
+       undone by replaying their inverses, so an unrecorded write beside the insert would survive
+       the ⌘Z that took the instance back, and never reach a co-editor.
+       SAFETY: `$elements` entries are JSON — module specifiers, `{ $ref }` imports and inline
+       element definitions — which is what a node key holds. */
+    mutateUpdateProperty(tab, [], "$elements", after as JxNodeValue);
+  }
+}
+
+/** The document's `$elements` with the component imported, or null when nothing would change. */
+function elementsImporting(tab: Tab, tagName: JxMutableNode["tagName"]): ElementsEntry[] | null {
+  if (!isString(tagName) || !tagName.includes("-")) {
+    return null;
+  }
+  const comp = componentRegistry.find((entry) => entry.tagName === tagName);
+  if (!comp) {
+    return null;
+  }
+  /* SAFETY: `$elements` holds module specifiers and `{ $ref }` imports; the document type and
+     files/elements.ts spell an inline entry as JxMutableNode and JxElement respectively, two editor
+     views of the same JSON object that enableElement only compares by `$ref`. */
+  const before = (tab.doc.document.$elements ?? []) as ElementsEntry[];
+  const after = enableElement(before, comp, tab.documentPath ?? null);
+  return after.length === before.length ? null : after;
+}
+
+/** A fresh instance of a registered component, or null for a tag the registry does not know. */
+export function componentInstance(tagName: string): JxMutableNode | null {
+  const comp = componentRegistry.find((entry) => entry.tagName === tagName);
+  return comp ? buildComponentInstance(comp) : null;
+}
+
+/**
+ * Every registered component as a slash-menu offer, under the Components heading: the project's
+ * own, described by their definition file, and the ones installed packages provide, described by
+ * their package. A package component needs no prior enabling, because inserting one imports its
+ * package ({@link mutateImportComponent}), exactly as the canvas drop does.
+ */
+export function componentSlashCommands(): SlashCommand[] {
+  return componentRegistry.map((comp) => ({
+    component: true,
+    description: (comp.source === "npm" ? comp.package : comp.path) ?? "",
+    group: COMPONENTS_GROUP,
+    label: `<${comp.tagName}>`,
+    tag: comp.tagName,
+  }));
+}

package/src/editor/insert-zone-action.ts

@@ -7,11 +7,13 @@
  * name via `setInsertZoneClickHandler(runInsertZoneAction)` in studio.ts.
  *
  * The cross-origin insertion "+" (drawn by the host from posted zones) runs the parent-realm
- * slash-menu → mutateInsertNode flow on click. The host captured the zone (parentPath + index); the
- * new node is selected at its inserted path. Salvaged from the orphaned insertion-helper.ts.
+ * slash-menu → mutateInsertNode flow on click. The menu offers the HTML elements and, under a
+ * Components heading, the project's components. The host captured the zone (parentPath + index);
+ * the new node is selected at its inserted path. Salvaged from the orphaned insertion-helper.ts.
  */
 
 import { showSlashMenu } from "./slash-menu";
+import { componentInstance, mutateImportComponent } from "./insert-component";
 import { defaultDef } from "../panels/shared";
 import { mutateInsertNode, transactDoc } from "../tabs/transact";
 import { activeTab } from "../workspace/workspace";
@@ -21,12 +23,19 @@ import type { JxPath } from "../state";
 export function runInsertZoneAction(btn: HTMLElement, zone: InsertZone): void {
   showSlashMenu(btn, "", {
     onSelect: (cmd) => {
-      const def = defaultDef(cmd.tag);
-      const insertPath = zone.insertParentPath as JxPath;
+      /* A pick from the Components group inserts an instance and imports the component, as a drop
+         of the same component does (§5.7); every other pick inserts the element's default. */
+      const instance = cmd.component === true ? componentInstance(cmd.tag) : null;
+      const def = instance ?? defaultDef(cmd.tag);
+      const insertPath: JxPath = zone.insertParentPath;
       const idx = zone.index;
       const newPath = [...insertPath, "children", idx];
-      transactDoc(activeTab.value, (t) => {
+      const tab = activeTab.value;
+      transactDoc(tab, (t) => {
         mutateInsertNode(t, insertPath, idx, def);
+        if (instance) {
+          mutateImportComponent(t, instance.tagName);
+        }
         t.session.selection = [newPath];
       });
     },

package/src/editor/merge-tags.ts

@@ -9,8 +9,10 @@
  * Pure and DOM-free: callers pass the data in, this returns plain descriptors.
  */
 
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { defCategory } from "../panels/signals-panel";
 import { dataTypeLabel, unwrapSignal } from "../panels/data-explorer";
+import type { JsonPrimitive, JxStateDefinition } from "@jxsuite/schema/types";
 
 export interface MergeTag {
   /** Insertion token placed between `${` and `}`, e.g. `state.user.name`, `item.title`, `index`. */
@@ -23,20 +25,50 @@ export interface MergeTag {
   category: string;
 }
 
+/**
+ * A value in a live render scope, as far as the merge-tag walk reads it: document data, a handler,
+ * a pending (`undefined`) entry, or an object — a plain record, a fetched payload, a Vue ref —
+ * whose own keys hold further scope values.
+ */
+export type ScopeValue =
+  | JsonPrimitive
+  | undefined
+  | bigint
+  | symbol
+  | ((...args: never[]) => void)
+  | ScopeValue[]
+  | ScopeRecord;
+
+/** A render scope, or any object inside one, read key by key. */
+export interface ScopeRecord {
+  readonly [key: string]: ScopeValue;
+}
+
 /** Levels of nesting walked beneath each root name. */
 const DEPTH_CAP = 3;
 /** Maximum object keys enumerated per level (mirrors the data-explorer tree cap). */
 const BREADTH_CAP = 30;
 
+/** Whether a scope value is an object read by key: non-null, not an array, not a function. */
+function isScopeRecord(value: ScopeValue): value is ScopeRecord {
+  return isNonNullObject(value) && !Array.isArray(value);
+}
+
+/** The value behind a Vue ref, or the value itself. */
+function unwrapScopeValue(value: ScopeValue): ScopeValue {
+  /* SAFETY: unwrapSignal returns its argument unchanged, or a ref's `.value`; a ref is a scope record,
+     so its `.value` member is itself a scope value. */
+  return unwrapSignal(value) as ScopeValue;
+}
+
 /** Type label plus a short value preview for primitives. */
-function previewHint(value: unknown): string {
-  const v = unwrapSignal(value);
+function previewHint(value: ScopeValue): string {
+  const v = unwrapScopeValue(value);
   const typeLabel = dataTypeLabel(v);
-  if (v === null || v === undefined || typeof v === "object") {
+  if (v === null || v === undefined || isNonNullObject(v)) {
     return typeLabel; // Null / pending / Array(n) / {n}
   }
-  const text =
-    typeof v === "string" ? (v.length > 24 ? `"${v.slice(0, 24)}…"` : `"${v}"`) : String(v);
+  const text = isString(v) ? (v.length > 24 ? `"${v.slice(0, 24)}…"` : `"${v}"`) : String(v);
   return `${typeLabel} · ${text}`;
 }
 
@@ -44,25 +76,25 @@ function previewHint(value: unknown): string {
  * Walk a resolved value, appending nested-path tags to `out`. Arrays contribute a `.length` tag and
  * stop (index access is context-dependent); plain objects recurse up to the depth/breadth caps.
  */
-function walk(value: unknown, prefix: string, category: string, depth: number, out: MergeTag[]) {
+function walk(value: ScopeValue, prefix: string, category: string, depth: number, out: MergeTag[]) {
   if (depth >= DEPTH_CAP) {
     return;
   }
-  const v = unwrapSignal(value);
-  if (v === null || v === undefined || typeof v !== "object") {
-    return;
-  }
+  const v = unwrapScopeValue(value);
   if (Array.isArray(v)) {
     const token = `${prefix}.length`;
     out.push({ category, hint: `number · ${v.length}`, label: token, token });
     return;
   }
+  if (!isScopeRecord(v)) {
+    return;
+  }
   const keys = Object.keys(v).slice(0, BREADTH_CAP);
   for (const key of keys) {
     if (key.startsWith("$")) {
       continue; // Internal keys ($children, $ref, reactive plumbing) are not author-facing
     }
-    const childVal = (v as Record<string, unknown>)[key];
+    const childVal = v[key];
     const childPrefix = `${prefix}.${key}`;
     out.push({ category, hint: previewHint(childVal), label: childPrefix, token: childPrefix });
     walk(childVal, childPrefix, category, depth + 1, out);
@@ -80,9 +112,9 @@ function walk(value: unknown, prefix: string, category: string, depth: number, o
  *   carries a `$map` (repeater) context, `item` / `item.*` / `index` tags are appended.
  */
 export function buildMergeTags(
-  state: Record<string, unknown> | null | undefined,
-  scope: Record<string, unknown> | null | undefined,
-  localScope: Record<string, unknown> | null = null,
+  state: Readonly<Record<string, JxStateDefinition>> | null | undefined,
+  scope: ScopeRecord | null | undefined,
+  localScope: ScopeRecord | null = null,
 ): MergeTag[] {
   const out: MergeTag[] = [];
   const defs = state ?? {};
@@ -103,13 +135,20 @@ export function buildMergeTags(
   }
 
   if (localScope) {
-    const map = unwrapSignal(localScope.$map) as { item?: unknown; index?: unknown } | undefined;
-    if (map && typeof map === "object") {
-      out.push({ category: "repeater", hint: previewHint(map.item), label: "item", token: "item" });
-      walk(map.item, "item", "repeater", 0, out);
+    const map = unwrapScopeValue(localScope.$map);
+    if (isNonNullObject(map)) {
+      // An array `$map` has no `item` / `index` members, so it reads as an empty row.
+      const row = isScopeRecord(map) ? map : undefined;
+      out.push({
+        category: "repeater",
+        hint: previewHint(row?.item),
+        label: "item",
+        token: "item",
+      });
+      walk(row?.item, "item", "repeater", 0, out);
       out.push({
         category: "repeater",
-        hint: previewHint(map.index),
+        hint: previewHint(row?.index),
         label: "index",
         token: "index",
       });