@jxsuite/schema 4.0.0 → 5.0.0

package/defs/children-value.schema.ts

@@ -15,7 +15,7 @@ export const arrayNamespaceSchema = {
         "removals; without a key, rows are keyed by index. $map/index is not a key — an index " +
         "names a position, not a row.",
       properties: {
-        $ref: { pattern: "^\\$map/item(/.+)?$", type: "string" },
+        $ref: { pattern: String.raw`^\$map/item(/.+)?$`, type: "string" },
       },
       required: ["$ref"],
       type: "object",
@@ -60,7 +60,7 @@ export const childrenValueSchema = {
         "Computed children — a ${…} template that resolves at build time to an array of child " +
         'definitions (e.g. "${state.entry.$children}" for parsed content). A bare plain-text ' +
         "string is NOT a valid children value; text children must be array items.",
-      pattern: "\\$\\{",
+      pattern: String.raw`\$\{`,
       type: "string",
     },
   ],

package/defs/class-def.schema.ts

@@ -167,7 +167,7 @@ export const formatDefSchema = {
     },
     extensions: {
       description: 'File extensions this format claims, with leading dot (e.g. [".md"]).',
-      items: { pattern: "^\\.", type: "string" },
+      items: { pattern: String.raw`^\.`, type: "string" },
       minItems: 1,
       type: "array",
     },

package/defs/expression-node.schema.ts

