@craft-native/ios 0.0.113 → 0.0.118

package/README.md

@@ -106,7 +106,7 @@ In Xcode:
 
 ### Experimental WebView-free screen
 
-The opt-in `native` renderer hosts compiled `.stx` screens in JavaScriptCore and renders their `View`, `Text`, `Button`, and `TextInput` nodes as UIKit controls. The default remains `web`; existing iOS apps are unchanged. This is a vertical slice, not yet a replacement for the WebView renderer: the native bridge supports device info, haptics, clipboard read/write, and multi-screen navigation. Lists and the rest of Craft's device APIs still need native adapters. Enable `enableHaptics` and `enableClipboard` in `craft.config.json` before using those two capabilities; disabled calls preserve Craft's `CAPABILITY_DISABLED` rejection code.
+The opt-in `native` renderer hosts compiled `.stx` screens in JavaScriptCore and renders their `View`, `SafeAreaView`, `Text`, `Button`, `TextInput`, `Image`, `ScrollView`, and recycling `FlatList` nodes as UIKit controls. `FlatList` uses `UICollectionView` with stable keyed rows, incremental diffs, grids, horizontal and inverted layouts, list chrome, and end-reached pagination. The default remains `web`; existing iOS apps are unchanged. Most Craft device APIs still need native adapters. Enable `enableHaptics` and `enableClipboard` in `craft.config.json` before using those two capabilities; disabled calls preserve Craft's `CAPABILITY_DISABLED` rejection code. The portable component, list, style, image-source, event, accessibility, and reconciliation behavior is specified in the [Native STX guide](../../docs/guides/native-stx.md).
 
 ```bash
 craft ios init NativeDemo --renderer native --output ./ios-native
@@ -117,7 +117,15 @@ craft ios run --output ./ios-native --simulator
 
 `stx-native` is currently a private package in the sibling [stx repository](https://github.com/stacksjs/stx). Run its source CLI with Bun until it is published or linked locally. A runnable screen is in [`fixtures/native-screen/Screen.stx`](./fixtures/native-screen/Screen.stx). In native mode, the app never instantiates `WKWebView`; a missing `dist/native-screen.js` fails the build rather than silently opening the web placeholder.
 
-Native screen updates reconcile the UIKit tree by sibling-scoped `key` (or `testID` for existing screens); unkeyed children reuse their position. `TextInput` objects therefore keep focus and selection while unrelated labels and buttons change. On macOS, `bun packages/ios/scripts/test-native-render.ts` runs the renderer's unit and simulator UI tests.
+Native screen updates use the versioned mutation protocol when the bundle
+supports it and fall back to whole-document rendering for older bundles.
+Updates reconcile the UIKit tree by sibling-scoped `key` (or `testID` for
+existing screens); unkeyed children reuse their position. `TextInput` objects
+therefore keep focus and selection while unrelated labels and buttons change.
+The protocol wire format, atomic validation, revisions, and error codes are in
+the [Native STX guide](../../docs/guides/native-stx.md). On macOS,
+`bun packages/ios/scripts/test-native-render.ts` runs the renderer's unit and
+simulator UI tests.
 
 For multiple native screens, configure named `.stx` routes and an initial screen in `stx-native.config.json` (see [`fixtures/native-navigation`](./fixtures/native-navigation)). Compile without a positional file: `stx-native compile --format bundle --output ./screen.js`. A screen can call `craft.navigation.push('details', { id: 7 })`, `.replace('home')`, or `.back()`; the destination reads `craft.route.params`. Craft uses a native navigation stack, so the back button and edge-swipe reveal the existing controller and retain its JavaScript and input state. `bun packages/ios/scripts/test-native-navigation.ts` compiles the fixture and runs its simulator test; the default WebView renderer is unchanged.
 
@@ -431,6 +439,20 @@ await window.craft.restorePurchases();
 window.craft.setKeepAwake(true);  // Prevent screen dimming
 window.craft.setKeepAwake(false); // Allow screen dimming
 
+// Speech: short spoken cues that duck the person's music instead of stopping
+// it, and play with the silent switch on. Always available (no config flag).
+// Resolves when the utterance ends: true if spoken, false if stopped or
+// interrupted. Rejects with INVALID_ARGUMENT for empty text.
+const spoken = await window.craft.speech.speak('Rest, 15 seconds. Up next: Dead Bug', {
+  rate: 1,          // 0.5 to 2, 1 = normal
+  language: 'en-US', // BCP-47; defaults to the device's language
+  interrupt: true   // default: stop what is being said first; false queues
+});
+await window.craft.speech.stop(); // pending speak() calls resolve false
+// Or `import { speech } from 'craft-native/mobile'`: the same calls, falling
+// back to the Web Speech API in a browser and resolving false where neither
+// exists. speech.isAvailable() says which.
+
 // Orientation Lock
 window.craft.lockOrientation('portrait');   // Lock to portrait
 window.craft.lockOrientation('landscape');  // Lock to landscape

package/dist/cli.js

@@ -411,7 +411,9 @@ async function init(options) {
   const swiftSource = swiftTemplate.replace(/CraftApp/g, `${name}App`).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
   writeFileSync(join(output, "Sources", `${name}App.swift`), swiftSource);
   cpSync(join(TEMPLATES_DIR, "CraftNativeScreen.swift"), join(output, "Sources", "CraftNativeScreen.swift"));
+  cpSync(join(TEMPLATES_DIR, "CraftNativeFlatList.swift"), join(output, "Sources", "CraftNativeFlatList.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.swift"));
+  cpSync(join(TEMPLATES_DIR, "CraftNativeMutation.swift"), join(output, "Sources", "CraftNativeMutation.swift"));
   const infoPlistTemplate = readFileSync(join(TEMPLATES_DIR, "Info.plist.template"), "utf-8");
   const infoPlist = infoPlistTemplate.replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{VERSION\}\}/g, config.version || "1.0.0").replace(/\{\{BUILD_NUMBER\}\}/g, config.buildNumber || "1").replace(/\{\{UI_STYLE\}\}/g, renderAppearance(config).interfaceStyle).replace(/\{\{STATUS_BAR_STYLE\}\}/g, renderAppearance(config).statusBarStyle).replace(/\{\{ORIENTATIONS\}\}/g, renderOrientations(config)).replace(/\{\{USAGE_DESCRIPTIONS\}\}/g, renderUsageDescriptions(config)).replace(/\{\{URL_TYPES\}\}/g, renderUrlTypes(config)).replace(/\{\{BACKGROUND_MODES\}\}/g, renderBackgroundModes(config)).replace(/\{\{LIVE_ACTIVITY_SUPPORT\}\}/g, config.enableLiveActivities ? `    <key>NSSupportsLiveActivities</key>
     <true/>

