@pyreon/zero 0.24.5 → 0.24.6

package/src/api-routes.ts

@@ -1,219 +0,0 @@
-import type { Middleware, MiddlewareContext } from '@pyreon/server'
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-/** HTTP methods supported by API routes. */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'
-
-/** Context passed to API route handlers. */
-export interface ApiContext {
-  /** The incoming request. */
-  request: Request
-  /** Parsed URL. */
-  url: URL
-  /** URL path. */
-  path: string
-  /** Dynamic route parameters (e.g., { id: "123" }). */
-  params: Record<string, string>
-  /** Request headers. */
-  headers: Headers
-}
-
-/** An API route handler function. */
-export type ApiHandler = (ctx: ApiContext) => Response | Promise<Response>
-
-/** An API route module — exports named HTTP method handlers. */
-export interface ApiRouteModule {
-  GET?: ApiHandler
-  POST?: ApiHandler
-  PUT?: ApiHandler
-  PATCH?: ApiHandler
-  DELETE?: ApiHandler
-  HEAD?: ApiHandler
-  OPTIONS?: ApiHandler
-}
-
-/** A registered API route entry. */
-export interface ApiRouteEntry {
-  /** URL pattern (e.g., "/api/posts/:id"). */
-  pattern: string
-  /** The route module with method handlers. */
-  module: ApiRouteModule
-}
-
-// ─── Pattern matching ────────────────────────────────────────────────────────
-
-/**
- * Match a URL path against an API route pattern.
- * Returns extracted params or null if no match.
- */
-export function matchApiRoute(pattern: string, path: string): Record<string, string> | null {
-  const patternParts = pattern.split('/').filter(Boolean)
-  const pathParts = path.split('/').filter(Boolean)
-  const params: Record<string, string> = {}
-
-  // A param NAME comes from the route pattern (file-based route like
-  // `[__proto__].ts`) — developer-controlled, so this is defense-in-depth
-  // rather than an attacker vector, but assigning `params['__proto__'] =
-  // …` still mutates the result object's prototype instead of setting a
-  // param. Skip the dangerous names (consistent with reconcile / i18n
-  // deepMerge guards) so a stray route name can't pollute.
-  const isUnsafeParam = (name: string): boolean =>
-    name === '__proto__' || name === 'constructor' || name === 'prototype'
-
-  for (let i = 0; i < patternParts.length; i++) {
-    const pp = patternParts[i]
-    if (!pp) continue
-
-    // Catch-all: :param*
-    if (pp.endsWith('*')) {
-      const paramName = pp.slice(1, -1)
-      if (!isUnsafeParam(paramName)) params[paramName] = pathParts.slice(i).join('/')
-      return params
-    }
-
-    // No more path segments
-    if (i >= pathParts.length) return null
-
-    // Dynamic segment: :param
-    if (pp.startsWith(':')) {
-      const paramName = pp.slice(1)
-      if (!isUnsafeParam(paramName)) params[paramName] = pathParts[i]!
-      continue
-    }
-
-    // Static segment
-    if (pp !== pathParts[i]) return null
-  }
-
-  return patternParts.length === pathParts.length ? params : null
-}
-
-// ─── Middleware ───────────────────────────────────────────────────────────────
-
-const HTTP_METHODS: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']
-
-/**
- * Create a middleware that dispatches API route requests.
- * API routes are matched by URL pattern and HTTP method.
- */
-export function createApiMiddleware(routes: ApiRouteEntry[]): Middleware {
-  return async (ctx: MiddlewareContext) => {
-    for (const route of routes) {
-      const params = matchApiRoute(route.pattern, ctx.path)
-      if (!params) continue
-
-      const method = ctx.req.method.toUpperCase() as HttpMethod
-      const handler = route.module[method]
-
-      if (!handler) {
-        // Route matched but method not supported
-        const allowed = HTTP_METHODS.filter((m) => route.module[m]).join(', ')
-        return new Response(null, {
-          status: 405,
-          headers: {
-            Allow: allowed,
-            'Content-Type': 'application/json',
-          },
-        })
-      }
-
-      return handler({
-        request: ctx.req,
-        url: ctx.url,
-        path: ctx.path,
-        params,
-        headers: ctx.req.headers,
-      })
-    }
-  }
-}
-
-// ─── Virtual module generation ───────────────────────────────────────────────
-
-/**
- * Detect whether a route file is an API route.
- * API routes are `.ts` or `.js` files inside an `api/` directory.
- */
-export function isApiRoute(filePath: string): boolean {
-  const normalized = filePath.replace(/\\/g, '/')
-  return (
-    normalized.startsWith('api/') &&
-    (normalized.endsWith('.ts') || normalized.endsWith('.js')) &&
-    !normalized.endsWith('.tsx') &&
-    !normalized.endsWith('.jsx')
-  )
-}
-
-/**
- * Convert an API route file path to a URL pattern.
- *
- * Examples:
- *   "api/posts.ts"        → "/api/posts"
- *   "api/posts/index.ts"  → "/api/posts"
- *   "api/posts/[id].ts"   → "/api/posts/:id"
- *   "api/[...path].ts"    → "/api/:path*"
- */
-export function apiFilePathToPattern(filePath: string): string {
-  let route = filePath
-  // Remove extension
-  for (const ext of ['.ts', '.js']) {
-    if (route.endsWith(ext)) {
-      route = route.slice(0, -ext.length)
-      break
-    }
-  }
-
-  const segments = route.split('/')
-  const urlSegments: string[] = []
-
-  for (const seg of segments) {
-    if (seg === 'index') continue
-
-    // Catch-all: [...param]
-    const catchAll = seg.match(/^\[\.\.\.(\w+)\]$/)
-    if (catchAll) {
-      urlSegments.push(`:${catchAll[1]}*`)
-      continue
-    }
-
-    // Dynamic: [param]
-    const dynamic = seg.match(/^\[(\w+)\]$/)
-    if (dynamic) {
-      urlSegments.push(`:${dynamic[1]}`)
-      continue
-    }
-
-    urlSegments.push(seg)
-  }
-
-  return `/${urlSegments.join('/')}`
-}
-
-/**
- * Generate a virtual module that exports API route entries.
- * Each entry maps a URL pattern to a module with HTTP method handlers.
- */
-export function generateApiRouteModule(files: string[], routesDir: string): string {
-  const apiFiles = files.filter(isApiRoute)
-
-  if (apiFiles.length === 0) {
-    return 'export const apiRoutes = []\n'
-  }
-
-  const imports: string[] = []
-  const entries: string[] = []
-
-  for (let i = 0; i < apiFiles.length; i++) {
-    const name = `_api${i}`
-    const file = apiFiles[i]
-    if (!file) continue
-    const fullPath = `${routesDir}/${file}`
-    const pattern = apiFilePathToPattern(file)
-
-    imports.push(`import * as ${name} from "${fullPath}"`)
-    entries.push(`  { pattern: ${JSON.stringify(pattern)}, module: ${name} }`)
-  }
-
-  return [...imports, '', 'export const apiRoutes = [', entries.join(',\n'), ']'].join('\n')
-}

