sparkbun 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sparkbun",
-	"version": "0.2.6",
+	"version": "0.2.8",
 	"description": "Build fast, lightweight, cross-platform desktop apps with TypeScript and Bun.",
 	"license": "MIT",
 	"author": "SparkBun Contributors",

package/src/bun/SparkBunConfig.ts

@@ -167,6 +167,12 @@ export interface SparkBunConfig {
 				 * Source directory (relative to project root or absolute). The
 				 * directory's own name becomes the archive's top-level folder,
 				 * so it extracts into the correct subdirectory.
+				 *
+				 * May also point at a PREBUILT `.tar` / `.tar.gz` / `.tar.zst`
+				 * file, which is embedded verbatim (no per-build tar+compress —
+				 * useful when a large payload is slow to compress and rarely
+				 * changes). Format is taken from the extension; `format`/
+				 * `compression` are ignored for prebuilt archives.
 				 */
 				path: string;
 				/**
@@ -177,9 +183,23 @@ export interface SparkBunConfig {
 				 */
 				format?: "zstd" | "gzip";
 				/**
-				 * Compression level. zstd: 1–22 (22 = maximum, large window).
-				 * gzip: 1–9. Higher is smaller but slower to compress.
-				 * @default 19 for zstd, 9 for gzip
+				 * Compression tier.
+				 * - "basic" — Bun's built-in CompressionStream (zstd ≈ level 3,
+				 *   gzip ≈ level 6). Fast, streaming, no level control. (default)
+				 * - number — explicit level via node:zlib streaming transforms.
+				 *   zstd: 1–22 (22 = maximum; large window, smallest output).
+				 *   gzip: 1–9. Higher is smaller but slower to compress.
+				 * - "none" — no compression; a plain `.tar`. For payloads that
+				 *   are already compressed (video, media) where recompression
+				 *   wastes build time. The manifest records format "none" and
+				 *   the app's extractor must skip its decompression step.
+				 * @default "basic"
+				 */
+				compression?: "none" | "basic" | number;
+				/**
+				 * Legacy alias for a numeric `compression` tier. Ignored when
+				 * `compression` is set.
+				 * @deprecated Use `compression` instead.
 				 */
 				level?: number;
 			}>;

package/src/bun/core/Updater.ts

@@ -922,17 +922,16 @@ if %rmRetry% GEQ 10 goto rmfailed
 timeout /t 2 /nobreak >nul
 goto rmloop
 :rmfailed
-echo Update failed: could not remove "${runningAppWin}" after retries.
-echo Files may still be locked by a helper process.
-pause
+:: The script runs in a hidden window, so log instead of echo/pause (a hidden
+:: pause would hang invisibly forever).
+echo Update failed: could not remove "${runningAppWin}" after retries. Files may still be locked by a helper process. >> "%~dp0update-error.log"
 exit /b 1
 :rmdone
 
 :: Move new app to current location (safe now that destination is gone)
 move "${newAppWin}" "${runningAppWin}"
 if not exist "${launcherPathWin}" (
-    echo Update failed: launcher not found at "${launcherPathWin}" after move.
-    pause
+    echo Update failed: launcher not found at "${launcherPathWin}" after move. >> "%~dp0update-error.log"
     exit /b 1
 )
 
@@ -947,24 +946,40 @@ for /f "tokens=1" %%t in ('schtasks /query /fo list ^| findstr /i "SparkBunUpdat
     schtasks /delete /tn "%%t" /f >nul 2>&1
 )
 
-:: Delete this update script after a short delay
+:: Delete this update script (and its hidden-window launcher) after a short delay
 ping -n 2 127.0.0.1 >nul
