@webjsdev/core 0.7.45 → 0.7.47

package/index-browser.js

@@ -30,6 +30,11 @@ export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
 export { cspNonce } from './src/csp-nonce.js';
+export { asset } from './src/asset-url.js';
+// Form actions (#1155). The field name is shared with the server dispatcher;
+// `setFormActionResolver` is server-only wiring and is stripped here, because
+// a browser stub carries its own identity and needs no resolver.
+export { FORM_ACTION_FIELD, FORM_ACTION_ID_KEY } from './src/form-action.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';

package/index.d.ts

@@ -52,6 +52,8 @@ export type {
   WebjsRedirectRule,
   WebjsTrailingSlash,
   WebjsCspConfig,
+  WebjsDoctorConfig,
+  WebjsDoctorSeverity,
 } from './src/webjs-config.d.ts';
 
 // Compile-time serializability typing for server actions (#488): the opt-in
@@ -104,6 +106,8 @@ export { Task, TaskStatus } from './src/task.js';
 // src/*.d.ts (#388 fixed the index.d.ts drift from index.js).
 export { signal, computed, effect, batch, isSignal, Signal } from './src/signal.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
+export { asset, setAssetUrlProvider } from './src/asset-url.js';
+export { FORM_ACTION_FIELD, FORM_ACTION_ID_KEY, setFormActionResolver } from './src/form-action.js';
 export { takeSeed, scanSeeds, SEED_MISS } from './src/action-seed-client.js';
 export { markStale, registerKeyTags, consumeStale, parseTagHeader, fetchMark } from './src/action-cache-client.js';
 // Client action-abort plumbing (#492): a superseded async render aborts its

package/index.js

@@ -15,6 +15,11 @@ export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, forbidden, unauthorized, isNotFound, isRedirect, isForbidden, isUnauthorized } from './src/nav.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
+export { asset, setAssetUrlProvider } from './src/asset-url.js';
+// Form actions (#1155). `FORM_ACTION_FIELD` is the hidden field both renderers
+// emit and the server's form dispatcher reads; `setFormActionResolver` is the
+// server-only wiring that maps a real action function back to its identity.
+export { FORM_ACTION_FIELD, FORM_ACTION_ID_KEY, setFormActionResolver } from './src/form-action.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.45",
+  "version": "0.7.47",
   "type": "module",
