@1agh/maude 0.20.0 → 0.21.0

package/plugins/design/dev-server/export-dialog.tsx

@@ -139,7 +139,7 @@ const DIALOG_CSS = `
 .dc-export-dialog .dc-ed-recent button:hover { background: rgba(0,0,0,0.04); border-color: rgba(0,0,0,0.06); }
 .dc-export-dialog footer { padding: 12px 20px; border-top: 1px solid var(--u-border-subtle, rgba(0,0,0,0.08)); display: flex; justify-content: flex-end; gap: 8px; }
 .dc-export-dialog footer button { padding: 8px 14px; border-radius: 0; border: 1px solid var(--u-fg-0, rgba(0,0,0,0.12)); background: var(--u-bg-1, var(--bg-0, #fafafa)); font: inherit; font-size: 12px; cursor: pointer; color: inherit; }
-.dc-export-dialog footer button.dc-ed-primary { background: var(--accent, #1a1a1a); color: var(--accent-fg, #fff); border-color: transparent; }
+.dc-export-dialog footer button.dc-ed-primary { background: var(--maude-hud-accent, #1a1a1a); color: var(--maude-hud-accent-fg, #fff); border-color: transparent; }
 .dc-export-dialog footer button:disabled { opacity: 0.4; cursor: not-allowed; }
 .dc-export-dialog .dc-ed-status { padding: 8px 20px; font-size: 12px; color: var(--fg-1, rgba(40,30,20,0.65)); border-top: 1px solid var(--u-border-subtle, rgba(0,0,0,0.08)); }
 .dc-export-dialog .dc-ed-status.is-error { color: var(--status-error, #c0392b); }

package/plugins/design/dev-server/hmr-broadcast.ts

@@ -25,10 +25,13 @@ const DEBOUNCE_MS = 50;
 
 export interface HmrMessage {
   type: 'canvas-hmr';
-  mode: 'css' | 'module' | 'hard';
+  mode: 'css' | 'module' | 'hard' | 'meta';
   /**
    * Canvas-relative path of the file that changed, slash-normalised. Absent
    * when mode === 'hard' (the change is global — every canvas reloads).
+   *
+   * For mode === 'meta' this is the `<base>.meta.json` path; iframe peels off
+   * the `.meta.json` suffix to compare against its own `canvasRel`.
    */
   file?: string;
   /** Cache-bust token — etag-like. Caller appends to <link> href. */
@@ -70,6 +73,13 @@ export function createHmrBroadcaster(
     if (ext === '.css') {
       return { type: 'canvas-hmr', mode: 'css', file: rel, version, scope: 'canvas' };
     }
+    // Phase 8 — canvas-meta sidecar (`<base>.meta.json`) carries the
+    // artboard layout / viewport. Emit a `meta` mode so foreign tabs can
+    // re-fetch + re-apply the layout WITHOUT a full reload (which would
+    // lose React state like tool mode, undo stack, scroll position).
+    if (rel.endsWith('.meta.json')) {
+      return { type: 'canvas-hmr', mode: 'meta', file: rel, version, scope: 'canvas' };
+    }
     if (ext === '.tsx' || ext === '.jsx' || ext === '.ts' || ext === '.js') {
       return { type: 'canvas-hmr', mode: 'module', file: rel, version, scope: 'canvas' };
     }
@@ -80,7 +90,10 @@ export function createHmrBroadcaster(
     // Coalesce: hard > module > css. If a hard reload is queued, ignore any
     // softer follow-up within the debounce window.
     if (pendingMsg) {
-      const rank: Record<HmrMessage['mode'], number> = { css: 0, module: 1, hard: 2 };
+      // meta is the lightest signal — it doesn't trigger a reload, just
+      // re-fetches the sidecar. CSS still ranks above it so a same-window
+      // CSS write wins over a meta echo.
+      const rank: Record<HmrMessage['mode'], number> = { meta: 0, css: 1, module: 2, hard: 3 };
       if (rank[msg.mode] < rank[pendingMsg.mode]) {
         // Keep the existing (harder) message; just refresh the timer.
       } else {

package/plugins/design/dev-server/http.ts

@@ -11,6 +11,7 @@ import type { Api } from './api.ts';
 import { buildCanvasModule } from './canvas-build.ts';
 import { canvasLibPath } from './canvas-lib-resolver.ts';
 import { TranspileError } from './canvas-pipeline.ts';
+import type { AiActivity } from './collab/ai-activity.ts';
 import type { Context } from './context.ts';
 import { isFormat, isScope, runExport } from './exporters/index.ts';
 import type { ActiveJsonShape } from './exporters/scope.ts';
@@ -157,7 +158,7 @@ export interface Http {
   fetch(req: Request): Promise<Response>;
 }
 
-export function createHttp(ctx: Context, api: Api, inspect: Inspect): Http {
+export function createHttp(ctx: Context, api: Api, inspect: Inspect, ai: AiActivity): Http {
   // Cache invalidation — when canvas-lib changes, every cached canvas bundle
   // is stale because canvas-lib is inlined into each one via the resolver
   // plugin. Drop the whole cache so the next request rebuilds with the fresh
@@ -306,6 +307,68 @@ export function createHttp(ctx: Context, api: Api, inspect: Inspect): Http {
       return Response.json({ committers }, { headers: { 'Cache-Control': 'no-store' } });
     },
 
+    '/_api/git-user': async (req: Request) => {
+      // Phase 8 — local `git config user.name` for the collab Awareness peer
+      // identity. Color-hash derives from this; falls back to anonymous-<pid>
+      // client-side when empty.
+      if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
+      const name = await api.gitCurrentUser();
+      return Response.json({ name }, { headers: { 'Cache-Control': 'no-store' } });
+    },
+
+    '/_api/ai': async (req: Request) => {
+      // Phase 8 Task 4 — read-only snapshot of the current AI activity map.
+      // GET → { entries: [{ file, author, startedAt, lastHeartbeat }, …] }
+      // Clients use this on mount to backfill the banner state without
+      // waiting for the next bus event.
+      if (req.method !== 'GET') return new Response('Method not allowed', { status: 405 });
+      return Response.json({ entries: ai.list() }, { headers: { 'Cache-Control': 'no-store' } });
+    },
+
+    '/_api/ai/start': async (req: Request) => {
+      // Phase 8 Task 4 — `/design:edit` (or any external slash command driving
+      // Claude work) POSTs here when work begins. body = { file, author }.
+      // Replaces any prior entry for the file.
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      const body = await readJson<{ file?: string; author?: string }>(req);
+      if (!body || typeof body.file !== 'string' || !body.file.trim()) {
+        return new Response('body.file required', { status: 400 });
+      }
+      const author =
+        typeof body.author === 'string' && body.author.trim()
+          ? body.author.trim().slice(0, 120)
+          : 'Claude';
+      const entry = ai.start(body.file.trim(), author);
+      return Response.json(entry, { headers: { 'Cache-Control': 'no-store' } });
+    },
+
+    '/_api/ai/heartbeat': async (req: Request) => {
+      // Refresh the lastHeartbeat. Returns 404 if no entry — slash command
+      // can treat that as "the server bounced; re-issue /start".
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      const body = await readJson<{ file?: string }>(req);
+      if (!body || typeof body.file !== 'string' || !body.file.trim()) {
+        return new Response('body.file required', { status: 400 });
+      }
+      const entry = ai.heartbeat(body.file.trim());
+      if (!entry) return new Response('no active entry', { status: 404 });
+      return Response.json(entry, { headers: { 'Cache-Control': 'no-store' } });
+    },
+
+    '/_api/ai/end': async (req: Request) => {
+      // Explicit completion (normal or error). Banner clears immediately.
+      if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 });
+      const body = await readJson<{ file?: string }>(req);
+      if (!body || typeof body.file !== 'string' || !body.file.trim()) {
+        return new Response('body.file required', { status: 400 });
+      }
+      const cleared = ai.end(body.file.trim());
+      return Response.json(
+        { cleared },
+        { status: cleared ? 200 : 404, headers: { 'Cache-Control': 'no-store' } }
+      );
+    },
+
     '/_api/annotations': async (req: Request) => {
       // Phase 5 — `<designRoot>/<slug>.annotations.svg` read / overwrite.
       // GET ?file=<repo-relative-canvas-path>           → SVG text (empty if absent)

package/plugins/design/dev-server/marquee-overlay.tsx

@@ -31,8 +31,8 @@ const ELEM_MARQUEE_CSS = `
   position: fixed;
   pointer-events: none;
   z-index: 5;
