@1agh/maude 0.15.0

package/plugins/design/dev-server/use-snap-guides.tsx

@@ -0,0 +1,215 @@
+/**
+ * @file       use-snap-guides.tsx — Phase 4.2 snap math + guide-line shapes
+ * @scope      plugins/design/dev-server/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
+ *             this on every pointermove tick.
+ *
+ * Two snap kinds:
+ *
+ *   Grid     — every `gridSize` world-units. Applied to top-left corner of
+ *              `proposed` (left edge for X, top edge for Y).
+ *   Sibling  — alignment with other artboard rects: left↔left, right↔right,
+ *              left↔right, right↔left, centerX↔centerX on the X-axis (and
+ *              the matching top/bottom/centerY set on the Y-axis).
+ *
+ * Tolerance is in world units, not screen pixels (DDR-028) — snap feel stays
+ * consistent across zoom levels.
+ *
+ * The X-axis and Y-axis are independent: a proposed rect can snap X to a
+ * sibling edge and Y to a grid line simultaneously. Both guides render.
+ *
+ * Closest candidate wins per axis (smallest |delta|). When multiple sibling
+ * candidates land on the exact same `pos` (e.g. two artboards' right edges
+ * stacked at the same x), we render one merged guide whose from/to spans the
+ * union of every aligned rect's perpendicular extent.
+ *
+ * `disabled: true` (Alt held) short-circuits with `{ x, y, guides: [] }`.
+ */
+
+export interface Rect {
+  /** Optional rect id — used by the drag controller to filter self / followers
+   *  out of the snap candidate set. `computeSnap` itself ignores it. */
+  id?: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export type SnapAxis = 'x' | 'y';
+
+export interface SnapGuide {
+  /** `"x"` → vertical line (snapping X coord). Line sits at `pos` on X,
+   *  spans `from..to` on Y. `"y"` is the dual: horizontal line at `pos` on Y,
+   *  spans `from..to` on X. */
+  axis: SnapAxis;
+  pos: number;
+  from: number;
+  to: number;
+}
+
+export interface SnapResult {
+  /** Possibly-snapped top-left X of the proposed rect (in world coords). */
+  x: number;
+  /** Possibly-snapped top-left Y. */
+  y: number;
+  /** Guides to render. 0..2 entries in the common case (one per axis). */
+  guides: SnapGuide[];
+}
+
+export interface SnapOptions {
+  /** World-units between grid lines. Default 40. */
+  gridSize: number;
+  /** Max world-unit distance at which a candidate is considered "close". */
+  tolerance: number;
+  /** Skip all snap math + return proposed unchanged (Alt-held bypass). */
+  disabled: boolean;
+}
+
+interface AxisCandidate {
+  /** Shift to apply to proposed on this axis. */
+  delta: number;
+  /** Position of the guide line in world coords (on the snapped axis). */
+  pos: number;
+  /** Perpendicular extent — `from..to` of the would-be guide. */
+  from: number;
+  to: number;
+}
+
+function nearestGridDelta(coord: number, gridSize: number, tolerance: number): number | null {
+  if (!Number.isFinite(coord) || gridSize <= 0) return null;
+  const nearest = Math.round(coord / gridSize) * gridSize;
+  const delta = nearest - coord;
+  return Math.abs(delta) <= tolerance ? delta : null;
+}
+
+function pickClosest(cands: AxisCandidate[]): AxisCandidate | null {
+  if (cands.length === 0) return null;
+  let best = cands[0] as AxisCandidate;
+  let bestAbs = Math.abs(best.delta);
+  for (let i = 1; i < cands.length; i++) {
+    const c = cands[i] as AxisCandidate;
+    const a = Math.abs(c.delta);
+    if (a < bestAbs) {
+      best = c;
+      bestAbs = a;
+    }
+  }
+  return best;
+}
+
+/**
+ * Among `cands`, find every entry whose `pos` matches `winner.pos` (within a
+ * tiny epsilon to absorb floating-point noise) and union their from/to into
+ * one guide. Returns the merged guide.
+ */
+function mergeAtPos(axis: SnapAxis, winner: AxisCandidate, cands: AxisCandidate[]): SnapGuide {
+  let from = winner.from;
+  let to = winner.to;
+  for (const c of cands) {
+    if (Math.abs(c.pos - winner.pos) > 0.001) continue;
+    if (c.from < from) from = c.from;
+    if (c.to > to) to = c.to;
+  }
+  return { axis, pos: winner.pos, from, to };
+}
+
+export function computeSnap(proposed: Rect, others: Rect[], opts: SnapOptions): SnapResult {
+  if (opts.disabled) {
+    return { x: proposed.x, y: proposed.y, guides: [] };
+  }
+  const { gridSize, tolerance } = opts;
+  const propLeft = proposed.x;
+  const propRight = proposed.x + proposed.w;
+  const propCenterX = proposed.x + proposed.w / 2;
+  const propTop = proposed.y;
+  const propBottom = proposed.y + proposed.h;
+  const propCenterY = proposed.y + proposed.h / 2;
+
+  const xCands: AxisCandidate[] = [];
+  const yCands: AxisCandidate[] = [];
+
+  // Grid candidates — left edge for X, top edge for Y. Perpendicular extent
+  // is just the proposed rect's own range (no sibling involved).
+  const gridX = nearestGridDelta(propLeft, gridSize, tolerance);
+  if (gridX !== null) {
+    xCands.push({
+      delta: gridX,
+      pos: propLeft + gridX,
+      from: propTop,
+      to: propBottom,
+    });
+  }
+  const gridY = nearestGridDelta(propTop, gridSize, tolerance);
+  if (gridY !== null) {
+    yCands.push({
+      delta: gridY,
+      pos: propTop + gridY,
+      from: propLeft,
+      to: propRight,
+    });
+  }
+
+  // Sibling candidates.
+  for (const other of others) {
+    const oLeft = other.x;
+    const oRight = other.x + other.w;
+    const oCenterX = other.x + other.w / 2;
+    const oTop = other.y;
+    const oBottom = other.y + other.h;
+    const oCenterY = other.y + other.h / 2;
+
+    // X-axis pairs: (propCoord, otherCoord).
+    const xPairs: Array<[number, number]> = [
+      [propLeft, oLeft],
+      [propRight, oRight],
+      [propLeft, oRight],
+      [propRight, oLeft],
+      [propCenterX, oCenterX],
+    ];
+    for (const [propCoord, otherCoord] of xPairs) {
+      const delta = otherCoord - propCoord;
+      if (Math.abs(delta) > tolerance) continue;
+      xCands.push({
+        delta,
+        pos: otherCoord,
+        from: Math.min(propTop, oTop),
+        to: Math.max(propBottom, oBottom),
+      });
+    }
+
+    // Y-axis pairs.
+    const yPairs: Array<[number, number]> = [
+      [propTop, oTop],
+      [propBottom, oBottom],
+      [propTop, oBottom],
+      [propBottom, oTop],
+      [propCenterY, oCenterY],
+    ];
+    for (const [propCoord, otherCoord] of yPairs) {
+      const delta = otherCoord - propCoord;
+      if (Math.abs(delta) > tolerance) continue;
+      yCands.push({
+        delta,
+        pos: otherCoord,
+        from: Math.min(propLeft, oLeft),
+        to: Math.max(propRight, oRight),
+      });
+    }
+  }
+
+  const winX = pickClosest(xCands);
+  const winY = pickClosest(yCands);
+
+  const guides: SnapGuide[] = [];
+  if (winX) guides.push(mergeAtPos('x', winX, xCands));
+  if (winY) guides.push(mergeAtPos('y', winY, yCands));
+
+  return {
+    x: proposed.x + (winX ? winX.delta : 0),
+    y: proposed.y + (winY ? winY.delta : 0),
+    guides,
+  };
+}

package/plugins/design/dev-server/use-tool-mode.tsx

@@ -0,0 +1,114 @@
+/**
+ * @file       use-tool-mode.tsx — Phase 4.1 tool-mode store
+ * @scope      plugins/design/dev-server/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
+ *             the same provider — the API is intentionally open.
+ *
+ * The router's `onTool` callback (input-router.tsx) writes into this store.
+ * The ToolPalette + cursor sync read from it. Selecting a tool also mutates
+ * `document.body.style.cursor` so the affordance matches across the iframe.
+ */
+
+import {
+  type ReactNode,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+
+import type { Tool } from './input-router.tsx';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+
+export interface ToolDescriptor {
+  id: Tool;
+  label: string;
+  /** Letter-key shortcut shown in the palette tooltip. */
+  shortcut: string;
+  /** CSS cursor value applied to <body> when this tool is active. */
+  cursor: string;
+}
+
+export const DEFAULT_TOOLS: readonly ToolDescriptor[] = Object.freeze([
+  { id: 'move', label: 'Move', shortcut: 'V', cursor: 'default' },
+  { id: 'hand', label: 'Hand', shortcut: 'H', cursor: 'grab' },
+  { id: 'comment', label: 'Comment', shortcut: 'C', cursor: 'crosshair' },
+  // Phase 5 — draw / annotation tools. Cursors stay as `crosshair` for pen /
+  // rect / arrow (the pen-tip glyph is reserved for the system text caret).
+  // Eraser uses `cell` as the closest cross-browser substitute for a rubber
+  // affordance (no native rubber cursor exists).
+  { id: 'pen', label: 'Pen', shortcut: 'B', cursor: 'crosshair' },
+  { id: 'rect', label: 'Rect', shortcut: 'R', cursor: 'crosshair' },
+  { id: 'ellipse', label: 'Ellipse', shortcut: 'O', cursor: 'crosshair' },
+  { id: 'arrow', label: 'Arrow', shortcut: 'A', cursor: 'crosshair' },
+  { id: 'eraser', label: 'Eraser', shortcut: 'E', cursor: 'cell' },
+]);
+
+interface ToolContextValue {
+  tool: Tool;
+  setTool: (t: Tool) => void;
+  tools: readonly ToolDescriptor[];
+}
+
+const ToolContext = createContext<ToolContextValue | null>(null);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider
+
+export function ToolProvider({
+  children,
+  tools = DEFAULT_TOOLS,
+  initial = 'move',
+}: {
+  children: ReactNode;
+  tools?: readonly ToolDescriptor[];
+  initial?: Tool;
+}) {
+  const [tool, setToolState] = useState<Tool>(initial);
+  const setTool = useCallback((t: Tool) => setToolState(t), []);
+
+  // Body cursor sync — applied to the canvas iframe's body (this hook runs
+  // inside the iframe context). The viewport-controller still owns the
+  // grabbing/grab cursor swap during space-pan; this only sets the resting
+  // cursor for the active tool.
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const desc = tools.find((t) => t.id === tool);
+    if (!desc) return;
+    const prev = document.body.style.cursor;
+    document.body.style.cursor = desc.cursor;
+    return () => {
+      document.body.style.cursor = prev;
+    };
+  }, [tool, tools]);
+
+  const value = useMemo<ToolContextValue>(() => ({ tool, setTool, tools }), [tool, setTool, tools]);
+
+  return <ToolContext.Provider value={value}>{children}</ToolContext.Provider>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+
+export function useToolMode(): ToolContextValue {
+  const ctx = useContext(ToolContext);
+  if (!ctx) {
+    throw new Error('useToolMode must be used inside <ToolProvider>');
+  }
+  return ctx;
+}
+
+/**
+ * Read-only variant — returns `null` when no provider mounted. Used by
+ * components that can render outside a ToolProvider tree (the input
+ * router's optional path).
+ */
+export function useToolModeOptional(): ToolContextValue | null {
+  return useContext(ToolContext);
+}

package/plugins/design/dev-server/ws.ts

@@ -0,0 +1,90 @@
+// Bun.serve native WebSocket handlers — replaces server.mjs's hand-rolled
+// RFC-6455 upgrade. Per-connection state lives on ws.data (Bun's typed slot).
+
+import type { ServerWebSocket, WebSocketHandler } from 'bun';
+
+import type { Api } from './api.ts';
+import type { Context } from './context.ts';
+import { createHmrBroadcaster } from './hmr-broadcast.ts';
+import type { Inspect } from './inspect.ts';
+
+export interface WsData {
+  id: string;
+  remote: string;
+}
+
+export interface Ws {
+  handler: WebSocketHandler<WsData>;
+  broadcast(payload: unknown): void;
+  clientCount(): number;
+}
+
+export function createWs(ctx: Context, api: Api, inspect: Inspect): Ws {
+  const clients = new Set<ServerWebSocket<WsData>>();
+
+  function send(ws: ServerWebSocket<WsData>, payload: unknown) {
+    try {
+      ws.send(typeof payload === 'string' ? payload : JSON.stringify(payload));
+    } catch {
+      /* dead socket — close handler will clean up */
+    }
+  }
+
+  function broadcast(payload: unknown) {
+    const msg = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    for (const ws of clients) send(ws, msg);
+  }
+
+  // Wire bus -> WS broadcasts. inspect.ts emits 'selected' / 'active' after every
+  // state write; fs-watch.ts emits 'fs:*' on every save.
+  ctx.bus.on('selected', (sel) => broadcast({ type: 'selected', selected: sel }));
+  ctx.bus.on('active', (file) => broadcast({ type: 'active', file }));
+  ctx.bus.on('fs:html', (file) => broadcast({ type: 'fs:html', file }));
+  ctx.bus.on('fs:css', (file) => broadcast({ type: 'fs:css', file }));
+  ctx.bus.on('fs:json', (file) => broadcast({ type: 'fs:json', file }));
+  ctx.bus.on('comments', ({ file, comments }: { file: string; comments: unknown[] }) =>
+    broadcast({ type: 'comments', file, comments })
+  );
+
+  // HMR broadcaster — turns fs:any change events into `canvas-hmr` messages.
+  // The iframe-side client (in _shell.html) decides reload strategy from `mode`.
+  createHmrBroadcaster(ctx, (msg) => broadcast(msg));
+
+  const handler: WebSocketHandler<WsData> = {
+    open(ws) {
+      clients.add(ws);
+      send(ws, { type: 'snapshot', state: inspect.state });
+    },
+    close(ws) {
+      clients.delete(ws);
+    },
+    async message(ws, raw) {
+      // biome-ignore lint/suspicious/noExplicitAny: JSON.parse result; narrowed by runtime discriminator checks below.
+      let msg: any;
+      try {
+        msg = JSON.parse(typeof raw === 'string' ? raw : new TextDecoder().decode(raw));
+      } catch {
+        return;
+      }
+      if (!msg || typeof msg !== 'object') return;
+      try {
+        if (msg.type === 'active' && typeof msg.file === 'string') inspect.setActive(msg.file);
+        else if (msg.type === 'tabs' && Array.isArray(msg.tabs)) inspect.setOpenTabs(msg.tabs);
+        else if (msg.type === 'select' && msg.selection) inspect.setSelected(msg.selection);
+        else if (msg.type === 'clear-select') inspect.setSelected(null);
+        else if (msg.type === 'comments-add' && msg.payload) await api.commentsAdd(msg.payload);
+        else if (msg.type === 'comments-patch' && msg.id)
+          await api.commentsPatch(msg.id, msg.patch || {});
+        else if (msg.type === 'comments-delete' && msg.id) await api.commentsDelete(msg.id);
+        else if (msg.type === 'comments-request' && typeof msg.file === 'string') {
+          const comments = await api.loadCommentsForFile(msg.file);
+          send(ws, { type: 'comments', file: msg.file, comments });
+        }
+      } catch (err) {
+        console.error('[ws] message handler threw:', err);
+      }
+    },
+  };
+
+  return { handler, broadcast, clientCount: () => clients.size };
+}

package/plugins/design/templates/_shell.html

@@ -0,0 +1,177 @@
+<!doctype html>
+<!--
+  _shell.html — shared canvas mount harness (DDR-019, Phase 3.6).
+
+  How it works:
+    1. The dev-server's TSX-canvas iframe loads this file with
+         ?canvas=<path-relative-to-designRoot>
+       (e.g. ?canvas=ui/Docs%20Site.tsx).
+    2. The importmap below resolves "react", "react-dom/client",
+       "react/jsx-runtime", "react/jsx-dev-runtime" against the four
+       /_canvas-runtime/*.js bundles served by the dev-server. The browser
+       only fetches each bundle once — every canvas in the session shares them.
+    3. The canvas TSX module is fetched from the same path under designRoot.
+       The dev-server's /<designRel>/ui/<slug>.tsx route runs canvas-pipeline
+       (data-cd-id injection) then Bun.build (browser-loadable ESM) and serves
+       the result with Content-Type application/javascript.
+    4. We grab the default export, wrap it in React's createRoot, and render
+       into <div id="canvas-root">. The token + component CSS files load
+       cooperatively — same href as for legacy .html canvases, so the visual
+       contract is identical.
+
+  This file is part of the plugin distribution; the dev-server serves it
+  directly from plugins/design/templates/. It is intentionally NOT copied
+  into <designRoot> — the dev-server is its single source of truth.
+-->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>Canvas</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+      }
+      html, body, #canvas-root { height: 100%; margin: 0; }
+      body { background: var(--u-bg-0, #fff); }
+      #canvas-mount-error {
+        font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+        padding: 16px 20px;
+        color: #b91c1c;
+        background: #fff5f5;
+        white-space: pre-wrap;
+      }
+      #canvas-mount-error:empty { display: none; }
+    </style>
+    <!-- Tokens + DS component CSS — loaded by the host app via the canvas's
+         .meta.json (set later via window.parent postMessage, OR by the dev-
+         server when it knows the active DS). For now we load both common
+         paths; one will 404 silently per DS depending on layout. -->
+    <link id="canvas-tokens" rel="stylesheet" href="" data-canvas-css="tokens" />
+    <link id="canvas-components" rel="stylesheet" href="" data-canvas-css="components" />
+    <script type="importmap">
+      {
+        "imports": {
+          "react": "/_canvas-runtime/react.js",
+          "react-dom": "/_canvas-runtime/react-dom.js",
+          "react-dom/client": "/_canvas-runtime/react-dom_client.js",
+          "react/jsx-runtime": "/_canvas-runtime/react_jsx-runtime.js",
+          "react/jsx-dev-runtime": "/_canvas-runtime/react_jsx-dev-runtime.js",
+          "pixi.js": "/_canvas-runtime/pixi-js.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <div id="canvas-root"></div>
+    <pre id="canvas-mount-error"></pre>
+
+    <script type="module">
+      const params = new URLSearchParams(location.search);
+      const canvasRel = params.get('canvas');
+      const designRel = params.get('designRel') || '.design';
+      const tokensRel = params.get('tokens') || '';
+      const componentsRel = params.get('components') || '';
+      const layoutRel = params.get('layout') || '';
+
+      function showError(msg) {
+        const el = document.getElementById('canvas-mount-error');
+        if (el) el.textContent = msg;
+        console.error('[canvas-shell]', msg);
+      }
+
+      // ---------------------------------------------------------------------
+      // HMR client — listens for `canvas-hmr` messages on /_ws. Three modes:
+      //   - css: swap <link> href with ?v=<version> cache bust.
+      //   - module: location.reload() — the canvas module re-fetches.
+      //   - hard: location.reload() — _lib/* changed, everything re-bundles.
+      // The WS connection retries on close (dev-server restart resilience).
+      function connectHmr() {
+        const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+        const ws = new WebSocket(proto + '://' + location.host + '/_ws');
+        ws.addEventListener('message', (ev) => {
+          try {
+            const msg = JSON.parse(ev.data);
+            if (!msg || msg.type !== 'canvas-hmr') return;
+            if (msg.mode === 'css') {
+              const v = msg.version || Date.now();
+              // Match by exact filename when we have one; otherwise refresh all.
+              const targetFile = (msg.file || '').split('/').pop();
+              for (const link of document.querySelectorAll('link[rel="stylesheet"]')) {
+                const href = link.getAttribute('href') || '';
+                if (!targetFile || href.includes(targetFile)) {
+                  const base = href.split('?')[0];
+                  link.setAttribute('href', base + '?v=' + v);
+                }
+              }
+            } else if (msg.mode === 'module' || msg.mode === 'hard') {
+              // Only reload when the change touches *this* canvas (or `_lib`).
+              if (msg.mode === 'hard' || !msg.file || (canvasRel && msg.file === canvasRel)) {
+                location.reload();
+              }
+            }
+          } catch (e) {
+            console.warn('[canvas-shell] HMR message parse error', e);
+          }
+        });
+        ws.addEventListener('close', () => {
+          // Reconnect after a beat — dev-server may have restarted.
+          setTimeout(connectHmr, 750);
+        });
+      }
+      connectHmr();
+
+      if (!canvasRel) {
+        showError('Missing ?canvas= query parameter. Add ?canvas=ui/<slug>.tsx.');
+      } else {
+        if (tokensRel) document.getElementById('canvas-tokens').href = '/' + designRel + '/' + tokensRel;
+        if (componentsRel) document.getElementById('canvas-components').href = '/' + designRel + '/' + componentsRel;
+        if (layoutRel) {
+          // Inject a third <link> for the DS layout chrome (specimens load this).
+          const layoutLink = document.createElement('link');
+          layoutLink.rel = 'stylesheet';
+          layoutLink.href = '/' + designRel + '/' + layoutRel;
+          layoutLink.dataset.canvasCss = 'layout';
+          document.head.appendChild(layoutLink);
+        }
+
+        const canvasUrl = '/' + designRel + '/' + canvasRel;
+        // Phase 4 T5 — read the canvas's sibling .meta.json and stash it on
+        // window so DesignCanvas can seed `layout` + `viewport` synchronously.
+        // The fetch runs in parallel with imports; failure is non-fatal (the
+        // canvas falls through to default grid + fit-to-screen).
+        const metaFileParam = encodeURIComponent(designRel + '/' + canvasRel);
+        const metaFetch = fetch('/_api/canvas-meta?file=' + metaFileParam, {
+          headers: { 'Cache-Control': 'no-store' },
+        })
+          .then((r) => (r.ok ? r.json() : null))
+          .then((j) => {
+            window.__canvas_meta__ = (j && typeof j === 'object') ? j : {};
+            window.__canvas_meta_file__ = designRel + '/' + canvasRel;
+          })
+          .catch(() => {
+            window.__canvas_meta__ = {};
+            window.__canvas_meta_file__ = designRel + '/' + canvasRel;
+          });
+        try {
+          const [{ createRoot }, mod, react] = await Promise.all([
+            import('react-dom/client'),
+            import(canvasUrl),
+            import('react'),
+            metaFetch,
+          ]);
+          const Canvas = mod.default;
+          if (typeof Canvas !== 'function') {
+            throw new Error(
+              'Canvas module at ' + canvasUrl + ' has no default export (or it is not a component).'
+            );
+          }
+          const root = createRoot(document.getElementById('canvas-root'));
+          root.render(react.createElement(Canvas));
+        } catch (err) {
+          showError((err && err.stack) || String(err));
+        }
+      }
+    </script>
+  </body>
+</html>

package/plugins/design/templates/canvas.tsx.template

@@ -0,0 +1,54 @@
+/**
+ * @canvas      {{NAME}} — {{SUBTITLE}}
+ * @ds          {{DS_NAME}}
+ * @platform    {{PLATFORM}}
+ * @opt_out     {{OPT_OUT_SCOPE}}
+ * @artboards   {{ARTBOARDS}}
+ * @brief       {{BRIEF}}
+ * @stack       React 19 · TSX · Bun.build · css_mode={{CSS_MODE}}
+ * @history     {{HISTORY_DIR}}
+ * @handoff     bunx shadcn add file://./{{NAME}}.registry.json
+ *
+ * Authored under {{DS_NAME}}. Tokens + shared component classes load via the
+ * dev-server's _shell.html harness — link tags arrive automatically from the
+ * iframe's ?tokens= / ?components= query. Class names match the DS's
+ * `_components.css` (`.btn`, `.tile`, `.sku`, `.seg`, ...). Bespoke classes go
+ * into a sibling .module.css iff `css_mode === "modules"`; for `inline` (the
+ * MDCC-DSN/01 default) prefer existing classes + `style={{}}` for arbitrary
+ * one-off values.
+ *
+ * The envelope primitives (`DesignCanvas`, `DCSection`, `DCArtboard`) and any
+ * specimen helpers come from the dev-server-bundled canvas library via the
+ * virtual specifier — the dev-server resolves it to
+ * `plugins/design/dev-server/canvas-lib.tsx` (single source, ships with the
+ * dev-server install per DDR-025), and `/design:handoff` AST-inlines the used
+ * exports so the registry-item drop is self-contained. Read that file for the
+ * full export surface (helpers + hooks) before reaching for new components.
+ *
+ * `data-cd-id="<8 hex>"` attributes are injected at request time by the dev
+ * server (canvas-pipeline.ts pass 1). Don't author them by hand — they'd be
+ * stripped + replaced. `/design:handoff` strips them again before the registry
+ * sidecar leaves dev (production has no business with dev-time scaffolding).
+ */
+
+import { useState } from "react";
+
+import { DesignCanvas, DCSection, DCArtboard } from "@maude/canvas-lib";
+
+export default function {{COMPONENT_NAME}}() {
+  return (
+    <DesignCanvas>
+      <DCSection id="overview" title="{{SUBTITLE}}">
+        <DCArtboard id="primary" label="A · primary" width={1280} height={800}>
+          <div className="mdcc" data-theme="{{THEME_DEFAULT}}">
+            {/* Replace this scaffold with the actual canvas content. The
+                envelope this template was rendered against is in
+                {{HISTORY_DIR}}/000-envelope.md. */}
+            <h1 className="sku">{{NAME}}</h1>
+            <p>{{BRIEF}}</p>
+          </div>
+        </DCArtboard>
+      </DCSection>
+    </DesignCanvas>
+  );
+}