@1agh/maude 0.22.2 → 0.24.0

package/plugins/design/dev-server/bin/smoke.sh

@@ -10,6 +10,9 @@
 #            [--include-system 0|1]   (default 1)
 #            [--timeout <secs>]       (default 8)
 #            [--engine auto|agent-browser|playwright]
+#            [--changed-only]         (default off — screenshot only canvases changed
+#                                      since the last smoke run; escalates to the full
+#                                      set when dev-server / canvas-lib / templates changed)
 #
 # Reads:
 #   $DESIGN_ROOT/_server.json   (must exist — caller runs server-up.sh first)
@@ -31,6 +34,7 @@ OUT_DIR=""
 INCLUDE_SYSTEM=1
 TIMEOUT=8
 ENGINE="auto"
+CHANGED_ONLY=0
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -39,8 +43,9 @@ while [ $# -gt 0 ]; do
     --include-system) INCLUDE_SYSTEM="$2"; shift 2 ;;
     --timeout)        TIMEOUT="$2"; shift 2 ;;
     --engine)         ENGINE="$2"; shift 2 ;;
+    --changed-only)   CHANGED_ONLY=1; shift ;;
     --help|-h)
-      sed -n '2,28p' "$0" | sed 's/^# \?//'
+      sed -n '2,30p' "$0" | sed 's/^# \?//'
       exit 0
       ;;
     *)
@@ -73,6 +78,10 @@ if [ -z "$OUT_DIR" ]; then
   OUT_DIR="$DESIGN_ROOT/_history/_smoke/$TS"
 fi
 mkdir -p "$OUT_DIR"
+# agent-browser ignores RELATIVE screenshot paths (writes to ~/.agent-browser/tmp
+# instead), which silently strands every PNG. Canonicalize to absolute so the
+# captured evidence actually lands in OUT_DIR. See DDR-021.
+OUT_DIR="$(cd "$OUT_DIR" && pwd)"
 
 # ---------- engine resolution ----------
 if [ "$ENGINE" = "auto" ]; then
@@ -107,6 +116,57 @@ COUNT=$(printf '%s' "$CANVASES" | grep -c .)
 [ "$COUNT" -gt 0 ] || { echo "smoke.sh: no canvases found (ui/*.tsx or system/*/preview/*.tsx)" >&2; exit 1; }
 echo "→ found $COUNT canvases" >&2
 
