@1agh/maude 1.4.6 → 1.5.0

package/apps/studio/annotations/fractional-index.ts

@@ -0,0 +1,234 @@
+/**
+ * @file       annotations/fractional-index.ts — z-order keys (DDR-242 §1)
+ * @scope      apps/studio/annotations/fractional-index.ts
+ * @purpose    Fractional indexing: a key strictly between any two keys, so a
+ *             reorder writes ONE element instead of renumbering its neighbours,
+ *             and two peers reordering concurrently converge.
+ *
+ *             Port of the algorithm in rocicorp/fractional-indexing
+ *             (https://github.com/rocicorp/fractional-indexing, CC0-1.0 — public
+ *             domain; kept in-tree so the hub, a DDR-054 "untrusted to peers"
+ *             component with a frozen lockfile, takes no new dependency).
+ *
+ *             Two peers inserting between the same two keys produce the SAME
+ *             key — order is therefore always `(index, id)` (`compareOrder`),
+ *             never index alone.
+ */
+
+export const BASE_62_DIGITS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+const ZERO = '0';
+const SMALLEST_INTEGER = `A${ZERO.repeat(26)}`;
+
+function midpoint(a: string, b: string | null): string {
+  if (b != null && a >= b) throw new Error(`${a} >= ${b}`);
+  if (a.slice(-1) === ZERO || (b && b.slice(-1) === ZERO)) throw new Error('trailing zero');
+  if (b) {
+    let n = 0;
+    while ((a[n] || ZERO) === b[n]) n++;
+    if (n > 0) return b.slice(0, n) + midpoint(a.slice(n), b.slice(n));
+  }
+  const digitA = a ? BASE_62_DIGITS.indexOf(a[0] as string) : 0;
+  const digitB = b != null ? BASE_62_DIGITS.indexOf(b[0] as string) : BASE_62_DIGITS.length;
+  if (digitB - digitA > 1) {
+    return BASE_62_DIGITS[Math.round(0.5 * (digitA + digitB))] as string;
+  }
+  if (b && b.length > 1) return b.slice(0, 1);
+  return (BASE_62_DIGITS[digitA] as string) + midpoint(a.slice(1), null);
+}
+
+function integerLength(head: string): number {
+  if (head >= 'a' && head <= 'z') return head.charCodeAt(0) - 97 + 2;
+  if (head >= 'A' && head <= 'Z') return 90 - head.charCodeAt(0) + 2;
+  throw new Error(`invalid order key head: ${head}`);
+}
+
+function integerPart(key: string): string {
+  const len = integerLength(key[0] as string);
+  if (len > key.length) throw new Error(`invalid order key: ${key}`);
+  return key.slice(0, len);
+}
+
+/** True when `key` is a well-formed order key (used to validate untrusted input). */
+export function isValidOrderKey(key: string): boolean {
+  try {
+    if (key === SMALLEST_INTEGER) return false;
+    if (!/^[0-9A-Za-z]+$/.test(key)) return false;
+    const i = integerPart(key);
+    return key.slice(i.length).slice(-1) !== ZERO;
+  } catch {
+    return false;
+  }
+}
+
+function assertKey(key: string): void {
+  if (!isValidOrderKey(key)) throw new Error(`invalid order key: ${key}`);
+}
+
+function incrementInteger(x: string): string | null {
+  const [head, ...digs] = x.split('') as [string, ...string[]];
+  let carry = true;
+  for (let i = digs.length - 1; carry && i >= 0; i--) {
+    const d = BASE_62_DIGITS.indexOf(digs[i] as string) + 1;
+    if (d === BASE_62_DIGITS.length) digs[i] = ZERO;
+    else {
+      digs[i] = BASE_62_DIGITS[d] as string;
+      carry = false;
+    }
+  }
+  if (!carry) return head + digs.join('');
+  if (head === 'Z') return `a${ZERO}`;
+  if (head === 'z') return null;
+  const h = String.fromCharCode(head.charCodeAt(0) + 1);
+  if (h > 'a') digs.push(ZERO);
+  else digs.pop();
+  return h + digs.join('');
+}
+
+function decrementInteger(x: string): string | null {
+  const [head, ...digs] = x.split('') as [string, ...string[]];
+  let borrow = true;
+  for (let i = digs.length - 1; borrow && i >= 0; i--) {
+    const d = BASE_62_DIGITS.indexOf(digs[i] as string) - 1;
+    if (d === -1) digs[i] = BASE_62_DIGITS.slice(-1);
+    else {
+      digs[i] = BASE_62_DIGITS[d] as string;
+      borrow = false;
+    }
+  }
+  if (!borrow) return head + digs.join('');
+  if (head === 'a') return `Z${BASE_62_DIGITS.slice(-1)}`;
+  if (head === 'A') return null;
+  const h = String.fromCharCode(head.charCodeAt(0) - 1);
+  if (h < 'Z') digs.push(BASE_62_DIGITS.slice(-1));
+  else digs.pop();
+  return h + digs.join('');
+}
+
+/** A key strictly between `a` and `b` (null = open end). Throws if `a >= b`. */
+export function keyBetween(a: string | null, b: string | null): string {
+  if (a != null) assertKey(a);
+  if (b != null) assertKey(b);
+  if (a != null && b != null && a >= b) throw new Error(`${a} >= ${b}`);
+  if (a == null) {
+    if (b == null) return `a${ZERO}`;
+    const ib = integerPart(b);
+    const fb = b.slice(ib.length);
+    if (ib === SMALLEST_INTEGER) return ib + midpoint('', fb);
+    if (ib < b) return ib;
+    const res = decrementInteger(ib);
+    if (res == null) throw new Error('cannot decrement any more');
+    return res;
+  }
+  if (b == null) {
+    const ia = integerPart(a);
+    const fa = a.slice(ia.length);
+    const i = incrementInteger(ia);
+    return i == null ? ia + midpoint(fa, null) : i;
+  }
+  const ia = integerPart(a);
+  const fa = a.slice(ia.length);
+  const ib = integerPart(b);
+  const fb = b.slice(ib.length);
+  if (ia === ib) return ia + midpoint(fa, fb);
+  const i = incrementInteger(ia);
+  if (i == null) throw new Error('cannot increment any more');
+  if (i < b) return i;
+  return ia + midpoint(fa, null);
+}
+
+/** `n` ascending keys strictly between `a` and `b`, evenly spread. */
+export function keysBetween(a: string | null, b: string | null, n: number): string[] {
+  if (n <= 0) return [];
+  if (n === 1) return [keyBetween(a, b)];
+  if (b == null) {
+    let c = keyBetween(a, b);
+    const out = [c];
+    for (let i = 0; i < n - 1; i++) {
+      c = keyBetween(c, b);
+      out.push(c);
+    }
+    return out;
+  }
+  if (a == null) {
+    let c = keyBetween(a, b);
+    const out = [c];
+    for (let i = 0; i < n - 1; i++) {
+      c = keyBetween(a, c);
+      out.push(c);
+    }
+    return out.reverse();
+  }
+  const mid = Math.floor(n / 2);
+  const c = keyBetween(a, b);
+  return [...keysBetween(a, c, mid), c, ...keysBetween(c, b, n - mid - 1)];
+}
+
+/** Total paint order: index (code-unit order), ties broken by id. */
+export function compareOrder(
+  a: { index: string; id: string },
+  b: { index: string; id: string }
+): number {
+  if (a.index !== b.index) return a.index < b.index ? -1 : 1;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+/**
+ * Keys for `ids` (desired order) that reuse `prev` keys where they are already
+ * in order (longest increasing run), minting new keys only for moved items.
+ */
+export function orderKeys(
+  ids: readonly string[],
+  prev: ReadonlyMap<string, string>
+): Map<string, string> {
+  const out = new Map<string, string>();
+  // Longest increasing subsequence over the items that have a previous key.
+  const cand = ids
+    .map((id, i) => ({ id, i, k: prev.get(id) }))
+    .filter((c) => c.k !== undefined) as Array<{ id: string; i: number; k: string }>;
+  const tails: number[] = [];
+  const back: number[] = new Array(cand.length).fill(-1);
+  for (let j = 0; j < cand.length; j++) {
+    const k = (cand[j] as { k: string }).k;
+    let lo = 0;
+    let hi = tails.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if ((cand[tails[mid] as number] as { k: string }).k < k) lo = mid + 1;
+      else hi = mid;
+    }
+    if (lo > 0) back[j] = tails[lo - 1] as number;
+    tails[lo] = j;
+  }
+  const keep = new Set<string>();
+  for (
+    let j = tails.length ? (tails[tails.length - 1] as number) : -1;
+    j >= 0;
+    j = back[j] as number
+  ) {
+    keep.add((cand[j] as { id: string }).id);
+  }
+  for (const id of keep) out.set(id, prev.get(id) as string);
+  // Fill the gaps between kept keys.
+  let i = 0;
+  while (i < ids.length) {
+    if (keep.has(ids[i] as string)) {
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < ids.length && !keep.has(ids[j] as string)) j++;
+    const lo = i > 0 ? (out.get(ids[i - 1] as string) ?? null) : null;
+    const hi = j < ids.length ? (out.get(ids[j] as string) ?? null) : null;
+    let keys: string[];
+    try {
+      keys = keysBetween(lo, hi, j - i);
+    } catch {
+      // Degenerate neighbours — renumber the whole sibling list.
+      const all = keysBetween(null, null, ids.length);
+      return new Map(ids.map((id, n) => [id, all[n] as string]));
+    }
+    for (let n = i; n < j; n++) out.set(ids[n] as string, keys[n - i] as string);
+    i = j;
+  }
+  return out;
+}

