@1agh/maude 0.28.1 → 0.30.0

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

@@ -0,0 +1,137 @@
+/* @layer components — maude redesign of the remaining legacy shell surfaces (Plan B).
+ *
+ * The HelpModal, in-app tour, what's-new (toast/panel), SystemView and CommentBar
+ * still carry their original project-DS "industrial catalogue" structure — hard
+ * offset shadows (`8px 8px 0`), full-contrast `--u-fg-0` borders, all-mono type,
+ * square edges, far-right-pushed description columns. Even after the `--u-*`
+ * bridge made them maude-COLORED, the STRUCTURE read as old. These overrides
+ * restyle them to the maude material (soft elevation, hairline borders, soft
+ * radii, Inter body + mono labels) WITHOUT rewriting their JSX. Scoped under
+ * `.maude` so they win over the legacy `@layer components` rules and only apply
+ * inside the studio shell. Remove a block once its surface is ported to `.st-*`.
+ */
+
+@layer components {
+
+/* ─── HelpModal ────────────────────────────────────────────────────────────── */
+.maude .help-modal {
+  background: var(--bg-2);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-lg);
+  font-family: var(--font-body);
+}
+.maude .help-modal-backdrop { background: color-mix(in oklab, var(--bg-0) 62%, transparent); }
+.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); }
+.maude .help-modal-close { color: var(--fg-2); border-radius: var(--radius-sm); }
+.maude .help-modal-close:hover { background: var(--bg-3); color: var(--fg-0); }
+.maude .help-modal-body details { border-bottom: 1px solid var(--border-subtle); }
+.maude .help-modal-body details > summary { color: var(--fg-2); font-family: var(--font-mono); letter-spacing: var(--tracking-wide); }
+.maude .help-modal-body details[open] > summary { color: var(--fg-0); }
+.maude .help-modal-body ul, .maude .help-modal-body ol { font-family: var(--font-body); }
+/* the load-bearing fix — descriptions sat far-right (margin-left:auto). Pull them
+   inline-left next to the key so each row reads as a definition, maude-style. */
+.maude .help-modal-body li { gap: var(--space-3); }
+.maude .help-modal-body li > span { margin-left: 0; text-align: left; color: var(--fg-2); font-size: var(--type-xs); }
+.maude .help-modal-body li > code,
+.maude .help-modal-body .cmds code { font-family: var(--font-mono); background: var(--bg-3); color: var(--accent); border-radius: var(--radius-xs); }
+.maude .help-modal-body kbd {
+  font-family: var(--font-mono); background: var(--bg-2); color: var(--fg-1);
+  border: 1px solid var(--border-default); border-bottom-width: 2px; border-radius: var(--radius-xs);
+}
+.maude .mdcc-tour__back { background: var(--bg-3); color: var(--fg-1); border: 1px solid var(--border-default); border-radius: var(--radius-sm); font-family: var(--font-body); }
+.maude .mdcc-tour__back:hover { background: var(--bg-4); color: var(--fg-0); }
+
+/* ─── In-app tour ──────────────────────────────────────────────────────────── */
+.maude .mdcc-tour__card, .mdcc-tour__card {
+  background: var(--bg-2); border: 1px solid var(--border-strong); border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-lg); font-family: var(--font-body); color: var(--fg-0);
+}
+.mdcc-tour__title { font-family: var(--font-display); font-weight: 600; letter-spacing: var(--tracking-tight); color: var(--fg-0); }
+.mdcc-tour__body { color: var(--fg-1); font-family: var(--font-body); }
+.mdcc-tour__step { font-family: var(--font-mono); color: var(--fg-3); }
+.mdcc-tour__spot { border-radius: var(--radius-md); box-shadow: 0 0 0 2px var(--accent), 0 0 0 9999px color-mix(in oklab, var(--bg-0) 55%, transparent); }
+.mdcc-tour__next { background: var(--accent); color: var(--accent-fg); border: 1px solid var(--accent); border-radius: var(--radius-sm); font-family: var(--font-body); font-weight: 500; }
+.mdcc-tour__next:hover { background: var(--accent-hover); border-color: var(--accent-hover); }
+.mdcc-tour__skip { background: transparent; color: var(--fg-2); border: 0; font-family: var(--font-body); }
+.mdcc-tour__skip:hover { color: var(--fg-0); }
+
+/* tour nudge (first-run) */
+.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); }
+.maude .mdcc-tour-nudge__skip { color: var(--fg-3); }
+.maude .mdcc-tour-nudge__skip:hover { color: var(--fg-0); }
+
+/* ─── What's-new (toast / panel) ───────────────────────────────────────────── */
+.maude .mdcc-wn-toast, .mdcc-wn-toast {
+  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);
+}
+.mdcc-wn-toast__mark { color: var(--accent); }
+.mdcc-wn-toast__title { font-family: var(--font-display); font-weight: 600; color: var(--fg-0); }
+.mdcc-wn-toast__summary { color: var(--fg-1); }
+.mdcc-wn-toast__cta { background: var(--accent); color: var(--accent-fg); border: 0; border-radius: var(--radius-sm); font-family: var(--font-body); font-weight: 500; }
+.mdcc-wn-toast__cta:hover { background: var(--accent-hover); }
+.mdcc-wn-toast__close { color: var(--fg-3); border-radius: var(--radius-sm); }
+.mdcc-wn-toast__close:hover { background: var(--bg-3); color: var(--fg-0); }
+.maude .mdcc-wn-panel, .mdcc-wn-panel {
+  background: var(--bg-2); border: 1px solid var(--border-strong); border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-lg); font-family: var(--font-body); color: var(--fg-0);
+}
+.mdcc-wn-item { border-bottom: 1px solid var(--border-subtle); }
+.mdcc-wn-item__title { font-family: var(--font-display); font-weight: 600; color: var(--fg-0); }
+.mdcc-wn-item__ver { font-family: var(--font-mono); color: var(--fg-3); }
+.mdcc-wn-item__summary { color: var(--fg-1); }
+.mdcc-wn-kind { font-family: var(--font-mono); letter-spacing: var(--tracking-wide); text-transform: uppercase; font-size: 10px; color: var(--accent); background: var(--accent-tint); border-radius: var(--radius-pill); padding: 1px 7px; }
+.mdcc-wn-item__tour, .mdcc-wn-item__more { color: var(--accent); font-family: var(--font-body); background: transparent; border: 0; }
+.mdcc-wn-empty { color: var(--fg-3); }
+
+/* ─── SystemView (DS overview) ─────────────────────────────────────────────── */
+.maude .sv { font-family: var(--font-body); color: var(--fg-0); }
+.maude .sv-header { border-bottom: 1px solid var(--border-subtle); }
+.maude .sv-sku { font-family: var(--font-mono); color: var(--accent); letter-spacing: var(--tracking-wide); }
+.maude .sv-title { font-family: var(--font-display); font-weight: 600; letter-spacing: var(--tracking-tight); color: var(--fg-0); text-transform: none; }
+.maude .sv-loc code { font-family: var(--font-mono); color: var(--fg-3); }
+.maude .sv-ds-picker { font-family: var(--font-mono); color: var(--fg-2); }
+.maude .sv-ds-picker select { background: var(--bg-3); color: var(--fg-0); border: 1px solid var(--border-default); border-radius: var(--radius-sm); font-family: var(--font-mono); padding: 2px 6px; }
+.maude .sv-ds-description { color: var(--fg-1); font-family: var(--font-body); }
+.maude .sv-section h2 { font-family: var(--font-mono); color: var(--fg-2); letter-spacing: var(--tracking-wide); text-transform: uppercase; font-size: var(--type-xs); border-bottom: 1px solid var(--border-subtle); }
+.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; }
+/* 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); }
+.maude .sv-preview-card:hover { border-color: var(--border-default); box-shadow: var(--shadow-md); }
+.maude .sv-preview-foot { font-family: var(--font-mono); }
+.maude .sv-preview-foot strong { color: var(--fg-0); font-family: var(--font-body); }
+.maude .sv-preview-foot code { color: var(--fg-3); }
+.maude .sv-empty { color: var(--fg-3); }
+.maude .sv-empty code { font-family: var(--font-mono); background: var(--bg-3); color: var(--accent); border-radius: var(--radius-xs); padding: 1px 5px; }
+
+}

package/{plugins/design/dev-server → apps/studio}/client/styles/_index.css

@@ -18,7 +18,16 @@
 
 @import url('./0-reset.css');
 @import url('./1-tokens.css');
+/* Plan B — maude DS token ladder, scoped under `.maude[data-theme]` (additive;
+   drives the rewritten `.st-*` chrome without disturbing the legacy amber tokens). */
+@import url('./1-tokens-maude.css');
 @import url('./2-layout.css');
 @import url('./3-shell.css');
