@pyreon/zero 0.11.7 → 0.11.9

package/lib/link.js

@@ -93,6 +93,17 @@ function doPrefetch(href) {
 	} catch {}
 }
 /**
+* 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')
+*/
+function prefetchRoute(href) {
+	doPrefetch(href);
+}
+/**
 * Composable that provides all link behavior — navigation, prefetching,
 * active state, and viewport observation.
 *
@@ -232,5 +243,5 @@ const Link = createLink((props) => /* @__PURE__ */ jsx("a", {
 }));
 
 //#endregion
-export { Link, createLink, useLink };
+export { Link, createLink, prefetchRoute, useLink };
 //# sourceMappingURL=link.js.map

package/lib/link.js.map

@@ -1 +1 @@
-{"version":3,"file":"link.js","names":[],"sources":["../src/utils/use-intersection-observer.ts","../../../core/core/lib/jsx-runtime.js","../src/link.tsx"],"sourcesContent":["import { onMount, onUnmount } from '@pyreon/core'\n\n/**\n * Observes an element and calls `onIntersect` once it enters the viewport.\n * Automatically disconnects after the first intersection.\n *\n * @param getElement - Getter for the target element (may be undefined before mount).\n * @param onIntersect - Callback fired when the element becomes visible.\n * @param rootMargin - IntersectionObserver rootMargin. Default: \"200px\".\n */\nexport function useIntersectionObserver(\n  getElement: () => HTMLElement | undefined,\n  onIntersect: () => void,\n  rootMargin = '200px',\n) {\n  onMount(() => {\n    const el = getElement()\n    if (!el) return undefined\n\n    const observer = new IntersectionObserver(\n      (entries) => {\n        for (const entry of entries) {\n          if (entry.isIntersecting) {\n            onIntersect()\n            observer.disconnect()\n          }\n        }\n      },\n      { rootMargin },\n    )\n\n    observer.observe(el)\n    onUnmount(() => observer.disconnect())\n    return undefined\n  })\n}\n","//#region src/h.ts\n/** Marker for fragment nodes — renders children without a wrapper element */\nconst Fragment = Symbol(\"Pyreon.Fragment\");\n/**\n* Hyperscript function — the compiled output of JSX.\n* `<div class=\"x\">hello</div>` → `h(\"div\", { class: \"x\" }, \"hello\")`\n*\n* Generic on P so TypeScript validates props match the component's signature\n* at the call site, then stores the result in the loosely-typed VNode.\n*/\n/** Shared empty props sentinel — identity-checked in mountElement to skip applyProps. */\nconst EMPTY_PROPS = {};\nfunction h(type, props, ...children) {\n\treturn {\n\t\ttype,\n\t\tprops: props ?? EMPTY_PROPS,\n\t\tchildren: normalizeChildren(children),\n\t\tkey: props?.key ?? null\n\t};\n}\nfunction normalizeChildren(children) {\n\tfor (let i = 0; i < children.length; i++) if (Array.isArray(children[i])) return flattenChildren(children);\n\treturn children;\n}\nfunction flattenChildren(children) {\n\tconst result = [];\n\tfor (const child of children) if (Array.isArray(child)) result.push(...flattenChildren(child));\n\telse result.push(child);\n\treturn result;\n}\n\n//#endregion\n//#region src/jsx-runtime.ts\n/**\n* JSX automatic runtime.\n*\n* When tsconfig has `\"jsxImportSource\": \"@pyreon/core\"`, the TS/bundler compiler\n* rewrites JSX to imports from this file automatically:\n*   <div class=\"x\" />  →  jsx(\"div\", { class: \"x\" })\n*/\nfunction jsx(type, props, key) {\n\tconst { children, ...rest } = props;\n\tconst propsWithKey = key != null ? {\n\t\t...rest,\n\t\tkey\n\t} : rest;\n\tif (typeof type === \"function\") return h(type, children !== void 0 ? {\n\t\t...propsWithKey,\n\t\tchildren\n\t} : propsWithKey);\n\treturn h(type, propsWithKey, ...children === void 0 ? [] : Array.isArray(children) ? children : [children]);\n}\nconst jsxs = jsx;\n\n//#endregion\nexport { Fragment, jsx, jsxs };\n//# sourceMappingURL=jsx-runtime.js.map","import { createRef } from '@pyreon/core'\nimport { useRouter } from '@pyreon/router'\nimport { useIntersectionObserver } from './utils/use-intersection-observer'\n\n// ─── Link component with prefetching ────────────────────────────────────────\n//\n// Provides client-side navigation, prefetching, and active state tracking.\n// Three levels of API:\n//\n// 1. useLink(props)   — composable returning handlers, state, and ref callback\n// 2. createLink(Comp) — HOC wrapping any component with link behavior\n// 3. Link             — default <a>-based link (built on createLink)\n\nexport interface LinkProps {\n  /** Target URL path. */\n  href: string\n  /** Link content. */\n  children?: any\n  /** CSS class name. */\n  class?: string\n  /** Class applied when this link matches the current route. */\n  activeClass?: string\n  /** Class applied when this link exactly matches the current route. */\n  exactActiveClass?: string\n  /** Prefetch strategy. Default: \"hover\" */\n  prefetch?: 'hover' | 'viewport' | 'none'\n  /** Open in new tab. */\n  external?: boolean\n  /** Inline styles. */\n  style?: string\n  /** ARIA label. */\n  'aria-label'?: string\n}\n\n/** Props passed to a custom component via createLink. */\nexport interface LinkRenderProps {\n  href: string\n  ref: import('@pyreon/core').Ref<HTMLAnchorElement>\n  onClick: (e: MouseEvent) => void\n  onMouseEnter: () => void\n  onTouchStart: () => void\n  isActive: () => boolean\n  isExactActive: () => boolean\n  /** Reactive class string — pass directly to element for auto-updates on route change. */\n  class: (() => string) | string | undefined\n  style?: string\n  target?: string\n  rel?: string\n  'aria-label'?: string\n  children?: any\n}\n\n/** Return type of useLink. */\nexport interface UseLinkReturn {\n  /** Ref object — attach to the root element for viewport-based prefetch. */\n  ref: import('@pyreon/core').Ref<HTMLAnchorElement>\n  /** Click handler — performs client-side navigation. */\n  handleClick: (e: MouseEvent) => void\n  /** Mouse enter handler — triggers hover prefetch. */\n  handleMouseEnter: () => void\n  /** Touch start handler — triggers prefetch on mobile. */\n  handleTouchStart: () => void\n  /** Whether the link partially matches the current route. */\n  isActive: () => boolean\n  /** Whether the link exactly matches the current route. */\n  isExactActive: () => boolean\n  /** Resolved class string including active classes. */\n  classes: () => string\n}\n\nconst prefetched = new Set<string>()\n\nfunction doPrefetch(href: string) {\n  if (prefetched.has(href)) return\n  prefetched.add(href)\n\n  const docLink = document.createElement('link')\n  docLink.rel = 'prefetch'\n  docLink.href = href\n  docLink.as = 'document'\n  document.head.appendChild(docLink)\n\n  try {\n    const chunkHint = document.createElement('link')\n    chunkHint.rel = 'modulepreload'\n    chunkHint.href = href\n    document.head.appendChild(chunkHint)\n  } catch {\n    // modulepreload is a hint, not critical\n  }\n}\n\n/**\n * Composable that provides all link behavior — navigation, prefetching,\n * active state, and viewport observation.\n *\n * Use this for full control when `createLink` is too opinionated.\n *\n * @example\n * function MyLink(props: LinkProps) {\n *   const link = useLink(props)\n *   return (\n *     <button ref={link.ref} class={link.classes()} onClick={link.handleClick}>\n *       {props.children}\n *     </button>\n *   )\n * }\n */\nexport function useLink(props: LinkProps): UseLinkReturn {\n  const router = useRouter()\n  const elementRef = createRef<HTMLAnchorElement>()\n  const strategy = props.prefetch ?? 'hover'\n\n  function handleClick(e: MouseEvent) {\n    if (\n      e.defaultPrevented ||\n      e.button !== 0 ||\n      e.metaKey ||\n      e.ctrlKey ||\n      e.shiftKey ||\n      e.altKey ||\n      props.external\n    ) {\n      return\n    }\n    e.preventDefault()\n    router.push(props.href)\n  }\n\n  function handleMouseEnter() {\n    if (strategy === 'hover') {\n      doPrefetch(props.href)\n    }\n  }\n\n  function handleTouchStart() {\n    if (strategy === 'hover' || strategy === 'viewport') {\n      doPrefetch(props.href)\n    }\n  }\n\n  if (strategy === 'viewport') {\n    useIntersectionObserver(\n      () => elementRef.current ?? undefined,\n      () => doPrefetch(props.href),\n    )\n  }\n\n  const isActive = () => {\n    const currentPath = router.currentRoute()?.path\n    if (!currentPath || !props.href) return false\n    if (props.href === '/') return currentPath === '/'\n    return currentPath.startsWith(props.href)\n  }\n\n  const isExactActive = () => {\n    const currentPath = router.currentRoute()?.path\n    if (!currentPath) return false\n    return currentPath === props.href\n  }\n\n  const classes = () => {\n    const cls: string[] = []\n    if (props.class) cls.push(props.class)\n    if (props.activeClass && isActive()) cls.push(props.activeClass)\n    if (props.exactActiveClass && isExactActive()) cls.push(props.exactActiveClass)\n    return cls.join(' ')\n  }\n\n  return {\n    ref: elementRef,\n    handleClick,\n    handleMouseEnter,\n    handleTouchStart,\n    isActive,\n    isExactActive,\n    classes,\n  }\n}\n\n/**\n * Higher-order component that wraps any component with link behavior.\n *\n * The wrapped component receives {@link LinkRenderProps} with all handlers,\n * active state, and accessibility attributes pre-wired.\n *\n * @example\n * // Custom button link\n * const ButtonLink = createLink((props) => (\n *   <button\n *     ref={props.ref}\n *     class={props.class}\n *     onClick={props.onClick}\n *     onMouseEnter={props.onMouseEnter}\n *   >\n *     {props.children}\n *   </button>\n * ))\n *\n * // Custom styled component\n * const CardLink = createLink((props) => (\n *   <div\n *     ref={props.ref}\n *     class={`card ${props.isActive() ? \"card--active\" : \"\"}`}\n *     onClick={props.onClick}\n *     onMouseEnter={props.onMouseEnter}\n *   >\n *     {props.children}\n *   </div>\n * ))\n *\n * // Usage\n * <ButtonLink href=\"/about\">About</ButtonLink>\n * <CardLink href=\"/posts\" prefetch=\"viewport\">Posts</CardLink>\n */\nexport function createLink(Component: (props: LinkRenderProps) => any): (props: LinkProps) => any {\n  return function WrappedLink(props: LinkProps) {\n    const link = useLink(props)\n\n    return (\n      <Component\n        href={props.href}\n        ref={link.ref}\n        onClick={link.handleClick}\n        onMouseEnter={link.handleMouseEnter}\n        onTouchStart={link.handleTouchStart}\n        isActive={link.isActive}\n        isExactActive={link.isExactActive}\n        class={link.classes}\n        {...(props.style ? { style: props.style } : {})}\n        {...(props.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}\n        {...(props['aria-label'] ? { 'aria-label': props['aria-label'] } : {})}\n        children={props.children}\n      />\n    )\n  }\n}\n\n/**\n * Default navigation link built on an `<a>` tag.\n *\n * @example\n * <Link href=\"/about\" prefetch=\"viewport\">About</Link>\n * <Link href=\"/posts\" activeClass=\"nav-active\">Posts</Link>\n */\nexport const Link = createLink((props: LinkRenderProps) => (\n  <a\n    ref={props.ref}\n    href={props.href}\n    {...(props.class ? { class: props.class } : {})}\n    {...(props.style ? { style: props.style } : {})}\n    {...(props.target ? { target: props.target } : {})}\n    {...(props.rel ? { rel: props.rel } : {})}\n    {...(props['aria-label'] ? { 'aria-label': props['aria-label'] } : {})}\n    {...(props.isExactActive() ? { 'aria-current': 'page' as const } : {})}\n    onClick={props.onClick}\n    onMouseEnter={props.onMouseEnter}\n    onTouchStart={props.onTouchStart}\n  >\n    {props.children}\n  </a>\n))\n"],"mappings":"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"}
+{"version":3,"file":"link.js","names":[],"sources":["../src/utils/use-intersection-observer.ts","../../../core/core/lib/jsx-runtime.js","../src/link.tsx"],"sourcesContent":["import { onMount, onUnmount } from '@pyreon/core'\n\n/**\n * Observes an element and calls `onIntersect` once it enters the viewport.\n * Automatically disconnects after the first intersection.\n *\n * @param getElement - Getter for the target element (may be undefined before mount).\n * @param onIntersect - Callback fired when the element becomes visible.\n * @param rootMargin - IntersectionObserver rootMargin. Default: \"200px\".\n */\nexport function useIntersectionObserver(\n  getElement: () => HTMLElement | undefined,\n  onIntersect: () => void,\n  rootMargin = '200px',\n) {\n  onMount(() => {\n    const el = getElement()\n    if (!el) return undefined\n\n    const observer = new IntersectionObserver(\n      (entries) => {\n        for (const entry of entries) {\n          if (entry.isIntersecting) {\n            onIntersect()\n            observer.disconnect()\n          }\n        }\n      },\n      { rootMargin },\n    )\n\n    observer.observe(el)\n    onUnmount(() => observer.disconnect())\n    return undefined\n  })\n}\n","//#region src/h.ts\n/** Marker for fragment nodes — renders children without a wrapper element */\nconst Fragment = Symbol(\"Pyreon.Fragment\");\n/**\n* Hyperscript function — the compiled output of JSX.\n* `<div class=\"x\">hello</div>` → `h(\"div\", { class: \"x\" }, \"hello\")`\n*\n* Generic on P so TypeScript validates props match the component's signature\n* at the call site, then stores the result in the loosely-typed VNode.\n*/\n/** Shared empty props sentinel — identity-checked in mountElement to skip applyProps. */\nconst EMPTY_PROPS = {};\nfunction h(type, props, ...children) {\n\treturn {\n\t\ttype,\n\t\tprops: props ?? EMPTY_PROPS,\n\t\tchildren: normalizeChildren(children),\n\t\tkey: props?.key ?? null\n\t};\n}\nfunction normalizeChildren(children) {\n\tfor (let i = 0; i < children.length; i++) if (Array.isArray(children[i])) return flattenChildren(children);\n\treturn children;\n}\nfunction flattenChildren(children) {\n\tconst result = [];\n\tfor (const child of children) if (Array.isArray(child)) result.push(...flattenChildren(child));\n\telse result.push(child);\n\treturn result;\n}\n\n//#endregion\n//#region src/jsx-runtime.ts\n/**\n* JSX automatic runtime.\n*\n* When tsconfig has `\"jsxImportSource\": \"@pyreon/core\"`, the TS/bundler compiler\n* rewrites JSX to imports from this file automatically:\n*   <div class=\"x\" />  →  jsx(\"div\", { class: \"x\" })\n*/\nfunction jsx(type, props, key) {\n\tconst { children, ...rest } = props;\n\tconst propsWithKey = key != null ? {\n\t\t...rest,\n\t\tkey\n\t} : rest;\n\tif (typeof type === \"function\") return h(type, children !== void 0 ? {\n\t\t...propsWithKey,\n\t\tchildren\n\t} : propsWithKey);\n\treturn h(type, propsWithKey, ...children === void 0 ? [] : Array.isArray(children) ? children : [children]);\n}\nconst jsxs = jsx;\n\n//#endregion\nexport { Fragment, jsx, jsxs };\n//# sourceMappingURL=jsx-runtime.js.map","import { createRef } from '@pyreon/core'\nimport { useRouter } from '@pyreon/router'\nimport { useIntersectionObserver } from './utils/use-intersection-observer'\n\n// ─── Link component with prefetching ────────────────────────────────────────\n//\n// Provides client-side navigation, prefetching, and active state tracking.\n// Three levels of API:\n//\n// 1. useLink(props)   — composable returning handlers, state, and ref callback\n// 2. createLink(Comp) — HOC wrapping any component with link behavior\n// 3. Link             — default <a>-based link (built on createLink)\n\nexport interface LinkProps {\n  /** Target URL path. */\n  href: string\n  /** Link content. */\n  children?: any\n  /** CSS class name. */\n  class?: string\n  /** Class applied when this link matches the current route. */\n  activeClass?: string\n  /** Class applied when this link exactly matches the current route. */\n  exactActiveClass?: string\n  /** Prefetch strategy. Default: \"hover\" */\n  prefetch?: 'hover' | 'viewport' | 'none'\n  /** Open in new tab. */\n  external?: boolean\n  /** Inline styles. */\n  style?: string\n  /** ARIA label. */\n  'aria-label'?: string\n}\n\n/** Props passed to a custom component via createLink. */\nexport interface LinkRenderProps {\n  href: string\n  ref: import('@pyreon/core').Ref<HTMLAnchorElement>\n  onClick: (e: MouseEvent) => void\n  onMouseEnter: () => void\n  onTouchStart: () => void\n  isActive: () => boolean\n  isExactActive: () => boolean\n  /** Reactive class string — pass directly to element for auto-updates on route change. */\n  class: (() => string) | string | undefined\n  style?: string\n  target?: string\n  rel?: string\n  'aria-label'?: string\n  children?: any\n}\n\n/** Return type of useLink. */\nexport interface UseLinkReturn {\n  /** Ref object — attach to the root element for viewport-based prefetch. */\n  ref: import('@pyreon/core').Ref<HTMLAnchorElement>\n  /** Click handler — performs client-side navigation. */\n  handleClick: (e: MouseEvent) => void\n  /** Mouse enter handler — triggers hover prefetch. */\n  handleMouseEnter: () => void\n  /** Touch start handler — triggers prefetch on mobile. */\n  handleTouchStart: () => void\n  /** Whether the link partially matches the current route. */\n  isActive: () => boolean\n  /** Whether the link exactly matches the current route. */\n  isExactActive: () => boolean\n  /** Resolved class string including active classes. */\n  classes: () => string\n}\n\nconst prefetched = new Set<string>()\n\nfunction doPrefetch(href: string) {\n  if (prefetched.has(href)) return\n  prefetched.add(href)\n\n  const docLink = document.createElement('link')\n  docLink.rel = 'prefetch'\n  docLink.href = href\n  docLink.as = 'document'\n  document.head.appendChild(docLink)\n\n  try {\n    const chunkHint = document.createElement('link')\n    chunkHint.rel = 'modulepreload'\n    chunkHint.href = href\n    document.head.appendChild(chunkHint)\n  } catch {\n    // modulepreload is a hint, not critical\n  }\n}\n\n/**\n * Prefetch a route's JS chunk by injecting `<link rel=\"prefetch\">` into the\n * document head. Deduplicates — calling with the same href twice is a no-op.\n *\n * @example\n * prefetchRoute('/about')\n * prefetchRoute('/dashboard')\n */\nexport function prefetchRoute(href: string): void {\n  doPrefetch(href)\n}\n\n/**\n * Composable that provides all link behavior — navigation, prefetching,\n * active state, and viewport observation.\n *\n * Use this for full control when `createLink` is too opinionated.\n *\n * @example\n * function MyLink(props: LinkProps) {\n *   const link = useLink(props)\n *   return (\n *     <button ref={link.ref} class={link.classes()} onClick={link.handleClick}>\n *       {props.children}\n *     </button>\n *   )\n * }\n */\nexport function useLink(props: LinkProps): UseLinkReturn {\n  const router = useRouter()\n  const elementRef = createRef<HTMLAnchorElement>()\n  const strategy = props.prefetch ?? 'hover'\n\n  function handleClick(e: MouseEvent) {\n    if (\n      e.defaultPrevented ||\n      e.button !== 0 ||\n      e.metaKey ||\n      e.ctrlKey ||\n      e.shiftKey ||\n      e.altKey ||\n      props.external\n    ) {\n      return\n    }\n    e.preventDefault()\n    router.push(props.href)\n  }\n\n  function handleMouseEnter() {\n    if (strategy === 'hover') {\n      doPrefetch(props.href)\n    }\n  }\n\n  function handleTouchStart() {\n    if (strategy === 'hover' || strategy === 'viewport') {\n      doPrefetch(props.href)\n    }\n  }\n\n  if (strategy === 'viewport') {\n    useIntersectionObserver(\n      () => elementRef.current ?? undefined,\n      () => doPrefetch(props.href),\n    )\n  }\n\n  const isActive = () => {\n    const currentPath = router.currentRoute()?.path\n    if (!currentPath || !props.href) return false\n    if (props.href === '/') return currentPath === '/'\n    return currentPath.startsWith(props.href)\n  }\n\n  const isExactActive = () => {\n    const currentPath = router.currentRoute()?.path\n    if (!currentPath) return false\n    return currentPath === props.href\n  }\n\n  const classes = () => {\n    const cls: string[] = []\n    if (props.class) cls.push(props.class)\n    if (props.activeClass && isActive()) cls.push(props.activeClass)\n    if (props.exactActiveClass && isExactActive()) cls.push(props.exactActiveClass)\n    return cls.join(' ')\n  }\n\n  return {\n    ref: elementRef,\n    handleClick,\n    handleMouseEnter,\n    handleTouchStart,\n    isActive,\n    isExactActive,\n    classes,\n  }\n}\n\n/**\n * Higher-order component that wraps any component with link behavior.\n *\n * The wrapped component receives {@link LinkRenderProps} with all handlers,\n * active state, and accessibility attributes pre-wired.\n *\n * @example\n * // Custom button link\n * const ButtonLink = createLink((props) => (\n *   <button\n *     ref={props.ref}\n *     class={props.class}\n *     onClick={props.onClick}\n *     onMouseEnter={props.onMouseEnter}\n *   >\n *     {props.children}\n *   </button>\n * ))\n *\n * // Custom styled component\n * const CardLink = createLink((props) => (\n *   <div\n *     ref={props.ref}\n *     class={`card ${props.isActive() ? \"card--active\" : \"\"}`}\n *     onClick={props.onClick}\n *     onMouseEnter={props.onMouseEnter}\n *   >\n *     {props.children}\n *   </div>\n * ))\n *\n * // Usage\n * <ButtonLink href=\"/about\">About</ButtonLink>\n * <CardLink href=\"/posts\" prefetch=\"viewport\">Posts</CardLink>\n */\nexport function createLink(Component: (props: LinkRenderProps) => any): (props: LinkProps) => any {\n  return function WrappedLink(props: LinkProps) {\n    const link = useLink(props)\n\n    return (\n      <Component\n        href={props.href}\n        ref={link.ref}\n        onClick={link.handleClick}\n        onMouseEnter={link.handleMouseEnter}\n        onTouchStart={link.handleTouchStart}\n        isActive={link.isActive}\n        isExactActive={link.isExactActive}\n        class={link.classes}\n        {...(props.style ? { style: props.style } : {})}\n        {...(props.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}\n        {...(props['aria-label'] ? { 'aria-label': props['aria-label'] } : {})}\n        children={props.children}\n      />\n    )\n  }\n}\n\n/**\n * Default navigation link built on an `<a>` tag.\n *\n * @example\n * <Link href=\"/about\" prefetch=\"viewport\">About</Link>\n * <Link href=\"/posts\" activeClass=\"nav-active\">Posts</Link>\n */\nexport const Link = createLink((props: LinkRenderProps) => (\n  <a\n    ref={props.ref}\n    href={props.href}\n    {...(props.class ? { class: props.class } : {})}\n    {...(props.style ? { style: props.style } : {})}\n    {...(props.target ? { target: props.target } : {})}\n    {...(props.rel ? { rel: props.rel } : {})}\n    {...(props['aria-label'] ? { 'aria-label': props['aria-label'] } : {})}\n    {...(props.isExactActive() ? { 'aria-current': 'page' as const } : {})}\n    onClick={props.onClick}\n    onMouseEnter={props.onMouseEnter}\n    onTouchStart={props.onTouchStart}\n  >\n    {props.children}\n  </a>\n))\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/zero",
-  "version": "0.11.7",
+  "version": "0.11.9",
   "description": "Pyreon Zero — zero-config full-stack framework powered by Pyreon and Vite",
   "license": "MIT",
   "author": "Vit Bokisch",
@@ -116,17 +116,17 @@
     "lint": "oxlint ."
   },
   "dependencies": {
-    "@pyreon/core": "^0.11.7",
-    "@pyreon/head": "^0.11.7",
-    "@pyreon/meta": "^0.11.7",
-    "@pyreon/router": "^0.11.7",
-    "@pyreon/runtime-dom": "^0.11.7",
-    "@pyreon/runtime-server": "^0.11.7",
-    "@pyreon/server": "^0.11.7",
-    "@pyreon/vite-plugin": "^0.11.7",
+    "@pyreon/core": "^0.11.9",
+    "@pyreon/head": "^0.11.9",
+    "@pyreon/meta": "^0.11.9",
+    "@pyreon/router": "^0.11.9",
+    "@pyreon/runtime-dom": "^0.11.9",
+    "@pyreon/runtime-server": "^0.11.9",
+    "@pyreon/server": "^0.11.9",
+    "@pyreon/vite-plugin": "^0.11.9",
     "vite": "^8.0.0"
   },
   "peerDependencies": {
-    "@pyreon/reactivity": "^0.11.7"
+    "@pyreon/reactivity": "^0.11.9"
   }
 }

