Module pane_command 

Canonical keyboard command model and focus-graph semantics for panes (bd-21pbi.1).

This module defines a host-agnostic keyboard interaction contract for the pane workspace: a normative command vocabulary (PaneCommand), a deterministic focus graph over the split tree (in-order traversal and spatial/directional navigation with explicit tie-breaks), a pure command resolver (resolve) that maps each command to a focus change, a list of structural PaneOperations, or a transient view-state change, plus explicit repeat/acceleration (PaneCommandAcceleration) and keymap precedence (PaneKeymapPrecedence) policies.

Why a command layer? Pointer drag-resize already has a first-class semantic pipeline (PaneSemanticInputEvent -> PaneDragResizeMachine -> PaneTree::operations_for_transition). Keyboard interaction needs an equivalent, but its vocabulary is broader than resize (focus navigation, split/close/move/swap, maximize/restore) and must NOT be expressed as host-specific key events. PaneCommand is that vocabulary: terminal (bd-21pbi.2) and web (bd-21pbi.3) hosts translate raw key events into PaneCommands, and resolve turns each command into the same outcome on every host. This is the executable form of the normative spec in docs/spec/pane-keyboard-interaction.md.

Determinism guarantee: for a fixed split-tree topology, layout, and focus context, resolve is a pure function. Equivalent command streams therefore yield identical pane state (topology hash + active pane) across hosts — the cross-host parity property the pane validation epic requires.

Structs

PaneAccessibilityPreferences

Host-agnostic accessibility preferences for pane interaction (bd-21pbi.5).

PaneAnnouncement

A concise, host-agnostic accessibility announcement for a pane state change. The web host renders text into an aria-live region; the terminal host surfaces it via a status line / log hook.

PaneAnnouncer

Coalescing announcer that keeps host live regions / status lines bounded and non-spammy: the latest offered announcement wins (so a burst of resize/repeat announcements collapses to one), and consecutive identical text is suppressed. Hosts call PaneAnnouncer::take once per render / live-region update.

PaneCommandAcceleration

Repeat-key acceleration policy for resize stepping. Explicit and testable: the first accelerate_after_repeats presses use base_units; sustained repeats escalate to accelerated_units.

PaneCommandResolution

The full result of resolving one PaneCommand: the effect plus the resulting focus context the host should adopt.

PaneFocusContext

Host-owned focus context consumed by resolve. This is plain input data, not competing persistent state: hosts store the active/maximized pane wherever they like (e.g. WorkspaceSnapshot::active_pane_id) and pass a snapshot here.

Enums

PaneAnnouncementCategory

Category of a pane state-change announcement (for host channel routing and coalescing).

PaneCardinalDirection

A cardinal direction for spatial focus and pane movement.

PaneCommand

The canonical, host-agnostic pane keyboard command vocabulary.

PaneCommandEffect

The concrete effect a resolved command produces. Focus changes and maximize state are transient (no tree mutation); structural changes are a list of PaneOperations the host applies via PaneTree::apply_operation.

PaneCommandNoopReason

Why a command resolved to a no-op.

PaneFocusOrdinal

Cyclic ordinal over the deterministic focus order.

PaneKeymapOwner

Who owns a key given its bindings and the active precedence policy.

PaneKeymapPrecedence

Conflict precedence between application-level keymaps and the pane manager.

Functions

announce_command

Generate a concise accessibility announcement for a resolved command.

focus_cyclic

The cyclic neighbour of active in focus_order. Returns None when active is absent from the order or the tree has fewer than two leaves.

focus_directional

The nearest leaf to active in a cardinal direction, using solved geometry.

focus_edge

The extreme leaf in a cardinal direction (jump to edge). Returns the active leaf’s own id when it is already the extreme, so callers can treat that as a no-op.

focus_order

Deterministic focus order: leaves in topological depth-first order (first child before second at every split). This is the canonical “tab order” and is independent of solved geometry, so it is stable for any layout area.

resolve

Resolve a single PaneCommand against the current tree, solved layout, and focus context. Pure and deterministic: identical inputs always yield an identical PaneCommandResolution, which is what makes equivalent command streams produce identical pane state across hosts.