@swiftbrowser/swift 0.0.0-stage → 0.2.0

package/Sources/SwiftUI/API/Redaction.swift

@@ -0,0 +1,75 @@
+// Redaction (`.redacted(reason:)`, `@Environment(\.redactionReasons)`) and
+// list separators' visibility. Redaction reasons pass down the environment,
+// so views that check them (to show placeholder content) adapt; the page
+// does not paint redacted text as grey boxes. The page draws a list's
+// separators itself, so `.listRowSeparator` and `.listSectionSeparator`
+// are accepted and leave the separators as they are.
+
+public struct RedactionReasons: OptionSet, Hashable, Sendable {
+    public let rawValue: Int
+    public init(rawValue: Int) { self.rawValue = rawValue }
+    public static let placeholder = RedactionReasons(rawValue: 1 << 0)
+    public static let privacy = RedactionReasons(rawValue: 1 << 1)
+    public static let invalidated = RedactionReasons(rawValue: 1 << 2)
+}
+
+struct _RedactionReasonsKey: EnvironmentKey {
+    static var defaultValue: RedactionReasons { [] }
+}
+
+extension EnvironmentValues {
+    /// Why the content is redacted; empty unless an ancestor is `.redacted(reason:)`.
+    public var redactionReasons: RedactionReasons {
+        get { self[_RedactionReasonsKey.self] }
+        set { self[_RedactionReasonsKey.self] = newValue }
+    }
+}
+
+public enum VerticalEdge: Int8, CaseIterable, Hashable, Sendable {
+    case top, bottom
+
+    public struct Set: OptionSet, Hashable, Sendable {
+        public let rawValue: Int8
+        public init(rawValue: Int8) { self.rawValue = rawValue }
+        public init(_ edge: VerticalEdge) { rawValue = 1 << edge.rawValue }
+        public static let top = Set(.top)
+        public static let bottom = Set(.bottom)
+        public static let all: Set = [.top, .bottom]
+    }
+}
+
+nonisolated extension View {
+    /// Adds `reason` to the environment's `redactionReasons` for the views below.
+    public func redacted(reason: RedactionReasons) -> some View {
+        _EnvironmentView(content: self) { $0.redactionReasons.formUnion(reason) }
+    }
+
+    /// Clears `redactionReasons` for the views below.
+    public func unredacted() -> some View {
+        _EnvironmentView(content: self) { $0.redactionReasons = [] }
+    }
+
+    /// Changes an environment value for the views below.
+    public func transformEnvironment<V>(_ keyPath: WritableKeyPath<EnvironmentValues, V>,
+                                        transform: @escaping (inout V) -> Void) -> some View {
+        _EnvironmentView(content: self) { transform(&$0[keyPath: keyPath]) }
+    }
+
+    /// Hides the separators at the row's `edges` (the page draws list
+    /// separators; a row hiding its bottom one, or the next row hiding its
+    /// top one, leaves the line between them out). `.visible` and
+    /// `.automatic` leave them as they are.
+    public func listRowSeparator(_ visibility: Visibility, edges: VerticalEdge.Set = .all) -> some View {
+        _styled {
+            guard visibility == .hidden else { return }
+            $0.extras["listRowSeparator"] = .object([
+                "top": .bool(edges.contains(.top)),
+                "bottom": .bool(edges.contains(.bottom)),
+            ])
+        }
+    }
+    /// The view unchanged: separators take the system color.
+    public func listRowSeparatorTint(_ color: Color?, edges: VerticalEdge.Set = .all) -> some View { self }
+    public func listSectionSeparator(_ visibility: Visibility, edges: VerticalEdge.Set = .all) -> some View { self }
+    public func listSectionSeparatorTint(_ color: Color?, edges: VerticalEdge.Set = .all) -> some View { self }
+}

package/Sources/SwiftUI/API/RowActions.swift

