@pyreon/zero 0.1.0

package/src/index.ts

@@ -0,0 +1,119 @@
+// ─── Core ─────────────────────────────────────────────────────────────────────
+
+export type { CreateAppOptions } from './app'
+export { createApp } from './app'
+export type { CreateServerOptions } from './entry-server'
+export { createServer } from './entry-server'
+
+// ─── Vite plugin ─────────────────────────────────────────────────────────────
+
+export { zeroPlugin as default } from './vite-plugin'
+
+// ─── File-system routing ─────────────────────────────────────────────────────
+
+export {
+  filePathToUrlPath,
+  generateRouteModule,
+  parseFileRoutes,
+  scanRouteFiles,
+} from './fs-router'
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+export { defineConfig, resolveConfig } from './config'
+
+// ─── ISR ─────────────────────────────────────────────────────────────────────
+
+export { createISRHandler } from './isr'
+
+// ─── Adapters ────────────────────────────────────────────────────────────────
+
+export {
+  bunAdapter,
+  nodeAdapter,
+  resolveAdapter,
+  staticAdapter,
+} from './adapters'
+
+// ─── Components ─────────────────────────────────────────────────────────────
+
+export type { ImageProps, ImageSource } from './image'
+export { Image } from './image'
+export type { LinkProps, LinkRenderProps, UseLinkReturn } from './link'
+export { createLink, Link, useLink } from './link'
+export type { ScriptProps, ScriptStrategy } from './script'
+export { Script } from './script'
+
+// ─── Middleware ──────────────────────────────────────────────────────────────
+
+export type { CacheConfig, CacheRule } from './cache'
+export { cacheMiddleware, securityHeaders, varyEncoding } from './cache'
+
+// ─── Font optimization ─────────────────────────────────────────────────────
+
+export type {
+  FallbackMetrics,
+  FontConfig,
+  FontDisplay,
+  GoogleFontInput,
+  GoogleFontStatic,
+  GoogleFontVariable,
+  LocalFont,
+} from './font'
+export { fontPlugin, fontVariables } from './font'
+
+// ─── Image processing ──────────────────────────────────────────────────────
+
+export type {
+  FormatSource,
+  ImageFormat,
+  ImagePluginConfig,
+  ProcessedImage,
+} from './image-plugin'
+export { imagePlugin } from './image-plugin'
+
+// ─── Theme ──────────────────────────────────────────────────────────────────
+
+export type { Theme } from './theme'
+export {
+  initTheme,
+  resolvedTheme,
+  setTheme,
+  ThemeToggle,
+  theme,
+  themeScript,
+  toggleTheme,
+} from './theme'
+
+// ─── SEO ────────────────────────────────────────────────────────────────────
+
+export type {
+  ChangeFreq,
+  JsonLdType,
+  RobotsConfig,
+  RobotsRule,
+  SeoPluginConfig,
+  SitemapConfig,
+  SitemapEntry,
+} from './seo'
+export {
+  generateRobots,
+  generateSitemap,
+  jsonLd,
+  seoMiddleware,
+  seoPlugin,
+} from './seo'
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type {
+  Adapter,
+  AdapterBuildOptions,
+  FileRoute,
+  ISRConfig,
+  LoaderContext,
+  RenderMode,
+  RouteMeta,
+  RouteModule,
+  ZeroConfig,
+} from './types'

package/src/isr.ts

