@webjsdev/server 0.8.58 → 0.8.60

package/src/actions.js

@@ -20,6 +20,7 @@ import { ifNoneMatchSatisfied } from './conditional-get.js';
 import { getBodyLimits } from './context.js';
 import { basePath } from './importmap.js';
 import { withBasePath } from './base-path.js';
+import { FORM_ACTION_ID_KEY } from '@webjsdev/core';
 
 /**
  * The JSON / RPC body cap in effect for the current request: the per-request
@@ -417,11 +418,18 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
     lines.push(`  return __body(fn, key, __METHOD, sig);`);
     lines.push(`}`);
   }
+  // Each stub carries its own `<hash>/<fn>` identity (#1155), so a client
+  // re-render of `<form action=${action}>` can bind the live form
+  // synchronously. The server resolves the REAL function's identity through the
+  // load-hook registry instead; both produce the same string, which is what
+  // makes the SSR'd form and the re-rendered one submit the same value.
+  // Non-enumerable so `import * as actions` and a spread stay unchanged.
+  lines.push(`const __id = (fn, name) => { try { Object.defineProperty(fn, ${J(FORM_ACTION_ID_KEY)}, { value: __HASH + '/' + name }); } catch {} return fn; };`);
   for (const name of fnNames) {
     lines.push(
       name === 'default'
-        ? `export default (...args) => __call('default', args);`
-        : `export const ${name} = (...args) => __call(${J(name)}, args);`,
+        ? `export default __id((...args) => __call('default', args), 'default');`
+        : `export const ${name} = __id((...args) => __call(${J(name)}, args), ${J(name)});`,
     );
   }
   return lines.join('\n') + '\n';

package/src/base-path.js

@@ -11,7 +11,10 @@
  * hydrates. `createRequestHandler` explicitly targets embedding, where a
  * sub-path mount is the norm.
  *
- * The model is strip-at-ingress + prefix-on-emit, two seams only:
+ * The model is strip-at-ingress + prefix-on-emit. Two seams carry it, plus two
+ * further `stripBasePath` consumers on the CACHE path (`dev.js`'s HTML-cache
+ * write and `html-cache.js`'s `revalidatePath`), which key on the
+ * app-root-relative path so a mounted app hits its own cache:
  *
  *   1. STRIP AT INGRESS. At the very start of request handling, when the
  *      request pathname starts with the basePath, strip it so all

package/src/body-limit.js

@@ -3,7 +3,7 @@
  *
  * webjs's prod server reads request bodies on three paths: the server-action
  * RPC endpoint (actions.js), `route.{js,ts}` handlers via `readBody` (json.js),
- * and the no-JS page-action form path (page-action.js). Without a cap, an
+ * and the no-JS form-submission path (form-dispatch.js). Without a cap, an
  * uncapped body is a memory-exhaustion vector. This module is the SINGLE place
  * that decides the limit and performs a bounded read, so every body-read site
  * enforces it uniformly.
@@ -31,7 +31,7 @@
 export const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 
 /**
- * Default form / multipart body cap: 10 MiB. A form submission (the page-action
+ * Default form / multipart body cap: 10 MiB. A form submission (the form-dispatch
  * path) may legitimately carry more than a JSON RPC call (a textarea, a small
  * upload), so it gets a separate, higher, still-bounded limit. Large file
  * uploads are a distinct concern (#247) with their own streaming story.
@@ -40,7 +40,7 @@ export const DEFAULT_MAX_MULTIPART_BYTES = 10 * 1024 * 1024;
 
 /**
  * Thrown by `readBody` (json.js) when a route handler's body exceeds the limit.
- * The RPC and page-action paths return a 413 Response inline, but `readBody`
+ * The RPC and form-dispatch paths return a 413 Response inline, but `readBody`
  * runs INSIDE a user route handler and returns parsed data, so it signals the
  * over-limit case by throwing. The API dispatcher (`handleApi`) catches this and
  * maps it to a 413, so a handler that just does `await readBody(req)` gets the
@@ -266,7 +266,7 @@ export async function readTextBounded(req, limit) {
 }
 
 /**
- * Read a request body as `FormData`, bounded by `limit`. Used by the page-action
+ * Read a request body as `FormData`, bounded by `limit`. Used by the form-dispatch
  * form path. Reconstructs a bounded Request from the already-read bytes and
  * defers to the platform `formData()` parser, so multipart and
  * urlencoded bodies are decoded exactly as before, just size-checked first.

package/src/check.js

@@ -3,6 +3,7 @@ import { join, relative, sep, basename, dirname } from 'node:path';
 import { walk } from './fs-walk.js';
 import {
   redactStringsAndTemplates,
+  redactToPlaceholders,
   extractWebComponentClassBodies,
   matchClosingBrace,
   parsePropEntries,
@@ -134,6 +135,11 @@ export const RULES = [
     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: 'form-action-not-a-get-action',
+    description:
+      'Flags `<form action=${someAction}>` bound to a `\'use server\'` action whose file declares `export const method = \'GET\'` (#488). A GET action is a READ: it is CSRF-exempt and rides its arguments in the url, while a form submission is a CSRF-checked POST carrying a body, so the two contracts contradict each other and the submission is answered with a 405 at runtime. The rule reads the imported action\'s own file, so it only fires when the binding really does resolve to a GET-declared action. Fix by dropping the `method` export (an action with no `method` is a POST, which is what a form wants) or by binding a different action; if the form really is a read, use a plain `<form method="get" action="/search">` with no bound action.',
+  },
   {
     name: 'no-redirect-in-api-route',
     description:
@@ -475,6 +481,36 @@ function enumerableExports(scan) {
  * @param {string} clause  the text between `import` and `from`
  * @returns {string[]|null}
  */
