@timber-js/app 0.2.0-alpha.191 → 0.2.0-alpha.194

package/dist/index.js

@@ -1,22 +1,25 @@
-import { a as __esmMin, o as __exportAll, s as __toCommonJS } from "./_chunks/dist-BA3u1z3W.js";
-import { t as RSC_CONTENT_TYPE } from "./_chunks/rsc-media-type-DRqE_lD_.js";
-import { a as canonicalize, d as isMetadataRouteServePath, u as isDynamicMetadataExtension } from "./_chunks/segment-keys-BawYuNFO.js";
-import { n as collectInterceptionRewrites, r as matchUrlParts, t as scanRoutes } from "./_chunks/scanner-CAietmj4.js";
-import { h as swallow } from "./_chunks/logger-CH7IcMmg.js";
-import { c as writeRouteCodegen, i as getPrerenderExport, l as buildDirToRouteMap, n as formatConventionWarnings, r as lintConventions, s as flushCodegenWrites, t as checkAppDirExists } from "./_chunks/convention-lint-CpteIpTm.js";
-import { c as resolveClientJavascript, i as mergeFileConfig, l as createNoopTimer, o as resolveAppDir, r as loadTimberConfigFile, s as resolveBuildDir, t as createPluginContext } from "./_chunks/plugin-context-rCinWLiE.js";
-import { r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "./_chunks/walkers-BsVLmD1S.js";
+import { l as registerDevDiscovery } from "./_chunks/graph-cache-CP4GEmf9.js";
+import { n as isScannableSourceFile, t as buildSourceExtensions } from "./_chunks/scan-BoP17W3w.js";
+import { t as RSC_CONTENT_TYPE } from "./_chunks/rsc-media-type-DDc7duTD.js";
+import { a as canonicalize, d as isMetadataRouteServePath, u as isDynamicMetadataExtension } from "./_chunks/segment-keys-BhqoHiLc.js";
+import { i as matchUrlParts, n as scanRoutes, r as collectInterceptionRewrites } from "./_chunks/scanner-BRIOmHE2.js";
+import { t as MDX_EXTENSIONS } from "./_chunks/mdx-file-CXyHGUpS.js";
+import { h as swallow } from "./_chunks/logger-pumCm3Il.js";
+import { c as writeRouteCodegen, i as getPrerenderExport, l as buildDirToRouteMap, n as formatConventionWarnings, r as lintConventions, s as flushCodegenWrites, t as checkAppDirExists } from "./_chunks/convention-lint-DO10_pVl.js";
+import { c as resolveClientJavascript, i as mergeFileConfig, l as createNoopTimer, o as resolveAppDir, r as loadTimberConfigFile, s as resolveBuildDir, t as createPluginContext } from "./_chunks/plugin-context-8idfR3UZ.js";
+import { r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "./_chunks/walkers-uCu3WW6_.js";
+import { i as poisonPillSource, r as markerFor, t as EXPLICIT_MARKERS } from "./_chunks/poison-rules-DoEhbqaY.js";
 import { i as withBasePath, n as normalizeBasePath, t as isRelativeBase } from "./_chunks/base-path-DaQrzbez.js";
 import { t as rscPayloadPath } from "./_chunks/rsc-payload-path-B_LBodc2.js";
 import { a as REDIRECTS_FILE, n as detectFsIdentity, o as RESERVED_OUTPUT_PATHS, r as fsKey, t as EXACT_FS_IDENTITY } from "./_chunks/fs-identity-D7vb6GdI.js";
 import { t as EMPTY_BUILD_MANIFEST } from "./_chunks/build-manifest-DWppEdLB.js";
 import { t as fnv1aHash } from "./_chunks/fast-hash-C-tVYrLb.js";
-import { t as formatSize } from "./_chunks/format-CfwjgPz9.js";
-import { createLogger, parseAst } from "vite";
+import { t as formatSize } from "./_chunks/format-BKclgVbk.js";
+import { createLogger, normalizePath, parseAst } from "vite";
 import { basename, dirname, extname, isAbsolute, join, normalize, relative, resolve, win32 } from "node:path";
 import { builtinModules, createRequire } from "node:module";
 import react, { reactCompilerPreset } from "@vitejs/plugin-react";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import nodeHTTP from "node:http";
 import { Readable, pipeline } from "node:stream";
 import { pipeline as pipeline$1 } from "node:stream/promises";
@@ -24,9 +27,10 @@ import "node:https";
 import "node:http2";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { styleText } from "node:util";
-import { constants, createGzip, gzipSync } from "node:zlib";
 import { createHash, randomUUID } from "node:crypto";
-import { copyFile, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { isIP } from "node:net";
+import { constants, createGzip, gzipSync } from "node:zlib";
 //#region src/plugins/content.ts
 var CONFIG_FILE_NAMES$1 = [
 	"content-collections.ts",
@@ -106,13 +110,14 @@ function timberContent(ctx) {
 			return null;
 		},
 		async configureServer(server) {
+			if (process.env.TIMBER_ANALYZE === "1") return;
 			if (!innerPlugin) return;
 			if (typeof innerPlugin.configureServer === "function") await innerPlugin.configureServer.call(this, server);
 		}
 	};
 }
 //#endregion
-//#region ../../node_modules/.pnpm/srvx@0.12.0/node_modules/srvx/dist/adapters/node.mjs
+//#region ../../node_modules/.pnpm/srvx@0.12.5/node_modules/srvx/dist/adapters/node.mjs
 function sendNodeResponse(nodeRes, webRes) {
 	try {
 		return _sendNodeResponse(nodeRes, webRes, false) || Promise.resolve();
@@ -397,7 +402,8 @@ var _traceMapping = null;
 */
 function getTraceMapping() {
 	if (_traceMapping) return _traceMapping;
-	_traceMapping = createRequire(createRequire(import.meta.url).resolve("vite"))("@jridgewell/trace-mapping");
+	const vitePath = createRequire(import.meta.url).resolve("vite");
+	_traceMapping = createRequire(vitePath)("@jridgewell/trace-mapping");
 	return _traceMapping;
 }
 /** Labels for terminal output. */
@@ -1143,13 +1149,31 @@ var ERROR_CSS = `
 *
 * Design doc: 18-build-system.md
 */
-var config_validation_exports = /* @__PURE__ */ __exportAll({
-	addVirtualModuleContext: () => addVirtualModuleContext,
-	checkPeerDependencies: () => checkPeerDependencies,
-	formatConfigErrors: () => formatConfigErrors,
-	formatMissingPeers: () => formatMissingPeers,
-	validateConfig: () => validateConfig
-});
+var knownKeys = new Set(Object.keys({
+	output: true,
+	debug: true,
+	clientJavascript: true,
+	adapter: true,
+	allowedOrigins: true,
+	csrf: true,
+	limits: true,
+	forms: true,
+	pageExtensions: true,
+	slowRequestMs: true,
+	renderTimeoutMs: true,
+	devBrowserLogs: true,
+	dev: true,
+	serverTiming: true,
+	appDir: true,
+	mdx: true,
+	actionEncryption: true,
+	reactCompiler: true,
+	sitemap: true,
+	buildDir: true,
+	clientSegmentCache: true,
+	topLoader: true,
+	budget: true
+}));
 /**
 * Validate a TimberUserConfig object.
 *
@@ -1164,29 +1188,31 @@ function validateConfig(config) {
 		value: config.output,
 		suggestion: "Use output: \"server\" (default) or output: \"static\" for static site generation."
 	});
-	if (config.pageExtensions !== void 0) if (!Array.isArray(config.pageExtensions)) errors.push({
-		field: "pageExtensions",
-		message: "pageExtensions must be an array of strings.",
-		value: config.pageExtensions,
-		suggestion: "Example: pageExtensions: [\"tsx\", \"ts\", \"jsx\", \"js\", \"mdx\"]"
-	});
-	else for (const ext of config.pageExtensions) {
-		if (typeof ext !== "string") {
-			errors.push({
-				field: "pageExtensions",
-				message: `pageExtensions contains a non-string value: ${JSON.stringify(ext)}`,
-				value: ext
-			});
-			break;
-		}
-		if (ext.startsWith(".")) {
-			errors.push({
-				field: "pageExtensions",
-				message: `pageExtensions should not include the leading dot: "${ext}"`,
-				value: ext,
-				suggestion: `Use "${ext.slice(1)}" instead of "${ext}".`
-			});
-			break;
+	if (config.pageExtensions !== void 0) {
+		if (!Array.isArray(config.pageExtensions)) errors.push({
+			field: "pageExtensions",
+			message: "pageExtensions must be an array of strings.",
+			value: config.pageExtensions,
+			suggestion: "Example: pageExtensions: [\"tsx\", \"ts\", \"jsx\", \"js\", \"mdx\"]"
+		});
+		else for (const ext of config.pageExtensions) {
+			if (typeof ext !== "string") {
+				errors.push({
+					field: "pageExtensions",
+					message: `pageExtensions contains a non-string value: ${JSON.stringify(ext)}`,
+					value: ext
+				});
+				break;
+			}
+			if (ext.startsWith(".")) {
+				errors.push({
+					field: "pageExtensions",
+					message: `pageExtensions should not include the leading dot: "${ext}"`,
+					value: ext,
+					suggestion: `Use "${ext.slice(1)}" instead of "${ext}".`
+				});
+				break;
+			}
 		}
 	}
 	if (config.slowRequestMs !== void 0) {
@@ -1255,6 +1281,10 @@ function validateConfig(config) {
 	});
 	return errors;
 }
+var RED = "\x1B[31m";
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var RESET = "\x1B[0m";
 /**
 * Format config errors for terminal output.
 */
@@ -1269,6 +1299,16 @@ function formatConfigErrors(errors) {
 	}
 	return lines.join("\n");
 }
+var VIRTUAL_MODULE_NAMES = {
+	"virtual:timber-rsc-entry": "RSC entry (server component handler)",
+	"virtual:timber-ssr-entry": "SSR entry (HTML renderer)",
+	"virtual:timber-browser-entry": "Browser entry (client hydration)",
+	"virtual:timber-config": "Runtime config (timber.config.ts)",
+	"virtual:timber-route-manifest": "Route manifest (app/ file tree)",
+	"virtual:timber-instrumentation": "Instrumentation (instrumentation.ts)",
+	"virtual:timber-cache-handler": "Cache handler (timber.cache.ts)",
+	"virtual:timber-build-manifest": "Build manifest (asset mapping)"
+};
 /**
 * Add timber-specific context to an error message that references virtual modules.
 *
@@ -1280,6 +1320,15 @@ function addVirtualModuleContext(errorMessage) {
 	return errorMessage;
 }
 /**
+* Required (non-optional) peer dependencies that must be installed.
+*/
+var REQUIRED_PEERS = [
+	"react",
+	"react-dom",
+	"@vitejs/plugin-react",
+	"@vitejs/plugin-rsc"
+];
+/**
 * Check that required peer dependencies are installed.
 *
 * Uses require.resolve with a try/catch — no fs scanning.
@@ -1318,57 +1367,325 @@ function formatMissingPeers(results) {
 	lines.push(`  ${BOLD}pnpm add ${names.join(" ")}${RESET}`);
 	return lines.join("\n");
 }
-var knownKeys, RED, BOLD, DIM, RESET, VIRTUAL_MODULE_NAMES, REQUIRED_PEERS;
-var init_config_validation = __esmMin((() => {
-	knownKeys = new Set(Object.keys({
-		output: true,
-		debug: true,
-		clientJavascript: true,
-		adapter: true,
-		allowedOrigins: true,
-		csrf: true,
-		limits: true,
-		forms: true,
-		pageExtensions: true,
-		slowRequestMs: true,
-		renderTimeoutMs: true,
-		devBrowserLogs: true,
-		dev: true,
-		serverTiming: true,
-		appDir: true,
-		mdx: true,
-		actionEncryption: true,
-		reactCompiler: true,
-		sitemap: true,
-		buildDir: true,
-		clientSegmentCache: true,
-		topLoader: true,
-		budget: true
-	}));
-	RED = "\x1B[31m";
-	BOLD = "\x1B[1m";
-	DIM = "\x1B[2m";
-	RESET = "\x1B[0m";
-	VIRTUAL_MODULE_NAMES = {
-		"virtual:timber-rsc-entry": "RSC entry (server component handler)",
-		"virtual:timber-ssr-entry": "SSR entry (HTML renderer)",
-		"virtual:timber-browser-entry": "Browser entry (client hydration)",
-		"virtual:timber-config": "Runtime config (timber.config.ts)",
-		"virtual:timber-route-manifest": "Route manifest (app/ file tree)",
-		"virtual:timber-instrumentation": "Instrumentation (instrumentation.ts)",
-		"virtual:timber-cache-handler": "Cache handler (timber.cache.ts)",
-		"virtual:timber-build-manifest": "Build manifest (asset mapping)"
+/** HMR custom event name for graph-affecting file changes. */
+var GRAPH_UPDATE_EVENT = "timber:graph-update";
+/**
+* Host-header allowlist check, ported branch-for-branch from Vite's
+* host-validation middleware (`isHostAllowedWithoutCache`) so this
+* endpoint's reachability matches the rest of the dev server:
+*
+* - `allowedHosts: true` allows everything
+* - a MISSING Host header is allowed (Vite parity — HTTP/1.0 probes)
+* - any IP-literal host is allowed (`vite --host` LAN access sends
+*   `Host: 192.168.x.x:port`; rejecting it would 403 this endpoint
+*   while every other dev route works)
+* - `localhost` and `*.localhost` are always allowed
+* - allowedHosts entries: exact match, or `.suffix` subdomain entries
+*/
+function isAllowedGraphHost(hostHeader, allowedHosts) {
+	if (allowedHosts === true) return true;
+	if (hostHeader === void 0) return true;
+	let host = hostHeader;
+	const bracket = host.match(/^\[([^\]]+)\](?::\d+)?$/);
+	if (bracket) return isIP(bracket[1]) === 6;
+	const colon = host.lastIndexOf(":");
+	if (colon !== -1) host = host.slice(0, colon);
+	host = host.toLowerCase();
+	if (isIP(host) !== 0) return true;
+	if (host === "localhost" || host.endsWith(".localhost")) return true;
+	for (const entry of allowedHosts ?? []) {
+		const allowed = entry.toLowerCase();
+		if (allowed.startsWith(".")) {
+			if (host === allowed.slice(1) || host.endsWith(allowed)) return true;
+		} else if (host === allowed) return true;
+	}
+	return false;
+}
+/**
+* Non-http(s) origins admitted without a host check: Vite's own
+* `file:` / `*-extension:` set (its host-validation regex), plus
+* `vscode-webview:` — VS Code webviews fetch with that Origin, and the
+* extension is this endpoint's primary consumer. Vite itself never
+* origin-checks plain HTTP GETs (only WebSocket upgrades), so this
+* layer is strictly additional; the additions keep it from rejecting
+* consumers Vite would serve.
+*
+* NOT admitted: `Origin: null`. Browsers serialize file:// pages'
+* opaque origin as the literal string `null` — but so do sandboxed
+* iframes and data: documents, exactly the untrusted embedders the
+* check exists to stop, and the header offers nothing to tell them
+* apart. file:// pages therefore cannot use this endpoint from a
+* browser; the `file:` scheme entry covers non-browser clients that
+* send a real scheme-form Origin (Vite admits the same set).
+*/
+var TRUSTED_ORIGIN_SCHEMES = /^(?:file|vscode-webview|.+-extension):/i;
+/** Origin check: absent is fine (CLI probe); present must pass the host allowlist. */
+function isAllowedGraphOrigin(originHeader, allowedHosts) {
+	if (originHeader === void 0) return true;
+	if (TRUSTED_ORIGIN_SCHEMES.test(originHeader)) return true;
+	let originUrl;
+	try {
+		originUrl = new URL(originHeader);
+	} catch {
+		return false;
+	}
+	if (originUrl.host === "") return false;
+	const bareHost = originUrl.hostname.replace(/^\[|\]$/g, "");
+	if (isIP(bareHost) !== 0) {
+		if (bareHost === "127.0.0.1" || bareHost === "::1") return true;
+		if (allowedHosts === true) return true;
+		return (allowedHosts ?? []).some((entry) => entry.toLowerCase() === bareHost);
+	}
+	return isAllowedGraphHost(originUrl.host, allowedHosts);
+}
+function sendJson(res, status, body) {
+	res.statusCode = status;
+	res.setHeader("content-type", "application/json; charset=utf-8");
+	res.end(JSON.stringify(body));
+}
+/**
+* Echo an ADMITTED origin back as CORS headers. A webview fetch from
+* `vscode-webview://…` passes the origin check but the browser rejects
+* the response body without `Access-Control-Allow-Origin` — the exact
+* transport design/47 specifies for the extension. Only the validated
+* origin is echoed (never `*`), with `Vary: Origin` for any cache in
+* between; unadmitted origins were already 403'd and get nothing.
+*/
+function reflectCors(res, origin) {
+	if (!origin) return;
+	res.setHeader("Access-Control-Allow-Origin", origin);
+	res.setHeader("Vary", "Origin");
+}
+/**
+* Create the Connect middleware handling GET /__timber/graph.
+*
+* Query surface: `?file=<path>` (absolute or project-root-relative) or
+* `?all=1`. Anything else is a 400 — fail loudly, like the CLI.
+*/
+function createGraphEndpointMiddleware(server, ctx) {
+	const sourceExtensions = buildSourceExtensions(ctx.config.pageExtensions);
+	return async (req, res, next) => {
+		const rawUrl = req.url;
+		if (!rawUrl || !rawUrl.startsWith("/__timber/")) {
+			next();
+			return;
+		}
+		const url = new URL(rawUrl, "http://placeholder.invalid");
+		if (url.pathname !== "/__timber/graph") {
+			sendJson(res, 404, { error: `unknown /__timber/ endpoint: ${url.pathname}` });
+			return;
+		}
+		if (req.method !== "GET") {
+			res.setHeader("Allow", "GET");
+			sendJson(res, 405, { error: "GET only" });
+			return;
+		}
+		const origin = req.headers.origin;
+		const allowedHosts = server.config.server.allowedHosts;
+		if (!server.config.server.https && !isAllowedGraphHost(req.headers.host, allowedHosts)) {
+			sendJson(res, 403, { error: "host not allowed" });
+			return;
+		}
+		if (!isAllowedGraphOrigin(origin, allowedHosts)) {
+			sendJson(res, 403, { error: "origin not allowed" });
+			return;
+		}
+		reflectCors(res, origin);
+		try {
+			const { classifyLiveFile, classifyLiveProject } = await import("./_chunks/live-graph-Bx4HodF1.js");
+			const preserveSymlinks = server.config.resolve.preserveSymlinks;
+			const root = normalizePath(preserveSymlinks ? ctx.root : await realpath(ctx.root));
+			const appDir = normalizePath(preserveSymlinks ? ctx.appDir : await realpath(ctx.appDir).catch(() => join(root, relative(ctx.root, ctx.appDir))));
+			const liveCtx = {
+				rsc: server.environments.rsc.moduleGraph,
+				ssr: server.environments.ssr.moduleGraph,
+				client: server.environments.client.moduleGraph,
+				root,
+				appDir,
+				pageExtensions: ctx.config.pageExtensions
+			};
+			const allParam = url.searchParams.get("all");
+			if (allParam !== null && allParam !== "1") {
+				sendJson(res, 400, { error: `unsupported all value: ${allParam} (use ?all=1)` });
+				return;
+			}
+			if (allParam === "1") {
+				sendJson(res, 200, {
+					version: 1,
+					source: "dev-server",
+					cached: false,
+					...await classifyLiveProject(liveCtx)
+				});
+				return;
+			}
+			const fileParam = url.searchParams.get("file");
+			if (!fileParam) {
+				sendJson(res, 400, { error: "missing ?file=<path> (or ?all=1)" });
+				return;
+			}
+			const absolute = normalizePath(isAbsolute(fileParam) ? resolve(fileParam) : resolve(root, fileParam));
+			let target;
+			try {
+				const physical = normalizePath(await realpath(absolute));
+				const rootPhysical = preserveSymlinks ? normalizePath(await realpath(root)) : root;
+				if (physical !== rootPhysical && !physical.startsWith(rootPhysical + "/") && !physical.startsWith(rootPhysical + "\\")) {
+					sendJson(res, 404, { error: `not a project file under ${root}` });
+					return;
+				}
+				if (preserveSymlinks) {
+					if (physical !== rootPhysical + absolute.slice(root.length)) {
+						sendJson(res, 404, { error: `not a project source file: ${absolute}` });
+						return;
+					}
+				}
+				target = normalizePath(preserveSymlinks ? absolute : physical);
+			} catch {
+				sendJson(res, 404, { error: `file not found: ${absolute}` });
+				return;
+			}
+			if (target !== root && !target.startsWith(root + "/") && !target.startsWith(root + "\\")) {
+				sendJson(res, 404, { error: `not a project file under ${root}` });
+				return;
+			}
+			if (!(await stat(target).catch(() => null))?.isFile() || !isScannableSourceFile(normalizePath(target), normalizePath(root), sourceExtensions)) {
+				sendJson(res, 404, { error: `not a project source file: ${target}` });
+				return;
+			}
+			const errors = [];
+			const module = await classifyLiveFile(target, liveCtx, void 0, errors);
+			sendJson(res, 200, {
+				version: 1,
+				source: "dev-server",
+				cached: false,
+				target: {
+					input: fileParam,
+					resolved: target
+				},
+				kind: module.kind,
+				pending: module.pending,
+				subtreeUnknown: module.subtreeUnknown,
+				envs: module.envs,
+				boundary: module.boundary,
+				chains: module.chains,
+				poisonings: module.poisonings,
+				errors
+			});
+		} catch (error) {
+			sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+		}
+	};
+}
+/**
+* Build the push channel: `timber:graph-update` custom HMR events per
+* project-source change. Consumers (the VS Code extension) re-query
+* and debounce on their side; the channel just emits. Non-source noise
+* (build output, dotdirs) is filtered by the same extension set the
+* scanners use.
+*
+* Two phases per edit, because one is not enough (codex review, PR
+* #1057): the `invalidated` event fires from the plugin's `hotUpdate`
+* hook — after Vite clears the module's transform result, but its
+* importer EDGES are only rebuilt when the module is next transformed.
+* The `transformed` event fires for exactly the files with a pending
+* invalidation, and only once the node's `transformResult` is set
+* again — the plugin transform hook itself runs BEFORE Vite's trailing
+* `vite:import-analysis` (which rebuilds the edges), so the hook only
+* marks the file "settling" and a short bounded timer confirms
+* completion via `isTransformed` before emitting. (A module nothing
+* re-requests never re-transforms — its `transformed` event waits for
+* the next render, which is also when the graph has new information.)
+*/
+function makeGraphUpdateChannel(ctx, send, isTransformed, canonicalize = (file) => file) {
+	/** Files invalidated but not yet re-transformed, per environment. */
+	const pending = /* @__PURE__ */ new Set();
+	const key = (file, environment) => `${environment}\0${file}`;
+	const root = normalizePath(canonicalize(ctx.root));
+	const extensions = buildSourceExtensions(ctx.config.pageExtensions);
+	const emitTransformed = (file, environment, structural) => {
+		send({
+			type: "custom",
+			event: GRAPH_UPDATE_EVENT,
+			data: structural ? {
+				file,
+				event: "update",
+				environment,
+				phase: "transformed",
+				structural: true
+			} : {
+				file,
+				event: "update",
+				environment,
+				phase: "transformed"
+			}
+		});
 	};
-	REQUIRED_PEERS = [
-		"react",
-		"react-dom",
-		"@vitejs/plugin-react",
-		"@vitejs/plugin-rsc"
+	/**
+	* Confirm the transform request finished (transformResult set again)
+	* before emitting phase `transformed`. If confirmation never arrives
+	* within the bounded schedule below, the pending key is RE-ARMED
+	* rather than emitted — a `transformed` event over a still-stale
+	* graph would be a false all-clear with no corrective event.
+	*/
+	/**
+	* Delays between confirmation re-checks: dense while a normal
+	* transform request finishes, then exponential backoff for slow
+	* import-analysis passes (large graphs, cold dep optimizer) — a
+	* completed slow transform is CACHED, so no later transform hook may
+	* ever fire for it and the tail checks are the only chance to emit.
+	* Total window ≈ 16 s, then give up (bounded — the async-safety
+	* rules ban open-ended polling) and re-arm the pending key.
+	*/
+	const CONFIRM_DELAYS_MS = [
+		...Array.from({ length: 25 }, () => 20),
+		500,
+		1e3,
+		2e3,
+		4e3,
+		8e3
 	];
-}));
+	const confirmAndEmit = (file, environment, attempt = 0, structural = false) => {
+		if (!isTransformed || isTransformed(file, environment)) {
+			emitTransformed(file, environment, structural);
+			return;
+		}
+		if (attempt >= CONFIRM_DELAYS_MS.length) {
+			if (!structural) pending.add(key(file, environment));
+			return;
+		}
+		setTimeout(() => confirmAndEmit(file, environment, attempt + 1, structural), CONFIRM_DELAYS_MS[attempt]);
+	};
+	return {
+		onHotUpdate(update) {
+			const file = normalizePath(canonicalize(update.file));
+			if (!isScannableSourceFile(file, root, extensions)) return;
+			if (update.type === "delete") pending.delete(key(file, update.environment));
+			else pending.add(key(file, update.environment));
+			send({
+				type: "custom",
+				event: GRAPH_UPDATE_EVENT,
+				data: {
+					file,
+					event: update.type,
+					environment: update.environment,
+					phase: "invalidated"
+				}
+			});
+		},
+		onTransform(id, environment) {
+			const file = normalizePath(id.split("?")[0]);
+			if (file.includes("virtual:timber-route-manifest")) {
+				confirmAndEmit(file, environment, 25, true);
+				return;
+			}
+			const pendingKey = key(file, environment);
+			if (!pending.has(pendingKey)) return;
+			pending.delete(pendingKey);
+			confirmAndEmit(file, environment);
+		}
+	};
+}
 //#endregion
 //#region src/server/compress.ts
-init_config_validation();
 /**
 * MIME types that benefit from compression.
 * text/* is handled via prefix matching; these are the specific
@@ -1481,7 +1798,8 @@ function compressResponse(request, response) {
 */
 function compressWithGzip(body) {
 	const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
-	pipeline(Readable.fromWeb(body), gzip, () => {});
+	const nodeInput = Readable.fromWeb(body);
+	pipeline(nodeInput, gzip, () => {});
 	return Readable.toWeb(gzip);
 }
 //#endregion
@@ -1516,10 +1834,35 @@ var ASSET_EXTENSIONS = /\.(?:js|ts|tsx|jsx|css|map|json|svg|png|jpg|jpeg|gif|web
 * Hook: configureServer (returns post-hook to register after Vite's middleware)
 */
 function timberDevServer(ctx) {
+	let graphChannel = null;
 	return {
 		name: "timber-dev-server",
 		apply: "serve",
 		/**
+		* Push channel for the graph endpoint, phase 1: `invalidated`, one
+		* per (file, environment). Emitted from hotUpdate — which runs
+		* AFTER Vite invalidates the environment module graphs — never
+		* from a raw watcher listener, which would race consumers into
+		* querying pre-invalidation memberships (design/47 §"Dev-server
+		* endpoint").
+		*/
+		hotUpdate({ file, type }) {
+			graphChannel?.onHotUpdate({
+				file,
+				type,
+				environment: this.environment.name
+			});
+		},
+		/**
+		* Push channel phase 2: `transformed`, when a pending-invalidated
+		* module's import edges are actually rebuilt. A Set lookup for
+		* everything without a pending invalidation — free on the hot
+		* path. Returning nothing leaves the code untouched.
+		*/
+		transform(_code, id) {
+			graphChannel?.onTransform(id, this.environment.name);
+		},
+		/**
 		* Register the dev server middleware and config file watcher.
 		*
 		* Registers as a pre-hook (no return value) so our middleware runs
@@ -1532,7 +1875,30 @@ function timberDevServer(ctx) {
 			const configPaths = CONFIG_FILE_NAMES.map((name) => join(ctx.root, name));
 			server.watcher.add(configPaths);
 			listenForClientErrors(server, ctx.root);
+			server.middlewares.use(createGraphEndpointMiddleware(server, ctx));
+			graphChannel = makeGraphUpdateChannel(ctx, (payload) => server.hot.send(payload), (file, environment) => {
+				const graph = server.environments[environment]?.moduleGraph;
+				if (!graph) return false;
+				const nodes = graph.getModulesByFile(file);
+				if (nodes) {
+					for (const node of nodes) if (node.transformResult != null) return true;
+					return false;
+				}
+				return graph.getModuleById(file)?.transformResult != null;
+			}, (file) => {
+				if (server.config?.resolve?.preserveSymlinks || file.includes("virtual:")) return file;
+				try {
+					return realpathSync(file);
+				} catch {
+					try {
+						return join(realpathSync(dirname(file)), basename(file));
+					} catch {
+						return file;
+					}
+				}
+			});
 			server.middlewares.use(createTimberMiddleware(server, ctx));
+			registerDevDiscovery(server.httpServer, ctx.root, server.config);
 			if (ctx.holdingServer) {
 				const originalListen = server.listen.bind(server);
 				const holdingRef = ctx.holdingServer;
@@ -2071,7 +2437,7 @@ function timberEntries(ctx) {
 }
 //#endregion
 //#region src/plugins/mdx.ts
-var MDX_EXTENSIONS = ["mdx", "md"];
+var MDX_EXTENSIONS_UNDOTTED = [...MDX_EXTENSIONS].map((ext) => ext.slice(1));
 /**
 * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
 * or in src/. Root takes precedence, matching Next.js behavior.
@@ -2094,8 +2460,9 @@ function findMdxComponents(root) {
 * Determine if MDX should be activated based on config and project structure.
 */
 function shouldActivate(ctx) {
+	if (ctx.config.mdx === false) return false;
 	const exts = ctx.config.pageExtensions;
-	if (exts && exts.some((ext) => MDX_EXTENSIONS.includes(ext))) return true;
+	if (exts && exts.some((ext) => MDX_EXTENSIONS_UNDOTTED.includes(ext))) return true;
 	if (existsSync(join(ctx.root, "content"))) return true;
 	return false;
 }
@@ -2105,13 +2472,11 @@ function shouldActivate(ctx) {
 *
 * Why this matters: pnpm only hoists declared (peer) dependencies into a
 * package's resolution scope. The MDX integration's optional companions
-* — `remark-frontmatter`, `remark-mdx-frontmatter`, `@mdx-js/rollup` — are
-* installed as direct deps of the consumer (e.g. `packages/website`), not
-* `@timber-js/app`. A bare `import('remark-frontmatter')` from inside this
-* file resolves against `packages/timber-app/node_modules` and silently
-* fails with `ERR_MODULE_NOT_FOUND`, which made `tryImport` return
-* `undefined` and skipped frontmatter parsing entirely — leaving MDX to
-* choke on YAML as JS expressions (TIM-840).
+* — `vite-plugin-satteri` and `satteri` — are installed as direct deps of
+* the consumer (e.g. `packages/website`), not `@timber-js/app`. A bare
+* `import('vite-plugin-satteri')` from inside this file resolves against
+* `packages/timber-app/node_modules` and silently fails with
+* `ERR_MODULE_NOT_FOUND` (TIM-840).
 *
 * Resolving relative to `projectRoot` (via `createRequire`) makes the
 * lookup walk the consumer's `node_modules` tree first, which is where
@@ -2122,7 +2487,8 @@ function shouldActivate(ctx) {
 */
 async function tryImport(name, projectRoot) {
 	try {
-		const mod = await import(pathToFileURL(createRequire(join(projectRoot, "package.json")).resolve(name)).href);
+		const resolved = createRequire(join(projectRoot, "package.json")).resolve(name);
+		const mod = await import(pathToFileURL(resolved).href);
 		return mod.default ?? mod;
 	} catch {
 		try {
@@ -2138,39 +2504,41 @@ async function tryImport(name, projectRoot) {
 * Create the timber-mdx Vite plugin.
 *
 * Uses the transform and resolveId hooks to delegate MDX compilation
-* to @mdx-js/rollup. The inner plugin is loaded lazily on first activation.
+* to vite-plugin-satteri. The inner plugin is loaded lazily on first
+* activation.
 *
-* Hooks: buildStart (loads @mdx-js/rollup), resolveId, load, transform
+* Hooks: buildStart (loads vite-plugin-satteri), resolveId, load, transform
 */
 function timberMdx(ctx) {
 	let innerPlugin = null;
 	async function activate() {
 		if (innerPlugin !== null || !shouldActivate(ctx)) return;
-		const createMdxPlugin = await tryImport("@mdx-js/rollup", ctx.root);
-		if (!createMdxPlugin) throw new Error([
-			"[timber] MDX is enabled but @mdx-js/rollup is not installed.",
+		if (ctx.config.pageExtensions?.includes("md")) throw new Error([
+			"[timber] pageExtensions includes 'md', but .md route pages are not supported:",
+			"Markdown files compile to HTML strings, not components.",
+			"",
+			"Use .mdx for pages (pageExtensions: ['tsx', 'ts', 'mdx']).",
+			".md files can still be imported as HTML strings — no pageExtensions entry needed."
+		].join("\n"));
+		const createSatteriPlugin = await tryImport("vite-plugin-satteri", ctx.root);
+		if (!createSatteriPlugin) throw new Error([
+			"[timber] MDX is enabled but vite-plugin-satteri is not installed.",
 			"",
 			"Install it:",
-			"  pnpm add -D @mdx-js/rollup remark-frontmatter remark-mdx-frontmatter",
+			"  pnpm add -D vite-plugin-satteri satteri",
 			"",
 			"MDX is activated because pageExtensions includes \"mdx\"/\"md\" or a content/ directory exists."
 		].join("\n"));
-		const mdxConfig = ctx.config.mdx ?? {};
-		const remarkPlugins = [];
-		const remarkFrontmatter = await tryImport("remark-frontmatter", ctx.root);
-		const remarkMdxFrontmatter = await tryImport("remark-mdx-frontmatter", ctx.root);
-		if (remarkFrontmatter) remarkPlugins.push(remarkFrontmatter);
-		if (remarkMdxFrontmatter) remarkPlugins.push(remarkMdxFrontmatter);
-		if (mdxConfig.remarkPlugins) remarkPlugins.push(...mdxConfig.remarkPlugins);
-		const mdxOptions = {
-			remarkPlugins,
-			rehypePlugins: mdxConfig.rehypePlugins ?? [],
-			recmaPlugins: mdxConfig.recmaPlugins ?? [],
-			remarkRehypeOptions: mdxConfig.remarkRehypeOptions
-		};
+		const mdxConfig = ctx.config.mdx || {};
+		const mdxOptions = { development: ctx.dev };
 		const mdxComponentsPath = findMdxComponents(ctx.root);
 		if (mdxComponentsPath) mdxOptions.providerImportSource = mdxComponentsPath;
-		innerPlugin = createMdxPlugin(mdxOptions);
+		innerPlugin = createSatteriPlugin({
+			mdx: mdxOptions,
+			...mdxConfig.mdastPlugins ? { mdastPlugins: mdxConfig.mdastPlugins } : {},
+			...mdxConfig.hastPlugins ? { hastPlugins: mdxConfig.hastPlugins } : {},
+			...mdxConfig.features ? { features: mdxConfig.features } : {}
+		});
 	}
 	return {
 		name: "timber-mdx",
@@ -2198,6 +2566,7 @@ function timberMdx(ctx) {
 		},
 		async transform(code, id) {
 			if (!innerPlugin) return null;
+			if (id.includes("?")) return null;
 			const envName = this.environment?.name;
 			if (envName && envName !== "rsc") return null;
 			if (typeof innerPlugin.transform === "function") return innerPlugin.transform.call(this, code, id);
@@ -2380,6 +2749,7 @@ var ROUTE_FILE_PATTERNS = /\/(page|layout|middleware|access|route|error|global-e
 */
 function writeCodegen(ctx) {
 	if (!ctx.routeTree) return;
+	if (process.env.TIMBER_ANALYZE === "1") return;
 	writeRouteCodegen(ctx.routeTree, ctx.appDir, ctx.root).catch((err) => {
 		console.warn("[timber] Failed to write codegen output:", err);
 	});
@@ -2607,9 +2977,7 @@ function warnSchemaValidation(ctx) {
 			case "bracket-mismatch":
 				console.warn(`[timber] ${w.message}`);
 				break;
-			case "missing-key":
-				console.warn(`[timber] ${w.message}`);
-				break;
+			case "missing-key": console.warn(`[timber] ${w.message}`);
 		}
 	}
 }
@@ -2631,14 +2999,13 @@ var __dirname = dirname(fileURLToPath(import.meta.url));
 var PKG_ROOT = __dirname.endsWith("plugins") ? resolve(__dirname, "..", "..") : resolve(__dirname, "..");
 var SHIMS_DIR = resolve(PKG_ROOT, "src", "shims");
 /**
-* Virtual module IDs for server-only and client-only poison pills.
-*
-* These packages cause build errors when imported in the wrong environment:
-* - `server-only` errors when imported in a client component
-* - `client-only` errors when imported in a server component
+* The server-only marker's virtual ID, needed directly by the
+* `#server-only-guard` resolution branch below. All poison-pill rules
+* (specifiers, virtual IDs, error messages, environment policy) live in
+* analyze/poison-rules.ts — the single source of truth shared with the
+* `timber graph` reporter (design/47 §3).
 */
-var SERVER_ONLY_VIRTUAL = "\0timber:server-only";
-var CLIENT_ONLY_VIRTUAL = "\0timber:client-only";
+var SERVER_ONLY_VIRTUAL = markerFor("server-only").virtualId;
 /**
 * Map from @timber-js/app/<subpath> to relative src/ file paths.
 *
@@ -2765,8 +3132,7 @@ function timberShims(_ctx) {
 		* the browser.
 		*/
 		resolveId(id) {
-			if (id === "server-only") return SERVER_ONLY_VIRTUAL;
-			if (id === "client-only") return CLIENT_ONLY_VIRTUAL;
+			for (const marker of EXPLICIT_MARKERS) if (id === marker.specifier) return marker.virtualId;
 			const cleanId = stripJsExtension(id);
 			if (cleanId in SHIM_MAP) {
 				if (envName(this) === "client" && cleanId === "next/navigation") return resolve(SHIMS_DIR, "navigation-client.ts");
@@ -2815,21 +3181,8 @@ function timberShims(_ctx) {
 		* clearly identifies the boundary violation.
 		*/
 		load(id) {
-			const isClient = envName(this) === "client";
-			if (id === SERVER_ONLY_VIRTUAL) {
-				if (isClient) return `throw new Error(
-  "This module cannot be imported from a Client Component module. " +
-  "It should only be used from a Server Component."
-);`;
-				return "export {};";
-			}
-			if (id === CLIENT_ONLY_VIRTUAL) {
-				if (!isClient) return `throw new Error(
-  "This module cannot be imported from a Server Component module. " +
-  "It should only be used from a Client Component."
-);`;
-				return "export {};";
-			}
+			const env = envName(this);
+			for (const marker of EXPLICIT_MARKERS) if (id === marker.virtualId) return poisonPillSource(marker, env);
 			if (id === "\0timber:server-empty") return `
 const msg = "[timber] @timber-js/app/server was imported from client code. " +
   "Server modules (headers, cookies, redirect, deny, etc.) cannot be used in client components. " +
@@ -4446,7 +4799,7 @@ function encodeInteger(builder, num, relative) {
 	} while (delta > 0);
 	return num;
 }
-var bufLength = 1024 * 16;
+var bufLength = 16384;
 var td = typeof TextDecoder !== "undefined" ? /* @__PURE__ */ new TextDecoder() : typeof Buffer !== "undefined" ? { decode(buf) {
 	return Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString();
 } } : { decode(buf) {
@@ -4499,7 +4852,7 @@ function encode(decoded) {
 	return writer.flush();
 }
 //#endregion
-//#region ../../node_modules/.pnpm/magic-string@0.30.21/node_modules/magic-string/dist/magic-string.es.mjs
+//#region ../../node_modules/.pnpm/magic-string@1.2.0/node_modules/magic-string/dist/index.mjs
 var BitSet = class BitSet {
 	constructor(arg) {
 		this.bits = arg instanceof BitSet ? arg.bits.slice() : [];
@@ -4543,14 +4896,16 @@ var Chunk = class Chunk {
 		return this.start < index && index < this.end;
 	}
 	eachNext(fn) {
-		let chunk = this;
+		fn(this);
+		let chunk = this.next;
 		while (chunk) {
 			fn(chunk);
 			chunk = chunk.next;
 		}
 	}
 	eachPrevious(fn) {
-		let chunk = this;
+		fn(this);
+		let chunk = this.previous;
 		while (chunk) {
 			fn(chunk);
 			chunk = chunk.previous;
@@ -4608,10 +4963,8 @@ var Chunk = class Chunk {
 		if (this.outro.length) return true;
 		const trimmed = this.content.replace(rx, "");
 		if (trimmed.length) {
-			if (trimmed !== this.content) {
-				this.split(this.start + trimmed.length).edit("", void 0, true);
-				if (this.edited) this.edit(trimmed, this.storeName, true);
-			}
+			if (trimmed !== this.content) if (this.edited) this.edit(trimmed, this.storeName, true);
+			else this.split(this.start + trimmed.length).edit("", void 0, true);
 			return true;
 		} else {
 			this.edit("", void 0, true);
@@ -4624,9 +4977,9 @@ var Chunk = class Chunk {
 		if (this.intro.length) return true;
 		const trimmed = this.content.replace(rx, "");
 		if (trimmed.length) {
-			if (trimmed !== this.content) {
-				const newChunk = this.split(this.end - trimmed.length);
-				if (this.edited) newChunk.edit(trimmed, this.storeName, true);
+			if (trimmed !== this.content) if (this.edited) this.edit(trimmed, this.storeName, true);
+			else {
+				this.split(this.end - trimmed.length);
 				this.edit("", void 0, true);
 			}
 			return true;
@@ -4637,14 +4990,27 @@ var Chunk = class Chunk {
 		}
 	}
 };
+/**
+* The single error type thrown by MagicString.
+*
+* Every message is prefixed with `[MagicString]` so its source is obvious at a
+* glance, and is kept short and consistent in tone.
+*/
+var MagicStringError = class extends Error {
+	name = "MagicStringError";
+	constructor(message, options) {
+		super(`[MagicString] ${message}`, options);
+	}
+};
 function getBtoa() {
 	if (typeof globalThis !== "undefined" && typeof globalThis.btoa === "function") return (str) => globalThis.btoa(unescape(encodeURIComponent(str)));
-	else if (typeof Buffer === "function") return (str) => Buffer.from(str, "utf-8").toString("base64");
-	else return () => {
-		throw new Error("Unsupported environment: `window.btoa` or `Buffer` should be supported.");
+	const buffer = globalThis["Buffer"];
+	if (buffer) return (str) => buffer.from(str, "utf-8").toString("base64");
+	return () => {
+		throw new MagicStringError("unsupported environment: `btoa` or `Buffer` is required");
 	};
 }
-var btoa = /*#__PURE__*/ getBtoa();
+var btoa = /* #__PURE__ */ getBtoa();
 var SourceMap = class {
 	constructor(properties) {
 		this.version = 3;
@@ -4656,43 +5022,20 @@ var SourceMap = class {
 		if (typeof properties.x_google_ignoreList !== "undefined") this.x_google_ignoreList = properties.x_google_ignoreList;
 		if (typeof properties.debugId !== "undefined") this.debugId = properties.debugId;
 	}
+	/**
+	* Returns the equivalent of `JSON.stringify(map)`
+	*/
 	toString() {
 		return JSON.stringify(this);
 	}
+	/**
+	* Returns a DataURI containing the sourcemap. Useful for doing this sort of thing:
+	* `generateMap(options?: SourceMapOptions): SourceMap;`
+	*/
 	toUrl() {
-		return "data:application/json;charset=utf-8;base64," + btoa(this.toString());
+		return `data:application/json;charset=utf-8;base64,${btoa(this.toString())}`;
 	}
 };
-function guessIndent(code) {
-	const lines = code.split("\n");
-	const tabbed = lines.filter((line) => /^\t+/.test(line));
-	const spaced = lines.filter((line) => /^ {2,}/.test(line));
-	if (tabbed.length === 0 && spaced.length === 0) return null;
-	if (tabbed.length >= spaced.length) return "	";
-	const min = spaced.reduce((previous, current) => {
-		const numSpaces = /^ +/.exec(current)[0].length;
-		return Math.min(numSpaces, previous);
-	}, Infinity);
-	return new Array(min + 1).join(" ");
-}
-function getRelativePath(from, to) {
-	const fromParts = from.split(/[/\\]/);
-	const toParts = to.split(/[/\\]/);
-	fromParts.pop();
-	while (fromParts[0] === toParts[0]) {
-		fromParts.shift();
-		toParts.shift();
-	}
-	if (fromParts.length) {
-		let i = fromParts.length;
-		while (i--) fromParts[i] = "..";
-	}
-	return fromParts.concat(toParts).join("/");
-}
-var toString = Object.prototype.toString;
-function isObject(thing) {
-	return toString.call(thing) === "[object Object]";
-}
 function getLocator(source) {
 	const originalLines = source.split("\n");
 	const lineOffsets = [];
@@ -4715,6 +5058,36 @@ function getLocator(source) {
 		};
 	};
 }
+function getRelativePath(from, to) {
+	const fromParts = from.split(/[/\\]/);
+	const toParts = to.split(/[/\\]/);
+	fromParts.pop();
+	while (fromParts[0] === toParts[0]) {
+		fromParts.shift();
+		toParts.shift();
+	}
+	if (fromParts.length) {
+		let i = fromParts.length;
+		while (i--) fromParts[i] = "..";
+	}
+	return fromParts.concat(toParts).join("/");
+}
+function guessIndent(code) {
+	const lines = code.split("\n");
+	const tabbed = lines.filter((line) => /^\t+/.test(line));
+	const spaced = lines.filter((line) => /^ {2,}/.test(line));
+	if (tabbed.length === 0 && spaced.length === 0) return null;
+	if (tabbed.length >= spaced.length) return "	";
+	const min = spaced.reduce((previous, current) => {
+		const numSpaces = /^ +/.exec(current)[0].length;
+		return Math.min(numSpaces, previous);
+	}, Infinity);
+	return " ".repeat(min);
+}
+var toString = Object.prototype.toString;
+function isObject(thing) {
+	return toString.call(thing) === "[object Object]";
+}
 var wordRegex = /\w/;
 var Mappings = class {
 	constructor(hires) {
@@ -4814,6 +5187,8 @@ var Mappings = class {
 	}
 };
 var n = "\n";
+var NEWLINE_CHAR = "\n".charCodeAt(0);
+var CR_CHAR = "\r".charCodeAt(0);
 var warned = {
 	insertLeft: false,
 	insertRight: false,
@@ -4849,11 +5224,11 @@ var MagicString = class MagicString {
 			},
 			byStart: {
 				writable: true,
-				value: {}
+				value: /* @__PURE__ */ new Map([[0, chunk]])
 			},
 			byEnd: {
 				writable: true,
-				value: {}
+				value: /* @__PURE__ */ new Map([[string.length, chunk]])
 			},
 			filename: {
 				writable: true,
@@ -4884,35 +5259,52 @@ var MagicString = class MagicString {
 				value: options.offset || 0
 			}
 		});
-		this.byStart[0] = chunk;
-		this.byEnd[string.length] = chunk;
 	}
+	/**
+	* Adds the specified character index (with respect to the original string) to sourcemap mappings, if `hires` is false.
+	*/
 	addSourcemapLocation(char) {
 		this.sourcemapLocations.add(char);
 	}
+	/**
+	* Appends the specified content to the end of the string.
+	*/
 	append(content) {
-		if (typeof content !== "string") throw new TypeError("outro content must be a string");
+		if (typeof content !== "string") throw new MagicStringError(`content must be a string, got ${typeof content}`);
 		this.outro += content;
 		return this;
 	}
+	/**
+	* Appends the specified content at the index in the original string.
+	* If a range *ending* with index is subsequently moved, the insert will be moved with it.
+	* See also `s.prependLeft(...)`.
+	*/
 	appendLeft(index, content) {
 		index = index + this.offset;
-		if (typeof content !== "string") throw new TypeError("inserted content must be a string");
+		if (typeof content !== "string") throw new MagicStringError(`content must be a string, got ${typeof content}`);
 		this._split(index);
-		const chunk = this.byEnd[index];
+		const chunk = this.byEnd.get(index);
 		if (chunk) chunk.appendLeft(content);
 		else this.intro += content;
 		return this;
 	}
+	/**
+	* Appends the specified content at the index in the original string.
+	* If a range *starting* with index is subsequently moved, the insert will be moved with it.
+	* See also `s.prependRight(...)`.
+	*/
 	appendRight(index, content) {
 		index = index + this.offset;
-		if (typeof content !== "string") throw new TypeError("inserted content must be a string");
+		if (typeof content !== "string") throw new MagicStringError(`content must be a string, got ${typeof content}`);
 		this._split(index);
-		const chunk = this.byStart[index];
+		const chunk = this.byStart.get(index);
 		if (chunk) chunk.appendRight(content);
 		else this.outro += content;
 		return this;
 	}
+	/**
+	* Does what you'd expect.
+	*/
 	clone() {
 		const cloned = new MagicString(this.original, {
 			filename: this.filename,
@@ -4921,8 +5313,8 @@ var MagicString = class MagicString {
 		let originalChunk = this.firstChunk;
 		let clonedChunk = cloned.firstChunk = cloned.lastSearchedChunk = originalChunk.clone();
 		while (originalChunk) {
-			cloned.byStart[clonedChunk.start] = clonedChunk;
-			cloned.byEnd[clonedChunk.end] = clonedChunk;
+			cloned.byStart.set(clonedChunk.start, clonedChunk);
+			cloned.byEnd.set(clonedChunk.end, clonedChunk);
 			const nextOriginalChunk = originalChunk.next;
 			const nextClonedChunk = nextOriginalChunk && nextOriginalChunk.clone();
 			if (nextClonedChunk) {
@@ -4939,6 +5331,10 @@ var MagicString = class MagicString {
 		cloned.outro = this.outro;
 		return cloned;
 	}
+	/**
+	* Generates a sourcemap object with raw mappings in array form, rather than encoded as a string.
+	* Useful if you need to manipulate the sourcemap further, but most of the time you will use `generateMap` instead.
+	*/
 	generateDecodedMap(options) {
 		options = options || {};
 		const sourceIndex = 0;
@@ -4963,12 +5359,17 @@ var MagicString = class MagicString {
 			x_google_ignoreList: this.ignoreList ? [sourceIndex] : void 0
 		};
 	}
+	/**
+	* Generates a version 3 sourcemap.
+	*/
 	generateMap(options) {
 		return new SourceMap(this.generateDecodedMap(options));
 	}
+	/** @internal */
 	_ensureindentStr() {
 		if (this.indentStr === void 0) this.indentStr = guessIndent(this.original);
 	}
+	/** @internal */
 	_getRawIndentString() {
 		this._ensureindentStr();
 		return this.indentStr;
@@ -4988,6 +5389,7 @@ var MagicString = class MagicString {
 			indentStr = this.indentStr || "	";
 		}
 		if (indentStr === "") return this;
+		const resolvedIndentStr = indentStr;
 		options = options || {};
 		const isExcluded = {};
 		if (options.exclude) (typeof options.exclude[0] === "number" ? [options.exclude] : options.exclude).forEach((exclusion) => {
@@ -4995,13 +5397,22 @@ var MagicString = class MagicString {
 		});
 		let shouldIndentNextCharacter = options.indentStart !== false;
 		const replacer = (match) => {
-			if (shouldIndentNextCharacter) return `${indentStr}${match}`;
+			if (shouldIndentNextCharacter) return `${resolvedIndentStr}${match}`;
 			shouldIndentNextCharacter = true;
 			return match;
 		};
 		this.intro = this.intro.replace(pattern, replacer);
 		let charIndex = 0;
 		let chunk = this.firstChunk;
+		const indentAt = (index) => {
+			shouldIndentNextCharacter = false;
+			if (index === chunk.start) chunk.prependRight(resolvedIndentStr);
+			else {
+				this._splitChunk(chunk, index);
+				chunk = chunk.next;
+				chunk.prependRight(resolvedIndentStr);
+			}
+		};
 		while (chunk) {
 			const end = chunk.end;
 			if (chunk.edited) {
@@ -5009,24 +5420,34 @@ var MagicString = class MagicString {
 					chunk.content = chunk.content.replace(pattern, replacer);
 					if (chunk.content.length) shouldIndentNextCharacter = chunk.content[chunk.content.length - 1] === "\n";
 				}
-			} else {
+			} else if (options.exclude) {
 				charIndex = chunk.start;
 				while (charIndex < end) {
 					if (!isExcluded[charIndex]) {
-						const char = this.original[charIndex];
-						if (char === "\n") shouldIndentNextCharacter = true;
-						else if (char !== "\r" && shouldIndentNextCharacter) {
-							shouldIndentNextCharacter = false;
-							if (charIndex === chunk.start) chunk.prependRight(indentStr);
-							else {
-								this._splitChunk(chunk, charIndex);
-								chunk = chunk.next;
-								chunk.prependRight(indentStr);
-							}
-						}
+						const char = this.original.charCodeAt(charIndex);
+						if (char === NEWLINE_CHAR) shouldIndentNextCharacter = true;
+						else if (char !== CR_CHAR && shouldIndentNextCharacter) indentAt(charIndex);
 					}
 					charIndex += 1;
 				}
+			} else {
+				charIndex = chunk.start;
+				while (charIndex < end) {
+					if (!shouldIndentNextCharacter) {
+						const nextLine = this.original.indexOf(n, charIndex);
+						if (nextLine === -1 || nextLine >= end) break;
+						shouldIndentNextCharacter = true;
+						charIndex = nextLine + 1;
+						continue;
+					}
+					const char = this.original.charCodeAt(charIndex);
+					if (char === NEWLINE_CHAR || char === CR_CHAR) {
+						charIndex += 1;
+						continue;
+					}
+					indentAt(charIndex);
+					charIndex += 1;
+				}
 			}
 			charIndex = chunk.end;
 			chunk = chunk.next;
@@ -5034,9 +5455,11 @@ var MagicString = class MagicString {
 		this.outro = this.outro.replace(pattern, replacer);
 		return this;
 	}
+	/** @internal */
 	insert() {
-		throw new Error("magicString.insert(...) is deprecated. Use prependRight(...) or appendLeft(...)");
+		throw new MagicStringError("insert() is deprecated, use appendLeft() or prependRight()");
 	}
+	/** @internal */
 	insertLeft(index, content) {
 		if (!warned.insertLeft) {
 			console.warn("magicString.insertLeft(...) is deprecated. Use magicString.appendLeft(...) instead");
@@ -5044,6 +5467,7 @@ var MagicString = class MagicString {
 		}
 		return this.appendLeft(index, content);
 	}
+	/** @internal */
 	insertRight(index, content) {
 		if (!warned.insertRight) {
 			console.warn("magicString.insertRight(...) is deprecated. Use magicString.prependRight(...) instead");
@@ -5051,19 +5475,23 @@ var MagicString = class MagicString {
 		}
 		return this.prependRight(index, content);
 	}
+	/**
+	* Moves the characters from `start` and `end` to `index`.
+	*/
 	move(start, end, index) {
 		start = start + this.offset;
 		end = end + this.offset;
 		index = index + this.offset;
-		if (index >= start && index <= end) throw new Error("Cannot move a selection inside itself");
+		if (start === end) return this;
+		if (index >= start && index <= end) throw new MagicStringError("cannot move a selection inside itself");
 		this._split(start);
 		this._split(end);
 		this._split(index);
-		const first = this.byStart[start];
-		const last = this.byEnd[end];
+		const first = this.byStart.get(start);
+		const last = this.byEnd.get(end);
 		const oldLeft = first.previous;
 		const oldRight = last.next;
-		const newRight = this.byStart[index];
+		const newRight = this.byStart.get(index);
 		if (!newRight && last === this.lastChunk) return this;
 		const newLeft = newRight ? newRight.previous : this.lastChunk;
 		if (oldLeft) oldLeft.next = oldRight;
@@ -5081,23 +5509,42 @@ var MagicString = class MagicString {
 		if (!newRight) this.lastChunk = last;
 		return this;
 	}
+	/**
+	* Replaces the characters from `start` to `end` with `content`, along with the appended/prepended content in
+	* that range. The same restrictions as `s.remove()` apply.
+	*
+	* The fourth argument is optional. It can have a storeName property - if true, the original name will be stored
+	* for later inclusion in a sourcemap's names array - and a contentOnly property which determines whether only
+	* the content is overwritten, or anything that was appended/prepended to the range as well.
+	*
+	* It may be preferred to use `s.update(...)` instead if you wish to avoid overwriting the appended/prepended content.
+	*/
 	overwrite(start, end, content, options) {
-		options = options || {};
+		const optionObject = typeof options === "object" && options ? options : {};
 		return this.update(start, end, content, {
-			...options,
-			overwrite: !options.contentOnly
+			...optionObject,
+			overwrite: !optionObject.contentOnly
 		});
 	}
+	/**
+	* Replaces the characters from `start` to `end` with `content`. The same restrictions as `s.remove()` apply.
+	*
+	* The fourth argument is optional. It can have a storeName property - if true, the original name will be stored
+	* for later inclusion in a sourcemap's names array - and an overwrite property which determines whether only
+	* the content is overwritten, or anything that was appended/prepended to the range as well.
+	*/
 	update(start, end, content, options) {
 		start = start + this.offset;
 		end = end + this.offset;
-		if (typeof content !== "string") throw new TypeError("replacement content must be a string");
+		if (typeof content !== "string") throw new MagicStringError(`content must be a string, got ${typeof content}`);
 		if (this.original.length !== 0) {
 			while (start < 0) start += this.original.length;
 			while (end < 0) end += this.original.length;
 		}
-		if (end > this.original.length) throw new Error("end is out of bounds");
-		if (start === end) throw new Error("Cannot overwrite a zero-length range – use appendLeft or prependRight instead");
+		if (start < 0) throw new MagicStringError(`start ${start} is out of bounds`);
+		if (end > this.original.length) throw new MagicStringError(`end ${end} is out of bounds`);
+		if (start === end) throw new MagicStringError(`cannot overwrite a zero-length range at ${start}, use appendLeft() or prependRight()`);
+		if (start > end) throw new MagicStringError(`end must be greater than start (start: ${start}, end: ${end})`);
 		this._split(start);
 		this._split(end);
 		if (options === true) {
@@ -5107,8 +5554,9 @@ var MagicString = class MagicString {
 			}
 			options = { storeName: true };
 		}
-		const storeName = options !== void 0 ? options.storeName : false;
-		const overwrite = options !== void 0 ? options.overwrite : false;
+		const optionObject = typeof options === "object" && options ? options : {};
+		const storeName = optionObject.storeName || false;
+		const overwrite = optionObject.overwrite || false;
 		if (storeName) {
 			const original = this.original.slice(start, end);
 			Object.defineProperty(this.storedNames, original, {
@@ -5117,12 +5565,12 @@ var MagicString = class MagicString {
 				enumerable: true
 			});
 		}
-		const first = this.byStart[start];
-		const last = this.byEnd[end];
+		const first = this.byStart.get(start);
+		const last = this.byEnd.get(end);
 		if (first) {
 			let chunk = first;
 			while (chunk !== last) {
-				if (chunk.next !== this.byStart[chunk.end]) throw new Error("Cannot overwrite across a split point");
+				if (chunk.next !== this.byStart.get(chunk.end)) throw new MagicStringError("cannot overwrite across a split point");
 				chunk = chunk.next;
 				chunk.edit("", false);
 			}
@@ -5134,29 +5582,42 @@ var MagicString = class MagicString {
 		}
 		return this;
 	}
+	/**
+	* Prepends the string with the specified content.
+	*/
 	prepend(content) {
-		if (typeof content !== "string") throw new TypeError("outro content must be a string");
+		if (typeof content !== "string") throw new MagicStringError(`content must be a string, got ${typeof content}`);
 		this.intro = content + this.intro;
 		return this;
 	}
+	/**
+	* Same as `s.appendLeft(...)`, except that the inserted content will go *before* any previous appends or prepends at index
+	*/
 	prependLeft(index, content) {
 		index = index + this.offset;
-		if (typeof content !== "string") throw new TypeError("inserted content must be a string");
+		if (typeof content !== "string") throw new MagicStringError(`content must be a string, got ${typeof content}`);
 		this._split(index);
-		const chunk = this.byEnd[index];
+		const chunk = this.byEnd.get(index);
 		if (chunk) chunk.prependLeft(content);
 		else this.intro = content + this.intro;
 		return this;
 	}
+	/**
+	* Same as `s.appendRight(...)`, except that the inserted content will go *before* any previous appends or prepends at `index`
+	*/
 	prependRight(index, content) {
 		index = index + this.offset;
-		if (typeof content !== "string") throw new TypeError("inserted content must be a string");
+		if (typeof content !== "string") throw new MagicStringError(`content must be a string, got ${typeof content}`);
 		this._split(index);
-		const chunk = this.byStart[index];
+		const chunk = this.byStart.get(index);
 		if (chunk) chunk.prependRight(content);
 		else this.outro = content + this.outro;
 		return this;
 	}
+	/**
+	* Removes the characters from `start` to `end` (of the original string, **not** the generated string).
+	* Removing the same content twice, or making removals that partially overlap, will cause an error.
+	*/
 	remove(start, end) {
 		start = start + this.offset;
 		end = end + this.offset;
@@ -5165,19 +5626,22 @@ var MagicString = class MagicString {
 			while (end < 0) end += this.original.length;
 		}
 		if (start === end) return this;
-		if (start < 0 || end > this.original.length) throw new Error("Character is out of bounds");
-		if (start > end) throw new Error("end must be greater than start");
+		if (start < 0 || end > this.original.length) throw new MagicStringError(`range ${start}–${end} is out of bounds`);
+		if (start > end) throw new MagicStringError(`end must be greater than start (start: ${start}, end: ${end})`);
 		this._split(start);
 		this._split(end);
-		let chunk = this.byStart[start];
+		let chunk = this.byStart.get(start);
 		while (chunk) {
 			chunk.intro = "";
 			chunk.outro = "";
 			chunk.edit("");
-			chunk = end > chunk.end ? this.byStart[chunk.end] : null;
+			chunk = end > chunk.end ? this.byStart.get(chunk.end) : null;
 		}
 		return this;
 	}
+	/**
+	* Reset the modified characters from `start` to `end` (of the original string, **not** the generated string).
+	*/
 	reset(start, end) {
 		start = start + this.offset;
 		end = end + this.offset;
@@ -5186,25 +5650,26 @@ var MagicString = class MagicString {
 			while (end < 0) end += this.original.length;
 		}
 		if (start === end) return this;
-		if (start < 0 || end > this.original.length) throw new Error("Character is out of bounds");
-		if (start > end) throw new Error("end must be greater than start");
+		if (start < 0 || end > this.original.length) throw new MagicStringError(`range ${start}–${end} is out of bounds`);
+		if (start > end) throw new MagicStringError(`end must be greater than start (start: ${start}, end: ${end})`);
 		this._split(start);
 		this._split(end);
-		let chunk = this.byStart[start];
+		let chunk = this.byStart.get(start);
 		while (chunk) {
 			chunk.reset();
-			chunk = end > chunk.end ? this.byStart[chunk.end] : null;
+			chunk = end > chunk.end ? this.byStart.get(chunk.end) : null;
 		}
 		return this;
 	}
 	lastChar() {
 		if (this.outro.length) return this.outro[this.outro.length - 1];
 		let chunk = this.lastChunk;
-		do {
+		while (chunk) {
 			if (chunk.outro.length) return chunk.outro[chunk.outro.length - 1];
 			if (chunk.content.length) return chunk.content[chunk.content.length - 1];
 			if (chunk.intro.length) return chunk.intro[chunk.intro.length - 1];
-		} while (chunk = chunk.previous);
+			chunk = chunk.previous;
+		}
 		if (this.intro.length) return this.intro[this.intro.length - 1];
 		return "";
 	}
@@ -5213,7 +5678,7 @@ var MagicString = class MagicString {
 		if (lineIndex !== -1) return this.outro.substr(lineIndex + 1);
 		let lineStr = this.outro;
 		let chunk = this.lastChunk;
-		do {
+		while (chunk) {
 			if (chunk.outro.length > 0) {
 				lineIndex = chunk.outro.lastIndexOf(n);
 				if (lineIndex !== -1) return chunk.outro.substr(lineIndex + 1) + lineStr;
@@ -5229,11 +5694,16 @@ var MagicString = class MagicString {
 				if (lineIndex !== -1) return chunk.intro.substr(lineIndex + 1) + lineStr;
 				lineStr = chunk.intro + lineStr;
 			}
-		} while (chunk = chunk.previous);
+			chunk = chunk.previous;
+		}
 		lineIndex = this.intro.lastIndexOf(n);
 		if (lineIndex !== -1) return this.intro.substr(lineIndex + 1) + lineStr;
 		return this.intro + lineStr;
 	}
+	/**
+	* Returns the content of the generated string that corresponds to the slice between `start` and `end` of the original string.
+	* Throws error if the indices are for characters that were already removed.
+	*/
 	slice(start = 0, end = this.original.length - this.offset) {
 		start = start + this.offset;
 		end = end + this.offset;
@@ -5247,12 +5717,12 @@ var MagicString = class MagicString {
 			if (chunk.start < end && chunk.end >= end) return result;
 			chunk = chunk.next;
 		}
-		if (chunk && chunk.edited && chunk.start !== start) throw new Error(`Cannot use replaced character ${start} as slice start anchor.`);
+		if (chunk && chunk.edited && chunk.start !== start) throw new MagicStringError(`cannot use edited character ${start} as slice start anchor`);
 		const startChunk = chunk;
 		while (chunk) {
 			if (chunk.intro && (startChunk !== chunk || chunk.start === start)) result += chunk.intro;
 			const containsEnd = chunk.start < end && chunk.end >= end;
-			if (containsEnd && chunk.edited && chunk.end !== end) throw new Error(`Cannot use replaced character ${end} as slice end anchor.`);
+			if (containsEnd && chunk.edited && chunk.end !== end) throw new MagicStringError(`cannot use edited character ${end} as slice end anchor`);
 			const sliceStart = startChunk === chunk ? start - chunk.start : 0;
 			const sliceEnd = containsEnd ? chunk.content.length + end - chunk.end : chunk.content.length;
 			result += chunk.content.slice(sliceStart, sliceEnd);
@@ -5262,37 +5732,45 @@ var MagicString = class MagicString {
 		}
 		return result;
 	}
+	/**
+	* Returns a clone of `s`, with all content before the `start` and `end` characters of the original string removed.
+	*/
 	snip(start, end) {
 		const clone = this.clone();
 		clone.remove(0, start);
 		clone.remove(end, clone.original.length);
 		return clone;
 	}
+	/** @internal */
 	_split(index) {
-		if (this.byStart[index] || this.byEnd[index]) return;
+		if (this.byStart.get(index) || this.byEnd.get(index)) return;
 		let chunk = this.lastSearchedChunk;
 		let previousChunk = chunk;
 		const searchForward = index > chunk.end;
 		while (chunk) {
 			if (chunk.contains(index)) return this._splitChunk(chunk, index);
-			chunk = searchForward ? this.byStart[chunk.end] : this.byEnd[chunk.start];
+			chunk = searchForward ? this.byStart.get(chunk.end) : this.byEnd.get(chunk.start);
 			if (chunk === previousChunk) return;
 			previousChunk = chunk;
 		}
 	}
+	/** @internal */
 	_splitChunk(chunk, index) {
 		if (chunk.edited && chunk.content.length) {
 			const loc = getLocator(this.original)(index);
-			throw new Error(`Cannot split a chunk that has already been edited (${loc.line}:${loc.column} – "${chunk.original}")`);
+			throw new MagicStringError(`cannot split a chunk that has already been edited (${loc.line}:${loc.column} – "${chunk.original}")`);
 		}
 		const newChunk = chunk.split(index);
-		this.byEnd[index] = chunk;
-		this.byStart[index] = newChunk;
-		this.byEnd[newChunk.end] = newChunk;
+		this.byEnd.set(index, chunk);
+		this.byStart.set(index, newChunk);
+		this.byEnd.set(newChunk.end, newChunk);
 		if (chunk === this.lastChunk) this.lastChunk = newChunk;
 		this.lastSearchedChunk = chunk;
 		return true;
 	}
+	/**
+	* Returns the generated string.
+	*/
 	toString() {
 		let str = this.intro;
 		let chunk = this.firstChunk;
@@ -5302,29 +5780,41 @@ var MagicString = class MagicString {
 		}
 		return str + this.outro;
 	}
+	/**
+	* Returns true if the resulting source is empty (disregarding white space).
+	*/
 	isEmpty() {
 		let chunk = this.firstChunk;
-		do
+		while (chunk) {
 			if (chunk.intro.length && chunk.intro.trim() || chunk.content.length && chunk.content.trim() || chunk.outro.length && chunk.outro.trim()) return false;
-		while (chunk = chunk.next);
+			chunk = chunk.next;
+		}
 		return true;
 	}
 	length() {
 		let chunk = this.firstChunk;
 		let length = 0;
-		do
+		while (chunk) {
 			length += chunk.intro.length + chunk.content.length + chunk.outro.length;
-		while (chunk = chunk.next);
+			chunk = chunk.next;
+		}
 		return length;
 	}
+	/**
+	* Removes empty lines from the start and end.
+	*/
 	trimLines() {
 		return this.trim("[\\r\\n]");
 	}
+	/**
+	* Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the start and end.
+	*/
 	trim(charType) {
 		return this.trimStart(charType).trimEnd(charType);
 	}
+	/** @internal */
 	trimEndAborted(charType) {
-		const rx = new RegExp((charType || "\\s") + "+$");
+		const rx = new RegExp(`${charType || "\\s"}+$`);
 		this.outro = this.outro.replace(rx, "");
 		if (this.outro.length) return true;
 		let chunk = this.lastChunk;
@@ -5333,21 +5823,25 @@ var MagicString = class MagicString {
 			const aborted = chunk.trimEnd(rx);
 			if (chunk.end !== end) {
 				if (this.lastChunk === chunk) this.lastChunk = chunk.next;
-				this.byEnd[chunk.end] = chunk;
-				this.byStart[chunk.next.start] = chunk.next;
-				this.byEnd[chunk.next.end] = chunk.next;
+				this.byEnd.set(chunk.end, chunk);
+				this.byStart.set(chunk.next.start, chunk.next);
+				this.byEnd.set(chunk.next.end, chunk.next);
 			}
 			if (aborted) return true;
 			chunk = chunk.previous;
 		} while (chunk);
 		return false;
 	}
+	/**
+	* Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the end.
+	*/
 	trimEnd(charType) {
 		this.trimEndAborted(charType);
 		return this;
 	}
+	/** @internal */
 	trimStartAborted(charType) {
-		const rx = new RegExp("^" + (charType || "\\s") + "+");
+		const rx = new RegExp(`^${charType || "\\s"}+`);
 		this.intro = this.intro.replace(rx, "");
 		if (this.intro.length) return true;
 		let chunk = this.firstChunk;
@@ -5356,22 +5850,29 @@ var MagicString = class MagicString {
 			const aborted = chunk.trimStart(rx);
 			if (chunk.end !== end) {
 				if (chunk === this.lastChunk) this.lastChunk = chunk.next;
-				this.byEnd[chunk.end] = chunk;
-				this.byStart[chunk.next.start] = chunk.next;
-				this.byEnd[chunk.next.end] = chunk.next;
+				this.byEnd.set(chunk.end, chunk);
+				this.byStart.set(chunk.next.start, chunk.next);
+				this.byEnd.set(chunk.next.end, chunk.next);
 			}
 			if (aborted) return true;
 			chunk = chunk.next;
 		} while (chunk);
 		return false;
 	}
+	/**
+	* Trims content matching `charType` (defaults to `\s`, i.e. whitespace) from the start.
+	*/
 	trimStart(charType) {
 		this.trimStartAborted(charType);
 		return this;
 	}
+	/**
+	* Indicates if the string has been changed.
+	*/
 	hasChanged() {
 		return this.original !== this.toString();
 	}
+	/** @internal */
 	_replaceRegexp(searchValue, replacement) {
 		function getReplacement(match, str) {
 			if (typeof replacement === "string") return replacement.replace(/\$(\$|&|\d+)/g, (_, i) => {
@@ -5380,12 +5881,15 @@ var MagicString = class MagicString {
 				if (+i < match.length) return match[+i];
 				return `$${i}`;
 			});
-			else return replacement(...match, match.index, str, match.groups);
+			else return replacement(match[0], ...match.slice(1), match.index, str, match.groups);
 		}
 		function matchAll(re, str) {
-			let match;
 			const matches = [];
-			while (match = re.exec(str)) matches.push(match);
+			while (true) {
+				const match = re.exec(str);
+				if (!match) break;
+				matches.push(match);
+			}
 			return matches;
 		}
 		if (searchValue.global) matchAll(searchValue, this.original).forEach((match) => {
@@ -5403,6 +5907,7 @@ var MagicString = class MagicString {
 		}
 		return this;
 	}
+	/** @internal */
 	_replaceString(string, replacement) {
 		const { original } = this;
 		const index = original.indexOf(string);
@@ -5412,24 +5917,30 @@ var MagicString = class MagicString {
 		}
 		return this;
 	}
+	/**
+	* String replacement with RegExp or string.
+	*/
 	replace(searchValue, replacement) {
 		if (typeof searchValue === "string") return this._replaceString(searchValue, replacement);
 		return this._replaceRegexp(searchValue, replacement);
 	}
+	/** @internal */
 	_replaceAllString(string, replacement) {
 		const { original } = this;
 		const stringLength = string.length;
 		for (let index = original.indexOf(string); index !== -1; index = original.indexOf(string, index + stringLength)) {
 			const previous = original.slice(index, index + stringLength);
-			let _replacement = replacement;
-			if (typeof replacement === "function") _replacement = replacement(previous, index, original);
+			const _replacement = typeof replacement === "function" ? replacement(previous, index, original) : replacement;
 			if (previous !== _replacement) this.overwrite(index, index + stringLength, _replacement);
 		}
 		return this;
 	}
+	/**
+	* Same as `s.replace`, but replace all matched strings instead of just one.
+	*/
 	replaceAll(searchValue, replacement) {
 		if (typeof searchValue === "string") return this._replaceAllString(searchValue, replacement);
-		if (!searchValue.global) throw new TypeError("MagicString.prototype.replaceAll called with a non-global RegExp argument");
+		if (!searchValue.global) throw new MagicStringError("replaceAll() requires a global RegExp");
 		return this._replaceRegexp(searchValue, replacement);
 	}
 };
@@ -5830,6 +6341,7 @@ function timberFonts(ctx) {
 			if (pipeline.cssIdMap.matches(id)) {
 				const importer = pipeline.cssIdMap.importerFor(id);
 				if (!importer) return "";
+				if (process.env.TIMBER_ANALYZE === "1") return "";
 				const skipFonts = process.env.TIMBER_SKIP_FONTS === "1";
 				for (const font of pipeline.googleFonts()) {
 					if (font.importer !== importer) continue;
@@ -7337,8 +7849,10 @@ function lookupFacades(id, sharedModuleFacades) {
 	if (!isBareSpecifier(id)) return void 0;
 	const needle = `/node_modules/${id}/`;
 	let merged;
-	for (const [key, facades] of sharedModuleFacades) if (key.includes(needle)) if (!merged) merged = [...facades];
-	else merged.push(...facades);
+	for (const [key, facades] of sharedModuleFacades) if (key.includes(needle)) {
+		if (!merged) merged = [...facades];
+		else merged.push(...facades);
+	}
 	return merged;
 }
 /**
@@ -7413,6 +7927,7 @@ function clientChunkGroup(meta, appDir, root, sharedModuleFacades) {
 *
 * Design docs: design/11-platform.md, design/25-production-deployments.md
 */
+var POISON_MARKER_SPECIFIERS = EXPLICIT_MARKERS.map((m) => m.specifier);
 var NODE_BUILTINS = builtinModules.flatMap((m) => [m, `node:${m}`]);
 var CLOUDFLARE_BUILTINS = [
 	"cloudflare:workers",
@@ -7426,7 +7941,8 @@ var BUILD_ONLY_EXTERNALS = [
 	"vite",
 	"nitro",
 	"rollup",
-	"@mdx-js/rollup",
+	"vite-plugin-satteri",
+	"satteri",
 	"fsevents",
 	"chokidar"
 ];
@@ -7436,12 +7952,8 @@ function timberServerBundle() {
 			name: "timber-server-bundle",
 			config(_cfg, { command }) {
 				if (command === "serve") return { environments: {
-					rsc: { resolve: { noExternal: ["server-only", "client-only"] } },
-					ssr: { resolve: { noExternal: [
-						"server-only",
-						"client-only",
-						"nuqs"
-					] } }
+					rsc: { resolve: { noExternal: [...POISON_MARKER_SPECIFIERS] } },
+					ssr: { resolve: { noExternal: [...POISON_MARKER_SPECIFIERS, "nuqs"] } }
 				} };
 				const serverDefine = { "process.env.NODE_ENV": JSON.stringify("production") };
 				return {
@@ -7569,9 +8081,7 @@ function collectPatternNames(node, out) {
 			for (const prop of node.properties ?? []) if (prop.type === "RestElement") collectPatternNames(prop, out);
 			else collectPatternNames(prop.value, out);
 			break;
-		case "TSParameterProperty":
-			if (node.parameter) collectPatternNames(node.parameter, out);
-			break;
+		case "TSParameterProperty": if (node.parameter) collectPatternNames(node.parameter, out);
 	}
 }
 /** Return the intersection of param names with `tracked`, or null if none. */
@@ -7943,7 +8453,8 @@ function timberCacheTransform(ctx) {
 			}
 			if (callSites.length === 0) return;
 			callSites.sort((a, b) => a.call.start - b.call.start);
-			const relPath = relative(ctx.root || process.cwd(), id);
+			const root = ctx.root || process.cwd();
+			const relPath = relative(root, id);
 			const s = new MagicString(code);
 			const occurrences = /* @__PURE__ */ new Map();
 			for (const { call, stmt } of callSites) {
@@ -8268,9 +8779,7 @@ function analyzeModule(program) {
 		case "ExportAllDeclaration":
 			collectExportAll(stmt, facts);
 			break;
-		case "ExportDefaultDeclaration":
-			collectExportDefault(stmt, facts);
-			break;
+		case "ExportDefaultDeclaration": collectExportDefault(stmt, facts);
 	}
 	walk(program, facts);
 	return facts;
@@ -9351,7 +9860,8 @@ function timberPrebuilt(ctx) {
 			if (bindings.named.size === 0 && bindings.namespaces.size === 0) return;
 			const callSites = collectModuleScopeSites(program, bindings);
 			if (callSites.length === 0) return;
-			const relPath = relative(ctx.root || process.cwd(), id);
+			const root = ctx.root || process.cwd();
+			const relPath = relative(root, id);
 			const s = new MagicString(code);
 			const occurrences = /* @__PURE__ */ new Map();
 			const wrapperName = ctx.dev ? "__prebuiltDev" : "__prebuilt";
@@ -9511,27 +10021,24 @@ function timberPrebuilt(ctx) {
 * `export const prerender` to descendant pages via most-specific-wins:
 * walk the segment tree from leaf to root, first explicit value wins.
 *
-* A layout that declares `export const prerender` is ALSO wrapped — the
-* layout's flight payload is its own static shell (`children` is a
-* separate component boundary), so caching it is natural (nav, sidebar,
-* footer benefit from build-time rendering). See design/45 §Layout
-* Propagation.
+* Layout declarations are propagation policy only. Layouts receive the real
+* descendant React element as `children` to preserve the server-layout
+* containment boundary, so their props are not cache-keyable and the layout
+* itself must not be registered for capture.
 *
 * This transform runs BEFORE timber-prebuilt so the generated
 * `cache.component(...)` call is picked up by the callsite rewrite.
 */
 /**
 * Walk the segment tree and resolve the effective prerender value for
-* every page and layout. Returns a map from file path to resolved value.
+* every page. Returns a map from page file path to resolved value.
 *
 * **Pages:** walk from leaf toward root; first explicit `export const prerender`
 * wins (page > nearest layout > ... > root layout). If none, dynamic.
 *
-* **Layouts:** a layout that declares `export const prerender` is wrapped
-* directly (its own shell is a separate component boundary from `children`).
-* Layouts without their own declaration are NOT wrapped — they don't
-* inherit from ancestors, because wrapping a layout's shell without the
-* author's explicit opt-in would cache content they may expect to be dynamic.
+* **Layouts:** declarations propagate to descendant pages but layouts are not
+* included in the result. Their real React-element `children` preserve secure
+* containment and deliberately make child-independent layout caching invalid.
 */
 function resolvePagePrerender(root) {
 	const result = /* @__PURE__ */ new Map();
@@ -9539,7 +10046,6 @@ function resolvePagePrerender(root) {
 		if (node.segmentType === "intercepting" || node.segmentType === "private") return;
 		const layoutValue = node.layout ? getPrerenderExport(node.layout.filePath) : void 0;
 		const stack = layoutValue !== void 0 ? [layoutValue, ...ancestorStack] : ancestorStack;
-		if (node.layout && layoutValue !== void 0 && layoutValue !== false) result.set(node.layout.filePath, layoutValue);
 		if (node.page) {
 			const pageValue = getPrerenderExport(node.page.filePath);
 			const resolved = pageValue !== void 0 ? pageValue : stack[0];
@@ -10622,7 +11128,8 @@ function timber(config) {
 			}
 			let resolvedDevPort = null;
 			let resolvedDevPortExplicit = false;
-			if (command === "serve" && !isPreview) {
+			const isMiddlewareMode = Boolean(userConfig.server?.middlewareMode);
+			if (command === "serve" && !isPreview && !isMiddlewareMode) {
 				ctx.holdingServer = createHoldingServer();
 				const holdingRef = ctx.holdingServer;
 				const result = await startDevServerPort({
@@ -10703,7 +11210,6 @@ function timber(config) {
 			ctx.buildDir = resolve(resolved.root, resolved.build.outDir);
 			if (!ctx.dev) ctx.timer = createNoopTimer();
 			else ctx.timer.start("dev-server-setup");
-			const { validateConfig, formatConfigErrors, checkPeerDependencies, formatMissingPeers } = (init_config_validation(), __toCommonJS(config_validation_exports));
 			const configErrors = validateConfig(ctx.config);
 			if (configErrors.length > 0) process.stderr.write(`${formatConfigErrors(configErrors)}\n\n`);
 			const peerWarning = formatMissingPeers(checkPeerDependencies(ctx.root));