pmx-canvas 0.4.8 → 0.5.0

package/src/client/canvas/SessionPanel.tsx

@@ -0,0 +1,481 @@
+import { useEffect, useState } from 'preact/hooks';
+import { useNow } from './use-now';
+import { agentIdentityHue, agentPhaseLabel } from '../../shared/agent-presence.js';
+import { formatCountdown, gateRemainingMs } from '../../shared/approval-gates.js';
+import { focusNode, selectedNodeIds } from '../state/canvas-store';
+import { activeSession, agentPresences } from '../state/presence-store';
+import {
+  type ApprovalGateView,
+  endSession,
+  heldGates,
+  pendingGates,
+  refreshTimeline,
+  reopenGate,
+  resolveGate,
+  scopeFence,
+  setScopeFence,
+  sessionWorkItems,
+  type TimelineEntry,
+  timelineCategory,
+  type TimelineEntryKind,
+  type TimelineFilter,
+  timelineEntries,
+  timelineFilter,
+  undoAgentEdit,
+  undoneActivityIds,
+  type WorkItemStatus,
+  type WorkItemView,
+} from '../state/session-store';
+
+/**
+ * Session panel (rail-chrome-v2 phase 4): the attached agent's work items,
+ * approval gates, and timeline — the human's supervisory surface. Mounted
+ * only while a session is attached (App gates it on sessionActive). Panel and
+ * canvas are one system: a gate resolved here resolves the same AX gate the
+ * on-canvas node controls see.
+ */
+
+/** Design status glyphs: queued · running · awaiting · done · vetoed. */
+const WORK_GLYPH: Record<WorkItemStatus, 'queued' | 'running' | 'awaiting' | 'done' | 'vetoed'> = {
+  todo: 'queued',
+  'in-progress': 'running',
+  blocked: 'awaiting',
+  done: 'done',
+  cancelled: 'vetoed',
+};
+
+/** Chip text per status. Deliberately NOT the glyph name: a cancelled item
+ * (withdrawn, duplicate) was not "vetoed" by anyone — saying so misreads
+ * the board's history. The glyph class keeps the design's visual tone. */
+const WORK_STATUS_TEXT: Record<WorkItemStatus, string> = {
+  todo: 'queued',
+  'in-progress': 'running',
+  blocked: 'awaiting',
+  done: 'done',
+  cancelled: 'cancelled',
+};
+
+// Each chip explains itself on hover — the row vocabulary is jargon otherwise.
+const TIMELINE_FILTERS: Array<{ id: TimelineFilter; label: string; hint: string }> = [
+  { id: 'all', label: 'All', hint: 'Everything below in one feed, newest first' },
+  { id: 'update', label: 'Updates', hint: 'Board edits agents made — nodes, edges, pins, work items' },
+  { id: 'steer', label: 'Steer', hint: 'Instructions sent to agents — by you from the composer, or agent-to-agent' },
+  { id: 'assistant', label: 'Assistant', hint: 'Messages agents posted for you to read' },
+  { id: 'event', label: 'Events', hint: 'Run telemetry — tool runs, approvals, failures, policy notes' },
+  { id: 'evidence', label: 'Evidence', hint: 'Proof agents recorded — test results, artifacts, links' },
+];
+
+const TIMELINE_FILTER_HINTS: Record<TimelineFilter, string> = Object.fromEntries(
+  TIMELINE_FILTERS.map((chip) => [chip.id, chip.hint]),
+) as Record<TimelineFilter, string>;
+
+const TIMELINE_TONE: Record<TimelineEntryKind, string> = {
+  policy: 'warn',
+  prompt: 'accent',
+  'assistant-message': 'muted',
+  'tool-start': 'accent',
+  'tool-result': 'ok',
+  failure: 'danger',
+  approval: 'warn',
+  steering: 'purple',
+  command: 'accent',
+  note: 'muted',
+  evidence: 'ok',
+  steer: 'purple',
+  update: 'purple',
+  yield: 'warn',
+};
+
+function clock(iso: string): string {
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return '';
+  return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+}
+
+function WorkItemRow({ item }: { item: WorkItemView }) {
+  const glyph = WORK_GLYPH[item.status] ?? 'queued';
+  const nodeId = item.nodeIds[0];
+  return (
+    <li class={`session-item status-${glyph}`} data-work-item-id={item.id}>
+      <span class="session-glyph" aria-hidden="true" />
+      <div class="session-item-main">
+        <button
+          type="button"
+          class="session-item-title"
+          title={nodeId ? 'Focus the linked node' : undefined}
+          disabled={!nodeId}
+          onClick={() => nodeId && focusNode(nodeId)}
+        >
+          {item.title}
+        </button>
+        {item.detail && <div class="session-item-detail">{item.detail}</div>}
+      </div>
+      <span class="session-item-status">{WORK_STATUS_TEXT[item.status] ?? glyph}</span>
+      <span class="session-item-time">{clock(item.updatedAt)}</span>
+    </li>
+  );
+}
+
+function GateRow({ gate, now }: { gate: ApprovalGateView; now: number }) {
+  const [busy, setBusy] = useState<'approved' | 'rejected' | null>(null);
+  const decide = async (decision: 'approved' | 'rejected') => {
+    setBusy(decision);
+    await resolveGate(gate, decision);
+    setBusy(null);
+  };
+  const nodeId = gate.nodeIds[0];
+  const remaining = gateRemainingMs(gate, now);
+  return (
+    <li class="session-item status-awaiting session-gate" data-gate-id={gate.id}>
+      <span class="session-glyph" aria-hidden="true" />
+      <div class="session-item-main">
+        <button
+          type="button"
+          class="session-item-title"
+          title={nodeId ? 'Focus the linked node' : undefined}
+          disabled={!nodeId}
+          onClick={() => nodeId && focusNode(nodeId)}
+        >
+          {gate.title}
+        </button>
+        {gate.detail && <div class="session-item-detail">{gate.detail}</div>}
+        {remaining !== null && (
+          <div class="session-gate-ttl" data-testid="gate-countdown">
+            auto-holds in {formatCountdown(remaining)} if unanswered
+          </div>
+        )}
+        <div class="session-gate-actions">
+          <button
+            type="button"
+            class="session-gate-approve"
+            disabled={busy !== null}
+            onClick={() => void decide('approved')}
+          >
+            {busy === 'approved' ? 'Approving…' : 'Approve'}
+          </button>
+          <button
+            type="button"
+            class="session-gate-reject"
+            disabled={busy !== null}
+            onClick={() => void decide('rejected')}
+          >
+            {busy === 'rejected' ? 'Rejecting…' : 'Reject'}
+          </button>
+        </div>
+      </div>
+      <span class="session-item-time">{clock(gate.createdAt)}</span>
+    </li>
+  );
+}
+
+function HeldGateRow({ gate }: { gate: ApprovalGateView }) {
+  const [busy, setBusy] = useState(false);
+  return (
+    <li class="session-item status-vetoed session-gate-held" data-gate-id={gate.id}>
+      <span class="session-glyph" aria-hidden="true" />
+      <div class="session-item-main">
+        <span class="session-item-title">{gate.title}</span>
+        <div class="session-item-detail">Auto-held — no answer in time, the action did not proceed.</div>
+        <div class="session-gate-actions">
+          <button
+            type="button"
+            class="session-gate-reject"
+            disabled={busy}
+            onClick={() => {
+              setBusy(true);
+              void reopenGate(gate).finally(() => setBusy(false));
+            }}
+          >
+            {busy ? 'Reopening…' : 'Reopen'}
+          </button>
+        </div>
+      </div>
+      <span class="session-item-status">held</span>
+    </li>
+  );
+}
+
+/**
+ * Scope row under the header: the fence the human granted, or the affordance
+ * to grant one from the current selection. The server refuses agent writes
+ * outside it; reads stay open.
+ */
+function ScopeRow() {
+  const fence = scopeFence.value;
+  const selected = selectedNodeIds.value.size;
+  const [busy, setBusy] = useState(false);
+  const apply = (nodeIds: string[] | null) => {
+    setBusy(true);
+    void setScopeFence(nodeIds).finally(() => setBusy(false));
+  };
+  return (
+    <div class={`session-scope${fence ? ' is-fenced' : ''}`} data-testid="session-scope">
+      <span class="session-scope-dot" aria-hidden="true" />
+      {fence ? (
+        <>
+          <span class="session-scope-text">
+            Scoped to <strong>{fence.nodeIds.length}</strong> node{fence.nodeIds.length === 1 ? '' : 's'} · writes
+            outside are blocked
+          </span>
+          <button type="button" class="session-scope-action" disabled={busy} onClick={() => apply(null)}>
+            Clear
+          </button>
+        </>
+      ) : (
+        <>
+          <span class="session-scope-text">Unscoped — the agent may write anywhere</span>
+          <button
+            type="button"
+            class="session-scope-action"
+            disabled={busy || selected === 0}
+            title={selected === 0 ? 'Select nodes on the canvas first' : 'Fence the agent to the selected nodes'}
+            onClick={() => apply([...selectedNodeIds.value])}
+          >
+            Fence to selection{selected > 0 ? ` (${selected})` : ''}
+          </button>
+        </>
+      )}
+    </div>
+  );
+}
+
+/** The row writer's display name: roster label when the key is a known writer, 'you' for the human. */
+function writerDisplay(who: string): string {
+  if (who === 'browser') return 'you';
+  const match = agentPresences.value.find((presence) => presence.sessionId === who || presence.source === who);
+  return match?.label ?? who;
+}
+
+function TimelineRow({ entry }: { entry: TimelineEntry }) {
+  const undone = undoneActivityIds.value.has(entry.id);
+  return (
+    <li class={`session-timeline-row tone-${TIMELINE_TONE[entry.kind] ?? 'muted'}`}>
+      <span class="session-timeline-dot" aria-hidden="true" />
+      <div class="session-timeline-main">
+        <div class="session-timeline-head">
+          <span class="session-timeline-label" title={TIMELINE_FILTER_HINTS[timelineCategory(entry.kind)]}>
+            {entry.label}
+          </span>
+          {/* With several assistants on one board, "Assistant · 23:11" answers
+              nothing — every row names its writer in that writer's identity hue. */}
+          {entry.who && (
+            <span
+              class="session-timeline-who"
+              style={{ '--identity-color': `hsl(${agentIdentityHue(entry.who)} 65% 62%)` }}
+            >
+              {writerDisplay(entry.who)}
+            </span>
+          )}
+          <span class="session-item-time">{clock(entry.createdAt)}</span>
+        </div>
+        <div class="session-timeline-body">{entry.body}</div>
+        {/* Item 10: one shared undo stack — the agent's latest edit can be
+            undone from here; the agent hears about it as steering. */}
+        {entry.undoable && !undone && (
+          <button
+            type="button"
+            class="session-timeline-undo"
+            data-testid="timeline-undo"
+            onClick={() => void undoAgentEdit(entry)}
+          >
+            ↩ undo this edit
+          </button>
+        )}
+        {undone && <div class="session-timeline-undone">undone · steering sent</div>}
+      </div>
+    </li>
+  );
+}
+
+export function SessionPanel() {
+  const [collapsed, setCollapsed] = useState(false);
+  const session = activeSession.value;
+  const items = sessionWorkItems.value;
+  const gates = pendingGates.value;
+  const held = heldGates.value;
+  const entries = timelineEntries.value;
+  const [workOpen, setWorkOpen] = useState(false);
+  // Which filter chip the pointer/focus is on — drives the caption under the
+  // row. Native `title` never renders in embedded panes, and an anchored
+  // tooltip would clip against the row's own overflow-x scroll container.
+  const [hoveredFilter, setHoveredFilter] = useState<TimelineFilter | null>(null);
+  const now = useNow();
+
+  // The timeline is read on mount; the SSE bridge refreshes it on every
+  // ax-event-created while a session is attached.
+  useEffect(() => {
+    void refreshTimeline();
+  }, []);
+
+  if (collapsed) {
+    return (
+      <aside class="session-panel is-collapsed" aria-label="Session (collapsed)">
+        <button type="button" class="session-collapse" onClick={() => setCollapsed(false)} title="Expand session panel">
+          ‹
+        </button>
+        <span class="session-collapsed-label">Session</span>
+      </aside>
+    );
+  }
+
+  return (
+    <aside class="session-panel" aria-label="Session">
+      <header class="session-panel-header">
+        <span class="session-panel-title">Session</span>
+        {session && (
+          <span class={`session-live phase-${session.phase}`} title={agentPhaseLabel(session)}>
+            <span class="session-live-dot" aria-hidden="true" />
+            live
+          </span>
+        )}
+        <span class="top-bar-spacer" />
+        {session && (
+          <button
+            type="button"
+            class="session-end"
+            title="End this session — a receipt and a snapshot of the board follow"
+            onClick={() => void endSession(session)}
+          >
+            End
+          </button>
+        )}
+        <button
+          type="button"
+          class="session-collapse"
+          onClick={() => setCollapsed(true)}
+          title="Collapse session panel"
+        >
+          ›
+        </button>
+      </header>
+
+      <ScopeRow />
+      {(() => {
+        // Fixed-position undo: the timeline row's "↩ undo this edit" chip
+        // proved unfindable in live testing (three rounds of a user hunting
+        // it). Whenever the agent's edit tops the shared stack, the same
+        // affordance also sits here — always in the same place.
+        const undoable = entries.find((entry) => entry.undoable && !undoneActivityIds.value.has(entry.id));
+        if (!undoable) return null;
+        return (
+          <div class="session-undo-row" data-testid="session-undo-row">
+            <span class="session-undo-text" title={undoable.body}>
+              Agent edit on top: {undoable.body}
+            </span>
+            <button type="button" class="session-undo-btn" onClick={() => void undoAgentEdit(undoable)}>
+              ↩ Undo
+            </button>
+          </div>
+        );
+      })()}
+
+      <div class="session-panel-body">
+        <section class="session-section">
+          {(() => {
+            // Collapsed by default — the timeline is the panel's main feed and
+            // a stack of done cards buried it. The header keeps the live
+            // signal (pulsing dot + running count); pending gates FORCE the
+            // list open, their approve/reject buttons live here.
+            const running = items.filter((item) => item.status === 'in-progress' || item.status === 'todo').length;
+            // Cancelled items are not outstanding work — "18/20 done" over a
+            // board with 2 cancelled duplicates reads as work remaining when
+            // none does. Count done against the non-cancelled set and name the
+            // cancelled rest.
+            const active = items.filter((item) => item.status !== 'cancelled');
+            const done = active.filter((item) => item.status === 'done').length;
+            const cancelled = items.length - active.length;
+            // Only PENDING gates force the list open — they need a decision.
+            // A held gate is settled (its Reopen is optional) and was pinning
+            // the whole panel un-collapsible (0.5.0 readiness, human report).
+            const mustShow = gates.length > 0;
+            const showList = workOpen || mustShow;
+            const summary =
+              running > 0
+                ? `${running} running`
+                : active.length > 0
+                  ? `${done}/${active.length} done${cancelled > 0 ? ` · ${cancelled} cancelled` : ''}`
+                  : items.length > 0
+                    ? `${items.length} cancelled`
+                    : 'none yet';
+            return (
+              <>
+                <button
+                  type="button"
+                  class="session-section-toggle"
+                  aria-expanded={showList}
+                  data-testid="work-items-toggle"
+                  onClick={() => setWorkOpen((open) => !open)}
+                >
+                  <span class="session-section-title">Work items</span>
+                  <span class="session-work-summary">
+                    {running > 0 && <span class="session-work-dot" aria-hidden="true" />}
+                    {summary}
+                  </span>
+                  <span class={`session-section-chevron${showList ? ' is-open' : ''}`} aria-hidden="true">
+                    ›
+                  </span>
+                </button>
+                {showList &&
+                  (gates.length === 0 && held.length === 0 && items.length === 0 ? (
+                    <div class="session-empty">No work items yet — the agent's tasks and gates appear here.</div>
+                  ) : (
+                    <ul class="session-list" aria-live="polite" aria-label="Work items and gates">
+                      {gates.map((gate) => (
+                        <GateRow key={gate.id} gate={gate} now={now} />
+                      ))}
+                      {held.map((gate) => (
+                        <HeldGateRow key={gate.id} gate={gate} />
+                      ))}
+                      {items.map((item) => (
+                        <WorkItemRow key={item.id} item={item} />
+                      ))}
+                    </ul>
+                  ))}
+              </>
+            );
+          })()}
+        </section>
+
+        <section class="session-section">
+          <h3 class="session-section-title">Timeline</h3>
+          <div class="session-timeline-filters" role="group" aria-label="Filter timeline">
+            {TIMELINE_FILTERS.map((chip) => (
+              <button
+                key={chip.id}
+                type="button"
+                class={`activity-filter${timelineFilter.value === chip.id ? ' is-active' : ''}`}
+                aria-pressed={timelineFilter.value === chip.id}
+                title={chip.hint}
+                onMouseEnter={() => setHoveredFilter(chip.id)}
+                onMouseLeave={() => setHoveredFilter((current) => (current === chip.id ? null : current))}
+                onFocus={() => setHoveredFilter(chip.id)}
+                onBlur={() => setHoveredFilter((current) => (current === chip.id ? null : current))}
+                onClick={() => {
+                  timelineFilter.value = chip.id;
+                }}
+              >
+                {chip.label}
+              </button>
+            ))}
+          </div>
+          {/* The hovered (else active) chip's meaning, always in normal flow —
+              visible on every surface, including ones without native tooltips. */}
+          <div class="session-timeline-hint" data-testid="timeline-filter-hint">
+            {TIMELINE_FILTER_HINTS[hoveredFilter ?? timelineFilter.value]}
+          </div>
+          {entries.length === 0 ? (
+            <div class="session-empty">
+              {timelineFilter.value === 'all' ? 'Nothing recorded yet.' : 'Nothing of this kind yet.'}
+            </div>
+          ) : (
+            <ul class="session-list session-timeline" aria-live="polite" aria-label="Timeline">
+              {entries.map((entry) => (
+                <TimelineRow key={entry.id} entry={entry} />
+              ))}
+            </ul>
+          )}
+        </section>
+      </div>
+    </aside>
+  );
+}

