@timber-js/app 0.2.0-alpha.147 → 0.2.0-alpha.149

package/dist/index.js

@@ -1,11 +1,12 @@
-import { n as setViteServer } from "./_chunks/warnings-CNPXaypM.js";
-import { a as isDynamicMetadataExtension, o as isMetadataRouteServePath } from "./_chunks/metadata-routes-BjepjefT.js";
-import { h as swallow } from "./_chunks/logger-Dt-jQaBO.js";
-import { c as loadTimberConfigFile, d as resolveBuildDir, f as resolveClientJavascript, l as mergeFileConfig, m as scanRoutes, o as DEFAULT_BUILD_DIR, p as createNoopTimer, s as createPluginContext, u as resolveAppDir } from "./_chunks/cli-schema-sync-CQaxupHv.js";
-import { a as generateRouteMap, i as collectInterceptionRewrites, r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "./_chunks/walkers-Ck4Y45XN.js";
+import { c as isDynamicMetadataExtension, l as isMetadataRouteServePath, r as canonicalize } from "./_chunks/canonicalize-P41GR6tY.js";
+import { t as matchUrlParts } from "./_chunks/tree-match-D2l830j2.js";
+import { h as swallow } from "./_chunks/logger-CM0clugc.js";
+import { s as scanRoutes } from "./_chunks/cli-schema-sync-DJDdyEae.js";
+import { a as generateRouteMap, i as validateSchemaAgainstRoutes, n as collectInterceptionRewrites, o as readFileCached, t as collectLeafRoutes } from "./_chunks/walkers-DvWDj453.js";
+import { a as mergeFileConfig, c as resolveClientJavascript, i as loadTimberConfigFile, o as resolveAppDir, r as createPluginContext, s as resolveBuildDir, u as createNoopTimer } from "./_chunks/plugin-context-GfDWsdd2.js";
 import { t as fnv1aHash } from "./_chunks/fast-hash-D6hIVt1Y.js";
 import { t as formatSize } from "./_chunks/format-CfwjgPz9.js";
-import { basename, dirname, extname, join, normalize, relative, resolve } from "node:path";
+import { basename, dirname, extname, join, normalize, relative, resolve, win32 } from "node:path";
 import { builtinModules, createRequire } from "node:module";
 import react, { reactCompilerPreset } from "@vitejs/plugin-react";
 import { existsSync, readFileSync } from "node:fs";
@@ -616,7 +617,7 @@ function extractHmrOptions(config) {
 	const opts = {
 		protocol: hmrOpts.protocol,
 		host: hmrOpts.host,
-		port: hmrOpts.port,
+		port: hmrOpts.clientPort || hmrOpts.port,
 		path: hmrOpts.path,
 		token: config.webSocketToken
 	};
@@ -1152,29 +1153,6 @@ function validateConfig(config) {
 			value: config.sitemap.defaultPriority
 		});
 	}
