@webjsdev/cli 0.10.56 → 0.10.57

package/lib/create.js

@@ -448,7 +448,14 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // The TypeScript compiler, for `npm run typecheck` (webjs typecheck runs
       // tsc --noEmit). Not needed at runtime (Node strips types in place), only
       // to type-check the app.
-      typescript: '^5.6.0',
+      // Must not resolve below the floor the tsconfig this same generator
+      // writes requires: `erasableSyntaxOnly` landed in TypeScript 5.8, and a
+      // 5.6 or 5.7 resolution refuses the whole config with
+      // `TS5023: Unknown compiler option`. Kept on the major the repo's own
+      // apps use, so an app and the framework that generated it type-check
+      // under the same compiler. Guarded by
+      // test/scaffolds/scaffold-typescript-floor.test.js.
+      typescript: '^6.0.3',
       '@types/node': '^24.0.0',
       '@web/test-runner': '^0.20.0',
       '@web/test-runner-playwright': '^0.11.0',

package/lib/doctor/codes.js

@@ -42,6 +42,7 @@ export const DOCTOR_CODES = {
   'vendor-gitignore': 'VENDOR_GITIGNORE',
   'webjs-versions': 'WEBJS_VERSIONS',
   'framework-resolve': 'FRAMEWORK_RESOLVE',
+  'framework-links': 'FRAMEWORK_LINKS',
   'importmap-coherence': 'IMPORTMAP_COHERENCE',
   'git-hook': 'GIT_HOOK',
   'Page/layout elision (carrier hygiene)': 'ELISION_CARRIERS',

package/lib/doctor/probes/framework-resolves.js

@@ -1,5 +1,5 @@
-import { existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
 import { createRequire } from 'node:module';
 
 /**
@@ -60,9 +60,7 @@ export function checkFrameworkResolves(appDir) {
         '@webjsdev/core cannot be resolved from this directory, and this is a git worktree with no ' +
         'node_modules. Git worktrees do not copy node_modules, so the framework is unresolvable here ' +
         'and `webjs dev` / `webjs start` would fail at SSR with a raw ERR_MODULE_NOT_FOUND.',
-      fix:
-        'Install dependencies in this worktree (`npm install`), or symlink node_modules from the ' +
-        'primary checkout (`ln -s ../<primary-checkout>/node_modules node_modules`).',
+      fix: freshWorktreeFix(appDir),
     };
   }
   if (!hasNodeModules) {
@@ -79,6 +77,184 @@ export function checkFrameworkResolves(appDir) {
     message:
       '@webjsdev/core cannot be resolved from this directory even though node_modules exists ' +
       '(a partial or corrupted install).',
-    fix: 'Reinstall dependencies (`npm install`, or remove node_modules and reinstall).',
+    fix: linkAwareReinstallFix(appDir),
+  };
+}
+
+/**
+ * Whether `dir`'s own `node_modules` is a SYMLINK, which in a linked worktree
+ * means it points at the primary checkout's tree. The remedies below branch on
+ * this, because `npm install` is the right advice when it is false and is the
+ * exact command that corrupts the primary when it is true (#1442).
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function modulesAreLinked(dir) {
+  try { return lstatSync(join(dir, 'node_modules')).isSymbolicLink(); } catch { return false; }
+}
+
+/**
+ * The `npm run worktree:link` sentence, but ONLY where that script exists.
+ *
+ * This module ships in the PUBLISHED CLI, and `bin/webjs.js` prints these
+ * remedies verbatim as the `webjs dev` / `webjs start` preflight failure. A
+ * scaffolded app has no `worktree:link` script, so naming it unconditionally
+ * sends the exact audience this check exists for (#954, a fresh app worktree)
+ * to run something that does not exist. Walk up for a package.json that really
+ * declares it, and stay silent otherwise.
+ *
+ * @param {string} appDir
+ * @returns {string} a leading-space sentence, or the empty string
+ */
+function linkScriptHint(appDir) {
+  let dir = resolve(appDir);
+  for (let i = 0; i < 8; i += 1) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+      if (pkg?.scripts?.['worktree:link']) {
+        return ' In this repo, `npm run worktree:link` does the whole setup and also repairs the shared tree.';
+      }
+    } catch { /* no package.json here, keep walking */ }
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return '';
+}
+
+/**
+ * Remedy for the #954 fresh-worktree case, which is a worktree with NO
+ * `node_modules` at all. There is no symlink in the way yet, so a real install
+ * is safe here, and this stays the app-generic advice it has always been.
+ * @param {string} appDir
+ * @returns {string}
+ */
+function freshWorktreeFix(appDir) {
+  return (
+    'Install dependencies in this worktree (`npm install`), or symlink node_modules from the ' +
+    'primary checkout (`ln -s ../<primary-checkout>/node_modules node_modules`). If you symlink, ' +
+    'never run an install through that link afterwards: it acts on the checkout that owns the ' +
+    'tree, not this one (#1442).' + linkScriptHint(appDir)
+  );
+}
+
+/**
+ * Remedy for a `node_modules` that exists but does not resolve the framework.
+ * When it is a SYMLINK, a bare `npm install` is the action that corrupts the
+ * checkout that owns the tree, so the advice has to differ.
+ * @param {string} appDir
+ * @returns {string}
+ */
+function linkAwareReinstallFix(appDir) {
+  if (modulesAreLinked(appDir)) {
+    return (
+      'node_modules here is a SYMLINK at another checkout, so do NOT run `npm install`: it would act ' +
+      'on that checkout, not this one (#1442). Either reinstall in the checkout that owns the tree, ' +
+      'or remove every node_modules symlink first, nested ones included ' +
+      '(`find . -maxdepth 5 -type l -name node_modules -delete`), and install here.' + linkScriptHint(appDir)
+    );
+  }
+  return 'Reinstall dependencies (`npm install`, or remove node_modules and reinstall).';
+}
+
+/**
+ * Classify the `@webjsdev/core` entry that `appDir` would resolve through.
+ *
+ * Walks up for the first `node_modules` carrying the package, then judges the
+ * link against the tree that PHYSICALLY owns that `node_modules`. That owner
+ * rule is the only one correct in a linked worktree: there `node_modules` is
+ * itself a symlink at the primary's, so the owning tree is the PRIMARY and a
+ * target inside it is right rather than foreign. Judging against `appDir` would
+ * report every correctly linked worktree as corrupted.
+ *
+ * @param {string} appDir
+ * @param {string} [pkg]
+ * @returns {{ state: 'absent'|'real'|'ok'|'dangling'|'foreign', entry?: string, target?: string, owner?: string }}
+ */
+export function inspectFrameworkLink(appDir, pkg = '@webjsdev/core') {
+  const parts = pkg.split('/');
+  let dir = resolve(appDir);
+  for (;;) {
+    const modules = join(dir, 'node_modules');
+    const entry = join(modules, ...parts);
+    let st = null;
+    try { st = lstatSync(entry); } catch { st = null; }
+    if (st) {
+      if (!st.isSymbolicLink()) return { state: 'real', entry };
+      let target = '';
+      try { target = readlinkSync(entry); } catch { return { state: 'real', entry }; }
+      // Resolve the target against the directory the link PHYSICALLY sits in,
+      // which is what the OS does. In a linked worktree `node_modules` is itself
+      // a symlink, so the lexical `dirname(entry)` is under the WORKTREE while
+      // the link really lives in the primary. Resolving lexically turns every
+      // correct `../../packages/core` into a worktree path and reports a healthy
+      // linked worktree as `foreign`.
+      let base = dirname(entry);
+      try { base = realpathSync(base); } catch { /* fall back to the lexical path */ }
+      const abs = resolve(base, target);
+      let owner = dir;
+      try { owner = dirname(realpathSync(modules)); } catch { /* use dir as given */ }
+      if (!existsSync(abs)) return { state: 'dangling', entry, target, owner };
+      let real = abs;
+      try { real = realpathSync(abs); } catch { /* compare the unresolved path */ }
+      let ownerReal = owner;
+      try { ownerReal = realpathSync(owner); } catch { /* compare as given */ }
+      if (real !== ownerReal && !real.startsWith(ownerReal + sep)) {
+        return { state: 'foreign', entry, target, owner: ownerReal };
+      }
+      return { state: 'ok', entry, target, owner: ownerReal };
+    }
+    const up = dirname(dir);
+    if (up === dir) return { state: 'absent' };
+    dir = up;
+  }
+}
+
+/**
+ * CHECK: framework link integrity (#1442). WARN when the `@webjsdev/core` entry
+ * in node_modules is a symlink that DANGLES or resolves OUTSIDE the tree that
+ * owns it. That is what an install run inside a linked worktree leaves behind,
+ * and it is invisible to the framework-resolve check above, which only asks
+ * whether the package resolves at all: a link into a live FOREIGN checkout
+ * resolves perfectly and silently runs another branch's framework source.
+ *
+ * Silent PASS for a real directory, a correct link, and no entry at all, so a
+ * normally installed app pays one `lstat`. WARN rather than fail, the same
+ * environment tier as the framework-resolve and version-coherence checks.
+ * @param {string} appDir
+ * @returns {DoctorResult}
+ */
+export function checkFrameworkLinks(appDir) {
+  const name = 'framework-links';
+  const r = inspectFrameworkLink(appDir);
+  if (r.state === 'absent' || r.state === 'real' || r.state === 'ok') {
+    return {
+      name,
+      status: 'pass',
+      message: 'The @webjsdev framework links resolve inside the checkout that owns them.',
+    };
+  }
+  const fix =
+    'Repoint the entry at the package inside the checkout that owns this node_modules. Do NOT run ' +
+    '`npm install` here while node_modules is a symlink: it acts on that owning checkout, not this ' +
+    'one (#1442).' + linkScriptHint(appDir);
+  if (r.state === 'dangling') {
+    return {
+      name,
+      status: 'warn',
+      message:
+        `${r.entry} is a symlink to ${r.target}, which does not exist. An install run inside a linked ` +
+        'worktree leaves these behind, and the worktree it named has since been removed.',
+      fix,
+    };
+  }
+  return {
+    name,
+    status: 'warn',
+    message:
+      `${r.entry} is a symlink to ${r.target}, which resolves OUTSIDE ${r.owner}, the checkout that ` +
+      'owns this node_modules. It resolves fine, so nothing fails, and the framework source being run ' +
+      "is another checkout's. A deliberate `npm link` produces the same shape.",
+    fix,
   };
 }

package/lib/doctor/runner.js

@@ -10,7 +10,7 @@ import { checkGitHook } from './probes/git-hook.js';
 import { checkElisionCarriers, checkElisionComponents } from './probes/elision.js';
 import { checkStaticAssetFreshness } from './probes/static-asset-freshness.js';
 import { checkUnmarkedAssetLinks } from './probes/unmarked-asset-links.js';
-import { checkFrameworkResolves } from './probes/framework-resolves.js';
+import { checkFrameworkResolves, checkFrameworkLinks } from './probes/framework-resolves.js';
 
 /**
  * @typedef {import('./codes.js').DoctorResult} DoctorResult
@@ -57,6 +57,7 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkVendorGitignore(appDir),
     checkWebjsVersions(appDir),
     Promise.resolve(checkFrameworkResolves(appDir)),
+    Promise.resolve(checkFrameworkLinks(appDir)),
     checkImportmapCoherence(appDir, opts),
     Promise.resolve(checkGitHook(appDir)),
     checkElisionCarriers(elision),

package/lib/doctor.js

@@ -53,5 +53,5 @@
 export { DOCTOR_SEVERITIES, DOCTOR_CODES, codeForName } from './doctor/codes.js';
 export { readDoctorPolicy, applyDoctorPolicy } from './doctor/policy.js';
 export { readAppBasePath } from './doctor/route-modules.js';
-export { frameworkResolves, checkFrameworkResolves } from './doctor/probes/framework-resolves.js';
+export { frameworkResolves, checkFrameworkResolves, inspectFrameworkLink, checkFrameworkLinks } from './doctor/probes/framework-resolves.js';
 export { runDoctorChecks } from './doctor/runner.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.56",
+  "version": "0.10.57",
   "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/rules/workflow.md

@@ -59,9 +59,10 @@ Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
    tsconfig), either of which would 500 the app at runtime. Everything else it
    reports is a warning that cannot fail the build. Widen or narrow the gate in
    `package.json` rather than in the workflow.
-5. Pre-merge self-review: before saying a PR is ready, run fresh-context review
-   rounds until one round finds zero issues (minimum two rounds, rotate focus).
-   Skip only for a one-line trivial change.
+
+How a PR gets REVIEWED is deliberately not specified here. Use whatever your
+team already does. WebJs has opinions about the code (the conventions above,
+`webjs check`, the test layers) and none about your review process.
 
 ## Git rules
 

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

@@ -80,6 +80,7 @@ The table above routes by the job; this one routes by the topic, for when you al
 | Server actions, mutations, queries, validation, the `ActionResult` envelope | `references/data-and-actions.md`              |
 | Sessions, login flows, route protection, `forbidden()` / `unauthorized()`   | `references/auth-and-sessions.md`             |
 | Tailwind, light-DOM tag-prefix rule, tokens, fixed headers, no-reflow layout | `references/styling.md`                        |
+| Where a repeated markup helper lives (`utils/ui/` vs `lib/`), and fragment vs display-only component | `references/styling.md`                        |
 | Client router, prefetch, frames, view transitions, Suspense streaming        | `references/client-router-and-streaming.md`   |
 | Optimistic UI for a user-facing mutation                                     | `references/optimistic-ui.md`                 |
 | The `@webjsdev/ui` component kit (a `components.json` is present): class helpers, tokens, `add` / `view`, the MCP `ui` tool | `references/ui-kit.md`                         |
@@ -122,8 +123,10 @@ app/                  ROUTING ONLY (thin adapters importing from modules/)
   error.ts loading.ts not-found.ts forbidden.ts unauthorized.ts   boundaries (nearest wins)
 middleware.ts         root middleware
 modules/<feature>/    actions/ (mutations, *.server.ts), queries/ (reads, *.server.ts),
-                      components/, utils/ (pure), types.ts
-lib/                  lib/*.server.ts server-only infra, lib/utils/ browser-safe helpers
+                      components/ (custom elements), types.ts,
+                      utils/ (pure; returns data, or an html fragment under utils/ui/)
+lib/                  lib/*.server.ts server-only infra, lib/utils/ browser-safe helpers,
+                      lib/utils/ui.ts app-wide html fragments (lib/ui/ once they grow)
 components/*.ts        shared presentational custom elements (one per file)
 db/*.server.ts        Drizzle: schema, connection
 public/*              static assets, served at /public/<name>

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

@@ -93,6 +93,8 @@ html`<link rel="stylesheet" href=${asset('/public/app.css')}>`
 
 That emits `/public/app.css?v=<hash>` in production and gets the immutable year; the same url un-marked gets a ~1h cap and can serve stale bytes from a CDN after a deploy until something purges it. `asset()` resolves on the server; the browser has no resolver and returns the path unchanged. Call it from a PAGE, LAYOUT, or metadata route, which render only on the server. Inside a component that ships to the browser it silently costs you the caching: hydration is a full client re-render, so the bare path overwrites the hashed one and the asset downloads twice. The url stays valid either way, so this is a convention rather than a `webjs check` rule (`webjs doctor` does flag the plain form, see below). Under `webjs.basePath`, include the prefix yourself (`asset('/app/public/x.css')`): the framework base-path-prefixes only the urls it emits, so an author-written url is already yours to prefix. Two more constraints: call it INSIDE the render function, because a module-scope call is a side effect the elision analyser reads as client work and it ships the whole module; and mark only files that change with a DEPLOY, because the hash is memoized for the process lifetime, so a `public/` file rewritten in place at runtime would keep its old url while being served `immutable` for a year. Off in dev, so dev output is byte-identical. Only `public/` paths resolve; anything else (and a path that fails to resolve) is returned untouched.
 
+`asset()` is a PROVIDER SEAM: `@webjsdev/server` installs the resolver at boot by importing `@webjsdev/core` and calling a setter, and that only reaches your app when both sides load the SAME copy of core. Two copies on disk are two independent sets of module-scope state, so the setter lands on one and your `asset()` reads the other, which returns bare paths and never says why. `cspNonce()` and the bound-form identity resolver behind `<form action=${fn}>` sit on the same seam and go inert together. `@webjsdev/server` therefore declares core as a PEER dependency, so npm resolves it against your app's copy and reports a genuine conflict at install time rather than nesting a second one. If you ever do end up with two (a hand-rolled install, a vendored copy), the symptom is those three features quietly doing nothing rather than any error, so reach for `npm ls @webjsdev/core` and `npm dedupe` before looking anywhere else.
+
 Forgetting it is the one real cost of opt-in, so `webjs doctor` catches it: a page, layout, or error boundary writing a plain `<link rel="stylesheet" href="/public/app.css">` gets a WARN naming the `file:line` and the fix (#1095). It reads your source and rewrites nothing, and it stays quiet about the non-marks that are deliberate: a cross-origin sheet, a `rel="icon"`, a `rel="preload"`, and any `href=${expr}` hole. Same posture as Rails (a `stylesheet_link_tag` helper over a digest manifest) and Remix (a hashed url from the build graph, surfaced through `links()`): take the fingerprint at the point the url is PRODUCED, never by rewriting a rendered document. A warning is easy to miss, so make it fatal in the app that cares: gate `UNMARKED_ASSET_LINKS` to `error` (see the doctor severity gate below) and one `npm run doctor` step in CI stops the un-versioned url reaching a deploy. The scaffold ships exactly that.
 
 It is opt-in rather than automatic because only the author knows which urls are the REQUEST. Do NOT mark a `rel="preload"` hint whose asset is actually fetched by CSS `url()`: the preload cache is keyed on the full url, so a versioned hint can never satisfy the unversioned request the stylesheet makes, and the file is fetched twice. Mark the thing that fetches, not the hint. Every cacheable response also carries a weak `ETag`, and a repeat request with a matching `If-None-Match` gets a `304 Not Modified` with no body. Unstorable (`no-store`) and streamed responses are excluded from the ETag path. A `private` response IS validated: `private` forbids SHARED storage, not validation, and the ETag hashes that response's own body, so two users with different bodies get different ETags and neither can match the other's, while two users with identical bodies are asking about identical bytes, where a 304 discloses nothing (#1140). That is what keeps the client router's partial responses cheap on a page that opted into caching; a default `no-store` page has nothing to validate either way. Dev is byte-faithful (no hashing).
@@ -216,7 +218,7 @@ An over-limit body responds `413` without buffering the whole payload.
 
 ### Doctor severity gate
 
-`webjs doctor` reports project health, and by default only a broken toolchain fails the exit. `--strict` makes EVERY warning fatal, which is unusable in CI, because four checks are environment-shaped: `GIT_HOOK` wants a local pre-commit hook a runner has no reason to have, `ENV_DRIFT` compares against a `.env` CI does not carry, `VENDOR_PIN` fetches the network, and `FRAMEWORK_RESOLVE` depends on the environment. So per-check severity is CONFIG, keyed by the stable code every result carries.
+`webjs doctor` reports project health, and by default only a broken toolchain fails the exit. `--strict` makes EVERY warning fatal, which is unusable in CI, because four checks are environment-shaped: `GIT_HOOK` wants a local pre-commit hook a runner has no reason to have, `ENV_DRIFT` compares against a `.env` CI does not carry, `VENDOR_PIN` fetches the network, and `FRAMEWORK_RESOLVE` plus `FRAMEWORK_LINKS` depend on the environment. So per-check severity is CONFIG, keyed by the stable code every result carries.
 
 ```jsonc
 { "webjs": {

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

@@ -44,17 +44,35 @@ enableClientRouter();    // turn soft navigation back on
 
 Per link, opt out with `data-no-router` (auth flows like `/logout`, OAuth redirects, print views, an experimental route with a different runtime). Cross-origin hrefs, `download`, a non-`_self` target, pure same-page hash jumps, and non-HTML extensions are auto-skipped.
 
+**Per link, keep the reader's scroll offset with `data-preserve-scroll`.** A forward navigation scrolls to top, matching what a browser does and what Next and Remix 3 do. The attribute is the escape hatch for a navigation that changes only part of what the reader is looking at: a filter, sort, or tab link whose control sits below the fold, a pager, or a form that re-renders in place with validation errors. WebJs wants it more than most, because a searchParams-only navigation already morphs the deepest shared boundary and preserves hydrated component state, so the scroll is the only thing such a navigation still throws away.
+
+```html
+<nav data-preserve-scroll>            <!-- covers every link inside -->
+  <a href="?sort=new">Newest</a>
+  <a href="?sort=top">Top</a>
+  <a href="/" data-preserve-scroll="false">Home</a>   <!-- opts back out -->
+</nav>
+<form method="post" action=${saveDraft} data-preserve-scroll>...</form>
+```
+
+It resolves through `closest()`, so one mark on a wrapping element covers every link in it (the same walk `data-webjs-frame` uses), and `data-preserve-scroll="false"` on a nearer element opts back out. On a form the lookup starts at the submitter and falls back to the form itself, so a marked form covers its own buttons whether they sit inside it or are attached from elsewhere with `form="id"`. The fallback only fills in a missing mark, so `data-preserve-scroll="false"` on a button still opts that button out of a marked form.
+
+Three things it does NOT do. A hash link still scrolls to its anchor, because the reader named a target and a named target beats a blanket preference. It is inert on a frame-targeted link, since a frame swap never writes a scroll to begin with. And it is inert with JS off, where the link is a plain `<a>` and the browser does whatever it does, so nothing about a page's correctness may depend on it.
+
+It carries the reader's CURRENT offset onto the destination; it does not restore the destination's remembered offset. Those are different features, and the second one is not something WebJs ships. So this is the wrong tool for a "back to the list" link, where the offset the reader wants is the one they had in the list, not the one they have in the article.
+
 **Programmatic navigation and cache eviction.**
 
 ```js
 import { navigate, revalidate } from '@webjsdev/core';
 await navigate('/about');                     // push history
 await navigate('/login', { replace: true });  // replace history
+await navigate('/products?sort=new', { scroll: false });  // keep the reader's offset
 revalidate('/products/123');                  // evict one URL from the snapshot cache
 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.
+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. The popstate an in-page fragment CLICK produces is absorbed rather than re-navigated (#1437), so an anchor click restores nothing and re-fetches nothing, the repeat click of one anchor included (that one REPLACES its entry rather than pushing, so it arrives with the url unchanged). The gate is PROVENANCE, the router marking the click it bowed out of and the next popstate consuming that mark, rather than any comparison of urls: a Back between two entries differing only by fragment can still need a re-render, because `getSubmitAction` prefers the raw `action` ATTRIBUTE and that carries no fragment, so a bound-submitter form declaring `action="/p"` pushes its 422 re-render at `/p` while the reader sits at `/p#sec`. A popstate with no click behind it therefore stays on the normal path, which means an ordinary Back or Forward between two fragment states still re-renders. Telling those apart would need to know whether the DOM was replaced between the two ENTRIES, which is per-entry state the router does not keep.
 
 **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.
 
@@ -70,12 +88,15 @@ It sends no `X-Webjs-Have`, deliberately: the server short-circuits at the first
 
 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).
 
+Keep the two scroll concerns apart. The Back/Forward restore below is the BROWSER's and has no per-link knob, because the offset it replays is one the browser recorded. The forward-navigation scroll-to-top is the router's own write, and `data-preserve-scroll` is its knob.
+
 **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.
+- **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 restore, which is the BROWSER's (see the next bullet) and which the router protects with a suppression window while the page settles. If Back lands in the wrong place, that is a framework bug to report, not something to patch in app code.
+- **The BROWSER restores Back/Forward scroll, not the router, and an app must not set `history.scrollRestoration = 'manual'`** (#1428). The router FORCES `history.scrollRestoration` to `auto` on start (and puts the app's own value back on `disableClientRouter()`), so setting `'manual'` yourself does not take effect while the router runs. Under `auto` the browser records a scroll position per history entry, replays it on a traverse, and composes the iOS edge back-swipe GESTURE PREVIEW from that same recorded state. The router writes no scroll on a restore at all: it reserves the recorded height (below) so the browser's replay lands on a document that can hold the offset, and that is the whole mechanism. One writer, the same model Next and Remix 3 use. Taking `manual` suppresses the recording, so every scrolled page previews BLANK for the whole gesture. That is what the router itself used to do, inherited from Turbo Drive's `assumeControlOfScrollRestoration`, and it is why Turbo still previews blank the same way: Turbo is single-writer too, but the writer is the APP. An app that sets `manual` re-breaks the preview app-wide.
 - **An app that sets `overflow-anchor` on `<html>` itself sees it overridden during a restore and restored afterwards**, including a value set inline by your own script. Setting it in a stylesheet is unaffected between restores. Nothing else on the page is touched, and the router never sets `overflow-anchor` anywhere but the root element.
 - **A new PAGE navigation ends an open window.** The window outlives its own restore on purpose (a floor, then a ceiling), so a page navigation or a page-level form submission starting inside that span closes it first, and reopens only if it earns one. Otherwise a second Back, or a click, would inherit suppressed anchoring on a page it was never meant for. A FRAME-TARGETED navigation or submission is the exception, on exactly the rule that decides frame targeting everywhere else (the enclosing frame, an explicit `data-webjs-frame="<id>"` from anywhere, or the frame's own `src`; `_top` and an unresolvable id are page navigations and do close the window). It swaps one region and leaves the page, and so the restored offset, intact, so it leaves the restore running. Closing there would hand anchoring back mid-restore and bring the double count straight back, and it needs no user input to happen, since a component upgrading in the just-restored page can drive a frame on its own.
-- **Suppression is conditional on the offset being reachable, and follows the chase onto it.** A page that has not grown yet can be too short to scroll that far, so the browser clamps to its current maximum. There the shortfall IS the growth still to come, and anchoring adding it is what carries the reader back down, so the router leaves anchoring alone. Suppressing in that case would freeze the clamp and strand the reader a full page-growth above where they left, which is this same defect pointing the other way. That case is not left to anchoring alone, though, because anchoring adds the FULL growth however far short the clamp fell, so by itself it only lands a reader who left at the very bottom. The router also CHASES the recorded offset there, re-asserting it the moment the page is tall enough to hold it, and then stopping. That is the one place the router writes scroll after the initial restore, it is scoped to the clamped path, and it stops on the same inputs that close a suppression window. It is also time-boxed, and more tightly than the window a landed restore gets: a few hundred milliseconds from the RESTORE, not the 2s ceiling, and the suppression it installs on landing shares that same deadline rather than starting a fresh one. That bound is what keeps it from moving a reader who has landed and started reading, since such a reader generates no input to cancel it and the chase cannot tell the restore settling apart from any other growth. Anchoring is left on only WHILE the offset is out of reach, which is the part that heals the clamp. The moment the chase lands on the offset it suppresses anchoring too, because the growth that made the offset reachable is rarely all of it and every later stage would otherwise be added on top of what was just written. Both halves end together on the bound. After it, the router writes no more scroll and anchoring is back on, so a component that reaches its final height later than the bound (a chart, an embed measured from its content) has its growth added and the reader drifts BELOW the offset, the same way they would without this fix at all, rather than sitting at the clamp.
+- **The recorded HEIGHT is reserved across the restore, so the offset is always reachable.** A snapshot records the page's settled `scrollHeight` alongside the offset, and the restore holds that height on the root element until the page has filled in. Without it the swapped-in markup is briefly shorter than the page it came from, the browser clamps the restore to whatever the short document allowed, and the reader lands short. The reservation removes that window rather than correcting for it afterwards, which is what retired the older catch-up that used to chase the offset as the page grew. It is released on the same settle that closes the anchoring window, on the same ceiling, and when another navigation supersedes the restore, but never on user input: releasing the height under a reader mid-scroll is the one harm an early release could do. An app's own inline `min-height` on the root is saved and put back, the same contract the anchoring window keeps.
 - **The window closes on the first real input** (`wheel`, `touchmove`, `keydown`, `pointerdown`), so a reader who starts scrolling mid-restore immediately gets normal browser anchoring back. Absent that it closes once the restore is over, which is the LATER of the restore's own background revalidation settling and a short floor, and at the latest on a 2s ceiling. The floor is load-bearing: waiting on the revalidation alone ties the window's length to network latency rather than to the growth it guards, so a server answering faster than the page renders would close it early and the reader would land low again. Suppression only ever WITHHOLDS a browser correction, it never moves the viewport, so it cannot yank someone who has taken over.
 
 Components that reach their final size only after they render (a chart, a media embed with no intrinsic dimensions, anything sized from measured content) are exactly the shape that triggers this, and they need no special handling: give them a placeholder height where you can, and let the router own the restore.
@@ -138,6 +159,14 @@ 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. 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.
 
+**A frame swap never moves the window scroll.** A page navigation scrolls to top, the way a browser does; a frame swap changes one region and leaves the rest of the document standing, the reader's scroll offset included. That holds for a nested link, an external `data-webjs-frame` trigger, a frame-targeted form submission, and a `src` self-load alike, and it holds for a `#hash` on a frame link too, which rides the URL without moving the viewport. It does NOT cover a pure fragment link whose path and query match the page it sits on, because the router never sees one: the click handler bows out before `preventDefault`, so the browser does its own native fragment jump and the window moves.
+
+**Every spelling of a fragment link is the browser's, the bare `#` included** (#1437). `href="#"` is the back-to-top idiom and it serializes with an EMPTY fragment, which reads identically to no fragment at all through `URL.hash`, so the bow-out tests the `href` for a `#` instead. A `<a href="#">Back to top</a>` therefore scrolls to top natively, inside a frame as well as outside one. `href=""` is NOT a fragment link: it resolves to the current url with the fragment REMOVED, which the spec reloads rather than jumps, so the router navigates it like any other link.
+
+The escapes are page navigations and DO scroll: `data-webjs-frame="_top"`, and an id `resolveTargetFrameId` cannot match to a live frame, which warns and degrades to a normal nav. Do not read that second one as covering a RESPONSE that lacks the requested frame (the `webjs:frame-missing` warning). There the frame resolved and the nav stayed frame-scoped, so the offset holds and only the panel is left unchanged. Turbo's `autoscroll` opt-in, which scrolls the frame itself into view on swap, has no WebJs equivalent; the router simply never writes scroll for a frame.
+
+**Read "never moves" as "WebJs never writes one", not as a guarantee the viewport cannot move.** A swap that makes the panel SHORTER shortens the document with it, and a reader parked near the bottom is then holding an offset the document can no longer reach, so the browser clamps it. Measured on the gallery's frames demo: filtering from All to Done at the bottom of the page moves the window from 474 to 405, exactly the 69px the document lost. The router wrote no scroll there (verified with every scrolling API instrumented), and any DOM change that shortens a page does the same thing. Keeping the frame a stable height across its states avoids it entirely.
+
 **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.
 
 **Self-loading.** Give a frame a `src` and it self-fetches (through the same swap path).

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

@@ -382,6 +382,14 @@ Import from `@webjsdev/core/directives`. Everything a `class`/`style`/conditiona
 | `asyncAppend(iter)` / `asyncReplace(iter)` | Stream from an async iterable, appending each value or replacing with the latest. |
 | `templateContent(el)` | Render the content of a `<template>` element. |
 
+Every directive here is CLIENT behaviour. At SSR the server renders one shot, so
+`guard` always invokes its function, `watch` reads its signal once and inlines
+the value, and `live` is fully transparent, resolving to the value it wraps in
+every hole position (a child, a plain attribute, a `?bool`, a `.prop`). So
+`?open=${live(false)}` omits its attribute exactly as `?open=${false}` does. It
+was previously resolved only in a child hole, which served `open=""` and let
+hydration close the element a moment later (#1443).
+
 ## Display-only elision
 
 A component that does no client-side work renders the same SSR'd HTML with or without its JS, so WebJs strips its import from the served source (and any vendor reachable only through it). This is automatic and conservative. A component stays elidable while it has NONE of:
@@ -390,7 +398,7 @@ A component that does no client-side work renders the same SSR'd HTML with or wi
 - a factory-declared reactive property that is not `{ state: true }`
 - an overridden lifecycle hook (including `renderFallback` / `renderError`)
 - an imported `signal` / `computed` / `watch` / `Task` / `ref` / streaming directive, or `addController` / `requestUpdate`
-- code that runs at module load (a top-level call, non-data `new`, dynamic `import(...)`, top-level `await`); only declarations and `X.register(...)` are allowed
+- code that runs at module load (a top-level call, non-data `new`, dynamic `import(...)`, top-level `await`); only declarations and `X.register(...)` are allowed. TypeScript types are erased before the analyser reads a module, so an annotation can never be a blocker however call-shaped it looks (`readonly (readonly [number, number, number])[]` is fine)
 - 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
 

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

@@ -3,7 +3,7 @@
 ## What This Covers
 
 - The Next.js patterns that LOOK right in WebJs but break, because WebJs borrows Next's file-based routing shape but not its execution model (no RSC, no `'use client'` split): `redirect()` in a route handler, `fetch()` in a page, `<Link>`, `NEXT_PUBLIC_`, `await params`.
-- The Lit patterns that break WebJs SSR or reactivity, because WebJs is HTML-first (real HTML first paint, JS opt-in per behaviour) not JS-first: `static properties` / the `@property()` decorator, class-field initializers, browser globals in `render()`, fetching in `connectedCallback`, interpolation into `<style>`, reading `assignedNodes()` in `firstUpdated` of a light-DOM component.
+- The Lit patterns that break WebJs SSR, reactivity, or event handling, because WebJs is HTML-first (real HTML first paint, JS opt-in per behaviour) not JS-first: `static properties` / the `@property()` decorator, class-field initializers, browser globals in `render()`, fetching in `connectedCallback`, passing a method straight to an `@event` binding, interpolation into `<style>`, reading `assignedNodes()` in `firstUpdated` of a light-DOM component.
 - The WebJs-shaped fix for each, with short code.
 
 Read this when a pattern feels familiar from Next.js or Lit but you are not sure it transfers. For the component runtime see `components.md`; for the routing surface see `routing-and-pages.md`. The one difference underneath everything: pages and layouts render server-only and never hydrate, and the one client boundary is a `WebComponent` custom element.
@@ -210,10 +210,14 @@ Navigation is automatic. The client router auto-enables when `@webjsdev/core` lo
 
 ### No `<ScrollRestoration>`, and no scroll restore of your own
 
-Remix ships a `<ScrollRestoration />` component, Next has a `scrollRestoration` flag and a pile of community `useEffect` + `scrollTo` recipes, and every one of them is a thing to NOT port. WebJs restores scroll on Back/Forward automatically: the router sets `history.scrollRestoration = 'manual'` on boot and is the sole authority on scroll for the whole navigation. There is no component to render and no option to enable. An app-level `popstate` listener that calls `scrollTo`, a remembered offset in `sessionStorage`, or a `scrollIntoView` on a saved element all race the router and win sometimes, which is worse than losing consistently.
+Remix ships a `<ScrollRestoration />` component, Next has a `scrollRestoration` flag and a pile of community `useEffect` + `scrollTo` recipes, and every one of them is a thing to NOT port. WebJs restores scroll on Back/Forward automatically, and the BROWSER is what does it: the router reserves the page's recorded height across the swap so the browser's own per-entry replay lands correctly, and writes no scroll itself. There is no component to render and no option to enable. An app-level `popstate` listener that calls `scrollTo`, a remembered offset in `sessionStorage`, or a `scrollIntoView` on a saved element all race the router and win sometimes, which is worse than losing consistently.
+
+**Do not set `history.scrollRestoration = 'manual'` either**, which is the one line most of those recipes start with. The browser only records a per-entry scroll offset under the default `auto`, and WebKit composes the iOS edge back-swipe gesture preview from that recording, so `manual` makes every scrolled page preview BLANK for the whole gesture (#1428). The router itself used to set it, inherited from Turbo Drive, and had the same bug. It no longer does.
 
 This includes the case that most tempts a hand-rolled fix: Back landing BELOW where the reader left, on a page whose components size themselves after they render. The router already handles it, by suppressing the browser's scroll anchoring across the restore so late growth above the viewport is not added to the offset it just replayed (see `client-router-and-streaming.md`). If a restore still lands wrong, report it rather than patching around it in app code.
 
+**One scroll reflex DOES port, and only one.** Next's `<Link scroll={false}>` has a WebJs spelling: `data-preserve-scroll` on the link, or on any element wrapping a group of them, and `navigate(url, { scroll: false })` programmatically. It suppresses the forward-navigation scroll-to-top, which is a write the ROUTER makes, and that is why it exists while none of the restore recipes above do: the restore is the browser's and the router is not a writer on it. Everything else in this section stands unchanged, including the rule not to hand-roll a restore. The attribute keeps the reader's CURRENT offset on a forward nav; it does not bring back the offset they once had on the destination, which is what a hand-rolled `sessionStorage` restore is usually reaching for.
+
 ### Server-only code: the `.server.ts` boundary, not a `server-only` package
 
 Next poisons a client-imported module with the `server-only` package. WebJs uses the file extension: `*.server.ts` is the path-level boundary (the file router refuses to serve the source). A `'use server'` file's exports are RPC-callable; a `.server.ts` file WITHOUT `'use server'` is a server-only utility whose browser import throws at load. Reach a no-`'use server'` utility through a `'use server'` action, `route.ts`, or `middleware`, never by direct import into a shipping page or component.
@@ -286,6 +290,26 @@ class StudentCard extends WebComponent({ student: prop<Student>(Object) }) {
 
 The `@property()` decorator is banned by the erasable-TS invariant (decorators are non-erasable, they would force a build step). A `static properties = { ... }` block THROWS at runtime (`no-static-properties`). The single replacement for both is the declare-free base-class factory `WebComponent({ ... })`, with the `prop()` helper carrying options.
 
+### Passing a method straight to an `@event` binding
+
+Lit invokes an `@event` listener with `this` set to the host element, so `@click=${this.handleClick}` is correct there. WebJs stores the handler verbatim and dispatches it through an internal part object (`part.handler?.(ev)` in `core/src/render-client/parts.js`), so `this` is THAT object, not your component. It does not fail loudly. A read such as `this.todos` returns `undefined`, and a write such as `this.count = 1` silently lands on the framework's internal object. The `TypeError` arrives later, when you dereference the `undefined` you read back, so the stack points away from the real cause. Nothing catches it statically either: `webjs check` and `tsc` both pass and the component SSRs correctly.
+
+Wrap the call at the binding site, which is the conventional spelling, or declare the handler as an arrow class field, which carries its own `this`.
+
+```ts
+// BROKEN: `this` is undefined when the event fires.
+html`<form @submit=${this.handleSubmit}>`
+
+// Wrap it at the binding site:
+html`<form @submit=${(e: SubmitEvent) => this.handleSubmit(e)}>`
+
+// Or pre-bind by declaring the handler as an arrow field:
+_onSubmit = (e: SubmitEvent) => { /* ... */ };
+html`<form @submit=${this._onSubmit}>`
+```
+
+An arrow class field is a class-field initializer, but it is NOT a reactive property, so the reactive-property class-field ban does not apply to it and `reactive-props-no-class-field` does not flag it.
+
 ### Expecting shadow DOM and reaching for scoped CSS
 
 Lit defaults to shadow DOM, so `static styles = css` scopes automatically. WebJs defaults to light DOM. A `static styles` block without `static shadow = true` does nothing useful and any inline `<style>` with bare class names leaks globally. The webjs-shaped fix is Tailwind utilities, which apply directly in light DOM. Reach for `static shadow = true` plus `static styles` only when scoped CSS genuinely belongs in a shadow root, or prefix every selector with the tag name if authoring vanilla light-DOM CSS.

package/templates/.agents/skills/webjs/references/optimistic-ui.md

@@ -85,7 +85,7 @@ TodoList.register('todo-list');
 
 ### Author the optimistic mutation as a degrade-first form
 
-Wrap the mutation in a REAL `<form>` bound to the action, then intercept it for the optimistic path. One form serves both: with JS off the browser submits and the server dispatches to that action (the no-JS write path, see `routing-and-pages.md`), and with JS on `@submit` calls `e.preventDefault()` and runs the optimistic path. That is the progressive-enhancement contract, not a fetch-only handler.
+Wrap the mutation in a REAL `<form>` bound to the action, then intercept it for the optimistic path. One form serves both: with JS off the browser submits and the server dispatches to that action (the no-JS write path, see `routing-and-pages.md`), and with JS on `@submit` calls `e.preventDefault()` and runs the optimistic path. That is the progressive-enhancement contract, not a fetch-only handler. Note the arrow wrapper on the listener: WebJs does not bind an `@event` handler to your component, so passing the method directly would leave `this` pointing at a framework-internal object (see `muscle-memory-gotchas.md`).
 
 The SAME imported function is the form binding and the optimistic path's callee, which is what makes a degrade-first form cheap to write: there is no second wiring to keep in step.
 
@@ -94,7 +94,7 @@ import { createTodo } from '#modules/todo/actions/create-todo.server.ts';
 
 render() {
   return html`
