@webjsdev/cli 0.10.44 → 0.10.45

package/README.md

@@ -38,9 +38,8 @@ Both `webjs create` and `create-webjs-app` auto-install dependencies in the new
 ## Commands
 
 ```sh
-webjs create <name>            # scaffold a full-stack app (default)
-webjs create <name> --template api   # backend-only API app
-webjs create <name> --template saas  # auth + dashboard + Drizzle User model
+webjs create <name>            # scaffold a full-stack app (default; auth ships as a gallery card)
+webjs create <name> --template api   # backend-only API app (routes + modules + Drizzle)
 
 webjs dev                      # dev server with live reload (runs webjs.dev.before, e.g. webjs db migrate, then serves; npm run dev is a thin alias)
 webjs start                    # production server (no build step, serves source directly)

package/bin/webjs.js

@@ -43,10 +43,10 @@ if (cmd !== 'help' && cmd !== undefined && !wantsHelp && !wantsVersion) {
   }
 }
 
-// Exactly three scaffolds exist. Keep this list as the single source of
+// Exactly two scaffolds exist. Keep this list as the single source of
 // truth. AI-agent docs in README.md / AGENTS.md / .cursorrules /
 // .agents/rules/workflow.md / .github/copilot-instructions.md mirror it.
-const TEMPLATES = ['full-stack', 'api', 'saas'];
+const TEMPLATES = ['full-stack', 'api'];
 
 const USAGE = `webjs commands:
   webjs dev   [--port 8080] [--no-hot]            Start dev server with live reload
@@ -60,8 +60,8 @@ const USAGE = `webjs commands:
                                                   --json emits the structured results (with stable codes). --strict also fails the exit on warnings
   webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs typecheck [tsc args...]                   Type-check the app with the project's tsc --noEmit (non-zero on errors)
-  webjs create <name> [--template full-stack|api|saas] [--db sqlite|postgres] [--runtime node|bun] [--no-install]  Scaffold a new webjs app
-                                                  (only 3 templates exist. default: full-stack, Drizzle, --db sqlite, --runtime node)
+  webjs create <name> [--template full-stack|api] [--db sqlite|postgres] [--runtime node|bun] [--no-install]  Scaffold a new webjs app
+                                                  (only 2 templates exist. default: full-stack, Drizzle, --db sqlite, --runtime node)
                                                   --runtime bun emits a Bun-flavored app (bun.lock, bun Dockerfile/CI, bun docs);
                                                   also auto-detected when run via "bun create webjs".
                                                   Auto-runs the detected package manager's install in the new dir
@@ -160,10 +160,10 @@ const HELP = {
     examples: ['webjs typecheck', 'webjs typecheck --watch'],
   },
   create: {
-    usage: 'webjs create <name> [--template full-stack|api|saas] [--db sqlite|postgres] [--runtime node|bun] [--no-install]',
+    usage: 'webjs create <name> [--template full-stack|api] [--db sqlite|postgres] [--runtime node|bun] [--no-install]',
     summary: 'Scaffold a new app. Defaults: full-stack template, Drizzle + SQLite, Node runtime.',
     options: [
-      { flag: '--template <t>', description: 'full-stack (default), api, or saas.' },
+      { flag: '--template <t>', description: 'full-stack (default) or api (backend-only, no UI).' },
       { flag: '--db <d>', description: 'sqlite (default) or postgres.' },
       { flag: '--runtime <r>', description: 'node (default) or bun.' },
       { flag: '--no-install', description: 'Skip the package-manager install step.' },
@@ -171,7 +171,7 @@ const HELP = {
     examples: [
       'webjs create my-app',
       'webjs create my-api --template api',
-      'webjs create my-saas --template saas --db postgres',
+      'webjs create my-api --template api --db postgres',
       'webjs create my-app --runtime bun',
     ],
   },
@@ -846,7 +846,7 @@ async function main() {
     case 'create': {
       const name = rest[0];
       if (!name || name.startsWith('-')) {
-        console.error('Usage: webjs create <app-name> [--template full-stack|api|saas]');
+        console.error('Usage: webjs create <app-name> [--template full-stack|api]');
         process.exit(1);
       }
       const template = flag(rest, '--template', 'full-stack');
@@ -856,16 +856,16 @@ async function main() {
         // on which scaffold to pick for which kind of app.
         console.error(`Error: unknown template '${template}'.
 
-Only three scaffolds exist:
-  full-stack   (default): pages + components + API + Drizzle/SQLite.
-                Pick this for any app the user describes in product terms
-                (todo app, blog, dashboard, marketplace, social feed, …).
-  api          backend-only: route handlers + modules, no pages/SSR.
-                Pick this only if the user explicitly asks for an HTTP/JSON
-                API with no UI.
-  saas         auth + login/signup + protected dashboard + Drizzle User
-                model. Pick this only if the user explicitly asks for auth
-                or a SaaS-shaped product.
+Only two scaffolds exist:
+  full-stack   (default): pages + components + API + Drizzle/SQLite, plus a
+                browsable feature gallery. Auth is one of the gallery cards
+                (login + session + a protected route), so a full-stack app
+                already carries a real auth baseline. Pick this for any app
+                the user describes in product terms (todo, blog, dashboard,
+                marketplace, social feed, a SaaS with accounts, …).
+  api          backend-only: route handlers + modules + Drizzle/SQLite, no
+                pages/SSR. Pick this only if the user explicitly asks for an
+                HTTP/JSON API with no UI.
 
 The scaffold is a starting point. Replace the example layout/page/
 components/schema with the actual app the user requested. Use Drizzle +

