@1agh/maude 0.29.0 → 0.31.0

package/apps/studio/client/styles/_index.css

@@ -30,4 +30,6 @@
 @import url('./4-components-maude.css');
 /* Plan B — maude redesign of remaining legacy shell surfaces (HelpModal, tour, what's-new, SystemView, CommentBar). */
 @import url('./5-maude-overrides.css');
+/* Phase 31 (DDR-123) — ACP chat sidepanel (chat-* inside the Assistant st-rpanel). */
+@import url('./6-acp-chat.css');
 @import url('./5-utilities.css');

package/apps/studio/client/tour/collab-tour.js

@@ -0,0 +1,61 @@
+// collab-tour.js — the version-control "rychlý kurz" (Phase 29, epic E4).
+//
+// Teaches the two-layer collab model on the EXISTING tour engine (overlay.jsx) —
+// never a fork. Per the teaching-model DDR (this phase REVERSES the "hide the
+// duality" recommendation in collab-model-design.md § Part 2): we surface a visible
+// three-verb action-cycle and teach the live-vs-async split honestly, because the
+// cycle has to match real buttons in the app and pure-hiding is leaky.
+//
+// Step 1 is a centered, target-less step whose graphic is the two-layer infographic
+// (the engine already centers target-less steps; the `render` field is the only
+// addition). Steps 2-4 spotlight the real action controls via stable [data-tour]
+// anchors (save-local / publish / pull) — `changes: true` opens the Changes panel
+// first so the buttons exist. Step 5 points at the live presence layer; step 6 is
+// the one honest hard thing, centered.
+//
+// Vocabulary is the canonical set ONLY (teaching-model table) — no raw git terms:
+//   Save changes locally · Publish for everyone · Pull changes · Draft · Shared version.
+
+import CollabModelInfographic from '../panels/CollabModelInfographic.jsx';
+
+export const COLLAB_TOUR = [
+  {
+    // Centered, no target — the engine renders target-less steps centered, and the
+    // `render` field draws the infographic above the copy.
+    render: CollabModelInfographic,
+    title: 'Working together, in one picture',
+    body: 'There are two layers. Up top, being together just happens. Below, your work moves through three simple steps. Let’s walk them.',
+  },
+  {
+    target: "[data-tour='save-local']",
+    changes: true,
+    title: 'Save changes locally',
+    body: 'When something looks right, save it. That keeps a version on your computer you can always come back to — like a checkpoint, just for you.',
+    placement: 'left',
+  },
+  {
+    target: "[data-tour='publish']",
+    changes: true,
+    title: 'Publish for everyone',
+    body: 'Ready to share? Publish sends your saved work to the whole team. Think of it as putting your version on the shared shelf.',
+    placement: 'left',
+  },
+  {
+    target: "[data-tour='pull']",
+    changes: true,
+    title: 'Pull changes',
+    body: 'When teammates publish, Pull brings their work onto your computer so you’re both looking at the same thing.',
+    placement: 'left',
+  },
+  {
+    target: "[data-tour='status']",
+    title: 'Being together is automatic',
+    body: 'Cursors, who’s here, and comments need no buttons at all. When you’re both in a canvas, you see each other live — that’s the top layer, always on.',
+    placement: 'bottom',
+  },
+  {
+    // Centered — the one honest hard thing.
+    title: 'The one thing worth knowing',
+    body: 'When you’re here together, publishing already covers your teammate — they’ve seen it live, so Publish is just dropping a bookmark. Only when you work apart can two versions drift. If that happens, Maude shows you both and lets you pick — keep mine, keep theirs, or keep both. Never a confusing merge.',
+  },
+];

package/apps/studio/client/tour/overlay.jsx

@@ -1,10 +1,23 @@
 // overlay.jsx — hand-rolled guided-tour engine (zero runtime dep, DDR-B).
 //
