@pyreon/zero 0.1.0

package/src/seo.ts

@@ -0,0 +1,281 @@
+import type { Middleware } from '@pyreon/server'
+import type { Plugin } from 'vite'
+
+// ─── SEO utilities ──────────────────────────────────────────────────────────
+//
+// Zero provides built-in SEO tooling:
+// - Automatic sitemap.xml generation from file-based routes
+// - Configurable robots.txt
+// - Structured data (JSON-LD) helpers
+// - Open Graph / Twitter Card meta helpers
+
+export interface SitemapConfig {
+  /** Base URL of the site (required). e.g. "https://example.com" */
+  origin: string
+  /** Paths to exclude from the sitemap. */
+  exclude?: string[]
+  /** Default change frequency. Default: "weekly" */
+  changefreq?: ChangeFreq
+  /** Default priority. Default: 0.7 */
+  priority?: number
+  /** Additional URLs to include (for dynamic routes). */
+  additionalPaths?: SitemapEntry[]
+}
+
+export interface SitemapEntry {
+  path: string
+  changefreq?: ChangeFreq
+  priority?: number
+  lastmod?: string
+}
+
+export type ChangeFreq =
+  | 'always'
+  | 'hourly'
+  | 'daily'
+  | 'weekly'
+  | 'monthly'
+  | 'yearly'
+  | 'never'
+
+/**
+ * Generate a sitemap.xml string from route file paths.
+ */
+export function generateSitemap(
+  routeFiles: string[],
+  config: SitemapConfig,
+): string {
+  const { origin, exclude = [], changefreq = 'weekly', priority = 0.7 } = config
+
+  const paths = routeFiles
+    .filter((f) => {
+      // Exclude layout, error, loading files
+      const name = f
+        .split('/')
+        .pop()
+        ?.replace(/\.\w+$/, '')
+      return name !== '_layout' && name !== '_error' && name !== '_loading'
+    })
+    .map((f) => {
+      // Convert file path to URL
+      let path = f
+        .replace(/\.\w+$/, '')
+        .replace(/\/index$/, '/')
+        .replace(/^index$/, '/')
+
+      // Skip dynamic routes — they need additionalPaths
+      if (path.includes('[')) return null
+
+      // Strip route groups
+      path = path.replace(/\([\w-]+\)\//g, '')
+
+      if (!path.startsWith('/')) path = `/${path}`
+      return path
+    })
+    .filter((p): p is string => p !== null)
+    .filter((p) => !exclude.some((e) => p.startsWith(e)))
+
+  const allPaths: SitemapEntry[] = [
+    ...paths.map((p) => ({ path: p, changefreq, priority })),
+    ...(config.additionalPaths ?? []),
+  ]
+
+  const entries = allPaths
+    .map((entry) => {
+      const loc = `${origin}${entry.path === '/' ? '' : entry.path}`
+      return `  <url>
+    <loc>${escapeXml(loc)}</loc>
+    <changefreq>${entry.changefreq ?? changefreq}</changefreq>
+    <priority>${entry.priority ?? priority}</priority>${entry.lastmod ? `\n    <lastmod>${entry.lastmod}</lastmod>` : ''}
+  </url>`
+    })
+    .join('\n')
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries}
+</urlset>`
+}
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+// ─── Robots.txt ─────────────────────────────────────────────────────────────
+
+export interface RobotsConfig {
+  /** Rules per user-agent. */
+  rules?: RobotsRule[]
+  /** Sitemap URL. */
+  sitemap?: string
+  /** Host directive. */
+  host?: string
+}
+
+export interface RobotsRule {
+  userAgent: string
+  allow?: string[]
+  disallow?: string[]
+  crawlDelay?: number
+}
+
+/**
+ * Generate a robots.txt string.
+ */
+export function generateRobots(config: RobotsConfig = {}): string {
+  const { rules = [{ userAgent: '*', allow: ['/'] }], sitemap, host } = config
+  const lines: string[] = []
+
+  for (const rule of rules) {
+    lines.push(`User-agent: ${rule.userAgent}`)
+    if (rule.allow) {
+      for (const path of rule.allow) lines.push(`Allow: ${path}`)
+    }
+    if (rule.disallow) {
+      for (const path of rule.disallow) lines.push(`Disallow: ${path}`)
+    }
+    if (rule.crawlDelay) lines.push(`Crawl-delay: ${rule.crawlDelay}`)
+    lines.push('')
+  }
+
+  if (sitemap) lines.push(`Sitemap: ${sitemap}`)
+  if (host) lines.push(`Host: ${host}`)
+
+  return lines.join('\n')
+}
+
+// ─── Structured data (JSON-LD) ──────────────────────────────────────────────
+
+export type JsonLdType =
+  | 'WebSite'
+  | 'WebPage'
+  | 'Article'
+  | 'BlogPosting'
+  | 'Product'
+  | 'Organization'
+  | 'Person'
+  | 'BreadcrumbList'
+  | 'FAQPage'
+  | (string & {})
+
+/**
+ * Generate a JSON-LD script tag string for structured data.
+ *
+ * @example
+ * useHead({
+ *   script: [jsonLd({
+ *     "@type": "WebSite",
+ *     name: "My Site",
+ *     url: "https://example.com",
+ *   })],
+ * })
+ */
+export function jsonLd(data: Record<string, unknown>): string {
+  const ld = {
+    '@context': 'https://schema.org',
+    ...data,
+  }
+  return `<script type="application/ld+json">${JSON.stringify(ld)}</script>`
+}
+
+// ─── SEO Vite plugin ────────────────────────────────────────────────────────
+
+export interface SeoPluginConfig {
+  /** Sitemap configuration. */
+  sitemap?: SitemapConfig
+  /** Robots.txt configuration. */
+  robots?: RobotsConfig
+}
+
+/**
+ * Zero SEO Vite plugin.
+ * Generates sitemap.xml and robots.txt at build time.
+ *
+ * @example
+ * import { seoPlugin } from "@pyreon/zero/seo"
+ *
+ * export default {
+ *   plugins: [
+ *     pyreon(),
+ *     zero(),
+ *     seoPlugin({
+ *       sitemap: { origin: "https://example.com" },
+ *       robots: { sitemap: "https://example.com/sitemap.xml" },
+ *     }),
+ *   ],
+ * }
+ */
+export function seoPlugin(config: SeoPluginConfig = {}): Plugin {
+  return {
+    name: 'pyreon-zero-seo',
+    apply: 'build',
+
+    async generateBundle(_, _bundle) {
+      // Generate sitemap.xml
+      if (config.sitemap) {
+        const { scanRouteFiles } = await import('./fs-router')
+        const routesDir = `${process.cwd()}/src/routes`
+
+        try {
+          const files = await scanRouteFiles(routesDir)
+          const sitemap = generateSitemap(files, config.sitemap)
+
+          this.emitFile({
+            type: 'asset',
+            fileName: 'sitemap.xml',
+            source: sitemap,
+          })
+        } catch {
+          // Sitemap generation failed — skip silently
+        }
+      }
+
+      // Generate robots.txt
+      if (config.robots) {
+        const robots = generateRobots(config.robots)
+
+        this.emitFile({
+          type: 'asset',
+          fileName: 'robots.txt',
+          source: robots,
+        })
+      }
+    },
+  }
+}
+
+// ─── SEO middleware (serve sitemap/robots in dev) ────────────────────────────
+
+/**
+ * SEO middleware for dev server.
+ * Serves sitemap.xml and robots.txt dynamically during development.
+ */
+export function seoMiddleware(config: SeoPluginConfig = {}): Middleware {
+  return async (ctx) => {
+    if (ctx.url.pathname === '/robots.txt' && config.robots) {
+      return new Response(generateRobots(config.robots), {
+        headers: { 'Content-Type': 'text/plain' },
+      })
+    }
+
+    if (ctx.url.pathname === '/sitemap.xml' && config.sitemap) {
+      try {
+        const { scanRouteFiles } = await import('./fs-router')
+        const routesDir = `${process.cwd()}/src/routes`
+        const files = await scanRouteFiles(routesDir)
+        const sitemap = generateSitemap(files, config.sitemap)
+
+        return new Response(sitemap, {
+          headers: { 'Content-Type': 'application/xml' },
+        })
+      } catch {
+        // Sitemap generation failed — continue to rendering
+      }
+    }
+  }
+}

package/src/sharp.d.ts

@@ -0,0 +1,20 @@
+declare module 'sharp' {
+  interface SharpInstance {
+    resize(
+      width: number,
+      height?: number,
+      options?: { fit?: string },
+    ): SharpInstance
+    webp(options?: { quality?: number }): SharpInstance
+    avif(options?: { quality?: number }): SharpInstance
+    jpeg(options?: { quality?: number; mozjpeg?: boolean }): SharpInstance
+    png(options?: { compressionLevel?: number }): SharpInstance
+    blur(sigma?: number): SharpInstance
+    toFile(path: string): Promise<void>
+    toBuffer(): Promise<Buffer>
+    metadata(): Promise<{ width?: number; height?: number; format?: string }>
+  }
+
+  function sharp(input: string | Buffer): SharpInstance
+  export default sharp
+}

package/src/theme.tsx

@@ -0,0 +1,162 @@
+import { onMount, onUnmount } from '@pyreon/core'
+import { effect, signal } from '@pyreon/reactivity'
+
+// ─── Theme system ───────────────────────────────────────────────────────────
+//
+// Provides dark/light/system theme support with:
+// - System preference detection via matchMedia
+// - Persistent preference via localStorage
+// - No flash of wrong theme (inline script in HTML)
+// - Reactive theme signal for components
+
+export type Theme = 'light' | 'dark' | 'system'
+
+const STORAGE_KEY = 'zero-theme'
+
+/** Reactive theme signal. */
+export const theme = signal<Theme>('system')
+
+/** Computed resolved theme (what's actually applied). */
+export function resolvedTheme(): 'light' | 'dark' {
+  const t = theme()
+  if (t === 'system') {
+    if (typeof window === 'undefined') return 'dark'
+    return window.matchMedia('(prefers-color-scheme: dark)').matches
+      ? 'dark'
+      : 'light'
+  }
+  return t
+}
+
+/** Toggle between light and dark. */
+export function toggleTheme() {
+  const current = resolvedTheme()
+  setTheme(current === 'dark' ? 'light' : 'dark')
+}
+
+/** Set theme explicitly. */
+export function setTheme(t: Theme) {
+  theme.set(t)
+  if (typeof document !== 'undefined') {
+    document.documentElement.dataset.theme = resolvedTheme()
+    try {
+      localStorage.setItem(STORAGE_KEY, t)
+    } catch {
+      // localStorage may not be available (SSR, private browsing)
+    }
+  }
+}
+
+/**
+ * Initialize the theme system. Call once in your app entry or layout.
+ * Reads from localStorage, listens for system preference changes.
+ */
+export function initTheme() {
+  onMount(() => {
+    // Read persisted preference
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY) as Theme | null
+      if (stored === 'light' || stored === 'dark' || stored === 'system') {
+        theme.set(stored)
+      }
+    } catch {
+      // localStorage may not be available
+    }
+
+    // Apply to document
+    document.documentElement.dataset.theme = resolvedTheme()
+
+    // Watch for system preference changes
+    const mq = window.matchMedia('(prefers-color-scheme: dark)')
+    function onChange() {
+      if (theme() === 'system') {
+        document.documentElement.dataset.theme = resolvedTheme()
+      }
+    }
+    mq.addEventListener('change', onChange)
+    onUnmount(() => mq.removeEventListener('change', onChange))
+
+    // Re-apply when theme signal changes
+    const dispose = effect(() => {
+      document.documentElement.dataset.theme = resolvedTheme()
+    })
+    if (dispose) onUnmount(() => dispose.dispose())
+
+    return undefined
+  })
+}
+
+/**
+ * Theme toggle button component.
+ *
+ * @example
+ * import { ThemeToggle } from "@pyreon/zero/theme"
+ * <ThemeToggle />
+ */
+export function ThemeToggle(props: { class?: string; style?: string }) {
+  initTheme()
+
+  return (
+    <button
+      class={props.class}
+      style={props.style}
+      onclick={toggleTheme}
+      aria-label="Toggle theme"
+      title="Toggle theme"
+      type="button"
+    >
+      {() =>
+        resolvedTheme() === 'dark' ? (
+          <svg
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            aria-hidden="true"
+          >
+            <circle cx="12" cy="12" r="5" />
+            <line x1="12" y1="1" x2="12" y2="3" />
+            <line x1="12" y1="21" x2="12" y2="23" />
+            <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
+            <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
+            <line x1="1" y1="12" x2="3" y2="12" />
+            <line x1="21" y1="12" x2="23" y2="12" />
+            <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
+            <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
+          </svg>
+        ) : (
+          <svg
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            aria-hidden="true"
+          >
+            <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+          </svg>
+        )
+      }
+    </button>
+  )
+}
+
+/**
+ * Inline script to prevent flash of wrong theme.
+ * Include this in your index.html <head> BEFORE any stylesheets.
+ *
+ * @example
+ * // index.html
+ * <head>
+ *   <script>{themeScript}</script>
+ *   ...
+ * </head>
+ */
+export const themeScript = `(function(){try{var t=localStorage.getItem("${STORAGE_KEY}");var r=t==="light"?"light":t==="dark"?"dark":window.matchMedia("(prefers-color-scheme:dark)").matches?"dark":"light";document.documentElement.dataset.theme=r}catch(e){}})()`

package/src/types.ts

@@ -0,0 +1,130 @@
+import type { ComponentFn } from '@pyreon/core'
+import type { NavigationGuard } from '@pyreon/router'
+import type { Middleware } from '@pyreon/server'
+
+// ─── Route module conventions ────────────────────────────────────────────────
+
+/** What a route file (e.g. `src/routes/index.tsx`) can export. */
+export interface RouteModule {
+  /** Default export is the page component. */
+  default?: ComponentFn
+  /** Layout wrapper — wraps this route and all children. */
+  layout?: ComponentFn
+  /** Loading component shown while lazy-loading or during Suspense. */
+  loading?: ComponentFn
+  /** Error component shown when the route errors. */
+  error?: ComponentFn
+  /** Server-side data loader. */
+  loader?: (ctx: LoaderContext) => Promise<unknown>
+  /** Per-route middleware. */
+  middleware?: Middleware | Middleware[]
+  /** Navigation guard — can redirect or block navigation. */
+  guard?: NavigationGuard
+  /** Route metadata. */
+  meta?: RouteMeta
+  /** Rendering mode override for this route. */
+  renderMode?: RenderMode
+}
+
+/** Context passed to route loaders. */
+export interface LoaderContext {
+  params: Record<string, string>
+  query: Record<string, string>
+  signal: AbortSignal
+  request: Request
+}
+
+/** Per-route metadata. */
+export interface RouteMeta {
+  title?: string
+  description?: string
+  [key: string]: unknown
+}
+
+// ─── Rendering modes ─────────────────────────────────────────────────────────
+
+export type RenderMode = 'ssr' | 'ssg' | 'spa' | 'isr'
+
+export interface ISRConfig {
+  /** Revalidation interval in seconds. */
+  revalidate: number
+}
+
+// ─── Zero config ─────────────────────────────────────────────────────────────
+
+export interface ZeroConfig {
+  /** Default rendering mode. Default: "ssr" */
+  mode?: RenderMode
+
+  /** Vite config overrides. */
+  vite?: Record<string, unknown>
+
+  /** SSR options. */
+  ssr?: {
+    /** Streaming mode. Default: "string" */
+    mode?: 'string' | 'stream'
+  }
+
+  /** SSG options — only used when mode is "ssg". */
+  ssg?: {
+    /** Paths to prerender (or function returning paths). */
+    paths?: string[] | (() => string[] | Promise<string[]>)
+  }
+
+  /** ISR config — only used when mode is "isr". */
+  isr?: ISRConfig
+
+  /** Deploy adapter. Default: "node" */
+  adapter?: 'node' | 'bun' | 'static'
+
+  /** Base URL path. Default: "/" */
+  base?: string
+
+  /** App-level middleware applied to all routes. */
+  middleware?: Middleware[]
+
+  /** Server port for dev/preview. Default: 3000 */
+  port?: number
+}
+
+// ─── File-system route ───────────────────────────────────────────────────────
+
+/** Internal representation of a file-system route before conversion to RouteRecord. */
+export interface FileRoute {
+  /** File path relative to routes dir (e.g. "users/[id].tsx") */
+  filePath: string
+  /** Parsed URL path pattern (e.g. "/users/:id") */
+  urlPath: string
+  /** Directory path for grouping (e.g. "users" or "" for root) */
+  dirPath: string
+  /** Route segment depth for nesting. */
+  depth: number
+  /** Whether this is a layout file. */
+  isLayout: boolean
+  /** Whether this is an error boundary file. */
+  isError: boolean
+  /** Whether this is a loading fallback file. */
+  isLoading: boolean
+  /** Whether this is a catch-all route. */
+  isCatchAll: boolean
+  /** Resolved rendering mode. */
+  renderMode: RenderMode
+}
+
+// ─── Adapter ─────────────────────────────────────────────────────────────────
+
+export interface Adapter {
+  name: string
+  /** Build the production server/output for this adapter. */
+  build(options: AdapterBuildOptions): Promise<void>
+}
+
+export interface AdapterBuildOptions {
+  /** Path to the built server entry. */
+  serverEntry: string
+  /** Path to the client build output. */
+  clientOutDir: string
+  /** Final output directory. */
+  outDir: string
+  config: ZeroConfig
+}

package/src/utils/use-intersection-observer.ts

@@ -0,0 +1,36 @@
+import { onMount, onUnmount } from '@pyreon/core'
+
+/**
+ * Observes an element and calls `onIntersect` once it enters the viewport.
+ * Automatically disconnects after the first intersection.
+ *
+ * @param getElement - Getter for the target element (may be undefined before mount).
+ * @param onIntersect - Callback fired when the element becomes visible.
+ * @param rootMargin - IntersectionObserver rootMargin. Default: "200px".
+ */
+export function useIntersectionObserver(
+  getElement: () => HTMLElement | undefined,
+  onIntersect: () => void,
+  rootMargin = '200px',
+) {
+  onMount(() => {
+    const el = getElement()
+    if (!el) return undefined
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            onIntersect()
+            observer.disconnect()
+          }
+        }
+      },
+      { rootMargin },
+    )
+
+    observer.observe(el)
+    onUnmount(() => observer.disconnect())
+    return undefined
+  })
+}

package/src/utils/with-headers.ts

@@ -0,0 +1,16 @@
+/**
+ * Clone a Response with modified headers.
+ * Avoids repeating the `new Response(body, { status, statusText, headers })` pattern.
+ */
+export function withHeaders(
+  response: Response,
+  modify: (headers: Headers) => void,
+): Response {
+  const headers = new Headers(response.headers)
+  modify(headers)
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}