Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

27.2 KB
Raw Blame
import { execFile } from 'node:child_process'
import { createHash } from 'node:crypto'
import { copyFile, mkdir, open, readdir, readFile, stat, unlink } from 'node:fs/promises'
import { homedir } from 'node:os'
import path from 'node:path'
import { promisify } from 'node:util'
import { IPC } from '../shared/ipc'
import {
  AERIAL_SHUFFLE_PREFIX,
  AERIAL_PREFIX,
  isAerialUuid,
  normalizeWallpaper,
  parseAerialId,
  wallpapersToKeep,
  type DesktopWallpaper,
  type WallpaperStill
} from '../shared/wallpaper'
import { renameAtomic, tempNameFor } from './fs-atomic'
import { platform } from './platform'

/**
 * Wallpaper files for the canvas background (Liquid Glass appearance). Core, so both shells serve
 * it: on the Server Edition (Linux) the stills list is simply empty and gradients need no files.
 *
 * Image work (measuring, converting to JPEG) goes through `WallpaperImageOps`. macOS defaults to
 * its built-in `sips`; the Electron shell registers a `nativeImage` implementation on Windows
 * (`src/main/wallpaper-native-image.ts` — core may not import electron). With no ops (Linux, the
 * Server Edition) there are no stills, and HEIC / over-cap imports are refused with a reason.
 *
 * Every file the renderer can get bytes for lives in ONE directory, `<userData>/wallpapers/`, under
 * a hash name this module minted. The renderer never names a path to read: a still is named by its
 * `mac:` / `win:` id and re-resolved against a fresh scan, and an imported image's path must be a direct
 * child of the cache dir with a hash-shaped name (`cachedImagePath`). So a hand-edited
 * settings.json cannot aim `load` at anything else, and there is no traversal to reject because
 * no caller-supplied segment is ever joined.
 *
 * `import` is the one exception: it takes a caller-supplied source path (the file picker's answer)
 * and copies any JPEG/PNG/WebP/HEIC-named regular file into the cache, whose bytes `load` then
 * returns. That is no wider than what the same caller already has (`fs:read` on both shells), but
 * it means the jail above governs `load`, not what can ENTER the cache.
 */

const run = promisify(execFile)

export const SYSTEM_WALLPAPER_DIR = '/System/Library/Desktop Pictures'
const SIPS = '/usr/bin/sips'
/** Real stills are several MB; the 356px `.madesktop` placeholders and thumbnails are not. */
const MIN_STILL_BYTES = 1_000_000
/** Windows' stock JPEGs are far smaller than macOS's HEICs (some theme stills are ~300 KB). */
const MIN_WINDOWS_STILL_BYTES = 200_000
const STILL_EXT = /\.(heic|jpe?g|png)$/i
const IMPORT_EXT = /\.(heic|jpe?g|png|webp)$/i
/** Shown first, in this order: the scenic ones. */
const SCENIC_FIRST = ['Sonoma Horizon', 'Sonoma']
const FULL_PX = 3840
const THUMB_PX = 320
/** Refuse to ship anything bigger over IPC as a data: URL. */
const MAX_LOAD_BYTES = 25 * 1024 * 1024
const CACHED_NAME = /^[0-9a-f]{40}(-t)?\.(jpg|jpeg|png|webp)$/

export interface ScannedStill {
  id: string
  label: string
  path: string
}

/**
 * The image converter seam. `id` is part of the cache key, which is why the sips one stays `sips`:
 * every macOS cache file minted before this seam existed keeps its name.
 */
export interface WallpaperImageOps {
  id: string
  /** Can `toJpeg` decode HEIC? (sips: yes; Chromium's nativeImage: no.) */
  canHeic: boolean
  /** An unreadable size counts as "too large" and is converted (sips can read what it cannot
   *  measure); false = copy it as-is (nativeImage cannot measure WebP, and cannot convert it). */
  convertUnknownSize: boolean
  /** Long edge in px, or null when it cannot say. */
  longEdge(src: string): Promise<number | null>
  /** Write a JPEG of `src` to `out`, downscaled to `maxPx` on its long edge only when larger. */
  toJpeg(src: string, maxPx: number, out: string): Promise<void>
}

