pmx-canvas 0.1.26 → 0.1.28

package/src/cli/agent.ts

@@ -11,7 +11,9 @@
  * - --yes for destructive actions, --dry-run for preview
  */
 
-import { readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { openUrlInExternalBrowser, wrapCanvasAutomationScript } from '../server/server.js';
 import { DEFAULT_EXCALIDRAW_ELEMENTS } from '../server/diagram-presets.js';
 import {
@@ -166,6 +168,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
     'help', 'h', 'ids', 'stdin', 'yes', 'list', 'clear', 'set', 'animated', 'dry-run', 'all',
     'no-open-in-canvas', 'lock-arrange', 'unlock-arrange', 'json', 'compact',
     'verbose', 'include-logs', 'no-pan', 'schema', 'example', 'examples', 'strict-size', 'scroll-overflow',
+    'report', 'canvas', 'hooks', 'tools', 'session-messaging', 'permissions', 'files', 'ui-prompts',
   ]);
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -183,7 +186,12 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
         }
       }
     } else if (arg.startsWith('-') && arg.length === 2) {
-      flags[arg.slice(1)] = true;
+      const key = arg.slice(1);
+      if (!BOOL_FLAGS.has(key) && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+        flags[key] = args[++i];
+      } else {
+        flags[key] = true;
+      }
     } else {
       positional.push(arg);
     }
