skrypt-ai 0.4.2 → 0.6.0

package/dist/template/src/components/scroll-to-hash.tsx

@@ -0,0 +1,48 @@
+'use client'
+
+import { useEffect } from 'react'
+import { usePathname } from 'next/navigation'
+
+/**
+ * Handles scrolling to hash targets after page navigation.
+ * Next.js App Router can intercept hash links before content is rendered.
+ * This component uses a MutationObserver to wait for the target element.
+ */
+export function ScrollToHash() {
+  const pathname = usePathname()
+
+  useEffect(() => {
+    const hash = window.location.hash
+    if (!hash) return
+
+    const id = hash.slice(1)
+
+    // Try immediate scroll first
+    const target = document.getElementById(id)
+    if (target) {
+      target.scrollIntoView({ behavior: 'smooth', block: 'start' })
+      return
+    }
+
+    // If element not found yet (SSR/hydration timing), observe DOM
+    const observer = new MutationObserver(() => {
+      const el = document.getElementById(id)
+      if (el) {
+        observer.disconnect()
+        el.scrollIntoView({ behavior: 'smooth', block: 'start' })
+      }
+    })
+
+    observer.observe(document.body, { childList: true, subtree: true })
+
+    // Cleanup after 5 seconds
+    const timeout = setTimeout(() => observer.disconnect(), 5000)
+
+    return () => {
+      observer.disconnect()
+      clearTimeout(timeout)
+    }
+  }, [pathname])
+
+  return null
+}

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

@@ -5,15 +5,13 @@ import { usePathname } from 'next/navigation'
 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 NavPage { title: string; path: string; pages?: NavPage[] }
