sparkbun 0.1.0

package/src/bun/preload/encryption.ts

@@ -0,0 +1,86 @@
+// Encryption/Decryption for secure RPC
+// Uses per-webview secret key set in window.__sparkbunSecretKeyBytes
+
+import "./globals.d.ts";
+
+function base64ToUint8Array(base64: string): Uint8Array {
+	return new Uint8Array(
+		atob(base64)
+			.split("")
+			.map((char) => char.charCodeAt(0)),
+	);
+}
+
+function uint8ArrayToBase64(uint8Array: Uint8Array): string {
+	let binary = "";
+	for (let i = 0; i < uint8Array.length; i++) {
+		binary += String.fromCharCode(uint8Array[i]!);
+	}
+	return btoa(binary);
+}
+
+async function generateKeyFromBytes(rawKey: Uint8Array): Promise<CryptoKey> {
+	return await window.crypto.subtle.importKey(
+		"raw",
+		rawKey as unknown as ArrayBuffer,
+		{ name: "AES-GCM" },
+		true,
+		["encrypt", "decrypt"],
+	);
+}
+
+export async function initEncryption(): Promise<void> {
+	const secretKey = await generateKeyFromBytes(
+		new Uint8Array(window.__sparkbunSecretKeyBytes),
+	);
+
+	const encryptString = async (
+		plaintext: string,
+	): Promise<{ encryptedData: string; iv: string; tag: string }> => {
+		const encoder = new TextEncoder();
+		const encodedText = encoder.encode(plaintext);
+		const iv = window.crypto.getRandomValues(new Uint8Array(12));
+		const encryptedBuffer = await window.crypto.subtle.encrypt(
+			{ name: "AES-GCM", iv },
+			secretKey,
+			encodedText,
+		);
+
+		// Split the tag (last 16 bytes) from the ciphertext
+		const encryptedData = new Uint8Array(encryptedBuffer.slice(0, -16));
+		const tag = new Uint8Array(encryptedBuffer.slice(-16));
+
+		return {
+			encryptedData: uint8ArrayToBase64(encryptedData),
+			iv: uint8ArrayToBase64(iv),
+			tag: uint8ArrayToBase64(tag),
+		};
+	};
+
+	const decryptString = async (
+		encryptedDataB64: string,
+		ivB64: string,
+		tagB64: string,
+	): Promise<string> => {
+		const encryptedData = base64ToUint8Array(encryptedDataB64);
+		const iv = base64ToUint8Array(ivB64);
+		const tag = base64ToUint8Array(tagB64);
+
+		// Combine encrypted data and tag to match the format expected by SubtleCrypto
+		const combinedData = new Uint8Array(encryptedData.length + tag.length);
+		combinedData.set(encryptedData);
+		combinedData.set(tag, encryptedData.length);
+
+		const decryptedBuffer = await window.crypto.subtle.decrypt(
+			{ name: "AES-GCM", iv: iv as unknown as ArrayBuffer },
+			secretKey,
+			combinedData as unknown as ArrayBuffer,
+		);
+
+		const decoder = new TextDecoder();
+		return decoder.decode(decryptedBuffer);
+	};
+
+	window.__sparkbun_encrypt = encryptString;
+	window.__sparkbun_decrypt = decryptString;
+}

package/src/bun/preload/events.ts