package/src/app.ts

@@ -1,92 +0,0 @@
-import type { ComponentFn, Props } from '@pyreon/core'
-import { Fragment, h } from '@pyreon/core'
-import { HeadProvider } from '@pyreon/head'
-import type { RouteRecord } from '@pyreon/router'
-import { createRouter, RouterProvider, RouterView } from '@pyreon/router'
-
-// ─── App assembly ────────────────────────────────────────────────────────────
-
-export interface CreateAppOptions {
-  /** Route definitions (from file-based routing or manual). */
-  routes: RouteRecord[]
-
-  /** Router mode. Default: "history" for SSR, "hash" for SPA. */
-  routerMode?: 'hash' | 'history'
-
-  /** Initial URL for SSR. */
-  url?: string
-
-  /** Root layout component wrapping all routes. */
-  layout?: ComponentFn
-
-  /** Global error component. */
-  errorComponent?: ComponentFn
-
-  /**
-   * Base URL prefix for the deployed app (e.g. `/blog/`). Forwarded to
-   * `createRouter({ base })` so RouterLinks render correctly prefixed
-   * hrefs (`<a href="/blog/about">` instead of `<a href="/about">`) and
-   * the router strips the prefix from incoming URLs before matching.
-   *
-   * Default: `'/'`. Pre-fix this was disconnected from `zero({ base })`
-   * — RouterLinks rendered un-prefixed hrefs even when Vite's asset URL
-   * rewriting was correctly using the prefix, causing client-side
-   * navigation to break against subpath deploys.
-   */
-  base?: string
-}
-
-/**
- * Create a full Zero app — assembles router, head provider, and root layout.
- *
- * Used internally by entry-server and entry-client.
- */
-export function createApp(options: CreateAppOptions) {
-  const router = createRouter({
-    routes: options.routes,
-    mode: options.routerMode ?? 'history',
-    ...(options.url ? { url: options.url } : {}),
-    ...(options.base && options.base !== '/' ? { base: options.base } : {}),
-    scrollBehavior: 'top',
-  })
-
-  // Detect the "double layout" footgun. fs-router emits `_layout.tsx` as a
-  // parent route record (the canonical Pyreon way to register a layout via
-  // file-system routing). If the user ALSO passes `options.layout` referring
-  // to the same component, the layout mounts twice — once via App's wrapper
-  // and once via the matched route chain. Result on hydration mismatch:
-  // 3× `nav.sidebar` + 3× `main.content`.
-  //
-  // Defense: when `options.layout` references the same component as ANY
-  // top-level route's `component`, drop the explicit option (the route-chain
-  // path is canonical) and warn in dev. Anyone who genuinely wants two
-  // layout wrappers can compose them inside a single component themselves.
-  const hasLayoutInRoutes =
-    options.layout !== undefined &&
-    options.routes.some((r) => r.component === options.layout)
-  if (hasLayoutInRoutes && process.env.NODE_ENV !== 'production') {
-    // oxlint-disable-next-line no-console
-    console.warn(
-      '[Pyreon] `createApp({ layout })` was passed a component that is ALSO a parent route in the matched chain (likely an fs-router `_layout.tsx`). The explicit `layout` option is being ignored to prevent double-mount. Remove the `layout` argument from `createApp`/`startClient` — the fs-router-emitted route handles it.',
-    )
-  }
-  const Layout = hasLayoutInRoutes ? DefaultLayout : (options.layout ?? DefaultLayout)
-
-  function App() {
-    return h(
-      HeadProvider,
-      null,
-      h(
-        RouterProvider as ComponentFn<Props>,
-        { router },
-        h(Layout, null, h(RouterView as ComponentFn<Props>, null)),
-      ),
-    )
-  }
-
-  return { App, router }
-}
-
-function DefaultLayout(props: Props) {
-  return h(Fragment, null, ...(Array.isArray(props.children) ? props.children : [props.children]))
-}