+/**
+ * The `{ local, imported }` pairs a named import clause binds, for a rule that
+ * has to match the LOCAL name against code (`action=${reader}`) while reporting
+ * the IMPORTED one (`readIt`, which is what the target module calls it).
+ *
+ * `importedValueNames` cannot serve here: it returns only the imported side,
+ * which is the wrong name to match against a template hole under `as`.
+ *
+ * @param {string} clause  the text between `import` and `from`
+ * @returns {{ local: string, imported: string }[]}
+ */
+function importedLocalNames(clause) {
+  if (/^\s*type\b/.test(clause)) return [];
+  const brace = clause.match(/\{([^}]*)\}/);
+  if (!brace) return [];
+  /** @type {{ local: string, imported: string }[]} */
+  const out = [];
+  for (const part of brace[1].split(',')) {
+    const seg = part.trim().replace(/^type\s+/, '');
+    if (!seg) continue;
+    const as = seg.split(/\s+as\s+/);
+    const imported = as[0].trim();
+    const local = (as[1] || as[0]).trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(local) && /^[A-Za-z_$][\w$]*$/.test(imported)) {
+      out.push({ local, imported });
+    }
+  }
+  return out;
+}
+
 function importedValueNames(clause) {
   if (/^\s*type\b/.test(clause)) return null; // import type { ... }
   const brace = clause.match(/\{([^}]*)\}/);
