@npaw/forge-react-native 9.6.1

package/ios/ForgeApple/Sources/NPAWForgeCapture/SectionsMarkers.swift

@@ -0,0 +1,105 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Pure parsing for the F3 sections accessibilityIdentifier marker
+ *               convention (`forge-section:<name>[:<order>]` and
+ *               `forge-item:<contentId>[:<position>]`) plus node classification
+ *               combining Tier 1 markers with the Tier 2 remote native-id lists
+ *               from the kernel capture plan. Platform-free so the parsing rules
+ *               are exhaustively testable without UIKit.
+ */
+
+import Foundation
+
+/// Parsed sections marker from an `accessibilityIdentifier`.
+public enum ForgeSectionMarker: Equatable {
+    case section(name: String, order: Int?)
+    case item(contentId: String, position: Int?)
+}
+
+/// Role resolved for one view/node during sections scanning.
+public enum SectionNodeRole: Equatable {
+    case section(name: String, order: Int?)
+    case item(contentId: String?, position: Int?)
+}
+
+/// Marker grammar: `forge-section:<name>[:<order>]` /
+/// `forge-item:<contentId>[:<position>]`. Prefix matching is exact and
+/// case-sensitive. The trailing component is treated as the numeric field only
+/// when it is a plain non-negative decimal integer that fits `Int` AND at
+/// least one other component precedes it; otherwise it stays part of the
+/// name/content id (names may therefore contain colons). Empty names/ids are
+/// malformed and yield `nil`.
+public enum ForgeSectionMarkerParser {
+    public static let sectionPrefix = "forge-section:"
+    public static let itemPrefix = "forge-item:"
+
+    public static func parse(_ identifier: String?) -> ForgeSectionMarker? {
+        guard let identifier else { return nil }
+        if identifier.hasPrefix(sectionPrefix) {
+            let payload = String(identifier.dropFirst(sectionPrefix.count))
+            guard let (name, number) = split(payload) else { return nil }
+            return .section(name: name, order: number)
+        }
+        if identifier.hasPrefix(itemPrefix) {
+            let payload = String(identifier.dropFirst(itemPrefix.count))
+            guard let (contentId, number) = split(payload) else { return nil }
+            return .item(contentId: contentId, position: number)
+        }
+        return nil
+    }
+
+    /// Classifies one node: Tier 1 markers win, then Tier 2 exact native-id
+    /// matches (section list checked before item list). Non-matching or empty
+    /// identifiers resolve to `nil`.
+    public static func classify(
+        identifier: String?,
+        sectionNativeIds: Set<String>,
+        itemNativeIds: Set<String>
+    ) -> SectionNodeRole? {
+        if let marker = parse(identifier) {
+            switch marker {
+            case let .section(name, order):
+                return .section(name: name, order: order)
+            case let .item(contentId, position):
+                return .item(contentId: contentId, position: position)
+            }
+        }
+        guard let identifier, !identifier.isEmpty else { return nil }
+        if sectionNativeIds.contains(identifier) {
+            return .section(name: identifier, order: nil)
+        }
+        if itemNativeIds.contains(identifier) {
+            return .item(contentId: identifier, position: nil)
+        }
+        return nil
+    }
+
+    private static func split(_ payload: String) -> (text: String, number: Int?)? {
+        guard !payload.isEmpty else { return nil }
+        let components = payload.components(separatedBy: ":")
+        if components.count >= 2,
+           let last = components.last,
+           let number = plainNonNegativeInt(last) {
+            let text = components.dropLast().joined(separator: ":")
+            guard !text.isEmpty else { return nil }
+            return (text, number)
+        }
+        return (payload, nil)
+    }
+
+    /// Strict digits-only parse: no signs, no whitespace, no decimal points.
+    /// Values that overflow `Int` are not numbers and stay part of the text.
+    private static func plainNonNegativeInt(_ value: String) -> Int? {
+        guard !value.isEmpty, value.allSatisfy(\.isASCII), value.allSatisfy(\.isNumber) else { return nil }
+        return Int(value)
+    }
+}