+# ---------- --changed-only incremental filter (Phase C / DDR-061) ----------
+# Default smoke screenshots every canvas. --changed-only narrows to the canvases
+# touched since the last recorded smoke run, UNLESS the diff touches an
+# "everything could break" shape (dev-server, canvas-lib, canvas templates) — then
+# it escalates back to the full set. Correctness > speed: no baseline, no git, or
+# an escalation trigger all fall back to the full set.
+MARKER="$DESIGN_ROOT/_history/_smoke/.last-smoke.json"
+if [ "$CHANGED_ONLY" = "1" ]; then
+  LAST_SHA=""
+  if [ -f "$MARKER" ] && command -v jq >/dev/null 2>&1; then
+    LAST_SHA=$(jq -r '.sha // empty' "$MARKER" 2>/dev/null)
+  fi
+  if ! command -v git >/dev/null 2>&1 || ! git -C "$REPO" rev-parse HEAD >/dev/null 2>&1; then
+    echo "→ --changed-only: no git in $REPO — running full set" >&2
+  elif [ -z "$LAST_SHA" ]; then
+    echo "→ --changed-only: no prior smoke baseline ($MARKER) — running full set" >&2
+  else
+    # All paths changed between the last smoke and the current working tree
+    # (committed + uncommitted), plus untracked canvases.
+    CHANGED=$(
+      { git -C "$REPO" diff --name-only "$LAST_SHA" -- 2>/dev/null
+        git -C "$REPO" ls-files --others --exclude-standard -- .design/ui .design/system 2>/dev/null
+      } | sort -u
+    )
+    if printf '%s\n' "$CHANGED" | grep -qE 'dev-server/|canvas-lib\.tsx|canvas[^/]*\.tsx\.template'; then
+      echo "→ --changed-only: dev-server / canvas-lib / template changed — escalating to FULL set" >&2
+    else
+      # Keep only canvases whose repo-relative path is in the changed set.
+      FILTERED=""
+      while IFS= read -r CANVAS; do
+        [ -z "$CANVAS" ] && continue
+        REL_REPO="${CANVAS#$REPO/}"
+        if printf '%s\n' "$CHANGED" | grep -qxF "$REL_REPO"; then
+          FILTERED="$FILTERED$CANVAS"$'\n'
+        fi
+      done <<< "$CANVASES"
+      CANVASES=$(printf '%s' "$FILTERED" | sed '/^$/d')
+      COUNT=$(printf '%s' "$CANVASES" | grep -c .)
+      if [ "$COUNT" -eq 0 ]; then
+        echo "→ --changed-only: no canvas .tsx changed since last smoke ($LAST_SHA) — nothing to screenshot" >&2
+        # Refresh the marker so the next run diffs from here, then exit clean.
+        mkdir -p "$(dirname "$MARKER")"
+        printf '{"sha":"%s","ts":"%s","mode":"changed-only-noop"}' \
+          "$(git -C "$REPO" rev-parse HEAD 2>/dev/null)" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$MARKER"
+        exit 0
+      fi
+      echo "→ --changed-only: $COUNT changed canvas(es) since $LAST_SHA" >&2
+    fi
+  fi
+fi
+
 # ---------- helpers ----------
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SLUG_HELPER="$SCRIPT_DIR/slug.sh"
@@ -160,6 +220,8 @@ probe_agent_browser() {
     for (const s of sel) { const el = document.querySelector(s); if (el && el.innerText) return el.innerText.slice(0, 120); }
     const body = document.body && document.body.innerText || '';
     if (body.startsWith('Error:') || body.startsWith('SyntaxError:') || body.startsWith('ReferenceError:')) return body.slice(0, 120);
+    const t = body.trim();
+    if (t === 'Not found' || t.startsWith('Forbidden (canvas origin)')) return 'route-error: ' + t.slice(0, 80);
     return '';
   })()" 2>/dev/null)
   # Strip wrapping quotes that agent-browser eval adds for strings.
