@deckbuilderkit/platform 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,107 @@
+// OS-specific code lives here, so apps and the other packages stay portable.
+import { basename } from 'node:path';
+export * from './browser.ts';
+export * from './dialogs.ts';
+export * from './editors.ts';
+export * from './errors.ts';
+export * from './exe.ts';
+export * from './files.ts';
+export * from './home.ts';
+export * from './json-file.ts';
+export * from './rename-retry.ts';
+export * from './run.ts';
+export * from './secrets.ts';
+export * from './theme.ts';
+export * from './trash.ts';
+export * from './win/autostart.ts';
+export * from './win/placement.ts';
+export * from './win/powershell.ts';
+export * from './win/protocol.ts';
+export * from './win/toast.ts';
+export * from './win/tray.ts';
+
+/**
+ * Reports a fatal error: on stderr, and on Windows also in a message box, because the exe is
+ * built without a console. Blocks until the box is closed.
+ */
+export function showError(title: string, text: string): void {
+  console.error(`${title}: ${text}`);
+  if (process.platform !== 'win32') return;
+  try {
+    const { dlopen, FFIType } = require('bun:ffi') as typeof import('bun:ffi');
+    const user32 = dlopen('user32.dll', {
+      MessageBoxW: { args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.u32], returns: FFIType.i32 },
+    });
+    const wide = (s: string) => Buffer.from(`${s}\0`, 'utf16le');
+    const MB_ICONERROR = 0x10;
+    user32.symbols.MessageBoxW(null, wide(text), wide(title), MB_ICONERROR);
+    user32.close();
+  } catch {
+    // stderr above is the fallback
+  }
+}
+
+/**
+ * Shows a native window (an HWND) on Windows; elsewhere a no-op. A process started hidden
+ * (`bun run` passes SW_HIDE in its STARTUPINFO) gets that value instead of its first ShowWindow
+ * call, so the window a library showed once stays hidden; this second call is honoured.
+ */
+export function showWindow(hwnd: import('bun:ffi').Pointer | null): void {
+  if (process.platform !== 'win32' || !hwnd) return;
+  try {
+    const { dlopen, FFIType } = require('bun:ffi') as typeof import('bun:ffi');
+    const user32 = dlopen('user32.dll', {
+      ShowWindow: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+    });
+    const SW_SHOW = 5;
+    user32.symbols.ShowWindow(hwnd, SW_SHOW);
+    user32.close();
+  } catch {
+    // the window stays as the library left it
+  }
+}
+
+/**
+ * Sets a native window's title-bar and taskbar icon (Windows) to the icon embedded in the running
+ * exe. The webview library picks its own icon; this makes the exe's `--windows-icon` the one shown.
+ * A no-op elsewhere and when running from source (the exe would be bun's).
+ */
+export function setWindowIconFromExe(hwnd: import('bun:ffi').Pointer | null): void {
+  if (process.platform !== 'win32' || !hwnd || /^bun(\.exe)?$/i.test(basename(process.execPath))) return;
+  try {
+    const { dlopen, FFIType } = require('bun:ffi') as typeof import('bun:ffi');
+    const shell32 = dlopen('shell32.dll', {
+      ExtractIconExW: { args: [FFIType.ptr, FFIType.i32, FFIType.ptr, FFIType.ptr, FFIType.u32], returns: FFIType.u32 },
+    });
+    const user32 = dlopen('user32.dll', {
+      SendMessageW: { args: [FFIType.ptr, FFIType.u32, FFIType.u64, FFIType.u64], returns: FFIType.u64 },
+    });
+    const large = new BigUint64Array(1);
+    const small = new BigUint64Array(1);
+    const path = Buffer.from(`${process.execPath}\0`, 'utf16le');
+    shell32.symbols.ExtractIconExW(path, 0, large, small, 1);
+    const WM_SETICON = 0x80;
+    if (small[0]) user32.symbols.SendMessageW(hwnd, WM_SETICON, 0n, small[0]); // ICON_SMALL
+    if (large[0]) user32.symbols.SendMessageW(hwnd, WM_SETICON, 1n, large[0]); // ICON_BIG
+    shell32.close();
+    user32.close();
+  } catch {
+    // the window keeps the library's icon
+  }
+}
+
+/** Opens a URL in the default browser; best-effort, failures are ignored. */
+export function openExternal(url: string): void {
+  if (!/^https?:\/\//.test(url)) return;
+  const cmd =
+    process.platform === 'win32'
+      ? ['rundll32', 'url.dll,FileProtocolHandler', url]
+      : process.platform === 'darwin'
+        ? ['open', url]
+        : ['xdg-open', url];
+  try {
+    Bun.spawn(cmd, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: true }).unref();
+  } catch {
+    // no browser launcher available
+  }
+}

