@kbve/droid 0.1.1 → 0.1.2

package/src/lib/state/sync-bus.ts

@@ -0,0 +1,109 @@
+import {
+	clearProfileCache,
+	setProfileCache,
+	type DroidProfile,
+} from './profile';
+import { clearStaffPermsCache, setStaffPermsCache } from './staff';
+
+const CHANNEL_NAME = 'kbve-droid-sync';
+
+export type SyncBusMessage =
+	| { type: 'profile-refresh'; profile: DroidProfile }
+	| { type: 'profile-clear' }
+	| {
+			type: 'staff-refresh';
+			user_id: string;
+			bitmask: number;
+	  }
+	| { type: 'staff-clear' };
+
+let channel: BroadcastChannel | null = null;
+let installed = false;
+
+function getChannel(): BroadcastChannel | null {
+	if (typeof BroadcastChannel === 'undefined') return null;
+	if (!channel) {
+		try {
+			channel = new BroadcastChannel(CHANNEL_NAME);
+		} catch {
+			channel = null;
+		}
+	}
+	return channel;
+}
+
+/**
+ * Subscribe to cross-context cache refresh messages. The service
+ * worker / shared worker / other tabs can post `SyncBusMessage`
+ * values to update the persistent stores. localStorage `storage`
+ * events already handle cross-tab sync for the persistentAtom
+ * itself; this bus exists so workers (which have no localStorage)
+ * can drive writes through.
+ */
+const noop = (): void => {
+	/* no-op cleanup */
+};
+
+export function installSyncBusListener(): () => void {
+	if (installed) return noop;
+	const bc = getChannel();
+	if (!bc) return noop;
+	installed = true;
+
+	const onMessage = (event: MessageEvent<SyncBusMessage>) => {
+		const msg = event.data;
+		if (!msg || typeof msg !== 'object') return;
+		switch (msg.type) {
+			case 'profile-refresh':
+				if (msg.profile?.user_id) setProfileCache(msg.profile);
+				break;
+			case 'profile-clear':
+				clearProfileCache();
+				break;
+			case 'staff-refresh':
+				if (msg.user_id && typeof msg.bitmask === 'number') {
+					setStaffPermsCache(msg.user_id, msg.bitmask);
+				}
+				break;
+			case 'staff-clear':
+				clearStaffPermsCache();
+				break;
+		}
+	};
+
+	bc.addEventListener('message', onMessage);
+
+	return () => {
+		bc.removeEventListener('message', onMessage);
+		installed = false;
+	};
+}
+
+export function broadcastProfileRefresh(profile: DroidProfile): void {
+	if (!profile?.user_id) return;
+	getChannel()?.postMessage({
+		type: 'profile-refresh',
+		profile,
+	} satisfies SyncBusMessage);
+}
+
+export function broadcastProfileClear(): void {
+	getChannel()?.postMessage({
+		type: 'profile-clear',
+	} satisfies SyncBusMessage);
+}
+
+export function broadcastStaffRefresh(userId: string, bitmask: number): void {
+	if (!userId) return;
+	getChannel()?.postMessage({
+		type: 'staff-refresh',
+		user_id: userId,
+		bitmask,
+	} satisfies SyncBusMessage);
+}
+
+export function broadcastStaffClear(): void {
+	getChannel()?.postMessage({
+		type: 'staff-clear',
+	} satisfies SyncBusMessage);
+}

package/src/lib/state/welcome-toast.spec.ts