-// One <TourOverlay steps={[…]} open onClose onComplete/> drives both the
-// per-feature spotlight tours (a What's New entry's `tour[]`) and the evergreen
-// usage tour. A step = { target (CSS selector / [data-tour] anchor), title,
-// body, placement? }. A step whose target can't be resolved still shows, just
-// centered with no spotlight — the tour never dead-ends on a missing element.
+// One <TourOverlay steps={[…]} open onClose onComplete bus hasSelection hasCanvas/>
+// drives both the per-feature spotlight tours (a What's New entry's `tour[]`) and
+// the evergreen usage tour.
+//
+// A step is { target, title, body, placement?, ...setup }. The engine does more
+// than spotlight: before each step it puts the shell into the state the target
+// needs, then waits for the element to actually render before measuring — so the
+// tour *walks the user through the live feature* instead of floating a modal over
+// a missing element. Setup directives (all optional):
+//   canvas: true            → ensure a canvas is open (bus.setup opens the first)
+//   inspector: true         → open the right-hand Inspector
+//   tab: 'inspect'|'layers'|'css'  → switch the Inspector tab
+//   requireSelection: true  → the target only exists once an element is ⌘-clicked
+//                             in the canvas; the card shows a "⌘-click to continue"
+//                             hint and the spotlight snaps onto the real row the
+//                             moment a selection lands.
+// A step whose target still can't be resolved shows centered (no spotlight) — the
+// tour never dead-ends on a missing element.
 //
 // A11y: role="dialog" + aria-modal, focus moves to the primary button on each
 // step and is trapped within the card, focus is restored on close, Esc skips,
@@ -26,7 +39,7 @@ function getRect(target) {
 }
 
 const CARD_W = 320;
