@webjsdev/core 0.7.45 → 0.7.46

package/index-browser.js

@@ -30,6 +30,7 @@ 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';
 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

@@ -104,6 +104,7 @@ 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 { 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,7 @@ 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';
 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,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.45",
+  "version": "0.7.46",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

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

@@ -99,6 +99,25 @@ 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);
+  }
+}
+
 /**
  * A minimal base for HTML Custom Elements that mirrors Lit's ergonomics
  * while staying JSDoc-only and no-build.
@@ -1176,7 +1195,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 +1208,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 +1449,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.js

@@ -0,0 +1,163 @@
+import { isBindingPrefix } from './binding-prefixes.js';
+
+/**
+ * Form-action attribute guard (#1154).
+ *
+ * Both SSR state machines and the client renderer import from here so the
+ * rule cannot drift between them. Each renderer commits attribute, boolean and
+ * property holes on separate branches, so the rule has more call sites than it
+ * looks like from any one file, and they are easy to change one at a time.
+ * That is why the predicate lives here rather than at each site.
+ *
+ * Two entry points, and the difference between them is the point:
+ * `assertNotFunctionActionAttr` is name-based, because an ATTRIBUTE is
+ * stringified into the markup on whatever tag it appears.
+ * `assertNotFunctionReflectedActionProp` is name-and-tag-based, because a
+ * PROPERTY only reaches the markup where the DOM reflects it. Using the first
+ * on the property path refused `<div .action=${fn}>`, which never leaked.
+ *
+ * The second SSR machine (`streamTemplate`) is reached only through
+ * `renderToStream(v, { ssr: false })`, which no page render uses: the server
+ * renders every page, Suspense included, via `renderToString`. Guarding it is
+ * about the public API surface rather than a live page leak, so do not infer
+ * from a bug there that pages were affected.
+ */
+
+/**
+ * Refuse to stringify a function interpolated into a form-action attribute.
+ *
+ * At SSR a `'use server'` import is the REAL server function (the RPC stub
+ * only exists in the browser), and a plain attribute hole commits via
+ * `String(val)`, so without this guard the action's SOURCE, secrets included,
+ * is serialized into the served HTML. The client renderer guards the same
+ * commit so a client re-render cannot write the source into the live DOM
+ * through a template binding. It does NOT cover property REFLECTION: a prop
+ * declared `reflect: true` writes `String(value)` to its attribute from the
+ * setter, which is not a commit site and is not reachable from here.
+ *
+ * Name-based on purpose (`action`, plus `formaction`, the submit-button
+ * override, which leaks identically): a function stringified under these
+ * names is never useful on any tag, and other attributes keep today's
+ * stringify behaviour so the claim stays narrow.
+ *
+ * @param {unknown} val the hole's resolved value
+ * @param {string} attrName the attribute being committed (any case)
+ * @param {string} [tag] lowercased owner tag, for the error message
+ */
+export function assertNotFunctionActionAttr(val, attrName, tag) {
+  if (!carriesFunction(val)) return;
+  if (!isFormActionAttr(attrName)) return;
+  throw new Error(formActionError(attrName, tag));
+}
+
+/**
+ * Refuse a function in a `.prop` binding, but ONLY where that property is a
+ * reflected IDL attribute and therefore really does write the source out.
+ *
+ * The attribute form leaks on any tag, because an attribute is stringified
+ * into the HTML wherever it appears. A PROPERTY is different: it leaks only
+ * when the DOM reflects it back to an attribute, and that is per element.
+ * `action` reflects on `<form>`; `formAction` reflects on `<button>` and
+ * `<input>`. Anywhere else (`<div .action=${fn}>`, `<li .action=${fn}>`, and
+ * `.action` on a `<button>`) the property is a plain expando: nothing is
+ * stringified and nothing reaches the markup.
+ *
+ * Gating on "is not a custom element" instead refused all of those, which is a
+ * false positive on a binding WebJs supports and that never leaked. A guard
+ * that turns a working delegated-command pattern (`<button .action=${() =>
+ * save(row)}>`) into a render error is not a narrower claim, it is a wrong one.
+ *
+ * A custom element is excluded for the same reason rather than a different
+ * one: it has no IDL reflection, so its `.action` is an author-defined
+ * property and a function is a legitimate value. Note the separate path that
+ * DOES write the source there, a prop declared `reflect: true`, which runs in
+ * the setter and never reaches any commit site.
+ *
+ * @param {unknown} val the hole's resolved value
+ * @param {string} propName the property being assigned (any case)
+ * @param {string} [tag] lowercased owner tag
+ */
+export function assertNotFunctionReflectedActionProp(val, propName, tag) {
+  if (!reflectsAsFormAction(propName, tag)) return;
+  assertNotFunctionActionAttr(val, propName, tag);
+}
+
+/**
+ * Is `propName` an IDL attribute that `tag` reflects to a content attribute?
+ * @param {string} propName
+ * @param {string} [tag]
+ * @returns {boolean}
+ */
+function reflectsAsFormAction(propName, tag) {
+  let name = String(propName).toLowerCase();
+  if (isBindingPrefix(name[0])) name = name.slice(1);
+  const owner = String(tag || '').toLowerCase();
+  if (name === 'action') return owner === 'form';
+  if (name === 'formaction') return owner === 'button' || owner === 'input';
+  return false;
+}
+
+/**
+ * Does stringifying this value expose a function's source?
+ *
+ * The commit sites do `String(val)`, and `Array.prototype.toString` stringifies
+ * each element through `String()` too, so `action=${[serverAction]}` leaks
+ * exactly as `action=${serverAction}` does. Recursive because nested arrays
+ * join the same way.
+ *
+ * Tracks visited arrays because `Array.prototype.join` has a cycle guard and
+ * this has to match it. A self-referential array stringifies to `''` rather
+ * than recursing forever, so a naive walk would turn a render that used to
+ * succeed into a stack overflow. Refusing to leak must not become a new way
+ * to crash.
+ *
+ * Deliberately NOT a check on the stringified result: sniffing the output for
+ * something function-shaped would misfire on a legitimate URL, and the value's
+ * shape is the thing actually being claimed. An object with a hand-written
+ * `toString` that returns a function's source is out of scope; that is
+ * deliberate exfiltration, not the accident this guards.
+ *
+ * @param {unknown} val
+ * @param {Set<unknown>} [seen]
+ * @returns {boolean}
+ */
+function carriesFunction(val, seen) {
+  if (typeof val === 'function') return true;
+  if (!Array.isArray(val)) return false;
+  const visited = seen || new Set();
+  if (visited.has(val)) return false;
+  visited.add(val);
+  return val.some((v) => carriesFunction(v, visited));
+}
+
+/**
+ * Is this the name of a form-action attribute?
+ *
+ * Strips a leading binding sigil before comparing. The SSR state machines
+ * accumulate the AUTHORED name, and only the unquoted `after-eq` branch splits
+ * the prefix off, so a quoted hole arrives here as `.action` / `?action` /
+ * `@action` with the sigil still attached. Comparing the raw name let every one
+ * of those through, which is the same leak wearing a different hat: the
+ * renderer treats a quoted binding hole as a plain attribute and stringifies it.
+ *
+ * @param {string} attrName
+ * @returns {boolean}
+ */
+function isFormActionAttr(attrName) {
+  let name = String(attrName).toLowerCase();
+  if (isBindingPrefix(name[0])) name = name.slice(1);
+  return name === 'action' || name === 'formaction';
+}
+
+/**
+ * The refusal message. Deliberately never echoes the function's source, which
+ * is the very thing being withheld.
+ * @param {string} attrName
+ * @param {string} [tag]
+ */
+function formActionError(attrName, tag) {
+  return `[webjs] a function was interpolated into ${String(attrName).toLowerCase()}= `
+    + `on <${tag || 'form'}>. Stringifying a function into HTML would leak its `
+    + `source (a 'use server' action's body included) to every visitor, so this `
+    + `is refused. Pass a URL string instead.`;
+}

