fix(router): address code review findings for query param allowlist

- Add Rust tests for allowed_query across the stack:
  - Protocol: round-trip with non-empty allowed_query
  - Parser: query attribute parsed into allowed_query field
  - Handler: matched/non-matched routes emit query attr in SSR
  - Handler: RouteChainEntry.to_json includes/omits allowedQuery
  - Handler: collect_route_chain carries allowed_query through
- Update DESIGN.md with allowed_query proto field and query attr docs
- Update VitePress docs: route.md, routing.md, ai.md with query attr
- Extract toKebab to module-level helper (was duplicated 3x)
- Add abort guard before content-type redirect in fetchPartial
- Fix fetch mocks in unit tests to include headers for content-type check

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mohamedmansour

DESIGN.md

@@ -188,6 +188,7 @@ pub struct WebUIFragmentRoute {
     pub fragment_id: String,                   // Fragment containing the route body
     pub exact: bool,                           // Require exact path match
     pub children: Vec<WebUIFragmentRoute>,     // Nested child routes
+    pub allowed_query: String,                 // Comma-separated allowlist of query params forwarded as attributes
 }
 ```
 
@@ -217,9 +218,14 @@ Child paths are relative to their parent (no leading `/`). The HTML nesting IS t
       <route path="lessons/:lessonId" component="lesson-page" exact />
     </route>
   </route>
+  <route path="compose" component="compose-page" query="action,to,subject" exact />
 </route>
 ```
 
+The optional `query` attribute declares which URL query parameters are forwarded as HTML attributes
+on the component (deny-by-default). Routes without `query` forward no query params. Route path
+params always take priority over query params to prevent URL-based attribute injection.
+
 **Route matching:** The handler uses an iterative path template matcher (no regex). Segments are
 compared left-to-right: `:param` binds a value, `*splat` captures remaining segments, `?` marks
 optional parameters. Exact matches (most literal segments) take precedence over parameterized ones.

LAZY_HYDRATION.md

@@ -0,0 +1,122 @@
+# Lazy SSR Hydration — Analysis & Implementation Notes
+
+Status: **REVERTED** — needs more work before merging.
+
+## The Idea
+
+Defer ALL binding creation (text, attr, cond, repeat) until the first
+reactive property change triggers `$update()`. Wire events + refs eagerly
+at mount time for immediate interactivity. This matches Preact's approach:
+hydration only attaches event listeners.
+
+## Performance Results (before revert)
+
+| Metric | Eager (p50) | Lazy (p50) | Delta |
+|--------|:---:|:---:|:---:|
+| FCP | 44 ms | 40 ms | -9% |
+| TTI | 29 ms | 18 ms | -38% |
+| INP Primary | 12 ms | 12 ms | 0% |
+| INP Secondary | 13 ms | 12 ms | -8% |
+| JS Heap | 2,138 KB | 2,225 KB | +4% |
+
+Light DOM results were excellent — **FCP 40ms vs Preact 52ms, TTI 18ms
+vs Preact 15ms**.
+
+## Implementation (reverted from commit 894ce5d)
+
+### What worked
+
+1. New field `$ssrPending: { root, tplDom, savedState }` stores deferred
+   hydration context
+2. `$mount()` SSR path: `$applySSRState()` + `$finalize()` (events only)
+3. Saved SSR state snapshot via `getObservableNames` iteration
+4. `$update()` detects `$ssrPending`, restores SSR state, runs `$hydrate`,
+   restores current state, runs full `$updateInstance`
+5. `skipFinalize` parameter on `$hydrate` prevents double event wiring
+6. 133/134 tests passed — all light DOM and most shadow DOM tests worked
+
+### What failed
+
+**sidebar-repeat [shadow DOM] test**: Sets `page = 'favorites'` expecting
+`[data-active]` to move from "Dashboard" to "Favorites".
+
+Root cause: After deferred `$hydrate` + `$updateInstance`, attr bindings
+INSIDE repeat items don't update when a non-collection property changes.
+
+The `$updateInstance(this.$root)` triggers:
+1. Root-level text/attr patches — works
+2. Root-level cond toggles — works
+3. Root-level `syncRepeat` — runs but items array is unchanged
+4. `syncRepeat` reuses all instances, calls `$updateInstance` per item
+5. Item `$updateInstance` patches item attrs — **BUT** the attr binding
+   `?data-active="{{nav.page == page}}"` resolves `page` via `$resolver`
+   which reads `this.page` — this SHOULD work since we restored current
+   state before `$updateInstance`
+
+Suspected deeper issue: The `$resolver` closure captures `this` but may
+resolve against the wrong scope chain during the deferred hydration path.
+Or `syncRepeat`'s unkeyed fast path isn't calling `$updateInstance` at all
+when items haven't changed (it bails on `rep.synced && items.length === 0`
+checks, or the "reuse" path updates scope values but doesn't call update).
+
+## What needs to be solved
+
+1. **Repeat item updates on non-collection property changes**: When `page`
+   changes, all repeat items that reference `page` in their bindings need
+   to be updated. The path index indexes root-level bindings but NOT
+   repeat item bindings. Currently this works because `syncRepeat` always
+   runs and cascades `$updateInstance` — but something in the lazy path
+   breaks this cascade.
+
+2. **State snapshot/restore complexity**: Saving and restoring state via
+   backing fields is fragile. If new observable types are added (e.g.,
+   computed properties), the snapshot may miss them.
+
+3. **Shadow DOM refs in conditionals**: `$wireRefs` during eager `$finalize`
+   may not find refs inside conditional blocks that haven't been hydrated.
+   Re-wiring after deferred hydration fixes this but adds complexity.
+
+## Alternative approaches to explore
+
+### A: Progressive hydration via requestIdleCallback
+Instead of deferring ALL bindings, hydrate during idle time after paint:
+```ts
+this.$finalize(root, meta, resolver); // events eagerly
+requestIdleCallback(() => {
+  this.$root = this.$hydrate(root, meta, tplDom);
+});
+```
+No state snapshot needed — hydration happens with original state.
+Risk: if user interacts before idle callback fires.
+
+### B: Component-level lazy (IntersectionObserver)
+Only hydrate components that are visible in the viewport:
+```ts
+if (this.getBoundingClientRect().top > window.innerHeight) {
+  // Below fold — defer until scrolled into view
+  const observer = new IntersectionObserver(([e]) => {
+    if (e.isIntersecting) {
+      this.$root = this.$hydrate(root, meta, tplDom);
+      observer.disconnect();
+    }
+  });
+  observer.observe(this);
+} else {
+  this.$root = this.$hydrate(root, meta, tplDom);
+}
+```
+For mail app: only ~10 of 50 email rows are visible. Saves ~80% of
+email-row hydration.
+
+### C: Skip repeat item hydration entirely
+For `<for>` loops, don't hydrate individual items at mount time. Only
+create repeat instances when the collection changes. Use `syncRepeat`
+to create fresh instances from scratch (clearing SSR content first).
+This avoids the complex SSR DOM matching for repeat items entirely.
+
+### D: Partial path index that includes repeat item bindings
+Extend `$buildPathIndex` to also index bindings inside repeat items.
+When a non-collection property changes, the path index would directly
+target the affected repeat item bindings without going through
+`syncRepeat`. This is the most correct fix but increases path index
+build cost.

