@webjsdev/cli 0.10.51 → 0.10.53

package/templates/.agents/skills/webjs/references/data-and-actions.md

@@ -135,7 +135,7 @@ import { createPost } from '#modules/posts/actions/create-post.server.ts';
 html`<form action=${createPost}><input name="title"></form>`;
 ```
 
-The renderer omits the `action` attribute so the form posts to the page's own url, supplies `method="post"` and an enctype, and emits a hidden `__webjs_action` field carrying the action's `<hash>/<fn>` identity, the same identity the RPC endpoint resolves. Nothing about the action's source reaches the browser. With JS off this is an ordinary HTML submission; with JS the client router posts the same body to the same url, so the two paths are identical by construction.
+The renderer omits the `action` attribute so the form posts to the page's own url, supplies `method="post"` and an enctype, and emits a hidden `__webjs_action` field carrying the action's `<hash>/<fn>` identity, the same identity the RPC endpoint resolves. Nothing about the action's source reaches the browser. With JS off this is an ordinary HTML submission; with JS the client router posts the same body to the same url, encoded per the declared `enctype` (#1307: multipart stays `FormData`, urlencoded, which is the HTML default, is sent as `URLSearchParams`), so the two paths are identical by construction.
 
 **A form-bound action always receives the `FormData`**, which is where it differs from the same function called over RPC (rich arguments) or server-to-server. `validate` is the typing seam: it takes the `FormData` and its transform-return becomes the action's typed input.
 
@@ -236,3 +236,55 @@ import { posts } from '#db/schema.server.ts';
 ```
 
 Keep the wire shape in a browser-safe `modules/<feature>/types.ts` with NO runtime import from a `.server.ts` file or from `db/`. Define a hand-written DTO, or a type-only derivation (`import type { Post } ...; export type PostFormatted = Omit<Post, 'createdAt'> & { createdAt: string }`). Never `export *` or a value re-export from a `.server.ts` in `types.ts`; that carries the runtime table bindings and breaks any component importing the types. Full reference at https://webjs.dev/docs.
+
+## SSR action seeding, and how to tell it is working
+
+When a shipping component's `async render()` awaits an action during SSR, WebJs serializes that result into the page and the generated RPC stub reads it on its FIRST client call. So `const u = await getUser(this.id)` runs once, on the server, and hydration reuses the result with no network round-trip.
+
+**You write nothing for this.** It is automatic, on by default, and there is no API to call. The only thing you can do is break it, so the section below is about noticing when you have.
+
+### The correctness boundary
+
+A seed hit returns the value the SSR render that produced this page computed for exactly this action, function, and argument list, so a hit cannot show the user something different from the HTML they are already looking at. A page navigation evicts whatever the outgoing page left unconsumed, both the block still in the DOM and anything already ingested from it, so a departed render's value is never served. On an HTML-cached page (`export const revalidate`) the seed rides inside the cached bytes, so it is exactly as fresh as the HTML it came with. A miss simply re-fetches.
+
+There is one shape where a hit can differ from the paint, and WebJs warns about it in dev: **an action that returns a DIFFERENT result for the SAME arguments twice in one render.** The seed carries the last result while the first component painted the first one. So keep an action deterministic for a given argument list. A counter, a `Math.random()`, a `new Date()` in the return value, or a read of mutable module state all break that rule, and dev prints:
+
+```
+[webjs] SSR action seeding: "getUser" returned two DIFFERENT results for the SAME arguments during one render. ...
+```
+
+The fix is to make the action deterministic, or to move the varying part into an argument so the two calls get different keys.
+
+### Reading the dev diagnostics
+
+A miss is invisible from the outside: the page still renders correctly, it just pays a round-trip per async component on every first load. Two channels make it visible in dev, and neither exists in production.
+
+**Server side, per request.** The `X-Webjs-Seed` response header, also folded into the dev access-log line as a `seed` field:
+
+| Value | What it means |
+|---|---|
+| `off` | Seeding is switched off (`"webjs": { "seed": false }` or `WEBJS_SEED=0`). Not a defect. |
+| `html-cache` | The #241 HTML response cache answered. The seeds rode inside the cached bytes. |
+| `collected=3, emitted=3` | Healthy. Three action results were captured and all three reached the page. |
+| `collected=3, emitted=0` | The serializer threw and dropped the whole block. Something in a returned value is not serializer-safe. |
+| `collected=3, emitted=0, streamed` | The page streams, so nothing could be emitted (see below). |
+
+Check it with `curl -sSI localhost:3000/` or in the network tab.
+
+**Browser side, per page view.** One `console.warn` at the first idle after hydration, and only when a call missed AND the client can be certain why. It stays silent otherwise, including on a page that emitted no seeds at all: every action call routes through the seed lookup, including ones that were never SSR-invoked and never could have been seeded (a mutation, a `Task` autorun, a `connectedCallback` read), so a miss there is not evidence of a defect. That case is the server header's job, where `collected=0` is unambiguous. The line names one of these:
+
+- *"This page streams"*, so no seeds could be emitted. Expected, not a bug (see below).
+- *"The page's seeds could not be serialized."* Something an action returned is not serializer-safe, so the whole block was dropped. The response header shows `collected` above `emitted` for the same reason.
+- *"The page seeded these actions under DIFFERENT arguments."* The key is `hash(action file) / function name / serialized arguments`, so the client asked with an argument the SSR render never used. Common cause: the component computes its argument from browser-only state (a `localStorage` read, a `connectedCallback` assignment), which the server render could not have known. A miss on an action the page never seeded at all is NOT reported, because a mutation or a client-only read routes through the same lookup and could never have been seeded.
+
+A miss AFTER hydration is correct and is not reported: the seed is consume-once, so a deliberate refetch or an argument change is supposed to go to the network.
+
+`seedStats()` from `@webjsdev/core` returns `{ ingested, replaced, hits, misses, keyMisses, pending }` (`keyMisses` being the provable subset of `misses`, a call for an action the page seeded under other arguments) if you want to assert this in a browser test or read it from the console. A non-zero `pending` at rest usually means the seeding component ELIDED, so its module never shipped and nothing on the client was ever going to consume the seed. `pending` covers the page you are on: a page navigation evicts whatever the outgoing page left unconsumed, both the block still sitting in the DOM and anything already ingested from it, since those values belong to a render no longer on screen.
+
+### The streamed-page exception
+
+A page carrying a `Suspense` or `<webjs-suspense>` boundary emits NO seed block at all, not just none for the streamed region: a streamed render's deferred boundaries resolve after the first flush, so their results cannot ride the block. Every action call on that page goes to the network on hydration. That is a real trade, so make it deliberately: reach for a streaming boundary when a slow region would otherwise block the first byte, and leave a fast page buffered so it seeds.
+
+### Switching it off
+
+`"webjs": { "seed": false }` in `package.json`, or `WEBJS_SEED=0`. The client then re-fetches on hydration exactly as it did before the feature, and stale-while-revalidate hides the flicker. Turn it off only to isolate a problem; there is no reason to ship with it off.

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

