image-preview

1import { atom, memberOf, read, update } from 'claude-code'
2import type { EngineInterface, RenderInput, RenderSurface, Register, Timer } from 'claude-code'
3
4import type { ConvertedFile, ImageItem } from '../types'
5import {
6  IMAGE_EXT,
7  absolutize,
8  baseName,
9  caption,
10  cellBox,
11  findImageCandidates,
12  isPng,
13  pngDimensions,
14  sipsDimensions,
15} from './images'
16
17const PANE = 'image-preview'
18const TITLE = '画像プレビュー'
19const KEEP = 20
20const PER_CALL = 4
21// What the terminal is asked to decode; bigger files get a caption instead.
22const MAX_BYTES = 32 * 1024 * 1024
23// A Bash run "produces" an image modified since it started (with clock slack).
24const SLACK_MS = 2000
25const CONVERT_MAX_PX = 1024
26// Converted copies kept in the session's cache; older ones are removed, never one the pane shows.
27const CACHE_KEEP = 50
28const CACHE_NAME = 'claude-image-preview'
29// A session's cache left behind (the process was killed before session.end) goes after a day.
30const STALE_MS = 24 * 60 * 60 * 1000
31// A live session touches its cache this often, so one left idle for a day is not taken for killed.
32const HEARTBEAT_MS = 60 * 60 * 1000
33// The pane's own rows that are not the picture: the step buttons, the caption, the path.
34const PANE_CHROME_ROWS = 3
35const PRUNED = 'キャッシュから削除済み'
36
37const images = atom({ plugin: 'image-preview', key: 'images' } as const, [])
38const cursor = atom({ plugin: 'image-preview', key: 'cursor' } as const, 0)
39const byTool = atom({ plugin: 'image-preview', key: 'byTool' } as const, [])
40const converted = atom({ plugin: 'image-preview', key: 'converted' } as const, [] as ConvertedFile[])
41
42// Where a call's paths are read from: taken in the hook itself, since a timer that outlives
43// the hook reads the session's directory, not that of the call (a subagent's worktree).
44type CallPlace = { cwd: string; home: string | undefined; sessionId: string }
45
46// Session caches made and checked by this load of the module, by session id.
47const cacheDirs = new Map<string, string>()
48let heartbeat: Timer | undefined
49
50// Each hour while this process keeps a cache, its mtime is moved on: another session's sweep
51// reads a folder untouched for a day as a killed session's, however idle this one is.
52function keepAlive($: EngineInterface): void {
53  heartbeat ??= $.clock.every(HEARTBEAT_MS, () => {
54    if (cacheDirs.size === 0) {
55      heartbeat?.cancel()
56      heartbeat = undefined
57      return
58    }
59    for (const dir of cacheDirs.values()) void $.process.run(['touch', '-c', '--', dir]).catch(() => undefined)
60  })
61}
62// Work after a tool call runs one at a time, in the order the calls finished.
63let queue: Promise<void> = Promise.resolve()
64
65async function sips($: EngineInterface, argv: string[]) {
66  return $.process.run(['sips', ...argv], { timeoutMs: 15_000 }).catch(() => undefined)
67}
68
69// A session id as a folder name: the same id always gives the same name, so a reload finds it again.
70const folderName = (sessionId: string) => sessionId.replace(/[^\w-]/g, '_')
71
72// TMPDIR when set, else ~/.cache: never a shared /tmp.
73async function rootDir($: EngineInterface): Promise<string | undefined> {
74  const tmp = (await $.env.get('TMPDIR'))?.replace(/\/+$/, '')
75  const home = (await $.env.get('HOME'))?.replace(/\/+$/, '')
76  return tmp !== undefined && tmp !== '' ? tmp : home !== undefined && home !== '' ? `${home}/.cache` : undefined
77}
78
79// `<parent>/<name>` when it is already a real directory (not a link) right where the parent resolves.
80async function checkedChild($: EngineInterface, parent: string, name: string): Promise<string | undefined> {
81  const [where, above] = await Promise.all([
82    $.fs.stat(`${parent}/${name}`, { resolve: true }).catch(() => undefined),
83    $.fs.stat(parent, { resolve: true }).catch(() => undefined),
84  ])
85  if (where?.kind !== 'dir' || where.isLink || above?.realPath === undefined) return undefined
86  return where.realPath === `${above.realPath}/${name}` ? where.realPath : undefined
87}
88
89/**
90 * `<parent>/<name>` as a folder only this user can reach: made 0700, then checked to be
91 * a real directory of ours (not a link, owned by us) right where the parent resolves,
92 * so nothing planted beforehand can take a write.
93 */
94async function privateChild($: EngineInterface, parent: string, name: string): Promise<string | undefined> {
95  const made = await $.process
96    .run(['/bin/sh', '-c', 'umask 077 && mkdir -p -m 700 -- "$1" && [ -d "$1" ] && [ ! -L "$1" ] && [ -O "$1" ] && chmod 700 -- "$1"', 'sh', `${parent}/${name}`])
97    .catch(() => undefined)
98  if (made?.exitCode !== 0) return undefined
99  return checkedChild($, parent, name)
100}
101
102// One cache per session: a session's prune never touches what another session's rows draw.
103async function cacheFolder($: EngineInterface, sessionId: string): Promise<string | undefined> {
104  const known = cacheDirs.get(sessionId)
105  if (known !== undefined) return known
106  // Work queued for a session a /clear has since ended: its folder is gone and stays gone.
107  if (sessionId !== (await $.session.id())) return undefined
108  const parent = await rootDir($)
109  if (parent === undefined) return undefined
110  const base = await privateChild($, parent, CACHE_NAME)
111  if (base === undefined) return undefined
112  const dir = await privateChild($, base, folderName(sessionId))
113  if (dir !== undefined) {
114    cacheDirs.set(sessionId, dir)
115    keepAlive($)
116  }
117  return dir
118}
119
120// The plugin's base folder as it already stands; nothing is made.
121async function existingBase($: EngineInterface): Promise<string | undefined> {
122  const parent = await rootDir($)
123  return parent === undefined ? undefined : checkedChild($, parent, CACHE_NAME)
124}
125
126async function removeSessionCache($: EngineInterface, sessionId: string): Promise<void> {
127  cacheDirs.delete(sessionId)
128  const base = await existingBase($)
129  if (base === undefined) return
130  const dir = await checkedChild($, base, folderName(sessionId))
131  if (dir !== undefined) await $.process.run(['rm', '-rf', '--', dir]).catch(() => undefined)
132}
133
134// Caches of sessions that never reached session.end (a killed process), once a day old.
135async function sweepStale($: EngineInterface, currentId: string): Promise<void> {
136  const base = await existingBase($)
137  if (base === undefined) return
138  const entries = await $.fs.list(base).catch(() => [])
139  const cutoff = (await $.clock.now()) - STALE_MS
140  for (const entry of entries) {
141    if (entry.kind !== 'dir' || entry.name === folderName(currentId)) continue
142    const stat = await $.fs.stat(`${base}/${entry.name}`, { resolve: true }).catch(() => undefined)
143    if (stat === undefined || stat.mtimeMs >= cutoff) continue
144    const dir = await checkedChild($, base, entry.name)
145    if (dir !== undefined) await $.process.run(['rm', '-rf', '--', dir]).catch(() => undefined)
146  }
147}
148
149/**
150 * Notes a converted copy and, past CACHE_KEEP, removes the oldest copies the pane does not
151 * show. Each row that drew a removed copy is told, so it shows a caption, not an empty box.
152 */
153async function trackConverted($: EngineInterface, png: string, toolUseId: string): Promise<void> {
154  const list = await update($, converted, all => {
155    const known = all.find(one => one.png === png)
156    const ids = [...new Set([...(known?.toolUseIds ?? []), toolUseId])]
157    return [...all.filter(one => one.png !== png), { png, toolUseIds: ids }]
158  })
159  if (list.length <= CACHE_KEEP) return
160  const shown = new Set((await read($, images)).flatMap(item => (item.png === undefined ? [] : [item.png])))
161  const dropped = list.filter(one => one.png !== png && !shown.has(one.png)).slice(0, list.length - CACHE_KEEP)
162  if (dropped.length === 0) return
163  const gone = new Set(dropped.map(one => one.png))
164  await update($, converted, all => all.filter(one => !gone.has(one.png)))
165  for (const one of dropped) {
166    await $.process.run(['rm', '-f', '--', one.png]).catch(() => undefined)
167    for (const id of one.toolUseIds) {
168      await update($, memberOf(byTool, { requestId: id }), items =>
169        items.map(item => {
170          if (item.png !== one.png) return item
171          const { png: _removed, ...rest } = item
172          return { ...rest, skipped: PRUNED }
173        }),
174      )
175    }
176  }
177}
178
179// A PNG's size is in its first 24 bytes: read those alone, never the whole file.
180async function pngHeader($: EngineInterface, path: string): Promise<string | undefined> {
181  const ran = await $.process.run(['/bin/sh', '-c', 'head -c 32 -- "$1" | base64', 'sh', path]).catch(() => undefined)
182  return ran?.exitCode === 0 ? ran.stdout.replace(/\s+/g, '') : undefined
183}
184
185async function dimensions($: EngineInterface, path: string) {
186  if (isPng(path)) {
187    const head = await pngHeader($, path)
188    return head === undefined ? undefined : pngDimensions(head)
189  }
190  const ran = await sips($, ['-g', 'pixelWidth', '-g', 'pixelHeight', path])
191  return ran?.exitCode === 0 ? sipsDimensions(ran.stdout) : undefined
192}
193
194async function hashOf(text: string): Promise<string> {
195  const digest = await crypto.subtle.digest('SHA-1', new TextEncoder().encode(text))
196  return [...new Uint8Array(digest)].slice(0, 8).map(b => b.toString(16).padStart(2, '0')).join('')
197}
198
199// Only PNG reaches the terminal's Image: anything else is converted with macOS sips.
200async function convertToPng($: EngineInterface, path: string, mtimeMs: number, place: CallPlace, toolUseId: string): Promise<string | undefined> {
201  const dir = await cacheFolder($, place.sessionId)
202  if (dir === undefined) return undefined
203  const out = `${dir}/${await hashOf(`${path}:${mtimeMs}`)}.png`
204  const ran = await sips($, ['-s', 'format', 'png', '-Z', String(CONVERT_MAX_PX), path, '--out', out])
205  if (ran?.exitCode !== 0) return undefined
206  await trackConverted($, out, toolUseId)
207  return out
208}
209
210async function describe(
211  $: EngineInterface,
212  path: string,
213  toolUseId: string,
214  since: number | undefined,
215  place: CallPlace,
216): Promise<ImageItem | undefined> {
217  const stat = await $.fs.stat(path).catch(() => undefined)
218  if (stat === undefined || stat.kind !== 'file') return undefined
219  // The Image's generation is a whole number; a file system's mtime need not be.
220  const mtimeMs = Math.trunc(stat.mtimeMs)
221  if (since !== undefined && mtimeMs < since - SLACK_MS) return undefined
222
223  const item: ImageItem = {
224    id: `${path}:${mtimeMs}`,
225    path,
226    name: baseName(path),
227    size: stat.size,
228    mtimeMs,
229    toolUseId,
230  }
231  if (stat.size > MAX_BYTES) return { ...item, skipped: '大きすぎるため省略' }
232
233  const dims = await dimensions($, path)
234  const png = isPng(path) ? path : await convertToPng($, path, mtimeMs, place, toolUseId)
235  return {
236    ...item,
237    ...dims,
238    ...(png === undefined ? { skipped: 'PNG に変換できないため省略' } : { png }),
239  }
240}
241
242async function remember($: EngineInterface, found: ImageItem[], toolUseId: string): Promise<void> {
243  if (found.length === 0) return
244  const ids = new Set(found.map(item => item.id))
245  await update($, images, list => [...found, ...list.filter(item => !ids.has(item.id))].slice(0, KEEP))
246  await update($, cursor, () => 0)
247  await update($, memberOf(byTool, { requestId: toolUseId }), () => found)
248  const first = found[0]
249  if (first !== undefined) {
250    $.ui.toast(`画像プレビュー: ${first.name}${found.length > 1 ? ` 他${found.length - 1}件` : ''}`)
251  }
252}
253
254async function collect(
255  $: EngineInterface,
256  groups: string[][],
257  toolUseId: string,
258  since: number | undefined,
259  place: CallPlace,
260): Promise<void> {
261  // A Bash run that only names an image it did not make (`file a.png` after a Write)
262  // does not show that version again.
263  const shown = since === undefined ? new Set<string>() : new Set((await read($, images)).map(item => item.id))
264  const found: ImageItem[] = []
265  const seen = new Set<string>()
266  for (const group of groups) {
267    // The longest reading that exists is the path: `/tmp/a /tmp/b.png` is no file, `/tmp/b.png` is.
268    for (const candidate of group) {
269      const path = absolutize(candidate, place.cwd, place.home)
270      if (path === undefined || !IMAGE_EXT.test(path) || seen.has(path)) continue
271      const item = await describe($, path, toolUseId, since, place)
272      if (item === undefined) continue
273      seen.add(path)
274      if (!shown.has(item.id)) found.push(item)
275      break
276    }
277    if (found.length >= PER_CALL) break
278  }
279  await remember($, found, toolUseId)
280}
281
282// Run after the result has gone back to the model: stat and sips never hold a tool call up.
283function later($: EngineInterface, work: () => Promise<void>): void {
284  $.clock.after(0, () => {
285    queue = queue.then(work).catch(err => $.ui.log(`image-preview: ${String(err)}`, { to: 'debug' }))
286    return queue
287  })
288}
289
290async function placeOf($: EngineInterface): Promise<CallPlace> {
291  const [cwd, home, sessionId] = await Promise.all([$.session.cwd(), $.env.get('HOME'), $.session.id()])
292  return { cwd, home, sessionId }
293}
294
295function thumbnail(e: RenderInput, $: EngineInterface, item: ImageItem, maxColumns: number, maxRows: number) {
296  const surface: RenderSurface = e.surface
297  const label = caption(item)
298  if (surface === 'terminal' && item.png !== undefined) {
299    const { Box, Text, Image } = $.ui.resolve({ ...e, surface })
300    const box = cellBox(item, maxColumns, maxRows)
301    return (
302      <Box key={item.id} flexDirection="column">
303        <Image
304          key={item.id}
305          source={{ file: item.png, format: 'png', generation: Math.trunc(item.mtimeMs) }}
306          columns={box.columns}
307          rows={box.rows}
308          alt={label}
309        />
310        <Text dimColor>🖼️ {label}</Text>
311      </Box>
312    )
313  }
314  const { Text } = $.ui.resolve(e)
315  return (
316    <Text key={item.id} dimColor wrap="truncate-end">
317      🖼️ {label}
318      {item.skipped !== undefined ? `（${item.skipped}）` : ''}
319    </Text>
320  )
321}
322
323export const register: Register = (on, options) => {
324  const isInline = options.inline !== false
325  const inlineRows = Math.min(60, Math.max(1, Number(options.maxRows ?? 12) || 12))
326
327  on('session.start', async ($, e, next) => {
328    await $.command.register({ name: 'images', description: 'このセッションの画像をプレビューペインに表示する' })
329    const sessionId = await $.session.id()
330    await sweepStale($, sessionId)
331    // After a reload this load has made nothing, yet the session's cache may be there already.
332    const base = await existingBase($)
333    const dir = base === undefined ? undefined : await checkedChild($, base, folderName(sessionId))
334    if (dir !== undefined) {
335      cacheDirs.set(sessionId, dir)
336      keepAlive($)
337    }
338    return next(e)
339  })
340
341  on('session.end', async ($, e, next) => {
342    // The session's converted copies go with it; the folder is found from the id and checked first.
343    await removeSessionCache($, e.sessionId)
344    return next(e)
345  })
346
347  on('command.run', { command: 'images' }, async $ => {
348    await $.ui.open({ id: PANE, title: TITLE })
349    return { text: '画像プレビューを開きました。' }
350  })
351
352  on('tool.call', { tool: ['Write', 'Edit', 'Read'] }, async ($, e, next) => {
353    const ran = await next(e)
354    if (ran.deny === undefined && ran.isError !== true && IMAGE_EXT.test(e.file_path)) {
355      const { file_path: path, tool_use_id: id } = e
356      const place = await placeOf($)
357      later($, () => collect($, [[path]], id, undefined, place))
358    }
359    return ran
360  }).catch(($, e, next) => next(e)) // an observer: a failure here never changes the call
361
362  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
363    const startedAt = await $.clock.now()
364    const ran = await next(e)
365    if (ran.deny !== undefined) return ran
366    const output = ran.text ?? (ran.isError === true ? '' : `${ran.result.stdout}\n${ran.result.stderr}`)
367    const groups = findImageCandidates(`${e.command}\n${output}`)
368    if (groups.length > 0) {
369      const id = e.tool_use_id
370      const place = await placeOf($)
371      later($, () => collect($, groups, id, startedAt, place))
372    }
373    return ran
374  }).catch(($, e, next) => next(e))
375
376  on('ui.render', { component: 'ToolUse' }, async ($, e, next) => {
377    if (!isInline) return next(e)
378    const found = await read($, memberOf(byTool, e))
379    if (found.length === 0) return next(e)
380    const row = await next(e)
381    const { Box } = $.ui.resolve(e)
382    const columns = Math.max(8, (e.viewport?.columns ?? 80) - 4)
383    return (
384      <Box flexDirection="column">
385        {row}
386        <Box flexDirection="column" paddingLeft={2}>
387          {found.map(item => thumbnail(e, $, item, columns, inlineRows))}
388        </Box>
389      </Box>
390    )
391  })
392
393  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
394    const { Box, Text, Button } = $.ui.resolve(e)
395    const list = await read($, images)
396    if (list.length === 0) return <Text dimColor>まだ画像はありません。</Text>
397    const at = Math.min(await read($, cursor), list.length - 1)
398    const item = list[at]
399    if (item === undefined) return <Text dimColor>まだ画像はありません。</Text>
400    const columns = Math.max(8, e.props.bodyColumns - 2)
401    // The pane's own room, not the whole screen: a docked pane shares it with tabs and marks.
402    const rows = Math.max(4, e.props.scroll.bodyRows - PANE_CHROME_ROWS)
403    const step = (by: number) => () => update($, cursor, n => Math.min(list.length - 1, Math.max(0, n + by)))
404    return (
405      <Box flexDirection="column">
406        <Box flexDirection="row" gap={2}>
407          <Button key="prev" hotkey="h" label="◀ 新しい" onPress={step(-1)} />
408          <Text dimColor>
409            {at + 1} / {list.length}
410          </Text>
411          <Button key="next" hotkey="l" label="古い ▶" onPress={step(1)} />
412        </Box>
413        {thumbnail(e, $, item, columns, rows)}
414        <Text dimColor wrap="truncate-start">
415          {item.path}
416        </Text>
417      </Box>
418    )
419  })
420}
421

