sparkbun 0.1.0

package/src/bun/SparkBunConfig.ts

@@ -0,0 +1,497 @@
+/**
+ * SparkBun configuration type definitions
+ * Used in sparkbun.config.ts files
+ */
+
+/**
+ * Bun.build() options that can be passed through to the bundler.
+ * Excludes options that are controlled by SparkBun (entrypoints, outdir, target).
+ * See https://bun.sh/docs/bundler for full documentation.
+ */
+type BunBuildOptions = Omit<
+	Parameters<typeof Bun.build>[0],
+	"entrypoints" | "outdir" | "target"
+>;
+
+export interface SparkBunConfig {
+	/**
+	 * Application metadata configuration
+	 */
+	app: {
+		/**
+		 * The display name of your application
+		 */
+		name: string;
+
+		/**
+		 * Unique identifier for your application (e.g., "com.example.myapp")
+		 * Used for platform-specific identifiers
+		 */
+		identifier: string;
+
+		/**
+		 * Application version string (e.g., "1.0.0")
+		 */
+		version: string;
+
+		/**
+		 * Optional description of the application
+		 */
+		description?: string;
+
+		/**
+		 * Publisher/company name (e.g., "My Company")
+		 * Used in Windows file properties and installer metadata
+		 */
+		publisher?: string;
+
+		/**
+		 * Copyright notice (e.g., "Copyright 2026 My Company")
+		 * Used in Windows file properties
+		 */
+		copyright?: string;
+
+		/**
+		 * Custom URL schemes to register for deep linking (e.g., ["myapp", "myapp-dev"])
+		 * This allows your app to be opened via URLs like myapp://some/path
+		 *
+		 * Platform support:
+		 * - macOS: Fully supported. App must be in /Applications folder for registration to work.
+		 * - Windows: Not yet supported
+		 * - Linux: Not yet supported
+		 *
+		 * To handle incoming URLs, listen for the "open-url" event:
+		 * ```typescript
+		 * SparkBun.events.on("open-url", (e) => {
+		 *   console.log("Opened with URL:", e.data.url);
+		 * });
+		 * ```
+		 */
+		urlSchemes?: string[];
+
+		/**
+		 * File type associations for the application.
+		 * Registers document types so the OS can open files with your app
+		 * (e.g., double-click in Finder, "Open With" menu, drag-to-dock).
+		 *
+		 * Platform support:
+		 * - macOS: Fully supported. Generates CFBundleDocumentTypes in Info.plist.
+		 * - Windows/Linux: Not yet supported.
+		 *
+		 * Files arrive as file:// URLs via the existing "open-url" event:
+		 * ```typescript
+		 * SparkBun.events.on("open-url", (e) => {
+		 *   if (e.data.url.startsWith("file://")) {
+		 *     console.log("Opened file:", e.data.url);
+		 *   }
+		 * });
+		 * ```
+		 */
+		fileAssociations?: Array<{
+			/** File extensions without the leading dot (e.g., ["dotlock", "json"]) */
+			ext: string[];
+			/** Human-readable name for this file type (e.g., "DotLock Document") */
+			name: string;
+			/** The app's role for this file type. @default "Viewer" */
+			role?: "Editor" | "Viewer" | "Shell" | "None";
+			/**
+			 * Path to an .icns file for this document type (macOS only).
+			 * The file is automatically copied into the app bundle's Resources folder
+			 * during the build. Only the filename (without path) is written to Info.plist.
+			 */
+			icon?: string;
+		}>;
+	};
+
+	/**
+	 * Build configuration options
+	 */
+	build?: {
+		/**
+		 * Bun process build configuration.
+		 * Accepts all Bun.build() options (plugins, sourcemap, minify, define, etc.)
+		 * in addition to the entrypoint. See https://bun.sh/docs/bundler
+		 */
+		bun?: {
+			/**
+			 * Entry point for the main Bun process
+			 * @default "src/bun/index.ts"
+			 */
+			entrypoint?: string;
+		} & BunBuildOptions;
+
+		/**
+		 * Browser view build configurations.
+		 * Each view accepts all Bun.build() options (plugins, sourcemap, minify, define, etc.)
+		 * in addition to the entrypoint. See https://bun.sh/docs/bundler
+		 */
+		views?: {
+			[viewName: string]: {
+				/**
+				 * Entry point for this view's TypeScript code
+				 */
+				entrypoint: string;
+			} & BunBuildOptions;
+		};
+
+		/**
+		 * Files to copy directly to the build output
+		 * Key is source path, value is destination path
+		 */
+		copy?: {
+			[sourcePath: string]: string;
+		};
+		/**
+		 * Output folder for built application
+		 * @default "build"
+		 */
+		buildFolder?: string;
+
+		/**
+		 * Output folder for distribution artifacts
+		 * @default "artifacts"
+		 */
+		artifactFolder?: string;
+
+		/**
+		 * Build targets to compile for
+		 * Can be "current", "all", or comma-separated list like "macos-arm64,win-x64"
+		 */
+		targets?: string;
+
+		/**
+		 * Override the CEF (Chromium Embedded Framework) version.
+		 * Format: "CEF_VERSION+chromium-CHROMIUM_VERSION"
+		 * Example: "144.0.11+ge135be2+chromium-144.0.7559.97"
+		 *
+		 * Check the sparkbun-cef-compat compatibility matrix for tested combinations
+		 * before overriding. Using an untested version may cause runtime issues.
+		 * @default Uses the version bundled with this SparkBun release
+		 */
+		cefVersion?: string;
+
+		/**
+		 * Override the Dawn (WebGPU) version.
+		 * Format: semver string (e.g., "0.2.3") or tag (e.g., "v0.2.3-beta.0")
+		 *
+		 * This downloads the specified sparkbun-dawn release and uses it
+		 * instead of the latest release.
+		 * @default Uses the latest sparkbun-dawn release
+		 */
+		wgpuVersion?: string;
+
+		/**
+		 * Override the Bun runtime version.
+		 * Format: semver string (e.g., "1.4.2")
+		 *
+		 * This downloads the specified Bun version from GitHub releases and uses it
+		 * instead of the version bundled with this SparkBun release.
+		 * @default Uses the version bundled with this SparkBun release
+		 */
+		bunVersion?: string;
+
+		/**
+		 * Locales to include in the ICU data file (Linux/Windows only).
+		 * Set to '*' to include all locales, or specify a subset like ['en', 'de']
+		 * to reduce app size. Has no effect on macOS (uses system ICU).
+		 * @default '*'
+		 */
+		locales?: string[] | "*";
+
+		/**
+		 * Additional file or directory paths to watch for changes during `sparkbun dev --watch`.
+		 * Paths are relative to the project root.
+		 * Useful for files that affect your build but aren't listed as entrypoints or copy sources.
+		 */
+		watch?: string[];
+
+		/**
+		 * Glob patterns for files that should not trigger a rebuild when changed.
+		 * Patterns are matched against project-relative paths.
+		 * The `build/`, `artifacts/`, and `node_modules/` directories are always ignored automatically.
+		 */
+		watchIgnore?: string[];
+
+		/**
+		 * macOS-specific build configuration
+		 */
+		mac?: {
+			/**
+			 * Enable code signing for macOS builds
+			 * @default false
+			 */
+			codesign?: boolean;
+
+			/**
+			 * Create a DMG artifact for macOS builds.
+			 * Disable this for local prototype builds that only need the app bundle and update archive.
+			 * @default true
+			 */
+			createDmg?: boolean;
+
+			/**
+			 * Enable notarization for macOS builds (requires codesign)
+			 * @default false
+			 */
+			notarize?: boolean;
+
+			/**
+			 * Bundle CEF (Chromium Embedded Framework) instead of using system WebView
+			 * @default false
+			 */
+			bundleCEF?: boolean;
+
+			/**
+			 * Bundle Dawn (WebGPU) for GPU-native rendering
+			 * @default false
+			 */
+			bundleWGPU?: boolean;
+
+			/**
+			 * Default renderer for webviews when not explicitly specified
+			 * @default 'native'
+			 */
+			defaultRenderer?: "native" | "cef";
+
+			/**
+			 * Custom Chromium command-line flags to pass to CEF during initialization.
+			 * Keys are flag names without the "--" prefix.
+			 * - `true` — add a switch-only flag
+			 * - `"value"` — add a flag with a value
+			 * - `false` — remove a default flag set by SparkBun
+			 *
+			 * @example
+			 * ```typescript
+			 * chromiumFlags: {
+			 *   "disable-gpu": false,               // remove SparkBun's default --disable-gpu
+			 *   "remote-debugging-port": "9333",    // --remote-debugging-port=9333
+			 * }
+			 * ```
+			 */
+			chromiumFlags?: Record<string, string | boolean>;
+
+			/**
+			 * macOS entitlements for code signing
+			 */
+			entitlements?: Record<string, boolean | string | string[]>;
+
+			/**
+			 * Path to .iconset folder or .icon file (from Icon Composer)
+			 * containing app icons.
+			 *
+			 * - `.iconset` folders are converted to .icns via iconutil
+			 *   (requires Command Line Tools)
+			 * - `.icon` files are compiled via actool, producing Assets.car
+			 *   for Liquid Glass on macOS 26+ and a .icns fallback for older
+			 *   macOS versions (requires Xcode)
+			 *
+			 * @default "icon.iconset"
+			 */
+			icons?: string;
+		};
+
+		/**
+		 * Windows-specific build configuration
+		 */
+		win?: {
+			/**
+			 * Bundle CEF (Chromium Embedded Framework) instead of using WebView2
+			 * @default false
+			 */
+			bundleCEF?: boolean;
+
+			/**
+			 * Bundle Dawn (WebGPU) for GPU-native rendering
+			 * @default false
+			 */
+			bundleWGPU?: boolean;
+
+			/**
+			 * Default renderer for webviews when not explicitly specified
+			 * @default 'native'
+			 */
+			defaultRenderer?: "native" | "cef";
+
+			/**
+			 * Custom Chromium command-line flags to pass to CEF during initialization.
+			 * Keys are flag names without the "--" prefix.
+			 * - `true` — add a switch-only flag
+			 * - `"value"` — add a flag with a value
+			 * - `false` — remove a default flag set by SparkBun
+			 *
+			 * @example
+			 * ```typescript
+			 * chromiumFlags: {
+			 *   "disable-gpu": false,               // remove SparkBun's default --disable-gpu
+			 *   "remote-debugging-port": "9333",    // --remote-debugging-port=9333
+			 * }
+			 * ```
+			 */
+			chromiumFlags?: Record<string, string | boolean>;
+
+			/**
+			 * Path to application icon (.ico format)
+			 * Used for the installer/extractor wrapper, desktop shortcuts, and taskbar
+			 * Should include multiple sizes (16x16, 32x32, 48x48, 256x256) for best results
+			 * @example "assets/icon.ico"
+			 */
+			icon?: string;
+
+			/**
+			 * Request administrator privileges on launch.
+			 * The app will check for admin at startup and re-launch itself
+			 * elevated via UAC if needed.
+			 * @default false
+			 */
+			requireAdmin?: boolean;
+		};
+
+		/**
+		 * Linux-specific build configuration
+		 */
+		linux?: {
+			/**
+			 * Bundle CEF (Chromium Embedded Framework) instead of using GTKWebKit
+			 * Recommended on Linux for advanced layer compositing features
+			 * @default false
+			 */
+			bundleCEF?: boolean;
+
+			/**
+			 * Bundle Dawn (WebGPU) for GPU-native rendering
+			 * @default false
+			 */
+			bundleWGPU?: boolean;
+
+			/**
+			 * Default renderer for webviews when not explicitly specified
+			 * @default 'native'
+			 */
+			defaultRenderer?: "native" | "cef";
+
+			/**
+			 * Custom Chromium command-line flags to pass to CEF during initialization.
+			 * Keys are flag names without the "--" prefix.
+			 * - `true` — add a switch-only flag
+			 * - `"value"` — add a flag with a value
+			 * - `false` — remove a default flag set by SparkBun
+			 *
+			 * @example
+			 * ```typescript
+			 * chromiumFlags: {
+			 *   "disable-gpu": false,               // remove SparkBun's default --disable-gpu
+			 *   "remote-debugging-port": "9333",    // --remote-debugging-port=9333
+			 * }
+			 * ```
+			 */
+			chromiumFlags?: Record<string, string | boolean>;
+
+			/**
+			 * Path to application icon (PNG format recommended)
+			 * Used for desktop entries, window icons, and taskbar
+			 * Should be at least 256x256 pixels for best results
+			 * @example "assets/icon.png"
+			 */
+			icon?: string;
+
+			/**
+			 * Request root privileges on launch.
+			 * The app will check for root at startup and re-launch itself
+			 * via pkexec if needed.
+			 * @default false
+			 */
+			requireAdmin?: boolean;
+
+			/**
+			 * Create a .deb package for Debian/Ubuntu.
+			 * @default false
+			 */
+			createDeb?: boolean;
+
+			/**
+			 * System library dependencies for the .deb package.
+			 * @default ["libwebkit2gtk-4.1-0", "libgtk-3-0t64", "libsoup-3.0-0", "libjavascriptcoregtk-4.1-0", "libayatana-appindicator3-1", "libgdk-pixbuf-2.0-0"]
+			 */
+			debDependencies?: string[];
+
+			/**
+			 * Package maintainer for the .deb control file.
+			 * @example "Your Name <you@example.com>"
+			 */
+			debMaintainer?: string;
+
+			/**
+			 * Install prefix for the .deb package.
+			 * @default "/opt/<AppNameNoSpaces>"
+			 */
+			installDir?: string;
+
+			/**
+			 * Desktop entry category.
+			 * @default "Utility;Application;"
+			 */
+			category?: string;
+		};
+	};
+
+	/**
+	 * Runtime behaviour configuration.
+	 * These values are copied into build.json and available to the Bun process at runtime.
+	 * You can add arbitrary keys here and access them via BuildConfig.
+	 */
+	runtime?: {
+		/**
+		 * Quit the application when the last BrowserWindow is closed.
+		 * @default true
+		 */
+		exitOnLastWindowClosed?: boolean;
+
+		[key: string]: unknown;
+	};
+
+	/**
+	 * Build scripts configuration
+	 */
+	scripts?: {
+		/**
+		 * Script to run before the build starts
+		 * Can be a path to a script file
+		 */
+		preBuild?: string;
+
+		/**
+		 * Script to run after build completes
+		 * Can be a path to a script file
+		 */
+		postBuild?: string;
+
+		/**
+		 * Script to run after the app is wrapped (macOS .app bundle created)
+		 * Can be a path to a script file
+		 */
+		postWrap?: string;
+
+		/**
+		 * Script to run after packaging is complete
+		 * Can be a path to a script file
+		 */
+		postPackage?: string;
+	};
+
+	/**
+	 * Release and distribution configuration
+	 */
+	release?: {
+		/**
+		 * Base URL for artifact distribution (e.g., S3 bucket, GitHub Releases)
+		 * Used for auto-updates and patch generation
+		 */
+		baseUrl?: string;
+		/**
+		 * Generate delta patch files by diffing against the previous release.
+		 * Disable to skip patch generation for local canary/stable testing.
+		 * @default true
+		 */
+		generatePatch?: boolean;
+	};
+}

