@wular/pnext 0.0.1

package/reference/dev.md

@@ -0,0 +1,69 @@
+# Dev Server
+
+`pnext dev` starts a Bun HTTP server for local development.
+
+## CLI
+
+```txt
+pnext dev [directory] [--port 3000] [--hostname 127.0.0.1]
+pnext build [directory] [--adapter vercel] [--verbose]
+pnext start [directory] [--port 3000] [--hostname 127.0.0.1]
+pnext analyze [route] [directory] [--brotli] [--files] [--json]
+pnext typegen [directory]
+```
+
+`analyze` takes a route (`/users/[id]` or a concrete path like `/users/ada`) to report on that route only.
+
+Add `@wular/pnext` as a package dependency and put `pnext` in package scripts:
+
+```json
+{
+  "devDependencies": {
+    "@wular/pnext": "^0.0.0"
+  },
+  "scripts": {
+    "dev": "pnext dev",
+    "build": "pnext build",
+    "start": "pnext start",
+    "analyze": "pnext analyze"
+  }
+}
+```
+
+The package exposes a `pnext` binary. Package managers make it available inside script `PATH`.
+
+## Processes
+
+pnext processes are labelled in Activity Monitor and `ps`: `pnext dev` shows
+up as a single `pnext-dev` server process, `pnext build` as `pnext-build`, and
+esbuild's service process as `pnext-esbuild`. Tailwind and PostCSS run in a
+worker thread inside the server process, not as child processes.
+
+The dev server re-execs itself — same pid — when its memory passes
+`PNEXT_DEV_MAX_RSS_MB` (default 2048). The esbuild service is stopped and
+respawned past `PNEXT_DEV_MAX_ESBUILD_RSS_MB` (default 1024).
+
+## Responsibilities
+
+- Scan the route tree.
+- Render matching pages on request.
+- Serve static assets from `public/`.
+- Build client route entries on demand with esbuild.
+- Cache generated client entries in `.pnext/cache`.
+- Notify the browser of route-tree changes through `/__pnext/events`.
+
+## Cache
+
+Client entry cache keys include the route id and source content hash. Cached entries are stored below `.pnext/cache/client`.
+
+## Reload Events
+
+The dev server exposes a server-sent events stream at `/__pnext/events`. Browser pages reload when app files change.
+
+## Typechecking
+
+The dev server does not typecheck in the request path. Run package lint or typecheck commands separately. `pnext build` under `compat.next` typechecks off-thread, in parallel with bundling, and reports it on its own line.
+
+## Server Adapter
+
+Use `pnext build --adapter vercel` to write Vercel Build Output at `.vercel/output`. Static pages and static `GET` route-handler outputs are emitted as files. Everything dynamic — pages, route handlers, and `proxy.ts` — is served by a single `_pnext` function on Vercel's Bun runtime; the proxy's `config.matcher` patterns become routes into it.

package/reference/env.md

@@ -0,0 +1,40 @@
+# Environment Variables
+
+pnext loads `.env*` files from the project root, not from `src/`.
+
+Variables already set on `process.env` win. Missing variables are loaded in this order:
+
+1. `.env.$NODE_ENV.local`
+2. `.env.local` except when `NODE_ENV` is `test`
+3. `.env.$NODE_ENV`
+4. `.env`
+
+If `NODE_ENV` is not set, `pnext dev` uses `development`; other commands use `production`.
+
+## Browser Variables
+
+Browser bundles inline only:
+
+- `process.env.NODE_ENV`
+- `process.env.NEXT_PUBLIC_*`
+- `process.env.PNEXT_PUBLIC_*`
+
+Other variables stay server-only. Server Components, layouts, route handlers, and proxy can read them through `process.env`.
+
+## Variable References
+
+Values can reference earlier environment variables:
+
+```env
+API_HOST=api.example.com
+NEXT_PUBLIC_API_URL=https://$API_HOST
+PORT=${APP_PORT:-3000}
+```
+
+`${VAR}` and `${VAR:-fallback}` both work. A variable already on `process.env` wins over the file's own value.
+
+Escape `$` when it should be literal:
+
+```env
+PRICE=\$10
+```

