landmarks-widget

1import { atom, read, update } from 'claude-code'
2import type { Elements, EngineInterface, PluginState, Register, RenderElement, RenderNode, RenderSurface, ToolCallInput, ToolCallResult } from 'claude-code'
3import type { WidgetsPlace } from 'widgets'
4
5import { fit, folder, plural } from './lib'
6
7type Tags = Pick<Elements[RenderSurface], 'Box' | 'Text' | 'Button'>
8type Trail = PluginState['landmarks-widget']['trail']
9type Mark = Trail['marks'][number]
10
11const PANE = 'widgets'
12const CARD_COLUMNS = 40
13const CARD_FRAME = 4
14const WIDE_COLUMNS = 30
15const MAX_MARKS = 200
16const MAX_ROWS = 8
17const FOLDED_ROWS = 7
18const MAX_LABEL = 48
19const USAGE = 'Usage: /landmarks-widget [on|off|list|go <n>|clear]'
20const VERBS = ['', 'on', 'off', 'list', 'clear']
21const EMPTY = 'No landmarks yet. Prompts, first edits, red and green checks, commits and questions are listed here; press one to jump to it.'
22const NEEDS = ['Jumping needs the fullscreen layout', 'Needs fullscreen'] as const
23const HINTS = ['Press a line or go <n>', 'go <n> jumps'] as const
24const CHECKS = /\b(test|tests|pytest|jest|vitest|tsc|lint|eslint|build|check|clippy)\b/
25const COMMIT = /\bgit\b(?:\s+-\S+(?:\s+[^-\s]\S*)?)*\s+commit(?=\s|$)/
26const SUBJECT = /^\[.+ [0-9a-f]{4,40}\] (.*)$/m
27const WHOLE = /^0*([1-9]\d*)$/
28const WIDE = /[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦\u{1f300}-\u{1faff}\u{20000}-\u{3fffd}]/u
29const REST: Trail = { marks: [], edited: [], mood: 'none', turn: 0, last: 0, waiting: 0, said: '' }
30const site = { plugin: 'widgets', key: 'site' } as const
31const widths = { plugin: 'widgets', key: 'widths' } as const
32const isOn = atom({ plugin: 'landmarks-widget', key: 'isOn' } as const, false)
33const spot = { plugin: 'landmarks-widget', key: 'trail' } as const
34const trail = atom(spot, REST)
35
36const cells = (text: string): number => [...text].reduce((sum, letter) => sum + (WIDE.test(letter) ? 2 : 1), 0)
37
38const cut = (text: string, room: number): string => {
39  if (cells(text) <= room) return text
40
41  const letters = [...text]
42  while (letters.length > 0 && cells(letters.join('')) > room - 1) letters.pop()
43
44  return `${letters.join('')}…`
45}
46
47const labelled = (text: string): string => {
48  const letters = [...text.replace(/\s+/g, ' ').trim()]
49
50  return letters.length > MAX_LABEL ? `${letters.slice(0, MAX_LABEL - 1).join('')}…` : letters.join('')
51}
52
53const line = (mark: Mark): string => (mark.label === '' ? mark.kind : `${mark.kind}: ${mark.label}`)
54
55const listed = (mark: Mark): string =>
56  `${mark.id}  t${mark.turn}  ${line(mark)}${mark.isNear ? ' (near)' : ''}${mark.row === '' ? ' (no row)' : ''}${mark.isGone ? ' (gone)' : ''}`
57
58const added = (held: Trail, kind: Mark['kind'], label: string, row: string): Trail => ({
59  ...held,
60  last: held.last + 1,
61  marks: [...held.marks, { id: held.last + 1, turn: held.turn, kind, label: labelled(label), row, isNear: false, isGone: false }].slice(-MAX_MARKS),
62})
63
64const begun = (held: Trail, text: string): Trail => {
65  const turned = { ...held, turn: held.turn + 1, waiting: 0 }
66  const first = text.split('\n').find(part => part.trim() !== '')
67  if (first === undefined) return turned
68
69  return { ...added(turned, 'you', first, ''), waiting: turned.last + 1 }
70}
71
72const anchored = (held: Trail, row: string): Trail =>
73  held.waiting === 0 || row === ''
74    ? held
75    : { ...held, waiting: 0, marks: held.marks.map(mark => (mark.id === held.waiting ? { ...mark, row, isNear: true } : mark)) }
76
77const edited = (held: Trail, path: string, row: string): Trail => {
78  const key = folder(path)
79  if (held.edited.includes(key)) return held
80
81  return { ...added(held, 'edit', path.split(/[\\/]/).pop() ?? '', row), edited: [...held.edited, key] }
82}
83
84const checked = (held: Trail, first: string, isFailed: boolean, row: string): Trail => {
85  const mood = isFailed ? 'red' : 'green'
86  if (isFailed === (held.mood === 'red')) return held.mood === mood ? held : { ...held, mood }
87
88  return { ...added(held, mood, first, row), mood }
89}
90
91const shelled = (held: Trail, command: string, ran: ToolCallResult, row: string): Trail => {
92  const first = command.split('\n')[0] ?? ''
93  const isFailed = ran.isError === true
94  const tried = CHECKS.test(first) ? checked(held, first, isFailed, row) : held
95  if (isFailed || !COMMIT.test(first)) return tried
96
97  const stdout = (ran.result as { stdout?: unknown } | undefined)?.stdout
98
99  return added(tried, 'commit', typeof stdout === 'string' ? (SUBJECT.exec(stdout)?.[1] ?? '') : '', row)
100}
101
102const noted = (held: Trail, e: ToolCallInput, ran: ToolCallResult): Trail => {
103  const row = e.tool_use_id ?? ''
104  const based = anchored(held, row)
105  if (e.tool === 'Edit' || e.tool === 'Write') return ran.isError === true ? based : edited(based, e.file_path, row)
106  if (e.tool === 'Bash') return shelled(based, e.command, ran, row)
107  if (e.tool === 'AskUserQuestion') return added(based, 'asked', e.questions[0]?.question ?? '', row)
108
109  return based
110}
111
112const picked = (marks: readonly Mark[]): readonly Mark[] => {
113  if (marks.length <= MAX_ROWS) return marks
114
115  const others = marks.filter(mark => mark.kind !== 'you').slice(-FOLDED_ROWS)
116  const prompts = others.length < FOLDED_ROWS ? marks.filter(mark => mark.kind === 'you').slice(others.length - FOLDED_ROWS) : []
117
118  return [...others, ...prompts].sort((one, other) => one.id - other.id)
119}
120
121const seat = (node: RenderNode, seats: Readonly<Record<string, RenderElement>>): RenderNode => {
122  if (typeof node !== 'object') return node
123  const { props, children } = node as { props?: { key?: unknown }; children?: RenderNode[] }
124  const seated = typeof props?.key === 'string' ? seats[props.key] : undefined
125  if (seated !== undefined) return seated
126
127  return children === undefined ? node : ({ ...node, children: children.map(child => seat(child, seats)) } as RenderElement)
128}
129
130const jump = async ($: EngineInterface, wanted: string, isFullscreen: boolean | undefined): Promise<string> => {
131  const { marks } = await read($, trail)
132  const mark = marks.find(held => held.id === Number(wanted))
133  if (mark === undefined) return marks.length === 0 ? 'No landmarks yet.' : `No landmark ${wanted}. The list holds ${marks[0]?.id} to ${marks.at(-1)?.id}.`
134  if (mark.row === '') return `Landmark ${mark.id} has no row: its turn made no tool call.`
135
136  let deny: string | undefined
137  try {
138    deny = (await $.ui.scroll({ to: { requestId: mark.row }, block: 'start' })).deny
139  } catch (error) {
140    deny = error instanceof Error ? error.message : String(error)
141  }
142
143  const isLayout = deny !== undefined && isFullscreen === false
144  const said =
145    deny === undefined
146      ? `At ${mark.id}: ${line(mark)}${mark.isNear ? ' (nearest row)' : ''}`
147      : isLayout
148        ? `Jumping needs the fullscreen layout (${deny}).`
149        : `${mark.id} did not move: ${deny}`
150  await update($, trail, held => ({
151    ...(held ?? REST),
152    said,
153    marks: isLayout ? (held ?? REST).marks : (held ?? REST).marks.map(kept => (kept.id === mark.id ? { ...kept, isGone: deny !== undefined } : kept)),
154  }))
155
156  return said
157}
158
159const show = async (
160  $: EngineInterface,
161  { Box, Text, Button }: Tags,
162  beneath: RenderElement,
163  place: WidgetsPlace,
164  columns: number,
165  isFullscreen: boolean | undefined,
166): Promise<RenderElement> => {
167  if (!(await read($, isOn))) return beneath
168  if ((await $.state.get(site)).value !== place) return beneath
169
170  const width = fit((await $.state.get(widths)).value?.['landmarks-widget'] ?? CARD_COLUMNS, columns)
171  const inner = width - CARD_FRAME
172  const isWide = width >= WIDE_COLUMNS
173  const { marks, said } = await read($, trail)
174  if (marks.length === 0) return $.widgets.card({ beneath, width, title: 'Landmarks', body: <Text dimColor>{EMPTY}</Text> })
175
176  const shown = picked(marks)
177  const folded = marks.length - shown.length
178  const pad = String(shown.at(-1)?.id ?? 0).length
179  const foot = isFullscreen === false ? NEEDS[isWide ? 0 : 1] : said === '' ? HINTS[isWide ? 0 : 1] : said
180
181  const rows = shown.map(mark => {
182    const fact = !isWide ? '' : mark.isGone ? 'gone' : mark.isNear ? 'near' : ''
183    const label = cut(`${String(mark.id).padStart(pad)} ${isWide ? `t${mark.turn} ` : ''}${line(mark)}`, inner - (fact === '' ? 0 : fact.length + 1))
184
185    return { mark, fact, label }
186  })
187
188  const card = await $.widgets.card({
189    beneath,
190    width,
191    title: 'Landmarks',
192    note: isWide ? plural(marks.length, 'landmark') : String(marks.length),
193    body: (
194      <Box flexDirection="column">
195        {folded > 0 && (
196          <Box key="more">
197            <Text dimColor wrap="truncate-end">
198              {cut(isWide ? `… ${folded} more in /landmarks-widget list` : `… ${folded} more`, inner)}
199            </Text>
200          </Box>
201        )}
202        {rows.map(({ mark, fact, label }) => (
203          <Box key={`row:${mark.id}`} justifyContent="space-between">
204            {mark.row === '' ? (
205              <Text dimColor wrap="truncate-end">
206                {label}
207              </Text>
208            ) : (
209              <Box key={`seat:${mark.id}`} />
210            )}
211            {fact !== '' && <Text dimColor>{fact}</Text>}
212          </Box>
213        ))}
214        <Box key="foot">
215          <Text dimColor wrap="truncate-end">
216            {cut(foot, inner)}
217          </Text>
218        </Box>
219      </Box>
220    ),
221  })
222
223  return seat(
224    card,
225    Object.fromEntries(
226      rows.map(({ mark, label }) => [
227        `seat:${mark.id}`,
228        <Button plain key={`go:${mark.id}`} label={label} dimColor={mark.isGone} onPress={() => jump($, String(mark.id), isFullscreen)} />,
229      ]),
230    ),
231  ) as RenderElement
232}
233
234export const register: Register = on => {
235  on('session.start', async ($, e, next) => {
236    await $.command.register({
237      name: 'landmarks-widget',
238      description: 'Toggle the Landmarks card, list its landmarks or jump to one',
239      argumentHint: '[on|off|list|go <n>|clear]',
240    })
241    if ((await $.store.get('isOn')) === true) await update($, isOn, () => true)
242
243    return next(e)
244  })
245
246  on('command.run', { command: 'landmarks-widget' }, async ($, e) => {
247    const [verb = '', ...rest] = e.args.trim().split(/\s+/)
248    const arg = verb.toLowerCase()
249    const wanted = arg === 'go' && rest.length === 1 ? (WHOLE.exec(rest[0] ?? '')?.[1] ?? '') : ''
250    if (arg === 'go' ? wanted === '' : rest.length > 0 || !VERBS.includes(arg)) return { text: USAGE }
251
252    if (arg === 'list' || arg === 'go' || arg === 'clear') {
253      if (!(await read($, isOn))) return { text: 'Landmarks is off.' }
254      if (arg === 'go') return { text: await jump($, wanted, e.presentation.isFullscreen) }
255      if (arg === 'clear') {
256        await update($, trail, held => ({ ...REST, turn: (held ?? REST).turn }))
257
258        return { text: 'Landmarks cleared.' }
259      }
260
261      const { marks } = await read($, trail)
262
263      return { text: marks.length === 0 ? 'No landmarks yet.' : marks.map(listed).join('\n') }
264    }
265
266    const isShown = await update($, isOn, shown => (arg === '' ? !(shown ?? false) : arg === 'on'))
267    await $.store.set('isOn', isShown)
268    if (!isShown) await update($, trail, () => REST)
269
270    return { text: isShown ? 'Landmarks on; /widgets places it.' : 'Landmarks off.' }
271  })
272
273  on('turn.start', async ($, e, next) => {
274    if (!(await read($, isOn))) return next(e)
275
276    await update($, trail, held => begun(held ?? REST, e.text))
277
278    return next(e)
279  })
280
281  on('tool.call', async ($, e, next) => {
282    if (e.agentId !== undefined || !(await read($, isOn))) return next(e)
283
284    const ran = await next(e)
285    try {
286      if (ran.deny === undefined) {
287        const { value: seen = REST, version } = await $.state.get(spot)
288        const made = noted(seen, e, ran)
289        if (made !== seen && !(await $.state.set(spot, made, { ifVersion: version })).isSet) await update($, trail, held => noted(held ?? REST, e, ran))
290      }
291    } catch {
292      // A landmark that cannot be read from the call must not cost Claude the result it was given.
293    }
294
295    return ran
296  })
297
298  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e, next) =>
299    show($, $.ui.resolve(e), await next(e), 'side', e.props.bodyColumns, e.viewport?.isFullscreen),
300  )
301
302  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) =>
303    e.props.hasSurvey ? next(e) : show($, $.ui.resolve(e), await next(e), 'above', e.props.bodyColumns, e.viewport?.isFullscreen),
304  )
305
306  on('ui.render', { component: 'PromptHint' }, async ($, e, next) =>
307    show($, $.ui.resolve(e), await next(e), 'below', e.viewport?.columns ?? 80, e.viewport?.isFullscreen),
308  )
309}
310

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 LandmarksSwitch = boolean
2
3declare module 'claude-code' {
4  interface PluginState {
5    'landmarks-widget': {
6      isOn: LandmarksSwitch
7      trail: {
8        marks: {
9          id: number
10          turn: number
11          kind: 'you' | 'edit' | 'red' | 'green' | 'commit' | 'asked'
12          label: string
13          row: string
14          isNear: boolean
15          isGone: boolean
16        }[]
17        edited: string[]
18        mood: 'none' | 'red' | 'green'
19        turn: number
20        last: number
21        waiting: number
22        said: string
23      }
24    }
25  }
26}
27