@craft-native/ios 0.0.123 → 0.0.125

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

package/dist/index.js

@@ -4,6 +4,129 @@ 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";
+  }
+})();
+function normalizeNativePath(raw) {
+  if (typeof raw !== "string")
+    return null;
+  let path = raw;
+  const cut = path.search(/[?#]/);
+  if (cut >= 0)
+    path = path.slice(0, cut);
+  if (!path.startsWith("/"))
+    return null;
+  path = path.replace(/\/{2,}/g, "/");
+  if (path.length > 1 && path.endsWith("/"))
+    path = path.slice(0, -1);
+  return path;
+}
+function routeSegments(path) {
+  return path === "/" ? [] : path.slice(1).split("/");
+}
+function matchNativePath(nativeScreens, raw) {
+  const path = normalizeNativePath(raw);
+  if (path === null)
+    return null;
+  const routes = Object.entries(nativeScreens ?? {}).map(([pattern, screen]) => ({ pattern: normalizeNativePath(pattern), screen })).filter((route) => route.pattern !== null && !!route.screen).map((route) => ({ ...route, segments: routeSegments(route.pattern) }));
+  const wild = (segments) => segments.at(-1) === "*" ? 1 : 0;
+  const fixed = (segments) => segments.filter((s) => s !== "*" && !s.startsWith(":")).length;
+  routes.sort((a, b) => wild(a.segments) - wild(b.segments) || fixed(b.segments) - fixed(a.segments) || b.segments.length - a.segments.length || (a.pattern < b.pattern ? -1 : a.pattern > b.pattern ? 1 : 0));
+  const decode = (value) => {
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  };
+  const parts = routeSegments(path);
+  for (const route of routes) {
+    const params = {};
+    let matched = true;
+    for (let i = 0;i < route.segments.length; i++) {
+      const segment = route.segments[i];
+      if (segment === "*") {
+        params["*"] = parts.slice(i).join("/");
+        break;
+      }
+      if (i >= parts.length) {
+        matched = false;
+        break;
+      }
+      if (segment.startsWith(":")) {
+        if (!parts[i]) {
+          matched = false;
+          break;
+        }
+        params[segment.slice(1)] = decode(parts[i]);
+      } else if (segment !== parts[i]) {
+        matched = false;
+        break;
+      }
+    }
+    if (!matched)
+      continue;
+    if (route.segments.at(-1) !== "*" && route.segments.length !== parts.length)
+      continue;
+    const query = raw.indexOf("?");
+    if (query >= 0) {
+      for (const item of raw.slice(query + 1).split("#")[0].split("&")) {
+        if (!item)
+          continue;
+        const [rawKey = "", ...rest] = item.split("=");
+        const key = decode(rawKey);
+        if (!key || key in params)
+          continue;
+        params[key] = decode(rest.join("=").replace(/\+/g, " "));
+      }
+    }
+    return { path, screen: route.screen, params };
+  }
+  return null;
+}
+function isHybrid(config) {
+  return (config.renderer ?? "web") === "web" && Object.keys(config.nativeScreens ?? {}).length > 0;
+}
+function hybridConfigProblems(config) {
+  const problems = [];
+  const screens = Object.entries(config.nativeScreens ?? {});
+  if (screens.length && config.renderer === "native")
+    problems.push('nativeScreens mixes native screens into a web app; it needs renderer: "web" (renderer: "native" is all native already).');
+  for (const [pattern, screen] of screens) {
+    if (normalizeNativePath(pattern) !== pattern || /[?#]/.test(pattern))
+      problems.push(`nativeScreens path "${pattern}" must be an absolute path with no query, hash or trailing slash.`);
+    if (routeSegments(normalizeNativePath(pattern) ?? "/").slice(0, -1).includes("*"))
+      problems.push(`nativeScreens path "${pattern}" may only end in *.`);
+    if (typeof screen !== "string" || !/^[A-Za-z_$][\w$-]*$/.test(screen))
+      problems.push(`nativeScreens screen "${String(screen)}" for "${pattern}" must be a screen name from the native bundle.`);
+  }
+  const ids = new Set;
+  for (const tab of config.tabs ?? []) {
+    if (!tab || typeof tab.id !== "string" || !tab.id || typeof tab.title !== "string" || !tab.title)
+      problems.push("Each tab needs an id (its root path) and a title.");
+    else if (ids.has(tab.id))
+      problems.push(`Tab "${tab.id}" is listed twice.`);
+    else
+      ids.add(tab.id);
+  }
+  for (const [key, target] of Object.entries(config.shareStorage ?? {})) {
+    if (!key || typeof target !== "string" || !target)
+      problems.push(`shareStorage "${key}" needs the Keychain key native screens read it under.`);
+  }
+  return problems;
+}
+function installNativeBundle(source, output) {
+  if (!existsSync(source))
+    throw new Error(`Native bundle not found: ${source}`);
+  const destination = join(output, "dist", "native-screen.js");
+  mkdirSync(dirname(destination), { recursive: true });
+  if (resolve(source) !== resolve(destination))
+    cpSync(source, destination);
+}
 var DEFAULT_CONFIG = {
   renderer: "web",
   version: "1.0.0",
@@ -171,6 +294,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)
@@ -184,12 +309,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) {
@@ -414,6 +557,102 @@ function renderLaunchScreen(config) {
   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);
   if (!existsSync(sourcePath))
@@ -520,16 +759,24 @@ async function init(options) {
   }
   if (config.enableBackgroundLocation)
     config.enableGeolocation = true;
+  const problems = hybridConfigProblems(config);
+  if (problems.length)
+    throw new Error(problems.join(`
+`));
+  if (Object.keys(config.shareStorage ?? {}).length)
+    config.enableSecureStorage = 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"));
+  cpSync(join(TEMPLATES_DIR, "CraftHybrid.swift"), join(output, "Sources", "CraftHybrid.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(/\{\{LAUNCH_SCREEN\}\}/g, renderLaunchScreen(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/>` : "");
@@ -619,51 +866,19 @@ ${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));
+  if (isHybrid(config)) {
+    if (config.nativeBundle)
+      installNativeBundle(config.nativeBundle, output);
+    else
+      console.warn("   \u26A0 nativeScreens is set without nativeBundle: every path opens in the web view until `craft ios build --native-bundle` supplies one.");
+  }
   console.log("\u2705 Project initialized");
   console.log("");
   console.log("Next steps:");
   console.log(`  1. cd ${output}`);
   if (config.renderer === "native") {
-    console.log("  2. Compile your screen: stx-native compile Screen.stx --format bundle --output screen.js");
+    console.log("  2. Compile your screen: stx native compile Screen.stx --format bundle --output screen.js");
     console.log("  3. Run: craft ios build --native-bundle screen.js");
   } else {
     console.log("  2. Add your web content to dist/index.html");
@@ -694,11 +909,15 @@ async function build(options) {
         cpSync(nativeBundlePath, destination);
     }
     if (!existsSync(join(output, "dist", "native-screen.js"))) {
-      throw new Error("Native iOS mode needs dist/native-screen.js. Compile a .stx screen with stx-native first.");
+      throw new Error("Native iOS mode needs dist/native-screen.js. Compile a .stx screen with `stx native compile` first.");
     }
-  } else if (nativeBundlePath) {
-    throw new Error('--native-bundle requires renderer: "native" in craft.config.json.');
+  } else if (nativeBundlePath && !isHybrid(config)) {
+    throw new Error('--native-bundle requires renderer: "native", or nativeScreens, in craft.config.json.');
   }
+  const problems = hybridConfigProblems(config);
+  if (problems.length)
+    throw new Error(problems.join(`
+`));
   if (devServer) {
     config.devServerURL = devServer;
     const origin = new URL(devServer).origin;
@@ -710,6 +929,15 @@ async function build(options) {
     syncWebAssets(htmlPath, output);
     console.log(`   Synced: ${htmlPath} \u2192 dist/`);
   }
+  if (isHybrid(config)) {
+    const bundle = nativeBundlePath ?? config.nativeBundle;
+    if (bundle) {
+      installNativeBundle(bundle, output);
+      console.log(`   Native screens: ${bundle} \u2192 dist/native-screen.js`);
+    } else if (!existsSync(join(output, "dist", "native-screen.js"))) {
+      console.warn("   \u26A0 nativeScreens is set but there is no native bundle: every path opens in the web view.");
+    }
+  }
   await refreshRuntime(output, options.runtimeDir);
   if (!generateProject)
     return;
@@ -844,20 +1072,29 @@ export {
   renderRuntimeSettings,
   renderPrivacyManifest,
   renderOrientations,
+  renderOfflinePage,
   renderLaunchScreen,
   renderEntitlements,
   renderDeviceFamilies,
+  renderBackgroundTaskIdentifiers,
   renderBackgroundModes,
   renderAppearance,
   renderAppBoundDomains,
+  readableTextOn,
   productName,
   pngHasAlpha,
   pickSimulator,
   orderSimulators,
   open,
+  normalizeNativePath,
+  matchNativePath,
+  isHybrid,
   installRuntime,
   init,
+  hybridConfigProblems,
   build,
   bootSimulator,
+  backgroundRefreshIdentifier,
+  associatedDomainEntries,
   LAUNCH_LOGO
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-native/ios",
-  "version": "0.0.123",
+  "version": "0.0.125",
   "homepage": "https://github.com/craft-native/craft/tree/main/packages/ios#readme",
   "repository": {
     "type": "git",