@transclude/core 0.2.0 → 0.3.0

package/README.md

@@ -1,4 +1,21 @@
-# transclude
+<h1 align="center">transclude</h1>
+
+<p align="center">An HTML-first server-side web framework.</p>
+
+<p align="center">
+  <a href="https://github.com/transclude-dev/transclude/actions/workflows/ci.yml"
+    ><img alt="CI" src="https://github.com/transclude-dev/transclude/actions/workflows/ci.yml/badge.svg"
+  /></a>
+  <a href="https://www.npmjs.com/package/@transclude/core"
+    ><img alt="npm" src="https://img.shields.io/npm/v/%40transclude%2Fcore?color=0b7285"
+  /></a>
+  <a href="https://transclude.dev/docs/runtimes"
+    ><img alt="node" src="https://img.shields.io/node/v/%40transclude%2Fcore?color=0b7285"
+  /></a>
+  <a href="https://github.com/transclude-dev/transclude/blob/main/LICENSE"
+    ><img alt="MIT" src="https://img.shields.io/npm/l/%40transclude%2Fcore?color=0b7285"
+  /></a>
+</p>
 
 HTML is the product. A page is an `.html` file, the directory tree is the route
 table, and any fragment of a page is a URL of its own. Nothing has to run in the
@@ -52,7 +69,7 @@ so a swap cannot drift from the page it replaces part of.
 
 ## What is in it
 
-- **Pages and endpoints.** An `.html` file answers GET; its `POST`, `PUT`,
+- **Pages and endpoints.** An `.html` file responds to GET; its `POST`, `PUT`,
   `PATCH` and `DELETE` exports answer the rest, so a plain `<form method="post">`
   works. A `.js` file in the same tree returns a `Response`.
 - **Fragments.** Mark an element `fragment` and it has a URL of its own. htmx,
@@ -106,6 +123,7 @@ npm run htmx          # the same, driven by htmx, on http://localhost:1965
 npm run includes      # transclusion on http://localhost:1966
 npm run auth          # a guarded section on http://localhost:1967
 npm run live          # server-sent events on http://localhost:1968
+npm run elements      # light and shadow elements on http://localhost:1969
 npm run check:src     # type-check the framework itself
 ```
 
@@ -115,7 +133,8 @@ prerendered site with a sitemap and a feed, `search` swaps a fragment into a
 page that works without it, `htmx` does the same with htmx and the
 `HX-Target` header, `includes` shows transclusion from three sources,
 `auth` guards a section with a layout and a signed cookie, `live` pushes
-updates over server-sent events, and `showcase` uses every feature and is where the
+updates over server-sent events, `elements` puts a light and a shadow element
+side by side, and `showcase` uses every feature and is where the
 browser checks live, because those need an app to run against. `www/` is the site at transclude.dev: a landing page, the
 documentation under `/docs`, and itself built with the framework.
 

package/bin/build.js

@@ -16,7 +16,7 @@ import { pathToFileURL } from 'node:url';
 import { build } from 'vite';
 import transclude from '../src/plugin.js';
 import { loadProject } from '../src/project.js';
-import { absoluteFrom, renderRoute, responseOf } from '../src/document.js';
+import { absoluteFrom, renderRoute, responseOf, urlFor } from '../src/document.js';
 import { feed, feedPath } from '../src/feed.js';
 import { includeContext } from '../src/include.js';
 import { nodeLookup } from '../src/lookup.js';
@@ -111,9 +111,15 @@ await build({
   },
 });
 
+// A worker entry imports this bundle, and an editor set to check the app's JS
+// then checks a file nobody wrote. Twenty errors in the showcase, all of them
+// about generated code. The banner is what keeps it out of that program.
+const entry = path.join(dist, 'server/entry.js');
+fs.writeFileSync(entry, `// @ts-nocheck\n${fs.readFileSync(entry, 'utf8')}`);
+
 // ---- prerender ------------------------------------------------------------
 