package/src/entry-server.ts

@@ -1,61 +1,69 @@
-import type { RouteRecord } from '@pyreon/router'
-import type { Middleware, MiddlewareContext } from '@pyreon/server'
-import { createHandler } from '@pyreon/server'
-import type { ApiRouteEntry } from './api-routes'
-import { createApiMiddleware } from './api-routes'
-import { createApp } from './app'
-import type { RouteMiddlewareEntry, ZeroConfig } from './types'
+import type { ComponentFn } from "@pyreon/core";
+import type { RouteRecord } from "@pyreon/router";
+import type { Middleware, MiddlewareContext } from "@pyreon/server";
+import { createHandler } from "@pyreon/server";
+import type { ApiRouteEntry } from "./api-routes";
+import { createApiMiddleware } from "./api-routes";
+import { createApp } from "./app";
+import { render404Page } from "./not-found";
+import type { RouteMiddlewareEntry, ZeroConfig } from "./types";
 
 // ─── Server entry factory ───────────────────────────────────────────────────
 
 export interface CreateServerOptions {
-  /** Route definitions. */
-  routes: RouteRecord[]
-  /** Zero config. */
-  config?: ZeroConfig
-  /** Additional middleware. */
-  middleware?: Middleware[]
-  /** Per-route middleware from virtual:zero/route-middleware. */
-  routeMiddleware?: RouteMiddlewareEntry[]
-  /** API route entries from virtual:zero/api-routes. */
-  apiRoutes?: ApiRouteEntry[]
-  /** HTML template override. */
-  template?: string
-  /** Client entry path. */
-  clientEntry?: string
+	/** Route definitions. */
+	routes: RouteRecord[];
+	/** Zero config. */
+	config?: ZeroConfig;
+	/** Additional middleware. */
+	middleware?: Middleware[];
+	/** Per-route middleware from virtual:zero/route-middleware. */
+	routeMiddleware?: RouteMiddlewareEntry[];
+	/** API route entries from virtual:zero/api-routes. */
+	apiRoutes?: ApiRouteEntry[];
+	/** HTML template override. */
+	template?: string;
+	/** Client entry path. */
+	clientEntry?: string;
+	/** Component to render when no route matches (from _404.tsx). */
+	notFoundComponent?: ComponentFn;
 }
 
 /**
  * Create a middleware that dispatches per-route middleware based on URL pattern matching.
  */
