Expose Perception check suppression as SPI

[johnnewman-square]

Follow-up to #396, which suppresses Perception's runtime check in two places: Store state reads, and the workflow render pass that workflowPreview drives from its UIViewControllerRepresentable callbacks. Both are covered, but the funnel deciding when suppression applies is internal, so a preview host outside this module can't reach it.

Downstream preview hosts exist. A host that declares its own UIViewControllerRepresentable rather than building on workflowPreview drives a render pass the same way, and so reproduces the same misreported reads for the workflows it previews. With no entry point here it would have to duplicate the predicate — a second copy of the rule in another repository, plus a new direct dependency on swift-perception for a module that has no other use for one.

Summary

• Expose the existing suppression funnel under a new PreviewHosting SPI
• Document the pre-iOS 17 limitation on the funnel, while that reasoning is in one place
• No behavior change: same availability gate, same predicate, same call sites within this module

Why SPI rather than public

Preview hosts are few and all of them are library code, so this is meaningless to an app and doesn't belong in the public surface. The signature names no Perception type — <T>(_ operation: () -> T) -> T — so a host adopts it with an @_spi(PreviewHosting) import WorkflowSwiftUI, requiring no Perception import and no new package.

The alternative shapes were worse. Making it public puts a niche primitive in front of every app developer. Leaving it internal pushes each host to reimplement the predicate, which is the drift #396 just removed from this module, recreated across repository boundaries where nobody will notice it diverging.

On the pre-iOS 17 limitation

Worth stating explicitly rather than leaving as an implementation detail, since it isn't obvious from the code and this module supports back to iOS 16.

Suppression stays off below iOS 17 and its siblings. A view body on those versions genuinely does need WithPerceptionTracking to observe state at all, so a warning about one is actionable and hiding it would turn a preview that silently stops updating into a preview that silently stops updating for no visible reason.

The cost is that a render-pass read still warns on those versions, where nothing can act on it: WithPerceptionTracking is a view modifier, and a workflow's render cannot be wrapped in one. Splitting the funnel in two would fix that, at the price of two near-identical entry points whose distinction only matters pre-17. Not worth it — but the gap should be written down.

Test plan

• swift build --target WorkflowSwiftUI, debug and release — the release build matters here, since the function is public with a #if DEBUG body
• swiftformat --lint clean across WorkflowSwiftUI/Sources
• XcodePreviewsTests and the test_perceptionRuntimeWarnings* tests are untouched, and the change is a visibility modifier plus documentation — leaving these to CI rather than a local tuist test run
• Adopted by a second preview host — the downstream adoption is written but not yet up, and depends on this landing first

Checklist

• Unit Tests (no behavior change; existing coverage applies)
• UI Tests (not applicable)
• Snapshot Tests (not applicable)
• I have made corresponding changes to the documentation

[johnnewman-square]

🤖 Closing this as unnecessary — the premise doesn't hold for the consumer that motivated it.

I couldn't reproduce the render-pass warning in a downstream preview host at all, even with suppression removed entirely. The reason is that the check is compiled out of any module whose deployment floor is iOS 17 or later. Not disabled at runtime — eliminated by overload resolution.

Both PerceptionRegistrar and this module's ObservationStateRegistrar declare access twice:

overload	availability	calls check()
access<Subject: Perceptible>	unrestricted, @_disfavoredOverload	yes
access<Subject: Observable>	@available(iOS 17, …)	no

check() has exactly one caller in all of swift-perception, inside the disfavored overload. And the @Perceptible macro conforms the type to Observation.Observable unconditionally — the generated conformance carries no availability attribute of its own. So once the call site is at a 17+ floor, the non-disfavored overload becomes visible and wins, at both layers:

1. The macro expansion in the consumer's own module resolves to ObservationStateRegistrar.access<Subject: Observable> — the one in the @available(iOS 17, …) extension.
2. Inside that extension the availability context is already 17+, so registrar.access resolves to PerceptionRegistrar.access<Subject: Observable>.
3. check() is not on that path.

Isolated repro of the language rule — same two-overload shape, one file, two deployment targets:

protocol Perceptible {}
protocol Observableish {}

struct Registrar {
    @available(*, deprecated, message: "PERCEPTIBLE OVERLOAD SELECTED")
    @_disfavoredOverload
    func access<S: Perceptible, M>(_ s: S, keyPath: KeyPath<S, M>) {}
}

@available(macOS 14, *)
extension Registrar {
    func access<S: Observableish, M>(_ s: S, keyPath: KeyPath<S, M>) {}
}

struct Model: Perceptible, Observableish {
    var foo = 0
    func go() { Registrar().access(self, keyPath: \.foo) }
}

-target arm64-apple-macos13.0 → warning: 'access(_:keyPath:)' is deprecated: PERCEPTIBLE OVERLOAD SELECTED
-target arm64-apple-macos14.0 → no warning (Observable overload selected)

So a preview host at a 17+ floor has nothing to suppress: its own state reads cannot reach check(), from a view body or a render pass. The SPI would be exported for a caller that has no use for it, and the adoption I had written turns out to be a no-op.

Worth being clear that this doesn't undercut #396 — it just scopes it. WorkflowSwiftUI declares .iOS(.v16), so Store's own reads do resolve to the disfavored overload and do need the suppression. That work is internal and self-contained, and nothing needs to leak past the module boundary for it.

The one case left uncovered is a preview host that is itself below iOS 17. If one turns up, this is the right shape for it and the branch will still be here.