@farm.js/core 0.1.0-beta.95 → 0.1.0-beta.97

package/dist/client.d.mts

@@ -1,24 +1,28 @@
-import { q as ClientOptions, g as APIResult } from './client-mcMC334J.mjs';
-export { s as APIClient, h as APIClientError, b as APIClientOptions, i as APIClientSystemError, c as APIClientWithoutIntegrationsOptions, u as ApiClients, D as ClientHeaders, E as ClientLifecycleHooks, G as ClientRequestEvent, H as ClientResponseEvent, a3 as InferIntegrationOperationBody, a4 as InferIntegrationOperationQuery, a5 as InferIntegrationOperationResponse, $ as IntegrationAPI, W as IntegrationClient, X as IntegrationClientAliases, a1 as IntegrationClientData, K as IntegrationClientError, Z as IntegrationClientOptions, _ as IntegrationClientRequestOptions, Y as IntegrationClientRoot, a0 as IntegrationClients, a2 as IntegrationOperationResult, a6 as IntegrationServerClient, a7 as IntegrationServerClientAliases, a8 as IntegrationServerClientOptions, a9 as IntegrationServerClientRequestOptions, aa as IntegrationServerClientRoot, ab as IntegrationServerRequestLike, r as RouteAPIClient, t as ServerAPIClient, S as ServerAPIClientOptions, d as ServerAPIClientWithoutIntegrationsOptions, w as createAPIClient, v as createApiClients, L as createIntegrationApi, J as createIntegrationClient, M as createIntegrationClients, P as createIntegrationServerClient, N as createIntegrations, z as createServerAPIClient, Q as getIntegrationAPIManifest, T as integrationClients, U as integrationsClient, V as integrationsServer } from './client-mcMC334J.mjs';
-export { F as FarmAPIStream } from './route-Cq3aObmj.mjs';
+import { q as ClientOptions, g as APIResult } from './client-DWoLZ3QU.mjs';
+export { s as APIClient, h as APIClientError, b as APIClientOptions, i as APIClientSystemError, c as APIClientWithoutIntegrationsOptions, u as ApiClients, H as ClientHeaders, J as ClientLifecycleHooks, K as ClientRequestEvent, L as ClientResponseEvent, a6 as InferIntegrationOperationBody, a7 as InferIntegrationOperationQuery, a8 as InferIntegrationOperationResponse, a2 as IntegrationAPI, Z as IntegrationClient, _ as IntegrationClientAliases, a4 as IntegrationClientData, N as IntegrationClientError, a0 as IntegrationClientOptions, a1 as IntegrationClientRequestOptions, $ as IntegrationClientRoot, a3 as IntegrationClients, a5 as IntegrationOperationResult, a9 as IntegrationServerClient, aa as IntegrationServerClientAliases, ab as IntegrationServerClientOptions, ac as IntegrationServerClientRequestOptions, ad as IntegrationServerClientRoot, ae as IntegrationServerRequestLike, r as RouteAPIClient, t as ServerAPIClient, S as ServerAPIClientOptions, d as ServerAPIClientWithoutIntegrationsOptions, w as createAPIClient, v as createApiClients, P as createIntegrationApi, M as createIntegrationClient, Q as createIntegrationClients, U as createIntegrationServerClient, T as createIntegrations, z as createServerAPIClient, V as getIntegrationAPIManifest, W as integrationClients, X as integrationsClient, Y as integrationsServer } from './client-DWoLZ3QU.mjs';
+export { F as FarmAPIStream } from './route-CvEr4Uc9.mjs';
 import React__default, { ComponentType, FormHTMLAttributes, FormEvent, AnchorHTMLAttributes, RefObject } from 'react';
 export { RouteActionTarget, UseActionFormProps, UseActionReturn, UseServerFnOptions, useAction } from './server-fn-client.mjs';
 export { UseServerQueryOptions, UseServerQueryResult, useServerQuery } from './server-query-client.mjs';
-export { an as FarmIntegrationAPI, c_ as FarmIntegrationAPIBodyFormat, c$ as FarmIntegrationAPIMethod, ao as FarmIntegrationAPIOperation, d0 as FarmIntegrationAPIResponseFormat, cX as api, cY as defineIntegrationAPI, cZ as defineIntegrationAPIOperation, de as endpoint } from './client-plugins-BvClItiL.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-BT024nuJ.mjs';
 export { UseThemeResult, useTheme } from './theme/client.mjs';
 import { FarmRouterPathParams, FarmRouterPathParam, FarmRouterBuildOptions, FarmRouterRouteInput } from './router.mjs';
-import { i as FarmViewTransitionMode, e as FarmNavigationBlockerContext, F as FarmNavigationState } from './spa-router-CyLkwst6.mjs';
-export { a as FarmNavigateOptions, d as FarmNavigationBlocker, f as FarmNavigationListener, h as FarmNavigationLocation, S as SPARouter, g as getRouter, n as navigateTo, p as prefetch, b as pushState, r as readPageState, c as replaceState } from './spa-router-CyLkwst6.mjs';
+import { i as FarmViewTransitionMode, e as FarmNavigationBlockerContext, F as FarmNavigationState } from './spa-router-BeyAVSc6.mjs';
+export { a as FarmNavigateOptions, d as FarmNavigationBlocker, f as FarmNavigationListener, h as FarmNavigationLocation, S as SPARouter, g as getRouter, n as navigateTo, p as prefetch, b as pushState, r as readPageState, c as replaceState } from './spa-router-BeyAVSc6.mjs';
 import { b as FarmI18nLocale } from './types-CnH8DOqo.mjs';
 export { F as FarmChunkRecoveryOptions, i as installChunkErrorRecovery, a as isChunkLoadError } from './chunk-recovery-lnQFzcQP.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, F as FarmClientPluginManager, s as FarmClientPluginManagerOptions, t as FarmClientPluginMetadata, u as FarmClientPluginRegistration, v as FarmClientPluginRouter, w as FarmClientPluginSetupEvent, x as FarmClientPluginStateEvent, c as createClientPluginManager } from './lifecycle-De0vQG45.mjs';