@@ -0,0 +1,84 @@
+/// Swipe actions and context menus on list rows (docs/ops-protocol.md, Phase 8).
+
+public enum HorizontalEdge: Hashable, CaseIterable, Sendable {
+    case leading, trailing
+}
+
+// MARK: - Swipe actions
+
+/// The `swipeactions` element: `[content, ...trailing, ...leading]`, the
+/// actions flattened to their `button`s (a `.tint` on a button stays as a
+/// `styled` wrapper carrying `tint`). Several `.swipeActions` on one row
+/// accumulate into one element.
+public struct _SwipeActionsView {
+    let content: any View
+    var trailing: [any View] = []
+    var leading: [any View] = []
+    var fullSwipeTrailing = true
+    var fullSwipeLeading = true
+
+    @MainActor
+    mutating func add(edge: HorizontalEdge, allowsFullSwipe: Bool, actions: any View) {
+        let flat = _flattenChildren(actions)
+        switch edge {
+        case .trailing:
+            trailing += flat
+            fullSwipeTrailing = allowsFullSwipe
+        case .leading:
+            leading += flat
+            fullSwipeLeading = allowsFullSwipe
+        }
+    }
+}
+extension _SwipeActionsView: _PrimitiveView {}
+extension _SwipeActionsView: _HostView {
+    var _kind: String { "swipeactions" }
+    func _props(in environment: EnvironmentValues) -> _JSON {
+        .object([
+            "trailing": .number(Double(trailing.count)),
+            "leading": .number(Double(leading.count)),
+            "fullSwipeTrailing": .bool(fullSwipeTrailing),
+            "fullSwipeLeading": .bool(fullSwipeLeading),
+        ])
+    }
+    var _content: [any View] { [content] + trailing + leading }
+}
+
+nonisolated extension View {
+    /// Buttons revealed by swiping the row horizontally. The first declared
+    /// action is nearest the content and is the one a full swipe performs.
+    @MainActor
+    public func swipeActions<T: View>(edge: HorizontalEdge = .trailing, allowsFullSwipe: Bool = true,
+                                      @ViewBuilder content: () -> T) -> _SwipeActionsView {
+        var view = (self as? _SwipeActionsView) ?? _SwipeActionsView(content: self)
+        view.add(edge: edge, allowsFullSwipe: allowsFullSwipe, actions: content())
+        return view
+    }
+}
+
+// MARK: - Context menu
+
+/// The `contextmenu` element: `[content, ...items]`, the items as in a `menu`.
+struct _ContextMenuView<Content: View, Items: View> {
+    let content: Content
+    let items: Items
+}
+extension _ContextMenuView: _PrimitiveView {}
+extension _ContextMenuView: _HostView {
+    var _kind: String { "contextmenu" }
+    func _props(in environment: EnvironmentValues) -> _JSON { .object([:]) }
+    var _content: [any View] { [content, items] }
+}
+
+nonisolated extension View {
+    /// Items shown in a popover on a long press or right click.
+    public func contextMenu<M: View>(@ViewBuilder menuItems: () -> M) -> some View {
+        _ContextMenuView(content: self, items: menuItems())
+    }
+
+    /// The preview is accepted and ignored.
+    public func contextMenu<M: View, P: View>(@ViewBuilder menuItems: () -> M,
+                                              @ViewBuilder preview: () -> P) -> some View {
+        _ContextMenuView(content: self, items: menuItems())
+    }
+}

package/Sources/SwiftUI/API/Scenes.swift

