Recommended pattern for flat enum dispatch in routing reducers (avoiding ___chkstk_darwin stack overflow)

[mike-at-legend]

Recommended pattern for flat enum dispatch in routing reducers (avoiding ___chkstk_darwin stack overflow)

We have routing reducers with 20-30+ destination cases (navigation stacks, sheet coordinators). Using @Reducer enum generates deeply nested _IfCaseLetReducer<_IfCaseLetReducer<...>> chains that cause ___chkstk_darwin / EXC_BAD_ACCESS stack overflows on physical devices in Release builds. The simulator is unaffected (8MB stack vs 1MB on device). The Swift optimizer inlines the @inlinable TCA functions in Release, which balloons the stack frame size at each nesting level.

This is the same class of issue described in #3063, #2321, and #1046.

Note: This is distinct from the large-state-size overflow in #488 (solved with @Box / CoW wrappers). Our state sizes are fine — the issue is the generic depth of the Reducer.Body type itself. You can verify this with MemoryLayout<MyReducer.Body>.size — it grows linearly with each Scope/ifCaseLet in the body, and past ~25 cases the stack frame exceeds what a 1MB device stack can handle.

Our workaround

We bypass @Reducer enum's auto-generated body entirely with a manual switch reducer. This produces zero generic nesting — a flat function with O(1) stack depth regardless of case count:

// @Reducer enum Path generates the State/Action enums,
// but we replace its reducer body with a manual flat dispatch.

@Reducer
enum Path {
    case chat(ChatsFeature)
    case profile(ProfileFeature)
    case settings(SettingsFeature)
    // ... 20+ more cases
}

// Manual flat dispatch — same behavior as @Reducer enum's
// auto-generated IfCaseLetReducer chain, but O(1) stack depth.
struct PathReducer: Reducer {
    typealias State = Path.State
    typealias Action = Path.Action

    func reduce(into state: inout State, action: Action) -> Effect<Action> {
        switch (state, action) {
        case (.chat(var cs), .chat(let ca)):
            let effect = ChatsFeature()._reduce(into: &cs, action: ca).map(Action.chat)
            state = .chat(cs)
            return effect
        case (.profile(var cs), .profile(let ca)):
            let effect = ProfileFeature()._reduce(into: &cs, action: ca).map(Action.profile)
            state = .profile(cs)
            return effect
        case (.settings(var cs), .settings(let ca)):
            let effect = SettingsFeature()._reduce(into: &cs, action: ca).map(Action.settings)
            state = .settings(cs)
            return effect
        // ... 20+ more cases
        default:
            return .none
        }
    }
}

We use this pattern in three places: navigation stack paths (~23 cases), sheet coordinators (~40 cases), and fullscreen cover destinations (~5 cases). It's been stable in production.

The deprecation concern

With #3857 deprecating reduce(into:action:) in 1.25, we've migrated to _reduce(into:action:) — the same non-deprecated internal dispatch method used by Scope, IfCaseLetReducer, and ReducerBuilder._Sequence. This silences the warning and is functionally identical.

However, the deprecation message says TCA 2.0 will remove the ability to invoke reduce entirely, and _reduce is an underscored API with no stability guarantees.

Questions

1. When _reduce is removed or made internal in 2.0, what's the intended pattern for manually dispatching to child reducers? Will enum scoping or a ReducerBuilder change flatten the generic depth so @Reducer enum is safe for 20-30+ cases?
2. Is there a better approach we should be using today? We considered @_optimize(none) on the body (which TCA already uses on _reduce) but that only helps at the call site, not the generated body type.
3. Would TCA benefit from a built-in flat-dispatch mechanism for large enum reducers — e.g., an array-based _ReduceArray similar to what ReducerBuilder already uses for buildArray?

[mike-at-legend]

in case it is useful context, I asked claude for a general summary of our architecture/decisions. I have reviewed the below to make sure I'm not purely sharing AI slop. Also sharing in case you or others find useful.

TCA Navigation Architecture: Custom Tabs, Sheets & Routing Reducers

A practical reference for building a production iOS app with The Composable Architecture — covering custom tab bars, dynamic-height sheets, manual routing reducers, and the tradeoffs behind each decision.

Overview

Our app is an app with 5 tabs, 20+ push destinations, 40+ sheet screens, and fullscreen covers. The navigation architecture is built on TCA with several custom layers to work around SwiftUI and TCA limitations we hit in production.

Key departures from vanilla TCA navigation:

• Custom floating tab bar instead of SwiftUI TabView
• Custom ZStack-based sheet system instead of SwiftUI .sheet() / @Presents
• Manual switch-based routing reducers instead of @Reducer enum's auto-generated body

---

1. Custom Tab Bar

We use a custom floating capsule-shaped tab bar (HStack in a ZStack overlay) instead of SwiftUI's TabView.

Why not SwiftUI TabView?

Design reasons:

• Floating pill design with rounded capsule shape, semi-transparent background
• Animated hide/show when entering immersive screens (chart trading, chat rooms)
• User avatar rendered directly in the profile tab button
• Scale + gradient highlight animation on selection

Technical reasons:

• SwiftUI TabView doesn't support reliable programmatic tab bar hiding with smooth animations (we hide for several screens)
• Tab bar visibility toggling (hidesTabBar property on certain path screens) requires frame-level control that TabView doesn't expose

How tabs are managed

Each tab owns an independent TabCoordinator with its own root feature and navigation stack:

@Reducer
struct TabCoordinator {
    @Reducer
    enum Root {
        case explore(ExploreFeature)
        case lobby(LobbyFeature)
        case chat(ChatsFeature)
        case feed(FeedFeature)
        case profile(ProfileFeature)
    }

    @ObservableState
    struct State: Equatable {
        var root: Root.State
        var path = StackState<Path.State>()
        @Presents var cover: CoverDestination.State?
    }
}

TabFeature holds all 5 coordinators, each wrapped in Indirect<T> (heap-allocated box) to prevent state struct size from blowing the stack:

struct TabFeature {
    @ObservableState
    struct State: Equatable {
        var selectedTab: Tab = .explore
        var exploreCoordinator: Indirect<TabCoordinator.State>
        var lobbyCoordinator: Indirect<TabCoordinator.State>
        var chatCoordinator: Indirect<TabCoordinator.State>
        var feedCoordinator: Indirect<TabCoordinator.State>
        var profileCoordinator: Indirect<TabCoordinator.State>
    }
}

Key property: tabs are fully independent. Each tab has its own StackState<Path.State>. If a user navigates to a profile from the Explore tab and also from the Chat tab, those are two separate ProfileFeature instances with independent state. Switching tabs preserves each stack.

Shared Path enum

The Path enum is shared across all 5 tabs — a single superset of all push destinations:

@Reducer
enum Path {
    case chat(ChatsFeature)
    case chatRoom(ChatRoomFeature)
    case clan(ClanFeature)
    case profile(ProfileFeature)
    case settings(SettingsFeature)
    case chartTrading(ChartTradingFeature)
    // ... 20+ cases
}

Why one enum instead of per-tab enums? Most destinations are reachable from multiple tabs. A profile can be opened from Explore, Chat, Feed, or another profile. A clan can be opened from a profile, the leaderboard, or chat. Maintaining 5 separate path enums would mean duplicating most cases across all of them.

---

2. Custom Sheet System

We use a custom ZStack-based sheet system (TabSheetCoordinator) instead of SwiftUI's .sheet() modifier.

Why not SwiftUI .sheet()?

The primary reason is dynamic content sizing. SwiftUI's .sheet() picks a detent (.medium, .large, or a fixed fraction) and the sheet stays at that height. It does not size-to-content. Our sheets vary wildly in height — a simple confirmation dialog might be 200pt, while a token selector with a search bar fills most of the screen. When a sheet pushes a second screen (e.g., deposit flow → network selector), the new screen may have a completely different natural height.

SwiftUI's .presentationDetents() can approximate this with custom detents, but:

• There's no "size to content" detent — you must know the height upfront
• Detents don't animate smoothly when content changes mid-presentation
• Multi-step navigation inside a sheet (push/pop with different heights) isn't supported

Additional benefits of our custom sheet:

