@webjsdev/cli 0.10.71 → 0.10.72

package/lib/create.js

@@ -585,13 +585,9 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // layout already writes asset(), so a fresh app is green on day one.
       // Two checks are fatal with no entry here at all, NODE_VERSION and
       // TSCONFIG_ERASABLE, because either would 500 the app at runtime;
-      // DARK_THEME_UNREACHABLE is at error too: AGENTS.md mandates light-dark()
-      // tokens, the generated layout writes them, and a layout that drops them
-      // leaves the stylesheet's .dark block dead and the OS setting ignored
-      // (#1628); elsewhere it is a design convention and stays a warning.
-      // Everything else keeps its default warn. Add a code with "off" to
+      // everything else keeps its default warn. Add a code with "off" to
       // silence it, or "error" to make it fatal too.
-      doctor: { gate: { UNMARKED_ASSET_LINKS: 'error', DARK_THEME_UNREACHABLE: 'error' } },
+      doctor: { gate: { UNMARKED_ASSET_LINKS: 'error' } },
       // The dependency audit's allowlist (#1492), the ONE place an accepted
       // advisory is listed, each with the reason it is safe. `webjs audit`
       // (the CI step below) fails on every other advisory at `level` or above,

package/lib/doctor/codes.js

@@ -51,7 +51,6 @@ export const DOCTOR_CODES = {
   'Asset urls (unmarked stylesheet links)': 'UNMARKED_ASSET_LINKS',
   'workspace-overrides': 'WORKSPACE_OVERRIDES',
   'app-icon': 'APP_ICON',
-  'dark-theme': 'DARK_THEME_UNREACHABLE',
 };
 
 /**

package/lib/doctor/runner.js

@@ -13,7 +13,6 @@ import { checkUnmarkedAssetLinks } from './probes/unmarked-asset-links.js';
 import { checkFrameworkResolves, checkFrameworkLinks } from './probes/framework-resolves.js';
 import { checkWorkspaceOverrides } from './probes/workspace-overrides.js';
 import { checkAppIcon } from './probes/app-icon.js';
-import { checkDarkTheme } from './probes/dark-theme.js';
 
 /**
  * @typedef {import('./codes.js').DoctorResult} DoctorResult
@@ -69,7 +68,6 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkUnmarkedAssetLinks(appDir),
     Promise.resolve(checkWorkspaceOverrides(appDir)),
     Promise.resolve(checkAppIcon(appDir)),
-    checkDarkTheme(appDir),
   ]);
   // Attach the stable machine code to every result (#975). Centralized here so
   // each check function stays free of the code-contract concern.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.71",
+  "version": "0.10.72",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjsdev/mcp": "^0.1.15",
+    "@webjsdev/mcp": "^0.1.16",
     "@webjsdev/server": "^0.8.89",
     "@webjsdev/ui": "^0.3.15"
   },

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

@@ -8,12 +8,30 @@ Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
 
 ## Grow the app in place (non-negotiable)
 
-Study the shipped showcase (a full-stack app's UI gallery under
-`app/features/` and `app/examples/todo`, the api template's
-`app/api/features/`), run `npm run gallery:clear`, then grow the app in place
-under `app/`, `components/`, and `modules/<feature>/`. `AGENTS.md` carries the
-build order, the data rule (the wired-up Drizzle database, never JSON files),
-and the browser check for a UI app.
+- **Study the shipped examples, then clear them and build.** The scaffold is a
+  starting point with a browsable showcase to learn the real idioms from, plus a
+  database wired up. A full-stack app ships a UI feature gallery (`app/features/`,
+  `app/examples/todo`); the api template ships a backend-features showcase
+  (`app/api/features/`), with logic in `modules/`. Building a real app: study the
+  parts that match your task (the skill teaches the same and SURVIVES the clear),
+  run `npm run gallery:clear` to shed the showcase (it keeps the agent skill and
+  the database wiring, and resets to a clean base), then regenerate the database
+  and grow the app in place under `app/`, `components/`, and `modules/<feature>/`.
+  `AGENTS.md` carries the full template-specific build playbook and the order to
+  follow.
+- **Use the wired-up database (Drizzle), never JSON files.** For any data the app
+  stores, define a Drizzle table in `db/schema.server.ts`, then
+  `npm run db:generate` and `npm run db:migrate`. Never use a JSON file, a
+  module-scope array or Map, or localStorage as a database.
+- **`app/` is routing-only.** Only routing files live in `app/` (page, layout,
+  route, middleware, metadata routes). Browser-safe helpers go in `lib/utils/`,
+  feature logic in `modules/`, server-only code behind `.server.ts`.
+- **For a UI app, render and LOOK before calling it done.** Define design tokens
+  in `app/layout.ts` with a palette that fits the app
+  (`.agents/skills/webjs/references/styling.md` is the guide), then open every
+  route you changed in a real browser and play through its states.
+  `npm run check` and `npm run typecheck` pass even when a layout collapses, so
+  the browser is the real check.
 
 ## Before starting ANY work
 

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

@@ -104,12 +104,12 @@ Common bundles:
 1. **Classify the change.** Route contract, data model, server mutation, auth, or only UI?
 2. **Start from the server.** Add the page/route and its server action or query before wiring interactive UI. A page render or a `<form>` POST should already return correct HTML before any component hydrates.
 3. **Put code in the narrowest owner.** Route-local first (`modules/<feature>/`), promote to `lib/` or `components/` only when reuse is real.
-4. **Keep server-only code behind `.server.ts`** (Core WebJs Rules 1 and 2).
+4. **Keep server-only code behind `.server.ts`.** The DB driver, secrets, and `node:*` never belong in a page, layout, or component.
 5. **Add interactivity per behaviour.** Reach for a component (and a signal or `@event`) only where the UI is genuinely interactive. A display-only component is elided from the browser. Then wrap the interactive part and STOP: the static markup around it stays in the page, where it costs nothing.
 6. **Validate input at the boundary.** Declare `export const validate` on an action; the RPC and `route()` boundaries run it.
 7. **Default mutations to optimistic UI** where the client can predict the result (`optimistic()` from `@webjsdev/core`).
-8. **Type every boundary from its source, never `unknown` or `any`.** The row type comes from the schema (`typeof todos.$inferSelect`), the action's input from a named `interface` and its result from `ActionResult<T>`, the routing files from `PageProps` / `LayoutProps` / `RouteHandlerContext`. `unknown` belongs on a payload nothing has vouched for yet that the next line narrows, and on a parameter of your own helper that forwards into an `html` template hole. Everywhere else, including a layout's `children`, it is a missing type. Carry a row type into a shipping component with `import type` (erased before the browser sees it). Nothing enforces this (both spellings are valid TypeScript, so `webjs check` and `tsc` pass either way), which is why it is written down. See `references/typescript.md`.
-9. **Test the narrowest meaningful layer**, and look at any UI change in a real browser (see Testing Defaults).
+8. **Type every boundary from its source, never `unknown` or `any`.** The row type comes from the schema (`typeof todos.$inferSelect`), the action's input from a named `interface` and its result from `ActionResult<T>`, the routing files from `PageProps` / `LayoutProps` / `RouteHandlerContext`. `unknown` belongs on a payload nothing has vouched for yet that the next line narrows, and on a parameter of your own helper that forwards into an `html` template hole. Everywhere else, including a layout's `children`, it is a missing type. See `references/typescript.md`.
+9. **Test the narrowest meaningful layer**, and render the app in a real browser for any UI change (static checks do not catch a collapsed layout).
 
 ## Project Layout
 
@@ -137,7 +137,7 @@ App-internal imports use the `#` root alias (`import { db } from '#db/connection
 ## Core WebJs Rules (invariants)
 
 1. Server-only code lives in `.server.ts`, `route.ts`, or `middleware.ts`. Never in a page, layout, or component (it crashes the browser at module load).
-2. `'use server'` exports are `async` functions returning serializer-safe values, callable from browser code as RPC. Files without `'use server'` are server-only utilities: reach them only from `'use server'` actions, `route.ts`, or middleware. Never add `'use server'` to a file only other server code imports (the DB connection, the schema).
+2. `'use server'` exports are `async` functions returning serializer-safe values. Files without `'use server'` are server-only utilities.
 3. Custom element tag names contain a hyphen. Pass the tag to `Class.register('tag-name')`.
 4. Event (`@`), property (`.`), and boolean (`?`) holes in `html` are UNQUOTED: `@click=${fn}`, never `@click="${fn}"`.
 5. Signals are the default state primitive. Import `signal` / `computed` from `@webjsdev/core`, read via `signal.get()` inside `render()`. The base-class factory `WebComponent({ ... })` is only for values riding an HTML attribute or arriving via SSR hydration.
@@ -147,7 +147,7 @@ App-internal imports use the `#` root alias (`import { db } from '#db/connection
 9. No backtick characters inside an `html\`...\`` body, even in comments (it closes the literal and 500s).
 10. TypeScript must be erasable (`erasableSyntaxOnly: true`): no `enum`, no value `namespace`, no constructor parameter properties, no legacy decorators.
 11. Reactive properties are declared ONLY through the base-class factory `extends WebComponent({ count: Number })`. Never a `static properties` block, never a class-field initializer (it clobbers the reactive accessor).
-12. A form that writes binds its action: `<form action=${importedAction}>`, or a per-button `<button formaction=${importedAction}>`. A bound submitter is SELF-SUFFICIENT (#1307): the renderer puts `formmethod="post"` and `formenctype` on the button itself, so it needs no bound form around it and works inside any form or none. Quoted bindings, non-submit controls, `<input type="submit">` (the identity needs its `value`, which is also its label, so use a `<button>`), submitter `name` / `value` / `form` / static `formaction` attributes (the identity IS the button's name/value pair, so both halves are spoken for), a `.prop` spelling of any of those, `action=${fn}` off a `<form>`, a bound form with `method="get"` (a GET sends no body for the action to read), a BOUND submitter's own non-post `formmethod` or unparseable `formenctype`, and a non-action function all throw. A PLAIN button's own `formmethod` / `formenctype` is a legal native override and is left alone. A page has no `action` export, so a bare `<form method="post">` is a 405.
+12. A form that writes binds its action: `<form action=${importedAction}>`, or a per-button `<button formaction=${importedAction}>`. A bound submitter is SELF-SUFFICIENT (#1307): the renderer puts `formmethod="post"` and `formenctype` on the button itself, so it needs no bound form around it and works inside any form or none. Quoted bindings, non-submit controls, `<input type="submit">` (the identity needs its `value`, which is also its label, so use a `<button>`), submitter `name` / `value` / `form` / static `formaction` attributes, a `.prop` spelling of any of those, `action=${fn}` off a `<form>`, a bound form with `method="get"`, a BOUND submitter's own non-post `formmethod` or unparseable `formenctype`, and a non-action function all throw. A PLAIN button's own `formmethod` / `formenctype` is a legal native override and is left alone. A page has no `action` export, so a bare `<form method="post">` is a 405.
 
 ## Export Map
 
@@ -272,12 +272,18 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 
 ## Common Mistakes To Avoid
 
-The invariants above are not repeated here; this list is the mistakes they do not already name.
-
+- Treating a page or layout like a React component and expecting its markup to hydrate. It runs server-only; put interactivity in a component.
 - Promoting a whole page section to a component so that one control inside it can be interactive. The island should wrap the control and the state it reads. An oversized island ships its own JS AND un-elides every display-only component inside it, so the cost is not linear in what you moved.
+- Importing a `.server.ts` utility (no `'use server'`) directly into a shipping component. Its browser stub throws at load; reach it through a `'use server'` action.
+- Using a `static properties` block or a class-field initializer for reactive props instead of the `WebComponent({ ... })` factory.
+- Quoting an event / property / boolean hole (`@click="${fn}"`).
 - Writing `fetch()` to call your own server instead of importing the action.
+- Writing a bare `<form method="post">` and expecting a page `action` export to catch it. There is no such export; bind the action with `action=${fn}` or the submission is a 405.
+- Putting a submitter's `formaction=${fn}` on anything that is not a submit control, or on a button carrying its own `name` / `value`. The identity IS the button's name/value pair, so both halves are spoken for.
+- Writing `formmethod="get"` or `formenctype="text/plain"` on a button that BINDS an action. Neither can carry that action's body, so the pair contradicts itself and throws. On a button that binds nothing it is a legal native override and is honoured.
 - Binding an action whose file declares `export const method = 'GET'`. Form-bound actions strictly require POST (default). Binding a GET action to a form is a 405 at runtime and a `webjs check` error (`form-action-not-a-get-action`).
 - Leaving read-only RPC server query actions as default `POST`. Always export `export const method = 'GET'` for RPC data queries so arguments ride URL params, ETags/304 caching work, and CSRF is safely bypassed.
+- Writing `method="get"` on a bound `<form action=${fn}>`. WebJs supplies `method="post"` and `formenctype` automatically, and a bound form declaring `method="get"` is REFUSED at render (a thrown error, not a warning), because a GET sends no body for the action to read.
 - Throwing `redirect()` / `notFound()` inside a `route.ts` handler (uncaught 500). Return a `Response` there.
 - A placeholder first paint that fetches in `connectedCallback`. SSR does not call `connectedCallback`; put first-paint data in the constructor (server-known inputs) or use `async render()`.
 - A browser global (`window`, `document`, `localStorage`) in the constructor or `render()`. It throws at SSR; do browser-only work in `connectedCallback`.

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -298,8 +298,6 @@ Two guarantees worth knowing. A result that could not check (a network or toolch
 
 `APP_ICON` warns while the favicon is still the scaffold's placeholder `app/icon.svg` (marked `data-webjs-placeholder`). Replace it with the app's own icon (`references/routing-and-pages.md`, "App icon and manifest").
 
-`DARK_THEME_UNREACHABLE` warns when the app defines colour tokens with a light value only and nothing applies a dark half: no `light-dark()`, no `@media (prefers-color-scheme: dark)` rule, no theme script in the root layout. The scaffold gates it `error` in its `package.json` because its AGENTS.md mandates `light-dark()` tokens; the fix is the token block in `references/styling.md`.
-
 ### Dependency audit allowlist
 
 `webjs audit` runs `npm audit` or `bun audit` (by the nearest lockfile, so a workspace member uses the root's) and fails on any advisory at or above `webjs.audit.level` (default `high`) that `webjs.audit.ignore` does not list. The scaffold's `Security: dependency audit` CI step runs it.

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

@@ -193,7 +193,7 @@ Whichever form you use, a token nothing references is dropped in both, so an unu
 </style>
 ```
 
-`light-dark()` is a native CSS function (CSS Color 5, Baseline 2024), not a library, so nothing to import. A single-theme app drops the `[data-theme]` rules and gives each token one colour. `webjs doctor` reports the floor as `DARK_THEME_UNREACHABLE` (the scaffold gates it `error`): an app whose tokens have a light value only, with no `light-dark()`, no `prefers-color-scheme` rule and no theme script in the root layout, because the scaffold stylesheet's `.dark` block would then be dead CSS and the OS dark setting ignored.
+`light-dark()` is a native CSS function (CSS Color 5, Baseline 2024), not a library, so nothing to import. A single-theme app drops the `[data-theme]` rules and gives each token one colour.
 
 **A manual theme toggle** writes `data-theme` on `<html>` (`light` / `dark`, or removes it for "follow the OS"). If you use `@webjsdev/ui` components, ALSO keep the `.dark` class in sync (the ui kit keys its own tokens off `.dark`), and apply the saved choice in a tiny inline `<script>` in the layout head so there is no first-paint flash. Verify dark mode in a real browser. Light mode passing proves nothing about dark.
 

package/templates/AGENTS.md

@@ -34,14 +34,49 @@ This is what separates a working app from a broken one.
 
 ## Type everything (all templates)
 
-Derive the type at every boundary from its source. Never reach for `any`, and
-never `unknown` where a real type exists. The rule is step 8 of the skill's "Default
-Workflow"; the full ladder, with an end-to-end example, is
+Full-stack type safety is what the `.server.ts` boundary buys you: a client
+component importing a server action resolves to that action's real signature at
+type-check time, with no build step and no code generation in between. So
+DERIVE the type at every boundary instead of widening it:
+
+- A database row: `export type Todo = typeof todos.$inferSelect` in
+  `db/schema.server.ts` (`$inferInsert` for a write), carried into a
+  browser-shipped component with `import type` (erased before it reaches the
+  browser, so it does not trip the server-import boundary).
+- An action's input: a named `interface`. Its result: `ActionResult<T>`.
+  Narrow with `if (result.success && result.data)`.
+- Routing files: `PageProps<'/blog/[slug]'>`, `LayoutProps`,
+  `RouteHandlerContext`, all from `@webjsdev/core`. Run `npx webjsdev types`
+  for the typed `Route` union and per-route `params`.
+- A reactive property: `prop<Student>(Object)`, `prop<Tag[]>(Array)`.
+
+Never reach for `any` or a loose `as any` cast, and do not reach for `unknown`
+either just because it looks safer. `unknown` is right for a payload nothing
+has vouched for yet, narrowed on the very next line (a `route.ts` `await
+req.json()`, an action's `export const validate` or a validator it delegates
+to, a `catch` binding), and for a parameter of YOUR OWN helper that forwards
+into an `html` template hole (a hole renders a string, a number, a
+`TemplateResult`, or an array of those, so `TemplateResult` alone is too
+narrow). That second case is about a value you accept, never one the framework
+already types. Everywhere else it is a missing type, not a safe one: `unknown`
+that survives into a return type, a component prop, a layout's `children`, or
+an action signature is the shape to fix.
+Nothing enforces this (both are valid TypeScript, so `webjs check` and `tsc`
+pass either way), which is exactly why it is written down. The full ladder,
+with an end-to-end example, is in
 `.agents/skills/webjs/references/typescript.md`.
 
 Keep server-only code (database drivers, secrets, `node:*` builtins) in
-`.server.ts` modules. The two kinds (with and without `'use server'`) are the
-skill's "Core WebJs Rules" 1 and 2.
+`.server.ts` modules. There are exactly two kinds:
+
+- A `.server.ts` file WITH `'use server';` as its first line is a server
+  action: WebJs exposes its exported async functions to browser code as RPC
+  calls, so browser modules may import it directly.
+- A `.server.ts` file WITHOUT `'use server'` is a server-only utility:
+  importing it from a page, layout, or component CRASHES in the browser at
+  module load. Reach it only from `'use server'` actions, `route.ts` handlers,
+  or middleware. Never add `'use server'` to a file only other server code
+  imports (the DB connection, the schema).
 
 ## Data (all templates)
 

package/templates/CLAUDE.md

@@ -9,9 +9,14 @@ is complete, WITHOUT being asked. Do not save all the work for one commit at the
 end. A finished implementation with zero commits is a mistake here, because git
 history is the user's revert and cherry-pick safety net.
 
-The full git contract (branches, commit messages, attribution) is
-`.agents/rules/workflow.md` "Git rules"; the
-`.claude/hooks/guard-branch-context.sh` hook refuses a commit on `main`. Two hooks back this up: the
+- After each completed unit whose tests pass, `git add` the related files and
+  `git commit` with an imperative subject under 72 chars, then push. If 5+ files
+  span more than one concern, you already waited too long.
+- Never commit to `main`. Work on a feature branch (the
+  `.claude/hooks/guard-branch-context.sh` hook enforces this).
+- No AI-attribution trailers (`Co-Authored-By`, `Generated by`).
+
+See AGENTS.md "Git workflow" for the full contract. Two hooks back this up: the
 `.claude/hooks/nudge-uncommitted.sh` PostToolUse hook reminds you while
 uncommitted changes pile up during work, and the
 `.claude/hooks/commit-before-stop.sh` Stop hook stops you from ending a turn

package/templates/CONVENTIONS.md

@@ -3,16 +3,34 @@
 The conventions for building a WebJs app live in the agent skill. **Read
 `AGENTS.md` first, then `.agents/skills/webjs/SKILL.md`** (it routes to focused
 references under `.agents/skills/webjs/references/`, loaded on demand). This file
-only says where each rule lives, so no rule is stated twice.
+is the short version.
 
-- **Build order** (study the showcase: a full-stack app's gallery under
-  `app/features/` and `app/examples/todo`, the api template's
-  `app/api/features/`; then `npm run gallery:clear`, data, UI, verify):
-  the playbook in `AGENTS.md`.
-- **Data** (the wired-up Drizzle database, never a JSON file, an in-memory
-  array or Map, or localStorage): `AGENTS.md`, "Data".
-- **Layout** (`app/` is routing only, logic in `modules/<feature>/`): the
-  skill's "Project Layout".
-- **Server boundary, progressive enhancement, typing**: the skill's "What WebJs
-  Is", "Core WebJs Rules", and "Default Workflow".
-- **Git, tests, and `npm run ci`**: `.agents/rules/workflow.md`.
+## The essentials
+
+- **`app/` is routing only.** Only routing files live there (page, layout, route,
+  middleware, metadata routes). Feature logic goes in `modules/<feature>/`
+  (`actions/`, `queries/`, `components/`, `utils/`); shared UI primitives go in
+  top-level `components/`; browser-safe helpers in `lib/utils/`.
+- **Server-only code goes behind `.server.ts`.** Reach it from a page or component
+  through a `'use server'` action, never by importing a server-only utility
+  directly into browser-bound code.
+- **Use the wired-up database (Drizzle).** Define real models in
+  `db/schema.server.ts`, then `npm run db:generate` and `npm run db:migrate`.
+  Never persist to a JSON file, an in-memory array or Map, or localStorage.
+- **The scaffold ships a showcase to learn from.** A full-stack app ships a UI
+  feature gallery (`app/features/`, `app/examples/todo`); the api template ships
+  a backend-features showcase (`app/api/features/`), with logic in `modules/`.
+  When you build a real app, study the parts that match your task (the skill
+  teaches the same and survives the clear), run `npm run gallery:clear` to shed
+  the showcase, then grow the app in place. `AGENTS.md` has the full
+  template-specific playbook.
+- **Derive types at every boundary.** Rows from `$inferSelect`, action inputs
+  from an `interface`, routing files from `PageProps` / `LayoutProps`. Never
+  `any`, and never `unknown` where a real type exists.
+- **Progressive enhancement is the default.** Pages render as HTML, `<a>`
+  navigates, a `<form action=${importedAction}>` submits, all with JavaScript off; opt into
+  interactivity per behaviour inside a component.
+- **Commit per logical unit** as soon as it is complete, and never push to `main`.
+
+Everything else (the module architecture, the `ActionResult` envelope, styling,
+testing, the client router, optimistic UI) is in the skill's references.

package/templates/partials/agents-playbook-api.md

@@ -44,12 +44,20 @@ cross-origin access use the `cors()` middleware from `@webjsdev/server`; with
 
 ### 5. Verify before you call it done
 
-Run `npm run ci` and fix what it reports. It runs every gate declared under
-`webjs.ci` in `package.json` (`webjs check`, `webjs doctor`, `webjs typecheck`,
-a dependency audit, then the test layers for the endpoints and modules you
-built), and the GitHub workflow runs the
-same list; `.agents/rules/workflow.md` has what each gate checks. While
-iterating, `npm run ci -- --only Tests` runs one layer.
+Run `npm run ci` and fix what it reports. It is one command for every gate,
+the step list declared in `package.json` under `webjs.ci`, with a result line
+per step:
+
+- `webjs check` (correctness: no browser-import or boundary violation).
+- `webjs doctor` (project health). It fails on whatever `package.json`
+  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
+  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
+- `webjs typecheck` (zero type errors).
+- A dependency audit.
+- The test layers for the endpoints and modules you built.
+
+The GitHub workflow runs the same list, so a green local run predicts CI.
+While iterating, `npm run ci -- --only Tests` runs one layer.
 
 Then boot `npm run dev` and probe each endpoint for the expected status and JSON
 shape.

package/templates/partials/agents-playbook-fullstack.md

@@ -84,21 +84,31 @@ action without also triggering the row navigation.
 
 ### 6. Build components for interactivity
 
-Pages and layouts never hydrate, so put every interactive behavior inside a
-`WebComponent` custom element, and declare its reactive properties only in the
-base-class factory (the skill's "Core WebJs Rules" 11). Use the shorthand for primitives
+Pages and layouts (`app/**/page.ts`, `app/**/layout.ts`) are server-only HTML
+generators, so put every interactive behavior inside a `WebComponent` custom
+element. Declare a component's reactive properties in the base-class factory,
+never as a class-field initializer (`items = []` clobbers the reactive
+accessor). Use the shorthand for primitives
 (`extends WebComponent({ name: String, count: Number, open: Boolean })`) and the
 `prop<T>()` helper for typed objects and arrays
 (`extends WebComponent({ items: prop<Item[]>(Array), user: prop<User>(Object) })`).
 
 ### 7. Verify before you call it done
 
-Run `npm run ci` and fix what it reports. It runs every gate declared under
-`webjs.ci` in `package.json` (`webjs check`, `webjs doctor`, `webjs typecheck`,
-a dependency audit, then the server, browser, and e2e test layers for the
-features you built), and the GitHub workflow runs the
-same list; `.agents/rules/workflow.md` has what each gate checks. While
-iterating, `npm run ci -- --only Tests` runs one layer. Then
+Run `npm run ci` and fix what it reports. It is one command for every gate,
+the step list declared in `package.json` under `webjs.ci`, with a result line
+per step:
+
+- `webjs check` (correctness: no browser-import or boundary violation).
+- `webjs doctor` (project health). It fails on whatever `package.json`
+  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
+  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
+- `webjs typecheck` (zero type errors).
+- A dependency audit.
+- The server, browser, and e2e test layers for the features you built.
+
+The GitHub workflow runs the same list, so a green local run predicts CI.
+While iterating, `npm run ci -- --only Tests` runs one layer. Then
 `npm run css:build` (compile Tailwind).
 
 Then boot `npm run dev`, confirm every page route returns HTTP 200, and open

package/lib/doctor/probes/dark-theme.js

@@ -1,91 +0,0 @@
-import { existsSync, readdirSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-
-/**
- * @typedef {import('../codes.js').DoctorResult} DoctorResult
- */
-
-const ROOT_LAYOUT = /^app\/layout\.(?:js|mjs|ts|mts)$/;
-/** Stylesheet sources: the Tailwind input and any hand-written sheet; never the compiled output. */
-const STYLE_SOURCE = /^(?:public|styles)\/(?:.+\/)?[^/]+\.css$/;
-const COMPILED_OR_VENDORED = /(?:^|\/)(?:tailwind\.css|node_modules\/|\.webjs\/|dist\/)/;
-/** A colour token definition: the two every palette starts from. */
-const TOKEN_DEF = /--(?:background|foreground)\s*:/;
-/** Any of these makes the dark half reachable. */
-const DUAL_TOKENS = /light-dark\s*\(/;
-const SCHEME_QUERY = /prefers-color-scheme/;
-/** A head script that applies a saved or detected theme. */
-const THEME_SCRIPT = /<script\b[^>]*>[\s\S]*?(?:prefers-color-scheme|localStorage|data-theme|classList\.(?:add|toggle)\(\s*['"`]dark['"`]|dataset\.theme)[\s\S]*?<\/script>/;
-
-/** CSS and JS block comments and line comments, so a commented-out token or hint does not count. */
-function stripComments(text) {
-  return text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
-}
-
-/**
- * The app's colour-token sources: the root layout (where the generated app
- * writes its palette) and the stylesheet sources under `public/` and `styles/`.
- * @param {string} appDir
- * @returns {Promise<Array<{ rel: string, content: string }>>}
- */
-async function tokenSources(appDir) {
-  /** @type {Array<{ rel: string, content: string }>} */
-  const out = [];
-  const read = async (rel) => {
-    try { out.push({ rel, content: await readFile(join(appDir, rel), 'utf8') }); } catch { /* unreadable: not a source */ }
-  };
-  for (const ext of ['ts', 'js', 'mts', 'mjs']) {
-    const rel = `app/layout.${ext}`;
-    if (existsSync(join(appDir, rel))) { await read(rel); break; }
-  }
-  for (const dir of ['public', 'styles']) {
-    const abs = join(appDir, dir);
-    if (!existsSync(abs)) continue;
-    for (const e of readdirSync(abs, { recursive: true, withFileTypes: true })) {
-      if (!e.isFile() || !e.name.endsWith('.css')) continue;
-      const rel = relative(appDir, join(e.parentPath || abs, e.name)).split('\\').join('/');
-      if (STYLE_SOURCE.test(rel) && !COMPILED_OR_VENDORED.test(rel)) await read(rel);
-    }
-  }
-  return out;
-}
-
-/**
- * `DARK_THEME_UNREACHABLE` (#1628): the app defines colour tokens but nothing
- * applies a dark half. The scaffold's stylesheet keeps the ui kit's `.dark`
- * token block, and `AGENTS.md` asks for `light-dark()` tokens under
- * `color-scheme: light dark`; a layout that uses neither, has no
- * `prefers-color-scheme` rule and runs no theme script ships dead CSS and
- * ignores the OS setting, which no light-mode screenshot reveals. A design
- * convention rather than a runtime break, so it lives in doctor (WARN by
- * default) and the scaffold gates it `error` because its AGENTS.md mandates
- * the tokens. Silent when the app defines no colour tokens at all.
- * @param {string} appDir
- * @returns {Promise<DoctorResult>}
- */
-export async function checkDarkTheme(appDir) {
-  const name = 'dark-theme';
-  if (!existsSync(join(appDir, 'app'))) {
-    return { name, status: 'pass', message: 'no app/ directory to analyse' };
-  }
-  const sources = await tokenSources(appDir);
-  const defining = sources.filter((s) => TOKEN_DEF.test(stripComments(s.content)));
-  if (!defining.length) {
-    return { name, status: 'pass', message: 'no colour tokens defined (nothing to reach)' };
-  }
-  const all = sources.map((s) => stripComments(s.content)).join('\n');
-  const layout = sources.find((s) => ROOT_LAYOUT.test(s.rel));
-  if (DUAL_TOKENS.test(all) || SCHEME_QUERY.test(all) || (layout && THEME_SCRIPT.test(layout.content))) {
-    return { name, status: 'pass', message: 'the dark half of the colour tokens is reachable' };
-  }
-  const where = defining.map((s) => s.rel).join(' and ');
-  return {
-    name,
-    status: 'warn',
-    message:
-      `colour tokens are defined in ${where} with a light value only: nothing applies a dark half (no light-dark(), no prefers-color-scheme rule, no theme script in the root layout), so the OS dark setting is ignored and any .dark block is dead CSS`,
-    fix:
-      'Write each colour token ONCE as light-dark(LIGHT, DARK) under `color-scheme: light dark` in the root layout (the block in .agents/skills/webjs/references/styling.md), or give the tokens an `@media (prefers-color-scheme: dark)` half, or add a head <script> that applies the saved theme (data-theme / the .dark class). Then check the app in a real browser with the OS in dark mode.',
-  };
-}