@swiftbrowser/swift 0.0.0-stage → 0.1.0

package/Sources/SwiftUI/API/Primitives.swift

@@ -0,0 +1,390 @@
+// MARK: - Text
+
+/// A localization key. Without localization tables the key is the text;
+/// interpolations are rendered into it.
+public struct LocalizedStringKey: Equatable, Sendable, ExpressibleByStringInterpolation {
+    public let key: String
+
+    public init(_ value: String) { key = value }
+    public init(stringLiteral value: String) { key = value }
+    public init(stringInterpolation: StringInterpolation) { key = stringInterpolation.text }
+
+    public struct StringInterpolation: StringInterpolationProtocol {
+        var text = ""
+        public init(literalCapacity: Int, interpolationCount: Int) {}
+        public mutating func appendLiteral(_ literal: String) { text += literal }
+        public mutating func appendInterpolation<T>(_ value: T) { text += String(describing: value) }
+        public mutating func appendInterpolation<T>(_ value: T, specifier: String) { text += String(describing: value) }
+    }
+}
+
+public struct Text: Equatable, Sendable {
+    let content: String
+
+    public init(verbatim content: String) { self.content = content }
+    public init(_ key: LocalizedStringKey) { self.content = key.key }
+    @_disfavoredOverload
+    public init<S: StringProtocol>(_ content: S) { self.content = String(content) }
+
+    /// A value formatted by `format` (`FoundationLite` supplies the formats;
+    /// FoundationBridge adds Foundation's `FormatStyle`).
+    public init<F: _TextFormat>(_ input: F.Input, format: F) { content = format._formatText(input) }
+
+    /// The text as a string, for bridge modules (a `prompt` becomes a placeholder).
+    public var _content: String { content }
+}
+extension Text: _PrimitiveView {}
+extension Text: _HostView {
+    var _kind: String { "text" }
+    func _props(in environment: EnvironmentValues) -> _JSON { .object(["text": .string(content)]) }
+}
+
+// MARK: - Image
+
+/// An SF Symbol (`systemName`) or an image from the app's asset catalog
+/// (`name`, possibly namespaced like `"dough/plain-full"`). The renderer owns
+/// the pixels: asset images come from the catalog manifest the web side
+/// builds from `Examples/<App>/*.xcassets` (see docs/ops-protocol.md).
+public struct Image: Equatable, Sendable {
+    enum Source: Equatable, Sendable {
+        case system(String)
+        case named(String)
+    }
+
+    let source: Source
+    /// `.resizable()`: fill the proposed size instead of the intrinsic one.
+    let isResizable: Bool
+
+    public init(systemName: String) {
+        source = .system(systemName)
+        isResizable = false
+    }
+
+    /// An image from the asset catalog. SwiftUI's `bundle:` parameter is not
+    /// offered: a Wasm app has no bundles, the catalog is the whole app's.
+    public init(_ name: String) {
+        source = .named(name)
+        isResizable = false
+    }
+
+    /// A catalog image hidden from assistive technology (no bridge in the
+    /// browser, so it draws like `Image(_:)`). As for `Image(_:)`, no `bundle:`.
+    public init(decorative name: String) {
+        source = .named(name)
+        isResizable = false
+    }
+
+    init(source: Source, isResizable: Bool) {
+        self.source = source
+        self.isResizable = isResizable
+    }
+
+    /// The SF Symbol name, for labels that render the icon as a glyph (tab
+    /// items, menu pickers); nil for catalog images.
+    var systemName: String? {
+        if case .system(let name) = source { return name }
+        return nil
+    }
+
+    public func resizable() -> Image { Image(source: source, isResizable: true) }
+
+    /// Accepted for source compatibility; the browser picks the interpolation.
+    public enum Interpolation: Hashable, Sendable {
+        case none, low, medium, high
+    }
+
+    public func interpolation(_ interpolation: Interpolation) -> Image { self }
+    public func antialiased(_ isAntialiased: Bool) -> Image { self }
+}
+extension Image: _PrimitiveView {}
+extension Image: _HostView {
+    var _kind: String { "image" }
+    func _props(in environment: EnvironmentValues) -> _JSON {
+        switch source {
+        case .system(let name):
+            return .object(["systemName": .string(name)])
+        case .named(let name):
+            return .object(["name": .string(name), "resizable": .bool(isResizable)])
+        }
+    }
+}
+
+// MARK: - Stacks
+
+public struct VStack<Content: View> {
+    let alignment: HorizontalAlignment
+    let spacing: CGFloat?
+    let content: Content
+
+    public init(alignment: HorizontalAlignment = .center, spacing: CGFloat? = nil,
+                @ViewBuilder content: () -> Content) {
+        self.alignment = alignment
+        self.spacing = spacing
+        self.content = content()
+    }
+}
+extension VStack: _PrimitiveView {}
+extension VStack: _HostView {
+    var _kind: String { "vstack" }
+    func _props(in environment: EnvironmentValues) -> _JSON {
+        .object(["spacing": spacing.map(_JSON.number) ?? .null, "alignment": .string(alignment.name)])
+    }
+    var _content: [any View] { [content] }
+}
+
+public struct HStack<Content: View> {
+    let alignment: VerticalAlignment
+    let spacing: CGFloat?
+    let content: Content
+
+    public init(alignment: VerticalAlignment = .center, spacing: CGFloat? = nil,
+                @ViewBuilder content: () -> Content) {
+        self.alignment = alignment
+        self.spacing = spacing
+        self.content = content()
+    }
+}
+extension HStack: _PrimitiveView {}
+extension HStack: _HostView {
+    var _kind: String { "hstack" }
+    func _props(in environment: EnvironmentValues) -> _JSON {
+        .object(["spacing": spacing.map(_JSON.number) ?? .null, "alignment": .string(alignment.name)])
+    }
+    var _content: [any View] { [content] }
+}
+
+public struct ZStack<Content: View> {
+    let alignment: Alignment
+    let content: Content
+
+    public init(alignment: Alignment = .center, @ViewBuilder content: () -> Content) {
+        self.alignment = alignment
+        self.content = content()
+    }
+}
+extension ZStack: _PrimitiveView {}
+extension ZStack: _HostView {
+    var _kind: String { "zstack" }
+    func _props(in environment: EnvironmentValues) -> _JSON { .object(["alignment": .string(alignment._name)]) }
+    var _content: [any View] { [content] }
+}
+
+/// Shows the first of its children whose ideal size fits the proposed space
+/// on `axes` (the last when none fits). The renderer measures and chooses
+/// (see docs/ops-protocol.md, Phase 7); the children are all its candidates.
+public struct ViewThatFits<Content: View> {
+    let axes: Axis.Set
+    let content: Content
+
+    public init(in axes: Axis.Set = [.horizontal, .vertical], @ViewBuilder content: () -> Content) {
+        self.axes = axes
+        self.content = content()
+    }
+}
+extension ViewThatFits: _PrimitiveView {}
+extension ViewThatFits: _HostView {
+    var _kind: String { "viewthatfits" }
+    func _props(in environment: EnvironmentValues) -> _JSON { .object(["axes": .string(axes._name)]) }
+    var _content: [any View] { [content] }
+}
+
+public struct Spacer: Sendable {
+    let minLength: CGFloat?
+    public init(minLength: CGFloat? = nil) { self.minLength = minLength }
+}
+extension Spacer: _PrimitiveView {}
+extension Spacer: _HostView {
+    var _kind: String { "spacer" }
+    func _props(in environment: EnvironmentValues) -> _JSON {
+        .object(["minLength": minLength.map(_JSON.number) ?? .null])
+    }
+}
+
+public struct Divider: Sendable {
+    public init() {}
+}
+extension Divider: _PrimitiveView {}
+extension Divider: _HostView {
+    var _kind: String { "divider" }
+    func _props(in environment: EnvironmentValues) -> _JSON { .object([:]) }
+}
+
+// MARK: - ScrollView
+
+public enum Axis: Int8, CaseIterable, Sendable {
+    case horizontal, vertical
+
+    public struct Set: OptionSet, Sendable {
+        public let rawValue: Int8
+        public init(rawValue: Int8) { self.rawValue = rawValue }
+        public static let horizontal = Set(rawValue: 1 << 0)
+        public static let vertical = Set(rawValue: 1 << 1)
+
+        /// `"horizontal"`, `"vertical"` or `"both"` (also for an empty set).
+        var _name: String {
+            if self == .horizontal { return "horizontal" }
+            if self == .vertical { return "vertical" }
+            return "both"
+        }
+    }
+}
+
+public struct ScrollView<Content: View> {
+    let axes: Axis.Set
+    let content: Content
+    /// `.refreshable`: true while the action runs.
+    @State var refreshing = false
+
+    public init(_ axes: Axis.Set = .vertical, showsIndicators: Bool = true,
+                @ViewBuilder content: () -> Content) {
+        self.axes = axes
+        self.content = content()
+    }
+}
+extension ScrollView: _PrimitiveView {}
+extension ScrollView: _HostView {
+    var _kind: String { "scrollview" }
+    func _props(in environment: EnvironmentValues) -> _JSON {
+        var props: [String: _JSON] = ["axes": .string(axes._name)]
+        _refresh(in: environment).addProps(to: &props)
+        if let snap = environment._scrollTargetBehavior { props["snap"] = .string(snap) }
+        return .object(props)
+    }
+    var _content: [any View] { [content] }
+}
+extension ScrollView: _Refreshing {
+    func _refresh(in environment: EnvironmentValues) -> _Refresh {
+        _Refresh(action: environment._refreshAction, refreshing: $refreshing)
+    }
+}
+
+// MARK: - Button
+
+public struct ButtonRole: Equatable, Sendable {
+    let name: String
+    public static let destructive = ButtonRole(name: "destructive")
+    public static let cancel = ButtonRole(name: "cancel")
+}
+
+public struct Button<Label: View> {
+    let action: @MainActor () -> Void
+    let role: ButtonRole?
+    let label: Label
+
+    public init(action: @escaping @MainActor () -> Void, @ViewBuilder label: () -> Label) {
+        self.action = action
+        self.role = nil
+        self.label = label()
+    }
+
+    public init(role: ButtonRole?, action: @escaping @MainActor () -> Void,
+                @ViewBuilder label: () -> Label) {
+        self.action = action
+        self.role = role
+        self.label = label()
+    }
+}
+
+extension Button where Label == Text {
+    public init<S: StringProtocol>(_ title: S, action: @escaping @MainActor () -> Void) {
+        self.init(action: action) { Text(title) }
+    }
+
+    public init<S: StringProtocol>(_ title: S, role: ButtonRole?, action: @escaping @MainActor () -> Void) {
+        self.init(role: role, action: action) { Text(title) }
+    }
+
+    public init(_ titleKey: LocalizedStringKey, action: @escaping @MainActor () -> Void) {
+        self.init(action: action) { Text(titleKey) }
+    }
+
+    public init(_ titleKey: LocalizedStringKey, role: ButtonRole?, action: @escaping @MainActor () -> Void) {
+        self.init(role: role, action: action) { Text(titleKey) }
+    }
+}
+
+extension Button where Label == SwiftUI.Label<Text, Image> {
+    public init<S: StringProtocol>(_ title: S, systemImage: String, action: @escaping @MainActor () -> Void) {
+        let title = String(title)
+        self.init(action: action) { SwiftUI.Label(title, systemImage: systemImage) }
+    }
+
+    public init<S: StringProtocol>(_ title: S, systemImage: String, role: ButtonRole?,
+                                   action: @escaping @MainActor () -> Void) {
+        let title = String(title)
+        self.init(role: role, action: action) { SwiftUI.Label(title, systemImage: systemImage) }
+    }
+
+    public init(_ titleKey: LocalizedStringKey, systemImage: String, action: @escaping @MainActor () -> Void) {
+        self.init(action: action) { SwiftUI.Label(titleKey, systemImage: systemImage) }
+    }
+
+    public init(_ titleKey: LocalizedStringKey, systemImage: String, role: ButtonRole?,
+                action: @escaping @MainActor () -> Void) {
+        self.init(role: role, action: action) { SwiftUI.Label(titleKey, systemImage: systemImage) }
+    }
+}
+extension Button: _PrimitiveView {}
+extension Button: _HostView {
+    var _kind: String { "button" }
+    func _props(in environment: EnvironmentValues) -> _JSON {
+        .object([
+            "style": .string(environment._buttonStyle),
+            "role": role.map { .string($0.name) } ?? .null,
+        ])
+    }
+    var _content: [any View] { [label] }
+    var _handler: ((_JSON) -> Void)? {
+        let action = self.action
+        return { _ in MainActor.assumeIsolated { action() } }
+    }
+}
+
+// MARK: - Button styles
+
+public protocol PrimitiveButtonStyle {
+    var _name: String { get }
+}
+
+public struct DefaultButtonStyle: PrimitiveButtonStyle {
+    public init() {}
+    public var _name: String { "automatic" }
+}
+public struct PlainButtonStyle: PrimitiveButtonStyle {
+    public init() {}
+    public var _name: String { "plain" }
+}
+public struct BorderedButtonStyle: PrimitiveButtonStyle {
+    public init() {}
+    public var _name: String { "bordered" }
+}
+public struct BorderedProminentButtonStyle: PrimitiveButtonStyle {
+    public init() {}
+    public var _name: String { "borderedProminent" }
+}
+
+public struct BorderlessButtonStyle: PrimitiveButtonStyle {
+    public init() {}
+    public var _name: String { "plain" }
+}
+extension PrimitiveButtonStyle where Self == BorderlessButtonStyle {
+    public static var borderless: BorderlessButtonStyle { BorderlessButtonStyle() }
+}
+extension PrimitiveButtonStyle where Self == DefaultButtonStyle {
+    public static var automatic: DefaultButtonStyle { DefaultButtonStyle() }
+}
+extension PrimitiveButtonStyle where Self == PlainButtonStyle {
+    public static var plain: PlainButtonStyle { PlainButtonStyle() }
+}
+extension PrimitiveButtonStyle where Self == BorderedButtonStyle {
+    public static var bordered: BorderedButtonStyle { BorderedButtonStyle() }
+}
+extension PrimitiveButtonStyle where Self == BorderedProminentButtonStyle {
+    public static var borderedProminent: BorderedProminentButtonStyle { BorderedProminentButtonStyle() }
+}
+
+extension View {
+    public func buttonStyle<S: PrimitiveButtonStyle>(_ style: S) -> some View {
+        environment(\._buttonStyle, style._name)
+    }
+}