@@ -489,8 +525,9 @@ function importedValueNames(clause) {
 /**
  * Scan a WebJs app directory and report convention violations.
  *
- * Every rule is a correctness check (a crash, a security leak, or a
- * build/type-strip failure), so they all run unconditionally. There is no
+ * Every rule is a correctness check (a crash, a security leak, a reactive
+ * prop that silently stops re-rendering, or a build/type-strip failure), so
+ * they all run unconditionally. There is no
  * per-project disabling: project conventions (layout, style, process) live in
  * CONVENTIONS.md as guidance, not in this tool.
  *
@@ -1333,6 +1370,90 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: form-action-not-a-get-action (#1155) ---
+  // `<form action=${fn}>` binds a server action to a POST submission. An action
+  // declaring `method = 'GET'` cannot serve one: it is CSRF-exempt and takes its
+  // args in the url, so the dispatcher answers 405. Catch it at edit time.
+  {
+    // A `'use server'` file's declared method, or absent when it declares none.
+    const methodByAbs = new Map();
+    for (const f of files) {
+      if (!/\.server\.m?[jt]s$/.test(f.rel)) continue;
+      if (!hasUseServerDirective(f.content)) continue;
+      const m = /\bexport\s+const\s+method\s*(?::[^=]*)?=\s*['"`]([A-Za-z]+)['"`]/.exec(f.scan);
+      if (m) methodByAbs.set(f.abs, m[1].toUpperCase());
+    }
+    if (methodByAbs.size) {
+      const reImport = /\bimport\s+([^'";]*?)\bfrom\s*(['"])/g;
+      for (const { abs, rel, content } of files) {
+        // PLACEHOLDER redaction, not either mask, and the choice is forced.
+        // The default mask blanks a tagged template outright, so a real
+        // `html`<form action=${fn}>`` disappears and the rule could never fire;
+        // the fully-blanked mask does the same. Placeholder mode keeps `${...}`
+        // holes as REAL code while turning each literal BODY into one opaque
+        // `__STR_n__` token, so a live binding is readable and a `<form
+        // action=${x}>` shown as text inside a docs sample is a single token
+        // with no hole in it. That distinction is the whole carve-out: the
+        // framework's own website renders this exact shape as a code sample.
+        const { redacted, literals } = redactToPlaceholders(content);
+        // A hole binds an action when the literal segment IMMEDIATELY before it
+        // ends inside a start tag at the attribute that tag can really bind:
+        // `action=` on a `<form>` (#1155), or `formaction=` on a `<button>` /
+        // `<input>` submitter (#1207). Reading the segment rather than the whole
+        // template is what keeps `<div action=${x}>` out. The tag and the
+        // attribute are matched as a PAIR, so `<form formaction=${x}>` and
+        // `<button action=${x}>` stay out too: both are refused at render time,
+        // and neither is this rule's failure mode.
+        const bound = new Set();
+        for (const m of redacted.matchAll(/__STR_(\d+)__\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g)) {
+          const before = literals[Number(m[1])] || '';
+          // The last `<` opens the tag the hole sits in. Requiring no `>`
+          // after it keeps the match inside that one start tag.
+          const tagAt = before.lastIndexOf('<');
+          if (tagAt < 0) continue;
+          const tag = before.slice(tagAt);
+          if (tag.includes('>')) continue;
+          const bindsForm = /^<form\b/i.test(tag) && /\saction=$/i.test(tag);
+          const bindsSubmitter = /^<(?:button|input)\b/i.test(tag) && /\sformaction=$/i.test(tag);
+          if (!bindsForm && !bindsSubmitter) continue;
+          bound.add(m[2]);
+        }
+        if (!bound.size) continue;
+        reImport.lastIndex = 0;
+        let im;
+        while ((im = reImport.exec(redacted))) {
+          // The specifier is a placeholder token in this view, so read the real
+          // one back out of `literals`.
+          const tok = /__STR_(\d+)__/.exec(redacted.slice(reImport.lastIndex, reImport.lastIndex + 24));
+          if (!tok) continue;
+          const spec = literals[Number(tok[1])] || '';
+          if (!/^(?:\.|#)/.test(spec)) continue;
+          const names = importedLocalNames(im[1]);
+          if (!names.length) continue;
+          const target = resolveImport(spec, abs, appDir);
+          // ONLY a GET is contradictory, and the rule must say exactly what the
+          // dispatcher does or it is a false positive. A browser form always
+          // submits as a POST, and the dispatcher runs a PUT / PATCH / DELETE
+          // action on that POST: the declared verb governs the RPC transport,
+          // not whether the function can serve a form. A GET is different in
+          // kind (CSRF-exempt, args in the url, no body), which is why it is
+          // the one the dispatcher answers with a 405.
+          const method = target ? methodByAbs.get(target) : undefined;
+          if (method !== 'GET') continue;
+          for (const { local, imported } of names) {
+            if (!bound.has(local)) continue;
+            violations.push({
+              rule: 'form-action-not-a-get-action',
+              file: rel,
+              message: `Binds \`${imported}\` to a form, but \`${spec}\` declares \`method = 'GET'\`. A GET action rides its arguments in the url and skips the CSRF check, so it cannot answer a form POST; the submission is a 405.`,
+              fix: `Drop the \`method\` export from \`${spec}\` (an action with no method is a POST, which is what a form submits), or bind an action that takes a POST.`,
+            });
+          }
+        }
+      }
+    }
+  }
+
   return violations;
 }
 

package/src/component-elision.js

@@ -145,9 +145,13 @@ export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'reques
  *   - `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.
+ *     see statically (an OBSERVER that computes the tag it waits for, a
+ *     `:defined` rule in an external stylesheet outside the module graph, a
+ *     consumer reaching the element through a string selector). It
+ *     cannot rescue a component whose OWN registration tag is computed: the
+ *     scanner requires a literal tag (invariant 3), so such a component is
+ *     never in `components` at all and nothing consults this analyser for it.
+ *     Context-free: any value other than `false` ships.
  *
  * @type {readonly string[]}
  */
@@ -904,12 +908,12 @@ export async function computeElidableComponents(components, moduleGraph, readFil
  * global (`window`, `document`, …), or a shipping component. Anything
  * ambiguous or unreadable keeps shipping.
  *
- * @param {Array<{ tag: string, file: string }>} components
+ * @param {Array<{ tag: string, file: string, className?: string }>} components
  * @param {string[]} routeModules  absolute paths of page + layout files
  * @param {import('./module-graph.js').ModuleGraph} moduleGraph
  * @param {(file: string) => Promise<string>} readFileFn
  * @param {string} [appDir]
- * @returns {Promise<{ elidableComponents: Set<string>, inertRouteModules: Set<string>, importOnlyRouteModules: Map<string, string[]>, shippedRouteModules: Map<string, { blocker: string|null, reason: string }> }>}
+ * @returns {Promise<{ elidableComponents: Set<string>, inertRouteModules: Set<string>, importOnlyRouteModules: Map<string, string[]>, shippedRouteModules: Map<string, { blocker: string|null, reason: string }>, componentVerdicts: Map<string, { tags: string[], className: string|null, shipped: boolean, evidence: string|null, by: string|null, reason: string|null }> }>}
  */
 export async function analyzeElision(components, routeModules, moduleGraph, readFileFn, appDir) {
   /** @type {Set<string>} */
@@ -926,6 +930,23 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
 
   /** @type {Set<string>} */
   const mustShip = new Set();
+  /**
+   * WHY each shipping component ships (#1308), so the app-level report can name
+   * the evidence instead of only the verdict. Written alongside every
+   * `mustShip.add` of a COMPONENT file; FIRST write wins, matching the
+   * first-match convention the analyser uses everywhere else.
+   * @type {Map<string, { evidence: string, by: string|null, reason: string|null }>}
+   */
+  const shipEvidence = new Map();
+  /**
+   * @param {string} file      the component file that ships
+   * @param {string} evidence  one of own | observed | closure | render | import | unreadable
+   * @param {string|null} by   the module that forced it, where one exists
+   * @param {string|null} [reason]
+   */
+  const noteShip = (file, evidence, by, reason) => {
+    if (!shipEvidence.has(file)) shipEvidence.set(file, { evidence, by, reason: reason ?? null });
+  };
   /** @type {Map<string, Set<string>>} */
   const fileTags = new Map();
   /** @type {Set<string>} modules importing a reactive primitive from core */
@@ -939,6 +960,8 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
   /** @type {Set<string>} component files forced to ship because some module
    * observes their registration (whenDefined / :defined / instanceof). */
   const observedComponentFiles = new Set();
+  /** @type {Map<string, string>} observed component file -> the module observing it (#1308) */
+  const observedBy = new Map();
 
   /** @type {Set<string>} */
   const allFiles = new Set(componentFiles);
@@ -957,7 +980,7 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     catch {
       // A component file we cannot read ships conservatively; a helper we
       // cannot read simply contributes no tags.
-      if (componentFiles.has(file)) mustShip.add(file);
+      if (componentFiles.has(file)) { mustShip.add(file); noteShip(file, 'unreadable', null, null); }
       continue;
     }
     if (typeof src !== 'string') continue;
@@ -989,8 +1012,9 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
         hasModuleScopeSideEffect(redacted, literals)) {
       clientGlobalOrBareFiles.add(file);
     }
-    if (componentFiles.has(file) && analyzeComponentSource(masked).interactive) {
-      mustShip.add(file);
+    if (componentFiles.has(file)) {
+      const v = analyzeComponentSource(masked);
+      if (v.interactive) { mustShip.add(file); noteShip(file, 'own', null, v.reason); }
     }
     // Cross-module registration observation (#169): if THIS module observes
     // another component's tag, that component must register client-side, so
@@ -999,13 +1023,13 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     // (all components are known up front, but we collect here while we hold
     // each source). Verdict-safe: only ever forces MORE components to ship.
     for (const m of masked.matchAll(WHEN_DEFINED_RE)) {
-      const f = tagToFile.get(m[1]); if (f) observedComponentFiles.add(f);
+      const f = tagToFile.get(m[1]); if (f) { observedComponentFiles.add(f); if (!observedBy.has(f)) observedBy.set(f, file); }
     }
     for (const m of masked.matchAll(TAG_DEFINED_RE)) {
-      const f = tagToFile.get(m[1]); if (f) observedComponentFiles.add(f);
+      const f = tagToFile.get(m[1]); if (f) { observedComponentFiles.add(f); if (!observedBy.has(f)) observedBy.set(f, file); }
     }
     for (const m of masked.matchAll(INSTANCEOF_RE)) {
-      const f = classToFile.get(m[1]); if (f) observedComponentFiles.add(f);
+      const f = classToFile.get(m[1]); if (f) { observedComponentFiles.add(f); if (!observedBy.has(f)) observedBy.set(f, file); }
     }
   }
 
@@ -1013,7 +1037,7 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
   // render/import rules propagate from it too. Dynamic tag strings and external
   // (non graph-reachable) stylesheets remain an author-facing caveat, since
   // static analysis cannot see them.
-  for (const f of observedComponentFiles) mustShip.add(f);
+  for (const f of observedComponentFiles) { mustShip.add(f); noteShip(f, 'observed', observedBy.get(f) ?? null, null); }
 
   // Reverse import edges (who imports each file), built once from the graph.
   // Drives both the closure-client-work reachability below and the fixpoint's
@@ -1065,7 +1089,7 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
       if (!deps) continue;
       for (const dep of deps) {
         if (serverFiles.has(dep)) continue;
-        if (reachesClientWork.has(dep)) { mustShip.add(file); break; }
+        if (reachesClientWork.has(dep)) { mustShip.add(file); noteShip(file, 'closure', dep, null); break; }
       }
     }
   }