@@ -0,0 +1,131 @@
+/// More of an app's scenes: several scenes in one `body`, window groups
+/// with an identifier or for a presented value, and the scene modifiers.
+///
+/// The page is the app's one window. An app whose `body` lists several
+/// scenes shows the first window group that is not for a value (a value's
+/// window opens only through `openWindow`, which does nothing, Windows.swift).
+/// `.onChange(of:)` on a scene watches the value from the window's root view.
+/// Window sizes, resizability, styles and the menu bar's `.commands` are
+/// accepted and do nothing: there is no window to size and no menu bar.
+
+/// The scenes of a `body` that lists several.
+public struct _TupleScene: Scene {
+    let parts: [any Scene]
+    public typealias Body = Never
+    public var body: Never { fatalError("_TupleScene is a primitive scene") }
+}
+
+extension _TupleScene: _RootScene {
+    var _rootView: any View {
+        let roots = parts.compactMap { $0 as? any _RootScene }
+        guard let root = roots.first(where: { !($0 is any _ValueWindowScene) }) ?? roots.first else {
+            fatalError("No scene the runtime can present. Use WindowGroup.")
+        }
+        return root._rootView
+    }
+}
+
+@MainActor
+extension SceneBuilder {
+    public static func buildBlock<each Content: Scene>(_ content: repeat each Content) -> _TupleScene {
+        var parts: [any Scene] = []
+        for part in repeat each content { parts.append(part) }
+        return _TupleScene(parts: parts)
+    }
+
+    public static func buildOptional<Content: Scene>(_ content: Content?) -> _TupleScene {
+        _TupleScene(parts: content.map { [$0] } ?? [])
+    }
+
+    public static func buildEither<Content: Scene>(first content: Content) -> _TupleScene {
+        _TupleScene(parts: [content])
+    }
+
+    public static func buildEither<Content: Scene>(second content: Content) -> _TupleScene {
+        _TupleScene(parts: [content])
+    }
+
+    public static func buildLimitedAvailability<Content: Scene>(_ content: Content) -> _TupleScene {
+        _TupleScene(parts: [content])
+    }
+}
+
+extension WindowGroup {
+    /// A window group with an identifier (`openWindow(id:)` names it).
+    public init(id: String, @ViewBuilder content: () -> Content) {
+        self.init(content: content)
+    }
+
+    public init(_ title: String, id: String, @ViewBuilder content: () -> Content) {
+        self.init(content: content)
+    }
+
+    public init(_ titleKey: LocalizedStringKey, id: String, @ViewBuilder content: () -> Content) {
+        self.init(content: content)
+    }
+}
+
+/// The content of a `WindowGroup(for:)`: made with no value.
+public struct _ValueWindowContent<Value: Codable & Hashable, Content: View>: View {
+    let make: (Binding<Value?>) -> Content
+    public var body: Content { make(.constant(nil)) }
+}
+
+/// A window group for presented values: never opened in the browser.
+protocol _ValueWindowScene {}
+extension WindowGroup: _ValueWindowScene where Content: _ValueWindowContentMarker {}
+protocol _ValueWindowContentMarker {}
+extension _ValueWindowContent: _ValueWindowContentMarker {}
+
+@MainActor
+extension WindowGroup {
+    /// A window per presented value (`openWindow(value:)`). The page opens no
+    /// other window, so the group is declared and never shown.
+    public init<D: Codable & Hashable, C: View>(for type: D.Type, @ViewBuilder content: @escaping (Binding<D?>) -> C)
+    where Content == _ValueWindowContent<D, C> {
+        self.init { _ValueWindowContent(make: content) }
+    }
+
+    public init<D: Codable & Hashable, C: View>(_ title: String, for type: D.Type,
+                                               @ViewBuilder content: @escaping (Binding<D?>) -> C)
+    where Content == _ValueWindowContent<D, C> {
+        self.init { _ValueWindowContent(make: content) }
+    }
+}
+
+/// How a window may be resized; accepted.
+public struct WindowResizability: Hashable, Sendable {
+    let name: String
+    public static let automatic = WindowResizability(name: "automatic")
+    public static let contentSize = WindowResizability(name: "contentSize")
+    public static let contentMinSize = WindowResizability(name: "contentMinSize")
+}
+
+/// `.onChange(of:)` on a scene: the root view watches the value.
+struct _SceneOnChange<Value: Equatable>: ViewModifier {
+    let value: Value
+    let initial: Bool
+    let action: (Value, Value) -> Void
+
+    func body(content: Content) -> some View {
+        content.onChange(of: value, initial: initial, action)
+    }
+}
+
+extension Scene {
+    /// Accepted: the page is not a resizable window.
+    public func defaultSize(width: CGFloat, height: CGFloat) -> some Scene { self }
+    public func defaultSize(_ size: CGSize) -> some Scene { self }
+    public func windowResizability(_ resizability: WindowResizability) -> some Scene { self }
+    public func handlesExternalEvents(matching conditions: Set<String>) -> some Scene { self }
+
+    /// Runs `action` when `value` changes, from the window's root view.
+    public func onChange<V: Equatable>(of value: V, initial: Bool = false,
+                                       _ action: @escaping (_ oldValue: V, _ newValue: V) -> Void) -> some Scene {
+        _modifyingRootView(_SceneOnChange(value: value, initial: initial, action: action))
+    }
+
+    public func onChange<V: Equatable>(of value: V, initial: Bool = false, _ action: @escaping () -> Void) -> some Scene {
+        _modifyingRootView(_SceneOnChange(value: value, initial: initial) { _, _ in action() })
+    }
+}

