@transclude/core 0.11.3 → 0.13.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));
 }
 
 /**
@@ -207,6 +227,7 @@ async function render(route, { url, params }) {
     stylesheet,
     csp: config.csp,
     lang: config.lang,
+    canonical: config.canonical,
     speculate: speculateRules,
     include,
   });
@@ -236,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: '' },
@@ -312,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

@@ -191,6 +191,7 @@ const renderPage = async (route, c, status = null, extra = {}) => {
     stylesheet: config.stylesheet ? `/${config.stylesheet}` : null,
     csp: config.csp,
     lang: config.lang,
+    canonical: config.canonical,
     include,
   });
   // A loader answered for itself: a redirect, or something that is not a page.

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.11.3",
+  "version": "0.13.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

@@ -358,6 +358,7 @@ export function createApp({
                 stylesheet: manifest.stylesheet,
                 csp: config.csp,
                 lang: config.lang,
+                canonical: config.canonical,
                 // Written by the build and carried here, so a server-rendered
                 // page says the same thing about speculation that a file does.
                 speculate: manifest.speculate ?? null,
@@ -429,6 +430,7 @@ export function createApp({
             stylesheet: manifest.stylesheet,
             csp: config.csp,
             lang: config.lang,
+            canonical: config.canonical,
             speculate: manifest.speculate ?? null,
             include,
           });

package/src/compiler/bind.js

@@ -69,6 +69,7 @@ class Bindgen {
     components = new Map(),
     shadowTags = new Set(),
     blockOf = new Map(),
+    anchoredOf = new Set(),
     refs = new Map(),
   } = {}) {
     this.components = components;
@@ -76,6 +77,10 @@ class Bindgen {
     // Which tree node owns which compiled block. Sharing the map is what keeps
     // this pass and the renderer from drifting apart over the same tree.
     this.blockOf = blockOf;
+    // The blocks the renderer fenced in anchors, which is more of them than it
+    // compiled. Shared for the same reason, and read for one question: is this a
+    // block the walk can step over.
+    this.anchoredOf = anchoredOf;
     // tag -> the local name the renderer imported that component under.
     this.refs = refs;
     this.frames = [new Frame(new Scope())];
@@ -165,6 +170,11 @@ class Bindgen {
     }
   }
 
+  /** A `<slot>` the renderer fenced, which is a light element's and never a shadow one's. */
+  isHole(node) {
+    return node.tagName === 'slot' && this.anchoredOf.has(node);
+  }
+
   abandon(slot) {
     if (slot.kind === 'text') {
       for (const node of slot.nodes) this.giveUpText(node.value);
@@ -208,14 +218,36 @@ class Bindgen {
       if (slot.kind === 'block') {
         const ref = this.bindBlock(slot, here);
         if (ref === null) {
-          for (const rest of rendered.slice(i)) this.abandon(rest);
-          this.frame.gaveUp = true;
-          return;
+          // A light element's block: rendered once and never rebuilt. What it
+          // read is volatile and its nodes are nothing to hold, but its anchors
+          // are in the markup, so the walk goes on past it. A block without them
+          // has no past it, and nothing after it binds.
+          if (!this.anchoredOf.has(slot.nodes[0])) {
+            for (const rest of rendered.slice(i)) this.abandon(rest);
+            this.frame.gaveUp = true;
+            return;
+          }
+          this.abandon(slot);
         }
         // Past a block the node count is not knowable, so addressing becomes
         // relative from here on.
         cursor = cursor ?? this.cursor();
-        this.locate(`${cursor} = __b[${ref}].end.nextSibling;`);
+        const past = ref === null ? `__afterBlock(${here})` : `__b[${ref}].end.nextSibling`;
+        this.locate(`${cursor} = ${past};`);
+        continue;
+      }
+
+      // A light element's `<slot>` is a compile-time hole holding the caller's
+      // markup, which is fenced for the same reason a block is. Nothing in it is
+      // ours to write, and the walk steps over it to reach what follows.
+      //
+      // The tag is asked for, not just the set: a branch arrives at its own part
+      // bare, with its directive already consumed, so a block's node reaches here
+      // as an ordinary element and is in the set too.
+      if (slot.kind === 'element' && this.isHole(slot.nodes[0])) {
+        this.abandon(slot);
+        cursor = cursor ?? this.cursor();
+        this.locate(`${cursor} = __afterBlock(${here});`);
         continue;
       }
 

package/src/compiler/codegen.js

@@ -98,6 +98,7 @@ export function compileFragment(nodes, opts = {}) {
     at,
     blockDefs: gen.blockDefs.join('\n'),
     blockOf: gen.blockOf,
+    anchoredOf: gen.anchoredOf,
     slots: Object.fromEntries(slots.map(([name, out]) => [name, out.code])),
     regions: Object.fromEntries(regions.map(([name, out]) => [name, out.code])),
     regionIncludes: gen.regionIncludes,
@@ -129,13 +130,16 @@ class Codegen {
     // `blocks` on, an `if` or `each` compiles to its own module-scope function,
     // and a `__fragment` passed from render would not be in scope inside it.
     this.fragments = fragments;
-    // With `blocks` on, `if` and `each` at the top level compile to their own
-    // function and are wrapped in comment anchors, so an update can re-render
-    // one region instead of the whole shadow root. Only an element is ever
-    // updated, so nothing else pays for the anchors.
-    this.blocks = blocks && !layout;
+    // With `blocks` on, every `if` and `each` is wrapped in comment anchors, so
+    // whatever binds this markup can find where one ends. Only an element is ever
+    // updated, so nothing else pays for them.
+    this.blocks = blocks;
     this.blockDefs = [];
     this.blockOf = new Map();
+    // Every block that got anchors, whether or not it also got a function. The
+    // binding pass reads it the way it reads `blockOf`: to know that a block it
+    // cannot bind is still one it can step over.
+    this.anchoredOf = new Set();
     this.inBlock = 0;
     // The loop variables in scope, outermost first, two per level. A block
     // inside a loop renders from them, so its function has to take them.
@@ -360,14 +364,25 @@ class Codegen {
   }
 
   /**
-   * True where a structural block is addressable on its own. Anchors nest and
-   * the runtime counts depth, and a block inside a loop takes that loop's
-   * variables as arguments, so nesting is not a reason to give up on either.
+   * True where a block is wrapped in anchors, which is where anything binds this
+   * markup at all. Anchors nest and the runtime counts depth, so nesting is not a
+   * reason to give up.
    */
-  standalone() {
+  anchored() {
     return this.blocks && this.inHead === 0;
   }
 
+  /**
+   * True where a block also compiles to a function of its own, which is what
+   * re-rendering one region rather than the whole root needs. Not in a layout,
+   * and a light element is compiled as one: `<slot>` there is a compile-time hole
+   * reading `__slots`, a parameter of `render` that a module-scope block function
+   * would not have. A light element rebuilds nothing anyway.
+   */
+  standalone() {
+    return this.anchored() && !this.layout;
+  }
+
   /** Flat list of the loop variables in scope, outermost first. */
   loopArgs() {
     return this.loops.flatMap((loop) => [loop.item, loop.index]);
@@ -382,6 +397,7 @@ class Codegen {
     const id = this.blockDefs.length;
     const params = ['__d', ...args].join(', ');
     this.blockOf.set(node, id);
+    this.anchoredOf.add(node);
     this.blockDefs.push(
       `const __blk${id} = { ${extra}html: (${params}) => { let __o = '';\n${joinOut(body).code}\nreturn __o; } };`,
     );
@@ -400,7 +416,16 @@ class Codegen {
       this.emitBlock(chain[0].node, out, body, '', args);
       return;
     }
+    // Emitted where it stands, and still fenced. The markup is rendered once and
+    // nothing will replace it, but the anchors are how a walk gets to the nodes
+    // after it: what a branch renders is only known once the data is.
+    const fenced = this.anchored();
+    if (fenced) {
+      this.anchoredOf.add(chain[0].node);
+      this.s(out, ANCHOR_OPEN);
+    }
     this.emitBranches(chain, out, scope, topLevel);
+    if (fenced) this.s(out, ANCHOR_CLOSE);
   }
 
   emitBranches(chain, out, scope, topLevel) {
@@ -537,6 +562,7 @@ class Codegen {
       const id = this.blockDefs.length;
       this.blockDefs.push('');
       this.blockOf.set(el, id);
+      this.anchoredOf.add(el);
 
       // A <template each> renders several nodes per item, so an item is a
       // region rather than a node and needs anchors of its own to be found.
@@ -562,7 +588,15 @@ class Codegen {
       return;
     }
 
+    // The same fence an inline `if` gets, and for the same reason: how many nodes
+    // the loop produces is a question only the data answers.
+    const fenced = this.anchored();
+    if (fenced) {
+      this.anchoredOf.add(el);
+      this.s(out, ANCHOR_OPEN);
+    }
     this.emitEachBody(el, out, scope, topLevel);
+    if (fenced) this.s(out, ANCHOR_CLOSE);
   }
 
   /** `list`, `key` and `item`. One loop, taken apart so it can be reconciled. */
@@ -653,13 +687,24 @@ class Codegen {
       const filled = `__slots[${JSON.stringify(name)}]`;
       const fallback = childrenOf(el);
 
-      if (!fallback.length) {
+      // The caller's markup, and how many nodes it is only this render knows. So
+      // it is fenced like a block, and for the same reason: nothing that binds
+      // this markup afterwards can count its way past it.
+      const fenced = this.anchored();
+      if (fenced) {
+        this.anchoredOf.add(el);
+        this.s(out, ANCHOR_OPEN);
+      }
+
+      if (fallback.length) {
+        this.c(out, `if (${filled}) { __o += ${filled}; } else {`);
+        this.emitChildren(fallback, out, scope);
+        this.c(out, `}`);
+      } else {
         this.c(out, `__o += ${filled} ?? '';`);
-        return;
       }
-      this.c(out, `if (${filled}) { __o += ${filled}; } else {`);
-      this.emitChildren(fallback, out, scope);
-      this.c(out, `}`);
+
+      if (fenced) this.s(out, ANCHOR_CLOSE);
       return;
     }
 

package/src/compiler/index.js

@@ -279,6 +279,7 @@ export function compileComponent(
         components,
         shadowTags,
         blockOf: template.blockOf,
+        anchoredOf: template.anchoredOf,
         refs: new Map(template.components.map(({ tag: name, ref }) => [name, ref])),
         // The runtime prepends <style> to the shadow root, so a component's own
         // first node is not at index 0. A light element's styles are hoisted
@@ -399,6 +400,7 @@ const MARK = {
   body: '/*@transclude:body*/',
   head: '/*@transclude:head*/',
   title: '/*@transclude:title*/',
+  server: '/*@transclude:server*/',
 };
 
 /**
@@ -450,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())};
@@ -499,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,
@@ -509,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.
  *
@@ -520,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 ?? [] },
@@ -547,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>`;
@@ -576,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())};
@@ -593,6 +629,7 @@ export async function load(ctx) {
 
 export function renderTitle(__d) {
   let __o = '';
+${MARK.title}
 ${indent(template.title)}
   return __o;
 }
@@ -607,6 +644,7 @@ export function renderBodyAttrs(__d) {
 
 export function renderHead(__d) {
   let __o = '';
+${MARK.head}
 ${indent(template.head)}
   return __o;
 }
@@ -620,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) };
 }
 
 /**
@@ -851,7 +893,7 @@ function unusedProps(defaultNode, reads, blocks) {
 // ---- module assembly helpers ---------------------------------------------
 
 function runtimeImport(runtime) {
-  return `import { escape as __e, attr as __a, attrProp as __ap, str as __str, json, shadow as __sh, data as __data, included as __incl, textAt as __textAt, setText as __setText, setParts as __setParts, setAttr as __setAttr, setAttrProp as __setAttrProp, blockAt as __blockAt, updateBlock as __updateBlock, coerceProps, defineComponent, defineLight, html } from ${JSON.stringify(runtime)};`;
+  return `import { escape as __e, attr as __a, attrProp as __ap, str as __str, json, shadow as __sh, data as __data, included as __incl, textAt as __textAt, setText as __setText, setParts as __setParts, setAttr as __setAttr, setAttrProp as __setAttrProp, blockAt as __blockAt, afterBlock as __afterBlock, updateBlock as __updateBlock, coerceProps, defineComponent, defineLight, html } from ${JSON.stringify(runtime)};`;
 }
 
 function layoutImports(layouts) {

package/src/defaults.js

@@ -34,6 +34,11 @@ export const DEFAULTS = {
   csrf: true,
   csp: false,
   speculate: false,
+  // `<link rel="canonical">` on every page, pointing at the page's own URL. Off
+  // by default because a page mounted at a second URL on purpose would get a
+  // wrong one, and a wrong canonical is worse than none: it hands the ranking to
+  // the other URL.
+  canonical: false,
   // `(source, file) => html`, and a `.md` page under `routes/` without one is an
   // error naming the file. This package ships no Markdown parser: which flavor
   // and which extensions are the app's to pick, the same way `cache` is a store
@@ -41,6 +46,31 @@ export const DEFAULTS = {
   markdown: null,
 };
 
+/**
+ * Keys a config may set that have no default, listed so the check below does not
+ * read them as typos.
+ *
+ * A key is here when leaving it out has to mean something other than a value.
+ * There is no feed to write down as the default feed, and no store to write down
+ * as the default `cache`: absent is how an app says it wants neither.
+ */
+const UNDEFAULTED = [
+  'cache',
+  'cookieSecret',
+  'feed',
+  'fragmentHeader',
+  'metadataBase',
+  'onError',
+  'port',
+  'precache',
+  'proxy',
+  'sitemap',
+  'watchElements',
+];
+
+/** Every key `transclude.config.js` may set. */
+export const KEYS = new Set([...Object.keys(DEFAULTS), ...UNDEFAULTED]);
+
 /**
  * A config with every default filled in.
  *
@@ -50,7 +80,34 @@ export const DEFAULTS = {
  *
  * @param {object} [config] whatever `transclude.config.js` exported
  * @returns {object} the same keys, plus the ones it did not mention
+ * @throws when `canonical` is on and there is no origin to build a URL from
  */
 export function withDefaults(config = {}) {
-  return { ...DEFAULTS, ...config };
+  // A key nothing reads is a line the author believes is doing something. The
+  // failure it replaces is silent and expensive: `stylesheeet` cost a site its
+  // whole stylesheet and said nothing, because an ignored key looks exactly like
+  // a key that worked.
+  const unknown = Object.keys(config).filter((key) => !KEYS.has(key));
+  if (unknown.length) {
+    throw new Error(
+      `[transclude] transclude.config.js sets ${unknown.join(', ')}, which nothing reads. ` +
+        `The keys are ${[...KEYS].sort().join(', ')}.`,
+    );
+  }
+
+  const merged = { ...DEFAULTS, ...config };
+
+  // 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
+  // disagreement this file exists to stop.
+  if (merged.canonical && !merged.metadataBase) {
+    throw new Error(
+      `[transclude] \`canonical: true\` needs \`metadataBase\`, which is the origin the ` +
+        `URL is built from. A request's own origin is the wrong one twice: behind a proxy ` +
+        `it is the internal address, and a prerendered page has no request at all.`,
+    );
+  }
+
+  return merged;
 }

package/src/document.js

@@ -177,6 +177,23 @@ const ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
 
 const escapeAttr = (value) => String(value).replace(/[&<>"]/g, (c) => ESCAPES[c]);
 
+/**
+ * The head the framework writes, as the outermost level of the merge.
+ *
+ * Through `mergeHead` rather than beside it, so a page or a layout writing its
+ * own `viewport` or `canonical` replaces this one instead of shipping a second
+ * copy. `charset` is not here: it has to be inside the first 1024 bytes, and it
+ * is not something to override.
+ *
+ * @param {string|null} canonical the page's own URL, absolute, or null for none
+ * @returns {string} one level's worth of head markup
+ */
+function frameworkHead(canonical) {
+  const tags = ['<meta name="viewport" content="width=device-width, initial-scale=1">'];
+  if (canonical) tags.push(`<link rel="canonical" href="${escapeAttr(canonical)}">`);
+  return tags.join('\n');
+}
+
 /**
  * `<html …>`, with `lang` first and whatever a loader added after it.
  *
@@ -239,7 +256,8 @@ function openTag(tag, attrs) {
  *
  * @param {object} page a compiled page module
  * @param {object} ctx the request context
- * @param {object} [options] `clientEntry`, `stylesheet`, `csp`, `lang`, `include`
+ * @param {object} [options] `clientEntry`, `stylesheet`, `csp`, `lang`, `include`,
+ *   `canonical`
  * @returns {Promise<string|Response>} a Response when a loader answered for itself
  */
 export async function renderRoute(page, ctx, options = {}) {
@@ -266,7 +284,18 @@ export async function renderRoute(page, ctx, options = {}) {
     if (mod !== page) inherited = { ...inherited, ...data };
   }
 
-  const html = renderDocument(chain, datas, options);
+  // The config's `canonical` is a yes or no; the document's is the URL. Turned
+  // into one here because this is the layer that holds the request, and because
+  // the four callers that render a page would otherwise each compute it.
+  //
+  // `route.path` and not the request's URL: a canonical URL names the page, so a
+  // query parameter has no place in it. That the path is already free of a
+  // trailing slash is Hono's doing under `trailingSlash: 'ignore'`, which is the
+  // setting that makes this option worth having.
+  const html = renderDocument(chain, datas, {
+    ...options,
+    canonical: options.canonical ? ctx.absolute(ctx.route.path) : null,
+  });
 
   // After the document exists, because the policy is built from what it inlined.
   // A prerendered page runs this once at build time and carries the result.
@@ -598,13 +627,15 @@ export function methodsOf(page) {
  * @param {object[]} chain the compiled modules, outermost first
  * @param {object[]} datas one per level, in the same order
  * @param {{ clientEntry?: string|null, stylesheet?: string|null, lang?: string,
- *   speculate?: string|null }} [options]
+ *   speculate?: string|null, canonical?: string|null }} [options] `canonical` is
+ *   the URL itself, already absolute. `renderRoute` is what turns the config's
+ *   yes-or-no into one, because this function sees no request.
  * @returns {string} the document, starting at `<!doctype html>`
  */
 export function renderDocument(
   chain,
   datas,
-  { clientEntry, stylesheet, lang = 'en', speculate = null } = {},
+  { clientEntry, stylesheet, lang = 'en', speculate = null, canonical = null } = {},
 ) {
   // Each level renders to a slot map and hands it to the level above, so a page
   // can fill more than one hole in its layout.
@@ -624,13 +655,10 @@ export function renderDocument(
   }
 
   // Everything else accumulates outermost first, so a page's <meta> comes last
-  // and a page's <style> can override a layout's.
-  // The framework's own defaults go through the merge as the outermost level, so
-  // a page or a layout writing its own `viewport` replaces this one instead of
-  // shipping beside it. `charset` is not here: it has to be inside the first
-  // 1024 bytes and is not something to override.
+  // and a page's <style> can override a layout's. The framework's own head is the
+  // outermost level; `frameworkHead` says what is in it and why.
   const [defaults, ...rest] = mergeHead([
-    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    frameworkHead(canonical),
     ...chain.map((mod, i) => mod.renderHead(datas[i])),
   ]);
   const head = rest.filter(Boolean);

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/runtime/index.js

@@ -308,6 +308,20 @@ function closingAnchor(open) {
   return null;
 }
 
+/**
+ * The node after a block nobody bound.
+ *
+ * A light element renders its blocks once and never rebuilds them, so it holds
+ * no state for one. The walk that finds every node after it still has to get
+ * past it, and how wide it is only the anchors say.
+ *
+ * @param {Comment} open the opening anchor
+ * @returns {Node|null}
+ */
+export function afterBlock(open) {
+  return closingAnchor(open)?.nextSibling ?? null;
+}
+
 /**
  * An item spans one node or, where it renders several, the region between its
  * own anchors. Everything downstream works on the range, so a single-element

package/src/server.js

@@ -69,7 +69,9 @@ export function baseApp(options = {}) {
    * So 'never' means strict routing plus a 301 to the one URL, and every
    * URL this framework generates is already that form: `routes/about.html` is
    * `/about`. 'ignore' is the loose router, which answers both with 200. Two URLs
-   * for one page, and nothing emits <link rel="canonical">.
+   * for one page, which is what `canonical: true` in the config answers: the
+   * loose router hands `c.req.path` over with the slash already gone, so the URL
+   * the tag names is the one form either way.
    *
    * `alwaysRedirect` matters because Hono's default only redirects a request that
    * already 404'd, and a catch-all route answers before it can. `/docs/intro/`

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 }`;