@1agh/maude 1.4.6 → 1.5.0

package/apps/studio/annotations/replica.ts

@@ -0,0 +1,264 @@
+/**
+ * @file       annotations/replica.ts — the annotations-v2 Yjs replica (DDR-242 §5)
+ * @scope      apps/studio/annotations/replica.ts
+ * @purpose    One codec for the board inside a Y.Doc, used by every writer: the
+ *             collab room, the studio sync agent + projection, and the hub
+ *             kernel. The replica is
+ *
+ *               Y.Map('annotations2')   element id → Y.Map(field → JSON value)
+ *                 '~v'      = 2          format marker (present once v2 wrote)
+ *                 '~action' = <id>       the action that produced the last write
+ *
+ *             A NEW type name on purpose: a v1 peer keeps writing
+ *             `Y.Map('annotations').svg`, which v2 never reads once '~v' is set,
+ *             so a stale peer can't erase a v2 board (the DDR-223 failure class).
+ *             Before any v2 write, the legacy value is read through the v1→v2
+ *             migration (lazy, read-only).
+ *
+ *             Writes are DIFFS: callers hand over a whole board (or ops) and
+ *             only changed elements / fields become Yjs updates — so every lane
+ *             "replace" in the sync code now crosses the wire per element.
+ *
+ *             The doc is peer-writable in legacy mode, so every read validates
+ *             (DDR-054): a malformed element is dropped, never trusted.
+ */
+
+import * as Y from 'yjs';
+import { MAX_LEGACY_SVG_BYTES } from './constants.ts';
+import { jsonEq } from './fields.ts';
+import { migrateSvg } from './migrate-v1.ts';
+import { type ApplyResult, applyOps, type Op } from './ops.ts';
+import { type BoardResult, parseBoard, serializeBoard, validateElements } from './schema.ts';
+import type { AnnotationElement } from './types.ts';
+
+export const REPLICA_TYPE = 'annotations2';
+/** The v1 map (`svg` key). Read only for lazy migration. */
+export const LEGACY_TYPE = 'annotations';
+export const FORMAT_KEY = '~v';
+export const ACTION_KEY = '~action';
+export const REPLICA_VERSION = 2;
+
+const ACTION_RE = /^[A-Za-z0-9_-]{1,96}$/;
+
+export function validActionId(v: unknown): v is string {
+  return typeof v === 'string' && ACTION_RE.test(v);
+}
+
+function outer(doc: Y.Doc): Y.Map<unknown> {
+  return doc.getMap<unknown>(REPLICA_TYPE);
+}
+
+/** True once any v2 writer has written this doc. */
+export function hasReplica(doc: Y.Doc): boolean {
+  return outer(doc).get(FORMAT_KEY) === REPLICA_VERSION;
+}
+
+function legacySvg(doc: Y.Doc): string | null {
+  const svg = doc.getMap<unknown>(LEGACY_TYPE).get('svg');
+  return typeof svg === 'string' && svg.trim() ? svg : null;
+}
+
+/**
+ * The board held by the doc, or null when it was never populated (neither a v2
+ * write nor a legacy value) — the cold-start "unknown" state, distinct from an
+ * empty board.
+ */
+export function readReplica(doc: Y.Doc): BoardResult | null {
+  const map = outer(doc);
+  if (map.get(FORMAT_KEY) === REPLICA_VERSION) {
+    const raw: unknown[] = [];
+    for (const [key, value] of map.entries()) {
+      if (key.startsWith('~')) continue;
+      if (value instanceof Y.Map) raw.push({ ...value.toJSON(), id: key });
+    }
+    return validateElements(raw);
+  }
+  const svg = legacySvg(doc);
+  if (svg !== null) {
+    // A peer-written legacy value far beyond the v1 cap is not parsed at all.
+    if (svg.length > MAX_LEGACY_SVG_BYTES) {
+      return {
+        elements: [],
+        dropped: [{ reason: 'legacy annotations value exceeds the size cap' }],
+      };
+    }
+    const m = migrateSvg(svg);
+    return { elements: m.elements, dropped: m.report };
+  }
+  if (doc.getMap<unknown>(LEGACY_TYPE).has('svg')) return { elements: [], dropped: [] };
+  return null;
+}
+
+/** Canonical board text of the doc, or null when never populated. */
+export function replicaBoardText(doc: Y.Doc): string | null {
+  const r = readReplica(doc);
+  return r ? serializeBoard(r.elements) : null;
+}
+
+/** The last action id recorded by a v2 writer (echo suppression). */
+export function replicaActionId(doc: Y.Doc): string | undefined {
+  const v = outer(doc).get(ACTION_KEY);
+  return validActionId(v) ? v : undefined;
+}
+
+/**
+ * The board text a doc's replica last AGREED with on disk — noted by every
+ * doc→disk projector (the room's flush, the sync agent's writer) and by the
+ * disk→doc importer. Keyed by the doc, so all projectors of a shared doc see
+ * the same base (sync/codec.ts `importAnnotationsFromDisk`).
+ */
+const onDisk = new WeakMap<Y.Doc, string>();
+
+/** Record that disk holds `text` as projected from / imported into `doc`. */
+export function noteAnnotationsOnDisk(doc: Y.Doc, text: string): void {
+  onDisk.set(doc, text);
+}
+
+export function annotationsOnDiskOf(doc: Y.Doc): string | undefined {
+  return onDisk.get(doc);
+}
+
+export interface WriteOpts {
+  /** Recorded under '~action' so the author can recognise its own echo. */
+  actionId?: string;
+}
+
+/**
+ * Make the replica hold exactly `elements` (already canonical), touching only
+ * what differs. Returns whether anything changed. One transaction, `origin`
+ * tagged, so peers receive ONE update.
+ */
+export function writeReplica(
+  doc: Y.Doc,
+  elements: readonly AnnotationElement[],
+  origin?: unknown,
+  opts: WriteOpts = {}
+): boolean {
+  const map = outer(doc);
+  const target = new Map(elements.map((e) => [e.id, e]));
+  let changed = false;
+  doc.transact(() => {
+    if (map.get(FORMAT_KEY) !== REPLICA_VERSION) {
+      map.set(FORMAT_KEY, REPLICA_VERSION);
+      changed = true;
+    }
+    for (const key of [...map.keys()]) {
+      if (key.startsWith('~') || target.has(key)) continue;
+      map.delete(key);
+      changed = true;
+    }
+    for (const [id, el] of target) {
+      const cur = map.get(id);
+      const fields = Object.entries(el).filter(([k]) => k !== 'id');
+      if (!(cur instanceof Y.Map)) {
+        const inner = new Y.Map<unknown>();
+        for (const [k, v] of fields) inner.set(k, v);
+        map.set(id, inner);
+        changed = true;
+        continue;
+      }
+      const keep = new Set(fields.map(([k]) => k));
+      for (const k of [...cur.keys()]) {
+        if (!keep.has(k)) {
+          cur.delete(k);
+          changed = true;
+        }
+      }
+      for (const [k, v] of fields) {
+        if (!jsonEq(cur.get(k), v)) {
+          cur.set(k, v);
+          changed = true;
+        }
+      }
+    }
+    if (changed && opts.actionId && validActionId(opts.actionId))
+      map.set(ACTION_KEY, opts.actionId);
+    else if (changed) map.delete(ACTION_KEY);
+  }, origin);
+  return changed;
+}
+
+/** `writeReplica` from untrusted board text. Returns null when the text is not a board. */
+export function writeReplicaText(
+  doc: Y.Doc,
+  text: string | null,
+  origin?: unknown,
+  opts: WriteOpts = {}
+): boolean | null {
+  if (text === null || text === '') return writeReplica(doc, [], origin, opts);
+  const parsed = parseBoard(text);
+  if (parsed.dropped.some((d) => d.id === undefined)) return null; // not a board document
+  return writeReplica(doc, parsed.elements, origin, opts);
+}
+
+/** Apply ops to the replica under the DDR-242 merge rule; writes only the diff. */
+export function applyOpsToReplica(
+  doc: Y.Doc,
+  ops: readonly Op[],
+  origin?: unknown,
+  opts: WriteOpts = {}
+): ApplyResult {
+  const cur = readReplica(doc)?.elements ?? [];
+  const r = applyOps(new Map(cur.map((e) => [e.id, e])), ops);
+  if (r.touched.size || !hasReplica(doc)) writeReplica(doc, [...r.state.values()], origin, opts);
+  return r;
+}
+
+/**
+ * Observe the replica. `cb` receives the whole validated board, the ids whose
+ * records changed, and the action id of the write (undefined for a legacy /
+ * unattributed write). Fires once immediately with the current state — but
+ * never for a doc that was never populated: "no value yet" is not an empty
+ * board, and reporting it as one would wipe what the caller already loaded
+ * (the DDR-223 lesson).
+ */
+export function observeReplica(
+  doc: Y.Doc,
+  cb: (
+    elements: AnnotationElement[],
+    changed: ReadonlySet<string>,
+    actionId: string | undefined
+  ) => void
+): () => void {
+  const map = outer(doc);
+  const legacy = doc.getMap<unknown>(LEGACY_TYPE);
+  const emit = (changed: Set<string>) => {
+    const r = readReplica(doc);
+    if (r === null) return;
+    cb(r.elements, changed, replicaActionId(doc));
+  };
+  const onDeep = (events: Y.YEvent<Y.AbstractType<unknown>>[]) => {
+    const changed = new Set<string>();
+    for (const ev of events) {
+      if (ev.target === map) {
+        for (const k of (ev as Y.YMapEvent<unknown>).keysChanged)
+          if (!k.startsWith('~')) changed.add(k);
+      } else {
+        const id = ev.path[0];
+        if (typeof id === 'string') changed.add(id);
+      }
+    }
+    if (changed.size) emit(changed);
+  };
+  // Until a v2 writer has written, a legacy peer's `svg` is the source.
+  const onLegacy = (ev: Y.YMapEvent<unknown>) => {
+    if (!hasReplica(doc) && ev.keysChanged.has('svg')) emit(new Set());
+  };
+  map.observeDeep(onDeep);
+  legacy.observe(onLegacy);
+  emit(new Set());
+  return () => {
+    map.unobserveDeep(onDeep);
+    legacy.unobserve(onLegacy);
+  };
+}
+
+/** Zero elements — the cold-start emptiness test (DDR-223), for board text or legacy SVG. */
+export function isEmptyBoardText(text: string | null): boolean {
+  if (text === null || text.trim() === '') return true;
+  if (/^\s*</.test(text)) {
+    if (text.length > MAX_LEGACY_SVG_BYTES) return false; // unparsed ≠ empty (DDR-223)
+    return migrateSvg(text).elements.length === 0;
+  }
+  return parseBoard(text).elements.length === 0;
+}

