jackherd 1.11.1 → 1.12.0

package/src/plans/texts.ts

@@ -1,8 +1,19 @@
-import { STALE_ACTIVITY_MINUTES } from './lane-summary'
+import { ARTIFACT_LINK_KIND } from '../config/link-kinds'
+import { AGENT_STATUS } from '../terminal/types'
+import type { LegendSection } from './legend'
 import { STALE_PLAN_DAYS } from './planned'
 import { CHECK_NAME_LENGTH, CHECKS, type ChecksState, type PullRequest } from './pull-requests'
 import { shownWithMore } from './shown-with-more'
-import { MODEL_MARK, NO_AGENT_WORD, PHASE_COUNT } from './symbols'
+import {
+  CHEVRON,
+  MODEL_MARK,
+  NO_AGENT_SYMBOL,
+  NO_AGENT_WORD,
+  PHASE_COUNT,
+  STATUS_SYMBOL,
+  TURN_MARK,
+  UNKNOWN_SYMBOL,
+} from './symbols'
 
 /** The words of an open lane: the age of a running phase, the words before the open phases that wait and the finished ones, and the pointer of a phase with only its review gate open. */
 export type HerdTexts = {
@@ -19,21 +30,48 @@ export type HerdTexts = {
  */
 export type PlanTexts = {
   noAgent: string
-  waiting: (lanes: number) => string
   startsAfter: (wait: string) => string
   noPlan: string
   noWorktree: string
   noRow: string
   /** The heads of the blocks on top of the herd. */
-  waitingHeading: string
-  appointmentHeading: string
+  yourTurnHeading: string
   sourceHeading: string
-  nextHeading: string
-  /** On a resting lane's line: the label before its starts-after cell, and the line for a lane without any reason. */
+  /** The heads of the blocks of the body: the lanes at work, the lanes that wait for their start, the unstarted plans. */
+  lanesHeading: string
+  waitingHeading: string
+  backlogHeading: string
+  /** The balance of the lanes head: how many lanes wait on you, how many idle otherwise. */
+  lanesWaitOnYou: (lanes: number) => string
+  lanesIdle: (lanes: number) => string
+  /** On a resting lane's line: the labels before a question to you, a row of "Your turn" and its starts-after cell, and the line for a lane without any reason. */
+  restWaitsOnYou: string
+  /** After `restWaitsOnYou`: how many questions of its report wait, their text being rows of "Your turn". */
+  restQuestions: (count: number) => string
+  restWaitsOn: string
   restAfter: string
   restNoReason: string
-  /** After the head of the next block when the board's section holds no line. */
-  nextEmpty: string
+  /** On an open lane's session line: how long its agent has rested. */
+  idleFor: (minutes: number) => string
+  /** The row under the tasks a phase shows of its open ones: how many more are open and how many are done. */
+  moreTasks: (open: number, done: number) => string
+  /** The row under an opened task's brief: how many lines its rest takes. */
+  moreLines: (count: number) => string
+  /** The footer while a row has the focus: what a click or a key does on it. */
+  clickHint: (action: string) => string
+  hintOpens: (name: string) => string
+  hintFolds: (name: string) => string
+  hintListsTasks: (phase: string) => string
+  hintFoldsTasks: (phase: string) => string
+  hintBlockAsks: string
+  hintBlockOpens: string
+  /** What the click hint calls a task, the rest of an opened task, the phases `next` lists and the ones `done` lists. */
+  hintTask: string
+  hintTaskRest: string
+  hintNextPhases: string
+  hintDonePhases: string
+  /** After the head of "Your turn" when nothing waits for the user and nothing is planned. */
+  yourTurnEmpty: string
   notInPlan: string
   /** Before a task an agent reports that no task of the plan names. */
   now: string
@@ -41,21 +79,18 @@ export type PlanTexts = {
   subagent: string
   /** In place of the count of a phase whose only open box is the documentation box of its review gate. */
   allButDocs: string
-  tickedSummary: (count: number) => string
-  /** The line above the listed ticked tasks of a phase; a click or `a` folds them again. */
-  tickedFold: (count: number) => string
   draft: string
   privateLink: string
-  planned: (phases: number, plans: number) => string
-  /** The head of the planned section in the herd: `planned · 3 plans, next:`. */
-  plannedHead: (plans: number) => string
+  /** The head of the backlog on the HTML page: `Backlog (3 phases in 2 plans)`. */
+  backlog: (phases: number, plans: number) => string
+  /** After the backlog head: `next: <plan> <phase>, …`. */
+  backlogNext: string
   phaseTally: (done: number, total: number) => string
   herd: HerdTexts
   checks: Record<ChecksState, string>
   hint: string
-  /** The notice when `a` is pressed with no phase open, where the key changes nothing on screen. */
-  showDoneNeedsPhase: string
-  legend: string[]
+  /** The help behind `?`: marks and keys with their meaning; the rules behind them stand in the README. */
+  legend: LegendSection[]
   /** The footer line when the coordinator could not be asked to put a question, with the reason. */
   notAsked: (reason: string) => string
   /** The footer line when the coordinator `name` was asked to put `subject`, `question <id>` or `board row <key>`. */
@@ -99,24 +134,42 @@ const ALL_BUT_DOCS = 'docs open'
 
 export const TEXTS: PlanTexts = {
   noAgent: NO_AGENT_WORD,
-  waiting: (lanes) => `waiting (${lanes})`,
   startsAfter: (wait) => `after ${wait}`,
   noPlan: 'no plan',
   noWorktree: 'no worktree',
   noRow: 'no row in lanes',
-  waitingHeading: 'Waiting for you',
-  appointmentHeading: 'Appointments',
+  yourTurnHeading: 'Your turn',
   sourceHeading: 'Sources',
-  nextHeading: 'Next',
-  restAfter: 'after:',
+  lanesHeading: 'Lanes',
+  waitingHeading: 'Waiting',
+  backlogHeading: 'Backlog',
+  lanesWaitOnYou: (lanes) => `${lanes} ${lanes === 1 ? 'waits' : 'wait'} on you`,
+  lanesIdle: (lanes) => `${lanes} idle`,
+  restWaitsOnYou: 'waits on you',
+  restQuestions: (count) => `· ${count} ${count === 1 ? 'question' : 'questions'}`,
+  restWaitsOn: 'waits on',
+  restAfter: 'after',
   restNoReason: 'idle · no reason',
-  nextEmpty: 'nothing queued, groom the board',
+  idleFor: (minutes) => `idle ${minutes < 60 ? `${minutes} min` : `${Math.floor(minutes / 60)} h`}`,
+  moreTasks: (open, done) =>
+    [...(open > 0 ? [`${open} more open`] : []), ...(done > 0 ? [`${done} done`] : [])].join(' · '),
+  moreLines: (count) => `${count} more ${count === 1 ? 'line' : 'lines'}`,
+  clickHint: (action) => `${action} · ? help`,
+  hintOpens: (name) => `click or → opens ${name}`,
+  hintFolds: (name) => `click or ← folds ${name}`,
+  hintListsTasks: (phase) => `click or → lists the tasks of ${phase}`,
+  hintFoldsTasks: (phase) => `click or ← folds the tasks of ${phase}`,
+  hintBlockAsks: 'click or enter asks the coordinator',
+  hintBlockOpens: 'click or enter opens it',
+  hintTask: 'the task',
+  hintTaskRest: 'the rest of the task',
+  hintNextPhases: 'the next phases',
+  hintDonePhases: 'the done phases',
+  yourTurnEmpty: 'nothing waits for you',
   notInPlan: 'not in the plan',
   now: 'now:',
   subagent: 'Subagent:',
   allButDocs: ALL_BUT_DOCS,
-  tickedSummary: (count) => `${count} ticked · click or a lists them`,
-  tickedFold: (count) => `${count} ticked · click or a folds them`,
   draft: 'draft · ',
   privateLink: 'private',
   phaseTally: (done, total) => (total > 0 ? `${done}/${total} ph` : ''),
@@ -127,26 +180,115 @@ export const TEXTS: PlanTexts = {
     reviewGate: 'Review gate',
     gate: '· gate',
   },
-  planned: (phases, plans) =>
-    `planned (${phases} ${phases === 1 ? 'phase' : 'phases'} in ${plans} ${plans === 1 ? 'plan' : 'plans'})`,
-  plannedHead: (plans) => `planned · ${plans} ${plans === 1 ? 'plan' : 'plans'}, next:`,
+  backlog: (phases, plans) =>
+    `Backlog (${phases} ${phases === 1 ? 'phase' : 'phases'} in ${plans} ${plans === 1 ? 'plan' : 'plans'})`,
+  backlogNext: 'next:',
   checks: {
     [CHECKS.passed]: '✓ checks',
     [CHECKS.failed]: '✗ checks',
     [CHECKS.pending]: '… checks',
     [CHECKS.none]: 'no checks',
   },
-  hint: '↑↓ select  →← open  a/click ticked tasks  s html  q quit  ? help',
-  showDoneNeedsPhase: 'a lists the ticked tasks inside an open phase: open one with → or a click',
+  hint: '↑↓ select  →← open  s html  q quit  ? help',
   legend: [
-    'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a link chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
-    '● working · ◆ blocked, waits for you · ◉ done = the agent finished its answer, not the lane · ○ idle · (·) no agent = a worktree nobody works in · • state unknown · only blocked wears its word in the lane line, the symbol says the rest · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · a working or blocked lane opens by itself only when it first appears, after that → ← and clicks are yours alone',
-    `▸ ▾ open and close · an open lane's branches, top down: the agent's title and ⎇ its branch, ↗ its pull requests, its link chips, the phases it works on, next, done · a lane shows only the phases its board rows name · a phase row = some of its tasks are ticked, one of its boxes was ticked in the last ${STALE_ACTIVITY_MINUTES} min, or an agent reports working on it, by number · n min ago since the last tick or report, · gate = only the review gate is open · ▶ teal = a task an agent reported (its task list or jh task; its name dim at the right edge when several agents work in the lane), ▷ dim = only guessed from the words of its log · now: <text> = a reported task no plan task names · a running review sits on the gate box that names it, in the phase it names or else the lane's current one · Subagent: <text> = a running subagent that names no phase and sits on none · next = the other open phases, as ranges · done = the finished ones · ${ALL_BUT_DOCS} = only the documentation box is open · a folded lane line names the phase moved last, +n more active ones, and its count · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a or a click on its ▸ n ticked line lists the ticked checkboxes of an open phase one by one, a or a click on its ▾ line folds them · s opens every lane and plan as one HTML page`,
-    `the bar = progress over the lane's plans · n/m = m checkboxes, n ticked · n/m ph = n of m phases finished · n/n in green = all ticked · 🥣 share of the context window used, on a folded lane only once it warns · Sonnet ${MODEL_MARK.differs} Opus in amber = the phase's subagent ran on another model than the plan's`,
-    '↗ pull request · 💬 new feedback · ✋ changes requested · 🌐 preview · 📡 ticket: chip 📡 T-1 · status among the link chips, 📡 <n> in amber on a folded lane when tickets are new',
-    `▌ on top = waits for your answer: 📎 a file or an Artifact that was sent (click: a cut-off row expands, then it opens), ? a question of the board or one a session left in its dialog (a click on its text only expands and folds it; [ask] at the right edge of a question asks the coordinator to put it; [done] closes the row: a board row gets its status, a sent file its record) · it goes when the board row is closed or \`jh waiting close <id>\` · \`Waiting for you\` heads the block (click: fold; click on +n: show all, on ▴ n: five) · ◷ the appointments of the board in a grey bar below it (click: fold; [done] closes the row, [run] asks the coordinator to run it now, [move] to ask you for a new time) · 1 2 3 = Next, the board lines to do next · ● Sources = the watcher’s sources that are no tickets: when each ran and its newest report, the mark amber while that report is under a day old and red while the source fails (click on a row: opens the entry) · planned = the open phases no lane works on, the next one per plan; stale? = its plan file was not changed on the base branch for ${STALE_PLAN_DAYS} days`,
-    '⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main',
-    '❯ and a light background = the row under the mouse or the arrows, on every clickable row · enter on a block row asks, opens or expands it and never presses [done] · [xx] in square brackets = a click does something, bold under the mouse',
+    {
+      title: 'Keys',
+      entries: [
+        { mark: '↑↓ j k', meaning: 'select a row' },
+        { mark: '→ ← enter', meaning: 'open, fold' },
+        { mark: 'h l space', meaning: 'like ← → and enter' },
+        { mark: 's', meaning: 'every lane and plan as one HTML page' },
+        { mark: 'wheel PgUp PgDn', meaning: 'scroll' },
+        { mark: 'click', meaning: 'what the footer says' },
+        { mark: 'ctrl+click', meaning: 'open a link chip' },
+        { mark: '? esc', meaning: 'close help' },
+        { mark: 'q', meaning: 'quit' },
+      ],
+    },
+    {
+      title: 'Lanes',
+      entries: [
+        { mark: STATUS_SYMBOL[AGENT_STATUS.working], meaning: 'agent working' },
+        { mark: STATUS_SYMBOL[AGENT_STATUS.blocked], meaning: 'blocked, waits for you' },
+        { mark: STATUS_SYMBOL[AGENT_STATUS.done], meaning: 'done: the agent finished its answer' },
+        { mark: STATUS_SYMBOL[AGENT_STATUS.idle], meaning: 'idle' },
+        { mark: `(${NO_AGENT_SYMBOL}) ${NO_AGENT_WORD}`, meaning: 'a worktree nobody works in' },
+        { mark: UNKNOWN_SYMBOL, meaning: 'state unknown' },
+        { mark: 'waits on you', meaning: '· n questions: open questions of its report' },
+        { mark: '🥣 36 %', meaning: 'context used' },
+        { mark: '⎇ ↑ ±', meaning: 'branch, commits ahead, uncommitted' },
+        { mark: 'n/m ph', meaning: 'phases finished' },
+        { mark: 'stale?', meaning: `plan unchanged for ${STALE_PLAN_DAYS} days` },
+      ],
+    },
+    {
+      title: 'Tasks',
+      entries: [
+        { mark: '● teal', meaning: 'running (reported), its text shimmers' },
+        { mark: '◌ dim', meaning: 'running (guessed)' },
+        { mark: `${CHEVRON.closed} ${CHEVRON.open}`, meaning: 'opens / folds' },
+        { mark: '☐ ☑', meaning: 'open, done' },
+        { mark: '→ P9', meaning: 'moved to another phase' },
+        { mark: 'now:', meaning: 'reported, no plan task names it' },
+        { mark: 'Subagent:', meaning: 'a subagent on no phase' },
+        { mark: '· gate', meaning: 'only the review gate is open' },
+        { mark: ALL_BUT_DOCS, meaning: 'only the documentation box is open' },
+        { mark: 'n/m', meaning: 'n of m checkboxes ticked' },
+        { mark: PHASE_COUNT.empty, meaning: 'no checkboxes' },
+        { mark: PHASE_COUNT.missing, meaning: 'not in the plan' },
+        { mark: `Sonnet ${MODEL_MARK.differs} Opus`, meaning: "another model than the plan's" },
+      ],
+    },
+    {
+      title: 'Your turn',
+      entries: [
+        { mark: TURN_MARK.now, meaning: 'question, amber' },
+        { mark: TURN_MARK.file, meaning: 'file or artifact sent' },
+        { mark: TURN_MARK.planned, meaning: 'appointment, teal' },
+        { mark: 'unblocks …', meaning: 'the lanes it frees' },
+        { mark: '[ask]', meaning: 'ask the coordinator to put it' },
+        { mark: '[done]', meaning: 'close the row' },
+        { mark: '[run]', meaning: 'run the appointment now' },
+        { mark: '[move]', meaning: 'ask for a new time' },
+      ],
+    },
+    {
+      title: 'Sources',
+      entries: [
+        { mark: 'amber', meaning: 'a new entry, not in Your turn' },
+        { mark: 'red', meaning: 'the source fails' },
+        { mark: '↑ in your turn', meaning: 'a row of Your turn asks about it' },
+      ],
+    },
+    {
+      title: 'Links',
+      entries: [
+        { mark: ARTIFACT_LINK_KIND.icon, meaning: 'artifact' },
+        { mark: '⑂', meaning: 'pull request or issue' },
+        { mark: '◈', meaning: 'Figma' },
+        { mark: '↗', meaning: 'pull request' },
+        { mark: '💬', meaning: 'new feedback' },
+        { mark: '✋', meaning: 'changes requested' },
+        { mark: '🌐', meaning: 'preview' },
+        { mark: '📡 T-1', meaning: 'ticket' },
+        { mark: '+n', meaning: 'more chips' },
+        { mark: 'private', meaning: 'the plan says so' },
+      ],
+    },
+    {
+      title: 'Colours',
+      entries: [
+        { mark: 'bold', meaning: 'a heading: lane name, phase title' },
+        { mark: 'plain', meaning: 'an open task' },
+        { mark: 'dim', meaning: 'an addition: time, ▸ n done, a path' },
+        { mark: '❯ light', meaning: 'the row under the mouse or the arrows' },
+        { mark: 'teal', meaning: 'runs: a reported task and its ●, or planned' },
+        { mark: 'amber', meaning: 'waits on you' },
+        { mark: 'red', meaning: 'fails' },
+        { mark: 'green', meaning: 'all ticked' },
+        { mark: '[xx] bold', meaning: 'the button under the mouse' },
+      ],
+    },
   ],
   notAsked: (reason) => `no coordinator to ask: ${reason}`,
   asked: (name, subject) => `asked ${name} for ${subject}`,

package/src/plans/view.ts

@@ -1,16 +1,29 @@
 import { ARTIFACT_LINK_KIND } from '../config/link-kinds'
 import { DEFAULT_TONES } from '../config/tones'
-import { fit, plainText } from '../terminal/text'
-import { renderSelected, type Screen } from './layout'
+import { fit, paint, plainText, visibleLength } from '../terminal/text'
+import { type AgentOf, clickHint } from './click-hint'
+import { type OverviewView, renderScreen, renderSelected, type Screen } from './layout'
 import type { Options } from './options'
+import { blockRowByKey, boldBracketAt, type FocusHit, focusLine, isFocused, LINKS_KEY_PREFIX } from './row-focus'
 import { laneSelection, overviewSelection, type Selection } from './selection'
+import { longestShimmer, type ShimmerRow, shimmerAt, shimmerRows } from './shimmer'
 import type { Snapshot } from './snapshot'
+import { TEXTS } from './texts'
 import { setTones } from './tones'
 
 const DEFAULT_WIDTH = 100
 const CURSOR_HOME = '\x1b[H'
 const CLEAR_LINE_END = '\x1b[K'
 const CLEAR_BELOW = '\x1b[J'
+const SYNC_BEGIN = '\x1b[?2026h'
+const SYNC_END = '\x1b[?2026l'
+
+/** One frame at 60 Hz: the herd draws at most once in this time. */
+export const FRAME_MS = 16
+
+/** How long to wait before the next drawing, so there is at most one per `FRAME_MS`; null `lastFrameAt` before the first. */
+export const nextFrameDelay = (lastFrameAt: number | null, now: number): number =>
+  lastFrameAt === null ? 0 : Math.max(FRAME_MS - (now - lastFrameAt), 0)
 
 export const TERMINAL_ON = '\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1003h\x1b[?1006h'
 export const TERMINAL_OFF = '\x1b[?1006l\x1b[?1003l\x1b[?1000l\x1b[?25h\x1b[?1049l'
@@ -23,52 +36,205 @@ const paneRows = (): number => process.stdout.rows ?? Number.MAX_SAFE_INTEGER
 export const bodyRows = (screen: Screen): number =>
   Math.max(paneRows() - screen.header.length - screen.footer.length, 1)
 
-/** The time as `HH:MM`, in the header and in the refresh error alike: a frame differs only once a minute. */
+/** The time as `HH:MM`, for the refresh error; the header carries no clock, so a quiet herd draws nothing new. */
 export const clockOf = (locale: string, now: Date = new Date()): string =>
   now.toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit' })
 
+const overviewOf = (snapshot: Snapshot, shimmer: boolean): OverviewView => {
+  setTones(snapshot.tones ?? DEFAULT_TONES)
+  return {
+    title: snapshot.title,
+    lanes: snapshot.views,
+    planned: snapshot.planned,
+    watch: snapshot.watch,
+    watchesTickets: snapshot.watchesTickets,
+    awaiting: snapshot.waiting,
+    groomedDays: snapshot.groomedDays,
+    yourTurn: snapshot.yourTurn,
+    sourceBlock: snapshot.sourceBlock,
+    unplaced: snapshot.unplaced,
+    shimmer,
+  }
+}
+
+const withErrors = (screen: Screen, errors: string[], width: number): Screen => ({
+  ...screen,
+  footer: [...errors.map((error) => fit(error, width)), ...screen.footer],
+})
+
 export const renderSnapshot = (
   snapshot: Snapshot,
   selection: Selection,
   errors: string[],
   width: number,
-  locale: string,
-): Screen => {
-  setTones(snapshot.tones ?? DEFAULT_TONES)
-  const screen = renderSelected(
-    {
-      title: snapshot.title,
-      time: clockOf(locale),
-      lanes: snapshot.views,
-      planned: snapshot.planned,
-      watch: snapshot.watch,
-      watchesTickets: snapshot.watchesTickets,
-      awaiting: snapshot.waiting,
-      groomedDays: snapshot.groomedDays,
-      next: snapshot.next,
-      appointments: snapshot.appointments,
-      sourceBlock: snapshot.sourceBlock,
-      unplaced: snapshot.unplaced,
-    },
-    selection,
-    width,
-  )
-  return { ...screen, footer: [...errors.map((error) => fit(error, width)), ...screen.footer] }
-}
+  shimmer = false,
+): Screen => withErrors(renderSelected(overviewOf(snapshot, shimmer), selection, width), errors, width)
+
+/** The snapshot drawn with no row focused (`unfocused`), the base a hover lays its focus on (`focusedScreen`). */
+export const renderUnfocused = (
+  snapshot: Snapshot,
+  selection: Selection,
+  errors: string[],
+  width: number,
+  shimmer = false,
+): Screen => withErrors(renderScreen(overviewOf(snapshot, shimmer), unfocused(selection), width), errors, width)
+
+/** The status of a lane's agent by the lane's name, for the footer's click hint. */
+export const agentOfSnapshot =
+  ({ views }: Snapshot): AgentOf =>
+  (name) =>
+    views.find(({ progress }) => progress.lane.name === name)?.status.agent ?? null
 
 export const startSelection = (snapshot: Snapshot, options: Options): Selection =>
   options.lane ? laneSelection(snapshot.views[0]?.progress) : overviewSelection()
 
-/** Header and footer stay put; the body shows `bodyRows` lines from `top`, padded so the footer sits at the bottom. */
-export const frameOutput = (screen: Screen, top: number, width: number, rows: number): string => {
+/** Header and footer stay put; the body shows `rows` lines from `top`, padded so the footer sits at the bottom. */
+export const frameLinesOf = (screen: Screen, top: number, rows: number): string[] => {
   const body = screen.body.lines.slice(top, top + rows)
   const padding = Array.from({ length: Math.max(rows - body.length, 0) }, () => '')
-  const lines = [...screen.header, ...body, ...padding, ...screen.footer]
-  return `${CURSOR_HOME}${lines.map((line) => `${fit(line, width)}${CLEAR_LINE_END}`).join('\r\n')}${CLEAR_BELOW}`
+  return [...screen.header, ...body, ...padding, ...screen.footer]
+}
+
+/** One line as written, a shimmering text with its stripe at `now`, cut to the pane. */
+const drawnLine = (line: string, width: number, now: number, longest: number): string =>
+  `${fit(shimmerAt(line, now, longest), width)}${CLEAR_LINE_END}`
+
+/** `lines` written whole from the top, between the marks of synchronized output. */
+const wholeFrame = (lines: readonly string[], width: number, now: number): string => {
+  const longest = longestShimmer(lines)
+  const drawn = lines.map((line) => drawnLine(line, width, now, longest)).join('\r\n')
+  return `${SYNC_BEGIN}${CURSOR_HOME}${drawn}${CLEAR_BELOW}${SYNC_END}`
 }
 
-/** The frame to write, or null when the terminal already shows it; a null `previous` means the terminal content is unknown. */
-export const frameToWrite = (previous: string | null, next: string): string | null => (previous === next ? null : next)
+/**
+ * The frame of `frameLinesOf` as written, a shimmering text with its stripe at `now` (epoch milliseconds). It stands
+ * between the marks of synchronized output, so a terminal that knows them never shows half of it.
+ */
+export const frameOutput = (screen: Screen, top: number, width: number, rows: number, now: number): string =>
+  wholeFrame(frameLinesOf(screen, top, rows), width, now)
+
+/**
+ * What to write to turn the frame `previous` on the terminal into `lines`: the frame whole when the terminal content
+ * is unknown (null) or its height changed, else each changed line at its cursor address, nothing when none changed.
+ * Lines are compared with their shimmer marks, so a stripe that moved on is no change (the shimmer clock draws that).
+ */
+export const changedLinesOutput = (
+  previous: readonly string[] | null,
+  lines: readonly string[],
+  width: number,
+  now: number,
+): string => {
+  if (previous === null || previous.length !== lines.length) return wholeFrame(lines, width, now)
+  const longest = longestShimmer(lines)
+  const changed = lines.flatMap((line, index) =>
+    line === previous[index] ? [] : [`\x1b[${index + 1};1H${drawnLine(line, width, now, longest)}`],
+  )
+  return changed.length === 0 ? '' : `${SYNC_BEGIN}${changed.join('')}${SYNC_END}`
+}
+
+/** The lines of the frame `frameOutput` writes that shimmer, by their row on the terminal. */
+export const frameShimmerRows = (screen: Screen, top: number, rows: number): ShimmerRow[] =>
+  shimmerRows(frameLinesOf(screen, top, rows))
+
+/** The rows that shimmer, prepared once per frame: the pass they share, and whether a row is wider than the pane. */
+export type PreparedShimmer = {
+  rows: readonly (ShimmerRow & { wide: boolean })[]
+  longest: number
+  width: number
+}
+
+export const preparedShimmer = (rows: readonly ShimmerRow[], width: number): PreparedShimmer => ({
+  rows: rows.map((row) => ({ ...row, wide: visibleLength(row.line) > width })),
+  longest: longestShimmer(rows.map(({ line }) => line)),
+  width,
+})
+
+/**
+ * The shimmer of the prepared rows at `now`: each row rewritten at its cursor address, nothing else of the pane, in
+ * one text within the marks of synchronized output; empty without rows. Only a row wider than the pane is cut.
+ */
+export const shimmerOutput = ({ rows, longest, width }: PreparedShimmer, now: number): string => {
+  if (rows.length === 0) return ''
+  const drawn = rows.map(({ row, line, wide }) => {
+    const striped = shimmerAt(line, now, longest)
+    return `\x1b[${row};1H${wide ? fit(striped, width) : striped}${CLEAR_LINE_END}`
+  })
+  return `${SYNC_BEGIN}${drawn.join('')}${SYNC_END}`
+}
+
+/** A selection that focuses no row: the screen drawn with it is the base `focusedScreen` lays the focus on. */
+export const unfocused = (selection: Selection): Selection => ({
+  ...selection,
+  selected: NO_ROW,
+  hovered: null,
+  hoveredFrom: null,
+})
+
+const NO_ROW = '\0'
+const LEAD = /^ */
+
+/** The blanks a block puts before a row it holds (`indented`): the focus lies right of them, as narrow as the row. */
+const leadOf = (line: string): number => LEAD.exec(line)?.[0].length ?? 0
+
+/** `lines` with the lines of `hit` (counted from `offset`) changed by `change`, the first line told by its index. */
+const changedHit = (
+  lines: readonly string[],
+  offset: number,
+  hit: FocusHit | undefined,
+  change: (line: string, index: number) => string,
+): string[] =>
+  lines.map((line, at) => {
+    const index = hit ? at + offset - hit.line : -1
+    return hit && index >= 0 && index < hit.lines ? change(line, index) : line
+  })
+
+/**
+ * `screen` with the focus `state` gives laid on one region of `lines`: the focused row on the focus background and
+ * mark, a line of links under the mouse marked alone, and the square-bracket button under the mouse bold.
+ */
+const focusedLines = (lines: readonly string[], offset: number, screen: Screen, state: Selection, width: number) => {
+  const hitOf = (key: string | null | undefined) => (key ? screen.focusHits.find((hit) => hit.key === key) : undefined)
+  const hovered = hitOf(state.hovered)
+  const focusedKey = state.selected !== null && isFocused(state, state.selected) ? state.selected : null
+  const focusedHit = hitOf(focusedKey)
+  const gutter = focusedHit ? leadOf(lines[focusedHit.line - offset] ?? '') : 0
+  const focused = changedHit(
+    lines,
+    offset,
+    focusedHit,
+    (line, index) => `${line.slice(0, gutter)}${focusLine(line.slice(gutter), width - gutter, index === 0)}`,
+  )
+  const links = state.hovered?.startsWith(LINKS_KEY_PREFIX)
+    ? changedHit(focused, offset, hovered, (line, index) => (index === 0 ? focusLine(line, width, true) : line))
+    : focused
+  const from = state.hoveredFrom
+  return from == null
+    ? links
+    : changedHit(links, offset, hovered, (line, index) => (index === 0 ? boldBracketAt(line, from) : line))
+}
+
+/**
+ * The screen a full drawing with `state` gives, laid on `plain` (drawn with `unfocused`) without a new layout: a hover
+ * only moves the focus. Null where it needs the layout: with the help open, or for a row of the blocks on top, whose
+ * buttons stand only at the selection. `agentOf` says a lane's agent, for the footer's click hint.
+ */
+export const focusedScreen = (plain: Screen, state: Selection, width: number, agentOf: AgentOf): Screen | null => {
+  const blocks = [plain.yourTurnBlock, plain.sourceBlock]
+  const isBlockRow = (key: string | null | undefined) => !!key && blockRowByKey(blocks, key) !== null
+  if (state.showLegend || isBlockRow(state.selected) || isBlockRow(state.hovered)) return null
+  const header = focusedLines(plain.header, 0, plain, state, width)
+  const lines = focusedLines(plain.body.lines, plain.header.length, plain, state, width)
+  const selectedHit = plain.focusHits.find(({ key }) => key === state.selected)
+  const cursorLine =
+    selectedHit && selectedHit.line >= plain.header.length ? selectedHit.line - plain.header.length : -1
+  const hint = clickHint(state, (key) => blockRowByKey(blocks, key), agentOf) ?? TEXTS.hint
+  return {
+    ...plain,
+    header,
+    body: { ...plain.body, lines, cursorLine },
+    footer: [...plain.footer.slice(0, -1), fit(paint.dim(hint), width)],
+  }
+}
 
 const ARTIFACT_ADDRESS = new RegExp(ARTIFACT_LINK_KIND.pattern)