package/src/render-client.js

@@ -1,6 +1,7 @@
 import { isTemplate, MARKER } from './html.js';
 import { BINDING_PREFIXES, isBindingPrefix } from './binding-prefixes.js';
 import { escapeAttr } from './escape.js';
+import { assertNotFunctionActionAttr, assertNotFunctionReflectedActionProp } from './form-action.js';
 import { isRepeat } from './repeat.js';
 import { isUnsafeHTML, isLive, isKeyed, isGuard, isTemplateContent, isRef, isCache, isUntil, isAsyncAppend, isAsyncReplace, isWatch } from './directives.js';
 import { Signal } from './signal.js';
@@ -671,17 +672,41 @@ function applyPart(part, value, _prev, allValues) {
       break;
     case 'attr': {
       if (value == null || value === false) part.el.removeAttribute(part.name);
-      else part.el.setAttribute(part.name, String(value));
+      else {
+        // #1154: refuse to stringify a function into action=/formaction=
+        // (mirrors the SSR guard, so a client re-render cannot write a
+        // server action's source into the live DOM).
+        assertNotFunctionActionAttr(value, part.name, part.el.localName);
+        part.el.setAttribute(part.name, String(value));
+      }
       break;
     }
     case 'prop':
+      // `.action=${fn}` is a leak too, not just the attribute form, but only
+      // where the property is a REFLECTED IDL attribute: assigning a function
+      // to `form.action` (or `.formAction` on a button/input) stringifies it
+      // into that element's own content attribute in a real browser. On any
+      // other native tag it is a plain expando that reflects nothing, and on a
+      // custom element it is an author-defined property, so a function is
+      // legitimate in both. The helper owns that distinction.
+      //
+      // Not covered here, because it is not a commit: a custom element's prop
+      // declared `reflect: true` writes String(value) from its own setter.
+      assertNotFunctionReflectedActionProp(value, part.name, part.el.localName);
       /** @type any */ (part.el)[part.name] = value;
       break;
     case 'bool':
+      // #1154: never leaked (a boolean binding stringifies nothing), but
+      // `?action=${fn}` is meaningless in every case, and refusing it keeps
+      // this renderer agreeing with both SSR machines.
+      assertNotFunctionActionAttr(value, part.name, part.el.localName);
       if (value) part.el.setAttribute(part.name, '');
       else part.el.removeAttribute(part.name);
       break;
     case 'event':
+      // NOT guarded, deliberately. An event binding never stringifies its
+      // value, and a function is the legitimate thing to pass one, so
+      // `<my-el @action=${handler}>` has to keep working.
       part.handler = typeof value === 'function' ? /** @type any */ (value) : null;
       break;
     case 'element':
@@ -692,7 +717,10 @@ function applyPart(part, value, _prev, allValues) {
       const mp = /** @type {{ statics: string[], group: number[] }} */ (/** @type any */ (part));
       let val = mp.statics[0];
       for (let j = 0; j < mp.group.length; j++) {
-        val += String((allValues ? allValues[mp.group[j]] : value) ?? '');
+        const piece = allValues ? allValues[mp.group[j]] : value;
+        // #1154: same function guard for each piece of a mixed attribute.
+        assertNotFunctionActionAttr(piece, part.name, part.el.localName);
+        val += String(piece ?? '');
         val += mp.statics[j + 1] || '';
       }
       part.el.setAttribute(part.name, val);