Duet Tutorial 2: One Behavior, Two Apps

# SKIE: the Swift-friendly projection of the Kotlin/Native framework — sealed
# hierarchies as enums, StateFlow as an async sequence.
skie = "0.10.14"

skie = { id = "co.touchlab.skie", version.ref = "skie" }

  // The Apple framework's Swift projection, applied by :apple-umbrella.
  alias(libs.plugins.skie) apply false

// The Apple boundary: one Kotlin/Native framework over the kernel and every
// feature module, consumed by the iOS app's shells package and by the
// boundary replay suite, both through scripts/assemble_kit.sh.
include(":apple-umbrella")

kotlin {
  jvmToolchain(25)

  val xcf = XCFramework("FoyerKit")

  listOf(
    macosArm64(),
    iosArm64(),
    iosSimulatorArm64(),
  ).forEach { target ->
    target.binaries.framework {
      baseName = "FoyerKit"
      isStatic = true
      binaryOption("bundleId", "dev.modaal.foyer.kit")
      // `export` puts a dependency's declarations in the framework's headers.
      // A module that is linked but not exported compiles, and Swift cannot
      // name a single type from it. One line per feature module.
      export(dependencies.project(":subtrees:splash:logic"))
      export(libs.duet.kernel)
      xcf.add(this)
    }
  }

  sourceSets {
    commonMain.dependencies {
      api(project(":subtrees:splash:logic"))
      api(libs.duet.kernel)
    }
  }
}

private val registry =
  ReplayRegistry(
    listOf<ReplayFeature>(
      ReplayFeature.entry(
        "splash",
        SplashState.serializer(),
        SplashActionSerializer,
        SplashEffectPayloadSerializer,
        ::splashReducer),
    ))

/**
 * The surface the Swift replay suite drives across the framework: canonicalize
 * fixture JSON through the core's own writer, and open a replay session over
 * a registered feature. Swift loads the files, threads the steps and compares
 * bytes; every canonical byte on both sides is produced here.
 */
object FoyerBoundary {
  // `@Throws` is the error channel. A Kotlin exception that crosses
  // Kotlin/Native without it terminates the process instead of surfacing as
  // a Swift error, so every throwing path exported to Swift carries it.
  @Throws(IllegalArgumentException::class)
  fun canonicalize(rawJson: String): String = BoundaryReplay.canonicalize(rawJson)

  @Throws(IllegalArgumentException::class)
  fun makeSession(feature: String, initialStateJson: String): ReplaySession =
    BoundaryReplay.makeSession(registry, feature, initialStateJson)
}

(cd "$ROOT/src-kmp" && ./gradlew ":apple-umbrella:$TASK" --console=plain -q)