@@ -0,0 +1,171 @@
+// Shared Event Emission for webview lifecycle events
+// Uses __sparkbunEventBridge which is available on ALL webviews (including sandboxed)
+// Falls back to __sparkbunInternalBridge for backwards compatibility until native code
+// is updated to include the eventBridge handler
+// This is a one-way channel for emitting events to native/bun - no RPC capability
+
+import "./globals.d.ts";
+
+// Emit a webview event to native code
+export function emitWebviewEvent(eventName: string, detail: string) {
+	// setTimeout works around a race condition with Bun FFI
+	setTimeout(() => {
+		// Prefer eventBridge (available on all webviews), fall back to internalBridge
+		// (for backwards compatibility until native code adds eventBridge handler)
+		const bridge =
+			window.__sparkbunEventBridge || window.__sparkbunInternalBridge;
+		bridge?.postMessage(
+			JSON.stringify({
+				id: "webviewEvent",
+				type: "message",
+				payload: {
+					id: window.__sparkbunWebviewId,
+					eventName,
+					detail,
+				},
+			}),
+		);
+	});
+}
+
+// Set up standard lifecycle event listeners
+export function initLifecycleEvents() {
+	// Emit dom-ready when page loads (top-level window only)
+	window.addEventListener("load", () => {
+		if (window === window.top) {
+			emitWebviewEvent("dom-ready", document.location.href);
+		}
+	});
+
+	// Track in-page navigation
+	window.addEventListener("popstate", () => {
+		emitWebviewEvent("did-navigate-in-page", window.location.href);
+	});
+
+	window.addEventListener("hashchange", () => {
+		emitWebviewEvent("did-navigate-in-page", window.location.href);
+	});
+}
+
+// Track cmd key state for SPA navigation detection
+let cmdKeyHeld = false;
+let cmdKeyTimestamp = 0;
+const CMD_KEY_THRESHOLD_MS = 500;
+
+export function isCmdHeld(): boolean {
+	if (cmdKeyHeld) return true;
+	return (
+		Date.now() - cmdKeyTimestamp < CMD_KEY_THRESHOLD_MS && cmdKeyTimestamp > 0
+	);
+}
+
+// Set up cmd+click detection for opening links in new windows
+export function initCmdClickHandling() {
+	window.addEventListener(
+		"keydown",
+		(event) => {
+			if (event.key === "Meta" || event.metaKey) {
+				cmdKeyHeld = true;
+				cmdKeyTimestamp = Date.now();
+			}
+		},
+		true,
+	);
+
+	window.addEventListener(
+		"keyup",
+		(event) => {
+			if (event.key === "Meta") {
+				cmdKeyHeld = false;
+				cmdKeyTimestamp = Date.now();
+			}
+		},
+		true,
+	);
+
+	window.addEventListener("blur", () => {
+		cmdKeyHeld = false;
+	});
+
+	// Intercept cmd+clicks on anchors before SPA frameworks can handle them
+	window.addEventListener(
+		"click",
+		(event) => {
+			if (event.metaKey || event.ctrlKey) {
+				const anchor = (event.target as HTMLElement)?.closest?.("a");
+				if (anchor && (anchor as HTMLAnchorElement).href) {
+					event.preventDefault();
+					event.stopPropagation();
+					event.stopImmediatePropagation();
+					emitWebviewEvent(
+						"new-window-open",
+						JSON.stringify({
+							url: (anchor as HTMLAnchorElement).href,
+							isCmdClick: true,
+							isSPANavigation: false,
+						}),
+					);
+				}
+			}
+		},
+		true,
+	);
+}
+
+// Intercept SPA navigation (history.pushState/replaceState) when cmd is held
+export function initSPANavigationInterception() {
+	const originalPushState = history.pushState;
+	const originalReplaceState = history.replaceState;
+
+	history.pushState = function (
+		state: unknown,
+		title: string,
+		url?: string | URL | null,
+	) {
+		if (isCmdHeld() && url) {
+			const resolvedUrl = new URL(String(url), window.location.href).href;
+			emitWebviewEvent(
+				"new-window-open",
+				JSON.stringify({
+					url: resolvedUrl,
+					isCmdClick: true,
+					isSPANavigation: true,
+				}),
+			);
+			return;
+		}
+		return originalPushState.apply(this, [state, title, url]);
+	};
+
+	history.replaceState = function (
+		state: unknown,
+		title: string,
+		url?: string | URL | null,
+	) {
+		if (isCmdHeld() && url) {
+			const resolvedUrl = new URL(String(url), window.location.href).href;
+			emitWebviewEvent(
+				"new-window-open",
+				JSON.stringify({
+					url: resolvedUrl,
+					isCmdClick: true,
+					isSPANavigation: true,
+				}),
+			);
+			return;
+		}
+		return originalReplaceState.apply(this, [state, title, url]);
+	};
+}
+
+// Prevent overscroll bounce effect
+export function initOverscrollPrevention() {
+	document.addEventListener("DOMContentLoaded", () => {
+		const style = document.createElement("style");
+		style.type = "text/css";
+		style.appendChild(
+			document.createTextNode("html, body { overscroll-behavior: none; }"),
+		);
+		document.head.appendChild(style);
+	});
+}

