@wular/pnext 0.0.4 → 0.0.7

package/reference/navigation.md

@@ -1,149 +1,109 @@
 # Navigation
 
-pnext navigation APIs are split by runtime so server routes do not import browser router code.
-
-## Typed Hrefs
-
-Use `href()` when building URLs outside JSX.
-
-```tsx
-import { href } from '@wular/pnext/navigation';
-
-const userHref = href('/users/[id]', {
-  params: { id: 'ada' },
-  search: { tab: 'runs' },
-});
-```
-
-Dynamic params are checked from generated route types. Routes without params do not take a `params` object.
+Links, prefetching, redirects, and the client router. Server and browser APIs sit in separate entry points, so a server route never pulls in router code meant for the browser.
 
 ## Link
 
-`<Link>` renders a normal anchor with typed route params and pnext prefetch metadata.
+Renders a normal anchor. The href is a route template, and params are checked against the generated route types, so a wrong name or a missing param fails TypeScript. Use a plain anchor for external URLs and for links you do not want typed.
 
 ```tsx
-import { Link } from '@wular/pnext/link';
+import { Link } from '@wular/pnext/link'
 
 export function Nav() {
   return (
-    <Link href="/users/[id]" params={{ id: 'ada' }} search={{ tab: 'runs' }}>
+    <Link
+      href="/users/[id]"
+      params={{ id: 'ada' }}
+      search={{ tab: 'runs' }}
+    >
       Ada
     </Link>
-  );
+  )
 }
 ```
 
-Supported props:
-
-- `href`: generated route path.
-- `params`: required for dynamic routes.
-- `search`: query params.
-- `hash`: hash fragment.
-- `prefetch`: `false`, `'intent'`, `'visible'`, or `'load'`.
-- `replace`: marks the navigation as history replace.
-- `scroll={false}`: preserves scroll on client navigation.
-- `onNavigate`: client-only same-origin navigation callback that can call `preventDefault()`.
-- `onPrefetchStart` / `onPrefetchFinish`: fire when this link's prefetch begins and settles, in every prefetch mode.
-
-Use a normal `<a>` for external URLs or intentionally untyped links.
+| Prop                                  | Value                                                         |
+| ------------------------------------- | ------------------------------------------------------------- |
+| `href`                                | Generated route path.                                         |
+| `params`                              | Required for dynamic routes.                                  |
+| `search`                              | Query params.                                                 |
+| `hash`                                | Hash fragment.                                                |
+| `prefetch`                            | `false`, `'intent'`, `'visible'`, or `'load'`.                |
+| `replace`                             | Marks the navigation as a history replace.                    |
+| `scroll`                              | `false` preserves scroll on client navigation.                |
+| `onNavigate`                          | Same-origin client callback that can call `preventDefault()`. |
+| `onPrefetchStart`, `onPrefetchFinish` | Fire when this link's prefetch begins and settles.            |
 
-## Soft Navigation
+## Prefetching
 
-`<Link>` clicks and `router.push()`/`router.replace()` swap the page in place instead of reloading the document, so shared chunks and CSS are never re-downloaded. Back and forward stay soft and restore scroll. Cross-origin targets, non-HTML responses, and fetch failures fall back to a full page load.
+Prefetch warms the target page and its assets. Set the mode per link with the `prefetch` prop, as in `<Link prefetch="intent">`.
 
-`prefetch` on `<Link>` warms the target page and its assets:
+- `'visible'` is the default, and fires when the link enters the viewport.
+- `'intent'` fires on hover, touch, or focus.
+- `'load'` fires as soon as the link renders.
+- `false` never prefetches. Pair it with `router.prefetch(href)` for manual control.
 
-- `'intent'` (default): on hover, touch, or focus.
-- `'visible'`: when the link enters the viewport.
-- `'load'`: as soon as the link renders.
-- `false`: never; pair with `router.prefetch(href)` for manual control.
+The app-wide default can be set with the `prefetch` field in `pnext.config.ts`, described in [Config](./config.md).
 
-Prefetched pages expire after 30 seconds and each navigation refetches on the next visit, so pages always reflect fresh server state. Prefetch is a no-op under `pnext dev`.
+Requests use low network priority. At most four run at once, though the hover-intent lane allows up to twelve. The core fallback expiry is five minutes. Prefetch does nothing in development.
 
-## Redirects
+## Soft navigation
 
-Use `notFound()` to render the nearest `not-found.tsx` fallback with a 404 response.
+Link clicks and router pushes swap the page in place instead of reloading the document, so shared chunks and CSS are never re-downloaded. Back and forward stay soft and restore scroll. Cross-origin targets, non-HTML responses, and fetch failures fall back to a full page load.
 
-Use `redirect()` to stop server rendering and return a redirect response. In the browser it navigates directly.
+## Redirects and not found
 
 ```tsx
-import { redirect } from '@wular/pnext/navigation';
+import { href, notFound, redirect } from '@wular/pnext/navigation'
 
-export default async function Page() {
-  const user = await getUser();
-  if (!user) redirect('/login');
-  return <Dashboard user={user} />;
-}
+redirect('/login')
+redirect('/login', 308)
+redirect(href('/users/[id]', { params: { id: 'ada' } }))
+notFound()
 ```
 
-`redirect()` returns a temporary 307 redirect on the server. `permanentRedirect()` returns 308.
-
-Client event handlers can call `redirect()` too. Keep it as the last statement, or `return redirect(...)`, because browser navigation does not synchronously stop the rest of the handler. Use `useRouter().push()` or `useRouter().replace()` when you want explicit history control.
+`redirect()` stops server rendering and returns a redirect response. Call it from pages, server components, route handlers, and any server helper used during rendering. Validate targets that come from user input.
 
