clauderipple 0.8.9 → 0.9.0

package/dist/mod/hooks/ui/kit.tsx

@@ -0,0 +1,258 @@
+// The desktop's capsules and drawn controls, put together: a picture from art.ts, the host's text in
+// our own colours beside it, and a blank native button laid over both to take the press. Desktop and
+// the editor only (an Svg in the table); the terminal keeps the text controls of parts.tsx.
+//
+// Host facts this is built on (2026-10):
+// - A Box drawn `position: "absolute"` is painted over every sibling that is not itself positioned,
+//   whatever comes after it in the tree (CSS stacking). The 2026-10-12 surfaces put their backdrop in
+//   such a Box and their words in plain ones: in the app the backdrop hid the panel's title, its ×
+//   and every row's name, and only the controls with a press laid over them showed. The app does
+//   not take `position: "relative"` from a Box either: it positions a Box only when one of its own
+//   children is absolute. So a capsule paints its sea first, absolute, and holds everything else in
+//   one layer after it that starts with an empty absolute Box (`lift`), which makes it positioned.
+// - A blank button's label is no-break spaces (U+00A0): the host sets a button's label
+//   `white-space: nowrap`, which would fold ordinary spaces into one. It is sized a little short of
+//   the drawing (an ellipsis would show) and sits in an absolute Box over the control, clipped to it.
+// - A plain Button's label takes the host's ink, which a dark capsule would swallow; nothing on a
+//   capsule is a labelled host Button. A keyed Box's `hover` lights a control on our own terms.
+
+import type { RenderNode } from 'claude-code'
+
+import { rippleSource } from './parts'
+import type { Els } from './parts'
+import type { Face } from './ripple'
+import type { Frame } from './view'
+import { CELL_PX, CLOSE_PX, INK, ROW_PX, SUB, SWITCH_H, SWITCH_W, WELL_PX, closeArt, labelPx, pillArt, seaArt, segmentedArt, sliderArt, switchArt, wellArt } from './art'
+import type { Glyph, PillLook, Sea, Tone } from './art'
+import { chOf } from './theme'
+
+/** Width of one U+00A0 in the host's 12 px button font, px, taken a little wide. */
+const NBSP_PX = 3.6
+/** The host's padding either side of a plain Button's label, px. */
+const BUTTON_PAD = 6
+/** The capsule's edge: a warm grey that reads against a light page and a dark one alike. */
+const EDGE = 'rgba(128,124,116,0.55)'
+/** A control under the pointer: a soft light on the water. */
+const HOVER = 'rgba(255,255,255,0.09)'
+const HOVER_EDGE = 'rgba(255,255,255,0.16)'
+/** A drawn control's height, px: pills, segments. */
+const CONTROL_PX = 26
+
+/** Cells a run of px takes, rounded up. */
+function cellsOf(px: number): number {
+  return Math.ceil(px / CELL_PX)
+}
+
+/** Rows a run of px takes, unrounded (the host takes fractions of a row). */
+export function rowsOf(px: number): number {
+  return Math.round((px / ROW_PX) * 1000) / 1000
+}
+
+/** A no-break space, spelled by its code: the bare character is invisible in source and was once lost. */
+const NBSP = String.fromCharCode(0xa0)
+
+/** A blank label as wide as a button over `px` should be. */
+export function blank(px: number): string {
+  return NBSP.repeat(Math.max(1, Math.floor((px - BUTTON_PAD * 2) / NBSP_PX)))
+}
+
+/** The blank button over a control `px` wide: last child of a `position: relative` Box. */
+export function press(el: Els, key: string, px: number, onPress: () => void): RenderNode {
+  const { Box, Button } = el
+  return (
+    <Box position="absolute" top={0} bottom={0} left={0} right={0} alignItems="center" justifyContent="center" overflow="hidden">
+      <Button key={key} plain label={blank(px)} onPress={() => onPress()} />
+    </Box>
+  )
+}
+
+/**
+ * An empty absolute Box: the first child of a Box that must paint above an absolute picture laid
+ * before it. The app does not take a Box's own `position: "relative"`; it positions a Box only
+ * when one of its children is absolute (seen 2026-10-13: every capsule's words, tiles and 리플이
+ * lay under the water, and only controls with a press laid over them showed).
+ */
+export function lift(el: Els): RenderNode {
+  const { Box } = el
+  return <Box position="absolute" top={0} left={0} />
+}
+
+/** A picture, `width` × `height` px, in a Box of its own that never shrinks. */
+export function pic(el: Els, key: string, source: string, alt: string, width: number, height: number): RenderNode {
+  if (!('Svg' in el)) return ''
+  const { Box, Svg } = el
+  return (
+    <Box key={'pic-' + key} flexShrink={0} alignItems="center">
+      <Svg source={source} alt={alt} width={width} height={height} />
+    </Box>
+  )
+}
+
+/**
+ * 리플이 on a capsule: its face drawn for the deep (the dark palette: light ink, lavender tone), a
+ * plain image in a Box of its own that never shrinks. `percent` fills a gauge face's ring.
+ */
+export function ripple(el: Els, key: string, face: Face, alt: string, size: number, percent?: number, dim = false): RenderNode {
+  if (!('Svg' in el)) return ''
+  const { Box, Svg } = el
+  return (
+    <Box key={'ripple-' + key} flexShrink={0}>
+      <Svg source={rippleSource(face, size, 'dark', percent, dim)} alt={alt} width={size} height={size} />
+    </Box>
+  )
+}
+
+/**
+ * A control that lights under the pointer: a keyed, positioned Box with a soft rounded light as its
+ * hover, holding what it shows and, last, its press. `scope` joins a hover group, so pointing at the
+ * control also shows what it does elsewhere (the band's tip).
+ */
+export function lit(el: Els, key: string, cells: number, children: RenderNode[], paddingX = 0.5, scope?: string): RenderNode {
+  const { Box } = el
+  return (
+    <Box key={'hv-' + key} position="relative" flexDirection="row" alignItems="center" columnGap={1} paddingX={paddingX} paddingY={0} width={cells} flexShrink={0} borderStyle="round" borderColor="rgba(0,0,0,0)" hover={{ backgroundColor: HOVER, borderColor: HOVER_EDGE, ...(scope ? { scope } : {}) }}>
+      {children}
+    </Box>
+  )
+}
+
+/**
+ * A capsule: a rounded Box edged in violet light, the deep (art.ts `seaArt`) painted behind it from
+ * its top left, and everything it holds in one positioned layer above the sea. `rows` is about how
+ * tall it draws; the sea is taken taller and wider than that, and the capsule clips it.
+ */
+export function capsule(el: Els, frame: Frame, c: { key: string; sea: Omit<Sea, 'at'> & { at?: Sea['at'] }; rows: number; paddingX?: number; paddingY?: number; gap?: number; children: RenderNode[] }): RenderNode {
+  const { Box } = el
+  const padX = c.paddingX ?? 1.5
+  const padY = c.paddingY ?? 0.5
+  const width = Math.max(40, frame.columns) * CELL_PX + 48
+  // Taken well past the estimate: a capsule taller than its sea would show the page beneath.
+  const visible = Math.round(c.rows * ROW_PX)
+  const height = visible + 220
+  const at = c.sea.at ?? { x: padX * CELL_PX + 12, y: padY * ROW_PX * 0.5 + 13 }
+  return (
+    <Box key={c.key} position="relative" flexDirection="column" borderStyle="round" borderColor={EDGE} paddingX={0} paddingY={0} overflow="hidden" width="100%" minWidth={0}>
+      <Box key={c.key + '-sea'} position="absolute" top={0} left={0}>
+        {pic(el, c.key + '-sea', seaArt(width, height, { ...c.sea, at, visible }), 'ClaudeRipple', width, height)}
+      </Box>
+      <Box key={c.key + '-layer'} position="relative" flexDirection="column" rowGap={c.gap ?? 0} paddingX={padX} paddingY={padY} width="100%" minWidth={0}>
+        {lift(el)}
+        {c.children}
+      </Box>
+    </Box>
+  )
+}
+
+/**
+ * A drawn button with its label in it: `primary` the one thing to press, `ghost` a quiet one. Its
+ * Box key starts `pill-` or `ghost-`, its press is `key`.
+ */
+export function pill(el: Els, key: string, label: string, look: PillLook, onPress: () => void, tone: Tone = 'violet', glyph?: Glyph): RenderNode {
+  const { Box } = el
+  const art = pillArt(label, look, tone, glyph)
+  return (
+    <Box key={(look === 'primary' ? 'pill-' : 'ghost-') + key} position="relative" width={art.cells} height={rowsOf(CONTROL_PX)} flexShrink={0} alignItems="center" justifyContent="center">
+      {pic(el, key, art.source, label, art.cells * CELL_PX, CONTROL_PX)}
+      {press(el, key, art.cells * CELL_PX, onPress)}
+    </Box>
+  )
+}
+
+/** Cells the way out takes. */
+export const CLOSE_CELLS = cellsOf(CLOSE_PX + 4)
+
+/** The way out: a soft disc with a ×, `label` its name for a reader that cannot see it. */
+export function closeButton(el: Els, key: string, label: string, onPress: () => void, scope?: string): RenderNode {
+  return lit(el, key, CLOSE_CELLS, [pic(el, key, closeArt(), label, CLOSE_PX, CLOSE_PX), press(el, key, CLOSE_CELLS * CELL_PX, onPress)], 0.25, scope)
+}
+
+/** Cells a switch and its word take, their hover's air included. */
+export function toggleCells(label: string): number {
+  return Math.ceil((SWITCH_W + CELL_PX + chOf(label) * CELL_PX * 1.1) / CELL_PX) + 1
+}
+
+/** A switch and its word (On / Off), the whole pressable; lit while on. */
+export function toggle(el: Els, key: string, on: boolean, label: string, onPress: () => void, busy = false, scope?: string): RenderNode {
+  const { Text } = el
+  const cells = toggleCells(label)
+  return lit(el, key, cells, [
+    pic(el, key, switchArt(on, busy), label, SWITCH_W, SWITCH_H),
+    <Text key={key + '-word'} color={on ? INK : SUB} bold={on}>{label}</Text>,
+    press(el, key, cells * CELL_PX, onPress),
+  ], 0.5, scope)
+}
+
+/**
+ * A field's well: a native field (Input) on a plate of the app's own page colour, light or dark as
+ * the app is (art.ts `wellArt`), so the host's own text colour reads in it on either theme. The
+ * field sits in a positioned layer above the plate.
+ */
+export function well(el: Els, key: string, cells: number, field: RenderNode, alt: string): RenderNode {
+  const { Box } = el
+  const w = cells * CELL_PX
+  return (
+    <Box key={'well-' + key} position="relative" flexDirection="row" alignItems="center" width={cells} flexShrink={1} minWidth={16} height={rowsOf(WELL_PX)} paddingX={1} overflow="hidden">
+      <Box position="absolute" top={0} left={0}>
+        {pic(el, 'well-' + key, wellArt(w, WELL_PX), alt, w, WELL_PX)}
+      </Box>
+      <Box key={'well-field-' + key} position="relative" flexGrow={1} flexShrink={1} minWidth={0}>
+        {lift(el)}
+        {field}
+      </Box>
+    </Box>
+  )
+}
+
+export type SegmentOption<T extends string> = { value: T; label: string }
+
+/** Each segment's cells: its label drawn at 12 px with air either side, at least five cells. */
+function segmentCells(labels: readonly string[]): number[] {
+  return labels.map(label => Math.max(5, Math.ceil((labelPx(label, 12) + 26) / CELL_PX)))
+}
+
+/**
+ * A segmented control drawn whole (art.ts), the chosen segment lit, each segment the press of its
+ * own option (`key-value`). `colors` lights the chosen one in its own colour (the efforts' depths).
+ */
+export function segmented<T extends string>(el: Els, key: string, options: readonly SegmentOption<T>[], value: T | null, onPick: (value: T) => void, tone: Tone = 'violet', colors?: readonly string[]): RenderNode {
+  const { Box } = el
+  const labels = options.map(o => o.label)
+  const cells = segmentCells(labels)
+  const total = cells.reduce((n, c) => n + c, 0)
+  const chosen = options.findIndex(o => o.value === value)
+  const alt = labels.map((label, i) => (i === chosen ? '[' + label + ']' : label)).join(' · ')
+  return (
+    <Box key={'seg-' + key} position="relative" flexDirection="row" width={total} height={rowsOf(CONTROL_PX)} flexShrink={0}>
+      <Box position="absolute" top={0} left={0}>
+        {pic(el, 'seg-' + key, segmentedArt(labels, cells, chosen, tone, colors), alt, total * CELL_PX, CONTROL_PX)}
+      </Box>
+      {options.map((o, i) => (
+        <Box key={'sg-' + key + '-' + o.value} position="relative" width={cells[i]} height={rowsOf(CONTROL_PX)} flexShrink={0}>
+          {press(el, key + '-' + o.value, cells[i]! * CELL_PX, () => onPick(o.value))}
+        </Box>
+      ))}
+    </Box>
+  )
+}
+
+/**
+ * A stepped slider: `values` as stops on one drawn track, the chosen one lit, each stop the press of
+ * an equal part of the track (`key-value`).
+ */
+export function slider<T extends string | number>(el: Els, key: string, values: readonly T[], value: T, onPick: (value: T) => void, cellsPerStop = 4): RenderNode {
+  const { Box } = el
+  const chosen = Math.max(0, values.indexOf(value))
+  const total = values.length * cellsPerStop
+  return (
+    <Box key={'sl-' + key} position="relative" flexDirection="row" width={total} height={rowsOf(CONTROL_PX)} flexShrink={0} alignItems="center">
+      <Box position="absolute" top={0} bottom={0} left={0} alignItems="center" justifyContent="center">
+        {pic(el, 'sl-' + key, sliderArt(values.length, cellsPerStop, chosen), String(value), total * CELL_PX, 22)}
+      </Box>
+      {values.map(v => (
+        <Box key={'st-' + key + '-' + v} position="relative" width={cellsPerStop} height={rowsOf(CONTROL_PX)} flexShrink={0}>
+          {press(el, key + '-' + v, cellsPerStop * CELL_PX, () => onPick(v))}
+        </Box>
+      ))}
+    </Box>
+  )
+}