@@ -1108,14 +1132,14 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     if (tags) {
       for (const tag of tags) {
         const childFile = tagToFile.get(tag);
-        if (childFile && !mustShip.has(childFile)) { mustShip.add(childFile); queue.push(childFile); }
+        if (childFile && !mustShip.has(childFile)) { mustShip.add(childFile); noteShip(childFile, 'render', node, null); queue.push(childFile); }
       }
     }
     const importers = importersOf.get(node);
     if (importers) {
       for (const imp of importers) {
         if (!componentFiles.has(imp)) continue;  // import rule is component -> component
-        if (!mustShip.has(imp)) { mustShip.add(imp); queue.push(imp); }
+        if (!mustShip.has(imp)) { mustShip.add(imp); noteShip(imp, 'import', node, null); queue.push(imp); }
       }
     }
   }
@@ -1146,6 +1170,41 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     return 'does client work';
   };
 
+  // Per-component verdict plus the evidence that produced it (#1308). Assembled
+  // ENTIRELY from what the passes above already computed: nothing is re-read and
+  // nothing is re-analysed, so this is a projection, not a second analysis. A
+  // file may register more than one tag, so rows are keyed by FILE with a
+  // sorted tag list.
+  /** @type {Map<string, { tags: string[], className: string|null, shipped: boolean, evidence: string|null, by: string|null, reason: string|null }>} */
+  const componentVerdicts = new Map();
+  for (const c of components) {
+    let row = componentVerdicts.get(c.file);
+    if (!row) {
+      const shipped = mustShip.has(c.file);
+      const ev = shipped ? shipEvidence.get(c.file) : undefined;
+      row = {
+        tags: [], className: c.className ?? null, shipped,
+        evidence: ev ? ev.evidence : null,
+        by: ev ? ev.by : null,
+        // An ELIDED component carries no reason on purpose: elision is the
+        // ABSENCE of every signal, so there is no positive fact to report.
+        // A shipping component with no evidence is only reachable if a future
+        // rule adds to `mustShip` without calling `noteShip`, so report null
+        // rather than a wrong claim (sigil-coverage guards against that drift).
+        reason: !shipped || !ev ? null
+          : ev.evidence === 'own' ? ev.reason
+          : ev.evidence === 'observed' ? `its registration is observed by ${ev.by}`
+          : ev.evidence === 'closure' ? `its import ${ev.by} ${clientEffectReason(/** @type {string} */ (ev.by))}`
+          : ev.evidence === 'render' ? `${ev.by} ships and can render its tag`
+          : ev.evidence === 'import' ? `${ev.by} ships and imports it`
+          : 'its source could not be read (ships conservatively)',
+      };
+      componentVerdicts.set(c.file, row);
+    }
+    if (!row.tags.includes(c.tag)) row.tags.push(c.tag);
+  }
+  for (const row of componentVerdicts.values()) row.tags.sort();
+
   // Route modules fall into three classes by their effective client closure
   // (skipping elided components and server stubs, which never load on the
   // client):
