@webjsdev/cli 0.10.54 → 0.10.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.54",
+  "version": "0.10.56",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {

package/templates/.agents/skills/webjs/SKILL.md

@@ -24,6 +24,8 @@ WebJs is an AI-first, web-components-first framework with **no build step**: sou
 
 **Progressive enhancement is the default architecture.** With JS off, content reads, `<a>` navigates, and a `<form action=${importedAction}>` submits to its server action. JS is opt-in per interactive behaviour. Never write a first paint that depends on hydration.
 
+**Islands, and why their size is a decision.** A WebJs page is server-rendered HTML with small interactive components embedded in it, each hydrating on its own when the browser upgrades its tag. That is the islands model, and what makes it pay is that the sea is free: static markup a page renders costs the browser nothing, because a page never hydrates. So an island is not a unit of code organisation, it is a unit of shipped JavaScript, and it should wrap the interactive part and stop. Absorbing a page's static markup into a component to keep things tidy converts free HTML into shipped JavaScript, and it takes every display-only child down with it, because a component rendered by a component that ships can no longer be elided. Size the island to the behaviour, not to the section of the design it happens to sit in. `references/components.md` has the stopping rule and a worked before/after.
+
 ## When To Use This Skill
 
 - New features or refactors touching pages, routes, actions, components, data, auth, sessions, styling, or tests
@@ -31,9 +33,44 @@ WebJs is an AI-first, web-components-first framework with **no build step**: sou
 - Answering "how should this be structured in WebJs?"
 - Finding the right export, reference doc, or default pattern for a task
 
+## Reach For The Right Primitive
+
+Scan this BEFORE deciding how to build something, while the shape of the code is still open. WebJs ships a primitive for most of the jobs below, and the mistake to guard against is rarely choosing badly between them. It is that the primitive never comes to mind at all, so the React-shaped version gets hand-rolled in its place. That version compiles, passes `webjs check`, and ships, so nothing catches it. The "reflex to resist" column is what the hand-rolled version usually looks like.
+
+Rows point rather than explain. The reference is the authority on the rule, and it is the durable half: the demo lives in the scaffold gallery, which an app deletes with `npm run gallery:clear` once it has outgrown it.
+
+| I need to... | Reach for | Reflex to resist | Reference | Demo |
+| --- | --- | --- | --- | --- |
+| add a URL, static or with a dynamic segment | a file at `app/<path>/page.ts`, `[id]` for a param | registering the route in a table or config | `references/routing-and-pages.md` | `app/features/routing` |
+| abandon a render because something is missing or not allowed | throw `notFound()` / `forbidden()` / `unauthorized()` | returning an error object and branching in the template | `references/routing-and-pages.md` | `app/features/boundaries` |
+| set a page's title, description, or social preview | `export const metadata` or `generateMetadata()` | writing `<head>` tags in the page | `references/routing-and-pages.md` | `app/features/metadata` |
+| make part of the page respond to a click or hold state | a `WebComponent` custom element | expecting the page's own markup to hydrate | `references/components.md` | `app/features/components` |
+| render a keyed list, or swap one node when state changes | `repeat()` / `watch()` from `/directives` | re-rendering the component or diffing by hand | `references/components.md` | `app/features/directives` |
+| get server data into a component's first paint | `async render()` awaiting an action | fetching in `connectedCallback`, which SSR never calls | `references/components.md` | `app/features/async-render` |
+| call server code from the browser | import the `'use server'` function and call it | hand-writing `fetch()` against an endpoint | `references/data-and-actions.md` | `app/features/server-actions` |
+| expose JSON to a caller outside the app | `route.ts` with named `GET` / `POST` exports | a server action, which is the in-app path | `references/routing-and-pages.md` | `app/features/route-handler` |
+| write data from a form, JS off included | `<form action=${importedAction}>` | an `@submit` handler calling `fetch()` | `references/data-and-actions.md` | `app/features/forms` |
+| make a mutation feel instant | `optimistic()` | a manual try-catch that restores a cached copy | `references/optimistic-ui.md` | `app/features/optimistic-ui` |
+| navigate without a full page reload | nothing, the router is already on | importing or configuring a router | `references/client-router-and-streaming.md` | `app/features/client-router` |
+| cross-fade a navigation instead of snapping | the `view-transition` meta, via page metadata | animating the swap yourself | `references/client-router-and-streaming.md` | `app/features/view-transitions` |
+| show tokens or progress as the server produces them | an action returning an async generator | polling, or a socket for a one-shot answer | `references/client-router-and-streaming.md` | `app/features/streaming` |
+| change ONE element after a write | `<webjs-stream>` | redrawing the whole list around it | `references/client-router-and-streaming.md` | `app/features/stream` |
+| paint the page before a slow region is ready | `<webjs-suspense>` with a fallback | blocking the whole page on the slow await | `references/client-router-and-streaming.md` | `app/features/suspense` |
+| refresh one region on its own, with no navigation | `<webjs-frame>` | a stateful component that fetches and re-renders | `references/client-router-and-streaming.md` | `app/features/frames` |
+| hold a live two-way connection | a `WS()` route export plus `connectWS()` | polling on an interval | `references/client-router-and-streaming.md` | `app/features/websockets` |
+| push one update to every client on a socket path | `broadcast()` | every client polling for changes | `references/client-router-and-streaming.md` | `app/features/broadcast` |
+| add login and a signed-in-only route | `createAuth` plus a redirect in the page | rolling password hashing and session cookies | `references/auth-and-sessions.md` | `app/features/auth` |
+| remember something per visitor across requests | `getSession()` on a signed cookie | a module-level map keyed by user | `references/auth-and-sessions.md` | `app/features/sessions` |
+| stop re-rendering a page identical for everyone | `export const revalidate` | caching by hand in a module variable | `references/built-ins.md` | `app/features/caching` |
+| read config or a secret at runtime | `process.env` server-side, `WEBJS_PUBLIC_` for the browser | importing a config module into a component | `references/built-ins.md` | `app/features/env` |
+| stop one caller hammering an endpoint | the `rateLimit()` middleware | counting requests inside the handler | `references/built-ins.md` | `app/features/rate-limit` |
+| accept an upload and serve it back | `FileStore` plus a streaming route | buffering the file in memory or writing to `public/` | `references/built-ins.md` | `app/features/file-storage` |
+| keep the app usable offline | the opt-in service worker | caching responses in `localStorage` | `references/service-worker.md` | `app/features/service-worker` |
+| see these composed in one real feature | the todo example app | stitching the single-feature demos together | `references/optimistic-ui.md` | `app/examples/todo` |
+
 ## Load Only The References You Need
 
-Classify the task first, then load the smallest useful reference set. Each reference starts with a "What This Covers" section; read that to confirm relevance before reading the rest. Loading more than two or three at once usually means the task is not narrowed yet.
+The table above routes by the job; this one routes by the topic, for when you already know which surface you are working on. Classify the task first, then load the smallest useful reference set. Each reference starts with a "What This Covers" section; read that to confirm relevance before reading the rest. Loading more than two or three at once usually means the task is not narrowed yet.
 
 | Task involves...                                                            | Start with                                    |
 | --------------------------------------------------------------------------- | --------------------------------------------- |
@@ -51,6 +88,7 @@ Classify the task first, then load the smallest useful reference set. Each refer
 | Auth, caching, env vars, rate limit, file storage, the `webjs` config block  | `references/built-ins.md`                      |
 | Node vs Bun, running the app, deploying, runtime-specific differences        | `references/runtime.md`                        |
 | Offline support, an asset cache, the opt-in service worker                   | `references/service-worker.md`                 |
+| Splitting a large file, or how big a module may be                            | `references/module-structure.md`              |
 | A pattern that feels like Next.js or Lit but might not transfer              | `references/muscle-memory-gotchas.md`         |
 
 Common bundles:
@@ -66,7 +104,7 @@ Common bundles:
 2. **Start from the server.** Add the page/route and its server action or query before wiring interactive UI. A page render or a `<form>` POST should already return correct HTML before any component hydrates.
 3. **Put code in the narrowest owner.** Route-local first (`modules/<feature>/`), promote to `lib/` or `components/` only when reuse is real.
 4. **Keep server-only code behind `.server.ts`.** The DB driver, secrets, and `node:*` never belong in a page, layout, or component.
-5. **Add interactivity per behaviour.** Reach for a component (and a signal or `@event`) only where the UI is genuinely interactive. A display-only component is elided from the browser.
+5. **Add interactivity per behaviour.** Reach for a component (and a signal or `@event`) only where the UI is genuinely interactive. A display-only component is elided from the browser. Then wrap the interactive part and STOP: the static markup around it stays in the page, where it costs nothing.
 6. **Validate input at the boundary.** Declare `export const validate` on an action; the RPC and `route()` boundaries run it.
 7. **Default mutations to optimistic UI** where the client can predict the result (`optimistic()` from `@webjsdev/core`).
 8. **Type every boundary from its source, never `unknown` or `any`.** The row type comes from the schema (`typeof todos.$inferSelect`), the action's input from a named `interface` and its result from `ActionResult<T>`, the routing files from `PageProps` / `LayoutProps` / `RouteHandlerContext`. `unknown` belongs on a payload nothing has vouched for yet that the next line narrows, and on a parameter of your own helper that forwards into an `html` template hole. Everywhere else, including a layout's `children`, it is a missing type. See `references/typescript.md`.
@@ -231,6 +269,7 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 ## Common Mistakes To Avoid
 
 - Treating a page or layout like a React component and expecting its markup to hydrate. It runs server-only; put interactivity in a component.
+- Promoting a whole page section to a component so that one control inside it can be interactive. The island should wrap the control and the state it reads. An oversized island ships its own JS AND un-elides every display-only component inside it, so the cost is not linear in what you moved.
 - Importing a `.server.ts` utility (no `'use server'`) directly into a shipping component. Its browser stub throws at load; reach it through a `'use server'` action.
 - Using a `static properties` block or a class-field initializer for reactive props instead of the `WebComponent({ ... })` factory.
 - Quoting an event / property / boolean hole (`@click="${fn}"`).

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -109,7 +109,11 @@ import { rateLimit } from '@webjsdev/server';
 export default rateLimit({ window: '1m', max: 60 });
 ```
 
-Options: `window` (ms or a string like `'1m'`), `max`, `key` (a string prefix or a `(req) => string` function, defaults to the client IP), `message`, `store`, `trustProxy` (honour the forwarded-IP headers; inert while `WEBJS_NO_TRUST_PROXY=1` is set, which outranks it and keeps the limiter on the framework-stamped peer). Over-limit responds `429` with `Retry-After` and `X-RateLimit-*` headers; an allowed response carries the remaining-quota headers too. For multi-instance scaling, set the global store to Redis once at startup.
+Options: `window` (ms or a string like `'1m'`), `max`, `key` (a string prefix or a `(req) => string` function, defaults to the framework-stamped socket peer), `message`, `store`, `trustProxy` (honour the forwarded-IP headers; inert while `WEBJS_NO_TRUST_PROXY=1` is set, which outranks it and keeps the limiter on the framework-stamped peer). Over-limit responds `429` with `Retry-After` and `X-RateLimit-*` headers; an allowed response carries the remaining-quota headers too. For multi-instance scaling, set the global store to Redis once at startup.
+
+**The default key is the socket PEER, which is the visitor only when the browser connects to you directly.** Deploy behind a CDN or a platform router and the peer is that proxy, so `trustProxy: true` is what a deployed limiter almost always wants. Get it wrong and nothing looks broken: a single shared proxy buckets every visitor together, and a proxy POOL (the common case) hands out one full allowance PER proxy, so the effective limit is multiplied by the pool size while `X-RateLimit-Remaining` still counts down convincingly inside each bucket. Diagnose it by sending the requests over ONE keep-alive connection, which pins them to one peer: counts that descend there but reset on a fresh connection mean you are bucketing proxies. `trustProxy: true` has one precondition, that the proxy in front strips an inbound `X-Forwarded-For` before adding its own (Cloudflare, Railway, Fly, Render, and Vercel do; nginx and Caddy only if configured), or a client can forge the header and choose its own bucket.
+
+**Behind a CDN, `trustProxy: true` alone is usually still wrong, so name the header: `rateLimit({ trustProxy: true, clientIpHeader: 'cf-connecting-ip' })`.** The default chain starts at the leftmost `X-Forwarded-For` entry, which behind Cloudflare is Cloudflare's EGRESS address rather than the visitor. Cloudflare pins one egress IP per connection, so the symptom is a limiter that counts down correctly for a button that pings on one connection and never refuses anyone who opens a new one. When `clientIpHeader` is set it is the only wire header read (falling back to the peer, then `_anon_`), a blank value falls through rather than becoming a key every visitor shares, and a comma chain is split so an appending proxy cannot mint a bucket per hop. The framework will NOT prefer `CF-Connecting-IP` on its own, because Cloudflare overwrites it, which makes it unforgeable behind Cloudflare and forgeable anywhere else: on an nginx or bare-platform deploy a client could then send it and outrank the header the real proxy set. Name the header YOUR edge sets and overwrites.
 
 ## Broadcast
 

package/templates/.agents/skills/webjs/references/client-router-and-streaming.md

@@ -2,7 +2,7 @@
 
 ## What This Covers
 
-- The automatic client router (SPA-style partial swaps), how it opts out, and programmatic `navigate()` / `revalidate()`.
+- The automatic client router (SPA-style partial swaps), how it opts out, and programmatic `navigate()` / `revalidate()` / `refreshPage()`.
 - Link prefetch with device-adaptive defaults.
 - `<webjs-frame>` partial-swap regions (WebJs's Turbo Frames).
 - View Transitions opt-in.
@@ -56,6 +56,20 @@ revalidate();                                 // clear the entire snapshot cache
 
 The router keeps a URL-keyed snapshot cache (LRU, cap 16) so Back/Forward restores instantly, then refetches in the background. Call `revalidate(path)` after a server action mutates data a cached page depends on. Wire bytes are minimized by an `X-Webjs-Have` header, so the server returns only the divergent layout fragment. Concurrent navigations abort the prior in-flight fetch, and scroll is restored on Back/Forward.
 
+**In-place refresh of the page you are on.** `refreshPage(mode)` re-renders the CURRENT url on the server and applies it without a page load.
+
+```js
+import { refreshPage } from '@webjsdev/core';
+await refreshPage();          // 'page': morph the deepest shared boundary
+await refreshPage('shell');   // replace the whole body (the layout's own markup changed)
+```
+
+It records no history entry and never scrolls, so the reader keeps their place and Back still goes to the previous page. `'page'` morphs the deepest shared boundary, so the outer layout's DOM and the hydrated state of its components survive; `'shell'` replaces the whole body, which is what a LAYOUT change needs, since a layout's own header, nav, and footer sit outside every children range and a boundary morph would leave them untouched. Component instances do not survive a `'shell'` refresh.
+
+It sends no `X-Webjs-Have`, deliberately: the server short-circuits at the first layout the client already holds, and a same-url request matches every one of them, so the response would omit the very layout that changed. It resolves `false` when it did not apply (the router is disabled, or the fetch failed), so a caller falls back to a full load.
+
+It does NOT reload changed component modules and cannot: `customElements.define` is once-per-tag and a module url is fetched once per document. A caller whose change touched browser code has to reload. This is exactly why the dev live-reload client calls `refreshPage` for a page or layout edit and `location.reload()` for a component edit (#1398, and see `references/runtime.md` for which dev modes get the refresh).
+
 **Back/Forward scroll restore vs late layout growth.** The router SUPPRESSES the browser's scroll anchoring (`overflow-anchor`) for the duration of a Back/Forward restore, then puts it back. The saved offset was recorded against the page at its SETTLED height, while the DOM the restore swaps in is still shorter until its components upgrade and render. Without the suppression the browser treats that late growth as content appearing above a reader and adds it to the offset the router just replayed, so the reader lands BELOW where they left (the reported case was 763px, exactly the height a page gained after its swap). What follows for an app:
 
 - **Do not write your own scroll restore.** A `popstate` listener that calls `scrollTo`, a saved offset in `sessionStorage`, a `scrollIntoView` on a remembered element: all of them fight the router, which already set `history.scrollRestoration = 'manual'` and is the sole authority on scroll during a navigation. If Back lands in the wrong place, that is a framework bug to report, not something to patch in app code.
@@ -110,6 +124,10 @@ A prefetch issues a real GET, so any mutating endpoint MUST be a POST or a `<for
 
 **The cache is ANCHOR-VALIDATED, not just URL-keyed (#1114).** A prefetched fragment is a reduced response: the request carries `X-Webjs-Have` (the boundaries the client already holds) and the server returns only the divergent part from the deepest boundary it short-circuited on. That boundary is the fragment's ANCHOR, and the fragment applies to any live DOM that still offers it with the same route-key. So on consume the router checks the anchor, not the whole `have` string: a root-anchored fragment survives an unrelated navigation and stays a cache hit, while one anchored at `/docs` is discarded once you leave /docs, because applying it would hand the swap a tree sharing no boundary with the live DOM, which correctly degrades to a full page load. A discard costs one round-trip. The router also never prefetches the page it is already on (#1106), since that request cannot serve any later navigation and only occupies a capped cache slot; a hover's intent timer routinely fires after the click it belongs to has already swapped, which is when that happens. Both behaviours are internal; nothing to configure.
 
+**The cache also carries a FRAME dimension (#1407).** A link that drives a `<webjs-frame>` is prefetched with the same `X-Webjs-Frame` header its click will send, so the cached body is the frame subtree the swap actually needs and the click resolves with no round trip. The server marks that sliced response `X-Webjs-Frame: <id>` on the way out, and varies on the request header, so the cache keys the entry by URL plus frame id: a page fragment can never be applied into a frame region, nor a frame subtree into a page swap, and each dimension is a separate entry for one URL. A frame entry is validated differently from a page one, because a subtree carries no boundary comment to anchor on: what has to hold is that a live `<webjs-frame>` with that id is still in the document, checked at consume time. Two responses are refused outright. A body answering a framed request WITHOUT the server's marker is a whole document (a streamed render skips the slice, and so does an id absent from the output), so it is discarded rather than stored under either key. The REFUSAL is remembered though, in a small memo kept outside the fragment cache, so a link on a streaming route re-asks about once per TTL instead of on every hover, without occupying a cache slot a real fragment could use (that memo set is itself capped, so a page with many distinct refused frame links can re-ask sooner). Only a detected deploy or an in-place `refreshPage` drops those memos early, since those are the two moments the SOURCE can have changed. `revalidate()` leaves them, because it is the post-mutation api and clearing there would drop every memo on every write; a mutation CAN change a render's streamed shape (a page may render `Suspense` conditionally on fetched data), but a memo that outlives that costs one skipped warm-up for that key until the TTL runs out, which is the cheaper side of the trade. And a framed link pointing at the URL the page is already on is a frame refresh, which must show fresh bytes, so #1106 excludes it in its own dimension.
+
+One consequence to know when reading a network tab: dedupe is per dimension, so a page holding TWO links to one URL, one driving a frame and one not, warms both and issues two speculative requests where it previously issued one. That is not redundancy, since the two responses genuinely differ and a click on either link needs its own; suppressing one would leave whichever link lost unwarmed ahead of the click, which bites hardest on touch, where `viewport` is the default and the only thing left is the `touchstart` warm at tap time. Both stay inside the same cache cap, concurrency gate, TTL, and `Save-Data` gate as every other prefetch, and the change adds no new trigger and no per-link fan-out.
+
 ## `<webjs-frame>` Partial-Swap Regions
 
 `<webjs-frame>` is WebJs's take on Turbo Frames, so most `<turbo-frame>` muscle memory transfers. It is a lazy, URL-addressable region that swaps on its own, driven by a link or form targeting its id, and it ships zero component JS. Use it for a region that loads or refreshes INDEPENDENTLY of a full-page navigation (a marketing widget, tabbed UI, a filtered results panel), which a page or layout cannot express.
@@ -118,7 +136,7 @@ A prefetch issues a real GET, so any mutating endpoint MUST be a POST or a `<for
 html`<webjs-frame id="activity">…contents…</webjs-frame>`
 ```
 
-On click the router walks `closest('webjs-frame')` from the target. If a frame is found and the response carries a matching `<webjs-frame id>`, the swap is scoped to that frame's children, and the server returns ONLY that subtree.
+On click the router walks `closest('webjs-frame')` from the target. If a frame is found and the response carries a matching `<webjs-frame id>`, the swap is scoped to that frame's children, and the server returns ONLY that subtree. A link that drives a frame participates in link prefetch like any other, in that frame's own dimension (#1407), so a hovered or viewport-warmed frame link swaps on click with no round trip. A `<webjs-frame src>` SELF-load is the exception: it neither reads nor keeps that cache, since asking a frame to load its own src is a freshness request rather than a hover being followed. See the prefetch section above for the frame dimension's rules.
 
 **External targeting.** A trigger does not have to be nested inside the frame. An `<a>` or `<form>` carrying `data-webjs-frame="<id>"` drives that frame from anywhere (an explicit `data-webjs-frame` wins over the enclosing-frame default). `data-webjs-frame="_top"` is a reserved token forcing a full-page navigation that breaks out of the frame.
 

package/templates/.agents/skills/webjs/references/components.md

@@ -101,6 +101,44 @@ NavDrawer.register('nav-drawer');
 
 This repo's own website is the worked example. Before commit `b80de906` the docs drawer and the header menu were exactly the first shape, and every accessibility bug their tests now pin came out of the split. `website/components/docs-drawer.ts` and `website/components/site-nav-menu.ts` are the second shape, and `website/AGENTS.md` records the app-level version of these rules under "What stays inline script in the root layout".
 
+## Sizing an island: own the behaviour, not the section
+
+The ownership rules above answer "what must not be split apart". They do NOT answer "how much to pull in", and read alone they push in one direction only: rule 1 says that if you are reaching for a selector, write the component that renders that markup instead. Applied without a stopping rule, that argument never terminates, because there is always more surrounding markup a component could render.
+
+Here is the stopping rule. **A component owns the markup its own behaviour reads or writes.** Static markup that no handler touches, no state change re-renders, and no template hole depends on belongs to the page, not to the island.
+
+This is a byte-cost rule, not a taste one. A page never hydrates, so markup it renders is free in the browser. Markup an island renders is not: the island's module is fetched, `@webjsdev/core` comes with it, and on upgrade the component re-renders, replacing the server's DOM for that subtree. Moving static markup across that boundary converts free HTML into shipped JavaScript that reproduces markup the server already sent.
+
+```ts
+// TOO BIG. One button's worth of behaviour, a whole page's worth of markup.
+class ProductPage extends WebComponent({ product: prop<Product>(Object) }) {
+  render() {
+    return html`
+      <h1>${this.product.name}</h1>
+      <p>${this.product.description}</p>
+      <spec-table .rows=${this.product.specs}></spec-table>
+      <button @click=${() => addToCart(this.product.id)}>Add to cart</button>
+      <review-list .reviews=${this.product.reviews}></review-list>
+    `;
+  }
+}
+```
+
+```ts
+// RIGHT SIZE. The page renders the static markup. The island is the button.
+class AddToCart extends WebComponent({ productId: String }) {
+  render() {
+    return html`<button @click=${() => addToCart(this.productId)}>Add to cart</button>`;
+  }
+}
+```
+
+The first version ships three modules instead of one: itself, plus `<spec-table>` and `<review-list>`, which were display-only and elidable until a shipping component rendered them (see "Display-only elision" below). The second ships one small module, and the heading, description, spec table, and reviews stay HTML the browser never pays for.
+
+**How to tell, on a component you are about to write.** Walk its template and ask of each element: does a handler in this class touch it, does a state or property change alter it, or does it sit in a template hole? If the answer is no for all three, that element is a passenger. A template that is mostly passengers is an island that wants splitting, and the split is usually "hoist the static markup back to the page and keep the interactive fragment".
+
+**The exception, and it is a real one.** Markup that is static *today* but is the thing a near-term behaviour will read is fine to keep, because the alternative is a component that reaches outward for it later, which is what rule 1 forbids. Judge the behaviour you are building, not one you are speculating about. When those genuinely collide, ownership wins over bytes: a coherent component that ships a little extra markup beats a split feature that a selector holds together.
+
 ## Reactive properties: the base-class factory
 
 Reactive properties are declared by passing their shape into `WebComponent({ ... })`. The types flow automatically to `this.<prop>`, so there is NO `static properties` block and NO `declare` line (a `static properties` block throws at runtime, caught by `no-static-properties`).
@@ -356,6 +394,8 @@ A component that does no client-side work renders the same SSR'd HTML with or wi
 - the dynamic slot READ surface (`slotchange`, `assignedNodes` / `assignedElements` / `assignedSlot`); merely RENDERING a `<slot>` does not ship (the SSR output carries the placed children, so a display-only slotted wrapper is byte-identical without its JS; native-write liveness is consumer-driven and the consumer's tag reference forces the ship)
 - being rendered by a component that itself ships
 
+That last blocker is the one to DESIGN around rather than merely inspect, because it is the only one that is not about the component you are looking at. Elision propagates downward from whatever ships, so the size of your islands decides how much of the tree stays elidable. Ten display-only components rendered by a page are ten modules the browser never fetches. The same ten rendered by one oversized interactive wrapper all ship, and nothing about any of them changed. This is why "Sizing an island" above is a byte-cost rule and not a tidiness preference.
+
 A bare `async render()` (no other signal, light DOM) is elided too: the SSR'd data is the complete first paint. Force shipping with `static interactive = true` when interactivity is invisible to static analysis. `static shadow = true` always ships (Declarative Shadow DOM re-attaches only during parsing). Turn elision off app-wide with `{ "webjs": { "elide": false } }` or `WEBJS_ELIDE=0`.
 
 ### What `static interactive = true` does and does not rescue
@@ -414,4 +454,4 @@ A `WebComponent` inherits `HTMLElement` (browser) or an `ElementShim` (SSR) plus
 - HTMLElement / Element: `title`, `id`, `slot`, `role`, `hidden`, `dir`, `lang`, `translate`, `draggable`, `tabIndex`, `className`, `dataset`, `remove`, `closest`, `matches`, `focus`, `blur`, `click`, `append` / `prepend`, `before` / `after`. Rename (`postTitle`, `removeItem`, `handleClick`).
 - WebComponent base: `render`, `update`, `requestUpdate`, `updated` / `firstUpdated`, `willUpdate` / `shouldUpdate`, `connectedCallback`, `renderError` / `renderFallback`, `addController` / `removeController`, `updateComplete` (#1021: there is no WebJs slot API to override; slots are native). Only override one deliberately, with its exact signature; never repurpose the name for app logic.
 
-Framework-private fields are underscore-prefixed (`_renderRoot`, `_connected`, `_changedProperties`, `_updatePromise`, `_isUpdating`); never declare a prop or field that matches one. Safe, non-inherited names: `label`, `open`, `count`, `value`, `name`, `items`, `todos`, `active`, `variant`, `size`, `checked`, `selected`, `heading`, `message`, `status`. When in doubt, grep the base surface in `node_modules/@webjsdev/core/src/component.js`.
+Framework-private fields are underscore-prefixed (`_renderRoot`, `_connected`, `_changedProperties`, `_updatePromise`, `_isUpdating`); never declare a prop or field that matches one. Safe, non-inherited names: `label`, `open`, `count`, `value`, `name`, `items`, `todos`, `active`, `variant`, `size`, `checked`, `selected`, `heading`, `message`, `status`. When in doubt, grep the base surface in `node_modules/@webjsdev/core/src/component.js` and its sibling `component/` directory, where the class body actually lives.

package/templates/.agents/skills/webjs/references/module-structure.md

@@ -0,0 +1,229 @@
+# Module structure: file size, design principles, and splitting a large module
+
+Read this before splitting a large source file, and before arguing about how
+big a module is allowed to be.
+
+Two things live here. The first is what "well structured" means in this repo,
+which is mostly judgment rather than a number. The second is the mechanical
+procedure for barrelling a large module into a directory, which is NOT judgment:
+it has a small number of failure modes that are silent, and every one of them
+has bitten this codebase already.
+
+---
+
+## Design principles: judgment, not a checker
+
+SOLID, DRY, and KISS apply here the way they apply anywhere. They are prose
+guidance, followed by judgment, and deliberately NOT enforced by `webjs check`.
+That split is the same one the rest of the project uses: `webjs check` carries
+correctness rules only (code that is wrong to ship), and anything a sensible
+project could reasonably do differently stays a convention.
+
+What they mean in practice, in a buildless framework whose source IS what runs:
+
+- **Single responsibility** is about what a module OWNS, not how long it is. A
+  module owns one concern when you can state that concern in a sentence without
+  the word "and". `router-client/prefetch.js` owns speculative fetching. It is
+  584 lines, and it is one responsibility.
+- **DRY applies to knowledge, not to text.** Two identical lines that would
+  change for different reasons are not duplication. A constant that appears in
+  three places IS, which is why this repo has drift guards that read one copy
+  and assert it against another (see the guard section below).
+- **KISS beats cleverness in a framework more than in an app.** The source is
+  the documentation surface for the AI agents that use WebJs, and it ships
+  unbundled to be read. An indirection that saves five lines and costs a reader
+  a jump is a bad trade here.
+- **Dependency direction matters more than dependency inversion.** Modules layer
+  downward: constants at the bottom, then pure helpers, then orchestration.
+  Nothing imports upward. This is not architectural taste, it is what keeps ESM
+  cycles out (see below). Two subsystems are genuinely mutually recursive and
+  cannot layer, the client router (a navigation fetches, the fetch swaps, the
+  swap upgrades, an upgraded element navigates) and light-DOM slots (projecting
+  installs the interceptors, an intercepted mutation re-projects). Those two are
+  named in `test/architecture/import-cycles.test.mjs`, which fails on any THIRD
+  cycle, so the rule holds everywhere it can.
+
+---
+
+## File size: target 800, ceiling around 1000
+
+**A source module targets 800 lines and should stay around 1000 at the most.**
+The ceiling is approximate on purpose. A module at 1040 is fine; one at 1900
+needs either a split or a named exemption (below), and the question to ask at
+that size is which responsibility it has picked up rather than how many lines
+it has. A barrel is exempt entirely, because its length is a function of how
+many names it re-exports.
+
+**Where this number comes from.** It was set by measuring the frameworks this
+project takes its cues from, not by picking a round figure:
+
+| Module | Lines |
+|---|---|
+| `lit/packages/lit-html/src/lit-html.ts` | 2303 |
+| `lit/packages/reactive-element/src/reactive-element.ts` | 1754 |
+| `vite/packages/vite/src/node/optimizer/index.ts` | 1487 |
+| `vite/packages/vite/src/node/server/index.ts` | 1447 |
+
+Every one of them draws its seams by responsibility and lets the orchestration
+entry stay large. None of them enforces a line count.
+
+**A much smaller cap is a bad trade, and this repo has the measurement.**
+Splitting ten modules into about ninety produced three bindings that needed
+accessors because ESM forbids assigning an imported binding, one dropped import
+that threw only inside a deferred callback, one symbol identity swap that
+silently broke slot forwarding, and three drift guards that broke or would have
+passed vacuously. Four of those six were invisible to `npm test`. Every module
+boundary is a place where those failures can happen, so boundaries are worth
+adding for cohesion and worth nothing when added to hit a number.
+
+There is also a runtime cost. In dev the browser fetches core source files
+individually rather than the bundle, so N modules is N requests at one more
+level of import-graph depth.
+
+**The ceiling is measured with a RAW line count** (the number `wc -l` prints,
+the number you see when you open the file), because that is how #1365 specified
+it and because a metric a reader cannot reproduce by looking at the file invites
+argument about the metric instead of the module. The tension with dense
+documentation is real: this repo's comment style can put a well-factored module
+at twice its code size, and a raw ceiling must never become a reason to delete
+explanation. The answer to that tension is the exemption list, not a different
+metric.
+
+**There is deliberately NO CI guard for this.** A line-count gate is a proxy
+metric that fights cohesion: it reds forever on a generated data table like
+`html-entities.js`, and it has to carry an exemption list that rots. So the
+ceiling is a REVIEW-TIME check, not a test. Measure it when you split something:
+
+```sh
+find <the tree you produced> -name '*.js' -exec wc -l {} + | awk '$1 > 1000 && $2 != "total"'
+```
+
+**A module that genuinely cannot or should not go under the ceiling gets a
+NAMED exemption**, argued in the PR that produces it, with its measured size and
+its reason. The three exemptions the #1365 split carries show what a valid
+reason looks like:
+
+- **lit parity** (`component/lifecycle.js`): the file tracks lit's
+  `reactive-element.ts`, which lit keeps WHOLE at 1754 lines, and the project's
+  standing decision is to keep lit-derived code close to lit rather than
+  restructure it.
+- **mutual recursion** (`render-client/parts.js`): the apply and instance group
+  calls back into itself, so a real split creates the import cycle the D4 rule
+  forbids, and the escape (a runtime dispatch registry) is a worse trade.
+- **a single closure over shared request state** (`dev/handler.js`): splitting
+  means threading that state through a context object, a high-risk rewrite of
+  every app's boot path for zero behaviour gain.
+
+Note what a valid reason is NOT: "it is mostly comments." If a module is over
+the ceiling only because it is well documented, that is a signal the ceiling is
+being measured too literally, not grounds for an exemption. Say why the CODE
+cannot be split, or split it.
+
+---
+
+## Splitting a module into a barrel plus a directory
+
+The naming rule, settled once for the whole framework: **the original file keeps
+its path and becomes the barrel, and its parts land in a sibling directory named
+after it.** So `packages/core/src/slot.js` stays, and its parts go in
+`packages/core/src/slot/`. Do NOT rename the barrel to match a public export
+subpath. The `package.json` `exports` map, the hand-written `.d.ts` overlays and
+their two guard tests, the docs pages that print importmap examples, and every
+relative test import all key off the current path.
+
+### The rule that matters most
+
+**A split is a MOVE, not a rewrite.** Retyping a function while relocating it is
+how a refactor with a green export surface ships behaviour changes. Move the
+lines verbatim. The only edits a move should produce are the `export ` keyword
+where a declaration now crosses a module boundary, and the generated import
+lines.
+
+### Where mutable module state goes
+
+A module-scope `let` goes in the module that WRITES it, not the module that
+looks like its topical home. ESM import bindings are read-only, so a module
+cannot assign a binding it imported.
+
+When two modules genuinely write the same binding, the owner exposes a
+one-statement accessor and the other module calls it:
+
+```js
+// scroll.js owns the counter.
+export let restoreGeneration = 0;
+export function bumpRestoreGeneration() { restoreGeneration += 1; }
+
+// navigator.js reads the live binding and calls the accessor to write.
+import { restoreGeneration, bumpRestoreGeneration } from './scroll.js';
+```
+
+Keep importing the binding itself wherever it is READ. Dropping it from the
+import list while a read site survives leaves a free variable, which throws only
+when that line executes. In the client router that meant a Back-button scroll
+restore silently landing at offset 0, with every node test still green.
+
+### Cycles and TDZ
+
+Layer the modules and never import upward. Node tolerates an import cycle, but
+reading a `const` or `class` binding during the cycle's evaluation phase throws
+a TDZ `ReferenceError` at module load, and in a minified browser bundle that is
+a blank page rather than a test failure.
+
+Where a back edge is unavoidable, resolve it by calling a function at call time
+rather than reading a binding at module scope.
+
+### Symbol identity
+
+`Symbol('x')` mints a unique value. `Symbol.for('x')` looks one up in the global
+registry by string. They are never interchangeable, and substituting one for the
+other produces a value that no existing object carries, so every lookup quietly
+returns `undefined`. Import the symbol from the module that created it.
+
+### Drift guards read source files by path
+
+This repo has guard tests that `readFileSync` a source file and grep it for a
+constant, to pin two copies of a value against each other. Barrelling a file
+breaks every one of them, and breaks them in two different ways:
+
+- an `assert.match` fails on its own precondition, which is loud and fine;
+- an `assert.doesNotMatch` starts passing **vacuously**, which is silent and is
+  the reason this is written down.
+
+After any split, grep the test tree for reads of the file you just barrelled and
+point each guard at the barrel PLUS every module beneath it.
+
+### Verification, in order
+
+```sh
+# 1. Export surface is identical, in BOTH directions. `added` must be empty too:
+#    a behaviour-preserving split adds no public surface.
+node --input-type=module -e "
+  const before = await import('/tmp/before.js');
+  const after  = await import('./packages/core/src/<file>.js');
+  const A = Object.keys(before).sort(), B = Object.keys(after).sort();
+  console.log(JSON.stringify({
+    missing: A.filter((k) => !B.includes(k)),
+    added:   B.filter((k) => !A.includes(k)),
+  }));
+"
+
+# 2. Every code line survived. Normalize away comments and the `export ` prefix,
+#    then diff. Anything left is a line the split CHANGED, and each one needs a
+#    reason in the commit message.
+
+# 3. The module loads at all (catches a TDZ throw introduced by a cycle).
+node --input-type=module -e "await import('./packages/core/index-browser.js')"
+node --input-type=module -e "await import('./packages/core/index.js')"
+
+# 4. Rebuild dist BEFORE any e2e or Bun run, which resolve the built bundle and
+#    would otherwise test the pre-split code and pass vacuously.
+node scripts/build-framework-dist.js
+
+# 5. The browser suite is MANDATORY for a renderer, router, component, or slot
+#    split. Those defects are post-hydration: the export surface is unchanged,
+#    the SSR bytes are unchanged, and node tests stay green.
+npm test && npm run test:browser
+```
+
+Step 5 is not optional and not a formality. Of the two silent defects this
+codebase has hit from splitting, both were caught by the browser suite alone.

package/templates/.agents/skills/webjs/references/muscle-memory-gotchas.md

@@ -202,7 +202,7 @@ Export `GET` / `POST` / etc. as named async functions `(request, { params }) =>
 
 ### `middleware.ts` is per-segment and chainable, not one matcher config
 
-The file stays `middleware.ts`, NOT Next 16's renamed `proxy.ts`. WebJs middleware is in-process, chainable, and per-segment (the Remix / Koa model). There is no `export const config = { matcher }` and no single-file restriction. The default export is `async (req, next) => Response`: return a Response to short-circuit, or call `next()` and post-process. Colocate `app/admin/middleware.ts` next to the admin routes and it runs for that subtree only. An optional root `middleware.ts` runs on every request, outermost to innermost.
+The file stays `middleware.ts`, NOT Next 16's renamed `proxy.ts`. WebJs middleware is in-process, chainable, and per-segment (the Remix / Koa model). There is no `export const config = { matcher }` and no single-file restriction. The default export is `async (req, next) => Response`: return a Response to short-circuit, or call `next()` and post-process. Colocate `app/admin/middleware.ts` next to the admin routes and it runs for that subtree only. An optional root `middleware.ts` runs on every app request, outermost to innermost. Some requests are answered before it and never reach it, and the RULE is what to remember, not the list: anything the listener shell or the framework's pre-analysis stage answers bypasses root middleware, and everything routed with the app reaches it. That covers WebSocket upgrades bound for a `route.ts` exporting `WS`, the dev SSE stream at `/__webjs/events`, and the framework's own `/__webjs/*` runtime assets and probes; in DEV only it also covers `/public/*` plus the `/sw.js` / `/offline.html` root remaps and `/favicon.ico`, so a stylesheet is never queued behind the dev startup analysis. In production those static files go through root middleware normally. **`webjs.redirects` and `webjs.trailingSlash` are the case intuition gets wrong**: you configure them, but the framework resolves them ahead of middleware, so a 308 from a redirect rule is answered without root middleware running (redirect in the middleware instead when it has to observe those requests). Server actions go the other way: they are routed with the app, so middleware DOES run for an action call, which is what lets you gate actions with auth or rate limiting.
 
 ### No `<Link>`, no `next/navigation`, no `next/*` libraries
 

package/templates/.agents/skills/webjs/references/routing-and-pages.md

@@ -18,6 +18,30 @@ Pages and layouts run **only on the server** to produce HTML. They do NOT hydrat
 
 `route.ts` is the one routing file that is NOT isomorphic: a server-only HTTP handler, never shipped to the client.
 
+### How much of the page belongs in the component
+
+"Put every interactive behaviour in a component" is not "put the section containing it in a component". Because a page never hydrates, the markup it renders costs the browser nothing, so a page that keeps its static content and delegates only the interactive fragment is both the cheapest and the conventional shape:
+
+```ts
+// app/products/[id]/page.ts
+export default async function Product({ params }: PageProps<'/products/[id]'>) {
+  const product = await getProduct(params.id);
+  return html`
+    <article>
+      <h1>${product.name}</h1>
+      <p>${product.description}</p>
+      <spec-table .rows=${product.specs}></spec-table>
+
+      <add-to-cart product-id=${product.id}></add-to-cart>
+
+      <review-list .reviews=${product.reviews}></review-list>
+    </article>
+  `;
+}
+```
+
+Only `<add-to-cart>` ships. `<spec-table>` and `<review-list>` are display-only, so the framework elides them and the browser fetches neither. Wrapping the whole article in a `<product-page>` component to "own the page" would ship all three, because a component rendered by a component that ships can no longer be elided. The sizing rule and a before/after are in `components.md` under "Sizing an island".
+
 ## Pages (`app/**/page.ts`)
 
 The default export is a possibly-async function receiving `{ params, searchParams, url, actionData }`. It returns a `TemplateResult`; it never calls `render()` itself.
@@ -187,8 +211,18 @@ Refusals worth knowing: `formaction=${fn}` is supported on a `<button>` anywhere
 
 - `error.ts` default-exports `({ error, ...ctx }) => TemplateResult`; catches sibling-page and deeper render errors, innermost wins (prod sends only `error.message`).
 - `loading.ts` wraps the sibling page in `Suspense` with an immediately-flushed fallback.
-- `not-found.ts` / `forbidden.ts` / `unauthorized.ts` render the nearest matching boundary for the thrown control-flow signal.
-- Root-only (in `app/` exactly): `global-error.ts` is the app-wide catch-all after nested `error` boundaries are exhausted and renders its OWN `<!doctype><html><body>` (returned verbatim, so keep it static HTML with no components or hydration). `global-not-found.ts` renders for an unmatched-anywhere URL when no `not-found` matches.
+- `not-found.ts` / `forbidden.ts` / `unauthorized.ts` render the nearest matching boundary for the thrown control-flow signal, and receive the same ctx a page does (`params`, `searchParams`, `url`).
+- **Every one of those boundaries renders INSIDE the layouts at and above its own segment** (#1298), so it carries the keyed `wj:children` pairs and a client-router navigation into a failing page stays a SOFT navigation with the surrounding chrome and its hydrated state intact. A layout deeper than the boundary is not rendered (it never rendered on the way in), and its module is not in the boundary's boot script; the boundary's own module IS. Since a boundary sits inside its own segment's layout, it cannot catch that layout, matching Next's `layout -> error -> page` hierarchy. What happens next differs by path, and the difference is worth knowing:
+
+- On the **500 path**, a throwing layout is handled by the next `error.{js,ts}` OUT: the walk tries each boundary in the chain, innermost first, and a layout that throws fails every attempt whose wrapped set contains it, so control ends at `global-error` (or the default 500 page) when they are exhausted.
+- On the **404 / 403 / 401 paths** there is NO outward walk. Each renders the one nearest boundary, so a throwing layout degrades that response to a chrome-less standalone render of the boundary with no boot script, keeping its status. A control-flow throw from a wrapped layout there (an auth-gate layout calling `redirect('/login')`) is discarded rather than honoured, deliberately: the status is already decided and the boundary page is the answer to that request.
+
+A genuine layout crash is reported to `onError` (and to the dev overlay on the 404 / 403 / 401 paths, where nothing else claimed the frame) rather than being swallowed. Repeats of the SAME cause within one request collapse to a single report, because one shared layout can fail every boundary attempt (and, when the layout is what threw, arrives again as the error that produced the 500). The key is the STAGE plus the error's name, message and construction site: the stack below that site records how the throw was reached and differs on every re-render, so it cannot be part of the key, and the stage is what keeps `global-error`'s own crash from being swallowed by a boundary that failed through the same helper. Two DIFFERENT failures are both reported, and anything whose key cannot be derived safely (a non-Error throw) is always reported rather than risking a drop. A control-flow sentinel never is, since it is routing rather than a crash.
+
+The BOUNDARY FILE's own crash (it throws, or fails to import at all) is reported the same way, and its response body follows the framework's standard rule for a thrown error: shown in dev, withheld in prod, where the page carries only its status. A thrown message is not author-controlled and may name a driver, a path or a connection string, so it does not reach the client; sanitizing the response never means losing the failure.
+
+Two further consequences: a layout that fetches runs its fetch again on a boundary response, and a `<webjs-suspense>` inside a wrapped layout shows its fallback, because a boundary response is buffered so its status is final before the first byte. A 404 for a URL that matched NO route has no chain to wrap in and stays a bare document.
+- Root-only (in `app/` exactly): `global-error.ts` is the app-wide catch-all after nested `error` boundaries are exhausted and renders its OWN `<!doctype><html><body>` (returned verbatim, so keep it static HTML with no components or hydration). That verbatim document is exactly why it is the one boundary left UNWRAPPED: a second shell would nest inside the root layout's, wrapping it would re-run the code that just threw, and with no boot script it could not soft-swap anyway. `global-not-found.ts` renders for an unmatched-anywhere URL when no `not-found` matches.
 
 Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments and default-export a possibly-async function; `sitemap()` / `sitemapIndex()` from `@webjsdev/server` serialize spec-valid XML.
 

package/templates/.agents/skills/webjs/references/runtime.md

@@ -35,8 +35,13 @@ Three seams pick a runtime-specific implementation, all inside the framework, no
 | Hot reload | `node --watch` | `bun --hot` |
 | WebSocket | the `ws` library | native `Bun.serve` + a bridge adapter |
 | 103 Early Hints | yes | no (`Bun.serve` has no informational-response API) |
+| Dev edit to a page / layout | full reload (the `node --watch` restart replaces the process) | refreshes IN PLACE, no reload (#1398) |
 | Reverse-proxy headers | `X-Forwarded-Proto` / `X-Forwarded-Host` honored | same |
 
+**The in-place dev refresh (#1398) needs the server process to SURVIVE the edit,** which is the whole of the Node-versus-Bun difference in that row. A page or layout never hydrates, so a freshly rendered page is the complete truth for it and the client router can swap it in without a reload, keeping scroll and (for a page edit) the hydrated state of components outside the changed region. The server classifies the changed file and puts the verdict on the live-reload event, so this needs a process that is still alive to do the classifying.
+
+Bun's `bun --hot` invalidates modules in place without restarting, so it gets the refresh. Node's `bun --hot` equivalent is `node --watch`, which RESTARTS the process on a change under `app`, `components`, `modules`, `lib`, or `actions`, or to a root `middleware.{ts,js,mts,mjs}`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE that watched set (`db/schema.server.ts`, a `webjs.dev.watch` content dir), and running `npm run dev -- --no-hot`, which keeps the server in one process on either runtime. A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
+
 The 103 Early Hints gap costs only a small first-load latency edge where an edge proxy forwards the 103, never correctness. The `modulepreload` hints still ship in the document head on both runtimes.
 
 Behind a TLS-terminating proxy (Railway, Fly, Render, Cloudflare, nginx), both shells rewrite the request URL from `X-Forwarded-Proto` / `X-Forwarded-Host`, so `ctx.url` in a page, `req.url` in a `route.{js,ts}` handler, and every absolute URL you build from either carry the ORIGINAL scheme and host rather than the internal `http://container` hop. A comma-separated chain (a CDN in front of a load balancer) takes the value closest to the client, only `http` and `https` are accepted as a scheme, and a malformed host is ignored rather than failing the request. This was Bun-only broken before #1090, which shipped an `http://` `og:image` on an HTTPS site.

package/templates/gallery/app/features/boundaries/page.ts

@@ -51,6 +51,17 @@ export default function BoundariesExample() {
         <code class="font-mono">not-found.ts</code> (404).
       </li>
     </ul>
+    <p class="text-muted-foreground text-sm">
+      Follow the first three links and notice what does NOT happen: the page
+      does not reload. A boundary renders inside the layouts at and above its
+      own segment, so the surrounding chrome survives and the navigation stays
+      a soft one. Two cases still reload, both for the same reason (there is no
+      shared shell to swap into): the fourth link, whose URL matches no route
+      at all, so there is no layout chain to render the
+      <code class="font-mono">not-found.ts</code> inside; and
+      <code class="font-mono">global-error.ts</code>, which owns its whole
+      document.
+    </p>
     <p class="text-muted-foreground text-sm">
       <code class="font-mono">forbidden()</code> is for an authenticated user who
       lacks permission (403); <code class="font-mono">unauthorized()</code> is for

package/templates/gallery/app/features/client-router/page.ts

@@ -26,7 +26,14 @@ export default function ClientRouterExample() {
       <a href="/features/client-router/second" class="${buttonClass()} no-underline">Go to page two</a>
       <a href="/" class="text-muted-foreground no-underline font-medium text-sm hover:text-foreground transition-colors">Home</a>
     </div>
-    <p class="text-muted-foreground text-sm mt-6">Or drive it from JS with <code class="font-mono">navigate()</code> / <code class="font-mono">revalidate()</code>:</p>
+    <p class="text-muted-foreground text-sm mt-6">
+      Rendered on the server at
+      <code class="font-mono">${new Date().toISOString().slice(11, 19)}</code> UTC.
+      This page function runs only on the server, so this stamp changes on every
+      render, which is what makes <code class="font-mono">refreshPage()</code>
+      below visible.
+    </p>
+    <p class="text-muted-foreground text-sm mt-6">Or drive it from JS with <code class="font-mono">navigate()</code> / <code class="font-mono">revalidate()</code> / <code class="font-mono">refreshPage()</code>:</p>
     <router-controls></router-controls>
     <p class="text-muted-foreground text-sm mt-6">
       Opt out app-wide with <code class="font-mono">{ "webjs": { "clientRouter": false } }</code>,