-const { pages } = await import(pathToFileURL(path.join(dist, 'server/entry.js')).href);
+const { pages } = await import(pathToFileURL(entry).href);
 
 /**
  * A static route has one URL. A dynamic route has as many as its `paths` export
@@ -134,7 +140,7 @@ async function urlsFor(route) {
 
   const listed = (await paths()) ?? [];
   return listed.map((params) => ({
-    url: route.pattern.replace(/:(\w+)(\{[^}]*\})?/g, (_, name) => String(params[name] ?? '')),
+    url: urlFor(route, params),
     params,
   }));
 }

package/bin/check.js

@@ -23,7 +23,22 @@ if (!fs.existsSync(types) || fs.readFileSync(types, 'utf8') !== next) {
 
 // Nothing downstream reads this file, so nothing else would notice it being
 // wrong. Parse what we just wrote, or a bad identifier ships silently.
-const emitted = ts.createProgram([types], { noEmit: true, skipLibCheck: true });
+//
+// `skipLibCheck` has to be off, and it was on. This is a .d.ts, which is the one
+// kind of file that flag skips, so the guard checked nothing at all: every
+// project shipped a file naming `__Cookies` and declaring it nowhere. An editor
+// missed it too, because a jsconfig.json implies the same flag.
+//
+// `types: []` keeps it to this file: whatever `@types` a project happens to have
+// installed is not what is being checked here, and one of them failing to
+// resolve its own dependency would read as our file being broken.
+const emitted = ts.createProgram([types], {
+  noEmit: true,
+  skipLibCheck: false,
+  types: [],
+  target: ts.ScriptTarget.ESNext,
+  lib: ['lib.esnext.d.ts', 'lib.dom.d.ts'],
+});
 const broken = [
   ...emitted.getSyntacticDiagnostics(),
   ...emitted.getSemanticDiagnostics(),
@@ -63,16 +78,23 @@ for (const file of files) {
     const text = lines[line - 1] ?? '';
     const trimmed = text.replace(/^\s+/, '');
     const shift = text.length - trimmed.length;
+    // The caret line is drawn under the trimmed source, so the column moves left
+    // by however much indentation was cut. A run is capped so one long span does
+    // not wrap the terminal.
+    const pad = ' '.repeat(Math.max(0, column - shift));
+    const run = '~'.repeat(Math.max(1, Math.min(diagnostic.length, 60)));
+
     console.log(`\n    ${trimmed}`);
-    console.log(`    ${' '.repeat(Math.max(0, column - shift))}${'~'.repeat(Math.max(1, Math.min(diagnostic.length, 60)))}`);
+    console.log(`    ${pad}${run}`);
   }
 }
 
-const total = errors + warnings;
-console.log(
-  total
-    ? `\n${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'} in ${files.length} files`
-    : `\nNo type errors in ${files.length} files.`,
-);
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+
+if (errors + warnings) {
+  console.log(`\n${plural(errors, 'error')}, ${plural(warnings, 'warning')} in ${files.length} files`);
+} else {
+  console.log(`\nNo type errors in ${files.length} files.`);
+}
 
 process.exitCode = errors ? 1 : 0;

package/bin/dev.js

@@ -19,7 +19,7 @@ import {
   runAction,
   withEnvelope,
 } from '../src/document.js';
-import { clientEntryUrl, pageModuleId } from '../src/plugin.js';
+import transclude, { clientEntryUrl, pageModuleId } from '../src/plugin.js';
 import { resolveRoutesDir, scanRoutes } from '../src/routes.js';
 import { baseApp, endpointMethods, runEndpoint, SERVER_FILE } from '../src/server.js';
 import { randomBytes } from 'node:crypto';
@@ -71,6 +71,11 @@ const server = http.createServer();
 const vite = await createViteServer({
   root,
   appType: 'custom',
+  // Passed here rather than left to the project's own `vite.config.js`, which is
+  // where dev used to get it. A project needs no Vite config at all, and the one
+  // built here is the one `loadProject` filled in, so dev compiles against the
+  // same config the build does. `configResolved` ignores a second registration.
+  plugins: [transclude(config)],
   server: { middlewareMode: true, hmr: { server } },
   // Vite would serve these itself, ahead of Hono, and production would serve
   // them a different way, which is how dev and production come to disagree. One
@@ -229,7 +234,10 @@ async function loadMiddleware() {
   if (!fs.existsSync(serverFile)) return null;
 
   const url = `/${config.appDir}/${SERVER_FILE}`;
-  const node = await vite.moduleGraph.getModuleByUrl(url, true);
+  // Vite's second argument is `ssr`. This module is only ever loaded through
+  // `ssrLoadModule`, so the SSR graph is the one holding it.
+  const ssr = true;
+  const node = await vite.moduleGraph.getModuleByUrl(url, ssr);
   if (node) vite.moduleGraph.invalidateModule(node);
 
   const mod = await vite.ssrLoadModule(url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "An HTML-first server framework. A page is an .html file, the directory tree is the route table, and any fragment of a page is a URL of its own. Runs on Node, Bun, Deno and workerd, and ships no client JavaScript by default.",
   "keywords": [
     "html",
@@ -57,7 +57,7 @@
   ],
   "scripts": {
     "test": "node --test \"test/**/*.test.js\"",
