@deckbuilderkit/platform 0.0.0-stage → 0.1.1

package/src/win/autostart.ts

@@ -0,0 +1,71 @@
+import { isCompiledExe } from '../exe.ts';
+import { type Runner, runWithTimeout } from '../run.ts';
+
+const RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
+const TIMEOUT_MS = 10_000;
+
+export interface AutostartOptions {
+  /** Registry value name, usually the app's display name. */
+  name: string;
+  /** Flags the exe gets at login. */
+  args?: string[];
+  run?: Runner;
+  execPath?: string;
+  /** False when running from source or off Windows: then nothing touches the registry. */
+  enabled?: boolean;
+  onWarn?: (msg: string) => void;
+}
+
+export interface Autostart {
+  /** Registers or removes the Run value; a no-op when not enabled. */
+  set(on: boolean): Promise<void>;
+  /** The registered command, or null when absent. */
+  registered(): Promise<string | null>;
+  /** Registers the Run value when absent or when the exe moved since it was registered. */
+  fixUp(): Promise<void>;
+}
+
+const runCommand = (execPath: string, args: string[] = []): string => [`"${execPath}"`, ...args].join(' ');
+
+export function autostartArgv(name: string, on: boolean, command: string): string[] {
+  return on
+    ? ['reg.exe', 'add', RUN_KEY, '/v', name, '/t', 'REG_SZ', '/d', command, '/f']
+    : ['reg.exe', 'delete', RUN_KEY, '/v', name, '/f'];
+}
+
+/** The data of value `name` in `reg.exe query` output. */
+export function parseRegQuery(stdout: string, name: string): string | null {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const m = stdout.match(new RegExp(`^\\s*${escaped}\\s+REG_SZ\\s+(.+?)\\s*$`, 'm'));
+  return m?.[1] ?? null;
+}
+
+/** Starts the exe at Windows login through the HKCU Run key. */
+export function createAutostart(opts: AutostartOptions): Autostart {
+  const run = opts.run ?? runWithTimeout;
+  const execPath = opts.execPath ?? process.execPath;
+  const enabled = opts.enabled ?? (process.platform === 'win32' && isCompiledExe(execPath));
+  const command = runCommand(execPath, opts.args);
+  const warn = opts.onWarn ?? ((msg) => console.warn(`autostart: ${msg}`));
+
+  const registered = async (): Promise<string | null> => {
+    const r = await run(['reg.exe', 'query', RUN_KEY, '/v', opts.name], TIMEOUT_MS);
+    return r.kind === 'done' && r.code === 0 ? parseRegQuery(r.stdout, opts.name) : null;
+  };
+
+  const set = async (on: boolean): Promise<void> => {
+    if (!enabled) return;
+    if (!on && (await registered()) === null) return;
+    const r = await run(autostartArgv(opts.name, on, command), TIMEOUT_MS);
+    if (r.kind === 'timeout' || r.code !== 0) warn(`reg.exe failed: ${r.kind === 'done' ? r.stderr.trim() : 'timeout'}`);
+  };
+
+  return {
+    set,
+    registered,
+    async fixUp() {
+      if (!enabled) return;
+      if ((await registered()) !== command) await set(true);
+    },
+  };
+}

package/src/win/placement.ts