@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { showWelcomeToast } from './welcome-toast';
+import { $auth, AuthPresets, resetAuth, setAuth } from './auth';
+import { $toasts } from './toasts';
+
+const SHOWN_KEY = 'kbve:welcome-shown';
+
+beforeEach(() => {
+	sessionStorage.clear();
+	$toasts.set({});
+	$auth.set({
+		tone: 'loading',
+		flags: AuthPresets.LOADING,
+		name: '',
+		username: undefined,
+		avatar: undefined,
+		id: '',
+		error: undefined,
+	});
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+});
+
+describe('showWelcomeToast', () => {
+	it('emits a "Welcome back, <name>" success toast for an authed user', () => {
+		setAuth({ tone: 'auth', name: 'Alice' });
+		showWelcomeToast();
+		const toasts = Object.values($toasts.get());
+		expect(toasts).toHaveLength(1);
+		expect(toasts[0]).toMatchObject({
+			message: 'Welcome back, Alice',
+			severity: 'success',
+		});
+		expect(sessionStorage.getItem(SHOWN_KEY)).toBe('1');
+	});
+
+	it('emits a generic info toast for an anon visitor', () => {
+		setAuth({ tone: 'anon' });
+		showWelcomeToast();
+		const toasts = Object.values($toasts.get());
+		expect(toasts[0]).toMatchObject({
+			message: 'Welcome!',
+			severity: 'info',
+		});
+	});
+
+	it('does not emit twice in the same session', () => {
+		setAuth({ tone: 'anon' });
+		showWelcomeToast();
+		showWelcomeToast();
+		expect(Object.values($toasts.get())).toHaveLength(1);
+	});
+
+	it('emits when auth resolves after a delay (subscription path)', () => {
+		showWelcomeToast();
+		expect(Object.values($toasts.get())).toHaveLength(0);
+
+		setAuth({ tone: 'auth', name: 'Bob' });
+		const toasts = Object.values($toasts.get());
+		expect(toasts).toHaveLength(1);
+		expect(toasts[0]).toMatchObject({ message: 'Welcome back, Bob' });
+	});
+
+	it('falls back to a generic toast after the 10s timeout when auth never resolves', () => {
+		vi.useFakeTimers();
+		showWelcomeToast();
+		expect(Object.values($toasts.get())).toHaveLength(0);
+
+		vi.advanceTimersByTime(10_000);
+		const toasts = Object.values($toasts.get());
+		expect(toasts).toHaveLength(1);
+		expect(toasts[0]).toMatchObject({
+			message: 'Welcome!',
+			severity: 'info',
+		});
+	});
+
+	it('marks shown without emitting when tone is error', () => {
+		setAuth({ tone: 'error', error: 'boom' });
+		showWelcomeToast();
+		expect(Object.values($toasts.get())).toHaveLength(0);
+		expect(sessionStorage.getItem(SHOWN_KEY)).toBe('1');
+	});
+
+	it('treats sessionStorage failures as not-shown without throwing', () => {
+		const original = Storage.prototype.getItem;
+		Storage.prototype.getItem = () => {
+			throw new Error('private mode');
+		};
+		try {
+			expect(() => {
+				resetAuth();
+				showWelcomeToast();
+			}).not.toThrow();
+		} finally {
+			Storage.prototype.getItem = original;
+		}
+	});
+});

