@1agh/maude 0.29.0 → 0.30.0

package/apps/studio/client/styles/4-components.css

@@ -1353,6 +1353,45 @@
   color: var(--u-fg-2);
   margin-bottom: 14px;
 }
+/* "Do this one thing" hint — shown when a step needs a canvas open or an element
+   ⌘-clicked (the cross-origin canvas means the tour can't do it for you). */
+.mdcc-tour__hint {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: -4px 0 14px;
+  padding: 8px 10px;
+  border-radius: var(--radius-md);
+  background: color-mix(in oklab, var(--u-accent) 12%, transparent);
+  border: 1px solid color-mix(in oklab, var(--u-accent) 35%, transparent);
+  color: var(--u-fg-1);
+  font-size: 12px;
+  line-height: 1.4;
+}
+.mdcc-tour__hint-dot {
+  flex: none;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--u-accent);
+  animation: mdcc-tour-pulse 1.4s ease-in-out infinite;
+}
+@keyframes mdcc-tour-pulse {
+  0%,
+  100% {
+    opacity: 0.4;
+    transform: scale(0.85);
+  }
+  50% {
+    opacity: 1;
+    transform: scale(1.15);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .mdcc-tour__hint-dot {
+    animation: none;
+  }
+}
 .mdcc-tour__actions {
   display: flex;
   align-items: center;

package/apps/studio/client/styles/5-maude-overrides.css

@@ -25,6 +25,9 @@
 .maude .help-modal-hd {
   border-bottom: 1px solid var(--border-subtle);
   background: var(--bg-1);
+  /* title + SKU sat glued together (flex space-between, no gap) */
+  justify-content: flex-start;
+  gap: var(--space-4);
 }
 .maude .help-modal-hd .title { font-family: var(--font-display); font-weight: 600; letter-spacing: var(--tracking-tight); text-transform: none; color: var(--fg-0); }
 .maude .help-modal-hd .sku { font-family: var(--font-mono); color: var(--fg-3); }
@@ -65,6 +68,8 @@
 .maude .mdcc-tour-nudge {
   background: var(--bg-2); border: 1px solid var(--border-default); border-left: 3px solid var(--accent);
   border-radius: var(--radius-md); box-shadow: var(--shadow-lg); font-family: var(--font-body); color: var(--fg-1);
+  /* raised above the in-canvas zoom pill (bottom-left), same as .st-toast */
+  bottom: 84px;
 }
 .maude .mdcc-tour-nudge__cta { background: var(--accent); color: var(--accent-fg); border: 0; border-radius: var(--radius-sm); font-family: var(--font-body); font-weight: 500; }
 .maude .mdcc-tour-nudge__cta:hover { background: var(--accent-hover); }
@@ -108,8 +113,17 @@
 .maude .sv-h-num, .maude .sv-count { font-family: var(--font-mono); color: var(--fg-3); }
 .maude .sv-tok-cell { border: 1px solid var(--border-subtle); border-radius: var(--radius-sm); background: var(--bg-1); overflow: hidden; }
 .maude .sv-tok-swatch { border-radius: 0; }
-.maude .sv-tok-name { font-family: var(--font-mono); color: var(--fg-0); }
-.maude .sv-tok-value { font-family: var(--font-mono); color: var(--fg-2); }
+/* token meta — the legacy side-by-side row wrapped long names across 3 lines
+ * ("--presence-" / "offline"); stack name over value, each on one nowrap line. */
+.maude .sv-tok-meta {
+  flex-direction: column;
+  align-items: flex-start;
+  justify-content: flex-start;
+  gap: 1px;
+  padding: var(--space-2) var(--space-3);
+}
+.maude .sv-tok-name { font-family: var(--font-mono); color: var(--fg-0); white-space: nowrap; max-width: 100%; }
+.maude .sv-tok-value { font-family: var(--font-mono); color: var(--fg-2); max-width: 100%; }
 .maude .sv-type-row { border-bottom: 1px solid var(--border-subtle); }
 .maude .sv-type-tok { font-family: var(--font-mono); color: var(--fg-2); }
 .maude .sv-preview-card { border: 1px solid var(--border-subtle); border-radius: var(--radius-md); background: var(--bg-1); overflow: hidden; box-shadow: var(--shadow-sm); }

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,12 @@ 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;
+
   return (
     <div className="mdcc-tour" role="presentation">
       {spot ? (
@@ -170,6 +250,14 @@ export function TourOverlay({ steps, open, onClose, onComplete }) {
         <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/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"

package/apps/studio/cursors-overlay.tsx

@@ -43,24 +43,28 @@ const CURSOR_CSS = `
 }
 .dc-cursor-arrow {
   display: block;
-  filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.25));
+  filter: drop-shadow(0 1px 1px rgba(0, 0, 0, 0.4));
 }
+/* DS colors-presence .cur-label recipe — hue pill, mono 10px, dark
+ * accent-fg text (never white-on-hue, which washed out on light hues).
+ * NOTE: keep this comment backtick-free — it lives inside the CURSOR_CSS
+ * template literal and a stray backtick closes it. */
 .dc-cursor-label {
   position: absolute;
-  top: 18px;
-  left: 14px;
-  padding: 2px 6px;
-  font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
+  /* specimen geometry: the pill hangs below-right of the 15px triangle */
+  top: 14px;
+  left: 10px;
+  padding: 1px 8px;
+  font-family: var(--font-mono, ui-monospace, monospace);
   font-weight: 500;
-  font-size: 11px;
-  line-height: 1.2;
-  color: var(--maude-hud-accent-fg, #fff);
-  border-radius: var(--radius-sm, 2px);
+  font-size: 10px;
+  line-height: 1.4;
+  color: var(--maude-hud-accent-fg, oklch(0.180 0.030 268));
+  border-radius: 999px;
   white-space: nowrap;
   max-width: 180px;
   overflow: hidden;
   text-overflow: ellipsis;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
 }
 .dc-peer-selection {
   position: absolute;
@@ -117,20 +121,16 @@ const Cursor = memo(function Cursor({ peer, viewport }: CursorProps): JSX.Elemen
   const screenY = peer.cursor.y * viewport.zoom + viewport.y;
   return (
     <div className="dc-cursor" style={{ transform: `translate(${screenX}px, ${screenY}px)` }}>
+      {/* DS colors-presence Pointer — one plain triangle glyph, tinted by its
+          owner (the specimen's exact 24-grid path, no tail/notch). */}
       <svg
         className="dc-cursor-arrow"
-        width="20"
-        height="22"
-        viewBox="0 0 20 22"
+        width="15"
+        height="15"
+        viewBox="0 0 24 24"
         aria-hidden="true"
       >
-        <path
-          d="M 2 2 L 2 18 L 6 14 L 9 21 L 12 20 L 9 13 L 14 13 Z"
-          fill={peer.color}
-          stroke="#fff"
-          strokeWidth="1.2"
-          strokeLinejoin="round"
-        />
+        <path d="M4 3 L20 11.5 L12.5 13 L10 21 Z" fill={peer.color} />
       </svg>
       <div className="dc-cursor-label" style={{ background: peer.color }}>
         {peer.name}