@kbve/droid 0.0.6 → 0.1.2

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

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import {
+	DroidEventSchemas,
+	DroidReadySchema,
+	DroidFirstConnectSchema,
+	DroidDownscaleSchema,
+	DroidUpscaleSchema,
+} from './event-types';
+
+describe('DroidEventSchemas', () => {
+	it('has all expected event keys', () => {
+		const keys = Object.keys(DroidEventSchemas);
+		expect(keys).toContain('droid-first-connect');
+		expect(keys).toContain('droid-ready');
+		expect(keys).toContain('droid-mod-ready');
+		expect(keys).toContain('droid-downscale');
+		expect(keys).toContain('droid-upscale');
+		expect(keys).toContain('panel-open');
+		expect(keys).toContain('panel-close');
+		expect(keys).toContain('toast-added');
+		expect(keys).toContain('toast-removed');
+		expect(keys).toContain('tooltip-opened');
+		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 21 event types', () => {
+		expect(Object.keys(DroidEventSchemas)).toHaveLength(21);
+	});
+});
+
+describe('DroidReadySchema', () => {
+	it('accepts valid payload', () => {
+		const result = DroidReadySchema.safeParse({ timestamp: 123 });
+		expect(result.success).toBe(true);
+	});
+
+	it('rejects missing timestamp', () => {
+		const result = DroidReadySchema.safeParse({});
+		expect(result.success).toBe(false);
+	});
+
+	it('rejects non-number timestamp', () => {
+		const result = DroidReadySchema.safeParse({ timestamp: 'now' });
+		expect(result.success).toBe(false);
+	});
+});
+
+describe('DroidFirstConnectSchema', () => {
+	it('accepts valid payload', () => {
+		const result = DroidFirstConnectSchema.safeParse({
+			timestamp: 1,
+			workersFirst: { db: true, ws: false },
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it('rejects missing workersFirst', () => {
+		const result = DroidFirstConnectSchema.safeParse({ timestamp: 1 });
+		expect(result.success).toBe(false);
+	});
+});
+
+describe('DroidDownscaleSchema', () => {
+	it('accepts valid payload', () => {
+		const result = DroidDownscaleSchema.safeParse({
+			timestamp: 1,
+			level: 'minimal',
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it('rejects missing level', () => {
+		const result = DroidDownscaleSchema.safeParse({ timestamp: 1 });
+		expect(result.success).toBe(false);
+	});
+});
+
+describe('DroidUpscaleSchema', () => {
+	it('accepts valid payload', () => {
+		const result = DroidUpscaleSchema.safeParse({
+			timestamp: 1,
+			level: 'full',
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it('rejects missing timestamp', () => {
+		const result = DroidUpscaleSchema.safeParse({ level: 'full' });
+		expect(result.success).toBe(false);
+	});
+});

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

@@ -1,5 +1,10 @@
 import { z } from 'zod';
 import { PanelIdSchema } from './panel-types';
+import {
+	ToastPayloadSchema,
+	TooltipPayloadSchema,
+	ModalPayloadSchema,
+} from './ui-event-types';
 
 export const ModMetaSchema = z.object({
 	name: z.string(),
@@ -20,16 +25,121 @@ export const DroidReadySchema = z.object({
 	timestamp: z.number(),
 });
 
+export const DroidFirstConnectSchema = z.object({
+	timestamp: z.number(),
+	workersFirst: z.object({
+		db: z.boolean(),
+		ws: z.boolean(),
+	}),
+});
+
+export const DroidDownscaleSchema = z.object({
+	timestamp: z.number(),
+	level: z.string(),
+});
+
+export const DroidUpscaleSchema = z.object({
+	timestamp: z.number(),
+	level: z.string(),
+});
+
+export const AuthReadySchema = z.object({
+	timestamp: z.number(),
+	tone: z.enum(['auth', 'anon']),
+	name: z.string().optional(),
+});
+
+export const AuthErrorSchema = z.object({
+	timestamp: z.number(),
+	message: z.string(),
+});
+
+export const WorkerErrorSchema = z.object({
+	timestamp: z.number(),
+	worker: z.enum(['shared', 'db', 'ws']),
+	operation: z.string(),
+	message: z.string(),
+});
+
+export const GatewayStrategyFallbackSchema = z.object({
+	timestamp: z.number(),
+	from: z.enum(['shared-worker', 'web-worker', 'direct']),
+	to: z.enum(['shared-worker', 'web-worker', 'direct']),
+	reason: z.string(),
+});
+
+// Page lifecycle — emitted by @kbve/astro's onMount/onSwap helpers so any
+// module on the bus (mods, plugins, vanilla driver) can react to navigation
+// without knowing whether the host is using ClientRouter, native cross-doc
+// view transitions, full reloads, or bfcache restores.
+export const PageLifecycleSchema = z.object({
+	timestamp: z.number(),
+	url: z.string(),
+	source: z.enum(['initial', 'astro-swap', 'page-reveal', 'bfcache']),
+});
+
+export const PalworldLiveSnapshotSchema = z.object({
+	ts: z.number(),
+	offline: z.boolean(),
+	players: z.array(
+		z.object({
+			name: z.string(),
+			level: z.number(),
+			x: z.number(),
+			y: z.number(),
+		}),
+	),
+	bosses: z.array(
+		z.object({
+			id: z.string(),
+			x: z.number(),
+			y: z.number(),
+			defeated_at: z.number(),
+			respawn_at: z.number(),
+		}),
+	),
+	events: z.array(
+		z.object({
+			kind: z.string(),
+			class: z.string(),
+			x: z.number(),
+			y: z.number(),
+			first_seen: z.number(),
+		}),
+	),
+});
+
 export const DroidEventSchemas = {
-	'droid-ready': DroidReadySchema, 
+	'droid-first-connect': DroidFirstConnectSchema,
+	'droid-ready': DroidReadySchema,
 	'droid-mod-ready': DroidModReadySchema,
+	'droid-downscale': DroidDownscaleSchema,
+	'droid-upscale': DroidUpscaleSchema,
 	'panel-open': PanelEventSchema,
 	'panel-close': PanelEventSchema,
+	'toast-added': ToastPayloadSchema,
+	'toast-removed': ToastPayloadSchema.pick({ id: true }),
+	'tooltip-opened': TooltipPayloadSchema,
+	'tooltip-closed': TooltipPayloadSchema.pick({ id: true }),
+	'modal-opened': ModalPayloadSchema,
+	'modal-closed': ModalPayloadSchema.pick({ id: true }),
+	'auth-ready': AuthReadySchema,
+	'auth-error': AuthErrorSchema,
+	'worker-error': WorkerErrorSchema,
+	'gateway-strategy-fallback': GatewayStrategyFallbackSchema,
+	'page-mount': PageLifecycleSchema,
+	'page-swap': PageLifecycleSchema,
+	'page-hide': PageLifecycleSchema,
+	'palworld-live-snapshot': PalworldLiveSnapshotSchema,
 };
 
 export type DroidEventMap = {
-	[K in keyof typeof DroidEventSchemas]: z.infer<(typeof DroidEventSchemas)[K]>;
+	[K in keyof typeof DroidEventSchemas]: z.infer<
+		(typeof DroidEventSchemas)[K]
+	>;
 };
 
 export type EventKey = keyof DroidEventMap;
-export type EventHandler<K extends EventKey> = (payload: DroidEventMap[K]) => void;
+export type EventHandler<K extends EventKey> = (
+	payload: DroidEventMap[K],
+) => void;

package/src/lib/types/modules.ts

@@ -1,8 +1,13 @@
 import type { Remote } from 'comlink';
 
+export interface ModInitContext {
+	emitFromWorker?: (msg: unknown) => void;
+}
+
 export interface BaseModAPI {
 	getMeta(): Promise<ModMeta>;
-	init?(ctx: any): void | Promise<void>;
+	init?(ctx: ModInitContext): void | Promise<void>;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	[key: string]: any;
 }
 
@@ -31,8 +36,10 @@ export interface ModManager {
 
 export interface SupabaseModAPI extends BaseModAPI {
 	configure(url: string, key: string): Promise<void>;
-	queryTestTable(): Promise<{ data: any; error: any }>;
-	insertTest(payload: Record<string, any>): Promise<{ data: any; error: any }>;
+	queryTestTable(): Promise<{ data: unknown; error: unknown }>;
+	insertTest(
+		payload: Record<string, unknown>,
+	): Promise<{ data: unknown; error: unknown }>;
 }
 
 export type VirtualNode = {
@@ -40,7 +47,7 @@ export type VirtualNode = {
 	id?: string;
 	key?: string;
 	class?: string;
-	attrs?: Record<string, any>;
+	attrs?: Record<string, string | number | boolean>;
 	style?: Partial<CSSStyleDeclaration>;
 	children?: (string | VirtualNode)[];
-};
+};

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

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import type { VirtualNode } from './modules';
+
+// Recursive VirtualNode schema matching the type in modules.ts.
+// Validates worker-produced descriptors at runtime.
+const VirtualNodeSchema: z.ZodType<VirtualNode, VirtualNode> = z.lazy(() =>
+	z.object({
+		tag: z.string(),
+		id: z.string().optional(),
+		key: z.string().optional(),
+		class: z.string().optional(),
+		attrs: z.record(z.string(), z.any()).optional(),
+		style: z.record(z.string(), z.string()).optional(),
+		children: z.array(z.union([z.string(), VirtualNodeSchema])).optional(),
+	}),
+);
+
+// ── Toast ──
+
+export const ToastSeveritySchema = z.enum([
+	'success',
+	'warning',
+	'error',
+	'info',
+]);
+export type ToastSeverity = z.infer<typeof ToastSeveritySchema>;
+
+export const ToastPayloadSchema = z.object({
+	id: z.string(),
+	message: z.string(),
+	severity: ToastSeveritySchema,
+	duration: z.number().positive().optional(),
+	vnode: VirtualNodeSchema.optional(),
+});
+export type ToastPayload = z.infer<typeof ToastPayloadSchema>;
+
+// ── Tooltip ──
+
+export const TooltipPositionSchema = z.enum([
+	'top',
+	'bottom',
+	'left',
+	'right',
+	'auto',
+]);
+export type TooltipPosition = z.infer<typeof TooltipPositionSchema>;
+
+export const TooltipPayloadSchema = z.object({
+	id: z.string(),
+	content: z.union([z.string(), VirtualNodeSchema]).optional(),
+	position: TooltipPositionSchema.optional(),
+	anchor: z.string().optional(),
+});
+export type TooltipPayload = z.infer<typeof TooltipPayloadSchema>;
+
+// ── Modal ──
+
+export const ModalPayloadSchema = z.object({
+	id: z.string(),
+	content: VirtualNodeSchema.optional(),
+	title: z.string().optional(),
+	metadata: z.record(z.string(), z.any()).optional(),
+});
+export type ModalPayload = z.infer<typeof ModalPayloadSchema>;
+
+export { VirtualNodeSchema };