package/dist/mod/hooks/ui/log.tsx

@@ -0,0 +1,109 @@
+// The request log pane: the router's records of model requests, newest first, one entry each with
+// what matters (model, provider, effort, tokens, cache, time, result). Moved here unchanged in
+// content from register.tsx's own drawing.
+
+import { t } from '../i18n'
+import type { RenderNode } from 'claude-code'
+
+import type { JudgeRun, StatusRequest } from '../../types'
+import { GREET_SIZE, action, actions as actions_, speak } from './parts'
+import type { Els } from './parts'
+import { cacheTone, providerColor, textTone } from './theme'
+import type { Frame, LogActions, LogView } from './view'
+import { cachePercent, clockTime, effortLabel, modelOf, promptTokens, seconds } from './view'
+
+function entry(el: Els, frame: Frame, record: StatusRequest, mineOnly: boolean): RenderNode {
+  const { Box, Text } = el
+  const tone = textTone(frame.appearance)
+  const cache = cachePercent(record.usage)
+  return (
+    <Box key={record.at + '-' + record.target} flexDirection="column">
+      <Box flexDirection="row" flexWrap="wrap" columnGap={1}>
+        {mineOnly ? null : (
+          <Text color={record.mine ? tone.accent : undefined} dimColor={!record.mine}>
+            {record.mine ? '●' : '○'}
+          </Text>
+        )}
+        <Text dimColor>{clockTime(record.at)}</Text>
+        <Text bold wrap="wrap">
+          {modelOf(record)}
+        </Text>
+        <Text color={providerColor(record.provider)}>{record.provider}</Text>
+        {record.resent ? (
+          <Text dimColor>{t(frame.lang, 'log.resent', { status: String(record.status) })}</Text>
+        ) : (
+          <Text color={record.ok ? tone.ok : tone.bad} bold={!record.ok}>
+            {record.ok ? '✓' : '✕ ' + String(record.status)}
+          </Text>
+        )}
+      </Box>
+      <Box flexDirection="row" flexWrap="wrap" columnGap={1}>
+        <Text dimColor>{record.effort ? effortLabel(record.effort, frame.lang) : '-'}</Text>
+        {record.usage ? <Text dimColor>{t(frame.lang, 'log.input', { tokens: tokens(promptTokens(record.usage)) })}</Text> : null}
+        {cache !== undefined ? <Text color={tone[cacheTone(cache)]}>{t(frame.lang, 'band.cachePercent', { percent: cache })}</Text> : null}
+        {record.usage ? <Text dimColor>{t(frame.lang, 'log.output', { tokens: tokens(record.usage.output) })}</Text> : null}
+        <Text dimColor>{seconds(record.ms / 1000, frame.lang)}</Text>
+      </Box>
+      {!record.ok && record.note ? (
+        <Text color={record.resent ? undefined : tone.bad} dimColor={record.resent} wrap="wrap">
+          {record.note}
+        </Text>
+      ) : null}
+    </Box>
+  )
+}
+
+const JUDGE_NAME = { haiku: 'settings.haiku', jev: 'settings.jev', model: 'agents.routerModel' } as const
+
+/** A verdict of this session's judge: who answered, in how long, what it chose, or why it fell back. */
+function judgeEntry(el: Els, frame: Frame, run: JudgeRun): RenderNode {
+  const { Box, Text } = el
+  const tone = textTone(frame.appearance)
+  const fell = run.by !== run.asked
+  const who = fell ? t(frame.lang, 'log.judgeFell', { asked: t(frame.lang, JUDGE_NAME[run.asked]), by: t(frame.lang, JUDGE_NAME[run.by]) }) : t(frame.lang, JUDGE_NAME[run.by])
+  const verdict = run.effort ? effortLabel(run.effort, frame.lang) + (run.sure !== undefined ? ' · ' + t(frame.lang, 'log.sure', { percent: Math.round(run.sure * 100) }) : '') : t(frame.lang, 'toasts.noVerdict')
+  return (
+    <Box key={'judge-' + run.at} flexDirection="column">
+      <Box flexDirection="row" flexWrap="wrap" columnGap={1}>
+        <Text dimColor>{clockTime(run.at)}</Text>
+        <Text bold>{t(frame.lang, run.for === 'worker' ? 'log.judgeWorker' : 'log.judge')}</Text>
+        <Text color={fell ? tone.warn : tone.accent}>{who}</Text>
+        <Text dimColor>{'→ ' + verdict}</Text>
+        <Text dimColor>{seconds(run.ms / 1000, frame.lang)}</Text>
+      </Box>
+      {run.error ? (
+        <Text color={tone.warn} wrap="wrap">
+          {run.error}
+        </Text>
+      ) : null}
+    </Box>
+  )
+}
+
+/** The log pane body: this session's verdicts in time order among its requests. */
+export function renderLog(el: Els, frame: Frame, view: LogView, actions: LogActions): RenderNode {
+  const { Box, Text } = el
+  const judges = view.mineOnly ? (view.judges ?? []) : []
+  const items = [...view.rows.map(record => ({ at: Date.parse(record.at), node: () => entry(el, frame, record, view.mineOnly) })), ...judges.map(run => ({ at: run.at, node: () => judgeEntry(el, frame, run) }))].sort((a, b) => b.at - a.at)
+  const scopeName = view.mineOnly ? t(frame.lang, 'log.thisSession') : t(frame.lang, 'log.allSessions')
+  const scope = action(el, frame, 'scope', view.mineOnly ? t(frame.lang, 'log.showAll') : t(frame.lang, 'log.onlySession'), actions.toggleScope, { hotkey: 'a' })
+  const legend = !view.mineOnly ? <Text key="legend" dimColor wrap="wrap">{t(frame.lang, 'log.legend')}</Text> : ''
+  // Empty, the pane has nothing to redraw it, so 리플이 can live out its idle loops here; with
+  // requests every poll redraws it and would start its motion over, so the list has no picture.
+  if (items.length === 0) return speak(el, frame, { key: 'log', face: 'calm', size: GREET_SIZE, title: scopeName, line: t(frame.lang, 'log.empty'), blocks: [legend, actions_(el, frame, [scope])] })
+  return (
+    <Box flexDirection="column" gap={1} width="100%">
+      <Box flexDirection="row" flexWrap="wrap" alignItems="center" columnGap={2}>
+        <Text bold>{scopeName}</Text>
+        {scope}
+      </Box>
+      {legend}
+      {items.map(item => item.node())}
+    </Box>
+  )
+}
+
+// The log keeps one decimal at every size (12.3k), as it always has.
+function tokens(n: number): string {
+  return n >= 1_000_000 ? (n / 1_000_000).toFixed(1) + 'M' : n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n)
+}

