@farm.js/core 0.1.61 → 0.1.62

package/dist/config.d-qt-mE8O5.d.mts

@@ -0,0 +1,341 @@
+/** Checks for one block, with errors prefixed by the block, such as `mobile (os: android)`. */
+interface PlatformBlockChecker {
+    fail(message: string): never;
+    checkKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>, where: string): void;
+    optionalString(value: unknown, key: string): string | undefined;
+}
+/** Results of function-valued blocks for one dev session or build. */
+type PlatformBlockCache<T> = Map<string, Promise<T>>;
+
+/**
+ * What web screens can call on an app native module (RFC 0004, 7.5): the Promise methods of its
+ * Codegen spec, read with React Native's own Codegen parser so the spec stays the one source. The
+ * Android shell checks arguments against these types before the module runs, and `src/farm.d.ts`
+ * types `native.<module>` from them.
+ */
+/** A value a web screen sends or receives, as the Codegen spec declares it. */
+type FarmNativeType = ({
+    type: "string";
+} | {
+    type: "number";
+    integer?: true;
+} | {
+    type: "boolean";
+}
+/** A string literal union, a single literal, or an enum: the values the spec allows. */
+ | {
+    type: "literal";
+    values: Array<string | number>;
+}
+/** An object type with declared properties: `ReadableMap` in Kotlin. */
+ | {
+    type: "object";
+    properties: FarmNativeProperty[];
+}
+/** `Object` or `UnsafeObject`: any JSON object, `ReadableMap` in Kotlin. */
+ | {
+    type: "map";
+}
+/** An array; without `element`, any JSON values. `ReadableArray` in Kotlin. */
+ | {
+    type: "array";
+    element?: FarmNativeType;
+}
+/** Return values only: `Promise<void>`. */
+ | {
+    type: "void";
+}
+/** Return values only: a type web screens get as JSON without a narrower type. */
+ | {
+    type: "unknown";
+}) & {
+    nullable?: true;
+};
+interface FarmNativeProperty {
+    name: string;
+    optional: boolean;
+    type: FarmNativeType;
+}
+interface FarmNativeMethod {
+    name: string;
+    params: FarmNativeProperty[];
+    /** What the Promise resolves with. */
+    returns: FarmNativeType;
+}
+/** The part of one Codegen spec web screens reach. */
+interface FarmNativeWebSpec {
+    /** Promise methods whose parameters web screens can send, in spec order. */
+    methods: FarmNativeMethod[];
+    /** Promise methods web screens cannot call, and why, such as a callback parameter. */
+    unsupported: Array<{
+        method: string;
+        reason: string;
+    }>;
+}
+
+/**
+ * Native modules (RFC 0004, 7.5): the app's own TurboModules in `src/native/`, and
+ * `mobile.modules`, the OS permission entries and usage strings per module.
+ */
+/** What the OS needs for one module: `mobile.modules.<name>`. */
+interface FarmMobileModuleConfig {
+    /**
+     * Android permissions the generated `AndroidManifest.xml` declares, such as
+     * `"android.permission.VIBRATE"`. Community modules already merge their own manifest's
+     * permissions, so this is for extra ones.
+     */
+    permissions?: string[];
+    /**
+     * iOS usage strings the generated `Info.plist` gets, keyed by usage-description key, such as
+     * `{ NSCameraUsageDescription: "Scans receipts." }`.
+     */
+    usage?: Record<string, string>;
+    /**
+     * Lets web screens (`page.tsx` in the shell's WebView) call the module's Promise methods as
+     * `native.<name>.<method>()` from `@farm.js/core/native`, with arguments checked against its
+     * Codegen spec. App modules in `src/native/` only: community modules need the React Native JS
+     * runtime. On iOS, a method with an object-typed parameter is not reachable (Codegen passes it to
+     * Objective-C as a C++ struct). Defaults to `false`.
+     */
+    web?: boolean;
+}
+interface ResolvedFarmMobileModuleConfig {
+    permissions: string[];
+    usage: Record<string, string>;
+    web: boolean;
+}
+/** One Codegen spec in `src/native/`, such as `NativeDevice.ts`. */
+interface FarmMobileAppModuleSpec {
+    /** The name the spec registers: `TurboModuleRegistry.getEnforcing<Spec>("Device")`. */
+    name: string;
+    /** Absolute path of the spec file. */
+    file: string;
+    /**
+     * With `mobile.modules.<name>.web`: the Promise methods web screens may call, read from the spec
+     * with React Native's Codegen.
+     */
+    web?: FarmNativeWebSpec;
+}
+/** The app's own native modules: the files in `src/native/` the generated projects copy. */
+interface FarmMobileAppModules {
+    /** Absolute path of `src/native/`. */
+    dir: string;
+    specs: FarmMobileAppModuleSpec[];
+    /** Absolute paths of the Kotlin files (`*.kt`), linked into the Android app. */
+    android: string[];
+    /**
+     * Absolute paths of the iOS files (`*.mm`, `*.m`, `*.h`, `*.swift`), built into the iOS app.
+     * A TurboModule is an Objective-C++ class that adopts its Codegen spec's `Native<Name>Spec`.
+     */
+    ios: string[];
+}
+
+type FarmMobileOS = "android" | "ios";
+/** How the native navigator shows a route: on a new stack screen, as a sheet, or in place. */
+type FarmMobilePresentation = "push" | "modal" | "replace";
+interface FarmMobileTab {
+    /** A static app route, such as `"/notes"`. Its screen is the tab's root. */
+    path: string;
+    title: string;
+    /** Platform icon name: an Android drawable or an SF Symbol on iOS, such as `"note.text"`. */
+    icon: string;
+}
+interface FarmMobileRouteConfig {
+    /** Defaults to `"push"`. A page's `export const mobile` wins. */
+    presentation?: FarmMobilePresentation;
+}
+/**
+ * What a route shows on mobile: a WebView of the web page (`"web"`), a screen from the
+ * `mobile.native.engine` (`"native"`), or a Compose or SwiftUI screen from `page.kt` or
+ * `page.swift` (`"platform"`).
+ */
+type FarmMobileScreen = "web" | "native" | "platform";
+/**
+ * What the route manifest shows for a route: a {@link FarmMobileScreen}, or `"server"`, a native
+ * screen the shell draws from the page the server renders (the analyzer's native tier). Config
+ * cannot ask for `"server"`; `export const mobile = { native: true }` or `native.auto: "on"` gets
+ * it for a page the analyzer proves. A shell that does not know a screen shows the route as web.
+ */
+type FarmMobileRouteScreen = FarmMobileScreen | "server";
+/** What builds native screens. Only the decision is recorded for now; no engine ships yet. */
+type FarmMobileNativeEngine = "react-native" | "platform";
+/**
+ * The build-time analyzer that finds pages a native screen could replace. `"report"` writes
+ * `native-report.json`; `"on"` also records its decisions in the route manifest.
+ */
+type FarmMobileNativeAuto = "off" | "report" | "on";
+/** `"intent"` starts a route's data request when a link to it is pressed. */
+type FarmMobilePrefetch = "intent" | "off";
+interface FarmMobileNativeRouteConfig {
+    /**
+     * Wins over the route's native files and the analyzer. `"native"` uses `page.native.tsx` (or
+     * the OS file) and otherwise asks the analyzer to port the page; `"platform"` needs `page.kt`
+     * or `page.swift`; `"web"` keeps the route web even when native files exist.
+     */
+    screen: FarmMobileScreen;
+    /** Overrides `screen` on Android. */
+    android?: FarmMobileScreen;
+    /** Overrides `screen` on iOS. */
+    ios?: FarmMobileScreen;
+    /** Defaults to `"push"`. Set it here or in `mobile.routes`, not both. */
+    presentation?: FarmMobilePresentation;
+}
+interface FarmMobileBudgets {
+    /** Installed app size, in MB. */
+    appSizeMb?: number;
+    /** Time from a tap to the next screen's first frame, in ms. */
+    screenOpenMs?: number;
+    /** Dropped frames allowed per screen open. */
+    droppedFrames?: number;
+}
+interface FarmMobileNativeConfig {
+    /** Defaults to `"react-native"`. */
+    engine?: FarmMobileNativeEngine;
+    /** Defaults to `"report"`. */
+    auto?: FarmMobileNativeAuto;
+    /** Per-route screens and navigation, keyed by app route pattern such as `"/notes/[id]"`. */
+    routes?: Record<string, FarmMobileNativeRouteConfig>;
+    /**
+     * Components that may render as native views inside web screens, such as `"Map"`. Reserved:
+     * no islands render yet.
+     */
+    islands?: string[];
+    /** Default for every route; a page's `export const mobile` wins. Defaults to `"intent"`. */
+    prefetch?: FarmMobilePrefetch;
+    budgets?: FarmMobileBudgets;
+}
+/**
+ * A page's `export const mobile = { ... }`, read from `page.tsx` without running it, so its
+ * values must be literals.
+ */
+interface FarmMobilePageConfig {
+    presentation?: FarmMobilePresentation;
+    prefetch?: FarmMobilePrefetch;
+    /**
+     * `false` keeps the route a web screen, even with a `page.native.tsx`. `true` requires a native
+     * screen: a native file next to the page, or a page the analyzer finds can render natively.
+     * The build fails, naming each blocker, when it cannot.
+     */
+    native?: boolean;
+}
+interface FarmMobileUserConfig {
+    /** Display name of the app. Defaults to the package.json `productName` or `name`. */
+    name?: string;
+    /**
+     * Reverse-DNS app identifier, used as the Android application ID and the iOS bundle ID, such as
+     * `"com.example.notes"`. Stores key the app on it. Defaults to `local.farm.<name>`.
+     */
+    id?: string;
+    /**
+     * Origin of the web deployment whose pages the app shows, such as `"https://notes.example.com"`.
+     * `http://` is allowed only for loopback and LAN hosts in dev.
+     */
+    server?: string;
+    /** Tab bar entries, at most 5. Without tabs the app is one stack starting at `/`. */
+    tabs?: FarmMobileTab[];
+    /** Per-route navigation, keyed by app route pattern such as `"/notes/[id]"`. */
+    routes?: Record<string, FarmMobileRouteConfig>;
+    /** Screen tiers per route, the native engine, and the analyzer. */
+    native?: FarmMobileNativeConfig;
+    /**
+     * Bundle a page shell, the route's layouts around its `loading.tsx`, into the app for routes
+     * whose loading file and layouts sit in static folders. A web screen that loads a document
+     * shows its shell at once, and keeps it up while the server is unreachable. Built by
+     * `farm build --mobile`; defaults to `false`.
+     */
+    shells?: boolean;
+    /**
+     * What the OS needs for each native module, keyed by module name: an app module's registered
+     * name (`src/native/NativeDevice.ts` registers `"Device"`) or an installed package such as
+     * `"react-native-vision-camera"`. `permissions` go into the Android manifest and `usage`
+     * strings into the iOS `Info.plist`.
+     */
+    modules?: Record<string, FarmMobileModuleConfig>;
+}
+/** What a function-valued `mobile` block receives. Resolved once per OS per dev start or build. */
+interface FarmMobileContext {
+    os: FarmMobileOS;
+    mode: "development" | "production";
+    command: "dev" | "build";
+    /** `--profile`, `"production"` by default. */
+    profile: string;
+    env: Readonly<Record<string, string | undefined>>;
+    /** App root. */
+    root: string;
+}
+/**
+ * `mobile` in farm.config: a static block, or a function of the platform context that returns
+ * one. The function runs in the CLI only; its code never reaches a server or browser bundle.
+ */
+type FarmMobileConfigInput = FarmMobileUserConfig | ((context: FarmMobileContext) => FarmMobileUserConfig | Promise<FarmMobileUserConfig>);
+interface ResolvedFarmMobileNativeConfig {
+    engine: FarmMobileNativeEngine;
+    auto: FarmMobileNativeAuto;
+    /** Keyed by route pattern with route groups removed. */
+    routes: Record<string, FarmMobileNativeRouteConfig>;
+    islands: string[];
+    prefetch: FarmMobilePrefetch;
+    budgets: FarmMobileBudgets;
+}
+interface ResolvedFarmMobileConfig {
+    name: string;
+    id: string;
+    /** Origin, without a trailing slash. Undefined only when the CLI supplies one (dev). */
+    server?: string;
+    tabs: FarmMobileTab[];
+    /** `mobile.routes`, keyed by route pattern with route groups removed. */
+    routes: Record<string, FarmMobileRouteConfig>;
+    native: ResolvedFarmMobileNativeConfig;
+    shells: boolean;
+    /** `mobile.modules`, checked: permissions deduplicated per module, usage strings trimmed. */
+    modules: Record<string, ResolvedFarmMobileModuleConfig>;
+}
+/**
+ * The origin a mobile app loads pages from. `https://` anywhere; `http://` only for loopback and
+ * LAN hosts (the emulator's `10.0.2.2`, `192.168.x.y`, `*.local`) when `command` is `"dev"`.
+ */
+declare function resolveFarmMobileServer(value: string, context: Pick<FarmMobileContext, "command">, check?: PlatformBlockChecker, key?: string): string;
+/**
+ * Check a page's `export const mobile` value, already read from its source. `where` names the
+ * file in errors.
+ */
+declare function validateFarmMobilePageConfig(value: unknown, where: string, context?: Pick<FarmMobileContext, "os">): FarmMobilePageConfig;
+/**
+ * Check a returned or static `mobile` block's shape. Route and module existence are checked by
+ * `resolveFarmMobileConfig`, which has the app's routes.
+ */
+declare function validateFarmMobileConfig(input: unknown, context?: Pick<FarmMobileContext, "os" | "command">): FarmMobileUserConfig | undefined;
+interface FarmMobileResolveOptions {
+    root: string;
+    srcDir?: string;
+    /** The app's page route patterns, such as `"/notes/[id]"` (route groups removed). */
+    routes: readonly string[];
+    /** Names the app's own native module specs register (`scanFarmMobileAppModules`). */
+    appModules?: readonly string[];
+}
+/**
+ * Fill in defaults for an already resolved (static or returned) `mobile` block and check it
+ * against the app: every tab, `routes`, and `native.routes` key must be a page route.
+ */
+declare function resolveFarmMobileConfig(input: FarmMobileUserConfig | undefined, options: FarmMobileResolveOptions, context: Pick<FarmMobileContext, "os" | "command">): ResolvedFarmMobileConfig;
+interface FarmMobileContextOptions {
+    command: FarmMobileContext["command"];
+    /** `--profile`; defaults to `"production"`. */
+    profile?: string;
+    /** Target OS; defaults to `"android"`, the first shell. */
+    os?: FarmMobileOS;
+    root: string;
+    mode: FarmMobileContext["mode"];
+}
+/** The context a function-valued block receives. `env` is a frozen snapshot. */
+declare function createFarmMobileContext(options: FarmMobileContextOptions): FarmMobileContext;
+/** Results of function-valued blocks for one dev session or build. */
+type FarmMobileBlockCache = PlatformBlockCache<FarmMobileUserConfig>;
+/**
+ * The plain `mobile` block for a context: the static object, or what the function returned.
+ * Validated, with errors naming the OS and field. With a cache, the function runs once per
+ * session and OS.
+ */
+declare function resolveFarmMobileBlock(input: FarmMobileConfigInput, context: FarmMobileContext, cache?: FarmMobileBlockCache): Promise<FarmMobileUserConfig>;
+
+export { type ResolvedFarmMobileNativeConfig as A, createFarmMobileContext as B, resolveFarmMobileBlock as C, resolveFarmMobileConfig as D, resolveFarmMobileServer as E, type FarmMobileOS as F, validateFarmMobileConfig as G, validateFarmMobilePageConfig as H, type PlatformBlockCache as P, type ResolvedFarmMobileConfig as R, type FarmMobileAppModules as a, type FarmMobileAppModuleSpec as b, type FarmMobileBudgets as c, type FarmMobileConfigInput as d, type FarmMobileContext as e, type FarmMobileModuleConfig as f, type FarmMobileNativeAuto as g, type FarmMobileNativeConfig as h, type FarmMobileNativeEngine as i, type FarmMobileNativeRouteConfig as j, type FarmMobilePageConfig as k, type FarmMobilePrefetch as l, type FarmMobilePresentation as m, type FarmMobileRouteConfig as n, type FarmMobileRouteScreen as o, type FarmMobileScreen as p, type FarmMobileTab as q, type FarmMobileUserConfig as r, type FarmNativeMethod as s, type FarmNativeProperty as t, type FarmNativeType as u, type FarmNativeWebSpec as v, type ResolvedFarmMobileModuleConfig as w, type FarmMobileBlockCache as x, type FarmMobileContextOptions as y, type FarmMobileResolveOptions as z };

