@webjsdev/cli 0.10.40 → 0.10.41

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

@@ -0,0 +1,123 @@
+# Styling
+
+## What This Covers
+
+- Tailwind-first: the strong default for pages AND light-DOM components, and the Lit reflex it counters
+- The light-DOM tag-prefix invariant when raw CSS is unavoidable
+- Extracting a repeated Tailwind bundle into a `lib/utils/ui.ts` `html` fragment (not `@apply`)
+- Design tokens: `:root` / `@theme` in the root layout
+- Light-DOM host `display: block` behaviour (and shadow hosts via `:host`)
+- When to use `static styles` (shadow DOM)
+- `position: fixed`, not `sticky`, for a pinned header (the iOS WebKit flicker)
+- Even-grid / no-reflow layout tips
+
+Read this when a task touches a class list, a `<style>`, a design token, a pinned header, or a grid/board/card layout. Sibling ref: `components.md` (light vs shadow DOM, `static styles`, host behaviour in depth).
+
+## Tailwind-first is the strong default
+
+Use Tailwind utilities for pages AND light-DOM components (the default DOM mode). Layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, and interaction states (hover/focus/active/disabled, dark mode) are all utility-expressible. Light DOM does not scope styles, so a utility class on a light-DOM element resolves against the global stylesheet exactly as it does on a page. That is why utilities are the right tool there, not an exception.
+
+### The Lit muscle-memory trap
+
+In Lit a component owns a shadow root and scopes its CSS with `static styles = css\`\``, so the reflex is to author scoped CSS or an inline `<style>` with semantic class names (`.hero`, `.card`, `.btn`) per component. In WebJs the default is light DOM, which does NOT scope. A `css` block does nothing without `static shadow = true` (the framework warns at runtime), and an inline `<style>` with bare semantic class names leaks those names into the global namespace. Reach for Tailwind utilities instead. When the same bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment (below), NOT a CSS class.
+
+### The custom-CSS allowlist
+
+Reserve raw CSS for what utilities genuinely cannot express. This is the exhaustive list, anything outside it should be a utility or a `lib/utils/ui.ts` helper:
+
+- design-token `:root` + `@theme` definitions (palette, fonts, fluid type scale, motion durations, declared once in the root layout),
+- `@property` animated custom properties paired with `@keyframes`,
+- `::-webkit-scrollbar` and `scrollbar-color` (no utility surface),
+- `prefers-reduced-motion` blocks,
+- complex `color-mix()` or gradient effects a utility cannot spell.
+
+When custom CSS IS unavoidable inside a light-DOM component, the tag-prefix invariant holds (every class selector is prefixed with the component tag). Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`\``, the right home for scoped CSS. The Tailwind-first steer is about the LIGHT-DOM default, not shadow DOM.
+
+## DRY via a JS helper, not `@apply`
+
+When the same Tailwind bundle repeats across 2+ places, extract it into a helper in `lib/utils/ui.ts` that returns an `html` fragment (SSR-time, no client runtime, output identical to inline classes):
+
+```ts
+import { html } from '@webjsdev/core';
+
+/** `● label` kicker: small caps, accent colour, above headings. */
+export function rubric(label: string, mb: 'sm' | 'md' = 'md') {
+  const mbCls = mb === 'sm' ? 'mb-3' : 'mb-4';
+  return html`
+    <span class="block font-mono text-[11px] leading-none font-semibold tracking-[0.2em] uppercase text-primary ${mbCls}">● ${label}</span>
+  `;
+}
+```
+
+```ts
+// app/blog/[slug]/page.ts
+import { rubric } from '#lib/utils/ui.ts';
+
+export default function Post({ params }) {
+  return html`${rubric('post')}<h1 class="font-serif ...">${title}</h1>`;
+}
+```
+
+| Repeats | Action |
+|---|---|
+| Once | Inline the classes. |
+| 2 to 3 times, identical | Extract to `lib/utils/ui.ts`. |
+| Varies by 1 to 2 props | Extract with a small parameter (`mb: 'sm' \| 'md'`). |
+| Radically different per call site | Keep inline, do not force-fit. |
+
+Avoid `@apply`: it hides which utilities a class uses and creates a second source of truth. A JS helper keeps the bundle visible at the definition site, composes with conditional classes and active states, and runs at SSR time.
+
+## Design tokens
+
+The default stack is a static compiled Tailwind stylesheet (`css:build` compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off) plus `@theme` design tokens (palette, fonts, fluid type, motion durations) declared once in the root layout. Consume them as utility classes (`text-foreground`, `bg-card`, `font-serif`, `duration-fast`). If you wire your own theme switch, drive BOTH signals on `<html>` (the `data-theme` attribute for the app palette blocks AND the `.dark` class for the `@webjsdev/ui` kit), or half the UI renders stale tokens. Verify dark mode in a real browser, light mode passing proves nothing about dark.
+
+## Light-DOM host display, and shadow hosts
+
+A custom element is `display: inline` in plain CSS, which collapses a component used as a block container to its content size. WebJs marks every LIGHT-DOM host `data-wj-host` and defaults it to `display: block` via one head rule in a low-priority cascade layer (`@layer webjs-host { :where([data-wj-host]) { display: block } }`), so a container component does not collapse. The layer keeps it overridable: any author style INCLUDING a Tailwind utility (`class="flex"`, `grid`, `hidden`) wins over it, and `[hidden]` still hides the host so `?hidden=${cond}` works. Opt into an inline light component with a tag-prefixed rule (`my-badge { display: inline }`).
+
+Shadow-DOM hosts are NOT marked (a document rule would override the shadow tree's own `:host`), so a shadow component sets its host display the idiomatic way in `static styles`:
+
+```ts
+static styles = css`:host { display: block }`;   // a shadow host with no :host display stays inline
+```
+
+**Size the HOST, not just an inner wrapper.** The host custom element is the box the parent lays out. A host that is a flex/grid item in a centering parent (`flex justify-center`, `grid place-items-center`) is sized to its content unless it carries width itself. Put the sizing classes on the host (`w-full max-w-[400px]`), not only on an inner `<div>`. Symptom: a board or card renders tiny even though its inner grid says `w-full max-w-[400px]`. Fix: move the sizing onto the host.
+
+## Even grids, no reflow
+
+The reflow bug (a cell grows when it gets content while the others shrink) comes from `auto`-sized grid rows. Size the tracks explicitly so every cell is an equal fraction regardless of content:
+
+```html
+<!-- a 3x3 board whose cells stay equal and square as it fills -->
+<div class="grid gap-2 aspect-square [grid-template-columns:repeat(3,1fr)] [grid-template-rows:repeat(3,1fr)]">
+  ${cells.map((c) => html`
+    <button class="grid place-items-center min-h-0 overflow-hidden text-[clamp(1rem,8cqi,3rem)]">${c}</button>
+  `)}
+</div>
+```
+
+- `aspect-ratio` (e.g. `aspect-square`) on the CONTAINER plus `repeat(N,1fr)` columns AND rows keeps every cell an equal square that does not resize as marks are placed. Putting `aspect-square` on the CELLS is the common mistake that produces uneven rows.
+- `min-h-0` + `overflow-hidden` on a cell stops its content forcing the track taller (a grid/flex child has an implicit `min-height: auto`).
+- Size text relative to the cell (`clamp()`, container-query units `cqi`) so the glyph scales with the board rather than dictating the cell size.
+
+Verify a layout by USING it, not by glancing at the first paint. A layout bug only shows mid-interaction: play through every state (fill the board, win, reload) and confirm nothing resizes.
+
+## Pin a header with `position: fixed`, never `sticky`
+
+A `position: sticky` header (the common `sticky top-0` pattern) flickers its background for one frame on iOS WebKit (every iOS browser uses WebKit) during a client-router forward navigation. The router's scroll-to-top after the content swap drives a sticky recompute that WebKit mis-repaints. It is iOS-only (fine on desktop and Android, invisible in DevTools emulation), and neither compositor promotion (`translateZ(0)` / `will-change`) nor changing the swap paint timing fixes it. Preserving the header across nav is correct and standard, only the `sticky` positioning is the problem.
+
+The fix is `position: fixed`. A fixed header is always pinned and never does the scroll-relative recompute, so the repaint bug never fires. Because fixed leaves normal flow, reserve the header height on the content below with a single `--header-h` custom property (kept exact with a `ResizeObserver`, degrading fine with no JS):
+
+```css
+:root  { --header-h: 56px; }              /* sane SSR first-paint default */
+header { position: fixed; inset-inline: 0; top: 0; }
+body   { padding-top: var(--header-h); }
+```
+```js
+const hdr = document.querySelector('header');
+const apply = () => document.documentElement.style.setProperty('--header-h', hdr.offsetHeight + 'px');
+apply();
+new ResizeObserver(apply).observe(hdr);
+```
+
+For a dashboard, an alternative is an app-shell scroll container (a non-scrolling `100dvh` flex column with `<main>` as the internal scroller), which needs no offset but changes the scroll model.

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

@@ -0,0 +1,125 @@
+# Testing
+
+## What This Covers
+
+- The four test layers (unit, browser, e2e, smoke) and where each file lives.
+- The `handle()` harness from `@webjsdev/server/testing` for driving the real request pipeline against a native `Response`.
+- `webjs test` and `webjs test --browser`, plus when a browser or e2e test is REQUIRED (hydration, client router, slots, custom-element upgrade).
+- Bun cross-runtime parity for runtime-sensitive code.
+- Rendering the app and LOOKING for visual defects a static check cannot catch (a collapsed or reflowing layout).
+- Convention validation with `webjs check`.
+
+Read this when you are adding tests for a feature, deciding which layer a test belongs in, or verifying a UI or theming change. For component mount and hydration helpers see `components.md`. For testing actions and the `ActionResult` envelope see `data-and-actions.md`.
+
+## Test layers
+
+Feature folders are primary, and the test kind is a subfolder inside the feature ONLY when that kind is present. Never create an empty `browser/` or `e2e/` folder.
+
+| Kind | Location | What it does |
+|---|---|---|
+| unit + integration | `test/<feature>/<name>.test.{js,ts,mjs}` | Imports modules and asserts. No spawned process, no network. |
+| browser | `test/<feature>/browser/<name>.test.js` | Real DOM, events, shadow / light DOM, in Chromium, Firefox, and WebKit. |
+| e2e | `test/<feature>/e2e/<name>.test.{ts,mjs}` | Boots a real process and drives it over HTTP / browser / stdout. Opt in with `WEBJS_E2E=1`. |
+| smoke | `test/<feature>/smoke/<name>.test.{js,ts}` | Fast deploy-time sanity check, a subset of e2e in spirit. |
+
+Assert only on what the layer needs. A block that inspects only the HTTP response, the SSR HTML string, headers, or the importmap does NOT need a browser. Keep in the browser suite only blocks that genuinely need a DOM (live state via `page.evaluate`, hydration, client-router nav, slots, view transitions, streaming into the DOM, custom-element upgrade).
+
+## App runners (`webjs test`)
+
+```sh
+webjs test              # runtime test runner over everything not under browser/ or e2e/
+webjs test --browser    # web-test-runner against test/**/browser/**
+WEBJS_E2E=1 webjs test   # adds the e2e layer
+```
+
+`webjs test` dispatches on the runtime (`node --test` on Node, `bun test` on Bun). The scaffold's `web-test-runner.config.js` globs `test/**/browser/**/*.test.js` and is already wired, so you do not set it up.
+
+A scaffolded app has one root `test/` directory shaped the same way (feature first, kind second):
+
+```
+test/
+  auth/
+    auth.test.ts                 # signup / login / currentUser
+    browser/login-form.test.js   # only if exercising DOM
+  posts/
+    posts.test.ts
+    browser/post-editor.test.js
+```
+
+## The `handle()` harness (`@webjsdev/server/testing`)
+
+`createRequestHandler({ appDir }).handle(request)` drives the FULL request pipeline (middleware, routing, SSR, page actions, server-action RPC, auth, CSRF) and returns a native `Response`. It is the same entry the framework's own suite uses, so the most realistic way to test an app is to fire a `Request` through it and assert on the `Response`, with no spawned process and no network. `@webjsdev/server/testing` ships thin builders over that `handle()`, each a few lines over native `Request` / `Response` that reuse the REAL cookie names, header names, and wire serializer. For a browser test that needs to drive the app in a real DOM, `createBrowserTestHandler()` from `@webjsdev/server/testing` exposes the same `handle()` pipeline to the WTR Chromium session.
+
+```js
+import { createRequestHandler } from '@webjsdev/server';
+import { testRequest, invokeActionForTest, rawActionRequest, loginAndGetCookies, withSessionCookie }
+  from '@webjsdev/server/testing';
+
+const app = await createRequestHandler({ appDir: process.cwd(), dev: true });
+
+const res = await testRequest(app.handle, '/about');
+assert.equal(res.status, 200);
+assert.match(await res.text(), /About/);
+```
+
+A bare path is prefixed with a dummy origin (the pipeline reads only `pathname` and `search`); a full URL string or a pre-built `Request` also works. The optional third arg is a standard `RequestInit`.
+
+### Auth and session helpers
+
+Server-action CSRF is an Origin / `Sec-Fetch-Site` check, so a test needs no CSRF setup. `loginAndGetCookies` drives the REAL credentials login through `handle()` and captures the genuine signed session cookie, so a follow-up request can hit a protected route as the logged-in user.
+
+```js
+const gated = await testRequest(app.handle, '/dashboard');
+assert.equal(gated.status, 302);                     // -> /login
+
+const { cookies } = await loginAndGetCookies(app.handle, { email, password });
+const dash = await testRequest(app.handle, '/dashboard', withSessionCookie({}, cookies));
+assert.equal(dash.status, 200);
+```
+
+### `invokeActionForTest`: round-trip an action through the REAL endpoint
+
+```js
+// modules/posts/actions/create.server.ts exports createPost
+const out = await invokeActionForTest(app, 'modules/posts/actions/create.server.ts', 'createPost', [input]);
+```
+
+It serializes the args with the WebJs serializer exactly as the generated client stub does, POSTs them same-origin to `/__webjs/action/<hash>/<fn>`, and parses the response. Prefer this over a direct import of the action. A direct import bypasses three production concerns the endpoint enforces (the wire serializer, CSRF, and prod error sanitization), so `invokeActionForTest` catches a regression a direct import cannot see. For negative cases, `rawActionRequest(app, file, fn, args, { crossOrigin: true })` returns the raw `Response` and never throws on a non-2xx (pass `{ omitCsrf: true }` to drop the CSRF pair).
+
+## When a browser or e2e test is REQUIRED
+
+A unit test is necessary but NOT sufficient for any change to hydration, the client router, slots, or custom-element upgrade. The headline behaviour of these is a browser or e2e assertion, so ship one:
+
+- Hydration and the SSR-then-hydrate agreement.
+- Client-router navigation, form submissions through the router, prefetch.
+- Slots and light / shadow DOM projection.
+- Custom-element upgrade of the SSR'd tag.
+- Progressive soft-nav streaming (assert the fallback is live at the moment the URL advances) belongs in e2e (`WEBJS_E2E=1`).
+
+Component mount helpers (`fixture`, `ssrFixture`, `waitForUpdate`) come from `@webjsdev/core/testing`; see `components.md`.
+
+## Rendering the app and looking for UI defects
+
+A layout bug (a board that collapses, cells of unequal size, a grid that resizes as it fills) is invisible to `webjs check`, `webjs typecheck`, and a glance at the empty first paint. Static tools give no signal for a visual defect, so render the app in a real browser and look.
+
+- A browser test can measure real geometry with `getBoundingClientRect()` and FAIL on the defect. There is no framework helper (it is a few lines); write it against your component and assert its children stay the same size and do not resize as the grid fills. Ship one for any grid, board, or gallery layout.
+- Test both light AND dark mode. Light mode passing proves nothing about dark mode. Emulate dark (a `newContext({ colorScheme: 'dark' })` or the theme toggle) and inspect a component's COMPUTED `background-color` and `color`, not just the page chrome.
+- Read the screenshot. Capture `page.screenshot({ fullPage: true })` and open the PNG. White-on-white or a stray light box is obvious visually and invisible in the markup.
+
+## Bun cross-runtime parity
+
+WebJs runs on Node 24+ or Bun. The Node suite is the source of truth; an additive Bun matrix re-runs the runtime-sensitive suite under Bun to catch the long tail of cross-runtime incompatibilities (a `node:*` API Bun implements differently, a crypto or stream edge case, an error-message-format quirk).
+
+Bun parity is part of the definition of done. A change to a runtime-sensitive surface (the serializer, the `node:http` vs `Bun.serve` listener and request path, SSR / action / CSRF dispatch, streams, `node:crypto`, the TS stripper, auth / session / cors) is NOT done until you run the Bun matrix green AND add or update a `test/bun/<feature>.mjs` cross-runtime assertion. Run it with `node scripts/run-bun-tests.js` (needs `bun` on PATH).
+
+## Convention validation (`webjs check`)
+
+`webjs check` is the correctness validator. Every rule catches code that is wrong to ship (a crash, a security leak, a type-strip failure), plus the `no-scaffold-placeholder` sentinel for unreplaced scaffold content. Run it and fix every violation before considering the change done (`webjs check --json` for an agent loop, `webjs check --rules` to list the rules). It is separate from `CONVENTIONS.md`, which carries the customizable project conventions you follow by judgment.
+
+## What NOT to do
+
+- Do not recreate a top-level `test/{unit,browser,e2e}/` shape. Kind is a child of feature, never the reverse.
+- Do not create empty kind folders.
+- Do not import from another package's `test/` directory. Test code is not a public surface.
+- Do not add `.unit` / `.integration` filename suffixes. The folder tells you the kind.
+- Do not run WTR or Playwright inside a headless sandbox that lacks the transform plugins or native browser libraries. Instead, extract the reconciliation or optimistic-update logic into a pure browser-safe utility and cover it with a Node unit test.

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

@@ -0,0 +1,148 @@
+# TypeScript
+
+## What This Covers
+
+- TypeScript at runtime with **no build step**: `.ts` / `.mts` is stripped in place, not compiled.
+- **Erasable syntax only** (`erasableSyntaxOnly: true`) and the exact list of banned constructs, with their allowed rewrites.
+- The **pluggable stripper** (Node 24+ built-in vs `amaro` on Bun) and how the browser gets stripped source.
+- **Full-stack type safety**: server-action types flow to the call site, `import type` crosses the `.server` boundary, plus the carrier rule.
+- **Typing pages, layouts, and route handlers** with `PageProps` / `LayoutProps` / `RouteHandlerContext` and the generated route union (`webjs types`).
+
+Read this when you are writing `.ts` in a WebJs app, hit a strip-time 500, or want typed params and hrefs. For action signatures and the serializer wire see `data-and-actions.md`. For typing reactive props see `components.md`.
+
+TypeScript is optional. JS + JSDoc gets the same call-site safety (the language server reads `@typedef` / `@param` / `@returns` identically). Add `"checkJs": true` to enforce it.
+
+## No build step: how `.ts` runs
+
+`.ts` works everywhere `.js` does, same routing conventions, same server-action behaviour. There is no user-visible `tsc` run and no build output.
+
+- **Server-side** `.ts` imports are stripped by the runtime automatically (Node exposes `process.features.typescript === 'strip'`, Bun runs `.ts` natively).
+- **Browser-bound** `.ts` requests go through the pluggable stripper on the dev server, which does whitespace replacement (every source position maps to the same output position, so stack traces stay byte-exact with no sourcemap shipped). Cached by mtime.
+
+The stripper backs onto **Node 24+'s built-in `module.stripTypeScriptTypes`** (itself SWC's WASM transform in strip-only mode) or, on **Bun**, `amaro` loaded directly (byte-identical output). Force one with `WEBJS_TS_STRIPPER=builtin|amaro`.
+
+## Erasable syntax only
+
+The stripper supports **erasable TypeScript only**: type annotations, `interface`, `type`, `declare`, generics, `import type`, `as` casts, and `satisfies`. Non-erasable syntax is rejected at strip time (a 500 naming the file), so set `erasableSyntaxOnly: true` in `tsconfig.json` to catch it as an editor squiggle first. `webjs check`'s `erasable-typescript-only` rule verifies the flag is set.
+
+Banned constructs and their erasable rewrites:
+
+```ts
+// BANNED (rejected at compile + runtime)
+enum Color { Red, Green, Blue }
+class Foo { constructor(public x: number) {} }   // parameter property
+namespace Util { export const helper = 1; }       // value namespace
+import fs = require('fs');                         // import = require
+@legacyDecorator class C {}                        // legacy decorator + emitDecoratorMetadata
+
+// ALLOWED (canonical erasable forms)
+const Color = { Red: 'Red', Green: 'Green', Blue: 'Blue' } as const;
+type Color = typeof Color[keyof typeof Color];
+
+class Foo {
+  x: number;
+  constructor(x: number) { this.x = x; }
+}
+
+const Util = { helper: 1 };
+
+import * as fs from 'fs';
+```
+
+A third-party `.ts` dependency shipping non-erasable syntax fails the same way (rare, most npm packages publish compiled `.js`). WebJs is buildless end-to-end with no bundler fallback, so keep `erasableSyntaxOnly` on and your own code never hits it.
+
+Prefer explicit `.ts` extensions in imports. A `.js` specifier pointing at a `.ts` sibling also resolves in the dev server, but explicit `.ts` is clearer.
+
+## Minimum `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noEmit": true,
+    "checkJs": true,
+    "allowJs": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "erasableSyntaxOnly": true
+  }
+}
+```
+
+`erasableSyntaxOnly: true` is the non-negotiable line. It aligns the compiler's accepted syntax with the stripper's, so violations surface as diagnostics instead of a runtime 500.
+
+## Full-stack type safety
+
+### Server actions type-check automatically
+
+Calling a server action from a client component resolves at type-check time to the action's real source file. The runtime stub swap is invisible to the checker, and the RPC serializer makes runtime match the types (`Date` stays `Date`, `Map` stays `Map`, `BigInt` stays `BigInt`; see `data-and-actions.md` for the full supported set).
+
+```ts
+// modules/posts/actions/create-post.server.ts
+export async function createPost(
+  input: { title: string; body: string },
+): Promise<ActionResult<PostFormatted>> { /* ... */ }
+
+// modules/posts/components/new-post.ts
+import { createPost } from '#modules/posts/actions/create-post.server.ts';
+const r = await createPost({ title, body });
+//        ^ Promise<ActionResult<PostFormatted>>
+if (r.success) r.data.title;   // PostFormatted.title: string
+```
+
+Class instances arrive as plain objects (prototypes and methods lost, matching React Server Actions). The opt-in `SerializableActionFn` annotation turns that silent loss into a compile error (`Serializable<T>` / `SerializableArgs` / `SerializableResult` are also exported, all types-only).
+
+### The carrier rule: `import type` across the `.server` boundary
+
+A `.server.ts` file WITHOUT `'use server'` is a server-only utility whose browser stub throws at load. But a **type-only** `import type { Row } from '#db/schema.server.ts'` is safe: the stripper erases it before it can reach the browser, so sharing a derived row type from a `.server.ts` into a shipping component is fine and is not flagged. A **value** import of that same file into a shipping module is the crash the `no-server-import-in-browser-module` check catches. So carry TYPES over the boundary with `import type`, and carry DATA over it through a `'use server'` action (whose RPC stub loads safely client-side).
+
+### Typed page / layout / route-handler props
+
+Type each routing entry with the exported helpers so a param typo is a compile error.
+
+```ts
+import type { PageProps, LayoutProps, RouteHandlerContext } from '@webjsdev/core';
+
+// Static route: params is Record<string, string>.
+export default function About({ searchParams }: PageProps) { /* ... */ }
+
+// Dynamic route: pass the route literal to narrow params.
+export default function Post({ params }: PageProps<'/blog/[slug]'>) {
+  const slug = params.slug; // typed string
+}
+
+// Layout adds children.
+export default function RootLayout({ children }: LayoutProps) { /* ... */ }
+
+// Route handler's 2nd arg.
+export async function GET(req: Request, ctx: RouteHandlerContext) {
+  return Response.json({ id: ctx.params.id });
+}
+```
+
+With no route literal (or before you generate route types), `params` is `Record<string, string>`, the runtime default. With `R` set to a generated dynamic route, `params` narrows to its exact shape (`{ slug: string }`, `{ rest: string[] }`, `{ slug?: string[] }`). These are pure types, erased at runtime.
+
+Type page metadata with the exported `Metadata` type (and `MetadataContext` for the `generateMetadata` argument), the same ergonomics as Next.js's `import type { Metadata } from 'next'`.
+
+### The generated route union (`webjs types`)
+
+Run `webjs types` to write `.webjs/routes.d.ts`, an opt-in overlay augmenting `@webjsdev/core` with one key per route in `app/`. It narrows two things at tsserver time:
+
+- The `Route` href type: `navigate('/blog/anything')` passes, `navigate('/nonexistent')` is an error. Until you generate the types, `Route` is `string` (unconstrained, non-breaking for JSDoc and un-generated apps).
+- Per-route `params`: `PageProps<'/blog/[slug]'>['params']` becomes `{ slug: string }`.
+
+```sh
+webjs types     # writes .webjs/routes.d.ts (route count printed)
+```
+
+`webjs dev` emits it at startup and re-emits after each route rebuild, so the editor always has fresh types. The file is gitignored (regenerated per machine, like Next's `.next/types`); the scaffold `tsconfig.json` already lists it in `include`. To opt in for an existing app, run `webjs types` once and add `.webjs/routes.d.ts` to `include`. This is webjs's no-build equivalent of Next 15's `typedRoutes`, achieved via interface declaration-merging rather than a bundler.
+
+### The `webjs` config block and auth user
+
+The `webjs` object in `package.json` has two typed references so a typo'd key is diagnosed instead of dropped: a JSON Schema (VS Code flags an unknown key while you edit) and the `WebjsConfig` type from `@webjsdev/core`. Type `auth()`'s session user by augmenting the `AuthUser` interface (types every `auth()` call) or by parameterising `createAuth<AppUser>(...)` (types one instance), both types-only. Un-augmented, `user` resolves to `Record<string, unknown>`.
+
+Both `@webjsdev/core` and `@webjsdev/server` ship hand-authored `.d.ts` overlays with a `types` export condition, so a `strict` + `nodenext` app resolves real types for either import with no TS7016 error. The runtime stays plain `.js` + JSDoc; the overlays cost nothing at runtime.

package/templates/.claude/hooks/check-server-imports.mjs

@@ -75,7 +75,7 @@ const msg =
   `A .server.{ts,js} file with NO 'use server' directive throws at load in the browser, ` +
   `so this would crash the page (webjs check flags it as no-server-import-in-browser-module). ` +
   `Fix: add 'use server' to make it an RPC action, or reach it from a 'use server' action / route.ts / ` +
-  `middleware.ts, or share only a type via 'import type'. See agent-docs/types-and-mutations.md.`;
+  `middleware.ts, or share only a type via 'import type'. See the skill's references/data-and-actions.md.`;
 
 if (process.env.WEBJS_SERVER_IMPORT_GATE === 'block') {
   process.stderr.write(`BLOCKED: ${msg}\n`);

package/templates/.claude/hooks/require-tests-with-src.sh

@@ -7,7 +7,7 @@
 # default. But it is a CONVENTION, not a correctness check: a sensible
 # app can legitimately want a test-less commit (a spike, a vendored
 # file, a pure refactor). The convention-vs-check principle in this
-# app's AGENTS.md and CONVENTIONS.md says guidance like this WARNS, it
+# app's AGENTS.md says guidance like this WARNS, it
 # does not hard-block by default. So this hook surfaces a loud reminder
 # and lets the commit proceed.
 #

package/templates/.claude/settings.json

@@ -1,15 +1,5 @@
 {
   "hooks": {
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": ".claude/hooks/route-skills.sh"
-          }
-        ]
-      }
-    ],
     "PreToolUse": [
       {
         "matcher": "Write|Edit|MultiEdit",
@@ -83,10 +73,6 @@
           {
             "type": "command",
             "command": ".claude/hooks/commit-before-stop.sh"
-          },
-          {
-            "type": "command",
-            "command": ".claude/hooks/design-review-before-stop.sh"
           }
         ]
       }