pmx-canvas 0.6.4 → 0.6.5

package/src/client/theme/global.css

@@ -1210,13 +1210,13 @@ body,
   font-size: 9px;
   padding: 1px 6px;
 }
-/* Idle cursors leave the board (user feedback, 0.5.1 cycle): with many agents
+/* Parked idle cursors leave the board (user feedback, 0.5.1 cycle): with many agents
    attached, a wall of parked "Idle" pills covers real node content. The
    element stays MOUNTED — counts, twin-merge, and cursor-follow logic are
    untouched, and visibility (not display) keeps its layout box so position
-   polls still resolve — but it paints nothing; any non-idle phase fades it
-   back in. Placed after .is-worker so opacity: 0 wins that collision. */
-.agent-cursor.phase-idle {
+   polls still resolve — but it paints nothing. An explicitly reported cursor
+   remains visible even while idle so cursor-only movement cannot disappear. */
+.agent-cursor.phase-idle:not(.has-explicit-cursor) {
   opacity: 0;
   visibility: hidden;
   transition:
@@ -4211,6 +4211,33 @@ html.is-node-resizing .ext-app-preview-catcher {
 }
 
 /* MCP app iframe */
+.mcp-app-frame-stack {
+  position: relative;
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  background: var(--c-panel-soft);
+  overflow: hidden;
+  border-radius: 0 0 calc(var(--radius) - 1px) calc(var(--radius) - 1px);
+}
+
+.mcp-app-frame-stack:has(.html-node-frame) {
+  width: 100%;
+  height: 100%;
+  min-height: 300px;
+  background: var(--c-bg);
+  border-radius: 6px;
+}
+
+.mcp-app-frame-stack:has(.html-node-frame-presentation) {
+  min-height: 0;
+  border-radius: 0;
+}
+
+.mcp-app-frame-stack:has(.html-node-frame-expanded) {
+  min-height: 70vh;
+}
+
 .mcp-app-frame {
   width: 100%;
   height: 100%;
@@ -6808,3 +6835,30 @@ html.is-node-dragging .intent-ghost,
 html.is-node-dragging .intent-line-layer {
   opacity: 0.5;
 }
+
+.present-button {
+  color: var(--c-text);
+  background: var(--c-bg);
+  border: 1px solid var(--c-line);
+  border-radius: 6px;
+  padding: 4px 12px;
+  cursor: pointer;
+}
+.is-presenting > :not(.app-main):not(.presentation-error),
+.is-presenting .app-main > :not(.canvas-region),
+.is-presenting .canvas-region > :not(.canvas-viewport) {
+  display: none !important;
+}
+.is-presenting .canvas-viewport { pointer-events: none; }
+.presentation-error {
+  position: fixed;
+  bottom: 16px;
+  left: 16px;
+  z-index: 100;
+  max-width: calc(100% - 32px);
+  padding: 10px 16px;
+  border: 1px solid var(--c-line);
+  border-radius: 6px;
+  background: var(--c-panel);
+  color: var(--c-text);
+}

package/src/json-render/server.ts

@@ -542,6 +542,35 @@ export function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpe
   return propsValidation.data as JsonRenderSpec;
 }
 
+/** shadcn 0.21 ignores these props unless the renderer supplies a two-way binding. */
+export function jsonRenderFormWarnings(spec: JsonRenderSpec): string[] {
+  const bindingOnlyProps: Record<string, string> = {
+    Input: 'value',
+    Textarea: 'value',
+    Select: 'value',
+    Radio: 'value',
+    Slider: 'value',
+    ToggleGroup: 'value',
+    ButtonGroup: 'selected',
+    Tabs: 'value',
+  };
+  const warnings: string[] = [];
+  for (const [key, rawElement] of Object.entries(spec.elements)) {
+    const element = asRecord(rawElement);
+    const type = typeof element?.type === 'string' ? element.type : '';
+    const prop = bindingOnlyProps[type];
+    if (!prop) continue;
+    const value = asRecord(element?.props)?.[prop];
+    if (value === undefined || value === null) continue;
+    const expression = asRecord(value);
+    if (hasString(expression?.$bindState) || hasString(expression?.$bindItem)) continue;
+    warnings.push(
+      `elements.${key}.props.${prop}: ${type} ignores an unbound ${prop} (including literal values and $state expressions). Use { "$bindState": "/form/field" } and seed spec.state.form.field with the initial value; inside a repeat use $bindItem with seeded item data.${type === 'Tabs' ? ' For an uncontrolled initial tab, use defaultValue instead.' : ''}`,
+    );
+  }
+  return warnings;
+}
+
 export function normalizeGraphType(value: string): GraphChartType {
   const normalized = value.toLowerCase().replace(/[-_\s]/g, '');
   return GRAPH_TYPE_ALIASES[normalized] ?? 'LineChart';

package/src/server/agent-presence.ts

@@ -198,6 +198,8 @@ const presenceSetSchema = z.object(PRESENCE_SET_SHAPE);
 
 interface StoredPresence extends AgentPresence {
   lastSeenMs: number;
+  /** Last explicit phase report; cursor/focus heartbeats must not keep a stale phase alive. */
+  phaseSetMs: number;
   /** Explicit phases (`thinking`) hold until the next touch; derived `tooling` decays. */
   toolingUntilMs: number | null;
   lastActivityNodeId: string | null;
@@ -381,6 +383,7 @@ export class AgentPresenceRegistry {
       contextUsage: null,
       lastSeenAt: new Date(now).toISOString(),
       lastSeenMs: now,
+      phaseSetMs: now,
       toolingUntilMs: null,
       startSnapshotId: null,
     };
@@ -458,10 +461,12 @@ export class AgentPresenceRegistry {
       }
       stored.startSnapshotId = inheritedSnapshotId ?? this.onSessionStart(this.publicView(stored, now));
     }
-    if (wasAttached && input.attached === false) {
-      this.onSessionEnd(this.publicView(stored, now), stored.startSnapshotId, input.endedBy ?? 'agent');
-      // An ended session is gone — like `session-end` on the activity feed, it
-      // must not linger as an "external writer" until the activity TTL.
+    if (input.attached === false) {
+      if (wasAttached)
+        this.onSessionEnd(this.publicView(stored, now), stored.startSnapshotId, input.endedBy ?? 'agent');
+      // An explicit detach always removes the presence. In particular, a
+      // worker that reports attached:false must not be refreshed into another
+      // full activity TTL as an external writer.
       this.presences.delete(key);
       this.dropAliasesTo(key);
       this.maybeStopSweeper();
@@ -481,6 +486,7 @@ export class AgentPresenceRegistry {
       if (input.detail !== undefined) stored.detail = input.detail;
     } else if (input.phase !== undefined) {
       stored.phase = input.phase;
+      stored.phaseSetMs = now;
       stored.detail = input.detail !== undefined ? input.detail : input.phase === 'tooling' ? stored.detail : null;
       stored.toolingUntilMs = input.phase === 'tooling' ? now + PRESENCE_TOOLING_SETTLE_MS : null;
     } else if (input.detail !== undefined) {
@@ -607,6 +613,7 @@ export class AgentPresenceRegistry {
   private publicView(stored: StoredPresence, now: number): AgentPresence {
     const {
       lastSeenMs: _lastSeenMs,
+      phaseSetMs: _phaseSetMs,
       toolingUntilMs,
       startSnapshotId: _startSnapshotId,
       lastActivityNodeId,
@@ -691,11 +698,10 @@ export class AgentPresenceRegistry {
         changed = true;
         continue;
       }
-      // Explicit thinking that nothing refreshed settles to idle: the host set
-      // it at turn start and never sent the turn-end idle (three "Thinking"
-      // chips on a silent board). Any touch bumps lastSeenMs, so an agent
-      // that IS doing canvas work keeps its thinking chip.
-      if (presence.phase === 'thinking' && now - presence.lastSeenMs > PRESENCE_THINKING_SETTLE_MS) {
+      // Cursor/focus heartbeats keep the writer live, but cannot keep a stale
+      // explicit phase alive. Only another explicit phase report resets this
+      // clock; operation-derived tooling remains its own short overlay.
+      if (presence.phase === 'thinking' && now - presence.phaseSetMs > PRESENCE_THINKING_SETTLE_MS) {
         presence.phase = 'idle';
         presence.detail = null;
         changed = true;

package/src/server/canvas-db.ts

@@ -6,6 +6,7 @@
  */
 
 import { Database } from 'bun:sqlite';
+import { tourSchema, type Tour } from '../shared/tour.js';
 import { existsSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
@@ -260,6 +261,7 @@ function parsePersistedAxState(raw: string | null | undefined): PmxAxState {
 // ── Persisted State Interface ───────────────────────────────────
 
 export interface PersistedCanvasState {
+  tour?: Tour;
   version: number;
   theme?: CanvasTheme;
   viewport: ViewportState;
@@ -270,6 +272,11 @@ export interface PersistedCanvasState {
   ax?: PmxAxState;
 }
 
+function readTour(raw: string | undefined): Tour | undefined {
+  if (!raw || raw === 'null') return undefined;
+  return tourSchema.parse(JSON.parse(raw));
+}
+
 // ── Database Management ─────────────────────────────────────────
 
 export function openCanvasDb(dbPath: string): Database {
@@ -394,6 +401,7 @@ export function saveStateToDB(db: Database, state: PersistedCanvasState): void {
        WHERE value IS NOT excluded.value`,
     );
     upsertMeta.run('theme', normalizeCanvasTheme(state.theme));
+    upsertMeta.run('tour', JSON.stringify(state.tour ?? null));
     upsertMeta.run('viewport_x', String(state.viewport.x));
     upsertMeta.run('viewport_y', String(state.viewport.y));
     upsertMeta.run('viewport_scale', String(state.viewport.scale));
@@ -610,6 +618,7 @@ export function loadStateFromDB(db: Database): PersistedCanvasState | null {
   return {
     version: 1,
     theme,
+    tour: readTour(db.query<{ value: string }, [string]>('SELECT value FROM meta WHERE key = ?').get('tour')?.value),
     viewport,
     nodes,
     edges,
@@ -632,6 +641,11 @@ export function saveSnapshotToDB(db: Database, snapshot: CanvasSnapshot, state:
       state.edges.length,
     ]);
 
+    db.run('INSERT INTO snapshot_meta (snapshot_id, key, value) VALUES (?, ?, ?)', [
+      snapshot.id,
+      'tour',
+      JSON.stringify(state.tour ?? null),
+    ]);
     // Insert snapshot viewport meta
     db.run('INSERT INTO snapshot_meta (snapshot_id, key, value) VALUES (?, ?, ?)', [
       snapshot.id,
@@ -859,6 +873,7 @@ export function loadSnapshotFromDB(
     snapshot,
     state: {
       version: 1,
+      tour: readTour(metaMap.get('tour')),
       viewport,
       nodes,
       edges,

package/src/server/canvas-operations.ts

@@ -33,6 +33,7 @@ import {
   emptyStreamingSpec,
   GRAPH_NODE_SIZE,
   inferJsonRenderNodeTitle,
+  jsonRenderFormWarnings,
   JSON_RENDER_NODE_SIZE,
   normalizeAndValidateJsonRenderSpec,
   type GraphNodeInput,
@@ -118,6 +119,29 @@ export const MCP_APP_NODE_DEFAULT_SIZE = { width: 960, height: 600 };
 export const IMAGE_NODE_DEFAULT_SIZE = { width: 480, height: 360 };
 export const LEDGER_NODE_DEFAULT_SIZE = { width: 420, height: 280 };
 
+export interface CanvasSizeAdjustment {
+  requested: { width: number | null; height: number | null };
+  applied: { width: number; height: number };
+  reason: 'defaulted' | 'clamped-to-minimum' | 'defaulted-and-clamped-to-minimum' | 'fit-to-children';
+}
+
+export function describeCreateSize(
+  requestedWidth: number | undefined,
+  requestedHeight: number | undefined,
+  resolvedWidth: number,
+  resolvedHeight: number,
+  applied: { width: number; height: number },
+): CanvasSizeAdjustment | undefined {
+  const defaulted = requestedWidth === undefined || requestedHeight === undefined;
+  const clamped = applied.width !== resolvedWidth || applied.height !== resolvedHeight;
+  if (!defaulted && !clamped) return undefined;
+  return {
+    requested: { width: requestedWidth ?? null, height: requestedHeight ?? null },
+    applied,
+    reason: defaulted && clamped ? 'defaulted-and-clamped-to-minimum' : clamped ? 'clamped-to-minimum' : 'defaulted',
+  };
+}
+
 // Per-type minimum creation sizes + clamp live in canvas-validation.ts
 // (NODE_MIN_CREATE_SIZES / clampCreateNodeSize) — shared with the validate
 // surface's sizeWarnings.
@@ -923,17 +947,15 @@ export function addCanvasNode(input: CanvasAddNodeInput): {
   id: string;
   node: CanvasNodeState;
   needsCodeGraphRecompute: boolean;
+  sizeAdjustment?: CanvasSizeAdjustment;
 } {
   if (input.type === 'json-render' || input.type === 'graph') {
     throw new Error(`Use the dedicated ${input.type} node APIs for structured viewer nodes.`);
   }
 
-  const { width, height } = clampCreateNodeSize(
-    input.type,
-    input.width ?? input.defaultWidth ?? 720,
-    input.height ?? input.defaultHeight ?? 600,
-    input.strictSize,
-  );
+  const resolvedWidth = input.width ?? input.defaultWidth ?? 720;
+  const resolvedHeight = input.height ?? input.defaultHeight ?? 600;
+  const { width, height } = clampCreateNodeSize(input.type, resolvedWidth, resolvedHeight, input.strictSize);
   const position =
     input.x !== undefined && input.y !== undefined
       ? { x: input.x, y: input.y }
@@ -959,7 +981,16 @@ export function addCanvasNode(input: CanvasAddNodeInput): {
     watchFileForNode(id, filePath);
   }
 
-  return { id, node: storedNode, needsCodeGraphRecompute: input.type === 'file' };
+  const sizeAdjustment = describeCreateSize(input.width, input.height, resolvedWidth, resolvedHeight, {
+    width,
+    height,
+  });
+  return {
+    id,
+    node: storedNode,
+    needsCodeGraphRecompute: input.type === 'file',
+    ...(sizeAdjustment ? { sizeAdjustment } : {}),
+  };
 }
 
 export function resolveCanvasNode(nodeRef: CanvasNodeLookupInput):
@@ -1415,7 +1446,8 @@ export function saveCanvasSnapshotWithReuse(name: string): { snapshot: CanvasSna
         diff.removedNodes.length === 0 &&
         diff.modifiedNodes.length === 0 &&
         diff.addedEdges.length === 0 &&
-        diff.removedEdges.length === 0;
+        diff.removedEdges.length === 0 &&
+        JSON.stringify(newestData.tour) === JSON.stringify(canvasState.getTour());
       if (identical) return { snapshot: newest, reused: true };
     }
   }
@@ -1508,7 +1540,11 @@ export function removeCanvasEdge(id: string): { removed: boolean } {
   return { removed: canvasState.removeEdge(id) };
 }
 
-export function createCanvasGroup(input: CanvasCreateGroupInput): { id: string; node: CanvasNodeState } {
+export function createCanvasGroup(input: CanvasCreateGroupInput): {
+  id: string;
+  node: CanvasNodeState;
+  sizeAdjustment?: CanvasSizeAdjustment;
+} {
   let x = input.x;
   let y = input.y;
   let width = input.width ?? 600;
@@ -1566,22 +1602,42 @@ export function createCanvasGroup(input: CanvasCreateGroupInput): { id: string;
   if (!node) {
     throw new Error(`Group "${id}" was not created.`);
   }
-  return { id, node };
+  const adjusted = input.width !== node.size.width || input.height !== node.size.height;
+  const fitted = childIds.length > 0 && ((input.x === undefined && input.y === undefined) || !explicitFrame);
+  return {
+    id,
+    node,
+    ...(adjusted
+      ? {
+          sizeAdjustment: {
+            requested: { width: input.width ?? null, height: input.height ?? null },
+            applied: node.size,
+            reason: fitted ? ('fit-to-children' as const) : ('defaulted' as const),
+          },
+        }
+      : {}),
+  };
 }
 
 export function groupCanvasNodes(
   groupId: string,
   childIds: string[],
   options: { childLayout?: CanvasArrangeMode } = {},
-): { ok: boolean } {
+): { ok: boolean; sizeAdjustment?: CanvasSizeAdjustment } {
+  const before = canvasState.getNode(groupId)?.size;
+  const ok = canvasState.groupNodes(groupId, childIds, {
+    // Preserve existing child positions unless an explicit layout is asked
+    // for — matching createCanvasGroup and the batch group.add path. Without
+    // this, grouping silently auto-packs the nodes into a grid.
+    preservePositions: options.childLayout === undefined,
+    ...(options.childLayout ? { layout: options.childLayout } : {}),
+  });
+  const applied = canvasState.getNode(groupId)?.size;
   return {
-    ok: canvasState.groupNodes(groupId, childIds, {
-      // Preserve existing child positions unless an explicit layout is asked
-      // for — matching createCanvasGroup and the batch group.add path. Without
-      // this, grouping silently auto-packs the nodes into a grid.
-      preservePositions: options.childLayout === undefined,
-      ...(options.childLayout ? { layout: options.childLayout } : {}),
-    }),
+    ok,
+    ...(before && applied && (before.width !== applied.width || before.height !== applied.height)
+      ? { sizeAdjustment: { requested: before, applied, reason: 'fit-to-children' as const } }
+      : {}),
   };
 }
 
@@ -1600,6 +1656,8 @@ export function createCanvasJsonRenderNode(input: JsonRenderNodeInput): {
   url: string;
   spec: JsonRenderSpec;
   node: CanvasNodeState;
+  warnings: string[];
+  sizeAdjustment?: CanvasSizeAdjustment;
 } {
   const spec = normalizeAndValidateJsonRenderSpec(input.spec);
   const { width, height } = clampCreateNodeSize(
@@ -1628,7 +1686,24 @@ export function createCanvasJsonRenderNode(input: JsonRenderNodeInput): {
   };
 
   canvasState.addJsonRenderNode(node);
-  return { id, url: String(node.data.url), spec, node };
+  const sizeAdjustment = describeCreateSize(
+    input.width,
+    input.height,
+    input.width ?? JSON_RENDER_NODE_SIZE.width,
+    input.height ?? JSON_RENDER_NODE_SIZE.height,
+    {
+      width,
+      height,
+    },
+  );
+  return {
+    id,
+    url: String(node.data.url),
+    spec,
+    node,
+    warnings: jsonRenderFormWarnings(spec),
+    ...(sizeAdjustment ? { sizeAdjustment } : {}),
+  };
 }
 
 /**
@@ -1643,7 +1718,7 @@ export function createCanvasStreamingJsonRenderNode(input: {
   width?: number;
   height?: number;
   strictSize?: boolean;
-}): { id: string; url: string; spec: JsonRenderSpec; node: CanvasNodeState } {
+}): { id: string; url: string; spec: JsonRenderSpec; node: CanvasNodeState; sizeAdjustment?: CanvasSizeAdjustment } {
   const spec = emptyStreamingSpec();
   const { width, height } = clampCreateNodeSize(
     'json-render',
@@ -1673,7 +1748,17 @@ export function createCanvasStreamingJsonRenderNode(input: {
   };
 
   canvasState.addJsonRenderNode(node);
-  return { id, url: String(node.data.url), spec, node };
+  const sizeAdjustment = describeCreateSize(
+    input.width,
+    input.height,
+    input.width ?? JSON_RENDER_NODE_SIZE.width,
+    input.height ?? JSON_RENDER_NODE_SIZE.height,
+    {
+      width,
+      height,
+    },
+  );
+  return { id, url: String(node.data.url), spec, node, ...(sizeAdjustment ? { sizeAdjustment } : {}) };
 }
 
 /**
@@ -1717,6 +1802,7 @@ export function createCanvasGraphNode(input: GraphNodeInput): {
   url: string;
   spec: JsonRenderSpec;
   node: CanvasNodeState;
+  sizeAdjustment?: CanvasSizeAdjustment;
 } {
   const title = input.title?.trim() || 'Graph';
   const spec = buildGraphSpec(input);
@@ -1747,7 +1833,14 @@ export function createCanvasGraphNode(input: GraphNodeInput): {
   };
 
   canvasState.addGraphNode(node);
-  return { id, url: String(node.data.url), spec, node };
+  const sizeAdjustment = describeCreateSize(
+    input.width,
+    input.heightPx,
+    input.width ?? GRAPH_NODE_SIZE.width,
+    input.heightPx ?? GRAPH_NODE_SIZE.height,
+    { width, height },
+  );
+  return { id, url: String(node.data.url), spec, node, ...(sizeAdjustment ? { sizeAdjustment } : {}) };
 }
 
 /**

package/src/server/canvas-schema.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { describeJsonRenderCatalog, type JsonRenderComponentDescriptor } from '../json-render/catalog.js';
 import {
   buildGraphSpec,
+  jsonRenderFormWarnings,
   normalizeAndValidateJsonRenderSpec,
   normalizeGraphType,
   type GraphNodeInput,
@@ -38,6 +39,7 @@ export interface StructuredValidationResult {
   ok: true;
   type: 'json-render' | 'graph' | 'html-primitive';
   normalizedSpec?: JsonRenderSpec;
+  warnings?: string[];
   normalizedPrimitive?: {
     kind: string;
     title: string;
@@ -235,6 +237,13 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
       { name: 'content', type: 'string', required: false, description: 'Mermaid diagram source text.' },
+      {
+        name: 'data.fit',
+        type: '"contain" | "none"',
+        required: false,
+        description:
+          'Default contain: shrink overflowing diagrams proportionally, without enlarging. none: 100% with scrolling. Open as site always uses 100%. CLI: --fit contain|none.',
+      },
     ],
     example: {
       type: 'mermaid',
@@ -1013,6 +1022,7 @@ export function validateStructuredCanvasPayload(input: {
       ok: true,
       type: 'json-render',
       normalizedSpec,
+      warnings: jsonRenderFormWarnings(normalizedSpec),
       summary: {
         root: normalizedSpec.root,
         elementCount: Object.keys(normalizedSpec.elements).length,

package/src/server/canvas-state.ts

@@ -13,6 +13,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import { tourSchema, type Tour } from '../shared/tour.js';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
 import { isAbsolute, join, dirname, relative } from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
@@ -223,6 +224,7 @@ export interface CanvasAnnotation {
 }
 
 export interface CanvasLayout {
+  tour?: Tour;
   viewport: ViewportState;
   theme: CanvasTheme;
   nodes: CanvasNodeState[];
@@ -333,6 +335,7 @@ class CanvasStateManager {
   private edges = new Map<string, CanvasEdge>();
   private annotations = new Map<string, CanvasAnnotation>();
   private _viewport: ViewportState = { x: 0, y: 0, scale: 1 };
+  private _tour: Tour | undefined;
   private _theme: CanvasTheme = 'dark';
   private _contextPinnedNodeIds = new Set<string>();
   private _workspaceRoot = process.cwd();
@@ -899,6 +902,7 @@ class CanvasStateManager {
       const payload = this.externalizePersistedStateBlobs({
         version: 1,
         theme: this._theme,
+        tour: this._tour,
         viewport: this._viewport,
         nodes: Array.from(this.nodes.values()),
         edges: Array.from(this.edges.values()),
@@ -957,6 +961,7 @@ class CanvasStateManager {
   }
 
   private applyPersistedState(state: PersistedCanvasState): void {
+    this._tour = state.tour ? structuredClone(state.tour) : undefined;
     this.nodes.clear();
     this.edges.clear();
     this.annotations.clear();
@@ -1091,7 +1096,7 @@ class CanvasStateManager {
         contextPins: Array.from(this._contextPinnedNodeIds),
         ax: this.getAxState(),
       });
-      saveSnapshotToDB(this._db, snapshot, payload);
+      saveSnapshotToDB(this._db, snapshot, { ...payload, tour: this._tour });
       snapshot.nodeCount = payload.nodes.length;
       snapshot.edgeCount = payload.edges.length;
       return snapshot;
@@ -1176,6 +1181,7 @@ class CanvasStateManager {
 
     const previousState: PersistedCanvasState = this.externalizePersistedStateBlobs({
       version: 1,
+      tour: this._tour,
       theme: this._theme,
       viewport: structuredClone(this._viewport),
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(node)),
@@ -1186,6 +1192,7 @@ class CanvasStateManager {
     });
     const nextState: PersistedCanvasState = {
       version: 1,
+      tour: resolved.state.tour,
       theme: normalizeCanvasTheme(resolved.state.theme, this._theme),
       viewport: structuredClone(resolved.state.viewport),
       nodes: Array.isArray(resolved.state.nodes) ? resolved.state.nodes.map((node) => structuredClone(node)) : [],
@@ -1233,9 +1240,13 @@ class CanvasStateManager {
   }
 
   /** Read a snapshot's data without restoring it (for diff). Resolves by ID or name. */
-  getSnapshotData(
-    idOrName: string,
-  ): { name: string; nodes: CanvasNodeState[]; edges: CanvasEdge[]; annotations: CanvasAnnotation[] } | null {
+  getSnapshotData(idOrName: string): {
+    name: string;
+    nodes: CanvasNodeState[];
+    edges: CanvasEdge[];
+    annotations: CanvasAnnotation[];
+    tour?: Tour;
+  } | null {
     const resolved = this.readResolvedSnapshot(idOrName);
     if (!resolved) return null;
     const state = {
@@ -1246,6 +1257,7 @@ class CanvasStateManager {
     };
     return {
       name: resolved.snapshot.name,
+      ...(state.tour ? { tour: structuredClone(state.tour) } : {}),
       nodes: Array.isArray(state.nodes) ? state.nodes.map((node) => structuredClone(node)) : [],
       edges: Array.isArray(state.edges) ? state.edges.map((edge) => structuredClone(edge)) : [],
       annotations: Array.isArray(state.annotations)
@@ -1620,6 +1632,7 @@ class CanvasStateManager {
 
   getLayout(): CanvasLayout {
     return {
+      tour: this.getTour(),
       viewport: structuredClone(this._viewport),
       theme: this._theme,
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(this.nodeForRead(node))),
@@ -1630,6 +1643,7 @@ class CanvasStateManager {
 
   getLayoutForPersistence(): CanvasLayout {
     return {
+      tour: this.getTour(),
       viewport: structuredClone(this._viewport),
       theme: this._theme,
       nodes: Array.from(this.nodes.values(), (node) => structuredClone(this.externalizeNodeDataBlobs(node))),
@@ -1638,6 +1652,24 @@ class CanvasStateManager {
     };
   }
 
+  getTour(): Tour | undefined {
+    return this._tour ? structuredClone(this._tour) : undefined;
+  }
+
+  setTour(tour: Tour | null): void {
+    const previous = this.getTour();
+    this._tour = tour === null ? undefined : tourSchema.parse(tour);
+    const next = this.getTour();
+    this.scheduleSave();
+    this.notifyChange('nodes');
+    this.recordMutation({
+      operationType: 'viewport',
+      description: 'Updated board tour',
+      forward: this.suppressed(() => this.setTour(next ?? null)),
+      inverse: this.suppressed(() => this.setTour(previous ?? null)),
+    });
+  }
+
   applyUpdates(updates: CanvasNodeUpdate[], options: ApplyUpdatesOptions = {}): { applied: number; skipped: number } {
     let applied = 0;
     let skipped = 0;
@@ -2246,6 +2278,8 @@ class CanvasStateManager {
   }
 
   clear(): void {
+    const oldTour = this.getTour();
+    this._tour = undefined;
     const oldNodes = Array.from(this.nodes.values()).map((n) => structuredClone(n));
     const oldEdges = Array.from(this.edges.values()).map((e) => structuredClone(e));
     const oldAnnotations = Array.from(this.annotations.values()).map((annotation) => structuredClone(annotation));
@@ -2274,6 +2308,7 @@ class CanvasStateManager {
         for (const e of oldEdges) this.addEdge(structuredClone(e));
         for (const annotation of oldAnnotations) this.addAnnotation(structuredClone(annotation));
         this.setContextPins(oldPins);
+        this.setTour(oldTour ?? null);
         this.ax.applyPersistedAx(oldAxState);
         this.setViewport(oldViewport);
         this.notifyChange('ax');