package/src/cache.ts

@@ -1,136 +0,0 @@
-import type { Middleware, MiddlewareContext } from '@pyreon/server'
-
-// ─── Cache control middleware ───────────────────────────────────────────────
-//
-// Smart caching middleware that sets appropriate cache headers based on
-// asset type, URL patterns, and build hashes.
-//
-// Strategies:
-// - Immutable: hashed assets (JS/CSS bundles) — cached forever
-// - Static: images, fonts, media — long cache with revalidation
-// - Dynamic: HTML pages — short or no cache, stale-while-revalidate
-// - API: JSON responses — no cache by default
-
-export interface CacheConfig {
-  /** Cache duration for immutable hashed assets (seconds). Default: 31536000 (1 year) */
-  immutable?: number
-  /** Cache duration for static assets like images/fonts (seconds). Default: 86400 (1 day) */
-  static?: number
-  /** Cache duration for pages (seconds). Default: 0 (no cache) */
-  pages?: number
-  /** Stale-while-revalidate window for pages (seconds). Default: 60 */
-  staleWhileRevalidate?: number
-  /** Custom rules by URL pattern. */
-  rules?: CacheRule[]
-}
-
-export interface CacheRule {
-  /** URL pattern to match (glob-style). e.g. "/api/*" */
-  match: string
-  /** Cache-Control header value. */
-  control: string
-}
-
-const HASHED_ASSET = /\.[a-f0-9]{8,}\.\w+$/
-const STATIC_EXT = /\.(png|jpe?g|gif|svg|webp|avif|ico|woff2?|ttf|otf|eot|mp4|webm|ogg|mp3|wav)$/i
-const SCRIPT_EXT = /\.(js|css|mjs)$/i
-
-/** @internal Exported for testing */
-export function matchGlob(pattern: string, path: string): boolean {
-  // Escape regex special chars, then convert glob wildcards
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-  const regex = escaped.replace(/\*/g, '.*').replace(/\?/g, '.')
-  return new RegExp(`^${regex}$`).test(path)
-}
-
-function resolveControl(
-  path: string,
-  immutableDuration: number,
-  staticDuration: number,
-  pageDuration: number,
-  swr: number,
-): string {
-  if (HASHED_ASSET.test(path)) {
-    return `public, max-age=${immutableDuration}, immutable`
-  }
-  if (SCRIPT_EXT.test(path)) {
-    return `public, max-age=3600, stale-while-revalidate=${swr}`
-  }
-  if (STATIC_EXT.test(path)) {
-    return `public, max-age=${staticDuration}, stale-while-revalidate=${swr}`
-  }
-  if (pageDuration > 0) {
-    return `public, max-age=${pageDuration}, stale-while-revalidate=${swr}`
-  }
-  return 'no-cache'
-}
-
-/**
- * Cache control middleware for Zero.
- * Sets Cache-Control headers on the response based on asset type.
- *
- * @example
- * import { cacheMiddleware } from "@pyreon/zero/cache"
- *
- * export default createHandler({
- *   routes,
- *   middleware: [
- *     cacheMiddleware({
- *       pages: 60,
- *       staleWhileRevalidate: 300,
- *       rules: [
- *         { match: "/api/*", control: "no-store" },
- *       ],
- *     }),
- *   ],
- * })
- */
-export function cacheMiddleware(config: CacheConfig = {}): Middleware {
-  const immutableDuration = config.immutable ?? 31536000
-  const staticDuration = config.static ?? 86400
-  const pageDuration = config.pages ?? 0
-  const swr = config.staleWhileRevalidate ?? 60
-  const rules = config.rules ?? []
-
-  return (ctx: MiddlewareContext) => {
-    const path = ctx.url.pathname
-
-    for (const rule of rules) {
-      if (matchGlob(rule.match, path)) {
-        ctx.headers.set('Cache-Control', rule.control)
-        return
-      }
-    }
-
-    const control = resolveControl(path, immutableDuration, staticDuration, pageDuration, swr)
-    ctx.headers.set('Cache-Control', control)
-  }
-}
-
-/**
- * Security headers middleware.
- * Adds common security headers to all responses.
- */
-export function securityHeaders(): Middleware {
-  return (ctx: MiddlewareContext) => {
-    ctx.headers.set('X-Content-Type-Options', 'nosniff')
-    ctx.headers.set('X-Frame-Options', 'DENY')
-    ctx.headers.set('X-XSS-Protection', '1; mode=block')
-    ctx.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
-    ctx.headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()')
-  }
-}
-
-/**
- * Compression detection middleware.
- * Sets Vary: Accept-Encoding header so caches can serve compressed variants.
- * Actual compression is handled by the runtime (Bun/Node) or reverse proxy.
- */
-export function varyEncoding(): Middleware {
-  return (ctx: MiddlewareContext) => {
-    const existing = ctx.headers.get('Vary')
-    if (!existing?.includes('Accept-Encoding')) {
-      ctx.headers.set('Vary', existing ? `${existing}, Accept-Encoding` : 'Accept-Encoding')
-    }
-  }
-}