package/Sources/SwiftUI/API/ScrollModifiers.swift

@@ -0,0 +1,132 @@
+// Scroll view modifiers from iOS 16-26 that Ice Cubes uses.
+//
+// - `.scrollDismissesKeyboard(.immediately | .interactively)`: the `list` or
+//   `scrollview` carries `"dismissesKeyboard": true`; when the viewer scrolls
+//   it, the page takes the focus away from the text field being edited
+//   (`.interactively` dismisses at the start of the scroll too: the page has
+//   no keyboard to drag down). `.automatic` and `.never` add nothing.
+// - `.scrollIndicators(_:axes:)`: accepted; the page's scroll views never
+//   show scroll bars (iOS shows them only while scrolling).
+// - `.scrollEdgeEffectStyle(_:for:)` (iOS 26): accepted; the page draws no
+//   edge blur under the bars.
+// - `.safeAreaInset(edge:alignment:spacing:content:)`: approximated as a
+//   stack: the inset view takes its room above or below (before or after)
+//   the view, which gets the rest, instead of overlapping a scroll view's
+//   content that can scroll out from under it; a nil `spacing` is none.
+
+public struct ScrollDismissesKeyboardMode: Hashable, Sendable {
+    let dismisses: Bool
+    public static let automatic = ScrollDismissesKeyboardMode(dismisses: false)
+    public static let immediately = ScrollDismissesKeyboardMode(dismisses: true)
+    public static let interactively = ScrollDismissesKeyboardMode(dismisses: true)
+    public static let never = ScrollDismissesKeyboardMode(dismisses: false)
+}
+
+public struct ScrollIndicatorVisibility: Hashable, Sendable {
+    let name: String
+    public static let automatic = ScrollIndicatorVisibility(name: "automatic")
+    public static let visible = ScrollIndicatorVisibility(name: "visible")
+    public static let hidden = ScrollIndicatorVisibility(name: "hidden")
+    public static let never = ScrollIndicatorVisibility(name: "never")
+}
+
+public struct ScrollEdgeEffectStyle: Hashable, Sendable {
+    let name: String
+    public static let automatic = ScrollEdgeEffectStyle(name: "automatic")
+    public static let hard = ScrollEdgeEffectStyle(name: "hard")
+    public static let soft = ScrollEdgeEffectStyle(name: "soft")
+}
+
+enum _ScrollDismissesKeyboardKey: EnvironmentKey { static let defaultValue = false }
+
+extension EnvironmentValues {
+    /// `.scrollDismissesKeyboard(.immediately | .interactively)` above a list or scroll view.
+    var _scrollDismissesKeyboard: Bool {
+        get { self[_ScrollDismissesKeyboardKey.self] }
+        set { self[_ScrollDismissesKeyboardKey.self] = newValue }
+    }
+}
+
+nonisolated extension View {
+    public func scrollDismissesKeyboard(_ mode: ScrollDismissesKeyboardMode) -> some View {
+        environment(\._scrollDismissesKeyboard, mode.dismisses)
+    }
+
+    public func scrollIndicators(_ visibility: ScrollIndicatorVisibility, axes: Axis.Set = [.vertical, .horizontal]) -> some View {
+        self
+    }
+
+    public func scrollEdgeEffectStyle(_ style: ScrollEdgeEffectStyle?, for edges: Edge.Set) -> some View { self }
+
+    public func scrollEdgeEffectHidden(_ hidden: Bool = true, for edges: Edge.Set = .all) -> some View { self }
+
+    public func safeAreaInset<V: View>(edge: VerticalEdge, alignment: HorizontalAlignment = .center,
+                                       spacing: CGFloat? = nil, @ViewBuilder content: () -> V) -> some View {
+        let inset = content()
+        return VStack(alignment: alignment, spacing: spacing ?? 0) {
+            if edge == .top { inset }
+            self.frame(maxWidth: .infinity, maxHeight: .infinity)
+            if edge == .bottom { inset }
+        }
+    }
+
+    public func safeAreaInset<V: View>(edge: HorizontalEdge, alignment: VerticalAlignment = .center,
+                                       spacing: CGFloat? = nil, @ViewBuilder content: () -> V) -> some View {
+        let inset = content()
+        return HStack(alignment: alignment, spacing: spacing ?? 0) {
+            if edge == .leading { inset }
+            self.frame(maxWidth: .infinity, maxHeight: .infinity)
+            if edge == .trailing { inset }
+        }
+    }
+}
+
+// MARK: - Content margins (iOS 17)
+
+/// Where content margins apply: a scroll view's content, or its indicators
+/// (which the page's scroll views do not inset).
+public struct ContentMarginPlacement: Hashable, Sendable {
+    let name: String
+    public static let automatic = ContentMarginPlacement(name: "automatic")
+    public static let scrollContent = ContentMarginPlacement(name: "scrollContent")
+    public static let scrollIndicators = ContentMarginPlacement(name: "scrollIndicators")
+}
+
+enum _ContentMarginsKey: EnvironmentKey { static let defaultValue: EdgeInsets? = nil }
+
+extension EnvironmentValues {
+    /// `.contentMargins(_:_:for:)` above a scroll view: the insets around its content.
+    var _scrollContentMargins: EdgeInsets? {
+        get { self[_ContentMarginsKey.self] }
+        set { self[_ContentMarginsKey.self] = newValue }
+    }
+}
+
+nonisolated extension View {
+    /// Insets the content of the scroll views below by `insets` on `edges`
+    /// (the content scrolls under the margin's area, as in SwiftUI, since it
+    /// is padding inside the scroll view). A margin set closer to the scroll
+    /// view wins on its edges.
+    public func contentMargins(_ edges: Edge.Set = .all, _ insets: EdgeInsets,
+                               for placement: ContentMarginPlacement = .automatic) -> some View {
+        transformEnvironment(\._scrollContentMargins) { margins in
+            guard placement != .scrollIndicators else { return }
+            var value = margins ?? EdgeInsets()
+            if edges.contains(.top) { value.top = insets.top }
+            if edges.contains(.leading) { value.leading = insets.leading }
+            if edges.contains(.bottom) { value.bottom = insets.bottom }
+            if edges.contains(.trailing) { value.trailing = insets.trailing }
+            margins = value
+        }
+    }
+
+    public func contentMargins(_ edges: Edge.Set = .all, _ length: CGFloat?,
+                               for placement: ContentMarginPlacement = .automatic) -> some View {
+        let amount = length ?? 16
+        return contentMargins(edges, EdgeInsets(top: amount, leading: amount, bottom: amount, trailing: amount), for: placement)
+    }
+
+    public func contentMargins(_ length: CGFloat, for placement: ContentMarginPlacement = .automatic) -> some View {
+        contentMargins(.all, length, for: placement)
+    }
+}