1// Pure helpers: finding image paths in text, sizing a thumbnail in cells, captions.
2
3export const IMAGE_EXT = /\.(png|jpe?g|webp|gif)$/i
4
5// A quoted path may hold spaces: "…", '…' or `…`.
6const QUOTED = /(["'`])([^"'`\n]*?\.(?:png|jpe?g|webp|gif))\1/gi
7// A bare path holds none, and may end a sentence: `out/cat.png.`, `out/cat.png。`, `(out/cat.png)`.
8// It lies inside one word: a run of characters a bare path may hold.
9const WORD = /[^\s'"`()<>|;,\[\]「」『』。、：]+/g
10const EXTENSION_AT = /\.(?:png|jpe?g|webp|gif)/gi
11// What may follow a bare path's extension, and what may stand before the word it starts.
12const AFTER = /[\s'"`),;:：\].。、」』!?！？]/
13const BEFORE = /[\s(,\[「『]/
14// A path that starts inside a word starts after one of these: `--out=a.png`, `x:/b.png`.
15const INNER_START = /[=:]/g
16// The token before a bare match, when it may be the head of a path split at a
17// space (`/tmp/a` before `b/x.jpg`): a path start, no file extension of its own.
18const PATH_START = /^(?:~|\.{1,2})?\//
19const NOT_TOKEN = /[\s'"`]/
20const HAS_EXTENSION = /\.\w{1,5}$/
21// Punctuation that ends a list item or a clause: `a.png, b.png` is two paths, never one.
22const SEPARATOR_END = /[,;:)\]]$/
23// How far back a split path is followed: a long argument list (`ls /a /b … /x.png`) is
24// not offered as one path per argument, nor one longer than a path can be.
25const MAX_PIECES = 8
26const MAX_PATH = 4096
27// Paths read from one text: a call shows its first few images, so a listing of thousands
28// (an echoed glob, `find -name '*.png'`) is read no further than its first ones.
29const MAX_GROUPS = 64
30
31const isUrl = (path: string) => /^[a-z]+:\/\//i.test(path)
32
33/**
34 * The bare image path in one word, at most one: from the word's first place a path may start
35 * to its last image extension that ends a path. As the regex it replaces read it, and linear.
36 */
37function pathInWord(text: string, from: number, word: string): { at: number; path: string } | undefined {
38  let end = -1
39  let extensionAt = -1
40  for (const match of word.matchAll(EXTENSION_AT)) {
41    const after = from + match.index + match[0].length
42    if (after === text.length || AFTER.test(text.charAt(after))) {
43      end = after
44      extensionAt = from + match.index
45    }
46  }
47  if (end < 0) return undefined
48  let at = from === 0 || BEFORE.test(text.charAt(from - 1)) ? from : -1
49  if (at < 0) {
50    INNER_START.lastIndex = 0
51    const inner = INNER_START.exec(word)
52    if (inner !== null) at = from + inner.index + 1
53  }
54  if (at < 0 || at > extensionAt) return undefined
55  return { at, path: text.slice(at, end) }
56}
57
58/** The token that ends one space before `end`, when one may head a split path. */
59function headBefore(text: string, end: number): string | undefined {
60  if (text.charAt(end - 1) !== ' ') return undefined
61  let from = end - 1
62  while (from > 0 && !NOT_TOKEN.test(text.charAt(from - 1)) && end - from <= MAX_PATH) from -= 1
63  if (from > 0 && !/\s/.test(text.charAt(from - 1))) return undefined
64  const piece = text.slice(from, end - 1)
65  return PATH_START.test(piece) ? piece : undefined
66}
67
68/**
69 * Image-looking paths in a command or its output, in order, each as its candidates,
70 * longest first. Text alone cannot tell `/tmp/a b/x.jpg` (one path with a space) from
71 * `convert /tmp/a /tmp/b.png` (two arguments): each joined reading is offered with the
72 * plain tail last, and the one that exists on disk is the path. Linear in the text: it
73 * runs on every Bash result before the result goes back. The first MAX_GROUPS paths only.
74 */
75export function findImageCandidates(text: string): string[][] {
76  const found: { at: number; candidates: string[] }[] = []
77  // Distinct paths read so far, URLs aside: what the cap counts, so repeats never use it up.
78  const quoted = new Set<string>()
79  const tails = new Set<string>()
80  for (const match of text.matchAll(QUOTED)) {
81    if (match[2] === undefined) continue
82    found.push({ at: match.index, candidates: [match[2]] })
83    if (!isUrl(match[2])) quoted.add(match[2])
84    if (quoted.size >= MAX_GROUPS) break
85  }
86  // Quoted spans are blanked out, so a space inside one is never read as a split.
87  const bare = text.replace(QUOTED, span => ' '.repeat(span.length))
88  for (const word of bare.matchAll(WORD)) {
89    if (tails.size >= MAX_GROUPS) break
90    const one = pathInWord(bare, word.index, word[0])
91    if (one === undefined) continue
92    let start = one.at
93    const candidates = [one.path]
94    let path = one.path
95    for (let head = headBefore(bare, start); head !== undefined && candidates.length <= MAX_PIECES; head = headBefore(bare, start)) {
96      if (SEPARATOR_END.test(head) || HAS_EXTENSION.test(head) || path.length + head.length + 1 > MAX_PATH) break
97      path = `${head} ${path}`
98      start -= head.length + 1
99      candidates.unshift(path)
100    }
101    found.push({ at: start, candidates })
102    if (!isUrl(one.path)) tails.add(one.path)
103  }
104  const seen = new Set<string>()
105  const groups: string[][] = []
106  for (const one of found.sort((a, b) => a.at - b.at)) {
107    const fresh = one.candidates.filter(path => !isUrl(path) && !seen.has(path))
108    if (fresh.length === 0) continue
109    for (const path of fresh) seen.add(path)
110    groups.push(fresh)
111    if (groups.length >= MAX_GROUPS) break
112  }
113  return groups
114}
115
116/** An absolute path for `path`, `~` expanded, relative ones against `cwd`; `..` and `.` folded. */
117export function absolutize(path: string, cwd: string, home: string | undefined): string | undefined {
118  let full = path
119  if (full === '~' || full.startsWith('~/')) {
120    if (home === undefined) return undefined
121    full = home + full.slice(1)
122  } else if (!full.startsWith('/')) {
123    full = `${cwd.replace(/\/$/, '')}/${full}`
124  }
125  const parts: string[] = []
126  for (const part of full.split('/')) {
127    if (part === '' || part === '.') continue
128    if (part === '..') parts.pop()
129    else parts.push(part)
130  }
131  return `/${parts.join('/')}`
132}
133
134export function baseName(path: string): string {
135  return path.slice(path.lastIndexOf('/') + 1)
136}
137
138export function isPng(path: string): boolean {
139  return /\.png$/i.test(path)
140}
141
142export function formatSize(bytes: number): string {
143  if (bytes < 1024) return `${bytes} B`
144  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
145  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
146}
147
148/** Width and height from the first bytes of a PNG (signature + IHDR), base64. */
149export function pngDimensions(headBase64: string): { width: number; height: number } | undefined {
150  let bytes: string
151  try {
152    bytes = atob(headBase64.slice(0, 32))
153  } catch {
154    return undefined
155  }
156  if (bytes.length < 24 || bytes.slice(1, 4) !== 'PNG' || bytes.slice(12, 16) !== 'IHDR') return undefined
157  const u32 = (at: number) =>
158    ((bytes.charCodeAt(at) << 24) | (bytes.charCodeAt(at + 1) << 16) | (bytes.charCodeAt(at + 2) << 8) | bytes.charCodeAt(at + 3)) >>> 0
159  const width = u32(16)
160  const height = u32(20)
161  return width > 0 && height > 0 ? { width, height } : undefined
162}
163
164/** `pixelWidth: 640` / `pixelHeight: 480` lines of `sips -g`. */
165export function sipsDimensions(stdout: string): { width: number; height: number } | undefined {
166  const width = Number(/pixelWidth:\s*(\d+)/.exec(stdout)?.[1])
167  const height = Number(/pixelHeight:\s*(\d+)/.exec(stdout)?.[1])
168  return width > 0 && height > 0 ? { width, height } : undefined
169}
170
171const clamp = (n: number, low: number, high: number) => Math.min(high, Math.max(low, Math.round(n)))
172
173/**
174 * The cell box a picture keeps its shape in: a terminal cell is about twice as
175 * tall as it is wide, and the Image element stretches to fill its box.
176 */
177export function cellBox(
178  size: { width?: number; height?: number },
179  maxColumns: number,
180  maxRows: number,
181): { columns: number; rows: number } {
182  const columnsCap = clamp(maxColumns, 1, 255)
183  const rowsCap = clamp(maxRows, 1, 255)
184  if (size.width === undefined || size.height === undefined) {
185    return { columns: Math.min(columnsCap, rowsCap * 2), rows: rowsCap }
186  }
187  const ratio = size.width / size.height
188  const columns = rowsCap * 2 * ratio
189  if (columns <= columnsCap) return { columns: clamp(columns, 1, 255), rows: rowsCap }
190  return { columns: columnsCap, rows: clamp(columnsCap / (2 * ratio), 1, 255) }
191}
192
193export function caption(item: { name: string; size: number; width?: number; height?: number }): string {
194  const dims = item.width !== undefined && item.height !== undefined ? ` · ${item.width}×${item.height}` : ''
195  return `${item.name} · ${formatSize(item.size)}${dims}`
196}
197

1export type ImageItem = {
2  /** `path:mtimeMs`: one per version of a file. */
3  id: string
4  /** Absolute path of the image as the session named it. */
5  path: string
6  name: string
7  size: number
8  mtimeMs: number
9  width?: number
10  height?: number
11  /** Absolute path of a PNG the terminal can draw: the file itself, or a converted copy. */
12  png?: string
13  /** Why no thumbnail is drawn, when none is. */
14  skipped?: string
15  /** The tool call that wrote, read or produced it. */
16  toolUseId: string
17}
18
19/** A PNG this plugin converted into the session's cache, and the rows that draw it. */
20export type ConvertedFile = { png: string; toolUseIds: string[] }
21
22declare module 'claude-code' {
23  interface PluginState {
24    'image-preview': {
25      /** Newest first. */
26      images: ImageItem[]
27      /** Index into `images` the pane shows. */
28      cursor: number
29      /** The images each ToolUse row draws, keyed by tool_use_id. */
30      byTool: StateFamily<ImageItem[]>
31      /** Converted copies in the session's cache, oldest first: what a prune may remove, and whose rows to tell. */
32      converted: ConvertedFile[]
33    }
34  }
35}
36