sparkbun 0.1.0

package/src/browser/index.ts

@@ -0,0 +1,234 @@
+import {
+	type RPCSchema,
+	type RPCTransport,
+	type SparkBunRPCSchema,
+	type SparkBunRPCConfig,
+	type RPCWithTransport,
+	createRPC,
+	defineSparkBunRPC,
+} from "../shared/rpc.js";
+import {
+	type WebviewTagElement,
+	type WebviewEventTypes,
+} from "./webviewtag";
+import { type WgpuTagElement, type WgpuEventTypes } from "./wgputag";
+import "./global.d.ts";
+
+const WEBVIEW_ID = window.__sparkbunWebviewId;
+const HOST_SOCKET_PORT =
+	window.__sparkbunHostSocketPort ?? window.__sparkbunRpcSocketPort;
+
+class Electroview<T extends RPCWithTransport> {
+	hostSocket?: WebSocket;
+	hostSocketCanSend = false;
+	// user's custom rpc browser <-> bun
+	rpc?: T;
+	rpcHandler?: (msg: unknown) => void;
+	carrots = {
+		invoke: <R = unknown>(
+			carrotId: string,
+			method: string,
+			params?: unknown,
+			options?: { windowId?: string },
+		) => this.invokeCarrot<R>(carrotId, method, params, options),
+	};
+
+	constructor(config: { rpc: T }) {
+		this.rpc = config.rpc;
+		this.init();
+	}
+
+	init() {
+		this.initSocketToHost();
+
+		// Set up handler for user RPC messages from the host runtime.
+		const hostMessageHandler = this.receiveMessageFromHost.bind(this);
+		window.__sparkbun!.receiveMessageFromHost = hostMessageHandler;
+		window.__sparkbun!.receiveMessageFromBun = hostMessageHandler;
+
+		if (this.rpc) {
+			this.rpc.setTransport(this.createTransport());
+		}
+
+		const pendingMessages = window.__sparkbunPendingHostMessages;
+		if (pendingMessages?.length) {
+			window.__sparkbunPendingHostMessages = [];
+			for (const message of pendingMessages) {
+				hostMessageHandler(message);
+			}
+		}
+	}
+
+	initSocketToHost() {
+		// Skip native socket when running in a remote browser (no port/webview ID)
+		if (!HOST_SOCKET_PORT || !WEBVIEW_ID) {
+			return;
+		}
+
+		// Note: Using ws:// for localhost is intentional - all RPC messages are
+		// encrypted with per-webview AES-GCM keys, making TLS redundant
+		const socket = new WebSocket(
+			`ws://localhost:${HOST_SOCKET_PORT}/socket?webviewId=${WEBVIEW_ID}`,
+		);
+
+		this.hostSocket = socket;
+
+		socket.addEventListener("open", () => {
+			// this.hostSocket?.send("Hello from webview " + WEBVIEW_ID);
+		});
+
+		socket.addEventListener("message", async (event) => {
+			const message = event.data;
+			if (typeof message === "string") {
+				try {
+					const encryptedPacket = JSON.parse(message);
+
+					const decrypted = await window.__sparkbun_decrypt(
+						encryptedPacket.encryptedData,
+						encryptedPacket.iv,
+						encryptedPacket.tag,
+					);
+
+					this.hostSocketCanSend = true;
+					this.rpcHandler?.(JSON.parse(decrypted));
+				} catch (err) {
+					console.error("Error parsing bun message:", err);
+				}
+			} else if (message instanceof Blob) {
+				// Handle binary data (e.g., convert Blob to ArrayBuffer if needed)
+			} else {
+				console.error("UNKNOWN DATA TYPE RECEIVED:", event.data);
+			}
+		});
+
+		socket.addEventListener("error", (event) => {
+			this.hostSocketCanSend = false;
+			console.error("Socket error:", event);
+		});
+
+		socket.addEventListener("close", (_event) => {
+			this.hostSocketCanSend = false;
+			// console.log("Socket closed:", event);
+		});
+	}
+
+	createTransport(): RPCTransport {
+		const that = this;
+		return {
+			send(message: unknown) {
+				try {
+					const messageString = JSON.stringify(message);
+					that.sendMessageToHost(messageString);
+				} catch (error) {
+					console.error("host: failed to serialize message to webview", error);
+				}
+			},
+			registerHandler(handler: (msg: unknown) => void) {
+				that.rpcHandler = handler;
+			},
+		};
+	}
+
+	async sendMessageToHost(msg: string) {
+		if (
+			this.hostSocketCanSend &&
+			this.hostSocket?.readyState === WebSocket.OPEN
+		) {
+			try {
+				const { encryptedData, iv, tag } =
+					await window.__sparkbun_encrypt(msg);
+
+				const encryptedPacket = {
+					encryptedData: encryptedData,
+					iv: iv,
+					tag: tag,
+				};
+				const encryptedPacketString = JSON.stringify(encryptedPacket);
+				this.hostSocket.send(encryptedPacketString);
+				return;
+			} catch (error) {
+				console.error("Error sending message to host via socket:", error);
+			}
+		}
+
+		// if socket's are unavailable, fallback to postMessage
+		window.__sparkbunHostBridge?.postMessage(msg);
+	}
+
+	receiveMessageFromHost(msg: unknown) {
+		// NOTE: in the webview messages are passed by executing window.__sparkbun.receiveMessageFromHost(object)
+		// so they're already parsed into an object here
+		if (this.rpcHandler) {
+			this.rpcHandler(msg);
+		}
+	}
+
+	async invokeCarrot<R = unknown>(
+		carrotId: string,
+		method: string,
+		params?: unknown,
+		options?: { windowId?: string },
+	): Promise<R> {
+		const requestProxy = (this.rpc as any)?.request;
+		if (!requestProxy || typeof requestProxy.invokeCarrot !== "function") {
+			throw new Error("Renderer carrot invocation is not available in this SparkBun host.");
+		}
+		return requestProxy.invokeCarrot({
+			carrotId,
+			method,
+			params,
+			windowId: options?.windowId,
+		}) as Promise<R>;
+	}
+	static defineRPC<Schema extends SparkBunRPCSchema>(
+		config: SparkBunRPCConfig<Schema, "webview">,
+	) {
+		return defineSparkBunRPC("webview", {
+			...config,
+			extraRequestHandlers: {
+				evaluateJavascriptWithResponse: ({ script }: { script: string }) => {
+					return new Promise((resolve) => {
+						try {
+							const resultFunction = new Function(script);
+							const result = resultFunction();
+
+							if (result instanceof Promise) {
+								result
+									.then((resolvedResult) => {
+										resolve(resolvedResult);
+									})
+									.catch((error) => {
+										console.error("bun: async script execution failed", error);
+										resolve(String(error));
+									});
+							} else {
+								resolve(result);
+							}
+						} catch (error) {
+							console.error("bun: failed to eval script", error);
+							resolve(String(error));
+						}
+					});
+				},
+			},
+		});
+	}
+}
+
+export {
+	type RPCSchema,
+	type SparkBunRPCSchema,
+	type SparkBunRPCConfig,
+	createRPC,
+	Electroview,
+	type WebviewTagElement,
+	type WebviewEventTypes,
+	type WgpuTagElement,
+	type WgpuEventTypes,
+};
+
+const SparkBun = {
+	Electroview,
+};
+
+export default SparkBun;