package/dist/config.d-qt-mE8O5.d.ts

@@ -0,0 +1,341 @@
+/** Checks for one block, with errors prefixed by the block, such as `mobile (os: android)`. */
+interface PlatformBlockChecker {
+    fail(message: string): never;
+    checkKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>, where: string): void;
+    optionalString(value: unknown, key: string): string | undefined;
+}
+/** Results of function-valued blocks for one dev session or build. */
+type PlatformBlockCache<T> = Map<string, Promise<T>>;
+
+/**
+ * What web screens can call on an app native module (RFC 0004, 7.5): the Promise methods of its
+ * Codegen spec, read with React Native's own Codegen parser so the spec stays the one source. The
+ * Android shell checks arguments against these types before the module runs, and `src/farm.d.ts`
+ * types `native.<module>` from them.
+ */
+/** A value a web screen sends or receives, as the Codegen spec declares it. */
+type FarmNativeType = ({
+    type: "string";
+} | {
+    type: "number";
+    integer?: true;
+} | {
+    type: "boolean";
+}
+/** A string literal union, a single literal, or an enum: the values the spec allows. */
+ | {
+    type: "literal";
+    values: Array<string | number>;
+}
+/** An object type with declared properties: `ReadableMap` in Kotlin. */
+ | {
+    type: "object";
+    properties: FarmNativeProperty[];
+}
+/** `Object` or `UnsafeObject`: any JSON object, `ReadableMap` in Kotlin. */
+ | {
+    type: "map";
+}
+/** An array; without `element`, any JSON values. `ReadableArray` in Kotlin. */
+ | {
+    type: "array";
+    element?: FarmNativeType;
+}
+/** Return values only: `Promise<void>`. */
+ | {
+    type: "void";
+}
+/** Return values only: a type web screens get as JSON without a narrower type. */
+ | {
+    type: "unknown";
+}) & {
+    nullable?: true;
+};
+interface FarmNativeProperty {
+    name: string;
+    optional: boolean;
+    type: FarmNativeType;
+}
+interface FarmNativeMethod {
+    name: string;
+    params: FarmNativeProperty[];
+    /** What the Promise resolves with. */
+    returns: FarmNativeType;
+}
+/** The part of one Codegen spec web screens reach. */
+interface FarmNativeWebSpec {
+    /** Promise methods whose parameters web screens can send, in spec order. */
+    methods: FarmNativeMethod[];
+    /** Promise methods web screens cannot call, and why, such as a callback parameter. */
+    unsupported: Array<{
+        method: string;
+        reason: string;
+    }>;
+}
+
+/**
+ * Native modules (RFC 0004, 7.5): the app's own TurboModules in `src/native/`, and
+ * `mobile.modules`, the OS permission entries and usage strings per module.
+ */
+/** What the OS needs for one module: `mobile.modules.<name>`. */
+interface FarmMobileModuleConfig {
+    /**
+     * Android permissions the generated `AndroidManifest.xml` declares, such as
+     * `"android.permission.VIBRATE"`. Community modules already merge their own manifest's
+     * permissions, so this is for extra ones.
+     */
+    permissions?: string[];
+    /**
+     * iOS usage strings the generated `Info.plist` gets, keyed by usage-description key, such as
+     * `{ NSCameraUsageDescription: "Scans receipts." }`.
+     */
+    usage?: Record<string, string>;
+    /**
+     * Lets web screens (`page.tsx` in the shell's WebView) call the module's Promise methods as
+     * `native.<name>.<method>()` from `@farm.js/core/native`, with arguments checked against its
+     * Codegen spec. App modules in `src/native/` only: community modules need the React Native JS
+     * runtime. On iOS, a method with an object-typed parameter is not reachable (Codegen passes it to
+     * Objective-C as a C++ struct). Defaults to `false`.
+     */
+    web?: boolean;
+}
+interface ResolvedFarmMobileModuleConfig {
+    permissions: string[];
+    usage: Record<string, string>;
+    web: boolean;
+}
+/** One Codegen spec in `src/native/`, such as `NativeDevice.ts`. */
+interface FarmMobileAppModuleSpec {
+    /** The name the spec registers: `TurboModuleRegistry.getEnforcing<Spec>("Device")`. */
+    name: string;
+    /** Absolute path of the spec file. */
+    file: string;
+    /**
+     * With `mobile.modules.<name>.web`: the Promise methods web screens may call, read from the spec
+     * with React Native's Codegen.
+     */
+    web?: FarmNativeWebSpec;
+}
+/** The app's own native modules: the files in `src/native/` the generated projects copy. */
+interface FarmMobileAppModules {
+    /** Absolute path of `src/native/`. */
+    dir: string;
+    specs: FarmMobileAppModuleSpec[];
+    /** Absolute paths of the Kotlin files (`*.kt`), linked into the Android app. */
+    android: string[];
+    /**
+     * Absolute paths of the iOS files (`*.mm`, `*.m`, `*.h`, `*.swift`), built into the iOS app.
+     * A TurboModule is an Objective-C++ class that adopts its Codegen spec's `Native<Name>Spec`.
+     */
+    ios: string[];
+}
+
+type FarmMobileOS = "android" | "ios";
+/** How the native navigator shows a route: on a new stack screen, as a sheet, or in place. */
+type FarmMobilePresentation = "push" | "modal" | "replace";
+interface FarmMobileTab {
+    /** A static app route, such as `"/notes"`. Its screen is the tab's root. */
+    path: string;
+    title: string;
+    /** Platform icon name: an Android drawable or an SF Symbol on iOS, such as `"note.text"`. */
+    icon: string;
+}
+interface FarmMobileRouteConfig {
+    /** Defaults to `"push"`. A page's `export const mobile` wins. */
+    presentation?: FarmMobilePresentation;
+}
+/**
+ * What a route shows on mobile: a WebView of the web page (`"web"`), a screen from the
+ * `mobile.native.engine` (`"native"`), or a Compose or SwiftUI screen from `page.kt` or
+ * `page.swift` (`"platform"`).
+ */
+type FarmMobileScreen = "web" | "native" | "platform";
+/**
+ * What the route manifest shows for a route: a {@link FarmMobileScreen}, or `"server"`, a native
+ * screen the shell draws from the page the server renders (the analyzer's native tier). Config
+ * cannot ask for `"server"`; `export const mobile = { native: true }` or `native.auto: "on"` gets
+ * it for a page the analyzer proves. A shell that does not know a screen shows the route as web.
+ */
+type FarmMobileRouteScreen = FarmMobileScreen | "server";
+/** What builds native screens. Only the decision is recorded for now; no engine ships yet. */
+type FarmMobileNativeEngine = "react-native" | "platform";
+/**
+ * The build-time analyzer that finds pages a native screen could replace. `"report"` writes
+ * `native-report.json`; `"on"` also records its decisions in the route manifest.
+ */
+type FarmMobileNativeAuto = "off" | "report" | "on";
+/** `"intent"` starts a route's data request when a link to it is pressed. */
+type FarmMobilePrefetch = "intent" | "off";
+interface FarmMobileNativeRouteConfig {
+    /**
+     * Wins over the route's native files and the analyzer. `"native"` uses `page.native.tsx` (or
+     * the OS file) and otherwise asks the analyzer to port the page; `"platform"` needs `page.kt`
+     * or `page.swift`; `"web"` keeps the route web even when native files exist.
+     */
+    screen: FarmMobileScreen;
+    /** Overrides `screen` on Android. */
+    android?: FarmMobileScreen;
+    /** Overrides `screen` on iOS. */
+    ios?: FarmMobileScreen;
+    /** Defaults to `"push"`. Set it here or in `mobile.routes`, not both. */
+    presentation?: FarmMobilePresentation;
+}
+interface FarmMobileBudgets {
+    /** Installed app size, in MB. */
+    appSizeMb?: number;
+    /** Time from a tap to the next screen's first frame, in ms. */
+    screenOpenMs?: number;
+    /** Dropped frames allowed per screen open. */
+    droppedFrames?: number;
+}
+interface FarmMobileNativeConfig {
+    /** Defaults to `"react-native"`. */
+    engine?: FarmMobileNativeEngine;
+    /** Defaults to `"report"`. */
+    auto?: FarmMobileNativeAuto;
+    /** Per-route screens and navigation, keyed by app route pattern such as `"/notes/[id]"`. */
+    routes?: Record<string, FarmMobileNativeRouteConfig>;
+    /**
+     * Components that may render as native views inside web screens, such as `"Map"`. Reserved:
+     * no islands render yet.
+     */
+    islands?: string[];
+    /** Default for every route; a page's `export const mobile` wins. Defaults to `"intent"`. */
+    prefetch?: FarmMobilePrefetch;
+    budgets?: FarmMobileBudgets;
+}
+/**
+ * A page's `export const mobile = { ... }`, read from `page.tsx` without running it, so its
+ * values must be literals.
+ */
+interface FarmMobilePageConfig {
+    presentation?: FarmMobilePresentation;
+    prefetch?: FarmMobilePrefetch;
+    /**
+     * `false` keeps the route a web screen, even with a `page.native.tsx`. `true` requires a native
+     * screen: a native file next to the page, or a page the analyzer finds can render natively.
+     * The build fails, naming each blocker, when it cannot.
+     */
+    native?: boolean;
+}
+interface FarmMobileUserConfig {
+    /** Display name of the app. Defaults to the package.json `productName` or `name`. */
+    name?: string;
+    /**
+     * Reverse-DNS app identifier, used as the Android application ID and the iOS bundle ID, such as
+     * `"com.example.notes"`. Stores key the app on it. Defaults to `local.farm.<name>`.
+     */
+    id?: string;
+    /**
+     * Origin of the web deployment whose pages the app shows, such as `"https://notes.example.com"`.
+     * `http://` is allowed only for loopback and LAN hosts in dev.
+     */
+    server?: string;
+    /** Tab bar entries, at most 5. Without tabs the app is one stack starting at `/`. */
+    tabs?: FarmMobileTab[];
+    /** Per-route navigation, keyed by app route pattern such as `"/notes/[id]"`. */
+    routes?: Record<string, FarmMobileRouteConfig>;
+    /** Screen tiers per route, the native engine, and the analyzer. */
+    native?: FarmMobileNativeConfig;
+    /**
+     * Bundle a page shell, the route's layouts around its `loading.tsx`, into the app for routes
+     * whose loading file and layouts sit in static folders. A web screen that loads a document
+     * shows its shell at once, and keeps it up while the server is unreachable. Built by
+     * `farm build --mobile`; defaults to `false`.
+     */
+    shells?: boolean;
+    /**
+     * What the OS needs for each native module, keyed by module name: an app module's registered
+     * name (`src/native/NativeDevice.ts` registers `"Device"`) or an installed package such as
+     * `"react-native-vision-camera"`. `permissions` go into the Android manifest and `usage`
+     * strings into the iOS `Info.plist`.
+     */
+    modules?: Record<string, FarmMobileModuleConfig>;
+}
+/** What a function-valued `mobile` block receives. Resolved once per OS per dev start or build. */
+interface FarmMobileContext {
+    os: FarmMobileOS;
+    mode: "development" | "production";
+    command: "dev" | "build";
+    /** `--profile`, `"production"` by default. */
+    profile: string;
+    env: Readonly<Record<string, string | undefined>>;
+    /** App root. */
+    root: string;
+}
+/**
+ * `mobile` in farm.config: a static block, or a function of the platform context that returns
+ * one. The function runs in the CLI only; its code never reaches a server or browser bundle.
+ */
+type FarmMobileConfigInput = FarmMobileUserConfig | ((context: FarmMobileContext) => FarmMobileUserConfig | Promise<FarmMobileUserConfig>);
+interface ResolvedFarmMobileNativeConfig {
+    engine: FarmMobileNativeEngine;
+    auto: FarmMobileNativeAuto;
+    /** Keyed by route pattern with route groups removed. */
+    routes: Record<string, FarmMobileNativeRouteConfig>;
+    islands: string[];
+    prefetch: FarmMobilePrefetch;
+    budgets: FarmMobileBudgets;
+}
+interface ResolvedFarmMobileConfig {
+    name: string;
+    id: string;
+    /** Origin, without a trailing slash. Undefined only when the CLI supplies one (dev). */
+    server?: string;
+    tabs: FarmMobileTab[];
+    /** `mobile.routes`, keyed by route pattern with route groups removed. */
+    routes: Record<string, FarmMobileRouteConfig>;
+    native: ResolvedFarmMobileNativeConfig;
+    shells: boolean;
+    /** `mobile.modules`, checked: permissions deduplicated per module, usage strings trimmed. */
+    modules: Record<string, ResolvedFarmMobileModuleConfig>;
+}
+/**
+ * The origin a mobile app loads pages from. `https://` anywhere; `http://` only for loopback and
+ * LAN hosts (the emulator's `10.0.2.2`, `192.168.x.y`, `*.local`) when `command` is `"dev"`.
+ */
+declare function resolveFarmMobileServer(value: string, context: Pick<FarmMobileContext, "command">, check?: PlatformBlockChecker, key?: string): string;
+/**
+ * Check a page's `export const mobile` value, already read from its source. `where` names the
+ * file in errors.
+ */
+declare function validateFarmMobilePageConfig(value: unknown, where: string, context?: Pick<FarmMobileContext, "os">): FarmMobilePageConfig;
+/**
+ * Check a returned or static `mobile` block's shape. Route and module existence are checked by
+ * `resolveFarmMobileConfig`, which has the app's routes.
+ */
+declare function validateFarmMobileConfig(input: unknown, context?: Pick<FarmMobileContext, "os" | "command">): FarmMobileUserConfig | undefined;
+interface FarmMobileResolveOptions {
+    root: string;
+    srcDir?: string;
+    /** The app's page route patterns, such as `"/notes/[id]"` (route groups removed). */
+    routes: readonly string[];
+    /** Names the app's own native module specs register (`scanFarmMobileAppModules`). */
+    appModules?: readonly string[];
+}
+/**
+ * Fill in defaults for an already resolved (static or returned) `mobile` block and check it
+ * against the app: every tab, `routes`, and `native.routes` key must be a page route.
+ */
+declare function resolveFarmMobileConfig(input: FarmMobileUserConfig | undefined, options: FarmMobileResolveOptions, context: Pick<FarmMobileContext, "os" | "command">): ResolvedFarmMobileConfig;
+interface FarmMobileContextOptions {
+    command: FarmMobileContext["command"];
+    /** `--profile`; defaults to `"production"`. */
+    profile?: string;
+    /** Target OS; defaults to `"android"`, the first shell. */
+    os?: FarmMobileOS;
+    root: string;
+    mode: FarmMobileContext["mode"];
+}
+/** The context a function-valued block receives. `env` is a frozen snapshot. */
+declare function createFarmMobileContext(options: FarmMobileContextOptions): FarmMobileContext;
+/** Results of function-valued blocks for one dev session or build. */
+type FarmMobileBlockCache = PlatformBlockCache<FarmMobileUserConfig>;
+/**
+ * The plain `mobile` block for a context: the static object, or what the function returned.
+ * Validated, with errors naming the OS and field. With a cache, the function runs once per
+ * session and OS.
+ */
+declare function resolveFarmMobileBlock(input: FarmMobileConfigInput, context: FarmMobileContext, cache?: FarmMobileBlockCache): Promise<FarmMobileUserConfig>;
+
+export { type ResolvedFarmMobileNativeConfig as A, createFarmMobileContext as B, resolveFarmMobileBlock as C, resolveFarmMobileConfig as D, resolveFarmMobileServer as E, type FarmMobileOS as F, validateFarmMobileConfig as G, validateFarmMobilePageConfig as H, type PlatformBlockCache as P, type ResolvedFarmMobileConfig as R, type FarmMobileAppModules as a, type FarmMobileAppModuleSpec as b, type FarmMobileBudgets as c, type FarmMobileConfigInput as d, type FarmMobileContext as e, type FarmMobileModuleConfig as f, type FarmMobileNativeAuto as g, type FarmMobileNativeConfig as h, type FarmMobileNativeEngine as i, type FarmMobileNativeRouteConfig as j, type FarmMobilePageConfig as k, type FarmMobilePrefetch as l, type FarmMobilePresentation as m, type FarmMobileRouteConfig as n, type FarmMobileRouteScreen as o, type FarmMobileScreen as p, type FarmMobileTab as q, type FarmMobileUserConfig as r, type FarmNativeMethod as s, type FarmNativeProperty as t, type FarmNativeType as u, type FarmNativeWebSpec as v, type ResolvedFarmMobileModuleConfig as w, type FarmMobileBlockCache as x, type FarmMobileContextOptions as y, type FarmMobileResolveOptions as z };