@webjsdev/core 0.8.0 → 0.9.1

package/src/directives.js

@@ -18,6 +18,7 @@
  *
  * @module directives
  */
+import { nothing, noChange } from './sentinels.js';
 
 // Re-export so the `/directives` subpath surface matches the documented table
 // in both src and dist mode. The implementation stays in repeat.js.
@@ -51,7 +52,24 @@ export { repeat, isRepeat } from './repeat.js';
  * @returns {{ _$webjs: 'unsafe-html', value: string }}
  */
 export function unsafeHTML(htmlString) {
-  return { _$webjs: 'unsafe-html', value: String(htmlString ?? '') };
+  const v = unsafeInput(htmlString, 'unsafeHTML');
+  return typeof v === 'string' ? { _$webjs: 'unsafe-html', value: v } : v;
+}
+
+/**
+ * The value an `unsafe*` directive was given, as Lit takes it (#1686):
+ * `nothing`, `null` or `undefined` render nothing, `noChange` keeps what is
+ * there, and anything else that is not a string throws (it used to be
+ * stringified, so `nothing` rendered as "Symbol(webjs.nothing)").
+ * @param {unknown} v
+ * @param {string} name
+ * @returns {string | typeof nothing | typeof noChange}
+ */
+function unsafeInput(v, name) {
+  if (v == null || v === nothing) return nothing;
+  if (v === noChange) return noChange;
+  if (typeof v !== 'string') throw new Error(`${name}() takes a string of trusted markup, not ${Array.isArray(v) ? 'an array' : typeof v}.`);
+  return v;
 }
 
 /**
@@ -63,6 +81,37 @@ export function isUnsafeHTML(x) {
   return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'unsafe-html';
 }
 
+/**
+ * Render a trusted SVG string inside an `<svg>` element (lit's `unsafeSVG`).
+ * The client parses the markup in the SVG namespace, so `<circle>` and
+ * `<path>` paint; the server emits it verbatim, exactly as `unsafeHTML` does.
+ * Same rule as `unsafeHTML`: NEVER pass user input.
+ *
+ * ```js
+ * html`<svg viewBox="0 0 10 10">${unsafeSVG(iconMarkup)}</svg>`;
+ * ```
+ *
+ * @param {string | null | undefined} svgString
+ * @returns {{ _$webjs: 'unsafe-html', value: string, ns: 'svg' }}
+ */
+export function unsafeSVG(svgString) {
+  const v = unsafeInput(svgString, 'unsafeSVG');
+  return typeof v === 'string' ? { _$webjs: 'unsafe-html', value: v, ns: 'svg' } : v;
+}
+
+/**
+ * Render a trusted MathML string inside a `<math>` element (lit's
+ * `unsafeMathML`). The client parses it in the MathML namespace; the server
+ * emits it verbatim. NEVER pass user input.
+ *
+ * @param {string | null | undefined} mathString
+ * @returns {{ _$webjs: 'unsafe-html', value: string, ns: 'mathml' }}
+ */
+export function unsafeMathML(mathString) {
+  const v = unsafeInput(mathString, 'unsafeMathML');
+  return typeof v === 'string' ? { _$webjs: 'unsafe-html', value: v, ns: 'mathml' } : v;
+}
+
 /* ================================================================
  * live
  * ================================================================ */
@@ -459,4 +508,112 @@ export function isWatch(x) {
   return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'watch';
 }
 