@@ -797,7 +805,28 @@ async function buildWebArtifactRequestBody(
 }
 
 async function runWebArtifactBuildCommand(flags: Record<string, string | true>): Promise<void> {
-  const result = await api('POST', '/api/canvas/web-artifact', await buildWebArtifactRequestBody(flags), { allowErrorJson: true });
+  const body = await buildWebArtifactRequestBody(flags);
+  // The build (init + dependency install + bundle) runs server-side and only
+  // returns a single HTTP response on completion, which can take minutes on a
+  // cold workspace. With no output an agent's tool wait expires before the node
+  // appears and the build looks hung. Emit a default-on heartbeat to stderr
+  // while the request is in flight — stdout (output) and the JSON response body
+  // stay untouched, so anything parsing stdout is unaffected.
+  const startedMs = Date.now();
+  process.stderr.write(
+    `[web-artifact] building "${String(body.title)}" — init + install + bundle (this can take a few minutes)...\n`,
+  );
+  const heartbeat = setInterval(() => {
+    const elapsedSeconds = Math.round((Date.now() - startedMs) / 1000);
+    process.stderr.write(`[web-artifact] still building... ${elapsedSeconds}s elapsed\n`);
+  }, 10_000);
+  if (typeof heartbeat.unref === 'function') heartbeat.unref();
+  let result: unknown;
+  try {
+    result = await api('POST', '/api/canvas/web-artifact', body, { allowErrorJson: true });
+  } finally {
+    clearInterval(heartbeat);
+  }
   output(result);
   if (isRecord(result) && result.ok === false) {
     process.exit(1);
@@ -1102,6 +1131,7 @@ cmd('node add', 'Add a node to the canvas', [
   'pmx-canvas node add --type file --content "src/index.ts"',
   'pmx-canvas node add --type webpage --url "https://example.com/docs"',
   'pmx-canvas node add --type html --title "Widget" --content "<main>Hello</main>"',
+  'pmx-canvas node add --type html --title "Showcase" --content ./report.html   (a .html path is read from disk; otherwise --content is raw HTML)',
   'pmx-canvas node add --type html --primitive choice-grid --data-file ./options.json --title "Options"',
   'pmx-canvas node add --type markdown --title "Note" --x 100 --y 200',
   'pmx-canvas node add --type json-render --title "Ops Dashboard" --spec-file ./dashboard.json',
@@ -1801,6 +1831,275 @@ cmd('ax focus', 'Set or clear PMX AX focus without moving the viewport', [
   output(await api('POST', '/api/canvas/ax/focus', { nodeIds, source: 'cli' }));
 });
 
+cmd('ax event add', 'Record a normalized AX timeline event', [
+  'pmx-canvas ax event add --kind tool-start --summary "ran tests"',
+  'pmx-canvas ax event add --kind failure --summary "build broke" --detail "..." node1 node2',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax event add');
+
+  const kind = requireFlag(flags, 'kind', 'pmx-canvas ax event add --kind <kind> --summary <text>');
+  const summary = requireFlag(flags, 'summary', 'pmx-canvas ax event add --kind <kind> --summary <text>');
+  const detail = getStringFlag(flags, 'detail');
+
+  output(await api('POST', '/api/canvas/ax/event', {
+    kind,
+    summary,
+    ...(detail ? { detail } : {}),
+    ...(positional.length > 0 ? { nodeIds: positional } : {}),
+    source: 'cli',
+  }));
+});
+
+cmd('ax steer', 'Send a steering message to the active agent session', [
+  'pmx-canvas ax steer "focus on the failing test first"',
+  'pmx-canvas ax steer --message "stop and re-plan"',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax steer');
+
+  const message = getStringFlag(flags, 'message') ?? positional.join(' ').trim();
+  if (!message) {
+    die('Missing steering message', 'pmx-canvas ax steer <message>');
+  }
+
+  output(await api('POST', '/api/canvas/ax/steer', { message, source: 'cli' }));
+});
+
+cmd('ax timeline', 'Read the bounded AX timeline (events, evidence, steering)', [
+  'pmx-canvas ax timeline',
+  'pmx-canvas ax timeline --limit 100',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax timeline');
+
+  const limit = optionalNumberFlag(flags, 'limit', 'pmx-canvas ax timeline --limit <n>');
+  output(await api('GET', `/api/canvas/ax/timeline${limit ? `?limit=${limit}` : ''}`));
+});
+
+cmd('ax work add', 'Add a canvas-bound AX work item', [
+  'pmx-canvas ax work add --title "Wire up auth" --status in-progress',
+  'pmx-canvas ax work add --title "Review API" node1 node2',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax work add');
+
+  const title = requireFlag(flags, 'title', 'pmx-canvas ax work add --title <text>');
+  const status = getStringFlag(flags, 'status');
+  const detail = getStringFlag(flags, 'detail');
+
+  output(await api('POST', '/api/canvas/ax/work', {
+    title,
+    ...(status ? { status } : {}),
+    ...(detail ? { detail } : {}),
+    ...(positional.length > 0 ? { nodeIds: positional } : {}),
+    source: 'cli',
+  }));
+});
+
+cmd('ax work update', 'Update a canvas-bound AX work item by ID', [
+  'pmx-canvas ax work update <id> --status done',
+  'pmx-canvas ax work update <id> --title "New title" --detail "..."',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax work update');
+
+  const id = positional[0];
+  if (!id) die('Missing work item ID', 'pmx-canvas ax work update <id> --status <status>');
+  const title = getStringFlag(flags, 'title');
+  const status = getStringFlag(flags, 'status');
+  const detail = getStringFlag(flags, 'detail');
+
+  output(await api('PATCH', `/api/canvas/ax/work/${encodeURIComponent(id)}`, {
+    ...(title ? { title } : {}),
+    ...(status ? { status } : {}),
+    ...(detail ? { detail } : {}),
+    ...(positional.length > 1 ? { nodeIds: positional.slice(1) } : {}),
+    source: 'cli',
+  }));
+});
+
+cmd('ax work list', 'List canvas-bound AX work items', [
+  'pmx-canvas ax work list',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax work list');
+
+  output(await api('GET', '/api/canvas/ax/work'));
+});
+
+cmd('ax approval request', 'Request a canvas-bound AX approval gate', [
+  'pmx-canvas ax approval request --title "Deploy to prod"',
+  'pmx-canvas ax approval request --title "Drop table" --action db.drop node1',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax approval request');
+
+  const title = requireFlag(flags, 'title', 'pmx-canvas ax approval request --title <text>');
+  const detail = getStringFlag(flags, 'detail');
+  const action = getStringFlag(flags, 'action');
+
+  output(await api('POST', '/api/canvas/ax/approval', {
+    title,
+    ...(detail ? { detail } : {}),
+    ...(action ? { action } : {}),
+    ...(positional.length > 0 ? { nodeIds: positional } : {}),
+    source: 'cli',
+  }));
+});
+
+cmd('ax approval resolve', 'Resolve a pending AX approval gate by ID', [
+  'pmx-canvas ax approval resolve <id> --decision approved',
+  'pmx-canvas ax approval resolve <id> --decision rejected --resolution "too risky"',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax approval resolve');
+
+  const id = positional[0];
+  if (!id) die('Missing approval gate ID', 'pmx-canvas ax approval resolve <id> --decision <approved|rejected>');
+  const decision = requireFlag(flags, 'decision', 'pmx-canvas ax approval resolve <id> --decision <approved|rejected>');
+  if (decision !== 'approved' && decision !== 'rejected') {
+    die('Invalid decision', 'pmx-canvas ax approval resolve <id> --decision <approved|rejected>');
+  }
+  const resolution = getStringFlag(flags, 'resolution');
+
+  output(await api('POST', `/api/canvas/ax/approval/${encodeURIComponent(id)}/resolve`, {
+    decision,
+    ...(resolution ? { resolution } : {}),
+    source: 'cli',
+  }));
+});
+
+cmd('ax approval list', 'List canvas-bound AX approval gates', [
+  'pmx-canvas ax approval list',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax approval list');
+
+  output(await api('GET', '/api/canvas/ax/approval'));
+});
+
+cmd('ax evidence add', 'Record an AX evidence item on the timeline', [
+  'pmx-canvas ax evidence add --kind test-output --title "unit pass" --body "..."',
+  'pmx-canvas ax evidence add --kind screenshot --title "before" --ref /tmp/before.png node1',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax evidence add');
+
+  const kind = requireFlag(flags, 'kind', 'pmx-canvas ax evidence add --kind <kind> --title <text>');
+  const title = requireFlag(flags, 'title', 'pmx-canvas ax evidence add --kind <kind> --title <text>');
+  const body = getStringFlag(flags, 'body');
+  const ref = getStringFlag(flags, 'ref');
+
+  output(await api('POST', '/api/canvas/ax/evidence', {
+    kind,
+    title,
+    ...(body ? { body } : {}),
+    ...(ref ? { ref } : {}),
+    ...(positional.length > 0 ? { nodeIds: positional } : {}),
+    source: 'cli',
+  }));
+});
+
+cmd('ax review add', 'Add a canvas-bound AX review annotation', [
+  'pmx-canvas ax review add --body "needs a test" --node node1',
+  'pmx-canvas ax review add --body "off-by-one" --kind finding --severity error --file src/x.ts',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax review add');
+
+  const body = requireFlag(flags, 'body', 'pmx-canvas ax review add --body <text>');
+  const kind = getStringFlag(flags, 'kind');
+  const severity = getStringFlag(flags, 'severity');
+  const anchorType = getStringFlag(flags, 'anchor');
+  const nodeId = getStringFlag(flags, 'node');
+  const file = getStringFlag(flags, 'file');
+  const author = getStringFlag(flags, 'author');
+
+  output(await api('POST', '/api/canvas/ax/review', {
+    body,
+    ...(kind ? { kind } : {}),
+    ...(severity ? { severity } : {}),
+    ...(anchorType ? { anchorType } : {}),
+    ...(nodeId ? { nodeId } : {}),
+    ...(file ? { file } : {}),
+    ...(author ? { author } : {}),
+    source: 'cli',
+  }));
+});
+
+cmd('ax review list', 'List canvas-bound AX review annotations', [
+  'pmx-canvas ax review list',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax review list');
+
+  output(await api('GET', '/api/canvas/ax/review'));
+});
+
+cmd('ax host report', 'Report host/session capability to the canvas', [
+  'pmx-canvas ax host report --host copilot --canvas --tools --session-messaging',
+  'pmx-canvas ax host report --host codex --canvas --files',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax host report');
+
+  const host = getStringFlag(flags, 'host');
+
+  output(await api('PUT', '/api/canvas/ax/host-capability', {
+    ...(host ? { host } : {}),
+    canvas: flags.canvas === true,
+    hooks: flags.hooks === true,
+    tools: flags.tools === true,
+    sessionMessaging: flags['session-messaging'] === true,
+    permissions: flags.permissions === true,
+    files: flags.files === true,
+    uiPrompts: flags['ui-prompts'] === true,
+    source: 'cli',
+  }));
+});
+
+cmd('ax host status', 'Read the reported host/session capability', [
+  'pmx-canvas ax host status',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax host status');
+
+  output(await api('GET', '/api/canvas/ax/host-capability'));
+});
+
+// ── copilot install-extension ────────────────────────────────
+cmd('copilot install-extension', 'Install the bundled GitHub Copilot extension adapter', [
+  'pmx-canvas copilot install-extension --dry-run',
+  'pmx-canvas copilot install-extension --target .github/extensions/pmx-canvas/extension.mjs --yes',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('copilot install-extension');
+
+  const sourcePath = fileURLToPath(new URL('../../.github/extensions/pmx-canvas/extension.mjs', import.meta.url));
+  if (!existsSync(sourcePath)) {
+    die('Bundled Copilot extension adapter not found.', `Expected at ${sourcePath}`);
+  }
+
+  const targetPath = getStringFlag(flags, 'target')
+    ?? join(process.cwd(), '.github', 'extensions', 'pmx-canvas', 'extension.mjs');
+  const dryRun = flags['dry-run'] === true;
+  const targetExists = existsSync(targetPath);
+
+  if (dryRun) {
+    output({ ok: true, dryRun: true, sourcePath, targetPath, targetExists, wrote: false });
+    return;
+  }
+
+  if (targetExists && flags.yes !== true) {
+    die('Target already exists. Re-run with --yes to overwrite.', `Target: ${targetPath}`);
+  }
+
+  mkdirSync(dirname(targetPath), { recursive: true });
+  copyFileSync(sourcePath, targetPath);
+  output({ ok: true, dryRun: false, sourcePath, targetPath, wrote: true });
+});
+
 // ── undo ─────────────────────────────────────────────────────
 cmd('undo', 'Undo the last canvas mutation', [
   'pmx-canvas undo',

package/src/cli/index.ts

@@ -32,7 +32,7 @@ if (args.includes('--version') || args.includes('-v')) {
 const AGENT_COMMANDS = new Set([
   'node', 'edge', 'json-render', 'search', 'layout', 'status', 'arrange', 'focus',
   'fit', 'screenshot', 'pin', 'ax', 'undo', 'redo', 'history', 'snapshot', 'diff', 'group', 'webview', 'open',
-  'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'external-app', 'diagram', 'graph', 'html', 'batch', 'validate', 'serve',
+  'clear', 'code-graph', 'spatial', 'watch', 'web-artifact', 'external-app', 'diagram', 'graph', 'html', 'batch', 'validate', 'serve', 'copilot',
 ]);
 
 const firstArg = args[0] ?? '';
@@ -563,6 +563,7 @@ Examples:
   pmx-canvas validate                                         Check layout collisions
   pmx-canvas watch --events context-pin,move-end              Watch semantic deltas
   pmx-canvas clear --dry-run                                  Preview destructive op
+  pmx-canvas copilot install-extension --dry-run             Preview Copilot adapter install
 `);
     process.exit(0);
   }

package/src/client/nodes/ExtAppFrame.tsx

@@ -8,8 +8,12 @@ import {
   collapseExpandedNode,
   expandNode,
   expandedNodeId,
+  nodes,
+  persistLayout,
+  resizeNode,
 } from '../state/canvas-store';
 import type { CanvasNodeState } from '../types';
+import { AUTO_FIT_TITLEBAR_HEIGHT } from '../canvas/auto-fit';
 import { useIframeDocument } from './iframe-document-url';
 
 type McpUiTheme = 'light' | 'dark';
@@ -120,6 +124,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const bridgeRef = useRef<AppBridge | null>(null);
   const transportRef = useRef<PostMessageTransport | null>(null);
+  const sizePersistTimerRef = useRef<number | null>(null);
   const latestToolInputRef = useRef<Record<string, unknown>>({});
   const latestToolResultRef = useRef<CallToolResult | undefined>(undefined);
   const toolResultSentRef = useRef(false);
@@ -216,6 +221,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     let fallbackTimer: ReturnType<typeof setTimeout> | null = null;
     let hostContextResizeObserver: ResizeObserver | null = null;
     let hostContextRaf: number | null = null;
+    let readyNudgeRaf: number | null = null;
     toolResultSentRef.current = false;
     lastSentToolResultRef.current = undefined;
     toolResultSendingRef.current = null;
@@ -261,6 +267,24 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         });
       };
 
+      // Re-deliver host context once the iframe has been laid out and painted.
+      // Canvas-backed widgets (e.g. Excalidraw) size their drawing surface from
+      // containerDimensions at first render; the single handshake-time delivery
+      // can land before the embedded frame has settled, leaving a black canvas
+      // until an expand/collapse forces a reflow. A double rAF lands after
+      // layout+paint, and sendHostContextChange always delivers (setHostContext
+      // would diff-suppress the identical context just sent at handshake).
+      const nudgeHostContextAfterLayout = () => {
+        if (readyNudgeRaf !== null) return;
+        readyNudgeRaf = requestAnimationFrame(() => {
+          readyNudgeRaf = requestAnimationFrame(() => {
+            readyNudgeRaf = null;
+            if (disposed || !bridgeReadyRef.current) return;
+            void bridge.sendHostContextChange?.(buildHostContext());
+          });
+        });
+      };
+
       const bridge = new AppBridge(
         null,
         { name: 'PMX Canvas', version: '1.0.0' },
@@ -283,7 +307,20 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
             width: node.size.width,
             height: maxHeight,
           });
-          iframe.style.height = `${resolveExtAppInlineFrameHeight(height, hostDimensions.height)}px`;
+          const inlineFrameHeight = resolveExtAppInlineFrameHeight(height, hostDimensions.height);
+          iframe.style.height = `${inlineFrameHeight}px`;
+          const currentSize = nodes.value.get(nodeId)?.size ?? node.size;
+          const nodeHeight = Math.max(currentSize.height, inlineFrameHeight + AUTO_FIT_TITLEBAR_HEIGHT);
+          if (Math.abs(nodeHeight - currentSize.height) > 8) {
+            resizeNode(nodeId, { width: currentSize.width, height: nodeHeight });
+            if (sizePersistTimerRef.current !== null) {
+              window.clearTimeout(sizePersistTimerRef.current);
+            }
+            sizePersistTimerRef.current = window.setTimeout(() => {
+              persistLayout({ recordHistory: false });
+              sizePersistTimerRef.current = null;
+            }, 0);
+          }
         }
         return {};
       };
@@ -386,6 +423,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         void Promise.resolve(bridge.sendHostContextChange(buildHostContext(isExpanded ? 'fullscreen' : 'inline')))
           .then(() => sendExtAppBootstrapState(bridge, latestToolInputRef.current, undefined))
           .then(() => flushToolResult(bridge))
+          .then(() => nudgeHostContextAfterLayout())
           .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             setError(`Bridge bootstrap failed: ${msg}`);
@@ -410,6 +448,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
             }
             setStatus(bootstrapToolResult ? 'done' : 'ready');
             setError(null);
+            nudgeHostContextAfterLayout();
           })
           .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -460,10 +499,18 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         cancelAnimationFrame(hostContextRaf);
         hostContextRaf = null;
       }
+      if (readyNudgeRaf !== null) {
+        cancelAnimationFrame(readyNudgeRaf);
+        readyNudgeRaf = null;
+      }
       bridgeReadyRef.current = false;
       toolResultSendingRef.current = null;
       themeUnsubRef.current?.();
       themeUnsubRef.current = null;
+      if (sizePersistTimerRef.current !== null) {
+        window.clearTimeout(sizePersistTimerRef.current);
+        sizePersistTimerRef.current = null;
+      }
       bridgeRef.current = null;
       if (transportRef.current) {
         transportRef.current.close().catch((closeError) => {

package/src/client/nodes/McpAppNode.tsx

@@ -2,12 +2,15 @@ import type { CanvasNodeState } from '../types';
 import { canvasTheme } from '../state/canvas-store';
 import { ExtAppFrame } from './ExtAppFrame';
 
-function withViewerParams(url: string, expanded: boolean): string {
+function withViewerParams(url: string, expanded: boolean, specVersion?: number): string {
   if (!url) return url;
   try {
     const resolved = new URL(url, window.location.origin);
     resolved.searchParams.set('theme', canvasTheme.value === 'light' ? 'light' : 'dark');
     if (expanded) resolved.searchParams.set('display', 'expanded');
+    // Streaming json-render nodes bump specVersion as patches accumulate; including
+    // it in the src reloads the iframe so it re-reads the latest accumulated spec.
+    if (typeof specVersion === 'number') resolved.searchParams.set('v', String(specVersion));
     return resolved.toString();
   } catch {
     return url;
@@ -31,7 +34,8 @@ export function McpAppNode({ node, expanded = false }: { node: CanvasNodeState;
     return <ExtAppFrame node={node} expanded={expanded} />;
   }
 
-  const url = withViewerParams((node.data.url as string) || '', expanded);
+  const specVersion = typeof node.data.specVersion === 'number' ? node.data.specVersion : undefined;
+  const url = withViewerParams((node.data.url as string) || '', expanded, specVersion);
   const sourceServer = (node.data.sourceServer as string) || '';
   const hostMode = (node.data.hostMode as string) || 'hosted';
   const fallbackReason = node.data.fallbackReason as string | undefined;

package/src/json-render/catalog.ts

@@ -12,8 +12,11 @@ import { schema } from './schema.js';
 import { shadcnComponentDefinitions } from '@json-render/shadcn/catalog';
 import { chartComponentDefinitions } from './charts/definitions';
 import { extraChartComponentDefinitions } from './charts/extra-definitions';
+import { tufteChartComponentDefinitions } from './charts/tufte-definitions';
+import { isDynamicPropValue } from './directives.js';
 
 const badgeDefinition = shadcnComponentDefinitions.Badge;
+const buttonDefinition = shadcnComponentDefinitions.Button;
 
 export const allComponentDefinitions = {
   ...shadcnComponentDefinitions,
@@ -23,8 +26,18 @@ export const allComponentDefinitions = {
       variant: z.enum(['default', 'secondary', 'destructive', 'outline', 'success', 'info', 'warning', 'error', 'danger']).nullable(),
     }),
   },
+  Button: {
+    ...buttonDefinition,
+    props: buttonDefinition.props.extend({
+      variant: z.enum(['primary', 'secondary', 'destructive', 'danger', 'outline', 'ghost', 'success']).nullable(),
+    }),
+    description:
+      'Clickable button. Bind on.press for handler. Choose variant by intent — at most ONE primary per view (the main call to action); use secondary for supporting actions; destructive (alias danger) for delete/remove/irreversible actions; outline/ghost for low-emphasis or toolbar actions; success to confirm a positive result. Omitting variant renders primary, so reserve the default for the single main action and set an explicit variant on every other button.',
+    example: { label: 'Save changes', variant: 'primary' },
+  },
   ...chartComponentDefinitions,
   ...extraChartComponentDefinitions,
+  ...tufteChartComponentDefinitions,
 };
 
 export const catalog = defineCatalog(schema as never, {
@@ -241,8 +254,9 @@ export function validateShadcnElementProps(spec: unknown): JsonRenderValidationR
     const definition = allComponentDefinitions[element.type as keyof typeof allComponentDefinitions];
     if (!definition || !hasSafeParse(definition.props)) continue;
 
+    const elementProps = asRecord(element.props) ?? {};
     const parsed = definition.props.safeParse(
-      normalizePropsForSchema(definition.props, asRecord(element.props) ?? {}),
+      normalizePropsForSchema(definition.props, elementProps),
     );
     if (parsed.success) continue;
 
@@ -250,6 +264,13 @@ export function validateShadcnElementProps(spec: unknown): JsonRenderValidationR
       const issuePath = Array.isArray(issue.path)
         ? issue.path.map((segment) => (typeof segment === 'symbol' ? String(segment) : segment))
         : [];
+      // A prop holding a `$`-keyed dynamic expression ($state/$item/$format/…)
+      // resolves to its real type at render time, so the static prop schema
+      // cannot type-check it — drop issues that point at such a prop.
+      const propKey = issuePath[0];
+      if (typeof propKey === 'string' && isDynamicPropValue(elementProps[propKey])) {
+        continue;
+      }
       issues.push({
         path: ['elements', elementKey, 'props', ...issuePath],
         message: issue.message ?? 'invalid value',