-    <form action=${createTodo} @submit=${this.handleSubmit}>
+    <form action=${createTodo} @submit=${(e: SubmitEvent) => this.handleSubmit(e)}>
       <input name="title" required>
       <button>Add</button>
     </form>
@@ -130,19 +130,31 @@ The component reads that seeded prop as its `optimistic()` `source`, so `source:
 For a boolean toggle where the value itself is the mutation (like, follow, pin), `optimistic(signal, value, action)` is a thin wrapper over the signal primitive.
 
 ```ts
-import { signal, optimistic } from '@webjsdev/core';
+import { WebComponent, prop, signal, optimistic, html } from '@webjsdev/core';
 import { likePost } from '#modules/posts/actions/like-post.server.ts';
 
-const liked = signal(false);
-// in an @click handler:
-const result = await optimistic(liked, true, () => likePost(postId));
-// `liked` flips to true instantly. If likePost THROWS or returns
-// { success: false }, `liked` rolls back to its prior value: the throw
-// re-throws, and the { success: false } result is returned so you can
-// read its error / fieldErrors. On success the optimistic value stays;
-// reconcile to the authoritative value from `result` if you need it.
+class LikeButton extends WebComponent({ postId: prop(String) }) {
+  // INSTANCE scope: one signal per element. A module-scope `signal()` is SHARED
+  // across every instance (invariant 5), so a feed of these would all flip
+  // together on one click. Scope per-item state to the instance.
+  private liked = signal(false);
+
+  private async toggle() {
+    const next = !this.liked.get();
+    // Returns the action's ActionResult, so a { success: false } is readable
+    // by the caller. The rollback has already happened by then.
+    return optimistic(this.liked, next, () => likePost(this.postId));
+  }
+
+  render() {
+    return html`<button @click=${() => this.toggle()}>${this.liked.get() ? 'Liked' : 'Like'}</button>`;
+  }
+}
+LikeButton.register('like-button');
 ```
 
+Reserve MODULE scope for state that genuinely is app-wide (a theme, a cart count, a sidebar-open flag), which is the case invariant 5's "module-scope signals share state across components" exists to serve. Per-item state goes on the instance, as above. `liked` is a plain instance field, not a reactive property declared in the factory, so the class-field ban does not reach it and `reactive-props-no-class-field` does not flag it. `gallery/modules/optimistic-ui/components/like-button.ts` is the same shape in shipped code.
+
 It rolls back on a thrown error OR an `ActionResult` `{ success: false }` envelope, and never on success. It is client-only (it mutates a signal), so a component importing it is never elided as a display-only component.
 
 ## When Optimistic UI Is Appropriate

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

@@ -20,7 +20,7 @@ Pick a runtime from the deploy target, not the code. Default to Node unless you
 Three seams pick a runtime-specific implementation, all inside the framework, none in your app:
 
 - **The listener.** `startServer` selects the `node:http` request shell on Node and a native `Bun.serve` shell on Bun. Both parse the request, run middleware, dispatch to your routes, and stream the response through the same downstream pipeline, so an SSR page, a server action RPC, and a route handler behave identically.
-- **The type stripper.** WebJs serves `.ts` / `.tsx` as ES modules by erasing the types in place with no bundler. On Node that is the built-in `module.stripTypeScriptTypes`; on Bun it is `amaro` (the same engine, byte-identical and position-preserving so stack traces still point at the right line). Either way your TypeScript must be erasable (see `typescript.md`).
+- **The type stripper.** WebJs serves `.ts` / `.mts` as ES modules by erasing the types in place with no bundler. Those two are the whole set: there is no JSX anywhere in the framework, so a `.tsx` file is not served. On Node that is the built-in `module.stripTypeScriptTypes`; on Bun it is `amaro` (the same engine, byte-identical and position-preserving so stack traces still point at the right line). Either way your TypeScript must be erasable (see `typescript.md`).
 - **A few built-ins.** SQLite, hot reload, and WebSockets each bind to the runtime's native primitive (see the table).
 
 ## Node vs Bun at a glance

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

@@ -36,7 +36,20 @@ When custom CSS IS unavoidable inside a light-DOM component, the tag-prefix inva
 
 ## DRY via a JS helper, not `@apply`
 
-When the same Tailwind bundle repeats across 2+ places, extract it into a helper in `lib/utils/ui.ts` that returns an `html` fragment (SSR-time, no client runtime, output identical to inline classes):
+When the same Tailwind bundle repeats across 2+ places, extract it into a helper that returns an `html` fragment (SSR-time, no client runtime, output identical to inline classes). Where the helper LIVES follows the narrowest-owner rule, so pick the tier by who consumes it:
+
+| Consumers | Home |
+|---|---|
+| routes across the app (a heading, a lede, a back link) | `lib/utils/ui.ts` |
+| one feature (a todo row, a comment card, a board) | `modules/<feature>/utils/ui/<name>.ts` |
+
+One file per fragment under `utils/ui/`, because a feature accumulates several and one-per-file keeps them greppable. A fragment promotes from the feature tier to `lib/` only when a second feature genuinely consumes it.
+
+The app-wide tier grows the same way, on the same judgment `references/module-structure.md` applies to any module. `lib/utils/ui.ts` is where it starts and where it usually stays: small, independent, one-element helpers belong together in one file, however many of them there are (the blog example keeps nine there quite happily). Split to `lib/ui/<name>.ts`, one file per fragment, when a fragment stops being a one-liner, when one composes others, or when the single file is no longer scannable. The framework's own website crossed that line and its four composed page fragments live in `lib/ui/`.
+
+So `modules/<feature>/utils/ui/`, `lib/utils/ui.ts`, and `lib/ui/` are one convention at three sizes rather than three conventions, and the `ui` segment is the part carrying the meaning at every one of them: inside `modules/<feature>/`, `components/` holds custom elements, `utils/ui/` holds functions returning a `TemplateResult`, and the rest of `utils/` holds functions returning data. Drop the segment and a view fragment ends up beside a pure data helper with nothing in the path to tell them apart.
+
+The example below is the app-wide tier:
 
 ```ts
 import { html } from '@webjsdev/core';