export interface WallpaperHost {
  platform: string
  env: Record<string, string | undefined>
  /** Tests only: the Windows stills root, bypassing `windowsWallpaperRoot(env)`. */
  windowsStillsRoot?: string
  /** Tests only: the macOS Aerials root, bypassing the real `~/Library/...` one. */
  aerialsRoot?: string
}
let mediaUrl: ((absPath: string) => string) | null = null
let host: () => WallpaperHost = () => ({ platform: process.platform, env: process.env })
let registeredOps: WallpaperImageOps | null = null

/** The shell's converter (Electron on Windows). macOS keeps sips whatever is registered. */
export function setWallpaperImageOps(ops: WallpaperImageOps | null): void {
  registeredOps = ops
  stillScan = null
}

/**
 * The shell's way to hand the page a local file by URL: Electron's `allowMediaPath` (nt-media://,
 * streamed with Range so a 400 MB clip is never read whole). Core may not import electron. With
 * none (the Server Edition) there are no aerials — the viewer's browser could not reach the files.
 */
export function setWallpaperMediaUrl(fn: ((absPath: string) => string) | null): void {
  mediaUrl = fn
}

/** Tests only: pretend to be another OS / environment, and forget the memoized scan. */
export function setWallpaperHostForTests(next: Partial<WallpaperHost> | null): void {
  host = next
    ? () => ({
        platform: next.platform ?? process.platform,
        env: next.env ?? process.env,
        windowsStillsRoot: next.windowsStillsRoot,
        aerialsRoot: next.aerialsRoot
      })
    : () => ({ platform: process.platform, env: process.env })
  registeredOps = null
  mediaUrl = null
  stillScan = null
}

function imageOps(): WallpaperImageOps | null {
  if (host().platform === 'darwin') return sipsImageOps
  return registeredOps
}

/** A system still's id, on any platform: the prefix names the OS whose scan resolves it. */
export function isSystemStillId(id: string): boolean {
  return id.startsWith('mac:') || id.startsWith('win:')
}

/** `%WINDIR%\Web\Wallpaper` — the stock Windows stills (Windows, ThemeA…, one folder each). */
export function windowsWallpaperRoot(env: Record<string, string | undefined>): string {
  return path.win32.join(env.WINDIR || env.SystemRoot || 'C:\\Windows', 'Web', 'Wallpaper')
}

export function wallpaperCacheDir(): string {
  return path.join(platform().userDataDir, 'wallpapers')
}

/**
 * The stock macOS stills under `root`, scenic first. Recurses into `.wallpapers/<name>/`, skips
 * `.thumbnails` and anything under 1 MB (which is what drops the `.madesktop` placeholders' tiny
 * siblings). A missing root is an empty list, which is the answer everywhere but macOS.
 */
export async function scanStills(
  root = SYSTEM_WALLPAPER_DIR,
  depth = 3,
  { prefix = 'mac:', minBytes = MIN_STILL_BYTES }: { prefix?: string; minBytes?: number } = {}
): Promise<ScannedStill[]> {
  const found: ScannedStill[] = []
  const walk = async (dir: string, left: number): Promise<void> => {
    let entries
    try {
      entries = await readdir(dir, { withFileTypes: true })
    } catch {
      return
    }
    for (const e of entries) {
      const p = path.join(dir, e.name)
      if (e.isDirectory()) {
        if (e.name !== '.thumbnails' && left > 0) await walk(p, left - 1)
      } else if (e.isFile() && STILL_EXT.test(e.name)) {
        try {
          if ((await stat(p)).size < minBytes) continue
        } catch {
          continue
        }
        const rel = path.relative(root, p).split(path.sep).join('/')
        found.push({ id: `${prefix}${rel}`, label: e.name.replace(STILL_EXT, ''), path: p })
      }
    }
  }
  await walk(root, depth)
  const seen = new Set<string>()
  const rank = (label: string): number => {
    const i = SCENIC_FIRST.indexOf(label)
    return i === -1 ? SCENIC_FIRST.length : i
  }
  return found
    .sort((a, b) => rank(a.label) - rank(b.label) || a.label.localeCompare(b.label))
    .filter((s) => (seen.has(s.label) ? false : (seen.add(s.label), true)))
}

