@abraca/convert 2.3.0

package/dist/index.d.ts

@@ -0,0 +1,356 @@
+import * as Y from "yjs";
+
+//#region packages/convert/src/types.d.ts
+interface DocPageMeta extends Record<string, unknown> {
+  color?: string;
+  icon?: string;
+  datetimeStart?: string;
+  datetimeEnd?: string;
+  allDay?: boolean;
+  dateTaken?: string;
+  dateStart?: string;
+  dateEnd?: string;
+  timeStart?: string;
+  timeEnd?: string;
+  taskProgress?: number;
+  members?: {
+    id: string;
+    label: string;
+  }[];
+  tags?: string[];
+  checked?: boolean;
+  priority?: number;
+  status?: string;
+  rating?: number;
+  url?: string;
+  email?: string;
+  phone?: string;
+  number?: number;
+  unit?: string;
+  subtitle?: string;
+  note?: string;
+  coverUploadId?: string;
+  coverDocId?: string;
+  coverMimeType?: string;
+  geoType?: 'marker' | 'line' | 'measure';
+  geoLat?: number;
+  geoLng?: number;
+  geoDescription?: string;
+  deskX?: number;
+  deskY?: number;
+  deskZ?: number;
+  deskMode?: string;
+  mmX?: number;
+  mmY?: number;
+  graphX?: number;
+  graphY?: number;
+  graphPinned?: boolean;
+  spX?: number;
+  spY?: number;
+  spZ?: number;
+  spRX?: number;
+  spRY?: number;
+  spRZ?: number;
+  spSX?: number;
+  spSY?: number;
+  spSZ?: number;
+  spShape?: string;
+  spOpacity?: number;
+  spModelUploadId?: string;
+  spModelDocId?: string;
+  slidesTransition?: 'none' | 'fade' | 'slide';
+  slidesTheme?: 'dark' | 'light';
+  __schemaVersion?: number;
+}
+//#endregion
+//#region packages/convert/src/markdown-to-yjs.d.ts
+/**
+ * Converts a filename (without extension) to a human-readable label.
+ *
+ * - `this-is-a-doc`  → `"This is a doc"`   (kebab/snake: sentence case)
+ * - `ThisIsADoc`     → `"This Is A Doc"`   (PascalCase: preserves word caps)
+ * - `thisIsADoc`     → `"This Is A Doc"`   (camelCase: preserves word caps)
+ */
+declare function filenameToLabel(raw: string): string;
+interface FrontmatterResult {
+  title?: string;
+  type?: string;
+  meta: Partial<DocPageMeta>;
+  body: string;
+}
+declare function parseFrontmatter(markdown: string): FrontmatterResult;
+/**
+ * Parses markdown text and writes the result into a Y.XmlFragment that
+ * TipTap's Collaboration extension can read.
+ *
+ * Requires `fragment.doc` to be set (i.e. the fragment must already be
+ * obtained from a live Y.Doc via `ydoc.getXmlFragment('default')`).
+ *
+ * @param fragment      The target `Y.Doc.getXmlFragment('default')`
+ * @param markdown      Raw markdown string
+ * @param fallbackTitle Used as the title when the markdown has no H1
+ */
+declare function populateYDocFromMarkdown(fragment: Y.XmlFragment, markdown: string, fallbackTitle?: string): void;
+//#endregion
+//#region packages/convert/src/yjs-to-markdown.d.ts
+declare function yjsToMarkdown(fragment: Y.XmlFragment, label: string, meta?: DocPageMeta, type?: string): string;
+/**
+ * Walk the Y.XmlFragment and concatenate all text content with no
+ * markup or frontmatter. Block boundaries become newlines. Useful for
+ * accessibility tooling, search indexing, and snippet previews.
+ */
+declare function yjsToPlainText(fragment: Y.XmlFragment): string;
+declare function yjsToHtml(fragment: Y.XmlFragment, label: string): string;
+//#endregion
+//#region packages/convert/src/html-to-yjs.d.ts
+/**
+ * Parses an HTML string and writes the result into a Y.XmlFragment that
+ * TipTap's Collaboration extension can read.
+ *
+ * @param fragment      The target `Y.Doc.getXmlFragment('default')`
+ * @param html          Raw HTML string
+ * @param fallbackTitle Used when no <title> or <h1> is found
+ */
+declare function populateYDocFromHtml(fragment: Y.XmlFragment, html: string, fallbackTitle?: string): void;
+/**
+ * Appends blocks from an HTML string to an existing Y.XmlFragment.
+ * Does NOT insert documentHeader/documentMeta — for appending to an existing doc.
+ */
+declare function appendHtmlToFragment(fragment: Y.XmlFragment, html: string): void;
+//#endregion
+//#region packages/convert/src/diff.d.ts
+type JsonAttr = string | number | boolean | null | JsonAttr[] | {
+  [key: string]: JsonAttr;
+};
+interface YjsTextRun {
+  insert: string;
+  attributes?: Record<string, JsonAttr>;
+}
+interface YjsJsonText {
+  kind: 'text';
+  runs: YjsTextRun[];
+}
+interface YjsJsonElement {
+  kind: 'element';
+  tag: string;
+  attrs?: Record<string, JsonAttr>;
+  children: YjsJsonNode[];
+}
+type YjsJsonNode = YjsJsonElement | YjsJsonText;
+declare function yfragmentToJson(frag: Y.XmlFragment): YjsJsonElement;
+/**
+ * Build a Y.XmlFragment from a previously captured golden JSON. The
+ * returned fragment is bound to a fresh Y.Doc so consumers can hand
+ * it to serialisers immediately. All Yjs mutations happen inside a
+ * single transaction.
+ */
+declare function jsonToYFragment(root: YjsJsonElement, doc?: Y.Doc, key?: string): Y.XmlFragment;
+interface YjsDiff {
+  equal: boolean;
+  /** Dotted path to the first divergence (empty when equal). */
+  path: string;
+  /** Short human-readable explanation. */
+  reason: string;
+}
+declare function diffYjs(a: Y.XmlFragment, b: Y.XmlFragment): YjsDiff;
+declare function diffJson(a: YjsJsonNode, b: YjsJsonNode): YjsDiff;
+/** Stringify a YjsJsonNode with sorted keys for byte-stable golden files. */
+declare function stringifyJsonNode(node: YjsJsonNode): string;
+//#endregion
+//#region packages/convert/src/spec/nodes.d.ts
+type NodeWireKind = 'vanilla' | 'fence' | 'mdc-container' | 'mdc-slotted' | 'mdc-atom-block' | 'mdc-atom-inl' | 'special';
+interface NodeAttrSpec {
+  /** Attribute name on the Y.XmlElement and on the MDC prop. */
+  key: string;
+  /** Wire type — controls how the attr is parsed/serialised in props. */
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'json';
+  /** Optional default value omitted from serialised output when equal. */
+  default?: unknown;
+  /** Allowed values for enum-like string attrs. */
+  values?: readonly string[];
+  /** Whether the attr is allowed to be omitted entirely. */
+  optional?: boolean;
+}
+interface NodeSpec {
+  /** Y.XmlElement nodeName. */
+  name: string;
+  /** Block vs inline. */
+  group: 'block' | 'inline';
+  /** Wire form on Markdown. */
+  wire: NodeWireKind;
+  /**
+   * For slotted containers: name of the child element used as a slot
+   * (e.g. `accordion-item` under `accordion`).
+   */
+  slotChild?: string;
+  /** Declared attributes. */
+  attrs?: readonly NodeAttrSpec[];
+  /**
+   * For `mdc-container` and `mdc-slotted`: what MDC tag name to emit.
+   * Defaults to `name` (kebab-cased — `accordionItem` → `accordion-item`).
+   */
+  mdcTag?: string;
+  /**
+   * Whether the node is content-bearing (paragraph, listItem, etc.)
+   * or a child wrapper (tableRow, tableHeader).
+   */
+  contentBearing?: boolean;
+  doc?: string;
+}
+declare const NODE_SPECS: readonly NodeSpec[];
+declare const NODE_SPEC_BY_NAME: ReadonlyMap<string, NodeSpec>;
+/** Derive the MDC tag for a node — `mdcTag` override or kebab-case of `name`. */
+declare function mdcTagOf(spec: NodeSpec): string;
+//#endregion
+//#region packages/convert/src/spec/marks.d.ts
+type MarkWireKind = 'delimited' | 'link' | 'mdc-span';
+interface MarkAttrSpec {
+  key: string;
+  type: 'string' | 'number' | 'boolean';
+  optional?: boolean;
+}
+interface MarkSpec {
+  name: string;
+  wire: MarkWireKind;
+  /** For `delimited`: the markdown delimiter (e.g. `**`, `*`, `~~`, `` ` ``, `__`, `==`). */
+  delim?: string;
+  attrs?: readonly MarkAttrSpec[];
+  doc?: string;
+}
+declare const MARK_SPECS: readonly MarkSpec[];
+declare const MARK_SPEC_BY_NAME: ReadonlyMap<string, MarkSpec>;
+declare const MARK_SPEC_BY_DELIM: ReadonlyMap<string, MarkSpec>;
+//#endregion
+//#region packages/convert/src/spec/universal-meta.d.ts
+type MetaValueType = 'string' | 'number' | 'integer' | 'boolean' | 'string[]' | 'string-enum' | 'iso-date' | 'iso-datetime' | 'hh-mm' | 'members' | 'json';
+interface UniversalMetaKey {
+  key: string;
+  type: MetaValueType;
+  /** Allowed values for `string-enum`. */
+  values?: readonly string[];
+  /** Inclusive minimum for `number` / `integer`. */
+  min?: number;
+  /** Inclusive maximum for `number` / `integer`. */
+  max?: number;
+  /**
+   * Alternate YAML key names recognised on parse — for backwards
+   * compatibility with hand-written frontmatter (e.g. `date` → `dateStart`).
+   * Serialise always uses the canonical `key`.
+   */
+  parseAliases?: readonly string[];
+  /** Human-readable hint, surfaced in documentation. */
+  doc?: string;
+}
+declare const UNIVERSAL_META_KEYS: readonly UniversalMetaKey[];
+declare const UNIVERSAL_META_KEY_NAMES: ReadonlySet<string>;
+/**
+ * Build a map of every recognised input key (canonical + aliases) to
+ * its canonical key. Used by the frontmatter parser.
+ */
+declare function buildAliasMap(): ReadonlyMap<string, string>;
+//#endregion
+//#region packages/convert/src/file-blocks/manifest.d.ts
+interface FsAdapter {
+  readTextFile: (path: string) => Promise<string>;
+  writeTextFile: (path: string, contents: string) => Promise<void>;
+  mkdir: (path: string, options?: {
+    recursive?: boolean;
+  }) => Promise<void>;
+  readBinaryFile?: (path: string) => Promise<Uint8Array>;
+  writeBinaryFile?: (path: string, contents: Uint8Array) => Promise<void>;
+  exists?: (path: string) => Promise<boolean>;
+  remove?: (path: string) => Promise<void>;
+}
+/** Install a filesystem adapter. Call this once at boot. */
+declare function setFsAdapter(adapter: FsAdapter): void;
+/** Read back the active adapter — useful for tests and for layered code. */
+declare function getFsAdapter(): FsAdapter | null;
+interface UploadManifestEntry {
+  uploadId: string;
+  filename: string;
+  relativePath: string;
+  contentHash: string;
+}
+interface ManifestEntry {
+  docId: string;
+  relativePath: string;
+  contentHash: string;
+  lastWrittenAt: number;
+  lastReadAt: number;
+  uploads: UploadManifestEntry[];
+}
+interface FsSyncManifest {
+  version: 2;
+  spaceId: string;
+  lastSyncAt: number;
+  entries: Record<string, ManifestEntry>;
+}
+declare function manifestDir(syncDir: string): string;
+declare function trashDir(syncDir: string): string;
+declare function orphansDir(syncDir: string): string;
+declare function conflictsDir(syncDir: string): string;
+declare function createEmptyManifest(spaceId: string): FsSyncManifest;
+declare function loadManifest(syncDir: string, spaceId: string): Promise<FsSyncManifest>;
+declare function saveManifest(syncDir: string, manifest: FsSyncManifest): Promise<void>;
+declare function lookupByDocId(manifest: FsSyncManifest, docId: string): ManifestEntry | undefined;
+declare function lookupByPath(manifest: FsSyncManifest, relativePath: string): ManifestEntry | undefined;
+declare function lookupByHash(manifest: FsSyncManifest, contentHash: string): ManifestEntry | undefined;
+declare function setEntry(manifest: FsSyncManifest, entry: ManifestEntry): void;
+declare function removeEntry(manifest: FsSyncManifest, docId: string): ManifestEntry | undefined;
+declare function buildReverseLookup(manifest: FsSyncManifest): Map<string, string>;
+//#endregion
+//#region packages/convert/src/file-blocks/paths.d.ts
+interface FsTreeEntry {
+  label: string;
+  parentId: string | null;
+  order: number;
+  type?: string;
+  meta?: any;
+}
+/**
+ * Convert a document label to a filesystem-safe filename (without extension).
+ * e.g. "My Project!" -> "my-project"
+ */
+declare function labelToFilename(label: string): string;
+/**
+ * Convert a filename back to a label (best-effort).
+ * e.g. "my-project" -> "my project", "my-project~a3f2" -> "my project"
+ */
+declare function fsFilenameToLabel(filename: string): string;
+/**
+ * Check if a doc has children in the tree (needs _index.md convention).
+ */
+declare function hasChildren(docId: string, treeData: Record<string, FsTreeEntry>): boolean;
+/**
+ * Build the relative path for a document (from syncDir root).
+ * Handles:
+ * - Ancestor chain walking
+ * - _index.md for docs with children
+ * - Collision resolution via ~XXXX suffix
+ */
+declare function buildRelativePath(docId: string, treeData: Record<string, FsTreeEntry>, manifest: FsSyncManifest): string;
+/**
+ * Get the directory portion of a relative path for a doc.
+ * For _index.md docs: returns the directory containing _index.md
+ * For leaf docs: returns the parent directory
+ */
+declare function getDocDir(relativePath: string): string;
+/**
+ * Determine the parent docId from a filesystem relative path by walking the
+ * path segments and matching against the tree.
+ */
+declare function resolveParentFromPath(relativePath: string, treeData: Record<string, FsTreeEntry>): string | null;
+/**
+ * Simple string hash (same as current useFsSync).
+ */
+declare function simpleHash(str: string): string;
+/**
+ * Get all tree data as a flat record.
+ */
+declare function getTreeData(treeMap: any): Record<string, FsTreeEntry>;
+/**
+ * Find the next order value for a given parent (max sibling order + 1).
+ */
+declare function nextOrder(treeData: Record<string, FsTreeEntry>, parentId: string | null): number;
+//#endregion
+export { type DocPageMeta, type FrontmatterResult, type FsAdapter, type FsSyncManifest, type FsTreeEntry, type JsonAttr, MARK_SPECS, MARK_SPEC_BY_DELIM, MARK_SPEC_BY_NAME, type ManifestEntry, type MarkAttrSpec, type MarkSpec, type MarkWireKind, type MetaValueType, NODE_SPECS, NODE_SPEC_BY_NAME, type NodeAttrSpec, type NodeSpec, type NodeWireKind, UNIVERSAL_META_KEYS, UNIVERSAL_META_KEY_NAMES, type UniversalMetaKey, type UploadManifestEntry, type YjsDiff, type YjsJsonElement, type YjsJsonNode, type YjsJsonText, type YjsTextRun, appendHtmlToFragment, buildAliasMap, buildRelativePath, buildReverseLookup, conflictsDir, createEmptyManifest, diffJson, diffYjs, filenameToLabel, fsFilenameToLabel, getDocDir, getFsAdapter, getTreeData, hasChildren, jsonToYFragment, labelToFilename, loadManifest, lookupByDocId, lookupByHash, lookupByPath, manifestDir, mdcTagOf, nextOrder, orphansDir, parseFrontmatter, populateYDocFromHtml, populateYDocFromMarkdown, removeEntry, resolveParentFromPath, saveManifest, setEntry, setFsAdapter, simpleHash, stringifyJsonNode, trashDir, yfragmentToJson, yjsToHtml, yjsToMarkdown, yjsToPlainText };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@abraca/convert",
+  "version": "2.3.0",
+  "description": "Bullet-proof Markdown ↔ Yjs/TipTap round-trip — canonical converter shared by cou-sh, abracadabra-nuxt, and @abraca/mcp.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/abracadabra-convert.cjs",
+  "module": "dist/abracadabra-convert.esm.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "source": {
+      "import": "./src/index.ts"
+    },
+    "default": {
+      "import": "./dist/abracadabra-convert.esm.js",
+      "require": "./dist/abracadabra-convert.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "peerDependencies": {
+    "yjs": "^13.6.8"
+  },
+  "peerDependenciesMeta": {
+    "@tauri-apps/plugin-fs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "yjs": "^13.6.8"
+  },
+  "scripts": {
+    "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/**/*.test.ts'"
+  }
+}

