@webjsdev/cli 0.10.21 → 0.10.23

package/bin/webjs.js

@@ -47,7 +47,7 @@ const USAGE = `webjs commands:
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check [--json]                            Run correctness checks on the app (--json emits structured violations)
   webjs mcp                                       Start the read-only MCP server (routes / actions / components / check)
-  webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook)
+  webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout elision)
   webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs typecheck [tsc args...]                   Type-check the app with the project's tsc --noEmit (non-zero on errors)
   webjs create <name> [--template full-stack|api|saas] [--db sqlite|postgres] [--runtime node|bun] [--no-install]  Scaffold a new webjs app

package/lib/create.js

@@ -918,7 +918,6 @@ export type ActionResult<T> =
 
   await writeFile(join(appDir, 'app', 'layout.ts'), `// webjs-scaffold-placeholder. This is the example app chrome (brand, nav, content-width container). Adapt it to your app, then delete this line. webjs check fails while the marker remains.
 import { html, cspNonce } from '@webjsdev/core';
-import '@webjsdev/core/client-router';
 import '#components/theme-toggle.ts';
 // Webjs UI components are tiered:
 //   - Tier 1 (button, card, input, label, alert, badge, separator, etc.) are
@@ -975,6 +974,26 @@ export default function RootLayout({ children }: { children: unknown }) {
           mq.addEventListener('change', apply);
         } catch (_) {}
       })();
+      // The header is position:fixed (not sticky): a sticky header flickers on
+      // iOS WebKit during a client-router nav. fixed leaves normal flow, so
+      // --header-h reserves its height for the content below. Measured here so
+      // it tracks the real (responsive) height; degrades fine with no JS via
+      // the :root default.
+      (function(){
+        function measure(){
+          try {
+            var hdr = document.querySelector('header');
+            if (!hdr) return;
+            var apply = function(){
+              document.documentElement.style.setProperty('--header-h', hdr.offsetHeight + 'px');
+            };
+            apply();
+            if (window.ResizeObserver) new ResizeObserver(apply).observe(hdr);
+          } catch (_) {}
+        }
+        if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', measure);
+        else measure();
+      })();
     </script>
     <script src="/public/tailwind-browser.js"></script>
     <!--
@@ -1064,7 +1083,9 @@ ${SHADCN_THEME}
       }
       /* Body + pseudo-elements utility classes can't reach. */
       html, body { margin: 0; }
