Skip to content

A team of long-lived bots for DeepSeek Harness, with main bots, bot-to-bot messages and group chats.

44.6 KB
Raw Blame
// The start window (docs/plans/2026-10-26-start-window.md §1, §8, §11; windows-onboarding §3): the
// app's own small window that shows start/start.html while the engine boots. It holds the
// start's state and sends the page the whole of it on every change; at the end it grows into the
// team window's rect, and the hidden team window shows on the same rect. The rect maths, the
// growth, the snapshot and the checks are plain functions, so the tests run without Electron.
import { pathToFileURL } from 'node:url'
import { writeFile } from 'node:fs/promises'
import { within } from './copy-tree.mjs'

export const START_STATE = 'ds-bot:start-state'
export const START_ACT = 'ds-bot:start-act'

export const START_SIZE = { width: 720, height: 540 }
export const SHORT_START_SIZE = { width: 720, height: 500 }
// Work areas lower than this get the short start window.
const SHORT_WORK_AREA = 588
export const MAIN_SIZE = { width: 1320, height: 860 }
export const PHASES = ['data', 'engine', 'team']
// A start that copies a team from DSH gets a stage of its own for the copy once the copy runs
// (§6): the ring has three arcs while the import card asks, and goes back to three when the copy
// stops or the start goes on without it.
export const IMPORT_PHASES = ['data', 'import', 'engine', 'team']
const COPY_CARDS = ['copying', 'importFailed']
export const phasesOf = state => (state.done.includes('import') || COPY_CARDS.includes(state.card?.kind) ? IMPORT_PHASES : PHASES)
export const START_KINDS = ['first', 'later', 'moving']
export const WATCHDOG_MS = 180_000
export const TEAM_VIEW_MS = 20_000
export const DESTROY_AFTER_MS = 300
// The hand-off (§8): the start window does not resize (stepped setBounds repaints only now and
// then, and the whale in it stutters). The team window, already under it, fades in while the
// start window fades out; window opacity is the compositor's. The team page gets the whale at the
// top of its jump and holds it there through the fade, then glides it onto the avatar.
export const CROSSFADE = { duration: 220, step: 16 }
export const HOLD_MS = CROSSFADE.duration + 40
// How long the team page may take to draw the whale it is handed before the fade starts anyway.
export const TEAM_WAIT_MS = 150
export const TEAM_HANDOFF = 'ds-bot:handoff'
export const FAILURE_LINES = 200
// 〔保存日志…〕 saves this many of the latest log lines, after the same header as the copied details.
export const SAVED_LINES = 5000
// The DeepSeek theme's --bt-main and --bt-ink (ui-standard 2.1), as in start.css: the window's
// own background and caption symbols, which show before the page paints and where Mica is not.
const COLORS = { light: { main: '#fcfcfc', ink: '#141414' }, dark: { main: '#141414', ink: '#f2f2f2' } }
const CAPTION_HEIGHT = 40
export const PAINT_WAIT_MS = 3000
// A window that Windows has just shown is drawn a few frames before its page is (and its own
// opening transition runs over them): the start window shows see-through and turns opaque
// this long after.
export const OPEN_MS = 200
const sinceLaunch = () => String(Math.round(process.uptime() * 1000))

// What the page may ask, and in which views (null: in any). The cards of later pull requests
// send other names, which are refused.
const ACT_VIEWS = {
  handoffShow: ['handoff'],
  handoffDone: ['handoff'],
  retry: ['failed', 'watchdog'],
  wait: ['watchdog'],
  reloadView: ['viewFailed'],
  // 「换个位置…」 on the page (also under the 180 s question), and the cards it leads to
  // (「会放在…」, a place that cannot be used).
  pick: ['boot', 'card', 'watchdog'],
  answer: ['card'],
  // The import card's model and options, and the copying card's stop (windows-onboarding §4).
  importModel: ['card'],
  importOption: ['card'],
  // The failure page's update banner: 〔下载〕 or 〔重试〕 on it, and 「手动下载」.
  installUpdate: ['failed'],
  manualDownload: ['failed'],
  copyDetails: null,
  saveLog: null,
  // The page has drawn its first frame: the window shows.
  painted: null,
}
export const START_ACTS = Object.freeze(Object.keys(ACT_VIEWS))

/** Whether the main process takes this act from the start page in this view. */
export function acceptsAct(name, view) {
  if (typeof name !== 'string' || !Object.hasOwn(ACT_VIEWS, name)) return false
  const views = ACT_VIEWS[name]
  return views === null || views.includes(view)
}

/** Whether a frame shows exactly the start page that was loaded. */
export function isStartPage(frameUrl, loadedUrl) {
  try {
    const frame = new URL(frameUrl)
    return frame.protocol === 'file:' && frame.href === new URL(loadedUrl).href
  } catch {
    return false
  }
}

export const startUrl = (page, kind) => `${pathToFileURL(page).href}?start=${kind}`

/** The start window's content size on a display's work area. */
export const startSize = workArea => ({ ...(workArea.height < SHORT_WORK_AREA ? SHORT_START_SIZE : START_SIZE) })

export function centred(size, area) {
  return {
    x: area.x + Math.round((area.width - size.width) / 2),
    y: area.y + Math.round((area.height - size.height) / 2),
    width: size.width,
    height: size.height,
  }
}

/** A rect moved, and shrunk if it must be, to lie inside an area. */
export function clampInto(rect, area) {
  const width = Math.min(rect.width, area.width)
  const height = Math.min(rect.height, area.height)
  return {
    x: Math.min(Math.max(rect.x, area.x), area.x + area.width - width),
    y: Math.min(Math.max(rect.y, area.y), area.y + area.height - height),
    width,
    height,
  }
}