/** A cached file's name: stable per source file version and output size. */
async function cacheKey(src: string, variant: string): Promise<string> {
  const st = await stat(src)
  return createHash('sha1').update(`${src}\x00${st.mtimeMs}\x00${st.size}\x00${variant}`).digest('hex')
}

/** In-flight conversions, so two callers asking for the same file share one `sips`. */
const inflight = new Map<string, Promise<string>>()

/** Publish `produce(tmp)` at `target` through a unique temp, unless it is already there. */
function publishOnce(target: string, produce: (tmp: string) => Promise<void>): Promise<string> {
  const pending = inflight.get(target)
  if (pending) return pending
  const job = (async () => {
    try {
      await stat(target)
      return target
    } catch {
      // not cached yet
    }
    await mkdir(path.dirname(target), { recursive: true })
    const tmp = tempNameFor(target)
    try {
      await produce(tmp)
      await renameAtomic(tmp, target)
    } catch (err) {
      await unlink(tmp).catch(() => {})
      throw err
    }
    return target
  })().finally(() => inflight.delete(target))
  inflight.set(target, job)
  return job
}

/** The long edge of an image in px, per `sips`; null when it cannot say. */
async function sipsLongEdge(src: string): Promise<number | null> {
  try {
    const { stdout } = await run(SIPS, ['-g', 'pixelWidth', '-g', 'pixelHeight', src], {
      timeout: 30_000
    })
    const dims = [...stdout.matchAll(/pixel(?:Width|Height):\s*(\d+)/g)].map((m) => Number(m[1]))
    return dims.length === 2 ? Math.max(dims[0], dims[1]) : null
  } catch {
    return null
  }
}

/**
 * HEIC/JPEG/PNG/WebP → JPEG no larger than `px` on its long edge, via macOS's built-in `sips`.
 * `-Z` alone would also UPSCALE (measured: a 320px image comes out 3840px wide), so it is passed
 * only when the image is actually larger; an unreadable size is treated as larger.
 */
export const sipsImageOps: WallpaperImageOps = {
  id: 'sips',
  canHeic: true,
  convertUnknownSize: true,
  longEdge: sipsLongEdge,
  async toJpeg(src, px, out) {
    const edge = await sipsLongEdge(src)
    const resize = edge === null || edge > px ? ['-Z', String(px)] : []
    await run(SIPS, ['-s', 'format', 'jpeg', ...resize, src, '--out', out], { timeout: 60_000 })
  }
}

/** The cache file `convert` publishes for `src` at `px` — also what the prune must keep. */
async function convertedName(ops: WallpaperImageOps, src: string, px: number, suffix: string, dir: string) {
  return path.join(dir, `${await cacheKey(src, `${ops.id}${px}`)}${suffix}.jpg`)
}

function convert(ops: WallpaperImageOps, src: string, px: number, suffix: string): Promise<string> {
  return convertedName(ops, src, px, suffix, wallpaperCacheDir()).then((target) =>
    publishOnce(target, (tmp) => ops.toJpeg(src, px, tmp))
  )
}

let stillScan: Promise<ScannedStill[]> | null = null
function stills(): Promise<ScannedStill[]> {
  const { platform: os, env, windowsStillsRoot } = host()
  // One scan per app run: the system stills only change with an OS update.
  if (os === 'darwin') {
    stillScan ??= scanStills().catch(() => [])
    return stillScan
  }
  // Windows lists its stills only when the shell gave us something to thumbnail them with.
  if (os === 'win32' && registeredOps) {
    stillScan ??= scanStills(windowsStillsRoot ?? windowsWallpaperRoot(env), 2, {
      prefix: 'win:',
      minBytes: MIN_WINDOWS_STILL_BYTES
    }).catch(() => [])
    return stillScan
  }
  return Promise.resolve([])
}

/**
 * The size check and the read go through ONE open descriptor, so the file measured is the file
 * read: a stat-then-readFile pair could be handed a different (larger) file between the two.
 */
async function toDataUrl(file: string): Promise<string | null> {
  let fh
  try {
    fh = await open(file, 'r')
    const st = await fh.stat()
    if (!st.isFile() || st.size > MAX_LOAD_BYTES) return null
    const ext = path.extname(file).slice(1).toLowerCase()
    const mime = ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'
    return `data:${mime};base64,${(await fh.readFile()).toString('base64')}`
  } catch {
    return null
  } finally {
    await fh?.close().catch(() => {})
  }
}