+del "%~dp0update.vbs" 2>nul
 del "%~f0"
 `;
 
 						await Bun.write(updateScriptPath, updateScript);
 
+						// VBS shim so the batch script runs with a HIDDEN window (style 0).
+						// schtasks can't hide a console app's window itself, and without
+						// this the whole update — wait loop included — sits in a visible
+						// cmd window. wscript.exe is a GUI-subsystem host, so nothing
+						// flashes. Errors are logged to update-error.log by the bat.
+						const scriptPathWin = updateScriptPath.replace(/\//g, "\\");
+						const vbsPath = join(parentDir, "update.vbs");
+						const vbsPathWin = vbsPath.replace(/\//g, "\\");
+						await Bun.write(
+							vbsPath,
+							`CreateObject("WScript.Shell").Run "cmd /c ""${scriptPathWin}""", 0, False\r\n`,
+						);
+
 						// Use Windows Task Scheduler to run the update script independently
 						// This ensures the script runs even after the app exits
-						const scriptPathWin = updateScriptPath.replace(/\//g, "\\");
 						const taskName = `SparkBunUpdate_${Date.now()}`;
 
-						// Create a scheduled task that runs immediately and deletes itself
+						// Create a scheduled task that runs immediately and deletes itself.
+						// windowsHide stops the schtasks invocations themselves from
+						// flashing console windows (the app is a GUI-subsystem process,
+						// so each unhidden child would allocate a fresh visible console).
 						execSync(
-							`schtasks /create /tn "${taskName}" /tr "cmd /c \\"${scriptPathWin}\\"" /sc once /st 00:00 /f`,
-							{ stdio: "ignore" },
+							`schtasks /create /tn "${taskName}" /tr "wscript.exe //B \\"${vbsPathWin}\\"" /sc once /st 00:00 /f`,
+							{ stdio: "ignore", windowsHide: true },
 						);
-						execSync(`schtasks /run /tn "${taskName}"`, { stdio: "ignore" });
+						execSync(`schtasks /run /tn "${taskName}"`, { stdio: "ignore", windowsHide: true });
 						// The task will be cleaned up by Windows after it runs, or we delete it in the batch script
 
 						// Use quit() for graceful shutdown - this closes all windows and processes

package/src/cli/archive-stream.ts

@@ -0,0 +1,292 @@
+/**
+ * Streaming, pure-Bun tar + compression for installer payload archives.
+ *
+ * The tar layer is hand-rolled ustar, emitted entry-by-entry with file bodies
+ * read in 8 MiB slices, so build memory stays bounded regardless of payload
+ * size — and there is no system `tar` dependency. (Shelling out to tar was a
+ * reliability problem: macOS bsdtar emits xattr pax headers that GNU tar
+ * rejects, and GNU tar parses "C:\..." as a remote-host spec.) The output is
+ * plain ustar — long paths via the name/prefix split, file modes preserved
+ * (executables stay executable), symlinks as typeflag '2' — readable by every
+ * tar implementation and by apps' streaming extractors.
+ *
+ * Compression tiers, chosen per archive (config `compression` field or
+ * `--compression` flag):
+ *   - "basic"  — Bun's built-in CompressionStream (zstd default ≈ level 3;
+ *                gzip default ≈ level 6). Fast, streaming, no level control.
+ *                The default tier.
+ *   - <number> — explicit level via node:zlib streaming transforms (zstd 1–22,
+ *                gzip 1–9). zstd 22 uses a large window; its ratio depends on
+ *                it. Slower to build, smallest output.
+ *   - "none"   — no compression; a plain `.tar`. For payloads that are already
+ *                compressed (video, archives) where recompression wastes time.
+ */
+
+import { readdirSync, statSync, lstatSync, readlinkSync, createWriteStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import zlib from "node:zlib";
+import { join, basename } from "node:path";
+
+export type ArchiveFormat = "zstd" | "gzip";
+export type ArchiveCompression = "none" | "basic" | number;
+
+const READ_CHUNK = 8 * 1024 * 1024; // file read slice size (bounds memory)
+
+/** File extension for an archive of the given format + compression. */
+export function archiveExtension(format: ArchiveFormat, compression: ArchiveCompression): string {
+	if (compression === "none") return "tar";
+	return format === "gzip" ? "tar.gz" : "tar.zst";
+}
+
+/**
+ * The effective numeric level recorded in the manifest: 0 for "none", the
+ * library default for "basic" (zstd 3 / gzip 6 — approximate; CompressionStream
+ * exposes no level), or the explicit number.
+ */
+export function effectiveLevel(format: ArchiveFormat, compression: ArchiveCompression): number {
+	if (compression === "none") return 0;
+	if (compression === "basic") return format === "gzip" ? 6 : 3;
+	return compression;
+}
+
+/** Human label for build logs, e.g. "zstd level 22", "zstd (basic)", "uncompressed". */
+export function compressionLabel(format: ArchiveFormat, compression: ArchiveCompression): string {
+	if (compression === "none") return "uncompressed";
+	if (compression === "basic") return `${format} (basic)`;
+	return `${format} level ${compression}`;
+}
+
+/** A POSIX ustar 512-byte header. Splits long paths across name/prefix. */
+function ustarHeader(
+	path: string,
+	size: number,
+	type: "0" | "2" | "5",
+	mode: number,
+	linkname = "",
+): Uint8Array {
+	const bl = (s: string) => Buffer.byteLength(s);
+	let name = path;
+	let prefix = "";
+	if (bl(name) > 100) {
+		// Split at a "/" so the suffix fits the 100-byte name field and the
+		// prefix fits the 155-byte prefix field (extractors rejoin them).
+		let split = -1;
+		for (let i = 0; i < path.length; i++) {
+			if (path[i] !== "/") continue;
+			if (bl(path.slice(0, i)) <= 155 && bl(path.slice(i + 1)) <= 100) {
+				split = i;
+				break;
+			}
+		}
+		if (split < 0) throw new Error(`Path too long for ustar: ${path}`);
+		prefix = path.slice(0, split);
+		name = path.slice(split + 1);
+	}
+	if (bl(linkname) > 100) throw new Error(`Symlink target too long for ustar: ${linkname}`);
+	const h = Buffer.alloc(512);
+	h.write(name, 0);
+	const putOct = (off: number, len: number, v: number) =>
+		h.write(v.toString(8).padStart(len - 1, "0") + "\0", off);
+	putOct(100, 8, mode & 0o7777);
+	putOct(108, 8, 0); // uid
+	putOct(116, 8, 0); // gid
+	putOct(124, 12, size);
+	putOct(136, 12, 0); // mtime
+	h.write(type, 156);
+	h.write(linkname, 157);
+	h.write("ustar\0", 257);
+	h.write("00", 263);
+	h.write(prefix, 345);
+	h.fill(0x20, 148, 156); // checksum field = spaces while summing
+	let sum = 0;
+	for (let i = 0; i < 512; i++) sum += h[i]!;
+	h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148);
+	return new Uint8Array(h.buffer, h.byteOffset, h.length);
+}
+
+type WalkEntry = {
+	abs: string;
+	rel: string;
+	kind: "dir" | "file" | "symlink";
+	size: number;
+	mode: number;
+};
+
+/** Depth-first walk; directories before their contents; "/" separators. */
+function* walk(absDir: string, rel: string): Generator<WalkEntry> {
+	const entries = readdirSync(absDir, { withFileTypes: true }).sort((x, y) =>
+		x.name.localeCompare(y.name),
+	);
+	for (const e of entries) {
+		if (e.name === ".DS_Store") continue;
+		const abs = join(absDir, e.name);
+		const r = `${rel}/${e.name}`;
+		if (e.isSymbolicLink()) {
+			yield { abs, rel: r, kind: "symlink", size: 0, mode: 0o777 };
+		} else if (e.isDirectory()) {
+			yield { abs, rel: r, kind: "dir", size: 0, mode: lstatSync(abs).mode };
+			yield* walk(abs, r);
+		} else if (e.isFile()) {
+			const st = statSync(abs);
+			yield { abs, rel: r, kind: "file", size: st.size, mode: st.mode };
+		}
+		// Sockets/FIFOs/devices are skipped.
+	}
+}
+
+/**
+ * The tar bytes for the tree rooted at `srcDir`, as a lazy async sequence.
+ * The directory's own name becomes the archive root.
+ */
+export async function* tarBytes(srcDir: string): AsyncGenerator<Uint8Array> {
+	const rootName = basename(srcDir);
+	yield ustarHeader(`${rootName}/`, 0, "5", statSync(srcDir).mode);
+	for (const e of walk(srcDir, rootName)) {
+		if (e.kind === "dir") {
+			yield ustarHeader(`${e.rel}/`, 0, "5", e.mode);
+			continue;
+		}
+		if (e.kind === "symlink") {
+			yield ustarHeader(e.rel, 0, "2", e.mode, readlinkSync(e.abs));
+			continue;
+		}
+		yield ustarHeader(e.rel, e.size, "0", e.mode);
+		const f = Bun.file(e.abs);
+		for (let off = 0; off < e.size; off += READ_CHUNK) {
+			yield new Uint8Array(await f.slice(off, Math.min(off + READ_CHUNK, e.size)).arrayBuffer());
+		}
+		const pad = (512 - (e.size % 512)) % 512;
+		if (pad) yield new Uint8Array(pad);
+	}
+	yield new Uint8Array(1024); // end-of-archive: two zero blocks
+}
+
+/**
+ * Scan a prebuilt tar archive (optionally zstd/gzip compressed) and total its
+ * file payload — the uncompressedBytes/fileCount progress denominators the
+ * manifest needs. Streaming: headers are parsed and bodies skipped, so memory
+ * stays bounded.
+ */
+export async function scanTarArchive(
+	path: string,
+	format: ArchiveFormat | "none",
+): Promise<{ uncompressedBytes: number; fileCount: number }> {
+	let stream = Bun.file(path).stream() as unknown as ReadableStream<Uint8Array>;
+	if (format !== "none") {
+		const ds = new DecompressionStream(
+			(format === "gzip" ? "gzip" : "zstd") as CompressionFormat,
+		) as unknown as ReadableWritablePair<Uint8Array, Uint8Array>;
+		stream = stream.pipeThrough(ds);
+	}
+	const reader = stream.getReader();
+	const td = new TextDecoder();
+	let buf: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+	let uncompressedBytes = 0;
+	let fileCount = 0;
+	let skip = 0; // bytes of body+padding left to discard
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (buf.length === 0) buf = value;
+		else {
+			const merged = new Uint8Array(buf.length + value.length);
+			merged.set(buf, 0);
+			merged.set(value, buf.length);
+			buf = merged;
+		}
+		while (true) {
+			if (skip > 0) {
+				const n = Math.min(skip, buf.length);
+				buf = buf.subarray(n);
+				skip -= n;
+				if (skip > 0) break;
+			}
+			if (buf.length < 512) break;
+			const h = buf.subarray(0, 512);
+			buf = buf.subarray(512);
+			let allZero = true;
+			for (let i = 0; i < 512; i++) {
+				if (h[i] !== 0) { allZero = false; break; }
+			}
+			if (allZero) continue; // end-of-archive marker block
+			const size =
+				parseInt(td.decode(h.subarray(124, 136)).replace(/\0.*$/, "").trim() || "0", 8) || 0;
+			const typeflag = String.fromCharCode(h[156] || 0);
+			// Regular files count toward the payload; metadata entries (long-name
+			// 'L'/'K', pax 'x'/'g') and dirs/links don't, but their bodies are
+			// still skipped.
+			if (typeflag === "0" || typeflag === "\0") {
+				uncompressedBytes += size;
+				fileCount++;
+			}
+			skip = size + ((512 - (size % 512)) % 512);
+		}
+	}
+	return { uncompressedBytes, fileCount };
+}
+
+/** Wrap an async generator as a web ReadableStream (for CompressionStream). */
+function toReadable(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
+	return new ReadableStream<Uint8Array>({
+		async pull(c) {
+			const { done, value } = await gen.next();
+			if (done) c.close();
+			else c.enqueue(value);
+		},
+	});
+}
+
+/**
+ * Tar `srcDir` and write it to `destPath`, compressed per the tier. Streaming
+ * end to end: nothing close to the payload size is ever in memory.
+ */
+export async function writeTarArchive(
+	srcDir: string,
+	destPath: string,
+	format: ArchiveFormat,
+	compression: ArchiveCompression,
+): Promise<void> {
+	const tar = tarBytes(srcDir);
+
+	if (compression === "none") {
+		await pipeline(tar, createWriteStream(destPath));
+		return;
+	}
+
+	if (compression === "basic") {
+		// Bun's built-in CompressionStream. "zstd" is valid in Bun but missing
+		// from the lib.dom CompressionFormat union (and the stream generics
+		// predate Uint8Array<ArrayBuffer>), hence the casts.
+		const cs = new CompressionStream(
+			(format === "gzip" ? "gzip" : "zstd") as CompressionFormat,
+		) as unknown as ReadableWritablePair<Uint8Array, Uint8Array>;
+		const compressed = toReadable(tar).pipeThrough(cs);
+		const sink = Bun.file(destPath).writer();
+		const reader = compressed.getReader();
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				sink.write(value);
+			}
+		} finally {
+			await sink.end();
+		}
+		return;
+	}
+
+	// Explicit level via node:zlib streaming transforms. The zstd APIs exist in
+	// Bun's node:zlib but not yet in the bundled @types, hence the cast.
+	const z = zlib as unknown as {
+		createGzip(opts: { level: number }): NodeJS.ReadWriteStream;
+		createZstdCompress(opts: { params: Record<number, number> }): NodeJS.ReadWriteStream;
+		constants: { ZSTD_c_compressionLevel: number };
+	};
+	const transform =
+		format === "gzip"
+			? z.createGzip({ level: compression })
+			: z.createZstdCompress({
+					params: { [z.constants.ZSTD_c_compressionLevel]: compression },
+				});
+	await pipeline(tar, transform, createWriteStream(destPath));
+}

package/src/cli/index.ts

@@ -33,6 +33,15 @@ import {
 	getMacOSBundleDisplayName,
 } from "../shared/naming";
 import { getTemplate, getTemplateNames } from "./templates/embedded";
+import {
+	writeTarArchive,
+	scanTarArchive,
+	archiveExtension,
+	effectiveLevel,
+	compressionLabel,
+	type ArchiveFormat,
+	type ArchiveCompression,
+} from "./archive-stream";
 // MacOS named pipes hang at around 4KB
 // @ts-expect-error - reserved for future use
 const _MAX_CHUNK_SIZE = 1024 * 2;
@@ -64,6 +73,38 @@ function createTar(tarPath: string, cwd: string, entries: string[]) {
 	);
 }
 
+// Compile an executable via Bun.build({ compile }) with a retry around a known
+// transient failure: on Windows the compile stamps PE version metadata through
+// resource updates (EndUpdateResourceW), and antivirus/indexer scans of the
+// freshly written exe intermittently fail that commit with "Failed to set
+// Windows metadata: FailedToCommit". Clear any stale output first (a scanned
+// leftover exe can hold locks), then retry a few times before giving up.
+async function buildCompiledExeWithRetry(
+	options: Parameters<typeof Bun.build>[0],
+	outputPath: string,
+): Promise<Awaited<ReturnType<typeof Bun.build>>> {
+	try { rmSync(outputPath, { force: true }); } catch {}
+	for (let attempt = 1; ; attempt++) {
+		try {
+			return await Bun.build(options);
+		} catch (err: any) {
+			// Bun surfaces compile errors as BuildMessage-like objects whose
+			// .message can be empty — the text only shows through Bun's inspect
+			// formatting, so match against every representation we can get.
+			let msg = "";
+			try {
+				msg = `${err?.message ?? ""} ${String(err)} ${Bun.inspect(err)}`;
+			} catch {}
+			if (attempt < 4 && /FailedToCommit|Failed to set Windows metadata/i.test(msg)) {
+				console.log(`  PE metadata commit failed (attempt ${attempt}/4) — retrying in 2s...`);
+				await Bun.sleep(2000);
+				continue;
+			}
+			throw err;
+		}
+	}
+}
+
 // Recursively measure a directory's total file bytes and file count.
 // Used to embed accurate progress denominators in the installer archive manifest.
 function measureDir(dir: string): { bytes: number; fileCount: number } {
@@ -84,28 +125,6 @@ function measureDir(dir: string): { bytes: number; fileCount: number } {
 	return { bytes, fileCount };
 }
 
-// Stream-compress a file with zstd or gzip at a specific level, using node:zlib
-// transforms so build memory stays bounded regardless of input size. Web
-// CompressionStream("zstd") is intentionally not used — it has no level control,
-// and the high compression ratio depends on level 22's large window.
-async function streamCompressFile(
-	srcPath: string,
-	destPath: string,
-	format: "zstd" | "gzip",
-	level: number,
-): Promise<void> {
-	const zlib = require("node:zlib");
-	const { createReadStream, createWriteStream } = require("node:fs");
-	const { pipeline } = require("node:stream/promises");
-	const transform =
-		format === "gzip"
-			? zlib.createGzip({ level })
-			: zlib.createZstdCompress({
-					params: { [zlib.constants.ZSTD_c_compressionLevel]: level },
-				});
-	await pipeline(createReadStream(srcPath), transform, createWriteStream(destPath));
-}
-
 // this when run as an npm script this will be where the folder where package.json is.
 const projectRoot = process.cwd();
 
@@ -1313,6 +1332,30 @@ function escapeXml(str: string): string {
 		.replace(/'/g, "&apos;");
 }
 
+/**
+ * Flip the PE subsystem from CONSOLE (3) to WINDOWS GUI (2) so the exe never
+ * opens a console window. Byte-identical to `editbin /SUBSYSTEM:WINDOWS`.
+ *
+ * This exists because Bun's `compile.windows.hideConsole` is a silent no-op:
+ * the only code that applies it sits after a switch in which every prong
+ * returns early (oven-sh/bun#19916; fix PR oven-sh/bun#20338 unmerged as of
+ * Bun 1.3.14). Bun's intended implementation writes the exact same byte at the
+ * exact same offset, so when upstream merges the fix, `hideConsole: true`
+ * takes over and this patch degrades to a no-op (the `current !== 2` check).
+ *
+ * Unlike Bun's flag, this also works when cross-compiling from macOS/Linux
+ * (Bun only applies windows options when the build host is Windows).
+ *
+ * Must run AFTER all other PE edits (payload injection, rescle metadata) and
+ * BEFORE any future code signing — mutating a signed exe invalidates the
+ * signature.
+ *
+ * Historical note: a May 2026 commit (cf58be7) blamed hideConsole for breaking
+ * the ShellExecuteW("runas") elevation flow. Since hideConsole never touched
+ * the binary, that breakage came from elsewhere (likely the experimental
+ * signature-stripping variant of this function that was being tested at the
+ * same time and was reverted in the same commit).
+ */
 function patchPeSubsystem(exePath: string): void {
 	const buf = readFileSync(exePath);
 	const peOffset = buf.readUInt32LE(0x3c);
@@ -2144,8 +2187,9 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 		if (targetOS === "win") {
 			if (OS !== "win") {
 				console.warn(
-					`\n⚠️  Cross-compiling for Windows: icon, hideConsole, and PE metadata (title, version, publisher, etc.) will be ignored.\n` +
+					`\n⚠️  Cross-compiling for Windows: icon and PE metadata (title, version, publisher, etc.) will be ignored.\n` +
 					`   Bun's Windows-specific compile options require building on a Windows host.\n` +
