polaroid

1import type { EngineInterface, Register } from 'claude-code'
2
3import { clip, costOf, tokensOf } from './lib/kz.ts'
4import { addTokens, buildHtml, buildMarkdown, emptyReport, familyOf, fileTouch, joinPath, reportStem } from './report.ts'
5import type { ReportAgent, ReportData, ReportFile, ReportLimit } from './report.ts'
6
7// The live collector. Module state starts over on a reload; session.start resets it.
8let data: ReportData = emptyReport(0)
9let openTurn: { index: number; prompt: string; startedAt: number; tools: number } | null = null
10let agents = new Map<string, ReportAgent>()
11let files = new Map<string, ReportFile>()
12let limits = new Map<string, ReportLimit>()
13let lastCtx = -1
14
15const MAX_SERIES = 360
16const MAX_COMMANDS = 200
17const MAX_TURNS = 500
18
19function reset(now: number): void {
20  data = emptyReport(now)
21  openTurn = null
22  agents = new Map()
23  files = new Map()
24  limits = new Map()
25  lastCtx = -1
26}
27
28function noteModel(model: string): void {
29  if (!model) return
30  if (!data.model) data.model = model
31  if (!data.models.includes(model)) data.models.push(model)
32}
33
34function noteContext(at: number, percent: number | undefined, tokens: number | undefined, window: number): void {
35  if (percent === undefined) return
36  data.ctxWindow = window
37  if (data.ctxPeakPercent === undefined || percent >= data.ctxPeakPercent) {
38    data.ctxPeakPercent = percent
39    data.ctxPeakTokens = tokens
40  }
41  if (Math.abs(percent - lastCtx) < 0.5) return
42  lastCtx = percent
43  data.ctxSeries.push([Math.max(0, at - data.startedAt), percent])
44  // Keep the series bounded: drop every other point of the older half.
45  if (data.ctxSeries.length > MAX_SERIES) {
46    const half = Math.floor(data.ctxSeries.length / 2)
47    data.ctxSeries = [...data.ctxSeries.slice(0, half).filter((_, i) => i % 2 === 0), ...data.ctxSeries.slice(half)]
48  }
49}
50
51function noteLimits(rateLimits: readonly { kind: string; percentUsed: number; resetsAt?: string }[]): void {
52  for (const l of rateLimits) {
53    const prev = limits.get(l.kind)
54    limits.set(l.kind, { kind: l.kind, percentUsed: l.percentUsed, peak: Math.max(prev?.peak ?? 0, l.percentUsed), resetsAt: l.resetsAt })
55  }
56}
57
58/** Reads what the engine knows now and freezes the report at this moment. */
59async function snapshot($: EngineInterface): Promise<ReportData> {
60  const now = await $.clock.now()
61  try {
62    const usage = await $.session.usage()
63    data.startedAt = Math.min(data.startedAt, usage.startedAt || data.startedAt)
64    data.costUsd = usage.cost?.usd
65    noteContext(now, usage.context.percent, usage.context.tokens, usage.context.window)
66    noteLimits(usage.rateLimits)
67  } catch {
68    // Keep what the hooks collected.
69  }
70  try {
71    const model = await $.session.model()
72    noteModel(model)
73    if (model) data.model = model
74  } catch {
75    // The first model seen stands.
76  }
77  try {
78    data.version = (await $.session.version()).version
79  } catch {
80    // Unknown version.
81  }
82  try {
83    data.root = await $.session.root()
84  } catch {
85    // No root known.
86  }
87  const turns = [...data.turns]
88  if (openTurn) {
89    turns.push({ index: openTurn.index, prompt: openTurn.prompt, startedAt: openTurn.startedAt, durationMs: now - openTurn.startedAt, tools: openTurn.tools, tokens: 0, usd: 0, reason: 'running' })
90  }
91  return {
92    ...data,
93    endedAt: now,
94    turns,
95    agents: [...agents.values()].map(a => (a.status === 'running' ? { ...a, durationMs: now - a.startedAt } : a)),
96    files: [...files.values()],
97    limits: [...limits.values()],
98    families: { ...data.families },
99    toolNames: { ...data.toolNames },
100    commands: [...data.commands],
101    ctxSeries: [...data.ctxSeries],
102    models: [...data.models],
103  }
104}
105
106async function shoot($: EngineInterface, format: 'html' | 'md'): Promise<string> {
107  const report = await snapshot($)
108  const now = report.endedAt
109  const root = report.root || (await $.session.cwd())
110  const path = joinPath(root, '.kozmos', 'reports', `${reportStem(now)}.${format}`)
111  await $.fs.write(path, format === 'html' ? buildHtml(report, now) : buildMarkdown(report, now))
112  let copied = false
113  try {
114    copied = (await $.ui.copy({ text: path })).isCopied === true
115  } catch {
116    copied = false
117  }
118  return `Polaroid ${format === 'html' ? 'report' : 'Markdown'} saved: ${path}${copied ? '\n(path copied to the clipboard)' : ''}`
119}
120
121export const register: Register = on => {
122  on('session.start', async ($, e, next) => {
123    const started = await next(e)
124    reset(await $.clock.now())
125    await $.command.register({
126      name: 'polaroid',
127      description: 'KOZMOS: snapshot this session as a self-contained HTML report in .kozmos/reports (/polaroid md for Markdown)',
128      argumentHint: '[md]',
129      immediate: true,
130    })
131    return started
132  })
133
134  on('command.run', { command: 'polaroid' }, async ($, e) => {
135    const arg = e.args.trim().toLowerCase()
136    const format = arg === 'md' || arg === 'markdown' ? 'md' : 'html'
137    try {
138      return { text: await shoot($, format) }
139    } catch (err) {
140      // The engine rejects its calls with an Error, and so does the code above.
141      return { text: `Polaroid could not write the report: ${(err as Error).message}` }
142    }
143  })
144
145  on('command.run', async ($, e, next) => {
146    if (e.command !== 'polaroid' && data.commands.length < MAX_COMMANDS) {
147      data.commands.push({ name: e.command, args: clip(e.args, 120), at: await $.clock.now() })
148    }
149    return next(e)
150  }).catch(($, e, next) => next(e))
151
152  on('turn.start', async ($, e, next) => {
153    const at = await $.clock.now()
154    const prompt = clip(e.text, 200)
155    if (!data.title && prompt) data.title = clip(prompt, 80)
156    openTurn = { index: data.turns.length + 1, prompt, startedAt: at, tools: 0 }
157    return next(e)
158  })
159
160  on('turn.step', async function* ($, e, next) {
161    noteModel(e.model)
162    const r = yield* next(e)
163    if (r.usage) {
164      data.tokens = addTokens(data.tokens, r.usage)
165      data.requests++
166    }
167    return r
168  })
169
170  on('turn.complete', async ($, e, next) => {
171    const at = await $.clock.now()
172    const usd = e.usage ? costOf(e.usage.model, e.usage) : 0
173    const tokens = e.usage ? tokensOf(e.usage) : 0
174    if (e.agentId === undefined) {
175      if (openTurn && data.turns.length < MAX_TURNS) {
176        data.turns.push({ index: openTurn.index, prompt: openTurn.prompt, startedAt: openTurn.startedAt, durationMs: e.durationMs, tools: openTurn.tools, tokens, usd, reason: e.reason })
177      }
178      openTurn = null
179    } else {
180      const a = agents.get(e.agentId)
181      if (a) {
182        a.durationMs = Math.max(a.durationMs, at - a.startedAt)
183        a.tokens += tokens
184        a.usd += usd
185        a.status = e.reason === 'answer' ? 'done' : 'failed'
186      }
187    }
188    return next(e)
189  }).catch(($, e, next) => next(e))
190
191  on('agent.spawn', async ($, e, next) => {
192    const at = await $.clock.now()
193    const r = await next(e)
194    if (r.deny === undefined && r.agentId) {
195      agents.set(r.agentId, { id: r.agentId, type: e.subagentType, description: clip(e.description, 80), model: r.model, startedAt: at, durationMs: 0, tokens: 0, usd: 0, status: 'running' })
196    }
197    return r
198  }).catch(($, e, next) => next(e))
199
200  on('tool.call', async ($, e, next) => {
201    const tool = String(e.tool)
202    const fam = familyOf(tool)
203    data.families[fam] = (data.families[fam] ?? 0) + 1
204    data.toolNames[tool] = (data.toolNames[tool] ?? 0) + 1
205    if (e.agentId === undefined && openTurn) openTurn.tools++
206    const touch = fileTouch(tool, e as unknown as Record<string, unknown>)
207    if (touch) {
208      const f = files.get(touch.path) ?? { path: touch.path, reads: 0, edits: 0, writes: 0 }
209      f[touch.kind]++
210      files.set(touch.path, f)
211    }
212    const ran = await next(e)
213    if (ran.isError === true || ran.deny !== undefined) data.toolErrors++
214    return ran
215  }).catch(($, e, next) => next(e))
216
217  on('session.measure', async ($, e, next) => {
218    const at = await $.clock.now()
219    noteContext(at, e.context.percent, e.context.tokens, e.context.window)
220    noteLimits(e.rateLimits)
221    if (e.cost) data.costUsd = e.cost.usd
222    return next(e)
223  })
224}
225

