@1agh/maude 0.26.0 → 0.28.0

package/plugins/design/dev-server/use-agent-presence.tsx

@@ -0,0 +1,244 @@
+/**
+ * @file       use-agent-presence.tsx — Phase 13.2 / DDR-078 agent presence.
+ * @scope      plugins/design/dev-server/use-agent-presence.tsx
+ * @purpose    Turn the Phase 8 `ai-activity` heartbeat into a *presence* peer:
+ *             when an agent (`/design:edit` / `/design:new`) is editing THIS
+ *             canvas, surface it like another connected human — an avatar in the
+ *             participants stack + the activity overlay (DDR-075) tinted with the
+ *             agent's own color + funny name. Pure client-side synthesis: the
+ *             agent is NOT injected into Yjs awareness (no protocol surgery), it
+ *             is a virtual participant derived from `ai-activity`.
+ *
+ * MVP scope (DDR-078): ONE agent per canvas (matches `ai-activity`'s file key).
+ * Multiple agents across the project each show in their own canvas tab; multiple
+ * agents on the SAME file at once would need `ai-activity` multi-author and is
+ * deliberately deferred. No roaming cursor (avatar + overlay only).
+ *
+ * Subscription mirrors `ai-banner.tsx`: parent `dgn:'ai-activity'` postMessage
+ * relay when embedded, own inspector WS when standalone, plus a GET /_api/ai
+ * seed so a tab opened mid-edit shows the agent immediately. Provided ONCE per
+ * canvas (canvas-lib bundle) so every DCArtboard + the chrome read one context —
+ * same cross-bundle rule as the activity context (DDR-077 lesson).
+ */
+
+import { type ReactNode, createContext, useContext, useEffect, useMemo, useState } from 'react';
+
+import { colorForName } from './use-collab.tsx';
+
+/** Wire shape of an `ai-activity` entry (matches collab/ai-activity.ts). */
+export interface AiEntry {
+  file: string;
+  author: string;
+  startedAt: number;
+  lastHeartbeat: number;
+}
+
+/** A virtual presence peer derived from an active agent. */
+export interface AgentPresence {
+  /** Stable per-session id (`author:startedAt`) — the funny-name + color seed. */
+  id: string;
+  /** Funny display name, e.g. "Bouncy Otter". */
+  name: string;
+  /** Deterministic peer color (shared palette with human peers). */
+  color: string;
+  /** The real author string the slash command reported ("Claude acting for X"). */
+  author: string;
+  startedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Funny-name generator — deterministic from the session seed so an agent keeps
+// the same name + color across heartbeats. ~20×20 = 400 combinations.
+
+const ADJECTIVES = [
+  'Bouncy',
+  'Zippy',
+  'Sleepy',
+  'Sneaky',
+  'Witty',
+  'Plucky',
+  'Mellow',
+  'Snappy',
+  'Cosmic',
+  'Fuzzy',
+  'Jolly',
+  'Nimble',
+  'Breezy',
+  'Quirky',
+  'Dapper',
+  'Wobbly',
+  'Spry',
+  'Peppy',
+  'Groovy',
+  'Sly',
+];
+
+const ANIMALS = [
+  'Otter',
+  'Walrus',
+  'Lynx',
+  'Heron',
+  'Badger',
+  'Falcon',
+  'Mantis',
+  'Newt',
+  'Quokka',
+  'Tapir',
+  'Gecko',
+  'Marten',
+  'Pangolin',
+  'Axolotl',
+  'Ferret',
+  'Puffin',
+  'Capybara',
+  'Narwhal',
+  'Wombat',
+  'Mongoose',
+];
+
+function hash32(s: string): number {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return h >>> 0;
+}
+
+/** Deterministic "Adjective Animal" from a seed (e.g. `author:startedAt`). */
+export function agentFunnyName(seed: string): string {
+  const h = hash32(seed || 'agent');
+  const adj = ADJECTIVES[h % ADJECTIVES.length] as string;
+  const animal = ANIMALS[(h >>> 8) % ANIMALS.length] as string;
+  return `${adj} ${animal}`;
+}
+
+/**
+ * Strip control chars + length-cap the author. The /_api/ai/start endpoint
+ * caps it server-side, but the postMessage relay path never round-trips the
+ * server, so we re-bound it here at the trust boundary (DDR-078 security
+ * follow-up) — keeps a spoofed `author` from bloating the badge even if the
+ * origin guard below ever regresses.
+ */
+function sanitizeAuthor(a: unknown): string {
+  // Keep printable chars only (drop C0/C1 controls + DEL), cap length — no
+  // control-char regex needed.
+  let out = '';
+  for (const ch of String(a ?? '')) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code >= 0x20 && code !== 0x7f) out += ch;
+    if (out.length >= 120) break;
+  }
+  return out;
+}
+
+/** Build the virtual presence peer from an `ai-activity` entry. */
+export function deriveAgent(entry: AiEntry): AgentPresence {
+  const author = sanitizeAuthor(entry.author);
+  const id = `${author}:${entry.startedAt}`;
+  const name = agentFunnyName(id);
+  return { id, name, color: colorForName(name), author, startedAt: entry.startedAt };
+}
+
+// ---------------------------------------------------------------------------
+
+function readMetaFile(explicit?: string): string {
+  if (explicit) return explicit;
+  if (typeof window !== 'undefined') {
+    const w = window as unknown as { __canvas_meta_file__?: string };
+    if (typeof w.__canvas_meta_file__ === 'string') return w.__canvas_meta_file__;
+  }
+  return '';
+}
+
+const AgentPresenceContext = createContext<AgentPresence | null>(null);
+
+export interface AgentPresenceProviderProps {
+  /** Canvas file key (designRel-prefixed, matching the `ai-activity` key). */
+  file?: string;
+  /** Test/seed override — when provided, the live subscription is skipped. */
+  initialAgent?: AgentPresence | null;
+  children: ReactNode;
+}
+
+export function AgentPresenceProvider({
+  file,
+  initialAgent,
+  children,
+}: AgentPresenceProviderProps) {
+  const myFile = readMetaFile(file);
+  const [entry, setEntry] = useState<AiEntry | null>(null);
+
+  useEffect(() => {
+    if (initialAgent !== undefined) return; // seeded (tests) — no live wiring
+    if (!myFile || typeof window === 'undefined') return;
+    let cancelled = false;
+
+    // Seed: a tab opened mid-edit should show the agent without waiting for the
+    // next heartbeat.
+    fetch('/_api/ai', { headers: { 'Cache-Control': 'no-store' } })
+      .then((r) => (r.ok ? r.json() : null))
+      .then((j: { entries?: AiEntry[] } | null) => {
+        if (cancelled || !j?.entries) return;
+        const mine = j.entries.find((e) => e && e.file === myFile);
+        if (mine) setEntry(mine);
+      })
+      .catch(() => {
+        /* network blip — live messages will fill in */
+      });
+
+    // Embedded: parent relays ai-activity via postMessage (ai-banner pattern).
+    const onMessage = (e: MessageEvent) => {
+      // DDR-078 security follow-up: only the trusted embedding parent relays
+      // ai-activity. Reject same-window self-posts (a hostile canvas faking a
+      // "Claude is editing" identity) and any non-parent source. Standalone
+      // (no parent) receives ai-activity via its own WS, never via postMessage.
+      if (e.source !== window.parent || window.parent === window) return;
+      const m = e.data as { dgn?: string; file?: string; entry?: AiEntry | null } | null;
+      if (!m || typeof m !== 'object' || m.dgn !== 'ai-activity') return;
+      if (m.file !== myFile) return;
+      setEntry(m.entry ?? null);
+    };
+    window.addEventListener('message', onMessage);
+
+    // Standalone (no embedding parent): dial the inspector WS ourselves.
+    let ws: WebSocket | null = null;
+    let reconnect: ReturnType<typeof setTimeout> | null = null;
+    function connectStandalone() {
+      const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+      const sock = new WebSocket(`${proto}//${location.host}/_ws`);
+      ws = sock;
+      sock.addEventListener('message', (ev) => {
+        try {
+          if (typeof ev.data !== 'string') return;
+          const m = JSON.parse(ev.data) as { type?: string; file?: string; entry?: AiEntry | null };
+          if (m.type !== 'ai-activity' || m.file !== myFile) return;
+          setEntry(m.entry ?? null);
+        } catch {
+          /* binary collab frame — ignore */
+        }
+      });
+      sock.addEventListener('close', () => {
+        ws = null;
+        reconnect = setTimeout(connectStandalone, 2000);
+      });
+    }
+    if (window.parent === window) connectStandalone();
+
+    return () => {
+      cancelled = true;
+      window.removeEventListener('message', onMessage);
+      if (reconnect) clearTimeout(reconnect);
+      ws?.close();
+    };
+  }, [myFile, initialAgent]);
+
+  const agent = useMemo<AgentPresence | null>(() => {
+    if (initialAgent !== undefined) return initialAgent;
+    return entry ? deriveAgent(entry) : null;
+  }, [entry, initialAgent]);
+
+  return <AgentPresenceContext.Provider value={agent}>{children}</AgentPresenceContext.Provider>;
+}
+
+/** The agent currently editing this canvas, or null. Inert outside the provider. */
+export function useAgentPresence(): AgentPresence | null {
+  return useContext(AgentPresenceContext);
+}