package/Sources/SwiftUI/API/Publishers.swift

@@ -0,0 +1,107 @@
+/// The sliver of Combine that SwiftUI code reaches for without importing
+/// Combine (Apple's SwiftUI re-exports it): `onReceive(_:perform:)` on a
+/// publisher such as `Timer.publish(…).autoconnect()`. A `_Publisher` delivers
+/// values to one subscriber at a time, on the main actor, until cancelled.
+public protocol _Publisher {
+    associatedtype Output
+    /// Starts delivering values; the returned cancellable stops it.
+    @MainActor func _subscribe(_ receive: @escaping @MainActor (Output) -> Void) -> any _Cancellable
+}
+
+public protocol _Cancellable: Sendable {
+    func cancel()
+}
+
+/// A cancellable backed by a task (publishers that tick from the executor).
+public struct _TaskCancellable: _Cancellable {
+    let task: Task<Void, Never>
+    public init(_ task: Task<Void, Never>) { self.task = task }
+    public func cancel() { task.cancel() }
+}
+
+/// Emits `make()` every `interval` seconds, from the executor's clock (the same
+/// clock as `.task` sleeps, so headless runs stay deterministic). The shim
+/// cannot name `Date`, so `Timer.publish` in FoundationLite and FoundationBridge
+/// wraps this with `{ Date() }`.
+public struct _IntervalPublisher<Output: Sendable>: _Publisher, Sendable {
+    public let interval: Double
+    let make: @Sendable () -> Output
+
+    public init(every interval: Double, make: @escaping @Sendable () -> Output) {
+        self.interval = interval
+        self.make = make
+    }
+
+    /// Starts ticking as soon as `onReceive` subscribes; Combine's `autoconnect`
+    /// has the same effect, so this is the identity.
+    public func autoconnect() -> _IntervalPublisher<Output> { self }
+
+    @MainActor public func _subscribe(_ receive: @escaping @MainActor (Output) -> Void) -> any _Cancellable {
+        let interval = max(interval, 0.001)
+        let make = self.make
+        let task = Task { @MainActor in
+            while !Task.isCancelled {
+                try? await Task.sleep(for: .seconds(interval))
+                if Task.isCancelled { break }
+                receive(make())
+            }
+        }
+        return _TaskCancellable(task)
+    }
+}
+
+/// The executor-driven timer behind `Timer.scheduledTimer(withTimeInterval:repeats:block:)`:
+/// fires `block` after `interval` seconds, again every `interval` when
+/// repeating, until `invalidate()`. Like Foundation's, a scheduled timer stays
+/// alive until it has fired (or forever while repeating) whether or not the
+/// caller keeps a reference.
+public final class _ExecutorTimer: @unchecked Sendable {
+    public let timeInterval: Double
+    public private(set) var isValid = true
+    private var task: Task<Void, Never>?
+
+    public init(interval: Double, repeats: Bool, block: @escaping @Sendable (_ExecutorTimer) -> Void) {
+        timeInterval = interval
+        task = Task { @MainActor in
+            repeat {
+                try? await Task.sleep(for: .seconds(max(interval, 0.001)))
+                guard self.isValid, !Task.isCancelled else { return }
+                block(self)
+            } while repeats && !Task.isCancelled
+            self.isValid = false
+        }
+    }
+
+    public func invalidate() {
+        isValid = false
+        task?.cancel()
+        task = nil
+    }
+}
+
+/// `onReceive` is a task that subscribes while the view is on screen (the
+/// runtime starts it on appear and cancels it when the view leaves).
+struct _OnReceiveView<Content: View, P: _Publisher>: View {
+    let content: Content
+    let publisher: P
+    let action: @MainActor (P.Output) -> Void
+    var body: some View {
+        let publisher = self.publisher
+        let action = self.action
+        return content.task { @MainActor in
+            let cancellable = publisher._subscribe(action)
+            // Stay alive until cancelled; the publisher drives the callbacks.
+            while !Task.isCancelled {
+                try? await Task.sleep(for: .seconds(3600))
+            }
+            cancellable.cancel()
+        }
+    }
+}
+
+extension View {
+    /// Calls `action` with every value `publisher` emits while the view is shown.
+    public func onReceive<P: _Publisher>(_ publisher: P, perform action: @escaping @MainActor (P.Output) -> Void) -> some View {
+        _OnReceiveView(content: self, publisher: publisher, action: action)
+    }
+}

package/Sources/SwiftUI/API/RowActions.swift

@@ -0,0 +1,83 @@
+/// 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 }
+}
+
+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.
+    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] }
+}
+
+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/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 }
+    }
+}
+
+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 {}
+extension HStack: _ScrollTargetContainer {}
+extension VStack: _ScrollTargetContainer {}
+
+// MARK: - containerRelativeFrame
+
+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)
+        }
+    }
+}