@webjsdev/cli 0.10.56 → 0.10.58

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,15 +75,47 @@ 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.
+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. Under the opt-in `webjsui lint` (configured by a `lint` block in `components.json`, see `references/ui-kit.md`), `w-9 h-9` is layout and `rounded-full` is shape in the shadcn category taxonomy, so an app running it sets `no-restyle` to `allow: ["layout", "rounded"]` for this idiom to pass: the plain radius group is granted by name without opening the whole `shape` category, and `border-2` beside a helper still fires.
 
 ```ts
 // components/ui/button.ts  (npx webjsdev ui add button, themed to your app)

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

@@ -189,6 +189,17 @@ WEBJS_ELIDE=0 npm run test:e2e
 
 A test that passes under one and fails under the other is a wrong verdict, and `webjs elision` tells you which module and on what evidence. If the component's interactivity is genuinely invisible to static analysis, the fix is `static interactive = true` on it; see `components.md` for what that override does and does not rescue.
 
+## One command for every layer (`webjs ci`)
+
+```sh
+npm run ci                     # the webjs.ci list: check, doctor, typecheck, audit, then every test layer
+npm run ci -- --only Tests     # one step or group by title
+npm run ci -- --fail-fast      # stop at the first failure
+npm run ci -- --json           # one JSON document for an agent loop
+```
+
+The scaffold declares its gate once, in `package.json` under `webjs.ci`, and `npm run ci` runs it with a timed result line per step (the Rails `bin/ci` model). The generated GitHub workflow runs the same list, so a green local run predicts CI. Run it before every push; the pre-commit hook deliberately runs none of it so a commit stays fast. Browser and e2e steps need a Chromium on the machine (`npx playwright install chromium`, plus `puppeteer-core` for the e2e layer), which the workflow installs for itself. The list, the flags, the `--signoff` merge gate, and the JSON shape are in `references/built-ins.md` under "Local CI".
+
 ## Type-checking your tests (`webjs typecheck`)
 
 Your tests are inside the tsconfig `include`, so `npm run typecheck` reads them (#1299). Treat a type error in a test as a failed gate, not a review catch: the checker sees a wrong argument shape or an unannotated parameter in a test the same way it sees one in `app/`.

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

@@ -52,6 +52,31 @@ So the loop is: `add` the component, then query `ui <name>` (MCP) or
   that ships inside the installed `@webjsdev/ui`, with no network. This pins you
   to the installed version; run `npx webjsdev ui diff` to see where your local copies
   drift from the upstream (that command alone compares against the live registry).
+- `npx webjsdev ui lint` is an OPT-IN design-system linter over the app's own
+  source. It reads the Tailwind classes in `html` templates, `cn()` calls and
+  `class=${...}` holes and reports, at the line, a raw palette colour where the
+  theme declares a role token (`no-raw-colors`, with a message naming only the
+  `--color-*` tokens the configured `tailwind.css` actually declares), an
+  arbitrary value such as `p-[13px]` (`no-arbitrary-values`; an arbitrary
+  VARIANT like `[&_svg]:size-4` never fires), and a class composed over a kit
+  helper (`no-restyle`, naming the helper's real variants and sizes read from
+  the app's copied `components/ui/*.ts`). It is off until `components.json`
+  carries a `lint` block, and with no block it reports nothing and exits 0.
+  `components/ui/**` is skipped by default (a copied primitive owns structural
+  values no variant expresses), and `allow` uses shadcn's category taxonomy
+  (`layout`, `color`, `typography`, `spacing`, `shape`, `effects`, `motion`) or
+  a class-group id such as `rounded`. `--json` emits `{ violations, summary }`
+  for an agent loop; `--max-warnings <n>` pins a count.
+
+  ```json
+  "lint": {
+    "rules": {
+      "no-raw-colors": "warn",
+      "no-arbitrary-values": { "severity": "warn", "allow": ["layout"] },
+      "no-restyle": { "severity": "error", "allow": ["layout", "rounded"] }
+    }
+  }
+  ```
 
 ## Inventory (run `npx webjsdev ui list` or the MCP `ui` tool for the authoritative, current set)
 

package/templates/.github/pull_request_template.md

@@ -4,10 +4,9 @@
 
 ## Test plan
 
-- [ ] Unit tests added/updated (`webjs test` passes)
-- [ ] E2E tests added/updated for user-facing changes (`webjs test --e2e` passes)
-- [ ] `webjs check` passes (no convention violations)
-- [ ] `webjs doctor` passes (project health; it fails on whatever `webjs.doctor.gate` marks `error`, plus the hard `NODE_VERSION` / `TSCONFIG_ERASABLE` checks)
+- [ ] `webjs ci` passes locally (the `webjs.ci` step list in package.json: `webjs check`, `webjs doctor`, `webjs typecheck`, the dependency audit, and the server / browser / e2e test layers; CI runs the same list)
+- [ ] Unit tests added/updated
+- [ ] E2E tests added/updated for user-facing changes (`WEBJS_E2E=1 webjs test`)
 
 ## Definition of done
 
@@ -33,7 +32,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/.github/workflows/ci.yml

@@ -1,15 +1,25 @@
 name: CI
 
-# The test gate for {{APP_NAME}}. Runs the full test pyramid on every PR
-# into main and on every push to main. This is the gate the local
-# pre-commit hook deliberately leaves out, so `git commit` stays fast and
-# the test gate runs in one authoritative place a local --no-verify cannot
-# skip. Same posture as the webjs framework's own CI.
+# The cloud half of CI for {{APP_NAME}}. The step list itself lives in
+# package.json under "webjs": { "ci": { "steps": [...] } }, and `npm run ci`
+# runs it: on a developer machine before a push, and here on every PR into
+# main and every push to main, so the two can never drift. This job only
+# prepares the runner (Node, dependencies, a browser, the database) and then
+# runs that one command.
 #
-# The four layers run as separate jobs so a failure names the layer that
-# broke. Mark all four as required status checks in the branch-protection
-# rule for main so a PR can only merge when every layer is green. Free on
-# public repos (ubuntu-latest has unlimited Actions minutes).
+# One job on purpose. Each step is still a collapsible log group with its own
+# result line, a failing step is annotated, and the run's step table lands in
+# the job summary, so a failure names the layer that broke. Mark this job as a
+# required status check in the branch-protection rule for main. A team that
+# wants one required check PER LAYER can add a matrix job that runs
+# `npx webjs ci --only "<group title>"` per entry.
+#
+# The local pre-commit hook deliberately runs none of this, so a commit stays
+# fast; `npm run ci` before pushing is the local gate. To hold a merge until a
+# LOCAL run is green, `npm run ci -- --signoff` posts a green commit status
+# through basecamp/gh-signoff, which branch protection can require (`gh signoff
+# install`), the Rails posture. Free on public repos (ubuntu-latest has
+# unlimited Actions minutes).
 
 on:
   pull_request:
@@ -17,40 +27,21 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: read
+
 # A newer push to the same branch cancels the older in-flight run.
 concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  conventions:
-    name: Conventions (webjs check)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: '24'
-          cache: npm
-      - run: npm ci
-      - run: npm run check
-      # Project health, on top of the correctness checks. WHICH findings are
-      # fatal is your call, declared in package.json under
-      # "webjs": { "doctor": { "gate": { "<CODE>": "off" | "warn" | "error" } } },
-      # so this step and a local `npm run doctor` always agree. The scaffold
-      # starts with UNMARKED_ASSET_LINKS at error (an un-versioned /public url
-      # is a real deploy-staleness bug). Two checks fail with no gate entry at
-      # all, NODE_VERSION and TSCONFIG_ERASABLE, because either would 500 the
-      # app at runtime; everything else stays a warn and cannot fail this job.
-      # Widen or narrow the gate in package.json, not
-      # here. Deliberately not --strict: the git-hook, env-drift, vendor-pin,
-      # and framework-resolve checks are environment-shaped and would fail a
-      # perfectly healthy runner.
-      - run: npm run doctor
-
-  unit:
-    name: Unit + integration (node --test)
+  ci:
+    name: CI (npm run ci)
     runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      DATABASE_URL: file:./ci.db
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
@@ -58,58 +49,17 @@ jobs:
           node-version: '24'
           cache: npm
       - run: npm ci
-      - name: Set up the database (generate + apply migrations)
-        run: npm run db:generate && npm run db:migrate
-        env:
-          DATABASE_URL: file:./ci.db
-      # --server keeps this job to node:test (the browser layer is its own
-      # job below). Without WEBJS_E2E the e2e folders are skipped too.
-      - run: npm run test:server
-        env:
-          DATABASE_URL: file:./ci.db
-
-  browser:
-    name: Browser (web-test-runner / Playwright)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: '24'
-          cache: npm
-      - run: npm ci
-      - name: Install Playwright Chromium
+      - name: Install Playwright Chromium (browser + e2e layers)
         run: npx playwright install --with-deps chromium
-      - run: npm run test:browser
-
-  e2e:
-    name: E2E (full app boot)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: '24'
-          cache: npm
-      - run: npm ci
-      - name: Set up the database (generate + apply migrations)
-        run: npm run db:generate && npm run db:migrate
-        env:
-          DATABASE_URL: file:./ci.db
-      # The scaffold's e2e test (test/hello/e2e/) drives a real browser
-      # via puppeteer-core, which is not a default dependency (the test
-      # skips when it is absent). Install it and Chromium so the e2e
-      # layer actually runs in CI rather than skipping silently.
-      - name: Install puppeteer-core + Chromium
-        run: |
-          npm install --no-save puppeteer-core
-          npx playwright install --with-deps chromium
+      # The scaffold's e2e test (test/hello/e2e/) drives a real browser via
+      # puppeteer-core, which is not a default dependency (the test skips when
+      # it is absent). Install it so the e2e layer runs here rather than
+      # skipping silently.
+      - name: Install puppeteer-core
+        run: npm install --no-save puppeteer-core
       - name: Resolve the Chromium binary path
         run: echo "CHROMIUM_PATH=$(node -e "console.log(require('playwright-core').chromium.executablePath())")" >> "$GITHUB_ENV"
-      # --server with WEBJS_E2E=1 runs node:test including the e2e folders
-      # (the runner gates them on that env var) and skips the browser layer.
-      - name: Run e2e
-        env:
-          WEBJS_E2E: '1'
-          DATABASE_URL: file:./ci.db
-        run: npm run test:server
+      - name: Set up the database (generate + apply migrations)
+        run: npm run db:generate && npm run db:migrate
+      # Everything above prepares the runner. This is the whole gate.
+      - run: npm run ci

package/templates/.hooks/pre-commit

@@ -7,10 +7,11 @@
 #
 # To bypass in emergencies: git commit --no-verify
 #
-# Tests and convention checks run in CI (.github/workflows/ci.yml), not
-# here, so a commit stays fast and the test gate cannot be skipped by a
-# local --no-verify. The CI workflow runs `webjs check` + `webjs test`
-# on every push and pull request.
+# Tests and convention checks do not run here, so a commit stays fast. The
+# step list lives in package.json under "webjs": { "ci" }. Run it locally
+# with `npm run ci` before pushing (the local gate), and the CI workflow
+# (.github/workflows/ci.yml) runs the same list on every push and pull
+# request, where a local --no-verify cannot skip it.
 #
 # Running more than one AI agent on this repo at once? Give each task its own
 # git worktree, not a shared checkout. Two agents in one working directory

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');
+  });
+});