package/plugins/design/dev-server/use-canvas-activity.tsx

@@ -0,0 +1,252 @@
+/**
+ * @file       use-canvas-activity.tsx — Phase 13 / DDR-029 activity context.
+ * @scope      plugins/design/dev-server/use-canvas-activity.tsx
+ * @purpose    Iframe-runtime React context fed by the server's `activity` WS
+ *             messages. `DCArtboard` reads it to render the "agent works here"
+ *             overlay on the artboards being edited right now.
+ *
+ * The bridge: the canvas-shell harness (`templates/_shell.html`) owns the WS
+ * connection and re-dispatches every `{ type:'activity', … }` message as a
+ * `maude:activity` CustomEvent on `document` (the same pattern used for
+ * `maude:meta-refreshed`). This provider subscribes to that event — no second
+ * socket, and trivially testable (dispatch the event in a test). In-memory only:
+ * activity is ephemeral, never persisted.
+ */
+
+import {
+  type ReactNode,
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+/** Cross-fade window after a file flips `idle` before its overlay is removed. */
+export const ACTIVITY_FADE_MS = 200;
+
+/** Wire shape of a server `activity` message (snake_case, matches activity.ts). */
+export interface ActivityMessage {
+  type?: 'activity';
+  file: string;
+  status: 'active' | 'idle';
+  artboard_ids?: string[] | null;
+  ts: string;
+}
+
+interface ActivityEntry {
+  status: 'active' | 'idle';
+  artboardIds: string[] | null;
+  ts: string;
+}
+
+type ActivityMap = Record<string, ActivityEntry>;
+
+/** What `useCanvasActivity()` returns for a given canvas file. */
+export interface CanvasActivity {
+  /** An entry exists (file is active OR within the post-idle fade window). */
+  present: boolean;
+  /** The file is currently being edited (drives the pulse). */
+  active: boolean;
+  /** Scoped artboard ids, or null = file-level (every artboard lights up). */
+  artboardIds: string[] | null;
+  /** Basename of the canvas file, for the badge label. */
+  fileLabel: string;
+}
+
+interface ActivityContextValue {
+  map: ActivityMap;
+  /** This canvas's design-root-relative key (server-message keyspace). */
+  currentKey: string;
+  normalizeKey: (file: string) => string;
+}
+
+const ActivityContext = createContext<ActivityContextValue | null>(null);
+
+// ---------------------------------------------------------------------------
+// Pure helpers — exported for unit tests.
+
+/**
+ * Normalize a canvas path to the server's activity keyspace: design-root-
+ * relative, slash-normalized, no leading slash. Accepts the canonical form
+ * (`ui/Foo.tsx`) or the designRel-prefixed form (`.design/ui/Foo.tsx`) that
+ * `mountCanvas` passes — stripping `designRel` when known.
+ */
+export function activityKey(file: string, designRel?: string): string {
+  let s = (file ?? '').replace(/\\/g, '/').replace(/^\/+/, '');
+  const dr = (designRel ?? '').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
+  if (dr && s.startsWith(`${dr}/`)) s = s.slice(dr.length + 1);
+  return s;
+}
+
+/** Pure reducer: fold one activity message into the map. */
+export function applyActivityChange(prev: ActivityMap, change: ActivityMessage): ActivityMap {
+  if (!change || typeof change.file !== 'string' || !change.file) return prev;
+  return {
+    ...prev,
+    [change.file]: {
+      status: change.status === 'active' ? 'active' : 'idle',
+      artboardIds: Array.isArray(change.artboard_ids) ? change.artboard_ids : null,
+      ts: typeof change.ts === 'string' ? change.ts : '',
+    },
+  };
+}
+
+/** True when an artboard id is in scope for a change (null scope = all). */
+export function matchesArtboard(artboardIds: string[] | null, id: string): boolean {
+  return artboardIds === null || artboardIds.includes(id);
+}
+
+function basename(key: string): string {
+  const i = key.lastIndexOf('/');
+  return i >= 0 ? key.slice(i + 1) : key;
+}
+
+function readDesignRel(explicit?: string): string | undefined {
+  if (explicit) return explicit;
+  if (typeof window !== 'undefined') {
+    const w = window as unknown as { __canvas_design_rel__?: string };
+    if (typeof w.__canvas_design_rel__ === 'string') return w.__canvas_design_rel__;
+  }
+  return undefined;
+}
+
+/**
+ * Seed the map from `window.__maude_activity_seed__` — the WS-open snapshot the
+ * shell stashes (raw server `activity.state`, keyed design-root-relative with a
+ * camelCase `artboardIds`). Load-bearing after the HMR reload a canvas edit
+ * triggers: the snapshot can land before React mounts, so the dispatched event
+ * is missed and only this synchronous read recovers the in-flight overlay.
+ */
+function readActivitySeed(): ActivityMap {
+  if (typeof window === 'undefined') return {};
+  const w = window as unknown as {
+    __maude_activity_seed__?: Record<
+      string,
+      { status?: 'active' | 'idle'; ts?: string; artboardIds?: string[] | null }
+    >;
+  };
+  const seed = w.__maude_activity_seed__;
+  if (!seed || typeof seed !== 'object') return {};
+  const out: ActivityMap = {};
+  for (const file of Object.keys(seed)) {
+    const e = seed[file];
+    if (!e || e.status !== 'active') continue; // only resurrect active overlays
+    out[file] = {
+      status: 'active',
+      artboardIds: Array.isArray(e.artboardIds) ? e.artboardIds : null,
+      ts: typeof e.ts === 'string' ? e.ts : '',
+    };
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+
+export interface CanvasActivityProviderProps {
+  /** This canvas's file (designRel-prefixed or design-root-relative). */
+  file?: string;
+  /** designRel for key normalization; defaults to `window.__canvas_design_rel__`. */
+  designRel?: string;
+  /** Seed (snapshot / tests). Keyed by design-root-relative path. */
+  initialState?: ActivityMap;
+  children: ReactNode;
+}
+
+export function CanvasActivityProvider({
+  file,
+  designRel,
+  initialState,
+  children,
+}: CanvasActivityProviderProps) {
+  const dr = readDesignRel(designRel);
+  const currentKey = useMemo(() => {
+    if (file) return activityKey(file, dr);
+    // No explicit file (the canvas-lib mount path) → read the design-root-
+    // relative canvas path the shell stamps on window. It already matches the
+    // server's activity keyspace, so no normalization is needed.
+    if (typeof window !== 'undefined') {
+      const w = window as unknown as { __canvas_rel__?: string };
+      if (typeof w.__canvas_rel__ === 'string' && w.__canvas_rel__) return w.__canvas_rel__;
+    }
+    return '';
+  }, [file, dr]);
+  const [map, setMap] = useState<ActivityMap>(() => initialState ?? readActivitySeed());
+  // Per-file removal timers for the post-idle cross-fade.
+  const fadeTimers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const timers = fadeTimers.current;
+
+    function onActivity(ev: Event) {
+      const detail = (ev as CustomEvent<ActivityMessage>).detail;
+      if (!detail || typeof detail.file !== 'string') return;
+      setMap((prev) => applyActivityChange(prev, detail));
+
+      const pending = timers.get(detail.file);
+      if (pending) {
+        clearTimeout(pending);
+        timers.delete(detail.file);
+      }
+      if (detail.status === 'idle') {
+        // Keep the (now-idle) entry around briefly so the overlay cross-fades
+        // out instead of snapping off, then drop it.
+        const ts = detail.ts;
+        const t = setTimeout(() => {
+          timers.delete(detail.file);
+          setMap((prev) => {
+            const entry = prev[detail.file];
+            // Only remove if it's still the same idle entry (not re-activated).
+            if (!entry || entry.status !== 'idle' || entry.ts !== ts) return prev;
+            const { [detail.file]: _drop, ...rest } = prev;
+            return rest;
+          });
+        }, ACTIVITY_FADE_MS);
+        timers.set(detail.file, t);
+      }
+    }
+
+    document.addEventListener('maude:activity', onActivity as EventListener);
+    return () => {
+      document.removeEventListener('maude:activity', onActivity as EventListener);
+      for (const t of timers.values()) clearTimeout(t);
+      timers.clear();
+    };
+  }, []);
+
+  const value = useMemo<ActivityContextValue>(
+    () => ({ map, currentKey, normalizeKey: (f: string) => activityKey(f, dr) }),
+    [map, currentKey, dr]
+  );
+
+  return <ActivityContext.Provider value={value}>{children}</ActivityContext.Provider>;
+}
+
+const EMPTY: CanvasActivity = {
+  present: false,
+  active: false,
+  artboardIds: null,
+  fileLabel: '',
+};
+
+/**
+ * Activity state for a canvas. With no argument, returns the current canvas's
+ * activity (the provider knows its own file); pass a `file` to query another.
+ * Returns an inert value outside the provider (legacy / specimen mounts), so the
+ * overlay simply never renders there.
+ */
+export function useCanvasActivity(file?: string): CanvasActivity {
+  const ctx = useContext(ActivityContext);
+  if (!ctx) return EMPTY;
+  const key = file != null ? ctx.normalizeKey(file) : ctx.currentKey;
+  if (!key) return EMPTY;
+  const entry = ctx.map[key];
+  return {
+    present: !!entry,
+    active: entry?.status === 'active',
+    artboardIds: entry?.artboardIds ?? null,
+    fileLabel: basename(key),
+  };
+}

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

@@ -3,6 +3,7 @@
 
 import type { ServerWebSocket, WebSocketHandler } from 'bun';
 
+import type { Activity } from './activity.ts';
 import type { Api } from './api.ts';
 import type { Collab, RoomConn } from './collab/index.ts';
 import type { Context } from './context.ts';
@@ -76,7 +77,13 @@ export interface Ws {
   clientCount(): number;
 }
 
-export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Collab): Ws {
+export function createWs(
+  ctx: Context,
+  api: Api,
+  inspect: Inspect,
+  collab: Collab,
+  activity: Activity
+): Ws {
   const clients = new Set<ServerWebSocket<WsData>>();
 
   function send(ws: ServerWebSocket<WsData>, payload: unknown) {
@@ -141,6 +148,14 @@ export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Colla
   // Uses broadcastHmr so the segregated canvas origin's HMR-only sockets get it.
   createHmrBroadcaster(ctx, (msg) => broadcastHmr(msg));
 
+  // Phase 13 / DDR-029 — canvas activity overlay. activity.ts emits
+  // `activity:change` per file as edits land + go idle. The overlay renders
+  // INSIDE the canvas iframe, which (with the default origin split, DDR-054)
+  // holds a `canvas-hmr` socket — so this MUST use broadcastHmr, not broadcast,
+  // to reach it. The payload is just a canvas path + status (no secrets); it's
+  // the same exposure class the iframe already gets from `canvas-hmr` file paths.
+  ctx.bus.on('activity:change', (payload) => broadcastHmr({ type: 'activity', ...payload }));
+
   // Bind a connection to its room. Stored per-socket so close() can find the
   // right room to disconnect from. Multiplexed via ws.data.id.
   const collabConns = new Map<string, { roomSlug: string; conn: RoomConn }>();
@@ -175,7 +190,11 @@ export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Colla
         return;
       }
       clients.add(ws);
-      send(ws, { type: 'snapshot', state: inspect.state });
+      // Snapshot carries the inspector state AND the activity map so a client
+      // opening mid-edit seeds its overlay state (Phase 13). Inspector-origin
+      // sockets only — `canvas-hmr` sockets get no snapshot by design and rely
+      // on live `activity` broadcasts.
+      send(ws, { type: 'snapshot', state: inspect.state, activity: activity.state });
     },
     async close(ws) {
       if (ws.data.kind === 'collab') {