@craft-native/ios 0.0.122 → 0.0.124

package/README.md

@@ -64,6 +64,9 @@ Build native iOS apps with web technologies using Craft.
 
 The iOS support is built into the main `craft` CLI:
 
+`FlatList` item roots receive the same `onLayout` callback as ordinary native
+views when rows are materialized or recycled.
+
 ```bash
 bun add craft-native
 ```
@@ -106,7 +109,7 @@ In Xcode:
 
 ### Experimental WebView-free screen
 
-The opt-in `native` renderer hosts compiled `.stx` screens in JavaScriptCore and renders their `View`, `SafeAreaView`, `Text`, `Button`, `TextInput`, `Image`, `ScrollView`, and recycling `FlatList` nodes as UIKit controls. `FlatList` uses `UICollectionView` with stable keyed rows, incremental diffs, grids, horizontal and inverted layouts, list chrome, and end-reached pagination. Native screens also expose the versioned capability bridge: JSON storage and SQLite survive relaunch, lifecycle and deep-link events are scoped to the top route, and local notifications use `UNUserNotificationCenter`. Enable each capability in `craft.config.json`; disabled calls preserve Craft's `CAPABILITY_DISABLED` rejection code and every request has deterministic timeout/cancellation behavior. The default remains `web`; existing iOS apps are unchanged. The portable component, capability, list, style, image-source, event, accessibility, and reconciliation behavior is specified in the [Native STX guide](../../docs/guides/native-stx.md).
+The opt-in `native` renderer hosts compiled `.stx` screens in JavaScriptCore and renders their `View`, `SafeAreaView`, `Text`, `Button`, `TextInput`, `ActivityIndicator`, `Image`, `ScrollView`, and recycling `FlatList` nodes as UIKit controls. `FlatList` uses `UICollectionView` with stable keyed rows, incremental diffs, grids, horizontal and inverted layouts, list chrome, and end-reached pagination. Native views support `onLayout` callbacks with point-based frame measurements that refresh after safe-area or orientation changes. Flex items support `flex`, `flexGrow`, `flexShrink`, and numeric `flexBasis` for main-axis space distribution. Native screens also expose the versioned capability bridge: JSON storage and SQLite survive relaunch, lifecycle and deep-link events are scoped to the top route, and local notifications use `UNUserNotificationCenter`. Enable each capability in `craft.config.json`; disabled calls preserve Craft's `CAPABILITY_DISABLED` rejection code and every request has deterministic timeout/cancellation behavior. The default remains `web`; existing iOS apps are unchanged. `Switch` supports state-aware `trackColor`, `thumbColor`, and iOS `ios_backgroundColor`; `Slider` supports track/thumb tint props and `step` snapping; `Image` reports load lifecycle events and structured failures. The portable component, capability, list, style, image-source, event, accessibility, and reconciliation behavior is specified in the [Native STX guide](../../docs/guides/native-stx.md).
 
 ```bash
 craft ios init NativeDemo --renderer native --output ./ios-native
@@ -122,6 +125,9 @@ supports it and fall back to whole-document rendering for older bundles.
 Updates reconcile the UIKit tree by sibling-scoped `key` (or `testID` for
 existing screens); unkeyed children reuse their position. `TextInput` objects
 therefore keep focus and selection while unrelated labels and buttons change.
+Native `TextInput` also applies `placeholderTextColor`, `selectionColor`,
+positive `maxLength`, `multiline`, and `numberOfLines` values while preserving
+the WebView fallback for routes that do not opt into the renderer.
 The protocol wire format, atomic validation, revisions, and error codes are in
 the [Native STX guide](../../docs/guides/native-stx.md). On macOS,
 `bun packages/ios/scripts/test-native-render.ts` runs the renderer's unit and
@@ -129,6 +135,8 @@ simulator UI tests.
 
 For multiple native screens, configure named `.stx` routes and an initial screen in `stx-native.config.json` (see [`fixtures/native-navigation`](./fixtures/native-navigation)). Compile without a positional file: `stx-native compile --format bundle --output ./screen.js`. A screen can call `craft.navigation.push('details', { id: 7 })`, `.replace('home')`, or `.back()`; the destination reads `craft.route.params`. Craft uses a native navigation stack, so the back button and edge-swipe reveal the existing controller and retain its JavaScript and input state. `bun packages/ios/scripts/test-native-navigation.ts` compiles the fixture and runs its simulator test; the default WebView renderer is unchanged.
 
+The optional Liquid Glass tab-bar styling is compiler-gated for Xcode 26/Swift 6.2 and later. Older SDKs compile the same tab bar with the material fallback, so generated projects remain buildable on Xcode 16.
+
 The iOS host overlays `craft.config.json` on its defaults. Missing or `null` capability flags stay disabled; explicitly set a flag to `true` to enable it. Both the Swift host and Zig bridge reject malformed values and fall back to all capabilities disabled.
 
 Edit `craft.config.json` in your iOS project:
@@ -203,12 +211,64 @@ development environment and Release builds use the production environment.
 The generated entitlements select the correct value from the active Xcode
 build configuration automatically.
 
+### Launch, offline and the feel of the web view
+
+```json
+{
+  "splashMaxSeconds": 3,
+  "requestTimeoutSeconds": 10,
+  "allowsLinkPreview": false,
+  "keyboardAccessory": false,
+  "disableZoom": true,
+  "associatedDomains": ["hq.training"],
+  "backgroundRefresh": { "enabled": true, "minimumIntervalMinutes": 30 }
+}
+```
+
+- `splashMaxSeconds` (default 3): the splash stays until the page calls
+  `splash.hide()` or its first contentful paint is on screen, and never longer
+  than this.
+- `requestTimeoutSeconds` (default 10): how long the app's own page may take
+  before the load counts as unreachable and the bundled page stands in.
+- The bundled page `init` writes (`dist/index.html`, until your web assets
+  replace it) is an offline page in the app's colours, light and dark, whose
+  Retry loads the remote page again. An app whose page has a service worker
+  normally opens from it offline; this shows on a first launch without one or
+  after a hard failure. With `appBoundDomains` it is loaded as a page of the
+  remote origin, because WebKit refuses to navigate from an app-bound domain
+  to `craft://app`.
+- `allowsLinkPreview` (default false): Safari's press-and-hold link previews.
+- `keyboardAccessory` (default false): WebKit's previous/next/Done bar above
+  the keyboard. Change it at runtime with `craft.chrome.setKeyboardAccessory`.
+- `disableZoom` (default true): no pinch or double-tap zoom, and the page's
+  viewport pinned at scale 1.
+- `associatedDomains`: universal links. A bare host is signed as
+  `applinks:<host>`; a universal link reaches the page as `craftDeepLink`, like
+  a custom-scheme link.
+- `backgroundRefresh`: a BGAppRefreshTask (`<bundleId>.refresh` unless
+  `identifier` is set), declared in `BGTaskSchedulerPermittedIdentifiers` with
+  the `fetch` background mode, scheduled no sooner than
+  `minimumIntervalMinutes` (default 15). It fires `craftBackgroundRefresh`.
+
+The web view also: shows `alert`, `confirm` and `prompt` as system alerts;
+opens `target=_blank` and `window.open` for the app's own origins in place and
+anything else in `SFSafariViewController`; grants `getUserMedia` to the app's
+own origin without WebKit's extra prompt; dismisses the keyboard with a drag;
+allows picture in picture; ends its user agent with `Craft/<version>
+<AppName>/<version>`; brings a page whose content process died back under the
+splash, on the page it was showing, at most three times a minute before
+showing the offline page; and saves its `interactionState` when the app goes to
+the background, so a launch after iOS ended the app returns to the same screen
+(same build only).
+
 ## JavaScript Bridge
 
 Once Craft is initialized, the `window.craft` object is available:
 
 ```javascript
-// Wait for Craft to be ready
+// window.craft is installed at document start, before the page's own scripts,
+// so it can be used at once. craftReady still fires, once, when the document
+// has been parsed, for pages that wait for it.
 window.addEventListener('craftReady', (e) => {
   console.log('Platform:', e.detail.platform); // 'ios'
   console.log('Capabilities:', e.detail.capabilities);
@@ -600,6 +660,64 @@ window.craft.watch.onReachabilityChange((status) => {
 });
 ```
 
