pmx-canvas 0.1.7 → 0.1.9

package/src/json-render/server.ts

@@ -11,7 +11,7 @@ export interface JsonRenderSpec {
 }
 
 export interface JsonRenderNodeInput {
-  title: string;
+  title?: string;
   spec: unknown;
   x?: number;
   y?: number;
@@ -430,6 +430,7 @@ function normalizeSpec(spec: Record<string, unknown>): Record<string, unknown> {
     const elementChanged =
       resolvedType !== element.type ||
       JSON.stringify(normalizedProps) !== JSON.stringify(rawProps) ||
+      !('visible' in element) ||
       !Array.isArray(element.children) ||
       normalizedChildren.length !== element.children.length;
 
@@ -438,6 +439,7 @@ function normalizeSpec(spec: Record<string, unknown>): Record<string, unknown> {
           ...element,
           type: resolvedType,
           props: normalizedProps,
+          visible: 'visible' in element ? element.visible : true,
           children: normalizedChildren,
         }
       : rawElement;
@@ -447,10 +449,39 @@ function normalizeSpec(spec: Record<string, unknown>): Record<string, unknown> {
   return changed ? { ...spec, elements: normalizedElements } : spec;
 }
 
-export function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec {
+function isBareJsonRenderElement(spec: Record<string, unknown>): boolean {
+  return typeof spec.type === 'string' && !('root' in spec) && !('elements' in spec);
+}
+
+function normalizeJsonRenderInput(spec: unknown): unknown {
   const specRecord = asRecord(spec);
+  if (!specRecord || !isBareJsonRenderElement(specRecord)) return spec;
+
+  return {
+    root: 'root',
+    elements: {
+      root: {
+        ...specRecord,
+        visible: 'visible' in specRecord ? specRecord.visible : true,
+        children: Array.isArray(specRecord.children)
+          ? specRecord.children.filter((child: unknown) => typeof child === 'string')
+          : [],
+      },
+    },
+  };
+}
+
+export function inferJsonRenderNodeTitle(spec: JsonRenderSpec, fallback = 'json-render'): string {
+  const rootElement = asRecord(spec.elements[spec.root]);
+  const rootProps = asRecord(rootElement?.props);
+  const title = rootProps?.title ?? rootProps?.text ?? rootElement?.type;
+  return typeof title === 'string' && title.trim().length > 0 ? title.trim() : fallback;
+}
+
+export function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec {
+  const specRecord = asRecord(normalizeJsonRenderInput(spec));
   if (!specRecord || typeof specRecord.root !== 'string' || !asRecord(specRecord.elements)) {
-    throw new Error('Missing root and elements in spec.');
+    throw new Error('Missing root and elements in spec. Pass a complete {root, elements} document, or a single bare component object with a type field.');
   }
 
   const normalizedSpec = normalizeSpec(specRecord);
@@ -572,6 +603,30 @@ export function buildGraphSpec(input: GraphNodeInput): JsonRenderSpec {
   });
 }
 
+export function buildGraphConfig(input: GraphNodeInput): Record<string, unknown> {
+  const title = input.title?.trim() || 'Graph';
+  return {
+    title,
+    graphType: input.graphType,
+    data: input.data,
+    ...(input.xKey ? { xKey: input.xKey } : {}),
+    ...(input.yKey ? { yKey: input.yKey } : {}),
+    ...(input.zKey ? { zKey: input.zKey } : {}),
+    ...(input.nameKey ? { nameKey: input.nameKey } : {}),
+    ...(input.valueKey ? { valueKey: input.valueKey } : {}),
+    ...(input.axisKey ? { axisKey: input.axisKey } : {}),
+    ...(input.metrics?.length ? { metrics: input.metrics } : {}),
+    ...(input.series?.length ? { series: input.series } : {}),
+    ...(input.barKey ? { barKey: input.barKey } : {}),
+    ...(input.lineKey ? { lineKey: input.lineKey } : {}),
+    ...(input.aggregate ? { aggregate: input.aggregate } : {}),
+    ...(input.color ? { color: input.color } : {}),
+    ...(input.barColor ? { barColor: input.barColor } : {}),
+    ...(input.lineColor ? { lineColor: input.lineColor } : {}),
+    ...(typeof input.height === 'number' ? { height: input.height } : {}),
+  };
+}
+
 export function createJsonRenderNodeData(
   nodeId: string,
   title: string,

package/src/mcp/server.ts

@@ -41,11 +41,18 @@ import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js
 
 let canvas: PmxCanvas | null = null;
 
-const jsonRenderSpecSchema = z.object({
-  root: z.string(),
-  elements: z.record(z.string(), z.unknown()),
-  state: z.record(z.string(), z.unknown()).optional(),
-}).passthrough();
+const jsonRenderSpecSchema = z.union([
+  z.object({
+    root: z.string(),
+    elements: z.record(z.string(), z.unknown()),
+    state: z.record(z.string(), z.unknown()).optional(),
+  }).passthrough(),
+  z.object({
+    type: z.string(),
+    props: z.record(z.string(), z.unknown()).optional(),
+    children: z.array(z.string()).optional(),
+  }).passthrough(),
+]);
 
 function structuredSchemaDescription(): string {
   const routing = describeCanvasSchema().mcp.nodeTypeRouting;
@@ -88,7 +95,9 @@ function encodeBase64(bytes: Uint8Array): string {
 
 function createdNodePayload(c: PmxCanvas, id: string): Record<string, unknown> {
   const node = c.getNode(id);
-  return node ? { ok: true, ...serializeCanvasNode(node) } : { ok: true, id };
+  if (!node) return { ok: true, id };
+  const serialized = serializeCanvasNode(node);
+  return { ok: true, node: serialized, ...serialized };
 }
 
 export async function startMcpServer(): Promise<void> {
@@ -140,6 +149,7 @@ export async function startMcpServer(): Promise<void> {
         .describe('Node type (prefer canvas_create_group for groups)'),
       title: z.string().optional().describe('Node title'),
       content: z.string().optional().describe('Node content (markdown for markdown nodes, file path for file nodes, image path/URL/data-URI for image nodes, URL for webpage nodes)'),
+      path: z.string().optional().describe('Compatibility alias for image node content. Prefer content for image paths.'),
       url: z.string().optional().describe('Canonical webpage URL field for webpage nodes. Overrides content when both are provided.'),
       x: z.number().optional().describe('X position (auto-placed if omitted)'),
       y: z.number().optional().describe('Y position (auto-placed if omitted)'),
@@ -169,7 +179,10 @@ export async function startMcpServer(): Promise<void> {
           ...(result.ok ? {} : { isError: true }),
         };
       }
-      const id = c.addNode(input);
+      const nodeInput = input.type === 'image' && input.path && !input.content
+        ? { ...input, content: input.path }
+        : input;
+      const id = c.addNode(nodeInput);
       return {
         content: [{ type: 'text', text: JSON.stringify(createdNodePayload(c, id), null, 2) }],
       };
@@ -442,8 +455,8 @@ export async function startMcpServer(): Promise<void> {
     'canvas_add_json_render_node',
     'Create a native json-render canvas node from a complete spec. Use this for structured dashboards, forms, tables, and other interactive UI panels that should render directly inside PMX Canvas.',
     {
-      title: z.string().describe('Node title'),
-      spec: jsonRenderSpecSchema.describe('Complete json-render spec with root, elements, and optional state'),
+      title: z.string().optional().describe('Optional node title. If omitted, PMX Canvas infers one from the root element.'),
+      spec: z.unknown().describe('json-render spec. Prefer a complete {root, elements, state?} document; a single bare component object is accepted for legacy callers.'),
       x: z.number().optional().describe('Optional X position'),
       y: z.number().optional().describe('Optional Y position'),
       width: z.number().optional().describe('Optional node width'),
@@ -453,7 +466,7 @@ export async function startMcpServer(): Promise<void> {
       const c = await ensureCanvas();
       try {
         const result = c.addJsonRenderNode({
-          title: input.title,
+          ...(typeof input.title === 'string' ? { title: input.title } : {}),
           spec: input.spec,
           ...(typeof input.x === 'number' ? { x: input.x } : {}),
           ...(typeof input.y === 'number' ? { y: input.y } : {}),
@@ -565,10 +578,16 @@ export async function startMcpServer(): Promise<void> {
       y: z.number().optional().describe('New Y position'),
       width: z.number().optional().describe('New width'),
       height: z.number().optional().describe('New height'),
+      spec: z.record(z.string(), z.unknown()).optional().describe('New json-render spec, or a graph payload with graphType/data for graph nodes'),
+      graphType: z.string().optional().describe('Graph type when updating a graph node'),
+      data: z.array(z.record(z.string(), z.unknown())).optional().describe('Graph dataset when updating a graph node'),
+      xKey: z.string().optional().describe('Graph x/category key'),
+      yKey: z.string().optional().describe('Graph y/value key'),
+      chartHeight: z.number().optional().describe('Graph chart content height, distinct from node height'),
       collapsed: z.boolean().optional().describe('Collapse or expand the node'),
       arrangeLocked: z.boolean().optional().describe('Prevent auto-arrange from moving this node. Pinned nodes are also skipped.'),
     },
-    async ({ id, title, content, x, y, width, height, collapsed, arrangeLocked }) => {
+    async ({ id, title, content, x, y, width, height, spec, graphType, data, xKey, yKey, chartHeight, collapsed, arrangeLocked }) => {
       const c = await ensureCanvas();
       const node = c.getNode(id);
       if (!node) {
@@ -587,22 +606,21 @@ export async function startMcpServer(): Promise<void> {
       if (collapsed !== undefined) {
         patch.collapsed = collapsed;
       }
-      if (title !== undefined || content !== undefined) {
-        patch.data = {
-          ...node.data,
-          ...(title !== undefined ? { title } : {}),
-          ...(content !== undefined ? { content } : {}),
-        };
-      }
+      if (title !== undefined) patch.title = title;
+      if (content !== undefined) patch.content = content;
+      if (spec !== undefined) patch.spec = spec;
+      if (graphType !== undefined) patch.graphType = graphType;
+      if (data !== undefined) patch.data = data;
+      if (xKey !== undefined) patch.xKey = xKey;
+      if (yKey !== undefined) patch.yKey = yKey;
+      if (chartHeight !== undefined) patch.chartHeight = chartHeight;
       if (arrangeLocked !== undefined) {
-        patch.data = {
-          ...(patch.data && typeof patch.data === 'object' ? patch.data as Record<string, unknown> : node.data),
-          arrangeLocked,
-        };
+        patch.arrangeLocked = arrangeLocked;
       }
       c.updateNode(id, patch);
+      const updated = c.getNode(id);
       return {
-        content: [{ type: 'text', text: JSON.stringify({ ok: true, id }) }],
+        content: [{ type: 'text', text: JSON.stringify(updated ? createdNodePayload(c, id) : { ok: true, id }, null, 2) }],
       };
     },
   );
@@ -732,6 +750,31 @@ export async function startMcpServer(): Promise<void> {
     },
   );
 
+  server.tool(
+    'canvas_fit_view',
+    'Fit the canvas viewport to all nodes or a selected subset. Useful before screenshots and whole-board review.',
+    {
+      width: z.number().optional().describe('Viewport width used for fit math (default 1440)'),
+      height: z.number().optional().describe('Viewport height used for fit math (default 900)'),
+      padding: z.number().optional().describe('World-space padding around fitted nodes (default 60)'),
+      maxScale: z.number().optional().describe('Maximum zoom scale (default 1)'),
+      nodeIds: z.array(z.string()).optional().describe('Optional node IDs to fit instead of the whole canvas'),
+    },
+    async (input) => {
+      const c = await ensureCanvas();
+      const result = c.fitView({
+        ...(typeof input.width === 'number' ? { width: input.width } : {}),
+        ...(typeof input.height === 'number' ? { height: input.height } : {}),
+        ...(typeof input.padding === 'number' ? { padding: input.padding } : {}),
+        ...(typeof input.maxScale === 'number' ? { maxScale: input.maxScale } : {}),
+        ...(Array.isArray(input.nodeIds) ? { nodeIds: input.nodeIds } : {}),
+      });
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+
   // ── canvas_clear ───────────────────────────────────────────────
   server.tool(
     'canvas_clear',

package/src/server/canvas-operations.ts

@@ -22,8 +22,10 @@ import { searchNodes } from './spatial-analysis.js';
 import { getCanvasNodeTitle, serializeCanvasNode, type SerializedCanvasNode } from './canvas-serialization.js';
 import {
   buildGraphSpec,
+  buildGraphConfig,
   createJsonRenderNodeData,
   GRAPH_NODE_SIZE,
+  inferJsonRenderNodeTitle,
   JSON_RENDER_NODE_SIZE,
   normalizeAndValidateJsonRenderSpec,
   type GraphNodeInput,
@@ -41,6 +43,33 @@ import { buildExcalidrawRestoreCheckpointToolInput, ensureExcalidrawCheckpointId
 export type CanvasArrangeMode = 'grid' | 'column' | 'flow';
 export type CanvasPinMode = 'set' | 'add' | 'remove';
 
+export interface CanvasFitViewOptions {
+  width?: number;
+  height?: number;
+  padding?: number;
+  maxScale?: number;
+  nodeIds?: string[];
+}
+
+export interface CanvasFitViewResult {
+  ok: true;
+  viewport: { x: number; y: number; scale: number };
+  nodeCount: number;
+  bounds: { x: number; y: number; width: number; height: number } | null;
+}
+
+export interface CanvasGraphNodeUpdateInput extends Partial<GraphNodeInput> {
+  spec?: unknown;
+  type?: string;
+}
+
+export interface CanvasStructuredNodeUpdateInput extends Omit<CanvasGraphNodeUpdateInput, 'data'> {
+  content?: unknown;
+  data?: unknown;
+  arrangeLocked?: unknown;
+  chartHeight?: unknown;
+}
+
 interface CanvasAddNodeInput {
   type: CanvasNodeState['type'];
   title?: string;
@@ -83,6 +112,246 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function positiveNumber(value: number | undefined, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function pickString(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+
+function pickNumber(record: Record<string, unknown>, key: string): number | undefined {
+  const value = record[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function pickStringArray(record: Record<string, unknown>, key: string): string[] | undefined {
+  const value = record[key];
+  if (!Array.isArray(value)) return undefined;
+  const strings = value.filter((item): item is string => typeof item === 'string' && item.trim().length > 0);
+  return strings.length > 0 ? strings : undefined;
+}
+
+function pickGraphData(record: Record<string, unknown>, key: string): Array<Record<string, unknown>> | undefined {
+  const value = record[key];
+  if (!Array.isArray(value)) return undefined;
+  const rows = value.filter((item): item is Record<string, unknown> => isRecord(item));
+  return rows.length === value.length ? rows : undefined;
+}
+
+function pickAggregate(record: Record<string, unknown>, key: string): GraphNodeInput['aggregate'] | undefined {
+  const value = record[key];
+  return value === 'sum' || value === 'count' || value === 'avg' ? value : undefined;
+}
+
+function isJsonRenderSpecLike(value: unknown): boolean {
+  return isRecord(value) && typeof value.root === 'string' && isRecord(value.elements);
+}
+
+function isGraphPayloadLike(value: unknown): value is Record<string, unknown> {
+  return isRecord(value) && !isJsonRenderSpecLike(value) && (
+    Array.isArray(value.data) || typeof value.graphType === 'string'
+  );
+}
+
+function hasGraphUpdateFields(input: Record<string, unknown>): boolean {
+  return input.graphType !== undefined ||
+    input.type !== undefined ||
+    Array.isArray(input.data) ||
+    input.xKey !== undefined ||
+    input.yKey !== undefined ||
+    input.zKey !== undefined ||
+    input.nameKey !== undefined ||
+    input.valueKey !== undefined ||
+    input.axisKey !== undefined ||
+    input.metrics !== undefined ||
+    input.series !== undefined ||
+    input.barKey !== undefined ||
+    input.lineKey !== undefined ||
+    input.aggregate !== undefined ||
+    input.color !== undefined ||
+    input.barColor !== undefined ||
+    input.lineColor !== undefined ||
+    input.chartHeight !== undefined;
+}
+
+function graphUpdateInput(input: CanvasStructuredNodeUpdateInput): CanvasGraphNodeUpdateInput {
+  const data = pickGraphData(input as Record<string, unknown>, 'data');
+  const {
+    data: _data,
+    content: _content,
+    arrangeLocked: _arrangeLocked,
+    chartHeight,
+    ...graphFields
+  } = input;
+  return {
+    ...graphFields,
+    ...(data ? { data } : {}),
+    ...(typeof chartHeight === 'number' ? { height: chartHeight } : {}),
+  };
+}
+
+function mergeNodeDataFields(
+  base: Record<string, unknown>,
+  input: CanvasStructuredNodeUpdateInput,
+): Record<string, unknown> {
+  return {
+    ...base,
+    ...(isRecord(input.data) ? input.data : {}),
+    ...(typeof input.arrangeLocked === 'boolean' ? { arrangeLocked: input.arrangeLocked } : {}),
+  };
+}
+
+export function hasStructuredNodeUpdateFields(input: Record<string, unknown>): boolean {
+  return input.spec !== undefined || hasGraphUpdateFields(input);
+}
+
+export function buildStructuredNodeUpdate(
+  node: CanvasNodeState,
+  input: CanvasStructuredNodeUpdateInput,
+): { data: Record<string, unknown> } {
+  const inputRecord = input as Record<string, unknown>;
+  const hasSpec = inputRecord.spec !== undefined;
+  const hasGraphFields = hasGraphUpdateFields(inputRecord);
+
+  if (node.type === 'json-render') {
+    if (hasGraphFields) {
+      throw new Error(`Graph update fields can only be used with graph nodes, not ${node.type} nodes.`);
+    }
+    if (!hasSpec) {
+      throw new Error('json-render structured updates require a spec.');
+    }
+    return {
+      data: mergeNodeDataFields(buildJsonRenderNodeUpdate(node, {
+        ...(typeof input.title === 'string' ? { title: input.title } : {}),
+        spec: input.spec,
+      }).data, input),
+    };
+  }
+
+  if (node.type === 'graph') {
+    return {
+      data: mergeNodeDataFields(buildGraphNodeUpdate(node, graphUpdateInput(input)).data, input),
+    };
+  }
+
+  throw new Error(`Structured spec and graph updates can only be used with json-render or graph nodes, not ${node.type} nodes.`);
+}
+
+function graphConfigToInput(config: Record<string, unknown>, fallbackTitle: string): GraphNodeInput | null {
+  const data = pickGraphData(config, 'data');
+  if (!data) return null;
+  return {
+    title: pickString(config, 'title') ?? fallbackTitle,
+    graphType: pickString(config, 'graphType') ?? 'line',
+    data,
+    ...(pickString(config, 'xKey') ? { xKey: pickString(config, 'xKey') } : {}),
+    ...(pickString(config, 'yKey') ? { yKey: pickString(config, 'yKey') } : {}),
+    ...(pickString(config, 'zKey') ? { zKey: pickString(config, 'zKey') } : {}),
+    ...(pickString(config, 'nameKey') ? { nameKey: pickString(config, 'nameKey') } : {}),
+    ...(pickString(config, 'valueKey') ? { valueKey: pickString(config, 'valueKey') } : {}),
+    ...(pickString(config, 'axisKey') ? { axisKey: pickString(config, 'axisKey') } : {}),
+    ...(pickStringArray(config, 'metrics') ? { metrics: pickStringArray(config, 'metrics') } : {}),
+    ...(pickStringArray(config, 'series') ? { series: pickStringArray(config, 'series') } : {}),
+    ...(pickString(config, 'barKey') ? { barKey: pickString(config, 'barKey') } : {}),
+    ...(pickString(config, 'lineKey') ? { lineKey: pickString(config, 'lineKey') } : {}),
+    ...(pickAggregate(config, 'aggregate') ? { aggregate: pickAggregate(config, 'aggregate') } : {}),
+    ...(pickString(config, 'color') ? { color: pickString(config, 'color') } : {}),
+    ...(pickString(config, 'barColor') ? { barColor: pickString(config, 'barColor') } : {}),
+    ...(pickString(config, 'lineColor') ? { lineColor: pickString(config, 'lineColor') } : {}),
+    ...(pickNumber(config, 'height') !== undefined ? { height: pickNumber(config, 'height') } : {}),
+  };
+}
+
+function mergeGraphInput(source: Record<string, unknown>, fallback: GraphNodeInput | null): GraphNodeInput {
+  const data = pickGraphData(source, 'data') ?? fallback?.data;
+  if (!data) throw new Error('Graph update requires a data array, either in the update payload or the existing graphConfig.');
+  return {
+    title: pickString(source, 'title') ?? fallback?.title ?? 'Graph',
+    graphType: pickString(source, 'graphType') ?? pickString(source, 'type') ?? fallback?.graphType ?? 'line',
+    data,
+    ...((pickString(source, 'xKey') ?? fallback?.xKey) ? { xKey: pickString(source, 'xKey') ?? fallback?.xKey } : {}),
+    ...((pickString(source, 'yKey') ?? fallback?.yKey) ? { yKey: pickString(source, 'yKey') ?? fallback?.yKey } : {}),
+    ...((pickString(source, 'zKey') ?? fallback?.zKey) ? { zKey: pickString(source, 'zKey') ?? fallback?.zKey } : {}),
+    ...((pickString(source, 'nameKey') ?? fallback?.nameKey) ? { nameKey: pickString(source, 'nameKey') ?? fallback?.nameKey } : {}),
+    ...((pickString(source, 'valueKey') ?? fallback?.valueKey) ? { valueKey: pickString(source, 'valueKey') ?? fallback?.valueKey } : {}),
+    ...((pickString(source, 'axisKey') ?? fallback?.axisKey) ? { axisKey: pickString(source, 'axisKey') ?? fallback?.axisKey } : {}),
+    ...((pickStringArray(source, 'metrics') ?? fallback?.metrics) ? { metrics: pickStringArray(source, 'metrics') ?? fallback?.metrics } : {}),
+    ...((pickStringArray(source, 'series') ?? fallback?.series) ? { series: pickStringArray(source, 'series') ?? fallback?.series } : {}),
+    ...((pickString(source, 'barKey') ?? fallback?.barKey) ? { barKey: pickString(source, 'barKey') ?? fallback?.barKey } : {}),
+    ...((pickString(source, 'lineKey') ?? fallback?.lineKey) ? { lineKey: pickString(source, 'lineKey') ?? fallback?.lineKey } : {}),
+    ...((pickAggregate(source, 'aggregate') ?? fallback?.aggregate) ? { aggregate: pickAggregate(source, 'aggregate') ?? fallback?.aggregate } : {}),
+    ...((pickString(source, 'color') ?? fallback?.color) ? { color: pickString(source, 'color') ?? fallback?.color } : {}),
+    ...((pickString(source, 'barColor') ?? fallback?.barColor) ? { barColor: pickString(source, 'barColor') ?? fallback?.barColor } : {}),
+    ...((pickString(source, 'lineColor') ?? fallback?.lineColor) ? { lineColor: pickString(source, 'lineColor') ?? fallback?.lineColor } : {}),
+    ...((pickNumber(source, 'height') ?? fallback?.height) !== undefined ? { height: pickNumber(source, 'height') ?? fallback?.height } : {}),
+  };
+}
+
+export function buildJsonRenderNodeUpdate(
+  node: CanvasNodeState,
+  input: { title?: string; spec: unknown },
+): { data: Record<string, unknown>; spec: JsonRenderSpec } {
+  if (node.type !== 'json-render') throw new Error(`Node "${node.id}" is not a json-render node.`);
+  const spec = normalizeAndValidateJsonRenderSpec(input.spec);
+  const title = input.title?.trim() || inferJsonRenderNodeTitle(spec);
+  return {
+    spec,
+    data: {
+      ...node.data,
+      ...createJsonRenderNodeData(node.id, title, spec, { viewerType: 'json-render' }),
+    },
+  };
+}
+
+export function buildGraphNodeUpdate(
+  node: CanvasNodeState,
+  input: CanvasGraphNodeUpdateInput,
+): { data: Record<string, unknown>; spec: JsonRenderSpec; graphConfig: Record<string, unknown> } {
+  if (node.type !== 'graph') throw new Error(`Node "${node.id}" is not a graph node.`);
+  const currentConfig = isRecord(node.data.graphConfig) ? node.data.graphConfig : {};
+  const fallbackTitle = typeof node.data.title === 'string' ? node.data.title : 'Graph';
+  const fallback = graphConfigToInput(currentConfig, fallbackTitle);
+  const source = isGraphPayloadLike(input.spec)
+    ? input.spec
+    : Object.fromEntries(
+        Object.entries(input).filter(([key, value]) => key !== 'spec' && value !== undefined),
+      );
+
+  if (input.spec !== undefined && !isGraphPayloadLike(input.spec)) {
+    const spec = normalizeAndValidateJsonRenderSpec(input.spec);
+    const title = input.title?.trim() || fallbackTitle;
+    return {
+      spec,
+      graphConfig: currentConfig,
+      data: {
+        ...node.data,
+        ...createJsonRenderNodeData(node.id, title, spec, {
+          viewerType: 'graph',
+          graphConfig: currentConfig,
+        }),
+      },
+    };
+  }
+
+  const graphInput = mergeGraphInput(source, fallback);
+  const spec = buildGraphSpec(graphInput);
+  const graphConfig = buildGraphConfig(graphInput);
+  const title = graphInput.title?.trim() || 'Graph';
+  return {
+    spec,
+    graphConfig,
+    data: {
+      ...node.data,
+      ...createJsonRenderNodeData(node.id, title, spec, {
+        viewerType: 'graph',
+        graphConfig,
+      }),
+    },
+  };
+}
+
 function getStoredExcalidrawCheckpointId(node: CanvasNodeState): string | null {
   const appCheckpoint = isRecord(node.data.appCheckpoint) ? node.data.appCheckpoint : null;
   const checkpointId = appCheckpoint?.id;
@@ -1000,7 +1269,7 @@ export function createCanvasJsonRenderNode(
     collapsed: false,
     pinned: false,
     dockPosition: null,
-    data: createJsonRenderNodeData(id, input.title, spec, {
+    data: createJsonRenderNodeData(id, input.title?.trim() || inferJsonRenderNodeTitle(spec), spec, {
       viewerType: 'json-render',
     }),
   };
@@ -1032,26 +1301,7 @@ export function createCanvasGraphNode(
     dockPosition: null,
     data: createJsonRenderNodeData(id, title, spec, {
       viewerType: 'graph',
-      graphConfig: {
-        title,
-        graphType: input.graphType,
-        data: input.data,
-        ...(input.xKey ? { xKey: input.xKey } : {}),
-        ...(input.yKey ? { yKey: input.yKey } : {}),
-        ...(input.zKey ? { zKey: input.zKey } : {}),
-        ...(input.nameKey ? { nameKey: input.nameKey } : {}),
-        ...(input.valueKey ? { valueKey: input.valueKey } : {}),
-        ...(input.axisKey ? { axisKey: input.axisKey } : {}),
-        ...(input.metrics?.length ? { metrics: input.metrics } : {}),
-        ...(input.series?.length ? { series: input.series } : {}),
-        ...(input.barKey ? { barKey: input.barKey } : {}),
-        ...(input.lineKey ? { lineKey: input.lineKey } : {}),
-        ...(input.aggregate ? { aggregate: input.aggregate } : {}),
-        ...(input.color ? { color: input.color } : {}),
-        ...(input.barColor ? { barColor: input.barColor } : {}),
-        ...(input.lineColor ? { lineColor: input.lineColor } : {}),
-        ...(typeof input.height === 'number' ? { height: input.height } : {}),
-      },
+      graphConfig: buildGraphConfig(input),
     }),
   };
 
@@ -1059,6 +1309,46 @@ export function createCanvasGraphNode(
   return { id, url: String(node.data.url), spec, node };
 }
 
+export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitViewResult {
+  const width = positiveNumber(options.width, 1440);
+  const height = positiveNumber(options.height, 900);
+  const padding = positiveNumber(options.padding, 60);
+  const maxScale = positiveNumber(options.maxScale, 1);
+  const nodeIdFilter = options.nodeIds && options.nodeIds.length > 0 ? new Set(options.nodeIds) : null;
+  const targetNodes = canvasState.getLayout().nodes.filter((node) => !nodeIdFilter || nodeIdFilter.has(node.id));
+
+  if (targetNodes.length === 0) {
+    const viewport = canvasState.viewport;
+    return { ok: true, viewport, nodeCount: 0, bounds: null };
+  }
+
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  for (const node of targetNodes) {
+    minX = Math.min(minX, node.position.x);
+    minY = Math.min(minY, node.position.y);
+    maxX = Math.max(maxX, node.position.x + node.size.width);
+    maxY = Math.max(maxY, node.position.y + node.size.height);
+  }
+
+  const bounds = { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+  const worldWidth = Math.max(1, bounds.width + padding * 2);
+  const worldHeight = Math.max(1, bounds.height + padding * 2);
+  const scale = Math.min(maxScale, width / worldWidth, height / worldHeight);
+  const centerX = minX + bounds.width / 2;
+  const centerY = minY + bounds.height / 2;
+  const viewport = {
+    x: width / 2 - centerX * scale,
+    y: height / 2 - centerY * scale,
+    scale,
+  };
+
+  canvasState.setViewport(viewport);
+  return { ok: true, viewport: canvasState.viewport, nodeCount: targetNodes.length, bounds };
+}
+
 function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === 'object' && !Array.isArray(value);
 }

package/src/server/canvas-schema.ts

@@ -171,7 +171,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/node',
     mcpTool: 'canvas_add_node',
     fields: [
-      { name: 'content', type: 'string', required: true, description: 'Image path, URL, or data URI.' },
+      { 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.' },
@@ -280,8 +280,8 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     endpoint: '/api/canvas/json-render',
     mcpTool: 'canvas_add_json_render_node',
     fields: [
-      { name: 'title', type: 'string', required: true, description: 'Rendered node title.' },
-      { name: 'spec', type: 'JsonRenderSpec', required: true, description: 'Complete json-render spec.' },
+      { 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.' },
@@ -439,6 +439,8 @@ export function describeCanvasSchema(): {
         'canvas_build_web_artifact',
         'canvas_open_mcp_app',
         'canvas_create_group',
+        'canvas_update_node',
+        'canvas_fit_view',
         'canvas_describe_schema',
         'canvas_validate_spec',
       ],