flamefront 0.0.0 → 0.1.0

package/src/index.ts

@@ -0,0 +1,1168 @@
+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 {
+  /** URL pathname prefix shared by app matching and generated routes. */
+  readonly basename?: string
+  /** Route-data endpoint pathname shared by browser loaders and the server. */
+  readonly dataPath?: string
+}
+
+export interface NormalizedRoutingOptions {
+  readonly basename: string
+  readonly dataPath: string
+}
+
+export interface IdleHydration {
+  readonly when: "idle"
+  readonly timeout?: number
+}
+
+export interface VisibleHydration {
+  readonly when: "visible"
+  readonly rootMargin?: string
+  readonly threshold?: number | readonly number[]
+}
+
+export interface InteractionHydration {
+  readonly when: "interaction"
+  readonly events?: HydrationInteractionEvents
+}
+
+export interface MediaHydration {
+  readonly when: "media"
+  readonly query: string
+}
+
+export type GeneratedHydration =
+  IdleHydration | VisibleHydration | InteractionHydration | MediaHydration
+
+/**
+ * `full` hydrates with the shell, `deferred` leaves boundaries to the route,
+ * `none` keeps server HTML inert, and an object generates one route boundary.
+ */
+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"
+
+/** Metadata emitted on generated router nodes for route-aware navigation. */
+export interface GeneratedRouteMetadata {
+  readonly id: string
+  /** Stable token used by the route-fragment boundary pass. */
+  readonly boundary: string
+  readonly kind: RouteBoundaryKind
+  readonly entry: string
+  readonly parent?: string
+  readonly path?: string
+  readonly render?: RenderMode
+  readonly navigation: RouteNavigationStrategy
+  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<
+  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: Entry
+  readonly render: RenderMode
+}
+
+export interface LayoutDefinition<
+  Children extends readonly RouteConfig[] = readonly RouteConfig[],
+> {
+  readonly kind: "layout"
+  /** Octane/Vite project-root module ID for the pathless layout component. */
+  readonly entry: string
+  readonly children: Children
+}
+
+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: {
+    <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: {
+    <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: {
+    <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({
+  basename: "/",
+  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",
+  "static",
+])
+const hydrationModes: ReadonlySet<unknown> = new Set([
+  "full",
+  "deferred",
+  "none",
+])
+const interactionEvents: ReadonlySet<string> = new Set([
+  "auxclick",
+  "beforeinput",
+  "click",
+  "compositionend",
+  "compositionstart",
+  "compositionupdate",
+  "contextmenu",
+  "dblclick",
+  "focusin",
+  "input",
+  "keydown",
+  "keyup",
+  "mousedown",
+  "mouseenter",
+  "mouseover",
+  "mouseup",
+  "pointerdown",
+  "pointerenter",
+  "pointerover",
+  "pointerup",
+  "touchend",
+  "touchstart",
+])
+const matcherCache = new WeakMap<
+  readonly RouteDefinition[],
+  Map<RenderMode | undefined, MultiMatcher<RouteDefinition>>
+>()
+
+function normalizeRoutingPath(
+  value: unknown,
+  name: string,
+  fallback: string,
+): string {
+  const path = value ?? fallback
+
+  if (typeof path !== "string" || path.length === 0) {
+    throw new TypeError(
+      `flamefront routing ${name} must be a non-empty string.`,
+    )
+  }
+
+  if (!path.startsWith("/")) {
+    throw new TypeError(`flamefront routing ${name} must start with '/'.`)
+  }
+
+  if (path.includes("?") || path.includes("#")) {
+    throw new TypeError(
+      `flamefront routing ${name} must be a pathname without a query or hash.`,
+    )
+  }
+
+  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 {
+  if (options !== undefined && (!options || typeof options !== "object")) {
+    throw new TypeError("flamefront routing options must be an object.")
+  }
+
+  return Object.freeze({
+    basename: normalizeRoutingPath(
+      options?.basename,
+      "basename",
+      defaultRoutingOptions.basename,
+    ),
+    dataPath: normalizeRoutingPath(
+      options?.dataPath,
+      "dataPath",
+      defaultRoutingOptions.dataPath,
+    ),
+  })
+}
+
+/** Remove the normalized app basename from a request pathname. */
+export function stripBasename(
+  pathname: string,
+  basename: string,
+): string | null {
+  if (basename === "/") {
+    return pathname
+  }
+
+  if (pathname === basename) {
+    return "/"
+  }
+
+  if (!pathname.startsWith(`${basename}/`)) {
+    return null
+  }
+
+  return pathname.slice(basename.length) || "/"
+}
+
+/** Prefix an app-relative route path with the normalized app basename. */
+export function joinBasename(basename: string, pathname: string): string {
+  if (basename === "/") {
+    return pathname || "/"
+  }
+
+  if (pathname === "/") {
+    return basename
+  }
+
+  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.`)
+  }
+}
+
+function assertOnlyKeys(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+  location: string,
+): void {
+  const allowed = new Set(keys)
+  const unexpected = Object.keys(value).find((key) => !allowed.has(key))
+
+  if (unexpected) {
+    throw new TypeError(
+      `flamefront route ${location} hydration has an unexpected ${JSON.stringify(unexpected)} option.`,
+    )
+  }
+}
+
+function assertThreshold(value: unknown, location: string): void {
+  const thresholds = Array.isArray(value) ? value : [value]
+
+  if (
+    thresholds.length === 0 ||
+    thresholds.some(
+      (threshold) =>
+        typeof threshold !== "number" ||
+        !Number.isFinite(threshold) ||
+        threshold < 0 ||
+        threshold > 1,
+    )
+  ) {
+    throw new TypeError(
+      `flamefront route ${location} hydration threshold must contain numbers from 0 through 1.`,
+    )
+  }
+}
+
+function validateGeneratedHydration(
+  hydration: Record<string, unknown>,
+  location: string,
+): void {
+  switch (hydration.when) {
+    case "idle":
+      assertOnlyKeys(hydration, ["when", "timeout"], location)
+      if (
+        hydration.timeout !== undefined &&
+        (typeof hydration.timeout !== "number" ||
+          !Number.isFinite(hydration.timeout) ||
+          hydration.timeout < 0)
+      ) {
+        throw new TypeError(
+          `flamefront route ${location} hydration timeout must be a non-negative number.`,
+        )
+      }
+
+      return
+    case "visible":
+      assertOnlyKeys(hydration, ["when", "rootMargin", "threshold"], location)
+      if (hydration.rootMargin !== undefined) {
+        assertString(
+          hydration.rootMargin,
+          `route ${location} hydration rootMargin`,
+        )
+      }
+
+      if (hydration.threshold !== undefined) {
+        assertThreshold(hydration.threshold, location)
+      }
+
+      return
+    case "interaction": {
+      assertOnlyKeys(hydration, ["when", "events"], location)
+      if (hydration.events === undefined) {
+        return
+      }
+
+      const events = Array.isArray(hydration.events)
+        ? hydration.events
+        : [hydration.events]
+
+      if (
+        events.length === 0 ||
+        events.some(
+          (event) => typeof event !== "string" || !interactionEvents.has(event),
+        )
+      ) {
+        throw new TypeError(
+          `flamefront route ${location} hydration events must be supported Octane interaction events.`,
+        )
+      }
+
+      return
+    }
+
+    case "media":
+      assertOnlyKeys(hydration, ["when", "query"], location)
+      assertString(hydration.query, `route ${location} hydration query`)
+      return
+    default:
+      throw new TypeError(
+        `flamefront route ${location} hydration trigger must be 'idle', 'visible', 'interaction', or 'media'.`,
+      )
+  }
+}
+
+function validateHydrationMode(
+  hydration: unknown,
+  render: RenderMode,
+  location: string,
+): void {
+  if (hydration === undefined) {
+    return
+  }
+
+  if (
+    typeof hydration === "object" &&
+    hydration !== null &&
+    !Array.isArray(hydration)
+  ) {
+    validateGeneratedHydration(
+      hydration as unknown as Record<string, unknown>,
+      location,
+    )
+    if (render !== "server" && render !== "static") {
+      throw new TypeError(
+        `flamefront route ${location} generated hydration requires render: 'server' or 'static'.`,
+      )
+    }
+
+    return
+  }
+
+  if (!hydrationModes.has(hydration)) {
+    throw new TypeError(
+      `flamefront route ${location} hydration must be 'full', 'deferred', 'none', or a trigger object.`,
+    )
+  }
+
+  if (render === "client" && hydration !== "full") {
+    throw new TypeError(
+      `flamefront route ${location} client hydration can only be 'full'.`,
+    )
+  }
+}
+
+function validateHydration(
+  routeDefinition: RouteDefinition,
+  location: string,
+): void {
+  validateHydrationMode(
+    routeDefinition.hydration,
+    routeDefinition.render,
+    location,
+  )
+}
+
+function freezeHydration(
+  hydration: HydrationMode | undefined,
+): HydrationMode | undefined {
+  if (typeof hydration !== "object" || hydration === null) {
+    return hydration
+  }
+
+  if (hydration.when === "visible" && Array.isArray(hydration.threshold)) {
+    return Object.freeze({
+      ...hydration,
+      threshold: Object.freeze([...hydration.threshold]),
+    })
+  }
+
+  if (hydration.when === "interaction" && Array.isArray(hydration.events)) {
+    return Object.freeze({
+      ...hydration,
+      events: Object.freeze([...hydration.events]),
+    })
+  }
+
+  return Object.freeze({ ...hydration })
+}
+
+function validateRoute(
+  routeDefinition: RouteDefinition,
+  location: string,
+): void {
+  if (!routeDefinition || typeof routeDefinition !== "object") {
+    throw new TypeError(`flamefront route ${location} must be an object.`)
+  }
+
+  assertString(routeDefinition.path, `route ${location} path`)
+  if (!routeDefinition.path.startsWith("/")) {
+    throw new TypeError(
+      `flamefront route ${location} path must start with '/'.`,
+    )
+  }
+
+  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'.`,
+    )
+  }
+
+  validateHydration(routeDefinition, location)
+}
+
+/** Define one explicit route without relying on a filesystem convention. */
+export function route<const Path extends string, const Entry extends string>(
+  path: Path,
+  entry: Entry,
+  options: RouteOptions = {},
+): RouteDefinition<Path, Entry> {
+  const definition: RouteDefinition<Path, Entry> = {
+    path,
+    entry,
+    ...options,
+    hydration: freezeHydration(options.hydration),
+    render: options.render ?? "server",
+  }
+
+  validateRoute(definition, "1")
+  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,
+  children: Children,
+): LayoutDefinition<Children> {
+  assertString(entry, "layout entry")
+  if (!Array.isArray(children)) {
+    throw new TypeError("flamefront layout children must be an array.")
+  }
+
+  return Object.freeze({
+    kind: "layout" as const,
+    entry,
+    children: Object.freeze([...children]) as unknown as Children,
+  })
+}
+
+function isLayoutDefinition(config: RouteConfig): config is LayoutDefinition {
+  return "kind" in config && config.kind === "layout"
+}
+
+function normalizeRouteTree(
+  configs: readonly RouteConfig[],
+  seenPaths: Set<string>,
+  hydrationDefaults: NormalizedHydrationDefaults,
+  location = "",
+): { tree: readonly RouteConfig[]; routes: readonly RouteDefinition[] } {
+  const routes: RouteDefinition[] = []
+  const tree = configs.map((config, index): RouteConfig => {
+    const configLocation = location
+      ? `${location}.${index + 1}`
+      : `${index + 1}`
+
+    if (!config || typeof config !== "object") {
+      throw new TypeError(
+        `flamefront route ${configLocation} must be an object.`,
+      )
+    }
+
+    if (isLayoutDefinition(config)) {
+      assertString(config.entry, `layout ${configLocation} entry`)
+      if (!Array.isArray(config.children)) {
+        throw new TypeError(
+          `flamefront layout ${configLocation} children must be an array.`,
+        )
+      }
+
+      const normalized = normalizeRouteTree(
+        config.children,
+        seenPaths,
+        hydrationDefaults,
+        configLocation,
+      )
+
+      routes.push(...normalized.routes)
+      return Object.freeze({
+        kind: "layout" as const,
+        entry: config.entry,
+        children: normalized.tree,
+      })
+    }
+
+    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 frozenRoute = Object.freeze(normalizedRoute)
+
+    routes.push(frozenRoute)
+    return frozenRoute
+  })
+
+  return { tree: Object.freeze(tree), routes: Object.freeze(routes) }
+}
+
+function createRouteMatcher<T extends RouteDefinition>(
+  routes: readonly T[],
+  render?: RenderMode,
+): MultiMatcher<T> {
+  const matcher = createMultiMatcher<T>()
+
+  for (const routeDefinition of routes) {
+    if (render === undefined || routeDefinition.render === render) {
+      matcher.add(routeDefinition.path, routeDefinition)
+    }
+  }
+
+  return matcher
+}
+
+function matchRoutes<T extends RouteDefinition>(
+  routes: readonly T[],
+  url: string | URL,
+  options: MatchRouteOptions = {},
+  basename = "/",
+): RouteMatch<T> | null {
+  let matchers = matcherCache.get(routes)
+
+  if (!matchers) {
+    matchers = new Map()
+    matcherCache.set(routes, matchers)
+  }
+
+  let matcher = matchers.get(options.render) as MultiMatcher<T> | undefined
+
+  if (!matcher) {
+    matcher = createRouteMatcher(routes, options.render)
+    matchers.set(options.render, matcher as MultiMatcher<RouteDefinition>)
+  }
+
+  const normalizedUrl = stripFlamefrontProtocolParams(url)
+  const appPathname = stripBasename(normalizedUrl.pathname, basename)
+
+  if (appPathname === null) {
+    return null
+  }
+
+  normalizedUrl.pathname = appPathname
+  if (normalizedUrl.pathname.length > 1) {
+    normalizedUrl.pathname = normalizedUrl.pathname.replace(/\/+$/, "")
+  }
+
+  return matcher.match(normalizedUrl) as RouteMatch<T> | null
+}
+
+/** Normalize and validate the application's explicit route graph. */
+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" | "hydrationDefaults" | "shellHydration"> &
+  AppDefinition<RouteLeaves<T["routes"]>> {
+  if (
+    !options ||
+    typeof options !== "object" ||
+    !Array.isArray(options.routes)
+  ) {
+    throw new TypeError("flamefront defineApp() requires a routes array.")
+  }
+
+  assertString(options.shell, "app shell entry")
+
+  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 = ((url: string | URL, loadOptions: LoadRouteOptions = {}) => {
+    const match = matchRoutes(frozenRoutes, url, {}, routing.basename)
+    const source = match?.data.render === "static" ? "static" : "live"
+
+    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,
+      )) as AppDefinition<AppRoute>["match"],
+    load,
+    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,
+    new Map([[undefined, createRouteMatcher(frozenRoutes)]]) as Map<
+      RenderMode | undefined,
+      MultiMatcher<RouteDefinition>
+    >,
+  )
+  return app
+}