jackherd 1.11.2 → 1.12.0

package/src/plans/selection.ts

@@ -1,7 +1,6 @@
 import { currentPhase, type LaneProgress } from '../plan-format'
 import { AGENT_STATUS } from '../terminal/types'
 import { chipUrlOf, isChipKey, planUrlOf } from './link-chips'
-import { TEXTS } from './texts'
 
 /**
  * Whether a lane is drawn open. It is decided once, when the lane first appears (`autoOpen`, by its status then), and
@@ -10,13 +9,12 @@ import { TEXTS } from './texts'
 export type LaneFold = { open: boolean }
 
 /** The blocks on top of the herd, by the name their fold is remembered under. */
-export const TOP_BLOCK = { waiting: 'waiting', next: 'next', appointments: 'appointments', sources: 'sources' } as const
+export const TOP_BLOCK = { yourTurn: 'yourTurn', sources: 'sources' } as const
 export type TopBlockId = (typeof TOP_BLOCK)[keyof typeof TOP_BLOCK]
 
 /**
- * The row under the cursor and the expanded phases, both as keys, whether ticked phases and items are
- * listed one by one or summed up in one line, whether the footer shows the symbol legend, and the
- * folds of the lanes by lane name.
+ * The row under the cursor and the expanded phases, both as keys, whether the footer shows the symbol legend, and
+ * the folds of the lanes by lane name.
  */
 export type Selection = {
   selected: string | null
@@ -25,11 +23,12 @@ export type Selection = {
   /** The column the square-bracket button under the mouse starts in; null or absent while the mouse is over none. */
   hoveredFrom?: number | null
   expanded: ReadonlySet<string>
-  showDone: boolean
   showLegend: boolean
   laneFolds: ReadonlyMap<string, LaneFold>
-  /** Per folded top block, the keys of its points seen when it was folded; a block that is open has no entry. */
-  blockFolds?: Readonly<Partial<Record<TopBlockId, ReadonlySet<string>>>>
+  /** The top blocks the user opened; every other one is folded, at the start of the herd all of them. */
+  openBlocks?: ReadonlySet<TopBlockId>
+  /** True once the user folded the lanes block, which is open at the start; absent or false while it is open. */
+  lanesFolded?: boolean
 }
 
 /** A lane as the folds need it: its name and the status its agent reports, null without an agent. */
@@ -58,8 +57,8 @@ export const INPUT = {
   toggle: ['\r', ' '],
   expand: ['\x1b[C', '\x1bOC', 'l'],
   collapse: ['\x1b[D', '\x1bOD', 'h'],
-  showDone: ['a'],
   legend: ['?'],
+  closeLegend: ['\x1b'],
   sprintPage: ['s'],
   pageUp: ['\x1b[5~'],
   pageDown: ['\x1b[6~'],
@@ -76,8 +75,46 @@ export const MOUSE_BUTTON = { left: 0, wheelUp: 64, wheelDown: 65 } as const
 /** One terminal read can carry several key presses; this splits it into keys, escape sequences kept whole. */
 export const splitKeys = (chunk: string): string[] => chunk.match(ESCAPE_SEQUENCE) ?? []
 
-/** The key of the closing row that lists the planned phases; no lane key starts without `@`, no phase key lacks a colon. */
-export const PLANNED_KEY = 'planned'
+const isMotionReport = (key: string): boolean => {
+  const mouse = parseMouse(key)
+  return mouse !== null && isMotion(mouse)
+}
+
+/**
+ * The keys of one read with every mouse motion but the last dropped: only where the mouse ended up counts, so a burst
+ * of motions is one hover, not one drawing each. Clicks, releases, the wheel and keys stay in their order.
+ */
+export const withoutStaleMotions = (keys: readonly string[]): string[] => {
+  const last = keys.reduce((found, key, index) => (isMotionReport(key) ? index : found), -1)
+  return keys.filter((key, index) => index === last || !isMotionReport(key))
+}
+
+/**
+ * The keys of the heads of the blocks of the body: the lanes at work, the lanes that wait for their start, and the
+ * backlog of phases no lane works on. No lane key starts without `@`, no phase key lacks a colon.
+ */
+const BLOCK_KEY_PREFIX = 'block>'
+export const LANES_KEY = `${BLOCK_KEY_PREFIX}lanes`
+export const WAITING_KEY = `${BLOCK_KEY_PREFIX}waiting`
+export const BACKLOG_KEY = `${BLOCK_KEY_PREFIX}backlog`
+
+/** Whether a key is the head of a block of the body. */
+export const isBlockHeadKey = (key: string): boolean => key.startsWith(BLOCK_KEY_PREFIX)
+
+const TOP_HEAD_KEY_PREFIX = 'head>'
+
+/** The key of the head of a block on top, which the arrows reach like every other clickable row. */
+export const topBlockHeadKey = (block: TopBlockId): string => `${TOP_HEAD_KEY_PREFIX}${block}`
+
+/** The block on top whose head a key names, null for any other key. */
+export const topBlockOfKey = (key: string): TopBlockId | null =>
+  Object.values(TOP_BLOCK).find((block) => topBlockHeadKey(block) === key) ?? null
+
+/** Whether the lanes block is drawn open: it is at the start of the herd, until the user folds it. */
+export const isLanesOpen = ({ lanesFolded }: Selection): boolean => !lanesFolded
+
+const withLanesOpen = (selection: Selection, open: boolean): Selection =>
+  isLanesOpen(selection) === open ? selection : { ...selection, lanesFolded: !open }
 
 export const phaseKey = (lane: string, stepIndex: number, phaseId: string): string => `${lane}:${stepIndex}:${phaseId}`
 
@@ -88,17 +125,16 @@ const PHASE_KEY = new RegExp(`^${PHASE_KEY_SHAPE}$`)
 /** Whether a key names a phase: not a lane, row or task key, which carry `@`, `>` or `#`. */
 const isPhaseKey = (key: string): boolean => PHASE_KEY.test(key)
 
+/** The phase id a phase key names (`4` of `lane:0:4`), null for any other key. */
+export const phaseIdOfKey = (key: string): string | null =>
+  isPhaseKey(key) ? key.slice(key.lastIndexOf(':') + 1) : null
+
 /** The key of a lane's `next` row, which opens to the phases that wait. */
 export const nextKey = (lane: string): string => `next>${lane}`
 
 /** The key of a lane's `✓` row, which opens to the finished phases. */
 export const finishedKey = (lane: string): string => `done>${lane}`
 
-const TICKED_KEY_PREFIX = 'ticked>'
-
-/** The key of the "N ticked" line of an open phase; it is clicked only, and a click lands on the phase. */
-export const tickedKey = (phase: string): string => `${TICKED_KEY_PREFIX}${phase}`
-
 const ITEM_KEY = new RegExp(`^(${PHASE_KEY_SHAPE})#(\\d+)$`)
 
 /**
@@ -108,18 +144,23 @@ const ITEM_KEY = new RegExp(`^(${PHASE_KEY_SHAPE})#(\\d+)$`)
  */
 export const itemKey = (phase: string, index: number): string => `${phase}#${index}`
 
+const TASK_REST_PREFIX = 'rest>'
+
+/** The key of the `▸ n more lines` row under an opened task, which opens the rest of its text. */
+export const taskRestKey = (task: string): string => `${TASK_REST_PREFIX}${task}`
+
+/** Whether a key is the rest row of an opened task. */
+export const isTaskRestKey = (key: string): boolean => key.startsWith(TASK_REST_PREFIX)
+
 /** The phase a task key belongs to, null for any other key. */
 export const itemPhaseOfKey = (key: string): string | null => key.match(ITEM_KEY)?.[1] ?? null
 
-const tickedPhaseOfKey = (key: string): string | null =>
-  key.startsWith(TICKED_KEY_PREFIX) ? key.slice(TICKED_KEY_PREFIX.length) : null
-
 const LANE_KEY_PREFIX = '@'
 
 /** The key of a lane's own row; it cannot collide with a phase key, which starts with a lane name and a colon. */
 export const laneKey = (lane: string): string => `${LANE_KEY_PREFIX}${lane}`
 
-const laneOfKey = (key: string): string | null => (key.startsWith(LANE_KEY_PREFIX) ? key.slice(1) : null)
+export const laneOfKey = (key: string): string | null => (key.startsWith(LANE_KEY_PREFIX) ? key.slice(1) : null)
 
 /** Working and blocked lanes show their phases; idle and done ones, and lanes without an agent, fold into one line. */
 export const autoOpen = (status: string | null): boolean =>
@@ -148,7 +189,6 @@ export const syncLaneFolds = (selection: Selection, lanes: readonly LaneStatusEn
 export const overviewSelection = (): Selection => ({
   selected: null,
   expanded: new Set(),
-  showDone: false,
   showLegend: false,
   laneFolds: new Map(),
 })
@@ -164,9 +204,9 @@ export const laneSelection = (progress: LaneProgress | undefined): Selection =>
   return { ...opened, selected: key, expanded: new Set([key]) }
 }
 
-/** The selectable rows in screen order, once each: only what is drawn can be selected; a chip or a "N ticked" line is clicked, not selected. */
+/** The selectable rows in screen order, once each: only what is drawn can be selected; a chip is clicked, not selected. */
 export const targetKeys = (targets: readonly ClickTarget[]): string[] => [
-  ...new Set(targets.map((target) => target.key).filter((key) => !isChipKey(key) && tickedPhaseOfKey(key) === null)),
+  ...new Set(targets.map((target) => target.key).filter((key) => !isChipKey(key))),
 ]
 
 /** The selected key, or the first one while nothing is selected or the selected phase left the sprint. */
@@ -183,7 +223,8 @@ const move = (selection: Selection, keys: readonly string[], step: number): Sele
 }
 
 const toggleIn = (keys: Set<string>, key: string): void => {
-  if (!keys.delete(key)) keys.add(key)
+  if (keys.has(key)) removeKey(keys, key)
+  else keys.add(key)
 }
 
 const opened = () => true
@@ -198,18 +239,15 @@ const foldLane = (selection: Selection, lane: string, next: (open: boolean) => b
 }
 
 /**
- * Selects the row under a click. A "N ticked" line flips `showDone` and selects its phase, a lane line flips the
- * fold of its lane, any other row opens when closed and closes when open: a phase shows its items.
+ * Selects the row under a click. A lane line flips the fold of its lane, any other row opens when closed and closes
+ * when open: a phase shows its items, a task its whole text. A task never opens its phase: the tasks shown under a
+ * folded phase stay under a folded phase.
  */
 export const applyClick = (selection: Selection, key: string): Selection => {
-  const phase = tickedPhaseOfKey(key)
-  if (phase !== null) return { ...selection, showDone: !selection.showDone, selected: phase }
-  const lane = laneOfKey(key)
-  if (lane !== null) return { ...foldLane(selection, lane, flipped), selected: key }
+  const head = foldedHead(selection, key, flipped)
+  if (head) return head
   const expanded = new Set(selection.expanded)
-  const itemPhase = itemPhaseOfKey(key)
-  if (itemPhase !== null && !expanded.has(itemPhase)) addWithPhase(expanded, key)
-  else toggleIn(expanded, key)
+  toggleIn(expanded, key)
   return { ...selection, selected: key, expanded }
 }
 
@@ -218,18 +256,33 @@ const toggle = (selection: Selection, keys: readonly string[]): Selection => {
   return current ? applyClick(selection, current) : selection
 }
 
-/** Adds a key to the expanded ones, with the phase of a task. */
-const addWithPhase = (expanded: Set<string>, key: string): void => {
+const addKey = (expanded: Set<string>, key: string): void => {
   expanded.add(key)
-  const itemPhase = itemPhaseOfKey(key)
-  if (itemPhase !== null) expanded.add(itemPhase)
 }
 
+/** Folds `key`, and the rest of its text when it is a task, so the next opening shows the brief again. */
 const removeKey = (expanded: Set<string>, key: string): void => {
   expanded.delete(key)
+  expanded.delete(taskRestKey(key))
 }
 
-/** Applies a change to the selected row: `nextFold` to the fold of a lane, `change` to the expanded keys for any other row. */
+/**
+ * The selection with the fold of `key` changed by `next` and `key` selected, when it is a row with a fold of its own:
+ * a lane, the lanes block or a block on top. Null for any other row, which opens through the expanded keys.
+ */
+const foldedHead = (selection: Selection, key: string, next: (open: boolean) => boolean): Selection | null => {
+  const lane = laneOfKey(key)
+  if (lane !== null) return { ...foldLane(selection, lane, next), selected: key }
+  if (key === LANES_KEY) return { ...withLanesOpen(selection, next(isLanesOpen(selection))), selected: key }
+  const block = topBlockOfKey(key)
+  if (block === null) return null
+  return { ...withBlockOpen(selection, block, next(!isBlockFolded(selection, block))), selected: key }
+}
+
+/**
+ * Applies a change to the selected row: `nextFold` to the fold of a lane, the lanes block or a block on top, `change`
+ * to the expanded keys for any other row.
+ */
 const changeSelected = (
   selection: Selection,
   keys: readonly string[],
@@ -238,82 +291,61 @@ const changeSelected = (
 ): Selection => {
   const current = selectedKey(selection, keys)
   if (!current) return selection
-  const lane = laneOfKey(current)
-  if (lane !== null) return { ...foldLane(selection, lane, nextFold), selected: current }
+  const head = foldedHead(selection, current, nextFold)
+  if (head) return head
   const expanded = new Set(selection.expanded)
   change(expanded, current)
   return { ...selection, selected: current, expanded }
 }
 
-/** The selection with `key` expanded when it was folded and folded when it was expanded; nothing else changes. */
-export const toggledExpansion = (selection: Selection, key: string): Selection => {
-  const expanded = new Set(selection.expanded)
-  if (!expanded.delete(key)) expanded.add(key)
-  return { ...selection, expanded }
-}
+/**
+ * Whether `candidate` is a point under `key`: one of its rows (`<key>><id>`), its `+<n>` line (`more><key>`) or the
+ * rest of its text when it is a task.
+ */
+const isChildKey = (key: string, candidate: string): boolean =>
+  candidate.startsWith(`${key}>`) || candidate === `more>${key}` || candidate === taskRestKey(key)
 
 /**
- * Whether `block` is drawn folded: it was folded and every point now open was there then. A point that arrived since
- * opens it again, so folding never hides something new. Each block remembers its own points.
+ * The selection with `key` expanded when it was folded, and folded with every point under it when it was expanded, so
+ * nothing stays open inside a folded row and comes back on the next opening; nothing else changes.
  */
-export const isBlockFolded = ({ blockFolds }: Selection, block: TopBlockId, keys: readonly string[]): boolean => {
-  const folded = blockFolds?.[block]
-  return folded !== undefined && keys.every((key) => folded.has(key))
+export const toggledExpansion = (selection: Selection, key: string): Selection => {
+  if (!selection.expanded.has(key)) return { ...selection, expanded: new Set(selection.expanded).add(key) }
+  const expanded = new Set([...selection.expanded].filter((open) => open !== key && !isChildKey(key, open)))
+  return { ...selection, expanded }
 }
 
 /**
- * The selection with the fold of each block forgotten that a new point opened, given the points each block holds now.
- * Without it a block that opened for a new point would fold again by itself once that point is gone. The selection
- * itself when no fold is forgotten.
+ * Whether `block` is drawn folded: every block on top starts folded, its head saying what it holds, and stays open from
+ * the user's opening to their folding, over every refresh. Nothing new opens it by itself.
  */
-export const settledBlockFolds = (
-  selection: Selection,
-  keysOf: Readonly<Record<TopBlockId, readonly string[]>>,
-): Selection => {
-  const folds = selection.blockFolds ?? {}
-  const opened = Object.values(TOP_BLOCK).filter(
-    (block) => folds[block] !== undefined && !isBlockFolded(selection, block, keysOf[block]),
-  )
-  if (opened.length === 0) return selection
-  const kept = Object.fromEntries(Object.entries(folds).filter(([block]) => !opened.includes(block as TopBlockId)))
-  const { blockFolds: _forgotten, ...rest } = selection
-  return Object.keys(kept).length > 0 ? { ...rest, blockFolds: kept } : rest
+export const isBlockFolded = ({ openBlocks }: Selection, block: TopBlockId): boolean => !openBlocks?.has(block)
+
+/** The selection with `block` opened when it was folded, and folded when it was open. */
+export const toggledBlockFold = (selection: Selection, block: TopBlockId): Selection => {
+  const open = new Set(selection.openBlocks)
+  if (open.has(block)) open.delete(block)
+  else open.add(block)
+  return { ...selection, openBlocks: open }
 }
 
-/** The selection with `block` folded over the points `keys` when it was open, and open when it was folded. */
-export const toggledBlockFold = (selection: Selection, block: TopBlockId, keys: readonly string[]): Selection => {
-  if (!isBlockFolded(selection, block, keys)) {
-    return { ...selection, blockFolds: { ...selection.blockFolds, [block]: new Set(keys) } }
-  }
-  const { blockFolds, ...rest } = selection
-  const { [block]: _folded, ...otherFolds } = blockFolds ?? {}
-  return Object.keys(otherFolds).length > 0 ? { ...rest, blockFolds: otherFolds } : rest
-}
+const withBlockOpen = (selection: Selection, block: TopBlockId, open: boolean): Selection =>
+  isBlockFolded(selection, block) === !open ? selection : toggledBlockFold(selection, block)
 
 const expand = (selection: Selection, keys: readonly string[]): Selection =>
-  changeSelected(selection, keys, opened, addWithPhase)
+  changeSelected(selection, keys, opened, addKey)
 
 const collapse = (selection: Selection, keys: readonly string[]): Selection =>
   changeSelected(selection, keys, closed, removeKey)
 
-/**
- * The line for a press of `a` that changes nothing on screen, null for any other input. The key lists the ticked
- * tasks inside an expanded phase, so it needs one among the `keys` drawn.
- */
-export const showDoneNotice = (selection: Selection, input: string, keys: readonly string[]): string | null => {
-  if (!isInput(INPUT.showDone, input)) return null
-  const phaseOpen = keys.some((key) => isPhaseKey(key) && selection.expanded.has(key))
-  return phaseOpen ? null : TEXTS.showDoneNeedsPhase
-}
-
 export const applyKey = (selection: Selection, input: string, keys: readonly string[]): Selection => {
   if (isInput(INPUT.up, input)) return move(selection, keys, -1)
   if (isInput(INPUT.down, input)) return move(selection, keys, 1)
   if (isInput(INPUT.toggle, input)) return toggle(selection, keys)
   if (isInput(INPUT.expand, input)) return expand(selection, keys)
   if (isInput(INPUT.collapse, input)) return collapse(selection, keys)
-  if (isInput(INPUT.showDone, input)) return { ...selection, showDone: !selection.showDone }
   if (isInput(INPUT.legend, input)) return { ...selection, showLegend: !selection.showLegend }
+  if (isInput(INPUT.closeLegend, input) && selection.showLegend) return { ...selection, showLegend: false }
   return selection
 }
 
@@ -353,7 +385,8 @@ const clicked = (mouse: MouseEvent, view: View, { targets, headerRows }: InputCo
 
 /**
  * Applies one key or mouse report. Wheel and page keys move the window and stop it following the
- * cursor; everything that changes the selection makes it follow again.
+ * cursor; everything that changes the selection makes it follow again, except opening the help, which
+ * starts at its top.
  */
 export const applyInput = (view: View, input: string, context: InputContext): View => {
   const mouse = parseMouse(input)
@@ -363,7 +396,9 @@ export const applyInput = (view: View, input: string, context: InputContext): Vi
   if (mouse)
     return key && !isChipKey(key) ? { ...view, selection: applyClick(view.selection, key), follow: true } : view
   const selection = applyKey(view.selection, input, context.keys)
-  return selection === view.selection ? view : { ...view, selection, follow: true }
+  if (selection === view.selection) return view
+  if (selection.showLegend && !view.selection.showLegend) return { ...view, selection, top: 0, follow: false }
+  return { ...view, selection, follow: true }
 }
 
 /** The row an input acts on: enter, space or right on the selected row, or a left click; null for anything else. */

package/src/plans/sent-files.ts

@@ -31,7 +31,7 @@ const isAddress = (file: string): boolean => file.startsWith('https://')
 const addressOf = (file: string): string =>
   isAddress(file) ? file : `file://${file.split('/').map(encodeURIComponent).join('/')}`
 
-/** What a badge or a for-you row shows of a file, without the control characters a hand-written record may carry. */
+/** What a badge or a row of "Your turn" shows of a file, without the control characters a hand-written record may carry. */
 const labelOf = (file: string, caption: string | null): string =>
   terminalSafe(isAddress(file) ? (caption ?? 'artifact') : basename(file))
 

package/src/plans/settings.ts

@@ -14,19 +14,21 @@ export type PlansSettings = Pick<
 > & {
   adapter: JackherdConfig['terminal']['adapter']
   fetchIntervalMinutes: number
+  /** Whether the running task of a folded lane shimmers; `NO_COLOR` keeps it still whatever this says. */
+  shimmer: boolean
   linkKinds: JackherdConfig['plans']['linkKinds']
   context: JackherdConfig['plans']['context']
   /** The `watch.sources` marked `ticket`, whose entries the view shows as badges. */
   ticketSources: TicketSource[]
   /** The other `watch.sources` by name, with the tone each names for a new report; the herd lists them in a block of their own. */
   herdSources: { name: string; tone: ToneName | null }[]
-  /** By source name: what the herd puts before a row of "Waiting for you" that came from the source, its `label` or else its name. */
+  /** By source name: what the herd puts before a row of "Your turn" that came from the source, its `label` or else its name. */
   sourceLabels: Record<string, string>
   /** The tone of each role in the herd. */
   tones: JackherdConfig['plans']['tones']
 }
 
-/** The locale of the herd's clock: the herd is English, with a 24-hour clock. */
+/** The locale of the times the herd writes (the refresh error, the last fetch): English, with a 24-hour clock. */
 export const CLOCK_LOCALE = 'en-GB'
 
 /** The herd's slice of a validated config. */
@@ -40,6 +42,7 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   skillPrefix: config.skillPrefix,
   adapter: config.terminal.adapter,
   fetchIntervalMinutes: config.plans.fetchIntervalMinutes,
+  shimmer: config.plans.shimmer,
   linkKinds: config.plans.linkKinds,
   context: config.plans.context,
   ticketSources: config.watch.sources.flatMap(({ name, lane, ticket }) =>

package/src/plans/shimmer.ts

@@ -0,0 +1,124 @@
+import { ESC, stripAnsi } from '../terminal/text'
+
+/** A line of the frame that shimmers, by its row on the terminal (1-based) and its text with the marks in it. */
+export type ShimmerRow = { row: number; line: string }
+
+/**
+ * The marks around a text that shimmers: SGR 5 and 25 (blink on, off), which nothing else in the herd writes.
+ * `shimmerAt` turns them into the stripe of the moment, so no line reaches the terminal with them.
+ */
+const MARK = { open: `${ESC}[5m`, close: `${ESC}[25m` } as const
+const MARKED = new RegExp(`${ESC}\\[5m([^${ESC}]*)${ESC}\\[25m`, 'g')
+const LONE_MARK = new RegExp(`${ESC}\\[2?5m`, 'g')
+const DEFAULT_FOREGROUND = `${ESC}[39m`
+
+type Rgb = readonly [number, number, number]
+
+/**
+ * The stripe is drawn `framesPerSecond` times a second; its middle glides `cellsPerSecond`, and it lifts the cells
+ * within `reachCells` of it in a soft bell from the teal `base` the whole text stands in to the light teal `peak`.
+ * After the stripe left the longest text on screen every row rests `pauseMs`, then all start again together.
+ */
+export const SHIMMER = {
+  framesPerSecond: 30,
+  cellsPerSecond: 20,
+  pauseMs: 600,
+  reachCells: 4.5,
+  base: [80, 180, 170] as Rgb,
+  peak: [175, 240, 232] as Rgb,
+} as const
+
+/** The width of the bell: at `reachCells` from its middle a cell keeps 5 % of the lift. */
+const BELL_WIDTH = SHIMMER.reachCells / Math.sqrt(3)
+/** The six levels of each channel in the colour cube of the 256 colours, which starts at index 16. */
+const CUBE_LEVELS: readonly number[] = [0, 95, 135, 175, 215, 255]
+const CUBE_FIRST = 16
+
+const nearestLevel = (value: number): number => {
+  const distances = CUBE_LEVELS.map((level) => Math.abs(level - value))
+  return distances.indexOf(Math.min(...distances))
+}
+
+/** The colour of the 256 nearest to `rgb`, channel by channel in the colour cube. */
+const cubeIndex = ([red, green, blue]: Rgb): number =>
+  CUBE_FIRST + 36 * nearestLevel(red) + 6 * nearestLevel(green) + nearestLevel(blue)
+
+const colourCode = (rgb: Rgb, trueColour: boolean): string =>
+  trueColour ? `38;2;${rgb[0]};${rgb[1]};${rgb[2]}` : `38;5;${cubeIndex(rgb)}`
+
+export const isTrueColour = (env: Record<string, string | undefined>): boolean =>
+  env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit'
+
+const TRUE_COLOUR = isTrueColour(process.env)
+
+/** `text` marked to shimmer, as plain text: styling of its own would stop the marks from pairing. */
+export const shimmering = (text: string): string => `${MARK.open}${stripAnsi(text)}${MARK.close}`
+
+/**
+ * `text` as plain text in the teal the shimmer rests in, the default foreground after it: a running task while the
+ * herd does not shimmer (`plans.shimmer: false`, `NO_COLOR`, `--once`). Only the foreground, so a focus background stays.
+ */
+export const stillTeal = (text: string, trueColour = TRUE_COLOUR): string =>
+  `${ESC}[${colourCode(SHIMMER.base, trueColour)}m${stripAnsi(text)}${DEFAULT_FOREGROUND}`
+
+export const hasShimmer = (line: string): boolean => line.includes(MARK.open)
+
+/** The characters of the longest marked text in `lines`, 0 without one: it sets the pass of every row. */
+export const longestShimmer = (lines: readonly string[]): number =>
+  Math.max(0, ...lines.flatMap((line) => [...line.matchAll(MARKED)].map((match) => [...(match[1] ?? '')].length)))
+
+/** One pass of the stripe over a longest text of `longest` characters, in and out of it, and the rest after it. */
+export const shimmerCycleMs = (longest: number): number =>
+  ((longest + 2 * SHIMMER.reachCells) / SHIMMER.cellsPerSecond) * 1000 + SHIMMER.pauseMs
+
+/** The middle of the stripe at `now` (epoch milliseconds) as a fraction of cells, negative before the text. */
+const stripeMiddle = (now: number, longest: number): number =>
+  ((now % shimmerCycleMs(longest)) * SHIMMER.cellsPerSecond) / 1000 - SHIMMER.reachCells
+
+/** The foreground of a cell `distance` cells from the middle: the teal lifted along the bell towards the peak. */
+const shadeCode = (distance: number, trueColour: boolean): string => {
+  const weight = Math.exp(-((distance / BELL_WIDTH) ** 2))
+  const channel = (index: 0 | 1 | 2) =>
+    Math.round(SHIMMER.base[index] + (SHIMMER.peak[index] - SHIMMER.base[index]) * weight)
+  return colourCode([channel(0), channel(1), channel(2)], trueColour)
+}
+
+/**
+ * `text` in teal, each character within reach of `middle` in the shade its distance gives, the default foreground
+ * after it; the characters out of reach are written in one run, so a long text costs no more than a short one.
+ */
+const striped = (text: string, middle: number, trueColour: boolean): string => {
+  const characters = [...text]
+  const base = colourCode(SHIMMER.base, trueColour)
+  const from = Math.max(Math.floor(middle - SHIMMER.reachCells), 0)
+  const to = Math.min(Math.ceil(middle + SHIMMER.reachCells), characters.length)
+  if (to <= from) return `${ESC}[${base}m${text}${DEFAULT_FOREGROUND}`
+  let stripe = ''
+  let current = base
+  for (let index = from; index < to; index++) {
+    const code = shadeCode(index + 0.5 - middle, trueColour)
+    if (code !== current) stripe += `${ESC}[${code}m`
+    current = code
+    stripe += characters[index]
+  }
+  const rest = characters.slice(to).join('')
+  const after = rest && current !== base ? `${ESC}[${base}m${rest}` : rest
+  return `${ESC}[${base}m${characters.slice(0, from).join('')}${stripe}${after}${DEFAULT_FOREGROUND}`
+}
+
+/**
+ * `line` as drawn at `now`: each marked text with the stripe of the moment, the marks gone, a mark left alone by a cut
+ * too. `longest` is `longestShimmer` over the frame, so every row starts and rests together.
+ */
+export const shimmerAt = (line: string, now: number, longest: number, trueColour = TRUE_COLOUR): string =>
+  line
+    .replace(MARKED, (_marked, text: string) => striped(text, stripeMiddle(now, longest), trueColour))
+    .replace(LONE_MARK, '')
+
+/** The lines of a frame that shimmer, by their row on the terminal; `lines` start at the top row. */
+export const shimmerRows = (lines: readonly string[]): ShimmerRow[] =>
+  lines.flatMap((line, index) => (hasShimmer(line) ? [{ row: index + 1, line }] : []))
+
+/** Whether running tasks shimmer: while the config's `plans.shimmer` allows it, not with `NO_COLOR` set to a value (no-color.org). */
+export const shimmerEnabled = (configured: boolean, env: Record<string, string | undefined>): boolean =>
+  configured && !env.NO_COLOR

package/src/plans/signals-read.ts

@@ -39,6 +39,22 @@ const recentSessionLogs = (project: string, notOlderThan: number): string[] => {
   }
 }
 
+/** One read of the signals: the recent logs, how one is read, and what ends the read (the cache cleaned, the records added). */
+const signalRound = ({ projects, root, worktrees }: SignalSource, now: number, cache: StatCache<TaskSignal[]>) => {
+  const notOlderThan = now - STALE_ACTIVITY_MINUTES * MS_PER_MINUTE
+  const round: SignalCache = { entries: cache, used: new Set<string>() }
+  return {
+    paths: [root, ...subdirectories(worktrees)].flatMap((directory) =>
+      recentSessionLogs(join(projects, projectDirectoryOf(directory)), notOlderThan),
+    ),
+    read: (path: string) => readClaudeSignals(path, { notOlderThan, cache: round }),
+    finish: (claude: TaskSignal[]): TaskSignal[] => {
+      dropUnused(round.entries, round.used)
+      return [...claude, ...recordSignals(readTaskRecords(root))]
+    },
+  }
+}
+
 /**
  * What agents report doing, as `TaskSignal`s: the tasks in progress in the recent Claude Code sessions of the main
  * checkout (the coordinator and its subagents) and of every worktree, and the open `jh task` records. Which lane a
@@ -46,17 +62,29 @@ const recentSessionLogs = (project: string, notOlderThan: number): string[] => {
  * log whose modification time and size did not change; logs this call did not look at are dropped from it.
  */
 export const readAllSignals = (
-  { projects, root, worktrees }: SignalSource,
+  source: SignalSource,
   now: number,
   cache: StatCache<TaskSignal[]> = new Map(),
 ): TaskSignal[] => {
-  const notOlderThan = now - STALE_ACTIVITY_MINUTES * MS_PER_MINUTE
-  const round: SignalCache = { entries: cache, used: new Set<string>() }
-  const claude = [root, ...subdirectories(worktrees)].flatMap((directory) =>
-    recentSessionLogs(join(projects, projectDirectoryOf(directory)), notOlderThan).flatMap((path) =>
-      readClaudeSignals(path, { notOlderThan, cache: round }),
-    ),
-  )
-  dropUnused(round.entries, round.used)
-  return [...claude, ...recordSignals(readTaskRecords(root))]
+  const round = signalRound(source, now, cache)
+  return round.finish(round.paths.flatMap(round.read))
+}
+
+/**
+ * `readAllSignals` with `pass` awaited before each log is parsed, so a gate (`createSliceGate`) can hand the event
+ * loop back between them; the result and the cache are the same.
+ */
+export const readAllSignalsSliced = async (
+  source: SignalSource,
+  now: number,
+  cache: StatCache<TaskSignal[]>,
+  pass: () => Promise<void>,
+): Promise<TaskSignal[]> => {
+  const round = signalRound(source, now, cache)
+  const claude: TaskSignal[] = []
+  for (const path of round.paths) {
+    await pass()
+    claude.push(...round.read(path))
+  }
+  return round.finish(claude)
 }

package/src/plans/slice-gate.ts

@@ -0,0 +1,51 @@
+/** Where the gate hands the event loop back and what it times the slices with; `setImmediate` and `performance.now`. */
+export type SliceLoop = { schedule: (turn: () => void) => void; clock: () => number }
+
+/** A gate that cuts long synchronous work into slices of the event loop. */
+export type SliceGate = { pass: () => Promise<void> }
+
+const SYSTEM_LOOP: SliceLoop = { schedule: (turn) => setImmediate(turn), clock: () => performance.now() }
+
+/**
+ * A gate the steps of a read pass before each piece of synchronous work. While the current slice is shorter than
+ * `budgetMs` a step passes at once; after that the gate hands the loop back (keys, mouse and drawing come first) and
+ * lets the waiting steps through in the order they asked, one at a time, each after the one before it reached its
+ * next `await`, as long as the new slice has time. Steps that run side by side (`Promise.all` over the lanes) thus
+ * take turns instead of running their synchronous parts back to back in one block.
+ */
+export const createSliceGate = (budgetMs: number, loop: SliceLoop = SYSTEM_LOOP): SliceGate => {
+  const waiting: (() => void)[] = []
+  let sliceStart = loop.clock()
+  let scheduled = false
+  const hasTime = () => loop.clock() - sliceStart < budgetMs
+
+  const scheduleTurn = () => {
+    if (scheduled) return
+    scheduled = true
+    loop.schedule(() => {
+      scheduled = false
+      sliceStart = loop.clock()
+      releaseNext()
+    })
+  }
+
+  const releaseNext = () => {
+    const next = waiting.shift()
+    if (!next) return
+    next()
+    void Promise.resolve().then(() => {
+      if (waiting.length === 0) return
+      if (hasTime()) releaseNext()
+      else scheduleTurn()
+    })
+  }
+
+  const pass = (): Promise<void> => {
+    if (waiting.length === 0 && !scheduled && hasTime()) return Promise.resolve()
+    const passed = new Promise<void>((resolve) => waiting.push(resolve))
+    scheduleTurn()
+    return passed
+  }
+
+  return { pass }
+}