craft-native 0.0.123 → 0.0.125

package/dist/android/templates/build.gradle.kts.app.template

@@ -59,6 +59,7 @@ dependencies {
     implementation("androidx.appcompat:appcompat:1.6.1")
     implementation("androidx.fragment:fragment-ktx:1.6.2")
     implementation("androidx.recyclerview:recyclerview:1.3.2")
+{{REFRESH_LAYOUT_DEPENDENCY}}
     implementation("androidx.webkit:webkit:1.12.1")
 {{JAVASCRIPT_ENGINE_DEPENDENCY}}
     implementation("com.google.android.material:material:1.11.0")

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.
@@ -792,12 +812,229 @@ export declare const tabBar: {
  * 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 a moment after the page finishes loading, and after ten
- * seconds at most.
+ * 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;
 };
+/** Letters, digits, `.`, `_` and `-`, not starting with a dot: the names the shell accepts. */
+export declare function isSnapshotName(name: string): boolean;
+/**
+ * Data the page keeps for its native screens. A native screen reads a
+ * snapshot synchronously before its first frame (`craft.snapshots.get(name)`),
+ * so it opens on the last data the page saw instead of an empty skeleton.
+ * Write one whenever the page has fresh data a native screen shows.
+ *
+ * Each is `Application Support/craft-snapshots/<name>.json` in the app.
+ * Outside a hybrid app every call is a no-op answering false.
+ */
+export declare const snapshots: {
+    isAvailable(): boolean;
+    /** Keep `value` (anything JSON can hold) as `name`. Answers whether it was handed to the shell. */
+    set(name: string, value: unknown): boolean;
+    remove(name: string): boolean;
+    /** Every snapshot, as on signing out. */
+    clear(): boolean;
+};
+/**
+ * Navigation between the page and the app's native screens.
+ *
+ * The shell already hands the stx router's navigations to native paths to
+ * the native screens, and Back at the entry a native screen opened goes back
+ * to it, so most pages need none of this. It is for code that navigates
+ * without the router.
+ */
+export declare const hybrid: {
+    /** Whether this page runs inside a hybrid app. */
+    isActive(): boolean;
+    /** The native screen `path` opens, or null when it is the page's. */
+    nativeScreenFor(path: string): {
+        path: string;
+        screen: string;
+        params: Record<string, string>;
+    } | null;
+    /** Open `path` as the shell would: a tab, a native screen, or the page pushed. */
+    open(path: string): boolean;
+    /** Back to the native screen under this page, when there is one. */
+    back(): 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>;
 };
@@ -957,5 +1194,16 @@ declare const mobile: {
     watchConnectivity: typeof watchConnectivity;
     tabBar: typeof tabBar;
     splash: typeof splash;
+    snapshots: typeof snapshots;
+    hybrid: typeof hybrid;
+    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.123";
+var version = "0.0.125";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];
@@ -3611,7 +3611,7 @@ cli.command("ios init <name>", "Initialize a new iOS project").option("--bundle-
     config: options?.renderer ? { renderer: options.renderer } : undefined
   });
 });