package/Sources/SwiftUI/API/ScrollTargets.swift

@@ -0,0 +1,104 @@
+/// Scroll snapping (docs/ops-protocol.md, "Phase 12"): `.scrollTargetBehavior`
+/// on a `ScrollView` and `.scrollTargetLayout()` on the stack inside it. The
+/// scroll view carries `snap` (`viewAligned` or `paging`) and the stack
+/// `scrollTarget: true`; the renderer maps them to CSS scroll snapping, so
+/// the children of the target layout become the snap points.
+
+public struct ScrollTargetBehavior: Hashable, Sendable {
+    let name: String
+    public static let viewAligned = ScrollTargetBehavior(name: "viewAligned")
+    public static let paging = ScrollTargetBehavior(name: "paging")
+    public static func viewAligned(limitBehavior: ViewAlignedScrollTargetBehavior.LimitBehavior) -> ScrollTargetBehavior { .viewAligned }
+}
+
+public enum ViewAlignedScrollTargetBehavior {
+    public struct LimitBehavior: Hashable, Sendable {
+        let name: String
+        public static let automatic = LimitBehavior(name: "automatic")
+        public static let always = LimitBehavior(name: "always")
+        public static let never = LimitBehavior(name: "never")
+    }
+}
+
+enum _ScrollTargetBehaviorKey: EnvironmentKey { static let defaultValue: String? = nil }
+enum _ScrollTargetLayoutKey: EnvironmentKey { static let defaultValue = false }
+
+extension EnvironmentValues {
+    var _scrollTargetBehavior: String? {
+        get { self[_ScrollTargetBehaviorKey.self] }
+        set { self[_ScrollTargetBehaviorKey.self] = newValue }
+    }
+    /// Set by `.scrollTargetLayout()`; the first stack below consumes it.
+    var _scrollTargetLayout: Bool {
+        get { self[_ScrollTargetLayoutKey.self] }
+        set { self[_ScrollTargetLayoutKey.self] = newValue }
+    }
+}
+
+nonisolated extension View {
+    public func scrollTargetBehavior(_ behavior: ScrollTargetBehavior) -> some View {
+        _EnvironmentView(content: self) { $0._scrollTargetBehavior = behavior.name }
+    }
+
+    public func scrollTargetLayout(isEnabled: Bool = true) -> some View {
+        _EnvironmentView(content: self) { $0._scrollTargetLayout = isEnabled }
+    }
+
+    /// Accepted for source compatibility; the browser's scroll views clip to their frame already.
+    public func scrollClipDisabled(_ disabled: Bool = true) -> some View { self }
+
+    /// Accepted for source compatibility; the browser decides bounce behavior.
+    public func scrollBounceBehavior(_ behavior: ScrollBounceBehavior, axes: Axis.Set = [.vertical]) -> some View { self }
+}
+
+public struct ScrollBounceBehavior: Hashable, Sendable {
+    let name: String
+    public static let automatic = ScrollBounceBehavior(name: "automatic")
+    public static let always = ScrollBounceBehavior(name: "always")
+    public static let basedOnSize = ScrollBounceBehavior(name: "basedOnSize")
+}
+
+/// The stacks `.scrollTargetLayout()` applies to; the runtime clears the flag
+/// for their children so nested stacks do not add snap points.
+protocol _ScrollTargetContainer: _TraitBearing {}
+extension HStack: _ScrollTargetContainer {}
+extension VStack: _ScrollTargetContainer {}
+
+// MARK: - containerRelativeFrame
+
+nonisolated extension View {
+    /// Sizes the view relative to its nearest container (the scroll view's
+    /// viewport or the screen): the whole container along `axes`, or `span`
+    /// of `count` equal columns separated by `spacing`. The renderer's layout
+    /// engine resolves it against the container it knows (`containerRelativeFrame`
+    /// style hint: an affine `a × container + b` per axis).
+    public func containerRelativeFrame(_ axes: Axis.Set, alignment: Alignment = .center) -> some View {
+        _containerRelativeFrame(axes, a: 1, b: 0, alignment: alignment)
+    }
+
+    public func containerRelativeFrame(_ axes: Axis.Set, count: Int, span: Int = 1, spacing: CGFloat,
+                                       alignment: Alignment = .center) -> some View {
+        let n = CGFloat(max(count, 1)), s = CGFloat(max(span, 1))
+        // SwiftUI: (container - spacing × (count - 1)) × span / count + spacing × (span - 1).
+        return _containerRelativeFrame(axes, a: s / n, b: -spacing * (n - 1) * s / n + spacing * (s - 1), alignment: alignment)
+    }
+
+    /// The closure variant. The closure is sampled at two container lengths and
+    /// treated as affine (`width * 0.6`, `width - 40`), which the common uses are.
+    public func containerRelativeFrame(_ axes: Axis.Set, alignment: Alignment = .center,
+                                       _ length: @escaping (CGFloat, Axis) -> CGFloat) -> some View {
+        let axis: Axis = axes.contains(.horizontal) ? .horizontal : .vertical
+        let b = length(0, axis)
+        let a = (length(1000, axis) - b) / 1000
+        return _containerRelativeFrame(axes, a: a, b: b, alignment: alignment)
+    }
+
+    func _containerRelativeFrame(_ axes: Axis.Set, a: CGFloat, b: CGFloat, alignment: Alignment) -> some View {
+        _styled {
+            var hint: [String: _JSON] = ["a": .number(a), "b": .number(b), "alignment": .string(alignment._name)]
+            if axes.contains(.horizontal) { hint["horizontal"] = .bool(true) }
+            if axes.contains(.vertical) { hint["vertical"] = .bool(true) }
+            $0.extras["containerRelativeFrame"] = .object(hint)
+        }
+    }
+}