SRC="$ROOT/src-kmp/apple-umbrella/build/XCFrameworks/$FLAVOR/FoyerKit.xcframework"
DST="$ROOT/src-kmp/apple-umbrella/build/XCFrameworks/app/FoyerKit.xcframework"
mkdir -p "$(dirname "$DST")"
rsync -a --delete "$SRC/" "$DST/"
echo "assemble_kit: $FLAVOR → ${DST#"$ROOT"/}"

    .binaryTarget(
      name: "FoyerKit",
      path: "../build/XCFrameworks/app/FoyerKit.xcframework"
    ),
    .testTarget(
      name: "BoundaryTests",
      dependencies: ["FoyerKit"],
      swiftSettings: [.enableExperimentalFeature("StrictConcurrency")],
      linkerSettings: [
        // FoyerKit is a static Kotlin/Native framework; its runtime needs
        // libc++ symbols Swift does not autolink.
        .linkedLibrary("c++"),
        .linkedFramework("Foundation"),
      ]
    ),

    var replayed = 0
    for rawStep in document["steps"] as! [[String: Any]] {
      let label = rawStep["label"] as? String ?? "step \(replayed)"
      let result = session.step(actionJson: try compactString(rawStep["action"]!))
      let expectedState = try FoyerBoundary.shared.canonicalize(
        rawJson: try compactString(rawStep["expectedState"]!))
      let expectedEffects = try FoyerBoundary.shared.canonicalize(
        rawJson: try compactString(rawStep["expectedEffects"]!))
      XCTAssertEqual(
        result.stateCanonical, expectedState, "\(fixture)/\(label): state diverged",
        file: file, line: line)
      XCTAssertEqual(
        result.effectsCanonical, expectedEffects, "\(fixture)/\(label): effects diverged",
        file: file, line: line)
      replayed += 1
    }
    return replayed

  private func replay(_ fixture: String) throws {
    let steps = try BoundaryReplayHarness.replay(fixture: fixture) { initialState in
      try FoyerBoundary.shared.makeSession(feature: "splash", initialStateJson: initialState)
    }
    XCTAssertGreaterThan(steps, 0, "the recording must contain steps to replay")
  }

  func testCeremonyCompletes() throws {
    try replay("splash.ceremony-completes")
  }

    .target(
      name: "FoyerBridge",
      dependencies: [
        .target(name: "FoyerKit"),
        .product(name: "DuetShells", package: "duet"),
      ],
      swiftSettings: strictConcurrency,
      linkerSettings: [
        // FoyerKit is a static Kotlin/Native framework; its runtime needs
        // libc++ symbols Swift does not autolink.
        .linkedLibrary("c++"),
        .linkedFramework("Foundation"),
      ]
    ),
    .target(
      name: "SplashShell",
      dependencies: [
        "FoyerBridge",
        .target(name: "FoyerKit"),
        .product(name: "DuetShells", package: "duet"),
      ],
      swiftSettings: strictConcurrency
    ),
    .testTarget(
      name: "SplashShellTests",
      dependencies: ["SplashShell"],
      swiftSettings: strictConcurrency
    ),

  /// Reduces before returning: the Kotlin store reduces synchronously on
  /// this thread, and the mirror re-reads `state.value` in the same call.
  public func send(_ action: Action) {
    sendAction(action)
    let latest = stateFlow.value
    if latest != state {
      state = latest
    }
  }

  /// `StoreHost` teardown: stops the collector, then the Kotlin runtime.
  public func cancel() {
    collector?.cancel()
    collector = nil
    teardownRuntime()
  }

public final class SplashViewShell: ViewShell {
  public let viewState = SplashViewState()
  public let store: SplashKitStore

  public init(store: SplashKitStore) {
    self.store = store
    super.init()
  }

  override public func bind() {
    // Registered first so it unwinds last: whatever this shell adopts on top
    // of the store stops before the store's `cancel()` ends its effects.
    // Adopting the mirror is also what makes `deactivate()` stop the Kotlin
    // runtime: its `cancel()` is the store's teardown plus its scope's.
    host.adopt(store)

    // State to view state. `StateTransitions` replays the current value on
    // subscription, so this adoption is also the initial projection.
    host.adopt(
      StateTransitions(state: store.$state) { [weak self] _, state in
        self?.apply(state)
      })
  }

  // MARK: - Intents (the view calls these)

  public func appeared() { store.send(SplashActionAppeared.shared) }
  public func ceremonyFinished() { store.send(SplashActionCeremonyFinished.shared) }

  // MARK: - State to view state

  private func apply(_ state: SplashState) {
    viewState.isArmed = state.isArmed
  }
}

final class LiveSplashEnvironment: NSObject, SplashEnvironment {
  private let onDelegate: (SplashDelegateEvent) -> Void

  init(onDelegate: @escaping (SplashDelegateEvent) -> Void) {
    self.onDelegate = onDelegate
  }

  /// The wall clock, the Kotlin object. Under `runTest` the Kotlin lane
  /// swaps in virtual time; the app runs on this.
  var clock: KernelClock { LiveClock.shared }

