@1agh/maude 0.30.0 → 0.32.0

package/apps/studio/test/readiness.test.ts

@@ -0,0 +1,127 @@
+// Readiness probe (DDR-128) — plugin-registry scan + PATH resolution. The
+// login-shell fallback's full correctness is proven on the packaged `.app`
+// (native-verification ceiling); here we cover the registry-scan branches, the
+// no-throw contracts, and the report shape. The probe is async (the fallback shells
+// out off the event loop — DDR-128 hardening), so everything awaits.
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { probeReadiness, resolveOnPath } from '../readiness.ts';
+
+const MARKET_OK = {
+  maude: { source: { source: 'github', repo: '1aGh/maude' }, installLocation: '/x' },
+};
+const INSTALLED_BOTH = {
+  version: 2,
+  plugins: {
+    'design@maude': [{ scope: 'user', version: '0.29.0' }],
+    'flow@maude': [{ scope: 'user', version: '0.29.0' }],
+  },
+};
+const INSTALLED_DESIGN_ONLY = { version: 2, plugins: { 'design@maude': [{ scope: 'user' }] } };
+
+function fixtureClaudeDir(opts: { markets?: unknown; installed?: unknown }): string {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-readiness-'));
+  const pluginsDir = join(dir, 'plugins');
+  mkdirSync(pluginsDir, { recursive: true });
+  if (opts.markets !== undefined)
+    writeFileSync(join(pluginsDir, 'known_marketplaces.json'), JSON.stringify(opts.markets));
+  if (opts.installed !== undefined)
+    writeFileSync(join(pluginsDir, 'installed_plugins.json'), JSON.stringify(opts.installed));
+  return dir;
+}
+
+async function withClaudeDir<T>(dir: string, fn: () => Promise<T> | T): Promise<T> {
+  const saved = process.env.CLAUDE_CONFIG_DIR;
+  process.env.CLAUDE_CONFIG_DIR = dir;
+  try {
+    return await fn();
+  } finally {
+    if (saved === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+    else process.env.CLAUDE_CONFIG_DIR = saved;
+  }
+}
+
+const pluginsItem = async (dir: string) =>
+  (await withClaudeDir(dir, () => probeReadiness())).items.find((i) => i.id === 'plugins')!;
+
+describe('readiness — plugin registry scan', () => {
+  test('both plugins + marketplace present → plugins item is present, no remediation', async () => {
+    const item = await pluginsItem(
+      fixtureClaudeDir({ markets: MARKET_OK, installed: INSTALLED_BOTH })
+    );
+    expect(item.status).toBe('present');
+    expect(item.remediation).toBeUndefined();
+  });
+
+  test('only design@maude installed → missing, names the absent flow@maude + offers the fix', async () => {
+    const item = await pluginsItem(
+      fixtureClaudeDir({ markets: MARKET_OK, installed: INSTALLED_DESIGN_ONLY })
+    );
+    expect(item.status).toBe('missing');
+    expect(item.detail).toContain('flow@maude');
+    expect(item.remediation).toContain('/plugin install');
+  });
+
+  test('registry absent → unknown (Claude Code internal contract; never throws)', async () => {
+    const item = await pluginsItem(fixtureClaudeDir({}));
+    expect(item.status).toBe('unknown');
+  });
+
+  test('plugin presence is the gate — a foreign-repo marketplace does not change a both-installed verdict', async () => {
+    const item = await pluginsItem(
+      fixtureClaudeDir({
+        markets: { other: { source: { repo: 'someone/else' } } },
+        installed: INSTALLED_BOTH,
+      })
+    );
+    expect(item.status).toBe('present');
+  });
+});
+
+describe('readiness — resolveOnPath', () => {
+  test('finds a binary that is on PATH', async () => {
+    const hit = await resolveOnPath('sh');
+    expect(hit).not.toBeNull();
+    expect(existsSync(hit!)).toBe(true);
+  });
+
+  test('returns null for a bogus binary without throwing', async () => {
+    expect(await resolveOnPath('maude-definitely-not-real-xyz')).toBeNull();
+  });
+
+  test('login-shell fallback recovers a binary hidden from the app PATH', async () => {
+    const saved = process.env.PATH;
+    try {
+      // Simulate the truncated/empty GUI env so Bun.which misses and the fallback fires.
+      process.env.PATH = '';
+      const hit = await resolveOnPath('sh');
+      // When a login shell is usable it must recover an absolute, real path. In a
+      // sandbox with no usable login shell the fallback returns null — we don't fail
+      // on that, but a non-null result must be a real absolute path.
+      if (hit !== null) {
+        expect(hit.startsWith('/')).toBe(true);
+        expect(existsSync(hit)).toBe(true);
+      }
+    } finally {
+      if (saved === undefined) delete process.env.PATH;
+      else process.env.PATH = saved;
+    }
+  });
+});
+
+describe('readiness — report shape', () => {
+  test('always returns the four items with stable ids and a boolean ready', async () => {
+    const report = await probeReadiness();
+    expect(report.items.map((i) => i.id)).toEqual(['claude', 'maude', 'plugins', 'agent-browser']);
+    expect(typeof report.ready).toBe('boolean');
+  });
+
+  test('agent-browser is optional and never gates ready', async () => {
+    const ab = (await probeReadiness()).items.find((i) => i.id === 'agent-browser')!;
+    expect(ab.required).toBe(false);
+  });
+});

package/apps/studio/test/sync-cold-seed-dedup.test.ts

@@ -0,0 +1,187 @@
+// Concurrent cold-seed de-duplication — F1 regression.
+//
+// RCA: `.ai/logs/rca/issue-collab-cold-seed-tsx-duplication.md`. When TWO
+// dev-servers seed the SAME canvas slug into an EMPTY hub at the SAME instant,
+// each reads `docBody === empty` before the other's `seed-local-up` write has
+// propagated, so both apply their (identical) body. Two `applyHtmlToDoc`
+// insertions from two Yjs clientIDs into one Y.Text are NOT content-deduped by
+// the CRDT — the body doubled (two `export default`), failing the canvas build.
+//
+// The fix elects a single writer (`syncMeta.seededBy` — Y.Map LWW converges it
+// to ONE clientID on every peer) which, inside a bounded post-seed window,
+// re-applies the canonical body so `applyHtmlToDoc`'s diff deletes the trailing
+// duplicate. These tests pin: (1) simultaneous seed → one copy, (2) a fresh peer
+// booting against an already-doubled hub recovers, (3) the sequential control
+// stays clean (no over-eager collapse of legitimately-adopted state).
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as Y from 'yjs';
+
+import { type CanvasSyncAgent, createCanvasSyncAgent } from '../sync/agent.ts';
+import { htmlFromDoc } from '../sync/codec.ts';
+import { createEchoGuard } from '../sync/echo-guard.ts';
+
+// A realistic canvas body — the un-buildable failure is `export default` × 2.
+const BODY = [
+  'import { DesignCanvas } from "@maude/canvas-lib";',
+  'export default function Screen() {',
+  '  return <DesignCanvas><h1>Shared draft</h1></DesignCanvas>;',
+  '}',
+  '',
+].join('\n');
+
+const TRANSPORT = Symbol('transport');
+
+let dirA: string;
+let dirB: string;
+let docA: Y.Doc;
+let docB: Y.Doc;
+let agentA: CanvasSyncAgent | undefined;
+let agentB: CanvasSyncAgent | undefined;
+
+function pathsFor(dir: string) {
+  return {
+    html: join(dir, 'screen.tsx'),
+    comments: join(dir, '_comments', 'screen.json'),
+    annotations: join(dir, 'screen.annotations.svg'),
+  };
+}
+
+function writeLocalBody(dir: string, body: string): void {
+  // Seed disk before the agent reconciles (the local side of the cold start).
+  writeFileSync(pathsFor(dir).html, body);
+}
+
+function makeAgent(doc: Y.Doc, dir: string): CanvasSyncAgent {
+  const a = createCanvasSyncAgent({
+    slug: 'screen',
+    doc,
+    paths: pathsFor(dir),
+    echoGuard: createEchoGuard(),
+    flushMs: 0, // synchronous flush via queueMicrotask
+  });
+  a.start();
+  return a;
+}
+
+/** Bidirectional full-state exchange, looped until the de-dup repair (which
+ *  fires synchronously inside applyUpdate) has propagated + settled. */
+function syncDocs(d1: Y.Doc, d2: Y.Doc, rounds = 6): void {
+  for (let i = 0; i < rounds; i++) {
+    Y.applyUpdate(d2, Y.encodeStateAsUpdate(d1), TRANSPORT);
+    Y.applyUpdate(d1, Y.encodeStateAsUpdate(d2), TRANSPORT);
+  }
+}
+
+beforeEach(() => {
+  dirA = mkdtempSync(join(tmpdir(), 'cold-seed-a-'));
+  dirB = mkdtempSync(join(tmpdir(), 'cold-seed-b-'));
+  docA = new Y.Doc();
+  docB = new Y.Doc();
+});
+
+afterEach(() => {
+  agentA?.stop();
+  agentB?.stop();
+  agentA = undefined;
+  agentB = undefined;
+  rmSync(dirA, { recursive: true, force: true });
+  rmSync(dirB, { recursive: true, force: true });
+});
+
+describe('concurrent cold-seed → single body', () => {
+  test('two peers seed identical bodies into an empty hub at once → ONE copy', async () => {
+    writeLocalBody(dirA, BODY);
+    writeLocalBody(dirB, BODY);
+    agentA = makeAgent(docA, dirA);
+    agentB = makeAgent(docB, dirB);
+
+    // The race: BOTH reconcile against an empty doc before either propagates.
+    await agentA.reconcile();
+    await agentB.reconcile();
+
+    // Hub merges both seeds — the moment the duplication would surface.
+    syncDocs(docA, docB);
+
+    // Both docs converge to exactly ONE copy (no doubled `export default`).
+    expect(htmlFromDoc(docA)).toBe(BODY);
+    expect(htmlFromDoc(docB)).toBe(BODY);
+    // And the count of `export default` is 1 — the build-breaking signature gone.
+    expect(htmlFromDoc(docA).match(/export default/g)?.length).toBe(1);
+
+    // Disk on both peers mirrors the single copy.
+    await agentA.flush();
+    await agentB.flush();
+    expect(readFileSync(pathsFor(dirA).html, 'utf8')).toBe(BODY);
+    expect(readFileSync(pathsFor(dirB).html, 'utf8')).toBe(BODY);
+  });
+
+  test('adopt-mode concurrent seed also self-heals to one copy', async () => {
+    writeLocalBody(dirA, BODY);
+    writeLocalBody(dirB, BODY);
+    agentA = createCanvasSyncAgent({
+      slug: 'screen',
+      doc: docA,
+      paths: pathsFor(dirA),
+      echoGuard: createEchoGuard(),
+      flushMs: 0,
+      adopt: true,
+    });
+    agentB = createCanvasSyncAgent({
+      slug: 'screen',
+      doc: docB,
+      paths: pathsFor(dirB),
+      echoGuard: createEchoGuard(),
+      flushMs: 0,
+      adopt: true,
+    });
+    agentA.start();
+    agentB.start();
+
+    await agentA.reconcile();
+    await agentB.reconcile();
+    syncDocs(docA, docB);
+
+    expect(htmlFromDoc(docA)).toBe(BODY);
+    expect(htmlFromDoc(docB)).toBe(BODY);
+  });
+});
+
+describe('recovery of an already-duplicated hub (requirement #3)', () => {
+  test('a peer booting against a doubled doc collapses it on reconcile', async () => {
+    writeLocalBody(dirA, BODY);
+    // Simulate a hub that already concatenated two identical seeds.
+    const t = docA.getText('html');
+    t.insert(0, BODY);
+    t.insert(BODY.length, BODY);
+    expect(htmlFromDoc(docA)).toBe(BODY + BODY);
+
+    agentA = makeAgent(docA, dirA);
+    await agentA.reconcile();
+
+    expect(htmlFromDoc(docA)).toBe(BODY);
+    expect(htmlFromDoc(docA).match(/export default/g)?.length).toBe(1);
+  });
+});
+
+describe('sequential control — no over-eager collapse', () => {
+  test('B joining after A seeded adopts the single copy (no duplication)', async () => {
+    writeLocalBody(dirA, BODY);
+    writeLocalBody(dirB, BODY);
+    agentA = makeAgent(docA, dirA);
+    agentB = makeAgent(docB, dirB);
+
+    // A seeds first and FULLY propagates before B reconciles.
+    await agentA.reconcile();
+    syncDocs(docA, docB);
+    // B now sees the hub already holds the body → noop (adopt), no second seed.
+    await agentB.reconcile();
+    syncDocs(docA, docB);
+
+    expect(htmlFromDoc(docA)).toBe(BODY);
+    expect(htmlFromDoc(docB)).toBe(BODY);
+  });
+});

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

@@ -8,7 +8,7 @@
 
 import { describe, expect, test } from 'bun:test';
 
-import { type ColdStartInput, decideColdStart } from '../sync/cold-start.ts';
+import { type ColdStartInput, decideColdStart, isExactRepeat } from '../sync/cold-start.ts';
 import { hashBytes } from '../sync/echo-guard.ts';
 
 const BODY_LOCAL = '<div>local work — a day of mascot edits</div>';
@@ -82,6 +82,66 @@ describe('decideColdStart — identical sides', () => {
   });
 });
 
