@1agh/maude 1.2.0 → 1.3.0

package/apps/studio/sync/repeated-module.ts

@@ -0,0 +1,73 @@
+// A canvas body that is one whole module written again right after itself.
+//
+// How it happens: two replicas each seed the SAME file into a shared document
+// independently (a desktop adopting its file while the hub's own copy was not
+// visible yet), and the CRDT keeps both inserts — the text concatenates. Every
+// later start that repeats the race doubles it again (2×, 4×, …), and a write
+// cut short leaves a whole copy plus a prefix of itself. Reported live on the
+// Alligators project, 2026-09-15: 38 canvases at exactly 4×, one at 1× + 879
+// characters.
+//
+// A module has ONE default export, so a body carrying the same module twice is
+// never something a person wrote. The repair keeps exactly one copy; anything
+// that is not a clean repeat (a real edit in either copy) is left alone for the
+// conflict machinery.
+
+const DEFAULT_EXPORT = /\bexport\s+default\b/g;
+
+export interface RepeatedModule {
+  /** The one copy to keep. */
+  unit: string;
+  /** Whole copies found (a trailing partial copy is counted as +0.5 → rounded up). */
+  times: number;
+  /** True when the tail was a cut-short copy (a prefix of the module). */
+  partialTail: boolean;
+}
+
+/**
+ * The single module a repeated canvas body is made of, or null when the body
+ * is not a clean repeat of one module.
+ */
+export function collapseRepeatedModule(body: string): RepeatedModule | null {
+  if (typeof body !== 'string' || body.length < 32) return null;
+  // Cheap gate: one module, one default export.
+  const exports = body.match(DEFAULT_EXPORT)?.length ?? 0;
+  if (exports < 2) return null;
+  // The second copy starts where the file's own opening appears again.
+  const probe = body.slice(0, Math.min(80, Math.floor(body.length / 2)));
+  const second = body.indexOf(probe, 1);
+  if (second <= 0) return null;
+  const unit = body.slice(0, second);
+  if ((unit.match(DEFAULT_EXPORT)?.length ?? 0) !== 1) return null;
+  let rest = body.slice(second);
+  let times = 1;
+  while (rest.startsWith(unit)) {
+    rest = rest.slice(unit.length);
+    times++;
+  }
+  if (rest === '') return times >= 2 ? { unit, times, partialTail: false } : null;
+  // A copy cut short: what is left must be the start of the module, and long
+  // enough that this is not a coincidence.
+  if (rest.length >= probe.length && unit.startsWith(rest)) {
+    return { unit, times: times + 1, partialTail: true };
+  }
+  return null;
+}
+
+/**
+ * A stylesheet written k≥2 times in a row (the same race on a canvas's CSS
+ * lane). Exact repeats only — a real stylesheet is never itself twice over.
+ */
+export function collapseRepeatedText(
+  text: string,
+  minUnit = 32
+): { unit: string; times: number } | null {
+  if (typeof text !== 'string' || text.length < minUnit * 2) return null;
+  for (let k = 8; k >= 2; k--) {
+    if (text.length % k) continue;
+    const unit = text.slice(0, text.length / k);
+    if (unit.length < minUnit || !unit.trim()) continue;
+    if (unit.repeat(k) === text) return { unit, times: k };
+  }
+  return null;
+}

package/apps/studio/sync/revision-barrier.ts

