@1agh/maude 0.27.0 → 0.28.0

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') {

package/plugins/design/templates/_shell.html

@@ -110,6 +110,10 @@
       /* HUDs + banners */
       .dc-ai-banner,
       .dc-undo-hud,
+      /* Activity overlay — live "agent works here" chrome (Phase 13 / DDR-029) */
+      .dc-activity-rim,
+      /* HMR "holding last good" toast (Phase 13.1 / DDR-077) */
+      .dc-hmr-holding,
       /* Artboard title/label button (editor affordance, not design content) */
       .dc-artboard-label,
       /* Generic opt-in hooks for any future floating overlay */
@@ -162,6 +166,52 @@
       const tokensRel = stripDesignPrefix(params.get('tokens') || '');
       const componentsRel = stripDesignPrefix(params.get('components') || '');
       const layoutRel = stripDesignPrefix(params.get('layout') || '');
+
+      // Phase 13.1 / DDR-077 — error-resilient HMR while an agent edits. Hoisted
+      // here so the HMR client (below) can soft-reload the canvas module instead
+      // of location.reload()-ing into a half-saved (broken) build.
+      const canvasUrl = canvasRel ? ('/' + designRel + '/' + canvasRel) : null;
+      const myFileKey = canvasRel ? (designRel + '/' + canvasRel) : null;
+      // True while an `ai-activity` entry is live for THIS canvas (an agent is
+      // running /design:edit|new on it). Mirrors ai-banner's gate: parent relays
+      // ai-activity via postMessage when embedded; the own-WS path (standalone /
+      // same-origin inspector socket) is handled in connectHmr below.
+      let agentEditing = false;
+      window.addEventListener('message', function (e) {
+        // DDR-078 security follow-up: only the trusted embedding parent relays
+        // ai-activity. Reject canvas self-posts (which could flip the HMR gate)
+        // and any non-parent source. Standalone gets it via its own WS below.
+        if (e.source !== window.parent || window.parent === window) return;
+        const m = e && e.data;
+        if (!m || typeof m !== 'object' || m.dgn !== 'ai-activity') return;
+        if (myFileKey && m.file === myFileKey) agentEditing = !!m.entry;
+      });
+
+      // Soft reload — re-import the canvas module (cache-busted) and swap it in
+      // via the runtime, holding the last good render on a build/import error
+      // (no white flash). Only used when an agent is editing; manual edits keep
+      // the plain location.reload() below.
+      function softReload(version) {
+        if (!canvasUrl) { location.reload(); return; }
+        const rt = window.__maudeCanvasRuntime;
+        if (!rt || !rt.remount) { location.reload(); return; }
+        import(canvasUrl + '?v=' + (version || Date.now()))
+          .then(function (mod) {
+            if (mod && typeof mod.default === 'function') {
+              rt.remount(mod.default);
+              if (rt.setHolding) rt.setHolding(false);
+            } else {
+              // No usable default export (rare) — fall back to a hard reload.
+              location.reload();
+            }
+          })
+          .catch(function (err) {
+            // Build/transpile/import error → keep the current render, surface a
+            // non-destructive "holding" toast. Next good build swaps it in.
+            if (rt.setHolding) rt.setHolding(true, (err && (err.message || String(err))) || 'build error');
+            console.warn('[canvas-shell] soft-reload held last good (build error):', err);
+          });
+      }
       // Phase 6.5 — exporters pass ?hide-chrome=1 to flip the export-mode
       // stylesheet from `media="not all"` to `media="all"`, hiding the
       // dev-server overlays during capture. See `<style id="canvas-hide-chrome">`.
