@craft-native/ios 0.0.92 → 0.0.95

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Craft iOS Builder
+ *
+ * Generates native iOS apps from web content using WKWebView.
+ */
+export interface CraftConfig {
+    appName: string;
+    bundleId: string;
+    version?: string;
+    buildNumber?: string;
+    darkMode?: boolean;
+    backgroundColor?: string;
+    enableSpeechRecognition?: boolean;
+    enableHaptics?: boolean;
+    enableShare?: boolean;
+    enableCamera?: boolean;
+    enableBiometric?: boolean;
+    enablePushNotifications?: boolean;
+    enableSecureStorage?: boolean;
+    enableGeolocation?: boolean;
+    enableClipboard?: boolean;
+    enableContacts?: boolean;
+    enableCalendar?: boolean;
+    enableLocalNotifications?: boolean;
+    enableInAppPurchase?: boolean;
+    enableKeepAwake?: boolean;
+    enableOrientationLock?: boolean;
+    enableDeepLinks?: boolean;
+    enableQRScanner?: boolean;
+    enableFilePicker?: boolean;
+    enableFileDownload?: boolean;
+    enableSocialAuth?: boolean;
+    enableAudioRecording?: boolean;
+    enableVideoRecording?: boolean;
+    enableMotionSensors?: boolean;
+    enableLocalDatabase?: boolean;
+    enableBluetooth?: boolean;
+    enableNFC?: boolean;
+    enableHealthKit?: boolean;
+    enableLiveActivities?: boolean;
+    enableWatchApp?: boolean;
+    enableBackgroundLocation?: boolean;
+    enableBackgroundTasks?: boolean;
+    enableScreenCapture?: boolean;
+    enablePDFViewer?: boolean;
+    enableAR?: boolean;
+    enableMLKit?: boolean;
+    devServerURL?: string;
+    iosVersion?: string;
+    watchosVersion?: string;
+    teamId?: string;
+    urlSchemes?: string[];
+    trustedOrigins?: string[];
+    associatedDomains?: string[];
+    appGroups?: string[];
+    appIconPath?: string;
+    privacy?: CraftPrivacyManifest;
+    orientations?: Array<'portrait' | 'landscape-left' | 'landscape-right' | 'portrait-upside-down'>;
+    deviceFamilies?: Array<'iphone' | 'ipad'>;
+}
+export interface CraftPrivacyDataType {
+    type: string;
+    linked?: boolean;
+    tracking?: boolean;
+    purposes: string[];
+}
+export interface CraftPrivacyAccessedApiType {
+    type: string;
+    reasons: string[];
+}
+export interface CraftPrivacyManifest {
+    tracking?: boolean;
+    trackingDomains?: string[];
+    collectedDataTypes?: CraftPrivacyDataType[];
+    accessedApiTypes?: CraftPrivacyAccessedApiType[];
+}
+export interface InitOptions {
+    name: string;
+    bundleId?: string;
+    teamId?: string;
+    output: string;
+    config?: Partial<CraftConfig>;
+    /**
+     * Where the Zig runtime archives live, overriding `CRAFT_IOS_RUNTIME`.
+     *
+     * `null` means "no runtime, whatever the environment says" — the shape
+     * `AppConfig.craftPath` has for `CRAFT_BIN`, and the reason it exists here
+     * is the same: a caller that does not opt in should not be steered by an
+     * ambient variable. Without it this package's own tests inherited whatever
+     * the developer's shell exported, and went from 12 passing to 8 passing and
+     * 4 failing when `CRAFT_IOS_RUNTIME` happened to be set.
+     *
+     * Omitted (`undefined`) keeps the environment lookup, which is what the
+     * monorepo dev loop uses.
+     */
+    runtimeDir?: string | null;
+}
+export interface BuildOptions {
+    htmlPath?: string;
+    devServer?: string;
+    output: string;
+    generateProject?: boolean;
+    /**
+     * Where to re-read the Zig runtime archives from, overriding
+     * `CRAFT_IOS_RUNTIME`. Same meaning as `InitOptions.runtimeDir`; `null`
+     * leaves whatever `init` installed exactly as it is.
+     */
+    runtimeDir?: string | null;
+}
+export interface OpenOptions {
+    output: string;
+}
+export interface RunOptions {
+    simulator: boolean;
+    output: string;
+}
+export declare function renderDeviceFamilies(config: CraftConfig): string;
+export declare function renderUsageDescriptions(config: CraftConfig): string;
+export declare function renderOrientations(config: CraftConfig): string;
+export declare function renderUrlTypes(config: CraftConfig): string;
+export declare function renderBackgroundModes(config: CraftConfig): string;
+export declare function renderEntitlements(config: CraftConfig): string;
+export declare function renderWatchEntitlements(config: CraftConfig): string;
+/**
+ * The build settings that link the Zig runtime into the app target.
+ *
+ * Two things are load-bearing here:
+ *
+ * `LIBRARY_SEARCH_PATHS` is written twice, once per SDK, so `-lcraft-ios`
+ * resolves to the device archive for a device build and the simulator archive
+ * for a simulator one without the flag itself changing. Xcode applies the
+ * `[sdk=...]` condition; xcodegen passes these keys through verbatim.
+ *
+ * The four `-u` flags are the reason anything works at all. Nothing in the
+ * Swift source *references* these symbols — `CraftZigRuntime` and
+ * `CraftSwiftShim` both find them with `dlsym` at runtime — so a static
+ * archive contributes no objects for them and the linker drops the entire
+ * runtime as unreachable. `-u` names them as undefined so the objects are
+ * pulled in and the symbols end up in the binary for `dlsym` to find.
+ *
+ * `-u` rather than `-force_load`: forcing the whole archive would pull in
+ * every object whether reachable or not, and these four entry points already
+ * reach everything the bridge actually uses.
+ */
+export declare function renderRuntimeSettings(): string;
+export declare function renderPrivacyManifest(config: CraftConfig): string;
+/** Replace the bundled web application atomically so removed assets cannot linger. */
+export declare function syncWebAssets(source: string, output: string): void;
+/**
+ * Initialize a new iOS project
+ */
+/**
+ * Where the Zig runtime archives live, or null when this build has none.
+ *
+ * `CRAFT_IOS_RUNTIME` points at a directory holding the archives `zig build
+ * build-ios-all` produces. It is opt-in and there is deliberately no fallback
+ * search: a generated project with no runtime is the shipping default today,
+ * and it works — `CraftZigRuntime.offer` is a `dlsym` miss, every action
+ * answers false, and the Swift switch serves the whole surface exactly as it
+ * always has. Guessing at a path would turn "no runtime" into "some runtime,
+ * from somewhere", which is the failure mode the pantry contract exists to
+ * rule out.
+ *
+ * This is the same shape as `CRAFT_BIN`: an explicit override for the monorepo
+ * dev loop, not a lookup path. Shipping the runtime to real apps means putting
+ * these archives in the pantry package beside the `craft` binary, which is a
+ * distribution decision this function does not make.
+ *
+ * `override` is what `InitOptions.runtimeDir` passes: a path to use instead of
+ * the variable, or `null` to declare there is no runtime regardless of what the
+ * environment says. `undefined` falls through to `CRAFT_IOS_RUNTIME`.
+ */
+export declare function resolveRuntimeDir(override?: string | null): string | null;
+/**
+ * Copy the Zig archives into the generated project as `Runtime/<sdk>/libcraft-ios.a`.
+ *
+ * One name for both SDKs, in two directories, because that is what lets a
+ * single `-lcraft-ios` in OTHER_LDFLAGS work for device and simulator builds:
+ * Xcode picks the directory by SDK and the flag never changes.
+ *
+ * Returns true when a runtime was installed.
+ */
+export declare function installRuntime(output: string, runtimeDir: string): Promise<boolean>;
+export declare function init(options: InitOptions): Promise<void>;
+/**
+ * Build web assets and generate Xcode project
+ */
+export declare function build(options: BuildOptions): Promise<void>;
+/**
+ * Open Xcode project
+ */
+export declare function open(options: OpenOptions): Promise<void>;
+/**
+ * Build and run on simulator or device
+ */
+/** One bootable simulator, as `simctl list` describes it. */
+export interface SimulatorDevice {
+    name: string;
+    udid: string;
+    state: string;
+    runtime: string;
+}
+/**
+ * Every available *iOS* simulator, newest runtime first, iPhones before iPads.
+ *
+ * Exported because the choice is worth testing without a simulator present -
+ * `pickSimulator` is the policy and this is the data it reads.
+ */
+export declare function orderSimulators(devices: SimulatorDevice[]): SimulatorDevice[];
+/**
+ * The device to run on.
+ *
+ * A booted one first - if the developer already has a simulator open, that is
+ * the one they are looking at - then the newest iPhone.
+ *
+ * This used to be the string `iPhone 15`, hard-coded into the `-destination`
+ * argument. On a machine whose Xcode ships iPhone 17 and no iPhone 15, that is
+ * not a fallback, it is `xcodebuild: error: Unable to find a device named
+ * 'iPhone 15'` - the command fails for a reason that has nothing to do with the
+ * app being built, and the fix is invisible from the error.
+ */
+export declare function pickSimulator(): Promise<SimulatorDevice | null>;
+/**
+ * Boot it, and wait until it can actually do something.
+ *
+ * `simctl boot` returns as soon as the device starts booting, and a device
+ * that reports `Booted` is minutes away from being able to install anything on
+ * a cold runtime. `bootstatus` is the wait, and skipping it is why a first run
+ * on a fresh machine fails where the second succeeds.
+ */
+export declare function bootSimulator(device: SimulatorDevice): Promise<void>;
+/**
+ * Bring the Simulator window to the front, if it can be found.
+ *
+ * `open -a Simulator` resolves through LaunchServices, and LaunchServices only
+ * knows the name if a Simulator.app has been registered under it - which is not
+ * true on a machine running Xcode-beta, where the answer is `Unable to find
+ * application named 'Simulator'`. The app is always at a known path under the
+ * *selected* developer directory, so that is tried first.
+ *
+ * Never throws. The window is a convenience: the app is installed and launched
+ * either way, and failing the whole run because a window did not come to the
+ * front would be reporting a cosmetic problem as a build failure.
+ */
+export declare function showSimulator(): Promise<void>;
+export declare function run(options: RunOptions): Promise<void>;