@1agh/maude 0.19.1 → 0.21.0

package/plugins/design/dev-server/equal-spacing-detector.ts

@@ -0,0 +1,98 @@
+/**
+ * @file       equal-spacing-detector.ts — T27 (Wave 3)
+ * @scope      plugins/design/dev-server/equal-spacing-detector.ts
+ * @purpose    Pure detector for Figma "Smart Selection" pink-dot affordance
+ *             (Rasmus Andersson 2018). Given 3+ rects on a single axis,
+ *             returns the equal gap + the screen-coord midpoints between
+ *             adjacent pairs IF all pairwise gaps are within `tolerancePx`
+ *             of each other. Returns `null` when the rects are not equally
+ *             distributed.
+ *
+ *             Pure / DOM-free / framework-free — same convention as
+ *             `computeSnap` in `use-snap-guides.tsx`. The overlay layer
+ *             consumes the result and paints the pink dots.
+ *
+ *             Coordinate space is the caller's choice — pass screen-space
+ *             rects for live overlay rendering, or world-space rects for
+ *             distribute-command verification. The math is uniform either
+ *             way; only the unit of `tolerancePx` differs.
+ */
+
+import type { Rect } from './use-snap-guides.tsx';
+
+export type SpacingAxis = 'x' | 'y';
+
+export interface EqualSpacingResult {
+  axis: SpacingAxis;
+  /** The gap measured between adjacent rects (post-sort by leading edge).
+   *  Caller renders this in the distance pill above each pink dot. */
+  gapPx: number;
+  /** Midpoint coords between consecutive rects. Length = rects.length - 1.
+   *  Each entry is in caller's coord space; renderers anchor pink dots here. */
+  midpoints: Array<{ x: number; y: number }>;
+}
+
+interface DetectOptions {
+  /** How close gaps must be to count as "equal", in caller's unit (default 1). */
+  tolerancePx?: number;
+}
+
+/**
+ * Detect equal spacing along one axis. Returns `null` when:
+ *   - fewer than 3 rects (2 rects trivially have "equal" spacing — undefined).
+ *   - any pairwise gap differs from the median by more than `tolerancePx`.
+ *   - rects overlap on the spacing axis (gap < 0 anywhere).
+ *
+ * The midpoint y (for axis='x') or x (for axis='y') is the average of the
+ * adjacent rects' center on the perpendicular axis — this places the pink
+ * dot vertically centered between the two siblings, which is where the
+ * distance pill anchors above.
+ */
+export function detectEqualSpacing(
+  rects: Rect[],
+  axis: SpacingAxis,
+  opts: DetectOptions = {}
+): EqualSpacingResult | null {
+  if (rects.length < 3) return null;
+  const tol = opts.tolerancePx ?? 1;
+
+  // Sort by leading edge on the spacing axis.
+  const sorted = [...rects].sort((a, b) => (axis === 'x' ? a.x - b.x : a.y - b.y));
+
+  // Compute pairwise gaps + midpoints.
+  const gaps: number[] = [];
+  const midpoints: Array<{ x: number; y: number }> = [];
+  for (let i = 1; i < sorted.length; i++) {
+    const prev = sorted[i - 1];
+    const cur = sorted[i];
+    if (!prev || !cur) return null;
+    if (axis === 'x') {
+      const gap = cur.x - (prev.x + prev.w);
+      if (gap < 0) return null; // overlap; not a distributed set
+      gaps.push(gap);
+      midpoints.push({
+        x: prev.x + prev.w + gap / 2,
+        y: (prev.y + prev.h / 2 + (cur.y + cur.h / 2)) / 2,
+      });
+    } else {
+      const gap = cur.y - (prev.y + prev.h);
+      if (gap < 0) return null;
+      gaps.push(gap);
+      midpoints.push({
+        x: (prev.x + prev.w / 2 + (cur.x + cur.w / 2)) / 2,
+        y: prev.y + prev.h + gap / 2,
+      });
+    }
+  }
+
+  // All gaps must be within tolerance of each other. Use the median as anchor
+  // to be robust against a single outlier — though if any gap is outside the
+  // band we return null, so median vs mean is academic here.
+  const sortedGaps = [...gaps].sort((a, b) => a - b);
+  const median = sortedGaps[Math.floor(sortedGaps.length / 2)] ?? 0;
+  for (const g of gaps) {
+    if (Math.abs(g - median) > tol) return null;
+  }
+
+  return { axis, gapPx: median, midpoints };
+}

