@swiftbrowser/native 0.0.0-stage → 0.10.0

package/swift/Sources/SwiftBrowserProtocol/Style.swift

@@ -0,0 +1,148 @@
+import Foundation
+
+/// A `styled` element's style: every field optional, each one modifier of
+/// the app's (docs/ops-protocol.md, "Style"; `interface Style` in
+/// Web/src/protocol.ts). The fields a renderer draws are typed here; `raw`
+/// keeps the whole object, so a field this type does not name is still there
+/// to read.
+public struct Style: Equatable, Sendable {
+    public var raw: JSONObject
+
+    public var padding: EdgeInsetsSpec?
+    public var font: FontSpec?
+    public var foreground: ShapeStyleSpec?
+    public var foregroundLevels: [ShapeStyleSpec]
+    public var background: ShapeStyleSpec?
+    public var frame: FrameSpec?
+    public var cornerRadius: Double?
+    public var backgroundCornerRadius: Double?
+    public var opacity: Double?
+    public var disabled: Bool?
+    public var layoutPriority: Double?
+    /// `.lineLimit(n)`; `lineLimitLifted` when the app passed `nil` to lift an inherited limit.
+    public var lineLimit: Int?
+    public var lineLimitLifted: Bool
+    public var lineLimitMin: Int?
+    public var multilineTextAlignment: String?
+    public var fixedSizeHorizontal: Bool?
+    public var fixedSizeVertical: Bool?
+    public var animation: AnimationSpec?
+    public var animationToken: Double?
+    public var labelIcon: Bool
+    public var transition: [TransitionSpec]?
+    public var aspectRatio: Double??
+    public var aspectRatioContentMode: String?
+    public var offset: PointSpec?
+    public var rotation: Double?
+    public var rotationAnchor: UnitPointSpec?
+    public var scale: PointSpec?
+    public var scaleAnchor: UnitPointSpec?
+    public var shadow: ShadowSpec?
+    public var clipped: Bool
+    public var tint: ColorSpec?
+    public var position: PointSpec?
+    public var badge: String?
+    public var listRowInsets: EdgeInsetsSpec?
+    public var listRowBackground: ShapeStyleSpec?
+    public var imageScale: String?
+    public var hidden: Bool
+    public var mask: ShapeStyleSpec?
+    public var hitTesting: Bool?
+    public var blendMode: String?
+    public var zIndex: Double?
+    public var blur: Double?
+    public var brightness: Double?
+    public var saturation: Double?
+    public var contrast: Double?
+    public var grayscale: Double?
+    public var hueRotation: Double?
+    public var colorInvert: Bool
+    public var colorMultiply: ColorSpec?
+    public var underline: Bool?
+    public var strikethrough: Bool?
+    public var italic: Bool?
+    /// `.ignoresSafeArea(edges:)`: the edges, or all four for `"all"`. Nil when not set.
+    public var ignoresSafeArea: [String]?
+    public var ignoresKeyboard: Bool
+    public var help: String?
+    public var matchedGeometry: String?
+    public var contentTransition: String?
+
+    public init(json: JSONValue) {
+        let fields = json.object ?? [:]
+        raw = fields
+        padding = EdgeInsetsSpec(json: fields.value("padding"))
+        font = FontSpec(json: fields.value("font"))
+        foreground = ShapeStyleSpec(json: fields.value("foreground"))
+        foregroundLevels = (fields.array("foregroundLevels") ?? []).compactMap(ShapeStyleSpec.init(json:))
+        background = ShapeStyleSpec(json: fields.value("background"))
+        frame = FrameSpec(json: fields.value("frame"))
+        cornerRadius = fields.double("cornerRadius")
+        backgroundCornerRadius = fields.double("backgroundCornerRadius")
+        opacity = fields.double("opacity")
+        disabled = fields.bool("disabled")
+        layoutPriority = fields.double("layoutPriority")
+        lineLimit = fields.int("lineLimit")
+        lineLimitLifted = fields["lineLimit"]?.isNull ?? false
+        lineLimitMin = fields.int("lineLimitMin")
+        multilineTextAlignment = fields.string("multilineTextAlignment")
+        fixedSizeHorizontal = fields.object("fixedSize")?.bool("horizontal")
+        fixedSizeVertical = fields.object("fixedSize")?.bool("vertical")
+        animation = AnimationSpec(json: fields.value("animation"))
+        animationToken = fields.double("animationToken")
+        labelIcon = fields.bool("labelIcon") ?? false
+        transition = fields["transition"].map(TransitionSpec.list(json:))
+        if let ratio = fields.object("aspectRatio") {
+            aspectRatio = .some(ratio.double("ratio"))
+            aspectRatioContentMode = ratio.string("contentMode")
+        } else {
+            aspectRatio = nil
+            aspectRatioContentMode = nil
+        }
+        offset = PointSpec(json: fields.value("offset"))
+        rotation = fields.double("rotation")
+        rotationAnchor = UnitPointSpec(json: fields.value("rotationAnchor"))
+        scale = PointSpec(json: fields.value("scale"))
+        scaleAnchor = UnitPointSpec(json: fields.value("scaleAnchor"))
+        shadow = ShadowSpec(json: fields.value("shadow"))
+        clipped = fields.bool("clipped") ?? false
+        tint = ColorSpec(json: fields.value("tint"))
+        position = PointSpec(json: fields.value("position"))
+        badge = fields.string("badge")
+        listRowInsets = EdgeInsetsSpec(json: fields.value("listRowInsets"))
+        listRowBackground = ShapeStyleSpec(json: fields.value("listRowBackground"))
+        imageScale = fields.string("imageScale")
+        hidden = fields.bool("hidden") ?? false
+        mask = ShapeStyleSpec(json: fields.value("mask"))
+        hitTesting = fields.bool("hitTesting")
+        blendMode = fields.string("blendMode")
+        zIndex = fields.double("zIndex")
+        blur = fields.double("blur")
+        brightness = fields.double("brightness")
+        saturation = fields.double("saturation")
+        contrast = fields.double("contrast")
+        grayscale = fields.double("grayscale")
+        hueRotation = fields.double("hueRotation")
+        colorInvert = fields.bool("colorInvert") ?? false
+        colorMultiply = ColorSpec(json: fields.value("colorMultiply"))
+        underline = fields.bool("underline")
+        strikethrough = fields.bool("strikethrough")
+        italic = fields.bool("italic")
+        if fields.string("ignoresSafeArea") == "all" {
+            ignoresSafeArea = ["top", "leading", "bottom", "trailing"]
+        } else {
+            ignoresSafeArea = fields.array("ignoresSafeArea")?.compactMap(\.string)
+        }
+        ignoresKeyboard = fields.bool("ignoresKeyboard") ?? false
+        help = fields.string("help")
+        matchedGeometry = fields.string("matchedGeometry")
+        contentTransition = fields.object("contentTransition")?.string("kind")
+    }
+
+    public init() {
+        self.init(json: .object([:]))
+    }
+
+    /// The style's field names, for the unsupported-field diagnostics and tests.
+    public var fieldNames: [String] { raw.keys.sorted() }
+}