@@ -0,0 +1,95 @@
+import type { ISRConfig } from './types'
+
+// ─── ISR Cache ───────────────────────────────────────────────────────────────
+
+interface CacheEntry {
+  html: string
+  headers: Record<string, string>
+  timestamp: number
+}
+
+/**
+ * In-memory ISR cache with stale-while-revalidate semantics.
+ *
+ * Wraps an SSR handler and caches responses per URL path.
+ * Serves stale content immediately while revalidating in the background.
+ */
+export function createISRHandler(
+  handler: (req: Request) => Promise<Response>,
+  config: ISRConfig,
+): (req: Request) => Promise<Response> {
+  const cache = new Map<string, CacheEntry>()
+  const revalidating = new Set<string>()
+  const revalidateMs = config.revalidate * 1000
+
+  async function revalidate(url: URL) {
+    const key = url.pathname
+    if (revalidating.has(key)) return
+    revalidating.add(key)
+
+    try {
+      const req = new Request(url.href, { method: 'GET' })
+      const res = await handler(req)
+      const html = await res.text()
+      const headers: Record<string, string> = {}
+      res.headers.forEach((v, k) => {
+        headers[k] = v
+      })
+
+      cache.set(key, { html, headers, timestamp: Date.now() })
+    } catch {
+      // Revalidation failed — stale cache entry remains valid
+    } finally {
+      revalidating.delete(key)
+    }
+  }
+
+  return async (req: Request): Promise<Response> => {
+    // Only cache GET requests
+    if (req.method !== 'GET') {
+      return handler(req)
+    }
+
+    const url = new URL(req.url)
+    const key = url.pathname
+    const entry = cache.get(key)
+
+    if (entry) {
+      const age = Date.now() - entry.timestamp
+
+      if (age > revalidateMs) {
+        // Stale — serve cached but revalidate in background
+        revalidate(url)
+      }
+
+      return new Response(entry.html, {
+        status: 200,
+        headers: {
+          ...entry.headers,
+          'content-type': 'text/html; charset=utf-8',
+          'x-isr-cache': age > revalidateMs ? 'STALE' : 'HIT',
+          'x-isr-age': String(Math.round(age / 1000)),
+        },
+      })
+    }
+
+    // Cache miss — render, cache, and return
+    const res = await handler(req)
+    const html = await res.text()
+    const headers: Record<string, string> = {}
+    res.headers.forEach((v, k) => {
+      headers[k] = v
+    })
+
+    cache.set(key, { html, headers, timestamp: Date.now() })
+
+    return new Response(html, {
+      status: 200,
+      headers: {
+        ...headers,
+        'content-type': 'text/html; charset=utf-8',
+        'x-isr-cache': 'MISS',
+      },
+    })
+  }
+}

package/src/link.tsx