package/src/lib/sw-recovery.spec.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { swRecovery } from './sw-recovery';
+
+type Reg = {
+	scriptURL: string;
+	unregister: ReturnType<typeof vi.fn>;
+};
+
+function makeReg(scriptURL: string, unregisterReturn = true): Reg {
+	return {
+		scriptURL,
+		unregister: vi.fn().mockResolvedValue(unregisterReturn),
+	};
+}
+
+function installNavigator(regs: Reg[]) {
+	const registrations = regs.map((r) => ({
+		active: { scriptURL: r.scriptURL },
+		installing: null,
+		waiting: null,
+		unregister: r.unregister,
+	})) as unknown as ServiceWorkerRegistration[];
+
+	Object.defineProperty(globalThis, 'navigator', {
+		value: {
+			serviceWorker: {
+				getRegistrations: vi.fn().mockResolvedValue(registrations),
+			},
+		},
+		configurable: true,
+		writable: true,
+	});
+}
+
+function installCaches(keys: string[]) {
+	const cacheStore: Record<string, boolean> = Object.fromEntries(
+		keys.map((k) => [k, true]),
+	);
+	(globalThis as unknown as { caches: CacheStorage }).caches = {
+		keys: vi.fn().mockResolvedValue([...keys]),
+		delete: vi.fn(async (key: string) => {
+			const had = !!cacheStore[key];
+			delete cacheStore[key];
+			return had;
+		}),
+		match: vi.fn(),
+		has: vi.fn(),
+		open: vi.fn(),
+	} as unknown as CacheStorage;
+}
+
+function clearGlobals() {
+	delete (globalThis as unknown as { navigator?: unknown }).navigator;
+	delete (globalThis as unknown as { caches?: unknown }).caches;
+}
+
+beforeEach(() => {
+	clearGlobals();
+	vi.spyOn(console, 'info').mockImplementation(vi.fn());
+	vi.spyOn(console, 'warn').mockImplementation(vi.fn());
+});
+
+afterEach(() => {
+	clearGlobals();
+	vi.restoreAllMocks();
+});
+
+describe('swRecovery', () => {
+	it('returns unsupported when navigator has no serviceWorker', async () => {
+		Object.defineProperty(globalThis, 'navigator', {
+			value: {},
+			configurable: true,
+			writable: true,
+		});
+		const result = await swRecovery();
+		expect(result.supported).toBe(false);
+		expect(result.unregistered).toEqual([]);
+	});
+
+	it('unregisters all SWs when allowedScripts is empty', async () => {
+		const stale = makeReg('https://chat.kbve.com/sw.js');
+		const other = makeReg('https://chat.kbve.com/old-sw.js');
+		installNavigator([stale, other]);
+		installCaches(['a', 'b']);
+
+		const result = await swRecovery();
+		expect(result.supported).toBe(true);
+		expect(result.unregistered).toEqual([
+			'https://chat.kbve.com/sw.js',
+			'https://chat.kbve.com/old-sw.js',
+		]);
+		expect(result.keptScripts).toEqual([]);
+		expect(result.cachesCleared).toEqual(['a', 'b']);
+		expect(stale.unregister).toHaveBeenCalledTimes(1);
+		expect(other.unregister).toHaveBeenCalledTimes(1);
+	});
+
+	it('keeps SWs whose absolute scriptURL is in allowedScripts', async () => {
+		const keep = makeReg('https://chat.kbve.com/sw.js');
+		const drop = makeReg('https://chat.kbve.com/legacy.js');
+		installNavigator([keep, drop]);
+		installCaches([]);
+
+		const result = await swRecovery({
+			allowedScripts: ['https://chat.kbve.com/sw.js'],
+		});
+		expect(result.keptScripts).toEqual(['https://chat.kbve.com/sw.js']);
+		expect(result.unregistered).toEqual([
+			'https://chat.kbve.com/legacy.js',
+		]);
+		expect(keep.unregister).not.toHaveBeenCalled();
+		expect(drop.unregister).toHaveBeenCalledTimes(1);
+	});
+
+	it('keeps SWs whose pathname matches an allowed pathname rule', async () => {
+		const keep = makeReg('https://chat.kbve.com/sw.js');
+		installNavigator([keep]);
+		installCaches([]);
+
+		const result = await swRecovery({
+			allowedScripts: ['/sw.js'],
+		});
+		expect(result.keptScripts).toEqual(['https://chat.kbve.com/sw.js']);
+		expect(keep.unregister).not.toHaveBeenCalled();
+	});
+
+	it('skips cache clearing when clearCaches is false', async () => {
+		installNavigator([makeReg('https://chat.kbve.com/old.js')]);
+		installCaches(['x']);
+
+		const result = await swRecovery({ clearCaches: false });
+		expect(result.cachesCleared).toEqual([]);
+	});
+
+	it('does not reload when nothing was removed', async () => {
+		installNavigator([]);
+		installCaches([]);
+
+		const reload = vi.fn();
+		Object.defineProperty(globalThis, 'window', {
+			value: { location: { reload } },
+			configurable: true,
+			writable: true,
+		});
+
+		const result = await swRecovery({ reloadOnCleanup: true });
+		expect(result.reloaded).toBe(false);
+		expect(reload).not.toHaveBeenCalled();
+	});
+
+	it('continues when an individual unregister rejects', async () => {
+		const ok = makeReg('https://chat.kbve.com/a.js');
+		const bad: Reg = {
+			scriptURL: 'https://chat.kbve.com/b.js',
+			unregister: vi.fn().mockRejectedValue(new Error('boom')),
+		};
+		installNavigator([ok, bad]);
+		installCaches([]);
+
+		const result = await swRecovery();
+		expect(result.unregistered).toEqual(['https://chat.kbve.com/a.js']);
+		expect(ok.unregister).toHaveBeenCalled();
+		expect(bad.unregister).toHaveBeenCalled();
+	});
+});

package/src/lib/sw-recovery.ts