package/apps/studio/annotations/legacy/mini-dom.ts

@@ -0,0 +1,207 @@
+/**
+ * @file       annotations/legacy/mini-dom.ts — DOM-free parse of a legacy annotation SVG
+ * @scope      apps/studio/annotations/legacy/mini-dom.ts
+ * @purpose    The v1 parser (`strokesFromDocument` in annotations-model.ts)
+ *             reads through a tiny slice of the DOM API. The hub runs on Node
+ *             (no DOMParser) yet must upconvert legacy SVG history blobs, and
+ *             the migration must give the SAME result on every host — so every
+ *             v2 consumer parses legacy SVG through this one tree, never a
+ *             browser DOMParser.
+ *
+ *             Supports exactly what the fixed annotation vocabulary needs:
+ *             elements, quoted attributes, text, the five XML entities plus
+ *             numeric references, comments / processing instructions (skipped),
+ *             and the selectors `[data-tool]`, `[attr]` and bare tag names.
+ *             Malformed input yields a document containing `<parsererror>`, which
+ *             the v1 parser already treats as "no strokes".
+ *
+ *             `outerHTML` only matters for elements WITHOUT a `data-id` (the
+ *             v1 `stableAnnotationId` fallback). Its bytes may differ from a
+ *             browser's serializer; ids of such hand-authored elements are
+ *             therefore stable across v2 hosts, not necessarily equal to what a
+ *             v1 browser tab computed. Canonical v1 output always carries data-id.
+ */
+
+import type { SvgDocLike, SvgElLike } from '../../annotations-model.ts';
+
+const MAX_DEPTH = 64;
+const MAX_NODES = 200_000;
+
+function decodeEntities(s: string): string {
+  return s.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|amp|lt|gt|quot|apos);/g, (m, ent: string) => {
+    if (ent === 'amp') return '&';
+    if (ent === 'lt') return '<';
+    if (ent === 'gt') return '>';
+    if (ent === 'quot') return '"';
+    if (ent === 'apos') return "'";
+    const cp = ent.startsWith('#x')
+      ? Number.parseInt(ent.slice(2), 16)
+      : Number.parseInt(ent.slice(1), 10);
+    return Number.isFinite(cp) && cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+  });
+}
+
+function escText(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function escAttr(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+
+type Node = MiniElement | string;
+
+export class MiniElement implements SvgElLike {
+  readonly tagName: string;
+  readonly attrs: Array<[string, string]>;
+  readonly children: Node[] = [];
+
+  constructor(tagName: string, attrs: Array<[string, string]>) {
+    this.tagName = tagName;
+    this.attrs = attrs;
+  }
+
+  getAttribute(name: string): string | null {
+    for (const [k, v] of this.attrs) if (k === name) return v;
+    return null;
+  }
+
+  private matches(selector: string): boolean {
+    const attr = /^\[([\w:-]+)\]$/.exec(selector);
+    if (attr) return this.getAttribute(attr[1] as string) !== null;
+    const local = this.tagName.split(':').pop()?.toLowerCase();
+    return local === selector.toLowerCase();
+  }
+
+  private *walk(): Generator<MiniElement> {
+    for (const c of this.children) {
+      if (typeof c === 'string') continue;
+      yield c;
+      yield* c.walk();
+    }
+  }
+
+  querySelector(selector: string): MiniElement | null {
+    for (const el of this.walk()) if (el.matches(selector)) return el;
+    return null;
+  }
+
+  querySelectorAll(selector: string): MiniElement[] {
+    const out: MiniElement[] = [];
+    for (const el of this.walk()) if (el.matches(selector)) out.push(el);
+    return out;
+  }
+
+  get textContent(): string {
+    let out = '';
+    for (const c of this.children) out += typeof c === 'string' ? c : c.textContent;
+    return out;
+  }
+
+  get outerHTML(): string {
+    const attrs = this.attrs.map(([k, v]) => ` ${k}="${escAttr(v)}"`).join('');
+    if (!this.children.length) return `<${this.tagName}${attrs}/>`;
+    const inner = this.children
+      .map((c) => (typeof c === 'string' ? escText(c) : c.outerHTML))
+      .join('');
+    return `<${this.tagName}${attrs}>${inner}</${this.tagName}>`;
+  }
+}
+
+function errorDoc(): MiniElement {
+  const root = new MiniElement('#document', []);
+  root.children.push(new MiniElement('parsererror', []));
+  return root;
+}
+
+/**
+ * Parse SVG text into a document-like tree. Never throws.
+ *
+ * A single forward scan with `indexOf` — never a regex that can re-scan the
+ * input: an unterminated `<!--`, `<?`, CDATA or tag is a parse error found in
+ * one pass (the defender review measured the earlier all-in-one regex at
+ * quadratic time on `<!--` repeated — minutes of a blocked event loop on a
+ * 4 MB body, reachable from the canvas origin and from peers).
+ */
+export function parseMiniDom(text: string): SvgDocLike & MiniElement {
+  const root = new MiniElement('#document', []);
+  const stack: MiniElement[] = [root];
+  const top = () => stack[stack.length - 1] as MiniElement;
+  const closeRe = /^<\/\s*([\w:-]+)\s*>$/;
+  const openRe = /^<([\w:-]+)((?:\s+[\w:-]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*(\/?)>$/;
+  const attrRe = /([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+  const len = text.length;
+  let i = 0;
+  let nodes = 0;
+  while (i < len) {
+    const lt = text.indexOf('<', i);
+    const chunk = text.slice(i, lt < 0 ? len : lt);
+    if (chunk) top().children.push(decodeEntities(chunk));
+    if (lt < 0) break;
+    if (++nodes > MAX_NODES) return errorDoc();
+    const skipTo = (terminator: string, from: number): number => {
+      const end = text.indexOf(terminator, from);
+      return end < 0 ? -1 : end + terminator.length;
+    };
+    if (text.startsWith('<!--', lt)) {
+      i = skipTo('-->', lt + 4);
+      if (i < 0) return errorDoc();
+      continue;
+    }
+    if (text.startsWith('<?', lt)) {
+      i = skipTo('?>', lt + 2);
+      if (i < 0) return errorDoc();
+      continue;
+    }
+    if (text.startsWith('<![CDATA[', lt)) {
+      const end = text.indexOf(']]>', lt + 9);
+      if (end < 0) return errorDoc();
+      top().children.push(text.slice(lt + 9, end));
+      i = end + 3;
+      continue;
+    }
+    if (text.startsWith('<!', lt)) {
+      i = skipTo('>', lt + 2);
+      if (i < 0) return errorDoc();
+      continue;
+    }
+    // A tag: scan to its closing '>' honouring quoted attribute values.
+    let j = lt + 1;
+    let quote = '';
+    while (j < len) {
+      const ch = text[j] as string;
+      if (quote) {
+        if (ch === quote) quote = '';
+      } else if (ch === '"' || ch === "'") quote = ch;
+      else if (ch === '>') break;
+      else if (ch === '<') return errorDoc();
+      j++;
+    }
+    if (j >= len) return errorDoc();
+    const tag = text.slice(lt, j + 1);
+    i = j + 1;
+    const close = closeRe.exec(tag);
+    if (close) {
+      const open = stack.pop();
+      if (!open || open === root || open.tagName !== close[1]) return errorDoc();
+      continue;
+    }
+    const m = openRe.exec(tag);
+    if (!m) return errorDoc();
+    const attrs: Array<[string, string]> = [];
+    let a: RegExpExecArray | null;
+    attrRe.lastIndex = 0;
+    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
+    while ((a = attrRe.exec(m[2] ?? '')) !== null) {
+      attrs.push([a[1] as string, decodeEntities(a[2] ?? a[3] ?? '')]);
+    }
+    const el = new MiniElement(m[1] as string, attrs);
+    top().children.push(el);
+    if (!m[3]) {
+      if (stack.length > MAX_DEPTH) return errorDoc();
+      stack.push(el);
+    }
+  }
+  if (stack.length !== 1) return errorDoc();
+  return root;
+}

package/apps/studio/annotations/migrate-boot.ts

@@ -0,0 +1,172 @@
+/**
+ * @file       annotations/migrate-boot.ts — one-shot v1 → v2 migration of board files
+ * @scope      apps/studio/annotations/migrate-boot.ts
+ * @purpose    DDR-242 §6. For every `<slug>.annotations.svg` at the design root:
+ *               • no `<slug>.annotations.json` yet → convert (the pure
+ *                 `migrateSvg`), write the board atomically, snapshot the
+ *                 original to `_history/<slug>/pre-annotations-v2/`, move the SVG
+ *                 to `_trash/annotations-v1/`;
+ *               • a board already exists → the SVG is STALE (an old branch
+ *                 checkout, a v1 peer) and is quarantined to
+ *                 `_trash/annotations-v1/stale-…`, never merged over the board.
+ *             Idempotent (the steady state is a no-op), never throws, never
+ *             deletes: every original survives under `_history/` or `_trash/`.
+ *             Mirrors sync/migrate-flat-fallback.ts. A lock under `_state/` keeps
+ *             two processes booting at once from racing the same files.
+ */
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+
+import { MAX_LEGACY_SVG_BYTES } from './constants.ts';
+import { migrateSvg } from './migrate-v1.ts';
+import { serializeBoard } from './schema.ts';
+
+export interface AnnotationsMigration {
+  slug: string;
+  action: 'migrated' | 'stale-quarantined' | 'failed';
+  elements?: number;
+  /** Elements that could not be carried over (from the migration report). */
+  dropped?: number;
+  detail?: string;
+}
+
+const LOCK = path.join('_state', 'annotations-v2-migrate.lock');
+const LOCK_STALE_MS = 60_000;
+
+function takeLock(designRoot: string, realRoot: string): (() => void) | null {
+  const abs = path.join(designRoot, LOCK);
+  try {
+    containedDir(realRoot, path.dirname(abs));
+    if (existsSync(abs) && Date.now() - statSync(abs).mtimeMs > LOCK_STALE_MS)
+      rmSync(abs, { force: true });
+    writeFileSync(abs, String(process.pid), { flag: 'wx' });
+    return () => rmSync(abs, { force: true });
+  } catch {
+    return null; // another process is migrating right now — it will finish the job
+  }
+}
+
+function stamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+/** `dir/name`, or a timestamped sibling when that is taken — a re-migration
+ *  (the SVG came back) never overwrites the first original (code review M7). */
+function freshPath(dir: string, name: string): string {
+  const plain = path.join(dir, name);
+  return existsSync(plain) ? path.join(dir, `${stamp()}-${name}`) : plain;
+}
+
+/**
+ * Create `dir` and prove it resolves inside the design root. `_history`,
+ * `_trash` and `_state` are ordinary directories a synced or checked-out
+ * project controls — a symlink among them must not turn a boot-time write
+ * into a write anywhere on disk (security review, defender #3).
+ */
+function containedDir(realRoot: string, dir: string): string {
+  const inside = (p: string) => {
+    const real = realpathSync(p);
+    if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+      throw new Error(`${path.relative(realRoot, dir)} resolves outside the design root`);
+    }
+  };
+  // Check the deepest EXISTING ancestor before creating anything: a recursive
+  // mkdir would already have followed a symlinked `_trash` out of the root.
+  let probe = dir;
+  while (!existsSync(probe) && path.dirname(probe) !== probe) probe = path.dirname(probe);
+  inside(probe);
+  mkdirSync(dir, { recursive: true });
+  inside(dir);
+  return dir;
+}
+
+export function migrateAnnotationsV2(opts: {
+  designRoot: string;
+  log?: (line: string) => void;
+}): AnnotationsMigration[] {
+  const { designRoot } = opts;
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const out: AnnotationsMigration[] = [];
+  let names: string[];
+  try {
+    names = readdirSync(designRoot).filter((n) => n.toLowerCase().endsWith('.annotations.svg'));
+  } catch {
+    return out;
+  }
+  if (!names.length) return out;
+  let realRoot: string;
+  try {
+    realRoot = realpathSync(designRoot);
+  } catch {
+    return out;
+  }
+  const release = takeLock(designRoot, realRoot);
+  if (!release) return out;
+  try {
+    for (const name of names) {
+      const slug = name.slice(0, -'.annotations.svg'.length);
+      const svgAbs = path.join(designRoot, name);
+      const jsonAbs = path.join(designRoot, `${slug}.annotations.json`);
+      try {
+        // Only a regular file is migrated — never a symlink's target — and its
+        // size is checked before a byte is read (untrusted content, DDR-054).
+        const st = lstatSync(svgAbs, { throwIfNoEntry: false });
+        if (!st) continue;
+        if (!st.isFile()) throw new Error('not a regular file');
+        if (st.size > MAX_LEGACY_SVG_BYTES) {
+          throw new Error(`larger than ${MAX_LEGACY_SVG_BYTES} bytes`);
+        }
+        const trashDir = containedDir(realRoot, path.join(designRoot, '_trash', 'annotations-v1'));
+        if (existsSync(jsonAbs)) {
+          const to = path.join(trashDir, `stale-${stamp()}-${name}`);
+          renameSync(svgAbs, to);
+          out.push({ slug, action: 'stale-quarantined', detail: path.relative(designRoot, to) });
+          log(
+            `[annotations] ${name} reappeared next to ${slug}.annotations.json — quarantined to ${path.relative(designRoot, to)} (the board was not changed)`
+          );
+          continue;
+        }
+        const text = readFileSync(svgAbs, 'utf8');
+        const { elements, report } = migrateSvg(text);
+        // Snapshot first: if anything below fails, the original is still in place.
+        const snapDir = containedDir(
+          realRoot,
+          path.join(designRoot, '_history', slug, 'pre-annotations-v2')
+        );
+        writeFileSync(freshPath(snapDir, name), text, { flag: 'wx' });
+        const stateDir = containedDir(realRoot, path.join(designRoot, '_state'));
+        const tmp = path.join(stateDir, `annotations-v2-${slug}-${process.pid}.tmp`);
+        writeFileSync(tmp, serializeBoard(elements));
+        renameSync(tmp, jsonAbs);
+        renameSync(svgAbs, freshPath(trashDir, name));
+        out.push({ slug, action: 'migrated', elements: elements.length, dropped: report.length });
+        log(
+          `[annotations] migrated ${name} → ${slug}.annotations.json (${elements.length} elements${
+            report.length
+              ? `, ${report.length} not carried over — see _history/${slug}/pre-annotations-v2/`
+              : ''
+          })`
+        );
+        for (const r of report) log(`[annotations]   ${r.id ?? '(board)'}: ${r.reason}`);
+      } catch (err) {
+        out.push({ slug, action: 'failed', detail: (err as Error).message });
+        log(`[annotations] could not migrate ${name}: ${(err as Error).message} — left in place`);
+      }
+    }
+  } finally {
+    release();
+  }
+  return out;
+}

package/apps/studio/annotations/migrate-cli.ts

@@ -0,0 +1,37 @@
+/**
+ * @file       annotations/migrate-cli.ts — run the v1 → v2 board migration by hand
+ * @scope      apps/studio/annotations/migrate-cli.ts
+ * @purpose    `bun apps/studio/annotations/migrate-cli.ts <designRoot> [--in-place]`
+ *
+ *             Default: the boot migration (`migrateAnnotationsV2`) — originals
+ *             kept under `_history/` + `_trash/`. `--in-place` converts each
+ *             `*.annotations.svg` to its `.json` sibling and removes the SVG,
+ *             with NO runtime dirs — for committed fixtures, where git holds
+ *             the original.
+ */
+
+import { readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { migrateAnnotationsV2 } from './migrate-boot.ts';
+import { migrateSvg } from './migrate-v1.ts';
+import { serializeBoard } from './schema.ts';
+
+const [root, flag] = process.argv.slice(2);
+if (!root) {
+  console.error('usage: migrate-cli.ts <designRoot> [--in-place]');
+  process.exit(2);
+}
+if (flag === '--in-place') {
+  for (const name of readdirSync(root).filter((n) => n.endsWith('.annotations.svg'))) {
+    const abs = path.join(root, name);
+    const { elements, report } = migrateSvg(readFileSync(abs, 'utf8'));
+    writeFileSync(abs.replace(/\.svg$/, '.json'), serializeBoard(elements));
+    rmSync(abs);
+    console.log(
+      `${name} → ${elements.length} elements${report.length ? ` (${report.length} not carried over)` : ''}`
+    );
+  }
+} else {
+  const r = migrateAnnotationsV2({ designRoot: root });
+  console.log(`${r.length} board file(s) processed`);
+}