+/* Plan B — maude DS studio chrome (.st-* ported from Studio.css), grown per slice. */
+@import url('./3-shell-maude.css');
 @import url('./4-components.css');
+/* Plan B — maude DS shared component classes (.btn/.kbd/.callout), scoped under `.maude`. */
+@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');
 @import url('./5-utilities.css');

package/{plugins/design/dev-server → apps/studio}/client/styles.css

@@ -974,7 +974,7 @@ button { font: inherit; }
 }
 /* Phase 6 — the shell-side composer / focused-row / pin-strip surfaces are
  * gone; pins + composer + thread popover live inside the canvas iframe
- * (plugins/design/dev-server/comments-overlay.{tsx,css}). The remaining
+ * (apps/studio/comments-overlay.{tsx,css}). The remaining
  * `.comment-bar` and `.cb-row.strip` rules below render the residual
  * open-count summary the shell still surfaces in the BottomBar. */
 

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

@@ -0,0 +1,279 @@
+// overlay.jsx — hand-rolled guided-tour engine (zero runtime dep, DDR-B).
+//
+// 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,
+// ←/→ navigate. prefers-reduced-motion disables the spotlight transition.
+
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+function getRect(target) {
+  if (typeof document === 'undefined' || !target) return null;
+  try {
+    const el = document.querySelector(target);
+    if (!el) return null;
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) return null;
+    return r;
+  } catch {
+    return null;
+  }
+}
+
+const CARD_W = 320;
+const CARD_H_EST = 184;
+
+function computeCardStyle(rect) {
+  if (typeof window === 'undefined' || !rect) {
+    return { top: '50%', left: '50%', transform: 'translate(-50%, -50%)', width: CARD_W };
+  }
+  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);
+  const left = Math.min(Math.max(12, rect.left), vw - CARD_W - 12);
+  return { top, left, width: CARD_W };
+}
+
+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(() => {
+    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 || !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 undefined;
+    prevFocus.current = document.activeElement;
+    const onMove = () => measure();
+    window.addEventListener('resize', onMove);
+    window.addEventListener('scroll', onMove, true);
+    return () => {
+      window.removeEventListener('resize', onMove);
+      window.removeEventListener('scroll', onMove, true);
+      try {
+        prevFocus.current?.focus?.();
+      } catch {}
+    };
+  }, [open, measure]);
+
+  const last = i >= steps.length - 1;
+  const next = useCallback(() => {
+    if (last) {
+      onComplete?.();
+      onClose?.();
+    } else {
+      setI((n) => Math.min(n + 1, steps.length - 1));
+    }
+  }, [last, onComplete, onClose, steps.length]);
+  const back = useCallback(() => setI((n) => Math.max(0, n - 1)), []);
+
+  // Keyboard: Esc skips, ←/→ navigate, Tab is trapped within the card buttons.
+  useEffect(() => {
+    if (!open) return undefined;
+    function onKey(e) {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onClose?.();
+      } else if (e.key === 'ArrowRight') {
+        e.preventDefault();
+        next();
+      } else if (e.key === 'ArrowLeft') {
+        e.preventDefault();
+        back();
+      } else if (e.key === 'Tab') {
+        const card = cardRef.current;
+        if (!card) return;
+        const f = card.querySelectorAll('button');
+        if (!f.length) return;
+        const first = f[0];
+        const lastEl = f[f.length - 1];
+        if (e.shiftKey && document.activeElement === first) {
+          e.preventDefault();
+          lastEl.focus();
+        } else if (!e.shiftKey && document.activeElement === lastEl) {
+          e.preventDefault();
+          first.focus();
+        }
+      }
+    }
+    window.addEventListener('keydown', onKey, true);
+    return () => window.removeEventListener('keydown', onKey, true);
+  }, [open, next, back, onClose]);
+
+  // Move focus to the primary action on each step (accessible dialog behavior).
+  useEffect(() => {
+    if (!open) return undefined;
+    const t = setTimeout(() => {
+      const primary = cardRef.current?.querySelector('[data-tour-primary]');
+      try {
+        primary?.focus();
+      } catch {}
+    }, 0);
+    return () => clearTimeout(t);
+  }, [open, i]);
+
+  if (!open || !steps.length || !step) return null;
+  const pad = 6;
+  const spot = rect
+    ? {
+        top: rect.top - pad,
+        left: rect.left - pad,
+        width: rect.width + pad * 2,
+        height: rect.height + pad * 2,
+      }
+    : 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 ? (
+        <div className="mdcc-tour__spot" style={spot} aria-hidden="true" />
+      ) : (
+        <div className="mdcc-tour__scrim" aria-hidden="true" />
+      )}
+      <div
+        className="mdcc-tour__card"
+        ref={cardRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="mdcc-tour-title"
+        aria-describedby="mdcc-tour-body"
+        style={computeCardStyle(rect)}
+      >
+        <div className="mdcc-tour__step">
+          {i + 1} / {steps.length}
+        </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
+          </button>
+          <div className="mdcc-tour__nav">
+            {i > 0 && (
+              <button type="button" className="mdcc-tour__back" onClick={back}>
+                Back
+              </button>
+            )}
+            <button type="button" className="mdcc-tour__next" data-tour-primary onClick={next}>
+              {last ? 'Done' : 'Next'}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,48 @@
+// usage-tour.js — the evergreen "how the Maude UI works" walkthrough.
+//
+// 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: "[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: "[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: "[data-tour='menus']",
+    title: 'Menus & tools',
+    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 — 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-seen.js

@@ -0,0 +1,52 @@
+// whats-new-seen.js — pure, browser-safe "what have I already seen?" logic.
+//
+// No React, no DOM, no node imports — so it's bundled into the client AND
+// imported directly by bun:test (test/whats-new.test.ts). Keep it that way.
+
+/** Parse a semver-ish string into a [major, minor, patch] triple, or null. */
+export function parseVer(v) {
+  if (typeof v !== 'string') return null;
+  const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/**
+ * Is version `a` strictly newer than `b`?
+ * - Unparseable `a` (e.g. "dev") → not newer (false).
+ * - Unparseable `b` but parseable `a` → newer (true): a real release outranks
+ *   a non-version "seen" marker, so the entry surfaces.
+ */
+export function verGt(a, b) {
+  const pa = parseVer(a);
+  const pb = parseVer(b);
+  if (!pa) return false;
+  if (!pb) return true;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] > pb[i];
+  }
+  return false;
+}
+
+/**
+ * Entries the user hasn't seen yet, given the version they last acknowledged.
+ * A pending entry (version == null) is always unseen until acknowledged.
+ */
+export function computeUnseen(entries, seenVersion) {
+  if (!Array.isArray(entries)) return [];
+  return entries.filter((e) => e && (e.version == null || verGt(e.version, seenVersion)));
+}
+
+/**
+ * The version to persist as "seen" after the user reads the panel — the highest
+ * of the current feed version and every entry's version. Stamping this clears
+ * the unseen set (pending entries excepted — they have no version to outrank).
+ */
+export function bestSeenVersion(entries, currentVersion) {
+  let best = currentVersion;
+  if (Array.isArray(entries)) {
+    for (const e of entries) {
+      if (e && e.version && verGt(e.version, best)) best = e.version;
+    }
+  }
+  return best;
+}