+describe('decideColdStart — concurrent cold-seed duplication (F1)', () => {
+  const BODY = '<div>export default fn — one copy</div>';
+
+  test('doc == local repeated twice → recover-seed-dup (collapse, not conflict)', () => {
+    const d = decideColdStart(input({ localBody: BODY, docBody: BODY + BODY }));
+    expect(d.action).toBe('recover-seed-dup');
+  });
+
+  test('doc == local repeated three times (3-way seed) → recover-seed-dup', () => {
+    const d = decideColdStart(input({ localBody: BODY, docBody: BODY.repeat(3) }));
+    expect(d.action).toBe('recover-seed-dup');
+  });
+
+  test('duplication recovery beats the conflict path even with divergent timestamps', () => {
+    // A doubled body is NOT new content — newest-wins must not get to pick it.
+    const d = decideColdStart(
+      input({
+        localBody: BODY,
+        docBody: BODY + BODY,
+        localMtimeMs: 1_000,
+        docBodyEditAtMs: 9_999,
+      })
+    );
+    expect(d.action).toBe('recover-seed-dup');
+  });
+
+  test('duplication recovery fires even with a stale journal', () => {
+    const d = decideColdStart(
+      input({ localBody: BODY, docBody: BODY + BODY, journalHash: 'stale' })
+    );
+    expect(d.action).toBe('recover-seed-dup');
+  });
+
+  test('doc = local + genuinely different bytes is NOT a repeat → conflict (snapshots both)', () => {
+    const d = decideColdStart(
+      input({
+        localBody: BODY,
+        docBody: `${BODY}<div>a real concurrent edit</div>`,
+        localMtimeMs: 2_000,
+        docBodyEditAtMs: 1_000,
+      })
+    );
+    expect(d.action).toBe('conflict');
+  });
+
+  test('exact equality (×1) stays a noop, never recover-seed-dup', () => {
+    expect(decideColdStart(input({ localBody: BODY, docBody: BODY })).action).toBe('noop');
+  });
+
+  test('isExactRepeat — exact multiples only', () => {
+    expect(isExactRepeat(BODY + BODY, BODY)).toBe(true);
+    expect(isExactRepeat(BODY.repeat(4), BODY)).toBe(true);
+    expect(isExactRepeat(BODY, BODY)).toBe(false); // ×1 is equality, not duplication
+    expect(isExactRepeat(`${BODY}x`, BODY)).toBe(false); // not a clean multiple
+    expect(isExactRepeat(`${BODY}${BODY}x`, BODY)).toBe(false);
+    expect(isExactRepeat('', BODY)).toBe(false);
+    expect(isExactRepeat(BODY, '')).toBe(false);
+  });
+});
+
 describe('decideColdStart — journal-gated fast-forward', () => {
   test('local ≠ doc, journal matches hash(local) → fast-forward-hub (no conflict)', () => {
     const d = decideColdStart(

package/apps/studio/test/tour-overlay.test.tsx

@@ -43,6 +43,24 @@ describe('TourOverlay', () => {
     expect(html).not.toContain('mdcc-tour__back'); // i === 0
   });
 
+  test('a step with a render graphic widens the card and draws the graphic (Phase 29 / E4)', () => {
+    function Graphic() {
+      return <div className="cm-info">TWO-LAYER-DIAGRAM</div>;
+    }
+    const html = renderToStaticMarkup(
+      <TourOverlay
+        open
+        steps={[{ render: Graphic, title: 'Working together', body: 'Two layers.' }]}
+        onClose={() => {}}
+        onComplete={() => {}}
+      />
+    );
+    expect(html).toContain('mdcc-tour__card--graphic');
+    expect(html).toContain('mdcc-tour__graphic');
+    expect(html).toContain('TWO-LAYER-DIAGRAM');
+    expect(html).toContain('Working together');
+  });
+
   test('closed or empty renders nothing', () => {
     expect(
       renderToStaticMarkup(

package/apps/studio/tool-palette.tsx

@@ -20,7 +20,7 @@ import {
   SHAPE_KIND_ICONS,
   TOOL_ICONS,
 } from './canvas-icons.tsx';
-import { useAnnotationsVisibility } from './use-annotations-visibility.tsx';
+import { useChromeVisibility } from './use-chrome-visibility.tsx';
 import { type ShapeKind, useToolMode } from './use-tool-mode.tsx';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -256,7 +256,7 @@ const SHAPE_KINDS: ReadonlyArray<{ kind: ShapeKind; label: string }> = [
 export function ToolPalette() {
   ensurePaletteStyles();
   const { tool, setTool, tools, sticky, toggleSticky, shapeKind, setShapeKind } = useToolMode();
-  const visibilityCtx = useAnnotationsVisibility();
+  const chrome = useChromeVisibility();
   const [mounted, setMounted] = useState(false);
   const [shapeOpen, setShapeOpen] = useState(false);
   const containerRef = useRef<HTMLDivElement | null>(null);
@@ -287,11 +287,12 @@ export function ToolPalette() {
   }, [tool]);
 
   if (!mounted) return null;
+  // Presentation Mode hides the whole tool palette (clean artboards-only view).
+  if (chrome?.present) return null;
 
   const byId = new Map(tools.map((t) => [t.id, t]));
   const navList = NAV_TOOLS.map((id) => byId.get(id)).filter(Boolean);
   const drawList = DRAW_TOOLS.map((id) => byId.get(id)).filter(Boolean);
-  const annotationsHidden = visibilityCtx ? !visibilityCtx.visible : false;
 
   const renderToolButton = (id: string, label: string, shortcut: string) => {
     const Icon = TOOL_ICONS[id];
@@ -412,12 +413,20 @@ export function ToolPalette() {
         </button>
         <button
           type="button"
-          aria-label={
-            annotationsHidden ? 'Show annotations (Shift+P)' : 'Hide annotations (Shift+P)'
-          }
-          aria-pressed={annotationsHidden}
-          title="Presentation (Shift+P)"
-          onClick={() => visibilityCtx?.setVisible(!visibilityCtx.visible)}
+          aria-label="Presentation mode — hide all chrome"
+          title="Presentation mode — hide all chrome (Esc to exit)"
+          onClick={() => {
+            // Present Mode is a SHELL-level state (it hides the menubar /
+            // sidebar / panels too), so the canvas iframe requests it from the
+            // parent shell, which flips on `.is-present` + broadcasts
+            // dgn:'view-chrome' back down. Enter-only — the palette is hidden
+            // while presenting; exit is Esc or the floating pill.
+            try {
+              window.parent.postMessage({ dgn: 'present-enter' }, '*');
+            } catch {
+              /* detached / cross-origin */
+            }
+          }}
         >
           <IconPresentation />
         </button>

package/apps/studio/use-chrome-visibility.tsx

@@ -0,0 +1,66 @@
+/**
+ * @file       use-chrome-visibility.tsx — canvas-chrome visibility store
+ * @scope      apps/studio/use-chrome-visibility.tsx
+ * @purpose    Tiny store shared by the in-canvas floating chrome — DCMiniMap +
+ *             DCZoomToolbar (canvas-lib), ToolPalette, and AnnotationsLayer —
+ *             so the dev-server menubar can hide/show the minimap and zoom
+ *             controls, and drive a non-destructive "Presentation Mode" that
+ *             overlays-hides ALL chrome (minimap, zoom, tool palette,
+ *             annotations) without mutating the user's individual toggles.
+ *             Mounted by CanvasShell (next to AnnotationsVisibilityProvider) so
+ *             the user canvas (which renders the minimap/zoom) AND its overlay
+ *             siblings under CanvasRouter all consume the same value. Updated
+ *             by the `dgn:'view-chrome'` postMessage handler in CanvasRouter.
+ *
+ *             `present` is a master overlay-hide that supersedes `minimap`/
+ *             `zoom`: while it is on, every chrome consumer renders nothing,
+ *             and exiting restores whatever the individual toggles were.
+ */
+
+import { createContext, type ReactNode, useCallback, useContext, useMemo, useState } from 'react';
+
+export interface ChromeVisibilityState {
+  /** Floating world mini-map (DCMiniMap). */
+  minimap: boolean;
+  /** Bottom zoom pill (DCZoomToolbar). */
+  zoom: boolean;
+  /** Presentation Mode — hides ALL chrome regardless of the two above. */
+  present: boolean;
+}
+
+export interface ChromeVisibilityValue extends ChromeVisibilityState {
+  /** Merge a partial patch (only the provided keys change). */
+  setChrome: (patch: Partial<ChromeVisibilityState>) => void;
+}
+
+const ChromeVisibilityContext = createContext<ChromeVisibilityValue | null>(null);
+
+export function ChromeVisibilityProvider({
+  children,
+  initial,
+}: {
+  children: ReactNode;
+  initial?: Partial<ChromeVisibilityState>;
+}) {
+  const [state, setState] = useState<ChromeVisibilityState>({
+    minimap: initial?.minimap ?? true,
+    zoom: initial?.zoom ?? true,
+    present: initial?.present ?? false,
+  });
+  const setChrome = useCallback((patch: Partial<ChromeVisibilityState>) => {
+    setState((prev) => ({ ...prev, ...patch }));
+  }, []);
+  const value = useMemo<ChromeVisibilityValue>(() => ({ ...state, setChrome }), [state, setChrome]);
+  return (
+    <ChromeVisibilityContext.Provider value={value}>{children}</ChromeVisibilityContext.Provider>
+  );
+}
+
+/**
+ * Returns the chrome-visibility value, or null when rendered outside a
+ * provider (e.g. a bare DS specimen). Consumers treat null as "all visible"
+ * so the default behaviour is unchanged.
+ */
+export function useChromeVisibility(): ChromeVisibilityValue | null {
+  return useContext(ChromeVisibilityContext);
+}