@@ -64,7 +64,21 @@ html`<form action=${saveDraft}>
 </form>`;
 ```
 
-The identity rides the pressed button's own `name`/`value` pair, which a browser submits for that button alone, so this works with JS off exactly as it does with JS on. Both entries reach the server and the LAST wins, which is always the submitter's when one was pressed. The submitter must be a `<button>` and cannot carry its own `name`, `value`, or `form` attribute, because the identity already occupies that pair. `<input type="submit">` is refused for the binding: the identity has to occupy its `value`, which on that control is also the visible caption, so the button would render captioned with the action id and could never be labelled. A `<button>` has no such conflict, since its label is its children.
+The identity rides the pressed button's own `name`/`value` pair, which a browser submits for that button alone, so this works with JS off exactly as it does with JS on. Both entries reach the server and the LAST wins, which is always the submitter's when one was pressed.
+
+**A bound submitter is self-sufficient, so the enclosing form does not have to be bound** (#1307). The renderer puts `formmethod="post"` and `formenctype="multipart/form-data"` on the button itself, alongside the identity, exactly as React emits `formMethod` and `formEncType` on a button carrying a function `formAction`. So a per-button action works inside a bound form, an unbound form, a `method="get"` form, or a form with no method at all:
+
+```js
+// Every button below submits a POST its action can read, with JS on or off.
+html`<form>
+  <button formaction=${saveDraft}>Save</button>
+  <button formaction=${publishPost}>Publish</button>
+</form>`;
+```
+
+One consequence worth knowing rather than discovering: no `formaction` url is emitted (an empty one is an HTML conformance error), so the submission targets whatever the FORM targets. A form declaring its own `action="/x"` sends its buttons to `/x`, which is native precedence. The action still runs if `/x` is a PAGE route, because the identity travels in the body, but against a `route.ts` or another origin the identity is ignored and nothing runs. In dev the client logs a warning at submit time naming the url. Leaving the form's `action` off, the ordinary shape, keeps the submission on the current page.
+
+The submitter must be a `<button>` and cannot carry its own `name`, `value`, or `form` attribute, because the identity already occupies that pair. `<input type="submit">` is refused for the binding: the identity has to occupy its `value`, which on that control is also the visible caption, so the button would render captioned with the action id and could never be labelled. A `<button>` has no such conflict, since its label is its children.
 
 **Only the bare, unquoted `action=${fn}` on a `<form>` binds.** Every near-miss is a hard render error rather than a silently-inert form, and the reason is a source leak. During SSR a `.server.ts` import is the ACTUAL function (the RPC stub exists only in the browser), and `action=` is an ordinary attribute hole, so stringifying it would write the function's body into the HTML every visitor downloads, including any literal inside it. The renderer throws instead, on the server and on the client, for `action=` and `formaction=` alike.
 
@@ -95,21 +109,21 @@ The bound, refused, and allowed shapes in full. Every "no" row is a binding that
 | `action=${fn}` unquoted, on a `<form>` | **no, it BINDS** | the one supported shape: the identity is resolved and emitted as a hidden field, nothing is stringified |
 | `action=${fn}` on any other tag | yes | `action` submits nothing off a `<form>`, so it is an ordinary attribute and the function would be stringified |
 | `action="${fn}"`, or a mixed `action="/x/${fn}"` | yes | quoting turns a binding hole back into a plain attribute |
-| `formaction=${fn}` unquoted, on a submitter inside a bound form | **no, it BINDS** | the second supported shape (#1207). The identity rides the button's own `name`/`value` pair, the one channel a browser submits for the pressed button alone, so no `formaction` url is emitted and the server takes the LAST `__webjs_action` entry |
-| `formaction=${fn}` inside an UNBOUND `<form>` | yes | `method="post"` and the enctype are forced on the FORM's start tag, which SSR has already emitted by the time it reaches the button, so a per-button action cannot retrofit them |
+| `formaction=${fn}` unquoted, on a submitter, ANYWHERE | **no, it BINDS** | the second supported shape (#1207, #1307). A bound submitter carries its WHOLE submission: the identity rides the button's own `name`/`value` pair, the one channel a browser submits for the pressed button alone, and the renderer adds `formmethod="post"` and `formenctype="multipart/form-data"` to the button itself. So it works inside a bound form, an unbound form, a `method="get"` form, or a form with no method at all, and it asks NOTHING of the element around it. No `formaction` url is emitted, and the server takes the LAST `__webjs_action` entry |
 | `formaction=${fn}` on a submitter carrying its own `name` or `value` | yes | the identity IS that name/value pair, so both halves are already spoken for. Bind one action on the form and dispatch on `name="intent"` if you need the button's own value |
 | `formaction=${fn}` on a non-submit control, or `<input type="image">` | yes | `formaction` is inert on anything that does not submit, and an image submitter sends `name.x` / `name.y` coordinates instead of `name=value`, so the identity would never arrive |
-| `formaction=${fn}` on a submitter with `form="other"` | yes | it re-points the submitter at a form other than the bound one it sits in, so the boundness just checked was about the wrong element |
-| `formmethod="get"` / `formenctype="text/plain"` on ANY submitter inside a bound form | yes | this is the Part B rule, and it applies whether or not that button binds an action of its own: a GET sends no body and `text/plain` is not parseable, so the submission works under JS (the router posts `FormData`) and 405s without it |
+| `formaction=${fn}` on a submitter with `form="other"` | yes | it re-points the submitter at a different form owner, which may not be where the identity field it needs lives |
+| `formmethod` / `formenctype` the BOUND submitter cannot submit with (`get`, `PATCH`, `text/plain`, `dialog`, a padded `" post "`) | yes | a same-element contradiction: you attached an action to THIS button and told THIS button to submit in a way that action could never read. The renderer supplies `formmethod="post"` and the enctype only where you supplied neither, so your own parseable value always wins |
+| `formmethod="get"` / `formenctype="text/plain"` on a PLAIN submitter inside a bound form | **no** | #1307 reversed this. Native HTML says the submitter's override wins, you typed it deliberately, and the form's action simply does not run, exactly as the same markup behaves anywhere else. In dev the client logs a console error at submit time if the submission is carrying an identity it cannot deliver |
 | `formmethod="dialog"` on a submitter that binds nothing | **no** | a native `<dialog>` dismissal, never a submission, so there is no body for the action to miss. It IS refused on a button that also binds an action, which is a straight contradiction |
-| a plain `formaction="/url"` on a submitter inside a bound form | **no** | it retargets the submission away from the page's bound action entirely, so its own `formmethod` is the author's business and Part B leaves it alone |
+| a plain `formaction="/url"` on a submitter inside a bound form | **no** | it retargets the submission away from the page's bound action entirely, so where it goes and how is your business |
 | `.action=` on a native form | yes | the supported binding is the plain attribute, and a `.prop` on a native element drops at SSR, so accepting it would mean a form that submits under JS and does nothing without it |
 | `.method=` / `.enctype=` / `.encoding=` on a BOUND form | yes | the same reason one level over. All three are reflected IDL attributes, so SSR drops the binding and emits `method="post"` while a browser ends at what you assigned. Write them as plain attributes |
 | a second `action=${fn}` on one form | yes | SSR emits the second as a plain url next to the identity field, the client takes the last. Bind exactly one, in either position |
 | a plain `action="/url"` beside the bound hole | yes | the hole drops only its OWN attribute, so SSR keeps the static one while the client removes it: without JS the browser posts to `/url`, with JS to the page |
 | `method=" post "` / `enctype=" multipart/form-data "` | yes | `method` and `enctype` are enumerated attributes matched against exact keywords with no whitespace stripping, so a padded value falls to the invalid-value default and the form submits as a GET with no body. Trimming it for you would emit the padded value anyway |
 | `encoding="..."` as an ATTRIBUTE on a bound form | **no** | inert in HTML (`form.encoding` reads back `enctype`), so both renderers ignore it and still supply `enctype`. Only the `.encoding` PROPERTY aliases enctype, and that spelling IS refused, one row up |
-| `.formAction=` on a button or input | yes | same reason, that is where `formAction` reflects |
+| `.formAction=` / `.formMethod=` / `.formEnctype=` on a BOUND submitter | yes | same reason, that is where they reflect: SSR drops the property and the browser applies it, so the button would submit one way with JS and another way without. On a PLAIN button they are ordinary native properties and are left alone |
 | `.action=` on any other native tag | **no** | a plain expando (`<div .action=${fn}>`, `<button .action=${fn}>`), reflecting nothing, so nothing reaches the markup |
 | `.action=` on a custom element | **no** | an author-defined property, not a reflected IDL attribute, so a function is a legitimate value. One declared `reflect: true` reflects on a path outside these commit sites, which used to write `String(value)` and emit the source. It now removes the attribute and warns instead, for a bare function and for an array carrying one, unless the prop supplies its own `converter.toAttribute`, which runs first and stays the author's call |
 | `?action=` | yes | a function never leaked through a boolean hole, but the binding is meaningless, so it is refused rather than emitting the bare `action=""` that ANY truthy value produces there. Two separate facts worth carrying: `action=""` is a conformance error (the spec wants a valid non-empty URL whenever the attribute is present), and deleting the attribute is still not the WebJs fix, since a page has no `action` export and an unbound `method="post"` form is a 405 (a bare GET form just re-renders). Bind it: `<form action=${fn}>` |
@@ -170,6 +184,12 @@ The file stays `middleware.ts`, NOT Next 16's renamed `proxy.ts`. WebJs middlewa
 
 Navigation is automatic. The client router auto-enables when `@webjsdev/core` loads (any page with a component), so a plain `<a href>` gets soft navigation for free. There is no `<Link>` to import and no `useRouter`. For programmatic navigation import `navigate()` / `revalidate()` from `@webjsdev/core`. There is no `next/image`, `next/font`, `next/script`, or `next/dynamic`. WebJs is no-build: use a plain `<img>`, a `<link>` / `@font-face`, a component's `static lazy = true` for viewport lazy-loading, and a dynamic `import()` where code should load lazily.
 
+### 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.
+
+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.
+
 ### 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.
@@ -268,4 +288,4 @@ Context providers publish on connect via `hostConnected`, which does not run at
 
 ### Vanilla DOM instead of Lit idioms
 
-WebJs components are Lit-shaped on purpose: the value is the declarative DX. Prefer a factory-declared reactive prop over `this.getAttribute`, a `signal` over a `state: true` prop for internal state, a `class=${...}` binding over `this.classList`, a `@click=${...}` binding over `this.addEventListener`, and `C.register('x')` over `customElements.define`. Vanilla DOM stays right only where the platform offers nothing declarative: `this.closest('ui-tabs')` for compound-component ancestor lookup (resolves at SSR too), slotted-content queries, global `document` / `window` listeners, and imperative `el.focus()`. This is a convention, not a lint rule.
+WebJs components are Lit-shaped on purpose: the value is the declarative DX. Prefer a factory-declared reactive prop over `this.getAttribute`, a `signal` over a `state: true` prop for internal state, a `class=${...}` binding over `this.classList`, a `@click=${...}` binding over `this.addEventListener`, and `C.register('x')` over `customElements.define`. Vanilla DOM stays right only where the platform offers nothing declarative: `this.closest('ui-tabs')` for compound-component ancestor lookup (resolves at SSR too), slotted-content queries, global `document` / `window` listeners, and imperative `el.focus()`. This is a convention, not a lint rule. A global `document` / `window` LISTENER is one of those legitimate cases, because the event happens outside the element. A document QUERY is not: reaching for markup that another component rendered is the jQuery habit to drop, and for your OWN rendered node a `ref` replaces the selector entirely. The ownership rules at the top of `components.md` state the full test.

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

@@ -104,7 +104,7 @@ render() {
 
 `method` and the enctype are supplied by the renderer, and the hidden identity field is re-inserted as the form's first child on every client render, so there is nothing to manage by hand.
 
-When a page owns SEVERAL mutations (create, toggle, delete), give each form its OWN binding (`action=${createTodo}` / `action=${toggleTodo}` / `action=${deleteTodo}`), or use per-button submitter server action bindings via `formaction=${action}` on submitter buttons inside a bound form (#1207). Alternatively, a form that dispatches dynamically can bind ONE action and inspect a submit button's `name="intent"`.
+When a page owns SEVERAL mutations (create, toggle, delete), give each form its OWN binding (`action=${createTodo}` / `action=${toggleTodo}` / `action=${deleteTodo}`), or use per-button submitter server action bindings via `formaction=${action}` on submitter buttons (#1207, #1307: a bound submitter carries its own submission, so the enclosing form need not be bound). Alternatively, a form that dispatches dynamically can bind ONE action and inspect a submit button's `name="intent"`.
 
 ## Seed the list from the server for SSR plus optimistic
 

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

@@ -179,7 +179,9 @@ Three responses that are not the happy path:
 
 The submission is Origin-verified (the same `Sec-Fetch-Site` / `Origin` check the RPC endpoint applies), so a no-JS form needs no CSRF token field.
 
-Refusals worth knowing: `formaction=${fn}` is supported only on a `<button>` inside a bound form, and that button may not carry `name`, `value`, `form`, or a static `formaction` attribute (`<input type="submit">` is refused, because the identity needs its `value`, which is also its label). A bound form may not declare `method="get"`, and a function bound to `action=` that is not a `'use server'` export throws at render rather than producing a form that posts nowhere. See `muscle-memory-gotchas.md` for the full table.
+A submitter's own `formmethod` / `formenctype` / `formtarget` overrides the form's on PRESENCE, not on the value being non-empty, and the client router resolves them the same way (#1322). So `<button type="submit" formmethod="">` really does submit as a GET, because a present-but-empty enumerated attribute falls to its own invalid-value default rather than inheriting the form's `method="post"`.
+
+Refusals worth knowing: `formaction=${fn}` is supported on a `<button>` anywhere, bound form or not (#1307: the renderer gives the button its own `formmethod` and `formenctype`), and that button may not carry `name`, `value`, `form`, or a static `formaction` attribute (`<input type="submit">` is refused, because the identity needs its `value`, which is also its label). A bound form may not declare `method="get"`, and a function bound to `action=` that is not a `'use server'` export throws at render rather than producing a form that posts nowhere. See `muscle-memory-gotchas.md` for the full table.
 
 ## Error, loading, and 404 boundaries
 

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

@@ -70,7 +70,7 @@ Avoid `@apply`: it hides which utilities a class uses and creates a second sourc
 
 ### 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), 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 some prefixes are still grouped coarsely and a less common pair can collide (`bg-clip-text` against `bg-primary`, `shadow-lg` against `shadow-red-500`). 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.
 
 ```ts
 // components/ui/button.ts  (npx webjsdev ui add button, themed to your app)

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

