@lovrozagar/flare 0.3.1 → 0.4.1

package/README.md

@@ -321,7 +321,7 @@ Chain order (typical): `intercept` → `cache` → `authenticate` → `input`
 | Method                                                                                        | Role                                                             |
 | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
 | `.cache(config)`                                                                              | Client / SSR / ISR / SSG / CDN                                   |
-| `.authenticate()` / `.authenticate("optional")` / `.authenticate(false)`                      | Auth gate                                                        |
+| `.authenticate()` / `.authenticate("optional")`                                               | Auth gate                                                        |
 | `.authorize(fn)`                                                                              | Role check; inherits parent unless overridden                    |
 | `.input({ params, searchParams })`                                                            | Standard Schema or parse fn                                      |
 | `.effects({ loaderDeps, shouldRefetch })`                                                     | When to rerun the loader on search change                        |
@@ -462,9 +462,10 @@ export const route = createPage("_root_/dashboard")
 ```
 
 - `.authenticate()` — required; null user → `UnauthenticatedError` (401).
-- `.authenticate("optional")` — user may be null.
-- `.authenticate(false)` — skip even if a parent required it.
-- Child inherits parent auth unless it sets its own mode.
+- `.authenticate("optional")` — user may be null; `ctx.auth` is `null` for anonymous requests.
+- Other arguments are callerData for `authenticateFn`: `.authenticate("admin")` is required, `.authenticate("optional", "viewer")` is optional.
+- A required layout gates every route below it; a child cannot loosen it.
+- `.authenticateOptional()` is a deprecated alias of `.authenticate("optional")`.
 - `createServer(router).authenticateFn(fn)` is the app-wide hook (cookie, header, JWT).
 
 Throw helpers: `ctx.notFound()`, `ctx.redirect({ to, params, search, status, replace })`, `ctx.unauthenticated()`, `ctx.unauthorized()`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lovrozagar/flare",
-	"version": "0.3.1",
+	"version": "0.4.1",
 	"description": "Solid meta-framework. Server-driven, NDJSON streaming, renderToStream.",
 	"keywords": [
 		"flare",
@@ -102,6 +102,9 @@
 		"type:check": "tsc --noEmit -p tsconfig.src.json",
 		"type:check:tests": "NODE_OPTIONS='--max-old-space-size=4096' tsc --noEmit"
 	},
+	"dependencies": {
+		"@types/negotiator": "catalog:"
+	},
 	"devDependencies": {
 		"@babel/parser": "catalog:",
 		"@capsizecss/metrics": "catalog:",
@@ -111,7 +114,6 @@
 		"@solidjs/web": "catalog:",
 		"@tanstack/query-broadcast-client-experimental": "catalog:",
 		"@tanstack/solid-query": "catalog:",
-		"@types/negotiator": "catalog:",
 		"isbot": "catalog:",
 		"jsdom": "catalog:",
 		"magic-string": "catalog:",
@@ -140,6 +142,7 @@
 		"oxc-resolver": ">=11.23.0",
 		"sharp": ">=0.33.0",
 		"solid-js": ">=2.0.0-rc.0",
+		"tailwindcss": ">=4.0.0",
 		"vite": ">=8.0.0"
 	},
 	"peerDependenciesMeta": {
@@ -169,6 +172,9 @@
 		},
 		"sharp": {
 			"optional": true
+		},
+		"tailwindcss": {
+			"optional": true
 		}
 	}
 }

package/src/generators/index.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, extname, join, posix } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, extname, join, posix, relative, resolve } from "node:path";
 import { parse as babelParse } from "@babel/parser";
 import { parseSeconds } from "../duration/index.ts";
 import type { AuthenticateMode } from "../route-builder/types.ts";
@@ -494,9 +494,7 @@ export function extractRouteDefinitions(src: string, filePath: string): RouteDef
 			const nextExport = NEXT_EXPORT_RE.exec(rest);
 			const chainText = nextExport ? rest.slice(0, nextExport.index) : rest;
 
-			const hasAuthenticateOptional = /\.authenticateOptional\s*\(/.test(chainText);
-			const hasAuthenticate = /\.authenticate\s*\(/.test(chainText);
-			const authenticateMode: AuthenticateMode = hasAuthenticateOptional ? "optional" : !!hasAuthenticate;
+			const authenticateMode = detectAuthenticateMode(chainText);
 			const hasAuthorize = /\.authorize\s*\(/.test(chainText);
 			const hasInput = /\.input\s*(?:<[^>]*>)?\s*\(/.test(chainText);
 			const responseRoute = /\.response\s*\(/.test(chainText);
@@ -640,6 +638,13 @@ function relativeImportPath(from: string, to: string): string {
 	return `${prefix}/${downs.join("/")}`;
 }
 
+/** Auth mode of a builder chain; mirrors `resolveAuthenticateArgs` in the route builder. */
+export function detectAuthenticateMode(chainText: string): AuthenticateMode {
+	if (/\.authenticateOptional\s*\(/.test(chainText)) return "optional";
+	if (/\.authenticate\s*\(\s*(["'`])optional\1\s*[,)]/.test(chainText)) return "optional";
+	return /\.authenticate\s*\(/.test(chainText);
+}
+
 function formatRouteMeta(def: RouteDefinition): string {
 	const parts: string[] = [];
 	if (def.authenticateMode === true) parts.push("authenticate: true");
@@ -846,7 +851,11 @@ function serializeRouteMeta(def: RouteDefinition): string {
 	return `{${meta}}`;
 }
 
-export function generateRoutesFile(defs: RouteDefinition[], outputDir: string): string {
+export function generateRoutesFile(
+	defs: RouteDefinition[],
+	outputDir: string,
+	app: AppEntries = resolveAppEntries(".", outputDir),
+): string {
 	const pages = defs.filter((d) => d.type === "page");
 	const layouts = generateLayoutsRecord(defs, outputDir);
 
@@ -858,22 +867,7 @@ export function generateRoutesFile(defs: RouteDefinition[], outputDir: string):
 	/* Detect whether any pages have .input() for search params typing */
 	const hasSearchParams = pages.some((d) => !d.responseRoute && d.hasInput);
 
-	/* Detect queryClientGetter in router source */
-	const routerFilePath = posix.join(posix.dirname(outputDir), "router");
-	let hasQueryClient = false;
-	for (const ext of [".ts", ".tsx"]) {
-		try {
-			const routerSource = readFileSync(`${routerFilePath}${ext}`, "utf-8");
-			if (routerSource.includes("queryClientGetter")) {
-				hasQueryClient = true;
-			}
-			break;
-		} catch {
-			/* file doesn't exist with this extension */
-		}
-	}
-
-	const serverHandler = resolveCreateServerExport(outputDir);
+	const { hasQueryClient, serverHandler } = app;
 	const registry = generateRouteRegistry(defs, outputDir, hasAuth, hasQueryClient, serverHandler !== null);
 
 	/* Deduplicate meta objects */
@@ -1008,25 +1002,84 @@ export function generateVirtualModuleTypes(): string {
 	return `/// <reference types="vite/client" />\n/// <reference types="@lovrozagar/flare/virtual-types" />\n`;
 }
 
-function resolveCreateServerExport(outputDir: string): { exportName: string; importPath: string } | null {
-	const serverFilePath = posix.join(posix.dirname(outputDir), "server");
-	for (const ext of [".ts", ".tsx"]) {
-		try {
-			const serverSource = readFileSync(`${serverFilePath}${ext}`, "utf-8");
-			const match = serverSource.match(/export\s+const\s+(\w+)\s*=\s*createServer/);
-			if (match?.[1]) {
-				return {
-					exportName: match[1],
-					importPath: relativeImportPath(`${outputDir}/routes.gen.ts`, serverFilePath),
-				};
-			}
-		} catch {
-			/* missing extension */
-		}
+export interface AppEntries {
+	hasQueryClient: boolean;
+	serverHandler: { exportName: string; importPath: string } | null;
+	warnings: string[];
+}
+
+const ENTRY_EXTS = [".ts", ".tsx"];
+
+/** Root-relative posix path of the first existing candidate (`base` as given, then with each extension). */
+function findSourceFile(rootDir: string, base: string): string | null {
+	for (const candidate of [
+		base,
+		...ENTRY_EXTS.map((ext) => `${base}${ext}`),
+		...ENTRY_EXTS.map((ext) => `${base}/index${ext}`),
+	]) {
+		const abs = resolve(rootDir, candidate);
+		if (existsSync(abs) && statSync(abs).isFile()) return relative(resolve(rootDir), abs).replaceAll("\\", "/");
 	}
 	return null;
 }
 
+function readSource(rootDir: string, rel: string | null): string | null {
+	if (!rel) return null;
+	try {
+		return readFileSync(resolve(rootDir, rel), "utf-8");
+	} catch {
+		return null;
+	}
+}
+
+/** Relative module the server entry imports the router from: `createServer(x)` + `import { x } from "./..."`. */
+function routerImportOf(serverSource: string): string | null {
+	const arg = serverSource.match(/createServer\s*(?:<[^>]*>)?\s*\(\s*(\w+)/)?.[1];
+	if (!arg) return null;
+	for (const m of serverSource.matchAll(/import\s*\{([^}]*)\}\s*from\s*["'](\.{1,2}\/[^"']+)["']/g)) {
+		const names = (m[1] ?? "").split(",").map((n) =>
+			n
+				.trim()
+				.split(/\s+as\s+/)
+				.pop(),
+		);
+		if (names.includes(arg)) return m[2] ?? null;
+	}
+	return null;
+}
+
+/**
+ * Server handler export and router facts for the registry. The server entry
+ * defaults to `server.ts(x)` beside the output dir; the router is the module
+ * the server passes to `createServer()`, else `router.ts(x)` beside it.
+ */
+export function resolveAppEntries(rootDir: string, outputDir: string, serverEntry?: string): AppEntries {
+	const warnings: string[] = [];
+	const srcDir = posix.dirname(outputDir);
+	const serverFile = serverEntry ? findSourceFile(rootDir, serverEntry) : findSourceFile(rootDir, `${srcDir}/server`);
+	const serverSource = readSource(rootDir, serverFile);
+
+	const routerSpec = serverSource && serverFile ? routerImportOf(serverSource) : null;
+	const routerFile =
+		(routerSpec && serverFile ? findSourceFile(rootDir, posix.join(posix.dirname(serverFile), routerSpec)) : null) ??
+		findSourceFile(rootDir, `${srcDir}/router`);
+	const hasQueryClient = readSource(rootDir, routerFile)?.includes("queryClientGetter") ?? false;
+
+	let serverHandler: AppEntries["serverHandler"] = null;
+	if (serverSource && serverFile) {
+		const exportName = serverSource.match(/export\s+const\s+(\w+)\s*=\s*createServer/)?.[1];
+		if (exportName) {
+			serverHandler = { exportName, importPath: relativeImportPath(`${outputDir}/routes.gen.ts`, serverFile) };
+		} else if (/createServer\s*(?:<[^>]*>)?\s*\(/.test(serverSource)) {
+			warnings.push(
+				`${serverFile} calls createServer() without exporting it; export the chain (export const server = createServer(router)...) so routes.gen.ts can infer auth, env, and serverContext`,
+			);
+		}
+	}
+
+	return { hasQueryClient, serverHandler, warnings };
+}
+
 /** Generate TypeScript declaration merging block for route type registry. */
 export function generateRouteRegistry(
 	defs: RouteDefinition[],
@@ -1148,12 +1201,12 @@ export function generateRouteRegistry(
 	}
 
 	if (hasServer && hasAuth) {
-		lines.push(`\t\tauth: NonNullable<Awaited<ReturnType<NonNullable<typeof _FlareHandler["authenticateFn"]>>>>`);
+		lines.push(`\t\tauth: NonNullable<NonNullable<(typeof _FlareHandler)["~flare"]>["auth"]>`);
 	}
 
 	if (hasServer) {
 		lines.push(`\t\tenv: Parameters<typeof _FlareHandler["fetch"]>[1]`);
-		lines.push(`\t\tserverContext: Awaited<ReturnType<NonNullable<typeof _FlareHandler["serverContext"]>>>`);
+		lines.push(`\t\tserverContext: NonNullable<(typeof _FlareHandler)["~flare"]>["serverContext"]`);
 	}
 	if (hasQueryClient) {
 		lines.push("\t\thasQueryClient: true");
@@ -1502,9 +1555,7 @@ export function scanSourceFilesFsCodegen(options: ScanOptions): RouteDefinition[
 		}
 
 		/* Extract chain metadata from file content */
-		const hasAuthenticateOptional = /\.authenticateOptional\s*\(/.test(content);
-		const hasAuthenticate = /\.authenticate\s*\(/.test(content);
-		const authenticateMode: AuthenticateMode = hasAuthenticateOptional ? "optional" : !!hasAuthenticate;
+		const authenticateMode = detectAuthenticateMode(content);
 		const hasAuthorize = /\.authorize\s*\(/.test(content);
 		const hasInput = /\.input\s*(?:<[^>]*>)?\s*\(/.test(content);
 		const responseRoute = /\.response\s*\(/.test(content);
@@ -1533,6 +1584,8 @@ export interface RunGenerateOptions {
 	ignorePrefix?: string;
 	outputPath?: string;
 	rootDir: string;
+	/** Server entry (root-relative or absolute); defaults to `server.ts(x)` beside the output dir. */
+	serverEntry?: string;
 	srcDir?: string;
 	typesOutputPath?: string;
 }
@@ -1617,7 +1670,12 @@ export function runGenerate(options: RunGenerateOptions): GenerateResult {
 		return { layouts: 0, routes: 0, warnings };
 	}
 
-	const content = generateRoutesFile(defs, outputDir);
+	const app = resolveAppEntries(options.rootDir, outputDir, options.serverEntry);
+	for (const warning of app.warnings) {
+		warnings.push(warning);
+		console.warn(`[flare:generate] ${warning}`);
+	}
+	const content = generateRoutesFile(defs, outputDir, app);
 	writeGenFile(fullOutputPath, content, "flare");
 
 	/* Write virtual module type declarations as a .d.ts file (must be ambient, not in a module) */

package/src/link/index.tsx

@@ -331,7 +331,7 @@ export function Link<TPath extends RoutePaths>(props: LinkProps<TPath>): JSX.Ele
 			};
 		},
 		({ disabled, el, external, hrefOnly, strategy }) => {
-			if (!el || disabled || hrefOnly || external) return;
+			if (!el || disabled || hrefOnly || external) return undefined;
 
 			if (strategy === "intent") {
 				el.addEventListener("focus", handleIntent);
@@ -368,6 +368,7 @@ export function Link<TPath extends RoutePaths>(props: LinkProps<TPath>): JSX.Ele
 			if (strategy === "render") {
 				return scheduleAfterLoad(() => triggerPrefetch());
 			}
+			return undefined;
 		},
 	);
 

package/src/navigation/index.ts

@@ -585,12 +585,12 @@ function hydrateCachedDeferred(cached: CachedMatch): boolean {
 function commitCachedShell(
 	c: FlareProviderContext,
 	allModules: LoadedRouteModule[],
+	rootLayout: LoadedRouteModule | undefined,
 	search: SearchParams,
 	params: Record<string, string | string[]>,
 ): { hadShell: boolean; keepMatchIds: string[] } {
 	if (!ctx) return { hadShell: false, keepMatchIds: [] };
 	let found = false;
-	const heads: PerRouteHead[] = [];
 	const keepMatchIds: string[] = [];
 	for (const mod of allModules) {
 		const matchId = matchIdForModule(mod, search, params);
@@ -600,10 +600,23 @@ function commitCachedShell(
 		if (cached.hasDeferred && hydrateCachedDeferred(cached)) {
 			keepMatchIds.push(matchId);
 		}
-		if (cached.headConfig) heads.push({ head: cached.headConfig, matchId });
 	}
 	if (!found) return { hadShell: false, keepMatchIds: [] };
 
+	/* applyPerRouteHeads replaces the whole hierarchy, so a partial set would
+	 * drop the root layout's CSS. Apply only when every route has a cached head;
+	 * otherwise the post-fetch update applies the full set. */
+	const heads: PerRouteHead[] = [];
+	for (const mod of rootLayout ? [rootLayout, ...allModules] : allModules) {
+		const matchId = matchIdForModule(mod, search, params);
+		const head = ctx.matchCache.get(matchId)?.headConfig;
+		if (!head) {
+			heads.length = 0;
+			break;
+		}
+		heads.push({ head, matchId });
+	}
+
 	c.setIntercepted(null);
 	c.setNotFound(false);
 	assignMatches(c, buildClientMatches(allModules, search, params));
@@ -1141,6 +1154,9 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 		 */
 		const nonRootLayouts = modules.layouts.filter((m) => m._type !== "root-layout");
 		const allModules: LoadedRouteModule[] = [...nonRootLayouts, modules.page];
+		/* The root layout still owns head state (title, CSS) on every navigation. */
+		const rootLayout = modules.layouts.find((m) => m._type === "root-layout");
+		const headModules = rootLayout ? [rootLayout, ...allModules] : allModules;
 
 		/* Instant navigation: reuse in-flight prefetch and paint a cached shell
 		 * before the enter NDJSON hop. Skipped when this nav already fetched in
@@ -1160,7 +1176,7 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 				}
 			}
 			if (controller.signal.aborted || myVersion !== navigationVersion) return;
-			const shell = commitCachedShell(c, allModules, search, modules.params);
+			const shell = commitCachedShell(c, allModules, rootLayout, search, modules.params);
 			hadShell = shell.hadShell;
 			paintedShell = shell.hadShell;
 			if (shell.hadShell) {
@@ -1387,25 +1403,21 @@ export async function navigate(options: InternalNavigateOptions, redirectCount =
 		const clientMatches = buildClientMatches(allModules, search, modules.params);
 
 		/* Step 11: Compute head data before update — used inside VT callback */
-		const freshHeads = fetchResult?.perRouteHeads ?? [];
-		const fetchedHeadIds = new Set<string>();
-		for (const h of freshHeads) fetchedHeadIds.add(h.matchId);
-		const perRouteHeads: PerRouteHead[] = [...freshHeads];
-		for (const mod of allModules) {
-			const deps = mod.effectsConfig?.loaderDeps?.({ search }) ?? [];
-			const matchId = computeMatchId({
-				loaderDeps: () => deps,
-				params: modules.params,
-				routeId: mod.virtualPath,
-				search,
-			});
-			if (!fetchedHeadIds.has(matchId)) {
-				const cached = ctx.matchCache.get(matchId);
-				if (cached?.headConfig) {
-					perRouteHeads.push({ head: cached.headConfig, matchId });
-				}
+		const freshHeads = new Map<string, HeadConfig>();
+		for (const h of fetchResult?.perRouteHeads ?? []) freshHeads.set(h.matchId, h.head);
+		const fetchedIds = new Set(fetchResult?.matches.map((m) => m.matchId));
+		/* Hierarchy order, root first. A fetched route uses its fresh head (none
+		 * under headReplace); an unfetched one falls back to the cache. */
+		const perRouteHeads: PerRouteHead[] = [];
+		for (const mod of headModules) {
+			const matchId = matchIdForModule(mod, search, modules.params);
+			const head = fetchedIds.has(matchId) ? freshHeads.get(matchId) : ctx.matchCache.get(matchId)?.headConfig;
+			if (head) {
+				perRouteHeads.push({ head, matchId });
+				freshHeads.delete(matchId);
 			}
 		}
+		for (const [matchId, head] of freshHeads) perRouteHeads.push({ head, matchId });
 
 		/* Step 12: Update state + scroll + head + cleanup.
 		 * Everything inside update() so VT captures the complete state transition. */

package/src/plugins/index.ts

@@ -153,7 +153,7 @@ const ENTRY_EXTENSIONS = [".tsx", ".ts"];
 
 function resolveEntry(root: string, base: string, override?: string): string {
 	if (override) {
-		if (!existsSync(join(root, override))) {
+		if (!existsSync(resolve(root, override))) {
 			throw new Error(`Flare: entry.${base} path "${override}" not found`);
 		}
 		return override;
@@ -189,7 +189,11 @@ function createResolverPlugin(): VitePlugin {
 
 /* ── Generate ────────────────────────────────────────────────────────── */
 
-function createGeneratePlugin(config: FlarePluginConfig, codegen: ReturnType<typeof resolveCodegenConfig>): VitePlugin {
+function createGeneratePlugin(
+	config: FlarePluginConfig,
+	codegen: ReturnType<typeof resolveCodegenConfig>,
+	serverEntry: string,
+): VitePlugin {
 	const ignorePrefix = config.ignorePrefix ?? "_";
 
 	const generateOpts = {
@@ -197,6 +201,7 @@ function createGeneratePlugin(config: FlarePluginConfig, codegen: ReturnType<typ
 		ignorePrefix,
 		outputPath: codegen.routesFilePath,
 		rootDir: "",
+		serverEntry,
 		typesOutputPath: codegen.typesFilePath,
 	};
 
@@ -235,12 +240,7 @@ function createGeneratePlugin(config: FlarePluginConfig, codegen: ReturnType<typ
 
 /* ── SSR Build ───────────────────────────────────────────────────────── */
 
-function createSsrBuildPlugin(
-	entries: ResolvedEntries,
-	config: FlarePluginConfig,
-	assetsBase: string,
-	assetsDir: string,
-): VitePlugin {
+function createSsrBuildPlugin(entries: ResolvedEntries, config: FlarePluginConfig, assetsDir: string): VitePlugin {
 	return {
 		config() {
 			return {
@@ -411,8 +411,8 @@ export function flare(config: FlarePluginConfig = EMPTY_OBJ): VitePlugin[] {
 		solid(solidConfig) as unknown as VitePlugin,
 		createImagePlugin(config, resolvedOptions.assetsBase, resolvedOptions.assetsDir),
 		createResolverPlugin(),
-		createGeneratePlugin(config, resolvedCodegen),
-		createSsrBuildPlugin(entries, config, resolvedOptions.assetsBase, resolvedOptions.assetsDir),
+		createGeneratePlugin(config, resolvedCodegen, resolve(root, entries.server)),
+		createSsrBuildPlugin(entries, config, resolvedOptions.assetsDir),
 		createDevServerPlugin(entries, resolvedOptions.assetsBase),
 		createPreviewServerPlugin(resolvedOptions.assetsBase),
 		createVirtualPlugin(config, entries, resolvedCodegen),

package/src/plugins/tw-compile.ts

@@ -177,10 +177,13 @@ export function extractDeclarations(
 	return raw.replace(/\s+/g, " ").trim();
 }
 
+const TAILWIND_MODULE: string = "tailwindcss";
+
 /** Initialize a Tailwind v4 compiler from an optional CSS entry file. */
 export async function initTailwindCompiler(cssPath?: string): Promise<TailwindCompiler> {
 	try {
-		const tw = await import("tailwindcss");
+		/* Optional peer: a non-literal specifier keeps consumers without tailwindcss typechecking. */
+		const tw = (await import(/* @vite-ignore */ TAILWIND_MODULE)) as { compile?: unknown; default?: unknown };
 		const compileFn = tw.compile ?? (tw.default as { compile?: unknown })?.compile;
 		if (typeof compileFn !== "function") {
 			throw new Error(

package/src/route-builder/create-layout.ts

@@ -12,6 +12,7 @@ import type {
 } from "./register.ts";
 import {
 	type AuthenticateMode,
+	type AuthenticateModeFromArgs,
 	BUILDER_MARKER,
 	type CacheConfig,
 	type DeferFn,
@@ -25,6 +26,7 @@ import {
 	type SearchParamsValidator,
 	type ServerThrowHelpers,
 	type ServerUrlHelpers,
+	resolveAuthenticateArgs,
 } from "./types.ts";
 
 /* ── callback context types ─────────────────────────────────────── */
@@ -315,7 +317,11 @@ interface LayoutBuilderAfterInput<
 	TAuth extends AuthenticateMode,
 	TPreloaderContext,
 > extends LayoutBuilderAfterAuthenticate<TPath, TParams, TSearch, TAuth, TPreloaderContext> {
-	authenticate(...args: unknown[]): LayoutBuilderAfterAuthenticate<TPath, TParams, TSearch, true, TPreloaderContext>;
+	/** Required by default; `.authenticate("optional")` lets anonymous requests through with `ctx.auth === null`. Other arguments are callerData for `authenticateFn`. */
+	authenticate<const TArgs extends readonly unknown[]>(
+		...args: TArgs
+	): LayoutBuilderAfterAuthenticate<TPath, TParams, TSearch, AuthenticateModeFromArgs<TArgs>, TPreloaderContext>;
+	/** @deprecated Use `.authenticate("optional", ...callerData)`. */
 	authenticateOptional(
 		...args: unknown[]
 	): LayoutBuilderAfterAuthenticate<TPath, TParams, TSearch, "optional", TPreloaderContext>;
@@ -601,12 +607,14 @@ function createBuilderAfterInput<
 >(state: BuilderStateInternal): LayoutBuilderAfterInput<TPath, TParams, TSearch, TAuth, TPreloaderContext> {
 	return {
 		...createBuilderAfterAuthenticate<TPath, TParams, TSearch, TAuth, TPreloaderContext>(state),
-		authenticate(...args: unknown[]) {
-			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, true, TPreloaderContext>({
-				...state,
-				authenticate: args,
-				authenticateMode: true,
-			});
+		authenticate<const TArgs extends readonly unknown[]>(...args: TArgs) {
+			return createBuilderAfterAuthenticate<
+				TPath,
+				TParams,
+				TSearch,
+				AuthenticateModeFromArgs<TArgs>,
+				TPreloaderContext
+			>({ ...state, ...resolveAuthenticateArgs(args) });
 		},
 		authenticateOptional(...args: unknown[]) {
 			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, "optional", TPreloaderContext>({

package/src/route-builder/create-page.ts

@@ -11,6 +11,7 @@ import type {
 } from "./register.ts";
 import {
 	type AuthenticateMode,
+	type AuthenticateModeFromArgs,
 	BUILDER_MARKER,
 	type CacheConfig,
 	type DeferFn,
@@ -24,6 +25,7 @@ import {
 	type SearchParamsValidator,
 	type ServerThrowHelpers,
 	type ServerUrlHelpers,
+	resolveAuthenticateArgs,
 } from "./types.ts";
 
 /* ── callback context types ─────────────────────────────────────── */
@@ -385,7 +387,11 @@ interface PageBuilderAfterInput<
 	TAuth extends AuthenticateMode,
 	TPreloaderContext,
 > extends PageBuilderAfterAuthenticate<TPath, TParams, TSearch, TAuth, TPreloaderContext> {
-	authenticate(...args: unknown[]): PageBuilderAfterAuthenticate<TPath, TParams, TSearch, true, TPreloaderContext>;
+	/** Required by default; `.authenticate("optional")` lets anonymous requests through with `ctx.auth === null`. Other arguments are callerData for `authenticateFn`. */
+	authenticate<const TArgs extends readonly unknown[]>(
+		...args: TArgs
+	): PageBuilderAfterAuthenticate<TPath, TParams, TSearch, AuthenticateModeFromArgs<TArgs>, TPreloaderContext>;
+	/** @deprecated Use `.authenticate("optional", ...callerData)`. */
 	authenticateOptional(
 		...args: unknown[]
 	): PageBuilderAfterAuthenticate<TPath, TParams, TSearch, "optional", TPreloaderContext>;
@@ -726,12 +732,14 @@ function createBuilderAfterInput<
 >(state: BuilderStateInternal): PageBuilderAfterInput<TPath, TParams, TSearch, TAuth, TPreloaderContext> {
 	return {
 		...createBuilderAfterAuthenticate<TPath, TParams, TSearch, TAuth, TPreloaderContext>(state),
-		authenticate(...args: unknown[]) {
-			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, true, TPreloaderContext>({
-				...state,
-				authenticate: args,
-				authenticateMode: true,
-			});
+		authenticate<const TArgs extends readonly unknown[]>(...args: TArgs) {
+			return createBuilderAfterAuthenticate<
+				TPath,
+				TParams,
+				TSearch,
+				AuthenticateModeFromArgs<TArgs>,
+				TPreloaderContext
+			>({ ...state, ...resolveAuthenticateArgs(args) });
 		},
 		authenticateOptional(...args: unknown[]) {
 			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, "optional", TPreloaderContext>({

package/src/route-builder/create-root-layout.ts

@@ -4,6 +4,7 @@ import type { Location } from "../router-primitives/index.ts";
 import type { ResolvedAuth, ResolvedEnv, ResolvedQueryClient, ResolvedServerContext } from "./register.ts";
 import {
 	type AuthenticateMode,
+	type AuthenticateModeFromArgs,
 	BUILDER_MARKER,
 	type CacheConfig,
 	type DeferFn,
@@ -17,6 +18,7 @@ import {
 	type SearchParamsValidator,
 	type ServerThrowHelpers,
 	type ServerUrlHelpers,
+	resolveAuthenticateArgs,
 } from "./types.ts";
 
 /* ── callback context types (root-specific) ─────────────────────── */
@@ -302,7 +304,11 @@ interface RootBuilderAfterInput<TPath extends string, TParams, TSearch> extends
 	TSearch,
 	false
 > {
-	authenticate(...args: unknown[]): RootBuilderAfterAuthenticate<TPath, TParams, TSearch, true>;
+	/** Required by default; `.authenticate("optional")` lets anonymous requests through with `ctx.auth === null`. Other arguments are callerData for `authenticateFn`. */
+	authenticate<const TArgs extends readonly unknown[]>(
+		...args: TArgs
+	): RootBuilderAfterAuthenticate<TPath, TParams, TSearch, AuthenticateModeFromArgs<TArgs>>;
+	/** @deprecated Use `.authenticate("optional", ...callerData)`. */
 	authenticateOptional(...args: unknown[]): RootBuilderAfterAuthenticate<TPath, TParams, TSearch, "optional">;
 }
 
@@ -569,11 +575,10 @@ function createBuilderAfterInput<TPath extends string, TParams, TSearch>(
 ): RootBuilderAfterInput<TPath, TParams, TSearch> {
 	return {
 		...createBuilderAfterAuthenticate<TPath, TParams, TSearch, false>(state),
-		authenticate(...args: unknown[]) {
-			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, true>({
+		authenticate<const TArgs extends readonly unknown[]>(...args: TArgs) {
+			return createBuilderAfterAuthenticate<TPath, TParams, TSearch, AuthenticateModeFromArgs<TArgs>>({
 				...state,
-				authenticate: args,
-				authenticateMode: true,
+				...resolveAuthenticateArgs(args),
 			});
 		},
 		authenticateOptional(...args: unknown[]) {

package/src/route-builder/types.ts

@@ -8,6 +8,24 @@ export type { FlareStore, FlareStoreEntry, StaticEntryData };
 
 export type AuthenticateMode = false | "optional" | true;
 
+/** `.authenticate("optional", ...callerData)` is optional; any other argument list is callerData for a required gate. */
+export type AuthenticateModeFromArgs<TArgs extends readonly unknown[]> = TArgs extends readonly [
+	"optional",
+	...unknown[],
+]
+	? "optional"
+	: true;
+
+/** Runtime half of `AuthenticateModeFromArgs`: splits the mode from the callerData forwarded to `authenticateFn`. */
+export function resolveAuthenticateArgs(args: readonly unknown[]): {
+	authenticate: unknown[];
+	authenticateMode: "optional" | true;
+} {
+	return args[0] === "optional"
+		? { authenticate: args.slice(1), authenticateMode: "optional" }
+		: { authenticate: [...args], authenticateMode: true };
+}
+
 /**
  * Symbol marker for route builder chain methods that look like render fns
  * but return builder objects. Used to filter them out in SSR/hydration/navigation

package/src/router-primitives/types.ts

@@ -1,3 +1,4 @@
+import type { AuthenticateMode } from "../route-builder/types.ts";
 import type { SearchParams } from "../url/index.ts";
 
 export type PrefetchStrategy = false | "intent" | "render" | "viewport";
@@ -19,7 +20,7 @@ export type RouteMetaStatic = {
 };
 
 export type RouteMeta = {
-	authenticate?: boolean;
+	authenticate?: AuthenticateMode;
 	authorize?: boolean;
 	client?: RouteMetaClient;
 	intercept?: { from: readonly string[]; render: string };

package/src/server/index.ts

@@ -39,25 +39,33 @@ export type MountTarget =
 	  }
 	| ((request: Request, env: unknown, ctx: { waitUntil(p: Promise<unknown>): void }) => Response | Promise<Response>);
 
-export interface ServerBuilder<TExcluded extends string = never> {
+export interface ServerBuilder<
+	TExcluded extends string = never,
+	TAuth = unknown,
+	TServerContext = Record<string, unknown>,
+> {
+	/** Type-only: what `.authenticateFn()` and `.serverContext()` resolve to. Generated route types read it. */
+	readonly "~flare"?: { auth: TAuth; serverContext: TServerContext };
 	authenticateFn: "authenticateFn" extends TExcluded
 		? never
-		: <TAuth>(
+		: <TNewAuth>(
 				fn: (ctx: {
 					callerData?: unknown[];
 					env: unknown;
 					request: Request;
 					serverContext: Record<string, unknown>;
 					url: URL;
-				}) => TAuth | null | Promise<TAuth | null>,
-			) => ServerBuilder<TExcluded | "authenticateFn">;
-	cache: "cache" extends TExcluded ? never : (config: HandlerCacheConfig) => ServerBuilder<TExcluded | "cache">;
+				}) => TNewAuth | null | Promise<TNewAuth | null>,
+			) => ServerBuilder<TExcluded | "authenticateFn", TNewAuth, TServerContext>;
+	cache: "cache" extends TExcluded
+		? never
+		: (config: HandlerCacheConfig) => ServerBuilder<TExcluded | "cache", TAuth, TServerContext>;
 	fetch(request: Request, env?: unknown, ctx?: { waitUntil?: (p: Promise<unknown>) => void }): Promise<Response>;
 	getStaticParams(): Promise<StaticParamsMap>;
 	keepalive: "keepalive" extends TExcluded
 		? never
-		: (config: KeepaliveConfig) => ServerBuilder<TExcluded | "keepalive">;
-	mount(prefix: string, target: MountTarget): ServerBuilder<TExcluded>;
+		: (config: KeepaliveConfig) => ServerBuilder<TExcluded | "keepalive", TAuth, TServerContext>;
+	mount(prefix: string, target: MountTarget): ServerBuilder<TExcluded, TAuth, TServerContext>;
 	security: "security" extends TExcluded
 		? never
 		: (
@@ -69,15 +77,19 @@ export interface ServerBuilder<TExcluded extends string = never> {
 							request: Request;
 							serverContext: Record<string, unknown>;
 					  }) => SecurityConfig),
-			) => ServerBuilder<TExcluded | "security">;
+			) => ServerBuilder<TExcluded | "security", TAuth, TServerContext>;
 	serverContext: "serverContext" extends TExcluded
 		? never
 		: <T extends Record<string, unknown>>(
 				fn: (ctx: { env: unknown; request: Request }) => T | Promise<T>,
-			) => ServerBuilder<TExcluded | "serverContext">;
-	sitemap: "sitemap" extends TExcluded ? never : (config: SitemapSubmitConfig) => ServerBuilder<TExcluded | "sitemap">;
-	tracing: "tracing" extends TExcluded ? never : (config: TracingConfig) => ServerBuilder<TExcluded | "tracing">;
-	use(...args: (FlareMiddleware | PathMatcher | string)[]): ServerBuilder<TExcluded>;
+			) => ServerBuilder<TExcluded | "serverContext", TAuth, T>;
+	sitemap: "sitemap" extends TExcluded
+		? never
+		: (config: SitemapSubmitConfig) => ServerBuilder<TExcluded | "sitemap", TAuth, TServerContext>;
+	tracing: "tracing" extends TExcluded
+		? never
+		: (config: TracingConfig) => ServerBuilder<TExcluded | "tracing", TAuth, TServerContext>;
+	use(...args: (FlareMiddleware | PathMatcher | string)[]): ServerBuilder<TExcluded, TAuth, TServerContext>;
 }
 
 /* Internal implementation type — no exclusion tracking */

package/src/server-handler/index.ts

@@ -640,7 +640,6 @@ interface EngineResult {
 
 async function handleSitemapSubmitRequest<TEnv>(
 	request: Request,
-	url: URL,
 	env: TEnv,
 	sitemapConfig: SitemapSubmitConfig<TEnv>,
 ): Promise<Response> {
@@ -1154,7 +1153,7 @@ export function createServerHandler<
 
 						if (url.pathname === "/_flare/sitemap/submit" && config.sitemap) {
 							/* Internal endpoints bypass middleware response handlers — only security headers */
-							let sitemapResponse = await handleSitemapSubmitRequest(request, url, env, config.sitemap);
+							let sitemapResponse = await handleSitemapSubmitRequest(request, env, config.sitemap);
 							sitemapResponse = addSecurityHeaders(sitemapResponse, secHeaders);
 							return sitemapResponse;
 						}
@@ -1288,7 +1287,7 @@ export function createServerHandler<
 						   client hashes into the new artifacts. */
 						if (
 							staticMeta &&
-							match.route.o.authenticate !== true &&
+							!match.route.o.authenticate &&
 							match.route.o.authorize !== true &&
 							resolvedStore &&
 							!isISRBgRequest &&
@@ -1622,7 +1621,7 @@ export function createServerHandler<
 						 */
 						if (
 							staticMeta?.mode === "isr" &&
-							match.route.o.authenticate !== true &&
+							!match.route.o.authenticate &&
 							match.route.o.authorize !== true &&
 							resolvedStore &&
 							!isDataRequest &&