@@ -0,0 +1,73 @@
+import type { Pointer } from 'bun:ffi';
+
+/** Where a window sits when not maximized, plus whether it is maximized. Pixels in virtual-screen coordinates. */
+export interface WindowPlacement {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  maximized: boolean;
+}
+
+// WINDOWPLACEMENT: length, flags, showCmd, ptMinPosition(2), ptMaxPosition(2), rcNormalPosition(4), all 32-bit.
+const STRUCT_INTS = 11;
+const SW_SHOWNORMAL = 1;
+const SW_SHOWMAXIMIZED = 3;
+const WPF_RESTORETOMAXIMIZED = 2;
+
+function user32() {
+  const { dlopen, FFIType } = require('bun:ffi') as typeof import('bun:ffi');
+  return dlopen('user32.dll', {
+    GetWindowPlacement: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+    SetWindowPlacement: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+  });
+}
+
+/** Reads a window's placement on Windows; undefined elsewhere or when the call fails. */
+export function getWindowPlacement(hwnd: Pointer | null): WindowPlacement | undefined {
+  if (process.platform !== 'win32' || !hwnd) return undefined;
+  try {
+    const { ptr } = require('bun:ffi') as typeof import('bun:ffi');
+    const lib = user32();
+    const buf = new Int32Array(STRUCT_INTS);
+    buf[0] = STRUCT_INTS * 4;
+    const ok = lib.symbols.GetWindowPlacement(hwnd, ptr(buf));
+    lib.close();
+    if (!ok) return undefined;
+    const maximized = buf[2] === SW_SHOWMAXIMIZED || (buf[1] & WPF_RESTORETOMAXIMIZED) !== 0;
+    return { left: buf[7], top: buf[8], right: buf[9], bottom: buf[10], maximized };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Moves and sizes a window (maximizing it if asked). Windows pulls a rectangle on a missing monitor back onto a visible one. */
+export function setWindowPlacement(hwnd: Pointer | null, p: WindowPlacement): void {
+  if (process.platform !== 'win32' || !hwnd) return;
+  try {
+    const { ptr } = require('bun:ffi') as typeof import('bun:ffi');
+    const lib = user32();
+    const buf = new Int32Array(STRUCT_INTS);
+    buf[0] = STRUCT_INTS * 4;
+    buf[2] = p.maximized ? SW_SHOWMAXIMIZED : SW_SHOWNORMAL;
+    buf[7] = p.left;
+    buf[8] = p.top;
+    buf[9] = p.right;
+    buf[10] = p.bottom;
+    lib.symbols.SetWindowPlacement(hwnd, ptr(buf));
+    lib.close();
+  } catch {
+    // the window stays where the library put it
+  }
+}
+
+/** Parses a saved placement; undefined when it isn't a sane rectangle. */
+export function parsePlacement(value: unknown): WindowPlacement | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const v = value as Record<string, unknown>;
+  const nums = [v.left, v.top, v.right, v.bottom];
+  if (!nums.every((n) => Number.isInteger(n)) || typeof v.maximized !== 'boolean') return undefined;
+  const [left, top, right, bottom] = nums as number[];
+  if (right - left < 200 || bottom - top < 150) return undefined;
+  return { left, top, right, bottom, maximized: v.maximized };
+}

package/src/win/powershell.ts

@@ -0,0 +1,39 @@
+type Stream = 'pipe' | 'ignore';
+
+/**
+ * Starts Windows PowerShell 5.1 (never pwsh: PowerShell 7 dropped WinRT projection) on `script`,
+ * hidden. The script goes in -EncodedCommand, so multi-line scripts and C# here-strings need no
+ * quoting and stdin stays free for data (callers write JSON lines to it). `sta` adds -STA
+ * (WinForms). stderr is always piped. No timeout: callers that need one use `killTree`.
+ */
+export function spawnPowerShell<In extends Stream = 'ignore', Out extends Stream = 'pipe'>(
+  script: string,
+  opts: { sta?: boolean; stdin?: In; stdout?: Out } = {},
+): Bun.Subprocess<In, Out, 'pipe'> {
+  const encoded = Buffer.from(script, 'utf16le').toString('base64');
+  const argv = ['powershell.exe', '-NoProfile', '-NonInteractive', ...(opts.sta ? ['-STA'] : []), '-EncodedCommand', encoded];
+  return Bun.spawn(argv, {
+    stdin: opts.stdin ?? 'ignore',
+    stdout: opts.stdout ?? 'pipe',
+    stderr: 'pipe',
+    windowsHide: true,
+  }) as Bun.Subprocess<In, Out, 'pipe'>;
+}
+
+/** JSON with non-ASCII \u-escaped, so the console code page of a host can't mangle it. */
+export function asciiJson(value: unknown): string {
+  return JSON.stringify(value).replace(/[\u007f-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+/** Calls `onLine` with each trimmed, non-empty line of a host's output stream. */
+export async function forEachLine(stream: ReadableStream<Uint8Array>, onLine: (line: string) => void): Promise<void> {
+  const decoder = new TextDecoder();
+  let buffered = '';
+  for await (const chunk of stream) {
+    buffered += decoder.decode(chunk, { stream: true });
+    const lines = buffered.split(/\r?\n/);
+    buffered = lines.pop() ?? '';
+    for (const line of lines) if (line.trim() !== '') onLine(line.trim());
+  }
+  if (buffered.trim() !== '') onLine(buffered.trim());
+}

package/src/win/protocol.ts

@@ -0,0 +1,79 @@
+import { isCompiledExe } from '../exe.ts';
+import { type Runner, runWithTimeout } from '../run.ts';
+
+const TIMEOUT_MS = 10_000;
+
+export interface UrlProtocolOptions {
+  /** URL scheme, e.g. `deckbuilder` for `deckbuilder://…`. */
+  scheme: string;
+  /** Display name; Windows shows `URL:<name>`. */
+  name: string;
+  execPath?: string;
+  run?: Runner;
+  /** False when running from source or off Windows: then nothing touches the registry. */
+  enabled?: boolean;
+  onWarn?: (msg: string) => void;
+}
+
+export interface UrlProtocol {
+  /** Writes the protocol keys; a no-op when not enabled. */
+  register(): Promise<void>;
+  /** The registered open command, or null when absent. */
+  registered(): Promise<string | null>;
+  /** Registers the protocol when absent or when the exe moved since it was registered. */
+  fixUp(): Promise<void>;
+}
+
+const protocolKey = (scheme: string): string => `HKCU\\Software\\Classes\\${scheme}`;
+
+const openCommand = (execPath: string): string => `"${execPath}" --open-url "%1"`;
+
+/** One `reg.exe add` per value the protocol needs. */
+export function protocolArgv(scheme: string, name: string, execPath: string): string[][] {
+  const key = protocolKey(scheme);
+  return [
+    ['reg.exe', 'add', key, '/ve', '/d', `URL:${name}`, '/f'],
+    ['reg.exe', 'add', key, '/v', 'URL Protocol', '/d', '', '/f'],
+    ['reg.exe', 'add', `${key}\\DefaultIcon`, '/ve', '/d', `"${execPath}",0`, '/f'],
+    ['reg.exe', 'add', `${key}\\shell\\open\\command`, '/ve', '/d', openCommand(execPath), '/f'],
+  ];
+}
+
+/** The data of the first REG_SZ value in `reg.exe query` output; the default value's name is localized. */
+export function parseFirstRegSz(stdout: string): string | null {
+  const m = stdout.match(/^\s*\S.*?\s+REG_SZ\s+(.+?)\s*$/m);
+  return m?.[1] ?? null;
+}
+
+/** Registers `<scheme>://` under HKCU so Windows opens such links with the exe (`--open-url <uri>`). */
+export function createUrlProtocol(opts: UrlProtocolOptions): UrlProtocol {
+  const run = opts.run ?? runWithTimeout;
+  const execPath = opts.execPath ?? process.execPath;
+  const enabled = opts.enabled ?? (process.platform === 'win32' && isCompiledExe(execPath));
+  const warn = opts.onWarn ?? ((msg) => console.warn(`url protocol: ${msg}`));
+
+  const registered = async (): Promise<string | null> => {
+    const r = await run(['reg.exe', 'query', `${protocolKey(opts.scheme)}\\shell\\open\\command`, '/ve'], TIMEOUT_MS);
+    return r.kind === 'done' && r.code === 0 ? parseFirstRegSz(r.stdout) : null;
+  };
+
+  const register = async (): Promise<void> => {
+    if (!enabled) return;
+    for (const cmd of protocolArgv(opts.scheme, opts.name, execPath)) {
+      const r = await run(cmd, TIMEOUT_MS);
+      if (r.kind === 'timeout' || r.code !== 0) {
+        warn(`reg.exe failed: ${r.kind === 'done' ? r.stderr.trim() : 'timeout'}`);
+        return;
+      }
+    }
+  };
+
+  return {
+    register,
+    registered,
+    async fixUp() {
+      if (!enabled) return;
+      if ((await registered()) !== openCommand(execPath)) await register();
+    },
+  };
+}

package/src/win/toast.ts

@@ -0,0 +1,168 @@
+import { killTree } from '../run.ts';
+import { asciiJson, forEachLine, spawnPowerShell } from './powershell.ts';
+
+export interface Toast {
+  title: string;
+  body: string;
+  /** URI Windows opens when the toast is clicked (http(s) opens the default browser). */
+  launch: string;
+}
+
+export interface Toaster {
+  show(toast: Toast): void;
+  /** Ends the host process; resolves with its exit code (null if none was running). */
+  close(): Promise<number | null>;
+}
+
+const noopToaster: Toaster = { show() {}, close: async () => null };
+
+// Windows PowerShell's own AppUserModelID: toasts need a registered app id, and a custom one
+// would need a Start-menu shortcut.
+const APP_ID = '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe';
+
+function xmlEscape(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}
+
+// activationType="protocol": Windows opens `launch` itself, so no COM activator is registered.
+export function toastXml(toast: Toast): string {
+  const body = toast.body === '' ? '' : `<text>${xmlEscape(toast.body)}</text>`;
+  return (
+    `<toast activationType="protocol" launch="${xmlEscape(toast.launch)}">` +
+    `<visual><binding template="ToastGeneric"><text>${xmlEscape(toast.title)}</text>${body}` +
+    '</binding></visual></toast>'
+  );
+}
+
+/** One stdin line for the host. */
+export function toastLine(toast: Toast): string {
+  return `${asciiJson({ xml: toastXml(toast) })}\n`;
+}
+
+// Reads one JSON line per toast until stdin closes. A bad line is reported on stderr and skipped.
+// $ProgressPreference: module-loading progress would otherwise reach stderr as CLIXML.
+const HOST_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$null = [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]
+$null = [Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime]
+$notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('${APP_ID}')
+while ($true) {
+  $line = [Console]::In.ReadLine()
+  if ($null -eq $line) { break }
+  if ($line.Trim() -eq '') { continue }
+  try {
+    $doc = New-Object Windows.Data.Xml.Dom.XmlDocument
+    $doc.LoadXml(($line | ConvertFrom-Json).xml)
+    $notifier.Show([Windows.UI.Notifications.ToastNotification]::new($doc))
+  } catch {
+    [Console]::Error.WriteLine($_.Exception.Message)
+  }
+}
+`;
+
+export interface ToastProcess {
+  pid: number;
+  write(line: string): void;
+  end(): void;
+  stderr: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+}
+
+export type ToastSpawn = () => ToastProcess;
+
+// stdin carries the toast lines.
+const spawnHost: ToastSpawn = () => {
+  const proc = spawnPowerShell(HOST_SCRIPT, { stdin: 'pipe', stdout: 'ignore' });
+  return {
+    pid: proc.pid,
+    write(line) {
+      proc.stdin.write(line);
+      proc.stdin.flush();
+    },
+    end: () => proc.stdin.end(),
+    stderr: proc.stderr,
+    exited: proc.exited,
+  };
+};
+
+export interface ToasterOptions {
+  spawn?: ToastSpawn;
+  onError?: (msg: string) => void;
+}
+
+interface Running {
+  proc: ToastProcess;
+  done: Promise<number>;
+}
+
+/**
+ * Windows toast notifications through a long-lived PowerShell host, started on the first toast
+ * and again after it dies. Off Windows (without `spawn`) it returns a toaster that does nothing.
+ */
+export function createToaster(opts: ToasterOptions = {}): Toaster {
+  if (!opts.spawn && process.platform !== 'win32') return noopToaster;
+  const spawn = opts.spawn ?? spawnHost;
+  const onError = opts.onError ?? ((msg) => console.warn(`toast: ${msg}`));
+  let current: Running | null = null;
+
+  const start = (): Running => {
+    const proc = spawn();
+    const errors = forEachLine(proc.stderr, onError).catch(() => {});
+    const entry: Running = { proc, done: Promise.resolve(0) };
+    entry.done = Promise.all([proc.exited, errors]).then(([code]) => {
+      if (current === entry) current = null;
+      if (code !== 0) onError(`toast host exited with code ${code}`);
+      return code;
+    });
+    current = entry;
+    return entry;
+  };
+
+  return {
+    show(toast) {
+      const line = toastLine(toast);
+      try {
+        (current ?? start()).proc.write(line);
+      } catch {
+        // The host died between toasts and its exit isn't observed yet: start a fresh one.
+        current = null;
+        try {
+          start().proc.write(line);
+        } catch (err) {
+          current = null;
+          onError(`toast host unavailable: ${(err as Error).message}`);
+        }
+      }
+    },
+    async close() {
+      const entry = current;
+      if (!entry) return null;
+      current = null;
+      entry.proc.end();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<null>((resolve) => {
+        timer = setTimeout(resolve, 5000, null);
+      });
+      const code = await Promise.race([entry.done, timeout]);
+      clearTimeout(timer);
+      if (code === null) killTree(entry.proc.pid);
+      return code;
+    },
+  };
+}
+
+// `bun packages/platform/src/win/toast.ts --selftest`: shows one real toast; exit code 0 means
+// Windows accepted it.
+if (import.meta.main && process.argv.includes('--selftest')) {
+  let failed = false;
+  const toaster = createToaster({
+    onError: (msg) => {
+      failed = true;
+      console.error(msg);
+    },
+  });
+  toaster.show({ title: 'DeckBuilder self-test', body: 'Toasts work <&> "ção"', launch: 'https://example.com/' });
+  const code = await toaster.close();
+  process.exit(failed || code !== 0 ? 1 : 0);
+}

package/src/win/tray.ts

@@ -0,0 +1,223 @@
+import { isCompiledExe } from '../exe.ts';
+import { killTree } from '../run.ts';
+import { asciiJson, forEachLine, spawnPowerShell } from './powershell.ts';
+
+export interface TrayItem {
+  id: string;
+  label: string;
+}
+
+export interface Tray {
+  /** False off Windows, where nothing shows. */
+  supported: boolean;
+  /** Resolves once the icon shows; rejects when the host ends or hangs before that. */
+  ready: Promise<void>;
+  /** Removes the icon and ends the host. */
+  close(): Promise<void>;
+}
+
+const noopTray: Tray = { supported: false, ready: Promise.resolve(), close: async () => {} };
+
+export interface TrayProcess {
+  pid: number;
+  end(): void;
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+}
+
+export type TraySpawn = (script: string) => TrayProcess;
+
+export interface TrayOptions {
+  /** Hover text; Windows shows at most 63 characters. */
+  tooltip: string;
+  /** Menu entries in order; double-clicking the icon selects the first. */
+  items: TrayItem[];
+  /** File whose icon shows; default: the exe when compiled, else a generic application icon. */
+  iconPath?: string;
+  spawn?: TraySpawn;
+  onSelect: (id: string) => void;
+  onError?: (msg: string) => void;
+  /** How long `ready` waits for the icon before the host is killed; default 15 s. */
+  readyTimeoutMs?: number;
+}
+
+export interface TraySpec {
+  tooltip: string;
+  iconPath: string | null;
+  /** `line` is what the host prints when the entry is clicked. */
+  items: { label: string; line: string }[];
+}
+
+export function traySpec(opts: Pick<TrayOptions, 'tooltip' | 'items' | 'iconPath'>): TraySpec {
+  return {
+    tooltip: opts.tooltip.slice(0, 63),
+    iconPath: opts.iconPath ?? null,
+    // A single & marks a menu mnemonic.
+    items: opts.items.map((item) => ({ label: item.label.replace(/&/g, '&&'), line: asciiJson({ select: item.id }) })),
+  };
+}
+
+// The spec comes as base64 JSON, so labels need no escaping. [Console]::In.ReadLineAsync() blocks
+// in .NET Framework, so stdin is read through its own StreamReader, polled by a timer next to the
+// message loop; EOF (the parent quit or crashed) removes the icon and ends the host. A handler
+// error must not reach WinForms, which would show its exception dialog.
+const HOST_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+Add-Type -AssemblyName System.Windows.Forms, System.Drawing
+$spec = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('__SPEC__')) | ConvertFrom-Json
+function Send($line) { try { [Console]::Out.WriteLine($line); [Console]::Out.Flush() } catch {} }
+[System.Windows.Forms.Application]::add_ThreadException({ param($s, $e) try { [Console]::Error.WriteLine($e.Exception.Message) } catch {} })
+$icon = New-Object System.Windows.Forms.NotifyIcon
+$icon.Icon = [System.Drawing.SystemIcons]::Application
+if ($spec.iconPath) {
+  try { $icon.Icon = [System.Drawing.Icon]::ExtractAssociatedIcon($spec.iconPath) } catch { [Console]::Error.WriteLine($_.Exception.Message) }
+}
+$icon.Text = $spec.tooltip
+$menu = New-Object System.Windows.Forms.ContextMenuStrip
+foreach ($item in $spec.items) {
+  $entry = $menu.Items.Add($item.label)
+  $entry.Tag = $item.line
+  $entry.add_Click({ param($s) Send $s.Tag })
+}
+$icon.ContextMenuStrip = $menu
+$first = @($spec.items)[0]
+$icon.add_MouseDoubleClick({ param($s, $e) if ($first -and $e.Button -eq 'Left') { Send $first.line } })
+$stdin = New-Object System.IO.StreamReader([Console]::OpenStandardInput())
+$state = @{ read = $stdin.ReadLineAsync() }
+$timer = New-Object System.Windows.Forms.Timer
+$timer.Interval = 250
+$timer.add_Tick({
+  if (-not $state.read.IsCompleted) { return }
+  if (-not $state.read.IsFaulted -and $null -ne $state.read.Result) { $state.read = $stdin.ReadLineAsync(); return }
+  $timer.Stop()
+  [System.Windows.Forms.Application]::ExitThread()
+})
+$icon.Visible = $true
+Send '{"ready":true}'
+$timer.Start()
+[System.Windows.Forms.Application]::Run()
+$icon.Visible = $false
+$icon.Dispose()
+`;
+
+function trayScript(spec: TraySpec): string {
+  return HOST_SCRIPT.replace('__SPEC__', Buffer.from(JSON.stringify(spec), 'utf8').toString('base64'));
+}
+
+// -STA for WinForms; stdin is the parent's lifeline.
+const spawnHost: TraySpawn = (script) => {
+  const proc = spawnPowerShell(script, { sta: true, stdin: 'pipe', stdout: 'pipe' });
+  return { pid: proc.pid, end: () => proc.stdin.end(), stdout: proc.stdout, stderr: proc.stderr, exited: proc.exited };
+};
+
+/**
+ * A notification-area icon with a context menu, hosted by a PowerShell process. Off Windows
+ * (without `spawn`) it returns a tray that does nothing.
+ */
+export function createTray(opts: TrayOptions): Tray {
+  if (!opts.spawn && process.platform !== 'win32') return noopTray;
+  const spawn = opts.spawn ?? spawnHost;
+  const onError = opts.onError ?? ((msg) => console.warn(`tray: ${msg}`));
+  const iconPath = opts.iconPath ?? (isCompiledExe() ? process.execPath : undefined);
+
+  let resolveReady: () => void = () => {};
+  let rejectReady: (err: Error) => void = () => {};
+  const ready = new Promise<void>((resolve, reject) => {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+  // The caller may not wait for it; a rejection must not end the process.
+  ready.catch(() => {});
+
+  let proc: TrayProcess;
+  try {
+    proc = spawn(trayScript(traySpec({ ...opts, iconPath })));
+  } catch (err) {
+    rejectReady(new Error(`tray host unavailable: ${(err as Error).message}`));
+    return { supported: true, ready, close: async () => {} };
+  }
+
+  let shown = false;
+  let closing: Promise<void> | null = null;
+  const output = forEachLine(proc.stdout, (line) => {
+    let msg: { ready?: unknown; select?: unknown } | null = null;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      // reported below
+    }
+    if (msg?.ready === true) {
+      shown = true;
+      resolveReady();
+    } else if (typeof msg?.select === 'string') {
+      try {
+        opts.onSelect(msg.select);
+      } catch (err) {
+        onError(`menu entry ${msg.select} failed: ${(err as Error).message}`);
+      }
+    } else onError(`unexpected output: ${line}`);
+  }).catch(() => {});
+  const errors = forEachLine(proc.stderr, onError).catch(() => {});
+  const done = Promise.all([proc.exited, output, errors]).then(([code]) => {
+    if (!shown) rejectReady(new Error(`tray host exited with code ${code} before showing the icon`));
+    else if (!closing) onError(`tray host exited with code ${code}`);
+    return code;
+  });
+
+  const readyTimeoutMs = opts.readyTimeoutMs ?? 15_000;
+  const readyTimer = setTimeout(() => {
+    rejectReady(new Error(`tray icon didn't show within ${readyTimeoutMs / 1000} s`));
+    killTree(proc.pid);
+  }, readyTimeoutMs);
+  const stopReadyTimer = () => clearTimeout(readyTimer);
+  ready.then(stopReadyTimer, stopReadyTimer);
+
+  return {
+    supported: true,
+    ready,
+    close() {
+      closing ??= (async () => {
+        stopReadyTimer();
+        try {
+          proc.end();
+        } catch {
+          // already gone
+        }
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const timeout = new Promise<null>((resolve) => {
+          timer = setTimeout(resolve, 5000, null);
+        });
+        const code = await Promise.race([done, timeout]);
+        clearTimeout(timer);
+        if (code === null) killTree(proc.pid);
+      })();
+      return closing;
+    },
+  };
+}
+
+// `bun packages/platform/src/win/tray.ts --selftest`: shows the icon, then removes it; exit code 0
+// means it showed within 15 s.
+if (import.meta.main && process.argv.includes('--selftest')) {
+  const tray = createTray({
+    tooltip: 'DeckBuilder self-test',
+    items: [{ id: 'hello', label: 'Self-test <&> "ção"' }],
+    onSelect: (id) => console.log(`selected ${id}`),
+    onError: (msg) => console.error(msg),
+  });
+  if (!tray.supported) {
+    console.error('No tray on this platform.');
+    process.exit(1);
+  }
+  let code = 0;
+  try {
+    await tray.ready;
+  } catch (err) {
+    console.error((err as Error).message);
+    code = 1;
+  }
+  await tray.close();
+  process.exit(code);
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.