@@ -0,0 +1,266 @@
+import { createRef } from '@pyreon/core'
+import { useRouter } from '@pyreon/router'
+import { useIntersectionObserver } from './utils/use-intersection-observer'
+
+// ─── Link component with prefetching ────────────────────────────────────────
+//
+// Provides client-side navigation, prefetching, and active state tracking.
+// Three levels of API:
+//
+// 1. useLink(props)   — composable returning handlers, state, and ref callback
+// 2. createLink(Comp) — HOC wrapping any component with link behavior
+// 3. Link             — default <a>-based link (built on createLink)
+
+export interface LinkProps {
+  /** Target URL path. */
+  href: string
+  /** Link content. */
+  children?: any
+  /** CSS class name. */
+  class?: string
+  /** Class applied when this link matches the current route. */
+  activeClass?: string
+  /** Class applied when this link exactly matches the current route. */
+  exactActiveClass?: string
+  /** Prefetch strategy. Default: "hover" */
+  prefetch?: 'hover' | 'viewport' | 'none'
+  /** Open in new tab. */
+  external?: boolean
+  /** Inline styles. */
+  style?: string
+  /** ARIA label. */
+  'aria-label'?: string
+}
+
+/** Props passed to a custom component via createLink. */
+export interface LinkRenderProps {
+  href: string
+  ref: import('@pyreon/core').Ref<HTMLElement>
+  onClick: (e: MouseEvent) => void
+  onMouseEnter: () => void
+  onTouchStart: () => void
+  isActive: () => boolean
+  isExactActive: () => boolean
+  /** Reactive class string — pass directly to element for auto-updates on route change. */
+  class: (() => string) | string | undefined
+  style?: string
+  target?: string
+  rel?: string
+  'aria-label'?: string
+  children?: any
+}
+
+/** Return type of useLink. */
+export interface UseLinkReturn {
+  /** Ref object — attach to the root element for viewport-based prefetch. */
+  ref: import('@pyreon/core').Ref<HTMLElement>
+  /** Click handler — performs client-side navigation. */
+  handleClick: (e: MouseEvent) => void
+  /** Mouse enter handler — triggers hover prefetch. */
+  handleMouseEnter: () => void
+  /** Touch start handler — triggers prefetch on mobile. */
+  handleTouchStart: () => void
+  /** Whether the link partially matches the current route. */
+  isActive: () => boolean
+  /** Whether the link exactly matches the current route. */
+  isExactActive: () => boolean
+  /** Resolved class string including active classes. */
+  classes: () => string
+}
+
+const prefetched = new Set<string>()
+
+function doPrefetch(href: string) {
+  if (prefetched.has(href)) return
+  prefetched.add(href)
+
+  const docLink = document.createElement('link')
+  docLink.rel = 'prefetch'
+  docLink.href = href
+  docLink.as = 'document'
+  document.head.appendChild(docLink)
+
+  try {
+    const chunkHint = document.createElement('link')
+    chunkHint.rel = 'modulepreload'
+    chunkHint.href = href
+    document.head.appendChild(chunkHint)
+  } catch {
+    // modulepreload is a hint, not critical
+  }
+}
+
+/**
+ * Composable that provides all link behavior — navigation, prefetching,
+ * active state, and viewport observation.
+ *
+ * Use this for full control when `createLink` is too opinionated.
+ *
+ * @example
+ * function MyLink(props: LinkProps) {
+ *   const link = useLink(props)
+ *   return (
+ *     <button ref={link.ref} class={link.classes()} onclick={link.handleClick}>
+ *       {props.children}
+ *     </button>
+ *   )
+ * }
+ */
+export function useLink(props: LinkProps): UseLinkReturn {
+  const router = useRouter()
+  const elementRef = createRef<HTMLElement>()
+  const strategy = props.prefetch ?? 'hover'
+
+  function handleClick(e: MouseEvent) {
+    if (
+      e.defaultPrevented ||
+      e.button !== 0 ||
+      e.metaKey ||
+      e.ctrlKey ||
+      e.shiftKey ||
+      e.altKey ||
+      props.external
+    ) {
+      return
+    }
+    e.preventDefault()
+    router.push(props.href)
+  }
+
+  function handleMouseEnter() {
+    if (strategy === 'hover') {
+      doPrefetch(props.href)
+    }
+  }
+
+  function handleTouchStart() {
+    if (strategy === 'hover' || strategy === 'viewport') {
+      doPrefetch(props.href)
+    }
+  }
+
+  if (strategy === 'viewport') {
+    useIntersectionObserver(
+      () => elementRef.current ?? undefined,
+      () => doPrefetch(props.href),
+    )
+  }
+
+  const isActive = () => {
+    const currentPath = router.currentRoute()?.path
+    if (!currentPath || !props.href) return false
+    if (props.href === '/') return currentPath === '/'
+    return currentPath.startsWith(props.href)
+  }
+
+  const isExactActive = () => {
+    const currentPath = router.currentRoute()?.path
+    if (!currentPath) return false
+    return currentPath === props.href
+  }
+
+  const classes = () => {
+    const cls: string[] = []
+    if (props.class) cls.push(props.class)
+    if (props.activeClass && isActive()) cls.push(props.activeClass)
+    if (props.exactActiveClass && isExactActive())
+      cls.push(props.exactActiveClass)
+    return cls.join(' ')
+  }
+
+  return {
+    ref: elementRef,
+    handleClick,
+    handleMouseEnter,
+    handleTouchStart,
+    isActive,
+    isExactActive,
+    classes,
+  }
+}
+
+/**
+ * Higher-order component that wraps any component with link behavior.
+ *
+ * The wrapped component receives {@link LinkRenderProps} with all handlers,
+ * active state, and accessibility attributes pre-wired.
+ *
+ * @example
+ * // Custom button link
+ * const ButtonLink = createLink((props) => (
+ *   <button
+ *     ref={props.ref}
+ *     class={props.class}
+ *     onclick={props.onClick}
+ *     onmouseenter={props.onMouseEnter}
+ *   >
+ *     {props.children}
+ *   </button>
+ * ))
+ *
+ * // Custom styled component
+ * const CardLink = createLink((props) => (
+ *   <div
+ *     ref={props.ref}
+ *     class={`card ${props.isActive() ? "card--active" : ""}`}
+ *     onclick={props.onClick}
+ *     onmouseenter={props.onMouseEnter}
+ *   >
+ *     {props.children}
+ *   </div>
+ * ))
+ *
+ * // Usage
+ * <ButtonLink href="/about">About</ButtonLink>
+ * <CardLink href="/posts" prefetch="viewport">Posts</CardLink>
+ */
+export function createLink(
+  Component: (props: LinkRenderProps) => any,
+): (props: LinkProps) => any {
+  return function WrappedLink(props: LinkProps) {
+    const link = useLink(props)
+
+    return (
+      <Component
+        href={props.href}
+        ref={link.ref}
+        onClick={link.handleClick}
+        onMouseEnter={link.handleMouseEnter}
+        onTouchStart={link.handleTouchStart}
+        isActive={link.isActive}
+        isExactActive={link.isExactActive}
+        class={link.classes}
+        style={props.style}
+        target={props.external ? '_blank' : undefined}
+        rel={props.external ? 'noopener noreferrer' : undefined}
+        aria-label={props['aria-label']}
+        children={props.children}
+      />
+    )
+  }
+}
+
+/**
+ * Default navigation link built on an `<a>` tag.
+ *
+ * @example
+ * <Link href="/about" prefetch="viewport">About</Link>
+ * <Link href="/posts" activeClass="nav-active">Posts</Link>
+ */
+export const Link = createLink((props: LinkRenderProps) => (
+  <a
+    ref={props.ref}
+    href={props.href}
+    class={props.class}
+    style={props.style}
+    target={props.target}
+    rel={props.rel}
+    aria-label={props['aria-label']}
+    aria-current={props.isExactActive() ? 'page' : undefined}
+    onclick={props.onClick}
+    onmouseenter={props.onMouseEnter}
+    ontouchstart={props.onTouchStart}
+  >
+    {props.children}
+  </a>
+))

