@webjsdev/cli 0.10.49 → 0.10.51

package/templates/gallery/modules/server-actions/actions/bump-clock.server.ts

@@ -0,0 +1,20 @@
+'use server';
+// A mutation paired with the cached GET in ../queries/read-clock.server.ts. With
+// no `method` export it defaults to POST (CSRF-protected, rich request body).
+//
+// `invalidates` lists the cache tags to evict when the action completes. The
+// server drops those tags from its own cache() entries and reports them on the
+// response, so the client coordinator marks them stale and the NEXT readClock()
+// bypasses its browser-cached copy instead of serving a value the mutation just
+// made wrong. Without this export the read would keep answering from cache until
+// its max-age elapsed.
+import type { ActionResult } from '@webjsdev/server';
+import { bumpReading } from '../utils/clock.server.ts';
+
+export const invalidates = () => ['clock'];
+
+export async function bumpClock(): Promise<ActionResult<{ reading: number }>> {
+  // Mutations return the ActionResult envelope, so a caller narrows one shape
+  // whether the write succeeded or failed.
+  return { success: true, data: { reading: bumpReading() } };
+}

package/templates/gallery/modules/server-actions/actions/greet.test.ts

@@ -13,7 +13,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { createRequestHandler, buildRouteTable, matchPage, matchApi, invokeActionForTest } from '@webjsdev/server';
-import { testRequest, loginAndGetCookies } from '@webjsdev/server/testing';
+import { submitForm, loginAndGetCookies } from '@webjsdev/server/testing';
 
 const appDir = process.cwd();
 process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';
