pmx-canvas 0.6.4 → 0.7.0

package/src/cli/commands/record.ts

@@ -0,0 +1,218 @@
+import { mkdirSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { z } from 'zod';
+import { isCanvasTheme } from '../../shared/themes.js';
+import { derivedTour, tourSchema, tourFrames, type Camera, type TourNode } from '../../shared/tour.js';
+import {
+  startCanvasAutomationWebView,
+  evaluateCanvasAutomationWebView,
+  screenshotCanvasAutomationWebView,
+  resizeCanvasAutomationWebView,
+  stopCanvasAutomationWebView,
+} from '../../server/server.js';
+import { cmd, getBaseUrl, invokeOperation, output, parseFlags, showCommandHelp } from '../shared.js';
+
+export function parseRecordOptions(flags: Record<string, string | boolean>) {
+  const number = (key: string, fallback: number) => {
+    if (flags[key] === true || flags[key] === false) throw new Error(`--${key} needs a number`);
+    return flags[key] === undefined ? fallback : Number(flags[key]);
+  };
+  for (const key of ['tour-file', 'chrome-path']) {
+    if (flags[key] !== undefined && typeof flags[key] !== 'string') throw new Error(`--${key} needs a path`);
+  }
+  const resolution = String(flags.resolution ?? '1280x720').match(/^(\d+)x(\d+)$/);
+  if (!resolution) throw new Error('Use --resolution WIDTHxHEIGHT');
+  const options = z
+    .object({
+      width: z.number().int().min(64).max(7680),
+      height: z.number().int().min(64).max(4320),
+      fps: z.number().int().min(1).max(120),
+      duration: z.number().positive().max(86400).optional(),
+      mode: z.enum(['realtime', 'deterministic']),
+      output: z.string().min(1),
+    })
+    .parse({
+      width: Number(resolution[1]),
+      height: Number(resolution[2]),
+      fps: number('fps', 30),
+      duration: flags.duration === undefined ? undefined : number('duration', 10),
+      mode: flags.mode ?? 'realtime',
+      output: typeof flags.output === 'string' ? flags.output : '',
+    });
+  if (flags.theme !== undefined && !isCanvasTheme(flags.theme)) throw new Error('Unknown --theme');
+  if (options.mode === 'realtime' && !options.duration && flags['stop-on-signal'] !== true) {
+    throw new Error('Realtime recording needs --duration SECONDS or --stop-on-signal');
+  }
+  if (options.mode === 'deterministic' && (flags.duration !== undefined || flags['stop-on-signal'])) {
+    throw new Error('Deterministic duration comes from tour stops; omit --duration and --stop-on-signal');
+  }
+  if (flags['tour-file'] && options.mode !== 'deterministic')
+    throw new Error('--tour-file requires --mode deterministic');
+  return {
+    ...options,
+    theme: typeof flags.theme === 'string' ? flags.theme : undefined,
+    present: flags.present === true,
+    tourFile: typeof flags['tour-file'] === 'string' ? flags['tour-file'] : undefined,
+    chromePath: typeof flags['chrome-path'] === 'string' ? flags['chrome-path'] : undefined,
+  };
+}
+
+cmd('tour get', 'Read the persisted tour or derived group order', ['pmx-canvas tour get'], async () => {
+  output(await invokeOperation('tour.get', {}));
+});
+cmd(
+  'tour set',
+  'Persist camera stops from JSON (null resets to group order)',
+  ['pmx-canvas tour set --file tour.json'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help) return showCommandHelp('tour set');
+    if (typeof flags.file !== 'string') throw new Error('Missing --file');
+    const tour = tourSchema.nullable().parse(await Bun.file(flags.file).json());
+    output(await invokeOperation('tour.set', { tour }));
+  },
+);
+
+cmd(
+  'record',
+  'Optionally capture the board tour or live presentation using Bun.WebView Chrome',
+  [
+    'pmx-canvas record --duration 10 --present --output demo.mp4',
+    'pmx-canvas record --mode deterministic --tour-file tour.json --present --fps 30 --output frames',
+    'pmx-canvas record --stop-on-signal --resolution 1920x1080 --output live.mp4',
+  ],
+  async (args) => {
+    const { flags } = parseFlags(args, { boolFlags: ['present', 'stop-on-signal'] });
+    if (flags.help || flags.h) return showCommandHelp('record');
+    const options = parseRecordOptions(flags);
+    const outputPath = resolve(options.output);
+    const video = /\.mp4$/i.test(outputPath);
+    const framesPath = video ? `${outputPath}.frames` : outputPath;
+    if (existsSync(outputPath) || existsSync(framesPath)) throw new Error('Output already exists; choose a new path');
+    const response = await fetch(`${getBaseUrl()}/api/canvas/state`);
+    if (!response.ok) throw new Error(`Cannot read board: HTTP ${response.status}`);
+    const board = (await response.json()) as { nodes: TourNode[]; viewport: Camera; tour?: unknown };
+    const tour =
+      options.mode === 'deterministic'
+        ? tourSchema.parse(
+            options.tourFile ? await Bun.file(options.tourFile).json() : (board.tour ?? derivedTour(board.nodes)),
+          )
+        : undefined;
+    if (tour && !tour.stops.length) throw new Error('No tour stops: supply --tour-file or create groups/a tour');
+    const url = new URL('/workbench', getBaseUrl());
+    if (options.present) url.searchParams.set('present', '1');
+    if (tour) url.searchParams.set('capture', '1');
+    if (options.theme) url.searchParams.set('theme', options.theme);
+    let stopping = false;
+    const stop = () => {
+      stopping = true;
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    let count = 0;
+    let duplicated = 0;
+    try {
+      await startCanvasAutomationWebView(url.href, {
+        backend: 'chrome',
+        width: options.width,
+        height: options.height,
+        chromePath: options.chromePath,
+      });
+      const deadline = Date.now() + 30_000;
+      while (!(await evaluateCanvasAutomationWebView('!!window.pmxCapture?.ready()'))) {
+        if (Date.now() > deadline) throw new Error('Workbench did not become capture-ready in 30 seconds');
+        await Bun.sleep(50);
+      }
+      // Chrome launch dimensions describe the outer window. WebView.resize
+      // applies viewport emulation, giving screenshots the requested pixels.
+      await resizeCanvasAutomationWebView(options.width, options.height);
+      await evaluateCanvasAutomationWebView(
+        'new Promise(r => requestAnimationFrame(() => requestAnimationFrame(() => r(true))))',
+      );
+      await evaluateCanvasAutomationWebView('document.fonts.ready.then(() => true)');
+      const area = (await evaluateCanvasAutomationWebView('window.pmxCapture.area()')) as {
+        width: number;
+        height: number;
+      };
+      const initial = (await evaluateCanvasAutomationWebView('window.pmxCapture.camera()')) as Camera;
+      mkdirSync(framesPath, { recursive: true });
+      const write = async (bytes: Uint8Array) => {
+        await Bun.write(join(framesPath, `frame-${String(count++).padStart(6, '0')}.png`), bytes);
+      };
+      const started = performance.now();
+      if (tour) {
+        for (const camera of tourFrames(tour, initial, board.nodes, area.width, area.height, options.fps)) {
+          if (stopping) break;
+          const applied = (await evaluateCanvasAutomationWebView(
+            `window.pmxCapture.frame(${JSON.stringify(camera)})`,
+          )) as Camera;
+          if (applied.x !== camera.x || applied.y !== camera.y || applied.scale !== camera.scale) {
+            throw new Error('Capture camera was changed before paint');
+          }
+          await write(await screenshotCanvasAutomationWebView({ format: 'png' }));
+        }
+      } else {
+        const limit = options.duration ? Math.ceil(options.duration * options.fps) : Infinity;
+        while (!stopping && count < limit) {
+          await Bun.sleep(Math.max(0, started + (count / options.fps) * 1000 - performance.now()));
+          const bytes = await screenshotCanvasAutomationWebView({ format: 'png' });
+          await write(bytes);
+          // Preserve wall-clock speed if capture is slower than requested fps.
+          const elapsedFrames = Math.min(limit, Math.floor(((performance.now() - started) / 1000) * options.fps));
+          while (count < elapsedFrames) {
+            await write(bytes);
+            duplicated++;
+          }
+        }
+      }
+      await Bun.write(
+        join(framesPath, 'recording.json'),
+        JSON.stringify(
+          {
+            mode: options.mode,
+            fps: options.fps,
+            width: options.width,
+            height: options.height,
+            frames: count,
+            duplicated,
+            seconds: count / options.fps,
+          },
+          null,
+          2,
+        ),
+      );
+    } finally {
+      process.off('SIGINT', stop);
+      process.off('SIGTERM', stop);
+      await stopCanvasAutomationWebView();
+    }
+    let encoded = false;
+    if (video && count > 0) {
+      const ffmpeg = Bun.which('ffmpeg');
+      if (!ffmpeg) console.error(`ffmpeg not found; PNG sequence retained at ${framesPath}`);
+      else {
+        const process = Bun.spawn(
+          [
+            ffmpeg,
+            '-n',
+            '-framerate',
+            String(options.fps),
+            '-i',
+            join(framesPath, 'frame-%06d.png'),
+            '-c:v',
+            'libx264',
+            '-pix_fmt',
+            'yuv420p',
+            '-vf',
+            'pad=ceil(iw/2)*2:ceil(ih/2)*2',
+            outputPath,
+          ],
+          { stdout: 'ignore', stderr: 'inherit' },
+        );
+        encoded = (await process.exited) === 0;
+        if (!encoded) throw new Error(`ffmpeg failed; PNG sequence retained at ${framesPath}`);
+      }
+    }
+    output({ ok: true, output: encoded ? outputPath : framesPath, frames: count, fps: options.fps, duplicated });
+  },
+);

package/src/cli/commands/view.ts

@@ -42,16 +42,17 @@ cmd('open', 'Open the current workbench in the browser', ['pmx-canvas open'], as
 cmd(
   'layout',
   'Get the full canvas layout (nodes, edges, viewport)',
-  ['pmx-canvas layout', 'pmx-canvas layout --summary'],
+  ['pmx-canvas layout', 'pmx-canvas layout --board <id>', 'pmx-canvas layout --summary'],
   async (args) => {
     const { flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('layout');
 
+    const board = typeof flags.board === 'string' ? flags.board : undefined;
     if (flags.summary || flags.compact) {
-      output(await invokeOperation('summary.get', {}));
+      output(await invokeOperation('summary.get', { board }));
       return;
     }
-    const result = await invokeOperation('layout.get', {});
+    const result = await invokeOperation('layout.get', { board });
     output(result);
   },
 );
@@ -61,12 +62,13 @@ cmd('status', 'Quick canvas summary', ['pmx-canvas status'], async (args) => {
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('status');
 
-  const layout = (await invokeOperation('layout.get', {})) as {
+  const board = typeof flags.board === 'string' ? flags.board : undefined;
+  const layout = (await invokeOperation('layout.get', { board })) as {
     nodes: Array<Record<string, unknown>>;
     edges: unknown[];
     viewport: unknown;
   };
-  const pinned = (await invokeOperation('pinned-context.get', {})) as { count: number; nodeIds: string[] };
+  const pinned = (await invokeOperation('pinned-context.get', { board })) as { count: number; nodeIds: string[] };
 
   const typeCounts: Record<string, number> = {};
   for (const n of layout.nodes) {

package/src/cli/index.ts

@@ -32,10 +32,13 @@ if (args.includes('--version') || args.includes('-v')) {
 // ── Agent CLI subcommands ────────────────────────────────────
 // If first arg is a known subcommand (not a --flag), route to the agent CLI.
 const AGENT_COMMANDS = new Set([
+  'tour',
+  'record',
   'node',
   'edge',
   'json-render',
   'search',
+  'context',
   'layout',
   'status',
   'arrange',
@@ -43,6 +46,10 @@ const AGENT_COMMANDS = new Set([
   'fit',
   'screenshot',
   'pin',
+  'board',
+  'backup',
+  'restore',
+  'export',
   'ax',
   'pump',
   'undo',
@@ -304,6 +311,10 @@ Agent CLI (works against running server):
   diagram add                         Add an Excalidraw diagram node
   html primitive add|schema           Add or inspect HTML communication primitives
   pin <ids...> | --list | --clear     Manage context pins
+  board list|create|rename|category   Manage boards (the human opens them in the workbench)
+  backup [status|schedule]            Back up every board, now or on a schedule
+  restore <backup-file>               Replace every board with a backup
+  export [--board id] [--out file]    Export a board as one HTML file anyone can open
   undo / redo / history               Time travel
   snapshot save|list|restore|diff|delete
                                       Manage snapshots
@@ -423,14 +434,15 @@ Examples:
   console.log('    pmx-canvas --help          (all commands)');
   console.log('\n  Press Ctrl+C to stop\n');
 
-  process.on('SIGINT', () => {
+  const shutdown = () => {
     console.log('\nShutting down...');
-    canvas.stop();
-    process.exit(0);
-  });
-
-  process.on('SIGTERM', () => {
-    canvas.stop();
-    process.exit(0);
-  });
+    try {
+      canvas.stop();
+      process.exit(0);
+    } catch (error) {
+      console.error('Shutdown refused: canvas changes could not be saved. Fix persistence and retry shutdown.', error);
+    }
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
 }

package/src/client/App.tsx

@@ -1,4 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import { Presentation } from './canvas/Presentation';
+import { presenting } from './state/presentation';
 import { AttentionHistory } from './canvas/AttentionHistory';
 import { AttentionToast } from './canvas/AttentionToast';
 import { registerCanvasArea, canvasArea } from './canvas/canvas-area';
@@ -6,9 +8,13 @@ import { CanvasViewport } from './canvas/CanvasViewport';
 import { CommandBar } from './canvas/CommandBar';
 import { ConnectionBanner } from './canvas/ConnectionBanner';
 import { CommandPalette } from './canvas/CommandPalette';
+import { BoardLinkDialog } from './canvas/BoardLinkDialog';
 import { ContextMenu, useContextMenu } from './canvas/ContextMenu';
 import { ContextPinBar } from './canvas/ContextPinBar';
 import { EmptyState } from './canvas/EmptyState';
+import { HomeView } from './canvas/HomeView';
+import { ExportDialog } from './canvas/ExportDialog';
+import { activeBoardId, boardsLoaded } from './state/boards-store';
 import { createNodeInView } from './canvas/create-in-view';
 import { undoFromKeyboard } from './state/session-store';
 import { ActivityFeed, WritersSheet } from './canvas/ExternalWriters';
@@ -65,11 +71,13 @@ export function App() {
   const [minimapVisible, setMinimapVisible] = useState(true);
   const [snapshotOpen, setSnapshotOpen] = useState(false);
   const [paletteOpen, setPaletteOpen] = useState(false);
+  const [boardLinkOpen, setBoardLinkOpen] = useState(false);
   const [shortcutsOpen, setShortcutsOpen] = useState(false);
   const [annotationTool, setAnnotationTool] = useState<AnnotationTool>(null);
   const snapshotBtnRef = useRef<HTMLButtonElement>(null);
   const { menu, openNodeMenu, openCanvasMenu, openEdgeMenu, closeMenu } = useContextMenu();
   const hasInitialLayout = hasInitialServerLayout.value;
+  const onHome = boardsLoaded.value && activeBoardId.value === null;
   // rail-chrome-v2: the one selector every agent surface mounts on. Exposed
   // as a data attribute so styling and tests can key on it; the quiet board
   // (no attached session) must stay byte-clean of agent chrome.
@@ -88,6 +96,12 @@ export function App() {
     return connectSSE();
   }, []);
 
+  useEffect(() => {
+    const open = () => setBoardLinkOpen(true);
+    window.addEventListener('pmx-open-board-link', open);
+    return () => window.removeEventListener('pmx-open-board-link', open);
+  }, []);
+
   // Keep the server's idea of this window's size current (0.4.6 orb feedback
   // #2) so an agent `fit` computes a scale that actually fits the human's
   // canvas region. Connect-time reporting lives in the SSE bridge; this covers
@@ -324,7 +338,11 @@ export function App() {
   const area = canvasArea();
 
   return (
-    <div class="app-shell" data-session-active={sessionIsActive ? 'true' : 'false'}>
+    <div
+      class={`app-shell${presenting.value ? ' is-presenting' : ''}`}
+      data-session-active={sessionIsActive ? 'true' : 'false'}
+    >
+      <Presentation />
       <ToolRail
         minimapVisible={minimapVisible}
         onToggleMinimap={handleToggleMinimap}
@@ -351,16 +369,21 @@ export function App() {
           <AttentionHistory />
           <ActivityFeed />
           <WritersSheet />
-          {hasInitialLayout && allNodes.length === 0 && intents.value.size === 0 && (
-            <EmptyState onOpenPalette={() => setPaletteOpen(true)} />
+          {onHome ? (
+            <HomeView />
+          ) : (
+            hasInitialLayout &&
+            allNodes.length === 0 &&
+            intents.value.size === 0 && <EmptyState onOpenPalette={() => setPaletteOpen(true)} />
           )}
           {selectedNodeIds.value.size > 0 && <SelectionBar />}
           {sessionIsActive ? <CommandBar /> : contextPinnedNodeIds.value.size > 0 && <ContextPinBar />}
           <SessionReceipt onOpenSnapshots={() => setSnapshotOpen(true)} />
           <TextPrompt />
+          <ExportDialog />
           {expandedNodeId.value && <ExpandedNodeOverlay />}
           <SnapshotPanel open={snapshotOpen} onClose={handleCloseSnapshot} anchorRef={snapshotBtnRef} />
-          {minimapVisible && (
+          {minimapVisible && !onHome && (
             <Minimap
               viewport={viewport}
               nodes={nodes}
@@ -375,6 +398,7 @@ export function App() {
       {sessionIsActive && <SessionPanel />}
       {menu && <ContextMenu menu={menu} onClose={closeMenu} />}
       {paletteOpen && <CommandPalette onClose={() => setPaletteOpen(false)} onToggleMinimap={handleToggleMinimap} />}
+      {boardLinkOpen && <BoardLinkDialog onClose={() => setBoardLinkOpen(false)} />}
       {shortcutsOpen && <ShortcutOverlay onClose={() => setShortcutsOpen(false)} />}
     </div>
   );

package/src/client/canvas/AgentPresenceLayer.tsx

@@ -45,7 +45,7 @@ export function AgentPresenceLayer() {
       {cursors.map(({ presence, position }) => (
         <div
           key={presence.sessionId}
-          class={`agent-cursor phase-${presence.phase}${presence.attached ? '' : ' is-external'}${presence.parentAgentId ? ' is-worker' : ''}`}
+          class={`agent-cursor phase-${presence.phase}${presence.cursor ? ' has-explicit-cursor' : ''}${presence.attached ? '' : ' is-external'}${presence.parentAgentId ? ' is-worker' : ''}`}
           data-session-id={presence.sessionId}
           style={{
             transform: `translate(${position.x}px, ${position.y}px)`,

package/src/client/canvas/BoardCopyDialog.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useRef, useState } from 'preact/hooks';
+import {
+  createBoardFrom,
+  openBoard,
+  previewBoardCopy,
+  type BoardCopyPreview,
+  type BoardSummary,
+} from '../state/boards-store';
+import { useFocusTrap } from './use-focus-trap';
+
+export function BoardCopyDialog({ board, onClose }: { board: BoardSummary; onClose: () => void }) {
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const nameRef = useRef<HTMLInputElement>(null);
+  const [preview, setPreview] = useState<BoardCopyPreview | null>(null);
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [name, setName] = useState(`${board.name} copy`);
+  const [includeReadme, setIncludeReadme] = useState(true);
+  const [includeStructure, setIncludeStructure] = useState(true);
+  const [openAfter, setOpenAfter] = useState(false);
+  const [error, setError] = useState('');
+  const [saving, setSaving] = useState(false);
+  useFocusTrap(dialogRef, true, { initial: nameRef });
+
+  useEffect(() => {
+    let active = true;
+    void previewBoardCopy(board.id).then((result) => {
+      if (!active) return;
+      if (!result || !Array.isArray(result.cards)) return setError('Could not load reusable cards. Try again.');
+      setPreview(result);
+      setSelected(new Set(result.cards.filter((card) => card.reusable).map((card) => card.id)));
+    });
+    return () => {
+      active = false;
+    };
+  }, [board.id]);
+
+  const submit = async (event: Event) => {
+    event.preventDefault();
+    if (!name.trim() || !preview) return;
+    setSaving(true);
+    setError('');
+    const created = await createBoardFrom({
+      sourceBoardId: board.id,
+      name: name.trim(),
+      ...(board.category ? { category: board.category } : {}),
+      nodeIds: [...selected],
+      includeReadme,
+      includeStructure,
+    });
+    setSaving(false);
+    if (!created) return setError('Could not create the board. Try a different name.');
+    if (openAfter) await openBoard(created.id);
+    onClose();
+  };
+
+  return (
+    <div class="text-prompt-backdrop" onMouseDown={onClose}>
+      <div
+        ref={dialogRef}
+        class="text-prompt board-copy-dialog"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="board-copy-title"
+        onMouseDown={(e) => e.stopPropagation()}
+      >
+        <form onSubmit={submit}>
+          <h2 id="board-copy-title">Create from {board.name}</h2>
+          <label class="board-copy-field">
+            Board name
+            <input
+              ref={nameRef}
+              class="text-prompt-input"
+              value={name}
+              onInput={(e) => setName(e.currentTarget.value)}
+            />
+          </label>
+          {!preview && !error && (
+            <div class="board-copy-status" role="status">
+              Loading reusable cards…
+            </div>
+          )}
+          {error && (
+            <div class="board-copy-error" role="alert">
+              {error}
+            </div>
+          )}
+          {preview && (
+            <fieldset class="board-copy-cards">
+              <legend>Cards to copy</legend>
+              {preview.cards.filter((card) => card.reusable).length === 0 ? (
+                <div class="board-copy-status">No reusable cards on this board.</div>
+              ) : (
+                preview.cards
+                  .filter((card) => card.reusable)
+                  .map((card) => (
+                    <label class="board-copy-card" key={card.id}>
+                      <input
+                        type="checkbox"
+                        checked={selected.has(card.id)}
+                        onChange={(e) => {
+                          const next = new Set(selected);
+                          e.currentTarget.checked ? next.add(card.id) : next.delete(card.id);
+                          setSelected(next);
+                        }}
+                      />
+                      <span>
+                        <strong>{card.title || 'Untitled card'}</strong>
+                        <small>{card.type}</small>
+                      </span>
+                    </label>
+                  ))
+              )}
+            </fieldset>
+          )}
+          <div class="board-copy-options">
+            <label>
+              <input
+                type="checkbox"
+                checked={includeStructure}
+                onChange={(e) => setIncludeStructure(e.currentTarget.checked)}
+              />{' '}
+              Preserve groups and connections
+            </label>
+            <label>
+              <input
+                type="checkbox"
+                checked={includeReadme}
+                disabled={!preview?.readmeNodeId}
+                onChange={(e) => setIncludeReadme(e.currentTarget.checked)}
+              />{' '}
+              Include README
+            </label>
+            <label>
+              <input type="checkbox" checked={openAfter} onChange={(e) => setOpenAfter(e.currentTarget.checked)} /> Open
+              the new board after creating
+            </label>
+          </div>
+          <p class="board-copy-note">
+            Only selected cards and structure are copied. Asks, history, and context pins start clear.
+          </p>
+          <div class="text-prompt-actions">
+            <button type="button" onClick={onClose}>
+              Cancel
+            </button>
+            <button type="submit" disabled={!preview || !name.trim() || saving}>
+              {saving ? 'Creating…' : 'Create board'}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  );
+}