@webjsdev/cli 0.10.20 → 0.10.21

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) {

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.21",
   "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)
 

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)
 

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,7 +107,7 @@ 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`).
 - 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.
@@ -109,5 +115,5 @@ each change must include.
 - 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.
+- 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
@@ -597,12 +598,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 +631,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 +662,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 +718,12 @@ 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`) |
 | 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
@@ -1218,7 +1223,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
 
@@ -635,10 +643,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 +669,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
@@ -680,15 +680,8 @@ value/binding diagnostics, hover); in VS Code / Cursor / Windsurf the
   - `my-widget .body`, `my-widget .title` (descendant selector)
 - 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.
+- 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
 
 ---
@@ -997,7 +990,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.