-const CARD_H_EST = 168;
+const CARD_H_EST = 184;
 
 function computeCardStyle(rect) {
   if (typeof window === 'undefined' || !rect) {
@@ -34,6 +47,13 @@ function computeCardStyle(rect) {
   }
   const vw = window.innerWidth;
   const vh = window.innerHeight;
+  const placeLeft = rect.left > CARD_W + 36 && vw - rect.right < CARD_W + 36;
+  if (placeLeft) {
+    // Panel-on-the-right targets (the Inspector): park the card to its left so it
+    // never covers the very thing it's pointing at.
+    const top = Math.min(Math.max(12, rect.top), vh - CARD_H_EST - 12);
+    return { top, left: Math.max(12, rect.left - CARD_W - 16), width: CARD_W };
+  }
   const roomBelow = vh - rect.bottom;
   const top =
     roomBelow > CARD_H_EST + 24 ? rect.bottom + 12 : Math.max(12, rect.top - CARD_H_EST - 12);
@@ -41,29 +61,84 @@ function computeCardStyle(rect) {
   return { top, left, width: CARD_W };
 }
 
-export function TourOverlay({ steps, open, onClose, onComplete }) {
+export function TourOverlay({ steps, open, onClose, onComplete, bus, hasSelection, hasCanvas }) {
   const [i, setI] = useState(0);
   const [rect, setRect] = useState(null);
   const cardRef = useRef(null);
   const prevFocus = useRef(null);
+  const pollRef = useRef(null);
+  // The bus is rebuilt by the parent on every render; ref it so its identity
+  // churn never re-triggers the per-step setup effect (which would thrash).
+  const busRef = useRef(bus);
+  busRef.current = bus;
+
+  const step = steps[i] || null;
 
   const measure = useCallback(() => {
-    const step = steps[i];
-    setRect(step ? getRect(step.target) : null);
-  }, [steps, i]);
+    if (!step) {
+      setRect(null);
+      return null;
+    }
+    const r = getRect(step.target);
+    setRect(r);
+    return r;
+  }, [step]);
 
   // Reset to the first step whenever a tour (re)opens.
   useEffect(() => {
     if (open) setI(0);
   }, [open]);
 
+  // Per-step: run the step's setup (open canvas / inspector / switch tab), then
+  // poll for the target to render before settling on a measurement. React state
+  // updates + the canvas-shell round-trip are async, so a single synchronous
+  // querySelector almost always misses on the first frame.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: re-run only on step/selection change; bus + measure reached via ref/stable closures on purpose.
   useLayoutEffect(() => {
-    if (open) measure();
-  }, [open, measure]);
+    if (!open || !step) return undefined;
+    let cancelled = false;
+    setRect(null);
+
+    // Establish the UI state this step wants to highlight.
+    try {
+      busRef.current?.setup?.(step);
+    } catch {}
+
+    let tries = 0;
+    const MAX = 24; // ~3s at 130ms
+    const tick = () => {
+      if (cancelled) return;
+      const r = measure();
+      const settled = r || tries >= MAX;
+      if (settled) {
+        if (r) {
+          try {
+            document.querySelector(step.target)?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+          } catch {}
+          // Re-measure after the scroll so the spotlight is glued post-layout.
+          requestAnimationFrame(() => {
+            if (!cancelled) measure();
+          });
+        }
+        return;
+      }
+      tries += 1;
+      pollRef.current = setTimeout(tick, 130);
+    };
+    tick();
+
+    return () => {
+      cancelled = true;
+      if (pollRef.current) clearTimeout(pollRef.current);
+    };
+    // Re-run when the step changes OR a selection arrives (a requireSelection
+    // target pops into existence the moment the user ⌘-clicks). `bus`/`measure`
+    // are reached through refs/stable closures to avoid identity-churn re-runs.
+  }, [open, i, hasSelection]);
 
   // Keep the spotlight glued to its target through scroll/resize; restore focus.
   useEffect(() => {
-    if (!open) return;
+    if (!open) return undefined;
     prevFocus.current = document.activeElement;
     const onMove = () => measure();
     window.addEventListener('resize', onMove);
@@ -90,7 +165,7 @@ export function TourOverlay({ steps, open, onClose, onComplete }) {
 
   // Keyboard: Esc skips, ←/→ navigate, Tab is trapped within the card buttons.
   useEffect(() => {
-    if (!open) return;
+    if (!open) return undefined;
     function onKey(e) {
       if (e.key === 'Escape') {
         e.preventDefault();
@@ -123,7 +198,7 @@ export function TourOverlay({ steps, open, onClose, onComplete }) {
 
   // Move focus to the primary action on each step (accessible dialog behavior).
   useEffect(() => {
-    if (!open) return;
+    if (!open) return undefined;
     const t = setTimeout(() => {
       const primary = cardRef.current?.querySelector('[data-tour-primary]');
       try {
@@ -133,8 +208,7 @@ export function TourOverlay({ steps, open, onClose, onComplete }) {
     return () => clearTimeout(t);
   }, [open, i]);
 
-  if (!open || !steps.length) return null;
-  const step = steps[i];
+  if (!open || !steps.length || !step) return null;
   const pad = 6;
   const spot = rect
     ? {
@@ -145,6 +219,17 @@ export function TourOverlay({ steps, open, onClose, onComplete }) {
       }
     : null;
 
+  // A requireSelection step whose target hasn't materialized yet: tell the user
+  // the one action only they can take (the canvas iframe is cross-origin, so the
+  // tour can't ⌘-click for them — DDR-054).
+  const needSelHint = !!step.requireSelection && !hasSelection;
+  const needCanvasHint = (!!step.canvas || !!step.requireSelection) && hasCanvas === false;
+
+  // Optional per-step graphic (Phase 29 / E4): a component drawn above the copy —
+  // the collab tour uses it for the centered two-layer infographic step. Widens the
+  // card so the diagram has room.
+  const Graphic = step.render || null;
+
   return (
     <div className="mdcc-tour" role="presentation">
       {spot ? (
@@ -153,7 +238,7 @@ export function TourOverlay({ steps, open, onClose, onComplete }) {
         <div className="mdcc-tour__scrim" aria-hidden="true" />
       )}
       <div
-        className="mdcc-tour__card"
+        className={'mdcc-tour__card' + (Graphic ? ' mdcc-tour__card--graphic' : '')}
         ref={cardRef}
         role="dialog"
         aria-modal="true"
@@ -164,12 +249,25 @@ export function TourOverlay({ steps, open, onClose, onComplete }) {
         <div className="mdcc-tour__step">
           {i + 1} / {steps.length}
         </div>
+        {Graphic && (
+          <div className="mdcc-tour__graphic">
+            <Graphic />
+          </div>
+        )}
         <div className="mdcc-tour__title" id="mdcc-tour-title">
           {step.title}
         </div>
         <div className="mdcc-tour__body" id="mdcc-tour-body">
           {step.body}
         </div>
+        {(needCanvasHint || needSelHint) && (
+          <div className="mdcc-tour__hint" role="status" aria-live="polite">
+            <span className="mdcc-tour__hint-dot" aria-hidden="true" />
+            {needCanvasHint
+              ? 'Open any canvas from the sidebar to follow along.'
+              : 'Hold ⌘ and click an element in the canvas — the panel fills in live.'}
+          </div>
+        )}
         <div className="mdcc-tour__actions">
           <button type="button" className="mdcc-tour__skip" onClick={onClose}>
             Skip

package/apps/studio/client/tour/usage-tour.js

@@ -1,35 +1,48 @@
 // usage-tour.js — the evergreen "how the Maude UI works" walkthrough.
 //
-// Targets stable elements that exist at first load (no canvas open required):
-// the sidebar, the empty viewport, the menus, the What's New badge, and Help.
-// Steps whose target is missing are shown centered by the overlay, so this is
-// resilient to chrome changes. Reached from Help → "Take the tour" and offered
-// once on first run.
+// Targets stable [data-tour] anchors (redesign-proof — styling classes get
+// renamed, these don't) on elements that exist at first load: the sidebar, the
+// viewport, the menus, the Inspector, the What's New badge, and Help. The
+// Inspector step carries `inspector: true` so the engine opens the panel before
+// spotlighting it. Steps whose target is missing are shown centered by the
+// overlay, so this stays resilient to chrome changes. Reached from Help →
+// "Take the tour" and offered once on first run.
 
 export const USAGE_TOUR = [
   {
-    target: '.sidebar',
+    target: "[data-tour='sidebar']",
     title: 'Your canvases live here',
     body: 'Every mock in the project shows up in this tree. Click one to open it in a tab — or use “+ board” to spin up a blank brief-board, no command needed.',
+    placement: 'right',
   },
   {
-    target: '.viewport',
+    target: "[data-tour='viewport']",
     title: 'The canvas',
     body: 'Open a canvas, then ⌘-hover to preview the element under your cursor and ⌘-click to select it. Right-click for Copy CSS / Fit / Reset.',
   },
   {
-    target: '.mb-menus',
+    target: "[data-tour='menus']",
     title: 'Menus & tools',
-    body: 'View toggles panels (tree, comments, annotations); Selection and Tools act on the active canvas. Press ? for every shortcut.',
+    body: 'View toggles panels (tree, comments, Inspector); Selection and Tools act on the active canvas. Press ? for every shortcut.',
+    placement: 'bottom',
+  },
+  {
+    target: "[data-tour='inspector']",
+    inspector: true,
+    title: 'The Inspector',
+    body: 'Opened from View → Inspector (or press I). Inspect · Layers · CSS — ⌘-click any element and edit its CSS against your design tokens, right here. No AI round-trip.',
+    placement: 'left',
   },
   {
     target: "[data-tour='whatsnew']",
     title: 'What’s new',
-    body: 'New features land here. Click the ✦ badge any time to catch up on what shipped.',
+    body: 'New features land here. Click the ✦ badge any time to catch up on what shipped — some entries come with a guided tour like this one.',
+    placement: 'bottom',
   },
   {
     target: "[data-tour='help']",
     title: 'Help is one key away',
     body: 'Press ? for the full keyboard cheat-sheet — and you can restart this tour from the Help menu whenever you like.',
+    placement: 'bottom',
   },
 ];

package/apps/studio/client/whats-new.jsx

@@ -48,20 +48,35 @@ export function useWhatsNew(currentVersion) {
   const [toastDismissed, setToastDismissed] = useState(() => readToastDismissed());
   const [panelOpen, setPanelOpen] = useState(false);
 
+  // Fetch the feed on mount AND whenever the window regains focus (Phase 32 /
+  // Task 5). The native shell can sit backgrounded for a long time; an auto-update
+  // (or a deploy of the web studio) bumps the feed while we're not looking, so we
+  // re-evaluate on focus to surface the ✦ badge without a full reload.
   useEffect(() => {
     let cancelled = false;
-    fetch('/_api/whats-new')
-      .then((r) => r.json())
-      .then((j) => {
-        if (cancelled) return;
-        setEntries(Array.isArray(j?.entries) ? j.entries : []);
-        if (typeof j?.version === 'string') setFeedVersion(j.version);
-      })
-      .catch(() => {
-        /* offline / restart — no banner */
-      });
+    const refresh = () => {
+      fetch('/_api/whats-new')
+        .then((r) => r.json())
+        .then((j) => {
+          if (cancelled) return;
+          setEntries(Array.isArray(j?.entries) ? j.entries : []);
+          if (typeof j?.version === 'string') setFeedVersion(j.version);
+        })
+        .catch(() => {
+          /* offline / restart — no banner */
+        });
+    };
+    refresh();
+    const onFocus = () => refresh();
+    const onVisible = () => {
+      if (document.visibilityState === 'visible') refresh();
+    };
+    window.addEventListener('focus', onFocus);
+    document.addEventListener('visibilitychange', onVisible);
     return () => {
       cancelled = true;
+      window.removeEventListener('focus', onFocus);
+      document.removeEventListener('visibilitychange', onVisible);
     };
   }, []);
 

package/apps/studio/collab/registry.ts

@@ -58,6 +58,14 @@ export interface Registry {
    * updated stroke set without waiting for a cold-open re-seed.
    */
   syncRoomFromAnnotations(slug: string, svg: string): void;
+  /**
+   * Phase 30 — project agent editing-presence onto a slug's room awareness so
+   * it crosses the hub (the loopback `ai-activity` bus event does not). `null`
+   * clears it. No-op when no room is live for the slug — a peer that joins
+   * later will see the agent on the next ai-activity heartbeat. Soft heads-up;
+   * never a lock.
+   */
+  setAgentEditing(slug: string, state: { name: string; since: number } | null): void;
   /**
    * Phase 9 Task 5 — attach the hub-side Awareness (from a sync provider) for
    * a slug so the Room's Awareness (browser peers) is bridged bidirectionally
@@ -192,6 +200,10 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
     }, 'inspector-write');
   }
 
+  function setAgentEditing(slug: string, state: { name: string; since: number } | null): void {
+    rooms.get(slug)?.setAgentEditing(state);
+  }
+
   async function flushAll(): Promise<void> {
     await Promise.all(Array.from(rooms.values(), (r) => r.flush()));
   }
@@ -227,6 +239,7 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
     getDoc,
     syncRoomFromComments,
     syncRoomFromAnnotations,
+    setAgentEditing,
     attachHubAwareness,
     pin,
     unpin,

package/apps/studio/collab/room.ts

@@ -57,6 +57,15 @@ export interface Room {
   connect(conn: RoomConn): Promise<void>;
   disconnect(conn: RoomConn): void;
   receive(conn: RoomConn, payload: Uint8Array): void;
+  /**
+   * Phase 30 — project an agent's "editing" activity onto this room's awareness
+   * using the room's own (otherwise-unused) local awareness slot, so the soft
+   * editing-presence crosses the hub to remote peers (the loopback `ai-activity`
+   * bus event does not). `null` clears it. Idempotent — a re-set of the same
+   * `{name, since}` is a no-op (ai-activity heartbeats re-emit every 10 s).
+   * NOT a lock; never blocks a peer.
+   */
+  setAgentEditing(state: { name: string; since: number } | null): void;
   /** Force the debounced flush to fire now. DDR-051 §3 (branch-switch). */
   flush(): Promise<void>;
   /** Tear down — clears timers + removes awareness. */
@@ -192,6 +201,32 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
     if (reply) conn.send(reply);
   }
 
+  // Phase 30 — agent editing-presence projected onto the room's own awareness
+  // slot. The key short-circuits redundant re-sets (ai-activity heartbeats
+  // re-emit the same entry every 10 s). The awareness `update` handler above
+  // broadcasts the change to local conns AND relays it to the hub via
+  // bridgeAwareness, so a remote peer's overlay attributes the edit.
+  let agentEditingKey: string | null = null;
+  function setAgentEditing(state: { name: string; since: number } | null): void {
+    if (destroyed) return;
+    const key = state ? `${state.name}${state.since}` : null;
+    if (key === agentEditingKey) return;
+    agentEditingKey = key;
+    if (state === null) {
+      awareness.setLocalState(null);
+      return;
+    }
+    awareness.setLocalState({
+      name: state.name,
+      color: '', // re-derived client-side from name; wire value is discarded
+      cursor: null,
+      selection: null,
+      annotationSelection: [],
+      viewport: { x: 0, y: 0, zoom: 1 },
+      editing: { since: state.since },
+    });
+  }
+
   async function destroy(): Promise<void> {
     destroyed = true;
     if (flushTimer) {
@@ -211,6 +246,7 @@ export function createRoom(slug: string, callbacks: RoomCallbacks): Room {
     connect,
     disconnect,
     receive,
+    setAgentEditing,
     flush,
     destroy,
     size: () => conns.size,

package/apps/studio/commands/annotation-strokes-command.ts

@@ -20,7 +20,7 @@
  */
 
 import type { Stroke } from '../annotations-layer.tsx';
-import type { CommandRecord, CommandSinks, EditCommand } from '../undo-stack.ts';
+import type { CommandRecord, EditCommand } from '../undo-stack.ts';
 import { registerCommand } from '../undo-stack.ts';
 
 /**

package/apps/studio/commands/move-artboards-command.ts

@@ -17,7 +17,7 @@
  * stale layout.
  */
 
-import type { CommandRecord, CommandSinks, EditCommand } from '../undo-stack.ts';
+import type { CommandRecord, EditCommand } from '../undo-stack.ts';
 import { registerCommand } from '../undo-stack.ts';
 
 export interface ArtboardLayoutEntry {

package/apps/studio/comments-overlay.tsx

@@ -161,7 +161,7 @@ function screenRectFor(
   } catch {
     return null;
   }
-  if (!el || !el.isConnected) return null;
+  if (!el?.isConnected) return null;
   const r = el.getBoundingClientRect();
   if (r.width === 0 && r.height === 0) return null;
   return { x: r.left, y: r.top, w: r.width, h: r.height };
@@ -204,7 +204,7 @@ export function CommentsOverlay(): React.ReactNode {
   const mirrorSelection = useCallback(
     (comment: OverlayComment | undefined) => {
       if (!selSet) return;
-      if (!comment || !comment.selector) {
+      if (!comment?.selector) {
         selSet.clear();
         return;
       }
@@ -298,7 +298,7 @@ export function CommentsOverlay(): React.ReactNode {
       const detail = (
         e as CustomEvent<{ selection?: ComposeSelection; clientX?: number; clientY?: number }>
       ).detail;
-      if (!detail || !detail.selection) return;
+      if (!detail?.selection) return;
       setComposer({
         selection: detail.selection,
         clientX: typeof detail.clientX === 'number' ? detail.clientX : 0,
@@ -383,7 +383,9 @@ export function CommentsOverlay(): React.ReactNode {
   const indexById = useMemo(() => {
     const m = new Map<string, number>();
     const all = comments.slice().sort((a, b) => a.created.localeCompare(b.created));
-    all.forEach((c, i) => m.set(c.id, i + 1));
+    all.forEach((c, i) => {
+      m.set(c.id, i + 1);
+    });
     return m;
   }, [comments]);
 
@@ -784,7 +786,7 @@ function CommentPin({
     return () => {
       if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
     };
-  }, [comment.selector, comment.bounds]);
+  }, [comment.selector, comment.bounds, comment.index]);
 
   const author = comment.author?.trim() || 'unknown';
   const label = `Comment ${sequence} by ${author}`;

package/apps/studio/context-menu.tsx

@@ -237,7 +237,9 @@ const MENU_CSS = `
 .dc-context-menu .dc-menu-flyout.is-flip { left: auto; right: calc(100% + 3px); }
 `.trim();
 
-function ensureMenuStyles(): void {
+// Exported (FigJam v3) — the annotation layer's right-click menu reuses the
+// same .dc-context-menu visual language without duplicating the stylesheet.
+export function ensureMenuStyles(): void {
   if (typeof document === 'undefined') return;
   if (document.getElementById('dc-context-menu-css')) return;
   const s = document.createElement('style');
@@ -342,7 +344,7 @@ function ContextMenuView({
           el.querySelectorAll<HTMLButtonElement>('button.dc-menu-item:not([disabled])')
         );
         if (items.length === 0) return;
-        const idx = items.findIndex((b) => b === document.activeElement);
+        const idx = items.indexOf(document.activeElement);
         const nextIdx =
           e.key === 'ArrowDown'
             ? (idx + 1) % items.length
@@ -368,7 +370,6 @@ function ContextMenuView({
       {sections.map((section, si) => {
         const sectionKey = section.map((i) => i.id).join('|') || `s${si}`;
         return (
-          // biome-ignore lint/a11y/useSemanticElements: ARIA group within role="menu"; no native equivalent.
           <div key={sectionKey} role="group">
             {si > 0 ? <div className="dc-menu-sep" aria-hidden="true" /> : null}
             {section.map((item) => (

package/apps/studio/contextual-toolbar.tsx

@@ -207,6 +207,20 @@ export function ContextualToolbar() {
   return (
     <div ref={ref} className="dc-elem-ctx-tb" role="toolbar" aria-label="Element actions">
       <span className="dc-elem-ctx-count">{count === 1 ? '1 element' : `${count} elements`}</span>
+      <button
+        type="button"
+        title="Inspect — open the right panel (Inspect / Layers / CSS)"
+        onClick={() => {
+          // Phase 12 — open the shell's Inspector on the current selection.
+          try {
+            window.parent.postMessage({ dgn: 'open-inspector' }, '*');
+          } catch {
+            /* detached / cross-origin */
+          }
+        }}
+      >
+        Inspect
+      </button>
       <button
         type="button"
         title="Copy CSS selector"