package/dist/index.js

@@ -406,7 +406,9 @@ async function init(options) {
   const swiftSource = swiftTemplate.replace(/CraftApp/g, `${name}App`).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
   writeFileSync(join(output, "Sources", `${name}App.swift`), swiftSource);
   cpSync(join(TEMPLATES_DIR, "CraftNativeScreen.swift"), join(output, "Sources", "CraftNativeScreen.swift"));
+  cpSync(join(TEMPLATES_DIR, "CraftNativeFlatList.swift"), join(output, "Sources", "CraftNativeFlatList.swift"));
   cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.swift"));
+  cpSync(join(TEMPLATES_DIR, "CraftNativeMutation.swift"), join(output, "Sources", "CraftNativeMutation.swift"));
   const infoPlistTemplate = readFileSync(join(TEMPLATES_DIR, "Info.plist.template"), "utf-8");
   const infoPlist = infoPlistTemplate.replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{VERSION\}\}/g, config.version || "1.0.0").replace(/\{\{BUILD_NUMBER\}\}/g, config.buildNumber || "1").replace(/\{\{UI_STYLE\}\}/g, renderAppearance(config).interfaceStyle).replace(/\{\{STATUS_BAR_STYLE\}\}/g, renderAppearance(config).statusBarStyle).replace(/\{\{ORIENTATIONS\}\}/g, renderOrientations(config)).replace(/\{\{USAGE_DESCRIPTIONS\}\}/g, renderUsageDescriptions(config)).replace(/\{\{URL_TYPES\}\}/g, renderUrlTypes(config)).replace(/\{\{BACKGROUND_MODES\}\}/g, renderBackgroundModes(config)).replace(/\{\{LIVE_ACTIVITY_SUPPORT\}\}/g, config.enableLiveActivities ? `    <key>NSSupportsLiveActivities</key>
     <true/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-native/ios",
-  "version": "0.0.113",
+  "version": "0.0.118",
   "homepage": "https://github.com/craft-native/craft/tree/main/packages/ios#readme",
   "repository": {
     "type": "git",

package/templates/CraftApp.swift

@@ -722,6 +722,24 @@ struct CraftWebView: UIViewRepresentable {
         // Keep awake
         private var isKeepingAwake = false
 
+        // Speech synthesis. One synthesizer for the life of the web view, so a
+        // cue can interrupt the one before it; each utterance it has not
+        // finished yet is held beside the call waiting on it.
+        private lazy var speechSynthesizer: AVSpeechSynthesizer = {
+            let synthesizer = AVSpeechSynthesizer()
+            synthesizer.delegate = self
+            return synthesizer
+        }()
+        private var pendingUtterances: [(utterance: AVSpeechUtterance, callbackId: String?)] = []
+        /// What the session was before speech claimed it; nil while speech
+        /// does not hold it.
+        private var speechAudioSessionToRestore: (AVAudioSession.Category, AVAudioSession.Mode, AVAudioSession.CategoryOptions)?
+        /// Activating and deactivating the audio session blocks until the
+        /// audio hardware answers, which iOS flags as a hang risk on the main
+        /// thread. They run here instead, in order, and the session state
+        /// above is only touched here.
+        private let speechAudioQueue = DispatchQueue(label: "craft.speech.audio")
+
         // Orientation lock
         private var lockedOrientation: UIInterfaceOrientationMask?
 
@@ -1058,6 +1076,16 @@ struct CraftWebView: UIViewRepresentable {
                 } else {
                     rejectCallback(callbackId, error: "setFlashlight needs true or false", code: "INVALID_ARGUMENT")
                 }
+            // Speech synthesis. Ungated, like the flashlight: speaking needs no
+            // permission and no entitlement.
+            case "speak":
+                if let text = body["text"] as? String, !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                    speak(text, body: body, callbackId: callbackId)
+                } else {
+                    rejectCallback(callbackId, error: "speak needs some text to say", code: "INVALID_ARGUMENT")
+                }
+            case "stopSpeaking":
+                stopSpeaking(callbackId: callbackId)
             // Vibrate pattern
             case "vibrate":
                 if let pattern = body["pattern"] as? [Int] {
@@ -1850,6 +1878,7 @@ struct CraftWebView: UIViewRepresentable {
                     orientationLock: \(config.enableOrientationLock),
                     deepLinks: \(config.enableDeepLinks),
                     flashlight: true,
+                    speech: true,
                     network: true,
                     deviceInfo: true,
                     badge: true,
@@ -2788,6 +2817,37 @@ struct CraftWebView: UIViewRepresentable {
                     });
                 },
 
+                // Speech synthesis. speak() settles when the utterance ends:
+                // true when it was spoken, false when something stopped it.
+                // No timeout, because a long sentence at a slow rate can
+                // outlast any deadline that would be fair to a short one.
+                speech: {
+                    speak: function(text, options) {
+                        var self = window.craft;
+                        var id = 'cb_' + (++self._callbackId);
+                        options = options || {};
+                        window.webkit.messageHandlers.craft.postMessage({
+                            action: 'speak',
+                            text: text == null ? '' : String(text),
+                            rate: typeof options.rate === 'number' ? options.rate : null,
+                            language: typeof options.language === 'string' ? options.language : null,
+                            interrupt: options.interrupt !== false,
+                            callbackId: id
+                        });
+                        return new Promise(function(resolve, reject) {
+                            self._callbacks[id] = {resolve: resolve, reject: reject};
+                        });
+                    },
+                    stop: function() {
+                        var self = window.craft;
+                        var id = 'cb_' + (++self._callbackId);
+                        window.webkit.messageHandlers.craft.postMessage({action: 'stopSpeaking', callbackId: id});
+                        return new Promise(function(resolve, reject) {
+                            self._callbacks[id] = {resolve: resolve, reject: reject};
+                        });
+                    }
+                },
+
                 // Orientation Lock
                 lockOrientation: function(orientation) {
                     var self = this;
@@ -4762,6 +4822,153 @@ struct CraftWebView: UIViewRepresentable {
             }
         }
 
+        // MARK: - Speech Synthesis
+        //
+        // Native rather than the page's own `speechSynthesis`, which in a
+        // WKWebView plays through the default soloAmbient session: it stops
+        // the person's music and the silent switch mutes it. A workout cue has
+        // to do neither, so the session is set up here for as long as there is
+        // something to say, and handed back when there is not.
+
+        private func speak(_ text: String, body: [String: Any], callbackId: String?) {
+            DispatchQueue.main.async {
+                if body["interrupt"] as? Bool ?? true {
+                    self.cancelPendingSpeech()
+                }
+
+                let utterance = AVSpeechUtterance(string: text)
+                utterance.rate = Self.utteranceRate(body["rate"] as? Double ?? 1)
+                // An unknown language finds no voice, and a nil voice is the
+                // device's own, which is the default anyway.
+                if let language = body["language"] as? String, !language.isEmpty,
+                   let voice = AVSpeechSynthesisVoice(language: language) {
+                    utterance.voice = voice
+                }
+
+                self.pendingUtterances.append((utterance, callbackId))
+                self.claimAudioSessionForSpeech {
+                    // Stopped while the session was being set up: say nothing.
+                    guard self.pendingUtterances.contains(where: { $0.utterance === utterance }) else { return }
+                    self.speechSynthesizer.speak(utterance)
+                }
+            }
+        }
+
+        private func stopSpeaking(callbackId: String?) {
+            DispatchQueue.main.async {
+                // When something was playing, its didCancel releases the
+                // session once the audio has actually stopped; deactivating
+                // before that fails as busy and leaves the music ducked.
+                if !self.cancelPendingSpeech() { self.releaseAudioSessionIfSilent() }
+                self.resolveCallback(callbackId, result: true)
+            }
+        }
+
+        /// Stop what is being said and settle every call waiting on it, false.
+        /// Returns whether the synthesizer was making a sound.
+        ///
+        /// Settled here rather than in `didCancel`, because the delegate hears
+        /// about the utterance that was playing and nothing about the ones
+        /// queued behind it, whose calls would otherwise never settle.
+        @discardableResult
+        private func cancelPendingSpeech() -> Bool {
+            let waiting = pendingUtterances
+            pendingUtterances.removeAll()
+            let synthesizer = speechSynthesizer
+            let wasSounding = synthesizer.isSpeaking || synthesizer.isPaused
+            if wasSounding { synthesizer.stopSpeaking(at: .immediate) }
+            for entry in waiting {
+                resolveCallback(entry.callbackId, result: false)
+            }
+            return wasSounding
+        }
+
+        /// The page's rate, where 1 is normal, on AVSpeechUtterance's scale.
+        ///
+        /// Apple's scale is not linear in speed: the default sits at 0.5 and
+        /// the maximum is far faster than twice that. So a slower rate scales
+        /// the default down in proportion, and a faster one climbs toward the
+        /// maximum at half the slope, which keeps 2 brisk but intelligible.
+        private static func utteranceRate(_ rate: Double) -> Float {
+            let requested = Float(min(max(rate.isFinite ? rate : 1, 0.5), 2))
+            let normal = AVSpeechUtteranceDefaultSpeechRate
+            let mapped = requested <= 1
+                ? normal * requested
+                : normal + (AVSpeechUtteranceMaximumSpeechRate - normal) * (requested - 1) / 2
+            return min(max(mapped, AVSpeechUtteranceMinimumSpeechRate), AVSpeechUtteranceMaximumSpeechRate)
+        }
+
+        /// Duck the music rather than stop it, and play through the silent
+        /// switch.
+        ///
+        /// `.playback` is what the switch does not mute, `.duckOthers` lowers
+        /// the music under the cue, and the spoken-audio option pauses a
+        /// podcast rather than talking over it. Left alone while recognition
+        /// or a recording holds the session: switching it to playback would
+        /// cut their microphone off mid-take.
+        ///
+        /// Set up on the speech queue, then `start` runs on the main thread.
+        private func claimAudioSessionForSpeech(then start: @escaping () -> Void) {
+            let microphoneBusy = audioEngine.isRunning || (audioRecorder?.isRecording ?? false)
+            speechAudioQueue.async {
+                if self.speechAudioSessionToRestore == nil && !microphoneBusy {
+                    let session = AVAudioSession.sharedInstance()
+                    let previous = (session.category, session.mode, session.categoryOptions)
+                    do {
+                        try session.setCategory(.playback, mode: .voicePrompt, options: [.duckOthers, .interruptSpokenAudioAndMixWithOthers])
+                        try session.setActive(true)
+                        self.speechAudioSessionToRestore = previous
+                    } catch {
+                        // Still speak, through whatever session the app has: a
+                        // cue that does not duck beats one that never plays.
+                        print("[Craft] Speech audio session failed: \(error.localizedDescription)")
+                    }
+                }
+                DispatchQueue.main.async(execute: start)
+            }
+        }
+
+        /// Hand the audio back once nothing is left to say, so the music
+        /// returns to full volume instead of staying ducked, and put back the
+        /// category the app had, so the page's own media plays as before.
+        ///
+        /// Checked on the main thread, where the queue of utterances lives, and
+        /// done on the speech queue after any setup already asked for, so a
+        /// cue that arrives meanwhile reclaims the session after this.
+        private func releaseAudioSessionIfSilent(retry: Bool = true) {
+            guard pendingUtterances.isEmpty else { return }
+            speechAudioQueue.async {
+                guard let previous = self.speechAudioSessionToRestore else { return }
+                let session = AVAudioSession.sharedInstance()
+                do {
+                    try session.setActive(false, options: .notifyOthersOnDeactivation)
+                } catch {
+                    // Busy: the synthesizer's audio has not quite drained, or
+                    // the page has its own media playing. Once more shortly
+                    // covers the first; for the second, staying active is
+                    // right, and the ducking still ends when the music app
+                    // hears nothing more.
+                    if retry {
+                        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
+                            self.releaseAudioSessionIfSilent(retry: false)
+                        }
+                        return
+                    }
+                    print("[Craft] Speech audio session release failed: \(error.localizedDescription)")
+                }
+                self.speechAudioSessionToRestore = nil
+                try? session.setCategory(previous.0, mode: previous.1, options: previous.2)
+            }
+        }
+
+        fileprivate func speechDidEnd(_ utterance: AVSpeechUtterance, spoken: Bool) {
+            if let index = pendingUtterances.firstIndex(where: { $0.utterance === utterance }) {
+                let entry = pendingUtterances.remove(at: index)
+                resolveCallback(entry.callbackId, result: spoken)
+            }
+            releaseAudioSessionIfSilent()
+        }
+
         // MARK: - Orientation Lock
         private func lockOrientation(_ orientation: String, callbackId: String?) {
             var mask: UIInterfaceOrientationMask = .all
@@ -6698,6 +6905,20 @@ extension URL {
 }
 
 // MARK: - Contact Picker Delegate
+// MARK: - AVSpeechSynthesizerDelegate
+//
+// The end of an utterance is what `craft.speech.speak()` waits for. Hopped to
+// main because every piece of speech state is touched there and nowhere else.
+extension CraftWebView.Coordinator: AVSpeechSynthesizerDelegate {
+    func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didFinish utterance: AVSpeechUtterance) {
+        DispatchQueue.main.async { self.speechDidEnd(utterance, spoken: true) }
+    }
+
+    func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didCancel utterance: AVSpeechUtterance) {
+        DispatchQueue.main.async { self.speechDidEnd(utterance, spoken: false) }
+    }
+}
+
 extension CraftWebView.Coordinator: CNContactPickerDelegate {
     func contactPicker(_ picker: CNContactPickerViewController, didSelect contact: CNContact) {
         let contactData = formatContact(contact)

package/templates/CraftNativeFlatList.swift

@@ -0,0 +1,323 @@
+import UIKit
+
+private final class CraftNativeFlatListLayout: UICollectionViewFlowLayout {
+    override func shouldInvalidateLayout(forBoundsChange newBounds: CGRect) -> Bool {
+        guard let current = collectionView?.bounds else { return true }
+        return scrollDirection == .vertical
+            ? abs(current.width - newBounds.width) > .ulpOfOne
+            : abs(current.height - newBounds.height) > .ulpOfOne
+    }
+}
+
+/// A keyed, recycling native list used by the stx-native FlatList primitive.
+/// The screen controller owns rendered row state; this view owns collection
+/// diffs, viewport state, and UICollectionView cell reuse.
+final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowLayout {
+    typealias RenderItem = (_ node: [String: Any], _ identity: String, _ previous: UIView?) -> UIView
+
+    private final class Cell: UICollectionViewCell {
+        static let reuseIdentifier = "CraftNativeFlatListCell"
+
+        private(set) var representedIdentity: String?
+        private(set) var hostedView: UIView?
+        var onRecycle: ((String) -> Void)?
+
+        override func prepareForReuse() {
+            super.prepareForReuse()
+            releaseHostedView()
+        }
+
+        func host(_ view: UIView, identity: String) {
+            if representedIdentity != identity { releaseHostedView() }
+            representedIdentity = identity
+            guard hostedView !== view else { return }
+            hostedView?.removeFromSuperview()
+            hostedView = view
+            view.translatesAutoresizingMaskIntoConstraints = false
+            contentView.addSubview(view)
+            NSLayoutConstraint.activate([
+                view.topAnchor.constraint(equalTo: contentView.topAnchor),
+                view.bottomAnchor.constraint(equalTo: contentView.bottomAnchor),
+                view.leadingAnchor.constraint(equalTo: contentView.leadingAnchor),
+                view.trailingAnchor.constraint(equalTo: contentView.trailingAnchor),
+            ])
+        }
+
+        func releaseHostedView() {
+            if let identity = representedIdentity { onRecycle?(identity) }
+            hostedView?.removeFromSuperview()
+            hostedView = nil
+            representedIdentity = nil
+            onRecycle = nil
+        }
+
+        override func preferredLayoutAttributesFitting(
+            _ layoutAttributes: UICollectionViewLayoutAttributes
+        ) -> UICollectionViewLayoutAttributes {
+            guard let hostedView = hostedView else { return layoutAttributes }
+            let attributes = layoutAttributes.copy() as! UICollectionViewLayoutAttributes
+            let target = CGSize(width: layoutAttributes.size.width, height: UIView.layoutFittingCompressedSize.height)
+            let measured = hostedView.systemLayoutSizeFitting(
+                target,
+                withHorizontalFittingPriority: .required,
+                verticalFittingPriority: .fittingSizeLevel
+            )
+            attributes.size.height = max(1, measured.height)
+            return attributes
+        }
+    }
+
+    private struct Item {
+        let identity: String
+        let node: [String: Any]
+        let signature: Data
+        let isChrome: Bool
+    }
+
+    private struct ViewportAnchor {
+        let identity: String
+        let distanceFromOrigin: CGFloat
+    }
+
+    private let flowLayout: UICollectionViewFlowLayout
+    private var diffableDataSource: UICollectionViewDiffableDataSource<Int, String>!
+    private var items: [Item] = []
+    private var itemsByIdentity: [String: Item] = [:]
+    private var renderItem: RenderItem?
+    private var recycleItem: ((String) -> Void)?
+    private var endReached: (() -> Void)?
+    private var endReachedThreshold = 0.1
+    private var endReachedSignature: String?
+    private var columns = 1
+    private var isApplyingSnapshot = false
+    private var pendingApply: (() -> Void)?
+
+    init() {
+        let layout = CraftNativeFlatListLayout()
+        layout.estimatedItemSize = CGSize(width: 320, height: 44)
+        layout.minimumLineSpacing = 0
+        layout.minimumInteritemSpacing = 0
+        flowLayout = layout
+        super.init(frame: .zero, collectionViewLayout: layout)
+        backgroundColor = .clear
+        alwaysBounceVertical = true
+        delegate = self
+        register(Cell.self, forCellWithReuseIdentifier: Cell.reuseIdentifier)
+        diffableDataSource = UICollectionViewDiffableDataSource<Int, String>(collectionView: self) {
+            [weak self] collectionView, indexPath, identity in
+            guard let self = self,
+                  let item = self.itemsByIdentity[identity],
+                  let cell = collectionView.dequeueReusableCell(
+                    withReuseIdentifier: Cell.reuseIdentifier,
+                    for: indexPath
+                  ) as? Cell,
+                  let renderItem = self.renderItem else { return UICollectionViewCell() }
+            let view = renderItem(item.node, identity, cell.hostedView)
+            cell.onRecycle = self.recycleItem
+            cell.host(view, identity: identity)
+            return cell
+        }
+    }
+
+    required init?(coder: NSCoder) { nil }
+
+    var visibleItemIdentities: [String] {
+        indexPathsForVisibleItems
+            .sorted { $0.item < $1.item }
+            .compactMap { diffableDataSource.itemIdentifier(for: $0) }
+    }
+
+    func apply(
+        nodes: [[String: Any]],
+        horizontal: Bool,
+        columns: Int,
+        inverted: Bool,
+        endReachedThreshold: Double,
+        renderItem: @escaping RenderItem,
+        recycleItem: @escaping (String) -> Void,
+        endReached: (() -> Void)?
+    ) {
+        if isApplyingSnapshot {
+            pendingApply = { [weak self] in
+                self?.apply(
+                    nodes: nodes,
+                    horizontal: horizontal,
+                    columns: columns,
+                    inverted: inverted,
+                    endReachedThreshold: endReachedThreshold,
+                    renderItem: renderItem,
+                    recycleItem: recycleItem,
+                    endReached: endReached
+                )
+            }
+            return
+        }
+        isApplyingSnapshot = true
+
+        self.renderItem = renderItem
+        self.recycleItem = recycleItem
+        self.endReached = endReached
+        self.endReachedThreshold = max(0, endReachedThreshold)
+        self.columns = max(1, columns)
+
+        layoutIfNeeded()
+        let oldItems = itemsByIdentity
+        let viewportAnchor = currentViewportAnchor()
+        var seen: [String: Int] = [:]
+        var next = nodes.enumerated().map { index, node -> Item in
+            let base = Self.identity(for: node) ?? "index:\(index)"
+            let occurrence = seen[base, default: 0]
+            seen[base] = occurrence + 1
+            let identity = occurrence == 0 ? base : "\(base)#\(occurrence)"
+            let props = node["props"] as? [String: Any] ?? [:]
+            let role = props["listRole"] as? String
+            let signature = (try? JSONSerialization.data(withJSONObject: node, options: [.sortedKeys])) ?? Data()
+            return Item(identity: identity, node: node, signature: signature, isChrome: role != nil && role != "item")
+        }
+        if inverted { next.reverse() }
+        items = next
+        itemsByIdentity = Dictionary(uniqueKeysWithValues: next.map { ($0.identity, $0) })
+
+        flowLayout.scrollDirection = horizontal ? .horizontal : .vertical
+        alwaysBounceHorizontal = horizontal
+        alwaysBounceVertical = !horizontal
+        showsHorizontalScrollIndicator = horizontal
+        showsVerticalScrollIndicator = !horizontal
+        flowLayout.invalidateLayout()
+
+        let nextIds = Set(itemsByIdentity.keys)
+        for identity in oldItems.keys where !nextIds.contains(identity) { recycleItem(identity) }
+        let changed = next.compactMap { item -> String? in
+            guard let old = oldItems[item.identity], old.signature != item.signature else { return nil }
+            return item.identity
+        }
+
+        var snapshot = NSDiffableDataSourceSnapshot<Int, String>()
+        snapshot.appendSections([0])
+        snapshot.appendItems(next.map(\.identity), toSection: 0)
+        let retainedOffset = contentOffset
+        diffableDataSource.apply(snapshot, animatingDifferences: false) { [weak self] in
+            guard let self = self else { return }
+            let live = Set(self.diffableDataSource.snapshot().itemIdentifiers)
+            let changedLive = changed.filter { live.contains($0) }
+            let restoreViewport = { [weak self] in
+                guard let self = self else { return }
+                self.layoutIfNeeded()
+                if let viewportAnchor = viewportAnchor {
+                    self.restore(viewportAnchor)
+                } else {
+                    self.setContentOffset(self.clamped(retainedOffset), animated: false)
+                }
+                self.finishApplyingSnapshot()
+            }
+            if !changedLive.isEmpty {
+                var update = self.diffableDataSource.snapshot()
+                update.reconfigureItems(changedLive)
+                self.diffableDataSource.apply(update, animatingDifferences: false, completion: restoreViewport)
+            } else {
+                restoreViewport()
+            }
+        }
+
+        let dataItems = next.filter { !$0.isChrome }
+        let contentSignature = "\(dataItems.count):\(dataItems.last?.identity ?? "empty")"
+        if contentSignature != endReachedSignature { endReachedSignature = nil }
+    }
+
+    func discardAll() {
+        visibleCells.compactMap { $0 as? Cell }.forEach { $0.releaseHostedView() }
+        itemsByIdentity.keys.forEach { recycleItem?($0) }
+        items = []
+        itemsByIdentity = [:]
+        renderItem = nil
+        recycleItem = nil
+        endReached = nil
+    }
+
+    func scrollViewDidScroll(_ scrollView: UIScrollView) { evaluateEndReached() }
+
+    func collectionView(
+        _ collectionView: UICollectionView,
+        layout collectionViewLayout: UICollectionViewLayout,
+        sizeForItemAt indexPath: IndexPath
+    ) -> CGSize {
+        guard items.indices.contains(indexPath.item) else { return CGSize(width: bounds.width, height: 44) }
+        let item = items[indexPath.item]
+        if flowLayout.scrollDirection == .horizontal {
+            return CGSize(width: max(1, bounds.width * 0.8), height: max(1, bounds.height))
+        }
+        let count = item.isChrome ? 1 : columns
+        let spacing = flowLayout.minimumInteritemSpacing * CGFloat(count - 1)
+        return CGSize(width: max(1, (bounds.width - spacing) / CGFloat(count)), height: 44)
+    }
+
+    private func evaluateEndReached() {
+        guard !isApplyingSnapshot, pendingApply == nil,
+              let endReached = endReached,
+              let lastVisible = indexPathsForVisibleItems.map(\.item).max() else { return }
+        let dataIndices = items.indices.filter { !items[$0].isChrome }
+        guard !dataIndices.isEmpty,
+              let lastDataOrdinal = dataIndices.lastIndex(where: { $0 <= lastVisible }) else { return }
+        let remaining = dataIndices.count - lastDataOrdinal - 1
+        let thresholdItems = max(1, Int(ceil(Double(dataIndices.count) * endReachedThreshold)))
+        guard remaining <= thresholdItems else { return }
+        let lastIdentity = items[dataIndices[dataIndices.count - 1]].identity
+        let signature = "\(dataIndices.count):\(lastIdentity)"
+        guard endReachedSignature != signature else { return }
+        endReachedSignature = signature
+        endReached()
+    }
+
+    private func finishApplyingSnapshot() {
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            self.isApplyingSnapshot = false
+            if let pendingApply = self.pendingApply {
+                self.pendingApply = nil
+                pendingApply()
+                return
+            }
+            self.evaluateEndReached()
+        }
+    }
+
+    private func clamped(_ offset: CGPoint) -> CGPoint {
+        CGPoint(
+            x: min(max(-adjustedContentInset.left, offset.x), max(-adjustedContentInset.left, contentSize.width - bounds.width + adjustedContentInset.right)),
+            y: min(max(-adjustedContentInset.top, offset.y), max(-adjustedContentInset.top, contentSize.height - bounds.height + adjustedContentInset.bottom))
+        )
+    }
+
+    private func currentViewportAnchor() -> ViewportAnchor? {
+        let horizontal = flowLayout.scrollDirection == .horizontal
+        let ordered = indexPathsForVisibleItems.sorted { lhs, rhs in
+            let left = layoutAttributesForItem(at: lhs)?.frame
+            let right = layoutAttributesForItem(at: rhs)?.frame
+            return horizontal ? (left?.minX ?? 0) < (right?.minX ?? 0) : (left?.minY ?? 0) < (right?.minY ?? 0)
+        }
+        guard let indexPath = ordered.first,
+              let identity = diffableDataSource.itemIdentifier(for: indexPath),
+              let frame = layoutAttributesForItem(at: indexPath)?.frame else { return nil }
+        let distance = horizontal ? frame.minX - contentOffset.x : frame.minY - contentOffset.y
+        return ViewportAnchor(identity: identity, distanceFromOrigin: distance)
+    }
+
+    private func restore(_ anchor: ViewportAnchor) {
+        guard let indexPath = diffableDataSource.indexPath(for: anchor.identity),
+              let frame = layoutAttributesForItem(at: indexPath)?.frame else { return }
+        var offset = contentOffset
+        if flowLayout.scrollDirection == .horizontal {
+            offset.x = frame.minX - anchor.distanceFromOrigin
+        } else {
+            offset.y = frame.minY - anchor.distanceFromOrigin
+        }
+        setContentOffset(clamped(offset), animated: false)
+    }
+
+    private static func identity(for node: [String: Any]) -> String? {
+        let props = node["props"] as? [String: Any] ?? [:]
+        return [node["id"], node["key"], props["key"], props["testID"]]
+            .compactMap { $0 as? String }
+            .first { !$0.isEmpty }
+    }
+}