-  "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
+  "description": "The runtime for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Ships the html and css template tags, the WebComponent base class, signals, directives, and the isomorphic renderers.",
   "types": "./index.d.ts",
   "exports": {
     ".": {

package/src/asset-url.d.ts

@@ -0,0 +1,3 @@
+/** Content-hashed `public/` asset urls (#1194). Server-side resolver; the browser bundle drops setAssetUrlProvider and `asset` returns its argument. */
+export function setAssetUrlProvider(fn: (path: string) => string): void;
+export function asset(path: string): string;

package/src/asset-url.js

@@ -0,0 +1,99 @@
+/**
+ * Resolve a `public/` asset url to its content-fingerprinted form, so a
+ * deploy that changes the file changes the url and no cache can serve the
+ * previous bytes.
+ *
+ *   import { html, asset } from '@webjsdev/core';
+ *   html`<link rel="stylesheet" href=${asset('/public/app.css')}>`
+ *
+ * On the server, `@webjsdev/server` installs a provider that appends
+ * `?v=<content-hash>`; the framework then serves a `?v=`-carrying request
+ * `immutable` for a year instead of the short fallback. On the browser there
+ * is no provider and the path is returned UNCHANGED.
+ *
+ * USE IT IN A PAGE, LAYOUT, OR METADATA ROUTE, not inside a component that
+ * ships to the browser. Those modules render only on the server, so the
+ * fingerprinted url is the one the browser sees and keeps. A component is
+ * different: hydration is a full client RE-RENDER (`render-client.js` drops
+ * the hydrate marker and `createInstance` replaces the SSR'd children), so
+ * the client value overwrites the server one. With no provider in the
+ * browser, `asset()` returns the bare path there, so an `<img src=${asset(
+ * '/public/logo.svg')}>` inside a shipping component paints the hashed url
+ * at SSR and then swaps it for the un-hashed one on upgrade, fetching the
+ * same bytes twice and leaving the short-lived url in the DOM. It still
+ * WORKS (the path is always valid), which is why this is a convention rather
+ * than a `webjs check` rule, but it silently forfeits the caching the call
+ * was for. Import the asset url into a layout, or accept the plain path.
+ *
+ * The sibling `cspNonce()` carries the same server/browser asymmetry and the
+ * same scoping, for the same hydration reason.
+ *
+ * Call it INSIDE the render function, not at module scope. A depth-0 call is a
+ * module-scope side effect, which the elision analyser reads as client work, so
+ * hoisting `const CSS = asset('/public/app.css')` pins the whole page or layout
+ * into the browser bundle for no benefit. Resolver ordering is not the issue
+ * (the server installs its resolver at boot, before any app module loads).
+ *
+ * Under `webjs.basePath`, write the prefix yourself: `asset('/app/public/x.css')`.
+ * The framework only base-path-prefixes urls IT emits, so an author-written
+ * url is already your responsibility (an un-prefixed one 404s under a
+ * sub-path deploy with or without this helper). `asset()` strips the prefix
+ * to find the file and keeps it on the url it returns.
+ *
+ * Mark files that change only with a DEPLOY. The hash is memoized for the
+ * process lifetime, and prod never rebuilds, so a `public/` file rewritten in
+ * place while the server runs keeps its old url while being served `immutable`
+ * for a year. A build artifact (a compiled stylesheet, a bundled script, a
+ * committed image) is exactly right; a runtime-written upload is not, and
+ * should keep its plain path (or carry its own version in the filename).
+ *
+ * Why this is opt-in rather than automatic. An earlier attempt (#1196)
+ * rewrote asset urls by matching the assembled HTML, and two deep-review
+ * rounds found six major defects, five of them the same bug: at that layer
+ * framework output and author data are indistinguishable, so the matcher kept
+ * touching things it did not own (a custom element's reactive prop, a
+ * rendered code sample, a `rel=preload` hint whose real request comes from
+ * CSS, a data-driven `src` pointing at `/.env`). Marking the url at the point
+ * the author writes it makes the meaning unambiguous, so the blast radius is
+ * exactly the set of urls someone deliberately marked and nothing else in the
+ * document is ever read or rewritten.
+ *
+ * Scope note: only a `public/` path is fingerprinted, matching what the
+ * static-asset route will actually serve. Anything else is returned
+ * unchanged rather than guessed at.
+ */
+
+/** @type {((path: string) => string) | null} */
+let _provider = null;
+
+/**
+ * Internal: server-only wiring. `@webjsdev/server` calls this once at load
+ * time to install the real resolver. Browser builds never call it, so
+ * `asset()` stays an identity function there.
+ *
+ * @param {(path: string) => string} fn
+ * @returns {void}
+ */
+export function setAssetUrlProvider(fn) {
+  _provider = fn;
+}
+
+/**
+ * The runtime function. Returns the fingerprinted url on the server, or the
+ * path unchanged when there is no provider (browser), when fingerprinting is
+ * off (dev, so dev output stays byte-identical), or when the file cannot be
+ * resolved. Every failure mode degrades to the plain path, never to a broken
+ * one.
+ *
+ * @param {string} path  a root-absolute same-origin path, e.g. `/public/app.css`
+ * @returns {string}
+ */
+export function asset(path) {
+  if (typeof path !== 'string' || !path) return path;
+  if (!_provider) return path;
+  try {
+    return _provider(path) || path;
+  } catch {
+    return path;
+  }
+}

package/src/component.js

@@ -1,5 +1,6 @@
 import { render as clientRender } from './render-client.js';
 import { setActiveActionSignal } from './action-abort-client.js';
+import { carriesFunction } from './form-action.js';
 import { isCSS, adoptStyles } from './css.js';
 import { register, tagOf } from './registry.js';
 import { parse as deserializeProp } from './serialize.js';
@@ -99,6 +100,63 @@ function defaultHasChanged(a, b) {
   return a !== b;
 }
 
+/**
+ * `String(v)` that cannot itself throw.
+ *
+ * A rejection reason is whatever the author rejected with, and not every value
+ * converts to a primitive: `Object.create(null)` has no `toString`, and a
+ * revoked Proxy throws on any operation. Coercing one in an error-reporting
+ * path turned a reportable failure into a second, unreported one.
+ *
+ * @param {unknown} v
+ * @returns {string}
+ */
+function safeString(v) {
+  try {
+    return String(v);
+  } catch {
+    return Object.prototype.toString.call(v);
+  }
+}
+
+/**
+ * Warn that a function value was dropped rather than reflected (#1169).
+ *
+ * A silently missing attribute is its own confusion, so say what went and why.
+ * The message deliberately does NOT include the value: printing the source is
+ * the leak this guard exists to prevent, and a server log is not always a
+ * private place.
+ *
+ * UNCONDITIONAL, matching the `.prop=${fn}` unserializable-value drop in
+ * `render-server.js`, which is the sibling path this guard mirrors. Two
+ * reasons not to gate it on a dev flag. It fires only on a genuine mistake (a
+ * function is never a meaningful attribute value), so there is no volume to
+ * suppress, and reflection runs per assignment rather than per frame.
+ *
+ * More decisively, a `NODE_ENV` gate does not survive the dist build.
+ * `scripts/build-framework-dist.js` runs esbuild with `platform: 'browser'`
+ * and `minify: true`, which substitutes `process.env.NODE_ENV` with
+ * `"production"` and folds the check to a constant. The SSR half of the
+ * warning would then be unreachable in every published build, which is how
+ * every installed app runs, and SSR is the half that matters most, since that
+ * is where the leaked source reached visitors.
+ *
+ * @param {{ constructor: unknown, tagName?: string }} host
+ * @param {string} propName
+ * @param {string} attrName
+ */
+function warnFunctionReflection(host, propName, attrName) {
+  if (typeof console === 'undefined' || !console.warn) return;
+  const tag = tagOf(/** @type any */ (host.constructor)) || host.tagName?.toLowerCase() || 'unknown';
+  console.warn(
+    `[webjs] reflect:true property "${propName}" on <${tag}> holds a function `
+    + `(or an array carrying one), which has no HTML attribute representation. `
+    + `Removing "${attrName}" instead of stringifying it (a stringified function `
+    + `writes its source into the page, so a server action's body would ship to `
+    + `the browser). Pass a string, or drop reflect on this property.`
+  );
+}
+
 /**
  * A minimal base for HTML Custom Elements that mirrors Lit's ergonomics
  * while staying JSDoc-only and no-build.
@@ -666,13 +724,43 @@ class WebComponentBase extends Base {
         const serialized = decl.converter.toAttribute(value, decl.type);
         if (serialized == null) this.removeAttribute(attrName);
         else this.setAttribute(attrName, serialized);
+      } else if (typeof value === 'function') {
+        // #1169: the value IS a function, and no branch below has a
+        // meaningful serialization for one. `String(fn)` is the function's
+        // SOURCE, so a reflected `'use server'` action would ship its whole
+        // body, closure secrets included, to every visitor, and
+        // `JSON.stringify(fn)` is `undefined`, which `setAttribute` writes as
+        // the literal string "undefined". Treat it like `null` and remove the
+        // attribute, matching what the `.prop=${fn}` SSR binding already does
+        // for an unserializable value.
+        //
+        // Placed AFTER the converter branch on purpose: a custom
+        // `toAttribute` is author-controlled, so its author has taken
+        // responsibility for serializing whatever they are handed.
+        this.removeAttribute(attrName);
+        warnFunctionReflection(this, propName, attrName);
       } else if (decl.type === Boolean) {
         if (value) this.setAttribute(attrName, '');
         else this.removeAttribute(attrName);
       } else if (value == null) {
         this.removeAttribute(attrName);
       } else if (decl.type === Object || decl.type === Array) {
+        // A JSON-typed prop CARRYING a function is safe and stays whole:
+        // `JSON.stringify` drops a function to `null` in an array and omits
+        // the key in an object, so `[1, 2, fn]` serializes to `[1,2,null]`
+        // with no source and no data loss. Refusing here would discard the
+        // `1` and the `2` on a path that never leaked.
         this.setAttribute(attrName, JSON.stringify(value));
+      } else if (carriesFunction(value)) {
+        // The string fall-through is the one place a CARRIED function still
+        // leaks. `String([fn])` is `Array.prototype.join`, which runs
+        // `String()` on every element, so `[serverAction]` writes the same
+        // source `serverAction` does. Hence the recursive predicate the
+        // form-action guard already uses, rather than a bare `typeof`, but
+        // scoped to this branch rather than applied above, where JSON
+        // handles the same shape losslessly.
+        this.removeAttribute(attrName);
+        warnFunctionReflection(this, propName, attrName);
       } else {
         this.setAttribute(attrName, String(value));
       }
@@ -1176,7 +1264,7 @@ class WebComponentBase extends Base {
       // (shouldUpdate=false) running during the fetch does NOT resolve
       // updateComplete early: the pending commit owns the resolution.
       this.__pendingAsyncCommits = (this.__pendingAsyncCommits || 0) + 1;
-      pendingCommit.then(() => {
+      const settle = () => {
         // Always decrement first, even when superseded, so the in-flight
         // count never leaks (a superseded cycle returns below without
         // committing, but it is no longer pending).
@@ -1189,6 +1277,37 @@ class WebComponentBase extends Base {
         }
         // --- 7-8 + updateComplete ---
         this._postCommit(changedProperties);
+      };
+      // A rejection has to settle the cycle too, or the counter stays >= 1
+      // forever: that both wedges `updateComplete` for this instance and
+      // disables the `!this.__pendingAsyncCommits` escape below for every
+      // later non-committing cycle. `_commitAsync` is written not to reject,
+      // but it is not the only thenable that reaches here: `update()` is a
+      // documented override point and may return one, so the handler belongs
+      // at this site rather than only at the one implementation of it.
+      pendingCommit.then(settle, (error) => {
+        // The token check gates the DOM write, NOT the release. A superseded
+        // cycle rejecting late (a discarded fetch, or the #492 abort of its own
+        // in-flight action surfacing as an AbortError) must not commit its
+        // error state over the newer render that already replaced it, which is
+        // the same rule both handlers inside _commitAsync follow. `settle()`
+        // still runs either way: it does its own token check before touching
+        // anything, and the decrement it owns has to happen regardless or the
+        // counter wedges exactly as it did before this handler existed.
+        // `finally`, not a trailing statement: the release must survive
+        // anything the reporting path throws. `String(error)` is evaluated in
+        // the argument expression, OUTSIDE _handleRenderError's own try/catch,
+        // so a rejection reason that cannot be coerced (a null-prototype
+        // object, a revoked Proxy) threw a TypeError straight out of this
+        // handler and skipped the decrement, wedging the counter in exactly
+        // the way this handler exists to prevent.
+        try {
+          if (token === this.__renderToken) {
+            this._handleRenderError(error instanceof Error ? error : new Error(safeString(error)));
+          }
+        } finally {
+          settle();
+        }
       });
       return;
     }
@@ -1399,7 +1518,23 @@ class WebComponentBase extends Base {
     return Promise.resolve(pending).then(
       (tpl) => {
         if (token !== this.__renderToken) return; // superseded by a newer render
-        clientRender(tpl, this._renderRoot);
+        // The COMMIT throws too, not just the fetch, and a sibling rejection
+        // handler cannot see it: `.then(onFulfil, onRejected)` never routes
+        // onFulfil's own throw to onRejected. Left uncaught, the returned
+        // promise rejected and _performRender's `.then` had no rejection
+        // handler, so the error escaped as an unhandled rejection,
+        // renderError() never ran, __pendingAsyncCommits never decremented
+        // (wedging it >= 1 forever, which also disables the non-committing
+        // cycle's _resolveUpdate escape), and updateComplete never settled.
+        // The sync path routes an identical throw to the same boundary, so
+        // this is what makes the two paths agree.
+        try {
+          clientRender(tpl, this._renderRoot);
+        } catch (commitError) {
+          this._handleRenderError(
+            commitError instanceof Error ? commitError : new Error(String(commitError)),
+          );
+        }
       },
       (error) => {
         if (token !== this.__renderToken) return;

package/src/form-action.d.ts

@@ -0,0 +1,16 @@
+/** Form actions (#1155): `<form action=${importedAction}>` and its wire. */
+
+/** The hidden field carrying a bound action's identity into the submission. */
+export const FORM_ACTION_FIELD: '__webjs_action';
+
+/** The property a generated client RPC stub carries its own identity on. */
+export const FORM_ACTION_ID_KEY: '$$webjsAction';
+
+/**
+ * Server-only wiring: maps a REAL server-action function back to its
+ * `<hash>/<fn>` identity. `@webjsdev/server` installs it at boot; the browser
+ * bundle drops it, because a stub carries its identity on itself.
+ */
+export function setFormActionResolver(
+  fn: (fn: Function) => string | null | Promise<string | null>,
+): void;