feat(folio): device build linking the iosArm64 framework

project.yml selects the Kotlin framework slice by SDK (iosArm64 for
iphoneos, iosSimulatorArm64 for simulator) and links via -framework Shared
on the SDK-conditional search path. New ios-device/test-ios-device recipes
mirror ios/test-ios, signing the Debug-iphoneos build with the .env API key.

examples/folio/app/iosApp/project.yml

@@ -19,25 +19,32 @@ targets:
     sources:
       - iosApp
     dependencies:
-      - framework: ../shared/build/bin/iosSimulatorArm64/debugFramework/Shared.framework
-        embed: false
       - sdk: libsqlite3.tbd
     settings:
       base:
         PRODUCT_BUNDLE_IDENTIFIER: app.folio
         PRODUCT_NAME: iosApp
         INFOPLIST_FILE: iosApp/Info.plist
+        # The Kotlin framework slice differs by SDK: device builds link the
+        # iosArm64 framework, simulator builds the iosSimulatorArm64 one. The
+        # search path and the prebuild gradle task both follow this variable.
+        KOTLIN_FRAMEWORK_DIR[sdk=iphoneos*]: iosArm64
+        KOTLIN_FRAMEWORK_DIR[sdk=iphonesimulator*]: iosSimulatorArm64
         FRAMEWORK_SEARCH_PATHS:
           - $(SRCROOT)/../shared/build/bin/$(KOTLIN_FRAMEWORK_DIR)/debugFramework
         OTHER_LDFLAGS:
           - -ObjC
-        KOTLIN_FRAMEWORK_DIR: iosSimulatorArm64
+          - -framework
+          - Shared
     preBuildScripts:
       - name: Build Kotlin framework
         script: |
           cd "$SRCROOT/../.."
+          if [[ "$PLATFORM_NAME" == iphoneos ]]; then
+            task=linkDebugFrameworkIosArm64
+          else
+            task=linkDebugFrameworkIosSimulatorArm64
+          fi
           ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}" \
-            ./gradlew :app:shared:linkDebugFrameworkIosSimulatorArm64
-        outputFiles:
-          - $(SRCROOT)/../shared/build/bin/iosSimulatorArm64/debugFramework/Shared.framework/Shared
+            ./gradlew :app:shared:$task
         basedOnDependencyAnalysis: false

examples/folio/justfile

@@ -8,6 +8,7 @@ seed       := env_var_or_default("SEED", "0")
 output     := env_var_or_default("OUTPUT", justfile_directory() / "sanderling" / "runs")
 ios_device := env_var_or_default("IOS_DEVICE", "iPhone 17 Pro")
 ios_app    := justfile_directory() / "app" / "iosApp" / "build" / "Build" / "Products" / "Debug-iphonesimulator" / "iosApp.app"
+ios_app_device := justfile_directory() / "app" / "iosApp" / "build" / "Build" / "Products" / "Debug-iphoneos" / "iosApp.app"
 
 default:
     @just --list
@@ -122,6 +123,25 @@ ios:
     xcrun simctl install booted "{{ios_app}}"
     xcrun simctl launch booted app.folio
 
+# Build the folio app for a connected physical iOS device (signed via .env creds).
+# Signing reads ASC_API_* and DEVELOPMENT_TEAM/SANDERLING_IOS_TEAM from .env;
+# sanderling installs the build on the device per run via devicectl.
+ios-device:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    export ANDROID_HOME="$(just _android-home)"
+    just ios-gen
+    xcodebuild -project app/iosApp/iosApp.xcodeproj -scheme iosApp \
+      -destination 'generic/platform=iOS' \
+      -derivedDataPath app/iosApp/build \
+      -allowProvisioningUpdates \
+      -authenticationKeyPath "$ASC_API_KEY_PATH" \
+      -authenticationKeyID "$ASC_API_KEY_ID" \
+      -authenticationKeyIssuerID "$ASC_API_ISSUER_ID" \
+      CODE_SIGN_STYLE=Automatic \
+      DEVELOPMENT_TEAM="${SANDERLING_IOS_TEAM:-${DEVELOPMENT_TEAM:-}}" \
+      build | tail -5
+
 # Run 'sanderling test' against the folio app. Uses a connected device if one is
 # online; otherwise boots AVD=<name> when provided, or auto-boots a bootable AVD.
 # Depends on install so the run always fuzzes the current build, matching
@@ -173,3 +193,20 @@ test-ios:
       --duration "{{duration}}" \
       --seed "{{seed}}" \
       --output "{{output}}"
+
+# Requires App Store Connect signing creds in .env and IOS_DEVICE set to the
+# connected device's name (or UDID / CoreDevice id).
+# Build + install + run sanderling spec on a connected physical iOS device.
+test-ios-device:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    just ios-device
+    "{{sanderling}}" test \
+      --platform ios \
+      --spec "{{justfile_directory()}}/sanderling/spec.ts" \
+      --bundle-id app.folio \
+      --ios-app-path "{{ios_app_device}}" \
+      --ios-device "{{ios_device}}" \
+      --duration "{{duration}}" \
+      --seed "{{seed}}" \
+      --output "{{output}}"