pmx-canvas 0.8.2 → 0.9.1

package/src/client/canvas/EdgeLayer.tsx

@@ -1,25 +1,138 @@
-import type { Signal } from '@preact/signals';
+import { type Signal, signal } from '@preact/signals';
+import { useEffect, useRef } from 'preact/hooks';
 import {
-  activeNodeId,
   draggingEdge,
+  edges,
   searchHighlightIds,
   selectedEdgeId,
   viewport,
   visibleNodeFor,
 } from '../state/canvas-store';
+import { linkMarks, writerName } from '../state/context-status-store';
+import { HUMAN_STARTED_SESSION_LABEL } from '../../shared/agent-presence';
+import { activeSession } from '../state/presence-store';
+import { activeBoard } from '../state/boards-store';
+import { reportClientViewportSize } from '../state/intent-bridge';
+import { relationDefinition, relationKind, relationText } from '../../shared/relations.js';
 import type { CanvasEdge, CanvasNodeState } from '../types';
+import { relationFilter, relationFocus, relationHighlight } from '../state/relation-store';
 
-// ── Edge type visual styles ──────────────────────────────────
-const EDGE_COLORS: Record<CanvasEdge['type'], string> = {
-  relation: 'var(--c-muted)',
-  'depends-on': 'var(--c-rel-informs)',
-  flow: 'var(--c-accent)',
-  // --c-dim is a very low-contrast hairline in dark palettes (forest: #5D7566
-  // on #0C1712); the dashed style is what distinguishes `references`.
-  references: 'var(--c-muted)',
-};
+/** Filter only the kinds on this board; shared presets are managed in Home. */
+export function RelationLegend() {
+  const board = activeBoard();
+  const list = [...edges.value.values()];
+  const legendRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const legend = legendRef.current;
+    if (!legend) return;
+    const observer = new ResizeObserver(() => void reportClientViewportSize());
+    observer.observe(legend);
+    return () => observer.disconnect();
+  }, [board?.id, list.length > 0]);
+  if (!board || list.length === 0) return null;
+  const kinds = [...new Set(list.map(relationKind))];
+  const selected = relationFilter.value?.boardId === board.id ? relationFilter.value.kind : null;
+  return (
+    <div
+      ref={legendRef}
+      class="relation-legend"
+      aria-label="Relation legend"
+      onPointerDown={(event) => event.stopPropagation()}
+    >
+      <select
+        aria-label="Filter board relations"
+        value={selected ?? ''}
+        onChange={(event) => {
+          const kind = event.currentTarget.value;
+          relationFilter.value = kind ? { boardId: board.id, kind } : null;
+        }}
+      >
+        <option value="">All relations</option>
+        {kinds.map((kind) => (
+          <option key={kind} value={kind}>
+            {kind} · {list.filter((edge) => relationKind(edge) === kind).length}
+          </option>
+        ))}
+      </select>
+      {kinds.map((kind) => {
+        const definition = relationDefinition({ kind }, board.relationVocabulary);
+        return (
+          <button
+            type="button"
+            key={kind}
+            aria-pressed={selected === kind}
+            style={{ '--relation-ink': `var(--c-rel-${definition.ink})` }}
+            onClick={() => {
+              relationFilter.value = selected === kind ? null : { boardId: board.id, kind };
+            }}
+          >
+            <span class="relation-swatch" aria-hidden="true" />
+            {kind} <span class="relation-count">{list.filter((edge) => relationKind(edge) === kind).length}</span>
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+/** The attached agent's name; a session you started that no agent has joined yet names no one. */
+function agentName(): string {
+  const label = activeSession.value?.label;
+  return label && label !== HUMAN_STARTED_SESSION_LABEL ? label : 'the agent';
+}
 
-const DIRECTED_TYPES = new Set<CanvasEdge['type']>(['depends-on', 'flow']);
+/** The hovered link pill's hint, drawn at screen level by `EdgeHint` (the edge layer is SVG in world space). */
+const edgeHint = signal<{ x: number; y: number; text: string; edgeId: string; view: unknown } | null>(null);
+
+function clock(iso: string | undefined): string {
+  if (!iso) return '';
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime())
+    ? ''
+    : ` · ${date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}`;
+}
+
+function who(actor: NonNullable<CanvasEdge['changedBy']>): string {
+  return actor.actor === 'agent' ? writerName(actor) : 'you';
+}
+
+/**
+ * Who drew the link and when (docs/design/LinkAuthorship.dc.html): "Drawn by
+ * Codex · 14:06", or, once someone else changed it, "You relabelled it · 14:20
+ * (drawn by Codex · 14:06)". A folded "not seen" state joins it.
+ */
+function linkHint(edge: CanvasEdge, notSeen: boolean): string | null {
+  // A link from before authorship was recorded names no one: "you" could be false.
+  if (edge.changedBy?.actor !== 'agent' && edge.changedBy?.actor !== 'human') return null;
+  const by = who(edge.changedBy);
+  const takenOver = !!edge.createdBy && who(edge.createdBy) !== by;
+  const lead = takenOver
+    ? `${by === 'you' ? 'You' : by} relabelled it${clock(edge.changedAt)} (drawn by ${edge.createdBy ? who(edge.createdBy) : ''}${clock(edge.createdAt)})`
+    : `${by === 'you' ? 'You drew it' : `Drawn by ${by}`}${clock(edge.createdAt ?? edge.changedAt)}`;
+  return notSeen ? `${lead} · not seen by ${agentName()} yet` : lead;
+}
+
+/** The link pill's hint, outside the zoomed canvas so it keeps screen size and is never clipped. */
+export function EdgeHint() {
+  const hint = edgeHint.value;
+  // The pill can vanish or move under a resting pointer (the link removed, the
+  // view panned or zoomed) without a pointerleave: the hint goes with it.
+  if (!hint || hint.view !== viewport.value || !edges.value.has(hint.edgeId)) return null;
+  return (
+    <span
+      class="toolbar-tooltip edge-hint"
+      role="tooltip"
+      data-testid="edge-hint"
+      style={{ left: `${hint.x}px`, top: `${hint.y}px` }}
+    >
+      <span class="toolbar-tooltip-label">{hint.text}</span>
+    </span>
+  );
+}
+
+// Connection-change glyphs (docs/design/LinksOptions.dc.html, option C), 24-unit paths.
+const LINK_MARK_EYE_OFF =
+  'M3 3l18 18M10.6 6.1A10 10 0 0 1 12 6c6.5 0 10 6 10 6a17 17 0 0 1-3 3.6M6.6 6.6C3.8 8.3 2 12 2 12s3.5 6 10 6a9.6 9.6 0 0 0 4.4-1';
 
 /**
  * Edges are drawn in world space, so a 1.5px stroke renders as 0.4 screen px at
@@ -37,6 +150,8 @@ function dashArray(edge: CanvasEdge, scale: number): string | undefined {
   const dashed = `${8 * scale} ${4 * scale}`;
   if (edge.style === 'dashed') return dashed;
   if (edge.style === 'dotted') return `${3 * scale} ${3 * scale}`;
+  if (!edge.style && relationDefinition(edge, activeBoard()?.relationVocabulary).kind === 'related')
+    return `${2 * scale} ${5 * scale}`;
   if (edge.type === 'references' && !edge.style) return dashed;
   return undefined;
 }
@@ -128,17 +243,24 @@ interface EdgePathProps {
   edge: CanvasEdge;
   fromNode: CanvasNodeState;
   toNode: CanvasNodeState;
+  start: Anchor;
+  end: Anchor;
   focused: boolean; // connected to the active node
   dimmed: boolean; // active node exists but this edge is NOT connected
   selected: boolean; // click-selected — Delete removes it
   scale: number; // inverse-viewport compensation, see edgeChromeScale()
-  onContextMenu?: (e: MouseEvent, edgeId: string) => void;
+  part: EdgeLayerPart;
 }
 
-function EdgePath({ edge, fromNode, toNode, focused, dimmed, selected, scale, onContextMenu }: EdgePathProps) {
-  const start = computeAnchor(fromNode, toNode);
-  const end = computeAnchor(toNode, fromNode);
+/**
+ * Lines draw below group frames, so a link never covers a group's header; pills
+ * draw in their own layer above the frames, so a link inside a group keeps a
+ * label (LinkAuthorship.dc.html). Transparent pill hits stay below ports without
+ * moving the painted label below the frame's wash.
+ */
+export type EdgeLayerPart = 'lines' | 'pills' | 'pill-hits';
 
+function EdgePath({ edge, fromNode, toNode, start, end, focused, dimmed, selected, scale, part }: EdgePathProps) {
   const dx = end.x - start.x;
   const dy = end.y - start.y;
   const dist = Math.sqrt(dx * dx + dy * dy);
@@ -148,66 +270,180 @@ function EdgePath({ edge, fromNode, toNode, focused, dimmed, selected, scale, on
   const cp2 = sideControlPoint(end, curvature);
 
   const d = `M ${start.x} ${start.y} C ${cp1.x} ${cp1.y}, ${cp2.x} ${cp2.y}, ${end.x} ${end.y}`;
-  const color = EDGE_COLORS[edge.type];
-  const directed = DIRECTED_TYPES.has(edge.type);
+  const definition = relationDefinition(edge, activeBoard()?.relationVocabulary);
+  const color = `var(--c-rel-${definition.ink})`;
+  const directed = definition.directed;
   const dash = dashArray(edge, scale);
 
-  // Labels keep a constant screen size only while nodes are still readable.
-  // The uncapped chrome compensation made "brief" dwarf its own nodes at
-  // overview zoom — cap label chrome like node chrome (2.2), and drop labels
-  // entirely once the board is slivers (chrome scale > 3.4 ≈ zoom < 30%).
+  // Labels keep a constant screen size only while nodes are still readable —
+  // label chrome caps like node chrome (2.2). Below 35% zoom the label goes and
+  // only the link's marks stay (LinkAuthorship.dc.html).
   const labelScale = Math.min(scale, 2.2);
-  const mid =
-    edge.label && scale <= 3.4 ? bezierMidpoint(start.x, start.y, cp1.x, cp1.y, cp2.x, cp2.y, end.x, end.y) : null;
+  const zoom = viewport.value.scale;
+  const marks = linkMarks(edge);
+  // Reasons belong in the hint/inspector, not a long pill covering both endpoints.
+  const label = edge.label ?? edge.kind;
+  const showLabel = !!label && zoom >= 0.35;
+  // Pill layout in label units (× labelScale): the label, then a hairline and
+  // "not seen by …", which keeps only its glyph on a short line or below 60% zoom.
+  const pad = showLabel ? 9 : 5;
+  const labelWidth = showLabel ? (label?.length ?? 0) * 7 : 0;
+  const notSeenText = `not seen by ${agentName()}`;
+  const wordedNotSeenWidth = 12 + notSeenText.length * 6.2 + 4;
+  const fullWidth = pad * 2 + labelWidth + (marks.notSeen ? (labelWidth ? 12 : 0) + wordedNotSeenWidth : 0);
+  // A short line: the full pill plus some line on either side would not fit.
+  const notSeenWords = marks.notSeen && zoom >= 0.6 && dist >= (fullWidth + 60) * labelScale;
+  const notSeenWidth = marks.notSeen ? (labelWidth ? 12 : 0) + (notSeenWords ? wordedNotSeenWidth : 12) : 0;
+  const pillWidth = pad * 2 + labelWidth + notSeenWidth;
+  const labelX = -pillWidth / 2 + pad;
+  const notSeenX = labelX + labelWidth + (labelWidth ? 12 : 0);
+  const hasPill = showLabel || marks.notSeen;
+  const mid = hasPill ? bezierMidpoint(start.x, start.y, cp1.x, cp1.y, cp2.x, cp2.y, end.x, end.y) : null;
 
   const pathId = `edge-path-${edge.id}`;
+  const select = (e: MouseEvent) => {
+    // The viewport's background click clears the selection — a click
+    // that LANDED on an edge must not immediately undo itself.
+    e.stopPropagation();
+    selectedEdgeId.value = edge.id;
+  };
+  const showHint = (anchor: Element, point?: { x: number; y: number }) => {
+    const text = [
+      `${String(fromNode.data.title ?? fromNode.id)} → ${String(toNode.data.title ?? toNode.id)}`,
+      relationText(edge),
+      linkHint(edge, marks.notSeen),
+    ]
+      .filter(Boolean)
+      .join('\n');
+    const rect = anchor.getBoundingClientRect();
+    edgeHint.value = {
+      x: point?.x ?? rect.left + rect.width / 2,
+      y: (point?.y ?? rect.bottom) + 8,
+      text,
+      edgeId: edge.id,
+      view: viewport.value,
+    };
+  };
+  const hideHint = () => {
+    edgeHint.value = null;
+  };
+
+  if (part === 'pill-hits') {
+    if (!mid) return null;
+    return (
+      <rect
+        class="edge-pill-hit"
+        data-testid="edge-pill-hit"
+        data-edge-id={edge.id}
+        x={mid.x - (pillWidth / 2) * labelScale}
+        y={mid.y - 10 * labelScale}
+        width={pillWidth * labelScale}
+        height={20 * labelScale}
+        rx={10 * labelScale}
+        fill="transparent"
+        onClick={select}
+        onPointerEnter={(e) => showHint(e.currentTarget)}
+        onPointerLeave={hideHint}
+      />
+    );
+  }
+
+  if (part === 'pills') {
+    if (!mid) return null;
+    return (
+      <g
+        transform={`translate(${mid.x}, ${mid.y})`}
+        class="edge-pill"
+        data-testid="edge-pill"
+        opacity={dimmed && !selected ? 0.35 : 1}
+      >
+        <rect
+          class="edge-label-bg"
+          x={(-pillWidth / 2) * labelScale}
+          y={-10 * labelScale}
+          width={pillWidth * labelScale}
+          height={20 * labelScale}
+          rx={10 * labelScale}
+        />
+        {showLabel && (
+          <text
+            class="edge-label"
+            x={(labelX + labelWidth / 2) * labelScale}
+            text-anchor="middle"
+            dominant-baseline="central"
+            fill={color}
+          >
+            {label}
+          </text>
+        )}
+        {marks.notSeen && (
+          <g class="edge-link-mark is-not-seen" data-testid="edge-link-mark">
+            {labelWidth > 0 && (
+              <line
+                x1={(notSeenX - 6) * labelScale}
+                x2={(notSeenX - 6) * labelScale}
+                y1={-6 * labelScale}
+                y2={6 * labelScale}
+                stroke="var(--c-line)"
+                stroke-width={labelScale}
+              />
+            )}
+            <path
+              transform={`translate(${notSeenX * labelScale}, ${-5 * labelScale}) scale(${(10 / 24) * labelScale})`}
+              d={LINK_MARK_EYE_OFF}
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            />
+            {notSeenWords && (
+              <text
+                class="edge-label"
+                x={(notSeenX + 14) * labelScale}
+                text-anchor="start"
+                dominant-baseline="central"
+                fill="currentColor"
+              >
+                {notSeenText}
+              </text>
+            )}
+          </g>
+        )}
+      </g>
+    );
+  }
 
   return (
     <g>
       {/* Invisible wide hitbox — the ONE interactive part of the edge layer
           (the svg itself is pointer-events:none): click selects the edge
-          (Delete then removes it), double-click opens the edge menu. */}
+          (Delete then removes it); usePanZoom owns right-click versus drag. */}
       <path
+        data-edge-id={edge.id}
         d={d}
         fill="none"
         stroke="transparent"
         stroke-width={12 * scale}
         style={{ cursor: 'pointer', pointerEvents: 'stroke' }}
-        onClick={(e) => {
-          // The viewport's background click clears the selection — a click
-          // that LANDED on an edge must not immediately undo itself.
-          e.stopPropagation();
-          selectedEdgeId.value = edge.id;
-        }}
-        onDblClick={onContextMenu ? (e) => onContextMenu(e as unknown as MouseEvent, edge.id) : undefined}
+        onClick={select}
+        onPointerEnter={(e) => showHint(e.currentTarget, { x: e.clientX, y: e.clientY })}
+        onPointerLeave={hideHint}
       />
 
-      {/* Glow layer for focused or selected edges */}
-      {(focused || selected) && (
-        <path
-          d={d}
-          fill="none"
-          stroke={color}
-          stroke-width={6 * scale}
-          stroke-dasharray={dash}
-          opacity={selected ? 0.3 : 0.15}
-          style={{ filter: 'blur(3px)' }}
-        />
-      )}
-
       {/* Visible edge — the `edge-arrow` marker uses the default
           markerUnits="strokeWidth", so the arrowhead scales with this. */}
       <path
         id={pathId}
         d={d}
-        class={selected ? 'edge-selected' : undefined}
+        class={selected ? 'edge-line edge-selected' : 'edge-line'}
         fill="none"
         stroke={color}
         stroke-width={(selected ? 3 : focused ? 2.5 : 1.5) * scale}
         stroke-dasharray={dash}
         marker-end={directed ? 'url(#edge-arrow)' : undefined}
         opacity={selected ? 1 : dimmed ? 0.2 : focused ? 1 : 0.85}
-        style={{ transition: 'opacity 0.2s, stroke-width 0.2s' }}
+        style={{ color }}
       />
 
       {/* Animated pulse dot */}
@@ -218,23 +454,6 @@ function EdgePath({ edge, fromNode, toNode, focused, dimmed, selected, scale, on
           </animateMotion>
         </circle>
       )}
-
-      {/* Label at midpoint */}
-      {mid && edge.label && (
-        <g transform={`translate(${mid.x}, ${mid.y})`}>
-          <rect
-            class="edge-label-bg"
-            x={-(edge.label.length * 3.5 + 8) * labelScale}
-            y={-10 * labelScale}
-            width={(edge.label.length * 7 + 16) * labelScale}
-            height={20 * labelScale}
-            rx={4 * labelScale}
-          />
-          <text class="edge-label" text-anchor="middle" dominant-baseline="central" fill="var(--c-text)">
-            {edge.label}
-          </text>
-        </g>
-      )}
     </g>
   );
 }
@@ -243,20 +462,52 @@ function EdgePath({ edge, fromNode, toNode, focused, dimmed, selected, scale, on
 interface EdgeLayerProps {
   nodes: Signal<Map<string, CanvasNodeState>>;
   edges: Signal<Map<string, CanvasEdge>>;
-  onEdgeContextMenu?: (e: MouseEvent, edgeId: string) => void;
+  part: EdgeLayerPart;
 }
 
-export function EdgeLayer({ nodes, edges, onEdgeContextMenu }: EdgeLayerProps) {
+export function EdgeLayer({ nodes, edges, part }: EdgeLayerProps) {
   const nodeMap = nodes.value;
   const edgeList = Array.from(edges.value.values());
-  const focusId = activeNodeId.value;
+  const focusId = relationFocus.value;
   const hasFocus = focusId !== null;
   const searchSet = searchHighlightIds.value;
   const hasSearch = searchSet !== null;
   const scale = edgeChromeScale(viewport.value.scale);
 
+  // Allocate a port to every incident link, including parallel and reverse links.
+  const ports = new Map<string, { start: Anchor; end: Anchor }>();
+  const sides = new Map<string, Array<{ anchor: Anchor; node: CanvasNodeState; order: number; id: string }>>();
+  for (const edge of edgeList) {
+    if (edge.toBoardId) continue;
+    const from = visibleNodeFor(edge.from);
+    const to = visibleNodeFor(edge.to);
+    if (!from || !to || from.id === to.id) continue;
+    const start = computeAnchor(from, to);
+    const end = computeAnchor(to, from);
+    ports.set(edge.id, { start, end });
+    for (const [anchor, node, other] of [
+      [start, from, to],
+      [end, to, from],
+    ] as const) {
+      const key = `${node.id}:${anchor.side}`;
+      const vertical = anchor.side === 'left' || anchor.side === 'right';
+      const group = sides.get(key) ?? [];
+      group.push({ anchor, node, order: vertical ? other.position.y : other.position.x, id: edge.id });
+      sides.set(key, group);
+    }
+  }
+  for (const group of sides.values()) {
+    if (group.length < 2) continue;
+    group.sort((a, b) => a.order - b.order || a.id.localeCompare(b.id));
+    group.forEach(({ anchor, node }, index) => {
+      const fraction = (index + 1) / (group.length + 1);
+      if (anchor.side === 'left' || anchor.side === 'right') anchor.y = node.position.y + node.size.height * fraction;
+      else anchor.x = node.position.x + node.size.width * fraction;
+    });
+  }
+
   // A drag-to-connect preview must draw on a board with no edges yet.
-  if (edgeList.length === 0 && !draggingEdge.value) return null;
+  if (edgeList.length === 0 && (part !== 'lines' || !draggingEdge.value)) return null;
 
   const PAD = 96;
   const worldNodes = Array.from(nodeMap.values());
@@ -270,8 +521,9 @@ export function EdgeLayer({ nodes, edges, onEdgeContextMenu }: EdgeLayerProps) {
 
   return (
     <svg
-      aria-label="Canvas connections"
-      role="img"
+      aria-label={part === 'lines' ? 'Canvas connections' : undefined}
+      aria-hidden={part !== 'lines' ? 'true' : undefined}
+      role={part === 'lines' ? 'img' : undefined}
       viewBox={`${minX} ${minY} ${width} ${height}`}
       width={width}
       height={height}
@@ -279,13 +531,17 @@ export function EdgeLayer({ nodes, edges, onEdgeContextMenu }: EdgeLayerProps) {
         position: 'absolute',
         top: `${minY}px`,
         left: `${minX}px`,
+        // Painting stays unchanged. Hit priority is card > port > pill > group
+        // interior > line, including raised and nested group frames.
+        zIndex:
+          part === 'pills' ? 1 : part === 'pill-hits' ? 'calc(var(--node-port-z, -1) - 1)' : 'var(--edge-line-z, -5)',
         pointerEvents: 'none',
         overflow: 'visible',
         '--edge-chrome-scale': scale.toFixed(3),
         '--edge-label-scale': Math.min(scale, 2.2).toFixed(3),
       }}
     >
-      <title>Canvas connections</title>
+      {part === 'lines' && <title>Canvas connections</title>}
       <defs>
         {/* userSpaceOnUse decouples the arrowhead from the UNCAPPED stroke
             compensation: the line stays a visible hairline at any zoom, but
@@ -301,32 +557,39 @@ export function EdgeLayer({ nodes, edges, onEdgeContextMenu }: EdgeLayerProps) {
           markerHeight={8 * Math.min(scale, 2.2)}
           orient="auto-start-reverse"
         >
-          <path d="M 0 1 L 10 5 L 0 9 z" fill="currentColor" opacity="0.75" />
+          <path d="M 0 1 L 10 5 L 0 9 z" fill="context-stroke" opacity="0.75" />
         </marker>
       </defs>
       {edgeList.map((edge) => {
+        // Remote endpoints are navigable links, never a same-ID card on this board.
+        if (edge.toBoardId) return null;
         // An endpoint hidden behind a collapsed group's chip is drawn to the chip.
         const fromNode = visibleNodeFor(edge.from);
         const toNode = visibleNodeFor(edge.to);
-        if (!fromNode || !toNode || fromNode.id === toNode.id) return null;
+        const anchors = ports.get(edge.id);
+        if (!fromNode || !toNode || !anchors) return null;
         const isConnected = hasFocus && (edge.from === focusId || edge.to === focusId);
         const searchDimmed = hasSearch && !(searchSet.has(edge.from) || searchSet.has(edge.to));
+        const highlight = relationHighlight.value;
         return (
           <EdgePath
             key={edge.id}
             edge={edge}
             fromNode={fromNode}
             toNode={toNode}
+            start={anchors.start}
+            end={anchors.end}
             focused={isConnected}
-            dimmed={(hasFocus && !isConnected) || searchDimmed}
+            dimmed={(highlight !== null && !highlight.links.has(edge.id)) || searchDimmed}
             selected={selectedEdgeId.value === edge.id}
             scale={scale}
-            onContextMenu={onEdgeContextMenu}
+            part={part}
           />
         );
       })}
       {/* Live preview edge while drag-connecting */}
-      {draggingEdge.value &&
+      {part === 'lines' &&
+        draggingEdge.value &&
         (() => {
           const de = draggingEdge.value;
           // Route the preview EXACTLY like the committed edge will route

package/src/client/canvas/EmptyState.tsx

@@ -7,14 +7,15 @@ import { modChord } from '../utils/platform';
 import { canvasAreaCenter } from './canvas-area';
 import { importFiles } from './import-files';
 import { promptedCreate } from './ToolRail';
+import { agentSessionsEnabled } from '../state/workspace-settings';
 
 /**
  * Empty board (rail-chrome-v2 phase 7, design item 11): centered onboarding
- * with the ghost mark, a 2×2 grid of starter actions, and the shortcut hint.
- * Every action is real: New note creates the same blank note as M, Drop files
+ * with direct starter actions and a separate way to start with your agent.
+ * Every action is real: Start a note creates the same blank note as M, Drop files
  * opens a picker onto the viewport's import path, Paste a link asks for a URL,
- * Start agent session attaches a browser-keyed session. Tokens only, so it
- * reads the same in dark and light.
+ * and the optional Start agent session attaches a browser-keyed session.
+ * Agent guidance stays visible independently of the session beta.
  */
 export function EmptyState({ onOpenPalette }: { onOpenPalette: () => void }) {
   const fileInput = useRef<HTMLInputElement>(null);
@@ -33,16 +34,8 @@ export function EmptyState({ onOpenPalette }: { onOpenPalette: () => void }) {
         <rect x="8" y="8" width="48" height="48" rx="7" />
         <rect x="20" y="20" width="24" height="24" rx="4" stroke-dasharray="4 4" />
       </svg>
-      <div>
-        <div class="empty-state-title">Nothing on this board yet</div>
-        <div class="empty-state-sub">Drop files anywhere, paste a link, or start from a note.</div>
-      </div>
+      <div class="empty-state-title">What would you like to work on?</div>
       <div class="empty-state-grid">
-        <button type="button" class="empty-state-action" onClick={newNote}>
-          <IconNodeMarkdown size={16} class="tone-accent" />
-          <span class="empty-state-action-label">New markdown note</span>
-          <kbd>M</kbd>
-        </button>
         <button type="button" class="empty-state-action" onClick={() => fileInput.current?.click()}>
           <svg
             width="16"
@@ -58,19 +51,41 @@ export function EmptyState({ onOpenPalette }: { onOpenPalette: () => void }) {
             <path d="M8 10 V2 M8 2 L5 5 M8 2 L11 5" />
             <path d="M2 10 V13 H14 V10" />
           </svg>
-          <span class="empty-state-action-label">Drop files</span>
+          <span class="empty-state-action-label">
+            Drop files here
+            <span class="empty-state-action-description">Bring in the material you want to work with.</span>
+          </span>
           <span class="empty-state-action-hint">or pick</span>
         </button>
         <button type="button" class="empty-state-action" onClick={() => promptedCreate('webpage')}>
           <IconNodeWebpage size={16} class="tone-ok" />
-          <span class="empty-state-action-label">Paste a link</span>
+          <span class="empty-state-action-label">
+            Paste a link
+            <span class="empty-state-action-description">Add a source, reference, or inspiration.</span>
+          </span>
           <kbd>{modChord('V')}</kbd>
         </button>
-        <button type="button" class="empty-state-action is-agent" onClick={() => void startSession()}>
-          <IconSteer size={16} class="tone-purple" />
-          <span class="empty-state-action-label">Start agent session</span>
+        <button type="button" class="empty-state-action" onClick={newNote}>
+          <IconNodeMarkdown size={16} class="tone-accent" />
+          <span class="empty-state-action-label">
+            Start a note
+            <span class="empty-state-action-description">
+              Write down an idea, then ask your agent to help you develop it.
+            </span>
+          </span>
+          <kbd>M</kbd>
         </button>
       </div>
+      <div class="empty-state-agent">
+        <div class="empty-state-agent-title">Or start with your agent</div>
+        <div class="empty-state-sub">Give your agent a task and ask it to work on this board.</div>
+        {agentSessionsEnabled.value && (
+          <button type="button" class="empty-state-action is-agent" onClick={() => void startSession()}>
+            <IconSteer size={16} class="tone-purple" />
+            <span class="empty-state-action-label">Start agent session</span>
+          </button>
+        )}
+      </div>
       <button type="button" class="empty-state-hint" onClick={onOpenPalette}>
         ? shortcuts · {modChord('K')} palette
       </button>