@webjsdev/server 0.8.50 → 0.8.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.50",
+  "version": "0.8.52",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/check.js

@@ -122,18 +122,13 @@ export const RULES = [
   {
     name: 'no-server-import-in-browser-module',
     description:
-      'A page / layout / component module that SHIPS to the browser (the build does NOT elide it) must not transitively import a server-only `.server.{ts,js}` module. The server module is replaced by a stub in the browser, so the import is fine while the page is display-only and elided (its server import is stripped), but the moment the page also does client work (it imports a component to register, enables the client router, uses a reactive primitive, …) it stops being elided and must load in the browser, dragging the server import with it. The stub then throws (or a server-only export like `auth` is missing) the instant the module loads, a runtime browser crash that `webjs typecheck` and the rest of `webjs check` miss. The rule reuses the build\'s own elision verdict, so it ONLY fires on modules that genuinely ship; a display-only page the framework elides is never flagged. The fix is to keep the server call off the browser-shipped module: gate the route in `middleware.ts`, call the server through a `\'use server\'` action, or register the component in a layout so the page elides again. Server-to-server imports (`.server.ts` importing `.server.ts`) and `middleware.ts` / `route.ts` (never shipped) are never flagged.',
+      'A page / layout / component module that SHIPS to the browser (the build does NOT elide it) must not transitively import a server-only `.server.{ts,js}` module. The server module is replaced by a stub in the browser, so the import is fine while the module never loads client-side: a display-only page is elided, and a page whose only client relevance is importing shipping components is import-only (#605/#963), dropped from the boot in favour of its components. But the moment the page does its OWN client work (the client router, a reactive primitive, a module-scope browser-global access, a client-effecting non-component util) it ships whole, dragging the server import with it. The stub then throws (or a server-only export like `auth` is missing) the instant the module loads, a runtime browser crash that `webjs typecheck` and the rest of `webjs check` miss. The rule reuses the build\'s own elision verdict, so it ONLY fires on modules that genuinely ship; an elided, inert, or import-only page is never flagged. The fix is to keep the server call off the browser-shipped module: gate the route in `middleware.ts`, call the server through a `\'use server\'` action, or move the module\'s own client work into a component so the page is dropped again. Server-to-server imports (`.server.ts` importing `.server.ts`) and `middleware.ts` / `route.ts` (never shipped) are never flagged.',
   },
   {
     name: 'one-action-per-configured-file',
     description:
       'A `\'use server\'` action file that declares HTTP-verb config (any of `method` / `cache` / `tags` / `invalidates` / `validate`, #488) must export exactly ONE callable action function. The config is file-level (it applies to the action in the file), so a second exported function would silently inherit the same verb / cache, which is almost never intended and makes the contract ambiguous. Move the extra function to its own `.server.ts` file (the one-function-per-file convention), or, if it is a private helper, do not export it. Files with no verb config are unaffected.',
   },
-  {
-    name: 'no-scaffold-placeholder',
-    description:
-      'The one sentinel-based check, and the deliberate exception to the "objectively broken code" framing of the other rules: it flags scaffold example content that has not been replaced, so a delivered app contains only what the user intended and never leftover scaffold code. `webjs create` marks its example/demo files (the example homepage in app/page.ts, the example app chrome in app/layout.ts) with a one-line marker comment carrying the literal token `webjs-scaffold-placeholder`. The rule scans raw source (the marker lives in a comment, which the redacted scan view would hide) and fails for every file that still carries the token. A freshly scaffolded app fails this rule BY DESIGN until its placeholders are addressed: replace the example content, or deliberately keep it, and in either case delete the marker line. No finished app legitimately ships a literal remove-me marker, so this still qualifies as a check rather than a convention. The marker is acknowledge-and-remove, so keeping a piece is a one-line deletion rather than a forced rewrite.',
-  },
   {
     name: 'no-redirect-in-api-route',
     description:
@@ -668,27 +663,6 @@ export async function checkConventions(appDir) {
     }
   }
 
-  // --- Rule: no-scaffold-placeholder ---
-  // `webjs create` marks its example/demo files (app/page.ts, app/layout.ts)
-  // with a one-line marker comment so a delivered app cannot silently ship
-  // leftover scaffold content. Scan RAW `content`: the marker lives in a
-  // comment, which the `scan` view redacts to whitespace. One violation per
-  // still-marked file. The token is assembled here so this source does not
-  // itself carry the contiguous literal.
-  {
-    const MARKER = 'webjs-scaffold-' + 'placeholder';
-    for (const { rel, content } of files) {
-      if (!content.includes(MARKER)) continue;
-      violations.push({
-        rule: 'no-scaffold-placeholder',
-        file: rel,
-        message:
-          'Scaffold placeholder marker still present. This file is unmodified example content from `webjs create`, and the delivered app should contain only what the user intended, not leftover scaffold code.',
-        fix: `Replace the example content (or deliberately keep it), then delete the marker comment line carrying the ${MARKER} token.`,
-      });
-    }
-  }
-
   // --- Rule: no-redirect-in-api-route ---
   // `redirect()` from `@webjsdev/core` throws a control-flow signal designed
   // for the SSR page renderer. In a `route.ts` API handler it goes uncaught
@@ -1219,11 +1193,12 @@ export async function checkConventions(appDir) {
   // --- Rule: no-server-import-in-browser-module ---
   // A page / layout / component module that SHIPS to the browser must not
   // transitively import a server-only `.server.{ts,js}` module. The browser
-  // gets a stub for the server file, so the import is harmless while the page
-  // is display-only and the framework ELIDES it (its server import is stripped
-  // from the served source). But the moment the page also does client work
-  // (imports a component to register, enables the client router, uses a
-  // reactive primitive, …) it stops being elided, must load in the browser,
+  // gets a stub for the server file, so the import is harmless while the
+  // module never loads client-side: a display-only page is elided, and an
+  // import-only page (#605/#963) is dropped from the boot in favour of its
+  // components. But the moment the page does its OWN client work (the client
+  // router, a reactive primitive, module-scope code, a client-effecting util
+  // on a component-free path) it ships whole, must load in the browser,
   // and drags the server import with it: the stub throws (or a server-only
   // export like `auth` is missing) the instant the module loads. That crash
   // only surfaces at runtime; typecheck and every other check pass.
@@ -1425,21 +1400,25 @@ async function checkServerImportInBrowserModule(appDir, violations) {
   // rule treats every candidate as shipping (which is correct: with elision
   // off, a display-only page really does ship its server import too).
   const elideEnabled = await readElideEnabledForCheck(appDir);
-  const { elidableComponents, inertRouteModules } = elideEnabled
+  const { elidableComponents, inertRouteModules, importOnlyRouteModules } = elideEnabled
     ? await analyzeElision(components, routeModules, moduleGraph, (f) => readFile(f, 'utf8'), appDir)
-    : { elidableComponents: new Set(), inertRouteModules: new Set() };
+    : { elidableComponents: new Set(), inertRouteModules: new Set(), importOnlyRouteModules: new Map() };
 
   // Candidate browser-shipped modules: components that are NOT elided, plus
-  // route modules that are NOT inert. A `.server.*` file is never a component
-  // (the scanner skips it) nor a route module the browser loads, so it cannot
-  // enter this set; server-to-server imports are excluded by construction.
+  // route modules that are NOT inert and NOT import-only (an import-only
+  // module is dropped from the boot in favour of its component frontier,
+  // #605/#963, so its own imports never load in a browser and a bare
+  // server-only import in it is harmless). A `.server.*` file is never a
+  // component (the scanner skips it) nor a route module the browser loads, so
+  // it cannot enter this set; server-to-server imports are excluded by
+  // construction.
   /** @type {Map<string, { kind: string }>} relFile is keyed by ABS path */
   const candidates = new Map();
   for (const c of components) {
     if (!elidableComponents.has(c.file)) candidates.set(c.file, { kind: 'component' });
   }
   for (const file of routeModules) {
-    if (inertRouteModules.has(file)) continue;
+    if (inertRouteModules.has(file) || importOnlyRouteModules.has(file)) continue;
     const base = basename(file);
     const kind = /^layout\./.test(base) ? 'layout' : 'page';
     candidates.set(file, { kind });
@@ -1496,17 +1475,20 @@ async function checkServerImportInBrowserModule(appDir, violations) {
     const importer = chainFiles.length >= 2 ? chainFiles[chainFiles.length - 2] : null;
     const viaTypesModule = importer && /(^|\/)types(\.m?[jt]s$|\/)/.test(relative(appDir, importer));
 
-    // The "register the component in a layout so it elides again" remedy only
-    // applies to a page / layout, which CAN elide (it became browser-bound by
-    // importing a component). The error / loading / not-found boundaries always
-    // ship and are never elided, so offering them an "elides again" fix is
-    // wrong. Branch the fix text on whether the kind can elide.
+    // The "elides again" remedy only applies to a page / layout: since the
+    // path-aware import-only verdict (#963), a page importing a component to
+    // register is dropped from the boot, so a page/layout on this rule ships
+    // because of its OWN client work (or a client-effecting non-component in
+    // its closure); moving that work into a component makes it a dropped
+    // carrier again and the server import never loads. The error / loading /
+    // not-found boundaries always ship and are never elided, so offering
+    // them an "elides again" fix is wrong. Branch the fix text on kind.
     const canElide = kind === 'page' || kind === 'layout';
     const typesHint = viaTypesModule
       ? `The edge enters via a types-shaped module (${relative(appDir, importer)}); if it re-exports a runtime VALUE from a \`.server.{ts,js}\` file, relocate that to a browser-safe typedef (a plain \`interface\` / JSDoc, or an \`import type\` which the stripper erases) so the type is shared without pinning the module. `
       : '';
     const fixText = canElide
-      ? `${typesHint}Keep the server call off this browser-shipped ${kind}. Options: (1) gate the route in \`middleware.ts\` (runs server-side, never ships); (2) move the server-only call behind a \`'use server'\` action in a \`.server.{ts,js}\` file and call it as an RPC; or (3) if this ${kind} only became browser-bound because it imports a component to register, register that component in a \`layout.{ts,js}\` instead so the ${kind} elides again and its server import is stripped.`
+      ? `${typesHint}Keep the server call off this browser-shipped ${kind}. Options: (1) gate the route in \`middleware.ts\` (runs server-side, never ships); (2) move the server-only call behind a \`'use server'\` action in a \`.server.{ts,js}\` file and call it as an RPC; or (3) move this ${kind}'s own client work (the module-scope call, browser-global access, or client-effecting util import that pins it) into a component, so the ${kind} elides again as a dropped carrier and its server import never loads.`
       : `${typesHint}Keep the server call off this browser-shipped ${kind} (it always ships and is never elided). Options: (1) gate the route in \`middleware.ts\` (runs server-side, never ships); or (2) move the server-only call behind a \`'use server'\` action in a \`.server.{ts,js}\` file and call it as an RPC.`;
 
     violations.push({

package/src/component-elision.js

@@ -93,7 +93,7 @@ export const REACTIVE_IMPORTS = new Set([
  * defines `render`, and the SSR walker calls it directly. `constructor`
  * is absent for the same reason (it runs during SSR to seed first
  * paint). Keep this list in lockstep with the lifecycle table in
- * agent-docs/components.md.
+ * the skill's references/components.md.
  *
  * @type {readonly string[]}
  */
@@ -134,25 +134,28 @@ export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'reques
  * `lifecycle-coverage.test.js` via prototype introspection), there is no
  * enumerable runtime source of "all static conventions", so the contract is
  * a documented one: a new interactivity static field MUST be added here AND
- * to the lifecycle table in agent-docs/components.md. `sigil-coverage.test.js`
+ * to the lifecycle table in the skill's references/components.md. `sigil-coverage.test.js`
  * asserts each entry is honoured as a ship signal.
  *
  *   - `shadow`: Declarative Shadow DOM attaches ONLY during HTML parsing, so a
  *     component that arrives via a client DOM insertion (a soft-nav swap, a
  *     streamed <webjs-suspense> boundary's replaceWith) would never re-attach
  *     its shadow root if elided. Context-free, so any shadow component ships.
- *   - `refresh`: `static refresh = true` is the explicit opt-in to ship a bare
- *     async component so its stale-while-revalidate refresh runs after SSR;
- *     eliding drops that on-load re-fetch (moot for request-stable data).
+ *   - `interactive`: `static interactive = true` is the explicit author
+ *     override that forces a component to ship even when the analyser would
+ *     elide it. It is the escape hatch for interactivity the analyser cannot
+ *     see statically (a dynamically-computed tag string, a `:defined` rule in
+ *     an external stylesheet outside the module graph). Context-free: any value
+ *     other than `false` ships.
  *
  * @type {readonly string[]}
  */
-export const INTERACTIVITY_STATIC_FIELDS = ['shadow', 'refresh'];
+export const INTERACTIVITY_STATIC_FIELDS = ['shadow', 'interactive'];
 
 /** Why each INTERACTIVITY_STATIC_FIELDS entry forces a ship (analyser reason). */
 const STATIC_FIELD_REASONS = {
   shadow: 'declares static shadow (DSD must re-attach on a client swap)',
-  refresh: 'declares static refresh = true (keeps the on-load re-fetch)',
+  interactive: 'declares static interactive = true (author-declared ship override)',
 };
 
 /**
@@ -163,14 +166,14 @@ const STATIC_FIELD_REASONS = {
  * module download plus a redundant on-hydration re-fetch. It ships only when
  * it ALSO carries an independent signal: an `@event`, a non-`state` reactive
  * prop, a reactive import, a lifecycle hook (`renderFallback()` included, via
- * CLIENT_LIFECYCLE_HOOKS), a `<slot>`, `static shadow = true`, `static refresh
- * = true`, cross-module observation, or a transitively-reachable interactive
- * dep / child (the fixpoint's import + render rules). The two genuinely new
- * carve-outs, both handled per-class below, are `static shadow` (Declarative
- * Shadow DOM only attaches during HTML parsing, so a streamed / soft-navigated
- * shadow component needs its module to re-run `attachShadow`) and the explicit
- * `static refresh = true` opt-in (keeps the stale-while-revalidate on-load
- * re-fetch that eliding would drop).
+ * CLIENT_LIFECYCLE_HOOKS), a `<slot>`, `static shadow = true`, `static
+ * interactive = true`, cross-module observation, or a transitively-reachable
+ * interactive dep / child (the fixpoint's import + render rules). The two
+ * per-class static-field carve-outs handled below are `static shadow`
+ * (Declarative Shadow DOM only attaches during HTML parsing, so a streamed or
+ * soft-navigated shadow component needs its module to re-run `attachShadow`)
+ * and the explicit `static interactive = true` override (forces a ship when
+ * the analyser cannot see a component's interactivity statically).
  */
 
 /**
@@ -445,7 +448,7 @@ function importsClientRouter(src, literals) {
  * `customElements.define` at module top level) imported via a binding clause
  * is NOT caught here, so eliding the importer drops that registration and the
  * element silently does not upgrade. This is the cross-module-registration
- * caveat documented in agent-docs/components.md and server AGENTS invariant 7;
+ * caveat documented in the skill's references/components.md and server AGENTS invariant 7;
  * the fix is `.server.{js,ts}` for genuinely server-only deps, or an
  * interactivity signal on the consumer. (It is not caught by an SSR crash:
  * the SSR `customElements` shim makes `define` a no-op server-side.)
@@ -564,8 +567,8 @@ export function analyzeComponentSource(src) {
 
   for (const { body, factoryArg } of bodies) {
     // Interactivity-signal static conventions (`static shadow` / `static
-    // refresh = true`), driven by the INTERACTIVITY_STATIC_FIELDS registry so a
-    // new convention is added in one place (see its doc for why each ships).
+    // interactive = true`), driven by the INTERACTIVITY_STATIC_FIELDS registry
+    // so a new convention is added in one place (see its doc for why each ships).
     for (const field of INTERACTIVITY_STATIC_FIELDS) {
       if (declaresStaticTrue(body, field)) {
         return { interactive: true, reason: STATIC_FIELD_REASONS[field] };
@@ -598,23 +601,23 @@ export function analyzeComponentSource(src) {
 /**
  * True if a class body declares a `static <name>` whose value is not the
  * literal `false`. Backs the `static shadow` (DSD-on-client-swap) and
- * `static refresh = true` (ship-the-async-refetch opt-in) ship signals (#474).
+ * `static interactive = true` (author-declared ship override) ship signals.
  *
  * Conservative on anything it cannot evaluate: a getter form
  * (`static get <name>()`) ships, and a non-`false` value of any shape
  * (`true`, a variable, an expression) ships. Only an absent declaration or a
  * literal `= false` is cleared as inert, matching the light-DOM /
- * no-refresh defaults.
+ * not-declared defaults.
  *
  * @param {string} classBody  redacted class body
- * @param {string} name       the static field name (`shadow` / `refresh`)
+ * @param {string} name       the static field name (`shadow` / `interactive`)
  * @returns {boolean}
  */
 function declaresStaticTrue(classBody, name) {
   // A getter cannot be evaluated statically; ship.
   if (new RegExp(`\\bstatic\\s+get\\s+${name}\\b`).test(classBody)) return true;
   const m = new RegExp(`\\bstatic\\s+${name}\\b\\s*=\\s*([^;\\n]*)`).exec(classBody);
-  if (!m) return false; // not declared: the default (light DOM / no refresh)
+  if (!m) return false; // not declared: the default (light DOM / not forced)
   return !/^false\b/.test(m[1].trim()); // `= false` is inert; anything else ships
 }
 
@@ -1135,16 +1138,24 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
   //   - INERT: neither the module nor its closure does any client work. Dropped
   //     from the boot script entirely (#179).
   //   - IMPORT-ONLY (#605): the module itself does no client work, and the ONLY
-  //     client work its closure reaches is SHIPPING COMPONENTS. Such a page /
-  //     layout module is just the import-graph carrier for its components; the
-  //     boot can emit those component modules directly and drop the module. The
-  //     condition is a positive subset test (every client-effecting closure
-  //     member is a component), NOT a hand-listed block list: any client-
-  //     effecting NON-component in the closure (a self-executing helper, a
-  //     client-router import, a reactive helper) keeps the whole module, since
-  //     dropping it would lose that side effect.
+  //     client work its closure reaches is SHIPPING COMPONENTS (or modules
+  //     those components carry). Such a page / layout module is just the
+  //     import-graph carrier for its components; the boot can emit those
+  //     component modules directly and drop the module.
   //   - SHIP: anything else (the module itself is client-effecting, or its
-  //     closure reaches a client-effecting non-component). Unchanged behaviour.
+  //     closure reaches a client-effecting non-component through a path that
+  //     does NOT pass through a shipping component). Unchanged behaviour.
+  //
+  // The walk is PATH-AWARE (#963): it stops descending at a shipping
+  // component, because that component is emitted in the module's place, so
+  // its whole subtree loads regardless of whether the page module ships.
+  // Consequently a client-effecting non-component reachable ONLY through
+  // shipping components (the module-scope-signal-in-its-own-file idiom of
+  // invariant 5, imported by a component the page renders) does not block
+  // import-only: dropping the page loses nothing, the emitted component
+  // still imports it. A client-effecting non-component reachable through a
+  // component-free path still ships the whole module, since dropping it
+  // would lose that side effect.
   /** @type {Set<string>} */
   const skip = new Set([...elidableComponents, ...serverFiles]);
   /** @type {Set<string>} */
@@ -1163,28 +1174,57 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
       shippedRouteModules.set(file, { blocker: null, reason: clientEffectReason(file) });
       continue;
     }
-    const closure = appDir ? transitiveDeps(moduleGraph, [file], appDir, skip) : [];
-    const effecting = closure.filter(isClientEffecting);
-    if (effecting.length === 0) { inertRouteModules.add(file); continue; }
-    // Import-only iff EVERY client-effecting closure member is a (shipping)
-    // component. isClientEffecting for a component already implies mustShip, so
-    // `effecting` is exactly the shipping components reachable from this module:
-    // re-emit that STATIC set (what loading the module would have registered, so
-    // a component imported but only conditionally rendered still registers).
+    // Truncated walk (path-aware, #963): BFS the module's import graph, but
+    // do NOT descend into shipping components (they are emitted in the
+    // module's place, so their subtrees load regardless). Collect those
+    // frontier components as the emit set: what loading the module would
+    // have registered, so a component imported but only conditionally
+    // rendered still registers. Skip elided components and server files
+    // exactly like transitiveDeps (they never load client-side; a stub is
+    // served instead). Non-appDir deps (core, vendor) are traversed but
+    // never classified, matching the old closure's appDir restriction.
     //
-    // A `static lazy` component is NOT special-cased here: it only appears in
-    // this STATIC closure when the route statically imports it, and in that case
-    // loading the module already eager-loaded it before elision, so emitting it
-    // directly preserves that exact behaviour. A normally-used lazy component is
-    // tag-referenced (never statically imported), so it is absent from this
-    // closure and still loads via the IntersectionObserver `observeLazy` path.
-    if (effecting.every((f) => componentFiles.has(f))) {
-      importOnlyRouteModules.set(file, effecting);
-    } else {
-      // A client-effecting non-component is reachable; ship the whole module.
-      // Name the FIRST such non-component as the blocker for the advisory.
-      const blocker = effecting.find((f) => !componentFiles.has(f));
+    // A `static lazy` component is NOT special-cased here: it only appears
+    // on this STATIC walk when the route statically imports it, and in that
+    // case loading the module already eager-loaded it before elision, so
+    // emitting it directly preserves that exact behaviour. A normally-used
+    // lazy component is tag-referenced (never statically imported), so it
+    // is absent from this walk and still loads via the IntersectionObserver
+    // `observeLazy` path.
+    /** @type {Set<string>} shipping components to emit in the module's place */
+    const frontier = new Set();
+    /** @type {string|null} first client-effecting non-component on a component-free path */
+    let blocker = null;
+    if (appDir) {
+      const visited = new Set([file]);
+      const queue = [file];
+      while (queue.length) {
+        const cur = /** @type {string} */ (queue.shift());
+        const deps = moduleGraph.get(cur);
+        if (!deps) continue;
+        for (const dep of deps) {
+          if (visited.has(dep)) continue;
+          visited.add(dep);
+          // Elided components and appDir server files are in `skip`;
+          // SERVER_FILE_RE additionally stops at a `.server.*` OUTSIDE appDir
+          // (a relative import escaping the app dir), exactly like
+          // transitiveDeps: the browser only ever sees its stub, so its
+          // subtree never loads and must not contribute a blocker.
+          if (skip.has(dep) || SERVER_FILE_RE.test(dep)) continue;
+          if (componentFiles.has(dep)) { frontier.add(dep); continue; } // emitted; subtree carried
+          if (dep.startsWith(appDir) && isClientEffecting(dep)) blocker ??= dep;
+          queue.push(dep);
+        }
+      }
+    }
+    if (blocker !== null) {
+      // A client-effecting non-component is reachable on a component-free
+      // path; ship the whole module and name the blocker for the advisory.
       shippedRouteModules.set(file, { blocker, reason: clientEffectReason(blocker) });
+    } else if (frontier.size === 0) {
+      inertRouteModules.add(file);
+    } else {
+      importOnlyRouteModules.set(file, [...frontier]);
     }
   }
 

package/src/dev-regenerate.js

@@ -0,0 +1,234 @@
+/**
+ * On-request regeneration of a stale build output in dev (#967).
+ *
+ * A UI scaffold compiles a STATIC `public/tailwind.css` (#947) so the app is
+ * fully styled with JavaScript OFF (progressive enhancement, invariant 1). In
+ * prod that static file is built once by `start.before`. In DEV the classic
+ * shape was a long-lived `tailwindcss --watch` in `dev.parallel`, but a watch
+ * that dies mid-session, lags, or never starts (an app-dir relocation, a killed
+ * child) then serves STALE or MISSING CSS with no error: a newly added utility
+ * class has no backing rule, so the app renders unstyled locally while prod is
+ * fine, a confusing, hard-to-attribute regression.
+ *
+ * This module removes that foot-gun by regenerating the output ON REQUEST when
+ * it is stale, instead of relying on a live watch. It is deliberately GENERIC
+ * and styling-agnostic: it runs whatever command the app declares, keyed by the
+ * output path, so the framework stays BYO-styling (the Tailwind knowledge lives
+ * in the scaffold's `package.json` config, not here). It is DEV-ONLY; prod keeps
+ * the static build, so dev and prod resolve classes through the exact SAME
+ * command (`tailwindcss -i input.css -o tailwind.css`) and cannot diverge.
+ *
+ * Declared as `webjs.dev.regenerate` in the app's `package.json`:
+ *   "webjs": { "dev": { "regenerate": [
+ *     { "output": "public/tailwind.css",
+ *       "command": "tailwindcss -i ./public/input.css -o ./public/tailwind.css --minify",
+ *       "inputs": ["app", "components", "modules", "lib", "public/input.css"] }
+ *   ] } }
+ *
+ * When `/public/tailwind.css` is requested and the newest mtime under any of
+ * `inputs` is newer than the output (or the output is missing), `command` is run
+ * to completion BEFORE the file is served, so the response is always fresh.
+ * Concurrent requests coalesce onto one in-flight compile.
+ */
+
+import { spawn as nodeSpawn } from 'node:child_process';
+import { readFile, stat, readdir } from 'node:fs/promises';
+import { delimiter, dirname, join } from 'node:path';
+
+/**
+ * @typedef {{ output: string, command: string, inputs: string[] }} RegenerateRule
+ */
+
+/**
+ * Read + normalize the `webjs.dev.regenerate` rules from an app's
+ * `package.json`. Defensive: a missing/malformed block yields `[]` (a plain app
+ * runs unchanged). Each rule's `output` is normalized to an appDir-relative path
+ * with no leading slash so it matches a served `/public/...` path after the
+ * slash is stripped.
+ *
+ * @param {string} appDir
+ * @param {(p: string) => Promise<string>} [read] injectable reader for tests
+ * @returns {Promise<RegenerateRule[]>}
+ */
+export async function readRegenerateRules(appDir, read) {
+  const readFn = read || ((p) => readFile(p, 'utf8'));
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFn(join(appDir, 'package.json')));
+  } catch {
+    return [];
+  }
+  const rules = pkg && pkg.webjs && pkg.webjs.dev ? pkg.webjs.dev.regenerate : null;
+  if (!Array.isArray(rules)) return [];
+  return rules
+    .filter((r) => r && typeof r.output === 'string' && typeof r.command === 'string')
+    .map((r) => ({
+      output: r.output.replace(/^\/+/, ''),
+      command: r.command,
+      inputs: Array.isArray(r.inputs) ? r.inputs.filter((i) => typeof i === 'string') : [],
+    }));
+}
+
+// Directories never worth walking for a source-freshness check: build output,
+// dependencies, VCS + framework caches. Skipping them keeps the walk cheap and
+// avoids treating a dependency's mtime as an app-source edit.
+const IGNORE_DIRS = new Set(['node_modules', '.git', '.webjs', 'dist', '.next', 'coverage']);
+
+/**
+ * Newest mtime (ms) of any FILE under a path: the file's own mtime, or the max
+ * over the files in a directory tree (skipping IGNORE_DIRS and dotfiles). A
+ * missing path is 0, so it never makes the output look stale.
+ *
+ * Directory-node mtimes are deliberately NOT counted: a directory's mtime bumps
+ * on a file add/remove but NOT on a content edit, so a content edit (the case
+ * that matters, a new utility class in an existing file) is only visible through
+ * the FILE mtime. Counting a new file's own mtime still catches an addition;
+ * only a pure deletion is missed, which is harmless (stale rules self-heal on
+ * the next real edit) and keeps the freshness check deterministic (a directory
+ * mtime is a moving target that made the comparison flaky across runtimes).
+ * Pure I/O, no throw.
+ *
+ * @param {string} abs
+ * @returns {Promise<number>}
+ */
+async function maxMtimeMs(abs) {
+  let st;
+  try {
+    st = await stat(abs);
+  } catch {
+    return 0;
+  }
+  if (!st.isDirectory()) return st.mtimeMs;
+  let newest = 0;
+  let entries;
+  try {
+    entries = await readdir(abs, { withFileTypes: true });
+  } catch {
+    return newest;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith('.') || IGNORE_DIRS.has(e.name)) continue;
+    // Skip symlinks entirely: following one can cycle (a link back to an
+    // ancestor) into unbounded recursion, or escape into node_modules via a
+    // renamed link. A symlinked source file is rare in an app tree; not
+    // counting its mtime is a safe tradeoff for a walk that cannot hang.
+    if (e.isSymbolicLink()) continue;
+    const m = await maxMtimeMs(join(abs, e.name));
+    if (m > newest) newest = m;
+  }
+  return newest;
+}
+
+/**
+ * Build a PATH that prepends every ancestor `node_modules/.bin` (mirrors
+ * `lib/run-tasks.js`'s `envWithLocalBin`), so a command naming a LOCAL-only
+ * binary (`tailwindcss`) resolves the same way `npm run` would.
+ *
+ * @param {string} cwd
+ * @returns {NodeJS.ProcessEnv}
+ */
+function envWithLocalBin(cwd) {
+  const bins = [];
+  let dir = cwd;
+  for (;;) {
+    bins.push(join(dir, 'node_modules', '.bin'));
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { ...process.env, PATH: [...bins, process.env.PATH || ''].join(delimiter) };
+}
+
+/**
+ * Run a regenerate command to completion. Never rejects (a compile failure is
+ * logged by the tool's own inherited stderr; the caller then serves whatever is
+ * on disk, degrading to the previous behaviour rather than 500ing the request).
+ *
+ * @param {string} command
+ * @param {string} cwd
+ * @param {typeof nodeSpawn} spawn
+ * @returns {Promise<void>}
+ */
+function runCommand(command, cwd, spawn) {
+  return new Promise((resolve) => {
+    const child = spawn(command, { shell: true, stdio: 'inherit', cwd, env: envWithLocalBin(cwd) });
+    child.on('exit', () => resolve());
+    child.on('error', () => resolve());
+  });
+}
+
+// In-flight compiles, keyed by appDir + output, so concurrent requests for the
+// same stale output share ONE compile instead of racing N of them. Module-scope
+// (not per-handler): the filesystem is the shared resource being guarded.
+const inFlight = new Map();
+
+/**
+ * If a regenerate rule matches `relPath` and its output is stale (older than the
+ * newest input, or missing), run the rule's command to completion before
+ * returning, so the caller serves a fresh file. A no-op when no rule matches or
+ * the output is already fresh. Concurrent calls for the same output coalesce.
+ *
+ * @param {string} appDir
+ * @param {string} relPath  appDir-relative served path, no leading slash (e.g. `public/tailwind.css`)
+ * @param {RegenerateRule[]} rules
+ * @param {{ spawn?: typeof nodeSpawn }} [opts] injectable spawn for tests
+ * @returns {Promise<void>}
+ */
+export async function maybeRegenerate(appDir, relPath, rules, opts = {}) {
+  const rule = rules && rules.find((r) => r.output === relPath);
+  if (!rule) return;
+  const key = appDir + '\0' + rule.output;
+  const pending = inFlight.get(key);
+  if (pending) return pending;
+
+  const spawn = opts.spawn || nodeSpawn;
+  const run = (async () => {
+    const outAbs = join(appDir, rule.output);
+    let outMtime = 0;
+    try {
+      outMtime = (await stat(outAbs)).mtimeMs;
+    } catch {
+      outMtime = 0; // missing output: always stale
+    }
+    if (outMtime !== 0) {
+      let newestSrc = 0;
+      for (const inp of rule.inputs) {
+        const m = await maxMtimeMs(join(appDir, inp));
+        if (m > newestSrc) newestSrc = m;
+      }
+      if (newestSrc <= outMtime) return; // fresh, nothing to do
+    }
+    await runCommand(rule.command, appDir, spawn);
+  })();
+  inFlight.set(key, run);
+  try {
+    await run;
+  } finally {
+    inFlight.delete(key);
+  }
+}
+
+/**
+ * Whether a dev-watcher filename is a regenerate OUTPUT (#967). A regenerate
+ * output is a build product the dev server itself writes on request, so a write
+ * to it must NOT trigger a rebuild + SSE reload: that would spuriously reload
+ * the page mid-navigation (breaking a soft-nav / streaming interaction) and,
+ * worse, could reload -> refetch -> recompile -> reload. Same rationale as the
+ * `db/dev.db` carve-out in `shouldIgnoreWatchPath`. `fs.watch` reports a path
+ * relative to the watched root with OS separators, so it is normalized to `/`
+ * before matching the rule's already-normalized `output`.
+ *
+ * @param {string} filename  `event.filename` from the dev watcher (root-relative)
+ * @param {RegenerateRule[]} rules
+ * @returns {boolean}
+ */
+export function isRegenerateOutputPath(filename, rules) {
+  if (!filename || !rules || !rules.length) return false;
+  const norm = String(filename).replace(/\\/g, '/');
+  return rules.some((r) => r.output === norm);
+}
+
+/** Test-only: clear the in-flight coalescing map between cases. */
+export function _resetInFlight() {
+  inFlight.clear();
+}

package/src/dev.js

@@ -27,6 +27,7 @@ import {
   hashFile,
 } from './actions.js';
 import { registerSeedHooks } from './action-seed.js';
+import { readRegenerateRules, maybeRegenerate, isRegenerateOutputPath } from './dev-regenerate.js';
 import { stripTypeScript, ensureStripper } from './ts-strip.js';
 import { defaultLogger } from './logger.js';
 import { assertNodeVersion } from './node-version.js';
@@ -773,6 +774,11 @@ export async function createRequestHandler(opts) {
     // SSE channel for the live overlay and replayed to a freshly-connected tab.
     // Dev-only (never populated when !dev); cleared on a successful rebuild.
     lastDevError: null,
+    // On-request regeneration rules (#967): `webjs.dev.regenerate` from the app's
+    // package.json. Dev-only (prod builds its outputs via `start.before`). Loaded
+    // now and refreshed on each rebuild so a config edit takes effect without a
+    // restart; empty for a plain app, so the serving path is unaffected.
+    regenerateRules: dev ? await readRegenerateRules(appDir) : [],
   };
 
   /**
@@ -1121,6 +1127,10 @@ export async function createRequestHandler(opts) {
     readyDone = false;
     readyError = null;
     readinessFn = undefined; // reload readiness.{js,ts} after a rebuild
+    // Refresh the on-request regenerate rules (#967) so a `webjs.dev.regenerate`
+    // config edit takes effect without a restart, mirroring the elide/router
+    // re-reads above. Dev-only; a no-op array in prod.
+    if (dev) state.regenerateRules = await readRegenerateRules(appDir);
     // Optimistically clear the dev error (#264): the rebuild itself only
     // re-scans the route table and INVALIDATES the lazy analysis (the real
     // re-parse / re-strip / re-render happens on the next request), so we do
@@ -1522,6 +1532,11 @@ export async function createRequestHandler(opts) {
      * startServer to a freshly-connected SSE client so the overlay shows even
      * after a navigation, not only on the breaking edit. Always null in prod. */
     getLastDevError: () => state.lastDevError,
+    /** Whether a dev-watcher filename is a `webjs.dev.regenerate` OUTPUT (#967),
+     * so `startServer`'s file watcher (a different scope, with no access to
+     * `state`) can skip a build product the server itself writes and avoid a
+     * spurious reload. Reads the live, rebuild-refreshed rules. */
+    isRegenerateOutput: (filename) => isRegenerateOutputPath(filename, state.regenerateRules),
     appDir,
     dev,
     logger,
@@ -1646,6 +1661,12 @@ export async function startServer(opts) {
         for await (const event of events) {
           const filename = event.filename || '';
           if (shouldIgnoreWatchPath(filename)) continue;
+          // A regenerate output (#967) is a build product the server itself
+          // writes on request; ignoring it stops a spurious rebuild + reload
+          // (and a reload -> refetch -> recompile -> reload cycle), same as the
+          // db/dev.db carve-out above. `app` exposes the check because `state`
+          // lives in createRequestHandler's scope, not here.
+          if (app.isRegenerateOutput(filename)) continue;
           rebuild();
         }
       } catch (err) {
@@ -1984,6 +2005,15 @@ async function handleCore(req, ctx) {
     if (!abs.startsWith(publicRoot)) {
       return new Response(null, { status: 404 });
     }
+    // On-request regeneration (#967): in dev, if a `webjs.dev.regenerate` rule
+    // matches this output and it is stale (a source is newer, or it is missing),
+    // rebuild it to completion BEFORE serving, so a newly added utility class is
+    // never served stale. No-op when no rule matches or the output is fresh, and
+    // never runs in prod (rules are empty there). This replaces the fragile
+    // `tailwindcss --watch` that could die mid-session and serve stale CSS.
+    if (dev && state.regenerateRules.length) {
+      await maybeRegenerate(appDir, p.replace(/^\/+/, ''), state.regenerateRules);
+    }
     // A `?v=<hash>` public asset is content-addressed -> immutable (#243).
     if (await exists(abs)) {
       const res = await fileResponse(abs, { dev, immutable: versioned });

package/src/elision-report.js

@@ -6,8 +6,9 @@
  * run at dev-server start and re-derived after each fs.watch rebuild). It
  * builds the module graph, runs `analyzeElision`, and returns the page / layout
  * route modules that SHIP WHOLE to the browser, each with the first
- * client-effecting blocker that pins it (or its own signal when the module
- * itself is the cause).
+ * client-effecting blocker that pins it (a non-component on a component-free
+ * path from the module, #963, or its own signal when the module itself is
+ * the cause).
  *
  * Consumed by `webjs doctor` to ADVISE why a page/layout is not elided (an
  * import-only #605 / inert #179 carrier stays out of the browser; a module that

package/src/ssr.js

@@ -155,11 +155,13 @@ export async function ssrPage(route, params, url, opts) {
     // Import-only route modules (#605) go one step further: a page / layout
     // whose only client relevance is importing shipping components is itself
     // dead weight on the client (it never hydrates), so it is dropped and its
-    // component modules are emitted directly in its place. The component set is
-    // the STATIC closure the analyser computed (what loading the module would
-    // have registered), so a component imported but only conditionally rendered
-    // still registers. Dedup so a component shared across the page and a layout
-    // (or two layouts) is emitted once.
+    // component modules are emitted directly in its place. The component set
+    // is the FRONTIER of the analyser's path-aware walk (#963): the shipping
+    // components the module reaches without passing through another shipping
+    // component. A component imported but only conditionally rendered still
+    // registers; one nested behind an emitted component is absent here and
+    // loads via its importer's own imports. Dedup so a component shared
+    // across the page and a layout (or two layouts) is emitted once.
     const inert = opts.inertRouteModules;
     const importOnly = opts.importOnlyRouteModules;
     const moduleUrls = [];
@@ -329,8 +331,28 @@ export async function ssrPage(route, params, url, opts) {
         if (!mod.default) continue;
         const tree = await mod.default({ ...ctx, error: err });
         const body = await renderToString(tree, { ssr: true, dev: opts.dev });
-        const moduleUrls = [route.file, ...route.layouts].map((f) => toUrlPath(f, opts.appDir));
-        const html = wrapInDocument(body, { metadata, moduleUrls, dev: opts.dev, nonce: errNonce });
+        // Apply the SAME inert / import-only substitution as the happy-path
+        // boot (#963): the error page must not ship a page/layout module the
+        // normal render drops. Pre-substitution, an import-only page with a
+        // bare `.server.*` import (legal, it never loads client-side) would
+        // load here whole and crash the error page's boot on the throw-at-load
+        // stub, killing the sibling component registrations in the same
+        // module script.
+        const errModuleUrls = [];
+        {
+          const seen = new Set();
+          const push = (abs) => {
+            const u = toUrlPath(abs, opts.appDir);
+            if (!seen.has(u)) { seen.add(u); errModuleUrls.push(u); }
+          };
+          for (const f of [route.file, ...route.layouts]) {
+            if (opts.inertRouteModules && opts.inertRouteModules.has(f)) continue;
+            const emit = opts.importOnlyRouteModules && opts.importOnlyRouteModules.get(f);
+            if (emit) emit.forEach(push);
+            else push(f);
+          }
+        }
+        const html = wrapInDocument(body, { metadata, moduleUrls: errModuleUrls, dev: opts.dev, nonce: errNonce });
         return htmlResponse(html, 500, opts.req, url);
       } catch (nested) {
         // fall through to next error boundary

package/webjs-config.schema.json

@@ -160,7 +160,7 @@
       "default": 5000
     },
     "dev": {
-      "description": "Dev task orchestration (#550). Read by the CLI (readAppTasks in packages/cli/lib/app-tasks.js), NOT the server. webjs dev runs `before` (one-shot, e.g. webjs db migrate) to completion, then `parallel` (long-lived watchers, e.g. tailwindcss --watch) alongside the server. Replaces the old predev hook + concurrently watchers.",
+      "description": "Dev task orchestration (#550). `before`/`parallel` are read by the CLI (readAppTasks in packages/cli/lib/app-tasks.js); `regenerate` is read by the server (readRegenerateRules in dev-regenerate.js). webjs dev runs `before` (one-shot, e.g. webjs db migrate) to completion, then `parallel` (long-lived watchers) alongside the server. Replaces the old predev hook + concurrently watchers.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
@@ -174,6 +174,30 @@
           "type": "array",
           "items": { "type": "string" }
         },
+        "regenerate": {
+          "description": "On-request build-output regeneration (#967), DEV-ONLY. Each rule rebuilds a stale `output` before the server serves it, instead of relying on a live watcher that can die and serve stale output. The scaffold uses this to keep the static public/tailwind.css fresh (#947) with no `tailwindcss --watch`. Read by the server (readRegenerateRules in dev-regenerate.js).",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["output", "command"],
+            "properties": {
+              "output": {
+                "description": "The appDir-relative served output file this rule rebuilds (e.g. public/tailwind.css). A leading slash is stripped.",
+                "type": "string"
+              },
+              "command": {
+                "description": "The shell command that rebuilds `output`. Run to completion before serving when the output is stale. The same command prod uses in start.before, so dev and prod outputs cannot diverge.",
+                "type": "string"
+              },
+              "inputs": {
+                "description": "Source paths (files or directories) whose newest mtime is compared to `output`'s. If any is newer (or the output is missing), the command runs. For Tailwind: the @source dirs plus public/input.css.",
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        },
         "watch": {
           "description": "Extra directories the dev live-reload watcher follows in addition to the appDir (#894), for content the app reads from outside its own tree (e.g. blog markdown in a repo-root blog/ dir). Each entry is resolved relative to the app root and may escape it (../blog). Read by the server (readDevWatchPathsFromApp).",
           "type": "array",