craft-native 0.0.122 → 0.0.124

package/dist/api/mobile.d.ts

@@ -203,6 +203,14 @@ export declare const haptics: {
      * Use when a selection changes (e.g., picker value change).
      */
     selection(): Promise<void>;
+    /**
+     * Warm the haptic engine ahead of a haptic the page knows is coming (the
+     * start of a drag, a long press about to complete), so it plays on the frame
+     * it is asked for. `impact`, `notification` or `selection` for one kind, an
+     * impact style or notification type for that one, nothing for all. iOS keeps
+     * a prepared engine awake for a few seconds. A no-op elsewhere.
+     */
+    prepare(kind?: HapticStyle | HapticNotificationType | 'impact' | 'notification' | 'selection'): Promise<void>;
     /**
      * Vibrate with a custom pattern.
      *
@@ -608,6 +616,18 @@ export declare const lifecycle: {
      * @returns Function to remove listener
      */
     onStateChange(callback: (state: AppState) => void): () => void;
+    /**
+     * The app came back to the foreground (`craftResume`), with how long it was
+     * away. A page can refresh what may have gone stale. iOS shell only.
+     */
+    onResume(callback: (event: {
+        backgroundedMs: number;
+    }) => void): () => void;
+    /**
+     * iOS is short of memory (`craftMemoryWarning`): drop caches, or the page's
+     * content process may be ended. iOS shell only.
+     */
+    onMemoryWarning(callback: () => void): () => void;
 };
 /**
  * Notification options.
@@ -754,6 +774,226 @@ export declare const network: {
     getStatus(): Promise<NetworkStatus>;
     onChange(callback: (status: NetworkStatus) => void): () => void;
 };
+/** A tab the native tab bar shows. */
+export interface NativeTab {
+    /** Comes back in `onSelect` when the tab is tapped. */
+    id: string;
+    title: string;
+    /** An SF Symbol name, such as `calendar`; the current tab draws its `.fill` variant when there is one. */
+    symbol: string;
+    /** A count on the icon; empty draws none. */
+    badge?: string;
+}
+export interface NativeTabBarOptions {
+    /** The current tab's id. */
+    selected?: string;
+    /** The current tab's colour, as `#rrggbb`; the system's label colour if unset. */
+    tint?: string;
+    tintDark?: string;
+}
+/**
+ * The phone's own tab bar, floating over the page: Liquid Glass on iOS 26 and
+ * later. The page describes it and keeps it on the current tab; a tap comes
+ * back through `onSelect` for the page to navigate. Where there is no native
+ * bar (a browser, Android for now), `isAvailable()` is false and every call is
+ * a no-op answering false, so the page draws its own.
+ *
+ * While the bar shows, `--craft-tab-bar-height` on the root element says how
+ * much of the screen's bottom it covers.
+ */
+export declare const tabBar: {
+    isAvailable(): boolean;
+    set(tabs: NativeTab[], options?: NativeTabBarOptions): boolean;
+    select(id: string): boolean;
+    hide(): boolean;
+    onSelect(callback: (id: string) => void): () => void;
+};
+/**
+ * The launch splash, which the shell holds over the page until the page says
+ * it is ready, so the app goes from its launch screen to content with no blank
+ * page in between. Call `hide()` once the first screen has painted. The shell
+ * hides it anyway once the page's first contentful paint is on screen, and
+ * after `splashMaxSeconds` (three by default) at most.
+ */
+export declare const splash: {
+    hide(): boolean;
+};
+/** A rect in the viewport's CSS pixels. */
+export interface NativeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Where a popover, sheet or menu points: a rect, or an element to point at. */
+export type NativeAnchor = NativeRect | {
+    getBoundingClientRect(): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+};
+export interface DialogAlertOptions {
+    title: string;
+    message?: string;
+    /** The button. The system's own "OK" if unset. */
+    okLabel?: string;
+}
+export interface DialogConfirmOptions {
+    title: string;
+    message?: string;
+    /** The confirming button. The system's own "OK" if unset. */
+    confirmLabel?: string;
+    /** The system's own "Cancel" if unset. */
+    cancelLabel?: string;
+    /** Paints the confirming button red, as iOS does for a delete. */
+    destructive?: boolean;
+}
+export interface ActionSheetAction {
+    id: string;
+    title: string;
+    /** `cancel` answers `null` whatever its id. */
+    style?: 'default' | 'destructive' | 'cancel';
+}
+export interface ActionSheetOptions {
+    title?: string;
+    message?: string;
+    actions: ActionSheetAction[];
+    /** Where the sheet points on iPad (and, from iOS 26, on iPhone). */
+    anchor?: NativeAnchor;
+}
+export interface ContextMenuItem {
+    id: string;
+    title: string;
+    /** An SF Symbol name, such as `trash`. */
+    symbol?: string;
+    destructive?: boolean;
+    disabled?: boolean;
+}
+export interface ContextMenuOptions {
+    items: ContextMenuItem[];
+    anchor: NativeAnchor;
+    title?: string;
+}
+export interface BrowserOpenOptions {
+    /** `safari`: SFSafariViewController in the app. `auth`: the system's web sign-in sheet. */
+    mode?: 'safari' | 'auth';
+    /** For `auth`: the URL scheme the provider redirects back to. */
+    callbackScheme?: string;
+}
+export interface BrowserOpenResult {
+    /** For `auth`: the callback URL the provider redirected to. */
+    url?: string;
+    cancelled: boolean;
+    error?: string;
+}
+export type SymbolWeight = 'ultraLight' | 'thin' | 'light' | 'regular' | 'medium' | 'semibold' | 'bold' | 'heavy' | 'black';
+export interface SymbolImageOptions {
+    /** Default 17. */
+    pointSize?: number;
+    weight?: SymbolWeight;
+    /** A CSS colour. The label colour if unset. */
+    color?: string;
+    scale?: 'small' | 'medium' | 'large';
+}
+export type StatusBarStyle = 'default' | 'light' | 'dark';
+/** The reading and motion settings the page should match. */
+export interface NativeAppearance {
+    /** The Dynamic Type size, as UIKit names it: `large` is the default. */
+    contentSizeCategory: string;
+    /** Body text's scale from its default size; also `--craft-font-scale` on the root element. */
+    fontScale: number;
+    reduceMotion: boolean;
+    reduceTransparency: boolean;
+    colorScheme: 'light' | 'dark';
+}
+/** A `craftSilentPush` or `craftBackgroundRefresh`. */
+export interface BackgroundWorkEvent {
+    /** Pass to `background.complete` to answer this one. */
+    id?: string;
+    /** The push's payload, for a silent push. */
+    payload?: Record<string, unknown>;
+}
+/**
+ * The system's alert, confirmation and action sheet. Off the iOS shell every
+ * call resolves without showing anything (`confirm` with false, `actionSheet`
+ * with null), so check `isAvailable()` to draw a web fallback.
+ */
+export declare const dialog: {
+    isAvailable(): boolean;
+    alert(options: DialogAlertOptions | string): Promise<void>;
+    confirm(options: DialogConfirmOptions | string): Promise<boolean>;
+    /** The chosen action's id, or null when dismissed. */
+    actionSheet(options: ActionSheetOptions): Promise<string | null>;
+};
+/**
+ * The system's context menu, anchored at a rect or element: the list with SF
+ * Symbols a long press shows (iOS 17.4 and later; the edit menu, then an
+ * action sheet, before). The chosen item's id, or null when dismissed.
+ */
+export declare const contextMenu: {
+    isAvailable(): boolean;
+    show(options: ContextMenuOptions): Promise<string | null>;
+};
+/**
+ * A page elsewhere without leaving the app: SFSafariViewController, or for
+ * `mode: 'auth'` the system's web sign-in sheet, which answers with the
+ * callback URL. On the web, `safari` opens a new tab and `auth` cannot catch
+ * the callback, so it answers cancelled.
+ */
+export declare const browser: {
+    isAvailable(): boolean;
+    open(url: string, options?: BrowserOpenOptions): Promise<BrowserOpenResult>;
+};
+/** An SF Symbol rasterised to a PNG data URL, or null where there are none. */
+export declare const symbols: {
+    image(name: string, options?: SymbolImageOptions): Promise<string | null>;
+};
+/** The status bar's text: light, dark, or the system's choice for the app's appearance. */
+export declare const statusBar: {
+    setStyle(style: StatusBarStyle): Promise<boolean>;
+};
+/** The shell's chrome around the page. */
+export declare const chrome: {
+    /** What shows past the page's edges when it rubber-bands (iOS 15). */
+    setUnderPageColor(color: string): Promise<boolean>;
+    /** WebKit's bar above the keyboard (previous, next, Done). Hidden by default. */
+    setKeyboardAccessory(visible: boolean): Promise<boolean>;
+};
+/**
+ * The system's pull-to-refresh on the page's scroll view. A pull fires
+ * `onRefresh`; call `end()` once the new content is in. It is removed when the
+ * document changes, so a page enables it for itself.
+ */
+export declare const refresh: {
+    isAvailable(): boolean;
+    enable(options?: {
+        tintColor?: string;
+    }): Promise<boolean>;
+    disable(): Promise<boolean>;
+    end(): Promise<boolean>;
+    onRefresh(callback: () => void): () => void;
+};
+/**
+ * Background time on iOS: a silent push (`content-available`) and the
+ * scheduled refresh (`backgroundRefresh.enabled` in the Craft config). Each
+ * waits for `complete(ok)` from the page, or 25 seconds.
+ */
+export declare const background: {
+    complete(ok?: boolean, id?: string): Promise<boolean>;
+    onRefresh(callback: (event: BackgroundWorkEvent) => void): () => void;
+    onSilentPush(callback: (event: BackgroundWorkEvent) => void): () => void;
+};
+/**
+ * Text size, Reduce Motion, Reduce Transparency and Light or Dark. In the iOS
+ * shell from the native settings (Dynamic Type included, which a web page
+ * cannot otherwise see); elsewhere from the media queries a browser has.
+ */
+export declare const appearance: {
+    get(): NativeAppearance | null;
+    onChange(callback: (appearance: NativeAppearance) => void): () => void;
+};
 export declare const appReview: {
     request(): Promise<boolean>;
 };
