@transclude/core 0.12.0 → 0.14.0

package/bin/build.js

@@ -18,7 +18,7 @@ import transclude from '../src/plugin.js';
 import { loadProject } from '../src/project.js';
 import { renderRoute, urlFor } from '../src/document.js';
 import { prerenderContext, refusePrerender } from '../src/prerender.js';
-import { isGated, readGated } from '../src/gate.js';
+import { isGated, readGated, unmatched } from '../src/gate.js';
 import { feed, feedPath } from '../src/feed.js';
 import { includeContext } from '../src/include.js';
 import { nodeLookup } from '../src/lookup.js';
@@ -28,6 +28,7 @@ import { buildSprite, readLibraries, refuseSpriteClash, spritePath } from '../sr
 import { PRECACHE_PATH, precacheDocument, precacheList } from '../src/precache.js';
 import { speculateSettings, speculationRules } from '../src/speculate.js';
 import { pool } from '../src/pool.js';
+import { mappedFrames } from '../src/stack.js';
 import { precompress } from '../src/compress.js';
 
 const { root, config } = await loadProject();
@@ -104,6 +105,10 @@ await build({
   build: {
     outDir: `${config.outDir}/server`,
     emptyOutDir: true,
+    // The map that lets a prerender failure name the .html line. The bundler
+    // composes it from what the plugin's load hook returns, which is why the
+    // virtual ids carry no '\0' prefix: rolldown leaves '\0' modules out.
+    sourcemap: true,
     // `ssr: true` rather than a path: Vite resolves a string entry against the
     // project root before any plugin sees it, which a virtual id cannot survive.
     ssr: true,
@@ -120,6 +125,15 @@ await build({
 const entry = path.join(dist, 'server/entry.js');
 fs.writeFileSync(entry, `// @ts-nocheck\n${fs.readFileSync(entry, 'utf8')}`);
 
+// The banner is one more line the map does not know about, so every position
+// it reports would be off by one, in the direction that names the wrong line
+// with full confidence. One empty group in front keeps every mapping true.
+if (fs.existsSync(`${entry}.map`)) {
+  const shifted = JSON.parse(fs.readFileSync(`${entry}.map`, 'utf8'));
+  shifted.mappings = `;${shifted.mappings}`;
+  fs.writeFileSync(`${entry}.map`, JSON.stringify(shifted));
+}
+
 // ---- prerender ------------------------------------------------------------
 
 const { pages, gated: declared } = await import(pathToFileURL(entry).href);
@@ -170,6 +184,11 @@ manifest.routes = manifest.routes.filter((route) => !isDraft(route));
  * string. A prerendered file is one file for every URL that resolves to it, so
  * `?q=` cannot change it.
  */
+// Every URL `paths()` named, before the gate. The covers-nothing check below
+// asks whether each gated entry could match anything, and a URL a gate held
+// back is exactly a matched one, so the list has to be taken before filtering.
+const namedByPaths = [];
+
 async function urlsFor(route) {
   if (pages[route.id]?.prerender === false) return [];
   if (!route.params.length) {
@@ -180,11 +199,12 @@ async function urlsFor(route) {
   if (typeof paths !== 'function') return [];
 
   const listed = (await paths()) ?? [];
-  return listed
-    .map((params) => ({ url: urlFor(route, params), params }))
-    // Matched per URL, not per route: `/notes/[id]` can be open while
-    // `/notes/secret` is not, and the pattern is the same for both.
-    .filter(({ url }) => !isGated(url, gated));
+  const named = listed.map((params) => ({ url: urlFor(route, params), params }));
+  for (const { url } of named) namedByPaths.push(url);
+
+  // Matched per URL, not per route: `/notes/[id]` can be open while
+  // `/notes/secret` is not, and the pattern is the same for both.
+  return named.filter(({ url }) => !isGated(url, gated));
 }
 
 /**
@@ -237,6 +257,42 @@ for (const route of manifest.routes) {
   for (const target of urls) targets.push({ route, target });
 }
 
+// ---- gated entries that cover nothing ---------------------------------------
+//
+// A typo in `gated` fails open: the entry matches nothing, the page it meant to
+// hold back is written, and the build reports a success. So every entry has to
+// cover something that exists: a page or endpoint pattern, a URL `paths()`
+// named, or a public file, which the gate also guards at runtime.
+{
+  const publicDir = config.publicDir ? path.join(root, config.appDir, config.publicDir) : null;
+  const files = [];
+  const walk = (dir, at) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) walk(path.join(dir, entry.name), `${at}${entry.name}/`);
+      else files.push(`${at}${entry.name}`);
+    }
+  };
+  if (publicDir && fs.existsSync(publicDir)) walk(publicDir, '/');
+
+  const missed = unmatched(gated, {
+    patterns: [
+      ...manifest.routes.map((route) => route.pattern),
+      // A gated draft is a declared intent, not a typo.
+      ...drafts.map((route) => route.pattern),
+      ...manifest.endpoints.map((route) => route.pattern),
+    ],
+    urls: [...namedByPaths, ...files],
+  });
+
+  if (missed.length) {
+    throw new Error(
+      `[transclude] "gated" in app/server.js has ${missed.map((entry) => `"${entry}"`).join(', ')}, ` +
+        `which matches no route, no URL a paths() names, and no public file. ` +
+        `An entry that covers nothing fails open: the page it meant to hold back is written and served.`,
+    );
+  }
+}
+
 if (manifest.notFound) {
   targets.push({
     route: { ...manifest.notFound, pattern: '' },
@@ -313,9 +369,26 @@ if (config.feed) {
 }
 
 if (failures.length) {
+  // Where each failure happened, in the author's file. The bundle's map is
+  // read exactly: a frame on a line the map says nothing about adds no
+  // position, rather than a neighbor's line with full confidence. The first
+  // mapped frame outside the runtime is the author's, because a throw that
+  // starts inside the runtime belongs to whatever line called it.
+  const mapFile = `${entry}.map`;
+  const bundleMap = fs.existsSync(mapFile) ? JSON.parse(fs.readFileSync(mapFile, 'utf8')) : null;
+  const positionOf = (error) => {
+    if (!bundleMap || typeof error?.stack !== 'string') return null;
+    const frames = mappedFrames(error.stack, 'server/entry.js', bundleMap);
+    const frame = frames.find((one) => !one.source.includes('/runtime/'));
+    if (!frame) return null;
+    const file = path.resolve(path.dirname(mapFile), frame.source);
+    return `${path.relative(root, file)}:${frame.line}`;
+  };
+
   console.error(`\n${failures.length} page${failures.length === 1 ? '' : 's'} failed to render:`);
   for (const failure of failures) {
-    console.error(`  ${failure.url}\n    ${failure.error.message}`);
+    const at = positionOf(failure.error);
+    console.error(`  ${failure.url}\n    ${failure.error.message}${at ? `\n    at ${at}` : ''}`);
   }
   process.exitCode = 1;
 }

package/bin/dev.js

@@ -264,17 +264,24 @@ const handleAction = async (route, c) => {
     : sendFragment(route, c, region, extra);
 };
 
-const onError = (c, err) => {
+const onError = (c, err, at = null) => {
   // Before anything reads the stack: Vite's transform means the raw one points
   // at generated code, and a reporter given that is worse than none.
   vite.ssrFixStacktrace(err);
   console.error(err);
 
-  // The same seam production has, so a reporter is exercised while you are the
-  // one looking at it rather than first on a live site.
+  // The same seam production has, with the same shape, so a reporter is
+  // exercised while you are the one looking at it rather than first on a live
+  // site. A field dev left null would read as a production bug later.
   if (typeof config.onError === 'function') {
     try {
-      config.onError(err, { request: c.req.raw, url: c.req.url, method: c.req.method });
+      config.onError(err, {
+        request: c.req.raw,
+        url: c.req.url,
+        method: c.req.method,
+        route: at ? { id: at.route.id, pattern: at.route.pattern, params: c.req.param() } : null,
+        phase: at?.phase ?? null,
+      });
     } catch (failed) {
       console.error('[transclude] onError itself threw:', failed);
     }
@@ -389,7 +396,7 @@ async function buildApp() {
         const fragment = fragmentOf(c);
         return fragment === null ? await renderPage(route, c) : await sendFragment(route, c, fragment);
       } catch (err) {
-        return onError(c, err);
+        return onError(c, err, { route, phase: fragmentOf(c) === null ? 'page' : 'fragment' });
       }
     });
 
@@ -400,7 +407,7 @@ async function buildApp() {
       try {
         return await handleAction(route, c);
       } catch (err) {
-        return onError(c, err);
+        return onError(c, err, { route, phase: 'action' });
       }
     });
   }
@@ -422,7 +429,7 @@ async function buildApp() {
           Allow: endpointMethods(mod).join(', '),
         });
       } catch (err) {
-        return onError(c, err);
+        return onError(c, err, { route, phase: 'endpoint' });
       }
     });
   }
@@ -432,7 +439,7 @@ async function buildApp() {
     try {
       return await renderPage(notFound, c, 404);
     } catch (err) {
-      return onError(c, err);
+      return onError(c, err, { route: notFound, phase: 'page' });
     }
   });
 

package/bin/serve.js

@@ -2,6 +2,7 @@
 // Node adapter. The app is in src/production.js; this listens with it.
 
 import { serve } from '@hono/node-server';
+import { drainOn } from '../src/drain.js';
 import { app, noBuild, port, summary } from '../src/production.js';
 
 if (noBuild) {
@@ -9,4 +10,8 @@ if (noBuild) {
   process.exit(1);
 }
 
-serve({ fetch: app.fetch, port }, ({ port }) => summary(port));
+const server = serve({ fetch: app.fetch, port }, ({ port }) => summary(port));
+
+// A container sends SIGTERM and waits. Node's default is to die on the spot,
+// which cuts a render that was halfway through answering.
+drainOn(server);

package/editor/vscode/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Dakroub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/editor/vscode/README.md

@@ -0,0 +1,30 @@
+# transclude for VS Code
+
+Diagnostics, hovers and syntax highlighting for the `.html` files of a
+[transclude](https://transclude.dev) project.
+
+A page here holds script blocks that are separate modules, which the editor's
+built-in HTML support reads as one. This extension understands the real shape:
+`${…}` is an expression, a directive is an expression, and a misspelled field
+is an error with a line number, the same ones `npm run check` reports.
+
+## How it works
+
+The extension ships no checker. It starts the language server that comes with
+your project's own `@transclude/core`, so the diagnostics match the framework
+version you build with. A workspace without a `transclude.config.js` is left
+alone.
+
+## Settings
+
+- `transclude.enable`: type check `.html` files in a transclude project. On by
+  default.
+
+## Building it yourself
+
+```sh
+cd editor/vscode
+npm install
+npx @vscode/vsce package
+code --install-extension transclude-0.1.0.vsix
+```

package/editor/vscode/extension.js

@@ -1,4 +1,4 @@
-// Starts the language server for workspaces that look like an transclude
+// Starts the language server for workspaces that look like a transclude
 // project. Anything else is left alone. The grammar is harmless everywhere, and
 // the checker only makes sense where transclude.config.js exists.
 
@@ -18,10 +18,13 @@ function activate(context) {
   const root = folder.uri.fsPath;
   if (!fs.existsSync(path.join(root, 'transclude.config.js'))) return;
 
-  // Installed, the server is in the package. In the framework's own repo it is
-  // beside this file. Try both rather than assume a layout.
+  // Installed, the server is in the package, which is @transclude/core: the
+  // unscoped name pointed at a package that does not exist, so the server was
+  // found only inside the framework's own repository. In that repository it is
+  // beside this file. Try both rather than assume a layout, and a test pins the
+  // first path to the name in package.json.
   const server = [
-    path.join(root, 'node_modules/transclude/editor/server.js'),
+    path.join(root, 'node_modules/@transclude/core/editor/server.js'),
     path.join(root, 'editor/server.js'),
   ].find((file) => fs.existsSync(file));
   if (!server) return;

package/editor/vscode/package-lock.json

@@ -0,0 +1,97 @@
+{
+  "name": "transclude",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "transclude",
+      "version": "0.1.0",
+      "license": "MIT",
+      "dependencies": {
+        "vscode-languageclient": "^9.0.1"
+      },
+      "engines": {
+        "vscode": "^1.85.0"
+      }
+    },
+    "node_modules/balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+      "license": "MIT"
+    },
+    "node_modules/brace-expansion": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.4.tgz",
+      "integrity": "sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg==",
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^1.0.0"
+      }
+    },
+    "node_modules/minimatch": {
+      "version": "5.1.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.9.tgz",
+      "integrity": "sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw==",
+      "license": "ISC",
+      "dependencies": {
+        "brace-expansion": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/semver": {
+      "version": "7.8.5",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
+      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/vscode-jsonrpc": {
+      "version": "8.2.0",
+      "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
+      "integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/vscode-languageclient": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/vscode-languageclient/-/vscode-languageclient-9.0.1.tgz",
+      "integrity": "sha512-JZiimVdvimEuHh5olxhxkht09m3JzUGwggb5eRUkzzJhZ2KjCN0nh55VfiED9oez9DyF8/fz1g1iBV3h+0Z2EA==",
+      "license": "MIT",
+      "dependencies": {
+        "minimatch": "^5.1.0",
+        "semver": "^7.3.7",
+        "vscode-languageserver-protocol": "3.17.5"
+      },
+      "engines": {
+        "vscode": "^1.82.0"
+      }
+    },
+    "node_modules/vscode-languageserver-protocol": {
+      "version": "3.17.5",
+      "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz",
+      "integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==",
+      "license": "MIT",
+      "dependencies": {
+        "vscode-jsonrpc": "8.2.0",
+        "vscode-languageserver-types": "3.17.5"
+      }
+    },
+    "node_modules/vscode-languageserver-types": {
+      "version": "3.17.5",
+      "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz",
+      "integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==",
+      "license": "MIT"
+    }
+  }
+}

package/editor/vscode/package.json

@@ -3,18 +3,42 @@
   "displayName": "transclude",
   "description": "Diagnostics, hovers and highlighting for transclude .html files",
   "version": "0.1.0",
+  "publisher": "transclude",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/transclude-dev/transclude.git",
+    "directory": "editor/vscode"
+  },
+  "keywords": [
+    "transclude",
+    "html",
+    "hypermedia",
+    "language-server"
+  ],
   "private": true,
-  "engines": { "vscode": "^1.85.0" },
-  "categories": ["Programming Languages"],
-  "activationEvents": ["onLanguage:html"],
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": [
+    "Programming Languages"
+  ],
+  "activationEvents": [
+    "onLanguage:html"
+  ],
   "main": "./extension.js",
   "contributes": {
     "grammars": [
       {
         "scopeName": "transclude.injection",
         "path": "./syntaxes/transclude.injection.json",
-        "injectTo": ["text.html.basic", "text.html.derivative"],
-        "embeddedLanguages": { "meta.embedded.expression.transclude": "javascript" }
+        "injectTo": [
+          "text.html.basic",
+          "text.html.derivative"
+        ],
+        "embeddedLanguages": {
+          "meta.embedded.expression.transclude": "javascript"
+        }
       }
     ],
     "configuration": {
@@ -28,5 +52,7 @@
       }
     }
   },
-  "dependencies": { "vscode-languageclient": "^9.0.1" }
+  "dependencies": {
+    "vscode-languageclient": "^9.0.1"
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.12.0",
+  "version": "0.14.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/src/app.js

@@ -35,6 +35,11 @@ import { withDefaults } from './defaults.js';
 
 const IMMUTABLE = 'public, max-age=31536000, immutable';
 const REVALIDATE = 'public, max-age=0, must-revalidate';
+// What a personal render says instead. `public` is an explicit grant, and a
+// page that read a cookie is one visitor's. A conforming shared cache would
+// revalidate and miss on the ETag anyway; this is for the CDN whose edge rule
+// skips revalidation and would hand one visitor's page to the next.
+const PERSONAL = 'private, no-cache';
 
 // One per process rather than one per render. It holds no state between calls.
 const encoder = new TextEncoder();
@@ -220,7 +225,7 @@ export function createApp({
       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)),
+      after: afterFor(c, (error) => report(error, c, { route, phase: 'after' })),
       ...extra,
     };
   };
@@ -316,7 +321,7 @@ export function createApp({
         if (html === null) return c.text(`no fragment "${region}"`, 404);
         return sendRendered(c, html, ctx);
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'fragment' });
       }
     });
 
@@ -369,7 +374,7 @@ export function createApp({
         if (html instanceof Response) return withEnvelope(html, ctx);
         return sendRendered(c, html, ctx);
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'action' });
       }
     });
   }
@@ -391,7 +396,7 @@ export function createApp({
           Allow: endpointMethods(mod).join(', '),
         });
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'endpoint' });
       }
     });
   }
@@ -450,7 +455,7 @@ export function createApp({
         // workerd stops the rebuild when this response is sent, and the entry it
         // leaves in the in-flight map answers every later request with a dead
         // promise.
-        const after = afterFor(c, (error) => report(error, c));
+        const after = afterFor(c, (error) => report(error, c, { route, phase: 'revalidate' }));
         const html = await cache.read(cacheKey(c.req.url), window, render, after);
 
         // A miss rendered through the cache, and that render can answer with a
@@ -462,7 +467,7 @@ export function createApp({
         const ctx = last ? last.ctx : contextFor(route, c);
         return sendRendered(c, html, ctx, preload);
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'page' });
       }
     });
   }
@@ -475,19 +480,28 @@ export function createApp({
    * `console.error` is the default and not much of one: a real site sends this
    * to something that can page a person. `onError` is that seam, and it is given
    * the request as well, because an error with no URL and no method is most of
-   * the way to useless.
+   * the way to useless. `route` and `phase` say where: the reader starts at the
+   * loader of `people/[slug]` with `slug: 'ada'` rather than at a URL to
+   * re-derive that from. The phases are page, fragment, action, endpoint,
+   * after and revalidate.
    *
    * It is called inside a `try`. A reporter that throws would otherwise replace
    * the error being reported, which is the one failure mode a reporting hook
    * must not have.
    */
-  function report(err, c) {
+  function report(err, c, at = null) {
     if (typeof config.onError !== 'function') {
       console.error(err);
       return;
     }
     try {
-      config.onError(err, { request: c.req.raw, url: c.req.url, method: c.req.method });
+      config.onError(err, {
+        request: c.req.raw,
+        url: c.req.url,
+        method: c.req.method,
+        route: at ? { id: at.route.id, pattern: at.route.pattern, params: c.req.param() } : null,
+        phase: at?.phase ?? null,
+      });
     } catch (failed) {
       console.error(err);
       console.error('[transclude] onError itself threw:', failed);
@@ -495,8 +509,8 @@ export function createApp({
   }
 
   /** Every `catch` above. One place decides what a failed request looks like. */
-  function internalError(c, err) {
-    report(err, c);
+  function internalError(c, err, at = null) {
+    report(err, c, at);
     // No ETag and no Cache-Control: nothing about a failure should be stored or
     // revalidated, and the same bytes would be sent for an unrelated one next time.
     if (!errorPage) return c.text('Internal error', 500);
@@ -529,7 +543,10 @@ export function createApp({
     const etag = encoding ? `${base.slice(0, -1)}-${encoding}"` : base;
 
     c.header('Vary', varyOn);
-    c.header('Cache-Control', REVALIDATE);
+    // The same test that gates the held-page store. A shareable render is
+    // anyone's; a personal one has to say so, or a cache told `public` would
+    // be within its rights to believe it.
+    c.header('Cache-Control', ctx && !isShareable(html, ctx) ? PERSONAL : REVALIDATE);
     c.header('ETag', etag);
 
     // Whatever the loaders put on `ctx.response`, after the defaults above so a

package/src/compiler/index.js

@@ -400,6 +400,7 @@ const MARK = {
   body: '/*@transclude:body*/',
   head: '/*@transclude:head*/',
   title: '/*@transclude:title*/',
+  server: '/*@transclude:server*/',
 };
 
 /**
@@ -451,10 +452,13 @@ export function compilePage(
   });
   assertIncludesResolve(template.regionIncludes, template.regions);
 
+  const serverAt = serverLines(blocks, server);
+
   const code = `
 ${runtimeImport(runtime)}
 ${componentImports(template.components)}
 ${layoutImports(layouts)}
+${MARK.server}
 ${server.code}
 
 export const css = ${JSON.stringify(blocks.styles.join('\n').trim())};
@@ -500,7 +504,9 @@ ${slotBodies(template)}
 }
 `;
 
-  const mapped = withMap(code, template, source, sourcePath ?? `${filename}.html`);
+  const mapped = withMap(code, template, source, sourcePath ?? `${filename}.html`, [
+    { marker: MARK.server, at: serverAt },
+  ]);
 
   return {
     code: mapped.code,
@@ -510,6 +516,23 @@ ${slotBodies(template)}
   };
 }
 
+/**
+ * The source line behind each line of the compiled loader.
+ *
+ * `bindDefaultExport` rewrites the export in place, so line i of the block's
+ * code is line `blocks.server.line + i` of the file. A page with no loader
+ * maps nothing: the placeholder is the compiler's own line.
+ *
+ * @param {object} blocks what `splitBlocks` returned
+ * @param {{ code: string }} server the bound loader
+ * @returns {number[]} one source line per line of `server.code`
+ */
+function serverLines(blocks, server) {
+  if (!blocks.server) return [];
+  const start = blocks.server.line ?? 1;
+  return server.code.split('\n').map((_, i) => start + i);
+}
+
 /**
  * The module, its markers removed, with a map from its lines to the file's.
  *
@@ -521,10 +544,13 @@ ${slotBodies(template)}
  * @param {object} template what `compileFragment` returned
  * @param {string} source the original `.html`
  * @param {string} filename how it should be named in a stack
+ * @param {Array<{ marker: string, at: (number|null)[] }>} [extra] blocks the
+ *   template does not know about, which today is the loader
  * @returns {{ code: string, map: string|null }}
  */
-function withMap(code, template, source, filename) {
+function withMap(code, template, source, filename, extra = []) {
   const blocks = [
+    ...extra,
     { marker: MARK.body, at: template.at?.body ?? [] },
     { marker: MARK.head, at: template.at?.head ?? [] },
     { marker: MARK.title, at: template.at?.title ?? [] },
@@ -548,10 +574,16 @@ function withMap(code, template, source, filename) {
  *
  * @param {string} source
  * @param {{ id: string, components?: Map<string, string>,
- *   shadowTags?: Set<string>, runtime: string }} options
- * @returns {{ code: string, warnings: string[], components: string[] }}
+ *   shadowTags?: Set<string>, runtime: string,
+ *   sourcePath?: string|null }} options
+ * @returns {{ code: string, map: string|null, warnings: string[],
+ *   components: string[] }} the module, a line-level map or null when there is
+ *   nothing to map, the warnings, and the tags it used
  */
-export function compileLayout(source, { id, components = new Map(), shadowTags = new Set(), runtime }) {
+export function compileLayout(
+  source,
+  { id, components = new Map(), shadowTags = new Set(), runtime, sourcePath = null },
+) {
   const blocks = splitBlocks(source);
   const where = `${id}/_layout.html <script server>`;
   const headWhere = `${id}/_layout.html <script head>`;
@@ -577,9 +609,12 @@ export function compileLayout(source, { id, components = new Map(), shadowTags =
     warnings.push('no <slot>, so nothing rendered inside this layout would appear');
   }
 
+  const serverAt = serverLines(blocks, server);
+
   const code = `
 ${runtimeImport(runtime)}
 ${componentImports(template.components)}
+${MARK.server}
 ${server.code}
 
 export const css = ${JSON.stringify(blocks.styles.join('\n').trim())};
@@ -594,6 +629,7 @@ export async function load(ctx) {
 
 export function renderTitle(__d) {
   let __o = '';
+${MARK.title}
 ${indent(template.title)}
   return __o;
 }
@@ -608,6 +644,7 @@ export function renderBodyAttrs(__d) {
 
 export function renderHead(__d) {
   let __o = '';
+${MARK.head}
 ${indent(template.head)}
   return __o;
 }
@@ -621,7 +658,11 @@ ${slotBodies(template)}
 export default { css, headScript, elements, hasTitle, load, renderTitle, renderHead, renderHtmlAttrs, renderBodyAttrs, render };
 `;
 
-  return { code, warnings, components: template.components.map((c) => c.tag) };
+  const mapped = withMap(code, template, source, sourcePath ?? `${id}/_layout.html`, [
+    { marker: MARK.server, at: serverAt },
+  ]);
+
+  return { code: mapped.code, map: mapped.map, warnings, components: template.components.map((c) => c.tag) };
 }
 
 /**

package/src/cookies.js

@@ -45,7 +45,9 @@ export function cookiesOf(request, response, secret = null) {
     // `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.
+    // hunting through the wiring instead of the value. `withDefaults` refuses
+    // the empty string at boot now; this stays for a `cookiesOf` reached
+    // without it.
     if (typeof secret === 'string') {
       throw new Error(
         `[transclude] ${what} needs a secret, and \`cookieSecret\` is set to an ` +
@@ -168,5 +170,18 @@ function overTls(request) {
  * turns the whole thing off. Set it yourself to override either way.
  */
 function withDefaults(options, request) {
-  return { path: '/', httpOnly: true, sameSite: 'Lax', secure: overTls(request), ...options };
+  const merged = { path: '/', httpOnly: true, sameSite: 'Lax', secure: overTls(request), ...options };
+
+  // Every browser drops this pair, silently, so writing it is never right.
+  // `None` is for a cookie sent cross-site, and those are Secure-only
+  // everywhere. Refused here rather than left to the browser, because a cookie
+  // that never arrives reads exactly like a bug somewhere else.
+  if (String(merged.sameSite).toLowerCase() === 'none' && !merged.secure) {
+    throw new Error(
+      `[transclude] a cookie with \`sameSite: 'None'\` needs \`secure: true\`. Every ` +
+        `browser drops the pair without it, silently. Set both, or use 'Lax'.`,
+    );
+  }
+
+  return merged;
 }

package/src/defaults.js

@@ -97,6 +97,19 @@ export function withDefaults(config = {}) {
 
   const merged = { ...DEFAULTS, ...config };
 
+  // Set but empty is refused at boot rather than at the first signed cookie,
+  // because that first read happens in production, at request time, days after
+  // the deploy that broke it. It happened: `wrangler secret put` took a blank
+  // line, so the binding existed and carried nothing. `null` stays fine, since
+  // that is how an app says it signs nothing.
+  if (merged.cookieSecret === '') {
+    throw new Error(
+      `[transclude] \`cookieSecret\` is an empty string. Whatever supplies it handed ` +
+        `over nothing: on a worker that is usually a \`wrangler secret put\` that took ` +
+        `a blank line. Set a real secret, or \`null\` for none.`,
+    );
+  }
+
   // Refused here because there are four places that render a page and only two of
   // them could fall back to a request's origin. Left to the render, `canonical`
   // would work in dev and throw in the build, which is the dev-and-production

package/src/drain.js

@@ -0,0 +1,63 @@
+// Finishing what is in flight when the platform says stop.
+//
+// A container sends SIGTERM and waits a moment before SIGKILL. Node's default
+// for SIGTERM is to die on the spot, so a render halfway through its loader
+// answers nobody, and an action may have happened with its response cut on the
+// wire. Draining instead refuses new connections, finishes what is running,
+// and leaves.
+//
+// No imports. `process` and the timers are globals, and the server arrives as
+// an argument.
+
+/**
+ * Exit cleanly on a stop signal, once the work in flight is done.
+ *
+ * `close` stops the listener and waits for every open connection. A keep-alive
+ * connection counts as open with no request on it, so idle ones are swept
+ * while the close waits; without the sweep, the first browser that ever
+ * connected would hold the wait to the cap. The cap is for a render that
+ * hangs: past it, every connection is cut and the exit code says the drain was
+ * not clean. Both timers are unref'd, so neither keeps a finished process
+ * alive.
+ *
+ * @param {object} server what `serve` returned: a `node:http` server
+ * @param {{ signals?: string[], grace?: number, sweep?: number, exit?: Function }} [options]
+ * @returns {() => void} the drain itself, so a test can run one without a signal
+ */
+export function drainOn(server, options = {}) {
+  const {
+    signals = ['SIGTERM', 'SIGINT'],
+    grace = 10_000,
+    sweep = 500,
+    exit = (code) => process.exit(code),
+  } = options;
+
+  // The cap and the close both want to be the exit. First one wins.
+  let left = false;
+  const leave = (code) => {
+    if (left) return;
+    left = true;
+    exit(code);
+  };
+
+  const drain = () => {
+    const idle = setInterval(() => server.closeIdleConnections?.(), sweep);
+    idle.unref?.();
+
+    const cap = setTimeout(() => {
+      server.closeAllConnections?.();
+      leave(1);
+    }, grace);
+    cap.unref?.();
+
+    server.close(() => {
+      clearInterval(idle);
+      clearTimeout(cap);
+      leave(0);
+    });
+    server.closeIdleConnections?.();
+  };
+
+  for (const signal of signals) process.once(signal, drain);
+  return drain;
+}

package/src/gate.js

@@ -36,12 +36,69 @@ export function isGated(url, patterns = []) {
   });
 }
 
+/**
+ * Whether an entry could gate some URL of a route.
+ *
+ * A pattern is Hono's spelling: `/notes/:id` takes one segment, and a brace
+ * parameter like `/docs/:path{.+}` can take the rest of the path. This asks
+ * about possibility, not fact: `/notes/secret` covers `/notes/:id` whether or
+ * not `paths()` ever names it, and a brace parameter is taken to match
+ * anything, so an unsure answer errs toward covered rather than refused.
+ *
+ * @param {string} entry one gated path
+ * @param {string} pattern a route pattern
+ * @returns {boolean}
+ */
+export function coversPattern(entry, pattern) {
+  const rest = entry.endsWith('/*');
+  const entrySegs = (rest ? entry.slice(0, -2) : entry).split('/').slice(1);
+  const patternSegs = pattern.split('/').slice(1);
+
+  for (let i = 0; i < patternSegs.length; i++) {
+    // The entry ran out. `/api/*` still covers whatever follows; `/api` does not.
+    if (i >= entrySegs.length) return rest;
+
+    const seg = patternSegs[i];
+    if (seg.startsWith(':')) {
+      if (seg.includes('{')) return true;
+      continue;
+    }
+    if (seg !== entrySegs[i]) return false;
+  }
+
+  // The pattern ran out. An entry asking for more segments than the route's
+  // URLs have covers none of them.
+  return rest || entrySegs.length === patternSegs.length;
+}
+
+/**
+ * The gated entries that cover nothing.
+ *
+ * A typo in `gated` fails open: the entry matches nothing, the page it meant to
+ * hold back is written, and the build reports a success. So the build asks
+ * whether each entry could ever match, and refuses the ones that could not.
+ *
+ * @param {string[]} gated
+ * @param {{ patterns?: string[], urls?: string[] }} site every route pattern,
+ *   and every concrete URL the build knows: what `paths()` named, and the
+ *   public files, which the gate also guards at runtime
+ * @returns {string[]} the entries with nothing to cover
+ */
+export function unmatched(gated, { patterns = [], urls = [] }) {
+  return gated.filter(
+    (entry) =>
+      !patterns.some((pattern) => coversPattern(entry, pattern)) &&
+      !urls.some((url) => isGated(url, [entry])),
+  );
+}
+
 /**
  * The declaration, or a refusal naming what is wrong with it.
  *
- * Checked rather than trusted, because every mistake here fails open. A typo
- * matches nothing, the page is written, and the build says it prerendered a page
- * that was supposed to need paying for.
+ * Checked rather than trusted, because a mistake here fails open: the page is
+ * written, and the build says it prerendered a page that was supposed to need
+ * paying for. This refuses the wrong shape. `unmatched` catches the typo that
+ * is still a path.
  *
  * @param {unknown} gated whatever `app/server.js` exported
  * @returns {string[]}

package/src/plugin.js

@@ -241,18 +241,24 @@ export default function transclude({
 
     resolveId(id, importer) {
       if (duplicate) return null;
-      if (id === SERVER_ENTRY || id === ELEMENTS_ENTRY) return '\0' + id;
+      // No '\0' prefix, on purpose. The convention marks a virtual id, and
+      // rolldown leaves '\0' modules out of the map it composes for a bundle,
+      // so `dist/server/entry.js.map` listed no page at all and a prerender
+      // failure could name no .html. Measured on Vite 8.2.1: with the prefix,
+      // no page is a source; without it, every page is. Resolution still ends
+      // here, because this hook answers for these ids before anything else.
+      if (id === SERVER_ENTRY || id === ELEMENTS_ENTRY) return id;
       if (
         id.startsWith(P_COMPONENT) ||
         id.startsWith(P_PAGE) ||
         id.startsWith(P_CLIENT) ||
         id.startsWith(P_LAYOUT)
       ) {
-        return '\0' + id;
+        return id;
       }
       // A virtual module has no directory, so Vite cannot resolve `../data/x.js`
       // on its own. The block was authored in a real file; use that file's dir.
-      if (importer?.startsWith('\0virtual:transclude-') && /^\.\.?\//.test(id)) {
+      if (importer?.startsWith('virtual:transclude-') && /^\.\.?\//.test(id)) {
         const source = origin.get(importer);
         if (source) return path.resolve(path.dirname(source), id);
       }
@@ -261,8 +267,8 @@ export default function transclude({
 
     load(id) {
       if (duplicate) return null;
-      if (!id.startsWith('\0virtual:transclude-')) return null;
-      const virt = id.slice(1);
+      if (!id.startsWith('virtual:transclude-')) return null;
+      const virt = id;
 
       // Every element in the app, not only the ones some page renders: a
       // fragment can name any of them, and which one it names is a runtime fact.
@@ -335,9 +341,16 @@ export const gated = ${hasMiddleware ? '__server.gated ?? []' : '[]'};
         const file = layouts.get(layoutId);
         if (!file) throw new Error(`[transclude] no layout "${layoutId}"`);
         origin.set(id, file);
-        const out = compileLayout(read(file), { id: layoutId, components, shadowTags, runtime });
+        // `sourcePath` absolute for the same reason as the page's below.
+        const out = compileLayout(read(file), {
+          id: layoutId,
+          components,
+          shadowTags,
+          runtime,
+          sourcePath: file,
+        });
         report(`${layoutId} layout`, out.warnings);
-        return out.code;
+        return out.map ? { code: out.code, map: out.map } : out.code;
       }
 
       if (virt.startsWith(P_PAGE)) {
@@ -387,7 +400,7 @@ export const gated = ${hasMiddleware ? '__server.gated ?? []' : '[]'};
 
         scan();
         for (const mod of server.moduleGraph.idToModuleMap.values()) {
-          if (mod.id?.startsWith('\0virtual:transclude-')) server.moduleGraph.invalidateModule(mod);
+          if (mod.id?.startsWith('virtual:transclude-')) server.moduleGraph.invalidateModule(mod);
         }
         const hot = server.hot ?? server.ws;
         hot?.send({ type: 'full-reload' });
@@ -401,11 +414,15 @@ export const gated = ${hasMiddleware ? '__server.gated ?? []' : '[]'};
 /**
  * Browser URL for a virtual module id.
  *
+ * No `__x00__`, because the ids carry no '\0' prefix. That encoding is Vite's
+ * spelling of the prefix in a URL, and with it here the browser asked for a
+ * module the graph no longer holds, on every page that ships JS, in dev only.
+ *
  * @param {string} page the route id
  * @returns {string} the URL Vite serves its entry from
  */
 export function clientEntryUrl(page) {
-  return `/@id/__x00__${P_CLIENT}${page}`;
+  return `/@id/${P_CLIENT}${page}`;
 }
 
 /**

package/src/proxy.js

@@ -33,13 +33,26 @@ const DEFAULTS = {
 
 const STYLE_MODES = new Set(['keep', 'strip']);
 
+/** Every key `proxy` may set. `lookup` has no default: absent means the runtime's. */
+const KEYS = new Set([...Object.keys(DEFAULTS), 'lookup']);
+
 /**
- * Defaults filled in, and the one value worth checking checked. A misspelled
- * `styles` would keep every style attribute and say nothing, which reads exactly
- * like the setting working.
+ * Defaults filled in, and what the author wrote checked. A misspelled `maxage`
+ * would fall back to the default and say nothing, which reads exactly like the
+ * setting working. That is the failure the config's own keys refuse by name,
+ * one level up, and these keys get the same treatment.
  */
 function settings(options) {
   const config = { ...DEFAULTS, ...options };
+
+  const unknown = Object.keys(options ?? {}).filter((key) => !KEYS.has(key));
+  if (unknown.length) {
+    throw new Error(
+      `[transclude] \`proxy\` sets ${unknown.join(', ')}, which nothing reads. ` +
+        `The keys are ${[...KEYS].sort().join(', ')}.`,
+    );
+  }
+
   if (!STYLE_MODES.has(config.styles)) {
     throw new Error(
       `[transclude] proxy.styles is ${JSON.stringify(config.styles)}. It is 'keep' or 'strip'.`,
@@ -289,10 +302,12 @@ export function proxyHandler(options = {}, deps = {}) {
     try {
       const entry = await readForeign(url, config, { ...deps, store });
 
-      // No id is a question about the document rather than a piece of it.
+      // No id is a question about the document rather than a piece of it, so
+      // the answer also says what the cleaning took out. The list was already
+      // kept for exactly this; nothing read it until here.
       if (!id) {
         const { listFragments } = await import('./extract.js');
-        return json(200, { url, fragments: listFragments(entry.doc) });
+        return json(200, { url, fragments: listFragments(entry.doc), removed: entry.removed });
       }
 
       const found = resolveFragment(entry.doc, id);

package/src/rewrite.js

@@ -81,15 +81,15 @@ export function sanitize(root, { styles = 'keep' } = {}) {
           removed.push('@style');
           return false;
         }
-        return true;
-      });
-
-      for (const attr of child.attrs) {
+        // Removed rather than emptied. An empty value still means something:
+        // `href=""` names the page the fragment lands in, and `action=""`
+        // submits to it, neither of which the source wrote.
         if (!allowedUrl(child, attr)) {
           removed.push(`@${attr.name}`);
-          attr.value = '';
+          return false;
         }
-      }
+        return true;
+      });
 
       visit(child);
     }
@@ -100,7 +100,7 @@ export function sanitize(root, { styles = 'keep' } = {}) {
 }
 
 /**
- * Whether a URL-bearing attribute may keep its value.
+ * Whether a URL-bearing attribute may stay.
  *
  * `javascript:` is refused everywhere. `data:` is refused everywhere except an
  * image source, where it is ordinary and cannot navigate anything.

package/src/stack.js

@@ -0,0 +1,106 @@
+// The author's position behind a frame in a bundled stack.
+//
+// Node can rewrite stacks itself, but its consumer takes the nearest earlier
+// mapping when a position has none, and in a bundle the nearest mapping can
+// belong to a different file. That answer arrives with full confidence: a
+// throw in colophon.html was once reported as app/lib/code.js:81. So the map
+// is read exactly here. A frame on a generated line the map says nothing
+// about names no file, rather than the neighbor's.
+//
+// Pure. No `node:` imports: the caller reads the files, this reads the strings.
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/**
+ * The numbers in one VLQ segment, the reverse of what the compiler writes.
+ *
+ * @param {string} segment
+ * @returns {number[]}
+ */
+function unvlq(segment) {
+  const values = [];
+  let shift = 0;
+  let value = 0;
+
+  for (const ch of segment) {
+    const digit = ALPHABET.indexOf(ch);
+    value += (digit & 31) << shift;
+    if (digit & 32) {
+      shift += 5;
+      continue;
+    }
+    values.push(value & 1 ? -(value >>> 1) : value >>> 1);
+    shift = 0;
+    value = 0;
+  }
+
+  return values;
+}
+
+/**
+ * The frames of a stack that sit in one bundle, mapped to their sources.
+ *
+ * Only a frame whose generated line carries a mapping is returned. The source
+ * index and line are running totals across the whole `mappings` string, so
+ * every line is walked once, in order, whichever lines the stack asks about.
+ *
+ * @param {string} stack whatever `error.stack` holds
+ * @param {string} bundle how the bundle is named in a frame, like `server/entry.js`
+ * @param {{ sources: string[], mappings: string }} map the bundle's source map
+ * @returns {Array<{ source: string, line: number }>} outermost frame first
+ */
+export function mappedFrames(stack, bundle, map) {
+  /** The bundle position a stack line names, or null. */
+  const positionOf = (line) => {
+    const at = line.indexOf(bundle);
+    if (at === -1) return null;
+    const found = line.slice(at + bundle.length).match(/^:(\d+):(\d+)/);
+    if (!found) return null;
+    return { line: Number(found[1]), column: Number(found[2]) };
+  };
+
+  const positions = stack.split('\n').map(positionOf).filter(Boolean);
+  if (!positions.length) return [];
+  const asked = new Set(positions.map((position) => position.line));
+
+  // One pass over the mappings, keeping only the lines the stack named. The
+  // source index and line are running totals across the whole string, so every
+  // line is walked whichever ones are kept.
+  const lines = map.mappings.split(';');
+  const kept = new Map();
+  let sourceIndex = 0;
+  let sourceLine = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const decoded = [];
+    let column = 0;
+
+    for (const segment of lines[i] ? lines[i].split(',') : []) {
+      const fields = unvlq(segment);
+      column += fields[0];
+      if (fields.length < 4) continue;
+      sourceIndex += fields[1];
+      sourceLine += fields[2];
+      decoded.push({ column, source: map.sources[sourceIndex], line: sourceLine + 1 });
+    }
+
+    if (decoded.length && asked.has(i + 1)) kept.set(i + 1, decoded);
+  }
+
+  const frames = [];
+  for (const position of positions) {
+    const decoded = kept.get(position.line);
+    if (!decoded) continue;
+
+    // The nearest mapping at or before the column. Within one generated line
+    // every mapping is the same module's, so this cannot name a neighbor. A
+    // stack column is 1-based and a map column is not.
+    let hit = null;
+    for (const segment of decoded) {
+      if (segment.column <= position.column - 1) hit = segment;
+    }
+    if (hit) frames.push({ source: hit.source, line: hit.line });
+  }
+
+  return frames;
+}

package/src/typecheck.js

@@ -303,7 +303,7 @@ export function createChecker({
     `route: { id: string; pattern: string; path: string }; ` +
     `layout: ${layoutType}; request: Request | null; fragment: string | null; ` +
     `action: unknown; response: { status: number; headers: Headers }; ` +
-    `cookies: __Cookies; htmlAttrs: Record<string, string | boolean | null>; ` +
+    `cookies: __Cookies; ` +
     `absolute: (path: string) => string; revalidateTag: (tag: string) => void; ` +
     `after: (work: Promise<unknown>) => void }`;