LAZY_HYDRATION_IMPLEMENTATION.md

@@ -0,0 +1,183 @@
+# Lazy Hydration — Implementation Reference
+
+Status: **REVERTED** — kept for future reference.
+
+## Approach
+
+Component-level lazy hydration using a shared `IntersectionObserver`.
+SSR DOM stays intact and visible. Hydration runs when the element
+enters the viewport (with 200px margin). Opt-in via `static lazy = true`
+on any `WebUIElement` subclass.
+
+## How it worked
+
+### Module-level shared observer
+
+One `IntersectionObserver` per document. A `Map<Element, () => void>`
+stores pending hydration callbacks. When an element intersects, its
+callback fires and the element is unobserved.
+
+```ts
+const lazyCallbacks = new Map<Element, () => void>();
+let lazyObserver: IntersectionObserver | null = null;
+
+function getLazyObserver(): IntersectionObserver {
+  if (lazyObserver) return lazyObserver;
+  lazyObserver = new IntersectionObserver(
+    (entries) => {
+      for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry.isIntersecting) {
+          const cb = lazyCallbacks.get(entry.target);
+          if (cb) {
+            lazyCallbacks.delete(entry.target);
+            lazyObserver!.unobserve(entry.target);
+            cb();
+          }
+        }
+      }
+    },
+    { rootMargin: '200px' },
+  );
+  return lazyObserver;
+}
+```
+
+### Class field
+
+```ts
+export class WebUIElement extends HTMLElement {
+  private $lazyPending = false;
+  // ... existing fields
+}
+```
+
+### $mount() modification
+
+Inside the `if (isSSR)` branch, before the normal `$applySSRState()` +
+`$hydrate()` path:
+
+```ts
+if (isSSR) {
+  const ctor = this.constructor as typeof WebUIElement & { lazy?: boolean };
+  if (ctor.lazy && typeof IntersectionObserver !== 'undefined') {
+    this.$lazyPending = true;
+    this.$meta = meta;
+    const observer = getLazyObserver();
+    lazyCallbacks.set(this, () => {
+      this.$lazyPending = false;
+      this.$applySSRState();
+      this.$root = this.$hydrate(root, meta, getTemplateDom(meta));
+      this.$hydrated = true;
+      this.$ready = true;
+    });
+    observer.observe(this);
+    // Don't block TTI — lazy components balance the lifecycle counter immediately
+    hydrationEnd(tag);
+    return;
+  }
+
+  // Normal eager SSR path
+  this.$applySSRState();
+  this.$root = this.$hydrate(root, meta, getTemplateDom(meta));
+}
+```
+
+### disconnectedCallback cleanup
+
+```ts
+disconnectedCallback(): void {
+  if (this.$lazyPending) {
+    lazyCallbacks.delete(this);
+    if (lazyObserver) lazyObserver.unobserve(this);
+    this.$lazyPending = false;
+  }
+}
+```
+
+### Usage
+
+```ts
+class EmailRow extends WebUIElement {
+  static lazy = true;
+  // ...
+}
+```
+
+## What it cost
+
+- ~300 bytes bundle size increase
+- One `IntersectionObserver` allocation (shared across all lazy elements)
+- Per lazy element: one `Map.set()` + one `observer.observe()` call
+
+## What it improved
+
+| Metric | mail-webui | mail-webui-light |
+|--------|:---:|:---:|
+| Event listeners | -32% (532→360) | -55% (622→282) |
+| JS Heap Used | -1.8% | -2.0% |
+| JS Script Duration | -5% | -3% |
+
+## Why it was reverted
+
+### 1. No FCP/LCP improvement
+
+FCP and LCP measure when the browser paints pixels. Paint happens from
+SSR HTML before any JS runs. Lazy hydration only defers JS work that
+happens after paint — it cannot improve FCP/LCP by design.
+
+### 2. Breaks repeat children
+
+When a parent component updates an array (e.g., adding a todo item),
+`syncRepeat` sets attributes on all child instances. For lazy children
+with `$ready = false`, the `$update()` call is silently dropped. The
+SSR DOM goes stale, causing visual mismatches.
+
+Attempted fix: force-hydrate lazy children when `$update()` is called.
+This triggered full hydration on every repeat child during every array
+update — worse than no lazy at all.
+
+### 3. IntersectionObserver misses scroll containers
+
+`IntersectionObserver` checks viewport intersection, not scroll position
+within a parent container. In the todo app with 1000 items in a scrollable
+`<div>`, ALL items register as "in viewport" because their host element
+is visible — even though 990 items are scrolled out of view.
+
+### 4. TTI regression for shadow DOM
+
+The async nature of `IntersectionObserver` added a layout cycle for
+visible lazy components. Shadow DOM TTI regressed +39% (12→17ms).
+Light DOM was slightly better (-6%).
+
+## Lessons learned
+
+1. **Component-level lazy is the wrong granularity.** The expensive work
+   is in repeat item hydration (1000 binding sets), not component hydration
+   (one component, one set of bindings).
+
+2. **The right approach is virtualized repeat** — only create repeat
+   instances for visible items. See `TODO_RENDER_PERF.md`.
+
+3. **Never silently drop `$update()` calls.** If a component receives a
+   property change, it must either process it or queue it — not ignore it.
+
+4. **`hydrationEnd()` must fire immediately** for deferred components,
+   or TTI measurement is blocked.
+
+## Test coverage that was created
+
+16 tests were written covering:
+
+- **Core behavior (4):** below-fold deferral, scroll-into-view hydration,
+  observer async behavior, SSR DOM preservation
+- **Lifecycle (3):** disconnect-before-hydrate cleanup, reconnect
+  re-observation, observer disconnect after hydration
+- **State/reactivity (3):** SSR state preservation, pre-hydration property
+  updates, reactive updates after lazy hydration
+- **Interaction (2):** events wired on hydrate, conditional hydration
+- **Integration (3):** non-lazy sibling unaffected, shared observer
+  verification, bulk scroll hydration
+
+These tests passed but were removed with the revert since the feature
+code was removed.