-For typed dynamic redirects, build the URL with `href()`:
+The status is 307 unless you pass 303, 307, or 308. `permanentRedirect()` returns 308.
 
-```tsx
-import { href, redirect } from '@wular/pnext/navigation';
+`notFound()` renders the nearest `not-found` fallback with a 404 response.
 
-redirect(href('/users/[id]', { params: { id: 'ada' } }));
-```
+In the browser, `redirect()` navigates directly. Keep it as the last statement of an event handler, or return it, because browser navigation does not synchronously stop the rest of the handler. Use the router when you want explicit history control.
 
-## Client Hooks
+## href()
 
-Client navigation hooks live in `@wular/pnext/navigation/client`.
+Builds a typed URL outside JSX. Routes without params take no params object.
 
-```tsx
-'use client';
-
-import { useRouter, useSearchParams } from '@wular/pnext/navigation/client';
-
-export function SortButton() {
-  const router = useRouter();
-  const searchParams = useSearchParams();
-
-  return (
-    <button
-      onClick={() => {
-        const search = new URLSearchParams(searchParams.toString());
-        search.set('sort', 'asc');
-        router.replace('/products', { search, scroll: false });
-      }}
-    >
-      Sort
-    </button>
-  );
-}
+```ts
+href('/users/[id]', {
+  params: { id: 'ada' },
+  search: { tab: 'runs' },
+})
 ```
 
-Available hooks:
-
-- `useRouter()`: `push`, `replace`, `prefetch`, `refresh`, `back`, and `forward`.
-- `usePathname()`: current browser pathname.
-- `useSearchParams()`: read-only URL search params.
-- `useParams<Route>()`: current route params from the initial route state.
-- `useRoute<Route>()`: pathname, route template, params, and search params together.
-- `useLinkStatus()`: pending shape for link feedback.
+## Client hooks
 
-`push()` and `replace()` are typed like `href()`. They soft-navigate when the path or query changes and fall back to the History API for same-URL hash updates. Cross-origin targets become a full page load. `refresh()` re-fetches the current route in place. `useLinkStatus()` currently always reports `{ pending: false }`.
+Exported from `@wular/pnext/navigation/client`, for use in components marked `"use client"`.
 
-## Dynamic Components
+| Hook                 | Returns                                                       |
+| -------------------- | ------------------------------------------------------------- |
+| `useRouter()`        | `push`, `replace`, `prefetch`, `refresh`, `back`, `forward`.  |
+| `usePathname()`      | Current browser pathname.                                     |
+| `useSearchParams()`  | Read-only URL search params.                                  |
+| `useParams<Route>()` | Current route params from the initial route state.            |
+| `useRoute<Route>()`  | Pathname, route template, params, and search params together. |
+| `useLinkStatus()`    | Currently always `{ pending: false }`.                        |
 
-Use `dynamic()` for lazily loaded Client Components.
+Router pushes and replaces are typed like links. They soft-navigate when the path or query changes, and fall back to the History API for same-URL hash updates. Cross-origin targets become a full page load. Refreshing re-fetches the current route in place.
 
-```tsx
-import { dynamic } from '@wular/pnext/dynamic';
+`useSearchParams()` returns a `ReadonlyURLSearchParams`, whose mutation methods throw. Copy it before changing it.
 
-const Chart = dynamic(() => import('./chart').then(module => module.Chart), {
-  load: 'visible',
-});
-```
-
-For default exports, use the shorter literal form:
-
-```tsx
-const Chart = dynamic('./chart');
+```ts
+const search = new URLSearchParams(searchParams.toString())
+search.set('sort', 'asc')
+router.replace('/products', { search, scroll: false })
 ```
 
-Literal dynamic imports work from Server Components and Client Components. If the target module starts with `"use client"`, pnext renders it as a Client Component island; otherwise it renders on the server.
+## Auth interrupts
 
-Dynamic Client Components loaded from Server Components render HTML on the server by default and hydrate when the chunk loads. Pass `ssr: false` for browser-only output. `load: 'visible'` implies browser-only output unless `ssr: true` is set. Inside Client Components, `dynamic()` is a browser lazy loader.
+`forbidden()` and `unauthorized()` throw `PNextForbiddenError` and `PNextUnauthorizedError`, both exported from the server navigation module along with `ReadonlyURLSearchParams`. The functions are core exports, but rendering them as 403 and 401 responses needs the experimental `compat.next` auth interrupts. See [Routing](./routing.md#convention-files).

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 this
-  workspace 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,127 +1,130 @@
 # 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() {
-  const post = await getPost();
-  return <article>{post.title}</article>;
+  const post = await getPost()
+  return <article>{post.title}</article>
 }
 ```
 
-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.
-
-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`.
+A layout file does not need a default export. Use a metadata-only layout when a segment only needs to set page metadata.
 
-## 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.
+
+## Streaming
 
-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.
+A Suspense boundary sends fallback HTML while the server finishes the content inside it.
 
-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.
+```tsx
+<Suspense fallback={<p>Loading comments...</p>}>
+  <Comments />
+</Suspense>
+```
 
-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.
+Dev and server responses stream the fallback first, then replace it when the content is ready. Static builds wait for the final content.
 
-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.
+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.
 
-## Streaming
+A segment `loading` file creates one of these boundaries automatically. See [Routing](./routing.md#convention-files).
 
-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.
+## Request cache
+
+`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 } }),
+)
+```
+
+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
 
-export default function Page() {
+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.