yaxa-svelte 2.7.0 → 2.8.1

package/dist/components/blocks/FAQ.svelte.d.ts

@@ -12,6 +12,7 @@ export type FAQProps = VariantProps<typeof faqVariants> & {
     badge?: string;
     items?: FAQItem[];
     categories?: string[];
+    enableSchema?: boolean;
     class?: string;
 };
 declare const FAQ: import("svelte").Component<FAQProps, {}, "">;

package/dist/components/blocks/FAQ.test.js

@@ -1,9 +1,29 @@
 import { describe, it, expect } from 'vitest';
 import { faqVariants } from './FAQ.svelte';
+import FAQ from './FAQ.svelte';
+import { renderComponent } from '../../testing/index.js';
 describe('FAQ Block', () => {
     it('generates default variant classes', () => {
         const classes = faqVariants();
         expect(classes).toContain('w-full');
         expect(classes).toContain('max-w-3xl');
     });
+    it('renders FAQ and injects Schema.org FAQPage json-ld when enabled', () => {
+        const items = [
+            { id: 1, question: 'How does it work?', answer: 'It works seamlessly with Svelte 5.' }
+        ];
+        const { cleanup, target } = renderComponent(FAQ, {
+            items,
+            enableSchema: true
+        });
+        expect(target.textContent).toContain('How does it work?');
+        expect(target.textContent).toContain('Frequently Asked Questions');
+        const scriptTag = document.querySelector('head script[type="application/ld+json"]');
+        if (scriptTag) {
+            const json = JSON.parse(scriptTag.textContent || '{}');
+            expect(json['@type']).toBe('FAQPage');
+            expect(json.mainEntity[0].name).toBe('How does it work?');
+        }
+        cleanup();
+    });
 });

package/dist/components/saas/AuthCard.svelte

@@ -1,13 +1,5 @@
-<script lang="ts">
-	import Card from '../layout/Card.svelte';
-	import Button from '../elements/Button.svelte';
-	import Input from '../forms/Input.svelte';
-	import FormField from '../forms/FormField.svelte';
-	import InputOTP from '../forms/InputOTP.svelte';
-	import Divider from '../layout/Divider.svelte';
-	import Alert from '../overlays/Alert.svelte';
-	import Icon from '../elements/Icon.svelte';
-	import { useAuth, type SocialProvider } from '../../composables/useAuth.svelte';
+<script module lang="ts">
+	import type { SocialProvider } from '../../composables/useAuth.svelte';
 
 	export type AuthCardMode =
 		| 'signin'
@@ -18,7 +10,7 @@
 		| '2fa-verify'
 		| 'email-change';
 
-	interface Props {
+	export interface AuthCardProps {
 		title?: string;
 		subtitle?: string;
 		mode?: AuthCardMode;
@@ -33,6 +25,18 @@
 		onsuccess?: () => void;
 		onerror?: (err: string) => void;
 	}
+</script>
+
+<script lang="ts">
+	import Card from '../layout/Card.svelte';
+	import Button from '../elements/Button.svelte';
+	import Input from '../forms/Input.svelte';
+	import FormField from '../forms/FormField.svelte';
+	import InputOTP from '../forms/InputOTP.svelte';
+	import Divider from '../layout/Divider.svelte';
+	import Alert from '../overlays/Alert.svelte';
+	import Icon from '../elements/Icon.svelte';
+	import { useAuth } from '../../composables/useAuth.svelte';
 
 	let {
 		title,
@@ -48,7 +52,7 @@
 		class: className = '',
 		onsuccess,
 		onerror
-	}: Props = $props();
+	}: AuthCardProps = $props();
 
 	const auth = useAuth();
 

package/dist/components/saas/AuthCard.svelte.d.ts

@@ -1,6 +1,6 @@
-import { type SocialProvider } from '../../composables/useAuth.svelte';
+import type { SocialProvider } from '../../composables/useAuth.svelte';
 export type AuthCardMode = 'signin' | 'signup' | 'magic-link' | 'forgot-password' | 'reset-password' | '2fa-verify' | 'email-change';
