@pyreon/zero 0.11.8 → 0.11.10

package/src/index.ts

@@ -1,136 +1,185 @@
 // ─── Core ─────────────────────────────────────────────────────────────────────
 
-export type { CreateAppOptions } from './app'
-export { createApp } from './app'
-export type { CreateServerOptions } from './entry-server'
-export { createServer } from './entry-server'
+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'
+export { zeroPlugin as default } from "./vite-plugin";
 
 // ─── File-system routing ─────────────────────────────────────────────────────
 
+export type { GenerateRouteModuleOptions } from './fs-router'
 export {
-  filePathToUrlPath,
-  generateMiddlewareModule,
-  generateRouteModule,
-  parseFileRoutes,
-  scanRouteFiles,
+	filePathToUrlPath,
+	generateMiddlewareModule,
+	generateRouteModule,
+	parseFileRoutes,
+	scanRouteFiles,
 } from './fs-router'
 
 // ─── Config ──────────────────────────────────────────────────────────────────
 
-export { defineConfig, resolveConfig } from './config'
+export { defineConfig, resolveConfig } from "./config";
 
 // ─── ISR ─────────────────────────────────────────────────────────────────────
 
-export { createISRHandler } from './isr'
+export { createISRHandler } from "./isr";
 
 // ─── Adapters ────────────────────────────────────────────────────────────────
 
-export { bunAdapter, nodeAdapter, resolveAdapter, staticAdapter } from './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'
+export type { ImageProps, ImageSource } from "./image";
+export { Image } from "./image";
+export type { LinkProps, LinkRenderProps, UseLinkReturn } from "./link";
+export { createLink, Link, prefetchRoute, useLink } from "./link";
+export type { ScriptProps, ScriptStrategy } from "./script";
+export { Script } from "./script";
+
+// ─── 404 Not Found ──────────────────────────────────────────────────────────
+
+export { render404Page } from "./not-found";
 
 // ─── Middleware ──────────────────────────────────────────────────────────────
 
-export type { CacheConfig, CacheRule } from './cache'
-export { cacheMiddleware, securityHeaders, varyEncoding } from './cache'
+export type { CacheConfig, CacheRule } from "./cache";
+export { cacheMiddleware, securityHeaders, varyEncoding } from "./cache";
+export { compose, getContext } from "./middleware";
 
 // ─── Font optimization ─────────────────────────────────────────────────────
 
 export type {
-  FallbackMetrics,
-  FontConfig,
-  FontDisplay,
-  GoogleFontInput,
-  GoogleFontStatic,
-  GoogleFontVariable,
-  LocalFont,
-} from './font'
-export { fontPlugin, fontVariables } from './font'
+	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'
+export type {
+	FormatSource,
+	ImageFormat,
+	ImagePluginConfig,
+	ProcessedImage,
+} from "./image-plugin";
+export { imagePlugin } from "./image-plugin";
 
 // ─── Theme ──────────────────────────────────────────────────────────────────
 
-export type { Theme } from './theme'
+export type { Theme } from "./theme";
 export {
-  initTheme,
-  resolvedTheme,
-  setTheme,
-  ThemeToggle,
-  theme,
-  themeScript,
-  toggleTheme,
-} from './theme'
+	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'
+	ChangeFreq,
+	JsonLdType,
+	RobotsConfig,
+	RobotsRule,
+	SeoPluginConfig,
+	SitemapConfig,
+	SitemapEntry,
+} from "./seo";
+export {
+	generateRobots,
+	generateSitemap,
+	jsonLd,
+	seoMiddleware,
+	seoPlugin,
+} from "./seo";
 
 // ─── API routes ──────────────────────────────────────────────────────────────
 
 export type {
-  ApiContext,
-  ApiHandler,
-  ApiRouteEntry,
-  ApiRouteModule,
-  HttpMethod,
-} from './api-routes'
-export { createApiMiddleware, generateApiRouteModule } from './api-routes'
+	ApiContext,
+	ApiHandler,
+	ApiRouteEntry,
+	ApiRouteModule,
+	HttpMethod,
+} from "./api-routes";
+export { createApiMiddleware, generateApiRouteModule } from "./api-routes";
 
 // ─── CORS ────────────────────────────────────────────────────────────────────
 