+/* ================================================================
+ * when / choose / map / join / range (lit-html parity)
+ *
+ * Plain functions, not markers: each returns an ordinary value (or a
+ * generator) the renderers already accept, so they behave identically on
+ * the server and the client and need no renderer support beyond iterables.
+ * ================================================================ */
+
+/**
+ * Render one of two templates on a condition. The case functions receive the
+ * condition value, as lit's `when` passes it.
+ *
+ * ```js
+ * html`${when(this.user, (u) => html`<p>Hi ${u.name}</p>`, () => html`<a href="/login">Sign in</a>`)}`;
+ * ```
+ *
+ * @template C, T, F
+ * @param {C} condition
+ * @param {(c: C) => T} trueCase
+ * @param {(c: C) => F} [falseCase]
+ * @returns {T | F | undefined}
+ */
+export function when(condition, trueCase, falseCase) {
+  return condition ? trueCase(condition) : falseCase?.(condition);
+}
+
+/**
+ * Render the case whose key is strictly equal (`===`) to `value`, else the
+ * default case, lit's `choose`.
+ *
+ * ```js
+ * html`${choose(this.tab, [
+ *   ['home', () => html`<home-tab></home-tab>`],
+ *   ['about', () => html`<about-tab></about-tab>`],
+ * ], () => html`<p>Not found</p>`)}`;
+ * ```
+ *
+ * @template T, V
+ * @param {T} value
+ * @param {Array<[T, () => V]>} cases
+ * @param {() => V} [defaultCase]
+ * @returns {V | undefined}
+ */
+export function choose(value, cases, defaultCase) {
+  for (const [key, fn] of cases) {
+    if (key === value) return fn();
+  }
+  return defaultCase?.();
+}
+
+/**
+ * Lazily map an iterable, lit's `map`. Returns a generator, which both
+ * renderers accept anywhere an array is.
+ *
+ * @template T, U
+ * @param {Iterable<T> | undefined} items
+ * @param {(value: T, index: number) => U} f
+ * @returns {Generator<U>}
+ */
+export function* map(items, f) {
+  if (items === undefined) return;
+  let i = 0;
+  for (const value of items) yield f(value, i++);
+}
+
+/**
+ * Interleave a separator between the items of an iterable, lit's `join`. The
+ * joiner is a value or a function of the separator's index.
+ *
+ * ```js
+ * html`${join(tags, html`<span>, </span>`)}`;
+ * ```
+ *
+ * @template I, J
+ * @param {Iterable<I> | undefined} items
+ * @param {J | ((index: number) => J)} joiner
+ * @returns {Generator<I | J>}
+ */
+export function* join(items, joiner) {
+  if (items === undefined) return;
+  const isFunction = typeof joiner === 'function';
+  let i = -1;
+  for (const value of items) {
+    if (i > -1) yield isFunction ? /** @type {any} */ (joiner)(i) : joiner;
+    i++;
+    yield value;
+  }
+}
+
+/**
+ * A generator of numbers, lit's `range`: `range(end)`, `range(start, end)` or
+ * `range(start, end, step)`. Pair it with `map` to render a counted list.
+ *
+ * ```js
+ * html`<ul>${map(range(3), (i) => html`<li>${i}</li>`)}</ul>`;
+ * ```
+ *
+ * @param {number} startOrEnd
+ * @param {number} [end]
+ * @param {number} [step]
+ * @returns {Generator<number>}
+ */
+export function* range(startOrEnd, end, step = 1) {
+  const start = end === undefined ? 0 : startOrEnd;
+  end ??= startOrEnd;
+  for (let i = start; step > 0 ? i < end : end < i; i += step) yield i;
+}
+
 export { classMap, styleMap, ifDefined } from './attribute-directives.js';

package/src/form-action.d.ts

@@ -14,3 +14,16 @@ export const FORM_ACTION_ID_KEY: '$$webjsAction';
 export function setFormActionResolver(
   fn: (fn: Function) => string | null | Promise<string | null>,
 ): void;
+
+/**
+ * Give an action (or its browser stub) a `.bind` that keeps its identity, so
+ * `<form action=${rsvp.bind(null, slug)}>` submits `rsvp(slug, formData)`.
+ * Wired by `@webjsdev/server` and by every generated stub; apps just call `.bind`.
+ */
+export function installActionBind<F extends Function>(fn: F): F;
+
+/** The identity a form submits for an action bound to `args` (`<hash>/<fn>#<args>`). */
+export function bindActionId(id: string, args: unknown[]): string;
+
+/** Split a submitted identity into the action's own identity and its bound arguments. */
+export function splitActionId(value: string): { id: string; args: unknown[] };

package/src/form-action.js

@@ -1,5 +1,6 @@
 import { isBindingPrefix } from './binding-prefixes.js';
 import { escapeAttr } from './escape.js';
+import { stringifySync, parse } from './serialize.js';
 
 /**
  * Form actions: binding a `'use server'` action straight into a form (#1155),
@@ -109,6 +110,89 @@ export const FORM_ACTION_FIELD = '__webjs_action';
  */
 export const FORM_ACTION_ID_KEY = '$$webjsAction';
 
