pmx-canvas 0.4.7 → 0.5.0

package/src/client/canvas/TopBar.tsx

@@ -0,0 +1,308 @@
+import type { ComponentChildren } from 'preact';
+import { useEffect, useState } from 'preact/hooks';
+import { IconFitAll, IconZoomIn, IconZoomOut } from '../icons';
+import {
+  animateViewport,
+  connectionStatus,
+  edges,
+  fitAll,
+  hasInitialServerLayout,
+  nodes,
+  sessionId,
+  traceEnabled,
+  viewport,
+  zoomByFactor,
+} from '../state/canvas-store';
+import { modChord } from '../utils/platform';
+import { canvasArea } from './canvas-area';
+import { BarHint } from './BarHint';
+import { degradedState } from './ConnectionBanner';
+import { ExternalWriterIndicator } from './ExternalWriters';
+import { useNow } from './use-now';
+import { agentPhaseLabel } from '../../shared/agent-presence.js';
+import { agentIdentityHue } from '../../shared/agent-presence.js';
+import { activeSession, agentPresences, attachedSessions, contextBudget } from '../state/presence-store';
+import { endSession, pendingGates, startSession } from '../state/session-store';
+import { formatCountdown, gateRemainingMs } from '../../shared/approval-gates.js';
+
+/**
+ * The attached session's chip (rail-chrome-v2 phase 3): phase-colored, with a
+ * dot that pulses while the agent thinks or runs a tool. Renders ONLY while a
+ * session is attached — the quiet board shows nothing here until phase 5
+ * lands the "Start agent session" affordance.
+ */
+function AgentChip() {
+  // Every attached session gets its chip — with several agents on the board,
+  // showing only the first hid the rest from the top bar entirely.
+  const sessions = attachedSessions.value;
+  if (sessions.length === 0) return null;
+  return (
+    <>
+      {sessions.map((session) => {
+        // Fleet roll-up: workers declaring this session as their parent count
+        // into its chip instead of growing the bar one chip per worker.
+        const workers = agentPresences.value.filter(
+          (presence) =>
+            presence.parentAgentId != null &&
+            (presence.parentAgentId === session.sessionId || presence.parentAgentId === session.source),
+        ).length;
+        return (
+          <BarHint
+            key={session.sessionId}
+            label={`Agent session — ${session.label}`}
+            tapToOpen
+            body="What this attached agent is doing right now: idle, thinking, running a tool, or waiting on your approval. Steer it from the composer below."
+          >
+            <span
+              class={`agent-chip phase-${session.phase}`}
+              data-phase={session.phase}
+              style={{ '--identity-color': `hsl(${agentIdentityHue(session.sessionId)} 65% 62%)` }}
+            >
+              <span class="agent-chip-dot" aria-hidden="true" />
+              <span class="agent-chip-label">{agentPhaseLabel(session)}</span>
+              <span class="agent-chip-who hud-collapsible-text">{session.label}</span>
+              {workers > 0 && (
+                <span class="agent-chip-workers">
+                  +{workers} worker{workers === 1 ? '' : 's'}
+                </span>
+              )}
+              <button
+                type="button"
+                class="agent-chip-end"
+                aria-label={`End ${session.label} session`}
+                title={`End ${session.label}'s session`}
+                onClick={(e) => {
+                  // The chip sits inside a tap-to-open hint — ending a session
+                  // must not also open it.
+                  e.stopPropagation();
+                  void endSession({ source: session.source, agentId: session.agentId });
+                }}
+              >
+                ×
+              </button>
+            </span>
+          </BarHint>
+        );
+      })}
+    </>
+  );
+}
+
+/**
+ * Amber escalation badge while any approval gate is pending in an attached
+ * session: "1 gate · 4:31" — the countdown is the soonest auto-hold.
+ */
+function GateBadge() {
+  const count = pendingGates.value.length;
+  const active = activeSession.value !== null && count > 0;
+  const now = useNow(active ? 1000 : 0);
+  if (!active) return null;
+  const soonest = pendingGates.value
+    .map((gate) => gateRemainingMs(gate, now))
+    .filter((ms): ms is number => ms !== null)
+    .sort((a, b) => a - b)[0];
+  return (
+    <BarHint
+      label="Approval gates waiting on you"
+      tapToOpen
+      body="The agent is blocked until you approve or reject in the session panel; unanswered gates auto-hold when the countdown runs out."
+    >
+      <span class="gate-badge">
+        {count} gate{count === 1 ? '' : 's'}
+        {soonest !== undefined && ` · ${formatCountdown(soonest)}`}
+      </span>
+    </BarHint>
+  );
+}
+
+function budgetTone(ratio: number): 'ok' | 'warn' | 'danger' {
+  if (ratio > 0.9) return 'danger';
+  if (ratio >= 0.7) return 'warn';
+  return 'ok';
+}
+
+function formatTokens(value: number): string {
+  return value >= 1000 ? `${(value / 1000).toFixed(value >= 10_000 ? 0 : 1)}k` : String(value);
+}
+
+/**
+ * Context meter (rail-chrome-v2 phase 5). Two honest modes:
+ * - the host reported the agent's REAL window (`contextUsage` on its presence)
+ *   → "Context": used / window, with the pinned payload as a note;
+ * - nothing reported (no adapter does yet) → "Pins": the pinned-context
+ *   payload estimate against the configured budget
+ *   (PMX_CANVAS_CONTEXT_BUDGET_TOKENS). Never presented as the agent's window.
+ * Session-only, like the chip; the estimate moves within a frame of a pin toggle.
+ */
+function ContextBudget() {
+  const session = activeSession.value;
+  if (!session) return null;
+  const budget = contextBudget.value;
+  const real = session.contextUsage;
+  const used = real ? real.used : budget.used;
+  const total = real ? real.total : budget.total;
+  const ratio = total > 0 ? Math.min(1, used / total) : 0;
+  const pct = Math.round(ratio * 100);
+  const hint = real
+    ? {
+        label: `Context window — reported by ${session.label}`,
+        body: `${formatTokens(real.used)} of ${formatTokens(real.total)} tokens of the agent's actual context window are used. Your ✦-pinned nodes account for ≈ ${formatTokens(budget.used)} tokens of it.`,
+      }
+    : {
+        label: 'Pins — pinned-context size (estimate)',
+        body: `The nodes you pinned (✦) are what the agent is asked to carry as context: ≈ ${formatTokens(budget.used)} of a ${formatTokens(budget.total)}-token budget. When the agent's host reports its real context window, this meter switches to showing that instead.`,
+      };
+  return (
+    <BarHint label={hint.label} body={hint.body} tapToOpen>
+      <span class={`context-budget tone-${budgetTone(ratio)}`} data-mode={real ? 'window' : 'pins'}>
+        <span class="context-budget-caption hud-collapsible-text">{real ? 'Context' : 'Pins'}</span>
+        <span class="context-budget-track" aria-hidden="true">
+          <span class="context-budget-fill" style={{ width: `${pct}%` }} />
+        </span>
+        <span class="context-budget-label" data-testid="budget-label">
+          {used > 0 && pct === 0 ? '<1' : pct}%
+        </span>
+      </span>
+    </BarHint>
+  );
+}
+
+/**
+ * Quiet-board affordance (rail-chrome-v2 phase 5): attach a human-started
+ * session. The agent's subsequent MCP/HTTP writes are attributed to it, which
+ * is what turns the quiet board into a Focus Session with a cursor and panel.
+ */
+function StartSessionButton() {
+  const [busy, setBusy] = useState(false);
+  if (activeSession.value) return null;
+  return (
+    <BarHint
+      label="Start an agent session"
+      body="Attaches a session to this board: the next agent that writes here is adopted into it, and you get the panel, composer, and receipt."
+    >
+      <button
+        type="button"
+        class="start-session-btn"
+        disabled={busy}
+        onClick={() => {
+          setBusy(true);
+          void startSession().finally(() => setBusy(false));
+        }}
+      >
+        <span class="start-session-dot" aria-hidden="true" />
+        Start agent session
+        <span class="beta-tag">beta</span>
+      </button>
+    </BarHint>
+  );
+}
+
+/**
+ * The slim 44px top bar (rail-chrome-v2 phase 1): connection state, board
+ * identity on the left, view controls on the right. `overflow:hidden` +
+ * `min-width:0` discipline throughout — the title ellipsizes, meta collapses
+ * below 1180px, and nothing ever wraps to a second row.
+ */
+export function TopBar() {
+  const status = connectionStatus.value;
+  const hasSynced = hasInitialServerLayout.value;
+  const v = viewport.value;
+  const nodeCount = nodes.value.size;
+  const edgeCount = edges.value.size;
+  const isTraceOn = traceEnabled.value;
+  const traceNodeCount = Array.from(nodes.value.values()).filter((n) => n.type === 'trace').length;
+
+  // Board identity = workspace basename, fetched once from /health. The
+  // canvas has no board-name concept — the workspace IS the board.
+  const [workspaceName, setWorkspaceName] = useState<string>('');
+  useEffect(() => {
+    let cancelled = false;
+    fetch('/health')
+      .then((r) => (r.ok ? r.json() : null))
+      .then((data: { workspace?: string } | null) => {
+        if (cancelled || typeof data?.workspace !== 'string' || !data.workspace) return;
+        const base = data.workspace
+          .replace(/[\\/]+$/, '')
+          .split(/[\\/]/)
+          .pop();
+        if (base) setWorkspaceName(base);
+      })
+      .catch(() => {});
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const degraded = degradedState.value;
+  const statusTitle = degraded ?? (status === 'connected' && !hasSynced ? 'syncing' : status);
+  const countsLabel = hasSynced
+    ? [
+        `${nodeCount} node${nodeCount !== 1 ? 's' : ''}`,
+        ...(edgeCount > 0 ? [`${edgeCount} edge${edgeCount !== 1 ? 's' : ''}`] : []),
+        ...(traceNodeCount > 0
+          ? [`${traceNodeCount} trace${traceNodeCount !== 1 ? 's' : ''}`]
+          : isTraceOn
+            ? ['trace armed']
+            : []),
+      ].join(' · ')
+    : 'Syncing canvas…';
+
+  const handleFit = () => {
+    const area = canvasArea();
+    fitAll(area.width, area.height);
+  };
+
+  return (
+    <div class="top-bar">
+      <BarHint
+        label={`Canvas status: ${statusTitle}`}
+        tapToOpen
+        body="Live updates stream in over SSE; amber means reconnecting."
+        align="start"
+      >
+        <span class={`connection-dot ${degraded ?? status}`} aria-label={`Canvas status: ${statusTitle}`} />
+      </BarHint>
+      <span class="top-bar-title" title={workspaceName || 'PMX Canvas'}>
+        {workspaceName || 'PMX Canvas'}
+      </span>
+      <span class="top-bar-meta hud-collapsible-text">{sessionId.value ? sessionId.value.slice(0, 12) : '…'}</span>
+      <span class="top-bar-meta hud-collapsible-text">{countsLabel}</span>
+
+      <span class="top-bar-spacer" />
+
+      <AgentChip />
+      <GateBadge />
+      <ContextBudget />
+      <ExternalWriterIndicator />
+      <StartSessionButton />
+
+      <div class="top-bar-sep" />
+
+      <BarHint label="Zoom out" shortcut={modChord('\u2212')}>
+        <button type="button" class="top-bar-btn" onClick={() => zoomByFactor(1 / 1.25)} aria-label="Zoom out">
+          <IconZoomOut />
+        </button>
+      </BarHint>
+      <BarHint label="Reset zoom" shortcut={modChord('0')}>
+        <button
+          type="button"
+          class="top-bar-zoom-label"
+          onClick={() => animateViewport({ x: 0, y: 0, scale: 1 }, 250)}
+          aria-label="Reset view"
+        >
+          {Math.round(v.scale * 100)}%
+        </button>
+      </BarHint>
+      <BarHint label="Zoom in" shortcut={modChord('+')}>
+        <button type="button" class="top-bar-btn" onClick={() => zoomByFactor(1.25)} aria-label="Zoom in">
+          <IconZoomIn />
+        </button>
+      </BarHint>
+      <BarHint label="Fit all" shortcut="F" align="end">
+        <button type="button" class="top-bar-btn" onClick={handleFit} aria-label="Fit canvas">
+          <IconFitAll />
+        </button>
+      </BarHint>
+    </div>
+  );
+}

package/src/client/canvas/auto-fit.ts

@@ -45,11 +45,7 @@ function isContentFitSurface(node: CanvasNodeState): boolean {
  *  whose height is controlled elsewhere. */
 function isAutoSizeExempt(node: CanvasNodeState): boolean {
   return (
-    node.collapsed === true ||
-    node.dockPosition != null ||
-    node.data.strictSize === true ||
-    node.data.userResized === true ||
-    node.type === 'group'
+    node.collapsed === true || node.data.strictSize === true || node.data.userResized === true || node.type === 'group'
   );
 }
 

package/src/client/canvas/canvas-area.ts

@@ -0,0 +1,41 @@
+/**
+ * The canvas region's box in screen coordinates. With the rail + top-bar shell
+ * the canvas no longer spans the window, so every "centre of the view" and
+ * "how big is the view" computation must use this region — anchoring zoom at
+ * `window.innerWidth / 2` would drift the board toward the rail on every step,
+ * and reporting the window to the server makes an agent `fit` compute a scale
+ * that hides nodes under the chrome.
+ *
+ * The shell registers its canvas-region element on mount; everything else asks
+ * for the rect. The window fallback keeps unit tests and any chromeless embed
+ * working unchanged.
+ */
+
+export interface CanvasAreaRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+let canvasAreaEl: HTMLElement | null = null;
+
+export function registerCanvasArea(el: HTMLElement | null): void {
+  canvasAreaEl = el;
+}
+
+export function canvasArea(): CanvasAreaRect {
+  if (canvasAreaEl?.isConnected) {
+    const rect = canvasAreaEl.getBoundingClientRect();
+    if (rect.width > 0 && rect.height > 0) {
+      return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+    }
+  }
+  return { left: 0, top: 0, width: window.innerWidth, height: window.innerHeight };
+}
+
+/** Screen-space centre of the canvas region — the anchor for centred zoom/focus. */
+export function canvasAreaCenter(): { x: number; y: number } {
+  const rect = canvasArea();
+  return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+}

package/src/client/canvas/create-in-view.ts

@@ -0,0 +1,48 @@
+import { focusNode, viewport } from '../state/canvas-store';
+import { createNodeFromClient } from '../state/intent-bridge';
+import { canvasAreaCenter } from './canvas-area';
+
+/** Default frames for human creates that pass no size (the server clamps to the type floor). */
+const DEFAULT_FRAME: Record<string, { width: number; height: number }> = {
+  markdown: { width: 520, height: 360 },
+  group: { width: 600, height: 400 },
+  html: { width: 720, height: 640 },
+  image: { width: 720, height: 520 },
+  file: { width: 720, height: 600 },
+  webpage: { width: 520, height: 420 },
+};
+
+/**
+ * A human create from the rail, keyboard, palette, or empty state lands
+ * centred in the CURRENT viewport — where the human is looking — instead of
+ * at the server's board-relative auto-placement, which on a busy board can
+ * be far off-screen (the rail's Group landed out of view). Explicit x/y win.
+ */
+export async function createNodeInView(opts: {
+  type: string;
+  title?: string;
+  content?: string;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+}): Promise<{ ok: boolean; id?: string }> {
+  if (opts.x !== undefined && opts.y !== undefined) return createNodeFromClient(opts);
+  const frame = DEFAULT_FRAME[opts.type] ?? { width: 360, height: 200 };
+  const width = opts.width ?? frame.width;
+  const height = opts.height ?? frame.height;
+  const centre = canvasAreaCenter();
+  const v = viewport.value;
+  const result = await createNodeFromClient({
+    ...opts,
+    width,
+    height,
+    x: Math.round((centre.x - v.x) / v.scale - width / 2),
+    y: Math.round((centre.y - v.y) / v.scale - height / 2),
+  });
+  // The shared viewport can move between the ask (a prompted dialog) and the
+  // create — focus the node so it can never land off-screen (0.5.0 readiness,
+  // Codex: Open image… required a palette hunt to find its node).
+  if (result.ok && result.id) focusNode(result.id);
+  return result;
+}

package/src/client/canvas/import-files.ts

@@ -0,0 +1,64 @@
+import { createNodeFromClient } from '../state/intent-bridge';
+
+const IMAGE_EXTS = new Set(['png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'bmp', 'ico', 'avif']);
+const MD_EXTS = new Set(['md', 'mdx', 'markdown']);
+
+export function nodeTypeFromFilename(name: string): 'image' | 'markdown' | 'file' {
+  const ext = name.split('.').pop()?.toLowerCase() ?? '';
+  if (IMAGE_EXTS.has(ext)) return 'image';
+  if (MD_EXTS.has(ext)) return 'markdown';
+  return 'file';
+}
+
+/**
+ * Turn local files into nodes laid out in a grid around a world point — the
+ * one implementation behind the viewport's drop zone and the empty state's
+ * file picker. Images become image nodes (data URI), markdown becomes
+ * markdown, everything else a file node with the text inlined.
+ */
+export async function importFiles(files: File[], baseWx: number, baseWy: number): Promise<void> {
+  const nodeW = 400;
+  const nodeH = 300;
+  const spacing = 20;
+  const cols = Math.ceil(Math.sqrt(files.length));
+
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i]!;
+    const col = i % cols;
+    const row = Math.floor(i / cols);
+    const wx = baseWx - (cols * (nodeW + spacing)) / 2 + col * (nodeW + spacing);
+    const wy = baseWy - nodeH / 2 + row * (nodeH + spacing);
+
+    const type = nodeTypeFromFilename(file.name);
+    const fileName = file.name;
+
+    if (type === 'image') {
+      const reader = new FileReader();
+      const dataUri: string = await new Promise((resolve) => {
+        reader.onload = () => resolve(reader.result as string);
+        reader.readAsDataURL(file);
+      });
+      await createNodeFromClient({
+        type: 'image',
+        title: fileName,
+        content: dataUri,
+        x: wx,
+        y: wy,
+        width: nodeW,
+        height: nodeH,
+      });
+    } else {
+      const text = await file.text();
+      const isWide = type === 'markdown' || type === 'file';
+      await createNodeFromClient({
+        type,
+        title: fileName,
+        content: text,
+        x: wx,
+        y: wy,
+        width: isWide ? 720 : nodeW,
+        height: isWide ? 500 : nodeH,
+      });
+    }
+  }
+}

package/src/client/canvas/kind-colors.ts

@@ -0,0 +1,22 @@
+import type { CanvasNodeState } from '../types';
+
+/** Kind color per node type, as CSS tokens so every theme keeps its palette. */
+export const KIND_COLOR: Record<CanvasNodeState['type'], string> = {
+  markdown: 'var(--c-accent)',
+  'mcp-app': 'var(--c-ok)',
+  webpage: 'var(--c-warn)',
+  'json-render': 'var(--c-ok)',
+  graph: 'var(--c-purple)',
+  prompt: 'var(--c-accent)',
+  response: 'var(--c-ok)',
+  status: 'var(--c-warn)',
+  context: 'var(--c-muted)',
+  ledger: 'var(--c-dim)',
+  trace: 'var(--c-purple)',
+  file: 'var(--c-accent)',
+  diff: 'var(--c-ok)',
+  mermaid: 'var(--c-purple)',
+  image: 'var(--c-ok)',
+  html: 'var(--c-warn)',
+  group: 'var(--c-accent)',
+};

package/src/client/canvas/snap-guides.ts

@@ -81,7 +81,7 @@ export function buildSnapCache(dragId: string, allNodes: Iterable<CanvasNodeStat
   const nodeList = Array.from(allNodes);
   const excludedIds = collectExcludedReferenceIds(dragId, nodeList);
   for (const n of nodeList) {
-    if (excludedIds.has(n.id) || n.dockPosition !== null) continue;
+    if (excludedIds.has(n.id)) continue;
     const l = n.position.x;
     const r = n.position.x + n.size.width;
     const cx = n.position.x + n.size.width / 2;

package/src/client/canvas/use-focus-trap.ts

@@ -0,0 +1,54 @@
+import { useEffect } from 'preact/hooks';
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Focus trap for modal overlays (rail-chrome-v2 item 18): while `active`, Tab
+ * cycles inside `ref`, the first focusable takes focus on open unless
+ * `initial` names one, and the element focused before the overlay opened gets
+ * focus back on close.
+ */
+export function useFocusTrap(
+  ref: { current: HTMLElement | null },
+  active: boolean,
+  options: { initial?: { current: HTMLElement | null }; restoreTo?: () => HTMLElement | null } = {},
+): void {
+  useEffect(() => {
+    if (!active) return;
+    const root = ref.current;
+    if (!root) return;
+    const previous = document.activeElement as HTMLElement | null;
+    const restoreTo = options.restoreTo;
+    const focusables = () => Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE));
+    const initial = options.initial?.current ?? focusables()[0];
+    if (initial && !root.contains(document.activeElement)) initial.focus();
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+      const items = focusables();
+      if (items.length === 0) return;
+      const first = items[0]!;
+      const last = items[items.length - 1]!;
+      const current = document.activeElement as HTMLElement | null;
+      if (e.shiftKey && (current === first || !root.contains(current))) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && current === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    root.addEventListener('keydown', onKey);
+    return () => {
+      root.removeEventListener('keydown', onKey);
+      // `restoreTo` wins: an overlay that replaced the element it was opened
+      // from (focus mode unmounts the node while expanded) names the element
+      // to return to, which may only exist after the next frame.
+      if (restoreTo) {
+        requestAnimationFrame(() => restoreTo()?.focus());
+      } else if (previous && document.contains(previous) && previous !== document.body) {
+        previous.focus();
+      }
+    };
+  }, [ref, active, options.initial, options.restoreTo]);
+}

package/src/client/canvas/use-now.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'preact/hooks';
+
+/**
+ * A ticking "now" for countdowns and relative ages. `intervalMs` 0 stops the
+ * ticker (the value still reads as the mount time) — pass 0 while the surface
+ * that needs it is hidden so an idle page runs no timers.
+ */
+export function useNow(intervalMs = 1000): number {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (intervalMs <= 0) return;
+    setNow(Date.now());
+    const timer = window.setInterval(() => setNow(Date.now()), intervalMs);
+    return () => window.clearInterval(timer);
+  }, [intervalMs]);
+  return now;
+}

package/src/client/canvas/use-pan-zoom.ts

@@ -1,4 +1,5 @@
 import type { Signal } from '@preact/signals';
+import { isPanModeActive } from '../state/canvas-store';
 import { useCallback, useEffect, useRef } from 'preact/hooks';
 import type { ViewportState } from '../types';
 
@@ -100,9 +101,19 @@ export function usePanZoom({ viewport, onViewportChange, onViewportCommit, disab
   const handlePointerDown = useCallback(
     (e: PointerEvent) => {
       if (disabled) return;
-      // Only pan when clicking the canvas background (not nodes)
       const container = containerRef.current;
-      if (!container || e.target !== container) return;
+      if (!container) return;
+      // Middle-drag pans from anywhere, any tool — standard canvas UX.
+      if (e.button === 1) {
+        e.preventDefault();
+      } else if (isPanModeActive()) {
+        // Pan tool / held Space: the world layer is pointer-inert (CSS), so
+        // the event target is the container even over nodes.
+        if (e.target !== container) return;
+      } else {
+        // Select tool: background drag belongs to the lasso (CanvasViewport).
+        return;
+      }
       isPanning.current = true;
       lastPointer.current = { x: e.clientX, y: e.clientY };
       container.setPointerCapture(e.pointerId);