@deckbuilderkit/shell 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@deckbuilderkit/shell",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adrianogpena/deckbuilder.git",
+    "directory": "packages/shell"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./window-worker": "./src/window-worker.ts"
+  },
+  "dependencies": {
+    "@deckbuilderkit/platform": "0.1.1",
+    "@deckbuilderkit/server-core": "0.1.1",
+    "webview-bun": "^2.4.0"
+  }
+}

package/src/app-window.ts

@@ -0,0 +1,65 @@
+import type { Subprocess } from 'bun';
+import { appBrowserArgv } from '@deckbuilderkit/platform';
+import { DEFAULT_WINDOW, type WindowOptions } from './window.ts';
+
+export interface AppWindowOptions {
+  /** Edge or Chrome, from `findAppBrowser()`. */
+  browser: string;
+  /** Browser profile of the app; one profile means one browser process for all app windows. */
+  profileDir: string;
+  window?: WindowOptions;
+  /** A launch became the browser's main process: its exit will report "all closed". */
+  onMainStarted?: () => void;
+  /** A launch handed its window to a browser process that isn't tracked (e.g. left over from a crash). */
+  onUntracked?: () => void;
+}
+
+// A launch that stays up this long is the browser's main process; one that exits sooner handed
+// its window to a browser process already running on the same profile.
+const MAIN_AFTER_MS = 3000;
+
+let main: Subprocess | null = null;
+let pending = 0;
+
+/** True while the tracked browser process runs or a launch hasn't settled yet. */
+export function appWindowsOpen(): boolean {
+  return main !== null || pending > 0;
+}
+
+/**
+ * Opens `url` in an Edge/Chrome app window. `onAllClosed` runs when the main browser process
+ * exits, which means every app window of the profile is closed.
+ */
+export function openAppWindow(url: string, opts: AppWindowOptions, onAllClosed: () => void): void {
+  const size = { width: opts.window?.width ?? DEFAULT_WINDOW.width, height: opts.window?.height ?? DEFAULT_WINDOW.height };
+  const proc = Bun.spawn(appBrowserArgv(opts.browser, url, opts.profileDir, size), { stdio: ['ignore', 'ignore', 'ignore'] });
+  pending++;
+  let settled = false;
+  const settle = () => {
+    if (settled) return false;
+    settled = true;
+    pending--;
+    return true;
+  };
+  const timer = setTimeout(() => {
+    if (!settle() || main) return;
+    main = proc;
+    opts.onMainStarted?.();
+  }, MAIN_AFTER_MS);
+  void proc.exited.then(() => {
+    clearTimeout(timer);
+    if (proc === main) {
+      main = null;
+      onAllClosed();
+    } else if (settle() && !main) opts.onUntracked?.();
+  });
+}
+
+/** Closes the tracked browser process gracefully, so its profile isn't marked as crashed. */
+export function closeAppWindows(): void {
+  if (!main) return;
+  if (process.platform === 'win32') {
+    Bun.spawn(['taskkill', '/PID', String(main.pid)], { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: true });
+  } else main.kill('SIGTERM');
+  main = null;
+}

package/src/flags.ts

