@jxsuite/studio 6.1.1 → 6.1.2

package/src/content/entry-model.ts

@@ -27,7 +27,15 @@ import { collectionInfo } from "../grid/sources/content-source";
 import { projectState } from "../store";
 import { findContentTypeSchema } from "../utils/studio-utils";
 import type { ContentSectionEntry } from "../types";
-import type { ContentTypeSchema, ContentTypeSchemaField } from "@jxsuite/schema/types";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type {
+  ContentTypeSchema,
+  ContentTypeSchemaField,
+  ContentTypeSchemaValue,
+  JsonObject,
+  JsonValue,
+} from "@jxsuite/schema/types";
+import type { EntryFields } from "./entry-fields";
 
 // ─── Collections ─────────────────────────────────────────────────────────────
 
@@ -44,7 +52,7 @@ export interface EntryCollection {
 
 /** Every content type the project declares, in declaration order. */
 export function collectionNames(): string[] {
-  return Object.keys((projectState?.projectConfig?.content ?? {}) as Record<string, unknown>);
+  return Object.keys(projectState?.projectConfig?.content ?? {});
 }
 
 /**
@@ -94,12 +102,13 @@ export function collectionOfPath(path: string | null): EntryCollection | null {
 // ─── Seeding a new entry ─────────────────────────────────────────────────────
 
 /** Deep copy of a schema `default`, so two entries seeded from one schema never share an object. */
-function cloneDefault(value: unknown): unknown {
-  if (value === null || typeof value !== "object") {
+function cloneDefault(value: ContentTypeSchemaValue): JsonValue {
+  if (value === null || !isNonNullObject(value)) {
     return value;
   }
+  // SAFETY: `JSON.parse` of what `JSON.stringify` just wrote is JSON by construction.
   // oxlint-disable-next-line unicorn/prefer-structured-clone
-  return JSON.parse(JSON.stringify(value)) as unknown;
+  return JSON.parse(JSON.stringify(value)) as JsonValue;
 }
 
 /**
@@ -109,8 +118,8 @@ function cloneDefault(value: unknown): unknown {
  * and picking an arbitrary entry of the target collection on the author's behalf would be inventing
  * a relationship they never stated.
  */
-function emptyForField(field: ContentTypeSchemaField): unknown {
-  if (typeof field.$ref === "string") {
+function emptyForField(field: ContentTypeSchemaField): JsonValue {
+  if (isString(field.$ref)) {
     return "";
   }
   switch (field.type) {
@@ -125,7 +134,7 @@ function emptyForField(field: ContentTypeSchemaField): unknown {
       return [];
     }
     case "object": {
-      return seedEntry(field as ContentTypeSchema);
+      return seedEntry(field);
     }
     default: {
       return "";
@@ -145,13 +154,13 @@ function emptyForField(field: ContentTypeSchemaField): unknown {
  * author's file full of keys they never asked for, and "the schema mentions it" is not a reason for
  * it to exist on disk — the form still draws a row for it, because the form draws the SCHEMA.
  */
-export function seedEntry(schema: ContentTypeSchema | null | undefined): Record<string, unknown> {
+export function seedEntry(schema: ContentTypeSchema | null | undefined): JsonObject {
   const properties = schema?.properties;
   if (!properties) {
     return {};
   }
-  const required = new Set(Array.isArray(schema?.required) ? schema.required : []);
-  const seed: Record<string, unknown> = {};
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const seed: JsonObject = {};
   for (const [name, field] of Object.entries(properties)) {
     if (field.default !== undefined) {
       seed[name] = cloneDefault(field.default);
@@ -168,7 +177,7 @@ export function seedEntry(schema: ContentTypeSchema | null | undefined): Record<
  */
 export function missingRequired(
   schema: ContentTypeSchema | null | undefined,
-  value: Record<string, unknown>,
+  value: EntryFields,
 ): string[] {
   const required = Array.isArray(schema?.required) ? schema.required : [];
   return required.filter((name) => value[name] === undefined);

package/src/editor/canvas-context-menu.ts

@@ -15,7 +15,6 @@ import { dismissContextMenu, showContextMenu } from "./context-menu";
 import { bubbleInlinePath } from "../canvas/canvas-helpers";
 import { activeTab } from "../workspace/workspace";
 import type { CanvasContextMenuHandler } from "../canvas/iframe-host";
-import type { JxPath } from "../state";
 
 /**
  * Build the handler.
@@ -34,7 +33,7 @@ export function makeCanvasContextMenuHandler(): CanvasContextMenuHandler {
       }
       // Lift inline-element paths (a <strong> inside a <p>) to their block parent — right-clicking
       // Formatted text should act on the block, matching the legacy handler.
-      const bubbled = bubbleInlinePath(activeTab.value?.doc.document, path as JxPath);
+      const bubbled = bubbleInlinePath(activeTab.value?.doc.document, path);
       // ShowContextMenu reads only preventDefault/clientX/clientY from the event, so a synthetic
       // MouseEvent carries the converted coords safely.
       const evt = new MouseEvent("contextmenu", { clientX, clientY });

package/src/editor/canvas-slash-bridge.ts

@@ -18,11 +18,8 @@ export const canvasSlashHandler: CanvasSlashHandler = {
      opened. Typing "/" needs none — the author keeps typing into the iframe's contenteditable and
      the engine re-posts `slashShow` with the updated filter. A menu opened BY NAME
      (`insert.openSlashMenu`) has no "/…" run to type into, so without the field the only way past
-     fifteen blocks is scrolling. */
+     fifteen blocks is scrolling. The menu reads `showFilter` for truthiness alone, so `false` and an
+     absent key are one state to it. */
   show: ({ rect, filter, showFilter, onSelect, onDismiss }) =>
-    showSlashMenuAtRect(rect, filter, {
-      onDismiss,
-      onSelect,
-      ...(showFilter === true ? { showFilter: true } : {}),
-    }),
+    showSlashMenuAtRect(rect, filter, { onDismiss, onSelect, showFilter: showFilter === true }),
 };

package/src/editor/content-slice.ts

@@ -14,11 +14,18 @@
  * @docs studio/editing/writing
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
 /** A block's content as a children array — the form both storage shapes normalize to. */
 export type Content = (JxMutableNode | string)[];
 
+/** A block's content in the form it is stored: `children` for markup, folded `textContent` else. */
+export interface StoredContent {
+  children?: Content;
+  textContent?: string;
+}
+
 /**
  * The content of `node` as a children array, whichever way it is stored.
  *
@@ -30,18 +37,16 @@ export function contentOf(node: JxMutableNode | undefined | null): Content {
     return [];
   }
   if (Array.isArray(node.children)) {
-    return node.children as Content;
+    return node.children;
   }
-  return typeof node.textContent === "string" && node.textContent.length > 0
-    ? [node.textContent]
-    : [];
+  return isString(node.textContent) && node.textContent.length > 0 ? [node.textContent] : [];
 }
 
 /** The rendered text length of a content array. */
 export function contentLength(children: Content): number {
   let n = 0;
   for (const child of children) {
-    n += typeof child === "string" ? child.length : contentLength(contentOf(child));
+    n += isString(child) ? child.length : contentLength(contentOf(child));
   }
   return n;
 }
@@ -60,7 +65,7 @@ export function sliceContent(children: Content, start: number, end: number): Con
     if (pos >= end) {
       break;
     }
-    if (typeof child === "string") {
+    if (isString(child)) {
       const childEnd = pos + child.length;
       if (childEnd > start) {
         const text = child.slice(
@@ -102,7 +107,7 @@ function withContent(node: JxMutableNode, children: Content): JxMutableNode {
   if (children.length === 0) {
     return { ...rest, textContent: "" };
   }
-  if (children.length === 1 && typeof children[0] === "string") {
+  if (children.length === 1 && isString(children[0])) {
     return { ...rest, textContent: children[0] };
   }
   return { ...rest, children };
@@ -115,12 +120,12 @@ function withContent(node: JxMutableNode, children: Content): JxMutableNode {
 export function normalizeContent(children: Content): Content {
   const out: Content = [];
   for (const child of children) {
-    if (typeof child === "string") {
+    if (isString(child)) {
       if (child.length === 0) {
         continue;
       }
       const prev = out.at(-1);
-      if (typeof prev === "string") {
+      if (isString(prev)) {
         out[out.length - 1] = prev + child;
         continue;
       }
@@ -152,15 +157,12 @@ export function spliceAcross(
 }
 
 /** `{ children }` when the content carries markup, else the folded `{ textContent }` form. */
-export function toStored(children: Content): {
-  children?: Content;
-  textContent?: string;
-} {
+export function toStored(children: Content): StoredContent {
   const normalized = normalizeContent(children);
   if (normalized.length === 0) {
     return { textContent: "" };
   }
-  if (normalized.length === 1 && typeof normalized[0] === "string") {
+  if (normalized.length === 1 && isString(normalized[0])) {
     return { textContent: normalized[0] };
   }
   return { children: normalized };

package/src/editor/context-menu.ts

@@ -21,10 +21,11 @@
  * is left here is the projection: the menu itself is the `menu` surface (`surfaces/menu.json`), a
  * `jx-menu` the kit gives its keyboard contract, its popover and its dismissal.
  */
-import { displayTagName } from "@jxsuite/schema/guards";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { displayTagName, isNodeObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { jsonClone } from "../utils/studio-utils";
 import { htmlToJx } from "@jxsuite/markup/html-to-jx";
-import { childIndex, getNodeAtPath, parentElementPath } from "../store";
+import { childIndex, parentElementPath } from "../store";
 import { activeTab, workspace } from "../workspace/workspace";
 import { isSelected, isSpliceablePath, primarySelection } from "../tabs/selection";
 import {
@@ -58,17 +59,15 @@ import type { AnyCommand, CommandRegistry } from "../commands/registry";
 import type { CommandContext } from "../commands/context";
 import type { Placement } from "../commands/levels";
 import type { JxPath } from "../state";
-import type { JxMutableNode, JxStyle } from "@jxsuite/schema/types";
-
-type JxNode = JxMutableNode;
+import type { JxAttributeValue, JxMutableNode, JxStyle } from "@jxsuite/schema/types";
 
 // ─── Clipboard helpers ───────────────────────────────────────────────────────
 
-const JX_MIME = "web application/jx+json";
+export const JX_MIME = "web application/jx+json";
 
-/** @param {JxNode | string} node */
-function nodeToHtml(node: JxNode | string): string {
-  if (typeof node === "string") {
+/** @param {JxMutableNode | string} node */
+function nodeToHtml(node: JxMutableNode | string): string {
+  if (isString(node)) {
     return node;
   }
   /* A chosen tag cannot be serialised to one HTML string, so the copy takes the branch the
@@ -77,9 +76,10 @@ function nodeToHtml(node: JxNode | string): string {
   const tag = displayTagName(node.tagName).split("|")[0] || "div";
   let attrs = "";
   if (node.attributes) {
-    for (const [k, v] of Object.entries(node.attributes)) {
+    // A document's attribute value is read as possibly JSON `null`, which is skipped with the refs.
+    for (const [k, v] of Object.entries<JxAttributeValue | null>(node.attributes)) {
       // Bound ($ref) attribute values have no static HTML representation — skip.
-      if (typeof v === "object") {
+      if (v === null || isNonNullObject(v)) {
         continue;
       }
       attrs += v === "" ? ` ${k}` : ` ${k}="${String(v).replaceAll('"', "&quot;")}"`;
@@ -94,7 +94,7 @@ function nodeToHtml(node: JxNode | string): string {
     }
   }
   let inner = "";
-  if (typeof node.textContent === "string") {
+  if (isString(node.textContent)) {
     inner = node.textContent;
   } else if (Array.isArray(node.children)) {
     inner = node.children.map((c) => nodeToHtml(c)).join("");
@@ -105,9 +105,9 @@ function nodeToHtml(node: JxNode | string): string {
 /**
  * Write a Jx node to the system clipboard with both jx+json and text/html types.
  *
- * @param {object} json
+ * @param {JxMutableNode} json
  */
-async function writeToClipboard(json: Record<string, unknown>) {
+async function writeToClipboard(json: JxMutableNode) {
   workspace.clipboard = json;
   try {
     const jxBlob = new Blob([JSON.stringify(json)], { type: JX_MIME });
@@ -131,7 +131,7 @@ async function writeToClipboard(json: Record<string, unknown>) {
 /**
  * Read from the system clipboard. Returns Jx node(s) or null.
  *
- * @returns {Promise<JxNode[] | null>}
+ * @returns {Promise<JxMutableNode[] | null>}
  */
 async function readFromClipboard() {
   try {
@@ -139,16 +139,18 @@ async function readFromClipboard() {
     for (const item of items) {
       if (item.types.includes(JX_MIME)) {
         const blob = await item.getType(JX_MIME);
-        const json = JSON.parse(await blob.text()) as JxNode;
+        /* SAFETY: `web application/jx+json` is Jx's own clipboard type, and `writeToClipboard` puts a
+           node there serialized with JSON.stringify; malformed text throws into the fallback below. */
+        const json = JSON.parse(await blob.text()) as JxMutableNode;
         return [json];
       }
       if (item.types.includes("text/html")) {
         const blob = await item.getType("text/html");
         const htmlStr = await blob.text();
         const nodes = htmlToJx(htmlStr);
-        const jxNodes = nodes.map((n) =>
-          typeof n === "string" ? { tagName: "p", textContent: n } : n,
-        ) as JxNode[];
+        const jxNodes: JxMutableNode[] = nodes.map((n) =>
+          isString(n) ? { tagName: "p", textContent: n } : n,
+        );
         if (jxNodes.length > 0) {
           return jxNodes;
         }
@@ -158,8 +160,8 @@ async function readFromClipboard() {
         const text = await blob.text();
         // Try parsing as Jx JSON
         try {
-          const parsed = JSON.parse(text) as JxNode;
-          if (parsed && parsed.tagName) {
+          const parsed: unknown = JSON.parse(text);
+          if (isNodeObject(parsed) && parsed.tagName) {
             return [parsed];
           }
         } catch {
@@ -241,7 +243,12 @@ export async function pasteNode() {
   }
 
   if (selected && selected.length >= 2) {
+    // SAFETY: parentElementPath returns a path for any path of two or more segments, checked above.
     const pp = parentElementPath(selected) as JxPath;
+    /* SAFETY: a selection with a sibling position ends in `"children", <index>`, so this is the
+       numeric child index. A selected repeater template (`…, "map"`) or `$switch` case also has two
+       or more segments; callers do not exclude that case yet, so it reaches here with a string
+       segment exactly as before this cast. */
     const idx = childIndex(selected) as number;
     transactDoc(tab, (t) => {
       for (let i = 0; i < nodes.length; i++) {
@@ -408,7 +415,10 @@ export function elementCommands(deps: ElementCommandDeps): AnyCommand[] {
         if (!target || !nodes || nodes.length === 0) {
           return;
         }
+        /* SAFETY: this record runs only when enabled, and `spliceable` admits a target whose path
+           ends in `"children", <index>` — so it has a parent element path. */
         const parent = parentElementPath(target.path) as JxPath;
+        // SAFETY: the same `spliceable` check proved the last segment is a numeric child index.
         const idx = childIndex(target.path) as number;
         transactDoc(activeTab.value, (t) => {
           for (const [offset, node] of nodes.entries()) {
@@ -576,7 +586,10 @@ function insertSiblingParagraph(target: ElementMenuTarget | null, offset: number
   if (!target) {
     return;
   }
+  /* SAFETY: both callers are records enabled only by `spliceable`, which admits a target whose path
+     ends in `"children", <index>` — so it has a parent element path. */
   const parent = parentElementPath(target.path) as JxPath;
+  // SAFETY: the same `spliceable` check proved the last segment is a numeric child index.
   const idx = childIndex(target.path) as number;
   transactDoc(activeTab.value, (t) =>
     mutateInsertNode(t, parent, idx + offset, { children: [], tagName: "p" }),
@@ -681,7 +694,7 @@ function commandTarget(): ElementMenuTarget | null {
   if (!tab || !path) {
     return null;
   }
-  const node = getNodeAtPath(tab.doc.document, path) as JxMutableNode | undefined;
+  const node = getNodeAtPath(tab.doc.document, path);
   return node ? { node, path } : null;
 }
 

package/src/editor/convert-targets.ts

@@ -1,34 +1,33 @@
 import elementsMeta from "../../data/elements-meta.json";
 
-export interface SlashCommand {
-  label: string;
-  tag: string;
-  description: string;
-}
+import { ELEMENT_DEFS } from "./editable-tags";
+import type { SlashCommand } from "./inline-edit";
+
+export type { SlashCommand } from "./inline-edit";
 
-const TAG_LABELS = {
-  article: "Article",
-  aside: "Aside",
-  blockquote: "Blockquote",
-  div: "Div",
-  footer: "Footer",
-  h1: "Heading 1",
-  h2: "Heading 2",
-  h3: "Heading 3",
-  h4: "Heading 4",
-  h5: "Heading 5",
-  h6: "Heading 6",
-  header: "Header",
-  main: "Main",
-  nav: "Nav",
-  ol: "Numbered List",
-  p: "Paragraph",
-  search: "Search",
-  section: "Section",
-  ul: "Bulleted List",
-} as Record<string, string>;
+const TAG_LABELS = new Map<string, string>([
+  ["article", "Article"],
+  ["aside", "Aside"],
+  ["blockquote", "Blockquote"],
+  ["div", "Div"],
+  ["footer", "Footer"],
+  ["h1", "Heading 1"],
+  ["h2", "Heading 2"],
+  ["h3", "Heading 3"],
+  ["h4", "Heading 4"],
+  ["h5", "Heading 5"],
+  ["h6", "Heading 6"],
+  ["header", "Header"],
+  ["main", "Main"],
+  ["nav", "Nav"],
+  ["ol", "Numbered List"],
+  ["p", "Paragraph"],
+  ["search", "Search"],
+  ["section", "Section"],
+  ["ul", "Bulleted List"],
+]);
 
-const groups = (elementsMeta.$convertGroups || {}) as Record<string, string[]>;
+const groups: Readonly<Record<string, string[]>> = elementsMeta.$convertGroups;
 
 /**
  * Get the list of tags the current element can be converted to.
@@ -37,18 +36,14 @@ const groups = (elementsMeta.$convertGroups || {}) as Record<string, string[]>;
  * @param {boolean} isEmpty
  * @returns {SlashCommand[]}
  */
-export function getConvertTargets(currentTag: string, isEmpty: boolean) {
-  const def = (elementsMeta.$defs as Record<string, Record<string, unknown>>)?.[currentTag] as
-    | Record<string, unknown>
-    | undefined;
+export function getConvertTargets(currentTag: string, isEmpty: boolean): SlashCommand[] {
+  const def = ELEMENT_DEFS[currentTag];
   if (!def?.$convertTo) {
     return [];
   }
 
   const groupNames =
-    isEmpty && def.$convertToWhenEmpty
-      ? (def.$convertToWhenEmpty as string[])
-      : [def.$convertTo as string];
+    isEmpty && def.$convertToWhenEmpty ? def.$convertToWhenEmpty : [def.$convertTo];
 
   const tags = new Set<string>();
   for (const name of groupNames) {
@@ -61,7 +56,7 @@ export function getConvertTargets(currentTag: string, isEmpty: boolean) {
 
   return [...tags].map((tag) => ({
     description: "",
-    label: TAG_LABELS[tag] || tag.charAt(0).toUpperCase() + tag.slice(1),
+    label: TAG_LABELS.get(tag) || tag.charAt(0).toUpperCase() + tag.slice(1),
     tag,
   }));
 }

package/src/editor/convert-to-component.ts

@@ -17,9 +17,10 @@
  *
  * @docs studio/design/components
  */
-import { displayTagName } from "@jxsuite/schema/guards";
+import { displayTagName, isNonNullObject } from "@jxsuite/schema/guards";
 import { errorMessage } from "@jxsuite/schema/parse";
-import { childIndex, getNodeAtPath, parentElementPath } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { childIndex, parentElementPath } from "../store";
 import { primarySelection } from "../tabs/selection";
 import { activeTab } from "../workspace/workspace";
 import { transact } from "../tabs/transact";
@@ -71,10 +72,16 @@ export async function convertToComponent() {
   const converted = transact(tab, (doc) => {
     // Navigate to parent's children array and replace the node
     const pp = parentElementPath(selectionPath) ?? [];
+    /* SAFETY: an element with a sibling position ends in `"children", <index>`, so this is the
+       numeric child index. A selected repeater template (`…, "map"`) or `$switch` case also passes
+       the two-segment check above; callers do not exclude that case yet, so it reaches here with a
+       string segment exactly as before this cast. */
     const idx = childIndex(selectionPath) as number;
     let parent = doc;
-    // Paths address nodes by construction (same contract as getNodeAtPath).
     for (const seg of pp) {
+      /* SAFETY: `pp` is the parent element's path, and a `JxPath` alternates node keys with
+         `"children"` and an index, so walking it from the root lands on a node (the same contract as
+         getNodeAtPath). */
       parent = parent[seg] as JxMutableNode;
     }
     if (!Array.isArray(parent.children)) {
@@ -87,8 +94,7 @@ export async function convertToComponent() {
       doc.$elements = [];
     }
     const alreadyReferenced = doc.$elements.some(
-      (/** @type {JxMutableNode | string | { $ref: string }} */ el) =>
-        el && typeof el === "object" && "$ref" in el && el.$ref === refPath,
+      (el) => isNonNullObject(el) && "$ref" in el && el.$ref === refPath,
     );
     if (!alreadyReferenced) {
       doc.$elements.push({ $ref: refPath });

package/src/editor/convert-to-repeater.ts

@@ -12,7 +12,9 @@
  *
  * @docs studio/design/repeaters
  */
-import { childIndex, childList, getNodeAtPath, parentElementPath } from "../store";
+import { getNodeAtPath } from "@jxsuite/schema/doc-ops";
+import { isJsonObject, isPrototypeDef } from "@jxsuite/schema/guards";
+import { childIndex, childList, parentElementPath } from "../store";
 import { primarySelection } from "../tabs/selection";
 import { activeTab } from "../workspace/workspace";
 import { transactDoc } from "../tabs/transact";
@@ -22,15 +24,18 @@ import { fetchPluginSchema } from "../services/code-services";
 import { CREATE_NEW_SOURCE, openConvertRepeaterSurface } from "../surfaces/convert-repeater";
 
 import type { ConvertRepeaterView } from "../surfaces/convert-repeater";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JxMutableNode, JxRef, JxStateDefinition } from "@jxsuite/schema/types";
 
 /** What a name has to look like to become a state definition. */
 const IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 
+/** A document's state definitions, by name. */
+type StateDefs = Readonly<Record<string, JxStateDefinition>>;
+
 interface RepeaterConfig {
-  items: { $ref: string } | unknown[];
-  filter?: { $ref: string };
-  sort?: { $ref: string };
+  items: JxRef;
+  filter?: JxRef;
+  sort?: JxRef;
   newDef?: { name: string };
 }
 
@@ -65,14 +70,18 @@ export async function convertToRepeater() {
     if (!pp) {
       return;
     }
+    /* SAFETY: the command is enabled only when every selected path is spliceable
+       (`structurallyEditable` in commands/defaults.ts), so `path` ends in `"children", <index>`. */
     const idx = childIndex(path) as number;
     const parent = getNodeAtPath(doc, pp);
     if (!parent?.children) {
       return;
     }
-    const element = childList(parent)[idx];
+    /* SAFETY: a selection addresses an element node (the canvas selects elements, and an outline
+       text row is not a selectable item), and this reads the selected slot of its parent. */
+    const element = childList(parent)[idx] as JxMutableNode;
 
-    const repeater: Record<string, unknown> = {
+    const repeater: JxMutableNode = {
       $prototype: "Array",
       items: config.items,
       map: element,
@@ -84,9 +93,11 @@ export async function convertToRepeater() {
       repeater.sort = config.sort;
     }
 
-    // Replace the selected element in place with the array pseudo-element — no wrapper div. The
-    // Repeated items render directly among the original parent's children.
-    (parent.children as (string | JxMutableNode)[])[idx] = repeater as unknown as JxMutableNode;
+    /* Replace the selected element in place with the array pseudo-element — no wrapper div. The
+       repeated items render directly among the original parent's children.
+       SAFETY: a document is normalized to the member form when it loads into a tab
+       (`normalizeArrayChildren`), so a present `children` is an array, never a bare repeater. */
+    (parent.children as (string | JxMutableNode)[])[idx] = repeater;
   });
 }
 
@@ -98,18 +109,19 @@ export async function convertToRepeater() {
  * returns in its schema — so it is asked for once per definition, and only for the ones the first
  * three did not already claim.
  */
-async function arraySourceNames(defs: Record<string, unknown>): Promise<string[]> {
+async function arraySourceNames(defs: StateDefs): Promise<string[]> {
   const named = Object.entries(defs)
-    .filter(([, d]) => {
-      const def = d as Record<string, unknown> | null;
-      return def?.type === "array" || Array.isArray(def?.default) || def?.$prototype === "Array";
-    })
+    .filter(
+      ([, def]) =>
+        isJsonObject(def) &&
+        (def.type === "array" || Array.isArray(def.default) || def.$prototype === "Array"),
+    )
     .map(([name]) => name);
 
   const docPath = activeTab.value?.documentPath;
-  for (const [name, d] of Object.entries(defs)) {
-    const def = d as Record<string, unknown> | null;
-    if (!def?.$prototype || def.$prototype === "Function" || def.$prototype === "Array") {
+  for (const [name, def] of Object.entries(defs)) {
+    // Only a named, non-Function, non-Array prototype can be a plugin whose schema says it returns one.
+    if (!isPrototypeDef(def) || !def.$prototype || def.$prototype === "Array") {
       continue;
     }
     if (named.includes(name)) {
@@ -117,8 +129,8 @@ async function arraySourceNames(defs: Record<string, unknown>): Promise<string[]
     }
     const schema = await fetchPluginSchema(
       {
-        ...(def.$src != null && { $src: def.$src as string }),
-        $prototype: def.$prototype as string,
+        ...(def.$src != null && { $src: def.$src }),
+        $prototype: def.$prototype,
       },
       { ...(docPath != null && { documentPath: docPath }) },
     );
@@ -136,10 +148,10 @@ async function arraySourceNames(defs: Record<string, unknown>): Promise<string[]
  * name keeps the dialog open with the reason under the field — the flow's state machine, which is
  * the half the surface deliberately does not have.
  *
- * @param {Record<string, unknown>} defs
+ * @param {StateDefs} defs
  * @returns {Promise<RepeaterConfig | null>}
  */
-async function promptRepeaterConfig(defs: Record<string, unknown>): Promise<RepeaterConfig | null> {
+async function promptRepeaterConfig(defs: StateDefs): Promise<RepeaterConfig | null> {
   const sources = await arraySourceNames(defs);
   const functions = Object.entries(defs)
     .filter(([, d]) => defCategory(d) === "function")

package/src/editor/editable-tags.ts

@@ -21,11 +21,26 @@
  */
 
 import elementsMeta from "../../data/elements-meta.json";
+import type { InlineAction } from "./inline-edit";
 
-interface ElementDef {
+/** The fields of one `elements-meta.json` `$defs` entry the editor reads. */
+export interface ElementMeta {
+  /** Tags this element accepts as inline children; containers declare `[]`. */
   $inlineChildren?: string[];
+  /** The formatting verbs the block action bar offers, or the tag whose list this one shares. */
+  $inlineActions?: InlineAction[] | string;
+  /** The `$convertGroups` group this element converts within. */
+  $convertTo?: string;
+  /** The groups offered instead of `$convertTo` while the element is empty. */
+  $convertToWhenEmpty?: string[];
 }
 
+/**
+ * The studio's element metadata by tag. The JSON is bundled with the studio, so the compiler checks
+ * every entry against {@link ElementMeta} here, once, instead of each reader asserting it.
+ */
+export const ELEMENT_DEFS: Readonly<Record<string, ElementMeta>> = elementsMeta.$defs;
+
 /**
  * Tags the studio's own metadata says accept inline children.
  *
@@ -36,7 +51,7 @@ interface ElementDef {
 const EXCLUDED = new Set(["pre"]);
 
 export const BUILTIN_EDITABLE_TAGS: ReadonlySet<string> = new Set(
-  Object.entries(elementsMeta.$defs as Record<string, ElementDef>)
+  Object.entries(ELEMENT_DEFS)
     .filter(([tag, def]) => !EXCLUDED.has(tag) && (def.$inlineChildren?.length ?? 0) > 0)
     .map(([tag]) => tag),
 );