skrypt-ai 0.4.0 → 0.4.2

package/dist/config/loader.js

@@ -36,7 +36,7 @@ function parseConfigFile(filepath) {
     }
     catch (err) {
         throw new Error(`Could not read config file: ${filepath}. ` +
-            (err instanceof Error ? err.message : String(err)));
+            (err instanceof Error ? err.message : String(err)), { cause: err });
     }
     let parsed;
     try {
@@ -45,7 +45,7 @@ function parseConfigFile(filepath) {
     catch (err) {
         throw new Error(`Config file has invalid YAML: ${filepath}. ` +
             `Please check the syntax and try again. ` +
-            (err instanceof Error ? err.message : String(err)));
+            (err instanceof Error ? err.message : String(err)), { cause: err });
     }
     if (parsed === null || parsed === undefined || typeof parsed !== 'object') {
         throw new Error(`Config file is empty or not a valid YAML object: ${filepath}. ` +

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>
+      )}
+    </>
+  )
+}

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

@@ -0,0 +1,101 @@
+'use client'
+
+import { useState, useRef, useCallback, type ReactNode } from 'react'
+
+interface TooltipProps {
+  children: ReactNode
+  content: string
+  side?: 'top' | 'bottom' | 'left' | 'right'
+}
+
+const arrowStyles: Record<string, React.CSSProperties> = {
+  top: {
+    bottom: -4,
+    left: '50%',
+    transform: 'translateX(-50%) rotate(45deg)',
+  },
+  bottom: {
+    top: -4,
+    left: '50%',
+    transform: 'translateX(-50%) rotate(45deg)',
+  },
+  left: {
+    right: -4,
+    top: '50%',
+    transform: 'translateY(-50%) rotate(45deg)',
+  },
+  right: {
+    left: -4,
+    top: '50%',
+    transform: 'translateY(-50%) rotate(45deg)',
+  },
+}
+
+const positionStyles: Record<string, React.CSSProperties> = {
+  top: {
+    bottom: '100%',
+    left: '50%',
+    transform: 'translateX(-50%)',
+    marginBottom: 8,
+  },
+  bottom: {
+    top: '100%',
+    left: '50%',
+    transform: 'translateX(-50%)',
+    marginTop: 8,
+  },
+  left: {
+    right: '100%',
+    top: '50%',
+    transform: 'translateY(-50%)',
+    marginRight: 8,
+  },
+  right: {
+    left: '100%',
+    top: '50%',
+    transform: 'translateY(-50%)',
+    marginLeft: 8,
+  },
+}
+
+export function Tooltip({ children, content, side = 'top' }: TooltipProps) {
+  const [visible, setVisible] = useState(false)
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const show = useCallback(() => {
+    timeoutRef.current = setTimeout(() => setVisible(true), 150)
+  }, [])
+
+  const hide = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = null
+    }
+    setVisible(false)
+  }, [])
+
+  return (
+    <span
+      className="relative inline-flex"
+      onMouseEnter={show}
+      onMouseLeave={hide}
+      onFocus={show}
+      onBlur={hide}
+    >
+      {children}
+      {visible && (
+        <span
+          role="tooltip"
+          className="tooltip-content absolute z-50 whitespace-nowrap bg-[var(--color-gray-900)] text-white text-xs px-2.5 py-1.5 rounded-lg shadow-lg tooltip-fade-in pointer-events-none"
+          style={positionStyles[side]}
+        >
+          {content}
+          <span
+            className="tooltip-content absolute h-2 w-2 bg-[var(--color-gray-900)]"
+            style={arrowStyles[side]}
+          />
+        </span>
+      )}
+    </span>
+  )
+}

package/dist/template/src/components/syntax-theme-selector.tsx

@@ -1,49 +1,196 @@
 'use client'
 