@@ -172,16 +234,24 @@ probe_agent_browser() {
     return
   fi
 
+  # The PNG IS the evidence (DDR-021). A missing/empty file means agent-browser
+  # never wrote it (relative path, capture crash, …) — that is a FAILURE, not an
+  # OK. The old code fell straight through to "OK" here, which is exactly how a
+  # broken canvas route ("Not found" 404 + no PNG) masqueraded as 43/43 green.
+  if [ ! -s "$out_png" ]; then
+    echo "ERROR"
+    echo "screenshot-not-written"
+    echo "$out_png"
+    return
+  fi
   # PNG size sanity — < 2 KB usually means blank background only.
-  if [ -s "$out_png" ]; then
-    local size
-    size=$(wc -c < "$out_png" 2>/dev/null | tr -d ' ')
-    if [ -n "$size" ] && [ "$size" -lt 2048 ]; then
-      echo "BLANK"
-      echo "png-${size}B"
-      echo "$out_png"
-      return
-    fi
+  local size
+  size=$(wc -c < "$out_png" 2>/dev/null | tr -d ' ')
+  if [ -n "$size" ] && [ "$size" -lt 2048 ]; then
+    echo "BLANK"
+    echo "png-${size}B"
+    echo "$out_png"
+    return
   fi
 
   echo "OK"
@@ -211,7 +281,11 @@ while IFS= read -r CANVAS; do
   N=$((N + 1))
   REL="${CANVAS#$DESIGN_ROOT/}"
   REL_ENC=$(urlencode_path "$REL")
-  URL="http://localhost:$PORT/$REL_ENC"
+  # Canvases render through the canvas shell, not the bare path. The bare
+  # `/<rel>` route 404s when the canvas-origin sandbox is on (default since
+  # phase-9.1) — only `/_canvas-shell.html?canvas=<rel>` mounts the canvas
+  # (works in both split-on and legacy same-origin modes).
+  URL="http://localhost:$PORT/_canvas-shell.html?canvas=$REL_ENC"
   SLUG=$(bash "$SLUG_HELPER" "$REL" 2>/dev/null || printf '%s' "$REL" | tr '/ ' '__' | tr '[:upper:]' '[:lower:]')
   OUT_PNG="$OUT_DIR/$SLUG.png"
 
@@ -264,6 +338,15 @@ done <<< "$CANVASES"
 echo "→ report: $MD" >&2
 echo "→ tsv:    $TSV" >&2
 
+# Record this run as the baseline for the next --changed-only diff (Phase C / DDR-061).
+if command -v git >/dev/null 2>&1 && git -C "$REPO" rev-parse HEAD >/dev/null 2>&1; then
+  mkdir -p "$DESIGN_ROOT/_history/_smoke"
+  printf '{"sha":"%s","ts":"%s","mode":"%s","count":%d,"failed":%d}' \
+    "$(git -C "$REPO" rev-parse HEAD 2>/dev/null)" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    "$([ "$CHANGED_ONLY" = "1" ] && echo changed-only || echo full)" "$COUNT" "$FAILED" \
+    > "$DESIGN_ROOT/_history/_smoke/.last-smoke.json"
+fi
+
 if [ $FAILED -gt 0 ]; then
   echo "✗ smoke: $FAILED / $COUNT canvases failed" >&2
   exit 3

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

@@ -114,6 +114,58 @@ async function buildClient(): Promise<{ outBytes: number; outPath: string }> {
   return { outBytes: out.size, outPath };
 }
 
+// ---------- (a.5) Comment mount layer (shell-owned comments) ----------
+//
+// canvas-comment-mount.tsx → dist/comment-mount.js. Loaded by _shell.html via
+// a `<script type="module">`; its `mountCanvas(...)` wraps any canvas default
+// export in the lite comment provider tree. React + the other canvas-runtime
+// packages are EXTERNAL (bare specifiers resolved by _shell.html's importmap)
+// so this bundle shares the single React/yjs singletons with the canvas
+// module — inlining a second React would break hooks ("invalid hook call").
+
+const COMMENT_MOUNT_EXTERNALS = [
+  'react',
+  'react-dom',
+  'react-dom/client',
+  'react/jsx-runtime',
+  'react/jsx-dev-runtime',
+  'yjs',
+  'y-protocols/sync',
+  'y-protocols/awareness',
+  'lib0/decoding',
+  'lib0/encoding',
+];
+
+async function buildCommentMount(): Promise<{ outBytes: number; outPath: string }> {
+  ensureDist();
+  const outPath = join(DIST, 'comment-mount.js');
+  const result = await Bun.build({
+    entrypoints: [join(ROOT, 'canvas-comment-mount.tsx')],
+    outdir: DIST,
+    target: 'browser',
+    format: 'esm',
+    naming: 'comment-mount.js',
+    external: COMMENT_MOUNT_EXTERNALS,
+    minify: MODE === 'release',
+    sourcemap: MODE === 'dev' ? 'inline' : 'none',
+    define: {
+      // ALWAYS production React — like canvas-build.ts. React is external and
+      // resolves through the importmap to the dev-server's PRODUCTION runtime
+      // bundles, where `react/jsx-dev-runtime`'s `jsxDEV` is a no-op (undefined
+      // at call time). Emitting dev jsx (`jsxDEV`) against a production runtime
+      // throws "jsxDEV is not a function". Both halves must agree on the JSX
+      // flavour — production jsx (`react/jsx-runtime`) is the contract.
+      'process.env.NODE_ENV': '"production"',
+    },
+  });
+  if (!result.success) {
+    const messages = result.logs.map((l) => l.message ?? String(l)).join('\n');
+    throw new Error(`Comment-mount build failed:\n${messages}`);
+  }
+  const out = Bun.file(outPath);
+  return { outBytes: out.size, outPath };
+}
+
 // ---------- (b) CSS bundle (Lightning CSS) ----------
 
 async function buildCss(): Promise<{ outBytes: number; outPath: string }> {
@@ -325,6 +377,7 @@ async function buildServerBinary(target: PlatformTarget): Promise<{ outPath: str
 
 async function watch() {
   await buildClient();
+  await buildCommentMount();
   await buildCss();
   console.log('[build:watch] initial build complete; watching client/ + server source...');
 
@@ -396,10 +449,16 @@ async function main() {
     `[build] client.bundle.js  ${client.outBytes.toLocaleString()} B  (${(t1 - t0).toFixed(0)} ms)`
   );
 
+  const commentMount = await buildCommentMount();
+  const t1b = performance.now();
+  console.log(
+    `[build] comment-mount.js  ${commentMount.outBytes.toLocaleString()} B  (${(t1b - t1).toFixed(0)} ms)`
+  );
+
   const css = await buildCss();
   const t2 = performance.now();
   console.log(
-    `[build] styles.css        ${css.outBytes.toLocaleString()} B  (${(t2 - t1).toFixed(0)} ms)`
+    `[build] styles.css        ${css.outBytes.toLocaleString()} B  (${(t2 - t1b).toFixed(0)} ms)`
   );
 
   // Pre-built runtime bundles — ship to disk so /_canvas-runtime/* never
@@ -415,7 +474,7 @@ async function main() {
   // on-disk artifacts against .min-sizes.json after the build.
   if (process.env.MAUDE_SKIP_RUNTIME_BUILD === '1') {
     console.log(
-      `[build] dist/runtime/*.js SKIPPED (MAUDE_SKIP_RUNTIME_BUILD=1 — using committed pre-built)`
+      '[build] dist/runtime/*.js SKIPPED (MAUDE_SKIP_RUNTIME_BUILD=1 — using committed pre-built)'
     );
   } else {
     const runtime = await buildRuntimeBundles();
@@ -444,4 +503,11 @@ if (import.meta.main) {
   await main();
 }
 
-export { buildClient, buildCss, buildServerBinary, PLATFORM_MATRIX, type PlatformTarget };
+export {
+  buildClient,
+  buildCommentMount,
+  buildCss,
+  buildServerBinary,
+  PLATFORM_MATRIX,
+  type PlatformTarget,
+};

package/plugins/design/dev-server/canvas-comment-mount.tsx

@@ -0,0 +1,384 @@
+/**
+ * @file       canvas-comment-mount.tsx — shell-owned comment layer + mountCanvas
+ * @scope      plugins/design/dev-server/canvas-comment-mount.tsx
+ * @purpose    The canvas mount harness (`_shell.html`) calls `mountCanvas`
+ *             instead of rendering the canvas default-export raw. mountCanvas
+ *             wraps ANY default export — a `DesignCanvas` UI canvas OR a bare
+ *             DS specimen — in a LITE comment provider tree so the in-place
+ *             comment tool works on every mounted surface.
+ *
+ * Why a single shell-owned layer (DDR — see plan §"Key decision"):
+ *   - Comments used to be mounted only by `DesignCanvas` (ToolProvider +
+ *     SelectionSetProvider + CommentsOverlay + the onDropComment router
+ *     branch). Bare specimens (`system/<ds>/preview/*.tsx`) never render
+ *     DesignCanvas, so they had no comment tool at all.
+ *   - Hoisting the comment subsystem here makes it universal. `DesignCanvas`
+ *     becomes a CONSUMER of the shell-provided ToolProvider / SelectionSet /
+ *     CommentsOverlay (via MaybeToolProvider / MaybeSelectionSetProvider and
+ *     by dropping its own <CommentsOverlay/>).
+ *
+ * Coexistence with the UI-canvas router: this layer's input router is an
+ * ANCESTOR capture-listener over the canvas. On a UI canvas, `CanvasShell`
+ * still runs its OWN router (hover / select / context-menu / undo). To avoid
+ * swallowing those gestures, this router passes a narrow `claimableActions`
+ * allowlist — `drop-comment` / `tool` / `escape` / `hover`. `hover` never
+ * preventDefaults so the inner router's halo is unaffected; everything else
+ * (select / context-menu / undo) propagates untouched to the inner router.
+ */
+
+import {
+  type ComponentType,
+  type ReactNode,
+  createElement,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { createRoot } from 'react-dom/client';
+
+import { CommentsOverlay } from './comments-overlay.tsx';
+import { deriveFile, hoverTargetToSelection } from './dom-selection.ts';
+import { type RouterAction, resolveHoverTarget, useInputRouter } from './input-router.tsx';
+import {
+  MaybeSelectionSetProvider,
+  type Selection,
+  useSelectionSet,
+} from './use-selection-set.tsx';
+import { MaybeToolProvider, useToolMode } from './use-tool-mode.tsx';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cursor CSS for the generic mount host. canvas-lib's HALO_CSS keys comment-
+// mode cursors on `.dc-canvas[data-active-tool]`, which is absent in a bare
+// specimen. We mirror the comment-tool cursor keyed on the mount host's
+// `data-active-tool` attribute so the affordance ships even with no canvas-lib
+// CSS present. The host is `display: contents` (so specimen layout is byte-
+// identical) — a `display:contents` box can't paint a cursor, so the rule
+// targets descendants of the host, not the host box itself.
+
+const MC_CURSOR_CSS = `
+[data-mc-host][data-active-tool="comment"] *,
+body[data-active-tool="comment"] * {
+  cursor: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'><path d='M3 3 L14 3 L14 11 L8 11 L4 14 L4 11 L3 11 Z' fill='white' stroke='%23111' stroke-width='1' stroke-linejoin='round'/></svg>") 4 4, crosshair !important;
+}
+`.trim();
+
+function ensureMountCursorStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('mc-cursor-css')) return;
+  const s = document.createElement('style');
+  s.id = 'mc-cursor-css';
+  s.textContent = MC_CURSOR_CSS;
+  document.head.appendChild(s);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CommentHost — owns the lite comment subsystem: the input router (comment-
+// scoped), the single CommentsOverlay, the comment-mode cursor attribute, and
+// the parent `dgn:'tool-set'` listener (so the outer menubar comment toggle
+// reaches the iframe).
+
+// Only these action kinds are claimed by the mount-layer router; the rest
+// propagate to a UI canvas's own router. `tool` + `escape` are also handled by
+// the inner router on UI canvases — idempotent (same shared provider). `hover`
+// is dispatched too (it never preventDefaults, so the inner router's own hover
+// halo on a UI canvas is unaffected) — we only PAINT the mount-layer preview
+// halo on a bare specimen, where there is no inner CanvasShell halo.
+const COMMENT_CLAIMS: ReadonlySet<RouterAction['kind']> = new Set<RouterAction['kind']>([
+  'drop-comment',
+  'tool',
+  'escape',
+  'hover',
+]);
+
+// True when no DesignCanvas/CanvasShell is mounted on this surface — i.e. a
+// bare DS specimen. On a UI canvas (`.dc-canvas` present) the inner shell owns
+// hover-halo painting + `resolveHoverTarget` element anchoring, so the lite
+// layer defers to it.
+function isBareSpecimen(): boolean {
+  return typeof document !== 'undefined' && !document.querySelector('.dc-canvas');
+}
+
+// Deepest non-chrome element under a point — the comment anchor for a bare
+// specimen (specimens aren't stamped with `data-cd-id` and have no
+// `.dc-artboard-body`, so `resolveHoverTarget` returns null for them).
+function pickSpecimenEl(clientX: number, clientY: number): HTMLElement | null {
+  if (typeof document === 'undefined') return null;
+  const hit = document.elementFromPoint(clientX, clientY) as HTMLElement | null;
+  if (!hit) return null;
+  // Never anchor to comment chrome or the document root.
+  if (hit.closest('.cm-composer, .cm-thread, .cm-mention-popup, .cm-pin, [data-mc-hover-halo]')) {
+    return null;
+  }
+  const tag = hit.tagName;
+  if (tag === 'HTML' || tag === 'BODY') return null;
+  return hit;
+}
+
+function CommentHost({ children, file }: { children: ReactNode; file: string | undefined }) {
+  ensureMountCursorStyles();
+  const { tool, setTool } = useToolMode();
+  const selSet = useSelectionSet();
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  // Hover-preview halo target (bare specimens only — see isBareSpecimen).
+  const [hoverEl, setHoverEl] = useState<HTMLElement | null>(null);
+
+  // Latest tool for the router (read at event time, not captured).
+  const toolRef = useRef(tool);
+  toolRef.current = tool;
+  const getActiveTool = useMemo(() => () => toolRef.current, []);
+
+  // Drop the preview halo whenever we leave comment mode.
+  useEffect(() => {
+    if (tool !== 'comment') setHoverEl(null);
+  }, [tool]);
+
+  // Reflect the active tool onto the host (and body, since the host is
+  // display:contents and can't carry a paintable cursor). Comment-mode CSS
+  // keys off `[data-active-tool="comment"]`.
+  useEffect(() => {
+    const host = hostRef.current;
+    if (host) host.setAttribute('data-active-tool', tool);
+    if (typeof document !== 'undefined' && document.body) {
+      document.body.setAttribute('data-active-tool', tool);
+    }
+    return () => {
+      host?.removeAttribute('data-active-tool');
+    };
+  }, [tool]);
+
+  // Parent `dgn:'tool-set'` — the outer dev-server menubar posts this when the
+  // user toggles the comment tool. Mirrors canvas-shell's listener so the
+  // toggle reaches bare specimens too (which have no inner shell listener).
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const onMessage = (e: MessageEvent) => {
+      const m = e.data as { dgn?: string; tool?: string } | null;
+      if (!m || typeof m !== 'object' || m.dgn !== 'tool-set') return;
+      if (typeof m.tool === 'string') setTool(m.tool as never);
+    };
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, [setTool]);
+
+  useInputRouter({
+    hostRef,
+    getActiveTool,
+    claimableActions: COMMENT_CLAIMS,
+    callbacks: {
+      onHover: ({ clientX, clientY }) => {
+        // Paint a preview halo only on bare specimens; a UI canvas's own
+        // CanvasShell HoverHalo owns the comment-mode preview there.
+        if (toolRef.current !== 'comment' || !isBareSpecimen()) {
+          setHoverEl(null);
+          return;
+        }
+        const el = pickSpecimenEl(clientX, clientY);
+        setHoverEl((prev) => (prev === el ? prev : el));
+      },
+      onTool: ({ tool: t }) => setTool(t),
+      onEscape: () => {
+        if (toolRef.current !== 'move') setTool('move');
+        setHoverEl(null);
+        selSet.clear();
+        if (typeof window !== 'undefined') {
+          try {
+            window.parent.postMessage({ dgn: 'force-clear' }, '*');
+          } catch {
+            /* parent detached */
+          }
+        }
+      },
+      onDropComment: ({ clientX, clientY }) => dropComment(clientX, clientY, selSet, file),
+    },
+  });
+
+  // `display: contents` keeps the specimen's own flex/grid layout byte-
+  // identical — the host box contributes nothing to layout. The fixed-position
+  // CommentsOverlay renders fine as a child regardless.
+  return (
+    <div data-mc-host ref={hostRef} style={{ display: 'contents' }}>
+      {children}
+      {hoverEl ? <MountHoverHalo el={hoverEl} /> : null}
+      <CommentsOverlay />
+    </div>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MountHoverHalo — fixed-position outline tracking the hovered element's screen
+// bounds via rAF. Inline-styled (no dependency on canvas-lib's HALO_CSS, which
+// a bare specimen doesn't load). Mirrors canvas-shell's HoverHalo visually.
+
+function MountHoverHalo({ el }: { el: HTMLElement }) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const targetRef = useRef<HTMLElement>(el);
+  targetRef.current = el;
+  const rafRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    const tick = () => {
+      rafRef.current = null;
+      const div = ref.current;
+      const t = targetRef.current;
+      if (div && t?.isConnected) {
+        const r = t.getBoundingClientRect();
+        if (r.width === 0 && r.height === 0) {
+          div.style.display = 'none';
+        } else {
+          div.style.display = 'block';
+          div.style.left = `${Math.round(r.left)}px`;
+          div.style.top = `${Math.round(r.top)}px`;
+          div.style.width = `${Math.round(r.width)}px`;
+          div.style.height = `${Math.round(r.height)}px`;
+        }
+      } else if (div) {
+        div.style.display = 'none';
+      }
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => {
+      if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
+    };
+  }, []);
+
+  return (
+    <div
+      ref={ref}
+      aria-hidden="true"
+      data-mc-hover-halo=""
+      style={{
+        position: 'fixed',
+        display: 'none',
+        pointerEvents: 'none',
+        zIndex: 2147483646,
+        border: '2px solid var(--maude-hud-accent, #d63b1f)',
+        borderRadius: '3px',
+        boxSizing: 'border-box',
+      }}
+    />
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Comment drop — generic path lifted from canvas-shell's onDropComment. Works
+// with or without artboards: deep/shallow resolveHoverTarget → elementsFromPoint
+// data-cd-id climb → floating fallback. Dispatches `cm:open-composer` for the
+// in-iframe overlay + posts `comment-compose` to the parent for legacy mocks.
+
+function dropComment(
+  clientX: number,
+  clientY: number,
+  selSet: { replace: (s: Selection) => void },
+  file: string | undefined
+): void {
+  if (typeof document === 'undefined') return;
+  let target = resolveHoverTarget(document, clientX, clientY, { deep: true });
+  if (!target) target = resolveHoverTarget(document, clientX, clientY, { deep: false });
+  // UI-canvas recovery — when both passes bail on a `pointer-events: none`
+  // decoration, enumerate the stack and climb the first `data-cd-id` ancestor
+  // inside an artboard body. Skipped on bare specimens, which instead anchor to
+  // the exact hovered element below (so the pin matches the hover preview halo).
+  if (!target && !isBareSpecimen() && typeof document.elementsFromPoint === 'function') {
+    const stack = document.elementsFromPoint(clientX, clientY);
+    for (const candidate of stack) {
+      const stamped = (candidate as Element).closest?.('[data-cd-id]') as HTMLElement | null;
+      if (!stamped) continue;
+      if (!stamped.closest('.dc-artboard-body')) continue;
+      const artboardEl = stamped.closest('[data-dc-screen]');
+      target = {
+        el: stamped,
+        cdId: stamped.getAttribute('data-cd-id'),
+        artboardId: artboardEl?.getAttribute('data-dc-screen') ?? null,
+      };
+      break;
+    }
+  }
+
+  // Bare-specimen anchor — specimens have no `.dc-artboard-body`, so
+  // resolveHoverTarget bails. Anchor to the EXACT element under the cursor (the
+  // same one pickSpecimenEl highlights for the hover preview), via its own
+  // data-cd-id when stamped, else a cssPath selector — so the dropped pin lands
+  // on the previewed element instead of floating.
+  if (!target && isBareSpecimen()) {
+    const el = pickSpecimenEl(clientX, clientY);
+    if (el) target = { el, cdId: el.getAttribute('data-cd-id'), artboardId: null };
+  }
+
+  if (!target) {
+    // Floating comment — no element anchor, just the click point (e.g. a click
+    // on empty canvas/specimen dead space). The overlay renders a pin at the
+    // stored bounds.
+    const floatingSel: Selection = {
+      file,
+      id: undefined,
+      selector: '',
+      artboardId: null,
+      tag: '',
+      classes: '',
+      text: '',
+      dom_path: [],
+      bounds: { x: clientX - 12, y: clientY - 12, w: 24, h: 24 },
+      html: '',
+    };
+    openComposer(floatingSel, clientX, clientY);
+    return;
+  }
+
+  const sel = hoverTargetToSelection(target, file);
+  selSet.replace(sel);
+  openComposer(sel, clientX, clientY);
+}
+
+function openComposer(selection: Selection, clientX: number, clientY: number): void {
+  if (typeof document !== 'undefined') {
+    try {
+      document.dispatchEvent(
+        new CustomEvent('cm:open-composer', { detail: { selection, clientX, clientY } })
+      );
+    } catch {
+      /* CustomEvent absent — fall through to parent path */
+    }
+  }
+  if (typeof window !== 'undefined') {
+    try {
+      window.parent.postMessage({ dgn: 'comment-compose', selection }, '*');
+    } catch {
+      /* parent detached */
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// mountCanvas — the shell harness entry. Renders the canvas wrapped in the lite
+// comment tree, or bare when comments are disabled (gallery thumbnails pass
+// `commentsEnabled: false` via `?comments=0`).
+
+export interface MountCanvasOptions {
+  rootEl: HTMLElement;
+  /** Canvas file key (designRel-prefixed). Defaults to `deriveFile()`. */
+  file?: string;
+  /** When false, the comment layer is skipped — the canvas renders raw. */
+  commentsEnabled: boolean;
+}
+
+export function mountCanvas(Canvas: ComponentType, opts: MountCanvasOptions): void {
+  const root = createRoot(opts.rootEl);
+  if (!opts.commentsEnabled) {
+    root.render(createElement(Canvas));
+    return;
+  }
+  const file = opts.file ?? deriveFile();
+  root.render(
+    createElement(
+      MaybeToolProvider,
+      null,
+      createElement(
+        MaybeSelectionSetProvider,
+        null,
+        createElement(CommentHost, { file }, createElement(Canvas))
+      )
+    )
+  );
+}