yaxa-svelte 2.4.0 → 2.5.0

package/README.md

@@ -295,7 +295,8 @@ export const GET = createApiDocsHandler({
 });
 ```
 
-- **Interactive Reference UI:** Open `/api/docs` in your browser.
+- **Interactive Reference UI:** Open `/api/docs` in your browser (supports `?theme=scalar` (default), `?theme=swagger`, or `?theme=redoc`).
+- **Live Demo:** Try it live on [yaxa.vercel.app/api/docs](https://yaxa.vercel.app/api/docs).
 - **Raw OpenAPI 3.1 JSON:** Request `/api/docs?format=json` or send `Accept: application/json` for SDK generation.
 
 ---
@@ -345,22 +346,68 @@ export const GET = async () => {
 
 ---
 
+## 📡 Real-Time Server-Sent Events (`yaxaSSE`, `broadcast`, & `useSSE`)
+
+Zero-infrastructure real-time communication across serverless and Node.js without third-party subscriptions. Features declarative SSE streaming, automatic keep-alive heartbeats, multi-channel pub/sub broadcasting, and a reactive Svelte 5 client rune with exponential reconnect backoff:
+
+```ts
+// 1. Server-Sent Events Endpoint (src/routes/api/events/+server.ts)
+import { yaxaSSE, requireAuth } from 'yaxa-svelte/server';
+
+export const GET = yaxaSSE({
+	guards: [requireAuth()],
+	channel: (event) => `org:${event.locals.orgId}`,
+	keepAliveIntervalMs: 15000, // Heartbeat ping prevents proxy & Vercel timeouts
+	onConnect: ({ send, user }) => {
+		send('connected', { userId: user.id });
+	}
+});
+
+// 2. Publish from anywhere (Endpoints, Webhooks, Background Workers)
+import { broadcast } from 'yaxa-svelte/server';
+
+await broadcast(`org:${orgId}`, 'invoice.settled', {
+	invoiceId: 'inv_4982',
+	amount: 29.0
+});
+```
+
+```svelte
+<!-- 3. Reactive Svelte 5 Client Rune -->
+<script lang="ts">
+	import { useSSE } from 'yaxa-svelte';
+
+	const stream = useSSE('/api/events');
+
+	// Typed event listeners with automatic cleanup
+	stream.on('invoice.settled', (data) => {
+		toast.success(`Payment settled: $${data.amount}`);
+	});
+</script>
+
+<Badge color={stream.connected ? 'success' : 'neutral'}>
+	{stream.connected ? 'Live Stream' : 'Connecting...'}
+</Badge>
+```
+
+---
+
 ## 📦 Subpath Exports Architecture
 
-| Subpath                 | Description                                                                                                                                                                                |
-| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Theme System & Composables (`useGate`, `useUpload`, `useToast`, `useClipboard`, etc.)                                                      |
-| `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />`                                                  |
-| `yaxa-svelte/server`    | `yaxaEndpoint` Pipeline, Declarative Guards, OpenAPI 3.1 & Scalar Docs, RFC 7807, Background Jobs (`enqueueJob`, `createJobRunner`), `eventBus`, Server Hooks, Drizzle DB, Storage & Email |
-| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)                                                               |
-| `yaxa-svelte/db`        | Multi-dialect Drizzle ORM clients & schemas for Neon (PostgreSQL) and Turso (SQLite/LibSQL)                                                                                                |
-| `yaxa-svelte/polar`     | Polar.sh billing, customer portal sessions, and webhook synchronization                                                                                                                    |
-| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                                                                           |
-| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                                                                   |
-| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                                                                                |
-| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                                                                             |
-| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                                                                  |
-| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                                                                           |
+| Subpath                 | Description                                                                                                                                                                                                                |
+| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Theme System & Composables (`useGate`, `useUpload`, `useSSE`, `useToast`, `useClipboard`, etc.)                                                                            |
+| `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />`                                                                                  |
+| `yaxa-svelte/server`    | `yaxaEndpoint` Pipeline, Declarative Guards, OpenAPI 3.1 & Scalar Docs, RFC 7807, Real-Time SSE (`yaxaSSE`, `broadcast`), Background Jobs (`enqueueJob`, `createJobRunner`), `eventBus`, Server Hooks, DB, Storage & Email |
+| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)                                                                                               |
+| `yaxa-svelte/db`        | Multi-dialect Drizzle ORM clients & schemas for Neon (PostgreSQL) and Turso (SQLite/LibSQL)                                                                                                                                |
+| `yaxa-svelte/polar`     | Polar.sh billing, customer portal sessions, and webhook synchronization                                                                                                                                                    |
+| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                                                                                                           |
+| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                                                                                                   |
+| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                                                                                                                |
+| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                                                                                                             |
+| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                                                                                                  |
+| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                                                                                                           |
 
 ---
 

package/dist/composables/useSSE.svelte.d.ts

@@ -0,0 +1,53 @@
+export type SSEStatus = 'idle' | 'connecting' | 'connected' | 'error' | 'closed';
+export interface UseSSEOptions {
+    /** Whether the SSE connection is active (defaults to true) */
+    enabled?: boolean;
+    /** Whether to send credentials/cookies with cross-origin requests */
+    withCredentials?: boolean;
+    /** Enable automatic reconnection on disconnect/error (defaults to true) */
+    autoReconnect?: boolean;
+    /** Maximum reconnection attempts before stopping (defaults to 10) */
+    maxRetries?: number;
+    /** Base reconnect delay in ms before exponential backoff (defaults to 1,000ms) */
+    baseDelayMs?: number;
+    /** Maximum delay between reconnect attempts in ms (defaults to 30,000ms) */
+    maxDelayMs?: number;
+    /** Callback invoked when the connection opens */
+    onOpen?: () => void;
+    /** Callback invoked on error */
+    onError?: (err: Event) => void;
+    /** Callback invoked when any message is received */
+    onMessage?: (data: any, event: MessageEvent) => void;
+}
+export type SSEEventHandler<T = any> = (data: T, event: MessageEvent) => void;
+export interface SSEResult {
+    readonly status: SSEStatus;
+    readonly connected: boolean;
+    readonly connecting: boolean;
+    readonly data: any;
+    readonly lastEvent: string | null;
+    readonly error: any;
+    on: <T = any>(event: string, handler: SSEEventHandler<T>) => () => void;
+    close: () => void;
+    reconnect: () => void;
+}
+/**
+ * Idiomatic Svelte 5 Composable Rune for Server-Sent Events (SSE).
+ * Provides automatic reconnect with jitter, typed event subscribers, and automatic teardown.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useSSE } from 'yaxa-svelte';
+ *
+ *   const stream = useSSE('/api/events');
+ *
+ *   stream.on('order.created', (order) => {
+ *     console.log('New order received:', order);
+ *   });
+ * </script>
+ *
+ * <p>Status: {stream.connected ? 'Live' : 'Connecting...'}</p>
+ * ```
+ */
+export declare function useSSE(url: string | (() => string), options?: UseSSEOptions): SSEResult;