package/src/bun/__tests__/ffi-contract.test.ts

@@ -0,0 +1,105 @@
+// Contract tests for the bun:ffi APIs that sparkbun depends on.
+//
+// Bun bumps don't usually break sparkbun, but when they do, the breakage
+// almost always lives in this surface — JSCallback marshaling, FFIType
+// encoding, dlopen behavior. These tests are a tripwire: if a new Bun release
+// breaks any of them, we want to know before cutting a sparkbun release,
+// not after a user reports a crash.
+//
+// Skipped on Windows for now since the bun-check workflow runs on Linux and
+// the system library paths differ. If we add a Windows runner later, switch
+// the libc path resolution to include msvcrt/ucrtbase.
+
+import { describe, expect, it } from "bun:test";
+import {
+	CString,
+	FFIType,
+	JSCallback,
+	dlopen,
+	ptr,
+	toArrayBuffer,
+	type Pointer,
+} from "bun:ffi";
+
+const isUnix =
+	process.platform === "darwin" || process.platform === "linux";
+
+const libcPath =
+	process.platform === "darwin" ? "libSystem.B.dylib" : "libc.so.6";
+
+(isUnix ? describe : describe.skip)(
+	"bun:ffi contract used by sparkbun",
+	() => {
+		it("dlopen + FFIType.cstring + FFIType.u64 (strlen)", () => {
+			const lib = dlopen(libcPath, {
+				strlen: {
+					args: [FFIType.cstring],
+					returns: FFIType.u64,
+				},
+			});
+
+			const len = lib.symbols.strlen(
+				new TextEncoder().encode("hello\0"),
+			);
+			expect(Number(len)).toBe(5);
+
+			lib.close();
+		});
+
+		it("ptr + toArrayBuffer round-trip", () => {
+			const src = new Uint8Array([1, 2, 3, 4, 5]);
+			const back = new Uint8Array(
+				toArrayBuffer(ptr(src), 0, src.byteLength),
+			);
+			expect(Array.from(back)).toEqual([1, 2, 3, 4, 5]);
+		});
+
+		it("CString reads null-terminated bytes", () => {
+			const buf = new Uint8Array([72, 105, 33, 0]); // "Hi!\0"
+			const s = new CString(ptr(buf));
+			expect(s.toString()).toBe("Hi!");
+		});
+
+		it("JSCallback: native invokes JS via function pointer (qsort)", () => {
+			const lib = dlopen(libcPath, {
+				qsort: {
+					args: [
+						FFIType.ptr,
+						FFIType.u64,
+						FFIType.u64,
+						FFIType.function,
+					],
+					returns: FFIType.void,
+				},
+			});
+
+			let comparisonCount = 0;
+			const compare = new JSCallback(
+				(aPtr: Pointer, bPtr: Pointer) => {
+					comparisonCount++;
+					const a = new Int32Array(toArrayBuffer(aPtr, 0, 4))[0]!;
+					const b = new Int32Array(toArrayBuffer(bPtr, 0, 4))[0]!;
+					return a - b;
+				},
+				{
+					args: [FFIType.ptr, FFIType.ptr],
+					returns: FFIType.i32,
+				},
+			);
+
+			const arr = new Int32Array([5, 2, 8, 1, 3]);
+			lib.symbols.qsort(
+				ptr(arr),
+				BigInt(arr.length),
+				4n,
+				compare.ptr,
+			);
+
+			expect(Array.from(arr)).toEqual([1, 2, 3, 5, 8]);
+			expect(comparisonCount).toBeGreaterThan(0);
+
+			compare.close();
+			lib.close();
+		});
+	},
+);

