pen-widget

1import { atom, read, update } from 'claude-code'
2import type { Elements, EngineInterface, PluginState, Register, RenderElement, RenderSurface, TurnStepChunk, TurnStepToolChunk } from 'claude-code'
3import type { WidgetsPlace } from 'widgets'
4
5import { fit, plural } from './lib'
6
7type Tags = Pick<Elements[RenderSurface], 'Box' | 'Text'>
8type Held = PluginState['pen-widget']['pen']
9type Call = NonNullable<Held>
10type Fields = { path: string; text: string }
11type Reader = {
12  id: string
13  tool: string
14  index: number
15  fields: Fields
16  phase: Call['phase']
17  depth: number
18  isInString: boolean
19  isKey: boolean
20  isKeyNext: boolean
21  key: string
22  field: 'path' | 'text' | ''
23  escape: string
24  high: string
25  path: string
26  newlines: number
27  chars: number
28  pieces: number
29  done: string[]
30  line: string
31  room: number
32  isInked: boolean
33  hasLetter: boolean
34}
35type Desk = { isReading: boolean; copiedAt: number; flips: number; version: number; reader?: Reader }
36
37const PANE = 'widgets'
38const CARD_COLUMNS = 40
39const HEAD_COLUMNS = 30
40const TAIL_ROWS = 5
41const LINE_LETTERS = 120
42const PATH_LETTERS = 200
43const KEY_LETTERS = 32
44const COPY_MS = 100
45const COPY_TRIES = 3
46const CURSOR = '▌'
47const USAGE = 'Usage: /pen-widget [on|off|show|clear]'
48const OFF = 'Pen is off.'
49const NOTHING = 'Nothing written yet.'
50const EMPTY = `${NOTHING} A file, edit or command shows here line by line while Claude is still writing it, before it runs.`
51const STOPPED = 'Stopped before it ran.'
52const STOPPED_SHORT = 'Stopped.'
53const PHASES = { writing: 'writing', written: 'written', stopped: 'stopped before it ran' } as const
54const FIELDS = new Map<string, Fields>([
55  ['Write', { path: 'file_path', text: 'content' }],
56  ['Edit', { path: 'file_path', text: 'new_string' }],
57  ['NotebookEdit', { path: 'notebook_path', text: 'new_source' }],
58  ['Bash', { path: '', text: 'command' }],
59  ['PowerShell', { path: '', text: 'command' }],
60])
61const ESCAPES: Readonly<Record<string, string>> = { n: '\n', r: '\r', t: '\t', b: '\b', f: '\f' }
62const CONTROL = /[\u0000-\u001f\u007f-\u009f]/
63const WIDE =
64  /[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹯＀-｠￠-￦\u{1f300}-\u{1faff}\u{20000}-\u{3fffd}]/u
65const site = { plugin: 'widgets', key: 'site' } as const
66const widths = { plugin: 'widgets', key: 'widths' } as const
67const switched = { plugin: 'pen-widget', key: 'isOn' } as const
68const penned = { plugin: 'pen-widget', key: 'pen' } as const
69const isOn = atom({ plugin: 'pen-widget', key: 'isOn' } as const, false)
70const pen = atom({ plugin: 'pen-widget', key: 'pen' } as const, null as Held)
71
72const fresh = (chunk: TurnStepToolChunk, fields: Fields): Reader => ({
73  id: chunk.id,
74  tool: chunk.name,
75  index: chunk.index,
76  fields,
77  phase: 'writing',
78  depth: 0,
79  isInString: false,
80  isKey: false,
81  isKeyNext: false,
82  key: '',
83  field: '',
84  escape: '',
85  high: '',
86  path: '',
87  newlines: 0,
88  chars: 0,
89  pieces: 0,
90  done: [],
91  line: '',
92  room: LINE_LETTERS,
93  isInked: false,
94  hasLetter: false,
95})
96
97const inked = (reader: Reader, letter: string): void => {
98  reader.chars += 1
99  if (letter === '\n') {
100    if (reader.isInked) reader.done = [...reader.done, reader.line].slice(-TAIL_ROWS)
101    reader.newlines += 1
102    reader.line = ''
103    reader.room = LINE_LETTERS
104    reader.isInked = false
105    reader.hasLetter = false
106
107    return
108  }
109  if (letter !== '\t' && CONTROL.test(letter)) return
110
111  reader.hasLetter = true
112  if (reader.room === 0) return
113
114  const kept = letter === '\t' ? '  '.slice(0, reader.room) : letter
115  reader.line += kept
116  reader.room -= letter === '\t' ? kept.length : 1
117  if (kept.trim() !== '') reader.isInked = true
118}
119
120const handed = (reader: Reader, unit: string): void => {
121  const code = unit.charCodeAt(0)
122  if (code >= 0xd800 && code <= 0xdbff) {
123    reader.high = unit
124
125    return
126  }
127
128  const isLow = code >= 0xdc00 && code <= 0xdfff
129  const letter = isLow && reader.high !== '' ? reader.high + unit : unit
130  reader.high = ''
131  if (isLow && letter === unit) return
132
133  if (reader.isKey) {
134    if (reader.key.length < KEY_LETTERS) reader.key += letter
135  } else if (reader.field === 'text') {
136    inked(reader, letter)
137  } else if (reader.field === 'path' && !CONTROL.test(letter)) {
138    reader.path = (reader.path + letter).slice(-PATH_LETTERS)
139  }
140}
141
142const lettered = (reader: Reader, letter: string): void => {
143  if (reader.escape === '\\') {
144    reader.escape = letter === 'u' ? '\\u' : ''
145    if (letter !== 'u') handed(reader, ESCAPES[letter] ?? letter)
146  } else if (reader.escape !== '') {
147    reader.escape += letter
148    if (reader.escape.length < 6) return
149
150    const code = Number.parseInt(reader.escape.slice(2), 16)
151    reader.escape = ''
152    if (!Number.isNaN(code)) handed(reader, String.fromCharCode(code))
153  } else if (letter === '\\') {
154    reader.escape = letter
155  } else if (letter === '"') {
156    reader.isInString = false
157    reader.high = ''
158  } else {
159    handed(reader, letter)
160  }
161}
162
163const marked = (reader: Reader, letter: string): void => {
164  if (letter === '"') {
165    reader.isInString = true
166    reader.isKey = reader.depth === 1 && reader.isKeyNext
167    reader.field = reader.isKey || reader.depth !== 1 || reader.key === '' ? '' : reader.key === reader.fields.path ? 'path' : reader.key === reader.fields.text ? 'text' : ''
168    if (reader.isKey) reader.key = ''
169  } else if (letter === '{' || letter === '[') {
170    reader.depth += 1
171    if (reader.depth === 1) reader.isKeyNext = true
172  } else if (letter === '}' || letter === ']') {
173    if (reader.depth === 0) return
174
175    reader.depth -= 1
176    if (reader.depth === 0) reader.phase = 'written'
177  } else if (reader.depth === 1 && letter === ':') {
178    reader.isKeyNext = false
179  } else if (reader.depth === 1 && letter === ',') {
180    reader.isKeyNext = true
181    reader.key = ''
182  }
183}
184
185const fed = (reader: Reader, json: string): void => {
186  reader.pieces += 1
187  for (let at = 0; at < json.length && reader.phase === 'writing'; at += 1) {
188    if (reader.isInString) lettered(reader, json.charAt(at))
189    else marked(reader, json.charAt(at))
190  }
191}
192
193const picture = (reader: Reader): Call => ({
194  id: reader.id,
195  tool: reader.tool,
196  path: reader.path,
197  phase: reader.phase,
198  lines: reader.newlines + (reader.hasLetter ? 1 : 0),
199  chars: reader.chars,
200  pieces: reader.pieces,
201  tail: (reader.isInked ? [...reader.done, reader.line] : reader.done).slice(-TAIL_ROWS),
202})
203
204const fitting = (letters: readonly string[], room: number): number => {
205  let cells = 0
206  let count = 0
207  for (const letter of letters) {
208    cells += WIDE.test(letter) ? 2 : 1
209    if (cells > room) break
210    count += 1
211  }
212
213  return count
214}
215
216const cut = (text: string, room: number): string => {
217  const letters = [...text]
218
219  return fitting(letters, room) === letters.length ? text : `${letters.slice(0, fitting(letters, room - 1)).join('')}…`
220}
221
222const cutStart = (text: string, room: number): string => {
223  const letters = [...text].reverse()
224
225  return fitting(letters, room) === letters.length ? text : `…${letters.slice(0, fitting(letters, room - 1)).reverse().join('')}`
226}
227
228const wrapped = (sentence: string, columns: number): string[] =>
229  sentence.split(' ').reduce<string[]>((rows, word) => {
230    const held = rows.at(-1)
231
232    return held !== undefined && held.length + 1 + word.length <= columns ? [...rows.slice(0, -1), `${held} ${word}`] : [...rows, word]
233  }, [])
234
235const brief = (path: string, room: number): string => {
236  const kept = cutStart(path, room)
237  const at = kept.search(/[\\/]/)
238
239  return kept === path || at < 0 ? kept : `…${kept.slice(at)}`
240}
241
242const heading = (held: Call, width: number): string => {
243  const inner = width - 4
244  if (held.path === '') return cut(held.tool, inner)
245  if (width < HEAD_COLUMNS) return brief(held.path, inner)
246
247  return `${held.tool} ${brief(held.path, inner - held.tool.length - 1)}`
248}
249
250const trailing = (held: Call, inner: number): string[] => {
251  const indent = Math.max(0, Math.min(...held.tail.map(row => row.search(/[^ ]/))))
252  const rows = held.tail.map(row => row.slice(indent))
253  if (held.phase !== 'writing') return rows.map(row => cut(row, inner))
254
255  return [...rows.slice(0, -1).map(row => cut(row, inner)), `${cut(rows.at(-1) ?? '', inner - 1)}${CURSOR}`]
256}
257
258const facts = (held: Held): string =>
259  held === null
260    ? NOTHING
261    : `${held.tool}${held.path === '' ? '' : ` ${held.path}`}: ${plural(held.lines, 'line')}, ${plural(held.chars, 'character')} in ${plural(held.pieces, 'piece')}, ${PHASES[held.phase]}.`
262
263const copied = async ($: EngineInterface, desk: Desk, isFresh: boolean): Promise<void> => {
264  const { reader } = desk
265  if (reader === undefined) return
266
267  let flipped = await $.state.get(switched)
268  let held = await $.state.get(penned)
269  let version = isFresh ? held.version : desk.version
270  for (let tries = 0; tries < COPY_TRIES; tries += 1) {
271    if (flipped.value !== true || flipped.version !== desk.flips || (!isFresh && held.value != null && held.value.id !== reader.id)) break
272
273    const landed = await $.state.set(penned, picture(reader), { ifVersion: version })
274    if (landed.isSet) {
275      desk.version = landed.version
276
277      return
278    }
279
280    // Every get of one dispatch reads one moment, so a switch-off made since shows only after a write has missed.
281    flipped = await $.state.get(switched)
282    held = await $.state.get(penned)
283    version = held.version
284  }
285  desk.reader = undefined
286  desk.isReading = false
287}
288
289const halted = async ($: EngineInterface, desk: Desk): Promise<void> => {
290  if (desk.reader?.phase !== 'writing') return
291
292  desk.reader.phase = 'stopped'
293  await copied($, desk, false)
294}
295
296const reading = async ($: EngineInterface, desk: Desk, chunk: TurnStepChunk): Promise<void> => {
297  if (chunk.kind === 'tool' || chunk.kind === 'text' || chunk.kind === 'thinking') await halted($, desk)
298  if (chunk.kind === 'tool') {
299    const fields = FIELDS.get(chunk.name)
300    if (fields === undefined || !desk.isReading) return
301
302    desk.reader = fresh(chunk, fields)
303    desk.copiedAt = Number.NEGATIVE_INFINITY
304    await copied($, desk, true)
305
306    return
307  }
308
309  const { reader } = desk
310  if (chunk.kind !== 'input' || reader === undefined || reader.phase !== 'writing' || chunk.index !== reader.index) return
311
312  fed(reader, chunk.json)
313  if (reader.phase === 'writing') {
314    const now = await $.clock.now()
315    if (now - desk.copiedAt < COPY_MS) return
316
317    desk.copiedAt = now
318  }
319  await copied($, desk, false)
320}
321
322const guarded = async (desk: Desk, work: () => Promise<void>): Promise<void> => {
323  try {
324    await work()
325  } catch {
326    desk.isReading = false
327  }
328}
329
330const show = async (
331  $: EngineInterface,
332  { Box, Text }: Tags,
333  beneath: RenderElement,
334  place: WidgetsPlace,
335  columns: number,
336): Promise<RenderElement> => {
337  if (!(await read($, isOn))) return beneath
338  if ((await $.state.get(site)).value !== place) return beneath
339
340  const width = fit((await $.state.get(widths)).value?.['pen-widget'] ?? CARD_COLUMNS, columns)
341  const inner = width - 4
342  const held = await read($, pen)
343  const rows = held === null ? wrapped(EMPTY, inner) : [heading(held, width), ...trailing(held, inner)]
344
345  return $.widgets.card({
346    beneath,
347    width,
348    title: 'Pen',
349    note: held === null ? '' : plural(held.lines, 'line'),
350    body: (
351      <Box flexDirection="column">
352        {rows.map(row => (
353          <Text dimColor={held?.phase !== 'writing'} wrap="truncate-end">
354            {row}
355          </Text>
356        ))}
357        {held?.phase === 'stopped' && (
358          <Text key="stopped" color="yellow" wrap="truncate-end">
359            {STOPPED.length <= inner ? STOPPED : STOPPED_SHORT}
360          </Text>
361        )}
362      </Box>
363    ),
364  })
365}
366
367export const register: Register = on => {
368  on('session.start', async ($, e, next) => {
369    await $.command.register({
370      name: 'pen-widget',
371      description: 'Toggle the Pen card, or show and clear the tool call Claude is writing',
372      argumentHint: '[on|off|show|clear]',
373    })
374    if ((await $.store.get('isOn')) === true) await update($, isOn, () => true)
375
376    return next(e)
377  })
378
379  on('command.run', { command: 'pen-widget' }, async ($, e) => {
380    const arg = e.args.trim().toLowerCase()
381    if (arg === 'show' || arg === 'clear') {
382      if (!(await read($, isOn))) return { text: OFF }
383      if (arg === 'show') return { text: facts(await read($, pen)) }
384
385      await update($, pen, () => null)
386
387      return { text: 'Pen cleared.' }
388    }
389    if (arg !== '' && arg !== 'on' && arg !== 'off') return { text: USAGE }
390
391    const isShown = await update($, isOn, shown => (arg === '' ? !(shown ?? false) : arg === 'on'))
392    await $.store.set('isOn', isShown)
393    if (!isShown) await update($, pen, () => null)
394
395    return { text: isShown ? 'Pen on; /widgets places it.' : 'Pen off.' }
396  })
397
398  on('turn.step', async function* ($, e, next) {
399    if (e.agentId !== undefined || !(await read($, isOn))) return yield* next(e)
400
401    const desk: Desk = { isReading: true, copiedAt: Number.NEGATIVE_INFINITY, flips: (await $.state.get(switched)).version, version: 0 }
402    try {
403      for await (const chunk of next(e)) {
404        if (desk.isReading) await guarded(desk, () => reading($, desk, chunk))
405        yield chunk
406      }
407    } finally {
408      await guarded(desk, () => halted($, desk))
409    }
410  })
411
412  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e, next) =>
413    show($, $.ui.resolve(e), await next(e), 'side', e.props.bodyColumns),
414  )
415
416  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) =>
417    e.props.hasSurvey ? next(e) : show($, $.ui.resolve(e), await next(e), 'above', e.props.bodyColumns),
418  )
419
420  on('ui.render', { component: 'PromptHint' }, async ($, e, next) =>
421    show($, $.ui.resolve(e), await next(e), 'below', e.viewport?.columns ?? 80),
422  )
423}
424