@@ -6,7 +6,7 @@ export const expressionPointerSchema = {
     "A JSON Pointer $ref operand within an expression node. $args/<name> resolves a named formula's parameter (callable entries only).",
   properties: {
     $ref: {
-      pattern: "^(\\$map/|\\$reduce/|\\$args/|event#/|#/|parent#/|window#/|document#/)",
+      pattern: String.raw`^(\$map/|\$reduce/|\$args/|event#/|#/|parent#/|window#/|document#/)`,
       type: "string",
     },
   },
@@ -16,7 +16,7 @@ export const expressionPointerSchema = {
 
 export const expressionLiteralSchema = {
   anyOf: [
-    { not: { pattern: "\\$\\{" }, type: "string" },
+    { not: { pattern: String.raw`\$\{` }, type: "string" },
     { type: "number" },
     { type: "boolean" },
     { type: "null" },

package/defs/ref-object.schema.ts

@@ -1,7 +1,7 @@
 export const internalRefSchema = {
   description: "Reference to a $defs type definition in the current component.",
   examples: ["#/$defs/Count", "#/$defs/TodoItem", "#/$defs/Status"],
-  pattern: "^#/\\$defs/",
+  pattern: String.raw`^#/\$defs/`,
   type: "string",
 } as const;
 
@@ -15,7 +15,7 @@ export const stateRefSchema = {
 export const externalRefSchema = {
   description: "Reference to an external Jx component file.",
   examples: ["./card.json", "https://cdn.example.com/button.json"],
-  pattern: "^(\\./|\\.\\./).*\\.json$|^https?://",
+  pattern: String.raw`^(\./|\.\./).*\.json$|^https?://`,
   type: "string",
 } as const;
 
@@ -36,7 +36,7 @@ export const parentRefSchema = {
 export const mapRefSchema = {
   description: "Reference to the current Array map iteration context.",
   examples: ["$map/item", "$map/index", "$map/item/text", "$map/item/done"],
-  pattern: "^\\$map/(item|index)(/.*)?$",
+  pattern: String.raw`^\$map/(item|index)(/.*)?$`,
   type: "string",
 } as const;
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "dependencies": {
-    "@webref/css": "^8.7.7",
+    "@webref/css": "^8.7.8",
     "@webref/elements": "^2.9.2",
-    "@webref/idl": "^3.85.2",
+    "@webref/idl": "^3.86.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },
@@ -20,6 +20,7 @@
     "./locale": "./src/locale.ts",
     "./intl": "./src/intl.ts",
     "./media-type": "./src/media-type.ts",
+    "./which": "./src/which.ts",
     "./overlays": "./src/overlays.ts",
     "./dialogs": "./src/dialogs.ts",
     "./a11y": "./src/a11y.ts",
@@ -60,7 +61,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "type": "module",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/src/component-meta.ts

@@ -8,8 +8,8 @@
  *
  * It lives here because THREE backends need the same answer and two of them had already written it
  * twice: `packages/server/src/studio-api.ts` (the dev server's `/__studio/components`) and
- * `packages/desktop/src/project-session.ts`. A third copy in the cloud adapter would have made
- * "which entries in `state` count as props" a question with three answers.
+ * `packages/desktop/src/backend/project-session.ts`. A third copy in the cloud adapter would have
+ * made "which entries in `state` count as props" a question with three answers.
  *
  * @license MIT
  */

package/src/doc-ops.ts

@@ -15,8 +15,8 @@
  * @module @jxsuite/schema/doc-ops
  */
 
-import { isNonNullObject, isNumber } from "./guards";
-import type { JxDocumentValue, JxMutableNode, JxPath } from "../types.ts";
+import { isNonNullObject, isNumber, isString } from "./guards";
+import type { JsonValue, JxDocumentValue, JxMutableNode, JxPath } from "../types.ts";
 
 /** Value-carrying document mutation, replayable in either direction. */
 export type JxDocOp =
@@ -161,8 +161,15 @@ function childArrayAt(doc: JxMutableNode, parentPath: JxPath): (JxMutableNode |
  * insertion (delta +1, inclusive) shifts them up. Returns `path` unchanged when the splice does not
  * affect it — including when `path` IS `parentPath`, since a splice moves a node's children, never
  * the node.
+ *
+ * @param {JxPath} parentPath - The node whose children were spliced
+ * @param {JxPath} path - The path to translate
+ * @param {number} spliceIndex - Where the splice happened
+ * @param {number} delta - -1 for a removal, +1 for an insertion
+ * @param {boolean} inclusive - Whether a path AT the index shifts (an insertion's rule)
+ * @returns {JxPath}
  */
-function shiftThroughSplice(
+export function shiftPrefixedIndex(
   parentPath: JxPath,
   path: JxPath,
   spliceIndex: number,
@@ -201,7 +208,7 @@ function assertNotIntoOwnSubtree(op: Extract<JxDocOp, { op: "move-child" }>): vo
  * counts from the end and an index past the end appends. The applier inserts with `splice`, so an
  * inverse must name the slot the node really landed in, not the one the op asked for.
  */
-function insertionSlot(index: number, length: number): number {
+export function insertionSlot(index: number, length: number): number {
   return index < 0 ? Math.max(length + index, 0) : Math.min(index, length);
 }
 
@@ -236,12 +243,18 @@ function insertionSlot(index: number, length: number): number {
 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;
+  assertIntegerIndexes(op);
   switch (op.op) {
     case "set-key": {
       const node = getNodeAtPath(doc, op.path);
-      if (!node) {
+      if (node === undefined) {
         throw new Error(`doc-op-node-not-found:${op.path.join("/")}`);
       }
+      /* A key set on a text child or a children array lands nowhere a renderer reads, so the edit
+         would succeed without effect; on `null` it would throw mid-transaction. */
+      if (!isNonNullObject(node) || Array.isArray(node)) {
+        throw new TypeError(`doc-op-not-a-node:${op.path.join("/")}`);
+      }
       const before = cloneValue(node[op.key]);
       return before === undefined
         ? { key: op.key, op: "set-key", path: op.path }
@@ -273,7 +286,7 @@ export function inverseOf(doc: JxMutableNode, op: JxDocOp): JxDocOp {
       return {
         fromIndex: toIndex,
         // The removal shifted paths under the source parent; the insertion, under the target.
-        fromParentPath: shiftThroughSplice(
+        fromParentPath: shiftPrefixedIndex(
           op.fromParentPath,
           op.toParentPath,
           op.fromIndex,
@@ -282,7 +295,7 @@ export function inverseOf(doc: JxMutableNode, op: JxDocOp): JxDocOp {
         ),
         op: "move-child",
         toIndex: op.fromIndex,
-        toParentPath: shiftThroughSplice(op.toParentPath, op.fromParentPath, toIndex, 1, true),
+        toParentPath: shiftPrefixedIndex(op.toParentPath, op.fromParentPath, toIndex, 1, true),
       };
     }
     default: {
@@ -292,6 +305,26 @@ export function inverseOf(doc: JxMutableNode, op: JxDocOp): JxDocOp {
   throw new Error(`unknown-doc-op:${kind}`);
 }
 
+/**
+ * Throw `doc-op-index:<path>` unless every index the op carries is an integer. A numeric string, a
+ * fraction or `NaN` would reach `splice`, which coerces or truncates it, so the op would land in a
+ * slot its recorded inverse does not name. Producers coerce canonical numeric strings before they
+ * build an op; this is the defence behind them.
+ */
+function assertIntegerIndexes(op: JxDocOp): void {
+  const indexes: [JxPath, unknown][] = [];
+  if (op.op === "move-child") {
+    indexes.push([op.fromParentPath, op.fromIndex], [op.toParentPath, op.toIndex]);
+  } else if (op.op === "insert-child" || op.op === "remove-child" || op.op === "set-child") {
+    indexes.push([op.parentPath, op.index]);
+  }
+  for (const [parentPath, index] of indexes) {
+    if (!Number.isInteger(index)) {
+      throw new TypeError(`doc-op-index:${[...parentPath, "children", String(index)].join("/")}`);
+    }
+  }
+}
+
 /** The node's existing children array, or null when it has none (or is not a node). */
 function childrenAt(doc: JxMutableNode, parentPath: JxPath): (JxMutableNode | string)[] | null {
   const parent = getNodeAtPath(doc, parentPath);
@@ -370,3 +403,197 @@ export function applyDocOpsWithInverse(doc: JxMutableNode, ops: readonly JxDocOp
   }
   return pairs;
 }
+
+// ─── Paths ───────────────────────────────────────────────────────────────────
+
+/**
+ * Whether `path` is an ancestor of (or equal to) `descendant`.
+ *
+ * @param {JxPath} path
+ * @param {JxPath} descendant
+ * @returns {boolean}
+ */
+export function isAncestor(path: JxPath, descendant: JxPath): boolean {
+  if (path.length > descendant.length) {
+    return false;
+  }
+  return path.every((v, i) => v === descendant[i]);
+}
+
+/**
+ * Order two paths the way the document reads: parents before children, siblings by index.
+ *
+ * Segments are compared pairwise; numbers numerically (so `children/10` follows `children/9`), and
+ * anything else by string order. A prefix sorts before what extends it.
+ *
+ * @param {JxPath} a
+ * @param {JxPath} b
+ * @returns {number}
+ */
+export function comparePaths(a: JxPath, b: JxPath): number {
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const x = a[i]!;
+    const y = b[i]!;
+    if (x === y) {
+      continue;
+    }
+    if (isNumber(x) && isNumber(y)) {
+      return x - y;
+    }
+    return String(x) < String(y) ? -1 : 1;
+  }
+  return a.length - b.length;
+}
+
+/**
+ * Drop any path whose ancestor is also in the list.
+ *
+ * Deleting a `<section>` and one of its own paragraphs is one deletion, not two: the paragraph goes
+ * with its parent, and a second splice into coordinates that no longer exist is how a batch
+ * corrupts a document.
+ *
+ * @param {readonly JxPath[]} paths
+ * @returns {JxPath[]}
+ */
+export function topLevelSelection(paths: readonly JxPath[]): JxPath[] {
+  const top: JxPath[] = [];
+  for (const path of paths) {
+    if (!paths.some((q) => !samePath(q, path) && isAncestor(q, path))) {
+      top.push([...path]);
+    }
+  }
+  return top;
+}
+
+function samePath(a: JxPath, b: JxPath): boolean {
+  return a.length === b.length && isAncestor(a, b);
+}
+
+/** Where a structural verb splices: the parent element's path and the index in its children. */
+export interface SpliceCoordinate {
+  parentPath: JxPath;
+  index: number;
+}
+
+/**
+ * The splice coordinate `path` names, or `null` for no path and for every path
+ * {@link isSpliceablePath} refuses.
+ *
+ * @param {JxPath | null | undefined} path
+ * @returns {SpliceCoordinate | null}
+ */
+export function spliceCoordinate(path: JxPath | null | undefined): SpliceCoordinate | null {
+  const index = path?.at(-1);
+  return path && path.at(-2) === "children" && isNumber(index)
+    ? { index, parentPath: path.slice(0, -2) }
+    : null;
+}
+
+/**
+ * Whether `path` names a position a structural edit can splice: a tail of `"children"` + index.
+ *
+ * Every structural edit reaches its parent by dropping the last two segments and its position by
+ * taking the last. That produces a splice coordinate for exactly one path shape, and a document
+ * holds three others a caller can name: the document element (`[]`), a repeater's map template
+ * (`[…, "children", "map"]`) and a `$switch` case (`[…, "cases", "warn"]`). For the template, the
+ * parent resolves to a children ARRAY, so the splice throws mid-edit; for a case it splices at
+ * `NaN` and takes the wrong child.
+ *
+ * @param {JxPath} path
+ * @returns {boolean}
+ */
+export function isSpliceablePath(path: JxPath): boolean {
+  return spliceCoordinate(path) !== null;
+}
+
+/**
+ * The order a structural batch must run in: contained paths dropped, unspliceable paths dropped,
+ * then LAST node first.
+ *
+ * Descending document order is what makes a loop of splices safe. Removing or duplicating at index
+ * `n` renumbers every sibling after `n`, so a batch that starts at the end never touches a
+ * coordinate a later step still needs.
+ *
+ * Containment is decided BEFORE spliceability, on the paths as given: a repeater template still
+ * shadows its own descendants, so naming the template and something inside it yields nothing rather
+ * than quietly deleting the child nobody pointed at.
+ *
+ * @param {readonly JxPath[]} paths
+ * @returns {JxPath[]} Deepest/last first, every entry a splice coordinate.
+ */
+export function structuralBatch(paths: readonly JxPath[]): JxPath[] {
+  return topLevelSelection(paths)
+    .filter((path) => isSpliceablePath(path))
+    .toSorted((a, b) => comparePaths(b, a));
+}
+
+/**
+ * An index written as JSON a model or a form produced, as the integer it names: an integer passes,
+ * a canonical decimal string (`"0"`, `"12"`, never `"01"`, `"1.0"` or `" 2"`) becomes its number,
+ * and anything else is `null`. Negative integers pass; whether one is meaningful is the caller's.
+ *
+ * @param {JsonValue | undefined} value - A tool argument or form field, as parsed JSON
+ * @returns {number | null}
+ */
+export function coerceIndex(value: JsonValue | undefined): number | null {
+  if (isNumber(value) && Number.isInteger(value)) {
+    return value;
+  }
+  return isString(value) && /^(?:0|[1-9]\d*)$/.test(value) ? Number(value) : null;
+}
+
+/** A move's forward and inverse ops, both `move-child`. */
+export interface PlannedMove {
+  forward: Extract<JxDocOp, { op: "move-child" }>;
+  inverse: Extract<JxDocOp, { op: "move-child" }>;
+}
+
+/**
+ * The ops that move the node at `fromPath` to `toIndex` of `toParentPath`'s children, without
+ * moving anything; null when the move cannot happen (the source is no child in a static children
+ * array, or the target is no node).
+ *
+ * `toIndex` is read as the slot in the target's children BEFORE the move, the way a drop indicator
+ * names it, so a move later in the same parent lands one earlier once the source is gone. A slot
+ * past the end is clamped to the last one, so the forward names where the node really lands. Throws
+ * `doc-op-move-into-self` when the target is inside the moved node.
+ *
+ * @param {JxMutableNode} doc - The document the move applies to
+ * @param {JxPath} fromPath
+ * @param {JxPath} toParentPath
+ * @param {number} toIndex
+ * @returns {PlannedMove | null}
+ */
+export function planMove(
+  doc: JxMutableNode,
+  fromPath: JxPath,
+  toParentPath: JxPath,
+  toIndex: number,
+): PlannedMove | null {
+  const at = spliceCoordinate(fromPath);
+  const fromParent = at && getNodeAtPath(doc, at.parentPath);
+  const toParent = getNodeAtPath(doc, toParentPath);
+  if (!at || !fromParent || !Array.isArray(fromParent.children) || !toParent) {
+    return null;
+  }
+  if (fromParent.children[at.index] === undefined) {
+    return null;
+  }
+  const sameParent = fromParent === toParent;
+  const adjusted = sameParent && at.index < toIndex ? toIndex - 1 : toIndex;
+  const targetLength = Array.isArray(toParent.children) ? toParent.children.length : 0;
+  const forward: PlannedMove["forward"] = {
+    fromIndex: at.index,
+    fromParentPath: at.parentPath,
+    op: "move-child",
+    toIndex: insertionSlot(adjusted, targetLength - (sameParent ? 1 : 0)),
+    toParentPath,
+  };
+  /* Computed against the document the move applies to. The inverse runs against the post-move
+     document, so `inverseOf` writes both of its parent paths in post-move coordinates: the removal
+     shifted paths under the source parent, the insertion paths under the target. */
+  const inverse = inverseOf(doc, forward);
+  /* SAFETY: `inverseOf` answers a `move-child` for a `move-child`. */
+  return { forward, inverse: inverse as PlannedMove["inverse"] };
+}

package/src/validate-project.ts

@@ -111,9 +111,11 @@ export async function validateProjectFile(projectRoot: string): Promise<ProjectV
 }
 
 /**
- * Restricted schema loader: only `file:` URLs inside the project root are served. Missing files
- * under `<root>/node_modules/` fall back to host resolution of the corresponding bare specifier
- * (in-repo starters have no local node_modules; the fragments still ship with the host).
+ * Restricted schema loader: only `file:` URLs inside the project root are served. A missing file
+ * under `<root>/node_modules/` resolves its bare specifier through the project's own resolution
+ * (in-repo starters have no local node_modules and walk up to the workspace's). Only this package's
+ * own core schemas fall back to the host: an extension's fragments, first-party ones included, are
+ * the project's to supply (specs/extensions.md §5.4).
  *
  * @param {string} uri - The `$ref` target ajv could not resolve from already-loaded resources
  * @param {string} root - Absolute project root
@@ -137,8 +139,8 @@ async function loadProjectSchemaRef(uri: string, root: string): Promise<JsonValu
     return readJson(filePath);
   }
 
-  // Host fallback: <root>/node_modules/<specifier> is absent — resolve the specifier through the
-  // Project's own resolution first, then the host's (workspace symlinks resolve transparently).
+  // <root>/node_modules/<specifier> is absent — resolve the specifier through the project's own
+  // Resolution (workspace symlinks resolve transparently), and through the host only for the core.
   const posixRel = rel.split("\\").join("/");
   const marker = "node_modules/";
   const markerIndex = posixRel.lastIndexOf(marker);
@@ -147,32 +149,37 @@ async function loadProjectSchemaRef(uri: string, root: string): Promise<JsonValu
   }
   const specifier = posixRel.slice(markerIndex + marker.length);
 
+  const ownPrefix = "@jxsuite/schema/";
   let resolved: string;
   try {
     const projRequire = createRequire(resolve(root, "package.json"));
     resolved = projRequire.resolve(specifier);
-  } catch {
+  } catch (error) {
+    if (!specifier.startsWith(ownPrefix)) {
+      throw new Error(
+        `Schema ref "${uri}" does not exist and "${specifier}" is not resolvable from the ` +
+          `project — is the package installed?`,
+        { cause: error },
+      );
+    }
     try {
       const selfRequire = createRequire(import.meta.url);
       resolved = selfRequire.resolve(specifier);
-    } catch (error) {
+    } catch (hostError) {
       // Exports-map subpath resolution is brittle against version-skewed shadowing installs (a
       // Stale local copy terminates Node's walk-up with ERR_PACKAGE_PATH_NOT_EXPORTED). Our own
       // Schema files are pure data and the running validator's copy is guaranteed to match, so
       // Read them straight off this package's disk as the last resort.
-      const ownPrefix = "@jxsuite/schema/";
-      if (specifier.startsWith(ownPrefix)) {
-        const ownFile = fileURLToPath(
-          new URL(`../${specifier.slice(ownPrefix.length)}`, import.meta.url),
-        );
-        if (existsSync(ownFile)) {
-          return readJson(ownFile);
-        }
+      const ownFile = fileURLToPath(
+        new URL(`../${specifier.slice(ownPrefix.length)}`, import.meta.url),
+      );
+      if (existsSync(ownFile)) {
+        return readJson(ownFile);
       }
       throw new Error(
         `Schema ref "${uri}" does not exist and "${specifier}" is not resolvable from the ` +
-          `project or the host`,
-        { cause: error },
+          `project or this host's core`,
+        { cause: hostError },
       );
     }
   }

package/src/which.ts

@@ -0,0 +1,75 @@
+/**
+ * Find an executable the way `Bun.which` does, on `node:fs` alone.
+ *
+ * The desktop backend runs on Electron's Node (specs/desktop.md §7.1), so the code it reaches
+ * cannot call `Bun.which`. The answer is held to Bun's by `tests/which.test.ts`: a name containing
+ * a path separator is resolved against the working directory and returned when it is an executable
+ * regular file; any other name is looked up in each non-empty `PATH` entry in order. On Windows,
+ * where every file passes an `X_OK` check, only a launchable name counts: one that already ends in
+ * `.exe`, `.cmd`, `.bat` or `.com` is tried as written, and any other gets each of those appended
+ * in that order. Like Bun, it ignores `PATHEXT`, whose `.js` and `.vbs` entries name files a
+ * process cannot spawn. The path returned is the one that was tried, so an appended extension is
+ * lower case whatever the file's own case, and never its realpath.
+ *
+ * Node-only: it reads the filesystem, unlike the rest of this package's browser-safe modules.
+ */
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, join, resolve } from "node:path";
+
+/** True when `path` is a regular file this process may execute. */
+function isExecutable(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) {
+      return false;
+    }
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The extensions Bun's `which` tries on Windows, in its order. */
+const WINDOWS_EXTENSIONS = [".exe", ".cmd", ".bat", ".com"];
+
+/**
+ * The names to try for `name`: itself elsewhere; on Windows, only names with a launchable
+ * extension.
+ */
+function candidates(name: string, platform: NodeJS.Platform): string[] {
+  if (platform !== "win32") {
+    return [name];
+  }
+  const lower = name.toLowerCase();
+  if (WINDOWS_EXTENSIONS.some((extension) => lower.endsWith(extension))) {
+    return [name];
+  }
+  return WINDOWS_EXTENSIONS.map((extension) => `${name}${extension}`);
+}
+
+/**
+ * The absolute path of the executable `name`, or null when there is none.
+ *
+ * @param name A command name, or a path (absolute, or relative to the working directory)
+ * @param options `PATH` overrides the environment's search path
+ */
+export function which(
+  name: string,
+  options: { PATH?: string; platform?: NodeJS.Platform } = {},
+): string | null {
+  if (name === "") {
+    return null;
+  }
+  const platform = options.platform ?? process.platform;
+  if (name.includes("/") || (platform === "win32" && name.includes("\\"))) {
+    return candidates(resolve(name), platform).find((path) => isExecutable(path)) ?? null;
+  }
+  const dirs = (options.PATH ?? process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const found = candidates(join(dir, name), platform).find((path) => isExecutable(path));
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}