@@ -54,10 +54,11 @@ test('an authenticated greet reads the caller off the session via actionContext(
   // migrated (run db:generate + db:migrate) rather than fail misleadingly.
   const email = `greet+${Date.now()}@example.com`;
   const password = 'password123';
-  const signupRes = await testRequest(app.handle, '/features/auth/signup', {
-    method: 'POST',
-    headers: { 'content-type': 'application/x-www-form-urlencoded' },
-    body: new URLSearchParams({ name: 'Ada', email, password }).toString(),
+  // `submitForm` renders the signup page and reuses the identity the server put
+  // in the form's hidden `__webjs_action` field, which is what tells the
+  // dispatcher which action to run; a POST without it is answered 405.
+  const signupRes = await submitForm(app.handle, '/features/auth/signup', {
+    name: 'Ada', email, password,
   });
   if (signupRes.status !== 302) { t.skip('app deps/db not ready; run db:generate + db:migrate'); return; }
   const { cookies } = await loginAndGetCookies(app.handle, { email, password });

package/templates/gallery/modules/server-actions/components/clock-reader.ts

@@ -0,0 +1,98 @@
+// Drives the GET-versus-mutation pair. Both are imported normally (the client
+// import is rewritten to a typed RPC stub); the verbs are declared on the action
+// files, so nothing here changes between a GET and a POST call site.
+//
+// The reads are click-driven on purpose. A read issued during SSR would resolve
+// from the action seed on its first client call, so "watch it hit the network"
+// would be wrong for the first paint.
+import { WebComponent, signal, html } from '@webjsdev/core';
+import { cardClass } from '#components/ui/card.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { readClock } from '../queries/read-clock.server.ts';
+import { bumpClock } from '../actions/bump-clock.server.ts';
+
+interface Row {
+  reading: number;
+  serving: number;
+  at: string;
+  clickedAt: string;
+}
+
+export class ClockReader extends WebComponent {
+  private rows = signal<Row[]>([]);
+  private busy = signal(false);
+  private error = signal('');
+
+  // Both timestamps are formatted here, in the visitor's timezone, so the server
+  // instant and the click time are directly comparable wherever this is deployed.
+  private clock(value: Date | string): string {
+    return new Date(value).toLocaleTimeString('en-US', { hour12: false });
+  }
+
+  async read() {
+    // `?disabled` only lands on the next render commit, so a second click in the
+    // same task would fire a second request. The signal is the real guard.
+    if (this.busy.get()) return;
+    this.busy.set(true);
+    this.error.set('');
+    const clickedAt = this.clock(new Date());
+    try {
+      // A GET action returns its value directly. The stub THROWS on a transport
+      // failure, so the call is guarded the same way the envelope is narrowed.
+      const r = await readClock();
+      this.rows.set([{ ...r, clickedAt }, ...this.rows.get()].slice(0, 6));
+    } catch {
+      this.error.set('The read failed. Is the server still running?');
+    } finally {
+      this.busy.set(false);
+    }
+  }
+
+  async bump() {
+    if (this.busy.get()) return;
+    this.busy.set(true);
+    this.error.set('');
+    try {
+      // A mutation returns the ActionResult envelope, so narrow on success.
+      const r = await bumpClock();
+      if (!r.success) this.error.set(r.error ?? 'The bump failed.');
+    } catch {
+      this.error.set('The bump failed. Is the server still running?');
+    } finally {
+      this.busy.set(false);
+    }
+  }
+
+  render() {
+    const rows = this.rows.get();
+    return html`
+      <div class="${cardClass()} grid gap-4 p-5 max-w-[520px]">
+        <div class="flex flex-wrap gap-2">
+          <button type="button" @click=${() => this.read()} ?disabled=${this.busy.get()}
+            aria-busy=${this.busy.get() ? 'true' : 'false'}
+            class=${buttonClass()}>Read</button>
+          <button type="button" @click=${() => this.bump()} ?disabled=${this.busy.get()}
+            aria-busy=${this.busy.get() ? 'true' : 'false'}
+            class=${buttonClass({ variant: 'secondary' })}>Bump the counter</button>
+        </div>
+        <!-- The results are swapped in after a click, so they are announced. -->
+        <div role="status" aria-live="polite">
+          ${rows.length
+            ? html`
+                <ul class="m-0 grid gap-1 list-none p-0 font-mono text-sm">
+                  ${rows.map((r) => html`
+                    <li class="flex justify-between gap-4">
+                      <span class="text-foreground">reading #${r.reading}, served ${r.serving} at ${this.clock(r.at)}</span>
+                      <span class="text-muted-foreground">clicked ${r.clickedAt}</span>
+                    </li>
+                  `)}
+                </ul>
+              `
+            : html`<p class="m-0 text-sm text-muted-foreground">Press Read twice in a row, then bump and read again.</p>`}
+        </div>
+        ${this.error.get() ? html`<p role="alert" class="m-0 text-sm text-destructive">${this.error.get()}</p>` : ''}
+      </div>
+    `;
+  }
+}
+ClockReader.register('clock-reader');

package/templates/gallery/modules/server-actions/queries/read-clock.server.ts

@@ -0,0 +1,38 @@
+'use server';
+// A GET server action. An action declares its HTTP semantics through reserved
+// sibling exports the framework reads statically, the same way a page declares
+// `export const revalidate`.
+//
+//   method     'GET' rides the args in the URL, is CSRF-exempt, and carries a weak
+//              ETag (a revalidation answers 304). It does NOT cache on its own: a
+//              GET with no `cache` export is `no-store`. With
+//              no `method` export an action is a POST mutation. (SSR seeding is
+//              NOT a GET feature: an action invoked during a fully buffered SSR
+//              render is seeded into the page whatever its verb. A streamed page
+//              emits no seed block at all.)
+//   cache      the max-age in seconds, and what makes the response cacheable at
+//              all. The number is shorthand for the object form, so
+//              { maxAge: 10, swr: 30 } adds a stale-while-revalidate grace
+//              window. PRIVATE by default. Only pass
+//              { public: true } for data identical for EVERY visitor, since a
+//              shared cache keys the entry on the URL and args alone. Same
+//              safety rule as a page's `export const revalidate`.
+//   tags       labels this cached entry so a mutation can evict it by name.
+//
+// One function per file is required once a file carries these config exports.
+import { serveReading } from '../utils/clock.server.ts';
+
+export const method = 'GET';
+export const cache = 10;
+export const tags = () => ['clock'];
+
+export async function readClock(): Promise<{ reading: number; serving: number; at: string }> {
+  // `at` goes over the wire as an ISO instant, not a formatted local time: the
+  // card sits it next to a browser-side timestamp, and a server in another
+  // timezone would otherwise put the two columns hours apart.
+  // `serving` counts the times this body actually ran, so a repeat call answered
+  // from the browser cache is visible: the number does not move. It is also why
+  // this particular read never answers a 304, since a per-execution counter gives
+  // every response a different ETag. A read whose result is stable does.
+  return { ...serveReading(), at: new Date().toISOString() };
+}

package/templates/gallery/modules/server-actions/utils/clock.server.ts

@@ -0,0 +1,27 @@
+// A server-only utility (no 'use server'), like format.server.ts next to it: the
+// tiny bit of state the cached GET read and the mutation that invalidates it
+// share. Not RPC-callable, so a browser import would throw at load. A real app
+// keeps this in the database.
+//
+// Two counters, because they show different things. `reading` is the domain
+// value the mutation changes. `servings` counts how many times the read actually
+// EXECUTED on the server, which is what makes a browser-cache hit visible: a
+// response served from cache does not run this function, so the number does not
+// move.
+//
+// Both are per-PROCESS and shared by every visitor, which is fine for a demo but
+// is exactly why a real app puts this in the database. On a deployed gallery
+// someone else's bump moves your reading, and your first read opens at whatever
+// serving number the process is on.
+let reading = 1;
+let servings = 0;
+
+export function serveReading(): { reading: number; serving: number } {
+  servings += 1;
+  return { reading, serving: servings };
+}
+
+export function bumpReading(): number {
+  reading += 1;
+  return reading;
+}

package/templates/gallery/modules/todo/actions/submit-todo.server.ts

@@ -0,0 +1,31 @@
+'use server';
+
+import { createTodo } from './create-todo.server.ts';
+import { toggleTodo } from './toggle-todo.server.ts';
+import { deleteTodo } from './delete-todo.server.ts';
+
+// The no-JS write path for the todo forms. Every <form> in <todo-app> binds
+// THIS action, and the submit button's own `name="intent"` says which mutation
+// to run, which is how one form serves several buttons.
+//
+// Why an intent dispatcher here rather than binding each button to its own
+// action: this form carries the todo's `id` on a hidden input and needs the
+// SAME id for whichever mutation runs, so one action reading both fields is the
+// simpler shape. When the buttons need no shared payload, bind each one
+// directly instead, with `formaction=${action}` on a <button> inside the bound
+// form. The identity then rides that button's own name/value pair, so it works
+// with JS off too. Two things to know: it must be a <button> (on an
+// <input type="submit"> the identity would occupy `value`, which is also that
+// control's visible label), and a bound submitter cannot carry its own
+// `name`/`value`, which is exactly the channel `name="intent"` uses below.
+//
+// With JS the component intercepts the submit and calls the underlying action
+// directly for the optimistic path, so this runs only with JS off.
+export async function submitTodo(formData: FormData) {
+  const intent = String(formData.get('intent') ?? '');
+  const id = String(formData.get('id') ?? '');
+  if (intent === 'create') return createTodo({ title: String(formData.get('title') ?? '') });
+  if (intent === 'toggle') return toggleTodo({ id });
+  if (intent === 'delete') return deleteTodo({ id });
+  return { success: false as const, error: 'Unknown action.', status: 400 };
+}

package/templates/gallery/modules/todo/components/todo-app.ts

@@ -1,6 +1,6 @@
 // The interactive surface. Demonstrates: the WebComponent factory + reactive
 // prop, the DECLARATIVE optimistic() API (instant update, auto-rollback), and
-// progressive enhancement (each mutation is a <form> posting to the page action,
+// progressive enhancement (each mutation is a <form action=${submitTodo}> bound to a server action,
 // intercepted by JS for the optimistic path). All interactivity lives in a
 // component; a page/layout cannot be interactive in its own markup.
 //
@@ -17,6 +17,7 @@ import { cn } from '#lib/utils/cn.ts';
 import { createTodo } from '../actions/create-todo.server.ts';
 import { toggleTodo } from '../actions/toggle-todo.server.ts';
 import { deleteTodo } from '../actions/delete-todo.server.ts';
+import { submitTodo } from '../actions/submit-todo.server.ts';
 import type { Todo } from '../types.ts';
 
 type Op =
@@ -95,9 +96,9 @@ export class TodoApp extends WebComponent({
           </div>
         </header>
 
-        <!-- Add: a real <form> so it works with JS off (posts to the page action);
-             with JS, @submit intercepts and runs the optimistic path. -->
-        <form method="post" action="" @submit=${(e: SubmitEvent) => this.add(e)}
+        <!-- Add: a real <form> bound to the server action, so it works with JS
+             off; with JS, @submit intercepts and runs the optimistic path. -->
+        <form action=${submitTodo} @submit=${(e: SubmitEvent) => this.add(e)}
           class="${cardClass()} flex items-center gap-2 p-2 pl-4 shadow-[0_1px_0_0_color-mix(in_oklch,var(--foreground)_5%,transparent)]">
           <input type="hidden" name="intent" value="create" />
           <input name="title" required maxlength="280" autocomplete="off" placeholder="What needs doing?"
@@ -109,7 +110,9 @@ export class TodoApp extends WebComponent({
         <ul class="list-none m-0 p-0 grid gap-2">
           ${list.length ? list.map((todo) => html`
             <li>
-              <form method="post" action=""
+              <!-- One form, two submit buttons: each carries its own
+                   name="intent", which the bound action dispatches on. -->
+              <form action=${submitTodo}
                 class="group flex items-center gap-3 px-3 py-2.5 rounded-xl bg-card border border-border transition-colors hover:border-border-strong ${todo.pending ? 'opacity-55' : ''}">
                 <input type="hidden" name="id" value=${todo.id} />
                 <!-- Toggle is a submit button (degrades to a form POST no-JS); with JS

package/templates/gallery/modules/todo/queries/list-todos.server.ts

@@ -1,8 +1,10 @@
 'use server';
 // A READ is a `'use server'` action so the client (and SSR) can call it via the
 // normal import (rewritten to a typed RPC stub). `method = 'GET'` rides args in
-// the URL, is CSRF-exempt, and its result is SSR-seeded so the component does
-// not re-fetch on hydration.
+// the URL and is CSRF-exempt. It declares no `cache`, so the response is
+// `no-store`: the verb marks the read as safe, the `cache` export is what makes
+// it cacheable. The todo page awaits this server-side and hands the rows down as
+// a `.todos=${...}` property, so nothing re-fetches it on the client.
 import { db } from '#db/connection.server.ts';
 import type { Todo } from '../types.ts';
 

package/templates/gallery/modules/todo/types.ts

@@ -1,12 +1,17 @@
-// WHY a hand-written interface (not `typeof todos.$inferSelect` from the schema):
-// this type is imported by the browser-shipped <todo-app> component. A VALUE
-// import from `db/*.server.ts` would pin the component to a server module and
-// crash it at load (webjs check flags it). A browser-safe shape here is safe.
-// See the server-actions section in this app's AGENTS.md.
-export interface Todo {
-  id: string;
-  title: string;
-  completed: boolean;
-  createdAt: Date;
+// The row shape is DERIVED from the schema, never re-declared: rename a column
+// in db/schema.server.ts and every consumer of this type is a compile error
+// instead of a silent `undefined` at runtime.
+//
+// `import type` is what makes that safe here. This type is imported by the
+// browser-shipped <todo-app> component, and a VALUE import from a
+// `db/*.server.ts` file would pin the component to a server module and crash it
+// at load (webjs check's no-server-import-in-browser-module flags it). A
+// type-only import is erased by the TypeScript stripper before it can reach the
+// browser, so it is exempt from that rule and costs the client nothing.
+import type { todos } from '#db/schema.server.ts';
+
+type TodoRow = typeof todos.$inferSelect;
+
+export interface Todo extends TodoRow {
   pending?: boolean; // client-only: true while an optimistic create is in flight
 }

package/templates/gallery/test/auth/auth.test.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 
 import { createRequestHandler } from '@webjsdev/server';
-import { testRequest, loginAndGetCookies, withSessionCookie } from '@webjsdev/server/testing';
+import { testRequest, submitForm, loginAndGetCookies, withSessionCookie } from '@webjsdev/server/testing';
 
 const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
@@ -14,7 +14,11 @@ const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 // we detect that at the RESPONSE level (a 5xx on the dashboard) and SKIP with a
 // clear message rather than report a misleading failure. After the db is set up
 // every assertion runs for real.
-process.env.DATABASE_URL ||= 'file:./dev.db';
+// The SAME path `.env.example` and `drizzle.config.ts` use, so `db:migrate`
+// prepares the database this test connects to. Pointing somewhere else made the
+// skip below permanent: it told you to run `db:migrate`, and running it
+// migrated a different file.
+process.env.DATABASE_URL ||= 'file:./db/dev.db';
 process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';
 
 function makeHandler() {
@@ -47,24 +51,35 @@ test('signup -> login -> dashboard renders for the authenticated user', async (t
   const email = `harness+${Date.now()}@example.com`;
   const password = 'password123';
 
-  // Real signup through the page server action (the no-JS form write-path).
-  let canSignup = true;
+  // Real signup through the bound server action (the no-JS form write-path).
+  // `submitForm` renders the page and reuses the identity the server put in the
+  // form's hidden field, exactly as a browser with JS off submits it; a POST
+  // without that field is not a form submission and is answered 405.
+  // Only the REQUEST is guarded: an unmigrated table makes the action throw, and
+  // that is the one condition worth skipping for. The assertions below stay
+  // outside the try on purpose, so a genuine regression fails loudly instead of
+  // being caught and reported as a database that was never set up.
+  let signupRes: Response | null = null;
   try {
-    const signupRes = await testRequest(app.handle, '/features/auth/signup', {
-      method: 'POST',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
-      body: new URLSearchParams({ name: 'Harness', email, password }).toString(),
+    signupRes = await submitForm(app.handle, '/features/auth/signup', {
+      name: 'Harness', email, password,
     });
-    // Success auto-logs-in and 302s to the dashboard (carrying the session
-    // cookie); a 422 means validation failed. Either way the action ran.
-    assert.ok([302, 422].includes(signupRes.status), 'signup action ran');
-    if (signupRes.status === 302) assert.equal(signupRes.headers.get('location'), '/features/auth/dashboard', 'signup lands on the dashboard');
-    if (signupRes.status !== 302) canSignup = false;
   } catch {
-    // No migrated DB table -> the action throws. Skip the DB-backed assertions.
-    canSignup = false;
+    signupRes = null;
+  }
+  if (!signupRes || signupRes.status >= 500) {
+    t.skip('no migrated DB; run db:migrate to enable the full flow');
+    return;
+  }
+  // Success auto-logs-in and 302s to the dashboard (carrying the session
+  // cookie); a 422 means validation failed. Either way the action ran.
+  assert.ok([302, 422].includes(signupRes.status), 'signup action ran');
+  if (signupRes.status === 302) {
+    assert.equal(signupRes.headers.get('location'), '/features/auth/dashboard', 'signup lands on the dashboard');
+  } else {
+    t.skip('signup was rejected by validation; run db:migrate to enable the full flow');
+    return;
   }
-  if (!canSignup) { t.skip('no migrated DB; run db:migrate to enable the full flow'); return; }
 
   // Real login captures the genuine signed session cookie.
   const { cookies } = await loginAndGetCookies(app.handle, { email, password });

package/templates/partials/agents-playbook-api.md

@@ -47,6 +47,10 @@ cross-origin access use the `cors()` middleware from `@webjsdev/server`; with
 Run each of these and fix what it reports, in order:
 
 - `npm run check` (correctness: no browser-import or boundary violation).
+- `npm run doctor` (project health; CI runs it too). It fails on whatever
+  `package.json` `webjs.doctor.gate` marks `error`, plus the two hard toolchain
+  checks that are fatal with no gate entry, `NODE_VERSION` and
+  `TSCONFIG_ERASABLE`.
 - `npm run typecheck` (zero type errors).
 - `npm test` (unit tests for the endpoints and modules you built).
 
@@ -63,5 +67,6 @@ npm run start           # production server
 npm test                # unit + browser tests
 npm run typecheck
 npm run check           # correctness checks
+npm run doctor          # project health (severity per check: webjs.doctor.gate)
 npm run db:generate && npm run db:migrate
 ```

package/templates/partials/agents-playbook-fullstack.md

@@ -98,6 +98,10 @@ accessor). Use the shorthand for primitives
 Run each of these and fix what it reports, in order:
 
 - `npm run check` (correctness: no browser-import or boundary violation).
+- `npm run doctor` (project health; CI runs it too). It fails on whatever
+  `package.json` `webjs.doctor.gate` marks `error`, plus the two hard toolchain
+  checks that are fatal with no gate entry, `NODE_VERSION` and
+  `TSCONFIG_ERASABLE`.
 - `npm run typecheck` (zero type errors).
 - `npm test` (unit and browser tests for the features you built).
 - `npm run css:build` (compile Tailwind).
@@ -118,6 +122,7 @@ npm test                     # unit + browser tests
 npm run typecheck
 npm run css:build            # compile Tailwind
 npm run check                # correctness checks
+npm run doctor               # project health (severity per check: webjs.doctor.gate)
 npx webjsdev ui add <name>   # copy a ui primitive into components/ui/
 npx webjsdev ui view <name>  # inspect a primitive's exact signature
 npm run db:generate && npm run db:migrate

package/templates/public/sw.js

@@ -15,8 +15,17 @@
  *   - Same-origin static assets (the per-file ESM modules, the framework
  *     runtime under /__webjs/core/, vendor bundles, public assets) are
  *     stale-while-revalidate, so a repeat visit works offline. In production
- *     these URLs carry a ?v=<hash> content fingerprint, so a changed file gets
- *     a new URL and the cache can never serve stale bytes.
+ *     the FRAMEWORK-emitted URLs (modules, the core runtime, vendor bundles)
+ *     carry a ?v=<hash> content fingerprint automatically, so a changed file
+ *     gets a new URL and the cache cannot serve stale bytes for those.
+ *
+ *     A public/ asset is the exception: its URL is fingerprinted only when you
+ *     mark it with asset() (href=${asset('/public/app.css')}). An un-marked
+ *     public/ URL is stable across deploys, so this worker serves the CACHED
+ *     copy and revalidates behind it, and the first load after a deploy shows
+ *     the OLD bytes. The cache version below will not necessarily rescue you,
+ *     because the build id it derives from is a deploy fingerprint rather than
+ *     a per-file content hash. Mark any public/ asset whose bytes change.
  *
  * Versioning ties to the deploy. The page registers this worker as
  * `/sw.js?v=<data-webjs-build>` (the importmap build id), so a new deploy

package/templates/scripts/clear-gallery.mjs

@@ -79,9 +79,9 @@ const galleryPaths = [
 // query), pruned with the rest of the card.
 const galleryModules = [
   'async-render', 'auth', 'broadcast', 'caching', 'client-router', 'components',
-  'directives', 'file-storage', 'frames', 'gallery', 'optimistic-ui', 'rate-limit',
-  'route-handler', 'server-actions', 'sessions', 'stream', 'streaming', 'suspense',
-  'todo', 'websockets',
+  'directives', 'file-storage', 'forms', 'frames', 'gallery', 'optimistic-ui',
+  'rate-limit', 'route-handler', 'server-actions', 'sessions', 'stream',
+  'streaming', 'suspense', 'todo', 'websockets',
 ].map((m) => `modules/${m}`);
 
 let removed = 0;
@@ -173,7 +173,8 @@ export default function Home() {
 }
 
 function MINIMAL_LAYOUT() {
-  return `import { html } from '@webjsdev/core';
+  return `import { html, asset } from '@webjsdev/core';
+import type { LayoutProps } from '@webjsdev/core';
 
 /**
  * Root layout: the ONLY file that writes the document shell. It links the
@@ -191,10 +192,14 @@ function MINIMAL_LAYOUT() {
 // hand-written <link> in the template body is ignored by browsers).
 export const metadata = { icons: '/public/favicon.svg' };
 
-export default function RootLayout({ children }: { children: unknown }) {
+export default function RootLayout({ children }: LayoutProps) {
   return html\`
     <meta name="color-scheme" content="light dark">
-    <link rel="stylesheet" href="/public/tailwind.css">
+    <!-- asset() content-hashes the url in production, so a deploy that changes
+         the CSS changes the url and the framework serves it immutable for a
+         year. Without it this stable url can serve the PREVIOUS stylesheet
+         from a CDN or a service-worker cache after a deploy. -->
+    <link rel="stylesheet" href=\${asset('/public/tailwind.css')}>
     <style>
       html, body { margin: 0; }
       body {

package/templates/test/hello/e2e/hello.test.ts

@@ -12,9 +12,26 @@
 import { test, describe, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
 import { createServer } from 'node:net';
 
-let browser: any, page: any, serverProcess: any, baseUrl: string;
+// puppeteer-core is an optional dev dependency, so `import type { Browser,
+// Page } from 'puppeteer-core'` does not resolve until you install it. These
+// minimal structural types keep the file typed in the meantime; swap them for
+// the real imports once puppeteer-core is in package.json. Reaching for `any`
+// here would silently un-type every call below.
+type Page = {
+  // goto resolves an HTTPResponse this file never reads, and modelling that
+  // type would mean re-declaring puppeteer's. Returning void is the honest
+  // narrow shape for the surface actually used.
+  goto(url: string, opts?: { waitUntil?: string; timeout?: number }): Promise<void>;
+  title(): Promise<string>;
+  on(event: string, handler: (e: Error) => void): void;
+  removeAllListeners(event: string): void;
+};
+type Browser = { newPage(): Promise<Page>; close(): Promise<void> };
+
+let browser: Browser, page: Page, serverProcess: ChildProcess, baseUrl: string;
 
 function freePort(): Promise<number> {
   return new Promise((resolve, reject) => {