pmx-canvas 0.6.4 → 0.6.5

package/src/server/index.ts

@@ -1,4 +1,6 @@
 import { EventEmitter } from 'node:events';
+import { derivedTour, type Tour } from '../shared/tour.js';
+export type { Tour, TourStop } from '../shared/tour.js';
 import { agentPresence } from './agent-presence.js';
 import { checkFenceTarget, type FenceTarget } from './scope-fence.js';
 import type { AgentPhase, AgentPresence, AgentPresenceSnapshot } from '../shared/agent-presence.js';
@@ -547,6 +549,16 @@ export class PmxCanvas extends EventEmitter {
     );
   }
 
+  getTour(): Tour {
+    return canvasState.getTour() ?? derivedTour(canvasState.getLayout().nodes);
+  }
+
+  setTour(tour: Tour | null): void {
+    assertInsideFence('tour.set', { boardWide: true });
+    canvasState.setTour(tour);
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  }
+
   clear(): void {
     assertInsideFence('canvas.clear', { boardWide: true });
     for (const node of canvasState.getLayout().nodes) {

package/src/server/operations/composites.ts

@@ -203,8 +203,10 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
     toolName: 'canvas_view',
     description:
       'Canvas viewport and layout control. Action "arrange" auto-lays-out nodes (grid/columns/etc.); "focus" pans/zooms the viewport to a node; "fit" zooms to fit all nodes in view; "clear" removes every node and edge from the canvas; "remove-annotation" deletes a human-drawn annotation by id.',
-    actionSummary: 'arrange | focus | fit | clear | remove-annotation',
+    actionSummary: 'arrange | focus | fit | clear | remove-annotation | get-tour | set-tour',
     actions: {
+      'get-tour': 'tour.get',
+      'set-tour': 'tour.set',
       arrange: 'arrange',
       focus: 'node.focus',
       fit: 'view.fit',

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

@@ -32,6 +32,7 @@
  */
 import { z } from 'zod';
 import { canvasState } from '../../canvas-state.js';
+import { describeCreateSize, type CanvasSizeAdjustment } from '../../canvas-operations.js';
 import {
   closeMcpAppSession,
   openMcpApp as openExternalMcpApp,
@@ -75,6 +76,7 @@ export interface OpenMcpAppCoreResult {
   toolCallId: string;
   sessionId: string;
   resourceUri: string;
+  sizeAdjustment?: CanvasSizeAdjustment;
 }
 
 /**
@@ -121,6 +123,7 @@ export async function openMcpAppCore(input: OpenMcpAppCoreInput, ctx: OperationC
   const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
     ? ensureExcalidrawCheckpointId(opened.toolResult, nodeIdSeed)
     : opened.toolResult;
+  const existingNodeIds = new Set(canvasState.getLayout().nodes.map((node) => node.id));
   ctx.emit('ext-app-open', {
     toolCallId,
     nodeId: nodeIdSeed,
@@ -158,6 +161,11 @@ export async function openMcpAppCore(input: OpenMcpAppCoreInput, ctx: OperationC
       getNode: (id) => canvasState.getNode(id),
       listNodes: () => canvasState.getLayout().nodes,
     });
+  const node = nodeId ? canvasState.getNode(nodeId) : undefined;
+  const sizeAdjustment =
+    node && !existingNodeIds.has(node.id)
+      ? describeCreateSize(input.width, input.height, node.size.width, node.size.height, node.size)
+      : undefined;
   return {
     ok: true,
     ...(nodeId ? { id: nodeId } : {}),
@@ -165,6 +173,7 @@ export async function openMcpAppCore(input: OpenMcpAppCoreInput, ctx: OperationC
     toolCallId,
     sessionId: opened.sessionId,
     resourceUri: opened.resourceUri,
+    ...(sizeAdjustment ? { sizeAdjustment } : {}),
   };
 }
 
@@ -388,6 +397,7 @@ function webArtifactEnvelope(result: WebArtifactCanvasBuildResult, includeLogs:
     ...(typeof result.nodeId === 'string' ? { id: result.nodeId } : {}),
     nodeId: result.nodeId,
     url: result.url,
+    ...(result.sizeAdjustment ? { sizeAdjustment: result.sizeAdjustment } : {}),
     metadata: result.metadata,
     logs: result.logs,
     ...(includeLogs ? { stdout: result.stdout, stderr: result.stderr } : {}),

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

@@ -145,7 +145,11 @@ function createInternalBatchNode(args: Record<string, unknown>): Record<string,
     defaultHeight: 200,
   });
 
-  return { ok: true, ...serializeCanvasNodeCompact(created.node) };
+  return {
+    ok: true,
+    ...serializeCanvasNodeCompact(created.node),
+    ...(created.sizeAdjustment ? { sizeAdjustment: created.sizeAdjustment } : {}),
+  };
 }
 
 /**
@@ -165,7 +169,7 @@ function shapeBatchEntry(op: string, result: unknown): Record<string, unknown> {
     const id = typeof body.id === 'string' ? body.id : '';
     const node = id ? canvasState.getNode(id) : undefined;
     const extras: Record<string, unknown> = {};
-    for (const key of ['fetch', 'error', 'url', 'spec']) {
+    for (const key of ['fetch', 'error', 'url', 'spec', 'sizeAdjustment']) {
       if (body[key] !== undefined) extras[key] = body[key];
     }
     if (node) return { ok: true, ...serializeCanvasNodeCompact(node), ...extras };
@@ -183,7 +187,11 @@ function shapeBatchEntry(op: string, result: unknown): Record<string, unknown> {
   if (op === 'group.add') {
     const groupId = typeof body.groupId === 'string' ? body.groupId : '';
     const group = groupId ? canvasState.getNode(groupId) : undefined;
-    return { ok: true, ...(group ? serializeCanvasNode(group) : { id: groupId }) };
+    return {
+      ok: true,
+      ...(group ? serializeCanvasNode(group) : { id: groupId }),
+      ...(body.sizeAdjustment ? { sizeAdjustment: body.sizeAdjustment } : {}),
+    };
   }
 
   // pin.set/add/remove: legacy pushed { ok:true, ...{ count, nodeIds } }; wire shape drops nodeIds.
@@ -305,6 +313,7 @@ function compactBatchValue(value: unknown): unknown {
     'content',
     'position',
     'size',
+    'sizeAdjustment',
     'fetch',
     'error',
     'from',

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

@@ -42,7 +42,7 @@ const groupCreateShape = {
 
 const groupCreateSchema = z.looseObject(groupCreateShape);
 
-const groupCreateOperation = defineOperation<z.infer<typeof groupCreateSchema>, CanvasNodeState>({
+const groupCreateOperation = defineOperation<z.infer<typeof groupCreateSchema>, ReturnType<typeof createCanvasGroup>>({
   name: 'group.create',
   mutates: true,
   input: groupCreateSchema,
@@ -69,7 +69,12 @@ const groupCreateOperation = defineOperation<z.infer<typeof groupCreateSchema>,
     formatResult: (result, input) => {
       const body = isRecord(result) ? result : {};
       const node = body.node as CanvasNodeState | undefined;
-      const payload = node ? createdNodePayloadFromNode(node, input) : { ok: true };
+      const payload = node
+        ? {
+            ...createdNodePayloadFromNode(node, input),
+            ...(body.sizeAdjustment ? { sizeAdjustment: body.sizeAdjustment } : {}),
+          }
+        : { ok: true };
       return { content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }] };
     },
   },
@@ -93,7 +98,7 @@ const groupCreateOperation = defineOperation<z.infer<typeof groupCreateSchema>,
         );
       }
     }
-    const { node } = createCanvasGroup({
+    return createCanvasGroup({
       title,
       childIds,
       color,
@@ -103,9 +108,11 @@ const groupCreateOperation = defineOperation<z.infer<typeof groupCreateSchema>,
       height,
       ...(childLayout ? { childLayout } : {}),
     });
-    return node;
   },
-  serialize: (node) => buildNodeResponse(node),
+  serialize: ({ node, sizeAdjustment }) => ({
+    ...buildNodeResponse(node),
+    ...(sizeAdjustment ? { sizeAdjustment } : {}),
+  }),
 });
 
 // ── group.add ─────────────────────────────────────────────────
@@ -157,9 +164,9 @@ const groupAddOperation = defineOperation<z.infer<typeof groupAddSchema>, Record
     if (!groupId || childIds.length === 0) {
       throw new OperationError('Missing groupId or childIds.');
     }
-    const { ok } = groupCanvasNodes(groupId, childIds, childLayout ? { childLayout } : {});
+    const { ok, sizeAdjustment } = groupCanvasNodes(groupId, childIds, childLayout ? { childLayout } : {});
     if (!ok) throw new OperationError('Group not found or no valid children.');
-    return { ok: true, groupId };
+    return { ok: true, groupId, ...(sizeAdjustment ? { sizeAdjustment } : {}) };
   },
 });
 

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

@@ -36,6 +36,7 @@ import {
   createCanvasGraphNode,
   createCanvasJsonRenderNode,
   createCanvasStreamingJsonRenderNode,
+  type CanvasSizeAdjustment,
 } from '../../canvas-operations.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from '../../canvas-schema.js';
 import { isHtmlPrimitiveKind } from '../../html-primitives.js';
@@ -84,9 +85,13 @@ function structuredNodeToolResult(result: unknown): { content: Array<{ type: 'te
   const body = isRecord(result) ? result : {};
   const node = body.node as CanvasNodeState | undefined;
   const payload = {
-    ...(node ? createdNodePayloadFromNode(node) : { ok: true }),
+    ...(node
+      ? createdNodePayloadFromNode(node, {}, body.sizeAdjustment ? { sizeAdjustment: body.sizeAdjustment } : {})
+      : { ok: true }),
     url: body.url,
     spec: body.spec,
+    ...(Array.isArray(body.warnings) ? { warnings: body.warnings } : {}),
+    ...(body.warning ? { warning: body.warning } : {}),
   };
   return { content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }] };
 }
@@ -168,7 +173,13 @@ const jsonRenderAddOperation = defineOperation<
       throw new OperationError(error instanceof Error ? error.message : String(error));
     }
   },
-  serialize: (result) => ({ ...buildNodeResponse(result.node), url: result.url, spec: result.spec }),
+  serialize: (result) => ({
+    ...buildNodeResponse(result.node),
+    url: result.url,
+    spec: result.spec,
+    warnings: result.warnings,
+    ...(result.sizeAdjustment ? { sizeAdjustment: result.sizeAdjustment } : {}),
+  }),
 });
 
 // ── jsonrender.stream ─────────────────────────────────────────
@@ -194,6 +205,7 @@ export interface StreamJsonRenderResult {
   specVersion: number;
   elementCount: number;
   streamStatus: 'open' | 'closed';
+  sizeAdjustment?: CanvasSizeAdjustment;
 }
 
 /**
@@ -206,6 +218,7 @@ export function streamJsonRenderCore(input: StreamJsonRenderInput): StreamJsonRe
   const done = input.done === true;
   let nodeId = typeof input.nodeId === 'string' && input.nodeId ? input.nodeId : undefined;
   let url = '';
+  let sizeAdjustment: CanvasSizeAdjustment | undefined;
   if (!nodeId) {
     const created = createCanvasStreamingJsonRenderNode({
       ...(typeof input.title === 'string' ? { title: input.title } : {}),
@@ -217,11 +230,17 @@ export function streamJsonRenderCore(input: StreamJsonRenderInput): StreamJsonRe
     });
     nodeId = created.id;
     url = created.url;
+    sizeAdjustment = created.sizeAdjustment;
   }
   const result = appendCanvasJsonRenderStream(nodeId, patches, done);
   if (!result.ok) throw new OperationError(result.error);
   const node = canvasState.getNode(nodeId);
-  return { id: nodeId, url: url || String(node?.data.url ?? ''), ...result };
+  return {
+    id: nodeId,
+    url: url || String(node?.data.url ?? ''),
+    ...result,
+    ...(sizeAdjustment ? { sizeAdjustment } : {}),
+  };
 }
 
 const jsonRenderStreamShape = {
@@ -303,6 +322,7 @@ const jsonRenderStreamOperation = defineOperation<z.infer<typeof jsonRenderStrea
         specVersion: body.specVersion,
         elementCount: body.elementCount,
         streamStatus: body.streamStatus,
+        ...(body.sizeAdjustment ? { sizeAdjustment: body.sizeAdjustment } : {}),
       };
       return { content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }] };
     },
@@ -558,7 +578,7 @@ const graphAddOperation = defineOperation<z.infer<typeof graphAddSchema>, Return
           ? body.highlight
           : undefined;
       const sort = body.sort === 'asc' || body.sort === 'desc' || body.sort === 'none' ? body.sort : undefined;
-      return createCanvasGraphNode({
+      const created = createCanvasGraphNode({
         title,
         graphType,
         data,
@@ -600,12 +620,24 @@ const graphAddOperation = defineOperation<z.infer<typeof graphAddSchema>, Return
         ...(width !== undefined ? { width } : {}),
         ...(nodeHeight !== undefined ? { heightPx: nodeHeight } : {}),
       });
+      return {
+        ...created,
+        ...(typeof body.height === 'number' && nodeHeight === undefined
+          ? { warning: '`height` controls graph plot height; use `nodeHeight` to set the node frame height.' }
+          : {}),
+      };
     } catch (error) {
       if (error instanceof OperationError) throw error;
       throw new OperationError(error instanceof Error ? error.message : String(error));
     }
   },
-  serialize: (result) => ({ ...buildNodeResponse(result.node), url: result.url, spec: result.spec }),
+  serialize: (result) => ({
+    ...buildNodeResponse(result.node),
+    url: result.url,
+    spec: result.spec,
+    ...(result.sizeAdjustment ? { sizeAdjustment: result.sizeAdjustment } : {}),
+    ...('warning' in result ? { warning: result.warning } : {}),
+  }),
 });
 
 // ── schema.describe ───────────────────────────────────────────

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

@@ -27,6 +27,7 @@ import {
   MCP_APP_NODE_DEFAULT_SIZE,
   IMAGE_NODE_DEFAULT_SIZE,
   LEDGER_NODE_DEFAULT_SIZE,
+  type CanvasSizeAdjustment,
 } from '../../canvas-operations.js';
 import { normalizeNodeAxCapabilities } from '../../ax-interaction.js';
 import { applyFileContentToNodeData, readFileNodeContent } from '../../file-content.js';
@@ -377,12 +378,13 @@ export function agentSafeFullLayoutPayload(layout: CanvasLayout): Record<string,
 export function createdNodePayloadFromNode(
   node: CanvasNodeState,
   options: Record<string, unknown> = {},
+  extras: Record<string, unknown> = {},
 ): Record<string, unknown> {
   if (!wantsFullPayload(options)) {
-    return { ok: true, node: compactNodePayload(node), id: node.id, nodeId: node.id };
+    return { ok: true, node: compactNodePayload(node), id: node.id, nodeId: node.id, ...extras };
   }
   const serialized = serializeCanvasNodeForAgent(node);
-  return { ok: true, node: serialized, ...serialized, nodeId: node.id };
+  return { ok: true, node: serialized, ...serialized, nodeId: node.id, ...extras };
 }
 
 // ── Operation cores (the SDK wraps these directly) ────────────
@@ -395,7 +397,7 @@ export function createdNodePayloadFromNode(
 export function createBasicCanvasNode(
   body: Record<string, unknown>,
   options: { fileMode: 'auto' | 'path' },
-): { node: CanvasNodeState; needsCodeGraphRecompute: boolean } {
+): { node: CanvasNodeState; needsCodeGraphRecompute: boolean; sizeAdjustment?: CanvasSizeAdjustment } {
   const type = typeof body.type === 'string' ? body.type : '';
   const extraData = isRecord(body.data) ? body.data : undefined;
   if (type === 'html') {
@@ -455,7 +457,7 @@ export function createBasicCanvasNode(
   const geometry = resolveCreateGeometry(body);
   const defaults = defaultNodeSize(type);
   try {
-    const { node, needsCodeGraphRecompute } = addCanvasNode({
+    const { node, needsCodeGraphRecompute, sizeAdjustment } = addCanvasNode({
       type: type as CanvasNodeState['type'],
       ...(typeof body.title === 'string'
         ? { title: body.title }
@@ -481,7 +483,7 @@ export function createBasicCanvasNode(
       defaultHeight: defaults.height,
       fileMode: options.fileMode,
     });
-    return { node, needsCodeGraphRecompute };
+    return { node, needsCodeGraphRecompute, ...(sizeAdjustment ? { sizeAdjustment } : {}) };
   } catch (error) {
     if (error instanceof OperationError) throw error;
     throw new OperationError(error instanceof Error ? error.message : String(error));
@@ -641,15 +643,15 @@ async function createWebpageNode(body: Record<string, unknown>, ctx: OperationCo
 
   const extraData = isRecord(body.data) ? body.data : undefined;
   const geometry = resolveCreateGeometry(body);
-  const { id, node } = addCanvasNode({
+  const { id, node, sizeAdjustment } = addCanvasNode({
     type: 'webpage',
     ...(typeof body.title === 'string' ? { title: body.title } : {}),
     content: normalizedUrl,
     ...(extraData ? { data: extraData } : {}),
     ...(body.strictSize === true ? { strictSize: true } : {}),
     ...geometry,
-    ...(geometry.width === undefined ? { width: WEBPAGE_NODE_DEFAULT_SIZE.width } : {}),
-    ...(geometry.height === undefined ? { height: WEBPAGE_NODE_DEFAULT_SIZE.height } : {}),
+    defaultWidth: WEBPAGE_NODE_DEFAULT_SIZE.width,
+    defaultHeight: WEBPAGE_NODE_DEFAULT_SIZE.height,
   });
 
   // The node should appear before the (slow) page fetch completes; the
@@ -662,6 +664,7 @@ async function createWebpageNode(body: Record<string, unknown>, ctx: OperationCo
     extras: {
       fetch: refreshed.ok ? { ok: true } : { ok: false, error: refreshed.error ?? 'Failed to fetch webpage content.' },
       ...(refreshed.ok ? {} : { error: refreshed.error }),
+      ...(sizeAdjustment ? { sizeAdjustment } : {}),
     },
   };
 }
@@ -691,7 +694,7 @@ function createHtmlPrimitiveNode(body: Record<string, unknown>): NodeAddResult {
   const axCapabilities =
     normalizeNodeAxCapabilities(body.axCapabilities) ??
     (declared ? { enabled: declared.enabled, allowed: [...declared.allowed] } : undefined);
-  const { node } = addCanvasNode({
+  const { node, sizeAdjustment } = addCanvasNode({
     type: 'html',
     title: built.title,
     data: {
@@ -718,6 +721,7 @@ function createHtmlPrimitiveNode(body: Record<string, unknown>): NodeAddResult {
         htmlBytes: Buffer.byteLength(built.html, 'utf-8'),
         defaultSize: built.defaultSize,
       },
+      ...(sizeAdjustment ? { sizeAdjustment } : {}),
     },
   };
 }
@@ -733,14 +737,14 @@ function createGroupNode(body: Record<string, unknown>): NodeAddResult {
     body.childLayout === 'grid' || body.childLayout === 'column' || body.childLayout === 'flow'
       ? body.childLayout
       : undefined;
-  const { node } = createCanvasGroup({
+  const { node, sizeAdjustment } = createCanvasGroup({
     ...(typeof body.title === 'string' ? { title: body.title } : {}),
     childIds,
     ...(typeof body.color === 'string' ? { color: body.color } : {}),
     ...(childLayout ? { childLayout } : {}),
     ...geometry,
   });
-  return { node };
+  return { node, ...(sizeAdjustment ? { extras: { sizeAdjustment } } : {}) };
 }
 
 const nodeAddShape = {
@@ -910,7 +914,8 @@ const nodeAddOperation = defineOperation<z.infer<typeof nodeAddSchema>, NodeAddR
         };
       }
       const node = body.node as CanvasNodeState | undefined;
-      const payload = node ? createdNodePayloadFromNode(node, input) : { ok: true };
+      const extras = body.sizeAdjustment ? { sizeAdjustment: body.sizeAdjustment } : {};
+      const payload = node ? createdNodePayloadFromNode(node, input, extras) : { ok: true };
       return { content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }] };
     },
   },
@@ -954,13 +959,13 @@ const nodeAddOperation = defineOperation<z.infer<typeof nodeAddSchema>, NodeAddR
     if (type === 'group') {
       return createGroupNode(body);
     }
-    const { node, needsCodeGraphRecompute } = createBasicCanvasNode(body, { fileMode: 'auto' });
+    const { node, needsCodeGraphRecompute, sizeAdjustment } = createBasicCanvasNode(body, { fileMode: 'auto' });
     if (needsCodeGraphRecompute) {
       scheduleCodeGraphRecompute(() => {
         ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
       });
     }
-    return { node };
+    return { node, ...(sizeAdjustment ? { extras: { sizeAdjustment } } : {}) };
   },
   serialize: ({ node, extras }) => ({ ...buildNodeResponse(node), ...(extras ?? {}) }),
 });
@@ -1129,7 +1134,10 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
       const body = isRecord(result) ? result : {};
       const node = body.node as CanvasNodeState | undefined;
       if (node) {
-        const payload = createdNodePayloadFromNode(node, input);
+        const payload = {
+          ...createdNodePayloadFromNode(node, input),
+          ...(body.sizeAdjustment ? { sizeAdjustment: body.sizeAdjustment } : {}),
+        };
         return { content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }] };
       }
       // No `node` field: a webpage-refresh result ({ ok, id, fetch?, error? }) or
@@ -1224,7 +1232,25 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
       }
     }
     const updated = canvasState.getNode(id);
-    return updated ? buildNodeResponse(updated) : { ok: true, id };
+    const fitted =
+      updated &&
+      existing.type === 'group' &&
+      (updated.size.width !== (patch.size?.width ?? existing.size.width) ||
+        updated.size.height !== (patch.size?.height ?? existing.size.height));
+    return updated
+      ? {
+          ...buildNodeResponse(updated),
+          ...(fitted
+            ? {
+                sizeAdjustment: {
+                  requested: { width: patch.size?.width ?? null, height: patch.size?.height ?? null },
+                  applied: updated.size,
+                  reason: 'fit-to-children',
+                },
+              }
+            : {}),
+        }
+      : { ok: true, id };
   },
 });
 

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

@@ -13,6 +13,7 @@
  * This module must never import server.ts or index.ts.
  */
 import { z } from 'zod';
+import { tourSchema, derivedTour } from '../../../shared/tour.js';
 import { canvasState } from '../../canvas-state.js';
 import { arrangeCanvasNodes, clearCanvas, fitCanvasView, setClientViewportSize } from '../../canvas-operations.js';
 import { validateCanvasLayout } from '../../canvas-validation.js';
@@ -272,7 +273,38 @@ const viewportSetOperation = defineOperation<z.infer<typeof viewportSetSchema>,
   },
 });
 
+const tourSetShape = { tour: tourSchema.nullable().describe('Ordered camera stops, or null to derive from groups') };
+const tourSetOperation = defineOperation({
+  name: 'tour.set',
+  mutates: true,
+  input: z.object(tourSetShape),
+  inputShape: tourSetShape,
+  http: { method: 'POST', path: '/api/canvas/tour' },
+  mcp: { toolName: 'canvas_set_tour', description: 'Persist an ordered board presentation tour.' },
+  handler: (input) => {
+    canvasState.setTour(input.tour);
+    return { ok: true };
+  },
+});
+const tourGetOperation = defineOperation({
+  name: 'tour.get',
+  mutates: false,
+  input: z.object({}),
+  inputShape: {},
+  http: { method: 'GET', path: '/api/canvas/tour' },
+  mcp: {
+    toolName: 'canvas_get_tour',
+    description: 'Read the board tour, deriving groups in reading order when absent.',
+  },
+  handler: () => ({
+    tour: canvasState.getTour() ?? derivedTour(canvasState.getLayout().nodes),
+    derived: !canvasState.getTour(),
+  }),
+});
+
 export const viewportOperations: Operation[] = [
+  tourSetOperation,
+  tourGetOperation,
   arrangeOperation,
   focusOperation,
   fitOperation,

package/src/server/operations/registry.ts

@@ -296,6 +296,12 @@ const PRESENCE_EXEMPT_OPS = new Set([
   'ax.activity.ingest',
   'human.presence.set',
   'human.presence.get',
+  // Camera and attention controls are observation/navigation, not edits.
+  // They must not create a writer, bump opCount, or refresh an existing one.
+  'viewport.set',
+  'view.fit',
+  'node.focus',
+  'ax.focus.set',
 ]);
 
 /** Layout mutations AND non-GET AX writes (work items, gates, evidence, steering) are agent activity. */

package/src/server/scope-fence.ts

@@ -111,7 +111,7 @@ function createTarget(input: Record<string, unknown>, extraNodeIds: string[] = [
 }
 
 /** Ops that rewrite the whole board — never allowed under a fence. */
-const BOARD_WIDE_OPS = new Set(['arrange', 'canvas.clear', 'snapshot.restore', 'render.workboard']);
+const BOARD_WIDE_OPS = new Set(['arrange', 'canvas.clear', 'snapshot.restore', 'render.workboard', 'tour.set']);
 
 /** Describe what a registry op would write, in fence terms. */
 export function describeOpTarget(op: Operation, rawInput: unknown): FenceTarget {

package/src/server/server.ts

@@ -143,7 +143,7 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy) => {
   let snapshot = startSnapshotId
     ? (canvasState.listSnapshots({ all: true }).find((entry) => entry.id === startSnapshotId) ?? null)
     : null;
-  let unchanged = false;
+  let unchanged = !startSnapshotId && canvasState.getLayout().nodes.length === 0;
   // A session that changed NOTHING on the board leaves no snapshot behind —
   // session churn (idle timeouts, receipt tests, attach/detach cycles) was
   // flooding the History drawer with identical boards.
@@ -184,6 +184,7 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy) => {
   // workbench session and would overwrite it. The label is what the receipt shows.
   emitPrimaryWorkbenchEvent('agent-session-ended', {
     label: presence.label,
+    parentAgentId: presence.parentAgentId ?? null,
     endedAt,
     endedBy,
     counts,
@@ -1431,15 +1432,17 @@ function handleNodeSurface(pathname: string, url: URL): Response {
     // escaped diagram source, rendered by /canvas/mermaid-entry.js.
     const inlineAssets = url.searchParams.get('inline-assets') === '1';
     const doc = buildHtmlSurfaceDocument(
-      buildMermaidSurfaceHtml(source, inlineAssets ? mermaidEntryJsInline() : null),
+      buildMermaidSurfaceHtml(
+        source,
+        inlineAssets ? mermaidEntryJsInline() : null,
+        node.data.fit === 'none' ? 'none' : 'contain',
+        url.searchParams.get('frameToken') ?? '',
+      ),
       {
         theme,
         title: surfaceTitle,
         themeToken: url.searchParams.get('themeToken') ?? undefined,
-        // Content-height reporter nonce (lets the node grow to fit the diagram).
-        ...(url.searchParams.get('frameToken')
-          ? { contentHeightToken: url.searchParams.get('frameToken') as string }
-          : {}),
+        // Mermaid reports its natural height itself, before contain scaling.
         // Inline the theme tokens so srcdoc-rendered surfaces (Amp orb portals)
         // are styled without depending on the <link> subresource.
         ...(surfaceThemeCssInline() ? { inlineThemeCss: surfaceThemeCssInline() as string } : {}),

package/src/server/web-artifacts.ts

@@ -13,7 +13,7 @@ import {
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { ensureArtifactsDir, getWorkspaceRoot } from './artifact-paths.js';
 import { canvasState, type CanvasNodeState } from './canvas-state.js';
-import { emitCanvasLayoutUpdate } from './canvas-operations.js';
+import { emitCanvasLayoutUpdate, type CanvasSizeAdjustment } from './canvas-operations.js';
 import { findOpenCanvasPosition } from './placement.js';
 
 const BUNDLED_WEB_ARTIFACT_SCRIPTS_DIR = join(import.meta.dir, 'web-artifacts', 'scripts');
@@ -95,12 +95,14 @@ export interface WebArtifactSourceContext {
 export interface WebArtifactCanvasOpenResult {
   nodeId: string;
   url: string;
+  sizeAdjustment: CanvasSizeAdjustment;
 }
 
 export interface WebArtifactCanvasBuildResult extends WebArtifactBuildOutput {
   openedInCanvas: boolean;
   nodeId?: string;
   url?: string;
+  sizeAdjustment?: CanvasSizeAdjustment;
   startedAt: string;
   completedAt: string;
   durationMs: number;
@@ -740,7 +742,11 @@ export function openWebArtifactInCanvas(input: {
   // This keeps web-artifacts.ts server-independent so the registry op
   // (operations/ops/app.ts) can import it without pulling in server.ts.
   emitCanvasLayoutUpdate();
-  return { nodeId: id, url };
+  return {
+    nodeId: id,
+    url,
+    sizeAdjustment: { requested: { width: null, height: null }, applied: node.size, reason: 'defaulted' },
+  };
 }
 
 export async function buildWebArtifactOnCanvas(
@@ -778,6 +784,7 @@ export async function buildWebArtifactOnCanvas(
     openedInCanvas: true,
     nodeId: opened.nodeId,
     url: opened.url,
+    sizeAdjustment: opened.sizeAdjustment,
     ...timing,
   };
 }

package/src/server/workboard.ts

@@ -82,14 +82,14 @@ export function buildWorkboardSpec(workItems: PmxAxWorkItem[]): JsonRenderSpec {
     }
     elements[columnId] = {
       type: 'Stack',
-      props: { direction: 'vertical', gap: 'sm' },
+      props: { direction: 'vertical', gap: 'sm', align: 'stretch' },
       children: columnChildren,
     };
     columnIds.push(columnId);
   }
   elements.board = {
-    type: 'Stack',
-    props: { direction: 'horizontal', gap: 'md', align: 'start' },
+    type: 'Grid',
+    props: { columns: columnIds.length, gap: 'md' },
     children: columnIds,
   };
   return { root: 'board', elements };