package/lib/api-gallery.js

@@ -2,7 +2,7 @@
  * Backend-features showcase for `webjs create --template api`.
  * A set of JSON/HTTP endpoints under `app/api/features/` that demonstrate the
  * backend capabilities an API app uses (the api counterpart of the UI gallery).
- * Extracted here (like saas-template.js) to keep create.js readable and dodge
+ * Extracted here to keep create.js readable and dodge
  * nested-template-literal escaping: files are built from arrays of
  * double-quoted strings, so `${...}` and backticks are emitted literally.
  */

package/lib/create.js

@@ -18,7 +18,6 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
-import { leanComponentSource } from './lean-copy.js';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -106,60 +105,6 @@ function resolveUiRegistryRoot() {
 }
 const UI_REGISTRY_ROOT = resolveUiRegistryRoot();
 
-/**
- * Read a single @webjsdev/ui registry component, rewrite its relative import
- * of `../lib/utils.ts` to the scaffolded app's aliased path so it resolves
- * when written to `components/ui/<name>.ts`. The scaffold puts cn() at
- * `lib/utils/cn.ts` (folder-grouped with other browser-safe helpers), so the
- * alias form is `#lib/utils/cn.ts` (#555/#556).
- *
- * @param {string} name  component name without `.ts` (e.g. 'button')
- * @returns {Promise<string>} source with import rewritten
- */
-async function readUiComponent(name) {
-  const src = join(UI_REGISTRY_ROOT, 'components', `${name}.ts`);
-  const raw = await readFile(src, 'utf8');
-  // The registry component imports cn() via a relative `../lib/utils.ts`; rewrite
-  // it to the scaffolded app's aliased path (cn lives at lib/utils/cn.ts).
-  const rewritten = raw
-    .replaceAll("'../lib/utils.ts'", "'#lib/utils/cn.ts'")
-    .replaceAll('"../lib/utils.ts"', '"#lib/utils/cn.ts"')
-    // onBeforeCache lives in its own client-only module so cn() stays pure (#819).
-    .replaceAll("'../lib/dom.ts'", "'#lib/utils/dom.ts'")
-    .replaceAll('"../lib/dom.ts"', '"#lib/utils/dom.ts"');
-  // Strip the worked @example from a Tier-1 helper (same as `webjs ui add`), so
-  // the scaffolded component is lean and the example is served on demand. The
-  // shared helper is used by the saas-template copier too, so they cannot drift.
-  return leanComponentSource(rewritten, name);
-}
-
-/**
- * Copy a list of @webjsdev/ui registry components into the scaffolded app
- * under `components/ui/`. Throws if any name is missing from the registry,
- * since the scaffold's generated pages import these by name and a missing
- * file would produce ERR_MODULE_NOT_FOUND at first request. Caller must
- * have already invoked assertUiRegistryAvailable().
- *
- * @param {string} appDir  destination app root
- * @param {string[]} names list of component file basenames (without `.ts`)
- */
-async function copyUiComponents(appDir, names) {
-  const uiDir = join(appDir, 'components', 'ui');
-  await mkdir(uiDir, { recursive: true });
-  for (const n of names) {
-    const src = join(UI_REGISTRY_ROOT, 'components', `${n}.ts`);
-    if (!existsSync(src)) {
-      throw new Error(
-        `@webjsdev/ui registry is missing component '${n}.ts' at ${src}. ` +
-        `The scaffold's example pages import this component by name. ` +
-        `Either the registry was published incompletely or the scaffold's ` +
-        `component list is out of sync with the registry.`,
-      );
-    }
-    await writeFile(join(uiDir, `${n}.ts`), await readUiComponent(n));
-  }
-}
-
 /**
  * Copy the example gallery (idiomatic, densely-commented working examples) into
  * the scaffolded app. Merges `templates/gallery/{app,modules}` over the app so
@@ -177,7 +122,9 @@ async function copyUiComponents(appDir, names) {
  */
 async function copyGallery(appDir) {
   const galleryDir = join(TEMPLATES, 'gallery');
-  for (const sub of ['app', 'modules']) {
+  // `test` carries the auth card's real request-pipeline test (test/auth); it
+  // ships with the gallery and is pruned by gallery:clear alongside the card.
+  for (const sub of ['app', 'modules', 'test']) {
     await cp(join(galleryDir, sub), join(appDir, sub), { recursive: true });
   }
 }
@@ -312,21 +259,19 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   const shouldInstall = opts.install === true;
   // Defence in depth. The CLI already validates this, but library
   // callers (tests, programmatic use) might pass anything.
-  const VALID_TEMPLATES = ['full-stack', 'api', 'saas'];
+  const VALID_TEMPLATES = ['full-stack', 'api'];
   if (!VALID_TEMPLATES.includes(template)) {
     throw new Error(
       `Unknown template '${template}'. Only ${VALID_TEMPLATES.join(' / ')} exist.`,
     );
   }
   const isApi = template === 'api';
-  const isSaas = template === 'saas';
-  // The example gallery ships in every UI scaffold (full-stack AND saas). The
-  // copyGallery gate below is !isApi, since only the api template has no UI. saas
-  // overwrites db/schema.server.ts with its own schema (which includes the
-  // gallery's todos table) and renders the gallery below its auth landing.
-  // isFullStack distinguishes the plain full-stack app from saas for the parts
-  // that differ (its own home page and the create.js-written schema).
-  const isFullStack = !isApi && !isSaas;
+  // The example gallery ships in the one UI template (not api, which has no UI),
+  // so the copyGallery gate below is !isApi. Auth is one of the gallery cards
+  // (app/features/auth + modules/auth), so a UI app ships a real, prunable auth
+  // baseline. `isFullStack` names the UI template for the parts that differ from
+  // api (the todos table + the passwordHash column the auth card needs).
+  const isFullStack = !isApi;
 
   // Database dialect (#563): sqlite (default) or postgres. Drizzle is the ORM;
   // the schema/queries/actions are identical across dialects, only db/columns
@@ -420,8 +365,13 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // app runs the compiler under Bun (its image has no Node), a Node app runs
       // it directly.
       ...(isApi ? {} : { 'css:build': cssBuildCmd }),
-      // Shed the demo gallery to a clean, buildable base (scripts/clear-gallery.mjs).
-      ...(isApi ? {} : { 'gallery:clear': isBun ? 'bun scripts/clear-gallery.mjs' : 'node scripts/clear-gallery.mjs' }),
+      // Shed the demo gallery / backend-features showcase to a clean, buildable
+      // base. The UI template runs clear-gallery.mjs; the api template runs
+      // clear-api-gallery.mjs (its showcase is app/api/features, not app/features).
+      'gallery:clear': (() => {
+        const script = isApi ? 'clear-api-gallery.mjs' : 'clear-gallery.mjs';
+        return isBun ? `bun scripts/${script}` : `node scripts/${script}`;
+      })(),
       dev: isBun ? 'bun --bun webjs dev' : 'webjs dev',
       start: isBun ? 'bun --bun webjs start' : 'webjs start',
       test: 'webjs test',
@@ -763,7 +713,10 @@ export const users = table('users', {
   name: text(),
   // JSON column: a structured value persisted as JSON, typed via json<T>().
   // Same helper works on SQLite and Postgres. Delete if you do not need it.
-  settings: json<{ theme?: string }>(),
+  settings: json<{ theme?: string }>(),${isFullStack ? `
+  // The auth gallery card (app/features/auth) signs credentials against this.
+  // gallery:clear removes this column with the rest of the auth surface.
+  passwordHash: text(),` : ''}
   createdAt: createdAt(),
 });
 ${isFullStack ? `
@@ -1040,10 +993,18 @@ export type ActionResult<T> =
     // counterpart of the UI gallery. Prune what you skip.
     const { writeApiGallery } = await import('./api-gallery.js');
     await writeApiGallery(appDir);
+
+    // The showcase-reset script (wired as `gallery:clear` for the api template).
+    // It sheds app/api/features + its modules back to the health + users base.
+    const apiClearSrc = join(TEMPLATES, 'scripts', 'clear-api-gallery.mjs');
+    if (existsSync(apiClearSrc)) {
+      await mkdir(join(appDir, 'scripts'), { recursive: true });
+      await cp(apiClearSrc, join(appDir, 'scripts', 'clear-api-gallery.mjs'));
+    }
   }
 
   if (!isApi) {
-    // Full-stack and SaaS templates: layout + page + theme toggle + Tailwind
+    // The UI template: layout + page + theme toggle + Tailwind
 
     // The Tailwind stylesheet is compiled from public/input.css (written below)
     // to a STATIC public/tailwind.css by css:build, and lib/utils/ui.ts helpers
@@ -1053,8 +1014,8 @@ export type ActionResult<T> =
     const publicDir = join(appDir, 'public');
     await mkdir(publicDir, { recursive: true });
     // Progressive-enhancement service worker (#271): ship the opt-in offline
-    // primitive (the worker + its offline fallback) into the UI scaffolds
-    // (full-stack / saas; this block is api-excluded since api has no UI).
+    // primitive (the worker + its offline fallback) into the UI scaffold
+    // (this block is api-excluded since api has no UI).
     // Dormant until the app registers it (see the skill's references/service-worker.md);
     // it never changes the JS-disabled baseline.
     for (const swFile of ['sw.js', 'offline.html']) {
@@ -1087,13 +1048,9 @@ export type ActionResult<T> =
     // styles/globals.css (the @webjsdev/ui theme).
     await writeUiBootstrap(appDir);
 
-    // The saas auth pages import a few ui-* primitives. A full-stack app adds
-    // any component on demand with `webjs ui add <name>`.
-    if (isSaas) {
-      await copyUiComponents(appDir, [
-        'button', 'card', 'alert', 'badge', 'separator', 'label', 'input',
-      ]);
-    }
+    // The gallery cards style with plain Tailwind (the app is pre-initialised for
+    // `webjs ui add <name>` via writeUiBootstrap above, but ships no components
+    // until you add them on demand).
 
     // The @webjsdev/ui theme (`--color-primary`, `--color-card`, the @theme maps,
     // @custom-variant, @keyframes) plus the app @theme mappings are compiled from
@@ -1136,10 +1093,10 @@ ${uiThemeRaw}
 
     // The gallery: idiomatic, densely-commented single-feature demos under
     // app/features/ plus one whole example app under app/examples/, with logic
-    // in modules/, all linked from the home page below. Shipped in every UI
-    // scaffold (full-stack AND saas) so an agent gains context by browsing real
-    // working code; prune per-feature (delete the route + its module) for what
-    // the app does not use.
+    // in modules/, all linked from the home page below. Shipped in the UI
+    // scaffold so an agent gains context by browsing real working code; prune
+    // per-feature (delete the route + its module) for what the app does not use,
+    // or shed the whole gallery at once with `gallery:clear`.
     await copyGallery(appDir);
 
   await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce } from '@webjsdev/core';
@@ -1322,11 +1279,7 @@ export default function RootLayout({ children }: { children: unknown }) {
   // demo and the example app, and a footer with the docs + source links. Treat it
   // as a starting point: prune the demos you do not use (delete the
   // app/features/<x> route AND its modules/<x>), then reshape this page into the
-  // app's real landing page. For the saas template a login/signup CTA row is
-  // spliced under the tagline.
-  const homeAuthLinks = isSaas
-    ? '\n          <div class="flex flex-wrap gap-3 items-center justify-center mt-2"><a href="/login" class="inline-flex items-center px-4 py-2 rounded-lg bg-primary text-primary-foreground text-sm font-medium no-underline hover:opacity-90">Log in</a><a href="/signup" class="inline-flex items-center px-4 py-2 rounded-lg border border-border text-foreground text-sm font-medium no-underline hover:bg-accent">Create an account</a></div>'
-    : '';
+  // app's real landing page.
   await writeFile(join(appDir, 'app', 'page.ts'), `import { html } from '@webjsdev/core';
 
 export const metadata = {
@@ -1340,10 +1293,15 @@ export const metadata = {
 const FEATURES = [
   { href: '/features/routing', title: 'Routing', blurb: 'A static route plus a dynamic [id] segment that reads params. The file-based router in miniature.' },
   { href: '/features/boundaries', title: 'Boundaries', blurb: 'The control-flow throws (forbidden / unauthorized / notFound) and the nearest boundary file that catches each.' },
+  { href: '/features/auth', title: 'Auth', blurb: 'Password login on createAuth, a signed session cookie, and a real protected route that redirects anonymous visitors to login.' },
   { href: '/features/components', title: 'Components', blurb: 'The WebComponent factory, reactive props, instance signals, and slot projection in light DOM.' },
   { href: '/features/server-actions', title: 'Server actions', blurb: 'A use-server RPC action next to a server-only .server.ts utility, and why the boundary matters.' },
   { href: '/features/optimistic-ui', title: 'Optimistic UI', blurb: 'The imperative optimistic(signal, value, action) flip: instant update, automatic rollback on failure.' },
   { href: '/features/async-render', title: 'Async render', blurb: 'A component that awaits server data in async render(), so the resolved value is in the first paint.' },
+  { href: '/features/streaming', title: 'Streaming actions', blurb: 'A use-server action that returns an async generator, streamed to the call site token by token with for await.' },
+  { href: '/features/stream', title: 'Stream updates', blurb: 'The <webjs-stream> element: renderStream() applies surgical append / replace / remove DOM updates by target id, no region redraw.' },
+  { href: '/features/suspense', title: 'Suspense boundary', blurb: 'The <webjs-suspense> element: a first-paint fallback for a SLOW component, with the resolved content streamed in.' },
+  { href: '/features/view-transitions', title: 'View transitions', blurb: 'The opt-in view-transition meta cross-fades a soft navigation, with a data-webjs-permanent element persisted across the swap.' },
   { href: '/features/directives', title: 'Directives', blurb: 'The lit-html directive set: repeat for keyed lists, watch(signal) for a fine-grained node swap.' },
   { href: '/features/route-handler', title: 'Route handlers', blurb: 'A server-only route.ts HTTP endpoint returning JSON, the WebJs equivalent of a Next route handler.' },
   { href: '/features/forms', title: 'Forms', blurb: 'A no-JS progressive-enhancement form posting to the page action, with server-side validation errors.' },
@@ -1376,7 +1334,7 @@ export default function Home() {
         </h1>
         <p class="text-base sm:text-lg text-muted-foreground max-w-lg leading-relaxed m-0">
           AI-first and web-components-first. Server-rendered, progressively enhanced, and buildless.
-        </p>${homeAuthLinks}
+        </p>
       </section>
 
       <!-- Gallery: every feature demo + the example app -->
@@ -1505,12 +1463,6 @@ ThemeToggle.register('theme-toggle');
 `);
   } // end if (!isApi)
 
-  // --- SaaS template extras: auth, dashboard, drizzle User model ---
-  if (isSaas) {
-    const { writeSaasFiles } = await import('./saas-template.js');
-    await writeSaasFiles(appDir, { runtime });
-  }
-
   // AGENTS.md is already in place via the shared `templateFiles` loop
   // earlier in this function, so no framework-root fallback needed.
 
@@ -1531,20 +1483,11 @@ ThemeToggle.register('theme-toggle');
     modules/users/{actions,queries,types.ts}   ← routes over server actions
     db/{schema,columns,connection}.server.ts   ← Drizzle (User model)
     ${guide}
-`);
-  } else if (isSaas) {
-    console.log(`  ${name}/
-    app/{layout,page}.ts, login/, signup/
-    app/dashboard/{page,settings,middleware}.ts  ← protected
-    app/api/auth/[...path]/route.ts              ← auth API
-    components/ui/*, components/theme-toggle.ts
-    modules/auth/*, lib/{auth,password}.server.ts
-    db/{schema,columns,connection}.server.ts     ← Drizzle (User model)
-    ${guide}
 `);
   } else {
     console.log(`  ${name}/
-    app/{layout,page}.ts          ← a minimal home to grow in place
+    app/{layout,page}.ts          ← gallery home; gallery:clear grows in place
+    app/features/*, modules/*     ← browsable demos (incl. auth: login + protected route)
     components/theme-toggle.ts
     public/input.css              ← Tailwind entry (compiles to public/tailwind.css)
     db/{schema,columns,connection}.server.ts  ← Drizzle
@@ -1593,9 +1536,9 @@ ThemeToggle.register('theme-toggle');
   // Next-steps banner prints LAST so the actionable command is the
   // final thing on screen, never buried above the AI-agent guidance.
   // Single copy-paste line so the user can move from "scaffold done"
-  // to "dev server up" in one command. The full-stack and saas
-  // templates ship with @webjsdev/ui already initialised; the api
-  // template has no UI but may add one later.
+  // to "dev server up" in one command. The full-stack template ships
+  // with @webjsdev/ui already initialised; the api template has no UI
+  // but may add one later.
   const installSegment = installed ? '' : `${pm} install && `;
   // The shipped schema is applied on the first `run dev` (webjs.*.before runs
   // `db migrate`), but only if a migration FILE exists. When we installed, we

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.44",
+  "version": "0.10.45",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/skills/webjs/references/client-router-and-streaming.md

@@ -17,7 +17,15 @@ Read this when a task touches client navigation, prefetch, partial-page swaps, s
 
 The router auto-enables the moment `@webjsdev/core` loads in the browser, which is any page that ships a component. There is nothing to import or opt into. It intercepts same-origin `<a>` clicks (including inside shadow DOM), fetches the target HTML, and replaces only the inside of the deepest shared layout. Outer header, sidenav, and footer DOM is never re-rendered, so scroll positions, input values, and `<details>` state survive a navigation.
 
-**Browser resilience: a dropped layout-marker comment.** SSR wraps each layout's children in a `<!--wj:children:<path>-->...<!--/wj:children-->` comment pair, and the deepest-shared-layout swap matches on those markers. Browsers intermittently DROP the trailing `<!--/wj:children-->` comment while parsing a soft-nav response (the open marker survives, the close does not), which leaves the router with no pairable slot and forces the destructive full-body swap that wipes the outer layout (the top navbar). This is a parse/timing race, not a browser-specific quirk: it surfaced first on Android Chrome (far more frequent under mobile CPU/memory pressure) and was later reproduced on desktop Chromium, so treat it as universal. The router recovers an orphaned open marker (treating the children as running to the end of the containing element), so a lost close comment still takes the correct scoped swap and the outer chrome keeps its DOM identity. The fix keys off the symptom (a missing close), never a user-agent check, so it covers every engine. A page whose sole or outermost close was dropped also omits that layout from its `X-Webjs-Have` request, so the server returns the FULL page (with its trailing chrome) rather than a reduced marker-pair-only fragment, and the swap is bounded against that full page's trailing-sibling count so a `<footer>` in the marker's OWN parent is preserved rather than swept. Wrapping `${children}` in a container element (the shipped idiom, `<main>${children}</main>` with the footer a sibling outside it) keeps this trivially correct, since the close marker is then the parent's last child, and it is the safe pattern for the remaining unhandled shape (a dropped INNER close in a nested layout, which mispairs and could otherwise sweep outer trailing content). Like the iOS-WebKit repaint note in [styling.md](./styling.md), this is a real-browser divergence from headless Chromium, but because it reproduces across engines the deterministic dropped-close browser test is the reliable way to guard it (a single desktop or device pass can miss the race).
+**The nav parse must preserve comments.** SSR wraps each layout's children AND the page itself in a KEYED boundary comment pair (open `<!--wj:children:<segment>:<route-key>-->`, close `<!--/wj:children:<segment>-->`, #1015). The route-key is the region's resolved concrete path with each substituted param value percent-encoded (so a user-controlled value can never terminate the comment or collide with the `:` delimiter). The router STRICTLY scans both the live and incoming DOM into segment maps: a close must id-match its innermost open, and ANY truncation, mispair, duplicate, or legacy anonymous open poisons the whole scan. The swap decision is two-tier with Next.js remount parity: a CHANGED route-key REPLACES (a fresh remount, permanents regrafted) at the PARENT of the shallowest changed boundary (a layout's boundary wraps only its children, so its own param-derived markup lives in the parent's range; anchoring there remounts the layout chrome too, exactly like Next re-rendering the layout with new params), else MORPH (the keyed state-preserving reconcile) at the deepest shared boundary when it is the leaf on both sides. The X-Webjs-Have header carries `segment:route-key` entries so the server re-renders (and re-ships) a dynamic layout the client holds for other params instead of short-circuiting past it. A poisoned scan or no shared segment degrades to a FULL PAGE LOAD (dev logs the cause), never a guessed recovery, so silent DOM corruption is structurally impossible. Hydration keys off another comment (`<!--webjs-hydrate-->`, which `__isHydrating()` reads as a component's first child). So the router and hydration both ride on comments SURVIVING the parse that turns a navigation response into a Document, which makes that parse a load-bearing correctness boundary rather than an implementation detail.
+
+`Document.parseHTMLUnsafe` STRIPS every comment in Chromium 150 (#1007). No other parse API does: `DOMParser`, `setHTMLUnsafe`, `template.innerHTML`, and plain `innerHTML` all preserve them, and so does the document's own navigation parser, which is why a hard refresh always looked correct and only soft nav broke. With the boundaries gone the router degrades to a full page load (correct, just not soft); with `webjs-hydrate` gone a slotted light-DOM component misses the hydration adopt path. `parseHTML` therefore PROBES `parseHTMLUnsafe` once for losslessness instead of sniffing versions, uses it when it is lossless (it is the only single-pass API that also processes Declarative Shadow DOM), and otherwise parses with `DOMParser`, which preserves comments. A fixed browser silently returns to the fast path.
+
+On that fallback, Declarative Shadow DOM is left UNPROCESSED (`DOMParser` does not attach it), a deliberate limitation tracked in #1011, because both ways of adding it back are worse than the gap. Re-serializing via `body.setHTMLUnsafe(body.innerHTML)` is not idempotent (Chromium omits the spec's LF-compensation, so a leading newline in `pre` / `textarea` is silently eaten, which in a `textarea` is form-data corruption), and attaching each root by hand yields a NON-declarative root, which makes any element whose constructor unconditionally calls `attachShadow()` throw `NotSupportedError` on upgrade. The gap costs a JS-less DSD-dependent element its shadow content on a full-body-swap nav, on a stripping browser only; a `static shadow = true` component attaches and renders its own root on upgrade, and a soft nav runs JS by definition.
+
+Note for anyone testing this: **the Chromium web-test-runner currently resolves (148) is LOSSLESS, so CI cannot observe the bug at all** (and `playwright` is a caret range, so that version moves on any dependency refresh). A test that merely asserts "markers survive" passes there whether or not the fix exists. The guard in `packages/core/test/routing/browser/comment-preserving-parse.test.js` SIMULATES a stripping parser so it is provable on every engine.
+
+**There is NO dropped-marker recovery (#1015 replaced #994's).** The pre-#1015 router "recovered" an orphaned open marker by guessing where its children ended (bounded by the other side's trailing-sibling count), which could guess wrong and corrupt silently. Keyed closes make a mispair DETECTABLE instead, and every integrity violation now degrades to a bounded, correct full page load. The historical producers of lost comments (our own comment-stripping parse #1007, mid-parse soft navs #1008) are fixed upstream, so the degradation is a rare backstop, not a common path. Wrapping `${children}` in a container element (the shipped idiom, `<main>${children}</main>` with the footer a sibling outside it) remains a fine layout pattern, though no correctness now depends on it.
 
 **Opting out.** App-wide with config, or per moment at runtime.
 
@@ -105,7 +113,7 @@ The router can wrap a navigation's DOM mutation in the native View Transitions A
 <meta name="view-transition" content="same-origin">
 ```
 
-The accepted value is `same-origin`. When enabled it wraps all three swap paths (the layout-marker swap, the `<webjs-frame>` swap, and the full-body fallback). When `startViewTransition` is unavailable the swap runs synchronously with no flash and no throw. To persist a live element (a playing `<audio>`, an open menu) across a swap by node identity, mark it `data-webjs-permanent` and give it an `id`.
+The accepted value is `same-origin`. When enabled it wraps every swap path (the two-tier boundary swap, the `<webjs-frame>` swap, and the background-revalidation full-body path). When `startViewTransition` is unavailable the swap runs synchronously with no flash and no throw. To persist a live element (a playing `<audio>`, an open menu) across a swap by node identity, mark it `data-webjs-permanent` and give it an `id`.
 
 ## `<webjs-stream>` Surgical Updates
 

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

@@ -103,7 +103,7 @@ class Panel extends WebComponent({ label: String }) {
 
 ## Slots
 
-The full `<slot>` surface works in light DOM with shadow-DOM parity; migrating modes never requires a template rewrite.
+The full `<slot>` surface works in light DOM with shadow-DOM parity; migrating modes never requires a template rewrite. A forwarded slot projects its content everywhere (client, SSR, hydration).
 
 ```ts
 class MyCard extends WebComponent {
@@ -116,7 +116,21 @@ class MyCard extends WebComponent {
 }
 ```
 
-Named slots, the default slot (unnamed children, text, comments), fallback content (a slot's inner markup when nothing matches), first-wins resolution, and dynamic `name=${...}` all behave per spec. The DOM API mirrors shadow slots: `assignedNodes` / `assignedElements` (with `{ flatten: true }`), `element.assignedSlot`, and the `slotchange` event. Both modes are SSR'd (light DOM projects into `<slot data-webjs-light data-projection="actual">`, shadow DOM via Declarative Shadow DOM), so slotted content renders with no JS.
+Named slots, the default slot (unnamed children, text, comments), fallback content (a slot's inner markup when nothing matches), and first-wins resolution all behave per spec. The DOM API mirrors shadow slots: `assignedNodes` / `assignedElements` (with `{ flatten: true }`), `element.assignedSlot`, and the `slotchange` event. Both modes are SSR'd (light DOM places children into `<slot data-webjs-light data-projection="actual">`, shadow DOM via Declarative Shadow DOM), so slotted content renders with no JS.
+
+**Light-DOM slots ARE the native DOM slot API (#1021, full shadow parity).** There is no WebJs-specific slot API. Post-mount writes are live exactly as in shadow DOM, and moving a component between `static shadow = false` and `true` never needs a rewrite:
+
+```ts
+const card = document.querySelector('my-card');
+card.appendChild(node);                         // live, projected
+card.querySelector('[slot=old]').slot = 'new';  // flip re-projects
+card.innerHTML = '<p>replaced</p>';             // replaces slotted content
+card.querySelector('slot').assignedNodes();     // read, mirrors shadow
+node.assignedSlot;
+card.querySelector('slot').addEventListener('slotchange', ...); // async + coalesced
+```
+
+Things to internalize. (1) Every native mutation is live: `appendChild` / `insertBefore` / `removeChild` / `el.remove()` / `innerHTML` / `el.slot=` flip / `HTMLSlotElement.assign()`. Reorder-by-append moves a child to the end (native semantics), a fragment expands and drains, and `insertBefore` against a renderer/non-child ref throws `NotFoundError`. One caveat rides `assign()`: the light-DOM version is an EXTENSION (an element-bound overlay while name matching keeps working), and native shadow `assign()` needs `slotAssignment: 'manual'` which WebJs does not set, so `assign()` is the one write that does NOT survive flipping to `static shadow = true`; avoid it in mode-portable components. (2) Four inherent gaps (from light DOM having no shadow boundary). The gaps: structural host reads (`host.children` / `host.childNodes` / `querySelector(':scope > ...')` / the `innerHTML` GETTER read the rendered template, not the authored children, so read slotted content with `assignedNodes()`); `assignedChild.parentNode` is the `<slot>`; `::slotted()` CSS is shadow-only (style slotted content with normal selectors / Tailwind); and initial-projection lifecycle timing (`firstUpdated` sees the `<slot>` element with EMPTY `assignedNodes()`, because the first light-DOM projection lands one microtask after the first render, where shadow DOM projects natively before it; read assigned content from a `slotchange` listener or after a microtask). (3) Conditional-on-slot at render time does not exist in EITHER mode (a shadow template can't branch on light-child presence at render time either); use CSS `:has()` / `slot:empty` or a `slotchange` listener. (4) The name `default` is a reserved alias for the default slot; do not name a slot `default`. (5) A display-only slotted wrapper still elides; a component whose slots are mutated at runtime is already shipped because a consumer references its tag (force a ship with `static interactive = true` only for a dynamically-resolved reference the analyser cannot see). (6) A generic DOM library should operate on the assigned nodes, never on the host element itself; writes into an ACTIVELY ASSIGNED slot container are folded into the record (self-heal), while a fallback-mode slot's content is renderer-owned and out of contract. (7) A FORWARDED slot projects its content everywhere (#1023): a template may forward a slot into a nested component (html`<inner-shell><slot></slot></inner-shell>`), and the outer component's content projects through it on a client-only mount, in the SSR first paint, and across hydration (no flash back to fallback). The renderer stamps each slot with its template owner (carried across SSR as `data-wj-slot-owner`), so a forwarded slot routes to the outer host that rendered it, not the child it nests in. (8) A LAYOUT's named slots stay in sync across soft navigation (#1024): when a layout renders its `${children}` inside a slotted shell and a page emits top-level `slot=`-attributed children, the named-slot slices update on a soft-nav boundary swap just as the default slice does (the swap resyncs every own slot of the enclosing shell from the incoming page).
 
 A compound child reads its parent at the first server paint via `closest('ui-tabs')` (only tag-name selectors resolve at SSR, and the compound parent must be light DOM). Genuine live-DOM reads (`querySelector`, `classList`, geometry) still throw at SSR, so keep them in `connectedCallback` / `firstUpdated`.
 
@@ -153,7 +167,8 @@ A component that does no client-side work renders the same SSR'd HTML with or wi
 - 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
-- a rendered `<slot>`, or being rendered by a component that itself ships
+- 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
 
 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 (a dynamically-built tag string, a `:defined` rule in an external stylesheet). `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`.
 
@@ -162,6 +177,6 @@ A bare `async render()` (no other signal, light DOM) is elided too: the SSR'd da
 A `WebComponent` inherits `HTMLElement` (browser) or an `ElementShim` (SSR) plus the framework reactivity base. A reactive prop or method whose NAME collides either fails to compile (`TS2415` for a type-incompatible property, `TS2416` for a method signature) or silently hijacks the native member at runtime. The fix is always to rename.
 
 - 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`. Only override one deliberately, with its exact signature; never repurpose the name for app logic.
+- 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`.

package/templates/.agents/skills/webjs/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>`.
+- 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 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.
@@ -149,6 +149,10 @@ The `@property()` decorator is banned by the erasable-TS invariant (decorators a
 
 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.
 
+### Reading `assignedNodes()` in `firstUpdated` of a light-DOM component
+
+In shadow DOM the browser projects slotted content natively before `firstUpdated`, so Lit muscle memory says `this.shadowRoot.querySelector('slot').assignedNodes()` is populated there. In light DOM the first projection lands one microtask AFTER the first render, so `firstUpdated` sees the `<slot>` element with an EMPTY `assignedNodes()`. The webjs-shaped fix: read assigned content from a `slotchange` listener (fires once projection lands, and on every later change), or wait a microtask. Every later read and every mutation-driven update behaves identically in both modes; only the first-render read differs.
+
 ### `:host { display: block }` on a light-DOM component
 
 A custom element is `display: inline` by default, so a block container collapses. In Lit you fix this with `:host { display: block }`, which works because Lit is shadow-DOM-first. A light-DOM WebJs component has no shadow root, so there is no `:host` to write. There is nothing to do: the framework already defaults every light-DOM host to `display: block` via a low-priority `@layer webjs-host` rule, overridable by any Tailwind utility (`class="flex"` wins). A shadow-DOM component (`static shadow = true`) still sets `:host { display: block }` in `static styles` itself, exactly like Lit.

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

@@ -46,7 +46,7 @@ The 103 Early Hints gap costs only a small first-load latency edge where an edge
 webjs create my-app --runtime bun
 ```
 
-`--runtime` is orthogonal to `--template`, so it re-flavors any of full-stack, saas, or api. A Bun scaffold emits a `bun.lock`, a pure `oven/bun:1` Dockerfile plus a bun-install CI, and bun-command agent docs. The test, db, and check tooling still runs on Node.
+`--runtime` is orthogonal to `--template`, so it re-flavors either full-stack or api. A Bun scaffold emits a `bun.lock`, a pure `oven/bun:1` Dockerfile plus a bun-install CI, and bun-command agent docs. The test, db, and check tooling still runs on Node.
 
 ## Running on Bun
 

package/templates/.agents/skills/webjs/references/service-worker.md

@@ -11,7 +11,7 @@ Read this when you want an offline experience or an asset cache in a WebJs app,
 
 ## What ships and why it is safe
 
-WebJs's UI scaffolds (full-stack and saas, not the api template) ship a hand-authored service worker at `public/sw.js` and an offline fallback at `public/offline.html`. Both ship **dormant**: they do nothing until the app registers the worker, and the worker only ever registers from JavaScript. So with JS off no worker exists, and pages, links, and forms behave exactly as before. It is opt-in and adds an offline experience plus an asset cache without changing the no-JS baseline.
+WebJs's UI scaffold (full-stack, not the api template) ships a hand-authored service worker at `public/sw.js` and an offline fallback at `public/offline.html`. Both ship **dormant**: they do nothing until the app registers the worker, and the worker only ever registers from JavaScript. So with JS off no worker exists, and pages, links, and forms behave exactly as before. It is opt-in and adds an offline experience plus an asset cache without changing the no-JS baseline.
 
 This is a thin, hand-readable worker built directly on the native Service Worker and Cache Storage APIs. There is no Workbox, no precache framework, and no bundler step, matching WebJs's no-build, close-to-web-standards posture. The file is yours to edit, not a framework internal.
 

package/templates/gallery/app/api/auth/[...path]/route.ts

@@ -0,0 +1,7 @@
+// The createAuth HTTP endpoints (signin, signout, OAuth callbacks). This route
+// stays at the app root, NOT under app/features/auth/, because createAuth
+// hardcodes /api/auth/signin/* and /api/auth/callback/* for its form posts and
+// OAuth redirect URIs. The rest of the auth card lives under app/features/auth/.
+import { handlers } from '#modules/auth/auth.server.ts';
+export const GET = handlers.GET;
+export const POST = handlers.POST;

package/templates/gallery/app/examples/layout.ts

@@ -0,0 +1,11 @@
+import { html } from '@webjsdev/core';
+
+// Shared layout for every gallery example app under /examples/*. It adds the same
+// slim "back to the gallery" link the feature demos get, so an example is never a
+// dead end. A non-root layout, so it never writes the document shell.
+export default function ExamplesLayout({ children }: { children: unknown }) {
+  return html`
+    <a href="/" class="inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground transition-colors no-underline mb-6">&larr; Gallery</a>
+    ${children}
+  `;
+}

package/templates/gallery/app/features/auth/dashboard/layout.ts

@@ -0,0 +1,20 @@
+import { html } from '@webjsdev/core';
+
+// Nested layout for the protected dashboard subtree. Logout is a plain
+// <form method="POST"> posting to the createAuth signout route: it clears the
+// session cookie and 302s home, and works with JS off (progressive-enhancement
+// default). signOut is server-only (modules/auth/auth.server.ts), so we POST to
+// its route rather than import it into a browser-shipping page. After signout the
+// dashboard middleware bounces any later visit to login.
+export default function DashboardLayout({ children }: { children: unknown }) {
+  return html`
+    <nav class="flex items-center gap-4 mb-6 pb-4 border-b border-border">
+      <a href="/features/auth/dashboard" class="text-sm font-medium text-foreground hover:underline">Dashboard</a>
+      <a href="/features/auth/dashboard/settings" class="text-sm font-medium text-foreground hover:underline">Settings</a>
+      <form method="POST" action="/api/auth/signout" class="ml-auto">
+        <button type="submit" class="px-3 py-1.5 rounded-lg border border-border text-sm text-foreground bg-transparent cursor-pointer transition-colors hover:bg-accent">Log out</button>
+      </form>
+    </nav>
+    ${children}
+  `;
+}

package/templates/gallery/app/features/auth/dashboard/middleware.ts

@@ -0,0 +1,14 @@
+import { auth } from '#modules/auth/auth.server.ts';
+
+// The protected-route gate. A per-segment middleware.ts runs for every request
+// under /features/auth/dashboard/*. It reads the signed session off the request
+// with auth(req); with no valid session it 302s to login BEFORE the page renders,
+// so an anonymous visitor never sees the protected content. This needs no DB
+// query (only a cookie read), so the gate is real the moment the app boots.
+export default async function requireAuth(req: Request, next: () => Promise<Response>) {
+  const session = await auth(req);
+  if (!session?.user) {
+    return new Response(null, { status: 302, headers: { location: '/features/auth/login' } });
+  }
+  return next();
+}