@@ -911,5 +1151,16 @@ declare const mobile: {
     health: typeof health;
     liveActivities: typeof liveActivities;
     watchConnectivity: typeof watchConnectivity;
+    tabBar: typeof tabBar;
+    splash: typeof splash;
+    dialog: typeof dialog;
+    contextMenu: typeof contextMenu;
+    browser: typeof browser;
+    symbols: typeof symbols;
+    statusBar: typeof statusBar;
+    chrome: typeof chrome;
+    refresh: typeof refresh;
+    background: typeof background;
+    appearance: typeof appearance;
 };
 export default mobile;

package/dist/cli.js

@@ -3303,7 +3303,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.122";
+var version = "0.0.124";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -310,7 +310,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.122";
+var version = "0.0.124";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -4885,6 +4885,14 @@ var haptics = {
       navigator.vibrate(5);
     }
   },
+  async prepare(kind) {
+    const craft = getCraftMobile();
+    if (typeof window !== "undefined" && craft?.haptics?.prepare) {
+      try {
+        await craft.haptics.prepare(kind);
+      } catch {}
+    }
+  },
   async vibrate(pattern) {
     const craft = getCraftMobile();
     if (typeof window !== "undefined" && craft?.haptics) {
@@ -5256,6 +5264,12 @@ var lifecycle = {
     };
     document.addEventListener("visibilitychange", handler);
     return () => document.removeEventListener("visibilitychange", handler);
+  },
+  onResume(callback) {
+    return onCraftEvent("craftResume", (detail) => callback({ backgroundedMs: Number(detail.backgroundedMs) || 0 }));
+  },
+  onMemoryWarning(callback) {
+    return onCraftEvent("craftMemoryWarning", () => callback());
   }
 };
 function bridgeNotification(options, now = Date.now()) {
@@ -5310,6 +5324,13 @@ var notifications = {
   }
 };
 var speakingOnTheWeb = new Set;
