# @getforma/router

Route matching, browser and native adapters, navigation, layouts, actions and lifecycle contracts.

The router is optional. Use the same coordinated candidate as core, compiler, build and Rust. Keep one coordinator per document and retain ordinary document navigation outside the admitted profile.

Published declaration: [@getforma/router@3.2.0-rc.2](https://unpkg.com/@getforma/router@3.2.0-rc.2/dist/index.d.ts).

## Values and functions

### createBrowserAdapter

Function export

```ts
declare function createBrowserAdapter(): RouteAdapter;
```

Each route render runs once inside a separately disposable Forma root.

Related declarations: [`RouteAdapter`](/docs/3.2/api-router/#symbol-RouteAdapter)

### createHtmlAdapter

Function export

```ts
declare function createHtmlAdapter(options: HtmlAdapterOptions): RouteAdapter;
```

Explicitly registered static documents. Only the marked region is ever parsed.

Related declarations: [`HtmlAdapterOptions`](/docs/3.2/api-router/#symbol-HtmlAdapterOptions), [`RouteAdapter`](/docs/3.2/api-router/#symbol-RouteAdapter)

### createNativeAdapter

Function export

```ts
declare function createNativeAdapter(bootstrap: NavigationBootstrap): RouteAdapter;
```



Related declarations: [`NavigationBootstrap`](/docs/3.2/api-router/#symbol-NavigationBootstrap), [`RouteAdapter`](/docs/3.2/api-router/#symbol-RouteAdapter)

### createRouter

Function export

```ts
declare function createRouter(input: RouterOptions): Router;
```

One coordinator per Document. Private/native response cache capacity is deliberately zero.

Related declarations: [`Router`](/docs/3.2/api-router/#symbol-Router), [`RouterOptions`](/docs/3.2/api-router/#symbol-RouterOptions)

### defineRoutes

Function export

```ts
declare function defineRoutes(input: readonly RouteDefinition[]): readonly RouteDefinition[];
```

Copy and validate caller configuration; mutation of the source never changes matching.

Related declarations: [`RouteDefinition`](/docs/3.2/api-router/#symbol-RouteDefinition)

### Link

Function export

```ts
declare function Link(props: LinkProps): HTMLAnchorElement;
```

An ordinary anchor; interception belongs to the root coordinator.

Related declarations: [`LinkProps`](/docs/3.2/api-router/#symbol-LinkProps)

### matchRoutes

Function export

```ts
declare function matchRoutes(routes: readonly RouteDefinition[], pathname: string): readonly Match[] | null;
```



Related declarations: [`Match`](/docs/3.2/api-router/#symbol-Match), [`RouteDefinition`](/docs/3.2/api-router/#symbol-RouteDefinition)

### NavigationError

Class export

```ts
declare class NavigationError extends Error {
    readonly code: string;
    readonly documentRecovery: boolean;
    readonly revoke: boolean;
    constructor(code: string, documentRecovery?: boolean, revoke?: boolean);
}
```



### Outlet

Function export

```ts
declare function Outlet(props: {
    outlet: HTMLElement;
}): HTMLElement;
```

Return the exact child outlet supplied to a browser route render.

## Exported types

### Accessor

Type alias export

```ts
type Accessor<T> = () => T;
```



### ActionOutcome

Interface export

```ts
interface ActionOutcome {
    readonly outcome: 'success' | 'validation' | 'error' | 'redirect';
    readonly status: number;
    readonly data: Readonly<Record<string, unknown>>;
}
```



### AdapterSession

Interface export

```ts
interface AdapterSession {
    initialize?(context: NavigationContext): Promise<void>;
    prepare(context: NavigationContext): Promise<PreparedView | Redirect>;
    allowsAction?(url: URL): boolean;
    admitAction?(data: unknown, response: Response, url: URL): ActionOutcome;
    invalidate?(): void;
    dispose(): void;
}
```



Related declarations: [`ActionOutcome`](/docs/3.2/api-router/#symbol-ActionOutcome), [`NavigationContext`](/docs/3.2/api-router/#symbol-NavigationContext), [`PreparedView`](/docs/3.2/api-router/#symbol-PreparedView), [`Redirect`](/docs/3.2/api-router/#symbol-Redirect)

### HtmlAdapterOptions

Interface export

```ts
interface HtmlAdapterOptions {
    readonly head: string;
    readonly pages: readonly HtmlPage[];
}
```



Related declarations: [`HtmlPage`](/docs/3.2/api-router/#symbol-HtmlPage)

### HtmlPage

Interface export

```ts
interface HtmlPage {
    readonly path: string;
    readonly sha256: string;
    readonly title: string;
    readonly head: string;
}
```



**`sha256`**

SHA-256 of the complete UTF-8 generated document, emitted at build time.

**`head`**

Build-generated identity of the immutable head/policy/assets.

### LinkProps

Interface export

```ts
interface LinkProps {
    href: string | URL;
    children?: string | Node | readonly (string | Node)[];
    target?: string;
    download?: string;
    class?: string;
    native?: boolean;
    document?: Document;
}
```



**`native`**

Leave this link to the browser.

### LocationState

Interface export

```ts
interface LocationState {
    readonly url: URL;
    readonly key: string;
    readonly matches: readonly {
        readonly id: string;
        readonly params: Readonly<Record<string, string>>;
    }[];
}
```



### Match

Interface export

```ts
interface Match {
    readonly id: string;
    readonly params: Readonly<Record<string, string>>;
    readonly definition: RouteDefinition;
}
```



Related declarations: [`RouteDefinition`](/docs/3.2/api-router/#symbol-RouteDefinition)

### NavigationBootstrap

Interface export

```ts
interface NavigationBootstrap {
    readonly registrations: Readonly<Record<string, (element: HTMLElement, props: Record<string, unknown> | null) => unknown>>;
    readonly app: string;
    readonly build: string;
    readonly group: string;
    readonly owners: readonly string[];
}
```



### NavigationContext

Interface export

```ts
interface NavigationContext {
    readonly url: URL;
    readonly matches: readonly Match[];
    readonly signal: AbortSignal;
    readonly revalidate: boolean;
    readonly location: Accessor<LocationState>;
}
```



Related declarations: [`Accessor`](/docs/3.2/api-router/#symbol-Accessor), [`LocationState`](/docs/3.2/api-router/#symbol-LocationState), [`Match`](/docs/3.2/api-router/#symbol-Match)

### NavigationResult

Type alias export

```ts
type NavigationResult = {
    kind: 'committed';
    location: LocationState;
    ready: Promise<void>;
} | {
    kind: 'cancelled';
    reason: 'superseded' | 'unchanged' | 'disposed';
} | {
    kind: 'blocked';
} | {
    kind: 'document-navigation';
    reason: string;
} | {
    kind: 'failed';
    code: string;
};
```



Related declarations: [`LocationState`](/docs/3.2/api-router/#symbol-LocationState)

### PreparedView

Interface export

```ts
interface PreparedView {
    readonly title?: string;
    readonly status?: number;
    readonly focus?: HTMLElement;
    validate(): void;
    commit(): void;
    activate(): Promise<void>;
    dispose(): void;
}
```



### Redirect

Interface export

```ts
interface Redirect {
    readonly redirect: string;
}
```



### RenderContext

Interface export

```ts
interface RenderContext {
    readonly url: URL;
    readonly location: Accessor<LocationState>;
    readonly params: Readonly<Record<string, string>>;
    readonly outlet: HTMLElement;
    readonly signal: AbortSignal;
}
```



Related declarations: [`Accessor`](/docs/3.2/api-router/#symbol-Accessor), [`LocationState`](/docs/3.2/api-router/#symbol-LocationState)

**`url`**

Destination snapshot for one-time route initialization.

**`signal`**

Aborts if preparation is cancelled or this owner is released; retained owners stay live.

### RouteAdapter

Interface export

```ts
interface RouteAdapter {
    readonly kind: 'browser' | 'html' | 'native';
    connect(root: HTMLElement): AdapterSession;
}
```



Related declarations: [`AdapterSession`](/docs/3.2/api-router/#symbol-AdapterSession)

### RouteDefinition

Interface export

```ts
interface RouteDefinition {
    readonly id: string;
    readonly path?: string;
    readonly index?: true;
    readonly children?: readonly RouteDefinition[];
    readonly adapter?: RouteAdapter;
    readonly render?: (context: RenderContext) => Element;
    readonly reuseKey?: (context: Match) => string;
}
```



Related declarations: [`Match`](/docs/3.2/api-router/#symbol-Match), [`RenderContext`](/docs/3.2/api-router/#symbol-RenderContext), [`RouteAdapter`](/docs/3.2/api-router/#symbol-RouteAdapter)

### Router

Interface export

```ts
interface Router {
    readonly location: Accessor<LocationState>;
    readonly pending: Accessor<URL | undefined>;
    readonly mutation: Accessor<'idle' | 'submitting' | 'revalidating' | 'uncertain'>;
    readonly ready: Promise<void>;
    navigate(to: string | URL, options?: {
        replace?: boolean;
    }): Promise<NavigationResult>;
    revalidate(): Promise<NavigationResult>;
    prefetch(to: string | URL): Promise<'completed' | 'skipped' | 'cancelled'>;
    submit(form: HTMLFormElement, submitter?: HTMLElement): Promise<SubmissionResult>;
    beforeLeave(check: (next: URL, signal: AbortSignal) => boolean | Promise<boolean>): () => void;
    invalidateContext(): void;
    resolveUncertain(check: (signal: AbortSignal) => Promise<boolean>): Promise<boolean>;
    dispose(): void;
}
```



Related declarations: [`Accessor`](/docs/3.2/api-router/#symbol-Accessor), [`LocationState`](/docs/3.2/api-router/#symbol-LocationState), [`NavigationResult`](/docs/3.2/api-router/#symbol-NavigationResult), [`SubmissionResult`](/docs/3.2/api-router/#symbol-SubmissionResult)

**`resolveUncertain`**

Clear the unknown-outcome latch only after application status/idempotency evidence.

### RouterOptions

Interface export

```ts
interface RouterOptions {
    readonly routes: readonly RouteDefinition[];
    readonly root: HTMLElement;
    readonly adapter: RouteAdapter;
    readonly base?: string;
    readonly statusRegion?: HTMLElement;
    readonly title?: (location: LocationState) => string;
    readonly onError?: (code: string) => void;
    readonly onAction?: (outcome: ActionOutcome, form: HTMLFormElement) => void;
    readonly checkContext?: (signal: AbortSignal) => Promise<boolean>;
    readonly contextChannel?: string;
    readonly recoveryKey?: string;
    readonly canPrefetch?: (url: URL) => boolean;
}
```



Related declarations: [`ActionOutcome`](/docs/3.2/api-router/#symbol-ActionOutcome), [`LocationState`](/docs/3.2/api-router/#symbol-LocationState), [`RouteAdapter`](/docs/3.2/api-router/#symbol-RouteAdapter), [`RouteDefinition`](/docs/3.2/api-router/#symbol-RouteDefinition)

**`recoveryKey`**

Public, build-specific recovery namespace. Never put a user identifier here.

**`canPrefetch`**

Explicit server/application attestation that this GET is safe to speculate.

### SubmissionResult

Type alias export

```ts
type SubmissionResult = {
    kind: 'success';
} | {
    kind: 'validation' | 'error';
    status: number;
    data: Readonly<Record<string, unknown>>;
} | {
    kind: 'busy' | 'unsupported' | 'uncertain' | 'disposed';
};
```