@1agh/maude 0.22.2 → 0.23.0

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

@@ -0,0 +1,156 @@
+/**
+ * @file       dom-selection.ts — selection-from-DOM helpers (leaf module)
+ * @scope      plugins/design/dev-server/dom-selection.ts
+ * @purpose    Pure DOM → Selection builders shared by the canvas chrome
+ *             (canvas-shell.tsx) and the shell-owned comment mount layer
+ *             (canvas-comment-mount.tsx). Lives in its own leaf module — no
+ *             React, no canvas-lib import — so both consumers can lift the
+ *             same `hoverTargetToSelection` / `deriveFile` logic without a
+ *             cycle and without bundling the heavy DesignCanvas tree into the
+ *             lite comment mount.
+ */
+
+import type { HoverTarget } from './input-router.tsx';
+import type { Selection } from './use-selection-set.tsx';
+
+/**
+ * Canvas file path for the current page. Under the mount harness the page is
+ * `/_canvas-shell.html?canvas=<rel>&designRel=<root>`; for legacy `.html`
+ * mocks it's the served file path itself.
+ */
+export function deriveFile(): string | undefined {
+  if (typeof window === 'undefined') return undefined;
+  try {
+    const p = window.location.pathname;
+    if (p === '/_canvas-shell.html' || p === '/_canvas-shell') {
+      const qs = new URLSearchParams(window.location.search);
+      const canvas = qs.get('canvas') ?? '';
+      const designRel = (qs.get('designRel') ?? '.design').replace(/^\/+|\/+$/g, '');
+      return canvas ? `${designRel}/${canvas}` : undefined;
+    }
+    return decodeURIComponent(p).replace(/^\//, '');
+  } catch {
+    return undefined;
+  }
+}
+
+export function realClasses(el: Element | null): string {
+  if (!el) return '';
+  return (el.getAttribute('class') ?? '')
+    .trim()
+    .split(/\s+/)
+    .filter((c) => c && !c.startsWith('dgn-') && !c.startsWith('dc-cv-'))
+    .join(' ');
+}
+
+export function shortText(el: Element | null, max: number): string {
+  if (!el) return '';
+  const t = ((el as HTMLElement).innerText || el.textContent || '').replace(/\s+/g, ' ').trim();
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+export function cssPath(el: Element | null): string {
+  if (!el) return '';
+  const path: string[] = [];
+  let cur: Element | null = el;
+  while (cur && cur.nodeType === 1 && path.length < 8) {
+    const dscEl = cur.getAttribute?.('data-dc-element');
+    if (dscEl) {
+      path.unshift(`[data-dc-element="${dscEl}"]`);
+      break;
+    }
+    const dscSc = cur.getAttribute?.('data-dc-screen');
+    if (dscSc) {
+      path.unshift(`[data-dc-screen="${dscSc}"]`);
+      break;
+    }
+    let sel = cur.nodeName.toLowerCase();
+    if (cur.id) {
+      sel = `#${cur.id}`;
+      path.unshift(sel);
+      break;
+    }
+    const cls = realClasses(cur).split(/\s+/).filter(Boolean).slice(0, 2);
+    if (cls.length) sel += `.${cls.join('.')}`;
+    let sib = 1;
+    let n: Element | null = cur.previousElementSibling;
+    while (n) {
+      sib++;
+      n = n.previousElementSibling;
+    }
+    sel += `:nth-child(${sib})`;
+    path.unshift(sel);
+    cur = cur.parentElement;
+  }
+  return path.join(' > ');
+}
+
+export function domPath(el: Element | null): string[] {
+  const hops: string[] = [];
+  let cur = el;
+  while (cur && cur.nodeType === 1 && hops.length < 8) {
+    let label = cur.nodeName.toLowerCase();
+    const dEl = cur.getAttribute?.('data-dc-element');
+    const dSc = cur.getAttribute?.('data-dc-screen');
+    if (dEl) label += `[data-dc-element="${dEl}"]`;
+    else if (dSc) label += `[data-dc-screen="${dSc}"]`;
+    else if (cur.id) label += `#${cur.id}`;
+    const cls = realClasses(cur).split(/\s+/).filter(Boolean).slice(0, 2);
+    if (cls.length && !dEl && !dSc) label += `.${cls.join('.')}`;
+    hops.unshift(label);
+    cur = cur.parentElement;
+  }
+  return hops;
+}
+
+export function cssEscape(s: string): string {
+  // Minimal CSS.escape polyfill — only handles chars actually present in
+  // pipeline-stamped IDs (alphanumerics + `-` + `_`).
+  return s.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`);
+}
+
+/**
+ * Build the wire-shape `Selection` for a resolved hover target. `file`
+ * defaults to `deriveFile()`; the comment mount layer passes it explicitly
+ * so all three consumers (router, overlay, mount) agree on the same key.
+ */
+export function hoverTargetToSelection(target: HoverTarget, file?: string): Selection {
+  const el = target.el;
+  const rect =
+    el && (el as HTMLElement).getBoundingClientRect
+      ? (el as HTMLElement).getBoundingClientRect()
+      : null;
+  // `cdId` is the hit element's OWN data-cd-id (deep mode); resolver never
+  // climbs to an ancestor. Falls back to cssPath of the hit when no stable
+  // anchor exists.
+  const cdId = target.cdId;
+  // Selector resolution order:
+  //   1. data-cd-id anchor — stable pipeline-stamped id (preferred).
+  //   2. data-dc-screen — chrome click promoted to whole-artboard select
+  //      (T24.5 G8 multi-artboard gesture).
+  //   3. cssPath of the hit — last-resort path string.
+  const selector = cdId
+    ? `[data-cd-id="${cdId}"]`
+    : !cdId && target.artboardId
+      ? `[data-dc-screen="${target.artboardId}"]`
+      : cssPath(el);
+  return {
+    file: file ?? deriveFile(),
+    id: cdId ?? undefined,
+    selector,
+    artboardId: target.artboardId,
+    tag: el?.tagName.toLowerCase() ?? '',
+    classes: realClasses(el),
+    text: shortText(el, 240),
+    dom_path: domPath(el),
+    bounds: rect
+      ? {
+          x: Math.round(rect.left),
+          y: Math.round(rect.top),
+          w: Math.round(rect.width),
+          h: Math.round(rect.height),
+        }
+      : null,
+    html: el ? (el.outerHTML ?? '').slice(0, 4000) : '',
+  };
+}

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

@@ -17,6 +17,7 @@
 // loaded via the importmap + Bun.build-produced ESM — there's no React Fast
 // Refresh runtime to register with. Full-reload is the reliable path.
 
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 
 import type { Context } from './context.ts';
@@ -64,26 +65,11 @@ export function createHmrBroadcaster(
   }
 
   function classify(filename: string): HmrMessage | null {
-    const rel = filename.replace(/\\/g, '/');
-    const ext = path.extname(rel).toLowerCase();
-    const version = Date.now();
-    if (rel.startsWith('_lib/')) {
-      return { type: 'canvas-hmr', mode: 'hard', scope: 'lib', version };
-    }
-    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' };
-    }
-    return null;
+    return classifyChange(filename, (cssRel) => {
+      const root = ctx.paths?.designRoot;
+      if (!root) return false; // no root resolved → can't probe; keep css swap
+      return existsSync(path.join(root, cssRel.replace(/\.css$/i, '.tsx')));
+    });
   }
 
   function enqueue(msg: HmrMessage) {
@@ -125,3 +111,48 @@ export function createHmrBroadcaster(
 // Helpers — exported for tests.
 
 export const HMR_DEBOUNCE_MS = DEBOUNCE_MS;
+
+/**
+ * Classify a changed design-root-relative path into an HMR message. Pure +
+ * fs-injected (`hasSiblingTsx`) so it unit-tests without touching disk.
+ *
+ * CSS routing is the load-bearing part. A canvas/specimen sibling stylesheet
+ * (e.g. `system/x/preview/motion.css` next to `motion.tsx`, pulled in via
+ * `import './motion.css'`) is INLINED into the built module as a `<style>` tag
+ * by canvas-build.ts — there is NO `<link>` for it. The iframe's `mode:'css'`
+ * handler swaps `<link href>` only, so a link swap for inlined CSS is a silent
+ * no-op and the edit never reaches the browser (the bug this fixes). For those
+ * we emit `mode:'module'` keyed on the sibling `.tsx`, so the open canvas
+ * reloads and re-inlines the fresh CSS via the existing module-reload path.
+ * Link-mounted CSS (DS tokens, `_components.css`, `_layout.css` — no sibling
+ * `.tsx`) keeps the fast, state-preserving css swap.
+ */
+export function classifyChange(
+  filename: string,
+  hasSiblingTsx: (cssRel: string) => boolean
+): HmrMessage | null {
+  const rel = filename.replace(/\\/g, '/');
+  const ext = path.extname(rel).toLowerCase();
+  const version = Date.now();
+  if (rel.startsWith('_lib/')) {
+    return { type: 'canvas-hmr', mode: 'hard', scope: 'lib', version };
+  }
+  if (ext === '.css') {
+    if (hasSiblingTsx(rel)) {
+      const siblingTsx = rel.replace(/\.css$/i, '.tsx');
+      return { type: 'canvas-hmr', mode: 'module', file: siblingTsx, version, scope: 'canvas' };
+    }
+    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' };
+  }
+  return null;
+}

package/plugins/design/dev-server/input-router.tsx

@@ -268,6 +268,16 @@ export interface UseInputRouterOptions {
   callbacks: RouterCallbacks;
   /** When false, listeners are not attached. Defaults to true. */
   enabled?: boolean;
+  /**
+   * Allowlist of action kinds this router is permitted to CLAIM (preventDefault
+   * + stopImmediatePropagation + dispatch). Any classified action outside the
+   * set is downgraded to `no-op` so it propagates untouched to other listeners.
+   * Omit to claim everything (the default — used by the full DesignCanvas
+   * router). The shell-owned comment mount layer passes a narrow set so it can
+   * coexist as an ANCESTOR capture-listener over a UI canvas's own router
+   * without swallowing select / context-menu / undo gestures it doesn't own.
+   */
+  claimableActions?: ReadonlySet<RouterAction['kind']>;
 }
 
 export function isEditableTarget(t: EventTarget | null): boolean {
@@ -295,13 +305,21 @@ export function isOverlayTarget(t: EventTarget | null): boolean {
 }
 
 export function useInputRouter(opts: UseInputRouterOptions): void {
-  const { hostRef, getActiveTool, isSpaceHeld, callbacks, enabled = true } = opts;
+  const { hostRef, getActiveTool, isSpaceHeld, callbacks, enabled = true, claimableActions } = opts;
 
   useEffect(() => {
     if (!enabled) return;
     const host = hostRef.current;
     if (!host) return;
 
+    // Downgrade any action this router isn't permitted to claim to no-op so it
+    // propagates untouched (no preventDefault / no dispatch). Identity pass-
+    // through when no allowlist is configured.
+    const claim = (action: RouterAction): RouterAction =>
+      claimableActions && action.kind !== 'no-op' && !claimableActions.has(action.kind)
+        ? { kind: 'no-op' }
+        : action;
+
     const dispatch = (action: RouterAction): void => {
       switch (action.kind) {
         case 'hover':
@@ -334,18 +352,20 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
     };
 
     const onPointerMove = (e: PointerEvent): void => {
-      const action = classify({
-        type: 'pointermove',
-        button: e.button,
-        metaKey: e.metaKey,
-        ctrlKey: e.ctrlKey,
-        shiftKey: e.shiftKey,
-        altKey: e.altKey,
-        clientX: e.clientX,
-        clientY: e.clientY,
-        spaceHeld: isSpaceHeld?.() ?? false,
-        activeTool: getActiveTool(),
-      });
+      const action = claim(
+        classify({
+          type: 'pointermove',
+          button: e.button,
+          metaKey: e.metaKey,
+          ctrlKey: e.ctrlKey,
+          shiftKey: e.shiftKey,
+          altKey: e.altKey,
+          clientX: e.clientX,
+          clientY: e.clientY,
+          spaceHeld: isSpaceHeld?.() ?? false,
+          activeTool: getActiveTool(),
+        })
+      );
       dispatch(action);
     };
 
@@ -354,18 +374,20 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
       // their own clicks. The router is in capture phase, so we have to
       // bail HERE before classify can claim the event.
       if (isOverlayTarget(e.target)) return;
-      const action = classify({
-        type: 'pointerdown',
-        button: e.button,
-        metaKey: e.metaKey,
-        ctrlKey: e.ctrlKey,
-        shiftKey: e.shiftKey,
-        altKey: e.altKey,
-        clientX: e.clientX,
-        clientY: e.clientY,
-        spaceHeld: isSpaceHeld?.() ?? false,
-        activeTool: getActiveTool(),
-      });
+      const action = claim(
+        classify({
+          type: 'pointerdown',
+          button: e.button,
+          metaKey: e.metaKey,
+          ctrlKey: e.ctrlKey,
+          shiftKey: e.shiftKey,
+          altKey: e.altKey,
+          clientX: e.clientX,
+          clientY: e.clientY,
+          spaceHeld: isSpaceHeld?.() ?? false,
+          activeTool: getActiveTool(),
+        })
+      );
       if (action.kind !== 'no-op') {
         // Suppress native behavior on every event the router claims —
         // button presses don't fire, inputs don't focus, the canvas
@@ -386,18 +408,20 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
      */
     const onMouseDown = (e: MouseEvent): void => {
       if (isOverlayTarget(e.target)) return;
-      const action = classify({
-        type: 'pointerdown',
-        button: e.button,
-        metaKey: e.metaKey,
-        ctrlKey: e.ctrlKey,
-        shiftKey: e.shiftKey,
-        altKey: e.altKey,
-        clientX: e.clientX,
-        clientY: e.clientY,
-        spaceHeld: isSpaceHeld?.() ?? false,
-        activeTool: getActiveTool(),
-      });
+      const action = claim(
+        classify({
+          type: 'pointerdown',
+          button: e.button,
+          metaKey: e.metaKey,
+          ctrlKey: e.ctrlKey,
+          shiftKey: e.shiftKey,
+          altKey: e.altKey,
+          clientX: e.clientX,
+          clientY: e.clientY,
+          spaceHeld: isSpaceHeld?.() ?? false,
+          activeTool: getActiveTool(),
+        })
+      );
       if (action.kind !== 'no-op') {
         e.preventDefault();
         e.stopImmediatePropagation();
@@ -414,41 +438,55 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
       if (isOverlayTarget(e.target)) return;
       const tool = getActiveTool();
       const mod = e.metaKey || e.ctrlKey;
-      const wouldRoute =
-        tool === 'comment' || (tool === 'move' && mod && e.button === 0) || e.button === 2;
-      if (wouldRoute) {
+      // Map the click to the action kind the matching pointerdown would have
+      // produced, then honor the claim allowlist so a scoped router (the
+      // comment mount layer) doesn't suppress clicks it never claimed.
+      const wouldRouteKind: RouterAction['kind'] | null =
+        tool === 'comment'
+          ? 'drop-comment'
+          : tool === 'move' && mod && e.button === 0
+            ? 'select'
+            : e.button === 2
+              ? 'context-menu'
+              : null;
+      if (wouldRouteKind && (!claimableActions || claimableActions.has(wouldRouteKind))) {
         e.preventDefault();
         e.stopImmediatePropagation();
       }
     };
 
     const onContextMenu = (e: MouseEvent): void => {
+      const action = claim(
+        classify({
+          type: 'contextmenu',
+          clientX: e.clientX,
+          clientY: e.clientY,
+          metaKey: e.metaKey,
+          ctrlKey: e.ctrlKey,
+          shiftKey: e.shiftKey,
+          altKey: e.altKey,
+          activeTool: getActiveTool(),
+        })
+      );
+      if (action.kind === 'no-op') return; // not ours to claim — let it bubble
       e.preventDefault();
       e.stopImmediatePropagation();
-      const action = classify({
-        type: 'contextmenu',
-        clientX: e.clientX,
-        clientY: e.clientY,
-        metaKey: e.metaKey,
-        ctrlKey: e.ctrlKey,
-        shiftKey: e.shiftKey,
-        altKey: e.altKey,
-        activeTool: getActiveTool(),
-      });
       dispatch(action);
     };
 
     const onKeyDown = (e: KeyboardEvent): void => {
-      const action = classify({
-        type: 'keydown',
-        key: e.key,
-        metaKey: e.metaKey,
-        ctrlKey: e.ctrlKey,
-        shiftKey: e.shiftKey,
-        altKey: e.altKey,
-        isEditable: isEditableTarget(e.target),
-        activeTool: getActiveTool(),
-      });
+      const action = claim(
+        classify({
+          type: 'keydown',
+          key: e.key,
+          metaKey: e.metaKey,
+          ctrlKey: e.ctrlKey,
+          shiftKey: e.shiftKey,
+          altKey: e.altKey,
+          isEditable: isEditableTarget(e.target),
+          activeTool: getActiveTool(),
+        })
+      );
       if (
         action.kind === 'tool' ||
         action.kind === 'escape' ||
@@ -486,7 +524,7 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
       } as EventListenerOptions);
       doc.removeEventListener('keydown', onKeyDown, true);
     };
-  }, [enabled, hostRef, getActiveTool, isSpaceHeld, callbacks]);
+  }, [enabled, hostRef, getActiveTool, isSpaceHeld, callbacks, claimableActions]);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

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

@@ -26,6 +26,7 @@ import { createFsWatch } from './fs-watch.ts';
 import { createHttp } from './http.ts';
 import { createInspect } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
+import { createSyncRuntime } from './sync/index.ts';
 import { type WsData, createWs, isLoopbackHost, parseCollabSlug } from './ws.ts';
 
 // Phase 19 / DDR-044 — covers the marketplace-cache-install gap where
@@ -199,6 +200,18 @@ await Bun.write(
 fsWatch.start();
 startHeapWatch();
 
+// Phase 9 Task 4 — bidirectional sync agent. No-op when the project isn't
+// linked to a hub (`.design/config.json` has no `linkedHub` field). Kicked
+// off after fsWatch so the agent's bus subscription receives every fs event.
+const syncRuntime = createSyncRuntime(ctx, collab ? { registry: collab.registry } : {});
+if (syncRuntime) {
+  try {
+    await syncRuntime.start();
+  } catch (err) {
+    console.error('[sync] startup failed — continuing in solo mode:', err);
+  }
+}
+
 const url = `http://localhost:${server.port}`;
 console.log(`\n  ${ctx.projectLabel} — local browser`);
 console.log('  ─────────────────────────────');
@@ -219,6 +232,11 @@ if (!process.env.NO_OPEN) {
 async function shutdown() {
   console.log('\n  Stopping…');
   fsWatch.stop();
+  try {
+    if (syncRuntime) await syncRuntime.stop();
+  } catch {
+    /* best-effort — provider sockets will be closed by process exit anyway */
+  }
   try {
     if (collab) await collab.registry.destroyAll();
   } catch {