package/src/script.tsx

@@ -0,0 +1,133 @@
+import { createRef, onMount, onUnmount } from '@pyreon/core'
+import { useIntersectionObserver } from './utils/use-intersection-observer'
+
+// ─── Script optimization component ─────────────────────────────────────────
+//
+// <Script> provides optimized third-party script loading:
+// - Defer loading until after hydration
+// - Load on idle (requestIdleCallback)
+// - Load on interaction (click, scroll, etc.)
+// - Load on viewport entry
+// - Worker offloading for analytics scripts
+
+export interface ScriptProps {
+  /** Script source URL. */
+  src: string
+  /** Loading strategy. Default: "afterHydration" */
+  strategy?: ScriptStrategy
+  /** Inline script content (alternative to src). */
+  children?: string
+  /** Script id for deduplication. */
+  id?: string
+  /** Async attribute. Default: true */
+  async?: boolean
+  /** onLoad callback. */
+  onLoad?: () => void
+  /** onError callback. */
+  onError?: (error: Error) => void
+}
+
+export type ScriptStrategy =
+  | 'beforeHydration'
+  | 'afterHydration'
+  | 'onIdle'
+  | 'onInteraction'
+  | 'onViewport'
+
+/**
+ * Optimized script loading component.
+ *
+ * @example
+ * // Load analytics after page is interactive
+ * <Script src="https://analytics.example.com/script.js" strategy="onIdle" />
+ *
+ * // Load chat widget when user scrolls
+ * <Script src="/chat-widget.js" strategy="onViewport" />
+ *
+ * // Inline script with deferred execution
+ * <Script strategy="afterHydration">
+ *   {`console.log("App hydrated!")`}
+ * </Script>
+ */
+export function Script(props: ScriptProps) {
+  function loadScript() {
+    // Deduplication
+    if (props.id && document.getElementById(props.id)) return
+
+    const script = document.createElement('script')
+    if (props.src) script.src = props.src
+    if (props.id) script.id = props.id
+    script.async = props.async !== false
+
+    if (props.onLoad) script.onload = props.onLoad
+    if (props.onError) {
+      script.onerror = () =>
+        props.onError?.(new Error(`Failed to load: ${props.src}`))
+    }
+
+    if (props.children && !props.src) {
+      script.textContent = props.children
+    }
+
+    document.head.appendChild(script)
+  }
+
+  onMount(() => {
+    const strategy = props.strategy ?? 'afterHydration'
+
+    switch (strategy) {
+      case 'beforeHydration':
+        // Already in HTML — do nothing
+        break
+
+      case 'afterHydration':
+        // Load immediately after mount (hydration is complete)
+        loadScript()
+        break
+
+      case 'onIdle':
+        if ('requestIdleCallback' in window) {
+          requestIdleCallback(() => loadScript(), { timeout: 5000 })
+        } else {
+          setTimeout(loadScript, 200)
+        }
+        break
+
+      case 'onInteraction': {
+        const events = ['click', 'scroll', 'keydown', 'touchstart']
+        function handler() {
+          for (const e of events) document.removeEventListener(e, handler)
+          loadScript()
+        }
+        for (const e of events) {
+          document.addEventListener(e, handler, { once: true, passive: true })
+        }
+        onUnmount(() => {
+          for (const e of events) document.removeEventListener(e, handler)
+        })
+        break
+      }
+
+      case 'onViewport':
+        // Handled below via useIntersectionObserver on the sentinel element
+        break
+    }
+    return undefined
+  })
+
+  const sentinelRef = createRef<HTMLElement>()
+  const strategy = props.strategy ?? 'afterHydration'
+
+  if (strategy === 'onViewport') {
+    useIntersectionObserver(
+      () => sentinelRef.current ?? undefined,
+      () => loadScript(),
+    )
+  }
+
+  if (strategy === 'onViewport') {
+    return <div ref={sentinelRef} style="width:0;height:0;overflow:hidden" />
+  }
+
+  return null
+}