package/swift/Sources/SwiftBrowserProtocol/Values.swift

@@ -0,0 +1,279 @@
+import Foundation
+
+// The value types of docs/ops-protocol.md (Web/src/protocol.ts), read from
+// their JSON. Each `init?(json:)` accepts the forms the protocol defines and
+// answers nil for anything else, so a renderer falls back to a default rather
+// than failing on a field it has not met.
+
+/// A color: explicit sRGB, a semantic name (`primary`, `blue`, `systemBackground`…)
+/// with an opacity multiplier, or an asset catalog color set.
+public enum ColorSpec: Equatable, Sendable {
+    case rgba(r: Double, g: Double, b: Double, a: Double)
+    case named(String, opacity: Double)
+    case asset(String, opacity: Double)
+
+    public init?(json: JSONValue) {
+        guard let fields = json.object else { return nil }
+        if let r = fields.double("r"), let g = fields.double("g"), let b = fields.double("b") {
+            self = .rgba(r: r, g: g, b: b, a: fields.double("a") ?? 1)
+        } else if let name = fields.string("name") {
+            self = .named(name, opacity: fields.double("a") ?? 1)
+        } else if let name = fields.string("named") {
+            self = .asset(name, opacity: fields.double("opacity") ?? 1)
+        } else {
+            return nil
+        }
+    }
+}
+
+/// A unit point in a view's bounds (0...1 on each axis).
+public struct UnitPointSpec: Equatable, Sendable {
+    public var x: Double
+    public var y: Double
+    public init(x: Double, y: Double) {
+        self.x = x
+        self.y = y
+    }
+    public init?(json: JSONValue) {
+        guard let x = json["x"].double, let y = json["y"].double else { return nil }
+        self.init(x: x, y: y)
+    }
+}
+
+public struct GradientStopSpec: Equatable, Sendable {
+    public var color: ColorSpec
+    public var location: Double
+    public init?(json: JSONValue) {
+        guard let color = ColorSpec(json: json["color"]), let location = json["location"].double else { return nil }
+        self.color = color
+        self.location = location
+    }
+}
+
+/// Everything a view can be painted with (`ShapeStyle` in protocol.ts).
+public enum ShapeStyleSpec: Equatable, Sendable {
+    case color(ColorSpec)
+    /// `.primary` ... `.quaternary` (1...4).
+    case hierarchical(level: Int, opacity: Double)
+    case linearGradient(stops: [GradientStopSpec], start: UnitPointSpec, end: UnitPointSpec, opacity: Double)
+    case radialGradient(stops: [GradientStopSpec], center: UnitPointSpec, startRadius: Double, endRadius: Double, opacity: Double)
+    case angularGradient(stops: [GradientStopSpec], center: UnitPointSpec, startAngle: Double, endAngle: Double, opacity: Double)
+    /// `Color.gradient`: a subtle vertical gradient from one color.
+    case colorGradient(ColorSpec, opacity: Double)
+    /// `ultraThin` ... `ultraThick`, `glass`, `glassClear`.
+    case material(String, opacity: Double)
+
+    public init?(json: JSONValue) {
+        guard let fields = json.object else { return nil }
+        let opacity = fields.double("opacity") ?? 1
+        if let color = ColorSpec(json: json) {
+            self = .color(color)
+        } else if let level = fields.int("hierarchical") {
+            self = .hierarchical(level: level, opacity: opacity)
+        } else if let gradient = fields.object("linearGradient"),
+                  let start = UnitPointSpec(json: gradient.value("start")), let end = UnitPointSpec(json: gradient.value("end"))
+        {
+            self = .linearGradient(stops: ShapeStyleSpec.stops(gradient), start: start, end: end, opacity: opacity)
+        } else if let gradient = fields.object("radialGradient"), let center = UnitPointSpec(json: gradient.value("center")) {
+            self = .radialGradient(
+                stops: ShapeStyleSpec.stops(gradient), center: center,
+                startRadius: gradient.double("startRadius") ?? 0, endRadius: gradient.double("endRadius") ?? 0, opacity: opacity
+            )
+        } else if let gradient = fields.object("angularGradient"), let center = UnitPointSpec(json: gradient.value("center")) {
+            self = .angularGradient(
+                stops: ShapeStyleSpec.stops(gradient), center: center,
+                startAngle: gradient.double("startAngle") ?? 0, endAngle: gradient.double("endAngle") ?? 360, opacity: opacity
+            )
+        } else if let color = ColorSpec(json: fields.value("colorGradient")) {
+            self = .colorGradient(color, opacity: opacity)
+        } else if let material = fields.string("material") {
+            self = .material(material, opacity: opacity)
+        } else {
+            return nil
+        }
+    }
+
+    private static func stops(_ gradient: JSONObject) -> [GradientStopSpec] {
+        (gradient.array("stops") ?? []).compactMap(GradientStopSpec.init(json:))
+    }
+}
+
+/// `padding`, `listRowInsets`: each edge optional.
+public struct EdgeInsetsSpec: Equatable, Sendable {
+    public var top: Double?
+    public var leading: Double?
+    public var bottom: Double?
+    public var trailing: Double?
+
+    public init(top: Double? = nil, leading: Double? = nil, bottom: Double? = nil, trailing: Double? = nil) {
+        self.top = top
+        self.leading = leading
+        self.bottom = bottom
+        self.trailing = trailing
+    }
+
+    public init?(json: JSONValue) {
+        guard let fields = json.object else { return nil }
+        self.init(top: fields.double("top"), leading: fields.double("leading"), bottom: fields.double("bottom"), trailing: fields.double("trailing"))
+    }
+}
+
+/// `font`: a text style that scales with Dynamic Type, or a fixed size
+/// (`relativeTo` names the style it scales like), with weight and design.
+public struct FontSpec: Equatable, Sendable {
+    public var textStyle: String?
+    public var size: Double?
+    public var relativeTo: String?
+    public var weight: String?
+    public var design: String?
+    public var monospacedDigit: Bool
+
+    public init?(json: JSONValue) {
+        guard let fields = json.object else { return nil }
+        textStyle = fields.string("textStyle")
+        size = fields.double("size")
+        relativeTo = fields.string("relativeTo")
+        weight = fields.string("weight")
+        design = fields.string("design")
+        monospacedDigit = fields.bool("monospacedDigit") ?? false
+    }
+}
+
+/// A frame dimension: points, or `"infinity"` to fill the available space.
+public enum DimensionSpec: Equatable, Sendable {
+    case points(Double)
+    case infinity
+
+    public init?(json: JSONValue) {
+        if let value = json.double { self = .points(value) } else if json.string == "infinity" { self = .infinity } else { return nil }
+    }
+}
+
+/// `.frame(width:height:)` or `.frame(minWidth:…)` with the content's alignment.
+public struct FrameSpec: Equatable, Sendable {
+    public var width: Double?
+    public var height: Double?
+    public var minWidth: DimensionSpec?
+    public var maxWidth: DimensionSpec?
+    public var minHeight: DimensionSpec?
+    public var maxHeight: DimensionSpec?
+    public var alignment: String
+
+    /// Whether this is the flexible form (any min/max), which `.frame(minWidth:…)` draws.
+    public var isFlexible: Bool { minWidth != nil || maxWidth != nil || minHeight != nil || maxHeight != nil }
+
+    public init?(json: JSONValue) {
+        guard let fields = json.object else { return nil }
+        width = fields.double("width")
+        height = fields.double("height")
+        minWidth = DimensionSpec(json: fields.value("minWidth"))
+        maxWidth = DimensionSpec(json: fields.value("maxWidth"))
+        minHeight = DimensionSpec(json: fields.value("minHeight"))
+        maxHeight = DimensionSpec(json: fields.value("maxHeight"))
+        alignment = fields.string("alignment") ?? "center"
+    }
+}
+
+/// A `commit`'s animation, or a `styled` element's `.animation(_:value:)`.
+public struct AnimationSpec: Equatable, Sendable {
+    /// `default`, `linear`, `easeIn`, `easeOut`, `easeInOut`, `spring`.
+    public var type: String
+    /// Seconds; 0.35 when absent. A spring's perceptual duration.
+    public var duration: Double?
+    /// A spring's bounce (0 critically damped).
+    public var bounce: Double?
+    public var delay: Double?
+    public var repeatCount: Int?
+    public var repeatsForever: Bool
+    public var autoreverses: Bool
+
+    public init?(json: JSONValue) {
+        guard let fields = json.object, let type = fields.string("type") else { return nil }
+        self.type = type
+        duration = fields.double("duration")
+        bounce = fields.double("bounce")
+        delay = fields.double("delay")
+        let repeatSpec = fields.object("repeat")
+        repeatCount = repeatSpec?.int("count")
+        repeatsForever = repeatSpec?.string("count") == "forever"
+        autoreverses = repeatSpec?.bool("autoreverses") ?? false
+    }
+
+    public var json: JSONValue {
+        var fields: JSONObject = ["type": .string(type)]
+        if let duration { fields["duration"] = .number(duration) }
+        if let bounce { fields["bounce"] = .number(bounce) }
+        if let delay { fields["delay"] = .number(delay) }
+        if repeatCount != nil || repeatsForever {
+            fields["repeat"] = .object([
+                "count": repeatsForever ? .string("forever") : .number(Double(repeatCount ?? 1)),
+                "autoreverses": .bool(autoreverses),
+            ])
+        }
+        return .object(fields)
+    }
+}
+
+/// One part of a `transition`: `opacity`, `scale`, `slide`, `move` (with an
+/// edge), `offset` (x, y), `identity`, or `asymmetric` (insertion and removal).
+public struct TransitionSpec: Equatable, Sendable {
+    public var kind: String
+    public var edge: String?
+    public var scale: Double?
+    public var x: Double?
+    public var y: Double?
+    public var insertion: [TransitionSpec]?
+    public var removal: [TransitionSpec]?
+
+    public init?(json: JSONValue) {
+        guard let fields = json.object, let kind = fields.string("kind") else { return nil }
+        self.kind = kind
+        edge = fields.string("edge")
+        scale = fields.double("scale")
+        x = fields.double("x")
+        y = fields.double("y")
+        insertion = fields["insertion"].map(TransitionSpec.list(json:))
+        removal = fields["removal"].map(TransitionSpec.list(json:))
+    }
+
+    /// A transition field: one part or a combined list of parts.
+    public static func list(json: JSONValue) -> [TransitionSpec] {
+        if let parts = json.array { return parts.compactMap(TransitionSpec.init(json:)) }
+        return TransitionSpec(json: json).map { [$0] } ?? []
+    }
+}
+
+public struct ShadowSpec: Equatable, Sendable {
+    public var color: ColorSpec?
+    public var radius: Double
+    public var x: Double
+    public var y: Double
+
+    public init?(json: JSONValue) {
+        guard let fields = json.object, let radius = fields.double("radius") else { return nil }
+        color = ColorSpec(json: fields.value("color"))
+        self.radius = radius
+        x = fields.double("x") ?? 0
+        y = fields.double("y") ?? 0
+    }
+}
+
+public struct PointSpec: Equatable, Sendable {
+    public var x: Double
+    public var y: Double
+    public init?(json: JSONValue) {
+        guard let fields = json.object else { return nil }
+        x = fields.double("x") ?? 0
+        y = fields.double("y") ?? 0
+    }
+}
+
+public struct SizeSpec: Equatable, Sendable {
+    public var width: Double
+    public var height: Double
+    public init?(json: JSONValue) {
+        guard let width = json["width"].double, let height = json["height"].double else { return nil }
+        self.width = width
+        self.height = height
+    }
+}