1// GENERATED by scripts/sync-shared.mjs from shared/kz.ts. Do not edit here.
2// KOZMOS shared kit. Source of truth: shared/kz.ts at the bundle root.
3// `node scripts/sync-shared.mjs` copies it into every mod as hooks/lib/kz.ts,
4// because a hooks module may only import files inside its own plugin.
5// Edit the root copy, never a mod's copy.
6
7// ---------------------------------------------------------------------------
8// Palette: one neon family across every KOZMOS mod.
9
10export const KZ = {
11  violet: '#a78bfa',
12  magenta: '#f472b6',
13  cyan: '#22d3ee',
14  teal: '#2dd4bf',
15  green: '#4ade80',
16  lime: '#a3e635',
17  yellow: '#facc15',
18  amber: '#fb923c',
19  red: '#f87171',
20  blue: '#60a5fa',
21  clay: '#d97757',
22  ink: '#1f1e1d',
23  mist: '#9ca3af',
24} as const
25
26/** Tool families, colored the same in every mod. */
27export function toolColor(tool: string): string {
28  const t = String(tool)
29  if (t === 'Bash' || t === 'PowerShell') return KZ.green
30  if (t === 'Edit' || t === 'Write' || t === 'NotebookEdit' || t === 'MultiEdit') return KZ.yellow
31  if (t === 'Read' || t === 'Glob' || t === 'Grep' || t === 'LSP') return KZ.blue
32  if (t === 'Agent' || t === 'Task' || t === 'Workflow') return KZ.violet
33  if (t.startsWith('Web')) return KZ.cyan
34  if (t.startsWith('Todo') || t.startsWith('Task')) return KZ.teal
35  if (t.startsWith('mcp__')) return KZ.magenta
36  return KZ.mist
37}
38
39/** A short glyph per tool family. */
40export function toolGlyph(tool: string): string {
41  const t = String(tool)
42  if (t === 'Bash' || t === 'PowerShell') return '$'
43  if (t === 'Edit' || t === 'Write' || t === 'NotebookEdit') return '✎'
44  if (t === 'Read') return '◉'
45  if (t === 'Glob' || t === 'Grep') return '⌕'
46  if (t === 'Agent') return '◈'
47  if (t.startsWith('Web')) return '◍'
48  if (t.startsWith('Todo') || t.startsWith('Task')) return '☑'
49  if (t.startsWith('mcp__')) return '⬡'
50  return '•'
51}
52
53// ---------------------------------------------------------------------------
54// Colors.
55
56export function hexToRgb(hex: string): [number, number, number] {
57  const h = hex.replace('#', '')
58  const n = parseInt(h.length === 3 ? h.split('').map(c => c + c).join('') : h, 16)
59  return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
60}
61
62export function rgbToHex(r: number, g: number, b: number): string {
63  const c = (v: number) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')
64  return `#${c(r)}${c(g)}${c(b)}`
65}
66
67export function mix(a: string, b: string, t: number): string {
68  const [r1, g1, b1] = hexToRgb(a)
69  const [r2, g2, b2] = hexToRgb(b)
70  const k = clamp01(t)
71  return rgbToHex(r1 + (r2 - r1) * k, g1 + (g2 - g1) * k, b1 + (b2 - b1) * k)
72}
73
74/** Green at 0, yellow at 0.6, red at 1: the heat of a gauge. */
75export function heat(t: number): string {
76  const k = clamp01(t)
77  return k < 0.6 ? mix(KZ.green, KZ.yellow, k / 0.6) : mix(KZ.yellow, KZ.red, (k - 0.6) / 0.4)
78}
79
80/** A smooth rainbow for hues 0..1 (for auroras, plasma and the like). */
81export function hue(h: number, s = 0.75, l = 0.6): string {
82  const k = ((h % 1) + 1) % 1
83  const a = s * Math.min(l, 1 - l)
84  const f = (n: number) => {
85    const x = (n + k * 12) % 12
86    return l - a * Math.max(-1, Math.min(x - 3, 9 - x, 1))
87  }
88  return rgbToHex(f(0) * 255, f(8) * 255, f(4) * 255)
89}
90
91export function hexToInt(hex: string): number {
92  const [r, g, b] = hexToRgb(hex)
93  return (r << 16) | (g << 8) | b
94}
95
96// ---------------------------------------------------------------------------
97// Numbers and text.
98
99export const clamp01 = (v: number): number => (Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : 0)
100
101export function fmtTokens(n: number): string {
102  if (!Number.isFinite(n)) return '—'
103  // Each unit starts where the one below would round up to 1000 of itself.
104  if (n >= 999.5e6) return `${(n / 1e9).toFixed(1)}B`
105  if (n >= 999_500) return `${(n / 1e6).toFixed(n >= 1e7 ? 0 : 1)}M`
106  if (n >= 999.5) return `${(n / 1e3).toFixed(n >= 1e4 ? 0 : 1)}k`
107  return `${Math.round(n)}`
108}
109
110export function fmtUsd(usd: number): string {
111  if (!Number.isFinite(usd)) return '$—'
112  if (usd < 0.01 && usd > 0) return '<$0.01'
113  return usd < 100 ? `$${usd.toFixed(2)}` : `$${Math.round(usd)}`
114}
115
116/** 0:42, 3:07, 1:02:33. */
117export function fmtClock(ms: number): string {
118  const s = Math.max(0, Math.round(ms / 1000))
119  const h = Math.floor(s / 3600)
120  const m = Math.floor((s % 3600) / 60)
121  const ss = String(s % 60).padStart(2, '0')
122  return h ? `${h}:${String(m).padStart(2, '0')}:${ss}` : `${m}:${ss}`
123}
124
125/** 42s, 7m, 2h41m, 3d4h: compact durations for countdowns. */
126export function fmtSpan(ms: number): string {
127  const s = Math.max(0, Math.round(ms / 1000))
128  if (s < 60) return `${s}s`
129  const m = Math.floor(s / 60)
130  if (m < 60) return `${m}m`
131  const h = Math.floor(m / 60)
132  if (h < 48) return `${h}h${String(m % 60).padStart(2, '0')}m`
133  return `${Math.floor(h / 24)}d${h % 24}h`
134}
135
136export function fmtPct(p: number | undefined): string {
137  return p === undefined || !Number.isFinite(p) ? '—' : `${Math.round(p)}%`
138}
139
140export function clip(s: string, max: number): string {
141  const one = s.replace(/\s+/g, ' ').trim()
142  return one.length > max ? one.slice(0, Math.max(1, max - 1)) + '…' : one
143}
144
145export function padEnd(s: string, n: number): string {
146  return s.length >= n ? s.slice(0, n) : s + ' '.repeat(n - s.length)
147}
148
149export function padStart(s: string, n: number): string {
150  return s.length >= n ? s.slice(s.length - n) : ' '.repeat(n - s.length) + s
151}
152
153/** `claude-opus-5-5[1m]` → `Opus 5.5`. */
154export function modelName(id: string | undefined): string {
155  if (!id) return '—'
156  const m = /(fable|mythos|opus|sonnet|haiku)-(\d+)(?:-(\d{1,2})(?!\d))?/i.exec(id)
157  if (!m) return id.replace(/^claude-/, '').replace(/\[.*\]$/, '')
158  const fam = m[1]!
159  return `${fam.charAt(0).toUpperCase()}${fam.slice(1).toLowerCase()} ${m[2]}${m[3] ? '.' + m[3] : ''}`
160}
161
162/** Last path segment, either slash. */
163export function baseName(p: string): string {
164  const parts = p.split(/[\\/]/).filter(Boolean)
165  return parts[parts.length - 1] ?? p
166}
167
168/** A stable small hash for seeding. */
169export function hash(s: string): number {
170  let h = 2166136261
171  for (let i = 0; i < s.length; i++) {
172    h ^= s.charCodeAt(i)
173    h = Math.imul(h, 16777619)
174  }
175  return h >>> 0
176}
177
178/** Deterministic 0..1 noise from two ints. */
179export function noise(x: number, y: number): number {
180  const s = Math.sin(x * 12.9898 + y * 78.233) * 43758.5453
181  return s - Math.floor(s)
182}
183
184/** A seeded PRNG (mulberry32). */
185export function rng(seed: number): () => number {
186  let a = seed >>> 0
187  return () => {
188    a = (a + 0x6d2b79f5) >>> 0
189    let t = a
190    t = Math.imul(t ^ (t >>> 15), t | 1)
191    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
192    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
193  }
194}
195
196// ---------------------------------------------------------------------------
197// Text gauges for the terminal.
198
199const EIGHTHS = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉']
200
201/** A smooth bar with eighth blocks: `█████▍    `. */
202export function bar(ratio: number, width: number, empty = '░'): string {
203  const w = Math.max(1, Math.floor(width))
204  const exact = clamp01(ratio) * w
205  const full = Math.floor(exact)
206  const part = EIGHTHS[Math.floor((exact - full) * 8)] ?? ''
207  const used = full + (part ? 1 : 0)
208  return '█'.repeat(full) + part + empty.repeat(Math.max(0, w - used))
209}
210
211/** A segmented gauge: `▰▰▰▱▱▱`. */
212export function pips(ratio: number, width: number, on = '▰', off = '▱'): string {
213  const w = Math.max(1, Math.floor(width))
214  const n = Math.round(clamp01(ratio) * w)
215  return on.repeat(n) + off.repeat(w - n)
216}
217
218const SPARK = '▁▂▃▄▅▆▇█'
219
220/** A sparkline of the last `width` values, scaled to their own max (or `max`). */
221export function sparkline(values: readonly number[], width: number, max?: number): string {
222  const tail = values.slice(-Math.max(1, width))
223  const top = max ?? Math.max(1e-9, ...tail)
224  const line = tail.map(v => SPARK[Math.min(7, Math.max(0, Math.round((v / top) * 7)))] ?? '▁').join('')
225  return line.padStart(width, ' ')
226}
227
228/** Braille line graph, 2 samples per cell, `rows` cells tall. */
229export function brailleGraph(values: readonly number[], width: number, rows: number, max?: number): string[] {
230  const samples = values.slice(-(width * 2))
231  const top = max ?? Math.max(1e-9, ...samples)
232  const dotsTall = rows * 4
233  const grid: number[][] = Array.from({ length: rows }, () => Array.from({ length: width }, () => 0))
234  const offset = width * 2 - samples.length
235  // Dot bits per column, from the bottom row of a cell up.
236  const LEFT = [0x40, 0x04, 0x02, 0x01]
237  const RIGHT = [0x80, 0x20, 0x10, 0x08]
238  samples.forEach((v, i) => {
239    const x = offset + i
240    const col = Math.floor(x / 2)
241    const isRight = x % 2 === 1
242    const h = Math.round(clamp01(v / top) * (dotsTall - 1))
243    for (let d = 0; d <= h; d++) {
244      const row = rows - 1 - Math.floor(d / 4)
245      const bits = isRight ? RIGHT : LEFT
246      const cellRow = grid[row]
247      if (cellRow && col >= 0) cellRow[col] = (cellRow[col] ?? 0) | bits[d % 4]!
248    }
249  })
250  return grid.map(r => r.map(b => String.fromCharCode(0x2800 + b)).join(''))
251}
252
253// ---------------------------------------------------------------------------
254// Raster: a grid of colored cells, packed as the engine wants it.
255
256const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
257
258export function toBase64(bytes: Uint8Array): string {
259  let out = ''
260  let i = 0
261  for (; i + 2 < bytes.length; i += 3) {
262    const n = (bytes[i]! << 16) | (bytes[i + 1]! << 8) | bytes[i + 2]!
263    out += B64[(n >> 18) & 63]! + B64[(n >> 12) & 63]! + B64[(n >> 6) & 63]! + B64[n & 63]!
264  }
265  const rest = bytes.length - i
266  if (rest === 1) {
267    const n = bytes[i]! << 16
268    out += B64[(n >> 18) & 63]! + B64[(n >> 12) & 63]! + '=='
269  } else if (rest === 2) {
270    const n = (bytes[i]! << 16) | (bytes[i + 1]! << 8)
271    out += B64[(n >> 18) & 63]! + B64[(n >> 12) & 63]! + B64[(n >> 6) & 63]! + '='
272  }
273  return out
274}
275
276/** The terminal's own default color, for a cell's foreground or background. */
277export const DEFAULT_COLOR = 0x01000000
278
279export class Canvas {
280  readonly cols: number
281  readonly rows: number
282  private readonly words: Uint32Array
283
284  constructor(cols: number, rows: number) {
285    this.cols = Math.max(1, Math.min(512, Math.floor(cols)))
286    this.rows = Math.max(1, Math.min(256, Math.floor(rows)))
287    this.words = new Uint32Array(this.cols * this.rows * 3)
288    this.clear()
289  }
290
291  clear(bg: number = DEFAULT_COLOR): void {
292    for (let i = 0; i < this.cols * this.rows; i++) {
293      this.words[i * 3] = 0x20
294      this.words[i * 3 + 1] = DEFAULT_COLOR
295      this.words[i * 3 + 2] = bg
296    }
297  }
298
299  /** Puts one width-1 character; colors are '#rrggbb' or a packed int. */
300  set(x: number, y: number, ch: string, fg?: string | number, bg?: string | number): void {
301    const cx = Math.floor(x)
302    const cy = Math.floor(y)
303    if (cx < 0 || cy < 0 || cx >= this.cols || cy >= this.rows) return
304    const i = (cy * this.cols + cx) * 3
305    const code = ch.codePointAt(0) ?? 0x20
306    this.words[i] = code > 0xffff || code < 0x20 ? 0x20 : code
307    if (fg !== undefined) this.words[i + 1] = typeof fg === 'number' ? fg : hexToInt(fg)
308    if (bg !== undefined) this.words[i + 2] = typeof bg === 'number' ? bg : hexToInt(bg)
309  }
310
311  /** Writes a string left to right, clipped to the canvas. */
312  text(x: number, y: number, s: string, fg?: string | number, bg?: string | number): void {
313    let cx = x
314    for (const ch of s) {
315      this.set(cx, y, ch, fg, bg)
316      cx++
317    }
318  }
319
320  /** Paints a cell's background only, keeping its character. */
321  paint(x: number, y: number, bg: string | number): void {
322    const cx = Math.floor(x)
323    const cy = Math.floor(y)
324    if (cx < 0 || cy < 0 || cx >= this.cols || cy >= this.rows) return
325    this.words[(cy * this.cols + cx) * 3 + 2] = typeof bg === 'number' ? bg : hexToInt(bg)
326  }
327
328  /** Two vertical pixels per cell with the upper-half block: `py` is in half-cells. */
329  pixel(x: number, py: number, color: string): void {
330    const cx = Math.floor(x)
331    const cy = Math.floor(py / 2)
332    if (cx < 0 || cy < 0 || cx >= this.cols || cy >= this.rows) return
333    const i = (cy * this.cols + cx) * 3
334    const c = hexToInt(color)
335    const isTop = Math.floor(py) % 2 === 0
336    if (this.words[i] !== 0x2580) {
337      this.words[i] = 0x2580
338      this.words[i + 1] = DEFAULT_COLOR
339      this.words[i + 2] = DEFAULT_COLOR
340    }
341    if (isTop) this.words[i + 1] = c
342    else this.words[i + 2] = c
343  }
344
345  /** The `cells` prop of a Raster. */
346  encode(): string {
347    return toBase64(new Uint8Array(this.words.buffer))
348  }
349}
350
351// ---------------------------------------------------------------------------
352// SVG for the desktop: one drawing per row (the desktop wraps siblings).
353
354export const FONT = "-apple-system,BlinkMacSystemFont,'Segoe UI',Inter,sans-serif"
355export const MONO = "ui-monospace,'Cascadia Code','SF Mono',Consolas,monospace"
356
357const XML_ESC: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }
358
359export function xml(s: string): string {
360  return s.replace(/[&<>"']/g, c => XML_ESC[c]!)
361}
362
363/** Theme-aware classes every KOZMOS drawing shares: t text, s secondary, m muted, k track, p panel. */
364export const SVG_BASE_CSS = `
365.t{fill:#1f1f1f}.s{fill:#5f5f5c}.m{fill:#8e8e8a}.k{fill:#e7e5e0}.p{fill:#f5f4f1}.ln{stroke:#e1dfda}
366@media (prefers-color-scheme: dark){.t{fill:#ededed}.s{fill:#b4b4b0}.m{fill:#7c7c78}.k{fill:#2d2d2b}.p{fill:#232322}.ln{stroke:#363634}}
367.pulse{animation:kzp 1.6s ease-in-out infinite}@keyframes kzp{50%{opacity:.35}}
368.spin{transform-box:fill-box;transform-origin:center;animation:kzs 2s linear infinite}@keyframes kzs{to{transform:rotate(360deg)}}
369@media (prefers-reduced-motion: reduce){*{animation:none!important}}
370`
371
372export function svg(width: number, height: number, body: string, css = ''): string {
373  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"><style>${SVG_BASE_CSS}${css}</style>${body}</svg>`
374}
375
376/** Rough width of UI text in px, for fitting labels. */
377export function textWidth(s: string, size: number): number {
378  let w = 0
379  for (const ch of s) w += (/[\s.,:;'|!il1()[\]]/.test(ch) ? 0.3 : /[A-Z@%MWmw]/.test(ch) ? 0.72 : 0.56) * size
380  return w
381}
382
383export function fitText(s: string, size: number, maxW: number): string {
384  if (textWidth(s, size) <= maxW) return s
385  let out = ''
386  for (const ch of s) {
387    if (textWidth(out + ch + '…', size) > maxW) break
388    out += ch
389  }
390  return out + '…'
391}
392
393/** A rounded progress bar as SVG markup. */
394export function svgBar(x: number, y: number, w: number, h: number, ratio: number, color: string): string {
395  const fw = Math.max(0, Math.min(w, w * clamp01(ratio)))
396  return `<rect class="k" x="${x}" y="${y}" width="${w}" height="${h}" rx="${h / 2}"/>` +
397    (fw > 0 ? `<rect x="${x}" y="${y}" width="${Math.max(h, fw)}" height="${h}" rx="${h / 2}" fill="${color}"/>` : '')
398}
399
400/** SVG text helper. */
401export function svgText(x: number, y: number, s: string, opts: { cls?: string; size?: number; weight?: number; anchor?: 'start' | 'middle' | 'end'; fill?: string; mono?: boolean } = {}): string {
402  const { cls = 't', size = 12, weight = 400, anchor = 'start', fill, mono = false } = opts
403  return `<text ${fill ? `fill="${fill}"` : `class="${cls}"`} x="${x}" y="${y}" font-family="${mono ? MONO : FONT}" font-size="${size}" font-weight="${weight}" text-anchor="${anchor}" font-variant-numeric="tabular-nums">${xml(s)}</text>`
404}
405
406/** Pixel width a desktop pane or band gives a drawing for `columns` reported columns. */
407export function pxOf(columns: number | undefined, fallback = 60, slack = 8): number {
408  return Math.max(200, Math.min(1600, (columns || fallback) * 8 - slack))
409}
410
411// ---------------------------------------------------------------------------
412// Prices, USD per million tokens: input, output, cache read, cache write (5 min).
413// Anthropic first-party rates as of 2026-10. Used only where the engine reports
414// tokens and not money (a subagent's own spend); the session total comes from
415// $.session.usage().cost, which is the engine's.
416
417const PRICES: [RegExp, [number, number, number, number]][] = [
418  [/fable|mythos/i, [10, 50, 0.25, 12.5]],
419  [/opus-5-5/i, [4, 20, 0.2, 5]],
420  [/opus/i, [5, 25, 0.5, 6.25]],
421  [/sonnet-5/i, [2, 10, 0.2, 2.5]],
422  [/sonnet/i, [3, 15, 0.3, 3.75]],
423  [/haiku-5/i, [0.1, 0.5, 0.01, 0.125]],
424  [/haiku/i, [1, 5, 0.1, 1.25]],
425]
426
427export type Usage = {
428  input_tokens?: number
429  output_tokens?: number
430  cache_read_input_tokens?: number
431  cache_creation_input_tokens?: number
432}
433
434export function priceOf(model: string): [number, number, number, number] {
435  return PRICES.find(([re]) => re.test(model))?.[1] ?? [4, 20, 0.2, 5]
436}
437
438export function costOf(model: string, u: Usage | null | undefined): number {
439  if (!u) return 0
440  const [i, o, r, w] = priceOf(model)
441  return ((u.input_tokens ?? 0) * i + (u.output_tokens ?? 0) * o + (u.cache_read_input_tokens ?? 0) * r + (u.cache_creation_input_tokens ?? 0) * w) / 1e6
442}
443
444export function tokensOf(u: Usage | null | undefined): number {
445  if (!u) return 0
446  return (u.input_tokens ?? 0) + (u.output_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0)
447}
448
449/** The context a request filled: everything it read plus what it wrote. */
450export function contextOf(u: Usage | null | undefined): number {
451  return tokensOf(u)
452}
453
454export function windowOf(model: string): number {
455  return /haiku-4/i.test(model) ? 200_000 : 1_000_000
456}
457
458// ---------------------------------------------------------------------------
459// Rate limits.
460
461export type Limit = { kind: string; percentUsed: number; resetsAt?: string }
462
463export function limitLabel(kind: string): string {
464  if (kind === 'five_hour') return '5h'
465  if (kind === 'seven_day') return '7d'
466  if (kind === 'spend_limit') return '$'
467  return kind.replace(/_/g, ' ')
468}
469
470/** Milliseconds until a window resets, or undefined. */
471export function untilReset(l: Limit, now: number): number | undefined {
472  if (!l.resetsAt) return undefined
473  const t = Date.parse(l.resetsAt)
474  return Number.isFinite(t) ? Math.max(0, t - now) : undefined
475}
476
477/** The length of a window in ms, for burn-rate math. */
478export function windowMs(kind: string): number | undefined {
479  if (kind === 'five_hour') return 5 * 3600_000
480  if (kind === 'seven_day') return 7 * 24 * 3600_000
481  return undefined
482}
483
484// ---------------------------------------------------------------------------
485// Tool calls, described in a few words.
486
487/** What a tool call is about: the command, the file, the pattern, the agent's task. */
488export function toolDetail(tool: string, input: unknown): string {
489  const e = (input ?? {}) as Record<string, unknown>
490  const s = (k: string) => (typeof e[k] === 'string' ? (e[k] as string) : '')
491  const t = String(tool)
492  if (t === 'Bash' || t === 'PowerShell') return clip(s('description') || s('command'), 60)
493  if (s('file_path')) return baseName(s('file_path'))
494  if (s('notebook_path')) return baseName(s('notebook_path'))
495  if (t === 'Agent') return clip(s('description') || s('subagent_type'), 60)
496  if (s('pattern')) return clip(s('pattern'), 60)
497  if (s('url')) return clip(s('url').replace(/^https?:\/\//, ''), 60)
498  if (s('query')) return clip(s('query'), 60)
499  if (s('subject')) return clip(s('subject'), 60)
500  if (Array.isArray(e.todos)) return `${(e.todos as unknown[]).length} todos`
501  if (t.startsWith('mcp__')) return t.split('__').slice(1).join(' · ')
502  return ''
503}
504
505/** `mcp__server__tool` → `server·tool`; built-ins unchanged. */
506export function toolName(tool: string): string {
507  const t = String(tool)
508  return t.startsWith('mcp__') ? t.split('__').slice(1).join('·') : t
509}
510

1// Polaroid's pure side: the session data it collects and the two documents it
2// writes from it, a self-contained HTML page and a Markdown file. No `$` here.
3
4import { KZ, clamp01, fmtClock, fmtTokens, fmtUsd, hash, limitLabel, modelName, rng } from './lib/kz.ts'
5import type { Usage } from './lib/kz.ts'
6
7export type ReportTurn = {
8  index: number
9  prompt: string
10  startedAt: number
11  durationMs: number
12  tools: number
13  tokens: number
14  usd: number
15  reason: string
16}
17
18export type ReportAgent = {
19  id: string
20  type: string
21  description: string
22  model: string
23  startedAt: number
24  durationMs: number
25  tokens: number
26  usd: number
27  status: 'running' | 'done' | 'failed'
28}
29
30export type ReportFile = { path: string; reads: number; edits: number; writes: number }
31export type ReportLimit = { kind: string; percentUsed: number; peak: number; resetsAt?: string }
32export type ReportCommand = { name: string; args: string; at: number }
33export type TokenSums = { input: number; output: number; cacheRead: number; cacheWrite: number }
34
35export type ReportData = {
36  title: string
37  model: string
38  models: string[]
39  version: string
40  root: string
41  startedAt: number
42  endedAt: number
43  costUsd?: number
44  tokens: TokenSums
45  requests: number
46  ctxPeakPercent?: number
47  ctxPeakTokens?: number
48  ctxWindow?: number
49  /** [ms since start, percent] samples. */
50  ctxSeries: [number, number][]
51  limits: ReportLimit[]
52  families: Record<string, number>
53  toolNames: Record<string, number>
54  toolErrors: number
55  turns: ReportTurn[]
56  agents: ReportAgent[]
57  files: ReportFile[]
58  commands: ReportCommand[]
59}
60
61export function emptyReport(now: number): ReportData {
62  return {
63    title: '',
64    model: '',
65    models: [],
66    version: '',
67    root: '',
68    startedAt: now,
69    endedAt: now,
70    tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
71    requests: 0,
72    ctxSeries: [],
73    limits: [],
74    families: {},
75    toolNames: {},
76    toolErrors: 0,
77    turns: [],
78    agents: [],
79    files: [],
80    commands: [],
81  }
82}
83
84// ---------------------------------------------------------------------------
85// Small facts.
86
87export const FAMILY_COLOR: Record<string, string> = {
88  shell: KZ.green,
89  edit: KZ.yellow,
90  read: KZ.blue,
91  search: KZ.teal,
92  agent: KZ.violet,
93  web: KZ.cyan,
94  tasks: KZ.lime,
95  skill: KZ.amber,
96  mcp: KZ.magenta,
97  other: KZ.mist,
98}
99
100export function familyOf(tool: string): string {
101  const t = String(tool)
102  if (t.startsWith('mcp__')) return 'mcp'
103  if (t === 'Bash' || t === 'PowerShell' || t === 'Monitor') return 'shell'
104  if (t === 'Edit' || t === 'Write' || t === 'NotebookEdit' || t === 'MultiEdit') return 'edit'
105  if (t === 'Read' || t === 'LSP') return 'read'
106  if (t === 'Glob' || t === 'Grep' || t === 'ToolSearch') return 'search'
107  if (t === 'Agent' || t === 'Task' || t === 'Workflow' || t === 'SendMessage') return 'agent'
108  if (t.startsWith('Web')) return 'web'
109  if (t.startsWith('Todo') || t.startsWith('Task')) return 'tasks'
110  if (t === 'Skill') return 'skill'
111  return 'other'
112}
113
114/** How a tool call touches a file, if it does. */
115export function fileTouch(tool: string, input: Record<string, unknown>): { path: string; kind: 'reads' | 'edits' | 'writes' } | undefined {
116  const path = typeof input.file_path === 'string' ? input.file_path : typeof input.notebook_path === 'string' ? input.notebook_path : ''
117  if (!path) return undefined
118  if (tool === 'Read') return { path, kind: 'reads' }
119  if (tool === 'Write') return { path, kind: 'writes' }
120  if (tool === 'Edit' || tool === 'MultiEdit' || tool === 'NotebookEdit') return { path, kind: 'edits' }
121  return undefined
122}
123
124export function addTokens(sum: TokenSums, u: Usage | null | undefined): TokenSums {
125  if (!u) return sum
126  return {
127    input: sum.input + (u.input_tokens ?? 0),
128    output: sum.output + (u.output_tokens ?? 0),
129    cacheRead: sum.cacheRead + (u.cache_read_input_tokens ?? 0),
130    cacheWrite: sum.cacheWrite + (u.cache_creation_input_tokens ?? 0),
131  }
132}
133
134export const totalTokens = (t: TokenSums): number => t.input + t.output + t.cacheRead + t.cacheWrite
135
136const pad2 = (n: number): string => String(n).padStart(2, '0')
137
138/** `session-20261009-143205` from a timestamp, in local time. */
139export function reportStem(at: number): string {
140  const d = new Date(at)
141  return `session-${d.getFullYear()}${pad2(d.getMonth() + 1)}${pad2(d.getDate())}-${pad2(d.getHours())}${pad2(d.getMinutes())}${pad2(d.getSeconds())}`
142}
143
144/** Joins onto `root` with the separator `root` already uses. */
145export function joinPath(root: string, ...parts: string[]): string {
146  const sep = root.includes('\\') && !root.includes('/') ? '\\' : '/'
147  return [root.replace(/[\\/]+$/, ''), ...parts].join(sep)
148}
149
150export function stamp(at: number): string {
151  const d = new Date(at)
152  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`
153}
154
155// ---------------------------------------------------------------------------
156// HTML.
157
158const ENTITIES: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;', '`': '&#96;' }
159
160/** Escapes text for HTML element content and quoted attribute values alike. */
161export function esc(s: unknown): string {
162  return String(s ?? '').replace(/[&<>"'`]/g, c => ENTITIES[c] as string)
163}
164
165const oneLine = (s: string, max: number): string => {
166  const t = s.replace(/\s+/g, ' ').trim()
167  return t.length > max ? `${t.slice(0, max - 1)}…` : t
168}
169
170const num = (n: number): string => n.toLocaleString('en-US')
171
172const CSS = `
173:root{--bg:#07060f;--panel:rgba(255,255,255,.035);--panel2:rgba(255,255,255,.06);--line:rgba(255,255,255,.09);--text:#eeeaff;--dim:#a29fc4;--mute:#6f6c8f;
174--violet:${KZ.violet};--magenta:${KZ.magenta};--cyan:${KZ.cyan};--green:${KZ.green};--yellow:${KZ.yellow};--amber:${KZ.amber};--red:${KZ.red};--blue:${KZ.blue}}
175*{box-sizing:border-box}
176html{background:var(--bg)}
177body{margin:0;color:var(--text);font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Inter,Roboto,sans-serif;min-height:100vh;
178background:radial-gradient(1200px 600px at 10% -10%,rgba(167,139,250,.22),transparent 60%),radial-gradient(900px 500px at 95% 0%,rgba(34,211,238,.14),transparent 60%),radial-gradient(800px 600px at 50% 110%,rgba(244,114,182,.10),transparent 60%),var(--bg)}
179main{max-width:1180px;margin:0 auto;padding:40px 20px 64px}
180h1,h2,h3{margin:0;font-weight:750;letter-spacing:-.01em}
181h2{font-size:13px;letter-spacing:.14em;text-transform:uppercase;color:var(--dim);margin-bottom:14px;display:flex;align-items:center;gap:10px}
182h2::before{content:"";width:8px;height:8px;border-radius:50%;background:var(--accent,var(--violet));box-shadow:0 0 12px var(--accent,var(--violet))}
183.mono{font-family:ui-monospace,"Cascadia Code","SF Mono",Consolas,monospace}
184.dim{color:var(--dim)}.mute{color:var(--mute)}
185.hero{display:grid;grid-template-columns:minmax(240px,320px) 1fr;gap:40px;align-items:center;margin-bottom:36px}
186.polaroid{background:#f6f2ea;padding:14px 14px 0;border-radius:4px;transform:rotate(-3deg);box-shadow:0 30px 60px rgba(0,0,0,.55),0 0 0 1px rgba(255,255,255,.4) inset,0 0 80px rgba(167,139,250,.25);transition:transform .4s}
187.polaroid:hover{transform:rotate(-1deg) scale(1.02)}
188.polaroid svg{display:block;width:100%;height:auto;border-radius:2px}
189.caption{color:#2b2540;font:22px/1.2 "Segoe Print","Bradley Hand","Comic Sans MS",cursive;padding:12px 4px 18px;text-align:center}
190.caption small{display:block;font:12px/1.4 -apple-system,"Segoe UI",sans-serif;color:#7a7390;margin-top:4px}
191.kicker{font-size:12px;letter-spacing:.3em;text-transform:uppercase;background:linear-gradient(90deg,var(--violet),var(--magenta),var(--cyan));-webkit-background-clip:text;background-clip:text;color:transparent;font-weight:800}
192.title{font-size:clamp(24px,3.4vw,38px);line-height:1.15;margin:8px 0 14px;text-shadow:0 0 40px rgba(167,139,250,.35)}
193.chips{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:22px}
194.chip{border:1px solid var(--line);background:var(--panel);border-radius:999px;padding:4px 12px;font-size:12px;color:var(--dim)}
195.chip b{color:var(--text);font-weight:650}
196.kpis{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:10px}
197.kpi{background:var(--panel);border:1px solid var(--line);border-radius:14px;padding:12px 14px;position:relative;overflow:hidden}
198.kpi::after{content:"";position:absolute;left:0;top:0;bottom:0;width:3px;background:var(--c,var(--violet));box-shadow:0 0 14px var(--c,var(--violet))}
199.kpi .k{font-size:10.5px;letter-spacing:.12em;text-transform:uppercase;color:var(--mute);font-weight:700}
200.kpi .v{font-size:22px;font-weight:780;margin-top:2px;font-variant-numeric:tabular-nums}
201.kpi .s{font-size:11.5px;color:var(--dim)}
202.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,460px),1fr));gap:18px;margin-bottom:18px}
203.card{background:linear-gradient(180deg,var(--panel2),var(--panel));border:1px solid var(--line);border-radius:18px;padding:20px;backdrop-filter:blur(6px);min-width:0}
204.card.wide{grid-column:1/-1}
205.card svg{display:block;width:100%;height:auto;overflow:visible}
206table{width:100%;border-collapse:collapse;font-size:13px}
207th{text-align:left;font-size:10.5px;letter-spacing:.12em;text-transform:uppercase;color:var(--mute);font-weight:700;padding:6px 8px;border-bottom:1px solid var(--line)}
208td{padding:7px 8px;border-bottom:1px solid rgba(255,255,255,.04);vertical-align:middle}
209tr:hover td{background:rgba(255,255,255,.025)}
210td.n{text-align:right;font-variant-numeric:tabular-nums;white-space:nowrap}
211.scroll{overflow-x:auto}
212.bar{height:6px;border-radius:3px;background:rgba(255,255,255,.07);overflow:hidden;min-width:60px}
213.bar i{display:block;height:100%;border-radius:3px;background:var(--c,var(--violet));box-shadow:0 0 10px var(--c,var(--violet))}
214.pill{display:inline-block;padding:1px 9px;border-radius:999px;font-size:11.5px;font-weight:650;background:color-mix(in srgb,var(--c) 18%,transparent);color:var(--c)}
215.limit{margin-bottom:14px}.limit .row{display:flex;justify-content:space-between;font-size:12.5px;margin-bottom:5px}
216.limit .bar{height:9px}
217.cmds{display:flex;flex-wrap:wrap;gap:8px}
218.cmd{border:1px solid var(--line);border-radius:10px;padding:6px 10px;background:var(--panel);font-size:12.5px}
219.cmd .t{color:var(--mute);font-size:11px;margin-left:6px}
220.empty{color:var(--mute);font-style:italic;padding:8px 0}
221.legend{display:flex;flex-wrap:wrap;gap:14px;font-size:12px;color:var(--dim);margin-top:10px}
222.legend span::before{content:"";display:inline-block;width:9px;height:9px;border-radius:3px;margin-right:6px;background:var(--c)}
223footer{margin-top:36px;text-align:center;color:var(--mute);font-size:12px}
224footer b{background:linear-gradient(90deg,var(--violet),var(--cyan));-webkit-background-clip:text;background-clip:text;color:transparent}
225@media (max-width:760px){.hero{grid-template-columns:1fr}.polaroid{max-width:300px;margin:0 auto}main{padding-top:24px}}
226@media (max-width:460px){.kpis{grid-template-columns:repeat(2,minmax(0,1fr))}}
227@media (prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}
228@keyframes tw{50%{opacity:.25}}.tw{animation:tw 3.2s ease-in-out infinite}
229`
230
231/** The square picture inside the polaroid frame: the session as a night sky. */
232export function snapshotArt(d: ReportData): string {
233  const S = 300
234  const r = rng(hash(`${d.title}|${d.startedAt}`))
235  const span = Math.max(1, d.endedAt - d.startedAt)
236  const parts: string[] = []
237  parts.push(`<defs><linearGradient id="sky" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#160a33"/><stop offset=".6" stop-color="#1c0f45"/><stop offset="1" stop-color="#05283a"/></linearGradient>
238<radialGradient id="neb" cx=".75" cy=".3" r=".55"><stop offset="0" stop-color="${KZ.magenta}" stop-opacity=".45"/><stop offset="1" stop-color="${KZ.magenta}" stop-opacity="0"/></radialGradient>
239<radialGradient id="neb2" cx=".2" cy=".8" r=".5"><stop offset="0" stop-color="${KZ.cyan}" stop-opacity=".3"/><stop offset="1" stop-color="${KZ.cyan}" stop-opacity="0"/></radialGradient>
240<filter id="gl"><feGaussianBlur stdDeviation="3"/></filter></defs>`)
241  parts.push(`<rect width="${S}" height="${S}" fill="url(#sky)"/><rect width="${S}" height="${S}" fill="url(#neb)"/><rect width="${S}" height="${S}" fill="url(#neb2)"/>`)
242  for (let i = 0; i < 90; i++) {
243    const x = r() * S
244    const y = r() * S
245    parts.push(`<circle cx="${x.toFixed(1)}" cy="${y.toFixed(1)}" r="${(0.3 + r() * 1.1).toFixed(2)}" fill="#fff" opacity="${(0.3 + r() * 0.7).toFixed(2)}"${i % 4 === 0 ? ` class="tw" style="animation-delay:-${(r() * 3).toFixed(2)}s"` : ''}/>`)
246  }
247  // Turns as a constellation across the frame: x by time, y by tool count, size by duration.
248  const maxTools = Math.max(1, ...d.turns.map(t => t.tools))
249  const maxDur = Math.max(1, ...d.turns.map(t => t.durationMs))
250  const pts = d.turns.map(t => {
251    const x = 24 + clamp01((t.startedAt - d.startedAt) / span) * (S - 48)
252    const y = S - 40 - (t.tools / maxTools) * (S - 90) + (r() - 0.5) * 16
253    return { x, y, rad: 2.5 + 7 * Math.sqrt(t.durationMs / maxDur), c: t.usd > 0.5 ? KZ.amber : t.tools > 10 ? KZ.magenta : KZ.cyan }
254  })
255  if (pts.length > 1) parts.push(`<polyline points="${pts.map(p => `${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(' ')}" fill="none" stroke="#fff" stroke-opacity=".28" stroke-width="1"/>`)
256  for (const p of pts) {
257    parts.push(`<circle cx="${p.x.toFixed(1)}" cy="${p.y.toFixed(1)}" r="${(p.rad * 2).toFixed(1)}" fill="${p.c}" opacity=".35" filter="url(#gl)"/>`)
258    parts.push(`<circle cx="${p.x.toFixed(1)}" cy="${p.y.toFixed(1)}" r="${p.rad.toFixed(1)}" fill="${p.c}"/>`)
259  }
260  // A horizon of tool families.
261  const fam = Object.entries(d.families).sort((a, b) => b[1] - a[1])
262  const total = fam.reduce((s, [, n]) => s + n, 0)
263  let x = 0
264  for (const [name, n] of fam) {
265    const w = (n / Math.max(1, total)) * S
266    parts.push(`<rect x="${x.toFixed(1)}" y="${S - 10}" width="${w.toFixed(1)}" height="10" fill="${FAMILY_COLOR[name] ?? KZ.mist}"/>`)
267    x += w
268  }
269  if (!total) parts.push(`<rect x="0" y="${S - 10}" width="${S}" height="10" fill="${KZ.violet}" opacity=".5"/>`)
270  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${S} ${S}" role="img" aria-label="A picture of the session: one glowing star per turn">${parts.join('')}</svg>`
271}
272
273function familyChart(d: ReportData): string {
274  const fam = Object.entries(d.families).sort((a, b) => b[1] - a[1])
275  if (!fam.length) return '<p class="empty">No tool calls this session.</p>'
276  const W = 520
277  const rowH = 30
278  const H = fam.length * rowH + 6
279  const top = Math.max(1, ...fam.map(([, n]) => n))
280  const total = fam.reduce((s, [, n]) => s + n, 0)
281  const rows = fam.map(([name, n], i) => {
282    const y = i * rowH
283    const c = FAMILY_COLOR[name] ?? KZ.mist
284    const w = Math.max(4, (n / top) * (W - 190))
285    return `<g><text x="0" y="${y + 19}" fill="#cfcbe8" font-size="13" font-weight="600">${esc(name)}</text>
286<rect x="80" y="${y + 7}" width="${W - 190}" height="14" rx="7" fill="rgba(255,255,255,.06)"/>
287<rect x="80" y="${y + 7}" width="${w.toFixed(1)}" height="14" rx="7" fill="${c}" filter="url(#fg)"/>
288<text x="${W - 100}" y="${y + 19}" fill="${c}" font-size="13" font-weight="750">${num(n)}</text>
289<text x="${W}" y="${y + 19}" fill="#6f6c8f" font-size="12" text-anchor="end">${Math.round((n / total) * 100)}%</text></g>`
290  })
291  return `<svg viewBox="0 0 ${W} ${H}" role="img" aria-label="Tool calls by family"><defs><filter id="fg" x="-20%" y="-50%" width="140%" height="200%"><feGaussianBlur stdDeviation="2.4" result="b"/><feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge></filter></defs>${rows.join('')}</svg>`
292}
293
294function contextChart(d: ReportData): string {
295  const pts = d.ctxSeries
296  if (pts.length < 2) return d.ctxPeakPercent !== undefined ? `<p class="dim">Peak ${Math.round(d.ctxPeakPercent)}% of the window.</p>` : '<p class="empty">No context readings yet.</p>'
297  const W = 520
298  const H = 120
299  const span = Math.max(1, d.endedAt - d.startedAt)
300  const xy = pts.map(([t, p]) => [(clamp01(t / span) * W).toFixed(1), (H - 8 - clamp01(p / 100) * (H - 16)).toFixed(1)])
301  const line = xy.map(([x, y]) => `${x},${y}`).join(' ')
302  // Two points at least, so there is a last one.
303  const area = `M0,${H} L${xy.map(([x, y]) => `${x},${y}`).join(' L')} L${(xy[xy.length - 1] as string[])[0]},${H} Z`
304  const grid = [25, 50, 75].map(p => `<line x1="0" x2="${W}" y1="${H - 8 - (p / 100) * (H - 16)}" y2="${H - 8 - (p / 100) * (H - 16)}" stroke="rgba(255,255,255,.07)" stroke-dasharray="3 5"/><text x="${W}" y="${H - 11 - (p / 100) * (H - 16)}" fill="#6f6c8f" font-size="10" text-anchor="end">${p}%</text>`).join('')
305  return `<svg viewBox="0 0 ${W} ${H}" role="img" aria-label="Context fill over the session"><defs><linearGradient id="cg" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="${KZ.cyan}" stop-opacity=".5"/><stop offset="1" stop-color="${KZ.cyan}" stop-opacity="0"/></linearGradient></defs>${grid}<path d="${area}" fill="url(#cg)"/><polyline points="${line}" fill="none" stroke="${KZ.cyan}" stroke-width="2" stroke-linejoin="round"/></svg>`
306}
307
308function timelineStrip(d: ReportData): string {
309  if (!d.turns.length) return ''
310  const W = 1000
311  const H = 46
312  const span = Math.max(1, d.endedAt - d.startedAt)
313  const maxUsd = Math.max(0.0001, ...d.turns.map(t => t.usd))
314  const blocks = d.turns.map(t => {
315    const x = clamp01((t.startedAt - d.startedAt) / span) * W
316    const w = Math.max(3, (t.durationMs / span) * W)
317    const k = t.usd / maxUsd
318    const c = k > 0.66 ? KZ.amber : k > 0.33 ? KZ.magenta : KZ.violet
319    return `<rect x="${x.toFixed(1)}" y="10" width="${w.toFixed(1)}" height="22" rx="4" fill="${c}" opacity="${(0.55 + 0.45 * k).toFixed(2)}"><title>Turn ${t.index}: ${esc(fmtClock(t.durationMs))}, ${t.tools} tools, ${esc(fmtUsd(t.usd))}</title></rect>`
320  })
321  return `<svg viewBox="0 0 ${W} ${H}" preserveAspectRatio="none" style="height:46px" role="img" aria-label="Turns across the session"><rect x="0" y="20" width="${W}" height="2" fill="rgba(255,255,255,.08)"/>${blocks.join('')}<text x="0" y="45" fill="#6f6c8f" font-size="10">0:00</text><text x="${W}" y="45" fill="#6f6c8f" font-size="10" text-anchor="end">${esc(fmtClock(span))}</text></svg>`
322}
323
324const barCell = (ratio: number, color: string): string => `<div class="bar" style="--c:${color}"><i style="width:${(clamp01(ratio) * 100).toFixed(1)}%"></i></div>`
325
326export function buildHtml(d: ReportData, generatedAt: number): string {
327  const dur = Math.max(0, d.endedAt - d.startedAt)
328  const toks = totalTokens(d.tokens)
329  const toolTotal = Object.values(d.families).reduce((s, n) => s + n, 0)
330  const title = d.title || 'A Claude Code session'
331  const cost = d.costUsd ?? d.turns.reduce((s, t) => s + t.usd, 0) + d.agents.reduce((s, a) => s + a.usd, 0)
332  const kpi = (k: string, v: string, s: string, c: string) => `<div class="kpi" style="--c:${c}"><div class="k">${esc(k)}</div><div class="v">${esc(v)}</div><div class="s">${esc(s)}</div></div>`
333
334  const tokenBar = toks
335    ? `<div style="display:flex;height:10px;border-radius:5px;overflow:hidden;margin-top:6px">${(
336        [['input', d.tokens.input, KZ.blue], ['output', d.tokens.output, KZ.magenta], ['cache read', d.tokens.cacheRead, KZ.teal], ['cache write', d.tokens.cacheWrite, KZ.amber]] as const
337      ).map(([, n, c]) => `<i style="width:${((n / toks) * 100).toFixed(2)}%;background:${c}"></i>`).join('')}</div>
338<div class="legend">${(
339        [['input', d.tokens.input, KZ.blue], ['output', d.tokens.output, KZ.magenta], ['cache read', d.tokens.cacheRead, KZ.teal], ['cache write', d.tokens.cacheWrite, KZ.amber]] as const
340      ).map(([k, n, c]) => `<span style="--c:${c}">${esc(k)} <b>${esc(fmtTokens(n))}</b></span>`).join('')}</div>`
341    : '<p class="empty">No token counts yet.</p>'
342
343  const limits = d.limits.length
344    ? d.limits.map(l => {
345        const c = l.percentUsed >= 85 ? KZ.red : l.percentUsed >= 60 ? KZ.amber : KZ.green
346        const reset = l.resetsAt && Number.isFinite(Date.parse(l.resetsAt)) ? ` · resets ${stamp(Date.parse(l.resetsAt))}` : ''
347        return `<div class="limit"><div class="row"><span><b>${esc(limitLabel(l.kind))}</b> <span class="mute">${esc(l.kind.replace(/_/g, ' '))}</span></span><span>${Math.round(l.percentUsed)}% <span class="mute">peak ${Math.round(l.peak)}%${esc(reset)}</span></span></div>${barCell(l.percentUsed / 100, c)}</div>`
348      }).join('')
349    : '<p class="empty">No rate-limit readings (none reported this session).</p>'
350
351  const topTools = Object.entries(d.toolNames).sort((a, b) => b[1] - a[1]).slice(0, 10)
352  const toolTop = Math.max(1, ...topTools.map(([, n]) => n))
353  const toolsTable = topTools.length
354    ? `<table><thead><tr><th>Tool</th><th></th><th class="n">Calls</th></tr></thead><tbody>${topTools.map(([name, n]) => `<tr><td class="mono">${esc(name)}</td><td style="width:45%">${barCell(n / toolTop, FAMILY_COLOR[familyOf(name)] as string)}</td><td class="n">${num(n)}</td></tr>`).join('')}</tbody></table>`
355    : ''
356
357  const maxDur = Math.max(1, ...d.turns.map(t => t.durationMs))
358  const turnsTable = d.turns.length
359    ? `<div class="scroll"><table><thead><tr><th>#</th><th>Prompt</th><th>Duration</th><th></th><th class="n">Tools</th><th class="n">Tokens</th><th class="n">Cost</th></tr></thead><tbody>${d.turns.map(t => `<tr><td class="mute">${t.index}</td><td>${esc(oneLine(t.prompt || '(continuation)', 90))}${t.reason !== 'answer' ? ` <span class="pill" style="--c:${t.reason === 'running' ? KZ.cyan : t.reason === 'aborted' ? KZ.amber : KZ.red}">${esc(t.reason)}</span>` : ''}</td><td class="n mono">${esc(fmtClock(t.durationMs))}</td><td style="width:18%">${barCell(t.durationMs / maxDur, KZ.violet)}</td><td class="n">${num(t.tools)}</td><td class="n">${esc(fmtTokens(t.tokens))}</td><td class="n">${esc(fmtUsd(t.usd))}</td></tr>`).join('')}</tbody></table></div>`
360    : '<p class="empty">No turns yet.</p>'
361
362  const agentsTable = d.agents.length
363    ? `<div class="scroll"><table><thead><tr><th>Agent</th><th>Type</th><th>Model</th><th class="n">Time</th><th class="n">Tokens</th><th class="n">Cost</th><th>Status</th></tr></thead><tbody>${d.agents.map(a => {
364        const c = a.status === 'failed' ? KZ.red : a.status === 'running' ? KZ.cyan : KZ.green
365        return `<tr><td>${esc(oneLine(a.description || a.id, 60))}</td><td><span class="pill" style="--c:${KZ.violet}">${esc(a.type)}</span></td><td>${esc(modelName(a.model))}</td><td class="n mono">${esc(fmtClock(a.durationMs))}</td><td class="n">${esc(fmtTokens(a.tokens))}</td><td class="n">${esc(fmtUsd(a.usd))}</td><td><span class="pill" style="--c:${c}">${esc(a.status)}</span></td></tr>`
366      }).join('')}</tbody></table></div>`
367    : '<p class="empty">No subagents were spawned.</p>'
368
369  const files = [...d.files].sort((a, b) => b.edits + b.writes - (a.edits + a.writes) || b.reads - a.reads).slice(0, 60)
370  const fileTop = Math.max(1, ...files.map(f => f.reads + f.edits + f.writes))
371  const filesTable = files.length
372    ? `<div class="scroll"><table><thead><tr><th>File</th><th class="n">Read</th><th class="n">Edited</th><th class="n">Written</th><th></th></tr></thead><tbody>${files.map(f => `<tr><td class="mono" style="word-break:break-all">${esc(f.path)}</td><td class="n">${f.reads || ''}</td><td class="n">${f.edits || ''}</td><td class="n">${f.writes || ''}</td><td style="width:16%">${barCell((f.reads + f.edits + f.writes) / fileTop, f.edits + f.writes ? KZ.yellow : KZ.blue)}</td></tr>`).join('')}</tbody></table></div>${d.files.length > files.length ? `<p class="mute">and ${d.files.length - files.length} more</p>` : ''}`
373    : '<p class="empty">No files were read or changed.</p>'
374
375  const commands = d.commands.length
376    ? `<div class="cmds">${d.commands.map(c => `<span class="cmd"><b class="mono">/${esc(c.name)}</b>${c.args ? ` <span class="dim">${esc(oneLine(c.args, 40))}</span>` : ''}<span class="t">${esc(fmtClock(c.at - d.startedAt))}</span></span>`).join('')}</div>`
377    : '<p class="empty">No slash commands were run.</p>'
378
379  const models = d.models.length > 1 ? `<span class="chip">also <b>${esc(d.models.filter(m => m !== d.model).map(modelName).join(', '))}</b></span>` : ''
380
381  return `<!doctype html>
382<html lang="en">
383<head>
384<meta charset="utf-8">
385<meta name="viewport" content="width=device-width,initial-scale=1">
386<meta name="color-scheme" content="dark">
387<title>${esc(`Polaroid · ${oneLine(title, 60)}`)}</title>
388<style>${CSS}</style>
389</head>
390<body>
391<main>
392<section class="hero">
393  <figure class="polaroid" style="margin:0">
394    ${snapshotArt(d)}
395    <figcaption class="caption">${esc(oneLine(title, 42))}<small>${esc(stamp(d.startedAt))} · ${esc(fmtClock(dur))}</small></figcaption>
396  </figure>
397  <div>
398    <div class="kicker">Session Polaroid</div>
399    <h1 class="title">${esc(title)}</h1>
400    <div class="chips">
401      <span class="chip">model <b>${esc(modelName(d.model) || '—')}</b></span>${models}
402      <span class="chip">Claude Code <b>${esc(d.version || '?')}</b></span>
403      <span class="chip">from <b>${esc(stamp(d.startedAt))}</b> to <b>${esc(stamp(d.endedAt))}</b></span>
404      ${d.root ? `<span class="chip mono">${esc(d.root)}</span>` : ''}
405    </div>
406    <div class="kpis">
407      ${kpi('Duration', fmtClock(dur), `${d.turns.length} turns`, KZ.cyan)}
408      ${kpi('Cost', fmtUsd(cost), d.costUsd === undefined ? 'estimated' : 'as /cost totals it', KZ.yellow)}
409      ${kpi('Tokens', fmtTokens(toks), `${num(d.requests)} requests`, KZ.magenta)}
410      ${kpi('Context peak', d.ctxPeakPercent !== undefined ? `${Math.round(d.ctxPeakPercent)}%` : '—', d.ctxPeakTokens !== undefined ? `${fmtTokens(d.ctxPeakTokens)} of ${fmtTokens(d.ctxWindow ?? 0)}` : '', KZ.blue)}
411      ${kpi('Tool calls', num(toolTotal), d.toolErrors ? `${d.toolErrors} failed` : 'none failed', KZ.green)}
412      ${kpi('Subagents', num(d.agents.length), `${d.files.length} files touched`, KZ.violet)}
413    </div>
414  </div>
415</section>
416
417<div class="grid">
418  <section class="card" style="--accent:var(--cyan)"><h2>Context</h2>${contextChart(d)}<h2 style="margin-top:18px;--accent:var(--magenta)">Tokens</h2>${tokenBar}</section>
419  <section class="card" style="--accent:var(--green)"><h2>Rate limits</h2>${limits}</section>
420</div>
421
422<div class="grid">
423  <section class="card" style="--accent:var(--green)"><h2>Tools by family</h2>${familyChart(d)}</section>
424  <section class="card" style="--accent:var(--blue)"><h2>Most-used tools</h2>${toolsTable || '<p class="empty">No tool calls this session.</p>'}</section>
425</div>
426
427<div class="grid">
428  <section class="card wide" style="--accent:var(--violet)"><h2>Timeline of turns</h2>${timelineStrip(d)}${turnsTable}</section>
429  <section class="card wide" style="--accent:var(--violet)"><h2>Subagents</h2>${agentsTable}</section>
430  <section class="card" style="--accent:var(--yellow)"><h2>Files touched</h2>${filesTable}</section>
431  <section class="card" style="--accent:var(--amber)"><h2>Commands run</h2>${commands}</section>
432</div>
433
434<footer>Shot by <b>KOZMOS Polaroid</b> · Claude Code ${esc(d.version || '?')} · ${esc(stamp(generatedAt))}</footer>
435</main>
436</body>
437</html>
438`
439}
440
441// ---------------------------------------------------------------------------
442// Markdown.
443
444/** Escapes text for a Markdown table cell or line: pipes, backticks, markup, newlines. */
445export function mdEsc(s: unknown): string {
446  return String(s ?? '').replace(/\r?\n/g, ' ').replace(/([\\`*_[\]|<>#])/g, '\\$1')
447}
448
449export function buildMarkdown(d: ReportData, generatedAt: number): string {
450  const dur = Math.max(0, d.endedAt - d.startedAt)
451  const toks = totalTokens(d.tokens)
452  const cost = d.costUsd ?? d.turns.reduce((s, t) => s + t.usd, 0) + d.agents.reduce((s, a) => s + a.usd, 0)
453  const toolTotal = Object.values(d.families).reduce((s, n) => s + n, 0)
454  const L: string[] = []
455  L.push(`# Session Polaroid: ${mdEsc(d.title || 'A Claude Code session')}`, '')
456  L.push(`- **Model:** ${mdEsc(modelName(d.model) || '—')}${d.models.length > 1 ? ` (also ${mdEsc(d.models.filter(m => m !== d.model).map(modelName).join(', '))})` : ''}`)
457  L.push(`- **Claude Code:** ${mdEsc(d.version || '?')}`)
458  L.push(`- **When:** ${stamp(d.startedAt)} to ${stamp(d.endedAt)} (${fmtClock(dur)})`)
459  if (d.root) L.push(`- **Project:** \`${d.root.replace(/`/g, "'")}\``)
460  L.push(`- **Cost:** ${fmtUsd(cost)}${d.costUsd === undefined ? ' (estimated)' : ''}`)
461  L.push(`- **Tokens:** ${fmtTokens(toks)} over ${d.requests} requests (input ${fmtTokens(d.tokens.input)}, output ${fmtTokens(d.tokens.output)}, cache read ${fmtTokens(d.tokens.cacheRead)}, cache write ${fmtTokens(d.tokens.cacheWrite)})`)
462  L.push(`- **Context peak:** ${d.ctxPeakPercent !== undefined ? `${Math.round(d.ctxPeakPercent)}%` : '—'}${d.ctxPeakTokens !== undefined ? ` (${fmtTokens(d.ctxPeakTokens)} of ${fmtTokens(d.ctxWindow ?? 0)})` : ''}`)
463  L.push(`- **Tool calls:** ${toolTotal}${d.toolErrors ? ` (${d.toolErrors} failed)` : ''}`, '')
464
465  if (d.limits.length) {
466    L.push('## Rate limits', '', '| Window | Used | Peak | Resets |', '| --- | ---: | ---: | --- |')
467    for (const l of d.limits) L.push(`| ${mdEsc(limitLabel(l.kind))} | ${Math.round(l.percentUsed)}% | ${Math.round(l.peak)}% | ${l.resetsAt && Number.isFinite(Date.parse(l.resetsAt)) ? stamp(Date.parse(l.resetsAt)) : '—'} |`)
468    L.push('')
469  }
470  const fam = Object.entries(d.families).sort((a, b) => b[1] - a[1])
471  if (fam.length) {
472    L.push('## Tools by family', '', '| Family | Calls | Share |', '| --- | ---: | ---: |')
473    for (const [name, n] of fam) L.push(`| ${mdEsc(name)} | ${n} | ${Math.round((n / toolTotal) * 100)}% |`)
474    L.push('')
475  }
476  L.push('## Timeline of turns', '')
477  if (d.turns.length) {
478    L.push('| # | Prompt | Duration | Tools | Tokens | Cost |', '| ---: | --- | ---: | ---: | ---: | ---: |')
479    for (const t of d.turns) L.push(`| ${t.index} | ${mdEsc(oneLine(t.prompt || '(continuation)', 80))} | ${fmtClock(t.durationMs)} | ${t.tools} | ${fmtTokens(t.tokens)} | ${fmtUsd(t.usd)} |`)
480  } else L.push('_No turns yet._')
481  L.push('', '## Subagents', '')
482  if (d.agents.length) {
483    L.push('| Agent | Type | Model | Time | Tokens | Cost | Status |', '| --- | --- | --- | ---: | ---: | ---: | --- |')
484    for (const a of d.agents) L.push(`| ${mdEsc(oneLine(a.description || a.id, 60))} | ${mdEsc(a.type)} | ${mdEsc(modelName(a.model))} | ${fmtClock(a.durationMs)} | ${fmtTokens(a.tokens)} | ${fmtUsd(a.usd)} | ${a.status} |`)
485  } else L.push('_No subagents were spawned._')
486  L.push('', '## Files touched', '')
487  if (d.files.length) {
488    L.push('| File | Read | Edited | Written |', '| --- | ---: | ---: | ---: |')
489    for (const f of d.files) L.push(`| ${mdEsc(f.path)} | ${f.reads} | ${f.edits} | ${f.writes} |`)
490  } else L.push('_No files were read or changed._')
491  L.push('', '## Commands run', '')
492  if (d.commands.length) for (const c of d.commands) L.push(`- ${fmtClock(c.at - d.startedAt)} \`/${c.name.replace(/`/g, "'")}\`${c.args ? ` ${mdEsc(oneLine(c.args, 60))}` : ''}`)
493  else L.push('_No slash commands were run._')
494  L.push('', `---`, `Shot by KOZMOS Polaroid · ${stamp(generatedAt)}`, '')
495  return L.join('\n')
496}
497