npm - @pyreon/zero - Versions diffs - 0.12.13 → 0.12.15 - Mend

@pyreon/zero 0.12.13 → 0.12.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (51) hide show

package/src/i18n-routing.ts CHANGED Viewed

@@ -13,7 +13,7 @@ import type { Plugin } from 'vite'
 //
 // Usage:
 //   import { i18nRouting } from "@pyreon/zero"
-//   export default { plugins: [zero(), i18nRouting({ locales: ["en", "de"], defaultLocale: "en" })] }
+//   export default { plugins: [Pyreon], defaultLocale: "en" })] }
 export interface I18nRoutingConfig {
   /** Supported locales. e.g. ["en", "de", "cs"] */

package/src/image-plugin.ts CHANGED Viewed

@@ -9,7 +9,7 @@ function warnSharpMissing() {
   sharpWarned = true
   // oxlint-disable-next-line no-console
   console.warn(
-    '\n[zero:image] sharp not installed — images will not be optimized. Install for full support: bun add -D sharp\n',
+    '\n[Pyreon] sharp not installed — images will not be optimized. Install for full support: bun add -D sharp\n',
   )
 }

package/src/isr.ts CHANGED Viewed

@@ -13,6 +13,13 @@ interface CacheEntry {
  *
  * Wraps an SSR handler and caches responses per URL path.
  * Serves stale content immediately while revalidating in the background.
+ *
+ * Bounded by `config.maxEntries` (default: 1000) with LRU eviction. The
+ * `Map` preserves insertion order, so re-inserting an entry on every
+ * serve (touching it) keeps the LRU order correct. Without the cap,
+ * unbounded URL spaces like `/user/:id` would grow cache memory without
+ * limit over the server's lifetime — a real leak in long-running
+ * deployments.
  */
 export function createISRHandler(
   handler: (req: Request) => Promise<Response>,
@@ -21,6 +28,28 @@ export function createISRHandler(
   const cache = new Map<string, CacheEntry>()
   const revalidating = new Set<string>()
   const revalidateMs = config.revalidate * 1000
+  const maxEntries = Math.max(1, config.maxEntries ?? 1000)
+  function set(key: string, entry: CacheEntry): void {
+    // LRU: re-inserting moves the key to the newest position. Then if we're
+    // over the cap, drop the oldest (first in iteration order).
+    if (cache.has(key)) cache.delete(key)
+    cache.set(key, entry)
+    while (cache.size > maxEntries) {
+      const oldest = cache.keys().next().value
+      if (oldest === undefined) break
+      cache.delete(oldest)
+    }
+  }
+  function touch(key: string): CacheEntry | undefined {
+    const entry = cache.get(key)
+    if (entry !== undefined) {
+      cache.delete(key)
+      cache.set(key, entry)
+    }
+    return entry
+  }
   async function revalidate(url: URL) {
     const key = url.pathname
@@ -36,7 +65,7 @@ export function createISRHandler(
         headers[k] = v
       })
-      cache.set(key, { html, headers, timestamp: Date.now() })
+      set(key, { html, headers, timestamp: Date.now() })
     } catch {
       // Revalidation failed — stale cache entry remains valid
     } finally {
@@ -52,7 +81,10 @@ export function createISRHandler(
     const url = new URL(req.url)
     const key = url.pathname
-    const entry = cache.get(key)
+    // `touch` moves the entry to the newest LRU position on read so
+    // hot paths survive eviction even when the cap is small. `get`
+    // wouldn't update ordering.
+    const entry = touch(key)
     if (entry) {
       const age = Date.now() - entry.timestamp

package/src/link.tsx CHANGED Viewed

@@ -71,31 +71,47 @@ export interface UseLinkReturn {
 }
 const MAX_PREFETCH_CACHE = 200
-const prefetched = new Set<string>()
+// Maps href → list of <link> elements injected into <head>. When the
+// cache evicts an href (FIFO at MAX_PREFETCH_CACHE), the matching <link>
+// elements must be removed too — otherwise head bloats unboundedly
+// across long SPA sessions (every Link interaction added 2 <link> nodes
+// with no cleanup).
+const prefetched = new Map<string, Element[]>()
 function doPrefetch(href: string) {
+  // Prefetch only fires from browser-mounted Link interactions (hover /
+  // click intent). Explicit guard documents the SSR-safety contract.
+  if (typeof document === 'undefined') return
   if (prefetched.has(href)) return
-  // Evict oldest entries when cache is full
+  // Evict oldest entries when cache is full — AND remove their DOM nodes.
   if (prefetched.size >= MAX_PREFETCH_CACHE) {
-    const first = prefetched.values().next().value
-    if (first) prefetched.delete(first)
+    const firstEntry = prefetched.entries().next().value
+    if (firstEntry) {
+      const [oldestHref, oldestLinks] = firstEntry
+      for (const link of oldestLinks) link.remove()
+      prefetched.delete(oldestHref)
+    }
   }
-  prefetched.add(href)
+  const injected: Element[] = []
   const docLink = document.createElement('link')
   docLink.rel = 'prefetch'
   docLink.href = href
   docLink.as = 'document'
   document.head.appendChild(docLink)
+  injected.push(docLink)
   try {
     const chunkHint = document.createElement('link')
     chunkHint.rel = 'modulepreload'
     chunkHint.href = href
     document.head.appendChild(chunkHint)
+    injected.push(chunkHint)
   } catch {
     // modulepreload is a hint, not critical
   }
+  prefetched.set(href, injected)
 }
 /**

package/src/og-image.ts CHANGED Viewed

@@ -38,7 +38,7 @@ function warnSharpMissing() {
   sharpWarned = true
   // oxlint-disable-next-line no-console
   console.warn(
-    '\n[zero:og-image] sharp not installed — OG images will not be generated. Install for full support: bun add -D sharp\n',
+    '\n[Pyreon] sharp not installed — OG images will not be generated. Install for full support: bun add -D sharp\n',
   )
 }
@@ -357,7 +357,7 @@ export function ogImagePlugin(config: OgImagePluginConfig): Plugin {
             const bgPath = join(root, template.background)
             if (!existsSync(bgPath)) {
               // oxlint-disable-next-line no-console
-              console.warn(`[zero:og-image] Background not found: ${bgPath}`)
+              console.warn(`[Pyreon] Background not found: ${bgPath}`)
               continue
             }
           }

package/src/script.tsx CHANGED Viewed

@@ -52,6 +52,10 @@ export type ScriptStrategy =
  */
 export function Script(props: ScriptProps): VNodeChild {
   function loadScript() {
+    // Only invoked from `onMount` — explicit guard documents the
+    // SSR-safety contract at the callsite (the rule can't AST-trace the
+    // indirect call).
+    if (typeof document === 'undefined') return
     // Deduplication
     if (props.id && document.getElementById(props.id)) return

package/src/theme.tsx CHANGED Viewed

@@ -1,5 +1,5 @@
 import type { VNodeChild } from '@pyreon/core'
-import { onMount, onUnmount } from '@pyreon/core'
+import { onMount } from '@pyreon/core'
 import { effect, signal } from '@pyreon/reactivity'
 // ─── Theme system ───────────────────────────────────────────────────────────
@@ -17,6 +17,19 @@ const STORAGE_KEY = 'zero-theme'
 /** Reactive theme signal. */
 export const theme = signal<Theme>('system')
+/**
+ * Reactive signal tracking the OS color-scheme preference. Updated by the
+ * `matchMedia('(prefers-color-scheme: dark)').change` event registered in
+ * `initTheme`. Components reading `resolvedTheme()` subscribe to BOTH
+ * `theme` and this signal, so a user toggling dark mode at the OS level
+ * re-renders everything reactively — not just the `<html data-theme>`
+ * attribute.
+ *
+ * SSR default is `_ssrDefault` (mutable via `setSSRThemeDefault`) so the
+ * server-rendered theme can differ from the client's OS preference.
+ */
+const _osPrefersDark = signal<boolean>(false)
 /** SSR fallback when system preference can't be detected. Default: 'light'. */
 let _ssrDefault: 'light' | 'dark' = 'light'
@@ -28,12 +41,17 @@ export function setSSRThemeDefault(value: 'light' | 'dark'): void {
   _ssrDefault = value
 }
-/** Computed resolved theme (what's actually applied). */
+/**
+ * Reactive read of the resolved theme. Subscribes to `theme` (explicit
+ * user choice) and — when `theme === 'system'` — to `_osPrefersDark`
+ * (OS color-scheme preference). Components using `resolvedTheme()`
+ * inside JSX / effects / computeds re-render when either changes.
+ */
 export function resolvedTheme(): 'light' | 'dark' {
   const t = theme()
   if (t === 'system') {
     if (typeof window === 'undefined') return _ssrDefault
-    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+    return _osPrefersDark() ? 'dark' : 'light'
   }
   return t
 }
@@ -76,15 +94,17 @@ export function initTheme() {
     // Apply to document
     document.documentElement.dataset.theme = resolvedTheme()
-    // Watch for system preference changes
+    // Watch for system preference changes. Seed the signal from the
+    // current media-query state, then update reactively on each OS
+    // preference flip. Components reading `resolvedTheme()` pick up the
+    // change automatically (they subscribe to `_osPrefersDark` when
+    // `theme === 'system'`).
     const mq = window.matchMedia('(prefers-color-scheme: dark)')
-    function onChange() {
-      if (theme() === 'system') {
-        document.documentElement.dataset.theme = resolvedTheme()
-      }
+    _osPrefersDark.set(mq.matches)
+    function onChange(e: MediaQueryListEvent) {
+      _osPrefersDark.set(e.matches)
     }
     mq.addEventListener('change', onChange)
-    onUnmount(() => mq.removeEventListener('change', onChange))
     // Re-apply when theme signal changes — updates data-theme + favicons
     const dispose = effect(() => {
@@ -97,9 +117,11 @@ export function initTheme() {
         link.media = link.dataset.faviconTheme === mode ? '' : 'not all'
       }
     })
-    if (dispose) onUnmount(() => dispose.dispose())
-    return undefined
+    return () => {
+      mq.removeEventListener('change', onChange)
+      dispose?.dispose()
+    }
   })
 }

package/src/types.ts CHANGED Viewed

@@ -48,6 +48,13 @@ export type RenderMode = 'ssr' | 'ssg' | 'spa' | 'isr'
 export interface ISRConfig {
   /** Revalidation interval in seconds. */
   revalidate: number
+  /**
+   * Maximum number of distinct URL paths to keep in the in-memory cache.
+   * Oldest-first LRU eviction once the cap is reached. Default: `1000`.
+   * Set higher for SSG-heavy sites, lower for routes with unbounded URL
+   * space (e.g. `/user/:id` where `:id` is free-form).
+   */
+  maxEntries?: number
 }
 // ─── Zero config ─────────────────────────────────────────────────────────────

package/src/vite-plugin.ts CHANGED Viewed

@@ -1,6 +1,7 @@
+import { readFile } from 'node:fs/promises'
 import { existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
-import type { Plugin } from 'vite'
+import type { Plugin, ViteDevServer } from 'vite'
 import { generateApiRouteModule } from './api-routes'
 import { resolveConfig } from './config'
@@ -20,6 +21,21 @@ function scanPyreonPackages(root: string): string[] {
     return []
   }
 }
+/**
+ * Resolve a package that isn't at the app's top-level `node_modules` but is
+ * nested under another `@pyreon/*` package. Used to alias `@pyreon/runtime-server`
+ * to the copy under `node_modules/@pyreon/zero/node_modules/@pyreon/runtime-server`
+ * so `ssrLoadModule` works without requiring the app to declare it as a
+ * direct dep.
+ */
+function resolveNestedPackage(root: string, name: string): string | undefined {
+  const direct = join(root, 'node_modules', name)
+  if (existsSync(direct)) return direct
+  const nested = join(root, 'node_modules', '@pyreon', 'zero', 'node_modules', name)
+  if (existsSync(nested)) return nested
+  return undefined
+}
 import { matchPattern } from "./entry-server";
 import { renderErrorOverlay } from "./error-overlay";
 import {
@@ -111,6 +127,41 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin {
 		},
 		configureServer(server) {
+			// Dev-mode SSR middleware — for mode: "ssr", actually render each
+			// matched route server-side instead of serving the SPA shell.
+			// Runs BEFORE the 404 handler so matched routes are SSR'd and
+			// unmatched ones fall through to the 404 handler.
+			if (config.mode === "ssr") {
+				server.middlewares.use((req, res, next) => {
+					const accept = req.headers.accept ?? "";
+					if (!accept.includes("text/html") && !accept.includes("*/*"))
+						return next();
+					const pathname = req.url?.split("?")[0] ?? "/";
+					if (pathname.startsWith("/@") || pathname.startsWith("/__"))
+						return next();
+					if (/\.\w+$/.test(pathname)) return next();
+					renderSsr(server, root, req.originalUrl ?? pathname, pathname).then(
+						(result) => {
+							if (result === null) return next();
+							res.statusCode = 200;
+							res.setHeader("Content-Type", "text/html; charset=utf-8");
+							res.setHeader("Content-Length", Buffer.byteLength(result));
+							res.end(result);
+						},
+						(err: unknown) => {
+							const error = err instanceof Error ? err : new Error(String(err));
+							server.ssrFixStacktrace(error);
+							const html = renderErrorOverlay(error);
+							res.statusCode = 500;
+							res.setHeader("Content-Type", "text/html; charset=utf-8");
+							res.setHeader("Content-Length", Buffer.byteLength(html));
+							res.end(html);
+						},
+					);
+				});
+			}
 			// 404 handler — check if the requested path matches any route.
 			// If not, render the nearest _404.tsx component with a 404 status.
 			// Uses a sync wrapper that calls the async handler, since Connect
@@ -134,7 +185,7 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin {
 					},
 					(err) => {
 						// oxlint-disable-next-line no-console
-						console.error('[zero] Error in 404 handler:', err);
+						console.error('[Pyreon] Error in 404 handler:', err);
 						next();
 					},
 				);
@@ -210,9 +261,33 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin {
 			const root = userConfig.root ?? process.cwd()
 			const pyreonExclude = scanPyreonPackages(root)
+			// `@pyreon/runtime-server` is only imported by zero's dev SSR
+			// middleware and the production server entry — apps rarely list it
+			// as a direct dep. Resolve it to the copy nested under zero so
+			// `ssrLoadModule("@pyreon/runtime-server")` works uniformly.
+			const runtimeServerAlias = resolveNestedPackage(
+				root,
+				"@pyreon/runtime-server",
+			)
 			return {
 				resolve: {
 					conditions: ['bun'],
+					...(runtimeServerAlias
+						? { alias: { '@pyreon/runtime-server': runtimeServerAlias } }
+						: {}),
+				},
+				// Vite's SSR module graph has its own resolver that defaults to the
+				// "node" condition — which would pick the built `lib/index.js` for
+				// every `@pyreon/*` package and bypass workspace source edits. Mirror
+				// the client-side "bun" condition + alias so dev SSR uses `src/`.
+				ssr: {
+					resolve: {
+						conditions: ['bun'],
+						...(runtimeServerAlias
+							? { alias: { '@pyreon/runtime-server': runtimeServerAlias } }
+							: {}),
+					},
 				},
 				optimizeDeps: {
 					exclude: pyreonExclude,
@@ -267,6 +342,133 @@ async function handle404(
 	return true;
 }
+/**
+ * Dev-mode SSR render pipeline. Returns the composed HTML string, or `null`
+ * if the URL doesn't match any known route (caller falls through to the 404
+ * middleware). Mirrors the production `createServer` flow:
+ *   1. Load virtual:zero/routes + app.ts via Vite's ssrLoadModule
+ *   2. Create a per-request router bound to the request URL
+ *   3. Pre-run loaders for the matched route(s)
+ *   4. Render app tree with head tag collection
+ *   5. Serialize loader data into `window.__PYREON_LOADER_DATA__`
+ *   6. Inject everything into the user's transformed index.html (so Vite
+ *      still gets a chance to inject its HMR client + JSX runtime prelude)
+ */
+async function renderSsr(
+	server: ViteDevServer,
+	root: string,
+	originalUrl: string,
+	pathname: string,
+): Promise<string | null> {
+	// Pattern check FIRST — otherwise SSR would try (and likely crash) on
+	// asset paths that happened to accept text/html (e.g. curl-style).
+	const routesMod = await server.ssrLoadModule(VIRTUAL_ROUTES_ID);
+	const routes = routesMod.routes as Array<{
+		path?: string;
+		children?: unknown[];
+	}>;
+	const patterns = flattenRoutePatterns(routes);
+	if (!patterns.some((pattern) => matchPattern(pattern, pathname))) {
+		return null;
+	}
+	// Read + transform index.html (Vite injects the HMR client / JSX prelude).
+	let template = await readFile(join(root, "index.html"), "utf-8");
+	template = await server.transformIndexHtml(originalUrl, template);
+	// Framework modules load through Vite's SSR module graph so user code (which
+	// imports the same packages) shares a single module instance — otherwise two
+	// copies of `@pyreon/router` would hold separate `RouterContext` IDs and
+	// `useContext` in RouterLink would miss the RouterProvider's value.
+	// `@pyreon/runtime-server` isn't a direct dep of most apps, so zero's
+	// `config()` hook registers an alias that points it at the copy under
+	// zero's own `node_modules` — same path → same Vite module → same instance.
+	const [core, headPkg, headSsr, routerPkg, runtimeServer] = await Promise.all(
+		[
+			server.ssrLoadModule("@pyreon/core") as Promise<
+				typeof import("@pyreon/core")
+			>,
+			server.ssrLoadModule("@pyreon/head") as Promise<
+				typeof import("@pyreon/head")
+			>,
+			server.ssrLoadModule("@pyreon/head/ssr") as Promise<
+				typeof import("@pyreon/head/ssr")
+			>,
+			server.ssrLoadModule("@pyreon/router") as Promise<
+				typeof import("@pyreon/router")
+			>,
+			server.ssrLoadModule("@pyreon/runtime-server") as Promise<
+				typeof import("@pyreon/runtime-server")
+			>,
+		],
+	);
+	// Build the SAME app tree the client will hydrate against. `entry-client`
+	// imports `layout` from `_layout.tsx` and passes it explicitly to
+	// `startClient` → `createApp`. We mirror that here: discover the user's
+	// `_layout` (if present) via Vite's SSR module graph and pass it along.
+	// Without this, SSR renders a different tree (no outer Layout wrapper)
+	// and hydration mismatches at the very first nesting level — cascading
+	// into duplicated mounts of every section below.
+	let userLayout: unknown
+	for (const ext of ['tsx', 'ts', 'jsx', 'js']) {
+		try {
+			const layoutMod = (await server.ssrLoadModule(
+				`/src/routes/_layout.${ext}`,
+			)) as { layout?: unknown; default?: unknown }
+			userLayout = layoutMod.layout ?? layoutMod.default
+			if (userLayout) break
+		} catch {
+			// Try the next extension. If none exist, createApp uses DefaultLayout.
+		}
+	}
+	// Use zero's own `createApp` rather than reassembling the tree by hand —
+	// guarantees server and client agree on every wrapper component (any
+	// future change to the App tree only needs to happen in one place).
+	// Load via `ssrLoadModule` so app.ts shares Vite's SSR module graph with
+	// the user's code: both end up importing the SAME `@pyreon/router` /
+	// `@pyreon/core` / `@pyreon/head` instances, so contexts (RouterContext,
+	// HeadContext, etc.) match between provider and consumer. A direct Node
+	// `import("./app")` would resolve those packages via Node's module graph,
+	// producing duplicate context registries that never connect.
+	const appMod = (await server.ssrLoadModule(
+		"@pyreon/zero/server",
+	)) as typeof import("./server")
+	type CreateAppLayout = NonNullable<
+		Parameters<typeof appMod.createApp>[0]["layout"]
+	>
+	const { App, router: routerInst } = appMod.createApp({
+		routes: routes as import("@pyreon/router").RouteRecord[],
+		routerMode: "history",
+		url: pathname,
+		...(userLayout ? { layout: userLayout as CreateAppLayout } : {}),
+	})
+	// `preload` loads lazy route components AND runs loaders for `pathname` so
+	// the synchronous render pass produces final HTML — no loading fallbacks,
+	// no `useLoaderData() === undefined`.
+	await routerInst.preload(pathname);
+	return runtimeServer.runWithRequestContext(async () => {
+		const app = core.h(App as Parameters<typeof core.h>[0], null);
+		const { html: appHtml, head } = await headSsr.renderWithHead(app);
+		const loaderData = routerPkg.serializeLoaderData(
+			routerInst as Parameters<typeof routerPkg.serializeLoaderData>[0],
+		);
+		const hasData = loaderData && Object.keys(loaderData).length > 0;
+		const loaderScript = hasData
+			? `<script>window.__PYREON_LOADER_DATA__=${JSON.stringify(loaderData).replace(/<\//g, "<\\/")}</script>`
+			: "";
+		return template
+			.replace("<!--pyreon-head-->", head)
+			.replace("<!--pyreon-app-->", appHtml)
+			.replace("<!--pyreon-scripts-->", loaderScript);
+	});
+}
 /** Extract all URL patterns from a nested route tree. */
 function flattenRoutePatterns(
 	routes: Array<{ path?: string; children?: unknown[] }>,