@webjsdev/server 0.8.40 → 0.8.41

package/index.js

@@ -77,4 +77,5 @@ export {
   actionEndpoint,
   invokeActionForTest,
   rawActionRequest,
+  createBrowserTestHandler,
 } from './src/testing.js';

package/package.json

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

package/src/check.js

@@ -82,7 +82,7 @@ export const RULES = [
   {
     name: 'reactive-props-no-class-field',
     description:
-      'A reactive property declared via the `extends WebComponent({ … })` factory must NOT also have a plain class-field initializer (`count = 0` or `count: number = 0`) in the class body. Under modern class-field semantics that initializer runs Object.defineProperty *after* super(), clobbering the framework\'s reactive accessor and silently breaking re-renders. Set the default by assigning in the constructor after super().',
+      'A reactive property declared via the `extends WebComponent({ … })` factory must NOT also have a plain class-field declaration (`count = 0`, `count: number = 0`, `count!: number`, or `count?: number`) in the class body. Under modern class-field semantics (including `erasableSyntaxOnly: true`) every class-field declaration compiles to Object.defineProperty *after* super(), clobbering the framework\'s reactive accessor and silently breaking re-renders. Set the default by assigning in the constructor after super().',
   },
   {
     name: 'array-prop-uses-array-type',
@@ -134,6 +134,11 @@ export const RULES = [
     description:
       'The one sentinel-based check, and the deliberate exception to the "objectively broken code" framing of the other rules: it flags scaffold example content that has not been replaced, so a delivered app contains only what the user intended and never leftover scaffold code. `webjs create` marks its example/demo files (the example homepage in app/page.ts, the example app chrome in app/layout.ts) with a one-line marker comment carrying the literal token `webjs-scaffold-placeholder`. The rule scans raw source (the marker lives in a comment, which the redacted scan view would hide) and fails for every file that still carries the token. A freshly scaffolded app fails this rule BY DESIGN until its placeholders are addressed: replace the example content, or deliberately keep it, and in either case delete the marker line. No finished app legitimately ships a literal remove-me marker, so this still qualifies as a check rather than a convention. The marker is acknowledge-and-remove, so keeping a piece is a one-line deletion rather than a forced rewrite.',
   },
+  {
+    name: 'no-redirect-in-api-route',
+    description:
+      'API route handlers (`route.{js,ts}`) must NOT call `redirect()` from `@webjsdev/core`. That function throws a control-flow signal designed for the SSR page renderer; in a route handler it goes uncaught and produces a 500. Use `Response.redirect(url, 303)` for external redirects or return a 3xx Response directly. Page functions, layouts, and server actions may still use `redirect()` (caught by the SSR pipeline).',
+  },
 ];
 
 /** Set of all known rule names for fast lookup. */
@@ -268,12 +273,20 @@ function findFieldInitializers(classBody, props) {
       let j = lineStart;
       while (j < classBody.length && classBody[j] !== '\n') j++;
       const line = classBody.slice(lineStart, j);
-      // Match: optional whitespace, optional `public/private/protected/readonly`,
-      // an identifier, optional `: <type>`, then `=`.
-      const fieldRe = /^\s*(?:(public|private|protected|readonly)\s+)?([A-Za-z_$][\w$]*)\s*(?::\s*[^=;]+)?\s*=\s*[^=>]/;
-      const m = fieldRe.exec(line);
-      if (m) {
-        const name = m[2];
+      // Match class-field declarations. Two shapes:
+      // 1. With initializer: `count = 0`, `count: number = 0`, `public count = 0`
+      // 2. Type-only (no initializer): `count!: number`, `count?: number`, `count: number`
+      // Both compile to Object.defineProperty after super() under modern class-field
+      // semantics, clobbering the reactive accessor.
+      // The initializer regex: optional modifier, identifier, optional type, then `=`.
+      const initRe = /^\s*(?:(public|private|protected|readonly)\s+)?([A-Za-z_$][\w$]*)\s*(?::\s*[^=;]+)?\s*=\s*[^=>]/;
+      // The type-only regex: optional modifier, identifier, then `!:` or `?:` or `:` with a type.
+      const typeOnlyRe = /^\s*(?:(public|private|protected|readonly)\s+)?([A-Za-z_$][\w$]*)\s*[!?]?\s*:\s*\S/;
+      const initM = initRe.exec(line);
+      const typeM = typeOnlyRe.exec(line);
+      // Prefer the initializer match; if neither, skip.
+      const name = initM ? initM[2] : (typeM ? typeM[2] : null);
+      if (name) {
         // `declare`, `static`, and `this.` patterns shouldn't reach here
         // (declare/static start with their keyword, this.x has the dot in
         // the regex group), but guard against matching keywords as names:
@@ -459,8 +472,11 @@ export async function checkConventions(appDir) {
 
   // --- Rule: reactive-props-no-class-field ---
   // A reactive property declared via the factory must not also carry a plain
-  // class-field initializer: it runs Object.defineProperty after super() and
-  // clobbers the framework's reactive accessor (silent broken re-renders).
+  // class-field declaration (initializer OR type-only): under modern class-field
+  // semantics (including `erasableSyntaxOnly: true`) every class-field declaration
+  // compiles to Object.defineProperty after super() and clobbers the framework's
+  // reactive accessor (silent broken re-renders). Catches `count = 0`,
+  // `count: number = 0`, `count!: number`, and `count?: number`.
   {
     for (const { rel, scan } of files) {
       if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
@@ -470,8 +486,8 @@ export async function checkConventions(appDir) {
           violations.push({
             rule: 'reactive-props-no-class-field',
             file: rel,
-            message: `Reactive prop \`${bad}\` uses a class-field initializer; this clobbers the framework's reactive accessor under modern class-field semantics.`,
-            fix: `Remove the class-field initializer and set the default by assigning \`this.${bad} = <value>\` inside \`constructor()\` after \`super()\`.`,
+            message: `Reactive prop \`${bad}\` uses a class-field declaration (initializer or type-only); this clobbers the framework's reactive accessor under modern class-field semantics.`,
+            fix: `Delete the class-field declaration and set the default by assigning \`this.${bad} = <value>\` inside \`constructor()\` after \`super()\`.`,
           });
         }
       }
@@ -557,6 +573,67 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: no-redirect-in-api-route ---
+  // `redirect()` from `@webjsdev/core` throws a control-flow signal designed
+  // for the SSR page renderer. In a `route.ts` API handler it goes uncaught
+  // and produces a 500. API handlers must use `Response.redirect(url, 303)`
+  // instead. Page functions, layouts, and server actions may still use
+  // `redirect()` (caught by the SSR / action pipeline).
+  {
+    const ROUTE_FILE = /(?:^|\/)route\.m?[jt]s$/;
+    for (const { rel, scan } of files) {
+      if (!ROUTE_FILE.test(rel)) continue;
+      // `redirect` reaches the route file in one of two statically-visible ways:
+      //   1. A NAMED import from `@webjsdev/core` (possibly aliased):
+      //      `import { redirect }`, `import { redirect as r }`, `import { …, redirect, … }`.
+      //   2. A NAMESPACE import then a member call:
+      //      `import * as core from '@webjsdev/core'` then `core.redirect(...)`.
+      // The named case flags a bare `redirect(` call; the namespace case flags
+      // `<ns>.redirect(`. `Response.redirect(` and any other `obj.redirect(` are
+      // the standard API and stay fine. A `redirect()` thrown inside a
+      // '`use server`' action the route calls DIRECTLY (an uncaught 500) needs
+      // cross-file analysis and is left to the AST rework (#753).
+      const namedM = /\bimport\s+\{[^}]*\bredirect\b(?:\s+as\s+(\w+))?\s*[^}]*\}\s+from\s+['"]@webjsdev\/core['"]/.exec(scan);
+      const nsM = /\bimport\s+\*\s+as\s+(\w+)\s+from\s+['"]@webjsdev\/core['"]/.exec(scan);
+      // A file can carry BOTH a named `redirect` import AND a namespace import,
+      // so check every matcher independently (not mutually exclusive): a named
+      // import means a bare `<localName>(`, a namespace import means
+      // `<ns>.redirect(`. The `member` flag distinguishes the two so a bare
+      // named call can screen out `Response.redirect(` / `obj.redirect(`.
+      /** @type {Array<{ re: RegExp, member: boolean }>} */
+      const matchers = [];
+      if (namedM) {
+        const localName = namedM[1] || 'redirect';
+        matchers.push({ re: new RegExp(`(?<!\\.)\\b${localName}\\s*\\(`, 'g'), member: false });
+      }
+      if (nsM) {
+        matchers.push({ re: new RegExp(`\\b${nsM[1]}\\.redirect\\s*\\(`, 'g'), member: true });
+      }
+      let flagged = false;
+      for (const { re, member } of matchers) {
+        if (flagged) break;
+        let m;
+        while ((m = re.exec(scan)) !== null) {
+          if (!member) {
+            // Screen out `Response.redirect(` / `someObj.redirect(` sharing the
+            // local name: a preceding member-access dot means it is not the import.
+            const before = scan.slice(Math.max(0, m.index - 20), m.index);
+            if (/\w\.$/.test(before)) continue;
+          }
+          violations.push({
+            rule: 'no-redirect-in-api-route',
+            file: rel,
+            message:
+              `\`redirect()\` from \`@webjsdev/core\` throws a control-flow signal for the SSR page renderer; in a \`route.ts\` handler it goes uncaught and returns a 500.`,
+            fix: `Use \`Response.redirect(url, 303)\` for external redirects, or return a 3xx Response directly. The \`redirect()\` sentinel is only valid in page functions, layouts, and server actions (where the SSR pipeline catches it).`,
+          });
+          flagged = true; // one violation per file is enough
+          break;
+        }
+      }
+    }
+  }
+
   // --- Rule: no-server-env-in-components ---
   // Catches `process.env.X` reads in component files where X is not a
   // WEBJS_PUBLIC_* var and not NODE_ENV. The SSR shim only exposes those

package/src/component-elision.js

@@ -126,6 +126,35 @@ export const CLIENT_LIFECYCLE_HOOKS = [
  */
 export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'requestUpdate'];
 
+/**
+ * Static class fields whose declaration (to a non-`false` value) marks a
+ * component interactive (must ship). Kept as ONE registry so a new
+ * interactivity-relevant static convention is added in a single place; the
+ * per-class analysis loops over it. Unlike prototype methods (guarded by
+ * `lifecycle-coverage.test.js` via prototype introspection), there is no
+ * enumerable runtime source of "all static conventions", so the contract is
+ * a documented one: a new interactivity static field MUST be added here AND
+ * to the lifecycle table in agent-docs/components.md. `sigil-coverage.test.js`
+ * asserts each entry is honoured as a ship signal.
+ *
+ *   - `shadow`: Declarative Shadow DOM attaches ONLY during HTML parsing, so a
+ *     component that arrives via a client DOM insertion (a soft-nav swap, a
+ *     streamed <webjs-suspense> boundary's replaceWith) would never re-attach
+ *     its shadow root if elided. Context-free, so any shadow component ships.
+ *   - `refresh`: `static refresh = true` is the explicit opt-in to ship a bare
+ *     async component so its stale-while-revalidate refresh runs after SSR;
+ *     eliding drops that on-load re-fetch (moot for request-stable data).
+ *
+ * @type {readonly string[]}
+ */
+export const INTERACTIVITY_STATIC_FIELDS = ['shadow', 'refresh'];
+
+/** 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)',
+};
+
 /**
  * A bare `async render()` is NOT a standalone ship signal (#474). Its SSR
  * pass bakes the resolved data into the first paint, so a light-DOM async
@@ -144,8 +173,37 @@ export const CLIENT_METHOD_CALLS = ['addController', 'removeController', 'reques
  * re-fetch that eliding would drop).
  */
 
-/** Match a `@event=${...}` binding inside a template (unquoted per invariant 4). */
-const EVENT_BINDING_RE = /@[A-Za-z][\w-]*\s*=\s*\$\{/;
+/**
+ * Template binding-prefix classification, the anchor for the elision drift
+ * guard. Every prefix core's renderers recognise (core's `BINDING_PREFIXES`)
+ * is one of two kinds:
+ *   - SSR_DROPPED_PREFIXES: a CLIENT-BEHAVIOUR ship signal. The binding drops
+ *     at SSR and is wired only after hydration (`@event`), so a component whose
+ *     only interactivity is such a binding MUST ship.
+ *   - ROUND_TRIP_PREFIXES: an SSR-SAFE binding that survives into the served
+ *     HTML (`.prop` via `data-webjs-prop-*`, `?bool` as a boolean attribute),
+ *     so it is NOT a ship signal on its own and stays elidable.
+ * `sigil-coverage.test.js` asserts these two lists PARTITION `BINDING_PREFIXES`
+ * exactly (union equal, disjoint), so a new sigil cannot be added to the
+ * renderers without being classified here. That closes the one interactivity
+ * surface the prototype-introspection guard (`lifecycle-coverage.test.js`)
+ * cannot see, because a sigil is template syntax, not a method or an export.
+ */
+export const SSR_DROPPED_PREFIXES = ['@'];
+export const ROUND_TRIP_PREFIXES = ['.', '?'];
+
+/** Escape a single char for safe inclusion in a regex character class. */
+const escapeForCharClass = (c) => c.replace(/[\\\]^-]/g, '\\$&');
+
+/**
+ * Match a client-behaviour binding (`@event=${...}`), a ship signal. The
+ * prefix set is DERIVED from SSR_DROPPED_PREFIXES (not hardcoded), so a new
+ * client-behaviour sigil added to core is detected here automatically once it
+ * is classified above. (unquoted per invariant 4)
+ */
+const EVENT_BINDING_RE = new RegExp(
+  `[${SSR_DROPPED_PREFIXES.map(escapeForCharClass).join('')}][A-Za-z][\\w-]*\\s*=\\s*\\$\\{`,
+);
 
 /** Match a `.onclick=${...}` (native event-handler property) binding. */
 const EVENT_PROP_RE = /\.on[a-z]+\s*=\s*\$\{/;
@@ -505,22 +563,13 @@ export function analyzeComponentSource(src) {
   }
 
   for (const { body, factoryArg } of bodies) {
-    // Shadow DOM always ships (#474). Declarative Shadow DOM attaches ONLY
-    // during HTML parsing; an elided 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, because eliding
-    // drops the module that runs `attachShadow`. The analyser is context-free
-    // (it cannot tell whether a given component will be streamed or
-    // navigated to), so any shadow component is shipped.
-    if (declaresStaticTrue(body, 'shadow')) {
-      return { interactive: true, reason: 'declares static shadow (DSD must re-attach on a client swap)' };
-    }
-    // `static refresh = true` is the explicit opt-in to ship a bare async
-    // component so its stale-while-revalidate refresh runs ~after SSR; eliding
-    // a bare async component drops that on-load re-fetch (moot for request-
-    // stable data, the default), so an author who wants fresh-on-load opts in.
-    if (declaresStaticTrue(body, 'refresh')) {
-      return { interactive: true, reason: 'declares static refresh = true (keeps the on-load re-fetch)' };
+    // 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).
+    for (const field of INTERACTIVITY_STATIC_FIELDS) {
+      if (declaresStaticTrue(body, field)) {
+        return { interactive: true, reason: STATIC_FIELD_REASONS[field] };
+      }
     }
     for (const hook of CLIENT_LIFECYCLE_HOOKS) {
       // A client lifecycle hook as a method (`hook(`) OR as an arrow class

package/src/dev.js

@@ -686,6 +686,14 @@ export async function createRequestHandler(opts) {
     middleware: null,
     bodyLimits,
     logger,
+    // Test-mode serve gate (#806). Set ONLY by the browser-test harness
+    // (`@webjsdev/server/testing`'s `createBrowserTestHandler`), NEVER by
+    // `webjs dev` / `webjs start`. When true the source-serve gate is relaxed
+    // so ANY app file under appDir is servable (a component a browser test
+    // imports is not route-reachable, so it is absent from `browserBoundFiles`
+    // and would 404). The `.server.*` guardrail (source -> RPC/throw stub) and
+    // the core / vendor serving are unchanged, so no server source is exposed.
+    testMode: opts.testMode === true,
     moduleGraph: null,
     elidableComponents: new Set(),
     inertRouteModules: new Set(),
@@ -1864,8 +1872,16 @@ async function handleCore(req, ctx) {
     // files (.server.{js,ts}) get a stub via the guardrail below; they
     // ARE included in browserBoundFiles because client code imports
     // them by path (the import rewrites to an RPC stub at request time).
-    const inGraph = state.browserBoundFiles && state.browserBoundFiles.has(abs);
-    if (abs.startsWith(appDir) && inGraph && (await exists(abs))) {
+    // In test mode any app file is servable (see the `state.testMode` note
+    // above); otherwise the file must be in the browser-bound module graph.
+    const inGraph = state.testMode || (state.browserBoundFiles && state.browserBoundFiles.has(abs));
+    // Containment: `abs` must be appDir itself or genuinely UNDER it. The
+    // trailing `sep` (matching the public-asset branch) stops a `..` path that
+    // resolves to a sibling sharing the appDir name-prefix (`/x/app` ->
+    // `/x/app-secrets/...`) from passing in test mode, where graph membership
+    // is not the gate.
+    const underAppDir = abs === appDir || abs.startsWith(appDir + sep);
+    if (underAppDir && inGraph && (await exists(abs))) {
       // Server-file guardrail: a file matching `.server.{js,ts,mjs,mts}`
       // MUST NEVER be served as source to the browser. The extension is
       // the path-level boundary; we re-verify it on every request (not

package/src/module-graph.js

@@ -447,6 +447,24 @@ async function parseFile(file, appDir, graph, seen, dynamic, bare) {
       // position is blanked in the mask, the match lives inside a literal
       // and is not a real import edge.
       if (masked[m.index] === ' ') continue;
+      // A statement-leading `import type { X }` / `import type * as X` /
+      // `import type Foo` (default type import) / `export type { X }` /
+      // `export type *` is fully erased by the TS stripper, so it never becomes
+      // a browser fetch or a runtime edge. Skip it, so a type-only import of a
+      // `.server.ts` (a common, correct way to share a derived row type) is not
+      // mistaken for a runtime dependency by the gate / elision / the
+      // no-server-import check. Two carve-outs keep this from over-dropping:
+      //   - `import type from '...'` is a VALUE default import whose binding is
+      //     literally named `type` (the stripper keeps it), so `type` directly
+      //     followed by `from` is NOT type-only.
+      //   - a MIXED `import { type A, b }` does NOT lead with `type`, so it is
+      //     kept (its `b` binding is a real runtime edge).
+      // #805
+      const lead = m[0];
+      const typeOnly =
+        /^(?:import|export)\s+type\s*[{*]/.test(lead) ||
+        (/^import\s+type\s+[A-Za-z_$]/.test(lead) && !/^import\s+type\s+from\b/.test(lead));
+      if (typeOnly) continue;
       const spec = m[1];
       // Guard a match whose `from '<spec>'` tail reaches INTO a blanked literal:
       // EXPORT_FROM_RE's lazy `[^'";]+?` can span a template body to a `from`

package/src/testing.d.ts

@@ -103,3 +103,13 @@ export declare function rawActionRequest(
     contentType?: string;
   },
 ): Promise<Response>;
+
+/** Browser-test harness (#806): a webjs handler a web-test-runner config
+ * proxies module requests to, so a browser test can import a real `.ts`
+ * component that imports a `'use server'` action. `importmapHtml()` is the
+ * `<script type="importmap">` to inject into the test page (call after warmup). */
+export declare function createBrowserTestHandler(appDir: string): Promise<{
+  handle: Handle;
+  warmup: () => Promise<void>;
+  importmapHtml: () => string;
+}>;

package/src/testing.js

@@ -348,3 +348,38 @@ export async function rawActionRequest(app, serverFilePath, fnName, args = [], o
 
   return testRequest(handle, endpoint, { method: 'POST', headers, body });
 }
+
+/**
+ * Browser-test harness (#806): build a webjs handler that a `web-test-runner`
+ * config can proxy module requests to, so a `test/**​/browser/*.test.js` file
+ * can import a real `.ts` component that imports a `'use server'` action and it
+ * loads + hydrates in a real browser. Plain WTR serves raw TS with no webjs
+ * transform, so the component (and its `#`-alias / `.server.ts` imports) never
+ * resolves; this handler runs the SAME dev pipeline (TS strip, `.server.ts` ->
+ * RPC stub, `#` alias, `/__webjs/core/*`, the importmap) as `webjs dev`.
+ *
+ * Uses `testMode` so ANY app file under appDir is servable (a component a test
+ * imports is not route-reachable, so it is absent from the browser-bound graph
+ * the normal serve gate requires). The `.server.*` source guardrail is
+ * unchanged, so no server source is exposed. `importmapHtml()` returns the
+ * `<script type="importmap">` to inject into the test page (call after warmup,
+ * so the map is final).
+ *
+ * The dev handler + importmap builder are LAZILY imported so importing the rest
+ * of `@webjsdev/server/testing` stays light (they pull the full server + the
+ * `ws` WebSocket subsystem).
+ *
+ * @param {string} appDir  the webjs app root (usually `process.cwd()`)
+ * @returns {Promise<{ handle: Handle, warmup: () => Promise<void>, importmapHtml: () => string }>}
+ */
+export async function createBrowserTestHandler(appDir) {
+  const { createRequestHandler } = await import('./dev.js');
+  const { importMapTag } = await import('./importmap.js');
+  const app = await createRequestHandler({ appDir, dev: true, testMode: true });
+  if (app.warmup) await app.warmup();
+  return {
+    handle: app.handle,
+    warmup: app.warmup || (async () => {}),
+    importmapHtml: () => importMapTag(),
+  };
+}