+### Native UI, appearance and background (iOS)
+
+Every call below returns a promise that settles and never throws: a failure
+answers with what "nothing happened" means for it. `craft-native/mobile`
+exports the same calls typed (`dialog`, `contextMenu`, `browser`, `symbols`,
+`statusBar`, `chrome`, `refresh`, `background`, `appearance`), resolving
+outside the shell too.
+
+```javascript
+// Haptics by kind, each on UIKit's own generator, kept warm.
+await craft.haptics.impact('rigid');          // light, medium, heavy, soft, rigid
+await craft.haptics.notification('success');  // success, warning, error
+await craft.haptics.selection();
+await craft.haptics.prepare('selection');     // before a gesture that will play one
+
+// System dialogs. An anchor is a rect in CSS pixels or an element.
+await craft.dialog.alert({ title: 'Saved' });
+const ok = await craft.dialog.confirm({ title: 'Delete workout?', confirmLabel: 'Delete', destructive: true });
+const choice = await craft.dialog.actionSheet({
+  title: 'Workout',
+  anchor: button,
+  actions: [{ id: 'edit', title: 'Edit' }, { id: 'delete', title: 'Delete', style: 'destructive' }],
+}); // the id, or null when dismissed
+
+// The system context menu (iOS 17.4+; the edit menu, then an action sheet, before).
+const picked = await craft.contextMenu.show({
+  anchor: row,
+  items: [{ id: 'duplicate', title: 'Duplicate', symbol: 'plus.square.on.square' }, { id: 'delete', title: 'Delete', symbol: 'trash', destructive: true }],
+});
+
+// SFSafariViewController, or the system web sign-in sheet.
+await craft.browser.open('https://example.com');
+const { url, cancelled } = await craft.browser.open(authorizeURL, { mode: 'auth', callbackScheme: 'hqtraining' });
+
+// An SF Symbol as a PNG data URL.
+img.src = await craft.symbols.image('heart.fill', { pointSize: 22, weight: 'semibold', color: '#e11d48' });
+
+// Chrome around the page.
+await craft.statusBar.setStyle('light');           // default, light, dark
+await craft.chrome.setUnderPageColor('#020617');    // shown past the page's edges
+await craft.chrome.setKeyboardAccessory(true);
+
+// Native pull to refresh.
+await craft.refresh.enable({ tintColor: '#22c55e' });
+craft.refresh.onRefresh(async () => { await reload(); craft.refresh.end(); });
+```
+
+Events on `window`:
+
+| Event | Detail | When |
+| --- | --- | --- |
+| `craftAppearance` | `{ contentSizeCategory, fontScale, reduceMotion, reduceTransparency, colorScheme }` | with `craftReady`, and whenever Dynamic Type, Reduce Motion, Reduce Transparency or Light/Dark changes. The root element also carries `--craft-font-scale`, `data-craft-reduce-motion`, `data-craft-reduce-transparency` and `data-craft-content-size` from the first byte; `craft.appearance` reads the current values. |
+| `craftResume` | `{ backgroundedMs }` | the app returned to the foreground |
+| `craftMemoryWarning` | `{}` | iOS is short of memory |
+| `craftSilentPush` | `{ id, payload }` | a `content-available` push; answer with `craft.background.complete(ok, id)` within 25 s |
+| `craftBackgroundRefresh` | `{ id }` | the scheduled refresh ran; answer the same way |
+| `craftRefresh` | `{}` | the native pull-to-refresh was pulled |
+
 ## CLI Reference
 
 ```bash

package/dist/cli.js

@@ -9,6 +9,13 @@ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statS
 import { dirname, join, resolve } from "path";
 var {$ } = globalThis.Bun;
 var TEMPLATES_DIR = join(dirname(import.meta.dir), "templates");
+var CRAFT_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(dirname(import.meta.dir), "package.json"), "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
 var DEFAULT_CONFIG = {
   renderer: "web",
   version: "1.0.0",
@@ -176,6 +183,8 @@ function plistArray(values, indent = 2) {
 }
 function renderBackgroundModes(config) {
   const modes = new Set;
+  if (config.backgroundRefresh?.enabled)
+    modes.add("fetch");
   if (config.enableBackgroundLocation)
     modes.add("location");
   if (config.enableBackgroundTasks)
@@ -189,12 +198,30 @@ function renderBackgroundModes(config) {
 ${plistArray([...modes])}
     </array>`;
 }