@@ -170,6 +170,33 @@ A cross-runtime proof is often a plain assert script rather than a test file, so
 - **Assert the exit code, never the logs.** These scripts conventionally pass a `quiet` logger, so anything that only logs is invisible. If your script catches its own failure, report it with an explicit `process.exit(1)` rather than a `console.error` alone, guarded as `if (import.meta.main) process.exit(1); else throw failure;`. The guard matters when a `.test.mjs` wrapper imports the script under `node --test`: an unguarded exit kills the whole single-process run and hides every other file's results, while the throw lets the harness report one failed test.
 - **Prove the script can FAIL before you trust it passing.** Break one assertion on purpose and confirm the run exits non-zero. A proof that cannot go red is worse than no proof: it reports success forever.
 
+## Proving display-only elision did not break anything
+
+WebJs strips the JavaScript of every component that does no client work, so a wrong verdict costs an app real interactivity and does it silently. Two commands cover the two halves, and you need both.
+
+```sh
+webjs elision --verify
+```
+
+renders every static page route with elision on and off and diffs the served bytes. It is the framework's own differential guard pointed at your route table, and it exits non-zero on a divergence AND on a corpus where nothing could be compared, so it belongs in CI. It forces the ON side on rather than reading your config, and reports how many modules elision actually dropped, so a pass that compared two identical renders is visible rather than silent. Dynamic routes are skipped by name; add real paths with `--routes /,/blog/hello`.
+
+That proves the bytes you SERVE did not change. It cannot prove post-hydration behaviour, because a wrongly dropped module shows up as a dead click, not as different bytes. Run your own browser or e2e suite twice for that half:
+
+```sh
+WEBJS_ELIDE=1 npm run test:e2e
+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.
+
+## 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/`.
+
+Write them to the same bar as app code, then. No `any`, no blanket `@ts-expect-error`. When a test needs a complete props object the framework would normally build, put a small typed helper in `test/helpers/` and import it rather than reaching for a cast; a cast in a test silences the one thing that would have told you the call was wrong.
+
+`.js` test files follow whatever `checkJs` says. With it off they are parsed and not checked, which is the usual setup for browser tests a real browser runs.
+
 ## Convention validation (`webjs check`)
 
 `npm run check` is the correctness validator. Every rule catches code that is wrong to ship, a crash, a security leak, a reactive prop that silently stops re-rendering, or a type-strip failure. Run it and fix every violation before considering the change done (`npm run check -- --json` for an agent loop, `npm run check -- --rules` to list the rules). It is separate from `CONVENTIONS.md`, which carries the customizable project conventions you follow by judgment.

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

