@jxsuite/schema 3.0.0 → 4.0.0

package/src/component-meta.ts

@@ -14,21 +14,23 @@
  * @license MIT
  */
 
-import type { JsonValue } from "../types";
+import { isJsonObject, isNonNullObject, isNumber, isString } from "./guards";
+import type { JsonObject, JsonValue } from "../types";
 
 /** One `<slot>` found in a component's tree. */
 export interface ComponentSlotDef {
   /** The slot's name; `""` for the unnamed slot. */
   name: string;
   /** Fallback children rendered when nothing is slotted in. */
-  fallback?: unknown[];
+  fallback?: JsonValue[];
 }
 
 /** One editable prop, derived from a `state` entry. */
 export interface ComponentPropDef {
   name: string;
   type?: unknown;
-  default?: JsonValue;
+  /** Absent for a full-form entry that declares no `default`. */
+  default?: JsonValue | undefined;
   format?: unknown;
 }
 
@@ -40,6 +42,12 @@ export interface ComponentMetaOut {
   props: ComponentPropDef[];
   slots?: ComponentSlotDef[];
   hasElements: boolean;
+  /**
+   * The custom-element tags its own tree renders, sorted; absent when there are none. A component
+   * written against the project's other components by bare `tagName` declares no `$elements`, so
+   * this is how a live renderer learns what one instance pulls in without fetching the definition.
+   */
+  uses?: string[];
 }
 
 /**
@@ -48,27 +56,29 @@ export interface ComponentMetaOut {
  * Whitespace-only names count as unnamed (`""`), and only static `children` arrays are walked — a
  * slot produced by a `$map` or a `$switch` has no fixed identity to report.
  *
- * @param {unknown} node - A node of the component document.
+ * @param {JsonValue | undefined} node - A node of the component document.
  * @param {ComponentSlotDef[]} [out] - Accumulator, for the recursive walk.
  * @returns {ComponentSlotDef[]}
  */
