@farm.js/core 0.1.0-beta.0

package/dist/client.d.mts

@@ -0,0 +1,329 @@
+export { n as APIClient, A as APIClientOptions, a as APIClientWithoutIntegrationsOptions, N as InferIntegrationOperationBody, P as InferIntegrationOperationQuery, Q as InferIntegrationOperationResponse, J as IntegrationAPI, D as IntegrationClient, E as IntegrationClientAliases, L as IntegrationClientData, s as IntegrationClientError, G as IntegrationClientOptions, H as IntegrationClientRequestOptions, F as IntegrationClientRoot, K as IntegrationClients, M as IntegrationOperationResult, T as IntegrationServerClient, U as IntegrationServerClientAliases, V as IntegrationServerClientOptions, W as IntegrationServerClientRequestOptions, X as IntegrationServerClientRoot, Y as IntegrationServerRequestLike, m as RouteAPIClient, o as ServerAPIClient, S as ServerAPIClientOptions, b as ServerAPIClientWithoutIntegrationsOptions, p as createAPIClient, t as createIntegrationApi, r as createIntegrationClient, u as createIntegrationClients, w as createIntegrationServerClient, v as createIntegrations, q as createServerAPIClient, x as getIntegrationAPIManifest, y as integrationClients, z as integrationsClient, B as integrationsServer } from './client-D_yUjVhe.mjs';
+export { ServerQueryFetchOptions, UseServerQueryOptions, UseServerQueryResult, fetchServerQuery, prefetchServerQuery, useServerQuery } from './server-query-client.mjs';
+export { F as FarmIntegrationAPI, e as FarmIntegrationAPIBodyFormat, f as FarmIntegrationAPIMethod, a as FarmIntegrationAPIOperation, g as FarmIntegrationAPIResponseFormat, b as api, d as defineIntegrationAPI, c as defineIntegrationAPIOperation, i as endpoint } from './integration-api-CHT2OKAf.mjs';
+import React__default, { AnchorHTMLAttributes, RefObject } from 'react';
+import { FarmRouterPathParams, FarmRouterPathParam, FarmRouterBuildOptions, FarmRouterRouteInput } from './router.mjs';
+import { F as FarmClientPluginManager } from './plugin-BJDf43dc.mjs';
+export { a as FarmClientHydrationCompleteEvent, b as FarmClientHydrationEvent, d as FarmClientHydrationMode, e as FarmClientHydrationSession, f as FarmClientLocation, g as FarmClientNavigationAction, h as FarmClientNavigationErrorEvent, i as FarmClientNavigationEvent, j as FarmClientNavigationLoadedEvent, k as FarmClientNavigationResolvedEvent, l as FarmClientNavigationSession, m as FarmClientPerformanceEvent, n as FarmClientPlugin, o as FarmClientPluginCloseEvent, p as FarmClientPluginEnforce, q as FarmClientPluginErrorEvent, r as FarmClientPluginErrorPhase, s as FarmClientPluginManagerOptions, t as FarmClientPluginMetadata, u as FarmClientPluginRegistration, v as FarmClientPluginRouter, w as FarmClientPluginSetupEvent, x as FarmClientPluginStateEvent, c as createClientPluginManager } from './plugin-BJDf43dc.mjs';
+import { a as FarmI18nClientSnapshot, c as FarmI18nLocale } from './types-BH1lhg5G.mjs';
+export { F as FarmChunkRecoveryOptions, i as installChunkErrorRecovery, a as isChunkLoadError } from './production-runtime-C_B79w2P.mjs';
+import './client-cache-D-EZ7XVW.mjs';
+import './cache.mjs';
+import './server-query.mjs';
+import './server-fn.mjs';
+
+type StoreState = Record<string, any>;
+type StoreValueUpdater<T> = T | ((previous: T) => T);
+type StorePatch<T extends StoreState> = Partial<T> | ((state: T) => Partial<T>);
+type StoreListener<T extends StoreState> = (state: T, previousState: T) => void;
+type StoreKeyListener<T extends StoreState, K extends keyof T> = (value: T[K], previousValue: T[K]) => void;
+type StoreKeysListener<T extends StoreState, K extends keyof T> = (value: Pick<T, K>, previousValue: Pick<T, K>) => void;
+type FieldAccessor<T extends StoreState, K extends keyof T> = {
+    (): T[K];
+    get(): T[K];
+    set(value: StoreValueUpdater<T[K]>): T[K];
+    subscribe(listener: StoreKeyListener<T, K>): () => void;
+};
+type StoreFields<T extends StoreState> = {
+    [K in keyof T]: FieldAccessor<T, K>;
+};
+interface StoreApi<T extends StoreState> {
+    use(): T;
+    use<K extends keyof T>(key: K): T[K];
+    use<K extends keyof T>(keys: readonly K[]): Pick<T, K>;
+    get(): T;
+    get<K extends keyof T>(key: K): T[K];
+    set<K extends keyof T>(key: K, value: StoreValueUpdater<T[K]>): T[K];
+    set(patch: StorePatch<T>): T;
+    replace(nextState: T | ((state: T) => T)): T;
+    reset(): T;
+    subscribe(listener: StoreListener<T>): () => void;
+    subscribe<K extends keyof T>(key: K, listener: StoreKeyListener<T, K>): () => void;
+    subscribe<K extends keyof T>(keys: readonly K[], listener: StoreKeysListener<T, K>): () => void;
+}
+type Store<T extends StoreState, TMethods extends Record<string, any> = {}> = StoreApi<T> & StoreFields<T> & TMethods;
+declare function createStore<T extends StoreState, TMethods extends Record<string, any> = {}>(initialState: T, extend?: (store: Store<T>) => TMethods): Store<T, TMethods>;
+
+/**
+ * Farm.js SPA Router
+ *
+ * Provides client-side navigation without full page reloads.
+ * Features:
+ * - Prefetch on viewport intersection
+ * - Prefetch on hover
+ * - Page caching
+ * - History API integration
+ * - Scroll restoration
+ */
+interface PageData {
+    props: Record<string, any>;
+    modulePath: string;
+    canonicalPath?: string;
+    isClientComponent?: boolean;
+    shouldHydrate?: boolean;
+    metadata?: {
+        title?: string;
+        description?: string;
+    };
+    layoutModules?: string[];
+    i18n?: FarmI18nClientSnapshot;
+}
+interface RouterOptions {
+    prefetchTimeout?: number;
+    cacheMaxAge?: number;
+    scrollRestoration?: boolean;
+    shouldUseDocumentNavigation?: (pathname: string) => boolean;
+    deploymentId?: string;
+}
+interface FarmNavigationBlockerContext {
+    from: string;
+    to: string;
+    action: "push" | "replace" | "pop";
+}
+type FarmNavigationBlocker = (context: FarmNavigationBlockerContext) => boolean | void | Promise<boolean | void>;
+type FarmViewTransitionMode = boolean | "auto";
+interface FarmNavigateOptions {
+    replace?: boolean;
+    scroll?: boolean;
+    state?: unknown;
+    viewTransition?: FarmViewTransitionMode;
+}
+interface FarmNavigationLocation {
+    href: string;
+    pathname: string;
+    search: string;
+    hash: string;
+}
+interface FarmNavigationState {
+    state: "idle" | "loading";
+    pending: boolean;
+    from: string | null;
+    to: FarmNavigationLocation | null;
+    action: FarmNavigationBlockerContext["action"] | null;
+    startedAt: number | null;
+}
+type FarmNavigationListener = (state: FarmNavigationState) => void;
+declare class SPARouter {
+    private cache;
+    private prefetchingUrls;
+    private observers;
+    private blockers;
+    private navigationListeners;
+    private navigationState;
+    private scrollElements;
+    private options;
+    private onNavigate?;
+    private clientPlugins?;
+    constructor(options?: RouterOptions);
+    /**
+     * Set the navigation handler that updates React
+     */
+    setNavigationHandler(handler: (data: PageData) => Promise<void>): void;
+    /**
+     * Connect Farm's browser plugin lifecycle to SPA navigation.
+     */
+    setClientPluginManager(manager: FarmClientPluginManager): void;
+    /**
+     * Navigate to a new URL
+     */
+    navigate(href: string, options?: FarmNavigateOptions): Promise<void>;
+    /**
+     * Prefetch a URL
+     */
+    prefetch(href: string): Promise<void>;
+    /**
+     * Observe an element for viewport intersection (prefetch when visible)
+     */
+    observeForPrefetch(element: HTMLAnchorElement): void;
+    /**
+     * Stop observing an element
+     */
+    unobserveForPrefetch(element: HTMLAnchorElement): void;
+    addBlocker(blocker: FarmNavigationBlocker): () => void;
+    getNavigationState(): FarmNavigationState;
+    subscribeNavigation(listener: FarmNavigationListener): () => void;
+    registerScrollElement(key: string, element: HTMLElement): () => void;
+    pushState(state: unknown, href?: string): void;
+    replaceState(state: unknown, href?: string): void;
+    private commitNavigation;
+    private runViewTransition;
+    /**
+     * Fetch page data from cache or server
+     */
+    private fetchPageData;
+    /**
+     * Handle browser back/forward navigation
+     */
+    private handlePopState;
+    /**
+     * Check if URL is cached
+     */
+    private isCached;
+    /**
+     * Check if URL is external
+     */
+    private isExternalUrl;
+    private shouldBlockNavigation;
+    private startNavigation;
+    private finishNavigation;
+    private setNavigationState;
+    private writePageState;
+    /**
+     * Save scroll position for a path
+     */
+    private saveScrollPosition;
+    /**
+     * Restore scroll position for a path
+     */
+    private restoreScrollPosition;
+    private restoreScrollElement;
+    /**
+     * Clear the page cache
+     */
+    clearCache(): void;
+}
+/**
+ * Get or create the global router instance
+ */
+declare function getRouter(): SPARouter;
+/**
+ * Navigate to a URL using the SPA router
+ */
+declare function navigateTo(href: string, options?: FarmNavigateOptions): Promise<void>;
+/**
+ * Prefetch a URL
+ */
+declare function prefetch(href: string): Promise<void>;
+declare function pushState(state: unknown, href?: string): void;
+declare function replaceState(state: unknown, href?: string): void;
+declare function readPageState<TState = unknown>(): TState | null;
+
+/**
+ * Prefetch strategy (TanStack Router–style):
+ * - "intent": prefetch on hover and touchstart (with prefetchDelay)
+ * - "viewport": prefetch when link enters viewport (IntersectionObserver)
+ * - "render": prefetch as soon as the link is mounted
+ * - "none" | false: no prefetch
+ */
+type PrefetchBehavior = false | "intent" | "viewport" | "render" | "none";
+/** @internal Legacy prefetch mode for backward compatibility */
+type PrefetchLegacy = boolean | "hover" | "viewport" | "none";
+/**
+ * Augment this interface via your generated farm-routes.d.ts so Link href is typed
+ * without passing a generic. Defaults to string when not augmented.
+ */
+interface LinkDefaultRoute {
+}
+type DefaultRoutePath = LinkDefaultRoute extends {
+    _: infer TRoute extends string;
+} ? TRoute : string;
+type DefaultRoutePattern = LinkDefaultRoute extends {
+    pattern: infer TRoute extends string;
+} ? TRoute : DefaultRoutePath;
+type DefaultRouteHref = DefaultRoutePath | DefaultRoutePattern;
+type RouteHref<TRoute extends string> = TRoute | `${TRoute}?${string}` | `${TRoute}#${string}` | `${TRoute}?${string}#${string}`;
+type RouteParamValue = Exclude<FarmRouterPathParam, null | undefined>;
+type RouteOptionalParamValue = FarmRouterPathParam;
+type RouteParams<TRoute extends string> = string extends TRoute ? FarmRouterPathParams : ExtractRouteParams<StripRouteSuffix<TRoute>>;
+/** External URLs; these are never type-checked as routes. */
+type ExternalHref = `http://${string}` | `https://${string}` | `//${string}` | `mailto:${string}`;
+type StripRouteSuffix<TRoute extends string> = TRoute extends `${infer Path}?${string}` ? StripRouteSuffix<Path> : TRoute extends `${infer Path}#${string}` ? StripRouteSuffix<Path> : TRoute;
+type ExtractRouteParams<TRoute extends string> = Simplify<ExtractOptionalCatchAllParams<TRoute> & ExtractCatchAllParams<TRoute> & ExtractDynamicParams<TRoute>>;
+type ExtractOptionalCatchAllParams<TRoute extends string> = TRoute extends `${string}[[...${infer Param}]]${infer Rest}` ? {
+    [Key in Param]?: RouteOptionalParamValue;
+} & ExtractOptionalCatchAllParams<Rest> : {};
+type ExtractCatchAllParams<TRoute extends string> = TRoute extends `${string}[...${infer Param}]${infer Rest}` ? Param extends `[...${string}` ? ExtractCatchAllParams<Rest> : {
+    [Key in Param]: RouteParamValue;
+} & ExtractCatchAllParams<Rest> : {};
+type ExtractDynamicParams<TRoute extends string> = TRoute extends `${string}[${infer Param}]${infer Rest}` ? Param extends `...${string}` | `[...${string}` ? ExtractDynamicParams<Rest> : {
+    [Key in Param]: RouteParamValue;
+} & ExtractDynamicParams<Rest> : {};
+type Simplify<T> = {
+    [Key in keyof T]: T[Key];
+} & {};
+type HasRouteParams<TRoute extends string> = keyof RouteParams<TRoute> extends never ? false : true;
+type RoutesWithRequiredParams<TRoute extends string> = TRoute extends string ? HasRouteParams<TRoute> extends true ? TRoute : never : never;
+type LinkRouteParamsProps<TRoute extends string> = string extends TRoute ? {
+    params?: FarmRouterPathParams;
+} : HasRouteParams<TRoute> extends true ? {
+    params: RouteParams<TRoute>;
+} : {
+    params?: FarmRouterPathParams;
+};
+type LinkRouteTargetProps<TRoute extends string> = [RoutesWithRequiredParams<TRoute>] extends [
+    never
+] ? {
+    /** Internal route path with all params already resolved. */
+    href: RouteHref<TRoute>;
+    params?: FarmRouterPathParams;
+} : TRoute extends string ? {
+    /** Internal route path or route pattern. */
+    href: RouteHref<TRoute>;
+} & LinkRouteParamsProps<TRoute> : never;
+type LinkExternalTargetProps = {
+    /** External URL; these are never type-checked as app routes. */
+    href: ExternalHref;
+    params?: never;
+};
+type LinkTargetProps<TRoute extends string> = LinkExternalTargetProps | LinkRouteTargetProps<TRoute>;
+type LinkProps<TRoute extends string = DefaultRouteHref> = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> & LinkTargetProps<TRoute> & {
+    /**
+     * When to prefetch. TanStack-style: "intent" (hover+touch), "viewport", "render", or "none".
+     * Legacy: true (intent+viewport), "hover" (intent), "viewport", false/"none".
+     */
+    prefetch?: PrefetchBehavior | PrefetchLegacy;
+    /** Search params appended after route params are resolved. */
+    query?: FarmRouterBuildOptions["query"];
+    /** Hash appended after route params and search params are resolved. */
+    hash?: string;
+    /** Add a trailing slash to the generated internal href. */
+    trailingSlash?: boolean;
+    /** Delay in ms before intent-based prefetch (hover/touch). Default 50. */
+    prefetchDelay?: number;
+    /** Replace current history entry instead of pushing */
+    replace?: boolean;
+    /** Scroll to top after navigation (default: true) */
+    scroll?: boolean;
+    /** Wrap this SPA navigation in a browser View Transition when supported. */
+    viewTransition?: FarmViewTransitionMode;
+    /** Preserve the active locale by default, or navigate using this locale. */
+    locale?: FarmI18nLocale;
+};
+type LinkComponentType = <TRoute extends string = DefaultRouteHref>(props: LinkProps<TRoute> & {
+    ref?: React__default.ForwardedRef<HTMLAnchorElement>;
+}) => React__default.ReactElement;
+declare const Link: LinkComponentType;
+
+interface UseRouterOptions {
+    basePath?: string;
+    routes?: FarmRouterRouteInput[];
+}
+interface UseBlockerOptions {
+    when: boolean | ((context: FarmNavigationBlockerContext) => boolean);
+    message?: string;
+    shouldBlock?: (context: FarmNavigationBlockerContext) => boolean | Promise<boolean>;
+}
+interface UseBlockerReturn {
+    active: boolean;
+}
+/**
+ * Hook for accessing router state and navigation
+ */
+declare function useRouter(options?: UseRouterOptions): {
+    push: (href: string) => void;
+    replace: (href: string) => void;
+    pushState: <TState>(pageState: TState, href?: string) => void;
+    replaceState: <TState>(pageState: TState, href?: string) => void;
+    back: () => void;
+    forward: () => void;
+    pathname: string;
+    searchParams: URLSearchParams;
+    params: Record<string, string>;
+    pageState: unknown;
+};
+declare function usePageState<TState = unknown>(): TState | null;
+declare function useNavigation(): FarmNavigationState;
+declare function useBlocker(options: UseBlockerOptions): UseBlockerReturn;
+declare function useScrollRestoration<TElement extends HTMLElement = HTMLElement>(key: string): RefObject<TElement>;
+
+export { type DefaultRouteHref, type DefaultRoutePath, type DefaultRoutePattern, type ExternalHref, FarmClientPluginManager, type FarmNavigateOptions, type FarmNavigationBlocker, type FarmNavigationBlockerContext, type FarmNavigationListener, type FarmNavigationLocation, type FarmNavigationState, type FarmViewTransitionMode, Link, type LinkDefaultRoute, type LinkProps, type PrefetchBehavior, type RouteHref, type RouteOptionalParamValue, type RouteParamValue, type RouteParams, SPARouter, type Store, type StoreApi, type StoreFields, type StoreKeyListener, type StoreKeysListener, type StoreListener, type StorePatch, type StoreState, type StoreValueUpdater, type UseBlockerOptions, type UseBlockerReturn, type UseRouterOptions, createStore, getRouter, navigateTo, prefetch, pushState, readPageState, replaceState, useBlocker, useNavigation, usePageState, useRouter, useScrollRestoration };

