@mirinjs/cli 0.1.0-alpha.1 → 0.1.0-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mirinjs/cli",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.11",
   "description": "CLI for mirin apps: dev, build, init.",
   "type": "module",
   "license": "MIT",
@@ -27,12 +27,12 @@
     "bun": ">=1.2.0"
   },
   "dependencies": {
-    "create-mirinjs": "0.1.0-alpha.1",
-    "mirinjs": "0.1.0-alpha.1"
+    "create-mirinjs": "0.1.0-alpha.11",
+    "mirinjs": "0.1.0-alpha.11"
   },
   "optionalDependencies": {
-    "@mirinjs/darwin-arm64": "0.1.0-alpha.1",
-    "@mirinjs/win32-x64": "0.1.0-alpha.1"
+    "@mirinjs/darwin-arm64": "0.1.0-alpha.11",
+    "@mirinjs/win32-x64": "0.1.0-alpha.11"
   },
   "publishConfig": {
     "access": "public"

package/src/artifacts.ts

@@ -67,7 +67,9 @@ export async function resolveArtifacts(opts: { release: boolean }): Promise<Arti
 
 /** The native core library file name for the host platform (MSVC has no `lib` prefix). */
 function coreFileName(): string {
-  return process.platform === "win32" ? "mirin_core.dll" : "libmirin_core.dylib";
+  if (process.platform === "win32") return "mirin_core.dll";
+  if (process.platform === "linux") return "libmirin_core.so";
+  return "libmirin_core.dylib";
 }
 
 /** The CEF subprocess binary name for the host platform. */
@@ -78,10 +80,12 @@ function helperFileName(): string {
 function assertSupportedPlatform(): void {
   const supported =
     (process.platform === "darwin" && process.arch === "arm64") ||
-    (process.platform === "win32" && process.arch === "x64");
+    (process.platform === "win32" && process.arch === "x64") ||
+    (process.platform === "linux" && process.arch === "x64");
   if (!supported) {
     throw new Error(
-      `mirin alpha supports macOS arm64 and Windows x64 (got ${process.platform}/${process.arch}).`,
+      `mirin alpha supports macOS arm64, Windows x64, and Linux x64 ` +
+        `(got ${process.platform}/${process.arch}).`,
     );
   }
 }
@@ -113,9 +117,12 @@ function cliVersion(): string {
 }
 
 /** A file/dir that, if present in a CEF dir, means the distribution is unpacked.
- *  macOS ships the framework bundle; Windows ships a flat dir with libcef.dll. */
+ *  macOS ships the framework bundle; Windows ships a flat dir with libcef.dll;
+ *  Linux ships a flat dir with libcef.so. */
 function cefMarker(): string {
-  return process.platform === "win32" ? "libcef.dll" : "Chromium Embedded Framework.framework";
+  if (process.platform === "win32") return "libcef.dll";
+  if (process.platform === "linux") return "libcef.so";
+  return "Chromium Embedded Framework.framework";
 }
 
 async function ensureCef(): Promise<string> {

package/src/build.ts

@@ -16,15 +16,92 @@
  */
 
 import { $ } from "bun";
-import { mkdirSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { mkdirSync, rmSync, readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { buildAppBundle } from "./bundle.ts";
 import { buildWindowsBundle } from "./bundle-win.ts";
+import { buildLinuxBundle } from "./bundle-linux.ts";
+import { buildLinuxPackages, resolveLinuxFormats } from "./package-linux.ts";
+import { makeWindowsIcon } from "./icon-win.ts";
 import { resolveArtifacts } from "./artifacts.ts";
 import { sweepBuildTemps } from "./temps.ts";
 import { normalizeSidecars, compileWorkers } from "./extras.ts";
 
 const IS_WINDOWS = process.platform === "win32";
+const IS_LINUX = process.platform === "linux";
+
+/** A PE FILEVERSION (`x.y.z.w`) from a semver string (pre-release suffix dropped). */
+function winFileVersion(v: string): string {
+  const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? `${m[1]}.${m[2]}.${m[3]}.0` : "0.0.0.0";
+}
+
+/**
+ * Flip a PE exe from the CONSOLE subsystem (3) to GUI (2) so Windows allocates
+ * **no console window** when it's launched from a shortcut. Bun's
+ * `--windows-hide-console` only hides the console at runtime (a brief flash);
+ * GUI subsystem prevents it entirely — the equivalent of Electrobun's
+ * `exe.subsystem = .Windows`. The optional-header Subsystem field is at
+ * `e_lfanew + 24 (PE sig + COFF) + 68`.
+ */
+function patchPeToGuiSubsystem(exePath: string): void {
+  const buf = readFileSync(exePath);
+  const peOff = buf.readUInt32LE(0x3c);
+  if (buf.readUInt32LE(peOff) !== 0x0000_4550) return; // not "PE\0\0"
+  const subsystemOff = peOff + 92;
+  if (buf.readUInt16LE(subsystemOff) === 3 /* CONSOLE */) {
+    buf.writeUInt16LE(2 /* GUI */, subsystemOff);
+    writeFileSync(exePath, buf);
+  }
+}
+
+/**
+ * Stamp a Bun-compiled Windows exe with the app icon + version metadata via
+ * rcedit. Bun's `--windows-icon` is a silent no-op on Windows hosts, so without
+ * this the exe keeps Bun's icon — which the Start Menu / Desktop shortcut, the
+ * taskbar, and Explorer all show. Uses a single largest-size icon: rcedit's
+ * multi-size replacement silently fails on Bun's appended-payload exes, while a
+ * single 256 entry takes and Windows downscales it cleanly for smaller views.
+ * Best-effort — warns (doesn't fail the build) if rcedit isn't installed.
+ */
+async function brandWindowsExe(
+  exe: string,
+  opts: {
+    projectDir: string;
+    work: string;
+    appName: string;
+    version: string;
+    icon?: string;
+    publisher: string;
+  },
+): Promise<void> {
+  if (!Bun.which("rcedit")) {
+    console.warn(
+      "[mirin build] rcedit not found — the Windows exe keeps Bun's default icon. " +
+        "Install it: `scoop install rcedit` (or `choco install rcedit`).",
+    );
+    return;
+  }
+  const args: string[] = [];
+  if (opts.icon) {
+    const ico = makeWindowsIcon(join(opts.projectDir, opts.icon), join(opts.work, "exe-icon.ico"), {
+      onlyLargest: true,
+    });
+    if (ico) args.push("--set-icon", ico);
+  }
+  const fv = winFileVersion(opts.version);
+  args.push(
+    "--set-version-string", "ProductName", opts.appName,
+    "--set-version-string", "FileDescription", opts.appName,
+    "--set-version-string", "CompanyName", opts.publisher,
+    "--set-file-version", fv,
+    "--set-product-version", fv,
+  );
+  const res = await $`rcedit ${exe} ${args}`.nothrow();
+  if (res.exitCode !== 0) {
+    console.warn(`[mirin build] rcedit failed (exit ${res.exitCode}) — exe branding skipped.`);
+  }
+}
 
 export interface BuildResult {
   /** Path to the assembled .app. */
@@ -45,12 +122,25 @@ export interface BuildResult {
   dmg: boolean | import("mirinjs").DmgConfig;
   /** NSIS installer config (Windows) — `true`/object/`false`; default `true`. */
   nsis: boolean | import("mirinjs").NsisConfig;
+  /** Inno Setup installer config (Windows) — preferred over NSIS; default `true`. */
+  inno: boolean | import("mirinjs").InnoConfig;
+  /** Linux packaging config (`mirin.config.ts` `linux`) — `true`/object/`false`; default `true`. */
+  linux: boolean | import("mirinjs").LinuxConfig;
+  /** Publisher / company name (config.publisher ?? appName). */
+  publisher: string;
+  /** Absolute path to the app icon source (config.icon), if set — for Linux packaging. */
+  icon?: string;
   /** Codesign identity used for the bundle, if any (MIRIN_SIGN_IDENTITY). */
   signIdentity?: string;
 }
 
-/** Read the project's package.json version (the single source of app version). */
+/**
+ * The app version: `$MIRIN_APP_VERSION` (release-pipeline override) wins, otherwise
+ * the project's package.json `version` (the single source of truth).
+ */
 function appVersion(projectDir: string): string {
+  const override = process.env.MIRIN_APP_VERSION;
+  if (override) return override;
   const pkgPath = join(projectDir, "package.json");
   if (!existsSync(pkgPath)) return "0.0.0";
   try {
@@ -60,7 +150,19 @@ function appVersion(projectDir: string): string {
   }
 }
 
-export async function build(projectDir = process.cwd()): Promise<BuildResult> {
+export interface BuildOptions {
+  /** Override the app version (else `$MIRIN_APP_VERSION` / package.json). */
+  version?: string;
+  /** On Linux, also emit distributable packages (AppImage/deb/rpm) after assembling. */
+  packageLinux?: boolean;
+  /** Restrict Linux packaging to these formats (else config.linux.formats / all). */
+  linuxFormats?: import("mirinjs").LinuxPackageFormat[];
+}
+
+export async function build(
+  projectDir = process.cwd(),
+  opts: BuildOptions = {},
+): Promise<BuildResult> {
   const outDir = join(projectDir, "build");
   const work = join(projectDir, ".mirin");
   mkdirSync(outDir, { recursive: true });
@@ -71,11 +173,14 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
   const appName: string = config.name ?? "Mirin App";
   const bundleId: string = config.id ?? "dev.mirin.app";
   const mainEntry = join(projectDir, config.main ?? "main/main.ts");
-  const version = appVersion(projectDir);
+  const version = opts.version ?? appVersion(projectDir);
   const channel: string = config.release?.channel ?? "stable";
   const baseUrl: string | undefined = config.release?.baseUrl;
   const dmg: boolean | import("mirinjs").DmgConfig = config.dmg ?? true;
   const nsis: boolean | import("mirinjs").NsisConfig = config.nsis ?? true;
+  const inno: boolean | import("mirinjs").InnoConfig = config.inno ?? true;
+  const linux: boolean | import("mirinjs").LinuxConfig = config.linux ?? true;
+  const publisher: string = config.publisher ?? appName;
 
   console.log(`[mirin build] ${appName} ${version}`);
 
@@ -92,6 +197,17 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
   const hostExe = join(work, IS_WINDOWS ? "host-release.exe" : "host-release");
   const workerJs = join(work, "worker.release.js");
   await $`bun build --compile --minify ${artifacts.hostEntry} --outfile ${hostExe}`.cwd(projectDir);
+  if (IS_WINDOWS) {
+    patchPeToGuiSubsystem(hostExe);
+    await brandWindowsExe(hostExe, {
+      projectDir,
+      work,
+      appName,
+      version,
+      icon: config.icon,
+      publisher,
+    });
+  }
   await $`bun build ${mainEntry} --target=bun --minify --outfile ${workerJs}`.cwd(projectDir);
 
   // Extra assets: resolve sidecar binaries + compile any extra worker entries.
@@ -99,7 +215,8 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
   const extraWorkers = await compileWorkers(projectDir, config.workers, join(work, "workers"), true);
 
   // 5. assemble (+ sign on macOS)
-  console.log(`[mirin build] assembling ${IS_WINDOWS ? "app folder" : ".app"}…`);
+  const artifactKind = IS_WINDOWS ? "app folder" : IS_LINUX ? "app folder" : ".app";
+  console.log(`[mirin build] assembling ${artifactKind}…`);
   // version.json embeds the running app's update identity (read by app.updater).
   // Only when `release` is configured — otherwise the app has no updater.
   const versionJson = baseUrl
@@ -108,7 +225,11 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
   const resources = {
     uiDir: join(projectDir, "dist"),
     workerJs,
-    manifestJson: JSON.stringify({ windows: config.windows }),
+    manifestJson: JSON.stringify({
+      id: bundleId,
+      windows: config.windows,
+      singleInstance: config.singleInstance,
+    }),
     versionJson,
     workers: extraWorkers,
   };
@@ -123,6 +244,17 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
         icon: config.icon ? join(projectDir, config.icon) : undefined,
         resources: { ...resources, sidecars: sidecars.map((s) => ({ name: s.name, src: s.src })) },
       })
+    : IS_LINUX
+    ? await buildLinuxBundle({
+        appName,
+        outDir,
+        hostExe,
+        coreDll: artifacts.coreDylib,
+        helperExe: artifacts.helperBin,
+        cefPath: artifacts.cefPath,
+        icon: config.icon ? join(projectDir, config.icon) : undefined,
+        resources: { ...resources, sidecars: sidecars.map((s) => ({ name: s.name, src: s.src })) },
+      })
     : await buildAppBundle({
         appName,
         bundleId,
@@ -139,6 +271,29 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
       });
 
   console.log(`\n[mirin build] done → ${app}`);
+
+  // Linux: optionally emit distributable packages (AppImage/deb/rpm) straight from
+  // `mirin build`. `mirin release` does its own packaging into build/release, so it
+  // never sets `packageLinux` — this path only runs for a direct build request.
+  if (IS_LINUX && opts.packageLinux && linux !== false) {
+    const formats = resolveLinuxFormats(linux, opts.linuxFormats);
+    console.log(`[mirin build] packaging Linux artifacts (${formats.join(", ")})…`);
+    const pkgs = await buildLinuxPackages({
+      appDir: app,
+      appName,
+      bundleId,
+      version,
+      publisher,
+      outDir,
+      projectDir,
+      icon: config.icon ? join(projectDir, config.icon) : undefined,
+      options: typeof linux === "object" ? linux : {},
+      formats,
+    });
+    const mb = (n: number) => (n / 1e6).toFixed(1);
+    for (const p of pkgs) console.log(`  ${p.path} (${mb(p.size)} MB)`);
+  }
+
   return {
     app,
     appName,
@@ -150,6 +305,10 @@ export async function build(projectDir = process.cwd()): Promise<BuildResult> {
     projectDir,
     dmg,
     nsis,
+    inno,
+    linux,
+    publisher,
+    icon: config.icon ? join(projectDir, config.icon) : undefined,
     signIdentity,
   };
 }

package/src/bundle-linux.ts

@@ -0,0 +1,234 @@
+/**
+ * Assemble a Linux app folder for a mirin app. Like Windows, Linux has no `.app`
+ * bundle — just a flat directory the dynamic loader can resolve libcef.so + the
+ * CEF runtime from, next to the host binary:
+ *
+ *   <App>/
+ *     <App>                    compiled Bun host (process.execPath)
+ *     libmirin_core.so         loaded by the host via bun:ffi
+ *     mirin-helper             CEF subprocess (browser_subprocess_path)
+ *     libcef.so, libEGL.so, libGLESv2.so, *.pak, icudtl.dat,
+ *     v8_context_snapshot.bin, locales/, chrome-sandbox, …  (CEF runtime)
+ *     resources/               (production only — dev serves from the Vite URL)
+ *       ui/, worker.js, mirin.manifest.json, version.json, sidecars/, workers/
+ *
+ * Wayland-only (docs/linux-port.md); the CEF subprocess name (`mirin-helper`) and
+ * the `resources/` layout match what mirin-core derives at runtime
+ * (engine::derive_subprocess_path, host.ts). libcef.so is resolved via
+ * LD_LIBRARY_PATH set on the host (dev.ts) or an rpath at build time.
+ */
+
+import { cpSync, mkdirSync, rmSync, writeFileSync, existsSync, readdirSync, chmodSync, statSync } from "node:fs";
+import { join, extname, basename } from "node:path";
+
+/** Source dir (vendor/cef on Linux) must contain libcef.so. */
+const CEF_MARKER = "libcef.so";
+
+/** CEF runtime files copied next to the host binary. Everything else in the Linux
+ *  distribution (include/, cmake/, CMakeLists.txt, archive.json, libcef_dll/) is
+ *  build-time only and intentionally left out. `.so` covers libcef/libEGL/
+ *  libGLESv2/libvk_swiftshader; the extras list catches the non-extension names. */
+const CEF_RUNTIME_EXTS = new Set([".so", ".bin", ".pak", ".dat"]);
+const CEF_RUNTIME_EXTRAS = ["locales", "vk_swiftshader_icd.json", "libvulkan.so.1", "chrome-sandbox"];
+
+export interface LinuxBundleOptions {
+  appName: string; // also the host binary stem → <appName>
+  outDir: string;
+  hostExe: string; // compiled Bun host (no extension)
+  coreDll: string; // libmirin_core.so
+  helperExe: string; // mirin-helper
+  cefPath: string; // dir containing the Linux CEF runtime (vendor/cef)
+  /** App icon source (.png / .iconset); resolved to a PNG at resources/icon.png for
+   *  the window's `_NET_WM_ICON` (taskbar/dock). */
+  icon?: string;
+  /** Production-only resources placed under <App>/resources. */
+  resources?: {
+    uiDir?: string; // Vite dist/ → resources/ui (served via app://ui)
+    workerJs?: string; // bundled main-process Worker → resources/worker.js
+    manifestJson?: string; // serialized manifest → resources/mirin.manifest.json
+    versionJson?: string; // serialized version.json → resources/version.json (updater)
+    sidecars?: { name: string; src: string }[]; // → resources/sidecars/<name>
+    workers?: Record<string, string>; // name → abs path → resources/workers/<name>.js
+  };
+}
+
+/**
+ * Resolve the app config's `icon` to a concrete square PNG usable on Linux (for
+ * the window's `_NET_WM_ICON`). Accepts a `.png` (used as-is) or a `.iconset`
+ * directory (pick a good mid/large size). Returns undefined for `.icns` (which the
+ * Linux core can't decode) or a missing/empty source.
+ *
+ * @param icon absolute path to the icon source (`config.icon` joined with the project root).
+ */
+export function resolveLinuxIconPng(icon: string): string | undefined {
+  if (!existsSync(icon)) return undefined;
+  if (statSync(icon).isDirectory()) {
+    const pngs = readdirSync(icon).filter((f) => extname(f).toLowerCase() === ".png");
+    if (!pngs.length) return undefined;
+    // Prefer 128×128: crisp in the dock, and small enough that its `_NET_WM_ICON`
+    // (a 128²+2 CARDINAL array ≈ 64 KB) stays under X11's ~256 KB max request size —
+    // a 256×256 icon (≈ 256 KB) can exceed it and get dropped. Fall back to the
+    // largest available under that ceiling (by pixels parsed from the iconset name).
+    const preferred = ["icon_128x128.png", "icon_64x64.png", "icon_256x256.png"];
+    const MAX_SIDE = 128;
+    const pick =
+      preferred.find((p) => pngs.includes(p)) ??
+      pngs
+        .slice()
+        .sort((a, b) => iconsetPixels(b) - iconsetPixels(a))
+        .find((p) => iconsetPixels(p) <= MAX_SIDE * MAX_SIDE) ??
+      pngs.sort((a, b) => iconsetPixels(a) - iconsetPixels(b))[0];
+    return pick ? join(icon, pick) : undefined;
+  }
+  return extname(icon).toLowerCase() === ".png" ? icon : undefined;
+}
+
+/**
+ * Resolve the app config's `icon` to the *largest* concrete PNG (for a `.desktop`
+ * `Icon=`, which is a file path with no X11 request-size limit — so we want it
+ * crisp, unlike the window `_NET_WM_ICON`). `.png` used as-is; `.iconset` → biggest
+ * PNG inside. Undefined for `.icns` or a missing source.
+ */
+export function resolveLinuxDesktopIconPng(icon: string): string | undefined {
+  if (!existsSync(icon)) return undefined;
+  if (statSync(icon).isDirectory()) {
+    const pngs = readdirSync(icon).filter((f) => extname(f).toLowerCase() === ".png");
+    if (!pngs.length) return undefined;
+    const biggest = pngs.sort((a, b) => iconsetPixels(b) - iconsetPixels(a))[0];
+    return biggest ? join(icon, biggest) : undefined;
+  }
+  return extname(icon).toLowerCase() === ".png" ? icon : undefined;
+}
+
+/**
+ * A freedesktop `.desktop` entry body for a mirin app. cosmic's dock resolves an
+ * X11 window's icon by matching its `WM_CLASS` (which the core sets to the app id)
+ * against a desktop entry's `StartupWMClass`, then uses that entry's `Icon` — the
+ * reliable path on cosmic (its `_NET_WM_ICON` fallback is unreliable). `wmClass`
+ * MUST equal the core's `res_class` (the bundle id).
+ */
+export function desktopEntry(opts: {
+  name: string;
+  exec: string;
+  iconPng: string;
+  wmClass: string;
+  /** Freedesktop main category (e.g. "Utility", "Development"). A trailing `;` is
+   *  added if missing (the spec requires list values to end with one). Omitted → no
+   *  Categories line. Used by the .deb/.rpm/AppImage entries (dev needs none). */
+  categories?: string;
+  /** Optional Comment= (tooltip / description) line. */
+  comment?: string;
+}): string {
+  const lines = ["[Desktop Entry]", "Type=Application", `Name=${opts.name}`];
+  if (opts.comment) lines.push(`Comment=${opts.comment}`);
+  lines.push(
+    `Exec=${opts.exec}`,
+    `Icon=${opts.iconPng}`,
+    `StartupWMClass=${opts.wmClass}`,
+    "Terminal=false",
+  );
+  if (opts.categories) {
+    lines.push(`Categories=${opts.categories.endsWith(";") ? opts.categories : `${opts.categories};`}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/** Effective pixel count encoded in an iconset filename (`icon_256x256@2x.png` → 512²). */
+function iconsetPixels(name: string): number {
+  const m = basename(name).match(/(\d+)x(\d+)(@(\d+)x)?/);
+  if (!m) return 0;
+  const scale = m[4] ? Number(m[4]) : 1;
+  return Number(m[1]) * Number(m[2]) * scale * scale;
+}
+
+/** Build the Linux app folder and return its path + the host binary to launch. */
+export async function buildLinuxBundle(
+  opts: LinuxBundleOptions,
+): Promise<{ app: string; exe: string }> {
+  const { appName, cefPath } = opts;
+  if (!existsSync(join(cefPath, CEF_MARKER))) {
+    throw new Error(`CEF runtime not found at ${cefPath} — run: bun scripts/fetch-cef.ts`);
+  }
+
+  const app = join(opts.outDir, appName);
+  rmSync(app, { recursive: true, force: true });
+  mkdirSync(app, { recursive: true });
+
+  const exe = join(app, appName);
+  cpSync(opts.hostExe, exe);
+  chmodSync(exe, 0o755);
+  cpSync(opts.coreDll, join(app, "libmirin_core.so"));
+  const helper = join(app, "mirin-helper");
+  cpSync(opts.helperExe, helper);
+  chmodSync(helper, 0o755);
+
+  copyCefRuntime(cefPath, app);
+
+  // The window taskbar/dock icon (`_NET_WM_ICON`) is set by the core from a PNG at
+  // `resources/icon.png`; host.ts points the init config's `icon_path` there in prod.
+  // (Dev serves it directly from the project via MIRIN_CONFIG_JSON, not the bundle.)
+  const iconPng = opts.icon ? resolveLinuxIconPng(opts.icon) : undefined;
+  if (iconPng) {
+    const res = join(app, "resources");
+    mkdirSync(res, { recursive: true });
+    cpSync(iconPng, join(res, "icon.png"));
+  }
+
+  // Production resources (dev passes none — paths come from env + the Vite URL).
+  if (opts.resources) {
+    const res = join(app, "resources");
+    mkdirSync(res, { recursive: true });
+    if (opts.resources.uiDir) cpSync(opts.resources.uiDir, join(res, "ui"), { recursive: true });
+    if (opts.resources.workerJs) cpSync(opts.resources.workerJs, join(res, "worker.js"));
+    if (opts.resources.manifestJson != null) {
+      writeFileSync(join(res, "mirin.manifest.json"), opts.resources.manifestJson);
+    }
+    if (opts.resources.versionJson != null) {
+      writeFileSync(join(res, "version.json"), opts.resources.versionJson);
+    }
+    if (opts.resources.workers && Object.keys(opts.resources.workers).length) {
+      const workersDir = join(res, "workers");
+      mkdirSync(workersDir, { recursive: true });
+      for (const [name, src] of Object.entries(opts.resources.workers)) {
+        cpSync(src, join(workersDir, `${name}.js`));
+      }
+    }
+    if (opts.resources.sidecars?.length) {
+      const sidecarsDir = join(res, "sidecars");
+      mkdirSync(sidecarsDir, { recursive: true });
+      for (const sc of opts.resources.sidecars) {
+        if (!existsSync(sc.src)) throw new Error(`sidecar "${sc.name}" not found: ${sc.src}`);
+        const dst = join(sidecarsDir, sc.name);
+        cpSync(sc.src, dst);
+        chmodSync(dst, 0o755);
+      }
+    }
+  }
+
+  return { app, exe };
+}
+
+/** Copy the CEF runtime (shared libs, paks, snapshot, icu data, locales) into `dest`. */
+function copyCefRuntime(cefPath: string, dest: string): void {
+  for (const entry of readdirSync(cefPath)) {
+    if (CEF_RUNTIME_EXTS.has(extname(entry).toLowerCase())) {
+      cpSync(join(cefPath, entry), join(dest, entry));
+    }
+  }
+  for (const extra of CEF_RUNTIME_EXTRAS) {
+    const src = join(cefPath, extra);
+    if (existsSync(src)) cpSync(src, join(dest, extra), { recursive: true });
+  }
+  // chrome-sandbox works setuid-root (mode 4755) or, on kernels with unprivileged
+  // user namespaces, via the namespace sandbox with no special perms. We can't
+  // setuid without root here; leave it executable and let CEF pick the userns path.
+  const sandbox = join(dest, "chrome-sandbox");
+  if (existsSync(sandbox)) {
+    try {
+      require("node:fs").chmodSync(sandbox, 0o755);
+    } catch {
+      /* best-effort */
+    }
+  }
+}