package/swift/Sources/SwiftBrowserTree/ElementNode.swift

@@ -0,0 +1,65 @@
+import Foundation
+import Observation
+import SwiftBrowserProtocol
+
+/// One element of the live tree: its id (stable for its life, assigned by the
+/// producer), its kind, its props as the last `create` or `update` left them,
+/// and its children in order.
+///
+/// Observable, so a SwiftUI view that reads one node's props re-evaluates
+/// when that node changes and not when another does: the granularity the
+/// protocol's `update` op already works at.
+@Observable
+public final class ElementNode: Identifiable {
+    public let id: Int
+    public let kind: String
+    public internal(set) var props: JSONObject
+    public internal(set) var children: [ElementNode] = []
+    public internal(set) weak var parent: ElementNode?
+
+    init(id: Int, kind: String, props: JSONObject) {
+        self.id = id
+        self.kind = kind
+        self.props = props
+    }
+
+    /// The root container, element id 0: never created or removed.
+    static func root() -> ElementNode { ElementNode(id: 0, kind: "root", props: [:]) }
+
+    /// The `styled` element's style (an empty style on any other kind).
+    public var style: Style { Style(json: props.value("style")) }
+
+    /// The first child, the one a wrapper kind (`styled`, `button`, `geometry`…) has.
+    public var child: ElementNode? { children.first }
+
+    /// The children of a kind.
+    public func children(ofKind kind: String) -> [ElementNode] { children.filter { $0.kind == kind } }
+
+    /// The children that are not of the given kinds (a screen's content, without its toolbars).
+    public func children(except kinds: Set<String>) -> [ElementNode] { children.filter { !kinds.contains($0.kind) } }
+
+    /// The index of this element among its parent's children, or nil when detached.
+    public var indexInParent: Int? { parent?.children.firstIndex { $0 === self } }
+
+    /// The nearest ancestor of a kind.
+    public func ancestor(ofKind kind: String) -> ElementNode? {
+        var node = parent
+        while let current = node {
+            if current.kind == kind { return current }
+            node = current.parent
+        }
+        return nil
+    }
+
+    /// The tree below this node as indented lines, `kind#id {props}`, for tests and logs.
+    public func dump(indent: Int = 0) -> String {
+        var lines: [String] = []
+        func visit(_ node: ElementNode, depth: Int) {
+            let props = node.props.isEmpty ? "" : " " + JSONValue.object(node.props).json
+            lines.append(String(repeating: "  ", count: depth) + "\(node.kind)#\(node.id)\(props)")
+            for child in node.children { visit(child, depth: depth + 1) }
+        }
+        visit(self, depth: indent)
+        return lines.joined(separator: "\n")
+    }
+}

