@timber-js/app 0.2.0-alpha.132 → 0.2.0-alpha.134

package/dist/index.js

@@ -1368,6 +1368,15 @@ function timberDevServer(ctx) {
 	return {
 		name: "timber-dev-server",
 		apply: "serve",
+		/**
+		* Register the dev server middleware and config file watcher.
+		*
+		* Registers as a pre-hook (no return value) so our middleware runs
+		* before Vite's built-in SPA fallback / historyApiFallback. This
+		* ensures we see the original URL (e.g. /blog) rather than a
+		* rewritten /index.html. Vite-internal and asset requests are
+		* filtered out explicitly and passed through to Vite.
+		*/
 		configureServer(server) {
 			const configPaths = CONFIG_FILE_NAMES.map((name) => join(ctx.root, name));
 			server.watcher.add(configPaths);
@@ -1825,6 +1834,17 @@ function generateCacheHandlerModule(configPath, hasCacheHandler) {
 function timberEntries(ctx) {
 	return {
 		name: "timber-entries",
+		/**
+		* Resolve virtual entry and config module IDs.
+		*
+		* Handles:
+		* - virtual:timber-rsc-entry → real file path
+		* - virtual:timber-ssr-entry → real file path
+		* - virtual:timber-browser-entry → real file path
+		* - virtual:timber-config → \0-prefixed virtual ID
+		* - \0 prefix stripping (RSC plugin re-imports)
+		* - Root prefix stripping (SSR build entries)
+		*/
 		resolveId(id) {
 			let cleanId = stripNullPrefix(id);
 			cleanId = stripRootPrefix(cleanId, ctx.root);
@@ -1834,6 +1854,12 @@ function timberEntries(ctx) {
 			if (cleanId === VIRTUAL_IDS.cacheHandler) return RESOLVED_CACHE_HANDLER_ID;
 			return null;
 		},
+		/**
+		* Load virtual modules: virtual:timber-config and virtual:timber-instrumentation.
+		*
+		* Entry files (rsc/ssr/browser) are real TypeScript files that Vite
+		* processes normally. Only config and instrumentation need generated code.
+		*/
 		load(id) {
 			if (id === RESOLVED_CONFIG_ID) return generateConfigModule(ctx);
 			if (id === RESOLVED_INSTRUMENTATION_ID) return generateInstrumentationModule(detectInstrumentationFile(ctx.root));
@@ -2372,6 +2398,14 @@ function timberRouting(ctx) {
 	}
 	return {
 		name: "timber-routing",
+		/**
+		* Resolve the virtual module ID.
+		*
+		* Handles:
+		* - virtual:timber-route-manifest
+		* - <root>/virtual:timber-route-manifest (Vite SSR build root prefix)
+		* - \0virtual:timber-route-manifest (RSC plugin re-imports)
+		*/
 		resolveId(id, importer) {
 			const cleanId = id.startsWith("\0") ? id.slice(1) : id;
 			if (cleanId === VIRTUAL_MODULE_ID$1) return RESOLVED_VIRTUAL_ID$1;
@@ -2386,6 +2420,12 @@ function timberRouting(ctx) {
 			}
 			return null;
 		},
+		/**
+		* Generate the route manifest module.
+		*
+		* The manifest exports the route tree as a serialized data structure
+		* with absolute import paths for all file references.
+		*/
 		load(id) {
 			if (id === RESOLVED_VIRTUAL_ID$1) {
 				if (!ctx.routeTree) rescan();
@@ -2406,10 +2446,23 @@ function timberRouting(ctx) {
 			}
 			return null;
 		},
+		/**
+		* Scan routes at build start.
+		*
+		* In dev mode, skip — configureServer runs after buildStart and will
+		* do its own scan. Avoids a redundant FS traversal on cold start.
+		*/
 		buildStart() {
 			if (ctx.dev) return;
 			rescan();
 		},
+		/**
+		* Set up file watcher in dev mode.
+		*
+		* Watches app/ for file additions/deletions/renames that affect
+		* the route tree, regenerates the manifest, and invalidates
+		* dependent modules via HMR.
+		*/
 		configureServer(devServer) {
 			rescan();
 			devServer.watcher.add(ctx.appDir);
@@ -2802,6 +2855,24 @@ function timberShims(_ctx) {
 	return {
 		name: "timber-shims",
 		enforce: "pre",
+		/**
+		* Resolve next/* imports to shim files.
+		*
+		* Resolution order:
+		* 1. Check server-only / client-only poison pill packages
+		* 2. Strip .js extension from the import specifier
+		* 3. Check next/* shim map
+		* 4. Return null (pass through) for everything else
+		*
+		* All @timber-js/app/* subpath imports resolve to dist/ via package.json
+		* exports in all environments. This ensures a single module instance
+		* for each module — the dist/ chunks share code via rollup's code
+		* splitting. No src/ remapping is needed (see TIM-568).
+		*
+		* The only exception is @timber-js/app/server in the client (browser)
+		* environment, which returns a virtual stub — server code must never
+		* be bundled into the browser.
+		*/
 		resolveId(id) {
 			if (id === "server-only") return SERVER_ONLY_VIRTUAL;
 			if (id === "client-only") return CLIENT_ONLY_VIRTUAL;
@@ -2838,6 +2909,13 @@ function timberShims(_ctx) {
 			}
 			return null;
 		},
+		/**
+		* Serve virtual modules for server-only / client-only poison pills.
+		*
+		* In the correct environment, the module is a no-op (empty export).
+		* In the wrong environment, it throws a build-time error message that
+		* clearly identifies the boundary violation.
+		*/
 		load(id) {
 			const isClient = this.environment?.name === "client";
 			if (id === SERVER_ONLY_VIRTUAL) {
@@ -5521,7 +5599,35 @@ function timberFonts(ctx) {
 	const pipeline = new FontPipeline();
 	return {
 		name: "timber-fonts",
+		/**
+		* `enforce: 'pre'` is load-bearing for the font CSS pipeline (TIM-828).
+		*
+		* The transform hook injects a side-effect
+		* `import 'virtual:timber-font-css/<hash>.css'` into every file that
+		* registers a font. @vitejs/plugin-rsc's `rsc:rsc-css-export-transform`
+		* later inspects each server component's source for CSS imports and
+		* wraps the default export in `import.meta.viteRsc.loadCss(...)` so
+		* the matched virtual CSS module ends up `preinit`'d as
+		* `<link rel="stylesheet" data-rsc-css-href=...>`.
+		*
+		* If timber-fonts ran in normal order it would inject the CSS import
+		* *after* plugin-rsc had already scanned the source, and the font CSS
+		* would be silently dropped from the rendered HTML. Running in the
+		* `pre` slot guarantees our injected import is visible to plugin-rsc's
+		* later CSS-export scan.
+		*/
 		enforce: "pre",
+		/**
+		* Resolve `@timber/fonts/google`, `@timber/fonts/local`, and the
+		* per-importer `virtual:timber-font-css/<hash>.css` modules injected
+		* by the transform hook.
+		*
+		* Strips the `\0` prefix added by the RSC plugin's re-imports and the
+		* absolute root prefix added by SSR build entries before comparing
+		* against the public IDs. The `.css` suffix on font-css ids is
+		* preserved so Vite's CSS pipeline (`isCSSRequest`) recognises the
+		* resolved id as CSS.
+		*/
 		resolveId(id) {
 			let cleanId = id.startsWith("\0") ? id.slice(1) : id;
 			const qIdx = cleanId.indexOf("?");
@@ -5537,6 +5643,19 @@ function timberFonts(ctx) {
 			if (pipeline.cssIdMap.matches(cleanId)) return "\0" + cleanId + query;
 			return null;
 		},
+		/**
+		* Return generated source for font virtual modules.
+		*
+		* The per-importer `virtual:timber-font-css/<hash>.css` modules
+		* return the combined font CSS for the specific importer that
+		* registered them. Vite's CSS pipeline handles injection from here:
+		* in dev the module rides the CSS HMR channel; in production it is
+		* emitted as a real CSS asset and @vitejs/plugin-rsc's `collectCss`
+		* walks the RSC module graph to find it.
+		*
+		* In dev mode we also lazily resolve Google `@font-face` descriptors
+		* from the CDN here, since `buildStart` is a no-op in dev.
+		*/
 		async load(id) {
 			if (id === "\0@timber/fonts/google") return generateGoogleVirtualModule(pipeline.fonts());
 			if (id === "\0@timber/fonts/local") return generateLocalVirtualModule();
@@ -5558,9 +5677,22 @@ function timberFonts(ctx) {
 			}
 			return null;
 		},
+		/**
+		* Serve local font files in dev mode under `/_timber/fonts/<basename>`.
+		* Font CSS goes through Vite's CSS pipeline (virtual modules), not
+		* this middleware.
+		*/
 		configureServer(server) {
 			installFontDevMiddleware(server, pipeline);
 		},
+		/**
+		* Download and cache Google Fonts during production builds.
+		*
+		* In dev mode this is a no-op — fonts point to the Google CDN and are
+		* resolved lazily inside `load()` when the side-effect module runs.
+		* The registry is populated by the transform hook which runs before
+		* `buildStart` in the build pipeline, so all fonts are known here.
+		*/
 		async buildStart() {
 			if (ctx.dev) return;
 			const googleFonts = [...pipeline.googleFonts()];
@@ -5572,9 +5704,23 @@ function timberFonts(ctx) {
 				pipeline.attachFaces(font.id, generateProductionFontFaces(familyCached, font.display));
 			}
 		},
+		/**
+		* Scan source files for font function calls and extract static config.
+		*
+		* Delegates to `runFontsTransform`. Errors raised through the
+		* `this.error` callback are surfaced as Vite plugin errors.
+		*/
 		transform(code, id) {
 			return runFontsTransform(code, id, pipeline, (msg) => this.error(msg));
 		},
+		/**
+		* Emit font binaries and build-manifest entries.
+		*
+		* Google fonts use the content-hashed filenames produced during
+		* `buildStart`. Local fonts are emitted by basename. Font CSS is
+		* handled by Vite's CSS pipeline via virtual modules — we only emit
+		* binaries here.
+		*/
 		generateBundle() {
 			emitFontAssets(pipeline, (asset) => this.emitFile(asset), (msg) => this.warn(msg));
 			if (!ctx.buildManifest) return;
@@ -5643,6 +5789,13 @@ function detectDynamicApis(code, fileId) {
 function timberStaticBuild(ctx) {
 	return {
 		name: "timber-static-build",
+		/**
+		* Validate source files during transform.
+		*
+		* In static mode, we check every app/ file for:
+		* - Dynamic API usage (getCookies(), getHeaders()) → build error
+		* - When client JS disabled: 'use client' / 'use server' directives → build error
+		*/
 		transform(code, id) {
 			if (!(ctx.config.output === "static")) return null;
 			if (id.includes("node_modules")) return null;