@pyreon/zero 0.14.0 → 0.16.0

package/src/i18n-routing.ts

@@ -1,19 +1,39 @@
 import { createContext } from '@pyreon/core'
 import { signal } from '@pyreon/reactivity'
 import type { Plugin } from 'vite'
+import type { FileRoute } from './types'
 
 // ─── Localized routing ─────────────────────────────────────────────────────
 //
-// Adds locale-prefixed routes to Zero's file-system router:
-// - /about → /en/about, /de/about, /cs/about
-// - / → /en, /de, /cs (or default locale without prefix)
-// - Automatic locale detection from Accept-Language header
-// - Redirect to preferred locale
-// - hreflang link generation
+// Adds locale-prefixed routes to Zero's file-system router (PR H of the SSG
+// roadmap). Two complementary halves:
+//
+// 1. **Build-time route duplication** — `expandRoutesForLocales(routes, config)`
+//    fans every `FileRoute` into per-locale variants according to the
+//    configured `strategy`. Called from `vite-plugin.ts`'s virtual-routes
+//    load AND `ssg-plugin.ts`'s pre-render path expansion. Wired via the
+//    `i18n?: I18nRoutingConfig` field on `ZeroConfig`.
+//
+// 2. **Request-time locale detection** — the `i18nRouting()` Vite plugin
+//    below attaches a middleware that reads `Accept-Language` / cookies,
+//    sets the `localeSignal` for `useLocale()`, and redirects root
+//    requests to the detected locale. Independent from (1) — `i18nRouting()`
+//    only handles middleware; route duplication happens via
+//    `expandRoutesForLocales` regardless of whether this plugin is mounted.
+//
+// Examples (with `locales: ["en","de","cs"]`, `defaultLocale: "en"`):
+// - `prefix-except-default` (default): `/about` (en, unprefixed) +
+//   `/de/about`, `/cs/about`. Best for SEO-on-default-locale apps.
+// - `prefix`: `/en/about`, `/de/about`, `/cs/about`. Every URL
+//   self-identifies its locale.
 //
 // Usage:
-//   import { i18nRouting } from "@pyreon/zero"
-//   export default { plugins: [Pyreon], defaultLocale: "en" })] }
+//   // zero.config.ts
+//   import { defineConfig, i18nRouting } from "@pyreon/zero"
+//   export default defineConfig({
+//     i18n: { locales: ["en","de","cs"], defaultLocale: "en" },
+//     plugins: [i18nRouting({ locales: ["en","de","cs"], defaultLocale: "en" })],
+//   })
 
 export interface I18nRoutingConfig {
   /** Supported locales. e.g. ["en", "de", "cs"] */
@@ -108,6 +128,218 @@ export function buildLocalePath(
   return `/${locale}${clean}`
 }
 
+/**
+ * Fan a `FileRoute[]` into per-locale duplicates so the file-system router
+ * knows about every localized URL pattern at build time. PR H — was the
+ * missing half of the i18n story before this PR (the `i18nRouting()` Vite
+ * plugin only handled request-time locale detection; routes themselves
+ * were never duplicated, so static-host SSG outputs and SSR matching had
+ * no `/de/about` / `/cs/about` records to render against).
+ *
+ * Strategy semantics:
+ *
+ * - **`prefix-except-default`** (default): the default locale's routes
+ *   keep their original `urlPath` unchanged (`/about` stays `/about`); all
+ *   non-default locales get a prefix (`/de/about`, `/cs/about`). Best for
+ *   SEO-on-default-locale apps — search engines see canonical URLs at
+ *   `/about` while non-default speakers get explicit prefixes.
+ *
+ * - **`prefix`**: every locale gets its own prefix, including the default
+ *   (`/en/about`, `/de/about`, `/cs/about`). Root `/` becomes `/en` /
+ *   `/de` / `/cs`. Better when no locale is "primary" — every URL
+ *   self-identifies its locale.
+ *
+ * Layouts, error boundaries, loading components, and 404 pages duplicate
+ * along with their pages — same source file (same `filePath`), new
+ * locale-prefixed `urlPath` / `dirPath` / `depth`. The route tree built
+ * from the expanded array therefore has one fully-formed subtree per
+ * locale, so layout matching, dynamic params (`[id]` → `:id`), and
+ * catch-all routes (`[...slug]` → `:slug*`) all compose naturally with
+ * the locale prefix — no special cases.
+ *
+ * `getStaticPaths` composition (for SSG): each duplicate route inherits
+ * the same `exports.getStaticPaths`. The SSG plugin's `expandUrlPattern`
+ * step then expands `/blog/[slug]` × `[en, de]` × `getStaticPaths()
+ * → ['a', 'b']` into `/blog/a`, `/blog/b`, `/de/blog/a`, `/de/blog/b`
+ * (or all six prefixed forms under `'prefix'` strategy). Cardinality
+ * compounds, which is by design — `ssg.concurrency` (PR D) limits
+ * in-flight renders independent of route count.
+ *
+ * No-op when `config.locales` is empty or contains only the default
+ * locale (prefix-except-default strategy with no other locales) — returns
+ * the input array unchanged. Always return a fresh array on duplication
+ * so callers don't accidentally mutate cached input.
+ *
+ * Reference: the helper is called from `vite-plugin.ts`'s virtual route
+ * module load AND `ssg-plugin.ts`'s pre-render path expansion. Tested in
+ * isolation — duplication is a pure transform on FileRoute[] with no
+ * filesystem or network side effects.
+ */
+export function expandRoutesForLocales(
+  routes: FileRoute[],
+  config: I18nRoutingConfig,
+): FileRoute[] {
+  const strategy = config.strategy ?? 'prefix-except-default'
+  const { locales, defaultLocale } = config
+
+  // Cheap no-op guards. Empty `locales` would otherwise produce an empty
+  // route array, killing the app silently.
+  if (locales.length === 0) return routes
+
+  // PR L2 — Validate every locale string before they reach the filesystem.
+  // The locales drive both URL pattern emission (`/${locale}/...`) AND
+  // filesystem writes (`mkdir(dist/${locale})` in ssg-plugin.ts's per-
+  // locale 404 emit). User-supplied input with `/`, `..`, `\`, NUL, or
+  // leading dots could write outside dist OR produce broken URLs.
+  // Validate at the single entry point so every downstream consumer
+  // (vite-plugin's virtual-routes load AND ssg-plugin's path expansion)
+  // benefits from one check.
+  //
+  // Reject:
+  //   - empty string (kills the app silently with no usable URLs)
+  //   - leading/trailing whitespace (URL-malformed)
+  //   - `/` or `\` (path traversal AND structurally invalid as a URL
+  //     segment — `/de/sub/about` would split into nested directories)
+  //   - `..` or `.` whole-string (path traversal)
+  //   - NUL char (system-call boundary breaks)
+  //   - leading `.` (hidden directory; macOS/Linux dotfile pattern that
+  //     would create `dist/.locale/` invisible to most ls outputs)
+  //
+  // Runs AFTER the empty-locales no-op guard so apps temporarily
+  // toggling to `i18n: { locales: [], ... }` (mid-migration shape)
+  // don't trip on an unused defaultLocale.
+  for (const locale of locales) validateLocale(locale)
+  validateLocale(defaultLocale)
+  if (
+    strategy === 'prefix-except-default'
+    && locales.length === 1
+    && locales[0] === defaultLocale
+  ) {
+    return routes
+  }
+
+  const expanded: FileRoute[] = []
+  for (const route of routes) {
+    for (const locale of locales) {
+      // For prefix-except-default, the default locale uses the ORIGINAL
+      // urlPath / dirPath / depth — no prefix applied.
+      if (strategy === 'prefix-except-default' && locale === defaultLocale) {
+        expanded.push(route)
+        continue
+      }
+
+      // PR H follow-up: skip duplication of ROOT-level layouts under
+      // `prefix-except-default`. The unprefixed default-locale root
+      // `_layout.tsx` (urlPath `/`) is the parent of the matched chain
+      // for EVERY path, including locale-prefixed ones — the route
+      // tree's hierarchical matching wraps `/de/about` under `/_layout`
+      // automatically. Producing a duplicate `/de/_layout` would cause
+      // the matcher to nest BOTH layouts (`/_layout` → `/de/_layout` →
+      // page), mounting the layout component twice and rendering two
+      // navbars / two PyreonUI providers.
+      //
+      // Non-root layouts (e.g. `/dashboard/_layout` at urlPath
+      // `/dashboard`) MUST still be duplicated — `/de/dashboard/users`
+      // is NOT a child of the unprefixed `/dashboard/_layout` (the
+      // path patterns don't match), so the de-prefixed dashboard needs
+      // its own `_layout`.
+      //
+      // Under `prefix` strategy this skip does NOT apply: there is no
+      // unprefixed default to inherit from, so every locale needs its
+      // own root layout (`/en/_layout`, `/de/_layout`, …).
+      if (
+        strategy === 'prefix-except-default'
+        && route.isLayout
+        && route.urlPath === '/'
+      ) {
+        continue
+      }
+
+      const newUrlPath = prefixUrlPath(route.urlPath, locale)
+      // dirPath needs the locale segment too so the route-tree builder
+      // groups localized siblings correctly. Original empty `dirPath`
+      // (root-level routes) becomes the bare locale.
+      const newDirPath = route.dirPath === '' ? locale : `${locale}/${route.dirPath}`
+      // Recompute depth from the new urlPath. Layouts at the root (depth
+      // 0) become depth 1 under their locale prefix; nested routes shift
+      // up by 1.
+      const newDepth = newUrlPath === '/' ? 0 : newUrlPath.split('/').filter(Boolean).length
+
+      expanded.push({
+        ...route,
+        urlPath: newUrlPath,
+        dirPath: newDirPath,
+        depth: newDepth,
+      })
+    }
+  }
+  return expanded
+}
+
+/**
+ * Prepend `/locale` to a URL pattern. Handles three shapes:
+ *   `/`         → `/de`
+ *   `/about`    → `/de/about`
+ *   `/users/:id` / `/blog/:slug*` → `/de/users/:id` / `/de/blog/:slug*`
+ *
+ * Internal helper to `expandRoutesForLocales`; not exported because the
+ * public surface for path-building is `buildLocalePath` (which strips
+ * existing locale prefixes — different semantics).
+ */
+function prefixUrlPath(urlPath: string, locale: string): string {
+  if (urlPath === '/') return `/${locale}`
+  return `/${locale}${urlPath}`
+}
+
+/**
+ * Validate a locale string (PR L2).
+ *
+ * The locale drives both URL pattern emission AND filesystem writes
+ * (see `expandRoutesForLocales` for full rationale). Reject input that
+ * would either:
+ *   - break path-traversal boundaries (`..`, `/`, `\`)
+ *   - produce invalid URL segments (whitespace, NUL)
+ *   - create hidden-file artifacts (`.` leading)
+ *   - silently kill the app (empty string)
+ *
+ * Throws with an actionable `[Pyreon]` error message. Called per-locale
+ * by `expandRoutesForLocales` after the empty-locales no-op guard.
+ *
+ * @internal — exported for unit testing.
+ */
+export function validateLocale(locale: string): void {
+  if (typeof locale !== 'string' || locale === '') {
+    throw new Error(
+      `[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. Locales must be non-empty strings (e.g. "en", "de", "en-US").`,
+    )
+  }
+  if (locale.trim() !== locale) {
+    throw new Error(
+      `[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. Leading or trailing whitespace not allowed.`,
+    )
+  }
+  if (locale.includes('/') || locale.includes('\\')) {
+    throw new Error(
+      `[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. Path separators ("/", "\\\\") not allowed — they would break URL emission and could write outside the dist directory.`,
+    )
+  }
+  if (locale === '..' || locale === '.') {
+    throw new Error(
+      `[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. Path-traversal segments not allowed.`,
+    )
+  }
+  if (locale.startsWith('.')) {
+    throw new Error(
+      `[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. Leading dot not allowed — it would create a hidden-file directory (\`dist/.${locale.slice(1)}/\`) invisible to most file listings.`,
+    )
+  }
+  if (locale.includes('\0')) {
+    throw new Error(
+      `[Pyreon] Invalid i18n locale: ${JSON.stringify(locale)}. NUL characters not allowed.`,
+    )
+  }
+}
+
 /**
  * Create a LocaleContext for use in components and loaders.
  */
@@ -176,10 +408,12 @@ export function i18nRouting(config: I18nRoutingConfig): Plugin {
   return {
     name: 'pyreon-zero-i18n-routing',
 
-    // Route duplication is NOT handled here. The fs-router's `scanRouteFiles`
-    // consumes the i18n config to duplicate routes per locale at build time.
-    // This plugin only provides: (1) the server middleware for locale detection
-    // and (2) the runtime hooks (useLocale, setLocale) for client-side use.
+    // Route duplication is NOT handled here. It happens in
+    // `vite-plugin.ts` and `ssg-plugin.ts` via `expandRoutesForLocales`,
+    // gated by the `i18n` field on `ZeroConfig`. This plugin only
+    // provides: (1) the dev server middleware for locale detection
+    // (Accept-Language, cookies, root redirect) and (2) the runtime
+    // hooks (useLocale, setLocale) for client-side use.
     configResolved() {},
 
     configureServer(server) {

package/src/image.tsx

@@ -1,4 +1,4 @@
-import type { VNodeChild } from '@pyreon/core'
+import type { Ref, VNodeChild } from '@pyreon/core'
 import { createRef } from '@pyreon/core'
 import { signal } from '@pyreon/reactivity'
 import type { FormatSource } from './image-plugin'
@@ -13,6 +13,12 @@ import { useIntersectionObserver } from './utils/use-intersection-observer'
 // - Multi-format support via <picture> (WebP/AVIF with fallback)
 // - Blur-up placeholder while loading
 // - Priority loading for above-the-fold images
+//
+// Three levels of API (mirrors @pyreon/zero/link):
+//
+// 1. useImage(props)   — composable returning resolved attributes + signals
+// 2. createImage(Comp) — HOC wrapping any component with image optimization
+// 3. Image             — default <div><img/></div> wrapper (built on createImage)
 
 export interface ImageProps {
   /** Image source URL. */
@@ -47,6 +53,9 @@ export interface ImageProps {
    * Raw mode — renders a plain `<img>` without the container div,
    * aspect-ratio, max-width, or lazy loading wrapper.
    * Use when the Image is inside a custom layout (absolute positioning, etc.).
+   *
+   * Note: `raw` skips the three-layer API entirely. `useImage` / `createImage`
+   * do not apply when `raw: true` — the component returns a bare `<img>`.
    */
   raw?: boolean
 }
@@ -56,37 +65,83 @@ export interface ImageSource {
   width: number
 }
 
+/** Return type of {@link useImage}. */
+export interface UseImageReturn {
+  /** Ref — attach to the container element for IntersectionObserver. */
+  containerRef: Ref<HTMLElement>
+  /** Whether the image has entered the viewport (and started loading). */
+  inView: () => boolean
+  /** Whether the `<img>` onLoad has fired. */
+  loaded: () => boolean
+  /** Resolved `src` accessor — empty string until inView, then `props.src`. */
+  src: () => string
+  /** Resolved srcSet accessor — empty until inView; empty when `formats` is set (srcset moves to `<source>` elements). */
+  srcSet: () => string
+  /** `sizes` attribute or undefined when no srcset. */
+  sizes: string | undefined
+  /** `aspect-ratio` CSS value (`"${width} / ${height}"`). */
+  aspectRatio: string
+  /** Resolved CSS for the container — position + overflow + aspect-ratio + max-width + caller's `style`. */
+  containerStyle: string
+  /** Resolved CSS accessor for the `<img>` — fit + transition + opacity (placeholder fade). */
+  imageStyle: () => string
+  /** Resolved CSS accessor for the placeholder `<img>` (only meaningful when `placeholder` is set). */
+  placeholderStyle: () => string
+  /** `loading` attribute — eager when priority/eager, else lazy. */
+  loading: 'lazy' | 'eager'
+  /** `fetchPriority` — 'high' when priority, else undefined. */
+  fetchPriority: 'high' | undefined
+  /** onLoad handler — sets the loaded signal. Wire into the rendered `<img>`. */
+  handleLoad: () => void
+  /** Resolved per-format <source> descriptors (or undefined when no formats). */
+  formats: FormatSource[] | undefined
+  /** Whether `formats` is non-empty (i.e. consumer should render a `<picture>` wrapper). */
+  hasFormats: boolean
+}
+
+/** Props passed to a custom component via {@link createImage}. */
+export interface ImageRenderProps {
+  /** Container ref. */
+  containerRef: Ref<HTMLElement>
+  /** CSS class for the container. */
+  class: string | undefined
+  /** Resolved container `style` string. */
+  containerStyle: string
+  /** Pre-rendered placeholder `<img>` (or `null` when `placeholder` is unset). */
+  placeholder: VNodeChild
+  /** Pre-rendered image — either a bare `<img>` or a `<picture>` tree when `formats` is set. */
+  image: VNodeChild
+}
+
 /**
- * Optimized image component with lazy loading, responsive images,
- * multi-format <picture> support, and blur-up placeholders.
+ * Composable that provides all image optimization behavior — lazy loading,
+ * srcset/sizes resolution, format selection, blur-placeholder state,
+ * load tracking.
  *
- * @example
- * // With imagePlugin — spread the import directly
- * import hero from "./hero.jpg?optimize"
- * <Image {...hero} alt="Hero" priority />
+ * Use this for full control when `createImage` is too opinionated about
+ * the surrounding markup (e.g. custom container layouts, non-`<div>`
+ * wrappers, additional overlay elements).
  *
  * @example
- * // Manual usage
- * <Image src="/hero.jpg" alt="Hero" width={1200} height={630} />
+ * function MyImage(props: ImageProps) {
+ *   const img = useImage(props)
+ *   return (
+ *     <figure ref={img.containerRef} style={img.containerStyle}>
+ *       <img
+ *         src={img.src}
+ *         srcSet={img.srcSet}
+ *         sizes={img.sizes}
+ *         alt={props.alt}
+ *         loading={img.loading}
+ *         onLoad={img.handleLoad}
+ *         style={img.imageStyle}
+ *       />
+ *       <figcaption>{props.alt}</figcaption>
+ *     </figure>
+ *   )
+ * }
  */
-export function Image(props: ImageProps): VNodeChild {
-  // Raw mode: plain <img> without container, lazy loading, or layout constraints
-  if (props.raw) {
-    return (
-      <img
-        src={props.src}
-        alt={props.alt}
-        width={props.width}
-        height={props.height}
-        class={props.class}
-        style={props.style}
-        decoding={props.decoding ?? 'async'}
-        loading={props.loading ?? 'lazy'}
-        fetchPriority={props.priority ? 'high' : undefined}
-      />
-    ) as any
-  }
-
+export function useImage(props: ImageProps): UseImageReturn {
   const isEager = props.priority || props.loading === 'eager'
   const loaded = signal(isEager)
   const inView = signal(isEager)
@@ -100,7 +155,7 @@ export function Image(props: ImageProps): VNodeChild {
 
   const sizes = props.sizes ?? '100vw'
   const fit = props.fit ?? 'cover'
-  const hasFormats = props.formats && props.formats.length > 0
+  const hasFormats = !!(props.formats && props.formats.length > 0)
   const aspectRatio = `${props.width} / ${props.height}`
 
   if (!isEager) {
@@ -110,7 +165,6 @@ export function Image(props: ImageProps): VNodeChild {
     )
   }
 
-  // Static styles (don't depend on signals)
   const containerStyle = [
     'position: relative',
     'overflow: hidden',
@@ -122,68 +176,165 @@ export function Image(props: ImageProps): VNodeChild {
     .filter(Boolean)
     .join('; ')
 
-  const imgEl = (
-    <img
-      src={() => (inView() ? props.src : '')}
-      srcSet={() => (!hasFormats && inView() && resolvedSrcset ? resolvedSrcset : '')}
-      sizes={resolvedSrcset ? sizes : undefined}
-      alt={props.alt}
-      width={props.width}
-      height={props.height}
-      loading={isEager ? 'eager' : 'lazy'}
-      decoding={props.decoding ?? 'async'}
-      fetchPriority={props.priority ? 'high' : undefined}
-      onLoad={() => loaded.set(true)}
-      style={() =>
-        [
-          'display: block',
-          'width: 100%',
-          'height: 100%',
-          `object-fit: ${fit}`,
-          'transition: opacity 0.3s ease',
-          props.placeholder && !loaded() ? 'opacity: 0' : 'opacity: 1',
-        ].join('; ')
-      }
-    />
-  )
-
-  return (
-    <div ref={containerRef} class={props.class} style={containerStyle}>
-      {props.placeholder && (
+  const imageStyle = () =>
+    [
+      'display: block',
+      'width: 100%',
+      'height: 100%',
+      `object-fit: ${fit}`,
+      'transition: opacity 0.3s ease',
+      props.placeholder && !loaded() ? 'opacity: 0' : 'opacity: 1',
+    ].join('; ')
+
+  const placeholderStyle = () =>
+    [
+      'position: absolute',
+      'inset: 0',
+      'width: 100%',
+      'height: 100%',
+      'object-fit: cover',
+      'filter: blur(20px)',
+      'transform: scale(1.1)',
+      'transition: opacity 0.4s ease',
+      loaded() ? 'opacity: 0; pointer-events: none' : 'opacity: 1',
+    ].join('; ')
+
+  return {
+    containerRef,
+    inView,
+    loaded,
+    src: () => (inView() ? props.src : ''),
+    srcSet: () => (!hasFormats && inView() && resolvedSrcset ? resolvedSrcset : ''),
+    sizes: resolvedSrcset ? sizes : undefined,
+    aspectRatio,
+    containerStyle,
+    imageStyle,
+    placeholderStyle,
+    loading: isEager ? 'eager' : 'lazy',
+    fetchPriority: props.priority ? 'high' : undefined,
+    handleLoad: () => loaded.set(true),
+    formats: props.formats,
+    hasFormats,
+  }
+}
+
+/**
+ * Higher-order component that wraps any component with image optimization.
+ *
+ * The wrapped component receives {@link ImageRenderProps} with the pre-rendered
+ * `image` JSX (bare `<img>` OR `<picture>` tree depending on formats), the
+ * pre-rendered `placeholder` JSX, and the container ref + styles. Consumers
+ * compose those pieces with whatever wrapper element / layout they want.
+ *
+ * @example
+ * // Custom figure-based image with caption
+ * const FigureImage = createImage((props) => (
+ *   <figure ref={props.containerRef} class={props.class} style={props.containerStyle}>
+ *     {props.placeholder}
+ *     {props.image}
+ *     <figcaption>Caption goes here</figcaption>
+ *   </figure>
+ * ))
+ *
+ * // Usage — identical to default <Image>
+ * <FigureImage src="/hero.jpg" alt="Hero" width={1200} height={630} />
+ */
+export function createImage(
+  Component: (p: ImageRenderProps) => any,
+): (props: ImageProps) => any {
+  return function WrappedImage(props: ImageProps) {
+    // `raw` mode short-circuits — returns a bare <img> with no optimization
+    // wrapper, no container, no createImage composition. Documented as the
+    // no-optimization escape hatch.
+    if (props.raw) {
+      return (
         <img
-          src={props.placeholder}
-          alt=""
-          aria-hidden="true"
-          loading="eager"
-          style={() =>
-            [
-              'position: absolute',
-              'inset: 0',
-              'width: 100%',
-              'height: 100%',
-              'object-fit: cover',
-              'filter: blur(20px)',
-              'transform: scale(1.1)',
-              'transition: opacity 0.4s ease',
-              loaded() ? 'opacity: 0; pointer-events: none' : 'opacity: 1',
-            ].join('; ')
-          }
+          src={props.src}
+          alt={props.alt}
+          width={props.width}
+          height={props.height}
+          class={props.class}
+          style={props.style}
+          decoding={props.decoding ?? 'async'}
+          loading={props.loading ?? 'lazy'}
+          fetchPriority={props.priority ? 'high' : undefined}
         />
-      )}
-      {hasFormats ? (
-        <picture>
-          {props.formats?.map((fmt) => (
-            <source
-              type={fmt.type}
-              srcSet={() => (inView() ? (fmt.srcset ?? '') : '')}
-              sizes={sizes}
-            />
-          ))}
-          {imgEl}
-        </picture>
-      ) : (
-        imgEl
-      )}
-    </div>
-  )
+      )
+    }
+
+    const img = useImage(props)
+
+    const imgEl = (
+      <img
+        src={img.src}
+        srcSet={img.srcSet}
+        sizes={img.sizes}
+        alt={props.alt}
+        width={props.width}
+        height={props.height}
+        loading={img.loading}
+        decoding={props.decoding ?? 'async'}
+        fetchPriority={img.fetchPriority}
+        onLoad={img.handleLoad}
+        style={img.imageStyle}
+      />
+    )
+
+    const placeholderEl = props.placeholder
+      ? (
+          <img
+            src={props.placeholder}
+            alt=""
+            aria-hidden="true"
+            loading="eager"
+            style={img.placeholderStyle}
+          />
+        )
+      : null
+
+    const imageEl = img.hasFormats
+      ? (
+          <picture>
+            {img.formats?.map((fmt) => (
+              <source
+                type={fmt.type}
+                srcSet={() => (img.inView() ? (fmt.srcset ?? '') : '')}
+                sizes={img.sizes}
+              />
+            ))}
+            {imgEl}
+          </picture>
+        )
+      : imgEl
+
+    return (
+      <Component
+        containerRef={img.containerRef}
+        class={props.class}
+        containerStyle={img.containerStyle}
+        placeholder={placeholderEl}
+        image={imageEl}
+      />
+    )
+  }
 }
+
+/**
+ * Default optimized image component with lazy loading, responsive srcset,
+ * `<picture>` multi-format support, and blur-up placeholders.
+ *
+ * @example
+ * // With imagePlugin — spread the import directly
+ * import hero from "./hero.jpg?optimize"
+ * <Image {...hero} alt="Hero" priority />
+ *
+ * @example
+ * // Manual usage
+ * <Image src="/hero.jpg" alt="Hero" width={1200} height={630} />
+ */
+export const Image: (props: ImageProps) => any = createImage((props) => (
+  <div ref={props.containerRef} class={props.class} style={props.containerStyle}>
+    {props.placeholder}
+    {props.image}
+  </div>
+))