/** The team window's rect: centred on the start window, inside the work area. */
export function mainRect(start, area, size = MAIN_SIZE) {
  const x = Math.round(start.x + start.width / 2 - size.width / 2)
  const y = Math.round(start.y + start.height / 2 - size.height / 2)
  return clampInto({ x, y, width: size.width, height: size.height }, area)
}

/** CSS's cubic-bezier() as a function of the time fraction. */
export function cubicBezier(x1, y1, x2, y2) {
  const curve = (p1, p2) => {
    const c = 3 * p1
    const b = 3 * (p2 - p1) - c
    const a = 1 - c - b
    return s => ((a * s + b) * s + c) * s
  }
  const x = curve(x1, x2)
  const y = curve(y1, y2)
  return (t) => {
    if (t <= 0) return 0
    if (t >= 1) return 1
    // x is monotonic for control points inside [0, 1], so halving finds its parameter.
    let low = 0
    let high = 1
    for (let step = 0; step < 40; step += 1) {
      const mid = (low + high) / 2
      if (x(mid) < t) low = mid
      else high = mid
    }
    return y((low + high) / 2)
  }
}
/**
 * Where the start page's whale lands at the hand-off (start-window §8): the Main Bot's avatar as
 * the team view reported it, in CSS px of that page, turned into DIP and then into the start
 * page's own coordinates once the start window has grown onto the team window's rect. The team
 * page may be zoomed, so its viewport's width gives the scale. Undefined unless the report is a
 * plausible box inside the team view.
 * @param {unknown} report { x, y, width, height, viewportWidth, viewportHeight }
 * @param {{ team: { x: number, y: number, width: number }, start: { x: number, y: number } }} content
 *   the team window's content rect, and the start window's content origin once it has grown
 */
export function landingOf(report, { team, start }) {
  if (report === null || typeof report !== 'object') return undefined
  const [x, y, width, height, viewportWidth, viewportHeight] = ['x', 'y', 'width', 'height', 'viewportWidth', 'viewportHeight'].map(key => Number(report[key]))
  if (![x, y, width, height, viewportWidth, viewportHeight].every(Number.isFinite) || viewportWidth <= 0 || viewportHeight <= 0) return undefined
  if (width < 16 || height < 16 || x < 0 || y < 0 || x + width > viewportWidth || y + height > viewportHeight) return undefined
  const scale = team.width / viewportWidth
  const round = value => Math.round(value * 2) / 2
  return { x: round(team.x + x * scale - start.x), y: round(team.y + y * scale - start.y), size: round(((width + height) / 2) * scale) }
}

/**
 * The whale the start page hands over, in CSS px of the team page: the start page's own box
 * ({ x, y, size } in its CSS px, which are DIP) through both windows' content origins and the
 * team page's zoom. Undefined unless it is a plausible box.
 * @param {unknown} whale { x, y, size }
 * @param {{ start: { x: number, y: number }, team: { x: number, y: number, width: number }, viewportWidth: number }} windows
 */
export function handoffBox(whale, { start, team, viewportWidth }) {
  if (whale === null || typeof whale !== 'object') return undefined
  const [x, y, size] = ['x', 'y', 'size'].map(key => Number(whale[key]))
  if (![x, y, size, viewportWidth].every(Number.isFinite) || size < 16 || viewportWidth <= 0) return undefined
  const zoom = team.width / viewportWidth
  const round = value => Math.round(value * 2) / 2
  return { x: round((start.x + x - team.x) / zoom), y: round((start.y + y - team.y) / zoom), size: round(size / zoom) }
}

// When the page never sends handoffShow, the main process shows the team window itself. The page
// sends it about 0.72 s after ready on a celebrating hand-off and 0.22 s otherwise (start-window §8).
export const fallbackMs = ({ start, celebrate }) => (start === 'first' || celebrate ? 2500 : 800)