@@ -62,12 +75,44 @@ export default function Post({ params }) {
 | Repeats | Action |
 |---|---|
 | Once | Inline the classes. |
-| 2 to 3 times, identical | Extract to `lib/utils/ui.ts`. |
+| 2 to 3 times, identical, inside ONE feature | Extract to `modules/<feature>/utils/ui/<name>.ts`. |
+| 2 to 3 times, identical, across features or routes | Extract to `lib/utils/ui.ts`. |
 | Varies by 1 to 2 props | Extract with a small parameter (`mb: 'sm' \| 'md'`). |
 | Radically different per call site | Keep inline, do not force-fit. |
 
 Avoid `@apply`: it hides which utilities a class uses and creates a second source of truth. A JS helper keeps the bundle visible at the definition site, composes with conditional classes and active states, and runs at SSR time.
 
+### Fragment or display-only component?
+
+Two questions, in order.
+
+**First, is this a UNIT or a repeated CLASS BUNDLE?** The helpers this section began with (a heading, a lede, a back link) are the second kind: one element with a class list you did not want to type twice. That is a fragment by definition and never a component; nobody wants `<page-lede>` as a tag in their DOM, and promoting a class bundle to an element is the same over-reach as absorbing a page section into an island. The question below only arises for a genuine unit of markup (a row, a card, a board) that could reasonably be either.
+
+**Second, for a unit: can the markup carry an extra wrapper element at all?** A component is a tag in the DOM, so choosing one adds a node between the parent and the markup. Usually that is fine and the component is the better choice, since it gets a tag name to target and can grow behaviour later. Two cases make it impossible outright:
+
+| Case | What happens |
+|---|---|
+| a `<table>` / `<tbody>` child | the parser FOSTER-PARENTS the element out of the table (an HTML spec rule, not a WebJs one), so it lands BEFORE the table and its cells are adopted by a `<tr>` it no longer owns. The component never renders where you put it |
+| output that is not DOM | a `<webjs-stream>` payload, or HTML a `route.ts` returns, is a STRING, and a component has no way to produce one |
+
+Three more render fine and are wrong in ways that surface later, so treat them as strong reasons rather than hard blocks. Measured in Chromium, the element survives in all three:
+
+| Case | What survives, what breaks |
+|---|---|
+| a `<ul>` / `<ol>` / `<dl>` child | the list renders, but `ul > li`, `:nth-child`, and list markers now see the wrapper instead of the row |
+| a `<select>` child | the control still offers a wrapped `<option>` (it is in `select.options`), but it is no longer `select > option`, so selector-based CSS and DOM code miss it, and the content model is invalid |
+| a `grid` / `flex` child | the wrapper becomes THE ITEM, so the children you meant to lay out sit one level too deep and the track sizing applies to the wrong box |
+
+Everywhere else the two are interchangeable, and the remaining difference is cost. Be precise about that too, because the obvious summary ("fragments are free, components ship") is wrong in both directions.
+
+**Rendered only by pages, they cost the same: nothing.** A page is inert or import-only, so a fragment it calls runs at SSR and is never fetched. A component that does no client work is elided, so it is never fetched either. Byte arguments do not decide this case; pick whichever reads better.
+
+**Rendered by a shipping island, BOTH ship.** A module a shipping component imports is fetched, fragment or not, so the fragment's function is downloaded too (verify it yourself: watch the network panel for the helper's path). What differs is what else comes with it. The component ships a custom element class plus its registration and upgrades once per instance, and, because elision propagates downward, it un-elides every display-only component IT renders. The fragment ships a function and stops there.
+
+So near an island the fragment is the smaller and more predictable choice, not a free one, and the gap is a class and its blast radius rather than everything. That is a tiebreaker, not a rule: it is worth acting on where a shipping island is or might become the renderer, and not worth reorganising page-level markup over. When it matters, measure with `webjs elision` rather than reasoning from either rule of thumb.
+
+**The summary.** A repeated class bundle is always a fragment. For a real unit, take the fragment where a wrapper element cannot exist (a table child, or string output) and where it would land wrong (a list, select, grid, or flex child); take the component whenever the markup needs behaviour, wants a tag to target, or might grow either; and treat the byte difference as the last consideration rather than the first.
+
 ### A design system for repeated PRIMITIVES: class helpers built on `@webjsdev/ui`
 
 An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. `cn` resolves Tailwind conflicts so a later class wins, including a shorthand over the axis it subsumes (`p-0` beats an earlier `px-4 py-2`), so an override just works. Conflicts are keyed on the CSS PROPERTY wherever `cn` can tell the properties apart, rather than on the shared class prefix, so the common prefix collisions do NOT evict: `cn('border-2', 'border-primary')` keeps both (a width and a colour), `cn('flex', 'flex-1')` keeps both (a `display` and a `flex-grow`, the shape an element that is both a flex container and a flex child needs), `cn('shadow-lg', 'shadow-red-500')` keeps both (a box-shadow and its colour), `cn('bg-clip-text', 'bg-primary')` keeps both (a clip and a colour, so the gradient-text idiom survives a later background), and an arbitrary value carrying a type hint is read as the property the hint names (`cn('shadow-lg', 'shadow-[color:red]')` keeps both). It is a small hand-rolled merger, not `tailwind-merge`, so it is still coarse in two ways. A prefix outside the families it knows is not grouped at all, so both classes are emitted and the winner is left to compiled stylesheet order (`inset-shadow-sm` against `inset-shadow-red-500`, `ring-2` against `ring-red-500`). And where one prefix carries two properties it reads the value against Tailwind's DEFAULT scales, so a `@theme`-extended name it cannot know about can still be misread and evict the wrong class: a custom `--shadow-card` makes `shadow-card` a box-shadow, but `cn` sees an unfamiliar name under a prefix whose bare names are usually colours and treats it as one. When an override has to win and you are unsure, pass the one class rather than layering, or install `clsx` + `tailwind-merge` and replace the helper (its header comment shows the swap). For an icon button prefer `size: 'none'` (it states "I supply my own box" by dropping the helper's padding + radius) over layering a `p-0` on top of the default size.