-interface Props {
+export interface AuthCardProps {
     title?: string;
     subtitle?: string;
     mode?: AuthCardMode;
@@ -15,6 +15,6 @@ interface Props {
     onsuccess?: () => void;
     onerror?: (err: string) => void;
 }
-declare const AuthCard: import("svelte").Component<Props, {}, "">;
+declare const AuthCard: import("svelte").Component<AuthCardProps, {}, "">;
 type AuthCard = ReturnType<typeof AuthCard>;
 export default AuthCard;

package/dist/components/saas/ResetPasswordCard.svelte

@@ -0,0 +1,13 @@
+<script module lang="ts">
+	import type { AuthCardProps } from './AuthCard.svelte';
+
+	export type ResetPasswordCardProps = Omit<AuthCardProps, 'mode'>;
+</script>
+
+<script lang="ts">
+	import AuthCard from './AuthCard.svelte';
+
+	let props: ResetPasswordCardProps = $props();
+</script>
+
+<AuthCard mode="reset-password" {...props} />

package/dist/components/saas/ResetPasswordCard.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { AuthCardProps } from './AuthCard.svelte';
+export type ResetPasswordCardProps = Omit<AuthCardProps, 'mode'>;
+declare const ResetPasswordCard: import("svelte").Component<ResetPasswordCardProps, {}, "">;
+type ResetPasswordCard = ReturnType<typeof ResetPasswordCard>;
+export default ResetPasswordCard;

package/dist/components/saas/SignInCard.svelte

@@ -0,0 +1,13 @@
+<script module lang="ts">
+	import type { AuthCardProps } from './AuthCard.svelte';
+
+	export type SignInCardProps = Omit<AuthCardProps, 'mode'>;
+</script>
+
+<script lang="ts">
+	import AuthCard from './AuthCard.svelte';
+
+	let props: SignInCardProps = $props();
+</script>
+
+<AuthCard mode="signin" {...props} />

package/dist/components/saas/SignInCard.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { AuthCardProps } from './AuthCard.svelte';
+export type SignInCardProps = Omit<AuthCardProps, 'mode'>;
+declare const SignInCard: import("svelte").Component<SignInCardProps, {}, "">;
+type SignInCard = ReturnType<typeof SignInCard>;
+export default SignInCard;

package/dist/components/saas/SignUpCard.svelte

@@ -0,0 +1,13 @@
+<script module lang="ts">
+	import type { AuthCardProps } from './AuthCard.svelte';
+
+	export type SignUpCardProps = Omit<AuthCardProps, 'mode'>;
+</script>
+
+<script lang="ts">
+	import AuthCard from './AuthCard.svelte';
+
+	let props: SignUpCardProps = $props();
+</script>
+
+<AuthCard mode="signup" {...props} />

package/dist/components/saas/SignUpCard.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { AuthCardProps } from './AuthCard.svelte';
+export type SignUpCardProps = Omit<AuthCardProps, 'mode'>;
+declare const SignUpCard: import("svelte").Component<SignUpCardProps, {}, "">;
+type SignUpCard = ReturnType<typeof SignUpCard>;
+export default SignUpCard;

package/dist/components/saas/auth-cards.test.d.ts

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

package/dist/components/saas/auth-cards.test.js

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import AuthCard from './AuthCard.svelte';
+import SignInCard from './SignInCard.svelte';
+import SignUpCard from './SignUpCard.svelte';
+import ResetPasswordCard from './ResetPasswordCard.svelte';
+import { AuthCard as SubpathAuthCard, SignInCard as SubpathSignInCard, SignUpCard as SubpathSignUpCard, ResetPasswordCard as SubpathResetPasswordCard, PasskeyUI, TwoFactorModal, useAuth } from '../../auth/index.js';
+import { renderComponent } from '../../testing/index.js';
+describe('Turnkey Auth Suite Components', () => {
+    it('exports all auth card component definitions from yaxa-svelte/auth', () => {
+        expect(AuthCard).toBeDefined();
+        expect(SignInCard).toBeDefined();
+        expect(SignUpCard).toBeDefined();
+        expect(ResetPasswordCard).toBeDefined();
+        expect(SubpathAuthCard).toBeDefined();
+        expect(SubpathSignInCard).toBeDefined();
+        expect(SubpathSignUpCard).toBeDefined();
+        expect(SubpathResetPasswordCard).toBeDefined();
+        expect(PasskeyUI).toBeDefined();
+        expect(TwoFactorModal).toBeDefined();
+        expect(typeof useAuth).toBe('function');
+    });
+    it('renders SignInCard with sign-in fields and action buttons', () => {
+        const { cleanup, target } = renderComponent(SignInCard, {
+            title: 'Welcome Back',
+            showSocial: true
+        });
+        expect(target.textContent).toContain('Welcome Back');
+        expect(target.textContent).toContain('Sign in');
+        expect(target.textContent).toContain('GitHub');
+        expect(target.textContent).toContain('Google');
+        cleanup();
+    });
+    it('renders SignUpCard with sign-up heading and register button', () => {
+        const { cleanup, target } = renderComponent(SignUpCard, {
+            title: 'Create Your Account'
+        });
+        expect(target.textContent).toContain('Create Your Account');
+        expect(target.textContent).toContain('Create Account');
+        cleanup();
+    });
+    it('renders ResetPasswordCard with password recovery UI', () => {
+        const { cleanup, target } = renderComponent(ResetPasswordCard, {
+            title: 'Reset Password',
+            resetToken: 'test-token-123'
+        });
+        expect(target.textContent).toContain('Reset Password');
+        expect(target.textContent).toContain('Confirm New Password');
+        cleanup();
+    });
+});

package/dist/components/seo/Seo.svelte

@@ -39,10 +39,15 @@
 
 	// Read config from prop or reactive Yaxa context
 	let config = $derived(propConfig || yaxa.config);
+	let baseUrl = $derived((config.url || '').replace(/\/$/, ''));
 
-	// Dynamic resolution from props OR SvelteKit page.data (e.g. +page.server.ts load data)
+	// Dynamic resolution from props OR useSeo() OR SvelteKit page.data (e.g. +page.server.ts load data)
 	let pageData = $derived(page.data || {});
-	let pageSeo = $derived((pageData.seo as Record<string, unknown>) || {});
+	let pageSeo = $derived(
+		(yaxa.pageSeo as unknown as Record<string, unknown>) ||
+			(pageData.seo as Record<string, unknown>) ||
+			{}
+	);
 
 	let resolvedTitle = $derived(
 		propTitle ||
@@ -73,9 +78,9 @@
 	let currentUrl = $derived.by(() => {
 		if (propCanonical) return propCanonical;
 		try {
-			return `${config.url}${page.url.pathname}`;
+			return `${baseUrl}${page.url.pathname}`;
 		} catch {
-			return config.url;
+			return baseUrl;
 		}
 	});
 
@@ -83,7 +88,9 @@
 
 	let resolvedOgImageUrl = $derived.by(() => {
 		if (typeof ogImage === 'string') {
-			return ogImage.startsWith('http') ? ogImage : `${config.url}${ogImage}`;
+			return ogImage.startsWith('http')
+				? ogImage
+				: `${baseUrl}${ogImage.startsWith('/') ? '' : '/'}${ogImage}`;
 		}
 		if (typeof ogImage === 'object' && ogImage !== null) {
 			const pairs: string[] = [];
@@ -101,7 +108,7 @@
 				pairs.push(`badge=${encodeURIComponent(computeProjectBadge(config.project))}`);
 			}
 			if (img.theme) pairs.push(`theme=${encodeURIComponent(img.theme)}`);
-			return `${config.url}/api/og?${pairs.join('&')}`;
+			return `${baseUrl}/api/og?${pairs.join('&')}`;
 		}
 		if (resolvedTitle && resolvedTitle !== config.name) {
 			const pairs: string[] = [
@@ -111,9 +118,9 @@
 			if (config.project) {
 				pairs.push(`badge=${encodeURIComponent(computeProjectBadge(config.project))}`);
 			}
-			return `${config.url}/api/og?${pairs.join('&')}`;
+			return `${baseUrl}/api/og?${pairs.join('&')}`;
 		}
-		return `${config.url}${config.seo?.defaultOgImage || '/api/og'}`;
+		return `${baseUrl}${config.seo?.defaultOgImage || '/api/og'}`;
 	});
 
 	let robotsContent = $derived.by(() => {
@@ -156,7 +163,7 @@
 		<meta name="keywords" content={keywords.join(', ')} />
 	{/if}
 	<link rel="canonical" href={currentUrl} />
-	<link rel="sitemap" type="application/xml" href="{config.url}/sitemap.xml" />
+	<link rel="sitemap" type="application/xml" href="{baseUrl}/sitemap.xml" />
 	<meta name="robots" content={robotsContent} />
 	<meta name="theme-color" content={config.theme?.primaryColor || '#ff3e00'} />
 	{#if config.project?.license}

package/dist/index.d.ts

@@ -45,6 +45,8 @@ export { default as AiThought } from './components/ai/AiThought.svelte';
 export type { AiThoughtProps } from './components/ai/AiThought.svelte';
 export { default as AiToolCall } from './components/ai/AiToolCall.svelte';
 export type { AiToolCallProps, ToolCallStatus } from './components/ai/AiToolCall.svelte';
+export { useAiChat } from './components/ai/useAiChat.svelte';
+export type { UseAiChatOptions, UseAiChatReturn } from './components/ai/useAiChat.svelte';
 export { default as LineChart } from './components/charts/LineChart.svelte';
 export type { LineChartProps, LineSeries, ChartDataPoint } from './components/charts/LineChart.svelte';
 export { default as BarChart } from './components/charts/BarChart.svelte';
@@ -181,10 +183,15 @@ export { createSitemapXslHandler, generateSitemapXsl } from './site/sitemap-xsl'
 export { createOgImageHandler, generateOgSvg } from './site/og';
 export type { OgImageOptions } from './site/og';
 export { createManifestHandler } from './site/manifest';
-export { generateWebSiteSchema, generateOrganizationSchema, generateSoftwareApplicationSchema, generateSoftwareSourceCodeSchema, generatePersonSchema, generateArticleSchema, generateBreadcrumbSchema } from './site/schema';
-export type { SchemaType, BreadcrumbItem, ArticleSchemaData } from './site/schema';
+export { createLlmsTxtHandler, generateLlmsTxt } from './site/llms';
+export type { LlmsTxtOptions, LlmsSection, LlmsLink } from './site/llms';
+export { createSkillHandler, generateSkillMd } from './site/skill';
+export type { SkillOptions, SkillAction } from './site/skill';
+export { generateWebSiteSchema, generateOrganizationSchema, generateSoftwareApplicationSchema, generateSoftwareSourceCodeSchema, generatePersonSchema, generateArticleSchema, generateBreadcrumbSchema, generateFaqSchema, generateProductSchema } from './site/schema';
+export type { SchemaType, BreadcrumbItem, ArticleSchemaData, FaqItem, ProductSchemaData } from './site/schema';
 export { definePageSeo } from './site/seo-helpers';
 export type { PageSeoConfig } from './site/seo-helpers';
+export { useSeo } from './site/useSeo.svelte';
 export { yaxa } from './vite/index';
 export type { YaxaPluginOptions } from './vite/index';
 export { default as Gate } from './components/saas/Gate.svelte';

package/dist/index.js

@@ -30,6 +30,7 @@ export { default as AiChat } from './components/ai/AiChat.svelte';
 export { default as PromptBar } from './components/ai/PromptBar.svelte';
 export { default as AiThought } from './components/ai/AiThought.svelte';
 export { default as AiToolCall } from './components/ai/AiToolCall.svelte';
+export { useAiChat } from './components/ai/useAiChat.svelte';
 // Native Theme-Aware SVG Charts
 export { default as LineChart } from './components/charts/LineChart.svelte';
 export { default as BarChart } from './components/charts/BarChart.svelte';
@@ -120,8 +121,11 @@ export { createSitemapHandler } from './site/sitemap';
 export { createSitemapXslHandler, generateSitemapXsl } from './site/sitemap-xsl';
 export { createOgImageHandler, generateOgSvg } from './site/og';
 export { createManifestHandler } from './site/manifest';
-export { generateWebSiteSchema, generateOrganizationSchema, generateSoftwareApplicationSchema, generateSoftwareSourceCodeSchema, generatePersonSchema, generateArticleSchema, generateBreadcrumbSchema } from './site/schema';
+export { createLlmsTxtHandler, generateLlmsTxt } from './site/llms';
+export { createSkillHandler, generateSkillMd } from './site/skill';
+export { generateWebSiteSchema, generateOrganizationSchema, generateSoftwareApplicationSchema, generateSoftwareSourceCodeSchema, generatePersonSchema, generateArticleSchema, generateBreadcrumbSchema, generateFaqSchema, generateProductSchema } from './site/schema';
 export { definePageSeo } from './site/seo-helpers';
+export { useSeo } from './site/useSeo.svelte';
 export { yaxa } from './vite/index';
 // SaaS Suite: UI Components & Composables (Pure UI & Context Runes)
 export { default as Gate } from './components/saas/Gate.svelte';

package/dist/root-purity.test.d.ts

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

package/dist/root-purity.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import * as rootExports from './index';
+import fs from 'node:fs';
+import path from 'node:path';
+describe('Root Entry Point Purity (yaxa-svelte)', () => {
+    const FORBIDDEN_EXPORTS = [
+        // Better-Auth client cards & composables (strictly yaxa-svelte/auth)
+        'useAuth',
+        'AuthCard',
+        'SignInCard',
+        'SignUpCard',
+        'ResetPasswordCard',
+        'PasskeyUI',
+        'TwoFactorModal',
+        'createYaxaAuth',
+        // Database & ORM (strictly yaxa-svelte/db)
+        'getDb',
+        'schemaPg',
+        'schemaSqlite',
+        // Server endpoints & pipeline (strictly yaxa-svelte/server)
+        'yaxaEndpoint',
+        'requireAuth',
+        'requireRole',
+        'createAiStreamHandler',
+        'createApiDocsHandler',
+        'yaxaSSE',
+        'broadcast',
+        'enqueueJob',
+        'defineWorker',
+        'createJobRunner',
+        // Admin (strictly yaxa-svelte/admin)
+        'createYaxaAdminHook',
+        'createDrizzleAdmin',
+        'AdminDashboard',
+        // Polar billing (strictly yaxa-svelte/polar)
+        'createPolarCheckout',
+        'createPolarWebhookHandler',
+        // Resend emails (strictly yaxa-svelte/email)
+        'sendMagicLinkEmail',
+        'sendWelcomeEmail',
+        // Storage uploads (strictly yaxa-svelte/storage)
+        'createPresignedUploadUrl'
+    ];
+    it('must NOT export any Better-Auth, database, or server backend primitives', () => {
+        for (const name of FORBIDDEN_EXPORTS) {
+            expect(rootExports[name], `Accidental re-export of '${name}' in root 'yaxa-svelte'! Must be in appropriate subpath ('yaxa-svelte/auth', 'yaxa-svelte/server', etc.)`).toBeUndefined();
+        }
+    });
+    it('src/lib/index.ts source must not reference restricted subpaths or heavy backend peer dependencies', () => {
+        const indexPath = path.resolve('src/lib/index.ts');
+        const source = fs.readFileSync(indexPath, 'utf-8');
+        const FORBIDDEN_SUBPATHS = [
+            './auth',
+            './server',
+            './db',
+            './polar',
+            './email',
+            './storage',
+            './admin',
+            'better-auth',
+            'drizzle-orm',
+            '@polar-sh/sdk',
+            'resend',
+            '@aws-sdk'
+        ];
+        for (const forbidden of FORBIDDEN_SUBPATHS) {
+            expect(source.includes(forbidden), `src/lib/index.ts contains forbidden reference: '${forbidden}'`).toBe(false);
+        }
+    });
+    it('src/lib/index.ts must not re-export auth card components', () => {
+        const indexPath = path.resolve('src/lib/index.ts');
+        const source = fs.readFileSync(indexPath, 'utf-8');
+        const FORBIDDEN_AUTH_CARDS = [
+            'AuthCard',
+            'SignInCard',
+            'SignUpCard',
+            'ResetPasswordCard',
+            'PasskeyUI',
+            'TwoFactorModal',
+            'useAuth'
+        ];
+        for (const card of FORBIDDEN_AUTH_CARDS) {
+            const regex = new RegExp(`\\b${card}\\b`);
+            expect(regex.test(source), `src/lib/index.ts contains forbidden auth component: '${card}'`).toBe(false);
+        }
+    });
+    it('root entry point successfully evaluates without throwing runtime errors', () => {
+        expect(rootExports).toBeDefined();
+        expect(typeof rootExports.Button).toBe('function');
+        expect(typeof rootExports.Modal).toBe('function');
+        expect(typeof rootExports.Gate).toBe('function');
+        expect(typeof rootExports.UserMenu).toBe('function');
+        expect(typeof rootExports.useGate).toBe('function');
+        expect(typeof rootExports.useYaxa).toBe('function');
+    });
+});

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

@@ -0,0 +1,2 @@
+export { createAiStreamHandler } from './stream';
+export type { AiStreamChunk, AiStreamContext, AiStreamHandlerFn, CreateAiStreamHandlerOptions } from './types';

package/dist/server/ai/index.js

@@ -0,0 +1 @@
+export { createAiStreamHandler } from './stream';

package/dist/server/ai/stream.d.ts

@@ -0,0 +1,24 @@
+import type { RequestHandler } from '@sveltejs/kit';
+import type { CreateAiStreamHandlerOptions } from './types';
+/**
+ * Creates a turnkey SvelteKit RequestHandler for AI chat streaming.
+ * Supports Server-Sent Events (SSE), multi-provider backends (Gemini, OpenAI, Anthropic, Ollama),
+ * guarded endpoints (auth/rate-limiting), and a built-in zero-config mock generator for dev/demos.
+ *
+ * @example
+ * ```ts
+ * // src/routes/api/ai/chat/+server.ts
+ * import { createAiStreamHandler, requireAuth } from 'yaxa-svelte/server';
+ *
+ * export const POST = createAiStreamHandler({
+ *   guards: [requireAuth()],
+ *   handler: async ({ messages, send }) => {
+ *     // Integrate your favorite LLM SDK
+ *     for await (const chunk of streamText({ model: 'gemini-2.5-pro', messages })) {
+ *       send({ type: 'text', delta: chunk.text });
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function createAiStreamHandler(options?: CreateAiStreamHandlerOptions): RequestHandler;

package/dist/server/ai/stream.js

@@ -0,0 +1,178 @@
+import { problemResponse } from '../endpoint/problem';
+/**
+ * Creates a turnkey SvelteKit RequestHandler for AI chat streaming.
+ * Supports Server-Sent Events (SSE), multi-provider backends (Gemini, OpenAI, Anthropic, Ollama),
+ * guarded endpoints (auth/rate-limiting), and a built-in zero-config mock generator for dev/demos.
+ *
+ * @example
+ * ```ts
+ * // src/routes/api/ai/chat/+server.ts
+ * import { createAiStreamHandler, requireAuth } from 'yaxa-svelte/server';
+ *
+ * export const POST = createAiStreamHandler({
+ *   guards: [requireAuth()],
+ *   handler: async ({ messages, send }) => {
+ *     // Integrate your favorite LLM SDK
+ *     for await (const chunk of streamText({ model: 'gemini-2.5-pro', messages })) {
+ *       send({ type: 'text', delta: chunk.text });
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function createAiStreamHandler(options = {}) {
+    const mockConfig = options.mock === true || (options.mock === undefined && !options.handler)
+        ? { delayMs: 25 }
+        : typeof options.mock === 'object'
+            ? { delayMs: options.mock.delayMs ?? 25 }
+            : null;
+    return async (event) => {
+        const { request, locals } = event;
+        // 1. Evaluate guards if configured
+        if (options.guards && options.guards.length > 0) {
+            for (const guard of options.guards) {
+                const result = await guard(event);
+                if (result instanceof Response) {
+                    return result;
+                }
+                if (result && typeof result === 'object' && 'status' in result && 'title' in result) {
+                    return problemResponse(result);
+                }
+                if (result === false) {
+                    return problemResponse({
+                        status: 403,
+                        title: 'Forbidden',
+                        detail: 'Access denied by endpoint guard.'
+                    });
+                }
+            }
+        }
+        // 2. Parse request payload
+        let messages = [];
+        try {
+            const body = await request.json();
+            messages = Array.isArray(body?.messages) ? body.messages : [];
+        }
+        catch {
+            return problemResponse({
+                status: 400,
+                title: 'Bad Request',
+                detail: 'Invalid JSON request body. Expected an object with a "messages" array.'
+            });
+        }
+        await options.onStart?.(event);
+        const user = locals?.user ?? null;
+        const encoder = new TextEncoder();
+        const signal = request.signal;
+        const stream = new ReadableStream({
+            async start(controller) {
+                let isClosed = false;
+                function safeEnqueue(str) {
+                    if (!isClosed && !signal.aborted) {
+                        try {
+                            controller.enqueue(encoder.encode(str));
+                        }
+                        catch {
+                            isClosed = true;
+                        }
+                    }
+                }
+                function sendChunk(chunk) {
+                    safeEnqueue(`data: ${JSON.stringify(chunk)}\n\n`);
+                }
+                const ctx = {
+                    event,
+                    messages,
+                    user,
+                    signal,
+                    send: sendChunk
+                };
+                try {
+                    if (options.handler) {
+                        const res = await options.handler(ctx);
+                        if (res && typeof res[Symbol.asyncIterator] === 'function') {
+                            for await (const chunk of res) {
+                                if (signal.aborted)
+                                    break;
+                                sendChunk(chunk);
+                            }
+                        }
+                    }
+                    else if (mockConfig) {
+                        // Simulated Realistic AI Flow: Thought -> Streamed Text -> Done
+                        const lastUserMsg = [...messages].reverse().find((m) => m.role === 'user');
+                        const prompt = lastUserMsg?.content || 'Hello';
+                        // 1. Thought start
+                        sendChunk({
+                            type: 'thought',
+                            thought: {
+                                running: true,
+                                text: 'Analyzing request and inspecting context...',
+                                steps: ['Interpreting prompt semantics', 'Checking relevant system tools']
+                            }
+                        });
+                        await new Promise((r) => setTimeout(r, Math.max(10, mockConfig.delayMs * 2)));
+                        if (signal.aborted)
+                            return;
+                        // 2. Thought finish
+                        sendChunk({
+                            type: 'thought',
+                            thought: {
+                                running: false,
+                                duration: 0.8,
+                                text: 'Context analyzed. Formulating response.',
+                                steps: ['Interpreting prompt semantics', 'Synthesizing output response']
+                            }
+                        });
+                        // 3. Stream response tokens
+                        const mockText = `I have received your request: "${prompt}".\n\nThis response is streamed live via Yaxa's \`createAiStreamHandler\` using Server-Sent Events (SSE). You can connect this seamlessly with OpenAI, Google Gemini, Anthropic, or local Ollama models.`;
+                        const words = mockText.split(' ');
+                        for (let i = 0; i < words.length; i++) {
+                            if (signal.aborted)
+                                break;
+                            const word = words[i] + (i === words.length - 1 ? '' : ' ');
+                            sendChunk({ type: 'text', delta: word });
+                            if (mockConfig.delayMs > 0) {
+                                await new Promise((r) => setTimeout(r, mockConfig.delayMs));
+                            }
+                        }
+                        if (!signal.aborted) {
+                            sendChunk({ type: 'done' });
+                        }
+                    }
+                    if (!isClosed) {
+                        isClosed = true;
+                        controller.close();
+                    }
+                }
+                catch (err) {
+                    if (!isClosed && !signal.aborted) {
+                        sendChunk({
+                            type: 'error',
+                            error: err instanceof Error ? err.message : String(err)
+                        });
+                        isClosed = true;
+                        try {
+                            controller.close();
+                        }
+                        catch {
+                            // Controller may already be closed
+                        }
+                    }
+                    await options.onError?.(err, event);
+                }
+            },
+            cancel() {
+                // Client cancelled stream
+            }
+        });
+        return new Response(stream, {
+            headers: {
+                'Content-Type': 'text/event-stream; charset=utf-8',
+                'Cache-Control': 'no-cache, no-transform',
+                Connection: 'keep-alive',
+                'X-Accel-Buffering': 'no'
+            }
+        });
+    };
+}