-function createRouteMiddlewareDispatcher(entries: RouteMiddlewareEntry[]): Middleware {
-  return async (ctx: MiddlewareContext) => {
-    for (const entry of entries) {
-      if (matchPattern(entry.pattern, ctx.path)) {
-        const mw = Array.isArray(entry.middleware) ? entry.middleware : [entry.middleware]
-        for (const fn of mw) {
-          const result = await fn(ctx)
-          if (result) return result
-        }
-      }
-    }
-  }
+function createRouteMiddlewareDispatcher(
+	entries: RouteMiddlewareEntry[],
+): Middleware {
+	return async (ctx: MiddlewareContext) => {
+		for (const entry of entries) {
+			if (matchPattern(entry.pattern, ctx.path)) {
+				const mw = Array.isArray(entry.middleware)
+					? entry.middleware
+					: [entry.middleware];
+				for (const fn of mw) {
+					const result = await fn(ctx);
+					if (result) return result;
+				}
+			}
+		}
+	};
 }
 
 /** Simple URL pattern matcher supporting :param and :param* segments. */
 export function matchPattern(pattern: string, path: string): boolean {
-  const patternParts = pattern.split('/').filter(Boolean)
-  const pathParts = path.split('/').filter(Boolean)
-
-  for (let i = 0; i < patternParts.length; i++) {
-    const pp = patternParts[i]
-    if (!pp) continue
-    if (pp.endsWith('*')) return true // catch-all matches everything after
-    if (pp.startsWith(':')) continue // dynamic segment matches anything
-    if (pp !== pathParts[i]) return false
-  }
-
-  return patternParts.length === pathParts.length
+	const patternParts = pattern.split("/").filter(Boolean);
+	const pathParts = path.split("/").filter(Boolean);
+
+	for (let i = 0; i < patternParts.length; i++) {
+		const pp = patternParts[i];
+		if (!pp) continue;
+		if (pp.endsWith("*")) return true; // catch-all matches everything after
+		if (pp.startsWith(":")) continue; // dynamic segment matches anything
+		if (pp !== pathParts[i]) return false;
+	}
+
+	return patternParts.length === pathParts.length;
 }
 
 /**
@@ -69,35 +77,75 @@ export function matchPattern(pattern: string, path: string): boolean {
  * export default createServer({ routes, routeMiddleware, apiRoutes })
  */
 export function createServer(options: CreateServerOptions) {
-  const config = options.config ?? {}
-
-  const allMiddleware: Middleware[] = []
-
-  // API routes run first — they short-circuit before SSR
-  if (options.apiRoutes?.length) {
-    allMiddleware.push(createApiMiddleware(options.apiRoutes))
-  }
-
-  // Per-route middleware runs next
-  if (options.routeMiddleware?.length) {
-    allMiddleware.push(createRouteMiddlewareDispatcher(options.routeMiddleware))
-  }
-
-  // Then global middleware from config and options
-  allMiddleware.push(...(config.middleware ?? []))
-  allMiddleware.push(...(options.middleware ?? []))
-
-  const { App } = createApp({
-    routes: options.routes,
-    routerMode: 'history',
-  })
-
-  return createHandler({
-    App,
-    routes: options.routes,
-    middleware: allMiddleware,
-    mode: config.ssr?.mode ?? 'string',
-    ...(options.template ? { template: options.template } : {}),
-    ...(options.clientEntry ? { clientEntry: options.clientEntry } : {}),
-  })
+	const config = options.config ?? {};
+
+	const allMiddleware: Middleware[] = [];
+
+	// API routes run first — they short-circuit before SSR
+	if (options.apiRoutes?.length) {
+		allMiddleware.push(createApiMiddleware(options.apiRoutes));
+	}
+
+	// Per-route middleware runs next
+	if (options.routeMiddleware?.length) {
+		allMiddleware.push(
+			createRouteMiddlewareDispatcher(options.routeMiddleware),
+		);
+	}
+
+	// Then global middleware from config and options
+	allMiddleware.push(...(config.middleware ?? []));
+	allMiddleware.push(...(options.middleware ?? []));
+
+	const { App } = createApp({
+		routes: options.routes,
+		routerMode: "history",
+	});
+
+	const handler = createHandler({
+		App,
+		routes: options.routes,
+		middleware: allMiddleware,
+		mode: config.ssr?.mode ?? "string",
+		...(options.template ? { template: options.template } : {}),
+		...(options.clientEntry ? { clientEntry: options.clientEntry } : {}),
+	});
+
+	// Wrap handler with 404 detection when a notFoundComponent is provided
+	if (!options.notFoundComponent) return handler;
+
+	const NotFound = options.notFoundComponent;
+	const routePatterns = flattenRoutePatterns(options.routes);
+
+	return async (req: Request) => {
+		const url = new URL(req.url);
+		const pathname = url.pathname;
+
+		// Check if any defined route matches this path
+		if (!routePatterns.some((pattern) => matchPattern(pattern, pathname))) {
+			const fullHtml = await render404Page(NotFound, options.template);
+			return new Response(fullHtml, {
+				status: 404,
+				headers: { "Content-Type": "text/html; charset=utf-8" },
+			});
+		}
+
+		return handler(req);
+	};
+}
+
+/** Extract all URL patterns from a nested route tree. */
+function flattenRoutePatterns(routes: RouteRecord[], prefix = ""): string[] {
+	const patterns: string[] = [];
+	for (const route of routes) {
+		const fullPath =
+			route.path === "/" && prefix ? prefix : `${prefix}${route.path}`;
+		patterns.push(fullPath);
+		if (route.children) {
+			patterns.push(
+				...flattenRoutePatterns(route.children as RouteRecord[], fullPath),
+			);
+		}
+	}
+	return patterns;
 }