TODO_RENDER_PERF.md

@@ -0,0 +1,35 @@
+# TODO: Render Performance Improvements
+
+## Virtualized Repeat (`<for virtualize>`)
+
+Instead of hydrating all repeat items, only create repeat instances for visible items.
+
+### Problem
+For large lists (1,000+ items), the framework creates bindings, scope objects, and DOM nodes
+for every item — even those the user will never scroll to see. This dominates TTI and memory.
+
+### Proposed approach
+- Server SSR renders all items (for SEO/FCP)
+- At hydration, `syncRepeat` with `virtualize` flag:
+  1. Measures container height and item height
+  2. Keeps only ~15 DOM nodes (visible window + small buffer)
+  3. Removes the other 985 SSR nodes from DOM
+  4. On scroll, recycles DOM nodes with new data (no create/destroy)
+
+### Expected savings (1,000 items)
+- Bindings: 45 instead of 3,000
+- Event listeners: 30 instead of 2,000
+- DOM nodes: ~75 instead of ~5,000
+- Memory: dramatically less
+
+### Design notes
+- Opt-in via `virtualize` attribute on `<for>` in template
+- Requires known/estimated item height for positioning
+- Scroll handler recycles DOM nodes by updating scope data
+- Should work with both keyed and unkeyed repeat
+- Must handle dynamic item heights (measure after render, cache)
+
+### Prior art
+- React Virtuoso, TanStack Virtual
+- Lit `@lit-labs/virtualizer`
+- iOS `UITableView` / Android `RecyclerView`