+function onCraftEvent(eventName, callback) {
+  if (typeof globalThis === "undefined")
+    return () => {};
+  const listener = (event) => callback(event.detail ?? {});
+  globalThis.addEventListener(eventName, listener);
+  return () => globalThis.removeEventListener(eventName, listener);
+}
 function detectPlatform2() {
   if (typeof window === "undefined")
     return "linux";

package/dist/index.js

@@ -58,7 +58,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.122";
+var version = "0.0.124";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -4645,6 +4645,14 @@ var haptics = {
       navigator.vibrate(5);
     }
   },
+  async prepare(kind) {
+    const craft = getCraftMobile();
+    if (typeof window !== "undefined" && craft?.haptics?.prepare) {
+      try {
+        await craft.haptics.prepare(kind);
+      } catch {}
+    }
+  },
   async vibrate(pattern) {
     const craft = getCraftMobile();
     if (typeof window !== "undefined" && craft?.haptics) {
@@ -5016,6 +5024,12 @@ var lifecycle = {
     };
     document.addEventListener("visibilitychange", handler);
     return () => document.removeEventListener("visibilitychange", handler);
+  },
+  onResume(callback) {
+    return onCraftEvent("craftResume", (detail) => callback({ backgroundedMs: Number(detail.backgroundedMs) || 0 }));
+  },
+  onMemoryWarning(callback) {
+    return onCraftEvent("craftMemoryWarning", () => callback());
   }
 };
 function bridgeNotification(options, now = Date.now()) {
@@ -5070,6 +5084,13 @@ var notifications = {
   }
 };
 var speakingOnTheWeb = new Set;
