@webjsdev/cli 0.10.20 → 0.10.22

package/lib/create.js

@@ -17,7 +17,7 @@ import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
-import { bunifyProse, bunifyDockerfile, bunifyCi } from './runtime-rewrite.js';
+import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -532,11 +532,12 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // touches npm/npx command tokens, so the test code itself is unaffected.
     'test/hello/browser/hello.test.js', 'test/hello/e2e/hello.test.ts',
   ]);
-  // compose.yaml needs NO bun transform: it builds from the (node-base + bun
-  // binary) Dockerfile and inherits its `bun --bun run start` CMD, and its
-  // healthcheck `node -e` works because the Node base provides node.
+  // compose.yaml builds from the (pure oven/bun) Dockerfile and inherits its
+  // `bun --bun run start` CMD; only its healthcheck needs switching off node
+  // (the pure Bun image has no node), which bunifyCompose does.
   const FILE_REWRITE = {
     'Dockerfile': bunifyDockerfile,
+    'compose.yaml': bunifyCompose,
     '.github/workflows/ci.yml': bunifyCi,
   };
   for (const f of templateFiles) {
@@ -917,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
@@ -974,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>
     <!--
@@ -1063,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);
@@ -1072,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/runtime-rewrite.js

@@ -23,14 +23,11 @@
  *   - the `dev` / `start` scripts force `bun --bun` (the server is Bun),
  *   - every other command stays `bun run` / `webjs ...` (runs on Node via the
  *     `webjs` bin's `#!/usr/bin/env node` shebang),
- *   - the Dockerfile keeps the `node:24-alpine` base and COPIES in the Bun
- *     binary (the server serves on Bun, but Node + `npx` stay available).
- *     A pure `oven/bun` base would need the installed `@webjsdev/cli` to be
- *     npx-free (#570), but a scaffolded app pins `@webjsdev/cli: latest`, and
- *     until the #570 build is the published `latest` an installed CLI may still
- *     shell `npx drizzle-kit` for the boot `webjs db migrate`, which a pure
- *     `oven/bun` image lacks. The node base works with ANY installed CLI; a
- *     future scaffold can drop to a pure `oven/bun` base once #570 is published.
+ *   - the Dockerfile is a pure `oven/bun:1` base (#595). This is safe as of
+ *     `@webjsdev/cli@0.10.20` (#570): `webjs db migrate` resolves drizzle-kit
+ *     and runs it under Bun (no `npx`), so a Node-less image works. (Before
+ *     #570 shipped as `latest`, this stayed on `node:24-alpine` + a copied Bun
+ *     binary, since the installed CLI could still shell `npx`.)
  */
 
 /**
@@ -50,10 +47,17 @@
 export function bunifyProse(s) {
   return s
     // Prose claim about the Dockerfile CMD (AGENTS.md dev-start parity section);
-    // the bun Dockerfile's CMD becomes `bun --bun run start`. The base stays
-    // node:24-alpine (+ a copied Bun binary), so the "pins node:24-alpine" prose
-    // is still accurate and is NOT rewritten.
+    // the bun Dockerfile's CMD becomes `bun --bun run start`.
     .replaceAll('`CMD ["npm", "start"]`', '`CMD ["bun", "--bun", "run", "start"]`')
+    // The "Containerized deploy" prose describes the node template's
+    // node:24-alpine base; the bun Dockerfile is a pure oven/bun:1 image (#595),
+    // so rewrite the base claim to match what the bun app actually ships. (The
+    // trailing `npm start` is rewritten to `bun --bun run start` by the generic
+    // rule below.)
+    .replaceAll(
+      'Dockerfile pins `node:24-alpine` (the same Node major CI uses), installs\ndeps (no build step, since Drizzle has no codegen), and starts via',
+      'Dockerfile is a pure `oven/bun:1` image (no Node, since `webjs db migrate`\nresolves drizzle-kit and runs under Bun with no `npx`, #570), installs deps\nwith `bun install` (no build step, since Drizzle has no codegen), and starts via',
+    )
     // The "Running on Bun" section frames Bun as opt-in ("force it with --bun").
     // In a bun-flavored app the dev/start scripts ALREADY embed --bun, so reframe
     // it as the configured default.
@@ -92,64 +96,73 @@ export function bunifyProse(s) {
 /**
  * Rewrite the scaffolded Dockerfile for Bun.
  *
- * Base decision (acceptance criterion): KEEP the `node:24-alpine` base and COPY
- * in the Bun binary, NOT a pure `oven/bun` image. Justification: the server
- * serves on Bun (`bun --bun run start` selects the `Bun.serve` listener), but a
- * scaffolded app pins `@webjsdev/cli: latest`, and until the npx-free CLI (#570)
- * is the published `latest`, the INSTALLED CLI may still shell `npx drizzle-kit`
- * for the boot-time `webjs db migrate`. A pure `oven/bun` image has NO `npx`
- * (verified), so that migrate would fail at container start. Keeping the Node
- * base gives `npx` + the Node toolchain while the copied Bun binary serves the
- * app on Bun, so the image works with ANY installed CLI version (the same
- * pattern the in-repo example apps deploy with). `bun install` (not `npm
- * install`) uses the committed `bun.lock`, and `trustedDependencies` lets
- * better-sqlite3's prebuild postinstall run. Once cli@#570 is the published
- * `latest`, a future scaffold can drop to a pure `oven/bun` base.
+ * Base decision (acceptance criterion): a pure `oven/bun:1` image (no Node).
+ * Safe as of `@webjsdev/cli@0.10.20` (#570): `webjs db` / `webjs test` resolve
+ * their tools (drizzle-kit, wtr) and spawn them with the current runtime instead
+ * of `npx`, so the boot-time `webjs db migrate` runs under Bun with no Node
+ * toolchain. (Before #570 was the published `latest`, this stayed on a
+ * `node:24-alpine` base with a copied Bun binary, since the installed CLI could
+ * still shell `npx`, which a pure Bun image lacks. #595 flipped it once the
+ * npx-free CLI shipped.) `oven/bun:1` is Debian-based: `ca-certificates` ship in
+ * the image and better-sqlite3 fetches its glibc prebuild on `bun install`
+ * (gated by `trustedDependencies`), so no build toolchain is needed.
  *
  * @param {string} s
  * @returns {string}
  */
 export function bunifyDockerfile(s) {
   return s
-    // Top comment: explain the node-base + copied-bun-binary rationale.
+    // Top comment: explain the pure oven/bun base.
     .replace(
       /# webjs serves \.ts directly[\s\S]*?since the built-in stripper and recursive fs\.watch need it\.\n/,
       '# webjs serves .ts directly by stripping types at the runtime layer, so there is\n' +
       '# NO JavaScript build step (webjs is buildless end to end; there is no bundler or\n' +
-      '# esbuild fallback). This image SERVES the app on **Bun** (`bun --bun run start`\n' +
-      '# selects the Bun.serve listener) while keeping the `node:24-alpine` base so the\n' +
-      '# Node toolchain (npx) stays available for the boot-time `webjs db migrate`. The\n' +
-      '# Bun binary is copied in below. Do not lower the Node base below 24 (the floor the\n' +
-      '# CI workflow and the framework pin enforce), since the toolchain and recursive\n' +
-      '# fs.watch need it. (A pure oven/bun base, no Node, is possible once your installed\n' +
-      '# @webjsdev/cli resolves drizzle-kit without npx; the node base works regardless.)\n',
+      '# esbuild fallback). This image runs the app on **Bun**: the type-strip comes from\n' +
+      '# `amaro`, the server serves via Bun.serve, and `webjs db migrate` runs under Bun\n' +
+      '# (the CLI resolves drizzle-kit without npx, #570), so no Node is needed. webjs also\n' +
+      '# runs on Node 24+; for a Node base instead, swap to `node:24-alpine` and start with\n' +
+      '# `npm start`.\n',
     )
-    // Copy the Bun binary (musl, matching the alpine base) in after the apk step.
+    .replace('FROM node:24-alpine', 'FROM oven/bun:1')
+    // Debian base: ca-certificates already present, no `apk`. Drop the alpine line.
     .replace(
-      'RUN apk add --no-cache ca-certificates\n',
-      'RUN apk add --no-cache ca-certificates\n\n' +
-      '# Bun binary, so the server serves on Bun while the Node toolchain above stays\n' +
-      '# available for the boot `webjs db migrate` (which may shell npx, depending on the\n' +
-      '# installed @webjsdev/cli version) and the shebang bins.\n' +
-      'COPY --from=oven/bun:1-alpine /usr/local/bin/bun /usr/local/bin/bun\n',
+      /# ca-certificates for outbound TLS \(e\.g\. a managed Postgres\)\. better-sqlite3\n# is a prebuilt native module, so no build toolchain is needed here\.\nRUN apk add --no-cache ca-certificates\n\n/,
+      '# The Debian-based oven/bun image ships ca-certificates for outbound TLS (e.g. a\n# managed Postgres). better-sqlite3 fetches its glibc prebuild on `bun install`\n# (gated by trustedDependencies), so no build toolchain is needed.\n\n',
     )
     // Lockfile + install (bun.lock, bun install).
     .replace(
       '# package-lock.json is optional (it\'s absent when the app was scaffolded with\n# --no-install); the glob keeps the COPY working with or without it.\nCOPY package.json package-lock.json* ./\nRUN npm install --no-audit --no-fund',
       '# bun.lock is optional (absent when scaffolded with --no-install); the glob keeps\n# the COPY working with or without it. trustedDependencies in package.json lets\n# better-sqlite3\'s native-prebuild postinstall run (bun skips postinstalls).\nCOPY package.json bun.lock* ./\nRUN bun install',
     )
-    // Entrypoint: serve on Bun. The healthcheck keeps `node -e` (the Node base
-    // provides node, so no change is needed there).
+    // Healthcheck: the pure Bun image has no node; use `bun -e`. Keep the
+    // dependency-free-probe comment accurate (the probe runs under Bun now).
+    .replace("(Node 24's built-in fetch, no curl/wget)", "(the runtime's built-in fetch, no curl/wget)")
+    .replace('CMD ["node", "-e", "fetch(', 'CMD ["bun", "-e", "fetch(')
+    // Entrypoint: serve on Bun.
     .replace(
       /# `npm start` is a thin alias[\s\S]*?the migrate no longer depends on an npm `prestart` hook\.\nCMD \["npm", "start"\]/,
       '# `bun --bun run start` runs the `start` script on Bun (the server serves via\n' +
       '# Bun.serve). `webjs start` runs the `webjs.start.before` step (`webjs db migrate`,\n' +
-      '# which shells drizzle-kit through the Node toolchain in this image), idempotent /\n' +
-      '# a no-op with no pending migrations, then serves on $PORT.\n' +
+      '# which resolves drizzle-kit and runs it under Bun, no npx, #570), idempotent / a\n' +
+      '# no-op with no pending migrations, then serves on $PORT.\n' +
       'CMD ["bun", "--bun", "run", "start"]',
     );
 }
 
+/**
+ * Rewrite compose.yaml for the pure-Bun image (#595): its healthcheck runs in
+ * the `oven/bun:1` container (compose's healthcheck overrides the Dockerfile's),
+ * which has no `node`, so switch `node -e` to `bun -e`. compose otherwise builds
+ * from the Dockerfile and inherits its `bun --bun run start` CMD, so nothing
+ * else changes.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function bunifyCompose(s) {
+  return s.replace('test: ["CMD", "node", "-e", "fetch(', 'test: ["CMD", "bun", "-e", "fetch(');
+}
+
 /**
  * Rewrite the GitHub Actions CI workflow for Bun: ADD `oven-sh/setup-bun`
  * alongside `actions/setup-node` (kept, because the `webjs` test/db/check

package/package.json

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

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

@@ -34,6 +34,13 @@ FIRST, before writing any code:
    - If on main/master: create a feature branch before editing.
    - If on a feature branch: verify it matches the current task.
 2. Sync: `git fetch origin && git rebase origin/main` if behind.
+3. If more than one agent may work this repo at once, use a DEDICATED git
+   worktree per task (`git worktree add -b <branch> ../<repo>-<slug> origin/main`,
+   `cd` in, work there, `git worktree remove` after merge), never a shared
+   checkout. Two agents in one directory collide: a `git checkout` in one moves
+   HEAD under the other, so commits land on the wrong branch. Git enforces
+   one-branch-per-worktree, so worktrees prevent it. A lone agent in a clean
+   checkout may use a plain branch.
 
 ## Autonomous mode (sandbox / no-prompt)
 
@@ -130,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
@@ -138,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

@@ -35,6 +35,12 @@ FIRST, before writing any code:
 2. Sync with parent: `git fetch origin && git log HEAD..origin/main --oneline`
    - If upstream has new commits: `git rebase origin/main` before starting.
    - Resolve any conflicts before proceeding with the task.
+3. If more than one agent may work this repo at once, use a DEDICATED git
+   worktree per task, not a shared checkout: `git worktree add -b <branch>
+   ../<repo>-<slug> origin/main`, `cd` in, work there, `git worktree remove`
+   after merge. Two agents in one directory collide (a `git checkout` in one
+   moves HEAD under the other, so commits land on the wrong branch). A lone
+   agent in a clean checkout may use a plain branch.
 
 ## Autonomous mode (sandbox / no-prompt)
 
@@ -107,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

@@ -32,6 +32,12 @@ FIRST, before writing any code:
    - If on main/master: create a feature branch before editing.
    - If on a feature branch: verify it matches the task at hand.
 2. Sync: `git fetch origin && git rebase origin/main` if behind.
+3. If more than one agent may work this repo at once, use a DEDICATED git
+   worktree per task (`git worktree add -b <branch> ../<repo>-<slug> origin/main`,
+   `cd` in, work there, `git worktree remove` after merge), never a shared
+   checkout. Two agents in one directory collide: a `git checkout` in one moves
+   HEAD under the other, so commits land on the wrong branch. A lone agent in a
+   clean checkout may use a plain branch.
 
 ## Autonomous mode (sandbox / no-prompt)
 
@@ -101,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 WebComponent, declare `static properties` (and `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.
+- 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).
-- 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 (static properties + declare) are for HTML attributes and .prop=${...} hydration.
+- 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/.hooks/pre-commit

@@ -11,9 +11,20 @@
 # here, so a commit stays fast and the test gate cannot be skipped by a
 # local --no-verify. The CI workflow runs `webjs check` + `webjs test`
 # on every push and pull request.
+#
+# Running more than one AI agent on this repo at once? Give each task its own
+# git worktree, not a shared checkout. Two agents in one working directory
+# collide: a `git checkout` in one moves HEAD under the other, so the next
+# commit lands on the wrong branch. Before committing, confirm the branch below
+# is the one you intended; if it moved, you are sharing a checkout. Isolate:
+#   git worktree add -b <branch> ../<app>-<task> origin/main && cd ../<app>-<task>
 
 BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null)
 
+# Surface the branch so a wrong-branch commit (a concurrent-agent HEAD move) is
+# visible in the commit output rather than silent.
+echo "[pre-commit] committing on branch: ${BRANCH:-<detached>}"
+
 if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
   echo ""
   echo "ERROR: Cannot commit directly to '$BRANCH'."

package/templates/AGENTS.md

@@ -163,8 +163,9 @@ entry, its own template parser. Inside `` html`…` `` templates you get:
 - Binding-aware completions: reachable tag names after `<`, and
   prefix-keyed attributes (`.prop` property names, `?bool` / plain
   hyphenated attribute names).
-- Diagnostics: value type-checks against `declare propName: T`, unquoted
-  `@`/`.`/`?` bindings, and expressionless `.prop` bindings.
+- Diagnostics: value type-checks against the reactive props declared in
+  `WebComponent({ ... })`, unquoted `@`/`.`/`?` bindings, and
+  expressionless `.prop` bindings.
 - Hover showing the component class / declared member type.
 
 In VS Code / Cursor / Windsurf, the **`webjs` extension** bundles this
@@ -561,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';
@@ -597,12 +597,13 @@ const secret = process.env.AUTH_SECRET;             // undefined (fail-closed)
 ```ts
 import { WebComponent, html, css } from '@webjsdev/core';
 
-export class Counter extends WebComponent {
-  static properties = { count: { type: Number } };
+// Recommended declare-free base-class factory style
+export class Counter extends WebComponent({
+  count: Number
+}) {
   static styles = css`button { padding: 8px 12px; }`;   // shadow-DOM only
   // static shadow = true;          // opt into shadow DOM (default: light DOM)
   // static lazy = true;             // download JS only when scrolled into view
-  declare count: number;             // TypeScript-only typed accessor
 
   constructor() {
     super();
@@ -629,8 +630,9 @@ the click handler is inert). Two consequences for how you write code:
 1. **Defaults for the first paint go in `constructor()`** (after
    `super()`), never as class-field initializers (which break
    reactivity) and never in `connectedCallback` (which the server
-   doesn't run). For Web Component properties with `declare`, set the
-   default in the constructor.
+   doesn't run). For reactive properties declared via the
+   `WebComponent({ ... })` factory, set the default in the constructor
+   or pass the `default` option (e.g. `prop(Number, { default: 0 })`).
 2. **`connectedCallback` is browser-only.** Use it for
    `localStorage`, viewport size, online status, or anything that
    genuinely can't be known on the server. Read the value, then
@@ -659,7 +661,8 @@ See [Progressive Enhancement](https://docs.webjs.dev/docs/progressive-enhancemen
 ## Lit muscle-memory gotchas (read if you have written lit before)
 
 Webjs's runtime API matches lit. The `WebComponent` base class,
-`static properties`, the lifecycle hooks, ReactiveControllers, the
+reactive properties (declared via the `WebComponent({ ... })` factory),
+the lifecycle hooks, ReactiveControllers, the
 directive set, `html` / `css` tagged templates. The **rendering
 model**, however, is different. Pure-lit patterns that work fine in a
 client-only lit app break in webjs's SSR pipeline or its reactivity
@@ -714,11 +717,15 @@ Practical consequences for agents writing webjs code.
 | Assuming an `async render()` always ships its module | A bare one (no other client signal) is ELIDED, so it costs zero JS and skips the on-hydration re-fetch, first paint unchanged | Rely on it for a fetch-and-display leaf. `static refresh = true` keeps the on-load refresh, `static shadow = true` always ships |
 | `window.X` / `document.X` in constructor or `render()` | SSR crash | Move to `connectedCallback` |
 | Top-level `import` of a browser-only library | SSR crash | Dynamic `import()` inside `connectedCallback` |
-| Class-field initializer for a reactive property (`student: Student = {...}`) | Silently breaks reactivity (overwrites the framework accessor) | `declare student: Student` plus constructor default |
-| `@property()` decorator | Banned by invariant 10 (erasable TS) | `static properties = { ... }` plus `declare` |
+| 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 via a `static properties` + `declare` reactive prop |
+| `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({ ... })` |
 | `ContextProvider` for server-known data | Default value during SSR, content shift on hydration | Pass via props from the page function |
 
 The full annotated catalog with code examples lives in the framework
@@ -782,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.
@@ -1218,7 +1226,14 @@ composition, so a nested shell ends up dropped by the HTML parser.
 
 ## Workflow expectations for AI agents
 
-1. Branch before editing. Never push to `main` directly.
+1. Branch before editing. Never push to `main` directly. **If more than one
+   agent may work this repo at once, give each task its own git worktree, not a
+   shared checkout** (`git worktree add -b <branch> ../<repo>-<slug> origin/main`,
+   `cd` in, work there, `git worktree remove` after merge). Two agents in one
+   working directory collide: a `git checkout` in one moves `HEAD` under the
+   other, so the next commit lands on the wrong branch. Git enforces
+   one-branch-per-worktree, so worktrees prevent it; a lone agent in a clean
+   checkout may use a plain branch.
 2. Every code change comes with a test, AGENTS.md / docs updates if the
    feature surface changed, `webjs check` passing. A unit test is not
    always enough: a component, hydration, the client router, or a server

package/templates/CONVENTIONS.md

@@ -60,6 +60,14 @@ even if the user doesn't explicitly ask.**
 3. If on a feature branch → verify it matches the current task
 4. Sync with parent: `git fetch origin && git rebase origin/main` if behind
 5. Don't mix unrelated work on the wrong branch
+6. **If more than one agent may work this repo at once, use a dedicated git
+   worktree per task, never a shared checkout.** Two agents in one working
+   directory collide: a `git checkout` in one moves `HEAD` under the other, so
+   the next commit lands on the wrong branch. Isolate each task:
+   `git worktree add -b <branch> ../<repo>-<slug> origin/main`, `cd` in, work
+   there, and `git worktree remove` after the PR merges. Git enforces
+   one-branch-per-worktree, so this makes the collision impossible. A lone agent
+   in a clean checkout may use a plain branch.
 
 ### After cloning: verify the toolchain
 
@@ -395,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.
 
 ---
 
@@ -635,10 +644,11 @@ Any stateful behavior with a Tier-2 element uses the element.
 ```ts
 import { WebComponent, html } from '@webjsdev/core';
 
-export class MyWidget extends WebComponent {
-  static properties = { label: { type: String }, count: { type: Number } };
-  declare label: string;
-  declare count: number;
+// Recommended declare-free base-class factory style
+export class MyWidget extends WebComponent({
+  label: String,
+  count: Number
+}) {
   // Light DOM is the default; Tailwind utility classes apply directly.
 
   constructor() {
@@ -660,16 +670,7 @@ export class MyWidget extends WebComponent {
 MyWidget.register('my-widget');
 ```
 
-`static properties` is the runtime declaration (reactive accessor,
-attribute coercion, reflection). `declare` types the field for
-TypeScript without emitting a class-field initializer that would
-clobber the reactive accessor at construction time. The two
-declarations together give you full intelligence in any tsserver-backed
-editor. See the Editor Setup docs for the standalone `@webjsdev/intellisense`
-(no Lit dependency) that extends this to tag / attribute intelligence
-inside `html\`…\`` templates (go-to-definition, binding-aware completions,
-value/binding diagnostics, hover); in VS Code / Cursor / Windsurf the
-`webjs` extension bundles it automatically.
+Reactive properties are declared one way: pass the properties shape directly to the base-class factory `WebComponent({ ... })` (e.g. `label: String`). The property types flow to `this.<prop>` with no `declare` lines needed, and the factory installs the reactive accessors so a class-field initializer can never clobber them. For per-property options use the `prop()` helper inside the shape (`count: prop(Number, { reflect: true })`, `mode: prop({ state: true })`); narrow a type with `prop<Student>(Object)`. Set defaults via the `default` option (`prop(Number, { default: 0 })`) or by assigning in the constructor after `super()`. A hand-written `static properties = { ... }` THROWS at construction (`no-static-properties`). The factory gives you full intelligence in any tsserver-backed editor. See the Editor Setup docs for the standalone `@webjsdev/intellisense` (no Lit dependency) that extends this to tag / attribute intelligence inside `html\`…\`` templates (go-to-definition, binding-aware completions, value/binding diagnostics, hover); in VS Code / Cursor / Windsurf the `webjs` extension bundles it automatically.
 
 **Rules:**
 - One component per file
@@ -678,17 +679,11 @@ value/binding diagnostics, hover); in VS Code / Cursor / Windsurf the
 - **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 use `declare propName: Type` (no value) plus a default in `constructor()` after `super()`.** Never write `propName = value` or `propName: Type = value` as a class-field initializer. It compiles to `Object.defineProperty(this, …)` after `super()` and clobbers the framework's reactive accessor, silently breaking re-renders. `webjs check` flags this via the `reactive-props-use-declare` rule.
-- 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 (`static properties =
-  { foo: { type: ... } }` with a sibling `declare foo: T`) wrap HTML
-  attributes, attribute reflection, and `.prop=${value}` SSR
-  hydration.
+- **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
 
 ---
@@ -736,6 +731,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
@@ -997,7 +1003,8 @@ component, applies its attributes, runs `willUpdate` and controllers'
 `firstUpdated`, `updated`, or any other browser-only lifecycle hook.
 Whatever state should appear on first paint MUST be set in the
 constructor (after `super()`), derived in `willUpdate`, or derivable
-from `static properties` + attributes on the rendered tag. Reading
+from the factory-declared reactive props + attributes on the rendered
+tag. Reading
 `this.getAttribute` / `hasAttribute` in `render()` works server-side (a
 server attribute shim backs the attribute methods), but a `Task`'s
 fetch still runs only on the client.