pmx-canvas 0.1.25 → 0.1.27

package/skills/tufte-viz/references/tufte-principles.md

@@ -0,0 +1,147 @@
+# Core Tufte Principles
+
+Reference for the fundamental principles from *The Visual Display of Quantitative Information*.
+
+## Table of Contents
+
+1. [Graphical Integrity](#graphical-integrity)
+2. [Data-Ink Ratio](#data-ink-ratio)
+3. [Chartjunk](#chartjunk)
+4. [Small Multiples](#small-multiples)
+5. [Data Density](#data-density)
+6. [The Tufte Test](#the-tufte-test)
+
+---
+
+## Graphical Integrity
+
+The representation of numbers on a graphic should be directly proportional to the numerical quantities represented.
+
+### Lie Factor
+
+```
+Lie Factor = (size of effect shown in graphic) / (size of effect in data)
+```
+
+- A lie factor of 1.0 means perfect honesty
+- Lie factors > 1.05 or < 0.95 distort perception
+- Common sources of distortion:
+  - Truncated baselines (bar charts not starting at zero)
+  - Area/volume encoding where length would suffice
+  - 3D perspective making nearer elements appear larger
+  - Non-linear axis scaling without clear labeling
+
+### Principles of Graphical Integrity
+
+1. Show data variation, not design variation
+2. Use clear, detailed, thorough labeling to defeat distortion
+3. In time-series displays, standardize monetary units (deflate for inflation)
+4. The number of information-carrying dimensions should not exceed the number of dimensions in the data
+5. Context: show the data in context - "compared to what?"
+
+---
+
+## Data-Ink Ratio
+
+The share of a graphic's ink devoted to non-redundant display of data-information.
+
+```
+Data-Ink Ratio = (data-ink) / (total ink used in graphic)
+```
+
+### Maximizing Data-Ink
+
+Within reason, the goal is to maximize the data-ink ratio:
+
+1. **Erase non-data-ink** - Remove elements that don't convey data (decorative borders, background fills, heavy axis boxes)
+2. **Erase redundant data-ink** - If the same information is encoded twice (e.g., both a label and a position), remove one
+3. **Revise and edit** - Iterate toward the simplest possible representation that retains all data meaning
+
+### Practical Applications
+
+- Replace heavy gridlines with light ones, or remove entirely if direct labels suffice
+- Use range-frame axes (axes that span only the data range, not arbitrary round numbers)
+- Remove chart borders/boxes
+- Use white gridlines on a light gray background (Tufte's "sparkline" aesthetic)
+- Let data points serve as their own tick marks where possible
+
+---
+
+## Chartjunk
+
+Non-data elements or redundant data elements that clutter a visualization without adding information.
+
+### Three Varieties
+
+1. **Unintentional optical art** - Moiré patterns from hatching, vibrating fills, and tight parallel lines that create visual interference
+2. **The grid** - Heavy, prominent grids that compete with or dominate the data
+3. **The duck** - Elaborate decorative structures built around the data (3D effects, pictorial embellishments, ornamental frames)
+
+### How to Eliminate
+
+- Default to no background fill, no border, no grid
+- Add gridlines only if the reader needs to extract precise values - and make them light/receding
+- Never use 3D unless the data is inherently three-dimensional
+- Remove legends when direct labeling is feasible
+- Remove decorative icons, clip art, or illustrations layered onto the data area
+
+---
+
+## Small Multiples
+
+A series of similar graphs or charts using the same scale and axes, allowing easy comparison across a varying condition.
+
+### When to Use
+
+- Comparing the same measure across many categories (regions, time periods, groups)
+- Showing change over time for multiple entities
+- Exploring multivariate data by faceting on one dimension
+- Whenever you're tempted to use color-coding to distinguish many overlapping series
+
+### Design Principles
+
+1. **Shared scales** - All panels must use identical axis ranges so position means the same thing everywhere
+2. **Consistent structure** - Same layout, same visual encoding in each panel
+3. **Minimal per-panel decoration** - Axis labels, ticks, and titles appear once (shared) rather than repeated in each panel
+4. **Clear ordering** - Arrange panels in a meaningful order (alphabetical, by outcome magnitude, by geography)
+5. **Reference elements** - Include a common reference (e.g., overall average) as a light/gray line in each panel for context
+
+### Density
+
+Small multiples can be packed tightly. Each panel should be large enough to reveal the data pattern but small enough that the eye can compare across many panels in a single view.
+
+---
+
+## Data Density
+
+The amount of data shown per unit area in a graphic.
+
+```
+Data Density = (number of entries in data matrix) / (area of data graphic)
+```
+
+### High-Density Displays
+
+- Most published graphics have far lower data density than they could achieve
+- Sparklines: intense, simple, word-sized graphics embedded in text or tables
+- Data tables with integrated graphical elements can achieve very high density
+- The human eye can resolve very fine differences - don't underestimate the reader
+
+### Shrink Principle
+
+Graphics can be shrunk far more than we usually think. A well-designed graphic retains meaning at small sizes because the data pattern (not the labels or decoration) carries the story.
+
+---
+
+## The Tufte Test
+
+A synthesis checklist for evaluating any completed visualization:
+
+1. **Is the lie factor close to 1.0?** - No distortions in area, length, or position
+2. **Is the data-ink ratio high?** - Could anything be erased without information loss?
+3. **Is there zero chartjunk?** - No decoration, no moiré, no unnecessary 3D
+4. **Does it answer "compared to what?"** - Context, baseline, or reference is present
+5. **Is labeling clear and integrated?** - Labels sit close to the data they describe, not in a distant legend
+6. **Is the data density appropriate?** - For the story being told, is enough data shown? Could a table or sparkline show more?
+7. **Would small multiples work better?** - If more than ~4 series overlap, consider faceting
+8. **Does every element earn its ink?** - One final pass: point to each mark and ask what it communicates

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);
     }
@@ -1102,6 +1110,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 +1810,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);
@@ -283,7 +288,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 {};
       };
@@ -464,6 +482,10 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
       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',