package/dist/composables/useSSE.svelte.js

@@ -0,0 +1,209 @@
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+/**
+ * Idiomatic Svelte 5 Composable Rune for Server-Sent Events (SSE).
+ * Provides automatic reconnect with jitter, typed event subscribers, and automatic teardown.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useSSE } from 'yaxa-svelte';
+ *
+ *   const stream = useSSE('/api/events');
+ *
+ *   stream.on('order.created', (order) => {
+ *     console.log('New order received:', order);
+ *   });
+ * </script>
+ *
+ * <p>Status: {stream.connected ? 'Live' : 'Connecting...'}</p>
+ * ```
+ */
+export function useSSE(url, options = {}) {
+    const { enabled = true, withCredentials = false, autoReconnect = true, maxRetries = 10, baseDelayMs = 1000, maxDelayMs = 30000, onOpen, onError, onMessage } = options;
+    let status = $state('idle');
+    let data = $state(null);
+    let lastEvent = $state(null);
+    let error = $state(null);
+    const connected = $derived(status === 'connected');
+    const connecting = $derived(status === 'connecting');
+    const listeners = new SvelteMap();
+    let es = null;
+    let reconnectTimer = null;
+    let retryCount = 0;
+    let manualClose = false;
+    function parseEventData(raw) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    function dispatchToListeners(eventType, parsed, rawEvent) {
+        const handlers = listeners.get(eventType);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(parsed, rawEvent);
+                }
+                catch (err) {
+                    console.error(`[useSSE Handler Error] Event '${eventType}':`, err);
+                }
+            }
+        }
+    }
+    function cleanupConnection() {
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+        if (es) {
+            es.close();
+            es = null;
+        }
+    }
+    function scheduleReconnect(targetUrl) {
+        if (manualClose || !autoReconnect || retryCount >= maxRetries) {
+            status = 'closed';
+            return;
+        }
+        // Exponential backoff with jitter
+        const delay = Math.min(maxDelayMs, baseDelayMs * Math.pow(1.5, retryCount) + Math.random() * 500);
+        retryCount++;
+        status = 'connecting';
+        reconnectTimer = setTimeout(() => {
+            connect(targetUrl);
+        }, delay);
+    }
+    function connect(targetUrl) {
+        cleanupConnection();
+        if (typeof window === 'undefined' || typeof EventSource === 'undefined') {
+            status = 'idle';
+            return;
+        }
+        status = 'connecting';
+        manualClose = false;
+        try {
+            const source = new EventSource(targetUrl, { withCredentials });
+            es = source;
+            source.onopen = () => {
+                status = 'connected';
+                retryCount = 0;
+                error = null;
+                onOpen?.();
+            };
+            source.onmessage = (event) => {
+                const parsed = parseEventData(event.data);
+                data = parsed;
+                lastEvent = 'message';
+                onMessage?.(parsed, event);
+                dispatchToListeners('message', parsed, event);
+            };
+            source.onerror = (err) => {
+                status = 'error';
+                error = err;
+                onError?.(err);
+                cleanupConnection();
+                scheduleReconnect(targetUrl);
+            };
+            // Re-attach custom event listeners
+            for (const [eventName] of listeners) {
+                if (eventName !== 'message') {
+                    source.addEventListener(eventName, (event) => {
+                        const parsed = parseEventData(event.data);
+                        data = parsed;
+                        lastEvent = eventName;
+                        dispatchToListeners(eventName, parsed, event);
+                    });
+                }
+            }
+        }
+        catch (err) {
+            status = 'error';
+            error = err;
+            scheduleReconnect(targetUrl);
+        }
+    }
+    function close() {
+        manualClose = true;
+        status = 'closed';
+        cleanupConnection();
+    }
+    function reconnect() {
+        manualClose = false;
+        retryCount = 0;
+        const targetUrl = typeof url === 'function' ? url() : url;
+        connect(targetUrl);
+    }
+    function on(event, handler) {
+        let handlers = listeners.get(event);
+        if (!handlers) {
+            handlers = new SvelteSet();
+            listeners.set(event, handlers);
+            // If EventSource is currently connected, register native listener for named event
+            if (es && event !== 'message') {
+                es.addEventListener(event, (evt) => {
+                    const parsed = parseEventData(evt.data);
+                    data = parsed;
+                    lastEvent = event;
+                    dispatchToListeners(event, parsed, evt);
+                });
+            }
+        }
+        handlers.add(handler);
+        return () => {
+            handlers?.delete(handler);
+            if (handlers?.size === 0) {
+                listeners.delete(event);
+            }
+        };
+    }
+    // Svelte 5 effect for automated lifecycle management if called inside a component/effect root
+    try {
+        $effect(() => {
+            const targetUrl = typeof url === 'function' ? url() : url;
+            if (enabled && targetUrl) {
+                connect(targetUrl);
+            }
+            else {
+                close();
+            }
+            return () => {
+                manualClose = true;
+                cleanupConnection();
+            };
+        });
+    }
+    catch {
+        // When called outside an effect root (e.g. In unit tests), connect directly
+        if (enabled) {
+            const targetUrl = typeof url === 'function' ? url() : url;
+            if (targetUrl) {
+                connect(targetUrl);
+            }
+        }
+    }
+    return {
+        get status() {
+            return status;
+        },
+        get connected() {
+            return connected;
+        },
+        get connecting() {
+            return connecting;
+        },
+        get data() {
+            return data;
+        },
+        get lastEvent() {
+            return lastEvent;
+        },
+        get error() {
+            return error;
+        },
+        on,
+        close,
+        reconnect
+    };
+}