-export { S as ServerQueryFetchOptions, f as fetchServerQuery, p as prefetchServerQuery } from './server-query-runtime-B50KAcj5.mjs';
+export { S as ServerQueryFetchOptions, f as fetchServerQuery, p as prefetchServerQuery } from './server-query-runtime-aP52iuL5.mjs';
 export { getTheme, setTheme, toggleTheme } from './theme/runtime.mjs';
-import './client-cache-CopR_MaI.mjs';
+import './client-cache-CCK-fCe0.mjs';
 import './cache.mjs';
 import './server-fn.mjs';
 import './server-fn-error-DDh14a0V.mjs';
 import './server-query.mjs';
+import './types-DQnyD3VD.mjs';
+import './island-CfGru1MO.mjs';
+import './render-plan-DLxJYAA5.mjs';
+import './client-plugins-B6-07YmP.mjs';
 import './renderer.mjs';
 import 'http';
 import './types-Cc8l9IqS.mjs';
@@ -38,12 +42,9 @@ import './navigation-errors-Dvwpzaer.mjs';
 import './server-action-security.mjs';
 import 'esbuild';
 import './image-config-Duob7wER.mjs';
-import './types-DQnyD3VD.mjs';
 import './font.mjs';
 import './after.mjs';
 import 'node:http';
-import './island-CfGru1MO.mjs';
-import './render-plan-CU31j-Jk.mjs';
 
 type MutationStatus = "idle" | "pending" | "success" | "error";
 type AnyMutationTarget = (...args: any[]) => Promise<any>;
@@ -58,14 +59,24 @@ type MutationOptimisticContext<TVariables, TData> = {
     variables: TVariables | undefined;
     current: TData | null;
 };