package/src/diff.ts

@@ -0,0 +1,302 @@
+// Structural Y.XmlFragment ↔ JSON converter, used by the test harness
+// to make round-trip assertions and to author golden fixtures by hand.
+//
+// The JSON shape is canonical:
+//
+//   YjsJsonNode =
+//     | { kind: 'element'; tag: string; attrs?: Record<string, JsonAttr>; children: YjsJsonNode[] }
+//     | { kind: 'text'; runs: Array<{ insert: string; attributes?: Record<string, JsonAttr> }> }
+//
+// Attributes are stored verbatim — strings, numbers, booleans, null,
+// nested JSON (for things like codeTree's `files`). The format is
+// committed alongside fixtures as `.y.json` so reviews of intent
+// changes are diffable.
+//
+// `yfragmentToJson(frag)` is deterministic: the same Y.XmlFragment
+// always produces byte-identical JSON when stringified with sorted
+// keys.
+
+import * as Y from 'yjs'
+
+export type JsonAttr =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonAttr[]
+  | { [key: string]: JsonAttr }
+
+export interface YjsTextRun {
+  insert: string
+  attributes?: Record<string, JsonAttr>
+}
+
+export interface YjsJsonText {
+  kind: 'text'
+  runs: YjsTextRun[]
+}
+
+export interface YjsJsonElement {
+  kind: 'element'
+  tag: string
+  attrs?: Record<string, JsonAttr>
+  children: YjsJsonNode[]
+}
+
+export type YjsJsonNode = YjsJsonElement | YjsJsonText
+
+// ── Yjs → JSON ──────────────────────────────────────────────────────────────
+
+function attrsToJson(el: Y.XmlElement): Record<string, JsonAttr> | undefined {
+  const out: Record<string, JsonAttr> = {}
+  let count = 0
+  for (const key of Object.keys(el.getAttributes())) {
+    const raw: unknown = el.getAttribute(key)
+    out[key] = normaliseAttr(raw)
+    count++
+  }
+  if (count === 0) return undefined
+  return sortKeys(out)
+}
+
+function normaliseAttr(v: unknown): JsonAttr {
+  if (v == null) return null
+  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') return v
+  if (Array.isArray(v)) return v.map(normaliseAttr)
+  if (typeof v === 'object') {
+    const out: Record<string, JsonAttr> = {}
+    for (const k of Object.keys(v as object).sort()) {
+      out[k] = normaliseAttr((v as Record<string, unknown>)[k])
+    }
+    return out
+  }
+  // Functions / symbols / undefined — coerce to null so the JSON
+  // remains valid and diffs surface the loss.
+  return null
+}
+
+function sortKeys(obj: Record<string, JsonAttr>): Record<string, JsonAttr> {
+  const out: Record<string, JsonAttr> = {}
+  for (const k of Object.keys(obj).sort()) out[k] = obj[k]!
+  return out
+}
+
+function textToJson(text: Y.XmlText): YjsJsonText {
+  const delta = text.toDelta() as Array<{ insert: unknown, attributes?: Record<string, unknown> }>
+  const runs: YjsTextRun[] = []
+  for (const op of delta) {
+    if (typeof op.insert !== 'string') continue
+    const run: YjsTextRun = { insert: op.insert }
+    if (op.attributes && Object.keys(op.attributes).length > 0) {
+      const normalised: Record<string, JsonAttr> = {}
+      for (const k of Object.keys(op.attributes).sort()) {
+        normalised[k] = normaliseAttr(op.attributes[k])
+      }
+      run.attributes = normalised
+    }
+    runs.push(run)
+  }
+  return { kind: 'text', runs }
+}
+
+function elementToJson(el: Y.XmlElement): YjsJsonElement {
+  const attrs = attrsToJson(el)
+  const children: YjsJsonNode[] = []
+  for (const child of el.toArray()) {
+    if (child instanceof Y.XmlElement) children.push(elementToJson(child))
+    else if (child instanceof Y.XmlText) children.push(textToJson(child))
+  }
+  const out: YjsJsonElement = { kind: 'element', tag: el.nodeName, children }
+  if (attrs) out.attrs = attrs
+  return out
+}
+
+export function yfragmentToJson(frag: Y.XmlFragment): YjsJsonElement {
+  const children: YjsJsonNode[] = []
+  for (const child of frag.toArray()) {
+    if (child instanceof Y.XmlElement) children.push(elementToJson(child))
+    else if (child instanceof Y.XmlText) children.push(textToJson(child))
+  }
+  return { kind: 'element', tag: '#fragment', children }
+}
+
+// ── JSON → Yjs ──────────────────────────────────────────────────────────────
+
+// Yjs rule: every Y.XmlElement must be attached to its parent BEFORE
+// its attributes are set or its children inserted. Otherwise the runtime
+// logs "Invalid access: Add Yjs type to a document before reading data."
+// and silently no-ops the mutation.
+//
+// So we do this in two passes per node: (1) create empty skeleton +
+// attach to parent; (2) populate attrs + recurse on children, which
+// each follow the same pattern. cou-sh's populateYDocFromMarkdown uses
+// the same pattern.
+
+function populateElement(el: Y.XmlElement, node: YjsJsonElement): void {
+  if (node.attrs) {
+    for (const k of Object.keys(node.attrs)) {
+      // Y.XmlElement.setAttribute only types `string`, but accepts
+      // arbitrary values in practice (numbers, booleans, JSON objects).
+      const v = node.attrs[k]
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      el.setAttribute(k, v as any)
+    }
+  }
+  for (const child of node.children) {
+    if (child.kind === 'element') {
+      const sub = new Y.XmlElement(child.tag)
+      el.insert(el.length, [sub])
+      populateElement(sub, child)
+    }
+    else {
+      const text = new Y.XmlText()
+      el.insert(el.length, [text])
+      populateText(text, child)
+    }
+  }
+}
+
+function populateText(text: Y.XmlText, node: YjsJsonText): void {
+  let offset = 0
+  for (const run of node.runs) {
+    if (run.attributes) {
+      text.insert(offset, run.insert, run.attributes as unknown as object)
+    }
+    else {
+      text.insert(offset, run.insert)
+    }
+    offset += run.insert.length
+  }
+}
+
+/**
+ * Build a Y.XmlFragment from a previously captured golden JSON. The
+ * returned fragment is bound to a fresh Y.Doc so consumers can hand
+ * it to serialisers immediately. All Yjs mutations happen inside a
+ * single transaction.
+ */
+export function jsonToYFragment(root: YjsJsonElement, doc?: Y.Doc, key = 'body'): Y.XmlFragment {
+  if (root.tag !== '#fragment') {
+    throw new Error(`jsonToYFragment expected tag="#fragment", got "${root.tag}"`)
+  }
+  const ydoc = doc ?? new Y.Doc()
+  const frag = ydoc.getXmlFragment(key)
+  ydoc.transact(() => {
+    for (const child of root.children) {
+      if (child.kind === 'element') {
+        const sub = new Y.XmlElement(child.tag)
+        frag.insert(frag.length, [sub])
+        populateElement(sub, child)
+      }
+      else {
+        const text = new Y.XmlText()
+        frag.insert(frag.length, [text])
+        populateText(text, child)
+      }
+    }
+  })
+  return frag
+}
+
+// ── Diff (deep equality with a path) ────────────────────────────────────────
+
+export interface YjsDiff {
+  equal: boolean
+  /** Dotted path to the first divergence (empty when equal). */
+  path: string
+  /** Short human-readable explanation. */
+  reason: string
+}
+
+export function diffYjs(a: Y.XmlFragment, b: Y.XmlFragment): YjsDiff {
+  return diffNode(yfragmentToJson(a), yfragmentToJson(b), '')
+}
+
+export function diffJson(a: YjsJsonNode, b: YjsJsonNode): YjsDiff {
+  return diffNode(a, b, '')
+}
+
+function diffNode(a: YjsJsonNode, b: YjsJsonNode, path: string): YjsDiff {
+  if (a.kind !== b.kind) {
+    return { equal: false, path, reason: `kind mismatch: ${a.kind} vs ${b.kind}` }
+  }
+  if (a.kind === 'text' && b.kind === 'text') {
+    const ar = a.runs
+    const br = b.runs
+    if (ar.length !== br.length) {
+      return { equal: false, path, reason: `text run count: ${ar.length} vs ${br.length}` }
+    }
+    for (let i = 0; i < ar.length; i++) {
+      const sub = `${path}/runs[${i}]`
+      const ai = ar[i]!
+      const bi = br[i]!
+      if (ai.insert !== bi.insert) {
+        return { equal: false, path: sub, reason: `insert: ${JSON.stringify(ai.insert)} vs ${JSON.stringify(bi.insert)}` }
+      }
+      const attrDiff = diffAttrs(ai.attributes, bi.attributes, sub)
+      if (!attrDiff.equal) return attrDiff
+    }
+    return { equal: true, path: '', reason: '' }
+  }
+  if (a.kind === 'element' && b.kind === 'element') {
+    if (a.tag !== b.tag) return { equal: false, path, reason: `tag: ${a.tag} vs ${b.tag}` }
+    const attrDiff = diffAttrs(a.attrs, b.attrs, path)
+    if (!attrDiff.equal) return attrDiff
+    if (a.children.length !== b.children.length) {
+      return { equal: false, path, reason: `child count: ${a.children.length} vs ${b.children.length}` }
+    }
+    for (let i = 0; i < a.children.length; i++) {
+      const sub = path === '' ? `[${i}]` : `${path}[${i}]`
+      const childDiff = diffNode(a.children[i]!, b.children[i]!, sub)
+      if (!childDiff.equal) return childDiff
+    }
+    return { equal: true, path: '', reason: '' }
+  }
+  return { equal: false, path, reason: 'unreachable kind combination' }
+}
+
+function diffAttrs(
+  a: Record<string, JsonAttr> | undefined,
+  b: Record<string, JsonAttr> | undefined,
+  path: string,
+): YjsDiff {
+  const ak = a ? Object.keys(a).sort() : []
+  const bk = b ? Object.keys(b).sort() : []
+  if (ak.length !== bk.length || ak.some((k, i) => k !== bk[i])) {
+    return { equal: false, path: `${path}.attrs`, reason: `attr keys: [${ak.join(',')}] vs [${bk.join(',')}]` }
+  }
+  for (const k of ak) {
+    const av = a![k]
+    const bv = b![k]
+    if (!attrEqual(av, bv)) {
+      return {
+        equal: false,
+        path: `${path}.attrs.${k}`,
+        reason: `attr value: ${JSON.stringify(av)} vs ${JSON.stringify(bv)}`,
+      }
+    }
+  }
+  return { equal: true, path: '', reason: '' }
+}
+
+function attrEqual(a: JsonAttr, b: JsonAttr): boolean {
+  if (a === b) return true
+  if (a === null || b === null) return false
+  if (typeof a !== typeof b) return false
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false
+    return a.every((v, i) => attrEqual(v, b[i]!))
+  }
+  if (typeof a === 'object' && typeof b === 'object') {
+    const ak = Object.keys(a).sort()
+    const bk = Object.keys(b).sort()
+    if (ak.length !== bk.length || ak.some((k, i) => k !== bk[i])) return false
+    return ak.every(k => attrEqual((a as Record<string, JsonAttr>)[k]!, (b as Record<string, JsonAttr>)[k]!))
+  }
+  return false
+}
+
+/** Stringify a YjsJsonNode with sorted keys for byte-stable golden files. */
+export function stringifyJsonNode(node: YjsJsonNode): string {
+  return JSON.stringify(node, null, 2) + '\n'
+}