-import { useContext } from 'react'
+import { useContext, useState, useRef, useEffect, useCallback, KeyboardEvent } from 'react'
 import { SyntaxThemeContext } from '@/contexts/syntax-theme'
 import { AVAILABLE_THEMES, DEFAULT_THEME } from '@/lib/highlight'
 import { Palette } from 'lucide-react'
 
 export function SyntaxThemeSelector() {
   const context = useContext(SyntaxThemeContext)
+  const [isOpen, setIsOpen] = useState(false)
+  const [activeIndex, setActiveIndex] = useState(-1)
+  const triggerRef = useRef<HTMLButtonElement>(null)
+  const listRef = useRef<HTMLDivElement>(null)
+  const optionRefs = useRef<(HTMLButtonElement | null)[]>([])
+  const closeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
-  // Safely handle when context isn't available (during SSG)
   const theme = context?.theme ?? DEFAULT_THEME
   const setTheme = context?.setTheme ?? (() => {})
   const availableThemes = context?.availableThemes ?? AVAILABLE_THEMES
 
+  // Find the index of the current active theme
+  const activeThemeIndex = availableThemes.findIndex((t) => t.name === theme)
+
+  const open = useCallback(() => {
+    if (closeTimeoutRef.current) {
+      clearTimeout(closeTimeoutRef.current)
+      closeTimeoutRef.current = null
+    }
+    setIsOpen(true)
+    setActiveIndex(activeThemeIndex >= 0 ? activeThemeIndex : 0)
+  }, [activeThemeIndex])
+
+  const close = useCallback(() => {
+    setIsOpen(false)
+    setActiveIndex(-1)
+  }, [])
+
+  const delayedClose = useCallback(() => {
+    closeTimeoutRef.current = setTimeout(close, 150)
+  }, [close])
+
+  const cancelClose = useCallback(() => {
+    if (closeTimeoutRef.current) {
+      clearTimeout(closeTimeoutRef.current)
+      closeTimeoutRef.current = null
+    }
+  }, [])
+
+  // Focus the active option when activeIndex changes while open
+  useEffect(() => {
+    if (isOpen && activeIndex >= 0) {
+      optionRefs.current[activeIndex]?.focus()
+    }
+  }, [isOpen, activeIndex])
+
+  // Close on outside click
+  useEffect(() => {
+    if (!isOpen) return
+    function handleClick(e: MouseEvent) {
+      const target = e.target as Node
+      if (
+        !triggerRef.current?.contains(target) &&
+        !listRef.current?.contains(target)
+      ) {
+        close()
+      }
+    }
+    document.addEventListener('mousedown', handleClick)
+    return () => document.removeEventListener('mousedown', handleClick)
+  }, [isOpen, close])
+
+  // Close on Escape
+  useEffect(() => {
+    if (!isOpen) return
+    function handleEsc(e: globalThis.KeyboardEvent) {
+      if (e.key === 'Escape') {
+        close()
+        triggerRef.current?.focus()
+      }
+    }
+    document.addEventListener('keydown', handleEsc)
+    return () => document.removeEventListener('keydown', handleEsc)
+  }, [isOpen, close])
+
+  function selectTheme(index: number) {
+    const t = availableThemes[index]
+    if (t) {
+      setTheme(t.name)
+      close()
+      triggerRef.current?.focus()
+    }
+  }
+
+  function handleTriggerKeyDown(e: KeyboardEvent) {
+    if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      open()
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      open()
+      setActiveIndex(availableThemes.length - 1)
+    }
+  }
+
+  function handleOptionKeyDown(e: KeyboardEvent, index: number) {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault()
+        setActiveIndex((index + 1) % availableThemes.length)
+        break
+      case 'ArrowUp':
+        e.preventDefault()
+        setActiveIndex((index - 1 + availableThemes.length) % availableThemes.length)
+        break
+      case 'Home':
+        e.preventDefault()
+        setActiveIndex(0)
+        break
+      case 'End':
+        e.preventDefault()
+        setActiveIndex(availableThemes.length - 1)
+        break
+      case 'Enter':
+      case ' ':
+        e.preventDefault()
+        selectTheme(index)
+        break
+      case 'Tab':
+        close()
+        break
+    }
+  }
+
+  const listboxId = 'syntax-theme-listbox'
+
   return (
-    <div className="relative group">
+    <div
+      className="relative"
+      onMouseEnter={() => { open(); cancelClose() }}
+      onMouseLeave={delayedClose}
+    >
       <button
+        ref={triggerRef}
         className="flex items-center gap-2 px-3 py-1.5 text-sm text-[var(--color-text-secondary)] hover:text-[var(--color-text)] rounded-md hover:bg-[var(--color-bg-secondary)] transition-colors"
         title="Syntax theme"
         aria-label={`Syntax theme: ${theme}`}
         aria-haspopup="listbox"
+        aria-expanded={isOpen}
+        aria-controls={isOpen ? listboxId : undefined}
+        onClick={() => { isOpen ? close() : open() }}
+        onKeyDown={handleTriggerKeyDown}
       >
         <Palette size={16} />
         <span className="hidden sm:inline">Theme</span>
       </button>
 
-      <div className="absolute right-0 top-full mt-1 w-48 py-1 bg-[var(--color-bg)] border border-[var(--color-border)] rounded-lg shadow-lg opacity-0 invisible group-hover:opacity-100 group-hover:visible transition-all z-50">
-        <div className="px-3 py-1.5 text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wide">
+      <div
+        ref={listRef}
+        id={listboxId}
+        role="listbox"
+        aria-label="Syntax theme"
+        aria-activedescendant={activeIndex >= 0 ? `syntax-theme-option-${activeIndex}` : undefined}
+        className={`absolute right-0 top-full mt-1 w-48 py-1 bg-[var(--color-bg)] border border-[var(--color-border)] rounded-lg shadow-lg transition-all z-50 ${
+          isOpen ? 'opacity-100 visible' : 'opacity-0 invisible pointer-events-none'
+        }`}
+      >
+        <div className="px-3 py-1.5 text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wide" aria-hidden="true">
           Syntax Theme
         </div>
-        {availableThemes.map((t) => (
-          <button
-            key={t.name}
-            onClick={() => setTheme(t.name)}
-            className={`w-full px-3 py-1.5 text-left text-sm flex items-center gap-2 hover:bg-[var(--color-bg-secondary)] transition-colors ${
-              theme === t.name ? 'text-[var(--color-primary)]' : 'text-[var(--color-text)]'
-            }`}
-          >
-            <span
-              className={`w-3 h-3 rounded-full ${t.isDark ? 'bg-gray-800' : 'bg-gray-200'}`}
-            />
-            {t.label}
-            {theme === t.name && <span className="ml-auto text-xs">Active</span>}
-          </button>
-        ))}
+        {availableThemes.map((t, index) => {
+          const isSelected = theme === t.name
+          return (
+            <button
+              key={t.name}
+              ref={(el) => { optionRefs.current[index] = el }}
+              id={`syntax-theme-option-${index}`}
+              role="option"
+              aria-selected={isSelected}
+              tabIndex={-1}
+              onClick={() => selectTheme(index)}
+              onKeyDown={(e) => handleOptionKeyDown(e, index)}
+              className={`w-full px-3 py-1.5 text-left text-sm flex items-center gap-2 hover:bg-[var(--color-bg-secondary)] transition-colors ${
+                isSelected ? 'text-[var(--color-primary)]' : 'text-[var(--color-text)]'
+              } ${activeIndex === index ? 'bg-[var(--color-bg-secondary)]' : ''}`}
+            >
+              <span
+                className={`w-3 h-3 rounded-full ${t.isDark ? 'bg-gray-800' : 'bg-gray-200'}`}
+              />
+              {t.label}
+              {isSelected && <span className="ml-auto text-xs">Active</span>}
+            </button>
+          )
+        })}
       </div>
     </div>
   )

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