package/src/browser/webviewtag.ts

@@ -0,0 +1,88 @@
+import "./global.d.ts";
+
+type WebviewEventTypes =
+	| "did-navigate"
+	| "did-navigate-in-page"
+	| "did-commit-navigation"
+	| "dom-ready"
+	| "host-message"
+	| "new-window-open";
+
+/**
+ * Interface representing an <sparkbun-webview> custom element.
+ * Use this to properly type webview elements obtained via querySelector.
+ *
+ * @example
+ * const webview = document.querySelector('sparkbun-webview') as WebviewTagElement;
+ * webview.loadURL('https://example.com');
+ * webview.toggleHidden(false);
+ */
+interface WebviewTagElement extends HTMLElement {
+	// Properties
+	webviewId?: number;
+	maskSelectors: Set<string>;
+	transparent: boolean;
+	passthroughEnabled: boolean;
+	hidden: boolean;
+	hiddenMirrorMode: boolean;
+	partition: string | null;
+
+	// Attribute-backed properties (getters/setters)
+	src: string | null;
+	html: string | null;
+	preload: string | null;
+	renderer: "cef" | "native";
+
+	// Mask management
+	addMaskSelector(selector: string): void;
+	removeMaskSelector(selector: string): void;
+
+	// Navigation
+	canGoBack(): Promise<boolean>;
+	canGoForward(): Promise<boolean>;
+	goBack(): void;
+	goForward(): void;
+	reload(): void;
+	loadURL(url: string): void;
+	loadHTML(html: string): void;
+
+	// Visibility and interaction
+	toggleTransparent(transparent?: boolean, bypassState?: boolean): void;
+	togglePassthrough(enablePassthrough?: boolean, bypassState?: boolean): void;
+	toggleHidden(hidden?: boolean, bypassState?: boolean): void;
+
+	// Events - listener receives a CustomEvent with detail property
+	on(event: WebviewEventTypes, listener: (event: CustomEvent) => void): void;
+	off(event: WebviewEventTypes, listener: (event: CustomEvent) => void): void;
+	emit(event: WebviewEventTypes, detail: unknown): void;
+
+	// Dimension sync
+	syncDimensions(force?: boolean): void;
+
+	// Navigation rules
+	setNavigationRules(rules: string[]): void;
+
+	// Find in page
+	findInPage(
+		searchText: string,
+		options?: { forward?: boolean; matchCase?: boolean },
+	): void;
+	stopFindInPage(): void;
+
+	// Developer tools
+	openDevTools(): void;
+	closeDevTools(): void;
+	toggleDevTools(): void;
+
+	// JavaScript execution
+	executeJavascript(js: string): void;
+}
+
+// Augment global types so querySelector('sparkbun-webview') returns WebviewTagElement
+declare global {
+	interface HTMLElementTagNameMap {
+		"sparkbun-webview": WebviewTagElement;
+	}
+}
+
+export { type WebviewTagElement, type WebviewEventTypes };

