skrypt-ai 0.3.4 → 0.4.1

package/dist/template/src/components/sidebar.tsx

@@ -2,71 +2,68 @@
 
 import Link from 'next/link'
 import { usePathname } from 'next/navigation'
-import { ChevronRight } from 'lucide-react'
-import { useState } from 'react'
+import { ChevronRight, BookOpen, Code, FileText, Settings, Key, Zap, Shield, Globe, Terminal, Database, Cloud, Lock, Rocket, Search, Star, Heart, Package, Puzzle, GitBranch, Cpu } from 'lucide-react'
+import { useState, useMemo } from 'react'
 import { cn } from '@/lib/utils'
 
-interface NavItem {
-  title: string
-  href?: string
-  items?: NavItem[]
-}
-
-interface NavPage {
-  title: string
-  path: string
-}
+interface NavPage { title: string; path: string; pages?: NavPage[] }
+interface NavGroup { group: string; icon?: string; pages: (NavPage | NavGroup)[] }
+interface DocsConfig { navigation: NavGroup[] }
 
-interface NavGroup {
-  group: string
-  pages: NavPage[]
+interface SidebarProps {
+  open?: boolean
+  onClose?: () => void
+  docsConfig: DocsConfig
 }
 
-interface DocsConfig {
-  navigation: NavGroup[]
+const iconMap: Record<string, React.ComponentType<{ size?: number; className?: string }>> = {
+  BookOpen, Code, FileText, Settings, Key, Zap, Shield, Globe,
+  Terminal, Database, Cloud, Lock, Rocket, Search, Star, Heart,
+  Package, Puzzle, GitBranch, Cpu,
 }
 
-function buildNavigation(config: DocsConfig): NavItem[] {
-  return config.navigation.map((group) => ({
-    title: group.group,
-    items: group.pages.map((page) => ({
-      title: page.title,
-      href: page.path,
-    })),
-  }))
+function isNavGroup(item: NavPage | NavGroup): item is NavGroup {
+  return 'group' in item && !('path' in item)
 }
 
-interface SidebarProps {
-  open?: boolean
-  onClose?: () => void
-  docsConfig: DocsConfig
+/** Check if any descendant page matches the current pathname */
+function hasActivePage(pages: (NavPage | NavGroup)[], pathname: string): boolean {
+  for (const item of pages) {
+    if (isNavGroup(item)) {
+      if (hasActivePage(item.pages, pathname)) return true
+    } else {
+      if (item.path === pathname) return true
+      if (item.pages && hasActivePage(item.pages, pathname)) return true
+    }
+  }
+  return false
 }
 
 export function Sidebar({ open, onClose, docsConfig }: SidebarProps) {
   const pathname = usePathname()
-  const navigation = buildNavigation(docsConfig)
 
   return (
     <>
-      {/* Mobile overlay */}
       {open && (
         <div
-          className="fixed inset-0 z-40 bg-black/50 backdrop-blur-sm md:hidden"
+          className="fixed inset-0 z-40 bg-black/50 backdrop-blur-sm lg:hidden"
+          role="button"
+          tabIndex={0}
+          aria-label="Close sidebar"
           onClick={onClose}
+          onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); onClose?.() } }}
         />
       )}
-
-      {/* Sidebar */}
       <aside
         className={cn(
-          'fixed left-0 top-[var(--header-height)] bottom-0 w-[var(--sidebar-width)] border-r border-[var(--color-border)] bg-[var(--color-bg)] overflow-y-auto z-50 transition-transform duration-200',
-          'md:translate-x-0',
-          open ? 'translate-x-0' : '-translate-x-full md:translate-x-0'
+          'fixed left-0 top-[var(--header-height)] bottom-0 w-[var(--sidebar-width)] bg-[var(--color-bg)] overflow-y-auto z-50 transition-transform duration-100 pl-2 sidebar-scroll-shadow',
+          'lg:translate-x-0',
+          open ? 'translate-x-0' : '-translate-x-full lg:translate-x-0'
         )}
       >
-        <nav className="px-3 py-4 space-y-6">
-          {navigation.map((section) => (
-            <NavSection key={section.title} section={section} pathname={pathname} onNavigate={onClose} />
+        <nav className="py-4 pr-2 space-y-6 divide-y divide-[var(--color-border)]">
+          {docsConfig.navigation.map((group) => (
+            <SidebarGroup key={group.group} group={group} pathname={pathname} onNavigate={onClose} level={0} />
           ))}
         </nav>
       </aside>
@@ -74,55 +71,117 @@ export function Sidebar({ open, onClose, docsConfig }: SidebarProps) {
   )
 }
 
-function NavSection({ section, pathname, onNavigate }: { section: NavItem; pathname: string; onNavigate?: () => void }) {
-  const hasActiveChild = section.items?.some((item) => pathname === item.href)
-  const [expanded, setExpanded] = useState(true)
+function SidebarGroup({ group, pathname, onNavigate, level }: { group: NavGroup; pathname: string; onNavigate?: () => void; level: number }) {
+  const isActive = useMemo(() => hasActivePage(group.pages, pathname), [group.pages, pathname])
+  const [expanded, setExpanded] = useState(isActive)
 
-  if (!section.items) {
-    return (
-      <Link
-        href={section.href || '#'}
-        onClick={onNavigate}
-        className={cn(
-          'block px-3 py-1.5 text-sm rounded-lg transition-colors',
-          pathname === section.href
-            ? 'bg-[var(--color-primary-light)] text-[var(--color-primary)] font-medium'
-            : 'text-[var(--color-text-secondary)] hover:text-[var(--color-text)] hover:bg-[var(--color-bg-secondary)]'
-        )}
-      >
-        {section.title}
-      </Link>
-    )
-  }
+  const Icon = group.icon ? iconMap[group.icon] : null
+
+  // Limit nesting to 3 levels
+  if (level > 2) return null
+
+  const paddingLeft = level === 0 ? 'pl-4' : level === 1 ? 'pl-10' : 'pl-14'
 
   return (
     <div>
       <button
         onClick={() => setExpanded(!expanded)}
-        className="flex items-center justify-between w-full px-3 py-1.5 text-xs font-semibold uppercase tracking-wider text-[var(--color-text-tertiary)] hover:text-[var(--color-text-secondary)] transition-colors"
+        aria-expanded={expanded}
+        className={cn(
+          'flex items-center gap-2.5 w-full mb-2 text-[0.8125rem] font-medium text-[var(--color-text)] hover:text-[var(--color-text)] transition-colors',
+          paddingLeft
+        )}
       >
-        {section.title}
         <ChevronRight
           size={14}
-          className={cn('transition-transform duration-200', expanded && 'rotate-90')}
+          className={cn('text-[var(--color-text-tertiary)] transition-transform duration-100', expanded && 'rotate-90')}
         />
+        {Icon && <Icon size={14} className="text-[var(--color-text-tertiary)]" />}
+        {group.group}
       </button>
       {expanded && (
-        <div className="mt-1 space-y-0.5">
-          {section.items.map((item) => (
-            <Link
-              key={item.href}
-              href={item.href || '#'}
-              onClick={onNavigate}
-              className={cn(
-                'block pl-3 ml-3 py-1.5 text-[0.8125rem] rounded-lg transition-colors border-l-2',
-                pathname === item.href
-                  ? 'border-[var(--color-primary)] text-[var(--color-primary)] font-medium bg-[var(--color-primary-light)]'
-                  : 'border-transparent text-[var(--color-text-secondary)] hover:text-[var(--color-text)] hover:border-[var(--color-border-strong)]'
-              )}
-            >
-              {item.title}
-            </Link>
+        <div className="space-y-px">
+          {group.pages.map((item) => {
+            if (isNavGroup(item)) {
+              return (
+                <SidebarGroup
+                  key={item.group}
+                  group={item}
+                  pathname={pathname}
+                  onNavigate={onNavigate}
+                  level={level + 1}
+                />
+              )
+            }
+
+            return (
+              <SidebarPageItem
+                key={item.path}
+                page={item}
+                pathname={pathname}
+                onNavigate={onNavigate}
+                level={level}
+              />
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}
+
+function SidebarPageItem({ page, pathname, onNavigate, level }: { page: NavPage; pathname: string; onNavigate?: () => void; level: number }) {
+  // Limit nesting depth to prevent infinite recursion
+  if (level > 3) return null
+  const hasChildren = page.pages && page.pages.length > 0
+  const isActive = useMemo(() => {
+    if (page.path === pathname) return true
+    if (page.pages && hasActivePage(page.pages, pathname)) return true
+    return false
+  }, [page, pathname])
+  const [expanded, setExpanded] = useState(isActive)
+
+  const paddingClass = level === 0 ? 'pl-10' : level === 1 ? 'pl-14' : 'pl-18'
+
+  return (
+    <div>
+      <div className="flex items-center">
+        <Link
+          href={page.path}
+          onClick={onNavigate}
+          className={cn(
+            'block flex-1 pr-3 py-1.5 text-[0.8125rem] rounded-lg transition-colors',
+            paddingClass,
+            pathname === page.path
+              ? 'bg-[var(--color-primary)]/10 text-[var(--color-primary)]'
+              : 'text-[var(--color-text-secondary)] hover:bg-[var(--color-primary)]/10 hover:text-[var(--color-primary)]'
+          )}
+        >
+          {page.title}
+        </Link>
+        {hasChildren && (
+          <button
+            onClick={() => setExpanded(!expanded)}
+            aria-expanded={expanded}
+            className="p-1 mr-2 text-[var(--color-text-tertiary)] hover:text-[var(--color-text)]"
+          >
+            <ChevronRight
+              size={12}
+              className={cn('transition-transform duration-100', expanded && 'rotate-90')}
+            />
+          </button>
+        )}
+      </div>
+      {hasChildren && expanded && (
+        <div className="space-y-px">
+          {page.pages!.map((child) => (
+            <SidebarPageItem
+              key={child.path}
+              page={child}
+              pathname={pathname}
+              onNavigate={onNavigate}
+              level={level + 1}
+            />
           ))}
         </div>
       )}

package/dist/template/src/components/table-of-contents.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { useEffect, useState } from 'react'
+import { usePathname } from 'next/navigation'
 import { cn } from '@/lib/utils'
 
 interface Heading {
@@ -12,6 +13,7 @@ interface Heading {
 export function TableOfContents() {
   const [headings, setHeadings] = useState<Heading[]>([])
   const [activeId, setActiveId] = useState('')
+  const pathname = usePathname()
 
   useEffect(() => {
     const article = document.querySelector('article')
@@ -20,19 +22,33 @@ export function TableOfContents() {
     const elements = article.querySelectorAll('h2, h3')
     const items: Heading[] = []
 
+    // Generic headings that repeat in API reference pages — skip them in TOC
+    const genericHeadings = new Set([
+      'parameters', 'returns', 'return value', 'return type',
+      'returned validator function', 'requirements',
+      'when results are returned', 'when each value is returned',
+      'validationresult shape',
+    ])
+
     elements.forEach((el) => {
-      const id = el.id || el.textContent?.toLowerCase().replace(/\s+/g, '-') || ''
+      const text = el.textContent || ''
+      const normalized = text.toLowerCase().trim()
+
+      // Skip generic/repeated headings
+      if (genericHeadings.has(normalized)) return
+
+      const id = el.id || normalized.replace(/\s+/g, '-')
       if (!el.id) el.id = id
 
       items.push({
         id,
-        text: el.textContent || '',
+        text,
         level: parseInt(el.tagName[1]),
       })
     })
 
     setHeadings(items)
-  }, [])
+  }, [pathname])
 
   useEffect(() => {
     const observer = new IntersectionObserver(
@@ -43,7 +59,7 @@ export function TableOfContents() {
           }
         })
       },
-      { rootMargin: '-80px 0px -80% 0px' }
+      { rootMargin: '-80px 0px -60% 0px' }
     )
 
     headings.forEach(({ id }) => {
@@ -57,13 +73,13 @@ export function TableOfContents() {
   if (headings.length === 0) return null
 
   return (
-    <nav className="hidden xl:block fixed right-8 top-[calc(var(--header-height)+2rem)] w-[var(--toc-width)] max-h-[calc(100vh-var(--header-height)-4rem)] overflow-y-auto">
+    <nav className="hidden lg:block fixed right-8 top-[calc(var(--header-height)+2rem)] w-[var(--toc-width)] max-h-[calc(100vh-var(--header-height)-4rem)] overflow-y-auto">
       <p className="text-[0.6875rem] font-semibold uppercase tracking-widest text-[var(--color-text-tertiary)] mb-3">
         On this page
       </p>
       <ul className="space-y-0.5 border-l border-[var(--color-border)]">
-        {headings.map((heading) => (
-          <li key={heading.id}>
+        {headings.map((heading, index) => (
+          <li key={`${heading.id}-${index}`}>
             <a
               href={`#${heading.id}`}
               className={cn(

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

@@ -1,10 +1,22 @@
 import { createHighlighter, type Highlighter, type BundledTheme } from 'shiki'
 
-let highlighter: Highlighter | null = null
+// Cache highlighter instances per loaded theme set
+const highlighterCache = new Map<string, Highlighter>()
 
-export type ThemeName = 'github-dark' | 'github-light' | 'dracula' | 'nord' | 'one-dark-pro' | 'vitesse-dark' | 'vitesse-light'
+export type ThemeName =
+  | 'catppuccin-mocha'
+  | 'catppuccin-latte'
+  | 'github-dark'
+  | 'github-light'
+  | 'dracula'
+  | 'nord'
+  | 'one-dark-pro'
+  | 'vitesse-dark'
+  | 'vitesse-light'
 
 export const AVAILABLE_THEMES: { name: ThemeName; label: string; isDark: boolean }[] = [
+  { name: 'catppuccin-mocha', label: 'Catppuccin', isDark: true },
+  { name: 'catppuccin-latte', label: 'Catppuccin Light', isDark: false },
   { name: 'github-dark', label: 'GitHub Dark', isDark: true },
   { name: 'github-light', label: 'GitHub Light', isDark: false },
   { name: 'dracula', label: 'Dracula', isDark: true },
@@ -14,34 +26,79 @@ export const AVAILABLE_THEMES: { name: ThemeName; label: string; isDark: boolean
   { name: 'vitesse-light', label: 'Vitesse Light', isDark: false },
 ]
 
-export const DEFAULT_THEME: ThemeName = 'github-dark'
+export const DEFAULT_THEME: ThemeName = 'catppuccin-mocha'
 
-export async function getHighlighter(): Promise<Highlighter> {
-  if (!highlighter) {
-    highlighter = await createHighlighter({
-      themes: AVAILABLE_THEMES.map(t => t.name) as BundledTheme[],
-      langs: [
-        'typescript',
-        'javascript',
-        'python',
-        'go',
-        'rust',
-        'json',
-        'yaml',
-        'bash',
-        'shell',
-        'markdown',
-        'html',
-        'css',
-        'jsx',
-        'tsx',
-        'sql',
-        'graphql',
-        'diff',
-      ],
-    })
+const SUPPORTED_LANGS = [
+  'typescript',
+  'javascript',
+  'python',
+  'go',
+  'rust',
+  'json',
+  'yaml',
+  'bash',
+  'shell',
+  'markdown',
+  'html',
+  'css',
+  'jsx',
+  'tsx',
+  'sql',
+  'graphql',
+  'diff',
+]
+
+// Start with just the default theme; load others on demand
+let defaultHighlighter: Highlighter | null = null
+let defaultHighlighterPromise: Promise<Highlighter> | null = null
+
+async function getDefaultHighlighter(): Promise<Highlighter> {
+  if (defaultHighlighter) return defaultHighlighter
+  if (defaultHighlighterPromise) return defaultHighlighterPromise
+
+  defaultHighlighterPromise = createHighlighter({
+    themes: [DEFAULT_THEME] as BundledTheme[],
+    langs: SUPPORTED_LANGS,
+  }).then(hl => {
+    defaultHighlighter = hl
+    highlighterCache.set(DEFAULT_THEME, hl)
+    return hl
+  })
+
+  return defaultHighlighterPromise
+}
+
+async function getHighlighterForTheme(theme: ThemeName): Promise<Highlighter> {
+  if (theme === DEFAULT_THEME || highlighterCache.has(DEFAULT_THEME)) {
+    // Try to load the theme into the existing default highlighter
+    const hl = await getDefaultHighlighter()
+    try {
+      // Check if the theme is already loaded by attempting to use it
+      const loadedThemes = hl.getLoadedThemes()
+      if (!loadedThemes.includes(theme as BundledTheme)) {
+        await hl.loadTheme(theme as BundledTheme)
+      }
+      return hl
+    } catch {
+      // If loading into existing highlighter fails, create a new one
+    }
   }
-  return highlighter
+
+  // Check cache
+  const cached = highlighterCache.get(theme)
+  if (cached) return cached
+
+  // Create a new highlighter with this theme
+  const hl = await createHighlighter({
+    themes: [theme] as BundledTheme[],
+    langs: SUPPORTED_LANGS,
+  })
+  highlighterCache.set(theme, hl)
+  return hl
+}
+
+export async function getHighlighter(): Promise<Highlighter> {
+  return getDefaultHighlighter()
 }
 
 export async function highlight(
@@ -49,9 +106,8 @@ export async function highlight(
   language: string,
   theme: ThemeName = DEFAULT_THEME
 ): Promise<string> {
-  const hl = await getHighlighter()
+  const hl = await getHighlighterForTheme(theme)
 
-  // Normalize language names
   const lang = normalizeLanguage(language)
 
   try {
@@ -60,7 +116,6 @@ export async function highlight(
       theme: theme as BundledTheme,
     })
   } catch {
-    // Fallback to plain text if language not supported
     return hl.codeToHtml(code, {
       lang: 'text',
       theme: theme as BundledTheme,
@@ -68,6 +123,10 @@ export async function highlight(
   }
 }
 
+export function isLightTheme(theme: ThemeName): boolean {
+  return AVAILABLE_THEMES.find(t => t.name === theme)?.isDark === false
+}
+
 function normalizeLanguage(lang: string): string {
   const aliases: Record<string, string> = {
     js: 'javascript',

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

@@ -1,4 +1,4 @@
-import { create, load, search as oramaSearch } from '@orama/orama'
+import { create, load, search as oramaSearch, type RawData } from '@orama/orama'
 import type { SearchDatabase, SearchHit } from './search-types'
 
 let db: SearchDatabase | null = null
@@ -27,12 +27,22 @@ async function loadSearchIndex(): Promise<void> {
     try {
       const response = await fetch('/search-index.json')
       if (!response.ok) {
-        throw new Error('Search index not found')
+        console.warn('Search index not available (HTTP ' + response.status + '). Search will be disabled.')
+        db = null
+        return
+      }
+
+      let data: unknown
+      try {
+        data = await response.json()
+      } catch (parseErr) {
+        console.error('Search index contains invalid JSON. Search will be disabled.')
+        db = null
+        return
       }
-      const data = await response.json()
 
       const newDb = await create({ schema }) as SearchDatabase
-      await load(newDb, data)
+      await load(newDb, data as RawData)
       db = newDb
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err)

package/dist/template/src/lib/theme-utils.ts

@@ -0,0 +1,140 @@
+/**
+ * Theme color derivation utilities.
+ * Pure functions — no external dependencies.
+ */
+
+/**
+ * Convert a hex color string to HSL components.
+ * Accepts 3-digit (#abc) or 6-digit (#aabbcc) hex, with or without #.
+ */
+export function hexToHsl(hex: string): { h: number; s: number; l: number } {
+  // Strip # prefix if present
+  hex = hex.replace(/^#/, '')
+
+  // Expand 3-digit shorthand to 6-digit
+  if (hex.length === 3) {
+    hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2]
+  }
+
+  const r = parseInt(hex.substring(0, 2), 16) / 255
+  const g = parseInt(hex.substring(2, 4), 16) / 255
+  const b = parseInt(hex.substring(4, 6), 16) / 255
+
+  const max = Math.max(r, g, b)
+  const min = Math.min(r, g, b)
+  const l = (max + min) / 2
+
+  if (max === min) {
+    // Achromatic
+    return { h: 0, s: 0, l }
+  }
+
+  const d = max - min
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+
+  let h: number
+  switch (max) {
+    case r:
+      h = ((g - b) / d + (g < b ? 6 : 0)) / 6
+      break
+    case g:
+      h = ((b - r) / d + 2) / 6
+      break
+    default:
+      h = ((r - g) / d + 4) / 6
+      break
+  }
+
+  return { h: h * 360, s, l }
+}
+
+/**
+ * Convert HSL components back to a hex color string.
+ * h: 0-360, s: 0-1, l: 0-1
+ */
+export function hslToHex(h: number, s: number, l: number): string {
+  // Clamp values
+  h = ((h % 360) + 360) % 360
+  s = Math.max(0, Math.min(1, s))
+  l = Math.max(0, Math.min(1, l))
+
+  const c = (1 - Math.abs(2 * l - 1)) * s
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+  const m = l - c / 2
+
+  let r: number, g: number, b: number
+
+  if (h < 60) {
+    ;[r, g, b] = [c, x, 0]
+  } else if (h < 120) {
+    ;[r, g, b] = [x, c, 0]
+  } else if (h < 180) {
+    ;[r, g, b] = [0, c, x]
+  } else if (h < 240) {
+    ;[r, g, b] = [0, x, c]
+  } else if (h < 300) {
+    ;[r, g, b] = [x, 0, c]
+  } else {
+    ;[r, g, b] = [c, 0, x]
+  }
+
+  const toHex = (v: number) =>
+    Math.round((v + m) * 255)
+      .toString(16)
+      .padStart(2, '0')
+
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
+}
+
+/**
+ * Derive primary, dark, and light variants from a single hex color.
+ * Dark variant: lightness reduced by ~15%
+ * Light variant: lightness increased by ~15%
+ */
+/**
+ * Compute WCAG relative luminance from a hex color.
+ * Returns 0 (black) to 1 (white).
+ */
+export function relativeLuminance(hex: string): number {
+  hex = hex.replace(/^#/, '')
+  if (hex.length === 3) {
+    hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2]
+  }
+  const r = parseInt(hex.substring(0, 2), 16) / 255
+  const g = parseInt(hex.substring(2, 4), 16) / 255
+  const b = parseInt(hex.substring(4, 6), 16) / 255
+
+  const toLinear = (c: number) => (c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4))
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b)
+}
+
+/**
+ * Return the best contrasting foreground color (white or dark) for a given background.
+ * Uses WCAG contrast ratio.
+ */
+export function contrastForeground(bgHex: string): string {
+  const lum = relativeLuminance(bgHex)
+  // WCAG contrast ratio: (L1 + 0.05) / (L2 + 0.05)
+  // White on bg: (1 + 0.05) / (lum + 0.05)
+  // Dark on bg: (lum + 0.05) / (0 + 0.05)
+  const contrastWithWhite = (1.05) / (lum + 0.05)
+  const contrastWithBlack = (lum + 0.05) / 0.05
+  return contrastWithWhite >= contrastWithBlack ? '#ffffff' : '#0f1117'
+}
+
+export function derivePrimaryColors(hex: string): {
+  primary: string
+  primaryDark: string
+  primaryLight: string
+  primaryForeground: string
+} {
+  const { h, s, l } = hexToHsl(hex)
+  const normalizedHex = hex.startsWith('#') ? hex : `#${hex}`
+
+  return {
+    primary: normalizedHex,
+    primaryDark: hslToHex(h, s, Math.max(0, l - 0.15)),
+    primaryLight: hslToHex(h, s, Math.min(1, l + 0.15)),
+    primaryForeground: contrastForeground(normalizedHex),
+  }
+}