package/dist/composables/useSSE.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/composables/useSSE.test.js

@@ -0,0 +1,122 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { useSSE } from './useSSE.svelte';
+class MockEventSource {
+    url;
+    withCredentials;
+    onopen = null;
+    onmessage = null;
+    onerror = null;
+    listeners = new Map();
+    readyState = 0;
+    static instances = [];
+    constructor(url, init) {
+        this.url = url;
+        this.withCredentials = init?.withCredentials;
+        MockEventSource.instances.push(this);
+    }
+    addEventListener(type, handler) {
+        let handlers = this.listeners.get(type);
+        if (!handlers) {
+            handlers = new Set();
+            this.listeners.set(type, handlers);
+        }
+        handlers.add(handler);
+    }
+    removeEventListener(type, handler) {
+        this.listeners.get(type)?.delete(handler);
+    }
+    close() {
+        this.readyState = 2;
+    }
+    simulateOpen() {
+        this.readyState = 1;
+        this.onopen?.();
+    }
+    simulateMessage(data, type = 'message') {
+        const rawData = typeof data === 'object' ? JSON.stringify(data) : String(data);
+        const evt = { data: rawData, type };
+        if (type === 'message') {
+            this.onmessage?.(evt);
+        }
+        const handlers = this.listeners.get(type);
+        if (handlers) {
+            for (const handler of handlers) {
+                handler(evt);
+            }
+        }
+    }
+    simulateError(err = new Event('error')) {
+        this.onerror?.(err);
+    }
+}
+describe('useSSE Composable Rune', () => {
+    beforeEach(() => {
+        MockEventSource.instances = [];
+        vi.stubGlobal('EventSource', MockEventSource);
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.restoreAllMocks();
+    });
+    it('initializes with connecting or connected state when EventSource exists', () => {
+        const sse = useSSE('/api/events', { enabled: true });
+        expect(sse.status).toBe('connecting');
+        expect(sse.connecting).toBe(true);
+        expect(sse.connected).toBe(false);
+        expect(MockEventSource.instances.length).toBe(1);
+        const instance = MockEventSource.instances[0];
+        expect(instance.url).toBe('/api/events');
+        instance.simulateOpen();
+        expect(sse.status).toBe('connected');
+        expect(sse.connected).toBe(true);
+        expect(sse.connecting).toBe(false);
+    });
+    it('handles message events and parses JSON data reactively', () => {
+        const onMessage = vi.fn();
+        const sse = useSSE('/api/events', { onMessage });
+        const instance = MockEventSource.instances[0];
+        instance.simulateOpen();
+        instance.simulateMessage({ user: 'Alice', score: 100 });
+        expect(sse.data).toEqual({ user: 'Alice', score: 100 });
+        expect(sse.lastEvent).toBe('message');
+        expect(onMessage).toHaveBeenCalledWith({ user: 'Alice', score: 100 }, expect.any(Object));
+    });
+    it('subscribes to custom named events via .on(eventName, handler)', () => {
+        const sse = useSSE('/api/events');
+        const instance = MockEventSource.instances[0];
+        instance.simulateOpen();
+        const orderHandler = vi.fn();
+        const unsubscribe = sse.on('order.paid', orderHandler);
+        instance.simulateMessage({ orderId: 'ord_99', total: 29.5 }, 'order.paid');
+        expect(orderHandler).toHaveBeenCalledTimes(1);
+        expect(orderHandler).toHaveBeenCalledWith({ orderId: 'ord_99', total: 29.5 }, expect.any(Object));
+        expect(sse.lastEvent).toBe('order.paid');
+        // Test unsubscribe
+        unsubscribe();
+        instance.simulateMessage({ orderId: 'ord_100', total: 10 }, 'order.paid');
+        expect(orderHandler).toHaveBeenCalledTimes(1);
+    });
+    it('closes the connection cleanly on .close()', () => {
+        const sse = useSSE('/api/events');
+        const instance = MockEventSource.instances[0];
+        instance.simulateOpen();
+        sse.close();
+        expect(sse.status).toBe('closed');
+        expect(sse.connected).toBe(false);
+        expect(instance.readyState).toBe(2);
+    });
+    it('reconnects when .reconnect() is invoked', () => {
+        const sse = useSSE('/api/events');
+        expect(MockEventSource.instances.length).toBe(1);
+        sse.close();
+        expect(sse.status).toBe('closed');
+        sse.reconnect();
+        expect(MockEventSource.instances.length).toBe(2);
+        expect(sse.status).toBe('connecting');
+    });
+    it('stays idle when enabled is false', () => {
+        const sse = useSSE('/api/events', { enabled: false });
+        expect(sse.status).toBe('idle');
+        expect(MockEventSource.instances.length).toBe(0);
+    });
+});

package/dist/index.d.ts

@@ -156,6 +156,8 @@ export { useFormAction } from './composables/useFormAction.svelte';
 export type { UseFormActionOptions } from './composables/useFormAction.svelte';
 export { useIdle } from './composables/useIdle.svelte';
 export type { UseIdleOptions } from './composables/useIdle.svelte';
+export { useSSE } from './composables/useSSE.svelte';
+export type { SSEStatus, UseSSEOptions, SSEEventHandler, SSEResult } from './composables/useSSE.svelte';
 export { default as ThemeStudio } from './components/theme/ThemeStudio.svelte';
 export type { ThemeStudioProps } from './components/theme/ThemeStudio.svelte';
 export { theme, themeInitScript, ACCENT_PALETTES, NEUTRAL_PALETTES, FONT_PRESETS, RADIUS_PRESETS, FONT_SIZE_PRESETS, DEFAULT_CHART_COLORS } from './theme/theme.svelte';