package/src/json-file.ts

@@ -0,0 +1,73 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { renameWithRetry } from './rename-retry.ts';
+
+/** Tail of each file's write queue, keyed by absolute path: writes to one file never overlap. */
+const queues = new Map<string, Promise<unknown>>();
+
+function enqueue<T>(file: string, job: () => Promise<T>): Promise<T> {
+  const key = resolve(file);
+  const run = (queues.get(key) ?? Promise.resolve()).catch(() => {}).then(job);
+  const tail = run.catch(() => {});
+  queues.set(key, tail);
+  void tail.then(() => {
+    if (queues.get(key) === tail) queues.delete(key);
+  });
+  return run;
+}
+
+/** Writes `data` to a temp file beside `file`, then renames it over the target; a crash never leaves a half-written file. */
+export function writeFileAtomic(file: string, data: string | Uint8Array | Blob | ReadableStream<Uint8Array>): Promise<void> {
+  return enqueue(file, async () => {
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${crypto.randomUUID().slice(0, 8)}.tmp`;
+    try {
+      if (typeof data === 'string' || data instanceof Uint8Array) await writeFile(tmp, data);
+      else {
+        // Bun.write(path, blob) copies a sliced file whole; the writer streams just the slice.
+        const out = Bun.file(tmp).writer();
+        try {
+          for await (const chunk of data instanceof Blob ? data.stream() : data) out.write(chunk);
+        } catch (err) {
+          await Promise.resolve(out.end()).catch(() => {});
+          throw err;
+        }
+        await out.end();
+      }
+      await renameWithRetry(tmp, file);
+    } catch (err) {
+      await rm(tmp, { force: true });
+      throw err;
+    }
+  });
+}
+
+/** `JSON.stringify(value, null, 2)` plus a newline, written atomically. */
+export function writeJsonAtomic(file: string, value: unknown): Promise<void> {
+  return writeFileAtomic(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+/**
+ * Reads and parses a JSON file. A missing file gives undefined; other read errors (EACCES, EISDIR) throw.
+ * A file that doesn't parse, or that `accept` rejects, is renamed to `<file>.corrupt-<epoch ms>`, reported
+ * on stderr, and gives undefined, so the next write doesn't silently destroy it.
+ */
+export async function readJsonFile(file: string, accept?: (value: unknown) => boolean): Promise<unknown | undefined> {
+  let text: string;
+  try {
+    text = await readFile(file, 'utf8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw err;
+  }
+  try {
+    const value: unknown = JSON.parse(text);
+    if (!accept || accept(value)) return value;
+  } catch {
+    // falls through to the quarantine below
+  }
+  const aside = `${file}.corrupt-${Date.now()}`;
+  console.error(`Unreadable JSON file moved aside: ${file} -> ${aside}`);
+  await rename(file, aside).catch(() => {});
+  return undefined;
+}

package/src/launch.ts

@@ -0,0 +1,4 @@
+// Not hidden: windowsHide starts explorer.exe with SW_HIDE and its window never appears.
+export function launch(argv: string[], windowsVerbatimArguments = false): void {
+  Bun.spawn(argv, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false, windowsVerbatimArguments }).unref();
+}

package/src/rename-retry.ts

@@ -0,0 +1,32 @@
+import { rename as fsRename, stat } from 'node:fs/promises';
+
+const RETRY_CODES = new Set(['EACCES', 'EPERM', 'EBUSY']);
+
+export interface RenameRetryOptions {
+  /** How long to keep retrying, in ms; default 10 s. */
+  timeoutMs?: number;
+  /** Injected in tests. */
+  rename?: (from: string, to: string) => Promise<void>;
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * `rename`, retried on Windows while EACCES / EPERM / EBUSY last: antivirus and the search indexer
+ * hold a just-written file open for a moment (VS Code retries the same way). A folder at `to` is not
+ * retried, since EPERM is then the real answer.
+ */
+export async function renameWithRetry(from: string, to: string, opts: RenameRetryOptions = {}): Promise<void> {
+  const rename = opts.rename ?? fsRename;
+  if ((opts.platform ?? process.platform) !== 'win32') return rename(from, to);
+  const deadline = Date.now() + (opts.timeoutMs ?? 10_000);
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await rename(from, to);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException)?.code;
+      if (!code || !RETRY_CODES.has(code) || Date.now() >= deadline) throw err;
+      if (await stat(to).then((s) => !s.isFile(), () => false)) throw err;
+      await Bun.sleep(Math.min(100, attempt * 10));
+    }
+  }
+}

package/src/run.ts

@@ -0,0 +1,84 @@
+import { spawn } from 'node:child_process';
+
+export type RunResult = { kind: 'done'; code: number; stdout: string; stderr: string } | { kind: 'timeout' };
+
+/** Runs a command and collects its output; faked in tests. */
+export type Runner = (cmd: string[], timeoutMs: number) => Promise<RunResult>;
+
+export const runWithTimeout: Runner = async (cmd, timeoutMs) => {
+  const proc = Bun.spawn(cmd, { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe', windowsHide: true });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<'timeout'>((resolve) => {
+    timer = setTimeout(() => resolve('timeout'), timeoutMs);
+  });
+  const done = Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+  const result = await Promise.race([done, timedOut]);
+  clearTimeout(timer);
+  if (result === 'timeout') {
+    killTree(proc.pid);
+    return { kind: 'timeout' };
+  }
+  const [stdout, stderr, code] = result;
+  return { kind: 'done', code, stdout, stderr };
+};
+
+/**
+ * Kills a child process and everything it spawned. Shims (scoop, Chocolatey) run the real exe as
+ * their own child, so a plain kill would leave that one alive.
+ */
+export function killTree(pid: number): void {
+  if (process.platform === 'win32') {
+    Bun.spawn(['taskkill', '/PID', String(pid), '/T', '/F'], { stdout: 'ignore', stderr: 'ignore', windowsHide: true });
+  } else {
+    try {
+      process.kill(pid);
+    } catch {
+      // already gone
+    }
+  }
+}
+
+/** `killTree` that returns once the tree is gone, e.g. right before `process.exit`. */
+export function killTreeSync(pid: number): void {
+  if (process.platform === 'win32') {
+    Bun.spawnSync(['taskkill', '/PID', String(pid), '/T', '/F'], { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: true });
+  } else {
+    try {
+      process.kill(pid);
+    } catch {
+      // already gone
+    }
+  }
+}
+
+/**
+ * Polls `url` until it answers with any HTTP status. Resolves true then, false after `timeoutMs`
+ * or once `until` returns true (e.g. the server process exited).
+ */
+export async function waitForUrl(url: string, opts: { timeoutMs: number; until?: () => boolean }): Promise<boolean> {
+  const deadline = Date.now() + opts.timeoutMs;
+  while (Date.now() < deadline && !opts.until?.()) {
+    try {
+      await fetch(url, { signal: AbortSignal.timeout(Math.max(1, deadline - Date.now())) });
+      return true;
+    } catch {
+      await Bun.sleep(200);
+    }
+  }
+  return false;
+}
+
+/**
+ * Starts `argv` outside this process's job object, so it outlives this process. Resolves once it
+ * started; rejects when it could not (e.g. missing exe).
+ */
+export function startDetached(argv: string[]): Promise<void> {
+  const [cmd, ...args] = argv;
+  if (!cmd) return Promise.reject(new Error('empty command'));
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore', windowsHide: true });
+    child.once('spawn', () => resolve());
+    child.once('error', reject);
+    child.unref();
+  });
+}

package/src/secrets.ts

@@ -0,0 +1,209 @@
+import { join } from 'node:path';
+import { PlatformError } from './errors.ts';
+import { appHome } from './home.ts';
+import { readJsonFile, writeJsonAtomic } from './json-file.ts';
+
+export interface SecretStore {
+  /** False when the OS store can't be used (Linux without secret-tool, macOS without security). */
+  available(): boolean;
+  /** Throws PlatformError 'secretsUnavailable' when the store isn't available. */
+  set(ref: string, value: string): Promise<void>;
+  /** null when nothing is stored under `ref` (or the store isn't available). */
+  get(ref: string): Promise<string | null>;
+  remove(ref: string): Promise<void>;
+}
+
+const REF = /^[\w.:-]{1,200}$/;
+const unavailable = (detail?: string) => new PlatformError('secretsUnavailable', 'The secret store is not available.', detail);
+
+/**
+ * Passwords and tokens an app keeps for the current OS user. Windows: DPAPI-encrypted blobs in
+ * `<dir>/secrets.json`, readable only by this Windows account. Linux: libsecret via `secret-tool`;
+ * macOS: the login keychain via `security` (both best-effort, untested).
+ */
+export function secretStore(appId: string, dir = appHome(appId)): SecretStore {
+  if (!/^[\w.-]+$/.test(appId)) throw new Error(`secretStore: invalid app id "${appId}"`);
+  const store =
+    process.platform === 'win32'
+      ? dpapiStore(appId, dir)
+      : process.platform === 'linux'
+        ? secretToolStore(appId)
+        : process.platform === 'darwin'
+          ? keychainStore(appId)
+          : null;
+  const checked = (ref: string) => {
+    if (!REF.test(ref)) throw new Error(`secretStore: invalid ref "${ref}"`);
+    return ref;
+  };
+  return {
+    available: () => store?.available() ?? false,
+    async set(ref, value) {
+      checked(ref);
+      if (!store?.available()) throw unavailable();
+      await store.set(ref, value);
+    },
+    async get(ref) {
+      checked(ref);
+      return store?.available() ? store.get(ref) : null;
+    },
+    async remove(ref) {
+      checked(ref);
+      if (store?.available()) await store.remove(ref);
+    },
+  };
+}
+
+// --- Windows: DPAPI --------------------------------------------------------------------------
+
+interface SecretsFile {
+  version: 1;
+  items: Record<string, string>;
+}
+
+const isSecretsFile = (v: unknown) =>
+  typeof v === 'object' &&
+  v !== null &&
+  (v as SecretsFile).version === 1 &&
+  typeof (v as SecretsFile).items === 'object' &&
+  (v as SecretsFile).items !== null &&
+  Object.values((v as SecretsFile).items).every((s) => typeof s === 'string');
+
+function dpapiStore(appId: string, dir: string): SecretStore {
+  const file = join(dir, 'secrets.json');
+  const entropy = Buffer.from(appId, 'utf8');
+  let items: Map<string, string> | null = null;
+  let chain: Promise<unknown> = Promise.resolve();
+
+  const locked = <R>(job: () => Promise<R>): Promise<R> => {
+    const run = chain.then(job);
+    chain = run.catch(() => {});
+    return run;
+  };
+
+  async function load(): Promise<Map<string, string>> {
+    if (!items) items = new Map(Object.entries(((await readJsonFile(file, isSecretsFile)) as SecretsFile | undefined)?.items ?? {}));
+    return items;
+  }
+
+  async function commit(next: Map<string, string>): Promise<void> {
+    await writeJsonAtomic(file, { version: 1, items: Object.fromEntries(next) } satisfies SecretsFile);
+    items = next;
+  }
+
+  return {
+    available: () => true,
+    set: (ref, value) =>
+      locked(async () => {
+        const sealed = dpapi(true, Buffer.from(value, 'utf8'), entropy);
+        if (!sealed) throw unavailable('CryptProtectData failed');
+        await commit(new Map(await load()).set(ref, sealed.toString('base64')));
+      }),
+    get: (ref) =>
+      locked(async () => {
+        const stored = (await load()).get(ref);
+        if (stored === undefined) return null;
+        const plain = dpapi(false, Buffer.from(stored, 'base64'), entropy);
+        if (!plain) throw new PlatformError('secretUnreadable', 'A stored secret could not be decrypted.', ref);
+        return plain.toString('utf8');
+      }),
+    remove: (ref) =>
+      locked(async () => {
+        const all = await load();
+        if (!all.has(ref)) return;
+        const next = new Map(all);
+        next.delete(ref);
+        await commit(next);
+      }),
+  };
+}
+
+const CRYPTPROTECT_UI_FORBIDDEN = 0x1;
+let dpapiLib: ReturnType<typeof openDpapi> | null = null;
+
+function openDpapi() {
+  const { dlopen, FFIType } = require('bun:ffi') as typeof import('bun:ffi');
+  // (pDataIn, szDataDescr | ppszDataDescr, pOptionalEntropy, pvReserved, pPromptStruct, dwFlags, pDataOut)
+  const sig = { args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.u32, FFIType.ptr], returns: FFIType.i32 } as const;
+  const crypt32 = dlopen('crypt32.dll', { CryptProtectData: sig, CryptUnprotectData: sig });
+  const kernel32 = dlopen('kernel32.dll', { LocalFree: { args: [FFIType.ptr], returns: FFIType.ptr } });
+  return { ...crypt32.symbols, ...kernel32.symbols };
+}
+
+/** A DATA_BLOB (x64: u32 cbData, 4 bytes padding, ptr pbData) over `data`; keep `data` alive during the call. */
+function blobOf(data: Uint8Array, size = data.length): Buffer {
+  const { ptr } = require('bun:ffi') as typeof import('bun:ffi');
+  const blob = Buffer.alloc(16);
+  blob.writeUInt32LE(size, 0);
+  blob.writeBigUInt64LE(BigInt(ptr(data)), 8);
+  return blob;
+}
+
+/** CryptProtectData (`protect`) or CryptUnprotectData over `data`; null when the call fails. */
+function dpapi(protect: boolean, data: Uint8Array, entropy: Uint8Array): Buffer | null {
+  const { toArrayBuffer } = require('bun:ffi') as typeof import('bun:ffi');
+  const lib = (dpapiLib ??= openDpapi());
+  // ptr() rejects empty buffers; cbData stays 0 for them.
+  const input = data.length ? data : new Uint8Array(1);
+  const inBlob = blobOf(input, data.length);
+  const entropyBlob = blobOf(entropy);
+  const out = Buffer.alloc(16);
+  const call = protect ? lib.CryptProtectData : lib.CryptUnprotectData;
+  const ok = call(inBlob, null, entropyBlob, null, null, CRYPTPROTECT_UI_FORBIDDEN, out);
+  void [input, entropy];
+  if (!ok) return null;
+  const size = out.readUInt32LE(0);
+  const at = Number(out.readBigUInt64LE(8)) as import('bun:ffi').Pointer;
+  try {
+    const copy = Buffer.alloc(size);
+    if (size) copy.set(new Uint8Array(toArrayBuffer(at, 0, size)));
+    return copy;
+  } finally {
+    lib.LocalFree(at);
+  }
+}
+
+// --- Linux and macOS (best-effort, untested) -------------------------------------------------
+
+async function exec(argv: string[], input?: string): Promise<{ code: number; stdout: string; stderr: string }> {
+  const proc = Bun.spawn(argv, { stdin: input === undefined ? 'ignore' : Buffer.from(input, 'utf8'), stdout: 'pipe', stderr: 'pipe' });
+  const [stdout, stderr, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+  return { code, stdout, stderr };
+}
+
+function secretToolStore(appId: string): SecretStore {
+  const attrs = (ref: string) => ['app', appId, 'ref', ref];
+  return {
+    available: () => Bun.which('secret-tool') !== null,
+    async set(ref, value) {
+      const r = await exec(['secret-tool', 'store', `--label=${appId}`, ...attrs(ref)], value);
+      if (r.code !== 0) throw unavailable(r.stderr.trim());
+    },
+    async get(ref) {
+      const r = await exec(['secret-tool', 'lookup', ...attrs(ref)]);
+      return r.code === 0 ? r.stdout : null;
+    },
+    async remove(ref) {
+      await exec(['secret-tool', 'clear', ...attrs(ref)]);
+    },
+  };
+}
+
+// The value never goes on argv: `security -i` reads the command from stdin. It is stored as hex
+// text (no quoting needed), so reading always hex-decodes.
+function keychainStore(appId: string): SecretStore {
+  return {
+    available: () => Bun.which('security') !== null,
+    async set(ref, value) {
+      const hex = Buffer.from(value, 'utf8').toString('hex');
+      const r = await exec(['security', '-i'], `add-generic-password -U -s "${appId}" -a "${ref}" -w ${hex || '""'}\n`);
+      if (r.code !== 0) throw unavailable(r.stderr.trim());
+    },
+    async get(ref) {
+      const r = await exec(['security', 'find-generic-password', '-s', appId, '-a', ref, '-w']);
+      return r.code === 0 ? Buffer.from(r.stdout.trim(), 'hex').toString('utf8') : null;
+    },
+    async remove(ref) {
+      await exec(['security', 'delete-generic-password', '-s', appId, '-a', ref]);
+    },
+  };
+}

package/src/theme.ts

@@ -0,0 +1,25 @@
+import { type Runner, runWithTimeout } from './run.ts';
+
+const PERSONALIZE = String.raw`HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize`;
+const TIMEOUT_MS = 5_000;
+
+/** The light/dark value in `reg.exe query <Personalize> /v AppsUseLightTheme` output. */
+export function parseRegTheme(stdout: string): 'dark' | 'light' | null {
+  const m = stdout.match(/AppsUseLightTheme\s+REG_DWORD\s+0x([0-9a-f]+)/i);
+  if (!m) return null;
+  return parseInt(m[1]!, 16) === 0 ? 'dark' : 'light';
+}
+
+/** The OS app theme (Windows registry, macOS defaults), or null where there is no such setting. */
+export async function osThemeKind(run: Runner = runWithTimeout): Promise<'dark' | 'light' | null> {
+  if (process.platform === 'win32') {
+    const r = await run(['reg.exe', 'query', PERSONALIZE, '/v', 'AppsUseLightTheme'], TIMEOUT_MS);
+    return r.kind === 'done' && r.code === 0 ? parseRegTheme(r.stdout) : null;
+  }
+  if (process.platform === 'darwin') {
+    // Prints "Dark" in dark mode; fails (no such key) in light mode.
+    const r = await run(['defaults', 'read', '-g', 'AppleInterfaceStyle'], TIMEOUT_MS);
+    return r.kind === 'done' && r.code === 0 && /dark/i.test(r.stdout) ? 'dark' : 'light';
+  }
+  return null;
+}

package/src/trash.ts

@@ -0,0 +1,90 @@
+import { PlatformError } from './errors.ts';
+import { runWithTimeout } from './run.ts';
+
+export interface TrashDeps {
+  /** Moves one absolute path to the recycle bin. */
+  trashOne: (path: string) => Promise<void>;
+}
+
+const defaultDeps: TrashDeps = { trashOne };
+
+const failed = (detail?: string) => new PlatformError('trashFailed', "Couldn't move to the Recycle Bin.", detail);
+const unavailable = (detail?: string) => new PlatformError('trashUnavailable', 'No recycle bin is available on this system.', detail);
+
+/**
+ * Moves the absolute `paths` (files or folders) to the OS recycle bin, one awaited call per path
+ * like VS Code. Stops at the first failure; the PlatformError 'trashFailed' (or 'trashUnavailable')
+ * lists which paths were and weren't moved. It never falls back to a permanent delete.
+ */
+export async function moveToTrash(paths: string[], deps = defaultDeps): Promise<void> {
+  const moved: string[] = [];
+  for (const path of paths) {
+    try {
+      await deps.trashOne(path);
+    } catch (err) {
+      const reason = err instanceof PlatformError ? err : failed((err as Error).message);
+      if (paths.length === 1) throw reason;
+      const notMoved = paths.slice(moved.length);
+      const detail = `${reason.detail ?? reason.message}
+Moved: ${moved.join(', ') || '(none)'}
+Not moved: ${notMoved.join(', ')}`;
+      throw reason.code === 'trashUnavailable' ? unavailable(detail) : failed(detail);
+    }
+    moved.push(path);
+  }
+}
+
+function trashOne(path: string): Promise<void> {
+  if (process.platform === 'win32') return shellTrash(path);
+  if (process.platform === 'darwin') {
+    const lines = ['on run argv', 'tell application "Finder" to delete (POSIX file (item 1 of argv) as alias)', 'end run'];
+    return run(['osascript', ...lines.flatMap((line) => ['-e', line]), path]);
+  }
+  if (process.platform === 'linux') return run(['gio', 'trash', path]);
+  throw unavailable();
+}
+
+// The shell call runs in this process: a PowerShell child that compiles C# on the fly (csc.exe,
+// P/Invoke, a delete) is what behavior-based antivirus flagged as ransomware (HEU_AEGIS_CRYPT).
+const FO_DELETE = 3;
+const FOF_SILENT = 0x4;
+const FOF_NOCONFIRMATION = 0x10;
+const FOF_ALLOWUNDO = 0x40;
+const FOF_NOERRORUI = 0x400;
+const FOF_WANTNUKEWARNING = 0x4000;
+
+function shellTrash(path: string): Promise<void> {
+  const { dlopen, FFIType, ptr } = require('bun:ffi') as typeof import('bun:ffi');
+  const { symbols } = dlopen('shell32.dll', { SHFileOperationW: { args: [FFIType.ptr], returns: FFIType.i32 } });
+  const from = Buffer.from(`${path}\0\0`, 'utf16le');
+  // SHFILEOPSTRUCTW (x64): hwnd@0, wFunc@8, pFrom@16, pTo@24, fFlags@32, fAnyOperationsAborted@36, hNameMappings@40, lpszProgressTitle@48.
+  const op = Buffer.alloc(56);
+  op.writeUInt32LE(FO_DELETE, 8);
+  op.writeBigUInt64LE(BigInt(ptr(from)), 16);
+  op.writeUInt16LE(FOF_ALLOWUNDO | FOF_NOCONFIRMATION | FOF_SILENT | FOF_NOERRORUI | FOF_WANTNUKEWARNING, 32);
+  const result = symbols.SHFileOperationW(ptr(op));
+  if (result !== 0) return Promise.reject(failed(`SHFileOperation failed with code 0x${result.toString(16)}`));
+  if (op.readInt32LE(36) !== 0) return Promise.reject(failed('Cancelled.'));
+  return Promise.resolve();
+}
+
+async function run(argv: string[]): Promise<void> {
+  let result: Awaited<ReturnType<typeof runWithTimeout>>;
+  try {
+    result = await runWithTimeout(argv, 60_000);
+  } catch (err) {
+    throw unavailable((err as Error).message);
+  }
+  if (result.kind === 'timeout') throw failed('Timed out.');
+  if (result.code !== 0) throw failed(result.stderr.trim());
+}
+
+// `bun packages/platform/src/trash.ts --selftest`: creates a temp file and moves it to the bin.
+if (import.meta.main && process.argv.includes('--selftest')) {
+  const { tmpdir } = await import('node:os');
+  const { join } = await import('node:path');
+  const file = join(tmpdir(), `deckbuilder-trash-selftest-${Date.now()}.txt`);
+  await Bun.write(file, 'DeckBuilder trash self-test\n');
+  await moveToTrash([file]);
+  console.log(`moved to the recycle bin: ${file} (exists now: ${await Bun.file(file).exists()})`);
+}