-export function collectSlotDefs(node: unknown, out: ComponentSlotDef[] = []): ComponentSlotDef[] {
-  if (!node || typeof node !== "object" || Array.isArray(node)) {
+export function collectSlotDefs(
+  node: JsonValue | undefined,
+  out: ComponentSlotDef[] = [],
+): ComponentSlotDef[] {
+  if (!isJsonObject(node)) {
     return out;
   }
-  const el = node as Record<string, unknown>;
-  if (el.tagName === "slot") {
-    const attrs = el.attributes as Record<string, unknown> | undefined;
-    const rawName = attrs?.name;
-    const name = typeof rawName === "string" ? rawName.trim() : "";
-    const { children } = el;
-    out.push({
-      name,
-      ...(Array.isArray(children) && children.length > 0 ? { fallback: children } : {}),
-    });
+  const { children } = node;
+  if (node.tagName === "slot") {
+    const attrs = node.attributes;
+    const rawName = isJsonObject(attrs) ? attrs.name : undefined;
+    const slot: ComponentSlotDef = { name: isString(rawName) ? rawName.trim() : "" };
+    if (Array.isArray(children) && children.length > 0) {
+      slot.fallback = children;
+    }
+    out.push(slot);
   }
-  if (Array.isArray(el.children)) {
-    for (const c of el.children) {
+  if (Array.isArray(children)) {
+    for (const c of children) {
       collectSlotDefs(c, out);
     }
   }
@@ -76,24 +86,76 @@ export function collectSlotDefs(node: unknown, out: ComponentSlotDef[] = []): Co
 }
 
 /**
- * Whether a `state` entry is an editable prop.
+ * Every custom-element tag (a `tagName` with a hyphen) in a document tree, its root excluded.
+ *
+ * Walks every place a node can sit — `children`, a repeater's `map`, a `$switch`'s `cases` — since
+ * an instance rendered through any of them still needs its definition registered.
+ *
+ * @param {JsonValue | undefined} node - The document, or a node of it.
+ * @param {Set<string>} [out] - Accumulator, for the recursive walk.
+ * @returns {Set<string>}
+ */
+export function collectUsedTags(node: JsonValue | undefined, out = new Set<string>()): Set<string> {
+  if (!isJsonObject(node)) {
+    return out;
+  }
+  const visit = (child: JsonValue | undefined) => {
+    if (isJsonObject(child)) {
+      if (isString(child.tagName) && child.tagName.includes("-")) {
+        out.add(child.tagName);
+      }
+      collectUsedTags(child, out);
+    }
+  };
+  const { cases, children, map } = node;
+  const nodes = [...(Array.isArray(children) ? children : [children]), map];
+  if (isJsonObject(cases)) {
+    nodes.push(...Object.values(cases));
+  }
+  for (const child of nodes) {
+    visit(child);
+  }
+  return out;
+}
+
+/** What `typeof` names a shorthand `state` entry's value: the only type a shorthand has on offer. */
+function shorthandTypeName(value: string | number | boolean): "string" | "number" | "boolean" {
+  if (isString(value)) {
+    return "string";
+  }
+  return isNumber(value) ? "number" : "boolean";
+}
+
+/**
+ * The editable prop a `state` entry offers, or null when it is not one.
  *
  * The shorthand form (`"title": "Hello"`) always is. The full form is one only when it is plain
  * data: a computed value, a handler or a prototype entry is machinery the author does not type
  * into, and offering it as a prop would put a text box in front of a function.
  *
- * @param {unknown} def - The `state` entry.
- * @returns {boolean}
+ * @param {string} name - The `state` key.
+ * @param {JsonValue} def - The `state` entry.
+ * @returns {ComponentPropDef | null}
  */
-function isPropEntry(def: unknown): boolean {
+function propFrom(name: string, def: JsonValue): ComponentPropDef | null {
   if (def == null) {
-    return false;
+    return null;
+  }
+  if (!isNonNullObject(def)) {
+    // Shorthand: the value IS the default, and its runtime type is the only type on offer.
+    return { default: def, name, type: shorthandTypeName(def) };
   }
-  if (typeof def !== "object") {
-    return true;
+  // An array entry declares nothing, so it reads as a full-form entry with every field absent.
+  const fields: JsonObject = isJsonObject(def) ? def : {};
+  if (fields.$prototype || fields.$handler || fields.$compute) {
+    return null;
   }
-  const obj = def as Record<string, unknown>;
-  return !obj.$prototype && !obj.$handler && !obj.$compute;
+  return {
+    default: fields.default,
+    format: fields.format,
+    name,
+    type: fields.type,
+  };
 }
 
 /**
@@ -103,41 +165,47 @@ function isPropEntry(def: unknown): boolean {
  * hyphen. That single test is what keeps a page or a data file from being reported as a component
  * when a whole project tree is scanned.
  *
- * @param {unknown} doc - The parsed document.
+ * @param {JsonValue | undefined} doc - The parsed document.
  * @param {string} path - Project-relative path, reported verbatim.
  * @returns {ComponentMetaOut | null}
  */
-export function componentMetaFrom(doc: unknown, path: string): ComponentMetaOut | null {
-  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+export function componentMetaFrom(
+  doc: JsonValue | undefined,
+  path: string,
+): ComponentMetaOut | null {
+  if (!isJsonObject(doc)) {
     return null;
   }
-  const content = doc as Record<string, unknown>;
-  const { tagName } = content;
-  if (typeof tagName !== "string" || !tagName.includes("-")) {
+  const { tagName } = doc;
+  if (!isString(tagName) || !tagName.includes("-")) {
     return null;
   }
-  const slots = collectSlotDefs(content);
-  const state = (content.state ?? {}) as Record<string, unknown>;
-  return {
-    $id: typeof content.$id === "string" && content.$id ? content.$id : null,
-    hasElements: Array.isArray(content.$elements) && content.$elements.length > 0,
+  const slots = collectSlotDefs(doc);
+  /*
+   * `state` is read the way `Object.entries` reads whatever is there: a malformed array or string
+   * yields its members, and a scalar or a missing entry yields nothing.
+   */
+  const declared = doc.state;
+  const state =
+    isJsonObject(declared) || Array.isArray(declared) || isString(declared)
+      ? Object.entries(declared)
+      : [];
+  // Everything before `tagName`, so `slots` lands where it always has in the serialized order.
+  const meta: Omit<ComponentMetaOut, "tagName"> = {
+    $id: isString(doc.$id) && doc.$id ? doc.$id : null,
+    hasElements: Array.isArray(doc.$elements) && doc.$elements.length > 0,
     path,
-    props: Object.entries(state)
-      .filter(([, def]) => isPropEntry(def))
-      .map(([name, def]) => {
-        if (typeof def !== "object" || def === null) {
-          // Shorthand: the value IS the default, and its runtime type is the only type on offer.
-          return { default: def as JsonValue, name, type: typeof def };
-        }
-        const obj = def as Record<string, unknown>;
-        return {
-          default: obj.default as JsonValue,
-          format: obj.format,
-          name,
-          type: obj.type,
-        };
-      }),
-    ...(slots.length > 0 ? { slots } : {}),
-    tagName,
+    props: state.flatMap(([name, def]) => {
+      const prop = propFrom(name, def);
+      return prop === null ? [] : [prop];
+    }),
   };
+  if (slots.length > 0) {
+    meta.slots = slots;
+  }
+  const uses = [...collectUsedTags(doc)].filter((tag) => tag !== tagName).toSorted();
+  if (uses.length > 0) {
+    meta.uses = uses;
+  }
+  return { ...meta, tagName };
 }

package/src/dialogs.ts

@@ -32,6 +32,7 @@ import {
   isPopover,
   labelOf,
   literalAttr,
+  OVERLAY_DOCS,
   popoverIdsIn,
   scalar,
   tagOf,
@@ -73,6 +74,12 @@ export const POPOVER_COMMANDS: ReadonlySet<string> = new Set([
 /** The values `closedby` takes. */
 export const DIALOG_CLOSEDBY = ["any", "closerequest", "none"] as const;
 
+/** {@link INVOKER_COMMANDS} as a lookup an attribute's literal text can be tested against. */
+const INVOKER_COMMAND_SET: ReadonlySet<string> = new Set(INVOKER_COMMANDS);
+
+/** {@link DIALOG_CLOSEDBY} as a lookup an attribute's literal text can be tested against. */
+const DIALOG_CLOSEDBY_SET: ReadonlySet<string> = new Set(DIALOG_CLOSEDBY);
+
 /**
  * Only a `<button>` carries `command` and `commandfor` (`HTMLButtonElement`, and no other
  * interface).
@@ -106,8 +113,6 @@ export interface DialogDefect {
   fix?: DialogFix;
 }
 
-const DOCS = "See docs/framework/concepts/overlays.";
-
 /** Whether the node is a `<dialog>`. */
 export function isDialog(node: JxElement): boolean {
   return tagOf(node) === "dialog";
@@ -142,7 +147,7 @@ export function documentHasDialog(doc: JxElement): boolean {
 
 /** Whether a node declares an `oncommand` handler, in any of the handler spellings. */
 function handlesCommand(node: JxElement): boolean {
-  const handler = (node as Record<string, unknown>).oncommand;
+  const handler = node.oncommand;
   return handler !== undefined && handler !== null;
 }
 
@@ -240,7 +245,7 @@ function invokerDefects(
       detail:
         "`command` and `commandfor` are attributes of `HTMLButtonElement` and of no other " +
         "interface — not even `<input>`, which `popovertarget` does allow. Elsewhere they parse " +
-        `and do nothing. Make it a <button>, or remove both attributes. ${DOCS}`,
+        `and do nothing. Make it a <button>, or remove both attributes. ${OVERLAY_DOCS}`,
       fix: "invoker",
       message: `<${tag || "element"}> carries command/commandfor, which only <button> supports.`,
       path,
@@ -250,16 +255,12 @@ function invokerDefects(
     return out;
   }
 
-  if (
-    command !== null &&
-    !(INVOKER_COMMANDS as readonly string[]).includes(command) &&
-    !isCustomCommand(command)
-  ) {
+  if (command !== null && !INVOKER_COMMAND_SET.has(command) && !isCustomCommand(command)) {
     out.push({
       detail:
         `\`command\` is an enumerated attribute taking ${INVOKER_COMMANDS.map((c) => `\`${c}\``).join(", ")}, ` +
         "or a custom command starting with `--`. Anything else is the invalid-value state, and a " +
-        `button in that state does nothing when clicked. ${DOCS}`,
+        `button in that state does nothing when clicked. ${OVERLAY_DOCS}`,
       message: `${label} declares command="${command}", which is not a built-in or --custom command.`,
       path,
       rule: "command-invalid",
@@ -277,7 +278,7 @@ function invokerDefects(
       out.push({
         detail:
           `No element in this document has the id "${target}". The dialogs and popovers here are: ${names}. ` +
-          `A commandfor that names nothing does nothing, silently. ${DOCS}`,
+          `A commandfor that names nothing does nothing, silently. ${OVERLAY_DOCS}`,
         message: `commandfor="${target}" names nothing in this document.`,
         path,
         rule: "command-target-missing",
@@ -290,7 +291,7 @@ function invokerDefects(
         out.push({
           detail:
             `\`${command}\` acts on a <dialog>, and "${target}" is ${targetsPopover ? "a popover" : `a <${tagOf(known) || "element"}>`}. ` +
-            `The click is ignored. ${targetsPopover ? "Use `toggle-popover`, `show-popover` or `hide-popover` for a popover." : "Point it at a dialog, or make the target one."} ${DOCS}`,
+            `The click is ignored. ${targetsPopover ? "Use `toggle-popover`, `show-popover` or `hide-popover` for a popover." : "Point it at a dialog, or make the target one."} ${OVERLAY_DOCS}`,
           message: `${label} sends ${command} to "${target}", which is not a dialog.`,
           path,
           rule: "command-target-mismatch",
@@ -300,7 +301,7 @@ function invokerDefects(
         out.push({
           detail:
             `\`${command}\` acts on a popover, and "${target}" is ${targetsDialog ? "a dialog" : `a <${tagOf(known) || "element"}>`} that declares no \`popover\`. ` +
-            `The click is ignored. ${targetsDialog ? "Use `show-modal`, `close` or `request-close` for a dialog." : "Give the target a `popover` attribute, or point the button elsewhere."} ${DOCS}`,
+            `The click is ignored. ${targetsDialog ? "Use `show-modal`, `close` or `request-close` for a dialog." : "Give the target a `popover` attribute, or point the button elsewhere."} ${OVERLAY_DOCS}`,
           message: `${label} sends ${command} to "${target}", which is not a popover.`,
           path,
           rule: "command-target-mismatch",
@@ -311,7 +312,7 @@ function invokerDefects(
           detail:
             `A custom command is a \`CommandEvent\` dispatched at its target, and "${target}" has no ` +
             "`oncommand` handler to answer it — so the click does nothing. Add one that switches on " +
-            `\`event#/command\`, or use a built-in command. ${DOCS}`,
+            `\`event#/command\`, or use a built-in command. ${OVERLAY_DOCS}`,
           message: `${label} sends ${command} to "${target}", which handles no command.`,
           path,
           rule: "custom-command-unhandled",
@@ -335,12 +336,12 @@ function dialogDefects(
   const { style } = node;
 
   const closedby = literalAttr(node, "closedby");
-  if (closedby !== null && !(DIALOG_CLOSEDBY as readonly string[]).includes(closedby)) {
+  if (closedby !== null && !DIALOG_CLOSEDBY_SET.has(closedby)) {
     out.push({
       detail:
         "`closedby` is an enumerated attribute taking `any` (light dismiss and Escape), " +
         "`closerequest` (Escape only, the default for a modal) or `none`. Anything else is the " +
-        `invalid-value default, \`auto\`, which is the same as leaving it out. ${DOCS}`,
+        `invalid-value default, \`auto\`, which is the same as leaving it out. ${OVERLAY_DOCS}`,
       message: `${label} declares closedby="${closedby}", which is not any, closerequest or none.`,
       path,
       rule: "dialog-closedby-invalid",
@@ -354,7 +355,7 @@ function dialogDefects(
         "A closed dialog is hidden by the browser's own `dialog:not([open]) { display: none }`. " +
         "That rule is UA-origin, so any author `display` beats it, and the dialog is laid out on " +
         "every page whether or not anyone opened it. `display` belongs in the `&[open]` rule and " +
-        `nowhere else. ${DOCS}`,
+        `nowhere else. ${OVERLAY_DOCS}`,
       fix: "display",
       message: `${label} sets display in its base rule.`,
       path,
@@ -372,7 +373,7 @@ function dialogDefects(
       detail:
         'No <button> in this document opens it with `command="show-modal"`. If it is opened from another ' +
         "file or from a function that calls `showModal()`, this is fine; otherwise there is no " +
-        `way for a reader to open it. ${DOCS}`,
+        `way for a reader to open it. ${OVERLAY_DOCS}`,
       message: `${label} has no invoker in this document.`,
       path,
       rule: "dialog-no-invoker",
@@ -386,7 +387,7 @@ function dialogDefects(
         "A modal dialog makes everything outside it inert, so the only ways out are the ones it " +
         'offers: `closedby="none"` turns off Escape and light dismiss, and nothing inside it ' +
         'closes it. A reader who opens it cannot leave. Add a <button command="close"> inside, or ' +
-        `drop \`closedby="none"\`. ${DOCS}`,
+        `drop \`closedby="none"\`. ${OVERLAY_DOCS}`,
       message: `${label} opens modally, closes on nothing, and has no close button.`,
       path,
       rule: "modal-without-close",

package/src/doc-ops.ts

@@ -15,18 +15,19 @@
  * @module @jxsuite/schema/doc-ops
  */
 
-import type { JxMutableNode, JxPath } from "../types.ts";
+import { isNonNullObject, isNumber } from "./guards";
+import type { JxDocumentValue, JxMutableNode, JxPath } from "../types.ts";
 
 /** Value-carrying document mutation, replayable in either direction. */
 export type JxDocOp =
   /** Set (or delete, when value is undefined) a key on the node at path. */
-  | { op: "set-key"; path: JxPath; key: string; value?: unknown }
+  | { op: "set-key"; path: JxPath; key: string; value?: JxDocumentValue | undefined }
   /** Insert a node at parentPath.children[index]. */
-  | { op: "insert-child"; parentPath: JxPath; index: number; node: unknown }
+  | { op: "insert-child"; parentPath: JxPath; index: number; node: JxMutableNode | string }
   /** Remove parentPath.children[index]. */
   | { op: "remove-child"; parentPath: JxPath; index: number }
   /** Replace parentPath.children[index] with node. */
-  | { op: "set-child"; parentPath: JxPath; index: number; node: unknown }
+  | { op: "set-child"; parentPath: JxPath; index: number; node: JxMutableNode | string }
   /** Raw two-splice move: remove fromParent.children[fromIndex], insert at toParent[toIndex]. */
   | {
       op: "move-child";
@@ -43,27 +44,34 @@ export interface JxDocOpPair {
 
 /** JSON round-trip clone — also normalizes away reactive proxies / functions / undefined. */
 function jsonClone<T>(value: T): T {
+  /* SAFETY: every value cloned here is document data (a node, a children member, or a key's value),
+     which is JSON by contract; the round trip reproduces that shape and drops only functions and
+     `undefined` members, which the document types already treat as absent. */
   // oxlint-disable-next-line unicorn/prefer-structured-clone -- structuredClone throws on reactive proxies; JSON normalization is the point
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
 /** Deep-clone a recorded value (undefined/null pass through; reactive proxies are read through). */
 export function cloneValue<T>(v: T): T {
-  return v === undefined || v === null ? v : (jsonClone(v as object) as T);
+  return v === undefined || v === null ? v : jsonClone(v);
 }
 
 /**
- * Walk a plain document tree by path. Paths address nodes by construction; missing segments and
- * non-node leaves surface as undefined (typed as node for caller ergonomics, matching Studio's
- * historical helper).
+ * Walk a plain document tree by path. Paths address nodes by construction; a missing segment
+ * surfaces as undefined, so every caller checks the answer before treating it as a node.
  */
-export function getNodeAtPath(doc: JxMutableNode, path: JxPath): JxMutableNode {
-  let node = doc;
+export function getNodeAtPath(doc: JxMutableNode, path: JxPath): JxMutableNode | undefined {
+  let node: JxMutableNode | undefined = doc;
   for (const key of path) {
+    // `== null` also stops at a JSON `null` partway down the path.
     if (node == null) {
-      return undefined as unknown as JxMutableNode;
+      return undefined;
     }
-    node = node[key] as JxMutableNode;
+    /* SAFETY: a `JxPath` alternates node keys with a "children" key and an index, so each step
+       lands on a node, on a children array (whose only use is the next, numeric, lookup, which an
+       array answers as a node would), or on nothing. A path that wrongly ends on a string child or a
+       children array reaches a caller as one; `childArray` and `insertableChildren` refuse it. */
+    node = node[key] as JxMutableNode | undefined;
   }
   return node;
 }
@@ -90,44 +98,40 @@ export function childArray(node: JxMutableNode): (JxMutableNode | string)[] {
  * aliases the op object. Throws (with a machine-readable reason) when a target path is missing.
  */
 export function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp): void {
+  // Read before the switch: an op from outside may carry a kind the union does not name.
+  const { op: kind } = op;
   switch (op.op) {
     case "set-key": {
       const node = getNodeAtPath(doc, op.path);
       if (!node) {
         throw new Error(`doc-op-node-not-found:${op.path.join("/")}`);
       }
-      const target = node as Record<string, unknown>;
       if (op.value === undefined) {
-        delete target[op.key];
+        delete node[op.key];
       } else {
-        target[op.key] = cloneValue(op.value);
+        node[op.key] = cloneValue(op.value);
       }
       return;
     }
     case "insert-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 0, cloneValue(op.node) as JxMutableNode);
+      childArrayAt(doc, op.parentPath).splice(op.index, 0, cloneValue(op.node));
       return;
     }
     case "remove-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 1);
+      childArrayAt(doc, op.parentPath).splice(op.index, 1);
       return;
     }
     case "set-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 1, cloneValue(op.node) as JxMutableNode);
+      childArrayAt(doc, op.parentPath).splice(op.index, 1, cloneValue(op.node));
       return;
     }
     case "move-child": {
       assertNotIntoOwnSubtree(op);
-      const fromParent = getNodeAtPath(doc, op.fromParentPath);
-      const toParent = getNodeAtPath(doc, op.toParentPath);
       /* Both arrays are resolved BEFORE the source is spliced, so a move whose target cannot receive
          children throws with the document untouched rather than having detached the node it could
          not place. */
-      const from = childArray(fromParent);
-      const to = childArray(toParent);
+      const from = childArrayAt(doc, op.fromParentPath);
+      const to = childArrayAt(doc, op.toParentPath);
       const [node] = from.splice(op.fromIndex, 1);
       to.splice(op.toIndex, 0, node!);
       return;
@@ -136,7 +140,19 @@ export function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp): void {
       break;
     }
   }
-  throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
+  throw new Error(`unknown-doc-op:${kind}`);
+}
+
+/**
+ * The children array of the node at `parentPath`, lazily created (see {@link childArray}); throws a
+ * `TypeError` naming the path when no node is there.
+ */
+function childArrayAt(doc: JxMutableNode, parentPath: JxPath): (JxMutableNode | string)[] {
+  const parent = getNodeAtPath(doc, parentPath);
+  if (parent == null) {
+    throw new TypeError(`doc-op-node-not-found:${parentPath.join("/")}`);
+  }
+  return childArray(parent);
 }
 
 /**
@@ -155,10 +171,10 @@ function shiftThroughSplice(
 ): JxPath {
   const depth = parentPath.length;
   const isProperPrefix = depth < path.length && parentPath.every((seg, i) => seg === path[i]);
-  if (!isProperPrefix || path[depth] !== "children" || typeof path[depth + 1] !== "number") {
+  const index = path[depth + 1];
+  if (!isProperPrefix || path[depth] !== "children" || !isNumber(index)) {
     return path;
   }
-  const index = path[depth + 1] as number;
   if (inclusive ? index < spliceIndex : index <= spliceIndex) {
     return path;
   }
@@ -218,13 +234,15 @@ function insertionSlot(index: number, length: number): number {
  * @returns {JxDocOp}
  */
 export function inverseOf(doc: JxMutableNode, op: JxDocOp): JxDocOp {
+  // Read before the switch: an op from outside may carry a kind the union does not name.
+  const { op: kind } = op;
   switch (op.op) {
     case "set-key": {
       const node = getNodeAtPath(doc, op.path);
       if (!node) {
         throw new Error(`doc-op-node-not-found:${op.path.join("/")}`);
       }
-      const before = cloneValue((node as Record<string, unknown>)[op.key]);
+      const before = cloneValue(node[op.key]);
       return before === undefined
         ? { key: op.key, op: "set-key", path: op.path }
         : { key: op.key, op: "set-key", path: op.path, value: before };
@@ -271,7 +289,7 @@ export function inverseOf(doc: JxMutableNode, op: JxDocOp): JxDocOp {
       break;
     }
   }
-  throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
+  throw new Error(`unknown-doc-op:${kind}`);
 }
 
 /** The node's existing children array, or null when it has none (or is not a node). */
@@ -292,10 +310,15 @@ function assertIndex(
 }
 
 /** A clone of `parentPath`'s child at `index`, or the applier's reason when there is none. */
-function existingChild(doc: JxMutableNode, parentPath: JxPath, index: number): unknown {
+function existingChild(
+  doc: JxMutableNode,
+  parentPath: JxPath,
+  index: number,
+): JxMutableNode | string {
   const children = childrenAt(doc, parentPath);
   assertIndex(children, parentPath, index);
-  return cloneValue(children[index]);
+  // `assertIndex` has just proven `index` is in range.
+  return cloneValue(children[index]!);
 }
 
 /**
@@ -304,8 +327,9 @@ function existingChild(doc: JxMutableNode, parentPath: JxPath, index: number): u
  * children array addressed as if it were a node, or a mapped-array `children`.
  */
 function insertableChildren(doc: JxMutableNode, parentPath: JxPath): (JxMutableNode | string)[] {
-  const node = getNodeAtPath(doc, parentPath) as unknown as { children?: unknown } | null;
-  if (!node || typeof node !== "object" || Array.isArray(node)) {
+  const node = getNodeAtPath(doc, parentPath);
+  // A path that ends on a string child or a children array is refused here, not just a missing one.
+  if (!isNonNullObject(node) || Array.isArray(node)) {
     throw new Error(`doc-op-node-not-found:${parentPath.join("/")}`);
   }
   if (node.children === undefined) {
@@ -314,7 +338,7 @@ function insertableChildren(doc: JxMutableNode, parentPath: JxPath): (JxMutableN
   if (!Array.isArray(node.children)) {
     throw new TypeError(`doc-op-mapped-children:${parentPath.join("/")}`);
   }
-  return node.children as (JxMutableNode | string)[];
+  return node.children;
 }
 
 /**

package/src/extension-registry.ts

@@ -11,8 +11,10 @@
  * format-dispatch view reuses FormatRegistry (including its extension/capability conflict checks).
  */
 
-import { FormatEntry, FormatRegistry } from "./format-registry";
+import { FormatEntry, FormatRegistry, classDefFrom } from "./format-registry";
 import type { FormatHostIO } from "./format-registry";
+import { isJsonObject, isString } from "./guards";
+import type { JsonObject, JsonValue } from "../types";
 
 export type {
   CapabilityInfo,
@@ -240,18 +242,23 @@ async function loadExtension(
     }
   }
 
-  let manifest: ExtensionManifest;
+  let loaded: JsonValue;
   try {
-    manifest = (await io.loadJson(manifestPath)) as unknown as ExtensionManifest;
+    loaded = await io.loadJson(manifestPath);
   } catch (error) {
     throw new Error(
       `Extension "${specifier}": cannot read manifest ${manifestPath}: ${errorMessage(error)}`,
       { cause: error },
     );
   }
-  if (!manifest || typeof manifest !== "object" || typeof manifest.name !== "string") {
+  if (!isJsonObject(loaded) || !isString(loaded.name)) {
     throw new Error(`Extension "${specifier}": ${EXTENSION_MANIFEST} must declare a "name"`);
   }
+  /* SAFETY: `name` was just checked to be a string. The other members are the shapes
+     extension-manifest.schema.json declares (string `title`/`description`, a `classes` map of
+     paths, a `schemas` record of paths), which every first-party extension's manifest test
+     validates its manifest against; this module resolves only the paths. */
+  const manifest: ExtensionManifest = loaded as JsonObject & ExtensionManifest;
   if (!specifier.startsWith(".") && manifest.name !== specifier) {
     throw new Error(
       `Extension "${specifier}": manifest name "${manifest.name}" does not match the specifier`,
@@ -261,7 +268,7 @@ async function loadExtension(
   const classes: FormatEntry[] = [];
   for (const [name, ref] of Object.entries(manifest.classes ?? {})) {
     const classPath = io.resolvePath(manifestPath, ref);
-    let classDef: Record<string, unknown>;
+    let classDef: JsonValue;
     try {
       classDef = await io.loadJson(classPath);
     } catch (error) {
@@ -270,7 +277,7 @@ async function loadExtension(
         { cause: error },
       );
     }
-    classes.push(new FormatEntry(name, classPath, classDef, io));
+    classes.push(new FormatEntry(name, classPath, classDefFrom(classDef), io));
   }
 
   const schemas: ExtensionInfo["schemas"] = {};
@@ -287,6 +294,6 @@ async function loadExtension(
   return { specifier, manifestPath, manifest, classes, schemas };
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+function errorMessage(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
 }