Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

10.0 KB
Raw Blame
/**
 * "Focus the node over there" — which node a directional move (⌘←/→/↑/↓) lands on, and which
 * node the gesture starts from when nothing is focused yet.
 *
 * The gesture is the one terminal multiplexers give you for free (Ghostty's `goto_split`, tmux's
 * `select-pane -L`, i3's `focus left`), but those all navigate a TREE OF SPLITS where "the pane to
 * the left" is a structural fact. On a canvas there is no tree: nodes are free-form rectangles the
 * user dragged, so the answer has to be inferred from geometry.
 *
 * Nearest-by-distance is the obvious inference and the wrong one — the closest node in the raw
 * Euclidean sense is very often the one diagonally up-and-left, so ⌘→ lands somewhere the user
 * never pointed. Candidates are therefore ranked in TWO TIERS:
 *
 *   Tier 0 — the candidate's perpendicular span OVERLAPS the origin's. These are the nodes a user
 *            would call "in the same row" (for a horizontal move) or "the same column" (vertical),
 *            and one of them is the answer whenever one exists, however far away it sits. Ordered
 *            by distance along the axis, so the immediate neighbour beats the one behind it.
 *   Tier 1 — no overlap, i.e. reachable only diagonally. Ordered by axial distance plus a
 *            {@link PERPENDICULAR_WEIGHT} penalty on the sideways offset, which is what stops a
 *            far-off-axis node beating a nearly-aligned one. This tier is why a node sitting alone
 *            on its row is not a dead end in every direction — a dead end there reads as the
 *            feature being broken, not as a deliberate boundary.
 *
 * Ties break on node id, so one canvas always answers the same way and the tests can state it.
 *
 * There is deliberately NO wrap-around: the last node in a direction is the end of the line, which
 * is what `goto_split` does and what keeps repeated presses from cycling forever.
 *
 * Every rect comes from `nodeFocus`'s `nodeFitRect`/`absolutePosition`, never from `node.position`
 * directly, and that is load-bearing rather than tidy: a GROUPED node's own `position` is relative
 * to its frame, so comparing one against a top-level node's compares two different coordinate
 * spaces. A terminal sitting at (24, 60) inside a frame parked at (4000, 0) would otherwise look
 * like the leftmost node on the canvas, and ⌘← from anywhere would fly to it.
 */
import { absolutePosition, nodeFitRect, type FocusableNode } from './nodeFocus'

export type FocusDirection = 'left' | 'right' | 'up' | 'down'

/** xyflow wraps every node in an element with this class and a `data-id` holding the node id —
 *  which is how the gesture finds the node the KEYBOARD is in, not merely the selected one.
 *  Pinned against the installed dist by the test beside this file, the same way keyContext.ts
 *  pins xterm's helper-textarea class: an upgrade that renames it must fail loudly rather than
 *  quietly leave every move starting from the wrong node. Note handles carry a `data-id` too
 *  (a composite), so the class has to be matched FIRST and the attribute read off that element. */
export const FLOW_NODE_CLASS = 'react-flow__node'

/**
 * A focus destination: everything `nodeFocus` needs to place a node in absolute space, plus the
 * node KIND, which is the one thing that decides what may be focused at all. Structural rather
 * than `CanvasNode` so the unit tests need no xyflow types and no DOM.
 */
export interface DirectionalNode extends FocusableNode {
  /** Group FRAMES are containers, not destinations — see {@link isFocusTarget}. */
  type?: string
}

/** Cost of a sideways offset relative to a step along the direction, for the diagonal tier. At 2,
 *  a node twice as far sideways as it is forward loses to one straight ahead. */
const PERPENDICULAR_WEIGHT = 2

/** Centers within this many world px of each other along the axis are not "beyond" each other, so
 *  two nodes the grid snapped into the same column never answer each other's ⌘→. */
const AXIS_EPSILON = 1

/**
 * The node a move in `dir` from `fromId` should focus, or null when `fromId` is the last node that
 * way (or is not on this canvas).
 */
export function nextNodeInDirection(
  nodes: readonly DirectionalNode[],
  fromId: string,
  dir: FocusDirection
): string | null {
  const origin = nodes.find((n) => n.id === fromId)
  if (!origin) return null
  const o = boundsOf(origin, nodes)
  const horizontal = dir === 'left' || dir === 'right'
  const forward = dir === 'right' || dir === 'down' ? 1 : -1

  let best: Score | null = null
  for (const node of nodes) {
    if (node.id === fromId || !isFocusTarget(node)) continue
    const r = boundsOf(node, nodes)
    // A non-finite center poisons every comparison below rather than merely losing them: NaN
    // fails `<` in both directions, so the FIRST such candidate becomes `best` and then nothing
    // valid can displace it. Positions arrive from a persisted workspace file, where a null
    // coordinate is one arithmetic step from NaN, so this is cheaper than trusting the input.
    if (!Number.isFinite(r.cx) || !Number.isFinite(r.cy)) continue
    const advance = forward * ((horizontal ? r.cx : r.cy) - (horizontal ? o.cx : o.cy))
    if (!(advance > AXIS_EPSILON)) continue
    const perp = Math.abs((horizontal ? r.cy : r.cx) - (horizontal ? o.cy : o.cx))
    const overlaps = horizontal
      ? r.top < o.bottom && o.top < r.bottom
      : r.left < o.right && o.left < r.right
    const score: Score = {
      tier: overlaps ? 0 : 1,
      cost: overlaps ? advance : advance + PERPENDICULAR_WEIGHT * perp,
      perp,
      id: node.id
    }
    if (!best || better(score, best)) best = score
  }
  return best?.id ?? null
}