+					`   (The console window is still hidden — the PE subsystem patch runs on any host.)\n` +
 					`   See: https://bun.com/docs/bundler/executables#windows-specific-flags\n`
 				);
 			} else {
@@ -3177,6 +3221,8 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 						hash,
 						config,
 						projectRoot,
+						targetOS,
+						currentTarget.arch,
 					);
 					artifactsToUpload.push(installerPath);
 				}
@@ -3199,8 +3245,10 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 				// the download button or display on your marketing site or in the app.
 				version: config.app.version,
 				hash: hash.toString(),
-				platform: OS,
-				arch: ARCH,
+				// The TARGET platform of these artifacts (host != target when
+				// cross-compiling, e.g. --target=win-x64 on macOS).
+				platform: targetOS,
+				arch: currentTarget.arch,
 				// channel: buildEnvironment,
 				// baseUrl: config.release.baseUrl
 			});
@@ -3284,24 +3332,53 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 
 		// Compression defaults for archives supplied via --archive flags.
 		// (Archives declared in sparkbun.config.ts carry their own per-archive
-		// format/level, so each project can mix tight and fast compression.)
-		const globalFormat = ((getFlag("--format=") as "zstd" | "gzip") || "zstd");
+		// format/compression, so each project can mix tight and fast compression.)
+		const globalFormat = ((getFlag("--format=") as ArchiveFormat) || "zstd");
 		const globalLevelFlag = getFlag("--level=");