// The reasons of the failure page (windows-onboarding §3), most specific first: a Host that
// stopped says so and carries its own error output, which names the cause. A folder of the data's
// that is not there (a drive that is gone) is 'missing', after the program's own files.
const MISSING = /ENOENT: no such file or directory, (?:mkdir|open|access|stat|lstat|scandir|opendir|rename|copyfile) /u
const REASONS = [
  ['permission', /\b(?:EACCES|EPERM)\b|permission denied|operation not permitted|access is denied/iu],
  ['space', /\b(?:ENOSPC|EDQUOT)\b|no space left|not enough space|disk (?:is )?full/iu],
  ['files', /\b(?:MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND)\b|cannot find (?:module|package)|could not load its own bundles|not a valid Win32 application|0xC0000135|3221225781/iu],
  ['engine', /DSH Host stopped|engine's web server/iu],
]

// Only a missing file of the program's own says that the install is incomplete: a data folder
// on a drive that is gone is missing too, and so is a workspace.
function missingOwnFile(error, text, program) {
  if (!/\bENOENT\b/u.test(text)) return false
  const paths = [error?.path, ...[...text.matchAll(/ENOENT: [^,\n]*, \w+ '([^'\n]+)'/gu)].map(match => match[1])]
  return paths.some(path => typeof path === 'string' && program.some(folder => within(path, folder)))
}

/**
 * @param {{ program?: string[] }} where `program`: the folders of the app's own files
 * @returns {'permission' | 'space' | 'files' | 'engine' | 'missing' | 'other'}
 */
export function failureReason(error, { program = [] } = {}) {
  const code = typeof error?.code === 'string' ? error.code : ''
  const message = error instanceof Error ? error.message : String(error ?? '')
  const text = `${code} ${message}`
  for (const [reason, pattern] of REASONS) {
    if (pattern.test(text) || (reason === 'files' && missingOwnFile(error, text, program))) return reason
  }
  return MISSING.test(text) ? 'missing' : 'other'
}

// The Main Bot that a kept team's sidebar shows first (ds-bot's channel.js: mainBotIds[0]; an
// older state.json has mainBotId), whose name the greeting says on a reinstall.
export function mainBotName(state) {
  const id = Array.isArray(state?.mainBotIds) ? state.mainBotIds[0] : state?.mainBotId
  const name = typeof id === 'string' ? state.bots?.[id]?.name : undefined
  return typeof name === 'string' && name.trim() !== '' ? name.trim() : undefined
}

// What the start knows about the team it opens. The ring page no longer shows it (no greeting or
// hint lines since 2026-10-30); the snapshot keeps it for now. previewNotice: DSH shows its
// preview notice when the Session is ready and the main view has no non-empty Session, which a
// data folder without a team always has.
export function explainOf({ offered = false, team } = {}) {
  if (offered) return { mode: 'import', nextStep: false, previewNotice: false }
  if (team !== undefined) {
    const name = mainBotName(team.team)
    return { mode: 'reinstall', bots: team.bots, groups: team.rooms, ...(name === undefined ? {} : { name }), nextStep: false, previewNotice: false }
  }
  return { mode: 'new', nextStep: true, previewNotice: true }
}

export const clockMs = (clock, now) => clock.base + (clock.running ? Math.max(0, now - clock.from) : 0)

/** The whole state the page gets: the page computes the elapsed time from clock.ms at clock.at. */
export function startSnapshot(state, now) {
  const snapshot = {
    v: 1,
    lang: state.lang,
    start: state.start,
    motion: state.motion,
    // Windows draws the caption buttons over the page's band; macOS and Linux a system title bar.
    frame: state.frame,
    view: state.view,
    phases: [...phasesOf(state)],
    phase: phasesOf(state).find(phase => !state.done.includes(phase)) ?? 'team',
    done: phasesOf(state).filter(phase => state.done.includes(phase)),
    clock: { ms: Math.round(clockMs(state.clock, now)), at: now, running: state.clock.running, rate: 1 },
    explain: { ...state.explain },
    celebrate: state.celebrate,
    // The window is on screen: the page's entrance starts (start.js).
    shown: state.shown === true,
  }
  if (state.hint !== undefined) snapshot.hint = { ...state.hint }
  if (state.place !== undefined) snapshot.place = { ...state.place }
  if (state.card !== undefined) snapshot.card = { ...state.card }
  if (state.failure !== undefined) snapshot.failure = { reason: state.failure.reason, log: [...state.failure.log] }
  if (state.landing !== undefined) snapshot.landing = { ...state.landing }
  if (state.update !== undefined) snapshot.update = { ...state.update }
  return snapshot
}

export const detailsText = ({ version, platform, arch, reason, lines }) => [`DS Bot ${version} (${platform} ${arch})`, `reason: ${reason}`, '', ...lines].join('\n')

const note = message => { console.log(`DS Bot: start window: ${message}`) }
// The page sends a button's detail as { value }; anything else counts as none.
const valueOf = payload => (payload !== null && typeof payload === 'object' && typeof payload.value === 'string' ? payload.value.slice(0, 40) : undefined)
// An option of the import card: its name and whether it is ticked.
const optionOf = payload => (payload !== null && typeof payload === 'object' && typeof payload.option === 'string' ? { option: payload.option.slice(0, 40), value: payload.value === true } : undefined)

export class StartWindow {
  #o
  #window
  #url
  #painted = Promise.resolve()
  #state
  #explain = explainOf()
  #asks = 0
  #watchAt = WATCHDOG_MS
  #timers = {}
  #phaseAt = 0
  #readyAt = 0
  #showAt = 0
  #handing = false
  #under = false
  #revealed = false
  // Whether the engine of this attempt is up; the stages done say where the whale is, which a
  // retry never moves back.
  #engineUp = false
  // What a dialog of the window (the folder picker) or a card keeps waiting: the hand-off, which
  // would take the window and the dialog's owner away, and the 20 s check's verdict.
  #readyHeld = false
  // The Main Bot avatar's place that came with ready(), kept while the hand-off is held.
  #readyReport
  #heldAt = 0
  #viewLate = false
  #teamShown
  #showTeam

  /**
   * @param {{
   *   electron: { BrowserWindow: any, ipcMain: any, screen: any, shell: any, clipboard: any, nativeTheme: any, systemPreferences: any },
   *   page: string, preload: string, icon: string, mica: boolean, devTools: boolean, css?: string,
   *   lang: () => 'zh' | 'en', motion: string, version: string, program: string[],
   *   log: { dir: string, tail: (count: number) => string[] },
   *   mainWindow: () => any,
   *   onRetry: () => void, onReload: () => void, onClose: () => void,
   *   onPick?: (value?: string) => void, onAnswer?: (value?: string) => void,
   *   saveAs?: (win: any, name: string) => Promise<string | undefined>,
   *   onUpdate?: (name: 'installUpdate' | 'manualDownload') => void,
   *   onImport?: (name: 'importModel' | 'importOption', value: unknown) => void,
   * }} options `lang` is asked at each open; `program` names the folders of the app's own files;
   *   `onClose` runs when the user closes the start window before the hand-off; `onPick` when
   *   the page asks for the folder picker ('changePlace' from its place line, nothing from a
   *   card's 〔重新选〕; on a later start the line's button moves the data), `onAnswer` with a
   *   card's answer ('use' for 〔继续〕 on 「会放在…」), `onUpdate` with a button of the failure
   *   page's update banner, `onImport` with the import card's model and options and the copying
   *   card's stop.
   */
  constructor(options) {
    this.#o = options
    this.#teamShown = new Promise((resolve) => { this.#showTeam = resolve })
    options.electron.ipcMain.handle(START_ACT, (event, name, payload) => this.#act(event, name, payload))
  }

  get kind() { return this.#state?.start }

  /** Settles once the current window has painted its first frame (or has had time to). */
  get painted() { return this.#painted }

  /** Settles once the team window has shown at a hand-off. */
  get teamShown() { return this.#teamShown }

  /** Whether the team window has shown at this start's hand-off. */
  get revealed() { return this.#revealed }

  /** Opens the window, unless one is open, with a fresh state for this kind of start. */
  open(kind) {
    if (this.#open()) return
    const { BrowserWindow, screen, nativeTheme } = this.#o.electron
    const start = START_KINDS.includes(kind) ? kind : 'later'
    this.#reset(start)
    const area = screen.getDisplayNearestPoint(screen.getCursorScreenPoint()).workArea
    const win32 = process.platform === 'win32'
    const { mica } = this.#o
    const colors = this.#colors()
    const rect = centred(startSize(area), area)
    const win = new BrowserWindow({
      ...rect,
      useContentSize: true, resizable: false, maximizable: false, fullscreenable: false, minimizable: true,
      show: false, title: 'DS Bot', icon: this.#o.icon,
      backgroundColor: mica ? '#00000000' : colors.main,
      // Frameless with the system minimize and close buttons over the page's empty 40 px band.
      ...(win32 ? {
        titleBarStyle: 'hidden',
        titleBarOverlay: { height: CAPTION_HEIGHT, color: mica ? '#00000000' : colors.main, symbolColor: colors.ink },
        ...(mica ? { backgroundMaterial: 'mica' } : {}),
      } : {}),
      webPreferences: {
        preload: this.#o.preload, contextIsolation: true, sandbox: true, nodeIntegration: false, webviewTag: false, spellcheck: false,
        // The page paces the whale and the hand-off on timers, which a covered or minimized
        // window would otherwise run once a second.
        backgroundThrottling: false,
        additionalArguments: [`--ds-bot-start=${pathToFileURL(this.#o.page).href}`],
      },
    })
    // At a fractional display scale, Electron 44 on Windows makes a frameless window a few pixels
    // larger than asked; setting the size again once it exists gives the size asked for.
    win.setContentBounds(rect)
    this.#window = win
    this.#url = startUrl(this.#o.page, start)
    const contents = win.webContents
    // The window shows once its page says it has drawn its first frame (the 'painted' act), so it
    // never opens on an empty panel: the page's whale and ring come about 1 s after the window.
    win.once('ready-to-show', () => { note(`the start page painted ${sinceLaunch()} ms after launch`) })
    this.#later('show', PAINT_WAIT_MS, () => { this.#showStart('the page did not say it painted', { now: true }) })
    this.#painted = new Promise((resolve) => {
      win.once('ready-to-show', resolve)
      contents.once('did-finish-load', resolve)
      setTimeout(resolve, PAINT_WAIT_MS)
    })
    win.on('page-title-updated', (event) => { event.preventDefault() })
    contents.on('will-navigate', (event) => { event.preventDefault() })
    contents.setWindowOpenHandler(() => ({ action: 'deny' }))
    // A reload loses what the preload kept, so the page gets the state again.
    // The page loads only its own files; the app's picker brings its sheet (page-card.css).
    contents.on('dom-ready', () => {
      if (this.#o.css) void contents.insertCSS(this.#o.css)
      this.#send()
    })
    contents.on('render-process-gone', (_event, details) => { note(`the page's renderer stopped (${String(details?.reason)})`) })
    if (this.#o.devTools) {
      contents.on('before-input-event', (_event, input) => {
        if (input.type === 'keyDown' && (input.key === 'F12' || (input.control && input.shift && input.key.toLowerCase() === 'i'))) contents.toggleDevTools()
      })
    }
    const recolor = () => {
      if (win.isDestroyed()) return
      const next = this.#colors()
      if (win32) win.setTitleBarOverlay({ color: mica ? '#00000000' : next.main, symbolColor: next.ink })
      if (!mica) win.setBackgroundColor(next.main)
    }
    nativeTheme.on('updated', recolor)
    win.once('closed', () => {
      nativeTheme.off('updated', recolor)
      if (this.#window !== win) return
      this.#window = undefined
      this.#clearTimers()
      if (!this.#revealed) this.#o.onClose()
    })
    void win.loadURL(this.#url).catch((error) => { note(`the start page did not load: ${error instanceof Error ? error.message : String(error)}`) })
  }

  /** The window that dialogs belong to, while it is the one showing; a dialog never opens over nothing. */
  owner() {
    if (!this.#open() || this.#revealed) return undefined
    this.#showStart('a dialog', { now: true })
    return this.#window
  }

  // Shown see-through, then opaque after OPEN_MS; `now` (a dialog, a page that never painted)
  // does not wait. The page starts the whale's entrance once the snapshot says `shown`.
  #showStart(why, { now = false } = {}) {
    this.#clear('show')
    const win = this.#window
    if (!this.#open()) return
    if (!win.isVisible()) {
      if (!now) win.setOpacity(0)
      win.show()
      note(`${this.#state.start} start window shown (${why}) ${sinceLaunch()} ms after launch`)
      if (!now) { this.#later('opaque', OPEN_MS, () => { this.#opaque() }); return }
    }
    if (now) this.#opaque()
  }

  #opaque() {
    this.#clear('opaque')
    if (!this.#open() || this.#state.shown) return
    this.#window.setOpacity(1)
    this.#update({ shown: true })
  }

  /** Brings the start window back while it is the one showing. */
  focus() {
    if (!this.#open() || this.#revealed) return false
    this.#showStart('focus', { now: true })
    const win = this.#window
    if (win.isMinimized()) win.restore()
    win.show()
    win.focus()
    return true
  }

  explain(explain) {
    this.#explain = { ...explain }
    if (this.#open()) this.#update({ explain: this.#explain })
  }

  /**
   * The line that says where the data goes, with 「换个位置…」 (start-window §2; a first start, or a
   * later one whose drive runs low, §5): the drive and its free space, or the folder. Undefined
   * takes the line away.
   * @param {{ drive?: string, path?: string, free?: string } | undefined} place
   */
  place(place) {
    if (this.#open()) this.#update({ place: place === undefined ? undefined : { ...place } })
  }

  /** A short drive's one-line note for the first 10 s (§4), or none. */
  hint(hint) {
    if (this.#open()) this.#update({ hint: hint === undefined ? undefined : { ...hint } })
  }

  /**
   * A card on the sheet while the start boots or the data moves (the clock stands still), or
   * none: back to the boot or the move. The cards of a place (「会放在…」, a place that cannot be
   * used, a later start's 「搬到这个文件夹?」), of the first run's import and of a move that did
   * not go through.
   * @param {{ kind: string, [field: string]: unknown } | undefined} card
   * @returns {boolean} whether the window shows it: not on the failure page or at the hand-off
   */
  card(card) {
    if (!this.#open() || !['boot', 'card', 'watchdog', 'moving'].includes(this.#state.view)) return false
    if (card === undefined && this.#state.view !== 'card') return false
    // Back in the boot, a 180 s question that the card replaced comes straight back.
    const back = this.#state.start === 'moving' ? 'moving' : 'boot'
    this.#update(card === undefined ? { view: back, card: undefined } : { view: 'card', card: { ...card } })
    if (card === undefined) this.#resume()
    return true
  }

  /**
   * The start begins again in another folder (§7): the stages go back to the start, the whale
   * sinks and surfaces with its arcs emptied, and the clock starts from 0. The first success after
   * it celebrates, as after a retry.
   */
  restart() {
    if (!this.#open()) return
    note('starting over in another folder')
    this.#engineUp = false
    this.#holdsOff()
    this.#watchAt = WATCHDOG_MS
    this.#phaseAt = Date.now()
    this.#clear('teamView')
    this.#update({ view: 'boot', done: [], card: undefined, failure: undefined, update: undefined, celebrate: true, clock: { base: 0, from: Date.now(), running: true } })
  }

  /**
   * The data moves in the middle of a later start (「换个位置…」 on its place line, §5): the page
   * loads again as the move's start, and a hand-off that waited goes with the start it was for.
   */
  moving() {
    if (!this.#open()) return
    note('the data moves: the start window becomes the move\'s')
    this.#url = startUrl(this.#o.page, 'moving')
    this.#reset('moving')
    void this.#window.loadURL(this.#url).catch((error) => { note(`the start page did not load: ${error instanceof Error ? error.message : String(error)}`) })
  }

  /**
   * The clock stands still while the user answers a dialog: thinking time is not the engine's.
   * The hand-off and the 20 s check wait for the answer too (see ready()).
   */
  async asking(promise) {
    this.#asks += 1
    this.#refresh()
    try {
      return await promise
    } finally {
      this.#asks -= 1
      this.#refresh()
      this.#resume()
    }
  }

  // What waited for the dialogs to close and the card to go.
  #resume() {
    if (this.#asks > 0 || !this.#open() || this.#state.view !== 'boot') return
    if (this.#readyHeld) {
      this.#readyHeld = false
      note(`the hand-off waited ${String(Date.now() - this.#heldAt)} ms for the answer`)
      this.ready(this.#readyReport)
    } else if (this.#viewLate) {
      this.#viewLate = false
      this.#teamViewLate()
    }
  }

  #holdsOff() {
    if (this.#readyHeld) note(`the held hand-off is dropped after ${String(Date.now() - this.#heldAt)} ms: the start goes on elsewhere`)
    this.#readyHeld = false
    this.#readyReport = undefined
    this.#viewLate = false
  }

  /** The data folder, the import or the engine is ready; the engine also again after a retry. */
  done(phase) {
    if (!this.#open() || !['data', 'import', 'engine'].includes(phase)) return
    const again = this.#state.done.includes(phase)
    if (again && (phase !== 'engine' || this.#engineUp)) return
    if (phase === 'engine') this.#engineUp = true
    note(`${phase} took ${String(Date.now() - this.#phaseAt)} ms`)
    this.#phaseAt = Date.now()
    // The engine came up while the 180 s question was open: the question goes.
    this.#update({ ...(again ? {} : { done: [...this.#state.done, phase] }), ...(this.#state.view === 'watchdog' ? { view: 'boot' } : {}) })
  }

  /**
   * The engine that warmed up while the import card waited has stopped for the copy: its stage
   * is open again until the engine of the copied team is up.
   */
  engineDown() {
    if (!this.#open() || !this.#state.done.includes('engine')) return
    this.#engineUp = false
    this.#update({ done: this.#state.done.filter(phase => phase !== 'engine') })
  }

  /** The engine's page started loading in the hidden team window: it has 20 s to call ready(). */
  teamLoading() {
    if (!this.#open()) return
    this.#later('teamView', TEAM_VIEW_MS, () => { this.#teamViewLate() })
  }

  #teamViewLate() {
    if (!['boot', 'card'].includes(this.#state.view)) return
    // A dialog or a card is up: the verdict waits for the answer (#resume).
    if (this.#asks > 0 || this.#state.view === 'card') { this.#viewLate = true; return }
    note(`the team view did not call ready() within ${String(TEAM_VIEW_MS / 1000)} s`)
    this.#update({ view: 'viewFailed', failure: { reason: 'other', log: this.#o.log.tail(FAILURE_LINES) } })
  }

  /**
   * dsBotApp.ready() from the team view: the hand-off starts. While a dialog of the window or
   * a card is up (the folder picker, 「会放在…」), it waits: the hand-off would take the window,
   * and with it the dialog's owner, away while the user is still choosing where the data goes.
   */
  ready(report) {
    if (!this.#open() || !['boot', 'card', 'viewFailed'].includes(this.#state.view) || !this.#engineUp) return
    this.#clear('teamView')
    this.#readyReport = report
    if (this.#asks > 0 || this.#state.view === 'card') {
      if (!this.#readyHeld) {
        note('the team view is ready; the hand-off waits for the answer')
        this.#heldAt = Date.now()
      }
      this.#readyHeld = true
      return
    }
    this.#readyHeld = false
    const now = Date.now()
    note(`team took ${String(now - this.#phaseAt)} ms`)
    this.#readyAt = now
    // A team view that loads after its 20 s goes in without a celebration (§7).
    const celebrate = this.#state.celebrate && this.#state.view !== 'viewFailed'
    this.#update({ view: 'handoff', done: [...phasesOf(this.#state)], celebrate, failure: undefined, landing: this.#landing(report) })
    const main = this.#o.mainWindow()
    if (main !== undefined && !main.isDestroyed() && !this.#window.isMinimized()) this.#underlay(main)
    this.#later('fallback', fallbackMs(this.#state), () => {
      note('the page did not send handoffShow')
      this.#handoffShow({ grow: false })
    })
  }

  /**
   * The failure page: in this window, or in a new one when the team window was already showing.
   * @param {string} kind the kind of start when no start window has opened yet
   */
  fail(error, kind = 'later') {
    const showing = this.#revealed
    // The page's hand-off empties it for the growth and cannot be undone there: a fresh page
    // draws the failure.
    const emptied = !showing && this.#open() && this.#state.view === 'handoff'
    if (showing) {
      this.#destroy()
      const main = this.#o.mainWindow()
      if (main !== undefined && !main.isDestroyed()) main.hide()
    }
    if (!this.#open()) this.open(showing || this.#state === undefined ? kind : this.#state.start)
    this.#cancelHandoff()
    this.#holdsOff()
    this.#clear('teamView')
    this.#clear('fallback')
    this.#update({ view: 'failed', failure: { reason: failureReason(error, { program: this.#o.program }), log: this.#o.log.tail(FAILURE_LINES) } })
    if (emptied) this.#window.webContents.reload()
  }

  /**
   * The failure page's update banner (start-window §7), or none: a new version that may fix what
   * keeps this one from starting. A retry takes it away.
   * @param {{ state: 'available' | 'downloading' | 'installing' | 'failed', version: string, page?: boolean, percent?: number, received?: number, total?: number } | undefined} update
   *   `page`: the version installs from its release page, not by itself; `received` and `total` in MB
   */
  update(update) {
    if (!this.#open() || this.#state.view !== 'failed') return
    this.#update({ update: update === undefined ? undefined : { ...update } })
  }

  /** The team window's rect: centred on the start window, inside that display's work area. */
  mainBounds() {
    const { screen } = this.#o.electron
    if (!this.#open()) return centred(clampInto({ x: 0, y: 0, ...MAIN_SIZE }, screen.getPrimaryDisplay().workArea), screen.getPrimaryDisplay().workArea)
    const start = this.#window.getNormalBounds()
    return mainRect(start, screen.getDisplayMatching(start).workArea)
  }

  // The whale's landing for this hand-off: the team window goes on its rect now (handoffShow
  // places it again, in case the start window is dragged meanwhile), and the start window's frame
  // offset carries over to the rect it grows to. The team page measured itself at the size the
  // window had before that. The landing is optional: anything odd, and the whale dives. A
  // minimized start window does not grow, and its bounds would not say where it is.
  #landing(report) {
    const main = this.#o.mainWindow()
    if (main === undefined || main.isDestroyed() || this.#window.isMinimized()) return undefined
    if (report === undefined) { note('no place to land: the whale dives'); return undefined }
    try {
      const measured = main.getContentBounds()
      const rect = this.placeMain(main)
      const team = main.getContentBounds()
      const outer = this.#window.getBounds()
      const inner = this.#window.getContentBounds()
      const landing = landingOf(report, { team: { x: team.x, y: team.y, width: measured.width }, start: { x: rect.x + inner.x - outer.x, y: rect.y + inner.y - outer.y } })
      const inside = landing !== undefined && landing.x >= 0 && landing.y >= 0 && landing.x + landing.size <= rect.width && landing.y + landing.size <= rect.height
      note(inside ? `the whale lands at ${String(landing.x)}, ${String(landing.y)} (${String(landing.size)} px)` : 'no place to land: the whale dives')
      return inside ? landing : undefined
    } catch (error) {
      note(`no place to land (${error instanceof Error ? error.message : String(error)}): the whale dives`)
      return undefined
    }
  }

  /**
   * Puts the hidden team window on its rect, also when made with it: the size it was made with
   * can be off by a few pixels (see open()), the one set afterwards is exact.
   * @returns the rect
   */
  placeMain(main = this.#o.mainWindow()) {
    const rect = this.mainBounds()
    if (main !== undefined && !main.isDestroyed()) main.setBounds(rect)
    return rect
  }

  #open() { return this.#window !== undefined && !this.#window.isDestroyed() }

  #colors() { return COLORS[this.#o.electron.nativeTheme.shouldUseDarkColors ? 'dark' : 'light'] }

  #reset(start) {
    this.#clearTimers()
    this.#handing = false
    this.#under = false
    this.#revealed = false
    this.#engineUp = false
    this.#holdsOff()
    this.#watchAt = WATCHDOG_MS
    const now = Date.now()
    this.#phaseAt = now
    this.#state = {
      lang: this.#o.lang(), start, motion: this.#o.motion, frame: process.platform === 'win32' ? 'band' : 'system',
      view: start === 'moving' ? 'moving' : 'boot',
      done: [], explain: this.#explain, celebrate: start === 'first', shown: false,
      clock: { base: 0, from: now, running: true },
      hint: undefined, place: undefined, card: undefined, failure: undefined, update: undefined,
    }
    this.#refresh()
  }

  // Applies a change, keeps the clock running only while the start is booting and nobody is
  // being asked, and sends the page the whole state.
  #update(change) {
    const now = Date.now()
    const next = { ...this.#state, ...change }
    const running = this.#asks === 0 && (next.view === 'boot' || next.view === 'moving')
    const clock = next.clock
    if (running !== clock.running) next.clock = { base: clockMs(clock, now), from: now, running }
    this.#state = next
    this.#armWatchdog()
    this.#send()
  }

  #refresh() { if (this.#state !== undefined) this.#update({}) }

  #send() {
    if (this.#open() && this.#state !== undefined) this.#window.webContents.send(START_STATE, startSnapshot(this.#state, Date.now()))
  }

  // 180 s on the start's clock without the engine: the whale asks whether to try again.
  #armWatchdog() {
    this.#clear('watchdog')
    const { start, view, clock } = this.#state
    if (start === 'moving' || view !== 'boot' || !clock.running || this.#engineUp) return
    this.#later('watchdog', this.#watchAt - clockMs(clock, Date.now()), () => {
      note(`no engine after ${String(Math.round(this.#watchAt / 1000))} s`)
      this.#update({ view: 'watchdog' })
    })
  }

  #act(event, name, payload) {
    const win = this.#window
    if (!this.#open() || event.sender !== win.webContents || event.senderFrame !== win.webContents.mainFrame
      || !isStartPage(event.senderFrame?.url, this.#url)) return false
    if (!acceptsAct(name, this.#state.view)) {
      note(`refused the act ${typeof name === 'string' ? name.slice(0, 40) : typeof name} in ${this.#state.view}`)
      return false
    }
    if (name === 'handoffShow') this.#handoffShow(payload)
    else if (name === 'handoffDone') note(`handoffDone at handoffShow + ${String(Date.now() - this.#showAt)} ms`)
    else if (name === 'retry') this.#retry()
    else if (name === 'wait') this.#wait()
    else if (name === 'reloadView') this.#reload()
    else if (name === 'copyDetails') this.#copyDetails()
    else if (name === 'saveLog') void this.#saveLog()
    else if (name === 'painted') this.#showStart('painted')
    else if (name === 'pick') this.#o.onPick?.(valueOf(payload))
    else if (name === 'answer') this.#o.onAnswer?.(valueOf(payload))
    else if (name === 'installUpdate' || name === 'manualDownload') this.#o.onUpdate?.(name)
    else if (name === 'importOption') this.#o.onImport?.(name, optionOf(payload))
    else if (name === 'importModel') this.#o.onImport?.(name, valueOf(payload))
    return true
  }

  // The failed stage, or the engine after the 180 s question, starts again; the stages already
  // done stay done, and the first success after this celebrates (§7). The engine starts again
  // in any case, so the 180 s question guards it again.
  #retry() {
    note(`retry from ${this.#state.view}`)
    this.#engineUp = false
    this.#holdsOff()
    this.#watchAt = WATCHDOG_MS
    this.#phaseAt = Date.now()
    this.#update({ view: 'boot', failure: undefined, update: undefined, celebrate: true, done: this.#state.done.filter(phase => phase !== 'team'), clock: { base: 0, from: Date.now(), running: true } })
    this.#o.onRetry()
  }

  // 〔继续等待〕: the question comes back after another 180 s on the clock.
  #wait() {
    this.#watchAt = clockMs(this.#state.clock, Date.now()) + WATCHDOG_MS
    this.#update({ view: 'boot' })
  }

  #reload() {
    note('reloading the team view')
    this.#update({ view: 'boot', failure: undefined })
    this.#o.onReload()
    this.teamLoading()
  }

  #copyDetails() {
    const { version } = this.#o
    const reason = this.#state.failure?.reason ?? 'other'
    const text = detailsText({ version, platform: process.platform, arch: process.arch, reason, lines: this.#o.log.tail(FAILURE_LINES) })
    void Promise.resolve(this.#o.electron.clipboard.writeText(text)).catch((error) => { note(`the details were not copied: ${error instanceof Error ? error.message : String(error)}`) })
  }

  // The app's own picker on the page (saveAs), not a system box.
  async #saveLog() {
    const { version, saveAs } = this.#o
    if (saveAs === undefined) return
    const reason = this.#state.failure?.reason ?? 'other'
    const text = detailsText({ version, platform: process.platform, arch: process.arch, reason, lines: this.#o.log.tail(SAVED_LINES) })
    try {
      const filePath = await saveAs(this.#window, 'DS-Bot-log.txt')
      if (!filePath) return
      await writeFile(filePath, text, 'utf8')
      note(`the log was saved to ${filePath}`)
    } catch (error) {
      note(`the log was not saved: ${error instanceof Error ? error.message : String(error)}`)
    }
  }

  // The page's content has faded; with a landing it is at the top of its jump and says where.
  #handoffShow(payload) {
    if (this.#handing || this.#state.view !== 'handoff') return
    const main = this.#o.mainWindow()
    if (main === undefined || main.isDestroyed()) return
    this.#handing = true
    this.#clear('fallback')
    this.#showAt = Date.now()
    note(`handoffShow at ready + ${String(this.#showAt - this.#readyAt)} ms`)
    // The start window may have been dragged since the team window was placed.
    this.placeMain(main)
    const box = this.#state.landing === undefined || this.#readyReport === undefined ? undefined : this.#teamBox(main, payload)
    if (box === undefined || !this.#under) { this.#reveal(); return }
    main.webContents.send(TEAM_HANDOFF, { ...box, hold: HOLD_MS })
    this.#later('teamWait', TEAM_WAIT_MS, () => { note('the team page did not say it drew the whale'); this.#reveal() })
  }

  /** The team page has drawn the whale it was handed: the windows cross-fade. */
  teamReady() {
    if (!this.#handing || this.#revealed || this.#timers.teamWait === undefined) return
    note(`the team page drew the whale at handoffShow + ${String(Date.now() - this.#showAt)} ms`)
    this.#reveal()
  }

  #teamBox(main, payload) {
    try {
      const whale = payload !== null && typeof payload === 'object' ? payload.whale : undefined
      const start = this.#window.getContentBounds()
      const team = main.getContentBounds()
      return handoffBox(whale, { start, team, viewportWidth: Number(this.#readyReport.viewportWidth) })
    } catch (error) {
      note(`no whale to hand over (${error instanceof Error ? error.message : String(error)})`)
      return undefined
    }
  }

  // At ready() the team window shows, see-through, out of the taskbar and under the start window,
  // so that Windows' own opening transition has run by the reveal (shown at the reveal, it dims
  // the page for a few frames) and the team page is drawn and can take the whale.
  #underlay(main) {
    try {
      main.setSkipTaskbar(true)
      main.setOpacity(0)
      main.showInactive()
      this.#window.moveTop()
      this.#under = true
    } catch (error) {
      note(`the team window did not go under the start window: ${error instanceof Error ? error.message : String(error)}`)
      this.#unlay(main)
    }
  }

  #unlay(main) {
    this.#under = false
    if (main.isDestroyed()) return
    main.hide()
    main.setOpacity(1)
    main.setSkipTaskbar(false)
  }

  // The team window shows on its rect: with the focus when the start window had it; otherwise
  // behind nothing new, flashing its taskbar button; minimized when the start window was.
  #reveal() {
    if (this.#revealed || !this.#open()) return
    const main = this.#o.mainWindow()
    if (main === undefined || main.isDestroyed()) return
    this.#revealed = true
    this.#showTeam()
    this.#clear('fallback')
    this.#clear('teamWait')
    const win = this.#window
    const how = win.isMinimized() ? 'minimized' : win.isFocused() ? 'focused' : 'behind'
    if (this.#under && how !== 'minimized') { this.#crossfade(main, win, how); return }
    if (this.#under) this.#unlay(main)
    if (how === 'focused') {
      main.show()
      main.focus()
    } else if (how === 'minimized') {
      main.minimize()
    } else {
      main.showInactive()
      try { main.moveAbove(win.getMediaSourceId()) } catch { /* the order stays the system's */ }
    }
    if (how !== 'focused') {
      main.flashFrame(true)
      main.once('focus', () => { main.flashFrame(false) })
    }
    // Leaves the taskbar only now, so the app's button never goes away.
    win.setSkipTaskbar(true)
    note(`team window shown (${how}) at ready + ${String(Date.now() - this.#readyAt)} ms`)
    this.#later('destroy', DESTROY_AFTER_MS, () => { this.#destroy() })
  }

  // The team window, on its rect around and under the start window, fades in while the start
  // window fades out over it. With a whale handed over, the team page holds it where the start
  // page's whale is through this fade, so the two stay on each other.
  #crossfade(main, win, how) {
    // A team window hidden while it waited (closed to the tray) comes back for the fade.
    if (!main.isVisible()) main.showInactive()
    main.setSkipTaskbar(false)
    win.setSkipTaskbar(true)
    note(`cross-fade at ready + ${String(Date.now() - this.#readyAt)} ms`)
    const began = Date.now()
    const step = () => {
      if (!this.#open() || main.isDestroyed()) return
      const time = Math.min(1, (Date.now() - began) / CROSSFADE.duration)
      const eased = time * time * (3 - 2 * time)
      main.setOpacity(eased)
      win.setOpacity(1 - eased)
      if (time < 1) { this.#later('fade', CROSSFADE.step, step); return }
      if (how === 'focused') main.focus()
      else {
        main.flashFrame(true)
        main.once('focus', () => { main.flashFrame(false) })
      }
      note(`team window shown (${how}) at ready + ${String(Date.now() - this.#readyAt)} ms`)
      this.#destroy()
    }
    step()
  }

  #cancelHandoff() {
    const main = this.#o.mainWindow()
    if (this.#under && !this.#revealed && main !== undefined) this.#unlay(main)
    if (!this.#handing || this.#revealed) return
    this.#clear('teamWait')
    this.#handing = false
  }

  #destroy() {
    const win = this.#window
    if (win !== undefined && !win.isDestroyed()) win.destroy()
  }

  #later(name, ms, run) {
    this.#clear(name)
    this.#timers[name] = setTimeout(() => {
      delete this.#timers[name]
      run()
    }, Math.max(0, ms))
  }

  #clear(name) {
    clearTimeout(this.#timers[name])
    delete this.#timers[name]
  }

  #clearTimers() { for (const name of Object.keys(this.#timers)) this.#clear(name) }
}