• Multi-step push/pop navigation with horizontal slide transitions inside the sheet
• Custom drag-to-dismiss on the handle indicator (SwiftUI's drag detection conflicts with scroll views)
• Keyboard-aware fixed height via maxSheetContentHeight environment variable
• Full control over spring animations and dismiss thresholds
• DismissAction environment (SwiftUI's dismiss doesn't work in ZStack overlays)

How it works

TabSheetCoordinator manages a StackState<Screen.State> where all screens (root and pushed) live in a single stack:

@Reducer
struct TabSheetCoordinator {
    @Reducer
    enum Screen {
        case memberActionsSheet(MemberActionsSheetFeature)
        case changeDisplayName(ChangeDisplayNameFeature)
        case closePosition(ClosePositionFeature)
        case createClan(CreateClanFeature)
        case withdrawSelection(WithdrawSelectionFeature)
        // ... 40+ cases
    }

    @ObservableState
    struct State: Equatable {
        var path = StackState<Screen.State>()
        var isPopping = false
        let id = UUID()  // Identity change on dismiss→re-present
    }
}

Presentation flow:

1. Child feature sends delegate action (e.g., .presentChangeDisplayName(currentValue))
2. Tab coordinator bubbles it up to AppCoordinator via signal action
3. AppCoordinator creates TabSheetCoordinator.State with the root screen and sets state.sheet = ...
4. The view layer renders the sheet as a ZStack overlay with fixedSize(horizontal: false, vertical: true) for dynamic height

Multi-step flows (deposit, clan creation, withdrawals) push screens onto the stack:

// Inside TabSheetCoordinator reducer:
case .createClan(.delegate(.presentClanImageSelector(state))):
    state.path.append(.clanImageSelector(state))
    return .none

Returning results: Sheet delegate actions bubble up through TabSheetCoordinator.Delegate to AppCoordinator, which sets state.sheet = nil and routes the result to the originating tab coordinator.

Why @presents is still used on the sheet slot

We use @Presents var sheet: TabSheetCoordinator.State? on AppCoordinator for the sheet slot itself. This gives us TCA's automatic effect cancellation on dismiss→re-present cycles. The distinction is:

• @Presents on the sheet slot (AppCoordinator → TabSheetCoordinator) = yes, for lifecycle management
• @Presents / SwiftUI .sheet() for individual screen presentation = no, we use our custom ZStack system

---

3. Manual Routing Reducers (Stack Overflow Fix)

The problem

@Reducer enum with 20+ cases generates a deeply nested _IfCaseLetReducer<_IfCaseLetReducer<...>> generic type. On physical devices in Release builds, the Swift optimizer inlines the @inlinable TCA functions, which balloons the stack frame size at each nesting level. With a 1MB stack on device (vs 8MB on simulator), this causes ___chkstk_darwin / EXC_BAD_ACCESS crashes.

We discovered this in production. The app shipped with @Reducer enum and crashed on device. Simulator testing never caught it because of the 8x larger stack.

This is a known issue: #3063, #2321, #1046.

The fix

We keep @Reducer enum for its generated State/Action types and case paths, but replace its auto-generated reducer body with a manual switch:

// @Reducer enum generates State, Action, CasePathable — but NOT the reducer body.
@Reducer
enum Path {
    case chat(ChatsFeature)
    case profile(ProfileFeature)
    case settings(SettingsFeature)
    // ... 20+ cases
}

// Manual flat dispatch — O(1) stack depth regardless of case count.
struct PathReducer: Reducer {
    typealias State = Path.State
    typealias Action = Path.Action

    func reduce(into state: inout State, action: Action) -> Effect<Action> {
        switch (state, action) {
        case (.chat(var cs), .chat(let ca)):
            let effect = ChatsFeature()._reduce(into: &cs, action: ca).map(Action.chat)
            state = .chat(cs)
            return effect
        case (.profile(var cs), .profile(let ca)):
            let effect = ProfileFeature()._reduce(into: &cs, action: ca).map(Action.profile)
            state = .profile(cs)
            return effect
        // ... each case follows the same pattern
        default:
            return .none
        }
    }
}

Then in the parent coordinator's body, we use the manual reducer instead of the auto-generated one:

var body: some ReducerOf<Self> {
    Scope(state: \.root, action: \.root) {
        RootReducer()  // NOT Root() — manual flat dispatch
    }
    .forEach(\.path, action: \.path) {
        PathReducer()  // NOT Path() — manual flat dispatch
    }
}

Where we use this

Reducer	File	Cases	Purpose
RootReducer	TabCoordinator	5	Tab root features
PathReducer	TabCoordinator	23	Navigation stack destinations
CoverReducer	TabCoordinator	5	Fullscreen cover destinations
ScreenReducer	TabSheetCoordinator	40+	Sheet screen destinations
TabsReducer	TabFeature	5	Tab coordinator dispatch

The _reduce question

With TCA 1.25 deprecating reduce(into:action:) (#3857), we use _reduce(into:action:) — the same non-deprecated internal dispatch method used by TCA's own Scope, IfCaseLetReducer, and ReducerBuilder._Sequence. This is functionally identical but the underscore prefix signals it's not a public API contract, so we're watching for what TCA 2.0 provides as a replacement.

---

4. Layer Hierarchy

AppFeature (auth, initialization)
└── AppCoordinator (cross-tab coordination)
    ├── TabFeature (tab switching, 5 coordinators)
    │   ├── TabCoordinator[explore] (root + StackState path + covers)
    │   ├── TabCoordinator[lobby]
    │   ├── TabCoordinator[chat]
    │   ├── TabCoordinator[feed]
    │   └── TabCoordinator[profile]
    ├── TabSheetCoordinator? (unified sheet layer, @Presents)
    └── FullScreenCover? (app-level covers, above sheets)

Action flow for presenting a sheet:

1. Feature sends delegate: .delegate(.presentTokenSelector)
2. Tab coordinator forwards as signal: .presentSheet(.assetSelector(state))
3. AppCoordinator handles signal: state.sheet = TabSheetCoordinator.State(path: [.assetSelector(state)])
4. View renders ZStack overlay with dynamic height

Action flow for sheet returning a result:

1. Sheet feature sends delegate: .delegate(.tokenSelected(symbol))
2. TabSheetCoordinator forwards as .delegate(.tokenSelected(symbol))
3. AppCoordinator handles: state.sheet = nil + routes result to originating tab