craft-native 0.0.278 → 0.0.290

package/dist/index.cjs

@@ -374,7 +374,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.278";
+var version = "0.0.290";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -611,6 +611,8 @@ async function packageMacOS(config, outDir) {
   const { name, version, bundleId = `com.myapp.${name.toLowerCase()}` } = config;
   const opts = config.macos || {};
   const hardenedRuntime = !opts.appStore;
+  if (opts.appStore && (!opts.entitlements || !opts.provisioningProfile))
+    return [{ success: false, platform: "macos", format: "app", error: "App Store packaging requires macos.entitlements and macos.provisioningProfile" }];
   const appBundlePath = import_path.join(outDir, `${name}.app`);
   const appBundle = opts.appBundlePath ? copyMacOSAppBundle(opts.appBundlePath, appBundlePath) : createMacOSAppBundle({
     name,
@@ -636,25 +638,42 @@ async function packageMacOS(config, outDir) {
     });
     return results;
   }
-  if (opts.signIdentity) {
-    const signed = await runTool("codesign", codesignArguments({
-      path: appBundlePath,
-      identity: opts.signIdentity,
-      entitlements: opts.entitlements,
-      hardenedRuntime
-    }));
-    if (!signed.success) {
-      results.push({ success: false, platform: "macos", format: "app", error: signed.error });
-      return results;
+  try {
+    const contents = import_path.join(appBundlePath, "Contents");
+    if (opts.provisioningProfile) {
+      const profile = import_path.join(contents, "embedded.provisionprofile");
+      import_fs.copyFileSync(opts.provisioningProfile, profile);
+      import_fs.chmodSync(profile, 420);
+    }
+    if (opts.privacyManifest)
+      import_fs.copyFileSync(opts.privacyManifest, import_path.join(contents, "Resources", "PrivacyInfo.xcprivacy"));
+    if (opts.appBundlePath) {
+      const metadata = {
+        CFBundleVersion: opts.buildNumber,
+        LSApplicationCategoryType: opts.category,
+        LSMinimumSystemVersion: opts.minimumSystemVersion,
+        LSUIElement: opts.menuBarOnly
+      };
+      if (config.iconPath) {
+        const icon = import_path.basename(config.iconPath);
+        import_fs.copyFileSync(config.iconPath, import_path.join(contents, "Resources", icon));
+        metadata.CFBundleIconFile = icon;
+      }
+      for (const [key, value] of Object.entries(metadata)) {
+        if (value === undefined)
+          continue;
+        const result = await runTool("plutil", ["-replace", key, typeof value === "boolean" ? "-bool" : "-string", String(value), import_path.join(contents, "Info.plist")]);
+        if (!result.success)
+          throw new Error(result.error);
+      }
     }
-  } else if (opts.appStore) {
-    results.push({
-      success: false,
-      platform: "macos",
-      format: "pkg",
-      error: 'App Store packaging requires macos.signIdentity (a "3rd Party Mac Developer Application" identity)'
-    });
-    return results;
+    if (opts.signIdentity) {
+      await signMacOSAppBundle(appBundlePath, bundleId, opts, hardenedRuntime);
+    } else if (opts.appStore) {
+      throw new Error('App Store packaging requires macos.signIdentity (a "3rd Party Mac Developer Application" identity)');
+    }
+  } catch (error) {
+    return [{ success: false, platform: "macos", format: "app", error: error.message }];
   }
   results.push({ success: true, platform: "macos", format: "app", outputPath: appBundlePath });
   if (opts.dmg !== false) {
@@ -678,7 +697,8 @@ async function packageMacOS(config, outDir) {
       identifier: bundleId,
       version,
       appStore: opts.appStore === true,
-      installerIdentity: opts.installerIdentity
+      installerIdentity: opts.installerIdentity,
+      signingKeychain: opts.signingKeychain
     });
     results.push({
       success: pkgResult.success,
@@ -919,6 +939,59 @@ ${body}
 </dict>
 </plist>`;
 }
+async function signMacOSAppBundle(app, bundleId, opts, hardenedRuntime) {
+  const scratch = createTempDir("craft-sign-");
+  try {
+    let helperEntitlements = opts.helperEntitlements;
+    if (opts.appStore && !helperEntitlements) {
+      helperEntitlements = import_path.join(scratch, "inherit.plist");
+      import_fs.writeFileSync(helperEntitlements, '<?xml version="1.0"?><plist version="1.0"><dict><key>com.apple.security.app-sandbox</key><true/><key>com.apple.security.inherit</key><true/></dict></plist>');
+    }
+    const extracted = await runTool("plutil", ["-extract", "CFBundleExecutable", "raw", "-o", "-", import_path.join(app, "Contents", "Info.plist")]);
+    if (!extracted.success)
+      throw new Error(extracted.error);
+    const main = import_path.join(app, "Contents", "MacOS", extracted.stdout.trim());
+    const sign = async (path, entitlements, identifier) => {
+      const signed = await runTool("codesign", codesignArguments({ path, identity: opts.signIdentity, entitlements, hardenedRuntime, identifier, keychain: opts.signingKeychain, deep: false }));
+      if (!signed.success)
+        throw new Error(signed.error);
+    };
+    const walk = async (directory) => {
+      for (const entry of import_fs.readdirSync(directory)) {
+        const path = import_path.join(directory, entry);
+        const stat = import_fs.lstatSync(path);
+        if (stat.isSymbolicLink())
+          continue;
+        if (stat.isDirectory()) {
+          await walk(path);
+          if (/\.(?:app|framework|xpc|appex|bundle)$/.test(entry))
+            await sign(path, /\.(?:app|xpc|appex)$/.test(entry) ? helperEntitlements : undefined);
+        } else if (path !== main && stat.isFile() && isMachO(path)) {
+          const executable = (stat.mode & 73) !== 0 && !/\.(?:dylib|so)$/.test(entry);
+          await sign(path, executable ? helperEntitlements : undefined, `${bundleId}.${entry}`);
+        }
+      }
+    };
+    await walk(import_path.join(app, "Contents"));
+    await sign(app, opts.entitlements);
+    const verified = await runTool("codesign", ["--verify", "--deep", "--strict", app]);
+    if (!verified.success)
+      throw new Error(verified.error);
+  } finally {
+    removeTempDir(scratch);
+  }
+}
+function isMachO(path) {
+  const fd = import_fs.openSync(path, "r");
+  try {
+    const magic = Buffer.alloc(4);
+    if (import_fs.readSync(fd, magic, 0, 4, 0) !== 4)
+      return false;
+    return [4277009102, 3472551422, 4277009103, 3489328638, 3405691582, 3199925962, 3405691583, 3216703178].includes(magic.readUInt32BE());
+  } finally {
+    import_fs.closeSync(fd);
+  }
+}
 function codesignArguments(opts) {
   return [
     "--force",
@@ -927,7 +1000,9 @@ function codesignArguments(opts) {
     ...opts.identity === "-" ? [] : ["--timestamp"],
     ...opts.hardenedRuntime ? ["--options", "runtime"] : [],
     ...opts.entitlements ? ["--entitlements", opts.entitlements] : [],
-    "--deep",
+    ...opts.identifier ? ["--identifier", opts.identifier] : [],
+    ...opts.keychain ? ["--keychain", opts.keychain] : [],
+    ...opts.deep === false ? [] : ["--deep"],
     opts.path
   ];
 }
@@ -938,6 +1013,7 @@ function productbuildArguments(opts) {
     "/Applications",
     "--sign",
     opts.identity,
+    ...opts.keychain ? ["--keychain", opts.keychain] : [],
     opts.outputPath
   ];
 }
@@ -1057,7 +1133,7 @@ function runTool(tool, args) {
     });
     proc.on("close", (code) => {
       if (code === 0)
-        resolve({ success: true });
+        resolve({ success: true, stdout });
       else
         resolve({ success: false, error: formatPackagingCommandError(tool, code, stdout, stderr) });
     });
@@ -1132,7 +1208,8 @@ async function createPKG(opts) {
     const built = await runTool("productbuild", productbuildArguments({
       appBundlePath: opts.appBundlePath,
       outputPath: opts.outputPath,
-      identity: opts.installerIdentity
+      identity: opts.installerIdentity,
+      keychain: opts.signingKeychain
     }));
     return built.success ? { success: true, outputPath: opts.outputPath } : { success: false, error: built.error };
   }

package/dist/index.d.cts

@@ -85,4 +85,4 @@ export declare function show(html: string, options?: WindowOptions): Promise<voi
  * Quick helper to load a URL
  */
 export declare function loadURL(url: string, options?: WindowOptions): Promise<void>;
-export type { WindowOptions, CraftSidebarAPI, CraftNativeUIAPI, CraftContextMenuItem, CraftContextMenuResult, AppConfig, CraftTrayAPI, CraftWindowAPI, CraftAppAPI, CraftBridgeAPI, Permission, HapticType, CraftHapticsAPI, CameraOptions, PhotoPickerOptions, CraftMobileAPI, CraftFileSystemAPI, CraftFsWatchEvent, CraftFsWatchHandle, CraftDatabaseAPI, CraftHttpAPI, CraftCryptoAPI, CraftCapabilities, CapabilityNamespace, CapabilityNamespaceStatus, CapabilityAction, CraftPreferencesAPI, CraftPreferencesInfo, CraftSettingsAPI, PreferenceValue, CraftEventType, CraftEventMap, CraftEventHandler, CraftEventEmitter, IOSConfig, AndroidConfig, MacOSConfig, WindowsConfig, LinuxConfig, CraftAppConfig, } from './types.js';
+export type { WindowOptions, CraftSidebarAPI, CraftNativeUIAPI, CraftContextMenuItem, CraftContextMenuResult, AppConfig, CraftTrayAPI, CraftWindowAPI, CraftAppAPI, CraftBridgeAPI, CraftTimersAPI, Permission, HapticType, CraftHapticsAPI, CameraOptions, PhotoPickerOptions, CraftMobileAPI, CraftFileSystemAPI, CraftFsWatchEvent, CraftFsWatchHandle, CraftDatabaseAPI, CraftHttpAPI, CraftCryptoAPI, CraftCapabilities, CapabilityNamespace, CapabilityNamespaceStatus, CapabilityAction, CraftPreferencesAPI, CraftPreferencesInfo, CraftSettingsAPI, PreferenceValue, CraftEventType, CraftEventMap, CraftEventHandler, CraftEventEmitter, IOSConfig, AndroidConfig, MacOSConfig, WindowsConfig, LinuxConfig, CraftAppConfig, } from './types.js';

package/dist/index.d.ts

@@ -85,4 +85,4 @@ export declare function show(html: string, options?: WindowOptions): Promise<voi
  * Quick helper to load a URL
  */
 export declare function loadURL(url: string, options?: WindowOptions): Promise<void>;
-export type { WindowOptions, CraftSidebarAPI, CraftNativeUIAPI, CraftContextMenuItem, CraftContextMenuResult, AppConfig, CraftTrayAPI, CraftWindowAPI, CraftAppAPI, CraftBridgeAPI, Permission, HapticType, CraftHapticsAPI, CameraOptions, PhotoPickerOptions, CraftMobileAPI, CraftFileSystemAPI, CraftFsWatchEvent, CraftFsWatchHandle, CraftDatabaseAPI, CraftHttpAPI, CraftCryptoAPI, CraftCapabilities, CapabilityNamespace, CapabilityNamespaceStatus, CapabilityAction, CraftPreferencesAPI, CraftPreferencesInfo, CraftSettingsAPI, PreferenceValue, CraftEventType, CraftEventMap, CraftEventHandler, CraftEventEmitter, IOSConfig, AndroidConfig, MacOSConfig, WindowsConfig, LinuxConfig, CraftAppConfig, } from './types.js';
+export type { WindowOptions, CraftSidebarAPI, CraftNativeUIAPI, CraftContextMenuItem, CraftContextMenuResult, AppConfig, CraftTrayAPI, CraftWindowAPI, CraftAppAPI, CraftBridgeAPI, CraftTimersAPI, Permission, HapticType, CraftHapticsAPI, CameraOptions, PhotoPickerOptions, CraftMobileAPI, CraftFileSystemAPI, CraftFsWatchEvent, CraftFsWatchHandle, CraftDatabaseAPI, CraftHttpAPI, CraftCryptoAPI, CraftCapabilities, CapabilityNamespace, CapabilityNamespaceStatus, CapabilityAction, CraftPreferencesAPI, CraftPreferencesInfo, CraftSettingsAPI, PreferenceValue, CraftEventType, CraftEventMap, CraftEventHandler, CraftEventEmitter, IOSConfig, AndroidConfig, MacOSConfig, WindowsConfig, LinuxConfig, CraftAppConfig, } from './types.js';

package/dist/index.js

@@ -117,7 +117,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.278";
+var version = "0.0.290";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -241,12 +241,15 @@ import { spawn } from "child_process";
 import { createHash } from "crypto";
 import {
   chmodSync,
+  closeSync,
   copyFileSync,
   cpSync,
   existsSync as existsSync3,
   lstatSync,
   mkdirSync,
+  openSync,
   readFileSync,
+  readSync,
   readdirSync as readdirSync2,
   rmSync as rmSync2,
   writeFileSync as writeFileSync2
@@ -365,6 +368,8 @@ async function packageMacOS(config, outDir) {
   const { name, version, bundleId = `com.myapp.${name.toLowerCase()}` } = config;
   const opts = config.macos || {};
   const hardenedRuntime = !opts.appStore;
+  if (opts.appStore && (!opts.entitlements || !opts.provisioningProfile))
+    return [{ success: false, platform: "macos", format: "app", error: "App Store packaging requires macos.entitlements and macos.provisioningProfile" }];
   const appBundlePath = join2(outDir, `${name}.app`);
   const appBundle = opts.appBundlePath ? copyMacOSAppBundle(opts.appBundlePath, appBundlePath) : createMacOSAppBundle({
     name,
@@ -390,25 +395,42 @@ async function packageMacOS(config, outDir) {
     });
     return results;
   }
-  if (opts.signIdentity) {
-    const signed = await runTool("codesign", codesignArguments({
-      path: appBundlePath,
-      identity: opts.signIdentity,
-      entitlements: opts.entitlements,
-      hardenedRuntime
-    }));
-    if (!signed.success) {
-      results.push({ success: false, platform: "macos", format: "app", error: signed.error });
-      return results;
+  try {
+    const contents = join2(appBundlePath, "Contents");
+    if (opts.provisioningProfile) {
+      const profile = join2(contents, "embedded.provisionprofile");
+      copyFileSync(opts.provisioningProfile, profile);
+      chmodSync(profile, 420);
+    }
+    if (opts.privacyManifest)
+      copyFileSync(opts.privacyManifest, join2(contents, "Resources", "PrivacyInfo.xcprivacy"));
+    if (opts.appBundlePath) {
+      const metadata = {
+        CFBundleVersion: opts.buildNumber,
+        LSApplicationCategoryType: opts.category,
+        LSMinimumSystemVersion: opts.minimumSystemVersion,
+        LSUIElement: opts.menuBarOnly
+      };
+      if (config.iconPath) {
+        const icon = basename(config.iconPath);
+        copyFileSync(config.iconPath, join2(contents, "Resources", icon));
+        metadata.CFBundleIconFile = icon;
+      }
+      for (const [key, value] of Object.entries(metadata)) {
+        if (value === undefined)
+          continue;
+        const result = await runTool("plutil", ["-replace", key, typeof value === "boolean" ? "-bool" : "-string", String(value), join2(contents, "Info.plist")]);
+        if (!result.success)
+          throw new Error(result.error);
+      }
     }
-  } else if (opts.appStore) {
-    results.push({
-      success: false,
-      platform: "macos",
-      format: "pkg",
-      error: 'App Store packaging requires macos.signIdentity (a "3rd Party Mac Developer Application" identity)'
-    });
-    return results;
+    if (opts.signIdentity) {
+      await signMacOSAppBundle(appBundlePath, bundleId, opts, hardenedRuntime);
+    } else if (opts.appStore) {
+      throw new Error('App Store packaging requires macos.signIdentity (a "3rd Party Mac Developer Application" identity)');
+    }
+  } catch (error) {
+    return [{ success: false, platform: "macos", format: "app", error: error.message }];
   }
   results.push({ success: true, platform: "macos", format: "app", outputPath: appBundlePath });
   if (opts.dmg !== false) {
@@ -432,7 +454,8 @@ async function packageMacOS(config, outDir) {
       identifier: bundleId,
       version,
       appStore: opts.appStore === true,
-      installerIdentity: opts.installerIdentity
+      installerIdentity: opts.installerIdentity,
+      signingKeychain: opts.signingKeychain
     });
     results.push({
       success: pkgResult.success,
@@ -673,6 +696,59 @@ ${body}
 </dict>
 </plist>`;
 }
+async function signMacOSAppBundle(app, bundleId, opts, hardenedRuntime) {
+  const scratch = createTempDir("craft-sign-");
+  try {
+    let helperEntitlements = opts.helperEntitlements;
+    if (opts.appStore && !helperEntitlements) {
+      helperEntitlements = join2(scratch, "inherit.plist");
+      writeFileSync2(helperEntitlements, '<?xml version="1.0"?><plist version="1.0"><dict><key>com.apple.security.app-sandbox</key><true/><key>com.apple.security.inherit</key><true/></dict></plist>');
+    }
+    const extracted = await runTool("plutil", ["-extract", "CFBundleExecutable", "raw", "-o", "-", join2(app, "Contents", "Info.plist")]);
+    if (!extracted.success)
+      throw new Error(extracted.error);
+    const main = join2(app, "Contents", "MacOS", extracted.stdout.trim());
+    const sign = async (path, entitlements, identifier) => {
+      const signed = await runTool("codesign", codesignArguments({ path, identity: opts.signIdentity, entitlements, hardenedRuntime, identifier, keychain: opts.signingKeychain, deep: false }));
+      if (!signed.success)
+        throw new Error(signed.error);
+    };
+    const walk = async (directory) => {
+      for (const entry of readdirSync2(directory)) {
+        const path = join2(directory, entry);
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+          continue;
+        if (stat.isDirectory()) {
+          await walk(path);
+          if (/\.(?:app|framework|xpc|appex|bundle)$/.test(entry))
+            await sign(path, /\.(?:app|xpc|appex)$/.test(entry) ? helperEntitlements : undefined);
+        } else if (path !== main && stat.isFile() && isMachO(path)) {
+          const executable = (stat.mode & 73) !== 0 && !/\.(?:dylib|so)$/.test(entry);
+          await sign(path, executable ? helperEntitlements : undefined, `${bundleId}.${entry}`);
+        }
+      }
+    };
+    await walk(join2(app, "Contents"));
+    await sign(app, opts.entitlements);
+    const verified = await runTool("codesign", ["--verify", "--deep", "--strict", app]);
+    if (!verified.success)
+      throw new Error(verified.error);
+  } finally {
+    removeTempDir(scratch);
+  }
+}
+function isMachO(path) {
+  const fd = openSync(path, "r");
+  try {
+    const magic = Buffer.alloc(4);
+    if (readSync(fd, magic, 0, 4, 0) !== 4)
+      return false;
+    return [4277009102, 3472551422, 4277009103, 3489328638, 3405691582, 3199925962, 3405691583, 3216703178].includes(magic.readUInt32BE());
+  } finally {
+    closeSync(fd);
+  }
+}
 function codesignArguments(opts) {
   return [
     "--force",
@@ -681,7 +757,9 @@ function codesignArguments(opts) {
     ...opts.identity === "-" ? [] : ["--timestamp"],
     ...opts.hardenedRuntime ? ["--options", "runtime"] : [],
     ...opts.entitlements ? ["--entitlements", opts.entitlements] : [],
-    "--deep",
+    ...opts.identifier ? ["--identifier", opts.identifier] : [],
+    ...opts.keychain ? ["--keychain", opts.keychain] : [],
+    ...opts.deep === false ? [] : ["--deep"],
     opts.path
   ];
 }
@@ -692,6 +770,7 @@ function productbuildArguments(opts) {
     "/Applications",
     "--sign",
     opts.identity,
+    ...opts.keychain ? ["--keychain", opts.keychain] : [],
     opts.outputPath
   ];
 }
@@ -811,7 +890,7 @@ function runTool(tool, args) {
     });
     proc.on("close", (code) => {
       if (code === 0)
-        resolve({ success: true });
+        resolve({ success: true, stdout });
       else
         resolve({ success: false, error: formatPackagingCommandError(tool, code, stdout, stderr) });
     });
@@ -886,7 +965,8 @@ async function createPKG(opts) {
     const built = await runTool("productbuild", productbuildArguments({
       appBundlePath: opts.appBundlePath,
       outputPath: opts.outputPath,
-      identity: opts.installerIdentity
+      identity: opts.installerIdentity,
+      keychain: opts.signingKeychain
     }));
     return built.success ? { success: true, outputPath: opts.outputPath } : { success: false, error: built.error };
   }

package/dist/ios/templates/CraftApp.swift

@@ -903,6 +903,9 @@ final class CraftChrome: ObservableObject {
     func tap(_ tab: Tab) {
         let reselect = tab.id == selected
         if !reselect {
+            // A tab's screen not made yet is made first, so the pill moves on
+            // a free main thread rather than stalling behind its mount.
+            CraftHybrid.shared.mountTabBeforeSelecting(tab.id)
             withAnimation(Self.motion(.spring(response: 0.32, dampingFraction: 0.86))) { selected = tab.id }
         }
         // A hybrid app shows the tab's own stack first; the page hears the
@@ -1162,11 +1165,7 @@ struct CraftTabBarView: View {
                     VStack(spacing: 3) {
                         ZStack(alignment: .topTrailing) {
                             if let image = tab.image, let url = URL(string: image) {
-                                AsyncImage(url: url) { image in
-                                    image.resizable().scaledToFill()
-                                } placeholder: {
-                                    Image(systemName: symbol(tab.symbol, selected: isSelected))
-                                }
+                                CraftTabPicture(url: url, placeholder: symbol(tab.symbol, selected: isSelected))
                                 .frame(width: iconSize + 4, height: iconSize + 4)
                                 .clipShape(Circle())
                                 .frame(height: iconSize + 6)
@@ -1258,6 +1257,46 @@ struct CraftTabBarView: View {
     }
 }
 
+/// A tab's picture (HQ's Me: the account's photo). It is kept once loaded,
+/// so a tab item drawn again (its screen mounting, the bar coming back) shows
+/// it at once: AsyncImage keeps nothing, so the photo went back to the
+/// person symbol, loaded again and arrived inside whatever animation was
+/// running, sliding in from the side on the first visit to Me.
+private struct CraftTabPicture: View {
+    let url: URL
+    let placeholder: String
+    @State private var image: UIImage?
+
+    private static let cache: NSCache<NSURL, UIImage> = {
+        let cache = NSCache<NSURL, UIImage>()
+        cache.countLimit = 16
+        return cache
+    }()
+
+    var body: some View {
+        Group {
+            if let shown = image ?? Self.cache.object(forKey: url as NSURL) {
+                Image(uiImage: shown).resizable().scaledToFill()
+            } else {
+                Image(systemName: placeholder)
+            }
+        }
+        // A picture arriving never animates, whatever transaction it lands in.
+        .transaction { $0.animation = nil }
+        .task(id: url) {
+            if let cached = Self.cache.object(forKey: url as NSURL) {
+                image = cached
+                return
+            }
+            guard let (data, response) = try? await URLSession.shared.data(from: url),
+                  (response as? HTTPURLResponse).map({ (200..<300).contains($0.statusCode) }) ?? true,
+                  let loaded = UIImage(data: data) else { return }
+            Self.cache.setObject(loaded, forKey: url as NSURL)
+            image = loaded
+        }
+    }
+}
+
 private struct CraftTabSelectionShape: Shape {
     let cornerRadius: CGFloat?
 

package/dist/ios/templates/CraftHybrid.swift

@@ -880,6 +880,13 @@ final class CraftHybrid: NSObject {
         return controller.tabTapped(id, reselect: reselect)
     }
 
+    /// A native tab not prepared yet mounts its screen now, hidden, before
+    /// the bar's selection moves (CraftChrome.tap).
+    func mountTabBeforeSelecting(_ id: String) {
+        guard isEnabled else { return }
+        controller?.mountTabBeforeSelecting(id)
+    }
+
     /// The page chose a tab itself (its `selectTab`, or a tab link).
     func pageSelectedTab(_ id: String) {
         guard isEnabled else { return }
@@ -1731,6 +1738,20 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
 
     private var preparation: Timer?
 
+    /// A native tab tapped before the shell prepared it (HQ's Me, prepared
+    /// last, tapped right after launch) mounts its screen hidden first. Mounted
+    /// in the tap's own turn after the selection began, it held the main
+    /// thread while SwiftUI's spring should have moved the pill, which then
+    /// stalled and jumped in from the side.
+    func mountTabBeforeSelecting(_ id: String) {
+        guard stacks[id] == nil, id != currentTab, activeTabSwipeTarget == nil,
+              hybrid.tabIds.contains(id), hybrid.routes.match(id) != nil, view.window != nil else { return }
+        let nav = makeStack(tab: id, rootPath: id, hidden: true)
+        nav.view.layoutIfNeeded()
+        Self.drawContents(of: nav.view.layer)
+        (visibleStack?.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(true)
+    }
+
     /// When the shell last moved between screens: a tab, a push or a pop.
     private var lastNavigation: CFTimeInterval = 0