@webjsdev/mcp 0.1.14 → 0.1.16

package/resources/references/components.md

@@ -30,7 +30,7 @@ Most of what follows restates widely held component-model advice, ported. Lit's
 
 **4. ARIA state is a hole in `render()`, derived from the same state that drives behaviour.** `aria-expanded=${this.open ? 'true' : 'false'}` cannot disagree with `this.open`. A second function that re-finds the button and calls `setAttribute` can, and does, the first time someone adds a close path that forgets to call it. The same holds for `class`, `?disabled`, and any `.prop`. Two caveats ride this rule:
 
-- Write the string explicitly for a tri-state ARIA attribute. A plain-attribute hole holding `false` serves `aria-expanded="false"` from the server and hydrates to NO attribute, because the client removes an attribute for `null` / `undefined` / `false` while the server stringifies it. `?attr=${bool}` is not a substitute, since a boolean binding omits the attribute in BOTH renderers.
+- A plain-attribute hole follows one rule on the server and the client (#1573): `null` / `undefined` omit the attribute, `false` omits it except on an `aria-*` name, where it is written as `"false"`, and `true` on an HTML boolean attribute (`checked`, `selected`, `disabled`, ...) writes the empty value like `?attr` (#1579). So `checked=${isDefault}` and `selected=${i === 0}` behave exactly like `?checked` / `?selected`, though `?attr` stays the clearer spelling for a boolean attribute. So `aria-expanded=${this.open}` serves `"true"` / `"false"` and hydrates unchanged, and `aria-current=${active ? 'page' : null}` omits the attribute on an inactive link. `?attr=${bool}` is not a substitute for a tri-state ARIA attribute, since a boolean binding omits the attribute when false.
 - A hole commits on the next render, one microtask later. The one place a direct write is still correct is a synchronous snapshot read such as `webjs:before-cache`, where the router reads `outerHTML` in the same task. That is a documented exception, not the normal path.
 
 **5. Behaviour needs an importable surface, or its test is a copy of it.** An inline `<script>` in a layout has no module identity, so a browser test cannot import it. It can only transcribe the listener into the test file and assert against the transcription, which then needs a SECOND test to grep the original for drift. Two tests, neither running shipping code. A component is importable, so its browser test mounts the real element and drives real events. A page or layout may still carry an inline `<script>`, but only for pre-paint boot work no module can do: reading a stored theme before first paint so the wrong palette never flashes, or measuring the header height into a CSS custom property. It must not be interactivity, and WHERE it sits decides how often it runs. The ROOT layout's markup sits OUTSIDE every swap range, so a soft navigation does not re-run its script, which is what makes it the right home for boot work and the wrong home for anything that has to respond to a later navigation. A page or a NESTED layout sits inside the swap range instead, so its script re-executes on every navigation that swaps that range (#1102), which means it has to be idempotent or guard on a flag it sets the first time. Neither shape gives you a listener that simply works, which is what a custom element is for. Under an opt-in CSP the script also needs the nonce from `cspNonce()`. `client-router-and-streaming.md` carries the full re-execution rule.
@@ -101,6 +101,44 @@ NavDrawer.register('nav-drawer');
 
 This repo's own website is the worked example. Before commit `b80de906` the docs drawer and the header menu were exactly the first shape, and every accessibility bug their tests now pin came out of the split. `website/components/docs-drawer.ts` and `website/components/site-nav-menu.ts` are the second shape, and `website/AGENTS.md` records the app-level version of these rules under "What stays inline script in the root layout".
 
+## Sizing an island: own the behaviour, not the section
+
+The ownership rules above answer "what must not be split apart". They do NOT answer "how much to pull in", and read alone they push in one direction only: rule 1 says that if you are reaching for a selector, write the component that renders that markup instead. Applied without a stopping rule, that argument never terminates, because there is always more surrounding markup a component could render.
+
+Here is the stopping rule. **A component owns the markup its own behaviour reads or writes.** Static markup that no handler touches, no state change re-renders, and no template hole depends on belongs to the page, not to the island.
+
+This is a byte-cost rule, not a taste one. A page never hydrates, so markup it renders is free in the browser. Markup an island renders is not: the island's module is fetched, `@webjsdev/core` comes with it, and on upgrade the component re-renders, replacing the server's DOM for that subtree. Moving static markup across that boundary converts free HTML into shipped JavaScript that reproduces markup the server already sent.
+
+```ts
+// TOO BIG. One button's worth of behaviour, a whole page's worth of markup.
+class ProductPage extends WebComponent({ product: prop<Product>(Object) }) {
+  render() {
+    return html`
+      <h1>${this.product.name}</h1>
+      <p>${this.product.description}</p>
+      <spec-table .rows=${this.product.specs}></spec-table>
+      <button @click=${() => addToCart(this.product.id)}>Add to cart</button>
+      <review-list .reviews=${this.product.reviews}></review-list>
+    `;
+  }
+}
+```
+
+```ts
+// RIGHT SIZE. The page renders the static markup. The island is the button.
+class AddToCart extends WebComponent({ productId: String }) {
+  render() {
+    return html`<button @click=${() => addToCart(this.productId)}>Add to cart</button>`;
+  }
+}
+```
+
+The first version ships three modules instead of one: itself, plus `<spec-table>` and `<review-list>`, which were display-only and elidable until a shipping component rendered them (see "Display-only elision" below). The second ships one small module, and the heading, description, spec table, and reviews stay HTML the browser never pays for.
+
+**How to tell, on a component you are about to write.** Walk its template and ask of each element: does a handler in this class touch it, does a state or property change alter it, or does it sit in a template hole? If the answer is no for all three, that element is a passenger. A template that is mostly passengers is an island that wants splitting, and the split is usually "hoist the static markup back to the page and keep the interactive fragment".
+
+**The exception, and it is a real one.** Markup that is static *today* but is the thing a near-term behaviour will read is fine to keep, because the alternative is a component that reaches outward for it later, which is what rule 1 forbids. Judge the behaviour you are building, not one you are speculating about. When those genuinely collide, ownership wins over bytes: a coherent component that ships a little extra markup beats a split feature that a selector holds together.
+
 ## Reactive properties: the base-class factory
 
 Reactive properties are declared by passing their shape into `WebComponent({ ... })`. The types flow automatically to `this.<prop>`, so there is NO `static properties` block and NO `declare` line (a `static properties` block throws at runtime, caught by `no-static-properties`).
@@ -147,9 +185,9 @@ For an array-typed prop pass `Array`, not `Object` (`array-prop-uses-array-type`
 
 **A `reflect: true` property holding a FUNCTION drops its attribute instead of writing one, and so does one holding an array that carries a function, unless the prop is `Object` or `Array` typed.** A function has no HTML attribute representation, and the serializations it would otherwise get are both useless and dangerous. `String(fn)` is the function's SOURCE, so a reflected `'use server'` action would ship its whole body, closure secrets included, to every visitor, and `JSON.stringify(fn)` is `undefined`, which lands in the attribute as the literal four-character string. So the reflection path treats a function like `null`, removes the attribute, and warns naming the property, the tag, and the attribute. This holds on both sides, since SSR and the client-side setter run the same path, and it holds for every property name (the leak was never specific to one called `action`). Two exceptions. A property with a custom `converter.toAttribute` runs that converter first and is left alone, because an author who writes one has taken responsibility for serializing whatever they are handed. And an `Object` or `Array` typed property CARRYING a function keeps its data, because `JSON.stringify` drops the function to `null` and omits the key, so `[1, 2, fn]` reflects as `[1,2,null]` with no source and nothing else lost. If you need a function on a component, use a plain property or a signal and do not mark it `reflect`.
 
-**An `Object` or `Array` typed reflected property whose value `JSON.stringify` cannot serialize AT ALL drops its attribute the same way, and warns.** Three shapes do this: a cycle (an object or array that reaches itself, which arrives from a parent/child graph, a linked node, a memo table, or anything a library hands back with a back-reference), a `BigInt` anywhere inside the value, and an author `toJSON()` that throws. The line to keep straight is that a value which serializes WITH A GAP in it keeps its data (the carried-function case above), while one that does not serialize at all has no string to put in the attribute and so has no attribute representation, exactly like a function. The property itself is untouched and still holds the value; only the attribute goes. Before this guard the throw escaped reflection entirely, which meant a client upgrade threw before the component's first render, and an SSR render was swallowed by per-component error isolation, which shows an error box in dev and renders the component EMPTY on a page that still returned 200 in production. To reflect something about a graph-shaped value, reflect a derived scalar (an id, a count) and keep the graph on a non-reflected property. On the read side an attribute that is PRESENT but not parseable JSON reads back as `null` rather than as the raw string, on both the SSR and the client reader. An ABSENT attribute is a different case: neither reader sees it, so the property keeps its constructor value. The two readers also see the same attribute SET, not merely the same fallback: a `state: true` prop, a camelCase attribute name, and an attribute matching no declared property are all ignored by both, and both are handed a value whose HTML character references are already decoded.
+**An `Object` or `Array` typed reflected property whose value `JSON.stringify` cannot serialize AT ALL drops its attribute the same way, and warns.** Three shapes do this: a cycle (an object or array that reaches itself, which arrives from a parent/child graph, a linked node, a memo table, or anything a library hands back with a back-reference), a `BigInt` anywhere inside the value, and an author `toJSON()` that throws. The line to keep straight is that a value which serializes WITH A GAP in it keeps its data (the carried-function case above), while one that does not serialize at all has no string to put in the attribute and so has no attribute representation, exactly like a function. The property itself is untouched and still holds the value; only the attribute goes. Before this guard the throw escaped reflection entirely, which meant a client upgrade threw before the component's first render, and an SSR render was swallowed by per-component error isolation, which shows an error box in dev and renders the component EMPTY on a page that still returned 200 in production. To reflect something about a graph-shaped value, reflect a derived scalar (an id, a count) and keep the graph on a non-reflected property. On the read side an attribute that is PRESENT but not parseable JSON reads back as `null` rather than as the raw string, on both the SSR and the client reader. An ABSENT attribute is a different case: neither reader sees it, so the property keeps its constructor value. The two readers also see the same attribute SET, not merely the same fallback: a `state: true` prop and an attribute matching no declared property are ignored by both, and a camelCase attribute name reaches its prop on both through the lowercased alias, and both are handed a value whose HTML character references are already decoded.
 
-**Writing attributes in markup.** Names are case-insensitive and the browser lowercases them while parsing, so write kebab-case (`user-name`); a camelCase attribute (`userName="…"`) reaches no property on either side. A prop that renames its attribute answers to the new name ONLY, so `open: prop(Boolean, { attribute: 'is-open' })` is written `<my-el is-open>` and `<my-el open>` reaches nothing. Character references are decoded before the value is coerced, so `cfg="&#123;&quot;a&quot;:1&#125;"` parses as the object it spells and `label="Tom &amp; Jerry"` is `Tom & Jerry`; the legacy semicolon-less forms decode exactly where a browser decodes them (`&nbsp` at the end of a value is a non-breaking space, `&nbspx` and `&nbsp=x` stay literal), and writing the semicolon avoids the question. A `state: true` prop takes an SSR value only through a `.prop=${value}` binding from the parent template, never from an attribute.
+**Writing attributes in markup.** Names are case-insensitive and the browser lowercases them while parsing, so a camelCase prop answers to BOTH its kebab-case name (`user-name`, the one reflection writes) and its lowercased name (`username`, lit's default), which is what a camelCase attribute in markup (`userName="…"`) arrives as; all three spellings reach `userName` on both sides. Prefer kebab-case. A prop that renames its attribute answers to the new name ONLY, so `open: prop(Boolean, { attribute: 'is-open' })` is written `<my-el is-open>` and `<my-el open>` reaches nothing. Character references are decoded before the value is coerced, so `cfg="&#123;&quot;a&quot;:1&#125;"` parses as the object it spells and `label="Tom &amp; Jerry"` is `Tom & Jerry`; the legacy semicolon-less forms decode exactly where a browser decodes them (`&nbsp` at the end of a value is a non-breaking space, `&nbspx` and `&nbsp=x` stay literal), and writing the semicolon avoids the question. A `state: true` prop takes an SSR value only through a `.prop=${value}` binding from the parent template, never from an attribute.
 
 **Never use a class-field declaration OR initializer** (`count = 0`, `student: Student = {...}`, `todos!: Todo[]`). Under `useDefineForClassFields` even a type-only `todos!: Todo[]` compiles to define an own property after `super()`, which clobbers the prototype's reactive accessor and silently breaks reactivity. Only declare props in the factory and read/write them off `this`. The `reactive-props-no-class-field` rule catches this.
 
@@ -344,6 +382,18 @@ Import from `@webjsdev/core/directives`. Everything a `class`/`style`/conditiona
 | `asyncAppend(iter)` / `asyncReplace(iter)` | Stream from an async iterable, appending each value or replacing with the latest. |
 | `templateContent(el)` | Render the content of a `<template>` element. |
 
+Every directive here is CLIENT behaviour. At SSR the server renders one shot, so
+`guard` always invokes its function, `watch` reads its signal once and inlines
+the value, and `live` is fully transparent, resolving to the value it wraps in
+every hole position (a child, a plain attribute, a `?bool`, a `.prop`). So
+`?open=${live(false)}` omits its attribute exactly as `?open=${false}` does. It
+was previously resolved only in a child hole, which served `open=""` and let
+hydration close the element a moment later (#1443).
+
+## Lazy components: load on first sight
+
+`static lazy = true` defers a component's module until an element with its tag is first visible: scrolled within 200px of the viewport, or shown when a `hidden` tab panel or a closed `<dialog>` around it opens. Reach for it for heavy panes and dialogs a first screen does not show (an editor behind a Code tab, a data browser, a settings dialog). It stays lazy when the component that renders it imports it (`import './code-pane.ts'`): the server keeps that import for SSR, and the browser copy of the importer gets an `observeLazy` registration in its place, with no preload for the lazy subtree (#1524). Only a SIDE-EFFECT import defers; a binding import (`import { CodePane } from ...`) stays eager, and one anywhere in the app makes that component eager everywhere. Until the module arrives the element is not upgraded, so a parent calling into it uses optional calls (`this.#pane.value?.save?.()`). The loader scans light DOM only, so do not render a lazy tag inside a shadow root. Browser tests (`webjs test --browser`) get every import as written, so a test that imports a lazy component has it defined at once. A component opened by a window event rather than by becoming visible (a panel that renders nothing until an `open` event) does not fit `static lazy`: dynamically `import()` its module in the code that dispatches the event, then dispatch.
+
 ## Display-only elision
 
 A component that does no client-side work renders the same SSR'd HTML with or without its JS, so WebJs strips its import from the served source (and any vendor reachable only through it). This is automatic and conservative. A component stays elidable while it has NONE of:
@@ -352,10 +402,12 @@ A component that does no client-side work renders the same SSR'd HTML with or wi
 - a factory-declared reactive property that is not `{ state: true }`
 - an overridden lifecycle hook (including `renderFallback` / `renderError`)
 - an imported `signal` / `computed` / `watch` / `Task` / `ref` / streaming directive, or `addController` / `requestUpdate`
-- code that runs at module load (a top-level call, non-data `new`, dynamic `import(...)`, top-level `await`); only declarations and `X.register(...)` are allowed
+- code that runs at module load (a top-level call, non-data `new`, dynamic `import(...)`, top-level `await`); only declarations and `X.register(...)` are allowed. A call inside a declaration does not run at load, so it is not a blocker: an arrow's expression body (`export const usd = (m) => Math.round(m) / MICROS`) and a function parameter default (`function relativeTime(when, now = Date.now())`) are both fine. TypeScript types are erased before the analyser reads a module, so an annotation can never be a blocker however call-shaped it looks (`readonly (readonly [number, number, number])[]` is fine)
 - the dynamic slot READ surface (`slotchange`, `assignedNodes` / `assignedElements` / `assignedSlot`); merely RENDERING a `<slot>` does not ship (the SSR output carries the placed children, so a display-only slotted wrapper is byte-identical without its JS; native-write liveness is consumer-driven and the consumer's tag reference forces the ship)
 - being rendered by a component that itself ships
 
+That last blocker is the one to DESIGN around rather than merely inspect, because it is the only one that is not about the component you are looking at. Elision propagates downward from whatever ships, so the size of your islands decides how much of the tree stays elidable. Ten display-only components rendered by a page are ten modules the browser never fetches. The same ten rendered by one oversized interactive wrapper all ship, and nothing about any of them changed. This is why "Sizing an island" above is a byte-cost rule and not a tidiness preference.
+
 A bare `async render()` (no other signal, light DOM) is elided too: the SSR'd data is the complete first paint. Force shipping with `static interactive = true` when interactivity is invisible to static analysis. `static shadow = true` always ships (Declarative Shadow DOM re-attaches only during parsing). Turn elision off app-wide with `{ "webjs": { "elide": false } }` or `WEBJS_ELIDE=0`.
 
 ### What `static interactive = true` does and does not rescue
@@ -414,4 +466,4 @@ A `WebComponent` inherits `HTMLElement` (browser) or an `ElementShim` (SSR) plus
 - HTMLElement / Element: `title`, `id`, `slot`, `role`, `hidden`, `dir`, `lang`, `translate`, `draggable`, `tabIndex`, `className`, `dataset`, `remove`, `closest`, `matches`, `focus`, `blur`, `click`, `append` / `prepend`, `before` / `after`. Rename (`postTitle`, `removeItem`, `handleClick`).
 - WebComponent base: `render`, `update`, `requestUpdate`, `updated` / `firstUpdated`, `willUpdate` / `shouldUpdate`, `connectedCallback`, `renderError` / `renderFallback`, `addController` / `removeController`, `updateComplete` (#1021: there is no WebJs slot API to override; slots are native). Only override one deliberately, with its exact signature; never repurpose the name for app logic.
 
-Framework-private fields are underscore-prefixed (`_renderRoot`, `_connected`, `_changedProperties`, `_updatePromise`, `_isUpdating`); never declare a prop or field that matches one. Safe, non-inherited names: `label`, `open`, `count`, `value`, `name`, `items`, `todos`, `active`, `variant`, `size`, `checked`, `selected`, `heading`, `message`, `status`. When in doubt, grep the base surface in `node_modules/@webjsdev/core/src/component.js`.
+Framework-private fields are underscore-prefixed (`_renderRoot`, `_connected`, `_changedProperties`, `_updatePromise`, `_isUpdating`); never declare a prop or field that matches one. Safe, non-inherited names: `label`, `open`, `count`, `value`, `name`, `items`, `todos`, `active`, `variant`, `size`, `checked`, `selected`, `heading`, `message`, `status`. When in doubt, grep the base surface in `node_modules/@webjsdev/core/src/component.js` and its sibling `component/` directory, where the class body actually lives.

package/resources/references/data-and-actions.md

@@ -139,6 +139,8 @@ The renderer omits the `action` attribute so the form posts to the page's own ur
 
 **A form-bound action always receives the `FormData`**, which is where it differs from the same function called over RPC (rich arguments) or server-to-server. `validate` is the typing seam: it takes the `FormData` and its transform-return becomes the action's typed input.
 
+A failing form action does not need to echo the submission back. On the 422 re-render `actionData.values` already carries every submitted text field (any `values` the action returns are layered on top), and with JavaScript on the client router restores what was typed into every control the re-render did not explicitly set (#1581). Return `values` only to normalize or blank a field; see `routing-and-pages.md` for the page side.
+
 Everything the action declares applies here too, or an action would be protected over RPC and open over a form:
 
 - `validate` runs on the submitted `FormData`.
@@ -206,7 +208,7 @@ export async function updateUser(id: number, patch: Partial<User>) { /* ... */ }
 
 ### Cancellation with `actionSignal()`
 
-Inside an action, `actionSignal()` from `@webjsdev/server` returns the request's `AbortSignal`. It fires when the client disconnects OR when a newer client render supersedes this one (the RPC stub aborts the previous in-flight fetch). Thread it into the work you start, and re-check it after an await to map an abort to a cancelled envelope:
+Inside an action, `actionSignal()` from `@webjsdev/server` returns the request's `AbortSignal`. It fires when the client disconnects OR when a newer client render supersedes this one (the RPC stub aborts the previous in-flight fetch). Only an action called in the synchronous part of a component's own `render()` is tied to that render. One called from `connectedCallback`, an event handler, `firstUpdated()` / `updated()`, or a `Task` is never cancelled by a re-render, including a child element's `connectedCallback` that runs while its parent's template is being committed, so a child can start its first fetch there without the parent's next render cancelling it. Thread it into the work you start, and re-check it after an await to map an abort to a cancelled envelope:
 
 ```ts
 'use server';

package/resources/references/module-structure.md

@@ -0,0 +1,229 @@
+# Module structure: file size, design principles, and splitting a large module
+
+Read this before splitting a large source file, and before arguing about how
+big a module is allowed to be.
+
+Two things live here. The first is what "well structured" means in this repo,
+which is mostly judgment rather than a number. The second is the mechanical
+procedure for barrelling a large module into a directory, which is NOT judgment:
+it has a small number of failure modes that are silent, and every one of them
+has bitten this codebase already.
+
+---
+
+## Design principles: judgment, not a checker
+
+SOLID, DRY, and KISS apply here the way they apply anywhere. They are prose
+guidance, followed by judgment, and deliberately NOT enforced by `webjs check`.
+That split is the same one the rest of the project uses: `webjs check` carries
+correctness rules only (code that is wrong to ship), and anything a sensible
+project could reasonably do differently stays a convention.
+
+What they mean in practice, in a buildless framework whose source IS what runs:
+
+- **Single responsibility** is about what a module OWNS, not how long it is. A
+  module owns one concern when you can state that concern in a sentence without
+  the word "and". `router-client/prefetch.js` owns speculative fetching. It is
+  584 lines, and it is one responsibility.
+- **DRY applies to knowledge, not to text.** Two identical lines that would
+  change for different reasons are not duplication. A constant that appears in
+  three places IS, which is why this repo has drift guards that read one copy
+  and assert it against another (see the guard section below).
+- **KISS beats cleverness in a framework more than in an app.** The source is
+  the documentation surface for the AI agents that use WebJs, and it ships
+  unbundled to be read. An indirection that saves five lines and costs a reader
+  a jump is a bad trade here.
+- **Dependency direction matters more than dependency inversion.** Modules layer
+  downward: constants at the bottom, then pure helpers, then orchestration.
+  Nothing imports upward. This is not architectural taste, it is what keeps ESM
+  cycles out (see below). Two subsystems are genuinely mutually recursive and
+  cannot layer, the client router (a navigation fetches, the fetch swaps, the
+  swap upgrades, an upgraded element navigates) and light-DOM slots (projecting
+  installs the interceptors, an intercepted mutation re-projects). Those two are
+  named in `test/architecture/import-cycles.test.mjs`, which fails on any THIRD
+  cycle, so the rule holds everywhere it can.
+
+---
+
+## File size: target 800, ceiling around 1000
+
+**A source module targets 800 lines and should stay around 1000 at the most.**
+The ceiling is approximate on purpose. A module at 1040 is fine; one at 1900
+needs either a split or a named exemption (below), and the question to ask at
+that size is which responsibility it has picked up rather than how many lines
+it has. A barrel is exempt entirely, because its length is a function of how
+many names it re-exports.
+
+**Where this number comes from.** It was set by measuring the frameworks this
+project takes its cues from, not by picking a round figure:
+
+| Module | Lines |
+|---|---|
+| `lit/packages/lit-html/src/lit-html.ts` | 2303 |
+| `lit/packages/reactive-element/src/reactive-element.ts` | 1754 |
+| `vite/packages/vite/src/node/optimizer/index.ts` | 1487 |
+| `vite/packages/vite/src/node/server/index.ts` | 1447 |
+
+Every one of them draws its seams by responsibility and lets the orchestration
+entry stay large. None of them enforces a line count.
+
+**A much smaller cap is a bad trade, and this repo has the measurement.**
+Splitting ten modules into about ninety produced three bindings that needed
+accessors because ESM forbids assigning an imported binding, one dropped import
+that threw only inside a deferred callback, one symbol identity swap that
+silently broke slot forwarding, and three drift guards that broke or would have
+passed vacuously. Four of those six were invisible to `npm test`. Every module
+boundary is a place where those failures can happen, so boundaries are worth
+adding for cohesion and worth nothing when added to hit a number.
+
+There is also a runtime cost. In dev the browser fetches core source files
+individually rather than the bundle, so N modules is N requests at one more
+level of import-graph depth.
+
+**The ceiling is measured with a RAW line count** (the number `wc -l` prints,
+the number you see when you open the file), because that is how #1365 specified
+it and because a metric a reader cannot reproduce by looking at the file invites
+argument about the metric instead of the module. The tension with dense
+documentation is real: this repo's comment style can put a well-factored module
+at twice its code size, and a raw ceiling must never become a reason to delete
+explanation. The answer to that tension is the exemption list, not a different
+metric.
+
+**There is deliberately NO CI guard for this.** A line-count gate is a proxy
+metric that fights cohesion: it reds forever on a generated data table like
+`html-entities.js`, and it has to carry an exemption list that rots. So the
+ceiling is a REVIEW-TIME check, not a test. Measure it when you split something:
+
+```sh
+find <the tree you produced> -name '*.js' -exec wc -l {} + | awk '$1 > 1000 && $2 != "total"'
+```
+
+**A module that genuinely cannot or should not go under the ceiling gets a
+NAMED exemption**, argued in the PR that produces it, with its measured size and
+its reason. The three exemptions the #1365 split carries show what a valid
+reason looks like:
+
+- **lit parity** (`component/lifecycle.js`): the file tracks lit's
+  `reactive-element.ts`, which lit keeps WHOLE at 1754 lines, and the project's
+  standing decision is to keep lit-derived code close to lit rather than
+  restructure it.
+- **mutual recursion** (`render-client/parts.js`): the apply and instance group
+  calls back into itself, so a real split creates the import cycle the D4 rule
+  forbids, and the escape (a runtime dispatch registry) is a worse trade.
+- **a single closure over shared request state** (`dev/handler.js`): splitting
+  means threading that state through a context object, a high-risk rewrite of
+  every app's boot path for zero behaviour gain.
+
+Note what a valid reason is NOT: "it is mostly comments." If a module is over
+the ceiling only because it is well documented, that is a signal the ceiling is
+being measured too literally, not grounds for an exemption. Say why the CODE
+cannot be split, or split it.
+
+---
+
+## Splitting a module into a barrel plus a directory
+
+The naming rule, settled once for the whole framework: **the original file keeps
+its path and becomes the barrel, and its parts land in a sibling directory named
+after it.** So `packages/core/src/slot.js` stays, and its parts go in
+`packages/core/src/slot/`. Do NOT rename the barrel to match a public export
+subpath. The `package.json` `exports` map, the hand-written `.d.ts` overlays and
+their two guard tests, the docs pages that print importmap examples, and every
+relative test import all key off the current path.
+
+### The rule that matters most
+
+**A split is a MOVE, not a rewrite.** Retyping a function while relocating it is
+how a refactor with a green export surface ships behaviour changes. Move the
+lines verbatim. The only edits a move should produce are the `export ` keyword
+where a declaration now crosses a module boundary, and the generated import
+lines.
+
+### Where mutable module state goes
+
+A module-scope `let` goes in the module that WRITES it, not the module that
+looks like its topical home. ESM import bindings are read-only, so a module
+cannot assign a binding it imported.
+
+When two modules genuinely write the same binding, the owner exposes a
+one-statement accessor and the other module calls it:
+
+```js
+// scroll.js owns the counter.
+export let restoreGeneration = 0;
+export function bumpRestoreGeneration() { restoreGeneration += 1; }
+
+// navigator.js reads the live binding and calls the accessor to write.
+import { restoreGeneration, bumpRestoreGeneration } from './scroll.js';
+```
+
+Keep importing the binding itself wherever it is READ. Dropping it from the
+import list while a read site survives leaves a free variable, which throws only
+when that line executes. In the client router that meant a Back-button scroll
+restore silently landing at offset 0, with every node test still green.
+
+### Cycles and TDZ
+
+Layer the modules and never import upward. Node tolerates an import cycle, but
+reading a `const` or `class` binding during the cycle's evaluation phase throws
+a TDZ `ReferenceError` at module load, and in a minified browser bundle that is
+a blank page rather than a test failure.
+
+Where a back edge is unavoidable, resolve it by calling a function at call time
+rather than reading a binding at module scope.
+
+### Symbol identity
+
+`Symbol('x')` mints a unique value. `Symbol.for('x')` looks one up in the global
+registry by string. They are never interchangeable, and substituting one for the
+other produces a value that no existing object carries, so every lookup quietly
+returns `undefined`. Import the symbol from the module that created it.
+
+### Drift guards read source files by path
+
+This repo has guard tests that `readFileSync` a source file and grep it for a
+constant, to pin two copies of a value against each other. Barrelling a file
+breaks every one of them, and breaks them in two different ways:
+
+- an `assert.match` fails on its own precondition, which is loud and fine;
+- an `assert.doesNotMatch` starts passing **vacuously**, which is silent and is
+  the reason this is written down.
+
+After any split, grep the test tree for reads of the file you just barrelled and
+point each guard at the barrel PLUS every module beneath it.
+
+### Verification, in order
+
+```sh
+# 1. Export surface is identical, in BOTH directions. `added` must be empty too:
+#    a behaviour-preserving split adds no public surface.
+node --input-type=module -e "
+  const before = await import('/tmp/before.js');
+  const after  = await import('./packages/core/src/<file>.js');
+  const A = Object.keys(before).sort(), B = Object.keys(after).sort();
+  console.log(JSON.stringify({
+    missing: A.filter((k) => !B.includes(k)),
+    added:   B.filter((k) => !A.includes(k)),
+  }));
+"
+
+# 2. Every code line survived. Normalize away comments and the `export ` prefix,
+#    then diff. Anything left is a line the split CHANGED, and each one needs a
+#    reason in the commit message.
+
+# 3. The module loads at all (catches a TDZ throw introduced by a cycle).
+node --input-type=module -e "await import('./packages/core/index-browser.js')"
+node --input-type=module -e "await import('./packages/core/index.js')"
+
+# 4. Rebuild dist BEFORE any e2e or Bun run, which resolve the built bundle and
+#    would otherwise test the pre-split code and pass vacuously.
+node scripts/build-framework-dist.js
+
+# 5. The browser suite is MANDATORY for a renderer, router, component, or slot
+#    split. Those defects are post-hydration: the export surface is unchanged,
+#    the SSR bytes are unchanged, and node tests stay green.
+npm test && npm run test:browser
+```
+
+Step 5 is not optional and not a formality. Of the two silent defects this
+codebase has hit from splitting, both were caught by the browser suite alone.

package/resources/references/muscle-memory-gotchas.md

@@ -3,7 +3,7 @@
 ## What This Covers
 
 - The Next.js patterns that LOOK right in WebJs but break, because WebJs borrows Next's file-based routing shape but not its execution model (no RSC, no `'use client'` split): `redirect()` in a route handler, `fetch()` in a page, `<Link>`, `NEXT_PUBLIC_`, `await params`.
-- The Lit patterns that break WebJs SSR or reactivity, because WebJs is HTML-first (real HTML first paint, JS opt-in per behaviour) not JS-first: `static properties` / the `@property()` decorator, class-field initializers, browser globals in `render()`, fetching in `connectedCallback`, interpolation into `<style>`, reading `assignedNodes()` in `firstUpdated` of a light-DOM component.
+- The Lit patterns that break WebJs SSR, reactivity, or event handling, because WebJs is HTML-first (real HTML first paint, JS opt-in per behaviour) not JS-first: `static properties` / the `@property()` decorator, class-field initializers, browser globals in `render()`, fetching in `connectedCallback`, passing a method straight to an `@event` binding, interpolation into `<style>`, reading `assignedNodes()` in `firstUpdated` of a light-DOM component.
 - The WebJs-shaped fix for each, with short code.
 
 Read this when a pattern feels familiar from Next.js or Lit but you are not sure it transfers. For the component runtime see `components.md`; for the routing surface see `routing-and-pages.md`. The one difference underneath everything: pages and layouts render server-only and never hydrate, and the one client boundary is a `WebComponent` custom element.
@@ -174,7 +174,9 @@ html`<form action=${submitFeedback}><input name="email"></form>`;
 html`<form method="post"><input name="email"></form>`;
 ```
 
-A hole that resolves to `null` is NOT the same as omitting the attribute. `method=${null}` renders `method=""`, which cannot submit and is refused; `?method=${false}` emits nothing at all, so WebJs supplies `method="post"` and the form works. Both leave no attribute in the DOM, which is exactly why the check reads your template rather than the rendered element.
+A plain attribute hole that resolves to `null` or `undefined` omits the attribute on both renderers (#1573), so `method=${null}` and `?method=${false}` both emit nothing and WebJs supplies `method="post"`. An EMPTY string is different: `method=${''}` renders `method=""`, which cannot submit and is refused.
+
+A boolean in a plain hole on an HTML boolean attribute renders like `?attr` (core 0.7.64+, #1579): `<option selected=${i === 0}>` and `<input type="radio" checked=${v.attending !== 'no'}>` mark only the true one. On an older core the server served `selected="false"` / `checked="false"`, which HTML reads as PRESENT, so the LAST option or radio won on first paint. `?selected=${...}` / `?checked=${...}` is correct on every version.
 
 A string stays a string: `action="/search"` and `action=${'/search'}` are unchanged, which is what a search form (`<form method="get" action="/search">`) and a `route.ts` endpoint both want. Other attributes keep their existing stringify behaviour; only a FUNCTION under `action` / `formaction` is claimed.
 
@@ -202,18 +204,22 @@ Export `GET` / `POST` / etc. as named async functions `(request, { params }) =>
 
 ### `middleware.ts` is per-segment and chainable, not one matcher config
 
-The file stays `middleware.ts`, NOT Next 16's renamed `proxy.ts`. WebJs middleware is in-process, chainable, and per-segment (the Remix / Koa model). There is no `export const config = { matcher }` and no single-file restriction. The default export is `async (req, next) => Response`: return a Response to short-circuit, or call `next()` and post-process. Colocate `app/admin/middleware.ts` next to the admin routes and it runs for that subtree only. An optional root `middleware.ts` runs on every request, outermost to innermost.
+The file stays `middleware.ts`, NOT Next 16's renamed `proxy.ts`. WebJs middleware is in-process, chainable, and per-segment (the Remix / Koa model). There is no `export const config = { matcher }` and no single-file restriction. The default export is `async (req, next) => Response`: return a Response to short-circuit, or call `next()` and post-process. Colocate `app/admin/middleware.ts` next to the admin routes and it runs for that subtree only. An optional root `middleware.ts` runs on every app request, outermost to innermost. Some requests are answered before it and never reach it, and the RULE is what to remember, not the list: anything the listener shell or the framework's pre-analysis stage answers bypasses root middleware, and everything routed with the app reaches it. That covers WebSocket upgrades bound for a `route.ts` exporting `WS`, the dev SSE stream at `/__webjs/events`, and the framework's own `/__webjs/*` runtime assets and probes; in DEV only it also covers `/public/*` plus the `/sw.js` / `/offline.html` root remaps and `/favicon.ico`, so a stylesheet is never queued behind the dev startup analysis. In production those static files go through root middleware normally. **`webjs.redirects` and `webjs.trailingSlash` are the case intuition gets wrong**: you configure them, but the framework resolves them ahead of middleware, so a 308 from a redirect rule is answered without root middleware running (redirect in the middleware instead when it has to observe those requests). Server actions go the other way: they are routed with the app, so middleware DOES run for an action call, which is what lets you gate actions with auth or rate limiting.
 
 ### No `<Link>`, no `next/navigation`, no `next/*` libraries
 
-Navigation is automatic. The client router auto-enables when `@webjsdev/core` loads (any page with a component), so a plain `<a href>` gets soft navigation for free. There is no `<Link>` to import and no `useRouter`. For programmatic navigation import `navigate()` / `revalidate()` from `@webjsdev/core`. There is no `next/image`, `next/font`, `next/script`, or `next/dynamic`. WebJs is no-build: use a plain `<img>`, a `<link>` / `@font-face`, a component's `static lazy = true` for viewport lazy-loading, and a dynamic `import()` where code should load lazily.
+Navigation is automatic. The client router auto-enables when `@webjsdev/core` loads (any page with a component), so a plain `<a href>` gets soft navigation for free. There is no `<Link>` to import and no `useRouter`. For programmatic navigation import `navigate()` / `revalidate()` from `@webjsdev/core`. There is no `next/image`, `next/font`, `next/script`, or `next/dynamic`. WebJs is no-build: use a plain `<img>`, a `<link>` / `@font-face`, a component's `static lazy = true` to load it when it is first visible (scrolled near, or its hidden tab panel or dialog opened, and it stays lazy when another component imports it), and a dynamic `import()` where code should load lazily.
 
 ### No `<ScrollRestoration>`, and no scroll restore of your own
 
-Remix ships a `<ScrollRestoration />` component, Next has a `scrollRestoration` flag and a pile of community `useEffect` + `scrollTo` recipes, and every one of them is a thing to NOT port. WebJs restores scroll on Back/Forward automatically: the router sets `history.scrollRestoration = 'manual'` on boot and is the sole authority on scroll for the whole navigation. There is no component to render and no option to enable. An app-level `popstate` listener that calls `scrollTo`, a remembered offset in `sessionStorage`, or a `scrollIntoView` on a saved element all race the router and win sometimes, which is worse than losing consistently.
+Remix ships a `<ScrollRestoration />` component, Next has a `scrollRestoration` flag and a pile of community `useEffect` + `scrollTo` recipes, and every one of them is a thing to NOT port. WebJs restores scroll on Back/Forward automatically, and the BROWSER is what does it: the router reserves the page's recorded height across the swap so the browser's own per-entry replay lands correctly, and writes no scroll itself. There is no component to render and no option to enable. An app-level `popstate` listener that calls `scrollTo`, a remembered offset in `sessionStorage`, or a `scrollIntoView` on a saved element all race the router and win sometimes, which is worse than losing consistently.
+
+**Do not set `history.scrollRestoration = 'manual'` either**, which is the one line most of those recipes start with. The browser only records a per-entry scroll offset under the default `auto`, and WebKit composes the iOS edge back-swipe gesture preview from that recording, so `manual` makes every scrolled page preview BLANK for the whole gesture (#1428). The router itself used to set it, inherited from Turbo Drive, and had the same bug. It no longer does.
 
 This includes the case that most tempts a hand-rolled fix: Back landing BELOW where the reader left, on a page whose components size themselves after they render. The router already handles it, by suppressing the browser's scroll anchoring across the restore so late growth above the viewport is not added to the offset it just replayed (see `client-router-and-streaming.md`). If a restore still lands wrong, report it rather than patching around it in app code.
 
+**One scroll reflex DOES port, and only one.** Next's `<Link scroll={false}>` has a WebJs spelling: `data-preserve-scroll` on the link, or on any element wrapping a group of them, and `navigate(url, { scroll: false })` programmatically. It suppresses the forward-navigation scroll-to-top, which is a write the ROUTER makes, and that is why it exists while none of the restore recipes above do: the restore is the browser's and the router is not a writer on it. Everything else in this section stands unchanged, including the rule not to hand-roll a restore. The attribute keeps the reader's CURRENT offset on a forward nav; it does not bring back the offset they once had on the destination, which is what a hand-rolled `sessionStorage` restore is usually reaching for.
+
 ### Server-only code: the `.server.ts` boundary, not a `server-only` package
 
 Next poisons a client-imported module with the `server-only` package. WebJs uses the file extension: `*.server.ts` is the path-level boundary (the file router refuses to serve the source). A `'use server'` file's exports are RPC-callable; a `.server.ts` file WITHOUT `'use server'` is a server-only utility whose browser import throws at load. Reach a no-`'use server'` utility through a `'use server'` action, `route.ts`, or `middleware`, never by direct import into a shipping page or component.
@@ -286,6 +292,26 @@ class StudentCard extends WebComponent({ student: prop<Student>(Object) }) {
 
 The `@property()` decorator is banned by the erasable-TS invariant (decorators are non-erasable, they would force a build step). A `static properties = { ... }` block THROWS at runtime (`no-static-properties`). The single replacement for both is the declare-free base-class factory `WebComponent({ ... })`, with the `prop()` helper carrying options.
 
+### Passing a method straight to an `@event` binding
+
+Lit invokes an `@event` listener with `this` set to the host element, so `@click=${this.handleClick}` is correct there. WebJs stores the handler verbatim and dispatches it through an internal part object (`part.handler?.(ev)` in `core/src/render-client/parts.js`), so `this` is THAT object, not your component. It does not fail loudly. A read such as `this.todos` returns `undefined`, and a write such as `this.count = 1` silently lands on the framework's internal object. The `TypeError` arrives later, when you dereference the `undefined` you read back, so the stack points away from the real cause. Nothing catches it statically either: `webjs check` and `tsc` both pass and the component SSRs correctly.
+
+Wrap the call at the binding site, which is the conventional spelling, or declare the handler as an arrow class field, which carries its own `this`.
+
+```ts
+// BROKEN: `this` is undefined when the event fires.
+html`<form @submit=${this.handleSubmit}>`
+
+// Wrap it at the binding site:
+html`<form @submit=${(e: SubmitEvent) => this.handleSubmit(e)}>`
+
+// Or pre-bind by declaring the handler as an arrow field:
+_onSubmit = (e: SubmitEvent) => { /* ... */ };
+html`<form @submit=${this._onSubmit}>`
+```
+
+An arrow class field is a class-field initializer, but it is NOT a reactive property, so the reactive-property class-field ban does not apply to it and `reactive-props-no-class-field` does not flag it.
+
 ### Expecting shadow DOM and reaching for scoped CSS
 
 Lit defaults to shadow DOM, so `static styles = css` scopes automatically. WebJs defaults to light DOM. A `static styles` block without `static shadow = true` does nothing useful and any inline `<style>` with bare class names leaks globally. The webjs-shaped fix is Tailwind utilities, which apply directly in light DOM. Reach for `static shadow = true` plus `static styles` only when scoped CSS genuinely belongs in a shadow root, or prefix every selector with the tag name if authoring vanilla light-DOM CSS.

package/resources/references/optimistic-ui.md

@@ -85,7 +85,7 @@ TodoList.register('todo-list');
 
 ### Author the optimistic mutation as a degrade-first form
 
-Wrap the mutation in a REAL `<form>` bound to the action, then intercept it for the optimistic path. One form serves both: with JS off the browser submits and the server dispatches to that action (the no-JS write path, see `routing-and-pages.md`), and with JS on `@submit` calls `e.preventDefault()` and runs the optimistic path. That is the progressive-enhancement contract, not a fetch-only handler.
+Wrap the mutation in a REAL `<form>` bound to the action, then intercept it for the optimistic path. One form serves both: with JS off the browser submits and the server dispatches to that action (the no-JS write path, see `routing-and-pages.md`), and with JS on `@submit` calls `e.preventDefault()` and runs the optimistic path. That is the progressive-enhancement contract, not a fetch-only handler. Note the arrow wrapper on the listener: WebJs does not bind an `@event` handler to your component, so passing the method directly would leave `this` pointing at a framework-internal object (see `muscle-memory-gotchas.md`).
 
 The SAME imported function is the form binding and the optimistic path's callee, which is what makes a degrade-first form cheap to write: there is no second wiring to keep in step.
 
@@ -94,7 +94,7 @@ import { createTodo } from '#modules/todo/actions/create-todo.server.ts';
 
 render() {
   return html`
-    <form action=${createTodo} @submit=${this.handleSubmit}>
+    <form action=${createTodo} @submit=${(e: SubmitEvent) => this.handleSubmit(e)}>
       <input name="title" required>
       <button>Add</button>
     </form>
@@ -130,19 +130,31 @@ The component reads that seeded prop as its `optimistic()` `source`, so `source:
 For a boolean toggle where the value itself is the mutation (like, follow, pin), `optimistic(signal, value, action)` is a thin wrapper over the signal primitive.
 
 ```ts
-import { signal, optimistic } from '@webjsdev/core';
+import { WebComponent, prop, signal, optimistic, html } from '@webjsdev/core';
 import { likePost } from '#modules/posts/actions/like-post.server.ts';
 
-const liked = signal(false);
-// in an @click handler:
-const result = await optimistic(liked, true, () => likePost(postId));
-// `liked` flips to true instantly. If likePost THROWS or returns
-// { success: false }, `liked` rolls back to its prior value: the throw
-// re-throws, and the { success: false } result is returned so you can
-// read its error / fieldErrors. On success the optimistic value stays;
-// reconcile to the authoritative value from `result` if you need it.
+class LikeButton extends WebComponent({ postId: prop(String) }) {
+  // INSTANCE scope: one signal per element. A module-scope `signal()` is SHARED
+  // across every instance (invariant 5), so a feed of these would all flip
+  // together on one click. Scope per-item state to the instance.
+  private liked = signal(false);
+
+  private async toggle() {
+    const next = !this.liked.get();
+    // Returns the action's ActionResult, so a { success: false } is readable
+    // by the caller. The rollback has already happened by then.
+    return optimistic(this.liked, next, () => likePost(this.postId));
+  }
+
+  render() {
+    return html`<button @click=${() => this.toggle()}>${this.liked.get() ? 'Liked' : 'Like'}</button>`;
+  }
+}
+LikeButton.register('like-button');
 ```
 
+Reserve MODULE scope for state that genuinely is app-wide (a theme, a cart count, a sidebar-open flag), which is the case invariant 5's "module-scope signals share state across components" exists to serve. Per-item state goes on the instance, as above. `liked` is a plain instance field, not a reactive property declared in the factory, so the class-field ban does not reach it and `reactive-props-no-class-field` does not flag it. `gallery/modules/optimistic-ui/components/like-button.ts` is the same shape in shipped code.
+
 It rolls back on a thrown error OR an `ActionResult` `{ success: false }` envelope, and never on success. It is client-only (it mutates a signal), so a component importing it is never elided as a display-only component.
 
 ## When Optimistic UI Is Appropriate