yaxa-svelte 2.6.0 → 2.8.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>
 
@@ -163,7 +170,7 @@ Handle **all 5 SEO endpoints** and **Better-Auth session parsing** in `src/hooks
 ```ts
 // src/hooks.server.ts
 import { sequence } from '@sveltejs/kit/hooks';
-import { createYaxaHook } from 'yaxa-svelte/server';
+import { createYaxaHook } from 'yaxa-svelte/seo';
 import { createYaxaAuth, createYaxaAuthHook } from 'yaxa-svelte/auth';
 import { siteConfig } from './site.config';
 
@@ -178,6 +185,10 @@ const authHook = createYaxaAuthHook({
 export const handle = sequence(yaxaHook, authHook);
 ```
 
+> **Pure Static Sites (`@sveltejs/adapter-static`):** Import directly from `yaxa-svelte/seo` (`createSitemapHandler`, `createRobotsHandler`, `createOgImageHandler`, `generateSitemapXsl`) with `export const prerender = true`. Completely headless with **zero DB, auth, or server runtime peer dependencies**.
+
+````
+
 ---
 
 ## 🛡️ Declarative Feature Gating (`<Gate />` & `useGate()`)
@@ -186,16 +197,16 @@ Declarative and programmatic subscription tier and RBAC gating with automatic Sv
 
 ```svelte
 <script lang="ts">
-	import { Gate, useGate } from 'yaxa-svelte';
+ import { Gate, useGate } from 'yaxa-svelte';
 
-	const gate = useGate();
+ const gate = useGate();
 </script>
 
 <!-- 0 props needed when wrapped in <YaxaApp user={data.user}> -->
 <Gate requiredPlan="pro" preview={true}>
-	<AdvancedAnalyticsWidget />
+ <AdvancedAnalyticsWidget />
 </Gate>
-```
+````
 
 ---
 
@@ -276,7 +287,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 +297,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 +306,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.
 
@@ -392,6 +403,46 @@ await broadcast(`org:${orgId}`, 'invoice.settled', {
 
 ---
 
+## 🤖 AI Streaming Bridge & Runes Chat (`useAiChat` & `createAiStreamHandler`)
+
+Zero-boilerplate bridge connecting SvelteKit streaming endpoints directly to `<AiChat>`, with progressive text streaming, thought duration/step inspection, tool invocation cards, and abortable retries:
+
+```ts
+// 1. Server Streaming Endpoint (src/routes/api/ai/chat/+server.ts)
+import { createAiStreamHandler, requireAuth } from 'yaxa-svelte/server';
+
+export const POST = createAiStreamHandler({
+	guards: [requireAuth()],
+	// Built-in realistic mock streaming for instant zero-config dev & demos,
+	// or provide your custom handler with Google Gemini, Anthropic, or OpenAI:
+	handler: async function* ({ messages }) {
+		yield { type: 'thought', thought: { running: true, text: 'Analyzing user request...' } };
+		// Yield text deltas, thoughts, and tool call states
+		yield { type: 'text', delta: 'Hello from your AI backend!' };
+		yield { type: 'done' };
+	}
+});
+```
+
+```svelte
+<!-- 2. Svelte 5 Client Chat (+page.svelte) -->
+<script lang="ts">
+	import { AiChat, useAiChat } from 'yaxa-svelte';
+
+	const chat = useAiChat({ api: '/api/ai/chat' });
+</script>
+
+<AiChat
+	messages={chat.messages}
+	loading={chat.loading}
+	onsend={(text) => chat.send(text)}
+	onstop={() => chat.stop()}
+	onretry={(msg) => chat.retry(msg)}
+/>
+```
+
+---
+
 ## 🔗 End-to-End Type-Safe Client RPC (`createApiClient`)
 
 Zero-codegen end-to-end type safety bridging your server `yaxaEndpoint` routes directly into Svelte 5 components and universal `load` functions. Adds less than 500 bytes gzipped to your client bundle:
@@ -441,22 +492,82 @@ 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/seo`       | Standalone SEO & Agent Engine: Sitemaps, robots.txt, XSL stylesheets, OpenGraph SVG, Schema.org JSON-LD (FAQPage, Product), WebManifest, llms.txt, skill.md, `useSeo()` runes, and prerendering utilities (Zero DB/Auth dependencies; 100% compatible with `@sveltejs/adapter-static`) |
+| `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`), AI Streaming (`createAiStreamHandler`), Background Jobs (`enqueueJob`, `createJobRunner`), `eventBus`, Server Hooks, DB, Storage & Email                     |
+| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<SignInCard />`, `<SignUpCard />`, `<ResetPasswordCard />`, `<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'`                                                                                                                                                                       |
 
 ---
 
@@ -465,9 +576,9 @@ export const load = async ({ fetch }) => {
 | Category               | Components                                                                                                                                                                                                                                                                                                               |
 | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Theming & Studio**   | `<ThemeStudio>`, `theme`, `ACCENT_PALETTES`, `NEUTRAL_PALETTES`, `RADIUS_PRESETS`, Harmonic Radius Multiplier Scale, Chart Palette Series Tokens                                                                                                                                                                         |
-| **AI Primitives**      | `<AiChat>`, `<PromptBar>`, `<AiThought>`, `<AiToolCall>`                                                                                                                                                                                                                                                                 |
+| **AI Primitives**      | `<AiChat>`, `<PromptBar>`, `<AiThought>`, `<AiToolCall>`, `useAiChat`                                                                                                                                                                                                                                                    |
 | **Charts (Pure SVG)**  | `<LineChart>`, `<BarChart>`, `<DonutChart>` (0 external charting dependencies, auto-responsive, dark/light theme aware)                                                                                                                                                                                                  |
-| **SaaS & Auth Suite**  | `<PasskeyUI>` (WebAuthn), `<TwoFactorModal>` (TOTP), `<AuthCard>` (Polymorphic), `<Gate>`, `<UserMenu>`, `<OrgSwitcher>`, `<PricingCard>`, `<PricingTable>`, `<SubscriptionCard>`, `useAuth`, `useGate`, `useUpload`                                                                                                     |
+| **SaaS & Auth Suite**  | `<SignInCard>`, `<SignUpCard>`, `<ResetPasswordCard>`, `<PasskeyUI>` (WebAuthn), `<TwoFactorModal>` (TOTP), `<AuthCard>` (Polymorphic), `<Gate>`, `<UserMenu>`, `<OrgSwitcher>`, `<PricingCard>`, `<PricingTable>`, `<SubscriptionCard>`, `useAuth`, `useGate`, `useUpload`                                              |
 | **Admin Suite**        | `<AdminDashboard>`, `<RecordDrawer>`, `<DevSandbox>`, `<ImpersonationBanner>`, `createYaxaAdminHook`, `createDrizzleAdmin`                                                                                                                                                                                               |
 | **Elements & Code**    | `<CodeDiff>` (Interactive Diff & Changelog), `<CodeBlock>`, `<DataTable>` (Client & Server Modes), `Button`, `ButtonGroup`, `Badge`, `Avatar`, `AvatarGroup`, `Chip`, `Meter`, `MetricCard`, `Kbd`, `Icon`, `Spinner`, `Progress`, `Skeleton`, `Link`, `Logo`, `Tree`, `Timeline`, `Terminal`, `VirtualList`, `Carousel` |
 | **Forms (Auto-Wired)** | `<Form>`, `<FormField>`, `Input`, `InputOTP`, `Textarea`, `Checkbox`, `Switch`, `Select`, `Combobox`, `MultiSelect`, `NumberInput`, `PhoneInput`, `CreditCardInput`, `RadioGroup`, `Slider`, `ColorPicker`, `ToggleGroup`, `DatePicker`, `DateRangePicker`, `Dropzone`, `<RichTextEditor>`                               |

package/dist/auth/index.d.ts

@@ -1,5 +1,11 @@
 export { default as AuthCard } from '../components/saas/AuthCard.svelte';
-export type { AuthCardMode } from '../components/saas/AuthCard.svelte';
+export type { AuthCardProps, AuthCardMode } from '../components/saas/AuthCard.svelte';
+export { default as SignInCard } from '../components/saas/SignInCard.svelte';
+export type { SignInCardProps } from '../components/saas/SignInCard.svelte';
+export { default as SignUpCard } from '../components/saas/SignUpCard.svelte';
+export type { SignUpCardProps } from '../components/saas/SignUpCard.svelte';
+export { default as ResetPasswordCard } from '../components/saas/ResetPasswordCard.svelte';
+export type { ResetPasswordCardProps } from '../components/saas/ResetPasswordCard.svelte';
 export { default as PasskeyUI, passkeyUiVariants } from '../components/saas/PasskeyUI.svelte';
 export type { PasskeyUiProps } from '../components/saas/PasskeyUI.svelte';
 export { default as TwoFactorModal } from '../components/saas/TwoFactorModal.svelte';

package/dist/auth/index.js

@@ -1,5 +1,8 @@
 // Yaxa SaaS Auth Suite (Better-Auth integration for Svelte 5 & SvelteKit)
 export { default as AuthCard } from '../components/saas/AuthCard.svelte';
+export { default as SignInCard } from '../components/saas/SignInCard.svelte';
+export { default as SignUpCard } from '../components/saas/SignUpCard.svelte';
+export { default as ResetPasswordCard } from '../components/saas/ResetPasswordCard.svelte';
 export { default as PasskeyUI, passkeyUiVariants } from '../components/saas/PasskeyUI.svelte';
 export { default as TwoFactorModal } from '../components/saas/TwoFactorModal.svelte';
 export { useAuth } from '../composables/useAuth.svelte';

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;
+}