-export type { CorsConfig } from './cors'
-export { corsMiddleware } from './cors'
+export type { CorsConfig } from "./cors";
+export { corsMiddleware } from "./cors";
 
 // ─── Rate limiting ──────────────────────────────────────────────────────────
 
-export type { RateLimitConfig } from './rate-limit'
-export { rateLimitMiddleware } from './rate-limit'
+export type { RateLimitConfig } from "./rate-limit";
+export { rateLimitMiddleware } from "./rate-limit";
 
 // ─── Compression ────────────────────────────────────────────────────────────
 
-export type { CompressionConfig } from './compression'
-export { compressionMiddleware, compressResponse, isCompressible } from './compression'
+export type { CompressionConfig } from "./compression";
+export {
+	compressionMiddleware,
+	compressResponse,
+	isCompressible,
+} from "./compression";
 
 // ─── Actions ─────────────────────────────────────────────────────────────────
 
-export type { Action, ActionContext, ActionHandler } from './actions'
-export { createActionMiddleware, defineAction } from './actions'
+export type { Action, ActionContext, ActionHandler } from "./actions";
+export { createActionMiddleware, defineAction } from "./actions";
+
+// ─── Favicon ────────────────────────────────────────────────────────────────
+
+export type { FaviconPluginConfig } from "./favicon";
+export { faviconPlugin } from "./favicon";
+
+// ─── Meta ───────────────────────────────────────────────────────────────────
+
+export type { MetaProps } from "./meta";
+export { buildMetaTags, Meta } from "./meta";
+
+// ─── I18n routing ───────────────────────────────────────────────────────────
+
+export type { I18nRoutingConfig, LocaleContext } from "./i18n-routing";
+export {
+	buildLocalePath,
+	createLocaleContext,
+	detectLocaleFromHeader,
+	extractLocaleFromPath,
+	i18nRouting,
+	setLocale,
+	useLocale,
+} from "./i18n-routing";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
 export type {
-  Adapter,
-  AdapterBuildOptions,
-  FileRoute,
-  ISRConfig,
-  LoaderContext,
-  RenderMode,
-  RouteMeta,
-  RouteMiddlewareEntry,
-  RouteModule,
-  ZeroConfig,
-} from './types'
+	Adapter,
+	AdapterBuildOptions,
+	FileRoute,
+	ISRConfig,
+	LoaderContext,
+	RenderMode,
+	RouteMeta,
+	RouteMiddlewareEntry,
+	RouteModule,
+	ZeroConfig,
+} from "./types";

package/src/link.tsx

@@ -30,6 +30,8 @@ export interface LinkProps {
   style?: string
   /** ARIA label. */
   'aria-label'?: string
+  /** Additional click handler — called before navigation. Call e.preventDefault() to cancel. */
+  onClick?: ((e: MouseEvent) => void) | undefined
 }
 
 /** Props passed to a custom component via createLink. */
@@ -90,6 +92,18 @@ function doPrefetch(href: string) {
   }
 }
 