@@ -0,0 +1,141 @@
+export interface SwRecoveryOptions {
+	allowedScripts?: readonly string[];
+	clearCaches?: boolean;
+	reloadOnCleanup?: boolean;
+	logPrefix?: string;
+}
+
+export interface SwRecoveryResult {
+	supported: boolean;
+	unregistered: string[];
+	keptScripts: string[];
+	cachesCleared: string[];
+	reloaded: boolean;
+}
+
+const DEFAULT_OPTS: Required<Omit<SwRecoveryOptions, 'allowedScripts'>> & {
+	allowedScripts: readonly string[];
+} = {
+	allowedScripts: [],
+	clearCaches: true,
+	reloadOnCleanup: false,
+	logPrefix: '[sw-recovery]',
+};
+
+function getScriptURL(reg: ServiceWorkerRegistration): string | null {
+	return (
+		reg.active?.scriptURL ??
+		reg.installing?.scriptURL ??
+		reg.waiting?.scriptURL ??
+		null
+	);
+}
+
+function scriptIsAllowed(
+	scriptURL: string | null,
+	allowed: readonly string[],
+): boolean {
+	if (!scriptURL) return false;
+	if (allowed.length === 0) return false;
+	return allowed.some((rule) => {
+		if (rule === scriptURL) return true;
+		try {
+			return new URL(scriptURL).pathname === rule;
+		} catch {
+			return false;
+		}
+	});
+}
+
+export async function swRecovery(
+	opts: SwRecoveryOptions = {},
+): Promise<SwRecoveryResult> {
+	const cfg = { ...DEFAULT_OPTS, ...opts };
+	const result: SwRecoveryResult = {
+		supported: false,
+		unregistered: [],
+		keptScripts: [],
+		cachesCleared: [],
+		reloaded: false,
+	};
+
+	if (
+		typeof navigator === 'undefined' ||
+		!('serviceWorker' in navigator) ||
+		typeof navigator.serviceWorker?.getRegistrations !== 'function'
+	) {
+		return result;
+	}
+
+	result.supported = true;
+
+	let registrations: readonly ServiceWorkerRegistration[] = [];
+	try {
+		registrations = await navigator.serviceWorker.getRegistrations();
+	} catch (err) {
+		console.warn(`${cfg.logPrefix} getRegistrations failed:`, err);
+		return result;
+	}
+
+	for (const reg of registrations) {
+		const scriptURL = getScriptURL(reg);
+		if (scriptIsAllowed(scriptURL, cfg.allowedScripts)) {
+			result.keptScripts.push(scriptURL as string);
+			continue;
+		}
+
+		try {
+			const ok = await reg.unregister();
+			if (ok) {
+				result.unregistered.push(scriptURL ?? '<unknown>');
+			}
+		} catch (err) {
+			console.warn(
+				`${cfg.logPrefix} unregister failed for ${scriptURL}:`,
+				err,
+			);
+		}
+	}
+
+	if (cfg.clearCaches && typeof caches !== 'undefined') {
+		try {
+			const keys = await caches.keys();
+			for (const key of keys) {
+				try {
+					const ok = await caches.delete(key);
+					if (ok) result.cachesCleared.push(key);
+				} catch (err) {
+					console.warn(
+						`${cfg.logPrefix} cache delete failed for ${key}:`,
+						err,
+					);
+				}
+			}
+		} catch (err) {
+			console.warn(`${cfg.logPrefix} caches.keys failed:`, err);
+		}
+	}
+
+	const removedAnything =
+		result.unregistered.length > 0 || result.cachesCleared.length > 0;
+
+	if (removedAnything) {
+		console.info(`${cfg.logPrefix} cleaned`, {
+			unregistered: result.unregistered,
+			kept: result.keptScripts,
+			caches: result.cachesCleared,
+		});
+	}
+
+	if (
+		cfg.reloadOnCleanup &&
+		removedAnything &&
+		typeof window !== 'undefined' &&
+		typeof window.location?.reload === 'function'
+	) {
+		result.reloaded = true;
+		window.location.reload();
+	}
+
+	return result;
+}

