@webjsdev/cli 0.10.52 → 0.10.53

package/lib/app-name.js

@@ -206,3 +206,76 @@ export function assertValidAppName(name) {
   }
   return /** @type {string} */ (name);
 }
+
+/**
+ * PostgreSQL's hard cap on an identifier, `NAMEDATALEN - 1` bytes. An
+ * over-length `CREATE DATABASE` name is silently truncated to this with only a
+ * NOTICE, which would reproduce the same name mismatch in a new guise, so the
+ * derivation caps it here instead.
+ */
+export const DB_NAME_MAX_LENGTH = 63;
+
+/**
+ * Derive the PostgreSQL database name the scaffold writes into the generated
+ * `.env.example` `DATABASE_URL`. The APP NAME itself is never touched by this:
+ * the directory, the `package.json` `name`, the `{{APP_NAME}}` substitution and
+ * `metadata.title` all keep the name exactly as typed. Only the database
+ * segment of that one URL is normalized.
+ *
+ * The point is a QUOTING-INVARIANT name. A result in `[a-z_][a-z0-9_]*` under
+ * 63 bytes folds to itself under `CREATE DATABASE <name>;` AND is passed
+ * through unquoted by `createdb` (which builds its statement through `fmtId`),
+ * so the emitted URL names the same database whichever route the user takes.
+ * A case-preserving name does not have that property: `CREATE DATABASE MyApp;`
+ * creates `myapp` while `createdb MyApp` creates `MyApp`.
+ *
+ * One qualification on that property. A name that folds to a PostgreSQL
+ * KEYWORD (`order`, `user`, `table`, `group`, `check`, `window`, `limit`) is
+ * still not quoting-invariant: `CREATE DATABASE order;` is a syntax error
+ * rather than a fold, while `createdb order` succeeds because `fmtId` quotes a
+ * keyword. That is deliberately not detected here. The keyword list is
+ * version-dependent and roughly 470 entries, which is disproportionate in a
+ * helper whose whole point is being pure and dependency-free, and the failure
+ * is a loud syntax error on a placeholder line the user is editing anyway,
+ * not the silent wrong-database mismatch this function exists to remove.
+ *
+ * Three sub-rules, in this order, and the order is load-bearing:
+ *
+ *   1. Fold with `toLowerCase()`, NOT `toLocaleLowerCase()`. The latter is
+ *      locale-dependent, so a Turkish-locale machine would fold `I` to the
+ *      dotless `ı`, which the class below then turns into `_`, making the
+ *      generated file machine-dependent.
+ *   2. Map every remaining character outside `[a-z0-9_]` to `_`, one for one.
+ *      No run-collapsing, no trimming: both are legal identifier characters,
+ *      and a 1:1 fold is one a reader can apply by eye. `checkAppName` already
+ *      restricts the input to `[A-Za-z0-9._-]`, so in practice this only ever
+ *      rewrites `.` and `-`.
+ *   3. Prefix a single `_` when the first character is a digit, BEFORE the
+ *      slice so the cap governs the final string. `ALLOWED_FIRST_CHAR` admits
+ *      a leading digit, and an unquoted PostgreSQL identifier may not start
+ *      with one.
+ *
+ * Slicing LAST is what makes the byte cap correct: after the fold every
+ * surviving character is one ASCII byte, so a code-unit slice is a byte slice,
+ * and there is no surrogate pair or percent-escape for it to bisect (every
+ * character is unreserved under RFC 3986, so the segment needs no encoding).
+ *
+ * Precondition: `name` has passed `checkAppName`. `scaffoldApp` asserts that
+ * before any file is written. That is what guarantees a non-empty result (a
+ * validated name's first character is `[A-Za-z0-9]`, which folds into the
+ * class and survives), so there is no empty-result fallback branch here.
+ *
+ * Collisions are accepted and NOT detected. `My-App` and `my_app` both fold to
+ * `my_app`. This is a placeholder in `.env.example`, not a provisioned
+ * resource: the scaffold contacts no server and cannot know what exists, and a
+ * uniquifying suffix would make the name untraceable to the app name. Rails
+ * takes the same position in `railties/lib/rails/generators/app_name.rb`.
+ *
+ * @param {string} name  an app name that has passed `checkAppName`
+ * @returns {string}     a fold-stable, unquoted-safe PostgreSQL database name
+ */
+export function toDatabaseName(name) {
+  const folded = name.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+  const prefixed = /^[0-9]/.test(folded) ? `_${folded}` : folded;
+  return prefixed.slice(0, DB_NAME_MAX_LENGTH);
+}