package/templates/.github/pull_request_template.md

@@ -33,7 +33,3 @@ in [`CONVENTIONS.md`](../CONVENTIONS.md) for the full guidance.
       there.
 - [ ] **Scaffold scripts / codegen** (if the project has any). Updated
       when the change affects what new instances generate.
-- [ ] **Pre-merge self-review loop.** Ran N rounds; last round clean.
-      Skip only for one-line trivial changes. See the **Pre-merge
-      self-review loop** section in [`CONVENTIONS.md`](../CONVENTIONS.md)
-      for the prompt template and reporting contract.

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

@@ -39,7 +39,11 @@ export default function ClientRouterExample() {
       Opt out app-wide with <code class="font-mono">{ "webjs": { "clientRouter": false } }</code>,
       or per-link with <code class="font-mono">data-no-router</code> (use it for
       auth flows like <code class="font-mono">/logout</code> that must reset
-      in-memory state).
+      in-memory state). A forward navigation scrolls to top; per link (or per
+      wrapping element) <code class="font-mono">data-preserve-scroll</code> keeps
+      the reader where they are, for a filter or tab link that changes only part
+      of what they are looking at. A hash link still scrolls to its anchor, and
+      a frame-targeted link never scrolled anyway.
     </p>
   `;
 }

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

@@ -42,7 +42,13 @@ export default function MetadataExample({
       Current title source:
       <code class="font-mono text-sm">${topic ? '?topic=' + topic : '(default, no ?topic=)'}</code>
     </p>
-    <ul class="list-disc pl-5 mb-4">
+    <!-- data-preserve-scroll keeps the reader's scroll offset instead of
+         jumping to the top on click. These links change only the query string
+         of the page you are already on, so the control you just used would
+         otherwise scroll out from under you. It sits on the <ul> and the router
+         resolves it with closest(), so one mark covers every link inside; a
+         single link can opt back out with data-preserve-scroll="false". -->
+    <ul class="list-disc pl-5 mb-4" data-preserve-scroll>
       <li><a class="text-primary underline underline-offset-2" href="/features/metadata?topic=webjs">?topic=webjs</a></li>
       <li><a class="text-primary underline underline-offset-2" href="/features/metadata?topic=Routing">?topic=Routing</a></li>
       <li><a class="text-primary underline underline-offset-2" href="/features/metadata">clear the param</a></li>

package/templates/gallery/modules/client-router/components/router-controls.ts

@@ -2,6 +2,10 @@
 // swap an <a> click does, but from an event handler (after a save, a wizard
 // step, etc.). `revalidate(url?)` evicts the browser snapshot cache so the next
 // visit refetches fresh HTML instead of the cached page.
+// `navigate(url, { scroll: false })` is the programmatic twin of
+// `data-preserve-scroll` on a link: the same soft swap, without the
+// scroll-to-top. Reach for it after an in-page action that changes the URL but
+// should not move the reader.
 // `refreshPage(mode?)` re-renders the page you are ALREADY on and swaps the
 // result in place, recording no history entry and never scrolling, so the reader
 // keeps their place. 'page' (the default) morphs the deepest shared boundary, so
@@ -37,6 +41,9 @@ export class RouterControls extends WebComponent {
           <button
             @click=${() => navigate('/features/client-router/second')}
             class=${buttonClass({ variant: 'secondary' })}>navigate() to page two</button>
+          <button
+            @click=${() => navigate('/features/client-router/second', { scroll: false })}
+            class=${buttonClass({ variant: 'secondary' })}>navigate(..., { scroll: false })</button>
           <button
             @click=${() => revalidate()}
             class=${buttonClass({ variant: 'link', size: 'none' })}>revalidate() the snapshot cache</button>

package/templates/gallery/modules/stream/components/browser/stream-demo.test.js

@@ -0,0 +1,64 @@
+// Co-located browser test for the stream demo, in real Chromium with real SSR
+// and hydration. The runner UI is `tdd` (suite/test) and there is no assertion
+// library, so a tiny inline assert does the job.
+//
+// This pins the one thing the row fragment has to get right: the SEEDED rows
+// (rendered from the html`` shape) and the STREAMED rows (rendered from the
+// string shape) come off one class list, so a mutation cannot leave the list
+// styled two ways. Both shapes are exercised through the real component.
+import { html } from '@webjsdev/core';
+import { ssrFixture } from '@webjsdev/core/testing';
+import '../stream-demo.ts';
+
+const assert = (cond, msg) => { if (!cond) throw new Error(msg || 'assertion failed'); };
+const rows = (el) => [...el.querySelectorAll('#stream-list > li')];
+const button = (el, label) => [...el.querySelectorAll('button')].find((b) => b.textContent.trim() === label);
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+suite('<stream-demo>', () => {
+  test('SSRs the two seeded rows as direct list children', async () => {
+    const el = await ssrFixture(html`<stream-demo></stream-demo>`);
+    const ids = rows(el).map((li) => li.id);
+    assert(ids.join(',') === 'row-1,row-2', `seeded ids, got ${ids}`);
+    // A direct child, no wrapper element between the list and the row. That is
+    // the structural reason the row is a fragment and not a display-only element.
+    assert(rows(el).every((li) => li.parentElement.id === 'stream-list'), 'rows are direct children of the list');
+  });
+
+  test('a streamed row carries the same classes as a seeded row', async () => {
+    const el = await ssrFixture(html`<stream-demo></stream-demo>`);
+    const seeded = rows(el)[0].className;
+    button(el, 'Append').click();
+    await tick();
+    const all = rows(el);
+    assert(all.length === 3, `three rows after append, got ${all.length}`);
+    const streamed = all[2];
+    assert(streamed.id === 'row-3', `appended row is row-3, got ${streamed.id}`);
+    assert(streamed.className === seeded, `streamed row classes match seeded:\n  ${streamed.className}\n  ${seeded}`);
+  });
+
+  test('the string shape escapes its holes', async () => {
+    // The html`` shape escapes its own holes; this plain-string one has to do
+    // it by hand, and it is the shape a reader copies. A raw value here would
+    // become markup as soon as renderStream() inserted it.
+    const { streamRowHTML } = await import('../../utils/ui/row.ts');
+    const out = streamRowHTML('x" onload="boom', '<img src=x onerror=boom>');
+    assert(!out.includes('<img'), `text hole is escaped, got ${out}`);
+    assert(!out.includes('" onload'), `attribute hole is escaped, got ${out}`);
+  });
+
+  test('replace keeps the id and reset restores the seed list', async () => {
+    const el = await ssrFixture(html`<stream-demo></stream-demo>`);
+    button(el, 'Replace Row 1').click();
+    await tick();
+    assert(rows(el)[0].id === 'row-1', 'replace keeps row-1');
+    assert(rows(el)[0].textContent.includes('replaced'), 'replace swaps the content');
+    button(el, 'Prepend').click();
+    await tick();
+    button(el, 'Reset').click();
+    await tick();
+    const ids = rows(el).map((li) => li.id);
+    assert(ids.join(',') === 'row-1,row-2', `reset restores the seed list, got ${ids}`);
+    assert(rows(el)[0].textContent.trim() === 'Row 1', 'reset restores the seed content');
+  });
+});

package/templates/gallery/modules/stream/components/stream-demo.ts

@@ -13,6 +13,15 @@
 // region-swap would clobber.
 import { WebComponent, html, renderStream } from '@webjsdev/core';
 import { buttonClass } from '#components/ui/button.ts';
+// The row markup lives in ONE place, a feature-local view fragment under
+// `utils/ui/` (see references/styling.md for that folder). A fragment rather
+// than a display-only <stream-row> element because BOTH of this demo's uses
+// rule an element out, which is the test to apply: the seeded list needs a
+// direct `<ul> > <li>` child (a wrapper tag would sit between them and break
+// the selector and the list semantics), and the streamed payload is an HTML
+// STRING, which a component cannot produce at all. Where a wrapper IS fine,
+// prefer the component.
+import { streamRow, streamRowHTML } from '../utils/ui/row.ts';
 
 // Build a <webjs-stream> payload string. It is a plain string (NOT an html``
 // template), so interpolating the row markup here is fine. `remove` needs no
@@ -22,9 +31,6 @@ function streamPayload(action: string, target: string, inner = '') {
   return `<webjs-stream action="${action}" target="${target}">${body}</webjs-stream>`;
 }
 
-const rowCls = 'flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground';
-const row = (id: string, label: string) => `<li id="${id}" class="${rowCls}">${label}</li>`;
-
 export class StreamDemo extends WebComponent {
   // A plain instance field, NOT a signal: incremented to mint unique row ids.
   // It is never read inside render(), so appending a row does not re-render the
@@ -37,16 +43,16 @@ export class StreamDemo extends WebComponent {
   // never runs. Name your handlers something else (see muscle-memory-gotchas).
   appendRow() {
     this.#n++;
-    renderStream(streamPayload('append', 'stream-list', row(`row-${this.#n}`, `Row ${this.#n} (appended)`)));
+    renderStream(streamPayload('append', 'stream-list', streamRowHTML(`row-${this.#n}`, `Row ${this.#n} (appended)`)));
   }
   prependRow() {
     this.#n++;
-    renderStream(streamPayload('prepend', 'stream-list', row(`row-${this.#n}`, `Row ${this.#n} (prepended)`)));
+    renderStream(streamPayload('prepend', 'stream-list', streamRowHTML(`row-${this.#n}`, `Row ${this.#n} (prepended)`)));
   }
   replaceFirst() {
     // `replace` swaps the target element itself. The replacement keeps id row-1,
     // so the button stays repeatable.
-    renderStream(streamPayload('replace', 'row-1', row('row-1', 'Row 1 (replaced)')));
+    renderStream(streamPayload('replace', 'row-1', streamRowHTML('row-1', 'Row 1 (replaced)')));
   }
   removeSecond() {
     // `remove` deletes the target and needs no <template>.
@@ -54,7 +60,7 @@ export class StreamDemo extends WebComponent {
   }
   reset() {
     // `update` replaces the target's children, restoring the seed list.
-    renderStream(streamPayload('update', 'stream-list', row('row-1', 'Row 1') + row('row-2', 'Row 2')));
+    renderStream(streamPayload('update', 'stream-list', streamRowHTML('row-1', 'Row 1') + streamRowHTML('row-2', 'Row 2')));
   }
 
   render() {
@@ -71,8 +77,7 @@ export class StreamDemo extends WebComponent {
         <!-- The target list. renderStream() mutates it by id; this markup renders
              once and is never re-rendered by the component. -->
         <ul id="stream-list" class="grid gap-2 m-0 p-0 list-none">
-          <li id="row-1" class="flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">Row 1</li>
-          <li id="row-2" class="flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground">Row 2</li>
+          ${streamRow('row-1', 'Row 1')}${streamRow('row-2', 'Row 2')}
         </ul>
       </div>
     `;

package/templates/gallery/modules/stream/utils/ui/row.ts

@@ -0,0 +1,41 @@
+// A feature-local VIEW FRAGMENT: pure, returns markup, used only by the stream
+// demo. It lives in `modules/<feature>/utils/ui/` rather than `utils/` (which
+// holds helpers returning DATA) or `components/` (which holds custom elements).
+// See .agents/skills/webjs/references/styling.md.
+//
+// WHY a fragment and not a display-only <stream-row> element: an element is a
+// tag in the DOM, and neither caller can carry one. The list wants a direct
+// `<ul> > <li>` child, so a wrapper would break that selector and the list
+// semantics; and <webjs-stream> takes its payload as an HTML STRING, which no
+// component can return. That is the test, not bytes: where a wrapper element is
+// harmless, reach for the component instead.
+//
+// Hence the two shapes below, off one class list, so the streamed row and the
+// seeded rows cannot drift apart. That drift was live: the class list used to
+// exist three times in this feature, once in a `rowCls` const and twice inlined
+// in the component's own template, which did not use the const.
+import { html, escapeAttr, escapeText } from '@webjsdev/core';
+
+const ROW =
+  'flex items-center gap-2 px-3 py-2 rounded-xl bg-card border border-border text-[15px] text-foreground';
+
+/**
+ * The row as a template, for the component's own render(). `unknown` on the
+ * label because it forwards straight into an `html` hole, which renders a
+ * string, a number, a TemplateResult, or an array of those.
+ */
+export function streamRow(id: string, label: unknown) {
+  return html`<li id=${id} class=${ROW}>${label}</li>`;
+}
+
+/**
+ * The same row as an HTML string, for a <webjs-stream> template payload.
+ *
+ * ESCAPE EVERY HOLE HERE. The `html` tag above escapes its own holes; this
+ * plain template literal does NOT, so an unescaped value becomes markup the
+ * moment renderStream() puts it in the document. The demo only ever passes its
+ * own literals, but this is the shape people copy, so it does the safe thing.
+ */
+export function streamRowHTML(id: string, label: string): string {
+  return `<li id="${escapeAttr(id)}" class="${ROW}">${escapeText(label)}</li>`;
+}

package/templates/gallery/test/rate-limit/rate-limit.test.ts

@@ -5,6 +5,7 @@ import { dirname, resolve } from 'node:path';
 
 import { createRequestHandler } from '@webjsdev/server';
 import { testRequest } from '@webjsdev/server/testing';
+import type { Handle } from '@webjsdev/server/testing';
 
 const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
@@ -22,7 +23,7 @@ const MAX = 5;
 // X-Forwarded-For that DISAGREES, standing in for the CDN egress address the
 // real deploy puts there, so a test that passes only because the two agree
 // cannot exist.
-function ping(handle: (req: Request) => Promise<Response>, visitor: string, cdnEgress = '172.68.1.9') {
+function ping(handle: Handle, visitor: string, cdnEgress = '172.68.1.9') {
   return testRequest(handle, PING, {
     headers: { 'cf-connecting-ip': visitor, 'x-forwarded-for': cdnEgress },
   });