@@ -1242,7 +1301,7 @@ export async function analyzeElision(components, routeModules, moduleGraph, read
     }
   }
 
-  return { elidableComponents, inertRouteModules, importOnlyRouteModules, shippedRouteModules };
+  return { elidableComponents, inertRouteModules, importOnlyRouteModules, shippedRouteModules, componentVerdicts };
 }
 
 /** Match a whole-line side-effect import: `import './x.js';` (no bindings). */

package/src/component-scanner.js

@@ -7,15 +7,13 @@
  * renders a component tag, `lookupModuleUrl(tag)` already has the URL
  * ready for `<link rel="modulepreload">` hints.
  *
- * The convention WebJs uses is the web-standard one:
- *
- *     class Counter extends WebComponent { … }
- *     customElements.define('my-counter', Counter);
- *
- * The scanner looks for `customElements.define('<tag>', <ClassName>)`
- * calls: static text patterns that are cheap to regex-match without
- * a full TS parse. A full parse would be ~50× slower for no payoff;
- * we only need `{ tag, className, moduleUrl }` tuples.
+ * The idiomatic WebJs registration is `Class.register('my-counter')`; the
+ * web-standard `customElements.define('my-counter', Counter)` is equally
+ * supported. The scanner matches BOTH, as static text patterns that are cheap
+ * to regex-match without a full TS parse. A full parse would be ~50× slower
+ * for no payoff; we only need `{ tag, className, moduleUrl }` tuples. Either
+ * way the tag must be a LITERAL (invariant 3): a computed one is invisible
+ * here, which is what makes it an orphan (see `findOrphanComponents`).
  */
 
 import { readFile, stat } from 'node:fs/promises';