  func notifyHost(event: SplashDelegateEvent) {
    onDelegate(event)
  }
}

  @MainActor
  public func buildSplash(
    onDelegate: @escaping (SplashDelegateEvent) -> Void
  ) -> SplashChild {
    let scope = mainImmediateStoreScope()
    let store = makeSplashStore(
      environment: LiveSplashEnvironment(onDelegate: onDelegate),
      scope: scope)
    let bridged = SplashKitStore(
      state: splashStateFlow(store: store),
      send: { store.send(action: $0) },
      teardown: {
        store.teardown()
        cancelStoreScope(scope: scope)
      })
    return SplashChild(shell: SplashViewShell(store: bridged))
  }

  public var body: some View {
    VStack(spacing: 12) {
      Text("Foyer")
        .font(.system(size: 45, weight: .medium, design: .default))
      Text("One core, two apps")
        .font(.body)
        .foregroundStyle(.secondary)
      if viewState.isArmed {
        ProgressView()
          .progressViewStyle(.linear)
          .frame(width: 120)
          .padding(.top, 24)
      }
    }
    .opacity(revealed ? 1 : 0)
    .offset(y: revealed ? 0 : 16)
    .frame(maxWidth: .infinity, maxHeight: .infinity)
    .onAppear {
      shell.appeared()
      withAnimation(.easeOut(duration: ceremonySeconds)) {
        revealed = true
      } completion: {
        shell.ceremonyFinished()
      }
    }
  }

  func testTheBuilderComposesTheRuntime() {
    let child = SplashBuilder().buildSplash(onDelegate: { _ in })
    let shell = child.shell
    shell.activate()
    defer { shell.deactivate() }

    XCTAssertFalse(shell.viewState.isArmed)
    shell.appeared()
    XCTAssertTrue(shell.viewState.isArmed, "the projection reads back before send returns")
  }

    shell.activate()
    shell.appeared()
    XCTAssertTrue(kotlinState.value.isArmed)

    shell.deactivate()

    // Driven directly: the store object is still alive, only its scope is
    // gone. A notification arriving here would mean teardown did not cross.
    store.send(action: SplashActionCeremonyFinished.shared)
    try? await Task.sleep(nanoseconds: 200_000_000)
    XCTAssertTrue(environment.notified.isEmpty, "an effect ran after deactivate")

echo "apple-boundary-lane: boundary replay (swift-consumer)"
run_swift_tests "boundary replay" "$ROOT/src-kmp/apple-umbrella/swift-consumer"

echo "apple-boundary-lane: Swift shells (FoyerKit)"
run_swift_tests "shells" "$ROOT/src-ios/Libraries/FoyerKit"

  private func splashCompleted(_ event: SplashDelegateEvent) {
    // Both completion paths notify every time; the first notification moves
    // the app on and the rest arrive after the splash is gone.
    guard case .splash = phase,
      case .completed(let completed) = onEnum(of: event)
    else { return }
    splash?.shell.deactivate()
    splash = nil
    phase = .placeholder(completedBy: completed.path)
  }

  var body: some View {
    switch app.phase {
    case .splash:
      if let splash = app.splash {
        SplashView(viewState: splash.shell.viewState, shell: splash.shell)
      }
    case .placeholder(let completedBy):
      PlaceholderView(completedBy: completedBy)
    }
  }

    dependencies:
    - package: FoyerKit
      product: FoyerBridge
    - package: FoyerKit
      product: SplashShell

      preActions:
      - name: Assemble FoyerKit (Kotlin core)
        script: |
          KIT="$PROJECT_DIR/../../scripts/assemble_kit.sh"
          [ -x "$KIT" ] || exit 0
          FLAVOR=debug
          if [ "$CONFIGURATION" != "Debug" ]; then FLAVOR=release; fi
          "$KIT" "$FLAVOR"
        settingsTarget: Foyer

  implementation(project(":subtrees:splash:logic"))
  implementation(libs.duet.kernel)
  // StoreHost and RetainedRoot: the teardown registry and the retained
  // carrier the Activity keeps the app on across rotation.
  implementation(libs.duet.shells.compose)
  implementation(libs.essenty.instance.keeper)

