skrypt-ai 0.4.1 → 0.5.0

package/dist/template/scripts/build-search-index.mjs

@@ -19,13 +19,15 @@ async function dirExists(dir) {
 async function getAllMDXFiles(dir) {
   const files = []
 
-  async function walk(currentDir) {
+  async function walk(currentDir, depth = 0) {
+    if (depth > 20) return
     try {
       const entries = await readdir(currentDir, { withFileTypes: true })
       for (const entry of entries) {
         const fullPath = join(currentDir, entry.name)
+        if (entry.isSymbolicLink?.()) continue
         if (entry.isDirectory()) {
-          await walk(fullPath)
+          await walk(fullPath, depth + 1)
         } else if (entry.name.endsWith('.md') || entry.name.endsWith('.mdx')) {
           files.push(fullPath)
         }
@@ -39,14 +41,30 @@ async function getAllMDXFiles(dir) {
   return files
 }
 
+/**
+ * Extract headings (h2, h3) as a separate searchable field.
+ * This lets users find pages by section names.
+ */
+function extractHeadings(content) {
+  const headings = []
+  const regex = /^#{2,3}\s+(.+)$/gm
+  let match
+  while ((match = regex.exec(content)) !== null) {
+    // Strip any inline formatting
+    const clean = match[1].replace(/[*_`[\]]/g, '').trim()
+    if (clean) headings.push(clean)
+  }
+  return headings.join(' | ')
+}
+
 function extractPlainText(content) {
   return content
     // Remove import statements
     .replace(/^import\s+.*$/gm, '')
     // Remove export statements
     .replace(/^export\s+.*$/gm, '')
-    // Remove MDX/JSX components
-    .replace(/<[^>]+>/g, '')
+    // Remove MDX/JSX components (but keep text content inside)
+    .replace(/<[^>]+>/g, ' ')
     // Remove code blocks
     .replace(/```[\s\S]*?```/g, '')
     .replace(/`[^`]+`/g, '')
@@ -68,6 +86,35 @@ function extractPlainText(content) {
     .trim()
 }
 
+/**
+ * Extract keywords from content — important terms that appear frequently
+ * or in headings, used to boost search relevance.
+ */
+function extractKeywords(content, title) {
+  const words = new Map()
+
+  // Title words get high weight
+  for (const word of title.toLowerCase().split(/\s+/)) {
+    if (word.length > 2) words.set(word, (words.get(word) || 0) + 3)
+  }
+
+  // Heading words get medium weight
+  const headingRegex = /^#{1,3}\s+(.+)$/gm
+  let match
+  while ((match = headingRegex.exec(content)) !== null) {
+    for (const word of match[1].toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/)) {
+      if (word.length > 2) words.set(word, (words.get(word) || 0) + 2)
+    }
+  }
+
+  // Sort by weight and return top keywords
+  return [...words.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 20)
+    .map(([word]) => word)
+    .join(' ')
+}
+
 function getSlugFromContentPath(filePath) {
   const rel = relative(CONTENT_DIR, filePath)
   const slug = rel
@@ -79,8 +126,6 @@ function getSlugFromContentPath(filePath) {
 }
 
 function getSlugFromAppPath(filePath) {
-  // For App Router: src/app/docs/quickstart/page.mdx -> /docs/quickstart
-  // src/app/docs/page.mdx -> /docs
   const rel = relative(APP_DOCS_DIR, filePath)
   const dir = dirname(rel)
   const name = basename(rel)
@@ -99,11 +144,9 @@ function getSlugFromAppPath(filePath) {
 }
 
 function extractTitle(content, filePath) {
-  // Try to get title from first heading
   const h1Match = content.match(/^#\s+(.+)$/m)
   if (h1Match) return h1Match[1].trim()
 
-  // Derive from file path
   const dir = dirname(filePath)
   const folderName = basename(dir)
   if (folderName && folderName !== 'docs' && folderName !== '.') {
@@ -122,10 +165,18 @@ async function buildSearchIndex() {
     schema: {
       id: 'string',
       title: 'string',
+      headings: 'string',
+      keywords: 'string',
       content: 'string',
       href: 'string',
       section: 'string',
     },
+    components: {
+      tokenizer: {
+        stemming: true,
+        language: 'english',
+      },
+    },
   })
 
   const documents = []
@@ -141,6 +192,8 @@ async function buildSearchIndex() {
 
         const title = data.title || extractTitle(content, file)
         const plainContent = extractPlainText(content)
+        const headings = extractHeadings(content)
+        const keywords = extractKeywords(content, title)
         const href = getSlugFromContentPath(file)
 
         if (seen.has(href)) continue
@@ -149,6 +202,8 @@ async function buildSearchIndex() {
         documents.push({
           id: href,
           title,
+          headings,
+          keywords,
           content: plainContent.slice(0, 5000),
           href,
           section: data.section || data.category || '',
@@ -165,7 +220,6 @@ async function buildSearchIndex() {
   if (await dirExists(APP_DOCS_DIR)) {
     const appFiles = await getAllMDXFiles(APP_DOCS_DIR)
     for (const file of appFiles) {
-      // Skip catch-all route files and layout files
       if (file.includes('[...slug]') || file.includes('layout.')) continue
 
       try {
@@ -174,6 +228,8 @@ async function buildSearchIndex() {
 
         const title = data.title || extractTitle(content, file)
         const plainContent = extractPlainText(content)
+        const headings = extractHeadings(content)
+        const keywords = extractKeywords(content, title)
         const href = getSlugFromAppPath(file)
 
         if (seen.has(href)) continue
@@ -182,6 +238,8 @@ async function buildSearchIndex() {
         documents.push({
           id: href,
           title,
+          headings,
+          keywords,
           content: plainContent.slice(0, 5000),
           href,
           section: data.section || data.category || '',

package/dist/template/src/components/mdx/dark-image.tsx

@@ -0,0 +1,56 @@
+'use client'
+
+import { useState, useEffect } from 'react'
+import { cn } from '@/lib/utils'
+
+interface DarkImageProps {
+  src: string
+  darkSrc: string
+  alt: string
+  width?: number
+  height?: number
+  className?: string
+}
+
+function getIsDark(): boolean {
+  if (typeof document === 'undefined') return false
+  if (document.documentElement.classList.contains('dark')) return true
+  if (document.documentElement.classList.contains('light')) return false
+  return window.matchMedia('(prefers-color-scheme: dark)').matches
+}
+
+export function DarkImage({ src, darkSrc, alt, width, height, className }: DarkImageProps) {
+  const [isDark, setIsDark] = useState(false)
+
+  useEffect(() => {
+    setIsDark(getIsDark())
+
+    const mq = window.matchMedia('(prefers-color-scheme: dark)')
+    const onMediaChange = () => setIsDark(getIsDark())
+    mq.addEventListener('change', onMediaChange)
+
+    const observer = new MutationObserver(() => {
+      setIsDark(getIsDark())
+    })
+
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['class'],
+    })
+
+    return () => {
+      mq.removeEventListener('change', onMediaChange)
+      observer.disconnect()
+    }
+  }, [])
+
+  return (
+    <img
+      src={isDark ? darkSrc : src}
+      alt={alt}
+      width={width}
+      height={height}
+      className={cn('rounded-lg', className)}
+    />
+  )
+}

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

@@ -0,0 +1,64 @@
+'use client'
+
+import { cn } from '@/lib/utils'
+
+interface FrameProps {
+  children: React.ReactNode
+  caption?: string
+  variant?: 'browser' | 'terminal' | 'plain'
+}
+
+function TrafficDots() {
+  return (
+    <div className="flex items-center gap-1.5">
+      <span className="block w-2 h-2 rounded-full bg-[#ff5f57]" />
+      <span className="block w-2 h-2 rounded-full bg-[#febc2e]" />
+      <span className="block w-2 h-2 rounded-full bg-[#28c840]" />
+    </div>
+  )
+}
+
+function BrowserChrome() {
+  return (
+    <div className="flex items-center gap-3 px-3.5 py-2.5 border-b border-[var(--color-border)] bg-[var(--color-bg-secondary)]">
+      <TrafficDots />
+      <div className="flex-1 h-5 rounded-md bg-[var(--color-bg)] border border-[var(--color-border)] px-2.5 flex items-center">
+        <span className="text-[10px] text-[var(--color-text-tertiary)] select-none truncate">
+          https://example.com
+        </span>
+      </div>
+    </div>
+  )
+}
+
+function TerminalChrome() {
+  return (
+    <div className="flex items-center gap-3 px-3.5 py-2.5 bg-[#1a1a1a]">
+      <TrafficDots />
+    </div>
+  )
+}
+
+export function Frame({ children, caption, variant = 'browser' }: FrameProps) {
+  return (
+    <figure className="my-4">
+      <div
+        className={cn(
+          'rounded-xl border border-[var(--color-border)] overflow-hidden',
+          variant === 'terminal' && 'bg-[#1a1a1a]'
+        )}
+      >
+        {variant === 'browser' && <BrowserChrome />}
+        {variant === 'terminal' && <TerminalChrome />}
+        <div className="[&>img]:!m-0 [&>img]:!rounded-none [&>img]:block [&>img]:w-full">
+          {children}
+        </div>
+      </div>
+      {caption && (
+        <figcaption className="text-sm text-[var(--color-text-tertiary)] mt-2 text-center">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  )
+}

package/dist/template/src/components/mdx/highlighted-code.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState, useEffect, useContext, ReactNode, isValidElement, Children, useRef } from 'react'
+import { useState, useEffect, useContext, ReactNode, isValidElement, Children, useRef, useCallback } from 'react'
 import { Copy, Check } from 'lucide-react'
 import { highlight, DEFAULT_THEME, isLightTheme, type ThemeName } from '@/lib/highlight'
 import { SyntaxThemeContext } from '@/contexts/syntax-theme'
@@ -54,11 +54,56 @@ function parseFilename(meta: string): string | undefined {
   return match ? match[1] : undefined
 }
 
+/** Hook to track horizontal overflow and scroll position of a scrollable element */
+function useScrollOverflow(ref: React.RefObject<HTMLElement | null>) {
+  const [hasOverflow, setHasOverflow] = useState(false)
+  const [scrolledToEnd, setScrolledToEnd] = useState(false)
+  const [scrolledFromStart, setScrolledFromStart] = useState(false)
+
+  const checkOverflow = useCallback(() => {
+    const el = ref.current
+    if (!el) return
+    const overflows = el.scrollWidth > el.clientWidth + 1
+    setHasOverflow(overflows)
+    if (overflows) {
+      const atEnd = el.scrollLeft + el.clientWidth >= el.scrollWidth - 1
+      const atStart = el.scrollLeft <= 1
+      setScrolledToEnd(atEnd)
+      setScrolledFromStart(!atStart)
+    } else {
+      setScrolledToEnd(false)
+      setScrolledFromStart(false)
+    }
+  }, [ref])
+
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+
+    checkOverflow()
+
+    // Re-check on window resize
+    const resizeObserver = new ResizeObserver(checkOverflow)
+    resizeObserver.observe(el)
+
+    el.addEventListener('scroll', checkOverflow, { passive: true })
+    return () => {
+      resizeObserver.disconnect()
+      el.removeEventListener('scroll', checkOverflow)
+    }
+  }, [ref, checkOverflow])
+
+  return { hasOverflow, scrolledToEnd, scrolledFromStart }
+}
+
 export function HighlightedCode({ children, className }: HighlightedCodeProps) {
   const [copied, setCopied] = useState(false)
   const [showToast, setShowToast] = useState(false)
   const [highlightedHtml, setHighlightedHtml] = useState<string | null>(null)
   const copyButtonRef = useRef<HTMLButtonElement>(null)
+  const scrollRef = useRef<HTMLDivElement>(null)
+
+  const { hasOverflow, scrolledToEnd, scrolledFromStart } = useScrollOverflow(scrollRef)
 
   const syntaxContext = useContext(SyntaxThemeContext)
   const theme: ThemeName = syntaxContext?.theme ?? DEFAULT_THEME
@@ -99,6 +144,17 @@ export function HighlightedCode({ children, className }: HighlightedCodeProps) {
     return () => { cancelled = true }
   }, [codeText, language, theme])
 
+  // Re-check overflow after highlight finishes (content may change width)
+  useEffect(() => {
+    if (highlightedHtml && scrollRef.current) {
+      const el = scrollRef.current
+      // Slight delay to let DOM paint
+      requestAnimationFrame(() => {
+        el.dispatchEvent(new Event('scroll'))
+      })
+    }
+  }, [highlightedHtml])
+
   async function handleCopy() {
     try {
       await navigator.clipboard.writeText(codeText)
@@ -126,51 +182,109 @@ export function HighlightedCode({ children, className }: HighlightedCodeProps) {
   // Remove trailing empty line from code
   if (lines[lines.length - 1] === '') lines.pop()
 
+  const fadeGradient = isLight
+    ? 'linear-gradient(to right, transparent, var(--color-code-bg))'
+    : 'linear-gradient(to right, transparent, var(--color-code-bg))'
+  const fadeGradientLeft = isLight
+    ? 'linear-gradient(to left, transparent, var(--color-code-bg))'
+    : 'linear-gradient(to left, transparent, var(--color-code-bg))'
+
   /** Render code with line numbers and/or line highlighting */
   function renderWithLineFeatures(htmlContent: string | null) {
     if (!hasLineFeatures) {
       // No line features — render normally
       if (htmlContent) {
         return (
-          <div
-            className="[&>pre]:!rounded-none [&>pre]:!border-0 [&>pre]:!m-0 [&>pre]:py-3.5 [&>pre]:px-4 [&>pre]:overflow-x-auto"
-            dangerouslySetInnerHTML={{ __html: htmlContent }}
-          />
+          <div className="relative">
+            <div
+              ref={scrollRef}
+              className="[&>pre]:!rounded-none [&>pre]:!border-0 [&>pre]:!m-0 [&>pre]:py-3.5 [&>pre]:px-4 [&>pre]:overflow-x-auto"
+              dangerouslySetInnerHTML={{ __html: htmlContent }}
+            />
+            {hasOverflow && scrolledFromStart && (
+              <div
+                className="absolute left-0 top-0 bottom-0 w-8 pointer-events-none"
+                style={{ background: fadeGradientLeft }}
+                aria-hidden="true"
+              />
+            )}
+            {hasOverflow && !scrolledToEnd && (
+              <div
+                className="absolute right-0 top-0 bottom-0 w-8 pointer-events-none"
+                style={{ background: fadeGradient }}
+                aria-hidden="true"
+              />
+            )}
+          </div>
         )
       }
       return (
-        <pre className="!rounded-none !border-0 !m-0 py-3.5 px-4 overflow-x-auto">
-          {children}
-        </pre>
+        <div className="relative">
+          <div ref={scrollRef}>
+            <pre className="!rounded-none !border-0 !m-0 py-3.5 px-4 overflow-x-auto">
+              {children}
+            </pre>
+          </div>
+          {hasOverflow && scrolledFromStart && (
+            <div
+              className="absolute left-0 top-0 bottom-0 w-8 pointer-events-none"
+              style={{ background: fadeGradientLeft }}
+              aria-hidden="true"
+            />
+          )}
+          {hasOverflow && !scrolledToEnd && (
+            <div
+              className="absolute right-0 top-0 bottom-0 w-8 pointer-events-none"
+              style={{ background: fadeGradient }}
+              aria-hidden="true"
+            />
+          )}
+        </div>
       )
     }
 
     // With line features, we need to render line by line
     return (
-      <div className="overflow-x-auto">
-        <table className="w-full border-collapse" style={{ tableLayout: 'auto' }}>
-          <tbody>
-            {lines.map((line, i) => {
-              const lineNum = i + 1
-              const isHighlighted = highlightedLines.has(lineNum)
-              return (
-                <tr
-                  key={i}
-                  className={isHighlighted ? 'bg-[var(--color-primary)]/[0.07]' : ''}
-                >
-                  {showLineNumbers && (
-                    <td className="text-right pr-4 select-none text-[var(--color-text-tertiary)] text-[0.75rem] py-0 pl-4 w-[1%] whitespace-nowrap align-top leading-[1.7142857]">
-                      {lineNum}
+      <div className="relative">
+        <div ref={scrollRef} className="overflow-x-auto">
+          <table className="w-full border-collapse" style={{ tableLayout: 'auto' }}>
+            <tbody>
+              {lines.map((line, i) => {
+                const lineNum = i + 1
+                const isHighlighted = highlightedLines.has(lineNum)
+                return (
+                  <tr
+                    key={i}
+                    className={isHighlighted ? 'bg-[var(--color-primary)]/[0.07]' : ''}
+                  >
+                    {showLineNumbers && (
+                      <td className="text-right pr-4 select-none text-[var(--color-text-tertiary)] text-[0.75rem] py-0 pl-4 w-[1%] whitespace-nowrap align-top leading-[1.7142857]">
+                        {lineNum}
+                      </td>
+                    )}
+                    <td className="py-0 pr-4 whitespace-pre font-mono text-[0.875em] leading-[1.7142857]">
+                      {line || ' '}
                     </td>
-                  )}
-                  <td className="py-0 pr-4 whitespace-pre font-mono text-[0.875em] leading-[1.7142857]">
-                    {line || ' '}
-                  </td>
-                </tr>
-              )
-            })}
-          </tbody>
-        </table>
+                  </tr>
+                )
+              })}
+            </tbody>
+          </table>
+        </div>
+        {hasOverflow && scrolledFromStart && (
+          <div
+            className="absolute left-0 top-0 bottom-0 w-8 pointer-events-none"
+            style={{ background: fadeGradientLeft }}
+            aria-hidden="true"
+          />
+        )}
+        {hasOverflow && !scrolledToEnd && (
+          <div
+            className="absolute right-0 top-0 bottom-0 w-8 pointer-events-none"
+            style={{ background: fadeGradient }}
+            aria-hidden="true"
+          />
+        )}
       </div>
     )
   }

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

@@ -13,3 +13,7 @@ export { H1, H2, H3, H4 } from './heading'
 export { ParamTable, Schema } from './param-table'
 export { Changelog, ChangelogEntry, Change } from './changelog'
 export { MethodBadge, StatusBadge, Endpoint } from './api-badge'
+export { Tooltip } from './tooltip'
+export { Frame } from './frame'
+export { DarkImage } from './dark-image'
+export { LinkPreview } from './link-preview'

package/dist/template/src/components/mdx/link-preview.tsx

@@ -0,0 +1,119 @@
+'use client'
+
+import { useState, useRef, useCallback, useEffect } from 'react'
+import Link from 'next/link'
+
+interface LinkPreviewProps {
+  href: string
+  children: React.ReactNode
+}
+
+export function LinkPreview({ href, children }: LinkPreviewProps) {
+  const [showPreview, setShowPreview] = useState(false)
+  const [position, setPosition] = useState<{ top: number; left: number } | null>(null)
+  const linkRef = useRef<HTMLAnchorElement>(null)
+  const hoverTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const leaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const isInternal = href.startsWith('/docs/') || href.startsWith('/docs')
+
+  // Derive a human-readable title from the link text (children) or href
+  const title = typeof children === 'string'
+    ? children
+    : href
+        .replace(/^\/docs\/?/, '')
+        .replace(/\//g, ' > ')
+        .replace(/-/g, ' ')
+        .replace(/\b\w/g, (c) => c.toUpperCase()) || 'Documentation'
+
+  const updatePosition = useCallback(() => {
+    if (!linkRef.current) return
+    const rect = linkRef.current.getBoundingClientRect()
+    setPosition({
+      top: rect.top,
+      left: rect.left + rect.width / 2,
+    })
+  }, [])
+
+  const handleMouseEnter = useCallback(() => {
+    if (!isInternal) return
+    if (leaveTimerRef.current) {
+      clearTimeout(leaveTimerRef.current)
+      leaveTimerRef.current = null
+    }
+    hoverTimerRef.current = setTimeout(() => {
+      updatePosition()
+      setShowPreview(true)
+    }, 300)
+  }, [isInternal, updatePosition])
+
+  const handleMouseLeave = useCallback(() => {
+    if (hoverTimerRef.current) {
+      clearTimeout(hoverTimerRef.current)
+      hoverTimerRef.current = null
+    }
+    leaveTimerRef.current = setTimeout(() => {
+      setShowPreview(false)
+    }, 150)
+  }, [])
+
+  // Cleanup timers on unmount
+  useEffect(() => {
+    return () => {
+      if (hoverTimerRef.current) clearTimeout(hoverTimerRef.current)
+      if (leaveTimerRef.current) clearTimeout(leaveTimerRef.current)
+    }
+  }, [])
+
+  // For external links, render a plain anchor
+  if (!isInternal) {
+    return (
+      <a href={href} target="_blank" rel="noopener noreferrer">
+        {children}
+      </a>
+    )
+  }
+
+  return (
+    <>
+      <Link
+        ref={linkRef}
+        href={href}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+        onFocus={handleMouseEnter}
+        onBlur={handleMouseLeave}
+      >
+        {children}
+      </Link>
+      {showPreview && position && (
+        <span
+          className="link-preview-card"
+          style={{
+            position: 'fixed',
+            top: position.top - 8,
+            left: position.left,
+            transform: 'translate(-50%, -100%)',
+            zIndex: 100,
+          }}
+          onMouseEnter={() => {
+            if (leaveTimerRef.current) {
+              clearTimeout(leaveTimerRef.current)
+              leaveTimerRef.current = null
+            }
+          }}
+          onMouseLeave={handleMouseLeave}
+        >
+          <span className="block px-3 py-2 rounded-lg bg-[var(--color-bg)] border border-[var(--color-border)] shadow-lg max-w-[240px]">
+            <span className="block text-sm font-medium text-[var(--color-text)] truncate">
+              {title}
+            </span>
+            <span className="block text-xs text-[var(--color-text-tertiary)] mt-0.5">
+              Click to navigate
+            </span>
+          </span>
+        </span>
+      )}
+    </>
+  )
+}