@@ -121,6 +121,12 @@
   :root:not(.light) .feedback-negative { background-color: rgba(127, 29, 29, 0.3); color: #f87171; }
 }
 
+/* Tooltip — dark mode overrides */
+:root.dark .tooltip-content { background-color: var(--color-gray-100); color: var(--color-gray-900); }
+@media (prefers-color-scheme: dark) {
+  :root:not(.light) .tooltip-content { background-color: var(--color-gray-100); color: var(--color-gray-900); }
+}
+
 /* ========================
    Base — in @layer base so Tailwind utilities can override
    ======================== */
@@ -463,3 +469,36 @@ input:focus-visible, textarea:focus-visible {
   animation: shimmer 1.5s infinite;
   border-radius: 0.25rem;
 }
+
+/* ========================
+   Tooltip fade-in
+   ======================== */
+@keyframes tooltip-fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+.tooltip-fade-in {
+  animation: tooltip-fade-in 150ms ease-out;
+}
+
+/* ========================
+   Page transitions — subtle fade-in for article content
+   ======================== */
+@keyframes page-fade-in {
+  from { opacity: 0; transform: translateY(4px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+.prose {
+  animation: page-fade-in 200ms ease-out;
+}
+
+/* ========================
+   Link preview card
+   ======================== */
+@keyframes link-preview-in {
+  from { opacity: 0; transform: translate(-50%, -100%) translateY(4px); }
+  to { opacity: 1; transform: translate(-50%, -100%) translateY(0); }
+}
+.link-preview-card {
+  animation: link-preview-in 150ms ease-out;
+}

package/dist/utils/validation.js

@@ -31,7 +31,7 @@ export function validateSlug(input) {
 }
 export function sanitizeForShell(input) {
     // Only allow safe characters for git refs, filenames, etc.
-    if (!/^[a-zA-Z0-9\/_~.^@{}\-]+$/.test(input)) {
+    if (!/^[a-zA-Z0-9/_~.^@{}-]+$/.test(input)) {
         throw new Error(`Unsafe characters in input: ${input}`);
     }
     return input;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skrypt-ai",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "AI-powered documentation generator with code examples",
   "type": "module",
   "main": "dist/cli.js",