package/src/bun/preload/globals.d.ts

@@ -0,0 +1,45 @@
+// Type declarations for SparkBun preload globals
+// These are set dynamically per-webview before the preload script runs
+
+declare global {
+	interface Window {
+		__sparkbunWebviewId: number;
+		__sparkbunWindowId: number;
+		__sparkbunRpcSocketPort: number;
+		__sparkbunHostSocketPort?: number;
+		__sparkbunSecretKeyBytes: number[];
+		// Event-only bridge (all webviews, including sandboxed)
+		__sparkbunEventBridge?: {
+			postMessage: (message: string) => void;
+		};
+		// Internal RPC bridge (trusted webviews only)
+		__sparkbunInternalBridge?: {
+			postMessage: (message: string) => void;
+		};
+		// User RPC bridge (trusted webviews only)
+		__sparkbunHostBridge?: {
+			postMessage: (message: string) => void;
+		};
+		__sparkbunBunBridge?: {
+			postMessage: (message: string) => void;
+		};
+		__sparkbun_encrypt: (
+			plaintext: string,
+		) => Promise<{ encryptedData: string; iv: string; tag: string }>;
+		__sparkbun_decrypt: (
+			encryptedData: string,
+			iv: string,
+			tag: string,
+		) => Promise<string>;
+		__sparkbunSendToHost: (message: unknown) => void;
+		__sparkbunPendingHostMessages?: unknown[];
+		__sparkbun: {
+			receiveMessageFromHost: (msg: unknown) => void;
+			receiveInternalMessageFromHost: (msg: unknown) => void;
+			receiveMessageFromBun: (msg: unknown) => void;
+			receiveInternalMessageFromBun: (msg: unknown) => void;
+		};
+	}
+}
+
+export {};

package/src/bun/preload/index-sandboxed.ts

@@ -0,0 +1,28 @@
+// SparkBun Sandboxed Preload Script (for untrusted webviews)
+// This is compiled to JS and injected into webviews that ARE sandboxed
+//
+// Minimal functionality for security: NO RPC, NO encryption, NO webview tags
+// Only includes: lifecycle events, cmd+click handling, overscroll prevention
+//
+// Before this script runs, the following must be set:
+// - window.__sparkbunWebviewId
+// - window.__sparkbunWindowId
+// - window.__sparkbunEventBridge (event emission only)
+
+import "./globals.d.ts";
+import {
+	initLifecycleEvents,
+	initCmdClickHandling,
+	initSPANavigationInterception,
+	initOverscrollPrevention,
+} from "./events";
+
+// Initialize minimal features for sandboxed webviews
+// No RPC handlers - sandboxed webviews cannot communicate with Bun
+// No drag regions - sandboxed content shouldn't control window movement
+// No webview tags - sandboxed content cannot create OOPIFs
+
+initLifecycleEvents();
+initCmdClickHandling();
+initSPANavigationInterception();
+initOverscrollPrevention();

package/src/bun/preload/index.ts

