Duet Swift Tutorial 1: Your First Feature

let package = Package(
  name: "SplashFeature",
  platforms: [
    // iOS for the app; macOS so the Swift lane runs as plain `swift test`.
    .iOS(.v17),
    .macOS(.v14),
  ],
  products: [
    .library(name: "SplashFeature", targets: ["SplashFeature"])
  ],
  dependencies: [
    // The Duet framework, pinned exactly: a newer release is a deliberate
    // re-pin, made in every manifest of the tree at once.
    .package(url: "https://github.com/modaal-agent/duet.git", exact: "0.7.0")
  ],
  targets: [
    .target(
      name: "SplashFeature",
      dependencies: [
        .product(name: "Duet", package: "duet")
      ],
      swiftSettings: strictConcurrency
    ),
    .testTarget(
      name: "SplashFeatureTests",
      dependencies: [
        "SplashFeature",
        .product(name: "DuetTesting", package: "duet"),
      ],
      swiftSettings: strictConcurrency
    ),
  ]
)

features:
  splash:
    swift: src-ios/Subtrees/Splash/SplashFeature/Sources/SplashFeature/SplashFeature.swift
    state: SplashState
    action: SplashAction
    effectPayload: SplashEffectPayload
    scenario: src-ios/Subtrees/Splash/SplashFeature/Tests/SplashFeatureTests/SplashScenarioTests.swift
    fixtures:
      - splash.ceremony-completes
      - splash.safety-net-fires
      - splash.both-paths-notify-twice
      - splash.repeat-appear-inert

// MARK: - Configuration

public enum SplashConfig {
  /// How long the safety net waits before it completes the splash on the
  /// ceremony's behalf. The reducer carries the value out in the effect
  /// payload, so the recordings pin it.
  public static let safetyNetMillis: Int64 = 3_000
}

public enum SplashEffectIds {
  /// The safety net's effect id. One net is in flight per store: a second
  /// `.run` under the same id cancels the first, and the store's teardown
  /// cancels it outright.
  public static let safetyNet: EffectID = "splash.safetyNet"
}

// MARK: - State

public struct SplashState: Equatable, Codable, Sendable {
  /// The arming latch: the safety net is armed once per mount.
  public var isArmed: Bool

  public init(isArmed: Bool = false) {
    self.isArmed = isArmed
  }
}

// MARK: - Actions

public enum SplashAction: Equatable, Sendable, CanonicalSumCodable {
  /// Shell report: the splash is on screen and the safety net should arm.
  case appeared
  /// Shell report: the splash animation reached its end.
  case ceremonyFinished
  /// Environment report: the armed delay elapsed.
  case safetyNetElapsed
}

// MARK: - Delegate events

/// Which of the two paths completed the splash.
public enum SplashCompletionPath: Equatable, Sendable, CanonicalSumCodable {
  case ceremony
  case safetyNet
}

/// What the splash tells its host. The host decides what happens next.
public enum SplashDelegateEvent: Equatable, Sendable, CanonicalSumCodable {
  case completed(path: SplashCompletionPath)
}

// MARK: - Effect payloads

public enum SplashEffectPayload: Equatable, Sendable, CanonicalSumCodable {
  /// Wait `afterMillis` on the environment's clock, then report
  /// `.safetyNetElapsed`. Runs under `SplashEffectIds.safetyNet`.
  case armSafetyNet(afterMillis: Int64)
  /// Hand a delegate event to the host.
  case notifyListener(SplashDelegateEvent)
}

  public func encode(to encoder: Encoder) throws {
    var c = encoder.container(keyedBy: SumCodingKeys.self)
    switch self {
    case let .armSafetyNet(afterMillis):
      try c.encode("armSafetyNet", forKey: .caseName)
      var v = c.nestedContainer(keyedBy: ValueKey.self, forKey: .value)
      try v.encode(afterMillis, forKey: ValueKey("afterMillis"))
    case let .notifyListener(v0):
      try c.encode("notifyListener", forKey: .caseName)
      try c.encode(v0, forKey: .value)
    }
  }

