yaxa-svelte 2.7.0 → 2.8.1

package/README.md

@@ -41,7 +41,7 @@ _Nuxt UI v4 & Nuxt UI Pro Equivalent for SvelteKit 2 & 3 & Svelte 5 with Built-i
 - 🚀 **100% DRY SEO Parity**: Automate dynamic Open Graph cards (`/api/og`), environment-aware `robots.txt`, XML sitemaps with human-readable `sitemap.xsl` stylesheets, PWA manifests, and Schema.org JSON-LD from a single `src/site.config.ts`.
 - 🔐 **Batteries-Included SaaS Suite**: Pre-integrated **Better-Auth**, multi-dialect **Drizzle ORM** (Neon PostgreSQL & Turso LibSQL/SQLite), **Polar.sh** payments & webhook sync, and **Resend** transactional emails.
 - 🧩 **50+ Production Components**: Elements, compound `<Skeleton recipe="...">` layouts, AI primitives, charts, advanced forms (`<RichTextEditor>`, `<PhoneInput>`, `<CreditCardInput>`), layout, overlays, sliding segmented `<Tabs>`, native `<Toast>` / `<Toaster>`, and drop-in SaaS widgets (`<AuthCard>`, `<UserMenu>`, `<PricingTable>`, `<SubscriptionCard>`).
-- 🛠️ **Composable Runes**: `useAuth`, `useShortcuts`, `useClipboard`, `useColorMode`, `useToast`, `useMediaQuery`, `useDebounce`, `useIdle`, `useGate`.
+- 🛠️ **Composable Runes**: `useShortcuts`, `useClipboard`, `useColorMode`, `useToast`, `useMediaQuery`, `useDebounce`, `useIdle`, `useGate`, `useAuth` (`yaxa-svelte/auth`).
 
 ---
 
@@ -170,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';
 
@@ -185,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()`)
@@ -193,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>
-```
+````
 
 ---
 
@@ -399,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:
@@ -509,20 +553,21 @@ A zero-overhead, runes-native query and mutation cache built specifically for Sv
 
 ## 📦 Subpath Exports Architecture
 
-| 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'`                                                                                                                                               |
+| 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'`                                                                                                                                                                       |
 
 ---
 
