RouterOptions

import type { RouterOptions } from "@shadow-js/router";

interface RouterOptions {
  /** Top-level routes, built with {@link defineRoute}. */
  readonly routes: readonly RouteDefinition[];
  /** Where locations come from. Defaults to the browser history of `window`, or memory history. */
  readonly history?: History;
  /** Mount point, for example `/app`. Matched at a segment boundary only. */
  readonly base?: string;
  /** Trailing-slash policy. Default `"never"`. */
  readonly trailingSlash?: "never" | "always" | "preserve";
  /**
   * Static segments compare ASCII case exactly, so `/About` and `/about` are two routes. Default `false`. Must match
   * the scanner's `caseSensitive` (the build rejects two routes that differ only in case when it is false).
   */
  readonly caseSensitive?: boolean;
  /**
   * Which routes this router matches. `"public"` leaves out the private routes (a `_`-prefixed path): a server router
   * for a request from outside uses it. Default `"all"`, the browser router's behavior.
   */
  readonly visibility?: "public" | "all";
  /** Serializes search objects for links and `navigate`. Default: the core canonical form. */
  readonly searchCodec?: SearchCodec;
  /** Initial context at the root, added to by `beforeLoad`. */
  readonly context?: Readonly<Record<string, unknown>>;
  /** Delay before a pending UI is shown. Default 1000 ms. */
  readonly pendingMs?: number;
  /** Minimum time a pending UI stays visible once shown. Default 500 ms. */
  readonly pendingMinMs?: number;
  /**
   * Optional capabilities, each imported from its own subpath: `scrollRestoration()` from
   * `@shadow-js/router/scroll`, `loaderCache()` from `/loaders`, `headManagement()` from `/head`,
   * `errorBoundaries()` from `/errors`, `matchFilters()` from `/filters`, `blockers()` from
   * `/blockers`, `viewTransitions()` from `/transitions` and `relativeLinks()` from `/relative`.
   * A route that uses `loader`, `head`, `error` or `matchFilters` needs its feature here; a router
   * refuses such a route at creation and names the feature. Default: none (the smallest router).
   */
  readonly features?: readonly RouterFeature[];
  /** Clock and timers. Default: the global clock. */
  readonly clock?: RouterClock;
  /** The window for listeners, scroll and storage. Default: the global `window`, if any. */
  readonly window?: RouterWindow;
  /** Receives background failures: preload and subscriber errors. Default: rethrown later. */
  readonly onError?: (error: unknown) => void;
  /**
   * Maps the error a route's `error` component is shown for a render failure, before the component
   * receives it. Default: the error itself. A server maps it to a public error in production, so the
   * component cannot show a message the visitor should not see. Its result must not throw.
   */
  readonly presentError?: (error: unknown) => unknown;
  /** Maximum redirects in one navigation. Default 20. */
  readonly maxRedirects?: number;
  /** Maximum length of a query string, in UTF-16 units. Default 4096. */
  readonly maxSearchLength?: number;
}