package/src/bun/core/ApplicationMenu.ts

@@ -0,0 +1,70 @@
+import { ffi, type ApplicationMenuItemConfig } from "../proc/native";
+import sparkBunEventEmitter from "../events/eventEmitter";
+import { roleLabelMap } from "./menuRoles";
+
+type NonDividerMenuItem = {
+	type?: "normal";
+	label?: string;
+	tooltip?: string;
+	action?: string;
+	role?: string;
+	data?: unknown;
+	submenu?: Array<ApplicationMenuItemConfig>;
+	enabled?: boolean;
+	checked?: boolean;
+	hidden?: boolean;
+	accelerator?: string;
+};
+
+export const setApplicationMenu = (menu: Array<ApplicationMenuItemConfig>) => {
+	const menuWithDefaults = menuConfigWithDefaults(menu);
+	ffi.request.setApplicationMenu({
+		menuConfig: JSON.stringify(menuWithDefaults),
+	});
+};
+
+export const on = (
+	name: "application-menu-clicked",
+	handler: (event: unknown) => void,
+) => {
+	const specificName = `${name}`;
+	sparkBunEventEmitter.on(specificName, handler);
+};
+
+const menuConfigWithDefaults = (
+	menu: Array<ApplicationMenuItemConfig>,
+): Array<ApplicationMenuItemConfig> => {
+	return menu.map((item) => {
+		if (item.type === "divider" || item.type === "separator") {
+			return { type: "divider" } as const;
+		} else {
+			const menuItem = item as NonDividerMenuItem;
+			// Use shared serialization method
+			const actionWithDataId = ffi.internal.serializeMenuAction(
+				menuItem.action || "",
+				menuItem.data,
+			);
+
+			return {
+				label:
+					menuItem.label ||
+					roleLabelMap[menuItem.role as keyof typeof roleLabelMap] ||
+					"",
+				type: menuItem.type || "normal",
+				// application menus can either have an action or a role. not both.
+				...(menuItem.role
+					? { role: menuItem.role }
+					: { action: actionWithDataId }),
+				// default enabled to true unless explicitly set to false
+				enabled: menuItem.enabled === false ? false : true,
+				checked: Boolean(menuItem.checked),
+				hidden: Boolean(menuItem.hidden),
+				tooltip: menuItem.tooltip || undefined,
+				accelerator: menuItem.accelerator || undefined,
+				...(menuItem.submenu
+					? { submenu: menuConfigWithDefaults(menuItem.submenu) }
+					: {}),
+			};
+		}
+	});
+};