@1agh/maude 1.2.0 → 1.3.0

package/apps/studio/notifications.tsx

@@ -0,0 +1,292 @@
+/** Shared shell/canvas notifications. Sonner owns layout, gestures and announcements;
+ * our clock also pauses for app overlays, hidden queue entries and Save dialogs. */
+import {
+  type CSSProperties,
+  type ReactNode,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { Toaster, toast } from 'sonner';
+
+export type NoticeKind = 'info' | 'success' | 'error' | 'warning' | 'undo';
+export interface Notice {
+  id?: string;
+  title: string;
+  description?: string;
+  content?: ReactNode;
+  kind?: NoticeKind;
+  group?: string;
+  duration?: number;
+  /** Change only for a new lifecycle phase, never for a progress update. */
+  timerKey?: string;
+  paused?: boolean;
+  action?: { label: string; onClick: () => void };
+  onDismiss?: () => void;
+}
+type Entry = Notice & { id: string };
+let entries: Entry[] = [];
+let sequence = 0;
+const listeners = new Set<() => void>();
+const publish = () => {
+  for (const listener of listeners) listener();
+};
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+const snapshot = () => entries;
+
+export function notify(notice: Notice): string {
+  const id = notice.id ?? `notice-${++sequence}`;
+  const existing = entries.findIndex((entry) => entry.id === id);
+  if (existing < 0) entries = [...entries, { ...notice, id }];
+  else entries = entries.map((entry) => (entry.id === id ? { ...notice, id } : entry));
+  publish();
+  return id;
+}
+
+let canvasSlot = 0;
+let canvasWindowStart = -Infinity;
+let canvasWindowCount = 0;
+/** Untrusted canvas traffic gets two reusable slots, leaving room for shell notices.
+ * Limit publications as well as retention; editing can emit dozens per second. */
+export function notifyCanvasText(title: string, kind: NoticeKind = 'info'): string | null {
+  const now = Date.now();
+  if (now < canvasWindowStart || now - canvasWindowStart >= 1000) {
+    canvasWindowStart = now;
+    canvasWindowCount = 0;
+  }
+  if (canvasWindowCount >= 5) return null;
+  canvasWindowCount++;
+  const previousUndo =
+    kind === 'undo'
+      ? entries.find((entry) => entry.group === 'canvas' && entry.kind === 'undo')
+      : undefined;
+  const id = previousUndo?.id ?? `canvas-notice-${canvasSlot++ % 2}`;
+  return notify({
+    id,
+    title: title.slice(0, 4000),
+    kind,
+    group: 'canvas',
+    timerKey: `${++sequence}`,
+  });
+}
+
+/** Programmatic removal (unmount/navigation) does not acknowledge the notice. */
+export function dismissNotice(id: string): void {
+  entries = entries.filter((entry) => entry.id !== id);
+  publish();
+}
+function acknowledge(id: string) {
+  const entry = entries.find((item) => item.id === id);
+  dismissNotice(id);
+  entry?.onDismiss?.();
+}
+
+export function noticeDuration(entry: Notice): number {
+  return (
+    entry.duration ??
+    (entry.action || ['error', 'warning', 'undo'].includes(entry.kind ?? '') ? 10_000 : 5_000)
+  );
+}
+
+/** Keep full diagnostics in their owning panel, including for screen readers. */
+export function summarizeNoticeText(text: string): string {
+  const compact = text.trim().replace(/\s+/g, ' ');
+  return compact.length > 280 ? `${compact.slice(0, 279)}…` : compact;
+}
+
+function NoticeCard({ entry }: { entry: Entry }) {
+  return (
+    <div
+      className="maude-notice"
+      data-kind={entry.kind ?? 'info'}
+      data-testid={`notice-${entry.id}`}
+    >
+      <button
+        type="button"
+        className="maude-notice-close"
+        aria-label="Dismiss notification"
+        onClick={(event) => {
+          event.currentTarget.blur();
+          acknowledge(entry.id);
+        }}
+      >
+        ×
+      </button>
+      <div className="maude-notice-title">{summarizeNoticeText(entry.title)}</div>
+      {entry.description && (
+        <div className="maude-notice-summary">{summarizeNoticeText(entry.description)}</div>
+      )}
+      {entry.content}
+      {entry.action && (
+        <button
+          type="button"
+          className="maude-notice-action"
+          onClick={(event) => {
+            event.currentTarget.blur();
+            entry.action?.onClick();
+            acknowledge(entry.id);
+          }}
+        >
+          {entry.action.label}
+        </button>
+      )}
+    </div>
+  );
+}
+
+function MountedNotice({
+  entry,
+  visible,
+  paused,
+}: {
+  entry: Entry;
+  visible: boolean;
+  paused: boolean;
+}) {
+  const duration = noticeDuration(entry);
+  const presentationId = useRef<string | null>(null);
+  const remaining = useRef(duration);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: a new lifecycle phase gets a fresh duration.
+  useEffect(() => {
+    remaining.current = duration;
+  }, [duration, entry.timerKey]);
+  // Keep the clock outside Sonner's card: hiding a group must preserve its time.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: restart the clock when its lifecycle phase changes.
+  useEffect(() => {
+    if (!visible || paused || entry.paused || duration === Infinity) return;
+    const started = Date.now();
+    const timer = setTimeout(() => acknowledge(entry.id), Math.max(0, remaining.current));
+    return () => {
+      clearTimeout(timer);
+      remaining.current = Math.max(0, remaining.current - (Date.now() - started));
+    };
+  }, [visible, paused, entry.paused, duration, entry.timerKey, entry.id]);
+  // Sonner invokes onDismiss even for programmatic removal. Invalidate the
+  // presentation before hiding so opening history never acknowledges a job.
+  useEffect(() => {
+    if (visible) {
+      const token = presentationId.current ?? `${entry.id}:view-${++sequence}`;
+      presentationId.current = token;
+      toast.custom(() => <NoticeCard entry={entry} />, {
+        id: token,
+        duration: Infinity,
+        onDismiss: () => {
+          if (presentationId.current === token) acknowledge(entry.id);
+        },
+      });
+    } else if (presentationId.current) {
+      const token = presentationId.current;
+      presentationId.current = null;
+      toast.dismiss(token);
+    }
+  }, [entry, visible]);
+  useEffect(
+    () => () => {
+      const token = presentationId.current;
+      presentationId.current = null;
+      if (token) toast.dismiss(token);
+    },
+    []
+  );
+  return null;
+}
+
+const NOTICE_CSS = `
+.maude-notifications [data-sonner-toaster] { --width: min(360px, calc(100vw - 32px)); z-index: 8000; }
+.maude-notifications [data-sonner-toast] { width: var(--width); }
+.maude-notifications [data-sonner-toast][data-expanded=false][data-front=false] {
+  overflow: hidden; border-radius: var(--radius-md, 8px);
+}
+.maude-notifications[data-paused=true] { visibility: hidden; pointer-events: none; }
+.maude-notice { box-sizing: border-box; position: relative; width: 100%; padding: 16px;
+  border: 1px solid var(--border-default, #45454c); border-left: 3px solid var(--accent, #d63b1f);
+  border-radius: var(--radius-md, 8px); background: var(--bg-2, #26262b); color: var(--fg-0, #fafafa);
+  box-shadow: 0 8px 28px #0004; font: 13px/1.5 var(--font-sans, system-ui, sans-serif);
+  display: flex; flex-direction: column; gap: 8px; overflow-wrap: anywhere; }
+.maude-notice[data-kind=error], .maude-notice[data-kind=warning] { border-left-color: var(--status-error, #d65b4d); }
+.maude-notice-title { font-weight: 600; padding-right: 20px; }
+.maude-notice-summary, .maude-notice-title, .maude-notice .st-export-degraded {
+  display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 3; overflow: hidden;
+  overflow-wrap: anywhere; }
+.maude-notice-summary { color: var(--fg-1, #ddd); }
+.maude-notice-close { position: absolute; right: 8px; top: 8px; border: 0; border-radius: 4px;
+  background: transparent; color: inherit; cursor: pointer; font-size: 18px; padding: 0 6px; }
+.maude-notice-action { align-self: flex-start; border: 0; background: transparent; color: inherit;
+  font: inherit; text-decoration: underline; cursor: pointer; padding: 2px 0; }
+.maude-notice button:focus-visible { outline: 2px solid var(--accent, #d63b1f); outline-offset: 2px; }
+.maude-notice .st-toast-actions { flex-wrap: wrap; }
+@media (prefers-reduced-motion: reduce) {
+  .maude-notifications [data-sonner-toast], .maude-notifications [data-sonner-toaster] {
+    animation: none !important; transition: none !important;
+  }
+}`;
+
+const NO_GROUPS: string[] = [];
+export function NotificationHost({
+  paused = false,
+  hiddenGroups = NO_GROUPS,
+}: {
+  paused?: boolean;
+  hiddenGroups?: string[];
+}) {
+  const notices = useSyncExternalStore(subscribe, snapshot, snapshot);
+  const hostRef = useRef<HTMLDivElement>(null);
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  const [hidden, setHidden] = useState(() => typeof document !== 'undefined' && document.hidden);
+  useEffect(() => {
+    const change = () => setHidden(document.hidden);
+    document.addEventListener('visibilitychange', change);
+    return () => document.removeEventListener('visibilitychange', change);
+  }, []);
+  useEffect(() => {
+    if (!notices.length) {
+      setHovered(false);
+      setFocused(false);
+    }
+    // Removing a focused DOM node does not reliably emit blur in browsers.
+    if (focused && !hostRef.current?.contains(document.activeElement)) setFocused(false);
+  }, [notices, focused]);
+  const visible = notices.filter((entry) => !hiddenGroups.includes(entry.group ?? ''));
+  // Publish only the latest three; older entries keep their clocks while waiting.
+  // This also keeps visibility and clocks aligned when a hidden group returns.
+  const timedIds = new Set(visible.slice(-3).map((entry) => entry.id));
+  return (
+    <div
+      ref={hostRef}
+      className="maude-notifications"
+      data-paused={paused}
+      onPointerEnter={() => setHovered(true)}
+      onPointerLeave={() => setHovered(false)}
+      onFocusCapture={() => setFocused(true)}
+      onBlurCapture={(event) => {
+        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setFocused(false);
+      }}
+    >
+      <style>{NOTICE_CSS}</style>
+      <Toaster
+        position="bottom-left"
+        offset={{ left: 16, bottom: 84 }}
+        mobileOffset={{ left: 16, right: 16, bottom: 84 }}
+        visibleToasts={3}
+        expand={focused}
+        style={{ '--width': 'min(360px, calc(100vw - 32px))' } as CSSProperties}
+        containerAriaLabel="Notifications"
+      />
+      {notices.map((entry) => (
+        <MountedNotice
+          key={entry.id}
+          entry={entry}
+          visible={timedIds.has(entry.id)}
+          paused={paused || hovered || focused || hidden || !timedIds.has(entry.id)}
+        />
+      ))}
+    </div>
+  );
+}

package/apps/studio/runtime-bundle.ts

@@ -47,6 +47,8 @@ export const RUNTIME_PACKAGES = [
   'react-dom/client',
   'react/jsx-runtime',
   'react/jsx-dev-runtime',
+  // Toasts in standalone canvases resolve without node_modules in packaged installs.
+  'sonner',
   // Pixi.js v8 — per-iframe runtime bundle for the non-destructive photo editor
   // (feature-photo-editor). The canvas-lib `<PhotoLayer>` reaches the WebGL
   // compositor (`photo/pipeline.ts`) through a LAZY runtime `import('pixi.js')`,

package/apps/studio/server.ts

@@ -14,6 +14,7 @@
 // else binds to a port. The orchestrator (slash commands) reads _server.json
 // to detect a live instance and avoid duplicate boots.
 
+import path from 'node:path';
 import { createAcp } from './acp/index.ts';
 import { cancelInstall, cancelSignin } from './acp/login-state.ts';
 import { createActivity } from './activity.ts';
@@ -78,7 +79,23 @@ let collab: ReturnType<typeof createCollab> | null = null;
 let inspectHandle: ReturnType<typeof createInspectRegistry> | null = null;
 
 const api = createApi(ctx, {
-  onCommentsChanged: (file, comments) => {
+  onCommentsChanged: (file, comments, base) => {
+    // Accepted-revisions mode (DDR-241): the change is PROPOSED; the room's
+    // document changes when the project publishes it. Fire-and-forget — the
+    // proposal is durable in the outbox before this returns, and the sidebar
+    // below already shows the author their own comment.
+    const runtime = ctx.syncControl?.current?.();
+    const proposed = runtime?.proposeLane?.(
+      api.fileSlug(file),
+      'comments',
+      JSON.stringify(comments),
+      base ? { baseText: JSON.stringify(base) } : {}
+    );
+    if (proposed) {
+      void proposed.catch(() => {});
+      ctx.bus.emit('comments', { file, comments });
+      return;
+    }
     // Phase 8 Task 3 — bridge into the live Y.Array so collab peers see the
     // change without waiting for cold-open re-seeding. No-op when no room is
     // live for this canvas slug.
@@ -98,9 +115,18 @@ const api = createApi(ctx, {
   },
   // Phase 8 Task 5 — same bridge for annotations. PUT /_api/annotations writes
   // the SVG blob to disk; we mirror it into the live Y.Map for collab peers.
-  onAnnotationsChanged: (file, svg) => {
+  onAnnotationsChanged: (file, svg, writeId, base) => {
+    const runtime = ctx.syncControl?.current?.();
+    const proposed = runtime?.proposeLane?.(api.fileSlug(file), 'annotations', svg, {
+      ...(writeId ? { writeId } : {}),
+      ...(base !== undefined ? { baseText: base } : {}),
+    });
+    if (proposed) {
+      void proposed.catch(() => {});
+      return;
+    }
     if (collab) {
-      collab.registry.syncRoomFromAnnotations(api.fileSlug(file), svg);
+      collab.registry.syncRoomFromAnnotations(api.fileSlug(file), svg, writeId);
     }
   },
   // feature-file-tree-drag-drop-folders (Task 3) — moveCanvas's collab guard
@@ -120,6 +146,13 @@ const api = createApi(ctx, {
       return false;
     }
   },
+  proposeFolder: (op) => ctx.syncControl?.current?.()?.proposeFolder?.(op) ?? null,
+  onMetaChanged: (file, text, baseText) => {
+    const proposed = ctx.syncControl
+      ?.current?.()
+      ?.proposeLane?.(api.fileSlug(file), 'meta', text, baseText ? { baseText } : {});
+    if (proposed) void proposed.catch(() => {});
+  },
   flushAndDropRoom: async (slug) => {
     if (collab) await collab.registry.forceDrop(slug);
   },
@@ -136,6 +169,19 @@ inspectHandle = inspects;
 // arrives without a vouched session.
 await inspects.for('').load();
 
+// Semantic structural notifications include remote sync operations as well as
+// API actions. Keep every session's agent/inspector context on the live path.
+ctx.bus.on('canvas-list-update', (change) => {
+  if (!change?.rel) return;
+  const file = path.posix.join(ctx.paths.designRel, change.rel);
+  if (change.action === 'moved' && change.fromRel) {
+    const fromFile = path.posix.join(ctx.paths.designRel, change.fromRel);
+    for (const inspect of inspects.all()) inspect.retarget(fromFile, file);
+  } else if (change.action === 'removed') {
+    for (const inspect of inspects.all()) inspect.remove(file);
+  }
+});
+
 collab = createCollab(ctx, api);
 const aiActivity = createAiActivity(ctx);
 
@@ -152,6 +198,16 @@ ctx.bus.on('ai-activity', (payload: { file: string; entry: AiActivityEntry | nul
     payload.entry ? { name: payload.entry.author, since: payload.entry.startedAt } : null
   );
 });
+// T16 — an AI edit whose heartbeat went silent (the driver crashed) did not
+// finish: whatever it wrote stays unpublished for the person's decision. An
+// explicit /end already closed its action, so this is a no-op then.
+ctx.bus.on('ai-activity', (payload: { file: string; entry: AiActivityEntry | null }) => {
+  if (payload.entry) return;
+  void ctx.syncControl
+    ?.current?.()
+    ?.endAiAction?.(`edit:${payload.file}`, 'failed')
+    ?.catch(() => {});
+});
 const gitLifecycle = createGitLifecycle(ctx, collab.registry);
 // Phase 13 / DDR-029 — fs-watch-driven canvas activity overlay. Subscribes to
 // `fs:any` and emits `activity:change`; ws.ts forwards it to canvas iframes.

package/apps/studio/sync/accepted-cold-start.ts

@@ -0,0 +1,225 @@
+// Cold start under accepted revisions — DDR-241 §3, plan T13/T14.
+//
+// The legacy cold start (`migrate-seed.ts`) had to CHOOSE a source and write it
+// into the shared document, because the document was writable and whatever a
+// peer put there was the project. Here the document is a read-only replica of
+// the accepted state, so cold start only ever DECIDES, per lane:
+//
+//   agreed       — disk already holds the accepted value;
+//   materialize  — disk is older than the project (or absent): the projection
+//                  writes the accepted value, keeping local bytes in recovery;
+//   propose      — disk carries a change made on top of a known base: it is
+//                  proposed, and the hub merges it three-way from that base;
+//   hold         — disk differs and nothing proves what it was derived from:
+//                  both are kept, the lane stays blocked with a visible
+//                  conflict, and the next save resolves it (T2's rule — never a
+//                  silent overwrite of either side).
+//
+// A canvas the project does not know yet is proposed as `doc.create` with all
+// of its lanes, so it arrives on every peer as ONE action.
+//
+// Comments and annotations are never re-proposed from disk here: every change
+// the studio made to them went through the durable outbox (drained before any
+// cold start), so a difference on disk is an older accepted state the room had
+// not re-projected — the accepted value wins, and the local file is kept in a
+// recovery slot in case a raw edit made while the studio was down lived there.
+
+import { existsSync, readFileSync } from 'node:fs';
+import type * as Y from 'yjs';
+
+import { cssFromDoc, htmlFromDoc, laneValueFromFile, readLaneFromDoc } from './codec.ts';
+import { hashBytes } from './echo-guard.ts';
+import type { SyncJournal } from './journal.ts';
+import type { DocProjection, ProjectionPaths, ProposalLane } from './projection.ts';
+import { readRecoveryBody, saveRecoveryBody } from './source-recovery.ts';
+import { sourceError } from './source-validation.ts';
+
+export type LaneDecision = 'agreed' | 'materialize' | 'propose' | 'hold';
+
+export interface LaneVerdict {
+  lane: ProposalLane;
+  decision: LaneDecision;
+  /** For `propose`: the value the local edit was derived from. For `hold`: the accepted value adopted as the base. */
+  base?: string;
+  local?: string;
+}
+
+function readText(p: string | undefined): string | null {
+  if (!p || !existsSync(p)) return null;
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pure decision for the source lanes. `knownBase` is the last value disk and
+ * the accepted replica agreed on (recovery slot), `baseHash` the journal's
+ * hash of it when the bytes are gone.
+ */
+export function decideSourceLane(input: {
+  local: string | null;
+  accepted: string;
+  knownBase: string | null;
+  baseHash?: string | null;
+}): { decision: LaneDecision; base?: string } {
+  const { local, accepted } = input;
+  if (local === null) return { decision: 'materialize' };
+  if (local === accepted) return { decision: 'agreed' };
+  let base = input.knownBase;
+  if (base === null && input.baseHash) {
+    if (hashBytes(accepted) === input.baseHash) base = accepted;
+    else if (hashBytes(local) === input.baseHash) base = local;
+  }
+  if (base === null) {
+    // The project never had this lane: nothing of anybody's can be lost.
+    if (accepted === '') return { decision: 'propose', base: '' };
+    return { decision: 'hold', base: accepted };
+  }
+  if (base === local) return { decision: 'materialize' }; // an older accepted state
+  return { decision: 'propose', base };
+}
+
+export interface AcceptedColdStartInput {
+  slug: string;
+  doc: Y.Doc;
+  paths: ProjectionPaths;
+  /** Design-root-relative body path (`ui/home.tsx`). */
+  rel: string;
+  /** Is this canvas a live document of the project's accepted state? */
+  inProject: boolean;
+  projection: DocProjection;
+  historyDir?: string;
+  journal?: SyncJournal;
+  createDoc: (lanes: Partial<Record<ProposalLane, string>>) => Promise<{
+    status: 'accepted' | 'rejected';
+    code?: string;
+  }>;
+  log?: Pick<Console, 'log' | 'warn'>;
+}
+
+export type AcceptedColdStartResult =
+  | { kind: 'created' }
+  | { kind: 'create-refused'; code?: string }
+  | { kind: 'reconciled'; verdicts: LaneVerdict[] };
+
+export async function acceptedColdStart(
+  i: AcceptedColdStartInput
+): Promise<AcceptedColdStartResult> {
+  const log = i.log ?? console;
+  const localHtml = readText(i.paths.html);
+
+  if (!i.inProject) {
+    if (localHtml === null) return { kind: 'reconciled', verdicts: [] };
+    const lanes: Partial<Record<ProposalLane, string>> = { html: localHtml };
+    const css = readText(i.paths.css);
+    if (css) lanes.css = css;
+    const metaText = readText(i.paths.meta);
+    const meta = metaText === null ? null : laneValueFromFile('meta', metaText);
+    if (meta && meta !== '{}') lanes.meta = meta;
+    const ann = readText(i.paths.annotations);
+    if (ann) lanes.annotations = ann;
+    const commentsText = readText(i.paths.comments);
+    const comments = commentsText === null ? null : laneValueFromFile('comments', commentsText);
+    if (comments) lanes.comments = comments;
+    const r = await i.createDoc(lanes);
+    if (r.status === 'accepted') {
+      // What the project now holds IS the local file: the next save is based
+      // on it, even if it lands before the publication reaches this replica.
+      i.projection.adoptBase(localHtml);
+      log.log(`[sync/${i.slug}] added to the project (accepted).`);
+      return { kind: 'created' };
+    }
+    log.warn(
+      `[sync/${i.slug}] the project did not accept this canvas (${r.code ?? 'rejected'}) — it stays local.`
+    );
+    return { kind: 'create-refused', code: r.code };
+  }
+
+  const verdicts: LaneVerdict[] = [];
+
+  // ---- html — the canvas source
+  const acceptedHtml = htmlFromDoc(i.doc);
+  if (localHtml !== null && localHtml !== acceptedHtml && sourceError(i.paths.html, localHtml)) {
+    // An invalid local body cannot be proposed; the projection keeps its bytes
+    // in recovery and reports it when it materializes the accepted source.
+    verdicts.push({ lane: 'html', decision: 'materialize', local: localHtml });
+  } else {
+    const d = decideSourceLane({
+      local: localHtml,
+      accepted: acceptedHtml,
+      knownBase: i.historyDir ? readRecoveryBody(i.historyDir, i.paths.html, 'base') : null,
+      baseHash: i.journal?.get(i.slug)?.bodyHash ?? null,
+    });
+    verdicts.push({ lane: 'html', ...d, ...(localHtml !== null ? { local: localHtml } : {}) });
+  }
+
+  // ---- css — opaque text, journal-checkpointed
+  if (i.paths.css) {
+    const localCss = readText(i.paths.css);
+    const d = decideSourceLane({
+      local: localCss,
+      accepted: cssFromDoc(i.doc) ?? '',
+      knownBase: i.historyDir ? readRecoveryBody(i.historyDir, i.paths.css, 'base') : null,
+      baseHash: i.journal?.get(i.slug)?.cssHash ?? null,
+    });
+    verdicts.push({ lane: 'css', ...d, ...(localCss !== null ? { local: localCss } : {}) });
+  }
+
+  // ---- meta — the shared layout keys (viewport never travels)
+  if (i.paths.meta) {
+    const metaText = readText(i.paths.meta);
+    const local = metaText === null ? null : laneValueFromFile('meta', metaText);
+    const accepted = readLaneFromDoc(i.doc, 'meta');
+    if (local === null || local === accepted || (local === '{}' && accepted === '')) {
+      verdicts.push({ lane: 'meta', decision: local === null ? 'materialize' : 'agreed' });
+    } else if (accepted === '') {
+      verdicts.push({ lane: 'meta', decision: 'propose', base: '', local });
+    } else {
+      // No base is recorded for layout: the project's arrangement wins and the
+      // projection merges it into the local file's private keys.
+      verdicts.push({ lane: 'meta', decision: 'materialize', local });
+    }
+  }
+
+  // ---- comments / annotations — the accepted value wins (see header)
+  for (const lane of ['comments', 'annotations'] as const) {
+    const p = lane === 'comments' ? i.paths.comments : i.paths.annotations;
+    const text = readText(p);
+    const local = text === null ? null : laneValueFromFile(lane, text);
+    const accepted = readLaneFromDoc(i.doc, lane);
+    if (local === null || local === accepted) {
+      verdicts.push({ lane, decision: local === null ? 'materialize' : 'agreed' });
+      continue;
+    }
+    if (i.historyDir && text) {
+      try {
+        saveRecoveryBody(i.historyDir, p, 'local', text);
+      } catch {
+        /* recovery is best-effort for these lanes */
+      }
+    }
+    verdicts.push({ lane, decision: 'materialize', local: text ?? undefined });
+  }
+
+  // ---- act
+  for (const v of verdicts) {
+    if (v.decision === 'propose' && v.local !== undefined) {
+      const value = v.lane === 'meta' ? v.local : (laneValueFromFile(v.lane, v.local) ?? v.local);
+      if (v.lane === 'html') i.projection.adoptBase(v.base ?? '');
+      // Stageable: a restored unfinished AI action (T16) keeps its canvases'
+      // differences for the person's decision instead of publishing them.
+      void i.projection.proposeLane(v.lane, value, { baseContent: v.base ?? '', stageable: true });
+    } else if (v.decision === 'hold' && v.local !== undefined) {
+      i.projection.hold(v.lane, v.base ?? '', v.local);
+    }
+  }
+  const moved = verdicts.filter((v) => v.decision === 'propose' || v.decision === 'hold');
+  if (moved.length) {
+    log.log(
+      `[sync/${i.slug}] cold start: ${moved.map((v) => `${v.lane}=${v.decision}`).join(', ')}`
+    );
+  }
+  return { kind: 'reconciled', verdicts };
+}