pmx-canvas 0.1.3 → 0.1.5

package/dist/types/json-render/charts/components.d.ts

@@ -39,9 +39,10 @@ export declare const tooltipStyle: {
     fontSize: number;
 };
 /** Shared wrapper for cartesian charts (Line + Bar). */
-export declare function CartesianChart({ props, children, }: {
+export declare function CartesianChart({ props, children, className, }: {
     props: CartesianChartProps;
     children: (data: Record<string, unknown>[]) => ReactNode;
+    className?: string;
 }): import("react/jsx-runtime").JSX.Element;
 declare function ChartLineChart({ props }: BaseComponentProps<CartesianChartProps>): import("react/jsx-runtime").JSX.Element;
 declare function ChartBarChart({ props }: BaseComponentProps<CartesianChartProps>): import("react/jsx-runtime").JSX.Element;

package/dist/types/server/canvas-serialization.d.ts

@@ -1,6 +1,7 @@
 import type { CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
 import { type CanvasNodeProvenance } from './canvas-provenance.js';
 export interface SerializedCanvasNode extends CanvasNodeState {
+    kind: string;
     title: string | null;
     content: string | null;
     path: string | null;

package/dist/types/server/ext-app-lookup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolve the canvas node ID for a given ext-app `toolCallId`.
+ *
+ * v0.1.4 fixed a long-standing `ext-app-ext-app-…` double-prefix bug where
+ * both `nodeId` and `toolCallId` carried the `ext-app-` prefix. This helper
+ * encodes the lookup contract so it doesn't drift between the
+ * `PmxCanvas` SDK class and the HTTP server.
+ *
+ * Resolution order:
+ *   1. The direct prefixed form (`ext-app-<toolCallId>` if not already
+ *      prefixed, otherwise `toolCallId` as-is).
+ *   2. The legacy `ext-app-ext-app-…` form, for canvases persisted before
+ *      v0.1.4 and still on disk. Remove this fallback in v0.2.x.
+ *   3. A scan of the layout for any `mcp-app` ext-app node carrying that
+ *      `toolCallId` in its data.
+ */
+import type { CanvasNodeState } from './canvas-state.js';
+export interface ExtAppLookupSource {
+    getNode(id: string): CanvasNodeState | undefined;
+    listNodes(): readonly CanvasNodeState[];
+}
+export declare function findCanvasExtAppNodeId(toolCallId: string, source: ExtAppLookupSource): string | null;

package/dist/types/server/image-source.d.ts

@@ -0,0 +1,3 @@
+export declare function validateLocalImageFile(path: string): {
+    mimeType: string;
+};

package/dist/types/server/index.d.ts

@@ -195,6 +195,7 @@ export declare class PmxCanvas extends EventEmitter {
         height?: number;
     }): Promise<{
         ok: true;
+        id?: string;
         nodeId: string | null;
         toolCallId: string;
         sessionId: string;
@@ -202,6 +203,7 @@ export declare class PmxCanvas extends EventEmitter {
     }>;
     addDiagram(input: DiagramPresetOpenInput): Promise<{
         ok: true;
+        id?: string;
         nodeId: string | null;
         toolCallId: string;
         sessionId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -84,8 +84,8 @@ pmx-canvas layout                          # Full canvas state
 pmx-canvas status                          # Quick summary
 pmx-canvas node add --type markdown --title "Plan"
 pmx-canvas node add --type webpage --url https://example.com/docs
-pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx
 pmx-canvas node add --type graph --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y
+pmx-canvas node add --type graph --graphType bar --data '[{"x":"a","y":1}]' --xKey x --yKey y
 pmx-canvas external-app add --kind excalidraw --title "Diagram"
 pmx-canvas node add --help --type webpage --json
 pmx-canvas node schema --type json-render --component Table --summary
@@ -97,6 +97,8 @@ pmx-canvas arrange --layout flow
 pmx-canvas focus <node-id> --no-pan             # Select/raise without moving the user's viewport
 pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
 pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
+pmx-canvas node list --type web-artifact --summary
+pmx-canvas node list --type external-app --summary
 pmx-canvas pin --list
 pmx-canvas snapshot save --name "before-refactor"
 pmx-canvas code-graph
@@ -107,6 +109,7 @@ pmx-canvas spatial
 
 - `node add|list|get|update|remove` — manage nodes
 - `node schema` — inspect running-server create schemas and canonical examples, with `--summary`, `--field`, and `--component` filters
+- Graph CLI fields accept both kebab-case flags and camelCase schema names, e.g. `--graph-type`/`--graphType`, `--x-key`/`--xKey`, and `--bar-color`/`--barColor`.
 - `edge add|list|remove` — manage edges
 - Search-based edge selectors must be specific enough to resolve exactly one node. Queries like
   `"DVT O3"` can be ambiguous; prefer the full visible title such as `"DVT O3 — GitOps"`.
@@ -119,6 +122,8 @@ pmx-canvas spatial
 - `group create|add|remove` — manage groups
 - `clear --yes` — destructive clear with explicit confirmation
 - `validate spec` — validate json-render specs and graph payloads without creating nodes
+- `web-artifact build` — build bundled React/Tailwind HTML artifacts; use `--deps` for extra packages and `--include-logs` only when raw logs are useful
+- `external-app add --kind excalidraw` — create the hosted Excalidraw preset; response includes `id` and `nodeId` aliases for the same canvas node
 - `serve status|stop` — inspect and stop daemonized servers started with `serve --daemon`
 - `code-graph`, `spatial` — analysis commands
 
@@ -128,10 +133,9 @@ Current caveat:
   through search later in the session. When you plan to curate an app-heavy comparison area,
   capture node IDs immediately after creation and verify membership with `node get --summary`,
   `layout --summary`, or the browser selection state instead of relying on search alone.
-- Some `mcp-app` creation flows are still awkward to address immediately after creation. If a
-  diagram/app flow gives you a session-oriented result first, resolve the final canvas node from
-  live layout or `node list --type mcp-app` before you try to group it, wire edges to it, or
-  revisit it later.
+- App-like nodes persist as `type: "mcp-app"` internally but serialized results include `kind`:
+  `web-artifact`, `external-app`, or `mcp-app`. Prefer `node list --type web-artifact` or
+  `node list --type external-app` when you need the operational subtype.
 - Generic `pmx-canvas node add --type mcp-app` is intentionally not supported because app nodes
   need app/session metadata. Use `pmx-canvas web-artifact build` for bundled React artifacts or
   `pmx-canvas external-app add --kind excalidraw` for the Excalidraw preset.

package/src/cli/agent.ts

@@ -237,8 +237,9 @@ function parseStringListFlag(
   flags: Record<string, string | true>,
   name: string,
   hint: string,
+  ...aliases: string[]
 ): string[] | undefined {
-  const raw = getStringFlag(flags, name);
+  const raw = getStringFlag(flags, name, ...aliases);
   if (raw === undefined) return undefined;
   const trimmed = raw.trim();
   if (!trimmed) {
@@ -295,6 +296,7 @@ function summarizeNodeResult(node: Record<string, unknown>): Record<string, unkn
     ...(node.ok !== undefined ? { ok: node.ok } : {}),
     id: node.id ?? null,
     type: node.type ?? null,
+    ...(typeof node.kind === 'string' ? { kind: node.kind } : {}),
     title: node.title ?? null,
     ...(typeof node.content === 'string' ? { contentPreview: truncateText(node.content) } : {}),
     ...(node.position !== undefined ? { position: node.position } : {}),
@@ -550,28 +552,39 @@ async function buildGraphRequestBody(
   const data = parseRecordArrayJson(rawData, hint);
 
   const body: Record<string, unknown> = {
-    graphType: getStringFlag(flags, 'graph-type') ?? 'line',
+    graphType: getStringFlag(flags, 'graph-type', 'graphType') ?? 'line',
     data,
   };
   if (typeof flags.title === 'string') body.title = flags.title;
-  if (typeof flags['x-key'] === 'string') body.xKey = flags['x-key'];
-  if (typeof flags['y-key'] === 'string') body.yKey = flags['y-key'];
-  if (typeof flags['z-key'] === 'string') body.zKey = flags['z-key'];
-  if (typeof flags['name-key'] === 'string') body.nameKey = flags['name-key'];
-  if (typeof flags['value-key'] === 'string') body.valueKey = flags['value-key'];
-  if (typeof flags['axis-key'] === 'string') body.axisKey = flags['axis-key'];
+  const xKey = getStringFlag(flags, 'x-key', 'xKey');
+  const yKey = getStringFlag(flags, 'y-key', 'yKey');
+  const zKey = getStringFlag(flags, 'z-key', 'zKey');
+  const nameKey = getStringFlag(flags, 'name-key', 'nameKey');
+  const valueKey = getStringFlag(flags, 'value-key', 'valueKey');
+  const axisKey = getStringFlag(flags, 'axis-key', 'axisKey');
+  if (xKey) body.xKey = xKey;
+  if (yKey) body.yKey = yKey;
+  if (zKey) body.zKey = zKey;
+  if (nameKey) body.nameKey = nameKey;
+  if (valueKey) body.valueKey = valueKey;
+  if (axisKey) body.axisKey = axisKey;
   const metrics = parseStringListFlag(flags, 'metrics', 'Use a comma-separated list, e.g. --metrics north,south');
   const series = parseStringListFlag(flags, 'series', 'Use a comma-separated list, e.g. --series north,south');
   if (metrics) body.metrics = metrics;
   if (series) body.series = series;
-  if (typeof flags['bar-key'] === 'string') body.barKey = flags['bar-key'];
-  if (typeof flags['line-key'] === 'string') body.lineKey = flags['line-key'];
+  const barKey = getStringFlag(flags, 'bar-key', 'barKey');
+  const lineKey = getStringFlag(flags, 'line-key', 'lineKey');
+  if (barKey) body.barKey = barKey;
+  if (lineKey) body.lineKey = lineKey;
   if (flags.aggregate === 'sum' || flags.aggregate === 'count' || flags.aggregate === 'avg') {
     body.aggregate = flags.aggregate;
   }
-  if (typeof flags.color === 'string') body.color = flags.color;
-  if (typeof flags['bar-color'] === 'string') body.barColor = flags['bar-color'];
-  if (typeof flags['line-color'] === 'string') body.lineColor = flags['line-color'];
+  const color = getStringFlag(flags, 'color');
+  const barColor = getStringFlag(flags, 'bar-color', 'barColor');
+  const lineColor = getStringFlag(flags, 'line-color', 'lineColor');
+  if (color) body.color = color;
+  if (barColor) body.barColor = barColor;
+  if (lineColor) body.lineColor = lineColor;
 
   const chartHeight = optionalPositiveFiniteFlag(flags, 'chart-height', 'Use a positive number, e.g. --chart-height 300');
   const x = optionalFiniteFlag(flags, 'x', 'Use a finite number, e.g. --x 500');
@@ -860,6 +873,21 @@ function filterJsonRenderSchemaView(
 // ── Commands ─────────────────────────────────────────────────
 
 const COMMANDS: Record<string, { run: (args: string[]) => Promise<void>; help: string; examples: string[] }> = {};
+const RESOURCE_COMMAND_ALIASES: Record<string, Record<string, string>> = {
+  node: {
+    delete: 'remove',
+    rm: 'remove',
+  },
+  edge: {
+    delete: 'remove',
+    rm: 'remove',
+  },
+};
+const RESOURCE_SUBCOMMAND_HINTS: Record<string, Record<string, string>> = {
+  node: {
+    pin: 'Use the top-level pin command instead: pmx-canvas pin <node-id>',
+  },
+};
 
 function cmd(
   name: string,
@@ -1035,7 +1063,7 @@ cmd('node list', 'List all nodes on the canvas', [
   let nodes = layout.nodes;
 
   if (flags.type && flags.type !== true) {
-    nodes = nodes.filter((n) => n.type === flags.type);
+    nodes = nodes.filter((n) => n.type === flags.type || n.kind === flags.type);
   }
 
   if (flags.ids) {
@@ -1291,7 +1319,9 @@ cmd('status', 'Quick canvas summary', [
   const typeCounts: Record<string, number> = {};
   for (const n of layout.nodes) {
     const data = isRecord(n.data) ? n.data : {};
-    const t = n.type === 'mcp-app' && data.hostMode === 'hosted' && typeof data.path === 'string'
+    const t = typeof n.kind === 'string'
+      ? n.kind
+      : n.type === 'mcp-app' && data.hostMode === 'hosted' && typeof data.path === 'string'
       ? 'web-artifact'
       : n.type as string;
     typeCounts[t] = (typeCounts[t] || 0) + 1;
@@ -1364,7 +1394,9 @@ cmd('external-app add', 'Create a hosted external app node', [
   });
 
   const result = await api('POST', '/api/canvas/diagram', body);
-  output(result);
+  output(result && typeof result === 'object' && !Array.isArray(result) && 'nodeId' in result && !('id' in result)
+    ? { id: (result as { nodeId?: unknown }).nodeId, ...result }
+    : result);
 });
 
 // ── pin ──────────────────────────────────────────────────────
@@ -2021,8 +2053,13 @@ function showCommandHelp(name: string): void {
     console.log('\nSchema help:');
     console.log('  pmx-canvas node add --help --type webpage');
     console.log('  pmx-canvas node add --help --type json-render --component Table');
+    console.log('  pmx-canvas node add --help --type graph');
     console.log('  pmx-canvas node add --help --type webpage --json');
   }
+  if (name === 'node add' || name === 'validate spec') {
+    console.log('\nGraph flags:');
+    console.log('  Graph fields accept kebab-case CLI flags and camelCase schema names, e.g. --graph-type/--graphType and --x-key/--xKey');
+  }
   if (name === 'node schema') {
     console.log('\nFilters:');
     console.log('  --summary                 Show compact schema summaries');
@@ -2203,12 +2240,32 @@ export async function runAgentCli(args: string[]): Promise<void> {
   // Unknown command — show help for the resource if it exists
   const resourceCommands = Object.keys(COMMANDS).filter((k) => k.startsWith(oneWord + ' '));
   if (resourceCommands.length > 0) {
-    console.log(`\nAvailable "${oneWord}" commands:\n`);
-    for (const k of resourceCommands) {
-      console.log(`  pmx-canvas ${k.padEnd(20)} ${COMMANDS[k].help}`);
+    if (args[1] === '--help' || args[1] === '-h') {
+      console.log(`\nAvailable "${oneWord}" commands:\n`);
+      for (const k of resourceCommands) {
+        console.log(`  pmx-canvas ${k.padEnd(20)} ${COMMANDS[k].help}`);
+      }
+      console.log('\nRun any command with --help for details.\n');
+      return;
     }
-    console.log('\nRun any command with --help for details.\n');
-    return;
+    const subcommand = args[1];
+    const suggestion = subcommand ? RESOURCE_COMMAND_ALIASES[oneWord]?.[subcommand] : undefined;
+    const extraHint = subcommand ? RESOURCE_SUBCOMMAND_HINTS[oneWord]?.[subcommand] : undefined;
+    const available = resourceCommands
+      .map((k) => k.slice(oneWord.length + 1))
+      .sort()
+      .join(', ');
+    const hints = [
+      suggestion ? `Did you mean: pmx-canvas ${oneWord} ${suggestion}?` : undefined,
+      extraHint,
+      `Available subcommands: ${available}`,
+    ].filter((hint): hint is string => typeof hint === 'string');
+    die(
+      subcommand
+        ? `Unknown ${oneWord} subcommand: "${subcommand}".`
+        : `Missing ${oneWord} subcommand.`,
+      hints.join(' '),
+    );
   }
 
   die(`Unknown command: ${oneWord}`, 'Run: pmx-canvas --help');

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

@@ -166,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);
@@ -232,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' &&
@@ -246,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;
@@ -542,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 });
@@ -552,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) {

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 } : {}),
               },
             });

package/src/server/canvas-operations.ts

@@ -4,7 +4,6 @@ import { recomputeCodeGraph } from './code-graph.js';
 import {
   canvasState,
   type CanvasEdge,
-  IMAGE_MIME_MAP,
   type CanvasNodeState,
   type CanvasNodeUpdate,
   type CanvasSnapshot,
@@ -36,6 +35,7 @@ import {
   getWebpageFetchErrorDetails,
   normalizeWebpageUrl,
 } from './webpage-node.js';
+import { validateLocalImageFile } from './image-source.js';
 import { buildExcalidrawRestoreCheckpointToolInput, ensureExcalidrawCheckpointId, isExcalidrawCreateView } from './diagram-presets.js';
 
 export type CanvasArrangeMode = 'grid' | 'column' | 'flow';
@@ -435,22 +435,14 @@ function buildImageNodeData(input: CanvasAddNodeInput): Record<string, unknown>
 
   if (!isDataUri && !isUrl && src) {
     const resolved = resolve(src);
-    const ext = resolved.split('.').pop()?.toLowerCase() ?? '';
     const fileName = resolved.split('/').pop() ?? src;
-    const mime = IMAGE_MIME_MAP[ext];
-    if (!mime) {
-      throw new Error(
-        `Invalid image node: "${fileName}" has unsupported extension ".${ext}". ` +
-          `Accepted: ${Object.keys(IMAGE_MIME_MAP).join(', ')}. ` +
-          `For non-image files use type="file" (live viewer) or type="webpage" (URL) instead.`,
-      );
-    }
+    const { mimeType } = validateLocalImageFile(resolved);
     return {
       ...(input.data ?? {}),
       src: resolved,
       title: input.title ?? fileName,
       path: resolved,
-      mimeType: mime,
+      mimeType,
     };
   }
 
@@ -1210,12 +1202,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.', aliases: ['data-json'] },
+      { 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'] },