de-shell 0.2.0__py3-none-any.whl

de_shell/js/main/config.ts

@@ -0,0 +1,53 @@
+/**
+ * config.ts — the per-app identity the shell needs but must not assume.
+ *
+ * Everything in this package used to say "spyde" out loud: the IPC channel
+ * prefix, the settings directory, the Python module to spawn, the wheel name,
+ * the setuptools_scm env-var suffix. None of that is shell knowledge — it is the
+ * one thing that differs between SpyDE, de-groundcrew and de-autopilot.
+ *
+ * An app calls `configureShell()` once, at the top of its main process, before
+ * anything else in this package runs.
+ */
+
+export interface ShellConfig {
+  /** Lowercase, filesystem- and URL-safe app id, e.g. 'spyde', 'groundcrew'.
+   *  Drives the IPC channel prefix (`<appId>:action`), the settings directory
+   *  (`~/.<appId>/settings.json`), the packaged-app env var
+   *  (`<APPID>_PACKAGED`), and the custom figure scheme (`<appId>-fig://`). */
+  appId: string
+  /** Human-readable name for user-facing strings ("… exited with code 1"). */
+  appName: string
+  /** The Python module the backend runs as: `python -m <pythonModule>`. */
+  pythonModule: string
+  /** Distribution name of the Python package, when it differs from the module
+   *  (e.g. module `spyde` / dist `spyde`). Used for the pre-built wheel prefix
+   *  and the SETUPTOOLS_SCM_PRETEND_VERSION_FOR_<NAME> env var. */
+  pythonDist?: string
+}
+
+let _config: ShellConfig | null = null
+
+export function configureShell(config: ShellConfig): void {
+  _config = { pythonDist: config.pythonModule, ...config }
+}
+
+export function shellConfig(): ShellConfig {
+  if (_config === null) {
+    throw new Error(
+      'configureShell() must be called before any @de/shell-main API. ' +
+      'Call it at the top of your main process entry point.',
+    )
+  }
+  return _config
+}
+
+/** `<appId>:<name>` — the IPC channel namespace. */
+export function channel(name: string): string {
+  return `${shellConfig().appId}:${name}`
+}
+
+/** `<APPID>` — the env-var namespace (uppercased, non-alphanumerics to `_`). */
+export function envPrefix(): string {
+  return shellConfig().appId.toUpperCase().replace(/[^A-Z0-9]/g, '_')
+}

de_shell/js/main/dialogs.ts

@@ -0,0 +1,62 @@
+/**
+ * dialogs.ts — native open/save dialogs, on the shell's channel.
+ *
+ * A sandboxed renderer cannot open a file dialog and has no filesystem paths,
+ * so this is the only way an app can ask the user for a file. Registered once
+ * per app by `registerShellDialogs`, on `<appId>:open-file` /
+ * `<appId>:open-directory` / `<appId>:save-file`.
+ *
+ * All resolve to a PATH or null. Null means cancelled, which is a normal
+ * outcome and not an error — the caller should do nothing rather than report a
+ * failure.
+ */
+import { BrowserWindow, dialog, ipcMain, shell } from 'electron'
+
+import { channel } from './config'
+
+export interface FileFilter { name: string; extensions: string[] }
+
+/** Protocols a renderer may hand to the OS browser. Deliberately no `file:` —
+ *  the web allowlist must never be talked into opening a local path. */
+const EXTERNAL_PROTOCOLS = new Set(['https:', 'http:', 'mailto:'])
+
+/** Wire the open/save dialog handlers and the external-link opener. Call
+ *  once, after `configureShell`. */
+export function registerShellDialogs(): void {
+  // Unprefixed on purpose: the preload sends on 'open-external' for every app.
+  ipcMain.on('open-external', (_e, url: string) => {
+    try {
+      if (EXTERNAL_PROTOCOLS.has(new URL(String(url)).protocol)) void shell.openExternal(url)
+    } catch { /* not a URL — ignore */ }
+  })
+
+  ipcMain.handle(channel('open-file'), async (event, filters?: FileFilter[]) => {
+    // Parent the dialog to the window that asked, so it is modal to that
+    // window rather than floating free of the app.
+    const win = BrowserWindow.fromWebContents(event.sender)
+    const opts = { properties: ['openFile' as const], filters }
+    const result = win
+      ? await dialog.showOpenDialog(win, opts)
+      : await dialog.showOpenDialog(opts)
+    return result.canceled || !result.filePaths.length ? null : result.filePaths[0]
+  })
+
+  ipcMain.handle(channel('open-directory'), async (event) => {
+    const win = BrowserWindow.fromWebContents(event.sender)
+    const opts = { properties: ['openDirectory' as const] }
+    const result = win
+      ? await dialog.showOpenDialog(win, opts)
+      : await dialog.showOpenDialog(opts)
+    return result.canceled || !result.filePaths.length ? null : result.filePaths[0]
+  })
+
+  ipcMain.handle(channel('save-file'),
+    async (event, filters?: FileFilter[], defaultPath?: string) => {
+      const win = BrowserWindow.fromWebContents(event.sender)
+      const opts = { filters, defaultPath }
+      const result = win
+        ? await dialog.showSaveDialog(win, opts)
+        : await dialog.showSaveDialog(opts)
+      return result.canceled || !result.filePath ? null : result.filePath
+    })
+}