+/**
+ * Prefetch a route's JS chunk by injecting `<link rel="prefetch">` into the
+ * document head. Deduplicates — calling with the same href twice is a no-op.
+ *
+ * @example
+ * prefetchRoute('/about')
+ * prefetchRoute('/dashboard')
+ */
+export function prefetchRoute(href: string): void {
+  doPrefetch(href)
+}
+
 /**
  * Composable that provides all link behavior — navigation, prefetching,
  * active state, and viewport observation.
@@ -112,6 +126,11 @@ export function useLink(props: LinkProps): UseLinkReturn {
   const strategy = props.prefetch ?? 'hover'
 
   function handleClick(e: MouseEvent) {
+    // Call user's onClick first — they may call e.preventDefault()
+    if (props.onClick) {
+      ;(props.onClick as (e: MouseEvent) => void)(e)
+    }
+
     if (
       e.defaultPrevented ||
       e.button !== 0 ||

package/src/meta.tsx

@@ -0,0 +1,210 @@
+import type { VNodeChild } from '@pyreon/core'
+import { useHead } from '@pyreon/head'
+import type { I18nRoutingConfig } from './i18n-routing'
+import { extractLocaleFromPath } from './i18n-routing'
+
+// ─── Meta component ────────────────────────────────────────────────────────
+
+export interface MetaProps {
+  /** Page title. Accepts reactive accessor `() => string`. */
+  title?: string | (() => string)
+  /** Page description. Accepts reactive accessor. */
+  description?: string | (() => string)
+  /** Canonical URL. Also sets og:url. */
+  canonical?: string
+  /** Open Graph image URL. Also sets twitter:image. */
+  image?: string
+  /** Image alt text for accessibility. */
+  imageAlt?: string
+  /** Open Graph type. Default: "website" */
+  type?: 'website' | 'article' | 'product' | 'profile'
+  /** Site name for og:site_name. */
+  siteName?: string
+  /** Twitter card type. Default: "summary_large_image" */
+  twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player'
+  /** Twitter @handle. */
+  twitterSite?: string
+  /** Twitter creator @handle. */
+  twitterCreator?: string
+  /** Locale. Default: "en_US" */
+  locale?: string
+  /** Alternate locales for hreflang. */
+  alternateLocales?: Array<{ locale: string; url: string }>
+  /** Robots directives. Default: "index, follow" */
+  robots?: string
+  /** Published time (ISO 8601) for article type. */
+  publishedTime?: string
+  /** Modified time (ISO 8601) for article type. */
+  modifiedTime?: string
+  /** Article author. */
+  author?: string
+  /** Article tags. */
+  tags?: string[]
+  /** JSON-LD structured data object. */
+  jsonLd?: Record<string, unknown>
+  /** Additional custom meta tags. */
+  extra?: Array<{ name?: string; property?: string; content: string }>
+  /**
+   * I18n routing config — when provided, auto-generates hreflang alternate
+   * links for all locales based on the current path.
+   * Also sets og:locale and og:locale:alternate.
+   */
+  i18n?: I18nRoutingConfig
+  /** Base URL for building absolute hreflang URLs. e.g. "https://example.com" */
+  origin?: string
+  children?: VNodeChild
+}
+
+const resolveStr = (v: string | (() => string) | undefined): string | undefined =>
+  typeof v === 'function' ? v() : v
+
+/**
+ * Declarative meta component for SSR-compatible page metadata.
+ *
+ * Supports reactive title/description — when passed as `() => string` accessors,
+ * they are forwarded to `useHead()` as a reactive getter so updates propagate
+ * automatically via signal tracking.
+ *
+ * @example
+ * ```tsx
+ * <Meta title="My Page" description="..." image="/og.jpg" canonical="https://..." />
+ * ```
+ *
+ * @example Reactive title
+ * ```tsx
+ * const count = signal(0)
+ * <Meta title={() => `${count()} items`} />
+ * ```
+ */
+export function Meta(props: MetaProps): VNodeChild {
+  const hasReactiveTitle = typeof props.title === 'function'
+  const hasReactiveDescription = typeof props.description === 'function'
+
+  // If title or description are reactive accessors, pass a getter to useHead
+  // so it re-evaluates when the signals change.
+  if (hasReactiveTitle || hasReactiveDescription) {
+    useHead((() => {
+      const title = resolveStr(props.title)
+      const description = resolveStr(props.description)
+      const tags = buildMetaTags({ ...props, title, description } as any)
+      return { title, meta: tags.meta, link: tags.link, script: tags.script }
+    }) as any)
+  } else {
+    const title = resolveStr(props.title)
+    const description = resolveStr(props.description)
+    const tags = buildMetaTags({ ...props, title, description } as any)
+    useHead({ title, meta: tags.meta, link: tags.link, script: tags.script } as any)
+  }
+
+  return props.children ?? null
+}
+
+interface MetaTags {
+  meta: Array<Record<string, string>>
+  link: Array<Record<string, string>>
+  script: Array<{ type: string; children: string }>
+}
+
+export function buildMetaTags(
+  props: Omit<MetaProps, 'title' | 'description' | 'children'> & {
+    title?: string
+    description?: string
+  },
+): MetaTags {
+  const meta: Array<Record<string, string>> = []
+  const link: Array<Record<string, string>> = []
+  const script: Array<{ type: string; children: string }> = []
+
+  const {
+    title, description, canonical, image, imageAlt,
+    type = 'website', siteName,
+    twitterCard = 'summary_large_image', twitterSite, twitterCreator,
+    locale = 'en_US', alternateLocales,
+    robots = 'index, follow',
+    publishedTime, modifiedTime, author, tags, jsonLd, extra,
+  } = props
+
+  if (description) meta.push({ name: 'description', content: description })
+  if (robots) meta.push({ name: 'robots', content: robots })
+  if (author) meta.push({ name: 'author', content: author })
+
+  if (title) meta.push({ property: 'og:title', content: title })
+  if (description) meta.push({ property: 'og:description', content: description })
+  if (canonical) meta.push({ property: 'og:url', content: canonical })
+  if (image) meta.push({ property: 'og:image', content: image })
+  if (imageAlt) meta.push({ property: 'og:image:alt', content: imageAlt })
+  meta.push({ property: 'og:type', content: type })
+  if (siteName) meta.push({ property: 'og:site_name', content: siteName })
+  meta.push({ property: 'og:locale', content: locale })
+
+  if (type === 'article') {
+    if (publishedTime) meta.push({ property: 'article:published_time', content: publishedTime })
+    if (modifiedTime) meta.push({ property: 'article:modified_time', content: modifiedTime })
+    if (author) meta.push({ property: 'article:author', content: author })
+    if (tags) for (const tag of tags) meta.push({ property: 'article:tag', content: tag })
+  }
+
+  meta.push({ name: 'twitter:card', content: twitterCard })
+  if (title) meta.push({ name: 'twitter:title', content: title })
+  if (description) meta.push({ name: 'twitter:description', content: description })
+  if (image) meta.push({ name: 'twitter:image', content: image })
+  if (imageAlt) meta.push({ name: 'twitter:image:alt', content: imageAlt })
+  if (twitterSite) meta.push({ name: 'twitter:site', content: twitterSite })
+  if (twitterCreator) meta.push({ name: 'twitter:creator', content: twitterCreator })
+
+  if (canonical) link.push({ rel: 'canonical', href: canonical })
+  if (alternateLocales) {
+    for (const alt of alternateLocales) {
+      link.push({ rel: 'alternate', hreflang: alt.locale, href: alt.url })
+    }
+  }
+
+  if (jsonLd) {
+    script.push({
+      type: 'application/ld+json',
+      children: JSON.stringify({ '@context': 'https://schema.org', ...jsonLd }),
+    })
+  }
+
+  if (extra) for (const tag of extra) meta.push(tag)
+
+  // I18n: auto-generate hreflang alternates from i18nRouting config
+  if (props.i18n) {
+    const i18nConfig = props.i18n
+    const origin = props.origin ?? ''
+    const currentPath = canonical?.replace(origin, '') ?? '/'
+    const { pathWithoutLocale } = extractLocaleFromPath(
+      currentPath,
+      i18nConfig.locales,
+      i18nConfig.defaultLocale,
+    )
+    const strategy = i18nConfig.strategy ?? 'prefix-except-default'
+
+    for (const loc of i18nConfig.locales) {
+      const localizedPath =
+        strategy === 'prefix-except-default' && loc === i18nConfig.defaultLocale
+          ? pathWithoutLocale
+          : `/${loc}${pathWithoutLocale === '/' ? '' : pathWithoutLocale}`
+
+      link.push({
+        rel: 'alternate',
+        hreflang: loc,
+        href: `${origin}${localizedPath}`,
+      })
+
+      // og:locale:alternate for non-current locales
+      if (loc !== locale) {
+        meta.push({ property: 'og:locale:alternate', content: loc })
+      }
+    }
+
+    // x-default hreflang pointing to default locale
+    link.push({
+      rel: 'alternate',
+      hreflang: 'x-default',
+      href: `${origin}${pathWithoutLocale}`,
+    })
+  }
+
+  return { meta, link, script }
+}

