@pyreon/zero 0.16.0 → 0.19.0

package/src/manifest.ts

@@ -475,6 +475,105 @@ const ButtonLink = createLink((props) => (
       seeAlso: ['Link', 'useLink'],
     },
 
+    {
+      name: 'Icon',
+      kind: 'component',
+      signature: '<Icon as={ImportedSvgComponent} | svg={rawSvgMarkupString} {...hostProps} />',
+      summary:
+        "Renders a FULL loaded SVG — it does NOT synthesize its own `<svg>` around hand-authored `<path>` children. You load an svg (it already contains the `<svg>` root) and Icon makes it container-sizable + theme-aware. Two source props: `as` — an imported SVG *component* (`import X from './x.svg?component'`), rendered DIRECTLY with no host wrapper (recommended; it's a real `<svg>` so container-fill is reliable); `svg` — the raw `<svg>…</svg>` *markup string* (`import x from './x.svg?raw'`), inlined via a single `<span>` host (a markup string needs a parent to mount — this one host is unavoidable for the string form). Defaults (`fill=\"currentColor\"`, `display:block;width:100%;height:100%`) are overridable — consumer props spread through and win. No fixed size → fills its container; `fill=\"currentColor\"` themes via CSS `color`. Intentionally no `useIcon` hook (an icon has no composable behaviour); two layers: `createIcon` (one component per loaded glyph) + `Icon` (one-off).",
+      example: `import { Icon } from '@pyreon/zero'
+import Check from './check.svg?component'
+import checkRaw from './check.svg?raw'
+
+// Component form — rendered directly, no wrapper, reliable fill:
+<span style="width:2rem"><Icon as={Check} /></span>
+
+// Raw-markup form — inlined inside one <span> host:
+<span style="width:2rem"><Icon svg={checkRaw} /></span>`,
+      mistakes: [
+        "Expecting `<Icon>` to synthesize an `<svg>` from `<path>` children — it does NOT. Pass a loaded svg via `as` (imported `?component`) or `svg` (imported `?raw` string). Children are not the API",
+        "Expecting `<Icon>` to size itself — it has NO intrinsic size; it fills its container. Wrap + size it (`<span style=\"width:1.5rem\">`) or use a sized flex/grid cell",
+        "Hardcoding `fill=\"#000\"` — breaks theming. Leave the `currentColor` default; drive colour with CSS `color` so dark mode + hover work for free. Only the `as` form forwards `fill` to the real svg — the `svg`-string form's markup is opaque, so colour it via `currentColor` inside the asset",
+        "Expecting svg-only props (`viewBox`, `fill`) to apply in the `svg`-string form — they can't reach the opaque inlined markup; only host attrs (`class`, `style`, `aria-*`, events) forward. Use the `as` form when you need to drive svg attributes",
+        "Reaching for a `useIcon` hook — there isn't one, by design. Use `createIcon` or inline `<Icon>`; an icon has no behaviour worth a hook layer",
+        "Preferring `svg` (raw string) for the wrapper-free guarantee — it's the opposite: `svg` ALWAYS adds a `<span>` host (unavoidable for string inlining); `as` is the zero-wrapper form",
+      ],
+      seeAlso: ['createIcon', 'IconProps', 'Image'],
+    },
+    {
+      name: 'createIcon',
+      kind: 'function',
+      signature: 'function createIcon(source: string | SvgComponent): (props: SvgAttributes) => VNodeChild',
+      summary:
+        "Builds a reusable icon component from a LOADED svg — a raw `<svg>…</svg>` markup string (`?raw`) OR an imported SVG component (`?component`). The result is still just `<Icon>` (string → `svg` prop, component → `as` prop), so it's container-sizable + theme-aware with every prop passed through. A generated icon set is `createIcon`-per-glyph with zero per-icon boilerplate. Mirrors the `createLink`/`createImage` factory layer, minus a hook (icons have no composable behaviour).",
+      example: `import { createIcon } from '@pyreon/zero'
+import StarSvg from './star.svg?component'
+import checkRaw from './check.svg?raw'
+
+export const Star = createIcon(StarSvg)     // component → rendered directly
+export const Check = createIcon(checkRaw)   // raw string → inlined via <span>
+
+// Sized + themed entirely by the consumer:
+<span style="width:48px"><Check class="text-green-600" aria-label="done" /></span>`,
+      mistakes: [
+        "Calling `createIcon` inside a component body — define icon components at module scope (like `createLink`/`createImage`). Re-creating the component every render defeats identity-based reconciliation",
+        "Passing hand-built `<path>` JSX as `source` — `source` is a full loaded svg: a `?raw` markup string OR a `?component` import. It does NOT take individual shapes; the loaded asset already contains its own `<svg>` root",
+        "Assuming the `?raw` form has no wrapper — the string form ALWAYS adds one `<span>` host (unavoidable for inlining markup). Use the `?component` form for the zero-wrapper, attribute-forwarding path",
+      ],
+      seeAlso: ['Icon', 'IconProps', 'createNamedIcon', 'iconsPlugin'],
+    },
+    {
+      name: 'iconsPlugin',
+      kind: 'function',
+      signature: "iconsPlugin({ dir | sets, out?, mode?: 'inline' | 'image' }): Plugin",
+      summary:
+        "Vite plugin (from `@pyreon/zero/server`): point it at a folder of `*.svg` files and it writes a strictly-typed generated `icons.gen.tsx` exporting `<Icon name=\"…\" />`. Add an svg → the `name` union widens; remove one → an invalid `name` fails typecheck. The generated file calls `createNamedIcon(REGISTRY)`, so `keyof typeof REGISTRY` IS the type surface (autocomplete + real go-to-definition, zero per-app wiring — same one-touch shape as fs-router / islands auto-registry). Regenerates on add/unlink in dev (idempotent write — never rewrites identical content). **Named multi-set form** (`sets: { ui: { dir }, brand: { dir, mode } }`, mutually exclusive with `dir`): one generated file exports a strictly-typed component PER set with NAMESPACED types so they never clash — `ui` → `<UiIcon name=\"…\" />` + `type UiIconName`, `brand` → `<BrandIcon name=\"…\" />` + `type BrandIconName`; per-set binding prefixes mean two sets sharing a glyph filename don't collide. Two render modes per the colorful-vs-system split (settable per-set): `mode: 'inline'` (default — system icons; each svg inlined as raw `?raw` markup, `currentColor`-themeable, recolor via CSS `color`) and `mode: 'image'` (colorful / brand icons; each svg emitted as a static asset, rendered `<img>`, NO mutation, original colors preserved). Default `out` is `icons.gen.tsx` next to `dir` for the single-set form (`src/icons` → `src/icons.gen.tsx`) or `src/icons.gen.tsx` for the multi-set form — recommend gitignoring it (build artifact). It writes a real file (NOT a virtual module) deliberately: the published `@pyreon/zero` package can't `import` a plugin virtual module — Rolldown resolves static imports before plugin `resolveId` (the same constraint that makes islands need `hydrateIslandsAuto(registry)` with an explicit import).",
+      example: `// vite.config.ts — single set:
+import { iconsPlugin } from '@pyreon/zero/server'
+iconsPlugin({ dir: './src/icons' })
+// app: import { Icon } from './icons.gen'; <Icon name="check-circle" />
+
+// Named multi-set — per-set typed components, no IconName clash:
+iconsPlugin({ sets: {
+  ui:    { dir: './src/icons/ui' },
+  brand: { dir: './src/icons/brand', mode: 'image' },
+}})
+// app: import { UiIcon, BrandIcon } from './icons.gen'
+// <UiIcon name="arrow-left" />  <BrandIcon name="logo-mark" />`,
+      mistakes: [
+        "Passing BOTH `dir` and `sets` (or neither) — exactly one is required; the plugin throws `[Pyreon] iconsPlugin: provide EXACTLY ONE of dir or sets` at config time",
+        "Using `mode: 'inline'` (default) for multicolor / brand SVGs — inline mode is for monochrome system icons you recolor via `currentColor`. A multicolor logo's hardcoded fills survive but you lose nothing by using `mode: 'image'`, which is the correct choice for no-mutation colorful assets",
+        "Using `mode: 'image'` for icons you need to recolor — `<img>` can't be themed via CSS `color`; the svg is opaque. Recolorable system icons need `mode: 'inline'`",
+        "Editing the generated `icons.gen.tsx` by hand — it's regenerated on every add/unlink. Add/remove `.svg` files in the set folder(s) instead; commit the gitignore entry, not the file",
+        "Expecting a virtual `import 'virtual:zero/icons'` — there isn't one (Rolldown import-ordering constraint). The plugin writes a REAL file you import by path; that's what gives go-to-definition + zero wiring",
+        "Pointing a set `dir` at a folder that doesn't exist yet — `scanIconDir` returns empty and the generated `*IconName` is `never` (every `name` fails typecheck). Create the folder + drop at least one `.svg` first",
+        "Forgetting `vite/client` types — the generated file's `?raw` imports rely on Vite's ambient `*.svg?raw` module declaration; the generated file emits `/// <reference types=\"vite/client\" />` but the consuming tsconfig must still resolve `vite/client`",
+      ],
+      seeAlso: ['createNamedIcon', 'Icon', 'IconProps'],
+    },
+    {
+      name: 'createNamedIcon',
+      kind: 'function',
+      signature:
+        "function createNamedIcon<R extends Record<string, string>>(registry: R, options?: { mode?: 'inline' | 'image' }): (props: { name: keyof R & string } & …) => VNodeChild",
+      summary:
+        "Runtime half of `iconsPlugin` — builds a strictly-typed `<Icon name=\"…\" />` from a name→source registry. `keyof R` makes `name` a precise string union (the generated file passes a literal registry so the union infers there → autocomplete + go-to-definition). `mode: 'inline'` (default) treats each `source` as raw `<svg>` markup rendered via `Icon` (`currentColor`-themeable system icons); `mode: 'image'` treats each `source` as an asset URL rendered `<img>` with NO mutation (colorful / brand icons). Either way it stays container-filling + props-transparent. Not normally hand-called — `iconsPlugin` emits the generated file that calls it; call it directly only for a hand-maintained set.",
+      example: `// icons.gen.tsx (auto-generated by iconsPlugin):
+import { createNamedIcon } from '@pyreon/zero'
+export const Icon = createNamedIcon({ 'check-circle': '<svg…>…</svg>' })
+
+// image mode (hand-maintained colorful set):
+import logo from './logo.svg' // Vite → URL
+export const Brand = createNamedIcon({ logo }, { mode: 'image' })
+<Brand name="logo" alt="Company" />`,
+      mistakes: [
+        "Passing a `Record<string, string>` typed loosely (e.g. `: Record<string, string>`) — that widens `keyof R` to `string` and you lose the typed `name`. Pass the object literal directly (or `as const`) so the keys infer",
+        "Using `mode: 'image'` then expecting `fill` / svg props to apply — the `<img>` is opaque; only host attrs (`class`, `style`, `alt`, events) forward. Use `mode: 'inline'` for svg-attribute control",
+        "Omitting `alt` in `mode: 'image'` — it defaults to `\"\"` (decorative). Pass a real `alt` for meaningful icons; screen readers skip empty-alt images",
+        "Calling `createNamedIcon` inside a component body — define the set once at module scope (the generated file does). Re-creating it per render defeats identity-based reconciliation",
+      ],
+      seeAlso: ['iconsPlugin', 'Icon', 'IconProps'],
+    },
     {
       name: 'Image',
       kind: 'component',

package/src/rate-limit.ts

@@ -62,6 +62,22 @@ export function rateLimitMiddleware(config: RateLimitConfig = {}): Middleware {
     for (const [key, entry] of store) {
       if (entry.resetAt <= now) store.delete(key)
     }
+    // HARD cap. The expired-sweep above only removes entries whose
+    // window has elapsed. An attacker flooding unique keys WITHIN one
+    // window (spoofed `X-Forwarded-For` / proxy header — `defaultKeyFn`
+    // trusts request headers) produces only fresh entries, so the sweep
+    // frees nothing and `store.set` grows the Map without bound — an
+    // unauthenticated memory-exhaustion DoS. `MAX_STORE_SIZE` was a
+    // declared constant used ONLY as a sweep trigger, never enforced.
+    // Map preserves insertion order, so evicting from the front drops
+    // the oldest trackers first (acceptable: an evicted attacker key
+    // simply gets a fresh window — no bypass of legitimate limits since
+    // a real client re-inserts and is immediately re-tracked).
+    while (store.size > MAX_STORE_SIZE) {
+      const oldest = store.keys().next().value
+      if (oldest === undefined) break
+      store.delete(oldest)
+    }
   }
 
   return (ctx: MiddlewareContext) => {

package/src/seo.ts

@@ -135,10 +135,25 @@ export function generateSitemap(
     .filter((p): p is string => p !== null)
     .filter((p) => !exclude.some((e) => p.startsWith(e)))
 
-  const allPaths: SitemapEntry[] = [
-    ...paths.map((p) => ({ path: p, changefreq, priority })),
-    ...(config.additionalPaths ?? []),
-  ]
+  // Dedup by path (first-wins, order-preserving). The same static route
+  // routinely appears in BOTH the file-system route scan AND
+  // `additionalPaths` (e.g. SSG-emitted paths merged in via
+  // `seoPlugin`), which previously produced a DUPLICATE `<url>` entry —
+  // the i18n branch of `clusterPathsByLocale` dedups via `byUnPrefixed`,
+  // but the non-i18n branch is a raw 1:1 `entries.map(...)`, so without
+  // this the duplicate reached the emitted sitemap. Dedup here covers
+  // both branches at the single source. The route-scan entry wins so its
+  // configured `changefreq`/`priority` is kept over a bare dup.
+  const allPaths: SitemapEntry[] = (() => {
+    const byPath = new Map<string, SitemapEntry>()
+    for (const e of [
+      ...paths.map((p) => ({ path: p, changefreq, priority })),
+      ...(config.additionalPaths ?? []),
+    ]) {
+      if (!byPath.has(e.path)) byPath.set(e.path, e)
+    }
+    return [...byPath.values()]
+  })()
 
   // PR K: when i18n is set, cluster URLs by their un-prefixed (default-
   // locale) form so each `<url>` entry can carry the hreflang siblings

package/src/server.ts

@@ -70,6 +70,8 @@ export { compose, getContext } from "./middleware";
 export { zeroPlugin as default, getZeroPluginConfig } from "./vite-plugin";
 export type { FaviconPluginConfig, FaviconLocaleConfig } from "./favicon";
 export { faviconPlugin, faviconLinks } from "./favicon";
+export type { IconsPluginConfig, IconSetConfig, NamedSetInput } from "./icons-plugin";
+export { iconsPlugin, iconNameFromFile, scanIconDir, generateIconSetSource, generateNamedIconSetsSource, componentNameFromSetKey } from "./icons-plugin";
 export type { SeoPluginConfig, SitemapConfig, RobotsConfig } from "./seo";
 export { seoPlugin, generateSitemap, generateRobots, jsonLd, seoMiddleware } from "./seo";
 export type { OgImagePluginConfig, OgImageTemplate, OgImageLayer } from "./og-image";

package/src/sharp.d.ts

@@ -9,6 +9,12 @@ declare module 'sharp' {
     toFile(path: string): Promise<void>
     toBuffer(): Promise<Buffer>
     metadata(): Promise<{ width?: number; height?: number; format?: string }>
+    /**
+     * Image statistics. `dominant` is the histogram-mode RGB swatch —
+     * the basis of the `'color'` / `'dominant-color'` placeholder
+     * strategy (a flat-fill SVG, not a muddy channel average).
+     */
+    stats(): Promise<{ dominant: { r: number; g: number; b: number } }>
   }
 
   function sharp(input: string | Buffer): SharpInstance

package/src/ssg-plugin.ts

@@ -23,7 +23,7 @@
 
 import { existsSync } from 'node:fs'
 import { mkdir, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises'
-import { dirname, join, resolve } from 'node:path'
+import { dirname, join, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { Plugin } from 'vite'
 import { resolveAdapter } from './adapters'
@@ -373,6 +373,25 @@ export function expandUrlPattern(pattern: string, params: Record<string, string>
           `[zero:ssg] getStaticPaths for "${pattern}" returned params without "${name}"`,
         )
       }
+      // Path-escape guard. The value is substituted verbatim into the
+      // URL that becomes a `dist/<path>/index.html` write target. A
+      // single (non-catch-all) `:slug` is ONE segment — a value
+      // containing `/` or being `.`/`..` (e.g. an unsanitized CMS slug
+      // `../../secret`) would escape the intended structure and write
+      // outside it. Catch-all `:slug*` legitimately spans segments
+      // (`a/b/c`), so it's exempt from the `/` check but still rejects
+      // `.`/`..` traversal segments.
+      const segs = isCatchAll ? value.split('/') : [value]
+      if (
+        (!isCatchAll && value.includes('/')) ||
+        segs.some((s) => s === '.' || s === '..')
+      ) {
+        throw new Error(
+          `[zero:ssg] getStaticPaths for "${pattern}" produced an unsafe "${name}" value ` +
+            `(${JSON.stringify(value)}): a ${isCatchAll ? 'catch-all' : 'dynamic'} segment ` +
+            `must not contain path-traversal ("." / "..")${isCatchAll ? '' : ' or "/"'}.`,
+        )
+      }
       return value
     })
     .join('/')
@@ -443,10 +462,17 @@ async function autoDetectStaticPaths(
     }
   }
 
+  // Dedup (order-preserving). The same concrete path can be produced
+  // more than once — a `getStaticPaths` returning a duplicate slug, or
+  // i18n route fan-out colliding — which otherwise renders the same
+  // `dist/<path>/index.html` twice (wasted work + last-write race) and
+  // feeds a duplicate `<url>` into the SSG→sitemap merge.
+  const deduped = [...new Set(out)]
+
   // Always include "/" as a fallback if no static routes were found —
   // a project with only dynamic routes still needs an index.html for the
   // host to know where to send unmatched URLs.
-  return out.length > 0 ? out : ['/']
+  return deduped.length > 0 ? deduped : ['/']
 }
 
 async function resolvePaths(
@@ -598,6 +624,21 @@ function resolveOutputPath(distDir: string, path: string): string {
   return join(distDir, path, 'index.html')
 }
 
+/**
+ * Path-containment check that is SEPARATOR-TERMINATED. A bare
+ * `resolve(filePath).startsWith(resolve(distDir))` is a string-prefix
+ * test, not a path test: with distDir `/app/dist`, a traversed filePath
+ * resolving to the SIBLING `/app/dist-evil/x` passes
+ * `'/app/dist-evil/x'.startsWith('/app/dist')` → true and the build
+ * writes outside the intended output root. `path` derives from caller
+ * route params (CMS slugs via `getStaticPaths`), so this is reachable.
+ */
+function isInsideDist(distDir: string, filePath: string): boolean {
+  const root = resolve(distDir)
+  const target = resolve(filePath)
+  return target === root || target.startsWith(root + sep)
+}
+
 // ─── Redirect emission (PR B) ──────────────────────────────────────────────
 //
 // The shape returned by the SSG entry's renderPath when a loader throws
@@ -1128,8 +1169,7 @@ export function ssgPlugin(userConfig: ZeroConfig = {}): Plugin {
 
             if (config.ssg?.redirectsAsHtml === 'meta-refresh') {
               const filePath = resolveOutputPath(distDir, p)
-              const resolvedOut = resolve(distDir)
-              if (!resolve(filePath).startsWith(resolvedOut)) {
+              if (!isInsideDist(distDir, filePath)) {
                 errors.push({ path: p, error: new Error(`Path traversal detected: "${p}"`) })
                 return
               }
@@ -1144,8 +1184,7 @@ export function ssgPlugin(userConfig: ZeroConfig = {}): Plugin {
           const filePath = resolveOutputPath(distDir, p)
 
           // Path-traversal guard — same as @pyreon/server's prerender.
-          const resolvedOut = resolve(distDir)
-          if (!resolve(filePath).startsWith(resolvedOut)) {
+          if (!isInsideDist(distDir, filePath)) {
             errors.push({ path: p, error: new Error(`Path traversal detected: "${p}"`) })
             return
           }
@@ -1174,8 +1213,7 @@ export function ssgPlugin(userConfig: ZeroConfig = {}): Plugin {
               const fallbackHtml = await config.ssg.onPathError(p, error)
               if (typeof fallbackHtml === 'string') {
                 const filePath = resolveOutputPath(distDir, p)
-                const resolvedOut = resolve(distDir)
-                if (!resolve(filePath).startsWith(resolvedOut)) {
+                if (!isInsideDist(distDir, filePath)) {
                   errors.push({ path: p, error: new Error(`Path traversal detected: "${p}"`) })
                   return
                 }
@@ -1505,6 +1543,7 @@ export const _internal = {
   resolvePaths,
   autoDetectStaticPaths,
   resolveOutputPath,
+  isInsideDist,
   expandUrlPattern,
   injectIntoTemplate,
   renderNetlifyRedirects,

package/src/types.ts

@@ -58,6 +58,15 @@ export interface ISRConfig {
    * space (e.g. `/user/:id` where `:id` is free-form).
    */
   maxEntries?: number
+  /**
+   * Max wall-time (ms) for a single background revalidation before it is
+   * abandoned. Without a bound, a handler that hangs leaves its key
+   * pinned in the in-flight set forever — every later request for that
+   * key short-circuits the de-dupe guard and the entry can never
+   * recover from stale. Default: `30000` (matches the Suspense
+   * streaming timeout).
+   */
+  revalidateTimeoutMs?: number
   /**
    * Cache-key derivation function. The default keys cache entries by
    * `url.pathname` ONLY — query strings, cookies, and headers are
@@ -254,6 +263,38 @@ export interface ZeroConfig {
       currentPath: string
       elapsed: number
     }) => void | Promise<void>
+    /**
+     * Route-level code splitting in SSG mode. Default `true`.
+     *
+     * When `true` (default), each route file becomes its own dynamic-import
+     * chunk via `lazy(() => import("..."))` — only the route the user
+     * lands on plus its dependencies ship in the initial bundle, the
+     * rest fetch on navigation. Matches the SSR/SPA-mode behaviour zero
+     * has always had; brings parity to SSG.
+     *
+     * When `false`, every route is bundled statically into the main
+     * client chunk (the pre-2026-Q3 SSG behaviour). Useful for tiny
+     * sites (2-5 pages) where the single-chunk-then-instant-nav trade
+     * is preferable — the chunk-fetch cost on navigation is gone, and
+     * the marginal bytes are negligible.
+     *
+     * Crossover point: ~5-8 routes. Below that, single-chunk is fine.
+     * Above that, lazy() shrinks the initial bundle by a meaningful
+     * amount (a 50-route docs site might drop from 200 KB to 80 KB on
+     * first paint).
+     *
+     * Underlying mechanism is the same 3-tier generator zero already
+     * uses for SSR/SPA mode (`fs-router.ts:generateRouteEntry`): lazy
+     * component + inlined metadata when possible, lazy + lazy-thunked
+     * function exports when not, namespace-import fallback for cases
+     * the literal-extractor can't reach.
+     *
+     * @example
+     * ssg: {
+     *   splitChunks: false, // bundle-everything for a 3-page marketing site
+     * }
+     */
+    splitChunks?: boolean
   }
 
   /** ISR config — only used when mode is "isr". */

package/src/vite-plugin.ts

@@ -90,6 +90,27 @@ export function getZeroPluginConfig(plugin: Plugin): ZeroConfig | undefined {
 	return zeroPluginConfigMap.get(plugin);
 }
 
+/**
+ * Detects `--port` / `--port=N` / `-p N` / `-p=N` in `process.argv`.
+ * Used by the plugin's `config()` hook to decide whether to apply the
+ * default port — when the CLI was invoked with `--port`, the plugin
+ * must skip its default so the CLI flag wins (see the comment at the
+ * port-handling block in `zeroPlugin()` for the full precedence model).
+ *
+ * Exported for testing only (the plugin uses it internally).
+ *
+ * @internal
+ */
+export function argvHasPortFlag(argv: readonly string[] = process.argv): boolean {
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--port" || a === "-p") return true;
+		if (a !== undefined && (a.startsWith("--port=") || a.startsWith("-p=")))
+			return true;
+	}
+	return false;
+}
+
 /**
  * Zero Vite plugin — adds file-based routing and zero-config conventions
  * on top of @pyreon/vite-plugin.
@@ -138,8 +159,23 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin[] {
 					const routes = config.i18n
 						? expandRoutesForLocales(baseRoutes, config.i18n)
 						: baseRoutes;
+					// SSG mode: lazy() route splitting by default (parity with
+					// SSR/SPA). Opt-out via `ssg.splitChunks: false` for tiny
+					// sites that prefer single-chunk + instant navigation.
+					//
+					// Pre-2026-Q3: SSG was hardcoded to `staticImports: true`
+					// (bundle everything). Trade-off was instant post-hydration
+					// nav, but the initial bundle grew linearly with route
+					// count — a 50-route docs site shipped all 50 route
+					// components on first paint. Lazy splitting (now the
+					// default for SSG) fixes that: only the landing route +
+					// deps load up front, the rest fetch on navigation. See
+					// `ssg.splitChunks` JSDoc in types.ts for the crossover-
+					// point rationale.
+					const ssgSplitDisabled =
+						config.mode === "ssg" && config.ssg?.splitChunks === false;
 					return generateRouteModuleFromRoutes(routes, routesDir, {
-						staticImports: config.mode === 'ssg',
+						staticImports: ssgSplitDisabled,
 					});
 				} catch (_err) {
 					return `export const routes = []`;
@@ -389,16 +425,32 @@ export function zeroPlugin(userConfig: ZeroConfig = {}): Plugin[] {
 				optimizeDeps: {
 					exclude: pyreonExclude,
 				},
-				// Only set the port when the user explicitly provided one in
-				// `zero({ port: N })`. Without this guard, the plugin always
-				// returned `server: { port: 3000 }` which overrode Vite's CLI
-				// `--port` flag and made multi-example dev impossible — every
-				// example tried to bind 3000 even when launched with
-				// `vite --port 5173`. Surfaced when wiring up the playwright
-				// e2e suite.
-				...(userConfig.port !== undefined
-					? { server: { port: config.port } }
-					: {}),
+				// Port handling — the zero-canonical default is 3000 (matches
+				// `zero dev` / `zero preview` / the runtime adapter, and
+				// matches Next.js / Remix / Astro convention).
+				//
+				// Apply the default UNLESS Vite's CLI was invoked with
+				// `--port`/`-p` (in which case the CLI flag must win — see
+				// memory: vite cli port doesnt override plugin). PR #579
+				// proved this empirically: returning `server: { port: 3000 }`
+				// unconditionally clobbered `vite --port 517N --strictPort`
+				// in the e2e playwright config and every webServer timed
+				// out. argv detection here lets the CLI win at the source.
+				//
+				// Precedence (CLI > user vite.config > zero({port}) > 3000):
+				//   1. `vite --port N` → argvHasPortFlag() === true → plugin
+				//      omits `server.port` entirely → CLI value wins
+				//   2. User `vite.config.ts server: { port: N }` → user
+				//      config beats plugin in Vite's merge order
+				//   3. `zero({ port: N })` → resolved into `config.port`
+				//   4. Default 3000 — when no other source set a port
+				//
+				// `process.argv` is populated by the time Vite invokes the
+				// plugin's config() hook (Vite calls plugins synchronously
+				// during CLI bootstrap before applying inline overrides).
+				...(userConfig.port === undefined && argvHasPortFlag()
+					? {}
+					: { server: { port: config.port } }),
 				// Propagate `zero({ base })` to Vite's `base` config — that's
 				// what controls asset URL rewriting in the built HTML/JS
 				// (`<script src="/blog/assets/…">`). Pre-fix this was a