/**
 * The focus target nearest `point`, by center distance — the SEED for a canvas where nothing is
 * focused or selected yet. Without it the first ⌘→ on a freshly opened project would have no
 * origin and do nothing, which is indistinguishable from an unbound chord.
 */
export function nodeNearestPoint(
  nodes: readonly DirectionalNode[],
  point: { x: number; y: number }
): string | null {
  let bestId: string | null = null
  let bestDist = Infinity
  for (const node of nodes) {
    if (!isFocusTarget(node)) continue
    const r = boundsOf(node, nodes)
    const dist = (r.cx - point.x) ** 2 + (r.cy - point.y) ** 2
    if (dist < bestDist || (dist === bestDist && bestId !== null && node.id < bestId)) {
      bestDist = dist
      bestId = node.id
    }
  }
  return bestId
}

/**
 * A group frame is the one node kind that must never be a focus destination: it is a container
 * drawn AROUND the nodes you actually want, so its rect overlaps all of them and it would win
 * every direction from inside itself.
 */
export function isFocusTarget(node: DirectionalNode): boolean {
  return node.type !== 'group'
}

interface Bounds {
  left: number
  top: number
  right: number
  bottom: number
  cx: number
  cy: number
}

/** The node's absolute bounds. `nodeFitRect` answers null when neither a measurement nor a
 *  persisted size is known (a node added this tick, before layout); such a node is treated as a
 *  POINT at its absolute position, so it is still reachable but can never overlap anyone's row —
 *  the honest answer for something with no size yet. */
function boundsOf(node: DirectionalNode, all: readonly DirectionalNode[]): Bounds {
  const rect = nodeFitRect(node, all) ?? { ...absolutePosition(node, all), width: 0, height: 0 }
  const { x, y, width, height } = rect
  return {
    left: x,
    top: y,
    right: x + width,
    bottom: y + height,
    cx: x + width / 2,
    cy: y + height / 2
  }
}

interface Score {
  tier: number
  cost: number
  perp: number
  id: string
}

const better = (a: Score, b: Score): boolean =>
  a.tier !== b.tier
    ? a.tier < b.tier
    : a.cost !== b.cost
      ? a.cost < b.cost
      : a.perp !== b.perp
        ? a.perp < b.perp
        : a.id < b.id

/** What a directional move should do: swap the focus-mode node, or travel the camera. */
export type DirectionalMove = { kind: 'swap-focus' | 'travel'; id: string }

export interface DirectionalMoveContext {
  /** Focus mode's node (`useFocusNode.focusedId`), or null on the plain canvas. */
  focusedId: string | null
  /** The node the KEYBOARD is in (the `.react-flow__node` ancestor of the active element). */
  keyboardId: string | null
  /** The single selected focus target, if any. */
  selectedId: string | null
  /** The view center in world coordinates, for seeding a canvas with no origin; null = unknown. */
  viewCenter: { x: number; y: number } | null
}

/**
 * The one decision behind ⌘←/→/↑/↓, in both places the chord can fire:
 *
 *  - **Focus mode** — one terminal fills the window and the flow pane is display:none, so there is
 *    no camera to move; the move SWAPS the focused node for its neighbour and the user stays in
 *    focus mode (before this, going from one focused terminal to the next was ⌘⇧F, ⌘→, ⌘⇧F). The
 *    origin is the focused node itself — the reparent detaches its root from the xyflow wrapper,
 *    so the keyboard origin reads as null there — and the candidates are TERMINALS only, the one
 *    kind focus mode can show (`focusTargetId`). A null at the edge is still a claimed chord.
 *  - **Canvas** — the origin is the node the keyboard is in, else the selected node, else (first
 *    press) the node nearest the view center is ADOPTED rather than moved from; the move TRAVELS.
 */
export function planDirectionalMove(
  nodes: readonly DirectionalNode[],
  dir: FocusDirection,
  ctx: DirectionalMoveContext
): DirectionalMove | null {
  if (ctx.focusedId) {
    const terminals = nodes.filter((n) => n.type === 'terminal')
    const next = nextNodeInDirection(terminals, ctx.focusedId, dir)
    return next ? { kind: 'swap-focus', id: next } : null
  }
  const from = ctx.keyboardId ?? ctx.selectedId
  if (!from) {
    const seed = ctx.viewCenter ? nodeNearestPoint(nodes, ctx.viewCenter) : null
    return seed ? { kind: 'travel', id: seed } : null
  }
  const next = nextNodeInDirection(nodes, from, dir)
  return next ? { kind: 'travel', id: next } : null
}