-		const defaultLevelFor = (fmt: "zstd" | "gzip") => (fmt === "gzip" ? 9 : 19);
+		const globalCompressionFlag = getFlag("--compression=");
+
+		// Parse a compression tier: "none" | "basic" | numeric level. Validates
+		// the level range for the format (zstd 1–22, gzip 1–9).
+		const parseCompression = (
+			raw: string | number,
+			fmt: ArchiveFormat,
+			source: string,
+		): ArchiveCompression => {
+			if (raw === "none" || raw === "basic") return raw;
+			const level = Number(raw);
+			const max = fmt === "gzip" ? 9 : 22;
+			if (!Number.isInteger(level) || level < 1 || level > max) {
+				console.error(
+					`Invalid compression for ${source}: "${raw}". Expected "none", "basic", or a ${fmt} level 1-${max}.`,
+				);
+				process.exit(1);
+			}
+			return level;
+		};
+
+		// Compression tier for archives that don't specify their own: the
+		// --compression / legacy --level flags, else "basic" (Bun's built-in
+		// CompressionStream — fast, streaming, no level control).
+		const defaultCompressionFor = (fmt: ArchiveFormat, source: string): ArchiveCompression =>
+			globalCompressionFlag
+				? parseCompression(globalCompressionFlag, fmt, source)
+				: globalLevelFlag
+					? parseCompression(globalLevelFlag, fmt, source)
+					: "basic";
 
 		type ArchiveSpec = {
 			name: string;
 			path: string;
-			format: "zstd" | "gzip";
-			level: number;
+			format: ArchiveFormat;
+			compression: ArchiveCompression;
 		};
 		const archives: ArchiveSpec[] = [];
 
 		const addArchive = (
 			name: string,
 			rawPath: string,
-			fmt: "zstd" | "gzip",
-			level: number,
+			fmt: ArchiveFormat,
+			compression: ArchiveCompression,
 		) => {
 			if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
 				console.error(`Invalid archive name: "${name}". Must be a valid identifier ([a-zA-Z_][a-zA-Z0-9_]*).`);
@@ -3316,22 +3393,35 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 				console.error(`Archive path does not exist: ${resolvedPath}`);
 				process.exit(1);
 			}
