fixkit

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { FixReport, FixStatus, Incoming, Receiver } from '../types'
5import * as fixes from '../core/fixes.mjs'
6import {
7  HOT_RELOAD_TOOL,
8  instructionsFor,
9  isBuildAndRun,
10  pressedLabel,
11  projectKind,
12  promptFor,
13  type ProjectKind,
14} from './prompt'
15
16const PANE = 'fix-queue'
17const TITLE = 'Fix queue'
18const STATUS_FILE = '.fixkit/status.json'
19
20const reports = atom({ plugin: 'fixkit', key: 'reports' } as const, [])
21const receiver = atom({ plugin: 'fixkit', key: 'receiver' } as const, {
22  state: 'starting',
23  detail: '',
24})
25const now = atom({ plugin: 'fixkit', key: 'now' } as const, 0)
26
27type ReceiverEvent =
28  | { type: 'ready'; port: number }
29  | { type: 'error'; message: string }
30  | { type: 'notice'; message: string }
31  | { type: 'launched' }
32  | { type: 'report'; report: Incoming }
33
34const LOOK: Record<FixStatus, { mark: string; label: string; color: string }> = {
35  queued: { mark: '○', label: 'queued', color: 'yellow' },
36  fixing: { mark: '◆', label: 'fixing', color: 'cyan' },
37  rebuilding: { mark: '▲', label: 'rebuilding', color: 'magenta' },
38  live: { mark: '✔', label: 'live', color: 'green' },
39  stopped: { mark: '✘', label: 'not rebuilt', color: 'red' },
40}
41
42// In a React Native or Flutter project a fix goes live through a reload, not a rebuild.
43const RELOAD_LOOK: typeof LOOK = { ...LOOK, stopped: { ...LOOK.stopped, label: 'not applied' } }
44
45const isActive = (report: FixReport) => fixes.isActive(report.status)
46
47// The project's root: a shell cd during the session does not move it, nor a reload after one.
48let root = ''
49// The report whose turn is running; its prompt was submitted by this mod.
50let current: string | null = null
51// What the project is built with: it picks the system prompt section, the pane's words and, in a
52// Flutter project, the hot_reload tool.
53let kind: ProjectKind = 'native'
54// The receiver's port, once it listens: the hot_reload tool asks it.
55let port: number | null = null
56
57function relative(path: string) {
58  return root && path.startsWith(root + '/') ? path.slice(root.length + 1) : path
59}
60
61/** `path:line`, the path relative to the project. */
62const where = (file: string, line: number) => `${relative(file)}:${line}`
63
64/** Changes one report, then publishes every status for the app to poll. */
65async function patch($: EngineInterface, id: string, change: (report: FixReport) => FixReport) {
66  const list = await update($, reports, all => all.map(one => (one.id === id ? change(one) : one)))
67  const statuses = Object.fromEntries(list.map(one => [one.id, one.status]))
68  // In the project, where the receiver reads it.
69  await $.fs.write(`${root}/${STATUS_FILE}`, JSON.stringify(statuses))
70}
71
72async function accept($: EngineInterface, incoming: Incoming) {
73  const { file, line } = incoming.element ?? {}
74  const source = file && line ? where(file, line) : null
75  const usedAt = (incoming.element?.usedAt ?? []).map(use => where(use.file, use.line))
76  const report: FixReport = {
77    id: incoming.id,
78    comment: incoming.comment,
79    element: incoming.element?.name ?? null,
80    accessibility: incoming.accessibility ?? null,
81    viewDescription: incoming.viewDescription ?? null,
82    source,
83    screen: incoming.screen,
84    screenshot: incoming.screenshot,
85    status: 'queued',
86    receivedAt: await $.clock.now(),
87    finishedAt: null,
88    edited: [],
89  }
90  await update($, reports, all => [...all, report].slice(-50))
91  await patch($, report.id, one => one)
92  $.ui.toast(`Fix request ${report.id}: ${report.comment}`)
93
94  // Resolves when the report's own turn starts, after any turn already running.
95  // As the person's own words: they typed the comment, and the engine adds no frame around it.
96  await $.prompt.submit({ text: promptFor(incoming, source, usedAt), asUser: true })
97  current = report.id
98  await patch($, report.id, one => ({ ...one, status: fixes.started() }))
99}
100
101/** The app launched while Claude works on a report: whatever built it, the fix is on screen. */
102async function launched($: EngineInterface) {
103  if (current !== null) {
104    await patch($, current, one => ({ ...one, status: fixes.launched() }))
105  }
106}
107
108async function listen($: EngineInterface) {
109  await update($, receiver, (): Receiver => ({ state: 'starting', detail: '' }))
110  const child = $.process.spawn({ argv: ['node', `${$.plugin.root}/server/receiver.mjs`], cwd: root })
111  let pending = ''
112
113  try {
114    for await (const { stream, text } of child) {
115      if (stream === 'stderr') {
116        $.ui.log(text, { to: 'debug' })
117        continue
118      }
119      pending += text
120      const lines = pending.split('\n')
121      pending = lines.pop() ?? ''
122
123      for (const line of lines.filter(Boolean)) {
124        const event = JSON.parse(line) as ReceiverEvent
125        if (event.type === 'ready') {
126          port = event.port
127          await update($, receiver, (): Receiver => ({ state: 'listening', detail: `127.0.0.1:${event.port}` }))
128        } else if (event.type === 'error') {
129          await update($, receiver, (): Receiver => ({ state: 'failed', detail: event.message }))
130          $.ui.toast(`fixkit: ${event.message}`)
131        } else if (event.type === 'notice') {
132          await update($, receiver, (was): Receiver => ({ ...was, notice: event.message }))
133        } else if (event.type === 'launched') {
134          void launched($)
135        } else {
136          void accept($, event.report)
137        }
138      }
139    }
140  } catch (error) {
141    await update($, receiver, (): Receiver => ({ state: 'failed', detail: String(error) }))
142    return
143  }
144
145  // The child has exited. Say so, unless it already reported why.
146  await update($, receiver, (was): Receiver =>
147    was.state === 'failed' ? was : { state: 'failed', detail: 'receiver stopped; run /reload-plugins' },
148  )
149}
150
151export const register: Register = on => {
152  on('session.start', async ($, e, next) => {
153    root = await $.session.root()
154    const readFile = (path: string) => $.fs.read(`${root}/${path}`).catch(() => null)
155    const [packageJson, pubspec] = await Promise.all([readFile('package.json'), readFile('pubspec.yaml')])
156    kind = projectKind({ packageJson, pubspec })
157    if (kind === 'flutter') {
158      await $.tool.register({
159        name: 'hot_reload',
160        description:
161          'Hot reloads the Flutter app that flutter run runs in the simulator or the emulator, so saved changes to its Dart code show on screen. restart: true hot restarts it instead, for changes hot reload does not apply. Fails with the reason, a compile error most likely.',
162        inputSchema: {
163          type: 'object',
164          properties: { restart: { type: 'boolean', description: 'Hot restart instead of hot reload' } },
165        },
166        isDeferred: false,
167      })
168    }
169    await $.command.register({
170      name: 'fix-queue',
171      description: 'Show the fix requests sent from the app in the simulator or the emulator',
172    })
173    const started = await next(e)
174
175    void $.ui.open({ id: PANE, title: TITLE })
176    void listen($)
177    // Keeps the elapsed seconds of a running fix ticking in the pane.
178    $.clock.every(1000, () => {
179      void (async () => {
180        if ((await read($, reports)).some(isActive)) {
181          await update($, now, () => Date.now())
182        }
183      })()
184    })
185
186    return started
187  })
188
189  on('prompt.compose', async ($, e, next) => {
190    const composed = await next(e)
191
192    return {
193      sections: [...composed.sections, { id: 'fixkit:fix-requests', text: instructionsFor(kind), scope: 'session' }],
194    }
195  })
196
197  on('command.run', { command: 'fix-queue' }, async $ => {
198    await $.ui.open({ id: PANE, title: TITLE })
199
200    return { text: 'Fix queue opened.' }
201  })
202
203  // A status that fails to save must not fail the tool call itself.
204  on('tool.call', async ($, e, next) => {
205    const id = current
206    if (id === null || e.agentId !== undefined) {
207      return next(e)
208    }
209
210    if (isBuildAndRun(String(e.tool))) {
211      await patch($, id, one => ({ ...one, status: fixes.building() }))
212      const ran = await next(e)
213      // A launch during the call has marked the report live; a failed call leaves it fixing.
214      if (ran.deny !== undefined || ran.isError === true) {
215        await patch($, id, one => ({ ...one, status: fixes.buildEnded(one.status) }))
216      }
217
218      return ran
219    }
220
221    if (e.tool === 'Edit' || e.tool === 'Write') {
222      const name = e.file_path.split('/').pop() ?? e.file_path
223      await patch($, id, one => (one.edited.includes(name) ? one : { ...one, edited: [...one.edited, name] }))
224    }
225
226    return next(e)
227  }).catch(($, e, next) => next(e))
228
229  // The hot_reload tool, through the receiver, which holds the Flutter app's VM service. Registered
230  // inside the hook above, which shows the report as rebuilding meanwhile.
231  on('tool.call', { tool: HOT_RELOAD_TOOL }, async ($, e) => {
232    const restart = e.restart === true
233    let answer: { ok: boolean; error?: string }
234    try {
235      if (port === null) throw new Error('The fixkit receiver is not listening yet')
236      const { text } = await $.http.fetch(`http://127.0.0.1:${port}/reload`, { method: 'POST', body: JSON.stringify({ restart }) })
237      answer = JSON.parse(text)
238    } catch (error) {
239      answer = { ok: false, error: error instanceof Error ? error.message : String(error) }
240    }
241    if (!answer.ok) {
242      const text = answer.error ?? 'The reload failed'
243      return { isError: true, result: text, text }
244    }
245    return { result: restart ? 'Restarted the app: the change is on screen.' : 'Reloaded the app: the change is on screen.' }
246  })
247
248  on('turn.complete', async ($, e, next) => {
249    const id = current
250    if (id !== null && e.agentId === undefined) {
251      current = null
252      const finishedAt = await $.clock.now()
253      // Live only when the app launched with the fix and the turn ended with an answer.
254      await patch($, id, one => ({
255        ...one,
256        status: fixes.finished(one.status, e.reason === 'answer'),
257        finishedAt,
258      }))
259    }
260
261    return next(e)
262  })
263
264  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
265    const { Box, Text } = $.ui.resolve(e)
266    const list = await read($, reports)
267    const link = await read($, receiver)
268    const clock = (await read($, now)) || (await $.clock.now())
269    const width = Math.max(20, e.props.bodyColumns)
270    // Each report takes five rows; the newest ones are kept in view.
271    const room = Math.max(1, Math.floor(((e.viewport?.rows ?? 30) - 6) / 5))
272
273    return (
274      <Box flexDirection="column" width={width}>
275        <Text color={link.state === 'failed' ? 'red' : link.state === 'listening' ? 'green' : 'yellow'}>
276          {link.state === 'listening' ? '●' : '○'} {link.state} <Text dimColor>{link.detail}</Text>
277        </Text>
278        {link.notice !== undefined && (
279          <Text dimColor wrap="wrap">
280            {link.notice}
281          </Text>
282        )}
283
284        {list.length === 0 && (
285          <Box flexDirection="column" marginTop={1}>
286            <Text>No fix requests yet.</Text>
287            <Text dimColor wrap="wrap">
288              Long press any element in the app, type what is wrong and press Return.
289            </Text>
290          </Box>
291        )}
292
293        {list.slice(-room).map(report => {
294          const look = (kind === 'native' ? LOOK : RELOAD_LOOK)[report.status]
295          const seconds = Math.max(0, Math.round(((report.finishedAt ?? clock) - report.receivedAt) / 1000))
296
297          return (
298            <Box flexDirection="column" marginTop={1}>
299              <Box justifyContent="space-between">
300                <Text color={look.color} bold>
301                  {look.mark} {report.id} {look.label}
302                </Text>
303                <Text dimColor>{seconds}s</Text>
304              </Box>
305              <Text bold wrap="truncate-end">
306                “{report.comment}”
307              </Text>
308              <Text wrap="truncate-middle">{pressedLabel(report)}</Text>
309              {report.source !== null && (
310                <Text dimColor wrap="truncate-start">
311                  {report.source}
312                </Text>
313              )}
314              {report.edited.length > 0 && (
315                <Text color="cyan" wrap="truncate-end">
316                  edited {report.edited.join(', ')}
317                </Text>
318              )}
319            </Box>
320          )
321        })}
322      </Box>
323    )
324  })
325}
326

