@yaag/tui 0.1.0

package/src/drill-state.ts

@@ -0,0 +1,163 @@
+/**
+ * The drill-in layer state machine (spec §1): tree → actions menu → transcript
+ * overlay, with `esc` backing out exactly one level.
+ *
+ * Pure and I/O-free. Every effect it can ask for is read-only — copy a path,
+ * open an editor, load a transcript, drop focus — so no gesture in this reducer
+ * can send to an Agent or stop a Run (ADR — a Peek observes, it never sends).
+ */
+import type { DrillAction, MenuAction, OverlayAction } from "./drill-keys.ts";
+import { moveMenuCursor, NODE_ACTIONS } from "./node-actions.ts";
+import { initialScroll, type Scroll, scrollBy } from "./overlay-scroll.ts";
+
+/** Which layer holds input focus. */
+export type DrillState =
+  | { readonly kind: "tree" }
+  | { readonly kind: "menu"; readonly path: string; readonly cursor: number }
+  | {
+      readonly kind: "transcript";
+      readonly path: string;
+      /** The layer `esc` returns to. */
+      readonly from: "tree" | "menu";
+      readonly scroll: Scroll;
+    };
+
+/** A read-only side effect the host performs after a transition. */
+export type DrillEffect =
+  | { readonly kind: "copySessionPath"; readonly path: string }
+  | { readonly kind: "openSystemPrompt"; readonly path: string }
+  | { readonly kind: "loadTranscript"; readonly path: string }
+  | { readonly kind: "dropFocus" };
+
+/** Everything a transition needs beyond the state: the selection and viewport. */
+export interface DrillContext {
+  /** The tree cursor's node path, absent when the tree has no selection. */
+  readonly selectedPath: string | undefined;
+  /** Content lines currently loaded for the overlay. */
+  readonly total: number;
+  /** Content rows the overlay draws. */
+  readonly rows: number;
+}
+
+/** One transition: the next state, plus the effect the host must perform. */
+export interface DrillTransition {
+  readonly state: DrillState;
+  readonly effect?: DrillEffect;
+}
+
+/** Any gesture the drill-in consumes, across its three layers. */
+export type AnyDrillAction = DrillAction | MenuAction | OverlayAction;
+
+/** The tree layer, with no menu and no overlay open. */
+export function emptyDrill(): DrillState {
+  return { kind: "tree" };
+}
+
+/**
+ * Applies one gesture to the drill state.
+ *
+ * A gesture that belongs to another layer returns the state unchanged and no
+ * effect, so a host may route the same byte through every layer safely.
+ */
+export function applyDrillAction(
+  state: DrillState,
+  action: AnyDrillAction,
+  context: DrillContext,
+): DrillTransition {
+  switch (state.kind) {
+    case "tree":
+      return fromTree(action, context);
+    case "menu":
+      return fromMenu(state, action);
+    case "transcript":
+      return fromTranscript(state, action, context);
+  }
+}
+
+function fromTree(action: AnyDrillAction, context: DrillContext): DrillTransition {
+  const tree: DrillState = { kind: "tree" };
+  if (action === "back") return { state: tree, effect: { kind: "dropFocus" } };
+  const path = context.selectedPath;
+  if (path === undefined) return { state: tree };
+  if (action === "openMenu") return { state: { kind: "menu", path, cursor: 0 } };
+  if (action === "openTranscript") return openTranscript(path, "tree");
+  return { state: tree };
+}
+
+function fromMenu(
+  state: { readonly kind: "menu"; readonly path: string; readonly cursor: number },
+  action: AnyDrillAction,
+): DrillTransition {
+  switch (action) {
+    case "menuUp":
+      return { state: { ...state, cursor: moveMenuCursor(state.cursor, -1) } };
+    case "menuDown":
+      return { state: { ...state, cursor: moveMenuCursor(state.cursor, 1) } };
+    case "cancel":
+      return { state: { kind: "tree" } };
+    case "confirm":
+      return confirmMenu(state);
+    default:
+      return { state };
+  }
+}
+
+function confirmMenu(state: {
+  readonly kind: "menu";
+  readonly path: string;
+  readonly cursor: number;
+}): DrillTransition {
+  switch (NODE_ACTIONS[state.cursor]?.action) {
+    case "viewTranscript":
+      return openTranscript(state.path, "menu");
+    case "copySessionPath":
+      return { state, effect: { kind: "copySessionPath", path: state.path } };
+    case "openSystemPrompt":
+      return { state, effect: { kind: "openSystemPrompt", path: state.path } };
+    default:
+      return { state };
+  }
+}
+
+function fromTranscript(
+  state: {
+    readonly kind: "transcript";
+    readonly path: string;
+    readonly from: "tree" | "menu";
+    readonly scroll: Scroll;
+  },
+  action: AnyDrillAction,
+  context: DrillContext,
+): DrillTransition {
+  const page = Math.max(1, Math.floor(context.rows));
+  switch (action) {
+    case "scrollUp":
+      return { state: { ...state, scroll: scroll(state, -1, context) } };
+    case "scrollDown":
+      return { state: { ...state, scroll: scroll(state, 1, context) } };
+    case "pageUp":
+      return { state: { ...state, scroll: scroll(state, -page, context) } };
+    case "pageDown":
+      return { state: { ...state, scroll: scroll(state, page, context) } };
+    case "copyPath":
+      return { state, effect: { kind: "copySessionPath", path: state.path } };
+    case "close":
+      return {
+        state:
+          state.from === "menu" ? { kind: "menu", path: state.path, cursor: 0 } : { kind: "tree" },
+      };
+    default:
+      return { state };
+  }
+}
+
+function scroll(state: { readonly scroll: Scroll }, delta: number, context: DrillContext): Scroll {
+  return scrollBy(state.scroll, delta, context.total, Math.max(1, Math.floor(context.rows)));
+}
+
+function openTranscript(path: string, from: "tree" | "menu"): DrillTransition {
+  return {
+    state: { kind: "transcript", path, from, scroll: initialScroll() },
+    effect: { kind: "loadTranscript", path },
+  };
+}

