@webjsdev/server 0.8.49 → 0.8.51

package/package.json

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

package/src/check.js

@@ -7,7 +7,7 @@ import {
   matchClosingBrace,
   parsePropEntries,
 } from './js-scan.js';
-import { buildModuleGraph, transitiveDeps } from './module-graph.js';
+import { buildModuleGraph, transitiveDeps, resolveImport } from './module-graph.js';
 import { scanComponents } from './component-scanner.js';
 import { buildRouteTable } from './router.js';
 import { analyzeElision } from './component-elision.js';
@@ -122,7 +122,7 @@ 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',
@@ -144,6 +144,11 @@ export const RULES = [
     description:
       'Flags a template interpolation (`${...}`) placed as a child of a `<style>` or `<script>` element inside a COMPONENT `html` template. Raw-text elements are an SSR/client asymmetry trap: the server renderer emits the interpolated content, but the client renderer drops it (a raw-text hole is a `noop`, since the compile cache is keyed on the static strings), so the element renders correctly on the server and then wipes to empty on hydration. Scoped to components (files with a `WebComponent` class), which hydrate; pages and layouts render server-only and never hydrate, so a page interpolating a `css` result into a `<style>` is a legitimate pattern and is not flagged. In a component, author scoped CSS with `static styles` (shadow DOM) or a `css` template. Found dogfooding a tic-tac-toe app (#845): a `<style>${STYLE}</style>` painted at SSR then vanished on hydrate.',
   },
+  {
+    name: 'no-missing-local-import',
+    description:
+      'Flags a NAMED value import of a symbol that a resolvable app-internal module does not export (`import { todos } from \'#db/schema.server.ts\'` when the schema no longer exports `todos`). The binding is `undefined` at runtime and crashes on first use, yet the rest of `webjs check` (elision-based, it does not compile types) misses it, so a schema swap that orphans a gallery module can pass `check` while `typecheck` is red. This is the runtime-crash class `check` exists to catch, filling that gap so an agent running only `check` cannot ship a broken import. Deliberately conservative to never false-positive on a valid app: it only inspects app-internal specifiers (a relative `./` path or a `#` alias) that resolve to a file in the app, only NAMED value imports (a `type` import, a default import, a namespace import, and any bare / `node:` / npm-package specifier are skipped), and it treats a module as UNKNOWABLE (never flags imports from it) when its exports are not fully enumerable: a `export * from ...` star re-export, a destructuring `export const { a } = ...`, or a multi-declarator `export const a = .., b = ..`. It reads names from `export function/class/const/let/var/type/interface/enum` and from `export { a, b as c }` / `export { x } from ...` clauses (the alias after `as` is the exported name). A re-export barrel therefore resolves correctly, and a `\'use server\'` action file exports its function names normally. Found dogfooding a tic-tac-toe app: dropping the example `todos` table left a gallery module importing it, green under `check` but red under `typecheck`.',
+  },
 ];
 
 /** Set of all known rule names for fast lookup. */
@@ -379,6 +384,112 @@ function findBrowserMemberUses(code) {
   return out;
 }
 