-cli.command("ios build", "Build iOS project").option("--html-path <path>", "Path to HTML file").option("--native-bundle <path>", "JavaScript bundle compiled by stx-native").option("-d, --dev-server <url>", "Development server URL").option("-o, --output <dir>", "iOS project directory", { default: "./ios" }).option("-w, --watch", "Watch for file changes and rebuild").example("craft ios build").example("craft ios build --html-path ./dist/index.html").example("craft ios build --native-bundle ./screen.js").example("craft ios build --dev-server http://localhost:3456").example("craft ios build --watch").action(async (options) => {
+cli.command("ios build", "Build iOS project").option("--html-path <path>", "Path to HTML file").option("--native-bundle <path>", "JavaScript bundle from `stx native compile`").option("-d, --dev-server <url>", "Development server URL").option("-o, --output <dir>", "iOS project directory", { default: "./ios" }).option("-w, --watch", "Watch for file changes and rebuild").example("craft ios build").example("craft ios build --html-path ./dist/index.html").example("craft ios build --native-bundle ./screen.js").example("craft ios build --dev-server http://localhost:3456").example("craft ios build --watch").action(async (options) => {
   const iosModule = await import(iosModuleURL);
   const doBuild = async () => {
     await iosModule.build({
@@ -3661,7 +3661,7 @@ cli.command("android init <name>", "Initialize a new Android project").option("-
     config: options?.renderer ? { renderer: options.renderer } : undefined
   });
 });
-cli.command("android build", "Build Android project").option("--html-path <path>", "Path to HTML file").option("--native-bundle <path>", "JavaScript bundle compiled by stx-native").option("-d, --dev-server <url>", "Development server URL").option("-o, --output <dir>", "Android project directory", { default: "./android" }).option("--release", "Build release APK").option("-w, --watch", "Watch for file changes and rebuild").example("craft android build").example("craft android build --release").example("craft android build --native-bundle ./screen.js").example("craft android build --watch").action(async (options) => {
+cli.command("android build", "Build Android project").option("--html-path <path>", "Path to HTML file").option("--native-bundle <path>", "JavaScript bundle from `stx native compile`").option("-d, --dev-server <url>", "Development server URL").option("-o, --output <dir>", "Android project directory", { default: "./android" }).option("--release", "Build release APK").option("-w, --watch", "Watch for file changes and rebuild").example("craft android build").example("craft android build --release").example("craft android build --native-bundle ./screen.js").example("craft android build --watch").action(async (options) => {
   const androidModule = await import(androidModuleURL);
   const doBuild = async () => {
     await androidModule.build({

package/dist/index.cjs

@@ -310,7 +310,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.123";
+var version = "0.0.125";
 
 // 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.123";
+var version = "0.0.125";
 
 // 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,11 +78,30 @@ 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;
     /**
@@ -103,8 +122,83 @@ 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'>;
+    /**
+     * Hybrid: app paths drawn as native stx screens instead of in the
+     * web view, each to the screen in the native bundle that draws it, e.g.
+     * `{ "/m": "Today", "/m/calendar": "Calendar" }`. A segment may be a
+     * parameter (`/m/workout/:id`) and the last one `*`. Needs `renderer: "web"`
+     * and `nativeBundle`; every other path stays in the web view, and a path
+     * whose screen is missing or throws falls back to it.
+     */
+    nativeScreens?: Record<string, string>;
+    /** Hybrid: the bundle `stx native compile --format bundle` wrote, copied to `dist/native-screen.js`. */
+    nativeBundle?: string;
+    /**
+     * The native tab bar, shown from the first frame, before the page loads.
+     * The page's own `tabBar.set` replaces it later. Each `id` is the tab's
+     * root path, as the page's tab links name it.
+     */
+    tabs?: CraftTab[];
+    /**
+     * Hybrid: web-storage keys the page writes (localStorage or
+     * sessionStorage) that native screens need, mirrored into the Keychain
+     * under the name given, e.g. `{ "auth_token": "auth.token" }` for
+     * `craft.secureStorage.getSync('auth.token')`. Turns on secure storage.
+     */
+    shareStorage?: Record<string, string>;
+}
+export interface CraftTab {
+    /** The tab's root path; comes back to the page in `craftTabSelect`. */
+    id: string;
+    title: string;
+    /** An SF Symbol name. */
+    symbol?: string;
+}
+/** `/a//b/?q#h` → `/a/b`, the way the shell and the page compare paths. Null for a relative path. */
+export declare function normalizeNativePath(raw: string): string | null;
+export interface NativePathMatch {
+    path: string;
+    screen: string;
+    params: Record<string, string>;
+}
+/**
+ * The native screen for a path, by the rules the shell (`CraftHybridRoutes`)
+ * and the page script apply: static segments win over `:params`, which win
+ * over a trailing `*`; query items become params under the path's own.
+ */
+export declare function matchNativePath(nativeScreens: Record<string, string> | undefined, raw: string): NativePathMatch | null;
+/** Whether a config mixes native screens into its web page. */
+export declare function isHybrid(config: Pick<CraftConfig, 'renderer' | 'nativeScreens'>): boolean;
+/** What is wrong with a config's hybrid and tab settings, one sentence each. */
+export declare function hybridConfigProblems(config: Pick<CraftConfig, 'renderer' | 'nativeScreens' | 'tabs' | 'shareStorage'>): string[];
+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;
@@ -145,7 +239,7 @@ export interface InitOptions {
 }
 export interface BuildOptions {
     htmlPath?: string;
-    /** JavaScript bundle emitted by `stx-native compile Screen.stx --format bundle`. */
+    /** JavaScript bundle emitted by `stx native compile Screen.stx --format bundle`. */
     nativeBundlePath?: string;
     devServer?: string;
     output: string;
@@ -185,6 +279,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;
 /**
@@ -219,6 +323,24 @@ export declare function pngHasAlpha(bytes: Uint8Array): boolean;
 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;
 /**