@kbve/droid 0.0.5 → 0.1.1

package/src/index.ts

@@ -1,21 +1,46 @@
+export type { KBVEGlobal } from './types';
+
 export * from './lib/droid';
 export * from './lib/types/bento';
+export * from './lib/types/event-types';
+export * from './lib/types/panel-types';
+export * from './lib/types/ui-event-types';
+export * from './lib/workers/events';
 export * from './lib/mod/mod-urls';
+export * from './lib/gateway';
+export * from './lib/state';
+
+export type { VirtualNode } from './lib/types/modules';
+
+// Worker-side validation
+export { validateUIMessage } from './lib/workers/validate';
+export type {
+	ValidatedWorkerMessage,
+	UIMessageType,
+} from './lib/workers/validate';
+
+// Canvas UI renderer (for direct worker usage)
+export { CanvasUIRenderer } from './lib/workers/canvas-ui-renderer';
+
+// Vite ?worker&url imports — bundles each worker as JS and returns the URL string
+import canvasWorkerUrl from './lib/workers/canvas-worker?worker&url';
+import dbWorkerUrl from './lib/workers/db-worker?worker&url';
+import wsWorkerUrl from './lib/workers/ws-worker?worker&url';
+import supabaseSharedWorkerUrl from './lib/workers/supabase-shared-worker?worker&url';
+import supabaseDbWorkerUrl from './lib/workers/supabase-db-worker?worker&url';
 
 export const workerURLs = {
-	canvasWorker: new URL(
-		'./lib/workers/canvas-worker.js',
-		import.meta.url,
-	),
-	dbWorker: new URL('./lib/workers/db-worker.js', import.meta.url),
-	wsWorker: new URL('./lib/workers/ws-worker.js', import.meta.url),
+	canvasWorker: canvasWorkerUrl,
+	dbWorker: dbWorkerUrl,
+	wsWorker: wsWorkerUrl,
+	supabaseSharedWorker: supabaseSharedWorkerUrl,
+	supabaseDbWorker: supabaseDbWorkerUrl,
 };
 
 export const workerStrings = {
-	canvasWorker: new URL(
-		'./lib/workers/canvas-worker.js',
-		import.meta.url,
-	).toString(),
-	dbWorker: new URL('./lib/workers/db-worker.js', import.meta.url).toString(),
-	wsWorker: new URL('./lib/workers/ws-worker.js', import.meta.url).toString(),
-};
+	canvasWorker: canvasWorkerUrl,
+	dbWorker: dbWorkerUrl,
+	wsWorker: wsWorkerUrl,
+	supabaseSharedWorker: supabaseSharedWorkerUrl,
+	supabaseDbWorker: supabaseDbWorkerUrl,
+};

package/src/lib/droid.spec.ts

@@ -1,26 +1,21 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { droid } from './droid';
 
 beforeEach(() => {
-	delete (window as any).kbve;
+	delete (window as unknown as { kbve?: unknown }).kbve;
 });
 
 describe('droid', () => {
-	it(
-		'should initialize and attach to window.kbve',
-		async () => {
-			const result = await droid();
+	it('should initialize and attach to window.kbve', async () => {
+		const result = await droid();
 
-			expect(result).toEqual({ initialized: true });
-			expect(window.kbve).toBeDefined();
-			expect(window.kbve?.api).toBeDefined();
-			expect(window.kbve?.i18n).toBeDefined();
-			expect(window.kbve?.uiux).toBeDefined();
-			expect(window.kbve?.ws).toBeDefined();
-			expect(window.kbve?.data).toBeDefined();
-			expect(window.kbve?.mod).toBeDefined();
-
-		},
-		10_000,
-	);
-});
+		expect(result).toEqual({ initialized: true });
+		expect(window.kbve).toBeDefined();
+		expect(window.kbve?.api).toBeDefined();
+		expect(window.kbve?.i18n).toBeDefined();
+		expect(window.kbve?.uiux).toBeDefined();
+		expect(window.kbve?.ws).toBeDefined();
+		expect(window.kbve?.data).toBeDefined();
+		expect(window.kbve?.mod).toBeDefined();
+	}, 10_000);
+});

