@1agh/maude 0.22.2 → 0.23.0

package/plugins/design/dev-server/test/sync-runtime.test.ts

@@ -0,0 +1,285 @@
+// Sync runtime wiring tests — Phase 9 Task 4.
+//
+// Uses an in-memory ProviderFactory so we don't need to start a Hocuspocus
+// server. The agents do real Y.Doc work; the test verifies the runtime
+// honors linkedHub config, discovers canvases, wires up agents, and
+// dispatches fs events through the bus correctly.
+
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+
+import type { Context, DevServerConfig } from '../context.ts';
+import { createBus } from '../context.ts';
+import {
+  type AwarenessRegistry,
+  type SyncProvider,
+  createSyncRuntime,
+  discoverCanvases,
+  toWsUrl,
+} from '../sync/index.ts';
+
+let dir: string;
+let cfgPathEnv: string | undefined;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'sync-runtime-'));
+  cfgPathEnv = process.env.HUBS_CONFIG_PATH;
+  // Point hubs.json to a temp file we control.
+  process.env.HUBS_CONFIG_PATH = join(dir, 'hubs.json');
+});
+
+afterEach(() => {
+  // Node's process.env stringifies on assignment; assigning undefined yields
+  // the literal string "undefined". delete is the correct restoration.
+  // biome-ignore lint/performance/noDelete: process.env semantics.
+  if (cfgPathEnv === undefined) delete process.env.HUBS_CONFIG_PATH;
+  else process.env.HUBS_CONFIG_PATH = cfgPathEnv;
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function writeHubsConfig(url: string, token: string): void {
+  const cfgPath = process.env.HUBS_CONFIG_PATH;
+  if (!cfgPath) throw new Error('HUBS_CONFIG_PATH not set by beforeEach');
+  writeFileSync(cfgPath, JSON.stringify({ hubs: { [url]: { token, linkedAt: 1 } } }));
+  // Match the CLI's saveHubsConfig mode so the DDR-054 §2h mode-warning
+  // doesn't fire on every test.
+  chmodSync(cfgPath, 0o600);
+}
+
+function makeCtx(linkedHub?: DevServerConfig['linkedHub']): Context {
+  // Minimal Context — only the fields the sync runtime touches.
+  const designRoot = join(dir, 'design');
+  mkdirSync(join(designRoot, 'ui'), { recursive: true });
+  mkdirSync(join(designRoot, '_comments'), { recursive: true });
+  return {
+    cfg: {
+      name: 'test',
+      projectLabel: null,
+      designRoot: 'design',
+      canvasGroups: [{ label: 'Canvases', path: 'ui' }],
+      rootClass: 'app',
+      themeDefault: 'dark',
+      tokensCssRel: 'system/colors.css',
+      teamAccentDefault: null,
+      handoffTargets: [],
+      newCanvasDir: 'ui',
+      newComponentDir: 'ui/components',
+      linkedHub,
+      _source: 'defaults',
+    },
+    projectLabel: 'test',
+    paths: {
+      repoRoot: dir,
+      designRel: 'design',
+      designRoot,
+      serverInfoFile: join(designRoot, '_server.json'),
+      activeFile: join(designRoot, '_active.json'),
+      commentsDir: join(designRoot, '_comments'),
+      canvasStateDir: join(designRoot, '_canvas-state'),
+      historyDir: join(designRoot, '_history'),
+      tokensUrlRel: 'design/system/colors.css',
+      systemDirRel: 'system',
+    },
+    bus: createBus(),
+  };
+}
+
+function inMemoryProviderFactory(): {
+  factory: (args: {
+    url: string;
+    token: string;
+    documentName: string;
+  }) => SyncProvider;
+  peerOf: (slug: string) => Y.Doc;
+} {
+  // Map of slug -> { local, peer } Y.Docs cross-linked via applyUpdate.
+  const peers = new Map<string, { local: Y.Doc; peer: Y.Doc }>();
+  const TRANSPORT = Symbol('test-transport');
+
+  function factory(args: {
+    url: string;
+    token: string;
+    documentName: string;
+  }): SyncProvider {
+    const local = new Y.Doc();
+    const peer = new Y.Doc();
+    local.on('update', (update: Uint8Array, origin: unknown) => {
+      if (origin === TRANSPORT) return;
+      Y.applyUpdate(peer, update, TRANSPORT);
+    });
+    peer.on('update', (update: Uint8Array, origin: unknown) => {
+      if (origin === TRANSPORT) return;
+      Y.applyUpdate(local, update, TRANSPORT);
+    });
+    peers.set(args.documentName, { local, peer });
+    return {
+      document: local,
+      awareness: new Awareness(local),
+      async onceSynced() {
+        // Synced immediately for the in-memory pair.
+      },
+      destroy() {
+        local.destroy();
+        peer.destroy();
+      },
+    };
+  }
+
+  return {
+    factory,
+    peerOf(slug: string): Y.Doc {
+      const entry = peers.get(slug);
+      if (!entry) throw new Error(`no provider for slug ${slug}`);
+      return entry.peer;
+    },
+  };
+}
+
+describe('createSyncRuntime', () => {
+  test('returns null when linkedHub is absent (solo mode)', () => {
+    const ctx = makeCtx(undefined);
+    expect(createSyncRuntime(ctx)).toBeNull();
+  });
+
+  test('returns null when token is missing from hubs.json', () => {
+    const ctx = makeCtx({ url: 'https://hub.example.com', linkedAt: 1 });
+    // No hubs.json written — token lookup returns null.
+    expect(createSyncRuntime(ctx)).toBeNull();
+  });
+
+  test('starts agents for each discovered canvas', async () => {
+    const url = 'https://hub.example.com';
+    writeHubsConfig(url, 'mau_test');
+    const ctx = makeCtx({ url, linkedAt: 1 });
+
+    writeFileSync(join(ctx.paths.designRoot, 'ui', 'screen.html'), '<button>hi</button>');
+    writeFileSync(join(ctx.paths.designRoot, 'ui', 'modal.html'), '<dialog>x</dialog>');
+
+    const { factory } = inMemoryProviderFactory();
+    const runtime = createSyncRuntime(ctx, { providerFactory: factory });
+    expect(runtime).not.toBeNull();
+
+    await runtime?.start();
+    expect(runtime?.size()).toBe(2);
+    expect(runtime?.agentFor('ui-screen')).toBeDefined();
+    expect(runtime?.agentFor('ui-modal')).toBeDefined();
+
+    await runtime?.stop();
+  });
+
+  test('adopt mode: pushes local disk state up to the hub on first sync', async () => {
+    const url = 'https://hub.example.com';
+    writeHubsConfig(url, 'mau_test');
+    const ctx = makeCtx({ url, linkedAt: 1, adopt: true });
+
+    writeFileSync(
+      join(ctx.paths.designRoot, 'ui', 'screen.html'),
+      '<button>local-bootstrap</button>'
+    );
+
+    const { factory, peerOf } = inMemoryProviderFactory();
+    const runtime = createSyncRuntime(ctx, { providerFactory: factory });
+    await runtime?.start();
+
+    // Reconcile fires after onceSynced() resolves — give one tick.
+    await new Promise((res) => setTimeout(res, 10));
+
+    expect(peerOf('ui-screen').getText('html').toString()).toBe('<button>local-bootstrap</button>');
+    await runtime?.stop();
+  });
+
+  test('bus fs:any event dispatches through the agent', async () => {
+    const url = 'https://hub.example.com';
+    writeHubsConfig(url, 'mau_test');
+    const ctx = makeCtx({ url, linkedAt: 1 });
+
+    const htmlPath = join(ctx.paths.designRoot, 'ui', 'screen.html');
+    writeFileSync(htmlPath, '');
+
+    const { factory, peerOf } = inMemoryProviderFactory();
+    const runtime = createSyncRuntime(ctx, { providerFactory: factory });
+    await runtime?.start();
+
+    // Simulate a local edit: write to disk, then fire the bus event the
+    // existing fs-watch.ts would emit.
+    writeFileSync(htmlPath, '<button>local</button>');
+    ctx.bus.emit('fs:any', 'ui/screen.html');
+
+    // Wait for fs-mirror's 250ms quiet window + agent flush slack.
+    await new Promise((res) => setTimeout(res, 400));
+
+    expect(peerOf('ui-screen').getText('html').toString()).toBe('<button>local</button>');
+    await runtime?.stop();
+  });
+
+  test('attaches each provider awareness to the registry and detaches on stop', async () => {
+    const url = 'https://hub.example.com';
+    writeHubsConfig(url, 'mau_test');
+    const ctx = makeCtx({ url, linkedAt: 1 });
+
+    writeFileSync(join(ctx.paths.designRoot, 'ui', 'screen.html'), '<button>hi</button>');
+    writeFileSync(join(ctx.paths.designRoot, 'ui', 'modal.html'), '<dialog>x</dialog>');
+
+    const attached: string[] = [];
+    let detachCount = 0;
+    const registry: AwarenessRegistry = {
+      attachHubAwareness(slug, _awareness) {
+        attached.push(slug);
+        return () => {
+          detachCount++;
+        };
+      },
+    };
+
+    const { factory } = inMemoryProviderFactory();
+    const runtime = createSyncRuntime(ctx, { providerFactory: factory, registry });
+    await runtime?.start();
+
+    expect(attached.sort()).toEqual(['ui-modal', 'ui-screen']);
+
+    await runtime?.stop();
+    expect(detachCount).toBe(2);
+  });
+});
+
+describe('discoverCanvases', () => {
+  test('finds .html files but EXCLUDES .tsx (DDR-054 §2b)', async () => {
+    const ctx = makeCtx({ url: 'https://h.example.com', linkedAt: 1 });
+    writeFileSync(join(ctx.paths.designRoot, 'ui', 'a.html'), '');
+    writeFileSync(join(ctx.paths.designRoot, 'ui', 'b.tsx'), '');
+
+    const list = await discoverCanvases(ctx);
+    const slugs = list.map((c) => c.slug).sort();
+    // .tsx is deliberately refused — hostile-hub-pushed JSX would be
+    // transpiled and executed in iframe same-origin. Solo-mode editing
+    // of .tsx is unaffected.
+    expect(slugs).toEqual(['ui-a']);
+  });
+
+  test('skips dirs starting with _ (e.g. _history, _comments)', async () => {
+    const ctx = makeCtx({ url: 'https://h.example.com', linkedAt: 1 });
+    mkdirSync(join(ctx.paths.designRoot, 'ui', '_history'));
+    writeFileSync(join(ctx.paths.designRoot, 'ui', '_history', 'snap.html'), '');
+    writeFileSync(join(ctx.paths.designRoot, 'ui', 'real.html'), '');
+
+    const list = await discoverCanvases(ctx);
+    expect(list.map((c) => c.slug)).toEqual(['ui-real']);
+  });
+});
+
+describe('toWsUrl', () => {
+  test('https → wss', () => {
+    expect(toWsUrl('https://hub.example.com')).toBe('wss://hub.example.com');
+  });
+  test('http → ws', () => {
+    expect(toWsUrl('http://localhost:1234')).toBe('ws://localhost:1234');
+  });
+  test('passthrough for ws://', () => {
+    expect(toWsUrl('ws://localhost:1234')).toBe('ws://localhost:1234');
+  });
+});

package/plugins/design/dev-server/use-collab.tsx

@@ -111,11 +111,164 @@ export interface CollabAwarenessState {
 
 export type ForeignAwareness = Omit<CollabAwarenessState, '__connId'> & { clientID: number };
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Untrusted-input sanitization at the awareness trust boundary.
+//
+// Phase 8 awareness was loopback-only — every state came from a trusted local
+// tab. Phase 9 (Task 5) bridges awareness through a SEMI-TRUSTED hub (DDR-054),
+// so foreign states are now attacker-influenceable. `useForeignAwareness` is
+// the single chokepoint where remote state is read before it reaches the
+// cursor / participant render sinks, so all validation lives here. Fields are
+// validated for VALUE, not just type:
+//   - color: re-derived locally from the (sanitized) name and the wire value
+//     is DISCARDED — a hub-chosen `color` string would otherwise flow into an
+//     inline `style` and a `url(...)` value beacons every viewer's browser.
+//     The palette is deterministic, so re-derivation is visually identical.
+//   - name: control / bidi / zero-width chars stripped, length-capped — blocks
+//     identity spoofing + render bloat.
+//   - cursor / viewport: finite-number gated — a NaN/Infinity would poison the
+//     CSS transform / the local viewport controller during Follow mode.
+//   - selection.cssPath: charset + length allowlist before it reaches
+//     `querySelector` — blocks selector-complexity DoS + arbitrary DOM probing.
+//   - annotationSelection: per-id token + array-length capped — blocks a
+//     querySelector render-storm.
+//   - peer count capped — blocks an unbounded-clients memory/render DoS.
+
+const MAX_FOREIGN_PEERS = 64;
+const MAX_NAME_LEN = 64;
+const MAX_CSSPATH_LEN = 512;
+const MAX_ANNOTATION_IDS = 256;
+const MAX_ANNOTATION_ID_LEN = 128;
+
+// Charset of every selector the canvas-shell `cssPath()` emits
+// (`[data-*="..."]`, `#id`, `tag.cls:nth-child(N)`, ` > ` combinators).
+const CSSPATH_ALLOWED = /^[A-Za-z0-9 ._#>:[\]="'()-]+$/;
+// `cssPath()` only ever emits `:nth-child(N)` as a parenthesised construct.
+// Functional pseudo-classes (`:has()`, `:is()`, `:where()`, `:not()`) trigger
+// per-render subtree walks → a malicious hub peer could publish a deeply
+// nested `:has()` selector and pin every viewer's main thread (querySelector
+// re-runs each render). So after stripping the legit `:nth-child/of-type(N)`
+// forms, any residual paren means a functional pseudo — reject. The charset
+// allowlist alone was wider than the generator (the original DoS hole).
+const CSSPATH_NTH = /:nth-(child|of-type)\(\d{1,4}\)/g;
+const ANNOTATION_ID_ALLOWED = /^[A-Za-z0-9._:-]+$/;
+
+function isSafeCssPath(p: string): boolean {
+  if (p.length > MAX_CSSPATH_LEN || !CSSPATH_ALLOWED.test(p)) return false;
+  const stripped = p.replace(CSSPATH_NTH, '');
+  return !stripped.includes('(') && !stripped.includes(')');
+}
+
+function isFiniteNum(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+// Control (C0/C1), zero-width, and bidi-override code points get stripped from
+// displayed strings so a remote peer can't spoof another's identity or hide
+// payloads in labels. A charCode scan (not a regex literal with raw control
+// chars) sidesteps biome's noControlCharactersInRegex while keeping the same
+// semantics — same approach as the hub's sanitizeForLog (DDR-053).
+function isUnsafeCodePoint(cp: number): boolean {
+  return (
+    cp <= 0x1f ||
+    (cp >= 0x7f && cp <= 0x9f) ||
+    (cp >= 0x200b && cp <= 0x200f) ||
+    (cp >= 0x202a && cp <= 0x202e) ||
+    (cp >= 0x2066 && cp <= 0x2069) ||
+    cp === 0xfeff
+  );
+}
+
+function sanitizeName(raw: unknown): string {
+  if (typeof raw !== 'string') return 'anonymous';
+  let cleaned = '';
+  for (const ch of raw) {
+    if (!isUnsafeCodePoint(ch.codePointAt(0) ?? 0)) cleaned += ch;
+  }
+  cleaned = cleaned.trim().slice(0, MAX_NAME_LEN);
+  return cleaned || 'anonymous';
+}
+
+function sanitizeCursor(raw: unknown): { x: number; y: number } | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const c = raw as { x?: unknown; y?: unknown };
+  return isFiniteNum(c.x) && isFiniteNum(c.y) ? { x: c.x, y: c.y } : null;
+}
+
+function sanitizeViewport(raw: unknown): { x: number; y: number; zoom: number } {
+  const fallback = { x: 0, y: 0, zoom: 1 };
+  if (!raw || typeof raw !== 'object') return fallback;
+  const v = raw as { x?: unknown; y?: unknown; zoom?: unknown };
+  if (!isFiniteNum(v.x) || !isFiniteNum(v.y) || !isFiniteNum(v.zoom) || v.zoom <= 0)
+    return fallback;
+  return { x: v.x, y: v.y, zoom: v.zoom };
+}
+
+function sanitizeSelection(raw: unknown): CollabAwarenessState['selection'] {
+  if (!raw || typeof raw !== 'object') return null;
+  const s = raw as { cssPath?: unknown; bounds?: unknown };
+  const b = s.bounds as { x?: unknown; y?: unknown; w?: unknown; h?: unknown } | undefined;
+  const bounds =
+    b && isFiniteNum(b.x) && isFiniteNum(b.y) && isFiniteNum(b.w) && isFiniteNum(b.h)
+      ? { x: b.x, y: b.y, w: b.w, h: b.h }
+      : null;
+  // Only keep cssPath if it matches the locator grammar — otherwise drop it and
+  // let the renderer fall back to the (validated) bounds.
+  const cssPath = typeof s.cssPath === 'string' && isSafeCssPath(s.cssPath) ? s.cssPath : '';
+  if (!cssPath && !bounds) return null;
+  return { cssPath, bounds: bounds ?? { x: 0, y: 0, w: 0, h: 0 } };
+}
+
+function sanitizeAnnotationSelection(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const id of raw) {
+    if (out.length >= MAX_ANNOTATION_IDS) break;
+    if (
+      typeof id === 'string' &&
+      id.length <= MAX_ANNOTATION_ID_LEN &&
+      ANNOTATION_ID_ALLOWED.test(id)
+    )
+      out.push(id);
+  }
+  return out;
+}
+
+/**
+ * Validate + normalize one foreign awareness state at the trust boundary.
+ * Returns null for states that can't be a peer (no usable name). `color` is
+ * always re-derived locally from the sanitized name — the wire value is never
+ * trusted, which is what closes the hub CSS-`url()` exfil channel. Exported so
+ * the hostile-input matrix can exercise it without a React harness.
+ */
+export function sanitizeForeignState(clientID: number, state: unknown): ForeignAwareness | null {
+  if (!state || typeof state !== 'object') return null;
+  const s = state as Partial<CollabAwarenessState>;
+  if (typeof s.name !== 'string') return null;
+  const name = sanitizeName(s.name);
+  return {
+    clientID,
+    name,
+    color: colorForName(name),
+    cursor: sanitizeCursor(s.cursor),
+    selection: sanitizeSelection(s.selection),
+    annotationSelection: sanitizeAnnotationSelection(s.annotationSelection),
+    viewport: sanitizeViewport(s.viewport),
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Context.
 
 interface CollabValue {
   doc: Y.Doc;
+  /**
+   * SECURITY INVARIANT: in linked mode this Awareness carries states relayed
+   * from a SEMI-TRUSTED hub (DDR-054). Foreign states are untrusted input —
+   * read them ONLY through `useForeignAwareness`, which sanitizes every field
+   * at the trust boundary (`sanitizeForeignState`). Do NOT call
+   * `awareness.getStates()` directly in render code; that bypasses the gate.
+   */
   awareness: Awareness;
   /** Local peer's session-stable color (derived from git user.name). */
   myColor: string;
@@ -158,19 +311,10 @@ export function useForeignAwareness(): ForeignAwareness[] {
       const myId = awareness.clientID;
       for (const [clientID, state] of awareness.getStates() as Map<number, unknown>) {
         if (clientID === myId) continue;
-        if (!state || typeof state !== 'object') continue;
-        const s = state as Partial<CollabAwarenessState>;
-        // Guard against partial states from stale peers / older protocol versions.
-        if (typeof s.name !== 'string' || typeof s.color !== 'string') continue;
-        out.push({
-          clientID,
-          name: s.name,
-          color: s.color,
-          cursor: s.cursor ?? null,
-          selection: s.selection ?? null,
-          annotationSelection: Array.isArray(s.annotationSelection) ? s.annotationSelection : [],
-          viewport: s.viewport ?? { x: 0, y: 0, zoom: 1 },
-        });
+        if (out.length >= MAX_FOREIGN_PEERS) break; // bound DoS via unbounded peers
+        // Sanitize every now-remote field at this trust boundary (Task 5).
+        const peer = sanitizeForeignState(clientID, state);
+        if (peer) out.push(peer);
       }
       return out;
     }

package/plugins/design/dev-server/use-selection-set.tsx

@@ -189,6 +189,18 @@ export function SelectionSetProvider({
   return <SelectionSetContext.Provider value={value}>{children}</SelectionSetContext.Provider>;
 }
 
+/**
+ * Mount a `SelectionSetProvider` only when none exists above us. The shell-
+ * owned comment mount layer provides one so both the lite comment router and
+ * `CanvasShell` share a single selection set. Hook called unconditionally;
+ * only the returned tree branches (hook rules).
+ */
+export function MaybeSelectionSetProvider({ children }: { children: ReactNode }) {
+  const outer = useContext(SelectionSetContext);
+  if (outer) return <>{children}</>;
+  return <SelectionSetProvider>{children}</SelectionSetProvider>;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Hooks
 

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

@@ -122,6 +122,18 @@ export function ToolProvider({
   return <ToolContext.Provider value={value}>{children}</ToolContext.Provider>;
 }
 
+/**
+ * Mount a `ToolProvider` only when none exists above us. When the shell-owned
+ * comment mount layer (canvas-comment-mount.tsx) already provides one,
+ * `DesignCanvas` consumes that instance instead of double-mounting. The hook
+ * is called unconditionally; only the returned tree branches (hook rules).
+ */
+export function MaybeToolProvider({ children }: { children: ReactNode }) {
+  const outer = useContext(ToolContext);
+  if (outer) return <>{children}</>;
+  return <ToolProvider>{children}</ToolProvider>;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Hook
 

package/plugins/design/templates/_shell.html

@@ -122,6 +122,10 @@
         const styleEl = document.getElementById('canvas-hide-chrome');
         if (styleEl) styleEl.media = 'all';
       }
+      // Shell-owned comment layer toggle. Gallery thumbnails pass `?comments=0`
+      // so the comment chrome is suppressed in previews; opened tabs omit it
+      // (comments on). hide-chrome exports also suppress comments.
+      const commentsEnabled = params.get('comments') !== '0' && params.get('hide-chrome') !== '1';
 
       function showError(msg) {
         const el = document.getElementById('canvas-mount-error');
@@ -234,10 +238,13 @@
             window.__canvas_meta_file__ = designRel + '/' + canvasRel;
           });
         try {
-          const [{ createRoot }, mod, react] = await Promise.all([
-            import('react-dom/client'),
+          // mountCanvas (dist/comment-mount.js) owns the React root + the lite
+          // comment provider tree. It externalizes react / react-dom/client to
+          // the importmap so the canvas module and the comment layer share one
+          // React singleton (inlining a second React would break hooks).
+          const [{ mountCanvas }, mod] = await Promise.all([
+            import('/_client/comment-mount.js'),
             import(canvasUrl),
-            import('react'),
             metaFetch,
           ]);
           const Canvas = mod.default;
@@ -246,8 +253,11 @@
               '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));
+          mountCanvas(Canvas, {
+            rootEl: document.getElementById('canvas-root'),
+            file: designRel + '/' + canvasRel,
+            commentsEnabled,
+          });
         } catch (err) {
           showError((err && err.stack) || String(err));
         }

package/plugins/design/templates/design-system-inspiration/SUB-AGENT-PROMPTS.md

@@ -14,6 +14,7 @@ The three MANDATORY safety blocks (ANIMATION SAFETY, RELATIVE-URL SAFETY, PLACEH
 
 ### ANIMATION SAFETY (mandatory — applies to motion specimen + any canvas with @keyframes / transitions)
 
+- **Tooling contract first (DDR-049).** The authoritative rule for WHICH tool to use is the "Animation tooling contract" in `skills/design-system/SKILL.md`: the **default for both specimens and canvases is `<MotionDemo role>` / the canvas-lib vocabulary from `@maude/canvas-lib`** (wraps `motion/react`), NOT hand-rolled `@keyframes`. Pure-CSS `.motion-*` role classes are a justified-only zero-JS escape hatch. The CSS rules below apply to that escape hatch and to the bounded-geometry constraints the vocabulary already satisfies — they do NOT license reaching for `@keyframes` by default.
 - **Bounded geometry.** Every tile that hosts a rotating / scaling animation MUST have `overflow: hidden`. Otherwise the bounding box extends ~√2× at 45°/135° rotations and overflows adjacent rows. **The motion specimen tiles all set `overflow: hidden` explicitly** — codify this with a CSS comment so future agents reading the file see the rationale.
 - **Sparkle / pulse / twinkle = small only.** Keyframes that scale from `0 → 1 → 0` (or similar "appear-and-disappear" patterns) are for elements ≤56px. **Never apply to full-width tiles.** Demo sparkle on a 32×32 chip inside a tile, never on the tile itself. The studyfi imprint retro D-3 caught a sparkle-on-full-tile that exploded the whole row.
 - **Loop motion = `infinite alternate`.** Specimens meant for continuous display use `animation: <kf> <dur> infinite alternate <easing>`. Single-shot animations finish in 150-200ms and leave the demo invisible on the second look — "looks dead until you hover" is the regression mode.