@@ -0,0 +1,87 @@
+import { type AppIdentity, DEV_PORT } from '@deckbuilderkit/server-core';
+
+/** The command line of an app, as `runApp` reads it. */
+export interface Flags {
+  /** The requested way to open the UI; runApp falls back from 'app' to 'browser' without Edge/Chrome. */
+  mode: 'window' | 'app' | 'browser' | 'none';
+  noOpen: boolean;
+  port?: number;
+  idleExitMinutes?: number;
+  dev: boolean;
+  help: boolean;
+  openUrl?: string;
+  afterUpdate: boolean;
+  window: boolean;
+}
+
+/**
+ * Parses the app's arguments (without the executable and script); unknown ones are ignored.
+ * With `--open-url` every other flag is ignored: a link holding a raw `"` can inject arguments.
+ */
+export function parseFlags(argv: string[]): Flags | { error: string } {
+  const flag = (name: string) => argv.includes(name);
+  const option = (name: string) => {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+
+  const openUrl = option('--open-url');
+  if (openUrl !== undefined) {
+    return { mode: 'window', noOpen: false, dev: false, help: false, openUrl, afterUpdate: false, window: false };
+  }
+
+  let port: number | undefined;
+  if (flag('--port')) {
+    const value = option('--port') ?? '';
+    port = /^\d{1,5}$/.test(value) ? Number(value) : NaN;
+    if (!(port <= 65535)) return { error: '--port wants a port number from 0 to 65535.' };
+  }
+  let idleExitMinutes: number | undefined;
+  if (flag('--idle-exit')) {
+    idleExitMinutes = Number(option('--idle-exit'));
+    if (!(idleExitMinutes > 0)) return { error: '--idle-exit wants a number of minutes greater than 0.' };
+  }
+
+  const dev = flag('--dev');
+  const noOpen = flag('--no-open');
+  const window = flag('--window');
+  const mode: Flags['mode'] = flag('--browser') ? (noOpen ? 'none' : 'browser')
+    : flag('--app') ? (noOpen ? 'none' : 'app')
+    : dev && !window ? 'none' : 'window';
+  return {
+    mode,
+    noOpen,
+    port,
+    idleExitMinutes,
+    dev,
+    help: flag('--help') || flag('-h'),
+    afterUpdate: flag('--after-update'),
+    window,
+  };
+}
+
+export function helpText(app: AppIdentity): string {
+  return `${app.name}
+
+Usage: ${app.id} [--app | --browser [--no-open]] [--port <n>] [--idle-exit <min>] [--dev [--window | --app]]
+       ${app.id} --open-url <uri>
+
+  --app              open the UI in an Edge/Chrome app window (falls back to --browser when
+                     neither is installed)
+  --browser          serve the UI to the default browser instead of opening a window; the
+                     Settings screen has a Quit button
+  --no-open          with --browser: print the address only
+  --port <n>         fixed port (default: any free port)
+  --idle-exit <min>  exit after <min> minutes without a request from an open UI (fractions
+                     allowed; the exe in --browser mode without a tray icon uses 10 without
+                     the flag)
+  --open-url <uri>   open a native window on <path> of a ${app.id}://open/<path> link
+                     (Windows passes deep links this way)
+  --dev              port ${DEV_PORT} for the Vite dev server (opens nothing unless --window, --app
+                     or --browser is given; never exits when idle). The printed URL survives
+                     reloads; after a watch restart open the newly printed one
+
+When ${app.name} already runs (outside --dev), a new launch opens a window or browser tab of
+the running instance instead.
+`;
+}

package/src/idle.ts

@@ -0,0 +1,38 @@
+type Interval = ReturnType<typeof setInterval>;
+
+export interface IdleWatchOptions {
+  timeoutMs: number;
+  now?: () => number;
+  setInterval?: (fn: () => void, ms: number) => Interval;
+  clearInterval?: (id: Interval) => void;
+  onIdle: () => void;
+}
+
+export interface IdleWatch {
+  /** Marks activity: the timeout starts over. */
+  touch(): void;
+  stop(): void;
+}
+
+/** Calls `onIdle` once when `touch` wasn't called for `timeoutMs`; checks every min(30 s, timeout / 2). */
+export function createIdleWatch(opts: IdleWatchOptions): IdleWatch {
+  const now = opts.now ?? Date.now;
+  const set = opts.setInterval ?? ((fn: () => void, ms: number) => setInterval(fn, ms));
+  const clear = opts.clearInterval ?? ((id: Interval) => clearInterval(id));
+  let last = now();
+  let id: Interval | null = set(() => {
+    if (now() - last < opts.timeoutMs) return;
+    stop();
+    opts.onIdle();
+  }, Math.min(30_000, opts.timeoutMs / 2));
+  function stop() {
+    if (id !== null) clear(id);
+    id = null;
+  }
+  return {
+    touch: () => {
+      last = now();
+    },
+    stop,
+  };
+}

package/src/index.ts

@@ -0,0 +1,318 @@
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import {
+  type AppIdentity,
+  DEV_PORT,
+  embeddedWebAssets,
+  type IndexTransform,
+  isUrlScheme,
+  launchCodes,
+  type Routes,
+  type SocketRoutes,
+  startServer,
+  VITE_PORT,
+} from '@deckbuilderkit/server-core';
+import { appHome, createTray, createUrlProtocol, findAppBrowser, isCompiledExe, openExternal, removeOldExe, type Tray, waitForUrl } from '@deckbuilderkit/platform';
+import { appWindowsOpen, closeAppWindows, openAppWindow } from './app-window.ts';
+import { helpText, parseFlags } from './flags.ts';
+import { createIdleWatch, type IdleWatch } from './idle.ts';
+import { acquireLock, createInstance, handOff, type OpenMode } from './instance.ts';
+import { parseAppLink } from './link.ts';
+import { launchUrl } from './urls.ts';
+import { openWindow, openWindows, type WindowOptions } from './window.ts';
+
+export type { OpenMode } from './instance.ts';
+export { DEFAULT_WINDOW, type WindowOptions } from './window.ts';
+
+/** What `onStart` gets to act on the running app. */
+export interface StartContext {
+  /**
+   * A link that opens the app on `#<path>`, e.g. for a toast's `launch`: `<id>://open/<path>` when
+   * `urlProtocol` is on in the Windows exe, else the local address with no secret in it (toast XML
+   * is stored on disk), which opens on the invalid-session message. Links that must work need
+   * `urlProtocol: true`.
+   */
+  link(path: string): string;
+  /** Opens a window (or browser tab) like a new launch would, on `#<path>` when given. */
+  show(mode: OpenMode, path?: string): void;
+  quit(): Promise<void>;
+}
+
+export interface TrayMenu {
+  /** Default "Open <app name>". */
+  openLabel?: string;
+  /** Default "Quit". */
+  quitLabel?: string;
+  /** Entries between Open and Quit; ids must not start with `__`. */
+  items?: { id: string; label: string; run(): void }[];
+}
+
+export interface RunOptions {
+  app: AppIdentity;
+  /** The app's API; as a function it gets the start context, called before the server serves. */
+  routes: Routes | ((ctx: StartContext) => Routes);
+  /** WebSocket routes (see `startServer`); as a function it gets the start context, like `routes`. */
+  sockets?: SocketRoutes | ((ctx: StartContext) => SocketRoutes);
+  /** Routes outside the session token check (see `startServer`); as a function it gets the start context, like `routes`. */
+  unauthenticated?: Routes | ((ctx: StartContext) => Routes);
+  /** Awaited first on every exit path (window close, tray Quit, `/api/quit`, idle, signals); errors are logged and ignored. */
+  onQuit?: () => void | Promise<void>;
+  /** Built UI folder, served when running from source; the exe serves its embedded copy instead. */
+  webDir: string;
+  /** Rewrites `index.html` before it is served, e.g. `themeHead(settings)` for the saved colours. */
+  transformIndex?: IndexTransform;
+  window?: WindowOptions;
+  /**
+   * Registers `<app.id>://` on Windows (exe only), so `<id>://open/<path>` links open the app;
+   * `app.id` must then be a valid URL scheme.
+   */
+  urlProtocol?: boolean;
+  /**
+   * A notification-area icon (Windows, not in --dev) with Open, the app's entries and Quit. The
+   * app then keeps running when its last window closes, and only exits when idle with --idle-exit.
+   */
+  tray?: boolean | TrayMenu;
+  /** Runs once the server listens; not in a launch that hands off to a running instance. */
+  onStart?: (ctx: StartContext) => void | Promise<void>;
+}
+
+/**
+ * Starts the local server, then opens the UI in a native window (default), an Edge/Chrome app
+ * window or the browser. Outside --dev only one instance runs: a second launch makes the running
+ * one open a new window (or browser tab) and exits. Run `<app> --help` for the flags.
+ */
+export async function runApp(opts: RunOptions): Promise<void> {
+  const { app } = opts;
+  const flags = parseFlags(process.argv.slice(2));
+  if ('error' in flags) {
+    console.error(`${flags.error}\n\n${helpText(app)}`);
+    process.exit(1);
+  }
+  if (flags.help) {
+    console.log(helpText(app));
+    process.exit(0);
+  }
+  if (flags.dev && isCompiledExe()) {
+    console.error('--dev only works from source.');
+    process.exit(1);
+  }
+
+  if (opts.urlProtocol && !isUrlScheme(app.id)) {
+    throw new Error(`urlProtocol needs an app id that is a valid URL scheme, not "${app.id}".`);
+  }
+  const trayMenu = opts.tray === true ? {} : opts.tray || null;
+  const reserved = trayMenu?.items?.find((item) => item.id.startsWith('__'));
+  if (reserved) throw new Error(`Tray entry ids must not start with "__", got "${reserved.id}".`);
+  const { dev, openUrl, idleExitMinutes: idleMinutes } = flags;
+  // A link that doesn't parse still opens the app, just without a path.
+  const startPath = openUrl === undefined ? undefined : (parseAppLink(openUrl, app.id) ?? undefined);
+  let mode: OpenMode = flags.mode;
+  const browser = mode === 'app' ? findAppBrowser() : null;
+  if (mode === 'app' && !browser) {
+    console.warn('No Edge or Chrome found for --app; using the default browser.');
+    mode = 'browser';
+  }
+  const port = flags.port ?? (dev ? DEV_PORT : 0);
+  const token = randomBytes(24).toString('hex');
+  // Launch URLs carry one-time codes, never the token; the dev code stays valid so reloads work.
+  const codes = launchCodes({ reusable: dev });
+  const embedded = embeddedWebAssets();
+  const instanceFile = join(appHome(app.id), 'instance.json');
+
+  const alreadyRunning = (running: true | string) => {
+    if (running === true) console.log(`${app.name} is already running; opened a new ${mode === 'browser' ? 'browser tab' : 'window'}.`);
+    else console.log(`${app.name} is already running at ${running}`);
+    process.exit(0);
+  };
+  // Another launch holds the start-up lock: wait until it answers as the instance.
+  const waitForOther = async () => {
+    const deadline = Date.now() + 10_000;
+    while (Date.now() < deadline) {
+      await Bun.sleep(250);
+      const running = await handOff(instanceFile, mode, startPath);
+      if (running) alreadyRunning(running);
+    }
+    console.error(`Another ${app.name} launch is starting but doesn't answer. Try again.`);
+    process.exit(1);
+  };
+  if (!dev) {
+    const lockFile = join(appHome(app.id), 'instance.lock');
+    // Started by the previous exe after it swapped itself out: wait until that one has exited.
+    if (flags.afterUpdate && isCompiledExe()) await removeOldExe(process.execPath);
+    else {
+      const running = await handOff(instanceFile, mode, startPath);
+      if (running) alreadyRunning(running);
+    }
+    if (acquireLock(lockFile) === 'held') await waitForOther();
+  }
+
+  // Where the UI is served: Vite in --dev, else this server. Set once the server listens.
+  let origin = '';
+  let idle: IdleWatch | null = null;
+  // Set while the tray icon starts or shows; `trayShown` once it does.
+  let tray: Tray | null = null;
+  let trayShown = false;
+  let closedWhileTrayStarts = false;
+  // Only the explicit --idle-exit watch, created at startup, survives the tray showing.
+  const enableIdleExit = (ms: number) => {
+    if (dev || idle || trayShown) return;
+    idle = createIdleWatch({ timeoutMs: ms, onIdle: () => void quit() });
+  };
+  const disableIdleExit = () => {
+    idle?.stop();
+    idle = null;
+  };
+  /** The single exit path. */
+  const quit = async (): Promise<void> => {
+    disableIdleExit();
+    try {
+      await opts.onQuit?.();
+    } catch (err) {
+      console.error(err);
+    }
+    closeAppWindows();
+    await Promise.all([server?.stop(true), tray?.close()]);
+    process.exit(0);
+  };
+  // Native windows and app windows both report here; the app ends once neither kind is open,
+  // unless it has a tray icon. While the icon starts, it waits to see whether it shows.
+  const onAllClosed = () => {
+    if (openWindows() > 0 || appWindowsOpen()) return;
+    if (!tray) void quit();
+    else if (!trayShown) closedWhileTrayStarts = true;
+  };
+  // WebView2 keeps its profile in %APPDATA%\<exe name>\: the webview library passes that
+  // folder explicitly, so WEBVIEW2_USER_DATA_FOLDER has no effect.
+  const openNative = (url: string) => {
+    openWindow(url, { title: app.name, debug: dev, stateFile: join(appHome(app.id), 'window.json'), ...opts.window }, onAllClosed);
+  };
+  const show = (m: OpenMode, path?: string): string => {
+    const url = launchUrl(origin, codes, path);
+    if (m === 'window') openNative(url);
+    else if (m === 'app') {
+      const exe = browser ?? findAppBrowser();
+      if (!exe) openExternal(url);
+      else {
+        openAppWindow(
+          url,
+          {
+            browser: exe,
+            profileDir: join(appHome(app.id), 'app-profile'),
+            window: opts.window,
+            // Windows of a browser process we don't watch never report closing: end when idle instead.
+            onUntracked: () => enableIdleExit(10 * 60_000),
+            onMainStarted: () => {
+              if (idleMinutes === undefined) disableIdleExit();
+            },
+          },
+          onAllClosed,
+        );
+      }
+    } else if (m === 'browser') openExternal(url);
+    return url;
+  };
+  const instance = dev ? null : createInstance(instanceFile, show);
+
+  const linkViaProtocol = !!opts.urlProtocol && process.platform === 'win32' && isCompiledExe();
+  // Filled in once the server listens; routes only run after that.
+  let serverPort = 0;
+  const ctx: StartContext = {
+    link: (path) => (linkViaProtocol ? `${app.id}://open/${path}` : `http://127.0.0.1:${serverPort}/#${path}`),
+    show: (m, path) => void show(m, path),
+    quit,
+  };
+
+  const routes: Routes = {
+    ...(typeof opts.routes === 'function' ? opts.routes(ctx) : opts.routes),
+    'POST /api/quit': () => {
+      setTimeout(() => void quit(), 200);
+      return { ok: true };
+    },
+    'POST /api/alive': () => ({ ok: true }),
+  };
+
+  const sockets = typeof opts.sockets === 'function' ? opts.sockets(ctx) : opts.sockets;
+  const unauthenticated: Routes = { ...instance?.routes, ...(typeof opts.unauthenticated === 'function' ? opts.unauthenticated(ctx) : opts.unauthenticated) };
+
+  let server: ReturnType<typeof startServer> | undefined;
+  try {
+    server = startServer({
+      routes,
+      sockets,
+      unauthenticated,
+      token,
+      codes,
+      devOrigins: dev ? [`http://localhost:${VITE_PORT}`, `http://127.0.0.1:${VITE_PORT}`] : undefined,
+      port,
+      web: { ...(embedded ? { files: embedded } : { dir: opts.webDir }), transformIndex: opts.transformIndex },
+      onActivity: () => idle?.touch(),
+    });
+  } catch (err) {
+    if ((err as { code?: string }).code === 'EADDRINUSE') console.error(`Port ${port} is already in use. Pass --port with another port.`);
+    else console.error(err);
+    process.exit(1);
+  }
+
+  serverPort = server.port!;
+  origin = dev ? `http://localhost:${VITE_PORT}` : `http://127.0.0.1:${serverPort}`;
+  instance?.publish(serverPort);
+
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => void quit());
+  // The exe in browser mode has no window to close, so it ends once no tab has called for a while.
+  if (idleMinutes !== undefined) enableIdleExit(idleMinutes * 60_000);
+  else if (mode === 'browser' && isCompiledExe()) enableIdleExit(10 * 60_000);
+
+  if (opts.urlProtocol) {
+    void createUrlProtocol({ scheme: app.id, name: app.name }).fixUp().catch((err) => console.error(err));
+  }
+  if (trayMenu && !dev) {
+    tray = startTray({
+      name: app.name,
+      menu: trayMenu,
+      open: () => void show(mode === 'none' ? 'window' : mode),
+      quit: () => void quit(),
+      onShown: () => {
+        trayShown = true;
+        if (idleMinutes === undefined) disableIdleExit();
+      },
+      onFailed: (err) => {
+        console.warn(`No tray icon: ${err.message}`);
+        tray = null;
+        if (closedWhileTrayStarts) onAllClosed();
+      },
+    });
+  }
+  void Promise.resolve(opts.onStart?.(ctx)).catch((err) => console.error(err));
+
+  // Prints the URL the first open used: one-time outside --dev, so with --no-open it is still unused.
+  const announce = (url: string) => {
+    if (mode !== 'window') console.log(`\n  ${app.name} running at ${url}\n  Press Ctrl+C to stop.\n`);
+  };
+  // `deckbuilder dev` starts Vite only once this server answers; don't load the page before Vite does.
+  if (dev && (mode === 'window' || mode === 'app')) void waitForUrl(origin, { timeoutMs: 30_000 }).then(() => announce(show(mode, startPath)));
+  else announce(show(mode, startPath));
+}
+
+/** Shows the tray icon with Open, the app's entries and Quit; null where there is no tray. */
+function startTray(o: {
+  name: string;
+  menu: TrayMenu;
+  open: () => void;
+  quit: () => void;
+  onShown: () => void;
+  onFailed: (err: Error) => void;
+}): Tray | null {
+  const entries = [
+    { id: '__open', label: o.menu.openLabel ?? `Open ${o.name}`, run: o.open },
+    ...(o.menu.items ?? []),
+    { id: '__quit', label: o.menu.quitLabel ?? 'Quit', run: o.quit },
+  ];
+  const tray = createTray({
+    tooltip: o.name,
+    items: entries.map(({ id, label }) => ({ id, label })),
+    onSelect: (id) => entries.find((entry) => entry.id === id)?.run(),
+  });
+  if (!tray.supported) return null;
+  tray.ready.then(o.onShown, o.onFailed);
+  return tray;
+}