+function backgroundRefreshIdentifier(config) {
+  if (!config.backgroundRefresh?.enabled)
+    return null;
+  return config.backgroundRefresh.identifier?.trim() || `${config.bundleId}.refresh`;
+}
+function renderBackgroundTaskIdentifiers(config) {
+  const identifier = backgroundRefreshIdentifier(config);
+  if (!identifier)
+    return "";
+  return `    <key>BGTaskSchedulerPermittedIdentifiers</key>
+    <array>
+${plistArray([identifier])}
+    </array>`;
+}
+function associatedDomainEntries(domains) {
+  return [...new Set((domains ?? []).map((value) => value.trim()).filter(Boolean).map((value) => /^[a-z]+:/i.test(value) ? value : `applinks:${value}`))];
+}
 function renderEntitlements(config) {
   const entries = [];
-  if (config.associatedDomains?.length) {
+  const associatedDomains = associatedDomainEntries(config.associatedDomains);
+  if (associatedDomains.length) {
     entries.push(`    <key>com.apple.developer.associated-domains</key>
     <array>
-${plistArray(config.associatedDomains)}
+${plistArray(associatedDomains)}
     </array>`);
   }
   if (config.appGroups?.length) {
@@ -378,6 +405,142 @@ function renderAssetCatalog(output, config) {
     info: { author: "xcode", version: 1 }
   }, null, 2)}
 `);
+  renderLaunchLogo(catalog, config);
+}
+var LAUNCH_LOGO = "LaunchLogo";
+function renderLaunchLogo(catalog, config) {
+  const imageset = join(catalog, `${LAUNCH_LOGO}.imageset`);
+  rmSync(imageset, { recursive: true, force: true });
+  if (!config.splashImagePath)
+    return;
+  mkdirSync(imageset, { recursive: true });
+  const images = [];
+  let vector = false;
+  for (const [source, dark] of [[config.splashImagePath, false], [config.splashImagePathDark, true]]) {
+    if (!source)
+      continue;
+    if (!existsSync(source))
+      throw new Error(`Splash image not found: ${source}`);
+    const extension = source.split(".").pop().toLowerCase();
+    if (extension === "svg" || extension === "pdf")
+      vector = true;
+    const filename = `${LAUNCH_LOGO}${dark ? "-dark" : ""}.${extension}`;
+    cpSync(source, join(imageset, filename));
+    images.push({
+      ...dark ? { appearances: [{ appearance: "luminosity", value: "dark" }] } : {},
+      filename,
+      idiom: "universal"
+    });
+  }
+  writeFileSync(join(imageset, "Contents.json"), `${JSON.stringify({
+    images,
+    info: { author: "xcode", version: 1 },
+    ...vector ? { properties: { "preserves-vector-representation": true } } : {}
+  }, null, 2)}
+`);
+}
+function renderLaunchScreen(config) {
+  const image = config.splashImagePath ? `
+        <key>UIImageName</key>
+        <string>${LAUNCH_LOGO}</string>` : "";
+  return `        <key>UIColorName</key>
+        <string>LaunchBackground</string>${image}`;
+}
+function hexChannels(hex) {
+  const value = hex?.trim().replace(/^#/, "") ?? "";
+  const full = value.length === 3 ? [...value].map((digit) => digit + digit).join("") : value.slice(0, 6);
+  if (!/^[0-9a-f]{6}$/i.test(full))
+    return null;
+  return [0, 2, 4].map((index) => Number.parseInt(full.slice(index, index + 2), 16));
+}
+function readableTextOn(background) {
+  const channels = hexChannels(background);
+  if (!channels)
+    return "#0f172a";
+  const [r, g, b] = channels.map((channel) => {
+    const c = channel / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  return luminance > 0.4 ? "#0f172a" : "#f8fafc";
+}
+function renderOfflinePage(config) {
+  const light = hexChannels(config.backgroundColor) ? config.backgroundColor : "#ffffff";
+  const dark = hexChannels(config.backgroundColorDark) ? config.backgroundColorDark : light;
+  const name = xmlEscape(config.appName);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="viewport-fit=cover, width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
+  <meta name="color-scheme" content="light dark">
+  <title>${name}</title>
+  <style>
+    :root { --background: ${light}; --text: ${readableTextOn(light)}; }
+    @media (prefers-color-scheme: dark) {
+      :root { --background: ${dark}; --text: ${readableTextOn(dark)}; }
+    }
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { height: 100%; }
+    body {
+      font: -apple-system-body;
+      font-family: -apple-system, system-ui, sans-serif;
+      background: var(--background);
+      color: var(--text);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      text-align: center;
+      padding: calc(env(safe-area-inset-top) + 24px) calc(env(safe-area-inset-right) + 32px) calc(env(safe-area-inset-bottom) + 24px) calc(env(safe-area-inset-left) + 32px);
+      -webkit-user-select: none;
+      user-select: none;
+      -webkit-tap-highlight-color: transparent;
+    }
+    main { max-width: 22rem; }
+    .app { font: -apple-system-subheadline; font-weight: 600; opacity: 0.6; margin-bottom: 0.5rem; }
+    h1 { font: -apple-system-title1; font-weight: 700; margin-bottom: 0.75rem; }
+    p { opacity: 0.72; line-height: 1.4; }
+    button {
+      font: -apple-system-headline;
+      margin-top: 1.75rem;
+      min-width: 9rem;
+      min-height: 44px;
+      padding: 0.75rem 1.75rem;
+      border: 0;
+      border-radius: 999px;
+      background: var(--text);
+      color: var(--background);
+      cursor: pointer;
+    }
+    button:active { opacity: 0.7; }
+    button:disabled { opacity: 0.5; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="app">${name}</div>
+    <h1>You're offline</h1>
+    <p>${name} could not reach the internet. Check your connection, then try again.</p>
+    <button id="retry" type="button">Retry</button>
+  </main>
+  <script>
+    (function () {
+      var button = document.getElementById('retry');
+      function retry() {
+        button.disabled = true;
+        button.textContent = 'Retrying';
+        var handler = window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.craft;
+        if (handler) handler.postMessage({ action: 'retryRemote' });
+        else location.reload();
+        // Still here a while later means the page is still out of reach.
+        setTimeout(function () { button.disabled = false; button.textContent = 'Retry'; }, 12000);
+      }
+      button.addEventListener('click', retry);
+    })();
+  </script>
+</body>
+</html>
+`;
 }
 function syncWebAssets(source, output) {
   const sourcePath = resolve(source);
@@ -487,14 +650,15 @@ async function init(options) {
     config.enableGeolocation = true;
   writeFileSync(join(output, "craft.config.json"), JSON.stringify(config, null, 2));
   const swiftTemplate = readFileSync(join(TEMPLATES_DIR, "CraftApp.swift"), "utf-8");
-  const swiftSource = swiftTemplate.replace(/CraftApp/g, `${name}App`).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
+  const swiftSource = swiftTemplate.replace(/CraftApp/g, `${name}App`).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{CRAFT_VERSION\}\}/g, CRAFT_VERSION);
   writeFileSync(join(output, "Sources", `${name}App.swift`), swiftSource);
   cpSync(join(TEMPLATES_DIR, "CraftNativeScreen.swift"), join(output, "Sources", "CraftNativeScreen.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeFlatList.swift"), join(output, "Sources", "CraftNativeFlatList.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeMutation.swift"), join(output, "Sources", "CraftNativeMutation.swift"));