de_shell/js/main/envProgress.ts

@@ -0,0 +1,126 @@
+/**
+ * envProgress.ts — parse `uv` first-run output into structured setup progress.
+ *
+ * `uv sync` / `uv pip install` stream human-readable status to stderr. On first
+ * packaged launch that stream is the ONLY signal that anything is happening
+ * (hundreds of MB of wheels, incl. PyTorch, are being fetched). The renderer
+ * turns these events into a floating "Setting up…" overlay with a live phase,
+ * a friendly current-step line, an optional download %, and a raw log tail —
+ * so first launch never looks frozen.
+ *
+ * This module is pure string→event, no I/O, so it is unit-testable
+ * (test_env_progress.ts) without spawning uv.
+ */
+
+export type EnvPhase =
+  | 'resolving'    // building the dependency graph
+  | 'downloading'  // fetching wheels/sdists
+  | 'installing'   // unpacking into the venv
+  | 'building'     // building the editable spyde package (setuptools_scm)
+  | 'torch'        // the per-machine torch step (the big one)
+  | 'working'      // fallback: uv said something we don't specifically classify
+
+export interface EnvProgressEvent {
+  phase: EnvPhase
+  /** Short human sentence for the overlay's headline step, e.g. "Downloading PyTorch". */
+  step: string
+  /** 0–100 when uv reports a download percentage for a large artifact; else null. */
+  percent: number | null
+}
+
+const KNOWN_BIG = /\btorch\b/i
+
+/**
+ * Classify ONE raw line of uv output. Returns null for noise (blank lines,
+ * lines we can't meaningfully turn into a step) — the caller keeps the last
+ * non-null event as the current state and always appends the raw line to the
+ * log tail regardless.
+ */
+export function parseUvLine(raw: string): EnvProgressEvent | null {
+  const line = raw.replace(/\r/g, '').trim()
+  if (!line) return null
+
+  // Our own [env-setup] breadcrumbs (pythonEnv.ts) — use them verbatim, they're
+  // already user-facing phase announcements.
+  if (line.startsWith('[env-setup]')) {
+    const msg = line.slice('[env-setup]'.length).trim()
+    // Order matters: the "two-step install … torch deferred" breadcrumb mentions
+    // torch but announces the RESOLVE phase, so match the sync/plan keywords
+    // first and only fall to the torch phase for an actual torch-install line.
+    if (/two-step|full locked|uv sync|deferred/i.test(msg)) {
+      return { phase: 'resolving', step: 'Preparing the analysis environment', percent: null }
+    }
+    if (/torch/i.test(msg)) {
+      return { phase: 'torch', step: 'Installing PyTorch for your GPU', percent: null }
+    }
+    return { phase: 'working', step: capitalize(msg), percent: null }
+  }
+
+  // A download progress line. uv renders these like:
+  //   "torch     ======>          123.4 MiB/825.0 MiB"  (bar form), or
+  //   "Downloading torch (825.0 MiB)"                    (start), or a trailing
+  //   percentage. Pull a percent if the two sizes are present.
+  const dl = line.match(/^([\w.\-]+)\s+.*?([\d.]+)\s*([KMG]i?B)\s*\/\s*([\d.]+)\s*([KMG]i?B)/i)
+  if (dl) {
+    const pkg = dl[1]
+    const cur = toBytes(dl[2], dl[3])
+    const tot = toBytes(dl[4], dl[5])
+    const percent = tot > 0 ? Math.min(100, Math.round((cur / tot) * 100)) : null
+    const big = KNOWN_BIG.test(pkg)
+    return {
+      phase: big ? 'torch' : 'downloading',
+      step: big ? 'Downloading PyTorch' : `Downloading ${pkg}`,
+      percent,
+    }
+  }
+
+  // uv's phase verbs (it prints "Resolved N packages", "Downloaded …",
+  // "Prepared …", "Installed N packages", "Building …").
+  if (/^Resolv(ing|ed)\b/i.test(line)) {
+    return { phase: 'resolving', step: 'Resolving dependencies', percent: null }
+  }
+  if (/^Download(ing|ed)\b/i.test(line)) {
+    const m = line.match(/^Download(?:ing|ed)\s+([\w.\-]+)/i)
+    const pkg = m?.[1]
+    const big = pkg ? KNOWN_BIG.test(pkg) : false
+    return {
+      phase: big ? 'torch' : 'downloading',
+      step: big ? 'Downloading PyTorch' : (pkg ? `Downloading ${pkg}` : 'Downloading packages'),
+      percent: null,
+    }
+  }
+  if (/^Prepar(ing|ed)\b/i.test(line)) {
+    return { phase: 'installing', step: 'Preparing packages', percent: null }
+  }
+  if (/^Install(ing|ed)\b/i.test(line)) {
+    const m = line.match(/(\d+)\s+packages?/i)
+    return {
+      phase: 'installing',
+      step: m ? `Installing ${m[1]} packages` : 'Installing packages',
+      percent: null,
+    }
+  }
+  if (/^Building\b/i.test(line) || /setuptools[_-]scm|Building wheel|Building editable/i.test(line)) {
+    return { phase: 'building', step: 'Building the SpyDE package', percent: null }
+  }
+  if (/^Audit(ing|ed)\b/i.test(line)) {
+    return { phase: 'installing', step: 'Finalizing the environment', percent: null }
+  }
+
+  // Recognized-but-unclassified: keep the phase we can't infer as generic
+  // "working" so the overlay still updates its step text and never looks stuck.
+  return { phase: 'working', step: 'Working', percent: null }
+}
+
+function toBytes(n: string, unit: string): number {
+  const v = parseFloat(n)
+  const u = unit.toUpperCase()
+  if (u.startsWith('G')) return v * 1024 ** 3
+  if (u.startsWith('M')) return v * 1024 ** 2
+  if (u.startsWith('K')) return v * 1024
+  return v
+}
+
+function capitalize(s: string): string {
+  return s ? s[0].toUpperCase() + s.slice(1) : s
+}

