@webjsdev/server 0.8.58 → 0.8.60

package/index.d.ts

@@ -478,25 +478,114 @@ export declare function primeComponentRegistry(
 ): Promise<{ count: number }>;
 /** Extract `{ className, tag }` pairs from a component module's source. */
 export declare function extractComponents(src: string): Array<{ className: string; tag: string }>;
-/** Find component classes that no page / component imports (orphans). */
+/**
+ * Find ORPHAN component classes: a `class X extends WebComponent` that its own
+ * file declares and NOTHING in the app registers with a LITERAL tag, either
+ * because there is no registration call anywhere or because the tag is
+ * computed. The registration cross-reference is app-wide, so a class a sibling
+ * module registers is not an orphan. Neither is visible to the
+ * scanner, so both always lose the elision verdict, the tag-to-module registry
+ * entry, and the preload hint; assume the element does not upgrade either.
+ * This is about REGISTRATION, never about import reachability. The full
+ * semantics, including the one case where a computed tag still upgrades, live
+ * on `findOrphanComponents` in `src/component-scanner.js`.
+ */
 export declare function findOrphanComponents(
   appDir: string,
 ): Promise<Array<{ className: string; file: string }>>;
 
 // ---------------------------------------------------------------------------
-// elision-report.js (#646)
+// elision-report.js (#646, #1308)
 // ---------------------------------------------------------------------------
 
+/** Which rule in the analyser forced a component to ship. First match wins. */
+export type ElisionEvidence = 'own' | 'observed' | 'closure' | 'render' | 'import' | 'unreadable';
+
+/** One component module's verdict. `evidence` / `reason` / `by` are null when elided. */
+export interface ElisionComponentRow {
+  /** App-relative path of the component module. */
+  file: string;
+  /** Every tag this file registers, sorted. */
+  tags: string[];
+  verdict: 'elided' | 'shipped';
+  evidence: ElisionEvidence | null;
+  reason: string | null;
+  /** App-relative path of the module that forced the ship, where one did. */
+  by: string | null;
+}
+
+/** One page/layout route module's verdict. */
+export interface ElisionRouteModuleRow {
+  file: string;
+  verdict: 'inert' | 'import-only' | 'shipped';
+  /** For `import-only`: the component modules the boot emits in its place. */
+  emits: string[];
+  /** For `shipped`: the first client-effecting blocker, or null when its own code is the cause. */
+  blocker: string | null;
+  reason: string | null;
+}
+
+/** A `class X extends WebComponent` with no literal-tag registration. */
+export interface ElisionOrphanRow {
+  file: string;
+  className: string;
+}
+
+export interface ElisionSummary {
+  components: number;
+  elided: number;
+  shipped: number;
+  routeModules: number;
+  inert: number;
+  importOnly: number;
+  shippedWhole: number;
+  orphans: number;
+}
+
+/** The whole app-level elision verdict. Every path is app-relative; every array is sorted by `file`. */
+export interface ElisionReport {
+  analysed: boolean;
+  /** Why nothing was analysed, when `analysed` is false. */
+  skipped: 'no-app' | 'elide-off' | 'unanalysable' | null;
+  components: ElisionComponentRow[];
+  routeModules: ElisionRouteModuleRow[];
+  orphans: ElisionOrphanRow[];
+  summary: ElisionSummary;
+}
+
 /**
- * App-level elision report: the page/layout route modules that SHIP WHOLE to
- * the browser instead of being elided as carriers, each with the first
- * client-effecting blocker that pins it (or `null` when the module's own code
- * is the cause) plus a human reason. A reporting layer over `analyzeElision`,
- * consumed by the `webjs doctor` carrier-hygiene advisory (#646).
+ * App-level elision report, BOTH directions (#646, #1308): every component
+ * module as elided or shipped (a shipped one naming the evidence and the module
+ * that forced it), every page/layout as inert / import-only / shipped (a
+ * shipped one naming the first client-effecting blocker), and every orphan
+ * component class that gets no verdict at all. A reporting layer over
+ * `analyzeElision`, never a second analysis and never a build artifact.
+ * Consumed by `webjs elision`, the MCP `list_elision` tool, and both `webjs
+ * doctor` elision checks.
  */
-export declare function analyzeAppElision(
-  appDir: string,
-): Promise<{ analysed: boolean; shipped: Array<{ file: string; blocker: string | null; reason: string }> }>;
+export declare function analyzeAppElision(appDir: string): Promise<ElisionReport>;
+
+// ---------------------------------------------------------------------------
+// elision-differential.js (#1308)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mask the JS-loaded set (importmap, boot script, modulepreload hints, vendor
+ * connection hints, content stamps) out of an SSR response so a diff sees only
+ * observable output. The ONE definition shared by the framework's own
+ * differential guard and `webjs elision --verify`, so an app can diff its own
+ * two captures with exactly the framework's comparator.
+ */
+export declare function maskJsSet(html: string): string;
+
+/**
+ * The URL paths of every STATIC page route in a `buildRouteTable` result,
+ * sorted and deduped. Dynamic routes are excluded (rendering one would mean
+ * inventing param values).
+ */
+export declare function staticPageRoutes(table: {
+  pages?: Array<{ routeDir?: string; paramNames?: string[] }>;
+}): string[];
 
 // ---------------------------------------------------------------------------
 // context.js (per-request context helpers)