package/Sources/SwiftUI/API/ScrollViewReader.swift

@@ -0,0 +1,144 @@
+// `ScrollViewReader` / `ScrollViewProxy.scrollTo(_:anchor:)`, and the
+// `.id(_:)` that names what to scroll to (docs/ops-protocol.md, "Scrolling
+// to a view").
+//
+// Inside a reader, every view with `.id(x)` is wrapped in a `styled` element
+// marked `"scrollID": true`. `proxy.scrollTo(x, anchor:)` queues a request
+// with a new serial number (increasing across all readers) and re-renders
+// the reader, whose body takes the queue: in that pass the marked element
+// whose id is `x` gets `"scrollTo": {"anchor": {x, y} | null, "serial": n}`
+// in its style (it loses it the next time the reader's body runs). After
+// laying out a pass that brings a `scrollTo` with a serial above every one
+// it handled, the page scrolls the scroll views (and lists) around the
+// element so the element's anchor point meets the same point of the visible
+// area (smoothly when the pass is animated, `withAnimation {
+// proxy.scrollTo(…) }`); a nil anchor scrolls as little as makes the
+// element visible.
+//
+// Outside a reader `.id(_:)` adds nothing to the element tree, as before.
+// Not supported: a `ForEach`'s own ids (the views need `.id(_:)` to be
+// targets), and `.id` resetting the identity (and state) of its view when
+// the id changes.
+
+// MARK: - Requests
+
+/// One `scrollTo` a reader is carrying out.
+struct _ScrollRequest: Equatable {
+    let target: AnyHashable
+    let anchor: UnitPoint?
+    /// Tells the page a repeated request from an old one.
+    let serial: Int
+}
+
+/// A reader's queue of requests, taken by its next body run.
+final class _ScrollRequestQueue {
+    var pending: [_ScrollRequest] = []
+    nonisolated(unsafe) static var lastSerial = 0
+}
+
+/// What `.id(_:)` views read: the requests of every enclosing reader.
+struct _ScrollReaderContext: Equatable {
+    var requests: [_ScrollRequest] = []
+}
+
+enum _ScrollReaderKey: EnvironmentKey { static var defaultValue: _ScrollReaderContext? { nil } }
+
+extension EnvironmentValues {
+    /// Set by `ScrollViewReader`; nil outside one.
+    var _scrollReader: _ScrollReaderContext? {
+        get { self[_ScrollReaderKey.self] }
+        set { self[_ScrollReaderKey.self] = newValue }
+    }
+}
+
+// MARK: - ScrollViewReader
+
+/// Scrolls the scroll views inside its content to the views given an `.id`.
+public struct ScrollViewProxy {
+    let request: @MainActor (AnyHashable, UnitPoint?) -> Void
+
+    /// Scrolls so the view with `.id(id)` is visible, its `anchor` point at
+    /// the same point of the scroll view's visible area (nil: as little as
+    /// makes it visible). Does nothing when no such view is on screen.
+    @MainActor
+    public func scrollTo<ID: Hashable>(_ id: ID, anchor: UnitPoint? = nil) {
+        request(AnyHashable(id), anchor)
+    }
+}
+
+public struct ScrollViewReader<Content: View>: View {
+    let content: (ScrollViewProxy) -> Content
+    @State private var queue = _ScrollRequestQueue()
+    /// Bumped by `scrollTo` so the reader's body runs and takes the queue.
+    @State private var requests = 0
+    @Environment(\._scrollReader) private var outer
+
+    public init(@ViewBuilder content: @escaping (ScrollViewProxy) -> Content) {
+        self.content = content
+    }
+
+    public var body: some View {
+        let queue = self.queue
+        let bump = $requests
+        let proxy = ScrollViewProxy { target, anchor in
+            _ScrollRequestQueue.lastSerial += 1
+            queue.pending.append(_ScrollRequest(target: target, anchor: anchor, serial: _ScrollRequestQueue.lastSerial))
+            bump.wrappedValue += 1
+        }
+        var context = outer ?? _ScrollReaderContext()
+        context.requests += queue.pending
+        queue.pending.removeAll()
+        return content(proxy).environment(\._scrollReader, context)
+    }
+}
+
+// MARK: - .id(_:)
+
+/// `.id(x)`: inside a `ScrollViewReader`, a `styled` element marking a
+/// scroll target (carrying the scroll command in the pass that asks for
+/// it); elsewhere the view itself.
+struct _IdentifiedView<Content: View> {
+    let content: Content
+    let id: AnyHashable
+    @Environment(\._scrollReader) var reader
+}
+extension _IdentifiedView: View {
+    var body: some View {
+        if let reader {
+            let request = reader.requests.last { $0.target == id }
+            content._styled { style in
+                style.extras["scrollID"] = .bool(true)
+                if let request {
+                    style.extras["scrollTo"] = .object([
+                        "anchor": request.anchor.map { .object(["x": .number($0.x), "y": .number($0.y)]) } ?? .null,
+                        "serial": .number(Double(request.serial)),
+                    ])
+                }
+            }
+        } else {
+            content
+        }
+    }
+}
+
+// MARK: - scrollContentBackground
+
+enum _ScrollContentBackgroundKey: EnvironmentKey { static let defaultValue: Visibility = .automatic }
+
+extension EnvironmentValues {
+    /// `.scrollContentBackground(_:)`; a `List` hides its grouped background when `.hidden`.
+    var _scrollContentBackground: Visibility {
+        get { self[_ScrollContentBackgroundKey.self] }
+        set { self[_ScrollContentBackgroundKey.self] = newValue }
+    }
+}
+
+nonisolated extension View {
+    /// `.hidden` drops a `List`'s own background (the system grouped
+    /// background), so a `.background(…)` behind the list shows through its
+    /// gaps; the rows keep their cell background. Scroll views and text
+    /// editors draw no background of their own already.
+    public func scrollContentBackground(_ visibility: Visibility) -> some View {
+        environment(\._scrollContentBackground, visibility)
+    }
+}