1// The status rules every harness follows, so a report reads the same in the app's banners
2// whichever agent works on it: queued → fixing → rebuilding → live, or stopped.
3
4/** @typedef {import('../types').FixStatus} FixStatus */
5
6/** The report's own turn has started. @returns {FixStatus} */
7export const started = () => 'fixing'
8
9/** The app is being built and launched. @returns {FixStatus} */
10export const building = () => 'rebuilding'
11
12/** The app launched while the report was worked on: whatever built it, the fix is on screen. @returns {FixStatus} */
13export const launched = () => 'live'
14
15/**
16 * A build call has returned. A launch during it has made the report live; otherwise the work goes on.
17 * @param {FixStatus} status
18 * @returns {FixStatus}
19 */
20export const buildEnded = status => (status === 'rebuilding' ? 'fixing' : status)
21
22/**
23 * The report's turn has ended. Live only when the app launched with the fix and the turn ended with an answer.
24 * @param {FixStatus} status
25 * @param {boolean} answered
26 * @returns {FixStatus}
27 */
28export const finished = (status, answered) => (answered && status === 'live' ? 'live' : 'stopped')
29
30/** @param {FixStatus} status */
31export const isActive = status => status !== 'live' && status !== 'stopped'
32

1// The prompt lives in core/, where every harness's adapter and the receiver can load it.
2export * from '../core/prompt.mjs'
3