package/reference/metadata.md

@@ -0,0 +1,86 @@
+# Metadata
+
+Core metadata takes no request input, so it resolves at build time. `pnext build` evaluates metadata objects, `metadata()`/`viewport()` functions, and metadata route code, and `pnext start` serves the prebuilt head for static routes without recomputing it per request.
+
+Use `compat.next` for Next.js request-time metadata APIs such as `generateMetadata()`, `generateViewport()`, streaming metadata, `headers()`, `cookies()`, and full `next/og` behavior.
+
+## Page and Layout Exports
+
+Pages and layouts can export `metadata` as an object:
+
+```tsx
+import type { Metadata } from '@wular/pnext';
+
+export const metadata: Metadata = {
+  title: 'About',
+  description: 'About the team',
+};
+```
+
+They can also export `metadata()` as a no-arg build-time function:
+
+```tsx
+export async function metadata() {
+  const site = await getSiteMetadata();
+  return {
+    title: site.title,
+    description: site.description,
+  };
+}
+```
+
+Metadata is resolved from root layout to page. Nearer segments override or extend earlier segments.
+
+pnext follows the Next.js metadata field shapes for common fields such as `title`, `description`, `metadataBase`, `openGraph`, `twitter`, `robots`, `icons`, `manifest`, `alternates`, `verification`, `appleWebApp`, `appLinks`, and `other`. Use the [Next.js metadata fields reference](https://nextjs.org/docs/app/api-reference/functions/generate-metadata#metadata-fields) for the full field schema.
+
+## Viewport
+
+Pages and layouts can export `viewport` as an object or a build-time function:
+
+```tsx
+import type { Viewport } from '@wular/pnext';
+
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  themeColor: '#0b0b0b',
+};
+```
+
+Use `compat.next` for `generateViewport()` with route props.
+
+## File Conventions
+
+Core supports static metadata files in route segments:
+
+- `icon`, `apple-icon`, `opengraph-image`, `twitter-image` — `.ico`, `.jpg`, `.jpeg`, `.png`, `.svg`, `.gif`, or `.webp`, optionally numbered (`icon2.png`)
+- `sitemap.xml`
+- `favicon.ico`, `robots.txt`, `manifest.json`, `manifest.webmanifest` — app root only
+
+Static files are copied during `pnext build` and served from the built public output. Image and sitemap files apply to their segment and its descendants; the root-only files are global.
+
+## Code Metadata Files
+
+Core also supports code variants of each, in `.tsx`, `.ts`, `.jsx`, `.js`, or `.mjs`: `icon`, `apple-icon`, `opengraph-image`, `twitter-image`, `sitemap`, plus root-only `robots` and `manifest`.
+
+In core, these modules run at build time. Their generated links and route outputs are stored in the build output, and `pnext start` does not recompute them during page requests.
+
+Code metadata route handlers can keep their metadata-route signatures, including `generateImageMetadata()` and `generateSitemaps()`, but core treats their results as build artifacts. Request-time variants that depend on `headers()`, `cookies()`, or dynamic request state belong in `compat.next`.
+
+## Precedence
+
+File-based metadata has higher priority than page/layout metadata for images and icons. Explicit page/layout image metadata still wins when it defines its own image list.
+
+The request path determines which segment metadata files apply. Route groups and parallel-route slot directories do not add URL path segments, but their metadata file output names are disambiguated at build time.
+
+## Static Params
+
+Core dynamic routes use `params()` for build-time param selection:
+
+```tsx
+export function params() {
+  return [{ slug: 'intro' }];
+}
+```
+
+`generateStaticParams()` is a Next compat API. In `compat.next`, pnext treats it as the fallback static params provider when a module does not export core `params()`.

package/reference/navigation.md

@@ -0,0 +1,149 @@
+# 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.
+
+## Link
+
+`<Link>` renders a normal anchor with typed route params and pnext prefetch metadata.
+
+```tsx
+import { Link } from '@wular/pnext/link';
+
+export function Nav() {
+  return (
+    <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.
+
+## Soft Navigation
+
+`<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` on `<Link>` warms the target page and its assets:
+
+- `'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.
+
+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`.
+
+## Redirects
+
+Use `notFound()` to render the nearest `not-found.tsx` fallback with a 404 response.
+
+Use `redirect()` to stop server rendering and return a redirect response. In the browser it navigates directly.
+
+```tsx
+import { redirect } from '@wular/pnext/navigation';
+
+export default async function Page() {
+  const user = await getUser();
+  if (!user) redirect('/login');
+  return <Dashboard user={user} />;
+}
+```
+
+`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.
+
+For typed dynamic redirects, build the URL with `href()`:
+
+```tsx
+import { href, redirect } from '@wular/pnext/navigation';
+
+redirect(href('/users/[id]', { params: { id: 'ada' } }));
+```
+
+## Client Hooks
+
+Client navigation hooks live in `@wular/pnext/navigation/client`.
+
+```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>
+  );
+}
+```
+
+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.
+
+`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 }`.
+
+## Dynamic Components
+
+Use `dynamic()` for lazily loaded Client Components.
+
+```tsx
+import { dynamic } from '@wular/pnext/dynamic';
+
+const Chart = dynamic(() => import('./chart').then(module => module.Chart), {
+  load: 'visible',
+});
+```
+
+For default exports, use the shorter literal form:
+
+```tsx
+const Chart = dynamic('./chart');
+```
+
+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.
+
+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.

package/reference/overview.md

@@ -0,0 +1,35 @@
+# pnext
+
+pnext is a Preact framework for file-routed applications. It keeps familiar Next-style routing and rendering semantics where they help, and diverges where pnext needs a simpler or smaller model.
+
+It renders on the server by default, passes request data through explicit props, provides strong generated route type safety, and ships client JavaScript only for components that opt into running in the browser.
+
+## Core Model
+
+- Routes live in an `app/` directory.
+- `page.tsx` files define UI routes.
+- `layout.tsx` files export metadata, viewport, and can wrap descendant pages.
+- `route.ts` files define HTTP handlers.
+- `proxy.ts` or `middleware.ts` can run before route matching.
+- `loading.tsx`, `error.tsx`, and `not-found.tsx` define route fallbacks.
+- Pages and layouts are pnext Server Components by default.
+- Server components can be async.
+- Pages without client components emit HTML without pnext client JavaScript.
+- Client Components can be loaded with `dynamic({ load: 'visible' })` and deferred until visible.
+- React compatibility mode supported via `compat.react`.
+- Next compatibility mode supported via `compat.next`.
+- Experimental React Compiler support for React-style Client Components via `compat.reactCompiler`.
+
+## References
+
+- [Config](./config.md)
+- [Routing](./routing.md)
+- [Metadata](./metadata.md)
+- [Navigation](./navigation.md)
+- [Rendering](./rendering.md)
+- [CSS](./css.md)
+- [Environment Variables](./env.md)
+- [Compatibility](./compat.md)
+- [Typegen](./typegen.md)
+- [Dev Server](./dev.md)
+- [Performance](./performance.md)

package/reference/performance.md

@@ -0,0 +1,97 @@
+# Performance
+
+Auto-generated by `bun bench` — do not edit by hand.
+
+- Date: 2026-08-17
+- Machine: Darwin 25.6.0 (arm64), Apple M1 x8
+- Bun: 1.3.6
+- Next.js: 16.2.12
+- Runs per metric: 3 (first discarded), medians reported
+
+Every fixture under `bench/fixtures/` runs unmodified on both frameworks, so the
+two columns render the same app from the same source.
+
+## Fixture: hello-world
+
+| Metric | pnext | Next.js | Ratio |
+| --- | --- | --- | --- |
+| Dev cold start (ready) | 101.8 ms | 268.2 ms | 2.63x |
+| Dev first page HTML | 82.0 ms | 1047.1 ms | 12.77x |
+| Dev warm request (p50 of 7) | 2.3 ms | 13.3 ms | 5.80x |
+| HMR save → visible | 19.7 ms | 41.7 ms | 2.11x |
+| Prod build (wall) | 302.0 ms | 3000.2 ms | 9.93x |
+| 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.73x |
+| First-page JS files | 3 | 5 | 1.67x |
+| Zero-island route client JS | 4.43 KB | 502.47 KB | 113.36x |
+
+Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
+
+## Fixture: ssr
+
+| Metric | pnext | Next.js | Ratio |
+| --- | --- | --- | --- |
+| Dev cold start (ready) | 93.8 ms | 288.1 ms | 3.07x |
+| Dev first page HTML | 103.4 ms | 1129.8 ms | 10.93x |
+| Dev warm request (p50 of 7) | 3.6 ms | 25.9 ms | 7.26x |
+| HMR save → visible | 24.6 ms | 67.1 ms | 2.73x |
+| Prod build (wall) | 372.1 ms | 3145.8 ms | 8.45x |
+| First-page client JS (raw) | 40.37 KB | 502.78 KB | 12.45x |
+| First-page client JS (gzip) | 16.13 KB | 142.03 KB | 8.80x |
+| 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) | 103.3 ms | 300.4 ms | 2.91x |
+| Dev first page HTML | 189.0 ms | 1278.9 ms | 6.77x |
+| Dev warm request (p50 of 7) | 6.7 ms | 28.4 ms | 4.22x |
+| HMR save → visible | 67.8 ms | 73.8 ms | 1.09x |
+| Prod build (wall) | 941.5 ms | 4160.1 ms | 4.42x |
+| First-page client JS (raw) | 63.26 KB | 507.42 KB | 8.02x |
+| First-page client JS (gzip) | 23.63 KB | 144.85 KB | 6.13x |
+| First-page JS files | 5 | 9 | 1.80x |
+
+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) | <= 150 ms | 93.8 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.
+- 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.
+
+## Commands
+
+```sh
+bun bench                  # every fixture, both frameworks
+bun bench/run.ts ssr       # one fixture
+bun bench/run.ts all --framework=pnext --runs=5
+```