@@ -537,11 +626,26 @@ export declare function rateLimit(opts?: {
   key?: string | ((req: Request) => string | Promise<string>);
   message?: string;
   store?: CacheStore;
+  /**
+   * Bucket on the forwarded-IP headers (`X-Forwarded-For`, `CF-Connecting-IP`,
+   * `X-Real-IP`) instead of the framework-stamped peer. Inert while
+   * `WEBJS_NO_TRUST_PROXY=1` is set: that env switch is the operator's
+   * statement about the topology and it outranks this option, so the limiter
+   * falls back to the stamped peer and logs once. Only safe behind a proxy
+   * that STRIPS inbound `X-Forwarded-For` before adding its own.
+   */
   trustProxy?: boolean;
 }): Middleware;
 /** Parse a window string (`'1m'`, `'30s'`) to milliseconds. */
 export declare function parseWindow(w: number | string): number;
-/** Resolve the client IP for a request (honoring proxy-trust posture). */
+/**
+ * Resolve the client IP for a request (honoring proxy-trust posture).
+ *
+ * Defaults to the framework-stamped peer, or `_anon_` when there is none.
+ * `trustProxy: true` reads the forwarded-IP headers instead, UNLESS
+ * `WEBJS_NO_TRUST_PROXY=1` is set, which overrides the option back to the
+ * stamped peer and logs once per process.
+ */
 export declare function clientIp(req: Request, opts?: { trustProxy?: boolean }): string;
 /** Stamp the socket remote address onto a request for `clientIp` to read. */
 export declare function stampRemoteIp(req: Request, remoteAddress: string): void;
@@ -613,7 +717,16 @@ export declare function cache<T extends (...args: any[]) => Promise<any>>(
 export declare function revalidateTag(tag: string): Promise<void>;
 /** Evict every `cache()` entry tagged with any of `tags`. */
 export declare function revalidateTags(tags: string[]): Promise<void>;
-/** Evict the cached HTML for a path (the next request re-renders). */
+/**
+ * Evict the cached HTML for a path (the next request re-renders).
+ *
+ * Keys carry the request origin, so a bare path resolves it from the calling
+ * request, which is exact from a server action. Pass an absolute url
+ * (`https://app.example/blog`) from a caller with no request in scope (a cron
+ * job, a queue worker); a bare path there warns and evicts nothing. Under
+ * `webjs.basePath` the absolute url is the PUBLIC one and its mount prefix is
+ * stripped, so it evicts the entry the write actually stored.
+ */
 export declare function revalidatePath(path: string): Promise<void>;
 /** Evict all cached HTML (per-process generation bump). */
 export declare function revalidateAll(): Promise<void>;

package/index.js

@@ -44,6 +44,7 @@ export {
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';
 export { analyzeAppElision } from './src/elision-report.js';
+export { maskJsSet, staticPageRoutes } from './src/elision-differential.js';
 export { headers, cookies, getRequest, withRequest, cspNonce, requestId } from './src/context.js';
 export { defaultLogger } from './src/logger.js';
 export { rateLimit, parseWindow, clientIp, stampRemoteIp } from './src/rate-limit.js';
@@ -75,6 +76,7 @@ export {
   withCookies,
   withSessionCookie,
   loginAndGetCookies,
+  submitForm,
   actionEndpoint,
   invokeActionForTest,
   rawActionRequest,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.58",
+  "version": "0.8.60",
   "type": "module",
-  "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
+  "description": "The server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Provides the file-based router, SSR, server actions, route handlers, middleware, and live reload on Node 24+ or Bun.",
   "main": "index.js",
   "types": "./index.d.ts",
   "exports": {
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjsdev/core": "^0.7.46",
+    "@webjsdev/core": "^0.7.48",
     "ws": "^8.20.0"
   },
   "publishConfig": {

package/src/action-seed-bun.js

@@ -3,7 +3,7 @@
  *
  * Bun has no `module.registerHooks`, so the seed facade is installed via a
  * `Bun.plugin` `onLoad`, the Bun analog of the Node load hook in
- * `action-seed.js`. This module is dynamically imported by `registerSeedHooks`
+ * `action-seed.js`. This module is dynamically imported by `registerActionHooks`
  * ONLY when `serverRuntime()` is `'bun'`, so the `Bun.*` global is never
  * referenced on Node (the same isolation as `listener-bun.js`).
  *
@@ -28,7 +28,7 @@
 
 /**
  * Install the `Bun.plugin` seed `onLoad`. Idempotency is the caller's
- * responsibility (`registerSeedHooks` guards on `_registered`).
+ * responsibility (`registerActionHooks` guards on `_registered`).
  *
  * @param {{
  *   isSeedCandidate: (specifier: string) => boolean,