/**
 * The cache file an `image` wallpaper names, or null when the value names anything else. Only a
 * DIRECT child of the cache dir with a hash-shaped name qualifies — that is the whole jail.
 */
export function cachedImagePath(p: string, cacheDir = wallpaperCacheDir()): string | null {
  if (typeof p !== 'string' || p.length === 0) return null
  const resolved = path.resolve(p)
  if (path.dirname(resolved) !== path.resolve(cacheDir)) return null
  if (!CACHED_NAME.test(path.basename(resolved))) return null
  return resolved
}

export async function listStills(): Promise<WallpaperStill[]> {
  const list = await stills()
  const out: WallpaperStill[] = []
  // Sequential on purpose: a fresh cache runs one `sips` per still, and a dozen at once is a burst
  // of CPU for a grid of 320px thumbnails. Cached, each is a stat plus a small read.
  const ops = imageOps()
  for (const s of list) {
    if (!ops) break
    const thumb = await convert(ops, s.path, THUMB_PX, '-t')
      .then(toDataUrl)
      .catch(() => null)
    out.push({ id: s.id, label: s.label, thumb })
  }
  return out
}

export async function loadWallpaper(value: unknown): Promise<string | null> {
  const w = normalizeWallpaper(value)
  if (w.kind === 'image') {
    const file = cachedImagePath(w.path)
    return file ? toDataUrl(file) : null
  }
  if (w.kind === 'preset' && isSystemStillId(w.id)) {
    const ops = imageOps()
    const still = ops && (await stills()).find((s) => s.id === w.id)
    if (!ops || !still) return null
    return convert(ops, still.path, FULL_PX, '')
      .then(toDataUrl)
      .catch(() => null)
  }
  if (w.kind === 'preset' && parseAerialId(w.id)) return aerialStill(w.id)
  return null
}

/**
 * Put a picked image into the cache and return the value to store. The cached copy is what keeps
 * the wallpaper when the original moves.
 *
 * The file is copied untouched when the page can show it as-is. The image ops (`sips` on macOS,
 * `nativeImage` on Windows) convert to a JPEG ≤ 3840px only when they must: HEIC (Chromium cannot
 * decode it — and only an ops that `canHeic`), or an image over 3840px or over `load`'s 25 MB cap —
 * a 60 MB camera PNG copied as-is would otherwise be refused at load, which reads as a wallpaper
 * that silently never appears. Re-encoding everything would flatten a PNG/WebP's alpha and
 * recompress a JPEG for nothing. Where no ops can do it, HEIC and an over-cap image are refused
 * HERE, where the picker can show the reason.
 */
export async function importWallpaper(sourcePath: unknown): Promise<DesktopWallpaper> {
  if (typeof sourcePath !== 'string' || !IMPORT_EXT.test(sourcePath)) {
    throw new Error('Choose a JPEG, PNG, WebP or HEIC image.')
  }
  const src = path.resolve(sourcePath)
  const keepNow = currentKeep()
  const ops = imageOps()
  const heic = /\.heic$/i.test(src)
  const srcStat = await stat(src)
  // A FIFO or device named `x.png` would hang copyFile/sips and wedge publishOnce for the run.
  if (!srcStat.isFile()) throw new Error('Choose a JPEG, PNG, WebP or HEIC image.')
  const tooBig = srcStat.size > MAX_LOAD_BYTES
  let result: DesktopWallpaper
  if (ops && (heic ? ops.canHeic : tooBig || (await oversize(ops, src)))) {
    result = { kind: 'image', path: await convert(ops, src, FULL_PX, '') }
  } else {
    if (heic) throw new Error("HEIC images can't be converted on this system. Choose a JPEG, PNG or WebP.")
    if (tooBig) {
      throw new Error(`That image is larger than ${MAX_LOAD_BYTES / 1024 / 1024} MB. Choose a smaller one.`)
    }
    const ext = path.extname(src).toLowerCase().replace('.jpeg', '.jpg')
    const target = path.join(wallpaperCacheDir(), `${await cacheKey(src, 'copy')}${ext}`)
    await publishOnce(target, (tmp) => copyFile(src, tmp))
    result = { kind: 'image', path: target }
  }
  // The setting is written by the renderer after this returns, so keep the new file AND everything
  // the saved settings still name (the wallpaper on screen and the "Your image" tile's recent import):
  // if that save never lands, nothing the settings point at may be gone. The settings hook prunes
  // the old ones once the choice is saved.
  void pruneWallpaperCache([...keepNow, result])
  return result
}