package/plugins/design/dev-server/equal-spacing-handles.tsx

@@ -0,0 +1,289 @@
+/**
+ * @file       equal-spacing-handles.tsx — T27 (Wave 3)
+ * @scope      plugins/design/dev-server/equal-spacing-handles.tsx
+ * @purpose    Figma Smart Selection pink-dot affordance. When 3+ elements are
+ *             selected AND their bounding rects are equally distributed on an
+ *             axis, render small pink dots at the midpoints between adjacent
+ *             pairs, each with a gap-distance pill above. Hover-gated:
+ *             dots are visible only while the cursor is within the union
+ *             bbox + 40 px padding — discoverable but not noisy.
+ *
+ *             Drag-to-adjust the gap is a Wave 3.x follow-up; for v1 we
+ *             paint the affordance only.
+ */
+
+import { useEffect, useRef, useState } from 'react';
+
+import {
+  type EqualSpacingResult,
+  type SpacingAxis,
+  detectEqualSpacing,
+} from './equal-spacing-detector.ts';
+import { useSelectionSet } from './use-selection-set.tsx';
+
+const HOVER_PADDING_PX = 40;
+/** Equal-spacing tolerance in screen pixels — distribute leaves 0–1 px
+ *  rounding error; 2 px is comfortably above noise without flagging
+ *  intentionally-uneven sets. */
+const EQUAL_TOLERANCE_PX = 2;
+
+const STYLES = `
+.dc-cv-eq-spacing-layer {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  z-index: 5;
+}
+.dc-cv-eq-dot {
+  position: absolute;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: #FF24BD;
+  transform: translate(-50%, -50%);
+  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.85);
+  opacity: 0;
+  transition: opacity 120ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+.dc-cv-eq-pill {
+  position: absolute;
+  transform: translate(-50%, calc(-100% - 8px));
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, monospace);
+  font-size: 10px;
+  padding: 2px 5px;
+  background: #FF24BD;
+  color: #ffffff;
+  border-radius: 2px;
+  letter-spacing: 0.02em;
+  white-space: nowrap;
+  opacity: 0;
+  transition: opacity 120ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+.dc-cv-eq-spacing-layer[data-visible="true"] .dc-cv-eq-dot,
+.dc-cv-eq-spacing-layer[data-visible="true"] .dc-cv-eq-pill {
+  opacity: 1;
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-cv-eq-dot, .dc-cv-eq-pill { transition-duration: 1ms; }
+}
+`.trim();
+
+function ensureStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-cv-eq-spacing-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-cv-eq-spacing-css';
+  s.textContent = STYLES;
+  document.head.appendChild(s);
+}
+
+function cssEscape(s: string): string {
+  // CSS.escape is available everywhere we care; manual fallback handles the
+  // jsdom test path where it may be missing.
+  // biome-ignore lint/suspicious/noExplicitAny: feature detect
+  const ce = (typeof CSS !== 'undefined' ? (CSS as any).escape : null) as
+    | ((v: string) => string)
+    | null;
+  if (ce) return ce(s);
+  return s.replace(/(["\\\]])/g, '\\$1');
+}
+
+function safeQuery(selector: string): Element | null {
+  try {
+    return document.querySelector(selector);
+  } catch {
+    return null;
+  }
+}
+
+interface ScreenRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+function resolveSelectionRects(sels: Array<{ id?: string; selector: string }>): ScreenRect[] {
+  const rects: ScreenRect[] = [];
+  for (const s of sels) {
+    const el = s.id
+      ? document.querySelector(`[data-cd-id="${cssEscape(s.id)}"]`)
+      : safeQuery(s.selector);
+    if (!el) continue;
+    const b = (el as HTMLElement).getBoundingClientRect();
+    if (b.width === 0 && b.height === 0) continue;
+    rects.push({ x: b.left, y: b.top, w: b.width, h: b.height });
+  }
+  return rects;
+}
+
+function unionBbox(rects: ScreenRect[]): ScreenRect | null {
+  if (rects.length === 0) return null;
+  let left = Number.POSITIVE_INFINITY;
+  let top = Number.POSITIVE_INFINITY;
+  let right = Number.NEGATIVE_INFINITY;
+  let bottom = Number.NEGATIVE_INFINITY;
+  for (const r of rects) {
+    if (r.x < left) left = r.x;
+    if (r.y < top) top = r.y;
+    if (r.x + r.w > right) right = r.x + r.w;
+    if (r.y + r.h > bottom) bottom = r.y + r.h;
+  }
+  return { x: left, y: top, w: right - left, h: bottom - top };
+}
+
+function pointInPaddedBox(px: number, py: number, b: ScreenRect, pad: number): boolean {
+  return px >= b.x - pad && px <= b.x + b.w + pad && py >= b.y - pad && py <= b.y + b.h + pad;
+}
+
+export function EqualSpacingHandles() {
+  ensureStyles();
+  const { selected } = useSelectionSet();
+  const layerRef = useRef<HTMLDivElement | null>(null);
+  const rafRef = useRef<number | null>(null);
+  const [hovered, setHovered] = useState(false);
+
+  // Track cursor position to gate dot visibility. We hide handles whenever
+  // the cursor leaves the (union bbox + padding) zone — discoverable on
+  // approach, invisible while the user is doing unrelated work elsewhere.
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const onMove = (e: PointerEvent) => {
+      const layer = layerRef.current;
+      if (!layer) return;
+      const dotsZone = layer.getBoundingClientRect();
+      // Layer is inset:0 in screen-fixed coords. We compare against the
+      // currently painted union bbox stored on a data attr each rAF tick.
+      const ubStr = layer.getAttribute('data-union-bbox');
+      if (!ubStr) {
+        setHovered(false);
+        return;
+      }
+      // Avoid TS-touchy split — manual parse.
+      const parts = ubStr.split(',');
+      const x = Number(parts[0]);
+      const y = Number(parts[1]);
+      const w = Number(parts[2]);
+      const h = Number(parts[3]);
+      if (Number.isNaN(x) || Number.isNaN(y)) return;
+      const inZone = pointInPaddedBox(e.clientX, e.clientY, { x, y, w, h }, HOVER_PADDING_PX);
+      if (inZone !== hovered) setHovered(inZone);
+      // Touch `dotsZone` to keep the ref-read in the dependency graph.
+      void dotsZone;
+    };
+    document.addEventListener('pointermove', onMove, { passive: true });
+    return () => document.removeEventListener('pointermove', onMove);
+  }, [hovered]);
+
+  // Resolve current selection → DOM rects → equal-spacing detector → paint.
+  // rAF loop so the affordance follows zoom + pan smoothly without React
+  // re-renders per frame.
+  useEffect(() => {
+    if (selected.length < 3) {
+      // Clear layer when selection drops below the affordance threshold.
+      const layer = layerRef.current;
+      if (layer) {
+        while (layer.firstChild) layer.removeChild(layer.firstChild);
+        layer.removeAttribute('data-union-bbox');
+      }
+      return;
+    }
+    let alive = true;
+
+    const tick = () => {
+      if (!alive) return;
+      rafRef.current = null;
+      const layer = layerRef.current;
+      if (!layer) return;
+      const rects = resolveSelectionRects(selected);
+      if (rects.length < 3) {
+        while (layer.firstChild) layer.removeChild(layer.firstChild);
+        layer.removeAttribute('data-union-bbox');
+        return;
+      }
+      // Detect on both axes; prefer the axis with the smaller relative spread
+      // (the "more confidently distributed" axis). Ties = horizontal wins.
+      const detX = detectEqualSpacing(rects, 'x', { tolerancePx: EQUAL_TOLERANCE_PX });
+      const detY = detectEqualSpacing(rects, 'y', { tolerancePx: EQUAL_TOLERANCE_PX });
+      const result = pickDetection(detX, detY);
+      if (!result) {
+        while (layer.firstChild) layer.removeChild(layer.firstChild);
+        layer.removeAttribute('data-union-bbox');
+        return;
+      }
+
+      const ub = unionBbox(rects);
+      if (ub) layer.setAttribute('data-union-bbox', `${ub.x},${ub.y},${ub.w},${ub.h}`);
+
+      paintHandles(layer, result);
+    };
+
+    const onFrame = () => {
+      if (rafRef.current != null) return;
+      rafRef.current = requestAnimationFrame(tick);
+    };
+
+    // Initial paint + continuous follow on pan/zoom/scroll.
+    onFrame();
+    const recheck = () => onFrame();
+    window.addEventListener('scroll', recheck, { passive: true, capture: true });
+    window.addEventListener('resize', recheck, { passive: true });
+    const observer = new MutationObserver(() => onFrame());
+    observer.observe(document.body, { attributes: true, subtree: true, childList: true });
+
+    return () => {
+      alive = false;
+      if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
+      window.removeEventListener('scroll', recheck, { capture: true } as EventListenerOptions);
+      window.removeEventListener('resize', recheck);
+      observer.disconnect();
+    };
+  }, [selected]);
+
+  return (
+    <div
+      ref={layerRef}
+      className="dc-cv-eq-spacing-layer"
+      data-visible={hovered ? 'true' : 'false'}
+      aria-hidden="true"
+    />
+  );
+}
+
+function pickDetection(
+  detX: EqualSpacingResult | null,
+  detY: EqualSpacingResult | null
+): EqualSpacingResult | null {
+  if (detX && detY) return detX.midpoints.length >= detY.midpoints.length ? detX : detY;
+  return detX ?? detY;
+}
+
+function paintHandles(layer: HTMLDivElement, result: EqualSpacingResult): void {
+  // Match child count to 2× midpoints (each midpoint = one dot + one pill).
+  const want = result.midpoints.length * 2;
+  while (layer.children.length < want) {
+    const isDot = layer.children.length % 2 === 0;
+    const node = document.createElement('div');
+    node.className = isDot ? 'dc-cv-eq-dot' : 'dc-cv-eq-pill';
+    if (!isDot) node.textContent = '';
+    layer.appendChild(node);
+  }
+  while (layer.children.length > want) {
+    layer.removeChild(layer.lastChild as Node);
+  }
+  const label = `${Math.round(result.gapPx)}`;
+  for (let i = 0; i < result.midpoints.length; i++) {
+    const m = result.midpoints[i];
+    if (!m) continue;
+    const dot = layer.children[i * 2] as HTMLDivElement;
+    const pill = layer.children[i * 2 + 1] as HTMLDivElement;
+    dot.style.left = `${m.x}px`;
+    dot.style.top = `${m.y}px`;
+    pill.style.left = `${m.x}px`;
+    pill.style.top = `${m.y}px`;
+    pill.textContent = label;
+  }
+}
+
+// Re-export the picker for tests.
+export { pickDetection };

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/handoff.ts

@@ -554,6 +554,16 @@ export async function emitRegistryItem(opts: EmitOptions): Promise<RegistryItem>
   // The trick: replace `DesignCanvas`, `DCArtboard`, `DCSection` in the
   // libMap with their static-frame variants before BFS. The static variants
   // have empty deps, so the transitive walk never reaches the engine code.
+  //
+  // Phase 3.7 / DDR-049 — motion helpers (MotionDemo, MotionTrack,
+  // TokenPlayback, ReducedMotionToggle, useMotionTokens, easingFromToken)
+  // depend on aliased imports from motion/react (_motionImpl,
+  // _useReducedMotion, _MotionAnimatePresence). When any of those land in the
+  // inlined output, splice the matching motion/react import line at the file
+  // head AND force-add "motion" to the registry-item's dependencies. The
+  // consumer's npm install + Next.js bundler resolves motion → bunx shadcn
+  // add lands an animated component with zero manual wiring.
+  let motionUsed = false;
   if (opts.designRoot) {
     const libPath = canvasLibPath(opts.designRoot);
     const libFile = Bun.file(libPath);
@@ -563,6 +573,19 @@ export async function emitRegistryItem(opts: EmitOptions): Promise<RegistryItem>
       applyHandoffStaticOverrides(libMap);
       const inlined = inlineUsedExports(tsx, libMap);
       tsx = inlined.content;
+      // Detect motion-helper usage from the inlined surface (the body refs
+      // _motionImpl / _useReducedMotion / _MotionAnimatePresence). We probe
+      // the post-inline source so we don't false-positive on a canvas that
+      // imports a non-motion helper sharing a name prefix.
+      motionUsed =
+        /\b_motionImpl\b/.test(tsx) ||
+        /\b_useReducedMotion\b/.test(tsx) ||
+        /\b_MotionAnimatePresence\b/.test(tsx);
+      if (motionUsed) {
+        const motionImport =
+          "import { motion as _motionImpl, useReducedMotion as _useReducedMotion, AnimatePresence as _MotionAnimatePresence } from 'motion/react';\n";
+        tsx = `${motionImport}${tsx}`;
+      }
     }
   }
 
