skrypt-ai 0.6.1 → 0.8.0

package/dist/template/src/app/reference/route.ts

@@ -1,5 +1,3 @@
-import { ApiReference } from '@scalar/nextjs-api-reference'
-
 const MOCK_SERVER_ENABLED = process.env.NEXT_PUBLIC_MOCK_SERVER === 'true'
 
 // Build servers list
@@ -18,19 +16,25 @@ const servers = [
   }] : []),
 ]
 
-export const GET = ApiReference({
-  spec: {
-    url: '/api/openapi',
-  },
-  // Scalar configuration options
-  theme: 'default',
-  hideModels: false,
-  darkMode: true,
-  servers,
-  // Enable request sharing (#76)
-  showSidebar: true,
-  searchHotKey: 'k',
-  metaData: {
-    title: 'API Reference',
-  },
-})
+// Dynamic import — @scalar/nextjs-api-reference is only loaded when
+// this route is actually hit (not bundled into the main docs pages)
+export const GET = async () => {
+  const { ApiReference } = await import('@scalar/nextjs-api-reference')
+  const handler = ApiReference({
+    spec: {
+      url: '/api/openapi',
+    },
+    // Scalar configuration options
+    theme: 'default',
+    hideModels: false,
+    darkMode: true,
+    servers,
+    // Enable request sharing (#76)
+    showSidebar: true,
+    searchHotKey: 'k',
+    metaData: {
+      title: 'API Reference',
+    },
+  })
+  return handler()
+}

package/dist/template/src/app/sitemap.ts

@@ -52,7 +52,7 @@ async function scanDir(dir: string, prefix: string): Promise<string[]> {
 
       if (entry.isDirectory()) {
         files.push(...await scanDir(join(dir, entry.name), path))
-      } else if (entry.name.endsWith('.mdx') || entry.name.endsWith('.md')) {
+      } else if ((entry.name.endsWith('.mdx') || entry.name.endsWith('.md')) && !entry.name.startsWith('llms') && !entry.name.startsWith('_') && entry.name !== 'README.md') {
         files.push(path)
       }
     }

package/dist/template/src/components/ai-chat-impl.tsx