package/swift/Sources/SwiftBrowserTree/OpTree.swift

@@ -0,0 +1,168 @@
+import Foundation
+import SwiftBrowserProtocol
+
+public struct OpTreeError: Error, CustomStringConvertible, Equatable {
+    public let message: String
+    public init(_ message: String) { self.message = message }
+    public var description: String { message }
+}
+
+/// The live element tree a renderer draws, kept current by applying ops
+/// (docs/ops-protocol.md, "Ops"). The counterpart of the web renderer's
+/// `elements` and `parents` maps (Web/src/renderer.ts), with Observation
+/// doing the invalidation: each `ElementNode` is observable, so whatever
+/// reads a node re-evaluates when an op changes it.
+///
+/// A pass is the ops up to and including a `commit`; the whole pass is
+/// applied inside one call of `animate`, so a host that sets
+/// `animate` to `withAnimation` gets the protocol's animated commits: every
+/// frame and style change of the pass animates, and children inserted or
+/// removed in it transition. `apply` may be called with several passes at
+/// once, or with part of one (the rest follows before the next commit).
+///
+/// Main-thread only, like the views reading it.
+@MainActor
+public final class OpTree {
+    /// The root container, element id 0.
+    public let root: ElementNode
+    private var nodes: [Int: ElementNode]
+    /// The ops of the current pass, until its `commit`.
+    private var pending: [Op] = []
+    /// How many passes were committed.
+    public private(set) var commits = 0
+    /// Ops applied that this tree does not render (`defaults`, `request`…), by name, for diagnostics.
+    public private(set) var unhandledOps: [String: Int] = [:]
+
+    /// Runs the body of a pass, animated as the commit asks (`withAnimation` on a SwiftUI host).
+    public var animate: (AnimationSpec?, () -> Void) -> Void = { _, body in body() }
+    /// Called after every committed pass.
+    public var onCommit: ((AnimationSpec?) -> Void)?
+    /// Where the renderer's events go (the app's `dispatch`).
+    public var onEvent: ((RendererEvent) -> Void)?
+    /// Ops this tree does not apply (a `request`, say), for the host to handle.
+    public var onOtherOp: ((String, JSONObject) -> Void)?
+
+    public init() {
+        root = ElementNode.root()
+        nodes = [0: root]
+    }
+
+    /// The element with this id, when it exists (created and not removed).
+    public func node(_ id: Int) -> ElementNode? { nodes[id] }
+
+    /// How many elements exist, the root included.
+    public var count: Int { nodes.count }
+
+    /// The root's props (`.preferredColorScheme`).
+    public var rootProps: RootProps { RootProps(props: root.props) }
+
+    /// Sends a renderer event to the app.
+    public func send(_ event: RendererEvent) {
+        onEvent?(event)
+    }
+
+    /// Applies ops in order. Throws on an op that cannot apply (an unknown
+    /// id, an insert into a missing parent); the ops before it have applied.
+    public func apply(_ ops: [Op]) throws {
+        for op in ops {
+            if case .commit(let animation) = op {
+                let pass = pending
+                pending.removeAll()
+                var failure: Error?
+                animate(animation) {
+                    do {
+                        for each in pass { try self.applyOne(each) }
+                    } catch {
+                        failure = error
+                    }
+                }
+                if let failure { throw failure }
+                commits += 1
+                onCommit?(animation)
+            } else {
+                pending.append(op)
+            }
+        }
+    }
+
+    /// Applies a JSON array of ops (what crosses the bridge).
+    public func apply(json: String) throws {
+        try apply(Op.decodeArray(json))
+    }
+
+    /// Applies the ops of a pass that had no `commit` yet, now (headless
+    /// streams end without one; tests use it).
+    public func flush() throws {
+        if pending.isEmpty { return }
+        try apply([.commit(animation: nil)])
+    }
+
+    private func applyOne(_ op: Op) throws {
+        switch op {
+        case .create(let id, let kind, let props):
+            guard id != 0 else { throw OpTreeError("create: id 0 is the root") }
+            if let existing = nodes[id] {
+                // The producer reuses an id only after removing it; a create
+                // for a live id replaces it in place (the web renderer does the same).
+                detach(existing)
+            }
+            nodes[id] = ElementNode(id: id, kind: kind, props: props)
+        case .update(let id, let props):
+            guard let node = nodes[id] else { throw OpTreeError("update: no element \(id)") }
+            if node.props != props { node.props = props }
+        case .insert(let parentId, let id, let index):
+            guard let node = nodes[id] else { throw OpTreeError("insert: no element \(id)") }
+            guard let parent = nodes[parentId] else { throw OpTreeError("insert: no parent \(parentId) for element \(id)") }
+            guard id != 0, !isAncestor(node, of: parent) else { throw OpTreeError("insert: element \(id) into its own subtree") }
+            if let current = node.parent {
+                if current === parent, let at = parent.children.firstIndex(where: { $0 === node }) {
+                    // A move among siblings.
+                    if at == index { return }
+                    var children = parent.children
+                    children.remove(at: at)
+                    children.insert(node, at: min(index, children.count))
+                    parent.children = children
+                    return
+                }
+                detach(node)
+            }
+            var children = parent.children
+            children.insert(node, at: min(max(index, 0), children.count))
+            parent.children = children
+            node.parent = parent
+        case .remove(let id):
+            guard id != 0 else { throw OpTreeError("remove: id 0 is the root") }
+            guard let node = nodes[id] else { throw OpTreeError("remove: no element \(id)") }
+            detach(node)
+            forget(node)
+        case .commit:
+            break
+        case .other(let name, let fields):
+            unhandledOps[name, default: 0] += 1
+            onOtherOp?(name, fields)
+        }
+    }
+
+    private func isAncestor(_ node: ElementNode, of other: ElementNode) -> Bool {
+        var current: ElementNode? = other
+        while let each = current {
+            if each === node { return true }
+            current = each.parent
+        }
+        return false
+    }
+
+    private func detach(_ node: ElementNode) {
+        guard let parent = node.parent else { return }
+        parent.children.removeAll { $0 === node }
+        node.parent = nil
+    }
+
+    private func forget(_ node: ElementNode) {
+        nodes[node.id] = nil
+        for child in node.children { forget(child) }
+    }
+
+    /// The whole tree as indented lines (tests, logs).
+    public func dump() -> String { root.dump() }
+}