When navigate means more than push

The state a screen router cannot reach

Two earlier pieces set this up. The surface-area piece counted dozens of view reads of shared coordinator state (the honest cost of ephemeral state that multiple screens care about). The state-aware piece showed how URLs can reach that state without leaking context into the grammar.

This piece names the state itself, from the app’s perspective: a closed vocabulary of named changes.

When “navigate” means more than push and present, where does the rest live? A search in the conversation list. A filter on the inbox. A scroll target that must wait for the list to exist. An avatar overlay. None of these is “push a new screen”. All are pieces of observable state that views read.

Most navigation systems stop at the screen boundary and scatter ad-hoc setters through the rest of the code. Iris takes the opposite view. A navigation plan is an ordered list of steps. Each step is either structural (push, pop, present, dismiss) or an effect (a named state change the app declares and implements in one place). Iris guarantees ordering, cancellation points between steps, and what happens when a newer URL arrives. It does not need to know what the effects mean.

A closed set of named changes

The app’s half of the contract is that set of changes. Each one names a single piece of ephemeral state, and a plan can interleave structural steps and these effect steps in one ordered list. The one place those changes are actually made is the apply step. In the demo messaging app this series measures its claims against, the full set is ten changes writing seven observable properties.

The ten are ordinary app state, named once each: set or clear an in-thread search; clear the list filter; queue a scroll to an avatar row or to a conversation row; expand or collapse an avatar; expand or dismiss an image attachment; and one composite that selects a bot’s tab and its filter together.

The shape of the set is as telling as its size. The changes come in symmetric pairs that share a property: set-and-clear for search, expand-and-collapse for the avatar, expand-and-dismiss for the attachment. The one composite change writes two properties in a single pass, so the interface never shows the halfway state. Views read these properties directly. Tests and automation read them through a snapshot, a packaged copy of the app’s observable state that is stamped onto every change the trace records.

Iris deliberately owns none of these names. I left the changes to the app, because only the app knows what its ephemeral state is; what Iris owns is the guarantee that the set stays closed. If a piece of state is worth driving from a URL, it earns one named change, one entry in the apply step, and nothing else.

Four entry points, one implementation

What makes the set a control surface rather than a routing table is who gets to use it. Four callers converge on the same apply step.

1. Taps. The search icon’s tap handler does not write the search query itself. It constructs a URL and opens it, so the same state-aware decision applies as for a link arriving from outside. Parity by construction, not by code review.
2. URLs. The open path parses an incoming URL against a frozen snapshot of current state, builds a plan, and runs it. This is the path everything else borrows.
3. Tests. The test driver fires URLs at the open path and asserts on the recorded trace. It reads the same observable properties the views do, through the same snapshot.
4. Scripted capture. simctl openurl drives the open path from a shell. The recordings in this series were staged that way: a script firing URLs at the running app until the screen shows the state worth capturing.

A tap is a URL the user didn’t see. A test is a URL with assertions. A capture session is a URL with a camera running. Remove any one, and the apply step neither knows nor cares.

One intent, one ordered list

Effects shine when combined with structural moves. For botmessages://avatar/aria-7/expanded, Iris produces one ordered plan:

case .avatarExpanded(let id):
    return [
        .effect(.dismissAttachmentExpansion),
        .effect(.clearInThreadSearch),
        .effect(.clearListFilter),
        .nav(.popToRoot),
        .nav(.dismissSheet),
        .effect(.scrollToAvatarRow(id)),
        .effect(.expandAvatar(id))
    ]

Clear the screen, reset the stack, then scroll and expand. Iris executes the list step-by-step, checking for cancellation between each one. The apply step sees only one change at a time.

Before writing, apply does three things:

1. If a newer URL has arrived, record [cancelled] and stop.
2. If the change would be a no-op, record [skipped].
3. Defer the trace record so guarded changes get the right suffix.

Every write touches one observable property. Views update, the trace records the post-state snapshot. Tests and agents rely on this: the trace says what actually happened, not just that the URL was “handled”.

What the design pays for

None of this is free. Four costs are worth naming, because each one bounds how far the trace can be trusted and how the surface behaves at its edges.

Parity as a structural fact

When tap entry and URL entry share one apply step, “you can drive the app by URL” stops being a claim and becomes a property of the architecture. A test fires a URL because URLs are the input language. A demo recording fires a URL for the same reason. An agent positioning the app for a screenshot fires a URL because there is nothing else to fire. No special path for tests, no separate hook for the recording, no parallel API for automation to drift out of date.

The same surface answers a harder question: how much can one URL hand the user, ready to continue rather than start over? Priming a draft is an effect case like any other, and a primed, mid-edit compose state two sheet layers deep turns out to be one URL’s worth of work. The final piece in this series shows that end to end. The full map lives on the deep-linking hub.