/** Is this image larger than the full-size cap? An unreadable size asks the ops what that means. */
async function oversize(ops: WallpaperImageOps, src: string): Promise<boolean> {
  const edge = await ops.longEdge(src)
  return edge === null ? ops.convertUnknownSize : edge > FULL_PX
}

/** The cache file a wallpaper value is drawn from, or null for none/gradients/unknown stills. */
async function fileFor(value: unknown, dir: string): Promise<string | null> {
  const w = normalizeWallpaper(value)
  if (w.kind === 'image') return cachedImagePath(w.path, dir)
  if (w.kind === 'preset' && isSystemStillId(w.id)) {
    const ops = imageOps()
    const still = ops && (await stills()).find((s) => s.id === w.id)
    if (!ops || !still) return null
    return convertedName(ops, still.path, FULL_PX, '', dir).catch(() => null)
  }
  return null
}

/**
 * Delete cached wallpapers nothing refers to any more. Only full-size files this module minted
 * (hash-named, no `-t`) are candidates: foreign files and temps are never touched, and still
 * thumbnails are kept (ponytail: ~20 KB each, one per system still; a stale one after an OS update
 * lingers until the cache dir is cleared). A conversion still in flight is never removed.
 *
 * Temps are deliberately left alone: `sweepStaleTempFiles` refuses any pid-bearing temp
 * (fs-atomic.ts — a pid cannot prove its writer is dead across instances), which is every temp
 * this module writes, and each writer already removes its own temp on failure.
 */
export async function pruneWallpaperCache(keep: unknown[], dir = wallpaperCacheDir()): Promise<void> {
  try {
    const keepFiles = new Set(
      (await Promise.all(keep.map((v) => fileFor(v, dir)))).filter((f): f is string => !!f)
    )
    for (const name of await readdir(dir)) {
      if (!CACHED_NAME.test(name) || name.includes('-t.')) continue
      const file = path.join(dir, name)
      if (keepFiles.has(file) || inflight.has(file)) continue
      await unlink(file).catch(() => {})
    }
  } catch {
    // best effort: a missing cache dir or an unreadable entry is nothing to clean
  }
}

/*
 * macOS Aerials (the moving wallpapers). macOS 26 keeps them under one root:
 * `manifest/entries.json` (every asset and category Apple offers), `videos/<asset UUID>.mov` (ONLY
 * what macOS has downloaded — the user downloads more in System Settings → Wallpaper) and
 * `thumbnails/<asset UUID>.png` (small stills, present for all). We never download anything.
 *
 * The jail is the same shape as the stills': the page names an aerial by `aerial:` /
 * `aerial-shuffle:` + UUID, core re-resolves it against a FRESH manifest scan, and the only paths
 * ever allowlisted are `<root>/videos/<id>.mov` and `<root>/thumbnails/<id>.png` built from a
 * UUID-shaped manifest id and found as a regular file by `readdir` (a symlink is not a file there,
 * and nt-media refuses one at serve time anyway). The pre-Sonoma `idleassetsd` layout has no
 * thumbnails, so it is not read (ponytail: add it as a second root if anyone runs an older macOS).
 */

export function aerialsRoot(): string {
  return host().aerialsRoot ?? path.join(homedir(), 'Library', 'Application Support', 'com.apple.wallpaper', 'aerials')
}

export interface AerialAsset {
  id: string
  label: string
  categories: string[]
  includeInShuffle: boolean
  order: number
}

export interface AerialCategory {
  id: string
  /** `AerialCategoryLandscapes` → `Landscapes`. */
  label: string
  order: number
}

export interface AerialScan {
  categories: AerialCategory[]
  assets: AerialAsset[]
  /** Asset ids with a `videos/<id>.mov` on disk. */
  downloaded: Set<string>
  /** Asset ids with a `thumbnails/<id>.png` on disk. */
  thumbs: Set<string>
}