de_shell/js/main/errorReport.ts

@@ -0,0 +1,261 @@
+/**
+ * errorReport.ts — "Report a Problem": what went wrong, on what machine, sent
+ * to the maintainers.
+ *
+ * The install base is small and the failures that matter are environmental —
+ * a GPU driver, a Windows install directory, a Python wheel that resolved
+ * differently on one machine. So a report is worth much more than a stack
+ * trace: it carries the OS, the app and runtime versions, the state of the
+ * managed Python environment, the last thing the updater said, and the tail of
+ * the backend's own output.
+ *
+ * NOTHING IS SENT WITHOUT A CLICK. Problems are recorded into a bounded
+ * in-memory ring as they happen so a report written minutes later still knows
+ * what failed, but the ring never leaves the machine on its own. There is no
+ * background transport, no crash handler phoning home, and no first-run consent
+ * screen to write, because there is nothing to consent to until the user opens
+ * the dialog and presses Send.
+ *
+ * Where it goes: a Sentry project, when a DSN is configured for the build (see
+ * `initErrorReporting`). With no DSN — or when the machine is offline, which
+ * for a microscope-room PC is the normal case — the same report is written to
+ * `<userData>/reports/` and the path handed back, so the user can attach it to
+ * an email. That fallback is not a degraded mode; it is the offline path.
+ */
+import { app, net } from 'electron'
+import { randomBytes } from 'crypto'
+import { mkdirSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { arch, cpus, freemem, platform, release, totalmem, type as osType } from 'os'
+import { shellConfig } from './config'
+import { recentBackendOutput } from './backendProcess'
+import { recordedProblems, type Problem } from './problemLog'
+import { getLastUpdateStatus, readUpdateChannel, updatesSupported } from './updater'
+import {
+  buildEnvelope, formatEventId, parseSentryDsn, sentryAuthHeader, type SentryTarget,
+} from './sentryEnvelope'
+
+/** Everything a report carries about the machine and the run. */
+export interface Diagnostics {
+  app: { name: string; version: string; packaged: boolean; channel: string; updatesSupported: boolean }
+  os: { platform: string; type: string; release: string; arch: string; totalMemoryGb: number; freeMemoryGb: number; cpu: string; locale: string }
+  runtime: { electron: string; chrome: string; node: string; v8: string }
+  update: { lastStatus: unknown }
+  problems: Problem[]
+  backendOutput: string[]
+  /** Whatever the host app added — SpyDE contributes its GPU and Python-env triage. */
+  host: Record<string, unknown>
+}
+
+/** What `submitReport` managed to do. */
+export interface ReportResult {
+  /** True when the report reached the reporting service. */
+  sent: boolean
+  /** Sentry's id for the event, when it was sent — worth quoting in an email. */
+  eventId?: string
+  /** Where the report was written locally. Always set, sent or not. */
+  bundlePath?: string
+  /** Why sending failed, when it did. */
+  error?: string
+}
+
+/** A report is small; a slow network should not hang the dialog. */
+const SEND_TIMEOUT_MS = 15_000
+
+let target: SentryTarget | null = null
+let hostDiagnostics: () => Promise<Record<string, unknown>> = async () => ({})
+
+/**
+ * Configure reporting. Call once at startup.
+ *
+ * `dsn` is the Sentry DSN for the build. It is a public key — it grants writing
+ * events and nothing else — so shipping it in the app is how Sentry is designed
+ * to be used; still, keep it in CI's environment rather than in the repo so it
+ * can be rotated without a code change. Absent or malformed, reports still work
+ * and go to disk only.
+ *
+ * `collectHostDiagnostics` lets the app add what only it can answer (SpyDE
+ * passes its GPU probe and managed-Python-environment triage).
+ */
+export function initErrorReporting(options: {
+  dsn?: string | null
+  collectHostDiagnostics?: () => Promise<Record<string, unknown>>
+}): void {
+  target = parseSentryDsn(options.dsn)
+  if (options.collectHostDiagnostics) hostDiagnostics = options.collectHostDiagnostics
+}
+
+/** Whether reports can reach the maintainers, or will only be written to disk. */
+export function reportingConfigured(): boolean {
+  return target !== null
+}
+
+const GIGABYTE = 1024 ** 3
+
+/** Gather everything a report carries. Safe to call at any time. */
+export async function collectDiagnostics(): Promise<Diagnostics> {
+  const cfg = shellConfig()
+  let host: Record<string, unknown> = {}
+  try {
+    host = await hostDiagnostics()
+  } catch (err) {
+    host = { error: String(err) }
+  }
+  return {
+    app: {
+      name: cfg.appName,
+      version: app.getVersion(),
+      packaged: app.isPackaged,
+      channel: safely(() => readUpdateChannel(), 'unknown'),
+      updatesSupported: safely(() => updatesSupported(), false),
+    },
+    os: {
+      platform: platform(),
+      type: osType(),
+      release: release(),
+      arch: arch(),
+      totalMemoryGb: round1(totalmem() / GIGABYTE),
+      freeMemoryGb: round1(freemem() / GIGABYTE),
+      cpu: cpus()[0]?.model ?? 'unknown',
+      locale: safely(() => app.getLocale(), 'unknown'),
+    },
+    runtime: {
+      electron: process.versions.electron ?? '',
+      chrome: process.versions.chrome ?? '',
+      node: process.versions.node ?? '',
+      v8: process.versions.v8 ?? '',
+    },
+    update: { lastStatus: safely(() => getLastUpdateStatus(), null) },
+    problems: recordedProblems(),
+    backendOutput: recentBackendOutput(),
+    host,
+  }
+}
+
+/**
+ * Write the report to disk and, when a DSN is configured, send it.
+ *
+ * The local copy is written FIRST and unconditionally: if the send fails the
+ * user still has something to attach to an email, and if it succeeds they have
+ * a record of what they sent. `contact` is whatever the reporter chose to type
+ * — it is optional, and an empty one is simply omitted rather than sent blank.
+ */
+export async function submitReport(input: {
+  message: string
+  contact?: string
+}): Promise<ReportResult> {
+  const diagnostics = await collectDiagnostics()
+  const eventId = formatEventId(randomBytes(16))
+  const bundlePath = writeBundle(eventId, input, diagnostics)
+
+  if (!target) {
+    return {
+      sent: false,
+      bundlePath,
+      error: 'No reporting service is configured for this build, so the report was saved locally.',
+    }
+  }
+  try {
+    await sendToSentry(target, eventId, input, diagnostics)
+    return { sent: true, eventId, bundlePath }
+  } catch (err) {
+    return { sent: false, eventId, bundlePath, error: (err as Error)?.message ?? String(err) }
+  }
+}
+
+/** The report as a file under `<userData>/reports/`. Returns '' if unwritable. */
+function writeBundle(
+  eventId: string,
+  input: { message: string; contact?: string },
+  diagnostics: Diagnostics,
+): string {
+  try {
+    const dir = join(app.getPath('userData'), 'reports')
+    mkdirSync(dir, { recursive: true })
+    // Sortable, filename-safe, and second-resolution is plenty for one report.
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+    const file = join(dir, `${shellConfig().appId}-report-${stamp}.json`)
+    writeFileSync(file, JSON.stringify({ eventId, ...input, diagnostics }, null, 2), 'utf8')
+    return file
+  } catch {
+    return ''
+  }
+}
+
+/** POST one envelope. Rejects on a network failure, a timeout, or a 4xx/5xx. */
+async function sendToSentry(
+  to: SentryTarget,
+  eventId: string,
+  input: { message: string; contact?: string },
+  diagnostics: Diagnostics,
+): Promise<void> {
+  const cfg = shellConfig()
+  const event: Record<string, unknown> = {
+    event_id: eventId,
+    timestamp: new Date().toISOString(),
+    platform: 'javascript',
+    level: 'error',
+    logger: 'user-report',
+    release: `${cfg.appId}@${diagnostics.app.version}`,
+    environment: diagnostics.app.packaged ? 'production' : 'development',
+    message: { formatted: firstLine(input.message) },
+    tags: {
+      os: diagnostics.os.platform,
+      os_release: diagnostics.os.release,
+      arch: diagnostics.os.arch,
+      channel: diagnostics.app.channel,
+      packaged: String(diagnostics.app.packaged),
+    },
+    contexts: {
+      os: { name: diagnostics.os.type, version: diagnostics.os.release },
+      device: { arch: diagnostics.os.arch, memory_size: diagnostics.os.totalMemoryGb, model: diagnostics.os.cpu },
+      runtime: { name: 'electron', version: diagnostics.runtime.electron },
+    },
+    extra: {
+      report: input.message,
+      diagnostics,
+    },
+  }
+  if (input.contact?.trim()) event.user = { email: input.contact.trim() }
+
+  const body = buildEnvelope(to, event, new Date().toISOString())
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS)
+  try {
+    // Electron's `net` rather than global fetch: it uses Chromium's stack, so a
+    // machine configured with a system proxy or a corporate root certificate —
+    // which describes a lot of instrument PCs — works without extra setup.
+    const response = await net.fetch(to.endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-sentry-envelope',
+        'X-Sentry-Auth': sentryAuthHeader(to, `${cfg.appId}-shell/1.0`),
+      },
+      body,
+      signal: controller.signal,
+    })
+    if (!response.ok) {
+      throw new Error(`The reporting service refused the report (HTTP ${response.status}).`)
+    }
+  } catch (err) {
+    if ((err as Error)?.name === 'AbortError') {
+      throw new Error('Sending timed out. The report was saved on this machine instead.')
+    }
+    throw err
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function firstLine(text: string): string {
+  const line = text.trim().split('\n')[0]
+  return line.length > 200 ? `${line.slice(0, 200)}...` : (line || 'Problem report')
+}
+
+function round1(value: number): number {
+  return Math.round(value * 10) / 10
+}
+
+function safely<T>(read: () => T, fallback: T): T {
+  try { return read() } catch { return fallback }
+}

de_shell/js/main/index.ts

@@ -0,0 +1,57 @@
+/**
+ * @de/shell-main — the Electron main-process kernel shared by SpyDE,
+ * de-groundcrew and de-autopilot.
+ *
+ * What lives here is everything that answers "how do I run a desktop app with a
+ * Python brain?" — spawning and supervising the sidecar, bootstrapping its uv
+ * environment on first launch, auto-update, and the identity plumbing that ties
+ * those to a particular app.
+ *
+ * Call `configureShell()` FIRST, before any other export in this package: the
+ * IPC channel prefix, settings directory, Python module name and packaged-app
+ * env var all read from it, and they throw rather than guess.
+ */
+export { configureShell, shellConfig, channel, envPrefix } from './config'
+export type { ShellConfig } from './config'
+
+export {
+  startBackend, stopBackend, sendAction, sendFigureEvent, sendResize,
+  recentBackendOutput,
+} from './backendProcess'
+
+export { recordProblem, recordedProblems } from './problemLog'
+export type { Problem } from './problemLog'
+
+export {
+  initErrorReporting, reportingConfigured, collectDiagnostics, submitReport,
+} from './errorReport'
+export type { Diagnostics, ReportResult } from './errorReport'
+
+export { parseSentryDsn } from './sentryEnvelope'
+
+export { registerShellDialogs } from './dialogs'
+export type { FileFilter } from './dialogs'
+
+export { createShellWindow } from './window'
+export type { ShellWindow, ShellWindowOptions } from './window'
+export type { BackendHandlers } from './backendProcess'
+
+export {
+  resolvePythonEnv, managedEnvPaths, venvPython, readLockedTorchVersion,
+  installTorchPerMachine,
+} from './pythonEnv'
+export type { ResolvedPython, EnsureOptions } from './pythonEnv'
+
+export { parseUvLine } from './envProgress'
+export type { EnvPhase, EnvProgressEvent } from './envProgress'
+
+export {
+  initUpdater, checkForUpdates, downloadUpdate, quitAndInstall, resetToIdle,
+  readUpdateChannel, setUpdateChannel, getLastUpdateStatus, updatesSupported,
+  friendlyError,
+} from './updater'
+export type { UpdateChannel, UpdateStatus } from './updater'
+
+export {
+  isPrereleaseVersion, defaultChannelForVersion, truncateMessage,
+} from './updaterErrors'

de_shell/js/main/problemLog.ts

@@ -0,0 +1,53 @@
+/**
+ * problemLog.ts — a bounded in-memory record of things that went wrong.
+ *
+ * Its own module, importing nothing, so that anything can write to it: the
+ * updater records its own failures here, and errorReport.ts reads the ring
+ * while also reading the updater's state. Merging the two would make that a
+ * cycle.
+ *
+ * The ring is memory only and never leaves the machine on its own — it exists
+ * so that a report the user writes minutes after a failure still knows what
+ * failed. See errorReport.ts for what happens to it.
+ */
+
+/** One thing that went wrong, as recorded when it happened. */
+export interface Problem {
+  /** When, as an ISO timestamp. */
+  at: string
+  /** Coarse source, e.g. 'main', 'backend', 'updater'. */
+  kind: string
+  /** The message/stack, truncated. */
+  detail: string
+}
+
+/** Keep it small: it is read in full into every report. */
+const MAX_PROBLEMS = 25
+const MAX_DETAIL_CHARS = 4000
+
+const problems: Problem[] = []
+
+/**
+ * Note that something went wrong.
+ *
+ * Deliberately cheap and total: it never throws and never sends, so it is safe
+ * to call from a crash handler, a stderr pump, or an updater error path.
+ */
+export function recordProblem(kind: string, detail: unknown): void {
+  try {
+    const text = detail instanceof Error
+      ? (detail.stack ?? detail.message)
+      : String(detail)
+    problems.push({
+      at: new Date().toISOString(),
+      kind,
+      detail: text.slice(0, MAX_DETAIL_CHARS),
+    })
+    if (problems.length > MAX_PROBLEMS) problems.splice(0, problems.length - MAX_PROBLEMS)
+  } catch { /* a reporting failure must never become the failure */ }
+}
+
+/** The problems recorded so far, oldest first. */
+export function recordedProblems(): Problem[] {
+  return [...problems]
+}