pmx-canvas 0.1.26 → 0.1.28

package/src/server/canvas-operations.ts

@@ -22,9 +22,11 @@ import { searchNodes } from './spatial-analysis.js';
 import { getCanvasNodeTitle, serializeCanvasNodeCompact, type SerializedCanvasNode } from './canvas-serialization.js';
 import { computeAutoArrange } from '../shared/auto-arrange.js';
 import {
+  applyJsonRenderStreamPatches,
   buildGraphSpec,
   buildGraphConfig,
   createJsonRenderNodeData,
+  emptyStreamingSpec,
   GRAPH_NODE_SIZE,
   inferJsonRenderNodeTitle,
   JSON_RENDER_NODE_SIZE,
@@ -105,6 +107,12 @@ interface CanvasAddNodeInput {
 
 export const MARKDOWN_NODE_DEFAULT_SIZE = { width: 640, height: 420 };
 export const MCP_APP_NODE_DEFAULT_SIZE = { width: 960, height: 600 };
+// Image and ledger nodes previously fell through to the generic 360x200 frame,
+// which clipped content (a 360-wide image / log stream is cramped). Give them
+// roomier defaults; height still auto-fits to content (see auto-fit.ts), so the
+// width bump is the reliable lever.
+export const IMAGE_NODE_DEFAULT_SIZE = { width: 480, height: 360 };
+export const LEDGER_NODE_DEFAULT_SIZE = { width: 420, height: 280 };
 
 interface CanvasCreateGroupInput {
   title?: string;
@@ -827,6 +835,39 @@ export function scheduleCodeGraphRecompute(onComplete?: () => void): void {
   }, 300);
 }
 
+/**
+ * Resolve an html-node `html` field that may be a path to a local .html/.htm file.
+ *
+ * If the string looks like a bare filesystem path to an existing HTML file
+ * (no markup, no newlines, short, ends in .html/.htm, exists on disk), read the
+ * file and return its contents. Otherwise return the string unchanged as raw HTML.
+ * On read failure, fall back to the raw string and warn — never throw.
+ *
+ * This is a local dev tool, so reading a user-pointed-at local file is acceptable;
+ * the markup/newline guards prevent misclassifying genuine HTML as a path.
+ */
+export function resolveHtmlContent(html: string): string {
+  const trimmed = html.trim();
+  const looksLikePath =
+    trimmed.length > 0 &&
+    trimmed.length <= 1024 &&
+    !trimmed.includes('\n') &&
+    !trimmed.includes('<') &&
+    /\.html?$/i.test(trimmed);
+  if (!looksLikePath) return html;
+
+  const resolved = resolve(trimmed);
+  if (!existsSync(resolved) || !statSync(resolved).isFile()) return html;
+
+  try {
+    return readFileSync(resolved, 'utf-8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[pmx-canvas] html node: failed to read "${resolved}" (${message}); treating --content as raw HTML.`);
+    return html;
+  }
+}
+
 export function addCanvasNode(input: CanvasAddNodeInput): {
   id: string;
   node: CanvasNodeState;
@@ -1471,6 +1512,78 @@ export function createCanvasJsonRenderNode(
   return { id, url: String(node.data.url), spec, node };
 }
 
+/**
+ * Create an empty streaming json-render node. Unlike createCanvasJsonRenderNode
+ * this does NOT validate a complete spec — the node starts blank and is filled
+ * in by appendCanvasJsonRenderStream as SpecStream patches arrive.
+ */
+export function createCanvasStreamingJsonRenderNode(input: {
+  title?: string;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  strictSize?: boolean;
+}): { id: string; url: string; spec: JsonRenderSpec; node: CanvasNodeState } {
+  const spec = emptyStreamingSpec();
+  const width = input.width ?? JSON_RENDER_NODE_SIZE.width;
+  const height = input.height ?? JSON_RENDER_NODE_SIZE.height;
+  const position =
+    input.x !== undefined && input.y !== undefined
+      ? { x: input.x, y: input.y }
+      : findOpenCanvasPosition(canvasState.getLayout().nodes, width, height);
+  const id = `ui-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+  const node: CanvasNodeState = {
+    id,
+    type: 'json-render',
+    position,
+    size: { width, height },
+    zIndex: 1,
+    collapsed: false,
+    pinned: false,
+    dockPosition: null,
+    data: createJsonRenderNodeData(id, input.title?.trim() || 'Streaming', spec, {
+      viewerType: 'json-render',
+      streamStatus: 'open',
+      specVersion: 0,
+      ...(input.strictSize ? { strictSize: true } : {}),
+    }),
+  };
+
+  canvasState.addJsonRenderNode(node);
+  return { id, url: String(node.data.url), spec, node };
+}
+
+/**
+ * Apply a batch of SpecStream patches to an existing json-render node, bumping
+ * its specVersion so the browser reloads the viewer with the accumulated spec.
+ */
+export function appendCanvasJsonRenderStream(
+  nodeId: string,
+  patches: unknown[],
+  done: boolean,
+):
+  | { ok: true; applied: number; skipped: number; specVersion: number; elementCount: number; streamStatus: 'open' | 'closed' }
+  | { ok: false; error: string } {
+  const node = canvasState.getNode(nodeId);
+  if (!node) return { ok: false, error: `Node "${nodeId}" not found.` };
+  if (node.type !== 'json-render') return { ok: false, error: `Node "${nodeId}" is not a json-render node.` };
+
+  const currentSpec = (node.data.spec as JsonRenderSpec | undefined) ?? emptyStreamingSpec();
+  const { spec, applied, skipped } = applyJsonRenderStreamPatches(currentSpec, patches);
+  const prevVersion = typeof node.data.specVersion === 'number' ? node.data.specVersion : 0;
+  const specVersion = prevVersion + 1;
+  const streamStatus: 'open' | 'closed' = done ? 'closed' : 'open';
+
+  canvasState.updateNode(nodeId, {
+    data: { ...node.data, spec, specVersion, streamStatus },
+  });
+
+  const elementCount =
+    spec.elements && typeof spec.elements === 'object' ? Object.keys(spec.elements).length : 0;
+  return { ok: true, applied, skipped, specVersion, elementCount, streamStatus };
+}
+
 export function createCanvasGraphNode(
   input: GraphNodeInput,
 ): { id: string; url: string; spec: JsonRenderSpec; node: CanvasNodeState } {
@@ -1664,14 +1777,22 @@ export async function executeCanvasBatch(
                   ? MARKDOWN_NODE_DEFAULT_SIZE.width
                   : type === 'mcp-app'
                     ? MCP_APP_NODE_DEFAULT_SIZE.width
-                    : 360,
+                    : type === 'image'
+                      ? IMAGE_NODE_DEFAULT_SIZE.width
+                      : type === 'ledger'
+                        ? LEDGER_NODE_DEFAULT_SIZE.width
+                        : 360,
               defaultHeight: type === 'html'
                 ? 640
                 : type === 'markdown'
                   ? MARKDOWN_NODE_DEFAULT_SIZE.height
                   : type === 'mcp-app'
                     ? MCP_APP_NODE_DEFAULT_SIZE.height
-                    : 200,
+                    : type === 'image'
+                      ? IMAGE_NODE_DEFAULT_SIZE.height
+                      : type === 'ledger'
+                        ? LEDGER_NODE_DEFAULT_SIZE.height
+                        : 200,
               fileMode: 'auto',
             });
             result = { ok: true, ...serializeCreatedNode(created.node) };

package/src/server/canvas-schema.ts

@@ -56,6 +56,10 @@ const CANONICAL_GRAPH_TYPES = [
   'radar',
   'stacked-bar',
   'composed',
+  'sparkline',
+  'dot-plot',
+  'bullet',
+  'slopegraph',
 ] as const;
 
 type CanvasGraphType = typeof CANONICAL_GRAPH_TYPES[number];
@@ -406,9 +410,9 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     fields: [
       {
         name: 'graphType',
-        type: '"line" | "bar" | "pie" | "area" | "scatter" | "radar" | "stacked-bar" | "composed"',
+        type: '"line" | "bar" | "pie" | "area" | "scatter" | "radar" | "stacked-bar" | "composed" | "sparkline" | "dot-plot" | "bullet" | "slopegraph"',
         required: true,
-        description: 'Chart type. Aliases like "stack" and "combo" are normalized server-side.',
+        description: 'Chart type. Includes the Tufte primitives sparkline, dot-plot (Cleveland), bullet (Few KPI vs target), and slopegraph (paired before/after). Aliases like "stack", "combo", "dot", and "slope" are normalized server-side.',
         aliases: ['graph-type'],
       },
       { name: 'data', type: 'Record<string, unknown>[]', required: true, description: 'Chart dataset. The CLI also accepts piped JSON via --stdin.', aliases: ['data-json', 'data-file'] },
@@ -417,7 +421,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       { name: 'yKey', type: 'string', required: false, description: 'Y-axis value key for line, bar, area, and scatter charts. Also used as a fallback bar key for composed charts.', aliases: ['y-key'] },
       { name: 'zKey', type: 'string', required: false, description: 'Optional bubble-size key for scatter charts.', aliases: ['z-key'] },
       { name: 'nameKey', type: 'string', required: false, description: 'Slice name key for pie graphs.', aliases: ['name-key'] },
-      { name: 'valueKey', type: 'string', required: false, description: 'Slice value key for pie graphs.', aliases: ['value-key'] },
+      { name: 'valueKey', type: 'string', required: false, description: 'Value key for pie slices, sparkline, dot-plot, and the bullet measure.', aliases: ['value-key'] },
       { name: 'axisKey', type: 'string', required: false, description: 'Category key for radar charts.', aliases: ['axis-key'] },
       { name: 'metrics', type: 'string[]', required: false, description: 'Series keys to plot as radar polygons. Defaults to non-axis numeric columns.' },
       { name: 'series', type: 'string[]', required: false, description: 'Series keys for stacked-bar segments. Defaults to non-x numeric columns.' },
@@ -427,6 +431,14 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       { name: 'color', type: 'string', required: false, description: 'Optional series color for line, bar, area, and scatter charts.' },
       { name: 'barColor', type: 'string', required: false, description: 'Optional bar color for composed charts.', aliases: ['bar-color'] },
       { name: 'lineColor', type: 'string', required: false, description: 'Optional line color for composed charts.', aliases: ['line-color'] },
+      { name: 'colorBy', type: '"series" | "category" | "value" | "none"', required: false, description: 'Bar charts only: how bars are colored. Default "series" (single accent + one highlighted bar). "category" rotates the palette, "value" shades by magnitude, "none" is flat. Color should encode data, not decorate.', aliases: ['color-by'] },
+      { name: 'highlight', type: 'number | "max" | "min"', required: false, description: 'Bar charts (colorBy="series") only: which bar gets the accent — "max" (default), "min", a 0-based index, or null for no emphasis.' },
+      { name: 'labelKey', type: 'string', required: false, description: 'Category label key for dot-plot, bullet, and slopegraph rows.', aliases: ['label-key'] },
+      { name: 'targetKey', type: 'string', required: false, description: 'Per-row target value key for bullet charts.', aliases: ['target-key'] },
+      { name: 'rangesKey', type: 'string', required: false, description: 'Per-row qualitative band thresholds (number[]) key for bullet charts.', aliases: ['ranges-key'] },
+      { name: 'beforeKey', type: 'string', required: false, description: 'Left-column value key for slopegraph.', aliases: ['before-key'] },
+      { name: 'afterKey', type: 'string', required: false, description: 'Right-column value key for slopegraph.', aliases: ['after-key'] },
+      { name: 'sort', type: '"asc" | "desc" | "none"', required: false, description: 'Row sort order for dot-plot (defaults to desc).' },
       { name: 'height', type: 'number', required: false, description: 'Optional chart content height.', aliases: ['chart-height'] },
       { name: 'showLegend', type: 'boolean', required: false, description: 'Show chart legend when supported; pass false for compact node layouts.', aliases: ['show-legend'] },
       { name: 'showLabels', type: 'boolean', required: false, description: 'Show direct labels when supported, such as pie slice labels; defaults to true.', aliases: ['show-labels'] },
@@ -502,6 +514,7 @@ export function describeCanvasSchema(): {
   jsonRender: {
     rootShape: Record<string, string>;
     components: JsonRenderComponentDescriptor[];
+    directives: Array<{ name: string; usage: string }>;
   };
   graph: {
     graphTypes: CanvasGraphType[];
@@ -526,6 +539,16 @@ export function describeCanvasSchema(): {
         state: 'record<string, unknown> | optional',
       },
       components: clone(describeJsonRenderCatalog()),
+      directives: [
+        { name: '$state', usage: '{ "$state": "/path/to/value" } — read a value from the state model by path (one-way). Use this to bind a value by path; there is no $path directive.' },
+        { name: '$format', usage: '{ "$format": "currency"|"number"|"percent"|"date", "value": <num|state-ref>, "currency"?: "USD", "locale"?, "style"?, "options"? } — Intl-formatted string' },
+        { name: '$math', usage: '{ "$math": "add"|"subtract"|"multiply"|"divide"|"mod"|"min"|"max"|"round"|"floor"|"ceil"|"abs", "a": <num>, "b"?: <num> }' },
+        { name: '$concat', usage: '{ "$concat": [<value>, <value>, ...] } — join values into one string' },
+        { name: '$count', usage: '{ "$count": <array|state-ref> } — length of an array' },
+        { name: '$truncate', usage: '{ "$truncate": <string>, "length": <num>, "suffix"?: "…" }' },
+        { name: '$pluralize', usage: '{ "$pluralize": <count>, "one": "item", "other": "items" }' },
+        { name: '$join', usage: '{ "$join": <array>, "separator"?: ", " }' },
+      ],
     },
     graph: {
       graphTypes: [...CANONICAL_GRAPH_TYPES],
@@ -537,6 +560,7 @@ export function describeCanvasSchema(): {
         'canvas_add_html_node',
         'canvas_add_html_primitive',
         'canvas_add_json_render_node',
+        'canvas_stream_json_render_node',
         'canvas_add_graph_node',
         'canvas_build_web_artifact',
         'canvas_open_mcp_app',

package/src/server/canvas-state.ts

@@ -29,8 +29,19 @@ import {
   isDbPopulated,
   checkpointCanvasDb,
   finalizeCanvasDbForClose,
+  appendAxEventToDB,
+  appendAxEvidenceToDB,
+  appendAxSteeringToDB,
+  markAxSteeringDeliveredInDB,
+  loadAxEventsFromDB,
+  loadAxEvidenceFromDB,
+  loadAxSteeringFromDB,
+  loadAxTimelineSummaryFromDB,
+  upsertAxHostCapabilityToDB,
+  loadAxHostCapabilityFromDB,
   type PersistedCanvasState,
   type CanvasTheme,
+  type AxTimelineQuery,
 } from './canvas-db.js';
 import { normalizeCanvasTheme } from './canvas-db.js';
 import {
@@ -43,10 +54,34 @@ import {
 } from './placement.js';
 import {
   createEmptyAxState,
+  createEmptyAxHostCapability,
   normalizeAxState,
+  normalizeAxHostCapability,
+  createAxWorkItem,
+  createAxApprovalGate,
+  createAxReviewAnnotation,
+  createAxEvent,
+  createAxEvidence,
+  createAxSteeringMessage,
   type PmxAxFocusState,
   type PmxAxSource,
   type PmxAxState,
+  type PmxAxWorkItem,
+  type PmxAxWorkItemStatus,
+  type PmxAxApprovalGate,
+  type PmxAxReviewAnnotation,
+  type PmxAxReviewKind,
+  type PmxAxReviewSeverity,
+  type PmxAxReviewStatus,
+  type PmxAxReviewAnchorType,
+  type PmxAxReviewRegion,
+  type PmxAxEvent,
+  type PmxAxEventKind,
+  type PmxAxEvidence,
+  type PmxAxEvidenceKind,
+  type PmxAxSteeringMessage,
+  type PmxAxHostCapability,
+  type PmxAxTimelineSummary,
 } from './ax-state.js';
 
 function logCanvasStateWarning(action: string, error: unknown, details?: Record<string, unknown>): void {
@@ -209,10 +244,10 @@ export interface CanvasNodeUpdate {
   dockPosition?: 'left' | 'right' | null;
 }
 
-export type CanvasChangeType = 'pins' | 'nodes' | 'ax';
+export type CanvasChangeType = 'pins' | 'nodes' | 'ax' | 'ax-timeline';
 
 export interface MutationRecordInfo {
-  operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
+  operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
   description: string;
   forward: () => void;
   inverse: () => void;
@@ -255,6 +290,14 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function replaceById<T extends { id: string }>(list: T[], item: T): T[] {
+  const idx = list.findIndex((x) => x.id === item.id);
+  if (idx === -1) return [...list, item];
+  const copy = list.slice();
+  copy[idx] = item;
+  return copy;
+}
+
 function isPersistedBlobRef(value: unknown): value is PersistedBlobRef {
   return isRecord(value) &&
     value.__pmxCanvasBlob === 'v1' &&
@@ -273,6 +316,7 @@ class CanvasStateManager {
   private _theme: CanvasTheme = 'dark';
   private _contextPinnedNodeIds = new Set<string>();
   private _axState: PmxAxState = createEmptyAxState();
+  private _axHostCapability: PmxAxHostCapability | null = null;
   private _workspaceRoot = process.cwd();
 
   // ── Change listeners (for MCP resource notifications) ──────
@@ -832,6 +876,14 @@ class CanvasStateManager {
 
   /** Load canvas state from SQLite (or legacy JSON fallback). Call once on server startup. */
   loadFromDisk(options: LoadFromDiskOptions = {}): boolean {
+    // Host capability lives in its own table (not snapshotted / not in PmxAxState).
+    if (this._db) {
+      try {
+        this._axHostCapability = loadAxHostCapabilityFromDB(this._db);
+      } catch (error) {
+        logCanvasStateWarning('load host capability failed', error, {});
+      }
+    }
     // Try SQLite first (only if DB has been populated)
     if (this._db && isDbPopulated(this._db)) {
       try {
@@ -1683,6 +1735,298 @@ class CanvasStateManager {
     return this.setAxFocus([], { source: 'system' });
   }
 
+  // ── Work items (canvas-bound; snapshotted via getAxState blob) ────
+  getWorkItems(): PmxAxWorkItem[] {
+    return this.getAxState().workItems;
+  }
+
+  addWorkItem(
+    input: { title: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    options: { source?: PmxAxSource } = {},
+  ): PmxAxWorkItem {
+    const oldAxState = this.getAxState();
+    const item = createAxWorkItem(input, options.source ?? 'api', this.currentNodeIdSet());
+    this.applyAxState({ ...oldAxState, workItems: [...oldAxState.workItems, item] });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'addWorkItem',
+      description: `Added work item "${item.title}"`,
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.workItems.find((w) => w.id === item.id) ?? item;
+  }
+
+  updateWorkItem(
+    id: string,
+    patch: { title?: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    options: { source?: PmxAxSource } = {},
+  ): PmxAxWorkItem | null {
+    const oldAxState = this.getAxState();
+    const existing = oldAxState.workItems.find((w) => w.id === id);
+    if (!existing) return null;
+    const merged: PmxAxWorkItem = {
+      ...existing,
+      ...(patch.title !== undefined ? { title: patch.title } : {}),
+      ...(patch.status !== undefined ? { status: patch.status } : {}),
+      ...(patch.detail !== undefined ? { detail: patch.detail } : {}),
+      ...(patch.nodeIds !== undefined ? { nodeIds: patch.nodeIds.filter((n) => this.nodes.has(n)) } : {}),
+      updatedAt: new Date().toISOString(),
+      source: options.source ?? existing.source,
+    };
+    this.applyAxState({ ...oldAxState, workItems: replaceById(oldAxState.workItems, merged) });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'updateWorkItem',
+      description: `Updated work item ${id}`,
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.workItems.find((w) => w.id === id) ?? null;
+  }
+
+  // ── Approval gates (canvas-bound) ─────────────────────────────────
+  getApprovalGates(): PmxAxApprovalGate[] {
+    return this.getAxState().approvalGates;
+  }
+
+  requestApproval(
+    input: { title: string; detail?: string | null; action?: string | null; nodeIds?: string[] },
+    options: { source?: PmxAxSource } = {},
+  ): PmxAxApprovalGate {
+    const oldAxState = this.getAxState();
+    const gate = createAxApprovalGate(input, options.source ?? 'api', this.currentNodeIdSet());
+    this.applyAxState({ ...oldAxState, approvalGates: [...oldAxState.approvalGates, gate] });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'requestApproval',
+      description: `Requested approval "${gate.title}"`,
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.approvalGates.find((g) => g.id === gate.id) ?? gate;
+  }
+
+  resolveApproval(
+    id: string,
+    decision: 'approved' | 'rejected',
+    options: { resolution?: string; source?: PmxAxSource } = {},
+  ): PmxAxApprovalGate | null {
+    const oldAxState = this.getAxState();
+    const gate = oldAxState.approvalGates.find((g) => g.id === id);
+    if (!gate || gate.status !== 'pending') return null;
+    const resolved: PmxAxApprovalGate = {
+      ...gate,
+      status: decision,
+      resolvedAt: new Date().toISOString(),
+      resolution: options.resolution ?? null,
+      source: options.source ?? gate.source,
+    };
+    this.applyAxState({ ...oldAxState, approvalGates: replaceById(oldAxState.approvalGates, resolved) });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'resolveApproval',
+      description: `Resolved approval ${id} -> ${decision}`,
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.approvalGates.find((g) => g.id === id) ?? null;
+  }
+
+  // ── Review annotations (canvas-bound) ─────────────────────────────
+  getReviewAnnotations(): PmxAxReviewAnnotation[] {
+    return this.getAxState().reviewAnnotations;
+  }
+
+  addReviewAnnotation(
+    input: {
+      body: string;
+      kind?: PmxAxReviewKind;
+      severity?: PmxAxReviewSeverity;
+      anchorType?: PmxAxReviewAnchorType;
+      nodeId?: string | null;
+      file?: string | null;
+      region?: PmxAxReviewRegion | null;
+      author?: string | null;
+    },
+    options: { source?: PmxAxSource } = {},
+  ): PmxAxReviewAnnotation | null {
+    // Validate the node anchor up front. A node-anchored review whose nodeId is
+    // missing or unknown would otherwise be silently dropped by
+    // normalizeAxForCurrentNodes after apply, yet still returned as a phantom
+    // success object — false success / silent data loss. Reject instead so the
+    // HTTP/MCP layers surface ok:false / 4xx.
+    const anchorType = input.anchorType ?? 'node';
+    if (anchorType === 'node' && (typeof input.nodeId !== 'string' || !this.currentNodeIdSet().has(input.nodeId))) {
+      return null;
+    }
+    const oldAxState = this.getAxState();
+    const annotation = createAxReviewAnnotation(input, options.source ?? 'api');
+    this.applyAxState({ ...oldAxState, reviewAnnotations: [...oldAxState.reviewAnnotations, annotation] });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'addReviewAnnotation',
+      description: `Added review ${annotation.kind} (${annotation.severity})`,
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.reviewAnnotations.find((r) => r.id === annotation.id) ?? annotation;
+  }
+
+  updateReviewAnnotation(
+    id: string,
+    patch: { body?: string; status?: PmxAxReviewStatus; severity?: PmxAxReviewSeverity; kind?: PmxAxReviewKind },
+    options: { source?: PmxAxSource } = {},
+  ): PmxAxReviewAnnotation | null {
+    const oldAxState = this.getAxState();
+    const existing = oldAxState.reviewAnnotations.find((r) => r.id === id);
+    if (!existing) return null;
+    const merged: PmxAxReviewAnnotation = {
+      ...existing,
+      ...(patch.body !== undefined ? { body: patch.body } : {}),
+      ...(patch.status !== undefined ? { status: patch.status } : {}),
+      ...(patch.severity !== undefined ? { severity: patch.severity } : {}),
+      ...(patch.kind !== undefined ? { kind: patch.kind } : {}),
+      updatedAt: new Date().toISOString(),
+      source: options.source ?? existing.source,
+    };
+    this.applyAxState({ ...oldAxState, reviewAnnotations: replaceById(oldAxState.reviewAnnotations, merged) });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'updateReviewAnnotation',
+      description: `Updated review ${id}`,
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.reviewAnnotations.find((r) => r.id === id) ?? null;
+  }
+
+  // ── Host capability (own table; reported by adapters) ─────────────
+  getHostCapability(): PmxAxHostCapability | null {
+    return this._axHostCapability;
+  }
+
+  setHostCapability(input: unknown, _options: { source?: PmxAxSource } = {}): PmxAxHostCapability {
+    const cap = normalizeAxHostCapability(
+      isRecord(input)
+        ? { ...input, reportedAt: new Date().toISOString() }
+        : { reportedAt: new Date().toISOString() },
+    ) ?? createEmptyAxHostCapability();
+    this._axHostCapability = cap;
+    if (this._db) {
+      try {
+        upsertAxHostCapabilityToDB(this._db, cap);
+      } catch (error) {
+        logCanvasStateWarning('save host capability failed', error, {});
+      }
+    }
+    this.notifyChange('ax');
+    return cap;
+  }
+
+  // ── Timeline (DB-direct; NOT in _axState; NOT history-recorded) ───
+  recordAxEvent(
+    input: { kind: PmxAxEventKind; summary: string; detail?: string | null; nodeIds?: string[]; data?: Record<string, unknown> | null },
+    options: { source?: PmxAxSource } = {},
+  ): PmxAxEvent {
+    const draft = createAxEvent(input, options.source ?? 'api');
+    if (this._db) {
+      try {
+        const ev = appendAxEventToDB(this._db, draft);
+        this.notifyChange('ax-timeline');
+        return ev;
+      } catch (error) {
+        logCanvasStateWarning('record ax event failed', error, { id: draft.id });
+      }
+    }
+    this.notifyChange('ax-timeline');
+    return { ...draft, seq: 0 };
+  }
+
+  addEvidence(
+    input: { kind: PmxAxEvidenceKind; title: string; body?: string | null; ref?: string | null; nodeIds?: string[]; data?: Record<string, unknown> | null },
+    options: { source?: PmxAxSource } = {},
+  ): PmxAxEvidence {
+    const draft = createAxEvidence(input, options.source ?? 'api');
+    if (this._db) {
+      try {
+        const ev = appendAxEvidenceToDB(this._db, draft);
+        this.notifyChange('ax-timeline');
+        return ev;
+      } catch (error) {
+        logCanvasStateWarning('add evidence failed', error, { id: draft.id });
+      }
+    }
+    this.notifyChange('ax-timeline');
+    return { ...draft, seq: 0 };
+  }
+
+  recordSteeringMessage(message: string, options: { source?: PmxAxSource } = {}): PmxAxSteeringMessage {
+    const draft = createAxSteeringMessage(message, options.source ?? 'api');
+    if (this._db) {
+      try {
+        const s = appendAxSteeringToDB(this._db, draft);
+        this.notifyChange('ax-timeline');
+        return s;
+      } catch (error) {
+        logCanvasStateWarning('record steering failed', error, { id: draft.id });
+      }
+    }
+    this.notifyChange('ax-timeline');
+    return { ...draft, seq: 0 };
+  }
+
+  markSteeringDelivered(id: string): boolean {
+    if (!this._db) return false;
+    try {
+      const ok = markAxSteeringDeliveredInDB(this._db, id);
+      if (ok) this.notifyChange('ax-timeline');
+      return ok;
+    } catch (error) {
+      logCanvasStateWarning('mark steering delivered failed', error, { id });
+      return false;
+    }
+  }
+
+  getAxEvents(q: AxTimelineQuery = {}): PmxAxEvent[] {
+    return this._db ? loadAxEventsFromDB(this._db, q) : [];
+  }
+
+  getAxEvidence(q: AxTimelineQuery = {}): PmxAxEvidence[] {
+    return this._db ? loadAxEvidenceFromDB(this._db, q) : [];
+  }
+
+  getAxSteering(q: AxTimelineQuery & { onlyPending?: boolean } = {}): PmxAxSteeringMessage[] {
+    return this._db ? loadAxSteeringFromDB(this._db, q) : [];
+  }
+
+  getAxTimelineSummary(): PmxAxTimelineSummary {
+    return this._db
+      ? loadAxTimelineSummaryFromDB(this._db)
+      : { recentEvents: [], recentEvidence: [], pendingSteering: [], counts: { events: 0, evidence: 0, steering: 0 } };
+  }
+
+  getAxTimeline(q: AxTimelineQuery = {}): { events: PmxAxEvent[]; evidence: PmxAxEvidence[]; steering: PmxAxSteeringMessage[]; summary: PmxAxTimelineSummary } {
+    return {
+      events: this.getAxEvents(q),
+      evidence: this.getAxEvidence(q),
+      steering: this.getAxSteering(q),
+      summary: this.getAxTimelineSummary(),
+    };
+  }
+
   setContextPins(nodeIds: string[]): void {
     const oldPins = Array.from(this._contextPinnedNodeIds);
     this._contextPinnedNodeIds.clear();
@@ -1814,6 +2158,9 @@ class CanvasStateManager {
     this.edges.clear();
     this.annotations.clear();
     this._contextPinnedNodeIds.clear();
+    // Clears canvas-bound AX state (focus, work items, approvals, review annotations).
+    // Timeline tables (ax_events/ax_evidence/ax_steering) and host capability are
+    // deliberately retained per the AX state-partition policy.
     this._axState = createEmptyAxState();
     this._viewport = { x: 0, y: 0, scale: 1 };
     this.scheduleSave();