package/dist/client.d.ts

@@ -0,0 +1,329 @@
+export { n as APIClient, A as APIClientOptions, a as APIClientWithoutIntegrationsOptions, N as InferIntegrationOperationBody, P as InferIntegrationOperationQuery, Q as InferIntegrationOperationResponse, J as IntegrationAPI, D as IntegrationClient, E as IntegrationClientAliases, L as IntegrationClientData, s as IntegrationClientError, G as IntegrationClientOptions, H as IntegrationClientRequestOptions, F as IntegrationClientRoot, K as IntegrationClients, M as IntegrationOperationResult, T as IntegrationServerClient, U as IntegrationServerClientAliases, V as IntegrationServerClientOptions, W as IntegrationServerClientRequestOptions, X as IntegrationServerClientRoot, Y as IntegrationServerRequestLike, m as RouteAPIClient, o as ServerAPIClient, S as ServerAPIClientOptions, b as ServerAPIClientWithoutIntegrationsOptions, p as createAPIClient, t as createIntegrationApi, r as createIntegrationClient, u as createIntegrationClients, w as createIntegrationServerClient, v as createIntegrations, q as createServerAPIClient, x as getIntegrationAPIManifest, y as integrationClients, z as integrationsClient, B as integrationsServer } from './client-Dkc03WP8.js';
+export { ServerQueryFetchOptions, UseServerQueryOptions, UseServerQueryResult, fetchServerQuery, prefetchServerQuery, useServerQuery } from './server-query-client.js';
+export { F as FarmIntegrationAPI, e as FarmIntegrationAPIBodyFormat, f as FarmIntegrationAPIMethod, a as FarmIntegrationAPIOperation, g as FarmIntegrationAPIResponseFormat, b as api, d as defineIntegrationAPI, c as defineIntegrationAPIOperation, i as endpoint } from './integration-api-CHT2OKAf.js';
+import React__default, { AnchorHTMLAttributes, RefObject } from 'react';
+import { FarmRouterPathParams, FarmRouterPathParam, FarmRouterBuildOptions, FarmRouterRouteInput } from './router.js';
+import { F as FarmClientPluginManager } from './plugin-BJDf43dc.js';
+export { a as FarmClientHydrationCompleteEvent, b as FarmClientHydrationEvent, d as FarmClientHydrationMode, e as FarmClientHydrationSession, f as FarmClientLocation, g as FarmClientNavigationAction, h as FarmClientNavigationErrorEvent, i as FarmClientNavigationEvent, j as FarmClientNavigationLoadedEvent, k as FarmClientNavigationResolvedEvent, l as FarmClientNavigationSession, m as FarmClientPerformanceEvent, n as FarmClientPlugin, o as FarmClientPluginCloseEvent, p as FarmClientPluginEnforce, q as FarmClientPluginErrorEvent, r as FarmClientPluginErrorPhase, s as FarmClientPluginManagerOptions, t as FarmClientPluginMetadata, u as FarmClientPluginRegistration, v as FarmClientPluginRouter, w as FarmClientPluginSetupEvent, x as FarmClientPluginStateEvent, c as createClientPluginManager } from './plugin-BJDf43dc.js';
+import { a as FarmI18nClientSnapshot, c as FarmI18nLocale } from './types-BH1lhg5G.js';
+export { F as FarmChunkRecoveryOptions, i as installChunkErrorRecovery, a as isChunkLoadError } from './production-runtime-DDEM1D2q.js';
+import './client-cache-CIlyBlmx.js';
+import './cache.js';
+import './server-query.js';
+import './server-fn.js';
+
+type StoreState = Record<string, any>;
+type StoreValueUpdater<T> = T | ((previous: T) => T);
+type StorePatch<T extends StoreState> = Partial<T> | ((state: T) => Partial<T>);
+type StoreListener<T extends StoreState> = (state: T, previousState: T) => void;
+type StoreKeyListener<T extends StoreState, K extends keyof T> = (value: T[K], previousValue: T[K]) => void;
+type StoreKeysListener<T extends StoreState, K extends keyof T> = (value: Pick<T, K>, previousValue: Pick<T, K>) => void;
+type FieldAccessor<T extends StoreState, K extends keyof T> = {
+    (): T[K];
+    get(): T[K];
+    set(value: StoreValueUpdater<T[K]>): T[K];
+    subscribe(listener: StoreKeyListener<T, K>): () => void;
+};
+type StoreFields<T extends StoreState> = {
+    [K in keyof T]: FieldAccessor<T, K>;
+};
+interface StoreApi<T extends StoreState> {
+    use(): T;
+    use<K extends keyof T>(key: K): T[K];
+    use<K extends keyof T>(keys: readonly K[]): Pick<T, K>;
+    get(): T;
+    get<K extends keyof T>(key: K): T[K];
+    set<K extends keyof T>(key: K, value: StoreValueUpdater<T[K]>): T[K];
+    set(patch: StorePatch<T>): T;
+    replace(nextState: T | ((state: T) => T)): T;
+    reset(): T;
+    subscribe(listener: StoreListener<T>): () => void;
+    subscribe<K extends keyof T>(key: K, listener: StoreKeyListener<T, K>): () => void;
+    subscribe<K extends keyof T>(keys: readonly K[], listener: StoreKeysListener<T, K>): () => void;
+}
+type Store<T extends StoreState, TMethods extends Record<string, any> = {}> = StoreApi<T> & StoreFields<T> & TMethods;
+declare function createStore<T extends StoreState, TMethods extends Record<string, any> = {}>(initialState: T, extend?: (store: Store<T>) => TMethods): Store<T, TMethods>;
+
+/**
+ * Farm.js SPA Router
+ *
+ * Provides client-side navigation without full page reloads.
+ * Features:
+ * - Prefetch on viewport intersection
+ * - Prefetch on hover
+ * - Page caching
+ * - History API integration
+ * - Scroll restoration
+ */
+interface PageData {
+    props: Record<string, any>;
+    modulePath: string;
+    canonicalPath?: string;
+    isClientComponent?: boolean;
+    shouldHydrate?: boolean;
+    metadata?: {
+        title?: string;
+        description?: string;
+    };
+    layoutModules?: string[];
+    i18n?: FarmI18nClientSnapshot;
+}
+interface RouterOptions {
+    prefetchTimeout?: number;
+    cacheMaxAge?: number;
+    scrollRestoration?: boolean;
+    shouldUseDocumentNavigation?: (pathname: string) => boolean;
+    deploymentId?: string;
+}
+interface FarmNavigationBlockerContext {
+    from: string;
+    to: string;
+    action: "push" | "replace" | "pop";
+}
+type FarmNavigationBlocker = (context: FarmNavigationBlockerContext) => boolean | void | Promise<boolean | void>;
+type FarmViewTransitionMode = boolean | "auto";
+interface FarmNavigateOptions {
+    replace?: boolean;
+    scroll?: boolean;
+    state?: unknown;
+    viewTransition?: FarmViewTransitionMode;
+}
+interface FarmNavigationLocation {
+    href: string;
+    pathname: string;
+    search: string;
+    hash: string;
+}
+interface FarmNavigationState {
+    state: "idle" | "loading";
+    pending: boolean;
+    from: string | null;
+    to: FarmNavigationLocation | null;
+    action: FarmNavigationBlockerContext["action"] | null;
+    startedAt: number | null;
+}
+type FarmNavigationListener = (state: FarmNavigationState) => void;
+declare class SPARouter {
+    private cache;
+    private prefetchingUrls;
+    private observers;
+    private blockers;
+    private navigationListeners;
+    private navigationState;
+    private scrollElements;
+    private options;
+    private onNavigate?;
+    private clientPlugins?;
+    constructor(options?: RouterOptions);
+    /**
+     * Set the navigation handler that updates React
+     */
+    setNavigationHandler(handler: (data: PageData) => Promise<void>): void;
+    /**
+     * Connect Farm's browser plugin lifecycle to SPA navigation.
+     */
+    setClientPluginManager(manager: FarmClientPluginManager): void;
+    /**
+     * Navigate to a new URL
+     */
+    navigate(href: string, options?: FarmNavigateOptions): Promise<void>;
+    /**
+     * Prefetch a URL
+     */
+    prefetch(href: string): Promise<void>;
+    /**
+     * Observe an element for viewport intersection (prefetch when visible)
+     */
+    observeForPrefetch(element: HTMLAnchorElement): void;
+    /**
+     * Stop observing an element
+     */
+    unobserveForPrefetch(element: HTMLAnchorElement): void;
+    addBlocker(blocker: FarmNavigationBlocker): () => void;
+    getNavigationState(): FarmNavigationState;
+    subscribeNavigation(listener: FarmNavigationListener): () => void;
+    registerScrollElement(key: string, element: HTMLElement): () => void;
+    pushState(state: unknown, href?: string): void;
+    replaceState(state: unknown, href?: string): void;
+    private commitNavigation;
+    private runViewTransition;
+    /**
+     * Fetch page data from cache or server
+     */
+    private fetchPageData;
+    /**
+     * Handle browser back/forward navigation
+     */
+    private handlePopState;
+    /**
+     * Check if URL is cached
+     */
+    private isCached;
+    /**
+     * Check if URL is external
+     */
+    private isExternalUrl;
+    private shouldBlockNavigation;
+    private startNavigation;
+    private finishNavigation;
+    private setNavigationState;
+    private writePageState;
+    /**
+     * Save scroll position for a path
+     */
+    private saveScrollPosition;
+    /**
+     * Restore scroll position for a path
+     */
+    private restoreScrollPosition;
+    private restoreScrollElement;
+    /**
+     * Clear the page cache
+     */
+    clearCache(): void;
+}
+/**
+ * Get or create the global router instance
+ */
+declare function getRouter(): SPARouter;
+/**
+ * Navigate to a URL using the SPA router
+ */
+declare function navigateTo(href: string, options?: FarmNavigateOptions): Promise<void>;
+/**
+ * Prefetch a URL
+ */
+declare function prefetch(href: string): Promise<void>;
+declare function pushState(state: unknown, href?: string): void;
+declare function replaceState(state: unknown, href?: string): void;
+declare function readPageState<TState = unknown>(): TState | null;
+
+/**
+ * Prefetch strategy (TanStack Router–style):
+ * - "intent": prefetch on hover and touchstart (with prefetchDelay)
+ * - "viewport": prefetch when link enters viewport (IntersectionObserver)
+ * - "render": prefetch as soon as the link is mounted
+ * - "none" | false: no prefetch
+ */
+type PrefetchBehavior = false | "intent" | "viewport" | "render" | "none";
+/** @internal Legacy prefetch mode for backward compatibility */
+type PrefetchLegacy = boolean | "hover" | "viewport" | "none";
+/**
+ * Augment this interface via your generated farm-routes.d.ts so Link href is typed
+ * without passing a generic. Defaults to string when not augmented.
+ */
+interface LinkDefaultRoute {
+}
+type DefaultRoutePath = LinkDefaultRoute extends {
+    _: infer TRoute extends string;
+} ? TRoute : string;
+type DefaultRoutePattern = LinkDefaultRoute extends {
+    pattern: infer TRoute extends string;
+} ? TRoute : DefaultRoutePath;
+type DefaultRouteHref = DefaultRoutePath | DefaultRoutePattern;
+type RouteHref<TRoute extends string> = TRoute | `${TRoute}?${string}` | `${TRoute}#${string}` | `${TRoute}?${string}#${string}`;
+type RouteParamValue = Exclude<FarmRouterPathParam, null | undefined>;
+type RouteOptionalParamValue = FarmRouterPathParam;
+type RouteParams<TRoute extends string> = string extends TRoute ? FarmRouterPathParams : ExtractRouteParams<StripRouteSuffix<TRoute>>;
+/** External URLs; these are never type-checked as routes. */
+type ExternalHref = `http://${string}` | `https://${string}` | `//${string}` | `mailto:${string}`;
+type StripRouteSuffix<TRoute extends string> = TRoute extends `${infer Path}?${string}` ? StripRouteSuffix<Path> : TRoute extends `${infer Path}#${string}` ? StripRouteSuffix<Path> : TRoute;
+type ExtractRouteParams<TRoute extends string> = Simplify<ExtractOptionalCatchAllParams<TRoute> & ExtractCatchAllParams<TRoute> & ExtractDynamicParams<TRoute>>;
+type ExtractOptionalCatchAllParams<TRoute extends string> = TRoute extends `${string}[[...${infer Param}]]${infer Rest}` ? {
+    [Key in Param]?: RouteOptionalParamValue;
+} & ExtractOptionalCatchAllParams<Rest> : {};
+type ExtractCatchAllParams<TRoute extends string> = TRoute extends `${string}[...${infer Param}]${infer Rest}` ? Param extends `[...${string}` ? ExtractCatchAllParams<Rest> : {
+    [Key in Param]: RouteParamValue;
+} & ExtractCatchAllParams<Rest> : {};
+type ExtractDynamicParams<TRoute extends string> = TRoute extends `${string}[${infer Param}]${infer Rest}` ? Param extends `...${string}` | `[...${string}` ? ExtractDynamicParams<Rest> : {
+    [Key in Param]: RouteParamValue;
+} & ExtractDynamicParams<Rest> : {};
+type Simplify<T> = {
+    [Key in keyof T]: T[Key];
+} & {};
+type HasRouteParams<TRoute extends string> = keyof RouteParams<TRoute> extends never ? false : true;
+type RoutesWithRequiredParams<TRoute extends string> = TRoute extends string ? HasRouteParams<TRoute> extends true ? TRoute : never : never;
+type LinkRouteParamsProps<TRoute extends string> = string extends TRoute ? {
+    params?: FarmRouterPathParams;
+} : HasRouteParams<TRoute> extends true ? {
+    params: RouteParams<TRoute>;
+} : {
+    params?: FarmRouterPathParams;
+};
+type LinkRouteTargetProps<TRoute extends string> = [RoutesWithRequiredParams<TRoute>] extends [
+    never
+] ? {
+    /** Internal route path with all params already resolved. */
+    href: RouteHref<TRoute>;
+    params?: FarmRouterPathParams;
+} : TRoute extends string ? {
+    /** Internal route path or route pattern. */
+    href: RouteHref<TRoute>;
+} & LinkRouteParamsProps<TRoute> : never;
+type LinkExternalTargetProps = {
+    /** External URL; these are never type-checked as app routes. */
+    href: ExternalHref;
+    params?: never;
+};
+type LinkTargetProps<TRoute extends string> = LinkExternalTargetProps | LinkRouteTargetProps<TRoute>;
+type LinkProps<TRoute extends string = DefaultRouteHref> = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> & LinkTargetProps<TRoute> & {
+    /**
+     * When to prefetch. TanStack-style: "intent" (hover+touch), "viewport", "render", or "none".
+     * Legacy: true (intent+viewport), "hover" (intent), "viewport", false/"none".
+     */
+    prefetch?: PrefetchBehavior | PrefetchLegacy;
+    /** Search params appended after route params are resolved. */
+    query?: FarmRouterBuildOptions["query"];
+    /** Hash appended after route params and search params are resolved. */
+    hash?: string;
+    /** Add a trailing slash to the generated internal href. */
+    trailingSlash?: boolean;
+    /** Delay in ms before intent-based prefetch (hover/touch). Default 50. */
+    prefetchDelay?: number;
+    /** Replace current history entry instead of pushing */
+    replace?: boolean;
+    /** Scroll to top after navigation (default: true) */
+    scroll?: boolean;
+    /** Wrap this SPA navigation in a browser View Transition when supported. */
+    viewTransition?: FarmViewTransitionMode;
+    /** Preserve the active locale by default, or navigate using this locale. */
+    locale?: FarmI18nLocale;
+};
+type LinkComponentType = <TRoute extends string = DefaultRouteHref>(props: LinkProps<TRoute> & {
+    ref?: React__default.ForwardedRef<HTMLAnchorElement>;
+}) => React__default.ReactElement;
+declare const Link: LinkComponentType;
+
+interface UseRouterOptions {
+    basePath?: string;
+    routes?: FarmRouterRouteInput[];
+}
+interface UseBlockerOptions {
+    when: boolean | ((context: FarmNavigationBlockerContext) => boolean);
+    message?: string;
+    shouldBlock?: (context: FarmNavigationBlockerContext) => boolean | Promise<boolean>;
+}
+interface UseBlockerReturn {
+    active: boolean;
+}
+/**
+ * Hook for accessing router state and navigation
+ */
+declare function useRouter(options?: UseRouterOptions): {
+    push: (href: string) => void;
+    replace: (href: string) => void;
+    pushState: <TState>(pageState: TState, href?: string) => void;
+    replaceState: <TState>(pageState: TState, href?: string) => void;
+    back: () => void;
+    forward: () => void;
+    pathname: string;
+    searchParams: URLSearchParams;
+    params: Record<string, string>;
+    pageState: unknown;
+};
+declare function usePageState<TState = unknown>(): TState | null;
+declare function useNavigation(): FarmNavigationState;
+declare function useBlocker(options: UseBlockerOptions): UseBlockerReturn;
+declare function useScrollRestoration<TElement extends HTMLElement = HTMLElement>(key: string): RefObject<TElement>;
+
+export { type DefaultRouteHref, type DefaultRoutePath, type DefaultRoutePattern, type ExternalHref, FarmClientPluginManager, type FarmNavigateOptions, type FarmNavigationBlocker, type FarmNavigationBlockerContext, type FarmNavigationListener, type FarmNavigationLocation, type FarmNavigationState, type FarmViewTransitionMode, Link, type LinkDefaultRoute, type LinkProps, type PrefetchBehavior, type RouteHref, type RouteOptionalParamValue, type RouteParamValue, type RouteParams, SPARouter, type Store, type StoreApi, type StoreFields, type StoreKeyListener, type StoreKeysListener, type StoreListener, type StorePatch, type StoreState, type StoreValueUpdater, type UseBlockerOptions, type UseBlockerReturn, type UseRouterOptions, createStore, getRouter, navigateTo, prefetch, pushState, readPageState, replaceState, useBlocker, useNavigation, usePageState, useRouter, useScrollRestoration };