yaxa-svelte 2.4.0 → 2.6.0

package/dist/client/types.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Standard RFC 7807 Problem Details representation.
+ * @see https://datatracker.ietf.org/doc/html/rfc7807
+ */
+export interface ProblemDetails {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    invalidParams?: Array<{
+        name: string;
+        reason: string;
+    }>;
+    [key: string]: unknown;
+}
+/**
+ * Standard Schema or validator representation.
+ */
+export type AnyValidator<T = any> = {
+    '~standard': {
+        validate: (value: unknown) => Promise<{
+            value?: T;
+            issues?: ReadonlyArray<any>;
+        }> | {
+            value?: T;
+            issues?: ReadonlyArray<any>;
+        };
+    };
+} | {
+    safeParse: (value: unknown) => {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: any;
+    };
+} | {
+    parse: (value: unknown) => T;
+} | ((value: unknown) => {
+    success: boolean;
+    data?: T;
+    error?: any;
+});
+/**
+ * Infer output type from a schema validator.
+ */
+export type InferValidatorOutput<V> = V extends {
+    '~standard': {
+        validate: (...args: any[]) => Promise<{
+            value?: infer T;
+        }> | {
+            value?: infer T;
+        };
+    };
+} ? T : V extends {
+    safeParse: (...args: any[]) => {
+        success: true;
+        data: infer T;
+    } | {
+        success: false;
+        error: any;
+    };
+} ? T : V extends {
+    parse: (...args: any[]) => infer T;
+} ? T : V extends (value: unknown) => {
+    success: true;
+    data: infer T;
+} ? T : any;
+/**
+ * Infer request payload and response types from a yaxaEndpoint handler or config.
+ */
+export type InferEndpoint<T> = T extends {
+    _yaxaConfig: {
+        schema?: {
+            body?: infer B;
+            query?: infer Q;
+            params?: infer P;
+            headers?: infer H;
+        };
+        handle: (...args: any[]) => infer R;
+    };
+} ? {
+    body: [B] extends [never] ? undefined : InferValidatorOutput<B>;
+    query: [Q] extends [never] ? undefined : InferValidatorOutput<Q>;
+    params: [P] extends [never] ? undefined : InferValidatorOutput<P>;
+    headers: [H] extends [never] ? undefined : InferValidatorOutput<H>;
+    response: Awaited<R> extends Response ? unknown : Awaited<R>;
+} : T extends (...args: any[]) => Promise<infer R> | infer R ? {
+    body: any;
+    query: any;
+    params: any;
+    headers: any;
+    response: Awaited<R> extends Response ? unknown : Awaited<R>;
+} : {
+    body: any;
+    query: any;
+    params: any;
+    headers: any;
+    response: any;
+};
+/**
+ * Strong discriminated union result returned by apiClient calls.
+ */
+export type ClientResponse<TData> = {
+    data: TData;
+    error: null;
+    response: Response;
+    status: number;
+    ok: true;
+} | {
+    data: null;
+    error: ProblemDetails;
+    response: Response;
+    status: number;
+    ok: false;
+};
+/**
+ * Client request options passed to an endpoint method.
+ */
+export interface ClientRequestOptions<TBody = unknown, TQuery = Record<string, any>, TParams = Record<string, any>> {
+    body?: TBody;
+    query?: TQuery;
+    params?: TParams;
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+}
+/**
+ * Helper to determine if an option object is required based on schema properties.
+ */
+export type RequiredKeys<T> = {
+    [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
+}[keyof T];
+export type ClientMethodFn<TEndpoint> = TEndpoint extends never ? (options?: ClientRequestOptions) => Promise<ClientResponse<any>> : InferEndpoint<TEndpoint> extends infer Inferred ? Inferred extends {
+    body: infer B;
+    query: infer Q;
+    params: infer P;
+    response: infer R;
+} ? (options?: {
+    body?: B;
+    query?: Q;
+    params?: P;
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+}) => Promise<ClientResponse<R>> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+/**
+ * HTTP methods supported by a route definition.
+ */
+export type RouteMethods<TRoute> = {
+    get: TRoute extends {
+        GET: infer H;
+    } ? ClientMethodFn<H> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+    post: TRoute extends {
+        POST: infer H;
+    } ? ClientMethodFn<H> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+    put: TRoute extends {
+        PUT: infer H;
+    } ? ClientMethodFn<H> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+    delete: TRoute extends {
+        DELETE: infer H;
+    } ? ClientMethodFn<H> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+    patch: TRoute extends {
+        PATCH: infer H;
+    } ? ClientMethodFn<H> : (options?: ClientRequestOptions) => Promise<ClientResponse<any>>;
+};
+/**
+ * Callable route proxy supporting path parameter interpolation.
+ * e.g. api['/api/projects/[id]']({ id: '123' }).get()
+ */
+export type RouteProxy<TRoute> = RouteMethods<TRoute> & {
+    (params: Record<string, any>): RouteMethods<TRoute>;
+};
+/**
+ * Global configuration options for creating an API client.
+ */
+export interface ApiClientConfig {
+    /**
+     * Base URL prefix for all requests (e.g. 'https://api.example.com' or '').
+     * Defaults to empty string (relative to current origin).
+     */
+    baseUrl?: string;
+    /**
+     * Custom fetch implementation (e.g. SvelteKit's event.fetch in load functions).
+     * Defaults to globalThis.fetch.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Default headers to attach to every request.
+     */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /**
+     * Interceptor hook called before every request.
+     */
+    onRequest?: (context: {
+        url: string;
+        options: RequestInit;
+    }) => void | Promise<void>;
+    /**
+     * Interceptor hook called on every response.
+     */
+    onResponse?: (context: {
+        response: Response;
+        data: any;
+        error: ProblemDetails | null;
+    }) => void | Promise<void>;
+}
+/**
+ * Dynamic Proxy type mapping paths to methods.
+ */
+export type ApiClient<TRoutes = Record<string, any>> = {
+    [K in keyof TRoutes]: RouteProxy<TRoutes[K]>;
+} & {
+    [path: string]: RouteProxy<any>;
+} & {
+    get: <TData = any>(path: string, options?: ClientRequestOptions) => Promise<ClientResponse<TData>>;
+    post: <TData = any>(path: string, options?: ClientRequestOptions) => Promise<ClientResponse<TData>>;
+    put: <TData = any>(path: string, options?: ClientRequestOptions) => Promise<ClientResponse<TData>>;
+    delete: <TData = any>(path: string, options?: ClientRequestOptions) => Promise<ClientResponse<TData>>;
+    patch: <TData = any>(path: string, options?: ClientRequestOptions) => Promise<ClientResponse<TData>>;
+};

package/dist/client/types.js

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

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';
@@ -205,5 +207,7 @@ export { default as FeatureGrid, featureGridVariants } from './components/blocks
 export type { FeatureGridProps, FeatureItem } from './components/blocks/FeatureGrid.svelte';
 export { createMockSiteConfig, createMockUser, createTestWrapperProps } from './testing';
 export type { YaxaTestOptions } from './testing';
+export { createApiClient, interpolatePath, serializeQueryParams } from './client';
+export type { ApiClient, ApiClientConfig, ClientRequestOptions, ClientResponse, InferEndpoint, RouteMethods, ProblemDetails as ClientProblemDetails } from './client';
 export { cn, tv } from './utils/cn';
 export type { VariantProps } from './utils/cn';

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';
@@ -137,5 +138,7 @@ export { default as FAQ, faqVariants } from './components/blocks/FAQ.svelte';
 export { default as FeatureGrid, featureGridVariants } from './components/blocks/FeatureGrid.svelte';
 // Testing Utilities
 export { createMockSiteConfig, createMockUser, createTestWrapperProps } from './testing';
+// Type-Safe Client RPC
+export { createApiClient, interpolatePath, serializeQueryParams } from './client';
 // Utilities
 export { cn, tv } from './utils/cn';

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 {