-			archives.push({ name, path: resolvedPath, format: fmt, level });
+			archives.push({ name, path: resolvedPath, format: fmt, compression });
 		};
 
-		// Archives declared in sparkbun.config.ts (build.installer.archives)
+		// Archives declared in sparkbun.config.ts (build.installer.archives).
+		// `compression` ("none" | "basic" | level) is the preferred knob; the
+		// legacy `level` field still works as a numeric tier.
 		const configArchives = (config.build as any)?.installer?.archives as
-			| Array<{ name: string; path: string; format?: "zstd" | "gzip"; level?: number }>
+			| Array<{
+					name: string;
+					path: string;
+					format?: ArchiveFormat;
+					compression?: "none" | "basic" | number;
+					level?: number;
+			  }>
 			| undefined;
 		if (configArchives) {
 			for (const a of configArchives) {
 				const fmt = a.format || globalFormat;
-				const level = a.level ?? (globalLevelFlag ? Number(globalLevelFlag) : defaultLevelFor(fmt));
-				addArchive(a.name, a.path, fmt, level);
+				const compression =
+					a.compression !== undefined
+						? parseCompression(a.compression, fmt, `archive "${a.name}"`)
+						: a.level !== undefined
+							? parseCompression(a.level, fmt, `archive "${a.name}"`)
+							: defaultCompressionFor(fmt, `archive "${a.name}"`);
+				addArchive(a.name, a.path, fmt, compression);
 			}
 		}
 