private class LiveSplashEnvironment(
  private val onDelegate: (SplashDelegateEvent) -> Unit,
) : SplashEnvironment {
  override val clock: KernelClock = LiveClock

  override fun notifyHost(event: SplashDelegateEvent) = onDelegate(event)
}

/**
 * Builds one splash mount: the live environment and the store, on the scope
 * the host owns. The store's lifetime belongs to the host, which is why the
 * scope is a build parameter.
 */
class SplashBuilder {
  fun buildSplash(onDelegate: (SplashDelegateEvent) -> Unit, scope: CoroutineScope): SplashStore =
    makeSplashStore(environment = LiveSplashEnvironment(onDelegate), scope = scope)
}

class AppHost(scope: CoroutineScope) {
  /** The teardown registry: what the host builds registers here and unwinds in reverse. */
  val host = StoreHost(scope)

  private val mutablePhase = MutableStateFlow<AppPhase>(AppPhase.Splash)
  val phase: StateFlow<AppPhase> = mutablePhase

  /** The splash store: mounted here, torn down when the splash completes. */
  var splash: SplashStore? =
    host.host(SplashBuilder().buildSplash(onDelegate = ::splashCompleted, scope = scope))
    private set

  private fun splashCompleted(event: SplashDelegateEvent) {
    // Both completion paths notify every time; the first notification moves
    // the app on and the rest arrive after the splash is gone.
    if (mutablePhase.value !is AppPhase.Splash) return
    val completed = event as SplashDelegateEvent.Completed
    splash?.teardown()
    splash = null
    mutablePhase.value = AppPhase.Placeholder(completedBy = completed.path)
  }

  /** Logical destruction only (finish, not rotation). */
  fun teardown() = host.teardownAll()
}

@Composable
fun SplashScreen(store: SplashStore, modifier: Modifier = Modifier) {
  val state by store.state.collectAsState()
  val reveal = remember { Animatable(0f) }

  LaunchedEffect(Unit) {
    store.send(SplashAction.Appeared)
    reveal.animateTo(1f, tween(CEREMONY_MILLIS, easing = FastOutSlowInEasing))
    store.send(SplashAction.CeremonyFinished)
  }

    retained =
      instanceKeeper().getOrCreate {
        RetainedRoot(Dispatchers.Main.immediate, AppHost::teardown) { scope -> AppHost(scope) }
      }

    setContent { AppRoot(retained.component) }

  @Test
  fun theCeremonyPathLandsOnThePlaceholderAndTearsTheSplashDown() = runTest {
    val app = AppHost(backgroundScope)
    val splash = assertNotNull(app.splash)
    assertEquals(AppPhase.Splash, app.phase.value)

    splash.send(SplashAction.Appeared)
    splash.send(SplashAction.CeremonyFinished)
    runCurrent()

    assertEquals(AppPhase.Placeholder(SplashCompletionPath.Ceremony), app.phase.value)
    assertNull(app.splash, "the completed splash is torn down")

    // The torn-down store's net never fires: past the deadline, nothing changes.
    advanceTimeBy(SplashConfig.SAFETY_NET_MILLIS)
    runCurrent()
    assertEquals(AppPhase.Placeholder(SplashCompletionPath.Ceremony), app.phase.value)
    app.teardown()
  }

  "targets": {
    "Foyer": {
      "platform": "iOS",
      "architecture": "duet",
      "template": "duet-kmp",
      "pair": "Foyer",
      "deviceTypes": ["iPhone"],
      "iphoneOrientations": ["UIInterfaceOrientationPortrait"]
    },
    "FoyerAndroid": {
      "platform": "Android",
      "architecture": "duet",
      "template": "duet-kmp",
      "pair": "Foyer",
      "androidOrientations": ["Portrait"]
    }
  },