@@ -62,19 +62,33 @@ Prefer explicit `.ts` extensions in imports. A `.js` specifier pointing at a `.t
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["node"],
     "strict": true,
     "noEmit": true,
-    "checkJs": true,
-    "allowJs": true,
     "allowImportingTsExtensions": true,
     "skipLibCheck": true,
     "erasableSyntaxOnly": true
-  }
+  },
+  "include": [
+    "app/**/*",
+    "components/**/*",
+    "modules/**/*",
+    "lib/**/*",
+    "test/**/*",
+    "middleware.js",
+    "middleware.ts",
+    ".webjs/routes.d.ts"
+  ],
+  "exclude": ["node_modules", ".webjs/vendor", "db/migrations"]
 }
 ```
 
 `erasableSyntaxOnly: true` is the non-negotiable line. It aligns the compiler's accepted syntax with the stripper's, so violations surface as diagnostics instead of a runtime 500.
 
+`test/**/*` is in the `include` on purpose (#1299), the way Next / Remix / Astro's generated configs cover the whole tree. Leave it there. A test file outside the `include` is a file `webjs typecheck` never opens, so an implicitly-`any` parameter or a wrong argument shape in a test survives until somebody reads the line, which is exactly how one reached review here. Do not add a second `tsconfig.test.json` either: a config nobody remembers to run reproduces the same gap in a new place.
+
+Note what is absent: `checkJs`, the flag mentioned at the top of this file for a JSDoc-typed codebase (it implies `allowJs`, so it is the only one you add). Turning it on makes `tsc` read your `.js` files, which is the point, but it also pulls in browser tests written as `.js`. Those run in a real browser through web-test-runner, so their test globals are not in scope for `tsc` and each one reports a `Cannot find name 'test'`. Turn it on deliberately, and give the browser tests a `types` entry or their own exclude when you do.
+
 ## Full-stack type safety
 
 ### The rule: derive the type, never `unknown` or `any`

package/templates/.claude/hooks/block-prose-punctuation.sh

@@ -6,16 +6,18 @@
 #
 #   1. U+2014 em-dash, anywhere.
 #   2. Space-hyphen-space " - " in PROSE contexts (comment lines, markdown
-#      lines, headings, blockquotes). Math expressions in code like
+#      lines, headings, blockquotes, a JSON "description" / "title" /
+#      "displayName" string value, and a column-0 YAML front-matter
+#      description: / title: / displayName: line). Math expressions in code like
 #      `Math.abs(a - b)` or `arr.length - 1` are NOT flagged.
-#   3. Space-semicolon-space " ; " in PROSE contexts. JS / CSS statement
-#      terminators (`;\n`) are NOT flagged.
+#   3. Space-semicolon-space " ; " in the same PROSE contexts as rule 2.
+#      JS / CSS statement terminators (`;\n`) are NOT flagged.
 #   4. Code-shaped left-hand side immediately followed by a colon and prose:
 #        - `<code>foo()</code>:` (markdown code-LHS in docs)
 #        - `<my-tag>:` (custom-element tag with hyphen)
 #        - Inline comment `// foo(): description`
 #
-# Why this exists: see AGENTS.md "Invariants", item 10. These patterns
+# Why this exists: see AGENTS.md "Invariants", item 11. These patterns
 # confuse AI agents that try to parse the prose as TypeScript / shorthand-
 # method / object-literal syntax, and trip humans reading API docs.
 #
@@ -46,8 +48,13 @@ if [ -z "$new_content" ]; then
   exit 0
 fi
 
+# Every match below reads from a here-string, never a pipe. `grep -q` exits on
+# the first match, which closes a pipe under `printf`, and with `set -o pipefail`
+# that SIGPIPE became the pipeline status, so the rule silently skipped on any
+# payload past the pipe buffer (measured: 0 of 8 blocks at 128 KB).
+
 # --- 1. U+2014 em-dash --------------------------------------------------
-if printf '%s' "$new_content" | grep -q $'\xe2\x80\x94'; then
+if grep -q $'\xe2\x80\x94' <<< "$new_content"; then
   cat >&2 <<'EOF'
 BLOCKED: em-dash (U+2014) detected in this tool call.
 
@@ -57,7 +64,7 @@ restructured sentence. Do NOT replace it with " - " or " ; " or a
 trailing colon on code: those are also banned. See rule 2 / 3 / 4
 below for the alternatives.
 
-Rule: AGENTS.md, Invariants section, item 10.
+Rule: AGENTS.md, Invariants section, item 11.
 Hook: .claude/hooks/block-prose-punctuation.sh.
 EOF
   exit 2
@@ -81,25 +88,42 @@ block_pause_hyphen=0
 # `*` (markdown bold-start would have a letter after, distinguishable),
 # followed by prose with `\w+ - \w+` pattern. Specifically: catch lines
 # like `// foo - bar`, ` * foo - bar`, `* foo - bar`.
-if printf '%s\n' "$new_content" | grep -qE '^[[:space:]]*(//|\*)[[:space:]].*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]'; then
+if grep -qE '^[[:space:]]*(//|\*)[[:space:]].*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]' <<< "$new_content"; then
   block_pause_hyphen=1
 fi
 
 # Markdown heading " - " pause: line starts with `#` followed by prose
 # and ` - ` pattern.
-if printf '%s\n' "$new_content" | grep -qE '^#{1,6}[[:space:]].*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]'; then
+if grep -qE '^#{1,6}[[:space:]].*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]' <<< "$new_content"; then
   block_pause_hyphen=1
 fi
 
 # Markdown blockquote " - " pause: line starts with `>` followed by prose
 # and ` - ` pattern. (Single `>` blockquote, not table.)
-if printf '%s\n' "$new_content" | grep -qE '^>[[:space:]].*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]'; then
+if grep -qE '^>[[:space:]].*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]' <<< "$new_content"; then
   block_pause_hyphen=1
 fi
 
 # HTML / markdown <p>, <li>, <td> body " - " pause: line contains a
 # closing HTML tag from a prose context, then prose-style ` - `.
-if printf '%s\n' "$new_content" | grep -qE '<(p|li|td|h[1-6]|strong|em|blockquote)[^>]*>[^<]*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]'; then
+if grep -qE '<(p|li|td|h[1-6]|strong|em|blockquote)[^>]*>[^<]*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]' <<< "$new_content"; then
+  block_pause_hyphen=1
+fi
+
+# JSON prose-value " - " pause: a string assignment whose KEY is one of the
+# three prose-bearing keys this project's JSON uses. Scoping to the key is what
+# keeps this off semver ranges, script commands, urls, paths and globs, every
+# one of which lives under a different key. Shape, not file path: the Bash
+# payload carries no file_path, so a heredoc writing a manifest is covered too.
+if grep -qE '^[[:space:]]*"(description|title|displayName)"[[:space:]]*:[[:space:]]*".*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]' <<< "$new_content"; then
+  block_pause_hyphen=1
+fi
+
+# YAML front-matter " - " pause, same three keys. Anchored at column 0 with no
+# leading whitespace, which is what confines it to document front matter: every
+# nested YAML mapping is indented, including the workflow-input `description:`
+# values in .github/workflows/release.yml.
+if grep -qE '^(description|title|displayName):[[:space:]].*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]' <<< "$new_content"; then
   block_pause_hyphen=1
 fi
 
@@ -118,13 +142,17 @@ restructured phrasing.
   Bad:  <li>Foo - bar.</li>
   Good: <li>Foo, with bar.</li>
 
+  Bad:  "description": "A library - for things"
+  Good: "description": "A library for things"
+
 Plain hyphens are still fine in compound words (`AI-first`), CLI
 flags (`--http2`), filenames, ranges, and math expressions in code
 (`arr.length - 1`, `Math.abs(a - b)`). The hook only flags the
 ` < word > - < word > ` pause-pattern in prose contexts (comments,
-markdown headings, blockquotes, HTML prose tags).
+markdown headings, blockquotes, HTML prose tags, and a JSON or
+front-matter description / title / displayName value).
 