package/src/browser/wgputag.ts

@@ -0,0 +1,48 @@
+import "./global.d.ts";
+
+type WgpuEventTypes = "ready";
+
+/**
+ * Interface representing an <sparkbun-wgpu> custom element.
+ * Use this to properly type wgpu elements obtained via querySelector.
+ *
+ * @example
+ * const wgpu = document.querySelector('sparkbun-wgpu') as WgpuTagElement;
+ * wgpu.toggleTransparent(true);
+ */
+interface WgpuTagElement extends HTMLElement {
+	// Properties
+	wgpuViewId?: number;
+	transparent: boolean;
+	passthroughEnabled: boolean;
+	hidden: boolean;
+
+	// Visibility and interaction
+	toggleTransparent(transparent?: boolean): void;
+	togglePassthrough(enablePassthrough?: boolean): void;
+	toggleHidden(hidden?: boolean): void;
+
+	// Dimension sync
+	syncDimensions(force?: boolean): void;
+
+	// Debug helper
+	runTest(): void;
+
+	// Mask management
+	addMaskSelector(selector: string): void;
+	removeMaskSelector(selector: string): void;
+
+	// Events - listener receives a CustomEvent with detail property
+	on(event: WgpuEventTypes, listener: (event: CustomEvent) => void): void;
+	off(event: WgpuEventTypes, listener: (event: CustomEvent) => void): void;
+	emit(event: WgpuEventTypes, detail: unknown): void;
+}
+
+// Augment global types so querySelector('sparkbun-wgpu') returns WgpuTagElement
+declare global {
+	interface HTMLElementTagNameMap {
+		"sparkbun-wgpu": WgpuTagElement;
+	}
+}
+
+export { type WgpuTagElement, type WgpuEventTypes };