@@ -0,0 +1,77 @@
+// SparkBun Full Preload Script (for trusted webviews)
+// This is compiled to JS and injected into webviews that are NOT sandboxed
+//
+// Includes: RPC, encryption, drag regions, webview tags, lifecycle events
+//
+// Before this script runs, the following must be set:
+// - window.__sparkbunWebviewId
+// - window.__sparkbunWindowId
+// - window.__sparkbunRpcSocketPort
+// - window.__sparkbunHostSocketPort (optional alias)
+// - window.__sparkbunSecretKeyBytes
+// - window.__sparkbunEventBridge (event emission - all webviews)
+// - window.__sparkbunInternalBridge (internal RPC - trusted only)
+// - window.__sparkbunHostBridge (user RPC - trusted only)
+// - window.__sparkbunBunBridge (legacy alias)
+
+import "./globals.d.ts";
+import { initEncryption } from "./encryption";
+import { handleResponse } from "./internalRpc";
+import { initDragRegions } from "./dragRegions";
+import { initWebviewTag } from "./webviewTag";
+import { initWgpuTag } from "./wgpuTag";
+import {
+	emitWebviewEvent,
+	initLifecycleEvents,
+	initCmdClickHandling,
+	initSPANavigationInterception,
+	initOverscrollPrevention,
+} from "./events";
+
+// Initialize encryption first (async)
+initEncryption().catch((err) =>
+	console.error("Failed to initialize encryption:", err),
+);
+
+// Set up global handlers for bun to call back
+// Wrapper to satisfy the (msg: unknown) => void type
+const internalMessageHandler = (msg: unknown) => {
+	handleResponse(msg as { type: string; id: string; success: boolean; payload: unknown });
+};
+
+const defaultUserMessageHandler = (msg: unknown) => {
+	// Buffer user RPC packets that arrive before the page-specific Electroview
+	// instance installs the real handler.
+	if (!window.__sparkbunPendingHostMessages) {
+		window.__sparkbunPendingHostMessages = [];
+	}
+	window.__sparkbunPendingHostMessages.push(msg);
+};
+
+if (!window.__sparkbun) {
+	window.__sparkbun = {
+		receiveInternalMessageFromHost: internalMessageHandler,
+		receiveMessageFromHost: defaultUserMessageHandler,
+		receiveInternalMessageFromBun: internalMessageHandler,
+		receiveMessageFromBun: defaultUserMessageHandler,
+	};
+} else {
+	window.__sparkbun.receiveInternalMessageFromHost = internalMessageHandler;
+	window.__sparkbun.receiveMessageFromHost = defaultUserMessageHandler;
+	window.__sparkbun.receiveInternalMessageFromBun = internalMessageHandler;
+	window.__sparkbun.receiveMessageFromBun = defaultUserMessageHandler;
+}
+
+// Allow preload scripts to send custom messages to the host webview
+window.__sparkbunSendToHost = (message: unknown) => {
+	emitWebviewEvent("host-message", JSON.stringify(message));
+};
+
+// Initialize all features
+initLifecycleEvents();
+initCmdClickHandling();
+initSPANavigationInterception();
+initOverscrollPrevention();
+initDragRegions();
+initWebviewTag();
+initWgpuTag();

package/src/bun/preload/internalRpc.ts

@@ -0,0 +1,80 @@
+// Internal RPC System for webview tags, drag regions, etc.
+// Communicates with Bun via __sparkbunInternalBridge
+
+import "./globals.d.ts";
+
+interface PendingRequest {
+	resolve: (value: unknown) => void;
+	reject: (reason: unknown) => void;
+}
+
+const pendingRequests: Record<string, PendingRequest> = {};
+let requestId = 0;
+let isProcessingQueue = false;
+const sendQueue: string[] = [];
+
+function processQueue() {
+	if (isProcessingQueue) {
+		setTimeout(processQueue);
+		return;
+	}
+	if (sendQueue.length === 0) return;
+
+	isProcessingQueue = true;
+	const batch = JSON.stringify(sendQueue);
+	sendQueue.length = 0;
+	window.__sparkbunInternalBridge?.postMessage(batch);
+
+	// 2ms delay to work around Bun JSCallback threading issue
+	setTimeout(() => {
+		isProcessingQueue = false;
+	}, 2);
+}
+
+export function send(type: string, payload: unknown) {
+	// Format: { type: 'message', id: handlerName, payload: data }
+	sendQueue.push(JSON.stringify({ type: "message", id: type, payload }));
+	processQueue();
+}
+
+export function request(type: string, payload: unknown): Promise<unknown> {
+	return new Promise((resolve, reject) => {
+		const id = `req_${++requestId}_${Date.now()}`;
+		pendingRequests[id] = { resolve, reject };
+		// Format: { type: 'request', method: handlerName, id: requestId, params: data, hostWebviewId: ... }
+		sendQueue.push(
+			JSON.stringify({
+				type: "request",
+				method: type,
+				id,
+				params: payload,
+				hostWebviewId: window.__sparkbunWebviewId,
+			}),
+		);
+		processQueue();
+		// Timeout after 10s
+		setTimeout(() => {
+			if (pendingRequests[id]) {
+				delete pendingRequests[id];
+				reject(new Error(`Request timeout: ${type}`));
+			}
+		}, 10000);
+	});
+}
+
+export function handleResponse(msg: {
+	type: string;
+	id: string;
+	success: boolean;
+	payload: unknown;
+}) {
+	// msg format: { type: 'response', id: requestId, success: bool, payload: data }
+	if (msg && msg.type === "response" && msg.id) {
+		const pending = pendingRequests[msg.id];
+		if (pending) {
+			delete pendingRequests[msg.id];
+			if (msg.success) pending.resolve(msg.payload);
+			else pending.reject(msg.payload);
+		}
+	}
+}