@@ -531,16 +576,16 @@ A zero-overhead, runes-native query and mutation cache built specifically for Sv
 | 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**  | `<Gate>`, `<UserMenu>`, `<OrgSwitcher>`, `<PricingCard>`, `<PricingTable>`, `<SubscriptionCard>`, `useGate`, `useUpload` (Root); `<SignInCard>`, `<SignUpCard>`, `<ResetPasswordCard>`, `<AuthCard>`, `<PasskeyUI>`, `<TwoFactorModal>`, `useAuth` (`yaxa-svelte/auth`)                                                  |
 | **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>`                               |
 | **Layout & Blocks**    | `Container`, `Header`, `Footer`, `Section`, `Card`, `Divider`, `YaxaApp`, `DashboardShell` (with independent sidebar tokens), `ResizablePanels`, Page Blocks (`Hero`, `SaaS Metrics`, `FAQ`, `Testimonials`, `FeatureGrid`)                                                                                              |
 | **Overlays & Nav**     | `Tabs`, `Breadcrumb`, `Pagination`, `CommandPalette` (`⌘K`), `DropdownMenu`, `ContextMenu`, `Modal`, `Drawer`, `Slideover`, `Popover`, `Tooltip` (with `arrow={false}` & `unstyled`), `Alert`, `Accordion`, `NotificationCenter`, `Stepper`                                                                              |
 | **Motion & Actions**   | `springTilt`, `smoothSlide`, `staggerFly`, `autosize`, `clickOutside`, `portal`, `sortableItem`, `infiniteScrollAction`                                                                                                                                                                                                  |
-| **Composables**        | `useAuth`, `useGate`, `useUpload`, `useClipboard`, `useShortcuts`, `useColorMode`, `useToast`, `useMediaQuery`, `useDebounce`, `useIdle`, `useInfiniteScroll`, `useSortable`, `useDataTable`, `useLocale`                                                                                                                |
+| **Composables**        | `useGate`, `useUpload`, `useClipboard`, `useShortcuts`, `useColorMode`, `useToast`, `useMediaQuery`, `useDebounce`, `useIdle`, `useInfiniteScroll`, `useSortable`, `useDataTable`, `useLocale` (Root); `useAuth` (`yaxa-svelte/auth`)                                                                                    |
 
 ---
 

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/components/ai/ai.test.js

@@ -1,13 +1,80 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi, afterEach } from 'vitest';
 import AiChat from './AiChat.svelte';
 import PromptBar from './PromptBar.svelte';
 import AiThought from './AiThought.svelte';
 import AiToolCall from './AiToolCall.svelte';
+import { useAiChat } from './useAiChat.svelte';
 describe('AI-Native Components', () => {
     it('should export all AI component definitions', () => {
         expect(AiChat).toBeDefined();
         expect(PromptBar).toBeDefined();
         expect(AiThought).toBeDefined();
         expect(AiToolCall).toBeDefined();
+        expect(typeof useAiChat).toBe('function');
+    });
+});
+describe('useAiChat Runes Composable', () => {
+    const originalFetch = globalThis.fetch;
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it('initializes with default and initial messages', () => {
+        const chat = useAiChat({
+            initialMessages: [{ id: 'init-1', role: 'user', content: 'Initial message' }]
+        });
+        expect(chat.messages).toHaveLength(1);
+        expect(chat.messages[0].content).toBe('Initial message');
+        expect(chat.input).toBe('');
+        expect(chat.loading).toBe(false);
+        expect(chat.error).toBeNull();
+    });
+    it('streams SSE text deltas and thoughts progressively into assistant message', async () => {
+        const encoder = new TextEncoder();
+        const stream = new ReadableStream({
+            start(controller) {
+                controller.enqueue(encoder.encode('data: {"type":"thought","thought":{"running":true,"text":"Analyzing..."}}\n\n'));
+                controller.enqueue(encoder.encode('data: {"type":"text","delta":"Hello "}\n\n'));
+                controller.enqueue(encoder.encode('data: {"type":"text","delta":"World!"}\n\n'));
+                controller.enqueue(encoder.encode('data: {"type":"done"}\n\n'));
+                controller.close();
+            }
+        });
+        globalThis.fetch = vi.fn().mockResolvedValue(new Response(stream, {
+            headers: { 'Content-Type': 'text/event-stream' }
+        }));
+        const chat = useAiChat();
+        chat.input = 'Say hello';
+        await chat.send();
+        expect(chat.messages).toHaveLength(2);
+        expect(chat.messages[0].role).toBe('user');
+        expect(chat.messages[0].content).toBe('Say hello');
+        expect(chat.messages[1].role).toBe('assistant');
+        expect(chat.messages[1].content).toBe('Hello World!');
+        expect(chat.messages[1].thought?.text).toBe('Analyzing...');
+        expect(chat.messages[1].isStreaming).toBe(false);
+        expect(chat.loading).toBe(false);
+        expect(chat.error).toBeNull();
+    });
+    it('handles retries and message clearing', async () => {
+        const encoder = new TextEncoder();
+        const mockResponse = () => new Response(new ReadableStream({
+            start(controller) {
+                controller.enqueue(encoder.encode('data: {"type":"text","delta":"Response 1"}\n\n'));
+                controller.enqueue(encoder.encode('data: {"type":"done"}\n\n'));
+                controller.close();
+            }
+        }));
+        globalThis.fetch = vi.fn().mockImplementation(() => Promise.resolve(mockResponse()));
+        const chat = useAiChat();
+        await chat.send('Prompt 1');
+        expect(chat.messages).toHaveLength(2);
+        expect(chat.messages[1].content).toBe('Response 1');
+        // Retrying replaces the assistant answer
+        await chat.retry();
+        expect(chat.messages).toHaveLength(2);
+        expect(chat.messages[0].content).toBe('Prompt 1');
+        // Clear empties conversation
+        chat.clear();
+        expect(chat.messages).toHaveLength(0);
     });
 });

package/dist/components/ai/index.d.ts

@@ -6,3 +6,5 @@ export { default as AiThought } from './AiThought.svelte';
 export type { AiThoughtProps } from './AiThought.svelte';
 export { default as AiToolCall } from './AiToolCall.svelte';
 export type { AiToolCallProps, ToolCallStatus } from './AiToolCall.svelte';
+export { useAiChat } from './useAiChat.svelte';
+export type { UseAiChatOptions, UseAiChatReturn } from './useAiChat.svelte';

package/dist/components/ai/index.js

@@ -2,3 +2,4 @@ export { default as AiChat } from './AiChat.svelte';
 export { default as PromptBar } from './PromptBar.svelte';
 export { default as AiThought } from './AiThought.svelte';
 export { default as AiToolCall } from './AiToolCall.svelte';
+export { useAiChat } from './useAiChat.svelte';

package/dist/components/ai/useAiChat.svelte.d.ts

@@ -0,0 +1,68 @@
+import type { AiMessage } from './AiChat.svelte';
+export interface UseAiChatOptions {
+    /**
+     * Endpoint URL for streaming chat completions.
+     * @default '/api/ai/chat'
+     */
+    api?: string;
+    /**
+     * Initial messages loaded into the chat conversation.
+     */
+    initialMessages?: AiMessage[];
+    /**
+     * Additional HTTP request headers or function returning headers.
+     */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Additional request body payload merged with `{ messages }`.
+     */
+    body?: Record<string, unknown> | (() => Record<string, unknown>);
+    /**
+     * Callback invoked when assistant finishes streaming a response.
+     */
+    onFinish?: (message: AiMessage) => void;
+    /**
+     * Callback invoked when an error occurs during streaming or fetch.
+     */
+    onError?: (error: Error) => void;
+}
+export interface UseAiChatReturn {
+    readonly messages: AiMessage[];
+    input: string;
+    readonly loading: boolean;
+    readonly error: string | null;
+    send: (content?: string, files?: File[]) => Promise<void>;
+    stop: () => void;
+    retry: (message?: AiMessage) => Promise<void>;
+    clear: () => void;
+    setMessages: (newMessages: AiMessage[]) => void;
+}
+/**
+ * Svelte 5 reactive runes composable for AI streaming chat.
+ * Direct bridge between SvelteKit streaming endpoints (`createAiStreamHandler`) and `<AiChat>`.
+ *
+ * Automatically coordinates:
+ * - Reactive messages array with user and assistant turns
+ * - Progressive streaming text deltas
+ * - `<AiThought>` real-time reasoning durations and steps
+ * - `<AiToolCall>` live tool executions and states
+ * - Abortable streams (`stop()`) and conversational retries (`retry()`)
+ *
+ * @example
+ * ```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)}
+ * />
+ * ```
+ */
+export declare function useAiChat(options?: UseAiChatOptions): UseAiChatReturn;

package/dist/components/ai/useAiChat.svelte.js

@@ -0,0 +1,258 @@
+import { SvelteDate } from 'svelte/reactivity';
+/**
+ * Svelte 5 reactive runes composable for AI streaming chat.
+ * Direct bridge between SvelteKit streaming endpoints (`createAiStreamHandler`) and `<AiChat>`.
+ *
+ * Automatically coordinates:
+ * - Reactive messages array with user and assistant turns
+ * - Progressive streaming text deltas
+ * - `<AiThought>` real-time reasoning durations and steps
+ * - `<AiToolCall>` live tool executions and states
+ * - Abortable streams (`stop()`) and conversational retries (`retry()`)
+ *
+ * @example
+ * ```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)}
+ * />
+ * ```
+ */
+export function useAiChat(options = {}) {
+    const api = options.api || '/api/ai/chat';
+    let messages = $state(options.initialMessages ? options.initialMessages.map((m) => ({ ...m })) : []);
+    let input = $state('');
+    let loading = $state(false);
+    let error = $state(null);
+    let abortController = null;
+    async function send(content, _files) {
+        void _files;
+        const prompt = (content !== undefined ? content : input).trim();
+        if (!prompt)
+            return;
+        // Reset input and clear any previous errors
+        input = '';
+        error = null;
+        loading = true;
+        // 1. Append User Message
+        const userMsg = {
+            id: `user_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+            role: 'user',
+            content: prompt,
+            createdAt: new SvelteDate()
+        };
+        messages.push(userMsg);
+        // 2. Append Assistant Placeholder Message
+        messages.push({
+            id: `asst_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+            role: 'assistant',
+            content: '',
+            isStreaming: true,
+            createdAt: new SvelteDate()
+        });
+        const assistantIdx = messages.length - 1;
+        abortController = new AbortController();
+        try {
+            const customHeaders = typeof options.headers === 'function' ? options.headers() : options.headers || {};
+            const customBody = typeof options.body === 'function' ? options.body() : options.body || {};
+            const response = await fetch(api, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...customHeaders
+                },
+                body: JSON.stringify({
+                    messages: $state.snapshot(messages),
+                    ...customBody
+                }),
+                signal: abortController.signal
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => '');
+                let detail = `Request failed with status ${response.status}`;
+                try {
+                    const json = JSON.parse(errorText);
+                    detail = json.detail || json.message || detail;
+                }
+                catch {
+                    // Response body was not JSON, retain default detail message
+                }
+                throw new Error(detail);
+            }
+            if (!response.body) {
+                throw new Error('Response body is null, cannot stream SSE chunks.');
+            }
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || '';
+                const target = messages[assistantIdx];
+                if (!target)
+                    break;
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || !trimmed.startsWith('data:'))
+                        continue;
+                    const dataStr = trimmed.slice(5).trim();
+                    if (dataStr === '[DONE]') {
+                        target.isStreaming = false;
+                        continue;
+                    }
+                    try {
+                        const chunk = JSON.parse(dataStr);
+                        if (chunk.type === 'text' && chunk.delta) {
+                            target.content += chunk.delta;
+                        }
+                        else if (chunk.type === 'thought' && chunk.thought) {
+                            target.thought = {
+                                ...target.thought,
+                                ...chunk.thought
+                            };
+                        }
+                        else if (chunk.type === 'tool_call' && chunk.tool) {
+                            if (!target.tools)
+                                target.tools = [];
+                            const existingIdx = target.tools.findIndex((t) => t.name === chunk.tool.name);
+                            if (existingIdx >= 0) {
+                                target.tools[existingIdx] = {
+                                    ...target.tools[existingIdx],
+                                    ...chunk.tool
+                                };
+                            }
+                            else {
+                                target.tools.push(chunk.tool);
+                            }
+                        }
+                        else if (chunk.type === 'error') {
+                            error = chunk.error || 'AI generation encountered an error.';
+                            target.isStreaming = false;
+                        }
+                        else if (chunk.type === 'done') {
+                            target.isStreaming = false;
+                        }
+                    }
+                    catch {
+                        // Ignore unparsable SSE frames
+                    }
+                }
+            }
+            const finalTarget = messages[assistantIdx];
+            if (finalTarget) {
+                finalTarget.isStreaming = false;
+                options.onFinish?.(finalTarget);
+            }
+        }
+        catch (err) {
+            if (err?.name === 'AbortError') {
+                // User manually aborted stream via stop()
+            }
+            else {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                error = errMsg;
+                options.onError?.(err instanceof Error ? err : new Error(errMsg));
+            }
+            const finalTarget = messages[assistantIdx];
+            if (finalTarget) {
+                finalTarget.isStreaming = false;
+            }
+        }
+        finally {
+            loading = false;
+            abortController = null;
+        }
+    }
+    function stop() {
+        if (abortController) {
+            abortController.abort();
+            abortController = null;
+        }
+        loading = false;
+        const last = messages[messages.length - 1];
+        if (last && last.role === 'assistant') {
+            last.isStreaming = false;
+        }
+    }
+    async function retry(messageToRetry) {
+        if (loading)
+            stop();
+        let targetIdx = -1;
+        if (messageToRetry) {
+            targetIdx = messages.findIndex((m) => m.id === messageToRetry.id);
+        }
+        else {
+            // Find the last assistant message
+            for (let i = messages.length - 1; i >= 0; i--) {
+                if (messages[i].role === 'assistant') {
+                    targetIdx = i;
+                    break;
+                }
+            }
+        }
+        if (targetIdx < 0)
+            return;
+        // Find the closest preceding user message
+        let promptToRetry = '';
+        for (let i = targetIdx - 1; i >= 0; i--) {
+            if (messages[i].role === 'user') {
+                promptToRetry = messages[i].content;
+                break;
+            }
+        }
+        // Remove the target message and any following messages
+        messages.splice(targetIdx);
+        if (promptToRetry) {
+            // Also pop the user message so send() doesn't duplicate it
+            if (messages.length > 0 && messages[messages.length - 1].role === 'user') {
+                messages.pop();
+            }
+            await send(promptToRetry);
+        }
+    }
+    function clear() {
+        if (loading)
+            stop();
+        messages.length = 0;
+        error = null;
+        loading = false;
+    }
+    function setMessages(newMessages) {
+        messages = newMessages.map((m) => ({ ...m }));
+    }
+    return {
+        get messages() {
+            return messages;
+        },
+        get input() {
+            return input;
+        },
+        set input(val) {
+            input = val;
+        },
+        get loading() {
+            return loading;
+        },
+        get error() {
+            return error;
+        },
+        send,
+        stop,
+        retry,
+        clear,
+        setMessages
+    };
+}

package/dist/components/blocks/FAQ.svelte

@@ -18,6 +18,7 @@
 		badge?: string;
 		items?: FAQItem[];
 		categories?: string[];
+		enableSchema?: boolean;
 		class?: string;
 	};
 </script>
@@ -26,6 +27,7 @@
 	import Icon from '../elements/Icon.svelte';
 	import Badge from '../elements/Badge.svelte';
 	import { smoothSlide } from '../../motion/transitions';
+	import { generateFaqSchema } from '../../site/schema.js';
 
 	let {
 		title = 'Frequently Asked Questions',
@@ -33,9 +35,12 @@
 		badge = 'FAQ',
 		items = [],
 		categories = [],
+		enableSchema = true,
 		class: className = ''
 	}: FAQProps = $props();
 
+	let faqSchema = $derived(enableSchema && items.length > 0 ? generateFaqSchema(items) : null);
+
 	let selectedCategory = $state('all');
 	let openIds = $state<Array<string | number>>([]);
 
@@ -58,6 +63,12 @@
 	}
 </script>
 
+<svelte:head>
+	{#if faqSchema}
+		{@html `<script type="application/ld+json">${JSON.stringify(faqSchema)}</` + `script>`}
+	{/if}
+</svelte:head>
+
 <section class={faqVariants({ class: className })}>
 	{#if title || description || badge}
 		<div class="mb-10 space-y-3 text-center">