package/lib/create.js

@@ -18,7 +18,7 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
-import { assertValidAppName } from './app-name.js';
+import { assertValidAppName, toDatabaseName } from './app-name.js';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -541,6 +541,11 @@ export async function scaffoldApp(name, cwd, opts = {}) {
         { name: '@webjsdev/intellisense' },
       ],
     },
+    // `test/**/*` is in so `webjs typecheck` reads the tests you write, the
+    // same way Next / Remix / Astro's generated configs do (#1299). A type
+    // error in a test is then a gate failure rather than something a reviewer
+    // has to catch by eye, and it needs no second config to remember to run.
+    //
     // `.webjs/routes.d.ts` is the OPT-IN generated route-types overlay (#258):
     // run `webjs types` (or `webjs dev`, which emits it) to narrow the
     // @webjsdev/core `Route` href union + per-route `params`. Listed in
@@ -552,6 +557,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       'components/**/*',
       'modules/**/*',
       'lib/**/*',
+      'test/**/*',
       'middleware.js',
       'middleware.ts',
       '.webjs/routes.d.ts',
@@ -877,9 +883,14 @@ export default defineConfig({
 `);
 
   // Env vars: append DATABASE_URL to the .env.example the template already
-  // copied (if present), idempotently.
+  // copied (if present), idempotently. The database segment is the app name
+  // normalized to a fold-stable PostgreSQL identifier, so the emitted URL
+  // names the same database whether the user runs `createdb` or types
+  // `CREATE DATABASE`. Hoisted because the post-scaffold guidance below names
+  // the same value, and the two must not be able to drift.
+  const dbName = toDatabaseName(name);
   const dbUrlLine = dialect === 'postgres'
-    ? 'DATABASE_URL=postgres://user:password@localhost:5432/' + name.replace(/[^a-z0-9_]/gi, '_')
+    ? 'DATABASE_URL=postgres://user:password@localhost:5432/' + dbName
     : 'DATABASE_URL=file:./db/dev.db';
   const envExample = join(appDir, '.env.example');
   if (existsSync(envExample)) {
@@ -1596,7 +1607,7 @@ ThemeToggle.register('theme-toggle');
   // local file with no .env). Point it at a running database; `dev` / `start`
   // then apply pending migrations via webjs.*.before.
   const pgNote = dialect === 'postgres'
-    ? `\nPostgres: copy .env.example to .env and set DATABASE_URL to a running database before \`${pm} run dev\`.\n`
+    ? `\nPostgres: copy .env.example to .env and set DATABASE_URL to a running database before \`${pm} run dev\`.\nThe example URL names the database \`${dbName}\`. Create that database or edit the URL.\n`
     : '';
   // Use `npx webjsdev ui ...` here, not `npx webjs ui ...`. The bare
   // `webjs` npm name is owned by an unrelated package; `npx webjs

package/lib/doctor.js

@@ -52,7 +52,7 @@
 
 import { existsSync, statSync, readdirSync, readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { createRequire } from 'node:module';
 import { checkNodeInline } from './node-preflight.js';
 
@@ -837,13 +837,87 @@ async function checkImportmapCoherence(appDir, opts) {
   };
 }
 
+/**
+ * Read a dependency's INSTALLED version as resolved FROM `appDir`, or null when
+ * it does not resolve there at all.
+ *
+ * Node's own resolver is the ground truth here, not a directory read. The check
+ * this serves asks "would this app resolve this dependency at runtime, and at
+ * what version", and Node's resolution algorithm IS that question's definition,
+ * so anything re-implementing it can only be a worse approximation. Asking Node
+ * handles workspace hoisting (the bug this fixes: under npm workspaces the
+ * `@webjsdev/*` deps hoist to the ROOT node_modules, so an app subdirectory has
+ * no local copy and a per-app `node_modules/<dep>/package.json` read reported
+ * every declared dep missing on a healthy install), symlinked workspace links,
+ * nested non-hoisted trees, and `package.json` `imports`, for free and for ever.
+ *
+ * The direct `<dep>/package.json` resolve is attempted FIRST because a package
+ * may declare no main entry at all: `@webjsdev/cli` is bin-only (no `main`, no
+ * `exports`), so `require.resolve('@webjsdev/cli')` throws MODULE_NOT_FOUND.
+ * The ERR_PACKAGE_PATH_NOT_EXPORTED fallback exists because a package may lock
+ * its manifest out of its `exports` map: `@webjsdev/server` exports only `.`,
+ * `./check`, `./testing`, and `./webjs-config.schema.json`, so the direct
+ * manifest resolve is refused and the main entry plus a bounded walk up to the
+ * package root is the way in. Neither strategy alone resolves all four
+ * `@webjsdev/*` packages; both halves are required.
+ *
+ * Local rather than `getPackageVersion` from `@webjsdev/server` for two reasons.
+ * Doctor must stay usable when the framework does not resolve from the app dir
+ * at all, which is the #954 fresh-worktree case doctor exists to diagnose, so
+ * this check cannot import the server (the same argument `frameworkResolves`
+ * below already follows). And `getPackageVersion` resolves the main entry only,
+ * so it returns null for a bin-only package, which would leave `@webjsdev/cli`
+ * reported missing: the same false positive with more machinery.
+ *
+ * Pinned by the workspace, bin-only, and exports-locked fixtures in
+ * `test/cli/doctor.test.mjs`.
+ * @param {string} dep package name, e.g. `@webjsdev/server`
+ * @param {string} appDir directory to anchor resolution at
+ * @returns {Promise<string|null>} the installed version, or null when unresolvable
+ */
+async function readInstalledVersion(dep, appDir) {
+  // The base file need not exist; createRequire only uses it to anchor the
+  // node_modules lookup at appDir.
+  const require = createRequire(join(appDir, '__webjs_resolve_probe__.js'));
+  let manifestPath = null;
+  try {
+    manifestPath = require.resolve(dep + '/package.json');
+  } catch (err) {
+    if (err?.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') return null;
+    let entry;
+    try {
+      entry = require.resolve(dep);
+    } catch {
+      return null;
+    }
+    let dir = dirname(entry);
+    for (let i = 0; i < 12; i++) {
+      const candidate = join(dir, 'package.json');
+      if (existsSync(candidate)) {
+        manifestPath = candidate;
+        break;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    if (!manifestPath) return null;
+  }
+  try {
+    return JSON.parse(await readFile(manifestPath, 'utf8')).version || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * CHECK 5, @webjsdev/* version coherence. WARN-level only (a version drift is
  * not a crash). Reads the app package.json `@webjsdev/*` ranges across
- * dependencies + devDependencies, then for each reads the INSTALLED version from
- * `node_modules/@webjsdev/<pkg>/package.json` and checks it satisfies the
- * declared range. PASS when every @webjsdev dep is present + satisfied; WARN on
- * a missing install or a range drift.
+ * dependencies + devDependencies, then for each resolves the INSTALLED version
+ * through Node's own resolver anchored at the app dir (see
+ * `readInstalledVersion`, which is why a workspace-hoisted install resolves)
+ * and checks it satisfies the declared range. PASS when every @webjsdev dep is
+ * present + satisfied; WARN on a missing install or a range drift.
  * @param {string} appDir
  * @returns {Promise<DoctorResult>}
  */
@@ -881,15 +955,8 @@ async function checkWebjsVersions(appDir) {
   const missing = [];
   const drift = [];
   for (const dep of webjsDeps) {
-    const installedPkg = join(appDir, 'node_modules', dep, 'package.json');
-    if (!existsSync(installedPkg)) {
-      missing.push(dep);
-      continue;
-    }
-    let installedVersion = '';
-    try {
-      installedVersion = JSON.parse(await readFile(installedPkg, 'utf8')).version || '';
-    } catch {
+    const installedVersion = await readInstalledVersion(dep, appDir);
+    if (!installedVersion) {
       missing.push(dep);
       continue;
     }

package/package.json

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

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

@@ -38,7 +38,7 @@ Classify the task first, then load the smallest useful reference set. Each refer
 | Task involves...                                                            | Start with                                    |
 | --------------------------------------------------------------------------- | --------------------------------------------- |
 | Pages, layouts, dynamic routes, route handlers, metadata, redirects, 404s   | `references/routing-and-pages.md`             |
-| Writing components: reactive props, signals, lifecycle, light vs shadow DOM  | `references/components.md`                     |
+| Writing components: what a component owns, reactive props, signals, lifecycle, light vs shadow DOM  | `references/components.md`                     |
 | Why a component's JS was or was not downloaded, `webjs elision`, `static interactive = true` | `references/components.md`                     |
 | Server actions, mutations, queries, validation, the `ActionResult` envelope | `references/data-and-actions.md`              |
 | Sessions, login flows, route protection, `forbidden()` / `unauthorized()`   | `references/auth-and-sessions.md`             |
@@ -243,3 +243,5 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 - A placeholder first paint that fetches in `connectedCallback`. SSR does not call `connectedCallback`; put first-paint data in the constructor (server-known inputs) or use `async render()`.
 - A browser global (`window`, `document`, `localStorage`) in the constructor or `render()`. It throws at SSR; do browser-only work in `connectedCallback`.
 - Interpolating into a component's `<style>` / `<script>` body. Use `static styles` or Tailwind.
+- Driving a component's markup from a delegated `document` listener in a page or layout, coupled by a class selector. The markup, the state, and the listener belong in one component.
+- Parking one component's UI state on `<body>` or `<html>`. The router's swap range never covers the document shell, so the flag outlives the markup it described. A document-wide SETTING such as the theme is the exception, and a transient effect such as a scroll lock is released in `disconnectedCallback`.

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

@@ -2,6 +2,7 @@
 
 ## What This Covers
 
+- What a component owns (markup, state, listeners, styling), and the rules that follow from it: refs over selectors, no state on `<body>`, ARIA derived in `render()`
 - Declaring reactive properties through the `WebComponent({ ... })` factory and `prop()`, with options (`reflect`, `state`, `attribute`, `default`, `converter`, `hasChanged`)
 - Signals as the default state primitive for component-local and shared state, plus `effect` / `batch`
 - The Lit-aligned lifecycle and exactly which hooks SSR runs versus skips
@@ -15,6 +16,91 @@
 
 Read this when you are authoring or reviewing a `WebComponent`. For styling a component (Tailwind, the tag-prefix rule, host sizing) see `styling.md`. For streaming a slow region or programmatic navigation see `client-router-and-streaming.md`. For Lit habits that break WebJs see `muscle-memory-gotchas.md`.
 
+## Ownership: what a component owns
+
+A component owns four things together: its markup, its state, its listeners, and its styling. The moment one of them lives in a different file from the rest, the feature can no longer be read, tested, or deleted as a unit, and the parts drift apart. These are CONVENTIONS, judged by a reader. `webjs check` has no rule for any of them, and adding one would be wrong, because a sensible app can legitimately want a delegated listener to pass.
+
+Most of what follows restates widely held component-model advice, ported. Lit's base class exists to hold reactive state, scoped styles, and a declarative template TOGETHER (the `lit` package README), and Lit documents a ref's value as `undefined` once the node "is no longer rendered", which is precisely the signal a selector lookup cannot give you. React frames the same ideas as lifting state to the closest common owner (react.dev, "Sharing State Between Components") and treating a ref as an escape hatch rather than the normal way to reach a node (react.dev, "Escape Hatches"). Where WebJs moves the boundary, the rule that needs it says so inline and names the mechanism.
+
+**1. Markup and the code that drives it live in the same component.** A class selector is not an interface. `document.querySelector('.nav-toggle')` keeps compiling, keeps type-checking, and keeps passing `webjs check` after someone renames the class in the other file. It just starts returning `null` at runtime. If you are writing a selector to find markup that another file rendered, write the component that renders it instead. Where a value genuinely has to exist in two places (a layout's pre-paint inline script cannot import), the second place READS the first declaration rather than restating it.
+
+**2. Reach your own rendered node with a ref, never with a selector.** `render()` already owns the node, so let the handle flow out of the template with `ref()` / `createRef()` from `@webjsdev/core/directives` (the directives table below carries the one-line summary). A ref is scoped to the component, so it cannot match a node some other component rendered, and it goes `undefined` when the node stops being rendered, which makes a stale handle visible instead of silent. Two reads a ref cannot express stay vanilla: `this.closest('parent-tag')` for compound-component ancestor lookup, and `assignedNodes()` for slotted content.
+
+**3. State lives on the component, never on `<body>` or `<html>`.** The client router swaps a range INSIDE the document, so the document shell sits outside every swap. An open flag parked on `<body>` therefore survives a navigation that removed the markup it described, and it re-opens a panel over the next page or leaves scrolling locked on a page with nothing open. State held in a reactive property or an INSTANCE signal dies with the element, which is the behaviour you wanted in the first place. A module-scope signal deliberately outlives it, which is what rule 7 reaches for, so it is the right home for state genuinely shared between components and the wrong one for one element's own open flag. The carve-out is a document-level EFFECT rather than one component's state, and it comes in two shapes. A TRANSIENT effect, a scroll lock being the usual case, belongs to the element that opened it and must be released in `disconnectedCallback`. A PERSISTENT one is a document-wide SETTING, the theme being the case the framework itself ships: the scaffold's theme toggle writes `data-theme` on `<html>` and persists it, deliberately without releasing it on disconnect, because it describes the document rather than the element (`styling.md` carries that pattern). What the rule forbids is neither of those. It is one component's own open / selected / active flag parked on the shell because that was the convenient place to reach it from.
+
+**4. ARIA state is a hole in `render()`, derived from the same state that drives behaviour.** `aria-expanded=${this.open ? 'true' : 'false'}` cannot disagree with `this.open`. A second function that re-finds the button and calls `setAttribute` can, and does, the first time someone adds a close path that forgets to call it. The same holds for `class`, `?disabled`, and any `.prop`. Two caveats ride this rule:
+
+- Write the string explicitly for a tri-state ARIA attribute. A plain-attribute hole holding `false` serves `aria-expanded="false"` from the server and hydrates to NO attribute, because the client removes an attribute for `null` / `undefined` / `false` while the server stringifies it. `?attr=${bool}` is not a substitute, since a boolean binding omits the attribute in BOTH renderers.
+- A hole commits on the next render, one microtask later. The one place a direct write is still correct is a synchronous snapshot read such as `webjs:before-cache`, where the router reads `outerHTML` in the same task. That is a documented exception, not the normal path.
+
+**5. Behaviour needs an importable surface, or its test is a copy of it.** An inline `<script>` in a layout has no module identity, so a browser test cannot import it. It can only transcribe the listener into the test file and assert against the transcription, which then needs a SECOND test to grep the original for drift. Two tests, neither running shipping code. A component is importable, so its browser test mounts the real element and drives real events. A page or layout may still carry an inline `<script>`, but only for pre-paint boot work no module can do: reading a stored theme before first paint so the wrong palette never flashes, or measuring the header height into a CSS custom property. It must not be interactivity, and WHERE it sits decides how often it runs. The ROOT layout's markup sits OUTSIDE every swap range, so a soft navigation does not re-run its script, which is what makes it the right home for boot work and the wrong home for anything that has to respond to a later navigation. A page or a NESTED layout sits inside the swap range instead, so its script re-executes on every navigation that swaps that range (#1102), which means it has to be idempotent or guard on a flag it sets the first time. Neither shape gives you a listener that simply works, which is what a custom element is for. Under an opt-in CSP the script also needs the nonce from `cspNonce()`. `client-router-and-streaming.md` carries the full re-execution rule.
+
+**6. Listening on `document` is legitimate. Querying `document` usually is not.** An outside-click dismissal or an Escape handler has no choice, because the event happens outside the element, so the listener has to be global. What decides whether that is ownership or a reach across the app is what the handler then READS. `this.contains(e.target)` is a decision about the component's own subtree. `document.querySelector('.other-thing')` is a decision about someone else's markup. Add the listener in `connectedCallback`, remove it in `disconnectedCallback`, and store the handler in a field so `removeEventListener` gets the same reference back (a function created inline at add time can never be removed).
+
+**7. Talk to an ancestor with an event, and to a stranger with a module-scope signal.** A child telling its own ancestor something dispatches a `CustomEvent` with `bubbles: true`, and the ancestor binds `@my-event=${...}` in the template that rendered it. Add `composed: true` as well when the component sets `static shadow = true`, or the event stops at the shadow boundary. Two components with NO ancestor relationship share a module-scope `signal` that both import, which is typed, greppable, and owned by a module. What neither case is: a made-up event name on `document` used as a global bus, which is a global variable with extra steps. Framework events such as `webjs:navigate` ride `document` because the router has no element to dispatch from, and that is not a licence to add your own.
+
+The shape to fix, all four pieces in different places:
+
+```js
+// In a layout's inline script, driving markup that another file rendered.
+document.addEventListener('click', (e) => {
+  if (e.target.closest('.nav-toggle')) document.body.toggleAttribute('data-nav-open');
+});
+function syncNav() {
+  const btn = document.querySelector('.nav-toggle');   // another file's markup
+  const open = document.body.hasAttribute('data-nav-open');  // outlives the markup
+  if (btn) btn.setAttribute('aria-expanded', String(open));  // a second home for the state
+}
+```
+
+The shape to write, one component owning all four:
+
+```ts
+import { WebComponent, prop, html } from '@webjsdev/core';
+import { createRef, ref } from '@webjsdev/core/directives';
+
+class NavDrawer extends WebComponent({ open: prop(Boolean, { reflect: true }) }) {
+  private toggleRef = createRef<HTMLButtonElement>();
+  // Stored in a field, so removeEventListener gets the same reference back.
+  private onDocClick = (e: MouseEvent) => {
+    if (!this.contains(e.target as Node)) this.open = false;   // reads its OWN subtree
+  };
+  private onDocKeydown = (e: KeyboardEvent) => {
+    if (e.key !== 'Escape' || !this.open) return;
+    this.open = false;
+    // The ref lands after the FIRST client commit, and `ref()` is a no-op at
+    // SSR, so read `.value` from a handler or `firstUpdated`, never from the
+    // constructor. This is the reach a selector would otherwise have done.
+    this.toggleRef.value?.focus();
+  };
+
+  constructor() { super(); this.open = false; }                // SSR runs the constructor
+
+  connectedCallback() {
+    super.connectedCallback();
+    document.addEventListener('click', this.onDocClick);       // listening globally is fine
+    document.addEventListener('keydown', this.onDocKeydown);
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('click', this.onDocClick);    // the state dies with the element
+    document.removeEventListener('keydown', this.onDocKeydown);
+  }
+
+  render() {
+    return html`
+      <button ${ref(this.toggleRef)}
+        aria-expanded=${this.open ? 'true' : 'false'}
+        @click=${() => { this.open = !this.open; }}>Menu</button>
+      <nav ?hidden=${!this.open}><slot></slot></nav>
+    `;
+  }
+}
+NavDrawer.register('nav-drawer');
+```
+
+This repo's own website is the worked example. Before commit `b80de906` the docs drawer and the header menu were exactly the first shape, and every accessibility bug their tests now pin came out of the split. `website/components/docs-drawer.ts` and `website/components/site-nav-menu.ts` are the second shape, and `website/AGENTS.md` records the app-level version of these rules under "What stays inline script in the root layout".
+
 ## Reactive properties: the base-class factory
 
 Reactive properties are declared by passing their shape into `WebComponent({ ... })`. The types flow automatically to `this.<prop>`, so there is NO `static properties` block and NO `declare` line (a `static properties` block throws at runtime, caught by `no-static-properties`).
@@ -48,7 +134,7 @@ The bare form is shorthand: `count: Number` means `prop(Number)`. Use `prop()` t
 | Option | Default | Meaning |
 |---|---|---|
 | `type` | `String` | Constructor feeding the default attribute converter |
-| `reflect` | `false` | Property changes write back to the HTML attribute (a function value removes it instead, see below) |
+| `reflect` | `false` | Property changes write back to the HTML attribute (a value with no attribute representation removes it instead, see below) |
 | `state` | `false` | Internal-only. No attribute, not observed |
 | `attribute` | derived from name | The HTML attribute name the property rides |
 | `default` | none | Declarative initial value (a function runs per instance for a fresh object / array) |
@@ -59,6 +145,8 @@ For an array-typed prop pass `Array`, not `Object` (`array-prop-uses-array-type`
 
 **A `reflect: true` property holding a FUNCTION drops its attribute instead of writing one, and so does one holding an array that carries a function, unless the prop is `Object` or `Array` typed.** A function has no HTML attribute representation, and the serializations it would otherwise get are both useless and dangerous. `String(fn)` is the function's SOURCE, so a reflected `'use server'` action would ship its whole body, closure secrets included, to every visitor, and `JSON.stringify(fn)` is `undefined`, which lands in the attribute as the literal four-character string. So the reflection path treats a function like `null`, removes the attribute, and warns naming the property, the tag, and the attribute. This holds on both sides, since SSR and the client-side setter run the same path, and it holds for every property name (the leak was never specific to one called `action`). Two exceptions. A property with a custom `converter.toAttribute` runs that converter first and is left alone, because an author who writes one has taken responsibility for serializing whatever they are handed. And an `Object` or `Array` typed property CARRYING a function keeps its data, because `JSON.stringify` drops the function to `null` and omits the key, so `[1, 2, fn]` reflects as `[1,2,null]` with no source and nothing else lost. If you need a function on a component, use a plain property or a signal and do not mark it `reflect`.
 
+**An `Object` or `Array` typed reflected property whose value `JSON.stringify` cannot serialize AT ALL drops its attribute the same way, and warns.** Three shapes do this: a cycle (an object or array that reaches itself, which arrives from a parent/child graph, a linked node, a memo table, or anything a library hands back with a back-reference), a `BigInt` anywhere inside the value, and an author `toJSON()` that throws. The line to keep straight is that a value which serializes WITH A GAP in it keeps its data (the carried-function case above), while one that does not serialize at all has no string to put in the attribute and so has no attribute representation, exactly like a function. The property itself is untouched and still holds the value; only the attribute goes. Before this guard the throw escaped reflection entirely, which meant a client upgrade threw before the component's first render, and an SSR render was swallowed by per-component error isolation, which shows an error box in dev and renders the component EMPTY on a page that still returned 200 in production. To reflect something about a graph-shaped value, reflect a derived scalar (an id, a count) and keep the graph on a non-reflected property. On the read side an attribute that is PRESENT but not parseable JSON reads back as `null` rather than as the raw string, on both the SSR and the client reader. An ABSENT attribute is a different case: neither reader sees it, so the property keeps its constructor value.
+
 **Never use a class-field declaration OR initializer** (`count = 0`, `student: Student = {...}`, `todos!: Todo[]`). Under `useDefineForClassFields` even a type-only `todos!: Todo[]` compiles to define an own property after `super()`, which clobbers the prototype's reactive accessor and silently breaks reactivity. Only declare props in the factory and read/write them off `this`. The `reactive-props-no-class-field` rule catches this.
 
 ## Signals are the default state primitive

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

@@ -288,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/routing-and-pages.md

@@ -179,6 +179,8 @@ 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.
 
+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

@@ -189,6 +189,14 @@ 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/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/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}`;