-Rule: AGENTS.md, Invariants section, item 10.
+Rule: AGENTS.md, Invariants section, item 11.
 Hook: .claude/hooks/block-prose-punctuation.sh.
 EOF
   exit 2
@@ -134,19 +162,29 @@ fi
 # Same prose-context guard as #2.
 block_pause_semicolon=0
 
-if printf '%s\n' "$new_content" | grep -qE '^[[:space:]]*(//|\*)[[:space:]].*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]'; then
+if grep -qE '^[[:space:]]*(//|\*)[[:space:]].*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]' <<< "$new_content"; then
   block_pause_semicolon=1
 fi
 
-if printf '%s\n' "$new_content" | grep -qE '^#{1,6}[[:space:]].*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]'; then
+if grep -qE '^#{1,6}[[:space:]].*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]' <<< "$new_content"; then
   block_pause_semicolon=1
 fi
 
-if printf '%s\n' "$new_content" | grep -qE '^>[[:space:]].*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]'; then
+if grep -qE '^>[[:space:]].*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]' <<< "$new_content"; then
   block_pause_semicolon=1
 fi
 
-if printf '%s\n' "$new_content" | grep -qE '<(p|li|td|h[1-6]|strong|em|blockquote)[^>]*>[^<]*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]'; then
+if grep -qE '<(p|li|td|h[1-6]|strong|em|blockquote)[^>]*>[^<]*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]' <<< "$new_content"; then
+  block_pause_semicolon=1
+fi
+
+# JSON prose-value " ; " pause, same three keys as rule 2.
+if grep -qE '^[[:space:]]*"(description|title|displayName)"[[:space:]]*:[[:space:]]*".*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]' <<< "$new_content"; then
+  block_pause_semicolon=1
+fi
+
+# YAML front-matter " ; " pause, column-0 anchored like rule 2.
+if grep -qE '^(description|title|displayName):[[:space:]].*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]' <<< "$new_content"; then
   block_pause_semicolon=1
 fi
 