public func splashReducer(
  state: inout SplashState,
  action: SplashAction
) -> [Effect<SplashEffectPayload>] {
  switch action {
  case .appeared:
    // The arming guard: a repeat `.appeared` writes nothing and emits nothing.
    guard !state.isArmed else { return [] }
    state.isArmed = true
    return [
      .run(
        .armSafetyNet(afterMillis: SplashConfig.safetyNetMillis),
        id: SplashEffectIds.safetyNet)
    ]

  case .ceremonyFinished:
    return [.run(.notifyListener(.completed(path: .ceremony)))]

  case .safetyNetElapsed:
    return [.run(.notifyListener(.completed(path: .safetyNet)))]
  }
}

public protocol SplashEnvironment {
  /// The clock the safety net waits on. The effect handler calls `sleep` here
  /// rather than `Task.sleep` directly, so a test can run the wait on virtual
  /// time.
  var clock: any KernelClock { get }

  /// Hand a delegate event to the host.
  func notifyHost(_ event: SplashDelegateEvent)
}

public func splashEffectHandler(
  environment: SplashEnvironment
) -> (SplashEffectPayload) -> AsyncStream<SplashAction> {
  { payload in
    switch payload {
    case let .armSafetyNet(afterMillis):
      let clock = environment.clock
      return AsyncStream { continuation in
        let task = Task {
          do {
            try await clock.sleep(nanoseconds: UInt64(afterMillis) * nanosPerMilli)
            continuation.yield(.safetyNetElapsed)
          } catch {
            // Cancelled: the store re-armed under the same id or tore down.
          }
          continuation.finish()
        }
        continuation.onTermination = { _ in task.cancel() }
      }

    case let .notifyListener(event):
      return AsyncStream { continuation in
        environment.notifyHost(event)
        continuation.finish()
      }
    }
  }
}

Four leaves over one given (a fresh store, then `appeared`):

| Recording | Pins |
| --- | --- |
| `splash.ceremony-completes` | `appeared` arms the net; `ceremonyFinished` notifies `completed(ceremony)` |
| `splash.safety-net-fires` | `safetyNetElapsed` notifies `completed(safetyNet)`. Mutually exclusive with the row above, so it is a branch over the same given rather than a scenario of its own |
| `splash.both-paths-notify-twice` | the deliberate non-latch: `ceremonyFinished` then `safetyNetElapsed`, two notifications |
| `splash.repeat-appear-inert` | the arming guard: a second `appeared` writes nothing and emits nothing |

private let splashScenario = Scenario<SplashState, SplashAction, SplashEffectPayload>(
  feature: "splash",
  description:
    "The splash arms a safety net when it appears and completes by whichever "
    + "path gets there first: the animation ending, or the net firing. Both "
    + "paths notify the host every time; a repeat Appeared is inert."
) {
  Given(SplashState())

  When("the splash appears", .appeared)
  Then("the safety net is armed") { $0.isArmed }
  ThenEffects("exactly the keyed safety net, carrying its duration") {
    $0 == [
      .run(
        .armSafetyNet(afterMillis: SplashConfig.safetyNetMillis),
        id: SplashEffectIds.safetyNet)
    ]
  }

  Branch("ceremony completes") {
    When("the animation reaches its end", .ceremonyFinished)
    Then("the arming latch is untouched") { $0.isArmed }
    ThenEffects("the host is notified, by the ceremony path") { $0 == notified(.ceremony) }
  }

  Branch("safety net fires") {
    When("the armed delay elapses instead", .safetyNetElapsed)
    Then("the arming latch is untouched") { $0.isArmed }
    ThenEffects("the host is notified, by the safety-net path") { $0 == notified(.safetyNet) }
  }

  Branch("both paths notify twice") {
    When("the animation reaches its end", .ceremonyFinished)
    ThenEffects("the host is notified, by the ceremony path") { $0 == notified(.ceremony) }
    When("the armed delay elapses on top of it", .safetyNetElapsed)
    ThenEffects("the host is notified again, by the safety-net path") {
      $0 == notified(.safetyNet)
    }
  }

  Branch("repeat appear inert") {
    When("the splash reports appearing a second time", .appeared)
    Then("still armed, unchanged") { $0.isArmed }
    ThenEffects("nothing: the net is not re-armed") { $0.isEmpty }
  }
}

    {
      "action": {
        "case": "appeared"
      },
      "expectedEffects": [],
      "expectedState": {
        "isArmed": true
      },
      "label": "repeat appear inert › the splash reports appearing a second time",
      "line": 55
    }

