lab

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3import { flow, flowColumns, holdButtons, kit } from '../kit/ui'
4
5import { GROUPS, byId, experiments, galleryExperiments } from './experiments'
6import type { Experiment } from './experiments'
7
8const INDEX = 'lab'
9const PREFIX = 'lab-'
10const GALLERY = 'lab-gallery'
11
12/** Whether a wide app pane flows the index's groups and the gallery into columns; the footer's switch flips it. */
13const columns = atom({ plugin: 'lab', key: 'columns' } as const, true)
14
15/** The column view's switch for a render: as the state holds it, and a press that flips it. */
16const flowSwitch = async ($: EngineInterface) => ({
17  on: await read($, columns),
18  toggle: () => void update($, columns, was => !was).catch(() => undefined),
19})
20
21/** Every experiment the desktop accepts, in one pane, for checking paint by eye. */
22const openGallery = ($: EngineInterface) => $.ui.open({ id: GALLERY, title: 'Lab: gallery' })
23
24const openExperiment = ($: EngineInterface, id: string) => {
25  const x = byId(id)
26  return $.ui.open({ id: PREFIX + id, title: x ? `Lab: ${x.title}` : id })
27}
28
29/**
30 * The elements each surface's table declares (the types' `Elements`). The
31 * table `$.ui.resolve` hands back answers every name on every surface: one a
32 * surface lacks is a stand-in that draws an empty column Box, so asking it
33 * says nothing, and this list is how the pane tells.
34 */
35const TABLES: Record<string, string[]> = {
36  terminal: ['Box', 'Text', 'Button', 'Input', 'Select', 'Link', 'Code', 'Markdown', 'Client', 'Raster', 'Image'],
37  desktop: ['Box', 'Text', 'Button', 'Input', 'Select', 'Svg', 'Link', 'Code', 'Markdown', 'Client'],
38  vscode: ['Box', 'Text', 'Button', 'Input', 'Select', 'Svg', 'Link', 'Code', 'Markdown'],
39  mobile: ['Box', 'Text', 'Button', 'Svg', 'Link', 'Code', 'Markdown'],
40}
41
42/**
43 * The surface's elements, noting each one the experiment asked for that the
44 * surface's table does not declare. For an element with no constructor at all
45 * it hands the bare tag name, so the engine names it in its refusal rather
46 * than the hook failing on an undefined constructor.
47 */
48const elementsOf = (table: object, surface: string, absent: Set<string>): any => {
49  const listed = new Set(TABLES[surface] ?? Object.keys(table))
50  return new Proxy(table, {
51    get: (t: any, k) => {
52      if (typeof k !== 'string') return t[k]
53      if (!listed.has(k)) absent.add(k)
54      return t[k] ?? k
55    },
56  })
57}
58
59export const register: Register = on => {
60  on('session.start', async ($, e, next) => {
61    await $.command.register({
62      name: 'lab',
63      description: 'Open the rendering lab: experiments on what the engine draws (/lab <id> opens one)',
64      argumentHint: '[experiment id]',
65    })
66    void $.ui.open({ id: INDEX, title: 'Lab' })
67    return next(e)
68  })
69
70  on('command.run', { command: 'lab' }, async ($, e) => {
71    const id = e.args.trim()
72    if (!id) {
73      await $.ui.open({ id: INDEX, title: 'Lab' })
74      return { text: `Lab opened: ${experiments.length} experiments.` }
75    }
76    if (id === 'gallery') {
77      await openGallery($)
78      return { text: `Lab gallery opened: ${galleryExperiments().length} experiments the desktop accepts.` }
79    }
80    if (!byId(id)) return { text: `No experiment "${id}". Run /lab for the list.` }
81    await openExperiment($, id)
82    return { text: `Lab experiment ${id} opened.` }
83  })
84
85  // The index: every experiment by group, a row each that opens its pane.
86  on('ui.render', { component: 'Pane', requestId: INDEX }, async ($, e) => {
87    const sw = await flowSwitch($)
88    // Buttons keep their press handles across redraws, so a click made just before one still lands.
89    const table = holdButtons($.ui.resolve(e), e)
90    const { Box, Button, Text } = table
91    // The kit draws the footer with the column view's switch (wide app panes only).
92    const k = kit(table as never, e.surface, e.props.bodyColumns, { flow: sw })
93    return (
94      <Box flexDirection="column" gap={1}>
95        <Button key="gallery" variant="primary" label="Gallery" onPress={() => void openGallery($)} />
96        <Text dimColor>
97          {experiments.length} experiments on what the {e.surface} surface draws. Each opens in a pane of its own.
98        </Text>
99        {/* The groups in columns when the desktop pane is wide; one stack otherwise. */}
100        {flow(Box, e.surface, e.props.bodyColumns, 'groups', GROUPS.map(group => (
101          <Box key={`group-${group}`} flexDirection="column">
102            <Text bold>{group}</Text>
103            {experiments
104              .filter(x => x.group === group)
105              .map(x => {
106                const note = `${x.id}${x.surfaces.length ? ` · ${x.surfaces.join(', ')}` : ' · expected refusal'}`
107                // The desktop draws a Button's label alone, never a dim child Text: there the
108                // title is the label and the note a dim Text beside it.
109                return e.surface === 'terminal' ? (
110                  <Button key={`open-${x.id}`} plain onPress={() => void openExperiment($, x.id)}>
111                    {x.title}{' '}
112                    <Text dimColor>{note}</Text>
113                  </Button>
114                ) : (
115                  <Box key={`row-${x.id}`} flexDirection="row" gap={1}>
116                    <Button key={`open-${x.id}`} plain label={x.title} onPress={() => void openExperiment($, x.id)} />
117                    <Text dimColor wrap="truncate">
118                      {note}
119                    </Text>
120                  </Box>
121                )
122              })}
123          </Box>
124        )), { gap: 1, single: !sw.on })}
125        {k.footer()}
126      </Box>
127    )
128  })
129
130  // One pane per experiment, and the gallery, all drawn by this hook.
131  on('ui.render', { component: 'Pane', requestId: /^lab-/ }, async ($, e) => {
132    // One table for the whole render, the experiment's included, its Buttons keeping their press handles.
133    const table = holdButtons($.ui.resolve(e), e)
134    const { Box, Button, Text } = table
135    const absent = new Set<string>()
136    const els = elementsOf(table, e.surface, absent)
137    // An element constructor may refuse its props as it is called (a bad
138    // hotkey): that is a verdict too, drawn in place of the experiment.
139    const drawBody = (x: Experiment) => {
140      try {
141        return x.draw(els, e.surface)
142      } catch (err) {
143        return <Text color="error">{`draw threw: ${String((err as Error)?.message ?? err)}`}</Text>
144      }
145    }
146    if (e.requestId === GALLERY) {
147      const sw = await flowSwitch($)
148      const k = kit(table as never, e.surface, e.props.bodyColumns, { flow: sw })
149      return (
150        <Box flexDirection="column" gap={1}>
151          {/* The experiments in columns when the desktop pane is wide, each clipped to its column; one stack otherwise. */}
152          {flow(
153            Box,
154            e.surface,
155            e.props.bodyColumns,
156            'gallery',
157            galleryExperiments().map((x, _i, all) => (
158              <Box
159                key={`x-${x.id}`}
160                flexDirection="column"
161                {...(flowColumns(e.surface, e.props.bodyColumns, all.length, { single: !sw.on }).count > 1 ? { minWidth: 0, overflow: 'hidden' } : {})}
162              >
163                <Text dimColor wrap="truncate-end">{`${x.id} — ${x.question}`}</Text>
164                {drawBody(x)}
165              </Box>
166            )),
167            { gap: 1, single: !sw.on },
168          )}
169          {k.footer()}
170        </Box>
171      )
172    }
173    const x = byId(e.requestId.slice(PREFIX.length))
174    if (!x) return <Text dimColor>No such experiment.</Text>
175    const body = drawBody(x)
176    const listed = x.surfaces.includes(e.surface)
177    return (
178      <Box flexDirection="column" gap={1}>
179        <Box flexDirection="column">
180          <Text bold>{x.title}</Text>
181          <Text dimColor>{x.question}</Text>
182          <Text dimColor>
183            {x.group} · {x.id} ·{' '}
184            {listed ? `meant for ${x.surfaces.join(', ')}` : x.surfaces.length ? `not meant for ${e.surface}` : 'expected refusal'}
185          </Text>
186          {absent.size > 0 && (
187            <Text color="warning">
188              {`absent from the ${e.surface} table: ${[...absent].join(', ')}`}
189            </Text>
190          )}
191          <Button key="index" plain dimColor label="All experiments" onPress={() => void $.ui.open({ id: INDEX, title: 'Lab' })} />
192        </Box>
193        {body}
194      </Box>
195    )
196  })
197
198  // The Client round trip: the echo module posts a ping, this answers its next props.
199  on('ui.message', { element: 'echo' }, async (_$, e) => {
200    const data = e.data as { ping?: number } | null
201    return { props: { pong: data?.ping ?? 0, via: e.surface } }
202  })
203}
204