+/**
+ * Bound form actions, Next.js's way to give a form action an extra argument:
+ * `<form action=${rsvp.bind(null, event.slug)}>` calls `rsvp(slug, formData)`.
+ * The arguments ride in the same hidden field as the identity, after a `#`
+ * (`<hash>/<fn>#<encoded args>`), so the submission works with JavaScript off
+ * and the server renderer, the browser renderer and the dispatcher share one
+ * encoding. They are not signed: an action is a public endpoint anyone can call
+ * with any arguments, so it authorizes them like any other input, as in Next.
+ */
+const BOUND_SEP = '#';
+
+/**
+ * The identity a form submits for `action` bound to `args`.
+ * @param {string} id the action's own `<hash>/<fn>` identity
+ * @param {unknown[]} args
+ * @returns {string}
+ */
+export function bindActionId(id, args) {
+  return args.length ? `${id}${BOUND_SEP}${encodeURIComponent(stringifySync(args))}` : id;
+}
+
+/**
+ * Split a submitted identity into the action's own identity and its bound
+ * arguments. Throws on an argument list that does not decode to an array.
+ * @param {string} value
+ * @returns {{ id: string, args: unknown[] }}
+ */
+export function splitActionId(value) {
+  const at = value.indexOf(BOUND_SEP);
+  if (at === -1) return { id: value, args: [] };
+  const args = parse(decodeURIComponent(value.slice(at + 1)));
+  if (!Array.isArray(args)) throw new TypeError('bound action arguments are not a list');
+  return { id: value.slice(0, at), args };
+}
+
+/**
+ * Bound functions made by an action's own `.bind`, mapped to the unbound
+ * action and every argument bound so far.
+ * @type {WeakMap<Function, { target: Function, args: unknown[] }>}
+ */
+const _bound = new WeakMap();
+
+/**
+ * Give a server action (or its browser stub) a `.bind` that keeps its identity,
+ * so the bound function can still be bound to a form. Called by the server's
+ * action wrapper and by every generated stub. Idempotent.
+ * @template {Function} F
+ * @param {F} fn
+ * @returns {F}
+ */
+export function installActionBind(fn) {
+  if (typeof fn !== 'function' || Object.prototype.hasOwnProperty.call(fn, 'bind')) return fn;
+  try {
+    Object.defineProperty(fn, 'bind', { value: bindAction, configurable: true, writable: true });
+  } catch {}
+  return fn;
+}
+
+/**
+ * `Function.prototype.bind`, plus the record that lets the renderers find the
+ * action and its arguments. The identity is a getter, computed when a form
+ * reads it, so a bound action called directly (over RPC, with a File among its
+ * arguments) never has to encode anything.
+ * @this {Function}
+ * @param {unknown} thisArg
+ * @param {...unknown} args
+ * @returns {Function}
+ */
+function bindAction(thisArg, ...args) {
+  const bound = Function.prototype.bind.call(this, thisArg, ...args);
+  const prev = _bound.get(this);
+  const target = prev ? prev.target : this;
+  const all = prev ? [...prev.args, ...args] : args;
+  _bound.set(bound, { target, args: all });
+  const own = formActionId(target);
+  if (own) {
+    try {
+      Object.defineProperty(bound, FORM_ACTION_ID_KEY, { get: () => bindActionId(own, all) });
+    } catch {}
+  }
+  return installActionBind(bound);
+}
+
 /** @type {((fn: Function) => (string | null | Promise<string | null>)) | null} */
 let _resolver = null;
 
