@webjsdev/cli 0.10.11 → 0.10.12

package/resources/agent-docs/ssr-partial-nav-design.md

@@ -0,0 +1,214 @@
+# SSR partial navigation: design note
+
+**Status:** SHIPPED (feature/nested-layout-partial-swap, 2026-05-16).
+The mechanism described below is implemented and tested. This document
+is preserved as the design record. Runtime reference for callers lives
+in `agent-docs/advanced.md` (Client router section) and the framework
+API table in `AGENTS.md`.
+
+**Motivating bug (resolved):** ui-website docs sidenav lost scroll on
+every link click because the docs layout sat 2 levels deep under the
+root layout, beyond `findLayoutShell`'s body-direct-child probe.
+**Previous workaround (now deleted):** `app/docs/layout.ts` saved /
+restored `.docs-sidenav` `scrollTop` via `sessionStorage` on every
+`webjs:navigate` event. Removed in the same PR as the framework fix.
+
+---
+
+**What actually shipped vs. what's below:**
+- The recommendation in this doc was `<webjs-frame>` as the primary
+  primitive. During design discussion the decision evolved to make
+  layout-marker discovery **auto-derived from folder structure**, so
+  layout authors write nothing. `<webjs-frame>` ships as the escape
+  hatch for non-layout partial-swap regions (rare).
+- The marker format is `<!--wj:children:<segment-path>-->` comment
+  pairs (Remix v3 lineage), not the `<webjs-frame>`-element approach
+  sketched below.
+- Wire-byte optimization, snapshot cache, keyed DOM diff with live-
+  attribute preservation, and per-segment `<template id="wj-loading:...">`
+  cloning all shipped in the same PR (originally deferred as v2+).
+
+The original `<webjs-frame>`-centric sketch below is preserved as
+historical context.
+
+---
+
+## Goal
+
+Preserve the DOM of any layout, at any depth, across same-origin navigations. Re-render only the deepest segment that actually changed.
+
+## Non-goals
+
+- Per-segment data fetching (Remix v3 `<Frame src>` style). Wire model stays one SSR response per nav.
+- React-style reconciler with full keyed-DOM diff inside the swap region. Out of scope for v1, can come later.
+- Parallel routes / intercepting routes (Next.js feature). Separate design.
+
+## Background: how the four references handle this
+
+| Framework | Mechanism | Wire format | Scope decided by |
+|---|---|---|---|
+| **Turbo** | `<turbo-frame id="X">` (flat DOM element) | full HTML response, server may optimize via `Turbo-Frame: X` header | Innermost enclosing `<turbo-frame>` of the click (`closest()`) |
+| **Remix v3** | `<!--rmx:f:id-->...<!--/rmx:f-->` comment markers + per-frame `src` | per-frame HTML or `<template id>` streams | Author-declared `<Frame name="...">` + `rmx-target` on link |
+| **Next.js App Router** | Recursive `FlightRouterState` tuple + per-segment `CacheNode` tree | RSC Flight (`react-server-dom-webpack`) | Server walks the tree, returns from divergence point |
+| **Lit Labs** | `Routes` controller with `outlet()` + child controllers via `RoutesConnectedEvent` | full template re-render (no partial scoping) | N/A (full subtree re-render every nav) |
+
+**Closest fit to webjs's current router:** Turbo. webjs already mirrors Turbo Drive (link interception, body swap, `pushState`, `data-no-router` ≡ `data-turbo="false"`).
+
+## Recommendation
+
+Adopt a Turbo-style frame primitive: `<webjs-frame id="...">`. Layouts that want partial-swap behavior wrap their replaceable region:
+
+```ts
+// app/docs/layout.ts
+import { html } from '@webjsdev/core';
+import { sidenav } from './sidenav.ts';
+
+export default function DocsLayout({ children }) {
+  return html`
+    <div class="docs-grid">
+      ${sidenav()}
+      <webjs-frame id="docs-content">${children}</webjs-frame>
+    </div>
+  `;
+}
+```
+
+### Algorithm: `packages/core/src/router-client.js` delta
+
+Existing `findLayoutShell(body)` stays as a fallback. Add `findActiveFrame(linkEl)`:
+
+```js
+function findActiveFrame(linkEl) {
+  // Walk up through shadow boundaries and into light DOM via composedPath at call site.
+  const frame = linkEl.closest('webjs-frame');
+  return frame ? frame.id : null;
+}
+
+async function navigate(url, event) {
+  const frameId = event ? findActiveFrame(event.target) : null;
+
+  const res = await fetch(url, {
+    headers: frameId ? { 'X-Webjs-Frame': frameId } : {},
+  });
+  if (!res.headers.get('content-type')?.startsWith('text/html')) {
+    // existing fallback: full nav
+    window.location.href = url;
+    return;
+  }
+
+  const html = await res.text();
+  const incoming = Document.parseHTMLUnsafe(html);
+
+  // 1. Frame path: preferred if active frame exists in both.
+  if (frameId) {
+    const target = document.querySelector(`webjs-frame#${CSS.escape(frameId)}`);
+    const source = incoming.querySelector(`webjs-frame#${CSS.escape(frameId)}`);
+    if (target && source) {
+      target.replaceChildren(...source.childNodes);
+      mergeHead(incoming.head);
+      runFrameScripts(target);
+      customElements.upgrade(target);
+      history.pushState({}, '', url);
+      document.dispatchEvent(new CustomEvent('webjs:navigate', { detail: { url, frameId } }));
+      return;
+    }
+  }
+
+  // 2. Existing layout-shell path (one level deep).
+  const shell = findLayoutShell(document.body);
+  const incomingShell = shell ? findLayoutShell(incoming.body) : null;
+  if (shell && incomingShell && shellsMatch(shell, incomingShell)) {
+    swapShellContent(shell, incomingShell);
+    /* existing path... */
+    return;
+  }
+
+  // 3. Full body swap (existing fallback).
+  document.body.replaceChildren(...incoming.body.childNodes);
+  /* existing path... */
+}
+```
+
+That's the entire detection delta: a `querySelector` keyed by the active frame's id, with the existing logic preserved as fallback.
+
+### `<webjs-frame>` element: ~30 lines
+
+```js
+// packages/core/src/webjs-frame.js
+import { WebComponent, html } from './index.js';
+
+export class WebjsFrame extends WebComponent {
+  static properties = { id: { type: String, reflect: true } };
+  render() { return html`<slot></slot>`; }
+}
+WebjsFrame.register('webjs-frame');
+```
+
+Light DOM (default): no shadow boundary, no slot mechanics. The element exists purely as a swap anchor with an addressable `id`. Children are normal light-DOM children that the router replaces via `replaceChildren`.
+
+### Server side: `X-Webjs-Frame` request header (optional optimization)
+
+When set, the SSR pipeline can return only the matching frame's HTML wrapped in a minimal stub document, skipping the rest of the layout chain. Wire is still plain HTML (no new format). v1 ships **without** this optimization. Full SSR response, client extracts what it needs. The header is forward-compat for the perf pass.
+
+### Head merging
+
+Same as today's `mergeHead`: replace `<title>`, merge `<meta>` tags by `name`/`property`, append new `<link>`/`<style>` elements, dedupe.
+
+### Script handling inside the swap region
+
+Re-execute `<script>` elements that match the existing one-level-shell path's `runScripts` logic. Idempotent registration via `Class.register()` makes this safe. The framework already handles `customElements.define` collisions.
+
+## Edge cases
+
+| Case | Behavior |
+|---|---|
+| Click on a link inside `<webjs-frame>` but `data-no-router` | Full browser navigation (existing semantics) |
+| Click on a link *outside* any frame, both pages share a `findLayoutShell` match | Falls through to existing layout-shell path |
+| Frame in old page but not in new (route change leaves the layout tree) | Frame lookup fails → fall to layout-shell or full body swap. Correct. |
+| Nested `<webjs-frame>`s | Innermost wins: `closest('webjs-frame')` returns the nearest enclosing frame. Mirrors Turbo behavior. |
+| Form submission inside a frame | Same. POST response gets the same frame-extract treatment. (Implement in form-submit path alongside link-click.) |
+| Hash-fragment-only navigation | Existing behavior. No fetch, browser handles. |
+| `data-frame="_top"` on a link | Escapes the enclosing frame, full nav. (Turbo precedent.) |
+
+## What this fixes
+
+- **ui-website docs sidenav scroll**: docs layout wraps content in `<webjs-frame id="docs-content">`. Sidenav lives *outside* the frame. Navigation between `/docs/components/a` → `/docs/components/b` only swaps frame children. The sidenav DOM is untouched, and `<aside>` scroll position is preserved natively. The `sessionStorage` workaround in `app/docs/layout.ts` can be deleted.
+- **Any nested-layout app**: the same primitive works whether the partial-swap region is 2, 3, or 5 levels deep.
+- **Mixed layouts**: pages that don't opt-in fall through to the existing one-level shell detection or full body swap. No regression risk.
+
+## What's deliberately deferred (future passes)
+
+1. **Keyed `data-key` DOM diff inside the frame.** Adopt Remix v3's `diff-dom.ts` algorithm to preserve input values, `<details>` open state, popover state, scroll positions on inner scroll containers across nav. Today's `replaceChildren` is coarse, but fine for v1 since the frame *itself* is preserved (outer scroll, sidenav, etc.).
+2. **`X-Webjs-Frame` server optimization** to avoid re-rendering layouts the client already has.
+3. **Server-pushed partial updates** (turbo-stream equivalent) via `<webjs-stream action="replace" target="...">`. Separate feature, useful for SSE/WebSocket-driven UI.
+4. **Frame-scoped error boundaries.** If a frame fetch 5xxs, render only the frame's `error.ts`, not the whole page.
+
+## Implementation plan
+
+1. **`packages/core/src/webjs-frame.js`**: new file, the custom element.
+2. **`packages/core/index.js`**: export `WebjsFrame`. Re-export `<webjs-frame>` via auto-registration import (so any app that imports `@webjsdev/core` gets it).
+3. **`packages/core/src/router-client.js`**: add `findActiveFrame()`, frame-swap branch in `navigate()`. Preserve existing `findLayoutShell` and full-body fallback.
+4. **`packages/core/src/router-client.js` (form path)**: apply the same frame-extract to form submit responses.
+5. **`packages/server/src/dev.js`**: accept `X-Webjs-Frame` header in dev mode (no-op for v1 but adds the request signal for telemetry).
+6. **Tests:**
+   - `packages/core/test/routing/router-client.test.js`: frame detection, querySelector with various ids, fallback when source frame missing.
+   - `test/e2e/nested-layout-partial-swap.test.mjs`: load `/docs/components/a`, scroll sidenav, click `/docs/components/b`, assert scroll preserved AND only frame children swapped.
+7. **Docs:**
+   - `AGENTS.md`: add `<webjs-frame>` to the public API table.
+   - `agent-docs/advanced.md`: new "Frames" section under the client-router doc.
+   - `docs/` app: a new docs page showing the pattern.
+8. **`packages/cli/templates/`**: none for v1 (frames are opt-in, no scaffold change needed).
+9. **ui-website cleanup**: remove the `sessionStorage` workaround in `app/docs/layout.ts` after the frame lands and tests prove scroll preservation.
+
+## Open questions
+
+1. **Should `<webjs-frame>` ship a `src=""` attribute** for lazy loading like turbo-frame does? Probably yes eventually, but not for v1. The motivating use case is layout-scope, not lazy data.
+2. **Should there be a sub-element registry** (something like `data-layout="docs"` as a shorthand)? Keep it explicit for v1: one mechanism. Consider sugar later.
+3. **`X-Webjs-Frame` header naming.** `Webjs-Frame` (like `Turbo-Frame`) is shorter. Either works, and v1 implements neither for response routing so the bikeshed is deferred.
+
+## References
+
+- Turbo source: `frame_controller.js:132-148` (response parse), `frame_renderer.js:5-16` (swap), `link_interceptor.js:48` (innermost-frame rule)
+- Remix v3 source: `packages/component/src/lib/frame.ts:1134-1146` (comment markers), `diff-dom.ts:124-162` (live-attr preservation list)
+- Next.js source: `packages/next/src/client/components/router-reducer/ppr-navigations.ts:230,251,292,354,486` (cache reuse vs create), `walk-tree-with-flight-router-state.tsx:106-112` (server-side tree walk)
+- webjs current: `packages/core/src/router-client.js` (`findLayoutShell`, single body-children scan)

package/resources/agent-docs/styling.md

@@ -0,0 +1,235 @@
+# Styling: Tailwind-first, plus vanilla-CSS opt-out
+
+Tailwind is the strong default. The conventions below cover the
+Tailwind-first rule and the lit reflex it exists to counter, then how to
+opt out and use plain CSS everywhere (fully supported).
+
+## Tailwind-first is the strong default
+
+**Use Tailwind utilities for pages AND light-DOM components (the default
+DOM mode).** Layout, spacing, color (via the `@theme` tokens),
+typography, borders, radius, shadows, and interaction states
+(hover/focus/active/disabled, dark mode) are all utility-expressible.
+Light DOM does not scope styles, so a utility class on a light-DOM
+element resolves against the global stylesheet exactly as it does on a
+page. That is why utilities are the right tool there, not an exception.
+
+### The lit muscle-memory trap (read this first)
+
+AI agents with strong lit / web-components training carry one habit that
+fights this default: in lit, a component owns a shadow root and scopes
+its CSS with `static styles = css\`\``, so the reflex is to author scoped
+CSS or an inline `<style>` with semantic class names (`.hero`,
+`.feature`, `.card`, `.btn`) for every component.
+
+**In webjs the default is light DOM, which does NOT scope.** A scoped
+`css` block does nothing without `static shadow = true` (the framework
+warns at runtime), and an inline `<style>` with bare semantic class names
+leaks those names into the global namespace. So reaching for either in a
+light-DOM component is the reflex to resist. Prefer Tailwind utilities.
+When the same utility bundle repeats, extract it into a `lib/utils/ui.ts`
+helper that returns an `` html`...` `` fragment (the existing pattern,
+below), NOT a CSS class. The helper keeps the utilities visible at the
+definition site and runs at SSR time, so the output is identical to
+writing the classes inline.
+
+### The custom-CSS allowlist (the only things raw CSS is for)
+
+Reserve raw CSS for what utilities genuinely cannot express. This is the
+exhaustive list; anything outside it should be a utility (or a
+`lib/utils/ui.ts` helper):
+
+- **design-token `:root` + `@theme` definitions** (the palette, fonts,
+  fluid type scale, motion durations declared once in the root layout),
+- **`@property` animated custom properties** paired with `@keyframes`,
+- **`::-webkit-scrollbar` and `scrollbar-color`** (no utility surface),
+- **`prefers-reduced-motion` blocks**,
+- **complex `color-mix()` or gradient effects** a utility cannot spell.
+
+When custom CSS IS unavoidable inside a light-DOM component, the
+tag-prefix invariant still holds (see the Vanilla CSS section below):
+every class selector is prefixed with the component tag. **Shadow-DOM components
+(`static shadow = true`) legitimately author `static styles = css\`\``,
+which is the right home for scoped CSS and is unchanged by this rule.**
+The Tailwind-first steer is about the LIGHT-DOM default, not about
+shadow DOM.
+
+## Tailwind + JS helpers (default convention)
+
+Default stack: Tailwind CSS browser runtime + `@theme` design tokens
+declared once in the root layout (palette, fonts, fluid type, motion
+durations). Consume via utility classes (`text-fg`, `bg-bg-elev`,
+`font-serif`, `duration-fast`, `text-display`).
+
+**DRY via JS helpers, not `@apply`.** When the same bundle of Tailwind
+classes repeats across 2+ places, extract it into a helper in
+`lib/utils/ui.ts`:
+
+```ts
+import { html } from '@webjsdev/core';
+
+/** `● label` kicker: small caps, accent colour, above headings. */
+export function rubric(label: string, mb: 'sm' | 'md' = 'md') {
+  const mbCls = mb === 'sm' ? 'mb-3' : 'mb-4';
+  return html`
+    <span class="block font-mono text-[11px] leading-none font-semibold tracking-[0.2em] uppercase text-accent ${mbCls}">● ${label}</span>
+  `;
+}
+
+/** "← label" back link: small caps, muted. */
+export function backLink(href: string, label: string) {
+  return html`
+    <a href=${href} class="inline-block mb-12 text-fg-subtle no-underline font-mono text-[11px] leading-none font-medium tracking-[0.15em] uppercase transition-colors duration-fast hover:text-fg">← ${label}</a>
+  `;
+}
+```
+
+```ts
+// app/blog/[slug]/page.ts
+import { rubric, backLink } from '../../../lib/utils/ui.ts';
+
+export default function Post({ params }) {
+  return html`
+    ${backLink('/', 'Posts')}
+    ${rubric('post')}
+    <h1 class="font-serif text-display ...">${title}</h1>
+  `;
+}
+```
+
+### When to extract, when to keep inline
+
+| Repeats | Action |
+|---|---|
+| Once | Inline the classes. |
+| 2–3 times, identical | Extract to `lib/utils/ui.ts`. |
+| Varies by 1–2 props | Extract with a small parameter (`mb: 'sm' \| 'md'`). |
+| Radically different per call site | Keep inline. Don't force-fit. |
+
+### Why not `@apply`?
+
+`@apply` hides which utilities a class uses from the reader and creates
+a second source of truth. JS helpers keep the class bundle visible at
+the definition site and compose naturally with other props (conditional
+classes, active states, etc.). They run at SSR time. Output HTML is
+identical to inline classes, no client-side runtime.
+
+## Dark mode: two signals, keep them in sync
+
+The default scaffold runs **two** theming systems, and a theme switch must
+drive **both** or one half goes stale (this is the single most common
+dark-mode bug in a scaffolded app):
+
+1. **Editorial chrome tokens** (`--fg`, `--bg`, `--accent`, ...) declared in
+   the root layout. They react to a **`data-theme` attribute** on `<html>`
+   (`data-theme="light"` vs absent) and default to dark.
+2. **Webjs UI (shadcn) component tokens** (`--background`, `--foreground`,
+   `--primary`, ...) used by everything under `components/ui/`. They react
+   to a **`.dark` class** on an ancestor (`@custom-variant dark (&:is(.dark *))`)
+   and default to light.
+
+The scaffold's head init script and `theme-toggle` set **both** signals on
+`<html>`: they write `data-theme` AND `classList.toggle('dark', isDark)`. If
+you wire your own theme switch or replace the toggle, you MUST set both.
+Setting only `data-theme` leaves the ui-* components rendering light tokens
+on a dark page (white buttons, white cards, invisible text) while the chrome
+looks correct.
+
+**Verify dark mode in a real browser, not just light.** Light mode passing
+proves nothing about dark mode: with neither signal set, both systems sit at
+a coincidentally matching default, so the divergence only appears once
+`.dark` / `data-theme` are applied. Emulate dark (`colorScheme: 'dark'` or
+flip the toggle) and check a shadcn component's computed `background-color`,
+not just the page chrome.
+
+## Vanilla CSS for the whole app (opt-out of Tailwind)
+
+Tailwind isn't required. To hand-write CSS everywhere, you need a
+scoping convention so generic class names (`.btn`, `.input`, `.header`)
+don't collide across pages, layouts, and components in the global
+light-DOM namespace.
+
+### Convention: three scopes, one rule each
+
+| Scope | Wrapper selector | Where it lives |
+|---|---|---|
+| **Component** | Custom-element tag | Nested CSS under `my-counter { … }` |
+| **Page** | `.page-<route>` | Wrap the page's markup in `<div class="page-<route>">` |
+| **Layout** | `.layout-<name>` | Wrap the layout's markup in `<div class="layout-<name>">` |
+
+Naming convention: derive the scope class from the file path. Slashes
+→ hyphens. Dynamic segments become their param name. Route groups
+`(marketing)` drop.
+
+- `app/page.ts`                       → `.page-home`
+- `app/about/page.ts`                 → `.page-about`
+- `app/dashboard/posts/new/page.ts`   → `.page-dashboard-posts-new`
+- `app/blog/[slug]/page.ts`           → `.page-blog-slug`
+- `app/(marketing)/about/page.ts`     → `.page-about`
+- `app/layout.ts`                     → `.layout-root`
+- `app/admin/layout.ts`               → `.layout-admin`
+
+Styles colocate with the markup as `const STYLES = css\`…\`` and
+interpolate via `<style>${STYLES.text}</style>`. `ts-lit-plugin` /
+`@webjsdev/ts-plugin` highlights the CSS and resolves class go-to-definition.
+
+### Example: a page
+
+```ts
+import { html, css } from '@webjsdev/core';
+
+const STYLES = css`
+  .page-dashboard {
+    .actions      { display: flex; gap: 12px; }
+    .btn          { padding: 12px 24px; border-radius: 999px; }
+    .btn-primary  { background: var(--accent); color: var(--accent-fg); }
+  }
+`;
+
+export default function Dashboard() {
+  return html`
+    <style>${STYLES.text}</style>
+    <div class="page-dashboard">
+      <div class="actions">
+        <a class="btn btn-primary" href="/new">+ New</a>
+      </div>
+    </div>
+  `;
+}
+```
+
+### Example: a layout
+
+```ts
+const STYLES = css`
+  .layout-root {
+    .header { position: sticky; top: 0; }
+    .nav    { display: flex; gap: 16px; }
+  }
+`;
+
+export default function RootLayout({ children }) {
+  return html`
+    <style>${STYLES.text}</style>
+    <div class="layout-root">
+      <header class="header">
+        <nav class="nav">…</nav>
+      </header>
+      <main>${children}</main>
+    </div>
+  `;
+}
+```
+
+Inside each scope, `.btn` / `.input` / `.header` / `.form` / `.item`
+are free names because CSS descendant combinators stop them at the scope
+boundary. A small curated set of **primitives** (`rubric`, `banner`,
+`accent-link`, `display-h1`, …) can live global in the root layout as
+your design system. Everything else is scoped.
+
+### Tradeoffs vs Tailwind
+
+More files you write, more discipline required, slight rename cost (2
+textual edits when a route folder moves). In exchange: no browser-
+runtime script, no `@theme` block, idiomatic CSS, plain cascade you can
+debug with any tool.