package/src/lib/droid.ts

@@ -1,7 +1,51 @@
-export async function droid(opts?: { workerURLs?: Record<string, string> }): Promise<{ initialized: boolean }> {
+export {
+	downscale,
+	upscale,
+	getScaleLevel,
+	type DroidScaleLevel,
+} from './workers/main.js';
+
+export async function droid(opts?: {
+	workerURLs?: Record<string, string>;
+	workerRefs?: {
+		canvasWorker?: Worker;
+		dbWorker?: SharedWorker;
+		wsWorker?: SharedWorker;
+	};
+	i18nPath?: string;
+	dataPath?: string;
+	/** Maximum time (ms) to wait for worker initialization before rejecting. Default: no timeout. */
+	initTimeout?: number;
+}): Promise<{ initialized: boolean }> {
 	console.log('[DROID]: droid<T>');
+
 	const { main } = await import('./workers/main.js');
-	await main({ workerURLs: opts?.workerURLs });
-	console.log('[DROID]: droid<T> => await WorkerURLs');
+
+	const initPromise = main({
+		workerURLs: opts?.workerURLs,
+		workerRefs: opts?.workerRefs,
+		i18nPath: opts?.i18nPath,
+		dataPath: opts?.dataPath,
+	});
+
+	if (opts?.initTimeout && opts.initTimeout > 0) {
+		const timeout = new Promise<never>((_, reject) =>
+			setTimeout(
+				() =>
+					reject(
+						new Error(
+							`[DROID] Worker init timed out after ${opts.initTimeout}ms`,
+						),
+					),
+				opts.initTimeout,
+			),
+		);
+		await Promise.race([initPromise, timeout]);
+	} else {
+		await initPromise;
+	}
+
+	console.log('[DROID]: droid<T> => await WorkerRefs + URLs');
+
 	return { initialized: true };
-}
+}

package/src/lib/gateway/SupabaseGateway.ts