1const MIN_CARD = 20
2const BARS = '▁▂▃▄▅▆▇█'
3
4export const fit = (wanted: number, columns: number): number => Math.min(wanted, Math.max(MIN_CARD, columns))
5
6export const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? '' : 's'}`
7
8export const span = (ms: number): string => {
9  const seconds = Math.max(0, Math.round(ms / 1000))
10  if (seconds < 60) return `${seconds}s`
11  const minutes = Math.floor(seconds / 60)
12  if (minutes < 60) return `${minutes}m ${String(seconds % 60).padStart(2, '0')}s`
13  const hours = Math.floor(minutes / 60)
14  if (hours < 24) return `${hours}h ${String(minutes % 60).padStart(2, '0')}m`
15
16  return `${Math.floor(hours / 24)}d ${hours % 24}h`
17}
18
19export const spark = (values: readonly number[], width: number): string => {
20  const shown = width > 0 ? values.slice(-width) : []
21  const top = Math.max(...shown, 0)
22
23  return shown
24    .map(value => (top <= 0 ? BARS[0] : BARS[Math.min(BARS.length - 1, Math.round((Math.max(0, value) / top) * (BARS.length - 1)))]))
25    .join('')
26}
27
28export const hash = (text: string): number => {
29  let held = 2166136261
30  for (const letter of text) held = Math.imul(held ^ (letter.codePointAt(0) ?? 0), 16777619)
31
32  return held >>> 0
33}
34
35export const shade = (color: number, factor: number): number =>
36  (Math.round((color >> 16) * factor) << 16) |
37  (Math.round(((color >> 8) & 255) * factor) << 8) |
38  Math.round((color & 255) * factor)
39
40export const folder = (path: string): string => {
41  const flat = path.replaceAll('\\', '/').replace(/\/+$/, '')
42
43  return /^[a-z]:/i.test(flat) ? flat.toLowerCase() : flat
44}
45

1export type PenSwitch = boolean
2
3declare module 'claude-code' {
4  interface PluginState {
5    'pen-widget': {
6      isOn: PenSwitch
7      pen: {
8        id: string
9        tool: string
10        path: string
11        phase: 'writing' | 'written' | 'stopped'
12        lines: number
13        chars: number
14        pieces: number
15        tail: string[]
16      } | null
17    }
18  }
19}
20