@@ -192,7 +242,55 @@
         ws.addEventListener('message', (ev) => {
           try {
             const msg = JSON.parse(ev.data);
-            if (!msg || msg.type !== 'canvas-hmr') return;
+            if (!msg) return;
+            // Phase 13.1 / DDR-077 — own-WS path for the agent-active gate (this
+            // socket is the inspector channel in standalone / same-origin mode;
+            // embedded canvas-hmr sockets get ai-activity via the parent's
+            // postMessage relay handled above).
+            if (msg.type === 'ai-activity') {
+              if (myFileKey && msg.file === myFileKey) agentEditing = !!msg.entry;
+              return;
+            }
+            // Phase 13 / DDR-029 — canvas activity overlay. The server pushes
+            // `{ type:'activity', file, status, artboard_ids, ts }` as edits land
+            // + go idle; the injected runtime (use-canvas-activity.tsx) listens
+            // for the `maude:activity` document event. Same-document bridge — no
+            // second socket. The `snapshot` seed re-plays the activity map for a
+            // tab that opens mid-edit (inspector-origin only).
+            if (msg.type === 'activity') {
+              // Maintain a running activity seed (shape matches the snapshot's
+              // `activity.state`: camelCase artboardIds). Load-bearing for the
+              // Phase 13.1 soft-reload: a soft remount resets the activity
+              // provider WITHOUT a page reload (so no fresh snapshot), and the
+              // provider re-seeds from this map — without it the overlay would
+              // vanish on every agent .tsx save.
+              if (!window.__maude_activity_seed__) window.__maude_activity_seed__ = {};
+              if (msg.status === 'active') {
+                window.__maude_activity_seed__[msg.file] = {
+                  status: 'active', artboardIds: msg.artboard_ids || null, ts: msg.ts,
+                };
+              } else {
+                delete window.__maude_activity_seed__[msg.file];
+              }
+              document.dispatchEvent(new CustomEvent('maude:activity', { detail: msg }));
+              return;
+            }
+            if (msg.type === 'snapshot' && msg.activity && typeof msg.activity === 'object') {
+              // Stash so the provider can seed on mount even if it isn't listening
+              // yet (the snapshot can arrive before React mounts — a real race
+              // after the HMR reload that a canvas edit triggers). Also dispatch
+              // for any provider that IS already mounted (same-origin live case).
+              window.__maude_activity_seed__ = msg.activity;
+              for (const file in msg.activity) {
+                const e = msg.activity[file];
+                if (!e) continue;
+                document.dispatchEvent(new CustomEvent('maude:activity', {
+                  detail: { type: 'activity', file: file, status: e.status, artboard_ids: e.artboardIds || null, ts: e.ts },
+                }));
+              }
+              return;
+            }
+            if (msg.type !== 'canvas-hmr') return;
             if (msg.mode === 'css') {
               const v = msg.version || Date.now();
               // Match by exact filename when we have one; otherwise refresh all.
@@ -222,7 +320,14 @@
             } else if (msg.mode === 'module' || msg.mode === 'hard') {
               // Only reload when the change touches *this* canvas (or `_lib`).
               if (msg.mode === 'hard' || !msg.file || (canvasRel && msg.file === canvasRel)) {
-                location.reload();
+                // Phase 13.1 / DDR-077 — when an agent is live-editing, soft-
+                // reload (hold last good on a broken intermediate). Manual edits
+                // (or no runtime yet) keep the plain, immediate hard reload.
+                if (agentEditing && window.__maudeCanvasRuntime && window.__maudeCanvasRuntime.remount) {
+                  softReload(msg.version);
+                } else {
+                  location.reload();
+                }
               }
             } else if (msg.mode === 'meta') {
               // Phase 8 — canvas-meta sidecar changed. Filter to our own canvas:
@@ -276,7 +381,7 @@
           document.head.appendChild(layoutLink);
         }
 
-        const canvasUrl = '/' + designRel + '/' + canvasRel;
+        // canvasUrl is hoisted above (Phase 13.1) so the HMR soft-reload can use it.
         // Phase 4 T5 — read the canvas's sibling .meta.json and stash it on
         // window so DesignCanvas can seed `layout` + `viewport` synchronously.
         // The fetch runs in parallel with imports; failure is non-fatal (the