@@ -161,10 +199,14 @@ two sentences (period) or with a conjunction (", and", ", but", ", so").
   Good: // Forms work. Links work too.
   Good: // Forms work, and links work too.
 
+  Bad:  "description": "Forms work ; links work too."
+  Good: "description": "Forms work. Links work too."
+
 Semicolons stay fine inside code (JS statement terminators, CSS
-declarations) since those are not flagged.
+declarations) since those are not flagged. Only the space-surrounded
+form is banned, so an ordinary English semicolon is untouched.
 
-Rule: AGENTS.md, Invariants section, item 10.
+Rule: AGENTS.md, Invariants section, item 11.
 Hook: .claude/hooks/block-prose-punctuation.sh.
 EOF
   exit 2
@@ -175,7 +217,7 @@ fi
 # lowercase prose. The `)</code>:` shape is unambiguous: this is markdown,
 # not code, AND the inner code ends in `()` so the colon visually parses
 # as a return-type annotation.
-if printf '%s' "$new_content" | grep -qE '\)</code>:[[:space:]][a-z]'; then
+if grep -qE '\)</code>:[[:space:]][a-z]' <<< "$new_content"; then
   cat >&2 <<'EOF'
 BLOCKED: code-LHS colon-then-prose detected ("<code>foo()</code>: ...").
 