+type MutationNetworkMode = "always" | "online";
 type UseMutationOptions<TVariables, TData, TError = Error> = {
     initialData?: TData | null;
     resetOnMutate?: boolean;
+    /**
+     * `"always"` (default) dispatches regardless of connectivity, preserving
+     * existing behavior. `"online"` pauses a submission while the browser is
+     * offline — including one whose dispatch failed while offline — and resumes
+     * it on the `online` event instead of failing it.
+     */
+    networkMode?: MutationNetworkMode;
     optimistic?: (context: MutationOptimisticContext<TVariables, TData>) => TData | null | undefined;
     rollbackOnError?: boolean;
     /**
      * Options forwarded to generated `api.route.method` clients.
-     * Server functions ignore this field.
+     * Server-function targets honor `request.retry`, key-targeted
+     * `request.optimistic` updates, and key-targeted `request.invalidate`;
+     * the remaining request options apply to API routes only.
      */
     request?: ClientOptions<TData, TError>;
     onSuccess?: (data: TData, variables: TVariables | undefined) => void;
@@ -81,6 +92,8 @@ type MutationTrigger<TTarget extends AnyMutationTarget> = [
 ] extends Parameters<TTarget> ? (variables?: MutationInput<TTarget>) => void : (variables: MutationInput<TTarget>) => void;
 type UseMutationReturn<TTarget extends AnyMutationTarget, TData = MutationData<TTarget>, TError = MutationError<TTarget>> = {
     pending: boolean;
+    /** True while a submission is waiting for the browser to come back online. */
+    paused: boolean;
     status: MutationStatus;
     data: TData | null;
     error: TError | null;
@@ -99,17 +112,27 @@ type UseMutationReturn<TTarget extends AnyMutationTarget, TData = MutationData<T
 declare function useMutation<TTarget extends AnyMutationTarget>(target: TTarget, options?: UseMutationOptions<MutationInput<TTarget>, MutationData<TTarget>, MutationError<TTarget>>): UseMutationReturn<TTarget>;
 
 type FetcherState = "idle" | "submitting";
+/** Local form conversion failed before the target was called. */
+declare class FetcherInputError extends Error {
+    readonly name: "FetcherInputError";
+    readonly code: "input_error";
+    readonly status: 0;
+    readonly data: undefined;
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
 type FetcherFormDataContext = {
     form: HTMLFormElement | null;
     submitter: HTMLElement | null;
 };
-type UseFetcherOptions<TTarget extends AnyMutationTarget> = UseMutationOptions<InferMutationVariables<TTarget>, InferMutationData<TTarget>, InferMutationError<TTarget>> & {
+type UseFetcherOptions<TTarget extends AnyMutationTarget> = Omit<UseMutationOptions<InferMutationVariables<TTarget>, InferMutationData<TTarget>, InferMutationError<TTarget> | FetcherInputError>, "request"> & {
+    request?: UseMutationOptions<InferMutationVariables<TTarget>, InferMutationData<TTarget>, InferMutationError<TTarget>>["request"];
     /**
      * Convert browser FormData into the target's typed variables.
      *
-     * Generated API routes default to `{ body: Object.fromEntries(formData) }`
-     * (or `{ query: ... }` for GET/HEAD). Server functions receive FormData
-     * directly so their input schema remains authoritative.
+     * Generated API routes preserve multipart forms and file values as a FormData
+     * body; text-only submissions default to a JSON object (or query for GET/HEAD).
+     * Server functions receive FormData directly. This mapper overrides defaults.
      */
     mapFormData?: (formData: FormData, context: FetcherFormDataContext) => InferMutationVariables<TTarget>;
 };
@@ -130,8 +153,10 @@ type UseFetcherReturn<TTarget extends AnyMutationTarget> = {
     state: FetcherState;
     status: MutationStatus;
     pending: boolean;
+    /** True while a submission is waiting for the browser to come back online. */
+    paused: boolean;
     data: InferMutationData<TTarget> | null;
-    error: InferMutationError<TTarget> | null;
+    error: InferMutationError<TTarget> | FetcherInputError | null;
     variables: InferMutationVariables<TTarget> | undefined;
     formData: FormData | null;
     submit: FetcherSubmit<TTarget>;
@@ -147,6 +172,99 @@ type UseFetcherReturn<TTarget extends AnyMutationTarget> = {
  */
 declare function useFetcher<TTarget extends AnyMutationTarget>(target: TTarget, options?: UseFetcherOptions<TTarget>): UseFetcherReturn<TTarget>;
 
+declare const FARM_CACHE_INVALIDATION_CHANNEL = "farm:cache-invalidation";
+type CrossTabCacheInvalidationOptions = {
+    /** Override the BroadcastChannel name, e.g. to isolate multiple apps on one origin. */
+    channelName?: string;
+};
+/**
+ * Bridge the cache invalidation bus across tabs of the same origin.
+ *
+ * Local invalidations are posted to a BroadcastChannel and applied in every
+ * other tab through the normal invalidation path, so mounted stale queries
+ * there refetch on their own. Only invalidation keys cross the channel, never
+ * cached data, which keeps private and credentialed cache scoping untouched.
+ *
+ * Opt-in and idempotent. Returns a disposer; a no-op where BroadcastChannel
+ * is unavailable (server rendering, older browsers).
+ */
+declare function enableCrossTabCacheInvalidation(options?: CrossTabCacheInvalidationOptions): () => void;
+
+/**
+ * Protocol version stamped into every persisted entry. Bump when the
+ * persisted shape changes; mismatched entries are dropped on load.
+ */
+declare const FARM_CLIENT_CACHE_PERSIST_VERSION = "1";
+/** Snapshot of a confirmed cache entry as stored by an adapter. */
+type PersistedEntry = {
+    data: unknown;
+    updatedAt: number;
+    staleAt: number;
+    gcAt?: number;
+    version: string;
+};
+/**
+ * Storage contract for client cache persistence. Implement these callbacks
+ * over any storage: IndexedDB, localStorage, OPFS, a native bridge. Farm owns
+ * every policy decision (what, when, and whether to persist); the adapter is
+ * plain keyed storage. `set` is an upsert.
+ */
+type FarmClientCacheAdapter = {
+    keys(): Promise<string[]>;
+    get(key: string): Promise<PersistedEntry | null>;
+    set(key: string, entry: PersistedEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /** Optional batch fast paths; the engine prefers them when present. */
+    getMany?(keys: string[]): Promise<Array<PersistedEntry | null>>;
+    setMany?(entries: Array<[string, PersistedEntry]>): Promise<void>;
+};
+/** Key-value client shape accepted by {@link storageClientCacheAdapter}. */
+type FarmClientCacheStorage = {
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    setItem<T = unknown>(key: string, value: T): Promise<unknown>;
+    removeItem(key: string): Promise<unknown>;
+    getKeys?(base?: string): Promise<string[]>;
+    keys?(base?: string): Promise<string[]>;
+    clear?(base?: string): Promise<unknown>;
+};
+type ClientCachePersistenceOptions = {
+    /**
+     * Extra version salt, typically an app build or deploy id. Entries written
+     * under a different value are dropped on load.
+     */
+    version?: string;
+    /** Coarse additional filter on top of per-declaration `persist: true`. */
+    persistKey?: (key: string) => boolean;
+    /** Debounce for write-behind flushes. */
+    flushDelayMs?: number;
+};
+/**
+ * Validate and type an adapter definition. Identity at runtime beyond shape
+ * checking, mirroring `defineConfig`-style helpers.
+ */
+declare function defineClientCacheAdapter(adapter: FarmClientCacheAdapter): FarmClientCacheAdapter;
+/**
+ * Adapt any Farm/unstorage-compatible key-value client to the client cache
+ * adapter contract, mirroring the server's `storageCacheAdapter`. Without a
+ * key enumeration method the adapter still persists but cannot warm-start.
+ */
+declare function storageClientCacheAdapter(storage: FarmClientCacheStorage, options?: {
+    base?: string;
+}): FarmClientCacheAdapter;
+/**
+ * @internal Wire an adapter to the shared client cache. Called by the
+ * generated client entry from the `cache.client.adapter` configuration; not
+ * part of the public API. Returns a disposer.
+ */
+declare function initPersistedClientCache(adapter: FarmClientCacheAdapter, options?: ClientCachePersistenceOptions): () => void;
+/**
+ * Remove every persisted cache entry. Call on logout or any session change so
+ * the next visitor on this device cannot warm-start into another user's data.
+ * Safe to call when persistence is not configured.
+ */
+declare function clearPersistedCache(): Promise<void>;
+
 type StoreState = Record<string, any>;
 type StoreValueUpdater<T> = T | ((previous: T) => T);
 type StorePatch<T extends StoreState> = Partial<T> | ((state: T) => Partial<T>);
@@ -339,4 +457,4 @@ declare function useNavigation(): FarmNavigationState;
 declare function useBlocker(options: UseBlockerOptions): UseBlockerReturn;
 declare function useScrollRestoration<TElement extends HTMLElement = HTMLElement>(key: string): RefObject<TElement | null>;
 
-export { type AnyMutationTarget, type DefaultRouteHref, type DefaultRoutePath, type DefaultRoutePattern, type ExternalHref, FarmNavigationBlockerContext, FarmNavigationState, FarmViewTransitionMode, type FetcherFormDataContext, type FetcherFormProps, type FetcherState, type FetcherSubmit, type FetcherSubmitAsync, type InferMutationData, type InferMutationError, type InferMutationVariables, Link, type LinkDefaultRoute, type LinkExternalUriSchemes, type LinkProps, type MutationAsync, type MutationOptimisticContext, type MutationStatus, type MutationTrigger, type PrefetchBehavior, type RouteHref, type RouteOptionalParamValue, type RouteParamValue, type RouteParams, type Store, type StoreApi, type StoreFields, type StoreKeyListener, type StoreKeysListener, type StoreListener, type StorePatch, type StoreState, type StoreValueUpdater, type UseBlockerOptions, type UseBlockerReturn, type UseFetcherOptions, type UseFetcherReturn, type UseMutationOptions, type UseMutationReturn, type UseRouterOptions, createStore, useBlocker, useFetcher, useMutation, useNavigation, usePageState, useRouter, useScrollRestoration };
+export { type AnyMutationTarget, type ClientCachePersistenceOptions, type CrossTabCacheInvalidationOptions, type DefaultRouteHref, type DefaultRoutePath, type DefaultRoutePattern, type ExternalHref, FARM_CACHE_INVALIDATION_CHANNEL, FARM_CLIENT_CACHE_PERSIST_VERSION, type FarmClientCacheAdapter, type FarmClientCacheStorage, FarmNavigationBlockerContext, FarmNavigationState, FarmViewTransitionMode, type FetcherFormDataContext, type FetcherFormProps, FetcherInputError, type FetcherState, type FetcherSubmit, type FetcherSubmitAsync, type InferMutationData, type InferMutationError, type InferMutationVariables, Link, type LinkDefaultRoute, type LinkExternalUriSchemes, type LinkProps, type MutationAsync, type MutationNetworkMode, type MutationOptimisticContext, type MutationStatus, type MutationTrigger, type PersistedEntry, type PrefetchBehavior, type RouteHref, type RouteOptionalParamValue, type RouteParamValue, type RouteParams, type Store, type StoreApi, type StoreFields, type StoreKeyListener, type StoreKeysListener, type StoreListener, type StorePatch, type StoreState, type StoreValueUpdater, type UseBlockerOptions, type UseBlockerReturn, type UseFetcherOptions, type UseFetcherReturn, type UseMutationOptions, type UseMutationReturn, type UseRouterOptions, clearPersistedCache, createStore, defineClientCacheAdapter, enableCrossTabCacheInvalidation, initPersistedClientCache, storageClientCacheAdapter, useBlocker, useFetcher, useMutation, useNavigation, usePageState, useRouter, useScrollRestoration };

package/dist/client.d.ts

@@ -1,24 +1,28 @@
-import { q as ClientOptions, g as APIResult } from './client-d5ONQ-Pd.js';
-export { s as APIClient, h as APIClientError, b as APIClientOptions, i as APIClientSystemError, c as APIClientWithoutIntegrationsOptions, u as ApiClients, D as ClientHeaders, E as ClientLifecycleHooks, G as ClientRequestEvent, H as ClientResponseEvent, a3 as InferIntegrationOperationBody, a4 as InferIntegrationOperationQuery, a5 as InferIntegrationOperationResponse, $ as IntegrationAPI, W as IntegrationClient, X as IntegrationClientAliases, a1 as IntegrationClientData, K as IntegrationClientError, Z as IntegrationClientOptions, _ as IntegrationClientRequestOptions, Y as IntegrationClientRoot, a0 as IntegrationClients, a2 as IntegrationOperationResult, a6 as IntegrationServerClient, a7 as IntegrationServerClientAliases, a8 as IntegrationServerClientOptions, a9 as IntegrationServerClientRequestOptions, aa as IntegrationServerClientRoot, ab as IntegrationServerRequestLike, r as RouteAPIClient, t as ServerAPIClient, S as ServerAPIClientOptions, d as ServerAPIClientWithoutIntegrationsOptions, w as createAPIClient, v as createApiClients, L as createIntegrationApi, J as createIntegrationClient, M as createIntegrationClients, P as createIntegrationServerClient, N as createIntegrations, z as createServerAPIClient, Q as getIntegrationAPIManifest, T as integrationClients, U as integrationsClient, V as integrationsServer } from './client-d5ONQ-Pd.js';
-export { F as FarmAPIStream } from './route-Y8lfz1wF.js';
+import { q as ClientOptions, g as APIResult } from './client-DuQuQC1h.js';
+export { s as APIClient, h as APIClientError, b as APIClientOptions, i as APIClientSystemError, c as APIClientWithoutIntegrationsOptions, u as ApiClients, H as ClientHeaders, J as ClientLifecycleHooks, K as ClientRequestEvent, L as ClientResponseEvent, a6 as InferIntegrationOperationBody, a7 as InferIntegrationOperationQuery, a8 as InferIntegrationOperationResponse, a2 as IntegrationAPI, Z as IntegrationClient, _ as IntegrationClientAliases, a4 as IntegrationClientData, N as IntegrationClientError, a0 as IntegrationClientOptions, a1 as IntegrationClientRequestOptions, $ as IntegrationClientRoot, a3 as IntegrationClients, a5 as IntegrationOperationResult, a9 as IntegrationServerClient, aa as IntegrationServerClientAliases, ab as IntegrationServerClientOptions, ac as IntegrationServerClientRequestOptions, ad as IntegrationServerClientRoot, ae as IntegrationServerRequestLike, r as RouteAPIClient, t as ServerAPIClient, S as ServerAPIClientOptions, d as ServerAPIClientWithoutIntegrationsOptions, w as createAPIClient, v as createApiClients, P as createIntegrationApi, M as createIntegrationClient, Q as createIntegrationClients, U as createIntegrationServerClient, T as createIntegrations, z as createServerAPIClient, V as getIntegrationAPIManifest, W as integrationClients, X as integrationsClient, Y as integrationsServer } from './client-DuQuQC1h.js';
+export { F as FarmAPIStream } from './route-4pd-EVtw.js';
 import React__default, { ComponentType, FormHTMLAttributes, FormEvent, AnchorHTMLAttributes, RefObject } from 'react';
 export { RouteActionTarget, UseActionFormProps, UseActionReturn, UseServerFnOptions, useAction } from './server-fn-client.js';
 export { UseServerQueryOptions, UseServerQueryResult, useServerQuery } from './server-query-client.js';
-export { an as FarmIntegrationAPI, c_ as FarmIntegrationAPIBodyFormat, c$ as FarmIntegrationAPIMethod, ao as FarmIntegrationAPIOperation, d0 as FarmIntegrationAPIResponseFormat, cX as api, cY as defineIntegrationAPI, cZ as defineIntegrationAPIOperation, de as endpoint } from './client-plugins-B9Sq-iMg.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-BT024nuJ.js';
 export { UseThemeResult, useTheme } from './theme/client.js';
 import { FarmRouterPathParams, FarmRouterPathParam, FarmRouterBuildOptions, FarmRouterRouteInput } from './router.js';
-import { i as FarmViewTransitionMode, e as FarmNavigationBlockerContext, F as FarmNavigationState } from './spa-router-BkqGXaV_.js';
-export { a as FarmNavigateOptions, d as FarmNavigationBlocker, f as FarmNavigationListener, h as FarmNavigationLocation, S as SPARouter, g as getRouter, n as navigateTo, p as prefetch, b as pushState, r as readPageState, c as replaceState } from './spa-router-BkqGXaV_.js';
+import { i as FarmViewTransitionMode, e as FarmNavigationBlockerContext, F as FarmNavigationState } from './spa-router-COgu4txb.js';
+export { a as FarmNavigateOptions, d as FarmNavigationBlocker, f as FarmNavigationListener, h as FarmNavigationLocation, S as SPARouter, g as getRouter, n as navigateTo, p as prefetch, b as pushState, r as readPageState, c as replaceState } from './spa-router-COgu4txb.js';
 import { b as FarmI18nLocale } from './types-CnH8DOqo.js';
 export { F as FarmChunkRecoveryOptions, i as installChunkErrorRecovery, a as isChunkLoadError } from './chunk-recovery-lnQFzcQP.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, F as FarmClientPluginManager, s as FarmClientPluginManagerOptions, t as FarmClientPluginMetadata, u as FarmClientPluginRegistration, v as FarmClientPluginRouter, w as FarmClientPluginSetupEvent, x as FarmClientPluginStateEvent, c as createClientPluginManager } from './lifecycle-De0vQG45.js';
-export { S as ServerQueryFetchOptions, f as fetchServerQuery, p as prefetchServerQuery } from './server-query-runtime-3zAj77yv.js';
+export { S as ServerQueryFetchOptions, f as fetchServerQuery, p as prefetchServerQuery } from './server-query-runtime-DXRNhX_3.js';
 export { getTheme, setTheme, toggleTheme } from './theme/runtime.js';
-import './client-cache-Djy_TlE8.js';
+import './client-cache-BMxuFqwH.js';
 import './cache.js';
 import './server-fn.js';
 import './server-fn-error-DDh14a0V.js';
 import './server-query.js';
+import './types-DQnyD3VD.js';
+import './island-CfGru1MO.js';
+import './render-plan-0GeHiGVZ.js';
+import './client-plugins-By6MVUX-.js';
 import './renderer.js';
 import 'http';
 import './types-Cc8l9IqS.js';
@@ -38,12 +42,9 @@ import './navigation-errors-Dvwpzaer.js';
 import './server-action-security.js';
 import 'esbuild';
 import './image-config-Duob7wER.js';
-import './types-DQnyD3VD.js';
 import './font.js';
 import './after.js';
 import 'node:http';
-import './island-CfGru1MO.js';
-import './render-plan-Dc8CjNI7.js';
 
 type MutationStatus = "idle" | "pending" | "success" | "error";
 type AnyMutationTarget = (...args: any[]) => Promise<any>;
@@ -58,14 +59,24 @@ type MutationOptimisticContext<TVariables, TData> = {
     variables: TVariables | undefined;
     current: TData | null;
 };
+type MutationNetworkMode = "always" | "online";
 type UseMutationOptions<TVariables, TData, TError = Error> = {
     initialData?: TData | null;
     resetOnMutate?: boolean;
+    /**
+     * `"always"` (default) dispatches regardless of connectivity, preserving
+     * existing behavior. `"online"` pauses a submission while the browser is
+     * offline — including one whose dispatch failed while offline — and resumes
+     * it on the `online` event instead of failing it.
+     */
+    networkMode?: MutationNetworkMode;
     optimistic?: (context: MutationOptimisticContext<TVariables, TData>) => TData | null | undefined;
     rollbackOnError?: boolean;
     /**
      * Options forwarded to generated `api.route.method` clients.
-     * Server functions ignore this field.
+     * Server-function targets honor `request.retry`, key-targeted
+     * `request.optimistic` updates, and key-targeted `request.invalidate`;
+     * the remaining request options apply to API routes only.
      */
     request?: ClientOptions<TData, TError>;
     onSuccess?: (data: TData, variables: TVariables | undefined) => void;
@@ -81,6 +92,8 @@ type MutationTrigger<TTarget extends AnyMutationTarget> = [
 ] extends Parameters<TTarget> ? (variables?: MutationInput<TTarget>) => void : (variables: MutationInput<TTarget>) => void;
 type UseMutationReturn<TTarget extends AnyMutationTarget, TData = MutationData<TTarget>, TError = MutationError<TTarget>> = {
     pending: boolean;
+    /** True while a submission is waiting for the browser to come back online. */
+    paused: boolean;
     status: MutationStatus;
     data: TData | null;
     error: TError | null;
@@ -99,17 +112,27 @@ type UseMutationReturn<TTarget extends AnyMutationTarget, TData = MutationData<T
 declare function useMutation<TTarget extends AnyMutationTarget>(target: TTarget, options?: UseMutationOptions<MutationInput<TTarget>, MutationData<TTarget>, MutationError<TTarget>>): UseMutationReturn<TTarget>;
 
 type FetcherState = "idle" | "submitting";
+/** Local form conversion failed before the target was called. */
+declare class FetcherInputError extends Error {
+    readonly name: "FetcherInputError";
+    readonly code: "input_error";
+    readonly status: 0;
+    readonly data: undefined;
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
 type FetcherFormDataContext = {
     form: HTMLFormElement | null;
     submitter: HTMLElement | null;
 };
-type UseFetcherOptions<TTarget extends AnyMutationTarget> = UseMutationOptions<InferMutationVariables<TTarget>, InferMutationData<TTarget>, InferMutationError<TTarget>> & {
+type UseFetcherOptions<TTarget extends AnyMutationTarget> = Omit<UseMutationOptions<InferMutationVariables<TTarget>, InferMutationData<TTarget>, InferMutationError<TTarget> | FetcherInputError>, "request"> & {
+    request?: UseMutationOptions<InferMutationVariables<TTarget>, InferMutationData<TTarget>, InferMutationError<TTarget>>["request"];
     /**
      * Convert browser FormData into the target's typed variables.
      *
-     * Generated API routes default to `{ body: Object.fromEntries(formData) }`
-     * (or `{ query: ... }` for GET/HEAD). Server functions receive FormData
-     * directly so their input schema remains authoritative.
+     * Generated API routes preserve multipart forms and file values as a FormData
+     * body; text-only submissions default to a JSON object (or query for GET/HEAD).
+     * Server functions receive FormData directly. This mapper overrides defaults.
      */
     mapFormData?: (formData: FormData, context: FetcherFormDataContext) => InferMutationVariables<TTarget>;
 };
@@ -130,8 +153,10 @@ type UseFetcherReturn<TTarget extends AnyMutationTarget> = {
     state: FetcherState;
     status: MutationStatus;
     pending: boolean;
+    /** True while a submission is waiting for the browser to come back online. */
+    paused: boolean;
     data: InferMutationData<TTarget> | null;
-    error: InferMutationError<TTarget> | null;
+    error: InferMutationError<TTarget> | FetcherInputError | null;
     variables: InferMutationVariables<TTarget> | undefined;
     formData: FormData | null;
     submit: FetcherSubmit<TTarget>;
@@ -147,6 +172,99 @@ type UseFetcherReturn<TTarget extends AnyMutationTarget> = {
  */
 declare function useFetcher<TTarget extends AnyMutationTarget>(target: TTarget, options?: UseFetcherOptions<TTarget>): UseFetcherReturn<TTarget>;
 
+declare const FARM_CACHE_INVALIDATION_CHANNEL = "farm:cache-invalidation";
+type CrossTabCacheInvalidationOptions = {
+    /** Override the BroadcastChannel name, e.g. to isolate multiple apps on one origin. */
+    channelName?: string;
+};
+/**
+ * Bridge the cache invalidation bus across tabs of the same origin.
+ *
+ * Local invalidations are posted to a BroadcastChannel and applied in every
+ * other tab through the normal invalidation path, so mounted stale queries
+ * there refetch on their own. Only invalidation keys cross the channel, never
+ * cached data, which keeps private and credentialed cache scoping untouched.
+ *
+ * Opt-in and idempotent. Returns a disposer; a no-op where BroadcastChannel
+ * is unavailable (server rendering, older browsers).
+ */
+declare function enableCrossTabCacheInvalidation(options?: CrossTabCacheInvalidationOptions): () => void;
+
+/**
+ * Protocol version stamped into every persisted entry. Bump when the
+ * persisted shape changes; mismatched entries are dropped on load.
+ */
+declare const FARM_CLIENT_CACHE_PERSIST_VERSION = "1";
+/** Snapshot of a confirmed cache entry as stored by an adapter. */
+type PersistedEntry = {
+    data: unknown;
+    updatedAt: number;
+    staleAt: number;
+    gcAt?: number;
+    version: string;
+};
+/**
+ * Storage contract for client cache persistence. Implement these callbacks
+ * over any storage: IndexedDB, localStorage, OPFS, a native bridge. Farm owns
+ * every policy decision (what, when, and whether to persist); the adapter is
+ * plain keyed storage. `set` is an upsert.
+ */
+type FarmClientCacheAdapter = {
+    keys(): Promise<string[]>;
+    get(key: string): Promise<PersistedEntry | null>;
+    set(key: string, entry: PersistedEntry): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /** Optional batch fast paths; the engine prefers them when present. */
+    getMany?(keys: string[]): Promise<Array<PersistedEntry | null>>;
+    setMany?(entries: Array<[string, PersistedEntry]>): Promise<void>;
+};
+/** Key-value client shape accepted by {@link storageClientCacheAdapter}. */
+type FarmClientCacheStorage = {
+    getItem<T = unknown>(key: string): Promise<T | null>;
+    setItem<T = unknown>(key: string, value: T): Promise<unknown>;
+    removeItem(key: string): Promise<unknown>;
+    getKeys?(base?: string): Promise<string[]>;
+    keys?(base?: string): Promise<string[]>;
+    clear?(base?: string): Promise<unknown>;
+};
+type ClientCachePersistenceOptions = {
+    /**
+     * Extra version salt, typically an app build or deploy id. Entries written
+     * under a different value are dropped on load.
+     */
+    version?: string;
+    /** Coarse additional filter on top of per-declaration `persist: true`. */
+    persistKey?: (key: string) => boolean;
+    /** Debounce for write-behind flushes. */
+    flushDelayMs?: number;
+};
+/**
+ * Validate and type an adapter definition. Identity at runtime beyond shape
+ * checking, mirroring `defineConfig`-style helpers.
+ */
+declare function defineClientCacheAdapter(adapter: FarmClientCacheAdapter): FarmClientCacheAdapter;
+/**
+ * Adapt any Farm/unstorage-compatible key-value client to the client cache
+ * adapter contract, mirroring the server's `storageCacheAdapter`. Without a
+ * key enumeration method the adapter still persists but cannot warm-start.
+ */
+declare function storageClientCacheAdapter(storage: FarmClientCacheStorage, options?: {
+    base?: string;
+}): FarmClientCacheAdapter;
+/**
+ * @internal Wire an adapter to the shared client cache. Called by the
+ * generated client entry from the `cache.client.adapter` configuration; not
+ * part of the public API. Returns a disposer.
+ */
+declare function initPersistedClientCache(adapter: FarmClientCacheAdapter, options?: ClientCachePersistenceOptions): () => void;
+/**
+ * Remove every persisted cache entry. Call on logout or any session change so
+ * the next visitor on this device cannot warm-start into another user's data.
+ * Safe to call when persistence is not configured.
+ */
+declare function clearPersistedCache(): Promise<void>;
+
 type StoreState = Record<string, any>;
 type StoreValueUpdater<T> = T | ((previous: T) => T);
 type StorePatch<T extends StoreState> = Partial<T> | ((state: T) => Partial<T>);
@@ -339,4 +457,4 @@ declare function useNavigation(): FarmNavigationState;
 declare function useBlocker(options: UseBlockerOptions): UseBlockerReturn;
 declare function useScrollRestoration<TElement extends HTMLElement = HTMLElement>(key: string): RefObject<TElement | null>;
 
-export { type AnyMutationTarget, type DefaultRouteHref, type DefaultRoutePath, type DefaultRoutePattern, type ExternalHref, FarmNavigationBlockerContext, FarmNavigationState, FarmViewTransitionMode, type FetcherFormDataContext, type FetcherFormProps, type FetcherState, type FetcherSubmit, type FetcherSubmitAsync, type InferMutationData, type InferMutationError, type InferMutationVariables, Link, type LinkDefaultRoute, type LinkExternalUriSchemes, type LinkProps, type MutationAsync, type MutationOptimisticContext, type MutationStatus, type MutationTrigger, type PrefetchBehavior, type RouteHref, type RouteOptionalParamValue, type RouteParamValue, type RouteParams, type Store, type StoreApi, type StoreFields, type StoreKeyListener, type StoreKeysListener, type StoreListener, type StorePatch, type StoreState, type StoreValueUpdater, type UseBlockerOptions, type UseBlockerReturn, type UseFetcherOptions, type UseFetcherReturn, type UseMutationOptions, type UseMutationReturn, type UseRouterOptions, createStore, useBlocker, useFetcher, useMutation, useNavigation, usePageState, useRouter, useScrollRestoration };
+export { type AnyMutationTarget, type ClientCachePersistenceOptions, type CrossTabCacheInvalidationOptions, type DefaultRouteHref, type DefaultRoutePath, type DefaultRoutePattern, type ExternalHref, FARM_CACHE_INVALIDATION_CHANNEL, FARM_CLIENT_CACHE_PERSIST_VERSION, type FarmClientCacheAdapter, type FarmClientCacheStorage, FarmNavigationBlockerContext, FarmNavigationState, FarmViewTransitionMode, type FetcherFormDataContext, type FetcherFormProps, FetcherInputError, type FetcherState, type FetcherSubmit, type FetcherSubmitAsync, type InferMutationData, type InferMutationError, type InferMutationVariables, Link, type LinkDefaultRoute, type LinkExternalUriSchemes, type LinkProps, type MutationAsync, type MutationNetworkMode, type MutationOptimisticContext, type MutationStatus, type MutationTrigger, type PersistedEntry, type PrefetchBehavior, type RouteHref, type RouteOptionalParamValue, type RouteParamValue, type RouteParams, type Store, type StoreApi, type StoreFields, type StoreKeyListener, type StoreKeysListener, type StoreListener, type StorePatch, type StoreState, type StoreValueUpdater, type UseBlockerOptions, type UseBlockerReturn, type UseFetcherOptions, type UseFetcherReturn, type UseMutationOptions, type UseMutationReturn, type UseRouterOptions, clearPersistedCache, createStore, defineClientCacheAdapter, enableCrossTabCacheInvalidation, initPersistedClientCache, storageClientCacheAdapter, useBlocker, useFetcher, useMutation, useNavigation, usePageState, useRouter, useScrollRestoration };

package/dist/client.mjs

@@ -1,22 +1,30 @@
 import {
+  FARM_CACHE_INVALIDATION_CHANNEL,
+  FARM_CLIENT_CACHE_PERSIST_VERSION,
+  FetcherInputError,
   Link,
+  clearPersistedCache,
   createStore,
+  defineClientCacheAdapter,
+  enableCrossTabCacheInvalidation,
+  initPersistedClientCache,
+  storageClientCacheAdapter,
   useFetcher,
   useMutation
-} from "./chunk-KWCNQUH5.mjs";
+} from "./chunk-EPDIF432.mjs";
 import {
   useAction
-} from "./chunk-SALMKQXH.mjs";
+} from "./chunk-6EJHNHH4.mjs";
 import {
   useServerQuery
-} from "./chunk-KOTSX5JH.mjs";
+} from "./chunk-52BR7LTX.mjs";
 import {
   useBlocker,
   useNavigation,
   usePageState,
   useRouter,
   useScrollRestoration
-} from "./chunk-MOW47IF5.mjs";
+} from "./chunk-6UYVU46O.mjs";
 import {
   useTheme
 } from "./chunk-CHITERV2.mjs";
@@ -35,11 +43,12 @@ import {
   integrationClients,
   integrationsClient,
   integrationsServer
-} from "./chunk-75CGAL6E.mjs";
+} from "./chunk-IZBX2TEU.mjs";
+import "./chunk-DU3PKDVQ.mjs";
 import {
   fetchServerQuery,
   prefetchServerQuery
-} from "./chunk-EXCGBERG.mjs";
+} from "./chunk-WD2EBM3I.mjs";
 import {
   getTheme,
   setTheme,
@@ -54,17 +63,17 @@ import {
   pushState,
   readPageState,
   replaceState
-} from "./chunk-MRVJCLYQ.mjs";
+} from "./chunk-PSQ7N4XP.mjs";
 import "./chunk-ULD4ENAH.mjs";
 import "./chunk-JIT7GXDP.mjs";
-import "./chunk-DLBUAJTK.mjs";
-import "./chunk-SCFX4UTD.mjs";
+import "./chunk-WMJGA32P.mjs";
+import "./chunk-EHTUKVSW.mjs";
 import {
   FarmClientPluginManager,
   createClientPluginManager,
   installChunkErrorRecovery,
   isChunkLoadError
-} from "./chunk-UWRGX3J3.mjs";
+} from "./chunk-UMUWR5XA.mjs";
 import "./chunk-RCNUKRBF.mjs";
 import "./chunk-GQVQESLY.mjs";
 import {
@@ -74,16 +83,16 @@ import {
   endpoint
 } from "./chunk-HKXMMPYI.mjs";
 import "./chunk-YECMFULZ.mjs";
-import "./chunk-XTLLHCWU.mjs";
+import "./chunk-V4VRLVLW.mjs";
 import "./chunk-6YPPIPKR.mjs";
 import "./chunk-3BXGOVKE.mjs";
 import "./chunk-4C3Z34O7.mjs";
-import "./chunk-AXVJCMVF.mjs";
-import "./chunk-RBRLLZL5.mjs";
+import "./chunk-2HDOV47R.mjs";
+import "./chunk-34IAPZBG.mjs";
 import "./chunk-WZ5QFROO.mjs";
-import "./chunk-ZRBCBOEX.mjs";
+import "./chunk-N2FY2QZ7.mjs";
 import "./chunk-FXG2PS27.mjs";
-import "./chunk-22VG4DFJ.mjs";
+import "./chunk-J3MPQ4MQ.mjs";
 import "./chunk-LM2YNO4U.mjs";
 import "./chunk-W4ZNS76E.mjs";
 import "./chunk-IBULMPCM.mjs";
@@ -91,11 +100,15 @@ import "./chunk-DZU3EKQP.mjs";
 import "./chunk-CGILA3WO.mjs";
 export {
   APIClientError,
+  FARM_CACHE_INVALIDATION_CHANNEL,
+  FARM_CLIENT_CACHE_PERSIST_VERSION,
   FarmClientPluginManager,
+  FetcherInputError,
   IntegrationClientError,
   Link,
   SPARouter,
   api,
+  clearPersistedCache,
   createAPIClient,
   createApiClients,
   createClientPluginManager,
@@ -106,13 +119,16 @@ export {
   createIntegrations,
   createServerAPIClient,
   createStore,
+  defineClientCacheAdapter,
   defineIntegrationAPI,
   defineIntegrationAPIOperation,
+  enableCrossTabCacheInvalidation,
   endpoint,
   fetchServerQuery,
   getIntegrationAPIManifest,
   getRouter,
   getTheme,
+  initPersistedClientCache,
   installChunkErrorRecovery,
   integrationClients,
   integrationsClient,
@@ -125,6 +141,7 @@ export {
   readPageState,
   replaceState,
   setTheme,
+  storageClientCacheAdapter,
   toggleTheme,
   useAction,
   useBlocker,

package/dist/config.d.mts

@@ -1,6 +1,6 @@
-import { m as FarmUserConfig } from './client-plugins-BvClItiL.mjs';
+import { m as FarmUserConfig } from './client-plugins-B6-07YmP.mjs';
 import './lifecycle-De0vQG45.mjs';
-import './route-Cq3aObmj.mjs';
+import './route-CvEr4Uc9.mjs';
 import './cache.mjs';
 import './renderer.mjs';
 import 'http';
@@ -8,6 +8,7 @@ import './types-Cc8l9IqS.mjs';
 import 'db0';
 import 'unstorage';
 import 'react';
+import './integration-api-BT024nuJ.mjs';
 import '@farming-labs/orm';
 import './types-CKwggz9n.mjs';
 import '@farming-labs/docs';