pmx-canvas 0.1.2 → 0.1.4

package/src/client/state/canvas-store.ts

@@ -1,5 +1,5 @@
 import { batch, computed, signal } from '@preact/signals';
-import type { CanvasEdge, CanvasLayout, CanvasNodeState, ConnectionStatus, ViewportState } from '../types';
+import { isExcalidrawNode, type CanvasEdge, type CanvasLayout, type CanvasNodeState, type ConnectionStatus, type ViewportState } from '../types';
 import { computeAutoArrange } from '../../shared/auto-arrange';
 import { pushCanvasUpdate, updateViewportFromClient } from './intent-bridge';
 
@@ -22,6 +22,11 @@ export const hasInitialServerLayout = signal<boolean>(false);
 // Only one node at a time can be in expanded/focus mode. When expanded, the
 // node renders as a full-viewport overlay for deep editing/reading.
 export const expandedNodeId = signal<string | null>(null);
+export const pendingExpandedNodeCloseId = signal<string | null>(null);
+let expandedCloseTimer: ReturnType<typeof setTimeout> | null = null;
+let pendingCloseInitialCheckpointAt: unknown = undefined;
+const EXCALIDRAW_CLOSE_POLL_MS = 100;
+const EXCALIDRAW_CLOSE_MAX_WAIT_MS = 2500;
 
 // ── Pending edge connection (for context menu "Connect from") ─
 export const pendingConnection = signal<{ from: string } | null>(null);
@@ -192,6 +197,14 @@ export function updateNode(id: string, patch: Partial<CanvasNodeState>): void {
   }
   next.set(id, { ...existing, ...patch });
   nodes.value = next;