package/src/lib/types/event-schemas.spec.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest';
+import {
+	DroidEventSchemas,
+	DroidFirstConnectSchema,
+	DroidReadySchema,
+	AuthReadySchema,
+	AuthErrorSchema,
+	WorkerErrorSchema,
+	PageLifecycleSchema,
+	PanelEventSchema,
+	DroidDownscaleSchema,
+	DroidUpscaleSchema,
+	DroidModReadySchema,
+} from './event-types';
+
+describe('DroidEventSchemas — happy path round-trips', () => {
+	it.each([
+		['droid-ready', DroidReadySchema, { timestamp: 1 }],
+		[
+			'droid-first-connect',
+			DroidFirstConnectSchema,
+			{ timestamp: 1, workersFirst: { db: true, ws: false } },
+		],
+		[
+			'droid-mod-ready',
+			DroidModReadySchema,
+			{ meta: { id: 'x', name: 'X', version: '1.0.0' }, timestamp: 1 },
+		],
+		[
+			'droid-downscale',
+			DroidDownscaleSchema,
+			{ timestamp: 1, level: 'minimal' },
+		],
+		['droid-upscale', DroidUpscaleSchema, { timestamp: 1, level: 'full' }],
+		[
+			'panel-open',
+			PanelEventSchema,
+			{ id: 'right', payload: { foo: 'bar' } },
+		],
+		['panel-close', PanelEventSchema, { id: 'top' }],
+		[
+			'auth-ready',
+			AuthReadySchema,
+			{ timestamp: 1, tone: 'auth' as const, name: 'Alice' },
+		],
+		[
+			'auth-error',
+			AuthErrorSchema,
+			{ timestamp: 1, message: 'invalid grant' },
+		],
+		[
+			'worker-error',
+			WorkerErrorSchema,
+			{
+				timestamp: 1,
+				worker: 'ws' as const,
+				operation: 'connect',
+				message: 'closed',
+			},
+		],
+		[
+			'page-mount',
+			PageLifecycleSchema,
+			{ timestamp: 1, url: '/foo', source: 'initial' as const },
+		],
+	])('%s accepts a valid payload', (_name, schema, payload) => {
+		expect(schema.safeParse(payload).success).toBe(true);
+	});
+});
+
+describe('DroidEventSchemas — rejection cases', () => {
+	it('rejects droid-first-connect without workersFirst', () => {
+		expect(
+			DroidFirstConnectSchema.safeParse({ timestamp: 1 }).success,
+		).toBe(false);
+	});
+
+	it('rejects auth-ready with an unknown tone', () => {
+		expect(
+			AuthReadySchema.safeParse({ timestamp: 1, tone: 'staff' }).success,
+		).toBe(false);
+	});
+
+	it('rejects worker-error with an unknown worker name', () => {
+		expect(
+			WorkerErrorSchema.safeParse({
+				timestamp: 1,
+				worker: 'gateway',
+				operation: 'x',
+				message: 'y',
+			}).success,
+		).toBe(false);
+	});
+
+	it('rejects page-lifecycle with an unknown source', () => {
+		expect(
+			PageLifecycleSchema.safeParse({
+				timestamp: 1,
+				url: '/x',
+				source: 'turbolinks',
+			}).success,
+		).toBe(false);
+	});
+
+	it('rejects schemas missing the timestamp field', () => {
+		expect(DroidReadySchema.safeParse({}).success).toBe(false);
+		expect(AuthErrorSchema.safeParse({ message: 'x' }).success).toBe(false);
+	});
+});
+
+describe('DroidEventSchemas — registry contract', () => {
+	it('every key resolves to a schema with safeParse', () => {
+		for (const [key, schema] of Object.entries(DroidEventSchemas)) {
+			expect(typeof (schema as { safeParse?: unknown }).safeParse).toBe(
+				'function',
+			);
+			expect(key).toMatch(/^[a-z]+(-[a-z]+)+$/);
+		}
+	});
+});

package/src/lib/types/event-types.spec.ts

@@ -23,10 +23,13 @@ describe('DroidEventSchemas', () => {
 		expect(keys).toContain('tooltip-closed');
 		expect(keys).toContain('modal-opened');
 		expect(keys).toContain('modal-closed');
+		expect(keys).toContain('auth-ready');
+		expect(keys).toContain('auth-error');
+		expect(keys).toContain('palworld-live-snapshot');
 	});
 
-	it('has exactly 13 event types', () => {
-		expect(Object.keys(DroidEventSchemas)).toHaveLength(13);
+	it('has exactly 21 event types', () => {
+		expect(Object.keys(DroidEventSchemas)).toHaveLength(21);
 	});
 });