flamefront 0.1.0-alpha.0 → 0.1.1

package/src/index.ts

@@ -1,12 +1,20 @@
 import {
   createMultiMatcher,
   type Match,
+  type MatchParams,
   type MultiMatcher,
 } from "@remix-run/route-pattern/match"
+import {
+  createHref as createPatternHref,
+  type CreateHrefArgs,
+} from "@remix-run/route-pattern/href"
 import type { HydrationInteractionEvents } from "octane/hydration"
 import { createRouteDataClient } from "./route-data-client.ts"
 import { stripFlamefrontProtocolParams } from "./fragment-protocol.ts"
 
+export { glob, joinRoutePath } from "./glob.ts"
+export type { GlobFile } from "./glob.ts"
+
 export type RenderMode = "client" | "server" | "static"
 
 export interface RoutingOptions {
@@ -51,6 +59,18 @@ export type GeneratedHydration =
  */
 export type HydrationMode = "full" | "deferred" | "none" | GeneratedHydration
 
+/** App-level fallbacks for routes that do not declare a hydration policy. */
+export interface HydrationDefaults {
+  readonly server?: HydrationMode
+  readonly static?: HydrationMode
+}
+
+/** Fully resolved app-level hydration fallbacks. */
+export interface NormalizedHydrationDefaults {
+  readonly server: HydrationMode
+  readonly static: HydrationMode
+}
+
 export type RouteNavigationStrategy = "router" | "fragment"
 
 export type RouteBoundaryKind = "shell" | "layout" | "route"
@@ -58,7 +78,7 @@ export type RouteBoundaryKind = "shell" | "layout" | "route"
 /** Metadata emitted on generated router nodes for route-aware navigation. */
 export interface GeneratedRouteMetadata {
   readonly id: string
-  /** Stable token used by the static-fragment boundary pass. */
+  /** Stable token used by the route-fragment boundary pass. */
   readonly boundary: string
   readonly kind: RouteBoundaryKind
   readonly entry: string
@@ -69,15 +89,22 @@ export interface GeneratedRouteMetadata {
   readonly hydration?: HydrationMode
 }
 
+export type RouteContent = "component" | "markdown"
+
 export interface RouteOptions {
+  /** The route entry's authored content shape. Omit for an Octane component. */
+  readonly content?: RouteContent
   readonly render?: RenderMode
   readonly hydration?: HydrationMode
 }
 
-export interface RouteDefinition extends RouteOptions {
-  readonly path: string
+export interface RouteDefinition<
+  Path extends string = string,
+  Entry extends string = string,
+> extends RouteOptions {
+  readonly path: Path
   /** Octane/Vite project-root module ID, such as `/src/Home.tsrx`. */
-  readonly entry: string
+  readonly entry: Entry
   readonly render: RenderMode
 }
 
@@ -92,35 +119,358 @@ export interface LayoutDefinition<
 
 export type RouteConfig = RouteDefinition | LayoutDefinition
 
+/** Flatten nested route configuration into the leaf route union. */
+export type RouteLeaf<Config> =
+  Config extends LayoutDefinition<infer Children>
+    ? number extends Children["length"]
+      ? RouteDefinition
+      : RouteLeaf<Children[number]>
+    : Config extends RouteDefinition
+      ? Config
+      : never
+
+export type RouteLeaves<Configs extends readonly RouteConfig[]> =
+  number extends Configs["length"]
+    ? RouteDefinition
+    : RouteLeaf<Configs[number]>
+
 export interface MatchRouteOptions {
   readonly render?: RenderMode
 }
 
+/**
+ * Route modules generated by Flamefront's optional declaration generator.
+ * Applications can use the authored route manifest without generated output;
+ * the empty base interface keeps that mode conservative.
+ */
+export interface RouteImportMap {}
+
+/** Parameters used when a route pattern is not available to the type system. */
+export type BroadRouteParams = Record<string, string | undefined>
+
+type RouteImportMapPath = Extract<keyof RouteImportMap, string>
+
+/** Route patterns emitted by Flamefront, or `string` before type generation. */
+export type RoutePath = [RouteImportMapPath] extends [never]
+  ? string
+  : RouteImportMapPath
+
+/**
+ * Parameters captured by a generated route pattern. A stale or missing map
+ * deliberately keeps the existing broad record behavior.
+ */
+type RouteParamsForKnownPath<Path extends string> = Path extends string
+  ? Path extends RouteImportMapPath
+    ? MatchParams<Path> extends infer Params
+      ? [Params] extends [never]
+        ? BroadRouteParams
+        : Params
+      : BroadRouteParams
+    : BroadRouteParams
+  : BroadRouteParams
+
+export type RouteParams<Path extends string = string> = [
+  RouteImportMapPath,
+] extends [never]
+  ? BroadRouteParams
+  : string extends Path
+    ? BroadRouteParams
+    : RouteParamsForKnownPath<Path>
+
+/** The route module associated with a generated route pattern. */
+export type RouteModuleFor<Path extends string = string> = [
+  RouteImportMapPath,
+] extends [never]
+  ? unknown
+  : Path extends RouteImportMapPath
+    ? RouteImportMap[Path]
+    : unknown
+
+type RouteLoaderFunction<Module> = Module extends {
+  readonly loader?: infer Loader
+}
+  ? Loader extends (...args: infer _Args) => infer Result
+    ? (...args: _Args) => Result
+    : never
+  : never
+
+/** The authored loader function associated with a generated route pattern. */
+export type RouteLoaderFor<Path extends string = string> = RouteLoaderFunction<
+  RouteModuleFor<Path>
+>
+
+/** The awaited result of a generated route's loader, or `unknown` as fallback. */
+export type RouteLoaderData<Path extends string = string> =
+  RouteLoaderFor<Path> extends (...args: infer _Args) => infer Result
+    ? Awaited<Result>
+    : unknown
+
+type RoutePageParams<Path extends RouteImportMapPath> =
+  keyof RouteParams<Path> extends never
+    ? BroadRouteParams
+    : RouteParams<Path> & Record<string, string | undefined>
+
+/** Registration shape for router libraries that expose typed route pages. */
+export type RoutePages = [RouteImportMapPath] extends [never]
+  ? Record<string, { readonly params: BroadRouteParams }>
+  : {
+      [Path in RouteImportMapPath]: {
+        readonly params: RoutePageParams<Path>
+      }
+    }
+
+declare module "@octanejs/remix-router" {
+  interface Register {
+    pages: RoutePages
+  }
+}
+
 export interface LoadRouteOptions {
   readonly signal?: AbortSignal
   readonly reload?: boolean
 }
 
+type TrimTrailingSlashes<Value extends string> = Value extends "/"
+  ? Value
+  : Value extends `${infer Path}/`
+    ? TrimTrailingSlashes<Path>
+    : Value
+
+type RoutePathname<Value extends string> = Value extends `${string}?${string}`
+  ? Value extends `${infer Path}?${string}`
+    ? RoutePathname<Path>
+    : string
+  : Value extends `${string}#${string}`
+    ? Value extends `${infer Path}#${string}`
+      ? RoutePathname<Path>
+      : string
+    : Value extends `/${string}`
+      ? TrimTrailingSlashes<Value>
+      : string
+
+type RouteSegments<Value extends string> = Value extends `/${infer Rest}`
+  ? Rest extends ""
+    ? []
+    : Rest extends `${infer Head}/${infer Tail}`
+      ? [Head, ...RouteSegments<`/${Tail}`>]
+      : [Rest]
+  : []
+
+type RouteSegmentMatches<
+  Pattern extends string,
+  Value extends string,
+> = Pattern extends `:${string}`
+  ? true
+  : Pattern extends `*${string}`
+    ? true
+    : Pattern extends `(${infer Optional})`
+      ? RouteSegmentMatches<Optional, Value>
+      : Pattern extends Value
+        ? true
+        : false
+
+type RoutePatternMatches<
+  Pattern extends readonly string[],
+  Value extends readonly string[],
+> = Pattern extends []
+  ? Value extends []
+    ? true
+    : false
+  : Pattern extends [infer Head extends string, ...infer Tail extends string[]]
+    ? Head extends `*${string}`
+      ? true
+      : Head extends `(${infer Optional})`
+        ? RoutePatternMatches<[Optional, ...Tail], [...Value]> extends true
+          ? true
+          : RoutePatternMatches<Tail, Value>
+        : Value extends [
+              infer ValueHead extends string,
+              ...infer ValueTail extends string[],
+            ]
+          ? RouteSegmentMatches<Head, ValueHead> extends true
+            ? RoutePatternMatches<Tail, ValueTail>
+            : false
+          : false
+    : false
+
+type RouteMatchesUrl<
+  Pattern extends string,
+  Url extends string,
+> = string extends Url
+  ? true
+  : RoutePatternMatches<
+      RouteSegments<RoutePathname<Pattern>>,
+      RouteSegments<RoutePathname<Url>>
+    >
+
+type MatchingRoutes<
+  Routes extends RouteDefinition,
+  Url extends string,
+> = Routes extends RouteDefinition
+  ? true extends RouteMatchesUrl<Routes["path"], Url>
+    ? Routes
+    : never
+  : never
+
+type ExactMatchingRoutes<
+  Routes extends RouteDefinition,
+  Url extends string,
+> = Routes extends RouteDefinition
+  ? Routes["path"] extends RoutePathname<Url>
+    ? Routes
+    : never
+  : never
+
+type MatchedRoutes<Routes extends RouteDefinition, Url extends string> = [
+  ExactMatchingRoutes<Routes, Url>,
+] extends [never]
+  ? MatchingRoutes<Routes, Url>
+  : ExactMatchingRoutes<Routes, Url>
+
+type MatchingImportMapPaths<
+  Url extends string,
+  Paths extends string = RouteImportMapPath,
+> = Paths extends string
+  ? true extends RouteMatchesUrl<Paths, Url>
+    ? Paths
+    : never
+  : never
+
+type ExactImportMapPaths<
+  Url extends string,
+  Paths extends string = RouteImportMapPath,
+> = Paths extends string
+  ? Paths extends RoutePathname<Url>
+    ? Paths
+    : never
+  : never
+
+type ImportMapPathsForUrl<Url extends string> = [
+  ExactImportMapPaths<Url>,
+] extends [never]
+  ? MatchingImportMapPaths<Url>
+  : ExactImportMapPaths<Url>
+
+type RoutesForUrl<Routes extends RouteDefinition, Url extends string> =
+  string extends RoutePathname<Url>
+    ? Routes
+    : [MatchedRoutes<Routes, Url>] extends [never]
+      ? Routes
+      : MatchedRoutes<Routes, Url>
+
+/** A matched route whose params retain the authored route pattern. */
+export type RouteMatch<Route extends RouteDefinition = RouteDefinition> = Omit<
+  Match<string, Route>,
+  "params"
+> & {
+  readonly params: RouteParams<Route["path"]>
+}
+
+type BroadRouteMatch<Route extends RouteDefinition> = Omit<
+  RouteMatch<Route>,
+  "params"
+> & {
+  readonly params: BroadRouteParams
+}
+
+/** Match result selected from a route union and a statically known URL. */
+export type RouteMatchForUrl<
+  Routes extends RouteDefinition,
+  Url extends string,
+> = string extends Url
+  ? BroadRouteMatch<Routes>
+  : string extends RoutePathname<Url>
+    ? BroadRouteMatch<Routes>
+    : RouteMatch<RoutesForUrl<Routes, Url>>
+
+/** Loader data selected from a route union and a statically known URL. */
+export type RouteDataForUrl<
+  Routes extends RouteDefinition,
+  Url extends string,
+> = string extends Url
+  ? unknown
+  : string extends RoutePathname<Url>
+    ? unknown
+    : [MatchedRoutes<Routes, Url>] extends [never]
+      ? unknown
+      : MatchedRoutes<Routes, Url> extends infer Route
+        ? Route extends RouteDefinition
+          ? RouteLoaderData<Route["path"]>
+          : unknown
+        : unknown
+
+/** Loader data selected directly from the generated map and a URL pathname. */
+export type RouteDataForPath<Url extends string> = string extends Url
+  ? unknown
+  : string extends RoutePathname<Url>
+    ? unknown
+    : [RouteImportMapPath] extends [never]
+      ? unknown
+      : [ImportMapPathsForUrl<Url>] extends [never]
+        ? unknown
+        : ImportMapPathsForUrl<Url> extends infer Path
+          ? Path extends string
+            ? RouteLoaderData<Path>
+            : unknown
+          : unknown
+
+/** A router destination constrained to generated route patterns when present. */
+export type RouteDestination<Path extends string = RoutePath> =
+  | Path
+  | {
+      readonly pathname: Path
+      readonly search?: string
+      readonly hash?: string
+      readonly state?: unknown
+    }
+
 export interface AppDefinition<T extends RouteDefinition = RouteDefinition> {
   /** Octane/Vite project-root module ID for the persistent app shell. */
   readonly shell: string
+  /** Hydration policy for the persistent shell region. */
+  readonly shellHydration: HydrationMode
   readonly routes: readonly T[]
   readonly routeTree: readonly RouteConfig[]
+  readonly hydrationDefaults: NormalizedHydrationDefaults
   readonly routing: NormalizedRoutingOptions
-  readonly match: (
-    url: string | URL,
-    options?: MatchRouteOptions,
-  ) => Match<string, T> | null
+  readonly match: {
+    <const Url extends string>(
+      url: Url,
+      options?: MatchRouteOptions,
+    ): RouteMatchForUrl<T, Url> | null
+    (url: URL, options?: MatchRouteOptions): RouteMatchForUrl<T, string> | null
+    (
+      url: string,
+      options?: MatchRouteOptions,
+    ): RouteMatchForUrl<T, string> | null
+    (
+      url: string | URL,
+      options?: MatchRouteOptions,
+    ): RouteMatchForUrl<T, string> | null
+  }
   /** Load route data using the route's live or static data source. */
-  readonly load: <Data = unknown>(
-    url: string | URL,
-    options?: LoadRouteOptions,
-  ) => Promise<Data>
+  readonly load: {
+    <const Url extends string>(
+      url: Url,
+      options?: LoadRouteOptions,
+    ): Promise<RouteDataForUrl<T, Url>>
+    <Data = unknown>(url: URL, options?: LoadRouteOptions): Promise<Data>
+    <Data = unknown>(url: string, options?: LoadRouteOptions): Promise<Data>
+    <Data = unknown>(
+      url: string | URL,
+      options?: LoadRouteOptions,
+    ): Promise<Data>
+  }
   /** Warm the same cache used by generated client route loaders. */
-  readonly prefetch: (
-    url: string | URL,
-    options?: LoadRouteOptions,
-  ) => Promise<void>
+  readonly prefetch: {
+    <const Url extends string>(
+      url: Url,
+      options?: LoadRouteOptions,
+    ): Promise<void>
+    (url: URL, options?: LoadRouteOptions): Promise<void>
+    (url: string, options?: LoadRouteOptions): Promise<void>
+    (url: string | URL, options?: LoadRouteOptions): Promise<void>
+  }
 }
 
 const defaultRoutingOptions: NormalizedRoutingOptions = Object.freeze({
@@ -128,6 +478,13 @@ const defaultRoutingOptions: NormalizedRoutingOptions = Object.freeze({
   dataPath: "/__flamefront/data",
 })
 
+const defaultHydrationDefaults: NormalizedHydrationDefaults = Object.freeze({
+  server: "full",
+  static: "full",
+})
+
+const defaultShellHydration: HydrationMode = "full"
+
 const renderModes: ReadonlySet<unknown> = new Set<RenderMode>([
   "client",
   "server",
@@ -193,6 +550,56 @@ function normalizeRoutingPath(
   return path.replace(/\/+$/, "") || "/"
 }
 
+function validateHydrationDefault(
+  hydration: unknown,
+  render: "server" | "static",
+): void {
+  validateHydrationMode(hydration, render, `hydrationDefaults.${render}`)
+}
+
+function normalizeHydrationDefaults(
+  options: HydrationDefaults | undefined = undefined,
+): NormalizedHydrationDefaults {
+  if (
+    options !== undefined &&
+    (!options || typeof options !== "object" || Array.isArray(options))
+  ) {
+    throw new TypeError("flamefront hydrationDefaults must be an object.")
+  }
+
+  if (options) {
+    const unexpected = Object.keys(options).find(
+      (key) => key !== "server" && key !== "static",
+    )
+
+    if (unexpected) {
+      throw new TypeError(
+        `flamefront hydrationDefaults has an unexpected ${JSON.stringify(unexpected)} option.`,
+      )
+    }
+  }
+
+  const server = options?.server ?? defaultHydrationDefaults.server
+  const staticMode = options?.static ?? defaultHydrationDefaults.static
+
+  validateHydrationDefault(server, "server")
+  validateHydrationDefault(staticMode, "static")
+
+  return Object.freeze({
+    server: freezeHydration(server) as HydrationMode,
+    static: freezeHydration(staticMode) as HydrationMode,
+  })
+}
+
+function normalizeShellHydration(
+  hydration: HydrationMode | undefined,
+): HydrationMode {
+  const normalized = hydration ?? defaultShellHydration
+
+  validateHydrationMode(normalized, "server", "shellHydration")
+  return freezeHydration(normalized) as HydrationMode
+}
+
 export function normalizeRoutingOptions(
   options: RoutingOptions | undefined = undefined,
 ): NormalizedRoutingOptions {
@@ -247,6 +654,17 @@ export function joinBasename(basename: string, pathname: string): string {
   return `${basename}${pathname.startsWith("/") ? pathname : `/${pathname}`}`
 }
 
+/** Build a concrete URL from one generated route pattern. */
+export function routeHref<const Path extends RoutePath>(
+  path: Path,
+  ...args: CreateHrefArgs<Path>
+): string {
+  return createPatternHref(path, ...args)
+}
+
+/** Alias for callers that prefer the `create*` naming convention. */
+export const createRouteHref = routeHref
+
 function assertString(value: unknown, name: string): asserts value is string {
   if (typeof value !== "string" || value.length === 0) {
     throw new TypeError(`flamefront ${name} must be a non-empty string.`)
@@ -355,12 +773,11 @@ function validateGeneratedHydration(
   }
 }
 
-function validateHydration(
-  routeDefinition: RouteDefinition,
+function validateHydrationMode(
+  hydration: unknown,
+  render: RenderMode,
   location: string,
 ): void {
-  const { hydration, render } = routeDefinition
-
   if (hydration === undefined) {
     return
   }
@@ -396,6 +813,17 @@ function validateHydration(
   }
 }
 
+function validateHydration(
+  routeDefinition: RouteDefinition,
+  location: string,
+): void {
+  validateHydrationMode(
+    routeDefinition.hydration,
+    routeDefinition.render,
+    location,
+  )
+}
+
 function freezeHydration(
   hydration: HydrationMode | undefined,
 ): HydrationMode | undefined {
@@ -437,6 +865,16 @@ function validateRoute(
 
   assertString(routeDefinition.entry, `route ${location} entry`)
 
+  if (
+    routeDefinition.content !== undefined &&
+    routeDefinition.content !== "component" &&
+    routeDefinition.content !== "markdown"
+  ) {
+    throw new TypeError(
+      `flamefront route ${location} content must be 'component' or 'markdown'.`,
+    )
+  }
+
   if (!renderModes.has(routeDefinition.render)) {
     throw new TypeError(
       `flamefront route ${location} render must be 'client', 'server', or 'static'.`,
@@ -447,12 +885,12 @@ function validateRoute(
 }
 
 /** Define one explicit route without relying on a filesystem convention. */
-export function route(
-  path: string,
-  entry: string,
+export function route<const Path extends string, const Entry extends string>(
+  path: Path,
+  entry: Entry,
   options: RouteOptions = {},
-): RouteDefinition {
-  const definition: RouteDefinition = {
+): RouteDefinition<Path, Entry> {
+  const definition: RouteDefinition<Path, Entry> = {
     path,
     entry,
     ...options,
@@ -464,6 +902,58 @@ export function route(
   return Object.freeze(definition)
 }
 
+/** Shorthand for a route with `render: "server"`. */
+export function serverRoute<
+  const Path extends string,
+  const Entry extends string,
+>(
+  path: Path,
+  entry: Entry,
+  options: Omit<RouteOptions, "render"> = {},
+): RouteDefinition<Path, Entry> {
+  return route(path, entry, { ...options, render: "server" })
+}
+
+/** Shorthand for a route with `render: "static"`. */
+export function staticRoute<
+  const Path extends string,
+  const Entry extends string,
+>(
+  path: Path,
+  entry: Entry,
+  options: Omit<RouteOptions, "render"> = {},
+): RouteDefinition<Path, Entry> {
+  return route(path, entry, { ...options, render: "static" })
+}
+
+/** Shorthand for a static route backed by a Sätteri `.md` entry. */
+export function markdownRoute<
+  const Path extends string,
+  const Entry extends string,
+>(
+  path: Path,
+  entry: Entry,
+  options: Omit<RouteOptions, "content"> = {},
+): RouteDefinition<Path, Entry> & { readonly content: "markdown" } {
+  return route(path, entry, {
+    ...options,
+    content: "markdown",
+    render: options.render ?? "static",
+  }) as RouteDefinition<Path, Entry> & { readonly content: "markdown" }
+}
+
+/** Shorthand for a route with `render: "client"`. */
+export function clientRoute<
+  const Path extends string,
+  const Entry extends string,
+>(
+  path: Path,
+  entry: Entry,
+  options: Omit<RouteOptions, "render"> = {},
+): RouteDefinition<Path, Entry> {
+  return route(path, entry, { ...options, render: "client" })
+}
+
 /** Group routes beneath a shared pathless layout without adding a URL segment. */
 export function layout<const Children extends readonly RouteConfig[]>(
   entry: string,
@@ -488,6 +978,7 @@ function isLayoutDefinition(config: RouteConfig): config is LayoutDefinition {
 function normalizeRouteTree(
   configs: readonly RouteConfig[],
   seenPaths: Set<string>,
+  hydrationDefaults: NormalizedHydrationDefaults,
   location = "",
 ): { tree: readonly RouteConfig[]; routes: readonly RouteDefinition[] } {
   const routes: RouteDefinition[] = []
@@ -513,6 +1004,7 @@ function normalizeRouteTree(
       const normalized = normalizeRouteTree(
         config.children,
         seenPaths,
+        hydrationDefaults,
         configLocation,
       )
 
@@ -524,19 +1016,24 @@ function normalizeRouteTree(
       })
     }
 
-    validateRoute(config, configLocation)
+    const hydration =
+      config.hydration ??
+      (config.render === "client" ? "full" : hydrationDefaults[config.render])
+    const normalizedRoute = {
+      ...config,
+      hydration: freezeHydration(hydration),
+    }
+
+    validateRoute(normalizedRoute, configLocation)
     if (seenPaths.has(config.path)) {
       throw new TypeError(`flamefront route path is duplicated: ${config.path}`)
     }
 
     seenPaths.add(config.path)
-    const normalizedRoute = Object.freeze({
-      ...config,
-      hydration: freezeHydration(config.hydration),
-    })
+    const frozenRoute = Object.freeze(normalizedRoute)
 
-    routes.push(normalizedRoute)
-    return normalizedRoute
+    routes.push(frozenRoute)
+    return frozenRoute
   })
 
   return { tree: Object.freeze(tree), routes: Object.freeze(routes) }
@@ -562,7 +1059,7 @@ function matchRoutes<T extends RouteDefinition>(
   url: string | URL,
   options: MatchRouteOptions = {},
   basename = "/",
-): Match<string, T> | null {
+): RouteMatch<T> | null {
   let matchers = matcherCache.get(routes)
 
   if (!matchers) {
@@ -589,7 +1086,7 @@ function matchRoutes<T extends RouteDefinition>(
     normalizedUrl.pathname = normalizedUrl.pathname.replace(/\/+$/, "")
   }
 
-  return matcher.match(normalizedUrl)
+  return matcher.match(normalizedUrl) as RouteMatch<T> | null
 }
 
 /** Normalize and validate the application's explicit route graph. */
@@ -597,9 +1094,14 @@ export function defineApp<
   const T extends {
     readonly shell: string
     readonly routes: readonly RouteConfig[]
+    readonly shellHydration?: HydrationMode
+    readonly hydrationDefaults?: HydrationDefaults
     readonly routing?: RoutingOptions
   },
->(options: T): Omit<T, "routes" | "routing"> & AppDefinition {
+>(
+  options: T,
+): Omit<T, "routes" | "routing" | "hydrationDefaults" | "shellHydration"> &
+  AppDefinition<RouteLeaves<T["routes"]>> {
   if (
     !options ||
     typeof options !== "object" ||
@@ -610,32 +1112,50 @@ export function defineApp<
 
   assertString(options.shell, "app shell entry")
 
-  const normalized = normalizeRouteTree(options.routes, new Set())
-  const frozenRoutes = normalized.routes
+  const hydrationDefaults = normalizeHydrationDefaults(
+    options.hydrationDefaults,
+  )
+  const shellHydration = normalizeShellHydration(options.shellHydration)
+  const normalized = normalizeRouteTree(
+    options.routes,
+    new Set(),
+    hydrationDefaults,
+  )
+
+  type AppRoute = RouteLeaves<T["routes"]>
+  const frozenRoutes = normalized.routes as readonly AppRoute[]
   const routing = normalizeRoutingOptions(options.routing)
   const routeDataClient = createRouteDataClient(routing)
-  const load = <Data = unknown>(
-    url: string | URL,
-    loadOptions: LoadRouteOptions = {},
-  ) => {
+  const load = ((url: string | URL, loadOptions: LoadRouteOptions = {}) => {
     const match = matchRoutes(frozenRoutes, url, {}, routing.basename)
     const source = match?.data.render === "static" ? "static" : "live"
 
-    return routeDataClient.load<Data>(url, source, loadOptions)
-  }
+    return routeDataClient.load(url, source, loadOptions)
+  }) as AppDefinition<AppRoute>["load"]
 
   const app = Object.freeze({
     ...options,
+    shellHydration,
+    hydrationDefaults,
     routes: frozenRoutes,
     routeTree: normalized.tree,
     routing,
-    match: (url: string | URL, matchOptions?: MatchRouteOptions) =>
-      matchRoutes(frozenRoutes, url, matchOptions, routing.basename),
+    match: ((url: string | URL, matchOptions?: MatchRouteOptions) =>
+      matchRoutes(
+        frozenRoutes,
+        url,
+        matchOptions,
+        routing.basename,
+      )) as AppDefinition<AppRoute>["match"],
     load,
-    prefetch: async (url: string | URL, loadOptions?: LoadRouteOptions) => {
-      await load(url, loadOptions)
-    },
-  }) as Omit<T, "routes" | "routing"> & AppDefinition
+    prefetch: (async (url: string | URL, loadOptions?: LoadRouteOptions) => {
+      const match = matchRoutes(frozenRoutes, url, {}, routing.basename)
+      const source = match?.data.render === "static" ? "static" : "live"
+
+      await routeDataClient.load(url, source, loadOptions)
+    }) as AppDefinition<AppRoute>["prefetch"],
+  }) as Omit<T, "routes" | "routing" | "hydrationDefaults" | "shellHydration"> &
+    AppDefinition<AppRoute>
 
   matcherCache.set(
     frozenRoutes,