1// The prompt every harness sends for a report, and the instructions that explain it. Plain
2// ESM with JSDoc types, so the Claude Code mod, the receiver and other harnesses' adapters
3// load it without a build.
4
5/**
6 * @typedef {import('../types').Accessibility} Accessibility
7 * @typedef {import('../types').AxElement} AxElement
8 * @typedef {import('../types').FixReport} FixReport
9 * @typedef {import('../types').Incoming} Incoming
10 */
11
12/** What a `[fix …]` prompt calls for; sent with the system prompt while the mod is loaded. */
13export const INSTRUCTIONS = `# Fix requests from the running app
14
15A prompt that ends with a line like
16
17[fix r1] TransactionRow › Text · Features/Home/TransactionRow.swift:29 · used at Features/Home/HomeView.swift:60 · StaticText "−€7.40" near "Coffee" · .fixkit/reports/r1.png
18[fix r2] StaticText "+€4,650.00" near "Northwind GmbH", "Salary, September" · Activity screen · .fixkit/reports/r2.png
19[fix r3] ProfileViewController.nameLabel · UILabel "Alex Morgan" · .fixkit/reports/r3.png
20
21was sent from the iOS app running in the simulator by the fixkit mod: someone long-pressed an element and typed the text above that line. The line holds the report's id and what is known about the element: in SwiftUI, the view's type after the app's view around it, or after the .fixable("name") on it or on a view around it, the file and line where the view's expression starts, and where the app's views around it are used; what accessibility says it is (its type, label, value, the control around it and the labels beside it in the same row); in a UIKit app, the view named after the property that holds it as Type.property, or its class and text, and its view controller as the screen; the screen's name when the app gives one; and a screenshot with the element outlined in red, or a red ring where the finger was.
22
23When a prompt carries that line:
24- Treat the text above it as the request. It may be a bug ("button is shifted") or a change ("make this green").
25- With a file and line, start there: the cause is in that view's expression and its modifiers, in the view around it, or in what is passed where that view is used.
26- When accessibility names something that is not at that line, something drawn over that view was pressed, such as a bar over a list: go by accessibility and the screenshot.
27- With a Type.property name, start at that property's declaration and where it is configured.
28- Without one, find the view by searching the Swift sources for the label and the labels beside it; a label made from data (an amount, a date) is found through the view that formats it, so search the neighbouring fixed labels first.
29- Make the smallest change that does what was asked. Do not refactor.
30- Open the screenshot only when the text and the code leave the request unclear.
31- Then rebuild and relaunch the app in the simulator the way this project builds (XcodeBuildMCP's build_run_sim when it is connected), so the change is on screen: the report counts as fixed once the app has launched again.
32- Answer in one or two sentences: what was wrong and what changed.`
33
34/** What a `[fix …]` prompt calls for in a React Native project, in place of `INSTRUCTIONS`. */
35export const RN_INSTRUCTIONS = `# Fix requests from the running app
36
37A prompt that ends with a line like
38
39[fix r1] WalletCard › Text · src/WalletCard.tsx:18 · used at App.tsx:31 · StaticText "Alex Morgan" · .fixkit/reports/r1.png
40[fix r2] StaticText "+€4,650.00" near "Northwind GmbH", "Salary, September" · .fixkit/reports/r2.png
41
42was sent from the React Native app running in the iOS simulator or the Android emulator by the fixkit mod: someone long-pressed an element and typed the text above that line. The line holds the report's id and what is known about the element: the components that rendered it, innermost last; the file and line where its JSX is written; where the components around it are used; what accessibility says it is (its type, label, value, #testID, the control around it and the labels beside it in the same row); and a screenshot with the element outlined in red, or a red ring where the finger was.
43
44When a prompt carries that line:
45- Treat the text above it as the request. It may be a bug ("button is shifted") or a change ("make this green").
46- With a file and line, start there: the cause is on that element, in the component around it, or in the props passed where that component is used. The line is read from the code the app launched with, so when that file has changed since, look around it.
47- Without one, find the element by searching the app's .tsx, .ts, .jsx and .js sources for its label, its testID and the labels beside it; a label made from data (an amount, a date) is found through the component that formats it, so search the neighbouring fixed labels first.
48- Make the smallest change that does what was asked. Do not refactor.
49- Open the screenshot only when the text and the code leave the request unclear.
50- Save the change and do not rebuild: Metro's Fast Refresh puts it on screen, which counts the report as fixed. Rebuild only when the change touches native code or native configuration, with the project's own command (npx expo run:ios or npx expo run:android, npx react-native run-ios or npx react-native run-android).
51- Answer in one or two sentences: what was wrong and what changed.`
52
53/**
54 * What a `[fix …]` prompt calls for in a Flutter project, in place of `INSTRUCTIONS`, with the way
55 * the harness hot reloads the app: `reload` asks for a reload, `restart` for a restart instead.
56 * @param {{ reload: string, restart: string }} how
57 */
58function flutterInstructions({ reload, restart }) {
59  return `# Fix requests from the running app
60
61A prompt that ends with a line like
62
63[fix r1] ProfileHeader › Text · lib/profile_header.dart:24 · used at lib/home.dart:31 · StaticText "Alex Morgan" · .fixkit/reports/r1.png
64[fix r2] StaticText "+€4,650.00" near "Northwind GmbH", "Salary, September" · .fixkit/reports/r2.png
65
66was sent from the Flutter app running in the iOS simulator or the Android emulator by the fixkit mod: someone long-pressed an element and typed the text above that line. The line holds the report's id and what is known about the element: the app's widget around it and the widget itself; the file and line where that widget is constructed; where the widgets around it are used; what accessibility says it is (its type, label, value, the control around it and the labels beside it in the same row); and a screenshot with the element outlined in red, or a red ring where the finger was.
67
68When a prompt carries that line:
69- Treat the text above it as the request. It may be a bug ("button is shifted") or a change ("make this green").
70- With a file and line, start there: the cause is in that constructor call, in the widget around it, or in what is passed where that widget is used.
71- Without one, find the widget by searching the app's .dart sources for its label and the labels beside it; a label made from data (an amount, a date) is found through the widget that formats it, so search the neighbouring fixed labels first.
72- Make the smallest change that does what was asked. Do not refactor.
73- Open the screenshot only when the text and the code leave the request unclear.
74- Save the change and ${reload}: it puts the change on screen, which counts the report as fixed. ${restart} when hot reload does not apply the change: a change to initState, field initializers, global or static variables, main, or an enum or generic type. When it fails, run dart analyze on the files you changed, fix what it reports and call it again. Rebuild with flutter run only when the change touches native code or native configuration.
75- Answer in one or two sentences: what was wrong and what changed.`
76}
77
78// How Claude Code hot reloads the app: through the hot_reload tool its mod serves.
79const CLAUDE_CODE_RELOAD = { reload: 'call the hot_reload tool', restart: 'Pass restart: true' }
80
81/**
82 * The instructions for a project of `kind`. A Flutter project's say how this harness hot reloads
83 * the app; without `flutterReload`, through the Claude Code mod's hot_reload tool.
84 * @param {ProjectKind} kind
85 * @param {{ reload: string, restart: string }} [flutterReload]
86 */
87export function instructionsFor(kind, flutterReload = CLAUDE_CODE_RELOAD) {
88  if (kind === 'flutter') return flutterInstructions(flutterReload)
89  return kind === 'react-native' ? RN_INSTRUCTIONS : INSTRUCTIONS
90}
91
92/** The Flutter instructions for Claude Code, whose mod serves the hot_reload tool. */
93export const FLUTTER_INSTRUCTIONS = instructionsFor('flutter')
94
95/** The tool the mod serves in a Flutter project: hot reload, or restart, the app `flutter run` runs. */
96export const HOT_RELOAD_TOOL = 'mcp__fixkit__hot_reload'
97
98/** @typedef {'native' | 'react-native' | 'flutter'} ProjectKind */
99
100/**
101 * Flutter when pubspec.yaml depends on the Flutter SDK, React Native when package.json depends on it, else native.
102 * @param {{ packageJson: string | null, pubspec: string | null }} files
103 * @returns {ProjectKind}
104 */
105export function projectKind({ packageJson, pubspec }) {
106  if (pubspec !== null && /^\s+sdk:\s*flutter\s*(?:#.*)?$/m.test(pubspec)) return 'flutter'
107  return isReactNativeProject(packageJson) ? 'react-native' : 'native'
108}
109
110/**
111 * Whether the project's package.json depends on React Native.
112 * @param {string | null} packageJson
113 */
114export function isReactNativeProject(packageJson) {
115  if (packageJson === null) return false
116  try {
117    const { dependencies = {}, devDependencies = {} } = JSON.parse(packageJson)
118    return 'react-native' in dependencies || 'react-native' in devDependencies
119  } catch {
120    return false
121  }
122}
123
124/**
125 * One accessibility element in words: its type, then its label, value and identifier.
126 * @param {AxElement} element
127 */
128function describeOne(element) {
129  const parts = [element.type]
130  if (element.label) parts.push(JSON.stringify(element.label))
131  if (element.value && element.value !== element.label) parts.push(`= ${JSON.stringify(element.value)}`)
132  if (element.identifier) parts.push(`#${element.identifier}`)
133  return parts.join(' ')
134}
135
136/**
137 * What accessibility says was pressed, in one phrase for the prompt and the pane.
138 * @param {Accessibility} accessibility
139 */
140export function describeAccessibility({ element, within, nearby }) {
141  let text = describeOne(element)
142  if (within) text += ` in ${describeOne(within)}`
143  if (nearby.length > 0) text += ` near ${nearby.map(label => JSON.stringify(label)).join(', ')}`
144  return text
145}
146
147/**
148 * The prompt: the person's comment as they typed it, then one line of context.
149 * `INSTRUCTIONS` tells the model what a message carrying a `[fix …]` line calls for.
150 * @param {Incoming} incoming
151 * @param {string | null} source
152 * @param {string[]} [usedAt]
153 */
154export function promptFor(incoming, source, usedAt = []) {
155  const { comment, element, id, screen, screenshot, touch } = incoming
156  const pressed = describePressed(incoming)
157  const context = [
158    element?.name,
159    source,
160    usedAt.length > 0 ? `used at ${usedAt.join(', ')}` : null,
161    pressed,
162    // A marked element says where it is; otherwise the screen's name helps find it.
163    !element && screen ? `${screen} screen` : null,
164    !element && !pressed && touch ? `touch at ${Math.round(touch.x)},${Math.round(touch.y)}` : null,
165    screenshot,
166  ].filter(Boolean)
167
168  return `${comment}\n\n[fix ${id}] ${context.join(' · ')}`
169}
170
171/**
172 * What was pressed in words. A UIKit app describes the very view it found under the finger, so its
173 * words come first; accessibility, read by position, can name a view under a sheet or a container.
174 * @param {{ accessibility?: Accessibility | null, viewDescription?: string | null }} pressed
175 * @returns {string | null}
176 */
177function describePressed({ accessibility, viewDescription }) {
178  return viewDescription ?? (accessibility ? describeAccessibility(accessibility) : null)
179}
180
181/**
182 * How the pane names what was pressed: the element's name, else what the app or accessibility said.
183 * @param {Pick<FixReport, 'element' | 'accessibility' | 'viewDescription' | 'screen'>} report
184 */
185export function pressedLabel(report) {
186  const { element, screen } = report
187  if (element) return element
188  const pressed = describePressed(report)
189  if (pressed) return pressed
190  return screen ? `${screen} screen` : 'unnamed element'
191}
192
193/**
194 * Whether a tool call puts a new build on screen: XcodeBuildMCP's build-and-run, or the mod's own
195 * hot reload in a Flutter project. The pane shows the report as rebuilding meanwhile; whether the
196 * fix reached the screen comes from the app itself, when it launches or reloads.
197 * @param {string} tool
198 */
199export function isBuildAndRun(tool) {
200  return tool === HOT_RELOAD_TOOL || /(?:^|_)build_run_sim$/.test(tool)
201}
202

1export type FixStatus = 'queued' | 'fixing' | 'rebuilding' | 'live' | 'stopped'
2
3/** An accessibility element as the receiver summarises it. */
4export type AxElement = {
5  type: string
6  label: string | null
7  value: string | null
8  identifier: string | null
9}
10
11/** What accessibility says the touch landed on. */
12export type Accessibility = {
13  element: AxElement
14  /** The nearest named element around it: the button around an icon, say. */
15  within: AxElement | null
16  /** Labels of the elements beside it in the same row, nearest first. */
17  nearby: string[]
18}
19
20/** A report as the receiver prints it, one JSON line each. */
21export type Incoming = {
22  id: string
23  comment: string
24  screen: string
25  screenshot: string | null
26  touch?: { x: number; y: number }
27  /**
28   * The element under the touch: a SwiftUI view named after the app's view around it
29   * (`TransactionRow › Text`) with the line its expression starts on, one marked with `.fixable`
30   * with its source line, or in a UIKit app a view named after the property that holds it
31   * (`ProfileViewController.nameLabel`), without one.
32   */
33  element?: {
34    name: string
35    file?: string
36    line?: number
37    /** Where the app's components around the element are used, nearest first. */
38    usedAt?: { file: string; line: number }[]
39  }
40  /** UIKit only: the pressed view's class and text, as the app sees it. */
41  viewDescription?: string
42  accessibility?: Accessibility | null
43}
44
45export type FixReport = {
46  id: string
47  comment: string
48  /** What was pressed: its `.fixable` name, or in a UIKit app the property that holds it (`Type.property`). */
49  element: string | null
50  accessibility: Accessibility | null
51  /** UIKit only: the pressed view's class and text. */
52  viewDescription: string | null
53  /** `path:line` of the element's declaration, relative to the project. */
54  source: string | null
55  screen: string
56  screenshot: string | null
57  status: FixStatus
58  receivedAt: number
59  finishedAt: number | null
60  /** Names of the files Claude edited for this report. */
61  edited: string[]
62}
63
64export type Receiver = {
65  state: 'starting' | 'listening' | 'failed'
66  detail: string
67  /** Advice that stays in the pane: how to install AXe, say. */
68  notice?: string
69}
70
71declare module 'claude-code' {
72  interface McpToolInputs {
73    /** The mod's own tool in a Flutter project: hot reload, or with `restart` hot restart, the app. */
74    mcp__fixkit__hot_reload: { restart?: boolean }
75  }
76  interface PluginState {
77    fixkit: { reports: FixReport[]; receiver: Receiver; now: number }
78  }
79}
80