pmx-canvas 0.3.0 → 0.3.1

package/src/server/canvas-schema.ts

@@ -62,7 +62,7 @@ const CANONICAL_GRAPH_TYPES = [
   'slopegraph',
 ] as const;
 
-type CanvasGraphType = typeof CANONICAL_GRAPH_TYPES[number];
+type CanvasGraphType = (typeof CANONICAL_GRAPH_TYPES)[number];
 
 function readPackageVersion(): string | null {
   try {
@@ -88,7 +88,13 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },
       { name: 'height', type: 'number', required: false, description: 'Optional node height.' },
-      { name: 'strictSize', type: 'boolean', required: false, description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.', aliases: ['strict-size', 'scroll-overflow'] },
+      {
+        name: 'strictSize',
+        type: 'boolean',
+        required: false,
+        description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.',
+        aliases: ['strict-size', 'scroll-overflow'],
+      },
     ],
     example: {
       type: 'markdown',
@@ -156,11 +162,26 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title.' },
       { name: 'content', type: 'string', required: false, description: 'Trace summary.' },
-      { name: 'toolName', type: 'string', required: false, description: 'Tool or operation label shown in the trace pill; defaults to title.' },
-      { name: 'category', type: 'string', required: false, description: 'Trace category color key: mcp, file, subagent, or other.' },
+      {
+        name: 'toolName',
+        type: 'string',
+        required: false,
+        description: 'Tool or operation label shown in the trace pill; defaults to title.',
+      },
+      {
+        name: 'category',
+        type: 'string',
+        required: false,
+        description: 'Trace category color key: mcp, file, subagent, or other.',
+      },
       { name: 'status', type: 'string', required: false, description: 'Trace status: running, success, or failed.' },
       { name: 'duration', type: 'string', required: false, description: 'Optional duration badge text.' },
-      { name: 'resultSummary', type: 'string', required: false, description: 'Short trace result summary; defaults to content.' },
+      {
+        name: 'resultSummary',
+        type: 'string',
+        required: false,
+        description: 'Short trace result summary; defaults to content.',
+      },
       { name: 'error', type: 'string', required: false, description: 'Short error message shown in failed traces.' },
     ],
     example: {
@@ -195,12 +216,38 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/node',
     mcpTool: 'canvas_node (action:"add")',
     fields: [
-      { name: 'content', type: 'string', required: true, description: 'Image path, URL, or data URI.', aliases: ['path'] },
+      {
+        name: 'content',
+        type: 'string',
+        required: true,
+        description: 'Image path, URL, or data URI.',
+        aliases: ['path'],
+      },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
-      { name: 'data.warning', type: 'string | { title?: string; detail: string }', required: false, description: 'Optional agent-supplied warning shown above the image.' },
-      { name: 'data.warnings', type: 'Array<string | { title?: string; detail: string }>', required: false, description: 'Optional list of agent-supplied image warnings.' },
-      { name: 'data.validationStatus', type: '"passed" | "failed" | "invalid"', required: false, description: 'Optional agent validation result for evidence-style images.' },
-      { name: 'data.validationMessage', type: 'string', required: false, description: 'Optional detail shown when validation fails.' },
+      {
+        name: 'data.warning',
+        type: 'string | { title?: string; detail: string }',
+        required: false,
+        description: 'Optional agent-supplied warning shown above the image.',
+      },
+      {
+        name: 'data.warnings',
+        type: 'Array<string | { title?: string; detail: string }>',
+        required: false,
+        description: 'Optional list of agent-supplied image warnings.',
+      },
+      {
+        name: 'data.validationStatus',
+        type: '"passed" | "failed" | "invalid"',
+        required: false,
+        description: 'Optional agent validation result for evidence-style images.',
+      },
+      {
+        name: 'data.validationMessage',
+        type: 'string',
+        required: false,
+        description: 'Optional detail shown when validation fails.',
+      },
     ],
     example: {
       type: 'image',
@@ -221,13 +268,25 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/node',
     mcpTool: 'canvas_node (action:"add")',
     fields: [
-      { name: 'url', type: 'string', required: true, description: 'HTTP(S) URL to fetch and cache.', aliases: ['content'] },
+      {
+        name: 'url',
+        type: 'string',
+        required: true,
+        description: 'HTTP(S) URL to fetch and cache.',
+        aliases: ['content'],
+      },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
       { name: 'x', type: 'number', required: false, description: 'Optional X position.' },
       { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },
       { name: 'height', type: 'number', required: false, description: 'Optional node height.' },
-      { name: 'strictSize', type: 'boolean', required: false, description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.', aliases: ['strict-size', 'scroll-overflow'] },
+      {
+        name: 'strictSize',
+        type: 'boolean',
+        required: false,
+        description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.',
+        aliases: ['strict-size', 'scroll-overflow'],
+      },
     ],
     example: {
       type: 'webpage',
@@ -246,21 +305,78 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/node',
     mcpTool: 'canvas_node (action:"add", type:"html")',
     fields: [
-      { name: 'html', type: 'string', required: false, description: 'HTML document or fragment rendered in the sandboxed iframe.', aliases: ['content', 'stdin'] },
-      { name: 'summary', type: 'string', required: false, description: 'Explicit agent-readable summary. If omitted, PMX derives one from visible HTML text.' },
-      { name: 'agentSummary', type: 'string', required: false, description: 'Explicit semantic sidecar used by search, pinned context, and spatial context.', aliases: ['agent-summary'] },
-      { name: 'embeddedNodeIds', type: 'string[]', required: false, description: 'Canvas node IDs represented or iframe-embedded by this HTML surface.', aliases: ['embedded-node-id', 'embedded-node-ids'] },
-      { name: 'embeddedUrls', type: 'string[]', required: false, description: 'URLs represented or iframe-embedded by this HTML surface.', aliases: ['embedded-url', 'embedded-urls'] },
-      { name: 'presentation', type: 'boolean', required: false, description: 'Marks this HTML surface as a fullscreen presentation/deck.' },
-      { name: 'slideTitles', type: 'string[]', required: false, description: 'Agent-readable slide titles for presentation HTML.', aliases: ['slide-title', 'slide-titles'] },
-      { name: 'primitive', type: 'HtmlPrimitiveKind', required: false, description: 'Generate HTML from a built-in communication primitive instead of passing raw HTML.', aliases: ['kind'] },
-      { name: 'data', type: 'record<string, unknown>', required: false, description: 'Primitive data when --primitive is used, or arbitrary node metadata.' },
+      {
+        name: 'html',
+        type: 'string',
+        required: false,
+        description: 'HTML document or fragment rendered in the sandboxed iframe.',
+        aliases: ['content', 'stdin'],
+      },
+      {
+        name: 'summary',
+        type: 'string',
+        required: false,
+        description: 'Explicit agent-readable summary. If omitted, PMX derives one from visible HTML text.',
+      },
+      {
+        name: 'agentSummary',
+        type: 'string',
+        required: false,
+        description: 'Explicit semantic sidecar used by search, pinned context, and spatial context.',
+        aliases: ['agent-summary'],
+      },
+      {
+        name: 'embeddedNodeIds',
+        type: 'string[]',
+        required: false,
+        description: 'Canvas node IDs represented or iframe-embedded by this HTML surface.',
+        aliases: ['embedded-node-id', 'embedded-node-ids'],
+      },
+      {
+        name: 'embeddedUrls',
+        type: 'string[]',
+        required: false,
+        description: 'URLs represented or iframe-embedded by this HTML surface.',
+        aliases: ['embedded-url', 'embedded-urls'],
+      },
+      {
+        name: 'presentation',
+        type: 'boolean',
+        required: false,
+        description: 'Marks this HTML surface as a fullscreen presentation/deck.',
+      },
+      {
+        name: 'slideTitles',
+        type: 'string[]',
+        required: false,
+        description: 'Agent-readable slide titles for presentation HTML.',
+        aliases: ['slide-title', 'slide-titles'],
+      },
+      {
+        name: 'primitive',
+        type: 'HtmlPrimitiveKind',
+        required: false,
+        description: 'Generate HTML from a built-in communication primitive instead of passing raw HTML.',
+        aliases: ['kind'],
+      },
+      {
+        name: 'data',
+        type: 'record<string, unknown>',
+        required: false,
+        description: 'Primitive data when --primitive is used, or arbitrary node metadata.',
+      },
       { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
       { name: 'x', type: 'number', required: false, description: 'Optional X position.' },
       { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },
       { name: 'height', type: 'number', required: false, description: 'Optional node height.' },
-      { name: 'strictSize', type: 'boolean', required: false, description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.', aliases: ['strict-size', 'scroll-overflow'] },
+      {
+        name: 'strictSize',
+        type: 'boolean',
+        required: false,
+        description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.',
+        aliases: ['strict-size', 'scroll-overflow'],
+      },
     ],
     example: {
       type: 'html',
@@ -283,23 +399,37 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/node',
     mcpTool: 'canvas_node (action:"add", type:"html", primitive:"<kind>")',
     fields: [
-      { name: 'kind', type: 'HtmlPrimitiveKind', required: true, description: 'Primitive kind. See top-level htmlPrimitives for the supported catalog.' },
-      { name: 'data', type: 'record<string, unknown>', required: false, description: 'Primitive-specific JSON object payload.' },
+      {
+        name: 'kind',
+        type: 'HtmlPrimitiveKind',
+        required: true,
+        description: 'Primitive kind. See top-level htmlPrimitives for the supported catalog.',
+      },
+      {
+        name: 'data',
+        type: 'record<string, unknown>',
+        required: false,
+        description: 'Primitive-specific JSON object payload.',
+      },
       { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
       { name: 'x', type: 'number', required: false, description: 'Optional X position.' },
       { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
       { name: 'width', type: 'number', required: false, description: 'Optional node width; defaults per primitive.' },
       { name: 'height', type: 'number', required: false, description: 'Optional node height; defaults per primitive.' },
-      { name: 'strictSize', type: 'boolean', required: false, description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.', aliases: ['strict-size', 'scroll-overflow'] },
+      {
+        name: 'strictSize',
+        type: 'boolean',
+        required: false,
+        description: 'Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting.',
+        aliases: ['strict-size', 'scroll-overflow'],
+      },
     ],
     example: {
       type: 'html-primitive',
       kind: 'choice-grid',
       title: 'Implementation Options',
       data: {
-        items: [
-          { title: 'Small patch', summary: 'Least disruption.', pros: ['Fast'], cons: ['Limited flexibility'] },
-        ],
+        items: [{ title: 'Small patch', summary: 'Least disruption.', pros: ['Fast'], cons: ['Limited flexibility'] }],
       },
     },
     notes: [
@@ -336,8 +466,18 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     mcpTool: 'canvas_app (action:"open-mcp-app")',
     fields: [
       { name: 'toolName', type: 'string', required: true, description: 'Tool name on the external MCP server.' },
-      { name: 'transport', type: '{ type: "stdio", command, args? } | { type: "http", url, headers? }', required: true, description: 'External MCP transport definition.' },
-      { name: 'toolArguments', type: 'record<string, unknown>', required: false, description: 'Arguments passed to the external MCP tool.' },
+      {
+        name: 'transport',
+        type: '{ type: "stdio", command, args? } | { type: "http", url, headers? }',
+        required: true,
+        description: 'External MCP transport definition.',
+      },
+      {
+        name: 'toolArguments',
+        type: 'record<string, unknown>',
+        required: false,
+        description: 'Arguments passed to the external MCP tool.',
+      },
       { name: 'title', type: 'string', required: false, description: 'Optional canvas node title override.' },
     ],
     example: {
@@ -360,7 +500,12 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Group title.' },
       { name: 'childIds', type: 'string[]', required: false, description: 'Initial child node IDs.' },
-      { name: 'childLayout', type: '"grid" | "column" | "flow"', required: false, description: 'Optional layout for grouped children.' },
+      {
+        name: 'childLayout',
+        type: '"grid" | "column" | "flow"',
+        required: false,
+        description: 'Optional layout for grouped children.',
+      },
     ],
     example: {
       title: 'API Layer',
@@ -375,8 +520,19 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/json-render',
     mcpTool: 'canvas_render (action:"add-json-render")',
     fields: [
-      { name: 'title', type: 'string', required: false, description: 'Optional rendered node title; inferred from the root element when omitted.' },
-      { name: 'spec', type: 'JsonRenderSpec | JsonRenderElement', required: true, description: 'Complete {root, elements} json-render spec, or a legacy single bare component object with a type field.' },
+      {
+        name: 'title',
+        type: 'string',
+        required: false,
+        description: 'Optional rendered node title; inferred from the root element when omitted.',
+      },
+      {
+        name: 'spec',
+        type: 'JsonRenderSpec | JsonRenderElement',
+        required: true,
+        description:
+          'Complete {root, elements} json-render spec, or a legacy single bare component object with a type field.',
+      },
       { name: 'x', type: 'number', required: false, description: 'Optional X position.' },
       { name: 'y', type: 'number', required: false, description: 'Optional Y position.' },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },
@@ -412,39 +568,206 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
         name: 'graphType',
         type: '"line" | "bar" | "pie" | "area" | "scatter" | "radar" | "stacked-bar" | "composed" | "sparkline" | "dot-plot" | "bullet" | "slopegraph"',
         required: true,
-        description: 'Chart type. Includes the Tufte primitives sparkline, dot-plot (Cleveland), bullet (Few KPI vs target), and slopegraph (paired before/after). Aliases like "stack", "combo", "dot", and "slope" are normalized server-side.',
+        description:
+          'Chart type. Includes the Tufte primitives sparkline, dot-plot (Cleveland), bullet (Few KPI vs target), and slopegraph (paired before/after). Aliases like "stack", "combo", "dot", and "slope" are normalized server-side.',
         aliases: ['graph-type'],
       },
-      { 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: '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.', 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: 'Value key for pie slices, sparkline, dot-plot, and the bullet measure.', 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.', 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.', aliases: ['bar-color'] },
-      { name: 'lineColor', type: 'string', required: false, description: 'Optional line color for composed charts.', aliases: ['line-color'] },
-      { name: 'colorBy', type: '"series" | "category" | "value" | "none"', required: false, description: 'Bar charts only: how bars are colored. Default "series" (single accent + one highlighted bar). "category" rotates the palette, "value" shades by magnitude, "none" is flat. Color should encode data, not decorate.', aliases: ['color-by'] },
-      { name: 'highlight', type: 'number | "max" | "min"', required: false, description: 'Bar charts (colorBy="series") only: which bar gets the accent — "max" (default), "min", a 0-based index, or null for no emphasis.' },
-      { name: 'labelKey', type: 'string', required: false, description: 'Category label key for dot-plot, bullet, and slopegraph rows.', aliases: ['label-key'] },
-      { name: 'targetKey', type: 'string', required: false, description: 'Per-row target value key for bullet charts.', aliases: ['target-key'] },
-      { name: 'rangesKey', type: 'string', required: false, description: 'Per-row qualitative band thresholds (number[]) key for bullet charts.', aliases: ['ranges-key'] },
-      { name: 'beforeKey', type: 'string', required: false, description: 'Left-column value key for slopegraph.', aliases: ['before-key'] },
-      { name: 'afterKey', type: 'string', required: false, description: 'Right-column value key for slopegraph.', aliases: ['after-key'] },
-      { name: 'sort', type: '"asc" | "desc" | "none"', required: false, description: 'Row sort order for dot-plot (defaults to desc).' },
-      { name: 'height', type: 'number', required: false, description: 'Optional chart content height.', aliases: ['chart-height'] },
-      { name: 'showLegend', type: 'boolean', required: false, description: 'Show chart legend when supported; pass false for compact node layouts.', aliases: ['show-legend'] },
-      { name: 'showLabels', type: 'boolean', required: false, description: 'Show direct labels when supported, such as pie slice labels; defaults to true.', aliases: ['show-labels'] },
+      {
+        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: 'Value key for pie slices, sparkline, dot-plot, and the bullet measure.',
+        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.',
+        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.',
+        aliases: ['bar-color'],
+      },
+      {
+        name: 'lineColor',
+        type: 'string',
+        required: false,
+        description: 'Optional line color for composed charts.',
+        aliases: ['line-color'],
+      },
+      {
+        name: 'colorBy',
+        type: '"series" | "category" | "value" | "none"',
+        required: false,
+        description:
+          'Bar charts only: how bars are colored. Default "series" (single accent + one highlighted bar). "category" rotates the palette, "value" shades by magnitude, "none" is flat. Color should encode data, not decorate.',
+        aliases: ['color-by'],
+      },
+      {
+        name: 'highlight',
+        type: 'number | "max" | "min"',
+        required: false,
+        description:
+          'Bar charts (colorBy="series") only: which bar gets the accent — "max" (default), "min", a 0-based index, or null for no emphasis.',
+      },
+      {
+        name: 'labelKey',
+        type: 'string',
+        required: false,
+        description: 'Category label key for dot-plot, bullet, and slopegraph rows.',
+        aliases: ['label-key'],
+      },
+      {
+        name: 'targetKey',
+        type: 'string',
+        required: false,
+        description: 'Per-row target value key for bullet charts.',
+        aliases: ['target-key'],
+      },
+      {
+        name: 'rangesKey',
+        type: 'string',
+        required: false,
+        description: 'Per-row qualitative band thresholds (number[]) key for bullet charts.',
+        aliases: ['ranges-key'],
+      },
+      {
+        name: 'beforeKey',
+        type: 'string',
+        required: false,
+        description: 'Left-column value key for slopegraph.',
+        aliases: ['before-key'],
+      },
+      {
+        name: 'afterKey',
+        type: 'string',
+        required: false,
+        description: 'Right-column value key for slopegraph.',
+        aliases: ['after-key'],
+      },
+      {
+        name: 'sort',
+        type: '"asc" | "desc" | "none"',
+        required: false,
+        description: 'Row sort order for dot-plot (defaults to desc).',
+      },
+      {
+        name: 'height',
+        type: 'number',
+        required: false,
+        description: 'Optional chart content height.',
+        aliases: ['chart-height'],
+      },
+      {
+        name: 'showLegend',
+        type: 'boolean',
+        required: false,
+        description: 'Show chart legend when supported; pass false for compact node layouts.',
+        aliases: ['show-legend'],
+      },
+      {
+        name: 'showLabels',
+        type: 'boolean',
+        required: false,
+        description: 'Show direct labels when supported, such as pie slice labels; defaults to true.',
+        aliases: ['show-labels'],
+      },
       { name: 'width', type: 'number', required: false, description: 'Optional node width.' },
-      { 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'] },
-      { name: 'strictSize', type: 'boolean', required: false, description: 'Keep explicit node size fixed and scroll overflowing content instead of browser auto-fitting.', aliases: ['strict-size', 'scroll-overflow'] },
+      {
+        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'],
+      },
+      {
+        name: 'strictSize',
+        type: 'boolean',
+        required: false,
+        description: 'Keep explicit node size fixed and scroll overflowing content instead of browser auto-fitting.',
+        aliases: ['strict-size', 'scroll-overflow'],
+      },
     ],
     example: {
       title: 'Deploy Trend',
@@ -470,16 +793,62 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     mcpTool: 'canvas_app (action:"build-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. 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'] },
+      {
+        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'],
+      },
       { name: 'projectPath', type: 'string', required: false, description: 'Optional project directory.' },
       { 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'] },
-      { name: 'timeoutMs', type: 'number', required: false, description: 'Build command timeout in milliseconds. This controls subprocess timeout, not the MCP client request timeout.' },
+      {
+        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'],
+      },
+      {
+        name: 'timeoutMs',
+        type: 'number',
+        required: false,
+        description:
+          'Build command timeout in milliseconds. This controls subprocess timeout, not the MCP client request timeout.',
+      },
     ],
     example: {
       title: 'Dashboard Artifact',
@@ -540,9 +909,21 @@ export function describeCanvasSchema(): {
       },
       components: clone(describeJsonRenderCatalog()),
       directives: [
-        { name: '$state', usage: '{ "$state": "/path/to/value" } — read a value from the state model by path (one-way). Use this to bind a value by path; there is no $path directive.' },
-        { name: '$format', usage: '{ "$format": "currency"|"number"|"percent"|"date", "value": <num|state-ref>, "currency"?: "USD", "locale"?, "style"?, "options"? } — Intl-formatted string' },
-        { name: '$math', usage: '{ "$math": "add"|"subtract"|"multiply"|"divide"|"mod"|"min"|"max"|"round"|"floor"|"ceil"|"abs", "a": <num>, "b"?: <num> }' },
+        {
+          name: '$state',
+          usage:
+            '{ "$state": "/path/to/value" } — read a value from the state model by path (one-way). Use this to bind a value by path; there is no $path directive.',
+        },
+        {
+          name: '$format',
+          usage:
+            '{ "$format": "currency"|"number"|"percent"|"date", "value": <num|state-ref>, "currency"?: "USD", "locale"?, "style"?, "options"? } — Intl-formatted string',
+        },
+        {
+          name: '$math',
+          usage:
+            '{ "$math": "add"|"subtract"|"multiply"|"divide"|"mod"|"min"|"max"|"round"|"floor"|"ceil"|"abs", "a": <num>, "b"?: <num> }',
+        },
         { name: '$concat', usage: '{ "$concat": [<value>, <value>, ...] } — join values into one string' },
         { name: '$count', usage: '{ "$count": <array|state-ref> } — length of an array' },
         { name: '$truncate', usage: '{ "$truncate": <string>, "length": <num>, "suffix"?: "…" }' },