package/src/duration-text.ts

@@ -0,0 +1,12 @@
+/**
+ * Formats a duration the way the Run tree mockup writes it: `45s` below one
+ * minute, `2m14s` above it, with the seconds zero-padded. A negative or
+ * non-finite duration formats as `0s`.
+ */
+export function durationText(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "0s";
+  const seconds = Math.floor(ms / 1_000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`;
+}

package/src/index.ts

@@ -0,0 +1,126 @@
+export { costText, tokensText } from "./accounting-text.ts";
+export { activityText } from "./activity-text.ts";
+export { AGENT_ASK_LEDGER_MAX, type AskLedger, type AskRow } from "./ask-ledger.ts";
+export {
+  type CompactRenderOptions,
+  compactAgentLine,
+  renderCompact,
+} from "./compact-render.ts";
+export { DrillController, type DrillHost } from "./drill-controller.ts";
+export {
+  DRILL_KEY_TABLE,
+  type DrillAction,
+  MENU_KEY_TABLE,
+  type MenuAction,
+  OVERLAY_KEY_TABLE,
+  type OverlayAction,
+  routeDrillKey,
+  routeMenuKey,
+  routeOverlayKey,
+} from "./drill-keys.ts";
+export {
+  type AnyDrillAction,
+  applyDrillAction,
+  type DrillContext,
+  type DrillEffect,
+  type DrillState,
+  type DrillTransition,
+  emptyDrill,
+} from "./drill-state.ts";
+export { durationText } from "./duration-text.ts";
+export { type KeyBinding, type NamedKeybindings, routeKey } from "./key-router.ts";
+export {
+  moveMenuCursor,
+  NODE_ACTIONS,
+  type NodeAction,
+  type NodeActionRow,
+  renderActionsMenu,
+} from "./node-actions.ts";
+export { agentOfPath, type NodePathSegment, parseNodePath } from "./node-path-parse.ts";
+export { renderNodeTable } from "./node-table.ts";
+export { type FramedBoxOptions, renderFramedBox } from "./overlay-frame.ts";
+export {
+  initialScroll,
+  maxOffset,
+  resolveOffset,
+  type Scroll,
+  scrollBy,
+} from "./overlay-scroll.ts";
+export {
+  createRunTreeView,
+  type RunTreeView,
+  type RunTreeViewHost,
+  type RunTreeViewOptions,
+  type RunViewExit,
+  type RunViewSurface,
+} from "./run-tree-view.ts";
+export { type RunViewResult, resultText, STDERR_TAIL_LINES } from "./run-view-result.ts";
+export {
+  applyRunViewAction,
+  livePhase,
+  type RunPhase,
+  type RunViewAction,
+  type RunViewEffect,
+  type RunViewOutcome,
+  type RunViewTransition,
+} from "./run-view-state.ts";
+export { routeSessionKey, SESSION_KEY_TABLE, type SessionAction } from "./session-keys.ts";
+export {
+  extractSystemPrompt,
+  parseTranscript,
+  type TranscriptItem,
+} from "./session-transcript.ts";
+export { renderSnapshot, type SnapshotRenderOptions } from "./snapshot-render.ts";
+export {
+  moveStopCursor,
+  renderStopPrompt,
+  STOP_PROMPT_CHOICES,
+  type StopChoice,
+  type StopChoiceRow,
+  type StopPromptOptions,
+} from "./stop-prompt.ts";
+export { sanitizeTerminalLine, sanitizeTerminalText } from "./terminal-text.ts";
+export { type NodeTranscriptOptions, nodeTranscriptLines } from "./transcript-content.ts";
+export {
+  renderTranscriptOverlay,
+  type TranscriptOverlayOptions,
+} from "./transcript-overlay.ts";
+export {
+  NO_TRANSCRIPT_STUB,
+  renderTranscript,
+  type TranscriptViewOptions,
+  transcriptHeader,
+} from "./transcript-render.ts";
+export {
+  moveSelection,
+  nodeAt,
+  nodeChain,
+  parentOf,
+  resolveSelection,
+} from "./tree-cursor.ts";
+export {
+  emptyFold,
+  type FoldState,
+  isExpanded,
+  type VisibleRow,
+  visibleRows,
+} from "./tree-fold.ts";
+export { GLYPHS } from "./tree-glyphs.ts";
+export {
+  cliKeybindings,
+  routeTreeKey,
+  TREE_KEY_TABLE,
+  type TreeAction,
+  type TreeKeyBinding,
+} from "./tree-keys.ts";
+export { buildTree, type TreeModelOptions } from "./tree-model.ts";
+export { applyTreeAction, emptyView, type TreeView } from "./tree-navigation.ts";
+export { TreeNavigator, type TreeNavigatorOptions } from "./tree-navigator.ts";
+export type { TreeNode, TreeNodeKind, TreeNodeState } from "./tree-node.ts";
+export { renderTree, type TreeRenderOptions } from "./tree-render.ts";
+export { TreeState, type TreeUpdate } from "./tree-state.ts";
+export {
+  renderRunsWidget,
+  type WidgetRenderOptions,
+  type WidgetRun,
+} from "./widget-render.ts";

package/src/key-router.ts

@@ -0,0 +1,47 @@
+import type { Keybinding, KeyId } from "@earendil-works/pi-tui";
+import { matchesKey } from "@earendil-works/pi-tui";
+
+/**
+ * A named-binding matcher. pi's injected `KeybindingsManager` and pi-tui's
+ * `getKeybindings()` both satisfy it, so `packages/tui` needs no dependency on
+ * the pi coding agent.
+ */
+export interface NamedKeybindings {
+  matches(data: string, binding: string): boolean;
+}
+
+/** One row of a key table: a named binding, literal keys, and vim fallbacks. */
+export interface KeyBinding<A extends string> {
+  readonly action: A;
+  /** The pi keybinding id, when a named action exists for the gesture. */
+  readonly named?: Keybinding;
+  /** Literal keys for a gesture pi names no action for. */
+  readonly keys?: readonly KeyId[];
+  /** Vim literals, tried only after every named binding and literal missed. */
+  readonly vim?: readonly KeyId[];
+}
+
+/**
+ * Resolves one input byte string to an action of `table`.
+ *
+ * Returns undefined when the table binds nothing for the input, so a layer
+ * consumes only its own keys and shadows no other pi default binding. Named
+ * bindings and literal keys resolve in a first pass, so a user keybinding
+ * override always wins; vim literals apply only after that pass missed every
+ * entry (spec §2). The vim fallbacks guard only the bindings the table names —
+ * a vim literal can still collide with a remap of an action it does not name.
+ */
+export function routeKey<A extends string>(
+  data: string,
+  keybindings: NamedKeybindings,
+  table: readonly KeyBinding<A>[],
+): A | undefined {
+  for (const entry of table) {
+    if (entry.named !== undefined && keybindings.matches(data, entry.named)) return entry.action;
+    if (entry.keys?.some((key) => matchesKey(data, key)) === true) return entry.action;
+  }
+  for (const entry of table) {
+    if (entry.vim?.some((key) => matchesKey(data, key)) === true) return entry.action;
+  }
+  return undefined;
+}

package/src/node-actions.ts

@@ -0,0 +1,57 @@
+/**
+ * The per-node actions menu of the drill-in (spec §1): the surviving read-only
+ * action set of spec §5. A Peek observes and never sends, so no action here can
+ * prompt an Agent or stop a Run (ADR — Peek).
+ */
+import { renderFramedBox } from "./overlay-frame.ts";
+
+/** One thing a reader may do with the selected node. */
+export type NodeAction = "viewTranscript" | "copySessionPath" | "openSystemPrompt";
+
+/** One menu row: the action and the label the reader sees. */
+export interface NodeActionRow {
+  readonly action: NodeAction;
+  readonly label: string;
+}
+
+/** The three read-only actions, in menu order (spec §5). */
+export const NODE_ACTIONS: readonly NodeActionRow[] = [
+  { action: "viewTranscript", label: "View transcript" },
+  { action: "copySessionPath", label: "Copy session file path" },
+  { action: "openSystemPrompt", label: "Open system prompt in editor" },
+];
+
+const FOOTER = " ↑↓ move  ↵ run  esc back";
+
+/**
+ * One actions-menu render request.
+ *
+ * Contract: `nodePath` titles the menu and is sanitized and truncated to the
+ * frame; `cursor` selects the highlighted row; `width` is the exact visible
+ * width of every returned line. Failure mode: a `cursor` outside the action
+ * list highlights no row, and a narrow or non-finite `width` degrades through
+ * `renderFramedBox` rather than throwing.
+ */
+export interface ActionsMenuOptions {
+  readonly nodePath: string;
+  readonly cursor: number;
+  readonly width: number;
+}
+
+/** Moves the menu cursor by `delta`, clamped to the action list — no wrap. */
+export function moveMenuCursor(cursor: number, delta: number): number {
+  return Math.max(0, Math.min(NODE_ACTIONS.length - 1, cursor + delta));
+}
+
+/** Draws the framed actions menu, titled with the node path. */
+export function renderActionsMenu(options: ActionsMenuOptions): readonly string[] {
+  const rows = NODE_ACTIONS.map(
+    (row, index) => `${index === options.cursor ? "❯" : " "} ${row.label}`,
+  );
+  return renderFramedBox({
+    title: `${options.nodePath} ─ actions`,
+    lines: rows,
+    footer: FOOTER,
+    width: options.width,
+  });
+}

package/src/node-path-parse.ts

@@ -0,0 +1,54 @@
+/** One parsed segment of a node path: an agent name, optionally with its Ask index. */
+export interface NodePathSegment {
+  readonly name: string;
+  /** The 0-based wire Ask index, absent for a bare agent segment. */
+  readonly askIndex?: number;
+}
+
+/**
+ * Parses `name(:askIndex(/childName…))` into its segments.
+ *
+ * Returns null for an empty path, a malformed Ask index, or an inner segment
+ * that carries no Ask index, so a hostile or truncated `node_update.path`
+ * renders nothing rather than a forged row. Names never contain `:` or `/`:
+ * `sanitizeNodeName` (runtime) removes them.
+ */
+export function parseNodePath(path: string): readonly NodePathSegment[] | null {
+  if (path === "") return null;
+  const parts = path.split("/");
+  const segments: NodePathSegment[] = [];
+  for (const [position, part] of parts.entries()) {
+    const last = position === parts.length - 1;
+    const segment = parseSegment(part, last);
+    if (segment === null) return null;
+    segments.push(segment);
+  }
+  return segments;
+}
+
+function parseSegment(part: string, last: boolean): NodePathSegment | null {
+  const colon = part.indexOf(":");
+  if (colon === -1) return last && part !== "" ? { name: part } : null;
+  const name = part.slice(0, colon);
+  const askIndex = parseAskIndex(part.slice(colon + 1));
+  if (name === "" || askIndex === null) return null;
+  return { name, askIndex };
+}
+
+function parseAskIndex(text: string): number | null {
+  if (!/^\d+$/.test(text)) return null;
+  return Number.parseInt(text, 10);
+}
+
+/**
+ * The Agent that owns a node path — its first segment.
+ *
+ * A nested node has no session file of its own (it runs with `--no-session`),
+ * so its transcript and session path resolve through its owning Agent. Returns
+ * the empty string for the empty path; a roll-up marker (`agent#pruned`) keeps
+ * only the Agent name.
+ */
+export function agentOfPath(path: string): string {
+  const separator = path.search(/[:/#]/);
+  return separator === -1 ? path : path.slice(0, separator);
+}

package/src/node-table.ts

@@ -0,0 +1,34 @@
+import type { AgentInfo, NodeInfo } from "@yaag/runtime";
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { clamp } from "./tree-rows.ts";
+
+/** Running Nested Nodes drawn for one Agent before the roll-up line. */
+const RUNNING_NODE_LINES = 8;
+
+/**
+ * Renders one Agent's Nested Node table as indented terminal lines.
+ *
+ * Running nodes come first and are capped. Each running node the cap hid is
+ * counted in one "and N more running" line, and each settled node, retained or
+ * pruned by the Summary, is counted in one "and N more finished" line. The two
+ * roll-ups stay separate, so a hidden running node is never reported as
+ * finished. Returns no lines for an Agent that owns no nodes.
+ */
+export function renderNodeTable(agent: AgentInfo, columns: number): readonly string[] {
+  const running = agent.nodes.filter((node) => node.state === "running");
+  const shown = running.slice(0, RUNNING_NODE_LINES);
+  const lines = shown.map((node) => clamp(`    ▸ ${nodeLine(node)}`, columns));
+  const hiddenRunning = running.length - shown.length;
+  if (hiddenRunning > 0) {
+    lines.push(clamp(`    and ${hiddenRunning} more running`, columns));
+  }
+  const finished = agent.nodes.length - running.length + agent.finishedNodesPruned;
+  if (finished > 0) lines.push(clamp(`    and ${finished} more finished`, columns));
+  return lines;
+}
+
+function nodeLine(node: NodeInfo): string {
+  const path = sanitizeTerminalLine(node.path);
+  const gist = node.activityGist === null ? "" : sanitizeTerminalLine(node.activityGist);
+  return `${path}  ${node.state}${gist === "" ? "" : ` · ${gist}`}`;
+}

package/src/overlay-frame.ts

@@ -0,0 +1,99 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { clamp } from "./tree-rows.ts";
+
+/** The box-drawing glyphs the normative overlay mockup uses. */
+const FRAME = {
+  topLeft: "┌",
+  topRight: "┐",
+  bottomLeft: "└",
+  bottomRight: "┘",
+  side: "│",
+  rule: "─",
+} as const;
+
+/** The narrowest frame that still pads its content away from the borders. */
+const PADDED_WIDTH = 6;
+
+/** Used when a caller asks for a width that is not a finite number. */
+const FALLBACK_WIDTH = PADDED_WIDTH;
+
+/**
+ * One framed box request.
+ *
+ * Contract: `width` is the exact visible column count of every returned line,
+ * floored and clamped to at least one column. `title`, `lines`, and `footer`
+ * are untrusted text: each is sanitized to a single line and truncated to fit.
+ * Failure mode: a width that is not finite cannot be drawn, so it degrades to
+ * six columns instead of throwing.
+ */
+export interface FramedBoxOptions {
+  readonly title: string;
+  readonly lines: readonly string[];
+  /** A key-hint row drawn as the last content row; omitted when absent. */
+  readonly footer?: string;
+  readonly width: number;
+}
+
+/**
+ * Draws a titled box around already-rendered content lines.
+ *
+ * Every untrusted string is sanitized to one line and truncated to the frame, so
+ * a hostile transcript, prompt gist, or node path can neither forge a row nor
+ * emit an escape byte. Each returned line is exactly `width` visible columns
+ * wide, including the narrow widths 1 to 5: below six columns the frame drops
+ * its inner padding, and at one column it draws the left border only. A width
+ * that is not finite degrades to six columns; it never throws.
+ */
+export function renderFramedBox(options: FramedBoxOptions): readonly string[] {
+  const width = Number.isFinite(options.width)
+    ? Math.max(1, Math.floor(options.width))
+    : FALLBACK_WIDTH;
+  const body = [...options.lines];
+  if (options.footer !== undefined) body.push(options.footer);
+  return [
+    titleLine(options.title, width),
+    ...body.map((line) => contentLine(line, width)),
+    bottomLine(width),
+  ];
+}
+
+function titleLine(title: string, width: number): string {
+  if (width === 1) return FRAME.topLeft;
+  const inner = width - 2;
+  const text =
+    width >= PADDED_WIDTH
+      ? fit(`${FRAME.rule} ${clamp(sanitizeTerminalLine(title), width - 5)} `, inner)
+      : "";
+  const fill = Math.max(0, inner - visibleWidth(text));
+  return `${FRAME.topLeft}${text}${FRAME.rule.repeat(fill)}${FRAME.topRight}`;
+}
+
+function contentLine(line: string, width: number): string {
+  if (width === 1) return FRAME.side;
+  const inner = width - 2;
+  const room = width >= PADDED_WIDTH ? inner - 2 : inner;
+  const text = room <= 0 ? "" : fit(clamp(sanitizeTerminalLine(line), room), room);
+  const pad = " ".repeat(Math.max(0, room - visibleWidth(text)));
+  const middle = width >= PADDED_WIDTH ? ` ${text}${pad} ` : `${text}${pad}`;
+  return `${FRAME.side}${middle}${FRAME.side}`;
+}
+
+function bottomLine(width: number): string {
+  if (width === 1) return FRAME.bottomLeft;
+  return `${FRAME.bottomLeft}${FRAME.rule.repeat(width - 2)}${FRAME.bottomRight}`;
+}
+
+/** Drops trailing characters until the text fits, for wide-glyph safety. */
+function fit(text: string, room: number): string {
+  if (visibleWidth(text) <= room) return text;
+  let out = "";
+  let used = 0;
+  for (const character of text) {
+    const next = used + visibleWidth(character);
+    if (next > room) break;
+    out += character;
+    used = next;
+  }
+  return out;
+}

package/src/overlay-scroll.ts

@@ -0,0 +1,47 @@
+/**
+ * The pure scroll model for a drill-in overlay: a follow-tail offset that pins
+ * to the bottom of a live transcript, releases when the reader scrolls up, and
+ * re-pins on return. Clock-free and I/O-free, so the follow rules are testable
+ * without a terminal.
+ */
+
+/** A viewport over rendered content: a top-line offset and whether it follows tail. */
+export interface Scroll {
+  readonly offset: number;
+  readonly following: boolean;
+}
+
+/** A viewport that follows the tail of an empty document. */
+export function initialScroll(): Scroll {
+  return { offset: 0, following: true };
+}
+
+/** The largest valid top offset for `rows` of `total` content lines. */
+export function maxOffset(total: number, rows: number): number {
+  return Math.max(0, total - Math.max(1, rows));
+}
+
+/**
+ * Resolves the concrete top offset to render.
+ *
+ * A following viewport pins to the bottom as the transcript grows; a released
+ * one keeps its offset, clamped to the current content, so a shrinking or
+ * rewritten session file cannot scroll past the end.
+ */
+export function resolveOffset(state: Scroll, total: number, rows: number): number {
+  const limit = maxOffset(total, rows);
+  return state.following ? limit : Math.min(state.offset, limit);
+}
+
+/**
+ * Applies a scroll of `delta` lines (negative is up), re-deriving follow state.
+ *
+ * Reaching the bottom resumes following; scrolling anywhere above it pauses, so
+ * a reader inspecting history is never yanked back down by a host refresh.
+ */
+export function scrollBy(state: Scroll, delta: number, total: number, rows: number): Scroll {
+  const limit = maxOffset(total, rows);
+  const from = state.following ? limit : Math.min(state.offset, limit);
+  const offset = Math.max(0, Math.min(limit, from + delta));
+  return { offset, following: offset >= limit };
+}