+function onCraftEvent(eventName, callback) {
+  if (typeof globalThis === "undefined")
+    return () => {};
+  const listener = (event) => callback(event.detail ?? {});
+  globalThis.addEventListener(eventName, listener);
+  return () => globalThis.removeEventListener(eventName, listener);
+}
 function detectPlatform2() {
   if (typeof window === "undefined")
     return "linux";

package/dist/ios/src/index.d.ts

@@ -78,13 +78,42 @@ export interface CraftConfig {
     /**
      * Also refuse to load anything but the app-bound domains in the web view
      * (WKWebViewConfiguration.limitsNavigationsToAppBoundDomains). Off by
-     * default: links elsewhere already open in Safari, and embedded players and
-     * maps in iframes keep loading.
+     * default: links elsewhere already open in Safari. WebKit applies the limit
+     * to the main frame only, so embedded players and maps in cross-origin
+     * iframes (YouTube, Vimeo) keep loading with it on (checked in the iOS 26
+     * simulator); WebKit only declines to inject user scripts into them, which
+     * the bridge never does.
      */
     limitNavigationsToAppBoundDomains?: boolean;
+    /**
+     * Universal links and shared web credentials
+     * (`com.apple.developer.associated-domains`). A bare host such as
+     * `hq.training` is written as `applinks:hq.training`; an entry with its own
+     * service (`webcredentials:`, `applinks:…?mode=developer`) is kept as given.
+     * A universal link reaches the page the way a custom-scheme link does, as
+     * `craftDeepLink`.
+     */
     associatedDomains?: string[];
+    /**
+     * iOS's scheduled background refresh (BGAppRefreshTask). When enabled the
+     * page gets `craftBackgroundRefresh` and answers with
+     * `craft.background.complete(ok)`. The identifier defaults to
+     * `<bundleId>.refresh` and is declared in BGTaskSchedulerPermittedIdentifiers,
+     * with the `fetch` background mode.
+     */
+    backgroundRefresh?: CraftBackgroundRefresh;
     appGroups?: string[];
     appIconPath?: string;
+    /**
+     * The logo the launch screen shows on `backgroundColor`, and that stays on
+     * screen until the page says it is ready (`splash.hide()`), so the app goes
+     * from launch to content without a blank web view in between. PNG, PDF or
+     * SVG, drawn at its own size in points: give an SVG the width and height it
+     * should have on screen.
+     */
+    splashImagePath?: string;
+    /** The splash logo in Dark Mode, on `backgroundColorDark`. The light one if unset. */
+    splashImagePathDark?: string;
     /**
      * Whether the app uses encryption beyond the exempt kinds (HTTPS, the
      * system's own). Written as `ITSAppUsesNonExemptEncryption`, so App Store
@@ -93,9 +122,36 @@ export interface CraftConfig {
      */
     usesNonExemptEncryption?: boolean;
     privacy?: CraftPrivacyManifest;
+    /** Press-and-hold link previews, as in Safari. Default false. */
+    allowsLinkPreview?: boolean;
+    /**
+     * WebKit's bar above the keyboard for a form field (previous, next, Done),
+     * which no native app's keyboard has. Default false: hidden. A page can
+     * change it with `craft.chrome.setKeyboardAccessory()`.
+     */
+    keyboardAccessory?: boolean;
+    /** Pinch and double-tap zoom off, and the page's viewport pinned at scale 1. Default true. */
+    disableZoom?: boolean;
+    /**
+     * The longest the launch splash stays up, in seconds, when the page neither
+     * hides it (`splash.hide()`) nor paints. Default 3.
+     */
+    splashMaxSeconds?: number;
+    /**
+     * How long the app's own page may take to answer, in seconds, before the
+     * load counts as unreachable and the bundled page stands in. Default 10.
+     */
+    requestTimeoutSeconds?: number;
     orientations?: Array<'portrait' | 'landscape-left' | 'landscape-right' | 'portrait-upside-down'>;
     deviceFamilies?: Array<'iphone' | 'ipad'>;
 }
+export interface CraftBackgroundRefresh {
+    enabled: boolean;
+    /** The BGTaskScheduler identifier. Default `<bundleId>.refresh`. */
+    identifier?: string;
+    /** The soonest iOS may run it again, in minutes. Default 15. */
+    minimumIntervalMinutes?: number;
+}
 export interface CraftPrivacyDataType {
     type: string;
     linked?: boolean;
@@ -175,6 +231,16 @@ export declare function renderOrientations(config: CraftConfig): string;
 export declare function renderAppBoundDomains(config: CraftConfig): string;
 export declare function renderUrlTypes(config: CraftConfig): string;
 export declare function renderBackgroundModes(config: CraftConfig): string;
+/** The background refresh task's identifier, or null when it is off. */
+export declare function backgroundRefreshIdentifier(config: Pick<CraftConfig, 'backgroundRefresh' | 'bundleId'>): string | null;
+/** BGTaskSchedulerPermittedIdentifiers: iOS runs no task it does not list. */
+export declare function renderBackgroundTaskIdentifiers(config: Pick<CraftConfig, 'backgroundRefresh' | 'bundleId'>): string;
+/**
+ * The associated-domains entitlement's entries. Each needs a service prefix,
+ * and a bare host (the easy thing to write) used to be signed as it was and
+ * then matched nothing, so universal links silently never opened the app.
+ */
+export declare function associatedDomainEntries(domains: string[] | undefined): string[];
 export declare function renderEntitlements(config: CraftConfig): string;
 export declare function renderWatchEntitlements(config: CraftConfig): string;
 /**
@@ -205,6 +271,28 @@ export declare function renderPrivacyManifest(config: CraftConfig): string;
  * (grey + alpha) or 6 (RGB + alpha), or a tRNS chunk before the image data.
  */
 export declare function pngHasAlpha(bytes: Uint8Array): boolean;
+/** The asset the launch screen and the splash both draw, so one hands over to the other unseen. */
+export declare const LAUNCH_LOGO = "LaunchLogo";
+/** The launch screen: the background colour, and the splash logo on it when there is one. */
+export declare function renderLaunchScreen(config: Pick<CraftConfig, 'splashImagePath'>): string;
+/** Near-black or near-white, whichever reads on `background` (WCAG relative luminance). */
+export declare function readableTextOn(background: string | undefined): string;
+/**
+ * The page the app shows when its own page cannot be reached: the generated
+ * `dist/index.html` until the app's web assets replace it.
+ *
+ * An app whose page has a service worker normally opens from it offline, so
+ * this only shows on a first launch without one, or when the remote fails
+ * hard. It used to be a placeholder that said "Built with Craft iOS" in white
+ * on whatever the background was (invisible on a light one) with a bridge
+ * status line under it: debug output, in front of the person using the app.
+ *
+ * Now it says what happened in the app's own colours, light and dark, sized
+ * with Dynamic Type, and Retry asks the shell to load the app's page again.
+ * The shell also goes back to the app's page by itself when the connection
+ * returns, so the page does not retry on `online` as well.
+ */
+export declare function renderOfflinePage(config: Pick<CraftConfig, 'appName' | 'backgroundColor' | 'backgroundColorDark'>): string;
 /** Replace the bundled web application atomically so removed assets cannot linger. */
 export declare function syncWebAssets(source: string, output: string): void;
 /**