dsh-inner-browser-use 0.27.0 → 0.34.95

package/review.js

@@ -0,0 +1,213 @@
+/**
+ * A review round: hand a repository address to the chat in the column, take its
+ * review back, and remember which commit the review was about. The log is what
+ * makes the next round checkable — advice given about a commit that has since
+ * moved on is stale, and saying so costs one line instead of a reread.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** Where rounds are kept when the caller does not say. */
+export const ROUND_DIR = join(process.env.DSH_HOME ?? join(process.env.HOME ?? '.', '.dsh'), 'inner-browser-use', 'rounds')
+
+/** How long an answer may be, so a chatty model cannot flood the log. */
+const ANSWER_CAP = 6000
+
+/**
+ * @param {string} text - one line of configuration.
+ * @returns {string} the value, or an empty string.
+ */
+function clean(text) {
+  return String(text ?? '').replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * The message to send: enough for a reviewer that has never seen this project,
+ * and no more. The address carries the code, so the message does not paste any.
+ * @param {{repo?: string, commit?: string, focus?: string}} [what] - what to review.
+ * @returns {string} the message.
+ */
+export function brief(what = {}) {
+  const repo = clean(what.repo)
+  /* What the reviewer said last time and what the code did about it: a point
+     already answered is not raised again, so a round does not re-litigate. */
+  const handled = Array.isArray(what.already) ? what.already.filter((mark) => clean(mark?.status) !== 'open') : []
+  const commit = clean(what.commit)
+  const focus = clean(what.focus)
+  const lines = ['Please review the latest code and tell me what to change.']
+  if (repo !== '') lines.push(`Repository: ${repo}`)
+  if (commit !== '') lines.push(`Look at commit ${commit} (the newest one) and the files it touches.`)
+  else lines.push('Look at the newest commit and the files it touches.')
+  if (focus !== '') lines.push(`Focus on: ${focus}`)
+  /* The reviewer cannot open the repository, so the change travels with the
+     request. Capped: a whole diff would bury the question it is attached to. */
+  const diff = String(what.diff ?? '').trim()
+  if (diff !== '') {
+    const cap = 5000
+    lines.push('The change under review, inline (a diff):')
+    lines.push(diff.length <= cap ? diff : `${diff.slice(0, cap)}\n… (trimmed)`)
+  }
+  if (handled.length > 0) {
+    lines.push('Already handled from your previous review, do not raise these again:')
+    for (const mark of handled.slice(0, 12)) {
+      const note = clean(mark.evidence) === '' ? '' : ` (${clean(mark.evidence).slice(0, 120)})`
+      lines.push(`- ${clean(mark.text).slice(0, 200)} — ${clean(mark.status)}${note}`)
+    }
+  }
+  lines.push('Answer with a short list: what is wrong, and the smallest change that fixes it. Name the file for each point.')
+  return lines.join('\n')
+}
+
+/**
+ * The suggestions in an answer, one line each: reviewers are asked for a list,
+ * and the list is what the next round acts on.
+ * @param {string} answer - what the reviewer said.
+ * @returns {string[]} the points, in the order given.
+ */
+export function points(answer) {
+  /* A page read flattens an answer into one line, so a list arrives as
+     "intro - first point - second point". Split on the markers a reviewer uses
+     for items, keep only pieces that carry a marker, and drop the echo of the
+     question when the page repeats it above the answer. */
+  const out = []
+  const seen = new Set()
+  for (const raw of String(answer ?? '').split(/\r?\n/)) {
+    const parts = raw.split(/\s+[-\u2022\u2013\u2014]\s+|\s+(?=\d+[.)]\s)/).map((part) => part.trim()).filter((part) => part !== '')
+    if (parts.length === 1 && !/^(?:[-*\u2022]|\d+[.)])\s+/.test(parts[0])) continue
+    for (let at = 0; at < parts.length; at += 1) {
+      let line = parts[at]
+      if (at === 0 && !/^(?:[-*\u2022]|\d+[.)])\s+/.test(line)) continue
+      line = line.replace(/^(?:Answer:\s*)/i, '').replace(/^(?:[-*\u2022]|\d+[.)])\s+/, '').trim()
+      if (/^(?:Please review|Repository:|Look at commit|Focus on:|Answer with)/i.test(line)) continue
+      if (line.length < 8 || line.length > 400) continue
+      const key = line.toLowerCase()
+      if (seen.has(key)) continue
+      seen.add(key)
+      out.push(line)
+    }
+  }
+  return out.slice(0, 40)
+}
+
+/**
+ * Write one round down. Append-only: a round is history, not state to rewrite.
+ * @param {{dir?: string, commit?: string, question?: string, answer?: string, tookMs?: number}} entry - the round.
+ * @returns {{file: string, round: any}} where it went and what was written.
+ */
+export function recordRound(entry = {}) {
+  const dir = clean(entry.dir) === '' ? ROUND_DIR : clean(entry.dir)
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, 'rounds.ndjson')
+  const round = {
+    at: new Date().toISOString(),
+    commit: clean(entry.commit),
+    question: clean(entry.question).slice(0, 400),
+    answer: String(entry.answer ?? '').replace(/\s+/g, ' ').trim().slice(0, ANSWER_CAP),
+    points: points(entry.answer),
+    tookMs: Math.max(0, Math.trunc(Number(entry.tookMs ?? 0)) || 0),
+  }
+  appendFileSync(file, `${JSON.stringify(round)}\n`)
+  return { file, round }
+}
+
+/**
+ * The last round played, for a round that wants to know what it was told before.
+ * @param {{dir?: string}} [where] - which log.
+ * @returns {any|null} the last round, or null when none was played.
+ */
+export function lastRound(where = {}) {
+  const dir = clean(where.dir) === '' ? ROUND_DIR : clean(where.dir)
+  const file = join(dir, 'rounds.ndjson')
+  if (!existsSync(file)) return null
+  const rows = readFileSync(file, 'utf8').split('\n').filter((row) => row.trim() !== '')
+  if (rows.length === 0) return null
+  /* Verdicts are separate rows, appended after the round they judge: find the
+     newest round, then fold in the marks written since. */
+  /** @type {any[]} */
+  const rows2 = []
+  for (const row of rows) {
+    try {
+      rows2.push(JSON.parse(row))
+    } catch {
+      /* a torn line costs its own row, not the log */
+    }
+  }
+  let at = -1
+  for (let i = rows2.length - 1; i >= 0; i -= 1) {
+    if (rows2[i]?.kind !== 'verdict') {
+      at = i
+      break
+    }
+  }
+  if (at < 0) return null
+  const round = rows2[at]
+  const latest = new Map()
+  for (const row of rows2.slice(at + 1)) {
+    if (row?.kind !== 'verdict' || clean(row.roundAt) !== clean(round.at)) continue
+    for (const mark of Array.isArray(row.marks) ? row.marks : []) if (Number.isInteger(mark?.point)) latest.set(mark.point, mark)
+  }
+  return { ...round, marks: [...latest.values()].sort((a, b) => a.point - b.point) }
+}
+
+/** What a point can be, once the code has looked at it. */
+export const MARK_STATUS = ['fixed', 'verified', 'invalid', 'open']
+
+/**
+ * Say what happened to the points of the last round. The verdict is history
+ * too: it is appended, and the next round reads it so a settled point is not
+ * raised twice.
+ * @param {{dir?: string, marks?: any[]}} entry - point numbers (1-based) and their outcome.
+ * @returns {{file: string, round: any, marks: any[]}|null} what was written, or null when there is no round.
+ */
+export function markRound(entry = {}) {
+  const dir = clean(entry.dir) === '' ? ROUND_DIR : clean(entry.dir)
+  const round = lastRound({ dir })
+  if (round === null) return null
+  const said = Array.isArray(round.points) ? round.points : []
+  /** @type {any[]} */
+  const marks = []
+  for (const raw of Array.isArray(entry.marks) ? entry.marks : []) {
+    const point = Math.trunc(Number(raw?.point ?? 0))
+    if (point < 1 || point > said.length) continue
+    const status = MARK_STATUS.includes(clean(raw?.status)) ? clean(raw.status) : 'open'
+    marks.push({ point, text: said[point - 1], status, evidence: clean(raw?.evidence).slice(0, 200), at: new Date().toISOString() })
+  }
+  if (marks.length === 0) return null
+  const file = join(dir, 'rounds.ndjson')
+  mkdirSync(dir, { recursive: true })
+  appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), kind: 'verdict', roundAt: round.at, commit: round.commit, marks })}\n`)
+  return { file, round, marks }
+}
+
+/**
+ * One line for the model: what the reviewer said last, and whether the code has
+ * moved since. A review of an old commit is worth reading and not worth obeying.
+ * @param {{dir?: string, commit?: string}} [now] - the commit the code is at now.
+ * @returns {string} the note, or an empty string when no round was played.
+ */
+export function lastRoundNote(now = {}) {
+  const last = lastRound(now)
+  if (last === null) return ''
+  const commit = clean(now.commit)
+  const same = commit === '' || last.commit === '' || last.commit === commit
+  const points = Array.isArray(last.points) ? last.points : []
+  const head = points.length === 0 ? 'the reviewer gave no list' : `${points.length} point${points.length === 1 ? '' : 's'}`
+  const when = same ? 'about this commit' : `about ${String(last.commit).slice(0, 12)}, and the code has moved since`
+  return `Last review (${last.at.slice(0, 16).replace('T', ' ')}): ${head}, ${when}.`
+}
+
+/**
+ * The reviewer's last points as a list to act on.
+ * @param {{dir?: string}} [where] - which log.
+ * @returns {string[]} the points.
+ */
+export function lastPoints(where = {}) {
+  const last = lastRound(where)
+  return last !== null && Array.isArray(last.points) ? last.points : []
+}
+
+/** @returns {string} the directory the log lives in. */
+export function roundDir() {
+  return dirname(join(ROUND_DIR, 'rounds.ndjson'))
+}

package/runtime/flash-app/main.js

@@ -0,0 +1,232 @@
+/* The one job of this app: open a window Chromium will render, and let the
+   sidecar drive it over the debugging port. The Flash plugin arrives from the
+   sidecar's environment and is appended to the command line here, because
+   Electron only honours these switches when they are set before Chromium
+   starts. */
+const { app, BrowserWindow, Menu } = require('electron')
+const http = require('http')
+const env = process.env
+
+app.commandLine.appendSwitch('use-mock-keychain')
+app.commandLine.appendSwitch('lang', 'zh-CN')
+app.commandLine.appendSwitch('password-store', 'basic')
+app.commandLine.appendSwitch('disable-background-timer-throttling')
+app.commandLine.appendSwitch('disable-backgrounding-occluded-windows')
+app.commandLine.appendSwitch('disable-renderer-backgrounding')
+/* A plugin paints on its own surface, and a GPU-composited surface does not
+   reach the screencast; software compositing puts it back in the page bitmap. */
+if (env.DSH_FLASH_SOFTWARE === '1') {
+  app.commandLine.appendSwitch('disable-gpu')
+  app.commandLine.appendSwitch('disable-gpu-compositing')
+  app.commandLine.appendSwitch('in-process-gpu')
+}
+if (env.DSH_FLASH_PORT) app.commandLine.appendSwitch('remote-debugging-port', env.DSH_FLASH_PORT)
+if (env.DSH_FLASH_UDD) app.commandLine.appendSwitch('user-data-dir', env.DSH_FLASH_UDD)
+if (env.DSH_FLASH_PLUGIN) {
+  app.commandLine.appendSwitch('ppapi-flash-path', env.DSH_FLASH_PLUGIN)
+  app.commandLine.appendSwitch('ppapi-flash-version', env.DSH_FLASH_VERSION || '32.0.0.371')
+  app.commandLine.appendSwitch('allow-outdated-plugins')
+  /* The plugin process is sandboxed in a way that cannot open a plugin living
+     outside the app bundle: it fails with "file system sandbox blocked open()"
+     and the page then reports no usable Flash. This app renders one page we
+     name ourselves, so it does not need that sandbox. */
+  app.commandLine.appendSwitch('no-sandbox')
+}
+
+app.on('window-all-closed', () => {
+  /* A closed window is the person closing the mirror, not the app's business. */
+})
+
+/* A plugin paints on a surface the debugging protocol's screencast does not
+   see, so the app hands out its own frames over a loopback port. */
+let capture = null
+let latest = null
+/* A plugin surface cannot be screencast, so this app is the capture source.
+   Capturing inside the request would make the picture cost the poll interval
+   plus the capture itself; a pump keeps one JPEG ready and requests return it. */
+let latestJpeg = null
+let latestAt = 0
+let pumping = false
+let pumpTimer = 0
+let painted = 0
+
+function alive(win) {
+  try {
+    return win !== null && win !== undefined && win.isDestroyed() !== true
+  } catch {
+    return false
+  }
+}
+
+/* A timer is its own fault domain: a window that closed between ticks must end
+   the pump, not throw into the app's process. */
+function pump() {
+  /* Offscreen rendering already hands every frame over in its paint callback;
+     a screenshot pump on top of it could only write a staler picture back. */
+  if (painted > 0) {
+    if (pumpTimer !== 0) clearInterval(pumpTimer)
+    pumpTimer = 0
+    return
+  }
+  if (pumping === true) return
+  if (alive(capture) !== true) {
+    if (pumpTimer !== 0) clearInterval(pumpTimer)
+    pumpTimer = 0
+    return
+  }
+  pumping = true
+  try {
+    capture.webContents.capturePage()
+      .then((image) => {
+        if (alive(capture) !== true) return
+        latest = image
+        latestJpeg = image.toJPEG(Number(env.DSH_FLASH_JPEG_QUALITY || 72))
+        latestAt = Date.now()
+      })
+      .catch(() => {})
+      .finally(() => { pumping = false })
+  } catch {
+    pumping = false
+  }
+}
+
+app.whenReady().then(() => {
+  const window = new BrowserWindow({
+    width: 1440,
+    height: 900,
+    x: -3000,
+    y: -3000,
+    /* Never a window on anybody's screen: the picture belongs in the column
+       that asked for it, and a game window parked off to the side is exactly
+       what this must not add to the desktop. */
+    show: false,
+    /* Without this macOS pulls a window placed past the edge of the screen back
+       onto it; the window is meant to stay where nobody can see it. */
+    enableLargerThanScreen: true,
+    frame: false,
+    skipTaskbar: true,
+    hasShadow: false,
+    focusable: false,
+    webPreferences: {
+      plugins: true,
+      backgroundThrottling: false,
+      contextIsolation: true,
+      /* macOS does not paint a window nobody can see, which used to force this
+         app to put a real game window on the desktop. Offscreen rendering
+         paints into a bitmap instead, so the page exists only in the column. */
+      offscreen: true,
+      useSharedTexture: false,
+      paintWhenInitiallyHidden: true,
+    },
+  })
+  capture = window
+  /* The Dock wanted to show this as a running app; the only thing it runs is
+     the picture in someone's column. */
+  if (app.dock !== undefined && app.dock !== null) app.dock.hide()
+  /* A running app with a menu puts its name in the menu bar the moment macOS
+     activates it, which is a second way for this to appear on someone's
+     desktop. No menu, and an accessory app: only the picture in the column. */
+  Menu.setApplicationMenu(null)
+  if (typeof app.setActivationPolicy === 'function') app.setActivationPolicy('accessory')
+  /* Offscreen frames arrive here; nothing is ever shown on a display. A paint
+     callback is its own fault domain: one failed frame must not end the app. */
+  try {
+    window.webContents.setFrameRate(Number(env.DSH_FLASH_FRAME_RATE || 30))
+    window.webContents.on('paint', (event, dirty, image) => {
+      try {
+        latest = image
+        latestJpeg = image.toJPEG(Number(env.DSH_FLASH_JPEG_QUALITY || 72))
+        latestAt = Date.now()
+        painted += 1
+      } catch {
+        /* a frame that cannot be encoded is skipped; the next one may work */
+      }
+    })
+  } catch {
+    /* an Electron without offscreen painting falls back to the capture pump */
+  }
+  window.loadURL(env.DSH_FLASH_URL || 'about:blank')
+  /* Faster than the sidecar asks: it then always finds a fresh picture. */
+  pumpTimer = setInterval(pump, Number(env.DSH_FLASH_PUMP_MS || 40))
+
+  const port = Number(env.DSH_FLASH_BRIDGE_PORT || 0)
+  if (port > 0) {
+    http.createServer(async (request, response) => {
+      if (capture === null || !request.url) {
+        response.writeHead(404).end()
+        return
+      }
+      if (request.url.startsWith('/info')) {
+        const size = latest === null ? null : latest.getSize()
+        response.writeHead(200, { 'content-type': 'application/json' })
+        response.end(JSON.stringify({ size, age: latestAt === 0 ? null : Date.now() - latestAt, visible: capture.isVisible(), opacity: capture.getOpacity(), painted, bounds: capture.getBounds(), url: capture.webContents.getURL(), title: capture.webContents.getTitle() }))
+        return
+      }
+      if (request.url.startsWith('/resize')) {
+        /* The column is a tall, narrow pane: a 16:10 window letterboxes the
+           game into a strip. Resizing the window to the pane makes the picture
+           fill it and the JPEG smaller, since capture is window-sized. */
+        try {
+          const size = new URL(request.url, 'http://x').searchParams
+          const width = Math.max(200, Math.min(2560, Number(size.get('w') || 0)))
+          const height = Math.max(200, Math.min(2560, Number(size.get('h') || 0)))
+          if (Number.isFinite(width) && Number.isFinite(height)) {
+            if (alive(capture) !== true) { response.writeHead(503); response.end(); return }
+            capture.setBounds({ x: -3000, y: -3000, width: Math.round(width), height: Math.round(height) })
+          }
+          const bounds = capture.getBounds()
+          response.writeHead(200, { 'content-type': 'application/json' })
+          response.end(JSON.stringify({ bounds }))
+        } catch {
+          response.writeHead(500).end()
+        }
+        return
+      }
+      if (request.url.startsWith('/input')) {
+        /* Input goes straight into the page instead of round-tripping through
+           the debugging protocol: a press arrives in a few milliseconds, and a
+           game that reads its mouse every frame is not left behind. */
+        try {
+          if (request.method !== 'POST') { response.writeHead(405).end(); return }
+          const chunks = []
+          let bytes = 0
+          for await (const chunk of request) {
+            bytes += chunk.length
+            if (bytes > 8192) { response.writeHead(413).end(); return }
+            chunks.push(chunk)
+          }
+          const body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')
+          if (alive(capture) !== true) { response.writeHead(503).end(); return }
+          const event = {}
+          for (const field of ['type', 'x', 'y', 'button', 'clickCount', 'deltaX', 'deltaY', 'keyCode', 'modifiers']) {
+            if (body[field] !== undefined && body[field] !== null) event[field] = body[field]
+          }
+          if (typeof event.type !== 'string' || event.type === '') { response.writeHead(400).end(); return }
+          capture.webContents.sendInputEvent(event)
+          response.writeHead(200, { 'content-type': 'application/json' })
+          response.end('{"ok":true}')
+        } catch {
+          response.writeHead(500).end()
+        }
+        return
+      }
+      if (!request.url.startsWith('/frame')) {
+        response.writeHead(404).end()
+        return
+      }
+      try {
+        const asked = Number(new URL(request.url, 'http://x').searchParams.get('q') || 0) // ui-copy-ignore
+        let jpeg = latestJpeg
+        if (jpeg === null || (asked > 0 && asked !== Number(env.DSH_FLASH_JPEG_QUALITY || 72))) {
+          const image = latest !== null ? latest : alive(capture) === true ? await capture.webContents.capturePage() : null
+          if (image === null) { response.writeHead(503); response.end(); return }
+          jpeg = image.toJPEG(asked > 0 ? asked : Number(env.DSH_FLASH_JPEG_QUALITY || 72))
+        }
+        response.writeHead(200, { 'content-type': 'image/jpeg', 'content-length': jpeg.length }) // ui-copy-ignore
+        response.end(jpeg)
+      } catch {
+        response.writeHead(503).end()
+      }
+    }).listen(port, '127.0.0.1')
+  }
+})

package/runtime/flash-app/package.json

@@ -0,0 +1 @@
+{"name":"dsh-flash-app","version":"1.0.0","private":true,"main":"main.js"}

package/runtime/flash-setup.mjs

@@ -0,0 +1,151 @@
+/* A page from the Flash era needs two things this plugin cannot put in its own
+   tarball: a browser that still speaks PPAPI, and the plugin itself. The first
+   is a Chromium build (BSD, redistributable); the second is Adobe's, which may
+   not be shipped. So the switch fetches both once, into the person's own state
+   directory, and afterwards the plugin works offline. */
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, renameSync, rmSync, statSync, readdirSync, copyFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** Root of everything the Flash runtime keeps. */
+export const FLASH_DIR = join(homedir(), '.dsh', 'inner-browser-use', 'flash')
+
+/** Chromium 87 is the last build with PPAPI, and the last Electron 11. */
+const ELECTRON_VERSION = process.env.DSH_FLASH_ELECTRON_VERSION ?? '11.3.0'
+
+/** Launchers known to carry a Pepper Flash plugin build. */
+const LAUNCHERS = ['百田游戏安全管家.app', '百田游戏管家.app', 'Flash Player.app']
+
+/** Where a Pepper Flash plugin may already live on this machine. */
+const PLUGIN_PATHS = LAUNCHERS.flatMap((name) => [
+  join('/Applications', name, 'Contents', 'Resources', 'libs', 'PepperFlashPlayer.plugin'),
+  join(homedir(), 'Applications', name, 'Contents', 'Resources', 'libs', 'PepperFlashPlayer.plugin'),
+  join('/Library/Internet Plug-Ins', 'PepperFlashPlayer.plugin'),
+])
+
+/** @param {string} path - candidate. @returns {boolean} true when it is a plugin bundle. */
+function isPlugin(path) {
+  return existsSync(join(path, 'Contents', 'Info.plist'))
+}
+
+/** @returns {string | undefined} the plugin already installed here. */
+export function findPlugin() {
+  const noted = process.env.DSH_INNER_BROWSER_FLASH_PLUGIN
+  if (noted !== undefined && existsSync(noted)) return noted
+  const own = join(FLASH_DIR, 'plugin', 'PepperFlashPlayer.plugin')
+  if (isPlugin(own)) return own
+  return PLUGIN_PATHS.find((path) => isPlugin(path))
+}
+
+/** @param {string} bundle - a .plugin bundle. @returns {string} the loadable plugin file. */
+export function pluginExecutable(bundle) {
+  const inner = join(bundle, 'Contents', 'MacOS', 'PepperFlashPlayer')
+  return existsSync(inner) ? inner : bundle
+}
+
+/** @returns {string} where the Chromium 87 binary would be. */
+export function electronPath() {
+  return join(FLASH_DIR, 'electron', 'Electron.app', 'Contents', 'MacOS', 'Electron')
+}
+
+/** @returns {{ electron: string, plugin: string } | null} the runtime, when ready. */
+export function readyFlash() {
+  const electron = electronPath()
+  const bundle = findPlugin()
+  if (!existsSync(electron) || bundle === undefined) return null
+  return { electron, plugin: pluginExecutable(bundle) }
+}
+
+/** @returns {string} the Chromium 87 build matching this machine. */
+function electronUrl() {
+  const noted = process.env.DSH_FLASH_ELECTRON_URL
+  if (noted !== undefined) return noted
+  /* Flash exists as an x86_64 library only, so the browser that hosts it must
+     be x86_64 as well; on Apple silicon both run under Rosetta. */
+  return `https://npmmirror.com/mirrors/electron/${ELECTRON_VERSION}/electron-v${ELECTRON_VERSION}-darwin-x64.zip`
+}
+
+/**
+ * Fetch one URL to a file, saying how far along it is.
+ * @param {string} url - what to fetch.
+ * @param {string} file - where it lands.
+ * @param {(seen: number, total: number) => void} [progress] - byte counter.
+ * @returns {Promise<void>} resolves when the file is complete.
+ */
+async function download(url, file, progress) {
+  const response = await fetch(url, { redirect: 'follow' })
+  if (!response.ok) throw new Error(`flash: ${url} answered ${response.status}`)
+  const total = Number(response.headers.get('content-length') ?? 0)
+  const chunks = []
+  let seen = 0
+  for await (const chunk of response.body) {
+    chunks.push(chunk)
+    seen += chunk.length
+    progress?.(seen, total)
+  }
+  const body = Buffer.concat(chunks)
+  if (total > 0 && body.length !== total) throw new Error(`flash: short download (${body.length}/${total})`)
+  mkdirSync(join(file, '..'), { recursive: true })
+  await import('node:fs/promises').then((fs) => fs.writeFile(file, body))
+}
+
+/**
+ * Make the Flash runtime usable on this machine, fetching what is missing.
+ * @param {{ progress?: (line: string) => void }} [options] - reporting hook.
+ * @returns {Promise<{ electron: string, plugin: string }>} the runtime.
+ */
+export async function ensureFlash(options = {}) {
+  const say = options.progress ?? (() => {})
+  mkdirSync(FLASH_DIR, { recursive: true })
+  let plugin = findPlugin()
+
+  if (!existsSync(electronPath())) {
+    const zip = join(FLASH_DIR, 'cache', `electron-v${ELECTRON_VERSION}-darwin-x64.zip`)
+    if (!existsSync(zip) || statSync(zip).size < 40_000_000) {
+      const url = electronUrl()
+      say(`下载 Chromium 87（约 80 MB）: ${url}`)
+      let last = 0
+      await download(url, zip, (seen, total) => {
+        if (seen - last > 8_000_000) {
+          last = seen
+          say(`  ${Math.round(seen / 1e6)} MB${total === 0 ? '' : ` / ${Math.round(total / 1e6)} MB`}`)
+        }
+      })
+    }
+    const staging = join(FLASH_DIR, 'electron.tmp')
+    rmSync(staging, { recursive: true, force: true })
+    mkdirSync(staging, { recursive: true })
+    say('解压 Chromium 87')
+    execFileSync('/usr/bin/unzip', ['-q', '-o', zip, '-d', staging], { stdio: 'ignore' })
+    const app = join(staging, 'Electron.app')
+    if (!existsSync(app)) throw new Error('flash: the archive had no Electron.app')
+    rmSync(join(FLASH_DIR, 'electron'), { recursive: true, force: true })
+    renameSync(staging, join(FLASH_DIR, 'electron'))
+    say('Chromium 87 就绪')
+  }
+
+  if (plugin === undefined) {
+    throw new Error('flash: 这台机器上没有 Pepper Flash 插件；装一次任意带 Flash 的游戏客户端（例如百田游戏安全管家），或用 DSH_INNER_BROWSER_FLASH_PLUGIN 指向已有的 PepperFlashPlayer.plugin')
+  }
+
+  const electron = electronPath()
+  const pluginFile = pluginExecutable(plugin)
+  say(`Flash 运行时就绪: ${electron}`)
+  say(`插件: ${pluginFile}`)
+  return { electron, plugin: pluginFile }
+}
+
+/**
+ * Human-readable state, without fetching anything.
+ * @returns {{ ready: boolean, electron: boolean, plugin: string | null, dir: string }} the state.
+ */
+export function flashStatus() {
+  const plugin = findPlugin() ?? null
+  return {
+    ready: existsSync(electronPath()) && plugin !== null,
+    electron: existsSync(electronPath()),
+    plugin: plugin === null ? null : pluginExecutable(plugin),
+    dir: FLASH_DIR,
+  }
+}