+      :root { --header-h: 56px; } /* fixed-header offset, kept exact by the script above */
       body {
+        padding-top: var(--header-h);
         background: var(--bg);
         color: var(--fg);
         font: 16px/1.65 var(--font-sans);
@@ -1073,7 +1094,7 @@ ${SHADCN_THEME}
       ::selection { background: var(--accent-tint); color: var(--fg); }
     </style>
 
-    <header class="sticky top-0 z-20 flex items-center gap-6 px-4 sm:px-6 py-3 border-b border-border bg-[color-mix(in_oklch,var(--bg)_75%,transparent)] backdrop-blur-[18px]">
+    <header class="fixed inset-x-0 top-0 z-20 flex items-center gap-6 px-4 sm:px-6 py-3 border-b border-border bg-[color-mix(in_oklch,var(--bg)_75%,transparent)] backdrop-blur-[18px]">
       <a href="/" class="mr-auto inline-flex items-center gap-2 no-underline text-fg font-semibold text-[15px] leading-none tracking-tight">
         <span>${name}</span>
       </a>

package/lib/doctor.js

@@ -36,7 +36,7 @@
 
 import { existsSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { checkNodeInline } from './node-preflight.js';
 
 /**
@@ -795,6 +795,53 @@ function checkGitHook(appDir) {
  *     instead of a real live resolve / node_modules read.
  * @returns {Promise<DoctorResult[]>}
  */
+/**
+ * Advisory (#646): name why a page/layout SHIPS its module to the browser
+ * instead of being elided. A page/layout that is a pure carrier (import-only
+ * #605 / inert #179) stays out of the browser; one that ships whole is pinned
+ * by a specific client-effecting NON-component in its closure (a util touching
+ * a client global, a module-scope side effect, a bare side-effect import) or by
+ * its own client work. This turns that invisible #605/#179 regression into a
+ * named line. WARN only: a page legitimately MAY ship, and the analyser is
+ * biased toward shipping by design (server AGENTS invariant 7), so this is a
+ * "you may not have intended this" hint, never a hard fail.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+async function checkElisionCarriers(appDir) {
+  const name = 'Page/layout elision (carrier hygiene)';
+  let report;
+  try {
+    const { analyzeAppElision } = await import('@webjsdev/server');
+    report = await analyzeAppElision(appDir);
+  } catch {
+    // Analysis unavailable (no app, malformed, server import failed): no advice.
+    return { name, status: 'pass', message: 'not analysed (no routable app or analysis unavailable)' };
+  }
+  if (!report.analysed) {
+    return { name, status: 'pass', message: 'not analysed (no routable app, or elision is disabled)' };
+  }
+  if (report.shipped.length === 0) {
+    return { name, status: 'pass', message: 'every page/layout is elided (a pure import-only or inert carrier)' };
+  }
+  const rel = (f) => relative(appDir, f) || f;
+  // Name the FIRST client-effecting blocker (there may be more than one; the
+  // module stays shipped until every such blocker is moved out).
+  const lines = report.shipped.map(({ file, blocker, reason }) =>
+    blocker
+      ? `${rel(file)} ships whole. Its first client-effecting blocker is ${rel(blocker)}, which ${reason} and is not a component`
+      : `${rel(file)} ships whole because it ${reason}`,
+  );
+  return {
+    name,
+    status: 'warn',
+    message:
+      `${report.shipped.length} page/layout module(s) ship to the browser instead of being elided:\n` +
+      lines.map((l) => `    ${l}`).join('\n'),
+    fix: 'Move the client work out of the page/layout closure (into a component, or a .server module reached through an action) so the carrier can be elided, or accept that it ships. See agent-docs/components.md.',
+  };
+}
+
 export async function runDoctorChecks(appDir, opts = {}) {
   const cliDir = opts.cliDir || new URL('.', import.meta.url).pathname;
   const results = await Promise.all([
@@ -806,6 +853,7 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkWebjsVersions(appDir),
     checkImportmapCoherence(appDir, opts),
     Promise.resolve(checkGitHook(appDir)),
+    checkElisionCarriers(appDir),
   ]);
   return results;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.21",
+  "version": "0.10.23",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/rules/workflow.md

@@ -137,6 +137,7 @@ self-review loop.
   `static styles = css\`...\`` for scoped CSS.
 - Custom-element tag names are passed to `.register('tag-name')`. They are NOT
   a static field on the class.
+- **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - One function per server action file (`*.server.ts`).
 - Server-only code (a DB driver like `better-sqlite3`/`pg`, `node:*`, anything that needs Node APIs)
   goes only in `.server.{js,ts}` files, `route.ts` handlers, or
@@ -145,8 +146,22 @@ self-review loop.
   stub for the browser. `lib/` holds both server-only infra
   (the DB in `db/*.server.ts`) and browser-safe utilities (`lib/utils/cn.ts` with
   `cn`); follow the same rule per file.
-- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat`
-  ship. Use plain template-literal expressions
+- Keep pages and layouts as pure carriers so their modules stay out of the
+  network tab. A page/layout never hydrates; the framework drops its module
+  from the browser as long as its only browser job is registering the
+  components it imports. It starts shipping its own module (invisible in tests,
+  an elision verdict) the moment its closure does any OTHER client work. So do
+  not give a page/layout module-scope client work (a top-level call, a
+  `window` / `document` / `customElements` access, a bare side-effect import,
+  or a `@webjsdev/core/client-router` import: routing is automatic), and do not
+  import a client-global-touching non-component util into it. Put client
+  behaviour in a component, server-only code in `.server.{js,ts}`. Self-check:
+  `page.ts` / `layout.ts` should not appear in the browser's network tab.
+- Directives: webjs exports the lit directives with no clean native equivalent
+  (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` /
+  `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`).
+  `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported.
+  For those, use plain template-literal expressions
   (`class=${active ? 'btn active' : 'btn'}`, `style=${'color:' + color}`,
   `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in
   `firstUpdated`) instead of Lit's `classMap` / `styleMap` / `ref` / `when` /

package/templates/.claude/hooks/block-raw-htmlelement.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Guardrail: a webjs custom element must extend the framework's WebComponent
+# base class, never raw HTMLElement.
+#
+# Why: a raw `extends HTMLElement` custom element is invisible to the webjs
+# elision analyser (it ships unconditionally, defeats display-only elision, and
+# keeps any importing page/layout from being import-only), it bypasses the
+# SSR / lifecycle / reactive-prop machinery, and it usually applies its DOM work
+# in connectedCallback (client-only), a progressive-enhancement bug.
+#
+# Scope: fires ONLY when the edited file lives in a webjs project (a package.json
+# up the tree depends on @webjsdev/*), so vanilla-JS projects are never touched.
+# Exempts framework source (packages/, node_modules/), since the framework
+# legitimately defines WebComponent and the SSR-inert <webjs-frame> / -stream /
+# -suspense primitives on raw HTMLElement. Honours an explicit escape-hatch
+# marker `webjs-allow-htmlelement: <reason>` for the rare native-API case
+# WebComponent cannot express (a form-associated element via ElementInternals,
+# a customized built-in via `extends HTMLButtonElement`, etc.).
+#
+# PreToolUse contract: exit 0 = allow, exit 2 = block (message on stderr).
+#
+# NOTE: No em-dashes, spaces around hyphens as pauses, or semicolons as pauses
+# are allowed in comments per project rules.
+set -euo pipefail
+
+input=$(cat)
+fp=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+[ -z "$fp" ] && exit 0
+case "$fp" in
+  *.ts|*.tsx|*.js|*.jsx|*.mts|*.mjs) ;;
+  *) exit 0 ;;
+esac
+
+# The text being written: Write -> .content, Edit -> .new_string, MultiEdit -> .edits[]?.new_string.
+content=$(printf '%s' "$input" | jq -r '(.tool_input.content // empty), (.tool_input.new_string // empty), (.tool_input.edits[]?.new_string // empty)')
+[ -z "$content" ] && exit 0
+
+# Only a class that extends raw HTMLElement is the target (not `typeof
+# HTMLElement` guards, not `instanceof HTMLElement`, not another base).
+printf '%s' "$content" \
+  | grep -Eq 'class[[:space:]]+[A-Za-z_$][A-Za-z0-9_$]*[[:space:]]+extends[[:space:]]+HTMLElement([[:space:]{]|$)' \
+  || exit 0
+
+# Explicit, acknowledged exception.
+printf '%s' "$content" | grep -qi 'webjs-allow-htmlelement' && exit 0
+
+# Framework source / installed deps are never app components.
+case "$fp" in
+  */packages/*|*/node_modules/*|packages/*|node_modules/*) exit 0 ;;
+esac
+
+# Webjs context: a package.json up the tree references @webjsdev/* (a webjs app
+# or the framework repo). Outside a webjs project this hook is a no-op.
+dir=$(CDPATH= cd -- "$(dirname -- "$fp")" 2>/dev/null && pwd || dirname -- "$fp")
+is_webjs=0
+while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+  if [ -f "$dir/package.json" ] && grep -q '@webjsdev/' "$dir/package.json" 2>/dev/null; then
+    is_webjs=1
+    break
+  fi
+  dir=$(dirname -- "$dir")
+done
+[ "$is_webjs" -eq 0 ] && exit 0
+
+cat >&2 <<'MSG'
+BLOCKED: a webjs custom element must extend the WebComponent base class, not raw HTMLElement.
+
+  import { WebComponent } from '@webjsdev/core';
+  class MyThing extends WebComponent {
+    render() { return html`...`; }
+  }
+  MyThing.register('my-thing');
+
+A display-only element (just host classes / static markup) can set its classes
+in the constructor (runs at SSR, so it is progressive-enhancement-safe) and
+stays elidable, so it ships zero JS. A raw `extends HTMLElement` element cannot
+be elided, defeats import-only routes, and applies its work client-only.
+
+If WebComponent genuinely cannot express this (a rare native-API edge case),
+add a marker comment containing `webjs-allow-htmlelement: <reason>` to the file
+to acknowledge the exception, and this guardrail will allow it.
+MSG
+exit 2

package/templates/.claude/settings.json

@@ -1,6 +1,15 @@
 {
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/block-raw-htmlelement.sh"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
         "hooks": [

package/templates/.cursorrules

@@ -113,8 +113,10 @@ self-review loop.
 - Shadow-DOM components opt in with `static shadow = true` and use `static styles = css` for scoped CSS, not inline styles. That is the right home for scoped CSS.
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
+- **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Server-only code (the DB driver `better-sqlite3` / `pg`, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files.
-- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. Use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
+- Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported. For those, use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
 - **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback` is never called on the server, so anything there only runs after hydration. Initial data for components comes from the page function (server-side fetch plus pass as attribute/property) OR from an `async render()` in the component itself (`const u = await getUser(this.uid)`, which SSR awaits so the data is in the first paint), NOT from `fetch` calls in `connectedCallback`. Prefer the co-located `async render()` over prop-drilling; `renderFallback()` is the optional re-fetch loading state (never first paint), and a `Task` is for genuinely client-only data. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
 - **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Because layouts persist across navigation, put shared chrome (sidenav, header) in `layout.ts` and page-specific content in `page.ts`. For validation errors, return 4xx HTML from a `route.ts` POST handler; the router renders it in place preserving the user's input. For non-layout swap regions, wrap in `<webjs-frame id="...">`. See "Client navigation patterns" in AGENTS.md.
+- **Keep pages and layouts as pure carriers** so their modules stay out of the network tab. A page/layout never hydrates; the framework drops its module from the browser as long as its only browser job is registering the components it imports. It starts shipping its own module (invisible in tests, an elision verdict) the moment its closure does any OTHER client work. Don't give a page/layout module-scope client work (a top-level call, a window/document/customElements access, a bare side-effect import, or a @webjsdev/core/client-router import: routing is automatic) or import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in .server.{js,ts}. Self-check: page.ts/layout.ts should not appear in the browser's network tab.
 - See AGENTS.md for the complete directive decision guide

package/templates/.github/copilot-instructions.md

@@ -107,13 +107,14 @@ each change must include.
 - **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
-- Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `static styles` for shadow-DOM components, call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults via the `default` option or the constructor, never a class-field initializer (`reactive-props-no-class-field`).
+- Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `static styles` for shadow-DOM components, call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults via the `default` option or the constructor, never a class-field initializer (`reactive-props-no-class-field`). Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type`. **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
 - Server actions: *.server.ts files with one exported async function each.
 - Server-only code (a DB driver like better-sqlite3/pg, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
-- Directives: webjs ships only `unsafeHTML`, `live`, and `repeat`. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. Use plain template-literal expressions and lifecycle hooks instead.
+- Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported; use plain template-literal expressions instead.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'
 - Task: import { Task, TaskStatus } from '@webjsdev/core/task'
 - Routing: file-based under app/ (page.ts, layout.ts, route.ts, middleware.ts).
+- Keep pages and layouts as pure carriers so their modules stay out of the network tab. A page/layout never hydrates; the framework drops its module from the browser as long as its only browser job is registering the components it imports. It starts shipping its own module (invisible in tests, an elision verdict) the moment its closure does any OTHER client work. Don't give a page/layout module-scope client work (a top-level call, a window/document/customElements access, a bare side-effect import, or a @webjsdev/core/client-router import: routing is automatic) or import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in .server.{js,ts}. Self-check: page.ts/layout.ts should not appear in the network tab.
 - Component state lives in signals from @webjsdev/core. Module-scope signals share state across components; instance signals (created in the constructor) carry component-local state. Reactive properties (declared via the `WebComponent({ ... })` factory) are for HTML attributes and .prop=${...} hydration.
 - Don't skip tests or documentation updates.

package/templates/AGENTS.md

@@ -562,7 +562,6 @@ CI gate).
 
 ```ts
 import { html, css, WebComponent } from '@webjsdev/core';
-import '@webjsdev/core/client-router';              // enable SPA nav
 import { unsafeHTML, live } from '@webjsdev/core/directives';
 import { createContext } from '@webjsdev/core/context';
 import { Task } from '@webjsdev/core/task';
@@ -721,6 +720,9 @@ Practical consequences for agents writing webjs code.
 | Class-field initializer for a reactive property (`student: Student = {...}`) | Silently breaks reactivity (overwrites the framework accessor) | Pass the shape to the base-class factory `WebComponent({ student: Object })` and set the default in the constructor (flagged by `reactive-props-no-class-field`) |
 | `@property()` decorator | Banned by invariant 10 (erasable TS) | Pass the shape to the base-class factory `WebComponent({ ... })` (the only supported form) |
 | Hand-written `static properties = { ... }` | Throws at construction (the factory owns property setup) | Pass the same shape to the base-class factory `WebComponent({ ... })` (flagged by `no-static-properties`) |
+| Array-typed prop declared with `Object` (`items: prop<Tag[]>(Object)`) | Works (Object and Array share one JSON converter), but misstates the prop's shape | Pass the `Array` constructor (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type` |
+| Extending raw `HTMLElement` directly | Bypasses SSR, reactive properties, elision, and lifecycle hooks; keeps the component from being elided | Always subclass `WebComponent` (or the factory form `WebComponent({...})`) |
+| Module-scope client work in a `page.ts` / `layout.ts` (a top-level call, a `window` / `document` / `customElements` access, a `@webjsdev/core/client-router` import), or importing a client-global-touching non-component util into one | The page/layout module stops being a droppable carrier and SHIPS its own JS to the browser (it shows up in the network tab); invisible in tests because it is an elision verdict, not a behaviour change | Keep pages/layouts pure carriers (their only browser job is registering the components they import; routing is automatic). Put client behaviour in a component, server-only code in `.server.{js,ts}`. Self-check: `page.ts` / `layout.ts` should not appear in the network tab |
 | Scoped `static styles = css` or an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component | Scoped block does nothing without `static shadow = true`; inline `<style>` class names leak globally | Tailwind utilities (the light-DOM default); or `static shadow = true` for genuinely scoped CSS |
 | `willUpdate` computing SSR-visible derived state | Works (runs at SSR), but overriding it opts the component out of elision | Fine for interactive components; for display-only, derive inline in `render()` |
 | `this.hasAttribute` / `getAttribute` in `render()` | Works (server attribute shim backs the attribute methods at SSR) | Read attributes directly, or declare a reactive prop via the base-class factory `WebComponent({ ... })` |
@@ -787,8 +789,9 @@ reference: https://docs.webjs.com/docs/server-actions
 
 ## Client navigation patterns (auto-magic)
 
-The client router enables itself when the scaffolded root layout imports
-`@webjsdev/core/client-router`. After that, **every `<a href>` and
+The client router enables itself automatically: it turns on whenever
+`@webjsdev/core` loads in the browser, which happens on any page that
+ships a component, so there is no import to add. **Every `<a href>` and
 `<form action>` on the page is enhanced into a partial-swap navigation
 or submission automatically**. You don't call a router API. Write
 standard HTML; the swap happens.

package/templates/CONVENTIONS.md

@@ -403,6 +403,7 @@ modules/
 - **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of a DB driver (`better-sqlite3` / `pg`) or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. The DB lives in `db/*.server.ts`; `lib/` holds other server-only infra and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files."
 - Routes (`app/**/page.ts`, `app/**/route.ts`) must be thin: import logic from modules
 - **Fetch server data in the component that needs it, with an `async render()`, not by prop-drilling.** A leaf component can write `const u = await getUser(this.uid)` directly in `render()`; SSR awaits it so the data is in the first paint, and the client uses stale-while-revalidate on a re-fetch. Reach for `renderFallback()` only to show a re-fetch loading state, and `Task` / signals only for genuinely client-only data (a `Task` shows its pending state at SSR, losing first-paint data). Do not put `await getData()` in a page / layout when a leaf component can own it (page fetches run sequentially, a route-level waterfall).
+- **Keep pages and layouts as pure carriers, so their modules stay out of the network tab.** A page/layout never hydrates; the framework drops its module from the browser as long as its only browser-relevant job is registering the components it imports. It starts shipping its own module (invisible in tests) the moment its closure does any OTHER client work. So do not give a page/layout module-scope client work (a top-level call, a `window` / `document` / `customElements` access, a bare side-effect import, or a `@webjsdev/core/client-router` import: routing is automatic), and do not import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in `.server.{js,ts}`. Self-check: `page.ts` / `layout.ts` should not appear in the browser's network tab.
 
 ---
 
@@ -505,7 +506,7 @@ SSR, page actions, server-action RPC, auth + CSRF), drive
 
 ```ts
 import { createRequestHandler } from '@webjsdev/server';
-import { testRequest, getCsrf, invokeActionForTest, loginAndGetCookies, withSessionCookie }
+import { testRequest, invokeActionForTest, loginAndGetCookies, withSessionCookie }
   from '@webjsdev/server/testing';
 
 const app = await createRequestHandler({ appDir: process.cwd(), dev: true });
@@ -523,8 +524,9 @@ const out = await invokeActionForTest(app, 'modules/posts/actions/create.server.
 
 Prefer `invokeActionForTest` over a direct import of the action when you want
 to verify the production contract: it exercises the wire serializer (a `Date` /
-`Map` arg survives), CSRF, and prod error sanitization, which a direct call
-bypasses. The saas template's `test/auth/auth.test.ts` is a worked example.
+`Map` arg survives), the Origin / Sec-Fetch-Site CSRF check (it models a
+same-origin POST), and prod error sanitization, which a direct call bypasses.
+The saas template's `test/auth/auth.test.ts` is a worked example.
 
 This is also why the auth test lives at `test/auth/auth.test.ts` (the
 feature-folder convention), NOT `test/unit/auth.test.ts`. Test KIND is a
@@ -678,9 +680,10 @@ Reactive properties are declared one way: pass the properties shape directly to
 - **If a light-DOM component authors its own custom CSS (a `<style>` block in `render()` or an imported stylesheet), every class selector MUST be prefixed with the component's tag name.** Either pattern works. Pick one and stay consistent:
   - `.my-widget__body`, `.my-widget__title` (BEM-ish)
   - `my-widget .body`, `my-widget .title` (descendant selector)
+- **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Tag name must contain a hyphen (HTML spec)
 - Always call `Class.register('tag')`. That's the standard DOM API.
-- **Reactive props are declared via the base-class factory `WebComponent({ ... })`.** A hand-written `static properties = { ... }` throws at construction (`webjs check` flags it via `no-static-properties`). Never write `propName = value` or `propName: Type = value` as a class-field initializer on a reactive prop. It compiles to `Object.defineProperty(this, …)` after `super()` and clobbers the framework's reactive accessor, silently breaking re-renders (`webjs check` flags this via `reactive-props-no-class-field`). Set defaults via the `default` option or in the constructor.
+- **Reactive props are declared via the base-class factory `WebComponent({ ... })`.** A hand-written `static properties = { ... }` throws at construction (`webjs check` flags it via `no-static-properties`). Never write `propName = value` or `propName: Type = value` as a class-field initializer on a reactive prop. It compiles to `Object.defineProperty(this, …)` after `super()` and clobbers the framework's reactive accessor, silently breaking re-renders (`webjs check` flags this via `reactive-props-no-class-field`). Set defaults via the `default` option or in the constructor. Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`): the two share one JSON converter so neither crashes, but `Array` states the shape and `webjs check` flags the `Object` form via `array-prop-uses-array-type`.
 - Component state lives in signals. Import `signal` from `@webjsdev/core`, read via `signal.get()` inside `render()`, write via `signal.set(value)`. Module-scope signals share state across components; instance signals (created in the constructor) carry component-local state. Reactive properties (declared via the factory) wrap HTML attributes, attribute reflection, and `.prop=${value}` SSR hydration.
 - Use lifecycle hooks (`firstUpdated`, `updated`) only when needed
 
@@ -729,6 +732,17 @@ color (via the `@theme` tokens), typography, borders, radius, shadows,
 and interaction states (hover/focus/active/disabled, dark mode). Light
 DOM does not scope styles, so utilities apply directly.
 
+**Pin a header with `position: fixed`, never `position: sticky`.** A
+sticky header flickers its background for one frame on iOS WebKit (every
+iOS browser) during a client-router navigation, because the preserved
+header plus the scroll-to-top trips a WebKit sticky-repaint bug that the
+usual GPU-promotion hacks (`translateZ`, `will-change`) do NOT fix. Use
+`position: fixed` and reserve the header height on the content with a
+`--header-height` variable (the scaffolded `app/layout.ts` does exactly
+this, kept exact by a `ResizeObserver`). It is iOS-only, invisible on
+desktop, Android, and in DevTools emulation, so it shows only on a real
+device.
+
 **The lit muscle-memory trap.** If you have written lit, the habit is to
 scope CSS in a shadow root (`static styles = css\`\``) or write an inline
 `<style>` with semantic class names (`.hero`, `.feature`, `.card`) for