pmx-canvas 0.9.3 → 0.11.0

package/src/client/theme/surface-theme.css

@@ -21,12 +21,12 @@
   /* ── Core palette (dark · ink + cyan) ────────────────────── */
   --c-bg: #081524;
   --c-panel: #0f1d31;
-  --c-panel-soft: #0a1729;
+  --c-panel-soft: #13243b;
   --c-line: #1b2c44;
   --c-text: #e6eef7;
-  --c-text-soft: #c7d3ea;
+  --c-text-soft: #b9c6d6;
   --c-muted: #8ea3bd;
-  --c-dim: #5c6b80;
+  --c-dim: #6b7d94;
   --c-accent: #4BBCFF;
   --c-ok: #2fd07f;
   --c-warn: #f4c542;
@@ -46,13 +46,13 @@
   /* Common aliases authored HTML might use. */
   --color-bg: #081524;
   --color-panel: #0f1d31;
-  --color-surface: #0a1729;
+  --color-surface: #13243b;
   --color-border: #1b2c44;
   --color-text: #e6eef7;
   --color-text-primary: #e6eef7;
-  --color-text-secondary: #c7d3ea;
+  --color-text-secondary: #b9c6d6;
   --color-text-muted: #8ea3bd;
-  --color-text-dim: #5c6b80;
+  --color-text-dim: #6b7d94;
   --color-accent: #4BBCFF;
   --color-success: #2fd07f;
   --color-warning: #f4c542;

package/src/json-render/charts/tufte-components.tsx

@@ -336,6 +336,18 @@ interface SlopegraphProps {
   height?: number | null;
 }
 