package/dist/mod/hooks/ui/parts.tsx

@@ -0,0 +1,217 @@
+// The pieces every drawing is made of: the element table, 리플이, the way it speaks (its face on
+// the left, what it says in one column beside it), and the controls of the cards and panels.
+//
+// These are the terminal's pieces and 리플이 everywhere; the desktop's drawn surfaces and controls
+// (2026-10-12) are art.ts and kit.tsx, which build on the facts below.
+// Engine and host facts (Claude Code 2.1.293, the desktop app's assets, 2026-10-10):
+// - The desktop draws every answer as a new DOM tree, each Svg a new element. What blinked was the
+//   interactive Svg: isInteractive makes it a sandboxed <iframe srcdoc>, which the host rebuilds
+//   blank on every redraw. A plain Svg is an <img> of a data URL; it does not blink across
+//   redraws, and CSS @keyframes inside the SVG run in it (seen in the owner's desktop app on
+//   2026-10-11 at commit 8d43b97: 리플이 moving in the band and the quick settings with no
+//   flicker; Effortless animates its band the same way). So 리플이 is always a plain image, never
+//   interactive. A redraw still starts its motion over, so every loop opens on a natural pose
+//   (ripple.ts).
+// - A Button's label is text only and its colours are the host's. A drawn control takes its press
+//   from a blank native button laid over it, and that blank label has to be sized a little short
+//   of the drawing and made of no-break spaces, or the host cuts it to an ellipsis or folds it to
+//   nothing (seen 2026-10-10 as "자동 (권장) …"); kit.tsx `blank` does both.
+// - A plain Button under the pointer turns full ink on a ghost fill, dimmed or not, so a state told
+//   by dimness alone looks the same on and off right after the click. A chosen option therefore
+//   says so in its shape: ● chosen, ○ not (the terminal's marks too), the unchosen also dimmed.
+// - `role="dismiss"` is drawn by the desktop as its native close control at the site's trailing
+//   edge (the band's × is one), the label its accessible name; the terminal draws a Button.
+// - An Svg needs alt, width and height (an interactive one without both falls back to ~300×150).
+//   Its CSS animations run without isInteractive (the 2026-10-10 reading that they need it was
+//   wrong); what isInteractive adds is the frame, and with it the blink.
+
+import type { ElementTable, RenderNode } from 'claude-code'
+
+import type { Frame } from './view'
+import { isRich } from './view'
+import { GAUGE_FACES, GRID, detailOf, gaugeStep, rippleBody, rippleCss } from './ripple'
+import type { Face } from './ripple'
+import { svgDoc } from './theme'
+import type { Appearance } from './theme'
+
+export type Els = ElementTable
+
+/** 리플이's size on a card (alerts, quick settings), px: the sheet's card badge. */
+export const FACE_SIZE = 44
+/** Where it greets or waits with nothing else to show (setup, empty panes), px: a bigger presence. */
+export const GREET_SIZE = 56
+
+const sources = new Map<string, string>()
+
+/**
+ * 리플이's SVG document: `face` at `size` px (the mini drawing below 34 px), the gauge in its 5%
+ * steps, dimmed or not. One fixed string per state, built once: the host is handed the same
+ * source until the state changes.
+ */
+export function rippleSource(face: Face, size: number, appearance: Appearance, percent?: number, dim = false): string {
+  const step = percent !== undefined && GAUGE_FACES.includes(face) ? gaugeStep(percent) : undefined
+  const key = [face, size, appearance, step ?? '', dim ? 'dim' : ''].join('|')
+  let source = sources.get(key)
+  if (!source) {
+    const detail = detailOf(size)
+    source = svgDoc(size, size, appearance, rippleBody(face, step, detail), rippleCss(face, step, detail) + (dim ? 'svg>g{opacity:.5}' : ''), '0 0 ' + GRID + ' ' + GRID)
+    sources.set(key, source)
+  }
+  return source
+}
+
+/**
+ * 리플이 with one of its faces (ripple.ts), `size` px square, alive: a plain image whose CSS motion
+ * runs inside it and survives redraws without a blink (never isInteractive, see above). `percent`
+ * fills the ring of a gauge face. Desktop and the editor only.
+ */
+export function mascot(el: Els, frame: Frame, key: string, face: Face, alt: string, size = FACE_SIZE, percent?: number): RenderNode {
+  if (!('Svg' in el)) return ''
+  const { Box, Svg } = el
+  // In a Box of its own that never shrinks: beside a column of text it keeps its size.
+  return (
+    <Box key={'ripple-' + key} flexShrink={0}>
+      <Svg source={rippleSource(face, size, frame.appearance, percent)} alt={alt} width={size} height={size} />
+    </Box>
+  )
+}
+
+/** True where 리플이 can be drawn: the desktop and the editor, with an Svg in the table. */
+export function canDraw(el: Els, frame: Frame): boolean {
+  return isRich(frame) && 'Svg' in el
+}
+
+export type Speech = {
+  key: string
+  face: Face
+  /** What it says: one short sentence, bold. */
+  title: string
+  /** Quiet words on the title's line after it (a step count, a panel's name). */
+  aside?: string
+  /** Colour of the title on the terminal, where there is no face to carry it. */
+  titleColor?: string
+  /** One line of why, dim. */
+  line?: string
+  /** The ring as a gauge (a percent). */
+  percent?: number
+  /** 리플이's size, px (FACE_SIZE unless it greets or waits: GREET_SIZE). */
+  size?: number
+  /** What follows, each block a row apart: fields, options, the actions. */
+  blocks?: RenderNode[]
+  /** The site's close control (desktop: the host's native ×; terminal: in the last block). */
+  dismiss?: RenderNode
+}
+
+/**
+ * 리플이 speaks: on the desktop its face on the left and beside it one column, the title and its
+ * line of why held together, then each block a row apart. The terminal draws the same column
+ * without the face. Every card and panel uses this, so they share one rhythm.
+ */
+export function speak(el: Els, frame: Frame, s: Speech): RenderNode {
+  const { Box, Text } = el
+  const rich = isRich(frame)
+  const head = (
+    <Box key="say" flexDirection="column">
+      <Box flexDirection="row" flexWrap="wrap" columnGap={2} alignItems="center">
+        <Text bold color={rich ? undefined : s.titleColor} wrap="wrap">{s.title}</Text>
+        {s.aside ? <Text dimColor>{s.aside}</Text> : null}
+      </Box>
+      {s.line ? <Text dimColor wrap="wrap">{s.line}</Text> : null}
+    </Box>
+  )
+  const blocks = (s.blocks ?? []).filter(b => b !== '' && b !== null && b !== undefined)
+  const column = (
+    // The text takes the width the face leaves and wraps in it (a row that wraps sizes its items
+    // to their whole line, which ran a body past the card: seen 2026-10-10).
+    <Box key="column" flexDirection="column" flexGrow={1} flexShrink={1} minWidth={0} rowGap={rich ? 1 : 0}>
+      {head}
+      {blocks}
+    </Box>
+  )
+  if (!canDraw(el, frame)) {
+    return (
+      <Box key={'say-' + s.key} flexDirection="column" width="100%">
+        {column}
+        {s.dismiss ?? null}
+      </Box>
+    )
+  }
+  return (
+    <Box key={'say-' + s.key} flexDirection="row" alignItems="flex-start" columnGap={2} width="100%">
+      {mascot(el, frame, s.key, s.face, s.title, s.size ?? FACE_SIZE, s.percent)}
+      {column}
+      {s.dismiss ?? null}
+    </Box>
+  )
+}
+
+// ---- Controls ----------------------------------------------------------------------------------
+
+/** A terminal (or mobile) control: `k: Label` with a hotkey, the label alone without one. */
+export function textButton(el: Els, key: string, label: string, onPress: () => void, hotkey?: string, primary?: boolean): RenderNode {
+  const { Button } = el
+  // A bracketed button hides its hotkey on the terminal, so one with a hotkey stays plain (`s: Save`).
+  if (primary && !hotkey) return <Button key={key} variant="primary" label={label} onPress={() => onPress()} />
+  return hotkey ? <Button key={key} plain hotkey={hotkey} label={label} onPress={() => onPress()} /> : <Button key={key} plain label={label} onPress={() => onPress()} />
+}
+
+/**
+ * A button. The one main action of a card or panel is the host's primary button on the desktop;
+ * every other action is quiet, dim text until the pointer is on it. The terminal keeps its hotkeys.
+ */
+export function action(el: Els, frame: Frame, key: string, label: string, onPress: () => void, opts: { hotkey?: string; primary?: boolean } = {}): RenderNode {
+  const { Button } = el
+  if (isRich(frame)) {
+    return opts.primary ? <Button key={key} variant="primary" label={label} onPress={() => onPress()} /> : <Button key={key} plain dimColor label={label} onPress={() => onPress()} />
+  }
+  return textButton(el, key, label, onPress, opts.hotkey, opts.primary)
+}
+
+/** The site's close control: the desktop's native ×, named `label`; a button on the terminal. */
+export function dismiss(el: Els, frame: Frame, key: string, label: string, onPress: () => void, hotkey?: string): RenderNode {
+  const { Button } = el
+  if (isRich(frame)) return <Button key={key} plain role="dismiss" label={label} onPress={() => onPress()} />
+  return textButton(el, key, label, onPress, hotkey)
+}
+
+/** The main action, then the quiet ones, in one row that wraps whole buttons. */
+export function actions(el: Els, frame: Frame, buttons: RenderNode[]): RenderNode {
+  const { Box } = el
+  const shown = buttons.filter(b => b !== '' && b !== null && b !== undefined)
+  if (!shown.length) return ''
+  return (
+    <Box key="actions" flexDirection="row" flexWrap="wrap" alignItems="center" columnGap={isRich(frame) ? 1 : 2}>
+      {shown}
+    </Box>
+  )
+}
+
+/** One option of several: `● Label` chosen, `○ Label` dim otherwise, on every surface. */
+export function option(el: Els, key: string, label: string, chosen: boolean, onPress: () => void, hotkey?: string): RenderNode {
+  const { Button } = el
+  const text = (chosen ? '● ' : '○ ') + label
+  if (hotkey) return <Button key={key} plain hotkey={hotkey} dimColor={!chosen} label={text} onPress={() => onPress()} />
+  return <Button key={key} plain dimColor={!chosen} label={text} onPress={() => onPress()} />
+}
+
+/** A row of options, one chosen. */
+export function segmented<T extends string>(
+  el: Els,
+  frame: Frame,
+  key: string,
+  options: readonly { value: T; label: string; hotkey?: string }[],
+  value: T,
+  onPick: (value: T) => void,
+): RenderNode {
+  const { Box } = el
+  return (
+    <Box flexDirection="row" flexWrap="wrap" columnGap={isRich(frame) ? 1 : 2}>
+      {options.map(o => option(el, key + '-' + o.value, o.label, o.value === value, () => onPick(o.value), isRich(frame) ? undefined : o.hotkey))}
+    </Box>
+  )
+}
+
+/** A two-state switch: one button that says its state (`● On` / `○ Off`) and flips it. */
+export function toggle(el: Els, frame: Frame, key: string, label: string, on: boolean, onPress: () => void, hotkey?: string): RenderNode {
+  return option(el, key, label, on, onPress, isRich(frame) ? undefined : hotkey)
+}