pmx-canvas 0.6.3 → 0.6.5

package/src/client/nodes/McpAppNode.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useMemo, useRef } from 'preact/hooks';
+import type { RefObject } from 'preact';
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks';
 import { HTML_SURFACE_PUSH_SOURCE } from '../../shared/ax-surface-protocol.js';
 import { canvasThemeScheme } from '../../shared/themes.js';
 import type { CanvasNodeState } from '../types';
@@ -54,6 +55,106 @@ export function isSameOriginFrameDocumentUrl(url: string, origin = window.locati
   }
 }
 
+type ViewerFrameSource = { src?: string; srcdoc?: string };
+
+/**
+ * Keep the last painted viewer in front while its replacement navigates. Viewer
+ * specs are immutable documents, so updates normally change `?v=` and reload the
+ * iframe; putting the new document in a hidden sibling avoids exposing Chromium's
+ * white navigation paint. Two animation frames after load gives the new document
+ * a composited paint before the old one is removed.
+ */
+export function RefreshingViewerFrame({
+  source,
+  iframeRef,
+  onLoad,
+  title,
+  className = 'mcp-app-frame',
+  sandbox = 'allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox',
+  allow = 'clipboard-read; clipboard-write',
+  tabIndex,
+}: {
+  source: ViewerFrameSource;
+  iframeRef: RefObject<HTMLIFrameElement>;
+  onLoad: () => void;
+  title: string;
+  className?: string;
+  sandbox?: string;
+  allow?: string;
+  tabIndex?: number;
+}) {
+  const sourceKey = source.src ?? source.srcdoc ?? '';
+  const [painted, setPainted] = useState({ key: sourceKey, source });
+  const [pending, setPending] = useState<{ key: string; source: ViewerFrameSource } | null>(null);
+  const promotionRef = useRef(0);
+
+  useEffect(() => {
+    promotionRef.current += 1;
+    if (!sourceKey || sourceKey === painted.key) {
+      setPending(null);
+      return;
+    }
+    if (!painted.key) {
+      setPainted({ key: sourceKey, source });
+      return;
+    }
+    setPending({ key: sourceKey, source });
+  }, [sourceKey, painted.key]);
+
+  useEffect(
+    () => () => {
+      promotionRef.current += 1;
+    },
+    [],
+  );
+
+  const frame = (entry: { key: string; source: ViewerFrameSource }, isPending: boolean) => (
+    <iframe
+      key={entry.key}
+      ref={isPending ? undefined : iframeRef}
+      {...entry.source}
+      class={className}
+      sandbox={sandbox}
+      allow={allow}
+      tabIndex={tabIndex}
+      loading={iframeMode.value === 'srcdoc' ? undefined : 'lazy'}
+      onLoad={(event) => {
+        if (!isPending) {
+          onLoad();
+          return;
+        }
+        const token = ++promotionRef.current;
+        const loadedFrame = event.currentTarget;
+        requestAnimationFrame(() =>
+          requestAnimationFrame(() => {
+            if (promotionRef.current !== token) return;
+            iframeRef.current = loadedFrame;
+            setPainted(entry);
+            setPending(null);
+            onLoad();
+          }),
+        );
+      }}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        width: '100%',
+        height: '100%',
+        visibility: isPending ? 'hidden' : 'visible',
+        background: 'var(--c-panel-soft)',
+      }}
+      title={title}
+    />
+  );
+
+  return (
+    <div class="mcp-app-frame-stack">
+      {frame(painted, false)}
+      {pending && frame(pending, true)}
+    </div>
+  );
+}
+
 export function McpAppNode({ node, expanded = false }: { node: CanvasNodeState; expanded?: boolean }) {
   if (node.data.mode === 'ext-app') {
     return <ExtAppFrame node={node} expanded={expanded} />;
@@ -180,19 +281,10 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
       {/* Plain iframe-backed viewers stay on an opaque origin. Hosted ext-apps use
           the explicit postMessage bridge instead, which is the only path that needs
           app/host RPC and broader capabilities. */}
-      <iframe
-        ref={iframeRef}
-        {...surfaceFrame}
-        class="mcp-app-frame"
-        sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
-        allow="clipboard-read; clipboard-write"
-        // Lazy loading only helps src mode (defers the HTTP request for
-        // off-screen nodes). In srcdoc mode the content is already inline —
-        // lazy would just delay PAINTING until the node scrolls near the
-        // viewport, which reads as "blank until opened" (Amp portal report).
-        loading={iframeMode.value === 'srcdoc' ? undefined : 'lazy'}
+      <RefreshingViewerFrame
+        source={surfaceFrame}
+        iframeRef={iframeRef}
         onLoad={pushAxState}
-        style={{ flex: 1, minHeight: 0, width: '100%' }}
         title={`MCP App: ${sourceServer}`}
       />
     </div>

package/src/client/nodes/MermaidNode.tsx

@@ -21,7 +21,8 @@ export function MermaidNode({ node, expanded = false }: { node: CanvasNodeState;
   // Per-mount nonce for the content-height reporter (node grows to fit content).
   const frameToken = useMemo(() => `frame-${crypto.randomUUID()}`, []);
   const source = typeof node.data.content === 'string' ? node.data.content : '';
-  const v = useMemo(() => surfaceContentHash(source), [source]);
+  const fit = node.data.fit === 'none' ? 'none' : 'contain';
+  const v = useMemo(() => surfaceContentHash(`${fit}:${source}`), [source, fit]);
 
   // `theme` is intentionally excluded from the deps: live theme changes are
   // pushed via postMessage below (no reload), while `v` reloads the frame when
@@ -70,7 +71,7 @@ export function MermaidNode({ node, expanded = false }: { node: CanvasNodeState;
       style={{
         width: '100%',
         height: '100%',
-        minHeight: expanded ? '70vh' : '300px',
+        minHeight: expanded ? '70vh' : '0',
         border: 'none',
         background: 'var(--c-bg)',
         borderRadius: '6px',

package/src/client/state/intent-store.ts

@@ -83,9 +83,13 @@ function setPhase(id: string, phase: IntentPhase, ms: number, settledNodeId?: st
   next.set(id, { ...current, phase, ...(settledNodeId ? { settledNodeId } : {}) });
   writeIntents(next);
   clearExitTimer(id);
+  // The layer removes ghosts on animationend, after the browser actually paints
+  // the morph. A wall-clock deadline equal to the CSS duration can delete a
+  // ghost before its delayed first paint or transition completes on a busy tab.
+  // Retain a backstop for hidden tabs or disabled animations.
   exitTimers.set(
     id,
-    setTimeout(() => removeIntent(id), ms),
+    setTimeout(() => removeIntent(id), ms + 1500),
   );
 }
 

package/src/client/state/presentation.ts

@@ -0,0 +1,7 @@
+import { signal } from '@preact/signals';
+
+export const presenting = signal(false);
+export const recordingCamera = signal(false);
+export function ownsCamera(): boolean {
+  return presenting.value || recordingCamera.value;
+}

package/src/client/state/session-store.ts

@@ -386,6 +386,9 @@ export function applySessionReceipt(data: Record<string, unknown>): void {
   const counts = data.counts as Partial<SessionReceipt['counts']> | undefined;
   const snapshot = data.snapshot as SessionReceipt['snapshot'] | undefined;
   if (typeof data.label !== 'string' || typeof data.endedAt !== 'string') return;
+  // Keep history/timeline intact, but only interrupt for a changed top-level
+  // session. Quiet endings must not replace an existing useful receipt.
+  if (data.unchanged === true || typeof data.parentAgentId === 'string') return;
   sessionReceipt.value = {
     label: data.label,
     endedAt: data.endedAt,

package/src/client/state/sse-bridge.ts

@@ -1,4 +1,5 @@
 import { findOpenCanvasPosition } from '../utils/placement.js';
+import { ownsCamera } from './presentation';
 import { normalizeExtAppToolResult } from '../utils/ext-app-tool-result.js';
 import type { CanvasAnnotation, CanvasEdge, CanvasNodeState } from '../types';
 import {
@@ -945,6 +946,7 @@ function reconnectDelayMs(attempt: number): number {
 }
 
 function handleCanvasFocusNode(data: Record<string, unknown>): void {
+  if (ownsCamera()) return;
   const nodeId = data.nodeId as string;
   if (nodeId && nodes.value.has(nodeId)) {
     if (data.noPan === true) {
@@ -956,6 +958,7 @@ function handleCanvasFocusNode(data: Record<string, unknown>): void {
 }
 
 function handleCanvasViewportUpdate(data: Record<string, unknown>): void {
+  if (ownsCamera()) return;
   const viewport = data.viewport as Record<string, unknown> | undefined;
   if (!viewport) return;
   const x = typeof viewport.x === 'number' ? viewport.x : 0;

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%;
@@ -4474,6 +4501,38 @@ html.is-node-resizing .ext-app-preview-catcher {
   font-weight: 600;
 }
 
+.feedback-backdrop {
+  position: fixed;
+  padding: 24px 0;
+  align-items: center;
+}
+.feedback-dialog {
+  width: min(480px, calc(100% - 32px));
+  max-height: calc(100dvh - 48px);
+  overflow-y: auto;
+  color: var(--c-text);
+}
+.feedback-dialog label {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  font-size: 12px;
+}
+.feedback-note {
+  margin: 0;
+  color: var(--c-muted);
+  font-size: 12px;
+  line-height: 1.5;
+}
+.feedback-dialog textarea {
+  resize: vertical;
+  min-height: 100px;
+}
+.feedback-dialog button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
 /* Selection action bar — floating bottom-center of the canvas region
    (rail-chrome-v2 phase 7, item 13). */
 /* In a session the command bar owns the bottom-center slot — lift the
@@ -6776,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,