-    "test:examples": "npm test --prefix examples/showcase && npm test --prefix examples/todomvc && npm test --prefix examples/blog && npm test --prefix examples/search && npm test --prefix examples/htmx && npm test --prefix examples/includes && npm test --prefix examples/auth && npm test --prefix examples/live",
+    "test:examples": "npm test --prefix examples/showcase && npm test --prefix examples/todomvc && npm test --prefix examples/blog && npm test --prefix examples/search && npm test --prefix examples/htmx && npm test --prefix examples/includes && npm test --prefix examples/auth && npm test --prefix examples/live && npm test --prefix examples/elements",
     "test:www": "npm test --prefix www",
     "showcase": "npm run dev --prefix examples/showcase",
     "todomvc": "npm run dev --prefix examples/todomvc",
@@ -67,6 +67,7 @@
     "includes": "npm run dev --prefix examples/includes",
     "auth": "npm run dev --prefix examples/auth",
     "live": "npm run dev --prefix examples/live",
+    "elements": "npm run dev --prefix examples/elements",
     "www": "npm run dev --prefix www",
     "check:src": "tsc -p tsconfig.src.json",
     "release": "node bin/release.js"

package/skills/transclude/SKILL.md

@@ -96,7 +96,7 @@ the render, which is how a layout does a login redirect.
 
 ## Forms and actions
 
