@1agh/maude 0.28.1 → 0.30.0

package/{plugins/design/dev-server → apps/studio}/use-annotation-selection.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-annotation-selection.tsx — Phase 5.1 annotation selection store
- * @scope      plugins/design/dev-server/use-annotation-selection.tsx
+ * @scope      apps/studio/use-annotation-selection.tsx
  * @purpose    Parallel to `use-selection-set`, but holds annotation stroke IDs
  *             instead of DOM-element selections. Annotation IDs are local
  *             identifiers (`s_*`) generated by `rid()` — they never live in
@@ -10,7 +10,15 @@
  * selection resets (the strokes themselves persist via `.annotations.svg`).
  */
 
-import { createContext, type ReactNode, useCallback, useContext, useMemo, useState } from 'react';
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 
 export interface AnnotationSelectionValue {
   selectedIds: string[];
@@ -57,10 +65,14 @@ export function AnnotationSelectionProvider({ children }: { children: ReactNode
 
   // Read live from state at call time so multi-step flows in the same tick
   // (e.g. a router callback that adds then asks `contains`) see the staged
-  // result instead of a stale closure capture.
-  const containsRef = { current: selectedIds };
+  // result instead of a stale closure capture. MUST be a real useRef — the
+  // pre-FigJam-v3 code created a fresh `{ current }` object literal every
+  // render, so the stable useCallback closure kept reading the FIRST render's
+  // (empty) selection forever: `contains()` always returned false, which
+  // silently broke hull/multi-drag and click-keeps-selection (user-gate
+  // finding, 2026-06-11).
+  const containsRef = useRef<string[]>(selectedIds);
   containsRef.current = selectedIds;
-  // biome-ignore lint/correctness/useExhaustiveDependencies: ref read intentionally
   const contains = useCallback((id: string) => containsRef.current.includes(id), []);
 
   const value = useMemo<AnnotationSelectionValue>(

package/{plugins/design/dev-server → apps/studio}/use-annotations-visibility.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-annotations-visibility.tsx — Phase 5.1 visibility store
- * @scope      plugins/design/dev-server/use-annotations-visibility.tsx
+ * @scope      apps/studio/use-annotations-visibility.tsx
  * @purpose    Tiny boolean store shared by AnnotationsLayer (render gate),
  *             ToolPalette (presentation toggle button), and the menubar
  *             bridge (`view-annotations` postMessage handler in

package/{plugins/design/dev-server → apps/studio}/use-artboard-drag.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-artboard-drag.tsx — Phase 4.2 artboard drag controller
- * @scope      plugins/design/dev-server/use-artboard-drag.tsx
+ * @scope      apps/studio/use-artboard-drag.tsx
  * @purpose    Owns the pointerdown → pointermove → pointerup state machine
  *             for dragging artboards on the infinite canvas. The pure
  *             `dragReducer` + `commitFromState` are unit-testable without a

package/{plugins/design/dev-server → apps/studio}/use-canvas-activity.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-canvas-activity.tsx — Phase 13 / DDR-029 activity context.
- * @scope      plugins/design/dev-server/use-canvas-activity.tsx
+ * @scope      apps/studio/use-canvas-activity.tsx
  * @purpose    Iframe-runtime React context fed by the server's `activity` WS
  *             messages. `DCArtboard` reads it to render the "agent works here"
  *             overlay on the artboards being edited right now.
@@ -132,7 +132,7 @@ function readActivitySeed(): ActivityMap {
   const out: ActivityMap = {};
   for (const file of Object.keys(seed)) {
     const e = seed[file];
-    if (!e || e.status !== 'active') continue; // only resurrect active overlays
+    if (e?.status !== 'active') continue; // only resurrect active overlays
     out[file] = {
       status: 'active',
       artboardIds: Array.isArray(e.artboardIds) ? e.artboardIds : null,
@@ -199,7 +199,7 @@ export function CanvasActivityProvider({
           setMap((prev) => {
             const entry = prev[detail.file];
             // Only remove if it's still the same idle entry (not re-activated).
-            if (!entry || entry.status !== 'idle' || entry.ts !== ts) return prev;
+            if (entry?.status !== 'idle' || entry.ts !== ts) return prev;
             const { [detail.file]: _drop, ...rest } = prev;
             return rest;
           });

package/apps/studio/use-canvas-media-drop.tsx

@@ -0,0 +1,343 @@
+/**
+ * @file       use-canvas-media-drop.tsx — Phase 23 canvas media intake
+ * @scope      apps/studio/use-canvas-media-drop.tsx
+ * @purpose    OS-level drag-and-drop + clipboard paste of images and URLs onto
+ *             the canvas. Routes each gesture to a create callback owned by
+ *             AnnotationsLayer (which holds the commit/undo sink + screenToWorld):
+ *               • image file → `onImage(file, world)`  → optimistic stroke + upload
+ *               • http(s) URL → `onLink(url, title, world)` → client-only link chip
+ *
+ *             The classification + URL helpers are PURE + exported so the unit
+ *             tests cover the dispatch matrix without a real DataTransfer /
+ *             ClipboardEvent. The hook itself only wires the DOM events and the
+ *             drag-affordance class.
+ *
+ *             Security: link URLs are gated to http(s) (no javascript:/data:);
+ *             image bytes go through POST /_api/asset (magic-byte sniff + caps,
+ *             DDR Task 9). Nothing here trusts the dropped content.
+ */
+
+import { useEffect } from 'react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure helpers (exported for unit tests)
+
+/** A normalized snapshot of a DataTransfer / ClipboardData payload. */
+export interface MediaPayload {
+  files: readonly File[];
+  /** text/uri-list (DnD) */
+  uriList: string;
+  /** text/html (carries the anchor text for a dragged/pasted link) */
+  html: string;
+  /** text/plain */
+  plain: string;
+}
+
+export type MediaIntent =
+  | { kind: 'image'; file: File }
+  | { kind: 'link'; url: string; title: string };
+
+/** True only for an absolute http(s) URL — the one scheme a link chip accepts. */
+export function isHttpUrl(value: string): boolean {
+  try {
+    const u = new URL(value.trim());
+    return u.protocol === 'http:' || u.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalize a single token into a safe http(s) URL, or null. You should NOT have
+ * to type a scheme to paste a link:
+ *   - an explicit scheme is kept ONLY if it's http(s) — `javascript:` / `data:`
+ *     / `file:` / `mailto:` all return null (never reach window.open);
+ *   - a scheme-less but domain-shaped token (`example.com`, `sub.example.io/x`)
+ *     gets `https://` prepended. The TLD must be alphabetic (≥2) so a bare
+ *     decimal like `3.5` or `v1.2` is NOT mistaken for a domain.
+ */
+export function normalizeUrl(raw: string): string | null {
+  const s = raw.trim();
+  if (!s) return null;
+  // Distinguish a real scheme (`http:`, `javascript:`) from a `host:port` colon.
+  // A scheme: the part before the FIRST colon is a valid scheme name (no `/`) AND
+  // the char after the colon is NOT a digit (a digit there is a port → scheme-less).
+  const colon = s.indexOf(':');
+  const hasScheme =
+    colon > 0 &&
+    /^[a-zA-Z][a-zA-Z0-9+.-]*$/.test(s.slice(0, colon)) &&
+    !/^\d/.test(s.slice(colon + 1));
+  if (hasScheme) return isHttpUrl(s) ? s : null;
+  // Scheme-less but domain-shaped (alphabetic TLD ≥2) → assume https.
+  if (/^([a-z0-9-]+\.)+[a-z]{2,}(:\d+)?(\/\S*)?$/i.test(s)) {
+    const u = `https://${s}`;
+    return isHttpUrl(u) ? u : null;
+  }
+  return null;
+}
+
+/**
+ * First link URL in a blob of text, normalized to http(s). Handles a uri-list
+ * (newline-separated, `#` comment lines), a bare-domain paste, and an explicit
+ * inline URL inside prose. Returns null when none.
+ */
+export function firstHttpUrl(text: string): string | null {
+  if (!text) return null;
+  for (const raw of text.split(/[\r\n]+/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const u = normalizeUrl(line);
+    if (u) return u;
+  }
+  // Fall back to an explicit inline URL token inside prose (a scheme is required
+  // here — bare-domain detection only fires on a whole standalone line).
+  const m = text.match(/https?:\/\/[^\s"'<>]+/i);
+  return m ? normalizeUrl(m[0]) : null;
+}
+
+/** Hostname without a leading `www.` — the chip's domain label. */
+export function linkDomain(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www\./, '');
+  } catch {
+    return url;
+  }
+}
+
+/** A readable title fallback when no anchor text is available. */
+export function prettifyUrl(url: string): string {
+  try {
+    const u = new URL(url);
+    const host = u.hostname.replace(/^www\./, '');
+    const path = u.pathname.replace(/\/+$/, '');
+    return path && path !== '/' ? `${host}${path}` : host;
+  } catch {
+    return url;
+  }
+}
+
+/** Anchor text from a `text/html` DnD/clipboard payload, else null. */
+export function anchorTextFromHtml(html: string): string | null {
+  if (!html) return null;
+  const m = html.match(/<a\b[^>]*>([\s\S]*?)<\/a>/i);
+  if (!m?.[1]) return null;
+  const text = m[1]
+    .replace(/<[^>]*>/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return text || null;
+}
+
+/**
+ * Decide what a drop / paste is: an image file wins over a URL (a dragged image
+ * carries both an image file AND a uri-list pointing at it). Returns null for a
+ * plain-text / non-media payload so the caller leaves the event untouched.
+ */
+export function classifyMediaPayload(p: MediaPayload): MediaIntent | null {
+  const imageFile = p.files.find((f) => typeof f.type === 'string' && f.type.startsWith('image/'));
+  if (imageFile) return { kind: 'image', file: imageFile };
+  const url = firstHttpUrl(p.uriList) ?? firstHttpUrl(p.plain);
+  if (url) {
+    const title = anchorTextFromHtml(p.html) ?? prettifyUrl(url);
+    return { kind: 'link', url, title };
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Upload
+
+/** POST raw image bytes to the capped asset route. Returns the assets/ path. */
+export async function uploadAsset(file: Blob): Promise<{ path: string } | { error: string }> {
+  try {
+    const res = await fetch('/_api/asset', {
+      method: 'POST',
+      headers: { 'Content-Type': file.type || 'application/octet-stream' },
+      body: file,
+    });
+    if (!res.ok) {
+      let msg = `upload failed (${res.status})`;
+      try {
+        const j = (await res.json()) as { error?: string };
+        if (j?.error) msg = j.error;
+      } catch {
+        /* non-JSON error body */
+      }
+      return { error: msg };
+    }
+    const j = (await res.json()) as { path?: string };
+    return typeof j?.path === 'string' ? { path: j.path } : { error: 'malformed upload response' };
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : 'network error' };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Transient toast (no React state — self-contained DOM, mirrors ensure*Styles)
+
+const TOAST_CSS = `
+.dc-media-toast {
+  position: fixed;
+  left: 50%;
+  bottom: 108px;
+  transform: translateX(-50%);
+  z-index: 9;
+  max-width: 360px;
+  padding: 8px 14px;
+  border-radius: 8px;
+  background: #26262b;
+  color: #fff;
+  font-family: var(--maude-chrome-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+  font-size: 12px;
+  box-shadow: 0 8px 28px rgba(0,0,0,0.34);
+  opacity: 0;
+  transition: opacity 140ms ease;
+  pointer-events: none;
+}
+.dc-media-toast[data-show="1"] { opacity: 1; }
+/* Drop affordance — a focus-accent inset frame while a media drag is over the
+   canvas, so the surface reads as a drop target. */
+.dc-media-dragover::after {
+  content: "";
+  position: fixed;
+  inset: 6px;
+  z-index: 8;
+  border: 2px dashed var(--maude-hud-accent, #d63b1f);
+  border-radius: 12px;
+  pointer-events: none;
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-media-toast { transition: none; }
+}
+`.trim();
+
+function ensureMediaStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-media-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-media-css';
+  s.textContent = TOAST_CSS;
+  document.head.appendChild(s);
+}
+
+/** Show a brief auto-dismissing toast in the canvas (e.g. an upload failure). */
+export function showCanvasToast(message: string): void {
+  if (typeof document === 'undefined') return;
+  ensureMediaStyles();
+  const el = document.createElement('div');
+  el.className = 'dc-media-toast';
+  el.setAttribute('role', 'status');
+  el.textContent = message;
+  document.body.appendChild(el);
+  requestAnimationFrame(() => el.setAttribute('data-show', '1'));
+  setTimeout(() => {
+    el.setAttribute('data-show', '0');
+    setTimeout(() => el.remove(), 200);
+  }, 2600);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+
+export interface MediaDropCallbacks {
+  onImage: (file: File, world: [number, number]) => void;
+  onLink: (url: string, title: string, world: [number, number]) => void;
+}
+
+export function useCanvasMediaDrop(opts: {
+  enabled: boolean;
+  screenToWorld: (cx: number, cy: number) => [number, number];
+  callbacks: MediaDropCallbacks;
+}): void {
+  const { enabled, screenToWorld, callbacks } = opts;
+  useEffect(() => {
+    if (!enabled || typeof document === 'undefined') return;
+    ensureMediaStyles();
+    const body = document.body;
+
+    const hasMedia = (dt: DataTransfer | null): boolean => {
+      if (!dt) return false;
+      const types = Array.from(dt.types ?? []);
+      return types.includes('Files') || types.includes('text/uri-list');
+    };
+
+    const payloadFromTransfer = (dt: DataTransfer): MediaPayload => ({
+      files: dt.files ? Array.from(dt.files) : [],
+      uriList: safeGet(dt, 'text/uri-list'),
+      html: safeGet(dt, 'text/html'),
+      plain: safeGet(dt, 'text/plain'),
+    });
+
+    const onDragOver = (e: DragEvent) => {
+      if (!hasMedia(e.dataTransfer)) return;
+      e.preventDefault();
+      if (e.dataTransfer) e.dataTransfer.dropEffect = 'copy';
+      body.classList.add('dc-media-dragover');
+    };
+    const onDragLeave = (e: DragEvent) => {
+      // Only clear when the pointer actually leaves the window (related target
+      // null), not when crossing between child elements.
+      if (e.relatedTarget == null) body.classList.remove('dc-media-dragover');
+    };
+    const onDrop = (e: DragEvent) => {
+      body.classList.remove('dc-media-dragover');
+      if (!e.dataTransfer) return;
+      const intent = classifyMediaPayload(payloadFromTransfer(e.dataTransfer));
+      if (!intent) return; // not media — leave the event for other handlers
+      e.preventDefault();
+      const world = screenToWorld(e.clientX, e.clientY);
+      dispatchIntent(intent, world);
+    };
+    const onPaste = (e: ClipboardEvent) => {
+      const cd = e.clipboardData;
+      if (!cd) return;
+      const files: File[] = [];
+      if (cd.files) for (const f of Array.from(cd.files)) files.push(f);
+      // Some browsers expose pasted images only via items, not files.
+      if (cd.items) {
+        for (const it of Array.from(cd.items)) {
+          if (it.kind === 'file' && it.type.startsWith('image/')) {
+            const f = it.getAsFile();
+            if (f && !files.includes(f)) files.push(f);
+          }
+        }
+      }
+      const intent = classifyMediaPayload({
+        files,
+        uriList: safeGet(cd, 'text/uri-list'),
+        html: safeGet(cd, 'text/html'),
+        plain: safeGet(cd, 'text/plain'),
+      });
+      if (!intent) return; // plain-text paste — let the existing paste flow run
+      e.preventDefault();
+      // Paste has no pointer position — drop at the visible viewport centre.
+      const world = screenToWorld(window.innerWidth / 2, window.innerHeight / 2);
+      dispatchIntent(intent, world);
+    };
+
+    const dispatchIntent = (intent: MediaIntent, world: [number, number]) => {
+      if (intent.kind === 'image') callbacks.onImage(intent.file, world);
+      else if (isHttpUrl(intent.url)) callbacks.onLink(intent.url, intent.title, world);
+    };
+
+    document.addEventListener('dragover', onDragOver);
+    document.addEventListener('dragleave', onDragLeave);
+    document.addEventListener('drop', onDrop);
+    document.addEventListener('paste', onPaste);
+    return () => {
+      document.removeEventListener('dragover', onDragOver);
+      document.removeEventListener('dragleave', onDragLeave);
+      document.removeEventListener('drop', onDrop);
+      document.removeEventListener('paste', onPaste);
+      body.classList.remove('dc-media-dragover');
+    };
+  }, [enabled, screenToWorld, callbacks]);
+}
+
+function safeGet(dt: DataTransfer, type: string): string {
+  try {
+    return dt.getData(type) ?? '';
+  } catch {
+    return '';
+  }
+}

package/{plugins/design/dev-server → apps/studio}/use-collab.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-collab.tsx — client-side Yjs collab provider for canvas iframes
- * @scope      plugins/design/dev-server/use-collab.tsx
+ * @scope      apps/studio/use-collab.tsx
  * @purpose    Mounts a single Y.Doc + Awareness per canvas iframe. Opens a
  *             WebSocket to `/_ws/collab/:slug`, speaks the y-websocket binary
  *             protocol, exposes hooks for the cursor overlay + Task 3 comments
@@ -39,26 +39,31 @@ const MESSAGE_AWARENESS = 1;
 // Color hash — stable per peer identity.
 
 /**
- * djb2 string hash → 0xRRGGBB color in a curated palette. Determinism per
+ * djb2 string hash → OKLCH color in a curated palette. Determinism per
  * input name is the load-bearing property: every peer hashing "Alice" must
- * land on the SAME color. 12 hues spread evenly around the wheel; saturation
- * + lightness fixed so all colors stay readable on light + dark surfaces.
+ * land on the SAME color.
+ *
+ * DS contract (colors-presence specimen): the AI agent rides
+ * `--presence-agent` (violet-magenta, hue 322) — "a hue no human state uses,
+ * so attribution on a shared canvas is unambiguous". Human hues therefore
+ * EXCLUDE the agent band (~292–352) AND the accent indigo band (~245–290,
+ * reserved for selection/active). L/C match the DS presence tokens
+ * (oklch ≈0.74 0.16) so every cursor reads at the same weight on both themes.
  */
 const COLOR_PALETTE = [
-  '#e91e63', // pink
-  '#f44336', // red
-  '#ff9800', // orange
-  '#ffc107', // amber
-  '#cddc39', // lime
-  '#4caf50', // green
-  '#009688', // teal
-  '#00bcd4', // cyan
-  '#03a9f4', // light blue
-  '#3f51b5', // indigo
-  '#673ab7', // deep purple
-  '#9c27b0', // purple
+  'oklch(0.70 0.17 12)', // rose
+  'oklch(0.72 0.16 40)', // coral
+  'oklch(0.78 0.15 78)', // amber  (presence-away hue)
+  'oklch(0.76 0.16 108)', // lime
+  'oklch(0.74 0.16 145)', // green  (presence-online hue)
+  'oklch(0.75 0.14 172)', // teal
+  'oklch(0.73 0.13 200)', // cyan
+  'oklch(0.72 0.13 238)', // blue   (status-info hue)
 ] as const;
 
+/** The AI agent's exclusive cursor/avatar hue — `--presence-agent`. */
+export const AGENT_COLOR = 'oklch(0.700 0.190 322)';
+
 export function colorForName(name: string): string {
   // COLOR_PALETTE is a non-empty const tuple; the explicit `?? '#000'`
   // fallback is unreachable but satisfies `noUncheckedIndexedAccess`.

package/{plugins/design/dev-server → apps/studio}/use-cursor-modifiers.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-cursor-modifiers.tsx — T28 (Wave 3)
- * @scope      plugins/design/dev-server/use-cursor-modifiers.tsx
+ * @scope      apps/studio/use-cursor-modifiers.tsx
  * @purpose    Modifier-aware cursor state machine. Tracks Alt / Shift / Meta
  *             modifier state globally and reflects it as `data-mod-*`
  *             attributes on `.dc-canvas`. CSS rules consume those attrs to

package/{plugins/design/dev-server → apps/studio}/use-keyboard-discipline.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-keyboard-discipline.tsx — T29 (Wave 3)
- * @scope      plugins/design/dev-server/use-keyboard-discipline.tsx
+ * @scope      apps/studio/use-keyboard-discipline.tsx
  * @purpose    Keyboard nudge + Cmd+A select-all-in-artboard. Bail when focus
  *             is inside an input / textarea / contenteditable so typing
  *             into the dev-server's own inputs (file tree filter, etc.)
@@ -29,6 +29,7 @@
 import { useEffect } from 'react';
 
 import { useArtboardsContext, useDragStateContext } from './canvas-lib.tsx';
+import { scopedCdSelector, selectorIndex } from './dom-selection.ts';
 import { isEditableTarget } from './input-router.tsx';
 import { type Selection, useSelectionSet } from './use-selection-set.tsx';
 
@@ -85,10 +86,12 @@ export function useKeyboardDiscipline(): void {
         for (const el of stamped) {
           const cdId = el.getAttribute('data-cd-id');
           if (!cdId) continue;
+          const kdSelector = scopedCdSelector(cdId, id);
           hits.push({
             id: cdId,
-            selector: `[data-cd-id="${cdId}"]`,
+            selector: kdSelector,
             artboardId: id,
+            index: selectorIndex(document, kdSelector, el),
             tag: el.tagName.toLowerCase(),
           });
         }

package/{plugins/design/dev-server → apps/studio}/use-selection-set.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-selection-set.tsx — Phase 4.1 multi-selection store
- * @scope      plugins/design/dev-server/use-selection-set.tsx
+ * @scope      apps/studio/use-selection-set.tsx
  * @purpose    Multi-element selection state for canvas-shell. The canvas
  *             input router calls `replace()` / `add()` / `clear()`;
  *             the provider debounces and posts up to the dev-server shell
@@ -46,6 +46,14 @@ export interface Selection {
   selector: string;
   /** Artboard host (`data-dc-screen`) — for scoping multi-edits in future. */
   artboardId?: string | null;
+  /**
+   * Occurrence index of this element among `querySelectorAll(selector)`.
+   * data-cd-id is stamped per SOURCE element, so a component rendered N times
+   * (a list row, or a reusable used twice) yields N DOM nodes with the SAME
+   * id+artboard selector. The index disambiguates which instance — resolvers
+   * use `querySelectorAll(selector)[index]`. Absent/0 → first match.
+   */
+  index?: number;
   /** Snapshot fields filled by the router from `resolveHoverTarget`. */
   tag?: string;
   classes?: string;
@@ -53,6 +61,15 @@ export interface Selection {
   dom_path?: string[];
   bounds?: { x: number; y: number; w: number; h: number } | null;
   html?: string;
+  /** Phase 12.2 — authored inline-style values (knob pre-fill) + resolved computed (placeholder hint). */
+  authored?: Record<string, string>;
+  computed?: Record<string, string>;
+  /** Phase 12.3 — authored inline-style props OUTSIDE the curated knob set, so the
+   *  panel can surface a custom CSS property the user added (e.g. `letter-spacing`). */
+  customStyles?: Record<string, string>;
+  /** Phase 12.3 — custom HTML attributes on the element (data-, aria-, role, title…),
+   *  so the panel reflects a custom attribute the user added via the escape hatch. */
+  attrs?: Record<string, string>;
 }
 
 interface SelectionSetValue {

package/{plugins/design/dev-server → apps/studio}/use-snap-guides.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-snap-guides.tsx — Phase 4.2 snap math + guide-line shapes
- * @scope      plugins/design/dev-server/use-snap-guides.tsx
+ * @scope      apps/studio/use-snap-guides.tsx
  * @purpose    Pure function `computeSnap` that returns a snapped (x, y) for a
  *             proposed artboard rect plus the guide lines that should render
  *             as visual feedback. No React state; the drag controller calls

package/{plugins/design/dev-server → apps/studio}/use-tool-mode.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-tool-mode.tsx — Phase 4.1 tool-mode store
- * @scope      plugins/design/dev-server/use-tool-mode.tsx
+ * @scope      apps/studio/use-tool-mode.tsx
  * @purpose    Context + hook for the active canvas tool. Wired into
  *             DesignCanvas. Phase 5 will
  *             register additional tools (pen, circle, arrow, eraser) via
@@ -52,10 +52,14 @@ export const DEFAULT_TOOLS: readonly ToolDescriptor[] = Object.freeze([
   { id: 'hand', label: 'Hand', shortcut: 'H', cursor: TOOL_CURSORS.hand },
   { id: 'comment', label: 'Comment', shortcut: 'C', cursor: TOOL_CURSORS.comment },
   { id: 'pen', label: 'Pen', shortcut: 'B', cursor: TOOL_CURSORS.pen },
+  // Annotation polish (item 8) — highlighter sits next to the pen.
+  { id: 'highlighter', label: 'Highlighter', shortcut: 'I', cursor: TOOL_CURSORS.highlighter },
   // Phase 24 — one Shape tool replaces the separate Rect (R) + Ellipse (O)
   // buttons; the primitive is chosen from the palette popover.
   { id: 'shape', label: 'Shape', shortcut: 'R', cursor: TOOL_CURSORS.shape },
   { id: 'sticky', label: 'Sticky', shortcut: 'N', cursor: TOOL_CURSORS.sticky },
+  // FigJam v3 — labelled organizing container.
+  { id: 'section', label: 'Section', shortcut: '⇧S', cursor: TOOL_CURSORS.shape },
   { id: 'arrow', label: 'Arrow', shortcut: 'A', cursor: TOOL_CURSORS.arrow },
   { id: 'text', label: 'Text', shortcut: 'T', cursor: TOOL_CURSORS.text },
   { id: 'eraser', label: 'Eraser', shortcut: 'E', cursor: TOOL_CURSORS.eraser },
@@ -112,7 +116,9 @@ export function ToolProvider({
   const clearSticky = useCallback(() => {
     setSticky({ tool: null, locked: false });
   }, []);
-  const [shapeKind, setShapeKind] = useState<ShapeKind>('square');
+  // FigJam v3 — soft default: a fresh Shape tool draws ROUNDED squares (the
+  // FigJam look); sharp squares stay one popover click away.
+  const [shapeKind, setShapeKind] = useState<ShapeKind>('rounded');
 
   // Cursor sync — applied inside the canvas (this hook runs in the canvas
   // context). The active tool's cursor is set on <body> AND forced across the

package/{plugins/design/dev-server → apps/studio}/use-undo-stack.tsx

@@ -1,6 +1,6 @@
 /**
  * @file       use-undo-stack.tsx — React Context + Provider for the undo stack
- * @scope      plugins/design/dev-server/use-undo-stack.tsx
+ * @scope      apps/studio/use-undo-stack.tsx
  * @purpose    Wraps the pure `undoReducer` (undo-stack.ts) in React state,
  *             owns the async runner that awaits side-effects before applying
  *             the next state transition, exposes the `lastLabel` HUD signal,