@wular/pnext 0.0.1 → 0.0.3

package/reference/data/bench.json

@@ -0,0 +1,513 @@
+{
+  "run": {
+    "date": "2026-08-20",
+    "machine": "CI — Blacksmith 4 vCPU (Intel Xeon), 16 GB RAM, Ubuntu 22.04 x64",
+    "bun": "1.3.10",
+    "next": "16.2.12",
+    "runs": "5 per metric (first discarded), medians reported"
+  },
+  "fixtures": [
+    {
+      "id": "hello",
+      "label": "hello-world",
+      "blurb": "A single page."
+    },
+    {
+      "id": "ssr",
+      "label": "ssr",
+      "blurb": "A server-rendered site."
+    },
+    {
+      "id": "dashboard",
+      "label": "dashboard",
+      "blurb": "A mid-size admin app — 30 routes, 18 client islands."
+    }
+  ],
+  "metrics": [
+    {
+      "id": "dev-ready",
+      "label": "Dev server ready",
+      "category": "dev",
+      "phase": "cold",
+      "rows": {
+        "hello": [
+          56.4,
+          "56.4 ms",
+          212.3,
+          "212.3 ms",
+          3.76
+        ],
+        "ssr": [
+          56,
+          "56.0 ms",
+          212.8,
+          "212.8 ms",
+          3.8
+        ],
+        "dashboard": [
+          57.1,
+          "57.1 ms",
+          246.4,
+          "246.4 ms",
+          4.31
+        ]
+      }
+    },
+    {
+      "id": "dev-first-page",
+      "label": "Dev first page HTML",
+      "category": "dev",
+      "phase": "cold",
+      "rows": {
+        "hello": [
+          79.9,
+          "79.9 ms",
+          993.5,
+          "993.5 ms",
+          12.44
+        ],
+        "ssr": [
+          93.5,
+          "93.5 ms",
+          1043.3,
+          "1043.3 ms",
+          11.16
+        ],
+        "dashboard": [
+          127,
+          "127.0 ms",
+          1285.8,
+          "1285.8 ms",
+          10.12
+        ]
+      }
+    },
+    {
+      "id": "dev-warm",
+      "label": "Dev warm request (p50 of 7)",
+      "category": "dev",
+      "phase": "warm",
+      "rows": {
+        "hello": [
+          3,
+          "3.0 ms",
+          14,
+          "14.0 ms",
+          4.69
+        ],
+        "ssr": [
+          16.5,
+          "16.5 ms",
+          26.4,
+          "26.4 ms",
+          1.6
+        ],
+        "dashboard": [
+          21.6,
+          "21.6 ms",
+          34.1,
+          "34.1 ms",
+          1.58
+        ]
+      }
+    },
+    {
+      "id": "hmr",
+      "label": "HMR save → visible",
+      "category": "dev",
+      "phase": "warm",
+      "rows": {
+        "hello": [
+          21.9,
+          "21.9 ms",
+          44.8,
+          "44.8 ms",
+          2.04
+        ],
+        "ssr": [
+          264.3,
+          "264.3 ms",
+          68.3,
+          "68.3 ms",
+          0.26
+        ],
+        "dashboard": [
+          300.4,
+          "300.4 ms",
+          97.6,
+          "97.6 ms",
+          0.32
+        ]
+      }
+    },
+    {
+      "id": "build-wall",
+      "label": "Production build (wall)",
+      "category": "build",
+      "phase": "cold",
+      "rows": {
+        "hello": [
+          291.3,
+          "291.3 ms",
+          2569.4,
+          "2569.4 ms",
+          8.82
+        ],
+        "ssr": [
+          310.5,
+          "310.5 ms",
+          2738.8,
+          "2738.8 ms",
+          8.82
+        ],
+        "dashboard": [
+          637.5,
+          "637.5 ms",
+          4566.3,
+          "4566.3 ms",
+          7.16
+        ]
+      }
+    },
+    {
+      "id": "prod-start",
+      "label": "Prod start (ready)",
+      "category": "build",
+      "phase": "cold",
+      "rows": {
+        "hello": [
+          60.7,
+          "60.7 ms",
+          110.9,
+          "110.9 ms",
+          1.83
+        ],
+        "ssr": [
+          57.1,
+          "57.1 ms",
+          105.5,
+          "105.5 ms",
+          1.85
+        ],
+        "dashboard": [
+          55.6,
+          "55.6 ms",
+          128.8,
+          "128.8 ms",
+          2.32
+        ]
+      }
+    },
+    {
+      "id": "prod-warm",
+      "label": "Prod warm request (p50 of 7)",
+      "category": "build",
+      "phase": "warm",
+      "rows": {
+        "hello": [
+          0.6,
+          "0.6 ms",
+          1.2,
+          "1.2 ms",
+          2.05
+        ],
+        "ssr": [
+          0.5,
+          "0.5 ms",
+          1.3,
+          "1.3 ms",
+          2.5
+        ],
+        "dashboard": [
+          0.5,
+          "0.5 ms",
+          1.7,
+          "1.7 ms",
+          3.41
+        ]
+      }
+    },
+    {
+      "id": "dev-rss",
+      "label": "Dev server RSS (ready + 7 warm)",
+      "category": "memory",
+      "phase": "warm",
+      "rows": {
+        "hello": [
+          130.8,
+          "130.8 MB",
+          536.4,
+          "536.4 MB",
+          4.1
+        ],
+        "ssr": [
+          151.3,
+          "151.3 MB",
+          553.6,
+          "553.6 MB",
+          3.66
+        ],
+        "dashboard": [
+          168.6,
+          "168.6 MB",
+          577.1,
+          "577.1 MB",
+          3.42
+        ]
+      }
+    },
+    {
+      "id": "build-rss",
+      "label": "Prod build peak RSS",
+      "category": "memory",
+      "phase": "cold",
+      "rows": {
+        "hello": [
+          124.2,
+          "124.2 MB",
+          455.8,
+          "455.8 MB",
+          3.67
+        ],
+        "ssr": [
+          136.8,
+          "136.8 MB",
+          456.6,
+          "456.6 MB",
+          3.34
+        ],
+        "dashboard": [
+          188,
+          "188.0 MB",
+          569,
+          "569.0 MB",
+          3.03
+        ]
+      }
+    },
+    {
+      "id": "prod-rss",
+      "label": "Prod server RSS (ready + 7 warm)",
+      "category": "memory",
+      "phase": "warm",
+      "rows": {
+        "hello": [
+          85.2,
+          "85.2 MB",
+          85.7,
+          "85.7 MB",
+          1.01
+        ],
+        "ssr": [
+          86,
+          "86.0 MB",
+          85.9,
+          "85.9 MB",
+          1
+        ],
+        "dashboard": [
+          87.3,
+          "87.3 MB",
+          90.6,
+          "90.6 MB",
+          1.04
+        ]
+      }
+    },
+    {
+      "id": "install",
+      "label": "Framework install size",
+      "category": "payload",
+      "phase": "static",
+      "rows": {
+        "hello": [
+          7.1,
+          "7.1 MB",
+          420.7,
+          "420.7 MB",
+          59.14
+        ],
+        "ssr": [
+          7.1,
+          "7.1 MB",
+          420.7,
+          "420.7 MB",
+          59.14
+        ],
+        "dashboard": [
+          7.1,
+          "7.1 MB",
+          420.7,
+          "420.7 MB",
+          59.14
+        ]
+      }
+    },
+    {
+      "id": "js-gzip",
+      "label": "First-page client JS (gzip)",
+      "category": "payload",
+      "phase": "static",
+      "rows": {
+        "hello": [
+          2.19,
+          "2.19 KB",
+          141.78,
+          "141.78 KB",
+          64.67
+        ],
+        "ssr": [
+          11.39,
+          "11.39 KB",
+          142.03,
+          "142.03 KB",
+          12.47
+        ],
+        "dashboard": [
+          15.26,
+          "15.26 KB",
+          144.85,
+          "144.85 KB",
+          9.5
+        ]
+      }
+    },
+    {
+      "id": "js-raw",
+      "label": "First-page client JS (raw)",
+      "category": "payload",
+      "phase": "static",
+      "rows": {
+        "hello": [
+          4.43,
+          "4.43 KB",
+          502.47,
+          "502.47 KB",
+          113.36
+        ],
+        "ssr": [
+          27.36,
+          "27.36 KB",
+          502.78,
+          "502.78 KB",
+          18.37
+        ],
+        "dashboard": [
+          38.51,
+          "38.51 KB",
+          507.42,
+          "507.42 KB",
+          13.18
+        ]
+      }
+    },
+    {
+      "id": "js-files",
+      "label": "First-page JS files",
+      "category": "payload",
+      "phase": "static",
+      "rows": {
+        "hello": [
+          3,
+          "3",
+          5,
+          "5",
+          1.67
+        ],
+        "ssr": [
+          4,
+          "4",
+          6,
+          "6",
+          1.5
+        ],
+        "dashboard": [
+          6,
+          "6",
+          9,
+          "9",
+          1.5
+        ]
+      }
+    },
+    {
+      "id": "zero-island",
+      "label": "Zero-island route client JS",
+      "category": "payload",
+      "phase": "static",
+      "rows": {
+        "hello": [
+          4.43,
+          "4.43 KB",
+          502.47,
+          "502.47 KB",
+          113.36
+        ],
+        "ssr": [
+          4.46,
+          "4.46 KB",
+          502.47,
+          "502.47 KB",
+          112.56
+        ]
+      }
+    }
+  ],
+  "headlines": [
+    {
+      "label": "Dev server ready",
+      "direction": "faster",
+      "value": "3.8–4.3×"
+    },
+    {
+      "label": "First page, cold",
+      "direction": "faster",
+      "value": "10–12×"
+    },
+    {
+      "label": "Warm request (dev)",
+      "direction": "faster",
+      "value": "1.6–4.7×"
+    },
+    {
+      "label": "Production build",
+      "direction": "faster",
+      "value": "7.2–8.8×"
+    },
+    {
+      "label": "Warm request (prod)",
+      "direction": "faster",
+      "value": "2–3.4×"
+    },
+    {
+      "label": "Dev server memory",
+      "direction": "less",
+      "value": "3.4–4.1×"
+    },
+    {
+      "label": "First-page client JS (gzip)",
+      "direction": "less",
+      "value": "9.5–65×"
+    },
+    {
+      "label": "Framework install size",
+      "direction": "smaller",
+      "value": "59×",
+      "detail": "7.1 MB vs 420.7 MB"
+    }
+  ],
+  "clientRuntimes": [
+    {
+      "name": "router-prefetch-only",
+      "raw": "473 B",
+      "gzip": "348 B",
+      "brotli": "283 B"
+    },
+    {
+      "name": "combined-router-hydrator",
+      "raw": "10.47 KB",
+      "gzip": "4.47 KB",
+      "brotli": "4.07 KB"
+    }
+  ]
+}