@@ -0,0 +1,206 @@
+'use client'
+
+import { useState, useRef, useEffect } from 'react'
+import { useChat } from '@ai-sdk/react'
+import { Streamdown } from 'streamdown'
+import { MessageSquare, X, Send, ExternalLink } from 'lucide-react'
+
+interface Citation {
+  title: string
+  path: string
+  snippet: string
+}
+
+interface AIChatProps {
+  projectName?: string
+  apiEndpoint?: string
+  placeholder?: string
+}
+
+export function AIChat({
+  projectName = 'this documentation',
+  apiEndpoint = '/api/chat',
+  placeholder = 'Ask a question...',
+}: AIChatProps) {
+  const [isOpen, setIsOpen] = useState(false)
+  const [citations, setCitations] = useState<Map<string, Citation[]>>(new Map())
+  const messagesEndRef = useRef<HTMLDivElement>(null)
+
+  const { messages, input, handleInputChange, handleSubmit, status, error } = useChat({
+    api: apiEndpoint,
+    onResponse(response: Response) {
+      // Extract citations from response header
+      const citationsHeader = response.headers.get('X-Citations')
+      if (citationsHeader) {
+        try {
+          const parsed = JSON.parse(atob(citationsHeader)) as Citation[]
+          // Associate citations with the next assistant message
+          setCitations(prev => {
+            const next = new Map(prev)
+            // Use a temporary key that will be replaced when the message arrives
+            next.set('_pending', parsed)
+            return next
+          })
+        } catch {
+          // Skip invalid citations
+        }
+      }
+    },
+    onFinish(message: { id: string }) {
+      // Move pending citations to the actual message ID
+      setCitations(prev => {
+        const next = new Map(prev)
+        const pending = next.get('_pending')
+        if (pending) {
+          next.delete('_pending')
+          next.set(message.id, pending)
+        }
+        return next
+      })
+    },
+  })
+
+  const isStreaming = status === 'streaming'
+  const isLoading = status === 'submitted'
+
+  useEffect(() => {
+    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
+  }, [messages, isStreaming])
+
+  if (!isOpen) {
+    return (
+      <button
+        onClick={() => setIsOpen(true)}
+        className="fixed bottom-6 right-6 z-50 flex h-14 w-14 items-center justify-center rounded-full bg-[var(--color-text)] text-[var(--color-bg)] shadow-lg transition-transform hover:scale-105"
+        aria-label="Open AI chat"
+      >
+        <MessageSquare className="h-6 w-6" />
+      </button>
+    )
+  }
+
+  return (
+    <div className="fixed bottom-6 right-6 z-50 flex h-[500px] w-[380px] flex-col overflow-hidden rounded-2xl border border-[var(--color-border)] bg-[var(--color-bg)] shadow-2xl">
+      {/* Header */}
+      <div className="flex items-center justify-between border-b border-[var(--color-border)] px-4 py-3">
+        <div className="flex items-center gap-2">
+          <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-[var(--color-text)]">
+            <MessageSquare className="h-4 w-4 text-[var(--color-bg)]" />
+          </div>
+          <div>
+            <p className="text-sm font-medium text-[var(--color-text)]">Ask AI</p>
+            <p className="text-xs text-[var(--color-text-tertiary)]">About {projectName}</p>
+          </div>
+        </div>
+        <button
+          onClick={() => setIsOpen(false)}
+          className="rounded-lg p-1 text-[var(--color-text-tertiary)] transition-colors hover:bg-[var(--color-bg-secondary)] hover:text-[var(--color-text-secondary)]"
+          aria-label="Close chat"
+        >
+          <X className="h-5 w-5" />
+        </button>
+      </div>
+
+      {/* Messages */}
+      <div className="flex-1 overflow-y-auto p-4 space-y-4">
+        {messages.length === 0 && (
+          <div className="text-center text-sm text-[var(--color-text-tertiary)] py-8">
+            <p>Ask me anything about {projectName}.</p>
+            <p className="mt-2 text-xs">I&apos;ll search the docs and give you an answer with sources.</p>
+          </div>
+        )}
+
+        {messages.map((message) => (
+          <div
+            key={message.id}
+            className={`flex ${message.role === 'user' ? 'justify-end' : 'justify-start'}`}
+          >
+            <div
+              className={`max-w-[85%] rounded-2xl px-4 py-2 text-sm ${
+                message.role === 'user'
+                  ? 'bg-[var(--color-text)] text-[var(--color-bg)]'
+                  : 'bg-[var(--color-bg-tertiary)] text-[var(--color-text)]'
+              }`}
+            >
+              {message.role === 'assistant' ? (
+                <div className="chat-markdown prose prose-sm max-w-none">
+                  <Streamdown
+                    shikiTheme={['github-light', 'github-dark']}
+                    isAnimating={isStreaming && message.id === messages[messages.length - 1]?.id}
+                  >
+                    {message.content}
+                  </Streamdown>
+                </div>
+              ) : (
+                <p className="whitespace-pre-wrap">{message.content}</p>
+              )}
+
+              {/* Citations */}
+              {citations.get(message.id) && (
+                <div className="mt-3 border-t border-[var(--color-border)] pt-2">
+                  <p className="text-xs font-medium text-[var(--color-text-tertiary)] mb-1">Sources:</p>
+                  <div className="space-y-1">
+                    {citations.get(message.id)!.map((citation, j) => (
+                      <a
+                        key={j}
+                        href={citation.path}
+                        className="flex items-center gap-1 text-xs text-[var(--color-primary)] hover:underline"
+                      >
+                        <ExternalLink className="h-3 w-3" />
+                        {citation.title}
+                      </a>
+                    ))}
+                  </div>
+                </div>
+              )}
+            </div>
+          </div>
+        ))}
+
+        {isLoading && (
+          <div className="flex justify-start">
+            <div className="flex items-center gap-2 rounded-2xl bg-[var(--color-bg-tertiary)] px-4 py-2 text-sm text-[var(--color-text-tertiary)]">
+              <span className="inline-block h-4 w-4 animate-spin rounded-full border-2 border-current border-t-transparent" />
+              Searching docs...
+            </div>
+          </div>
+        )}
+
+        {error && (
+          <div className="flex justify-start">
+            <div className="rounded-2xl bg-red-50 px-4 py-2 text-sm text-red-600">
+              Something went wrong. Please try again.
+            </div>
+          </div>
+        )}
+
+        <div ref={messagesEndRef} />
+      </div>
+
+      {/* Input */}
+      <form
+        onSubmit={handleSubmit}
+        className="border-t border-[var(--color-border)] p-3"
+      >
+        <div className="flex items-center gap-2">
+          <input
+            type="text"
+            value={input}
+            onChange={handleInputChange}
+            placeholder={placeholder}
+            disabled={isStreaming || isLoading}
+            className="flex-1 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg-secondary)] px-4 py-2 text-sm text-[var(--color-text)] outline-none transition-colors placeholder:text-[var(--color-text-tertiary)] focus:border-[var(--color-border-strong)]"
+          />
+          <button
+            type="submit"
+            disabled={!input.trim() || isStreaming || isLoading}
+            className="flex h-10 w-10 items-center justify-center rounded-xl bg-[var(--color-text)] text-[var(--color-bg)] transition-colors hover:opacity-90 disabled:opacity-50"
+            aria-label="Send message"
+          >
+            <Send className="h-4 w-4" />
+          </button>
+        </div>
+      </form>
+    </div>
+  )
+}