const orderOf = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : Number.MAX_SAFE_INTEGER)

/** The parts of `entries.json` we use, both lists sorted by `preferredOrder`. Malformed rows drop. */
export function parseAerialManifest(json: unknown): Pick<AerialScan, 'categories' | 'assets'> {
  const o = (json && typeof json === 'object' ? json : {}) as Record<string, unknown>
  const rows = (v: unknown): Record<string, unknown>[] =>
    Array.isArray(v) ? v.filter((r): r is Record<string, unknown> => !!r && typeof r === 'object') : []
  const categories = rows(o.categories)
    .filter((c) => typeof c.id === 'string' && isAerialUuid(c.id) && typeof c.localizedNameKey === 'string')
    .map((c) => ({
      id: c.id as string,
      label: (c.localizedNameKey as string).replace(/^AerialCategory/, ''),
      order: orderOf(c.preferredOrder)
    }))
    .filter((c) => c.label.length > 0)
    .sort((a, b) => a.order - b.order)
  const assets = rows(o.assets)
    .filter((a) => typeof a.id === 'string' && isAerialUuid(a.id))
    .map((a) => ({
      id: a.id as string,
      label: typeof a.accessibilityLabel === 'string' && a.accessibilityLabel ? a.accessibilityLabel : 'Aerial',
      categories: Array.isArray(a.categories) ? a.categories.filter((c): c is string => typeof c === 'string') : [],
      includeInShuffle: a.includeInShuffle === true,
      order: orderOf(a.preferredOrder)
    }))
    .sort((a, b) => a.order - b.order)
  return { categories, assets }
}

/** The UUIDs of the regular files `<dir>/<UUID><ext>`. A missing dir is an empty set. */
async function uuidFiles(dir: string, ext: string): Promise<Set<string>> {
  const out = new Set<string>()
  try {
    for (const e of await readdir(dir, { withFileTypes: true })) {
      const id = e.name.endsWith(ext) ? e.name.slice(0, -ext.length) : ''
      if (e.isFile() && isAerialUuid(id)) out.add(id)
    }
  } catch {
    // not there: nothing downloaded / no thumbnails
  }
  return out
}

/** A fresh scan, every call: one small JSON read and two readdirs (macOS downloads clips at will). */
export async function scanAerials(root = aerialsRoot()): Promise<AerialScan | null> {
  let manifest
  try {
    manifest = parseAerialManifest(JSON.parse(await readFile(path.join(root, 'manifest', 'entries.json'), 'utf8')))
  } catch {
    return null
  }
  const [downloaded, thumbs] = await Promise.all([
    uuidFiles(path.join(root, 'videos'), '.mov'),
    uuidFiles(path.join(root, 'thumbnails'), '.png')
  ])
  return { ...manifest, downloaded, thumbs }
}

/** A shuffle's category members (by preferredOrder), or the one asset an `aerial:` id names. */
function aerialMembers(scan: AerialScan, id: string): AerialAsset[] {
  const a = parseAerialId(id)
  if (!a) return []
  if (!a.shuffle) return scan.assets.filter((x) => x.id === a.uuid)
  if (!scan.categories.some((c) => c.id === a.uuid)) return []
  return scan.assets.filter((x) => x.categories.includes(a.uuid))
}

/** The scan, when this host can serve aerials at all (macOS desktop with a media URL minter). */
async function aerialScan(): Promise<{ scan: AerialScan; root: string; url: (p: string) => string } | null> {
  const url = mediaUrl
  if (host().platform !== 'darwin' || !url) return null
  const root = aerialsRoot()
  const scan = await scanAerials(root)
  return scan ? { scan, root, url } : null
}

function thumbUrl(s: { scan: AerialScan; root: string; url: (p: string) => string }, id: string | undefined) {
  return id && s.scan.thumbs.has(id) ? s.url(path.join(s.root, 'thumbnails', `${id}.png`)) : null
}

