craft-native 0.0.487 → 0.0.491

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

@@ -149,6 +149,55 @@ private fun craftNativeBoolean(value: Any?, fallback: Boolean = false): Boolean
 
 private fun craftNativeInt(value: Any?, fallback: Int): Int = (value as? Number)?.toInt() ?: fallback
 
+/**
+ * Where a field's text and hint begin, vertically.
+ *
+ * The platform's `Widget.EditText` carries `gravity = center_vertical`, and
+ * nothing between it and this app overrides it: `Theme.CraftApp` inherits
+ * `Theme.Material3.DayNight.NoActionBar`, no Material3 theme binds
+ * `android:editTextStyle`, and AppCompat binds it to
+ * `Widget.AppCompat.EditText`, whose chain reaches `android:Widget.EditText`
+ * without touching gravity. A single-line field is never taller than its
+ * text, so the centring cannot show; a field given a `minHeight` drew its
+ * first line — and its hint — halfway down the box, where iOS and the web
+ * both start at the top (#502).
+ *
+ * Only the vertical bits are replaced. The horizontal ones are left exactly
+ * as they were, because `textAlign` resolves through `textAlignment`, whose
+ * default of `TEXT_ALIGNMENT_INHERIT` can still fall back to this gravity.
+ */
+private fun craftNativeVerticalGravity(current: Int, multiline: Boolean): Int =
+    (current and Gravity.VERTICAL_GRAVITY_MASK.inv()) or (if (multiline) Gravity.TOP else Gravity.CENTER_VERTICAL)
+
+
+/**
+ * A scroll event's geometry in density-independent units.
+ *
+ * UIKit reports `contentOffset`, `contentSize` and `layoutMeasurement` in
+ * points, and this host's own `emitLayoutEvent` already divides a View's
+ * pixels by the display density. These three were the exception: they shipped
+ * raw pixels, so the same scroll handler saw values three times larger on a
+ * 3x Android screen than on iOS — and larger than the `onLayout` bounds the
+ * same screen reports, which is the comparison infinite-scroll code makes.
+ */
+private fun craftNativeScrollMetrics(
+    offsetX: Int,
+    offsetY: Int,
+    contentWidth: Int,
+    contentHeight: Int,
+    viewportWidth: Int,
+    viewportHeight: Int,
+    density: Double,
+): JSONObject {
+    // A density of zero would be a broken DisplayMetrics; report pixels rather
+    // than NaN, which JSON cannot carry and a handler cannot compare.
+    val scale = if (density.isFinite() && density > 0.0) density else 1.0
+    return JSONObject()
+        .put("contentOffset", JSONObject().put("x", offsetX / scale).put("y", offsetY / scale))
+        .put("contentSize", JSONObject().put("width", contentWidth / scale).put("height", contentHeight / scale))
+        .put("layoutMeasurement", JSONObject().put("width", viewportWidth / scale).put("height", viewportHeight / scale))
+}
+
 private fun craftNativePickerValue(value: Any?): String? = when (value) {
     is String -> value
     is Number -> value.toDouble().takeIf { it.isFinite() }?.let { value.toString() }
@@ -391,6 +440,16 @@ private object CraftNativeSkewTransforms {
 /** A DOM-free SVG surface for the geometry emitted by the shared STX native protocol. */
 /** Local native chart selection: no JS events are needed while scrubbing. */
 private class CraftNativeChartInspection(private val view: View) {
+    companion object {
+        /** The one chart with a reading pinned open, if any. */
+        private var pinned: java.lang.ref.WeakReference<CraftNativeChartInspection>? = null
+        /** A touch that starts off the pinned chart closes its reading; the touch still lands where it was aimed. */
+        fun touchBegan(event: MotionEvent) {
+            if (event.actionMasked != MotionEvent.ACTION_DOWN) return
+            val open = pinned?.get() ?: return
+            if (!open.contains(event.rawX, event.rawY)) open.dismiss()
+        }
+    }
     private var fingerprint = ""
     private var title = ""
     private var points = emptyList<JSONObject>()
@@ -399,8 +458,9 @@ private class CraftNativeChartInspection(private val view: View) {
     private var startY = 0f
     private var dragging = false
     private var abandoned = false
+    private var holding = false
     private val slop = android.view.ViewConfiguration.get(view.context).scaledTouchSlop
-    private val hold = Runnable { if (!abandoned) selectAt(startX) }
+    private val hold = Runnable { if (!abandoned) { holding = true; selectAt(startX) } }
     val enabled: Boolean get() = points.isNotEmpty()
     private val density get() = view.resources.displayMetrics.density
     private fun dp(value: Float) = value * density
@@ -414,7 +474,7 @@ private class CraftNativeChartInspection(private val view: View) {
             val x = it.optDouble("x", Double.NaN)
             x.isFinite() && x in 0.0..1.0 && it.opt("label") is String
         }
-        selected = -1
+        dismiss()
         view.isFocusable = enabled
         view.invalidate()
     }
@@ -431,16 +491,31 @@ private class CraftNativeChartInspection(private val view: View) {
         view.sendAccessibilityEvent(android.view.accessibility.AccessibilityEvent.TYPE_VIEW_SELECTED)
         view.invalidate()
     }
-    private fun selectAt(x: Float) {
-        if (view.width <= 0) return
+    private fun nearest(x: Float): Int? {
+        if (view.width <= 0) return null
         val fraction = (x / view.width).coerceIn(0f, 1f)
-        points.indices.minByOrNull { kotlin.math.abs(points[it].optDouble("x") - fraction) }?.let { select(it) }
+        return points.indices.minByOrNull { kotlin.math.abs(points[it].optDouble("x") - fraction) }
+    }
+    private fun selectAt(x: Float) { nearest(x)?.let { select(it); pinned = java.lang.ref.WeakReference(this) } }
+    /** Puts the reading away. Returns whether one was showing. */
+    fun dismiss(): Boolean {
+        if (pinned?.get() === this) pinned = null
+        if (selected < 0) return false
+        selected = -1
+        view.invalidate()
+        return true
+    }
+    /** A tap pins the reading under it; tapping the pinned reading again puts it away. */
+    private fun tapAt(x: Float) { if (nearest(x) == selected) dismiss() else selectAt(x) }
+    private fun contains(rawX: Float, rawY: Float): Boolean {
+        val origin = IntArray(2).also { view.getLocationOnScreen(it) }
+        return rawX >= origin[0] && rawX < origin[0] + view.width && rawY >= origin[1] && rawY < origin[1] + view.height
     }
     fun touch(event: MotionEvent): Boolean {
         if (!enabled) return false
         when (event.actionMasked) {
             MotionEvent.ACTION_DOWN -> {
-                startX = event.x; startY = event.y; dragging = false; abandoned = false
+                startX = event.x; startY = event.y; dragging = false; abandoned = false; holding = false
                 view.postDelayed(hold, 250)
             }
             MotionEvent.ACTION_MOVE -> {
@@ -455,17 +530,19 @@ private class CraftNativeChartInspection(private val view: View) {
             }
             MotionEvent.ACTION_UP -> {
                 view.removeCallbacks(hold)
-                if (!abandoned) { view.performClick(); selectAt(event.x) }
+                // A drag or a hold reads the chart only while the finger is down.
+                if (dragging || holding) dismiss()
+                else if (!abandoned) { view.performClick(); tapAt(event.x) }
                 view.parent?.requestDisallowInterceptTouchEvent(false)
             }
             MotionEvent.ACTION_CANCEL -> {
-                view.removeCallbacks(hold); abandoned = true; selected = -1
-                view.parent?.requestDisallowInterceptTouchEvent(false); view.invalidate()
+                view.removeCallbacks(hold); abandoned = true; dismiss()
+                view.parent?.requestDisallowInterceptTouchEvent(false)
             }
         }
         return !abandoned
     }
-    fun detach() { view.removeCallbacks(hold); selected = -1 }
+    fun detach() { view.removeCallbacks(hold); dismiss() }
     fun accessibility(info: android.view.accessibility.AccessibilityNodeInfo) {
         if (!enabled) return
         info.className = "android.widget.SeekBar"
@@ -480,7 +557,7 @@ private class CraftNativeChartInspection(private val view: View) {
         when (action) {
             android.view.accessibility.AccessibilityNodeInfo.ACTION_SCROLL_FORWARD -> select(if (selected < 0) 0 else selected + 1)
             android.view.accessibility.AccessibilityNodeInfo.ACTION_SCROLL_BACKWARD -> select(if (selected < 0) points.lastIndex else selected - 1)
-            android.view.accessibility.AccessibilityNodeInfo.ACTION_DISMISS -> { selected = -1; view.invalidate() }
+            android.view.accessibility.AccessibilityNodeInfo.ACTION_DISMISS -> dismiss()
             else -> return false
         }
         return true
@@ -1186,6 +1263,7 @@ internal object CraftNativePointers {
     fun ownsTouch(view: View): Boolean = route(view).firstOrNull() !in setOf("none", "box-none")
 
     fun dispatch(view: View, event: MotionEvent, native: (MotionEvent) -> Boolean): Boolean {
+        CraftNativeChartInspection.touchBegan(event)
         val state = states.getOrPut(view) { State() }
         val route = route(view)
         if (event.actionMasked == MotionEvent.ACTION_CANCEL) {
@@ -4827,6 +4905,17 @@ class MainActivity : AppCompatActivity() {
         val chunks = CraftNativeChunks()
         /** A `requestAnimationFrame` is waiting for the next frame. */
         var frameRequested = false
+        /**
+         * Choreographer's frame time at this screen's first delivered frame.
+         *
+         * `requestAnimationFrame` hands its callback a `DOMHighResTimeStamp`:
+         * milliseconds measured from the context's own origin, so the first one
+         * is near zero. `frameTimeNanos` counts from boot, which on a device up
+         * for a month is nine digits of offset, and UIKit already subtracts its
+         * own origin (`frameTimeOrigin` in `CraftNativeScreen.swift`). Without
+         * this the same shared animation code sees two different epochs.
+         */
+        var frameTimeOrigin: Long? = null
         /** The screen's timers (`setTimeout`), kept by the host. */
         val timers = mutableMapOf<Int, Runnable>()
         val drafts = mutableMapOf<String, String>()
@@ -5182,9 +5271,51 @@ class MainActivity : AppCompatActivity() {
         }
         val launch = initialDeepLink?.let { routes.appPath(it.toString(), urlSchemes) }
         if (launch != null) deliveredInitialDeepLink = true
-        selectTab(routes.tabFor(launch ?: routes.initialPath)?.let { routes.tabs.indexOf(it) } ?: 0)
+        // A launch link is deliberately not gated. Suppressing one would have
+        // to decide whether it is dropped or replayed after signing in, and
+        // UIKit does not gate them either — its gate resolves the start path
+        // while links are still queued for replay. Same gap, both hosts, and
+        // better as its own change than as a silent asymmetry here.
+        val start = if (launch != null) launch else gatedStartPath(routes.initialPath)
+        selectTab(routes.tabFor(start)?.let { routes.tabs.indexOf(it) } ?: 0)
         if (launch != null && routes.tabFor(launch) == null) navigateOpen(launch, fromLink = true)
-        else if (routes.tabs.isEmpty() && screens.isEmpty()) navigateOpen(routes.initialPath)
+        else if (routes.tabs.isEmpty() && screens.isEmpty()) navigateOpen(start)
+    }
+
+    /**
+     * Send a signed-out launch to the gate's redirect before any screen is
+     * built (#499).
+     *
+     * The app script cannot do this. `openScreen` returns as soon as it has an
+     * isolate and evaluates the script later on an executor, so opening the
+     * app script before the first screen only creates its isolate first — the
+     * two then evaluate with nothing ordering them, and whether the gate runs
+     * before the first screen paints is a race. On a launch that follows an
+     * expired session rather than a sign-out, losing that race paints the
+     * previous session's kept snapshot.
+     *
+     * UIKit loses the same race by construction rather than by chance, which
+     * is where this was reported; the fix is the same on both and so is the
+     * config.
+     */
+    private fun gatedStartPath(start: String): String {
+        val gate = config.optJSONObject("nativeGate") ?: return start
+        val redirect = gate.optString("redirect").takeIf { it.isNotBlank() } ?: return start
+        val listed = gate.optJSONArray("publicPaths")
+        val allowed = (0 until (listed?.length() ?: 0)).mapNotNull { index ->
+            listed?.optString(index)?.takeIf { it.isNotBlank() }
+        }
+        if (CraftNativePrelude.gateAdmits(start, allowed)) return start
+        val key = gate.optString("token").ifBlank { CraftNativePrelude.sessionTokenKey(config) }
+        if (!stores.secureValue(key).isNullOrEmpty()) return start
+        // A redirect nothing can draw would trade a private screen for a blank
+        // one. Say so and leave the start path alone.
+        if (routes.match(redirect) == null) {
+            Log.w(TAG, "nativeGate redirect $redirect has no native screen; the gate did not run")
+            return start
+        }
+        Log.i(TAG, "no sign-in under $key: starting on $redirect instead of $start")
+        return redirect
     }
 
     private fun installChrome() {
@@ -5814,7 +5945,11 @@ class MainActivity : AppCompatActivity() {
             if (!screen.active || !screen.frameRequested) return@postFrameCallback
             if (visibleScreen !== screen && !screen.headless) return@postFrameCallback
             screen.frameRequested = false
-            send(screen, "FRAME_FIRE", JSONObject().put("time", frameTime / 1_000_000.0))
+            // Milliseconds from this screen's first frame, not from boot: see
+            // Screen.frameTimeOrigin. Nanoseconds are subtracted before the
+            // division so the difference keeps full resolution.
+            val origin = screen.frameTimeOrigin ?: frameTime.also { screen.frameTimeOrigin = it }
+            send(screen, "FRAME_FIRE", JSONObject().put("time", (frameTime - origin) / 1_000_000.0))
         }
     }
 
@@ -6575,6 +6710,8 @@ class MainActivity : AppCompatActivity() {
                 if (isSingleLine == multiline) isSingleLine = !multiline
                 val wantedLines = if (multiline) craftNativeInt(props.opt("numberOfLines"), Int.MAX_VALUE).coerceAtLeast(1) else 1
                 if (maxLines != wantedLines) maxLines = wantedLines
+                val wantedGravity = craftNativeVerticalGravity(gravity, multiline)
+                if (gravity != wantedGravity) gravity = wantedGravity
                 isEnabled = craftNativeBoolean(props.opt("editable"), true)
                 configureTextStyle(this, style)
                 // The style's padding is where the text starts, as on iOS and
@@ -7136,10 +7273,15 @@ class MainActivity : AppCompatActivity() {
                     onScroll = { scrollX, scrollY ->
                         screen.scrollHandlers[nativeScroll]?.let { current ->
                             val contentView = nativeScroll.content
-                            send(screen, "EVENT", JSONObject().put("handlerName", current).put("nativeEvent", JSONObject()
-                                .put("contentOffset", JSONObject().put("x", scrollX).put("y", scrollY))
-                                .put("contentSize", JSONObject().put("width", contentView.width).put("height", contentView.height))
-                                .put("layoutMeasurement", JSONObject().put("width", nativeScroll.width).put("height", nativeScroll.height))))
+                            // Density-independent, like `emitLayoutEvent` and
+                            // like UIKit's points: see craftNativeScrollMetrics.
+                            val scale = resources.displayMetrics.density.toDouble()
+                            send(screen, "EVENT", JSONObject().put("handlerName", current).put("nativeEvent", craftNativeScrollMetrics(
+                                offsetX = scrollX, offsetY = scrollY,
+                                contentWidth = contentView.width, contentHeight = contentView.height,
+                                viewportWidth = nativeScroll.width, viewportHeight = nativeScroll.height,
+                                density = scale,
+                            )))
                         }
                     },
                     onBeginDrag = {
@@ -7476,16 +7618,12 @@ class MainActivity : AppCompatActivity() {
             ?: craftNativeOptionalString(props.opt("resizeMode")).orEmpty()
     }
 
-    private fun flatListScrollEvent(list: CraftNativeFlatList): JSONObject = JSONObject()
-        .put("contentOffset", JSONObject()
-            .put("x", list.computeHorizontalScrollOffset())
-            .put("y", list.computeVerticalScrollOffset()))
-        .put("contentSize", JSONObject()
-            .put("width", list.computeHorizontalScrollRange())
-            .put("height", list.computeVerticalScrollRange()))
-        .put("layoutMeasurement", JSONObject()
-            .put("width", list.width)
-            .put("height", list.height))
+    private fun flatListScrollEvent(list: CraftNativeFlatList): JSONObject = craftNativeScrollMetrics(
+        offsetX = list.computeHorizontalScrollOffset(), offsetY = list.computeVerticalScrollOffset(),
+        contentWidth = list.computeHorizontalScrollRange(), contentHeight = list.computeVerticalScrollRange(),
+        viewportWidth = list.width, viewportHeight = list.height,
+        density = resources.displayMetrics.density.toDouble(),
+    )
 
     private fun reconcileChildren(
         screen: Screen,

package/dist/cli.js

@@ -1025,6 +1025,9 @@ async function detachDiskImage(mount, options = {}) {
     await wait(attempt * 2000);
   }
 }
+function attachedDevice(attachOutput) {
+  return attachOutput.match(/^(\/dev\/disk\d+)(?=\s)/m)?.[1] ?? null;
+}
 async function createDiskImage(opts) {
   if (!/^[^/:\n]{1,27}$/.test(opts.volumeName))
     return { success: false, error: `Invalid DMG volume name "${opts.volumeName}"; must be 1..27 chars without /, :, or newline` };
@@ -1068,7 +1071,7 @@ async function createDiskImage(opts) {
     phase = "layout";
     writeInstallerLayout(mount, opts.volumeName, bundleName);
     phase = "detach";
-    const detached = await detachDiskImage(mount);
+    const detached = await detachDiskImage(attachedDevice(attachment) ?? mount);
     if (!detached.success) {
       detachAttempts = detached.attempts;
       throw new Error(detached.error);
@@ -1083,7 +1086,7 @@ async function createDiskImage(opts) {
 Disk image lifecycle: ${JSON.stringify({ phase, image: writable, mount, attachment, detachAttempts })}` };
   } finally {
     if (mounted)
-      await runTool("hdiutil", ["detach", mount, "-force"]);
+      await runTool("hdiutil", ["detach", attachedDevice(attachment) ?? mount, "-force"]);
     removeTempDir(scratch);
   }
 }
@@ -3243,7 +3246,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.487";
+var version = "0.0.491";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -376,7 +376,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.487";
+var version = "0.0.491";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -1393,6 +1393,9 @@ async function detachDiskImage(mount, options = {}) {
     await wait(attempt * 2000);
   }
 }
+function attachedDevice(attachOutput) {
+  return attachOutput.match(/^(\/dev\/disk\d+)(?=\s)/m)?.[1] ?? null;
+}
 async function createDiskImage(opts) {
   if (!/^[^/:\n]{1,27}$/.test(opts.volumeName))
     return { success: false, error: `Invalid DMG volume name "${opts.volumeName}"; must be 1..27 chars without /, :, or newline` };
@@ -1436,7 +1439,7 @@ async function createDiskImage(opts) {
     phase = "layout";
     writeInstallerLayout(mount, opts.volumeName, bundleName);
     phase = "detach";
-    const detached = await detachDiskImage(mount);
+    const detached = await detachDiskImage(attachedDevice(attachment) ?? mount);
     if (!detached.success) {
       detachAttempts = detached.attempts;
       throw new Error(detached.error);
@@ -1451,7 +1454,7 @@ async function createDiskImage(opts) {
 Disk image lifecycle: ${JSON.stringify({ phase, image: writable, mount, attachment, detachAttempts })}` };
   } finally {
     if (mounted)
-      await runTool("hdiutil", ["detach", mount, "-force"]);
+      await runTool("hdiutil", ["detach", attachedDevice(attachment) ?? mount, "-force"]);
     removeTempDir(scratch);
   }
 }

package/dist/index.js

@@ -117,7 +117,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.487";
+var version = "0.0.491";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -1149,6 +1149,9 @@ async function detachDiskImage(mount, options = {}) {
     await wait(attempt * 2000);
   }
 }
+function attachedDevice(attachOutput) {
+  return attachOutput.match(/^(\/dev\/disk\d+)(?=\s)/m)?.[1] ?? null;
+}
 async function createDiskImage(opts) {
   if (!/^[^/:\n]{1,27}$/.test(opts.volumeName))
     return { success: false, error: `Invalid DMG volume name "${opts.volumeName}"; must be 1..27 chars without /, :, or newline` };
@@ -1192,7 +1195,7 @@ async function createDiskImage(opts) {
     phase = "layout";
     writeInstallerLayout(mount, opts.volumeName, bundleName);
     phase = "detach";
-    const detached = await detachDiskImage(mount);
+    const detached = await detachDiskImage(attachedDevice(attachment) ?? mount);
     if (!detached.success) {
       detachAttempts = detached.attempts;
       throw new Error(detached.error);
@@ -1207,7 +1210,7 @@ async function createDiskImage(opts) {
 Disk image lifecycle: ${JSON.stringify({ phase, image: writable, mount, attachment, detachAttempts })}` };
   } finally {
     if (mounted)
-      await runTool("hdiutil", ["detach", mount, "-force"]);
+      await runTool("hdiutil", ["detach", attachedDevice(attachment) ?? mount, "-force"]);
     removeTempDir(scratch);
   }
 }

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

@@ -317,6 +317,28 @@ export interface CraftConfig {
      * `craftsession` event on the page.
      */
     sessionTokenKey?: string;
+    /**
+     * Which screens a signed-out launch may start on.
+     *
+     * The shell resolves this while it is deciding the start path, before any
+     * screen is built. An app script cannot do the same job: it is started from
+     * the first frame's completion block, so by the time it can read a token the
+     * signed-in screen it would have prevented has already been painted — with
+     * the previous session's kept snapshot in it when the launch follows an
+     * expired token rather than a sign-out.
+     *
+     * ```ts
+     * nativeGate: {
+     *   publicPaths: ['/m/login', '/m/signup', '/m/store'],
+     *   redirect: '/m/login',
+     * }
+     * ```
+     *
+     * `publicPaths` admits a listed path and anything under it, so `/m/store`
+     * covers `/m/store/42` and not `/m/storefront`. `token` defaults to
+     * `sessionTokenKey`, the item `craft.session` already follows.
+     */
+    nativeGate?: NativeGate;
     /**
      * Crash and error reporting to bughq (CraftCrashReporter.swift): crashes
      * and hangs (signal handlers, NSException, MetricKit), uncaught JavaScript
@@ -325,6 +347,25 @@ export interface CraftConfig {
      */
     crashReporting?: CraftCrashReporting;
 }
+/**
+ * An auth gate the shell applies while resolving the start path.
+ *
+ * See `CraftConfig.nativeGate`. The allowlist is static data in the apps that
+ * need this, so emitting it into the config costs nothing at runtime.
+ */
+export interface NativeGate {
+    /**
+     * Paths a signed-out launch may start on, each admitting what sits under it.
+     *
+     * Not `public`: that is a Swift keyword, and remapping it would make the
+     * stored key differ from the property the host decodes it into.
+     */
+    publicPaths?: string[];
+    /** Where a signed-out launch starts instead. Must itself be public. */
+    redirect: string;
+    /** The secure-storage key holding the sign-in. Defaults to `sessionTokenKey`. */
+    token?: string;
+}
 export interface CraftCrashReporting {
     /** The bughq project's public ingest key. Ships in the app; it is not a secret. */
     key: string;
@@ -362,7 +403,7 @@ export declare function usesNativeBundle(config: Pick<CraftConfig, 'renderer' |
  */
 export declare function nativeStartPath(config: Pick<CraftConfig, 'devServerURL'>): string;
 /** What is wrong with a config's hybrid and tab settings, one sentence each. */
-export declare function hybridConfigProblems(config: Pick<CraftConfig, 'renderer' | 'nativeScreens' | 'nativeScreenConstraints' | 'tabs' | 'shareStorage' | 'devServerURL' | 'nativeApp' | 'nativeScriptThread' | 'notificationCategories'>): string[];
+export declare function hybridConfigProblems(config: Pick<CraftConfig, 'renderer' | 'nativeScreens' | 'nativeScreenConstraints' | 'tabs' | 'shareStorage' | 'devServerURL' | 'nativeApp' | 'nativeScriptThread' | 'notificationCategories' | 'nativeGate'>): string[];
 /**
  * The builder installs a directory of route bundles (stx's `routesDir`) as
  * well as the one-file bundle, and the app runs each screen from its own

package/dist/ios/src/index.js

@@ -740,6 +740,21 @@ function hybridConfigProblems(config) {
     if (!matchNativePath(config.nativeScreens, start, config.nativeScreenConstraints))
       problems.push(`The start path "${start}" (from devServerURL) is not a nativeScreens path; with renderer: "native" the app must start on a native screen.`);
   }
+  const gate = config.nativeGate;
+  if (gate !== undefined) {
+    if (typeof gate.redirect !== "string" || normalizeNativePath(gate.redirect) !== gate.redirect)
+      problems.push(`nativeGate.redirect "${String(gate.redirect)}" must be an absolute path with no query, hash or trailing slash.`);
+    else if (hasNativeRoutes(config) && !matchNativePath(config.nativeScreens, gate.redirect, config.nativeScreenConstraints))
+      problems.push(`nativeGate.redirect "${gate.redirect}" is not a nativeScreens path; a signed-out launch would have nothing to show.`);
+    for (const path of gate.publicPaths ?? []) {
+      if (typeof path !== "string" || normalizeNativePath(path) !== path)
+        problems.push(`nativeGate.publicPaths "${String(path)}" must be an absolute path with no query, hash or trailing slash.`);
+    }
+    if (typeof gate.redirect === "string" && !(gate.publicPaths ?? []).some((path) => gate.redirect === path || gate.redirect.startsWith(`${path}/`)))
+      problems.push(`nativeGate.redirect "${gate.redirect}" must also be listed in nativeGate.publicPaths.`);
+    if (gate.token !== undefined && (typeof gate.token !== "string" || !gate.token))
+      problems.push("nativeGate.token must be the secure-storage key the sign-in lives under.");
+  }
   if (config.nativeApp !== undefined) {
     if (typeof config.nativeApp !== "string" || !/^[A-Za-z_$][\w$-]*$/.test(config.nativeApp))
       problems.push(`nativeApp "${String(config.nativeApp)}" must be a route name from the native bundle.`);

package/dist/ios/templates/CraftApp.swift

@@ -2046,6 +2046,9 @@ struct CraftConfig: Codable {
     /// (`auth.token` unless set): `craft.session` follows it, and a change of
     /// it is `SESSION_CHANGED` on every screen (CraftSession).
     var sessionTokenKey: String? = nil
+    /// Which screens a signed-out launch may start on, resolved before the
+    /// first frame is built (CraftHybrid.configure).
+    var nativeGate: NativeGate? = nil
     /// The bundle route of the app script: a screen-less script that runs for
     /// the app's whole life and hears the app's events (CraftHybrid.swift).
     var nativeApp: String? = nil
@@ -2057,6 +2060,33 @@ struct CraftConfig: Codable {
     /// unless the config names a project key.
     var crashReporting: CrashReporting? = nil
 
+    /// An auth gate the shell applies while resolving the start path.
+    ///
+    /// An app script cannot do this. It is started from the first frame's
+    /// `CATransaction` completion block, so by the time it can read a token
+    /// the signed-in screen it would have prevented is already on screen —
+    /// with the previous session's kept snapshot in it when the launch
+    /// follows an expired token rather than a sign-out (#499). The check has
+    /// to belong to whoever decides the start path, and that is the shell.
+    struct NativeGate: Codable {
+        /// Paths that may be shown without a sign-in. A path is public when
+        /// it is listed, or when it sits under a listed one: `/m/store`
+        /// admits `/m/store/42` and not `/m/storefront`.
+        ///
+        /// Spelled `publicPaths` rather than `public` in the stored config
+        /// too. `public` is a Swift keyword, and remapping it through
+        /// `CodingKeys` would make the property name and the stored key
+        /// differ — which is exactly what the Zig conformance mirror checks,
+        /// and a divergence worth not having for the sake of one word.
+        var publicPaths: [String]? = nil
+        /// Where a signed-out launch starts instead.
+        var redirect: String? = nil
+        /// The secure-storage key holding the sign-in. Defaults to
+        /// `sessionTokenKey`, which is the same item `craft.session` follows,
+        /// so an app that already declares one need not repeat it.
+        var token: String? = nil
+    }
+
     struct Tab: Codable {
         var id: String
         var title: String

package/dist/ios/templates/CraftHybrid.swift

@@ -425,6 +425,7 @@ final class CraftHybrid: NSObject {
                 : "[craft hybrid] nativeScreens are set but dist/native-screen.js is missing; the app has no screens to show")
         }
         isEnabled = wanted && Self.hasBundle
+        applyGate(config)
         if isEnabled, !hasWeb, routes.match(startPath) == nil {
             // No web view to show it in: the first tab a screen draws.
             let fallback = (config.tabs ?? []).map(\.id).first { routes.match($0) != nil }
@@ -458,6 +459,54 @@ final class CraftHybrid: NSObject {
         DispatchQueue.main.asyncAfter(deadline: .now() + 1.5) { self.startAppScript() }
     }
 
+    /// Whether `path` may be shown to someone who is not signed in.
+    ///
+    /// Listed, or under something listed: `/m/store` admits `/m/store/42` and
+    /// not `/m/storefront`. Prefixes are compared with the separator attached
+    /// so a listed path cannot admit a sibling that merely starts with its
+    /// letters.
+    static func gateAdmits(_ path: String, public allowed: [String]) -> Bool {
+        allowed.contains { entry in
+            var listed = entry
+            while listed.count > 1, listed.hasSuffix("/") { listed.removeLast() }
+            guard !listed.isEmpty else { return false }
+            if path == listed { return true }
+            // "/" is the root path, not a prefix of everything. Reading it as
+            // one would admit every path, which is a gate that is not a gate.
+            guard listed != "/" else { return false }
+            return path.hasPrefix(listed + "/")
+        }
+    }
+
+    /// Send a signed-out launch to the gate's redirect before anything is built.
+    ///
+    /// This runs while `startPath` is still being resolved, which is the
+    /// whole point: the app script that would otherwise do it does not start
+    /// until the first frame has been committed, so it can only push sign-in
+    /// on top of a screen that has already been drawn with the previous
+    /// session's data in it (#499).
+    ///
+    /// The Keychain read is synchronous and can cost 100-900ms cold. It is
+    /// not an extra read: every signed-in screen reads this same item when it
+    /// opens, and `CraftKeychain` caches it, so the gate moves the app's first
+    /// read earlier rather than adding one. Only apps that declare a gate pay
+    /// it at all.
+    private func applyGate(_ config: CraftConfig) {
+        guard let gate = config.nativeGate, let redirect = gate.redirect, !redirect.isEmpty else { return }
+        guard !Self.gateAdmits(startPath, public: gate.publicPaths ?? []) else { return }
+        let key = gate.token ?? config.sessionTokenKey ?? "auth.token"
+        guard (CraftNativeActions.webSecureValue(forKey: key) ?? "").isEmpty else { return }
+        // A redirect nothing can draw would trade a private screen for a
+        // blank one. Say so and leave the start path alone; the fallback
+        // below then treats it as any other unroutable start.
+        if isEnabled, !hasWeb, routes.match(redirect) == nil {
+            NSLog("[craft hybrid] nativeGate redirect %@ has no native screen; the gate did not run", redirect)
+            return
+        }
+        NSLog("[craft hybrid] no sign-in under %@: starting on %@ instead of %@", key, redirect, startPath)
+        startPath = redirect
+    }
+
     /// A silent push or a background refresh is waiting for the app script,
     /// with iOS's clock running: it starts now rather than after a frame,
     /// which a launch in the background never draws.

package/dist/ios/templates/CraftNativeActions.swift

@@ -2001,7 +2001,15 @@ enum CraftSnapshots {
             }
             lock.unlock()
             DispatchQueue.main.async {
-                if ok { NotificationCenter.default.post(name: changed, object: nil, userInfo: ["name": name]) }
+                // Posted whether or not the write landed. A screen displays its
+                // checkpoint optimistically, and this notification carries only
+                // the name, so a reader answers it by calling `read` — which
+                // after a failure finds the previous value, because `pending`
+                // was cleared above and the cache was only refilled on success.
+                // Posting only on success left a failed checkpoint on screen as
+                // though it had been kept; Android already restores it
+                // (`changed("snapshots", name, if (ok) json else previous, null)`).
+                NotificationCenter.default.post(name: changed, object: nil, userInfo: ["name": name])
                 completion?(ok)
             }
         }