package/apps/studio/annotations/scene.ts

@@ -0,0 +1,235 @@
+/**
+ * @file       annotations/scene.ts — world-space view over a set of elements
+ * @scope      apps/studio/annotations/scene.ts
+ * @purpose    Elements store PARENT-relative geometry (DDR-242 §1). The scene
+ *             turns that into world space: parent origins, world boxes, arrow
+ *             endpoints, paint order (a container is followed by its subtree),
+ *             subtree queries and top-most hit-testing. Pure and React-free —
+ *             the canvas, the AI projection and the hub all use this one.
+ */
+
+import { MAX_NESTING_DEPTH } from './constants.ts';
+import { arrowEnds, type ResolvedArrow } from './elements/arrow.model.ts';
+import { textBindable } from './elements/text.model.ts';
+import { compareOrder } from './fractional-index.ts';
+import { defOf } from './registry.ts';
+import type { AnnotationElement, Box, GeomCtx } from './types.ts';
+
+const TOP = '\u0000top';
+
+export class Scene {
+  readonly byId: ReadonlyMap<string, AnnotationElement>;
+  private readonly kids = new Map<string, AnnotationElement[]>();
+  private readonly originCache = new Map<string, { x: number; y: number }>();
+
+  constructor(elements: Iterable<AnnotationElement>) {
+    const byId = new Map<string, AnnotationElement>();
+    for (const el of elements) byId.set(el.id, el);
+    this.byId = byId;
+    for (const el of byId.values()) {
+      const p = this.effectiveParent(el);
+      const key = p ?? TOP;
+      const list = this.kids.get(key);
+      if (list) list.push(el);
+      else this.kids.set(key, [el]);
+    }
+    for (const list of this.kids.values()) list.sort(compareOrder);
+  }
+
+  get(id: string): AnnotationElement | undefined {
+    return this.byId.get(id);
+  }
+
+  get size(): number {
+    return this.byId.size;
+  }
+
+  /**
+   * The parent an element is actually drawn under: its `parent` when that names
+   * an existing CONTAINER reachable without a cycle, else top level. A dangling
+   * parent (deleted concurrently) degrades to top level — never to a lost node.
+   */
+  effectiveParent(el: AnnotationElement): string | null {
+    const seen = new Set<string>([el.id]);
+    let cur = el.parent;
+    let depth = 0;
+    let first: string | null = null;
+    while (cur !== undefined) {
+      const p = this.byId.get(cur);
+      if (!p || seen.has(cur) || !defOf(p.type)?.caps.container || depth >= MAX_NESTING_DEPTH) {
+        return null;
+      }
+      if (first === null) first = cur;
+      seen.add(cur);
+      cur = p.parent;
+      depth++;
+    }
+    return first;
+  }
+
+  /** Children of `parent` (null = top level) in paint order. */
+  childrenOf(parent: string | null): readonly AnnotationElement[] {
+    return this.kids.get(parent ?? TOP) ?? [];
+  }
+
+  /** Every element in paint order: siblings by (index, id), a container before its subtree. */
+  paintOrder(): AnnotationElement[] {
+    const out: AnnotationElement[] = [];
+    const walk = (parent: string | null) => {
+      for (const el of this.childrenOf(parent)) {
+        out.push(el);
+        if (defOf(el.type)?.caps.container) walk(el.id);
+      }
+    };
+    walk(null);
+    return out;
+  }
+
+  /** All descendants of `id` (not including it), in paint order. */
+  descendants(id: string): AnnotationElement[] {
+    const out: AnnotationElement[] = [];
+    const walk = (parent: string) => {
+      for (const el of this.childrenOf(parent)) {
+        out.push(el);
+        walk(el.id);
+      }
+    };
+    walk(id);
+    return out;
+  }
+
+  /** Ancestor ids, nearest first. */
+  ancestors(id: string): string[] {
+    const out: string[] = [];
+    const el = this.byId.get(id);
+    let cur = el ? this.effectiveParent(el) : null;
+    while (cur) {
+      out.push(cur);
+      const p = this.byId.get(cur);
+      cur = p ? this.effectiveParent(p) : null;
+    }
+    return out;
+  }
+
+  /** World origin of the element's parent (0,0 at top level). */
+  originOf(el: AnnotationElement): { x: number; y: number } {
+    const p = this.effectiveParent(el);
+    if (!p) return { x: 0, y: 0 };
+    const cached = this.originCache.get(p);
+    if (cached) return cached;
+    const parent = this.byId.get(p) as AnnotationElement;
+    const po = this.originOf(parent);
+    const o = {
+      x: po.x + (typeof parent.x === 'number' ? parent.x : 0),
+      y: po.y + (typeof parent.y === 'number' ? parent.y : 0),
+    };
+    this.originCache.set(p, o);
+    return o;
+  }
+
+  ctx(el: AnnotationElement): GeomCtx {
+    return { origin: this.originOf(el), resolve: (id) => this.resolve(id) };
+  }
+
+  private resolve(id: string): { box: Box; rot: number; bindable: boolean } | null {
+    const el = this.byId.get(id);
+    if (!el) return null;
+    const def = defOf(el.type);
+    if (!def?.caps.box) return null;
+    const box = this.worldBox(el);
+    if (!box) return null;
+    let bindable = def.caps.bindable;
+    if (el.type === 'text') bindable = textBindable(box.w, box.h);
+    return { box, rot: typeof el.rot === 'number' ? el.rot : 0, bindable };
+  }
+
+  /** Unrotated world bounds, or null (unknown type without a box, degenerate arrow…). */
+  worldBox(elOrId: AnnotationElement | string): Box | null {
+    const el = typeof elOrId === 'string' ? this.byId.get(elOrId) : elOrId;
+    if (!el) return null;
+    const def = defOf(el.type);
+    let local: Box | null;
+    if (def) {
+      // Arrows resolve their hosts in world space and return parent-space bounds.
+      local = def.bounds(el, this.ctx(el));
+    } else {
+      const { x, y, w, h } = el as Record<string, unknown>;
+      local =
+        typeof x === 'number' &&
+        typeof y === 'number' &&
+        typeof w === 'number' &&
+        typeof h === 'number'
+          ? { x, y, w, h }
+          : null;
+    }
+    if (!local) return null;
+    const o = this.originOf(el);
+    return { x: local.x + o.x, y: local.y + o.y, w: local.w, h: local.h };
+  }
+
+  /** World endpoints of an arrow. */
+  arrowWorld(el: AnnotationElement): ResolvedArrow | null {
+    if (el.type !== 'arrow') return null;
+    const r = arrowEnds(el, this.ctx(el));
+    if (!r) return null;
+    const o = this.originOf(el);
+    return { ...r, x1: r.x1 + o.x, y1: r.y1 + o.y, x2: r.x2 + o.x, y2: r.y2 + o.y };
+  }
+
+  /** Top-most element whose hit-test accepts the WORLD point, optionally filtered. */
+  hitTest(
+    wx: number,
+    wy: number,
+    tol: number,
+    accept: (el: AnnotationElement) => boolean = () => true
+  ): AnnotationElement | null {
+    const order = this.paintOrder();
+    for (let i = order.length - 1; i >= 0; i--) {
+      const el = order[i] as AnnotationElement;
+      if (!accept(el)) continue;
+      const def = defOf(el.type);
+      const o = this.originOf(el);
+      if (def) {
+        if (def.hitTest(el, wx - o.x, wy - o.y, tol, this.ctx(el))) return el;
+      } else {
+        const b = this.worldBox(el);
+        if (
+          b &&
+          wx >= b.x - tol &&
+          wx <= b.x + b.w + tol &&
+          wy >= b.y - tol &&
+          wy <= b.y + b.h + tol
+        ) {
+          return el;
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Deepest container whose world box contains the world point — the section an
+   * element dropped at that point belongs to. `exclude` skips a subtree (the
+   * dragged selection must not become its own parent).
+   */
+  containerAt(
+    wx: number,
+    wy: number,
+    exclude: ReadonlySet<string> = new Set()
+  ): AnnotationElement | null {
+    let best: AnnotationElement | null = null;
+    let bestDepth = -1;
+    for (const el of this.byId.values()) {
+      if (exclude.has(el.id) || !defOf(el.type)?.caps.container) continue;
+      if (this.ancestors(el.id).some((a) => exclude.has(a))) continue;
+      const b = this.worldBox(el);
+      if (!b || wx < b.x || wx > b.x + b.w || wy < b.y || wy > b.y + b.h) continue;
+      const depth = this.ancestors(el.id).length;
+      if (depth > bestDepth) {
+        best = el;
+        bestDepth = depth;
+      }
+    }
+    return best;
+  }
+}

package/apps/studio/annotations/schema.ts

@@ -0,0 +1,188 @@
+/**
+ * @file       annotations/schema.ts — the annotations-v2 board: validate, parse, serialize
+ * @scope      apps/studio/annotations/schema.ts
+ * @purpose    DDR-242 §2–§3. A board is `{"format":"maude.annotations","v":2,
+ *             "elements":[…]}` written with ONE element per line in a
+ *             deterministic order, so the same board is the same bytes on every
+ *             machine and a git diff shows exactly which element changed.
+ *
+ *             Validation is TOTAL and per element: a bad element is dropped and
+ *             reported, never the whole board (the DDR-223 lesson — emptiness
+ *             must never be manufactured from a parse problem). Board-level
+ *             rules: unique ids, a valid `index` (repaired, not dropped), no
+ *             parent cycles, nesting depth ≤ MAX_NESTING_DEPTH, element and byte
+ *             caps.
+ */
+
+import { MAX_BOARD_BYTES, MAX_ELEMENTS, MAX_NESTING_DEPTH } from './constants.ts';
+import { parseJsonSafe } from './fields.ts';
+import { compareOrder, isValidOrderKey, keyBetween } from './fractional-index.ts';
+import { defOf, validateElement } from './registry.ts';
+import type { AnnotationElement } from './types.ts';
+
+export const BOARD_FORMAT = 'maude.annotations';
+export const BOARD_VERSION = 2;
+
+export interface Dropped {
+  id?: string;
+  reason: string;
+}
+
+export interface BoardResult {
+  elements: AnnotationElement[];
+  dropped: Dropped[];
+}
+
+/** Sort key: depth first, then parent, then (index, id) — parents always precede children. */
+function canonicalOrder(elements: readonly AnnotationElement[]): AnnotationElement[] {
+  const byId = new Map(elements.map((e) => [e.id, e]));
+  const depth = (e: AnnotationElement): number => {
+    let d = 0;
+    let cur = e.parent;
+    while (cur !== undefined && d <= MAX_NESTING_DEPTH) {
+      d++;
+      cur = byId.get(cur)?.parent;
+    }
+    return d;
+  };
+  const depths = new Map(elements.map((e) => [e.id, depth(e)]));
+  return [...elements].sort((a, b) => {
+    const da = depths.get(a.id) as number;
+    const db = depths.get(b.id) as number;
+    if (da !== db) return da - db;
+    const pa = a.parent ?? '';
+    const pb = b.parent ?? '';
+    if (pa !== pb) return pa < pb ? -1 : 1;
+    return compareOrder(a, b);
+  });
+}
+
+/**
+ * Validate an untrusted element list into canonical records.
+ *  - invalid records are dropped + reported;
+ *  - a duplicate id keeps the FIRST occurrence;
+ *  - an invalid `index` is repaired (appended after its siblings) — a z-order
+ *    glitch is never a reason to lose content;
+ *  - a `parent` that is missing, not a container, cyclic or too deep is cleared
+ *    (the element is kept at top level, its coordinates unchanged — the caller
+ *    of a live edit never produces that; this only guards hostile/stale input).
+ */
+export function validateElements(raw: readonly unknown[]): BoardResult {
+  const dropped: Dropped[] = [];
+  const out: AnnotationElement[] = [];
+  const seen = new Set<string>();
+  const needsIndex: Record<string, unknown>[] = [];
+  for (const item of raw.slice(0, MAX_ELEMENTS)) {
+    let candidate = item;
+    // Repair a bad index before validation so the element survives it.
+    if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) {
+      const idx = (candidate as Record<string, unknown>).index;
+      if (typeof idx !== 'string' || !isValidOrderKey(idx)) {
+        candidate = { ...(candidate as Record<string, unknown>), index: 'a0' };
+        needsIndex.push(candidate as Record<string, unknown>);
+      }
+    }
+    const r = validateElement(candidate);
+    if (!r.ok) {
+      dropped.push({ id: r.id, reason: r.reason });
+      continue;
+    }
+    if (seen.has(r.el.id)) {
+      dropped.push({ id: r.el.id, reason: 'duplicate id' });
+      continue;
+    }
+    seen.add(r.el.id);
+    out.push(r.el);
+  }
+  if (raw.length > MAX_ELEMENTS) {
+    dropped.push({
+      reason: `board exceeds ${MAX_ELEMENTS} elements; ${raw.length - MAX_ELEMENTS} dropped`,
+    });
+  }
+  const byId = new Map(out.map((e) => [e.id, e]));
+  // Parent sanity: missing / non-container / cycle / too deep → top level.
+  for (const el of out) {
+    if (el.parent === undefined) continue;
+    const seenChain = new Set<string>([el.id]);
+    let cur: string | undefined = el.parent;
+    let depth = 0;
+    let ok = true;
+    while (cur !== undefined) {
+      const p = byId.get(cur);
+      if (
+        !p ||
+        seenChain.has(cur) ||
+        !defOf(p.type)?.caps.container ||
+        ++depth > MAX_NESTING_DEPTH
+      ) {
+        ok = false;
+        break;
+      }
+      seenChain.add(cur);
+      cur = p.parent;
+    }
+    if (!ok) {
+      delete el.parent;
+      dropped.push({ id: el.id, reason: 'invalid parent cleared (kept at top level)' });
+    }
+  }
+  // Index repair: append after the siblings' current maximum, in input order.
+  const repaired = new Set(needsIndex.map((c) => c.id));
+  for (const el of out) {
+    if (!repaired.has(el.id)) continue;
+    let max: string | null = null;
+    for (const s of out) {
+      if (s === el || repaired.has(s.id) || s.parent !== el.parent) continue;
+      if (max === null || s.index > max) max = s.index;
+    }
+    el.index = keyBetween(max, null);
+    repaired.delete(el.id);
+  }
+  return { elements: canonicalOrder(out), dropped };
+}
+
+/** Parse a board file (untrusted text). A malformed file yields zero elements + a report. */
+export function parseBoard(text: string): BoardResult {
+  if (text.length > MAX_BOARD_BYTES) {
+    return { elements: [], dropped: [{ reason: 'board file exceeds the byte cap' }] };
+  }
+  const doc = parseJsonSafe(text);
+  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+    return { elements: [], dropped: [{ reason: 'not a board document' }] };
+  }
+  const d = doc as Record<string, unknown>;
+  if (d.format !== BOARD_FORMAT || typeof d.v !== 'number') {
+    return { elements: [], dropped: [{ reason: 'unknown board format' }] };
+  }
+  if (d.v > BOARD_VERSION) {
+    return {
+      elements: [],
+      dropped: [{ reason: `board format v${d.v} is newer than this client` }],
+    };
+  }
+  return validateElements(Array.isArray(d.elements) ? d.elements : []);
+}
+
+/**
+ * Canonical bytes. Records are already canonical (spec key order, defaults
+ * omitted); this fixes the element order and the one-element-per-line layout.
+ */
+export function serializeBoard(elements: readonly AnnotationElement[]): string {
+  const ordered = canonicalOrder(elements);
+  if (ordered.length === 0) {
+    return `{"format":"${BOARD_FORMAT}","v":${BOARD_VERSION},"elements":[]}\n`;
+  }
+  const lines = ordered.map((e) => JSON.stringify(e));
+  return `{"format":"${BOARD_FORMAT}","v":${BOARD_VERSION},"elements":[\n${lines.join(',\n')}\n]}\n`;
+}
+
+export function isEmptyBoard(elements: readonly unknown[]): boolean {
+  return elements.length === 0;
+}
+
+/** Canonical form of one record (re-validated). Throws only on programmer error. */
+export function canonical(el: Record<string, unknown>): AnnotationElement {
+  const r = validateElement(el);
+  if (!r.ok) throw new Error(`invalid element ${String(el.id)}: ${r.reason}`);
+  return r.el;
+}