/** One "Shuffle <category>" tile per category with any asset, then one tile per downloaded aerial. */
export async function listAerials(): Promise<WallpaperStill[]> {
  const s = await aerialScan()
  if (!s) return []
  const shuffles: WallpaperStill[] = []
  const singles: WallpaperStill[] = []
  for (const c of s.scan.categories) {
    const members = aerialMembers(s.scan, `${AERIAL_SHUFFLE_PREFIX}${c.id}`)
    if (!members.length) continue
    shuffles.push({ id: `${AERIAL_SHUFFLE_PREFIX}${c.id}`, label: `Shuffle ${c.label}`, thumb: thumbUrl(s, members[0].id) })
    for (const a of members) {
      if (s.scan.downloaded.has(a.id) && !singles.some((x) => x.id === `${AERIAL_PREFIX}${a.id}`)) {
        singles.push({ id: `${AERIAL_PREFIX}${a.id}`, label: a.label, thumb: thumbUrl(s, a.id) })
      }
    }
  }
  return [...shuffles, ...singles]
}

/**
 * The clips an aerial wallpaper plays: its own downloaded ones (a shuffle's only if
 * `includeInShuffle`, else any of the category's downloaded ones). When it has none — a category macOS has not downloaded anything for, or a
 * single aerial macOS has since deleted — ANY downloaded aerial plays instead: the thumbnail is a
 * 214×130 PNG, and stretched over the window it reads as a blurry regression, not a wallpaper. Only
 * with nothing downloaded at all is the list empty (the thumbnail then shows).
 */
export async function aerialClips(value: unknown): Promise<string[]> {
  const w = normalizeWallpaper(value)
  const s = w.kind === 'preset' && parseAerialId(w.id) ? await aerialScan() : null
  if (!s || w.kind !== 'preset') return []
  const shuffle = parseAerialId(w.id)!.shuffle
  const downloaded = aerialMembers(s.scan, w.id).filter((a) => s.scan.downloaded.has(a.id))
  const own = shuffle ? downloaded.filter((a) => a.includeInShuffle) : downloaded
  // A category whose downloaded clips are all left out of macOS's shuffle still plays its own
  // before anything from another category.
  const fallback = own.length ? own : downloaded
  const clips = fallback.length ? fallback : s.scan.assets.filter((a) => s.scan.downloaded.has(a.id))
  return clips.map((a) => s.url(path.join(s.root, 'videos', `${a.id}.mov`)))
}

/** The still under (and instead of) the video: the first member's thumbnail, by preferredOrder. */
async function aerialStill(id: string): Promise<string | null> {
  const s = await aerialScan()
  return s ? thumbUrl(s, aerialMembers(s.scan, id)[0]?.id) : null
}

let currentKeep: () => unknown[] = () => []

/**
 * Wire onto the platform's RPC surface (Electron ipcMain / server WS-RPC alike). The settings
 * accessors let the cache follow the choice: a changed `desktopWallpaper` prunes what the old one
 * left behind. There is deliberately no prune at boot: `SettingsStore.init` answers an unreadable
 * settings.json with the defaults, and pruning against that would delete the wallpaper the user
 * actually chose — a failed read is not evidence the choice went away. Only a SAVED change prunes.
 */
export function registerWallpaperIpc(settings: {
  get: () => { desktopWallpaper?: unknown; recentWallpaperImage?: unknown }
  onChange: (cb: (s: { desktopWallpaper?: unknown; recentWallpaperImage?: unknown }) => void) => unknown
}): void {
  currentKeep = () => wallpapersToKeep(settings.get())
  // The user's most recent import is kept too (`wallpapersToKeep`): choosing a preset must not
  // delete the image the "Your image" tile still offers.
  const key = (s: { desktopWallpaper?: unknown; recentWallpaperImage?: unknown }): string =>
    JSON.stringify(wallpapersToKeep(s))
  let last = key(settings.get())
  settings.onChange((s) => {
    const next = key(s)
    if (next === last) return
    last = next
    void pruneWallpaperCache(wallpapersToKeep(s))
  })
  platform().handle(IPC.wallpaperListStills, () => listStills())
  platform().handle(IPC.wallpaperLoad, (value: unknown) => loadWallpaper(value))
  platform().handle(IPC.wallpaperImport, (sourcePath: unknown) => importWallpaper(sourcePath))
  platform().handle(IPC.wallpaperListAerials, () => listAerials())
  platform().handle(IPC.wallpaperAerialClips, (value: unknown) => aerialClips(value))
}