+/**
+ * True if any `export const/let/var` declares more than one binding
+ * (`export const a = 1, b = 2`), which the single-name collector would
+ * under-count. Depth-aware: a comma inside an initializer (`f(a, b)`, `[a, b]`,
+ * `{ a, b }`) does not count, only a top-level comma before the statement end.
+ * Bailing the whole module on this errs toward a false negative (safe), never a
+ * false positive. Runs on the string/comment-redacted `scan`.
+ * @param {string} scan
+ * @returns {boolean}
+ */
+function hasMultiDeclaratorExport(scan) {
+  const re = /\bexport\s+(?:const|let|var)\b/g;
+  let m;
+  while ((m = re.exec(scan))) {
+    let depth = 0;      // () [] {} nesting
+    let angle = 0;      // <> generics, tracked ONLY inside a type annotation
+    let seenEq = false; // passed this declarator's `=` (now in the initializer)
+    let inType = false; // inside a `: Type` annotation (before the `=`)
+    for (let i = m.index + m[0].length; i < scan.length; i++) {
+      const ch = scan[i];
+      if (ch === '(' || ch === '[' || ch === '{') { depth++; continue; }
+      if (ch === ')' || ch === ']' || ch === '}') { if (depth === 0) break; depth--; continue; }
+      if (depth !== 0) continue;
+      if (ch === ';') break;
+      // A plain `=` ends the type annotation and enters the initializer. `<=`,
+      // `>=`, `=>`, `==` are harmless here (seenEq only latches true).
+      if (ch === '=') { seenEq = true; inType = false; angle = 0; continue; }
+      // A `:` BEFORE the `=` opens the type annotation. A `:` after `=` (a
+      // ternary in the initializer) is NOT a type and must not suppress a real
+      // declarator comma.
+      if (ch === ':' && !seenEq) { inType = true; continue; }
+      // Inside a type annotation `<` / `>` are generic delimiters (a comparison
+      // only appears in the initializer, after `=`). Track their depth so a
+      // generic's comma (`Map<string, number>`) is skipped while a real
+      // declarator comma (`a: number, b: number`) still counts. A `>` that is
+      // part of a `=>` function-type arrow is not a generic close.
+      if (inType && ch === '<') { angle++; continue; }
+      if (inType && ch === '>' && scan[i - 1] !== '=') { if (angle > 0) angle--; continue; }
+      // A top-level comma starts a second declarator UNLESS it is a generic's
+      // comma inside a type annotation.
+      if (ch === ',' && !(inType && angle > 0)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Enumerate a module's provable named exports from its redacted `scan`, for the
+ * `no-missing-local-import` rule. Returns `null` when the export list is NOT
+ * fully enumerable (a `export *` star re-export, a destructuring export, or a
+ * multi-declarator `export const a = .., b = ..`), which tells the rule to treat
+ * the module as unknowable and flag nothing from it. Otherwise returns the set
+ * of exported names (the alias after `as` for a clause, and type/interface/enum
+ * names too, so a value import of a type is not falsely flagged; tsc owns that).
+ * @param {string} scan  string/template/comment-redacted source
+ * @returns {Set<string>|null}
+ */
+function enumerableExports(scan) {
+  // Unknowable export shapes: bail so the rule never false-positives.
+  if (/\bexport\s*\*/.test(scan)) return null;                       // export * from
+  if (/\bexport\s+(?:const|let|var)\s*[{[]/.test(scan)) return null; // destructuring export
+  if (hasMultiDeclaratorExport(scan)) return null;                   // export const a=1, b=2
+  const names = new Set();
+  let m;
+  const collect = (re) => { while ((m = re.exec(scan))) names.add(m[1]); };
+  collect(/\bexport\s+(?:async\s+)?function\b\s*\*?\s*([A-Za-z_$][\w$]*)/g);
+  collect(/\bexport\s+(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/g);
+  collect(/\bexport\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/g);
+  collect(/\bexport\s+(?:type|interface|enum|namespace)\s+([A-Za-z_$][\w$]*)/g);
+  // A named-default import (`import { default as Foo }`) is legal against an
+  // `export default` module, so record the `default` name when present.
+  if (/\bexport\s+default\b/.test(scan)) names.add('default');
+  // `export { a, b as c }` / `export type { ... }` / `export { x } from '...'`:
+  // the EXPORTED name is the alias after `as`, else the bare name.
+  const reClause = /\bexport\s+(?:type\s+)?\{([^}]*)\}/g;
+  while ((m = reClause.exec(scan))) {
+    for (let part of m[1].split(',')) {
+      part = part.trim().replace(/^type\s+/, '');
+      if (!part) continue;
+      const name = part.split(/\s+as\s+/).pop().trim();
+      if (/^[A-Za-z_$][\w$]*$/.test(name)) names.add(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * The NAMED VALUE names a single `import { ... } from` clause pulls in, for the
+ * `no-missing-local-import` rule. Returns `null` for an `import type { ... }`
+ * (all type, skip), and `[]` for a default / namespace / side-effect import
+ * (nothing named to verify). A per-specifier inline `type` marker is dropped,
+ * and for `a as b` the IMPORTED name is `a` (what the target must export).
+ * @param {string} clause  the text between `import` and `from`
+ * @returns {string[]|null}
+ */
+function importedValueNames(clause) {
+  if (/^\s*type\b/.test(clause)) return null; // import type { ... }
+  const brace = clause.match(/\{([^}]*)\}/);
+  if (!brace) return []; // default / namespace only
+  return brace[1].split(',')
+    .map((s) => s.trim())
+    .filter((s) => s && !/^type\s/.test(s))
+    .map((s) => s.split(/\s+as\s+/)[0].trim())
+    .filter((n) => /^[A-Za-z_$][\w$]*$/.test(n));
+}
+
 /**
  * Scan a WebJs app directory and report convention violations.
  *
@@ -1108,11 +1219,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.
@@ -1125,6 +1237,59 @@ export async function checkConventions(appDir) {
   // directly, so it is not elided and ships the server import.
   await checkServerImportInBrowserModule(appDir, violations);
 
+  // --- Rule: no-missing-local-import ---
+  // A named value import of a symbol an app-internal module does not export is a
+  // runtime crash (the binding is undefined) that the elision-based checks miss,
+  // so `check` can stay green while `typecheck` is red (a dropped schema table
+  // orphaning a gallery module is the motivating dogfood case). Conservative by
+  // construction: only app-internal specifiers resolving to a known app file,
+  // only named value imports, and only when the target's exports are fully
+  // enumerable (see enumerableExports / importedValueNames).
+  {
+    // Fully-blanked view (blankStrings=true): string AND template AND comment
+    // bodies blank to spaces, position-preserving. The default `scan` keeps
+    // plain-string bodies VERBATIM (so callers can read `register('tag')`),
+    // which would let an `import`/`export` inside a string be matched, so use
+    // the fully-blanked view for both the export map and the import scan. The
+    // real specifier is read back from `content` at the same (length-preserved)
+    // offset.
+    const maskedByAbs = new Map();
+    for (const f of files) maskedByAbs.set(f.abs, redactStringsAndTemplates(f.content, true));
+    const exportsByAbs = new Map();
+    for (const f of files) exportsByAbs.set(f.abs, enumerableExports(maskedByAbs.get(f.abs)));
+    // `import\s+` excludes `import.meta` and a dynamic `import(`. The clause is
+    // `[^'";]*?` so it cannot swallow a side-effect `import '...'` (its quote) or
+    // bridge across a `;` into the next statement's `from`.
+    const reImport = /\bimport\s+([^'";]*?)\bfrom\s*(['"])/g;
+    for (const { abs, rel, content } of files) {
+      const masked = maskedByAbs.get(abs);
+      reImport.lastIndex = 0;
+      let m;
+      while ((m = reImport.exec(masked))) {
+        const quote = m[2];
+        const specStart = reImport.lastIndex;           // just past the opening quote
+        const specEnd = content.indexOf(quote, specStart);
+        if (specEnd < 0) continue;
+        const spec = content.slice(specStart, specEnd);
+        if (!/^(?:\.|#)/.test(spec)) continue; // app-internal only (relative or #alias)
+        const names = importedValueNames(m[1]);
+        if (!names || names.length === 0) continue;
+        const target = resolveImport(spec, abs, appDir);
+        const exp = exportsByAbs.get(target);
+        if (exp == null) continue; // not an app file, or exports not enumerable
+        for (const name of names) {
+          if (exp.has(name)) continue;
+          violations.push({
+            rule: 'no-missing-local-import',
+            file: rel,
+            message: `Imports \`${name}\` from \`${spec}\`, but that module does not export \`${name}\`. The binding is undefined at runtime and crashes on first use (often a renamed or removed export, e.g. a dropped schema table).`,
+            fix: `Add \`${name}\` to \`${spec}\`, correct the imported name, or remove the import.`,
+          });
+        }
+      }
+    }
+  }
+
   return violations;
 }
 
@@ -1261,21 +1426,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 });
@@ -1332,17 +1501,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

@@ -141,18 +141,21 @@ export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'reques
  *     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).
  */
 
 /**
@@ -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
@@ -1528,6 +1550,7 @@ function wrapHead(opts) {
 <html lang="en">
 <head>
 <meta charset="utf-8">
+<style${n}>@layer webjs-host{:where([data-wj-host]){display:block}:where([data-wj-host][hidden]:not([hidden='until-found'])){display:none}}</style>
 ${opts.nonce ? `<meta name="csp-nonce" content="${escapeAttr(opts.nonce)}">` : ''}
 ${metaTags.join('\n')}
 <title>${escapeHtml(title)}</title>

package/src/vendor.js

@@ -1176,9 +1176,16 @@ async function pruneOrphans(appDir, expected) {
  * instead. When the app has zero bare-specifier imports at all
  * (scanned source produced nothing), returns
  * `{ pins: [], pruned: [], downloaded: 0, noBareImports: true }`
- * WITHOUT writing the pin file. Callers that need to surface a
- * non-zero exit code key off `failed` or `noBareImports`; both
- * are absent on the success path.
+ * WITHOUT writing the pin file. When the scan DID find specifiers but
+ * every one was dropped because no local version resolved (the package
+ * is not installed under `node_modules`), returns
+ * `{ pins: [], pruned: [], downloaded: 0, droppedUnresolvable: [...] }`
+ * (also WITHOUT a pin file), so the caller can name the found-but-
+ * uninstalled specifiers instead of claiming there were none. A
+ * partial pin (some resolved, some dropped) still writes the file and
+ * carries `droppedUnresolvable` alongside `pins`. Callers that need to
+ * surface a non-zero exit code key off `failed`, `noBareImports`, or an
+ * all-dropped `droppedUnresolvable`; all are absent on a clean success.
  *
  * The `from` option mirrors importmap-rails's `bin/importmap pin foo
  * --from jsdelivr`. Default `jspm` resolves to jspm.io; other values
@@ -1196,6 +1203,7 @@ async function pruneOrphans(appDir, expected) {
  *   provider?: string,
  *   failed?: boolean,
  *   noBareImports?: boolean,
+ *   droppedUnresolvable?: string[],
  *   attemptedInstalls?: string[],
  * }>}
  */
@@ -1224,12 +1232,23 @@ export async function pinAll(appDir, opts = {}) {
    * @type {Map<string, { pkg: string, version: string, subpath: string }>}
    */
   const partsByInstall = new Map();
+  /**
+   * Bare specifiers the scan FOUND but that were dropped because no local
+   * version could be resolved (the package is not installed under the app's
+   * `node_modules`). Kept distinct from "scan found nothing" so the CLI can
+   * name them and point at the remedy instead of claiming there were none.
+   * @type {string[]}
+   */
+  const droppedUnresolvable = [];
   for (const spec of bare) {
     if (BUILTIN.has(spec)) continue;
     const pkg = extractPackageName(spec);
     if (!pkg || BUILTIN.has(pkg) || FRAMEWORK_SERVER_ONLY.has(pkg)) continue;
     const version = getPackageVersion(pkg, appDir);
-    if (!version) continue;
+    if (!version) {
+      droppedUnresolvable.push(spec);
+      continue;
+    }
     const subpath = spec.slice(pkg.length);
     const install = `${pkg}@${version}${subpath}`;
     installs.push(install);
@@ -1350,12 +1369,22 @@ export async function pinAll(appDir, opts = {}) {
   // -imports filter, so the file exists but does nothing. The CLI
   // surfaces this as a clearer "no bare imports found" message.
   if (installs.length === 0) {
+    // Distinguish the two empty-set causes the CLI must report differently:
+    // the scan genuinely found nothing (noBareImports) vs it found specifiers
+    // that were all dropped for a missing local version (droppedUnresolvable).
+    if (droppedUnresolvable.length > 0) {
+      return { pins, pruned: [], downloaded, droppedUnresolvable, provider: from };
+    }
     return { pins, pruned: [], downloaded, noBareImports: true, provider: from };
   }
 
   await writePinFile(appDir, importmap, integrity, from);
   const pruned = await pruneOrphans(appDir, expected);
-  return { pins, pruned, downloaded, provider: from };
+  // Some specifiers may have pinned while others were dropped for a missing
+  // version; surface the dropped ones so a partial pin is not silent.
+  return droppedUnresolvable.length > 0
+    ? { pins, pruned, downloaded, provider: from, droppedUnresolvable }
+    : { pins, pruned, downloaded, provider: from };
 }
 
 /**

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",