package/src/bun/preload/overlaySync.ts

@@ -0,0 +1,107 @@
+import "./globals.d.ts";
+
+export interface Rect {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+
+export type MaskRect = Rect;
+
+export type OverlaySyncOptions = {
+	onSync: (rect: Rect, masksJson: string) => void;
+	getMasks?: () => MaskRect[];
+	burstIntervalMs?: number;
+	baseIntervalMs?: number;
+	burstDurationMs?: number;
+};
+
+export class OverlaySyncController {
+	private element: HTMLElement;
+	private options: Required<OverlaySyncOptions>;
+	private lastRect: Rect = { x: 0, y: 0, width: 0, height: 0 };
+	private resizeObserver: ResizeObserver | null = null;
+	private positionLoop: ReturnType<typeof setTimeout> | null = null;
+	private resizeHandler: (() => void) | null = null;
+	private burstUntil = 0;
+
+	constructor(element: HTMLElement, options: OverlaySyncOptions) {
+		this.element = element;
+		this.options = {
+			onSync: options.onSync,
+			getMasks: options.getMasks ?? (() => []),
+			burstIntervalMs: options.burstIntervalMs ?? 50,
+			baseIntervalMs: options.baseIntervalMs ?? 100,
+			burstDurationMs: options.burstDurationMs ?? 500,
+		};
+	}
+
+	start() {
+		this.resizeObserver = new ResizeObserver(() => this.sync());
+		this.resizeObserver.observe(this.element);
+
+		const loop = () => {
+			this.sync();
+			const now = performance.now();
+			const interval =
+				now < this.burstUntil
+					? this.options.burstIntervalMs
+					: this.options.baseIntervalMs;
+			this.positionLoop = setTimeout(loop, interval);
+		};
+		this.positionLoop = setTimeout(loop, this.options.baseIntervalMs);
+
+		this.resizeHandler = () => this.sync(true);
+		window.addEventListener("resize", this.resizeHandler);
+	}
+
+	stop() {
+		if (this.resizeObserver) this.resizeObserver.disconnect();
+		if (this.positionLoop) clearTimeout(this.positionLoop);
+		if (this.resizeHandler) {
+			window.removeEventListener("resize", this.resizeHandler);
+		}
+		this.resizeObserver = null;
+		this.positionLoop = null;
+		this.resizeHandler = null;
+	}
+
+	forceSync() {
+		this.sync(true);
+	}
+
+	setLastRect(rect: Rect) {
+		this.lastRect = rect;
+	}
+
+	private sync(force = false) {
+		const rect = this.element.getBoundingClientRect();
+		const newRect: Rect = {
+			x: rect.x,
+			y: rect.y,
+			width: rect.width,
+			height: rect.height,
+		};
+
+		if (newRect.width === 0 && newRect.height === 0) {
+			return;
+		}
+
+		if (
+			!force &&
+			newRect.x === this.lastRect.x &&
+			newRect.y === this.lastRect.y &&
+			newRect.width === this.lastRect.width &&
+			newRect.height === this.lastRect.height
+		) {
+			return;
+		}
+
+		this.burstUntil = performance.now() + this.options.burstDurationMs;
+		this.lastRect = newRect;
+
+		const masks = this.options.getMasks();
+		this.options.onSync(newRect, JSON.stringify(masks));
+	}
+}