-  border: 1px solid var(--accent, #0d99ff);
-  background: color-mix(in oklab, var(--accent, #0d99ff) 8%, transparent);
+  border: 1px solid var(--maude-hud-accent, #0d99ff);
+  background: color-mix(in oklab, var(--maude-hud-accent, #0d99ff) 8%, transparent);
   display: none;
 }
 `.trim();

package/plugins/design/dev-server/participants-chrome.tsx

@@ -0,0 +1,261 @@
+/**
+ * @file       participants-chrome.tsx — top-right avatar stack of live peers
+ * @scope      plugins/design/dev-server/participants-chrome.tsx
+ * @purpose    Phase 8 Task 6 — show who's currently on the canvas. Colored
+ *             initials in a circle per peer, with a popover for full name +
+ *             "Follow" button. Follow mode publishes `followTarget` on my
+ *             Awareness; a separate effect pulls the target's viewport on
+ *             every update and calls controller.setViewport, snapping my pan
+ *             + zoom to theirs in lockstep.
+ *
+ * Follow semantics — soft and one-way. The target peer doesn't know they're
+ * being followed (no UI, no Awareness echo). Either party panning the canvas
+ * breaks nothing on the other end; I just keep mirroring until I click my
+ * own avatar to release. tldraw-style.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { useViewportControllerContext } from './canvas-lib.tsx';
+import { type ForeignAwareness, useCollab, useForeignAwareness } from './use-collab.tsx';
+
+const CHROME_CSS = `
+.dc-participants {
+  position: fixed;
+  top: 12px;
+  right: 12px;
+  z-index: 10000;
+  display: flex;
+  align-items: center;
+  pointer-events: auto;
+  font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
+}
+.dc-participant {
+  width: 26px;
+  height: 26px;
+  border-radius: 50%;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 600;
+  font-size: 10px;
+  line-height: 1;
+  letter-spacing: 0.02em;
+  color: var(--maude-hud-accent-fg, #fff);
+  border: 1.5px solid var(--bg-0, #fff);
+  margin-left: -6px;
+  cursor: pointer;
+  position: relative;
+  box-shadow: 0 1px 2px rgba(0,0,0,0.08);
+  user-select: none;
+  transition: transform 120ms ease, z-index 0ms 120ms;
+}
+.dc-participant:first-child { margin-left: 0; }
+.dc-participant:hover {
+  transform: scale(1.06);
+  z-index: 10;
+  transition-delay: 0ms;
+}
+.dc-participant:focus-visible {
+  outline: 2px solid var(--maude-hud-accent, oklch(56% 0.170 50));
+  outline-offset: 2px;
+}
+.dc-participant--following {
+  outline: 1.5px solid var(--maude-hud-accent, oklch(56% 0.170 50));
+  outline-offset: 1.5px;
+}
+.dc-participant-popover {
+  position: absolute;
+  top: calc(100% + 8px);
+  right: 0;
+  min-width: 168px;
+  padding: 10px 12px;
+  background: var(--bg-1, #fff);
+  color: var(--fg-0, #111);
+  border: 1px solid var(--border-default, rgba(0,0,0,0.16));
+  border-radius: var(--radius-md, 4px);
+  font-size: 12px;
+  line-height: 1.35;
+  white-space: nowrap;
+  box-shadow: 0 6px 18px rgba(0,0,0,0.10);
+  z-index: 11;
+}
+.dc-participant-popover__name {
+  font-weight: 600;
+  margin-bottom: 8px;
+  color: var(--fg-0, #111);
+  letter-spacing: 0.01em;
+}
+.dc-participant-popover__btn {
+  display: inline-block;
+  padding: 4px 10px;
+  background: var(--maude-hud-accent, oklch(56% 0.170 50));
+  color: var(--maude-hud-accent-fg, #fff);
+  border: none;
+  border-radius: var(--radius-sm, 2px);
+  font-family: inherit;
+  font-weight: 500;
+  font-size: 11px;
+  line-height: 1.3;
+  cursor: pointer;
+  letter-spacing: 0.02em;
+}
+.dc-participant-popover__btn:hover { background: var(--maude-hud-accent-hover, var(--maude-hud-accent, oklch(50% 0.170 50))); }
+.dc-participant-popover__btn--stop {
+  background: var(--bg-3, #e5e5e5);
+  color: var(--fg-0, #111);
+  border: 1px solid var(--border-subtle, rgba(0,0,0,0.12));
+}
+.dc-participant-popover__btn--stop:hover { background: var(--bg-4, #d8d8d8); }
+@media (prefers-reduced-motion: reduce) {
+  .dc-participant { transition: none; }
+}
+`.trim();
+
+function ensureChromeStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-participants-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-participants-css';
+  s.textContent = CHROME_CSS;
+  document.head.appendChild(s);
+}
+
+function initialsFor(name: string): string {
+  const cleaned = name.trim();
+  if (!cleaned) return '?';
+  const parts = cleaned.split(/\s+/).filter(Boolean);
+  const first = parts[0] ?? '';
+  if (parts.length === 1) return first.slice(0, 2).toUpperCase();
+  const second = parts[1] ?? '';
+  return ((first[0] ?? '') + (second[0] ?? '')).toUpperCase();
+}
+
+interface AvatarProps {
+  peer: ForeignAwareness;
+  isFollowing: boolean;
+  onToggleFollow: (clientID: number) => void;
+}
+
+function Avatar({ peer, isFollowing, onToggleFollow }: AvatarProps): JSX.Element {
+  const [open, setOpen] = useState(false);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    const onDocClick = (e: MouseEvent) => {
+      if (!rootRef.current) return;
+      if (!rootRef.current.contains(e.target as Node)) setOpen(false);
+    };
+    document.addEventListener('mousedown', onDocClick);
+    return () => document.removeEventListener('mousedown', onDocClick);
+  }, [open]);
+
+  return (
+    <div
+      ref={rootRef}
+      className={`dc-participant${isFollowing ? ' dc-participant--following' : ''}`}
+      style={{ background: peer.color }}
+      onClick={() => setOpen((v) => !v)}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          setOpen((v) => !v);
+        }
+      }}
+      // biome-ignore lint/a11y/useSemanticElements: 28px round chip needs raw <div> + inline bg + custom focus ring; <button> reset is more code than the rule saves.
+      role="button"
+      tabIndex={0}
+      title={peer.name}
+      aria-label={peer.name}
+      aria-expanded={open}
+    >
+      {initialsFor(peer.name)}
+      {open && (
+        // biome-ignore lint/a11y/useKeyWithClickEvents: stop-propagation wrapper; keyboard focus stays in the button child.
+        // biome-ignore lint/a11y/useSemanticElements: popover wrapper carries no semantic role; the inner <button> is the actionable element.
+        <div className="dc-participant-popover" onClick={(e) => e.stopPropagation()}>
+          <div className="dc-participant-popover__name">{peer.name}</div>
+          <button
+            type="button"
+            className={`dc-participant-popover__btn${isFollowing ? ' dc-participant-popover__btn--stop' : ''}`}
+            onClick={() => {
+              onToggleFollow(peer.clientID);
+              setOpen(false);
+            }}
+          >
+            {isFollowing ? 'Stop following' : `Follow ${peer.name.split(/\s+/)[0]}`}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function ParticipantsChrome(): JSX.Element | null {
+  ensureChromeStyles();
+  const collab = useCollab();
+  const peers = useForeignAwareness();
+  const controller = useViewportControllerContext();
+
+  const [followTarget, setFollowTarget] = useState<number | null>(null);
+
+  const onToggleFollow = useCallback(
+    (clientID: number) => {
+      setFollowTarget((prev) => (prev === clientID ? null : clientID));
+      if (collab) {
+        collab.publishAwareness({
+          selection: collab.awareness.getLocalState()?.selection ?? null,
+        });
+        // Tag follow target as an Awareness key so Phase 9 follow-back UIs
+        // can read it; not currently used by anything else.
+        const state = collab.awareness.getLocalState() ?? {};
+        collab.awareness.setLocalState({
+          ...state,
+          followTarget: clientID === followTarget ? null : clientID,
+        });
+      }
+    },
+    [collab, followTarget]
+  );
+
+  // Apply follow — when followTarget is set, mirror the target's viewport
+  // onto our local controller. Each peer-Awareness update re-fires this; we
+  // skip when the viewport hasn't actually changed (saves a controller write).
+  const lastAppliedRef = useRef<{ x: number; y: number; zoom: number } | null>(null);
+  useEffect(() => {
+    if (followTarget === null) {
+      lastAppliedRef.current = null;
+      return;
+    }
+    if (!controller) return;
+    const target = peers.find((p) => p.clientID === followTarget);
+    if (!target) {
+      // Target peer disconnected; release follow.
+      setFollowTarget(null);
+      return;
+    }
+    const v = target.viewport;
+    const last = lastAppliedRef.current;
+    if (last && last.x === v.x && last.y === v.y && last.zoom === v.zoom) return;
+    lastAppliedRef.current = { x: v.x, y: v.y, zoom: v.zoom };
+    controller.setViewport(v);
+  }, [controller, followTarget, peers]);
+
+  if (peers.length === 0) return null;
+
+  return (
+    <div className="dc-participants" aria-label="Active collaborators">
+      {peers.map((p) => (
+        <Avatar
+          key={p.clientID}
+          peer={p}
+          isFollowing={followTarget === p.clientID}
+          onToggleFollow={onToggleFollow}
+        />
+      ))}
+    </div>
+  );
+}
+
+export { initialsFor };

package/plugins/design/dev-server/runtime-bundle.ts

@@ -60,6 +60,14 @@ export const RUNTIME_PACKAGES = [
   // dep declaration on the registry-item.json output.
   'motion',
   'motion/react',
+  // Phase 8 / DDR-051 — Yjs + y-protocols for the canvas-shell collab client.
+  // Each canvas iframe opens a WS to /_ws/collab/:slug and owns a per-iframe
+  // Y.Doc + Awareness instance. Externalised here so the client-side
+  // use-collab.tsx + cursors-overlay.tsx resolve via the importmap; canvases
+  // that don't use collab pay zero bundle cost (tree-shaken).
+  'yjs',
+  'y-protocols/sync',
+  'y-protocols/awareness',
 ] as const;
 
 export type RuntimePackage = (typeof RUNTIME_PACKAGES)[number];

package/plugins/design/dev-server/server.ts

@@ -18,12 +18,15 @@ import { spawn } from 'node:child_process';
 
 import { createApi } from './api.ts';
 import { bootSelfHeal } from './boot-self-heal.ts';
+import { createAiActivity } from './collab/ai-activity.ts';
+import { createGitLifecycle } from './collab/git-lifecycle.ts';
+import { createCollab } from './collab/index.ts';
 import { createContext } from './context.ts';
 import { createFsWatch } from './fs-watch.ts';
 import { createHttp } from './http.ts';
 import { createInspect } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
-import { createWs } from './ws.ts';
+import { type WsData, createWs, isLoopbackHost, parseCollabSlug } from './ws.ts';
 
 // Phase 19 / DDR-044 — covers the marketplace-cache-install gap where
 // node_modules/ ships empty (git clone honors .gitignore). Auto-installs +
@@ -32,17 +35,41 @@ await bootSelfHeal();
 
 const ctx = createContext();
 
-const api = createApi(ctx, async (file) => {
-  // After every comments mutation, re-broadcast the updated list.
-  const comments = await api.loadCommentsForFile(file);
-  ctx.bus.emit('comments', { file, comments });
+// Forward-declared so the api.commentsAdd/patch/delete/addReply callback can
+// reach into the collab registry (Phase 8 Task 3 bridge). collab is initialized
+// synchronously below; the callback only fires at runtime, by which point the
+// binding is set.
+let collab: ReturnType<typeof createCollab> | null = null;
+
+const api = createApi(ctx, {
+  onCommentsChanged: async (file) => {
+    // After every comments mutation, re-broadcast the updated list.
+    const comments = await api.loadCommentsForFile(file);
+    ctx.bus.emit('comments', { file, comments });
+    // 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.
+    if (collab) {
+      collab.registry.syncRoomFromComments(api.fileSlug(file), comments);
+    }
+  },
+  // 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) => {
+    if (collab) {
+      collab.registry.syncRoomFromAnnotations(api.fileSlug(file), svg);
+    }
+  },
 });
 
 const inspect = createInspect(ctx, (file) => api.loadCommentsForFile(file));
 await inspect.load();
 
-const ws = createWs(ctx, api, inspect);
-const http = createHttp(ctx, api, inspect);
+collab = createCollab(ctx, api);
+const aiActivity = createAiActivity(ctx);
+const gitLifecycle = createGitLifecycle(ctx, collab.registry);
+const ws = createWs(ctx, api, inspect, collab);
+const http = createHttp(ctx, api, inspect, aiActivity);
 const fsWatch = createFsWatch(ctx);
 
 // Port: --port arg > $PORT > $MDCC_DEV_PORT > 4399.
@@ -59,21 +86,46 @@ function resolvePort(): { port: number; explicit: boolean } {
 
 const { port: BASE_PORT, explicit: PORT_EXPLICIT } = resolvePort();
 
-type BunServer = ReturnType<typeof Bun.serve<{ id: string; remote: string }, never>>;
+type BunServer = ReturnType<typeof Bun.serve<WsData, never>>;
 
 function startServer(port: number): BunServer {
-  return Bun.serve<{ id: string; remote: string }, never>({
+  return Bun.serve<WsData, never>({
     port,
     hostname: '127.0.0.1',
     development: process.env.NODE_ENV !== 'production',
     routes: http.routes,
     async fetch(req, srv) {
-      // WebSocket upgrade.
-      if (new URL(req.url).pathname.startsWith('/_ws')) {
+      const pathname = new URL(req.url).pathname;
+
+      // Phase 8 — collab WS, binary y-websocket protocol. Loopback-only;
+      // DDR-047 makes cross-machine collab a Phase 9 hub-deploy story, not
+      // a `--bind 0.0.0.0` flag on this server.
+      const collabSlug = parseCollabSlug(pathname);
+      if (collabSlug !== null) {
+        if (!isLoopbackHost(req.headers.get('host'))) {
+          return new Response('cross-machine collab requires Phase 9 hub deploy', {
+            status: 403,
+          });
+        }
         const ok = srv.upgrade(req, {
           data: {
             id: crypto.randomUUID(),
             remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
+            kind: 'collab',
+            slug: collabSlug,
+          },
+        });
+        if (ok) return undefined as unknown as Response;
+        return new Response('Upgrade failed', { status: 400 });
+      }
+
+      // Legacy inspector WS — JSON frames, designer-facing live tab state.
+      if (pathname.startsWith('/_ws')) {
+        const ok = srv.upgrade(req, {
+          data: {
+            id: crypto.randomUUID(),
+            remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
+            kind: 'inspector',
           },
         });
         if (ok) return undefined as unknown as Response;
@@ -167,6 +219,21 @@ if (!process.env.NO_OPEN) {
 async function shutdown() {
   console.log('\n  Stopping…');
   fsWatch.stop();
+  try {
+    if (collab) await collab.registry.destroyAll();
+  } catch {
+    /* best-effort flush; the JSON snapshot is the ground truth anyway */
+  }
+  try {
+    aiActivity.stop();
+  } catch {
+    /* janitor cleanup is best-effort */
+  }
+  try {
+    gitLifecycle.stop();
+  } catch {
+    /* watcher cleanup is best-effort */
+  }
   try {
     await Bun.write(ctx.paths.serverInfoFile, '').catch(() => {});
     // Remove the file by writing empty then unlinking.

package/plugins/design/dev-server/test/ai-activity.test.ts

@@ -0,0 +1,113 @@
+// Unit: AI activity tracker (Phase 8 Task 4).
+
+import { describe, expect, test } from 'bun:test';
+
+import { HEARTBEAT_GRACE_MS, createAiActivity } from '../collab/ai-activity.ts';
+import { type Context, createBus } from '../context.ts';
+
+function makeCtx(): { ctx: Context; events: { file: string; entry: unknown }[] } {
+  const events: { file: string; entry: unknown }[] = [];
+  const bus = createBus();
+  bus.on('ai-activity', (p: { file: string; entry: unknown }) => events.push(p));
+  const ctx = {
+    cfg: {} as Context['cfg'],
+    projectLabel: 'test',
+    paths: {} as Context['paths'],
+    bus,
+  };
+  return { ctx, events };
+}
+
+describe('AiActivity', () => {
+  test('start adds an entry and emits bus event', () => {
+    const { ctx, events } = makeCtx();
+    const clock = 1000;
+    const ai = createAiActivity(ctx, () => clock);
+    const entry = ai.start('ui/Foo.tsx', 'Claude');
+    expect(entry.file).toBe('ui/Foo.tsx');
+    expect(entry.author).toBe('Claude');
+    expect(entry.startedAt).toBe(1000);
+    expect(entry.lastHeartbeat).toBe(1000);
+    expect(events).toHaveLength(1);
+    expect(events[0]?.entry).toBe(entry);
+    ai.stop();
+  });
+
+  test('start preserves startedAt across restart for the same file', () => {
+    const { ctx } = makeCtx();
+    let clock = 1000;
+    const ai = createAiActivity(ctx, () => clock);
+    ai.start('ui/Foo.tsx', 'Claude');
+    clock = 5000;
+    const restarted = ai.start('ui/Foo.tsx', 'Claude');
+    expect(restarted.startedAt).toBe(1000);
+    expect(restarted.lastHeartbeat).toBe(5000);
+    ai.stop();
+  });
+
+  test('heartbeat refreshes lastHeartbeat + emits', () => {
+    const { ctx, events } = makeCtx();
+    let clock = 1000;
+    const ai = createAiActivity(ctx, () => clock);
+    ai.start('ui/Foo.tsx', 'Claude');
+    clock = 2000;
+    const refreshed = ai.heartbeat('ui/Foo.tsx');
+    expect(refreshed?.lastHeartbeat).toBe(2000);
+    expect(refreshed?.startedAt).toBe(1000);
+    // Two bus events — one for start, one for heartbeat.
+    expect(events.length).toBe(2);
+    ai.stop();
+  });
+
+  test('heartbeat returns null when no entry exists', () => {
+    const { ctx } = makeCtx();
+    const ai = createAiActivity(ctx);
+    expect(ai.heartbeat('ui/Absent.tsx')).toBeNull();
+    ai.stop();
+  });
+
+  test('end clears the entry and emits a null', () => {
+    const { ctx, events } = makeCtx();
+    const clock = 1000;
+    const ai = createAiActivity(ctx, () => clock);
+    ai.start('ui/Foo.tsx', 'Claude');
+    const ok = ai.end('ui/Foo.tsx');
+    expect(ok).toBe(true);
+    expect(ai.get('ui/Foo.tsx')).toBeNull();
+    const last = events.at(-1);
+    expect(last?.entry).toBeNull();
+    ai.stop();
+  });
+
+  test('end on absent entry returns false (no emit)', () => {
+    const { ctx, events } = makeCtx();
+    const ai = createAiActivity(ctx);
+    expect(ai.end('ui/Absent.tsx')).toBe(false);
+    expect(events.length).toBe(0);
+    ai.stop();
+  });
+
+  test('list returns all live entries', () => {
+    const { ctx } = makeCtx();
+    const clock = 1000;
+    const ai = createAiActivity(ctx, () => clock);
+    ai.start('ui/Foo.tsx', 'Claude');
+    ai.start('ui/Bar.tsx', 'Claude');
+    expect(ai.list().length).toBe(2);
+    ai.end('ui/Foo.tsx');
+    expect(ai.list().length).toBe(1);
+    ai.stop();
+  });
+
+  test('grace period — entry stays inside HEARTBEAT_GRACE_MS', () => {
+    const { ctx } = makeCtx();
+    let clock = 1000;
+    const ai = createAiActivity(ctx, () => clock);
+    ai.start('ui/Foo.tsx', 'Claude');
+    // 29 s later — still within grace.
+    clock = 1000 + HEARTBEAT_GRACE_MS - 1000;
+    // We don't auto-tick the janitor in tests; just confirm entry still exists.
+    expect(ai.get('ui/Foo.tsx')).not.toBeNull();
+    ai.stop();
+  });
+});