@@ -0,0 +1,183 @@
+// Unified gateway for Supabase operations with automatic strategy selection
+
+import type {
+	ISupabaseStrategy,
+	SelectOptions,
+	SessionResponse,
+	WebSocketStatus,
+	StrategyType,
+	GatewayConfig,
+} from './types';
+import {
+	detectCapabilities,
+	selectStrategy,
+	logCapabilities,
+	getStrategyDescription,
+} from './capabilities';
+import { SharedWorkerStrategy } from './strategies/SharedWorkerStrategy';
+import { WebWorkerStrategy } from './strategies/WebWorkerStrategy';
+import { DirectStrategy } from './strategies/DirectStrategy';
+
+// Vite ?worker&url imports — bundles workers as JS and returns their URL
+import defaultSharedWorkerUrl from '../workers/supabase-shared-worker?worker&url';
+import defaultDbWorkerUrl from '../workers/supabase-db-worker?worker&url';
+
+/**
+ * SupabaseGateway: Unified interface for all Supabase operations
+ *
+ * Automatically selects the best strategy based on browser capabilities:
+ * 1. SharedWorker + DB Worker Pool (desktop: Chrome, Firefox, Edge)
+ * 2. WebSocket Worker + DB Worker Pool (Android, Safari)
+ * 3. Direct/Main thread (fallback)
+ *
+ * All strategies implement the same interface, so application code is unchanged.
+ */
+export class SupabaseGateway implements ISupabaseStrategy {
+	private strategy: ISupabaseStrategy;
+	private strategyType: StrategyType;
+
+	constructor(config: GatewayConfig = {}) {
+		const capabilities = detectCapabilities();
+		logCapabilities(capabilities);
+
+		this.strategyType =
+			config.forceStrategy || selectStrategy(capabilities);
+		console.log(
+			`[SupabaseGateway] Selected strategy: ${getStrategyDescription(this.strategyType)}`,
+		);
+
+		const poolSize = config.poolSize ?? 3;
+		const workerUrls = config.workerUrls ?? {};
+
+		switch (this.strategyType) {
+			case 'shared-worker': {
+				const sharedUrl =
+					workerUrls.sharedWorker ?? defaultSharedWorkerUrl;
+				const dbUrl = workerUrls.dbWorker ?? defaultDbWorkerUrl;
+				this.strategy = new SharedWorkerStrategy(
+					sharedUrl,
+					dbUrl,
+					poolSize,
+				);
+				break;
+			}
+			case 'web-worker': {
+				const wsUrl =
+					workerUrls.webSocketWorker ?? defaultSharedWorkerUrl;
+				const dbUrl = workerUrls.dbWorker ?? defaultDbWorkerUrl;
+				this.strategy = new WebWorkerStrategy(wsUrl, dbUrl, poolSize);
+				break;
+			}
+			case 'direct':
+				this.strategy = new DirectStrategy();
+				break;
+		}
+	}
+
+	getStrategyType(): StrategyType {
+		return this.strategyType;
+	}
+
+	getStrategyDescription(): string {
+		return getStrategyDescription(this.strategyType);
+	}
+
+	// Delegate all methods to the selected strategy
+
+	init(
+		url: string,
+		anonKey: string,
+		options?: Record<string, unknown>,
+	): Promise<SessionResponse> {
+		return this.strategy.init(url, anonKey, options);
+	}
+
+	on(event: string, callback: (payload: unknown) => void): () => void {
+		return this.strategy.on(event, callback);
+	}
+
+	getSession(): Promise<SessionResponse> {
+		return this.strategy.getSession();
+	}
+
+	signInWithPassword(
+		email: string,
+		password: string,
+	): Promise<SessionResponse> {
+		return this.strategy.signInWithPassword(email, password);
+	}
+
+	signOut(): Promise<void> {
+		return this.strategy.signOut();
+	}
+
+	select(table: string, opts?: SelectOptions): Promise<unknown[]> {
+		return this.strategy.select(table, opts);
+	}
+
+	insert(
+		table: string,
+		data: Record<string, unknown> | Record<string, unknown>[],
+	): Promise<unknown[]> {
+		return this.strategy.insert(table, data);
+	}
+
+	update(
+		table: string,
+		data: Record<string, unknown>,
+		match: Record<string, unknown>,
+	): Promise<unknown[]> {
+		return this.strategy.update(table, data, match);
+	}
+
+	upsert(
+		table: string,
+		data: Record<string, unknown> | Record<string, unknown>[],
+	): Promise<unknown[]> {
+		return this.strategy.upsert(table, data);
+	}
+
+	delete(table: string, match: Record<string, unknown>): Promise<unknown[]> {
+		return this.strategy.delete(table, match);
+	}
+
+	rpc(fn: string, args?: Record<string, unknown>): Promise<unknown> {
+		return this.strategy.rpc(fn, args);
+	}
+
+	subscribePostgres(
+		key: string,
+		params: Record<string, unknown>,
+		callback: (payload: unknown) => void,
+	): () => void {
+		return this.strategy.subscribePostgres(key, params, callback);
+	}
+
+	connectWebSocket(wsUrl?: string): Promise<WebSocketStatus> {
+		return this.strategy.connectWebSocket(wsUrl);
+	}
+
+	disconnectWebSocket(): Promise<void> {
+		return this.strategy.disconnectWebSocket();
+	}
+
+	sendWebSocketMessage(data: unknown): Promise<void> {
+		return this.strategy.sendWebSocketMessage(data);
+	}
+
+	getWebSocketStatus(): Promise<WebSocketStatus> {
+		return this.strategy.getWebSocketStatus();
+	}
+
+	onWebSocketMessage(callback: (message: unknown) => void): () => void {
+		return this.strategy.onWebSocketMessage(callback);
+	}
+
+	onWebSocketStatus(callback: (status: WebSocketStatus) => void): () => void {
+		return this.strategy.onWebSocketStatus(callback);
+	}
+
+	terminate() {
+		this.strategy.terminate();
+	}
+}

