pmx-canvas 0.4.4 → 0.4.6

package/src/server/index.ts

@@ -542,15 +542,22 @@ export class PmxCanvas extends EventEmitter {
       nodeIds?: string[];
       data?: Record<string, unknown> | null;
     },
-    options?: { source?: PmxAxSource },
+    options?: { source?: PmxAxSource; agentId?: string | null },
   ): PmxAxEvent {
-    const event = canvasState.recordAxEvent(input, { source: options?.source ?? 'sdk' });
+    const event = canvasState.recordAxEvent(input, { source: options?.source ?? 'sdk', agentId: options?.agentId });
     emitPrimaryWorkbenchEvent('ax-event-created', { event });
     return event;
   }
 
-  sendSteering(message: string, options?: { source?: PmxAxSource }): PmxAxSteeringMessage {
-    const steering = canvasState.recordSteeringMessage(message, { source: options?.source ?? 'sdk' });
+  sendSteering(
+    message: string,
+    options?: { source?: PmxAxSource; agentId?: string | null; target?: string | null },
+  ): PmxAxSteeringMessage {
+    const steering = canvasState.recordSteeringMessage(message, {
+      source: options?.source ?? 'sdk',
+      agentId: options?.agentId,
+      target: options?.target,
+    });
     emitPrimaryWorkbenchEvent('ax-event-created', { steering });
     return steering;
   }
@@ -604,7 +611,13 @@ export class PmxCanvas extends EventEmitter {
   }
 
   addWorkItem(
-    input: { title: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    input: {
+      title: string;
+      status?: PmxAxWorkItemStatus;
+      detail?: string | null;
+      nodeIds?: string[];
+      agentId?: string | null;
+    },
     options?: { source?: PmxAxSource },
   ): PmxAxWorkItem {
     const workItem = canvasState.addWorkItem(input, { source: options?.source ?? 'sdk' });
@@ -614,7 +627,13 @@ export class PmxCanvas extends EventEmitter {
 
   updateWorkItem(
     id: string,
-    patch: { title?: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    patch: {
+      title?: string;
+      status?: PmxAxWorkItemStatus;
+      detail?: string | null;
+      nodeIds?: string[];
+      agentId?: string | null;
+    },
     options?: { source?: PmxAxSource },
   ): PmxAxWorkItem | null {
     const workItem = canvasState.updateWorkItem(id, patch, { source: options?.source ?? 'sdk' });

package/src/server/intent-registry.ts

@@ -50,6 +50,7 @@ const intentSignalSchema = z.looseObject({
   seq: z.number().int().min(0).max(9999).optional(),
   ttlMs: z.number().positive().max(MAX_INTENT_TTL_MS).optional(),
   source: z.string().max(60).optional(),
+  auto: z.boolean().optional(),
 });
 
 const intentUpdateSchema = z.looseObject({
@@ -146,6 +147,7 @@ export class IntentRegistry {
       ...(typeof input.confidence === 'number' ? { confidence: input.confidence } : {}),
       ...(typeof input.seq === 'number' ? { seq: input.seq } : {}),
       ...(input.source ? { source: input.source } : {}),
+      ...(input.auto === true ? { auto: true } : {}),
       createdAt: existing?.createdAt ?? now,
       expiresAt: now + ttl,
     };

package/src/server/operations/composites.ts

@@ -156,14 +156,15 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_render',
     description:
-      'Spec-driven content: discover the schema, validate a payload, or create a json-render / graph node. Action "describe-schema" returns the json-render component catalog + create schemas; "validate" checks a spec or graph payload without creating a node; "add-json-render" creates a json-render node from a complete spec; "stream-json-render" progressively builds one from SpecStream patches (omit nodeId to create, pass it back to append, done=true to finish); "add-graph" creates a chart node (line, bar, pie, area, scatter, radar, stacked-bar, composed, sparkline, dot-plot, bullet, slopegraph).',
-    actionSummary: 'describe-schema | validate | add-json-render | stream-json-render | add-graph',
+      'Spec-driven content: discover the schema, validate a payload, or create a json-render / graph node. Action "describe-schema" returns the json-render component catalog + create schemas; "validate" checks a spec or graph payload without creating a node; "add-json-render" creates a json-render node from a complete spec; "stream-json-render" progressively builds one from SpecStream patches (omit nodeId to create, pass it back to append, done=true to finish); "add-graph" creates a chart node (line, bar, pie, area, scatter, radar, stacked-bar, composed, sparkline, dot-plot, bullet, slopegraph); "workboard" materializes a live AX work-item board (a json-render node with a column per status) that auto-refreshes whenever work items change — idempotent, rebuilding the existing board in place.',
+    actionSummary: 'describe-schema | validate | add-json-render | stream-json-render | add-graph | workboard',
     actions: {
       'describe-schema': 'schema.describe',
       validate: 'spec.validate',
       'add-json-render': 'jsonrender.add',
       'stream-json-render': 'jsonrender.stream',
       'add-graph': 'graph.add',
+      workboard: 'render.workboard',
     },
   },
   {

package/src/server/operations/http.ts

@@ -84,7 +84,11 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
       const input = route.readInput
         ? await route.readInput(req, params, url)
         : await defaultReadInput(req, params, url);
-      const result = await executeOperation(op.name, input);
+      // The workbench marks its own HTTP calls: a human dragging/editing in
+      // the browser is not agent activity, so it never synthesizes an
+      // auto-ghost. Everything else (CLI, scripts, adapters) counts as agent.
+      const fromWorkbench = req.headers.get('x-pmx-workbench') === '1';
+      const result = await executeOperation(op.name, input, { suppressAutoGhost: fromWorkbench });
       return responseJson(result, route.status ? route.status(result) : 200);
     } catch (error) {
       if (error instanceof OperationError) {

package/src/server/operations/ops/ax-shared.ts

@@ -12,11 +12,30 @@ import { z } from 'zod';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { PmxAxSource } from '../../ax-state.js';
 
-export const AX_SOURCES = ['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'] as const;
+export const AX_SOURCES = [
+  'agent',
+  'amp',
+  'api',
+  'browser',
+  'cli',
+  'codex',
+  'copilot',
+  'mcp',
+  'sdk',
+  'system',
+] as const;
 
 /** Zod schema for the optional `source` field shared by AX MCP tool shapes. */
 export const AX_SOURCE_SHAPE = z.enum(AX_SOURCES).optional().describe('Optional host/source label. Defaults to mcp.');
 
+/** Zod schema for the optional `agentId` field shared by AX MCP tool shapes. */
+export const AX_AGENT_ID_SHAPE = z
+  .string()
+  .min(1)
+  .max(80)
+  .optional()
+  .describe('Per-agent identity within the host (orchestration); source stays the host label.');
+
 /** An absent or unrecognized source falls back to the per-surface default. */
 export function normalizeAxSource(value: unknown, fallback: PmxAxSource): PmxAxSource {
   return (AX_SOURCES as readonly string[]).includes(value as string) ? (value as PmxAxSource) : fallback;

package/src/server/operations/ops/ax-state.ts

@@ -27,7 +27,7 @@ import { buildCanvasAxContext } from '../../ax-context.js';
 import type { PmxAxPolicy } from '../../ax-state.js';
 import { defineOperation, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
-import { normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
+import { AX_SOURCES, normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
 
 // ── ax.get (canvas_get_ax) ────────────────────────────────────
 
@@ -112,7 +112,7 @@ const axFocusSetOperation = defineOperation<z.infer<typeof axFocusSetSchema>, Re
     extraShape: {
       nodeIds: z.array(z.string()).describe('Node IDs to place in the AX focus field. Missing nodes are ignored.'),
       source: z
-        .enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .enum(AX_SOURCES)
         .optional()
         .describe(
           'Optional host/source label for adapter-originated focus. Defaults to mcp. Use codex from the Codex app adapter.',
@@ -167,7 +167,7 @@ const axPolicySetOperation = defineOperation<z.infer<typeof axPolicySetSchema>,
         })
         .optional(),
       prompt: z.object({ systemAppend: z.string().optional(), mode: z.string().optional() }).optional(),
-      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']).optional(),
+      source: z.enum(AX_SOURCES).optional(),
     },
     // Legacy MCP tool forwarded only the present tools/prompt fields (source split out).
     buildInput: (input) => ({
@@ -236,10 +236,7 @@ const axHostCapabilityReportOperation = defineOperation<
       files: z.boolean().optional(),
       uiPrompts: z.boolean().optional(),
       raw: z.record(z.string(), z.unknown()).optional().describe('Optional raw capability payload for diagnostics.'),
-      source: z
-        .enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
-        .optional()
-        .describe('Optional host/source label. Defaults to mcp.'),
+      source: z.enum(AX_SOURCES).optional().describe('Optional host/source label. Defaults to mcp.'),
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: (result) => {

package/src/server/operations/ops/ax-timeline.ts

@@ -51,7 +51,13 @@ import { buildPendingAxActivity, isAxEventKind, isAxEvidenceKind } from '../../a
 import type { PmxAxEventKind, PmxAxEvidenceKind } from '../../ax-state.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
-import { AX_SOURCE_SHAPE, axJsonResult, normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
+import {
+  AX_AGENT_ID_SHAPE,
+  AX_SOURCE_SHAPE,
+  axJsonResult,
+  normalizeAxNodeIds,
+  normalizeAxSource,
+} from './ax-shared.js';
 
 const AX_EVENT_KINDS = [
   'prompt',
@@ -73,6 +79,7 @@ const axEventRecordShape = {
   nodeIds: z.unknown().optional().describe('Optional node IDs this event relates to.'),
   data: z.unknown().optional().describe('Optional structured data payload.'),
   source: z.unknown().optional().describe('Optional host/source label. Defaults to mcp.'),
+  agentId: z.unknown().optional().describe('Optional per-agent identity within the host.'),
 };
 
 const axEventRecordSchema = z.looseObject(axEventRecordShape);
@@ -97,6 +104,7 @@ const axEventRecordOperation = defineOperation<z.infer<typeof axEventRecordSchem
       nodeIds: z.array(z.string()).optional().describe('Optional node IDs this event relates to.'),
       data: z.record(z.string(), z.unknown()).optional().describe('Optional structured data payload.'),
       source: AX_SOURCE_SHAPE,
+      agentId: AX_AGENT_ID_SHAPE,
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: axJsonResult,
@@ -113,7 +121,10 @@ const axEventRecordOperation = defineOperation<z.infer<typeof axEventRecordSchem
         nodeIds: normalizeAxNodeIds(input.nodeIds),
         data: isRecord(input.data) ? input.data : null,
       },
-      { source: normalizeAxSource(input.source, 'api') },
+      {
+        source: normalizeAxSource(input.source, 'api'),
+        ...(typeof input.agentId === 'string' ? { agentId: input.agentId } : {}),
+      },
     );
     ctx.emit('ax-event-created', { event });
     return { ok: true, event } as unknown as Record<string, unknown>;
@@ -184,6 +195,8 @@ const axEvidenceAddOperation = defineOperation<z.infer<typeof axEvidenceAddSchem
 const axSteerShape = {
   message: z.unknown().optional().describe('The steering instruction to deliver to the active agent session.'),
   source: z.unknown().optional().describe('Optional host/source label. Defaults to mcp.'),
+  agentId: z.unknown().optional().describe('Optional per-agent identity within the host.'),
+  target: z.unknown().optional().describe('Optional agentId/consumer this steer is addressed to. Omit to broadcast.'),
 };
 
 const axSteerSchema = z.looseObject(axSteerShape);
@@ -204,6 +217,13 @@ const axSteerOperation = defineOperation<z.infer<typeof axSteerSchema>, Record<s
     extraShape: {
       message: z.string().describe('The steering instruction to deliver to the active agent session.'),
       source: AX_SOURCE_SHAPE,
+      agentId: AX_AGENT_ID_SHAPE,
+      target: z
+        .string()
+        .min(1)
+        .max(80)
+        .optional()
+        .describe('The agentId/consumer this steer is addressed to. Omit to broadcast to all consumers.'),
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: axJsonResult,
@@ -214,6 +234,8 @@ const axSteerOperation = defineOperation<z.infer<typeof axSteerSchema>, Record<s
     }
     const steering = canvasState.recordSteeringMessage(input.message, {
       source: normalizeAxSource(input.source, 'api'),
+      ...(typeof input.agentId === 'string' ? { agentId: input.agentId } : {}),
+      ...(typeof input.target === 'string' ? { target: input.target } : {}),
     });
     ctx.emit('ax-event-created', { steering });
     return { ok: true, steering } as unknown as Record<string, unknown>;
@@ -328,7 +350,8 @@ const axDeliveryMarkOperation = defineOperation<z.infer<typeof axDeliveryMarkSch
   },
   mcp: {
     toolName: 'canvas_mark_ax_delivery',
-    description: 'Mark a PMX AX steering message as delivered so it is not handed out again.',
+    description:
+      'Mark a PMX AX steering message as delivered so it is not handed out again. Compare-and-set: `delivered:true` only on the actual undelivered→delivered transition — a false means the id was unknown OR another consumer already marked it, so do NOT treat the message as your delivery.',
     extraShape: {
       id: z.string().describe('The steering message id to mark delivered.'),
     },

package/src/server/operations/ops/ax-work.ts

@@ -57,7 +57,14 @@ import type {
 } from '../../ax-state.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
-import { AX_SOURCE_SHAPE, AX_SOURCES, axJsonResult, normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
+import {
+  AX_AGENT_ID_SHAPE,
+  AX_SOURCE_SHAPE,
+  AX_SOURCES,
+  axJsonResult,
+  normalizeAxNodeIds,
+  normalizeAxSource,
+} from './ax-shared.js';
 
 const AX_WORK_ITEM_STATUSES = new Set(['todo', 'in-progress', 'blocked', 'done', 'cancelled']);
 function normalizeAxWorkItemStatus(value: unknown): PmxAxWorkItemStatus | undefined {
@@ -98,6 +105,7 @@ const axWorkCreateShape = {
   detail: z.unknown().optional().describe('Optional longer description.'),
   nodeIds: z.unknown().optional().describe('Optional node IDs this work item is tied to.'),
   source: z.unknown().optional().describe('Optional host/source label. Defaults to mcp.'),
+  agentId: z.unknown().optional().describe('Optional per-agent identity within the host.'),
 };
 
 const axWorkCreateSchema = z.looseObject(axWorkCreateShape);
@@ -124,6 +132,7 @@ const axWorkCreateOperation = defineOperation<z.infer<typeof axWorkCreateSchema>
       detail: z.string().optional().describe('Optional longer description.'),
       nodeIds: z.array(z.string()).optional().describe('Optional node IDs this work item is tied to.'),
       source: AX_SOURCE_SHAPE,
+      agentId: AX_AGENT_ID_SHAPE,
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: axJsonResult,
@@ -146,10 +155,18 @@ const axWorkCreateOperation = defineOperation<z.infer<typeof axWorkCreateSchema>
         ...(status ? { status } : {}),
         ...(typeof input.detail === 'string' ? { detail: input.detail } : {}),
         ...(Array.isArray(input.nodeIds) ? { nodeIds: normalizeAxNodeIds(input.nodeIds) } : {}),
+        ...(typeof input.agentId === 'string' ? { agentId: input.agentId } : {}),
       },
       { source: normalizeAxSource(input.source, 'api') },
     );
     ctx.emit('ax-state-changed', { workItem });
+    // The status mirror writes data.axWorkStatus onto linked nodes, but this
+    // op is mutates:false (AX writes must not spam layout frames) — so emit
+    // the ONE layout frame ourselves when links exist, or open boards never
+    // see the chip until an unrelated mutation happens to refresh them.
+    if (workItem.nodeIds.length > 0) {
+      ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    }
     return { ok: true, workItem } as unknown as Record<string, unknown>;
   },
 });
@@ -163,6 +180,7 @@ const axWorkUpdateShape = {
   detail: z.unknown().optional().describe('New detail text.'),
   nodeIds: z.unknown().optional().describe('Replacement node IDs.'),
   source: z.unknown().optional().describe('Optional host/source label. Defaults to mcp.'),
+  agentId: z.unknown().optional().describe('Optional per-agent identity within the host.'),
 };
 
 const axWorkUpdateSchema = z.looseObject(axWorkUpdateShape);
@@ -187,6 +205,7 @@ const axWorkUpdateOperation = defineOperation<z.infer<typeof axWorkUpdateSchema>
       detail: z.string().optional().describe('New detail text.'),
       nodeIds: z.array(z.string()).optional().describe('Replacement node IDs.'),
       source: AX_SOURCE_SHAPE,
+      agentId: AX_AGENT_ID_SHAPE,
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: axJsonResult,
@@ -207,11 +226,18 @@ const axWorkUpdateOperation = defineOperation<z.infer<typeof axWorkUpdateSchema>
         ...(status ? { status } : {}),
         ...(typeof input.detail === 'string' || input.detail === null ? { detail: input.detail as string | null } : {}),
         ...(Array.isArray(input.nodeIds) ? { nodeIds: normalizeAxNodeIds(input.nodeIds) } : {}),
+        ...(typeof input.agentId === 'string' ? { agentId: input.agentId } : {}),
       },
       { source: normalizeAxSource(input.source, 'api') },
     );
     if (!workItem) throw new OperationError('work item not found.', 404);
     ctx.emit('ax-state-changed', { workItem });
+    // Same as create: the mirror touched node data only if the patch carried
+    // status or nodeIds — emit the layout frame those chips need (this op is
+    // mutates:false, so nothing else will).
+    if (input.status !== undefined || input.nodeIds !== undefined) {
+      ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    }
     return { ok: true, workItem } as unknown as Record<string, unknown>;
   },
 });

package/src/server/operations/ops/batch.ts

@@ -238,7 +238,9 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
         continue;
       }
       const dispatch = resolveDispatch(operation.op, args);
-      const raw = await executeOperation(dispatch.name, dispatch.args);
+      // Batch churn is exempt from auto-ghosts (matches the skill's explicit
+      // ghost-cursor exemption for batch operations).
+      const raw = await executeOperation(dispatch.name, dispatch.args, { suppressAutoGhost: true });
       const result = shapeBatchEntry(operation.op, raw);
       results.push(result);
       if (typeof operation.assign === 'string' && operation.assign.trim().length > 0) {
@@ -373,6 +375,14 @@ const batchOperation = defineOperation<z.infer<typeof batchSchema>, BatchEnvelop
     // ctx.emit). After the loop completes, emit ONE final canvas-layout-update.
     const envelope = await runWithSuppressedEmits(() => runBatch(operations));
     ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    // The suppression window also swallows the pins op's context-pins-changed
+    // frame, leaving the client's pin state (menus, indicators) stale until
+    // reload (0.4.5 report Finding X). If the batch touched pins, follow the
+    // layout frame with ONE final pins frame carrying the end state.
+    if (operations.some((entry) => entry.op.startsWith('pin.'))) {
+      const nodeIds = Array.from(canvasState.contextPinnedNodeIds);
+      ctx.emit('context-pins-changed', { count: nodeIds.length, nodeIds });
+    }
     return envelope;
   },
 });

package/src/server/operations/ops/json-render.ts

@@ -39,6 +39,7 @@ import {
 } from '../../canvas-operations.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from '../../canvas-schema.js';
 import { isHtmlPrimitiveKind } from '../../html-primitives.js';
+import { renderWorkboard } from '../../workboard.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import {
   buildNodeResponse,
@@ -311,6 +312,48 @@ const jsonRenderStreamOperation = defineOperation<z.infer<typeof jsonRenderStrea
   // Wire shape is `{ id, url, ok, applied, ... }` — handler output verbatim.
 });
 
+// ── render.workboard ──────────────────────────────────────────
+
+const workboardRenderShape = {
+  intentId: z
+    .string()
+    .optional()
+    .catch(undefined)
+    .describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
+  x: z.number().optional().catch(undefined).describe('Optional X position (only used when creating the board)'),
+  y: z.number().optional().catch(undefined).describe('Optional Y position (only used when creating the board)'),
+};
+
+const workboardRenderSchema = z.looseObject(workboardRenderShape);
+
+const workboardRenderOperation = defineOperation<
+  z.infer<typeof workboardRenderSchema>,
+  ReturnType<typeof renderWorkboard>
+>({
+  name: 'render.workboard',
+  mutates: true,
+  input: workboardRenderSchema,
+  inputShape: workboardRenderShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/workboard',
+  },
+  mcp: {
+    toolName: 'canvas_render_workboard',
+    description:
+      'Materialize a live work-item board: a json-render node with one column per status (todo → in-progress → blocked → done → cancelled) showing every AX work item as a card (title, agentId chip, detail). Idempotent: rebuilds the existing board node in place when one exists, otherwise creates it. The board auto-refreshes whenever work items change.',
+  },
+  handler: (input) => {
+    const body: Record<string, unknown> = input;
+    const x = pickFiniteNumber(body, 'x');
+    const y = pickFiniteNumber(body, 'y');
+    return renderWorkboard({
+      ...(x !== undefined ? { x } : {}),
+      ...(y !== undefined ? { y } : {}),
+    });
+  },
+});
+
 // ── graph.add ─────────────────────────────────────────────────
 
 const graphAddShape = {
@@ -829,6 +872,7 @@ const specValidateOperation = defineOperation<z.infer<typeof specValidateSchema>
 export const jsonRenderOperations: Operation[] = [
   jsonRenderAddOperation,
   jsonRenderStreamOperation,
+  workboardRenderOperation,
   graphAddOperation,
   schemaDescribeOperation,
   specValidateOperation,

package/src/server/operations/ops/nodes.ts

@@ -55,6 +55,8 @@ export const NODE_TYPES = [
   'ledger',
   'trace',
   'file',
+  'diff',
+  'mermaid',
   'image',
   'mcp-app',
   'webpage',
@@ -69,6 +71,15 @@ export function defaultNodeSize(type: string): { width: number; height: number }
   switch (type) {
     case 'html':
       return { width: 720, height: 640 };
+    case 'file':
+      // Code preview needs real width and enough height for the header bar +
+      // a useful snippet — the generic default rendered as a content-less bar
+      // (0.4.4 portal feedback).
+      return { width: 520, height: 360 };
+    case 'diff':
+      return { width: 640, height: 420 };
+    case 'mermaid':
+      return { width: 640, height: 460 };
     case 'markdown':
       return MARKDOWN_NODE_DEFAULT_SIZE;
     case 'mcp-app':
@@ -415,7 +426,16 @@ export function createBasicCanvasNode(
   try {
     const { node, needsCodeGraphRecompute } = addCanvasNode({
       type: type as CanvasNodeState['type'],
-      ...(typeof body.title === 'string' ? { title: body.title } : {}),
+      ...(typeof body.title === 'string'
+        ? { title: body.title }
+        : // Untitled file nodes get the filename — otherwise the title bar
+          // reads as a bare "FILE" chip with nothing identifying the file.
+          type === 'file' && typeof content === 'string' && content.trim()
+          ? // Separator-agnostic: Windows paths use backslashes (0.3.2's
+            // basename fix class — a '/'-only split makes the whole path
+            // the title there).
+            { title: content.trim().split(/[\\/]/).pop() }
+          : {}),
       ...(typeof content === 'string' ? { content } : {}),
       ...(htmlMergedData && Object.keys(htmlMergedData).length > 0 ? { data: htmlMergedData } : {}),
       ...(type === 'trace' && typeof body.toolName === 'string' ? { toolName: body.toolName } : {}),
@@ -769,7 +789,7 @@ const nodeAddOperation = defineOperation<z.infer<typeof nodeAddSchema>, NodeAddR
   mcp: {
     toolName: 'canvas_add_node',
     description:
-      'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, status, context, ledger, trace, file, image, webpage, mcp-app, html, group. Dedicated routes: json-render -> canvas_render {action:"add-json-render"}, graph -> canvas_render {action:"add-graph"}, web-artifact -> canvas_app {action:"build-artifact"}, external apps -> canvas_app {action:"open-mcp-app"}, groups -> canvas_group {action:"create"}. Call canvas_render {action:"describe-schema"} for the full nodeTypeRouting table.',
+      'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, status, context, ledger, trace, file, diff, mermaid, image, webpage, mcp-app, html, group. Dedicated routes: json-render -> canvas_render {action:"add-json-render"}, graph -> canvas_render {action:"add-graph"}, web-artifact -> canvas_app {action:"build-artifact"}, external apps -> canvas_app {action:"open-mcp-app"}, groups -> canvas_group {action:"create"}. Call canvas_render {action:"describe-schema"} for the full nodeTypeRouting table.',
     extraShape: {
       type: z
         .enum([
@@ -779,6 +799,8 @@ const nodeAddOperation = defineOperation<z.infer<typeof nodeAddSchema>, NodeAddR
           'ledger',
           'trace',
           'file',
+          'diff',
+          'mermaid',
           'image',
           'webpage',
           'mcp-app',

package/src/server/operations/ops/viewport.ts

@@ -121,7 +121,14 @@ const focusOperation = defineOperation<z.infer<typeof focusSchema>, Record<strin
     if (!node) throw new OperationError(`Node "${nodeId}" not found.`, 404);
     const noPan = body.noPan === true;
     if (!noPan) {
-      canvasState.setViewport({ x: node.position.x - 100, y: node.position.y - 100 });
+      // The viewport is a SCREEN-space translate: screen = world * scale + v
+      // (CanvasViewport's matrix(scale,0,0,scale,x,y)), the same convention
+      // fitCanvasView and the client's focusNode use. So park the node's
+      // top-left at a fixed screen-space margin — 64/96 screen px, which
+      // clears the 44px floating toolbar at ANY zoom (0.4.5 report Finding Z:
+      // the old world-space margin shrank below the toolbar at low scales).
+      const scale = canvasState.viewport.scale || 1;
+      canvasState.setViewport({ x: 64 - node.position.x * scale, y: 96 - node.position.y * scale });
     } else {
       const maxZ = canvasState.getLayout().nodes.reduce((max, layoutNode) => Math.max(max, layoutNode.zIndex), 0);
       canvasState.updateNode(nodeId, { zIndex: maxZ + 1 });