package/dist/index.js

@@ -103,6 +103,7 @@ export { Sortable, useSortable } from './composables/useSortable.svelte';
 export { useDataTable } from './composables/useDataTable.svelte';
 export { useFormAction } from './composables/useFormAction.svelte';
 export { useIdle } from './composables/useIdle.svelte';
+export { useSSE } from './composables/useSSE.svelte';
 // Theming & Theme Studio
 export { default as ThemeStudio } from './components/theme/ThemeStudio.svelte';
 export { theme, themeInitScript, ACCENT_PALETTES, NEUTRAL_PALETTES, FONT_PRESETS, RADIUS_PRESETS, FONT_SIZE_PRESETS, DEFAULT_CHART_COLORS } from './theme/theme.svelte';

package/dist/server/index.d.ts

@@ -28,3 +28,5 @@ export { generateOpenApiSpec, createApiDocsHandler, createApiRegistry, globalApi
 export type { OpenApiSpec31, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, GenerateOpenApiOptions, ApiDocsOptions, ApiDocsTheme, EndpointLike, EndpointMap } from './openapi/index';
 export { enqueueJob, defineWorker, createJobRunner, eventBus, EventBus, parseJobDelay } from './jobs/index';
 export type { JobRecord, JobDelay, EnqueueJobOptions, WorkerContext, WorkerHandler, WorkerDefinition, JobRunnerOptions, JobBatchResult, JobRunner, EventHandler, EventSubscription, IEventBus } from './jobs/index';
+export { yaxaSSE, formatSSEFrame, broadcast, createBroadcaster, globalBroadcaster, MemoryBroadcaster } from './realtime/index';
+export type { SSEMessage, SSEClientContext, YaxaSSEOptions, BroadcastMessage, BroadcastSubscriber, Broadcaster } from './realtime/index';

package/dist/server/index.js

@@ -24,3 +24,5 @@ export { yaxaEndpoint, createProblemDetails, problemResponse, isProblemDetails,
 export { generateOpenApiSpec, createApiDocsHandler, createApiRegistry, globalApiRegistry, convertToJsonSchema } from './openapi/index';
 // Embedded Background Workflows, Job Queue & Domain Events (Milestone 6)
 export { enqueueJob, defineWorker, createJobRunner, eventBus, EventBus, parseJobDelay } from './jobs/index';
+// Adapter-Agnostic Real-Time Abstractions & Server-Sent Events (Milestone 5)
+export { yaxaSSE, formatSSEFrame, broadcast, createBroadcaster, globalBroadcaster, MemoryBroadcaster } from './realtime/index';

package/dist/server/openapi/handler.js

@@ -78,10 +78,12 @@ function renderRedocHtml(specJson, title) {
  * page (Scalar, Swagger UI, or Redoc) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
  */
 export function createApiDocsHandler(options = {}) {
-    const theme = options.theme || 'scalar';
+    const defaultTheme = options.theme || 'scalar';
     return async (event) => {
         const { url, request } = event;
         const format = url.searchParams.get('format');
+        const themeQuery = url.searchParams.get('theme');
+        const activeTheme = themeQuery && ['scalar', 'swagger', 'redoc'].includes(themeQuery) ? themeQuery : defaultTheme;
         const acceptHeader = request.headers.get('accept') || '';
         const spec = generateOpenApiSpec(options);
         // If caller requests JSON via query param, accept header, or path ending in .json
@@ -98,10 +100,10 @@ export function createApiDocsHandler(options = {}) {
         // Render Interactive HTML Docs
         const specJson = JSON.stringify(spec);
         let html;
-        if (theme === 'swagger') {
+        if (activeTheme === 'swagger') {
             html = renderSwaggerHtml(specJson, spec.info.title);
         }
-        else if (theme === 'redoc') {
+        else if (activeTheme === 'redoc') {
             html = renderRedocHtml(specJson, spec.info.title);
         }
         else {

package/dist/server/openapi/openapi.test.js

@@ -216,4 +216,17 @@ describe('createApiDocsHandler Endpoint', () => {
         expect(html).toContain('redoc.standalone.js');
         expect(html).toContain('redoc-container');
     });
+    it('allows overriding theme dynamically via ?theme query parameter', async () => {
+        const handler = createApiDocsHandler({
+            title: 'Dynamic Theme Test',
+            theme: 'scalar'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs?theme=swagger'
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        const html = await response.text();
+        expect(html).toContain('swagger-ui-dist');
+    });
 });

package/dist/server/realtime/broadcaster.d.ts

@@ -0,0 +1,31 @@
+import type { Broadcaster, BroadcastSubscriber } from './types';
+/**
+ * In-memory channel broadcaster suitable for single-node deployments and local development.
+ * Supports zero external dependencies with complete error isolation across subscribers.
+ */
+export declare class MemoryBroadcaster implements Broadcaster {
+    private channels;
+    publish<T = unknown>(channel: string, event: string, payload: T, id?: string): void;
+    subscribe<T = unknown>(channel: string, subscriber: BroadcastSubscriber<T>): () => void;
+    unsubscribe<T = unknown>(channel: string, subscriber: BroadcastSubscriber<T>): void;
+    subscriberCount(channel: string): number;
+    clear(): void;
+}
+/**
+ * Global default broadcaster instance.
+ */
+export declare const globalBroadcaster: Broadcaster;
+/**
+ * Creates a broadcaster instance or wraps a custom adapter.
+ */
+export declare function createBroadcaster(customAdapter?: Broadcaster): Broadcaster;
+/**
+ * Broadcast an event to all connected clients on a channel.
+ * Callable from any endpoint, server action, webhook, or background worker.
+ *
+ * @example
+ * ```ts
+ * await broadcast(`org:${orgId}`, 'invoice.paid', { id: 'inv_123', total: 4900 });
+ * ```
+ */
+export declare function broadcast<T = unknown>(channel: string, event: string, payload: T, id?: string, broadcasterInstance?: Broadcaster): Promise<void>;

package/dist/server/realtime/broadcaster.js

@@ -0,0 +1,76 @@
+/**
+ * In-memory channel broadcaster suitable for single-node deployments and local development.
+ * Supports zero external dependencies with complete error isolation across subscribers.
+ */
+export class MemoryBroadcaster {
+    channels = new Map();
+    publish(channel, event, payload, id) {
+        const subscribers = this.channels.get(channel);
+        if (!subscribers || subscribers.size === 0) {
+            return;
+        }
+        const message = {
+            channel,
+            event,
+            payload,
+            id
+        };
+        // Isolate subscriber errors so one failure does not halt remaining subscribers
+        for (const subscriber of subscribers) {
+            try {
+                subscriber(message);
+            }
+            catch (err) {
+                console.error(`[Yaxa Broadcaster Error] Channel '${channel}', Event '${event}':`, err);
+            }
+        }
+    }
+    subscribe(channel, subscriber) {
+        let subscribers = this.channels.get(channel);
+        if (!subscribers) {
+            subscribers = new Set();
+            this.channels.set(channel, subscribers);
+        }
+        subscribers.add(subscriber);
+        return () => {
+            this.unsubscribe(channel, subscriber);
+        };
+    }
+    unsubscribe(channel, subscriber) {
+        const subscribers = this.channels.get(channel);
+        if (subscribers) {
+            subscribers.delete(subscriber);
+            if (subscribers.size === 0) {
+                this.channels.delete(channel);
+            }
+        }
+    }
+    subscriberCount(channel) {
+        return this.channels.get(channel)?.size ?? 0;
+    }
+    clear() {
+        this.channels.clear();
+    }
+}
+/**
+ * Global default broadcaster instance.
+ */
+export const globalBroadcaster = new MemoryBroadcaster();
+/**
+ * Creates a broadcaster instance or wraps a custom adapter.
+ */
+export function createBroadcaster(customAdapter) {
+    return customAdapter || new MemoryBroadcaster();
+}
+/**
+ * Broadcast an event to all connected clients on a channel.
+ * Callable from any endpoint, server action, webhook, or background worker.
+ *
+ * @example
+ * ```ts
+ * await broadcast(`org:${orgId}`, 'invoice.paid', { id: 'inv_123', total: 4900 });
+ * ```
+ */
+export async function broadcast(channel, event, payload, id, broadcasterInstance = globalBroadcaster) {
+    await broadcasterInstance.publish(channel, event, payload, id);
+}

package/dist/server/realtime/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './broadcaster';
+export * from './sse';

package/dist/server/realtime/index.js

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './broadcaster';
+export * from './sse';

package/dist/server/realtime/realtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/realtime/realtime.test.js

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { formatSSEFrame, yaxaSSE } from './sse';
+import { MemoryBroadcaster, broadcast } from './broadcaster';
+import { requireAuth } from '../endpoint/guards';
+import { createMockRequestEvent } from '../../testing/index.js';
+describe('formatSSEFrame', () => {
+    it('formats simple text message without event name', () => {
+        const frame = formatSSEFrame({ data: 'hello world' });
+        expect(frame).toBe('data: hello world\n\n');
+    });
+    it('formats JSON object data and custom event name', () => {
+        const frame = formatSSEFrame({
+            event: 'order.created',
+            data: { id: 123, total: 49.99 }
+        });
+        expect(frame).toContain('event: order.created\n');
+        expect(frame).toContain('data: {"id":123,"total":49.99}\n\n');
+    });
+    it('includes id and retry fields when provided', () => {
+        const frame = formatSSEFrame({
+            id: 'evt_001',
+            event: 'status',
+            retry: 5000,
+            data: 'ok'
+        });
+        expect(frame).toContain('id: evt_001\n');
+        expect(frame).toContain('event: status\n');
+        expect(frame).toContain('retry: 5000\n');
+        expect(frame).toContain('data: ok\n\n');
+    });
+    it('splits multiline strings into multiple data lines per SSE spec', () => {
+        const multiline = 'line 1\nline 2\r\nline 3';
+        const frame = formatSSEFrame({ data: multiline });
+        expect(frame).toBe('data: line 1\ndata: line 2\ndata: line 3\n\n');
+    });
+});
+describe('MemoryBroadcaster Engine', () => {
+    let broadcaster;
+    beforeEach(() => {
+        broadcaster = new MemoryBroadcaster();
+    });
+    afterEach(() => {
+        broadcaster.clear();
+    });
+    it('dispatches published messages only to matching channel subscribers', () => {
+        const channel1Handler = vi.fn();
+        const channel2Handler = vi.fn();
+        broadcaster.subscribe('channel:1', channel1Handler);
+        broadcaster.subscribe('channel:2', channel2Handler);
+        broadcaster.publish('channel:1', 'ping', { test: true });
+        expect(channel1Handler).toHaveBeenCalledTimes(1);
+        expect(channel1Handler).toHaveBeenCalledWith({
+            channel: 'channel:1',
+            event: 'ping',
+            payload: { test: true },
+            id: undefined
+        });
+        expect(channel2Handler).not.toHaveBeenCalled();
+    });
+    it('unsubscribes cleanly using returned cleanup function', () => {
+        const handler = vi.fn();
+        const unsubscribe = broadcaster.subscribe('room:lobby', handler);
+        expect(broadcaster.subscriberCount('room:lobby')).toBe(1);
+        broadcaster.publish('room:lobby', 'msg', 'first');
+        expect(handler).toHaveBeenCalledTimes(1);
+        unsubscribe();
+        expect(broadcaster.subscriberCount('room:lobby')).toBe(0);
+        broadcaster.publish('room:lobby', 'msg', 'second');
+        expect(handler).toHaveBeenCalledTimes(1);
+    });
+    it('isolates subscriber errors without halting other subscribers', () => {
+        const failingSubscriber = vi.fn(() => {
+            throw new Error('Subscriber crashed');
+        });
+        const healthySubscriber = vi.fn();
+        const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        broadcaster.subscribe('alerts', failingSubscriber);
+        broadcaster.subscribe('alerts', healthySubscriber);
+        broadcaster.publish('alerts', 'danger', { level: 'high' });
+        expect(failingSubscriber).toHaveBeenCalledTimes(1);
+        expect(healthySubscriber).toHaveBeenCalledTimes(1);
+        expect(consoleSpy).toHaveBeenCalled();
+        consoleSpy.mockRestore();
+    });
+});
+describe('yaxaSSE Server Handler', () => {
+    let broadcaster;
+    beforeEach(() => {
+        broadcaster = new MemoryBroadcaster();
+    });
+    afterEach(() => {
+        broadcaster.clear();
+    });
+    it('sets standard SSE response headers', async () => {
+        const handler = yaxaSSE({ broadcaster, keepAliveIntervalMs: 0 });
+        const event = createMockRequestEvent({ url: 'http://localhost:5173/api/events' });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toBe('text/event-stream; charset=utf-8');
+        expect(response.headers.get('cache-control')).toBe('no-cache, no-transform');
+        expect(response.headers.get('connection')).toBe('keep-alive');
+        expect(response.headers.get('x-accel-buffering')).toBe('no');
+        expect(response.body).toBeInstanceOf(ReadableStream);
+    });
+    it('evaluates declarative guards and blocks unauthenticated requests with 401 Problem Details', async () => {
+        const handler = yaxaSSE({
+            guards: [requireAuth()],
+            broadcaster
+        });
+        // Event without authenticated user
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/events',
+            locals: {}
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(401);
+        expect(response.headers.get('content-type')).toContain('application/problem+json');
+        const body = await response.json();
+        expect(body.title).toContain('Unauthorized');
+    });
+    it('invokes onConnect and delivers messages through client send', async () => {
+        let onConnectCalled = false;
+        const handler = yaxaSSE({
+            broadcaster,
+            keepAliveIntervalMs: 0,
+            channel: 'dashboard',
+            onConnect: ({ send }) => {
+                onConnectCalled = true;
+                send('welcome', { initialized: true });
+            }
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/events',
+            locals: { user: { id: 'usr_123', email: 'alex@example.com' } }
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        const { value } = await reader.read();
+        const text = decoder.decode(value);
+        expect(onConnectCalled).toBe(true);
+        expect(text).toContain('event: welcome\n');
+        expect(text).toContain('data: {"initialized":true}\n\n');
+        await reader.cancel();
+    });
+    it('receives events published via broadcast() helper', async () => {
+        const handler = yaxaSSE({
+            broadcaster,
+            keepAliveIntervalMs: 0,
+            channel: 'tenant:acme'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/events'
+        });
+        const response = await handler(event);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        // Broadcast an event on the channel
+        await broadcast('tenant:acme', 'kpi.updated', { value: 99.4 }, undefined, broadcaster);
+        const { value } = await reader.read();
+        const text = decoder.decode(value);
+        expect(text).toContain('event: kpi.updated\n');
+        expect(text).toContain('data: {"value":99.4}\n\n');
+        await reader.cancel();
+    });
+    it('resolves dynamic channel from RequestEvent', async () => {
+        const handler = yaxaSSE({
+            broadcaster,
+            keepAliveIntervalMs: 0,
+            channel: (evt) => `user:${evt.locals.user.id}`
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/events',
+            locals: { user: { id: 'usr_abc' } }
+        });
+        const response = await handler(event);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        // Broadcast to matching dynamic channel
+        await broadcast('user:usr_abc', 'notification', { msg: 'Test' }, undefined, broadcaster);
+        const { value } = await reader.read();
+        const text = decoder.decode(value);
+        expect(text).toContain('event: notification\n');
+        expect(text).toContain('data: {"msg":"Test"}\n\n');
+        await reader.cancel();
+    });
+    it('invokes onDisconnect when stream is cancelled or client aborts', async () => {
+        let disconnected = false;
+        const abortController = new AbortController();
+        const handler = yaxaSSE({
+            broadcaster,
+            keepAliveIntervalMs: 0,
+            channel: 'session',
+            onDisconnect: () => {
+                disconnected = true;
+            }
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/events',
+            signal: abortController.signal
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        // Trigger stream cancel
+        const reader = response.body.getReader();
+        await reader.cancel();
+        expect(disconnected).toBe(true);
+    });
+});

package/dist/server/realtime/sse.d.ts

@@ -0,0 +1,28 @@
+import type { RequestHandler } from '@sveltejs/kit';
+import type { SSEMessage, YaxaSSEOptions } from './types';
+/**
+ * Formats a payload into a valid Server-Sent Events text frame.
+ */
+export declare function formatSSEFrame<T = unknown>(message: SSEMessage<T>): string;
+/**
+ * Creates a turnkey SvelteKit Server-Sent Events (SSE) RequestHandler with
+ * guard evaluation, automatic keep-alive pings, and channel broadcasting.
+ *
+ * @example
+ * ```ts
+ * // src/routes/api/events/+server.ts
+ * import { yaxaSSE, requireAuth } from 'yaxa-svelte/server';
+ *
+ * export const GET = yaxaSSE({
+ *   guards: [requireAuth()],
+ *   channel: (event) => `org:${event.locals.orgId}`,
+ *   keepAliveIntervalMs: 15000,
+ *   onConnect: ({ send }) => {
+ *     send('welcome', { time: Date.now() });
+ *   }
+ * });
+ * ```
+ */
+export declare function yaxaSSE(options?: YaxaSSEOptions): RequestHandler & {
+    _yaxaConfig: any;
+};

package/dist/server/realtime/sse.js

@@ -0,0 +1,225 @@
+import { globalBroadcaster } from './broadcaster';
+import { problemResponse } from '../endpoint/problem';
+/**
+ * Formats a payload into a valid Server-Sent Events text frame.
+ */
+export function formatSSEFrame(message) {
+    let output = '';
+    if (message.id !== undefined) {
+        output += `id: ${message.id}\n`;
+    }
+    if (message.event !== undefined) {
+        output += `event: ${message.event}\n`;
+    }
+    if (message.retry !== undefined) {
+        output += `retry: ${message.retry}\n`;
+    }
+    const dataStr = typeof message.data === 'object' && message.data !== null
+        ? JSON.stringify(message.data)
+        : String(message.data ?? '');
+    // SSE specification requires multiple 'data: ' lines if data contains newlines
+    const lines = dataStr.split(/\r\n|\r|\n/);
+    for (const line of lines) {
+        output += `data: ${line}\n`;
+    }
+    output += '\n';
+    return output;
+}
+/**
+ * Creates a turnkey SvelteKit Server-Sent Events (SSE) RequestHandler with
+ * guard evaluation, automatic keep-alive pings, and channel broadcasting.
+ *
+ * @example
+ * ```ts
+ * // src/routes/api/events/+server.ts
+ * import { yaxaSSE, requireAuth } from 'yaxa-svelte/server';
+ *
+ * export const GET = yaxaSSE({
+ *   guards: [requireAuth()],
+ *   channel: (event) => `org:${event.locals.orgId}`,
+ *   keepAliveIntervalMs: 15000,
+ *   onConnect: ({ send }) => {
+ *     send('welcome', { time: Date.now() });
+ *   }
+ * });
+ * ```
+ */
+export function yaxaSSE(options = {}) {
+    const keepAliveIntervalMs = options.keepAliveIntervalMs ?? 15_000;
+    const keepAliveComment = options.keepAliveComment ?? ': ping\n\n';
+    const broadcaster = options.broadcaster ?? globalBroadcaster;
+    const sseHandler = async (event) => {
+        const { request, locals } = event;
+        // 1. Evaluate guards if configured
+        if (options.guards && options.guards.length > 0) {
+            for (const guard of options.guards) {
+                const result = await guard(event);
+                if (result instanceof Response) {
+                    return result;
+                }
+                if (result && typeof result === 'object' && 'status' in result && 'title' in result) {
+                    return problemResponse(result);
+                }
+                if (result === false) {
+                    return problemResponse({
+                        status: 403,
+                        title: 'Forbidden',
+                        detail: 'Access denied by endpoint guard.'
+                    });
+                }
+            }
+        }
+        // 2. Resolve target channel
+        let channel = 'default';
+        if (typeof options.channel === 'function') {
+            channel = await options.channel(event);
+        }
+        else if (typeof options.channel === 'string' && options.channel.length > 0) {
+            channel = options.channel;
+        }
+        const user = locals?.user ?? null;
+        const orgId = locals?.orgId ?? locals?.org?.id ?? null;
+        const connectionId = `sse_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+        const encoder = new TextEncoder();
+        let unsubscribe = null;
+        let pingTimer = null;
+        let isClosed = false;
+        let clientCloseFn = null;
+        const stream = new ReadableStream({
+            start(controller) {
+                const safeEnqueue = (text) => {
+                    if (isClosed)
+                        return false;
+                    try {
+                        controller.enqueue(encoder.encode(text));
+                        return true;
+                    }
+                    catch {
+                        isClosed = true;
+                        return false;
+                    }
+                };
+                const clientSend = (eventOrMessage, data) => {
+                    if (isClosed)
+                        return false;
+                    let msg;
+                    if (typeof eventOrMessage === 'string') {
+                        msg = { event: eventOrMessage, data: data };
+                    }
+                    else {
+                        msg = eventOrMessage;
+                    }
+                    return safeEnqueue(formatSSEFrame(msg));
+                };
+                const clientClose = () => {
+                    if (isClosed)
+                        return;
+                    isClosed = true;
+                    if (pingTimer) {
+                        clearInterval(pingTimer);
+                        pingTimer = null;
+                    }
+                    if (unsubscribe) {
+                        unsubscribe();
+                        unsubscribe = null;
+                    }
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        // Stream might already be closed by client
+                    }
+                    if (options.onDisconnect) {
+                        Promise.resolve(options.onDisconnect({
+                            connectionId,
+                            channel,
+                            event,
+                            user,
+                            orgId
+                        })).catch((err) => {
+                            console.error('[Yaxa SSE onDisconnect Error]:', err);
+                        });
+                    }
+                };
+                clientCloseFn = clientClose;
+                // Subscribe client to channel broadcast events
+                unsubscribe = broadcaster.subscribe(channel, (msg) => {
+                    clientSend({
+                        event: msg.event,
+                        data: msg.payload,
+                        id: msg.id
+                    });
+                });
+                // Heartbeat loop to keep connections open through proxies/firewalls
+                if (keepAliveIntervalMs > 0) {
+                    pingTimer = setInterval(() => {
+                        safeEnqueue(keepAliveComment);
+                    }, keepAliveIntervalMs);
+                }
+                // Abort handling when client closes connection or navigates away
+                if (request.signal) {
+                    request.signal.addEventListener('abort', clientClose, { once: true });
+                }
+                // Context provided to onConnect
+                const clientContext = {
+                    connectionId,
+                    channel,
+                    event,
+                    user,
+                    orgId,
+                    send: clientSend,
+                    close: clientClose
+                };
+                // Invoke onConnect callback
+                if (options.onConnect) {
+                    Promise.resolve(options.onConnect(clientContext)).catch((err) => {
+                        console.error('[Yaxa SSE onConnect Error]:', err);
+                    });
+                }
+            },
+            cancel() {
+                if (clientCloseFn) {
+                    clientCloseFn();
+                }
+                else {
+                    isClosed = true;
+                    if (pingTimer) {
+                        clearInterval(pingTimer);
+                        pingTimer = null;
+                    }
+                    if (unsubscribe) {
+                        unsubscribe();
+                        unsubscribe = null;
+                    }
+                }
+            }
+        });
+        return new Response(stream, {
+            status: 200,
+            headers: {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-cache, no-transform',
+                connection: 'keep-alive',
+                'x-accel-buffering': 'no'
+            }
+        });
+    };
+    sseHandler._yaxaConfig = {
+        summary: options.summary || 'Server-Sent Events Stream',
+        description: options.description ||
+            'Real-time Server-Sent Events stream with multi-channel pub/sub and keep-alive heartbeats.',
+        guards: options.guards,
+        status: 200,
+        responses: {
+            '200': {
+                description: 'Active event stream',
+                content: {
+                    'text/event-stream': {
+                        schema: { type: 'string' }
+                    }
+                }
+            }
+        }
+    };
+    return sseHandler;
+}

package/dist/server/realtime/types.d.ts

@@ -0,0 +1,116 @@
+import type { RequestEvent } from '@sveltejs/kit';
+import type { Guard } from '../endpoint/types';
+/**
+ * Structured Server-Sent Event message payload.
+ */
+export interface SSEMessage<T = unknown> {
+    /** Optional unique event ID for client Last-Event-ID tracking */
+    id?: string;
+    /** Optional named event type (defaults to 'message') */
+    event?: string;
+    /** Payload data to transmit. Objects/arrays are JSON-encoded automatically */
+    data: T;
+    /** Optional reconnection delay in milliseconds suggested to the client */
+    retry?: number;
+}
+/**
+ * Context provided to onConnect and event callbacks.
+ */
+export interface SSEClientContext {
+    /** Unique connection ID */
+    connectionId: string;
+    /** Active channel name */
+    channel: string;
+    /** The incoming SvelteKit RequestEvent */
+    event: RequestEvent;
+    /** Resolved user from guards/locals */
+    user?: any;
+    /** Active organization ID from guards/locals */
+    orgId?: string | null;
+    /** Send an SSE message directly to this client */
+    send: <T = unknown>(eventOrMessage: string | SSEMessage<T>, data?: T) => boolean;
+    /** Explicitly close this SSE connection */
+    close: () => void;
+}
+/**
+ * Configuration options for yaxaSSE endpoint handler.
+ */
+export interface YaxaSSEOptions {
+    /** Summary for OpenAPI documentation */
+    summary?: string;
+    /** Description for OpenAPI documentation */
+    description?: string;
+    /**
+     * Declarative guards executed before establishing the SSE connection.
+     * If a guard fails, an RFC 7807 Problem Details response (e.g. 401, 403, 429) is returned.
+     */
+    guards?: Guard[];
+    /**
+     * Channel name to subscribe this client to. Can be a static string or a dynamic function
+     * of the incoming RequestEvent (e.g. `(event) => \`org:\${event.locals.orgId}\``).
+     * Defaults to `'default'`.
+     */
+    channel?: string | ((event: RequestEvent) => string | Promise<string>);
+    /**
+     * Keep-alive ping interval in milliseconds to prevent reverse proxies, firewalls,
+     * and serverless platforms (e.g. Vercel) from terminating idle connections.
+     * Set to 0 to disable. Defaults to 15,000ms (15s).
+     */
+    keepAliveIntervalMs?: number;
+    /**
+     * Custom comment or payload for keep-alive pings.
+     * Defaults to `: ping\n\n`.
+     */
+    keepAliveComment?: string;
+    /**
+     * Hook called immediately after connection establishment and headers transmission.
+     */
+    onConnect?: (ctx: SSEClientContext) => void | Promise<void>;
+    /**
+     * Hook called when the client disconnects or the request is aborted.
+     */
+    onDisconnect?: (ctx: Omit<SSEClientContext, 'send' | 'close'>) => void | Promise<void>;
+    /**
+     * Custom broadcaster instance. If omitted, uses the global broadcaster singleton.
+     */
+    broadcaster?: Broadcaster;
+}
+/**
+ * Broadcast message contract.
+ */
+export interface BroadcastMessage<T = unknown> {
+    channel: string;
+    event: string;
+    payload: T;
+    id?: string;
+}
+/**
+ * Broadcaster subscription callback.
+ */
+export type BroadcastSubscriber<T = unknown> = (msg: BroadcastMessage<T>) => void;
+/**
+ * Broadcaster adapter interface.
+ * Can be implemented by MemoryBroadcaster, RedisBroadcaster, ValkeyBroadcaster, etc.
+ */
+export interface Broadcaster {
+    /**
+     * Publish an event to all subscribers listening on the specified channel.
+     */
+    publish: <T = unknown>(channel: string, event: string, payload: T, id?: string) => Promise<void> | void;
+    /**
+     * Subscribe to events on a specific channel. Returns an unsubscribe function.
+     */
+    subscribe: <T = unknown>(channel: string, subscriber: BroadcastSubscriber<T>) => () => void;
+    /**
+     * Unsubscribe a callback from a channel.
+     */
+    unsubscribe: <T = unknown>(channel: string, subscriber: BroadcastSubscriber<T>) => void;
+    /**
+     * Returns current number of active subscribers on a channel (optional).
+     */
+    subscriberCount?: (channel: string) => number;
+    /**
+     * Remove all subscribers across all channels.
+     */
+    clear?: () => void;
+}

package/dist/server/realtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/testing/index.d.ts

@@ -85,6 +85,8 @@ export interface MockRequestEventOptions {
     params?: Record<string, string>;
     locals?: Record<string, any>;
     cookies?: Record<string, string>;
+    signal?: AbortSignal;
+    request?: Request;
 }
 /**
  * Creates a mocked typed SvelteKit RequestEvent for unit testing endpoints and server hooks.

package/dist/testing/index.js

@@ -124,11 +124,13 @@ export function createMockRequestEvent(options = {}) {
             }
         }
     }
-    const request = new Request(url.toString(), {
-        method,
-        headers,
-        body: method !== 'GET' && method !== 'HEAD' ? bodyContent : undefined
-    });
+    const request = options.request ||
+        new Request(url.toString(), {
+            method,
+            headers,
+            body: method !== 'GET' && method !== 'HEAD' ? bodyContent : undefined,
+            signal: options.signal
+        });
     const cookieStore = new Map(Object.entries(options.cookies || {}));
     const cookies = {
         get: (name) => cookieStore.get(name),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaxa-svelte",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "The Intuitive Svelte UI Library — Nuxt UI v4 equivalent for SvelteKit 2 & 3 & Svelte 5 with automated SEO, dynamic OpenGraph cards, sitemaps, robots.txt, and Tailwind CSS v4.",
   "license": "MIT",
   "homepage": "https://yaxa.vercel.app",