@wular/pnext 0.0.6 → 0.0.8

package/reference/performance.md

@@ -1,155 +1,34 @@
 # Performance
 
-Measured against Next.js: the same fixture source runs under both frameworks and `bun bench` measures them side by side, on a Blacksmith 4-vCPU CI runner (full machine details below). The ranges below span the fixtures — hello-world, an SSR site, and a mid-size admin dashboard (30 routes, 18 client islands):
+Measured results against Next.js, and what a route ships to the browser. The numbers come from running the same hello-world, SSR, and 30-route dashboard fixtures under both frameworks. Ratios are Next.js time or memory divided by pnext, so a larger number favors pnext.
 
-|                             |                   pnext vs Next.js |
-| --------------------------- | ---------------------------------: |
-| Dev server ready            |                **3.8–4.3× faster** |
-| First page, cold            |                  **10–12× faster** |
-| Warm request (dev)          |                **1.6–4.7× faster** |
-| HMR save → visible          |                       **0.3–2×** ¹ |
-| Production build            |                **7.2–8.8× faster** |
-| Warm request (prod)         |                  **2–3.4× faster** |
-| Prod server ready           |                **1.8–2.3× faster** |
-| Dev server memory           |                  **3.4–4.1× less** |
-| Build peak memory           |                    **3–3.7× less** |
-| Framework install size      | **59× smaller** (7.1 MB vs 421 MB) |
-| First-page client JS (gzip) |                   **9.5–65× less** |
+| Metric                        | Result across the three fixtures                                                      |
+| ----------------------------- | ------------------------------------------------------------------------------------- |
+| Dev first page HTML           | **10.1–12.4× faster**                                                                 |
+| HMR save to visible content   | **2.0× faster** on hello-world; **3.1–3.9× slower** on the SSR and dashboard fixtures |
+| Production build time         | **7.2–8.8× faster**                                                                   |
+| Dev server memory             | **3.4–4.1× less**                                                                     |
+| Production cold start (ready) | **1.8–2.3× faster**                                                                   |
 