+  cpSync(join(TEMPLATES_DIR, "CraftNativeUI.swift"), join(output, "Sources", "CraftNativeUI.swift"));
   const infoPlistTemplate = readFileSync(join(TEMPLATES_DIR, "Info.plist.template"), "utf-8");
-  const infoPlist = infoPlistTemplate.replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{VERSION\}\}/g, config.version || "1.0.0").replace(/\{\{BUILD_NUMBER\}\}/g, config.buildNumber || "1").replace(/\{\{UI_STYLE\}\}/g, renderAppearance(config).interfaceStyle).replace(/\{\{STATUS_BAR_STYLE\}\}/g, renderAppearance(config).statusBarStyle).replace(/\{\{ORIENTATIONS\}\}/g, renderOrientations(config)).replace(/\{\{USAGE_DESCRIPTIONS\}\}/g, renderUsageDescriptions(config)).replace(/\{\{URL_TYPES\}\}/g, renderUrlTypes(config)).replace(/\{\{APP_BOUND_DOMAINS\}\}/g, renderAppBoundDomains(config)).replace(/\{\{BACKGROUND_MODES\}\}/g, renderBackgroundModes(config)).replace(/\{\{NON_EXEMPT_ENCRYPTION\}\}/g, config.usesNonExemptEncryption ? "true" : "false").replace(/\{\{LIVE_ACTIVITY_SUPPORT\}\}/g, config.enableLiveActivities ? `    <key>NSSupportsLiveActivities</key>
+  const infoPlist = infoPlistTemplate.replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{VERSION\}\}/g, config.version || "1.0.0").replace(/\{\{BUILD_NUMBER\}\}/g, config.buildNumber || "1").replace(/\{\{UI_STYLE\}\}/g, renderAppearance(config).interfaceStyle).replace(/\{\{STATUS_BAR_STYLE\}\}/g, renderAppearance(config).statusBarStyle).replace(/\{\{ORIENTATIONS\}\}/g, renderOrientations(config)).replace(/\{\{USAGE_DESCRIPTIONS\}\}/g, renderUsageDescriptions(config)).replace(/\{\{URL_TYPES\}\}/g, renderUrlTypes(config)).replace(/\{\{APP_BOUND_DOMAINS\}\}/g, renderAppBoundDomains(config)).replace(/\{\{BACKGROUND_MODES\}\}/g, renderBackgroundModes(config)).replace(/\{\{BACKGROUND_TASK_IDENTIFIERS\}\}/g, renderBackgroundTaskIdentifiers(config)).replace(/\{\{LAUNCH_SCREEN\}\}/g, renderLaunchScreen(config)).replace(/\{\{NON_EXEMPT_ENCRYPTION\}\}/g, config.usesNonExemptEncryption ? "true" : "false").replace(/\{\{LIVE_ACTIVITY_SUPPORT\}\}/g, config.enableLiveActivities ? `    <key>NSSupportsLiveActivities</key>
     <true/>
     <key>NSSupportsLiveActivitiesFrequentUpdates</key>
     <true/>` : "");
@@ -584,45 +748,7 @@ ${nativeDependencies.join(`
     writeFileSync(join(output, "WatchExtension", "Info.plist"), watchExtensionInfo);
     writeFileSync(join(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }
-  const placeholderHtml = `<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="viewport-fit=cover, width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
-  <title>${xmlEscape(displayName)}</title>
-  <style>
-    * { margin: 0; padding: 0; box-sizing: border-box; }
-    body {
-      font-family: -apple-system, system-ui, sans-serif;
-      background: ${config.backgroundColor};
-      color: white;
-      min-height: 100vh;
-      display: flex;
-      justify-content: center;
-      align-items: center;
-      padding: env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left);
-    }
-    .container { text-align: center; padding: 2rem; }
-    h1 { font-size: 2.5rem; margin-bottom: 1rem; }
-    p { opacity: 0.7; }
-    .ready { color: #4ade80; font-size: 0.9rem; margin-top: 2rem; }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <h1>\u26A1 ${xmlEscape(displayName)}</h1>
-    <p>Built with Craft iOS</p>
-    <p class="ready" id="status">Waiting for Craft bridge...</p>
-  </div>
-  <script>
-    window.addEventListener('craftReady', (e) => {
-      document.getElementById('status').textContent = \`\u2713 Craft bridge ready (platform: \${e.detail.platform})\`;
-      console.log('Craft capabilities:', e.detail.capabilities);
-    });
-  </script>
-</body>
-</html>`;
-  writeFileSync(join(output, "dist", "index.html"), placeholderHtml);
+  writeFileSync(join(output, "dist", "index.html"), renderOfflinePage(config));
   console.log("\u2705 Project initialized");
   console.log("");
   console.log("Next steps:");

package/dist/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;
 /**