package/src/instance.ts

@@ -0,0 +1,166 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { linkSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { Routes } from '@deckbuilderkit/server-core';
+import { isSafePath } from './link.ts';
+
+// Single instance: the running app publishes its port and a secret in instance.json (in the app
+// data folder). A second launch asks it to open what was requested and exits. The secret only
+// unlocks this one route, not the API: its response carries no session token, at most a launch URL
+// with a one-time code.
+
+export const INSTANCE_HEADER = 'x-deckbuilder-instance';
+export const INSTANCE_PATH = '/api/instance/open';
+export const INSTANCE_ROUTE = `POST ${INSTANCE_PATH}`;
+
+/** What a launch asks for: a native window, an Edge/Chrome app window, a browser tab, or nothing (`--no-open`). */
+export type OpenMode = 'window' | 'app' | 'browser' | 'none';
+
+interface InstanceInfo {
+  pid: number;
+  port: number;
+  secret: string;
+}
+
+function readInfo(file: string): InstanceInfo | null {
+  try {
+    const info = JSON.parse(readFileSync(file, 'utf8')) as Partial<InstanceInfo>;
+    return typeof info.port === 'number' && typeof info.secret === 'string' && typeof info.pid === 'number' ? (info as InstanceInfo) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Asks the instance published in `file` to open `mode`, on `path` when given. Resolves true once it
+ * opened it, a fresh launch URL for mode 'none', or null when none answers (no file, or a stale one
+ * left by a killed process).
+ */
+export async function handOff(file: string, mode: OpenMode, path?: string, fetchFn: typeof fetch = fetch): Promise<true | string | null> {
+  const info = readInfo(file);
+  if (!info) return null;
+  try {
+    const res = await fetchFn(`http://127.0.0.1:${info.port}${INSTANCE_PATH}`, {
+      method: 'POST',
+      headers: { [INSTANCE_HEADER]: info.secret, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ mode, path }),
+      signal: AbortSignal.timeout(3000),
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { url?: unknown; ok?: unknown };
+    if (typeof body.url === 'string') return body.url;
+    return body.ok === true ? true : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface Instance {
+  /** Unauthenticated route for the server; it checks the secret itself. */
+  routes: Routes;
+  /** Writes instance.json once the server listens; it is removed again on exit. */
+  publish(port: number): void;
+}
+
+/**
+ * `open` opens what a later launch asked for and returns the launch URL it used, if any. Only mode
+ * 'none' sends it back: that launch wants an address to print.
+ */
+export function createInstance(file: string, open: (mode: OpenMode, path?: string) => string | null): Instance {
+  const secret = Buffer.from(randomBytes(24).toString('hex'));
+  return {
+    routes: {
+      [INSTANCE_ROUTE]: async ({ req, json }) => {
+        const given = Buffer.from(req.headers.get(INSTANCE_HEADER) ?? '');
+        if (given.length !== secret.length || !timingSafeEqual(given, secret)) return new Response('Forbidden', { status: 403 });
+        const { mode, path } = await json<{ mode?: unknown; path?: unknown }>();
+        const safe = typeof path === 'string' && isSafePath(path) ? path : undefined;
+        const m = mode === 'app' || mode === 'browser' || mode === 'none' ? mode : 'window';
+        const url = open(m, safe);
+        return m === 'none' && url !== null ? { url } : { ok: true };
+      },
+    },
+    publish(port) {
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, JSON.stringify({ pid: process.pid, port, secret: secret.toString() }), { mode: 0o600 });
+      process.on('exit', () => {
+        // A later instance may have taken the file over (e.g. after an update); leave its file.
+        if (readInfo(file)?.pid === process.pid) rmSync(file, { force: true });
+      });
+    },
+  };
+}
+
+function lockPid(file: string): number | null {
+  try {
+    const pid = Number(readFileSync(file, 'utf8').trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: the process exists but belongs to someone else.
+    return (err as { code?: string }).code === 'EPERM';
+  }
+}
+
+/** A lock older than this whose pid isn't the published instance is stale, whatever the pid. */
+const LOCK_MAX_AGE_MS = 60_000;
+
+/**
+ * A lock is stale when its process is gone, or when it is old and no published instance owns it:
+ * pids get reused, so a dead launch's lock can name a live, unrelated process.
+ */
+function staleLock(file: string, pid: number | null, now: number, instanceFile: string): boolean {
+  if (pid === null || pid === process.pid || !alive(pid)) return true;
+  let mtime: number;
+  try {
+    mtime = statSync(file).mtimeMs;
+  } catch {
+    return true;
+  }
+  return now - mtime > LOCK_MAX_AGE_MS && readInfo(instanceFile)?.pid !== pid;
+}
+
+/**
+ * Takes the start-up lock that keeps two launches from both becoming the instance. 'held' means
+ * another live launch has it; a stale lock (see `staleLock`) is taken over. Released on exit.
+ * `instanceFile` defaults to instance.json next to the lock.
+ */
+export function acquireLock(file: string, opts: { now?: () => number; instanceFile?: string } = {}): 'acquired' | 'held' {
+  const now = opts.now ?? Date.now;
+  const instanceFile = opts.instanceFile ?? join(dirname(file), 'instance.json');
+  mkdirSync(dirname(file), { recursive: true });
+  // Link a complete temp file into place: the lock never exists without its pid.
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, String(process.pid));
+  try {
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        linkSync(tmp, file);
+      } catch (err) {
+        if ((err as { code?: string }).code !== 'EEXIST') throw err;
+        if (!staleLock(file, lockPid(file), now(), instanceFile)) return 'held';
+        rmSync(file, { force: true });
+        continue;
+      }
+      // Two launches that both found the same stale lock: the later one removed ours. Wait for
+      // such a launch to finish its link, then trust only what is on disk.
+      Bun.sleepSync(100);
+      if (lockPid(file) !== process.pid) return 'held';
+      process.on('exit', () => {
+        if (lockPid(file) === process.pid) rmSync(file, { force: true });
+      });
+      return 'acquired';
+    }
+    return 'held';
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+}

package/src/link.ts

@@ -0,0 +1,16 @@
+// Deep links: `<scheme>://open/<path>` opens the app on `#<path>`.
+
+/** A path that is safe to put after `#` in the UI address. */
+export function isSafePath(path: string): boolean {
+  return /^[A-Za-z0-9_\-./]*$/.test(path) && !path.includes('..');
+}
+
+/** The path of a `<scheme>://open/<path>` link, or null when it is not one or the path is unsafe. */
+export function parseAppLink(uri: string, scheme: string): string | null {
+  const prefix = `${scheme}://open`;
+  if (uri.slice(0, prefix.length).toLowerCase() !== prefix.toLowerCase()) return null;
+  const rest = uri.slice(prefix.length);
+  if (rest !== '' && !rest.startsWith('/')) return null;
+  const path = rest.replace(/^\//, '').replace(/\/$/, '');
+  return isSafePath(path) ? path : null;
+}

package/src/urls.ts

@@ -0,0 +1,7 @@
+import { CODE_PARAM, type LaunchCodes } from '@deckbuilderkit/server-core';
+
+/** A URL that opens the UI at `origin`, on `#<path>` when given, with a fresh launch code. */
+export function launchUrl(origin: string, codes: LaunchCodes, path?: string): string {
+  const url = `${origin}/?${CODE_PARAM}=${codes.issue()}`;
+  return path ? `${url}#${path}` : url;
+}

package/src/webview-bun.d.ts

@@ -0,0 +1,31 @@
+// webview-bun ships TypeScript source, not .d.ts, so skipLibCheck doesn't cover it and its
+// source fails our strict settings. tsconfig.json maps the import here; bun still runs the real package.
+// Only the parts the shell uses are declared.
+export enum SizeHint {
+  NONE = 0,
+  MIN = 1,
+  MAX = 2,
+  FIXED = 3,
+}
+
+export interface Size {
+  width: number;
+  height: number;
+  hint: SizeHint;
+}
+
+export class Webview {
+  constructor(debug?: boolean, size?: Size);
+  /** Null when the native webview could not be created. */
+  get unsafeHandle(): unknown;
+  /** The native window: an HWND on Windows. */
+  get unsafeWindowHandle(): import('bun:ffi').Pointer | null;
+  set title(title: string);
+  set size(size: Size);
+  navigate(url: string): void;
+  init(source: string): void;
+  eval(source: string): void;
+  bind(name: string, callback: (...args: any[]) => any): void;
+  run(): void;
+  destroy(): void;
+}

package/src/webview-zoom.ts

@@ -0,0 +1,26 @@
+// The window's own zoom (what Ctrl+wheel used to change), set through WebView2's ICoreWebView2Controller.
+// webview-bun 2.4.0 doesn't bind webview_get_native_handle, so the library is opened a second time for it.
+import { CFunction, dlopen, FFIType, read, type Pointer } from 'bun:ffi';
+// @ts-expect-error a native library imported as a file path, as webview-bun does
+import bundledLib from 'webview-bun/build/libwebview.dll' with { type: 'file' };
+
+const BROWSER_CONTROLLER = 2;
+/** ICoreWebView2Controller vtable: IUnknown (3), get/put_IsVisible, get/put_Bounds, get_ZoomFactor, put_ZoomFactor. */
+const PUT_ZOOM_FACTOR = 8;
+
+/** Sets the zoom of the webview `handle` (webview-bun's `unsafeHandle`); call it on the window's thread. Windows only. */
+export function setWebviewZoom(handle: Pointer, factor: number): void {
+  if (process.platform !== 'win32' || !Number.isFinite(factor) || factor <= 0) return;
+  const lib = dlopen((process.env.WEBVIEW_PATH as string | undefined) ?? (bundledLib as string), {
+    webview_get_native_handle: { args: [FFIType.ptr, FFIType.i32], returns: FFIType.ptr },
+  });
+  try {
+    const controller = lib.symbols.webview_get_native_handle(handle, BROWSER_CONTROLLER);
+    if (!controller) return;
+    const vtable = read.ptr(controller, 0) as Pointer;
+    const putZoomFactor = CFunction({ ptr: read.ptr(vtable, PUT_ZOOM_FACTOR * 8) as Pointer, args: [FFIType.ptr, FFIType.f64], returns: FFIType.i32 });
+    putZoomFactor(controller, factor);
+  } finally {
+    lib.close();
+  }
+}

package/src/window-worker.ts

@@ -0,0 +1,91 @@
+// One native window per Worker: Webview.run() blocks this thread until the window closes.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { getWindowPlacement, openExternal, parsePlacement, setWindowIconFromExe, setWindowPlacement, showWindow, type WindowPlacement } from '@deckbuilderkit/platform';
+import type { Pointer } from 'bun:ffi';
+import { SizeHint, Webview } from 'webview-bun';
+import { setWebviewZoom } from './webview-zoom.ts';
+import type { WindowRequest } from './window.ts';
+
+declare const self: Worker;
+
+function readPlacement(file: string): WindowPlacement | undefined {
+  try {
+    return parsePlacement(JSON.parse(readFileSync(file, 'utf8')));
+  } catch {
+    return undefined;
+  }
+}
+
+// Runs before every page load. Tells the UI it is in a window, sends links to other origins to
+// the default browser instead of navigating the app window away, and stops Ctrl+wheel and
+// Ctrl +/-/0 from zooming the whole window (the zoom is a setting; the page still gets the events).
+const INIT = `
+window.__DECKBUILDER_SHELL__ = 'window';
+(() => {
+  addEventListener('wheel', (e) => { if (e.ctrlKey) e.preventDefault(); }, { passive: false, capture: true });
+  const zoomKeys = ['Equal', 'Minus', 'Digit0', 'NumpadAdd', 'NumpadSubtract', 'Numpad0'];
+  addEventListener('keydown', (e) => { if (e.ctrlKey && zoomKeys.includes(e.code)) e.preventDefault(); }, { capture: true });
+  const external = (href) => {
+    try { return new URL(href, location.href).origin !== location.origin; } catch { return false; }
+  };
+  document.addEventListener('click', (e) => {
+    // getAttribute, not a.href: an SVG link's href is an SVGAnimatedString, not a URL.
+    const a = e.target instanceof Element ? e.target.closest('a') : null;
+    const href = a && (a.getAttribute('href') ?? a.getAttribute('xlink:href'));
+    if (href == null || e.defaultPrevented || !external(href)) return;
+    e.preventDefault();
+    window.__deckbuilderOpenExternal(new URL(href, location.href).href);
+  });
+  const saveBounds = () => { if (window.__deckbuilderSaveBounds) window.__deckbuilderSaveBounds(); };
+  setInterval(saveBounds, 1000);
+  addEventListener('beforeunload', saveBounds);
+  const open = window.open;
+  window.open = (url, ...rest) => {
+    if (url && external(String(url))) { window.__deckbuilderOpenExternal(String(url)); return null; }
+    return open.call(window, url, ...rest);
+  };
+})();
+`;
+
+self.onmessage = (e: MessageEvent<WindowRequest>) => {
+  // The window shows #121212 until the page paints (WEBVIEW2_DEFAULT_BACKGROUND_COLOR has no effect
+  // with this webview library); the palette inlined into index.html (themeHead) carries the first paint.
+  const { url, title, width, height, debug, stateFile } = e.data;
+  const webview = new Webview(debug, { width, height, hint: SizeHint.NONE });
+  if (!webview.unsafeHandle) {
+    // WebView2 failed to start, e.g. its profile folder is still locked by msedgewebview2.exe
+    // processes of a previous run that was killed.
+    self.postMessage({ error: 'Could not create the window (WebView2 failed to start).' });
+    process.exit(1);
+  }
+  // Started through `bun run`, the process starts hidden and the library's own show is swallowed.
+  const hwnd = webview.unsafeWindowHandle;
+  showWindow(hwnd);
+  setWindowIconFromExe(hwnd);
+  if (stateFile) {
+    const saved = readPlacement(stateFile);
+    if (saved) setWindowPlacement(hwnd, saved);
+    // The window is gone once run() returns, so the page reports in while it lives: every second and on unload.
+    let last = JSON.stringify(saved ?? null);
+    webview.bind('__deckbuilderSaveBounds', () => {
+      const now = getWindowPlacement(hwnd);
+      const text = JSON.stringify(now ?? null);
+      if (!now || text === last) return;
+      last = text;
+      try {
+        mkdirSync(dirname(stateFile), { recursive: true });
+        writeFileSync(stateFile, text);
+      } catch {
+        // losing the position is harmless
+      }
+    });
+  }
+  webview.title = title;
+  webview.bind('__deckbuilderOpenExternal', (href: string) => openExternal(href));
+  webview.bind('__deckbuilderSetZoom', (factor: number) => setWebviewZoom(webview.unsafeHandle as Pointer, factor));
+  webview.init(INIT);
+  webview.navigate(url);
+  webview.run();
+  process.exit(0);
+};

package/src/window.ts

@@ -0,0 +1,57 @@
+import { showError } from '@deckbuilderkit/platform';
+
+export interface WindowOptions {
+  title?: string;
+  width?: number;
+  height?: number;
+  /** Enables the WebView2 dev tools (F12, right-click → Inspect). */
+  debug?: boolean;
+  /** JSON file where the window's position, size and maximized state are kept between runs. */
+  stateFile?: string;
+}
+
+/** Message the window worker receives. */
+export interface WindowRequest {
+  url: string;
+  title: string;
+  width: number;
+  height: number;
+  debug: boolean;
+  stateFile?: string;
+}
+
+/** Size of a new native or app window unless the app passes one. */
+export const DEFAULT_WINDOW = { width: 1280, height: 820 };
+
+let open = 0;
+
+/** Native windows that are still open. */
+export function openWindows(): number {
+  return open;
+}
+
+/**
+ * Opens a native window on `url`. Each window runs in its own Worker because Webview.run()
+ * blocks its thread; the server stays on the main thread. `onAllClosed` runs when the last one closes.
+ */
+export function openWindow(url: string, opts: WindowOptions, onAllClosed: () => void): void {
+  open++;
+  // In the exe this resolves next to the bundled entry, where `deckbuilder build` puts the worker entrypoint.
+  const worker = new Worker(new URL('./window-worker.ts', import.meta.url).href);
+  const request: WindowRequest = {
+    url,
+    title: opts.title ?? '',
+    width: opts.width ?? DEFAULT_WINDOW.width,
+    height: opts.height ?? DEFAULT_WINDOW.height,
+    debug: opts.debug ?? false,
+    stateFile: opts.stateFile,
+  };
+  worker.postMessage(request);
+  worker.addEventListener('message', (e: MessageEvent<{ error?: string }>) => {
+    if (e.data.error) showError(opts.title ?? 'Error', e.data.error);
+  });
+  worker.addEventListener('error', (e) => showError(opts.title ?? 'Error', `Window failed: ${e.message}`));
+  worker.addEventListener('close', () => {
+    if (--open === 0) onAllClosed();
+  });
+}

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.