-¹ pnext live-reloads (no client HMR runtime; state doesn't survive a save) — the metric
-is save → fresh HTML, which both models support. Scoped invalidation fixed the small
-fixture (21.9 ms, ahead of Next); the larger fixtures still trail on this runner
-(264/300 ms vs 68/98 ms) and the remaining cost is under investigation.
+For interactive tables and per-fixture values, see [pnext.dev/benchmarks](https://www.pnext.dev/benchmarks).
 
-Nothing is prebundled — the dev server compiles what a request needs and caches it content-addressed, which is why readiness doesn't scale with app size. The production server idles at parity with Next (~85–87 MB) while answering warm requests 2–3.4× faster.
+## What ships to the browser
 
-The tables below are one full run's absolute numbers, pasted from `bun bench` output (the CI run's `bench-output` artifact carries the same data as `bench.json`).
+Server-only routes ship 0 KB of route JavaScript, because they need no browser runtime to render their content.
 
-- Date: 2026-08-20 (actions run 32364720143)
-- Machine: CI — Blacksmith 4 vCPU (Intel Xeon), 16 GB RAM, Ubuntu 22.04 x64
-- Bun: 1.3.10
-- Next.js: 16.2.12
-- Runs per metric: 5 (first discarded), medians reported
+For client navigation and prefetching, the prefetch-only runtime is 348 B gzip. The combined router and hydrator runtime is 4.47 KB gzip.
 
-Every fixture under `bench/fixtures/` runs unmodified on both frameworks, so the
-two columns render the same app from the same source.
+Routes using the Next compatibility layer carry its navigation client, so their client-JS numbers are not the core zero-JS case.
 
-## Fixture: hello-world
+## The HMR result
 
-| Metric                           | pnext    | Next.js   | Ratio   |
-| -------------------------------- | -------- | --------- | ------- |
-| Dev cold start (ready)           | 56.4 ms  | 212.3 ms  | 3.76x   |
-| Dev first page HTML              | 79.9 ms  | 993.5 ms  | 12.44x  |
-| Dev warm request (p50 of 7)      | 3.0 ms   | 14.0 ms   | 4.69x   |
-| Dev server RSS (ready + 7 warm)  | 130.8 MB | 536.4 MB  | 4.10x   |
-| HMR save → visible               | 21.9 ms  | 44.8 ms   | 2.04x   |
-| Prod build (wall)                | 291.3 ms | 2569.4 ms | 8.82x   |
-| Prod build peak RSS              | 124.2 MB | 455.8 MB  | 3.67x   |
-| Prod start (ready)               | 60.7 ms  | 110.9 ms  | 1.83x   |
-| Prod warm request (p50 of 7)     | 0.6 ms   | 1.2 ms    | 2.05x   |
-| Prod server RSS (ready + 7 warm) | 85.2 MB  | 85.7 MB   | 1.01x   |
-| Framework install size           | 7.1 MB   | 420.7 MB  | 59.14x  |
-| First-page client JS (raw)       | 4.43 KB  | 502.47 KB | 113.36x |
-| First-page client JS (gzip)      | 2.19 KB  | 141.78 KB | 64.67x  |
-| First-page JS files              | 3        | 5         | 1.67x   |
-| Zero-island route client JS      | 4.43 KB  | 502.47 KB | 113.36x |
+HMR is slower than Next.js on the larger fixtures and is under investigation. pnext uses live reload rather than a client HMR runtime, so component state does not survive a save. The measurement above is the time until the page serves fresh visible content.
 
-Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
+## How these were measured
 
-## Fixture: ssr
+These results are from **2026-08-20**, using Bun **1.3.10** and Next.js **16.2.12** on a Blacksmith 4-vCPU (Intel Xeon), 16 GB RAM, Ubuntu 22.04 x64 CI runner. Each metric used five runs, discarded the first, and reports medians.
 
-| Metric                           | pnext    | Next.js   | Ratio   |
-| -------------------------------- | -------- | --------- | ------- |
-| Dev cold start (ready)           | 56.0 ms  | 212.8 ms  | 3.80x   |
-| Dev first page HTML              | 93.5 ms  | 1043.3 ms | 11.16x  |
-| Dev warm request (p50 of 7)      | 16.5 ms  | 26.4 ms   | 1.60x   |
-| Dev server RSS (ready + 7 warm)  | 151.3 MB | 553.6 MB  | 3.66x   |
-| HMR save → visible               | 264.3 ms | 68.3 ms   | 0.26x   |
-| Prod build (wall)                | 310.5 ms | 2738.8 ms | 8.82x   |
-| Prod build peak RSS              | 136.8 MB | 456.6 MB  | 3.34x   |
-| Prod start (ready)               | 57.1 ms  | 105.5 ms  | 1.85x   |
-| Prod warm request (p50 of 7)     | 0.5 ms   | 1.3 ms    | 2.50x   |
-| Prod server RSS (ready + 7 warm) | 86.0 MB  | 85.9 MB   | 1.00x   |
-| Framework install size           | 7.1 MB   | 420.7 MB  | 59.14x  |
-| First-page client JS (raw)       | 27.36 KB | 502.78 KB | 18.37x  |
-| First-page client JS (gzip)      | 11.39 KB | 142.03 KB | 12.47x  |
-| First-page JS files              | 4        | 6         | 1.50x   |
-| Zero-island route client JS      | 4.46 KB  | 502.47 KB | 112.56x |
-
-Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
-
-## Fixture: dashboard
-
-| Metric                           | pnext    | Next.js   | Ratio  |
-| -------------------------------- | -------- | --------- | ------ |
-| Dev cold start (ready)           | 57.1 ms  | 246.4 ms  | 4.31x  |
-| Dev first page HTML              | 127.0 ms | 1285.8 ms | 10.12x |
-| Dev warm request (p50 of 7)      | 21.6 ms  | 34.1 ms   | 1.58x  |
-| Dev server RSS (ready + 7 warm)  | 168.6 MB | 577.1 MB  | 3.42x  |
-| HMR save → visible               | 300.4 ms | 97.6 ms   | 0.32x  |
-| Prod build (wall)                | 637.5 ms | 4566.3 ms | 7.16x  |
-| Prod build peak RSS              | 188.0 MB | 569.0 MB  | 3.03x  |
-| Prod start (ready)               | 55.6 ms  | 128.8 ms  | 2.32x  |
-| Prod warm request (p50 of 7)     | 0.5 ms   | 1.7 ms    | 3.41x  |
-| Prod server RSS (ready + 7 warm) | 87.3 MB  | 90.6 MB   | 1.04x  |
-| Framework install size           | 7.1 MB   | 420.7 MB  | 59.14x |
-| First-page client JS (raw)       | 38.51 KB | 507.42 KB | 13.18x |
-| First-page client JS (gzip)      | 15.26 KB | 144.85 KB | 9.50x  |
-| First-page JS files              | 6        | 9         | 1.50x  |
-
-Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
-
-## Client runtime bundles
-
-| Runtime                  | Raw      | Gzip    | Brotli  |
-| ------------------------ | -------- | ------- | ------- |
-| router-prefetch-only     | 473 B    | 348 B   | 283 B   |
-| combined-router-hydrator | 10.47 KB | 4.47 KB | 4.07 KB |
-
-## Targets
-
-| Target                                     | Limit            | Measured              | Status        |
-| ------------------------------------------ | ---------------- | --------------------- | ------------- |
-| Dev cold start, ssr fixture (pnext)        | <= 100 ms        | 56.0 ms               | PASS          |
-| Router runtime                             | <= 1.00 KB gzip  | 348 B gzip            | PASS          |
-| Hydrated-route framework tax               | <= 5.00 KB gzip  | 4.47 KB gzip          | PASS          |
-| Zero-island route client JS (ssr `/about`) | 0 B (core pnext) | 4.46 KB (compat.next) | not exercised |
-
-## Notes
-
-- First-page client JS counts the `<script src>` and `rel="modulepreload"` assets the
-  route executes, fetched from each framework's own production server; `noModule`
-  polyfills and speculative `rel="preload"` hints for other routes are excluded on both sides.
-- Dev cold start wipes the output directory, spawns the dev server on a free port and
-  stops at the readiness banner; first page HTML is the GET that follows it, so it
-  includes on-demand compilation.
-- HMR appends a marker to a rendered string in a page component and polls until the
-  page serves it back. A 200 with stale HTML does not count. pnext applies the save via
-  live-reload (full document refresh, no client HMR runtime); Next applies it via Fast
-  Refresh. The metric is model-agnostic: time until fresh content is served.
-- Fixtures enable `compat.next` so one source tree runs on both frameworks. That ships
-  pnext's Next-compat navigation client, which a core pnext app does not carry — the
-  0 B zero-island budget is a core-pnext invariant this suite does not exercise.
-
-## Memory
-
-- RSS is summed across the whole process tree (parent + spawned workers), read once at a
-  fixed point: right after the ready signal and the 7 warm requests, dev and prod alike.
-  It is never sampled at an arbitrary time, since RSS is pressure-sensitive.
-- Build peak RSS comes from `/usr/bin/time` wrapping the build process directly (`-l` on
-  macOS, `-v` on Linux), not the tree-sum helper — it is the OS-reported peak over the
-  whole build, not a single snapshot. The framework server-entry prebundle is emitted by
-  a short-lived child whose transient RSS (~15–25 MB, returned at exit) this number
-  excludes.
-- Framework install size is each framework's own package cost, not the fixture's total
-  `node_modules`, which both frameworks share: `next` + its platform `@next/swc-*` binary,
-  or `@wular/pnext`'s npm-publish footprint (its `package.json` "files" list, since the
-  repo resolves it to source rather than an installed build) + `preact`.
-
-## Commands
-
-```sh
-bun bench                  # every fixture, both frameworks
-bun bench/run.ts ssr       # one fixture
-bun bench/run.ts all --framework=pnext --runs=5
-```
+- The fixtures use the same source under both frameworks.
+- Dev first page HTML includes on-demand compilation after a cold server start.
+- Dev memory is summed across the server process tree after readiness and seven warm requests.
+- Build memory is the operating system's reported peak RSS.

