craft-native 0.0.304 → 0.0.319

package/dist/android/src/index.js

@@ -286,12 +286,12 @@ async function createAndroidEmulator(options) {
     if (options.acceptLicenses)
       await run([options.sdkmanager, `--sdk_root=${sdk}`, "--licenses"], `y
 `.repeat(100));
-    await run([options.sdkmanager, `--sdk_root=${sdk}`, "platform-tools", "emulator"], options.acceptLicenses ? `y
+    await run([options.sdkmanager, `--sdk_root=${sdk}`, "--verbose", "platform-tools", "emulator"], options.acceptLicenses ? `y
 `.repeat(100) : undefined);
     const acceleration = await run([executable, "-accel-check"], undefined, 30000, true);
     if (options.acceleration === "hardware" && acceleration.code !== 0)
       throw new Error(`Android hardware acceleration is unavailable; inspect ${artifacts}`);
-    await run([options.sdkmanager, `--sdk_root=${sdk}`, options.image], options.acceptLicenses ? `y
+    await run([options.sdkmanager, `--sdk_root=${sdk}`, "--verbose", options.image], options.acceptLicenses ? `y
 `.repeat(100) : undefined);
     const devices = (await run([adb, "devices"], undefined, 1e4)).stdout;
     if (devices.split(`

package/dist/android/templates/CraftNativeShell.kt.template

@@ -806,6 +806,10 @@ internal class CraftNativeChrome(
     private val density = resources.displayMetrics.density
     private var screenBackgroundColor: Int? = null
     private var selectedTab = 0
+    private var tabBarHiddenByScreen = false
+    private var visiblePath: String? = null
+    private val accessorySelected: Boolean
+        get() = accessorySpec?.optString("path")?.let { path -> visiblePath == path || visiblePath?.startsWith(path + "/") == true } == true
     private var swipeTracking = false
     private var swipeIntercepted = false
     private var horizontalScrollDeferred = false
@@ -969,7 +973,8 @@ internal class CraftNativeChrome(
     }
 
     /** Draws `options` (a screen's `setOptions`) for a screen `depth` deep in its stack. */
-    fun apply(options: JSONObject, depth: Int, fallbackTitle: String?) {
+    fun apply(options: JSONObject, depth: Int, fallbackTitle: String?, path: String? = null) {
+        visiblePath = path
         screenBackgroundColor = options.opt("backgroundColor")
             ?.takeUnless { it == JSONObject.NULL }
             ?.let { craftNativeOptionalString(it) }
@@ -1004,7 +1009,19 @@ internal class CraftNativeChrome(
             renderedButtonSpecs = buttonSpecs
         }
         val tabBarHidden = options.optBoolean("tabBarHidden", false) || depth > 0 && options.optBoolean("tabBarHiddenWhenPushed", false)
-        tabRow.visibility = if (tabs.isEmpty() || tabBarHidden) View.GONE else View.VISIBLE
+        if (tabBarHiddenByScreen != tabBarHidden) {
+            tabBarHiddenByScreen = tabBarHidden
+            tabRow.animate().cancel()
+            val duration = if (android.animation.ValueAnimator.areAnimatorsEnabled()) 240L else 0L
+            if (tabBarHidden) {
+                tabRow.animate().translationY(dp(80).toFloat()).alpha(0f).setDuration(duration).withEndAction {
+                    if (tabBarHiddenByScreen) tabRow.visibility = View.GONE
+                }.start()
+            } else if (tabs.isNotEmpty()) {
+                tabRow.visibility = View.VISIBLE
+                tabRow.animate().translationY(0f).alpha(1f).setDuration(duration).start()
+            }
+        } else if (tabs.isEmpty()) tabRow.visibility = View.GONE
         accessorySpec = options.optJSONObject("tabAccessory")?.takeIf {
             val path = it.optString("path")
             path.startsWith("/") && !path.startsWith("//") && it.has("title")
@@ -1091,7 +1108,7 @@ internal class CraftNativeChrome(
     /** Selection belongs to the native tab stack, including retained pushed screens. */
     internal fun tabIconAppearance(index: Int, motionAllowed: Boolean): CraftTabIconAppearance {
         val tab = tabs[index]
-        val selected = index == selectedTab
+        val selected = index == selectedTab && !accessorySelected
         return CraftTabIconAppearance(
             if (selected) selectedSymbols[tab.id] ?: tabSymbols[tab.id] ?: tab.symbol else tabSymbols[tab.id] ?: tab.symbol,
             if (selected) selectedIconTints[tab.id] ?: tabIconTints[tab.id] else tabIconTints[tab.id],
@@ -1114,12 +1131,13 @@ internal class CraftNativeChrome(
         backButton.imageTintList = ColorStateList.valueOf(accent)
         val surface = if (dark) Color.parseColor("#1C1C1E") else Color.parseColor("#F9F9F9")
         tabBar.background = GradientDrawable().apply { setColor(surface); cornerRadius = dp(32).toFloat() }
-        accessory.background = GradientDrawable().apply { setColor(surface); cornerRadius = dp(32).toFloat() }
-        accessorySpec?.let { accessoryIcon.setImageDrawable(CraftNativeIcons.drawable(context, null, it.optString("symbol"), text)) }
+        accessory.isSelected = accessorySelected
+        accessory.background = GradientDrawable().apply { setColor(if (accessorySelected) Color.argb(36, Color.red(accent), Color.green(accent), Color.blue(accent)) else surface); cornerRadius = dp(32).toFloat() }
+        accessorySpec?.let { accessoryIcon.setImageDrawable(CraftNativeIcons.drawable(context, null, it.optString("symbol"), if (accessorySelected) accent else text)) }
         tabViews.forEachIndexed { index, (icon, label) ->
-            tabBar.getChildAt(index).isSelected = index == selectedTab
+            tabBar.getChildAt(index).isSelected = index == selectedTab && !accessorySelected
             tabBar.getChildAt(index).background = tabCellBackground(index, dark)
-            val color = if (index == selectedTab) accent else muted
+            val color = if (index == selectedTab && !accessorySelected) accent else muted
             val id = tabs[index].id
             val number = tabIconText[id]
             val appearance = tabIconAppearance(index, hasWindowFocus() && tabRow.isShown && android.animation.ValueAnimator.areAnimatorsEnabled())
@@ -1209,7 +1227,7 @@ internal class CraftNativeChrome(
     private fun accentColor(dark: Boolean): Int = if (dark) Color.parseColor("#0A84FF") else Color.parseColor("#007AFF")
 
     private fun tabCellBackground(index: Int, dark: Boolean): android.graphics.drawable.Drawable? {
-        if (index != selectedTab || (tabBarAppearance.selectionColor == null && tabBarAppearance.selectionCornerRadius == null)) return rippleBackground()
+        if (accessorySelected || index != selectedTab || (tabBarAppearance.selectionColor == null && tabBarAppearance.selectionCornerRadius == null)) return rippleBackground()
         val color = tabBarAppearance.selectionColor?.let { runCatching { Color.parseColor(it) }.getOrNull() }
             ?: if (dark) Color.argb(42, 255, 255, 255) else Color.argb(23, 0, 0, 0)
         val radius = tabBarAppearance.selectionCornerRadius?.let { (it * density).toInt().toFloat() } ?: dp(32).toFloat()

package/dist/android/templates/MainActivityNative.kt.template

@@ -864,6 +864,7 @@ internal class CraftNativeFlexLayout(context: Context) : LinearLayout(context) {
         super.onWindowVisibilityChanged(visibility)
         if (visibility != View.VISIBLE) celebration?.stop()
     }
+    var pageViewport: Pair<Int, Int>? = null
     var onLayoutChanged: (() -> Unit)? = null
     private val styles = mutableMapOf<View, CraftNativeLayoutStyle>()
     private var wrap = false
@@ -1839,6 +1840,12 @@ internal class CraftNativeFlexLayout(context: Context) : LinearLayout(context) {
     }
 
     override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
+        pageViewport?.let { (pageWidth, pageHeight) ->
+            val pages = (0 until childCount).map { getChildAt(it) }.filter { it.visibility != View.GONE }
+            pages.forEach { it.measure(MeasureSpec.makeMeasureSpec(pageWidth, MeasureSpec.EXACTLY), MeasureSpec.makeMeasureSpec(pageHeight, MeasureSpec.EXACTLY)) }
+            setMeasuredDimension(pageWidth * pages.size, pageHeight)
+            return
+        }
         val unboundedHorizontal = unboundedWidth && orientation == HORIZONTAL
         val widthMode = if (unboundedHorizontal) View.MeasureSpec.UNSPECIFIED else View.MeasureSpec.getMode(widthMeasureSpec)
         widthDefinite = widthMode == View.MeasureSpec.EXACTLY
@@ -1875,6 +1882,12 @@ internal class CraftNativeFlexLayout(context: Context) : LinearLayout(context) {
 
     override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
         celebration?.layout()
+        pageViewport?.let { (pageWidth, pageHeight) ->
+            val pages = (0 until childCount).map { getChildAt(it) }.filter { it.visibility != View.GONE }
+            pages.forEachIndexed { index, child -> child.layout(index * pageWidth, 0, (index + 1) * pageWidth, pageHeight) }
+            onLayoutChanged?.invoke()
+            return
+        }
         widthDefinite = true
         if (grid) {
             val layout = gridLayout(width, height)
@@ -2237,15 +2250,92 @@ private class CraftNativeKeyboardAvoidingView(context: Context) : FrameLayout(co
     }
 }
 
-private class CraftNativeScrollView(context: Context) : SwipeRefreshLayout(context) {
+/** CSS family fallback order, using bundled app fonts before platform families. */
+internal fun craftNativeFontFamily(family: String?, bundledFonts: Map<String, Typeface> = emptyMap()): Typeface =
+    family?.split(',')?.asSequence()?.map { it.trim().trim('"', '\'') }?.mapNotNull { name ->
+        bundledFonts[name] ?: when (name.lowercase()) {
+            "monospace", "ui-monospace" -> Typeface.MONOSPACE
+            "serif", "ui-serif" -> Typeface.SERIF
+            "sans-serif", "ui-sans-serif", "system-ui", "-apple-system" -> Typeface.SANS_SERIF
+            else -> Typeface.create(name, Typeface.NORMAL).takeUnless { it == Typeface.DEFAULT }
+        }
+    }?.firstOrNull() ?: Typeface.DEFAULT
+
+internal class CraftNativeScrollView(context: Context) : SwipeRefreshLayout(context) {
     val content = CraftNativeFlexLayout(context)
     // Keep one refresh target across axis changes. Replacing all children of
     // SwipeRefreshLayout would also detach its own animated indicator.
     private val scrollContainer = FrameLayout(context)
-    private val vertical = ScrollView(context)
-    private val horizontal = HorizontalScrollView(context)
+    private val vertical = object : ScrollView(context) {
+        override fun onInterceptTouchEvent(event: MotionEvent): Boolean = isEnabled && super.onInterceptTouchEvent(event)
+        override fun onTouchEvent(event: MotionEvent): Boolean = isEnabled && super.onTouchEvent(event)
+    }
+    private val horizontal = object : HorizontalScrollView(context) {
+        override fun onInterceptTouchEvent(event: MotionEvent): Boolean = isEnabled && super.onInterceptTouchEvent(event)
+        override fun onTouchEvent(event: MotionEvent): Boolean = isEnabled && super.onTouchEvent(event)
+    }
     private var horizontalMode: Boolean? = null
     private var pagingEnabled = false
+    private var authoredPageIndex: Int? = null
+    private var pendingPageIndex: Int? = null
+    private var currentPageIndex = 0
+    private var reportedPage: Pair<Int, Int>? = null
+    private var pageHandler: ((Int, Int) -> Unit)? = null
+    private var pageSettleGeneration = 0
+    private var pageDragging = false
+    private var pageInMotion = false
+
+    private fun schedulePageSettle(scroller: View) {
+        val generation = ++pageSettleGeneration
+        scroller.postDelayed({
+            if (generation == pageSettleGeneration && !pageDragging) {
+                pageInMotion = false
+                settlePage()
+            }
+        }, 80L)
+    }
+
+    fun configurePager(value: Any?, onSelect: ((Int, Int) -> Unit)?) {
+        val next = (value as? Number)?.toDouble()?.takeIf { it.isFinite() }?.coerceIn(0.0, (Int.MAX_VALUE / 2).toDouble())?.toInt()
+        if (next != authoredPageIndex) pendingPageIndex = next
+        authoredPageIndex = next
+        pageHandler = onSelect
+        if (next == null) { content.pageViewport = null; reportedPage = null }
+        requestLayout()
+    }
+
+    private fun settlePage() {
+        if (authoredPageIndex == null || horizontal.width <= 0 || pageDragging || pageInMotion) return
+        val pages = (0 until content.childCount).map { content.getChildAt(it) }.filter { it.visibility != View.GONE }
+        val index = (horizontal.scrollX.toFloat() / horizontal.width).roundToInt().coerceIn(0, max(0, pages.size - 1))
+        val target = index * horizontal.width
+        if (horizontal.scrollX != target) {
+            // ACTION_UP can start native motion after our touch listener's snap.
+            // A rounded index is not settled until that viewport is fully shown.
+            pageInMotion = true
+            horizontal.smoothScrollTo(target, 0)
+            schedulePageSettle(horizontal)
+            return
+        }
+        currentPageIndex = index
+        pages.forEachIndexed { i, page -> page.importantForAccessibility = if (i == index) View.IMPORTANT_FOR_ACCESSIBILITY_AUTO else View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS }
+        val report = index to pages.size
+        if (report != reportedPage) { reportedPage = report; pageHandler?.invoke(index, pages.size) }
+    }
+
+    override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
+        val oldWidth = horizontal.width
+        super.onLayout(changed, left, top, right, bottom)
+        if (authoredPageIndex != null && horizontalMode == true && horizontal.width > 0) {
+            val count = (0 until content.childCount).count { content.getChildAt(it).visibility != View.GONE }
+            val index = (pendingPageIndex ?: currentPageIndex).coerceIn(0, max(0, count - 1))
+            if (pendingPageIndex != null || oldWidth != horizontal.width || index != currentPageIndex) horizontal.scrollTo(index * horizontal.width, 0)
+            pendingPageIndex = null
+            currentPageIndex = index
+            settlePage()
+        }
+    }
+
     private var bounces = true
     private var alwaysBounceVertical = true
     private var alwaysBounceHorizontal = true
@@ -2273,6 +2363,10 @@ private class CraftNativeScrollView(context: Context) : SwipeRefreshLayout(conte
         // configured. Interception is gated below instead.
         isEnabled = true
         setHorizontal(false)
+        // Paging is owned by this native control even before an Activity
+        // supplies optional bridge callbacks. Its normal configuration may
+        // replace these listeners without changing gesture ownership.
+        setScrollListeners(null, null, null, null, null, "none", null)
     }
 
     override fun onInterceptTouchEvent(event: MotionEvent): Boolean {
@@ -2301,6 +2395,7 @@ private class CraftNativeScrollView(context: Context) : SwipeRefreshLayout(conte
         val unspecified = MeasureSpec.makeMeasureSpec(0, MeasureSpec.UNSPECIFIED)
         val horizontalPadding = paddingLeft + paddingRight
         val verticalPadding = paddingTop + paddingBottom
+        content.pageViewport = if (authoredPageIndex != null && sideways) max(0, widthSize - horizontalPadding) to max(0, heightSize - verticalPadding) else null
         content.measure(
             if (sideways || widthMode == MeasureSpec.UNSPECIFIED) unspecified
             else MeasureSpec.makeMeasureSpec(max(0, widthSize - horizontalPadding), MeasureSpec.EXACTLY),
@@ -2316,7 +2411,7 @@ private class CraftNativeScrollView(context: Context) : SwipeRefreshLayout(conte
                 ViewGroup.LayoutParams.WRAP_CONTENT,
                 ViewGroup.LayoutParams.MATCH_PARENT,
             )
-            params.width = max(params.width, content.measuredWidth)
+            params.width = if (authoredPageIndex != null) content.measuredWidth else max(params.width, content.measuredWidth)
             content.layoutParams = params
         }
         fun fit(mode: Int, size: Int, wanted: Int): Int = when (mode) {
@@ -2648,11 +2743,18 @@ private class CraftNativeScrollView(context: Context) : SwipeRefreshLayout(conte
 
             scroller.setOnScrollChangeListener { _, x, y, _, _ ->
                 if (horizontalMode != true) updateStickyHeaders()
+                if (authoredPageIndex != null) {
+                    pageInMotion = true
+                    schedulePageSettle(scroller)
+                }
                 onScroll?.invoke(x, y)
             }
             scroller.setOnTouchListener { _, event ->
                 when (event.actionMasked) {
                     android.view.MotionEvent.ACTION_DOWN -> {
+                        pageDragging = true
+                        pageInMotion = false
+                        pageSettleGeneration += 1
                         if (momentumActive) {
                             momentumActive = false
                             onMomentumEnd?.invoke()
@@ -2674,6 +2776,8 @@ private class CraftNativeScrollView(context: Context) : SwipeRefreshLayout(conte
                         }
                         onEndDrag?.invoke()
                         if (pagingEnabled) snapToPage(scroller)
+                        pageDragging = false
+                        if (authoredPageIndex != null) schedulePageSettle(scroller)
                         if (moved && !momentumActive) {
                             momentumActive = true
                             lastX = scroller.scrollX
@@ -2692,6 +2796,10 @@ private class CraftNativeScrollView(context: Context) : SwipeRefreshLayout(conte
 
     fun clearScrollListeners() {
         scrollListenerGeneration += 1
+        pageSettleGeneration += 1
+        pageDragging = false
+        pageInMotion = false
+        pageHandler = null
         vertical.setOnScrollChangeListener(null)
         vertical.setOnTouchListener(null)
         horizontal.setOnScrollChangeListener(null)
@@ -4868,7 +4976,7 @@ class MainActivity : AppCompatActivity() {
         val bars = chrome ?: return
         val depth = screens.indexOf(screen).coerceAtLeast(0)
         val fallback = if (depth == 0) routes.tabs.getOrNull(currentTab)?.title else null
-        bars.apply(screen.options, depth, fallback)
+        bars.apply(screen.options, depth, fallback, screen.path)
     }
 
     /** Applies a screen-specific background, falling back to the dynamic app colour. */
@@ -4932,6 +5040,7 @@ class MainActivity : AppCompatActivity() {
         put("viewReparent")
         put("viewNonModalPresentation")
         put("nativePlatformControls")
+        put("nativePager")
     }
 
     private fun appVersion(): Pair<String, String> = runCatching {
@@ -6095,6 +6204,10 @@ class MainActivity : AppCompatActivity() {
                     craftNativeBoolean(props.opt("alwaysBounceHorizontal"), horizontal),
                 )
                 setPagingEnabled(craftNativeBoolean(props.opt("pagingEnabled")))
+                val pageHandler = craftNativeEventName(events, "onPageSelected").takeIf { it.isNotBlank() }
+                configurePager(props.opt("pageIndex"), pageHandler?.let { handler ->
+                    { index, count -> send(screen, "EVENT", JSONObject().put("handlerName", handler).put("nativeEvent", JSONObject().put("index", index).put("count", count))) }
+                })
                 val refreshNode = (0 until children.length()).asSequence()
                     .mapNotNull { children.optJSONObject(it) }
                     .firstOrNull { canonicalType(it.optString("type")) == "RefreshControl" }
@@ -6916,7 +7029,7 @@ class MainActivity : AppCompatActivity() {
         }
         val italic = craftNativeOptionalString(style.opt("fontStyle")) == "italic"
         val family = craftNativeOptionalString(style.opt("fontFamily"))?.takeIf { it.isNotBlank() }
-        val base = family?.let { bundledFonts[it] } ?: Typeface.create(family, Typeface.NORMAL)
+        val base = craftNativeFontFamily(family, bundledFonts)
         view.typeface = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
             Typeface.create(base, weight, italic)
         } else Typeface.create(base, (if (weight >= 600) Typeface.BOLD else Typeface.NORMAL) or

package/dist/cli.js

@@ -262,6 +262,7 @@ async function packageMacOS(config, outDir) {
     iconPath: config.iconPath,
     provisioningProfile: opts.provisioningProfile,
     additionalExecutables: opts.additionalExecutables,
+    nativeRuntimePath: opts.nativeRuntimePath,
     outputPath: appBundlePath
   });
   if (!appBundle.success) {
@@ -543,7 +544,7 @@ ${schemes.length ? `MimeType=${schemes.map((scheme) => `x-scheme-handler/${schem
 }
 function macOSInfoPlist(metadata) {
   const entries = [
-    ["CFBundleExecutable", metadata.name],
+    ["CFBundleExecutable", metadata.executableName || metadata.name],
     ["CFBundleIdentifier", metadata.bundleId],
     ["CFBundleName", metadata.name],
     ["CFBundleShortVersionString", metadata.version],
@@ -686,6 +687,9 @@ function copyMacOSAppBundle(source, destination) {
     return { success: false, error: error.message };
   }
 }
+function macOSRuntimeExecutablePath(appBundlePath) {
+  return join2(appBundlePath, "Contents", "Helpers", "CraftRuntime.app", "Contents", "MacOS", "craft");
+}
 function createMacOSAppBundle(opts) {
   try {
     const { name, binaryPath, iconPath, provisioningProfile, additionalExecutables, outputPath } = opts;
@@ -702,6 +706,27 @@ function createMacOSAppBundle(opts) {
       copyFileSync(executable, destination);
       chmodSync(destination, 493);
     }
+    if (opts.nativeRuntimePath) {
+      const helper = macOSRuntimeExecutablePath(outputPath);
+      const helperContents = resolve(helper, "..", "..");
+      mkdirSync(join2(helperContents, "MacOS"), { recursive: true });
+      copyFileSync(opts.nativeRuntimePath, helper);
+      chmodSync(helper, 493);
+      if (iconPath) {
+        mkdirSync(join2(helperContents, "Resources"), { recursive: true });
+        copyFileSync(iconPath, join2(helperContents, "Resources", "icon.icns"));
+      }
+      writeFileSync3(join2(helperContents, "Info.plist"), macOSInfoPlist({
+        name,
+        executableName: "craft",
+        version: opts.version,
+        bundleId: `${opts.bundleId}.runtime`,
+        buildNumber: opts.buildNumber,
+        minimumSystemVersion: opts.minimumSystemVersion,
+        menuBarOnly: true,
+        iconName: iconPath ? "icon" : undefined
+      }));
+    }
     let iconName;
     if (iconPath) {
       if (!existsSync4(iconPath))
@@ -2945,7 +2970,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.304";
+var version = "0.0.319";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -158,6 +158,7 @@ __export(exports_src, {
   liveActivities: () => liveActivities,
   loadURL: () => loadURL,
   location: () => location,
+  macOSRuntimeExecutablePath: () => macOSRuntimeExecutablePath,
   materialYou: () => materialYou,
   media: () => media,
   menuItem: () => menuItem,
@@ -374,7 +375,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.304";
+var version = "0.0.319";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -627,6 +628,7 @@ async function packageMacOS(config, outDir) {
     iconPath: config.iconPath,
     provisioningProfile: opts.provisioningProfile,
     additionalExecutables: opts.additionalExecutables,
+    nativeRuntimePath: opts.nativeRuntimePath,
     outputPath: appBundlePath
   });
   if (!appBundle.success) {
@@ -909,7 +911,7 @@ ${schemes.length ? `MimeType=${schemes.map((scheme) => `x-scheme-handler/${schem
 }
 function macOSInfoPlist(metadata) {
   const entries = [
-    ["CFBundleExecutable", metadata.name],
+    ["CFBundleExecutable", metadata.executableName || metadata.name],
     ["CFBundleIdentifier", metadata.bundleId],
     ["CFBundleName", metadata.name],
     ["CFBundleShortVersionString", metadata.version],
@@ -1052,6 +1054,9 @@ function copyMacOSAppBundle(source, destination) {
     return { success: false, error: error.message };
   }
 }
+function macOSRuntimeExecutablePath(appBundlePath) {
+  return import_path.join(appBundlePath, "Contents", "Helpers", "CraftRuntime.app", "Contents", "MacOS", "craft");
+}
 function createMacOSAppBundle(opts) {
   try {
     const { name, binaryPath, iconPath, provisioningProfile, additionalExecutables, outputPath } = opts;
@@ -1068,6 +1073,27 @@ function createMacOSAppBundle(opts) {
       import_fs.copyFileSync(executable, destination);
       import_fs.chmodSync(destination, 493);
     }
+    if (opts.nativeRuntimePath) {
+      const helper = macOSRuntimeExecutablePath(outputPath);
+      const helperContents = import_path.resolve(helper, "..", "..");
+      import_fs.mkdirSync(import_path.join(helperContents, "MacOS"), { recursive: true });
+      import_fs.copyFileSync(opts.nativeRuntimePath, helper);
+      import_fs.chmodSync(helper, 493);
+      if (iconPath) {
+        import_fs.mkdirSync(import_path.join(helperContents, "Resources"), { recursive: true });
+        import_fs.copyFileSync(iconPath, import_path.join(helperContents, "Resources", "icon.icns"));
+      }
+      import_fs.writeFileSync(import_path.join(helperContents, "Info.plist"), macOSInfoPlist({
+        name,
+        executableName: "craft",
+        version: opts.version,
+        bundleId: `${opts.bundleId}.runtime`,
+        buildNumber: opts.buildNumber,
+        minimumSystemVersion: opts.minimumSystemVersion,
+        menuBarOnly: true,
+        iconName: iconPath ? "icon" : undefined
+      }));
+    }
     let iconName;
     if (iconPath) {
       if (!import_fs.existsSync(iconPath))

package/dist/index.d.cts

@@ -24,7 +24,7 @@ export declare function parseCraftVersionOutput(output: string): string;
  * (#236).
  */
 export declare function craftProcessFailedMessage(code: number | null, stderr: string, quiet: boolean): string;
-export { packageApp, pack, type PackageConfig, type PackageResult } from './package.js';
+export { packageApp, pack, macOSRuntimeExecutablePath, type PackageConfig, type PackageResult } from './package.js';
 export { craftBinaryNotFoundMessage, resolveCraftBinary } from './binary-resolver.js';
 export * from './utils/index.js';
 export * from './api/index.js';
@@ -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, MenubarState, 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';
+export type { WindowOptions, CraftSidebarAPI, CraftNativeUIAPI, CraftContextMenuItem, CraftContextMenuResult, AppConfig, CraftTrayAPI, CraftWindowAPI, CraftAppAPI, CraftBridgeAPI, MenubarState, MenubarInitOptions, 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

@@ -24,7 +24,7 @@ export declare function parseCraftVersionOutput(output: string): string;
  * (#236).
  */
 export declare function craftProcessFailedMessage(code: number | null, stderr: string, quiet: boolean): string;
-export { packageApp, pack, type PackageConfig, type PackageResult } from './package.js';
+export { packageApp, pack, macOSRuntimeExecutablePath, type PackageConfig, type PackageResult } from './package.js';
 export { craftBinaryNotFoundMessage, resolveCraftBinary } from './binary-resolver.js';
 export * from './utils/index.js';
 export * from './api/index.js';
@@ -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, MenubarState, 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';
+export type { WindowOptions, CraftSidebarAPI, CraftNativeUIAPI, CraftContextMenuItem, CraftContextMenuResult, AppConfig, CraftTrayAPI, CraftWindowAPI, CraftAppAPI, CraftBridgeAPI, MenubarState, MenubarInitOptions, 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.304";
+var version = "0.0.319";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -384,6 +384,7 @@ async function packageMacOS(config, outDir) {
     iconPath: config.iconPath,
     provisioningProfile: opts.provisioningProfile,
     additionalExecutables: opts.additionalExecutables,
+    nativeRuntimePath: opts.nativeRuntimePath,
     outputPath: appBundlePath
   });
   if (!appBundle.success) {
@@ -666,7 +667,7 @@ ${schemes.length ? `MimeType=${schemes.map((scheme) => `x-scheme-handler/${schem
 }
 function macOSInfoPlist(metadata) {
   const entries = [
-    ["CFBundleExecutable", metadata.name],
+    ["CFBundleExecutable", metadata.executableName || metadata.name],
     ["CFBundleIdentifier", metadata.bundleId],
     ["CFBundleName", metadata.name],
     ["CFBundleShortVersionString", metadata.version],
@@ -809,6 +810,9 @@ function copyMacOSAppBundle(source, destination) {
     return { success: false, error: error.message };
   }
 }
+function macOSRuntimeExecutablePath(appBundlePath) {
+  return join2(appBundlePath, "Contents", "Helpers", "CraftRuntime.app", "Contents", "MacOS", "craft");
+}
 function createMacOSAppBundle(opts) {
   try {
     const { name, binaryPath, iconPath, provisioningProfile, additionalExecutables, outputPath } = opts;
@@ -825,6 +829,27 @@ function createMacOSAppBundle(opts) {
       copyFileSync(executable, destination);
       chmodSync(destination, 493);
     }
+    if (opts.nativeRuntimePath) {
+      const helper = macOSRuntimeExecutablePath(outputPath);
+      const helperContents = resolve(helper, "..", "..");
+      mkdirSync(join2(helperContents, "MacOS"), { recursive: true });
+      copyFileSync(opts.nativeRuntimePath, helper);
+      chmodSync(helper, 493);
+      if (iconPath) {
+        mkdirSync(join2(helperContents, "Resources"), { recursive: true });
+        copyFileSync(iconPath, join2(helperContents, "Resources", "icon.icns"));
+      }
+      writeFileSync2(join2(helperContents, "Info.plist"), macOSInfoPlist({
+        name,
+        executableName: "craft",
+        version: opts.version,
+        bundleId: `${opts.bundleId}.runtime`,
+        buildNumber: opts.buildNumber,
+        minimumSystemVersion: opts.minimumSystemVersion,
+        menuBarOnly: true,
+        iconName: iconPath ? "icon" : undefined
+      }));
+    }
     let iconName;
     if (iconPath) {
       if (!existsSync3(iconPath))
@@ -11595,6 +11620,7 @@ export {
   liveActivities,
   loadURL,
   location,
+  macOSRuntimeExecutablePath,
   materialYou,
   media,
   menuItem,

package/dist/ios/src/index.js

@@ -189,7 +189,12 @@ function serializeSimulatorSteps(steps) {
   };
   const line = (step) => {
     let arg = "";
-    if ("paths" in step) {
+    if (step.command === "holdtab") {
+      const seconds = step.seconds ?? 6;
+      if (!step.text.trim() || step.text.includes("|") || number(seconds) < 2 || seconds > 10)
+        throw new Error("holdtab needs a nonempty tab name and 2\u201310 seconds");
+      arg = `${step.text} | ${seconds}`;
+    } else if ("paths" in step) {
       if (!step.paths.length || step.paths.length > 64)
         throw new Error("Expected 1\u201364 touch paths");
       for (const path of step.paths) {

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

@@ -61,6 +61,12 @@ export type SimulatorStep = {
  | {
     command: 'touches';
     paths: TimedTouchPoint[][];
+}
+/** Standard XCTest tab hold; independent screenshots must be captured before release. */
+ | {
+    command: 'holdtab';
+    text: string;
+    seconds?: number;
 } | {
     command: 'field';
     index: number;

package/dist/ios/templates/CraftApp.swift

@@ -766,6 +766,13 @@ final class CraftChrome: ObservableObject {
     @Published var tabAccessory: Tab?
     private weak var tabAccessoryOwner: AnyObject?
     @Published var selected: String?
+    /// The visible destination may be the accessory, independently of its owning stack.
+    @Published var visiblePath: String?
+    var accessorySelected: Bool {
+        guard let path = visiblePath, let accessory = tabAccessory?.id else { return false }
+        return path == accessory || path.hasPrefix(accessory + "/")
+    }
+    var highlightedTab: String? { accessorySelected ? nil : selected }
     let tabSwipeProgress = CraftTabSwipeProgress()
     private(set) var tabSwipePosition: CGFloat? {
         get { tabSwipeProgress.position }
@@ -1172,6 +1179,18 @@ final class CraftChromeRelay: NSObject, WKScriptMessageHandler {
 
 /// The floating tab bar: Liquid Glass on iOS 26 and later, a material capsule before.
 struct CraftTabBarView: View {
+    @Environment(\.dynamicTypeSize) private var dynamicTypeSize
+
+    var body: some View {
+        // ScaledMetric reads the environment of its owning view. Put the
+        // metrics in a child so this compact-chrome cap reaches them too.
+        CraftTabBarContent(viewerTextSize: dynamicTypeSize)
+            .dynamicTypeSize(...DynamicTypeSize.xxxLarge)
+    }
+}
+
+private struct CraftTabBarContent: View {
+    let viewerTextSize: DynamicTypeSize
     @ObservedObject private var chrome = CraftChrome.shared
     @Environment(\.accessibilityReduceMotion) private var reduceMotion
     @Environment(\.scenePhase) private var scenePhase
@@ -1183,7 +1202,7 @@ struct CraftTabBarView: View {
     @ScaledMetric(relativeTo: .caption2) private var badgeSize: CGFloat = 10
 
     var body: some View {
-        if chrome.tabBarVisible && !chrome.tabs.isEmpty {
+        if !chrome.tabs.isEmpty {
             HStack(spacing: 8) {
                 bar
                 if let accessory = chrome.tabAccessory {
@@ -1191,8 +1210,13 @@ struct CraftTabBarView: View {
                         surface {
                             Image(systemName: accessory.symbol)
                                 .font(.system(size: iconSize))
-                                .foregroundStyle(Color.primary)
+                                .foregroundStyle(chrome.accessorySelected ? selectedColor : Color.primary)
                                 .frame(width: 62, height: 62)
+                                .background {
+                                    if chrome.accessorySelected {
+                                        Circle().fill(selectedColor.opacity(0.14)).padding(4)
+                                    }
+                                }
                         }
                             .contentShape(Rectangle())
                             .overlay(alignment: .topTrailing) {
@@ -1207,9 +1231,17 @@ struct CraftTabBarView: View {
                             }
                     }
                     .buttonStyle(.plain)
+                    .accessibilityShowsLargeContentViewer {
+                        Image(systemName: accessory.symbol)
+                        Text(accessory.accessibilityLabel ?? accessory.title)
+                    }
+                    // Keep accessibility intent for the viewer; displayed
+                    // sizes come from the bounded metrics owned above.
+                    .environment(\.dynamicTypeSize, viewerTextSize)
                     .accessibilityLabel(accessory.accessibilityLabel ?? accessory.title)
                     .accessibilityValue(accessory.badge ?? "")
                     .accessibilityIdentifier("craft-tab-accessory")
+                    .accessibilityAddTraits(chrome.accessorySelected ? .isSelected : [])
                 }
             }
                 .padding(.horizontal, 16)
@@ -1219,9 +1251,14 @@ struct CraftTabBarView: View {
                         .onAppear { report(proxy) }
                         .onChange(of: proxy.frame(in: .global)) { _ in report(proxy) }
                 })
-                .transition(reduceMotion ? .opacity : .move(edge: .bottom).combined(with: .opacity))
+                // Keep the view mounted: a disappearing conditional inside a
+                // child does not reliably animate in the UIKit navigation transaction.
+                .offset(y: chrome.tabBarVisible || reduceMotion ? 0 : 120)
+                .opacity(chrome.tabBarVisible ? 1 : 0)
+                .allowsHitTesting(chrome.tabBarVisible)
+                .accessibilityHidden(!chrome.tabBarVisible)
+                .animation(.easeInOut(duration: reduceMotion ? 0.12 : 0.24), value: chrome.tabBarVisible)
                 .ignoresSafeArea(.keyboard)
-                .dynamicTypeSize(...DynamicTypeSize.xxxLarge)
         }
     }
 
@@ -1260,7 +1297,7 @@ struct CraftTabBarView: View {
     private var items: some View {
         HStack(spacing: 0) {
             ForEach(chrome.tabs) { tab in
-                let isSelected = tab.id == chrome.selected
+                let isSelected = tab.id == chrome.highlightedTab
                 Button { chrome.tap(tab) } label: {
                     VStack(spacing: 3) {
                         ZStack(alignment: .topTrailing) {
@@ -1305,6 +1342,7 @@ struct CraftTabBarView: View {
                     Image(systemName: symbol(tab.symbol, selected: isSelected))
                     Text(tab.displayTitle)
                 }
+                .environment(\.dynamicTypeSize, viewerTextSize)
                 .accessibilityIdentifier("craft-tab-\(tab.id)")
                 .accessibilityLabel(tab.accessibilityLabel ?? tab.badge.map { "\(tab.displayTitle), \($0)" } ?? tab.displayTitle)
                 .accessibilityAddTraits(isSelected ? [.isSelected, .isButton] : .isButton)
@@ -1312,7 +1350,7 @@ struct CraftTabBarView: View {
         }
         .background {
             CraftTabSelectionIndicator(
-                selected: chrome.tabs.firstIndex(where: { $0.id == chrome.selected }),
+                selected: chrome.tabs.firstIndex(where: { $0.id == chrome.highlightedTab }),
                 count: chrome.tabs.count,
                 cornerRadius: chrome.tabSelectionCornerRadius
             )

package/dist/ios/templates/CraftHybrid.swift

@@ -1664,6 +1664,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             (nav.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(true)
         }
         currentTab = id
+        if let top = nav.topViewController { CraftChrome.shared.visiblePath = nativePaths[ObjectIdentifier(top)] }
         for (key, other) in stacks { other.view.isHidden = key != id }
         nav.view.frame = view.bounds
         view.bringSubviewToFront(nav.view)
@@ -2042,6 +2043,9 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     func navigationController(_ navigationController: UINavigationController, willShow viewController: UIViewController, animated: Bool) {
         lastNavigation = CACurrentMediaTime()
         if animated { CraftFramePacing.shared.begin("navigation") }
+        if navigationController === visibleStack {
+            CraftChrome.shared.visiblePath = nativePaths[ObjectIdentifier(viewController)]
+        }
         // The page draws its own header, and a tab's root screen its own
         // title unless it asked for the bar; a pushed native screen gets the
         // bar and its Back.
@@ -2084,6 +2088,8 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             hybrid.pageReset(to: rootPath)
         }
         guard navigationController === visibleStack else { return }
+        // Also restore selection after a cancelled interactive pop.
+        CraftChrome.shared.visiblePath = nativePaths[ObjectIdentifier(viewController)]
         if let slot = viewController as? CraftHybridWebSlot { adoptWeb(into: slot) } else { parkWeb() }
     }
 

package/dist/ios/templates/CraftNativeActions.swift

@@ -43,6 +43,7 @@ enum CraftNativeActions {
         // `speech`, `audio` (background sound) and `eventStream` (a fetch read
         // as it arrives) need nothing the app has to declare.
         var values = ["device", "clipboard", "haptics", "storage", "lifecycle", "fetch", "dialog", "speech", "audio", "eventStream", "linking", "badge", "animation", "viewFocus", "viewMeasure", "viewReparent", "viewNonModalPresentation", "nativePlatformControls"]
+        values.append("nativePager")
         values.append("storageCompareAndSet")
         values.append("storageSetIfAbsent")
         values.append("viewScroll")

package/dist/ios/templates/CraftNativeScreen.swift

@@ -2744,6 +2744,7 @@ final class CraftNativeCelebration {
 }
 
 private class CraftNativeFlowView: UIStackView {
+    var pageViewport: CGSize? { didSet { if pageViewport != oldValue { invalidateMeasurements() } } }
     var celebration: CraftNativeCelebration?
     func configureCelebration(_ raw: Any?) {
         if raw != nil && celebration == nil { celebration = CraftNativeCelebration(view: self) }
@@ -2966,6 +2967,7 @@ private class CraftNativeFlowView: UIStackView {
     }
 
     func measure(width: CGFloat?, height: CGFloat?, maxWidth: CGFloat, maxHeight: CGFloat) -> CGSize {
+        if let page = pageViewport { return CGSize(width: page.width * CGFloat(arrangedSubviews.filter { !$0.isHidden }.count), height: page.height) }
         let key = MeasureKey(width: width, height: height, maxWidth: maxWidth, maxHeight: maxHeight)
         if let cached = measurements[key] { return cached }
         let size = layout(width: width, height: height, maxWidth: maxWidth, maxHeight: maxHeight, place: false).size
@@ -2977,6 +2979,12 @@ private class CraftNativeFlowView: UIStackView {
         super.layoutSubviews()
         craftApplyCornerRadius()
         celebration?.layout()
+        if let page = pageViewport {
+            for (index, child) in arrangedSubviews.filter({ !$0.isHidden }).enumerated() {
+                child.frame = CGRect(x: CGFloat(index) * page.width, y: 0, width: page.width, height: page.height)
+            }
+            return
+        }
         let scale = window?.screen.scale ?? traitCollection.displayScale
         let result = layout(width: bounds.width, height: bounds.height, maxWidth: bounds.width, maxHeight: bounds.height, place: true)
         var moved = false
@@ -4344,6 +4352,46 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
     private var laidOutSize: CGSize = .zero
     private let pullToRefresh = UIRefreshControl()
     private var refreshHandler: (() -> Void)?
+    private var authoredPageIndex: Int?
+    private var pendingPageIndex: Int?
+    private var currentPageIndex = 0
+    private var pageAnimating = false
+    private var reportedPage: (Int, Int)?
+    private var pageHandler: ((Int, Int) -> Void)?
+
+    /// Opt-in viewport-sized pages. Ordinary horizontal scroll strips retain
+    /// their intrinsic widths; only a controlled pageIndex enables this mode.
+    func configurePager(_ raw: Any?, onSelect: ((Int, Int) -> Void)?) {
+        let next = craftNativeNumber(raw).flatMap { number -> Int? in
+            let value = number.doubleValue
+            return value.isFinite ? Int(min(Double(Int.max / 2), max(0, value))) : nil
+        }
+        if next != authoredPageIndex { pendingPageIndex = next; contentNeedsLayout = true }
+        authoredPageIndex = next
+        pageHandler = onSelect
+        if next == nil { contentStack.pageViewport = nil; reportedPage = nil; pageAnimating = false }
+        setNeedsLayout()
+    }
+
+    func beginPageDrag() { pageAnimating = false }
+
+    func finishPageMotion() {
+        pageAnimating = false
+        DispatchQueue.main.async { [weak self] in self?.settlePage() }
+    }
+
+    func settlePage() {
+        guard authoredPageIndex != nil, bounds.width > 0, !pageAnimating,
+              !isTracking, !isDragging, !isDecelerating else { return }
+        let pages = contentStack.arrangedSubviews.filter { !$0.isHidden }
+        let index = min(max(0, Int((contentOffset.x / bounds.width).rounded())), max(0, pages.count - 1))
+        currentPageIndex = index
+        for (i, child) in pages.enumerated() { child.accessibilityElementsHidden = i != index }
+        if reportedPage?.0 != index || reportedPage?.1 != pages.count {
+            reportedPage = (index, pages.count)
+            pageHandler?(index, pages.count)
+        }
+    }
 
     override init(frame: CGRect) {
         super.init(frame: frame)
@@ -4384,6 +4432,11 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
     /// The size of the content laid out across the visible width (or, sideways,
     /// height), which is also the scroll view's own size when nothing fixes it.
     func contentFitting(width: CGFloat?, height: CGFloat?) -> CGSize {
+        if authoredPageIndex != nil && !isVertical {
+            let pageWidth = max(0, width ?? bounds.width)
+            let pageHeight = max(0, height ?? bounds.height)
+            return CGSize(width: pageWidth * CGFloat(contentStack.arrangedSubviews.filter { !$0.isHidden }.count), height: pageHeight)
+        }
         if isVertical {
             let contentWidth = max(0, (width ?? bounds.width) - adjustedContentInset.left - adjustedContentInset.right)
             return contentStack.measure(width: contentWidth, height: nil, maxWidth: contentWidth, maxHeight: CraftNativeFlexLayout.unbounded)
@@ -4406,7 +4459,9 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
         craftApplyCornerRadius()
         if contentNeedsLayout || laidOutSize != bounds.size {
             contentNeedsLayout = false
+            let resized = laidOutSize != bounds.size
             laidOutSize = bounds.size
+            if authoredPageIndex != nil && !isVertical { contentStack.pageViewport = bounds.size }
             var size = contentFitting(width: bounds.width, height: bounds.height)
             if isVertical {
                 size.width = max(0, bounds.width - adjustedContentInset.left - adjustedContentInset.right)
@@ -4416,12 +4471,31 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
             let frame = CGRect(origin: .zero, size: size)
             if contentStack.frame != frame { contentStack.frame = frame }
             if contentSize != size { contentSize = size }
+            if authoredPageIndex != nil && !isVertical {
+                contentStack.layoutIfNeeded()
+                let count = contentStack.arrangedSubviews.filter { !$0.isHidden }.count
+                let index = min(max(0, pendingPageIndex ?? currentPageIndex), max(0, count - 1))
+                let target = CGPoint(x: CGFloat(index) * bounds.width, y: 0)
+                let moves = pendingPageIndex != nil || resized || index != currentPageIndex
+                let animated = moves && target != contentOffset && !resized && !UIAccessibility.isReduceMotionEnabled
+                if moves {
+                    pageAnimating = animated
+                    setContentOffset(target, animated: animated)
+                }
+                pendingPageIndex = nil
+                currentPageIndex = index
+                if !animated && !isTracking && !isDragging && !isDecelerating { settlePage() }
+            }
         }
         // A scroll view lays out on every frame of a scroll: the sticky
         // headers follow it here, over content placed by this same pass.
         if !stickyIndices.isEmpty || pendingScrollTarget != nil { contentStack.layoutIfNeeded() }
         updateStickyHeaders()
         scrollToPendingTarget()
+        // A nonanimated target changes the offset synchronously inside this
+        // layout pass. Rebase the headers against that actual viewport, not
+        // the viewport from before the target was applied.
+        updateStickyHeaders()
     }
 
     // MARK: Sticky headers
@@ -4444,7 +4518,7 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
         view.center.y - view.bounds.height / 2
     }
 
-    private func updateStickyHeaders() {
+    fileprivate func updateStickyHeaders() {
         let children = contentStack.arrangedSubviews
         let headers = isVertical ? stickyIndices.compactMap { $0 < children.count ? children[$0] : nil }.filter { !$0.isHidden } : []
         for view in stickyViews where !headers.contains(where: { $0 === view }) {
@@ -4617,11 +4691,13 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
         craftScrollGesture(gestureRecognizer, runsWith: otherGestureRecognizer)
     }
 
-    func setAxis(_ axis: NSLayoutConstraint.Axis) {
+    func setAxis(_ axis: NSLayoutConstraint.Axis, resetBounce: Bool = true) {
         if contentStack.axis != axis { setContentNeedsLayout() }
         contentStack.axis = axis
-        alwaysBounceVertical = axis == .vertical
-        alwaysBounceHorizontal = axis == .horizontal
+        if resetBounce {
+            alwaysBounceVertical = axis == .vertical
+            alwaysBounceHorizontal = axis == .horizontal
+        }
     }
 }
 
@@ -8461,6 +8537,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             scroll.isScrollEnabled = props["scrollEnabled"] as? Bool != false
             scroll.bounces = props["bounces"] as? Bool ?? true
             scroll.isPagingEnabled = props["pagingEnabled"] as? Bool ?? false
+            let pageHandler = nonEmptyHandler(events["onPageSelected"])
+            scroll.configurePager(props["pageIndex"], onSelect: pageHandler.map { handler in
+                { [weak self] index, count in self?.send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": ["index": index, "count": count]]) }
+            })
             scroll.keyboardDismissMode = keyboardDismissMode(props["keyboardDismissMode"])
             scroll.setKeyboardShouldPersistTaps(props["keyboardShouldPersistTaps"])
             scroll.showsVerticalScrollIndicator = props["showsVerticalScrollIndicator"] as? Bool != false
@@ -8492,6 +8572,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 contentStyle.merge(override) { _, next in next }
             }
             configureStack(scroll.contentStack, style: contentStyle)
+            // Content-style defaults are vertical; the scroll host's explicit
+            // axis must survive that shared container configuration without
+            // resetting the authored bounce options applied above.
+            scroll.setAxis(direction, resetBounce: false)
             reconcileChildren(children.filter {
                 guard let child = $0 as? [String: Any] else { return true }
                 return canonicalType(child["type"] as? String ?? "") != "RefreshControl"
@@ -9712,10 +9796,28 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             for: size,
             compatibleWith: traitCollection
         )
-        var font = (style["fontFamily"] as? String).flatMap { UIFont(name: $0, size: scaledSize) }
-            ?? .systemFont(ofSize: scaledSize, weight: weight)
+        let families = (style["fontFamily"] as? String ?? "").split(separator: ",").map {
+            $0.trimmingCharacters(in: .whitespacesAndNewlines).trimmingCharacters(in: CharacterSet(charactersIn: "\"'"))
+        }
+        let selectedFont = families.lazy.compactMap { family -> UIFont? in
+            switch family.lowercased() {
+            case "monospace", "ui-monospace": return .monospacedSystemFont(ofSize: scaledSize, weight: weight)
+            case "serif", "ui-serif":
+                let system = UIFont.systemFont(ofSize: scaledSize, weight: weight)
+                return system.fontDescriptor.withDesign(.serif).map { UIFont(descriptor: $0, size: scaledSize) }
+            case "sans-serif", "ui-sans-serif", "system-ui", "-apple-system": return .systemFont(ofSize: scaledSize, weight: weight)
+            default:
+                guard let custom = UIFont(name: family, size: scaledSize) else { return nil }
+                let weighted = custom.fontDescriptor.addingAttributes([.traits: [UIFontDescriptor.TraitKey.weight: weight.rawValue]])
+                var traits = custom.fontDescriptor.symbolicTraits
+                if weight >= .semibold { traits.insert(.traitBold) } else { traits.remove(.traitBold) }
+                let descriptor = weighted.withSymbolicTraits(traits) ?? weighted
+                return UIFont(descriptor: descriptor, size: scaledSize)
+            }
+        }.first
+        var font = selectedFont ?? .systemFont(ofSize: scaledSize, weight: weight)
         if style["fontStyle"] as? String == "italic",
-           let descriptor = font.fontDescriptor.withSymbolicTraits(.traitItalic) {
+           let descriptor = font.fontDescriptor.withSymbolicTraits(font.fontDescriptor.symbolicTraits.union(.traitItalic)) {
             font = UIFont(descriptor: descriptor, size: scaledSize)
         }
         return font
@@ -10502,6 +10604,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 
     func scrollViewDidScroll(_ scrollView: UIScrollView) {
+        // Sticky positioning is a native scroll behavior and must also run
+        // without a JavaScript onScroll subscription, including animations.
+        (scrollView as? CraftNativeScrollView)?.updateStickyHeaders()
         guard let handler = scrollHandlers[ObjectIdentifier(scrollView)] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": scrollEvent(scrollView)])
     }
@@ -10510,12 +10615,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     func scrollViewWillBeginDragging(_ scrollView: UIScrollView) {
         CraftFramePacing.shared.begin(pacingName)
+        (scrollView as? CraftNativeScrollView)?.beginPageDrag()
         guard let handler = scrollBeginHandlers[ObjectIdentifier(scrollView)] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": scrollEvent(scrollView)])
     }
 
     func scrollViewDidEndDragging(_ scrollView: UIScrollView, willDecelerate decelerate: Bool) {
-        if !decelerate { CraftFramePacing.shared.end(pacingName) }
+        if !decelerate { CraftFramePacing.shared.end(pacingName); (scrollView as? CraftNativeScrollView)?.finishPageMotion() }
         guard let handler = scrollEndHandlers[ObjectIdentifier(scrollView)] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": scrollEvent(scrollView)])
     }
@@ -10527,10 +10633,15 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) {
         CraftFramePacing.shared.end(pacingName)
+        (scrollView as? CraftNativeScrollView)?.finishPageMotion()
         guard let handler = scrollMomentumEndHandlers[ObjectIdentifier(scrollView)] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": scrollEvent(scrollView)])
     }
 
+    func scrollViewDidEndScrollingAnimation(_ scrollView: UIScrollView) {
+        (scrollView as? CraftNativeScrollView)?.finishPageMotion()
+    }
+
     private func scrollEvent(_ scrollView: UIScrollView) -> [String: Any] {
         [
             "contentOffset": ["x": scrollView.contentOffset.x, "y": scrollView.contentOffset.y],

package/dist/ios/templates/testing/DriverTests.swift.template

@@ -22,6 +22,7 @@ import Darwin
 ///   tapif <text>          tap it when it is on screen, else carry on (the big timer's "Show the controls")
 ///   tapid <identifier>
 ///   longpressid <identifier> holds a hittable native element to open its edit menu
+///   holdtab <name> [| secs] standard XCTest hold (2–10s, default 6), BEGIN/END timing receipt
 ///   touches <JSON>       timed normalized touch paths in one native dispatch
 ///   tapxy <x> <y>         normalised 0…1 of the screen
 ///   tapexact <label>      a button whose label is exactly this
@@ -381,6 +382,43 @@ final class DriverTests: XCTestCase {
             }
             target.press(forDuration: 1.2)
             note("longpressid \(arg): ok")
+        case "holdtab":
+            let parts = arg.components(separatedBy: "|").map { $0.trimmingCharacters(in: .whitespaces) }
+            guard parts.count <= 2, let name = parts.first, !name.isEmpty,
+                  let duration = parts.count == 2 ? Double(parts[1]) : 6,
+                  duration.isFinite, (2...10).contains(duration) else {
+                check(false, "holdtab needs a tab name and 2–10 seconds")
+                return
+            }
+            guard let button = poll(10, { tabButton(name) }) else {
+                check(false, "holdtab cannot find tab \(name)")
+                return
+            }
+            let frame = button.frame
+            let coordinate = button.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5))
+            let startedAt = Date().timeIntervalSince1970
+            let startedUptime = ProcessInfo.processInfo.systemUptime
+            // BEGIN arms the independent screenshot watcher. XCTest still
+            // performs its normal idle checks before synthesizing the press;
+            // the watcher must wait for that synthesis, not infer touch-down.
+            note("BEGIN holdtab \(name) | \(duration) | \(startedAt)")
+            fflush(nil)
+            coordinate.press(forDuration: duration)
+            let returnedAt = Date().timeIntervalSince1970
+            let returnedUptime = ProcessInfo.processInfo.systemUptime
+            note("END holdtab \(name) | \(returnedAt)")
+            let receipt: [String: Any] = [
+                "tab": name, "requestedSeconds": duration,
+                "input": "XCUICoordinate.press(forDuration:)",
+                "startedAt": startedAt, "returnedAt": returnedAt,
+                "startedUptime": startedUptime, "returnedUptime": returnedUptime,
+                "frame": ["x": frame.minX, "y": frame.minY, "width": frame.width, "height": frame.height],
+                "note": "Call times include XCTest idle checks; during-hold screenshots require an independent synthesis-timed capture.",
+            ]
+            if let data = try? JSONSerialization.data(withJSONObject: receipt, options: [.sortedKeys]) {
+                post("/save?name=holdtab-\(Int(startedUptime * 1000)).json", data)
+            }
+            check(true, "holdtab \(name): standard \(duration)s press returned")
         case "touches":
             do {
                 guard let data = arg.data(using: .utf8),

package/dist/package.d.ts

@@ -83,13 +83,17 @@ export interface PackageConfig {
         applePassword?: string;
         /** Team ID for notarization. Required by `notarytool` alongside `appleId`. */
         teamId?: string;
+        /**
+         * Native Craft provider for a server-backed app. Embeds a separately
+         * identified agent app so AppKit, Accessibility and MenuBarAgent resolve
+         * the GUI process to its own CFBundleExecutable.
+         */
+        nativeRuntimePath?: string;
         /**
          * Extra executables copied into `Contents/MacOS/` beside the app binary.
          *
-         * A server-backed app (a Bun program driving a Craft webview, say) spawns a
-         * helper at runtime; bundle it here so the installed `.app` is
-         * self-contained. Resolve it relative to the running executable — on macOS
-         * the helper lands next to `process.execPath`.
+         * Use nativeRuntimePath for the GUI provider. This option is for non-GUI
+         * command line helpers, resolved beside process.execPath.
          */
         additionalExecutables?: string[];
         /**
@@ -173,6 +177,8 @@ export declare function formatPackagingCommandError(tool: string, code: number |
 export declare function packageApp(config: PackageConfig): Promise<PackageResult[]>;
 export interface MacOSBundleMetadata {
     name: string;
+    /** Actual executable basename when it differs from the app's display name. */
+    executableName?: string;
     version: string;
     bundleId: string;
     /** `CFBundleVersion`. Defaults to `version`. */
@@ -238,6 +244,11 @@ export declare function notarytoolArguments(opts: {
         issuer: string;
     };
 }): string[];
+/**
+ * Helper: Create macOS app bundle
+ */
+/** The native GUI agent's location, shared with desktop launchers. */
+export declare function macOSRuntimeExecutablePath(appBundlePath: string): string;
 export declare function dmgCapacityMegabytes(contentBytes: number): number;
 export declare function dmgCreateArguments(opts: {
     appBundlePath: string;

package/dist/types.d.ts

@@ -1189,9 +1189,7 @@ export interface CraftBridgeAPI {
     menubar?: {
         /** Native visibility requires macOS 27, a direct build and Accessibility.
          * No automatic fallback to width-based hiding is performed. */
-        init(options?: {
-            backend?: 'legacy' | 'nativeVisibility';
-        }): Promise<void>;
+        init(options?: MenubarInitOptions): Promise<void>;
         destroy(): Promise<void>;
         requestPermission(): Promise<void>;
         collapse(): Promise<void>;
@@ -2373,6 +2371,13 @@ export interface CraftTimersAPI {
         signal?: AbortSignal;
     }): Promise<void>;
 }
+/** Native grouping policy. Unselected application icons are always protected. */
+export interface MenubarInitOptions {
+    backend?: 'legacy' | 'nativeVisibility';
+    /** Defaults to true. False accepts native suppression of Apple modules,
+     * including Focus, Now Playing and camera/microphone indicators. */
+    preserveSystemItems?: boolean;
+}
 /** Settled native menu-bar state; private visibility capability is explicit. */
 export interface MenubarState {
     collapsed: boolean;
@@ -2383,6 +2388,7 @@ export interface MenubarState {
     authorized?: boolean;
     busy?: boolean;
     hiddenAppCount?: number;
+    preserveSystemItems?: boolean;
     markerWidth?: number;
-    error?: 'unavailable' | 'permissionRequired' | 'layoutUnavailable' | 'activationFailed' | 'activationTimeout' | null;
+    error?: 'unavailable' | 'permissionRequired' | 'layoutUnavailable' | 'emptyGroup' | 'visibilityMismatch' | 'activationFailed' | 'activationTimeout' | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craft-native",
-  "version": "0.0.304",
+  "version": "0.0.319",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",