@@ -186,7 +228,7 @@ parses as a TypeScript return-type annotation. Rewrite verb-led.
   Good: <code>repeat()</code> is the keyed list directive
   Good: <code>startServer()</code> creates an HTTP(S) server
 
-Rule: AGENTS.md, Invariants section, item 10.
+Rule: AGENTS.md, Invariants section, item 11.
 Hook: .claude/hooks/block-prose-punctuation.sh.
 EOF
   exit 2
@@ -195,7 +237,7 @@ fi
 # --- 4b. Custom-element-tag <my-tag>: prose ------------------------------
 # HTML reserves hyphenated tag names for custom elements (W3C spec), so
 # `<x-y>:` is unambiguous prose, never JSX / TS / CSS.
-if printf '%s' "$new_content" | grep -qE '<[a-z][a-z0-9]*(-[a-z0-9]+)+([[:space:]][^>]*)?>:[[:space:]][a-z]'; then
+if grep -qE '<[a-z][a-z0-9]*(-[a-z0-9]+)+([[:space:]][^>]*)?>:[[:space:]][a-z]' <<< "$new_content"; then
   cat >&2 <<'EOF'
 BLOCKED: custom-element-tag colon-then-prose detected ("<my-tag>: ...").
 
@@ -206,7 +248,7 @@ webjs bans `<my-tag>: <prose>` in comments and docs. Rewrite verb-led.
   Bad:  // <ui-dialog-content>: the centered panel.
   Good: // <ui-dialog-content> is the centered panel.
 
-Rule: AGENTS.md, Invariants section, item 10.
+Rule: AGENTS.md, Invariants section, item 11.
 Hook: .claude/hooks/block-prose-punctuation.sh.
 EOF
   exit 2
@@ -216,7 +258,7 @@ fi
 # Match comment-line prefix (`//` or leading `*`) before `\w+(...): ` and
 # lowercase prose. Avoids TS return-type annotations because those never
 # appear inside comment lines.
-if printf '%s\n' "$new_content" | grep -qE '^[[:space:]]*(//|\*)[[:space:]][^(]*[A-Za-z_][A-Za-z0-9_]*\([^)]*\):[[:space:]][a-z]'; then
+if grep -qE '^[[:space:]]*(//|\*)[[:space:]][^(]*[A-Za-z_][A-Za-z0-9_]*\([^)]*\):[[:space:]][a-z]' <<< "$new_content"; then
   cat >&2 <<'EOF'
 BLOCKED: comment-line code-LHS colon-then-prose detected ("// foo(): ...").
 
@@ -227,7 +269,7 @@ webjs bans `xyz(): <prose>` inside comments and JSDoc. Rewrite verb-led.
   Bad:  // closest(): null if the click wasn't inside a frame
   Good: // closest() returns null when the click wasn't inside a frame
 
-Rule: AGENTS.md, Invariants section, item 10.
+Rule: AGENTS.md, Invariants section, item 11.
 Hook: .claude/hooks/block-prose-punctuation.sh.
 EOF
   exit 2

package/templates/gallery/modules/async-render/components/server-clock.ts

