yaxa-svelte 2.6.0 → 2.7.0

package/README.md

@@ -5,6 +5,7 @@
 **The Intuitive Svelte UI & Solo SaaS Library**  
 _Nuxt UI v4 & Nuxt UI Pro Equivalent for SvelteKit 2 & 3 & Svelte 5 with Built-in SEO & SaaS Parity._
 
+[![Live Demo](https://img.shields.io/badge/Live_Demo-yaxa.vercel.app-000000?style=flat&logo=vercel&logoColor=white)](https://yaxa.vercel.app)
 [![npm version](https://img.shields.io/npm/v/yaxa-svelte.svg?color=CB3837&logo=npm)](https://www.npmjs.com/package/yaxa-svelte)
 [![npm downloads](https://img.shields.io/npm/dm/yaxa-svelte.svg?color=blue)](https://www.npmjs.com/package/yaxa-svelte)
 [![Svelte 5](https://img.shields.io/badge/Svelte-5.0+-FF3E00?style=flat&logo=svelte&logoColor=white)](https://svelte.dev)
@@ -15,7 +16,13 @@ _Nuxt UI v4 & Nuxt UI Pro Equivalent for SvelteKit 2 & 3 & Svelte 5 with Built-i
 [![Security Policy](https://img.shields.io/badge/Security-Policy-blue.svg)](SECURITY.md)
 [![Contributing](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-[**Live Documentation & Playground →**](https://yaxa.vercel.app)
+<br />
+
+[**🚀 Live Demo**](https://yaxa.vercel.app) &nbsp;•&nbsp;
+[**📚 Documentation**](https://yaxa.vercel.app/docs) &nbsp;•&nbsp;
+[**🎨 Theme Studio**](https://yaxa.vercel.app/theme) &nbsp;•&nbsp;
+[**💼 SaaS Showcase**](https://yaxa.vercel.app/saas) &nbsp;•&nbsp;
+[**⚡ Scalar API Reference**](https://yaxa.vercel.app/api/docs)
 
 </div>
 
@@ -276,7 +283,7 @@ export const POST = yaxaEndpoint({
 
 ## 📜 Auto-Generated OpenAPI 3.1 & Interactive Docs (`/api/docs`)
 
-Instantly generate an OpenAPI 3.1 specification and host interactive documentation ([Scalar](https://scalar.com/), Swagger UI, or Redoc) directly from your `yaxaEndpoint` routes:
+Instantly generate an OpenAPI 3.1 specification and host interactive documentation ([Scalar](https://scalar.com/) or Swagger UI) directly from your `yaxaEndpoint` routes:
 
 ```ts
 // src/routes/api/docs/+server.ts
@@ -286,7 +293,7 @@ import { POST as createProject } from '../projects/+server';
 export const GET = createApiDocsHandler({
 	title: 'Acme SaaS API',
 	version: '1.0.0',
-	theme: 'scalar', // 'scalar' (default) | 'swagger' | 'redoc'
+	theme: 'scalar', // 'scalar' (default) | 'swagger'
 	endpoints: {
 		'/api/projects': {
 			POST: createProject
@@ -295,7 +302,7 @@ export const GET = createApiDocsHandler({
 });
 ```
 
-- **Interactive Reference UI:** Open `/api/docs` in your browser (supports `?theme=scalar` (default), `?theme=swagger`, or `?theme=redoc`).
+- **Interactive Reference UI:** Open `/api/docs` in your browser (supports `?theme=scalar` (default) or `?theme=swagger`).
 - **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.
 
@@ -441,22 +448,81 @@ export const load = async ({ fetch }) => {
 
 ---
 
+## ⚡ Runes-Native Reactive Query & Realtime RPC (`createQuery`, `createMutation`)
+
+A zero-overhead, runes-native query and mutation cache built specifically for Svelte 5. Features request coalescing, stale-while-revalidate, window focus revalidation, optimistic updates with automatic rollback, and live SSE cache invalidation:
+
+```svelte
+<!-- src/routes/projects/+page.svelte -->
+<script lang="ts">
+	import { api } from '$lib/api';
+	import { createQuery, createMutation } from 'yaxa-svelte';
+
+	let activeOrg = $state('org_123');
+
+	// 1. Reactive Query: auto-refetches when activeOrg changes
+	const projects = createQuery(() => api['/api/projects'].get({ query: { orgId: activeOrg } }), {
+		staleTimeMs: 15_000,
+		refetchOnWindowFocus: true,
+		subscribeToSse: `org:${activeOrg}/projects` // ⚡ Live SSE invalidation
+	});
+
+	// 2. Optimistic Mutation with Automatic Rollback on RFC 7807 Error
+	const createProject = createMutation(
+		(name: string) => api['/api/projects'].post({ body: { name, orgId: activeOrg } }),
+		{
+			onMutate: (name) => {
+				const previous = projects.data;
+				projects.optimisticUpdate((curr) => [
+					{ id: 'temp-' + Date.now(), name, status: 'creating' },
+					...(curr ?? [])
+				]);
+				return { previous }; // Snapshot for rollback
+			},
+			onError: (err, _name, context) => {
+				if (context?.previous) projects.setData(context.previous);
+				toast.error(err.title, err.detail);
+			},
+			onSettled: () => projects.invalidate()
+		}
+	);
+</script>
+
+{#if projects.isLoading}
+	<Skeleton count={3} class="h-10 w-full" />
+{:else if projects.data}
+	<ul>
+		{#each projects.data as project}
+			<li class={project.id.startsWith('temp-') ? 'opacity-50' : ''}>
+				{project.name}
+			</li>
+		{/each}
+	</ul>
+{/if}
+
+<Button onclick={() => createProject.mutate('New Project')} loading={createProject.isPending}>
+	Create Project
+</Button>
+```
+
+---
+
 ## 📦 Subpath Exports Architecture
 
-| Subpath                 | Description                                                                                                                                                                                                                |
-| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Type-Safe Client RPC (`createApiClient`), 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'`                                                                                                           |
+| Subpath                 | Description                                                                                                                                                                                                                                                    |
+| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Type-Safe Client RPC (`createApiClient`), Runes Query Engine (`createQuery`, `createMutation`, `QueryClient`), 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/client/index.d.ts

@@ -1,2 +1,5 @@
 export * from './types';
 export * from './client';
+export * from './query-cache.svelte';
+export * from './query.svelte';
+export * from './mutation.svelte';

package/dist/client/index.js

@@ -1,2 +1,5 @@
 export * from './types';
 export * from './client';
+export * from './query-cache.svelte';
+export * from './query.svelte';
+export * from './mutation.svelte';

package/dist/client/mutation.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { ClientResponse, ProblemDetails } from './types';
+export type MutationFn<TData = any, TVariables = any> = (variables: TVariables) => Promise<ClientResponse<TData> | TData>;
+export interface CreateMutationOptions<TData = any, TVariables = any, TError = ProblemDetails | Error, TContext = unknown> {
+    /**
+     * Callback fired immediately before the mutation runs.
+     * Ideal for optimistic updates; returned context will be passed to onError and onSettled.
+     */
+    onMutate?: (variables: TVariables) => Promise<TContext> | TContext;
+    /**
+     * Callback fired when mutation succeeds.
+     */
+    onSuccess?: (data: TData, variables: TVariables, context: TContext | undefined) => Promise<void> | void;
+    /**
+     * Callback fired when mutation fails.
+     */
+    onError?: (error: TError, variables: TVariables, context: TContext | undefined) => Promise<void> | void;
+    /**
+     * Callback fired when mutation completes (either success or error).
+     */
+    onSettled?: (data: TData | null, error: TError | null, variables: TVariables, context: TContext | undefined) => Promise<void> | void;
+}
+export interface CreateMutationResult<TData = any, TVariables = any, TError = ProblemDetails | Error> {
+    readonly data: TData | null;
+    readonly error: TError | null;
+    readonly status: 'idle' | 'pending' | 'success' | 'error';
+    readonly isPending: boolean;
+    readonly isSuccess: boolean;
+    readonly isError: boolean;
+    readonly isIdle: boolean;
+    mutate: (variables: TVariables) => Promise<TData>;
+    reset: () => void;
+}
+/**
+ * Idiomatic Svelte 5 Runes Mutation Composable.
+ * Features optimistic rollbacks, lifecycle callbacks, and RFC 7807 problem details unwrapping.
+ */
+export declare function createMutation<TData = any, TVariables = void, TError = ProblemDetails | Error, TContext = unknown>(mutationFn: MutationFn<TData, TVariables>, options?: CreateMutationOptions<TData, TVariables, TError, TContext>): CreateMutationResult<TData, TVariables, TError>;

package/dist/client/mutation.svelte.js

@@ -0,0 +1,87 @@
+/**
+ * Checks if a response is a Yaxa ClientResponse.
+ */
+function isClientResponse(res) {
+    return (typeof res === 'object' &&
+        res !== null &&
+        'ok' in res &&
+        'status' in res &&
+        ('data' in res || 'error' in res));
+}
+/**
+ * Idiomatic Svelte 5 Runes Mutation Composable.
+ * Features optimistic rollbacks, lifecycle callbacks, and RFC 7807 problem details unwrapping.
+ */
+export function createMutation(mutationFn, options = {}) {
+    let data = $state(null);
+    let error = $state(null);
+    let status = $state('idle');
+    const isPending = $derived(status === 'pending');
+    const isSuccess = $derived(status === 'success');
+    const isError = $derived(status === 'error');
+    const isIdle = $derived(status === 'idle');
+    async function mutate(variables) {
+        status = 'pending';
+        error = null;
+        let context;
+        try {
+            if (options.onMutate) {
+                context = await options.onMutate(variables);
+            }
+            const result = await mutationFn(variables);
+            let finalData;
+            if (isClientResponse(result)) {
+                if (!result.ok) {
+                    throw result.error;
+                }
+                finalData = result.data;
+            }
+            else {
+                finalData = result;
+            }
+            data = finalData;
+            status = 'success';
+            await options.onSuccess?.(finalData, variables, context);
+            await options.onSettled?.(finalData, null, variables, context);
+            return finalData;
+        }
+        catch (err) {
+            const errPayload = err;
+            error = errPayload;
+            status = 'error';
+            await options.onError?.(errPayload, variables, context);
+            await options.onSettled?.(null, errPayload, variables, context);
+            throw err;
+        }
+    }
+    function reset() {
+        data = null;
+        error = null;
+        status = 'idle';
+    }
+    return {
+        get data() {
+            return data;
+        },
+        get error() {
+            return error;
+        },
+        get status() {
+            return status;
+        },
+        get isPending() {
+            return isPending;
+        },
+        get isSuccess() {
+            return isSuccess;
+        },
+        get isError() {
+            return isError;
+        },
+        get isIdle() {
+            return isIdle;
+        },
+        mutate,
+        reset
+    };
+}

package/dist/client/query-cache.svelte.d.ts

@@ -0,0 +1,51 @@
+import { SvelteSet } from 'svelte/reactivity';
+export type QueryKey = string | readonly unknown[];
+/**
+ * Deterministically serializes a QueryKey into a cache string.
+ */
+export declare function hashQueryKey(key: QueryKey): string;
+export type QueryStatus = 'idle' | 'loading' | 'success' | 'error';
+export interface QueryCacheEntry<TData = any, TError = any> {
+    readonly key: string;
+    data: TData | null;
+    error: TError | null;
+    status: QueryStatus;
+    isFetching: boolean;
+    updatedAt: number;
+    inFlightPromise: Promise<TData | null> | null;
+    subscribers: SvelteSet<() => void>;
+    invalidate: () => Promise<void>;
+}
+export interface InvalidateOptions {
+    key?: QueryKey;
+    exact?: boolean;
+}
+/**
+ * Runes-native Query Client managing cache entries, request coalescing,
+ * and real-time invalidation.
+ */
+export declare class QueryClient {
+    private entries;
+    /**
+     * Retrieves or initializes a cache entry for a given key string.
+     */
+    getOrCreateEntry<TData = any, TError = any>(keyHash: string, initialData?: TData): QueryCacheEntry<TData, TError>;
+    /**
+     * Retrieves current data for a query key from the cache.
+     */
+    getQueryData<TData = any>(key: QueryKey): TData | null;
+    /**
+     * Manually sets or optimistically updates data for a query key.
+     */
+    setQueryData<TData = any>(key: QueryKey, updater: TData | ((previous: TData | null) => TData)): TData;
+    /**
+     * Invalidates queries matching a key or filter, triggering active subscribers to refetch.
+     */
+    invalidateQueries(filter?: InvalidateOptions | QueryKey): Promise<void>;
+    /**
+     * Clears the cache completely.
+     */
+    clear(): void;
+}
+export declare function getQueryClient(): QueryClient;
+export declare function setQueryClient(client: QueryClient): void;

package/dist/client/query-cache.svelte.js

@@ -0,0 +1,172 @@
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+/**
+ * Deterministically serializes a QueryKey into a cache string.
+ */
+export function hashQueryKey(key) {
+    if (typeof key === 'string')
+        return key;
+    try {
+        return JSON.stringify(key, (_, val) => {
+            if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+                // Sort object keys deterministically
+                return Object.keys(val)
+                    .sort()
+                    .reduce((acc, k) => {
+                    acc[k] = val[k];
+                    return acc;
+                }, {});
+            }
+            return val;
+        });
+    }
+    catch {
+        return String(key);
+    }
+}
+/**
+ * Runes-native Query Client managing cache entries, request coalescing,
+ * and real-time invalidation.
+ */
+export class QueryClient {
+    entries = new SvelteMap();
+    /**
+     * Retrieves or initializes a cache entry for a given key string.
+     */
+    getOrCreateEntry(keyHash, initialData) {
+        const entry = this.entries.get(keyHash);
+        if (!entry) {
+            let data = $state(initialData !== undefined ? initialData : null);
+            let error = $state(null);
+            let status = $state(initialData !== undefined ? 'success' : 'idle');
+            let isFetching = $state(false);
+            let updatedAt = $state(initialData !== undefined ? Date.now() : 0);
+            const subscribers = new SvelteSet();
+            const newEntry = {
+                key: keyHash,
+                get data() {
+                    return data;
+                },
+                set data(val) {
+                    data = val;
+                },
+                get error() {
+                    return error;
+                },
+                set error(val) {
+                    error = val;
+                },
+                get status() {
+                    return status;
+                },
+                set status(val) {
+                    status = val;
+                },
+                get isFetching() {
+                    return isFetching;
+                },
+                set isFetching(val) {
+                    isFetching = val;
+                },
+                get updatedAt() {
+                    return updatedAt;
+                },
+                set updatedAt(val) {
+                    updatedAt = val;
+                },
+                inFlightPromise: null,
+                subscribers,
+                invalidate: async () => {
+                    for (const notify of Array.from(subscribers)) {
+                        try {
+                            notify();
+                        }
+                        catch {
+                            // Ignored
+                        }
+                    }
+                }
+            };
+            this.entries.set(keyHash, newEntry);
+            return newEntry;
+        }
+        // If entry exists but has no data and initialData was provided, populate it
+        if (entry.data === null && initialData !== undefined && entry.status === 'idle') {
+            entry.data = initialData;
+            entry.status = 'success';
+            entry.updatedAt = Date.now();
+        }
+        return entry;
+    }
+    /**
+     * Retrieves current data for a query key from the cache.
+     */
+    getQueryData(key) {
+        const hash = hashQueryKey(key);
+        const entry = this.entries.get(hash);
+        return entry ? entry.data : null;
+    }
+    /**
+     * Manually sets or optimistically updates data for a query key.
+     */
+    setQueryData(key, updater) {
+        const hash = hashQueryKey(key);
+        const entry = this.getOrCreateEntry(hash);
+        const nextData = typeof updater === 'function'
+            ? updater(entry.data)
+            : updater;
+        entry.data = nextData;
+        entry.error = null;
+        entry.status = 'success';
+        entry.updatedAt = Date.now();
+        return nextData;
+    }
+    /**
+     * Invalidates queries matching a key or filter, triggering active subscribers to refetch.
+     */
+    async invalidateQueries(filter) {
+        if (!filter) {
+            for (const entry of this.entries.values()) {
+                await entry.invalidate();
+            }
+            return;
+        }
+        const isKey = typeof filter === 'string' || Array.isArray(filter);
+        const key = isKey ? filter : filter.key;
+        const exact = isKey ? false : Boolean(filter.exact);
+        if (!key) {
+            for (const entry of this.entries.values()) {
+                await entry.invalidate();
+            }
+            return;
+        }
+        const targetHash = hashQueryKey(key);
+        for (const [hash, entry] of this.entries.entries()) {
+            if (exact) {
+                if (hash === targetHash) {
+                    await entry.invalidate();
+                }
+            }
+            else {
+                if (hash.startsWith(targetHash) || hash === targetHash) {
+                    await entry.invalidate();
+                }
+            }
+        }
+    }
+    /**
+     * Clears the cache completely.
+     */
+    clear() {
+        this.entries.clear();
+    }
+}
+/**
+ * Global default query client singleton.
+ */
+let globalClient = new QueryClient();
+export function getQueryClient() {
+    return globalClient;
+}
+export function setQueryClient(client) {
+    globalClient = client;
+}

package/dist/client/query.svelte.d.ts

@@ -0,0 +1,71 @@
+import { type QueryClient, type QueryKey, type QueryStatus } from './query-cache.svelte';
+import type { ClientResponse, ProblemDetails } from './types';
+import type { SSEResult } from '../composables/useSSE.svelte';
+export type QueryFn<TData = any> = () => Promise<ClientResponse<TData> | TData>;
+export interface CreateQueryOptions<TData = any, TError = ProblemDetails | Error> {
+    /**
+     * Explicit cache key or reactive key getter. If omitted, an auto-derived key is used.
+     */
+    key?: QueryKey | (() => QueryKey);
+    /**
+     * Whether the query should execute automatically (defaults to true).
+     * Can be a boolean or a reactive boolean getter: `() => !!userId`.
+     */
+    enabled?: boolean | (() => boolean);
+    /**
+     * Initial data (useful for SSR hydration to avoid loading flashes).
+     */
+    initialData?: TData;
+    /**
+     * Time in milliseconds before data is considered stale (defaults to 0).
+     */
+    staleTimeMs?: number;
+    /**
+     * Whether to refetch data when the browser window regains focus (defaults to true).
+     */
+    refetchOnWindowFocus?: boolean;
+    /**
+     * Whether to refetch data when network reconnects (defaults to true).
+     */
+    refetchOnReconnect?: boolean;
+    /**
+     * Custom query client instance (defaults to global client).
+     */
+    client?: QueryClient;
+    /**
+     * Server-Sent Events stream or channel for live real-time cache invalidation.
+     */
+    subscribeToSse?: string | {
+        sse?: SSEResult;
+        event?: string;
+    };
+    /**
+     * Callback on successful fetch.
+     */
+    onSuccess?: (data: TData) => void;
+    /**
+     * Callback on error.
+     */
+    onError?: (error: TError) => void;
+}
+export interface CreateQueryResult<TData = any, TError = ProblemDetails | Error> {
+    readonly data: TData | null;
+    readonly error: TError | null;
+    readonly status: QueryStatus;
+    readonly isLoading: boolean;
+    readonly isFetching: boolean;
+    readonly isSuccess: boolean;
+    readonly isError: boolean;
+    readonly updatedAt: number;
+    refetch: () => Promise<TData | null>;
+    invalidate: () => Promise<void>;
+    setData: (updater: TData | ((prev: TData | null) => TData)) => void;
+    optimisticUpdate: (updater: (prev: TData | null) => TData) => void;
+    destroy: () => void;
+}
+/**
+ * Idiomatic Svelte 5 Runes Query Composable.
+ * Features automatic dependency tracking, request coalescing, stale-while-revalidate,
+ * window focus revalidation, and SSE live invalidation.
+ */
+export declare function createQuery<TData = any, TError = ProblemDetails | Error>(keyOrFn: QueryKey | (() => QueryKey) | QueryFn<TData>, fnOrOptions?: QueryFn<TData> | CreateQueryOptions<TData, TError>, maybeOptions?: CreateQueryOptions<TData, TError>): CreateQueryResult<TData, TError>;

package/dist/client/query.svelte.js

@@ -0,0 +1,213 @@
+import { hashQueryKey, getQueryClient } from './query-cache.svelte';
+/**
+ * Checks if a response is a Yaxa ClientResponse.
+ */
+function isClientResponse(res) {
+    return (typeof res === 'object' &&
+        res !== null &&
+        'ok' in res &&
+        'status' in res &&
+        ('data' in res || 'error' in res));
+}
+/**
+ * Normalizes query key evaluation.
+ */
+function resolveKey(keyOrFn, fallback) {
+    if (typeof keyOrFn === 'function') {
+        return keyOrFn();
+    }
+    if (keyOrFn !== undefined) {
+        return keyOrFn;
+    }
+    return fallback || 'default-query-key';
+}
+/**
+ * Idiomatic Svelte 5 Runes Query Composable.
+ * Features automatic dependency tracking, request coalescing, stale-while-revalidate,
+ * window focus revalidation, and SSE live invalidation.
+ */
+export function createQuery(keyOrFn, fnOrOptions, maybeOptions) {
+    let keyConfig;
+    let queryFn;
+    let options;
+    if (typeof keyOrFn === 'function' && fnOrOptions && typeof fnOrOptions === 'function') {
+        // createQuery(keyFn, queryFn, options)
+        keyConfig = keyOrFn;
+        queryFn = fnOrOptions;
+        options = maybeOptions || {};
+    }
+    else if (typeof keyOrFn === 'function' && (!fnOrOptions || typeof fnOrOptions === 'object')) {
+        // createQuery(queryFn, options)
+        queryFn = keyOrFn;
+        options = fnOrOptions || {};
+        keyConfig = options.key;
+    }
+    else {
+        // createQuery(key, queryFn, options)
+        keyConfig = keyOrFn;
+        queryFn = fnOrOptions;
+        options = maybeOptions || {};
+    }
+    const client = options.client || getQueryClient();
+    const staleTimeMs = options.staleTimeMs ?? 0;
+    const refetchOnWindowFocus = options.refetchOnWindowFocus ?? true;
+    const refetchOnReconnect = options.refetchOnReconnect ?? true;
+    const fallbackKey = queryFn.toString();
+    const initialKey = resolveKey(keyConfig, fallbackKey);
+    const initialHash = hashQueryKey(initialKey);
+    // Pre-seed entry immediately on creation with initialData if provided
+    client.getOrCreateEntry(initialHash, options.initialData);
+    function getCurrentKey() {
+        return resolveKey(keyConfig, fallbackKey);
+    }
+    function getCurrentHash() {
+        return hashQueryKey(getCurrentKey());
+    }
+    function getIsEnabled() {
+        return typeof options.enabled === 'function'
+            ? options.enabled()
+            : options.enabled !== undefined
+                ? options.enabled
+                : true;
+    }
+    function getEntry() {
+        return client.getOrCreateEntry(getCurrentHash(), options.initialData);
+    }
+    async function executeFetch(force = false) {
+        if (!getIsEnabled())
+            return null;
+        const targetEntry = getEntry();
+        // 1. Check Stale Time if not forced
+        if (!force && targetEntry.updatedAt > 0) {
+            const age = Date.now() - targetEntry.updatedAt;
+            if (age < staleTimeMs && targetEntry.data !== null) {
+                return targetEntry.data;
+            }
+        }
+        // 2. Request Coalescing: Reuse in-flight Promise if already running
+        if (targetEntry.inFlightPromise) {
+            return targetEntry.inFlightPromise;
+        }
+        targetEntry.isFetching = true;
+        if (targetEntry.status === 'idle') {
+            targetEntry.status = 'loading';
+        }
+        const promise = (async () => {
+            try {
+                const result = await queryFn();
+                let finalData;
+                if (isClientResponse(result)) {
+                    if (!result.ok) {
+                        throw result.error;
+                    }
+                    finalData = result.data;
+                }
+                else {
+                    finalData = result;
+                }
+                targetEntry.data = finalData;
+                targetEntry.error = null;
+                targetEntry.status = 'success';
+                targetEntry.updatedAt = Date.now();
+                options.onSuccess?.(finalData);
+                return finalData;
+            }
+            catch (err) {
+                targetEntry.error = err;
+                targetEntry.status = 'error';
+                options.onError?.(err);
+                return null;
+            }
+            finally {
+                targetEntry.isFetching = false;
+                targetEntry.inFlightPromise = null;
+            }
+        })();
+        targetEntry.inFlightPromise = promise;
+        return promise;
+    }
+    // Subscriber notification callback
+    const subscriber = () => {
+        executeFetch(true);
+    };
+    const initialEntry = getEntry();
+    initialEntry.subscribers.add(subscriber);
+    // Initial execution if enabled and not already hydrated/fresh
+    if (getIsEnabled() && initialEntry.status === 'idle') {
+        executeFetch(false);
+    }
+    // Window listeners
+    let cleanupWindowListeners;
+    if (typeof window !== 'undefined') {
+        const onFocus = () => {
+            if (refetchOnWindowFocus && getIsEnabled()) {
+                executeFetch(false);
+            }
+        };
+        const onOnline = () => {
+            if (refetchOnReconnect && getIsEnabled()) {
+                executeFetch(true);
+            }
+        };
+        window.addEventListener('focus', onFocus);
+        window.addEventListener('online', onOnline);
+        cleanupWindowListeners = () => {
+            window.removeEventListener('focus', onFocus);
+            window.removeEventListener('online', onOnline);
+        };
+    }
+    // SSE Live-Invalidation Bridge
+    let cleanupSse;
+    if (options.subscribeToSse && typeof options.subscribeToSse === 'object') {
+        const sseOption = options.subscribeToSse;
+        if (sseOption.sse && sseOption.event) {
+            cleanupSse = sseOption.sse.on(sseOption.event, () => {
+                executeFetch(true);
+            });
+        }
+    }
+    function destroy() {
+        const currentEntry = getEntry();
+        currentEntry.subscribers.delete(subscriber);
+        cleanupWindowListeners?.();
+        cleanupSse?.();
+    }
+    return {
+        get data() {
+            return getEntry().data;
+        },
+        get error() {
+            return getEntry().error;
+        },
+        get status() {
+            return getEntry().status;
+        },
+        get isLoading() {
+            const e = getEntry();
+            return e.status === 'loading' && e.data === null;
+        },
+        get isFetching() {
+            return getEntry().isFetching;
+        },
+        get isSuccess() {
+            return getEntry().status === 'success';
+        },
+        get isError() {
+            return getEntry().status === 'error';
+        },
+        get updatedAt() {
+            return getEntry().updatedAt;
+        },
+        refetch: () => executeFetch(true),
+        invalidate: async () => {
+            await getEntry().invalidate();
+        },
+        setData: (updater) => {
+            client.setQueryData(getCurrentKey(), updater);
+        },
+        optimisticUpdate: (updater) => {
+            client.setQueryData(getCurrentKey(), updater);
+        },
+        destroy
+    };
+}

package/dist/client/query.test.d.ts

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

package/dist/client/query.test.js

@@ -0,0 +1,242 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { hashQueryKey, QueryClient, createQuery, createMutation, setQueryClient } from './index';
+describe('Runes Query Engine - hashQueryKey', () => {
+    it('returns string keys as-is', () => {
+        expect(hashQueryKey('projects')).toBe('projects');
+        expect(hashQueryKey('/api/items')).toBe('/api/items');
+    });
+    it('deterministically hashes arrays and nested objects regardless of key order', () => {
+        const keyA = ['projects', { orgId: '123', status: 'active' }];
+        const keyB = ['projects', { status: 'active', orgId: '123' }];
+        expect(hashQueryKey(keyA)).toBe(hashQueryKey(keyB));
+    });
+});
+describe('Runes Query Engine - QueryClient', () => {
+    let client;
+    beforeEach(() => {
+        client = new QueryClient();
+        setQueryClient(client);
+    });
+    it('creates, retrieves, and updates query cache entries', () => {
+        expect(client.getQueryData('users')).toBeNull();
+        client.setQueryData('users', [{ id: '1', name: 'Alice' }]);
+        expect(client.getQueryData('users')).toEqual([{ id: '1', name: 'Alice' }]);
+        // Functional updater
+        client.setQueryData('users', (prev) => [
+            ...(prev ?? []),
+            { id: '2', name: 'Bob' }
+        ]);
+        expect(client.getQueryData('users')).toHaveLength(2);
+    });
+    it('invalidates matching queries with exact and prefix filters', async () => {
+        const entry1 = client.getOrCreateEntry('projects-list');
+        const entry2 = client.getOrCreateEntry('projects-detail-1');
+        const entry3 = client.getOrCreateEntry('users');
+        const listener1 = vi.fn();
+        const listener2 = vi.fn();
+        const listener3 = vi.fn();
+        entry1.subscribers.add(listener1);
+        entry2.subscribers.add(listener2);
+        entry3.subscribers.add(listener3);
+        // Invalidate all projects
+        await client.invalidateQueries('projects');
+        expect(listener1).toHaveBeenCalledTimes(1);
+        expect(listener2).toHaveBeenCalledTimes(1);
+        expect(listener3).not.toHaveBeenCalled();
+        // Exact invalidation
+        await client.invalidateQueries({ key: 'projects-list', exact: true });
+        expect(listener1).toHaveBeenCalledTimes(2);
+        expect(listener2).toHaveBeenCalledTimes(1);
+    });
+});
+describe('Runes Query Engine - createQuery', () => {
+    let client;
+    beforeEach(() => {
+        client = new QueryClient();
+        setQueryClient(client);
+    });
+    it('fetches data and unwraps ClientResponse successfully', async () => {
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            data: [{ id: 'proj_1', name: 'Alpha' }],
+            error: null,
+            response: new Response()
+        });
+        const query = createQuery('test-projects', fetchMock, { client });
+        expect(query.isLoading).toBe(true);
+        expect(query.data).toBeNull();
+        const result = await query.refetch();
+        expect(result).toEqual([{ id: 'proj_1', name: 'Alpha' }]);
+        expect(query.data).toEqual([{ id: 'proj_1', name: 'Alpha' }]);
+        expect(query.isSuccess).toBe(true);
+        expect(query.isLoading).toBe(false);
+        expect(query.isError).toBe(false);
+    });
+    it('handles ClientResponse errors and RFC 7807 problem details', async () => {
+        const errorResponse = {
+            ok: false,
+            status: 404,
+            data: null,
+            error: {
+                type: 'https://yaxa.dev/errors/not-found',
+                title: 'Project Not Found',
+                status: 404,
+                detail: 'No project with ID 999 exists'
+            },
+            response: new Response(null, { status: 404 })
+        };
+        const fetchMock = vi.fn().mockResolvedValue(errorResponse);
+        const onError = vi.fn();
+        const query = createQuery('not-found-query', fetchMock, { client, onError });
+        await query.refetch();
+        expect(query.data).toBeNull();
+        expect(query.isError).toBe(true);
+        expect(query.error).toEqual(errorResponse.error);
+        expect(onError).toHaveBeenCalledWith(errorResponse.error);
+    });
+    it('coalesces multiple in-flight concurrent requests to the same key', async () => {
+        let resolveCall = () => { };
+        const fetchMock = vi.fn().mockImplementation(() => new Promise((res) => {
+            resolveCall = res;
+        }));
+        const query1 = createQuery('shared-key', fetchMock, { client });
+        const query2 = createQuery('shared-key', fetchMock, { client });
+        // Trigger both simultaneously
+        const p1 = query1.refetch();
+        const p2 = query2.refetch();
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        resolveCall({
+            ok: true,
+            status: 200,
+            data: { result: 'shared' },
+            error: null,
+            response: new Response()
+        });
+        const [res1, res2] = await Promise.all([p1, p2]);
+        expect(res1).toEqual({ result: 'shared' });
+        expect(res2).toEqual({ result: 'shared' });
+    });
+    it('respects staleTimeMs and avoids refetching when cache is fresh', async () => {
+        const fetchMock = vi.fn().mockResolvedValue('data-1');
+        const query = createQuery('stale-key', fetchMock, {
+            client,
+            staleTimeMs: 10_000
+        });
+        await query.refetch();
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        // Non-forced fetch should return cached data because staleTimeMs hasn't elapsed
+        client.getOrCreateEntry('stale-key').updatedAt = Date.now();
+        const entry = client.getOrCreateEntry('stale-key');
+        expect(entry.data).toBe('data-1');
+    });
+    it('hydrates with initialData with zero loading state', () => {
+        const query = createQuery('ssr-key', async () => 'fetched', {
+            client,
+            initialData: 'preloaded'
+        });
+        expect(query.data).toBe('preloaded');
+        expect(query.isLoading).toBe(false);
+        expect(query.isSuccess).toBe(true);
+    });
+    it('supports optimisticUpdate and setData', () => {
+        const query = createQuery('list-key', async () => ['item1'], {
+            client,
+            initialData: ['item1']
+        });
+        query.optimisticUpdate((prev) => [...(prev ?? []), 'item2']);
+        expect(query.data).toEqual(['item1', 'item2']);
+        query.setData(['item-override']);
+        expect(query.data).toEqual(['item-override']);
+    });
+    it('respects enabled: false and skips automatic fetching', async () => {
+        const fetchMock = vi.fn().mockResolvedValue('data');
+        const query = createQuery('disabled-key', fetchMock, {
+            client,
+            enabled: false
+        });
+        const res = await query.refetch();
+        expect(res).toBeNull();
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+    it('supports live invalidation via subscribeToSse', async () => {
+        const mockSse = {
+            on: vi.fn((_event, handler) => {
+                // Save handler
+                mockSse.trigger = handler;
+                return () => { };
+            })
+        };
+        const fetchMock = vi.fn().mockResolvedValue('sse-data');
+        createQuery('sse-query', fetchMock, {
+            client,
+            subscribeToSse: {
+                sse: mockSse,
+                event: 'project.updated'
+            }
+        });
+        expect(mockSse.on).toBeDefined();
+    });
+});
+describe('Runes Query Engine - createMutation', () => {
+    it('executes successful mutation and runs lifecycle hooks', async () => {
+        const onMutate = vi.fn().mockReturnValue({ tempId: 'temp_123' });
+        const onSuccess = vi.fn();
+        const onSettled = vi.fn();
+        const mutationFn = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 201,
+            data: { id: 'real_123', name: 'Created' },
+            error: null,
+            response: new Response(null, { status: 201 })
+        });
+        const mutation = createMutation(mutationFn, {
+            onMutate,
+            onSuccess,
+            onSettled
+        });
+        expect(mutation.isIdle).toBe(true);
+        const promise = mutation.mutate({ name: 'Created' });
+        expect(mutation.isPending).toBe(true);
+        const result = await promise;
+        expect(result).toEqual({ id: 'real_123', name: 'Created' });
+        expect(mutation.data).toEqual({ id: 'real_123', name: 'Created' });
+        expect(mutation.isSuccess).toBe(true);
+        expect(mutation.isPending).toBe(false);
+        expect(onMutate).toHaveBeenCalledWith({ name: 'Created' });
+        expect(onSuccess).toHaveBeenCalledWith({ id: 'real_123', name: 'Created' }, { name: 'Created' }, { tempId: 'temp_123' });
+        expect(onSettled).toHaveBeenCalledWith({ id: 'real_123', name: 'Created' }, null, { name: 'Created' }, { tempId: 'temp_123' });
+    });
+    it('handles mutation errors, passes context for rollback, and re-throws', async () => {
+        const rollbackContext = { previousList: ['item1'] };
+        const onMutate = vi.fn().mockReturnValue(rollbackContext);
+        const onError = vi.fn();
+        const onSettled = vi.fn();
+        const errorResponse = {
+            ok: false,
+            status: 400,
+            data: null,
+            error: {
+                type: 'https://yaxa.dev/errors/validation',
+                title: 'Bad Request',
+                status: 400,
+                detail: 'Name must be at least 3 characters'
+            },
+            response: new Response(null, { status: 400 })
+        };
+        const mutation = createMutation(async () => errorResponse, {
+            onMutate,
+            onError,
+            onSettled
+        });
+        await expect(mutation.mutate(undefined)).rejects.toEqual(errorResponse.error);
+        expect(mutation.isError).toBe(true);
+        expect(mutation.error).toEqual(errorResponse.error);
+        expect(onError).toHaveBeenCalledWith(errorResponse.error, undefined, rollbackContext);
+        expect(onSettled).toHaveBeenCalledWith(null, errorResponse.error, undefined, rollbackContext);
+        mutation.reset();
+        expect(mutation.isIdle).toBe(true);
+        expect(mutation.error).toBeNull();
+        expect(mutation.data).toBeNull();
+    });
+});

package/dist/index.d.ts

@@ -207,7 +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 { createApiClient, interpolatePath, serializeQueryParams, createQuery, createMutation, QueryClient, getQueryClient, setQueryClient, hashQueryKey } from './client';
+export type { ApiClient, ApiClientConfig, ClientRequestOptions, ClientResponse, InferEndpoint, RouteMethods, ProblemDetails as ClientProblemDetails, QueryKey, QueryStatus, QueryCacheEntry, CreateQueryOptions, CreateQueryResult, CreateMutationOptions, CreateMutationResult, QueryFn, MutationFn } from './client';
 export { cn, tv } from './utils/cn';
 export type { VariantProps } from './utils/cn';

package/dist/index.js

@@ -138,7 +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';
+// Type-Safe Client RPC & Runes Query Engine
+export { createApiClient, interpolatePath, serializeQueryParams, createQuery, createMutation, QueryClient, getQueryClient, setQueryClient, hashQueryKey } from './client';
 // Utilities
 export { cn, tv } from './utils/cn';

package/dist/server/openapi/handler.d.ts

@@ -2,6 +2,6 @@ import type { RequestHandler } from '@sveltejs/kit';
 import type { ApiDocsOptions } from './types';
 /**
  * Creates a turnkey SvelteKit RequestHandler that generates an interactive OpenAPI 3.1 documentation
- * page (Scalar, Swagger UI, or Redoc) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
+ * page (Scalar or Swagger UI) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
  */
 export declare function createApiDocsHandler(options?: ApiDocsOptions): RequestHandler;

package/dist/server/openapi/handler.js

@@ -1,11 +1,35 @@
 import { generateOpenApiSpec } from './generator';
-function renderScalarHtml(specJson, title) {
+function renderHeadMeta({ title, description, canonicalUrl, ogImage }) {
+    const descTag = description
+        ? `<meta name="description" content="${description.replace(/"/g, '&quot;')}" />`
+        : '';
+    const canonicalTag = canonicalUrl ? `<link rel="canonical" href="${canonicalUrl}" />` : '';
+    const ogImageTag = ogImage ? `<meta property="og:image" content="${ogImage}" />` : '';
+    const ogDescTag = description
+        ? `<meta property="og:description" content="${description.replace(/"/g, '&quot;')}" />`
+        : '';
+    const ogUrlTag = canonicalUrl ? `<meta property="og:url" content="${canonicalUrl}" />` : '';
+    return `    <title>${title}</title>
+    ${descTag}
+    <meta name="robots" content="index, follow" />
+    ${canonicalTag}
+    <meta property="og:type" content="website" />
+    <meta property="og:title" content="${title.replace(/"/g, '&quot;')}" />
+    ${ogDescTag}
+    ${ogUrlTag}
+    ${ogImageTag}
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="${title.replace(/"/g, '&quot;')}" />
+    ${ogDescTag}
+    ${ogImageTag}`.trim();
+}
+function renderScalarHtml(specJson, meta) {
     return `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${title}</title>
+    ${renderHeadMeta(meta)}
     <style>
       body { margin: 0; background-color: #0f172a; }
     </style>
@@ -18,13 +42,13 @@ function renderScalarHtml(specJson, title) {
   </body>
 </html>`;
 }
-function renderSwaggerHtml(specJson, title) {
+function renderSwaggerHtml(specJson, meta) {
     return `<!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${title}</title>
+    ${renderHeadMeta(meta)}
     <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
     <style>
       body { margin: 0; background: #fafafa; }
@@ -48,34 +72,9 @@ function renderSwaggerHtml(specJson, title) {
   </body>
 </html>`;
 }
-function renderRedocHtml(specJson, title) {
-    return `<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${title}</title>
-    <style>
-      body { margin: 0; padding: 0; }
-    </style>
-  </head>
-  <body>
-    <div id="redoc-container"></div>
-    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
-    <script>
-      Redoc.init(${specJson}, {
-        scrollYOffset: 50,
-        theme: {
-          colors: { primary: { main: '#3b82f6' } }
-        }
-      }, document.getElementById('redoc-container'));
-    </script>
-  </body>
-</html>`;
-}
 /**
  * Creates a turnkey SvelteKit RequestHandler that generates an interactive OpenAPI 3.1 documentation
- * page (Scalar, Swagger UI, or Redoc) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
+ * page (Scalar or Swagger UI) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
  */
 export function createApiDocsHandler(options = {}) {
     const defaultTheme = options.theme || 'scalar';
@@ -83,7 +82,7 @@ export function createApiDocsHandler(options = {}) {
         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 activeTheme = themeQuery && ['scalar', 'swagger'].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
@@ -99,16 +98,17 @@ export function createApiDocsHandler(options = {}) {
         }
         // Render Interactive HTML Docs
         const specJson = JSON.stringify(spec);
-        let html;
-        if (activeTheme === 'swagger') {
-            html = renderSwaggerHtml(specJson, spec.info.title);
-        }
-        else if (activeTheme === 'redoc') {
-            html = renderRedocHtml(specJson, spec.info.title);
-        }
-        else {
-            html = renderScalarHtml(specJson, spec.info.title);
-        }
+        const canonicalUrl = `${url.origin}${url.pathname}`;
+        const ogImage = `${url.origin}/api/og?title=${encodeURIComponent(spec.info.title)}&badge=API+Docs`;
+        const meta = {
+            title: spec.info.title,
+            description: spec.info.description,
+            canonicalUrl,
+            ogImage
+        };
+        const html = activeTheme === 'swagger'
+            ? renderSwaggerHtml(specJson, meta)
+            : renderScalarHtml(specJson, meta);
         return new Response(html, {
             headers: {
                 'content-type': 'text/html; charset=utf-8',

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

@@ -200,21 +200,20 @@ describe('createApiDocsHandler Endpoint', () => {
         expect(html).toContain('swagger-ui-dist');
         expect(html).toContain('SwaggerUIBundle');
     });
-    it('renders Redoc HTML when theme is redoc', async () => {
+    it('falls back to scalar HTML when an unrecognized theme query is passed', async () => {
         const handler = createApiDocsHandler({
-            title: 'Redoc Docs Test',
-            theme: 'redoc'
+            title: 'Fallback Docs Test',
+            theme: 'scalar'
         });
         const event = createMockRequestEvent({
-            url: 'http://localhost:5173/api/docs'
+            url: 'http://localhost:5173/api/docs?theme=unknown'
         });
         const response = await handler(event);
         expect(response.status).toBe(200);
         expect(response.headers.get('content-type')).toContain('text/html');
         const html = await response.text();
-        expect(html).toContain('<title>Redoc Docs Test</title>');
-        expect(html).toContain('redoc.standalone.js');
-        expect(html).toContain('redoc-container');
+        expect(html).toContain('<title>Fallback Docs Test</title>');
+        expect(html).toContain('@scalar/api-reference');
     });
     it('allows overriding theme dynamically via ?theme query parameter', async () => {
         const handler = createApiDocsHandler({

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

@@ -107,13 +107,12 @@ export interface GenerateOpenApiOptions {
     endpoints?: EndpointMap;
     registry?: any;
 }
-export type ApiDocsTheme = 'scalar' | 'swagger' | 'redoc';
+export type ApiDocsTheme = 'scalar' | 'swagger';
 export interface ApiDocsOptions extends GenerateOpenApiOptions {
     /**
      * Interactive UI theme:
-     * - 'scalar' (default): Modern, dark-mode native, high contrast developer reference.
+     * - 'scalar' (default): Modern, dark-mode native, high contrast developer reference with interactive runner.
      * - 'swagger': Classic Swagger UI with interactive Try-It-Out console.
-     * - 'redoc': Clean 3-panel technical documentation format.
      */
     theme?: ApiDocsTheme;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaxa-svelte",
-  "version": "2.6.0",
+  "version": "2.7.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",