package/reference/rendering.md

@@ -1,20 +1,10 @@
 # Rendering
 
-pnext renders on the server first and sends browser JavaScript only for interactive components.
+Where a component runs, what crosses between server and browser, and how to stream or defer work. pnext renders on the server first and sends browser JavaScript only for the components that need it.
 
 ## Server Components
 
-Pages and layout components are Server Components. They run only on the server, so they can read files, query databases, call internal services, and use server-only dependencies without adding that code to the browser bundle.
-
-A `layout.tsx` file does not need a default export. Use metadata-only layouts when a segment only needs to set page metadata.
-
-Use Server Components for data loading and non-interactive UI:
-
-- Render HTML from server data.
-- Keep expensive parsing, formatting, and data libraries on the server.
-- Pass serializable props to Client Components for interactive parts.
-- Render Client Components inside Server Components when part of the page needs interactivity.
-- Read request data from explicit page/layout props when a route depends on headers or cookies.
+Pages and layouts are Server Components. They run only on the server, so they can read files, query databases, call internal services, and use server-only dependencies without any of that reaching the browser bundle. They can be async, and static builds wait for the final HTML.
 
 ```tsx
 export default async function Page() {
@@ -23,105 +13,118 @@ export default async function Page() {
 }
 ```
 
-Server components can be async. Static builds wait for the final HTML.
-
-Pages and layouts that read `request` receive a `NextRequest` compatible object. It extends the standard Request with convenience access for cookies and headers.
+A layout file does not need a default export. Use a metadata-only layout when a segment only needs to set page metadata.
 