/// The feature's door to the platform: a clock to wait on and a sink for the
/// delegate event. The app implements it; tests use the generated
/// `SplashEnvironmentMock`.
/// sourcery: CreateMock
public protocol SplashEnvironment {

mocks:
  bundle: 0.10.2
  generators:
    splash_mocks:
      output: src-ios/Subtrees/Splash/SplashFeature/Tests/SplashFeatureTests/Generated/SplashFeatureMocks.swift
      template: Mocks.swifttemplate
      sources:
        - src-ios/Subtrees/Splash/SplashFeature/Sources/SplashFeature
      args:
        - import=Duet
        - import=SplashFeature

    // MARK: - Methods
    func notifyHost(_ event: SplashDelegateEvent) {
        notifyHostCallCount += 1
        notifyHostArgs.append(event)
        if let __notifyHostHandler = self.notifyHostHandler {
            __notifyHostHandler(event)
        }
    }
    var notifyHostCallCount: Int = 0
    var notifyHostArgs: [SplashDelegateEvent] = []
    var notifyHostHandler: ((_ event: SplashDelegateEvent) -> ())? = nil

  func testSafetyNetFiresAfterItsDuration() async {
    let clock = TestClock()
    let environment = SplashEnvironmentMock(clock: clock)
    let store = armedStore(environment)

    await clock.advance(byNanoseconds: nanos(SplashConfig.safetyNetMillis))

    // `receive`, not `send`: the handler emitted this action, so the store
    // already has it and the test states what arrived.
    await store.receive(.safetyNetElapsed)
    store.expectEffects([notifySafetyNet])
    await store.finish()
    XCTAssertEqual(environment.notifyHostArgs, [.completed(path: .safetyNet)])
  }

  func testTeardownCancelsTheArmedNet() async {
    let clock = TestClock()
    let environment = SplashEnvironmentMock(clock: clock)
    let store = armedStore(environment)

    store.teardown()
    await clock.advance(byNanoseconds: nanos(SplashConfig.safetyNetMillis * 3))

    await store.finish()
    XCTAssertEqual(environment.notifyHostArgs, [])
  }

// The replay registry: one typed entry per feature. `tools/duet protocol-run`
// sends each recorded step through this server and compares the bytes it
// returns with the recording.
public let appReplayRegistry = ReplayRegistry([
  ReplayFeature.entry("splash", SplashState.self, SplashAction.self) { state, action in
    splashReducer(state: &state, action: action)
  }
])

// The replay-protocol endpoint: the framework's stdio server over the
// registry. No app links this executable.
ReplayServer.serve(registry: appReplayRegistry)

  dependencies: [
    // The Duet framework, pinned exactly, at the release every other manifest
    // in this tree names.
    .package(url: "https://github.com/modaal-agent/duet.git", exact: "0.7.0"),
    .package(path: "../../Subtrees/Splash/SplashFeature"),
  ],

# The Swift package that owns the Sources/replay-runner executable, the
# protocol lane's driver.
replayRunner: src-ios/Libraries/Replay