@tinvar/renderer 0.0.0-stage → 0.4.1

package/src/workbench.js

@@ -0,0 +1,754 @@
+// The workbench and the playground: an app's pages and components rendered
+// in isolation, from props an app writes or a developer gives, in dev and
+// in dev alone (ADR 0089).
+//
+// A Vite plugin, as the email preview is (ADR 0086): its pages are served by
+// the dev server `tinvar serve --dev` starts, behind PHP's server under
+// /_vite/, and by nothing else. It has no part in a build (`apply: 'serve'`),
+// and the module it reads samples from is imported by no entry, so no build
+// contains either.
+//
+//   /_vite/__workbench                 each page and its samples
+//   /_vite/__workbench/<page>          one page: a sample, its props to edit, and the page drawn
+//   /_vite/__playground                each component and its samples
+//   /_vite/__playground/<component>    the same, for one component
+//
+// What renders is the app's own code in the dev server's rsc and ssr
+// environments -- the process that renders every page in dev, which holds no
+// secret -- and nothing else: no PHP, no database, no session. A query a
+// server component calls is answered from the sample's `queries`, and one
+// the sample does not answer fails; a <Deferred> boundary is given a token
+// nothing will take. The page drawn runs no script: what is shown is the
+// HTML, under a policy of its own, in a sandboxed frame. Where the app gives
+// a client module, it may be drawn with its client script instead (ADR
+// 0132): hydrated in a frame sandboxed to an origin of its own -- an opaque
+// one, which holds no cookie and no storage and reaches no page of the
+// app's -- under a policy that connects nowhere and posts no form.
+//
+// Where it refuses:
+//   - anywhere that says production, loudly, as the dev server does;
+//   - and it is not mounted -- with a line saying why -- unless TINVAR_ENV
+//     says local, development or testing, or under a server profile other
+//     than test (production, staging);
+//   - a request not from this machine, naming this machine, is answered as a
+//     path the dev server has nothing at: DNS rebinding points a name of a
+//     page's own at 127.0.0.1, and cannot change the Host its requests name;
+//   - props are given by a POST from the workbench's own page alone (its
+//     Origin), JSON, and at most 64 KiB.
+
+import { randomBytes } from 'node:crypto';
+import { PRODUCTION_MARKERS } from './dev-guard.js';
+
+/** The TINVAR_ENV values that say this is not production; nothing else does. Mirrors Tinvar\Support\BuildProfile. */
+export const NON_PRODUCTION = ['local', 'development', 'testing'];
+
+/** Hosts a request may name: this machine's, by address, `localhost` or a name under it. */
+const LOOPBACK_HOST =
+  /^(?:localhost|(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+localhost|127(?:\.\d{1,3}){3}|\[::1\])(?::[1-9]\d{0,4})?$/i;
+
+/** Addresses a loopback peer connects from. */
+const LOOPBACK_PEER = /^(?:127(?:\.\d{1,3}){3}|::1|::ffff:127(?:\.\d{1,3}){3})$/i;
+
+/** A page's, a component's or a sample's name. */
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_.\-]{0,63}$/;
+
+/** The most a POST of props may be. */
+export const MAX_PROPS_BYTES = 64 * 1024;
+
+/** The most of a render's HTML that is read. */
+const MAX_HTML_BYTES = 8 * 1024 * 1024;
+
+/** And of its RSC payload, kept for a frame that runs the app's client script. */
+const MAX_PAYLOAD_BYTES = 8 * 1024 * 1024;
+
+/** The id of the data block a scripted frame's payload is in, which the app's client module reads. */
+export const PAYLOAD_ID = 'tinvar-workbench-payload';
+
+export class WorkbenchRefused extends Error {}
+
+/**
+ * Whether the workbench may be mounted here: throws where anything says
+ * production, and answers why not where nothing says this is a developer's
+ * machine.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {string | null} why it is not mounted, or null when it is
+ */
+export function workbenchRefusal(env = process.env) {
+  for (const name of PRODUCTION_MARKERS) {
+    if (
+      String(env[name] ?? '')
+        .trim()
+        .toLowerCase() === 'production'
+    ) {
+      throw new WorkbenchRefused(
+        `The workbench is refused: ${name}=production. It renders the app's pages and components for whoever ` +
+          'asks, so it runs under the dev server alone.',
+      );
+    }
+  }
+  const environment = String(env.TINVAR_ENV ?? '')
+    .trim()
+    .toLowerCase();
+  if (!NON_PRODUCTION.includes(environment)) {
+    return 'nothing says this is not production: set TINVAR_ENV=local (or development, or testing)';
+  }
+  const profile = String(env.TINVAR_PROFILE ?? '')
+    .trim()
+    .toLowerCase();
+  if (profile !== '' && profile !== 'test') {
+    return `TINVAR_PROFILE=${profile}: only the test profile, and dev, carry the development tools`;
+  }
+
+  return null;
+}
+
+/**
+ * Whether a request is from this machine, naming this machine: its peer, the
+ * Host it names, and -- behind PHP's server, which proxies the dev server --
+ * every address and host the proxy says it forwarded for.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ */
+export function fromThisMachine(req) {
+  const host = req.headers.host ?? '';
+  const peer = req.socket?.remoteAddress ?? '';
+  if (!LOOPBACK_HOST.test(host) || !LOOPBACK_PEER.test(peer)) return false;
+
+  const forwardedFor = req.headers['x-forwarded-for'];
+  if (forwardedFor !== undefined) {
+    const addresses = String(forwardedFor)
+      .split(',')
+      .map((a) => a.trim());
+    if (!addresses.every((a) => LOOPBACK_PEER.test(a))) return false;
+  }
+  const forwardedHost = req.headers['x-forwarded-host'];
+  if (forwardedHost !== undefined && !LOOPBACK_HOST.test(String(forwardedHost))) return false;
+  // A header no proxy of ours adds, which says someone else's did.
+  if (req.headers.forwarded !== undefined || req.headers['x-real-ip'] !== undefined) return false;
+
+  return true;
+}
+
+/**
+ * Whether a request is a module, style or font that a scripted frame of the
+ * workbench asked for -- which it may read, and nothing else may.
+ *
+ * Such a frame is sandboxed to an opaque origin, so what it loads it asks
+ * for with `Origin: null`, and its loads are cross-origin: the dev server
+ * must allow `null` for them, or no module runs. But `null` is every
+ * sandboxed frame's origin, a page on any site included, and the dev
+ * server's modules are the app's source. So `null` is allowed only where
+ * the request also says it came from this dev server: a Referer of this
+ * origin, under the dev server's base -- the frame's own document, or a
+ * module it loaded. A page elsewhere cannot send this origin as its
+ * Referer (it can send none, which is refused). And only for a GET or HEAD
+ * from this machine, naming this machine, of something under the base that
+ * is not one of the dev tools' own pages (`__workbench`, `__mail`, ...).
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {string} base the dev server's base, `/_vite/`
+ */
+export function forScriptedFrame(req, base) {
+  if (req.headers.origin !== 'null' || (req.method !== 'GET' && req.method !== 'HEAD')) return false;
+  if (!fromThisMachine(req)) return false;
+  const path = new URL(req.url ?? '/', 'http://workbench.invalid').pathname;
+  if (!path.startsWith(base) || path.startsWith(`${base}__`)) return false;
+  let referer;
+  try {
+    referer = new URL(String(req.headers.referer ?? ''));
+  } catch {
+    return false;
+  }
+  return referer.origin === `http://${req.headers.host}` && referer.pathname.startsWith(base);
+}
+
+/**
+ * The HTML of a frame that runs the app's client script: the render with
+ * its own scripts taken out, as forTheFrame() has it, then the payload in a
+ * data block, never run, and one module script under the frame's nonce. That
+ * script installs React Refresh's preamble where the dev server has it --
+ * the app's components, transformed for Fast Refresh, refuse to load
+ * without it -- keeps a link from taking the frame anywhere, and imports
+ * the app's client module, which reads the payload and hydrates.
+ *
+ * @param {string} html
+ * @param {string} css
+ * @param {unknown[]} rows the payload, as the rows a page's own inline scripts push
+ * @param {string} nonce
+ * @param {string} client the client module's URL
+ * @param {string | null} refresh React Refresh's runtime's URL, where the dev server has it
+ */
+export function scriptedFrame(html, css, rows, nonce, client, refresh) {
+  const json = (value) => JSON.stringify(value).replace(/</g, '\\u003c');
+  const boot =
+    (refresh === null
+      ? ''
+      : `import RefreshRuntime from ${json(refresh)};RefreshRuntime.injectIntoGlobalHook(window);` +
+        'window.$RefreshReg$=()=>{};window.$RefreshSig$=()=>(type)=>type;' +
+        'window.__vite_plugin_react_preamble_installed__=true;') +
+    // A link would load the app's own page into the frame: it stays put.
+    "document.addEventListener('click',(e)=>{if(e.target instanceof Element&&e.target.closest('a[href]'))e.preventDefault()},true);" +
+    `await import(${json(client)});`;
+  const tail =
+    `<script type="application/json" id="${PAYLOAD_ID}">${json(rows)}</script>` +
+    `<script type="module" nonce="${escapeHtml(nonce)}">${boot}</script>`;
+  // A stylesheet asked for with CORS from an opaque origin carries no
+  // Referer in Chromium, so forScriptedFrame() could not tell it from a
+  // page elsewhere asking: it is asked for without, as a stylesheet may be,
+  // and the frame's policy holds it to the dev server.
+  const out = forTheFrame(html, css).replace(/<link\b[^>]*>/gi, (tag) =>
+    /\brel=["']?stylesheet\b/i.test(tag)
+      ? tag.replace(/\s+crossorigin(?:=(?:"[^"]*"|'[^']*'|[^\s>]+))?/gi, '')
+      : tag,
+  );
+  return /<\/body>/i.test(out)
+    ? out.replace(/<\/body>(?![\s\S]*<\/body>)/i, () => `${tail}</body>`)
+    : out + tail;
+}
+
+/**
+ * A render's RSC payload as the rows a page's inline scripts push: text
+ * where it is UTF-8, and a `{"$b64": ...}` row where it is not, as the
+ * renderer writes them and `inlinePayloadStream()` reads them.
+ *
+ * @param {Uint8Array} bytes
+ * @returns {unknown[]}
+ */
+export function payloadRows(bytes) {
+  if (bytes.length === 0) return [];
+  try {
+    return [new TextDecoder('utf-8', { fatal: true }).decode(bytes)];
+  } catch {
+    return [{ $b64: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64') }];
+  }
+}
+
+/** @param {string} value */
+function escapeHtml(value) {
+  return String(value).replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#x27;' })[c],
+  );
+}
+
+/** @param {unknown} value */
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * A query client that answers from `answers` alone: a value, or a function
+ * of the call's arguments. A call it has no answer for fails, naming it.
+ *
+ * @param {Record<string, unknown>} answers
+ */
+export function sampleQueries(answers) {
+  return {
+    async call(name, args) {
+      if (!Object.hasOwn(answers, name)) {
+        throw new Error(
+          `The workbench has no answer for '${name}': give the sample one under queries['${name}'].`,
+        );
+      }
+      const answer = answers[name];
+      return typeof answer === 'function' ? answer(args ?? {}) : structuredClone(answer);
+    },
+  };
+}
+
+/** A mint client whose tokens nothing takes: a <Deferred> boundary draws its fallback. */
+const MINTS = { mint: async () => 'workbench' };
+
+/**
+ * Every byte of a stream, up to MAX_PAYLOAD_BYTES.
+ *
+ * @param {ReadableStream<Uint8Array>} stream
+ */
+async function readBytes(stream) {
+  const reader = stream.getReader();
+  const chunks = [];
+  let bytes = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytes += value.byteLength;
+    if (bytes > MAX_PAYLOAD_BYTES) {
+      await reader.cancel();
+      throw new Error('The render wrote more than 8 MiB of payload.');
+    }
+    chunks.push(value);
+  }
+  return new Uint8Array(Buffer.concat(chunks));
+}
+
+/** @param {ReadableStream<Uint8Array>} stream */
+async function readAll(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let html = '';
+  let bytes = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytes += value.byteLength;
+    if (bytes > MAX_HTML_BYTES) {
+      await reader.cancel();
+      throw new Error('The render wrote more than 8 MiB.');
+    }
+    html += decoder.decode(value, { stream: true });
+  }
+  return html + decoder.decode();
+}
+
+/**
+ * The render made for the frame it is drawn in, which runs no script: its
+ * scripts and module preloads taken out -- none would run, and the payload
+ * they carry is not what is shown -- and `css`, styles the app's tooling
+ * would have injected with a script, put in its head.
+ *
+ * @param {string} html
+ * @param {string} css
+ */
+export function forTheFrame(html, css = '') {
+  let out = html
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, '')
+    .replace(/<link\b[^>]*\brel=["']?modulepreload["']?[^>]*>/gi, '');
+  if (css !== '') {
+    // Inside a <style>, only its own end tag ends it.
+    const style = `<style>${css.replace(/<\/style/gi, '<\\/style')}</style>`;
+    out = /<\/head>/i.test(out) ? out.replace(/<\/head>/i, () => `${style}</head>`) : style + out;
+  }
+  return out;
+}
+
+/**
+ * Reads a POST's body, up to MAX_PROPS_BYTES, as the `props` field of a
+ * form, parsed as JSON.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ */
+async function postedProps(req) {
+  const type = String(req.headers['content-type'] ?? '')
+    .split(';')[0]
+    .trim()
+    .toLowerCase();
+  if (type !== 'application/x-www-form-urlencoded') {
+    throw new WorkbenchRefused('Props are posted from the workbench page, as a form.');
+  }
+  let size = 0;
+  const chunks = [];
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_PROPS_BYTES) throw new WorkbenchRefused('The props are larger than 64 KiB.');
+    chunks.push(chunk);
+  }
+  const form = new URLSearchParams(Buffer.concat(chunks).toString('utf8'));
+  try {
+    return { props: JSON.parse(form.get('props') ?? ''), sample: form.get('sample') ?? '' };
+  } catch {
+    throw new WorkbenchRefused('The props are not JSON.');
+  }
+}
+
+/**
+ * The queries a render is answered from: the entry's, then its sample's,
+ * then any given with the props -- where a function in the sample, shown
+ * as '[function]' to edit, is kept as the function.
+ */
+function answersFor(entry, sample, given) {
+  const own = (value) => (isRecord(value) ? value : {});
+  const edited = Object.fromEntries(
+    Object.entries(own(given?.queries)).filter(([, value]) => value !== FUNCTION_SHOWN),
+  );
+  return { ...own(entry?.queries), ...own(sample?.queries), ...edited };
+}
+
+/** How a function among a sample's props is shown in the editor. */
+const FUNCTION_SHOWN = '[function]';
+
+/**
+ * The plugin. `module` is the app's workbench module, loaded in the rsc
+ * environment, whose default export has its `pages` and `components` with
+ * their samples, `renderPage(frame, client, mints)` and
+ * `renderElement(element, frame, client, mints)` -- each answering an RSC
+ * stream. `ssr` is a module of the app's, loaded in the ssr environment,
+ * whose `prerenderHtml(rscStream)` answers the whole HTML, every Suspense
+ * boundary filled in, since the frame runs no script to fill one in later.
+ * Neither is imported by an entry, so no build has them.
+ *
+ * `css`, when given, answers styles the app's tooling injects with a script
+ * in dev -- StyleX's, say -- for the frame, which runs none.
+ *
+ * @param {{ module: string, ssr: string, environment?: string, ssrEnvironment?: string, workbench?: string, playground?: string, css?: () => string | Promise<string> }} options
+ * @returns {import('vite').Plugin}
+ */
+export function workbench({
+  module,
+  ssr,
+  environment = 'rsc',
+  ssrEnvironment = 'ssr',
+  workbench: workbenchPath = '__workbench',
+  playground: playgroundPath = '__playground',
+  css,
+  client,
+}) {
+  return {
+    name: 'tinvar:workbench',
+    apply: 'serve',
+    configureServer(server) {
+      const refusal = workbenchRefusal();
+      if (refusal !== null) {
+        server.config.logger.info(`[tinvar:workbench] not mounted: ${refusal}.`);
+        return;
+      }
+
+      const base = server.config.base.replace(/\/?$/, '/');
+      const kinds = {
+        [`${base}${workbenchPath}`]: 'pages',
+        [`${base}${playgroundPath}`]: 'components',
+      };
+
+      // A scripted frame's modules, styles and fonts, and nothing else of
+      // the dev server's, may be read from its opaque origin.
+      if (client !== undefined) {
+        server.middlewares.use((req, res, next) => {
+          if (forScriptedFrame(req, base)) {
+            res.setHeader('access-control-allow-origin', 'null');
+            res.setHeader('vary', 'Origin, Referer');
+          }
+          next();
+        });
+      }
+
+      server.middlewares.use(async (req, res, next) => {
+        const url = new URL(req.url ?? '/', 'http://workbench.invalid');
+        const prefix = Object.keys(kinds).find((p) => url.pathname === p || url.pathname.startsWith(`${p}/`));
+        if (prefix === undefined) return next();
+        const kind = kinds[prefix];
+
+        const send = (status, type, body, policy, referrer = 'no-referrer') => {
+          res.statusCode = status;
+          res.setHeader('content-type', `${type}; charset=utf-8`);
+          res.setHeader('cache-control', 'no-store');
+          res.setHeader('x-content-type-options', 'nosniff');
+          res.setHeader('referrer-policy', referrer);
+          res.setHeader('cross-origin-resource-policy', 'same-origin');
+          res.setHeader('content-security-policy', policy);
+          res.end(body);
+        };
+        const plain = (status, text) => send(status, 'text/plain', text, "default-src 'none'");
+
+        // This machine, asked by this machine.
+        if (!fromThisMachine(req)) return plain(404, 'Not found');
+
+        const host = String(req.headers.host);
+        const origin = `http://${host}`;
+        const rest = url.pathname.slice(prefix.length).replace(/^\//, '');
+        const [name, action, extra] = rest === '' ? [] : rest.split('/');
+        if (extra !== undefined || (action !== undefined && action !== 'render')) {
+          return plain(404, 'Not found');
+        }
+
+        // With the app's client script, where the app gives a client module.
+        const scripted = url.searchParams.get('script') === '1';
+        if (scripted && client === undefined) {
+          return plain(404, 'This app gives the workbench no client module to run: workbench({ client }).');
+        }
+
+        const posted = req.method === 'POST';
+        if (!posted && req.method !== 'GET' && req.method !== 'HEAD') {
+          res.setHeader('allow', 'GET, HEAD, POST');
+          return plain(405, 'Method not allowed');
+        }
+        // Given props come from the workbench's own page, and from no other:
+        // a form on any site can post to this machine's address.
+        if (posted) {
+          const site = req.headers['sec-fetch-site'];
+          if (
+            action !== 'render' ||
+            req.headers.origin !== origin ||
+            (site !== undefined && site !== 'same-origin')
+          ) {
+            return plain(403, 'Props are posted from the workbench page alone.');
+          }
+        }
+
+        const page =
+          "default-src 'none'; style-src 'unsafe-inline'; frame-src 'self'; form-action 'self'; " +
+          "frame-ancestors 'none'; base-uri 'none'";
+
+        try {
+          const app = (await load(server, environment, module)).default;
+          if (
+            !isRecord(app) ||
+            typeof app.renderPage !== 'function' ||
+            typeof app.renderElement !== 'function'
+          ) {
+            throw new Error(
+              `${module} must export a default workbench: its pages, components, renderPage and renderElement.`,
+            );
+          }
+          const entries = isRecord(app[kind]) ? app[kind] : {};
+          const names = Object.keys(entries)
+            .filter((n) => NAME.test(n))
+            .sort();
+
+          if (name === undefined) {
+            return send(200, 'text/html', index(kind, prefix, entries, names), page);
+          }
+          if (!NAME.test(name) || !names.includes(name) || !Object.hasOwn(entries, name)) {
+            return plain(404, `No such ${kind === 'pages' ? 'page' : 'component'}.`);
+          }
+          const entry = entries[name];
+          const samples = isRecord(entry?.samples) ? entry.samples : {};
+          const sampleNames = Object.keys(samples).filter((n) => NAME.test(n));
+          const asked = url.searchParams.get('sample') ?? sampleNames[0] ?? '';
+          if (!posted && (!NAME.test(asked) || !Object.hasOwn(samples, asked))) {
+            return plain(404, 'No such sample.');
+          }
+
+          if (action === undefined) {
+            return send(
+              200,
+              'text/html',
+              detail(kind, prefix, name, sampleNames, asked, samples[asked], scripted, client !== undefined),
+              page,
+            );
+          }
+
+          let given = samples[asked];
+          let sample = samples[asked];
+          if (posted) {
+            const form = await postedProps(req);
+            given = form.props;
+            sample =
+              NAME.test(form.sample) && Object.hasOwn(samples, form.sample)
+                ? samples[form.sample]
+                : undefined;
+          }
+          const prerenderer = await load(server, ssrEnvironment, ssr);
+          if (typeof prerenderer.prerenderHtml !== 'function') {
+            throw new Error(`${ssr} must export prerenderHtml(rscStream), answering the whole HTML.`);
+          }
+          const drawn = await render(
+            app,
+            prerenderer,
+            kind,
+            entry,
+            given,
+            answersFor(entry, sample, given),
+            scripted,
+          );
+          const styles = typeof css === 'function' ? String((await css()) ?? '') : '';
+          if (scripted) {
+            const nonce = randomBytes(16).toString('base64');
+            const html = scriptedFrame(
+              drawn.html,
+              styles,
+              drawn.rows ?? [],
+              nonce,
+              await clientUrl(server, client, base),
+              server.config.plugins.some((p) => p.name === 'vite:react-refresh')
+                ? `${base}@react-refresh`
+                : null,
+            );
+            // Its own origin, an opaque one: no cookie, no storage, no
+            // reach into this page or the app's. Script under the nonce and
+            // from the dev server alone, which answers its modules to that
+            // origin only for a Referer of its own (forScriptedFrame); eval
+            // for React's development build, as the app's dev pages allow.
+            // It connects nowhere -- no fetch, no socket, so no request of
+            // the app's, Vite's HMR included -- posts no form and frames
+            // nothing. Its Referer is sent, to this origin alone, since that
+            // is what lets its modules load.
+            return send(
+              200,
+              'text/html',
+              html,
+              `sandbox allow-scripts; default-src 'none'; script-src 'nonce-${nonce}' 'unsafe-eval' ${origin}${base}; ` +
+                `style-src ${origin} 'unsafe-inline'; img-src ${origin} data: blob:; font-src ${origin} data:; ` +
+                "connect-src 'none'; form-action 'none'; frame-src 'none'; worker-src 'none'; object-src 'none'; " +
+                "frame-ancestors 'self'; base-uri 'none'",
+              'same-origin',
+            );
+          }
+          const html = forTheFrame(drawn.html, styles);
+          // Drawn in a sandbox of its own: no script and no form, by the
+          // sandbox and by the policy both, and nothing loaded but styles,
+          // fonts and images from here. It keeps this origin -- with no
+          // script to use it -- so the stylesheet's fonts, which are always
+          // fetched by CORS, load.
+          return send(
+            200,
+            'text/html',
+            html,
+            `sandbox allow-same-origin; default-src 'none'; script-src 'none'; style-src ${origin} 'unsafe-inline'; ` +
+              `img-src ${origin} data:; font-src ${origin} data:; frame-ancestors 'self'; base-uri 'none'; form-action 'none'`,
+          );
+        } catch (error) {
+          const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+          return plain(error instanceof WorkbenchRefused ? 400 : 500, message);
+        }
+      });
+    },
+  };
+}
+
+/**
+ * The URL the browser loads the app's client module by: under the dev
+ * server's base, by its path in the project, or through `@fs` for a file
+ * outside it.
+ */
+async function clientUrl(server, module, base) {
+  const env = server.environments.client;
+  const resolved = env ? await env.pluginContainer.resolveId(module, undefined) : null;
+  if (!resolved) throw new Error(`${module} does not resolve in the 'client' environment.`);
+  const root = server.config.root.replace(/\/?$/, '/');
+  const id = resolved.id.split('?')[0];
+  return id.startsWith(root) ? `${base}${id.slice(root.length)}` : `${base}@fs${id}`;
+}
+
+/**
+ * One render: a page's frame, or a component's element, from its props --
+ * the app's RSC stream, then the whole HTML from it; and, for a frame that
+ * runs the app's client script, the payload too, as rows.
+ */
+async function render(app, html, kind, entry, given, queries, keep = false) {
+  if (!isRecord(given)) throw new WorkbenchRefused('The props are a JSON object.');
+  const frame = {
+    rid: `workbench-${randomBytes(8).toString('hex')}`,
+    nonce: randomBytes(16).toString('base64'),
+    allow: Object.keys(queries).filter((q) => !q.startsWith('$')),
+  };
+  const client = sampleQueries(queries);
+
+  if (kind === 'pages') {
+    if (typeof entry.route !== 'string') throw new Error('A workbench page names its route.');
+    const pageFrame = {
+      ...frame,
+      route: entry.route,
+      params: isRecord(given.params) ? given.params : {},
+      data: { page: given.page ?? null, layouts: isRecord(given.layouts) ? given.layouts : {} },
+    };
+    return drawn(html, await app.renderPage(pageFrame, client, MINTS), keep);
+  }
+
+  if (typeof entry.render !== 'function') throw new Error('A playground component has a render(props).');
+  const props = isRecord(given.props) ? given.props : {};
+  return drawn(html, await app.renderElement(entry.render(props), frame, client, MINTS), keep);
+}
+
+/**
+ * The HTML of an RSC stream, and its payload where $keep: the stream read
+ * twice, the payload while the HTML is drawn from it.
+ *
+ * @param {{ prerenderHtml(stream: ReadableStream<Uint8Array>): Promise<ReadableStream<Uint8Array>> }} html
+ * @param {ReadableStream<Uint8Array>} stream
+ * @param {boolean} keep
+ */
+async function drawn(html, stream, keep) {
+  if (!keep) return { html: await readAll(await html.prerenderHtml(stream)), rows: null };
+  const [forHtml, forPayload] = stream.tee();
+  const payload = readBytes(forPayload);
+  const out = await readAll(await html.prerenderHtml(forHtml));
+  return { html: out, rows: payloadRows(await payload) };
+}
+
+/**
+ * The default export of `module`, imported in `environment` of the dev
+ * server, where it renders: that environment's own module runner, never
+ * Node's, so it shares React and the RSC plugin's set-up with the app.
+ */
+async function load(server, environment, module) {
+  const env = server.environments[environment];
+  if (!env?.runner) throw new Error(`The dev server has no runnable '${environment}' environment.`);
+  const resolved = await env.pluginContainer.resolveId(module, undefined);
+  if (!resolved) throw new Error(`${module} does not resolve in the '${environment}' environment.`);
+
+  return env.runner.import(resolved.id);
+}
+
+/** The list of pages or components, each with its samples. */
+function index(kind, prefix, entries, names) {
+  const title = kind === 'pages' ? 'Workbench' : 'Playground';
+  const items = names
+    .map((n) => {
+      const samples = isRecord(entries[n]?.samples)
+        ? Object.keys(entries[n].samples).filter((s) => NAME.test(s))
+        : [];
+      const links = samples
+        .map(
+          (s) =>
+            `<a href="${escapeHtml(`${prefix}/${n}?sample=${encodeURIComponent(s)}`)}">${escapeHtml(s)}</a>`,
+        )
+        .join(' · ');
+      const route =
+        kind === 'pages' && typeof entries[n]?.route === 'string'
+          ? ` <code>${escapeHtml(entries[n].route)}</code>`
+          : '';
+      return `<li><strong>${escapeHtml(n)}</strong>${route} ${links}</li>`;
+    })
+    .join('');
+  const other = kind === 'pages' ? ['__playground', 'components'] : ['__workbench', 'pages'];
+  const otherHref = prefix.replace(/__[a-z]+$/, other[0]);
+  return shell(
+    title,
+    `<h1>${title}</h1><p>The app's ${kind}, each drawn from its samples, in isolation. ` +
+      `<a href="${escapeHtml(otherHref)}">The ${other[1]}</a>.</p><ul>${items || '<li>None yet.</li>'}</ul>`,
+  );
+}
+
+/** One page or component: its samples, the props to edit, and the render beside them. */
+function detail(kind, prefix, name, sampleNames, asked, sample, scripted = false, canScript = false) {
+  const base = `${prefix}/${name}`;
+  const script = scripted ? '&script=1' : '';
+  const tabs = sampleNames
+    .map((s) =>
+      s === asked
+        ? `<strong>${escapeHtml(s)}</strong>`
+        : `<a href="${escapeHtml(`${base}?sample=${encodeURIComponent(s)}${script}`)}">${escapeHtml(s)}</a>`,
+    )
+    .join(' · ');
+  // Static, or with the app's client script in a frame of an origin of its own.
+  const modes = canScript
+    ? `<p>${
+        scripted
+          ? `<a href="${escapeHtml(`${base}?sample=${encodeURIComponent(asked)}`)}">Static</a> · <strong>With client script</strong>` +
+            ' — hydrated in a sandbox of its own origin: it holds no cookie, connects nowhere and posts no form, so a query or an action it makes fails.'
+          : `<strong>Static</strong> · <a href="${escapeHtml(`${base}?sample=${encodeURIComponent(asked)}&script=1`)}">With client script</a>`
+      }</p>`
+    : '';
+  const json = JSON.stringify(
+    sample ?? {},
+    (_key, value) => (typeof value === 'function' ? FUNCTION_SHOWN : value),
+    2,
+  );
+  const render = `${base}/render?sample=${encodeURIComponent(asked)}${script}`;
+  return shell(
+    name,
+    `<p><a href="${escapeHtml(prefix)}">${kind === 'pages' ? 'Workbench' : 'Playground'}</a></p>` +
+      `<h1>${escapeHtml(name)}</h1><p>${tabs}</p>${modes}` +
+      `<form method="post" action="${escapeHtml(`${base}/render${scripted ? '?script=1' : ''}`)}" target="drawn">` +
+      `<input type="hidden" name="sample" value="${escapeHtml(asked)}">` +
+      `<textarea name="props" spellcheck="false">${escapeHtml(json)}</textarea>` +
+      '<p><button type="submit">Draw with these props</button> ' +
+      `A query the sample answers with a function shows as <code>${FUNCTION_SHOWN}</code> and is still answered by it; ` +
+      'give a value under <code>queries</code> to change it.</p></form>' +
+      // Never both: a frame that runs script and keeps this origin could
+      // take its own sandbox off.
+      `<iframe name="drawn" src="${escapeHtml(render)}" sandbox="${scripted ? 'allow-scripts' : 'allow-same-origin'}" title="${escapeHtml(name)}"></iframe>`,
+  );
+}
+
+/** @param {string} title @param {string} body */
+function shell(title, body) {
+  return (
+    `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(title)} · workbench</title>` +
+    '<style>body{font:14px/1.5 system-ui,sans-serif;margin:24px;color:#111110;background:#F7F7F5}' +
+    'iframe{width:100%;height:720px;border:1px solid #E6E5E1;background:#fff}' +
+    'textarea{width:100%;height:220px;font:12px/1.4 ui-monospace,monospace;border:1px solid #E6E5E1;padding:8px}' +
+    'li{margin:4px 0}</style>' +
+    `</head><body>${body}</body></html>`
+  );
+}