-	const knownKeys = new Set([
-		"output",
-		"debug",
-		"clientJavascript",
-		"adapter",
-		"cacheHandler",
-		"allowedOrigins",
-		"csrf",
-		"limits",
-		"pageExtensions",
-		"slowRequestMs",
-		"renderTimeoutMs",
-		"devBrowserLogs",
-		"dev",
-		"serverTiming",
-		"appDir",
-		"mdx",
-		"actionEncryption",
-		"reactCompiler",
-		"sitemap",
-		"buildDir",
-		"topLoader"
-	]);
 	for (const key of Object.keys(config)) if (!knownKeys.has(key)) errors.push({
 		field: key,
 		message: `Unknown config option: "${key}".`,
@@ -1245,8 +1223,33 @@ function formatMissingPeers(results) {
 	lines.push(`  ${BOLD$1}pnpm add ${names.join(" ")}${RESET$1}`);
 	return lines.join("\n");
 }
-var RED$1, BOLD$1, DIM$1, RESET$1, VIRTUAL_MODULE_NAMES, REQUIRED_PEERS;
+var knownKeys, RED$1, BOLD$1, DIM$1, RESET$1, VIRTUAL_MODULE_NAMES, REQUIRED_PEERS;
 var init_config_validation = __esmMin((() => {
+	knownKeys = new Set(Object.keys({
+		output: true,
+		debug: true,
+		clientJavascript: true,
+		adapter: true,
+		cacheHandler: true,
+		allowedOrigins: true,
+		csrf: true,
+		limits: true,
+		actions: 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,
+		topLoader: true
+	}));
 	RED$1 = "\x1B[31m";
 	BOLD$1 = "\x1B[1m";
 	DIM$1 = "\x1B[2m";
@@ -1433,9 +1436,8 @@ function timberDevServer(ctx) {
 		configureServer(server) {
 			const configPaths = CONFIG_FILE_NAMES.map((name) => join(ctx.root, name));
 			server.watcher.add(configPaths);
-			setViteServer(server);
 			listenForClientErrors(server, ctx.root);
-			server.middlewares.use(createTimberMiddleware(server, ctx.root));
+			server.middlewares.use(createTimberMiddleware(server, ctx));
 			if (ctx.holdingServer) {
 				const originalListen = server.listen.bind(server);
 				const holdingRef = ctx.holdingServer;
@@ -1463,7 +1465,8 @@ function timberDevServer(ctx) {
 * For non-route requests (assets, Vite internals, HMR), the middleware
 * calls next() to let Vite handle them.
 */
-function createTimberMiddleware(server, projectRoot) {
+function createTimberMiddleware(server, ctx) {
+	const projectRoot = ctx.root;
 	const hmrOptions = extractHmrOptions(server.config);
 	return async (req, res, next) => {
 		const url = req.url;
@@ -1475,7 +1478,7 @@ function createTimberMiddleware(server, projectRoot) {
 			next();
 			return;
 		}
-		if (isAssetRequest(url) && !isMetadataRouteServePath(url)) {
+		if (isAssetRequest(url) && !isMetadataRouteServePath(url) && !isRouteOwnedAsset(ctx.routeTree, server, url)) {
 			next();
 			return;
 		}
@@ -1658,6 +1661,40 @@ function isAssetRequest(url) {
 	return ASSET_EXTENSIONS.test(url);
 }
 /**
+* Check whether an asset-extension URL belongs to a scanned route rather
+* than a static file.
+*
+* Route handlers may live at paths ending in asset-like extensions
+* (app/feed.json/route.ts → /feed.json), which the asset bypass would
+* otherwise hand to Vite — 404ing in dev while working in production.
+* Uses the same canonicalization and tree walker as the runtime matcher
+* so dev classification agrees with what the pipeline would match.
+*
+* A file that actually exists on disk wins over the route match: the
+* production server serves public/ statics before the RSC handler (see
+* adapters/nitro.ts), and Vite serves root-relative source files (e.g.
+* /app/global.css) in dev. Without this, a broad catch-all route like
+* app/[...slug] would shadow every static asset. Joining the canonical
+* pathname is traversal-safe — canonicalize() resolves `..` segments and
+* rejects root escapes and encoded separators.
+*
+* Reads ctx.routeTree per request — the routing plugin rescans it on
+* file add/unlink/change, so newly created routes are picked up live.
+*/
+function isRouteOwnedAsset(routeTree, server, url) {
+	if (!routeTree) return false;
+	const rawPathname = url.split("?")[0];
+	const result = canonicalize(rawPathname);
+	if (!result.ok) return false;
+	const parts = result.pathname === "/" ? [] : result.pathname.slice(1).split("/");
+	if (matchUrlParts(routeTree.root, parts) === null) return false;
+	const relativePath = result.pathname.slice(1);
+	const { publicDir, root } = server.config;
+	if (publicDir && existsSync(join(publicDir, relativePath))) return false;
+	if (existsSync(join(root, relativePath))) return false;
+	return true;
+}
+/**
 * Listen for client-side errors forwarded from the browser via HMR.
 *
 * The browser entry catches uncaught errors and unhandled rejections,
@@ -2132,6 +2169,208 @@ async function writeSegmentTypes(routeTree, appDir, root) {
 	await Promise.all(writes);
 }
 //#endregion
+//#region src/routing/manifest-codegen.ts
+/**
+* Route manifest codegen — generates virtual module source for the route
+* manifest, search-params registry, and global schema.
+*
+* Extracted from plugins/routing.ts to keep it under the 500-line budget.
+* See design/18-build-system.md §"Virtual Modules".
+*
+* Task: TIM-1071 item 8
+*/
+var SINGLE_FILE_KEYS = [
+	"page",
+	"layout",
+	"middleware",
+	"access",
+	"route",
+	"error",
+	"default",
+	"denied",
+	"params"
+];
+var RECORD_FILE_KEYS = [
+	"statusFiles",
+	"jsonStatusFiles",
+	"legacyStatusFiles",
+	"metadataRoutes"
+];
+var SCHEMA_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx"
+];
+/**
+* Generate the virtual module source for the route manifest.
+*
+* The output is a default-exported object containing the serialized route tree.
+* All file references use absolute paths (required for virtual modules).
+*/
+function generateManifestModule(tree, viteRoot) {
+	const imports = [];
+	let importIndex = 0;
+	function addImport(file) {
+		const varName = `_route${importIndex++}`;
+		imports.push(`const ${varName} = () => import("${file.filePath}");`);
+		return varName;
+	}
+	function serializeRouteFile(key, file, indent) {
+		return `${indent}${key}: { load: ${addImport(file)}, filePath: ${JSON.stringify(file.filePath)} },`;
+	}
+	function serializeRouteFileRecord(key, record, indent) {
+		const entries = Object.entries(record);
+		if (entries.length === 0) return null;
+		return `${indent}${key}: {\n${entries.map(([name, file]) => {
+			const v = addImport(file);
+			return `${indent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`;
+		}).join(",\n")}\n${indent}},`;
+	}
+	function serializeNode(node, indent) {
+		const nextIndent = indent + "  ";
+		const parts = [];
+		parts.push(`${nextIndent}segmentName: ${JSON.stringify(node.segmentName)},`);
+		parts.push(`${nextIndent}segmentType: ${JSON.stringify(node.segmentType)},`);
+		parts.push(`${nextIndent}urlPath: ${JSON.stringify(node.urlPath)},`);
+		if (node.paramName) parts.push(`${nextIndent}paramName: ${JSON.stringify(node.paramName)},`);
+		if (node.interceptionMarker) parts.push(`${nextIndent}interceptionMarker: ${JSON.stringify(node.interceptionMarker)},`);
+		if (node.interceptedSegmentName) parts.push(`${nextIndent}interceptedSegmentName: ${JSON.stringify(node.interceptedSegmentName)},`);
+		for (const key of SINGLE_FILE_KEYS) {
+			const file = node[key];
+			if (file) parts.push(serializeRouteFile(key, file, nextIndent));
+		}
+		for (const key of RECORD_FILE_KEYS) {
+			const record = node[key];
+			if (record) {
+				const line = serializeRouteFileRecord(key, record, nextIndent);
+				if (line) parts.push(line);
+			}
+		}
+		if (node.children.length > 0) {
+			const childNodes = node.children.map((c) => serializeNode(c, nextIndent));
+			parts.push(`${nextIndent}children: [\n${childNodes.join(",\n")}\n${nextIndent}],`);
+		} else parts.push(`${nextIndent}children: [],`);
+		const slotKeys = Object.keys(node.slots);
+		if (slotKeys.length > 0) {
+			const slotEntries = [];
+			for (const slotName of slotKeys) {
+				const slotNode = node.slots[slotName];
+				slotEntries.push(`${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + "  ")}`);
+			}
+			parts.push(`${nextIndent}slots: {\n${slotEntries.join(",\n")}\n${nextIndent}},`);
+		} else parts.push(`${nextIndent}slots: {},`);
+		return `${indent}{\n${parts.join("\n")}\n${indent}}`;
+	}
+	const rootSerialized = serializeNode(tree.root, "  ");
+	let proxyLine = "";
+	if (tree.proxy) proxyLine = `  proxy: { load: ${addImport(tree.proxy)}, filePath: ${JSON.stringify(tree.proxy.filePath)} },`;
+	let globalErrorLine = "";
+	if (tree.globalError) globalErrorLine = `  globalError: { load: ${addImport(tree.globalError)}, filePath: ${JSON.stringify(tree.globalError.filePath)} },`;
+	const rewrites = collectInterceptionRewrites(tree.root);
+	const rewritesLine = rewrites.length > 0 ? `  interceptionRewrites: ${JSON.stringify(rewrites.map((r) => ({
+		interceptedPattern: r.interceptedPattern,
+		interceptingPrefix: r.interceptingPrefix
+	})))},` : "";
+	return [
+		"// Auto-generated route manifest — do not edit.",
+		"// Generated by timber-routing plugin.",
+		"",
+		...imports,
+		"",
+		"const manifest = {",
+		`  viteRoot: ${JSON.stringify(viteRoot)},`,
+		proxyLine,
+		globalErrorLine,
+		rewritesLine,
+		`  root: ${rootSerialized},`,
+		"};",
+		"",
+		"export default manifest;"
+	].filter((line) => line !== void 0 && line !== "").join("\n");
+}
+/**
+* Walk the route tree and collect every page that exports a
+* `searchParams` definition, then emit a module that statically imports
+* each export and registers it into the shared search-params registry.
+*/
+function generateSearchParamsRegistryModule(tree) {
+	const entries = [];
+	function walk(node) {
+		if (node.page) {
+			if (node.params && fileHasSearchParamsExport(node.params.filePath)) entries.push({
+				urlPath: node.urlPath,
+				filePath: node.params.filePath
+			});
+			else if (fileHasSearchParamsExport(node.page.filePath)) entries.push({
+				urlPath: node.urlPath,
+				filePath: node.page.filePath
+			});
+		}
+		for (const child of node.children) walk(child);
+		for (const slot of Object.values(node.slots)) walk(slot);
+	}
+	walk(tree.root);
+	entries.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
+	const lines = [];
+	lines.push("// Auto-generated search-params registry — do not edit.");
+	lines.push("// Generated by timber-routing plugin (TIM-830).");
+	lines.push("");
+	lines.push("import { registerSearchParams } from '@timber-js/app/search-params';");
+	lines.push("");
+	entries.forEach((entry, i) => {
+		lines.push(`import { searchParams as r${i} } from ${JSON.stringify(entry.filePath)};`);
+	});
+	lines.push("");
+	entries.forEach((entry, i) => {
+		lines.push(`registerSearchParams(${JSON.stringify(entry.urlPath)}, r${i});`);
+	});
+	lines.push("");
+	lines.push("export {};");
+	lines.push("");
+	return lines.join("\n");
+}
+function fileHasSearchParamsExport(filePath) {
+	try {
+		if (!existsSync(filePath)) return false;
+		const content = readFileCached(filePath);
+		return /export\s+(const|let|var)\s+searchParams\b/.test(content) || /export\s*\{[^}]*\bsearchParams\b[^}]*\}/.test(content);
+	} catch {
+		return false;
+	}
+}
+/**
+* Generate the virtual:timber-schema module.
+*
+* When app/schema.{ts,tsx,js,jsx} exists, generates a module that
+* imports the schema and resolves its segmentParams codecs into a
+* bare-name codec map for runtime coercion.
+*/
+function generateSchemaModule(appDir) {
+	let schemaPath = null;
+	for (const ext of SCHEMA_EXTENSIONS) {
+		const candidate = join(appDir, `schema${ext}`);
+		if (existsSync(candidate)) {
+			schemaPath = candidate;
+			break;
+		}
+	}
+	if (!schemaPath) return ["// Auto-generated schema loader — no app/schema.ts found.", "export default null;"].join("\n");
+	return [
+		"// Auto-generated schema loader — do not edit.",
+		"// Generated by timber-routing plugin (TIM-931).",
+		"",
+		`import schema from ${JSON.stringify(schemaPath)};`,
+		`import { resolveSchemaCodecs } from '@timber-js/app/params';`,
+		"",
+		"const globalCodecs = schema?.segmentParams",
+		"  ? resolveSchemaCodecs(schema.segmentParams)",
+		"  : null;",
+		"",
+		"export default globalCodecs;"
+	].join("\n");
+}
+//#endregion
 //#region src/routing/convention-lint.ts
 /**
 * Convention linter — validates common misconfigurations in the route tree.
@@ -2231,7 +2470,7 @@ function checkRouteExports(node, warnings) {
 	if (node.route) {
 		const filePath = node.route.filePath;
 		try {
-			const source = readFileSync(filePath, "utf-8");
+			const source = readFileCached(filePath);
 			if (!EXPORT_PATTERN.test(source)) {
 				const hint = /export\s+default\b/.test(source) ? "  It looks like you have a default export. route.ts uses named exports\n  for HTTP methods (GET, POST, etc.), not a default export.\n" : "";
 				warnings.push({
@@ -2297,7 +2536,7 @@ function isScriptExtension(ext) {
 }
 function checkFileDefaultExport(filePath, fileType, warnings) {
 	try {
-		const source = readFileSync(filePath, "utf-8");
+		const source = readFileCached(filePath);
 		if (!DEFAULT_EXPORT_PATTERN.test(source)) warnings.push({
 			id: `NO_DEFAULT_EXPORT:${filePath}`,
 			summary: `${fileType}.tsx has no default export: ${filePath}`,
@@ -2620,245 +2859,6 @@ function invalidateManifest(server) {
 	}
 	server.hot.send({ type: "full-reload" });
 }
-/**
-* TIM-830: Walk the route tree and collect every page that exports a
-* `searchParams` definition, then emit a module that statically imports
-* each export and registers it into the shared search-params registry.
-*
-* Keys use the un-interpolated route pattern (e.g. '/products/[id]') so
-* <Link> can look up the definition from the original `href` prop before
-* segmentParams are interpolated.
-*/
-/** Schema file extensions to check, in priority order. */
-var SCHEMA_EXTENSIONS = [
-	".ts",
-	".tsx",
-	".js",
-	".jsx"
-];
-/**
-* TIM-931: Generate the virtual:timber-schema module.
-*
-* When app/schema.{ts,tsx,js,jsx} exists, generates a module that
-* imports the schema and resolves its segmentParams codecs into a
-* bare-name codec map for runtime coercion.
-*
-* When no schema exists, exports null.
-*/
-function generateSchemaModule(appDir) {
-	let schemaPath = null;
-	for (const ext of SCHEMA_EXTENSIONS) {
-		const candidate = join(appDir, `schema${ext}`);
-		if (existsSync(candidate)) {
-			schemaPath = candidate;
-			break;
-		}
-	}
-	if (!schemaPath) return ["// Auto-generated schema loader — no app/schema.ts found.", "export default null;"].join("\n");
-	return [
-		"// Auto-generated schema loader — do not edit.",
-		"// Generated by timber-routing plugin (TIM-931).",
-		"",
-		`import schema from ${JSON.stringify(schemaPath)};`,
-		`import { resolveSchemaCodecs } from '@timber-js/app/params';`,
-		"",
-		"const globalCodecs = schema?.segmentParams",
-		"  ? resolveSchemaCodecs(schema.segmentParams)",
-		"  : null;",
-		"",
-		"export default globalCodecs;"
-	].join("\n");
-}
-function generateSearchParamsRegistryModule(tree) {
-	const entries = [];
-	function walk(node) {
-		if (node.page) {
-			if (node.params && fileHasSearchParamsExport(node.params.filePath)) entries.push({
-				urlPath: node.urlPath,
-				filePath: node.params.filePath
-			});
-			else if (fileHasSearchParamsExport(node.page.filePath)) entries.push({
-				urlPath: node.urlPath,
-				filePath: node.page.filePath
-			});
-		}
-		for (const child of node.children) walk(child);
-		for (const slot of Object.values(node.slots)) walk(slot);
-	}
-	walk(tree.root);
-	entries.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
-	const lines = [];
-	lines.push("// Auto-generated search-params registry — do not edit.");
-	lines.push("// Generated by timber-routing plugin (TIM-830).");
-	lines.push("");
-	lines.push("import { registerSearchParams } from '@timber-js/app/search-params';");
-	lines.push("");
-	entries.forEach((entry, i) => {
-		lines.push(`import { searchParams as r${i} } from ${JSON.stringify(entry.filePath)};`);
-	});
-	lines.push("");
-	entries.forEach((entry, i) => {
-		lines.push(`registerSearchParams(${JSON.stringify(entry.urlPath)}, r${i});`);
-	});
-	lines.push("");
-	lines.push("export {};");
-	lines.push("");
-	return lines.join("\n");
-}
-/**
-* Lightweight check for a `searchParams` named export. Mirrors
-* `fileHasExport('searchParams')` in routing/codegen.ts so we stay
-* in sync with what the type codegen detects.
-*/
-function fileHasSearchParamsExport(filePath) {
-	try {
-		if (!existsSync(filePath)) return false;
-		const content = readFileSync(filePath, "utf-8");
-		return /export\s+(const|let|var)\s+searchParams\b/.test(content) || /export\s*\{[^}]*\bsearchParams\b[^}]*\}/.test(content);
-	} catch {
-		return false;
-	}
-}
-/**
-* Generate the virtual module source code for the route manifest.
-*
-* The output is a default-exported object containing the serialized route tree.
-* All file references use absolute paths (required for virtual modules).
-*/
-function generateManifestModule(tree, viteRoot) {
-	const imports = [];
-	let importIndex = 0;
-	/**
-	* Create a lazy import expression for a route file.
-	* Returns the import variable name.
-	*/
-	function addImport(file) {
-		const varName = `_route${importIndex++}`;
-		imports.push(`const ${varName} = () => import("${file.filePath}");`);
-		return varName;
-	}
-	/**
-	* Serialize a segment node to a JS object literal.
-	*/
-	function serializeNode(node, indent) {
-		const nextIndent = indent + "  ";
-		const parts = [];
-		parts.push(`${nextIndent}segmentName: ${JSON.stringify(node.segmentName)},`);
-		parts.push(`${nextIndent}segmentType: ${JSON.stringify(node.segmentType)},`);
-		parts.push(`${nextIndent}urlPath: ${JSON.stringify(node.urlPath)},`);
-		if (node.paramName) parts.push(`${nextIndent}paramName: ${JSON.stringify(node.paramName)},`);
-		if (node.interceptionMarker) parts.push(`${nextIndent}interceptionMarker: ${JSON.stringify(node.interceptionMarker)},`);
-		if (node.interceptedSegmentName) parts.push(`${nextIndent}interceptedSegmentName: ${JSON.stringify(node.interceptedSegmentName)},`);
-		if (node.page) {
-			const v = addImport(node.page);
-			parts.push(`${nextIndent}page: { load: ${v}, filePath: ${JSON.stringify(node.page.filePath)} },`);
-		}
-		if (node.layout) {
-			const v = addImport(node.layout);
-			parts.push(`${nextIndent}layout: { load: ${v}, filePath: ${JSON.stringify(node.layout.filePath)} },`);
-		}
-		if (node.middleware) {
-			const v = addImport(node.middleware);
-			parts.push(`${nextIndent}middleware: { load: ${v}, filePath: ${JSON.stringify(node.middleware.filePath)} },`);
-		}
-		if (node.access) {
-			const v = addImport(node.access);
-			parts.push(`${nextIndent}access: { load: ${v}, filePath: ${JSON.stringify(node.access.filePath)} },`);
-		}
-		if (node.route) {
-			const v = addImport(node.route);
-			parts.push(`${nextIndent}route: { load: ${v}, filePath: ${JSON.stringify(node.route.filePath)} },`);
-		}
-		if (node.error) {
-			const v = addImport(node.error);
-			parts.push(`${nextIndent}error: { load: ${v}, filePath: ${JSON.stringify(node.error.filePath)} },`);
-		}
-		if (node.default) {
-			const v = addImport(node.default);
-			parts.push(`${nextIndent}default: { load: ${v}, filePath: ${JSON.stringify(node.default.filePath)} },`);
-		}
-		if (node.denied) {
-			const v = addImport(node.denied);
-			parts.push(`${nextIndent}denied: { load: ${v}, filePath: ${JSON.stringify(node.denied.filePath)} },`);
-		}
-		if (node.params) {
-			const v = addImport(node.params);
-			parts.push(`${nextIndent}params: { load: ${v}, filePath: ${JSON.stringify(node.params.filePath)} },`);
-		}
-		if (node.statusFiles && Object.keys(node.statusFiles).length > 0) {
-			const statusEntries = [];
-			for (const [code, file] of Object.entries(node.statusFiles)) {
-				const v = addImport(file);
-				statusEntries.push(`${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`);
-			}
-			parts.push(`${nextIndent}statusFiles: {\n${statusEntries.join(",\n")}\n${nextIndent}},`);
-		}
-		if (node.jsonStatusFiles && Object.keys(node.jsonStatusFiles).length > 0) {
-			const jsonEntries = [];
-			for (const [code, file] of Object.entries(node.jsonStatusFiles)) {
-				const v = addImport(file);
-				jsonEntries.push(`${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`);
-			}
-			parts.push(`${nextIndent}jsonStatusFiles: {\n${jsonEntries.join(",\n")}\n${nextIndent}},`);
-		}
-		if (node.legacyStatusFiles && Object.keys(node.legacyStatusFiles).length > 0) {
-			const legacyEntries = [];
-			for (const [name, file] of Object.entries(node.legacyStatusFiles)) {
-				const v = addImport(file);
-				legacyEntries.push(`${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`);
-			}
-			parts.push(`${nextIndent}legacyStatusFiles: {\n${legacyEntries.join(",\n")}\n${nextIndent}},`);
-		}
-		if (node.metadataRoutes && Object.keys(node.metadataRoutes).length > 0) {
-			const metaEntries = [];
-			for (const [name, file] of Object.entries(node.metadataRoutes)) {
-				const v = addImport(file);
-				metaEntries.push(`${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`);
-			}
-			parts.push(`${nextIndent}metadataRoutes: {\n${metaEntries.join(",\n")}\n${nextIndent}},`);
-		}
-		if (node.children.length > 0) {
-			const childNodes = node.children.map((c) => serializeNode(c, nextIndent));
-			parts.push(`${nextIndent}children: [\n${childNodes.join(",\n")}\n${nextIndent}],`);
-		} else parts.push(`${nextIndent}children: [],`);
-		const slotKeys = Object.keys(node.slots);
-		if (slotKeys.length > 0) {
-			const slotEntries = [];
-			for (const slotName of slotKeys) {
-				const slotNode = node.slots[slotName];
-				slotEntries.push(`${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + "  ")}`);
-			}
-			parts.push(`${nextIndent}slots: {\n${slotEntries.join(",\n")}\n${nextIndent}},`);
-		} else parts.push(`${nextIndent}slots: {},`);
-		return `${indent}{\n${parts.join("\n")}\n${indent}}`;
-	}
-	const rootSerialized = serializeNode(tree.root, "  ");
-	let proxyLine = "";
-	if (tree.proxy) proxyLine = `  proxy: { load: ${addImport(tree.proxy)}, filePath: ${JSON.stringify(tree.proxy.filePath)} },`;
-	let globalErrorLine = "";
-	if (tree.globalError) globalErrorLine = `  globalError: { load: ${addImport(tree.globalError)}, filePath: ${JSON.stringify(tree.globalError.filePath)} },`;
-	const rewrites = collectInterceptionRewrites(tree.root);
-	const rewritesLine = rewrites.length > 0 ? `  interceptionRewrites: ${JSON.stringify(rewrites.map((r) => ({
-		interceptedPattern: r.interceptedPattern,
-		interceptingPrefix: r.interceptingPrefix
-	})))},` : "";
-	return [
-		"// Auto-generated route manifest — do not edit.",
-		"// Generated by timber-routing plugin.",
-		"",
-		...imports,
-		"",
-		"const manifest = {",
-		`  viteRoot: ${JSON.stringify(viteRoot)},`,
-		proxyLine,
-		globalErrorLine,
-		rewritesLine,
-		`  root: ${rootSerialized},`,
-		"};",
-		"",
-		"export default manifest;"
-	].filter((line) => line !== void 0 && line !== "").join("\n");
-}
 //#endregion
 //#region src/plugins/shims.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
@@ -3061,6 +3061,58 @@ ${SERVER_STUB_EXPORTS.map((name) => name === "RedirectType" ? `export const Redi
 	};
 }
 //#endregion
+//#region src/fonts/paths.ts
+/**
+* Shared path/URL helpers for the timber-fonts pipeline.
+*
+* Two concerns live here:
+*
+* - `fontUrlPrefix` — the public URL prefix for font binaries, derived
+*   from Vite's resolved `base`. Every URL the pipeline emits (@font-face
+*   src, manifest hrefs, dev middleware matching) must go through this so
+*   apps deployed under a non-root base (`base: '/my-app/'`) resolve
+*   fonts correctly. Emitted *file* locations are not base-prefixed —
+*   only URLs are.
+*
+* - `fontOutputBasename` / `hashedFontBasename` — basename derivation for
+*   local font sources. Paths are absolutized with `resolve()`, which
+*   produces backslash separators on Windows, so `split('/').pop()` is
+*   not safe. `path.win32.basename` handles both separators.
+*
+* Design doc: 24-fonts.md
+*/
+/** Directory (relative to the build output / URL root) holding font binaries. */
+var FONT_OUTPUT_DIR = "_timber/fonts";
+/**
+* Build the URL prefix for font binaries from Vite's resolved `base`.
+*
+* `fontUrlPrefix('/')` → `/_timber/fonts`
+* `fontUrlPrefix('/my-app/')` → `/my-app/_timber/fonts`
+*/
+function fontUrlPrefix(base = "/") {
+	return `${base.endsWith("/") ? base : `${base}/`}${FONT_OUTPUT_DIR}`;
+}
+/**
+* Derive the output basename for a local font source path.
+*
+* Uses `path.win32.basename` because it splits on both `/` and `\`,
+* handling absolute paths produced by `resolve()` on any platform.
+*/
+function fontOutputBasename(srcPath) {
+	return win32.basename(srcPath);
+}
+/**
+* Derive the content-hashed output basename for a local font source.
+*
+* `hashedFontBasename('C:\\fonts\\MyFont-Bold.woff2', 'a1b2c3d4')`
+* → `MyFont-Bold-a1b2c3d4.woff2`
+*/
+function hashedFontBasename(srcPath, hash) {
+	const basename = fontOutputBasename(srcPath);
+	const ext = win32.extname(basename);
+	return `${ext ? basename.slice(0, -ext.length) : basename}-${hash}${ext}`;
+}
+//#endregion
 //#region src/fonts/google.ts
 /**
 * Google Fonts download, caching, and dev CDN fallback.
@@ -3256,12 +3308,14 @@ async function isCacheHit(metaPath, dataPath) {
 * Generate @font-face descriptors for cached (production) Google Fonts.
 *
 * Each CachedFont gets a FontFaceDescriptor pointing to the
-* content-hashed URL under `/_timber/fonts/`.
+* content-hashed URL under `<base>_timber/fonts/`. The `urlPrefix` comes
+* from `fontUrlPrefix(viteBase)` so apps deployed under a non-root base
+* resolve fonts correctly.
 */
-function generateProductionFontFaces(cachedFonts, display) {
+function generateProductionFontFaces(cachedFonts, display, urlPrefix = fontUrlPrefix()) {
 	return cachedFonts.map((cf) => ({
 		family: cf.face.family,
-		src: `url('/_timber/fonts/${cf.hashedFilename}') format('woff2')`,
+		src: `url('${urlPrefix}/${cf.hashedFilename}') format('woff2')`,
 		weight: cf.face.weight,
 		style: cf.face.style,
 		display,
@@ -3528,6 +3582,126 @@ function buildFontStack(family) {
 	return parts.join(", ");
 }
 //#endregion
+//#region src/fonts/ast-walk.ts
+/** Convert a 0-based byte offset into a 1-based line and 0-based column. */
+function offsetToLineColumn(source, offset) {
+	let line = 1;
+	let lastNewline = -1;
+	for (let i = 0; i < offset; i++) if (source[i] === "\n") {
+		line++;
+		lastNewline = i;
+	}
+	return {
+		line,
+		column: offset - lastNewline - 1
+	};
+}
+/**
+* Invoke `visit` on every direct child AST node of `node` (array elements
+* and object-valued properties with a `type` field).
+*/
+function walkChildNodes(node, visit) {
+	for (const key of Object.keys(node)) {
+		if (key === "type") continue;
+		const child = node[key];
+		if (Array.isArray(child)) {
+			for (const item of child) if (item && typeof item === "object" && item.type) visit(item);
+		} else if (child && typeof child === "object" && child.type) visit(child);
+	}
+}
+/**
+* Node types that introduce a nested scope — any font call inside is an
+* error (font calls must be module-level, same constraint as Next.js).
+* Module scope so it isn't rebuilt on every recursive walk call.
+*/
+var NESTED_SCOPE_TYPES = new Set([
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"ArrowFunctionExpression",
+	"IfStatement",
+	"ForStatement",
+	"ForInStatement",
+	"ForOfStatement",
+	"WhileStatement",
+	"DoWhileStatement",
+	"SwitchStatement",
+	"TryStatement",
+	"BlockStatement",
+	"ClassDeclaration",
+	"ClassExpression"
+]);
+/**
+* Recursively walk an AST node looking for font CallExpressions in nested
+* scopes (function bodies, if-blocks, loops, etc.). Font calls must be
+* module-level; nested calls are collected as errors.
+*
+* `isNested` tracks whether we've descended past the top-level statement.
+* Top-level VariableDeclarations and ExpressionStatements are already
+* handled by the main loop in `findFontCallSites`, so we only flag calls
+* found deeper.
+*/
+function walkForNestedFontCalls(node, bindingNames, source, out, isNested) {
+	if (!node || typeof node !== "object") return;
+	if (node.type === "CallExpression") {
+		const callee = node.callee;
+		if (isNested && callee.type === "Identifier" && bindingNames.has(callee.name)) {
+			const pos = offsetToLineColumn(source, node.start);
+			out.push({
+				name: callee.name,
+				line: pos.line,
+				column: pos.column
+			});
+			return;
+		}
+	}
+	const enterNested = isNested || NESTED_SCOPE_TYPES.has(node.type);
+	walkChildNodes(node, (child) => walkForNestedFontCalls(child, bindingNames, source, out, enterNested));
+}
+/**
+* Recursively walk an AST node looking for references to font bindings
+* that were not consumed by a recognized call site.
+*
+* Skips:
+* - recognized CallExpressions (the transform rewrites them wholesale)
+* - TS type-position nodes (erased at runtime)
+* - non-computed member properties (`obj.Inter` doesn't reference the binding)
+* - non-computed object keys (`{ Inter: 1 }` doesn't reference the binding)
+* - export aliases (`export { inter as Inter }` — only `local` is a reference)
+*/
+function walkForUnconsumedReferences(node, bindingNames, consumedCallStarts, source, out) {
+	if (!node || typeof node !== "object") return;
+	if (node.type === "ImportDeclaration" || node.type.startsWith("TS")) return;
+	if (node.type === "Identifier") {
+		const name = node.name;
+		if (bindingNames.has(name)) {
+			const pos = offsetToLineColumn(source, node.start);
+			out.push({
+				name,
+				line: pos.line,
+				column: pos.column
+			});
+		}
+		return;
+	}
+	if (node.type === "CallExpression" && consumedCallStarts.has(node.start)) return;
+	if (node.type === "MemberExpression" && !node.computed) {
+		const object = node.object;
+		if (object) walkForUnconsumedReferences(object, bindingNames, consumedCallStarts, source, out);
+		return;
+	}
+	if (node.type === "Property" && !node.computed) {
+		const value = node.value;
+		if (value) walkForUnconsumedReferences(value, bindingNames, consumedCallStarts, source, out);
+		return;
+	}
+	if (node.type === "ExportSpecifier") {
+		const local = node.local;
+		if (local) walkForUnconsumedReferences(local, bindingNames, consumedCallStarts, source, out);
+		return;
+	}
+	walkChildNodes(node, (child) => walkForUnconsumedReferences(child, bindingNames, consumedCallStarts, source, out));
+}
+//#endregion
 //#region src/fonts/ast.ts
 /**
 * AST utilities for extracting static font configs from source code.
@@ -3546,19 +3720,6 @@ function buildFontStack(family) {
 *
 * Design doc: 24-fonts.md §"Step 1: Static Analysis"
 */
-/** Convert a 0-based byte offset into a 1-based line and 0-based column. */
-function offsetToLineColumn(source, offset) {
-	let line = 1;
-	let lastNewline = -1;
-	for (let i = 0; i < offset; i++) if (source[i] === "\n") {
-		line++;
-		lastNewline = i;
-	}
-	return {
-		line,
-		column: offset - lastNewline - 1
-	};
-}
 /**
 * Extract a static string value from an AST node.
 * Returns undefined if the node is not a string literal.
@@ -3769,6 +3930,7 @@ function findFontCallSites(source) {
 	}
 	const bindings = [];
 	const importNodesToRemove = [];
+	const namespaceImports = [];
 	for (const stmt of program.body) {
 		if (!isImportDeclaration(stmt)) continue;
 		const importDecl = stmt;
@@ -3777,26 +3939,40 @@ function findFontCallSites(source) {
 		if (GOOGLE_FONT_SOURCES.has(specSource)) provider = "google";
 		else if (LOCAL_FONT_SOURCES.has(specSource)) provider = "local";
 		if (!provider) continue;
-		for (const spec of importDecl.specifiers) if (spec.type === "ImportSpecifier" && provider === "google") bindings.push({
-			localName: spec.local.name,
-			importedName: spec.imported?.name ?? spec.local.name,
-			provider,
-			importNode: importDecl
-		});
-		else if (spec.type === "ImportDefaultSpecifier" && provider === "local") bindings.push({
-			localName: spec.local.name,
-			importedName: "default",
-			provider,
-			importNode: importDecl
-		});
-		importNodesToRemove.push({
+		let producedBinding = false;
+		for (const spec of importDecl.specifiers) if (spec.type === "ImportSpecifier" && provider === "google") {
+			producedBinding = true;
+			bindings.push({
+				localName: spec.local.name,
+				importedName: spec.imported?.name ?? spec.local.name,
+				provider,
+				importNode: importDecl
+			});
+		} else if (spec.type === "ImportDefaultSpecifier" && provider === "local") {
+			producedBinding = true;
+			bindings.push({
+				localName: spec.local.name,
+				importedName: "default",
+				provider,
+				importNode: importDecl
+			});
+		} else if (spec.type === "ImportNamespaceSpecifier") {
+			const pos = offsetToLineColumn(source, spec.start);
+			namespaceImports.push({
+				name: spec.local.name,
+				line: pos.line,
+				column: pos.column
+			});
+		}
+		if (producedBinding) importNodesToRemove.push({
 			start: stmt.start,
 			end: stmt.end
 		});
 	}
-	if (bindings.length === 0) return null;
+	if (bindings.length === 0 && namespaceImports.length === 0) return null;
 	const bindingsByName = new Map(bindings.map((b) => [b.localName, b]));
 	const callSites = [];
+	const consumedCallStarts = /* @__PURE__ */ new Set();
 	let dynamicCall = null;
 	for (const stmt of program.body) {
 		const effectiveStmt = isExportNamedDeclaration(stmt) && stmt.declaration ? stmt.declaration : stmt;
@@ -3807,6 +3983,7 @@ function findFontCallSites(source) {
 			const site = matchCallExpression(call, bindingsByName, source);
 			if (!site) continue;
 			if (site === "dynamic") {
+				consumedCallStarts.add(call.start);
 				if (!dynamicCall && isIdentifier(call.callee)) {
 					const argStart = call.arguments[0].start;
 					const argEnd = call.arguments[0].end;
@@ -3816,6 +3993,7 @@ function findFontCallSites(source) {
 			}
 			const assignedName = isIdentifier(declarator.id) ? declarator.id.name : null;
 			const { line, column } = offsetToLineColumn(source, call.start);
+			consumedCallStarts.add(call.start);
 			callSites.push({
 				binding: site.binding,
 				assignedName,
@@ -3832,6 +4010,7 @@ function findFontCallSites(source) {
 				const site = matchCallExpression(call, bindingsByName, source);
 				if (site && site !== "dynamic") {
 					const { line, column } = offsetToLineColumn(source, call.start);
+					consumedCallStarts.add(call.start);
 					callSites.push({
 						binding: site.binding,
 						assignedName: null,
@@ -3841,10 +4020,13 @@ function findFontCallSites(source) {
 						line,
 						column
 					});
-				} else if (site === "dynamic" && !dynamicCall && isIdentifier(call.callee)) {
-					const argStart = call.arguments[0].start;
-					const argEnd = call.arguments[0].end;
-					dynamicCall = `${call.callee.name}(${source.slice(argStart, argEnd)})`;
+				} else if (site === "dynamic") {
+					consumedCallStarts.add(call.start);
+					if (!dynamicCall && isIdentifier(call.callee)) {
+						const argStart = call.arguments[0].start;
+						const argEnd = call.arguments[0].end;
+						dynamicCall = `${call.callee.name}(${source.slice(argStart, argEnd)})`;
+					}
 				}
 			}
 		}
@@ -3854,63 +4036,22 @@ function findFontCallSites(source) {
 		if (stmt.type === "ImportDeclaration") continue;
 		walkForNestedFontCalls(stmt, bindingsByName, source, nestedCalls, false);
 	}
+	const unsupportedUsages = [];
+	for (const stmt of program.body) {
+		if (stmt.type === "ImportDeclaration") continue;
+		walkForUnconsumedReferences(stmt, bindingsByName, consumedCallStarts, source, unsupportedUsages);
+	}
 	return {
 		bindings,
 		callSites,
 		importNodesToRemove,
 		dynamicCall,
-		nestedCalls
+		nestedCalls,
+		namespaceImports,
+		unsupportedUsages
 	};
 }
 /**
-* Recursively walk an AST node looking for font CallExpressions in nested
-* scopes (function bodies, if-blocks, loops, etc.). Font calls must be
-* module-level; nested calls are collected as errors.
-*
-* `isNested` tracks whether we've descended past the top-level statement.
-* Top-level VariableDeclarations and ExpressionStatements are already
-* handled by the main loop in `findFontCallSites`, so we only flag calls
-* found deeper.
-*/
-function walkForNestedFontCalls(node, bindings, source, out, isNested) {
-	if (!node || typeof node !== "object") return;
-	if (node.type === "CallExpression") {
-		const callee = node.callee;
-		if (isNested && callee.type === "Identifier" && bindings.has(callee.name)) {
-			const pos = offsetToLineColumn(source, node.start);
-			out.push({
-				name: callee.name,
-				line: pos.line,
-				column: pos.column
-			});
-			return;
-		}
-	}
-	const enterNested = isNested || new Set([
-		"FunctionDeclaration",
-		"FunctionExpression",
-		"ArrowFunctionExpression",
-		"IfStatement",
-		"ForStatement",
-		"ForInStatement",
-		"ForOfStatement",
-		"WhileStatement",
-		"DoWhileStatement",
-		"SwitchStatement",
-		"TryStatement",
-		"BlockStatement",
-		"ClassDeclaration",
-		"ClassExpression"
-	]).has(node.type);
-	for (const key of Object.keys(node)) {
-		if (key === "type") continue;
-		const child = node[key];
-		if (Array.isArray(child)) {
-			for (const item of child) if (item && typeof item === "object" && item.type) walkForNestedFontCalls(item, bindings, source, out, enterNested);
-		} else if (child && typeof child === "object" && child.type) walkForNestedFontCalls(child, bindings, source, out, enterNested);
-	}
-}
-/**
 * Match a CallExpression against the font bindings map.
 *
 * Returns the binding + config node if the call is a static font call,
@@ -4001,23 +4142,23 @@ function resolveLocalFontPaths(importerPath, sources) {
 function generateFamilyName(sources) {
 	if (sources.length === 0) return "Local Font";
 	const firstPath = sources[0].path;
-	const stem = (firstPath.split("/").pop() ?? firstPath).replace(/\.[^.]+$/, "");
+	const stem = fontOutputBasename(firstPath).replace(/\.[^.]+$/, "");
 	return stem.replace(/[-_]?(Regular|Bold|Italic|Light|Medium|SemiBold|ExtraBold|Thin|Black|Heavy)$/i, "") || stem;
 }
 /**
 * Generate @font-face descriptors for local font sources.
 *
 * Each source entry produces one @font-face rule. The `src` descriptor
-* uses a `url()` pointing to the served path under `/_timber/fonts/`.
-* The `urlPrefix` defaults to `/_timber/fonts` — the path used by both
-* the dev server middleware and the production build output.
+* uses a `url()` pointing to the served path under `<base>_timber/fonts/`.
+* The `urlPrefix` defaults to `fontUrlPrefix()` (root base) — pass
+* `fontUrlPrefix(viteBase)` so non-root deployments resolve correctly.
 */
-function generateLocalFontFaces(family, sources, display, urlPrefix = "/_timber/fonts") {
+function generateLocalFontFaces(family, sources, display, urlPrefix = fontUrlPrefix()) {
 	return sources.map((entry) => {
 		const format = inferFontFormat(entry.path);
 		return {
 			family,
-			src: `url('${urlPrefix}/${entry.hashedBasename ?? entry.path.split("/").pop() ?? entry.path}') format('${format}')`,
+			src: `url('${urlPrefix}/${entry.hashedBasename ?? fontOutputBasename(entry.path)}') format('${format}')`,
 			weight: entry.weight,
 			style: entry.style,
 			display
@@ -4224,9 +4365,18 @@ var FontPipeline = class {
 	_entries = /* @__PURE__ */ new Map();
 	/** When true, local font sources are content-hashed at registration time. */
 	_hashOnRegister;
+	/**
+	* Vite's resolved `base`. Set from the plugin's `configResolved` hook so
+	* every @font-face URL the pipeline renders carries the prefix.
+	*/
+	_base = "/";
 	constructor(opts) {
 		this._hashOnRegister = opts?.hashOnRegister ?? false;
 	}
+	/** Set Vite's resolved `base` (from `configResolved`). */
+	setBase(base) {
+		this._base = base;
+	}
 	/**
 	* Per-importer virtual CSS module id registry. Populated by the
 	* transform hook when it inlines a font function call, read by the
@@ -4296,10 +4446,8 @@ var FontPipeline = class {
 		if (this._hashOnRegister && entry.provider === "local" && entry.localSources) for (const src of entry.localSources) {
 			const absolutePath = normalize(resolve(src.path));
 			if (!existsSync(absolutePath)) continue;
-			const hash = contentHash(readFileSync(absolutePath));
-			const basename = src.path.split("/").pop() ?? src.path;
-			const ext = extname(basename);
-			src.hashedBasename = `${ext ? basename.slice(0, -ext.length) : basename}-${hash}${ext}`;
+			const data = readFileSync(absolutePath);
+			src.hashedBasename = hashedFontBasename(src.path, contentHash(data));
 		}
 		this._entries.set(entry.id, entry);
 	}
@@ -4363,8 +4511,9 @@ var FontPipeline = class {
 	* or lazily in `load` for dev).
 	*/
 	getCss() {
+		const urlPrefix = fontUrlPrefix(this._base);
 		const cssParts = [];
-		for (const entry of this._entries.values()) cssParts.push(renderEntryCss(entry));
+		for (const entry of this._entries.values()) cssParts.push(renderEntryCss(entry, urlPrefix));
 		return cssParts.join("\n\n");
 	}
 	/**
@@ -4384,10 +4533,11 @@ var FontPipeline = class {
 	* pipeline handles it as a valid empty CSS module.
 	*/
 	getCssForSegment(importer) {
+		const urlPrefix = fontUrlPrefix(this._base);
 		const cssParts = [];
 		for (const entry of this._entries.values()) {
 			if (entry.importer !== importer) continue;
-			cssParts.push(renderEntryCss(entry));
+			cssParts.push(renderEntryCss(entry, urlPrefix));
 		}
 		return cssParts.join("\n\n");
 	}
@@ -4395,15 +4545,13 @@ var FontPipeline = class {
 /**
 * Render the combined CSS for a single font entry.
 *
-* Mirrors the standalone `generateFontCss` helper exported from
-* `virtual-modules.ts`, but reads `faces` straight off the entry instead
-* of from a parallel map. Kept private to this module so the only public
-* way to render a `FontEntry`'s CSS is through `FontPipeline.getCss()`.
+* Reads `faces` straight off the entry. Private to this module — the only
+* public way to render a `FontEntry`'s CSS is through `FontPipeline.getCss()`.
 */
-function renderEntryCss(entry) {
+function renderEntryCss(entry, urlPrefix) {
 	const cssParts = [];
 	if (entry.provider === "local" && entry.localSources) {
-		const faceCss = generateFontFaces(generateLocalFontFaces(entry.family, entry.localSources, entry.display));
+		const faceCss = generateFontFaces(generateLocalFontFaces(entry.family, entry.localSources, entry.display, urlPrefix));
 		if (faceCss) cssParts.push(faceCss);
 	}
 	if (entry.provider === "google" && entry.faces && entry.faces.length > 0) {
@@ -5525,6 +5673,14 @@ function runFontsTransform(code, id, pipeline, emitError) {
 		const first = analysis.nestedCalls[0];
 		emitError(`Font function \`${first.name}()\` must be called at module scope. Found nested call at line ${first.line}, column ${first.column}. Move the call to the top level of the module.`);
 	}
+	if (analysis.namespaceImports.length > 0) {
+		const first = analysis.namespaceImports[0];
+		emitError(`Namespace imports of font modules are not supported (\`* as ${first.name}\` at line ${first.line}, column ${first.column}). Use a named import instead: \`import { Inter } from 'next/font/google'\`.`);
+	}
+	if (analysis.unsupportedUsages.length > 0) {
+		const first = analysis.unsupportedUsages[0];
+		emitError(`Unsupported usage of font function \`${first.name}\` at line ${first.line}, column ${first.column}. A font call must be \`const x = Font({...})\` at module scope (export const is fine). The call result cannot be nested in other expressions, and the imported font function cannot be aliased or re-exported.`);
+	}
 	if (analysis.callSites.length === 0 && analysis.bindings.length === 0) return null;
 	const s = new MagicString(code);
 	for (const site of analysis.callSites) if (site.binding.provider === "google") {
@@ -5600,11 +5756,12 @@ var FONT_MIME_TYPES = {
 * captured by reference so that fonts registered after `configureServer`
 * runs (during transform) are still resolvable.
 */
-function installFontDevMiddleware(server, pipeline) {
+function installFontDevMiddleware(server, pipeline, base = "/") {
+	const urlPrefix = `${fontUrlPrefix(base)}/`;
 	server.middlewares.use((req, res, next) => {
 		const url = req.url;
-		if (!url || !url.startsWith("/_timber/fonts/")) return next();
-		const requestedFilename = url.slice(15);
+		if (!url || !url.startsWith(urlPrefix)) return next();
+		const requestedFilename = url.slice(urlPrefix.length);
 		if (requestedFilename.includes("..") || requestedFilename.includes("/")) {
 			res.statusCode = 400;
 			res.end("Bad request");
@@ -5613,7 +5770,7 @@ function installFontDevMiddleware(server, pipeline) {
 		for (const font of pipeline.fonts()) {
 			if (font.provider !== "local" || !font.localSources) continue;
 			for (const src of font.localSources) {
-				if ((src.path.split("/").pop() ?? "") !== requestedFilename && src.hashedBasename !== requestedFilename) continue;
+				if (fontOutputBasename(src.path) !== requestedFilename && src.hashedBasename !== requestedFilename) continue;
 				const absolutePath = normalize(resolve(src.path));
 				if (!existsSync(absolutePath)) {
 					res.statusCode = 404;
@@ -5623,7 +5780,7 @@ function installFontDevMiddleware(server, pipeline) {
 				const data = readFileSync(absolutePath);
 				const ext = absolutePath.split(".").pop()?.toLowerCase();
 				res.setHeader("Content-Type", FONT_MIME_TYPES[ext ?? ""] ?? "application/octet-stream");
-				res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+				res.setHeader("Cache-Control", "no-cache");
 				res.setHeader("Access-Control-Allow-Origin", "*");
 				res.end(data);
 				return;
@@ -5667,7 +5824,7 @@ function groupCachedFontsByFamily(cachedFonts) {
 function emitFontAssets(pipeline, emitFile, warn) {
 	for (const cf of pipeline.uniqueCachedFiles()) emitFile({
 		type: "asset",
-		fileName: `_timber/fonts/${cf.hashedFilename}`,
+		fileName: `${FONT_OUTPUT_DIR}/${cf.hashedFilename}`,
 		source: cf.data
 	});
 	for (const font of pipeline.fonts()) {
@@ -5678,11 +5835,11 @@ function emitFontAssets(pipeline, emitFile, warn) {
 				warn(`Local font file not found: ${absolutePath}`);
 				continue;
 			}
-			const filename = src.hashedBasename ?? src.path.split("/").pop() ?? src.path;
+			const filename = src.hashedBasename ?? fontOutputBasename(src.path);
 			const data = readFileSync(absolutePath);
 			emitFile({
 				type: "asset",
-				fileName: `_timber/fonts/${filename}`,
+				fileName: `${FONT_OUTPUT_DIR}/${filename}`,
 				source: data
 			});
 		}
@@ -5695,22 +5852,25 @@ function emitFontAssets(pipeline, emitFile, warn) {
 * `buildManifest.css` keys work after TIM-1014.
 *
 * All font binaries use content-hashed filenames for immutable caching.
+* Hrefs are prefixed with Vite's resolved `base` so they match the URLs
+* the platform serves the emitted binaries under.
 */
-function writeFontManifest(pipeline, buildManifest) {
+function writeFontManifest(pipeline, buildManifest, base = "/") {
+	const urlPrefix = fontUrlPrefix(base);
 	const fontsByImporter = /* @__PURE__ */ new Map();
 	for (const entry of pipeline.entries()) {
 		const manifestEntries = fontsByImporter.get(entry.importer) ?? [];
 		if (entry.provider === "local" && entry.localSources) for (const src of entry.localSources) {
-			const filename = src.hashedBasename ?? src.path.split("/").pop() ?? src.path;
+			const filename = src.hashedBasename ?? fontOutputBasename(src.path);
 			const format = inferFontFormat(src.path);
 			manifestEntries.push({
-				href: `/_timber/fonts/${filename}`,
+				href: `${urlPrefix}/${filename}`,
 				format,
 				crossOrigin: "anonymous"
 			});
 		}
 		else if (entry.cachedFiles) for (const cf of entry.cachedFiles) manifestEntries.push({
-			href: `/_timber/fonts/${cf.hashedFilename}`,
+			href: `${urlPrefix}/${cf.hashedFilename}`,
 			format: "woff2",
 			crossOrigin: "anonymous"
 		});
@@ -5725,9 +5885,19 @@ function writeFontManifest(pipeline, buildManifest) {
 */
 function timberFonts(ctx) {
 	const pipeline = new FontPipeline({ hashOnRegister: !ctx.dev });
+	let resolvedBase = "/";
 	return {
 		name: "timber-fonts",
 		/**
+		* Capture Vite's resolved `base` so every font URL the pipeline emits
+		* (@font-face src, manifest hrefs, dev middleware matching) carries
+		* the prefix. Emitted file locations are unaffected — only URLs.
+		*/
+		configResolved(config) {
+			resolvedBase = config.base;
+			pipeline.setBase(config.base);
+		},
+		/**
 		* `enforce: 'pre'` is load-bearing for the font CSS pipeline (TIM-828).
 		*
 		* The transform hook injects a side-effect
@@ -5811,7 +5981,7 @@ function timberFonts(ctx) {
 		* this middleware.
 		*/
 		configureServer(server) {
-			installFontDevMiddleware(server, pipeline);
+			installFontDevMiddleware(server, pipeline, resolvedBase);
 		},
 		/**
 		* Download and cache Google Fonts during production builds.
@@ -5828,10 +5998,11 @@ function timberFonts(ctx) {
 			const googleFonts = [...pipeline.googleFonts()];
 			if (googleFonts.length === 0) return;
 			const cachedByFamily = groupCachedFontsByFamily(await downloadAndCacheFonts(googleFonts, ctx.root));
+			const urlPrefix = fontUrlPrefix(resolvedBase);
 			for (const font of googleFonts) {
 				const familyCached = cachedByFamily.get(font.family.toLowerCase()) ?? [];
 				pipeline.attachCachedFiles(font.id, familyCached);
-				pipeline.attachFaces(font.id, generateProductionFontFaces(familyCached, font.display));
+				pipeline.attachFaces(font.id, generateProductionFontFaces(familyCached, font.display, urlPrefix));
 			}
 		},
 		/**
@@ -5853,7 +6024,7 @@ function timberFonts(ctx) {
 		generateBundle() {
 			emitFontAssets(pipeline, (asset) => this.emitFile(asset), (msg) => this.warn(msg));
 			if (!ctx.buildManifest) return;
-			writeFontManifest(pipeline, ctx.buildManifest);
+			writeFontManifest(pipeline, ctx.buildManifest, resolvedBase);
 		}
 	};
 }
@@ -6658,6 +6829,7 @@ function clientChunkGroup(meta, appDir, root) {
 */
 var BUILD_ONLY_EXTERNALS = [
 	...builtinModules.flatMap((m) => [m, `node:${m}`]),
+	"vite",
 	"nitro",
 	"rollup",
 	"@mdx-js/rollup",
@@ -6747,13 +6919,21 @@ function timberServerBundle() {
 * timber-cache-transform — Vite plugin that injects stable callsite IDs
 * into `cache()` calls imported from `@timber-js/app/cache`.
 *
-* Without this plugin, cache keys use a process-local counter (fnIdCounter)
-* which is unstable across cold starts in serverless/multi-instance
-* deployments. With a shared CacheHandler (Redis/KV), colliding counters
-* cause cache key poisoning — serving one route's cached data to another.
+* Detected callsite forms (TIM-1054):
+*   - named imports, including aliases: `import { cache as c }` + `c(fn, opts)`
+*   - namespace imports: `import * as ns` + `ns.cache(fn, opts)`
+* Forms a per-module transform cannot trace — local variable aliases
+* (`const c = cache`), user re-export wrapper modules, computed access
+* (`ns['cache']`) — fall back to the runtime fnId derived from
+* fnv1a(fn.toString()) (see cache/timber-cache.ts), which is deterministic
+* across instances and cold starts of the same build. Without either
+* mechanism, an ordinal counter would collide across instances with a shared
+* CacheHandler (Redis/KV) — cache key poisoning, serving one route's cached
+* data to another.
 *
 * The plugin transforms:
-*   cache(fn, opts)  →  cache(fn, opts, "stable-id")
+*   cache(fn, opts)      →  cache(fn, opts, "stable-id")
+*   ns.cache(fn, opts)   →  ns.cache(fn, opts, "stable-id")
 *
 * where stable-id =
 *   fnv1a(relPath + ":cache:" + fnv1a(stmtText) + ":" + fnv1a(callSpanText) + ":" + occurrence)
@@ -6788,20 +6968,43 @@ function timberServerBundle() {
 */
 var CACHE_MODULE_SOURCES = new Set(["@timber-js/app/cache", "timber/cache"]);
 /**
-* Find the local binding name(s) for `cache` imported from the cache module.
+* Find the local binding name(s) for `cache` imported from the cache module —
+* both named imports and namespace imports (TIM-1054).
 */
 function findCacheBindings(program) {
-	const bindings = /* @__PURE__ */ new Set();
+	const named = /* @__PURE__ */ new Set();
+	const namespaces = /* @__PURE__ */ new Set();
 	for (const stmt of program.body) {
 		if (stmt.type !== "ImportDeclaration") continue;
 		const decl = stmt;
 		if (!CACHE_MODULE_SOURCES.has(decl.source.value)) continue;
 		for (const spec of decl.specifiers) {
+			if (spec.type === "ImportNamespaceSpecifier") {
+				namespaces.add(spec.local.name);
+				continue;
+			}
 			if (spec.type !== "ImportSpecifier") continue;
-			if ((spec.imported?.name ?? spec.local.name) === "cache") bindings.add(spec.local.name);
+			if ((spec.imported?.name ?? spec.local.name) === "cache") named.add(spec.local.name);
 		}
 	}
-	return bindings;
+	return {
+		named,
+		namespaces
+	};
+}
+/**
+* Is this callee a reference to the imported `cache` function — either a bare
+* identifier bound by a named import, or `ns.cache` on a namespace import?
+* Computed access (`ns['cache']`) is deliberately not matched; it falls back
+* to the runtime fnId derivation.
+*/
+function isCacheCallee(callee, bindings) {
+	if (callee.type === "Identifier") return bindings.named.has(callee.name);
+	if (callee.type === "MemberExpression") {
+		const member = callee;
+		return !member.computed && member.object.type === "Identifier" && bindings.namespaces.has(member.object.name) && member.property.type === "Identifier" && member.property.name === "cache";
+	}
+	return false;
 }
 /**
 * Recursively walk AST nodes to find cache() call expressions.
@@ -6812,7 +7015,7 @@ function findCacheBindings(program) {
 function findCacheCallSites(node, cacheBindings, results) {
 	if (node.type === "CallExpression") {
 		const call = node;
-		if (call.callee.type === "Identifier" && cacheBindings.has(call.callee.name) && call.arguments.length === 2) results.push(call);
+		if (call.arguments.length === 2 && isCacheCallee(call.callee, cacheBindings)) results.push(call);
 	}
 	for (const key of Object.keys(node)) {
 		if (key === "type" || key === "start" || key === "end") continue;
@@ -6856,7 +7059,7 @@ function timberCacheTransform(ctx) {
 				return;
 			}
 			const cacheBindings = findCacheBindings(program);
-			if (cacheBindings.size === 0) return;
+			if (cacheBindings.named.size === 0 && cacheBindings.namespaces.size === 0) return;
 			const callSites = [];
 			for (const stmt of program.body) {
 				const calls = [];
@@ -7750,14 +7953,15 @@ function timber(config) {
 			ctx.timer.start("config-load");
 			const fileConfig = loadTimberConfigFile(viteRoot);
 			if (fileConfig) {
-				mergeFileConfig(ctx, fileConfig);
+				ctx.config = mergeFileConfig(ctx.config, fileConfig);
 				ctx.clientJavascript = resolveClientJavascript(ctx.config);
 			}
 			ctx.config.output ??= "server";
 			ctx.timer.end("config-load");
 			const viteOutDir = userConfig.build?.outDir;
 			const timberBuildDir = ctx.config.buildDir;
-			ctx.buildDir = resolveBuildDir(resolve(userConfig.root ?? process.cwd()), timberBuildDir, viteOutDir);
+			const resolvedRoot = resolve(userConfig.root ?? process.cwd());
+			ctx.buildDir = resolveBuildDir(resolvedRoot, timberBuildDir, viteOutDir);
 			if (viteRoot !== process.cwd()) {
 				const hasCompilerInReloaded = !config?.reactCompiler && ctx.config.reactCompiler;
 				const hadCompilerInEarly = !config?.reactCompiler && earlyFileConfig?.reactCompiler;
@@ -7784,7 +7988,7 @@ function timber(config) {
 				resolvedDevPort = start.port;
 				resolvedDevPortExplicit = start.explicit;
 			}
-			const buildOutDir = timberBuildDir ? timberBuildDir : viteOutDir && viteOutDir !== "dist" ? viteOutDir : DEFAULT_BUILD_DIR;
+			const buildOutDir = relative(resolvedRoot, ctx.buildDir);
 			const envOutDirs = {};
 			for (const envName of [
 				"rsc",