@@ -578,6 +601,7 @@ export async function emitRegistryItem(opts: EmitOptions): Promise<RegistryItem>
   const depSet = new Set(depsFiltered);
   depSet.add('react');
   depSet.add('react-dom');
+  if (motionUsed) depSet.add('motion');
   const finalDeps = [...depSet].sort();
 
   // Compute slug for `name` field — kebab-case of the file stem.

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
@@ -192,6 +193,33 @@ export function createHttp(ctx: Context, api: Api, inspect: Inspect): Http {
   }
   void libWatcher;
 
+  // G7v2 — canvas-lib.tsx transitively imports many dev-server siblings
+  // (canvas-shell, contextual-toolbar, equal-spacing-handles, ...). Editing
+  // any of them invalidates the bundled canvas output. Without watching them
+  // the mtime-keyed `canvasCache` keeps serving the stale bundle and the
+  // user sees pre-edit behaviour even after a hard iframe reload.
+  //
+  // Recursive watch over DEV_SERVER_ROOT, filtered to .tsx — server-only .ts
+  // (api / http / context / etc.) doesn't reach the canvas. Test files
+  // (`test/`) and built output (`dist/`, `client/`) also skipped.
+  let devSrcWatcher: ReturnType<typeof watch> | null = null;
+  try {
+    devSrcWatcher = watch(DEV_SERVER_ROOT, { recursive: true }, (_evt, filename) => {
+      if (!filename) return;
+      if (!filename.endsWith('.tsx')) return;
+      if (filename.startsWith('test/') || filename.startsWith('test\\')) return;
+      if (filename.startsWith('dist/') || filename.startsWith('client/')) return;
+      canvasCache.clear();
+      ctx.bus.emit('fs:any', `_lib/${filename}`);
+    });
+  } catch (err) {
+    console.warn(
+      '[dev-server-src] failed to watch source tree:',
+      err instanceof Error ? err.message : err
+    );
+  }
+  void devSrcWatcher;
+
   async function readJson<T = unknown>(req: Request, max = 256 * 1024): Promise<T | null> {
     try {
       const text = await req.text();
@@ -279,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)