reifyui 0.16.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "reifyui",
3
- "version": "0.16.1",
3
+ "version": "0.18.0",
4
4
  "description": "The open-source rendering & interaction layer for agentic applications. Stream and render any agent's output as polished, application-native UI — model-agnostic, framework-agnostic, design-system-native. The foundation for building generative-UI and agent products.",
5
5
  "keywords": [
6
6
  "react",
@@ -1,23 +1,173 @@
1
1
  // The files a turn produced, opened beside the conversation instead of printed into it.
2
2
  //
3
3
  // In the conversation a file is a card (the package's FileCard: its kind, Copy, Download, and the
4
- // whole card opens it). Opened, it shows here: the file rendered (Markdown as a document, code
5
- // highlighted, images, PDFs, sheets), a switcher across every file the conversation made, Copy,
6
- // Download and Close. Docked, it is a column the host places beside the chat; `overlay` makes it a
7
- // drawer over the page from the right, which is what a narrow screen gets.
4
+ // whole card opens it). Opened, it shows here, under ONE header row: the file's kind, its name as a
5
+ // switcher (a dropdown of every file of the conversation, grouped by folder, filterable when there are
6
+ // many, keyboard driven), then Copy, Download and Close. Below, the file rendered (Markdown as a
7
+ // document, code highlighted, images, PDFs, sheets). Docked, it is a column the host places beside the
8
+ // chat; `overlay` makes it a drawer over the page from the right, and on a phone the dropdown is a
9
+ // sheet from the bottom.
8
10
  //
9
11
  // Transport and rendering stay the host's, exactly as for FilePreview: `fetchFile` (with the
10
12
  // host's auth), `renderMarkdown`, `officePdfUrl`, `parseWorkbook`, `onDownload`.
11
- import React, { useEffect, useRef } from 'react';
13
+ import React, { useEffect, useMemo, useRef, useState } from 'react';
12
14
  import { FilePreview } from '../components/FilePreview.jsx';
13
15
  import { FileTypeIcon } from '../components/FileTypeIcon.jsx';
16
+ import { bytesLabel } from '../format.js';
17
+
18
+ const FILTER_AT = 8; // more files than this, and the list opens with a filter box
19
+
20
+ /** "epsilla-enterprise-subscr…store-v2.png": the start and the end, which is where names differ. */
21
+ export function middleEllipsis(name, max = 40) {
22
+ const s = String(name || '');
23
+ if (s.length <= max) return s;
24
+ const tail = Math.min(Math.max(10, Math.floor(max * 0.45)), max - 4);
25
+ return `${s.slice(0, max - tail - 1)}…${s.slice(-tail)}`;
26
+ }
27
+
28
+ /** A name that truncates in the MIDDLE at whatever width it gets: the start shrinks with an ellipsis,
29
+ * the end (where similar names differ: "-v2", the extension) always shows. */
30
+ export function MidName(props) {
31
+ const { name, className } = props;
32
+ const s = String(name || '');
33
+ const cut = s.length > 16 ? s.length - Math.min(14, Math.floor(s.length / 2)) : s.length;
34
+ return (
35
+ <span className={'uac-mid' + (className ? ` ${className}` : '')}>
36
+ <span className="uac-mid-h">{s.slice(0, cut)}</span>{cut < s.length ? <span className="uac-mid-t">{s.slice(cut)}</span> : null}
37
+ </span>
38
+ );
39
+ }
40
+
41
+ function dirOf(path) {
42
+ const p = String(path || '');
43
+ const i = p.lastIndexOf('/');
44
+ return i > 0 ? p.slice(0, i) : '';
45
+ }
46
+
47
+ function Check() {
48
+ return (
49
+ <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.4" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
50
+ <path d="M5 12l5 5L20 7" />
51
+ </svg>
52
+ );
53
+ }
54
+
55
+ /** The name in the header, as a dropdown of every file. `files`: [{key, name, path?, size?, turn?}]. */
56
+ export function FileSwitcher(props) {
57
+ const { files, current, onSelect, label = 'Files in this conversation', turnLabel = (n) => `Turn ${n}` } = props;
58
+ const [open, setOpen] = useState(false);
59
+ const [q, setQ] = useState('');
60
+ const [hi, setHi] = useState(0);
61
+ const root = useRef(null);
62
+ const list = useRef(null);
63
+ const input = useRef(null);
64
+ const btn = useRef(null);
65
+ const id = useRef(`uac-fs-${Math.random().toString(36).slice(2, 9)}`).current;
66
+ const cur = files.find((f) => f.key === current) || files[0];
67
+ const needle = q.trim().toLowerCase();
68
+ const shown = useMemo(() => files.filter((f) => !needle || String(f.path || f.name).toLowerCase().includes(needle)), [files, needle]);
69
+ // by folder, in the order folders first appear; the root (no folder) first
70
+ const groups = useMemo(() => {
71
+ const by = new Map();
72
+ for (const f of shown) {
73
+ const d = dirOf(f.path);
74
+ if (!by.has(d)) by.set(d, []);
75
+ by.get(d).push(f);
76
+ }
77
+ return [...by.entries()].sort((a, b) => (a[0] === '' ? -1 : b[0] === '' ? 1 : 0));
78
+ }, [shown]);
79
+ const flat = groups.flatMap(([, fs]) => fs);
80
+ const grouped = groups.length > 1 || (groups.length === 1 && groups[0][0] !== '');
81
+ const many = files.length > FILTER_AT;
82
+
83
+ useEffect(() => {
84
+ if (!open) return undefined;
85
+ setHi(Math.max(0, flat.findIndex((f) => f.key === (cur && cur.key))));
86
+ const t = setTimeout(() => { if (many && input.current) input.current.focus(); else if (list.current) list.current.focus(); }, 0);
87
+ const away = (e) => { if (root.current && !root.current.contains(e.target)) setOpen(false); };
88
+ document.addEventListener('mousedown', away);
89
+ document.addEventListener('touchstart', away);
90
+ return () => { clearTimeout(t); document.removeEventListener('mousedown', away); document.removeEventListener('touchstart', away); };
91
+ }, [open]); // eslint-disable-line react-hooks/exhaustive-deps
92
+ useEffect(() => { setHi(0); }, [needle]);
93
+ useEffect(() => {
94
+ if (!open || !list.current) return;
95
+ const el = list.current.querySelector(`[data-i="${hi}"]`);
96
+ if (el && el.scrollIntoView) el.scrollIntoView({ block: 'nearest' });
97
+ }, [hi, open]);
98
+
99
+ if (!cur) return null;
100
+ const pick = (f) => { setOpen(false); setQ(''); if (f && onSelect) onSelect(f.key); if (btn.current) btn.current.focus(); };
101
+ const keys = (e) => {
102
+ if (e.key === 'ArrowDown') { e.preventDefault(); setHi((i) => Math.min(flat.length - 1, i + 1)); }
103
+ else if (e.key === 'ArrowUp') { e.preventDefault(); setHi((i) => Math.max(0, i - 1)); }
104
+ else if (e.key === 'Home') { e.preventDefault(); setHi(0); }
105
+ else if (e.key === 'End') { e.preventDefault(); setHi(flat.length - 1); }
106
+ else if (e.key === 'Enter') { e.preventDefault(); pick(flat[hi]); }
107
+ else if (e.key === 'Escape') { e.preventDefault(); e.stopPropagation(); setOpen(false); if (btn.current) btn.current.focus(); }
108
+ else if (e.key === 'Tab') setOpen(false);
109
+ };
110
+ const single = files.length < 2;
111
+ let i = -1;
112
+ return (
113
+ <div ref={root} className={'uac-fs' + (open ? ' is-open' : '')}>
114
+ <button ref={btn} type="button" className="uac-fs-btn" title={cur.path || cur.name} disabled={single}
115
+ aria-haspopup={single ? undefined : 'listbox'} aria-expanded={single ? undefined : open} aria-controls={single ? undefined : id}
116
+ onClick={() => setOpen((v) => !v)}
117
+ onKeyDown={(e) => { if (!single && (e.key === 'ArrowDown' || e.key === 'ArrowUp')) { e.preventDefault(); setOpen(true); } }}>
118
+ <MidName name={cur.name} className="uac-fs-name" />
119
+ {single ? null : (
120
+ <svg className="uac-fs-chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><path d="M6 9l6 6 6-6" /></svg>
121
+ )}
122
+ </button>
123
+ {open ? (
124
+ <>
125
+ <div className="uac-fs-scrim" aria-hidden="true" onClick={() => setOpen(false)} />
126
+ <div className="uac-fs-pop" onKeyDown={keys}>
127
+ <div className="uac-fs-head"><span>{label}</span><span className="uac-fs-count">{files.length}</span></div>
128
+ {many ? (
129
+ <input ref={input} className="uac-fs-q" type="search" placeholder="Find a file" value={q} autoComplete="off" spellCheck={false}
130
+ aria-label="Find a file" aria-controls={id} onChange={(e) => setQ(e.target.value)} />
131
+ ) : null}
132
+ <div ref={list} id={id} className="uac-fs-list" role="listbox" tabIndex={-1} aria-label={label}
133
+ aria-activedescendant={flat[hi] ? `${id}-${hi}` : undefined}>
134
+ {groups.map(([dir, fs]) => (
135
+ <div key={dir || '.'} role="group" aria-label={dir || 'Top level'}>
136
+ {grouped ? <div className="uac-fs-dir" aria-hidden="true">{dir || 'Top level'}</div> : null}
137
+ {fs.map((f) => {
138
+ i += 1;
139
+ const n = i;
140
+ const on = f.key === cur.key;
141
+ const meta = [f.size != null ? bytesLabel(f.size) : '', f.turn != null ? turnLabel(f.turn) : ''].filter(Boolean).join(' · ');
142
+ return (
143
+ <div key={f.key} id={`${id}-${n}`} data-i={n} role="option" aria-selected={on}
144
+ className={'uac-fs-opt' + (on ? ' is-on' : '') + (n === hi ? ' is-hi' : '')}
145
+ title={f.path || f.name} onMouseEnter={() => setHi(n)} onClick={() => pick(f)}>
146
+ <FileTypeIcon name={f.name} size={16} />
147
+ <MidName name={f.name} className="uac-fs-on" />
148
+ {meta ? <span className="uac-fs-meta">{meta}</span> : null}
149
+ <span className="uac-fs-ck">{on ? <Check /> : null}</span>
150
+ </div>
151
+ );
152
+ })}
153
+ </div>
154
+ ))}
155
+ {!flat.length ? <div className="uac-fs-none">No file matches.</div> : null}
156
+ </div>
157
+ </div>
158
+ </>
159
+ ) : null}
160
+ </div>
161
+ );
162
+ }
14
163
 
15
164
  /**
16
- * files: [{ key, name, url }] (key: stable id, e.g. the file id); active: the key shown.
165
+ * files: [{ key, name, url, path?, size?, turn? }] (key: stable id, e.g. the file id; path: where it
166
+ * sits in the workspace, for folders; size in bytes and the turn that made it, when known).
17
167
  */
18
168
  export function ArtifactPanel(props) {
19
169
  const {
20
- files = [], active, onSelect, onClose, overlay = false, label = 'Files in this conversation',
170
+ files = [], active, onSelect, onClose, overlay = false, label = 'Files in this conversation', turnLabel,
21
171
  fetchFile, renderMarkdown, officePdfUrl, parseWorkbook, onDownload, className,
22
172
  } = props;
23
173
  const ref = useRef(null);
@@ -27,27 +177,18 @@ export function ArtifactPanel(props) {
27
177
  if (!overlay || !cur) return undefined;
28
178
  const back = document.activeElement;
29
179
  const t = setTimeout(() => { const b = ref.current && ref.current.querySelector('button'); if (b) b.focus(); }, 0);
30
- const key = (e) => { if (e.key === 'Escape') { e.stopPropagation(); onClose && onClose(); } };
180
+ const key = (e) => { if (e.key === 'Escape' && !e.defaultPrevented) { e.stopPropagation(); onClose && onClose(); } };
31
181
  document.addEventListener('keydown', key);
32
182
  return () => { clearTimeout(t); document.removeEventListener('keydown', key); if (back && back.focus) back.focus(); };
33
183
  }, [overlay, !!cur]); // eslint-disable-line react-hooks/exhaustive-deps
34
184
  if (!cur) return null;
35
- const switcher = files.length > 1 ? (
36
- <nav className="uac-art-files" aria-label={label}>
37
- {files.map((f) => (
38
- <button key={f.key} type="button" className={'uac-art-file' + (f.key === cur.key ? ' is-on' : '')}
39
- aria-current={f.key === cur.key ? 'true' : undefined} title={f.name} onClick={() => onSelect && onSelect(f.key)}>
40
- <FileTypeIcon name={f.name} size={14} /><span>{f.name}</span>
41
- </button>
42
- ))}
43
- </nav>
44
- ) : null;
185
+ const switcher = <FileSwitcher files={files} current={cur.key} onSelect={onSelect} label={label} turnLabel={turnLabel} />;
45
186
  return (
46
187
  <>
47
188
  {overlay ? <div className="uac-art-scrim" aria-hidden="true" onClick={() => onClose && onClose()} /> : null}
48
189
  <div ref={ref} className={'uac-art' + (overlay ? ' is-overlay' : '') + (className ? ` ${className}` : '')}
49
190
  role={overlay ? 'dialog' : undefined} aria-modal={overlay ? 'true' : undefined} aria-label={overlay ? `Preview of ${cur.name}` : undefined}>
50
- <FilePreview key={cur.key} file={{ url: cur.url, name: cur.name }} onClose={onClose} before={switcher}
191
+ <FilePreview key={cur.key} file={{ url: cur.url, name: cur.name }} onClose={onClose} nameSlot={switcher}
51
192
  fetchFile={fetchFile} renderMarkdown={renderMarkdown} officePdfUrl={officePdfUrl} parseWorkbook={parseWorkbook} onDownload={onDownload} />
52
193
  </div>
53
194
  </>
@@ -7,7 +7,7 @@
7
7
  // Components take one `props` object and destructure inside, so TypeScript hosts do not infer
8
8
  // every optional slot as required (the convention of the rest of the package).
9
9
  import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
10
- import { describeTool, toolLine, summarizeCalls, resultNote, parseToolArgs } from './tools.js';
10
+ import { describeTool, toolLine, summarizeCalls, resultNote, parseToolArgs, browserElements } from './tools.js';
11
11
  import { liveState, segments, latestPlan } from './turn.js';
12
12
  import { formatElapsed, formatDuration, formatTokens, useElapsed } from './time.js';
13
13
  import { Chevron, IcTerminal, IcDoc, IcScroll, IcSearch, IcGlobe, IcSpawn, IcList, IcSkill, IcPlug, IcTool, IcThink,
@@ -246,10 +246,15 @@ function StepDetail(props) {
246
246
  );
247
247
  }
248
248
 
249
- /** One call: what it did, to what, how it went; click for its whole input and output. */
249
+ /**
250
+ * One call: what it did, to what, how it went; click for its whole input and output. A call the host
251
+ * shows in a place of its own (`openStep` answers a handler for it: a browser step opens the browser
252
+ * beside the conversation) opens there on a click instead, the way a file card opens its file.
253
+ */
250
254
  export function StepRow(props) {
251
- const { item, labels = DEFAULT_AGENT_LABELS, defaultOpen = false } = props;
252
- const d = useMemo(() => describeTool(item.name, item.args), [item.name, item.args]);
255
+ const { item, labels = DEFAULT_AGENT_LABELS, defaultOpen = false, element = null, openStep, active = false } = props;
256
+ const d = useMemo(() => describeTool(item.name, item.args, { element }), [item.name, item.args, element]);
257
+ const opener = openStep ? openStep(item, d) || null : null;
253
258
  const [open, setOpen] = useState(defaultOpen);
254
259
  const uid = useRef(`uac-s-${Math.random().toString(36).slice(2, 9)}`).current;
255
260
  const running = item.status === 'running';
@@ -260,11 +265,12 @@ export function StepRow(props) {
260
265
  // split "Ran npm test" into the verb (quiet) and the target (ink), when the line is verb + target
261
266
  const hasTarget = d.target && line === `${verb} ${d.target}`;
262
267
  const note = !running && item.status !== 'failed' ? resultNote(d.kind, item.output) : '';
263
- const hasDetail = !!(item.args && item.args !== '{}' && item.args !== '""') || item.output !== undefined;
268
+ const hasDetail = !opener && (!!(item.args && item.args !== '{}' && item.args !== '""') || item.output !== undefined);
264
269
  return (
265
- <div className={cls('uac-step', `is-${item.status}`)} data-kind={d.kind}>
270
+ <div className={cls('uac-step', `is-${item.status}`, opener && 'is-opens', opener && active && 'is-active')} data-kind={d.kind}>
266
271
  <button type="button" className="uac-step-h" aria-expanded={hasDetail ? open : undefined} aria-controls={hasDetail ? uid : undefined}
267
- disabled={!hasDetail} onClick={() => setOpen((v) => !v)} title={d.targetFull || undefined}>
272
+ aria-current={opener && active ? 'true' : undefined}
273
+ disabled={!opener && !hasDetail} onClick={opener || (() => setOpen((v) => !v))} title={d.targetFull || undefined}>
268
274
  <StatusGlyph status={item.status} kind={d.kind} />
269
275
  <span className="uac-step-t">
270
276
  {hasTarget ? (<><span className="uac-step-v">{verb}</span> <span className={cls('uac-step-o', d.mono && 'is-mono')}>{d.target}</span></>)
@@ -276,7 +282,7 @@ export function StepRow(props) {
276
282
  {item.status === 'stopped' ? <span className="uac-step-n">{labels.stoppedCall}</span> : null}
277
283
  {running && runMs != null ? <span className="uac-step-time">{formatElapsed(runMs)}</span>
278
284
  : tookMs != null && tookMs >= 1000 ? <span className="uac-step-time">{formatDuration(tookMs)}</span> : null}
279
- {hasDetail ? <span className="uac-chev" aria-hidden="true"><Chevron dir={open ? 'down' : 'right'} size={12} /></span> : null}
285
+ {hasDetail || opener ? <span className="uac-chev" aria-hidden="true"><Chevron dir={open && !opener ? 'down' : 'right'} size={12} /></span> : null}
280
286
  </button>
281
287
  {item.status === 'failed' && item.output ? <div className="uac-step-err">{firstLine(item.output)}</div> : null}
282
288
  {open && hasDetail ? <StepDetail item={item} d={d} labels={labels} id={uid} /> : null}
@@ -322,14 +328,15 @@ function sumDiff(tools) {
322
328
  * live line, `[mark] 1m 4s · Running npm test`, and opens to the calls so far.
323
329
  */
324
330
  export function WorkGroup(props) {
325
- const { items, live = false, liveLabel, start = null, mark, motion, labels = DEFAULT_AGENT_LABELS, defaultOpen = false } = props;
331
+ const { items, live = false, liveLabel, start = null, mark, motion, labels = DEFAULT_AGENT_LABELS, defaultOpen = false,
332
+ elements = null, openStep, activeStep = null } = props;
326
333
  const [open, setOpen] = useState(defaultOpen);
327
334
  const uid = useRef(`uac-g-${Math.random().toString(36).slice(2, 9)}`).current;
328
335
  const tools = items.filter((x) => x.kind === 'tool');
329
336
  const thoughts = items.filter((x) => x.kind === 'thinking');
330
337
  const failed = tools.filter((x) => x.status === 'failed').length;
331
338
  let summary = '';
332
- if (tools.length) summary = summarizeCalls(tools);
339
+ if (tools.length) summary = summarizeCalls(elements ? tools.map((t) => ({ name: t.name, args: t.args, element: elements[t.id] })) : tools);
333
340
  else if (thoughts.length) {
334
341
  const t = thoughts[0];
335
342
  const ms = t.startedAt != null && t.endedAt != null ? t.endedAt - t.startedAt : null;
@@ -341,7 +348,8 @@ export function WorkGroup(props) {
341
348
  const body = open ? (
342
349
  <div className="uac-calls" id={uid}>
343
350
  {items.map((it) => (it.kind === 'tool'
344
- ? <StepRow key={it.id} item={it} labels={labels} />
351
+ ? <StepRow key={it.id} item={it} labels={labels} element={elements ? elements[it.id] || null : null}
352
+ openStep={openStep} active={activeStep != null && activeStep === it.id} />
345
353
  : <ThinkingRow key={it.id} item={it} labels={labels} />))}
346
354
  </div>
347
355
  ) : null;
@@ -496,9 +504,12 @@ export function TurnOutcome(props) {
496
504
  export function AgentTurnView(props) {
497
505
  const {
498
506
  turn, renderMarkdown, mark, motion, labels: labelsIn, showUser = true, renderUserFile, userExtra,
499
- meta, renderFiles, actions, describeIncomplete, liveStart,
507
+ meta, renderFiles, actions, describeIncomplete, liveStart, openStep, activeStep = null,
500
508
  } = props;
501
509
  const labels = useMemo(() => ({ ...DEFAULT_AGENT_LABELS, ...(labelsIn || {}) }), [labelsIn]);
510
+ // what each browser call acted on, read from the page snapshots before it in this turn
511
+ const items = turn ? turn.items : null;
512
+ const elements = useMemo(() => browserElements(items), [items]);
502
513
  if (!turn) return null;
503
514
  const running = turn.status === 'running';
504
515
  const segs = segments(turn);
@@ -509,7 +520,7 @@ export function AgentTurnView(props) {
509
520
  const liveWork = running && lastSeg && lastSeg.type === 'work';
510
521
  let liveLabel = labels.thinking;
511
522
  if (now) {
512
- if (now.phase === 'tool' && now.tool) liveLabel = toolLine(describeTool(now.tool.name, now.tool.args), 'running');
523
+ if (now.phase === 'tool' && now.tool) liveLabel = toolLine(describeTool(now.tool.name, now.tool.args, { element: elements[now.tool.id] }), 'running');
513
524
  else if (now.phase === 'writing') liveLabel = labels.writing;
514
525
  else if (now.phase === 'starting') liveLabel = labels.starting;
515
526
  }
@@ -526,7 +537,8 @@ export function AgentTurnView(props) {
526
537
  return (
527
538
  <React.Fragment key={`w${i}`}>
528
539
  {plan ? <TodoCard todos={plan} labels={labels} running /> : null}
529
- <WorkGroup items={s.items} live liveLabel={liveLabel} start={start} mark={mark} motion={motion} labels={labels} />
540
+ <WorkGroup items={s.items} live liveLabel={liveLabel} start={start} mark={mark} motion={motion} labels={labels}
541
+ elements={elements} openStep={openStep} activeStep={activeStep} />
530
542
  </React.Fragment>
531
543
  );
532
544
  }
@@ -534,7 +546,8 @@ export function AgentTurnView(props) {
534
546
  return <StreamingText key={s.item.id || `t${i}`} text={s.item.text} render={renderMarkdown}
535
547
  active={running && i === lastTextIdx && i === segs.length - 1} />;
536
548
  }
537
- return <WorkGroup key={`w${i}-${s.items[0] && s.items[0].id}`} items={s.items} labels={labels} />;
549
+ return <WorkGroup key={`w${i}-${s.items[0] && s.items[0].id}`} items={s.items} labels={labels}
550
+ elements={elements} openStep={openStep} activeStep={activeStep} />;
538
551
  })}
539
552
  {!liveWork && plan ? <TodoCard todos={plan} labels={labels} running={running} /> : null}
540
553
  {running && !liveWork ? <WorkingIndicator mark={mark} motion={motion} start={start} label={liveLabel} /> : null}
@@ -65,10 +65,18 @@ export interface ToolDescription {
65
65
  diff: { added: number; removed: number } | null;
66
66
  todos: TodoEntry[] | null;
67
67
  }
68
- export function describeTool(name: string, args: unknown): ToolDescription;
68
+ /** The element a browser call acts on, as a page snapshot named its ref. */
69
+ export interface BrowserElement { role: string; name: string }
70
+ /** `opts.element`: for a browser call, the element its ref names (from browserElements). */
71
+ export function describeTool(name: string, args: unknown, opts?: { element?: BrowserElement | null }): ToolDescription;
69
72
  export function toolKind(name: string): ToolKind;
70
73
  export function toolLine(d: ToolDescription, state: 'running' | 'done'): string;
71
- export function summarizeCalls(calls: { name: string; args?: unknown }[]): string;
74
+ export function summarizeCalls(calls: { name: string; args?: unknown; element?: BrowserElement | null }[]): string;
75
+ /** The action a browser tool's name carries ("click" for mcp__plugs__browser_click), '' when the action
76
+ * is an argument (`browser`, `computer`), null when the tool is not a browser's. */
77
+ export function browserActOf(name: string): string | null;
78
+ /** {[call id]: element} for the browser calls whose ref an earlier snapshot in the same turn named. */
79
+ export function browserElements(items: TurnItem[] | null | undefined): Record<string, BrowserElement>;
72
80
  export function resultNote(kind: ToolKind, output: unknown): string;
73
81
  export function parseToolArgs(args: unknown): Record<string, unknown>;
74
82
  export function todosOf(args: Record<string, unknown>): TodoEntry[] | null;
@@ -110,10 +118,14 @@ export function WorkingIndicator(props: MarkProps & {
110
118
  export function CopyButton(props: { text: string; labels?: AgentLabels; label?: string }): ReactElement;
111
119
  export function DiffBadge(props: { diff: { added: number; removed: number } | null }): ReactElement | null;
112
120
  export function LinesBlock(props: { lines: { text: string; cls?: string }[]; limit?: number; labels?: AgentLabels; className?: string; numbered?: boolean }): ReactElement;
113
- export function StepRow(props: { item: ToolItem; labels?: AgentLabels; defaultOpen?: boolean }): ReactElement;
121
+ /** A call the host shows in a place of its own: a handler for the calls it opens (a browser step opens
122
+ * the browser beside the conversation), null for the rest, which unfold to their input and output. */
123
+ export type OpenStep = (item: ToolItem, d: ToolDescription) => (() => void) | null | undefined;
124
+ export function StepRow(props: { item: ToolItem; labels?: AgentLabels; defaultOpen?: boolean; element?: BrowserElement | null;
125
+ openStep?: OpenStep; active?: boolean }): ReactElement;
114
126
  export function ThinkingRow(props: { item: ThinkingItem; labels?: AgentLabels }): ReactElement;
115
127
  export function WorkGroup(props: MarkProps & { items: (ToolItem | ThinkingItem)[]; live?: boolean; liveLabel?: string; start?: number | null;
116
- labels?: AgentLabels; defaultOpen?: boolean }): ReactElement | null;
128
+ labels?: AgentLabels; defaultOpen?: boolean; elements?: Record<string, BrowserElement> | null; openStep?: OpenStep; activeStep?: string | null }): ReactElement | null;
117
129
  export function TodoCard(props: { todos: TodoEntry[] | null; labels?: AgentLabels; running?: boolean }): ReactElement | null;
118
130
  export function StreamingText(props: { text: string; active?: boolean; render?: (text: string) => ReactNode }): ReactElement;
119
131
  export function UserBubble(props: { user: TurnUser | null; renderFile?: (f: { name: string; src?: string }, i: number) => ReactNode; extra?: ReactNode }): ReactElement | null;
@@ -136,6 +148,10 @@ export interface AgentTurnViewProps extends MarkProps {
136
148
  describeIncomplete?: (i: { reason?: string; detail?: string }) => string;
137
149
  /** the epoch ms the live clock counts from, when it is not the turn's own startedAt */
138
150
  liveStart?: number | null;
151
+ /** calls the host opens in a place of its own (a browser step opens the browser), instead of unfolding */
152
+ openStep?: OpenStep;
153
+ /** the id of the call the host is showing now: its row stays marked */
154
+ activeStep?: string | null;
139
155
  }
140
156
  export function AgentTurnView(props: AgentTurnViewProps): ReactElement | null;
141
157
 
@@ -189,7 +205,15 @@ export interface AgentConversationProps extends MarkProps {
189
205
  }
190
206
  export function AgentConversation(props: AgentConversationProps): ReactElement;
191
207
 
192
- export interface ArtifactFile { key: string; name: string; url: string }
208
+ export interface ArtifactFile {
209
+ key: string; name: string; url: string;
210
+ /** where it sits in the workspace (files are grouped by its folder) */
211
+ path?: string;
212
+ /** bytes, when known */
213
+ size?: number;
214
+ /** the turn that made it (1-based), when known */
215
+ turn?: number;
216
+ }
193
217
  export interface ArtifactPanelProps {
194
218
  files: ArtifactFile[];
195
219
  /** the key of the file shown (default: the first) */
@@ -199,6 +223,8 @@ export interface ArtifactPanelProps {
199
223
  /** a drawer over the page from the right (a narrow screen) instead of a docked column */
200
224
  overlay?: boolean;
201
225
  label?: string;
226
+ /** the words for "made in turn n" in the file list (default "Turn n") */
227
+ turnLabel?: (n: number) => string;
202
228
  fetchFile?: (url: string) => Promise<Response>;
203
229
  renderMarkdown?: (text: string) => ReactNode;
204
230
  officePdfUrl?: (url: string) => string;
@@ -207,6 +233,13 @@ export interface ArtifactPanelProps {
207
233
  className?: string;
208
234
  }
209
235
  export function ArtifactPanel(props: ArtifactPanelProps): ReactElement | null;
236
+ /** The preview header's file name as a dropdown of every file (ArtifactPanel uses it). */
237
+ export function FileSwitcher(props: { files: Omit<ArtifactFile, 'url'>[]; current: string; onSelect?: (key: string) => void; label?: string;
238
+ turnLabel?: (n: number) => string }): ReactElement | null;
239
+ /** "epsilla-enterprise-subscr…store-v2.png": the start and the end of a long name. */
240
+ export function middleEllipsis(name: string, max?: number): string;
241
+ /** A name truncated in the middle at whatever width it is given: the end always shows. */
242
+ export function MidName(props: { name: string; className?: string }): ReactElement;
210
243
  export interface FileCardProps {
211
244
  name: string; origin?: string; bytes?: number;
212
245
  onPreview?: () => void; onDownload?: () => void;
@@ -223,4 +256,6 @@ export function FilePreview(props: {
223
256
  file: { url: string; name: string } | null; onClose?: () => void; fetchFile?: (url: string) => Promise<Response>;
224
257
  officePdfUrl?: (url: string) => string; renderMarkdown?: (text: string) => ReactNode;
225
258
  parseWorkbook?: ArtifactPanelProps['parseWorkbook']; onDownload?: (url: string, name: string) => void; title?: string; before?: ReactNode;
259
+ /** a control in the name's place in the header row (a file switcher) */
260
+ nameSlot?: ReactNode;
226
261
  }): ReactElement;
@@ -3,7 +3,7 @@
3
3
  // the data newTurn, reduceTurn, finish, turnFromEvents, turnFromResponse, turnFromHistory,
4
4
  // turnFromMessage, liveState, segments, latestPlan, isTerminal
5
5
  // the words describeTool, toolKind, toolLine, summarizeCalls, resultNote, parseToolArgs,
6
- // todosOf, diffOf, patchStats, commandText
6
+ // todosOf, diffOf, patchStats, commandText, browserActOf, browserElements
7
7
  // the clocks formatElapsed, formatDuration, formatTokens, useElapsed, useNow
8
8
  // the marks MARK_MOTIONS, MOTIONS, motionFor
9
9
  // the views AgentConversation, AgentTurnView, WorkGroup, StepRow, ThinkingRow, TodoCard,
@@ -17,13 +17,13 @@
17
17
  export { newTurn, reduceTurn, finish, turnFromEvents, turnFromResponse, turnFromHistory, turnFromMessage,
18
18
  liveState, segments, latestPlan, isTerminal } from './turn.js';
19
19
  export { describeTool, toolKind, toolLine, summarizeCalls, resultNote, parseToolArgs, todosOf, diffOf, patchStats,
20
- commandText, baseNameOf, lineCount } from './tools.js';
20
+ commandText, baseNameOf, lineCount, browserActOf, browserElements } from './tools.js';
21
21
  export { formatElapsed, formatDuration, formatTokens, useElapsed, useNow } from './time.js';
22
22
  export { MARK_MOTIONS, MOTIONS, motionFor } from './marks.js';
23
23
  export { AgentConversation, AgentTurnView, WorkGroup, StepRow, ThinkingRow, TodoCard, WorkingIndicator, WorkingMark,
24
24
  StreamingText, TurnOutcome, UserBubble, AgentComposer, CopyButton, DiffBadge, LinesBlock, useStickToBottom,
25
25
  DEFAULT_AGENT_LABELS } from './components.jsx';
26
26
  // the files a turn made: cards in the conversation (FileCard), opened beside it (ArtifactPanel)
27
- export { ArtifactPanel } from './artifacts.jsx';
27
+ export { ArtifactPanel, FileSwitcher, MidName, middleEllipsis } from './artifacts.jsx';
28
28
  export { FileCard } from '../components/FileCard.jsx';
29
29
  export { FilePreview } from '../components/FilePreview.jsx';