cache-band

  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
    if (e.props.hasSurvey) return next(e)
    const view = (await read($, viewAtom)) ?? EMPTY
    // A new session, before its first reply: nothing is cached yet. The band
    // shows from the start anyway, so the toggles can be set before then.
    const isFresh = view.lastUsedAt === 0 || view.ctxTokens === 0

    const [isCompacting, warmth] = await Promise.all([read($, compactingAtom), read($, warmthAtom)])
    const below = await next(e)
    const table = $.ui.resolve(e)
    const { Box, Text, Button } = table
    // The terminal has no Svg (its table hands one out that draws nothing), so
    // it keeps the meter of block characters and words for the toggles.
    const Svg = e.surface !== 'terminal' && 'Svg' in table ? table.Svg : undefined

    const isWorking = e.props.isWorking
    const t = temperatureOf(isWorking ? 0 : isFresh ? TTL_MS : Math.max(0, view.now - view.lastUsedAt))
    const isEmpty = isFresh && !isWorking
    const isCold = t.leftMs === 0
    const { filled, empty } = meterOf(t.leftMs / TTL_MS)
    const size = tokens(view.ctxTokens)
    const untilAct = t.leftMs - LEAD_MS
    const soon = untilAct < 60_000 ? '<1m' : span(untilAct)
    const status = isWorking
      ? 'in use'
      : isEmpty
        ? 'no cache yet'
        : isCold
          ? `next message rewrites ${size}`
          : warmth.isPinging
            ? 'pinging…'
            : willPing(warmth)
              ? `ping in ${soon}`
              : `cold in ${span(t.leftMs)}`

    // The cells each layout takes in one row, with the longest status.
    const columns = e.props.bodyColumns
    const cacheCells =
      (Svg ? pxCells(GAUGE_ICON + 105) : CELLS) + 1 + textCells('cooling') + 1 + textCells(`· next message rewrites ${size}`)
    const named = (name: string) => (Svg ? ICON_BUTTON + 1 + textCells(name) : textCells(`☐ ${name}`)) + PAD
    const togglesFull = named('Auto cache') + 2 + named('Auto compact')
    const togglesShort = Svg ? ICON_BUTTON + 1 + ICON_BUTTON : togglesFull
    const compactCells = textCells('Compact') + PAD
    const fullCells = Math.ceil(textCells('Cache') + 1 + cacheCells + 3 + togglesFull + 2 + compactCells)
    const mediumCells = Math.ceil(cacheCells + 3 + togglesShort + 2 + compactCells)
    const layout = columns >= fullCells ? 'full' : columns >= mediumCells || !Svg ? 'medium' : 'icons'
    const isFull = layout === 'full'
    const isIcons = layout === 'icons'
    const bar = isIcons && columns < TINY ? 64 : 105
    // A terminal narrower still keeps the cold status short.
    const shownStatus = !Svg && columns < mediumCells && isCold && !isEmpty ? 'full rewrite next' : status

    // A card that opens while the pointer is over the keyed Box around it; the
    // first of several lines is its heading.
    const card = (...lines: string[]) => (
      <Box
        position="absolute"
        top={-4}
        left={0}
        display="none"
        hover={{ display: 'flex' }}
        flexDirection="column"
        rowGap={1}
        borderStyle="round"
        borderColor="subtle"
        backgroundColor="background"
        paddingX={1}
      >
        {lines.map((line, i) => (
          <Text bold={isIcons && i === 0 && lines.length > 2}>{line}</Text>
        ))}
      </Box>
    )

    // A picture a person presses: a blank button laid over it and centered on
    // it takes the click, and its hover frames the picture.
    const pressable = (key: string, picture: RenderElement, onPress: () => void, tip?: string) => (
      <Box key={`${key}-box`} position="relative" flexDirection="row" alignItems="center" flexShrink={0}>
        {picture}
        <Box
          position="absolute"
          top={0}
          left={0}
          right={0}
          height="100%"
          flexDirection="row"
          alignItems="center"
          justifyContent="center"
        >
          <Button key={key} label={ICON_BLANK} plain onPress={onPress} />
        </Box>
        {tip !== undefined && card(tip)}
      </Box>
    )

    // A toggle: its glowing icon, named beside it when the band has room and
    // in a hover card when it hasn't. The terminal gets a box and its name.
    const toggle = (key: string, name: string, isOn: boolean, svg: (isOn: boolean) => string, does: string, onPress: () => void) => {
      if (!Svg) {
        return <Button key={key} label={`${isOn ? '☑' : '☐'} ${name}`} plain dimColor={!isOn} onPress={onPress} />
      }
      const state = `${name} ${isOn ? 'on' : 'off'}`
      const icon = pressable(
        key,
        <Svg source={svg(isOn)} alt={state} width={18} height={18} />,
        onPress,
        isFull ? undefined : `${state}: ${does}`,
      )
      if (!isFull) return icon

      return (
        <Box key={`${key}-named`} flexDirection="row" alignItems="center" columnGap={1} flexShrink={0}>
          {icon}
          <Button key={`${key}-name`} label={name} plain dimColor={!isOn} onPress={onPress} />
        </Box>
      )
    }

    // Each piece keeps its size; nothing wraps mid-phrase.
    const gauge = Svg ? (
      <Box flexShrink={0}>
        <Svg
          source={gaugeSvg(t.word, t.leftMs / TTL_MS, bar)}
          alt={isEmpty ? 'No cache yet' : isCold ? 'Cache cold' : `Cache ${t.word}, ${span(t.leftMs)} left`}
          width={GAUGE_ICON + bar}
          height={16}
        />
      </Box>
    ) : (
      <Box flexDirection="row" flexShrink={0}>
        <Text color={t.tone}>{filled}</Text>
        <Text color="rate_limit_empty">{empty}</Text>
      </Box>
    )

    const about = [
      (isEmpty
        ? `Claude starts caching this conversation with your first message, and keeps it for an hour after ` +
          `it last used it.`
        : `Claude keeps this conversation cached for an hour after it last used it.`) +
        ` While it's warm, each message re-reads it from the cache, which costs far less. Once it's cold, ` +
        `the next message writes it all into the cache again` +
        (isEmpty ? '.' : ` (${size} tokens now).`) +
        ` Compact shrinks the conversation, so both cost less.`,
      `Auto cache pings a background copy of the conversation 10 minutes before the cache would go cold, ` +
        `which keeps it hot without adding anything to the chat. A ping costs about a twentieth of a ` +
        `rewrite, so it stops after ${MAX_PINGS} in a row (about 16 hours away) and starts again when you ` +
        `send a message.` +
        (warmth.pings > 0 ? ` Pinged ${warmth.pings}× since your last message.` : ''),
      `Auto compact compacts the conversation once it passes ${tokens(AUTO_COMPACT_AT)} tokens, right ` +
        `after Claude's reply. Past that size every message costs more and Claude misses more of what's ` +
        `in it; Claude Code's own auto-compact would wait until about 830k.`,
    ]
    const word = t.word.charAt(0).toUpperCase() + t.word.slice(1)

    const cache = (
      <Box key="cache" flexDirection="row" alignItems="center" columnGap={1} flexShrink={0}>
        {isFull && (
          <Text dimColor wrap="truncate">
            Cache