@webjsdev/server 0.9.0 → 0.10.1

package/src/client-signals.js

@@ -0,0 +1,171 @@
+/**
+ * Lexical signals of browser code, shared by the `webjs check` rules for the
+ * server / browser line (#1686) and the route-module hints `webjs status` and
+ * `webjs doctor` report. Nothing here decides what ships: a component always
+ * ships, and these only spot code that would silently never run.
+ *
+ * @module
+ */
+import { maskComments, redactToPlaceholders } from './js-scan.js';
+import { resolveImport } from './module-graph.js';
+
+/** A `.server.{js,ts,mjs,mts}` file. */
+const SERVER_FILE_RE = /\.server\.m?[jt]s$/;
+
+/**
+ * Named imports from a `@webjsdev/core` specifier that imply the
+ * component does reactive or async client work. Importing any of these
+ * forces the module to ship: signals re-render on change, Task resolves
+ * on the client, the streaming directives settle on the client, and
+ * Context consumers subscribe after upgrade.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const REACTIVE_IMPORTS = new Set([
+  'signal',
+  'computed',
+  'effect',
+  'watch',
+  // `optimistic(signal, value, action)` mutates a signal (client work) and
+  // settles after a server round-trip, so a component importing it is not
+  // display-only and must ship.
+  'optimistic',
+  'Task',
+  'until',
+  'asyncAppend',
+  'asyncReplace',
+  'ContextProvider',
+  'ContextConsumer',
+  'connectWS',
+  // `renderStream(payload)` applies a server stream-action payload to the live
+  // DOM (append/replace/remove), so a component importing it does client work
+  // and must ship (#248).
+  'renderStream',
+  // Client-only directives. `ref` / `createRef` fire a callback against the
+  // live element (focus, measure, third-party mount); `live` syncs an input
+  // value against the DOM. All produce identical SSR HTML but do real work
+  // only after upgrade, so a component using them must ship. Render-time
+  // directives (repeat, unsafeHTML, keyed, guard, cache, map) are NOT here:
+  // they are SSR-renderable and common in display-only components.
+  'ref',
+  'createRef',
+  'live',
+  // Custom directive authoring (Lit's `directive()`, `Directive`,
+  // `AsyncDirective`, from `@webjsdev/core/directive` and
+  // `@webjsdev/core/async-directive`). A directive class may hold per-part
+  // state and an AsyncDirective pushes values after upgrade through
+  // `setValue`, so the analyser cannot prove the SSR output is the whole
+  // story and a component importing one ships.
+  'directive',
+  'Directive',
+  'AsyncDirective',
+  // `ContextRoot` buffers context requests until a late provider upgrades,
+  // and `ContextProviderEvent` hands subscribers to a nearer provider; both
+  // only happen in the browser.
+  'ContextRoot',
+  'ContextProviderEvent',
+  // Lit's `SignalWatcher` mixin (an identity mixin here, watching is built
+  // in): a component that names it reacts to signals after upgrade.
+  'SignalWatcher',
+]);
+
+/** An event binding (`@event=${...}`), quoted or unquoted (invariant 4). */
+export const EVENT_BINDING_RE = /@[A-Za-z][\w-]*\s*=\s*["']?\$\{/;
+
+/**
+ * Identifiers that only exist in a browser; their presence means client work.
+ * Both this and COMPONENT_CLIENT_GLOBAL_RE are tested against the
+ * PLACEHOLDER redaction (`redactToPlaceholders`), never against raw or
+ * comment-masked source: a quoted string body or a template literal's TEXT is
+ * data, not a reference, so `'lucide-app-window'` must not read as `window`,
+ * while code inside a `${...}` hole stays real code and still matches. A global
+ * written in template text is SSR output (an inline `<script>` runs from the
+ * served HTML whether or not the module ships), the reasoning #623 applied to
+ * route modules, now extended to every module.
+ */
+export const CLIENT_GLOBAL_RE = /\b(?:window|document|navigator|localStorage|sessionStorage|customElements|matchMedia|addEventListener)\b/;
+
+/**
+ * Custom-element tag names a module references in its templates. A tag
+ * must contain a hyphen (HTML custom-element spec), which excludes
+ * native elements. Over-detection is safe: it only forces more modules
+ * to ship.
+ *
+ * @param {string} src raw module source
+ * @returns {Set<string>}
+ */
+export function extractRenderedTags(src) {
+  /** @type {Set<string>} */
+  const tags = new Set();
+  // Mask comments first so a `<some-tag>` written in a doc comment is not read
+  // as a rendered tag (#179). String and template content is kept, so real tags
+  // inside `html` templates are still found.
+  const masked = maskComments(src);
+  const re = /<([a-z][a-z0-9]*-[a-z0-9-]*)\b/g;
+  let m;
+  while ((m = re.exec(masked)) !== null) tags.add(m[1]);
+  return tags;
+}
+
+/** Reactive primitives: state a route module can hold but never update in a browser. */
+const REACTIVE_NAMES = new Set(['signal', 'computed', 'effect', 'watch']);
+const IMPORT_STMT_RE = /(?:^|[;\n])\s*import\s+(?:(type\s+)?([^'"`;]*?)\s+from\s+)?['"]__STR_(\d+)__['"]/g;
+const FIX_HINT = 'Move it into a component, or into `instrumentation-client.ts` for app-wide browser code.';
+
+/**
+ * Advisory notes on a ROUTE module's source (#1686): code that looks meant for
+ * the browser but runs only on the server, because a page, layout or boundary
+ * never loads there. Never a refusal: each pattern is legal on the server and
+ * merely does nothing useful, so the dev server and `webjs doctor`
+ * (`ROUTE_BROWSER_CODE`) surface these as hints.
+ *
+ * Reads the placeholder redaction, so a browser global written in a string or
+ * in template TEXT (an inline `<script>` that runs from the rendered HTML) is
+ * not a hint, while one in code or in a `${...}` hole is.
+ *
+ * @param {string} src  the route module's source
+ * @param {{ file: string, appDir: string, isComponent: (abs: string) => boolean, carriesComponent?: (abs: string) => boolean }} ctx
+ *   `carriesComponent` says whether a module leads to a component (a barrel of
+ *   component imports), whose components the boot already loads in its place
+ * @returns {string[]}
+ */
+export function routeModuleBrowserHints(src, { file, appDir, isComponent, carriesComponent }) {
+  /** @type {string[]} */
+  const hints = [];
+  const { redacted, literals } = redactToPlaceholders(src);
+  const global = CLIENT_GLOBAL_RE.exec(redacted);
+  if (global) {
+    hints.push(`\`${global[0]}\` is used, but this module runs only on the server, so that code never runs in a browser. ${FIX_HINT}`);
+  }
+  for (const m of redacted.matchAll(IMPORT_STMT_RE)) {
+    if (m[1]) continue; // `import type` is erased
+    const spec = literals[Number(m[3])];
+    const bindings = m[2];
+    if (spec === undefined) continue;
+    if (spec === '@webjsdev/core/client-router') {
+      hints.push('`@webjsdev/core/client-router` is imported, but this module never loads in a browser. The router starts by itself once any component loads, or import it from `instrumentation-client.ts`.');
+      continue;
+    }
+    if (bindings && /^@webjsdev\/core(\/signals)?$/.test(spec)) {
+      const names = (bindings.match(/\{([^}]*)\}/)?.[1] || '').split(',')
+        .map((n) => n.trim().split(/\s+as\s+/)[0].trim()).filter((n) => REACTIVE_NAMES.has(n));
+      if (names.length) {
+        hints.push(`\`${names[0]}\` is imported, but this module never hydrates, so its state never changes in a browser. Keep reactive state in a component.`);
+      }
+      continue;
+    }
+    if (bindings) continue;
+    // A side-effect import: anything it sets up happens on the server only.
+    if (/\.css$/.test(spec) || SERVER_FILE_RE.test(spec)) continue;
+    const local = spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('#');
+    if (local) {
+      const abs = resolveImport(spec, file, appDir);
+      if (!abs || isComponent(abs) || SERVER_FILE_RE.test(abs)) continue;
+      if (carriesComponent && carriesComponent(abs)) continue;
+    } else if (spec.startsWith('@webjsdev/') || spec.startsWith('node:')) {
+      continue;
+    }
+    hints.push(`The side-effect import of \`${spec}\` runs only on the server. If it sets something up in the browser, import it from a component or from \`instrumentation-client.ts\`.`);
+  }
+  return hints;
+}

package/src/component-scanner.js

@@ -169,7 +169,7 @@ export async function primeComponentRegistry(appDir, components) {
  * Per-file results of the orphan scan, validated on the exact source (#1575):
  * the dev server runs `findOrphanComponents` after every rebuild, and on a
  * large app re-scanning every unchanged file cost about 100 ms an edit.
- * @type {Map<string, { src: string, declared: Set<string>, registered: string[] }>}
+ * @type {Map<string, { src: string, declared: Set<string>, registered: string[], extended: Set<string> }>}
  */
 const ORPHAN_SCAN_CACHE = new Map();
 
@@ -177,7 +177,7 @@ const ORPHAN_SCAN_CACHE = new Map();
  * The classes one file declares as WebComponents and the ones it registers.
  * @param {string} file
  * @param {string} src
- * @returns {{ declared: Set<string>, registered: string[] }}
+ * @returns {{ declared: Set<string>, registered: string[], extended: Set<string> }}
  */
 function orphanScan(file, src) {
   const hit = ORPHAN_SCAN_CACHE.get(file);
@@ -198,7 +198,14 @@ function orphanScan(file, src) {
   // component NOR an orphan and vanished from every surface, which is the
   // exact shape the orphan report exists to catch.
   const registered = extractComponents(src).map((c) => c.className);
-  const entry = { src, declared, registered };
+  // Every class some other class extends. A base class its registered
+  // subclasses share (the kit's UiCarouselButton under UiCarouselPrevious and
+  // UiCarouselNext) is never meant to have a tag of its own, so it is not an
+  // orphan (#1686: the website warned about two of them on every boot).
+  const extended = new Set();
+  const baseRe = /\bclass\s+[A-Za-z_$][\w$]*\s+extends\s+([A-Z][A-Za-z0-9_$]*)\b/g;
+  while ((m = baseRe.exec(redacted)) !== null) if (m[1] !== 'WebComponent') extended.add(m[1]);
+  const entry = { src, declared, registered, extended };
   ORPHAN_SCAN_CACHE.set(file, entry);
   return entry;
 }
@@ -217,18 +224,14 @@ function orphanScan(file, src) {
  *     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.
+ *     ordinary code, so it runs only IF the module reaches the browser. A
+ *     route module never does (#1686), and an orphan is not in
+ *     `componentFiles`, so it never joins the frontier a route module emits in
+ *     its place. It loads only when a shipping component imports it, 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
+ * Lost in EVERY case, whichever shape: 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.
  *
@@ -262,6 +265,8 @@ export async function findOrphanComponents(appDir) {
   const declaredPerFile = [];
   /** @type {Set<string>} every class name registered ANYWHERE in the app */
   const registeredAnywhere = new Set();
+  /** @type {Set<string>} every class name another class extends, anywhere */
+  const extendedAnywhere = new Set();
 
   for await (const file of walk(appDir, filter)) {
     let src;
@@ -280,14 +285,15 @@ export async function findOrphanComponents(appDir) {
     // 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 { declared, registered } = orphanScan(file, src);
+    const { declared, registered, extended } = orphanScan(file, src);
     for (const cls of registered) registeredAnywhere.add(cls);
+    for (const cls of extended) extendedAnywhere.add(cls);
     if (declared.size) declaredPerFile.push({ file, declared });
   }
 
   for (const { file, declared } of declaredPerFile) {
     for (const cls of declared) {
-      if (!registeredAnywhere.has(cls)) orphans.push({ className: cls, file });
+      if (!registeredAnywhere.has(cls) && !extendedAnywhere.has(cls)) orphans.push({ className: cls, file });
     }
   }
   return orphans;

package/src/context.js

@@ -1,5 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { parseCookies } from './csrf.js';
+import { CookieStore, cookiesView } from './cookie-store.js';
 import { setCspNonceProvider, cspNonce } from '@webjsdev/core';
 import { shared } from './process-shared.js';
 
@@ -36,7 +36,10 @@ import { shared } from './process-shared.js';
  * wrong `revalidate` on a cookie-reading page fails safe (uncached) instead of
  * leaking one visitor's view to another.
  *
- * @typedef {{ req: Request, cspNonce?: string, bodyLimits?: { json: number, multipart: number }, requestId?: string, dynamicAccess?: boolean }} Store
+ * `revalidatedPaths` collects every `revalidatePath()` call made while serving
+ * the request, so an RPC action response can tell the browser to refresh them.
+ *
+ * @typedef {{ req: Request, cspNonce?: string, bodyLimits?: { json: number, multipart: number }, requestId?: string, dynamicAccess?: boolean, revalidatedPaths?: { path: string, layout: boolean }[], cookieStore?: CookieStore, cookiesSealed?: boolean, componentErrorSink?: (tag: string, error: unknown) => void }} Store
  */
 
 /** @type {AsyncLocalStorage<Store>} */
@@ -97,6 +100,43 @@ export function getBodyLimits() {
   return als.getStore()?.bodyLimits ?? null;
 }
 
+/**
+ * Set the app's `webjs.allowedOrigins` on the current store, so a check that
+ * runs inside a route handler (the auth routes' origin check, #1686) honours
+ * the same allowlist the action endpoint does.
+ * @param {string[]} origins
+ */
+export function setAllowedOrigins(origins) {
+  const store = als.getStore();
+  if (store) store.allowedOrigins = origins;
+}
+
+/** The app's cross-origin allowlist for this request, or [] outside one. */
+export function getAllowedOrigins() {
+  return als.getStore()?.allowedOrigins ?? [];
+}
+
+/**
+ * Set where the current request's isolated component render failures go. The
+ * dev handler sets one per request so a component that throws during SSR,
+ * which renders its error state in place and leaves the page at 200, still
+ * reaches the dev status `webjs status` reads.
+ *
+ * @param {(tag: string, error: unknown) => void} sink
+ */
+export function setComponentErrorSink(sink) {
+  const store = als.getStore();
+  if (store) store.componentErrorSink = sink;
+}
+
+// The core renderer has no server imports, so it reports an isolated component
+// failure through this process-wide hook, which forwards to the sink of the
+// request being rendered. Outside a request, or with no sink set, it is a no-op.
+globalThis[Symbol.for('webjs.ssr.componentError')] = (tag, error) => {
+  const sink = als.getStore()?.componentErrorSink;
+  if (typeof sink === 'function') sink(tag, error);
+};
+
 /**
  * Set the per-request correlation id on the current store (issue #239). The
  * handler calls this at the start of every request with either an inbound
@@ -195,28 +235,124 @@ export function headers() {
   // Accept-Language / Cookie read varies the output), so mark the request
   // dynamic so the HTML cache excludes it even under `revalidate` (#241).
   markDynamicAccess();
-  return req.headers;
+  let ro = _readonlyHeaders.get(req);
+  if (!ro) {
+    ro = new ReadonlyHeaders(req.headers);
+    _readonlyHeaders.set(req, ro);
+  }
+  return ro;
+}
+
+/** One read-only copy per request, so repeated `headers()` calls agree. */
+const _readonlyHeaders = shared('readonly-headers', () => new WeakMap());
+
+/**
+ * The request headers `headers()` returns, read-only as Next.js's
+ * `ReadonlyHeaders` is (#1686): writing them changed nothing anyone reads, so
+ * a `set` meant for the RESPONSE vanished silently. A write throws naming the
+ * places a response header or a cookie is actually set.
+ */
+class ReadonlyHeaders extends Headers {
+  /** @returns {never} */
+  append() { throw readonlyHeadersError(); }
+  /** @returns {never} */
+  set() { throw readonlyHeadersError(); }
+  /** @returns {never} */
+  delete() { throw readonlyHeadersError(); }
+}
+
+function readonlyHeadersError() {
+  const e = new Error(
+    'headers() is read-only, as in Next.js: it returns the REQUEST headers. To send a response '
+    + 'header, return it from a route handler or middleware (new Response(body, { headers })) or '
+    + 'set metadata.cacheControl on a page; to set a cookie, use cookies().set().',
+  );
+  e.name = 'ReadonlyHeadersError';
+  return e;
 }
 
 /**
- * Read-only cookie jar for the in-flight request. Returns an object with
- * `.get(name)`, `.has(name)`, `.entries()`. To SET a cookie, return a
- * `Response` whose headers include `Set-Cookie` (route handlers and
- * exposed actions can do this directly).
+ * The in-flight request's cookie store (Next.js's `cookies()` from
+ * `next/headers`). `get(name)` returns `{ name, value }` or undefined, so
+ * `cookies().get('theme')?.value` reads a value; `getAll`, `has`, `size` and
+ * iteration read; `set(name, value, options)` / `set({ name, value, ... })`
+ * and `delete(name)` write a `Set-Cookie` onto this request's response
+ * (applied by the request handler), and a later read in the same request sees
+ * the write. The result is also awaitable, so Next 15's
+ * `(await cookies()).get('theme')` works too. Throws outside a request.
+ *
+ * `options.maxAge` is in SECONDS (Next's unit) and `path` defaults to `/`.
  *
- * @returns {{ get: (name: string) => string | undefined, has: (name: string) => boolean, entries: () => [string, string][] }}
+ * @returns {ReturnType<typeof cookiesView>}
  */
 export function cookies() {
-  const req = getRequest();
-  if (!req) throw new Error('cookies(): called outside a request scope');
+  const store = als.getStore();
+  if (!store) throw new Error('cookies(): called outside a request scope');
   // Reading cookies makes the render per-user (a logged-in vs logged-out body
   // keys off an auth cookie), so mark the request dynamic so the HTML cache
   // excludes it even under `revalidate`, the core leak defense (#241).
   markDynamicAccess();
-  const map = parseCookies(req);
-  return {
-    get: (name) => map[name],
-    has: (name) => Object.prototype.hasOwnProperty.call(map, name),
-    entries: () => Object.entries(map),
-  };
+  return cookiesView(requestCookieStore(store));
+}
+
+/**
+ * The request's cookie store, created on first use. Shared by `cookies()` and
+ * middleware's `request.cookies`, so a write through either is one write.
+ * @param {Store} [store]
+ * @returns {CookieStore}
+ */
+export function requestCookieStore(store = als.getStore()) {
+  if (!store) throw new Error('cookies(): called outside a request scope');
+  if (!store.cookieStore) {
+    store.cookieStore = new CookieStore(store.req.headers.get('cookie'));
+    if (store.cookiesSealed) store.cookieStore.sealed = true;
+  }
+  return store.cookieStore;
+}
+
+/**
+ * Seal the request's cookies once its response headers are decided: a later
+ * `cookies().set()` / `.delete()` (a component rendering inside a streamed
+ * boundary) throws instead of being silently lost. Reads stay allowed.
+ */
+export function sealCookies() {
+  const store = als.getStore();
+  if (!store) return;
+  store.cookiesSealed = true;
+  if (store.cookieStore) store.cookieStore.sealed = true;
+}
+
+/**
+ * The current request's cookie store if one was created, for the handler to
+ * apply its pending `Set-Cookie` writes. Null when no code touched cookies.
+ * @returns {CookieStore | null}
+ */
+export function currentCookieStore() {
+  return als.getStore()?.cookieStore || null;
+}
+
+/**
+ * Record a `revalidatePath()` call against the current request (a no-op with
+ * no ambient request).
+ * @param {string} path app-root-relative pathname, or a route pattern
+ * @param {boolean} layout Next's `'layout'` type
+ */
+export function recordRevalidatedPath(path, layout) {
+  const store = als.getStore();
+  if (!store) return;
+  (store.revalidatedPaths ||= []).push({ path, layout });
+}
+
+/**
+ * The `x-webjs-refresh` header value for the paths revalidated during this
+ * request, or null when there were none. Each path is percent-encoded (a path
+ * may contain a comma) and a layout entry carries a `;layout` suffix.
+ * @returns {string | null}
+ */
+export function refreshHeaderValue() {
+  const list = als.getStore()?.revalidatedPaths;
+  if (!list || !list.length) return null;
+  const seen = new Set();
+  for (const { path, layout } of list) seen.add(encodeURIComponent(path) + (layout ? ';layout' : ''));
+  return [...seen].join(',');
 }