package/src/client/canvas/SessionReceipt.tsx

@@ -0,0 +1,141 @@
+import { useState } from 'preact/hooks';
+import { dismissSessionReceipt, sessionReceipt } from '../state/session-store';
+
+/**
+ * Session receipt (rail-chrome-v2 phase 5, design item 2): a dismissible card
+ * at the canvas region's top-right after a session ends — what the session did
+ * (items / done / vetoed), the pre-session snapshot (taken at attach, so View
+ * diff shows the session's changes and a restore undoes them), and History
+ * (the snapshots panel). Client-side state, cleared on dismiss.
+ */
+
+export interface DiffSummary {
+  added: number;
+  removed: number;
+  modified: number;
+}
+
+/** The wire shape is SnapshotDiffResult (addedNodes/removedNodes/modifiedNodes/addedEdges/removedEdges). */
+export function summarizeDiff(diff: unknown): DiffSummary | null {
+  if (!diff || typeof diff !== 'object') return null;
+  const d = diff as Record<string, unknown>;
+  const count = (value: unknown): number => (Array.isArray(value) ? value.length : 0);
+  return {
+    added: count(d.addedNodes) + count(d.addedEdges),
+    removed: count(d.removedNodes) + count(d.removedEdges),
+    modified: count(d.modifiedNodes),
+  };
+}
+
+export function SessionReceipt({ onOpenSnapshots }: { onOpenSnapshots: () => void }) {
+  const receipt = sessionReceipt.value;
+  const [diff, setDiff] = useState<DiffSummary | null>(null);
+  const [loadingDiff, setLoadingDiff] = useState(false);
+  if (!receipt) return null;
+
+  const viewDiff = async () => {
+    if (!receipt.snapshot) return;
+    setLoadingDiff(true);
+    try {
+      const response = await fetch(`/api/canvas/snapshots/${encodeURIComponent(receipt.snapshot.id)}/diff`, {
+        headers: { 'x-pmx-workbench': '1' },
+      });
+      if (response.ok) {
+        const body = (await response.json()) as { diff?: unknown };
+        setDiff(summarizeDiff(body.diff) ?? { added: 0, removed: 0, modified: 0 });
+      }
+    } finally {
+      setLoadingDiff(false);
+    }
+  };
+
+  const ended = new Date(receipt.endedAt);
+  const endedLabel = Number.isNaN(ended.getTime())
+    ? ''
+    : `${String(ended.getHours()).padStart(2, '0')}:${String(ended.getMinutes()).padStart(2, '0')}`;
+
+  return (
+    <div class="session-receipt" data-testid="session-receipt" role="status">
+      <div class="session-receipt-head">
+        <span class="session-receipt-dot" aria-hidden="true" />
+        <span class="session-receipt-title">
+          {receipt.endedBy === 'human'
+            ? 'Session ended by you'
+            : receipt.endedBy === 'idle-timeout'
+              ? 'Session ended — idle timeout'
+              : receipt.endedBy === 'agent'
+                ? 'Session ended by the agent'
+                : 'Session ended'}
+          {endedLabel ? ` · ${endedLabel}` : ''}
+        </span>
+        <button
+          type="button"
+          class="session-receipt-close"
+          onClick={dismissSessionReceipt}
+          aria-label="Dismiss receipt"
+        >
+          ×
+        </button>
+      </div>
+      <div class="session-receipt-tiles">
+        <div class="session-receipt-tile">
+          <span class="session-receipt-tile-label">Items</span>
+          <span class="session-receipt-tile-value">{receipt.counts.items}</span>
+        </div>
+        <div class="session-receipt-tile">
+          <span class="session-receipt-tile-label">Done</span>
+          <span class="session-receipt-tile-value tone-ok">{receipt.counts.done}</span>
+        </div>
+        {/* Three different outcomes, shown only when present — a cancelled
+            duplicate is not a rejection, and neither is an unanswered gate. */}
+        {receipt.counts.cancelled > 0 && (
+          <div class="session-receipt-tile">
+            <span class="session-receipt-tile-label">Cancelled</span>
+            <span class="session-receipt-tile-value tone-muted">{receipt.counts.cancelled}</span>
+          </div>
+        )}
+        {receipt.counts.rejected > 0 && (
+          <div class="session-receipt-tile">
+            <span class="session-receipt-tile-label">Rejected</span>
+            <span class="session-receipt-tile-value tone-danger">{receipt.counts.rejected}</span>
+          </div>
+        )}
+        {receipt.counts.held > 0 && (
+          <div class="session-receipt-tile">
+            <span class="session-receipt-tile-label">Held</span>
+            <span class="session-receipt-tile-value tone-warn">{receipt.counts.held}</span>
+          </div>
+        )}
+      </div>
+      <div class="session-receipt-note">
+        {receipt.snapshot
+          ? 'A snapshot of the board from before this session is saved — restore it to undo the session.'
+          : receipt.unchanged
+            ? 'This session changed nothing on the board — no snapshot kept.'
+            : 'The board was empty when the session started — nothing to restore.'}
+      </div>
+      {diff && (
+        <div class="session-receipt-diff" data-testid="session-receipt-diff">
+          This session: {diff.added} added · {diff.removed} removed · {diff.modified} modified
+        </div>
+      )}
+      <div class="session-receipt-actions">
+        {/* No snapshot → no diff will ever exist for this receipt; a forever-
+            disabled button is noise (the note above says why). */}
+        {receipt.snapshot && (
+          <button type="button" class="session-receipt-primary" disabled={loadingDiff} onClick={() => void viewDiff()}>
+            {loadingDiff ? 'Comparing…' : 'View diff'}
+          </button>
+        )}
+        <button
+          type="button"
+          class="session-receipt-secondary"
+          title="Open the History drawer — saved boards and past sessions"
+          onClick={onOpenSnapshots}
+        >
+          History
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/client/canvas/ShortcutOverlay.tsx

@@ -1,4 +1,4 @@
-import { MOD_KEY as MOD } from '../utils/platform';
+import { isMac, modChord } from '../utils/platform';
 
 interface ShortcutGroup {
   title: string;
@@ -6,19 +6,32 @@ interface ShortcutGroup {
 }
 
 const GROUPS: ShortcutGroup[] = [
+  {
+    title: 'Tools',
+    shortcuts: [
+      { keys: 'V', desc: 'Select tool — drag empty space to lasso' },
+      { keys: 'Space (hold)', desc: 'Pan — drag anywhere moves the board' },
+      { keys: 'A', desc: 'Annotate — draw on the canvas' },
+    ],
+  },
   {
     title: 'Navigation',
     shortcuts: [
-      { keys: `${MOD}+K`, desc: 'Command palette — search nodes & actions' },
+      { keys: modChord('K'), desc: 'Command palette — search nodes & actions' },
       { keys: 'Tab / Shift+Tab', desc: 'Cycle through nodes' },
       { keys: '\u2190 \u2191 \u2192 \u2193', desc: 'Walk graph along edges (when node focused)' },
-      { keys: `${MOD}+0`, desc: 'Reset viewport to origin' },
-      { keys: `${MOD}++ / ${MOD}+\u2212`, desc: 'Zoom in / out' },
+      { keys: 'F', desc: 'Fit all nodes on screen' },
+      { keys: modChord('0'), desc: 'Reset viewport to origin' },
+      { keys: `${modChord('+')} / ${modChord('\u2212')}`, desc: 'Zoom in / out' },
     ],
   },
   {
     title: 'Creation',
     shortcuts: [
+      { keys: 'M', desc: 'New markdown note' },
+      { keys: 'I / W / H', desc: 'New image / webpage / HTML surface' },
+      { keys: 'Shift+F', desc: 'New file node (workspace path)' },
+      { keys: 'G / Shift+G', desc: 'Group the selection (new frame when empty) / ungroup' },
       { keys: 'Double-click', desc: 'Create new markdown note on canvas' },
       { keys: 'Drag port \u2192 node', desc: 'Connect two nodes (hover to reveal ports)' },
     ],
@@ -28,7 +41,9 @@ const GROUPS: ShortcutGroup[] = [
     shortcuts: [
       { keys: 'Click', desc: 'Focus node (highlights neighbors & edges)' },
       { keys: 'Shift+Click', desc: 'Toggle node in multi-selection' },
-      { keys: 'Shift+Drag', desc: 'Lasso select multiple nodes' },
+      { keys: 'Drag empty space', desc: 'Lasso select multiple nodes' },
+      { keys: isMac ? 'Delete / \u232b' : 'Delete / Backspace', desc: 'Delete the selection (or the focused node)' },
+      { keys: isMac ? '\u2318Z / \u21e7\u2318Z' : 'Ctrl+Z / Ctrl+Y', desc: 'Undo / redo — agent edits included' },
       { keys: 'Esc', desc: 'Clear selection / close overlay' },
     ],
   },
@@ -36,7 +51,7 @@ const GROUPS: ShortcutGroup[] = [
     title: 'View',
     shortcuts: [
       { keys: '?', desc: 'Toggle this shortcut overlay' },
-      { keys: 'Minimap', desc: 'Click/drag to navigate (toggle in toolbar)' },
+      { keys: 'Minimap', desc: 'Click/drag to navigate (toggle in the rail)' },
       { keys: 'Right-click', desc: 'Context menu — dock, focus, connect' },
     ],
   },