pmx-canvas 0.9.3 → 0.11.0

package/src/server/html-primitives.ts

@@ -812,13 +812,12 @@ function page(input: {
   * { box-sizing: border-box; }
   body { margin: 0; padding: 22px; background: radial-gradient(circle at top left, color-mix(in srgb, var(--color-accent, #4a9eff) 18%, transparent), transparent 34rem), var(--color-bg, #0b0f14); color: var(--color-text, #e8edf2); font-family: var(--font-sans, ui-sans-serif, system-ui, sans-serif); }
   .shell { max-width: 1160px; margin: 0 auto; }
-  header.hero { display: grid; grid-template-columns: 1fr auto; gap: 16px; align-items: start; margin-bottom: 20px; }
+  header.hero { margin-bottom: 20px; }
   .kicker { color: var(--color-accent, #4a9eff); text-transform: uppercase; letter-spacing: .16em; font-size: 11px; font-weight: 800; }
   h1 { margin: 5px 0 8px; font-size: clamp(28px, 4vw, 46px); line-height: .95; letter-spacing: -.04em; }
   h2 { margin: 0 0 12px; font-size: 19px; letter-spacing: -.02em; }
   h3 { margin: 0 0 8px; font-size: 15px; }
   p { color: var(--color-text-secondary, #aeb8c2); margin: 0 0 12px; }
-  .actions { display: flex; gap: 8px; flex-wrap: wrap; justify-content: flex-end; }
   button { border: 1px solid var(--color-border, #263241); background: var(--color-panel, #111821); color: var(--color-text, #e8edf2); border-radius: 999px; padding: 8px 12px; font: inherit; cursor: pointer; }
   button:hover { border-color: var(--color-accent, #4a9eff); transform: translateY(-1px); }
   table { width: 100%; border-collapse: collapse; color: var(--color-text-secondary, #aeb8c2); font-size: 13px; }
@@ -861,20 +860,20 @@ function page(input: {
   .slide h2 { font-size: clamp(30px, 5vw, 58px); line-height: .95; }
   .preview { white-space: pre-wrap; min-height: 220px; }
   .figure svg { width: 100%; min-height: 220px; border-radius: 14px; background: color-mix(in srgb, var(--color-bg, #0b0f14) 86%, white); border: 1px solid var(--color-border, #263241); }
-  @media (max-width: 760px) { body { padding: 14px; } header.hero, .two, .three { grid-template-columns: 1fr; } .actions { justify-content: flex-start; } .sticky { position: static; } }
+  @media (max-width: 760px) { body { padding: 14px; } .two, .three { grid-template-columns: 1fr; } .sticky { position: static; } }
 </style>
 </head>
 <body>
 <div class="shell">
   <header class="hero">
     <div><div class="kicker">PMX HTML primitive / ${escapeHtml(input.kind)}</div><h1>${escapeHtml(input.title)}</h1><p>${escapeHtml(input.summary)}</p></div>
-    <div class="actions"><button type="button" data-copy-json>Copy JSON</button><button type="button" data-copy-prompt>Copy prompt</button></div>
   </header>
   ${input.body}
 </div>
 <script type="application/json" id="pmx-data">${safeJson(input.data)}</script>
 <script>
 const PMX_DATA = JSON.parse(document.getElementById('pmx-data').textContent);
+window.__pmxGetCopyJson = () => PMX_DATA;
 function fallbackCopy(text) {
   const el = document.createElement('textarea');
   el.value = text;
@@ -890,11 +889,6 @@ async function copyText(text) {
   if (navigator.clipboard && window.isSecureContext) await navigator.clipboard.writeText(text);
   else fallbackCopy(text);
 }
-document.querySelector('[data-copy-json]')?.addEventListener('click', () => {
-  const payload = typeof window.__pmxGetCopyJson === 'function' ? window.__pmxGetCopyJson() : PMX_DATA;
-  copyText(JSON.stringify(payload, null, 2));
-});
-document.querySelector('[data-copy-prompt]')?.addEventListener('click', () => copyText('Use this PMX Canvas HTML primitive output as context:\\n\\n' + JSON.stringify(PMX_DATA, null, 2)));
 ${input.script ?? ''}
 </script>
 </body>

package/src/server/html-surface.ts

@@ -61,6 +61,14 @@ const PMX_CANVAS_THEME_TOKEN = ${token};
 window.addEventListener('message', (event) => {
   const message = event.data;
   if (event.source !== window.parent || !message || message.source !== '${HTML_SURFACE_PUSH_SOURCE}' || message.token !== PMX_CANVAS_THEME_TOKEN) return;
+  if (message.type === 'copy-json' && PMX_CANVAS_THEME_TOKEN && typeof message.requestId === 'string') {
+    let json;
+    try {
+      if (typeof window.__pmxGetCopyJson === 'function') json = JSON.stringify(window.__pmxGetCopyJson(), null, 2);
+    } catch {}
+    window.parent.postMessage({ source: '${HTML_SURFACE_PUSH_SOURCE}', type: 'copy-json-result', token: PMX_CANVAS_THEME_TOKEN, requestId: message.requestId, json }, '*');
+    return;
+  }
   if (message.type === 'check-ready') {
     const reply = (type) => window.parent.postMessage({ source: '${HTML_SURFACE_PUSH_SOURCE}', type, token: PMX_CANVAS_THEME_TOKEN }, '*');
     reply('mounted');

package/src/server/index.ts

@@ -1,8 +1,17 @@
 import { EventEmitter } from 'node:events';
-import type { Camera, Tour, TourStop } from '../shared/tour.js';
-import { currentTour, exitTour, goToTourStop, moveCamera, type TourStep, type TourStepResult } from './tour-control.js';
-export type { Tour, TourStop } from '../shared/tour.js';
-export type { TourStep, TourStepResult } from './tour-control.js';
+import type { Camera, Tour, TourPresenter, TourStop } from '../shared/tour.js';
+import {
+  currentTour,
+  exitTour,
+  goToTourStop,
+  moveCamera,
+  type TourState,
+  type TourStep,
+  type TourStepResult,
+  type TourSuperseded,
+} from './tour-control.js';
+export type { Tour, TourPresenter, TourStop } from '../shared/tour.js';
+export type { TourState, TourStep, TourStepResult, TourSuperseded } from './tour-control.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';
@@ -612,8 +621,8 @@ export class PmxCanvas extends EventEmitter {
     );
   }
 
-  getTour(): Tour {
-    return currentTour().tour;
+  getTour(): TourState {
+    return currentTour();
   }
 
   setTour(tour: Tour | null): void {
@@ -623,16 +632,25 @@ export class PmxCanvas extends EventEmitter {
   }
 
   /** Present a tour stop (index, `next` or `previous`) in the workbench. Not recorded in undo history. */
-  goToTourStop(step: TourStep, options?: { present?: boolean }): TourStepResult {
-    const result = goToTourStop(step);
-    emitPrimaryWorkbenchEvent('canvas-tour-step', { ...result, present: options?.present !== false });
+  goToTourStop(step: TourStep, options?: { present?: boolean; presenter?: undefined }): TourStepResult;
+  goToTourStop(
+    step: TourStep,
+    options: { present?: boolean; presenter?: TourPresenter },
+  ): TourStepResult | TourSuperseded;
+  goToTourStop(
+    step: TourStep,
+    options?: { present?: boolean; presenter?: TourPresenter },
+  ): TourStepResult | TourSuperseded {
+    const result = goToTourStop(step, options?.presenter);
+    if (!('superseded' in result))
+      emitPrimaryWorkbenchEvent('canvas-tour-step', { ...result, present: options?.present !== false });
     return result;
   }
 
   /** Leave presentation in every viewer. */
-  exitTour(): void {
-    exitTour();
-    emitPrimaryWorkbenchEvent('canvas-tour-exit', {});
+  exitTour(presenter?: TourPresenter): void {
+    const result = exitTour(presenter);
+    if (!('superseded' in result)) emitPrimaryWorkbenchEvent('canvas-tour-exit', { ...result });
   }
 
   /** Ease the camera to a node, world rect or viewport. Not recorded in undo history. */

package/src/server/operations/http.ts

@@ -8,7 +8,7 @@
  */
 import { executeOperation, listOperations } from './registry.js';
 import { SOURCE_LABEL_RE } from '../agent-presence.js';
-import { OperationError } from './types.js';
+import { OperationError, type OperationExecutionOptions, type OperationProgress } from './types.js';
 import { isWorkbenchToken, refuseStaleWorkbenchWrite } from '../workbench-auth.js';
 
 function responseJson(data: unknown, status = 200): Response {
@@ -20,6 +20,57 @@ function responseJson(data: unknown, status = 200): Response {
   });
 }
 
+/** Opt-in NDJSON; the terminal frame retains the ordinary HTTP status/body. */
+export type OperationStreamFrame =
+  | { type: 'progress'; progress: OperationProgress }
+  | { type: 'result'; status: number; body: unknown };
+
+function operationFailure(name: string, error: unknown, signal: AbortSignal): Response {
+  if (signal.aborted) return responseJson({ ok: false, cancelled: true, error: 'Operation cancelled.' }, 499);
+  if (error instanceof OperationError) {
+    return responseJson({ ok: false, error: error.message, ...(error.details ?? {}) }, error.status);
+  }
+  // Keep unexpected errors server-side, never leak a Bun development overlay.
+  console.error(`[operation] unhandled error dispatching ${name}:`, error);
+  return responseJson({ ok: false, error: 'Internal error processing the request.' }, 500);
+}
+
+function progressResponse(
+  req: Request,
+  name: string,
+  run: (options: OperationExecutionOptions) => Promise<Response>,
+): Response {
+  const cancelled = new AbortController();
+  const signal = AbortSignal.any([req.signal, cancelled.signal]);
+  const encoder = new TextEncoder();
+  let closed = false;
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const send = (frame: OperationStreamFrame): void => {
+        if (!closed) controller.enqueue(encoder.encode(`${JSON.stringify(frame)}\n`));
+      };
+      let response: Response;
+      try {
+        response = await run({ signal, onProgress: (progress) => send({ type: 'progress', progress }) });
+      } catch (error) {
+        response = operationFailure(name, error, signal);
+      }
+      if (!closed) {
+        send({ type: 'result', status: response.status, body: await response.json() });
+        closed = true;
+        controller.close();
+      }
+    },
+    cancel() {
+      closed = true;
+      cancelled.abort();
+    },
+  });
+  return new Response(stream, {
+    headers: { 'Content-Type': 'application/x-ndjson', 'Cache-Control': 'no-store', 'X-Accel-Buffering': 'no' },
+  });
+}
+
 export function matchOperationPath(template: string, pathname: string): Record<string, string> | null {
   const templateSegments = template.split('/');
   const pathSegments = pathname.split('/');
@@ -83,6 +134,7 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
     const params = matchOperationPath(route.path, url.pathname);
     if (!params) continue;
     try {
+      req.signal.throwIfAborted();
       const input = route.readInput
         ? await route.readInput(req, params, url)
         : await readOperationInput(req, params, url);
@@ -100,27 +152,23 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
       // HTTP callers read as 'api'.
       const sourceHeader = req.headers.get('x-pmx-source');
       const source = sourceHeader && SOURCE_LABEL_RE.test(sourceHeader) ? sourceHeader : 'api';
-      const result = await executeOperation(op.name, input, {
-        // The legacy marker remains a UI-policy signal (ghost suppression).
-        // Only the unguessable boot token classifies authorship as human.
-        suppressAutoGhost: workbenchMarked,
-        fromWorkbench: workbenchMarked,
-        humanAuthor,
-        source,
-        proxiedRead: req.headers.get('x-pmx-proxied-read') === '1',
-      });
-      return responseJson(result, route.status ? route.status(result) : 200);
+      const run = async (options: OperationExecutionOptions): Promise<Response> => {
+        const result = await executeOperation(op.name, input, {
+          ...options,
+          // The legacy marker remains a UI-policy signal (ghost suppression).
+          // Only the unguessable boot token classifies authorship as human.
+          suppressAutoGhost: workbenchMarked,
+          fromWorkbench: workbenchMarked,
+          humanAuthor,
+          source,
+          proxiedRead: req.headers.get('x-pmx-proxied-read') === '1',
+        });
+        return responseJson(result, route.status ? route.status(result) : 200);
+      };
+      if (req.headers.get('accept') === 'application/x-ndjson') return progressResponse(req, op.name, run);
+      return await run({ signal: req.signal });
     } catch (error) {
-      if (error instanceof OperationError) {
-        return responseJson({ ok: false, error: error.message, ...(error.details ?? {}) }, error.status);
-      }
-      // An unexpected (non-OperationError) throw from a handler MUST NOT escape the
-      // dispatcher: Bun.serve has no per-request boundary, so an escaped throw renders
-      // its dev error overlay (HTTP 500 text/html leaking the absolute server source
-      // path + stack). Return a clean JSON 500 with a generic message instead (the
-      // real error is logged server-side, never echoed to the client).
-      console.error(`[operation] unhandled error dispatching ${op.name}:`, error);
-      return responseJson({ ok: false, error: 'Internal error processing the request.' }, 500);
+      return operationFailure(op.name, error, req.signal);
     }
   }
   return null;

package/src/server/operations/index.ts

@@ -77,7 +77,12 @@ export { runCanvasBatchOperation, type BatchEnvelope } from './ops/batch.js';
 // OpenMcpAppCoreResult is the SDK's cast target for executeOperation('mcpapp.open').
 export type { OpenMcpAppCoreResult } from './ops/app.js';
 export { LocalOperationInvoker, HttpOperationInvoker, type OperationInvoker } from './invoker.js';
-export { registerOperationTools, registerCompositeTools, type OperationToolHost } from './mcp.js';
+export {
+  registerOperationTools,
+  registerCompositeTools,
+  registerOperationHelpTool,
+  type OperationToolHost,
+} from './mcp.js';
 export { compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';
 export {
   OperationError,
@@ -85,5 +90,7 @@ export {
   type Operation,
   type OperationContext,
   type OperationDefinition,
+  type OperationExecutionOptions,
   type OperationErrorStatus,
+  type OperationProgress,
 } from './types.js';

package/src/server/operations/invoker.ts

@@ -5,10 +5,11 @@
  */
 import { SOURCE_LABEL_RE } from '../agent-presence.js';
 import { executeOperation, getOperation } from './registry.js';
-import { OperationError, type OperationErrorStatus } from './types.js';
+import { OperationError, type OperationErrorStatus, type OperationExecutionOptions } from './types.js';
+import type { OperationStreamFrame } from './http.js';
 
 export interface OperationInvoker {
-  invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+  invoke(name: string, input: Record<string, unknown>, options?: OperationExecutionOptions): Promise<unknown>;
 }
 
 /**
@@ -40,9 +41,14 @@ export class LocalOperationInvoker implements OperationInvoker {
     this.proxiedRead = source === 'mcp';
   }
 
-  async invoke(name: string, input: Record<string, unknown>): Promise<unknown> {
+  async invoke(
+    name: string,
+    input: Record<string, unknown>,
+    options: OperationExecutionOptions = {},
+  ): Promise<unknown> {
     const args = this.allowExternalMcp ? input : { ...input, allowExternalMcp: false };
     return await executeOperation(name, defaultPresenceSource(name, args, this.source), {
+      ...options,
       source: this.source,
       proxiedRead: this.proxiedRead,
     });
@@ -53,6 +59,37 @@ function toOperationErrorStatus(status: number): OperationErrorStatus {
   return status === 404 ? 404 : status === 409 ? 409 : status === 403 ? 403 : 400;
 }
 
+async function readProgressResponse(response: Response, options: OperationExecutionOptions): Promise<Response> {
+  if (!response.body) throw new OperationError('Missing operation progress stream.');
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      buffer += decoder.decode(value, { stream: !done });
+      let end = buffer.indexOf('\n');
+      while (end !== -1) {
+        const frame = JSON.parse(buffer.slice(0, end)) as OperationStreamFrame;
+        buffer = buffer.slice(end + 1);
+        if (frame.type === 'result') return Response.json(frame.body, { status: frame.status });
+        if (frame.type !== 'progress') throw new OperationError('Invalid operation progress frame.');
+        try {
+          await options.onProgress?.(frame.progress);
+        } catch (error) {
+          if (!options.signal?.aborted) console.error('[operation] progress callback failed:', error);
+        }
+        end = buffer.indexOf('\n');
+      }
+      if (done) throw new OperationError('Operation progress stream ended without a result.');
+    }
+  } finally {
+    // A fetch abort already errors the reader; preserve that original failure.
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+
 /** Builds the HTTP request from the op's route template (`:id` from input, GET flags to query). */
 export class HttpOperationInvoker implements OperationInvoker {
   private readonly baseUrl: string;
@@ -70,7 +107,12 @@ export class HttpOperationInvoker implements OperationInvoker {
     this.proxiedRead = source === 'mcp';
   }
 
-  async invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown> {
+  async invoke(
+    name: string,
+    rawInput: Record<string, unknown>,
+    options: OperationExecutionOptions = {},
+  ): Promise<unknown> {
+    options.signal?.throwIfAborted();
     const args = this.allowExternalMcp ? rawInput : { ...rawInput, allowExternalMcp: false };
     const input = defaultPresenceSource(name, args, this.source);
     const op = getOperation(name);
@@ -96,8 +138,10 @@ export class HttpOperationInvoker implements OperationInvoker {
 
     let url = `${this.baseUrl}${path}`;
     const proxyHeaders: Record<string, string> = this.proxiedRead ? { 'x-pmx-proxied-read': '1' } : {};
+    if (options.onProgress) proxyHeaders.accept = 'application/x-ndjson';
     const init: RequestInit = {
       method: route.method,
+      signal: options.signal,
       headers: { 'x-pmx-source': this.source, ...proxyHeaders },
     };
     if (route.method === 'GET' || route.method === 'DELETE') {
@@ -112,7 +156,10 @@ export class HttpOperationInvoker implements OperationInvoker {
       init.body = JSON.stringify(rest);
     }
 
-    const response = await fetch(url, init);
+    let response = await fetch(url, init);
+    if (response.headers.get('content-type')?.startsWith('application/x-ndjson')) {
+      response = await readProgressResponse(response, options);
+    }
     const text = await response.text();
     let parsed: unknown = null;
     let parsedAsJson = false;
@@ -125,6 +172,7 @@ export class HttpOperationInvoker implements OperationInvoker {
       }
     }
     if (!response.ok) {
+      if (response.status === 499) throw new DOMException('Operation cancelled.', 'AbortError');
       // errorBodyAsResult carries the route's STRUCTURED partial-failure
       // envelope (e.g. canvas_batch { ok:false, failedIndex, ... }) through as
       // a result. A non-JSON error body (an HTML 502 from a proxy, a foreign