@@ -0,0 +1,129 @@
+// Revision visibility — plan T14 (DDR-241).
+//
+// One accepted action can change several canvases (a folder move, an agent's
+// multi-file edit, a restore). The hub stamps every document it writes for a
+// revision with `acceptedRevision` and the number of documents in that
+// revision (`acceptedCohort`). A receiving studio must not leave its checkout —
+// which is what the renderer and the file tree read — holding half of such a
+// revision: canvas A at revision 12 importing a canvas B still at 11 is a
+// state the project never had.
+//
+// So each document's projection ARRIVES here when it is ready to write the
+// revision, and the barrier releases the whole cohort together, in one tick,
+// once every document has arrived. A document this peer does not hold yet (one
+// created in the same action arrives by pull) or will never hold (outside its
+// groups) must not wedge the others: after `timeoutMs` the barrier releases
+// what it has. A document that is already on disk at the revision (a fresh
+// projection's first write) reports `present` and holds nothing.
+
+export interface RevisionBarrier {
+  /**
+   * A projection is ready to write `revision`. Returns true when the write is
+   * HELD — `release` runs later (possibly synchronously, before this returns,
+   * when this arrival completes the cohort).
+   */
+  arrive(revision: number, cohort: number, key: string, release: () => void): boolean;
+  /** A document already on disk at `revision` — counts, holds nothing. */
+  present(revision: number, cohort: number, key: string): void;
+  /** Revisions still waiting (tests/diagnostics). */
+  waiting(): number[];
+  stop(): void;
+}
+
+interface Cohort {
+  expected: number;
+  arrived: Set<string>;
+  held: Map<string, () => void>;
+  timer: ReturnType<typeof setTimeout> | null;
+}
+
+export function createRevisionBarrier(
+  opts: { timeoutMs?: number; log?: Pick<Console, 'warn'> } = {}
+) {
+  const timeoutMs = opts.timeoutMs ?? 1500;
+  const log = opts.log ?? console;
+  const cohorts = new Map<number, Cohort>();
+  /** Revisions already released — a late arrival writes straight through. */
+  let releasedUpTo = 0;
+  const released = new Set<number>();
+  /**
+   * Documents that reported `present` before anyone waited on their revision
+   * (a pulled document can land before its sibling's update is flushed). Kept
+   * briefly so the cohort, when it opens, already counts them.
+   */
+  const early = new Map<number, Set<string>>();
+
+  function release(revision: number, reason: 'complete' | 'timeout'): void {
+    const c = cohorts.get(revision);
+    if (!c) return;
+    cohorts.delete(revision);
+    if (c.timer) clearTimeout(c.timer);
+    released.add(revision);
+    if (released.size > 512) {
+      // Bounded memory: forget the oldest half; they are long settled.
+      const sorted = [...released].sort((a, b) => a - b);
+      for (const r of sorted.slice(0, 256)) released.delete(r);
+      releasedUpTo = Math.max(releasedUpTo, sorted[255] ?? 0);
+    }
+    if (reason === 'timeout') {
+      log.warn(
+        `[sync/revision] revision ${revision}: ${c.arrived.size} of ${c.expected} documents here — showing them without the rest.`
+      );
+    }
+    // One tick: every held write runs back to back.
+    for (const fn of c.held.values()) {
+      try {
+        fn();
+      } catch (err) {
+        log.warn(`[sync/revision] a held write failed: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  function cohortFor(revision: number, expected: number): Cohort | null {
+    if (released.has(revision) || revision <= releasedUpTo) return null;
+    let c = cohorts.get(revision);
+    if (!c) {
+      c = { expected, arrived: new Set(early.get(revision) ?? []), held: new Map(), timer: null };
+      early.delete(revision);
+      c.timer = setTimeout(() => release(revision, 'timeout'), timeoutMs);
+      cohorts.set(revision, c);
+    }
+    return c;
+  }
+
+  const barrier: RevisionBarrier = {
+    arrive(revision, cohort, key, fn) {
+      if (!(cohort > 1) || !Number.isInteger(revision)) return false;
+      const c = cohortFor(revision, cohort);
+      if (!c) return false;
+      c.arrived.add(key);
+      c.held.set(key, fn);
+      if (c.arrived.size >= c.expected) release(revision, 'complete');
+      return true;
+    },
+    present(revision, cohort, key) {
+      if (!(cohort > 1) || !Number.isInteger(revision)) return;
+      // Counts toward a revision somebody is waiting on; never opens one — a
+      // document already on disk has nothing to wait for.
+      const c = cohorts.get(revision);
+      if (!c) {
+        if (released.has(revision) || revision <= releasedUpTo) return;
+        const set = early.get(revision) ?? new Set<string>();
+        set.add(key);
+        early.set(revision, set);
+        if (early.size > 64) early.delete(Math.min(...early.keys()));
+        return;
+      }
+      c.arrived.add(key);
+      if (c.arrived.size >= c.expected) release(revision, 'complete');
+    },
+    waiting: () => [...cohorts.keys()],
+    stop() {
+      for (const c of cohorts.values()) if (c.timer) clearTimeout(c.timer);
+      cohorts.clear();
+      early.clear();
+    },
+  };
+  return barrier;
+}

package/apps/studio/sync/seed-repair.ts

@@ -0,0 +1,46 @@
+// Both sync handlers must repair the live seed race before projecting (#121).
+import type * as Y from 'yjs';
+import {
+  applyCssToDoc,
+  applyHtmlToDoc,
+  cssFromDoc,
+  htmlFromDoc,
+  markSeeded,
+  seededByFromDoc,
+  stampBodyEdit,
+} from './codec.ts';
+import { isExactRepeat } from './cold-start.ts';
+
+export const SEED_REPAIR_WINDOW_MS = 10_000;
+type Seed = { body: string; css: string | null; until: number };
+const seeds = new WeakMap<Y.Doc, Seed>();
+
+export function rememberSeed(doc: Y.Doc, body: string, css: string | null, origin: unknown): void {
+  seeds.set(doc, { body, css, until: Date.now() + SEED_REPAIR_WINDOW_MS });
+  markSeeded(doc, origin);
+}
+
+/** Exact repeats only; divergent seeds are preserved for conflict recovery. */
+export function repairSeedDuplication(doc: Y.Doc, origin: unknown): ('body' | 'css')[] {
+  const seed = seeds.get(doc);
+  if (!seed) return [];
+  if (Date.now() > seed.until) {
+    seeds.delete(doc);
+    return [];
+  }
+  if (seededByFromDoc(doc) !== doc.clientID) return [];
+  const repaired: ('body' | 'css')[] = [];
+  doc.transact(() => {
+    if (isExactRepeat(htmlFromDoc(doc), seed.body)) {
+      applyHtmlToDoc(doc, seed.body, origin);
+      stampBodyEdit(doc, origin);
+      repaired.push('body');
+    }
+    const css = cssFromDoc(doc);
+    if (css !== null && seed.css !== null && isExactRepeat(css, seed.css)) {
+      applyCssToDoc(doc, seed.css, origin);
+      repaired.push('css');
+    }
+  }, origin);
+  return repaired;
+}

package/apps/studio/sync/source-merge.ts

@@ -0,0 +1,100 @@
+// Three-way merge of a canvas body — audit 2026-09-13 P0 #1 (plan T2).
+//
+// A local save authored on an older base used to be imported by diffing the
+// file against the CURRENT doc, which turned every stale byte into an edit: a
+// peer's newer title was "reverted" by a save that only changed a colour. The
+// base is the body disk and doc last agreed on; the merge applies each side's
+// edits relative to it and refuses the moment two edits touch.
+//
+// Character-level on purpose: canvases put many attributes on one line, and a
+// line merge would call the audit's title/colour race a conflict. The price is
+// that "independent" means "non-touching spans", not "semantically unrelated"
+// — which is why the caller validates the merged source before importing it,
+// and why anything ambiguous is preserved for a person rather than guessed at.
+
+import { diffChars } from 'diff';
+
+export type MergeResult =
+  | { ok: true; merged: string }
+  /** `overlap` — the edits touch; `budget` — too large to diff safely. */
+  | { ok: false; reason: 'overlap' | 'budget' };
+
+/** One replacement of `base[start, end)` by `text`. `start === end` inserts. */
+interface Edit {
+  start: number;
+  end: number;
+  text: string;
+}
+
+/** Same bounds the text lane uses for its import diff (codec applyTextLane). */
+const DIFF_BUDGET = { maxEditLength: 4096, timeout: 50 };
+
+function editsOf(base: string, next: string): Edit[] | null {
+  let prefix = 0;
+  const maxPrefix = Math.min(base.length, next.length);
+  while (prefix < maxPrefix && base.charCodeAt(prefix) === next.charCodeAt(prefix)) prefix++;
+  let suffix = 0;
+  const maxSuffix = Math.min(base.length - prefix, next.length - prefix);
+  while (
+    suffix < maxSuffix &&
+    base.charCodeAt(base.length - 1 - suffix) === next.charCodeAt(next.length - 1 - suffix)
+  ) {
+    suffix++;
+  }
+  // Never split a surrogate pair across an edit boundary.
+  if (prefix > 0 && /[\uD800-\uDBFF]/.test(base[prefix - 1] ?? '')) prefix--;
+  if (suffix > 0 && /[\uDC00-\uDFFF]/.test(base[base.length - suffix] ?? '')) suffix--;
+  const from = base.slice(prefix, base.length - suffix);
+  const to = next.slice(prefix, next.length - suffix);
+  if (!from && !to) return [];
+  if (!from || !to) return [{ start: prefix, end: prefix + from.length, text: to }];
+  const changes = diffChars(from, to, DIFF_BUDGET);
+  if (changes === undefined) return null;
+  const edits: Edit[] = [];
+  let offset = prefix;
+  let open: Edit | null = null;
+  for (const change of changes) {
+    if (change.removed || change.added) {
+      open ??= { start: offset, end: offset, text: '' };
+      if (change.removed) {
+        open.end += change.value.length;
+        offset += change.value.length;
+      } else open.text += change.value;
+    } else {
+      if (open) edits.push(open);
+      open = null;
+      offset += change.value.length;
+    }
+  }
+  if (open) edits.push(open);
+  return edits;
+}
+
+const same = (a: Edit, b: Edit) => a.start === b.start && a.end === b.end && a.text === b.text;
+
+/**
+ * Merge `ours` and `theirs`, both derived from `base`. Edits that touch —
+ * overlapping, adjacent, or two insertions at one point — are an `overlap`
+ * unless they are the identical edit, which is applied once.
+ */
+export function mergeSource(base: string, ours: string, theirs: string): MergeResult {
+  if (ours === theirs || theirs === base) return { ok: true, merged: ours };
+  if (ours === base) return { ok: true, merged: theirs };
+  const a = editsOf(base, ours);
+  const b = editsOf(base, theirs);
+  if (!a || !b) return { ok: false, reason: 'budget' };
+  const all: Edit[] = [];
+  for (const edit of [...a, ...b].sort((x, y) => x.start - y.start || x.end - y.end)) {
+    const prev = all[all.length - 1];
+    if (prev && same(prev, edit)) continue;
+    if (prev && edit.start <= prev.end) return { ok: false, reason: 'overlap' };
+    all.push(edit);
+  }
+  let merged = '';
+  let cursor = 0;
+  for (const edit of all) {
+    merged += base.slice(cursor, edit.start) + edit.text;
+    cursor = edit.end;
+  }
+  return { ok: true, merged: merged + base.slice(cursor) };
+}

package/apps/studio/sync/source-ops.ts

@@ -0,0 +1,289 @@
+// UI source operations that survive a race — plan T23/T24 (DDR-241).
+//
+// A change the person makes in the inspector or on the canvas (a text, a
+// style property, an attribute) is saved as a whole-canvas proposal with the
+// base it was made from; the hub merges it three-way. Two people changing the
+// SAME property touch the same characters, and a character merge can only
+// call that a conflict — a dialog for "we both picked a colour", which is not
+// what a design tool does. Figma-class tools resolve it by acceptance order:
+// the later assignment wins, and nothing else of either person's is lost.
+//
+// So such an edit also records WHAT it was — the operation, the element's
+// position-independent print, and the value — and when its proposal loses a
+// race the studio re-applies exactly that operation onto the version that won
+// and proposes again. What the other person changed elsewhere survives (it is
+// in the version the edit is re-applied to); the same property takes the
+// later value; the history keeps both actions in the order they were accepted.
+//
+// It re-applies only when it can find THE element (canvas-edit
+// `relocateElement`); a deleted or ambiguous target is a genuine conflict and
+// goes to the person, never to a guess.
+
+import {
+  applyDeleteElement,
+  applyDuplicateElement,
+  applyEdit,
+  applyMove,
+  applyRemove,
+  applyRemoveClip,
+  applyResizeArtboard,
+  applyRetimeSequenceByClip,
+  applySetArtboardGuides,
+  applySetArtboardHug,
+  applySetArtboardKind,
+  applySetArtboardLabel,
+  applySetArtboardStyle,
+  applyTextEdit,
+  type ElementPrint,
+  elementPrint,
+  relocateElement,
+} from '../canvas-edit.ts';
+
+/** An artboard is addressed by its authored id — stable by construction. */
+export type ArtboardFn = 'resize' | 'hug' | 'style' | 'kind' | 'label' | 'guides';
+
+export type SourceOp =
+  | {
+      kind: 'text';
+      id: string;
+      text: string;
+      occurrence?: number;
+      before?: string;
+      print: ElementPrint;
+    }
+  | {
+      kind: 'set';
+      id: string;
+      attr: string;
+      value: string;
+      occurrence?: number;
+      print: ElementPrint;
+    }
+  | { kind: 'remove'; id: string; attr: string; occurrence?: number; print: ElementPrint }
+  // T25 — structural element operations, re-found by print.
+  | { kind: 'delete'; id: string; occurrence?: number; print: ElementPrint }
+  | { kind: 'duplicate'; id: string; occurrence?: number; print: ElementPrint }
+  | {
+      kind: 'move';
+      id: string;
+      refId: string;
+      position: string;
+      idIndex?: number;
+      refIndex?: number;
+      print: ElementPrint;
+      refPrint: ElementPrint;
+    }
+  // Artboards and clips carry stable ids already (authored id; stableId +
+  // content hash) — no print needed; a changed clip fails its own hash check.
+  | { kind: 'artboard'; fn: ArtboardFn; artboardId: string; args: unknown[]; print?: undefined }
+  | {
+      kind: 'clip-retime' | 'clip-remove';
+      artboardId?: string;
+      stableId: string;
+      expectedHash?: string;
+      patch?: unknown;
+      print?: undefined;
+    };
+
+type Describable =
+  | { kind: 'text'; id: string; text: string; occurrence?: number; before?: string }
+  | { kind: 'set'; id: string; attr: string; value: string; occurrence?: number }
+  | { kind: 'remove'; id: string; attr: string; occurrence?: number }
+  | { kind: 'delete'; id: string; occurrence?: number }
+  | { kind: 'duplicate'; id: string; occurrence?: number }
+  | {
+      kind: 'move';
+      id: string;
+      refId: string;
+      position: string;
+      idIndex?: number;
+      refIndex?: number;
+    }
+  | { kind: 'artboard'; fn: ArtboardFn; artboardId: string; args: unknown[] }
+  | {
+      kind: 'clip-retime' | 'clip-remove';
+      artboardId?: string;
+      stableId: string;
+      expectedHash?: string;
+      patch?: unknown;
+    };
+
+type StableOp = Extract<SourceOp, { kind: 'artboard' | 'clip-retime' | 'clip-remove' }>;
+type ElementOp = Exclude<SourceOp, StableOp>;
+const STABLE = new Set(['artboard', 'clip-retime', 'clip-remove']);
+function isStable<T extends { kind: string }>(op: T): boolean {
+  return STABLE.has(op.kind);
+}
+
+/** The attribute a print must ignore for this op (it is the one changing). */
+function editedAttr(op: { kind: string; attr?: string }): string | null {
+  if (op.kind !== 'set' && op.kind !== 'remove') return null;
+  const a = op.attr ?? '';
+  return a.startsWith('style.') ? 'style' : a;
+}
+
+/** Describe an operation against the source it is about to be applied to. */
+export function describeSourceOp(
+  canvasAbsPath: string,
+  source: string,
+  op: Describable
+): SourceOp | null {
+  try {
+    if (isStable(op)) return op as SourceOp;
+    const el = op as Exclude<Describable, { kind: 'artboard' | 'clip-retime' | 'clip-remove' }>;
+    // A text edit's own text is what changes, so it is not part of the print.
+    const print = elementPrint(canvasAbsPath, source, el.id, editedAttr(el), el.kind !== 'text');
+    if (!print) return null;
+    if (el.kind === 'move') {
+      const refPrint = elementPrint(canvasAbsPath, source, el.refId, null);
+      return refPrint ? { ...el, print, refPrint } : null;
+    }
+    return { ...el, print } as SourceOp;
+  } catch {
+    return null;
+  }
+}
+
+export type ReplayResult =
+  | { ok: true; source: string }
+  | { ok: false; reason: 'target-missing' | 'failed' };
+
+/** Re-apply `op` onto `head` — the version that won. Pure. */
+export function replaySourceOp(canvasAbsPath: string, anyOp: SourceOp, head: string): ReplayResult {
+  if (isStable(anyOp)) return replayStable(canvasAbsPath, anyOp as StableOp, head);
+  return replayElement(canvasAbsPath, anyOp as ElementOp, head);
+}
+
+function replayStable(canvasAbsPath: string, op: StableOp, head: string): ReplayResult {
+  try {
+    if (op.kind === 'artboard')
+      return { ok: true, source: replayArtboard(canvasAbsPath, op, head) };
+    if (op.kind === 'clip-retime') {
+      return {
+        ok: true,
+        source: applyRetimeSequenceByClip(
+          canvasAbsPath,
+          head,
+          op.artboardId,
+          op.stableId,
+          op.expectedHash,
+          op.patch as Parameters<typeof applyRetimeSequenceByClip>[5]
+        ).source,
+      };
+    }
+    if (op.kind === 'clip-remove') {
+      return {
+        ok: true,
+        source: applyRemoveClip(canvasAbsPath, head, op.artboardId, op.stableId, op.expectedHash)
+          .source,
+      };
+    }
+  } catch {
+    return { ok: false, reason: 'failed' };
+  }
+  return { ok: false, reason: 'failed' };
+}
+
+function replayElement(canvasAbsPath: string, op: ElementOp, head: string): ReplayResult {
+  let id: string | null;
+  try {
+    id = relocateElement(canvasAbsPath, head, op.id, op.print, editedAttr(op));
+  } catch {
+    return { ok: false, reason: 'failed' };
+  }
+  if (!id) return { ok: false, reason: 'target-missing' };
+  try {
+    switch (op.kind) {
+      case 'text':
+        return {
+          ok: true,
+          source: applyTextEdit(canvasAbsPath, head, id, op.text, {
+            ...(op.occurrence !== undefined ? { occurrence: op.occurrence } : {}),
+          }).source,
+        };
+      case 'set':
+        return {
+          ok: true,
+          source: applyEdit(canvasAbsPath, head, id, op.attr, op.value, op.occurrence).source,
+        };
+      case 'remove':
+        return {
+          ok: true,
+          source: applyRemove(canvasAbsPath, head, id, op.attr, op.occurrence).source,
+        };
+      case 'delete':
+        return {
+          ok: true,
+          source: applyDeleteElement(canvasAbsPath, head, id, op.occurrence).source,
+        };
+      case 'duplicate':
+        return {
+          ok: true,
+          source: applyDuplicateElement(canvasAbsPath, head, id, op.occurrence).source,
+        };
+      case 'move': {
+        const refId = relocateElement(canvasAbsPath, head, op.refId, op.refPrint, null);
+        if (!refId) return { ok: false, reason: 'target-missing' };
+        return {
+          ok: true,
+          source: applyMove(
+            canvasAbsPath,
+            head,
+            id,
+            refId,
+            op.position as Parameters<typeof applyMove>[4],
+            op.idIndex,
+            op.refIndex
+          ).source,
+        };
+      }
+    }
+  } catch {
+    return { ok: false, reason: 'failed' };
+  }
+  return { ok: false, reason: 'failed' };
+}
+
+function replayArtboard(
+  abs: string,
+  op: Extract<SourceOp, { kind: 'artboard' }>,
+  head: string
+): string {
+  const a = op.args;
+  switch (op.fn) {
+    case 'resize':
+      return applyResizeArtboard(
+        abs,
+        head,
+        op.artboardId,
+        a[0] as number | undefined,
+        a[1] as number | undefined
+      ).source;
+    case 'hug':
+      return applySetArtboardHug(
+        abs,
+        head,
+        op.artboardId,
+        a[0] === true,
+        a[1] as number | undefined
+      ).source;
+    case 'style':
+      return applySetArtboardStyle(
+        abs,
+        head,
+        op.artboardId,
+        a[0] as Parameters<typeof applySetArtboardStyle>[3]
+      ).source;
+    case 'kind':
+      return applySetArtboardKind(abs, head, op.artboardId, (a[0] as string | null) ?? null).source;
+    case 'label':
+      return applySetArtboardLabel(abs, head, op.artboardId, String(a[0] ?? '')).source;
+    case 'guides':
+      return applySetArtboardGuides(
+        abs,
+        head,
+        op.artboardId,
+        (a[0] as Record<string, unknown> | null) ?? null
+      ).source;
+  }
+}