package/src/lib/gateway/WorkerCommunication.ts

@@ -0,0 +1,132 @@
+// Unified communication layer for all workers (SharedWorker, WebWorker, main thread)
+// Uses BroadcastChannel for real-time events
+
+import type { BroadcastEvent } from './types';
+
+/**
+ * WorkerCommunication: Unified communication layer for workers
+ *
+ * Features:
+ * - BroadcastChannel for real-time events
+ * - Works in SharedWorker, WebWorker, and main thread
+ *
+ * Note: This layer does NOT open IndexedDB. The SharedWorker is the single
+ * writer to the auth database (sb-auth-v2). All other contexts receive
+ * auth state via BroadcastChannel or postMessage.
+ */
+export class WorkerCommunication {
+	private bc: BroadcastChannel | null = null;
+	private listeners = new Map<string, Set<(payload: unknown) => void>>();
+	private channelName: string;
+
+	constructor(channelName = 'supabase_events') {
+		this.channelName = channelName;
+		this.initBroadcastChannel();
+	}
+
+	private initBroadcastChannel() {
+		try {
+			if (typeof BroadcastChannel !== 'undefined') {
+				this.bc = new BroadcastChannel(this.channelName);
+				this.bc.onmessage = (e: MessageEvent) =>
+					this.handleBroadcast(e.data);
+			}
+		} catch (err) {
+			console.error(
+				'[WorkerCommunication] Failed to initialize BroadcastChannel:',
+				err,
+			);
+		}
+	}
+
+	/**
+	 * Broadcast an event to all workers and tabs
+	 */
+	broadcast(event: BroadcastEvent) {
+		if (this.bc) {
+			try {
+				this.bc.postMessage(event);
+			} catch (err) {
+				console.error('[WorkerCommunication] Broadcast failed:', err);
+			}
+		}
+	}
+
+	private handleBroadcast(event: BroadcastEvent) {
+		const { type, key } = event;
+
+		if (type === 'realtime' && key) {
+			this.emit(`realtime:${key}`, event.payload);
+		} else {
+			this.emit(type, event);
+		}
+	}
+
+	/**
+	 * Subscribe to events (local and broadcast)
+	 */
+	on(event: string, callback: (payload: unknown) => void): () => void {
+		if (!this.listeners.has(event)) {
+			this.listeners.set(event, new Set());
+		}
+		this.listeners.get(event)?.add(callback);
+
+		return () => {
+			const set = this.listeners.get(event);
+			if (set) {
+				set.delete(callback);
+				if (set.size === 0) {
+					this.listeners.delete(event);
+				}
+			}
+		};
+	}
+
+	private emit(event: string, payload: unknown) {
+		const listeners = this.listeners.get(event);
+		if (listeners) {
+			listeners.forEach((cb) => {
+				try {
+					cb(payload);
+				} catch (err) {
+					console.error(
+						`[WorkerCommunication] Listener error for ${event}:`,
+						err,
+					);
+				}
+			});
+		}
+	}
+
+	/**
+	 * Check if BroadcastChannel is available
+	 */
+	hasBroadcastChannel(): boolean {
+		return this.bc !== null;
+	}
+
+	/**
+	 * Close connections
+	 */
+	close() {
+		if (this.bc) {
+			this.bc.close();
+			this.bc = null;
+		}
+		this.listeners.clear();
+	}
+}
+
+/**
+ * Create a singleton instance for use across workers
+ */
+let _instance: WorkerCommunication | null = null;
+
+export function getWorkerCommunication(
+	channelName?: string,
+): WorkerCommunication {
+	if (!_instance) {
+		_instance = new WorkerCommunication(channelName);
+	}
+	return _instance;
+}