@webjsdev/mcp 0.1.16 → 0.1.18

package/resources/references/runtime.md

@@ -35,6 +35,7 @@ Three seams pick a runtime-specific implementation, all inside the framework, no
 | Hot reload | restart on change (the `webjs dev` supervisor, #1521) | in place in one long-lived process (`bun --hot` resets the module registry, #1575); only an `instrumentation.*` / `env.*` edit restarts it |
 | WebSocket | the `ws` library | native `Bun.serve` + a bridge adapter |
 | 103 Early Hints | yes | no (`Bun.serve` has no informational-response API) |
+| Response compression (prod) | brotli / gzip / deflate over `node:zlib`: a buffered body (an SSR page, JSON, a module) is compressed synchronously and sent with its `Content-Length`, a streamed body through a streaming compressor, a buffered body under 1 KB is sent as is, and a buffered body under 32 KB is gzip-encoded even when brotli is accepted (gzip 6 is 2 to 3x cheaper than brotli 4 at that size for a few percent more bytes, #1646) | same (both shells share the seam, the 1 KB floor and the 32 KB brotli floor) |
 | Dev edit to a page / layout | full reload (the dev restart replaces the process) | refreshes IN PLACE, no reload (#1398) |
 | Reverse-proxy headers | `X-Forwarded-Proto` / `X-Forwarded-Host` honored | same |
 
@@ -42,7 +43,7 @@ Three seams pick a runtime-specific implementation, all inside the framework, no
 
 **The in-place dev refresh (#1398) needs the server process to SURVIVE the edit,** which is the whole of the Node-versus-Bun difference in that row. A page or layout never hydrates, so a freshly rendered page is the complete truth for it and the client router can swap it in without a reload, keeping scroll and (for a page edit) the hydrated state of components outside the changed region. The server classifies the changed file and puts the verdict on the live-reload event, so this needs a process that is still alive to do the classifying.
 
-Bun keeps ONE dev server process for the whole session (#1575), so it gets the refresh. `bun --hot` re-runs the CLI on a change; the first run's server owns the process (its listener, live-reload stream, watchers and analysis caches) and a re-run only tells it the module registry was reset, so nothing is started twice and memory stays flat over hundreds of edits (it used to grow about 25 MB an edit until `bun --hot` stopped reloading). The app's modules load through a `Bun.plugin` that reads them fresh, and its `#` imports resolve through the app's own `imports` map, because Bun keeps the old source of a file that was replaced (an atomic save) and a stale directory listing for a new file next to a `*.server.*` module. So `bun --hot` no longer sees app edits itself, and the dev server asks it for a registry reset after an edit to a module some other module imports, a new module, or a `*.server.*` module, all without a process restart. A page, layout or route handler nothing imports needs no reset: the dev re-import is keyed by the file's content, so an unchanged file reuses its loaded module (no new module instance per request) and an edited one is a new import. `instrumentation.*` and `env.*` run once per process, so an edit to one restarts the server on both runtimes. On Node the `webjs dev` supervisor (it replaced `node --watch` in #1521) RESTARTS the server process on a change under `app`, `components`, `modules`, `lib`, or `actions`, or to a root `middleware.{ts,js,mts,mjs}`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE that watched set (`db/schema.server.ts`, a `webjs.dev.watch` content dir), and running `npm run dev -- --no-hot`, which keeps the server in one process on either runtime. An in-place refresh loads the rebuilt stylesheets (a `webjs.dev.regenerate` compile runs on that request) BEFORE it swaps the new markup in, and drops the old sheets only after, so an element that gained a utility class never paints without its rule (#1535; a full reload never had the gap, since a head stylesheet is render-blocking). A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
+Bun keeps ONE dev server process for the whole session (#1575), so it gets the refresh. `bun --hot` re-runs the CLI on a change; the first run's server owns the process (its listener, live-reload stream, watchers and analysis caches) and a re-run only tells it the module registry was reset, so nothing is started twice and memory stays flat over hundreds of edits (it used to grow about 25 MB an edit until `bun --hot` stopped reloading). The app's modules load through a `Bun.plugin` that reads them fresh, and its `#` imports resolve through the app's own `imports` map, because Bun keeps the old source of a file that was replaced (an atomic save) and a stale directory listing for a new file next to a `*.server.*` module. So `bun --hot` no longer sees app edits itself, and the dev server asks it for a registry reset after an edit to a module some other module imports, a new module, or a `*.server.*` module, all without a process restart. A page, layout or route handler nothing imports needs no reset: the dev re-import is keyed by the file's content, so an unchanged file reuses its loaded module (no new module instance per request) and an edited one is a new import. `instrumentation.*` and `env.*` run once per process, so an edit to one restarts the server on both runtimes. On Node the `webjs dev` supervisor (it replaced `node --watch` in #1521) RESTARTS the server process on a change under `app`, `components`, `modules`, `lib`, `actions`, or `db` (a schema edit has to reach a fresh process, #1664; only JS and TS source under `db/` counts, so a database file and its sidecars never restart it), or to a root `middleware.{ts,js,mts,mjs}`, and a fresh process holds no record of what changed, so those edits are always a full reload. Two Node cases still refresh in place: an edit OUTSIDE that watched set (a `webjs.dev.watch` content dir), and running `npm run dev -- --no-hot`, which keeps the server in one process on either runtime. An in-place refresh loads the rebuilt stylesheets (a `webjs.dev.regenerate` compile runs on that request) BEFORE it swaps the new markup in, and drops the old sheets only after, so an element that gained a utility class never paints without its rule (#1535; a full reload never had the gap, since a head stylesheet is render-blocking). A component edit is a full reload everywhere by design, because `customElements.define` is once-per-tag and swapping fresh markup onto the old class would be worse than the reload.
 
 After a reset, app code that imports `@webjsdev/server` gets a fresh copy of the package while the first run's server keeps handling requests. Everything the two copies must agree on (the request `auth()`, `cookies()` and `headers()` read, the action signal, the seed collector and action identity, the default cache store, sessions, broadcast clients) lives in process-wide state keyed by `Symbol.for`, so a signed-in page and the `'use server'` queries it calls still see the request after any number of edits (#1590). Before that fix, `auth()` without an explicit request returned `null` in app code after the first edit.
 
@@ -97,6 +98,10 @@ Both `node:sqlite` and `bun:sqlite` default `busy_timeout` to 0, so a contended
 
 A `--db postgres` app opens one `pg` Pool in `db/connection.server.ts`. It holds no session state between queries (no `SET`, `LISTEN`, or advisory lock kept across them), so the same code works behind a transaction pooler. Idle connections close after 10 seconds, a connection attempt gives up after 5 seconds (a database that is down fails the request instead of hanging it), `DATABASE_POOL_MAX` caps the pool (default 10), and an idle connection the server drops (a restart or failover) is logged rather than crashing the process. Keep it that way: do not add `SET` statements or session-scoped features to app code.
 
+## Knowing when an edit has settled
+
+After an edit, the dev server rebuilds and re-analyses the app, and on Node it may restart first. The reload frame a tab receives goes out BEFORE anything is re-imported, so a broken module only shows on the next request. Do not `sleep` and grep a page for "Server error". Run `npx webjs status [path...]` (#1664): it waits until the change has been rebuilt and the analysis has run again (retrying through a Node restart), requests each path (the app root when none is given) plus every page with a recorded render error, then prints every error, render, TypeScript strip, rebuild, route handler, server action, middleware, with its file, line and code frame. A render error stays listed across an unrelated rebuild until that url answers below 500 again (fixed, or deleted and now a 404), and the other kinds clear on each rebuild. A page re-requested only because of an old error fails the run on a server error, not on a 404. It exits 0 when settled and clean, 1 on any problem, 2 when no dev server answered; `--json` gives one document an agent can branch on. The same data is the dev-only `GET /__webjs/dev/status?wait=<seconds>` (`{ status, settled, ready, boot, seq, rebuilds, errors }`), which answers 404 under `npm run start`.
+
 ## Verifying a runtime-sensitive change
 
 Most app code needs no runtime-specific testing, because it does not touch a runtime seam. If you DO change something runtime-sensitive (the serializer, a stream, `node:crypto`, low-level request handling, anything that behaves differently under `Bun.serve` versus `node:http`), prove it on both runtimes. The Node suite is the source of truth, and an additive Bun matrix re-runs the runtime-sensitive tests under Bun. See `testing.md` for the cross-runtime matrix and the `test/bun/**` assertions.

package/resources/references/styling.md

@@ -150,9 +150,9 @@ Native `<button>` / `<a>` / `<input>` already have correct focus + keyboard beha
 
 ## Design tokens and theming
 
-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 declared once in the root layout. You consume them as utility classes (`bg-background`, `text-foreground`, `bg-card`, `border-border`, `font-serif`).
+The default stack is a static compiled Tailwind stylesheet (the `webjs.dev.regenerate` rule compiles `public/input.css` to the linked `public/tailwind.css`, so it works with JS off; `webjs regenerate` in `dev.before` / `start.before` builds it only when stale and records the build, and `npm run css:build` is the same compile by hand, unrecorded) plus `@theme` design tokens declared once in the root layout. You consume them as utility classes (`bg-background`, `text-foreground`, `bg-card`, `border-border`, `font-serif`).
 
-**Two halves.** (1) `public/input.css` MAPS token names into Tailwind with `@theme inline` (`--color-background: var(--background)`), so `bg-background` resolves to `var(--background)`. That is infrastructure; leave it. (2) The root layout (`app/layout.ts`) DEFINES the values as plain CSS custom properties in a `<style>` block. That is your palette; make it your own. A freshly cleared app (after `npm run gallery:clear`) ships only the OS system-colour base (`Canvas` / `CanvasText`) with NO tokens, so building this palette is your first styling step.
+**Two halves.** (1) The `@theme inline` maps (`--color-background: var(--background)`) turn token names into utilities, so `bg-background` resolves to `var(--background)`. That is infrastructure; leave it. (2) The VALUES live in `styles/globals.css`, inside the theme block `webjs ui init` owns (between `/* @webjsdev/ui theme */` and `/* @webjsdev/ui theme end */`): the light ones on `:root`, the dark ones on `.dark`, the fonts in the block's `@theme inline`. That is your palette; make it your own, by editing the block or with `npx webjsdev ui init --preset <code>` (a code from webjs.dev/ui/create), which replaces it. The scaffold writes its gallery palette there, and a cleared app keeps it. **Never redefine a theme token in the root layout**: a `<style>` there comes after the stylesheet, so it wins, and every later preset or block edit silently stops showing. Tokens your app adds itself go AFTER the block's end marker, where a preset leaves them alone.
 
 **`@theme` and `@theme inline` differ in whether the token reaches `:root`, and the difference is silent.** Measured on `tailwindcss@4.3.0`, a token mapped in a theme block is emitted as a real `:root` custom property when:
 
@@ -167,7 +167,7 @@ The one cell that bites is `inline` plus utility-only usage. Nothing on the page
 
 Whichever form you use, a token nothing references is dropped in both, so an unused mapping is dead configuration rather than a safety net.
 
-**Light and dark, defined once (DRY).** Write each colour token ONE time with the native CSS `light-dark(LIGHT, DARK)` function and let `color-scheme` pick the side. The default `color-scheme: light dark` follows the OS; a `[data-theme]` attribute forces one. No duplicated light/dark blocks:
+**Light and dark, defined once (DRY), for tokens you write by hand.** The kit's theme block uses `:root` plus `.dark`, the shape a preset writes. For a palette you author yourself (in place of the block's values, or for your own extra tokens after it), you can instead write each colour token ONE time with the native CSS `light-dark(LIGHT, DARK)` function and let `color-scheme` pick the side. The default `color-scheme: light dark` follows the OS; a `[data-theme]` attribute forces one. No duplicated light/dark blocks:
 
 ```html
 <style>
@@ -195,7 +195,7 @@ Whichever form you use, a token nothing references is dropped in both, so an unu
 
 `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.
+**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. When the palette itself lives on `.dark` (the kit's theme block, the scaffold's shape), switch `color-scheme` on the same class (`:root { color-scheme: light } :root.dark { color-scheme: dark }`, with `<meta name="color-scheme" content="light">`): only the script sets `.dark`, so with JavaScript off the page is light throughout, where `color-scheme: light dark` would draw OS-dark native controls and scrollbars over light tokens. Verify dark mode in a real browser. Light mode passing proves nothing about dark.
 
 **Edge cases.** `light-dark()` is COLOUR-only. A colour needed in just one theme sets the unused side to a no-op (`light-dark(#fff, transparent)`). A derived token that references a `light-dark()` one (like `--primary-tint` above) tracks both themes automatically. A NON-colour token that must differ per theme (a shadow's geometry, a gradient, a size, an image) cannot use `light-dark()`; give it a `:root[data-theme='dark']` override plus an `@media (prefers-color-scheme: dark) { :root:not([data-theme]) { ... } }` rule for the OS default.
 
@@ -203,6 +203,22 @@ Whichever form you use, a token nothing references is dropped in both, so an unu
 
 **Focus rings.** The design system applies ONE themed, keyboard-only focus ring globally in the theme CSS: `@layer base { * { @apply border-border outline-ring/50 } }` themes the outline COLOUR to `--ring/50`, and a `:focus-visible { outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent); outline-offset: 2px }` forces a SOLID outline. That second rule matters: `outline-ring/50` alone leaves `outline-style: auto`, so the browser draws its OWN focus ring (which can look thick and white and ignore the colour). So every focusable element (button, link, input) shares one `--ring`-coloured ring with no per-element styling (a native `<button>` renders it a touch wider than a link, a Chromium form-control quirk, but the colour is the same). Do NOT re-add a focus style on a light-DOM element (`buttonClass` deliberately carries none), and NEVER remove it (`outline: none` with no replacement fails WCAG 2.4.7). `:focus-visible` already limits the ring to keyboard / programmatic focus, not a mouse click. A SHADOW-DOM component is the ONE exception: a document rule cannot cross the shadow boundary, so it styles its own focus in `static styles`, matching the global ring EXACTLY (`--ring` at 50%, the same as `outline-ring/50`): `button:focus-visible { outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent); outline-offset: 2px }`. Without it, its controls fall back to the raw browser outline (thick, light on a dark theme, and shown on window-refocus).
 
+## A stylesheet for one section of the app
+
+When one part of the app has its own stylesheet (an admin area, a docs section, a component gallery), link it from THAT section's layout, as the first thing the layout renders, and leave the root layout alone:
+
+```ts
+// app/admin/layout.ts
+export default function AdminLayout({ children }: LayoutProps) {
+  return html`
+    <link rel="stylesheet" href=${asset('/public/admin.css')}>
+    <div class="admin-shell">${children}</div>
+  `;
+}
+```
+
+The server moves a `<link rel="stylesheet">` at the start of any layout's or page's output into `<head>`, after the root layout's own links, so it blocks first paint like a root stylesheet does (#1669). Comments and other `<link>` tags before it are fine; any other element ends the run, so a link further down stays where it is. A second link to a file the head already links is dropped, whether its href is written relative or absolute (a link with a different `media` is a different sheet, so a print copy and a screen copy are both kept). A page with a `loading.{js,ts}` boundary is the one exception: it streams in after the head is sent, so its own leading link is not hoisted; link that page's sheet from its layout instead. The hoisted link is marked with the layout that owns it, so when a soft navigation leaves the section the client router switches the sheet off, and switches it back on when the reader returns (see `references/client-router-and-streaming.md`). Do NOT also link the section's sheet from the root layout by pathname: the root layout is not re-rendered on a soft navigation, so that copy is never switched off and outlives the section.
+
 ## 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 }`).
@@ -249,21 +265,22 @@ Verify a layout by USING it, not by glancing at the first paint. A layout bug on
 
 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):
+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, and size the header BY that property:
 
 ```css
-:root  { --header-h: 56px; }              /* sane SSR first-paint default */
-header { position: fixed; inset-inline: 0; top: 0; }
+:root  { --header-h: 3.5rem; }
+header { position: fixed; inset-inline: 0; top: 0; height: var(--header-h); }
 body   { padding-top: var(--header-h); }
+html   { scroll-padding-top: var(--header-h); }  /* #anchor jumps stop below the header */
 ```
-```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.
+The last line matters as soon as a page has in-page links: without it an `#anchor` jump, native or the client router's `scrollIntoView`, lands the target under the header. Next's app router reads the same `scroll-padding-top` when it scrolls a segment into view, and shadcn's site sets it from its header-height variable.
+
+With Tailwind, that is `class="fixed inset-x-0 top-0 h-[var(--header-h)]"` on the header. The scaffold's layout already carries the token and a `body:has(> header.fixed)` rule, so pinning its navbar is adding `fixed inset-x-0 top-0 z-20` and nothing else. Pinning from a breakpoint up works the same way: `md:fixed md:inset-x-0 md:top-0` pins it on wider screens only, because `public/input.css` carries a matching rule for each default breakpoint written with Tailwind's `@variant`, so it follows the app's own `--breakpoint-*` values. A breakpoint added under a new name needs its own line beside them.
+
+**Do not measure the header with JavaScript.** The tempting version, a `<head>` script that writes `offsetHeight` into `--header-h` from a `ResizeObserver`, breaks on a client-router swap that replaces the header (a layout refresh, a form action that re-renders the layouts): the observer fires for the detached old node, reads a height of 0, and the content slides under the navbar with no way back short of a reload. The head script never re-runs, so nothing re-measures. A token the header is sized by cannot drift, because there is nothing to keep in sync.
+
+A header whose height changes by breakpoint sets the token per breakpoint (`@media (min-width: 768px) { :root { --header-h: 4rem } }`). A header that genuinely wraps to an unknown height belongs in an app-shell scroll container instead: a non-scrolling `100dvh` flex column with `<main>` as the internal scroller, which needs no offset at all but changes the scroll model.
 
 ### A fixed header and a modal that locks scroll
 

package/resources/references/typescript.md

@@ -105,7 +105,7 @@ The ladder, in the order to climb it:
 | That row inside a shipping component | `import type { Todo } from '#db/schema.server.ts'` | `any[]`, or re-declaring the shape by hand |
 | A server action's input | a named `interface CreatePostInput` | `input: unknown` / `input: any` |
 | A server action's result | `Promise<ActionResult<Post>>` | `Promise<any>` |
-| `export const validate` | `(input: unknown)`, narrowed in the body, returning `data` that `satisfies` the action's input type | `(input: any)`, which un-types the returned `data` too |
+| `export const validate` | `(input: unknown)`, narrowed in the body, returning `data` that `satisfies` the action's input type. On every boundary the input reads by property (`raw.title`), on a form submission as strings and `File`s | `(input: any)`, which un-types the returned `data` too |
 | A page | `PageProps<'/blog/[slug]'>` | `{ params: Record<string, any> }` |
 | A layout | `LayoutProps` (whose `children` is a `TemplateResult`) | `{ children: unknown }` |
 | A route handler's 2nd argument | `RouteHandlerContext<'/api/users/[id]'>` | `{ params: any }` |

package/resources/references/ui-kit.md

@@ -29,15 +29,49 @@ once while composing, not code that should sit in your repo. Get the full
 paste-ready structure on demand:
 
 - **MCP `ui` tool** (preferred when available): call `ui` with no args for the
-  kit inventory (each component's tier, helper signatures, npm deps); pass
-  `{ name: "accordion" }` for one component's helper signatures, the paste-ready
-  structural example, the accessibility header, and deps.
+  kit inventory (each component's tier, helper signatures, npm deps, plus the
+  block and chart names); pass `{ name: "accordion" }` for one component's
+  helper signatures, the paste-ready structural example, the accessibility
+  header, and deps.
 - **CLI**: `npx webjsdev ui list` (inventory), `npx webjsdev ui view <name>` (the projected
   view plus the full source). Same data as the MCP tool (one shared projector).
 
 So the loop is: `add` the component, then query `ui <name>` (MCP) or
 `npx webjsdev ui view <name>` for the accessible structure, paste it, and fill it in.
 
+## Blocks and charts: install a view, do not write one
+
+**Rule: before hand-writing a login or signup page, an app sidebar shell, a
+dashboard, a data table or a chart, list the blocks and install the closest
+one.** A block is a ready-made view you install and then edit. Its files land
+in your app as code you own, so you spend your effort on the app instead of
+regenerating a page shell.
+
+- **Find one.** The MCP `ui` tool with no args lists the block and chart NAMES
+  grouped by category; `{ type: "block" }` or `{ category: "login" }` adds a
+  one-line description each. On the CLI, `npx webjsdev ui list --type block`
+  (or `--category login`, and `--json` for a compact array).
+- **See what it installs.** `ui { name: "login-03" }` (MCP) or
+  `npx webjsdev ui view login-03 --files-only` returns the description, the
+  components it depends on, the install command, and every file with the path
+  it lands at (`app/login/page.ts`, `components/login-form.ts`). Ask for the
+  sources only if you need them before installing (`source: true`, or `view`
+  without `--files-only`); installing and reading the files is cheaper.
+- **Install it.** `npx webjsdev ui add login-03`. It writes each file to its
+  target, installs the components it uses, rewrites every import to your
+  aliases, and adds any design tokens it needs that your stylesheet lacks. A
+  file that already exists is kept unless you pass `--overwrite`, and the
+  command lists what it wrote.
+- **Then edit it.** Rename the route, change the copy, and wire the form: a
+  block's form has no `action`, so bind your `'use server'` action
+  (`<form action=${signIn}>`) as `references/data-and-actions.md` describes.
+
+Shipped today: shadcn's ten authentication blocks, `login-01` to `login-05`
+and `signup-01` to `signup-05` (categories `authentication` plus `login` or
+`signup`). A chart is a block whose categories include `chart`
+(`type: "chart"` lists them). The list grows, so query it rather than trusting
+this paragraph.
+
 ## Setup and resolution
 
 - `npx webjsdev ui init` writes `components.json`, `lib/utils/cn.ts`, and the CSS design

package/src/mcp-docs.js

@@ -400,8 +400,9 @@ export async function initText(deps) {
     'pull the specific docs you need via the `docs` tool or the `webjs-docs://*`',
     'resources. webjs is web-components-first and looks like Lit + Rails, NOT React/Next:',
     'there is NO RSC, no server/client component split, no `use client`. Components',
-    'hydrate (islands); pages and layouts do NOT hydrate. Signals are the default',
-    'state primitive. Server-only code lives behind the `.server.{js,ts}` boundary.',
+    'hydrate (islands); pages and layouts do NOT hydrate. State works as in Lit',
+    '(`state: true` props) alongside signals. Server-only code lives behind the',
+    '`.server.{js,ts}` boundary.',
     'When writing a component, read `webjs-docs://lit-muscle-memory-gotchas` first:',
     'the Lit habits that break webjs SSR/reactivity each have a webjs-shaped fix there.',
     '',
@@ -564,7 +565,8 @@ const PROMPT_BODIES = {
   ].join('\n'),
   add_component: [
     'Add an interactive WebComponent. One custom element per file; register at module',
-    'top level. Signals are the default state; read with `.get()` inside render().',
+    'top level. Hold state in a `state: true` prop (reassign it) or a signal (read with',
+    '`.get()`, write with `.set()`).',
     '',
     '```ts',
     "import { WebComponent, html, signal } from '@webjsdev/core';",

package/src/mcp.js

@@ -105,13 +105,26 @@ const DOCS_SCHEMA = {
   required: [],
 };
 
-/** `ui` lists the @webjsdev/ui kit, or details one component by `name`. */
+/** `ui` lists the @webjsdev/ui kit, or details one component or block by `name`. */
 const UI_SCHEMA = {
   type: 'object',
   properties: {
     name: {
       type: 'string',
-      description: 'A component name (e.g. button, accordion, dialog). Omit for the full kit inventory.',
+      description: 'A component (button, dialog) or block (login-01) name. Omit for the inventory.',
+    },
+    type: {
+      type: 'string',
+      enum: ['ui', 'block', 'chart', 'all'],
+      description: 'List one kind with one-line descriptions: ui (components), block, chart, or all.',
+    },
+    category: {
+      type: 'string',
+      description: 'List the blocks and charts in one category (login, signup, sidebar, dashboard, area, ...) with descriptions.',
+    },
+    source: {
+      type: 'boolean',
+      description: 'With a block `name`: include the file sources. Off by default, since installing the block and reading the files is cheaper.',
     },
   },
   required: [],
@@ -170,7 +183,7 @@ const TOOL_DEFS = [
   {
     name: 'ui',
     description:
-      'The @webjsdev/ui component kit (shadcn-style, copied into your repo). No args returns the inventory (each component: tier, helper signatures, npm deps); pass `name` for one component: helper signatures, the paste-ready structural example, the a11y/description header, and deps. Use before hand-writing UI so you reach for a helper (e.g. buttonClass()) and the accessible structure instead of expanding Tailwind blind. Reads the kit, not your app. Read-only.',
+      'The @webjsdev/ui kit (shadcn-style, copied into your repo): components, plus blocks and charts (a block is a ready-made view you install and then edit: a login or signup page, a sidebar shell, a dashboard, a chart). No args returns the component inventory (tier, helper signatures, npm deps) and the block and chart NAMES grouped by category; `type` / `category` list them with one-line descriptions. Pass `name` for one component (helper signatures, the paste-ready example, the a11y header, deps) or one block (description, dependencies, the install command, and the files it writes with their targets; `source: true` adds the sources). Before hand-writing a page, a dashboard, a sidebar shell, an auth form or a chart, look for a block and install it. Reads the kit, not your app. Read-only.',
     inputSchema: UI_SCHEMA,
   },
   {
@@ -420,16 +433,6 @@ export function makeToolRunners(deps) {
   };
 }
 
-/**
- * Run the `ui` tool: the @webjsdev/ui kit inventory (no args) or one component's
- * projection (helper signatures + paste-ready example + a11y/description header
- * + deps). Projects the SHARED `@webjsdev/ui/registry/extract` leaf, the same
- * one `webjsui view` renders, so the CLI and MCP cannot drift (#983, the #979
- * shared-projector pattern). `uiDeps` is injected so tests need no real package.
- *
- * @param {{ uiInventory: Function, uiComponent: Function }} uiDeps
- * @param {{ name?: string }} args
- */
 /**
  * Resolve the `ui` tool's deps from the shared `@webjsdev/ui/registry/extract`
  * leaf, GUARDED (#983): if `@webjsdev/ui` is absent or too old to carry the
@@ -439,29 +442,70 @@ export function makeToolRunners(deps) {
  * top-level import would instead reject during bootstrap and sink the whole
  * server. `importer` is injected so the failure path is unit-testable.
  *
- * @param {() => Promise<{ uiInventory: Function, uiComponent: Function }>} importer
- * @returns {Promise<{ uiInventory: Function, uiComponent: Function }>}
+ * A `@webjsdev/ui` that predates blocks (no `uiBlocks` export) still serves
+ * the components: the block deps then answer with nothing rather than throw.
+ *
+ * @param {() => Promise<any>} importer
+ * @returns {Promise<UiDeps>}
  */
 export async function loadUiDeps(importer) {
   try {
     const ui = await importer();
-    return { uiInventory: ui.uiInventory, uiComponent: ui.uiComponent };
+    return {
+      uiInventory: ui.uiInventory,
+      uiComponent: ui.uiComponent,
+      uiBlocks: ui.uiBlocks ?? (() => []),
+      uiBlockIndex: ui.uiBlockIndex ?? (() => ({ blocks: {}, charts: {} })),
+      uiBlock: ui.uiBlock ?? (() => null),
+    };
   } catch {
     const unavailable = () => {
       throw new Error('@webjsdev/ui is not available (install/upgrade @webjsdev/ui to use the ui tool)');
     };
-    return { uiInventory: unavailable, uiComponent: unavailable };
+    return { uiInventory: unavailable, uiComponent: unavailable, uiBlocks: unavailable, uiBlockIndex: unavailable, uiBlock: unavailable };
   }
 }
 
+/**
+ * @typedef {{
+ *   uiInventory: Function, uiComponent: Function,
+ *   uiBlocks: Function, uiBlockIndex: Function, uiBlock: Function,
+ * }} UiDeps
+ */
+
+/**
+ * Run the `ui` tool. No args: the component inventory plus the block and chart
+ * names grouped by category. `type` / `category`: one compact entry per match
+ * with its description. A component `name`: its projection (helper signatures,
+ * paste-ready example, a11y header, deps). A block `name`: its description,
+ * dependencies, install command and files with targets (sources with
+ * `source: true`). Projects the SHARED `@webjsdev/ui/registry/extract` leaf,
+ * the same one `webjsui view` renders, so the CLI and MCP cannot drift (#983,
+ * the #979 shared-projector pattern). `uiDeps` is injected so tests need no
+ * real package.
+ *
+ * @param {UiDeps} uiDeps
+ * @param {{ name?: string, type?: string, category?: string, source?: boolean }} args
+ */
 export function runUiTool(uiDeps, args) {
   const name = typeof args.name === 'string' && args.name ? args.name : null;
-  if (!name) return { inventory: uiDeps.uiInventory() };
-  const component = uiDeps.uiComponent(name);
-  if (!component) {
-    throw new Error(`Unknown component "${String(name)}". Call ui with no args for the inventory.`);
+  const type = typeof args.type === 'string' && args.type ? args.type : null;
+  if (type && !['ui', 'block', 'chart', 'all'].includes(type)) {
+    throw new Error(`Unknown type "${type}". Use ui, block, chart or all.`);
   }
-  return component;
+  const category = typeof args.category === 'string' && args.category ? args.category : null;
+  if (!name) {
+    // A filter lists one kind with its one-line descriptions. The bare call
+    // stays cheap: the component inventory plus the block and chart NAMES by
+    // category (D18), and a test caps its size.
+    if (type || category) return { items: uiDeps.uiBlocks({ type: type ?? undefined, category: category ?? undefined }) };
+    return { inventory: uiDeps.uiInventory(), ...uiDeps.uiBlockIndex() };
+  }
+  const component = uiDeps.uiComponent(name);
+  if (component) return component;
+  const block = uiDeps.uiBlock(name, { source: args.source === true });
+  if (block) return block;
+  throw new Error(`Unknown component or block "${String(name)}". Call ui with no args for the inventory.`);
 }
 
 /**