package/reference/rendering.md

@@ -0,0 +1,127 @@
+# Rendering
+
+pnext renders on the server first and sends browser JavaScript only for interactive components.
+
+## 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.
+
+```tsx
+export default async function Page() {
+  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`.
+
+## Document
+
+Use the root `layout.tsx` to own `<html>` and `<body>`:
+
+```tsx
+import type { LayoutProps } from '@wular/pnext';
+
+export default function Layout({ children }: LayoutProps) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+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.
+
+### Metadata
+
+Pages and layouts can export core build-time `metadata`, `metadata()`, `viewport`, and `viewport()`. See [Metadata](./metadata.md) for the full core metadata model.
+
+## Request Cache
+
+Use server-only `cache()` to dedupe repeated server work during one render or route-handler request:
+
+```tsx
+import { cache } from '@wular/pnext/cache';
+
+export const getPost = cache(async (id: string) => {
+  return db.post.findUnique({ where: { id } });
+});
+```
+
+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.
+
+## Client Components
+
+Add `"use client"` to components that need browser APIs, hooks, or event handlers.
+
+```tsx
+// app/counter.tsx
+'use client';
+
+import { useState } from 'preact/hooks';
+
+export function Counter({ initial }: { initial: number }) {
+  const [count, setCount] = useState(initial);
+  return <button onClick={() => setCount(count + 1)}>Count {count}</button>;
+}
+```
+
+```tsx
+// app/page.tsx
+import { Counter } from './counter';
+
+export default function Page() {
+  return <Counter initial={0} />;
+}
+```
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+## Streaming
+
+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.
+
+```tsx
+import { Suspense } from '@wular/pnext';
+
+async function Comments() {
+  const comments = await getComments();
+  return <CommentList comments={comments} />;
+}
+
+export default function Page() {
+  return (
+    <Suspense fallback={<p>Loading comments...</p>}>
+      <Comments />
+    </Suspense>
+  );
+}
+```
+
+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.