@webjsdev/server 0.8.67 → 0.8.68

package/src/dev-embed.js

@@ -0,0 +1,129 @@
+/**
+ * The dev embed bridge, SERVER half (#1498).
+ *
+ * `webjs dev` with `WEBJS_EMBED_ORIGINS` set (a comma-separated list of parent
+ * origins, e.g. `https://crisp.app,http://localhost:8080`) makes an app ready
+ * to be previewed inside an iframe on those origins:
+ *
+ *   1. every HTML document gets a small inline script (the browser half,
+ *      `dev-embed-client.js`) that reports page state to the parent and takes
+ *      a few commands from it, carrying the request's CSP nonce like every
+ *      other inline script WebJs emits;
+ *   2. the response stops refusing the frame: `X-Frame-Options` is dropped
+ *      and a CSP `frame-ancestors` directive is widened to the listed origins.
+ *
+ * Unset, both are a no-op and a document is byte-identical to before. Under
+ * `webjs start` (`dev: false`) neither ever happens: the handler records no
+ * origins and `wrapHead` gates on `opts.dev` as well.
+ *
+ * The origins are a module-level switch (mirroring `setClientRouterEnabled`),
+ * set by `createRequestHandler`, so no option has to thread through every
+ * render path that reaches `wrapHead`.
+ */
+import { readFileSync } from 'node:fs';
+import { jsonForScriptTag } from './script-tag-json.js';
+import { escapeAttr } from './ssr/escape.js';
+
+/**
+ * The browser half, read once and inlined: its `export` keyword stripped, and
+ * its comments too, since they are the bulk of the file and every framed page
+ * would carry them. The source has no string or regex containing a comment
+ * opener, which `test/dev/dev-embed.test.js` pins.
+ */
+const CLIENT_SRC = readFileSync(new URL('./dev-embed-client.js', import.meta.url), 'utf8')
+  .replace(/\/\*[\s\S]*?\*\//g, '')
+  .replace(/^\s*\/\/.*$/gm, '')
+  .replace(/^export /gm, '')
+  .replace(/^\s+/gm, '')
+  .trim();
+
+/** @type {string[]} */
+let _origins = [];
+
+/**
+ * Parse `WEBJS_EMBED_ORIGINS`. Each entry must be an http(s) origin; a path or
+ * trailing slash is normalized away (`https://a.dev/` is `https://a.dev`).
+ * Anything else (a bare host, `*`, another scheme) is dropped with a warning,
+ * because a wildcard would hand every page's console and errors to any site
+ * that frames it.
+ *
+ * @param {string | undefined} raw
+ * @param {{ warn?: (msg: string) => void }} [opts]
+ * @returns {string[]} unique normalized origins, in input order
+ */
+export function parseEmbedOrigins(raw, opts) {
+  if (typeof raw !== 'string' || !raw.trim()) return [];
+  const warn = (opts && opts.warn) || ((m) => console.warn(m));
+  /** @type {string[]} */
+  const out = [];
+  for (const part of raw.split(',')) {
+    const v = part.trim();
+    if (!v) continue;
+    let origin = '';
+    try {
+      const u = new URL(v);
+      if (u.protocol === 'http:' || u.protocol === 'https:') origin = u.origin;
+    } catch { /* not a URL */ }
+    if (!origin) {
+      warn(`[webjs] WEBJS_EMBED_ORIGINS: ignoring "${v}", expected an origin like https://example.com`);
+      continue;
+    }
+    if (!out.includes(origin)) out.push(origin);
+  }
+  return out;
+}
+
+/**
+ * Record the allowed embed origins for this process. `createRequestHandler`
+ * calls it at construction: the parsed env value in dev, `[]` otherwise.
+ *
+ * @param {string[]} origins
+ */
+export function setEmbedOrigins(origins) {
+  _origins = Array.isArray(origins) ? origins.slice() : [];
+}
+
+/** @returns {string[]} the allowed embed origins (empty = bridge off) */
+export function embedOrigins() {
+  return _origins;
+}
+
+/**
+ * The inline bridge `<script>` for a document, or `''` when the bridge is off.
+ * Includes its own leading newline so the off case adds zero bytes to the
+ * head (the same shape as the client-router opt-out flag beside it).
+ *
+ * @param {{ dev: boolean, nonce?: string }} opts
+ * @returns {string}
+ */
+export function embedScriptTag(opts) {
+  if (!opts.dev || !_origins.length) return '';
+  const n = opts.nonce ? ` nonce="${escapeAttr(opts.nonce)}"` : '';
+  return `\n<script${n} data-webjs-embed>(function(){${CLIENT_SRC}\ninstallEmbedBridge(${jsonForScriptTag(_origins)});})();</script>`;
+}
+
+/**
+ * Let the listed origins frame a dev response: drop `X-Frame-Options` (it has
+ * no way to name another origin) and add the origins to a `frame-ancestors`
+ * directive in either CSP header. A policy without `frame-ancestors` already
+ * allows any parent, so it is left alone. Mutates `headers` in place.
+ *
+ * @param {Headers} headers
+ * @param {string[]} origins
+ */
+export function allowEmbedFraming(headers, origins) {
+  if (!origins.length) return;
+  headers.delete('x-frame-options');
+  for (const name of ['content-security-policy', 'content-security-policy-report-only']) {
+    const value = headers.get(name);
+    if (!value) continue;
+    const next = value.split(';').map((d) => {
+      const t = d.trim();
+      if (!/^frame-ancestors(\s|$)/i.test(t)) return d;
+      const sources = t.split(/\s+/).slice(1).filter((s) => s !== "'none'");
+      for (const o of origins) if (!sources.includes(o)) sources.push(o);
+      return ` frame-ancestors ${sources.join(' ')}`;
+    }).join(';').trim();
+    try { headers.set(name, next); } catch { /* keep the original policy */ }
+  }
+}

package/src/dev-overlay.js

@@ -158,6 +158,14 @@ export function renderDevOverlay(f, currentPath) {
   (document.body || document.documentElement).appendChild(o);
   __wjOverlay = o;
   __wjFrame = f;
+  // Announce that an overlay is now on screen, for the dev embed bridge
+  // (#1498), which relays it to a host framing this page. Dispatched here,
+  // after the scope gate above, so a frame held for another url never counts.
+  try {
+    document.dispatchEvent(new CustomEvent('webjs:dev-overlay', {
+      detail: { kind: f.kind || 'render', message: f.message || '', file: f.file || null, line: f.line || null },
+    }));
+  } catch (_) { /* a listener throwing must not break the overlay */ }
 }
 
 /**

package/src/dev-source-locations-hook.js

@@ -0,0 +1,139 @@
+/**
+ * The SSR half of dev source locations (#1499): a module load hook that runs
+ * `annotateSourceLocations` over every app module the SERVER imports, so SSR
+ * output carries the same `data-webjs-src` attributes the browser-served copy
+ * of the module renders (the browser half is in `dev/serve.js`).
+ *
+ * Installed only by the dev handler, only when `WEBJS_SOURCE_LOCATIONS=1`, and
+ * before any app module is imported (ESM caches by URL, so a module loaded
+ * first would stay unannotated until its next dev cache-bust re-import). The
+ * hook is process-global and cannot be uninstalled, so it is scoped to the app
+ * roots registered with it: a module outside every registered root is never
+ * touched.
+ *
+ * Node: `module.registerHooks` with a `load` hook that calls `nextLoad` FIRST
+ * and transforms its result. That keeps it chained with the `'use server'`
+ * seed hook (which it never sees anyway: `*.server.*` modules are excluded) and
+ * keeps Node's own TypeScript stripping, since a `.ts` result keeps its
+ * `module-typescript` format and Node strips it after the hook.
+ *
+ * Bun: `Bun.plugin` `onLoad`. A Bun `onLoad` must return contents for every
+ * path its filter matches, and when two plugins match the same path the first
+ * registered wins, so the filter itself excludes `node_modules` and `*.server.*`
+ * (a lookahead, which Bun's filter honours). The seed plugin therefore keeps
+ * every server module whatever the registration order.
+ */
+import * as nodeModule from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { relative, isAbsolute } from 'node:path';
+import { serverRuntime } from './listener-core.js';
+import {
+  annotateSourceLocations,
+  isSourceLocationCandidate,
+  sourceLocationFile,
+} from './dev-source-locations.js';
+
+/** App roots the hook annotates. */
+const _roots = new Set();
+let _installed = false;
+
+/**
+ * The registered app root containing `abs`, or null.
+ * @param {string} abs
+ * @returns {string | null}
+ */
+function rootFor(abs) {
+  for (const root of _roots) {
+    const rel = relative(root, abs);
+    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return root;
+  }
+  return null;
+}
+
+/**
+ * Annotate one module's source, or return null when it is not a candidate.
+ * @param {string} abs absolute path, no query
+ * @param {string} src
+ * @returns {string | null}
+ */
+export function transformForSsr(abs, src) {
+  const root = rootFor(abs);
+  if (!root || !isSourceLocationCandidate(abs, root)) return null;
+  return annotateSourceLocations(src, sourceLocationFile(abs, root));
+}
+
+/**
+ * Node `load` hook. Fail-open: any surprise returns `nextLoad`'s result as is.
+ * @param {string} url
+ * @param {object} context
+ * @param {(u: string, c: object) => any} nextLoad
+ */
+function sourceLocationLoadHook(url, context, nextLoad) {
+  const result = nextLoad(url, context);
+  try {
+    if (!url.startsWith('file:') || !result || result.source == null) return result;
+    if (result.format !== 'module' && result.format !== 'module-typescript') return result;
+    const abs = fileURLToPath(url.split('?')[0]);
+    const src = typeof result.source === 'string'
+      ? result.source
+      : Buffer.from(result.source).toString('utf8');
+    const out = transformForSsr(abs, src);
+    if (out == null || out === src) return result;
+    return { ...result, source: out };
+  } catch {
+    return result;
+  }
+}
+
+/**
+ * Escape a string for use inside a RegExp.
+ * @param {string} s
+ */
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+}
+
+/**
+ * Register `appDir` with the SSR source-location hook, installing the hook on
+ * the first call. Idempotent per root.
+ *
+ * @param {string} appDir absolute app root
+ * @returns {boolean} whether the hook is (now) installed
+ */
+export function registerSourceLocationHook(appDir) {
+  if (_roots.has(appDir)) return _installed;
+  _roots.add(appDir);
+  if (serverRuntime() === 'bun') {
+    // One plugin per root, each with a filter that can never match a
+    // `node_modules` or `*.server.*` path (see the module comment).
+    const filter = new RegExp(
+      '^' + escapeRe(appDir) + '/(?:(?!node_modules/)(?!.*\\.server\\.).)*\\.m?[jt]s(\\?.*)?$',
+    );
+    /** @type {any} */ (globalThis).Bun.plugin({
+      name: 'webjs-source-locations',
+      setup(build) {
+        build.onLoad({ filter }, async (args) => {
+          const abs = args.path.split('?')[0];
+          const loader = /\.m?ts$/.test(abs) ? 'ts' : 'js';
+          const src = readFileSync(abs, 'utf8');
+          let contents = src;
+          try {
+            contents = transformForSsr(abs, src) ?? src;
+          } catch { /* fail open: the raw module */ }
+          return { contents, loader };
+        });
+      },
+    });
+    _installed = true;
+    return true;
+  }
+  if (_installed) return true;
+  if (typeof nodeModule.registerHooks !== 'function') {
+    console.warn('[webjs] WEBJS_SOURCE_LOCATIONS: this runtime has no module.registerHooks, so SSR output carries no data-webjs-src (client renders still do).');
+    return false;
+  }
+  nodeModule.registerHooks({ load: sourceLocationLoadHook });
+  _installed = true;
+  return true;
+}