@1agh/maude 0.19.1 → 0.20.0

package/plugins/design/dev-server/commands/annotation-strokes-command.ts

@@ -0,0 +1,127 @@
+/**
+ * @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
+ * @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
+ *             match that shape rather than diffing.
+ *
+ *             Per DDR-050 rev 2 the runtime command is rebuilt per iframe
+ *             mount from a serializable `CommandRecord` so the stack
+ *             survives canvas switches. The `putFn` here also updates the
+ *             iframe's local React strokes state (see annotations-layer
+ *             `putStrokes`) so undo/redo visibly refresh, not just PUT.
+ *
+ *             Why per-stroke commands (not coalesced into a 300 ms window):
+ *             matches Figma/FigJam — Cmd+Z reverts the most recent tap or
+ *             pen stroke individually. Coalescing into windows led to a
+ *             matoucí "why did Cmd+Z erase two of my last lines?" UX.
+ */
+
+import type { Stroke } from '../annotations-layer.tsx';
+import type { CommandRecord, CommandSinks, EditCommand } from '../undo-stack.ts';
+import { registerCommand } from '../undo-stack.ts';
+
+/**
+ * Push-once callable that submits a full `Stroke[]` to the server (or its
+ * test stub) AND updates the iframe's local strokes state. The
+ * annotations-layer `putStrokes` is the production binding.
+ */
+export type StrokesPutFn = (next: readonly Stroke[]) => void | Promise<void>;
+
+export interface AnnotationStrokesPayload {
+  before: readonly Stroke[];
+  after: readonly Stroke[];
+}
+
+export const ANNOTATION_STROKES_KIND = 'annotation-strokes';
+
+export interface AnnotationStrokesCommandInit {
+  before: readonly Stroke[];
+  after: readonly Stroke[];
+  putFn: StrokesPutFn;
+  /** Optional label override (eraser → "erase 1 stroke"). */
+  label?: string;
+  /** Telemetry kind. */
+  kind?: string;
+}
+
+export function createAnnotationStrokesCommand(init: AnnotationStrokesCommandInit): EditCommand {
+  const { putFn } = init;
+  const before = init.before.map(cloneStroke);
+  const after = init.after.map(cloneStroke);
+  const label = init.label ?? defaultLabel(before, after);
+  const kind = init.kind ?? ANNOTATION_STROKES_KIND;
+
+  return {
+    kind,
+    label,
+    async do() {
+      await putFn(after.map(cloneStroke));
+    },
+    async undo() {
+      await putFn(before.map(cloneStroke));
+    },
+  };
+}
+
+/**
+ * Build a persistable record from the same inputs as `createAnnotationStrokesCommand`.
+ * Used by the consumer alongside the EditCommand so the runtime side-effect
+ * and the stored shape share one snapshot.
+ */
+export function buildAnnotationStrokesRecord(opts: {
+  before: readonly Stroke[];
+  after: readonly Stroke[];
+  label?: string;
+}): CommandRecord<AnnotationStrokesPayload> {
+  const before = opts.before.map(cloneStroke);
+  const after = opts.after.map(cloneStroke);
+  return {
+    kind: ANNOTATION_STROKES_KIND,
+    label: opts.label ?? defaultLabel(before, after),
+    payload: { before, after },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Registry
+
+registerCommand<AnnotationStrokesPayload>(ANNOTATION_STROKES_KIND, (record, sinks) => {
+  const putFn = sinks.strokesPutFn as StrokesPutFn | undefined;
+  if (!putFn) return null;
+  return createAnnotationStrokesCommand({
+    before: record.payload.before,
+    after: record.payload.after,
+    putFn,
+    label: record.label,
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internals
+
+/**
+ * Structured clone — works for every Stroke variant because they're plain
+ * JSON-shaped (no Date / Map / DOM nodes). The pen `points: WorldPoint[]`
+ * array is nested-cloned too so callers can't poison the snapshot by
+ * mutating the source.
+ */
+function cloneStroke<T extends Stroke>(s: T): T {
+  // structuredClone is available on every runtime we ship to (Bun, modern
+  // browsers, Node 17+). Fall back to JSON for the rare older harness.
+  if (typeof structuredClone === 'function') return structuredClone(s);
+  return JSON.parse(JSON.stringify(s)) as T;
+}
+
+function defaultLabel(before: readonly Stroke[], after: readonly Stroke[]): string {
+  const added = after.length - before.length;
+  if (added > 0) return `add ${added} stroke${added === 1 ? '' : 's'}`;
+  if (added < 0) {
+    const erased = -added;
+    return `erase ${erased} stroke${erased === 1 ? '' : 's'}`;
+  }
+  // Same count — could be translate / edit / fill-change.
+  return `edit ${after.length} stroke${after.length === 1 ? '' : 's'}`;
+}

package/plugins/design/dev-server/commands/equal-spacing-command.ts

@@ -0,0 +1,28 @@
+/**
+ * @file       commands/equal-spacing-command.ts — undo label helpers for
+ *             equal-spacing / align gestures.
+ * @scope      plugins/design/dev-server/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
+ *             payload is identical — a layout snapshot pair) and only the
+ *             HUD label differs. These helpers compute the labels.
+ *
+ *             Why not a separate Command class? The wrapping logic would
+ *             duplicate `before`/`after`/`patchFn` + add an indirection.
+ *             A label is a one-line string; a factory is overkill.
+ *             Keeping `MoveArtboardsCommand` as the only artboard-layout
+ *             command keeps the future Yjs swap (Phase 8) one-for-one.
+ */
+
+export type AlignMode = 'left' | 'right' | 'center-x' | 'top' | 'bottom' | 'center-y';
+
+/** "equal-space 3 artboards" — N must be ≥ 3 (distribute requires it). */
+export function equalSpacingLabel(n: number): string {
+  return `equal-space ${n} artboard${n === 1 ? '' : 's'}`;
+}
+
+/** "align left 4 artboards" — N must be ≥ 2 (align requires it). */
+export function alignLabel(mode: AlignMode, n: number): string {
+  return `align ${mode} ${n} artboard${n === 1 ? '' : 's'}`;
+}

package/plugins/design/dev-server/commands/move-artboards-command.ts

@@ -0,0 +1,158 @@
+/**
+ * @file       commands/move-artboards-command.ts — undo entry for artboard moves
+ * @scope      plugins/design/dev-server/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
+ *             spy). The command is rebuilt per iframe mount from a
+ *             `CommandRecord` so the stack survives canvas switches
+ *             (DDR-050 rev 2).
+ *
+ * Why full snapshots, not a sparse diff. The server-side endpoint
+ * (`PATCH /_api/canvas-meta`, see api.ts:523–528) shallow-merges patch.layout
+ * over the existing meta. A sparse `{ artboards: [movedOnly] }` would drop
+ * every unchanged rect on its head. Storing the full array is simpler and
+ * resilient — the external-edit invalidation (DDR-050 rule 6) clears the
+ * stack whenever the file changes outside our PATCH so we never restore a
+ * stale layout.
+ */
+
+import type { CommandRecord, CommandSinks, EditCommand } from '../undo-stack.ts';
+import { registerCommand } from '../undo-stack.ts';
+
+export interface ArtboardLayoutEntry {
+  id: string;
+  x: number;
+  y: number;
+  /** Width — JSX-authoritative; carried through for shape-completeness. */
+  w?: number;
+  h?: number;
+}
+
+/**
+ * Signature compatible with canvas-lib's `applyArtboardLayout(layout)`.
+ * Tests pass a spy; production wiring passes the real React-state-+-PATCH
+ * applier.
+ */
+export type LayoutPatchFn = (layout: ArtboardLayoutEntry[]) => void | Promise<void>;
+
+export interface MoveArtboardsPayload {
+  before: readonly ArtboardLayoutEntry[];
+  after: readonly ArtboardLayoutEntry[];
+}
+
+/** Convenience constant — keeps spelling consistent across files. */
+export const MOVE_ARTBOARDS_KIND = 'move-artboards';
+
+export interface MoveArtboardsCommandInit {
+  before: readonly ArtboardLayoutEntry[];
+  after: readonly ArtboardLayoutEntry[];
+  patchFn: LayoutPatchFn;
+  /** Optional label override (equal-spacing wraps with its own copy). */
+  label?: string;
+  /** Telemetry kind. Defaults to `MOVE_ARTBOARDS_KIND`. */
+  kind?: string;
+}
+
+export function createMoveArtboardsCommand(init: MoveArtboardsCommandInit): EditCommand {
+  const { before, after, patchFn } = init;
+  // Snapshot once — mutating the source arrays later cannot poison the command.
+  const beforeSnapshot = before.map(cloneEntry);
+  const afterSnapshot = after.map(cloneEntry);
+  const movedCount = countMoved(beforeSnapshot, afterSnapshot);
+  const label = init.label ?? `move ${movedCount} artboard${movedCount === 1 ? '' : 's'}`;
+  const kind = init.kind ?? MOVE_ARTBOARDS_KIND;
+
+  return {
+    kind,
+    label,
+    async do() {
+      await patchFn(afterSnapshot.map(cloneEntry));
+    },
+    async undo() {
+      await patchFn(beforeSnapshot.map(cloneEntry));
+    },
+  };
+}
+
+/**
+ * Build a persistable record from the same inputs. Use this together with
+ * the EditCommand so the runtime side-effect AND the persisted shape share
+ * one snapshot.
+ */
+export function buildMoveArtboardsRecord(opts: {
+  before: readonly ArtboardLayoutEntry[];
+  after: readonly ArtboardLayoutEntry[];
+  label?: string;
+}): CommandRecord<MoveArtboardsPayload> {
+  const before = opts.before.map(cloneEntry);
+  const after = opts.after.map(cloneEntry);
+  const moved = countMoved(before, after);
+  const label = opts.label ?? `move ${moved} artboard${moved === 1 ? '' : 's'}`;
+  return { kind: MOVE_ARTBOARDS_KIND, label, payload: { before, after } };
+}
+
+/**
+ * Diff helper — returns `null` when `before` and `after` describe the same
+ * layout (call sites use this to skip pushing a no-op drag onto the stack).
+ * Compares positions only; size diffs are ignored (size is JSX-authoritative
+ * per DDR-027, position is the only mutable channel).
+ */
+export function diffLayoutPositions(
+  before: readonly ArtboardLayoutEntry[],
+  after: readonly ArtboardLayoutEntry[]
+): { changed: number } | null {
+  if (before.length !== after.length) return { changed: Math.max(before.length, after.length) };
+  const byId = new Map<string, ArtboardLayoutEntry>();
+  for (const r of before) byId.set(r.id, r);
+  let changed = 0;
+  for (const r of after) {
+    const prev = byId.get(r.id);
+    if (!prev || prev.x !== r.x || prev.y !== r.y) changed++;
+  }
+  if (changed === 0) return null;
+  return { changed };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Registry — rebuild EditCommand from a persisted CommandRecord + current
+// iframe's sinks. Runs once on module load (top-level side-effect intentional).
+
+registerCommand<MoveArtboardsPayload>(MOVE_ARTBOARDS_KIND, (record, sinks) => {
+  const patchFn = sinks.layoutPatchFn as LayoutPatchFn | undefined;
+  if (!patchFn) return null;
+  return createMoveArtboardsCommand({
+    before: record.payload.before,
+    after: record.payload.after,
+    patchFn,
+    label: record.label,
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internals
+
+function cloneEntry(r: ArtboardLayoutEntry): ArtboardLayoutEntry {
+  const out: ArtboardLayoutEntry = { id: r.id, x: r.x, y: r.y };
+  if (typeof r.w === 'number') out.w = r.w;
+  if (typeof r.h === 'number') out.h = r.h;
+  return out;
+}
+
+function countMoved(
+  before: readonly ArtboardLayoutEntry[],
+  after: readonly ArtboardLayoutEntry[]
+): number {
+  const byId = new Map<string, ArtboardLayoutEntry>();
+  for (const r of before) byId.set(r.id, r);
+  let n = 0;
+  for (const r of after) {
+    const prev = byId.get(r.id);
+    if (!prev) {
+      n++;
+      continue;
+    }
+    if (prev.x !== r.x || prev.y !== r.y) n++;
+  }
+  return n;
+}

package/plugins/design/dev-server/comments-overlay.tsx

@@ -1143,14 +1143,22 @@ function computeThreadAnchor(comment: OverlayComment): { x: number; y: number }
 }
 
 function computeAnchor(state: ComposerState): { x: number; y: number } {
-  // Try the selected element first — its live screen rect gives the most
-  // natural anchor (composer sits flush under the element the user clicked).
+  // G4 — anchor to the cursor click point first. Earlier versions anchored to
+  // the selected element's bottom-left, which landed the composer flush in
+  // the corner regardless of where the user clicked — surprising for the
+  // common case of "I clicked the middle of an element, expecting the
+  // composer to appear near my cursor". The element-rect path remains as a
+  // fallback for entry points that don't carry a cursor (e.g. opening the
+  // composer from a contextual toolbar button — those should set clientX/Y
+  // to a sensible anchor before dispatching).
+  if (state.clientX || state.clientY) {
+    return { x: state.clientX, y: state.clientY + 8 };
+  }
   if (state.selection.selector) {
     const rect = screenRectFor(state.selection.selector);
     if (rect) {
       return { x: rect.x, y: rect.y + rect.h + 8 };
     }
   }
-  // Fall back to the raw click point — composer drops 8px below the cursor.
-  return { x: state.clientX, y: state.clientY + 8 };
+  return { x: 16, y: 16 };
 }

package/plugins/design/dev-server/contextual-toolbar.tsx

@@ -0,0 +1,241 @@
+/**
+ * @file       contextual-toolbar.tsx — T30 (Wave 3)
+ * @scope      plugins/design/dev-server/contextual-toolbar.tsx
+ * @purpose    Selection-anchored floating chrome for ELEMENT selections
+ *             (cd-id entries in the selection set). Mirrors the
+ *             MultiArtboardToolbar pattern but scopes to user content inside
+ *             artboards. Actions surface the existing right-click handlers
+ *             one click closer:
+ *
+ *               • Copy CSS path
+ *               • Copy data-cd-id
+ *               • Add comment
+ *
+ *             Hides when:
+ *               - no selection,
+ *               - selection contains only artboards (MultiArtboardToolbar
+ *                 covers that),
+ *               - selection contains only annotations (their own toolbar
+ *                 fires from `annotations-context-toolbar.tsx`).
+ *
+ *             Anchored 14 px above the element selection union bbox; flips
+ *             below when bbox top is < 60 px from the viewport edge — same
+ *             contract as MultiArtboardToolbar so the two never collide.
+ *
+ *             Selection-change tweens are NOT animated here in v1; the
+ *             instant reposition is acceptable given the toolbar fades in
+ *             only when stickily relevant. A future polish wave can add
+ *             the 180 ms position tween per the plan note.
+ */
+
+import { useEffect, useRef } from 'react';
+
+import { useSelectionSet } from './use-selection-set.tsx';
+
+const CTX_TOOLBAR_CSS = `
+.dc-elem-ctx-tb {
+  position: fixed;
+  pointer-events: auto;
+  z-index: 6;
+  display: none;
+  align-items: stretch;
+  gap: 2px;
+  padding: 4px;
+  background: var(--u-bg-0, var(--bg-0, #ffffff));
+  border: 1px solid var(--u-fg-0, #1c1917);
+  border-radius: 8px;
+  box-shadow: 0 6px 24px color-mix(in oklab, var(--u-fg-0, #1c1917) 10%, transparent);
+  font-family: var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-size: 11px;
+  letter-spacing: 0.02em;
+  color: var(--u-fg-0, #1a1a1a);
+  user-select: none;
+  opacity: 0;
+  transition: opacity 100ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+.dc-elem-ctx-tb[data-on="true"] {
+  opacity: 1;
+}
+.dc-elem-ctx-tb button {
+  appearance: none;
+  background: transparent;
+  border: 0;
+  border-radius: 6px;
+  padding: 4px 10px;
+  font: inherit;
+  cursor: pointer;
+  color: inherit;
+  transition: background-color 80ms linear;
+}
+.dc-elem-ctx-tb button:hover {
+  background: color-mix(in oklab, var(--accent, #d63b1f) 8%, transparent);
+}
+.dc-elem-ctx-tb .dc-elem-ctx-count {
+  padding: 4px 8px 4px 10px;
+  color: var(--fg-1, rgba(40,30,20,0.7));
+  border-right: 1px solid var(--u-border-subtle, rgba(0,0,0,0.08));
+  margin-right: 2px;
+  font-variant-numeric: tabular-nums;
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-elem-ctx-tb, .dc-elem-ctx-tb button { transition: none; }
+}
+`.trim();
+
+function ensureStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-elem-ctx-tb-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-elem-ctx-tb-css';
+  s.textContent = CTX_TOOLBAR_CSS;
+  document.head.appendChild(s);
+}
+
+function copyText(text: string): void {
+  if (typeof navigator === 'undefined' || !navigator.clipboard) return;
+  void navigator.clipboard.writeText(text).catch(() => {
+    /* clipboard blocked */
+  });
+}
+
+function openComposerForSelection(
+  sel: { id?: string; selector: string },
+  anchorEl: Element | null
+): void {
+  if (typeof document === 'undefined') return;
+  // Anchor near the top-right of the targeted element so the composer drops
+  // into a clear area next to it. Matches the comment-tool click affordance
+  // post-G4 (cursor-anchored composer).
+  let clientX = 0;
+  let clientY = 0;
+  if (anchorEl) {
+    const r = (anchorEl as HTMLElement).getBoundingClientRect();
+    clientX = r.right - 8;
+    clientY = r.top + r.height / 2;
+  }
+  try {
+    document.dispatchEvent(
+      new CustomEvent('cm:open-composer', {
+        detail: { selection: sel, clientX, clientY },
+      })
+    );
+  } catch {
+    /* CustomEvent unsupported — fall through */
+  }
+  // Back-compat parent post for legacy mocks.
+  if (typeof window !== 'undefined') {
+    try {
+      window.parent.postMessage({ dgn: 'comment-compose', selection: sel }, '*');
+    } catch {
+      /* parent detached */
+    }
+  }
+}
+
+export function ContextualToolbar() {
+  ensureStyles();
+  const { selected } = useSelectionSet();
+  const ref = useRef<HTMLDivElement | null>(null);
+  const rafRef = useRef<number | null>(null);
+
+  // Element selections = entries with `id` (data-cd-id) set. Pure artboard
+  // selections (artboardId-only, no id) and empty sets fall through.
+  const elementSelections = selected.filter((s) => !!s.id);
+  const visible = elementSelections.length > 0;
+
+  useEffect(() => {
+    const div = ref.current;
+    if (!div) return;
+    if (!visible) {
+      div.style.display = 'none';
+      div.setAttribute('data-on', 'false');
+      return;
+    }
+    const tick = () => {
+      rafRef.current = null;
+      let xMin = Number.POSITIVE_INFINITY;
+      let yMin = Number.POSITIVE_INFINITY;
+      let xMax = Number.NEGATIVE_INFINITY;
+      let yMax = Number.NEGATIVE_INFINITY;
+      let any = false;
+      for (const sel of elementSelections) {
+        const node = sel.id
+          ? document.querySelector(`[data-cd-id="${sel.id}"]`)
+          : document.querySelector(sel.selector);
+        if (!node) continue;
+        const r = (node as HTMLElement).getBoundingClientRect();
+        if (r.width === 0 && r.height === 0) continue;
+        any = true;
+        if (r.left < xMin) xMin = r.left;
+        if (r.top < yMin) yMin = r.top;
+        if (r.right > xMax) xMax = r.right;
+        if (r.bottom > yMax) yMax = r.bottom;
+      }
+      if (!any) {
+        div.style.display = 'none';
+        div.setAttribute('data-on', 'false');
+        rafRef.current = requestAnimationFrame(tick);
+        return;
+      }
+      div.style.display = 'flex';
+      const tw = div.offsetWidth || 0;
+      const centerX = (xMin + xMax) / 2;
+      const top = yMin;
+      const gap = 14;
+      let anchorY = top - div.offsetHeight - gap;
+      if (anchorY < 60) anchorY = yMax + gap;
+      div.style.left = `${Math.round(centerX - tw / 2)}px`;
+      div.style.top = `${Math.round(anchorY)}px`;
+      div.setAttribute('data-on', 'true');
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => {
+      if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
+    };
+  }, [visible, elementSelections]);
+
+  if (!visible) {
+    return <div ref={ref} className="dc-elem-ctx-tb" aria-hidden="true" />;
+  }
+
+  // For multi-selection, Copy actions operate on the FIRST element — same
+  // convention as the right-click menu (single-target). Future polish: a
+  // mini-menu that lets the user pick which selection's CSS to copy.
+  const primary = elementSelections[0];
+  const count = elementSelections.length;
+
+  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="Copy CSS selector"
+        onClick={() => primary && copyText(primary.selector)}
+      >
+        Copy CSS
+      </button>
+      <button
+        type="button"
+        title="Copy data-cd-id"
+        disabled={!primary?.id}
+        onClick={() => primary?.id && copyText(primary.id)}
+      >
+        Copy ID
+      </button>
+      <button
+        type="button"
+        title="Add comment on this element"
+        onClick={() => {
+          if (!primary) return;
+          const node = primary.id
+            ? document.querySelector(`[data-cd-id="${primary.id}"]`)
+            : document.querySelector(primary.selector);
+          openComposerForSelection(primary, node);
+        }}
+      >
+        Comment
+      </button>
+    </div>
+  );
+}