+/** Separate close labels without moving the data points they describe. */
+function slopeLabelPositions(values: number[], top: number, bottom: number): number[] {
+  const order = values.map((y, index) => ({ y, index })).sort((a, b) => a.y - b.y);
+  const gap = Math.min(14, (bottom - top) / Math.max(1, order.length - 1));
+  for (let i = 1; i < order.length; i++) order[i].y = Math.max(order[i].y, order[i - 1].y + gap);
+  if (order.length) order[order.length - 1].y = Math.min(order[order.length - 1].y, bottom);
+  for (let i = order.length - 2; i >= 0; i--) order[i].y = Math.min(order[i].y, order[i + 1].y - gap);
+  const result = [...values];
+  for (const { y, index } of order) result[index] = y;
+  return result;
+}
+
 function ChartSlopegraph({ props }: BaseComponentProps<SlopegraphProps>) {
   const stroke = props.color ?? ACCENT;
   const rows = (props.data ?? []).map((row) => ({
@@ -359,6 +371,16 @@ function ChartSlopegraph({ props }: BaseComponentProps<SlopegraphProps>) {
   // fills without pushing a scrollbar onto the iframe document.
   const plotH = chartPlotHeight(height, Boolean(props.title));
   const scaleY = (v: number) => topPad + (1 - (v - min) / (max - min)) * (plotH - topPad - botPad);
+  const beforeLabels = slopeLabelPositions(
+    rows.map((row) => scaleY(row.before)),
+    topPad,
+    plotH - botPad,
+  );
+  const afterLabels = slopeLabelPositions(
+    rows.map((row) => scaleY(row.after)),
+    topPad,
+    plotH - botPad,
+  );
 
   return (
     <div ref={frameRef} className="pmx-chart pmx-chart--slopegraph" style={{ height }}>
@@ -390,10 +412,30 @@ function ChartSlopegraph({ props }: BaseComponentProps<SlopegraphProps>) {
               <line x1={leftX} y1={y1} x2={rightX} y2={y2} stroke={lineColor} strokeWidth={1.5} />
               <circle cx={leftX} cy={y1} r={2.5} fill={lineColor} />
               <circle cx={rightX} cy={y2} r={2.5} fill={lineColor} />
-              <text x={leftX - 8} y={y1} textAnchor="end" dominantBaseline="central" fontSize={11} fill={INK}>
+              {beforeLabels[i] !== y1 && (
+                <line x1={leftX} y1={y1} x2={leftX - 5} y2={beforeLabels[i]} stroke={lineColor} />
+              )}
+              {afterLabels[i] !== y2 && (
+                <line x1={rightX} y1={y2} x2={rightX + 5} y2={afterLabels[i]} stroke={lineColor} />
+              )}
+              <text
+                x={leftX - 8}
+                y={beforeLabels[i]}
+                textAnchor="end"
+                dominantBaseline="central"
+                fontSize={11}
+                fill={INK}
+              >
                 {`${row.label}  ${row.before}`}
               </text>
-              <text x={rightX + 8} y={y2} textAnchor="start" dominantBaseline="central" fontSize={11} fill={INK}>
+              <text
+                x={rightX + 8}
+                y={afterLabels[i]}
+                textAnchor="start"
+                dominantBaseline="central"
+                fontSize={11}
+                fill={INK}
+              >
                 {`${row.after}  ${row.label}`}
               </text>
             </g>

package/src/json-render/renderer/index.css

@@ -3,7 +3,7 @@
 
 @source "../../../../node_modules/@json-render/shadcn/dist/index.js";
 
-@custom-variant dark (&:is([data-theme="dark"] *));
+@custom-variant dark (&:is(.dark *));
 
 @theme {
   --font-sans: "IBM Plex Sans", system-ui, sans-serif;
@@ -99,6 +99,66 @@
   --chart-6: #ffffff;
 }
 
+/* Named themes share the canvas surface, including nested cards and charts.
+   Explicit dark/light remain available for authored design experiments. */
+:root[data-canvas-theme] {
+  --radius: 6px;
+  --text-xs: 11px;
+  --text-sm: 12px;
+  --text-base: 13px;
+  --text-lg: 15px;
+  --text-xl: 20px;
+  --background: var(--c-panel);
+  --foreground: var(--c-text);
+  --card: var(--c-panel-soft);
+  --card-foreground: var(--c-text);
+  --popover: var(--c-panel);
+  --popover-foreground: var(--c-text);
+  --primary: var(--c-accent);
+  --primary-foreground: var(--c-on-accent, var(--c-on-pin));
+  --secondary: var(--c-panel-soft);
+  --secondary-foreground: var(--c-text);
+  --muted: var(--c-panel-soft);
+  --muted-foreground: var(--c-muted);
+  --accent: var(--c-panel-soft);
+  --accent-foreground: var(--c-text);
+  --destructive: var(--c-danger);
+  --border: var(--c-line);
+  --input: var(--c-line);
+  --ring: var(--c-accent);
+  --chart-1: var(--c-accent);
+  --chart-2: var(--c-rel-supports);
+  --chart-3: var(--c-rel-contradicts);
+  --chart-4: var(--c-rel-cites);
+  --chart-5: var(--c-rel-informs);
+  --chart-6: var(--c-muted);
+  font-size: 16px;
+}
+
+/* surface-theme's unlayered body rule otherwise wins over Tailwind's base layer. */
+body {
+  background: var(--background);
+  color: var(--foreground);
+  padding: 0;
+  font-family: var(--font-sans);
+  font-size: 13px;
+}
+
+.pmx-viewer-root { width: 100%; min-width: 0; }
+[data-embedded] .pmx-viewer-root:not(:has(> [data-slot="card"])) { padding: 12px 14px; }
+[data-embedded] .pmx-viewer-root > [data-slot="card"] {
+  width: 100%;
+  max-width: none;
+  border: 0;
+  border-radius: 0;
+  box-shadow: none;
+  background: transparent;
+  padding: 12px 14px;
+}
+[data-embedded][data-duplicate-title] .pmx-viewer-root > [data-slot="card"] > [data-slot="card-header"] > [data-slot="card-title"] { display: none; }
+[data-embedded][data-duplicate-title] .pmx-viewer-root > [data-slot="card"] > [data-slot="card-header"]:not(:has([data-slot="card-description"])) { display: none; }
+[data-embedded] .pmx-viewer-root > [data-slot="card"] > [data-slot="card-content"] { padding: 0; }
+
 @theme inline {
   --radius-sm: calc(var(--radius) - 4px);
   --radius-md: calc(var(--radius) - 2px);
@@ -159,7 +219,7 @@ button {
   border: 1px solid transparent;
   border-radius: 9999px;
   padding: 0.125rem 0.5rem;
-  font-size: 0.75rem;
+  font-size: max(11px, 0.75rem);
   font-weight: 500;
   line-height: 1.25rem;
 }

package/src/json-render/renderer/index.tsx

@@ -23,6 +23,7 @@ import { extraChartComponents } from '../charts/extra-components';
 import { tufteChartComponents } from '../charts/tufte-components';
 import { pmxCanvasDirectives } from '../directives';
 import { JsonRenderDevtools } from '@json-render/devtools-react';
+import { canvasThemeScheme, isCanvasTheme } from '../../shared/themes.js';
 
 type BadgeVariant =
   | 'default'
@@ -167,10 +168,12 @@ function syncPreferredTheme(): void {
 }
 
 function applyTheme(theme: unknown): void {
-  if (theme !== 'dark' && theme !== 'light' && theme !== 'high-contrast') return;
+  if (theme !== 'dark' && theme !== 'light' && !isCanvasTheme(theme)) return;
   document.documentElement.setAttribute('data-theme', theme);
-  document.documentElement.classList.toggle('dark', theme === 'dark' || theme === 'high-contrast');
-  document.documentElement.style.colorScheme = theme === 'light' ? 'light' : 'dark';
+  document.documentElement.toggleAttribute('data-canvas-theme', isCanvasTheme(theme));
+  const scheme = theme === 'light' ? 'light' : canvasThemeScheme(theme);
+  document.documentElement.classList.toggle('dark', scheme === 'dark');
+  document.documentElement.style.colorScheme = scheme;
 }
 
 function App({ store }: { store: StateStore }) {
@@ -235,11 +238,15 @@ function App({ store }: { store: StateStore }) {
         padding: 0,
         boxSizing: 'border-box' as const,
       }
-    : { minHeight: '100vh', padding: 16, boxSizing: 'border-box' as const };
+    : { minHeight: '100vh', padding: 0, boxSizing: 'border-box' as const };
   return (
-    <div style={containerStyle}>
+    <div
+      style={containerStyle}
+      data-embedded={!isSite ? '' : undefined}
+      data-duplicate-title={spec.elements[spec.root]?.props?.title === document.title ? '' : undefined}
+    >
       <JSONUIProvider registry={registry} store={store} directives={pmxCanvasDirectives} handlers={buildAxHandlers()}>
-        <div style={isSite ? { flex: 1, minHeight: 0 } : undefined}>
+        <div className="pmx-viewer-root" style={isSite ? { flex: 1, minHeight: 0 } : undefined}>
           <Renderer spec={spec} registry={registry} loading={false} />
         </div>
         {window.__PMX_CANVAS_JSON_RENDER_DEVTOOLS__ ? <JsonRenderDevtools position="right" /> : null}
@@ -282,8 +289,25 @@ if (root) {
   // Standalone viewers have no state token and render immediately.
   window.addEventListener('message', (event: MessageEvent) => {
     if (event.source !== window.parent) return;
-    const m = event.data as { source?: string; type?: string; token?: string; state?: unknown } | null;
+    const m = event.data as {
+      source?: string;
+      type?: string;
+      token?: string;
+      state?: unknown;
+      theme?: unknown;
+      title?: unknown;
+    } | null;
     if (!m) return;
+    if (m.source === HTML_SURFACE_PUSH_SOURCE && m.type === 'theme-update' && stateToken && m.token === stateToken) {
+      applyTheme(m.theme);
+      if (typeof m.title === 'string') {
+        document.title = m.title;
+        const spec = window.__PMX_CANVAS_JSON_RENDER_SPEC__;
+        document
+          .querySelector('[data-embedded]')
+          ?.toggleAttribute('data-duplicate-title', spec?.elements[spec.root]?.props?.title === m.title);
+      }
+    }
     if (m.source === JSON_VIEWER_STATE_SOURCE && m.type === 'restore' && stateToken && m.token === stateToken) {
       if (m.state === null || (typeof m.state === 'object' && !Array.isArray(m.state)))
         mount(m.state as Record<string, unknown> | null);

package/src/json-render/server.ts

@@ -6,6 +6,7 @@ import { applySpecPatch, parseSpecStreamLine, type Spec, type SpecStreamLine } f
 import { allComponentDefinitions, catalog, validateShadcnElementProps, type JsonRenderIssue } from './catalog.js';
 import { findUnknownDirectiveKey, isDynamicPropValue } from './directives.js';
 import { contentHeightReporterTag } from '../shared/content-height-reporter.js';
+import type { CanvasThemeName } from '../shared/themes.js';
 
 export interface JsonRenderSpec {
   root: string;
@@ -1030,7 +1031,7 @@ export async function readJsonRenderBundle(): Promise<{ js: string; css: string
 export async function buildJsonRenderViewerHtml(options: {
   title: string;
   spec: JsonRenderSpec;
-  theme?: 'dark' | 'light' | 'high-contrast';
+  theme?: CanvasThemeName | 'dark' | 'light';
   display?: 'expanded' | 'site';
   devtools?: boolean;
   nodeId?: string;
@@ -1076,7 +1077,7 @@ export async function buildJsonRenderViewerHtml(options: {
     const heightReporter = options.frameToken ? contentHeightReporterTag(options.frameToken) : '';
     return buildAppHtml({
       title: options.title,
-      css: cssBundle,
+      css: `${readFileSync(join(import.meta.dir, '../client/theme/surface-theme.css'), 'utf-8')}\n${cssBundle}`,
       js: escapeInlineScriptSource(boot),
       head: `<meta name="color-scheme" content="light dark" />${heightReporter}`,
     });

package/src/mcp/canvas-access.ts

@@ -2,7 +2,6 @@ import { realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, resolve } from 'node:path';
 import { createCanvas, canvasState, type CanvasLayout, type CanvasNodeState, type PmxCanvas } from '../server/index.js';
-import type { PmxAxSource } from '../server/ax-state.js';
 import type { ContextReadInput } from '../server/context-reads.js';
 import { HttpOperationInvoker, LocalOperationInvoker, type OperationInvoker } from '../server/operations/index.js';
 
@@ -14,13 +13,9 @@ import { HttpOperationInvoker, LocalOperationInvoker, type OperationInvoker } fr
 // not CanvasAccess. The public SDK PmxCanvas methods are unchanged.
 type AxStateResult = ReturnType<PmxCanvas['getAxState']>;
 type AxContextResult = ReturnType<PmxCanvas['getAxContext']>;
-type SubmitAxInteractionInput = Parameters<PmxCanvas['submitAxInteraction']>[0];
-type SubmitAxInteractionResult = ReturnType<PmxCanvas['submitAxInteraction']>;
 type GetPendingSteeringResult = ReturnType<PmxCanvas['getPendingSteering']>;
 type ListElicitationsResult = ReturnType<PmxCanvas['listElicitations']>;
 type ListModeRequestsResult = ReturnType<PmxCanvas['listModeRequests']>;
-type IngestActivityInput = Parameters<PmxCanvas['ingestActivity']>[0];
-type IngestActivityResult = ReturnType<PmxCanvas['ingestActivity']>;
 type GetPolicyResult = ReturnType<PmxCanvas['getPolicy']>;
 type GetAxTimelineQuery = Parameters<PmxCanvas['getAxTimeline']>[0];
 type GetAxTimelineResult = ReturnType<PmxCanvas['getAxTimeline']>;
@@ -56,14 +51,9 @@ export interface CanvasAccess {
   listWorkItems(): Promise<ListWorkItemsResult>;
   listApprovalGates(): Promise<ListApprovalGatesResult>;
   listReviewAnnotations(): Promise<ListReviewAnnotationsResult>;
-  submitAxInteraction(
-    input: SubmitAxInteractionInput,
-    options?: { source?: PmxAxSource },
-  ): Promise<SubmitAxInteractionResult>;
   getPendingSteering(options?: { consumer?: string; limit?: number }): Promise<GetPendingSteeringResult>;
   listElicitations(): Promise<ListElicitationsResult>;
   listModeRequests(): Promise<ListModeRequestsResult>;
-  ingestActivity(input: IngestActivityInput, options?: { source?: PmxAxSource }): Promise<IngestActivityResult>;
   getPolicy(): Promise<GetPolicyResult>;
   getHistory(): Promise<HistoryResult>;
   getPinnedNodeIds(board?: string): Promise<string[]>;
@@ -75,7 +65,7 @@ export interface CanvasAccess {
   // canvas_screenshot (still hand-written — binary payload) is the only webview
   // tool left on CanvasAccess; it needs the status + screenshot accessors.
   getAutomationWebViewStatus(): Promise<AutomationWebViewStatus>;
-  screenshotAutomationWebView(options?: AutomationScreenshotOptions): Promise<Uint8Array>;
+  screenshotAutomationWebView(options?: AutomationScreenshotOptions, signal?: AbortSignal): Promise<Uint8Array>;
 }
 
 class LocalCanvasAccess implements CanvasAccess {
@@ -123,13 +113,6 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.getAxTimeline(query);
   }
 
-  async submitAxInteraction(
-    input: SubmitAxInteractionInput,
-    options?: { source?: PmxAxSource },
-  ): Promise<SubmitAxInteractionResult> {
-    return this.canvas.submitAxInteraction(input, { source: options?.source ?? 'mcp' });
-  }
-
   async getPendingSteering(options?: { consumer?: string; limit?: number }): Promise<GetPendingSteeringResult> {
     return this.canvas.getPendingSteering(options);
   }
@@ -142,10 +125,6 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.listModeRequests();
   }
 
-  async ingestActivity(input: IngestActivityInput, options?: { source?: PmxAxSource }): Promise<IngestActivityResult> {
-    return this.canvas.ingestActivity(input, { source: options?.source ?? 'mcp' });
-  }
-
   async getPolicy(): Promise<GetPolicyResult> {
     return this.canvas.getPolicy();
   }
@@ -299,23 +278,6 @@ class RemoteCanvasAccess implements CanvasAccess {
     return await this.requestJson<GetAxTimelineResult>('GET', `/api/canvas/ax/timeline${qs}`);
   }
 
-  async submitAxInteraction(
-    input: SubmitAxInteractionInput,
-    options?: { source?: PmxAxSource },
-  ): Promise<SubmitAxInteractionResult> {
-    // The interaction endpoint returns its structured outcome (ok/code/error) in
-    // the body for both accepted and rejected interactions, so read the body
-    // regardless of HTTP status rather than throwing on a denial.
-    const response = await fetch(`${this.remoteBaseUrl}/api/canvas/ax/interaction`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ ...input, source: options?.source ?? 'mcp' }),
-    });
-    const body = await response.json().catch(() => null);
-    if (body && typeof body === 'object') return body as SubmitAxInteractionResult;
-    throw new Error(`Remote canvas interaction failed with HTTP ${response.status}`);
-  }
-
   async getPendingSteering(options?: { consumer?: string; limit?: number }): Promise<GetPendingSteeringResult> {
     const params = new URLSearchParams();
     if (options?.consumer) params.set('consumer', options.consumer);
@@ -338,13 +300,6 @@ class RemoteCanvasAccess implements CanvasAccess {
     return r.modeRequests ?? [];
   }
 
-  async ingestActivity(input: IngestActivityInput, options?: { source?: PmxAxSource }): Promise<IngestActivityResult> {
-    return await this.requestJson<IngestActivityResult>('POST', '/api/canvas/ax/activity', {
-      ...input,
-      source: options?.source ?? 'mcp',
-    });
-  }
-
   async getPolicy(): Promise<GetPolicyResult> {
     const r = await this.requestJson<{ policy?: GetPolicyResult }>('GET', '/api/canvas/ax/policy');
     if (!r.policy) throw new Error('Remote canvas did not return a policy.');
@@ -404,11 +359,15 @@ class RemoteCanvasAccess implements CanvasAccess {
     return await this.requestJson<AutomationWebViewStatus>('GET', '/api/workbench/webview');
   }
 
-  async screenshotAutomationWebView(options: AutomationScreenshotOptions = {}): Promise<Uint8Array> {
+  async screenshotAutomationWebView(
+    options: AutomationScreenshotOptions = {},
+    signal?: AbortSignal,
+  ): Promise<Uint8Array> {
     const response = await fetch(`${this.remoteBaseUrl}/api/workbench/webview/screenshot`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(options),
+      signal,
     });
     if (!response.ok) {
       const text = await response.text();

package/src/mcp/resource-subscriptions.ts

@@ -0,0 +1,181 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import {
+  ErrorCode,
+  McpError,
+  SubscribeRequestSchema,
+  UnsubscribeRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { canvasState } from '../server/canvas-state.js';
+import { onWorkbenchEvent } from '../server/server.js';
+import type { CanvasAccess } from './canvas-access.js';
+import { ContextUriTemplate } from './context-uri-template.js';
+
+const liveResources = new Set(
+  [
+    'layout',
+    'boards',
+    'summary',
+    'context',
+    'graph',
+    'spatial-context',
+    'history',
+    'code-graph',
+    'pinned-context',
+    'ax',
+    'ax-context',
+    'ax-timeline',
+    'ax-work',
+    'ax-pending-steering',
+    'ax-delivery',
+  ].map((name) => `canvas://${name}`),
+);
+const contextTemplate = new ContextUriTemplate();
+const graphTemplate = new ContextUriTemplate('graph', ['focus', 'depth']);
+
+// A context-status-changed read receipt must never trigger another read forever.
+const resourceEvents = new Set([
+  'context-pins-changed',
+  'boards-changed',
+  'knowledge-changed',
+  'ax-state-changed',
+  'ax-event-created',
+  'canvas-layout-update',
+  'canvas-viewport-update',
+  'canvas-camera-move',
+  'canvas-tour-step',
+  'canvas-tour-exit',
+  // These events synchronize node data inside server.ts.
+  'workbench-open',
+  'ext-app-open',
+  'ext-app-update',
+  'ext-app-result',
+  'context-cards',
+  'context-usage',
+  'aux-open',
+  'aux-close',
+  'canvas-status',
+  'execution-phase',
+  'canvas-response-start',
+  'canvas-response-delta',
+  'canvas-response-complete',
+]);
+
+function isLiveResource(uri: string): boolean {
+  return liveResources.has(uri) || contextTemplate.match(uri) !== null || graphTemplate.match(uri) !== null;
+}
+
+/** One subscription set and event source per MCP connection. Notifications are not reads. */
+export function registerResourceSubscriptions(server: McpServer, getCanvas: () => Promise<CanvasAccess>) {
+  const subscriptions = new Set<string>();
+  let disposeSource: (() => void) | undefined;
+  let source: string | null | undefined;
+  let closed = false;
+
+  function notify(): void {
+    // Broad invalidation is intentional: context projections span pins, nodes and AX.
+    for (const uri of subscriptions) {
+      void server.server.sendResourceUpdated({ uri }).catch((error: unknown) => {
+        if (!closed) console.error('[mcp] resource notification failed:', error);
+      });
+    }
+  }
+
+  async function watchRemote(baseUrl: string, signal: AbortSignal): Promise<void> {
+    while (!signal.aborted) {
+      try {
+        const response = await fetch(`${baseUrl}/api/workbench/events`, { signal });
+        if (!response.ok || !response.body) throw new Error(`Canvas event stream: HTTP ${response.status}`);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+          // Reconnecting may have missed a change. Invalidate subscribed URIs only.
+          notify();
+          while (!signal.aborted) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const frames = buffer.split('\n\n');
+            buffer = frames.pop() ?? '';
+            for (const frame of frames) {
+              const event = frame
+                .split('\n')
+                .find((line) => line.startsWith('event:'))
+                ?.slice(6)
+                .trim();
+              if (event && resourceEvents.has(event)) notify();
+            }
+          }
+        } finally {
+          await reader.cancel().catch(() => {});
+          reader.releaseLock();
+        }
+      } catch (error) {
+        if (signal.aborted) return;
+        console.error('[mcp] canvas event stream disconnected:', error);
+      }
+      try {
+        await delay(1_000, undefined, { signal });
+      } catch {
+        return;
+      }
+    }
+  }
+
+  function attach(canvas: CanvasAccess): void {
+    if (closed || subscriptions.size === 0 || source === canvas.remoteBaseUrl) return;
+    disposeSource?.();
+    source = canvas.remoteBaseUrl;
+    if (source) {
+      const controller = new AbortController();
+      disposeSource = () => controller.abort();
+      void watchRemote(source, controller.signal);
+    } else {
+      const disposeState = canvasState.onChange(notify);
+      // Library-only writes do not change the active board's state.
+      const disposeEvents = onWorkbenchEvent((event) => {
+        if (resourceEvents.has(event)) notify();
+      });
+      disposeSource = () => {
+        disposeState();
+        disposeEvents();
+      };
+    }
+  }
+
+  function dispose(): void {
+    closed = true;
+    subscriptions.clear();
+    disposeSource?.();
+    disposeSource = undefined;
+    source = undefined;
+  }
+
+  server.server.registerCapabilities({ resources: { subscribe: true } });
+  server.server.setRequestHandler(SubscribeRequestSchema, async ({ params }, extra) => {
+    if (!isLiveResource(params.uri))
+      throw new McpError(ErrorCode.InvalidParams, `Resource does not support subscriptions: ${params.uri}`);
+    const canvas = await getCanvas();
+    extra.signal.throwIfAborted();
+    if (closed) throw new McpError(ErrorCode.InternalError, 'Connection closed');
+    subscriptions.add(params.uri);
+    attach(canvas);
+    return {};
+  });
+  server.server.setRequestHandler(UnsubscribeRequestSchema, ({ params }) => {
+    subscriptions.delete(params.uri);
+    if (subscriptions.size === 0) {
+      disposeSource?.();
+      disposeSource = undefined;
+      source = undefined;
+    }
+    return {};
+  });
+  const onclose = server.server.onclose;
+  server.server.onclose = () => {
+    dispose();
+    onclose?.();
+  };
+  return { attach, dispose };
+}