+  const updatedAt = (next.get(id)?.data.appCheckpoint as { updatedAt?: unknown } | undefined)?.updatedAt;
+  if (
+    pendingExpandedNodeCloseId.value === id &&
+    updatedAt !== undefined &&
+    updatedAt !== pendingCloseInitialCheckpointAt
+  ) {
+    finishExpandedNodeClose(id);
+  }
 }
 
 export function updateNodeData(id: string, dataPatch: Record<string, unknown>): void {
@@ -585,11 +598,60 @@ export function walkGraph(direction: 'up' | 'down' | 'left' | 'right'): void {
 export function expandNode(id: string): void {
   const node = nodes.value.get(id);
   if (!node) return;
+  if (expandedCloseTimer !== null) {
+    clearTimeout(expandedCloseTimer);
+    expandedCloseTimer = null;
+  }
+  pendingExpandedNodeCloseId.value = null;
+  pendingCloseInitialCheckpointAt = undefined;
   bringToFront(id);
   expandedNodeId.value = id;
 }
 
+function finishExpandedNodeClose(nodeId: string): void {
+  if (expandedCloseTimer !== null) {
+    clearTimeout(expandedCloseTimer);
+    expandedCloseTimer = null;
+  }
+  if (expandedNodeId.value === nodeId) expandedNodeId.value = null;
+  if (pendingExpandedNodeCloseId.value === nodeId) pendingExpandedNodeCloseId.value = null;
+  pendingCloseInitialCheckpointAt = undefined;
+}
+
 export function collapseExpandedNode(): void {
+  const nodeId = expandedNodeId.value;
+  const node = nodeId ? nodes.value.get(nodeId) : undefined;
+  if (nodeId && node && isExcalidrawNode(node)) {
+    const closingNodeId = nodeId;
+    const startedAt = Date.now();
+    pendingExpandedNodeCloseId.value = closingNodeId;
+    pendingCloseInitialCheckpointAt = (node.data.appCheckpoint as { updatedAt?: unknown } | undefined)?.updatedAt;
+    if (expandedCloseTimer !== null) clearTimeout(expandedCloseTimer);
+    const pollForSave = () => {
+      const latestNode = nodes.value.get(closingNodeId);
+      const latestCheckpointAt = (latestNode?.data.appCheckpoint as { updatedAt?: unknown } | undefined)?.updatedAt;
+      if (
+        latestCheckpointAt !== undefined &&
+        latestCheckpointAt !== pendingCloseInitialCheckpointAt
+      ) {
+        finishExpandedNodeClose(closingNodeId);
+        return;
+      }
+      if (Date.now() - startedAt >= EXCALIDRAW_CLOSE_MAX_WAIT_MS) {
+        finishExpandedNodeClose(closingNodeId);
+        return;
+      }
+      expandedCloseTimer = setTimeout(pollForSave, EXCALIDRAW_CLOSE_POLL_MS);
+    };
+    expandedCloseTimer = setTimeout(pollForSave, EXCALIDRAW_CLOSE_POLL_MS);
+    return;
+  }
+  if (expandedCloseTimer !== null) {
+    clearTimeout(expandedCloseTimer);
+    expandedCloseTimer = null;
+  }
+  pendingExpandedNodeCloseId.value = null;
+  pendingCloseInitialCheckpointAt = undefined;
   expandedNodeId.value = null;
 }
 

package/src/client/state/sse-bridge.ts

@@ -6,6 +6,7 @@ import {
   addEdge,
   addNode,
   applyServerCanvasLayout,
+  bringToFront,
   cancelViewportAnimation,
   canvasTheme,
   connectionStatus,
@@ -165,7 +166,8 @@ function ensureMcpAppNode(data: Record<string, unknown>): void {
 
 function ensureExtAppNode(data: Record<string, unknown>): void {
   const toolCallId = data.toolCallId as string;
-  const id = `ext-app-${toolCallId}`;
+  const eventNodeId = typeof data.nodeId === 'string' && data.nodeId.length > 0 ? data.nodeId : null;
+  const id = eventNodeId ?? (toolCallId.startsWith('ext-app-') ? toolCallId : `ext-app-${toolCallId}`);
   const existing = nodes.value.get(id);
   if (existing) {
     updateNodeData(id, data);
@@ -231,8 +233,10 @@ function ensureExtAppNode(data: Record<string, unknown>): void {
 }
 
 function findExtAppNodeId(toolCallId: string): string | null {
-  const directId = `ext-app-${toolCallId}`;
+  const directId = toolCallId.startsWith('ext-app-') ? toolCallId : `ext-app-${toolCallId}`;
   if (nodes.value.has(directId)) return directId;
+  const legacyDirectId = `ext-app-${toolCallId}`;
+  if (legacyDirectId !== directId && nodes.value.has(legacyDirectId)) return legacyDirectId;
   for (const [nodeId, node] of nodes.value.entries()) {
     if (
       node.type === 'mcp-app' &&
@@ -245,6 +249,13 @@ function findExtAppNodeId(toolCallId: string): string | null {
   return null;
 }
 
+function findExtAppEventNodeId(data: Record<string, unknown>): string | null {
+  const eventNodeId = typeof data.nodeId === 'string' && data.nodeId.length > 0 ? data.nodeId : null;
+  if (eventNodeId && nodes.value.has(eventNodeId)) return eventNodeId;
+  if (typeof data.toolCallId !== 'string' || !data.toolCallId) return null;
+  return findExtAppNodeId(data.toolCallId);
+}
+
 function findOnlyPendingExtAppNodeId(serverName: unknown, toolName: unknown): string | null {
   if (typeof serverName !== 'string' || !serverName) return null;
   if (typeof toolName !== 'string' || !toolName) return null;
@@ -541,7 +552,7 @@ function handleExtAppOpen(data: Record<string, unknown>): void {
 function handleExtAppUpdate(data: Record<string, unknown>): void {
   if (typeof data.toolCallId !== 'string' || !data.toolCallId) return;
   const id =
-    findExtAppNodeId(data.toolCallId) ?? findOnlyPendingExtAppNodeId(data.serverName, data.toolName);
+    findExtAppEventNodeId(data) ?? findOnlyPendingExtAppNodeId(data.serverName, data.toolName);
   if (!id) return;
   if (nodes.value.has(id)) {
     updateNodeData(id, { html: data.html });
@@ -551,7 +562,7 @@ function handleExtAppUpdate(data: Record<string, unknown>): void {
 function handleExtAppResult(data: Record<string, unknown>): void {
   if (typeof data.toolCallId !== 'string' || !data.toolCallId) return;
   const id =
-    findExtAppNodeId(data.toolCallId) ?? findOnlyPendingExtAppNodeId(data.serverName, data.toolName);
+    findExtAppEventNodeId(data) ?? findOnlyPendingExtAppNodeId(data.serverName, data.toolName);
   if (!id) return;
   if (nodes.value.has(id)) {
     if (data.success === false) {
@@ -827,6 +838,10 @@ function reconnectDelayMs(attempt: number): number {
 function handleCanvasFocusNode(data: Record<string, unknown>): void {
   const nodeId = data.nodeId as string;
   if (nodeId && nodes.value.has(nodeId)) {
+    if (data.noPan === true) {
+      bringToFront(nodeId);
+      return;
+    }
     focusNode(nodeId);
   }
 }

package/src/client/types.ts

@@ -74,6 +74,18 @@ export const EXPANDABLE_TYPES = new Set<CanvasNodeState['type']>([
   'image',
 ]);
 
+export const EXCALIDRAW_SERVER_NAME = 'Excalidraw';
+export const EXCALIDRAW_CREATE_VIEW_TOOL = 'create_view';
+
+export function isExcalidrawNode(node: CanvasNodeState): boolean {
+  return (
+    node.type === 'mcp-app' &&
+    node.data.mode === 'ext-app' &&
+    node.data.serverName === EXCALIDRAW_SERVER_NAME &&
+    node.data.toolName === EXCALIDRAW_CREATE_VIEW_TOOL
+  );
+}
+
 export interface CanvasLayout {
   viewport: ViewportState;
   nodes: CanvasNodeState[];

package/src/json-render/charts/components.tsx

@@ -103,15 +103,17 @@ export const tooltipStyle = {
 export function CartesianChart({
   props,
   children,
+  className,
 }: {
   props: CartesianChartProps;
   children: (data: Record<string, unknown>[]) => ReactNode;
+  className?: string;
 }) {
   const chartData = processChartData(props.data ?? [], props.xKey, props.yKey, props.aggregate);
   const h = props.height ?? 300;
 
   return (
-    <div className="pmx-chart">
+    <div className={`pmx-chart${className ? ` ${className}` : ''}`}>
       {props.title && <div className="pmx-chart__title">{props.title}</div>}
       <ResponsiveContainer width="100%" height={h}>
         {children(chartData)}
@@ -123,7 +125,7 @@ export function CartesianChart({
 function ChartLineChart({ props }: BaseComponentProps<CartesianChartProps>) {
   const stroke = props.color ?? CHART_COLORS[0];
   return (
-    <CartesianChart props={props}>
+    <CartesianChart props={props} className="pmx-chart--line">
       {(data) => (
         <RechartsLineChart data={data}>
           <CartesianGrid strokeDasharray="3 3" stroke="var(--border, #e5e5e5)" />
@@ -147,7 +149,7 @@ function ChartLineChart({ props }: BaseComponentProps<CartesianChartProps>) {
 function ChartBarChart({ props }: BaseComponentProps<CartesianChartProps>) {
   const fill = props.color ?? CHART_COLORS[0];
   return (
-    <CartesianChart props={props}>
+    <CartesianChart props={props} className="pmx-chart--bar">
       {(data) => (
         <RechartsBarChart data={data}>
           <CartesianGrid strokeDasharray="3 3" stroke="var(--border, #e5e5e5)" />
@@ -166,7 +168,7 @@ function ChartPieChart({ props }: BaseComponentProps<PieChartProps>) {
   const h = props.height ?? 300;
 
   return (
-    <div className="pmx-chart">
+    <div className="pmx-chart pmx-chart--pie">
       {props.title && <div className="pmx-chart__title">{props.title}</div>}
       <ResponsiveContainer width="100%" height={h}>
         <RechartsPieChart>

package/src/json-render/charts/extra-components.tsx

@@ -45,7 +45,7 @@ function ChartAreaChart({ props }: BaseComponentProps<AreaChartProps>) {
   const stroke = props.color ?? CHART_COLORS[0];
   const gradientId = `pmx-area-${props.yKey ?? 'value'}`;
   return (
-    <CartesianChart props={props}>
+    <CartesianChart props={props} className="pmx-chart--area">
       {(data) => (
         <RechartsAreaChart data={data}>
           <defs>
@@ -88,7 +88,7 @@ function ChartScatterChart({ props }: BaseComponentProps<ScatterChartProps>) {
   const h = props.height ?? 300;
 
   return (
-    <div className="pmx-chart">
+    <div className="pmx-chart pmx-chart--scatter">
       {props.title && <div className="pmx-chart__title">{props.title}</div>}
       <ResponsiveContainer width="100%" height={h}>
         <RechartsScatterChart>
@@ -118,7 +118,7 @@ function ChartRadarChart({ props }: BaseComponentProps<RadarChartProps>) {
   const h = props.height ?? 320;
 
   return (
-    <div className="pmx-chart">
+    <div className="pmx-chart pmx-chart--radar">
       {props.title && <div className="pmx-chart__title">{props.title}</div>}
       <ResponsiveContainer width="100%" height={h}>
         <RechartsRadarChart data={data} outerRadius="75%">
@@ -163,7 +163,7 @@ function ChartStackedBarChart({ props }: BaseComponentProps<StackedBarChartProps
   const h = props.height ?? 300;
 
   return (
-    <div className="pmx-chart">
+    <div className="pmx-chart pmx-chart--stacked-bar">
       {props.title && <div className="pmx-chart__title">{props.title}</div>}
       <ResponsiveContainer width="100%" height={h}>
         <RechartsBarChart data={chartData}>
@@ -234,7 +234,7 @@ function ChartComposedChart({ props }: BaseComponentProps<ComposedChartProps>) {
   const h = props.height ?? 300;
 
   return (
-    <div className="pmx-chart">
+    <div className="pmx-chart pmx-chart--composed">
       {props.title && <div className="pmx-chart__title">{props.title}</div>}
       <ResponsiveContainer width="100%" height={h}>
         <RechartsComposedChart data={data}>

package/src/json-render/renderer/index.css

@@ -147,9 +147,23 @@ button {
 
 .pmx-chart {
   width: 100%;
+  min-width: 280px;
+  overflow-x: auto;
   padding: 0.5rem 0;
 }
 
+.pmx-chart--line,
+.pmx-chart--area,
+.pmx-chart--scatter,
+.pmx-chart--stacked-bar,
+.pmx-chart--composed {
+  min-width: 320px;
+}
+
+.pmx-chart--radar {
+  min-width: 360px;
+}
+
 .pmx-chart__title {
   font-size: 0.875rem;
   font-weight: 600;

package/src/mcp/server.ts

@@ -279,10 +279,18 @@ export async function startMcpServer(): Promise<void> {
       data: z.array(z.record(z.string(), z.unknown())).optional().describe('Graph dataset when type="graph"'),
       xKey: z.string().optional().describe('X-axis key for line/bar graphs'),
       yKey: z.string().optional().describe('Y-axis key for line/bar graphs'),
+      zKey: z.string().optional().describe('Optional bubble-size key for scatter charts'),
       nameKey: z.string().optional().describe('Slice name key for pie graphs'),
       valueKey: z.string().optional().describe('Slice value key for pie graphs'),
+      axisKey: z.string().optional().describe('Category key for radar charts'),
+      metrics: z.array(z.string()).optional().describe('Series keys to plot as radar polygons'),
+      series: z.array(z.string()).optional().describe('Series keys for stacked-bar segments'),
+      barKey: z.string().optional().describe('Bar series key for composed charts'),
+      lineKey: z.string().optional().describe('Line series key for composed charts'),
       aggregate: z.enum(['sum', 'count', 'avg']).optional().describe('Optional aggregation for repeated keys'),
       color: z.string().optional().describe('Optional graph color'),
+      barColor: z.string().optional().describe('Optional bar color for composed charts'),
+      lineColor: z.string().optional().describe('Optional line color for composed charts'),
       height: z.number().optional().describe('Optional graph content height'),
     },
     async (input) => {
@@ -300,10 +308,18 @@ export async function startMcpServer(): Promise<void> {
                 data: input.data ?? [],
                 ...(typeof input.xKey === 'string' ? { xKey: input.xKey } : {}),
                 ...(typeof input.yKey === 'string' ? { yKey: input.yKey } : {}),
+                ...(typeof input.zKey === 'string' ? { zKey: input.zKey } : {}),
                 ...(typeof input.nameKey === 'string' ? { nameKey: input.nameKey } : {}),
                 ...(typeof input.valueKey === 'string' ? { valueKey: input.valueKey } : {}),
+                ...(typeof input.axisKey === 'string' ? { axisKey: input.axisKey } : {}),
+                ...(Array.isArray(input.metrics) ? { metrics: input.metrics } : {}),
+                ...(Array.isArray(input.series) ? { series: input.series } : {}),
+                ...(typeof input.barKey === 'string' ? { barKey: input.barKey } : {}),
+                ...(typeof input.lineKey === 'string' ? { lineKey: input.lineKey } : {}),
                 ...(typeof input.aggregate === 'string' ? { aggregate: input.aggregate } : {}),
                 ...(typeof input.color === 'string' ? { color: input.color } : {}),
+                ...(typeof input.barColor === 'string' ? { barColor: input.barColor } : {}),
+                ...(typeof input.lineColor === 'string' ? { lineColor: input.lineColor } : {}),
                 ...(typeof input.height === 'number' ? { height: input.height } : {}),
               },
             });
@@ -348,6 +364,7 @@ export async function startMcpServer(): Promise<void> {
       mainTsx: z.string().optional().describe('Optional contents for src/main.tsx'),
       indexHtml: z.string().optional().describe('Optional contents for index.html'),
       files: z.record(z.string(), z.string()).optional().describe('Optional map of additional project-relative file paths to file contents'),
+      deps: z.array(z.string()).optional().describe('Optional npm dependencies to install before bundling (e.g. ["recharts", "framer-motion@^11"]). Validated against npm-name format; flags and shell metacharacters are rejected.'),
       projectPath: z.string().optional().describe('Optional workspace-relative reusable project path. Defaults to .pmx-canvas/artifacts/.web-artifacts/<slug>'),
       outputPath: z.string().optional().describe('Optional workspace-relative HTML output path. Defaults to .pmx-canvas/artifacts/<slug>.html'),
       openInCanvas: z.boolean().optional().describe('Open the generated artifact in canvas after build (default true)'),
@@ -366,6 +383,7 @@ export async function startMcpServer(): Promise<void> {
           ...(typeof input.mainTsx === 'string' ? { mainTsx: input.mainTsx } : {}),
           ...(typeof input.indexHtml === 'string' ? { indexHtml: input.indexHtml } : {}),
           ...(input.files ? { files: input.files } : {}),
+          ...(Array.isArray(input.deps) ? { deps: input.deps } : {}),
           ...(typeof input.projectPath === 'string'
             ? { projectPath: safeWorkspacePath(input.projectPath) }
             : {}),
@@ -672,13 +690,34 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_focus_node ──────────────────────────────────────────
   server.tool(
     'canvas_focus_node',
-    'Pan the viewport to center on a specific node.',
-    { id: z.string().describe('Node ID to focus on') },
-    async ({ id }) => {
+    'Bring a node into focus. By default the viewport pans so the node is centered. Pass noPan=true to raise/select the node without moving the human\'s camera (useful when reacting to background events without disrupting the human\'s current view).',
+    {
+      id: z.string().describe('Node ID to focus on'),
+      noPan: z
+        .boolean()
+        .optional()
+        .describe('If true, raise/select the node without panning the viewport. Default false.'),
+    },
+    async ({ id, noPan }) => {
       const c = await ensureCanvas();
-      c.focusNode(id);
+      const result = c.focusNode(id, { ...(noPan === true ? { noPan: true } : {}) });
+      if (!result) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ ok: false, error: `Node "${id}" not found.` }),
+            },
+          ],
+        };
+      }
       return {
-        content: [{ type: 'text', text: JSON.stringify({ ok: true, focused: id }) }],
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ ok: true, focused: result.focused, panned: result.panned }),
+          },
+        ],
       };
     },
   );

package/src/server/canvas-operations.ts

@@ -36,6 +36,7 @@ import {
   getWebpageFetchErrorDetails,
   normalizeWebpageUrl,
 } from './webpage-node.js';
+import { buildExcalidrawRestoreCheckpointToolInput, ensureExcalidrawCheckpointId, isExcalidrawCreateView } from './diagram-presets.js';
 
 export type CanvasArrangeMode = 'grid' | 'column' | 'flow';
 export type CanvasPinMode = 'set' | 'add' | 'remove';
@@ -82,6 +83,29 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function getStoredExcalidrawCheckpointId(node: CanvasNodeState): string | null {
+  const appCheckpoint = isRecord(node.data.appCheckpoint) ? node.data.appCheckpoint : null;
+  const checkpointId = appCheckpoint?.id;
+  return typeof checkpointId === 'string' && checkpointId.trim().length > 0 ? checkpointId.trim() : null;
+}
+
+function resolveExtAppRehydratedToolInput(
+  node: CanvasNodeState,
+  openedToolInput: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!isExcalidrawCreateView(node.data.serverName, node.data.toolName)) return openedToolInput;
+  const checkpointId = getStoredExcalidrawCheckpointId(node);
+  if (!checkpointId) return openedToolInput;
+  const appCheckpoint = isRecord(node.data.appCheckpoint) ? node.data.appCheckpoint : null;
+  return {
+    ...openedToolInput,
+    elements: buildExcalidrawRestoreCheckpointToolInput(
+      checkpointId,
+      typeof appCheckpoint?.data === 'string' ? appCheckpoint.data : undefined,
+    ),
+  };
+}
+
 function isExtAppNode(node: CanvasNodeState | undefined): node is CanvasNodeState {
   return node?.type === 'mcp-app' && node.data.mode === 'ext-app';
 }
@@ -280,13 +304,18 @@ export async function syncCanvasRuntimeBackends(
           ? { serverName: current.data.serverName.trim() }
           : {}),
       });
+      const toolInput = resolveExtAppRehydratedToolInput(current, opened.toolInput);
+      const storedCheckpointId = getStoredExcalidrawCheckpointId(current);
+      const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
+        ? ensureExcalidrawCheckpointId(opened.toolResult, nodeId, storedCheckpointId)
+        : opened.toolResult;
 
       canvasState.withSuppressedRecording(() => {
         setExtAppRuntimeState(nodeId, {
           appSessionId: opened.sessionId,
           html: opened.html,
-          toolInput: opened.toolInput,
-          toolResult: opened.toolResult,
+          toolInput,
+          toolResult,
           resourceUri: opened.resourceUri,
           toolDefinition: opened.tool,
           resourceMeta: opened.resourceMeta,
@@ -704,7 +733,7 @@ function collectArrangeExcludedNodeIds(nodes: CanvasNodeState[]): Set<string> {
   const excluded = new Set<string>();
   for (const node of nodes) {
     const parentGroup = typeof node.data.parentGroup === 'string' ? node.data.parentGroup : null;
-    if (isArrangeLocked(node) || (parentGroup && excludedGroupIds.has(parentGroup))) {
+    if (parentGroup || isArrangeLocked(node)) {
       excluded.add(node.id);
     }
   }
@@ -747,12 +776,13 @@ export function arrangeCanvasNodes(layout: CanvasArrangeMode): { arranged: numbe
       return;
     }
 
-    const cols = Math.max(1, Math.floor(1440 / (360 + gap)));
+    const maxNodeWidth = movableNodes.reduce((max, node) => Math.max(max, node.size.width), 360);
+    const cols = Math.max(1, Math.floor(1440 / (maxNodeWidth + gap)));
     let col = 0;
     let rowY = 80;
     let rowMaxHeight = 0;
     for (const node of movableNodes) {
-      const x = 40 + col * (360 + gap);
+      const x = 40 + col * (maxNodeWidth + gap);
       canvasState.updateNode(node.id, { position: { x, y: rowY } });
       rowMaxHeight = Math.max(rowMaxHeight, node.size.height);
       col++;
@@ -1180,12 +1210,20 @@ export async function executeCanvasBatch(
             ...(typeof args.title === 'string' ? { title: args.title } : {}),
             ...(typeof args.xKey === 'string' ? { xKey: args.xKey } : {}),
             ...(typeof args.yKey === 'string' ? { yKey: args.yKey } : {}),
+            ...(typeof args.zKey === 'string' ? { zKey: args.zKey } : {}),
             ...(typeof args.nameKey === 'string' ? { nameKey: args.nameKey } : {}),
             ...(typeof args.valueKey === 'string' ? { valueKey: args.valueKey } : {}),
+            ...(typeof args.axisKey === 'string' ? { axisKey: args.axisKey } : {}),
+            ...(Array.isArray(args.metrics) ? { metrics: args.metrics.filter((m): m is string => typeof m === 'string') } : {}),
+            ...(Array.isArray(args.series) ? { series: args.series.filter((s): s is string => typeof s === 'string') } : {}),
+            ...(typeof args.barKey === 'string' ? { barKey: args.barKey } : {}),
+            ...(typeof args.lineKey === 'string' ? { lineKey: args.lineKey } : {}),
             ...(args.aggregate === 'sum' || args.aggregate === 'count' || args.aggregate === 'avg'
               ? { aggregate: args.aggregate }
               : {}),
             ...(typeof args.color === 'string' ? { color: args.color } : {}),
+            ...(typeof args.barColor === 'string' ? { barColor: args.barColor } : {}),
+            ...(typeof args.lineColor === 'string' ? { lineColor: args.lineColor } : {}),
             ...(typeof args.height === 'number' ? { height: args.height } : {}),
             ...(typeof args.x === 'number' ? { x: args.x } : {}),
             ...(typeof args.y === 'number' ? { y: args.y } : {}),

package/src/server/canvas-schema.ts

@@ -282,26 +282,27 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
         type: '"line" | "bar" | "pie" | "area" | "scatter" | "radar" | "stacked-bar" | "composed"',
         required: true,
         description: 'Chart type. Aliases like "stack" and "combo" are normalized server-side.',
+        aliases: ['graph-type'],
       },
-      { name: 'data', type: 'Record<string, unknown>[]', required: true, description: 'Chart dataset.' },
+      { name: 'data', type: 'Record<string, unknown>[]', required: true, description: 'Chart dataset. The CLI also accepts piped JSON via --stdin.', aliases: ['data-json', 'data-file'] },
       { name: 'title', type: 'string', required: false, description: 'Optional graph title.' },
-      { name: 'xKey', type: 'string', required: false, description: 'X-axis/category key for line, bar, area, scatter, stacked-bar, and composed charts.' },
-      { name: 'yKey', type: 'string', required: false, description: 'Y-axis value key for line, bar, area, and scatter charts. Also used as a fallback bar key for composed charts.' },
-      { name: 'zKey', type: 'string', required: false, description: 'Optional bubble-size key for scatter charts.' },
-      { name: 'nameKey', type: 'string', required: false, description: 'Slice name key for pie graphs.' },
-      { name: 'valueKey', type: 'string', required: false, description: 'Slice value key for pie graphs.' },
-      { name: 'axisKey', type: 'string', required: false, description: 'Category key for radar charts.' },
+      { name: 'xKey', type: 'string', required: false, description: 'X-axis/category key for line, bar, area, scatter, stacked-bar, and composed charts.', aliases: ['x-key'] },
+      { name: 'yKey', type: 'string', required: false, description: 'Y-axis value key for line, bar, area, and scatter charts. Also used as a fallback bar key for composed charts.', aliases: ['y-key'] },
+      { name: 'zKey', type: 'string', required: false, description: 'Optional bubble-size key for scatter charts.', aliases: ['z-key'] },
+      { name: 'nameKey', type: 'string', required: false, description: 'Slice name key for pie graphs.', aliases: ['name-key'] },
+      { name: 'valueKey', type: 'string', required: false, description: 'Slice value key for pie graphs.', aliases: ['value-key'] },
+      { name: 'axisKey', type: 'string', required: false, description: 'Category key for radar charts.', aliases: ['axis-key'] },
       { name: 'metrics', type: 'string[]', required: false, description: 'Series keys to plot as radar polygons. Defaults to non-axis numeric columns.' },
       { name: 'series', type: 'string[]', required: false, description: 'Series keys for stacked-bar segments. Defaults to non-x numeric columns.' },
-      { name: 'barKey', type: 'string', required: false, description: 'Bar series key for composed charts.' },
-      { name: 'lineKey', type: 'string', required: false, description: 'Line series key for composed charts.' },
+      { name: 'barKey', type: 'string', required: false, description: 'Bar series key for composed charts.', aliases: ['bar-key'] },
+      { name: 'lineKey', type: 'string', required: false, description: 'Line series key for composed charts.', aliases: ['line-key'] },
       { name: 'aggregate', type: '"sum" | "count" | "avg"', required: false, description: 'Optional aggregation for repeated x-axis values in line, bar, area, and stacked-bar charts.' },
       { name: 'color', type: 'string', required: false, description: 'Optional series color for line, bar, area, and scatter charts.' },
-      { name: 'barColor', type: 'string', required: false, description: 'Optional bar color for composed charts.' },
-      { name: 'lineColor', type: 'string', required: false, description: 'Optional line color for composed charts.' },
-      { name: 'height', type: 'number', required: false, description: 'Optional chart content height.' },
+      { name: 'barColor', type: 'string', required: false, description: 'Optional bar color for composed charts.', aliases: ['bar-color'] },
+      { name: 'lineColor', type: 'string', required: false, description: 'Optional line color for composed charts.', aliases: ['line-color'] },
+      { name: 'height', type: 'number', required: false, description: 'Optional chart content height.', aliases: ['chart-height'] },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },
-      { name: 'nodeHeight', type: 'number', required: false, description: 'Optional node height.' },
+      { name: 'nodeHeight', type: 'number', required: false, description: 'Optional node height (canvas frame). Distinct from `height`, which sets only the chart content height inside the node.', aliases: ['node-height'] },
     ],
     example: {
       title: 'Deploy Trend',
@@ -326,7 +327,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/web-artifact',
     fields: [
       { name: 'title', type: 'string', required: true, description: 'Artifact title used for default paths.' },
-      { name: 'appTsx', type: 'string', required: true, description: 'Contents for src/App.tsx.', aliases: ['stdin', 'app-file', 'app-tsx'] },
+      { name: 'appTsx', type: 'string', required: true, description: 'Contents for src/App.tsx. The CLI also accepts piped contents via --stdin.', aliases: ['app-file', 'app-tsx'] },
       { name: 'indexCss', type: 'string', required: false, description: 'Optional src/index.css contents.', aliases: ['index-css-file', 'index-css'] },
       { name: 'mainTsx', type: 'string', required: false, description: 'Optional src/main.tsx contents.', aliases: ['main-file', 'main-tsx'] },
       { name: 'indexHtml', type: 'string', required: false, description: 'Optional index.html contents.', aliases: ['index-html-file', 'index-html'] },
@@ -334,6 +335,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       { name: 'outputPath', type: 'string', required: false, description: 'Optional output HTML path.' },
       { name: 'openInCanvas', type: 'boolean', required: false, description: 'Open the built artifact on the canvas (default true).' },
       { name: 'includeLogs', type: 'boolean', required: false, description: 'Include raw build stdout/stderr in the response (default false).' },
+      { name: 'deps', type: 'string[]', required: false, description: 'Optional npm dependencies to add before bundling, e.g. recharts.', aliases: ['deps'] },
     ],
     example: {
       title: 'Dashboard Artifact',

package/src/server/canvas-serialization.ts

@@ -6,6 +6,7 @@ import {
 } from './canvas-provenance.js';
 
 export interface SerializedCanvasNode extends CanvasNodeState {
+  kind: string;
   title: string | null;
   content: string | null;
   path: string | null;
@@ -26,6 +27,21 @@ function pickProvenance(value: unknown): CanvasNodeProvenance | null {
   return value as CanvasNodeProvenance;
 }
 
+function getCanvasNodeKind(node: CanvasNodeState, data: Record<string, unknown>): string {
+  if (node.type !== 'mcp-app') return node.type;
+  // Authoritative discriminator added in v0.1.4. New web-artifacts always set
+  // it; matching here first means a future URL-only artifact (no `data.path`)
+  // still classifies correctly without falling through to the legacy heuristic.
+  if (data.viewerType === 'web-artifact') return 'web-artifact';
+  if (data.mode === 'ext-app') return 'external-app';
+  // Transitional fallback for canvas state.json files persisted before v0.1.4
+  // introduced `viewerType`. Web-artifacts written by older versions always
+  // stored a `path` to the bundled HTML file, so this heuristic is safe for
+  // existing data. Remove in v0.2.x once a one-shot migration runs at boot.
+  if (data.hostMode === 'hosted' && typeof data.path === 'string') return 'web-artifact';
+  return 'mcp-app';
+}
+
 export function getCanvasNodeTitle(node: CanvasNodeState): string | null {
   return pickString(node.data.title)
     ?? (node.type === 'webpage' ? pickString(node.data.pageTitle) : null)
@@ -47,6 +63,7 @@ export function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode
   return {
     ...node,
     data,
+    kind: getCanvasNodeKind(node, data),
     title: getCanvasNodeTitle(node),
     content: getCanvasNodeContent(node),
     path: pickString(data.path),
@@ -77,7 +94,8 @@ export function buildCanvasSummary(): CanvasSummary {
 
   const typeCounts: Record<string, number> = {};
   for (const n of layout.nodes) {
-    typeCounts[n.type] = (typeCounts[n.type] ?? 0) + 1;
+    const kind = getCanvasNodeKind(n, normalizeCanvasNodeData(n.type, n.data));
+    typeCounts[kind] = (typeCounts[kind] ?? 0) + 1;
   }
 
   const pinnedTitles = layout.nodes