@transclude/core 0.6.0 → 0.8.0

package/bin/build.js

@@ -16,7 +16,8 @@ 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, urlFor } from '../src/document.js';
+import { renderRoute, urlFor } from '../src/document.js';
+import { prerenderContext, refusePrerender } from '../src/prerender.js';
 import { feed, feedPath } from '../src/feed.js';
 import { includeContext } from '../src/include.js';
 import { nodeLookup } from '../src/lookup.js';
@@ -25,7 +26,6 @@ import { etagOf, loadAssets, loadStatic } from '../src/static-cache.js';
 import { buildSprite, readLibraries, refuseSpriteClash, spritePath } from '../src/icons.js';
 import { PRECACHE_PATH, precacheDocument, precacheList } from '../src/precache.js';
 import { speculateSettings, speculationRules } from '../src/speculate.js';
-import { cookiesOf } from '../src/cookies.js';
 import { pool } from '../src/pool.js';
 import { precompress } from '../src/compress.js';
 
@@ -148,24 +148,19 @@ async function urlsFor(route) {
 }
 
 /**
- * A prerendered file has no status and no headers. It is a file. So a loader
- * that answered with a Response, or set a status other than 200, is saying this
- * URL is not a page you can write down, and the build says so rather than
- * writing a file that lies about it.
+ * One page, rendered to the markup that gets written.
+ *
+ * What it is allowed to be, and the `ctx` it is given, are both in
+ * `src/prerender.js`, where they can be tested. Nothing imports this file.
  */
 async function render(route, { url, params }) {
-  const response = responseOf();
-  const ctx = {
-    url: `http://localhost${url}`,
+  const ctx = prerenderContext({
+    route,
+    url,
     params,
-    route: { id: route.id, pattern: route.pattern ?? '', path: url },
-    request: null,
-    fragment: null,
-    action: null,
-    response,
-    cookies: cookiesOf(null, response, config.cookieSecret),
-    absolute: absoluteFrom(config.metadataBase, null),
-  };
+    cookieSecret: config.cookieSecret,
+    metadataBase: config.metadataBase,
+  });
 
   const html = await renderRoute(pages[route.id], ctx, {
     clientEntry: assets.get(route.id) ?? null,
@@ -176,30 +171,7 @@ async function render(route, { url, params }) {
     include,
   });
 
-  if (html instanceof Response) {
-    throw new Error(`answered with ${html.status} instead of markup, so it cannot be prerendered`);
-  }
-  if (ctx.response.status !== 200) {
-    throw new Error(`answered ${ctx.response.status}, which no file can carry`);
-  }
-  // A file carries no headers either. A Set-Cookie or a Cache-Control written here
-  // would be thrown away, which is worse than being told.
-  const [header] = [...ctx.response.headers.keys()];
-  if (header) {
-    throw new Error(`set a ${header} header, which no file can carry`);
-  }
-  // Reading a cookie is what makes a page personal, and there is no request
-  // here to read one from. Whatever this file says about the reader is what a
-  // reader with no cookies would have seen, and every visitor gets that copy.
-  // A layout or an included route can do this without the page mentioning it,
-  // which is what makes it worth saying out loud.
-  if (ctx.cookies.personal) {
-    throw new Error(
-      `read a cookie, so it is different for each visitor and cannot be one file. ` +
-        `Give it \`export const prerender = false\`, or stop reading the cookie ` +
-        `here or in what it includes`,
-    );
-  }
+  refusePrerender(ctx, html);
   return html;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.6.0",
+  "version": "0.8.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",

package/skills/transclude/references/elements.md

@@ -215,6 +215,31 @@ document.addEventListener(
 The element is then a real form field: it submits, resets and validates with the
 rest of them.
 
+### Saying it is invalid
+
+`host.internals` is the handle the platform hands out, so `setValidity` works the
+way it does on an input. `:invalid` matches, a submit is blocked, and the browser
+shows its own message.
+
+```html
+<script>
+  export const prototype = {
+    updated() {
+      const empty = !this.value;
+      this.internals.setValidity(
+        empty ? { valueMissing: true } : {},
+        empty ? 'Pick at least one tag.' : '',
+        this,
+      );
+    },
+  };
+</script>
+```
+
+Call it whenever the value changes, and pass no arguments to clear it. A field
+that cannot say it is wrong is not really a field, and this is the part most
+custom controls leave out.
+
 ## An icon element
 
 The framework compiles `app/icons/` into one `/icons.svg` and defines no element

package/skills/transclude/references/server.md

@@ -154,6 +154,80 @@ something built on Wasm fails there and nowhere else. A prerendered page never
 runs its loader in production, so this stays hidden until something asks for a
 fragment.
 
+### worker.js
+
+```js
+import { workerFrom } from '@transclude/core/worker';
+import * as bundle from './dist/server/assets.js';
+import * as entry from './dist/server/entry.js';
+import manifest from './dist/routes.json';
+import config from './transclude.config.js';
+
+export default workerFrom({ config, manifest, entry, bundle });
+```
+
+The imports stay in the app: a bundler needs a literal path. `workerFrom` builds
+the app on the first request, which is when `env` exists, and takes
+`cookieSecret` from `env.COOKIE_SECRET`. For anything else, call `createApp`
+from `@transclude/core/app` directly.
+
+### Bindings
+
+`ctx` has no `env`. It carries nothing that names one runtime, and `env` names
+one: the other three fill that slot with something else. A KV namespace, a D1
+database or a secret reaches a loader through the app instead.
+
+`worker.js` belongs to the app and does get `env`. Hold it in a module and
+import that.
+
+```js
+// app/lib/bindings.js — no `node:` imports, this ends up in the worker bundle
+/** @type {Env|null} */
+let current = null;
+
+export const hold = (env) => (current = env);
+
+export const bindings = () => {
+  if (!current) throw new Error('No bindings: this app is running off workerd.');
+  return current;
+};
+```
+
+`worker.js` calls `hold(env)` inside `appFor`, before the `app ??=` line. A
+loader then imports `bindings` and reads `bindings().DB`.
+
+Module scope is safe here because `env` is one object for the life of the
+isolate. Holding a `Request` the same way is not, since two visitors would share
+whichever arrived last.
+
+**A page that reads a binding needs `prerender = false`.** The build runs on
+Node, where nothing calls `hold`, so the build runs that loader and throws.
+
+### ctx.after
+
+`after(work)` takes a promise the reader does not wait for.
+
+```js
+export const prerender = false;
+
+export default async ({ after, url }) => {
+  after(recordView(url));
+  return { notes: await notes.all() };
+};
+```
+
+On workerd this is `waitUntil`, which keeps the isolate up past the response.
+Node, Bun and Deno keep running anyway, so it changes nothing there.
+
+It takes the promise, not a function returning one. A function is refused, since
+wrapping one would resolve to the function and run nothing.
+
+A rejection goes to `onError` with the request that started it. Nothing awaits
+this work, so leaving it would end the process on Node.
+
+Calling it from a prerendered page stops the build: a file has no response to
+outlive. `prerender = false` is the fix, as it is for a binding.
+
 ## Testing
 
 The app is a function from a request to a response.

package/src/after.js

@@ -0,0 +1,67 @@
+// Work that outlives the response.
+//
+// Every runtime here keeps a promise running after a response, except the one
+// that matters most for this. Node, Bun and Deno are processes, and a promise
+// nobody awaits finishes on its own. workerd is not: the isolate is allowed to
+// stop once the response is sent, and anything still running stops with it.
+// `waitUntil` is how a worker asks to stay up, and it exists nowhere else.
+//
+// So `ctx.after` is a capability rather than a runtime's API. It means the same
+// thing on all four: this work does not have to finish before the reader is
+// served. That is the bar `env` failed, which is why there is no `ctx.env`.
+//
+// No `node:` imports.
+
+/**
+ * The runtime's `ExecutionContext`, or null when it has none.
+ *
+ * Hono's getter throws rather than answering undefined, so the only way to ask
+ * is to try. The `try` covers the getter and nothing else: a `waitUntil` that
+ * throws is a real failure and belongs to the caller.
+ *
+ * @param {object} c a Hono context
+ * @returns {{ waitUntil: (work: Promise<unknown>) => void }|null}
+ */
+export function executionCtxOf(c) {
+  try {
+    return c.executionCtx;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `ctx.after` for one request.
+ *
+ * The rejection handling is the reason this is not one line at the call site.
+ * Nothing is awaiting this work, so a throw inside it reaches the runtime's
+ * unhandled rejection handler, which on Node ends the process. It goes to the
+ * same place a failed request goes instead, with the request that started it.
+ *
+ * `report` is called with the error alone. Whoever builds this already knows
+ * which request it belongs to.
+ *
+ * @param {object} c a Hono context
+ * @param {(error: unknown) => void} report where a failure goes
+ * @returns {(work: Promise<unknown>) => void}
+ */
+export function afterFor(c, report) {
+  return (work) => {
+    // A function is the mistake worth naming. `after(() => log())` would be
+    // wrapped by `Promise.resolve`, resolve to the function itself, and do
+    // nothing at all, which is the one shape that fails without a symptom.
+    if (typeof work?.then !== 'function') {
+      throw new TypeError(
+        '[transclude] ctx.after takes a promise. Call the work and pass what it ' +
+          'returns, as in `after(log(url))` rather than `after(() => log(url))`.',
+      );
+    }
+
+    const settled = Promise.resolve(work).catch(report);
+
+    // Only workerd has one. Everywhere else the promise is already running and
+    // the process is still there to finish it.
+    const execution = executionCtxOf(c);
+    if (execution) execution.waitUntil(settled);
+  };
+}

package/src/app.js

@@ -29,6 +29,8 @@ import {
 import { pickEncoding } from './negotiate.js';
 import { baseApp, endpointMethods, runEndpoint } from './server.js';
 import { cookiesOf } from './cookies.js';
+import { afterFor } from './after.js';
+import { withDefaults } from './defaults.js';
 
 const IMMUTABLE = 'public, max-age=31536000, immutable';
 const REVALIDATE = 'public, max-age=0, must-revalidate';
@@ -142,7 +144,11 @@ function isShareable(html, ctx) {
  * @returns {object} a Hono app, ready to serve
  */
 export function createApp({
-  config,
+  // Filled in here rather than by the caller, because only one of the four
+  // runtimes has a `loadProject` to fill them in on the way. A worker imports
+  // `transclude.config.js` and hands over exactly what the author wrote, so
+  // every key they left out was undefined until this line.
+  config: written,
   manifest,
   pages,
   endpoints = {},
@@ -163,6 +169,7 @@ export function createApp({
   // it the proxy's allowlist is the whole defense.
   lookup = null,
 }) {
+  const config = withDefaults(written);
   const cache = createCache(config.cache);
 
   // One resolver for the app, so several pages including the same document read
@@ -210,6 +217,9 @@ export function createApp({
       cookies: cookiesOf(c.req.raw, response, config.cookieSecret),
       absolute: absoluteFrom(config.metadataBase, c.req.url),
       revalidateTag: cache.revalidateTag,
+      // Reported through `report`, so work that fails after the reader is gone
+      // is not quieter than work that fails in front of them.
+      after: afterFor(c, (error) => report(error, c)),
       ...extra,
     };
   };

package/src/compiler/codegen.js

@@ -820,6 +820,8 @@ class Codegen {
    * Date crosses as an ISO string rather than as JSON.
    */
   emitAttrs(el, out, scope, ref = null) {
+    if (this.loops.length) assertUniqueTransitionName(el);
+
     for (const attr of el.attrs) {
       if (DIRECTIVES.has(attr.name)) continue;
 
@@ -1000,6 +1002,45 @@ export function gatherChain(nodes, i) {
  * @param {object} node
  * @returns {object[]} a template's live under `.content`, so walking `childNodes` finds nothing
  */
+/**
+ * A repeated element may not carry a `view-transition-name` written out.
+ *
+ * The name has to be unique in the document. Every copy of a repeated element
+ * would carry the same one, and the browser's answer to that is to run no
+ * transition at all: nothing throws, nothing is logged, the page just stops
+ * animating. That is the whole reason this is a compile error.
+ *
+ * `none` is allowed, because it is the one value that means "not part of a
+ * transition" and is safe to repeat.
+ *
+ * Only the `style` attribute is checked. A name applied through a class is in a
+ * stylesheet this compiler does not read, so this catches the spelling everyone
+ * writes rather than every spelling there is.
+ */
+function assertUniqueTransitionName(el) {
+  const style = el.attrs?.find((a) => a.name === 'style')?.value;
+  if (!style) return;
+
+  const at = style.indexOf('view-transition-name');
+  if (at === -1) return;
+
+  // Just this declaration, so `${}` elsewhere in the attribute does not excuse
+  // a name that is still written out.
+  const end = style.indexOf(';', at);
+  const declaration = end === -1 ? style.slice(at) : style.slice(at, end);
+
+  if (declaration.includes('${')) return;
+  if (/:\s*none\s*$/.test(declaration)) return;
+
+  throw new CompileError(
+    `<${el.tagName}> is repeated and writes out a view-transition-name, so every ` +
+      `copy would carry the same one. A name has to be unique in the document, and ` +
+      `a browser that finds two runs no transition at all rather than saying so. ` +
+      `Derive it from the loop, as in "view-transition-name: card-\${item.id}".`,
+    el,
+  );
+}
+
 export function childrenOf(node) {
   if (node.tagName === 'template' && node.content) return node.content.childNodes ?? [];
   return node.childNodes ?? [];

package/src/cookies.js

@@ -39,6 +39,21 @@ export function cookiesOf(request, response, secret = null) {
 
   const requireSecret = (what) => {
     if (secret) return secret;
+
+    // Set-but-empty is worth its own sentence. It happened on a real deploy:
+    // `wrangler secret put` took a blank line, so the binding existed, every
+    // `typeof` along the way said `string`, and the config carried it all the
+    // way here. The only thing that said otherwise was the length. Reading
+    // "needs a secret" while looking at a secret that is plainly set sends you
+    // hunting through the wiring instead of the value.
+    if (typeof secret === 'string') {
+      throw new Error(
+        `[transclude] ${what} needs a secret, and \`cookieSecret\` is set to an ` +
+          `empty string. Whatever supplies it handed over nothing: on a worker that ` +
+          `is usually a \`wrangler secret put\` that took a blank line`,
+      );
+    }
+
     throw new Error(
       `[transclude] ${what} needs a secret. Set \`cookieSecret\` in ` +
         `transclude.config.js (read it from the environment there, not from a literal)`,

package/src/defaults.js

@@ -0,0 +1,51 @@
+// What a config means when it does not say.
+//
+// Split out of `project.js` because that file reads a disk and this has to run
+// where there is no disk. `loadProject` is Node's way in, and a worker has no
+// equivalent: it imports `transclude.config.js` directly, so the object reaching
+// `createApp` there is exactly what the author wrote and nothing more.
+//
+// That gap was live for a while. `fragmentParam` was only ever filled in by
+// `loadProject`, so on workerd `config.fragmentParam` was undefined, the check
+// for it read as "no parameter configured", and every `?fragment=` request was
+// answered with the whole document. A swap then wrote a second copy of the page
+// into the element it was meant to replace. It looked like a compiler bug and it
+// was a missing default.
+//
+// Applied in `createApp` rather than in each entry, so there is one place and no
+// runtime can skip it.
+//
+// No `node:` imports.
+
+/** Every key with a value, and the value it takes when the config is quiet. */
+export const DEFAULTS = {
+  appDir: 'app',
+  routesDir: 'routes',
+  elementsDir: 'elements',
+  publicDir: 'public',
+  iconsDir: 'icons',
+  outDir: 'dist',
+  typesFile: 'app/transclude-env.d.ts',
+  stylesheet: null,
+  lang: 'en',
+  fragmentParam: 'fragment',
+  trailingSlash: 'never',
+  strict: false,
+  csrf: true,
+  csp: false,
+  speculate: false,
+};
+
+/**
+ * A config with every default filled in.
+ *
+ * A key the author wrote wins, including one written as `null` or `false`. Only
+ * an absent key takes the default, which is what lets `fragmentParam: null` turn
+ * the parameter off rather than quietly turning it back on.
+ *
+ * @param {object} [config] whatever `transclude.config.js` exported
+ * @returns {object} the same keys, plus the ones it did not mention
+ */
+export function withDefaults(config = {}) {
+  return { ...DEFAULTS, ...config };
+}

package/src/prerender.js

@@ -0,0 +1,110 @@
+// What a page is allowed to be, if it is going to be a file.
+//
+// A prerendered page is written once and served to everyone. It has no status,
+// no headers and no reader. So a loader that answers with a `Response`, sets a
+// status, writes a header or reads a cookie is saying this URL is not a page you
+// can write down, and the build says so rather than writing a file that lies
+// about it.
+//
+// Split out of `bin/build.js` so the refusals can be tested. Nothing imports
+// that file: it is a script that runs a build the moment it is loaded, so every
+// message here used to be checked by hand or not at all.
+//
+// No `node:` imports, though nothing needs that of this file yet. It is here
+// because the three modules it calls have the same rule.
+
+import { absoluteFrom, responseOf } from './document.js';
+import { cookiesOf } from './cookies.js';
+
+/**
+ * The `ctx` a loader is handed while the build renders it to a file.
+ *
+ * `revalidateTag` and `after` are refusals rather than absences. Left off the
+ * object they are `undefined`, and a loader calling one fails with `x is not a
+ * function`, which names neither what the page did nor how to stop. Both stay in
+ * the generated type either way, because the checker cannot know which pages
+ * become files.
+ *
+ * @param {object} options
+ * @param {{ id: string, pattern?: string }} options.route
+ * @param {string} options.url the path being written
+ * @param {Record<string, string>} options.params
+ * @param {string|null} [options.cookieSecret]
+ * @param {string} [options.metadataBase]
+ * @returns {object} the same shape a request gets, minus what a file cannot have
+ */
+export function prerenderContext({ route, url, params, cookieSecret = null, metadataBase }) {
+  const response = responseOf();
+
+  return {
+    url: `http://localhost${url}`,
+    params,
+    route: { id: route.id, pattern: route.pattern ?? '', path: url },
+    // Null here and at no other time, which is how a shared layout can skip the
+    // part that needs a visitor.
+    request: null,
+    fragment: null,
+    action: null,
+    response,
+    cookies: cookiesOf(null, response, cookieSecret),
+    absolute: absoluteFrom(metadataBase, null),
+
+    revalidateTag: () => {
+      throw new Error(
+        `called \`ctx.revalidateTag\`, and a build holds no rendered pages to drop. ` +
+          `Give it \`export const prerender = false\`, or move the call to the action ` +
+          `or endpoint that changes the data`,
+      );
+    },
+
+    after: () => {
+      throw new Error(
+        `called \`ctx.after\`, and a file has no response for that work to outlive. ` +
+          `Give it \`export const prerender = false\`, or start the work from an ` +
+          `endpoint or an action instead`,
+      );
+    },
+  };
+}
+
+/**
+ * Throws unless what was rendered can be written to a file.
+ *
+ * Called after the render rather than during it, because three of the four are
+ * things a loader does on the way past and only the finished `ctx` knows about.
+ * Every message continues a sentence whose subject is the page, since that is
+ * what the build prints above it.
+ *
+ * @param {object} ctx the context the render was given
+ * @param {string|Response} html what the render answered
+ * @throws when this URL cannot be one file
+ */
+export function refusePrerender(ctx, html) {
+  if (html instanceof Response) {
+    throw new Error(`answered with ${html.status} instead of markup, so it cannot be prerendered`);
+  }
+
+  if (ctx.response.status !== 200) {
+    throw new Error(`answered ${ctx.response.status}, which no file can carry`);
+  }
+
+  // A file carries no headers either. A Set-Cookie or a Cache-Control written
+  // here would be thrown away, which is worse than being told.
+  const [header] = [...ctx.response.headers.keys()];
+  if (header) {
+    throw new Error(`set a ${header} header, which no file can carry`);
+  }
+
+  // Reading a cookie is what makes a page personal, and there is no request here
+  // to read one from. Whatever this file says about the reader is what a reader
+  // with no cookies would have seen, and every visitor gets that copy. A layout
+  // or an included route can do this without the page mentioning it, which is
+  // what makes it worth saying out loud.
+  if (ctx.cookies.personal) {
+    throw new Error(
+      `read a cookie, so it is different for each visitor and cannot be one file. ` +
+        `Give it \`export const prerender = false\`, or stop reading the cookie ` +
+        `here or in what it includes`,
+    );
+  }
+}

package/src/project.js

@@ -11,6 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { withDefaults } from './defaults.js';
 
 export const CONFIG_FILE = 'transclude.config.js';
 
@@ -80,24 +81,11 @@ export function findRoot(from = process.cwd()) {
  *
  * `port` is not here. `portOf` already answers it, and it reads the environment
  * first, which a plain default cannot do.
+ *
+ * They live in `defaults.js` rather than here, because a worker has no
+ * `loadProject` and needs the same answers. `createApp` applies them for every
+ * runtime, and this file is only Node's way in.
  */
-const DEFAULTS = {
-  appDir: 'app',
-  routesDir: 'routes',
-  elementsDir: 'elements',
-  publicDir: 'public',
-  iconsDir: 'icons',
-  outDir: 'dist',
-  typesFile: 'app/transclude-env.d.ts',
-  stylesheet: null,
-  lang: 'en',
-  fragmentParam: 'fragment',
-  trailingSlash: 'never',
-  strict: false,
-  csrf: true,
-  csp: false,
-  speculate: false,
-};
 
 /**
  * The root and its config together, because nothing needs one without the other.
@@ -117,7 +105,7 @@ export async function loadProject(from = process.cwd()) {
     throw new Error(`[transclude] ${CONFIG_FILE} must export a config object as its default`);
   }
   assertNoSplitDirs(config, file);
-  return { root, config: { ...DEFAULTS, ...config }, configFile: file };
+  return { root, config: withDefaults(config), configFile: file };
 }
 
 /**

package/src/typecheck.js

@@ -289,7 +289,8 @@ export function createChecker({
     `route: { id: string; pattern: string; path: string }; ` +
     `request: Request; fragment: string | null; ` +
     `response: { status: number; headers: Headers }; cookies: __Cookies; ` +
-    `absolute: (path: string) => string; revalidateTag: (tag: string) => void }`;
+    `absolute: (path: string) => string; revalidateTag: (tag: string) => void; ` +
+    `after: (work: Promise<unknown>) => void }`;
 
   const contextLiteral = (params, layoutType) =>
     `{ url: string; params: { ${params.map((name) => `${name}: string`).join('; ')} }; ` +
@@ -297,7 +298,8 @@ export function createChecker({
     `layout: ${layoutType}; request: Request | null; fragment: string | null; ` +
     `action: unknown; response: { status: number; headers: Headers }; ` +
     `cookies: __Cookies; htmlAttrs: Record<string, string | boolean | null>; ` +
-    `absolute: (path: string) => string; revalidateTag: (tag: string) => void }`;
+    `absolute: (path: string) => string; revalidateTag: (tag: string) => void; ` +
+    `after: (work: Promise<unknown>) => void }`;
 
   /**
    * Builds every shim in dependency order: components depend on nothing, a

package/src/worker.js

@@ -5,6 +5,8 @@
 // is WebCrypto and therefore async. Those are runtime facts, so they live here.
 // Which modules to import is an app fact, so that stays in the app's own entry.
 
+import { createApp } from './app.js';
+
 /** base64 in, bytes out. `atob` is in every runtime that has no `Buffer`. */
 const decode = (base64) => Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
 
@@ -85,3 +87,58 @@ export async function hash(body) {
   for (const byte of bytes) base64 += String.fromCharCode(byte);
   return `"${btoa(base64).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '').slice(0, 20)}"`;
 }
+
+/**
+ * The whole worker, for an app that wants the ordinary wiring.
+ *
+ * Nine apps in this repository wrote the same forty lines: parse the manifest,
+ * wrap each byte map, build the app on the first request because that is when
+ * `env` exists, and hand the request on. The imports have to stay in the app's
+ * own file, because a bundler needs a literal path to follow. The wiring does
+ * not, and this is it.
+ *
+ * `cookieSecret` comes from `env.COOKIE_SECRET` when there is one, which is the
+ * only piece of config a worker cannot read at import time. An app needing
+ * something else calls `createApp` itself: this covers the common shape rather
+ * than every shape.
+ *
+ * @param {object} options
+ * @param {object} options.config the app's `transclude.config.js`
+ * @param {string|object} options.manifest `dist/routes.json`, text or parsed
+ * @param {object} options.entry everything `dist/server/entry.js` exports
+ * @param {object} options.bundle everything `dist/server/assets.js` exports
+ * @returns {{ fetch: (request: Request, env: object, ctx: object) => Response|Promise<Response> }}
+ */
+export function workerFrom({ config, manifest, entry, bundle }) {
+  // Built on the first request rather than at import, because that is when
+  // `env` exists. There is no `process.env` here, so a secret read any earlier
+  // is undefined, and signing refuses.
+  let app = null;
+
+  return {
+    fetch(request, env, ctx) {
+      app ??= createApp({
+        config: { ...config, cookieSecret: env.COOKIE_SECRET ?? config.cookieSecret },
+        // There is no JSON module type in Workers, so the manifest usually
+        // arrives as a string. Used as an object it gives a route table of
+        // `undefined` and a site of 404s that looks exactly like a routing bug.
+        manifest: typeof manifest === 'string' ? JSON.parse(manifest) : manifest,
+        pages: entry.pages,
+        endpoints: entry.endpoints,
+        middleware: entry.middleware,
+        statics: bytesFrom(bundle.statics),
+        assets: bytesFrom(bundle.assets),
+        publicFiles: fileHandler(bundle.publicFiles),
+        notFound: pageEntry(bundle.notFound),
+        errorPage: pageEntry(bundle.errorPage),
+        hash,
+        // The edge compresses. Doing it here would be a second pass over bytes
+        // already going through one.
+        compress: null,
+        precache: bundle.precache,
+      });
+
+      return app.fetch(request, env, ctx);
+    },
+  };
+}