package/ios/ForgeApple/Sources/NPAWForgeCapture/SectionsSwiftUI.swift

@@ -0,0 +1,284 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: SwiftUI view modifiers for F3 sections auto-capture. `.forgeSection`
+ *               marks a container and `.forgeSectionItem` marks content inside it;
+ *               both publish their global frame continuously through a geometry
+ *               preference (throttled ~100 ms with a trailing flush) so scrolling
+ *               keeps visibility percentages fresh in the sections coordinator —
+ *               impressions re-verify against real values at fire time — while
+ *               `onDisappear` stays the remove path. Visibility clips against the
+ *               foreground window-scene bounds (split-screen correct) with a
+ *               `UIScreen.main` fallback. The section modifier propagates its
+ *               engine key through the environment so nested items attach to the
+ *               right section automatically.
+ */
+
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#endif
+#if canImport(SwiftUI)
+import SwiftUI
+#if canImport(UIKit)
+import UIKit
+#endif
+
+@available(iOS 13.0, tvOS 13.0, macOS 10.15, *)
+private struct ForgeSectionKeyEnvironmentKey: EnvironmentKey {
+    static let defaultValue: String? = nil
+}
+
+@available(iOS 13.0, tvOS 13.0, macOS 10.15, *)
+extension EnvironmentValues {
+    var forgeSectionKey: String? {
+        get { self[ForgeSectionKeyEnvironmentKey.self] }
+        set { self[ForgeSectionKeyEnvironmentKey.self] = newValue }
+    }
+}
+
+/// Window-bounds visibility approximation for SwiftUI global frames: on
+/// UIKit platforms the ratio of the frame inside the container bounds, and
+/// a plain appear=100/disappear=0 signal elsewhere.
+enum ForgeSwiftUIVisibility {
+    static func pct(ofGlobalFrame frame: CGRect) -> Int {
+        guard frame.width > 0, frame.height > 0 else { return 0 }
+        #if canImport(UIKit)
+        let visible = frame.intersection(containerBounds())
+        guard !visible.isNull, !visible.isEmpty else { return 0 }
+        let ratio = (visible.width * visible.height) / (frame.width * frame.height)
+        return max(0, min(100, Int((ratio * 100).rounded())))
+        #else
+        return 100
+        #endif
+    }
+
+    #if canImport(UIKit)
+    /// SwiftUI `.global` frames are window-relative, so clip against the
+    /// foreground window-scene bounds when one is resolvable (a split-screen
+    /// app does not span the full screen); `UIScreen.main` stays as the
+    /// fallback for hosts without a resolvable scene and off-main callers.
+    private static func containerBounds() -> CGRect {
+        if Thread.isMainThread {
+            let scenes = UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }
+            let scene = scenes.first { $0.activationState == .foregroundActive } ?? scenes.first
+            if let scene {
+                return scene.coordinateSpace.bounds
+            }
+        }
+        return UIScreen.main.bounds
+    }
+    #endif
+}
+
+/// Main-thread leading+trailing throttle (~100 ms) for continuous SwiftUI
+/// frame publishing: the first change in a window delivers immediately, rapid
+/// follow-ups coalesce into one trailing delivery of the latest frame. Scroll
+/// bursts cannot flood the engine, while the final resting frame always lands
+/// so a stale visibility percentage never survives a fast scroll.
+final class ForgeSwiftUIFrameThrottle {
+    static let defaultIntervalMs: Int64 = 100
+
+    private let intervalMs: Int64
+    private let nowMs: () -> Int64
+    private let scheduleOnMain: (Int64, @escaping () -> Void) -> Void
+    private var lastDeliveryAtMs: Int64?
+    private var pending: (frame: CGRect, deliver: (CGRect) -> Void)?
+    private var trailingScheduled = false
+
+    init(
+        intervalMs: Int64 = ForgeSwiftUIFrameThrottle.defaultIntervalMs,
+        nowMs: @escaping () -> Int64 = { ForgeClock.elapsedRealtimeMs() },
+        scheduleOnMain: @escaping (Int64, @escaping () -> Void) -> Void = { delayMs, block in
+            DispatchQueue.main.asyncAfter(
+                deadline: .now() + .milliseconds(Int(clamping: delayMs)),
+                execute: block
+            )
+        }
+    ) {
+        self.intervalMs = max(0, intervalMs)
+        self.nowMs = nowMs
+        self.scheduleOnMain = scheduleOnMain
+    }
+
+    func push(frame: CGRect, deliver: @escaping (CGRect) -> Void) {
+        let now = nowMs()
+        if let last = lastDeliveryAtMs, now - last < intervalMs {
+            pending = (frame, deliver)
+            if !trailingScheduled {
+                trailingScheduled = true
+                scheduleOnMain(max(1, intervalMs - (now - last))) { [weak self] in
+                    self?.deliverPending()
+                }
+            }
+            return
+        }
+        lastDeliveryAtMs = now
+        pending = nil
+        deliver(frame)
+    }
+
+    private func deliverPending() {
+        trailingScheduled = false
+        guard let pending else { return }
+        self.pending = nil
+        lastDeliveryAtMs = nowMs()
+        pending.deliver(pending.frame)
+    }
+}
+
+/// Geometry preference carrying a modifier's global frame. One shared key
+/// type is safe: every modifier instance publishes on its own `Color.clear`
+/// and consumes the value inside that same background subtree, so instances
+/// never observe each other's frames.
+@available(iOS 13.0, tvOS 13.0, macOS 10.15, *)
+private struct ForgeFramePreferenceKey: PreferenceKey {
+    static let defaultValue = CGRect.zero
+
+    static func reduce(value: inout CGRect, nextValue: () -> CGRect) {
+        value = nextValue()
+    }
+}
+
+@available(iOS 13.0, tvOS 13.0, macOS 10.15, *)
+public struct ForgeSectionCaptureModifier: ViewModifier {
+    private let handle: AutomaticCaptureHandle
+    private let name: String
+    private let order: Int?
+    @State private var instanceKey = "swiftui-section-\(UUID().uuidString)"
+    @State private var frameThrottle = ForgeSwiftUIFrameThrottle()
+
+    public init(handle: AutomaticCaptureHandle, name: String, order: Int?) {
+        self.handle = handle
+        self.name = name
+        self.order = order
+    }
+
+    public func body(content: Content) -> some View {
+        content
+            .background(
+                GeometryReader { proxy in
+                    Color.clear
+                        .preference(key: ForgeFramePreferenceKey.self, value: proxy.frame(in: .global))
+                        .onPreferenceChange(ForgeFramePreferenceKey.self) { frame in
+                            // Continuous visibility: scroll/layout changes
+                            // republish the frame so the engine store stays
+                            // fresh and impressions re-verify against real
+                            // percentages at fire time.
+                            frameThrottle.push(frame: frame) { latest in
+                                pushSection(frame: latest)
+                            }
+                        }
+                        .onAppear {
+                            pushSection(frame: proxy.frame(in: .global))
+                        }
+                        .onDisappear {
+                            handle.sectionsCoordinator.removeSection(source: .swiftui, key: instanceKey)
+                        }
+                }
+            )
+            .environment(\.forgeSectionKey, instanceKey)
+    }
+
+    private func pushSection(frame: CGRect) {
+        handle.sectionsCoordinator.updateSection(
+            source: .swiftui,
+            SectionSnapshot(
+                key: instanceKey,
+                name: name,
+                order: order,
+                visibilityPct: ForgeSwiftUIVisibility.pct(ofGlobalFrame: frame),
+                itemCount: 0
+            )
+        )
+    }
+}
+
+@available(iOS 13.0, tvOS 13.0, macOS 10.15, *)
+public struct ForgeSectionItemCaptureModifier: ViewModifier {
+    private let handle: AutomaticCaptureHandle
+    private let contentId: String
+    private let position: Int?
+    private let title: String?
+    @State private var instanceKey = "swiftui-item-\(UUID().uuidString)"
+    @State private var frameThrottle = ForgeSwiftUIFrameThrottle()
+    @Environment(\.forgeSectionKey) private var sectionKey: String?
+
+    public init(handle: AutomaticCaptureHandle, contentId: String, position: Int?, title: String?) {
+        self.handle = handle
+        self.contentId = contentId
+        self.position = position
+        self.title = title
+    }
+
+    public func body(content: Content) -> some View {
+        content.background(
+            GeometryReader { proxy in
+                Color.clear
+                    .preference(key: ForgeFramePreferenceKey.self, value: proxy.frame(in: .global))
+                    .onPreferenceChange(ForgeFramePreferenceKey.self) { frame in
+                        // Resolve the environment section key before the
+                        // throttled (possibly deferred) delivery so the
+                        // escaping closure never reads @Environment late.
+                        let resolvedSectionKey = sectionKey
+                        frameThrottle.push(frame: frame) { latest in
+                            pushItem(resolvedSectionKey: resolvedSectionKey, frame: latest)
+                        }
+                    }
+                    .onAppear {
+                        pushItem(resolvedSectionKey: sectionKey, frame: proxy.frame(in: .global))
+                    }
+                    .onDisappear {
+                        handle.sectionsCoordinator.removeItem(source: .swiftui, key: instanceKey)
+                    }
+            }
+        )
+    }
+
+    private func pushItem(resolvedSectionKey: String?, frame: CGRect) {
+        let coordinator = handle.sectionsCoordinator
+        coordinator.updateItem(
+            source: .swiftui,
+            ItemSnapshot(
+                key: instanceKey,
+                contentId: contentId,
+                position: position ?? coordinator.assignedPosition(
+                    sectionKey: resolvedSectionKey ?? "swiftui",
+                    itemKey: instanceKey
+                ),
+                sectionKey: resolvedSectionKey,
+                visibilityPct: ForgeSwiftUIVisibility.pct(ofGlobalFrame: frame),
+                title: title
+            )
+        )
+    }
+}
+
+@available(iOS 13.0, tvOS 13.0, macOS 10.15, *)
+public extension View {
+    /// Marks this view as an F3 section container named `name`. An explicit
+    /// `order` wins over first-seen ordering across the whole screen.
+    func forgeSection(_ name: String, order: Int? = nil, handle: AutomaticCaptureHandle) -> some View {
+        modifier(ForgeSectionCaptureModifier(handle: handle, name: name, order: order))
+    }
+
+    /// Marks this view as F3 section content. Nest it inside a `.forgeSection`
+    /// container to attach the item to that section automatically.
+    func forgeSectionItem(
+        contentId: String,
+        position: Int? = nil,
+        title: String? = nil,
+        handle: AutomaticCaptureHandle
+    ) -> some View {
+        modifier(ForgeSectionItemCaptureModifier(handle: handle, contentId: contentId, position: position, title: title))
+    }
+}
+#endif