-A page answers GET with its loader. Other verbs are named exports on the same
+A page responds to GET with its loader. Other verbs are named exports on the same
 file.
 
 ```html

package/src/address.js

@@ -69,8 +69,15 @@ export function parseV6(text) {
   const halves = body.split('::');
   if (halves.length > 2) return null;
 
-  const read = (part) =>
-    part === '' ? [] : part.split(':').map((g) => (/^[0-9a-f]{1,4}$/i.test(g) ? parseInt(g, 16) : NaN));
+  // Each half of a `::` is groups of up to four hex digits. A group that is not
+  // becomes NaN, which the caller checks for rather than throwing here.
+  const read = (part) => {
+    if (part === '') return [];
+    return part.split(':').map((group) => {
+      if (!/^[0-9a-f]{1,4}$/i.test(group)) return NaN;
+      return parseInt(group, 16);
+    });
+  };
 
   const head = read(halves[0]);
   const rest = halves.length === 2 ? read(halves[1]) : [];

package/src/app.js

@@ -39,6 +39,71 @@ const encoder = new TextEncoder();
 /** Below this, the framing costs more than it saves. A 91 byte file gzips to 120. */
 export const COMPRESSIBLE_FLOOR = 512;
 
+/**
+ * Sends the best representation the client will accept. `Vary` is not optional
+ * here: without it a shared cache would serve one encoding to everyone.
+ */
+function send(c, entry, cacheControl, status = 200) {
+  // The key list is built once per entry rather than per request. An entry is
+  // produced at load time and never changes, so the spread was a fresh array
+  // for every hit on the same file.
+  entry.encodingList ??= [...entry.encodings.keys()];
+  const encoding = pickEncoding(c.req.header('accept-encoding'), entry.encodingList);
+  const chosen = encoding ? entry.encodings.get(encoding) : null;
+
+  const body = chosen?.body ?? entry.body;
+  const etag = chosen?.etag ?? entry.etag;
+
+  c.header('Vary', 'Accept-Encoding');
+  c.header('Cache-Control', cacheControl);
+  c.header('ETag', etag);
+
+  if (c.req.header('if-none-match') === etag) return c.body(null, 304);
+
+  if (chosen) c.header('Content-Encoding', encoding);
+  c.header('Content-Type', entry.type);
+  c.header('Content-Length', String(body.length));
+  return c.body(body, status);
+}
+
+/**
+ * What a page is going to ask for, said in a header.
+ *
+ * This is not streaming. Render is `__o += …` to the last component, which is
+ * what lets an include resolve before it and a prerendered page stay a file,
+ * and making it async would tax every component call for something most pages
+ * here do not need. So the body still leaves in one piece.
+ *
+ * What it does buy: the stylesheet and the client entry come from the route
+ * table, not from a loader, so they are known before any loader runs. A proxy
+ * that reads this sends a 103 and the browser fetches them while the page is
+ * still being made. Cloudflare and Fastly do. A browser reading it directly
+ * gets less, since these headers arrive with the body anyway.
+ */
+function preloadHeader(stylesheet, clientEntry) {
+  const parts = [];
+  if (stylesheet) parts.push(`<${stylesheet}>; rel=preload; as=style`);
+  if (clientEntry) parts.push(`<${clientEntry}>; rel=preload; as=script; crossorigin`);
+  return parts.length ? parts.join(', ') : null;
+}
+
+/**
+ * Whether this render can be handed to the next visitor.
+ *
+ * Three ways it cannot. It answered with a `Response`, it is not 2xx, or it is
+ * personal. Personal means a header was written *or* a cookie was read. The
+ * second half matters: a page that only reads a cookie and renders a count from
+ * it sets no header at all, and holding it would hand one visitor's count to the
+ * next.
+ */
+function isShareable(html, ctx) {
+  if (html instanceof Response) return false;
+  if (ctx.response.status >= 300) return false;
+
+  const wroteHeader = [...ctx.response.headers.keys()].length > 0;
+  return !wroteHeader && !ctx.cookies.personal;
+}
+
 /**
  * `statics`, `assets`, `notFound` and `errorPage` are bytes from wherever the
  * runtime keeps them; `publicFiles` is a Hono handler or null; `compress` is null
@@ -50,6 +115,24 @@ export const COMPRESSIBLE_FLOOR = 512;
  * `subtle.digest`. Awaiting costs nothing on the first and is the only way to
  * accept the second.
  *
+ * The body is long because the order routes are registered in *is* the behavior,
+ * so it is written out once, in that order, rather than split across functions
+ * that could be called in a different one. What gets registered, in order:
+ *
+ *   /assets/*        hashed, so immutable
+ *   sitemap, precache, feed, proxy    each only if the config asked for it
+ *   fragments and actions             every route, before anything static
+ *   endpoints                         before the static handler, which matches
+ *                                     on path alone and would answer first
+ *   prerendered pages                 bytes from disk
+ *   pages                             every route, not only the dynamic ones
+ *   not found
+ *
+ * The two rules worth knowing: a fragment or an action has to come before the
+ * prerendered handler, and an endpoint's path has no file behind it but
+ * `/api/notes` and a prerendered `/api/notes/index.html` look the same to a
+ * matcher.
+ *
  * @param {{ config: object, manifest: object, pages: Record<string, object>,
  *   endpoints?: Record<string, object>, statics?: object, assets?: object,
  *   notFound?: object|null, errorPage?: object|null, hash: Function,
@@ -162,12 +245,6 @@ export function createApp({
    */
   const varyOn = header ? `Accept-Encoding, ${header}` : 'Accept-Encoding';
 
-  /**
-   * Fragments and actions come first, and for every route rather than only the
-   * dynamic ones: a page whose document was prerendered still has regions worth
-   * asking for and mutations worth accepting, and the prerendered handler below
-   * matches on path alone, so it would answer either one with a static document.
-   */
   // Before the route table, like the public files, so a `[...path]` catch-all
   // cannot answer for it.
   if (config.sitemap) {
@@ -209,6 +286,12 @@ export function createApp({
     app.get(PROXY_PATH, (c) => handler(c.req.raw));
   }
 
+  /**
+   * Fragments and actions come first, and for every route rather than only the
+   * dynamic ones: a page whose document was prerendered still has regions worth
+   * asking for and mutations worth accepting, and the prerendered handler below
+   * matches on path alone, so it would answer either one with a static document.
+   */
   for (const route of manifest.routes ?? []) {
     app.get(route.pattern, async (c, next) => {
       const region = regionOf(route, c);
@@ -313,12 +396,11 @@ export function createApp({
 
     app.get(route.pattern, async (c) => {
       try {
-        // One render, called by the cache when it needs one and directly when
-        // the route has no window. `cacheable` is the same rule the build uses
-        // to decide a route can be a file: a 2xx with no header a file could not
-        // carry. A `Set-Cookie` in a shared cache is one visitor's session
-        // handed to the next.
-        let rendered = null;
+        // The cache calls this when it needs a render and nothing calls it on a
+        // hit, so what it produced is left here for the lines after. A hit
+        // leaves it null, which is the difference the code below reads.
+        let last = null;
+
         const render = async () => {
           const ctx = contextFor(route, c);
           const html = await renderRoute(pages[route.id], ctx, {
@@ -329,32 +411,27 @@ export function createApp({
             include,
           });
 
-          rendered = { ctx, html };
-          const ok = !(html instanceof Response) && ctx.response.status < 300;
-          // Three ways a page is not a shared answer: it answered with a
-          // Response, it is not 2xx, or it is personal. Personal means a header
-          // was written *or* a cookie was read. The second half matters: a page
-          // that only reads a cookie and renders a count from it sets no header
-          // at all, and holding it would hand one visitor's count to the next.
-          const shared = [...ctx.response.headers.keys()].length === 0 && !ctx.cookies.personal;
-          return { html, cacheable: ok && shared };
+          last = { ctx, html };
+          return { html, cacheable: isShareable(html, ctx) };
         };
 
-        if (window) {
-          const html = await cache.read(cacheKey(c.req.url), window, render);
+        if (!window) {
+          await render();
+          const { ctx, html } = last;
+          if (html instanceof Response) return withEnvelope(html, ctx);
+          return sendRendered(c, html, ctx, preload);
+        }
 
-          // A miss renders through the cache, and that render can answer with a
-          // `Response`. It was not stored, but it is still the answer.
-          if (html instanceof Response) return withEnvelope(html, rendered.ctx);
+        const html = await cache.read(cacheKey(c.req.url), window, render);
 
-          // A hit ran no loader, so there is no envelope to carry. A cached page
-          // has none by definition: one with a header was never stored.
-          return sendRendered(c, html, rendered?.ctx ?? contextFor(route, c), preload);
-        }
+        // A miss rendered through the cache, and that render can answer with a
+        // `Response`. It was not stored, but it is still the answer.
+        if (html instanceof Response) return withEnvelope(html, last.ctx);
 
-        await render();
-        if (rendered.html instanceof Response) return withEnvelope(rendered.html, rendered.ctx);
-        return sendRendered(c, rendered.html, rendered.ctx, preload);
+        // A hit ran no loader, so there is no envelope to carry: a page with a
+        // header was never stored. It still needs a context to send with.
+        const ctx = last ? last.ctx : contextFor(route, c);
+        return sendRendered(c, html, ctx, preload);
       } catch (err) {
         return internalError(c, err);
       }
@@ -388,27 +465,6 @@ export function createApp({
     }
   }
 
-  /**
-   * What a page is going to ask for, said in a header.
-   *
-   * This is not streaming. Render is `__o += …` to the last component, which is
-   * what lets an include resolve before it and a prerendered page stay a file,
-   * and making it async would tax every component call for something most pages
-   * here do not need. So the body still leaves in one piece.
-   *
-   * What it does buy: the stylesheet and the client entry come from the route
-   * table, not from a loader, so they are known before any loader runs. A proxy
-   * that reads this sends a 103 and the browser fetches them while the page is
-   * still being made. Cloudflare and Fastly do. A browser reading it directly
-   * gets less, since these headers arrive with the body anyway.
-   */
-  function preloadHeader(stylesheet, clientEntry) {
-    const parts = [];
-    if (stylesheet) parts.push(`<${stylesheet}>; rel=preload; as=style`);
-    if (clientEntry) parts.push(`<${clientEntry}>; rel=preload; as=script; crossorigin`);
-    return parts.length ? parts.join(', ') : null;
-  }
-
   /** Every `catch` above. One place decides what a failed request looks like. */
   function internalError(c, err) {
     report(err, c);
@@ -421,33 +477,6 @@ export function createApp({
     return c.body(errorPage.body, 500);
   }
 
-  /**
-   * Sends the best representation the client will accept. `Vary` is not optional
-   * here: without it a shared cache would serve one encoding to everyone.
-   */
-  function send(c, entry, cacheControl, status = 200) {
-    // The key list is built once per entry rather than per request. An entry is
-    // produced at load time and never changes, so the spread was a fresh array
-    // for every hit on the same file.
-    entry.encodingList ??= [...entry.encodings.keys()];
-    const encoding = pickEncoding(c.req.header('accept-encoding'), entry.encodingList);
-    const chosen = encoding ? entry.encodings.get(encoding) : null;
-
-    const body = chosen?.body ?? entry.body;
-    const etag = chosen?.etag ?? entry.etag;
-
-    c.header('Vary', 'Accept-Encoding');
-    c.header('Cache-Control', cacheControl);
-    c.header('ETag', etag);
-
-    if (c.req.header('if-none-match') === etag) return c.body(null, 304);
-
-    if (chosen) c.header('Content-Encoding', encoding);
-    c.header('Content-Type', entry.type);
-    c.header('Content-Length', String(body.length));
-    return c.body(body, status);
-  }
-
   /**
    * A response rendered for this request. There is no prebuilt variant to reach
    * for, so the ETag is computed here and the body is compressed on the way out.

package/src/compiler/ambient.js

@@ -0,0 +1,99 @@
+// The types a shim declares for itself, in one place.
+//
+// A shim writes JSDoc and transclude-env.d.ts writes TypeScript, so the same
+// shape had two spellings and only one of them was ever written. Every context
+// type in the emitted file named `__Cookies` and nothing declared it, which no
+// check reported: a jsconfig.json implies `skipLibCheck`, and the guard in
+// `bin/check.js` written to catch exactly this passes it too, so the file it
+// checks is the one kind of file that flag skips.
+
+/**
+ * Each entry is one type, written the way TypeScript spells it. `params` are the
+ * type parameters, which JSDoc writes as `@template` and a `.d.ts` writes in
+ * angle brackets.
+ */
+export const AMBIENT = [
+  {
+    name: '__CookieOptions',
+    params: [],
+    text:
+      "{ path?: string; domain?: string; maxAge?: number; expires?: Date; httpOnly?: boolean; secure?: boolean; sameSite?: 'Strict' | 'Lax' | 'None' }",
+  },
+  {
+    name: '__Cookies',
+    params: [],
+    text:
+      '{ get(name: string): string | undefined; all(): Record<string, string>; ' +
+      'set(name: string, value: string, options?: __CookieOptions): void; ' +
+      'delete(name: string, options?: __CookieOptions): void; ' +
+      'signed: { get(name: string): Promise<string | undefined>; ' +
+      'all(): Promise<Record<string, string>>; ' +
+      'set(name: string, value: string, options?: __CookieOptions): Promise<void> } }',
+  },
+  {
+    // The mapping is what keeps `${user.nmae}` an error. TypeScript treats a type
+    // that came straight from an object literal in a .js file as open for expando
+    // properties, so reading an undeclared one is allowed. Remapping the keys
+    // gives an ordinary object type, where it is not.
+    //
+    // The conditional widens a bare `[]`, which otherwise infers `never[]` and
+    // turns "no annotation" from "less checking" into a page of errors about a
+    // type nobody wrote.
+    name: '__Shape',
+    params: ['T'],
+    text: '{ [K in keyof T]: T[K] extends never[] ? any[] : T[K] }',
+  },
+];
+
+export const AMBIENT_NAMES = new Set(AMBIENT.map(({ name }) => name));
+
+/**
+ * The JSDoc a shim carries for the given names. A name JSDoc cannot resolve is
+ * `any` rather than an error, so a shim that names one of these without this is
+ * checking nothing and saying so nowhere.
+ *
+ * @param {string[]} names
+ * @returns {string}
+ */
+export function ambientJsdoc(names) {
+  return AMBIENT.filter(({ name }) => names.includes(name))
+    .map(({ name, params, text }) => {
+      const template = params.length ? ` * @template ${params.join(', ')}\n` : '';
+      return `/**\n${template} * @typedef {${text}} ${name}\n */\n`;
+    })
+    .join('');
+}
+
+/**
+ * The same types as TypeScript declarations, for the emitted file. Only the ones
+ * it mentions: an unused type in a generated file is noise.
+ *
+ * @param {string} body what the file says so far
+ * @param {(type: string) => string} [format] how to lay a type out
+ * @returns {string[]} the lines to put above it
+ */
+export function ambientDeclarations(body, format = (type) => type) {
+  // One of these names another, so keep looking until a pass adds nothing:
+  // `__Cookies` alone would leave `__CookieOptions` undeclared, which is the
+  // whole bug again one level down.
+  const used = [];
+  for (let text = body, added = true; added; ) {
+    added = false;
+    for (const type of AMBIENT) {
+      if (used.includes(type) || !new RegExp(`\\b${type.name}\\b`).test(text)) continue;
+      used.push(type);
+      text += type.text;
+      added = true;
+    }
+  }
+  if (!used.length) return [];
+
+  return [
+    '// Declared by the compiler. Every context type below names these.',
+    ...used.map(({ name, params, text }) => {
+      const generics = params.length ? `<${params.join(', ')}>` : '';
+      return `type ${name}${generics} = ${format(text)};`;
+    }),
+    '',
+  ];
+}