@@ -16,8 +16,9 @@ export class ServerClock extends WebComponent {
   // serves it with ZERO JavaScript and skips the redundant on-hydration
   // re-fetch. This is the common fetch-and-display leaf shape. If you ever need
   // to force a component to ship when the analyser would elide it (for
-  // interactivity static analysis cannot see, like a dynamically-computed tag
-  // string), declare `static interactive = true`.
+  // interactivity static analysis cannot see, like an observer that computes
+  // the tag it waits for), declare `static interactive = true`. Run
+  // `webjs elision` to see the verdict for every component in this app.
   async render() {
     const info = await serverGreeting();
     return html`<p class="font-mono text-sm">server rendered this at

package/templates/gallery/modules/directives/components/directive-demo.ts

@@ -31,7 +31,10 @@ export class DirectiveDemo extends WebComponent {
   // A controlled value (for `live`) and a key (for `keyed`).
   private text = signal('type here');
   private variant = signal(0);
-  // A handle to the input node, attached by `ref` in the browser.
+  // A handle to the input node, attached by `ref` in the browser. A ref rather
+  // than a `querySelector` because the template already owns the node, so the
+  // handle flows out of `render()` instead of being re-found by a selector that
+  // could match someone else's markup (or nothing at all after a rename).
   private inputRef = createRef<HTMLInputElement>();
   // Created ONCE (not per render), so `until` keeps the resolved value across
   // re-renders instead of flashing back to the fallback each time.

package/templates/gallery/modules/gallery/components/gallery-nav.ts

@@ -6,6 +6,11 @@
 // active item from location.pathname, so the highlight follows soft-nav. SSR is
 // still correct: `render()` reads the `current` prop (the pathname the layout
 // passes) for the first paint, and the client takes over from location after.
+// The document LISTENER below is the legitimate case, not a reach across the
+// app: the router has no element to dispatch from, and the handler reads only
+// location.pathname and writes only this module's own signal, so it queries
+// nothing outside itself. Querying the document for another file's markup is
+// the shape to avoid.
 import { WebComponent, prop, html, signal } from '@webjsdev/core';
 import { FEATURE_GROUPS } from '#modules/gallery/nav.ts';
 

package/templates/gallery/modules/todo/actions/submit-todo.server.ts

@@ -12,9 +12,11 @@ import { deleteTodo } from './delete-todo.server.ts';
 // action: this form carries the todo's `id` on a hidden input and needs the
 // SAME id for whichever mutation runs, so one action reading both fields is the
 // simpler shape. When the buttons need no shared payload, bind each one
-// directly instead, with `formaction=${action}` on a <button> inside the bound
-// form. The identity then rides that button's own name/value pair, so it works
-// with JS off too. Two things to know: it must be a <button> (on an
+// directly instead, with `formaction=${action}` on a <button>. The enclosing
+// <form> does NOT have to be bound: a bound submitter carries its own
+// `formmethod` and enctype, so it works in any form or none. The identity rides
+// that button's own name/value pair, so it works with JS off too. Two things to
+// know: it must be a <button> (on an
 // <input type="submit"> the identity would occupy `value`, which is also that
 // control's visible label), and a bound submitter cannot carry its own
 // `name`/`value`, which is exactly the channel `name="intent"` uses below.

package/templates/test/hello/e2e/hello.test.ts

@@ -20,6 +20,13 @@ import { createServer } from 'node:net';
 // minimal structural types keep the file typed in the meantime; swap them for
 // the real imports once puppeteer-core is in package.json. Reaching for `any`
 // here would silently un-type every call below.
+//
+// They also stay in force when the package IS present, which is the case a
+// generated app usually hits, since @web/test-runner pulls puppeteer-core in
+// transitively. The real Page / Browser are far richer than these, so letting
+// them flow in would fail against the narrow shapes here for the goto return
+// type and the event-handler signature. The single import below is the one
+// boundary where that is resolved, and it is the only suppressed line.
 type Page = {
   // goto resolves an HTTPResponse this file never reads, and modelling that
   // type would mean re-declaring puppeteer's. Returning void is the honest
@@ -30,6 +37,10 @@ type Page = {
   removeAllListeners(event: string): void;
 };
 type Browser = { newPage(): Promise<Page>; close(): Promise<void> };
+// The module's own default export, narrowed to the one call this file makes.
+type Puppeteer = {
+  launch(opts: { executablePath?: string; headless?: boolean; args?: string[] }): Promise<Browser>;
+};
 
 let browser: Browser, page: Page, serverProcess: ChildProcess, baseUrl: string;
 
@@ -46,9 +57,23 @@ function freePort(): Promise<number> {
 }
 
 before(async () => {
-  let puppeteer;
+  let puppeteer: Puppeteer | undefined;
+  // The next line is where the optional dependency enters, and what it reports
+  // depends on whether puppeteer-core is installed: an unresolved specifier
+  // when it is absent, a type mismatch against the structural shapes above
+  // when it is present. Suppressing it keeps the rest of the file checked
+  // against those shapes either way.
+  //
+  // It is deliberately ts-ignore rather than the expect-error directive, whose
+  // name is spelled out here rather than written, because a comment line
+  // starting with that token IS a live directive to tsc even inside prose. The
+  // expect-error form is wrong on its own merits too: it errors when there is
+  // nothing to suppress, so it would break whenever the package resolves
+  // cleanly.
+  // @ts-ignore
   try { puppeteer = (await import('puppeteer-core')).default; }
   catch { console.log('# Skipping: puppeteer-core not installed'); return; }
+  if (!puppeteer) return;
 
   const port = await freePort();
   baseUrl = `http://localhost:${port}`;