package/ios/ForgeApple/Sources/NPAWForgeCapture/SwiftUICapture.swift

@@ -0,0 +1,44 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: SwiftUI helper for reporting visible routes through the automatic capture pipeline.
+ */
+
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#endif
+#if canImport(SwiftUI)
+import SwiftUI
+
+@available(iOS 13.0, tvOS 13.0, macOS 10.15, *)
+public struct ForgeScreenCaptureModifier: ViewModifier {
+    private let handle: AutomaticCaptureHandle
+    private let name: String
+
+    public init(handle: AutomaticCaptureHandle, name: String) {
+        self.handle = handle
+        self.name = name
+    }
+
+    public func body(content: Content) -> some View {
+        content.onAppear {
+            _ = handle.screenView(name)
+        }
+    }
+}
+
+@available(iOS 13.0, tvOS 13.0, macOS 10.15, *)
+public extension View {
+    func forgeScreen(_ name: String, handle: AutomaticCaptureHandle) -> some View {
+        modifier(ForgeScreenCaptureModifier(handle: handle, name: name))
+    }
+}
+#endif

package/ios/ForgeApple/Sources/NPAWForgeCore/AdAdapter.swift

@@ -0,0 +1,199 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Apple ad adapter base class and public manual fire API.
+ */
+
+import Foundation
+
+open class AdAdapter: NSObject {
+    public let adapterInstanceId = UUID()
+    open var descriptor = AdapterDescriptor(
+        adapterId: "generic-ad",
+        category: .ad,
+        playerFamily: "Generic Ads",
+        version: "unknown"
+    )
+    open var playerObject: AnyObject? {
+        didSet {
+            if oldValue === playerObject { return }
+            if isBound { unregisterListeners() }
+            if isBound, playerObject != nil { registerListeners() }
+        }
+    }
+    private var isBound = false
+    public private(set) weak var videoAdapter: VideoAdapter?
+
+    public init(player: AnyObject? = nil) {
+        self.playerObject = player
+        super.init()
+    }
+
+    func bindToVideoAdapter(_ videoAdapter: VideoAdapter) {
+        self.videoAdapter = videoAdapter
+        isBound = true
+        if playerObject != nil { registerListeners() }
+    }
+
+    func unbindFromVideoAdapter() {
+        if isBound { unregisterListeners() }
+        isBound = false
+        videoAdapter = nil
+    }
+
+    open func registerListeners() {}
+    open func unregisterListeners() {}
+
+    open func metadata() -> [String: String] {
+        [
+            "adapterId": descriptor.adapterId,
+            "category": descriptor.category.rawValue,
+            "playerFamily": descriptor.playerFamily,
+            "version": descriptor.version,
+        ]
+    }
+
+    open func onAdEvent(
+        _ event: AdEvent,
+        timestampMs: Int64 = 0,
+        metadata: AdMetadataSnapshot? = nil
+    ) -> ForgeOutcome {
+        let resolved = metadata ?? defaultMetadata(nil)
+        switch event {
+        case .manifest: return fireManifest(metadata: resolved, timestampMs: timestampMs)
+        case .breakStart: return fireBreakStart(metadata: resolved, timestampMs: timestampMs)
+        case .adInit: return fireAdInit(metadata: resolved, timestampMs: timestampMs)
+        case .start: return fireStart(metadata: resolved, timestampMs: timestampMs)
+        case .join: return fireJoin(metadata: resolved, timestampMs: timestampMs)
+        case .pause: return firePause(metadata: resolved, timestampMs: timestampMs)
+        case .resume: return fireResume(metadata: resolved, timestampMs: timestampMs)
+        case .bufferBegin: return fireBufferBegin(metadata: resolved, timestampMs: timestampMs)
+        case .bufferEnd: return fireBufferEnd(metadata: resolved, timestampMs: timestampMs)
+        case .quartile: return fireQuartile(resolved.quartile, timestampMs: timestampMs)
+        case .click: return fireClick(metadata: resolved, timestampMs: timestampMs)
+        case .skip: return fireSkip(timestampMs: timestampMs)
+        case .stop: return fireStop(metadata: resolved, timestampMs: timestampMs)
+        case .error: return fireError(errorCode: resolved.errorCode, errorMessage: resolved.errorMessage, errorMetadata: resolved.errorMetadata, timestampMs: timestampMs)
+        case .fatalError: return fireFatalError(errorCode: resolved.errorCode, errorMessage: resolved.errorMessage, errorMetadata: resolved.errorMetadata, timestampMs: timestampMs)
+        case .breakStop: return fireBreakStop(metadata: resolved, timestampMs: timestampMs)
+        }
+    }
+
+    open func fireManifest(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.manifest, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireBreakStart(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.breakStart, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireAdInit(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.adInit, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireStart(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.start, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireJoin(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.join, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func firePause(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.pause, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireResume(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.resume, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireBufferBegin(convertFromSeek: Bool? = false, params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.bufferBegin, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireBufferEnd(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.bufferEnd, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireQuartile(_ quartile: Int? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        var metadata = defaultMetadata(nil)
+        metadata.quartile = quartile
+        return record(.quartile, metadata, timestampMs)
+    }
+    open func fireClick(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.click, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireClick(adUrl: String?) -> ForgeOutcome {
+        fireClick(params: adUrl.map { ["adUrl": $0] } ?? [:])
+    }
+    open func fireSkip(timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.skip, defaultMetadata(nil), timestampMs)
+    }
+    open func fireStop(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.stop, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireError(errorCode: String? = nil, errorMessage: String? = nil, errorMetadata: String? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        var metadata = defaultMetadata(nil)
+        metadata.errorCode = errorCode
+        metadata.errorMessage = errorMessage
+        metadata.errorMetadata = errorMetadata
+        return record(.error, metadata, timestampMs)
+    }
+    open func fireFatalError(errorCode: String? = nil, errorMessage: String? = nil, errorMetadata: String? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        var metadata = defaultMetadata(nil)
+        metadata.errorCode = errorCode
+        metadata.errorMessage = errorMessage
+        metadata.errorMetadata = errorMetadata
+        metadata.errorLevel = "fatal"
+        return record(.fatalError, metadata, timestampMs)
+    }
+    open func fireBreakStop(params: [String: String]? = [:], metadata: AdMetadataSnapshot? = nil, timestampMs: Int64 = 0) -> ForgeOutcome {
+        record(.breakStop, metadata ?? defaultMetadata(params), timestampMs)
+    }
+    open func fireDestroy(timestampMs: Int64 = 0) -> ForgeOutcome { .unsupportedCapability }
+
+    open func defaultMetadata(_ params: [String: String]?) -> AdMetadataSnapshot {
+        AdMetadataSnapshot(
+            adId: params?["adId"] ?? params?["ad_id"],
+            creativeId: params?["adCreativeId"] ?? params?["creative_id"],
+            adUrl: params?["adUrl"] ?? params?["ad_url"],
+            adTitle: params?["adTitle"],
+            adDurationMs: params?["adDurationMs"].flatMap(Int64.init) ?? params?["adDuration"].flatMap(Self.secondsToMillis),
+            adPlayheadMs: params?["adPlayheadMs"].flatMap(Int64.init) ?? params?["adPlayhead"].flatMap(Self.secondsToMillis),
+            adBitrate: params?["adBitrate"].flatMap(Int64.init),
+            position: params?["position"].flatMap(AdPosition.from),
+            quartile: params?["quartile"].flatMap(Int.init),
+            insertionType: (params?["adInsertionType"] ?? params?["insertion_type"]).flatMap(AdInsertionType.from) ?? .unknown,
+            errorMetadata: params?["errorMetadata"],
+            errorLevel: params?["errorLevel"]
+        )
+    }
+
+    func record(_ event: AdEvent, _ metadata: AdMetadataSnapshot, _ timestampMs: Int64) -> ForgeOutcome {
+        videoAdapter?.recordAdEvent(event: event, timestampMs: timestampMs, metadata: metadata) ?? .ignoredInvalidState
+    }
+
+    private static func secondsToMillis(_ value: String) -> Int64? {
+        Double(value).map { Int64($0 * 1000.0) }
+    }
+}
+
+private extension AdPosition {
+    static func from(_ value: String) -> AdPosition {
+        switch value.lowercased() {
+        case "pre": return .pre
+        case "mid": return .mid
+        case "post": return .post
+        default: return .unknown
+        }
+    }
+}
+
+private extension AdInsertionType {
+    static func from(_ value: String) -> AdInsertionType {
+        switch value.lowercased() {
+        case "csai", "client_side": return .clientSide
+        case "ssai", "server_side": return .serverSide
+        default: return .unknown
+        }
+    }
+}