-interface NavGroup { group: string; icon?: string; pages: (NavPage | NavGroup)[] }
-interface DocsConfig { navigation: NavGroup[] }
+import type { NavPage, NavGroup } from '@/lib/navigation'
+import { isNavGroup } from '@/lib/navigation'
 
 interface SidebarProps {
   open?: boolean
   onClose?: () => void
-  docsConfig: DocsConfig
+  groups: NavGroup[]
 }
 
 const iconMap: Record<string, React.ComponentType<{ size?: number; className?: string }>> = {
@@ -22,10 +20,6 @@ const iconMap: Record<string, React.ComponentType<{ size?: number; className?: s
   Package, Puzzle, GitBranch, Cpu,
 }
 
-function isNavGroup(item: NavPage | NavGroup): item is NavGroup {
-  return 'group' in item && !('path' in item)
-}
-
 /** Check if any descendant page matches the current pathname */
 function hasActivePage(pages: (NavPage | NavGroup)[], pathname: string): boolean {
   for (const item of pages) {
@@ -39,7 +33,7 @@ function hasActivePage(pages: (NavPage | NavGroup)[], pathname: string): boolean
   return false
 }
 
-export function Sidebar({ open, onClose, docsConfig }: SidebarProps) {
+export function Sidebar({ open, onClose, groups }: SidebarProps) {
   const pathname = usePathname()
 
   return (
@@ -61,8 +55,8 @@ export function Sidebar({ open, onClose, docsConfig }: SidebarProps) {
           open ? 'translate-x-0' : '-translate-x-full lg:translate-x-0'
         )}
       >
-        <nav className="py-4 pr-2 space-y-6 divide-y divide-[var(--color-border)]">
-          {docsConfig.navigation.map((group) => (
+        <nav className="py-4 pr-2 space-y-5">
+          {groups.map((group) => (
             <SidebarGroup key={group.group} group={group} pathname={pathname} onNavigate={onClose} level={0} />
           ))}
         </nav>
@@ -80,7 +74,7 @@ function SidebarGroup({ group, pathname, onNavigate, level }: { group: NavGroup;
   // Limit nesting to 3 levels
   if (level > 2) return null
 
-  const paddingLeft = level === 0 ? 'pl-4' : level === 1 ? 'pl-10' : 'pl-14'
+  const paddingLeft = level === 0 ? 'pl-4' : level === 1 ? 'pl-8' : 'pl-12'
 
   return (
     <div>
@@ -88,15 +82,15 @@ function SidebarGroup({ group, pathname, onNavigate, level }: { group: NavGroup;
         onClick={() => setExpanded(!expanded)}
         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',
+          'flex items-center gap-2 w-full mb-1 py-1 text-[0.6875rem] font-semibold uppercase tracking-wider text-[var(--color-text-tertiary)] hover:text-[var(--color-text-secondary)] transition-colors',
           paddingLeft
         )}
       >
         <ChevronRight
-          size={14}
-          className={cn('text-[var(--color-text-tertiary)] transition-transform duration-100', expanded && 'rotate-90')}
+          size={10}
+          className={cn('shrink-0 transition-transform duration-100', expanded && 'rotate-90')}
         />
-        {Icon && <Icon size={14} className="text-[var(--color-text-tertiary)]" />}
+        {Icon && <Icon size={12} className="shrink-0" />}
         {group.group}
       </button>
       {expanded && (
@@ -141,7 +135,7 @@ function SidebarPageItem({ page, pathname, onNavigate, level }: { page: NavPage;
   }, [page, pathname])
   const [expanded, setExpanded] = useState(isActive)
 
-  const paddingClass = level === 0 ? 'pl-10' : level === 1 ? 'pl-14' : 'pl-18'
+  const paddingClass = level === 0 ? 'pl-7' : level === 1 ? 'pl-11' : 'pl-14'
 
   return (
     <div>

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

@@ -21,6 +21,7 @@ export function TableOfContents() {
 
     const elements = article.querySelectorAll('h2, h3')
     const items: Heading[] = []
+    const seenIds = new Set<string>()
 
     // Generic headings that repeat in API reference pages — skip them in TOC
     const genericHeadings = new Set([
@@ -28,6 +29,7 @@ export function TableOfContents() {
       'returned validator function', 'requirements',
       'when results are returned', 'when each value is returned',
       'validationresult shape',
+      'example', 'related', 'notes', 'properties',
     ])
 
     elements.forEach((el) => {
@@ -37,9 +39,16 @@ export function TableOfContents() {
       // Skip generic/repeated headings
       if (genericHeadings.has(normalized)) return
 
+      // Skip headings inside Card components (Cards use h3 for titles, not doc headings)
+      if (el.closest('.card-link') || el.closest('[data-card]')) return
+
       const id = el.id || normalized.replace(/\s+/g, '-')
       if (!el.id) el.id = id
 
+      // Deduplicate — skip if we've already seen this ID
+      if (seenIds.has(id)) return
+      seenIds.add(id)
+
       items.push({
         id,
         text,

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

@@ -1,7 +1,4 @@
-import { createHighlighter, type Highlighter, type BundledTheme } from 'shiki'
-
-// Cache highlighter instances per loaded theme set
-const highlighterCache = new Map<string, Highlighter>()
+import { codeToHtml, type BundledTheme } from 'shiki'
 
 export type ThemeName =
   | 'catppuccin-mocha'
@@ -28,98 +25,16 @@ export const AVAILABLE_THEMES: { name: ThemeName; label: string; isDark: boolean
 
 export const DEFAULT_THEME: ThemeName = 'catppuccin-mocha'
 
-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
-    }
-  }
-
-  // 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(
   code: string,
   language: string,
   theme: ThemeName = DEFAULT_THEME
 ): Promise<string> {
-  const hl = await getHighlighterForTheme(theme)
-
   const lang = normalizeLanguage(language)
-
   try {
-    return hl.codeToHtml(code, {
-      lang,
-      theme: theme as BundledTheme,
-    })
+    return await codeToHtml(code, { lang, theme: theme as BundledTheme })
   } catch {
-    return hl.codeToHtml(code, {
-      lang: 'text',
-      theme: theme as BundledTheme,
-    })
+    return await codeToHtml(code, { lang: 'text', theme: theme as BundledTheme })
   }
 }
 

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

@@ -0,0 +1,159 @@
+export interface NavPage {
+  title: string
+  path: string
+  description?: string
+  pages?: NavPage[]
+}
+
+export interface NavGroup {
+  group: string
+  icon?: string
+  pages: (NavPage | NavGroup)[]
+}
+
+export interface NavTab {
+  tab: string
+  icon?: string
+  groups: NavGroup[]
+  href?: string
+}
+
+export type Navigation = NavGroup[] | NavTab[]
+
+export function isNavGroup(item: NavPage | NavGroup): item is NavGroup {
+  return 'group' in item && !('path' in item)
+}
+
+/** Check if navigation uses tabs format */
+export function hasTabs(navigation: Navigation): navigation is NavTab[] {
+  return navigation.length > 0 && 'tab' in navigation[0]
+}
+
+/** Recursively check if a page path exists within a list of groups */
+function groupsContainPath(groups: NavGroup[], pathname: string): boolean {
+  for (const group of groups) {
+    for (const item of group.pages) {
+      if (isNavGroup(item)) {
+        if (groupsContainPath([item], pathname)) return true
+      } else {
+        if (item.path === pathname) return true
+        if (item.pages && pagesContainPath(item.pages, pathname)) return true
+      }
+    }
+  }
+  return false
+}
+
+function pagesContainPath(pages: NavPage[], pathname: string): boolean {
+  for (const page of pages) {
+    if (page.path === pathname) return true
+    if (page.pages && pagesContainPath(page.pages, pathname)) return true
+  }
+  return false
+}
+
+/** Find the active tab based on current pathname */
+export function getActiveTab(pathname: string, tabs: NavTab[]): NavTab | null {
+  for (const tab of tabs) {
+    if (tab.href && tab.href === pathname) return tab
+    if (tab.groups && groupsContainPath(tab.groups, pathname)) return tab
+  }
+  // Default to first tab if no match
+  return tabs.length > 0 ? tabs[0] : null
+}
+
+/** Get sidebar groups for current pathname (works for both flat and tabbed nav) */
+export function getTabGroups(navigation: Navigation, pathname: string): NavGroup[] {
+  if (!hasTabs(navigation)) return navigation
+  const active = getActiveTab(pathname, navigation)
+  return active?.groups ?? []
+}
+
+/** Get first page path for a tab (for linking) */
+export function getTabHref(tab: NavTab): string {
+  if (tab.href) return tab.href
+  for (const group of tab.groups) {
+    for (const item of group.pages) {
+      if (isNavGroup(item)) {
+        for (const subItem of item.pages) {
+          if (!isNavGroup(subItem) && subItem.path) return subItem.path
+        }
+      } else {
+        return item.path
+      }
+    }
+  }
+  return '/'
+}
+
+/** Flatten all pages across all tabs/groups for prev/next navigation */
+export function getAllPagesFlat(navigation: Navigation): Array<{ title: string; path: string }> {
+  const pages: Array<{ title: string; path: string }> = []
+
+  function collectFromPages(items: (NavPage | NavGroup)[]) {
+    for (const item of items) {
+      if (isNavGroup(item)) {
+        collectFromPages(item.pages)
+      } else {
+        pages.push({ title: item.title, path: item.path })
+        if (item.pages) collectFromPages(item.pages)
+      }
+    }
+  }
+
+  if (hasTabs(navigation)) {
+    for (const tab of navigation) {
+      if (tab.groups) {
+        for (const group of tab.groups) {
+          collectFromPages(group.pages)
+        }
+      }
+    }
+  } else {
+    for (const group of navigation) {
+      collectFromPages(group.pages)
+    }
+  }
+
+  return pages
+}
+
+/** Look up page info from navigation (works with both formats) */
+export function findPageInNavigation(
+  navigation: Navigation,
+  pathname: string
+): { title?: string; description?: string } {
+  function searchPages(items: (NavPage | NavGroup)[]): { title?: string; description?: string } | null {
+    for (const item of items) {
+      if (isNavGroup(item)) {
+        const found = searchPages(item.pages)
+        if (found) return found
+      } else {
+        if (item.path === pathname) return { title: item.title, description: item.description }
+        if (item.pages) {
+          const found = searchPages(item.pages)
+          if (found) return found
+        }
+      }
+    }
+    return null
+  }
+
+  if (hasTabs(navigation)) {
+    for (const tab of navigation) {
+      if (tab.groups) {
+        for (const group of tab.groups) {
+          const found = searchPages(group.pages)
+          if (found) return found
+        }
+      }
+    }
+  } else {
+    for (const group of navigation) {
+      const found = searchPages(group.pages)
+      if (found) return found
+    }
+  }
+
+  return {}
+}

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

@@ -1,6 +1,5 @@
 /**
  * Type definitions for Orama search database
- * Fixes P0: Removes `any` types from search functionality
  */
 
 import type { Orama, Results, SearchParams } from '@orama/orama'
@@ -9,6 +8,8 @@ import type { Orama, Results, SearchParams } from '@orama/orama'
 export interface SearchDocument {
   id: string
   title: string
+  headings: string
+  keywords: string
   content: string
   href: string
   section: string
@@ -18,6 +19,8 @@ export interface SearchDocument {
 export type SearchDatabase = Orama<{
   id: 'string'
   title: 'string'
+  headings: 'string'
+  keywords: 'string'
   content: 'string'
   href: 'string'
   section: 'string'

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

@@ -7,6 +7,8 @@ let loadPromise: Promise<void> | null = null
 const schema = {
   id: 'string' as const,
   title: 'string' as const,
+  headings: 'string' as const,
+  keywords: 'string' as const,
   content: 'string' as const,
   href: 'string' as const,
   section: 'string' as const,
@@ -41,7 +43,15 @@ async function loadSearchIndex(): Promise<void> {
         return
       }
 
-      const newDb = await create({ schema }) as SearchDatabase
+      const newDb = await create({
+        schema,
+        components: {
+          tokenizer: {
+            stemming: true,
+            language: 'english',
+          },
+        },
+      }) as SearchDatabase
       await load(newDb, data as RawData)
       db = newDb
     } catch (err) {
@@ -55,10 +65,21 @@ async function loadSearchIndex(): Promise<void> {
 }
 
 /**
- * Generate a snippet with highlighted search terms
+ * Generate a snippet with highlighted search terms, preferring heading matches
  */
-function generateSnippet(content: string, query: string, maxLength: number = 150): string {
+function generateSnippet(content: string, headings: string, query: string, maxLength: number = 150): string {
   const terms = query.toLowerCase().split(/\s+/).filter(Boolean)
+
+  // Check if any headings match — show that context first
+  if (headings) {
+    const headingList = headings.split(' | ')
+    for (const heading of headingList) {
+      if (terms.some(term => heading.toLowerCase().includes(term))) {
+        return heading
+      }
+    }
+  }
+
   const contentLower = content.toLowerCase()
 
   // Find the best position to start the snippet (where most terms match)
@@ -110,11 +131,13 @@ export async function search(query: string): Promise<SearchResultWithHighlight[]
   try {
     const results = await oramaSearch(db, {
       term: query,
-      properties: ['title', 'content'],
+      properties: ['title', 'headings', 'keywords', 'content'],
       limit: 10,
-      tolerance: 1,
+      tolerance: 2,
       boost: {
-        title: 2,
+        title: 5,
+        headings: 3,
+        keywords: 2,
         content: 1,
       },
     })
@@ -124,7 +147,7 @@ export async function search(query: string): Promise<SearchResultWithHighlight[]
       href: hit.document.href,
       content: hit.document.content,
       section: hit.document.section || undefined,
-      snippet: generateSnippet(hit.document.content, query),
+      snippet: generateSnippet(hit.document.content, hit.document.headings, query),
       score: hit.score,
     }))
   } catch (err) {

package/dist/template/src/styles/globals.css

@@ -80,14 +80,14 @@
     --color-bg: #0f1117;
     --color-bg-secondary: #1a1d27;
     --color-bg-tertiary: #252833;
-    --color-text: #f3f4f6;
-    --color-text-secondary: #d1d5db;
+    --color-text: #e0e2e6;
+    --color-text-secondary: #b0b4bc;
     --color-text-tertiary: #6b7280;
     --color-border: rgba(255, 255, 255, 0.07);
     --color-border-strong: rgba(255, 255, 255, 0.12);
     --color-code-bg: #0b0c0e;
     --color-code-border: rgba(255, 255, 255, 0.1);
-    --color-code-text: #f3f4f6;
+    --color-code-text: #e0e2e6;
   }
 }
 
@@ -95,14 +95,14 @@
   --color-bg: #0f1117;
   --color-bg-secondary: #1a1d27;
   --color-bg-tertiary: #252833;
-  --color-text: #f3f4f6;
-  --color-text-secondary: #d1d5db;
+  --color-text: #e0e2e6;
+  --color-text-secondary: #b0b4bc;
   --color-text-tertiary: #6b7280;
   --color-border: rgba(255, 255, 255, 0.07);
   --color-border-strong: rgba(255, 255, 255, 0.12);
   --color-code-bg: #0b0c0e;
   --color-code-border: rgba(255, 255, 255, 0.1);
-  --color-code-text: #f3f4f6;
+  --color-code-text: #e0e2e6;
 }
 
 /* Error page icon — dark mode overrides (avoids Tailwind dark: variant mismatch) */
@@ -257,6 +257,17 @@ code {
   border-bottom-width: 2px;
 }
 
+/* Cards and card groups should not inherit prose link styling */
+.prose .card-link,
+.prose a:has(> .group) {
+  border-bottom: none !important;
+  font-weight: inherit;
+}
+.prose .card-link:hover,
+.prose a:has(> .group):hover {
+  border-bottom: none !important;
+}
+
 .prose p {
   margin-top: 1.25em;
   margin-bottom: 1.25em;

package/dist/utils/files.d.ts

@@ -1,9 +1,17 @@
 /**
  * Recursively find all .md and .mdx files in a directory.
- * Skips hidden directories and node_modules.
+ * Skips hidden directories, node_modules, and symlinks.
  */
 export declare function findMdxFiles(dir: string): string[];
 /**
  * Convert string to URL-safe slug
  */
 export declare function slugify(str: string): string;
+/**
+ * Simple YAML frontmatter parser — splits on --- markers.
+ * Returns parsed key-value data and remaining content body.
+ */
+export declare function parseFrontmatter(content: string): {
+    data: Record<string, unknown>;
+    content: string;
+};