1import type { RenderElement, RenderSurface } from 'claude-code'
2
3import { middle, pct, short } from './format'
4import { ICON_PX, glyphOf, iconSvg } from './icons'
5import { ms } from './perf'
6import type { PerfRow, PerfSnapshot } from './perf'
7import { C, FILL, GLYPH, GRAY, INK, MUTED, STATUS, TRACK, isKitColor, termInk, tint, treePrefix } from './tokens'
8import type { Duo, StatusKind } from './tokens'
9
10/**
11 * The shared components. Each draws for the surface it is given: on the app
12 * surfaces (desktop, VS Code, mobile) as boxes laid out by flexbox, crisp at
13 * any width; in the terminal as cells, `columns` wide.
14 *
15 * What the desktop accepts (2.1.293): whole percentages only, `flexGrow` up to
16 * 10000, fractional heights and margins; no `hover`. Borders `round` (rounded
17 * corners), single, double, bold and classic draw; `dashed` doesn't. SVG is
18 * drawn as an image: crisp only at its exact pixel size, so it's kept to small
19 * fixed pieces like bar ends.
20 *
21 * Units on the desktop (measured on 2.1.295): a column (widths, paddingX, marginX,
22 * gaps between columns) is ~7.8px; a row of size (`height`, `minHeight`) is ~19px,
23 * one text line; but vertical spacing (marginTop/Bottom/Y, paddingTop/Bottom/Y,
24 * rowGap) is half that, ~9.5px a unit. A `transparent` border colour is drawn in
25 * the text's colour, so the kit draws no border to round a fill.
26 */
27
28/** The element constructors the kit draws with. `Button` is needed only for collapsible sections. */
29export type Els = {
30  Box: (props: any, ...children: any[]) => RenderElement
31  Text: (props: any, ...children: any[]) => RenderElement
32  Button?: (props: any, ...children: any[]) => RenderElement
33  /** Rounds the ends of bars where the surface has it. */
34  Svg?: (props: any, ...children: any[]) => RenderElement
35}
36
37/**
38 * The Buttons one pane drew last, per scope: each by its key, with the props and
39 * children it was drawn with, the element built for them, and the latest press.
40 */
41type HeldButton = { look: string; made: unknown; element: RenderElement; frame: number; press: (e: any) => void }
42const heldButtons = new Map<string, { frame: number; buttons: Map<string, HeldButton> }>()
43
44/**
45 * The element table `els` with a `Button` that keeps each button's press handle
46 * from one drawing to the next, for the drawing `scope` names (the render event
47 * itself: its component, requestId and surface). Call it once per render, as
48 * the drawing starts (after the render's awaits), and draw every Button of that
49 * render with the table it returns (the kit's own included: pass it to `kit`).
50 *
51 * Why: the engine's JSX gives every Button it builds a new handle, and frees the
52 * old one as soon as a drawing leaves it out; a press reaches its `onPress` by
53 * that handle alone. So a redraw between drawing and click (the click focusing
54 * the pane, a timer's write) left the press on a freed handle, and it did
55 * nothing. Here a Button whose key, props and children match the last render's
56 * is that same element, its handle unchanged, its press running the latest
57 * `onPress`. One that changed is built anew (a stale press on it misses, as it
58 * should); one absent from the last render is forgotten.
59 */
60export const holdButtons = <E extends { Button?: unknown }>(els: E, scope: string | { component: string; requestId: string; surface: string }): E => {
61  const Made = els.Button as ((props: any, ...children: any[]) => RenderElement) | undefined
62  if (!Made) return els
63  const id = typeof scope === 'string' ? scope : `${scope.component}\u0000${scope.requestId}\u0000${scope.surface}`
64  const pane = heldButtons.get(id) ?? { frame: 0, buttons: new Map<string, HeldButton>() }
65  heldButtons.set(id, pane)
66  // A new render: keep only what the last one drew.
67  for (const [key, b] of pane.buttons) if (b.frame < pane.frame) pane.buttons.delete(key)
68  pane.frame += 1
69  const frame = pane.frame
70  const Button = (props: any, ...rest: any[]): RenderElement => {
71    const { children: given, onPress, ...plain } = props ?? {}
72    const children: unknown[] = rest.length ? rest : given === undefined ? [] : Array.isArray(given) ? given : [given]
73    const key = plain.key ?? plain.label ?? (children.length === 1 && typeof children[0] === 'string' ? children[0] : undefined)
74    if (typeof key !== 'string' || typeof onPress !== 'function') {
75      return (
76        <Made {...plain} onPress={onPress}>
77          {children}
78        </Made>
79      )
80    }
81    const look = JSON.stringify([plain, children])
82    const was = pane.buttons.get(key)
83    // A second Button on one key in one render is built apart: one element can't hold two presses.
84    if (was?.frame === frame) {
85      return (
86        <Made {...plain} onPress={onPress}>
87          {children}
88        </Made>
89      )
90    }
91    // The same look from the same constructor (another plugin may restyle the table's).
92    if (was && was.look === look && was.made === Made) {
93      was.frame = frame
94      was.press = onPress
95      return was.element
96    }
97    const b: HeldButton = { look, made: Made, frame, press: onPress, element: null as unknown as RenderElement }
98    b.element = (
99      <Made {...plain} onPress={(e: any) => b.press(e)}>
100        {children}
101      </Made>
102    )
103    pane.buttons.set(key, b)
104    return b.element
105  }
106  // Everything else read through to the table as it was (whatever kind of object it is).
107  // Defined, not assigned: the engine's table is frozen, and its read-only Button would refuse an assignment.
108  return Object.create(els, { Button: { value: Button, enumerable: true } }) as E
109}
110
111/**
112 * A bar part: its value, its color, and the label its legend shows. `room: true`
113 * marks room rather than use (free space, a reserve): the terminal draws it as
114 * the bar's light rail in its colour, and a `bar: true` legend keys it with `─`.
115 */
116export type Part = { value: number; color: string; label?: string; room?: boolean }
117
118const BAR = 0.45
119
120/** One row's height in CSS pixels on the desktop, measured: a 0.45-row bar is 8.5px tall. */
121const ROW_PX = 8.5 / 0.45
122/** One column's width in CSS pixels on the desktop (as the playground calibrates it): what an SVG sized in cells is drawn at. */
123const COL_PX = 7.8
124
125/*
126 * The grid. Mods use these, never raw spacing numbers:
127 *
128 * - SPACE.pair between the two halves of a pair (glyph and figure, dot and label),
129 *   SPACE.item between items in a row, SPACE.group between groups of items;
130 *   SPACE.block between blocks inside a section body (rows in a list sit at 0).
131 * - INSET: a band's (header, footer) padding on both sides, and a body's on the right,
132 *   so header figures, body figures and the footer end on one line.
133 * - BODY_INDENT: a body's left edge, just past the header's fold arrow.
134 * - Reading columns: LABEL | gauge (grows) | FIG right-aligned | FIG2 right-aligned.
135 */
136export const SPACE = { pair: 0.75, item: 1.25, group: 2, block: 0.8 } as const
137const INSET = 1
138const BODY_INDENT = 1.6
139/**
140 * The content edges: everything that isn't a band (the header totals, section bodies)
141 * starts at `left` and ends at `right`. Alignment rules, for every row:
142 * - labels, names and titles start on the left edge;
143 * - the row's last figure or action ends on the right edge (rows are space-between);
144 * - figures are right-aligned; a row's right side is one cluster, never two.
145 */
146export const EDGE = { left: BODY_INDENT, right: INSET } as const
147const LABEL = 10
148const FIG = 5
149const FIG2 = 6
150/** The terminal's fold-arrow gutter. */
151const GUTTER = 2
152
153/*
154 * The terminal's grid. A terminal lays out in whole cells, so it has its own
155 * spacing (a fraction would round differently row to row) and draws to an exact
156 * width in cells. `k.space` and `k.edge` give the grid for the kit's surface.
157 *
158 * - CELLS: pair 1 (glyph and figure), item 1 (columns of a reading), group 2
159 *   (figures in a summary, actions in a row), block 1 (a blank row).
160 * - Indent: a section body starts GUTTER (2) in, under the header's icon column;
161 *   each tree level indents 2 more.
162 * - Reading columns: LABEL (10) | gauge (the rest) | FIG (5) | FIG2 (6), one cell
163 *   apart; under MIN_GAUGE cells of gauge the label narrows, then the gauge goes.
164 */
165export const CELLS = { pair: 1, item: 1, group: 2, block: 1 } as const
166/** The fewest cells a terminal gauge is drawn in; narrower, the reading drops it and keeps its figures. */
167const MIN_GAUGE = 6
168/** The narrowest a terminal reading's label gets before its gauge is dropped. */
169const MIN_LABEL = 6
170/** The cells of its text a terminal list item keeps (with its ellipsis) before its right cluster is cut. */
171const ITEM_KEEPS = 6
172/**
173 * The narrowest pane the terminal draws section bodies in. Narrower, each section
174 * draws its header and figures only (a floor, as bottom's basic mode), rather
175 * than every reading collapsing to an ellipsis.
176 */
177export const MIN_COLUMNS = 30
178
179/**
180 * The terminal's meter glyphs. A gauge and a bar are both a heavy line on a light
181 * one, to half a cell (╸): a bar's parts are runs of the heavy line, each in its
182 * own solid theme colour, and its room (free space, a reserve) the light rail in
183 * its colour. No shades or dithers: they render as a checkerboard in real fonts.
184 */
185export const METER = {
186  line: '━',
187  half: '╸',
188  rail: '─',
189  /** Lower eighths, 0 to 8: for columns that rise. */
190  rise: [' ', '▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'],
191} as const
192
193/**
194 * The widest a dashboard's sections are drawn on the terminal, in cells, when a
195 * mod passes `measure: MEASURE` to `kit()`: past it, more width only spreads
196 * readings apart and sends the eye across the pane.
197 */
198export const MEASURE = 72
199/** The terminal's right margin: figures stop one cell short of the pane's edge. */
200const RIGHT = 1
201/** The cells a section title's column takes, so header figures start on one column. */
202const TITLE_COL = 10
203
204/** The terminal's fold arrows: the small triangles, a cell each. */
205export const FOLD = { open: '▾', closed: '▸' } as const
206
207/**
208 * The terminal's marks for lists and footers: a selected row's gutter mark (a
209 * left half block, in `suggestion`, Claude Code's own selection colour), the key
210 * hints' separator, and the ellipsis that ends anything cut.
211 */
212export const MARK = { selected: '▌', sep: ' · ', more: '…', stale: '↻' } as const
213
214/**
215 * Braille dots for a sparkline, filled from the bottom: a cell holds two points
216 * (its left and right dot columns), four levels each. `left[n]` is the left
217 * column's bottom n dots, `right[n]` the right column's; OR them onto U+2800.
218 */
219export const SPARK = {
220  base: 0x2800,
221  left: [0, 0x40, 0x44, 0x46, 0x47],
222  right: [0, 0x80, 0xa0, 0xb0, 0xb8],
223} as const
224/**
225 * A band's (a section header's, a footer's) height on the app surfaces, in rows of
226 * size: one text row and a little room. Fixed rather than padded, so every band is
227 * as tall as every other whatever it holds: a native Button, a Link or an icon in
228 * a row of the real desktop is taller or shorter than a line of text, and a padded
229 * band grew or shrank with it (the launcher's rows came out uneven).
230 */
231export const BAND_ROWS = 1.3
232
233/**
234 * A Braille blank (U+2800): drawn as nothing, as a space is, but never trimmed or
235 * collapsed. A Button labelled with them lies over what the desktop can't draw in a
236 * Button (an icon, a coloured word), which shows through; its key is its address.
237 */
238export const BLANK = '⠀'
239/** A tile's padding above and below its lines, and the room between its lines: enough to breathe. */
240const TILE_PAD_Y = 0.6
241const TILE_ROW_GAP = 0.2
242
243/**
244 * The desktop's fold arrow: full-size triangles, since text can't be sized.
245 * U+FE0E keeps ▶ a text glyph; without it macOS can draw it as an emoji. Never
246 * on the terminal, which draws FOLD and never gets a variation selector.
247 */
248export const fold = (collapsed: boolean) => (collapsed ? '▶︎' : '▼')
249
250
251/**
252 * `text` split for two terminal lines `width` cells wide: the first holds as many
253 * whole words as fit (a word longer than the line is cut to it), the second the
254 * rest, which the caller truncates. The second is empty when it all fits on one.
255 */
256const breakLine = (text: string, width: number): [string, string] => {
257  const chars = [...text]
258  if (chars.length <= width) return [text, '']
259  // The last space at or before the line's end; none, a hard cut.
260  let cut = -1
261  for (let i = Math.min(width, chars.length - 1); i > 0; i--) {
262    if (chars[i] === ' ') {
263      cut = i
264      break
265    }
266  }
267  if (cut <= 0) return [chars.slice(0, width).join(''), chars.slice(width).join('').trimStart()]
268  return [chars.slice(0, cut).join('').trimEnd(), chars.slice(cut + 1).join('').trimStart()]
269}
270
271
272/** The debug footer's glyph for each job the mods time; all muted, a slow job's figure turns amber or red. */
273export const PERF_GLYPH: Readonly<Record<string, string>> ={ render: '▣', tick: '↻', resources: '◎', usage: '◕', git: '⎇', gh: '⇡' }
274
275/*
276 * The terminal's look ("rules", after lazygit and gh-dash, made quieter). A header
277 * is a dim arrow and icon, the title in bold default foreground, its figures on a
278 * shared column right after it (so the eye doesn't cross the pane), then a dim `─`
279 * rule out to the edge. Status colours keep their one meaning; nothing else is coloured.
280 *
281 * Two tones and one weight carry the hierarchy: dim for what a thing is (labels,
282 * units, notes), the default foreground for what it says (values, list text),
283 * bold for the title and the one figure that matters in each section (a header's
284 * first figure). No italics: real terminal fonts draw them oddly, and some not at
285 * all. Tune the look here, in one place:
286 * - title: a section's name: bold;
287 * - label: what a value is (a reading's, a prop's, a legend entry's label): dim;
288 * - value: the figure or word that answers (a reading's figure, a prop's value): plain;
289 * - strong: the one figure per section that matters (a header's first figure): bold;
290 * - secondary: text a reader still reads, after the main text (a list row's note): dim;
291 * - meta: what's scanned past (units, ages, counts in a list row): dim.
292 *
293 * The alternatives it was picked from (inspector, panel, ledger) are in commit ab3a37a.
294 */
295
296/** Text props a terminal role is drawn with. */
297type Role = { color?: string; dimColor?: boolean; bold?: boolean; italic?: boolean }
298
299export const TERM_ROLES: Readonly<Record<'title' | 'label' | 'value' | 'strong' | 'secondary' | 'meta', Role>> = {
300  title: { bold: true },
301  label: { dimColor: true },
302  value: {},
303  strong: { bold: true },
304  secondary: { dimColor: true },
305  meta: { dimColor: true },
306}
307
308/**
309 * The header icon's colour on the terminal: dim (MUTED), as the fold arrow, since
310 * grey is what icons mean. The title beside it is bold in the default foreground,
311 * so a header carries no hue that could be read as a status in the rows under
312 * it. Read when drawing, so a skin worn later is the one drawn.
313 */
314const termHeaderIcon = () => MUTED
315
316/** What the kit is told about the pane beyond its surface and width. */
317export type KitOptions = {
318  /**
319   * Whether the pane has the keyboard: pass `e.props.isFocused`. Key hints show
320   * only while it's true, and a selected list row is drawn dimmed while it's
321   * false. Left out, the pane counts as focused.
322   */
323  focused?: boolean
324  /**
325   * The widest the terminal draws sections, in cells (`MEASURE` for a dashboard
326   * of readings). Past it a section keeps this width and the rest of the pane
327   * stays empty. Left out, sections span the pane (a file tree wants every cell).
328   */
329  measure?: number
330  /**
331   * The column view's switch, as the mod holds it in its own state (key
332   * `columns`, default on): off, `flow` gives one stack at any width. With a
333   * `toggle`, a wide desktop pane's footer (`perf`, `footer`) draws the quiet
334   * action that flips it (see `flowToggle`).
335   */
336  flow?: FlowSwitch
337}
338
339/** The column view's switch: `on` as the mod's state holds it, `toggle` to flip it from a press. */
340export type FlowSwitch = { on: boolean; toggle?: () => void }
341
342/**
343 * A part of a list row's right cluster that says when it gives way: at narrow
344 * widths the part with the highest `drop` goes first (ties: the later one), then
345 * the next, until the row fits; parts without one (rank 0) are never dropped,
346 * only cut. `cells` is its width on the terminal when it's an element the kit
347 * can't measure (a string measures itself).
348 */
349export type RightPart = { part: RenderElement | string; drop?: number; cells?: number }
350
351/** One key hint: the key as the person types it, and what it does. */
352export type Hint = { key: string; label: string }
353
354const isRightPart = (x: RenderElement | string | RightPart): x is RightPart => typeof x === 'object' && x !== null && 'part' in x && !('type' in x)
355
356/**
357 * The cells a part draws in on the terminal, as far as the kit can tell: a
358 * string's characters; a Text's text; a row Box's children and gaps; a plain
359 * Button's label (and `1: ` before it with a hotkey). Undefined when it can't.
360 */
361const cellsOf = (x: unknown): number | undefined => {
362  if (x == null || x === false) return 0
363  if (typeof x === 'string' || typeof x === 'number') return [...String(x)].length
364  if (Array.isArray(x)) {
365    let n = 0
366    for (const c of x) {
367      const m = cellsOf(c)
368      if (m === undefined) return undefined
369      n += m
370    }
371    return n
372  }
373  if (typeof x !== 'object') return undefined
374  const el = x as { type?: string; props?: Record<string, any>; children?: unknown[] }
375  const p = el.props ?? {}
376  const kids = el.children ?? (p.children as unknown[] | undefined) ?? []
377  if (el.type === 'Text') return cellsOf(kids)
378  if (el.type === 'Button') {
379    const label = p.label === undefined ? cellsOf(kids) : [...String(p.label)].length
380    if (label === undefined) return undefined
381    return (p.plain ? label : label + 4) + (p.hotkey ? 3 : 0)
382  }
383  if (el.type === 'Box') {
384    const list = (Array.isArray(kids) ? kids : [kids]).flat(Infinity as 1).filter(c => c != null && c !== false)
385    const sizes = list.map(cellsOf)
386    if (sizes.some(s => s === undefined)) return undefined
387    const n = sizes as number[]
388    if (p.flexDirection === 'column') return Math.max(0, ...n)
389    const gap = Number(p.columnGap ?? p.gap ?? 0)
390    return n.reduce((a, b) => a + b, 0) + gap * Math.max(0, n.length - 1)
391  }
392  return undefined
393}
394
395/*
396 * Flow: a pane's sections in columns when the desktop gives it the width.
397 *
398 * The engine tells a render its pane's width (`e.props.bodyColumns`; on the desktop
399 * the pane's width over its code font's advance), and draws again when it changes.
400 * At a sidebar's width the sections stack as they always have; past two of
401 * FLOW_MIN (plus the gutter) they split into two columns, past three into three.
402 * The terminal always stacks: its panes dock beside the transcript and are narrow.
403 */
404
405/**
406 * The narrowest a flow column gets, in the pane's reported columns: about the
407 * widest a desktop sidebar is drawn (Storybook's 110), halved, so a section in a
408 * column reads as it does in a roomy sidebar. Two columns from 82 (about 640px), three from 124 (about 970px).
409 */
410export const FLOW_MIN = 40
411/** The most columns a flow splits into: more makes every section a sliver. */
412export const FLOW_MAX = 3
413/** The gutter between flow columns: a group's room, as between groups of items in a row. No rule or panel marks it. */
414const FLOW_GAP = SPACE.group
415
416/** How a flow is told to lay out; each defaults to the kit's FLOW_MIN, FLOW_MAX. */
417export type FlowOptions = {
418  /** The narrowest column, in reported columns. */
419  min?: number
420  /** The most columns. */
421  max?: number
422  /**
423   * Each block's height in rows, where the caller knows better than the kit's
424   * estimate (`undefined` entries are estimated). In the order the blocks are given.
425   */
426  rows?: (number | undefined)[]
427  /**
428   * The room between blocks in a column, in the desktop's vertical units, for
429   * blocks that space themselves apart in one stack (a list's tiles, each with a
430   * margin above all but the first): in columns they drop that margin and the
431   * column spaces them, so every column's first block starts on one line.
432   */
433  gap?: number
434  /** One stack at any width: the column view switched off (KitOptions' `flow`). */
435  single?: boolean
436}
437
438/** Whether a pane `columns` across on `surface` is wide enough to split into flow columns at all. */
439export const flowSplits = (surface: RenderSurface, columns: number, o: Pick<FlowOptions, 'min'> = {}) =>
440  surface !== 'terminal' && Math.floor((Math.floor(columns) + FLOW_GAP) / ((o.min ?? FLOW_MIN) + FLOW_GAP)) >= 2
441
442/**
443 * How many columns a flow of `blocks` blocks takes at `columns` across on
444 * `surface`, and each column's width in reported columns: 1 and the whole width
445 * on the terminal, at a sidebar's width, with fewer than two blocks, or `single`.
446 */
447export const flowColumns = (surface: RenderSurface, columns: number, blocks: number, o: FlowOptions = {}) => {
448  const min = o.min ?? FLOW_MIN
449  const max = o.max ?? FLOW_MAX
450  const fit = surface === 'terminal' || o.single ? 1 : Math.floor((Math.floor(columns) + FLOW_GAP) / (min + FLOW_GAP))
451  const count = Math.max(1, Math.min(fit, max, blocks))
452  return { count, width: count === 1 ? columns : Math.floor((columns - FLOW_GAP * (count - 1)) / count) }
453}
454
455/** A drawn element's own props and children, as the engine's JSX and Storybook's both build them. */
456const partsOf = (x: any): { type?: string; p: Record<string, any>; kids: unknown[] } => {
457  const p = (x?.props ?? {}) as Record<string, any>
458  const given = x?.children ?? p.children ?? []
459  return { type: x?.type, p, kids: (Array.isArray(given) ? given : [given]).flat(Infinity as 1).filter(c => c != null && c !== false) }
460}
461
462/**
463 * About how many rows tall an element draws on the desktop: a Text or a Button a
464 * row, a column Box its children stacked, a row Box its tallest child, a `height`
465 * as given; vertical margins, padding and gaps at half a row a unit, as the
466 * desktop draws them. Only good enough to balance columns, never to size them.
467 */
468export const rowsOf = (x: unknown): number => {
469  if (x == null || x === false) return 0
470  if (typeof x === 'string' || typeof x === 'number') return 1
471  if (Array.isArray(x)) return x.reduce((n: number, c) => n + rowsOf(c), 0)
472  if (typeof x !== 'object') return 0
473  const { type, p, kids } = partsOf(x)
474  if (p.display === 'none' || p.position === 'absolute') return 0
475  const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
476  // Vertical spacing in half rows (the desktop's unit for it), as rows.
477  const around =
478    (num(p.marginTop) + num(p.marginBottom) + 2 * num(p.marginY) + 2 * num(p.margin) + num(p.paddingTop) + num(p.paddingBottom) + 2 * num(p.paddingY) + 2 * num(p.padding)) / 2
479  let own: number
480  if (typeof p.height === 'number') own = p.height
481  else if (type === 'Box') {
482    const sizes = kids.map(rowsOf)
483    if (p.flexDirection === 'column') own = sizes.reduce((a, b) => a + b, 0) + (num(p.rowGap ?? p.gap) * Math.max(0, sizes.length - 1)) / 2
484    else own = Math.max(0, ...sizes)
485  } else own = 1
486  return Math.max(own, num(p.minHeight)) + around
487}
488
489/**
490 * Splits `heights` into `n` runs in order, so the tallest run is as short as it
491 * can be: blocks read top to bottom, then left to right, and the columns end
492 * about even. Returns each run's first index.
493 */
494const balance = (heights: number[], n: number): number[] => {
495  const m = heights.length
496  const sum = [0]
497  for (const h of heights) sum.push(sum[sum.length - 1]! + h)
498  // best[j][i]: the tallest column laying the first i blocks in j columns; cut[j][i] where the last column starts.
499  const best = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(Infinity))
500  const cut = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0))
501  best[0]![0] = 0
502  for (let j = 1; j <= n; j++) {
503    for (let i = j; i <= m; i++) {
504      // Every column holds at least one block.
505      for (let s = j - 1; s < i; s++) {
506        const tall = Math.max(best[j - 1]![s]!, sum[i]! - sum[s]!)
507        // Ties go to the later cut, so earlier columns take more and the last isn't the tall one.
508        if (tall <= best[j]![i]!) {
509          best[j]![i] = tall
510          cut[j]![i] = s
511        }
512      }
513    }
514  }
515  const starts: number[] = []
516  let i = m
517  for (let j = n; j >= 1; j--) {
518    starts.unshift(cut[j]![i]!)
519    i = cut[j]![i]!
520  }
521  return starts
522}
523
524/**
525 * Lays `blocks` (a pane's sections, a list's tiles) out in columns when the pane
526 * is wide enough (see `flowColumns`); otherwise gives them back as they were, so
527 * a narrow pane draws exactly what it drew before. Spread the result where the
528 * blocks went: `{flow(Box, e.surface, columns, 'sections', [a, b, c])}`.
529 *
530 * A block is never split across columns. They read top to bottom, then left to
531 * right, cut where the columns come out most even by `rowsOf`'s estimate (or the
532 * `rows` given). Each column is a plain column Box (key `<key>-col-<n>`), each
533 * block in it spanning the column's width; the gutter between is FLOW_GAP, with
534 * no rule, panel or outline.
535 */
536export const flow = (
537  Box: Els['Box'],
538  surface: RenderSurface,
539  columns: number,
540  key: string,
541  blocks: (RenderElement | null | false | undefined)[],
542  o: FlowOptions = {},
543): (RenderElement | null)[] => {
544  const shown = blocks.map((b, i) => ({ b, rows: o.rows?.[i] })).filter((x): x is { b: RenderElement; rows: number | undefined } => x.b != null && x.b !== false)
545  const { count } = flowColumns(surface, columns, shown.length, o)
546  if (count < 2) return blocks.map(b => b || null)
547  const starts = balance(
548    shown.map(x => x.rows ?? rowsOf(x.b)),
549    count,
550  )
551  const runs = starts.map((s, c) => shown.slice(s, starts[c + 1] ?? shown.length))
552  return [
553    <Box key={key} flexDirection="row" width="100%" columnGap={FLOW_GAP} alignItems="flex-start">
554      {runs.map((run, c) => (
555        // Columns share the row equally, growing from no width, as a legend's do (the desktop doesn't stretch a nested box).
556        <Box key={`${key}-col-${c}`} flexDirection="column" flexGrow={1} flexShrink={1} width={0} minWidth={0} {...(o.gap ? { rowGap: o.gap } : {})}>
557          {run.map((x, i) => (
558            <Box key={`${key}-${c}-${i}`} flexDirection="column" width="100%" minWidth={0}>
559              {x.b}
560            </Box>
561          ))}
562        </Box>
563      ))}
564    </Box>,
565  ]
566}
567
568export const kit = (els: Els, surface: RenderSurface, columns = 40, opts: KitOptions = {}) => {
569  const { Box, Text, Button, Svg } = els
570  const terminal = surface === 'terminal'
571  /** Whether the pane has the keyboard; unknown counts as yes. */
572  const paneFocused = opts.focused !== false
573  /** A flow's options with the column view's switch applied: off, one stack. */
574  const flowOpts = (o: FlowOptions = {}): FlowOptions => (opts.flow?.on === false ? { ...o, single: true } : o)
575  /** Under MIN_COLUMNS the terminal draws section headers only. */
576  const floor = terminal && Math.floor(columns) < MIN_COLUMNS
577  /** A text role's props on the terminal (see TERM_ROLES). */
578  const R = TERM_ROLES
579  /** Text a step below the main text: one of the three greys on the app surfaces; plain dim in the terminal, whose greys are its own. */
580  const tone = (level: keyof typeof GRAY) => (terminal ? { dimColor: true } : { color: GRAY[level] })
581  /** A token colour as Text props for this surface: on the terminal a status's theme key, a grey as dim. */
582  const ink = (color?: string): { color?: string; dimColor?: boolean } => (terminal ? termInk(color) : color ? { color } : {})
583  /** The grid for this surface: CELLS on the terminal, SPACE elsewhere. */
584  const space = terminal ? CELLS : SPACE
585  const edge = terminal ? { left: GUTTER, right: RIGHT } : EDGE
586  /** A section's width in terminal cells: the pane's, up to the measure. */
587  const span = Math.max(1, Math.min(Math.floor(columns), opts.measure ?? Infinity))
588  /** A section body's width in terminal cells: the section's less the gutter and the right margin. */
589  const body = Math.max(1, span - GUTTER - RIGHT)
590  const clamp01 = (x: number) => (Number.isFinite(x) ? Math.max(0, Math.min(1, x)) : 0)
591
592  /** A run of one glyph in one colour, as one Text. */
593  const run = (key: string, glyph: string, n: number, props: Record<string, unknown>) =>
594    n > 0 ? <Text key={key} {...props}>{glyph.repeat(n)}</Text> : null
595
596  /**
597   * A terminal gauge `width` cells wide: a heavy line to the half cell over a
598   * dim light rail. Anything above zero shows at least half a cell.
599   */
600  const lineMeter = (fraction: number, color: string, width: number): RenderElement => {
601    const w = Math.max(1, Math.floor(width))
602    let halves = Math.round(clamp01(fraction) * w * 2)
603    if (fraction > 0 && halves === 0) halves = 1
604    const full = Math.floor(halves / 2)
605    const half = halves % 2
606    return (
607      <Text>
608        {run('fill', METER.line, full, ink(color))}
609        {half ? <Text key="half" {...ink(color)}>{METER.half}</Text> : null}
610        {run('rail', METER.rail, w - full - half, { dimColor: true })}
611      </Text>
612    )
613  }
614
615  /**
616   * A terminal bar `width` cells wide, one row: each part a run of the heavy line
617   * (`━`) in its own solid colour, to the half cell; a `room` part the light rail
618   * (`─`) in its colour; what's left the dim rail. Anything above zero shows at
619   * least half a cell. A cell shared by two parts takes the first one's colour.
620   */
621  const lineBar = (parts: Part[], total: number, width: number): RenderElement => {
622    const w = Math.max(1, Math.floor(width))
623    const halves = w * 2
624    const ends: { end: number; color: string; room: boolean }[] = []
625    let at = 0
626    for (const p of parts) {
627      if (!(p.value > 0) || at >= halves) continue
628      at = Math.min(halves, at + Math.max(1, Math.round((p.value / total) * halves)))
629      ends.push({ end: at, color: p.color, room: Boolean(p.room) })
630    }
631    const partAt = (h: number) => ends.find(x => h < x.end)
632    const rail = { glyph: METER.rail, props: { dimColor: true } as Record<string, unknown> }
633    const cells: { glyph: string; props: Record<string, unknown> }[] = []
634    for (let c = 0; c < w; c++) {
635      const left = partAt(2 * c)
636      const right = partAt(2 * c + 1)
637      if (!left) cells.push(rail)
638      else if (left.room) cells.push({ glyph: METER.rail, props: ink(left.color) })
639      // A used part ending at the half: the half line, then nothing (a room part, or the rail, starts next cell).
640      else if (!right || right.room) cells.push({ glyph: METER.half, props: ink(left.color) })
641      else cells.push({ glyph: METER.line, props: ink(left.color) })
642    }
643    // Runs of the same glyph and colour, as one Text each.
644    const runs: RenderElement[] = []
645    let i = 0
646    while (i < cells.length) {
647      let j = i + 1
648      while (j < cells.length && cells[j]!.glyph === cells[i]!.glyph && JSON.stringify(cells[j]!.props) === JSON.stringify(cells[i]!.props)) j++
649      runs.push(<Text key={`r${i}`} {...cells[i]!.props}>{cells[i]!.glyph.repeat(j - i)}</Text>)
650      i = j
651    }
652    return <Text>{runs}</Text>
653  }
654
655  /*
656   * Rounding on the desktop. Boxes have no corner radius; what rounds is:
657   *
658   * - `capped`: anything thin (bars, gauges). SVG end caps drawn at an exact pixel
659   *   size, so they stay crisp; the middle takes no height and stretches to the caps.
660   * - Nothing else: `rounded` boxes (bands, tiles) are square-cornered fills.
661   *
662   * What doesn't work, so nobody tries again: a `round` border in `transparent` to
663   * round a fill (the desktop doesn't know `transparent` as a border colour and draws
664   * the border in the text's colour: every band and tile became an outlined bubble),
665   * a border in a see-through fill's own colour (paints twice and draws a ring),
666   * borders on thin bars (empty, or blobs),
667   * glyph ends (◖━◗, ╺━╸ don't draw), SVG slivers a few pixels wide (don't draw), an
668   * SVG stretched to fit (blurs), a circle drawn over a rect in one SVG (a translucent
669   * colour doubles where they overlap).
670   */
671
672  /**
673   * An icon at the kit's one size (ICON_PX square): the SVG drawing where the
674   * surface has SVG and the kit has one for `key`, else its glyph as text
675   * (`glyphOf`: the terminal glyph for a named icon, never the name itself).
676   *
677   * `color` may be a file type's `Duo` (`FILE_TYPE`): light and dark values on the
678   * app surfaces, dim on the terminal, which draws file types monochrome.
679   * `alt` names the drawing for a reader that can't see it (the desktop's
680   * accessible name); `tooltip` also shows it under the pointer, drawing the SVG
681   * interactive (a sandboxed frame), so keep it to an icon that says something
682   * on its own (a branch's upstream), never one under a Button.
683   */
684  const icon = (key: string, color: string | Duo, px = ICON_PX, opts: { alt?: string; tooltip?: string } = {}): RenderElement => {
685    const source = Svg && !terminal ? iconSvg(key, color, px, opts.tooltip) : null
686    if (!Svg || !source) return <Text {...ink(typeof color === 'string' ? color : MUTED)}>{glyphOf(key)}</Text>
687    const alt = opts.alt ?? opts.tooltip ?? 'icon'
688    return opts.tooltip ? <Svg source={source} alt={alt} width={px} height={px} isInteractive /> : <Svg source={source} alt={alt} width={px} height={px} />
689  }
690
691  /**
692   * One rounded end:a square `px` tall, a half circle on the outside and a filled
693   * strip on the inside, as one shape.
694   */
695  const cap = (px: number, color: string, side: 'left' | 'right'): RenderElement | null => {
696    if (!Svg) return null
697    const r = px / 2
698    const d = side === 'left' ? `M${r} 0H${px}V${px}H${r}A${r} ${r} 0 0 1 ${r} 0Z` : `M0 0H${r}A${r} ${r} 0 0 1 ${r} ${px}H0Z`
699    // Over the track, as the bar's middle paints its parts: a see-through part's end
700    // then comes out the same shade as the rest of it.
701    const under = color === TRACK ? '' : `<path d="${d}" fill="${TRACK}"/>`
702    const source =
703      `<svg xmlns="http://www.w3.org/2000/svg" width="${px}" height="${px}" viewBox="0 0 ${px} ${px}">` +
704      `${under}<path d="${d}" fill="${color}"/></svg>`
705    return (
706      <Box flexShrink={0}>
707        <Svg source={source} alt="rounded end" width={px} height={px} />
708      </Box>
709    )
710  }
711
712  /**
713   * Rounds the ends of something thin: `middle` between a `left` and a `right` cap,
714   * `height` rows tall. Give `middle` no height of its own; it stretches to the caps,
715   * whose pixel size it can't drift from. Where the surface has no SVG, `middle` alone
716   * at `height`.
717   */
718  const capped = (height: number, left: string, right: string, middle: (height: number | undefined) => RenderElement): RenderElement => {
719    if (terminal || !Svg) return middle(height)
720    const px = Math.max(4, Math.round(height * ROW_PX))
721    return (
722      <Box flexDirection="row" flexGrow={1} alignItems="stretch">
723        {cap(px, left, 'left')}
724        {middle(undefined)}
725        {cap(px, right, 'right')}
726      </Box>
727    )
728  }
729
730  /**
731   * A filled box, a row or more tall: a band or a tile. Square-cornered and with no
732   * border on the app surfaces, as the design has no outlines and the desktop has no
733   * transparent border to round a fill with (see "Rounding on the desktop" above).
734   * In the terminal, the box without fill.
735   */
736  const rounded = (color: string, props: Record<string, unknown>, children: RenderElement | (RenderElement | null)[] | null) =>
737    terminal ? (
738      <Box {...props}>{children}</Box>
739    ) : (
740      <Box {...props} backgroundColor={color}>
741        {children}
742      </Box>
743    )
744
745  /**
746   * A tile: one item of a list that has several lines (a branch and its PR), in its
747   * own rounded fill a step lighter than the pane, so items read as units. A
748   * `selected` tile takes a blue-tinted fill: picked, without an outline; half
749   * as tinted while the pane isn't `focused` (the kit's `focused` by default).
750   * On the terminal, a blank row above and no fill, selected or not: a terminal
751   * list that selects draws its rows with `item`, which has a selection mark.
752   */
753  const tile = (key: string, children: (RenderElement | null)[], opts: { selected?: boolean; focused?: boolean } = {}) =>
754    terminal ? (
755      <Box key={key} flexDirection="column" marginTop={1}>
756        {children}
757      </Box>
758    ) : (
759      rounded(
760        opts.selected ? ((opts.focused ?? paneFocused) ? FILL.selected : FILL.selectedBlurred) : FILL.tile,
761        { key, flexDirection: 'column', paddingX: SPACE.item, paddingY: TILE_PAD_Y, rowGap: TILE_ROW_GAP, width: '100%' },
762        children,
763      )
764    )
765
766  /**
767   * A thin bar: parts left to right out of `max`, the rest as track. On the
768   * terminal one row `width` cells wide (a section body's width by default): the
769   * gauge's heavy line, each part in its own colour, `room` parts and the rest
770   * as the light rail (see `lineBar`).
771   */
772  const bar = (parts: Part[], max: number, opts: { height?: number; width?: number } = {}): RenderElement => {
773    const total = Math.max(max, parts.reduce((n, p) => n + Math.max(0, p.value), 0), 1)
774    if (terminal) {
775      const w = opts.width ?? body
776      return lineBar(parts, total, w)
777    }
778    // Grow factors out of 1000 (the desktop caps them at 10000): finer than a pixel at any width.
779    // Rounded by SVG end caps around a flat middle. Borders can't round it: on the desktop a
780    // border takes room inside the box, so a thin bordered track draws empty and bordered fills
781    // draw as blobs; glyph bars (◖━◗, ╺━╸) don't draw at all.
782    const height = opts.height ?? BAR
783    const shown = parts.filter(p => p.value > 0).map(p => ({ ...p, grow: (p.value / total) * 1000 }))
784    const rest = Math.max(0, 1000 - shown.reduce((n, p) => n + p.grow, 0))
785    // Not `h`: that's the JSX factory.
786    const flat = (rows: number | undefined) => (
787      <Box flexDirection="row" flexGrow={1} height={rows} backgroundColor={TRACK} overflow="hidden">
788        {/* An explicit full height: the desktop doesn't stretch a child to its parent's height. */}
789        {shown.map(p => (
790          <Box flexGrow={p.grow} flexShrink={0} width={0} height="100%" backgroundColor={p.color} />
791        ))}
792        {rest > 0 ? <Box flexGrow={rest} width={0} /> : null}
793      </Box>
794    )
795    // The caps sit inside the bar's width, so a scale under it still lines up with its ends.
796    const first = shown[0]?.color ?? TRACK
797    const last = rest > 0 ? TRACK : (shown[shown.length - 1]?.color ?? TRACK)
798    return capped(height, first, last, flat)
799  }
800
801  /**
802   * A label as GitHub draws one: a rounded chip filled with the label's colour,
803   * faint and see-through (FILL.pill), and its name in the theme's foreground, which
804   * reads on the light desktop theme and the dark one whatever the label's colour
805   * (a label without a hex colour gets the track's grey). On the
806   * terminal, a `■` swatch and the name in the default foreground: a label's
807   * colour is data (GitHub's hex) that may not read on the person's theme, so it
808   * only ever tints the one-cell swatch, never the text. A status colour (a kit
809   * token) draws as its theme key, as everywhere.
810   */
811  const pill = (key: string, text: string, color: string) => {
812    if (terminal) {
813      return (
814        <Text key={key}>
815          <Text {...(isKitColor(color) ? ink(color) : { color })}>■</Text>
816          {` ${text}`}
817        </Text>
818      )
819    }
820    return rounded(tint(color, FILL.pill) ?? TRACK, { key, flexDirection: 'row', paddingX: 0.6, flexShrink: 0 }, [<Text key="t">{text}</Text>])
821  }
822
823  /**
824   * A small mark of colour, a legend's key: a dot on the app surfaces, a square
825   * `■` on the terminal. `line: true` keys a line bar's part (`k.bar`) on the
826   * terminal with its own glyph: `━` for a part, `─` for a `room` one.
827   */
828  const swatch = (color: string, o: { line?: boolean; room?: boolean } = {}) => (
829    <Text {...ink(color)}>{terminal ? (o.line ? (o.room ? METER.rail : METER.line) : '■') : '●'}</Text>
830  )
831
832  /**
833   * A legend: each entry a key, a dim label and its figure. `note` is an optional
834   * coloured figure after it (a failure count). With `bar: true` (a legend that
835   * keys a `bar`, its items in the bar's order, `room` ones included) the
836   * terminal's keys are the bar's own glyphs, `━` and `─`.
837   *
838   * On the terminal it's a compact grid, filled row by row in the items' order:
839   * as many columns as fit with labels up to 10 cells (`maxCols`, 3 at most),
840   * 3 cells apart; then each column takes its share of the row, up to what its
841   * longest label, figure and note need, so labels widen into spare room and are
842   * cut with … only when it runs out, and a label stays close to its figure. The app surfaces
843   * share the row out in up to three columns.
844   */
845  const legend = (
846    key: string,
847    items: { label: string; color: string; figure: string; note?: string; noteColor?: string; room?: boolean }[],
848    maxCols?: number,
849    opts: { bar?: boolean } = {},
850  ) => {
851    if (terminal) {
852      const len = (s: string) => [...s].length
853      const longest = Math.max(1, ...items.map(t => len(t.label)))
854      const figW = Math.max(1, ...items.map(t => len(t.figure)))
855      const noteW = Math.max(0, ...items.map(t => (t.note ? len(t.note) + 1 : 0)))
856      const fixed = 2 + 1 + figW + noteW
857      const gap = 3
858      // How many columns fit is decided at the compact width (labels up to LABEL cells)...
859      const compact = fixed + Math.min(LABEL, longest)
860      const fit = Math.max(1, Math.floor((body + gap) / (compact + gap)))
861      const cols = Math.max(1, Math.min(maxCols ?? 3, fit, items.length))
862      const rows = Array.from({ length: Math.ceil(items.length / cols) }, (_, r) => items.slice(r * cols, r * cols + cols))
863      // ...then each column takes its share of the row, up to what its longest label needs,
864      // and the label has what's left after the key, figure and note.
865      const share = Math.floor((body - gap * (cols - 1)) / cols)
866      const width = Math.max(1, Math.min(fixed + longest, share))
867      const labelRoom = Math.max(1, width - fixed)
868      const fitLabel = (s: string) => (len(s) <= labelRoom ? s : [...s].slice(0, Math.max(0, labelRoom - 1)).join('') + MARK.more)
869      return (
870        <Box key={key} flexDirection="column">
871          {rows.map((row, r) => (
872            <Box key={`${key}-row-${r}`} flexDirection="row" gap={gap}>
873              {row.map(t => (
874                <Box key={`${key}-${t.label}`} flexDirection="row" width={width} flexShrink={0}>
875                  <Box width={2} flexShrink={0}>
876                    {swatch(t.color, { line: opts.bar, room: t.room })}
877                  </Box>
878                  <Box flexGrow={1} flexShrink={1} minWidth={0}>
879                    <Text {...R.label} wrap="truncate">
880                      {fitLabel(t.label)}
881                    </Text>
882                  </Box>
883                  <Box width={figW + 1} flexShrink={0} flexDirection="row" justifyContent="flex-end">
884                    <Text {...R.value}>{t.figure}</Text>
885                  </Box>
886                  {noteW ? (
887                    <Box width={noteW} flexShrink={0} flexDirection="row" justifyContent="flex-end">
888                      {t.note ? <Text {...ink(t.noteColor)}>{t.note}</Text> : null}
889                    </Box>
890                  ) : null}
891                </Box>
892              ))}
893            </Box>
894          ))}
895        </Box>
896      )
897    }
898    // Few rows: two columns for up to four entries, three beyond. (The pane's reported
899    // width in columns runs smaller than what the desktop draws, so it can't decide this.)
900    const cols = Math.min(maxCols ?? 3, items.length <= 4 ? 2 : 3, Math.max(1, items.length))
901    const per = Math.ceil(items.length / cols)
902    const groups = Array.from({ length: cols }, (_, c) => items.slice(c * per, c * per + per))
903    return (
904      // The legend spans the body (the desktop doesn't stretch a nested box), and its
905      // columns share that width equally, as a bar's parts do: grow from zero width.
906      <Box key={key} flexDirection="row" width="100%" gap={space.group}>
907        {groups.map((col, c) => (
908          <Box key={`${key}-col-${c}`} flexGrow={1} width={0} flexDirection="column">
909            {col.map(t => (
910              // The full column's width (the desktop doesn't stretch it); the label gives way first.
911              <Box key={`${key}-${t.label}`} flexDirection="row" alignItems="center" gap={space.pair} width="100%">
912                {swatch(t.color)}
913                <Box flexGrow={1} flexShrink={1} minWidth={0}>
914                  <Text {...tone('light')} wrap="truncate">
915                    {t.label}
916                  </Text>
917                </Box>
918                {t.note ? <Text {...ink(t.noteColor)}>{t.note}</Text> : null}
919                <Text>{t.figure}</Text>
920              </Box>
921            ))}
922          </Box>
923        ))}
924      </Box>
925    )
926  }
927
928  /** A caption: dim uppercase, for a chart's or a column's heading. The only uppercase besides a state word. */
929  const caption = (text: string) => <Text {...(terminal ? R.meta : tone('mid'))}>{text.toUpperCase()}</Text>
930
931  /**
932   * A header's figures, one form for every section: figures, each followed by
933   * a dim lowercase unit, SPACE.group apart. A figure is coloured only when the
934   * colour is a status. On the terminal the first figure is bold (the one that
935   * matters; put it first) and the rest plain.
936   *
937   * Its state, before the figures, so a cut never takes it:
938   * - `loading`: no figures yet (the first read): the pending mark `◌` holds
939   *   their place, so a folded section still says it's coming;
940   * - `age`: how old the figures are when they're last-good figures kept through
941   *   a refresh, as a dim `↻ 2m`;
942   * - `failed`: the last refresh failed and these are the last-good figures: an
943   *   amber `▲` (with the age after it, dim, when given). Keep the figures; don't
944   *   swap the body for an error.
945   */
946  const summary = (items: ([string, string?, string?] | null | false)[], state: { loading?: boolean; age?: string; failed?: boolean } = {}) => {
947    const shown = items.filter((x): x is [string, string?, string?] => Boolean(x))
948    const pending = state.loading && !shown.length
949    if (terminal) {
950      // One line of text, the figures CELLS.group apart: too wide for its room, it's
951      // cut wherever that falls and ends in an ellipsis, never mid-figure without one.
952      const mark = state.failed ? (
953        <Text key="state">
954          <Text {...ink(STATUS.warn.color)}>{STATUS.warn.glyph}</Text>
955          {state.age ? <Text {...R.secondary}>{` ${state.age}`}</Text> : null}
956          {shown.length ? ' '.repeat(CELLS.group) : null}
957        </Text>
958      ) : state.age ? (
959        <Text key="state" {...R.secondary}>
960          {`${MARK.stale} ${state.age}`}
961          {shown.length ? ' '.repeat(CELLS.group) : null}
962        </Text>
963      ) : null
964      return (
965        <Box flexDirection="row" minWidth={0} flexShrink={1}>
966          <Text wrap="truncate">
967            {pending ? <Text key="pending" {...ink(STATUS.pending.color)}>{STATUS.pending.glyph}</Text> : null}
968            {mark}
969            {shown.map(([figure, unit, color], i) => (
970              <Text key={`${figure}-${unit ?? ''}`}>
971                {i ? ' '.repeat(CELLS.group) : null}
972                {/* The first figure is the one that matters: bold; the rest plain. */}
973                <Text {...(i ? R.value : R.strong)} {...ink(color)}>{figure}</Text>
974                {unit ? <Text {...R.meta}>{` ${unit}`}</Text> : null}
975              </Text>
976            ))}
977          </Text>
978        </Box>
979      )
980    }
981    // Too wide for the band, the last item ends in an ellipsis and what's past it is cut.
982    return (
983      <Box flexDirection="row" gap={space.group} minWidth={0} flexShrink={1} overflow="hidden">
984        {pending ? <Text key="pending" color={STATUS.pending.color}>{STATUS.pending.glyph}</Text> : null}
985        {state.failed ? (
986          <Text key="state">
987            <Text color={STATUS.warn.color}>{STATUS.warn.glyph}</Text>
988            {state.age ? <Text {...tone('mid')}>{` ${state.age}`}</Text> : null}
989          </Text>
990        ) : state.age ? (
991          <Text key="state" {...tone('mid')}>{`${MARK.stale} ${state.age}`}</Text>
992        ) : null}
993        {shown.map(([figure, unit, color], i) => (
994          <Text key={`${figure}-${unit ?? ''}`} wrap={i === shown.length - 1 ? 'truncate' : undefined}>
995            <Text {...ink(color)}>{figure}</Text>
996            {unit ? <Text {...tone('mid')}>{` ${unit}`}</Text> : null}
997          </Text>
998        ))}
999      </Box>
1000    )
1001  }
1002
1003  /**
1004   * Labels under a chart, each centred under its place: `at` from 0 to 1 across
1005   * the chart's width (the first and last flush with its ends). On the terminal
1006   * one dim line `width` cells wide (a section body's by default; pass the
1007   * chart's): a label that would touch the one before it is left out.
1008   */
1009  const axis = (key: string, labels: { at: number; text: string }[], width?: number) => {
1010    const row: RenderElement[] = []
1011    const sorted = [...labels].sort((a, b) => a.at - b.at)
1012    if (terminal) {
1013      const w = Math.max(1, Math.floor(width ?? body))
1014      const line = Array.from({ length: w }, () => ' ')
1015      let free = 0
1016      for (const l of sorted) {
1017        const text = [...l.text]
1018        const start = Math.max(0, Math.min(w - text.length, Math.round(clamp01(l.at) * w - text.length / 2)))
1019        if (start < free || start + text.length > w) continue
1020        text.forEach((ch, i) => (line[start + i] = ch))
1021        free = start + text.length + 1
1022      }
1023      return (
1024        <Text key={key} dimColor>
1025          {line.join('').trimEnd()}
1026        </Text>
1027      )
1028    }
1029    sorted.forEach((l, i) => {
1030      // Each label owns the span halfway to its neighbours; the ends own up to the edge.
1031      const from = i === 0 ? 0 : (sorted[i - 1]!.at + l.at) / 2
1032      const to = i === sorted.length - 1 ? 1 : (l.at + sorted[i + 1]!.at) / 2
1033      const align = i === 0 && l.at === 0 ? 'flex-start' : i === sorted.length - 1 && l.at === 1 ? 'flex-end' : 'center'
1034      row.push(
1035        <Box key={`${key}-${i}`} flexGrow={Math.max(1, Math.round((to - from) * 1000))} width={0} flexDirection="row" justifyContent={align}>
1036          <Text {...tone('dark')}>{l.text}</Text>
1037        </Box>,
1038      )
1039    })
1040    return (
1041      <Box key={key} flexDirection="row">
1042        {row}
1043      </Box>
1044    )
1045  }
1046
1047  /**
1048   * An instrument's scale under a bar: ticks at 0, 25, 50, 75 and 100%, and a
1049   * marker where `mark` falls (a fraction of the scale), in `markColor`. On the
1050   * terminal a row `width` cells wide (a section body's by default, as `bar`):
1051   * dim ticks (╵) and the marker as ▴.
1052   */
1053  const scale = (mark?: number, markColor: string = C.warn, width?: number) => {
1054    if (terminal) {
1055      const w = Math.max(2, Math.floor(width ?? body))
1056      const row = Array.from({ length: w }, () => ' ')
1057      for (const at of [0, 0.25, 0.5, 0.75, 1]) row[Math.round(at * (w - 1))] = '╵'
1058      const m = mark === undefined ? -1 : Math.round(clamp01(mark) * (w - 1))
1059      if (m < 0) return <Text dimColor>{row.join('')}</Text>
1060      return (
1061        <Text>
1062          <Text dimColor>{row.slice(0, m).join('')}</Text>
1063          <Text {...ink(markColor)}>▴</Text>
1064          <Text dimColor>{row.slice(m + 1).join('')}</Text>
1065        </Text>
1066      )
1067    }
1068    // Every tick at its place on the scale, the marker among them, gaps between sized by flex-grow.
1069    const marks: Array<{ at: number; color: string; height: number }> = [0, 0.25, 0.5, 0.75, 1].map(at => ({ at, color: TRACK, height: 0.3 }))
1070    if (mark !== undefined) marks.push({ at: Math.max(0, Math.min(1, mark)), color: markColor, height: 0.45 })
1071    marks.sort((a, b) => a.at - b.at)
1072    const row: RenderElement[] = []
1073    marks.forEach((m, i) => {
1074      if (i > 0) row.push(<Box key={`g${i}`} flexGrow={Math.max(0, (m.at - marks[i - 1]!.at) * 1000)} width={0} />)
1075      row.push(<Box key={`m${i}`} width={0.12} height={m.height} backgroundColor={m.color} flexShrink={0} />)
1076    })
1077    return (
1078      <Box flexDirection="row" alignItems="flex-start" height={0.45}>
1079        {row}
1080      </Box>
1081    )
1082  }
1083
1084  /**
1085   * A section as a properties inspector draws one (Premiere's Effect Controls):
1086   * a collapsible header row (icon, title, figures, then the fold arrow last at
1087   * the right end) and its properties indented under it, the terminal's under the
1088   * title. The arrow (a Button, key `toggle-<id>`) folds it. No panel, outline or tint: rows and indentation do
1089   * the grouping. Collapsible when given `onToggle` (the mod keeps which are
1090   * folded in its state); folded, only the header row shows.
1091   */
1092  const section = (s: {
1093    id: string
1094    title: string
1095    /** An icon before the title (a GLYPH, drawn as the kit's SVG icon), always muted. */
1096    icon?: string
1097    right?: RenderElement | null
1098    collapsed?: boolean
1099    onToggle?: () => void
1100    /**
1101     * On the terminal, the right side (figures, buttons) keeps its natural width
1102     * and only the title is cut, with an ellipsis: for a header whose right side
1103     * is controls that must all show. Size the right side to fit the row yourself.
1104     * Without it, the title keeps up to 12 cells and then it and the figures give
1105     * way together. The desktop draws the same either way.
1106     */
1107    keepRight?: boolean
1108    /** No figures yet: with no `right`, the figure slot shows the pending mark (`summary([], { loading: true })`). */
1109    loading?: boolean
1110    /**
1111     * The figures restate what the body shows (the fullest of the readings under
1112     * it): the terminal draws them only while the body is hidden, folded or under
1113     * the narrow floor, so an open section doesn't say it twice.
1114     */
1115    restated?: boolean
1116    children: RenderElement | (RenderElement | null)[] | null
1117  }) => {
1118    if (s.loading && !s.right) s = { ...s, right: summary([], { loading: true }) }
1119    if (terminal) {
1120      // ◔ Title       figures ─────────────── ▾
1121      //   body, two cells in, under the title
1122      // A dim icon, the title bold, the figures on a shared column right after it
1123      // (TITLE_COL), a dim rule, then the dim fold arrow last, flush right. The icon
1124      // takes the GUTTER the body is indented by, so a title lines up with the
1125      // readings under it. No band or box. Every section leaves one blank row under
1126      // it, open or folded.
1127      const arrow = s.collapsed ? FOLD.closed : FOLD.open
1128      const toggle =
1129        s.onToggle && Button ? (
1130          <Button key={`toggle-${s.id}`} plain dimColor label={arrow} onPress={() => s.onToggle?.()} />
1131        ) : (
1132          <Text dimColor>{arrow}</Text>
1133        )
1134      // The arrow keeps its cell whatever else gives way; `gap` is its room when the row has no gap of its own.
1135      const arrowBox = (gap: number) => (
1136        <Box key="fold" flexShrink={0} marginLeft={gap}>
1137          {toggle}
1138        </Box>
1139      )
1140      const lead = s.icon ? GUTTER : 0
1141      const titleCells = [...s.title].length
1142      const keeps = Math.min(titleCells, 12)
1143      // Under MIN_COLUMNS, the header and its figures only: the body is left out.
1144      const open = !s.collapsed && !floor
1145      const right = s.restated && open ? null : s.right
1146      const head = [
1147        s.icon ? (
1148          <Box key="icon" width={GUTTER} flexShrink={0}>
1149            {icon(s.icon, termHeaderIcon())}
1150          </Box>
1151        ) : null,
1152        <Box key="name" flexShrink={1} minWidth={0}>
1153          <Text wrap="truncate" {...R.title}>
1154            {s.title}
1155          </Text>
1156        </Box>,
1157      ]
1158      // The rule takes only the room left: from no width, cut at its box's edge.
1159      const rule = (
1160        <Box key="rule" flexGrow={1} flexShrink={1} width={0} minWidth={0} height={1} overflow="hidden">
1161          <Text dimColor>{METER.rail.repeat(Math.max(1, Math.floor(columns)))}</Text>
1162        </Box>
1163      )
1164      const row = s.keepRight ? (
1165        // Controls on the right edge: they keep their width and only the title is cut.
1166        <Box flexDirection="row" gap={CELLS.item}>
1167          <Box key="title" flexDirection="row" flexShrink={1} minWidth={lead + 1}>
1168            {head}
1169          </Box>
1170          {rule}
1171          {right ? (
1172            <Box key="right" flexDirection="row" minWidth={0} flexShrink={0} overflow="hidden">
1173              {right}
1174            </Box>
1175          ) : null}
1176          {arrowBox(0)}
1177        </Box>
1178      ) : (
1179        // The title's column gives way first (down to 12 cells of title), then the figures; the rule
1180        // only ever takes what's left.
1181        <Box flexDirection="row">
1182          <Box
1183            key="title"
1184            flexDirection="row"
1185            // Without figures the rule follows the title; with them, they start on the shared column.
1186            width={lead + (right ? Math.max(TITLE_COL, titleCells) + CELLS.group : titleCells + CELLS.item)}
1187            flexShrink={1000}
1188            minWidth={lead + keeps + (right ? CELLS.group : CELLS.item)}
1189          >
1190            {head}
1191          </Box>
1192          {right ? (
1193            <Box key="right" flexDirection="row" minWidth={0} flexShrink={1} overflow="hidden" marginRight={CELLS.item}>
1194              {right}
1195            </Box>
1196          ) : null}
1197          {rule}
1198          {arrowBox(CELLS.item)}
1199        </Box>
1200      )

1import type { RenderElement } from 'claude-code'
2
3import * as S from './svg'
4
5/*
6 * The lab's catalogue: one experiment per question about what the rendering
7 * engine accepts. Each `draw` builds its tree from the elements it is handed
8 * (`$.ui.resolve(e)` in the engine, Storybook's own in a story) and the global
9 * JSX `h`, nothing else, so the same code runs in both.
10 */
11
12export type Surface = 'desktop' | 'terminal' | 'vscode' | 'mobile'
13export type Group = 'Graphics' | 'Animation' | 'Interaction' | 'Layout' | 'Text' | 'Elements'
14
15export type Experiment = {
16  id: string
17  group: Group
18  title: string
19  /** What it tests, one line. */
20  question: string
21  /** Where it is meant to draw; the tests mount it on the others too, to record refusals. */
22  surfaces: Surface[]
23  draw: (els: any, surface: string) => RenderElement
24}
25
26export const SURFACES: Surface[] = ['desktop', 'terminal', 'vscode', 'mobile']
27const REMOTE: Surface[] = ['desktop', 'vscode', 'mobile']
28const ALL: Surface[] = SURFACES
29const CLIENT: Surface[] = ['terminal', 'desktop']
30const FIELDS: Surface[] = ['desktop', 'terminal', 'vscode']
31
32/** Standard padded base64 of bytes; the environment's own `toBase64` is not everywhere. */
33const ABC = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
34export const base64 = (bytes: Uint8Array): string => {
35  let out = ''
36  for (let i = 0; i < bytes.length; i += 3) {
37    const a = bytes[i] ?? 0
38    const b = bytes[i + 1] ?? 0
39    const c = bytes[i + 2] ?? 0
40    const n = (a << 16) | (b << 8) | c
41    out += ABC[(n >> 18) & 63]! + ABC[(n >> 12) & 63]!
42    out += i + 1 < bytes.length ? ABC[(n >> 6) & 63]! : '='
43    out += i + 2 < bytes.length ? ABC[n & 63]! : '='
44  }
45  return out
46}
47
48/** Raster cells: `[codePoint, fg, bg]` u32 triplets, little-endian, base64. */
49const cells = (triplets: number[]) => {
50  const words = Uint32Array.from(triplets)
51  return base64(new Uint8Array(words.buffer))
52}
53
54/** A hue ramp across `columns` x `rows` cells, half blocks for two pixels a cell. */
55const rampCells = (columns: number, rows: number) => {
56  const t: number[] = []
57  const rgb = (h: number) => {
58    const f = (n: number) => {
59      const k = (n + h * 6) % 6
60      return Math.round(255 * (1 - Math.max(0, Math.min(k, 4 - k, 1))))
61    }
62    return (f(5) << 16) | (f(3) << 8) | f(1)
63  }
64  for (let y = 0; y < rows; y++) {
65    for (let x = 0; x < columns; x++) t.push(0x2580, rgb((x + y * 2) / columns), rgb((x + y * 2 + 1) / columns))
66  }
67  return cells(t)
68}
69
70/** 16 x 16 RGBA pixels: a radial blob. */
71const rgbaBlob = () => {
72  const px = new Uint8Array(16 * 16 * 4)
73  for (let y = 0; y < 16; y++) {
74    for (let x = 0; x < 16; x++) {
75      const d = Math.hypot(x - 7.5, y - 7.5) / 8
76      const i = (y * 16 + x) * 4
77      px[i] = 47
78      px[i + 1] = 128
79      px[i + 2] = 237
80      px[i + 3] = Math.max(0, Math.round(255 * (1 - d)))
81    }
82  }
83  return base64(px)
84}
85
86/** A 1 x 1 PNG pixel. */
87const PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=='
88
89const svg = (els: any, source: string, alt: string, isInteractive?: boolean, extra?: object) => {
90  const { Svg } = els
91  return <Svg source={source} alt={alt} isInteractive={isInteractive || undefined} {...extra} />
92}
93
94/** A labelled row: a dim label, then what it shows. */
95const row = (els: any, label: string, child: any, key?: string) => {
96  const { Box, Text } = els
97  return (
98    <Box key={key} flexDirection="row" gap={1}>
99      <Box width={18} flexShrink={0}>
100        <Text dimColor wrap="truncate-end">
101          {label}
102        </Text>
103      </Box>
104      {child}
105    </Box>
106  )
107}
108
109const col = (els: any, ...children: any[]) => {
110  const { Box } = els
111  return (
112    <Box flexDirection="column" gap={1}>
113      {children}
114    </Box>
115  )
116}
117
118const note = (els: any, text: string) => {
119  const { Text } = els
120  return <Text dimColor>{text}</Text>
121}
122
123const SAMPLE_TS = `export const total = (xs: number[]) =>
124  xs.reduce((sum, x) => sum + x, 0)
125
126// a very long line to see wrapping: ${'abcdefghij '.repeat(12)}
127const answer = total([40, 2])`
128
129const SAMPLE_DIFF = `@@ -1,5 +1,6 @@
130 import { a } from './a'
131-const b = a + 1
132+const b = a + 2
133+const c = b * 2
134 export default b
135 // end`
136
137const MARKDOWN = `## Markdown, as a reply draws it
138
139Some **bold**, _italic_, \`code\`, ~~struck~~ and a [link](https://example.com).
140
141| Surface | Svg | Client |
142| --- | --- | --- |
143| desktop | yes | yes |
144| terminal | no | yes |
145
146- one
147- two
148  - nested
149
150\`\`\`ts
151const x: number = 42
152\`\`\`
153
154> a quote
155
156<context>a context block, drawn as written here</context>`
157
158/** The colour strings the backgroundColor experiments try, by id. */
159const BACKGROUNDS: [string, string][] = [
160  ['hex', '#2f80ed'],
161  ['hex-short', '#28e'],
162  ['hex-alpha', '#2f80ed55'],
163  ['named', 'tomato'],
164  ['ansi-name', 'blueBright'],
165  ['theme-key', 'success'],
166  ['rgb', 'rgb(47, 128, 237)'],
167  ['rgba', 'rgba(47, 128, 237, 0.3)'],
168  ['transparent', 'transparent'],
169  ['hsl', 'hsl(140 60% 40%)'],
170  ['linear-gradient', 'linear-gradient(90deg, #2f80ed, #9b51e0)'],
171  ['radial-gradient', 'radial-gradient(circle, #f2994a, transparent)'],
172  ['css-var', 'var(--accent)'],
173]
174
175export const experiments: Experiment[] = [
176  // Graphics
177  {
178    id: 'svg-linear-gradient',
179    group: 'Graphics',
180    title: 'Linear gradients',
181    question: 'Does an Svg draw linearGradient fills, horizontal and vertical, with stop-opacity?',
182    surfaces: REMOTE,
183    draw: els => svg(els, S.LINEAR, 'Two linear gradient bars and a vertical gradient'),
184  },
185  {
186    id: 'svg-radial-gradient',
187    group: 'Graphics',
188    title: 'Radial gradients',
189    question: 'Does an Svg draw radialGradient fills (an off-centre sphere, a fading glow)?',
190    surfaces: REMOTE,
191    draw: els => svg(els, S.RADIAL, 'A shaded sphere and a glow'),
192  },
193  {
194    id: 'svg-blur',
195    group: 'Graphics',
196    title: 'Blur filter',
197    question: 'Does feGaussianBlur draw, at stdDeviation 1 and 4?',
198    surfaces: REMOTE,
199    draw: els => svg(els, S.BLUR, 'A square sharp, slightly blurred and very blurred'),
200  },
201  {
202    id: 'svg-drop-shadow',
203    group: 'Graphics',
204    title: 'Drop shadow',
205    question: 'Does feDropShadow draw, and the older blur, offset and merge chain?',
206    surfaces: REMOTE,
207    draw: els => svg(els, S.SHADOW, 'Two cards with drop shadows'),
208  },
209  {
210    id: 'svg-masks',
211    group: 'Graphics',
212    title: 'Clip, mask, opacity',
213    question: 'Do clipPath, a gradient mask, opacity and fill-opacity draw?',
214    surfaces: REMOTE,
215    draw: els => svg(els, S.MASKS, 'A clipped circle, a masked fade and translucent bars'),
216  },
217  {
218    id: 'svg-text',
219    group: 'Graphics',
220    title: 'SVG text and fonts',
221    question: 'Which font families, weights, styles, anchors and textPath does Svg text draw?',
222    surfaces: REMOTE,
223    draw: els => svg(els, S.FONTS, 'Text in sans, serif and mono, and text along a path'),
224  },
225  {
226    id: 'svg-pattern-use',
227    group: 'Graphics',
228    title: 'Pattern, marker, use',
229    question: 'Do pattern fills, markers and symbol + use (internal href) draw?',
230    surfaces: REMOTE,
231    draw: els => svg(els, S.PATTERN, 'A hatched box, an arrow and two reused dots'),
232  },
233  {
234    id: 'svg-size',
235    group: 'Graphics',
236    title: 'Svg width and height',
237    question: 'Do the width and height props scale the same markup (CSS pixels)?',
238    surfaces: REMOTE,
239    draw: els =>
240      col(
241        els,
242        row(els, 'markup size', svg(els, S.RADIAL, 'Sphere at its own size')),
243        row(els, 'width 120', svg(els, S.RADIAL, 'Sphere at 120 wide', false, { width: 120 })),
244        row(els, '480 x 40', svg(els, S.RADIAL, 'Sphere stretched', false, { width: 480, height: 40 })),
245      ),
246  },
247  {
248    id: 'svg-limit-ok',
249    group: 'Graphics',
250    title: 'Svg at 131072 characters',
251    question: 'Is an Svg source of exactly 131072 characters accepted?',
252    surfaces: REMOTE,
253    draw: els => svg(els, S.sized(131072), 'A source exactly at the cap'),
254  },
255  {
256    id: 'svg-limit-over',
257    group: 'Graphics',
258    title: 'Svg at 131073 characters',
259    question: 'Is an Svg source one character past the cap refused, and with what reason?',
260    surfaces: [],
261    draw: els => svg(els, S.sized(131073), 'A source one past the cap'),
262  },
263  {
264    id: 'svg-not-svg',
265    group: 'Graphics',
266    title: 'Svg with no <svg> root',
267    question: 'Does the validator check that source is an SVG document at all?',
268    surfaces: [],
269    draw: els => svg(els, '<div>not svg</div>', 'An HTML fragment'),
270  },
271  {
272    id: 'svg-no-alt',
273    group: 'Graphics',
274    title: 'Svg with an empty alt',
275    question: 'Is alt required to be non-empty?',
276    surfaces: [],
277    draw: els => svg(els, S.RADIAL, ''),
278  },
279  {
280    id: 'scrub-script',
281    group: 'Graphics',
282    title: 'Scrub: <script>',
283    question: 'Is a <script> inside an interactive Svg stripped or blocked? (green text means it did not run)',
284    surfaces: REMOTE,
285    draw: els => svg(els, S.SCRUB_SCRIPT, 'A script that would rewrite the text', true),
286  },
287  {
288    id: 'scrub-onload',
289    group: 'Graphics',
290    title: 'Scrub: event attributes',
291    question: 'Are onload and onclick attributes stripped in an interactive Svg?',
292    surfaces: REMOTE,
293    draw: els => svg(els, S.SCRUB_ONLOAD, 'Event attributes that would rewrite the text', true),
294  },
295  {
296    id: 'scrub-href',
297    group: 'Graphics',
298    title: 'Scrub: external href',
299    question: 'Does an <image> or <a> with an external https href load, or is it stripped?',
300    surfaces: REMOTE,
301    draw: els => svg(els, S.SCRUB_HREF, 'An external image and link', true),
302  },
303  {
304    id: 'scrub-data-href',
305    group: 'Graphics',
306    title: 'Scrub: data: href',
307    question: 'Does an <image> with a data: URI draw?',
308    surfaces: REMOTE,
309    draw: els => svg(els, S.SCRUB_DATA_HREF, 'A data URI image'),
310  },
311  {
312    id: 'scrub-foreign',
313    group: 'Graphics',
314    title: 'Scrub: <foreignObject>',
315    question: 'Does <foreignObject> HTML draw inside an interactive Svg?',
316    surfaces: REMOTE,
317    draw: els => svg(els, S.SCRUB_FOREIGN, 'HTML inside foreignObject', true),
318  },
319
320  // Animation
321  {
322    id: 'smil-interactive',
323    group: 'Animation',
324    title: 'SMIL, interactive',
325    question: 'With isInteractive, do SMIL animate/animateTransform blink, fade, rotate, morph d and grow?',
326    surfaces: REMOTE,
327    draw: els => svg(els, S.SMIL, 'Five SMIL animations', true),
328  },
329  {
330    id: 'smil-image',
331    group: 'Animation',
332    title: 'SMIL as an image',
333    question: 'Without isInteractive (drawn as an image), does SMIL still animate?',
334    surfaces: REMOTE,
335    draw: els => svg(els, S.SMIL, 'Five SMIL animations, as an image'),
336  },
337  {
338    id: 'css-interactive',
339    group: 'Animation',
340    title: 'CSS @keyframes, interactive',
341    question: 'With isInteractive, do CSS @keyframes in a <style> animate (spin, pulse, slide)?',
342    surfaces: REMOTE,
343    draw: els => svg(els, S.CSS_KEYFRAMES, 'Three CSS animations', true),
344  },
345  {
346    id: 'css-image',
347    group: 'Animation',
348    title: 'CSS @keyframes as an image',
349    question: 'Without isInteractive, do CSS @keyframes still animate?',
350    surfaces: REMOTE,
351    draw: els => svg(els, S.CSS_KEYFRAMES, 'Three CSS animations, as an image'),
352  },
353  {
354    id: 'client-blink',
355    group: 'Animation',
356    title: 'Client: blinking dot',
357    question: 'Does a Client surface module blink a dot with surface.every(500) + setState?',
358    surfaces: CLIENT,
359    draw: els => {
360      const { Client } = els
361      return <Client key="blink" module="./clients/blink.tsx" props={{ ms: 500 }} />
362    },
363  },
364  {
365    id: 'client-fade',
366    group: 'Animation',
367    title: 'Client: colour fade',
368    question: 'Does stepping a Text colour every 80 ms read as a fade, and dimColor toggle?',
369    surfaces: CLIENT,
370    draw: els => {
371      const { Client } = els
372      return <Client key="fade" module="./clients/fade.tsx" props={{}} />
373    },
374  },
375  {
376    id: 'client-bar',
377    group: 'Animation',
378    title: 'Client: growing bar',
379    question: 'Does a bar grow smoothly in eighth-cell steps every 50 ms, sized from surface.columns?',
380    surfaces: CLIENT,
381    draw: els => {
382      const { Client } = els
383      return <Client key="bar" module="./clients/bar.tsx" props={{}} width="100%" />
384    },
385  },
386  {
387    id: 'client-spinner',
388    group: 'Animation',
389    title: 'Client: spinner',
390    question: 'Does a braille spinner turn at 80 ms a frame?',
391    surfaces: CLIENT,
392    draw: els => {
393      const { Client } = els
394      return <Client key="spinner" module="./clients/spinner.tsx" props={{ label: 'spinning on the frame clock' }} />
395    },
396  },
397  {
398    id: 'client-fps',
399    group: 'Animation',
400    title: 'Client: frame-clock ceiling',
401    question: 'Asked for a tick every 1 ms and every 16 ms, how many ticks a second actually arrive?',
402    surfaces: CLIENT,
403    draw: els => {
404      const { Box, Client } = els
405      return (
406        <Box flexDirection="column" gap={1}>
407          <Client key="fps1" module="./clients/fps.tsx" props={{ ms: 1 }} />
408          <Client key="fps16" module="./clients/fps.tsx" props={{ ms: 16 }} />
409        </Box>
410      )
411    },
412  },
413
414  // Interaction
415  {
416    id: 'svg-hover',
417    group: 'Interaction',
418    title: 'SVG CSS :hover',
419    question: 'With isInteractive, does CSS :hover (with transitions) restyle SVG shapes?',
420    surfaces: REMOTE,
421    draw: els => svg(els, S.HOVER, 'Three cells and a circle that react to hover', true),
422  },
423  {
424    id: 'svg-title',
425    group: 'Interaction',
426    title: 'SVG <title> tooltip',
427    question: 'With isInteractive, does a <title> child show a native tooltip on hover?',
428    surfaces: REMOTE,
429    draw: els => svg(els, S.TITLE, 'Shapes with tooltips', true),
430  },
431  {
432    id: 'box-hover',
433    group: 'Interaction',
434    title: 'Box hover',
435    question: 'In a keyed Box, do hover backgroundColor, borderColor and a display none to flex reveal apply?',
436    surfaces: ALL,
437    draw: els => {
438      const { Box, Text } = els
439      return (
440        <Box flexDirection="column" gap={1}>
441          <Box key="bg" paddingX={1} hover={{ backgroundColor: '#2f80ed' }}>
442            <Text hover={{ color: '#ffffff', bold: true }}>hover me: background and text</Text>
443          </Box>
444          <Box key="border" borderStyle="round" borderColor="#3a3a3c" paddingX={1} hover={{ borderColor: '#27ae60' }}>
445            <Text>hover me: border colour</Text>
446          </Box>
447          <Box key="reveal" flexDirection="row" gap={1}>
448            <Text>hover me to reveal:</Text>
449            <Box display="none" hover={{ display: 'flex' }}>
450              <Text color="#eb5757">revealed</Text>
451            </Box>
452          </Box>
453        </Box>
454      )
455    },
456  },
457  {
458    id: 'hover-scope',
459    group: 'Interaction',
460    title: 'Hover scope groups',
461    question: 'Do elements sharing a hover scope light together, without a keyed Box?',
462    surfaces: ALL,
463    draw: els => {
464      const { Box, Text } = els
465      return (
466        <Box flexDirection="column" gap={1}>
467          <Text hover={{ scope: 'alpha', color: '#2f80ed', bold: true }}>alpha: row one</Text>
468          <Text>unrelated row</Text>
469          <Text hover={{ scope: 'alpha', color: '#2f80ed', bold: true }}>alpha: row two (lights with one)</Text>
470          <Box flexDirection="row" gap={1}>
471            <Text hover={{ scope: 'beta', inverse: true }}>beta</Text>
472            <Box display="none" hover={{ scope: 'beta', display: 'flex' }}>
473              <Text color="#27ae60">beta revealed</Text>
474            </Box>
475          </Box>
476        </Box>
477      )
478    },
479  },
480  {
481    id: 'box-absolute',
482    group: 'Interaction',
483    title: 'Absolute hover card',
484    question: 'Does a position absolute Box revealed on hover paint over the rows above without moving them?',
485    surfaces: ALL,
486    draw: els => {
487      const { Box, Text } = els
488      return (
489        <Box flexDirection="column">
490          <Text>row one</Text>
491          <Text>row two</Text>
492          <Text>row three</Text>
493          <Box key="anchor" flexDirection="row">
494            <Text color="#2f80ed">◆ hover this glyph</Text>
495            <Box
496              position="absolute"
497              top={-3}
498              left={4}
499              display="none"
500              hover={{ display: 'flex' }}
501              borderStyle="round"
502              backgroundColor="#1c1c1e"
503              paddingX={1}
504            >
505              <Text color="#ffffff">a card over the rows above</Text>
506            </Box>
507          </Box>
508          <Text>row after</Text>
509        </Box>
510      )
511    },
512  },
513  {
514    id: 'buttons',
515    group: 'Interaction',
516    title: 'Button variants',
517    question: 'How do plain, primary, secondary, dismiss, hotkey, dimColor and Text children draw?',
518    surfaces: ALL,
519    draw: els => {
520      const { Box, Button, Text } = els
521      const nop = () => undefined
522      return (
523        <Box flexDirection="column" gap={1}>
524          <Box flexDirection="row" gap={1}>
525            <Button key="default" label="Default" onPress={nop} />
526            <Button key="primary" label="Primary" variant="primary" onPress={nop} />
527            <Button key="secondary" label="Secondary" variant="secondary" onPress={nop} />
528            <Button key="dismiss" label="Dismiss" role="dismiss" onPress={nop} />
529          </Box>
530          <Box flexDirection="row" gap={1}>
531            <Button key="plain" plain label="Plain" onPress={nop} />
532            <Button key="hot" plain hotkey="1" label="Plain with hotkey" onPress={nop} />
533            <Button key="hot2" hotkey="w" label="Hotkey w" onPress={nop} />
534            <Button key="dim" dimColor label="Dim" onPress={nop} />
535          </Box>
536          <Button key="rowbtn" plain onPress={nop}>
537            A whole row <Text dimColor>2m ago</Text> <Text color="#27ae60">chip</Text>
538          </Button>
539        </Box>
540      )
541    },
542  },
543  {
544    id: 'button-bad-hotkey',
545    group: 'Interaction',
546    title: 'Button with a two-letter hotkey',
547    question: 'Is a hotkey other than one digit or lowercase letter refused?',
548    surfaces: [],
549    draw: els => {
550      const { Button } = els
551      return <Button key="bad" hotkey="ab" label="ab" onPress={() => undefined} />
552    },
553  },
554  {
555    id: 'button-box-child',
556    group: 'Interaction',
557    title: 'Button holding a Box',
558    question: 'Is a Button with a Box child refused?',
559    surfaces: [],
560    draw: els => {
561      const { Box, Button, Text } = els
562      return (
563        <Button key="boxed" onPress={() => undefined}>
564          <Box>
565            <Text>inside</Text>
566          </Box>
567        </Button>
568      )
569    },
570  },
571  {
572    id: 'input-select',
573    group: 'Interaction',
574    title: 'Input and Select',
575    question: 'Do Input (label, placeholder, value, submitLabel) and Select draw and take input?',
576    surfaces: FIELDS,
577    draw: els => {
578      const { Box, Input, Select } = els
579      return (
580        <Box flexDirection="column" gap={1}>
581          <Input key="name" label="Name" placeholder="type here" submitLabel="save" onSubmit={() => undefined} onInput={() => undefined} />
582          <Input key="prefilled" label="Prefilled" value="hello" onSubmit={() => undefined} />
583          <Select
584            key="pick"
585            label="Pick"
586            value="b"
587            options={[
588              { value: 'a', label: 'Alpha' },
589              { value: 'b', label: 'Beta' },
590              { value: 'c', label: 'Gamma' },
591            ]}
592            onSelect={() => undefined}
593          />
594        </Box>
595      )
596    },
597  },
598  {
599    id: 'select-duplicate',
600    group: 'Interaction',
601    title: 'Select with duplicate values',
602    question: 'Are duplicate option values refused?',
603    surfaces: [],
604    draw: els => {
605      const { Select } = els
606      return (
607        <Select
608          key="dup"
609          options={[
610            { value: 'a', label: 'One' },
611            { value: 'a', label: 'Two' },
612          ]}
613          onSelect={() => undefined}
614        />
615      )
616    },
617  },
618  {
619    id: 'links',
620    group: 'Interaction',
621    title: 'Links by scheme',
622    question: 'Which hrefs draw as links (https, http, file, mailto, javascript) and which as plain text?',
623    surfaces: ALL,
624    draw: els => {
625      const { Box, Link } = els
626      return (
627        <Box flexDirection="column">
628          {row(els, 'https', <Link href="https://example.com" label="https://example.com" />)}
629          {row(els, 'http', <Link href="http://example.com" label="http://example.com" />)}
630          {row(els, 'file', <Link href="file:///etc/hosts" label="file:///etc/hosts" />)}
631          {row(els, 'mailto', <Link href="mailto:someone@example.com" label="mailto:" />)}
632          {row(els, 'javascript', <Link href="javascript:alert(1)" label="javascript:" />)}
633          {row(els, 'no label', <Link href="https://example.com/bare" />)}
634        </Box>
635      )
636    },
637  },
638  {
639    id: 'link-too-long',
640    group: 'Interaction',
641    title: 'Link past 2048 characters',
642    question: 'Is a Link whose href is longer than 2048 characters refused?',
643    surfaces: [],
644    draw: els => {
645      const { Link } = els
646      return <Link href={`https://example.com/${'a'.repeat(2100)}`} label="long" />
647    },
648  },
649  {
650    id: 'markdown-links',
651    group: 'Interaction',
652    title: 'Markdown answering its links',
653    question: 'Does onLinkPress take a link press, and pressableLinks narrow which?',
654    surfaces: ALL,
655    draw: els => {
656      const { Markdown } = els
657      return (
658        <Markdown
659          key="md-links"
660          text={'Press [this one](https://example.com/mine) or [this other](https://example.com/theirs), which opens normally.'}
661          pressableLinks={['https://example.com/mine']}
662          onLinkPress={() => undefined}
663        />
664      )
665    },
666  },
667  {
668    id: 'client-pointer',
669    group: 'Interaction',
670    title: 'Client: pointer following',
671    question: 'Does onPointer report down, move, up, enter and leave in cells (and fine sub-cell positions)?',
672    surfaces: CLIENT,
673    draw: els => {
674      const { Client } = els
675      return <Client key="pointer" module="./clients/pointer.tsx" props={{}} width="100%" height={6} />
676    },
677  },
678  {
679    id: 'client-keys',
680    group: 'Interaction',
681    title: 'Client: keys',
682    question: 'Once clicked, does a Client receive keys through onKey?',
683    surfaces: CLIENT,
684    draw: els => {
685      const { Client } = els
686      return <Client key="keys" module="./clients/keys.tsx" props={{}} />
687    },
688  },
689  {
690    id: 'client-post',
691    group: 'Interaction',
692    title: 'Client: post round trip',
693    question: "Does surface.post reach the hooks module's ui.message, and its { props } answer come back?",
694    surfaces: CLIENT,
695    draw: els => {
696      const { Client } = els
697      return <Client key="echo" module="./clients/echo.tsx" props={{}} />
698    },
699  },
700
701  // Layout
702  {
703    id: 'borders',
704    group: 'Layout',
705    title: 'Border styles',
706    question: 'Which borderStyle values draw: single, double, round, bold, singleDouble, doubleSingle, classic, arrow, dashed, quote?',
707    surfaces: ALL,
708    draw: els => {
709      const { Box, Text } = els
710      const styles = ['single', 'double', 'round', 'bold', 'singleDouble', 'doubleSingle', 'classic', 'arrow', 'dashed', 'quote']
711      return (
712        <Box flexDirection="row" flexWrap="wrap" gap={1}>
713          {styles.map(style => (
714            <Box borderStyle={style} borderColor="#2f80ed" paddingX={1}>
715              <Text>{style}</Text>
716            </Box>
717          ))}
718          <Box borderStyle="round" borderDimColor paddingX={1}>
719            <Text>dim border</Text>
720          </Box>
721        </Box>
722      )
723    },
724  },
725  {
726    id: 'border-unknown',
727    group: 'Layout',
728    title: 'Unknown border style',
729    question: 'Is borderStyle "wavy" refused, or drawn without a border?',
730    surfaces: ALL,
731    draw: els => {
732      const { Box, Text } = els
733      return (
734        <Box borderStyle="wavy" paddingX={1}>
735          <Text>borderStyle wavy</Text>
736        </Box>
737      )
738    },
739  },
740  // One experiment per colour string, so each refusal is its own.
741  ...BACKGROUNDS.map(
742    ([id, color]): Experiment => ({
743      id: `bg-${id}`,
744      group: 'Layout',
745      title: `backgroundColor ${color}`,
746      question: `Is a Box backgroundColor of "${color}" accepted (Box and Text), and what paints?`,
747      surfaces: ALL,
748      draw: els => {
749        const { Box, Text } = els
750        return (
751          <Box flexDirection="column" gap={1}>
752            <Box width={24} height={2} backgroundColor={color} paddingX={1}>
753              <Text>Box</Text>
754            </Box>
755            <Text backgroundColor={color}> Text with it </Text>
756          </Box>
757        )
758      },
759    }),
760  ),
761  {
762    id: 'pct-whole',
763    group: 'Layout',
764    title: 'Whole percentages',
765    question: 'Do width percentages (25%, 50%, 100%) lay out?',
766    surfaces: ALL,
767    draw: els => {
768      const { Box, Text } = els
769      return (
770        <Box flexDirection="column" width="100%">
771          {['25%', '50%', '100%'].map(w => (
772            <Box width={w} backgroundColor="#2f80ed">
773              <Text color="#ffffff">{w}</Text>
774            </Box>
775          ))}
776        </Box>
777      )
778    },
779  },
780  {
781    id: 'pct-fraction',
782    group: 'Layout',
783    title: 'Fractional percentage',
784    question: 'Is width "25.5%" refused?',
785    surfaces: [],
786    draw: els => {
787      const { Box, Text } = els
788      return (
789        <Box width="25.5%">
790          <Text>25.5%</Text>
791        </Box>
792      )
793    },
794  },
795  {
796    id: 'flexgrow-limit',
797    group: 'Layout',
798    title: 'flexGrow past 10000',
799    question: 'Is flexGrow 10001 refused?',
800    surfaces: [],
801    draw: els => {
802      const { Box, Text } = els
803      return (
804        <Box flexGrow={10001}>
805          <Text>flexGrow 10001</Text>
806        </Box>
807      )
808    },
809  },
810  {
811    id: 'fractional-cells',
812    group: 'Layout',
813    title: 'Fractional heights and margins',
814    question: 'Are fractional height and margin values accepted?',
815    surfaces: ALL,
816    draw: els => {
817      const { Box, Text } = els
818      return (
819        <Box flexDirection="column">
820          <Box height={1.5} marginTop={0.5} backgroundColor="#27ae60">
821            <Text>height 1.5, marginTop 0.5</Text>
822          </Box>
823          <Text>after</Text>
824        </Box>
825      )
826    },
827  },
828  {
829    id: 'flex',
830    group: 'Layout',
831    title: 'Flex layout',
832    question: 'Do gap, wrap, justifyContent, alignItems, flexGrow and overflow hidden lay out as Ink does?',
833    surfaces: ALL,
834    draw: els => {
835      const { Box, Text } = els
836      return (
837        <Box flexDirection="column" gap={1}>
838          <Box flexDirection="row" justifyContent="space-between">
839            <Text>left</Text>
840            <Text>centre</Text>
841            <Text>right</Text>
842          </Box>
843          <Box flexDirection="row" gap={2} flexWrap="wrap">
844            {Array.from({ length: 12 }, (_, i) => (
845              <Text>item{i}</Text>
846            ))}
847          </Box>
848          <Box flexDirection="row">
849            <Box flexGrow={1} backgroundColor="#2f80ed">
850              <Text>grow 1</Text>
851            </Box>
852            <Box flexGrow={3} backgroundColor="#9b51e0">
853              <Text>grow 3</Text>
854            </Box>
855          </Box>
856          <Box width={12} height={1} overflow="hidden">
857            <Text>overflow hidden cuts this long text</Text>
858          </Box>
859        </Box>
860      )
861    },
862  },
863
864  // Text
865  {
866    id: 'text-styles',
867    group: 'Text',
868    title: 'Text styles',
869    question: 'Do bold, italic, underline, strikethrough, inverse, dimColor, color and backgroundColor draw?',
870    surfaces: ALL,
871    draw: els => {
872      const { Box, Text } = els
873      return (
874        <Box flexDirection="column">
875          <Text bold>bold</Text>
876          <Text italic>italic</Text>
877          <Text underline>underline</Text>
878          <Text strikethrough>strikethrough</Text>
879          <Text inverse>inverse</Text>
880          <Text dimColor>dimColor</Text>
881          <Text color="#eb5757">color #eb5757</Text>
882          <Text color="warning">color theme key warning</Text>
883          <Text backgroundColor="#2f80ed" color="#ffffff">
884            backgroundColor
885          </Text>
886          <Text>
887            nested: <Text bold>bold</Text> and <Text color="#27ae60">green</Text> in one line
888          </Text>
889        </Box>
890      )
891    },
892  },
893  {
894    id: 'text-wrap',
895    group: 'Text',
896    title: 'Text wrap modes',
897    question: 'How do wrap, end, middle, truncate, truncate-start, truncate-middle and truncate-end cut a long line?',
898    surfaces: ALL,
899    draw: els => {
900      const { Box, Text } = els
901      const long = 'The quick brown fox jumps over the lazy dog and keeps running past the edge of the pane'
902      const modes = ['wrap', 'end', 'middle', 'truncate', 'truncate-start', 'truncate-middle', 'truncate-end']
903      return (
904        <Box flexDirection="column">
905          {modes.map(m =>
906            row(
907              els,
908              m,
909              <Box width={30}>
910                <Text wrap={m}>{long}</Text>
911              </Box>,
912            ),
913          )}
914        </Box>
915      )
916    },
917  },
918  {
919    id: 'text-hover',
920    group: 'Text',
921    title: 'Text hover',
922    question: 'Does Text hover (colour, bold, underline, inverse) apply inside a keyed Box?',
923    surfaces: ALL,
924    draw: els => {
925      const { Box, Text } = els
926      return (
927        <Box key="texthover" flexDirection="column">
928          <Text hover={{ color: '#2f80ed' }}>colour on hover</Text>
929          <Text hover={{ bold: true, underline: true }}>bold and underline on hover</Text>
930          <Text dimColor hover={{ dimColor: false, inverse: true }}>dim to inverse on hover</Text>
931        </Box>
932      )
933    },
934  },
935  {
936    id: 'text-hover-unkeyed',
937    group: 'Text',
938    title: 'Text hover outside a keyed Box',
939    question: 'Is a Text hover with no keyed Box and no scope refused?',
940    surfaces: [],
941    draw: els => {
942      const { Text } = els
943      return <Text hover={{ color: '#2f80ed' }}>unkeyed hover</Text>
944    },
945  },
946  {
947    id: 'text-long',
948    group: 'Text',
949    title: 'Text past 100000 characters',
950    question: 'Is a 120000-character Text accepted, and cut at 100000?',
951    surfaces: ALL,
952    draw: els => {
953      const { Text } = els
954      return <Text>{'0123456789'.repeat(12000)}</Text>
955    },
956  },
957  {
958    id: 'text-glyphs',
959    group: 'Text',
960    title: 'Glyphs and emoji',
961    question: 'Do box drawing, blocks, braille, CJK and emoji draw in Text?',
962    surfaces: ALL,
963    draw: els => {
964      const { Box, Text } = els
965      return (
966        <Box flexDirection="column">
967          <Text>box ┌─┬─┐ ╭─╮ ═ ║ blocks ▁▂▃▄▅▆▇█ ░▒▓</Text>
968          <Text>braille ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ ⣿⣀</Text>
969          <Text>CJK 漢字 かな 한글</Text>
970          <Text>emoji 🚀 ✅ 👩‍💻 🏳️‍🌈</Text>
971        </Box>
972      )
973    },
974  },
975
976  // Elements
977  {
978    id: 'code-source',
979    group: 'Elements',
980    title: 'Code: source',
981    question: 'Does Code highlight TypeScript with a startLine gutter, and wrap vs truncate-end long lines?',
982    surfaces: ALL,
983    draw: els => {
984      const { Box, Code } = els
985      return (
986        <Box flexDirection="column" gap={1}>
987          <Code source={SAMPLE_TS} language="typescript" startLine={41} />
988          <Code source={SAMPLE_TS} path="example.ts" wrap="truncate-end" />
989        </Box>
990      )
991    },
992  },
993  {
994    id: 'code-diff',
995    group: 'Elements',
996    title: 'Code: diff',
997    question: "Does Code format 'diff' draw a unified diff with gutters and colours?",
998    surfaces: ALL,
999    draw: els => {
1000      const { Code } = els
1001      return <Code source={SAMPLE_DIFF} format="diff" path="b.ts" />
1002    },
1003  },
1004  {
1005    id: 'code-bad-diff',
1006    group: 'Elements',
1007    title: 'Code: diff with no hunk header',
1008    question: "Is a 'diff' with no @@ header refused, or drawn as plain code?",
1009    surfaces: ALL,
1010    draw: els => {
1011      const { Code } = els
1012      return <Code source={'-old\n+new'} format="diff" />
1013    },
1014  },
1015  {
1016    id: 'code-bad-wrap',
1017    group: 'Elements',
1018    title: "Code: wrap 'truncate'",
1019    question: "Is Code wrap 'truncate' (a Text spelling) refused?",
1020    surfaces: [],
1021    draw: els => {
1022      const { Code } = els
1023      return <Code source="x" wrap="truncate" />
1024    },
1025  },
1026  {
1027    id: 'markdown',
1028    group: 'Elements',
1029    title: 'Markdown',
1030    question: 'Does Markdown draw headings, emphasis, tables, lists, fences, quotes and a <context> block?',
1031    surfaces: ALL,
1032    draw: els => {
1033      const { Markdown } = els
1034      return <Markdown text={MARKDOWN} />
1035    },
1036  },
1037  {
1038    id: 'raster',
1039    group: 'Elements',
1040    title: 'Raster',
1041    question: 'Does a Raster draw a hue ramp of half-block cells with per-cell fg and bg?',
1042    surfaces: ['terminal'],
1043    draw: els => {
1044      const { Raster } = els
1045      return <Raster key="ramp" columns={48} rows={4} cells={rampCells(48, 4)} />
1046    },
1047  },
1048  {
1049    id: 'raster-wide-cell',
1050    group: 'Elements',
1051    title: 'Raster with a wide cell',
1052    question: 'Is a Raster cell holding a width-2 character refused, naming its index?',
1053    surfaces: [],
1054    draw: els => {
1055      const { Raster } = els
1056      return <Raster key="wide" columns={2} rows={1} cells={cells([0x41, 0xffffff, 0x01000000, 0x6f22, 0xffffff, 0x01000000])} />
1057    },
1058  },
1059  {
1060    id: 'image-png',
1061    group: 'Elements',
1062    title: 'Image: PNG',
1063    question: 'Does an Image of a base64 PNG draw (kitty graphics) or fall back to alt?',
1064    surfaces: ['terminal'],
1065    draw: els => {
1066      const { Image } = els
1067      return <Image key="png" source={{ png: PNG }} columns={8} rows={4} alt="a one-pixel PNG, scaled" />
1068    },
1069  },
1070  {
1071    id: 'image-rgba',
1072    group: 'Elements',
1073    title: 'Image: RGBA',
1074    question: 'Does an Image of raw RGBA bytes (16 x 16, with alpha) draw?',
1075    surfaces: ['terminal'],
1076    draw: els => {
1077      const { Image } = els
1078      return <Image key="rgba" source={{ rgba: rgbaBlob(), width: 16, height: 16 }} columns={8} rows={4} alt="a blue blob" />
1079    },
1080  },
1081]
1082
1083/** The experiments by group, in catalogue order. */
1084export const GROUPS: Group[] = ['Graphics', 'Animation', 'Interaction', 'Layout', 'Text', 'Elements']
1085
1086export const byId = (id: string) => experiments.find(x => x.id === id)
1087
1088/**
1089 * The experiments verdicts.json records the desktop refusing; the gallery
1090 * leaves them out so its one tree validates. lab.test.ts checks this list
1091 * against the run's own verdicts.
1092 */
1093export const DESKTOP_REFUSED = [
1094  'svg-limit-over',
1095  'button-bad-hotkey',
1096  'button-box-child',
1097  'select-duplicate',
1098  'link-too-long',
1099  'bg-radial-gradient',
1100  'pct-fraction',
1101  'flexgrow-limit',
1102  'text-hover-unkeyed',
1103  'code-bad-wrap',
1104]
1105
1106/**
1107 * What the gallery draws, in group order: every experiment the desktop
1108 * accepts. `text-long` goes last: a tree draws its first 100000 characters of
1109 * text, and its 120000 would cut every experiment after it.
1110 */
1111export const galleryExperiments = () => {
1112  const shown = GROUPS.flatMap(g => experiments.filter(x => x.group === g && !DESKTOP_REFUSED.includes(x.id)))
1113  return [...shown.filter(x => x.id !== 'text-long'), ...shown.filter(x => x.id === 'text-long')]
1114}
1115

1const trim = (n: number) => (n >= 100 ? String(Math.round(n)) : n.toFixed(1).replace(/\.0$/, ''))
2
3/** Token counts: 950, 1.2k, 84k, 1M. */
4export const tokens = (n: number): string => {
5  if (n >= 999_500) return `${trim(n / 1_000_000)}M`
6  if (n >= 1_000) return `${trim(n / 1_000)}k`
7  return String(Math.round(n))
8}
9
10/** A duration to the second: 12s, 3m 05s, 2h 05m. */
11export const duration = (ms: number): string => {
12  const s = Math.max(0, Math.floor(ms / 1_000))
13  if (s < 60) return `${s}s`
14  const m = Math.floor(s / 60)
15  if (m < 60) return `${m}m ${String(s % 60).padStart(2, '0')}s`
16  return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, '0')}m`
17}
18
19/** A duration at a glance: 47m, 2h05, 3d4h. */
20export const short = (ms: number): string => {
21  const m = Math.max(0, Math.floor(ms / 60_000))
22  if (m < 60) return `${m}m`
23  const h = Math.floor(m / 60)
24  if (h < 24) return `${h}h${String(m % 60).padStart(2, '0')}`
25  return `${Math.floor(h / 24)}d${h % 24}h`
26}
27
28/** How long ago, coarsely, as GitHub lists things: 5m, 3h, 2d, 3w, 4mo, 2y. */
29export const ago = (ms: number): string => {
30  const m = Math.max(0, Math.floor(ms / 60_000))
31  if (m < 60) return `${m}m`
32  const h = Math.floor(m / 60)
33  if (h < 24) return `${h}h`
34  const d = Math.floor(h / 24)
35  if (d < 14) return `${d}d`
36  if (d < 60) return `${Math.floor(d / 7)}w`
37  if (d < 365) return `${Math.floor(d / 30)}mo`
38  return `${Math.floor(d / 365)}y`
39}
40
41/** US dollars: $1.50, $123. */
42/** Bytes, short: 812, 41K, 3.2M, 16G. */
43export const bytes = (n: number): string => {
44  const units = ['', 'k', 'M', 'G', 'T']
45  let i = 0
46  while (n >= 1024 && i < units.length - 1) {
47    n /= 1024
48    i++
49  }
50  return `${n >= 10 || i === 0 ? Math.round(n) : n.toFixed(1)}${units[i]}`
51}
52
53export const money =(usd: number) => (usd >= 100 ? `$${Math.round(usd)}` : `$${usd.toFixed(2)}`)
54
55/** `value` as a whole percent of `max`, clamped: the desktop takes whole percentages only. */
56export const pct = (value: number, max: number) => `${Math.round(Math.max(0, Math.min(100, (value / Math.max(max, 1)) * 100)))}%`
57
58/**
59 * `text` cut in the middle to at most `cells` characters, the end kept: a path
60 * keeps its first segment and as many whole segments from its end as fit
61 * (`src/…/hooks/view.tsx`), then `…/view.tsx`, then the end of its name; other
62 * text keeps its start and end around `…`. Text that fits comes back as is.
63 */
64export const middle = (text: string, cells: number): string => {
65  const chars = [...text]
66  const n = Math.max(0, Math.floor(cells))
67  if (chars.length <= n) return text
68  if (n <= 1) return n === 1 ? '…' : ''
69  const parts = text.split('/')
70  if (parts.length >= 2) {
71    const len = (s: string) => [...s].length
72    const head = parts[0]!
73    const tail: string[] = [parts[parts.length - 1]!]
74    // As many whole segments from the end as fit after `head/…/`.
75    for (let i = parts.length - 2; i > 0; i--) {
76      const next = [parts[i]!, ...tail].join('/')
77      if (len(`${head}/…/${next}`) > n) break
78      tail.unshift(parts[i]!)
79    }
80    const kept = tail.join('/')
81    if (len(`${head}/…/${kept}`) <= n) return `${head}/…/${kept}`
82    if (len(`…/${kept}`) <= n) return `…/${kept}`
83    // Not even the name fits: the end of the name.
84    const name = [...kept]
85    return `…${name.slice(name.length - (n - 1)).join('')}`
86  }
87  // Plain text: a little more of the start than the end.
88  const front = Math.ceil((n - 1) / 2)
89  const back = n - 1 - front
90  return `${chars.slice(0, front).join('')}…${back ? chars.slice(chars.length - back).join('') : ''}`
91}
92
93/** The last path segment. */
94export const basename = (path: string) => path.split(/[\\/]/).filter(Boolean).pop() ?? path
95

1import { GLYPH } from './tokens'
2import type { Duo } from './tokens'
3
4/*
5 * The kit's icons: stroked drawings on a 16×16 grid, drawn as SVG at one exact
6 * pixel size so every icon is the same height and width and stays crisp (an SVG
7 * the page has to scale blurs). Keyed by the glyph each one stands in for, so a
8 * component given a GLYPH draws the icon where the surface has SVG, the glyph
9 * where it doesn't (the terminal).
10 */
11
12/** The icons' drawn size in CSS pixels. */
13export const ICON_PX = 13
14
15const PATHS: Record<string, string> = {
16  // A pie a quarter cut: how full.
17  [GLYPH.context]: '<circle cx="8" cy="8" r="6"/><path d="M8 2v6h6"/>',
18  [GLYPH.time]: '<circle cx="8" cy="8" r="6"/><path d="M8 4.5V8l2.5 1.5"/>',
19  [GLYPH.turns]: '<path d="M13 8a5 5 0 1 1-1.6-3.7"/><path d="M13 2.5v3.2H9.8"/>',
20  [GLYPH.tools]: '<path d="M10.5 2.5a3 3 0 0 0-3.3 4.1L2.6 11.2l2.2 2.2 4.6-4.6a3 3 0 0 0 4.1-3.3l-1.9 1.9-1.9-.4-.4-1.9z"/>',
21  [GLYPH.files]: '<path d="M3 13l.9-3.4L10.8 2.7l2.5 2.5-6.9 6.9z"/>',
22  [GLYPH.agents]: '<path d="M8 2l1.4 4.6L14 8l-4.6 1.4L8 14l-1.4-4.6L2 8l4.6-1.4z"/>',
23  // A gauge: a dial three-quarters round, open at the bottom, centred like the
24  // other icons (a half dial sat low in its square and read as cut off), and a needle.
25  [GLYPH.limits]: '<path d="M3.76 12.24a6 6 0 1 1 8.48 0"/><path d="M8 8l2.6-2.6"/>',
26  [GLYPH.cost]: '<circle cx="8" cy="8" r="6"/><path d="M10 6.2c-.4-.8-1.2-1.2-2-1.2-1.1 0-2 .6-2 1.5S6.9 7.8 8 8s2 .6 2 1.5-.9 1.5-2 1.5c-.8 0-1.6-.4-2-1.2M8 4v1M8 11v1"/>',
27  // Events: a bolt.
28  events: '<path d="M9 1.5L3.5 9H8l-1 5.5L12.5 7H8z"/>',
29}
30
31/**
32 * GitHub's own icons for branches and pull requests: Octicons (`@primer/octicons`
33 * 19.15.0, `*-16.svg`, MIT, © GitHub Inc.), copied unchanged. Filled shapes, not
34 * strokes, so they're drawn filled in the icon's colour.
35 */
36const FILLED: Record<string, string> = {
37  [GLYPH.branch]:
38    'M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.493 2.493 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628A2.25 2.25 0 0 1 9.5 3.25Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z',
39  'pr-open':
40    'M1.5 3.25a2.25 2.25 0 1 1 3 2.122v5.256a2.251 2.251 0 1 1-1.5 0V5.372A2.25 2.25 0 0 1 1.5 3.25Zm5.677-.177L9.573.677A.25.25 0 0 1 10 .854V2.5h1A2.5 2.5 0 0 1 13.5 5v5.628a2.251 2.251 0 1 1-1.5 0V5a1 1 0 0 0-1-1h-1v1.646a.25.25 0 0 1-.427.177L7.177 3.427a.25.25 0 0 1 0-.354ZM3.75 2.5a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm0 9.5a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm8.25.75a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Z',
41  'pr-merged':
42    'M5.45 5.154A4.25 4.25 0 0 0 9.25 7.5h1.378a2.251 2.251 0 1 1 0 1.5H9.25A5.734 5.734 0 0 1 5 7.123v3.505a2.25 2.25 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.95-.218ZM4.25 13.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm8.5-4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5ZM5 3.25a.75.75 0 1 0 0 .005V3.25Z',
43  'pr-closed':
44    'M3.25 1A2.25 2.25 0 0 1 4 5.372v5.256a2.251 2.251 0 1 1-1.5 0V5.372A2.251 2.251 0 0 1 3.25 1Zm9.5 5.5a.75.75 0 0 1 .75.75v3.378a2.251 2.251 0 1 1-1.5 0V7.25a.75.75 0 0 1 .75-.75Zm-2.03-5.273a.75.75 0 0 1 1.06 0l.97.97.97-.97a.748.748 0 0 1 1.265.332.75.75 0 0 1-.205.729l-.97.97.97.97a.751.751 0 0 1-.018 1.042.751.751 0 0 1-1.042.018l-.97-.97-.97.97a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734l.97-.97-.97-.97a.75.75 0 0 1 0-1.06ZM2.5 3.25a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0ZM3.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm9.5 0a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z',
45  'issue-opened': 'M8 9.5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3ZM8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Z',
46  comment:
47    'M1 2.75C1 1.784 1.784 1 2.75 1h10.5c.966 0 1.75.784 1.75 1.75v7.5A1.75 1.75 0 0 1 13.25 12H9.06l-2.573 2.573A1.458 1.458 0 0 1 4 13.543V12H2.75A1.75 1.75 0 0 1 1 10.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h4.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z',
48  'pr-draft':
49    'M3.25 1A2.25 2.25 0 0 1 4 5.372v5.256a2.251 2.251 0 1 1-1.5 0V5.372A2.251 2.251 0 0 1 3.25 1Zm9.5 14a2.25 2.25 0 1 1 0-4.5 2.25 2.25 0 0 1 0 4.5ZM2.5 3.25a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0ZM3.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm9.5 0a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM14 7.5a1.25 1.25 0 1 1-2.5 0 1.25 1.25 0 0 1 2.5 0Zm0-4.25a1.25 1.25 0 1 1-2.5 0 1.25 1.25 0 0 1 2.5 0Z',
50  // Files and folders, for trees of them.
51  file: 'M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 9 4.25V1.5Zm6.75.062V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z',
52  'file-code':
53    'M4 1.75C4 .784 4.784 0 5.75 0h5.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v8.586A1.75 1.75 0 0 1 14.25 15h-9a.75.75 0 0 1 0-1.5h9a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 10 4.25V1.5H5.75a.25.25 0 0 0-.25.25v2.5a.75.75 0 0 1-1.5 0Zm1.72 4.97a.75.75 0 0 1 1.06 0l2 2a.75.75 0 0 1 0 1.06l-2 2a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734l1.47-1.47-1.47-1.47a.75.75 0 0 1 0-1.06ZM3.28 7.78 1.81 9.25l1.47 1.47a.751.751 0 0 1-.018 1.042.751.751 0 0 1-1.042.018l-2-2a.75.75 0 0 1 0-1.06l2-2a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042Zm8.22-6.218V4.25c0 .138.112.25.25.25h2.688l-.011-.013-2.914-2.914-.013-.011Z',
54  folder: 'M1.75 1A1.75 1.75 0 0 0 0 2.75v10.5C0 14.216.784 15 1.75 15h12.5A1.75 1.75 0 0 0 16 13.25v-8.5A1.75 1.75 0 0 0 14.25 3H7.5a.25.25 0 0 1-.2-.1l-.9-1.2C6.07 1.26 5.55 1 5 1H1.75Z',
55  'folder-open':
56    'M.513 1.513A1.75 1.75 0 0 1 1.75 1h3.5c.55 0 1.07.26 1.4.7l.9 1.2a.25.25 0 0 0 .2.1H13a1 1 0 0 1 1 1v.5H2.75a.75.75 0 0 0 0 1.5h11.978a1 1 0 0 1 .994 1.117L15 13.25A1.75 1.75 0 0 1 13.25 15H1.75A1.75 1.75 0 0 1 0 13.25V2.75c0-.464.184-.91.513-1.237Z',
57  // Git and the actions on a tree or a command.
58  'git-commit': 'M11.93 8.5a4.002 4.002 0 0 1-7.86 0H.75a.75.75 0 0 1 0-1.5h3.32a4.002 4.002 0 0 1 7.86 0h3.32a.75.75 0 0 1 0 1.5Zm-1.43-.75a2.5 2.5 0 1 0-5 0 2.5 2.5 0 0 0 5 0Z',
59  'repo-push':
60    'M2 2.5A2.5 2.5 0 0 1 4.5 0h8.75a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0V1.5h-8a1 1 0 0 0-1 1v6.708A2.493 2.493 0 0 1 4.5 9h2.25a.75.75 0 0 1 0 1.5H4.5a1 1 0 0 0 0 2h4.75a.75.75 0 0 1 0 1.5H4.5A2.5 2.5 0 0 1 2 11.5Zm12.23 7.79h-.001l-1.224-1.224v6.184a.75.75 0 0 1-1.5 0V9.066L10.28 10.29a.75.75 0 0 1-1.06-1.061l2.505-2.504a.75.75 0 0 1 1.06 0L15.29 9.23a.751.751 0 0 1-.018 1.042.751.751 0 0 1-1.042.018Z',
61  alert:
62    'M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z',
63  trash:
64    'M11 1.75V3h2.25a.75.75 0 0 1 0 1.5H2.75a.75.75 0 0 1 0-1.5H5V1.75C5 .784 5.784 0 6.75 0h2.5C10.216 0 11 .784 11 1.75ZM4.496 6.675l.66 6.6a.25.25 0 0 0 .249.225h5.19a.25.25 0 0 0 .249-.225l.66-6.6a.75.75 0 0 1 1.492.149l-.66 6.6A1.748 1.748 0 0 1 10.595 15h-5.19a1.75 1.75 0 0 1-1.741-1.575l-.66-6.6a.75.75 0 1 1 1.492-.15ZM6.5 1.75V3h3V1.75a.25.25 0 0 0-.25-.25h-2.5a.25.25 0 0 0-.25.25Z',
65  search:
66    'M10.68 11.74a6 6 0 0 1-7.922-8.982 6 6 0 0 1 8.982 7.922l3.04 3.04a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215ZM11.5 7a4.499 4.499 0 1 0-8.997 0A4.499 4.499 0 0 0 11.5 7Z',
67  sync: 'M1.705 8.005a.75.75 0 0 1 .834.656 5.5 5.5 0 0 0 9.592 2.97l-1.204-1.204a.25.25 0 0 1 .177-.427h3.646a.25.25 0 0 1 .25.25v3.646a.25.25 0 0 1-.427.177l-1.38-1.38A7.002 7.002 0 0 1 1.05 8.84a.75.75 0 0 1 .656-.834ZM8 2.5a5.487 5.487 0 0 0-4.131 1.869l1.204 1.204A.25.25 0 0 1 4.896 6H1.25A.25.25 0 0 1 1 5.75V2.104a.25.25 0 0 1 .427-.177l1.38 1.38A7.002 7.002 0 0 1 14.95 7.16a.75.75 0 0 1-1.49.178A5.5 5.5 0 0 0 8 2.5Z',
68  'arrow-up':
69    'M3.47 7.78a.75.75 0 0 1 0-1.06l4.25-4.25a.75.75 0 0 1 1.06 0l4.25 4.25a.751.751 0 0 1-.018 1.042.751.751 0 0 1-1.042.018L9 4.81v7.44a.75.75 0 0 1-1.5 0V4.81L4.53 7.78a.75.75 0 0 1-1.06 0Z',
70  home: 'M6.906.664a1.749 1.749 0 0 1 2.187 0l5.25 4.2c.415.332.657.835.657 1.367v7.019A1.75 1.75 0 0 1 13.25 15h-3.5a.75.75 0 0 1-.75-.75V9H7v5.25a.75.75 0 0 1-.75.75h-3.5A1.75 1.75 0 0 1 1 13.25V6.23c0-.531.242-1.034.657-1.366l5.25-4.2Zm1.25 1.171a.25.25 0 0 0-.312 0l-5.25 4.2a.25.25 0 0 0-.094.196v7.019c0 .138.112.25.25.25H5.5V8.25a.75.75 0 0 1 .75-.75h3.5a.75.75 0 0 1 .75.75v5.25h2.75a.25.25 0 0 0 .25-.25V6.23a.25.25 0 0 0-.094-.195Z',
71  eye: 'M8 2c1.981 0 3.671.992 4.933 2.078 1.27 1.091 2.187 2.345 2.637 3.023a1.62 1.62 0 0 1 0 1.798c-.45.678-1.367 1.932-2.637 3.023C11.67 13.008 9.981 14 8 14c-1.981 0-3.671-.992-4.933-2.078C1.797 10.83.88 9.576.43 8.898a1.62 1.62 0 0 1 0-1.798c.45-.677 1.367-1.931 2.637-3.022C4.33 2.992 6.019 2 8 2ZM1.679 7.932a.12.12 0 0 0 0 .136c.411.622 1.241 1.75 2.366 2.717C5.176 11.758 6.527 12.5 8 12.5c1.473 0 2.825-.742 3.955-1.715 1.124-.967 1.954-2.096 2.366-2.717a.12.12 0 0 0 0-.136c-.412-.621-1.242-1.75-2.366-2.717C10.824 4.242 9.473 3.5 8 3.5c-1.473 0-2.825.742-3.955 1.715-1.124.967-1.954 2.096-2.366 2.717ZM8 10a2 2 0 1 1-.001-3.999A2 2 0 0 1 8 10Z',
72  // What an agent's tool call is doing: a command, an edit, the web, an MCP server, anything else.
73  terminal:
74    'M0 2.75C0 1.784.784 1 1.75 1h12.5c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0 1 14.25 15H1.75A1.75 1.75 0 0 1 0 13.25Zm1.75-.25a.25.25 0 0 0-.25.25v10.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25V2.75a.25.25 0 0 0-.25-.25ZM7.25 8a.749.749 0 0 1-.22.53l-2.25 2.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L5.44 8 3.72 6.28a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l2.25 2.25c.141.14.22.331.22.53Zm1.5 1.5h3a.75.75 0 0 1 0 1.5h-3a.75.75 0 0 1 0-1.5Z',
75  pencil:
76    'M11.013 1.427a1.75 1.75 0 0 1 2.474 0l1.086 1.086a1.75 1.75 0 0 1 0 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 0 1-.927-.928l.929-3.25c.081-.286.235-.547.445-.758l8.61-8.61Zm.176 4.823L9.75 4.81l-6.286 6.287a.253.253 0 0 0-.064.108l-.558 1.953 1.953-.558a.253.253 0 0 0 .108-.064Zm1.238-3.763a.25.25 0 0 0-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 0 0 0-.354Z',
77  globe:
78    'M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM5.78 8.75a9.64 9.64 0 0 0 1.363 4.177c.255.426.542.832.857 1.215.245-.296.551-.705.857-1.215A9.64 9.64 0 0 0 10.22 8.75Zm4.44-1.5a9.64 9.64 0 0 0-1.363-4.177c-.307-.51-.612-.919-.857-1.215a9.927 9.927 0 0 0-.857 1.215A9.64 9.64 0 0 0 5.78 7.25Zm-5.944 1.5H1.543a6.507 6.507 0 0 0 4.666 5.5c-.123-.181-.24-.365-.352-.552-.715-1.192-1.437-2.874-1.581-4.948Zm-2.733-1.5h2.733c.144-2.074.866-3.756 1.58-4.948.12-.197.237-.381.353-.552a6.507 6.507 0 0 0-4.666 5.5Zm10.181 1.5c-.144 2.074-.866 3.756-1.58 4.948-.12.197-.237.381-.353.552a6.507 6.507 0 0 0 4.666-5.5Zm2.733-1.5a6.507 6.507 0 0 0-4.666-5.5c.123.181.24.365.353.552.714 1.192 1.436 2.874 1.58 4.948Z',
79  plug: 'M4 8H2.5a1 1 0 0 0-1 1v5.25a.75.75 0 0 1-1.5 0V9a2.5 2.5 0 0 1 2.5-2.5H4V5.133a1.75 1.75 0 0 1 1.533-1.737l2.831-.353.76-.913c.332-.4.825-.63 1.344-.63h.782c.966 0 1.75.784 1.75 1.75V4h2.25a.75.75 0 0 1 0 1.5H13v4h2.25a.75.75 0 0 1 0 1.5H13v.75a1.75 1.75 0 0 1-1.75 1.75h-.782c-.519 0-1.012-.23-1.344-.63l-.761-.912-2.83-.354A1.75 1.75 0 0 1 4 9.867Zm6.276-4.91-.95 1.14a.753.753 0 0 1-.483.265l-3.124.39a.25.25 0 0 0-.219.248v4.734c0 .126.094.233.219.249l3.124.39a.752.752 0 0 1 .483.264l.95 1.14a.25.25 0 0 0 .192.09h.782a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25h-.782a.25.25 0 0 0-.192.09Z',
80  'dot-fill': 'M8 4a4 4 0 1 1 0 8 4 4 0 0 1 0-8Z',
81  // Kinds of agent: one that writes code, a worker, a quick fix, a reviewer, an explorer,
82  // a planner, a general one, a guide.
83  code: 'm11.28 3.22 4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L13.94 8l-3.72-3.72a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215Zm-6.56 0a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L2.06 8l3.72 3.72a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L.47 8.53a.75.75 0 0 1 0-1.06Z',
84  tools:
85    'M5.433 2.304A4.492 4.492 0 0 0 3.5 6c0 1.598.832 3.002 2.09 3.802.518.328.929.923.902 1.64v.008l-.164 3.337a.75.75 0 1 1-1.498-.073l.163-3.33c.002-.085-.05-.216-.207-.316A5.996 5.996 0 0 1 2 6a5.993 5.993 0 0 1 2.567-4.92 1.482 1.482 0 0 1 1.673-.04c.462.296.76.827.76 1.423v2.82c0 .082.041.16.11.206l.75.51a.25.25 0 0 0 .28 0l.75-.51A.249.249 0 0 0 9 5.282V2.463c0-.596.298-1.127.76-1.423a1.482 1.482 0 0 1 1.673.04A5.993 5.993 0 0 1 14 6a5.996 5.996 0 0 1-2.786 5.068c-.157.1-.209.23-.207.315l.163 3.33a.752.752 0 0 1-1.094.714.75.75 0 0 1-.404-.64l-.164-3.345c-.027-.717.384-1.312.902-1.64A4.495 4.495 0 0 0 12.5 6a4.492 4.492 0 0 0-1.933-3.696c-.024.017-.067.067-.067.16v2.818a1.75 1.75 0 0 1-.767 1.448l-.75.51a1.75 1.75 0 0 1-1.966 0l-.75-.51A1.75 1.75 0 0 1 5.5 5.282V2.463c0-.092-.043-.142-.067-.159Z',
86  zap: 'M9.504.43a1.516 1.516 0 0 1 2.437 1.713L10.415 5.5h2.123c1.57 0 2.346 1.909 1.22 3.004l-7.34 7.142a1.249 1.249 0 0 1-.871.354h-.302a1.25 1.25 0 0 1-1.157-1.723L5.633 10.5H3.462c-1.57 0-2.346-1.909-1.22-3.004L9.503.429Zm1.047 1.074L3.286 8.571A.25.25 0 0 0 3.462 9H6.75a.75.75 0 0 1 .694 1.034l-1.713 4.188 6.982-6.793A.25.25 0 0 0 12.538 7H9.25a.75.75 0 0 1-.683-1.06l2.008-4.418.003-.006a.036.036 0 0 0-.004-.009l-.006-.006-.008-.001c-.003 0-.006.002-.009.004Z',
87  checklist:
88    'M2.5 1.75v11.5c0 .138.112.25.25.25h3.17a.75.75 0 0 1 0 1.5H2.75A1.75 1.75 0 0 1 1 13.25V1.75C1 .784 1.784 0 2.75 0h8.5C12.216 0 13 .784 13 1.75v7.736a.75.75 0 0 1-1.5 0V1.75a.25.25 0 0 0-.25-.25h-8.5a.25.25 0 0 0-.25.25Zm13.274 9.537v-.001l-4.557 4.45a.75.75 0 0 1-1.055-.008l-1.943-1.95a.75.75 0 0 1 1.062-1.058l1.419 1.425 4.026-3.932a.75.75 0 1 1 1.048 1.074ZM4.75 4h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM4 7.75A.75.75 0 0 1 4.75 7h2a.75.75 0 0 1 0 1.5h-2A.75.75 0 0 1 4 7.75Z',
89  telescope:
90    'M14.184 1.143v-.001l1.422 2.464a1.75 1.75 0 0 1-.757 2.451L3.104 11.713a1.75 1.75 0 0 1-2.275-.702l-.447-.775a1.75 1.75 0 0 1 .53-2.32L11.682.573a1.748 1.748 0 0 1 2.502.57Zm-4.709 9.32h-.001l2.644 3.863a.75.75 0 1 1-1.238.848l-1.881-2.75v2.826a.75.75 0 0 1-1.5 0v-2.826l-1.881 2.75a.75.75 0 1 1-1.238-.848l2.049-2.992a.746.746 0 0 1 .293-.253l1.809-.87a.749.749 0 0 1 .944.252ZM9.436 3.92h-.001l-4.97 3.39.942 1.63 5.42-2.61Zm3.091-2.108h.001l-1.85 1.26 1.505 2.605 2.016-.97a.247.247 0 0 0 .13-.151.247.247 0 0 0-.022-.199l-1.422-2.464a.253.253 0 0 0-.161-.119.254.254 0 0 0-.197.038ZM1.756 9.157a.25.25 0 0 0-.075.33l.447.775a.25.25 0 0 0 .325.1l1.598-.769-.83-1.436-1.465 1Z',
91  tasklist:
92    'M2 2h4a1 1 0 0 1 1 1v4a1 1 0 0 1-1 1H2a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1Zm4.655 8.595a.75.75 0 0 1 0 1.06L4.03 14.28a.75.75 0 0 1-1.06 0l-1.5-1.5a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l.97.97 2.095-2.095a.75.75 0 0 1 1.06 0ZM9.75 2.5h5.5a.75.75 0 0 1 0 1.5h-5.5a.75.75 0 0 1 0-1.5Zm0 5h5.5a.75.75 0 0 1 0 1.5h-5.5a.75.75 0 0 1 0-1.5Zm0 5h5.5a.75.75 0 0 1 0 1.5h-5.5a.75.75 0 0 1 0-1.5Zm-7.25-9v3h3v-3Z',
93  hubot:
94    'M0 8a8 8 0 0 1 16 0v5.25a.75.75 0 0 1-1.5 0V8a6.5 6.5 0 1 0-13 0v5.25a.75.75 0 0 1-1.5 0Zm3-1.25C3 5.784 3.784 5 4.75 5h6.5c.966 0 1.75.784 1.75 1.75v1.5A1.75 1.75 0 0 1 11.25 10h-6.5A1.75 1.75 0 0 1 3 8.25Zm1.47-.53a.75.75 0 0 0 0 1.06l1.5 1.5a.75.75 0 0 0 1.06 0L8 7.81l.97.97a.75.75 0 0 0 1.06 0l1.5-1.5a.749.749 0 0 0-.326-1.275.749.749 0 0 0-.734.215l-.97.97-.97-.97a.75.75 0 0 0-1.06 0l-.97.97-.97-.97a.75.75 0 0 0-1.06 0Zm1.03 6.03a.75.75 0 0 1 .75-.75h3.5a.75.75 0 0 1 0 1.5h-3.5a.75.75 0 0 1-.75-.75Z',
95  book: 'M0 1.75A.75.75 0 0 1 .75 1h4.253c1.227 0 2.317.59 3 1.501A3.743 3.743 0 0 1 11.006 1h4.245a.75.75 0 0 1 .75.75v10.5a.75.75 0 0 1-.75.75h-4.507a2.25 2.25 0 0 0-1.591.659l-.622.621a.75.75 0 0 1-1.06 0l-.622-.621A2.25 2.25 0 0 0 5.258 13H.75a.75.75 0 0 1-.75-.75Zm7.251 10.324.004-5.073-.002-2.253A2.25 2.25 0 0 0 5.003 2.5H1.5v9h3.757a3.75 3.75 0 0 1 1.994.574ZM8.755 4.75l-.004 7.322a3.752 3.752 0 0 1 1.992-.572H14.5v-9h-3.495a2.25 2.25 0 0 0-2.25 2.25Z',
96  fold: 'M10.896 2H8.75V.75a.75.75 0 0 0-1.5 0V2H5.104a.25.25 0 0 0-.177.427l2.896 2.896a.25.25 0 0 0 .354 0l2.896-2.896A.25.25 0 0 0 10.896 2ZM8.75 15.25a.75.75 0 0 1-1.5 0V14H5.104a.25.25 0 0 1-.177-.427l2.896-2.896a.25.25 0 0 1 .354 0l2.896 2.896a.25.25 0 0 1-.177.427H8.75v1.25Zm-6.5-6.5a.75.75 0 0 0 0-1.5h-.5a.75.75 0 0 0 0 1.5h.5ZM6 8a.75.75 0 0 1-.75.75h-.5a.75.75 0 0 1 0-1.5h.5A.75.75 0 0 1 6 8Zm2.25.75a.75.75 0 0 0 0-1.5h-.5a.75.75 0 0 0 0 1.5h.5ZM12 8a.75.75 0 0 1-.75.75h-.5a.75.75 0 0 1 0-1.5h.5A.75.75 0 0 1 12 8Zm2.25.75a.75.75 0 0 0 0-1.5h-.5a.75.75 0 0 0 0 1.5h.5Z',
97}
98
99/**
100 * Where a branch's upstream lives, by the remote's host: GitHub's mark and a
101 * generic remote (a cloud) are Octicons (`@primer/octicons`, `mark-github-16.svg`
102 * and `cloud-16.svg`, MIT, © GitHub Inc.); GitLab's and Forgejo's marks are from
103 * Simple Icons (`icons/gitlab.svg`, `icons/forgejo.svg`, CC0 1.0), on their
104 * 24×24 grid. All copied unchanged, drawn filled in the icon's colour.
105 */
106const HOSTS: Record<string, { d: string; grid: number }> = {
107  'mark-github': {
108    grid: 16,
109    d: 'M6.766 11.328c-2.063-.25-3.516-1.734-3.516-3.656 0-.781.281-1.625.75-2.188-.203-.515-.172-1.609.063-2.062.625-.078 1.468.25 1.968.703.594-.187 1.219-.281 1.985-.281.765 0 1.39.094 1.953.265.484-.437 1.344-.765 1.969-.687.218.422.25 1.515.046 2.047.5.593.766 1.39.766 2.203 0 1.922-1.453 3.375-3.547 3.64.531.344.89 1.094.89 1.954v1.625c0 .468.391.734.86.547C13.781 14.359 16 11.53 16 8.03 16 3.61 12.406 0 7.984 0 3.563 0 0 3.61 0 8.031a7.88 7.88 0 0 0 5.172 7.422c.422.156.828-.125.828-.547v-1.25c-.219.094-.5.156-.75.156-1.031 0-1.64-.562-2.078-1.609-.172-.422-.36-.672-.719-.719-.187-.015-.25-.093-.25-.187 0-.188.313-.328.625-.328.453 0 .844.281 1.25.86.313.452.64.655 1.031.655s.641-.14 1-.5c.266-.265.47-.5.657-.656',
110  },
111  cloud: {
112    grid: 16,
113    d: 'M2 7.25A5.225 5.225 0 0 1 7.25 2a5.222 5.222 0 0 1 4.767 3.029A4.472 4.472 0 0 1 16 9.5c0 2.505-1.995 4.5-4.5 4.5h-8A3.474 3.474 0 0 1 0 10.5c0-1.41.809-2.614 2.001-3.17Zm1.54.482a.75.75 0 0 1-.556.832c-.86.22-1.484.987-1.484 1.936 0 1.124.876 2 2 2h8c1.676 0 3-1.324 3-3s-1.324-3-3-3a.75.75 0 0 1-.709-.504A3.72 3.72 0 0 0 7.25 3.5C5.16 3.5 3.5 5.16 3.5 7.25c.002.146.014.292.035.436l.004.036.001.008Z',
114  },
115  gitlab: {
116    grid: 24,
117    d: 'm23.6004 9.5927-.0337-.0862L20.3.9814a.851.851 0 0 0-.3362-.405.8748.8748 0 0 0-.9997.0539.8748.8748 0 0 0-.29.4399l-2.2055 6.748H7.5375l-2.2057-6.748a.8573.8573 0 0 0-.29-.4412.8748.8748 0 0 0-.9997-.0537.8585.8585 0 0 0-.3362.4049L.4332 9.5015l-.0325.0862a6.0657 6.0657 0 0 0 2.0119 7.0105l.0113.0087.03.0213 4.976 3.7264 2.462 1.8633 1.4995 1.1321a1.0085 1.0085 0 0 0 1.2197 0l1.4995-1.1321 2.4619-1.8633 5.006-3.7489.0125-.01a6.0682 6.0682 0 0 0 2.0094-7.003z',
118  },
119  forgejo: {
120    grid: 24,
121    d: 'M16.7773 0c1.6018 0 2.9004 1.2986 2.9004 2.9005s-1.2986 2.9004-2.9004 2.9004c-1.0854 0-2.0315-.596-2.5288-1.4787H12.91c-2.3322 0-4.2272 1.8718-4.2649 4.195l-.0007 2.1175a7.0759 7.0759 0 0 1 4.148-1.4205l.1176-.001 1.3385.0002c.4973-.8827 1.4434-1.4788 2.5288-1.4788 1.6018 0 2.9004 1.2986 2.9004 2.9005s-1.2986 2.9004-2.9004 2.9004c-1.0854 0-2.0315-.596-2.5288-1.4787H12.91c-2.3322 0-4.2272 1.8718-4.2649 4.195l-.0007 2.319c.8827.4973 1.4788 1.4434 1.4788 2.5287 0 1.602-1.2986 2.9005-2.9005 2.9005-1.6018 0-2.9004-1.2986-2.9004-2.9005 0-1.0853.596-2.0314 1.4788-2.5287l-.0002-9.9831c0-3.887 3.1195-7.0453 6.9915-7.108l.1176-.001h1.3385C14.7458.5962 15.692 0 16.7773 0ZM7.2227 19.9052c-.6596 0-1.1943.5347-1.1943 1.1943s.5347 1.1943 1.1943 1.1943 1.1944-.5347 1.1944-1.1943-.5348-1.1943-1.1944-1.1943Zm9.5546-10.4644c-.6596 0-1.1944.5347-1.1944 1.1943s.5348 1.1943 1.1944 1.1943c.6596 0 1.1943-.5347 1.1943-1.1943s-.5347-1.1943-1.1943-1.1943Zm0-7.7346c-.6596 0-1.1944.5347-1.1944 1.1943s.5348 1.1943 1.1944 1.1943c.6596 0 1.1943-.5347 1.1943-1.1943s-.5347-1.1943-1.1943-1.1943Z',
122  },
123}
124
125/**
126 * Each named icon's glyph on the terminal: one cell wide, from Unicode blocks
127 * monospace fonts carry (geometric shapes, arrows, box drawing, a few dingbats),
128 * never one with an emoji presentation (⚠ ⚡ ◼ draw as emoji in some terminals).
129 * A GLYPH key is its own glyph.
130 */
131export const TERM_GLYPH: Readonly<Record<string, string>> = {
132  events: '↯',
133  'issue-opened': '◉',
134  comment: '≡',
135  'pr-open': GLYPH.pr,
136  'pr-merged': '◆',
137  'pr-closed': GLYPH.failed,
138  'pr-draft': GLYPH.pending,
139  file: '□',
140  'file-code': '□',
141  // A tree shows a folder by its fold: closed points right, open points down.
142  folder: '▸',
143  'folder-open': '▾',
144  'git-commit': '○',
145  'repo-push': GLYPH.up,
146  alert: '▲',
147  trash: '⌫',
148  search: '⌕',
149  sync: GLYPH.turns,
150  'arrow-up': GLYPH.up,
151  home: '⌂',
152  eye: '◎',
153  // ⇕, not ↕: ↕ has an emoji presentation.
154  fold: '⇕',
155  terminal: '$',
156  pencil: '✎',
157  globe: '◎',
158  plug: '⏚',
159  'dot-fill': '·',
160  code: '◆',
161  tools: '◇',
162  // ↯, not ⚡: ⚡ has an emoji presentation; ✓, not ✔, for the same reason.
163  zap: '↯',
164  checklist: '✓',
165  telescope: '⌕',
166  tasklist: '≡',
167  hubot: '○',
168  book: '?',
169}
170
171/**
172 * The glyph an icon draws as where there's no SVG: its terminal glyph, a
173 * one-character key as itself, else a dot (never the icon's name as text).
174 */
175export const glyphOf = (key: string): string => TERM_GLYPH[key] ?? ([...key].length === 1 ? key : '•')
176
177/** An XML text node's escapes, for a tooltip's `<title>`. */
178const xml = (text: string) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
179
180/**
181 * The SVG for an icon (a GLYPH or a name), drawn in `color`; null when the kit has none.
182 *
183 * A `Duo` colour (a file type's, `FILE_TYPE` in kit/tokens.ts) draws the dark value
184 * and switches to the light one by the page's colour scheme, in a style inside the
185 * SVG: the engine tells a render hook no desktop theme. `title` is a tooltip,
186 * shown where the SVG is drawn interactive.
187 */
188export const iconSvg = (key: string, color: string | Duo, px = ICON_PX, title?: string): string | null => {
189  const host = HOSTS[key]
190  const filled = host?.d ?? FILLED[key]
191  const body = PATHS[key]
192  if (!filled && !body) return null
193  const grid = host?.grid ?? 16
194  const base = typeof color === 'string' ? color : color.dark
195  const paint = filled ? 'fill' : 'stroke'
196  const scheme = typeof color === 'string' ? '' : `<style>@media (prefers-color-scheme: light){svg{${paint}:${color.light}}}</style>`
197  const tip = title ? `<title>${xml(title)}</title>` : ''
198  const open = `<svg xmlns="http://www.w3.org/2000/svg" width="${px}" height="${px}" viewBox="0 0 ${grid} ${grid}" `
199  if (filled) return `${open}fill="${base}">${scheme}${tip}<path d="${filled}"/></svg>`
200  return `${open}fill="none" stroke="${base}" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">${scheme}${tip}${body}</svg>`
201}
202

1/**
2 * What a mod costs: how often each named thing ran, how long it took, and how
3 * much of the last minute it spent. Each compiled mod gets its own copy of the
4 * kit, so these are that mod's numbers. Recording never redraws: the footer
5 * shows them as of the pane's latest draw, so measuring adds no load.
6 *
7 *   const done = perf.start('render'); …; done()
8 *   await perf.time('git', () => run(...))
9 *   perf.count('state write')
10 */
11
12const now = (): number => (globalThis as { performance?: { now(): number } }).performance?.now() ?? Date.now()
13
14const WINDOW = 60_000
15
16type Entry = { n: number; total: number; last: number; max: number; recent: Array<[at: number, ms: number]> }
17
18export type PerfRow = {
19  name: string
20  /** Runs since the mod loaded. */
21  n: number
22  /** Runs in the last minute. */
23  perMin: number
24  /** Milliseconds per run, on average; 0 for counts. */
25  avgMs: number
26  lastMs: number
27  maxMs: number
28  /** Milliseconds spent in the last minute. */
29  busyMs: number
30}
31
32export type PerfSnapshot = { sinceMs: number; rows: PerfRow[] }
33
34export const createPerf = () => {
35  const entries = new Map<string, Entry>()
36  const loadedAt = Date.now()
37
38  const record = (name: string, ms: number) => {
39    const e = entries.get(name) ?? { n: 0, total: 0, last: 0, max: 0, recent: [] }
40    const at = Date.now()
41    e.n++
42    e.total += ms
43    e.last = ms
44    e.max = Math.max(e.max, ms)
45    e.recent.push([at, ms])
46    // Keep only the window, so a long session doesn't grow this.
47    while (e.recent.length && at - e.recent[0]![0] > WINDOW) e.recent.shift()
48    entries.set(name, e)
49  }
50
51  /** Starts timing `name`; call what it returns when it's done. */
52  const start = (name: string) => {
53    const t0 = now()
54    return () => record(name, now() - t0)
55  }
56
57  /** Times `fn`, sync or async, under `name`. */
58  const time = <T>(name: string, fn: () => T): T => {
59    const done = start(name)
60    let out: T
61    try {
62      out = fn()
63    } catch (err) {
64      done()
65      throw err
66    }
67    if (out instanceof Promise) return out.finally(done) as T
68    done()
69    return out
70  }
71
72  /** Counts one occurrence of `name`, with no time. */
73  const count = (name: string) => record(name, 0)
74
75  const snapshot = (): PerfSnapshot => {
76    const at = Date.now()
77    const rows = [...entries].map(([name, e]) => {
78      const recent = e.recent.filter(([t]) => at - t <= WINDOW)
79      return {
80        name,
81        n: e.n,
82        perMin: recent.length,
83        avgMs: e.n ? e.total / e.n : 0,
84        lastMs: e.last,
85        maxMs: e.max,
86        busyMs: recent.reduce((s, [, ms]) => s + ms, 0),
87      }
88    })
89    // What cost the most in the last minute first, then what ran most.
90    rows.sort((a, b) => b.busyMs - a.busyMs || b.perMin - a.perMin)
91    return { sinceMs: at - loadedAt, rows }
92  }
93
94  return { start, time, count, snapshot }
95}
96
97export type Perf = ReturnType<typeof createPerf>
98
99/** Milliseconds, short: 0.4ms, 12ms, 1.2s. */
100export const ms = (v: number): string => (v >= 1_000 ? `${(v / 1_000).toFixed(1)}s` : v >= 10 ? `${Math.round(v)}ms` : `${v.toFixed(1)}ms`)
101

1import type { Skin } from './skin'
2import { DEFAULT_SKIN, SKINS } from './skins'
3import type { SkinId } from './skins'
4
5/**
6 * The instrument's colours. Each hue means one thing, everywhere:
7 *
8 * - grey (MUTED): labels, icons, git marks, ordinary values
9 * - slate (INK): "how much" — bars and gauges that only measure
10 * - blue: live or in progress — running, pending, the activity series
11 * - amber: getting close to a limit — 75% and up, the compaction mark
12 * - red: failed, conflicted, 90% and up
13 * - green: finished well — checks passed, an agent done
14 * - purple: merged
15 *
16 * Cyan and orchid aren't statuses: they only tint parts within one chart.
17 *
18 * The values come from the skin the kit wears (kit/skin.ts): a zen theme pack's
19 * palette, mapped to what the app surfaces draw. The kit starts in the
20 * `claude-code` skin; `wear()` puts on another. Read them when drawing, never
21 * into a module-level constant, so a skin worn later reaches every drawing.
22 */
23export const C = {
24  ok: '',
25  warn: '',
26  bad: '',
27  blue: '',
28  purple: '',
29  cyan: '',
30  slate: '',
31  orchid: '',
32}
33
34/** Quantity ink: what a bar or gauge is drawn in when it only says how much. */
35export let INK = ''
36
37/** Shades within one chart: parts of one thing, told apart without new meanings. */
38export const RAMP = {
39  blue: ['', '', '', ''] as [string, string, string, string],
40  slate: ['', '', '', ''] as [string, string, string, string],
41}
42
43/** A bar's empty part and other quiet fills: a grey that reads on light and dark. */
44export const TRACK = 'rgba(128,128,128,0.18)'
45
46/**
47 * `color` (#rgb or #rrggbb) at `alpha` (0 to 1), as rgba(): a tint that lets the
48 * pane show through, so it reads on the light desktop theme and the dark one.
49 * Undefined for anything that isn't a hex colour.
50 */
51export const tint = (color: string, alpha: number): string | undefined => {
52  const hex = color.replace(/^#/, '')
53  const full = hex.length === 3 ? [...hex].map(x => x + x).join('') : hex
54  if (!/^[0-9a-f]{6}$/i.test(full)) return undefined
55  const [r, g, b] = [0, 2, 4].map(i => parseInt(full.slice(i, i + 2), 16))
56  return `rgba(${r},${g},${b},${alpha})`
57}
58
59/**
60 * The app surfaces' fills, behind text. The engine gives render hooks no desktop
61 * theme to read and no theme key for a fill, so each is a see-through tint over
62 * the pane: a neutral grey darkens the light pane and lightens the dark one by
63 * about the same step, and the text over it keeps the theme's own foreground.
64 * Never on the terminal, which draws no fills.
65 *
66 * - head: a section header's band, the step that marks where a section starts;
67 * - tile: one item of a list of several-line items, a step quieter than a band;
68 * - selected: the picked tile or row, tinted towards the blue that means live;
69 * - selectedBlurred: the same while the pane doesn't have the keyboard, half as strong;
70 * - pill: how strongly a label's own colour fills its chip.
71 */
72export const FILL = {
73  head: 'rgba(128,128,128,0.09)',
74  tile: 'rgba(128,128,128,0.05)',
75  selected: '',
76  selectedBlurred: '',
77  pill: 0.22,
78}
79
80/** Text, icons and marks that should recede. */
81export let MUTED = ''
82
83/**
84 * Three greys for text below the main text, each a step quieter, so a row can say
85 * what matters most without colour (tuned for the desktop's dark pane; mid and
86 * dark also read on the light one):
87 * - light: secondary text a reader still reads (a linked PR's title, a byline);
88 * - mid: metadata scanned past (ages, counts, secondary actions);
89 * - dark: the quietest marks (an icon beside a count, a heading over a list).
90 */
91export const GRAY = { light: '', mid: '', dark: '' }
92
93/** A colour with one value for the light desktop theme and one for the dark. */
94export type Duo = { readonly light: string; readonly dark: string }
95
96/**
97 * File-type icon colours. One meaning: this file's type. Only a file tree's icons
98 * take them, never text, a header or a control (those stay grey), and only on the
99 * app surfaces: the terminal draws file icons monochrome (dim), as a file type is
100 * no state a theme key means.
101 *
102 * The values are IntelliJ's New UI ("expui") icon colours, each from the fill or
103 * stroke of the icon named beside it: intellij-community
104 * `platform/icons/src/expui/fileTypes/<name>.svg` (light) and `<name>_dark.svg`
105 * (dark), and `platform/icons/src/expui/nodes/` for the folders. Apache 2.0,
106 * © JetBrains s.r.o. and contributors (each SVG's header).
107 *
108 * An icon drawn in a Duo carries both values and picks one by the page's colour
109 * scheme (`iconSvg` in kit/icons.ts); where that can't be read it takes the dark.
110 */
111export const FILE_TYPE = {
112  /** typeScript.svg */
113  typescript: { light: '#3574F0', dark: '#548AF7' },
114  /** javaScript.svg */
115  javascript: { light: '#FFAF0F', dark: '#F2C55C' },
116  /** json.svg */
117  json: { light: '#834DF0', dark: '#B589EC' },
118  /** markdown.svg */
119  markdown: { light: '#3574F0', dark: '#548AF7' },
120  /** config.svg (its accent), toml.svg, docker.svg */
121  config: { light: '#3574F0', dark: '#548AF7' },
122  /** yaml.svg */
123  yaml: { light: '#DB3B4B', dark: '#DB5C5C' },
124  /** css.svg */
125  style: { light: '#4682FA', dark: '#548AF7' },
126  /** html.svg */
127  html: { light: '#369650', dark: '#57965C' },
128  /** xml.svg */
129  xml: { light: '#E66D17', dark: '#C77D55' },
130  /** csv.svg */
131  data: { light: '#208A3C', dark: '#57965C' },
132  /** sql.svg */
133  sql: { light: '#834DF0', dark: '#B589EC' },
134  /** image.svg */
135  image: { light: '#3574F0', dark: '#548AF7' },
136  /** archive.svg */
137  archive: { light: '#3574F0', dark: '#548AF7' },
138  /** text.svg, shell.svg, unknown.svg, font.svg: any other file, lockfiles included */
139  text: { light: '#6C707E', dark: '#CED0D6' },
140  /** nodes/folder.svg, nodes/folderGithub.svg */
141  folder: { light: '#6C707E', dark: '#CED0D6' },
142  /** nodes/excludeRoot.svg: a folder git ignores (node_modules, build output) */
143  excluded: { light: '#F28C35', dark: '#C77D55' },
144} as const satisfies Record<string, Duo>
145
146export type FileType = keyof typeof FILE_TYPE
147
148/** Slate under 75%, amber from 75%, red from 90%: colour only once it matters. */
149export const levelColor = (percent: number): string => (percent >= 90 ? C.bad : percent >= 75 ? C.warn : INK)
150
151/*
152 * The terminal's colours. The terminal draws each status in the engine theme key
153 * that means the same thing, so it follows the person's terminal theme (dark,
154 * light, colour-blind, ANSI-only) instead of a fixed hex that may not read on it:
155 *
156 * - green  C.ok     → 'success'
157 * - red    C.bad    → 'error'
158 * - amber  C.warn   → 'warning'
159 * - blue   C.blue   → 'suggestion'
160 * - purple C.purple → 'merged'
161 * - the greys (MUTED, GRAY, TRACK) → the terminal's own dim, never a grey hex
162 * - quantity (INK, slate) → the terminal's default foreground
163 * - the shades within one chart (RAMP, cyan, orchid) → plain and dim in turn
164 *   (TERM_TINT), the blue ramp as `suggestion` and dimmed `suggestion`
165 * - any other hex → the default foreground: no fixed hex reaches the terminal,
166 *   where it can vanish on a light, an ANSI-only or a colour-blind theme.
167 */
168const themeKey: Record<string, string> = {}
169export const THEME_KEY: Readonly<Record<string, string>> = themeKey
170
171const QUIET = new Set<string>()
172
173/** Text props on the terminal: a theme key, the terminal's dim, or neither (the default foreground). */
174export type TermInk = { color?: string; dimColor?: boolean }
175
176/**
177 * The chart shades on the terminal, which has no colours to spare for them: the
178 * slate ramp (quantity) is the default foreground and dim in turn, the blue ramp
179 * `suggestion` and dimmed `suggestion` in turn, cyan plain and orchid dim. A
180 * bar's parts are all runs of the same heavy line (METER), told apart by these
181 * inks alone: no shade or dither glyphs, which render as a checkerboard.
182 */
183const termTint: Record<string, TermInk> = {}
184export const TERM_TINT: Readonly<Record<string, TermInk>> = termTint
185
186/** Whether `color` is one of the kit's tokens (a status, a grey, a chart shade), not data such as a GitHub label's hex. */
187export const isKitColor = (color: string): boolean => QUIET.has(color) || color in THEME_KEY || color in TERM_TINT
188
189/** A raw colour (hex, rgb(), hsl()) rather than a theme key's name. */
190const RAW = /^(#|rgba?\(|hsla?\()/i
191
192/**
193 * A colour's Text props on the terminal: a status as its theme key, a grey as
194 * `dimColor`, a chart shade as TERM_TINT says, a theme key's name as itself, and
195 * any other raw colour as nothing (the default foreground). Nothing for no colour.
196 */
197export const termInk = (color?: string): TermInk => {
198  if (!color) return {}
199  if (QUIET.has(color)) return { dimColor: true }
200  const key = THEME_KEY[color]
201  if (key) return { color: key }
202  const tint = TERM_TINT[color]
203  if (tint) return { ...tint }
204  return RAW.test(color) ? {} : { color }
205}
206
207/**
208 * One glyph per idea, shared so mods read alike (the SVG icons are keyed by these).
209 * Each is what the terminal draws: one cell, and never a character with an emoji
210 * presentation (Unicode's Emoji property: ⚒ ⚠ ⚡ ⏱ ↕ ◼ draw as emoji in some
211 * terminals and take two cells).
212 */
213export const GLYPH = {
214  context: '◕',
215  cost: '$',
216  time: '◷',
217  turns: '↻',
218  // The place-of-interest sign, as on a Command key: what the tools are called with.
219  tools: '⌘',
220  files: '✎',
221  agents: '✦',
222  limits: '◔',
223  layers: '▤',
224  branch: '⎇',
225  pr: '⇡',
226  running: '◐',
227  done: '✓',
228  failed: '✕',
229  stopped: '■',
230  pending: '◌',
231  up: '↑',
232  down: '↓',
233} as const
234
235/**
236 * A status's mark: one glyph and the colour that means it, the same on every
237 * surface. Draw it with `k.status(kind)`, never by hand, so a running task, a
238 * running server and a pending check all read alike.
239 */
240export const STATUS = {
241  running: { glyph: GLYPH.running, color: '' },
242  pending: { glyph: GLYPH.pending, color: '' },
243  done: { glyph: GLYPH.done, color: '' },
244  failed: { glyph: GLYPH.failed, color: '' },
245  warn: { glyph: '▲', color: '' },
246  merged: { glyph: '◆', color: '' },
247  stopped: { glyph: GLYPH.stopped, color: '' },
248  idle: { glyph: '○', color: '' },
249}
250
251export type StatusKind = keyof typeof STATUS
252
253/** The skin the kit wears now: a key of SKINS, or `custom` for a skin passed in whole. */
254export let SKIN: SkinId | 'custom' = DEFAULT_SKIN
255
256/**
257 * Puts on a skin: a zen theme pack's (a key of SKINS, kit/skins.ts) or one made
258 * in full. Every colour above takes the skin's value, and the terminal's mapping
259 * follows, so each meaning keeps its theme key. Wear one before the first
260 * drawing (at the top of the hooks module); the kit starts in DEFAULT_SKIN.
261 */
262export const wear = (skin: SkinId | Skin): void => {
263  const s = typeof skin === 'string' ? SKINS[skin] : skin
264  if (!s) throw new Error(`no skin '${String(skin)}'`)
265  SKIN = typeof skin === 'string' ? skin : 'custom'
266  Object.assign(C, { ok: s.ok, warn: s.warn, bad: s.bad, blue: s.blue, purple: s.purple, cyan: s.cyan, slate: s.slate, orchid: s.orchid })
267  INK = s.slate
268  RAMP.blue.splice(0, 4, ...s.ramp.blue)
269  RAMP.slate.splice(0, 4, ...s.ramp.slate)
270  FILL.selected = tint(s.blue, 0.13)!
271  FILL.selectedBlurred = tint(s.blue, 0.065)!
272  MUTED = s.muted
273  Object.assign(GRAY, s.gray)
274  const status: Record<StatusKind, string> = {
275    running: s.blue,
276    pending: s.blue,
277    done: s.ok,
278    failed: s.bad,
279    warn: s.warn,
280    merged: s.purple,
281    stopped: s.muted,
282    idle: s.muted,
283  }
284  for (const kind of Object.keys(status) as StatusKind[]) STATUS[kind].color = status[kind]
285  for (const key of Object.keys(themeKey)) delete themeKey[key]
286  Object.assign(themeKey, { [s.ok]: 'success', [s.bad]: 'error', [s.warn]: 'warning', [s.blue]: 'suggestion', [s.purple]: 'merged' })
287  QUIET.clear()
288  for (const grey of [s.muted, s.gray.light, s.gray.mid, s.gray.dark, TRACK]) QUIET.add(grey)
289  for (const key of Object.keys(termTint)) delete termTint[key]
290  Object.assign(termTint, {
291    [s.ramp.slate[0]]: {},
292    [s.ramp.slate[1]]: { dimColor: true },
293    [s.ramp.slate[2]]: {},
294    [s.ramp.slate[3]]: { dimColor: true },
295    [s.ramp.blue[1]]: { color: 'suggestion', dimColor: true },
296    [s.ramp.blue[2]]: { color: 'suggestion' },
297    [s.ramp.blue[3]]: { color: 'suggestion', dimColor: true },
298    [s.cyan]: {},
299    [s.orchid]: { dimColor: true },
300  })
301}
302
303wear(DEFAULT_SKIN)
304
305/**
306 * Tree connectors for nested rows (agents under the agent that spawned them,
307 * files under folders), each two cells wide so levels indent on the grid.
308 */
309export const TREE = { tee: '├─', last: '└─', pipe: '│ ', blank: '  ' } as const
310
311/**
312 * A nested row's connector: for each level above it, a pipe where that level has
313 * more rows below, else blank; then a tee, or an elbow for the last child.
314 * Empty at the top level.
315 */
316export const treePrefix = (guides: boolean[], last: boolean, depth = guides.length + 1): string =>
317  depth === 0 ? '' : `${guides.map(g => (g ? TREE.pipe : TREE.blank)).join('')}${last ? TREE.last : TREE.tee}`
318

1/*
2 * The SVG documents the experiments draw, as strings: each one self-contained,
3 * well under the engine's 131072-character cap unless it probes the cap.
4 */
5
6const NS = 'xmlns="http://www.w3.org/2000/svg"'
7const W = 240
8const H = 80
9
10/** An `<svg>` of the usual size around `body`. */
11export const doc = (body: string, w = W, h = H) => `<svg ${NS} width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">${body}</svg>`
12
13const label = (x: number, y: number, s: string) =>
14  `<text x="${x}" y="${y}" font-family="-apple-system, system-ui, sans-serif" font-size="10" fill="#8e8e93">${s}</text>`
15
16export const LINEAR = doc(
17  `<defs>
18    <linearGradient id="h" x1="0" x2="1"><stop offset="0" stop-color="#2f80ed"/><stop offset="1" stop-color="#9b51e0"/></linearGradient>
19    <linearGradient id="v" x1="0" x2="0" y1="0" y2="1"><stop offset="0" stop-color="#27ae60"/><stop offset="0.5" stop-color="#f2c94c" stop-opacity="0.6"/><stop offset="1" stop-color="#eb5757"/></linearGradient>
20  </defs>
21  <rect x="8" y="8" width="140" height="14" rx="7" fill="url(#h)"/>
22  <rect x="8" y="30" width="140" height="6" rx="3" fill="url(#h)" opacity="0.5"/>
23  <rect x="168" y="8" width="24" height="64" rx="4" fill="url(#v)"/>
24  ${label(8, 60, 'horizontal, vertical, stop-opacity')}`,
25)
26
27export const RADIAL = doc(
28  `<defs>
29    <radialGradient id="r" cx="0.35" cy="0.35" r="0.65"><stop offset="0" stop-color="#ffffff"/><stop offset="0.4" stop-color="#56ccf2"/><stop offset="1" stop-color="#2f80ed"/></radialGradient>
30    <radialGradient id="g" fx="0.5" fy="0.5"><stop offset="0" stop-color="#f2994a" stop-opacity="1"/><stop offset="1" stop-color="#f2994a" stop-opacity="0"/></radialGradient>
31  </defs>
32  <circle cx="40" cy="40" r="30" fill="url(#r)"/>
33  <circle cx="120" cy="40" r="34" fill="url(#g)"/>
34  ${label(170, 44, 'sphere, glow')}`,
35)
36
37export const BLUR = doc(
38  `<defs>
39    <filter id="b1"><feGaussianBlur stdDeviation="1"/></filter>
40    <filter id="b4" x="-50%" y="-50%" width="200%" height="200%"><feGaussianBlur stdDeviation="4"/></filter>
41  </defs>
42  <rect x="10" y="20" width="40" height="40" fill="#2f80ed"/>
43  <rect x="70" y="20" width="40" height="40" fill="#2f80ed" filter="url(#b1)"/>
44  <rect x="130" y="20" width="40" height="40" fill="#2f80ed" filter="url(#b4)"/>
45  ${label(10, 74, 'sharp, 1, 4')}`,
46)
47
48export const SHADOW = doc(
49  `<defs>
50    <filter id="ds" x="-30%" y="-30%" width="160%" height="160%"><feDropShadow dx="2" dy="3" stdDeviation="2.5" flood-color="#000" flood-opacity="0.35"/></filter>
51    <filter id="old" x="-30%" y="-30%" width="160%" height="160%">
52      <feGaussianBlur in="SourceAlpha" stdDeviation="2"/><feOffset dx="2" dy="2" result="o"/>
53      <feComponentTransfer><feFuncA type="linear" slope="0.4"/></feComponentTransfer>
54      <feMerge><feMergeNode/><feMergeNode in="SourceGraphic"/></feMerge>
55    </filter>
56  </defs>
57  <rect x="14" y="14" width="80" height="40" rx="6" fill="#fff" stroke="#ddd" filter="url(#ds)"/>
58  <rect x="124" y="14" width="80" height="40" rx="6" fill="#fff" stroke="#ddd" filter="url(#old)"/>
59  ${label(14, 72, 'feDropShadow, blur+offset+merge')}`,
60)
61
62export const MASKS = doc(
63  `<defs>
64    <clipPath id="c"><circle cx="40" cy="36" r="26"/></clipPath>
65    <linearGradient id="fade" x1="0" x2="1"><stop offset="0" stop-color="#fff"/><stop offset="1" stop-color="#000"/></linearGradient>
66    <mask id="m"><rect x="80" y="10" width="70" height="52" fill="url(#fade)"/></mask>
67  </defs>
68  <g clip-path="url(#c)"><rect x="0" y="0" width="80" height="80" fill="#9b51e0"/><rect x="0" y="30" width="80" height="12" fill="#f2c94c"/></g>
69  <rect x="80" y="10" width="70" height="52" fill="#27ae60" mask="url(#m)"/>
70  <rect x="160" y="10" width="30" height="52" fill="#eb5757" opacity="0.25"/>
71  <rect x="196" y="10" width="30" height="52" fill="#eb5757" fill-opacity="0.6" stroke="#eb5757" stroke-opacity="1"/>
72  ${label(8, 76, 'clipPath, mask, opacity, fill-opacity')}`,
73)
74
75export const FONTS = doc(
76  `<text x="8" y="16" font-family="-apple-system, system-ui, sans-serif" font-size="13">System sans 13</text>
77  <text x="8" y="32" font-family="Georgia, serif" font-style="italic" font-size="13">Serif italic</text>
78  <text x="8" y="48" font-family="ui-monospace, Menlo, monospace" font-size="12" font-weight="700">Mono bold 0123</text>
79  <text x="8" y="66" font-family="system-ui" font-size="10" letter-spacing="2" text-decoration="underline" fill="#2f80ed">tracked, underlined</text>
80  <text x="232" y="30" font-family="system-ui" font-size="20" text-anchor="end" fill="#eb5757">end</text>
81  <path id="arc" d="M150 70 Q190 40 232 70" fill="none"/>
82  <text font-size="9" font-family="system-ui"><textPath href="#arc">along a path</textPath></text>`,
83)
84
85export const PATTERN = doc(
86  `<defs>
87    <pattern id="p" width="8" height="8" patternUnits="userSpaceOnUse"><path d="M0 8 L8 0" stroke="#8e8e93" stroke-width="1"/></pattern>
88    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0 0 L10 5 L0 10z" fill="#2f80ed"/></marker>
89    <symbol id="dot" viewBox="0 0 10 10"><circle cx="5" cy="5" r="4" fill="#27ae60"/></symbol>
90  </defs>
91  <rect x="8" y="8" width="70" height="50" fill="url(#p)" stroke="#8e8e93"/>
92  <line x1="96" y1="50" x2="150" y2="14" stroke="#2f80ed" stroke-width="2" marker-end="url(#arrow)"/>
93  <use href="#dot" x="170" y="10" width="20" height="20"/><use href="#dot" x="196" y="30" width="30" height="30"/>
94  ${label(8, 74, 'pattern, marker, symbol+use')}`,
95)
96
97/** SMIL: a blink (discrete opacity), a fade, a rotation and a path morph. */
98const SMIL_BODY = `
99  <circle cx="20" cy="30" r="8" fill="#eb5757"><animate attributeName="opacity" values="1;0" dur="1s" calcMode="discrete" repeatCount="indefinite"/></circle>
100  <circle cx="60" cy="30" r="8" fill="#2f80ed"><animate attributeName="opacity" values="1;0.1;1" dur="2s" repeatCount="indefinite"/></circle>
101  <g transform="translate(100 30)"><rect x="-9" y="-9" width="18" height="18" fill="#9b51e0"><animateTransform attributeName="transform" type="rotate" from="0" to="360" dur="3s" repeatCount="indefinite"/></rect></g>
102  <path fill="#27ae60" d="M140 20 L160 20 L160 40 L140 40 Z"><animate attributeName="d" dur="2s" repeatCount="indefinite" values="M140 20 L160 20 L160 40 L140 40 Z;M150 18 L162 30 L150 42 L138 30 Z;M140 20 L160 20 L160 40 L140 40 Z"/></path>
103  <rect x="180" y="26" width="0" height="8" fill="#f2994a"><animate attributeName="width" values="0;50;0" dur="2s" repeatCount="indefinite"/></rect>
104  ${label(8, 66, 'blink, fade, rotate, morph d, grow')}`
105
106export const SMIL = doc(SMIL_BODY)
107
108/** CSS animation inside the document's own `<style>`. */
109const CSS_BODY = `
110  <style>
111    @keyframes spin { to { transform: rotate(360deg) } }
112    @keyframes pulse { 0%, 100% { opacity: 1 } 50% { opacity: 0.15 } }
113    @keyframes slide { from { transform: translateX(0) } to { transform: translateX(80px) } }
114    .spin { transform-origin: 30px 30px; animation: spin 1.5s linear infinite }
115    .pulse { animation: pulse 1.2s ease-in-out infinite }
116    .slide { animation: slide 2s ease-in-out infinite alternate }
117  </style>
118  <rect class="spin" x="20" y="20" width="20" height="20" fill="#9b51e0"/>
119  <circle class="pulse" cx="80" cy="30" r="10" fill="#2f80ed"/>
120  <rect class="slide" x="110" y="24" width="12" height="12" rx="6" fill="#27ae60"/>
121  ${label(8, 66, 'CSS @keyframes: spin, pulse, slide')}`
122
123export const CSS_KEYFRAMES = doc(CSS_BODY)
124
125export const HOVER = doc(
126  `<style>
127    .cell { fill: #e0e0e0; transition: fill 120ms }
128    .cell:hover { fill: #2f80ed }
129    .grow { transform-origin: 200px 30px; transition: transform 150ms }
130    .grow:hover { transform: scale(1.4) }
131  </style>
132  <rect class="cell" x="8" y="10" width="36" height="36" rx="4"/>
133  <rect class="cell" x="50" y="10" width="36" height="36" rx="4"/>
134  <rect class="cell" x="92" y="10" width="36" height="36" rx="4"/>
135  <circle class="grow" cx="200" cy="30" r="14" fill="#f2994a"/>
136  ${label(8, 66, 'CSS :hover with transitions')}`,
137)
138
139export const TITLE = doc(
140  `<rect x="8" y="10" width="60" height="40" fill="#2f80ed"><title>Blue: 42 tokens</title></rect>
141  <circle cx="110" cy="30" r="20" fill="#27ae60"><title>Green circle tooltip</title></circle>
142  ${label(8, 66, 'hover for a native <title> tooltip')}`,
143)
144
145export const SCRUB_SCRIPT = doc(
146  `<text id="t" x="8" y="30" font-size="14" fill="#27ae60">script did not run (stripped or blocked)</text>
147  <script>document.getElementById('t').textContent = 'SCRIPT RAN'; document.getElementById('t').setAttribute('fill', 'red')</script>`,
148  320,
149)
150
151export const SCRUB_ONLOAD = `<svg ${NS} width="320" height="40" onload="document.getElementById('t').textContent='ONLOAD RAN'"><text id="t" x="8" y="24" font-size="14" fill="#27ae60" onclick="this.textContent='ONCLICK RAN'">onload did not run (click me too)</text></svg>`
152
153export const SCRUB_HREF = doc(
154  `<image href="https://github.githubassets.com/favicons/favicon.png" x="8" y="8" width="32" height="32"/>
155  <a href="https://example.com"><text x="48" y="24" font-size="12" fill="#2f80ed">external a href</text></a>
156  ${label(48, 44, 'an external image shows left if not stripped')}`,
157  320,
158)
159
160export const SCRUB_DATA_HREF = doc(
161  `<image x="8" y="8" width="32" height="32" href="data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 10 10'%3E%3Ccircle cx='5' cy='5' r='5' fill='%23eb5757'/%3E%3C/svg%3E"/>
162  ${label(48, 28, 'a data: image (red dot) shows left if kept')}`,
163  320,
164)
165
166export const SCRUB_FOREIGN = doc(
167  `<foreignObject x="8" y="8" width="300" height="40"><div xmlns="http://www.w3.org/1999/xhtml" style="font: 13px system-ui; color: #eb5757">FOREIGN OBJECT HTML DRAWN <b>bold</b></div></foreignObject>
168  ${label(8, 66, 'blank above: foreignObject stripped')}`,
169  320,
170)
171
172/** A document of exactly `n` characters, padded with a comment. */
173export const sized = (n: number) => {
174  const head = `<svg ${NS} width="240" height="24"><text x="4" y="16" font-size="12">${n} characters</text><!--`
175  const tail = '--></svg>'
176  return head + 'x'.repeat(Math.max(0, n - head.length - tail.length)) + tail
177}
178

1import type { ClientModule } from 'claude-code'
2
3type Props = { ms?: number }
4type State = { on: boolean; ticks: number }
5
6/** A dot that blinks on the surface's frame clock, every `ms` (500 by default). */
7const Blink: ClientModule<Props, State> = (props, surface) => {
8  const { Box, Text } = surface.elements
9  if (surface.state === undefined) {
10    let ticks = 0
11    surface.every(props.ms ?? 500, () => {
12      ticks++
13      surface.setState({ on: ticks % 2 === 0, ticks })
14    })
15    surface.setState({ on: true, ticks: 0 })
16  }
17  const on = surface.state?.on ?? true
18  return (
19    <Box flexDirection="row" gap={1}>
20      <Text key="dot" color={on ? '#eb5757' : '#3a3a3c'}>●</Text>
21      <Text dimColor>{on ? 'on ' : 'off'} tick {surface.state?.ticks ?? 0}</Text>
22    </Box>
23  )
24}
25
26export default Blink
27

1import type { ClientModule } from 'claude-code'
2
3type State = { step: number }
4
5/** Twelve steps of blue, up and down, every 80 ms: a fade made of colour changes. */
6const RAMP = ['#0b1a2e', '#102a4a', '#163a66', '#1c4a82', '#225a9e', '#2f80ed', '#4a90f0', '#66a3f3', '#82b5f5', '#9ec8f8', '#bad9fa', '#d6eafc']
7
8const Fade: ClientModule<Record<string, never>, State> = (_props, surface) => {
9  const { Box, Text } = surface.elements
10  if (surface.state === undefined) {
11    let step = 0
12    surface.every(80, () => surface.setState({ step: ++step }))
13    surface.setState({ step: 0 })
14  }
15  const step = surface.state?.step ?? 0
16  const i = step % (RAMP.length * 2 - 2)
17  const at = i < RAMP.length ? i : RAMP.length * 2 - 2 - i
18  return (
19    <Box flexDirection="column">
20      <Text key="swatch" color={RAMP[at]}>████████ colour step {at}</Text>
21      <Text key="dim" dimColor={step % 10 < 5}>dimColor toggled every 5 steps</Text>
22    </Box>
23  )
24}
25
26export default Fade
27

1import type { ClientModule } from 'claude-code'
2
3type State = { step: number }
4
5const EIGHTHS = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉']
6
7/** A bar that grows to the region's width and back, in eighths of a cell, every 50 ms. */
8const Bar: ClientModule<Record<string, never>, State> = (_props, surface) => {
9  const { Box, Text } = surface.elements
10  if (surface.state === undefined) {
11    let step = 0
12    surface.every(50, () => surface.setState({ step: ++step }))
13    surface.setState({ step: 0 })
14  }
15  const width = Math.max(8, Math.min(surface.columns || 40, 60) - 8)
16  const span = width * 8
17  const step = surface.state?.step ?? 0
18  const i = step % (span * 2)
19  const eighths = i < span ? i : span * 2 - i
20  const full = Math.floor(eighths / 8)
21  const bar = '█'.repeat(full) + EIGHTHS[eighths % 8]
22  return (
23    <Box flexDirection="row">
24      <Text key="bar" color={eighths > span * 0.8 ? '#eb5757' : '#2f80ed'}>{bar.padEnd(width, ' ')}</Text>
25      <Text dimColor> {Math.round((eighths / span) * 100)}%</Text>
26    </Box>
27  )
28}
29
30export default Bar
31

1import type { ClientModule } from 'claude-code'
2
3type State = { step: number }
4
5const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
6
7/** A braille spinner at 80 ms a frame. */
8const Spinner: ClientModule<{ label?: string }, State> = (props, surface) => {
9  const { Box, Text } = surface.elements
10  if (surface.state === undefined) {
11    let step = 0
12    surface.every(80, () => surface.setState({ step: ++step }))
13    surface.setState({ step: 0 })
14  }
15  const step = surface.state?.step ?? 0
16  return (
17    <Box flexDirection="row" gap={1}>
18      <Text key="frame" color="#9b51e0">{FRAMES[step % FRAMES.length]}</Text>
19      <Text>{props.label ?? 'working'}</Text>
20    </Box>
21  )
22}
23
24export default Spinner
25