-Use `request.cookies.get()`, `request.headers.get()`, `request.method`, and `request.url` from props. It keeps static routes static and makes request-dependent routes dynamic.
-
-Apps using `compat.next` can also import `cookies()` and `headers()` from `next/headers`.
-
-## Document
+## Client Components
 
-Use the root `layout.tsx` to own `<html>` and `<body>`:
+A `"use client"` directive marks a component that needs browser APIs, hooks, or event handlers. Server Components can render them. They render HTML on the server, then hydrate in the browser.
 
 ```tsx
-import type { LayoutProps } from '@wular/pnext'
+'use client'
 
-export default function Layout({ children }: LayoutProps) {
+import { useState } from 'preact/hooks'
+
+export function Counter({ initial }: { initial: number }) {
+  const [count, setCount] = useState(initial)
   return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
+    <button onClick={() => setCount(count + 1)}>Count {count}</button>
   )
 }
 ```
 
-If the root layout exports a default component, it must return `<html>` and `<body>`.
-If the root layout only exports metadata, pnext creates the document shell.
+Files imported by a client component become client code automatically. Add the directive to an imported file only when a server component also renders it directly.
 
-### Metadata
+A Client Component can wrap server-rendered children. Those children stay server-rendered, and only the wrapper hydrates.
 
-Pages and layouts can export core build-time `metadata`, `metadata()`, `viewport`, and `viewport()`. See [Metadata](./metadata.md) for the full core metadata model.
+Put the directive at the top of a page when the whole page needs browser-only behavior. Prefer smaller client components when only part of the page is interactive.
 
-## Request Cache
+## Lazy loading
 
-Use server-only `cache()` to dedupe repeated server work during one render or route-handler request:
+`dynamic()` defers loading a component. It works in Server Components and Client Components alike, and inside a Client Component it is a browser lazy loader. The loader can also be a literal module path for a default export.
 
 ```tsx
-import { cache } from '@wular/pnext/cache'
+import { dynamic } from '@wular/pnext/dynamic'
 
-export const getPost = cache(async (id: string) => {
-  return db.post.findUnique({ where: { id } })
+const Chart = dynamic(() => import('./chart').then(m => m.Chart), {
+  load: 'visible',
 })
 ```
 
-Calls to the same cached function with the same arguments share the result inside the current request. The cache is cleared between requests, so it does not share data across users, is not a persistent data cache, and should not be imported from Client Components.
+A Client Component target renders on the server and hydrates by default. The options change that:
 
-## Client Components
+- `ssr: false` produces browser-only output.
+- `load: 'visible'` waits for the island to enter view, and accepts `rootMargin` and `threshold`. It is browser-only as well unless `ssr` is true.
+- `loading` supplies fallback UI.
 
-Add `"use client"` to components that need browser APIs, hooks, or event handlers.
+## Props that cross the boundary
 
-```tsx
-// app/counter.tsx
-'use client'
+Props passed from a server component to a client component must be serializable.
 
-import { useState } from 'preact/hooks'
+- Accepted: strings, numbers, booleans, `null`, `undefined`, arrays, plain objects, `Map`, `Set`, typed arrays, and `ArrayBuffer`.
+- Rejected: functions, symbols, `bigint`, and class instances such as `Date` and `URL`. Pass those as strings.
 
-export function Counter({ initial }: { initial: number }) {
-  const [count, setCount] = useState(initial)
-  return <button onClick={() => setCount(count + 1)}>Count {count}</button>
-}
-```
+Self-referencing values are fine, because they are written as back-references.
 
