previews

1import { atom, read, update } from 'claude-code'
2import type { Elements, EngineInterface, Register, RenderNode } from 'claude-code'
3
4import { boxFor, cacheName, imagePath, needsConversion, parseSize } from './image'
5
6const shown = atom({ plugin: 'previews', key: 'shown' } as const, null)
7
8let home = ''
9/** image path → what to draw (a PNG path and its size), worked out once. */
10const prepared = new Map<string, Promise<{ png: string; width: number; height: number } | null>>()
11
12async function prepare($: EngineInterface, path: string) {
13  const stat = await $.fs.stat(path).catch(() => null)
14  if (!stat) return null
15  let png = path
16  if (needsConversion(path)) {
17    const dir = `${home}/Library/Caches/claude-previews`
18    png = `${dir}/${cacheName(path, (stat as { mtimeMs?: number }).mtimeMs ?? 0)}`
19    await $.process.run(['mkdir', '-p', dir])
20    const r = await $.process.run(['sips', '-s', 'format', 'png', path, '--out', png])
21    if (r.exitCode !== 0) return null
22  }
23  const size = parseSize((await $.process.run(['sips', '-g', 'pixelWidth', '-g', 'pixelHeight', png])).stdout)
24  return { png, ...size }
25}
26
27function prepared$($: EngineInterface, path: string) {
28  if (!prepared.has(path)) prepared.set(path, prepare($, path).catch(() => null))
29  return prepared.get(path)!
30}
31
32/** How tall a preview is drawn, from the setting. */
33let previewRows = 14
34
35/** A row plus a 🖼 line per image it read; a picture only while the pointer is on its line. */
36async function withPreviews($: EngineInterface, ui: Elements['terminal'], requestId: string, columns: number, row: RenderNode, paths: string[]) {
37  const { Box, Client, Image } = ui
38  const current = await read($, shown)
39  const maxColumns = Math.max(10, columns - 6)
40  const lines = await Promise.all(
41    paths.map(async (path, i) => {
42      const id = `${requestId}~${i}`
43      const name = path.split('/').pop() ?? path
44      const isShown = current === id
45      const pic = isShown ? await prepared$($, path) : null
46      const box = pic && boxFor(pic.width, pic.height, previewRows, maxColumns)
47      return (
48        <Box flexDirection="column">
49          <Client key={`preview-${id}`} module="./preview.tsx" props={{ name, shown: isShown }} />
50          {pic && box && (
51            <Box marginLeft={4}>
52              <Image source={{ file: pic.png, format: 'png' }} rows={box.rows} columns={box.columns} alt={name} />
53            </Box>
54          )}
55        </Box>
56      )
57    }),
58  )
59  return (
60    <Box flexDirection="column">
61      {row}
62      {lines}
63    </Box>
64  )
65}
66
67export const register: Register = (on, options) => {
68  previewRows = typeof options.rows === 'number' && options.rows > 0 ? Math.min(60, options.rows) : 14
69
70  on('session.start', async ($, e, next) => {
71    home = (await $.process.run(['sh', '-c', 'echo "$HOME"'])).stdout.trim()
72    return next(e)
73  })
74
75  // A single tool row (expanded transcripts, --verbose).
76  on('ui.render', { component: 'ToolUse' }, async ($, e, next) => {
77    const path = imagePath(e.props.tool, e.props.input)
78    if (!path || e.surface !== 'terminal') return next(e)
79    return withPreviews($, $.ui.resolve(e), e.requestId, e.viewport?.columns ?? 80, await next(e), [path])
80  })
81
82  // The collapsed row ("Read 3 files") that groups tool calls by default.
83  on('ui.render', { component: 'ToolGroup' }, async ($, e, next) => {
84    if (e.surface !== 'terminal' || e.props.isExpanded) return next(e)
85    const paths = e.props.calls.map(c => imagePath(c.tool, c.input)).filter((p): p is string => p !== undefined)
86    if (paths.length === 0) return next(e)
87    return withPreviews($, $.ui.resolve(e), e.requestId, e.viewport?.columns ?? 80, await next(e), paths)
88  })
89
90  on('ui.message', async ($, e, next) => {
91    if (!e.element.startsWith('preview-')) return next(e)
92    const id = e.element.slice('preview-'.length)
93    await update($, shown, current => (e.data === 'enter' ? id : current === id ? null : current))
94    return next(e)
95  })
96}
97

1/** Formats the terminal draws as-is, and the ones macOS's `sips` converts to PNG first. */
2const PNG = /\.png$/i
3const CONVERTIBLE = /\.(jpe?g|gif|webp|heic|heif|tiff?|bmp)$/i
4
5export function isImage(path: string): boolean {
6  return PNG.test(path) || CONVERTIBLE.test(path)
7}
8
9export function needsConversion(path: string): boolean {
10  return !PNG.test(path) && CONVERTIBLE.test(path)
11}
12
13/** The image path a Read call opened, when it's an image. */
14export function imagePath(tool: string, input: unknown): string | undefined {
15  if (tool !== 'Read' || !input || typeof input !== 'object') return undefined
16  const path = (input as { file_path?: unknown }).file_path
17  return typeof path === 'string' && path.startsWith('/') && isImage(path) ? path : undefined
18}
19
20/**
21 * A box that keeps the picture's shape (a cell is about twice as tall as wide): `rows` tall when it fits,
22 * shorter when the screen's width caps it.
23 */
24export function boxFor(width: number, height: number, rows: number, maxColumns: number): { rows: number; columns: number } {
25  if (!(width > 0 && height > 0)) return { rows, columns: Math.min(rows * 2, maxColumns) }
26  const ratio = width / height
27  const columns = Math.max(4, Math.min(maxColumns, Math.round(rows * 2 * ratio)))
28  return { rows: Math.max(1, Math.min(rows, Math.round(columns / (2 * ratio)))), columns }
29}
30
31/** `sips -g pixelWidth -g pixelHeight` output → size. */
32export function parseSize(sips: string): { width: number; height: number } {
33  const n = (key: string) => Number(new RegExp(`${key}:\\s*(\\d+)`).exec(sips)?.[1] ?? 0)
34  return { width: n('pixelWidth'), height: n('pixelHeight') }
35}
36
37/** A stable file name for a converted copy (FNV-1a of the path and its modification time). */
38export function cacheName(path: string, mtimeMs: number): string {
39  let h = 0x811c9dc5
40  for (const c of `${path}|${mtimeMs}`) h = Math.imul(h ^ c.charCodeAt(0), 0x01000193) >>> 0
41  return `${h.toString(16)}.png`
42}
43

1import type { ClientModule } from 'claude-code'
2
3// The 🖼 line: drawn by the surface so pointer enter/leave reach it; the hooks module draws the picture.
4const PreviewLabel: ClientModule<{ name: string; shown: boolean }> = ({ name, shown }, surface) => {
5  const { Text } = surface.elements
6  surface.onPointer(ev => {
7    if (ev.type === 'enter' || ev.type === 'leave') surface.post(ev.type)
8  })
9  return <Text dimColor={!shown}>  🖼  {shown ? name : `${name} · hover to preview`}</Text>
10}
11export default PreviewLabel
12

1/** The ToolUse row whose preview the pointer is over, or null. */
2export type ShownPreview = string | null
3
4declare module 'claude-code' {
5  interface PluginState {
6    previews: { shown: ShownPreview }
7  }
8}
9