-		// Archives passed via --archive name=path (level/format from global flags)
+		// Archives passed via --archive name=path (format/compression from global flags)
 		for (let i = 0; i < process.argv.length; i++) {
 			if (process.argv[i] === "--archive" && process.argv[i + 1]) {
 				const arg = process.argv[i + 1]!;
@@ -3340,8 +3430,13 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 					console.error(`Invalid --archive format: "${arg}". Expected: name=path`);
 					process.exit(1);
 				}
-				const level = globalLevelFlag ? Number(globalLevelFlag) : defaultLevelFor(globalFormat);
-				addArchive(arg.substring(0, eqIdx), arg.substring(eqIdx + 1), globalFormat, level);
+				const name = arg.substring(0, eqIdx);
+				addArchive(
+					name,
+					arg.substring(eqIdx + 1),
+					globalFormat,
+					defaultCompressionFor(globalFormat, `--archive ${name}`),
+				);
 			}
 		}
 
@@ -3409,7 +3504,13 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 
 		type ArchiveInfo = {
 			file: string;
-			format: "zstd" | "gzip";
+			// "none" = plain .tar, no decompression step at extract time.
+			format: "zstd" | "gzip" | "none";
+			// The tier as configured ("prebuilt" = the config pointed at an
+			// already-built archive file, embedded verbatim); `level` keeps the
+			// effective numeric level for older consumers (0 = uncompressed or
+			// unknown; "basic" ≈ zstd 3 / gzip 6).
+			compression: "none" | "basic" | number | "prebuilt";
 			level: number;
 			uncompressedBytes: number;
 			fileCount: number;
@@ -3418,51 +3519,74 @@ usageDescriptions : ""}${urlTypes ? "\n" + urlTypes : ""}${documentTypes ?
 		const archiveManifest: Record<string, ArchiveInfo> = {};
 
 		if (archives.length > 0) {
-			console.log("Creating archives (tar + streaming compression)...");
+			console.log("Creating archives (streaming tar + compression)...");
 
 			for (const spec of archives) {
-				const ext = spec.format === "gzip" ? "tar.gz" : "tar.zst";
+				// A FILE path is a prebuilt archive: embed it verbatim instead of
+				// tarring + compressing a directory. Lets projects with large,
+				// slow-to-compress payloads (e.g. zstd-22 game data) build them
+				// once and skip the per-build recompression entirely. Format comes
+				// from the extension; the manifest's progress denominators come
+				// from a streaming scan of the archive.
+				if (statSync(spec.path).isFile()) {
+					const m = spec.path.match(/\.tar(\.zst|\.gz)?$/i);
+					if (!m) {
+						console.error(
+							`Archive "${spec.name}": file paths must point at a prebuilt .tar/.tar.gz/.tar.zst (got ${spec.path})`,
+						);
+						process.exit(1);
+					}
+					const fmt: "zstd" | "gzip" | "none" =
+						m[1]?.toLowerCase() === ".zst" ? "zstd" : m[1]?.toLowerCase() === ".gz" ? "gzip" : "none";
+					const preExt = fmt === "none" ? "tar" : fmt === "gzip" ? "tar.gz" : "tar.zst";
+					const preFileName = `archive-${spec.name}.${preExt}`;
+					console.log(`  Embedding prebuilt ${spec.name}: ${spec.path}`);
+					cpSync(spec.path, join(stagingDir, preFileName));
+					const { uncompressedBytes, fileCount } = await scanTarArchive(spec.path, fmt);
+					const compressedBytes = statSync(spec.path).size;
+					console.log(
+						`  ${spec.name}: ${(uncompressedBytes / 1024 / 1024).toFixed(0)} MB -> ` +
+							`${(compressedBytes / 1024 / 1024).toFixed(0)} MB (prebuilt ${preExt}, ${fileCount} files)`,
+					);
+					archiveManifest[spec.name] = {
+						file: preFileName,
+						format: fmt,
+						compression: "prebuilt",
+						level: 0,
+						uncompressedBytes,
+						fileCount,
+						compressedBytes,
+					};
+					continue;
+				}
+
+				const ext = archiveExtension(spec.format, spec.compression);
 				const archiveFileName = `archive-${spec.name}.${ext}`;
 				const archiveDestPath = join(stagingDir, archiveFileName);
-				const tarTmpPath = join(stagingDir, `archive-${spec.name}.tar`);
 
 				console.log(`  Archiving ${spec.name}: ${spec.path}`);
 
-				// Build the uncompressed tar with the system `tar`. It streams to disk
-				// (bounded build memory) and preserves empty directories as real
-				// entries. The source folder name is kept as the archive root (e.g.
-				// "Dune 2000/...") via `tar -C <parent> <basename>`, so it extracts
-				// into the correct subdirectory.
-				//
-				// The on-disk format may be GNU (Windows/Linux — long paths via
-				// "././@LongLink") or pax (macOS bsdtar — long paths via extended
-				// headers). The installer's streaming extractor understands both, plus
-				// plain ustar, so the archive is portable regardless of build host.
-				//
-				// (Bun.Archive is intentionally not used here: its lazy Bun.file()
-				// inputs write empty file bodies, and eager byte inputs would require
-				// loading the entire payload into memory.)
-				const parent = dirname(spec.path);
-				const baseName = basename(spec.path);
-				createTar(tarTmpPath, parent, [baseName]);
+				// Hand-rolled streaming tar piped straight into the compressor (see
+				// archive-stream.ts): plain ustar with the source folder name kept
+				// as the archive root (e.g. "Dune 2000/..."), file modes preserved,
+				// bounded build memory, and no system tar dependency — the on-disk
+				// format is identical regardless of build host.
+				await writeTarArchive(spec.path, archiveDestPath, spec.format, spec.compression);
 
 				// Measure uncompressed bytes + file count for progress denominators.
 				const { bytes: uncompressedBytes, fileCount } = measureDir(spec.path);
 
-				// Stream-compress the tar at the requested level (bounded build memory).
-				await streamCompressFile(tarTmpPath, archiveDestPath, spec.format, spec.level);
-				unlinkSync(tarTmpPath);
-
 				const compressedBytes = statSync(archiveDestPath).size;
 				console.log(
 					`  ${spec.name}: ${(uncompressedBytes / 1024 / 1024).toFixed(0)} MB -> ` +
 						`${(compressedBytes / 1024 / 1024).toFixed(0)} MB ` +
-						`(${spec.format} level ${spec.level}, ${fileCount} files)`,
+						`(${compressionLabel(spec.format, spec.compression)}, ${fileCount} files)`,
 				);
 				archiveManifest[spec.name] = {
 					file: archiveFileName,
-					format: spec.format,
-					level: spec.level,
+					format: spec.compression === "none" ? "none" : spec.format,
+					compression: spec.compression,
+					level: effectiveLevel(spec.format, spec.compression),
 					uncompressedBytes,
 					fileCount,
 					compressedBytes,
@@ -3659,6 +3783,8 @@ ${archiveExports.join("\n")}
 
 		console.log("Compiling installer executable...");
 
+		// (Compiled via buildCompiledExeWithRetry below — PE metadata commit
+		// failures from AV scans are transient and retried.)
 		const installerCompileOptions: any = {
 			target: `bun-${targetOSName}-${targetARCH}`,
 			outfile: outputPath,
@@ -3681,9 +3807,14 @@ ${archiveExports.join("\n")}
 				}
 			}
 			installerCompileOptions.windows = {
-				// Don't set hideConsole — it conflicts with the ShellExecuteW("runas")
-				// elevation flow in the wrapper template. The PE subsystem patch
-				// (CONSOLE -> WINDOWS) applied after compilation hides the console.
+				// Currently a no-op in Bun (oven-sh/bun#19916 — the subsystem edit is
+				// unreachable code; fix PR #20338 unmerged as of 1.3.14), so the
+				// console is actually hidden by patchPeSubsystem() below. Set it
+				// anyway: it's harmless today and becomes the primary mechanism the
+				// day Bun fixes it (the patch then no-ops). See patchPeSubsystem's
+				// doc comment for why the old "conflicts with elevation" story here
+				// was a misattribution.
+				hideConsole: true,
 				...(icoPath && { icon: icoPath }),
 				title: `${installerName} Setup`,
 				version: installerVersion,
@@ -3693,10 +3824,13 @@ ${archiveExports.join("\n")}
 			};
 		}
 
-		const installerBuild = await Bun.build({
-			entrypoints: [join(stagingDir, "installer.ts")],
-			compile: installerCompileOptions,
-		});
+		const installerBuild = await buildCompiledExeWithRetry(
+			{
+				entrypoints: [join(stagingDir, "installer.ts")],
+				compile: installerCompileOptions,
+			},
+			outputPath,
+		);
 		if (!installerBuild.success) {
 			console.error("Installer compilation failed:", installerBuild.logs);
 			throw new Error("Installer compilation failed");
@@ -4318,9 +4452,16 @@ ${archiveExports.join("\n")}
 		hash: string,
 		config: any,
 		projectRoot: string,
+		// The TARGET platform being built for — not the build host. These used to
+		// be derived from the host OS/ARCH globals, so cross-compiling (e.g.
+		// `--target=win-x64` on macOS) wrongly built a host-platform installer
+		// whose extensionless outfile then collided with the app bundle directory
+		// ("is a directory" build failure).
+		targetOS: "win" | "linux" | "macos",
+		targetArch: string,
 	): Promise<string> {
-		const targetOSName = OS === "macos" ? "darwin" : OS === "win" ? "windows" : "linux";
-		const isWindows = OS === "win";
+		const targetOSName = targetOS === "macos" ? "darwin" : targetOS === "win" ? "windows" : "linux";
+		const isWindows = targetOS === "win";
 
 		const setupFileName = isWindows
 			? getWindowsSetupFileName(config.app.name, buildEnvironment)
@@ -4337,9 +4478,9 @@ ${archiveExports.join("\n")}
 		// Copy archive
 		copyFileSync(compressedTarPath, join(stagingDir, "app-archive.tar.gz"));
 
-		// Write metadata
-		const platformConfig = OS === "macos" ? config.build?.mac
-			: OS === "win" ? config.build?.win
+		// Write metadata (platform config of the TARGET, not the build host)
+		const platformConfig = targetOS === "macos" ? config.build?.mac
+			: targetOS === "win" ? config.build?.win
 			: config.build?.linux;
 		const metadata = {
 			identifier: config.app.identifier,
@@ -4356,11 +4497,18 @@ ${archiveExports.join("\n")}
 		copyFileSync(templatePath, join(stagingDir, "installer.ts"));
 
 		const installerCompileOptions: any = {
-			target: `bun-${targetOSName}-${ARCH}`,
+			target: `bun-${targetOSName}-${targetArch}`,
 			outfile: outputPath,
 		};
 
-		if (isWindows) {
+		if (isWindows && OS !== "win") {
+			// Bun only applies windows compile options on a Windows host; the
+			// console is still hidden by patchPeSubsystem below (works anywhere).
+			console.warn(
+				`\n⚠️  Cross-compiling the Windows installer: icon and PE metadata (title, version, publisher, etc.) will be ignored.\n` +
+				`   Build on a Windows host if the installer exe needs them.\n`
+			);
+		} else if (isWindows) {
 			let icoPath: string | undefined;
 			if (config.build.win?.icon) {
 				const iconSrc = config.build.win.icon.startsWith("/") || config.build.win.icon.match(/^[a-zA-Z]:/)
@@ -4389,10 +4537,13 @@ ${archiveExports.join("\n")}
 		}
 
 		console.log("Compiling installer...");
-		const installerBuild = await Bun.build({
-			entrypoints: [join(stagingDir, "installer.ts")],
-			compile: installerCompileOptions,
-		});
+		const installerBuild = await buildCompiledExeWithRetry(
+			{
+				entrypoints: [join(stagingDir, "installer.ts")],
+				compile: installerCompileOptions,
+			},
+			outputPath,
+		);
 		if (!installerBuild.success) {
 			console.error("Installer compilation failed:", installerBuild.logs);
 			throw new Error("Installer compilation failed");

package/src/installer/installer-template.ts

@@ -92,6 +92,36 @@ function getInstallDir(meta: Metadata): string {
 	}
 }
 
+// Create a .lnk via WScript.Shell. windowsHide is essential: the installer is a
+// GUI-subsystem exe, so without it each PowerShell child allocates its own
+// visible console window mid-install. PowerShell is called by absolute path
+// (PATH isn't reliable in every launch context), and the paths are passed
+// through the environment ($env:SB_*) rather than interpolated into the script
+// text, so an app name containing quotes can't break or inject into the command.
+function createShortcut(lnkPath: string, targetPath: string, workingDir: string) {
+	const systemRoot = process.env.SystemRoot || process.env.windir || "C:\\Windows";
+	const powershell = join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+	const script =
+		"$ws = New-Object -ComObject WScript.Shell;" +
+		" $s = $ws.CreateShortcut($env:SB_LNK);" +
+		" $s.TargetPath = $env:SB_TARGET;" +
+		" $s.WorkingDirectory = $env:SB_WORKDIR;" +
+		" $s.Save()";
+	try {
+		Bun.spawnSync([powershell, "-NoProfile", "-Command", script], {
+			stdout: "ignore",
+			stderr: "ignore",
+			windowsHide: true,
+			env: {
+				...process.env,
+				SB_LNK: lnkPath,
+				SB_TARGET: targetPath,
+				SB_WORKDIR: workingDir,
+			},
+		});
+	} catch {}
+}
+
 async function createWindowsShortcuts(appDir: string, meta: Metadata) {
 	const binDir = join(appDir, "bin");
 	const exePath = join(binDir, `${meta.name.replace(/ /g, "")}.exe`);
@@ -100,19 +130,11 @@ async function createWindowsShortcuts(appDir: string, meta: Metadata) {
 
 	// Start Menu shortcut
 	const startMenu = join(process.env.APPDATA || "", "Microsoft", "Windows", "Start Menu", "Programs");
-	try {
-		Bun.spawnSync(["powershell", "-NoProfile", "-Command",
-			`$ws = New-Object -ComObject WScript.Shell; $s = $ws.CreateShortcut('${join(startMenu, meta.name + ".lnk")}'); $s.TargetPath = '${exePath}'; $s.WorkingDirectory = '${binDir}'; $s.Save()`
-		]);
-	} catch {}
+	createShortcut(join(startMenu, meta.name + ".lnk"), exePath, binDir);
 
 	// Desktop shortcut
-	try {
-		const desktop = join(process.env.USERPROFILE || "", "Desktop");
-		Bun.spawnSync(["powershell", "-NoProfile", "-Command",
-			`$ws = New-Object -ComObject WScript.Shell; $s = $ws.CreateShortcut('${join(desktop, meta.name + ".lnk")}'); $s.TargetPath = '${exePath}'; $s.WorkingDirectory = '${binDir}'; $s.Save()`
-		]);
-	} catch {}
+	const desktop = join(process.env.USERPROFILE || "", "Desktop");
+	createShortcut(join(desktop, meta.name + ".lnk"), exePath, binDir);
 
 	console.log("Created Start Menu and Desktop shortcuts");
 }