package/src/client.ts

@@ -1,143 +0,0 @@
-import type { ComponentFn } from '@pyreon/core'
-import { h } from '@pyreon/core'
-import type { RouteRecord } from '@pyreon/router'
-import { hydrateLoaderData } from '@pyreon/router'
-import { hydrateRoot, mount } from '@pyreon/runtime-dom'
-import { createApp } from './app'
-
-// Vite-injected build-time constant. Defined in `vite-plugin.ts`'s
-// `config()` hook from `zero({ base })`. Falls back to `'/'` for
-// non-Vite builds (test environments, etc.) so the read is always
-// safe. The fallback is documented intent — there's no Pyreon
-// deployment outside Vite that consumes this.
-declare const __ZERO_BASE__: string
-
-// ─── Client entry factory ───────────────────────────────────────────────────
-
-export interface StartClientOptions {
-  /** Route definitions. */
-  routes: RouteRecord[]
-  /** Root layout component. */
-  layout?: ComponentFn
-}
-
-/**
- * Start the client-side app — hydrates SSR content or mounts fresh for SPA.
- *
- * ## Loader data flow
- *
- * Direct navigation to a route with a `loader` function needs data to be
- * available on the VERY FIRST render. This is handled in two modes:
- *
- * - **SSR mode (zero's default)**: the server pre-runs loaders, renders the
- *   HTML with loader data already applied, and embeds a JSON blob in the
- *   HTML as `window.__PYREON_LOADER_DATA__`. On the client we read that
- *   blob and call `hydrateLoaderData(router, data)` BEFORE hydrating — so
- *   the hydration pass sees the same data the SSR render produced
- *   (avoids hydration mismatches and the flash of "not found" fallback).
- *
- * - **SPA cold start (no SSR content)**: no `__PYREON_LOADER_DATA__` was
- *   embedded, so we call `router.replace(currentPath)` after mount to
- *   trigger the loader pipeline for the initial route. The first render
- *   shows whatever the component displays for `useLoaderData() === undefined`
- *   (typically a loading state or fallback); once loaders resolve, the
- *   reactive `useLoaderData` re-renders with the data. This matches
- *   standard SPA loading behavior.
- *
- * Without this wiring, direct URL navigation to a loader-backed route
- * (e.g. `/posts/3`) showed the "Post not found" fallback indefinitely
- * because `useLoaderData()` returned `undefined` forever. The router
- * only ran loaders on in-app navigation (push/replace), not on initial
- * mount.
- *
- * @example
- * import { routes } from "virtual:zero/routes"
- * import { startClient } from "@pyreon/zero/client"
- *
- * startClient({ routes })
- */
-export function startClient(options: StartClientOptions) {
-  // `startClient` is the browser entry point — only ever called from a
-  // user's `client.ts` mounted in the browser. Explicit guard documents
-  // that contract and gives a clearer error than `document is not defined`.
-  if (typeof document === 'undefined') {
-    throw new Error('[Pyreon] startClient() can only be called in the browser.')
-  }
-  const container = document.getElementById('app')
-  if (!container) throw new Error('[Pyreon] Missing #app container element')
-
-  // Read the Vite-injected base so `createRouter({ base })` matches the
-  // value Vite used to rewrite asset URLs. `typeof` guard covers the
-  // edge case where the constant isn't defined (non-Vite test contexts);
-  // missing the constant in a real Vite build is impossible because the
-  // plugin's `config()` hook always declares it via `define`.
-  const base =
-    typeof __ZERO_BASE__ !== 'undefined' && __ZERO_BASE__ !== '/'
-      ? __ZERO_BASE__
-      : undefined
-
-  const { App, router } = createApp({
-    routes: options.routes,
-    routerMode: 'history',
-    ...(options.layout ? { layout: options.layout } : {}),
-    ...(base ? { base } : {}),
-  })
-
-  // ── Loader data hydration (SSR path) ───────────────────────────────────────
-  // If the server embedded loader data, hydrate it BEFORE mounting so the
-  // initial render sees the same data the SSR pass produced. This avoids
-  // hydration mismatches and eliminates the flash-of-fallback.
-  const ssrLoaderData = (window as unknown as Record<string, unknown>)
-    .__PYREON_LOADER_DATA__
-  const hasSSRLoaderData =
-    ssrLoaderData !== undefined &&
-    typeof ssrLoaderData === 'object' &&
-    ssrLoaderData !== null
-  if (hasSSRLoaderData) {
-    // `router` is the public Router<> type; hydrateLoaderData uses the
-    // internal RouterInstance shape. The cast is safe because they're
-    // the same object at runtime — just narrower/wider type views.
-    hydrateLoaderData(router as never, ssrLoaderData as Record<string, unknown>)
-  }
-
-  const vnode = h(App, null)
-
-  // ── Mount vs hydrate ───────────────────────────────────────────────────────
-  // Ignore comment nodes (Vite injects <!--app-html-->) — only real DOM
-  // elements or text nodes count as SSR content worth hydrating.
-  const hasSSRContent = Array.from(container.childNodes).some(
-    (n) => n.nodeType === 1 || (n.nodeType === 3 && n.textContent!.trim().length > 0),
-  )
-  const cleanup = hasSSRContent ? hydrateRoot(container, vnode) : mount(vnode, container)
-
-  // ── Loader run (SPA cold-start path) ───────────────────────────────────────
-  // If we had no SSR loader data AND no SSR content, this is a true SPA
-  // cold start. Trigger the router's loader pipeline for the current route
-  // via `replace()` with the same path — doesn't change the URL, just kicks
-  // off the loader batch. Guards, middleware, and redirects run too, which
-  // matches what any other route navigation would do.
-  //
-  // If we DID have SSR content but NO loader data — that's an unusual case
-  // (SSR disabled for this route but loader defined). Run loaders anyway so
-  // the client catches up.
-  if (!hasSSRLoaderData) {
-    const currentPath = router.currentRoute().path
-    router.replace(currentPath).catch((err: unknown) => {
-      // Loader failures are already reported via the route's error handling
-      // pipeline. We swallow the promise rejection here to prevent unhandled
-      // rejection warnings — the route's `errorComponent` (if any) already
-      // handled the display.
-      // @ts-ignore — `import.meta.env.DEV` is provided by Vite/Rolldown at build time
-      if (import.meta.env?.DEV === true) {
-        // oxlint-disable-next-line no-console
-        console.warn(
-          '[Pyreon] Initial loader run failed for route:',
-          currentPath,
-          err,
-        )
-      }
-    })
-  }
-
-  return cleanup
-}