package/src/middleware.ts

@@ -0,0 +1,65 @@
+import type { Middleware, MiddlewareContext } from '@pyreon/server'
+
+// ─── Middleware composition ─────────────────────────────────────────────────
+//
+// Chains multiple middleware functions into a single middleware.
+// Each middleware runs in order. If any returns a Response, the chain
+// short-circuits and that Response is returned. If all return void,
+// the composed middleware returns void (continues to rendering).
+
+/**
+ * Compose multiple middleware into a single middleware function.
+ * Middleware runs sequentially — if any returns a Response, the chain stops.
+ *
+ * @example
+ * import { compose } from "@pyreon/zero/middleware"
+ * import { corsMiddleware } from "@pyreon/zero/cors"
+ * import { rateLimitMiddleware } from "@pyreon/zero/rate-limit"
+ *
+ * const combined = compose(
+ *   corsMiddleware({ origin: "*" }),
+ *   rateLimitMiddleware({ max: 100 }),
+ *   cacheMiddleware(),
+ * )
+ */
+export function compose(...middlewares: Middleware[]): Middleware {
+  return async (ctx: MiddlewareContext) => {
+    for (const mw of middlewares) {
+      const result = await mw(ctx)
+      if (result instanceof Response) return result
+    }
+  }
+}
+
+// ─── Shared request context ─────────────────────────────────────────────────
+//
+// Lightweight context bag attached to MiddlewareContext.locals so middleware
+// can communicate without coupling. Uses a namespaced key to avoid collisions
+// with user-defined locals.
+
+const ZERO_CTX_KEY = '__zeroCtx'
+
+/**
+ * Get the shared Zero context from a middleware context.
+ * Creates one if it doesn't exist. Middleware can use this to
+ * pass data to downstream middleware without polluting `ctx.locals`.
+ *
+ * @example
+ * const authMiddleware: Middleware = (ctx) => {
+ *   const zctx = getContext(ctx)
+ *   zctx.userId = "user_123"
+ * }
+ *
+ * const loggingMiddleware: Middleware = (ctx) => {
+ *   const zctx = getContext(ctx)
+ *   console.log("User:", zctx.userId)
+ * }
+ */
+export function getContext(ctx: MiddlewareContext): Record<string, unknown> {
+  let zctx = ctx.locals[ZERO_CTX_KEY] as Record<string, unknown> | undefined
+  if (!zctx) {
+    zctx = {}
+    ctx.locals[ZERO_CTX_KEY] = zctx
+  }
+  return zctx
+}

