@transclude/core 0.12.0 → 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));
 }
 
 /**
@@ -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/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.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/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/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/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 }`;