-```tsx
-// app/page.tsx
-import { Counter } from './counter'
+## Reading request data
 
-export default function Page() {
-  return <Counter initial={0} />
-}
+The request prop on a page or layout is a `NextRequest` compatible object, which extends the standard Request with convenience access for cookies and headers, plus method and URL.
+
+```tsx
+const theme = request?.cookies.get('theme')?.value
 ```
 
-Files imported by a client component are client code automatically. Add `"use client"` to an imported file only when it is also rendered directly from a server component.
+Reading it keeps static routes static and marks request-dependent routes dynamic. Apps using `compat.next` can import `cookies()` and `headers()` from `next/headers` instead.
 
-Props passed from server components to client components must be serializable. pnext accepts strings, numbers, booleans, `null`, `undefined`, arrays, plain objects, `Map`, `Set`, typed arrays, and `ArrayBuffer`. Self-referencing values are fine — they are written as back-references. It rejects functions, symbols, `bigint`, and class instances, including `Date` and `URL`; pass those as strings.
+## Streaming
 
-Server Components can render Client Components. Client Components render HTML on the server, then hydrate in the browser. Client Components can wrap server-rendered children; those children stay server-rendered and only the wrapper hydrates in the browser.
+A Suspense boundary sends fallback HTML while the server finishes the content inside it.
 
-Use `dynamic({ ssr: false })` for browser-only Client Components. `dynamic({ load: 'visible' })` is browser-only by default, so it can keep Preact and the component chunk out of the initial route bundle until the island enters view.
+```tsx
+<Suspense fallback={<p>Loading comments...</p>}>
+  <Comments />
+</Suspense>
+```
 
-If the whole page needs browser-only behavior, put `"use client"` at the top of the page. Prefer smaller client components when only part of the page is interactive.
+Dev and server responses stream the fallback first, then replace it when the content is ready. Static builds wait for the final content.
 
-## Streaming
+pnext exports `Suspense` and `SuspenseProps` from `@wular/pnext` and resolves these boundaries in its own renderer, so core apps need nothing from `preact/compat`. Apps with `compat.react` can keep importing React's `Suspense`, since both identities are recognized.
+
+A segment `loading` file creates one of these boundaries automatically. See [Routing](./routing.md#convention-files).
+
+## Request cache
 
-Wrap slower server content in `<Suspense>` to show fallback HTML while the server finishes rendering the rest. The pnext renderer resolves these boundaries itself, so core apps use pnext's own `Suspense` — no `preact/compat` involved. Apps with `compat.react` can keep importing React's `Suspense`; both identities are recognized.
+`cache()` dedupes repeated work inside one render or route-handler request.
 
 ```tsx
-import { Suspense } from '@wular/pnext'
+import { cache } from '@wular/pnext/cache'
 
-async function Comments() {
-  const comments = await getComments()
-  return <CommentList comments={comments} />
-}
+export const getPost = cache(async (id: string) =>
+  db.post.findUnique({ where: { id } }),
+)
+```
 
-export default function Page() {
+Calls with the same arguments share one result. The cache is cleared between requests, so it never shares data across users. It is not a persistent data cache, and it should not be imported from Client Components.
+
+## Root layout
+
+The root layout owns the document. One with a default component must return `<html>` and `<body>`. One that only exports metadata gets a document shell from pnext. For the head itself, see [Metadata](./metadata.md).
+
+```tsx
+import type { LayoutProps } from '@wular/pnext'
+
+export default function Layout({ children }: LayoutProps) {
   return (
-    <Suspense fallback={<p>Loading comments...</p>}>
-      <Comments />
-    </Suspense>
+    <html lang="en">
+      <body>{children}</body>
+    </html>
   )
 }
 ```
 
-Dev and server responses can stream the fallback first, then replace it when the server content is ready. Static builds wait for the final content.
+## Experimental: partial prerendering and cacheComponents
+
+A page that uses request data and exports `experimental_ppr` produces a static shell with postponed Suspense content that is resumed for the request. The renderer represents postponed work with a `PostponeError`, so wrap that content in Suspense rather than handling the error yourself.
+
+`cacheComponents` requires `compat.next` and is set in the loaded Next configuration. It makes the shell-and-resume path the default, and turns request APIs into values that postpone when first awaited inside Suspense during prerendering: `cookies()`, `headers()`, `connection()`, route params, search params, and `io()`. The `io()` helper comes from the compat API and has no effect unless cacheComponents is enabled.
+
+Cache lifetimes and cache tags recorded during prerendering are honored when prebuilt output is served, including partial shells. Reach them through the Next `cacheLife()` and cache-tag APIs, which compat supplies.