@jxsuite/schema 2.2.0 → 3.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Kevin Shenk
+Copyright (c) 2026 Avunu LLC and Jx Suite contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -42,6 +42,13 @@ const schema = await generateSchema(); // component meta-schema object
 const valid = await validateDocument(doc); // validate a Jx document
 ```
 
+## Documents as data
+
+Two subpaths let any host edit and write a Jx document the way Studio does, with no DOM, no reactive store and no yjs:
+
+- **`@jxsuite/schema/doc-ops`** is the document-op vocabulary. A `JxDocOp` (`set-key`, `insert-child`, `remove-child`, `set-child`, `move-child`) is a value-carrying mutation addressed by `JxPath`. `applyDocOpToDoc(doc, op)` applies one to a plain tree; `inverseOf(doc, op)` computes the op that undoes it, against the document as it stands before the op, in the coordinates of the document after it; `applyDocOpsWithInverse(doc, ops)` applies a sequence and answers each forward/inverse pair. Studio's history, the canvas iframe's shadow document and the collab bridge all replay through this one implementation, and `@jxsuite/collab/ops` re-exports it. Undoing an insert or move into a node that had no `children` leaves `children: []` behind, as Studio's history always has.
+- **`@jxsuite/schema/json-layout`** is the layout-preserving JSON serializer behind every save. `parseJsonDocument(text)` answers the document and the facts about its text the formatter keeps; `serializeJson(document, layout)` writes it back with those honoured, so a one-value edit is a one-line diff.
+
 ## Component schema coverage
 
 - **`tagName`**: all standard HTML element names from `@webref/elements`

package/package.json

@@ -1,8 +1,8 @@
 {
   "dependencies": {
-    "@webref/css": "^8.7.4",
-    "@webref/elements": "^2.8.0",
-    "@webref/idl": "^3.83.1",
+    "@webref/css": "^8.7.5",
+    "@webref/elements": "^2.9.0",
+    "@webref/idl": "^3.85.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },
@@ -25,6 +25,8 @@
     "./a11y": "./src/a11y.ts",
     "./ijson": "./src/ijson.ts",
     "./parse": "./src/parse.ts",
+    "./doc-ops": "./src/doc-ops.ts",
+    "./json-layout": "./src/json-layout.ts",
     "./defs": "./defs/index.ts",
     "./schema.json": "./schema.json",
     "./project-schema.json": "./project-schema.json",
@@ -58,7 +60,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "type": "module",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/schema.json

@@ -3578,6 +3578,20 @@
             }
           ]
         },
+        "oninstallresult": {
+          "description": "Event handler for the \"installresult\" event.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/RefObject"
+            },
+            {
+              "$ref": "#/$defs/ExpressionEntry"
+            },
+            {
+              "$ref": "#/$defs/FunctionDef"
+            }
+          ]
+        },
         "oninvalid": {
           "description": "Event handler for the \"invalid\" event.",
           "oneOf": [
@@ -5636,6 +5650,34 @@
             }
           ]
         },
+        "ontoolactivated": {
+          "description": "Event handler for the \"toolactivated\" event.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/RefObject"
+            },
+            {
+              "$ref": "#/$defs/ExpressionEntry"
+            },
+            {
+              "$ref": "#/$defs/FunctionDef"
+            }
+          ]
+        },
+        "ontoolcancel": {
+          "description": "Event handler for the \"toolcancel\" event.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/RefObject"
+            },
+            {
+              "$ref": "#/$defs/ExpressionEntry"
+            },
+            {
+              "$ref": "#/$defs/FunctionDef"
+            }
+          ]
+        },
         "ontoolchange": {
           "description": "Event handler for the \"toolchange\" event.",
           "oneOf": [
@@ -27922,6 +27964,7 @@
         "img",
         "input",
         "ins",
+        "install",
         "kbd",
         "label",
         "legend",

package/src/asset-paths.ts

@@ -77,6 +77,16 @@ export interface AssetMount {
   urlPrefix: string;
   /** Absolute directory the prefix maps onto. */
   dir: string;
+  /**
+   * Whether the mount serves a file, asked with the file's path relative to {@link dir},
+   * `/`-separated. Absent means every file under the directory. A mount over a folder of notes sets
+   * it so that what the collection leaves out (`exclude`, hidden files, unpublished documents) is
+   * never reachable through the mount either: {@link assetUrlFor} gives a refused file no URL and
+   * {@link resolveAssetUrl} resolves a refused URL to nothing, so no host serves or copies it. It is
+   * a function, so it exists only where the mount was declared; a host that rebuilds a mount from
+   * its two strings (a project-relative copy for Studio) gets none.
+   */
+  filter?: (path: string) => boolean;
 }
 
 /** Normalize a path or prefix for comparison: forward slashes, no trailing slash. */
@@ -117,6 +127,10 @@ export function assetUrlFor(mounts: readonly AssetMount[], absolutePath: string)
       continue;
     }
     const rest = path.slice(dir.length + 1);
+    const { filter: serves } = mount;
+    if (serves && !serves(rest)) {
+      return null;
+    }
     const encoded = rest
       .split("/")
       .map((segment) => encodeURIComponent(segment))
@@ -160,6 +174,10 @@ export function resolveAssetUrl(mounts: readonly AssetMount[], url: string): str
     if (segments.some((s) => s === "" || s === "." || s === "..")) {
       return null;
     }
+    const { filter: serves } = mount;
+    if (serves && !serves(segments.join("/"))) {
+      return null;
+    }
     return `${normalizeDir(mount.dir)}/${segments.join("/")}`;
   }
   return null;

package/src/doc-ops.ts

@@ -0,0 +1,348 @@
+/**
+ * The canonical Jx document-op vocabulary, its pure applier, and its inverse. A `JxDocOp` is a
+ * value-carrying, replayable mutation of a plain-JSON Jx document tree, addressed by `JxPath`
+ * (alternating "children" / index segments for structure, plus node keys). Studio's transaction
+ * pipeline records forward/inverse pairs of these for history replay; the collab bridge mirrors
+ * them into a shared Y.Doc.
+ *
+ * This module is deliberately yjs-free and imports types only: the slim canvas-iframe bundle
+ * imports the applier for its non-reactive shadow doc, and it MUST stay byte-identical in behavior
+ * to the parent's history replay — both sides import this one implementation. It lives in
+ * `@jxsuite/schema`, beside the document types, so any host can edit a document the way Studio does
+ * without taking yjs: a Durable Object, a headless tool, a test. `@jxsuite/collab/ops` re-exports
+ * it.
+ *
+ * @module @jxsuite/schema/doc-ops
+ */
+
+import type { 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 }
+  /** Insert a node at parentPath.children[index]. */
+  | { op: "insert-child"; parentPath: JxPath; index: number; node: unknown }
+  /** 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 }
+  /** Raw two-splice move: remove fromParent.children[fromIndex], insert at toParent[toIndex]. */
+  | {
+      op: "move-child";
+      fromParentPath: JxPath;
+      fromIndex: number;
+      toParentPath: JxPath;
+      toIndex: number;
+    };
+
+export interface JxDocOpPair {
+  forward: JxDocOp;
+  inverse: JxDocOp;
+}
+
+/** JSON round-trip clone — also normalizes away reactive proxies / functions / undefined. */
+function jsonClone<T>(value: T): T {
+  // 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);
+}
+
+/**
+ * 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).
+ */
+export function getNodeAtPath(doc: JxMutableNode, path: JxPath): JxMutableNode {
+  let node = doc;
+  for (const key of path) {
+    if (node == null) {
+      return undefined as unknown as JxMutableNode;
+    }
+    node = node[key] as JxMutableNode;
+  }
+  return node;
+}
+
+/** The node's children array, lazily created; throws if `node` is itself a children array or mapped. */
+export function childArray(node: JxMutableNode): (JxMutableNode | string)[] {
+  // Defense-in-depth: a path that resolves to a children array (rather than a node) would
+  // Otherwise get a bogus `.children` property tacked on here, silently storing the insert where
+  // Nothing renders. Callers must pass a node; fail loudly if they don't.
+  if (Array.isArray(node)) {
+    throw new TypeError("Cannot insert into a children array; parentPath must point at a node");
+  }
+  if (!node.children) {
+    node.children = [];
+  }
+  if (!Array.isArray(node.children)) {
+    throw new TypeError("Cannot insert into mapped-array children; edit the map template instead");
+  }
+  return node.children;
+}
+
+/**
+ * Apply a replayable doc op to a bare document tree. Values/nodes are cloned in, so the tree never
+ * aliases the op object. Throws (with a machine-readable reason) when a target path is missing.
+ */
+export function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp): void {
+  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];
+      } else {
+        target[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);
+      return;
+    }
+    case "remove-child": {
+      const parent = getNodeAtPath(doc, op.parentPath);
+      childArray(parent).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);
+      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 [node] = from.splice(op.fromIndex, 1);
+      to.splice(op.toIndex, 0, node!);
+      return;
+    }
+    default: {
+      break;
+    }
+  }
+  throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
+}
+
+/**
+ * Translate `path` into post-splice coordinates when it descends through `parentPath`'s children at
+ * or beyond the spliced index: a removal (delta -1) at the index shifts deeper paths down; an
+ * 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.
+ */
+function shiftThroughSplice(
+  parentPath: JxPath,
+  path: JxPath,
+  spliceIndex: number,
+  delta: number,
+  inclusive: boolean,
+): 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") {
+    return path;
+  }
+  const index = path[depth + 1] as number;
+  if (inclusive ? index < spliceIndex : index <= spliceIndex) {
+    return path;
+  }
+  const shifted = [...path];
+  shifted[depth + 1] = index + delta;
+  return shifted;
+}
+
+/**
+ * Refuse a move into the moved node itself or into its own subtree. Splicing the node out first
+ * would detach the very parent the insert was to land in, so the subtree would vanish and no
+ * inverse could bring it back.
+ */
+function assertNotIntoOwnSubtree(op: Extract<JxDocOp, { op: "move-child" }>): void {
+  const moved = [...op.fromParentPath, "children", op.fromIndex];
+  const target = op.toParentPath;
+  if (target.length >= moved.length && moved.every((seg, i) => seg === target[i])) {
+    throw new Error(`doc-op-move-into-self:${target.join("/")}`);
+  }
+}
+
+/**
+ * The index a `splice(index, 0, …)` into `length` elements actually inserts at: a negative index
+ * 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 {
+  return index < 0 ? Math.max(length + index, 0) : Math.min(index, length);
+}
+
+/**
+ * The op that undoes `op`, computed against `doc` as it stands BEFORE `op` is applied.
+ *
+ * Every inverse is expressed in the coordinates of the document after `op` ran, because that is the
+ * document it will be applied to. For four kinds that is the op's own coordinates. `move-child` is
+ * the one that is not: removing the node shifts every sibling path after it under the source
+ * parent, and inserting it shifts every sibling path at or after the target index under the
+ * destination parent, so each parent path of the inverse is translated through the other splice.
+ * The rule is the one Studio's own move has always recorded.
+ *
+ * **One residue is not undone, deliberately.** Inserting or moving a node into a parent with no
+ * `children` creates the array (the applier's `childArray` does), and undoing it removes the node
+ * but leaves `children: []`. A single op cannot both move a node back and delete a key, and
+ * Studio's own history has always recorded exactly these inverses, so matching it is the contract;
+ * an empty `children` array renders as nothing and validates as the absent key does.
+ *
+ * An index the applier would clamp (`splice` appends past the end and counts a negative index from
+ * it) is recorded as the slot the node actually lands in.
+ *
+ * Throws when the op cannot be applied: its target does not resolve, an insert or move targets
+ * something that cannot hold children, or a move targets the moved node's own subtree. An op that
+ * cannot be applied has nothing to undo, and a caller that computed an inverse for it would record
+ * a history entry for an edit that never happened.
+ *
+ * @param {JxMutableNode} doc - The document the op is about to be applied to
+ * @param {JxDocOp} op
+ * @returns {JxDocOp}
+ */
+export function inverseOf(doc: JxMutableNode, op: JxDocOp): JxDocOp {
+  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]);
+      return before === undefined
+        ? { key: op.key, op: "set-key", path: op.path }
+        : { key: op.key, op: "set-key", path: op.path, value: before };
+    }
+    case "insert-child": {
+      const { length } = insertableChildren(doc, op.parentPath);
+      return {
+        index: insertionSlot(op.index, length),
+        op: "remove-child",
+        parentPath: op.parentPath,
+      };
+    }
+    case "remove-child": {
+      const removed = existingChild(doc, op.parentPath, op.index);
+      return { index: op.index, node: removed, op: "insert-child", parentPath: op.parentPath };
+    }
+    case "set-child": {
+      const replaced = existingChild(doc, op.parentPath, op.index);
+      return { index: op.index, node: replaced, op: "set-child", parentPath: op.parentPath };
+    }
+    case "move-child": {
+      assertNotIntoOwnSubtree(op);
+      const source = childrenAt(doc, op.fromParentPath);
+      assertIndex(source, op.fromParentPath, op.fromIndex);
+      const target = insertableChildren(doc, op.toParentPath);
+      // The target's length after the removal: the same array when the move stays in one parent.
+      const toIndex = insertionSlot(op.toIndex, target.length - (target === source ? 1 : 0));
+      return {
+        fromIndex: toIndex,
+        // The removal shifted paths under the source parent; the insertion, under the target.
+        fromParentPath: shiftThroughSplice(
+          op.fromParentPath,
+          op.toParentPath,
+          op.fromIndex,
+          -1,
+          false,
+        ),
+        op: "move-child",
+        toIndex: op.fromIndex,
+        toParentPath: shiftThroughSplice(op.toParentPath, op.fromParentPath, toIndex, 1, true),
+      };
+    }
+    default: {
+      break;
+    }
+  }
+  throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
+}
+
+/** 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);
+  return parent && Array.isArray(parent.children) ? parent.children : null;
+}
+
+/** Throw the applier's reason unless `children` holds an element at `index`. */
+function assertIndex(
+  children: (JxMutableNode | string)[] | null,
+  parentPath: JxPath,
+  index: number,
+): asserts children is (JxMutableNode | string)[] {
+  if (!children || index < 0 || index >= children.length) {
+    throw new Error(`doc-op-node-not-found:${[...parentPath, "children", index].join("/")}`);
+  }
+}
+
+/** 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 {
+  const children = childrenAt(doc, parentPath);
+  assertIndex(children, parentPath, index);
+  return cloneValue(children[index]);
+}
+
+/**
+ * The children array an insert into `parentPath` lands in — an empty stand-in when the node has no
+ * `children` yet, since the applier creates one — or the reason it cannot land: no node there, a
+ * 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)) {
+    throw new Error(`doc-op-node-not-found:${parentPath.join("/")}`);
+  }
+  if (node.children === undefined) {
+    return [];
+  }
+  if (!Array.isArray(node.children)) {
+    throw new TypeError(`doc-op-mapped-children:${parentPath.join("/")}`);
+  }
+  return node.children as (JxMutableNode | string)[];
+}
+
+/**
+ * Apply `ops` to `doc` in order, answering the forward/inverse pair for each — the record a history
+ * entry, an undo stack or a journal needs. Each inverse is computed against the document as it
+ * stands just before its own op, so a sequence whose later ops address what earlier ones created is
+ * recorded correctly. Undo applies the inverses in REVERSE order.
+ *
+ * Stops at the first op that does not apply and rethrows its reason; the ops before it have been
+ * applied, and their pairs are on the error as `applied`, so a caller can roll them back.
+ *
+ * @param {JxMutableNode} doc
+ * @param {readonly JxDocOp[]} ops
+ * @returns {JxDocOpPair[]}
+ */
+export function applyDocOpsWithInverse(doc: JxMutableNode, ops: readonly JxDocOp[]): JxDocOpPair[] {
+  const pairs: JxDocOpPair[] = [];
+  for (const forward of ops) {
+    let inverse: JxDocOp;
+    try {
+      inverse = inverseOf(doc, forward);
+      applyDocOpToDoc(doc, forward);
+    } catch (error) {
+      throw Object.assign(error instanceof Error ? error : new Error(String(error)), {
+        applied: pairs,
+      });
+    }
+    pairs.push({ forward, inverse });
+  }
+  return pairs;
+}

package/src/json-layout.ts

@@ -0,0 +1,474 @@
+/**
+ * A JSON document's layout — the facts about a file's text that `JSON.parse` throws away and a save
+ * has to put back.
+ *
+ * Studio's native JSON branch used to be `JSON.stringify(document, null, 2)`, and that is not the
+ * layout the repository is kept in. The formatter (`oxfmt`, Prettier-compatible for JSON) keeps a
+ * short object on the one line its author wrote it on, so every
+ * `packages/studio/src/surfaces/*.json` and `packages/ui/components/*.json` — files Studio now
+ * opens as projects — carries hundreds of `{ "part": "bar" }`s that a save expanded to three lines
+ * each. One edit became a whole-file diff, and the line the author actually changed was buried in
+ * it (issue 308).
+ *
+ * Two halves. {@link deriveJsonLayout} reads the source text once, when a file is read into a tab,
+ * and records the things the formatter would preserve; {@link serializeJson} writes a document back
+ * with those facts honoured and everything else laid out the way the formatter lays it out. The
+ * test that proves the pair is byte-identity over every formatted document in this repository.
+ *
+ * **What is recorded, and why nothing else.** The formatter preserves three authored choices and
+ * relays everything else. (1) Whether an object's `{` is followed by a line break: an object
+ * written on one line stays on one line while it fits the print width, and one whose first key sits
+ * on its own line stays expanded however short it is. (2) A blank line between two members of an
+ * object or an array — one, however many were written, and never one against a bracket. (3) A
+ * non-ASCII character an author spelt as a `\uXXXX` escape, which `JSON.stringify` would otherwise
+ * turn into the literal character and so touch a line the edit never reached. Arrays are relaid
+ * from scratch every time — `[\n 1, 2 ]` comes back as `[1, 2]` — so an array's own line break is a
+ * fact the serializer would then have to ignore, and it is not recorded.
+ *
+ * **Keyed by JSON Pointer**, so the record survives every edit that leaves a node where it was: a
+ * changed value, a new sibling, a removed one. An object with no entry — one the edit created —
+ * takes its parent's answer, so a new `{ "$ref": … }` inside an inline `attributes` lands inline
+ * beside its siblings rather than blowing the object open; at an expanded level, or in a document
+ * that has no layout at all, it expands, which is what the formatter does with `JSON.stringify`
+ * output.
+ *
+ * The width rules are measured against `oxfmt`, not recalled from Prettier: a container is inline
+ * when the whole line, trailing comma included, is at most `printWidth` columns; a container with
+ * an expanded object or a blank line anywhere inside it expands (a break propagates outward); an
+ * array of two or more elements that are all objects with more than one key, or all arrays with
+ * more than one element, always expands one element per line; and an array of two or more numbers
+ * fills its lines instead of taking one per line. Width is DISPLAY width, as the formatter measures
+ * it, not string length: a CJK or fullwidth character and an emoji are two columns, a combining
+ * mark or a format character is none ({@link displayWidth}; probed against oxfmt, which uses the
+ * `unicode-width` tables — the ranges here are Prettier's, and agree with those on everything a
+ * document is likely to hold). Scalars are `JSON.stringify`'s, so `1e5` reads back as `100000` and
+ * `1.50` as `1.5` — the parsed value has already lost the spelling, and no document in this
+ * repository writes a number either way. `package.json` is the one file the formatter lays out as
+ * `JSON.stringify` does, every array expanded; it is not a document and nothing here writes one.
+ *
+ * @docs studio/interface/tabs
+ */
+
+/** A JSON Pointer (RFC 6901) segment: `~` and `/` are the two characters that need escaping. */
+function segment(key: string): string {
+  return key.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+/**
+ * What a source text said about its own layout, by JSON Pointer.
+ *
+ * `inline` maps an object to whether its `{` and first key shared a line; an empty object has no
+ * entry because `{}` is `{}` either way. `blankAfter` holds the members a blank line followed.
+ * `escaped` maps a string to the UTF-16 code units its source spelt as `\uXXXX` — the units rather
+ * than a flag, because `"— Julio Cortázar"` with only the dash escaped is a string this repository
+ * holds, and a flag would have had to choose which half of it to rewrite.
+ */
+export interface JsonLayout {
+  inline: Map<string, boolean>;
+  blankAfter: Set<string>;
+  escaped: Map<string, Set<number>>;
+}
+
+/** The print width the repository formats to — `.oxfmtrc.json` leaves oxfmt's default in place. */
+export const JSON_PRINT_WIDTH = 100;
+
+/**
+ * Read the layout facts out of a JSON text.
+ *
+ * A scanner rather than a parser: the text has already been through `JSON.parse` by the time this
+ * runs (see {@link parseJsonDocument}), so it is known to be well-formed and the scanner only has to
+ * find its way from one container to the next. Keys are decoded with `JSON.parse` so the pointer
+ * matches the key the document actually holds, escapes and all.
+ */
+export function deriveJsonLayout(text: string): JsonLayout {
+  const layout: JsonLayout = { blankAfter: new Set(), escaped: new Map(), inline: new Map() };
+  let i = 0;
+
+  /** Skip whitespace; report how many line breaks were among it. */
+  const space = (): number => {
+    let newlines = 0;
+    while (
+      i < text.length &&
+      (text[i] === " " || text[i] === "\t" || text[i] === "\r" || text[i] === "\n")
+    ) {
+      if (text[i] === "\n") {
+        newlines += 1;
+      }
+      i += 1;
+    }
+    return newlines;
+  };
+
+  /** Consume the string starting at `i`; return its raw text and the code units it escaped. */
+  const string = (): { raw: string; escaped: Set<number> } => {
+    const start = i;
+    const escaped = new Set<number>();
+    i += 1;
+    while (i < text.length && text[i] !== '"') {
+      if (text[i] === "\\") {
+        if (text[i + 1] === "u") {
+          const unit = Number.parseInt(text.slice(i + 2, i + 6), 16);
+          if (unit >= 0x80) {
+            escaped.add(unit);
+          }
+          i += 6;
+        } else {
+          i += 2;
+        }
+      } else {
+        i += 1;
+      }
+    }
+    i += 1;
+    return { escaped, raw: text.slice(start, i) };
+  };
+
+  /**
+   * After a member: consume its separator and note a blank line before the next one. Returns
+   * whether the container closed instead.
+   */
+  const separator = (memberPath: string, close: string): boolean => {
+    let newlines = space();
+    if (text[i] === close) {
+      i += 1;
+      return true;
+    }
+    i += 1; // ","
+    newlines += space();
+    if (newlines >= 2) {
+      layout.blankAfter.add(memberPath);
+    }
+    return false;
+  };
+
+  const value = (path: string): void => {
+    space();
+    const c = text[i];
+    if (c === "{") {
+      i += 1;
+      const broken = space() > 0;
+      if (text[i] === "}") {
+        i += 1;
+        return;
+      }
+      layout.inline.set(path, !broken);
+      while (i < text.length) {
+        const key = JSON.parse(string().raw) as string;
+        space();
+        i += 1; // ":"
+        const member = `${path}/${segment(key)}`;
+        value(member);
+        if (separator(member, "}")) {
+          return;
+        }
+      }
+    } else if (c === "[") {
+      i += 1;
+      space();
+      if (text[i] === "]") {
+        i += 1;
+        return;
+      }
+      for (let index = 0; i < text.length; index += 1) {
+        const member = `${path}/${index}`;
+        value(member);
+        if (separator(member, "]")) {
+          return;
+        }
+      }
+    } else if (c === '"') {
+      const { escaped } = string();
+      if (escaped.size > 0) {
+        layout.escaped.set(path, escaped);
+      }
+    } else {
+      // A number or a literal: runs to the next delimiter.
+      while (i < text.length && !",]} \t\r\n".includes(text[i]!)) {
+        i += 1;
+      }
+    }
+  };
+
+  value("");
+  return layout;
+}
+
+/** Parse a JSON file into the document it holds and the layout it was written in. */
+export function parseJsonDocument(text: string): {
+  document: Record<string, unknown>;
+  layout: JsonLayout;
+} {
+  const document = JSON.parse(text) as Record<string, unknown>;
+  return { document, layout: deriveJsonLayout(text) };
+}
+
+// ─── Writing ──────────────────────────────────────────────────────────────────
+
+/** Anything outside printable ASCII: the one case {@link displayWidth} has to count. */
+const NOT_ASCII = /[^\u0020-\u007E]/;
+
+/** A mark or a format character (a zero-width joiner, say) takes no column. */
+const ZERO_WIDTH = /^[\p{Mn}\p{Me}\p{Cf}]$/u;
+
+/** A character the formatter draws two columns wide: East Asian Wide/Fullwidth, or an emoji. */
+const EMOJI = /^\p{Emoji_Presentation}$/u;
+
+/**
+ * East Asian Wide and Fullwidth (`is-fullwidth-code-point`'s table, which is what Prettier's
+ * `getStringWidth` consults): Hangul Jamo, CJK and its punctuation, Hangul syllables, the
+ * compatibility ideographs, vertical and small forms, the fullwidth Latin block, and the
+ * supplementary ideographic planes.
+ */
+function isWide(cp: number): boolean {
+  return (
+    cp >= 0x11_00 &&
+    (cp <= 0x11_5f ||
+      cp === 0x23_29 ||
+      cp === 0x23_2a ||
+      (cp >= 0x2e_80 && cp <= 0x32_47 && cp !== 0x30_3f) ||
+      (cp >= 0x32_50 && cp <= 0x4d_bf) ||
+      (cp >= 0x4e_00 && cp <= 0xa4_c6) ||
+      (cp >= 0xa9_60 && cp <= 0xa9_7c) ||
+      (cp >= 0xac_00 && cp <= 0xd7_a3) ||
+      (cp >= 0xf9_00 && cp <= 0xfa_ff) ||
+      (cp >= 0xfe_10 && cp <= 0xfe_19) ||
+      (cp >= 0xfe_30 && cp <= 0xfe_6b) ||
+      (cp >= 0xff_01 && cp <= 0xff_60) ||
+      (cp >= 0xff_e0 && cp <= 0xff_e6) ||
+      (cp >= 0x1_b0_00 && cp <= 0x1_b0_01) ||
+      (cp >= 0x1_f2_00 && cp <= 0x1_f2_51) ||
+      (cp >= 0x2_00_00 && cp <= 0x3_ff_fd))
+  );
+}
+
+/**
+ * How many columns a line of output occupies — what the formatter compares against the print width.
+ * `String.length` counts UTF-16 units, and the two part company exactly where a document holds
+ * non-Latin text: `"漢"` is one unit and two columns, an emoji is two units and two columns, `"é"`
+ * written as `e` plus a combining acute is two units and one column. Measured with the length, a
+ * line of CJK could sit "inline" at 62 units and 106 columns, and the formatter would break it open
+ * on the next run — a save that is not formatter-stable.
+ */
+export function displayWidth(text: string): number {
+  if (!NOT_ASCII.test(text)) {
+    return text.length;
+  }
+  let width = 0;
+  for (const c of text) {
+    if (ZERO_WIDTH.test(c)) {
+      continue;
+    }
+    width += isWide(c.codePointAt(0)!) || EMOJI.test(c) ? 2 : 1;
+  }
+  return width;
+}
+
+type Entry = [key: string, value: unknown];
+
+/** Whether `JSON.stringify` would drop this value from an object. */
+function omitted(value: unknown): boolean {
+  return value === undefined || typeof value === "function" || typeof value === "symbol";
+}
+
+function entriesOf(value: object): Entry[] {
+  return Object.entries(value).filter(([, v]) => !omitted(v));
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Whether the formatter forces this array open: two or more elements, all objects with more than
+ * one key or all arrays with more than one element (Prettier's "concisely printed" rule,
+ * inverted).
+ */
+function forcedOpen(items: unknown[]): boolean {
+  if (items.length < 2) {
+    return false;
+  }
+  const kind = Array.isArray(items[0]) ? "array" : isObject(items[0]) ? "object" : null;
+  if (kind === null) {
+    return false;
+  }
+  return items.every((item) =>
+    kind === "array"
+      ? Array.isArray(item) && item.length > 1
+      : isObject(item) && entriesOf(item).length > 1,
+  );
+}
+
+/** Two or more numbers: the formatter fills lines with them rather than stacking one per line. */
+function isNumberRun(items: unknown[]): boolean {
+  return items.length > 1 && items.every((item) => typeof item === "number");
+}
+
+/** A scalar, as `JSON.stringify` spells it — with the code units the source escaped, escaped. */
+function scalar(value: unknown, escaped?: Set<number>): string {
+  const text = JSON.stringify(value) ?? "null";
+  return escaped === undefined
+    ? text
+    : text.replaceAll(/[\u0080-\uFFFF]/g, (c) => {
+        const unit = c.codePointAt(0)!;
+        return escaped.has(unit) ? `\\u${unit.toString(16).padStart(4, "0")}` : c;
+      });
+}
+
+/**
+ * Write a document in the layout the formatter would keep it in.
+ *
+ * `layout` is what {@link deriveJsonLayout} read from the file this document came from, or `null`
+ * for a document that has no file yet (or whose file was not JSON) — every object then expands and
+ * every array is laid by fit, which is the formatter's own answer for `JSON.stringify` output. The
+ * result ends with exactly one newline, as every formatted file does.
+ */
+export function serializeJson(
+  value: unknown,
+  layout: JsonLayout | null,
+  printWidth = JSON_PRINT_WIDTH,
+): string {
+  const inline = layout?.inline ?? new Map<string, boolean>();
+  const blankAfter = layout?.blankAfter ?? new Set<string>();
+  const escaped = layout?.escaped ?? new Map<string, Set<number>>();
+
+  /**
+   * Whether an object is a candidate for one line: its own record, or its parent's when it has
+   * none.
+   */
+  const soft = (path: string, inherited: boolean): boolean => inline.get(path) ?? inherited;
+
+  /**
+   * The one-line rendering, or `null` when something inside is forced open — an expanded object, a
+   * blank line, or an array the formatter always breaks — so that the break propagates outward the
+   * way the formatter's does.
+   */
+  const flat = (v: unknown, path: string, inherited: boolean): string | null => {
+    if (Array.isArray(v)) {
+      if (v.length === 0) {
+        return "[]";
+      }
+      if (forcedOpen(v)) {
+        return null;
+      }
+      const parts: string[] = [];
+      for (const [index, item] of v.entries()) {
+        const member = `${path}/${index}`;
+        const part = blankAfter.has(member) ? null : flat(item, member, inherited);
+        if (part === null) {
+          return null;
+        }
+        parts.push(part);
+      }
+      return `[${parts.join(", ")}]`;
+    }
+    if (isObject(v)) {
+      const entries = entriesOf(v);
+      if (entries.length === 0) {
+        return "{}";
+      }
+      if (!soft(path, inherited)) {
+        return null;
+      }
+      const parts: string[] = [];
+      for (const [key, item] of entries) {
+        const member = `${path}/${segment(key)}`;
+        const part = blankAfter.has(member) ? null : flat(item, member, true);
+        if (part === null) {
+          return null;
+        }
+        parts.push(`${JSON.stringify(key)}: ${part}`);
+      }
+      return `{ ${parts.join(", ")} }`;
+    }
+    return scalar(v, escaped.get(path));
+  };
+
+  /** Members one per line, with the blank lines the source had between them. */
+  const stack = (members: { path: string; text: string }[]): string =>
+    members
+      .map(({ path, text }, index) =>
+        index === members.length - 1 ? text : `${text},\n${blankAfter.has(path) ? "\n" : ""}`,
+      )
+      .join("");
+
+  /**
+   * A value at `column`, followed on its last line by `trailing` more characters (the comma a
+   * parent adds, which counts toward the width the formatter measures).
+   */
+  const render = (
+    v: unknown,
+    path: string,
+    indent: number,
+    column: number,
+    inherited: boolean,
+    trailing: number,
+  ): string => {
+    const line = flat(v, path, inherited);
+    // A scalar is never broken, however long: only a container has a second layout to fall to.
+    const container = Array.isArray(v) || isObject(v);
+    if (line !== null && (!container || column + displayWidth(line) + trailing <= printWidth)) {
+      return line;
+    }
+    const pad = " ".repeat(indent + 2);
+    const close = `\n${" ".repeat(indent)}`;
+    if (Array.isArray(v)) {
+      if (isNumberRun(v)) {
+        const blank = (index: number) => blankAfter.has(`${path}/${index}`);
+        return `[\n${fill(v, pad, printWidth, blank)}${close}]`;
+      }
+      const items = v.map((item, index) => {
+        const member = `${path}/${index}`;
+        const last = index === v.length - 1;
+        const text = render(item, member, indent + 2, pad.length, inherited, last ? 0 : 1);
+        return { path: member, text: `${pad}${text}` };
+      });
+      return `[\n${stack(items)}${close}]`;
+    }
+    const entries = entriesOf(v as object);
+    const own = soft(path, inherited);
+    const members = entries.map(([key, item], index) => {
+      const member = `${path}/${segment(key)}`;
+      const prefix = `${JSON.stringify(key)}: `;
+      const last = index === entries.length - 1;
+      const at = pad.length + displayWidth(prefix);
+      const text = render(item, member, indent + 2, at, own, last ? 0 : 1);
+      return { path: member, text: `${pad}${prefix}${text}` };
+    });
+    return `{\n${stack(members)}${close}}`;
+  };
+
+  return `${render(value, "", 0, 0, false, 0)}\n`;
+}
+
+/**
+ * Numbers packed onto lines greedily: the next one joins the line when it fits with its comma, and
+ * opens a new line otherwise. Each line carries `pad`. A blank line the source had after a number
+ * (`blank`) ends its line and stays, as it does between any other two members. Lengths, not
+ * {@link displayWidth}: a line of numbers and spaces is ASCII, so the two agree.
+ */
+function fill(
+  numbers: unknown[],
+  pad: string,
+  printWidth: number,
+  blank: (index: number) => boolean,
+): string {
+  const lines: string[] = [];
+  let line = "";
+  for (const [index, n] of numbers.entries()) {
+    const item = `${scalar(n)}${index === numbers.length - 1 ? "" : ","}`;
+    if (line === "") {
+      line = `${pad}${item}`;
+    } else if (line.length + 1 + item.length <= printWidth) {
+      line = `${line} ${item}`;
+    } else {
+      lines.push(line);
+      line = `${pad}${item}`;
+    }
+    if (blank(index) && index < numbers.length - 1) {
+      lines.push(line, "");
+      line = "";
+    }
+  }
+  lines.push(line);
+  return lines.join("\n");
+}

package/types.ts

@@ -857,6 +857,26 @@ export interface ContentLoaderEntry {
     mtime?: string;
     /** Authored text of a field the date-coercion pass rewrote, keyed by field name. */
     rawDates?: Record<string, unknown>;
+    /**
+     * The entry's source file, relative to its content type's source directory, `/`-separated and
+     * with its extension (`Frappe/Bench Operations.md`). Stamped by the content loader for every
+     * entry it reads from a directory, so a message or an "edit this page" link can name the file
+     * an entry came from.
+     */
+    path?: string;
+    /**
+     * The entry's route: the site-absolute path its content type's `route` template gives it,
+     * without a locale prefix or a trailing slash (`/kb/frappe/bench-operations`). Present only
+     * when the content type declares a `route`. Everything that needs a URL for the entry (links
+     * between entries, `$paths`, search, feeds) reads this, so they cannot disagree.
+     */
+    route?: string;
+    /**
+     * The entry's URL as a link target: {@link route} percent-encoded, with the locale prefix of a
+     * `{locale}` collection and the site's `build.trailingSlash` applied
+     * (`/kb/frappe/bench-operations/`).
+     */
+    url?: string;
     /**
      * The locale this entry was loaded for, set only when its content type's `source` carried a
      * `{locale}` placeholder. It is what lets a `[slug]` route under `/fr/` expand the French