@@ -155,6 +239,11 @@ export async function resolveFormActionId(fn) {
   const own = formActionId(fn);
   if (own) return own;
   if (typeof fn !== 'function' || !_resolver) return null;
+  const bound = _bound.get(fn);
+  if (bound) {
+    const base = await resolveFormActionId(bound.target);
+    return base ? bindActionId(base, bound.args) : null;
+  }
   try {
     const id = await _resolver(/** @type {Function} */ (fn));
     return typeof id === 'string' && id ? id : null;
@@ -491,6 +580,9 @@ export function assertSubmittableSubmitter(tag, formMethod, formEnctype) {
  */
 export function assertNotFunctionActionAttr(val, attrName, tag) {
   if (!carriesFunction(val)) return;
+  // Every attribute commit site already calls this guard, so the React-style
+  // `onClick=${fn}` refusal rides it too (one call site per renderer path).
+  assertNotFunctionEventAttr(val, attrName, tag);
   if (!isFormActionAttr(attrName)) return;
   throw new Error(formActionError(attrName, tag));
 }
@@ -552,19 +644,36 @@ export function assertNotFunctionReflectedActionProp(val, propName, tag) {
  * looks right and silently posts nowhere, which is the one outcome a
  * progressive-enhancement form must never have, so this throws instead.
  *
+ * A function made with the native `Function.prototype.bind` (anything but an
+ * action's own `.bind`, which keeps the identity) gets its own message, since
+ * the inline-`'use server'` advice would send its author the wrong way.
+ *
  * @param {string | null} id
  * @param {string} [tag]
+ * @param {unknown} [fn] the bound value, to name a `.bind()` result
  * @returns {string} the identity, narrowed
  */
-export function assertIdentifiableAction(id, tag) {
+export function assertIdentifiableAction(id, tag, fn) {
   if (id) return id;
   const attr = tag === 'button' || tag === 'input' ? 'formaction=' : 'action=';
+  if (typeof fn === 'function' && /^bound /.test(fn.name)) {
+    throw new Error(
+      `[webjs] the function in ${attr} on <${tag || 'form'}> is a bound function that is not a `
+      + `server action. Bind the imported action itself: action.bind(null, id) on a function `
+      + `exported from a 'use server' *.server.{js,ts} module keeps its identity, and the bound `
+      + `arguments arrive before the form data. See https://webjs.dev/docs/server-actions#bound-arguments`,
+    );
+  }
   throw new Error(
     `[webjs] the function in ${attr} on <${tag || 'form'}> is not a server action. `
     + `Only a function imported from a 'use server' *.server.{js,ts} module can be `
     + `bound to a form or a submitter, because the identity the browser submits `
-    + `has to resolve back to something the server can run. Move the handler into `
-    + `a server action and import it, or pass a url string.`,
+    + `has to resolve back to something the server can run. A 'use server' `
+    + `directive inside a function body (Next.js's inline action) is not one: the `
+    + `boundary is a file. Move the function into its own module, e.g. `
+    + `modules/<feature>/actions/<name>.server.ts starting with 'use server', `
+    + `export it and import it here, or pass a url string. `
+    + `See https://webjs.dev/docs/troubleshooting#inline-use-server`,
   );
 }
 
@@ -883,7 +992,7 @@ export function reconcileFormAction(form, value, method, enctype, shape) {
     // Not a bound action (a url string, null, or a function the browser stub
     // never stamped). A function that was MEANT as an action still refuses, so
     // a form never silently posts nowhere.
-    if (typeof value === 'function') assertIdentifiableAction(null, form.localName);
+    if (typeof value === 'function') assertIdentifiableAction(null, form.localName, value);
     releaseFormAction(form, method, enctype, shape.propAttrs);
     return;
   }
@@ -1256,3 +1365,29 @@ function formActionError(attrName, tag) {
     + `action=\${action} on the <form> itself or a formaction=\${action} on a `
     + `<button> inside a bound form. Anywhere else, pass a URL string.`;
 }
+
+/**
+ * Refuse a function interpolated into an `on*` ATTRIBUTE (`onClick=${fn}`,
+ * `onclick="${fn}"`, `?onclick=${fn}`), React's event spelling. An attribute
+ * stringifies its value, so the function's SOURCE would be written into the
+ * HTML as an inline handler that runs in the global scope with none of its
+ * closure: it never does what it says, and it ships the code to every
+ * visitor. A WebComponent template binds events with `@click=${fn}`.
+ *
+ * @param {unknown} val
+ * @param {string | undefined} attrName
+ * @param {string | undefined} tag
+ */
+export function assertNotFunctionEventAttr(val, attrName, tag) {
+  if (!carriesFunction(val)) return;
+  const name = String(attrName || '').replace(/^[?.@]/, '');
+  if (!/^on[a-z]/i.test(name)) return;
+  const event = name.slice(2).toLowerCase();
+  throw new Error(
+    `webjs: a function was interpolated into the \`${name}\` attribute on <${tag || 'element'}>. `
+    + `An attribute is a string, so the function's source would be written into the HTML as an inline handler `
+    + `that runs without its closure. Bind the event with \`@${event}=\${handler}\` in a WebComponent's render() `
+    + `(a page or layout never hydrates, so its handlers must live in a component). `
+    + `See https://webjs.dev/docs/troubleshooting#function-in-on-attribute`,
+  );
+}

package/src/hot.js

@@ -0,0 +1,23 @@
+/**
+ * The dev hot-swap seam (#1689). The dev server's reload client installs a hot
+ * client on `globalThis[Symbol.for('webjs.hot')]` before any component module
+ * runs; production never does, so each read here is one global lookup that
+ * finds nothing. No logic lives in core: the client is inlined into
+ * `/__webjs/reload.js` from `@webjsdev/server`'s `dev-hot-client.js`.
+ */
+const HOT = Symbol.for('webjs.hot');
+const g = /** @type {any} */ (globalThis);
+
+/**
+ * The template strings `html()` / `svg()` / `mathml()` keep. Under the dev
+ * hot client, textually identical templates share one strings object across
+ * module evaluations, so a hot swap rebuilds only the templates whose text
+ * changed.
+ * @param {TemplateStringsArray | string[]} s
+ * @param {0 | 1 | 2} kind `html`, `svg` or `mathml`, so equal text under two tags stays apart
+ * @returns {TemplateStringsArray | string[]}
+ */
+export function hotStrings(s, kind) { const h = g[HOT]; return h === undefined ? s : h.strings(s, kind); }
+
+/** @returns {((tag: string, prev: Function, next: Function) => Function) | null} */
+export function hotReplacer() { const h = g[HOT]; return h === undefined ? null : h.replace; }

package/src/html.d.ts

@@ -4,10 +4,14 @@ export interface TemplateResult {
   values: unknown[];
   /** Set by the `svg` tag: the client parses the strings inside an `<svg>` wrapper. */
   svg?: boolean;
+  /** Set by the `mathml` tag: the client parses the strings inside a `<math>` wrapper. */
+  mathml?: boolean;
 }
 
 export function html(strings: TemplateStringsArray | string[], ...values: unknown[]): TemplateResult;
 /** lit's `svg` tag: a fragment parsed as SVG on the client, rendered like `html` on the server. */
 export function svg(strings: TemplateStringsArray | string[], ...values: unknown[]): TemplateResult;
+/** lit's `mathml` tag: a fragment parsed as MathML on the client, rendered like `html` on the server. */
+export function mathml(strings: TemplateStringsArray | string[], ...values: unknown[]): TemplateResult;
 export function isTemplate(x: unknown): x is TemplateResult;
 export const MARKER: 'wjm-';

package/src/html.js

@@ -1,17 +1,35 @@
+import { hotStrings } from './hot.js';
+
 /**
  * Tagged template literal producing a {@link TemplateResult}.
  *
  * A TemplateResult is an isomorphic description of HTML: the static string
  * pieces plus the dynamic values. Server and client renderers both consume it.
  *
- * @typedef {{ _$webjs: 'template', strings: TemplateStringsArray | string[], values: unknown[], svg?: boolean }} TemplateResult
+ * @typedef {{ _$webjs: 'template', strings: TemplateStringsArray | string[], values: unknown[], svg?: boolean, mathml?: boolean }} TemplateResult
  *
  * @param {TemplateStringsArray | string[]} strings
  * @param {...unknown} values
  * @returns {TemplateResult}
  */
 export function html(strings, ...values) {
-  return { _$webjs: 'template', strings, values };
+  return { _$webjs: 'template', strings: hotStrings(trusted(strings), 0), values };
+}
+
+/**
+ * The renderers render a template result's strings as markup only when they
+ * carry `raw`, which a tagged template's strings always do, so a result that
+ * arrived as data (JSON with the `_$webjs` brand) is refused. A plain array
+ * passed to `html()` / `svg()` / `mathml()` is code, as `string[]` in the type
+ * says, so it is marked the same way (kept in place so the template cache
+ * still keys on it, copied only when frozen).
+ * @param {TemplateStringsArray | string[]} strings
+ */
+function trusted(strings) {
+  if (!Array.isArray(strings) || Object.prototype.hasOwnProperty.call(strings, 'raw')) return strings;
+  const target = Object.isExtensible(strings) ? strings : strings.slice();
+  Object.defineProperty(target, 'raw', { value: target });
+  return target;
 }
 
 /**
@@ -32,7 +50,21 @@ export function html(strings, ...values) {
  * @returns {TemplateResult}
  */
 export function svg(strings, ...values) {
-  return { _$webjs: 'template', strings, values, svg: true };
+  return { _$webjs: 'template', strings: hotStrings(trusted(strings), 1), values, svg: true };
+}
+
+/**
+ * Tagged template literal for a MathML FRAGMENT, lit's `mathml` tag: markup
+ * that sits inside a `<math>` element but is built in its own template. The
+ * client parses it inside a `<math>` wrapper so its elements land in the
+ * MathML namespace; the server renders it exactly like `html`.
+ *
+ * @param {TemplateStringsArray | string[]} strings
+ * @param {...unknown} values
+ * @returns {TemplateResult}
+ */
+export function mathml(strings, ...values) {
+  return { _$webjs: 'template', strings: hotStrings(trusted(strings), 2), values, mathml: true };
 }
 
 /**

package/src/is-server.d.ts

@@ -0,0 +1,2 @@
+/** lit's `isServer`: `true` outside a browser (the SSR pass), `false` in one. */
+export const isServer: boolean;

package/src/is-server.js

@@ -0,0 +1,18 @@
+/**
+ * `isServer`, lit's flag: `true` when this module runs outside a browser (the
+ * SSR pass on Node or Bun), `false` in a browser.
+ *
+ * Use it to guard browser-only work in code that also runs at SSR (a
+ * component's constructor, `render()`, `willUpdate()`, a controller's
+ * `hostUpdate()`):
+ *
+ * ```js
+ * import { isServer } from '@webjsdev/core';
+ * if (!isServer) this.width = window.innerWidth;
+ * ```
+ *
+ * Decided by the presence of `window` and `document`, the same test the
+ * `WebComponent` base uses to pick between `HTMLElement` and its server shim,
+ * so the two can never disagree.
+ */
+export const isServer = !(typeof window !== 'undefined' && typeof document !== 'undefined');

package/src/jsx-guard.js

@@ -0,0 +1,130 @@
+/**
+ * React-isms in an `html` template that can never work, found once per
+ * template (the compilers call this beside their compile cache), so the
+ * mistake is a loud render error naming the fix instead of a silently wrong
+ * page:
+ *
+ *   - `className=` / `htmlFor=`: JSX's DOM-property spellings. In HTML they
+ *     are plain unknown attributes (`classname`, `htmlfor`), so the class
+ *     never applies and the label never points at its control.
+ *   - A capitalised tag (`<Link>`, `<Button>`): a JSX component. HTML
+ *     lowercases it into an unknown element (`<link>` is even a void
+ *     metadata element), so nothing renders.
+ *
+ * The scan follows the HTML tokenizer states that matter: text, a start tag
+ * and its attributes, quoted values, comments, and raw text (`script`,
+ * `style`, `textarea`, `title`), so prose such as `&lt;Link&gt;` or a
+ * `className` mentioned in text is never flagged.
+ *
+ * @module jsx-guard
+ */
+
+const RAW = new Set(['script', 'style', 'textarea', 'title']);
+
+/**
+ * @typedef {{ kind: 'attr' | 'tag', name: string }} JsxIsm
+ */
+
+/**
+ * The first React-ism in a template's static strings, or null.
+ * @param {readonly string[]} strings
+ * @returns {JsxIsm | null}
+ */
+export function findJsxIsm(strings) {
+  let mode = 'text';      // text | tagname | tag | attr | q | comment | raw
+  let quote = '';
+  let name = '';
+  let tag = '';
+  let closing = false;
+  let rawTag = '';
+  for (let s = 0; s < strings.length; s++) {
+    const str = strings[s];
+    // A hole ends whatever name was being read.
+    if (s > 0) {
+      if (mode === 'tagname') mode = 'tag';
+      else if (mode === 'attr') { name = ''; mode = 'tag'; }
+    }
+    for (let i = 0; i < str.length; i++) {
+      const c = str[i];
+      switch (mode) {
+        case 'text':
+          if (c === '<') {
+            if (str.startsWith('<!--', i)) { mode = 'comment'; i += 3; }
+            else if (/[A-Za-z/]/.test(str[i + 1] || '')) {
+              closing = str[i + 1] === '/';
+              if (closing) i++;
+              mode = 'tagname';
+              tag = '';
+            }
+          }
+          break;
+        case 'tagname':
+          if (/[\s/>]/.test(c)) {
+            if (!closing && /^[A-Z](?=.*[a-z])/.test(tag)) return { kind: 'tag', name: tag };
+            mode = c === '>' ? afterTag(tag, closing) : 'tag';
+            if (mode === 'raw') rawTag = tag.toLowerCase();
+          } else tag += c;
+          break;
+        case 'tag':
+          if (c === '>') { mode = afterTag(tag, closing); if (mode === 'raw') rawTag = tag.toLowerCase(); }
+          else if (c === '"' || c === "'") { mode = 'q'; quote = c; }
+          else if (!/[\s/=]/.test(c)) { mode = 'attr'; name = c; }
+          break;
+        case 'attr':
+          if (/[\s=/>]/.test(c)) {
+            if (name === 'className' || name === 'htmlFor') return { kind: 'attr', name };
+            name = '';
+            if (c === '>') { mode = afterTag(tag, closing); if (mode === 'raw') rawTag = tag.toLowerCase(); }
+            else mode = 'tag';
+          } else name += c;
+          break;
+        case 'q':
+          if (c === quote) mode = 'tag';
+          break;
+        case 'comment':
+          if (str.startsWith('-->', i)) { mode = 'text'; i += 2; }
+          break;
+        case 'raw':
+          if (c === '<' && str.slice(i + 2, i + 2 + rawTag.length).toLowerCase() === rawTag && str[i + 1] === '/') {
+            mode = 'tagname'; closing = true; tag = ''; i += 1;
+          }
+          break;
+        default:
+          break;
+      }
+    }
+  }
+  if (mode === 'attr' && (name === 'className' || name === 'htmlFor')) return { kind: 'attr', name };
+  return null;
+}
+
+/**
+ * @param {string} tag
+ * @param {boolean} closing
+ */
+function afterTag(tag, closing) {
+  return !closing && RAW.has(tag.toLowerCase()) ? 'raw' : 'text';
+}
+
+/**
+ * The error message for a React-ism, naming the WebJs fix.
+ * @param {JsxIsm} ism
+ * @returns {string}
+ */
+export function jsxIsmMessage(ism) {
+  if (ism.kind === 'attr') {
+    const html = ism.name === 'className' ? 'class' : 'for';
+    return `webjs: \`${ism.name}=\` in an html template is JSX, not HTML: the browser reads it as an unknown \`${ism.name.toLowerCase()}\` attribute and it does nothing. Write \`${html}=\` instead (\`${html}=\${...}\` for a dynamic value). See https://webjs.dev/docs/troubleshooting#jsx-in-html-template`;
+  }
+  return `webjs: \`<${ism.name}>\` in an html template is a JSX component, not HTML: the browser lowercases it into an unknown \`<${ism.name.toLowerCase()}>\` element and renders nothing. Use the custom element's tag (\`<my-${ism.name.toLowerCase()}>\`, registered with ${ism.name}.register('my-${ism.name.toLowerCase()}')), or a plain element such as \`<a href>\` for a link. See https://webjs.dev/docs/troubleshooting#jsx-in-html-template`;
+}
+
+/**
+ * Throw when a template carries a React-ism. Called once per template by
+ * each compiler, so the cost is paid at first render only.
+ * @param {readonly string[]} strings
+ */
+export function assertNoJsxIsms(strings) {
+  const ism = findJsxIsm(strings);
+  if (ism) throw new Error(jsxIsmMessage(ism));
+}