@1agh/maude 0.28.0 → 0.29.0

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

@@ -0,0 +1,191 @@
+// 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.
+//
+// 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 = 168;
+
+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 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 }) {
+  const [i, setI] = useState(0);
+  const [rect, setRect] = useState(null);
+  const cardRef = useRef(null);
+  const prevFocus = useRef(null);
+
+  const measure = useCallback(() => {
+    const step = steps[i];
+    setRect(step ? getRect(step.target) : null);
+  }, [steps, i]);
+
+  // Reset to the first step whenever a tour (re)opens.
+  useEffect(() => {
+    if (open) setI(0);
+  }, [open]);
+
+  useLayoutEffect(() => {
+    if (open) measure();
+  }, [open, measure]);
+
+  // Keep the spotlight glued to its target through scroll/resize; restore focus.
+  useEffect(() => {
+    if (!open) return;
+    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;
+    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;
+    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) return null;
+  const step = steps[i];
+  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;
+
+  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>
+        <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,35 @@
+// 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.
+
+export const USAGE_TOUR = [
+  {
+    target: '.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.',
+  },
+  {
+    target: '.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',
+    title: 'Menus & tools',
+    body: 'View toggles panels (tree, comments, annotations); Selection and Tools act on the active canvas. Press ? for every shortcut.',
+  },
+  {
+    target: "[data-tour='whatsnew']",
+    title: 'What’s new',
+    body: 'New features land here. Click the ✦ badge any time to catch up on what shipped.',
+  },
+  {
+    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.',
+  },
+];

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;
+}

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

@@ -0,0 +1,250 @@
+// whats-new.jsx — Maude UI "What's New" surfaces.
+//
+//   useWhatsNew(version)  → headless handle (fetch + seen-state + open-state)
+//   <WhatsNewBadge>       → menubar entry point (✦ + unseen-count dot)
+//   <WhatsNewToast>       → first-run notice (bottom-left, mirrors ai-banner.tsx)
+//   <WhatsNewPanel>       → list of entries (reuses the help-modal backdrop)
+//
+// Styling lives in client/styles/4-components.css (.mdcc-wn-*). Spotlight tours
+// (entry.tour[]) land in Phase 3 — the panel/toast leave a hook for them.
+
+import { useCallback, useEffect, useState } from 'react';
+import { bestSeenVersion, computeUnseen } from './whats-new-seen.js';
+
+const WN_SEEN = 'mdcc-whatsnew-seen';
+const WN_TOAST = 'mdcc-whatsnew-toast-dismissed';
+
+// learnMore renders as <a href> in the privileged main origin. Only bind an
+// http(s) URL — belt-and-suspenders next to React's built-in URL sanitizer and
+// the schema's pattern (security review, defense-in-depth).
+function isSafeHref(url) {
+  return typeof url === 'string' && /^https?:\/\//i.test(url);
+}
+
+function readSeen(currentVersion) {
+  try {
+    const v = localStorage.getItem(WN_SEEN);
+    if (v) return v;
+    // First ever run: acknowledge the current version silently so a brand-new
+    // user isn't greeted with the entire backlog as "new". Only true upgrades
+    // (and pending dev entries) surface after this.
+    localStorage.setItem(WN_SEEN, currentVersion);
+  } catch {}
+  return currentVersion;
+}
+
+function readToastDismissed() {
+  try {
+    return localStorage.getItem(WN_TOAST);
+  } catch {
+    return null;
+  }
+}
+
+export function useWhatsNew(currentVersion) {
+  const [entries, setEntries] = useState([]);
+  const [feedVersion, setFeedVersion] = useState(currentVersion);
+  const [seenVersion, setSeenVersion] = useState(() => readSeen(currentVersion));
+  const [toastDismissed, setToastDismissed] = useState(() => readToastDismissed());
+  const [panelOpen, setPanelOpen] = useState(false);
+
+  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 */
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const unseen = computeUnseen(entries, seenVersion);
+  const showToast = unseen.length > 0 && toastDismissed !== feedVersion && !panelOpen;
+  const toastEntry = unseen[0] ?? null;
+
+  const markAllSeen = useCallback(() => {
+    const next = bestSeenVersion(entries, feedVersion);
+    setSeenVersion(next);
+    setToastDismissed(feedVersion);
+    try {
+      localStorage.setItem(WN_SEEN, next);
+      localStorage.setItem(WN_TOAST, feedVersion);
+    } catch {}
+  }, [entries, feedVersion]);
+
+  const dismissToast = useCallback(() => {
+    setToastDismissed(feedVersion);
+    try {
+      localStorage.setItem(WN_TOAST, feedVersion);
+    } catch {}
+  }, [feedVersion]);
+
+  const openPanel = useCallback(() => setPanelOpen(true), []);
+  const closePanel = useCallback(() => {
+    setPanelOpen(false);
+    markAllSeen();
+  }, [markAllSeen]);
+
+  return {
+    entries,
+    unseen,
+    feedVersion,
+    panelOpen,
+    openPanel,
+    closePanel,
+    showToast,
+    toastEntry,
+    dismissToast,
+    markAllSeen,
+  };
+}
+
+export function WhatsNewBadge({ count = 0, onOpen }) {
+  return (
+    <button
+      type="button"
+      className="mdcc-wn-badge"
+      data-tour="whatsnew"
+      onClick={onOpen}
+      title="What's new"
+      aria-label={count > 0 ? `What's new — ${count} new` : "What's new"}
+    >
+      <span aria-hidden="true">✦</span>
+      <span className="mdcc-wn-badge__label">New</span>
+      {count > 0 && (
+        <span className="mdcc-wn-badge__dot" aria-hidden="true">
+          {count}
+        </span>
+      )}
+    </button>
+  );
+}
+
+export function WhatsNewToast({ wn }) {
+  if (!wn.showToast || !wn.toastEntry) return null;
+  const e = wn.toastEntry;
+  const total = wn.unseen.length;
+  // Plan C P6 — restyled to the maude `.st-toast` family (was `mdcc-wn-toast`),
+  // matching `.design/ui/Studio.tsx` AB-D. Behavior unchanged.
+  return (
+    <div className="st-toast" role="status" aria-live="polite">
+      <button
+        type="button"
+        className="st-toast-close"
+        aria-label="Dismiss"
+        onClick={wn.dismissToast}
+      >
+        ×
+      </button>
+      <div className="st-toast-hd">
+        <span aria-hidden="true">✦</span>
+        What's new{e.version ? ` · v${e.version}` : ''}
+      </div>
+      <div className="st-toast-title">{e.title}</div>
+      <div className="st-toast-txt">{e.summary}</div>
+      <div className="st-toast-actions">
+        <button type="button" className="btn btn--primary btn--sm" onClick={wn.openPanel}>
+          {total > 1 ? `See all (${total})` : 'Details'}
+        </button>
+        <button type="button" className="btn btn--ghost btn--sm" onClick={wn.dismissToast}>
+          Dismiss
+        </button>
+      </div>
+    </div>
+  );
+}
+
+export function WhatsNewPanel({ wn, onStartTour }) {
+  const { panelOpen, closePanel } = wn;
+  useEffect(() => {
+    if (!panelOpen) return;
+    function onKey(e) {
+      if (e.key === 'Escape') closePanel();
+    }
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [panelOpen, closePanel]);
+
+  if (!panelOpen) return null;
+  const unseenIds = new Set(wn.unseen.map((e) => e.id));
+  return (
+    <div
+      className="help-modal-backdrop"
+      role="presentation"
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) closePanel();
+      }}
+    >
+      <div
+        className="mdcc-wn-panel"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="mdcc-wn-title"
+      >
+        <header className="help-modal-hd">
+          <span className="title" id="mdcc-wn-title">
+            ✦ What’s new in maude
+          </span>
+          <button
+            type="button"
+            className="help-modal-close"
+            aria-label="Close (Esc)"
+            onClick={closePanel}
+          >
+            ×
+          </button>
+        </header>
+        <div className="mdcc-wn-panel__body">
+          {wn.entries.length === 0 ? (
+            <p className="mdcc-wn-empty">Nothing new yet.</p>
+          ) : (
+            <ul className="mdcc-wn-list">
+              {wn.entries.map((e) => (
+                <li
+                  key={e.id}
+                  className={'mdcc-wn-item' + (unseenIds.has(e.id) ? ' is-unseen' : '')}
+                >
+                  <div className="mdcc-wn-item__hd">
+                    <span className={'mdcc-wn-kind mdcc-wn-kind--' + e.kind}>{e.kind}</span>
+                    <span className="mdcc-wn-item__title">{e.title}</span>
+                    <span className="mdcc-wn-item__ver">{e.version ? `v${e.version}` : 'next'}</span>
+                  </div>
+                  <p className="mdcc-wn-item__summary">{e.summary}</p>
+                  {isSafeHref(e.learnMore) && (
+                    <a
+                      className="mdcc-wn-item__more"
+                      href={e.learnMore}
+                      target="_blank"
+                      rel="noreferrer"
+                    >
+                      Learn more →
+                    </a>
+                  )}
+                  {onStartTour && Array.isArray(e.tour) && e.tour.length > 0 && (
+                    <button
+                      type="button"
+                      className="mdcc-wn-item__tour"
+                      onClick={() => {
+                        closePanel();
+                        onStartTour(e.tour);
+                      }}
+                    >
+                      ▶ Take tour
+                    </button>
+                  )}
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/{plugins/design/dev-server → apps/studio}/collab/index.ts

@@ -7,13 +7,13 @@ import path from 'node:path';
 import type { Api } from '../api.ts';
 import type { Context } from '../context.ts';
 
-import { Y_TYPES, createPersistence } from './persistence.ts';
-import { type Registry, createRegistry } from './registry.ts';
+import { createPersistence, Y_TYPES } from './persistence.ts';
+import { createRegistry, type Registry } from './registry.ts';
 
-export { Y_TYPES };
+export type { CollabConn } from './protocol.ts';
 export type { Registry } from './registry.ts';
 export type { Room, RoomConn } from './room.ts';
-export type { CollabConn } from './protocol.ts';
+export { Y_TYPES };
 
 export interface Collab {
   registry: Registry;

package/{plugins/design/dev-server → apps/studio}/collab/persistence.ts

@@ -8,7 +8,7 @@ import * as Y from 'yjs';
 
 import type { Api } from '../api.ts';
 import type { Context } from '../context.ts';
-import { type RoomCallbacks, ensureStateDir } from './room.ts';
+import { ensureStateDir, type RoomCallbacks } from './room.ts';
 
 /**
  * Y.Doc shared-type names. Frozen on Task 1 so client + server agree even

package/{plugins/design/dev-server → apps/studio}/commands/annotation-strokes-command.ts

@@ -1,7 +1,7 @@
 /**
  * @file       commands/annotation-strokes-command.ts — undo entry for annotation
  *             stroke add / erase / batch-translate.
- * @scope      plugins/design/dev-server/commands/annotation-strokes-command.ts
+ * @scope      apps/studio/commands/annotation-strokes-command.ts
  * @purpose    Records a `Stroke[]` pair (before/after) and routes both
  *             directions through a single `putFn`. The server endpoint is
  *             `PUT /_api/annotations` which replaces the entire SVG; we

package/{plugins/design/dev-server → apps/studio}/commands/equal-spacing-command.ts

@@ -1,7 +1,7 @@
 /**
  * @file       commands/equal-spacing-command.ts — undo label helpers for
  *             equal-spacing / align gestures.
- * @scope      plugins/design/dev-server/commands/equal-spacing-command.ts
+ * @scope      apps/studio/commands/equal-spacing-command.ts
  * @purpose    Distribute + align both call `dragBus.commitPositions(moved)`,
  *             which wraps the move in a generic MoveArtboardsCommand. Per
  *             DDR-050 the underlying command type is shared (the inverse

package/{plugins/design/dev-server → apps/studio}/commands/move-artboards-command.ts

@@ -1,6 +1,6 @@
 /**
  * @file       commands/move-artboards-command.ts — undo entry for artboard moves
- * @scope      plugins/design/dev-server/commands/move-artboards-command.ts
+ * @scope      apps/studio/commands/move-artboards-command.ts
  * @purpose    Reversible record of an artboard-layout PATCH. Pairs the full
  *             `before` and `after` layout snapshots with an injected
  *             `patchFn` (in production, `applyArtboardLayout`; in tests, a