package/dist/template/src/components/ai-chat.tsx

@@ -1,15 +1,7 @@
 'use client'
 
-import { useState, useRef, useEffect } from 'react'
-import { useChat } from '@ai-sdk/react'
-import { Streamdown } from 'streamdown'
-import { MessageSquare, X, Send, ExternalLink } from 'lucide-react'
-
-interface Citation {
-  title: string
-  path: string
-  snippet: string
-}
+import dynamic from 'next/dynamic'
+import { MessageSquare } from 'lucide-react'
 
 interface AIChatProps {
   projectName?: string
@@ -17,190 +9,25 @@ interface AIChatProps {
   placeholder?: string
 }
 
-export function AIChat({
-  projectName = 'this documentation',
-  apiEndpoint = '/api/chat',
-  placeholder = 'Ask a question...',
-}: AIChatProps) {
-  const [isOpen, setIsOpen] = useState(false)
-  const [citations, setCitations] = useState<Map<string, Citation[]>>(new Map())
-  const messagesEndRef = useRef<HTMLDivElement>(null)
-
-  const { messages, input, handleInputChange, handleSubmit, status, error } = useChat({
-    api: apiEndpoint,
-    onResponse(response: Response) {
-      // Extract citations from response header
-      const citationsHeader = response.headers.get('X-Citations')
-      if (citationsHeader) {
-        try {
-          const parsed = JSON.parse(atob(citationsHeader)) as Citation[]
-          // Associate citations with the next assistant message
-          setCitations(prev => {
-            const next = new Map(prev)
-            // Use a temporary key that will be replaced when the message arrives
-            next.set('_pending', parsed)
-            return next
-          })
-        } catch {
-          // Skip invalid citations
-        }
-      }
-    },
-    onFinish(message: { id: string }) {
-      // Move pending citations to the actual message ID
-      setCitations(prev => {
-        const next = new Map(prev)
-        const pending = next.get('_pending')
-        if (pending) {
-          next.delete('_pending')
-          next.set(message.id, pending)
-        }
-        return next
-      })
-    },
-  })
-
-  const isStreaming = status === 'streaming'
-  const isLoading = status === 'submitted'
-
-  useEffect(() => {
-    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
-  }, [messages, isStreaming])
-
-  if (!isOpen) {
-    return (
-      <button
-        onClick={() => setIsOpen(true)}
-        className="fixed bottom-6 right-6 z-50 flex h-14 w-14 items-center justify-center rounded-full bg-[var(--color-text)] text-[var(--color-bg)] shadow-lg transition-transform hover:scale-105"
-        aria-label="Open AI chat"
-      >
-        <MessageSquare className="h-6 w-6" />
-      </button>
-    )
-  }
-
+// Thin loading placeholder — just the FAB button (no heavy deps loaded yet)
+function AIChatLoading() {
   return (
-    <div className="fixed bottom-6 right-6 z-50 flex h-[500px] w-[380px] flex-col overflow-hidden rounded-2xl border border-[var(--color-border)] bg-[var(--color-bg)] shadow-2xl">
-      {/* Header */}
-      <div className="flex items-center justify-between border-b border-[var(--color-border)] px-4 py-3">
-        <div className="flex items-center gap-2">
-          <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-[var(--color-text)]">
-            <MessageSquare className="h-4 w-4 text-[var(--color-bg)]" />
-          </div>
-          <div>
-            <p className="text-sm font-medium text-[var(--color-text)]">Ask AI</p>
-            <p className="text-xs text-[var(--color-text-tertiary)]">About {projectName}</p>
-          </div>
-        </div>
-        <button
-          onClick={() => setIsOpen(false)}
-          className="rounded-lg p-1 text-[var(--color-text-tertiary)] transition-colors hover:bg-[var(--color-bg-secondary)] hover:text-[var(--color-text-secondary)]"
-          aria-label="Close chat"
-        >
-          <X className="h-5 w-5" />
-        </button>
-      </div>
-
-      {/* Messages */}
-      <div className="flex-1 overflow-y-auto p-4 space-y-4">
-        {messages.length === 0 && (
-          <div className="text-center text-sm text-[var(--color-text-tertiary)] py-8">
-            <p>Ask me anything about {projectName}.</p>
-            <p className="mt-2 text-xs">I&apos;ll search the docs and give you an answer with sources.</p>
-          </div>
-        )}
-
-        {messages.map((message) => (
-          <div
-            key={message.id}
-            className={`flex ${message.role === 'user' ? 'justify-end' : 'justify-start'}`}
-          >
-            <div
-              className={`max-w-[85%] rounded-2xl px-4 py-2 text-sm ${
-                message.role === 'user'
-                  ? 'bg-[var(--color-text)] text-[var(--color-bg)]'
-                  : 'bg-[var(--color-bg-tertiary)] text-[var(--color-text)]'
-              }`}
-            >
-              {message.role === 'assistant' ? (
-                <div className="chat-markdown prose prose-sm max-w-none">
-                  <Streamdown
-                    shikiTheme={['github-light', 'github-dark']}
-                    isAnimating={isStreaming && message.id === messages[messages.length - 1]?.id}
-                  >
-                    {message.content}
-                  </Streamdown>
-                </div>
-              ) : (
-                <p className="whitespace-pre-wrap">{message.content}</p>
-              )}
-
-              {/* Citations */}
-              {citations.get(message.id) && (
-                <div className="mt-3 border-t border-[var(--color-border)] pt-2">
-                  <p className="text-xs font-medium text-[var(--color-text-tertiary)] mb-1">Sources:</p>
-                  <div className="space-y-1">
-                    {citations.get(message.id)!.map((citation, j) => (
-                      <a
-                        key={j}
-                        href={citation.path}
-                        className="flex items-center gap-1 text-xs text-[var(--color-primary)] hover:underline"
-                      >
-                        <ExternalLink className="h-3 w-3" />
-                        {citation.title}
-                      </a>
-                    ))}
-                  </div>
-                </div>
-              )}
-            </div>
-          </div>
-        ))}
-
-        {isLoading && (
-          <div className="flex justify-start">
-            <div className="flex items-center gap-2 rounded-2xl bg-[var(--color-bg-tertiary)] px-4 py-2 text-sm text-[var(--color-text-tertiary)]">
-              <span className="inline-block h-4 w-4 animate-spin rounded-full border-2 border-current border-t-transparent" />
-              Searching docs...
-            </div>
-          </div>
-        )}
-
-        {error && (
-          <div className="flex justify-start">
-            <div className="rounded-2xl bg-red-50 px-4 py-2 text-sm text-red-600">
-              Something went wrong. Please try again.
-            </div>
-          </div>
-        )}
+    <button
+      className="fixed bottom-6 right-6 z-50 flex h-14 w-14 items-center justify-center rounded-full bg-[var(--color-text)] text-[var(--color-bg)] shadow-lg transition-transform hover:scale-105"
+      aria-label="Open AI chat"
+    >
+      <MessageSquare className="h-6 w-6" />
+    </button>
+  )
+}
 
-        <div ref={messagesEndRef} />
-      </div>
+// Dynamic import — @ai-sdk/react, streamdown, and the full chat UI
+// are only downloaded when this component is rendered on a page
+const AIChatImpl = dynamic(
+  () => import('./ai-chat-impl').then(m => ({ default: m.AIChat })),
+  { ssr: false, loading: () => <AIChatLoading /> },
+)
 
-      {/* Input */}
-      <form
-        onSubmit={handleSubmit}
-        className="border-t border-[var(--color-border)] p-3"
-      >
-        <div className="flex items-center gap-2">
-          <input
-            type="text"
-            value={input}
-            onChange={handleInputChange}
-            placeholder={placeholder}
-            disabled={isStreaming || isLoading}
-            className="flex-1 rounded-xl border border-[var(--color-border)] bg-[var(--color-bg-secondary)] px-4 py-2 text-sm text-[var(--color-text)] outline-none transition-colors placeholder:text-[var(--color-text-tertiary)] focus:border-[var(--color-border-strong)]"
-          />
-          <button
-            type="submit"
-            disabled={!input.trim() || isStreaming || isLoading}
-            className="flex h-10 w-10 items-center justify-center rounded-xl bg-[var(--color-text)] text-[var(--color-bg)] transition-colors hover:opacity-90 disabled:opacity-50"
-            aria-label="Send message"
-          >
-            <Send className="h-4 w-4" />
-          </button>
-        </div>
-      </form>
-    </div>
-  )
+export function AIChat(props: AIChatProps) {
+  return <AIChatImpl {...props} />
 }

package/dist/template/src/components/mdx/index.tsx

@@ -1,3 +1,6 @@
+import dynamic from 'next/dynamic'
+
+// Lightweight components — static imports (always in bundle)
 export { Card, CardGroup } from './card'
 export { Tabs, TabList, Tab, TabPanel } from './tabs'
 export { CodeGroup } from './code-group'
@@ -6,9 +9,6 @@ export { HighlightedCode } from './highlighted-code'
 export { Callout, Info, Warning, Success, Error, Tip, Note } from './callout'
 export { Accordion, AccordionGroup } from './accordion'
 export { Steps, Step } from './steps'
-export { CodePlayground } from './code-playground'
-export { PythonPlayground } from './python-playground'
-export { GoPlayground } from './go-playground'
 export { H1, H2, H3, H4 } from './heading'
 export { ParamTable, Schema } from './param-table'
 export { Changelog, ChangelogEntry, Change } from './changelog'
@@ -17,5 +17,28 @@ export { Tooltip } from './tooltip'
 export { Frame } from './frame'
 export { DarkImage } from './dark-image'
 export { LinkPreview } from './link-preview'
-export { Mermaid } from './mermaid'
 export { Screenshot } from './screenshot'
+
+// Heavy components — dynamic imports (code-split, loaded only when rendered)
+// Each underlying component already has 'use client' and guards browser APIs
+// behind useEffect/handlers, so SSR of the shell is safe.
+
+// @codesandbox/sandpack-react (~5 MB)
+export const CodePlayground = dynamic(
+  () => import('./code-playground').then(m => ({ default: m.CodePlayground })),
+)
+
+// Pyodide loaded at runtime via CDN, but the component itself is still heavy
+export const PythonPlayground = dynamic(
+  () => import('./python-playground').then(m => ({ default: m.PythonPlayground })),
+)
+
+// Go playground (uses fetch to go.dev API)
+export const GoPlayground = dynamic(
+  () => import('./go-playground').then(m => ({ default: m.GoPlayground })),
+)
+
+// mermaid (~2.5 MB)
+export const Mermaid = dynamic(
+  () => import('./mermaid').then(m => ({ default: m.Mermaid })),
+)

package/dist/template/src/lib/fonts.ts

@@ -0,0 +1,135 @@
+/**
+ * Font configuration for the documentation template.
+ *
+ * Supports customizable Google Fonts via docs.json:
+ *
+ *   {
+ *     "fonts": {
+ *       "sans": "Inter",           // default
+ *       "mono": "JetBrains Mono"   // default
+ *     }
+ *   }
+ *
+ * Also supports the legacy `theme.font` key for backward compatibility.
+ */
+
+// ---------------------------------------------------------------------------
+// Curated font lists — only supported Google Fonts are allowed
+// ---------------------------------------------------------------------------
+
+export const SUPPORTED_SANS_FONTS: Record<string, { weights: string }> = {
+  'Inter':            { weights: '400;500;600;700;800' },
+  'Plus Jakarta Sans': { weights: '400;500;600;700;800' },
+  'DM Sans':          { weights: '400;500;600;700' },
+  'Geist':            { weights: '400;500;600;700;800' },
+  'Outfit':           { weights: '400;500;600;700;800' },
+  'Space Grotesk':    { weights: '400;500;600;700' },
+  'Manrope':          { weights: '400;500;600;700;800' },
+  'Sora':             { weights: '400;500;600;700;800' },
+  'Instrument Sans':  { weights: '400;500;600;700' },
+  'Albert Sans':      { weights: '400;500;600;700;800' },
+}
+
+export const SUPPORTED_MONO_FONTS: Record<string, { weights: string }> = {
+  'JetBrains Mono': { weights: '400;500;600;700' },
+  'Fira Code':      { weights: '400;500;600;700' },
+  'Source Code Pro': { weights: '400;500;600;700' },
+  'IBM Plex Mono':  { weights: '400;500;600;700' },
+  'Geist Mono':     { weights: '400;500;600;700' },
+  'Space Mono':     { weights: '400;700' },
+  'Roboto Mono':    { weights: '400;500;600;700' },
+  'Inconsolata':    { weights: '400;500;600;700' },
+}
+
+const DEFAULT_SANS = 'Inter'
+const DEFAULT_MONO = 'JetBrains Mono'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ResolvedFont {
+  /** The font name as it appears in CSS font-family */
+  name: string
+  /** Whether this font needs to be loaded from Google Fonts */
+  isCustom: boolean
+  /** 'sans' or 'mono' */
+  type: 'sans' | 'mono'
+}
+
+export interface ResolvedFonts {
+  sans: ResolvedFont
+  mono: ResolvedFont
+  /** True if at least one font needs Google Fonts loading */
+  needsGoogleFonts: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/** Sanitize a font name — strip anything that isn't alphanumeric, space, or hyphen */
+function sanitize(name: string): string {
+  return name.replace(/[^a-zA-Z0-9\s-]/g, '').trim()
+}
+
+/**
+ * Resolve font configuration from docs.json.
+ *
+ * Priority:
+ *   1. `fonts.sans` / `fonts.mono` (new format)
+ *   2. `theme.font` (legacy — applied to sans only)
+ *   3. Defaults: Inter + JetBrains Mono
+ *
+ * Unrecognized font names fall back to defaults.
+ */
+export function resolveFonts(docsConfig: Record<string, unknown>): ResolvedFonts {
+  const fonts = docsConfig.fonts as { sans?: string; mono?: string } | undefined
+  const legacyFont = (docsConfig.theme as { font?: string } | undefined)?.font
+
+  // Resolve sans font
+  const rawSans = fonts?.sans || legacyFont || DEFAULT_SANS
+  const safeSans = sanitize(rawSans)
+  const sansIsSupported = safeSans in SUPPORTED_SANS_FONTS
+  const sansName = sansIsSupported ? safeSans : DEFAULT_SANS
+  const sansIsCustom = sansName !== DEFAULT_SANS
+
+  // Resolve mono font
+  const rawMono = fonts?.mono || DEFAULT_MONO
+  const safeMono = sanitize(rawMono)
+  const monoIsSupported = safeMono in SUPPORTED_MONO_FONTS
+  const monoName = monoIsSupported ? safeMono : DEFAULT_MONO
+  const monoIsCustom = monoName !== DEFAULT_MONO
+
+  return {
+    sans: { name: sansName, isCustom: sansIsCustom, type: 'sans' },
+    mono: { name: monoName, isCustom: monoIsCustom, type: 'mono' },
+    needsGoogleFonts: sansIsCustom || monoIsCustom,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Google Fonts URL builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a single Google Fonts CSS URL that loads both sans and mono fonts.
+ * Only includes fonts that are non-default (custom).
+ */
+export function buildGoogleFontsUrl(sans: ResolvedFont, mono: ResolvedFont): string | null {
+  const families: string[] = []
+
+  if (sans.isCustom) {
+    const weights = SUPPORTED_SANS_FONTS[sans.name]?.weights || '400;500;600;700'
+    families.push(`family=${encodeURIComponent(sans.name)}:wght@${weights}`)
+  }
+
+  if (mono.isCustom) {
+    const weights = SUPPORTED_MONO_FONTS[mono.name]?.weights || '400;500;600;700'
+    families.push(`family=${encodeURIComponent(mono.name)}:wght@${weights}`)
+  }
+
+  if (families.length === 0) return null
+
+  return `https://fonts.googleapis.com/css2?${families.join('&')}&display=swap`
+}