package/src/not-found.ts

@@ -0,0 +1,44 @@
+import type { ComponentFn } from "@pyreon/core";
+import { h } from "@pyreon/core";
+import { renderToString } from "@pyreon/runtime-server";
+
+// ─── 404 Not Found rendering ────────────────────────────────────────────────
+//
+// Shared utility for rendering 404 pages in both dev (vite-plugin) and
+// production (entry-server). Renders the notFoundComponent into HTML
+// and wraps it in a minimal document if no template is provided.
+
+const DEFAULT_404_BODY =
+	"<h1>404 — Not Found</h1><p>The page you requested does not exist.</p>";
+
+/**
+ * Render a 404 component to a full HTML string.
+ * If no component is provided, returns a default 404 page.
+ */
+export async function render404Page(
+	component: ComponentFn | undefined,
+	template?: string,
+): Promise<string> {
+	let body: string;
+	if (component) {
+		body = await renderToString(h(component, null));
+	} else {
+		body = DEFAULT_404_BODY;
+	}
+
+	if (template?.includes("<!--pyreon-app-->")) {
+		return template.replace("<!--pyreon-app-->", body);
+	}
+
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>404 — Not Found</title>
+</head>
+<body>
+  ${body}
+</body>
+</html>`;
+}

package/src/types.ts

@@ -105,6 +105,8 @@ export interface FileRoute {
   isError: boolean
   /** Whether this is a loading fallback file. */
   isLoading: boolean
+  /** Whether this is a not-found (404) file. */
+  isNotFound: boolean
   /** Whether this is a catch-all route. */
   isCatchAll: boolean
   /** Resolved rendering mode. */