@webjsdev/server 0.9.0 → 0.10.0

package/src/jwe.js

@@ -0,0 +1,155 @@
+/**
+ * The session token, encrypted as Auth.js v5 encrypts it (#1686): a compact
+ * JWE with `alg: "dir"` and `enc: "A256CBC-HS512"`, keyed by HKDF-SHA256 over
+ * the secret with the cookie name as salt and
+ * `Auth.js Generated Encryption Key (<salt>)` as info (64 bytes), and a `kid`
+ * that is the key's JWK thumbprint, so several secrets can rotate. Its
+ * contents are unreadable to the browser, where a signed JWT is only base64.
+ *
+ * Built on Web Crypto alone (A256CBC-HS512 is AES-256-CBC plus a truncated
+ * HMAC-SHA-512 over the AAD, IV, ciphertext and AAD length, RFC 7518 5.2), so
+ * it runs the same on Node and Bun with no dependency. Reference:
+ * `packages/core/src/jwt.ts` in the Auth.js repository.
+ */
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+const ALG = 'dir';
+const ENC = 'A256CBC-HS512';
+/** Seconds of clock skew allowed on `exp`, as Auth.js's decode. */
+const CLOCK_TOLERANCE = 15;
+
+/** @param {ArrayBuffer | Uint8Array} buf */
+function b64url(buf) {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  let s = '';
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** @param {string} s */
+function unb64url(s) {
+  const bin = atob(s.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (s.length % 4)) % 4));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/** @param {...Uint8Array} parts */
+function concat(...parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) { out.set(p, o); o += p.length; }
+  return out;
+}
+
+/** Derived keys by secret and salt: the secret and cookie name never change, so HKDF runs once. */
+const derived = new Map();
+
+/** 64 bytes for A256CBC-HS512, as Auth.js derives them (memoized per secret and salt). */
+function deriveKey(secret, salt) {
+  const id = `${salt}\u0000${secret}`;
+  let key = derived.get(id);
+  if (!key) {
+    key = deriveKeyUncached(secret, salt);
+    key.catch(() => derived.delete(id));
+    derived.set(id, key);
+  }
+  return key;
+}
+
+async function deriveKeyUncached(secret, salt) {
+  const base = await crypto.subtle.importKey('raw', enc.encode(secret), 'HKDF', false, ['deriveBits']);
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'HKDF', hash: 'SHA-256', salt: enc.encode(salt), info: enc.encode(`Auth.js Generated Encryption Key (${salt})`) },
+    base,
+    512,
+  );
+  return new Uint8Array(bits);
+}
+
+/** Thumbprints by derived key, so a token's `kid` check costs no hash after the first. */
+const thumbprints = new WeakMap();
+
+/** RFC 7638 thumbprint of the key as an `oct` JWK, SHA-512 as jose picks for a 64-byte key (memoized per key). */
+async function thumbprint(key) {
+  let t = thumbprints.get(key);
+  if (!t) { t = thumbprintUncached(key); thumbprints.set(key, t); }
+  return t;
+}
+
+async function thumbprintUncached(key) {
+  const json = `{"k":"${b64url(key)}","kty":"oct"}`;
+  return b64url(await crypto.subtle.digest('SHA-512', enc.encode(json)));
+}
+
+/** The A256CBC-HS512 authentication tag (RFC 7518 5.2.2.1). */
+async function tagFor(macKey, aad, iv, ct) {
+  const al = new Uint8Array(8);
+  new DataView(al.buffer).setBigUint64(0, BigInt(aad.length * 8));
+  const hk = await crypto.subtle.importKey('raw', macKey, { name: 'HMAC', hash: 'SHA-512' }, false, ['sign']);
+  return new Uint8Array(await crypto.subtle.sign('HMAC', hk, concat(aad, iv, ct, al))).slice(0, 32);
+}
+
+/** @param {Uint8Array} a @param {Uint8Array} b */
+function equalBytes(a, b) {
+  if (a.length !== b.length) return false;
+  let d = 0;
+  for (let i = 0; i < a.length; i++) d |= a[i] ^ b[i];
+  return d === 0;
+}
+
+/**
+ * Encrypt a session payload. `iat` and `jti` are added when absent, as
+ * Auth.js's encode sets them; `exp` is the caller's.
+ * @param {Record<string, unknown>} payload
+ * @param {string | string[]} secret the first is the one that encrypts
+ * @param {string} salt the session cookie's name
+ * @returns {Promise<string>}
+ */
+export async function encryptSession(payload, secret, salt) {
+  const key = await deriveKey(Array.isArray(secret) ? secret[0] : secret, salt);
+  const kid = await thumbprint(key);
+  const header = b64url(enc.encode(JSON.stringify({ alg: ALG, enc: ENC, kid })));
+  const claims = { iat: Math.floor(Date.now() / 1000), jti: crypto.randomUUID(), ...payload };
+  const iv = crypto.getRandomValues(new Uint8Array(16));
+  const aes = await crypto.subtle.importKey('raw', key.slice(32), 'AES-CBC', false, ['encrypt']);
+  const ct = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-CBC', iv }, aes, enc.encode(JSON.stringify(claims))));
+  const tag = await tagFor(key.slice(0, 32), enc.encode(header), iv, ct);
+  return `${header}..${b64url(iv)}.${b64url(ct)}.${b64url(tag)}`;
+}
+
+/**
+ * Decrypt a session token, or null when it is not one this app made, was
+ * tampered with, or has expired. Each secret is tried, the one whose
+ * thumbprint matches the token's `kid` first, as Auth.js's decode does.
+ * @param {string} token
+ * @param {string | string[]} secret
+ * @param {string} salt the session cookie's name
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
+export async function decryptSession(token, secret, salt) {
+  try {
+    const parts = String(token).split('.');
+    if (parts.length !== 5 || parts[1] !== '') return null;
+    const [h, , ivB, ctB, tagB] = parts;
+    const header = JSON.parse(dec.decode(unb64url(h)));
+    if (header.alg !== ALG || header.enc !== ENC) return null;
+    const iv = unb64url(ivB);
+    const ct = unb64url(ctB);
+    const tag = unb64url(tagB);
+    const secrets = Array.isArray(secret) ? secret : [secret];
+    for (const s of secrets) {
+      const key = await deriveKey(s, salt);
+      if (header.kid && header.kid !== (await thumbprint(key))) continue;
+      if (!equalBytes(tag, await tagFor(key.slice(0, 32), enc.encode(h), iv, ct))) continue;
+      const aes = await crypto.subtle.importKey('raw', key.slice(32), 'AES-CBC', false, ['decrypt']);
+      const claims = JSON.parse(dec.decode(await crypto.subtle.decrypt({ name: 'AES-CBC', iv }, aes, ct)));
+      if (typeof claims.exp === 'number' && Date.now() / 1000 > claims.exp + CLOCK_TOLERANCE) return null;
+      return claims;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/lazy-components.js

@@ -0,0 +1,166 @@
+/**
+ * `static lazy = true` components (#1524): a side-effect import of a lazy
+ * component is served as a lazy-loader registration instead of an eager
+ * import, so the browser fetches the module on first sight of its tag.
+ *
+ * @module
+ */
+import { redactStringsAndTemplates, maskComments } from './js-scan.js';
+
+/** A `.server.{js,ts,mjs,mts}` file: a stub on the client, inert there. */
+const SERVER_FILE_RE = /\.server\.m?[jt]s$/;
+
+/** Match a whole-line side-effect import: `import './x.js';` (no bindings). */
+const SIDE_EFFECT_IMPORT_RE = /^([ \t]*)import\s+(['"])([^'"]+)\2\s*;?[ \t]*$/gm;
+
+/**
+ * Defer side-effect imports of `static lazy` components (#1524). A lazy
+ * component that a shipping module imports for registration used to load
+ * eagerly as part of that module's static graph, which defeated `static lazy`
+ * whenever the class had to be imported at all (and SSR needs the import: the
+ * server only knows the tag is lazy once the class registered). The SERVER
+ * keeps the real import; this rewrites only the BROWSER copy, replacing the
+ * import line in place (same line, so positions stay stable) with a
+ * registration on the lazy loader:
+ *
+ *     import('@webjsdev/core/lazy-loader').then((m) => m.observeLazy({"x-tag":"/url"}));
+ *
+ * The loader then imports the module the first time an element with one of
+ * its tags is in (or near) the viewport: a hidden tab panel when it first
+ * shows, a closed dialog's content when it opens, a below-the-fold element
+ * when it scrolls near. Its MutationObserver also catches a tag rendered
+ * later on the client, so an imported-but-not-yet-rendered component still
+ * registers when it appears.
+ *
+ * Only a side-effect import is rewritten (a binding import needs its value
+ * now, so it stays eager), the match runs over a redacted copy so an
+ * import-looking line inside a string, template, or comment is never touched,
+ * and an importer with no lazy dependency in the graph returns untouched with
+ * no regex work.
+ *
+ * @param {string} source             module source (already type-stripped if TS)
+ * @param {string} importerAbs        absolute path of the importing module
+ * @param {import('./module-graph.js').ModuleGraph | undefined} moduleGraph
+ * @param {Map<string, string[]> | undefined} lazyFiles  lazy component file -> the tags it registers
+ * @param {(spec: string, fromFile: string, appDir: string) => (string|null)} resolveImport
+ * @param {string} appDir
+ * @param {(abs: string) => string} urlFor  the browser URL the loader imports (base path + content hash applied)
+ * @returns {string}
+ */
+export function deferLazyImportsFromSource(source, importerAbs, moduleGraph, lazyFiles, resolveImport, appDir, urlFor) {
+  if (!lazyFiles || lazyFiles.size === 0) return source;
+  const deps = moduleGraph && moduleGraph.get(importerAbs);
+  if (!deps) return source;
+  let hasLazyDep = false;
+  for (const d of deps) {
+    if (lazyFiles.has(d)) { hasLazyDep = true; break; }
+  }
+  if (!hasLazyDep) return source;
+
+  const redacted = redactStringsAndTemplates(source);
+  let out = '';
+  let last = 0;
+  for (const m of redacted.matchAll(SIDE_EFFECT_IMPORT_RE)) {
+    const start = /** @type {number} */ (m.index);
+    const end = start + m[0].length;
+    const resolved = resolveImport(m[3], importerAbs, appDir);
+    const tags = resolved ? lazyFiles.get(resolved) : undefined;
+    out += source.slice(last, start);
+    if (tags && tags.length) {
+      const url = urlFor(/** @type {string} */ (resolved));
+      const entries = Object.fromEntries(tags.map((t) => [t, url]));
+      out += `${m[1]}import('@webjsdev/core/lazy-loader').then((m) => m.observeLazy(${JSON.stringify(entries)}));`;
+    } else {
+      out += source.slice(start, end);
+    }
+    last = end;
+  }
+  out += source.slice(last);
+  return out;
+}
+
+/**
+ * The lazy component files of an app (#1524): every scanned component file
+ * that declares `static lazy = true`, mapped to the tags it registers.
+ *
+ * @param {Array<{ tag: string, file: string, lazy?: boolean }>} components
+ * @returns {Map<string, string[]>}
+ */
+export function lazyComponentFiles(components) {
+  /** @type {Map<string, string[]>} */
+  const out = new Map();
+  for (const c of components) {
+    if (!c.lazy) continue;
+    const tags = out.get(c.file);
+    if (tags) { if (!tags.includes(c.tag)) tags.push(c.tag); } else out.set(c.file, [c.tag]);
+  }
+  return out;
+}
+
+/** A test module (the same rule the component scanner skips). */
+const TEST_FILE_RE = /\.(test|spec)\.m?[jt]sx?$/;
+
+/** `import <bindings> from 'x'` (the bindings part is captured). */
+const BINDING_IMPORT_RE = /\bimport\s+(type\s+)?([\w$*{}\s,]+?)\s+from\s+(['"])([^'"]+)\3/g;
+/** `export { a } from 'x'` / `export * from 'x'` (a re-export needs the module too). */
+const REEXPORT_RE = /\bexport\s+(type\s+)?(?:\*|\{[^}]*\}|\*\s+as\s+[\w$]+)\s+from\s+(['"])([^'"]+)\2/g;
+
+/**
+ * Is this import clause types only (`import type { A }`, or every named
+ * specifier marked `type`)? Those are erased before the browser sees them.
+ *
+ * @param {string | undefined} typeKw
+ * @param {string} clause
+ */
+function typeOnlyClause(typeKw, clause) {
+  if (typeKw) return true;
+  const m = clause.trim().match(/^\{([\s\S]*)\}$/);
+  if (!m) return false;
+  const names = m[1].split(',').map((s) => s.trim()).filter(Boolean);
+  return names.length > 0 && names.every((n) => /^type\s/.test(n));
+}
+
+/**
+ * The lazy component files some module imports WITH bindings (#1524). A
+ * binding import loads the module eagerly whatever the class says, because the
+ * importer needs the value when it runs. Such a file is not lazy in practice,
+ * so the caller drops it from the lazy set: otherwise the preload walks would
+ * skip a module the browser still fetches up front, which only makes it slower.
+ *
+ * Only importers whose graph edges reach a lazy file are read. A server file is
+ * never served, and a test file (`*.test.*` / `*.spec.*`) never ships to a
+ * page, so their imports do not count: a component's own browser test imports
+ * it with bindings, and that must not make it eager in the app.
+ *
+ * @param {Map<string, string[]>} lazyFiles
+ * @param {import('./module-graph.js').ModuleGraph | undefined} moduleGraph
+ * @param {(file: string) => Promise<string>} readFileFn
+ * @param {(spec: string, fromFile: string, appDir: string) => (string|null)} resolveImport
+ * @param {string} appDir
+ * @returns {Promise<Set<string>>}
+ */
+export async function bindingImportedLazyFiles(lazyFiles, moduleGraph, readFileFn, resolveImport, appDir) {
+  /** @type {Set<string>} */
+  const out = new Set();
+  if (!lazyFiles.size || !moduleGraph) return out;
+  for (const [importer, deps] of moduleGraph) {
+    if (SERVER_FILE_RE.test(importer) || TEST_FILE_RE.test(importer)) continue;
+    let reaches = false;
+    for (const d of deps) if (lazyFiles.has(d) && !out.has(d)) { reaches = true; break; }
+    if (!reaches) continue;
+    let src;
+    try { src = await readFileFn(importer); } catch { continue; }
+    const code = redactStringsAndTemplates(maskComments(src));
+    for (const m of code.matchAll(BINDING_IMPORT_RE)) {
+      if (typeOnlyClause(m[1], m[2])) continue;
+      const abs = resolveImport(m[4], importer, appDir);
+      if (abs && lazyFiles.has(abs)) out.add(abs);
+    }
+    for (const m of code.matchAll(REEXPORT_RE)) {
+      if (m[1]) continue;
+      const abs = resolveImport(m[3], importer, appDir);
+      if (abs && lazyFiles.has(abs)) out.add(abs);
+    }
+  }
+  return out;
+}

package/src/listener-core.js

@@ -445,9 +445,11 @@ export class SseHub {
    * and an absent or malformed verdict is emitted as `reload` here too, so the
    * fail-safe holds on both ends of the wire and a tab running against a
    * restarted server can never be skewed into a lighter response than the
-   * change deserves.
+   * change deserves. A verdict's `modules` and `css` (#1689) ride the same
+   * payload, and `inPlace` is read here at send time, so a handler that only
+   * learns after construction that it reloads in place still says so.
    *
-   * @param {{ v?: string, by?: string, why?: string } | null} [verdict]
+   * @param {{ v?: string, by?: string, why?: string, modules?: string[], css?: true } | null} [verdict]
    */
   reload(verdict) {
     const v = verdict && typeof verdict.v === 'string' ? verdict : { v: 'reload' };

package/src/lit-hints.js

@@ -0,0 +1,172 @@
+/**
+ * The Lit-habit hint table: what to write in WebJs when Lit muscle memory
+ * reaches for something WebJs cannot have.
+ *
+ * WebJs matches Lit's component API wherever it can with no build step. Two
+ * kinds of Lit code still cannot work, and both fail far from the line that
+ * caused them unless something names the fix:
+ *
+ *  - DECORATORS (`@customElement`, `@property`, `@state`, `@query`, ...).
+ *    Node's type stripper passes them through untouched, so the module then
+ *    dies with a bare `SyntaxError: Invalid or unexpected token` on Node and
+ *    in the browser (Bun runs legacy decorators and throws a
+ *    `ReferenceError` for the undefined decorator instead).
+ *  - NAMES that do not exist in `@webjsdev/core` (`LitElement`, a decorator
+ *    function, a type imported as a value). ESM reports them as
+ *    `does not provide an export named X`, which says nothing about the fix.
+ *
+ * One table feeds every surface that reports these, so the fix text cannot
+ * drift: the `no-non-erasable-typescript` and `core-imports-exist` check
+ * rules, the dev server's post-strip scan, and the dev error overlay.
+ */
+import { redactStringsAndTemplates } from './js-scan.js';
+
+/**
+ * Lit decorator name to the WebJs spelling of the same thing.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const DECORATOR_FIXES = Object.freeze({
+  customElement:
+    "Drop `@customElement('my-el')` and register after the class: `MyEl.register('my-el')` (or `customElements.define('my-el', MyEl)`).",
+  property:
+    "Declare the property in Lit's `static properties = { count: { type: Number } }` plus a `declare count: number;` line (or pass the shape to the factory: `class X extends WebComponent({ count: Number })`), and set its default in the constructor after `super()`.",
+  state:
+    'Declare it as internal state with `static properties = { open: { state: true } }` plus `declare open: boolean;` (or hold it in a signal), and set its default in the constructor.',
+  query:
+    "Replace `@query('#x') el` with a getter: `get el() { return this.renderRoot.querySelector('#x'); }`.",
+  queryAll:
+    "Replace `@queryAll('.x') els` with a getter: `get els() { return this.renderRoot.querySelectorAll('.x'); }`.",
+  queryAsync:
+    "Replace `@queryAsync('#x') el` with an async method: `async el() { await this.updateComplete; return this.renderRoot.querySelector('#x'); }`.",
+  queryAssignedElements:
+    "Replace it with a getter over the slot: `get items() { return this.renderRoot.querySelector('slot')?.assignedElements({ flatten: true }) ?? []; }`.",
+  queryAssignedNodes:
+    "Replace it with a getter over the slot: `get nodes() { return this.renderRoot.querySelector('slot')?.assignedNodes({ flatten: true }) ?? []; }`.",
+  eventOptions:
+    'Pass listener options with a listener object in the binding: `@scroll=${{ handleEvent: (e) => this.onScroll(e), passive: true }}`.',
+  provide:
+    'Create the provider in the constructor: `new ContextProvider(this, { context: myContext, initialValue })` from `@webjsdev/core/context`.',
+  consume:
+    'Create the consumer in the constructor: `new ContextConsumer(this, { context: myContext, subscribe: true })` from `@webjsdev/core/context`.',
+});
+
+/** The fix line shared by every decorator not in the table. */
+export const GENERIC_DECORATOR_FIX =
+  'WebJs has no build step, so decorators cannot run. Declare reactive properties with `static properties` (or the `WebComponent({ ... })` factory), register with `MyEl.register(tag)`, and write `@query`-style lookups as getters over `this.renderRoot`.';
+
+/**
+ * The fix for one decorator name.
+ * @param {string} name  the decorator identifier without the `@`
+ * @returns {string}
+ */
+export function decoratorFix(name) {
+  return Object.hasOwn(DECORATOR_FIXES, name) ? DECORATOR_FIXES[name] : GENERIC_DECORATOR_FIX;
+}
+
+/**
+ * A decorator in CODE position: at the start of a line or right after a
+ * `{`, `;` or `}`, an `@` followed by an identifier (optionally dotted), with
+ * whatever follows being another decorator, a call, or a class member / class
+ * declaration. Run over a mask in which every comment, string and template
+ * body is blanked, so `@click=${...}` in an `html` template, `@media` in a
+ * `css` template, and `@param` in a JSDoc block are never seen.
+ */
+const DECORATOR_RE = /(^|[{;}])([ \t]*)@([A-Za-z_$][\w$]*)(?:\.[A-Za-z_$][\w$]*)*(?=[ \t]*(?:\(|\r?\n|[A-Za-z_$#@*[]))/gm;
+
+/**
+ * Find the first decorator in `src`, or null.
+ * @param {string} src  raw JS / TS source
+ * @param {string} [scan]  an already-built `redactStringsAndTemplates(src, true)` mask
+ * @returns {{ name: string, index: number, line: number, column: number } | null}
+ */
+export function findDecorator(src, scan) {
+  if (typeof src !== 'string' || !src.includes('@')) return null;
+  const mask = scan ?? redactStringsAndTemplates(src, true);
+  DECORATOR_RE.lastIndex = 0;
+  const m = DECORATOR_RE.exec(mask);
+  if (!m) return null;
+  const index = m.index + m[1].length + m[2].length;
+  const before = src.slice(0, index);
+  const line = before.split('\n').length;
+  const column = index - before.lastIndexOf('\n');
+  return { name: m[3], index, line, column };
+}
+
+/**
+ * One message for a found decorator, shared by `webjs check` and dev.
+ * @param {{ name: string, line: number }} hit
+ * @returns {{ message: string, fix: string }}
+ */
+export function decoratorReport(hit) {
+  return {
+    message:
+      `Decorator \`@${hit.name}\` at line ${hit.line}. WebJs serves source with no build step and decorators are not erasable TypeScript: ` +
+      'Node and the browser reject the module with a bare `SyntaxError: Invalid or unexpected token`, so the component never loads.',
+    fix: decoratorFix(hit.name),
+  };
+}
+
+/**
+ * Names Lit code imports that `@webjsdev/core` will never export, mapped to the
+ * WebJs replacement. A name NOT here that is still missing from core gets the
+ * generic "not exported" message with the list of near names; a name that core
+ * exports only as a TYPE gets the `import type` fix instead.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const MISSING_NAME_FIXES = Object.freeze({
+  LitElement: "Extend `WebComponent` from '@webjsdev/core': `class MyEl extends WebComponent { ... }`.",
+  ReactiveElement: "Extend `WebComponent` from '@webjsdev/core'. It is the reactive element and the template renderer in one class.",
+  customElement: DECORATOR_FIXES.customElement,
+  property: DECORATOR_FIXES.property,
+  state: DECORATOR_FIXES.state,
+  query: DECORATOR_FIXES.query,
+  queryAll: DECORATOR_FIXES.queryAll,
+  queryAsync: DECORATOR_FIXES.queryAsync,
+  queryAssignedElements: DECORATOR_FIXES.queryAssignedElements,
+  queryAssignedNodes: DECORATOR_FIXES.queryAssignedNodes,
+  eventOptions: DECORATOR_FIXES.eventOptions,
+  provide: DECORATOR_FIXES.provide,
+  consume: DECORATOR_FIXES.consume,
+  supportsAdoptingStyleSheets: 'Drop it. WebJs adopts `static styles` into a shadow root itself and falls back to a `<style>` element when constructable stylesheets are missing.',
+  defaultConverter: 'Drop the import. The built-in attribute conversion for `String` / `Number` / `Boolean` / `Object` / `Array` applies whenever a property declares no `converter`.',
+  notEqual: 'Drop the import. A property with no `hasChanged` already uses `!Object.is(value, oldValue)`.',
+});
+
+/**
+ * The fix for a name that `@webjsdev/core` does not export as a value.
+ * @param {string} name
+ * @param {{ typeOnly?: boolean, specifier?: string }} [info]
+ * @returns {string}
+ */
+export function missingCoreNameFix(name, info = {}) {
+  const spec = info.specifier || '@webjsdev/core';
+  if (info.typeOnly) {
+    return `\`${name}\` is a TYPE in ${spec}, with no runtime value. Import it with \`import type { ${name} } from '${spec}'\` (or \`import { type ${name} }\`), since the type stripper keeps a plain import and the module then fails to load.`;
+  }
+  if (Object.hasOwn(MISSING_NAME_FIXES, name)) return MISSING_NAME_FIXES[name];
+  return `Remove the import of \`${name}\` or import a name ${spec} exports. Its source is readable in node_modules/@webjsdev/core.`;
+}
+
+/**
+ * Parse the missing name and the module out of an ESM link error, on either
+ * runtime: Node's `The requested module 'x' does not provide an export named
+ * 'Y'` and Bun's `Export named 'Y' not found in module 'x'.`
+ * @param {string} message
+ * @returns {{ name: string, module: string } | null}
+ */
+export function parseMissingExport(message) {
+  if (typeof message !== 'string') return null;
+  let m = /requested module '([^']+)' does not provide an export named '([^']+)'/.exec(message);
+  if (m) return { module: m[1], name: m[2] };
+  m = /Export named '([^']+)' not found in module '([^']+)'/.exec(message);
+  if (m) return { module: m[2], name: m[1] };
+  return null;
+}
+
+/**
+ * True when an ESM link error names a WebJs core module.
+ * @param {string} mod
+ */
+export function isCoreModule(mod) {
+  return /@webjsdev\/core|\/packages\/core\/|\/__webjs\/core\//.test(mod);
+}