package/reference/performance.md

@@ -1,12 +1,35 @@
 # 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
+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):
+
+|                             |                   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** |
+
+¹ 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.
+
+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.
+
+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`).
+
+- 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: 3 (first discarded), medians reported
+- Runs per metric: 5 (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.
@@ -15,13 +38,19 @@ two columns render the same app from the same source.
 
 | 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 |
+| 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.73x |
+| 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 |
 
@@ -31,13 +60,19 @@ Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
 
 | 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 |
+| 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 |
 
@@ -47,14 +82,20 @@ Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
 
 | 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 |
+| 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.
 
@@ -69,7 +110,7 @@ Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
 
 | Target | Limit | Measured | Status |
 | --- | --- | --- | --- |
-| Dev cold start, ssr fixture (pnext) | <= 150 ms | 93.8 ms | PASS |
+| 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 |
@@ -83,11 +124,28 @@ Ratio is Next.js / pnext, so above `1.00x` means pnext is ahead.
   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.
+  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

package/src/api/router/runtime.ts

@@ -437,11 +437,18 @@ async function warmPageAssets(html: string) {
   for (const link of doc.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"][href]')) {
     preloadStylesheet(link.getAttribute('href') ?? '');
   }
+  warmEntryChunks(doc);
+  const entrySrc = entryScriptSrc(doc);
+  if (entrySrc) await importEntry(entrySrc);
+}
+
+// The destination entry's static chunks, kicked off before the entry itself is imported: without
+// this the browser only discovers them after the entry parses, so every chunk the split put behind
+// the entry costs another serial round trip on the navigation's critical path.
+function warmEntryChunks(doc: Document) {
   for (const link of doc.querySelectorAll<HTMLLinkElement>('link[rel="modulepreload"][href]')) {
     preloadModule(link.getAttribute('href') ?? '');
   }
-  const entrySrc = entryScriptSrc(doc);
-  if (entrySrc) await importEntry(entrySrc);
 }
 
 function preloadStylesheet(href: string) {
@@ -4676,6 +4683,7 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // Warm the new document's assets before touching the current one: the swap
   // then paints styled content immediately instead of flashing unstyled HTML.
   const entrySrc = entryScriptSrc(doc);
+  warmEntryChunks(doc);
   const [entryModule] = await Promise.all([
     entrySrc ? importEntry(entrySrc) : Promise.resolve(null),
     addStylesheets(doc),