@@ -148,10 +146,36 @@ export async function primeComponentRegistry(appDir, components) {
 }
 
 /**
- * Find `class X extends WebComponent` (or its subclasses) declarations
- * that are NOT accompanied by a `customElements.define(tag, X)` call in
- * the same file. Lets the dev server warn authors early when they
- * forget the registration step.
+ * Find ORPHAN components: a `class X extends WebComponent` that NOTHING in the
+ * app registers with a LITERAL tag, via either `X.register('tag')` or
+ * `customElements.define('tag', X)`. The declaration is per-file, the
+ * registration cross-reference is app-wide.
+ *
+ * TWO shapes land here and they fail differently, so any message about this
+ * must cover both:
+ *
+ *   - No registration call ANYWHERE in the app (the forgot-to-register case).
+ *     Nothing ever registers the tag, so the element NEVER upgrades. The
+ *     cross-reference is app-wide precisely so a class registered by a sibling
+ *     module is not accused of this.
+ *   - A registration whose tag is COMPUTED (`X.register(TAG)`). That call is
+ *     ordinary code, so it runs IF the module reaches the browser, which
+ *     requires the importing module to ship WHOLE. An inert, import-only, or
+ *     elided importer is dropped from the boot and takes the import with it,
+ *     and then the element does not upgrade either. Assume it does not. An
+ *     orphan is not in `componentFiles`, so it never joins the frontier an
+ *     import-only page emits in its place, and a page that renders a real
+ *     component alongside the orphan is import-only unless it ALSO does its
+ *     own client work (which ships it whole, #963). Shipping whole is the
+ *     narrower case, so treat the upgrade as lost until proven otherwise.
+ *
+ * Lost in EVERY case, whichever shape: the elision verdict, the tag-to-module
+ * registry entry, and the modulepreload hint. That, not the upgrade, is the
+ * part that is always true, and it is what every message about this should
+ * lead with.
+ *
+ * Matches the literal `extends WebComponent` only, so a class extending a
+ * component SUBCLASS is not reported.
  *
  * @param {string} appDir
  * @returns {Promise<Array<{ className: string, file: string }>>}
@@ -164,30 +188,62 @@ export async function findOrphanComponents(appDir) {
     !/\.(test|spec)\.m?[jt]sx?$/.test(p) &&
     !/\.server\.m?[jt]s$/.test(p);
 
+  // TWO passes, because registration is an APP-WIDE fact while the declaration
+  // is per-file. A class may legitimately be declared in one module and
+  // registered by a sibling (`customElements.define('my-badge', Badge)` in a
+  // separate file), which the scanner header calls equally supported and which
+  // `extractComponents` already picks up as a real component. Reporting it as
+  // an orphan is a FALSE positive, and a false warning on a legitimate pattern
+  // is exactly what makes an author stop reading the warnings.
+  //
+  // Trade-off, deliberate: the cross-reference is by class NAME, so two
+  // same-named classes in different files, one registered and one genuinely
+  // orphaned, hide the real orphan. That is rarer than the sibling-registration
+  // pattern and errs toward silence rather than toward a wrong accusation.
+  /** @type {Array<{ file: string, declared: Set<string> }>} */
+  const declaredPerFile = [];
+  /** @type {Set<string>} every class name registered ANYWHERE in the app */
+  const registeredAnywhere = new Set();
+
   for await (const file of walk(appDir, filter)) {
     let src;
     try { src = await readFile(file, 'utf8'); } catch { continue; }
+    // Scan REDACTED source, the same way `extractComponents` above does. A
+    // `class X extends WebComponent` written inside an `html` template or a
+    // string is a CODE SAMPLE (every docs page is full of them), not a real
+    // declaration, and reporting it as an unregistered component is a false
+    // orphan. Redaction blanks comments and swaps each string / template body
+    // for a `__STR_<idx>__` placeholder, so a genuine top-level declaration
+    // still matches while a sample inside a template does not. It does NOT
+    // preserve offsets (a placeholder is a different length than the body it
+    // replaces), which is fine here because an orphan is reported by class
+    // name and file, never by position. If this scan ever needs a line or
+    // column, reach for `redactStringsAndTemplates(src, true)`, WITH the
+    // blank-strings argument: the default form keeps plain-string bodies and
+    // single-line untagged templates verbatim, so a sample written either way
+    // would match again and the false orphan would be back.
+    const { redacted } = redactToPlaceholders(src);
     // Find every class that extends WebComponent (exact name: we trust
     // the framework convention).
     const classRe = /\b(?:export\s+)?(?:default\s+)?class\s+([A-Z][A-Za-z0-9_$]*)\s+extends\s+WebComponent\b/g;
-    // A class counts as "registered" if either Class.register('tag') or
-    // customElements.define('tag', Class) appears in the file.
-    const registerRe = /\b([A-Z][A-Za-z0-9_$]*)\.register\s*\(\s*['"][^'"]+['"]\s*\)/g;
-    const defineRe = /\bcustomElements\.define\s*\(\s*['"][^'"]+['"]\s*,\s*([A-Z][A-Za-z0-9_$]*)\b/g;
-
     const declared = new Set();
     let m;
-    while ((m = classRe.exec(src)) !== null) declared.add(m[1]);
-    if (declared.size === 0) continue;
+    while ((m = classRe.exec(redacted)) !== null) declared.add(m[1]);
 
-    const registered = new Set();
-    while ((m = registerRe.exec(src)) !== null) registered.add(m[1]);
-    while ((m = defineRe.exec(src)) !== null) registered.add(m[1]);
+    // "Registered" is whatever `extractComponents` accepts, reused rather than
+    // re-expressed. The two scans MUST agree on what a literal tag is: when
+    // this used its own looser pattern, a redacted interpolated template
+    // (`Class.register(\`${p}__STR_1__\`)`) satisfied the orphan scan but not
+    // `extractComponents`, so a computed template-literal tag was neither a
+    // component NOR an orphan and vanished from every surface, which is the
+    // exact shape the orphan report exists to catch.
+    for (const c of extractComponents(src)) registeredAnywhere.add(c.className);
+    if (declared.size) declaredPerFile.push({ file, declared });
+  }
 
+  for (const { file, declared } of declaredPerFile) {
     for (const cls of declared) {
-      if (!registered.has(cls)) {
-        orphans.push({ className: cls, file });
-      }
+      if (!registeredAnywhere.has(cls)) orphans.push({ className: cls, file });
     }
   }
   return orphans;

package/src/context.js

@@ -17,7 +17,7 @@ import { setCspNonceProvider, cspNonce } from '@webjsdev/core';
  *
  * `bodyLimits` holds the resolved request body-size caps (issue #237) so
  * `readBody` (used inside `route.{js,ts}` handlers, which have no handle to the
- * server state) can enforce the same limit the RPC and page-action paths do. The
+ * server state) can enforce the same limit the RPC and form-dispatch paths do. The
  * handler writes it per request via `setBodyLimits`.
  *
  * `requestId` holds the per-request correlation id (issue #239). The handler

package/src/csp.js

@@ -50,8 +50,9 @@ const CONTROL_CHARS = /[\x00-\x1f\x7f-\x9f]/;
  * with webjs's own output, which is: nonce-signed inline `<script>` tags
  * (the boot script, the public-env shim, the importmap), nonce-signed
  * `<link rel="modulepreload">`, ES modules fetched same-origin and from
- * the configured vendor CDN, and Tailwind's runtime which injects a
- * `<style>` element (so inline styles must be allowed).
+ * the configured vendor CDN, and one inline `<style>` in the head. The
+ * nonce covers scripts only, so that rule and every app-authored style
+ * alike are admitted by `'unsafe-inline'` (see the `style-src` note).
  *
  * `script-src` uses `'strict-dynamic'` so a nonce-loaded module can pull
  * in its own dependencies (the importmap-driven per-file ESM graph)
@@ -67,10 +68,25 @@ const CONTROL_CHARS = /[\x00-\x1f\x7f-\x9f]/;
 const DEFAULT_DIRECTIVES = {
   'default-src': "'self'",
   'script-src': "'nonce-__NONCE__' 'strict-dynamic' 'self' https:",
-  // Tailwind's browser runtime injects a <style> element, and webjs
-  // emits an inline <style> for adopted component styles, so inline
-  // styles must be permitted. Style elements are not a script-injection
-  // vector, so this does not weaken the script protection.
+  // NOTE this directive carries no nonce source, unlike `script-src`, so a
+  // nonce attribute on a <style> is INERT here and every inline style is
+  // admitted by 'unsafe-inline' alone. That includes WebJs's own head rule
+  // (the @layer webjs-host block), which SSR does stamp with the nonce but
+  // which this policy never checks it against. Dropping 'unsafe-inline'
+  // would block that rule too, not only app style.
+  //
+  // What keeps the allowance necessary is inline style with no realistic
+  // nonce path, and it arrives in four shapes. A page or layout may write
+  // an inline <style>, which an author could nonce by hand but does not by
+  // default. A light-DOM component's <style> and a shadow component's
+  // `static styles`, serialized into its declarative shadow root, are both
+  // emitted by the core renderer with no nonce and no way to supply one.
+  // And every style="..." attribute is unfixable in principle, since a
+  // nonce applies to elements and never to attributes. No styling library
+  // is involved in any of them.
+  //
+  // Style elements are not a script-injection vector, so this does not
+  // weaken the script protection.
   'style-src': "'self' 'unsafe-inline'",
   'img-src': "'self' data: https:",
   'font-src': "'self' data: https:",