From 50a4122a00cfd3e1868bb77a3fa201f1cab46a82 Mon Sep 17 00:00:00 2001
From: Dan Leedham <danleedham@googlemail.com>
Date: Wed, 17 Dec 2025 14:35:50 +0000
Subject: [PATCH 1/6] Allow adding label without icon

---
 .../ForeFlightKMLDemo/KML/KMLGenerator.swift  |   4 +-
 .../ForeFlightKMLDemo/Views/ContentView.swift |  15 ++--
 Package.resolved                              |   9 ++
 Package.swift                                 |   9 +-
 README.md                                     |  12 +++
 .../ForeFlightKML/Errors/KMZExportError.swift |   5 ++
 .../ForeFlightKML+Convenience.swift           |  31 +++++++
 Sources/ForeFlightKML/ForeFlightKML.swift     |   5 ++
 Sources/ForeFlightKML/ForeflightKML+KMZ.swift |  50 +++++++++++
 .../ForeFlightKML/Models/StyleManager.swift   |   7 ++
 Sources/ForeFlightKML/Resources/1x1.png       | Bin 0 -> 95 bytes
 .../Styles/Geometry/PointStyle.swift          |  15 ++++
 Sources/ForeFlightKML/Styles/IconStyle.swift  |  15 ++++
 Sources/ForeFlightKML/Styles/Style.swift      |   6 ++
 Sources/ForeFlightKML/Utils/Protocols.swift   |   6 ++
 .../ForeFlightKML+KMZTests.swift              |  80 ++++++++++++++++++
 .../ModelTests/AltitudeTests.swift            |   2 -
 .../StyleTests/Geometry/PointStyleTests.swift |  33 +++++++-
 .../StyleTests/IconStyle+HiddenTests.swift    |  44 ++++++++++
 .../StyleTests/IconStyleTests.swift           |  15 ++++
 .../UserMapShapesSampleFullTest.swift         |   4 +-
 .../UserMapShapesSampleIndividualTests.swift  |   1 -
 22 files changed, 351 insertions(+), 17 deletions(-)
 create mode 100644 Sources/ForeFlightKML/Errors/KMZExportError.swift
 create mode 100644 Sources/ForeFlightKML/ForeflightKML+KMZ.swift
 create mode 100644 Sources/ForeFlightKML/Resources/1x1.png
 create mode 100644 Tests/ForeFlightKMLTests/ForeFlightKML+KMZTests.swift
 create mode 100644 Tests/ForeFlightKMLTests/StyleTests/IconStyle+HiddenTests.swift

diff --git a/Example/ForeFlightKMLDemo/KML/KMLGenerator.swift b/Example/ForeFlightKMLDemo/KML/KMLGenerator.swift
index 9cba4d1..d022d9e 100644
--- a/Example/ForeFlightKMLDemo/KML/KMLGenerator.swift
+++ b/Example/ForeFlightKMLDemo/KML/KMLGenerator.swift
@@ -4,7 +4,7 @@ import CoreLocation
 import ForeFlightKML
 
 enum KMLGenerator {
-    static func generateCircleKML(center: CLLocationCoordinate2D, radiusMeters: Double) -> String {
+    static func generateCircleKML(center: CLLocationCoordinate2D, radiusMeters: Double) throws -> Data? {
         let builder = ForeFlightKMLBuilder(documentName: "Foreflight KML Demo")
 
         let centerCoordinate = Coordinate(latitude: center.latitude, longitude: center.longitude)
@@ -23,7 +23,7 @@ enum KMLGenerator {
             radiusMeters: radiusMeters * 2,
             style: PolygonStyle(outlineColor: .black, fillColor: .warning.withAlpha(0.3)))
 
-        return builder.build()
+        return try builder.buildKMZ()
     }
 
     static func polygonCoordinatesForMap(center: CLLocationCoordinate2D, radiusMeters: Double) -> [CLLocationCoordinate2D] {
diff --git a/Example/ForeFlightKMLDemo/Views/ContentView.swift b/Example/ForeFlightKMLDemo/Views/ContentView.swift
index a18b871..c5574ab 100644
--- a/Example/ForeFlightKMLDemo/Views/ContentView.swift
+++ b/Example/ForeFlightKMLDemo/Views/ContentView.swift
@@ -48,19 +48,20 @@ struct ContentView: View {
 
     private func handleMapTap(_ coord: CLLocationCoordinate2D) {
         lastTapCoordinate = coord
+        
+        do {
+            let kmz = try KMLGenerator.generateCircleKML(center: coord, radiusMeters: defaultRadiusMeters)
 
-        let kml = KMLGenerator.generateCircleKML(center: coord, radiusMeters: defaultRadiusMeters)
+            let dateFormatter = DateFormatter()
+            dateFormatter.dateFormat = "yyyyMMdd'T'HHmmss'Z'"
 
-        let dateFormatter = DateFormatter()
-        dateFormatter.dateFormat = "yyyyMMdd'T'HHmmss'Z'"
+            let tmpURL = FileManager.default.temporaryDirectory.appendingPathComponent("\(dateFormatter.string(from: Date())).kmz")
 
-        let tmpURL = FileManager.default.temporaryDirectory.appendingPathComponent("\(dateFormatter.string(from: Date())).kml")
-        do {
-            try kml.data(using: .utf8)?.write(to: tmpURL)
+            try kmz?.write(to: tmpURL)
             kmlToShareURL = tmpURL
             showingShare = true
         } catch {
-            print("Failed to write KML: \(error)")
+            print("Failed to write KMZ: \(error)")
             kmlToShareURL = nil
         }
     }
diff --git a/Package.resolved b/Package.resolved
index b312d27..a95a72e 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -8,6 +8,15 @@
         "revision" : "c72d7ea459c6eee4d041272c61f84df61d850091",
         "version" : "0.2.2"
       }
+    },
+    {
+      "identity" : "zipfoundation",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/weichsel/ZIPFoundation.git",
+      "state" : {
+        "revision" : "22787ffb59de99e5dc1fbfe80b19c97a904ad48d",
+        "version" : "0.9.20"
+      }
     }
   ],
   "version" : 2
diff --git a/Package.swift b/Package.swift
index 14f7748..71dbf62 100644
--- a/Package.swift
+++ b/Package.swift
@@ -11,13 +11,18 @@ let package = Package(
         )
     ],
     dependencies: [
-        .package(url: "https://github.com/florianreinhart/Geodesy", .upToNextMajor(from: "0.2.2"))
+        .package(url: "https://github.com/florianreinhart/Geodesy", .upToNextMajor(from: "0.2.2")),
+        .package(url: "https://github.com/weichsel/ZIPFoundation.git", from: "0.9.0")
     ],
     targets: [
         .target(
             name: "ForeFlightKML",
             dependencies: [
-                .product(name: "Geodesy", package: "Geodesy")
+                .product(name: "Geodesy", package: "Geodesy"),
+                .product(name: "ZIPFoundation", package: "ZIPFoundation")
+            ],
+            resources: [
+                .process("Resources")
             ]
         ),
         .testTarget(
diff --git a/README.md b/README.md
index 099d969..80dc333 100644
--- a/README.md
+++ b/README.md
@@ -81,6 +81,18 @@ Full public API surface is visible in the package sources; the README examples s
 - **Angles/bearings**: bearings (for arc & circle generation) are interpreted in degrees (0..360). The bearing convention is clockwise from north.
 - **Altitude**: When you provide altitudes, the `AltitudeMode` is emitted (defaults to `.absolute` in most geometries).
 - **Styles**: `Style` generates a stable `id` when provided; otherwise a UUID-based id is generated. `ForeFlightKMLBuilder` will automatically register styles added via `Placemark`.
+
+### ForeFlight point label color (important)
+
+For Point placemarks:
+- LabelStyle.color is ignored
+- Label badge color is driven by IconStyle.color
+
+To create a label-only point with a colored badge:
+```
+    builder.addLabel("Text", coordinate: .init(...), color: KMLColor)
+```
+
 ---
 
 ## Demo & tests
diff --git a/Sources/ForeFlightKML/Errors/KMZExportError.swift b/Sources/ForeFlightKML/Errors/KMZExportError.swift
new file mode 100644
index 0000000..ba3e86e
--- /dev/null
+++ b/Sources/ForeFlightKML/Errors/KMZExportError.swift
@@ -0,0 +1,5 @@
+public enum KMZExportError: Error {
+    case kmzRequired
+    case missingLocalResource(String)
+    case archiveCreationFailed
+}
diff --git a/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift b/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift
index 715a8c6..f0110e8 100644
--- a/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift
+++ b/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift
@@ -291,4 +291,35 @@ extension ForeFlightKMLBuilder {
         let placemark = Placemark(name: name, geometry: segment, style: style)
         return addPlacemark(placemark)
     }
+    
+    @discardableResult
+    public func addLabel(
+        _ text: String,
+        coordinate: Coordinate,
+        altitude: Double? = nil,
+        color: KMLColor = .white
+    ) -> Self {
+        addPoint(
+            name: text,
+            coordinate: coordinate,
+            altitude: altitude,
+            style: .labelBadge(color: color)
+        )
+    }
+
+    @discardableResult
+    public func addLabel(
+        _ text: String,
+        latitude: Double,
+        longitude: Double,
+        altitude: Double? = nil,
+        color: KMLColor = .white
+    ) -> Self {
+        addLabel(
+            text,
+            coordinate: Coordinate(latitude: latitude, longitude: longitude),
+            altitude: altitude,
+            color: color
+        )
+    }
 }
diff --git a/Sources/ForeFlightKML/ForeFlightKML.swift b/Sources/ForeFlightKML/ForeFlightKML.swift
index 5df0777..3ec83e7 100644
--- a/Sources/ForeFlightKML/ForeFlightKML.swift
+++ b/Sources/ForeFlightKML/ForeFlightKML.swift
@@ -46,6 +46,11 @@ public final class ForeFlightKMLBuilder {
         }
         return self
     }
+    
+    /// True if this document must be exported as KMZ to render correctly.
+    var requiresKMZ: Bool {
+        styleManager.requiresKMZ
+    }
 
     // MARK: - Build Methods
 
diff --git a/Sources/ForeFlightKML/ForeflightKML+KMZ.swift b/Sources/ForeFlightKML/ForeflightKML+KMZ.swift
new file mode 100644
index 0000000..300dac6
--- /dev/null
+++ b/Sources/ForeFlightKML/ForeflightKML+KMZ.swift
@@ -0,0 +1,50 @@
+import Foundation
+import ZIPFoundation
+
+public extension ForeFlightKMLBuilder {
+
+    /// Build a KMZ (ZIP) containing doc.kml and any required local assets.
+    func buildKMZ() throws -> Data? {
+
+        let kmlData = kmlData()
+
+        let archive = try Archive(accessMode: .create)
+
+        try archive.addEntry(
+            with: "doc.kml",
+            type: .file,
+            uncompressedSize: Int64(kmlData.count),
+            compressionMethod: .deflate,
+            provider: { position, size in
+                let start = Int(position)
+                guard start < kmlData.count else { return Data() }
+                let end = min(start + size, kmlData.count)
+                return kmlData.subdata(in: start..<end)
+            }
+        )
+
+        if requiresKMZ {
+            try addLocalAssets(to: archive)
+        }
+
+        return archive.data
+    }
+}
+
+private extension ForeFlightKMLBuilder {
+
+    func addLocalAssets(to archive: Archive) throws {
+
+        let bundle = Bundle.module
+
+        guard let iconURL = bundle.url(forResource: "1x1", withExtension: "png") else {
+            throw KMZExportError.missingLocalResource("1x1.png")
+        }
+
+        try archive.addEntry(
+            with: "1x1.png",
+            fileURL: iconURL,
+            compressionMethod: .deflate
+        )
+    }
+}
diff --git a/Sources/ForeFlightKML/Models/StyleManager.swift b/Sources/ForeFlightKML/Models/StyleManager.swift
index 74eaf89..de22251 100644
--- a/Sources/ForeFlightKML/Models/StyleManager.swift
+++ b/Sources/ForeFlightKML/Models/StyleManager.swift
@@ -46,6 +46,13 @@ internal class StyleManager {
             markAsReferenced(styleId)
         }
     }
+    
+    /// True if any referenced style requires KMZ packaging.
+    var requiresKMZ: Bool {
+        referencedStyleIds.contains { id in
+            styles[id]?.requiresKMZ == true
+        }
+    }
 
     // MARK: - Style Management
 
diff --git a/Sources/ForeFlightKML/Resources/1x1.png b/Sources/ForeFlightKML/Resources/1x1.png
new file mode 100644
index 0000000000000000000000000000000000000000..1914264c08781d1f30ee0b8482bccf44586f2dc1
GIT binary patch
literal 95
zcmeAS@N?(olHy`uVBq!ia0vp^j3CU&3?x-=hn)ga%mF?ju0VQumF+E%TuG2$FoVOh
l8)-lem#2$k2*>s01R$G<f$@>z9%CSj!PC{xWt~$(697H@6ZHT9

literal 0
HcmV?d00001

diff --git a/Sources/ForeFlightKML/Styles/Geometry/PointStyle.swift b/Sources/ForeFlightKML/Styles/Geometry/PointStyle.swift
index eb969e2..e648e6f 100644
--- a/Sources/ForeFlightKML/Styles/Geometry/PointStyle.swift
+++ b/Sources/ForeFlightKML/Styles/Geometry/PointStyle.swift
@@ -24,6 +24,10 @@ public struct PointStyle: KMLStyle {
     public func id() -> String {
         return styleId
     }
+    
+    public var requiresKMZ: Bool {
+        icon.requiresKMZ
+    }
 
     public func kmlString() -> String {
         var components: [String] = []
@@ -36,3 +40,14 @@ public struct PointStyle: KMLStyle {
         return components.joined(separator: "\n")
     }
 }
+
+public extension PointStyle {
+    /// A point style that renders only the placemark name as a label.
+    static func labelBadge(color: KMLColor = .white, id: String? = nil) -> PointStyle {
+            PointStyle(
+                icon: .transparentLocalPng(tint: color),
+                label: nil, // ForeFlight ignores LabelStyle for point badges
+                id: id
+            )
+    }
+}
diff --git a/Sources/ForeFlightKML/Styles/IconStyle.swift b/Sources/ForeFlightKML/Styles/IconStyle.swift
index 629b84f..9da0ed2 100644
--- a/Sources/ForeFlightKML/Styles/IconStyle.swift
+++ b/Sources/ForeFlightKML/Styles/IconStyle.swift
@@ -60,6 +60,15 @@ public struct IconStyle: KMLSubStyle {
     func iconHref() -> String {
         return iconHrefValue
     }
+    
+    /// True if this icon references a local resource and therefore
+    /// requires KMZ packaging to render correctly in ForeFlight.
+    var requiresKMZ: Bool {
+        // Local icon references (e.g. "1x1.png") must be packaged in a KMZ.
+        // Remote URLs (http/https) are fine in plain KML.
+        !iconHrefValue.hasPrefix("http://") &&
+        !iconHrefValue.hasPrefix("https://")
+    }
 
     public func kmlString() -> String {
         var lines: [String] = []
@@ -127,3 +136,9 @@ public enum DefinedIconColor: String {
     case pink = "pink"
     case red = "red"
 }
+
+public extension IconStyle {
+    static func transparentLocalPng(tint color: KMLColor = .white, scale: Double? = 1.0) -> IconStyle {
+        IconStyle(href: "1x1.png", color: color, scale: scale)
+    }
+}
diff --git a/Sources/ForeFlightKML/Styles/Style.swift b/Sources/ForeFlightKML/Styles/Style.swift
index 16a9d07..18660d8 100644
--- a/Sources/ForeFlightKML/Styles/Style.swift
+++ b/Sources/ForeFlightKML/Styles/Style.swift
@@ -19,6 +19,12 @@ internal struct Style: KMLStyle {
     public func id() -> String {
         return styleId
     }
+    
+    var requiresKMZ: Bool {
+        subStyles.contains {
+            ($0 as? IconStyle)?.requiresKMZ == true
+        }
+    }
 
     /// Create a new complete style.
     /// - Parameters:
diff --git a/Sources/ForeFlightKML/Utils/Protocols.swift b/Sources/ForeFlightKML/Utils/Protocols.swift
index a131adb..3ea966d 100644
--- a/Sources/ForeFlightKML/Utils/Protocols.swift
+++ b/Sources/ForeFlightKML/Utils/Protocols.swift
@@ -12,6 +12,12 @@ public protocol KMLStyle {
     // Top-level style that must provide an id and full KML (usually a <Style id="..."> ... </Style>)
     func id() -> String
     func kmlString() -> String
+    // Whether this style requires KMZ packaging (e.g. local icon assets).
+    var requiresKMZ: Bool { get }
+}
+
+public extension KMLStyle {
+    var requiresKMZ: Bool { false }
 }
 
 /// Represents a style *sub-element* like `<LineStyle>` or `<PolyStyle>`.
diff --git a/Tests/ForeFlightKMLTests/ForeFlightKML+KMZTests.swift b/Tests/ForeFlightKMLTests/ForeFlightKML+KMZTests.swift
new file mode 100644
index 0000000..266434b
--- /dev/null
+++ b/Tests/ForeFlightKMLTests/ForeFlightKML+KMZTests.swift
@@ -0,0 +1,80 @@
+import XCTest
+@testable import ForeFlightKML
+import GeodesySpherical
+import ZIPFoundation
+
+final class KMZPackagingTests: XCTestCase {
+
+    func test_buildKMZ_alwaysContainsDocKML() throws {
+        let builder = ForeFlightKMLBuilder()
+        builder.addPoint(
+            name: "Normal",
+            coordinate: Coordinate(latitude: 51.0, longitude: -1.0),
+            altitude: 0,
+            style: PointStyle(icon: .custom(type: .square, color: .white, scale: 1.0))
+        )
+
+        let kmz = try builder.buildKMZ()
+        let archive = try makeArchive(from: kmz!)
+
+        XCTAssertNotNil(archive["doc.kml"], "KMZ must contain doc.kml at root")
+    }
+
+    func test_buildKMZ_doesNotInclude1x1png_whenNotRequired() throws {
+        let builder = ForeFlightKMLBuilder()
+        builder.addPoint(
+            name: "Normal",
+            coordinate: Coordinate(latitude: 51.0, longitude: -1.0),
+            altitude: 0,
+            style: PointStyle(icon: .custom(type: .square, color: .white, scale: 1.0))
+        )
+
+        XCTAssertFalse(builder.requiresKMZ)
+
+        let kmz = try builder.buildKMZ()
+        let archive = try makeArchive(from: kmz!)
+
+        XCTAssertNil(archive["1x1.png"], "KMZ should not include 1x1.png unless required")
+    }
+
+    func test_buildKMZ_includes1x1png_whenRequired() throws {
+        let builder = ForeFlightKMLBuilder()
+        builder.addLabel("Badge", coordinate: Coordinate(latitude: 51.0, longitude: -1.0), color: .warning)
+        XCTAssertTrue(builder.requiresKMZ)
+
+        let kmz = try builder.buildKMZ()
+        let archive = try makeArchive(from: kmz!)
+
+        XCTAssertNotNil(archive["1x1.png"], "KMZ must include 1x1.png when label badges are used")
+    }
+
+    // MARK: - Helpers
+
+    private func makeArchive(from kmzData: Data) throws -> Archive {
+        let url = FileManager.default.temporaryDirectory
+            .appendingPathComponent(UUID().uuidString)
+            .appendingPathExtension("kmz")
+
+        try kmzData.write(to: url)
+        return try Archive(url: url, accessMode: .read)
+    }
+    
+    func test_builderAddLabel() {
+        let builder = ForeFlightKMLBuilder()
+
+        builder.addLabel("Label Warning", coordinate: .init(latitude: 51.2345, longitude: -1.2345), color: .warning)
+        do {
+            let kmz = try builder.buildKMZ()
+
+            let url = FileManager.default.temporaryDirectory
+                .appendingPathComponent("test.kmz")
+
+            try kmz!.write(to: url)
+            print("KMZ written to:", url)
+        } catch {
+            XCTFail("Unable to build KMZ: \(error)")
+        }
+    }
+}
+
+
diff --git a/Tests/ForeFlightKMLTests/ModelTests/AltitudeTests.swift b/Tests/ForeFlightKMLTests/ModelTests/AltitudeTests.swift
index 077d225..845a476 100644
--- a/Tests/ForeFlightKMLTests/ModelTests/AltitudeTests.swift
+++ b/Tests/ForeFlightKMLTests/ModelTests/AltitudeTests.swift
@@ -22,9 +22,7 @@ final class AltitudeSupportTests: XCTestCase {
 
     func testPointWithAltitudeNoMode() {
         let point = Point(Coordinate(latitude: 1, longitude: -1), altitude: 0)
-
         let kml = point.kmlString()
-        print(kml)
         XCTAssertTrue(kml.contains("<coordinates>-1.0,1.0,0.0</coordinates>"))
         XCTAssertFalse(kml.contains("<altitudeMode>"))
     }
diff --git a/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift b/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
index cff7162..88752f2 100644
--- a/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
+++ b/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
@@ -1,5 +1,5 @@
 import XCTest
-
+import GeodesySpherical
 @testable import ForeFlightKML
 
 final class PointStylesTests: XCTestCase {
@@ -46,4 +46,35 @@ final class PointStylesTests: XCTestCase {
 
         XCTAssertNotEqual(style1.id(), style2.id())
     }
+    
+    func test_pointStyle_requiresKMZ_followsIconStyle() {
+        let s1 = PointStyle(icon: .transparentLocalPng(tint: .white))
+        XCTAssertTrue(s1.requiresKMZ)
+
+        let s2 = PointStyle(icon: .custom(type: .square, color: .white))
+        XCTAssertFalse(s2.requiresKMZ)
+    }
+
+    func test_labelBadge_requiresKMZ_true() {
+        let s = PointStyle.labelBadge(color: .warning)
+        XCTAssertTrue(s.requiresKMZ)
+    }
+
+    func test_addLabel_emitsTransparentHref_andIconColor() {
+        let builder = ForeFlightKMLBuilder(documentName: "Test")
+        builder.addLabel("Badge", coordinate: Coordinate(latitude: 51.0, longitude: -1.0), color: .warning)
+
+        let kml = builder.build()
+
+        XCTAssertTrue(kml.contains("<href>1x1.png</href>"))
+        XCTAssertTrue(kml.contains("<IconStyle>"))
+        XCTAssertTrue(kml.contains("<color>"), "Label badge must emit IconStyle color (drives ForeFlight badge)")
+    }
+
+    func test_labelBadge_doesNotEmitLabelStyle() {
+        let style = PointStyle.labelBadge(color: .warning, id: "fixed")
+        let xml = style.kmlString()
+
+        XCTAssertFalse(xml.contains("<LabelStyle>"), "labelBadge should omit LabelStyle (ForeFlight ignores it)")
+    }
 }
diff --git a/Tests/ForeFlightKMLTests/StyleTests/IconStyle+HiddenTests.swift b/Tests/ForeFlightKMLTests/StyleTests/IconStyle+HiddenTests.swift
new file mode 100644
index 0000000..315ad74
--- /dev/null
+++ b/Tests/ForeFlightKMLTests/StyleTests/IconStyle+HiddenTests.swift
@@ -0,0 +1,44 @@
+import XCTest
+@testable import ForeFlightKML
+import GeodesySpherical
+
+final class LabelOnlyTests: XCTestCase {
+
+    func test_iconStyleTransparentLocalPng_emitsLocalHref() {
+        let kml = IconStyle.transparentLocalPng().kmlString()
+
+        XCTAssertTrue(kml.contains("<IconStyle>"))
+        XCTAssertTrue(kml.contains("<Icon>"))
+        XCTAssertTrue(
+            kml.contains("<href>1x1.png</href>"),
+            "Label-only icon must reference bundled transparent PNG"
+        )
+        XCTAssertTrue(kml.contains("</IconStyle>"))
+    }
+
+    func test_pointStyleLabelOnly_emitsStyle() {
+        let style = PointStyle.labelBadge(color: .white)
+        let kml = style.kmlString()
+
+        XCTAssertTrue(kml.contains("<Style id=\""), "PointStyle should emit a Style wrapper")
+        XCTAssertTrue(kml.contains("<IconStyle>"), "Label-only style must include IconStyle (hidden icon)")
+        XCTAssertTrue(kml.contains("<href>1x1.png</href>"))
+        XCTAssertFalse(kml.contains("<LabelStyle>"), "For Label-only, FF ignores LabelStyle")
+        XCTAssertTrue(kml.contains("</Style>"))
+    }
+
+    func test_builderAddLabel_emitsPlacemarkNameAndHiddenIconScale() {
+        let builder = ForeFlightKMLBuilder()
+
+        builder.addLabel("Label Warning", coordinate: .init(latitude: 51.2345, longitude: -1.2345), color: .warning)
+        let kml = builder.build()
+
+        XCTAssertTrue(kml.contains("<Placemark>"))
+        XCTAssertTrue(kml.contains("<Style id=\"ps-"), "PointStyle should generate ps- style id by default")
+        XCTAssertTrue(kml.contains("<IconStyle>"))
+        XCTAssertFalse(kml.contains("<LabelStyle>"), "For Label-only, FF ignores LabelStyle")
+        XCTAssertTrue(kml.contains("<href>1x1.png</href>"))
+        XCTAssertTrue(kml.contains("<Point>"), "Label must still be attached to a Point geometry")
+        XCTAssertTrue(kml.contains("<coordinates>"), "Point should emit coordinates")
+    }
+}
diff --git a/Tests/ForeFlightKMLTests/StyleTests/IconStyleTests.swift b/Tests/ForeFlightKMLTests/StyleTests/IconStyleTests.swift
index 8691930..9bb8e06 100644
--- a/Tests/ForeFlightKMLTests/StyleTests/IconStyleTests.swift
+++ b/Tests/ForeFlightKMLTests/StyleTests/IconStyleTests.swift
@@ -52,4 +52,19 @@ final class IconStyleTests: XCTestCase {
         let kml2 = icon2.kmlString()
         XCTAssertTrue(kml2.contains("<scale>0.5</scale>"))
     }
+    
+    func test_iconStyle_transparentLocalPng_requiresKMZ_true() {
+        let icon = IconStyle.transparentLocalPng(tint: .white, scale: 1.0)
+        XCTAssertTrue(icon.requiresKMZ)
+    }
+
+    func test_iconStyle_customGoogleShape_requiresKMZ_false() {
+        let icon = IconStyle.custom(type: .square, color: .white, scale: 1.0)
+        XCTAssertFalse(icon.requiresKMZ)
+    }
+
+    func test_iconStyle_predefinedGooglePaddle_requiresKMZ_false() {
+        let icon = IconStyle.predefined(type: .circle, color: .red, scale: 1.0)
+        XCTAssertFalse(icon.requiresKMZ)
+    }
 }
diff --git a/Tests/ForeFlightKMLTests/UserMapShapesSampleFullTest.swift b/Tests/ForeFlightKMLTests/UserMapShapesSampleFullTest.swift
index 5026eaf..45911db 100644
--- a/Tests/ForeFlightKMLTests/UserMapShapesSampleFullTest.swift
+++ b/Tests/ForeFlightKMLTests/UserMapShapesSampleFullTest.swift
@@ -267,7 +267,7 @@ final class UserMapShapesRecreationTests: XCTestCase {
             altitude: 0,
             style: PointStyle(
                 icon: .custom(type: .square, color: .fromHex("FFB001"), scale: 1.2),
-                label: LabelStyle(color: .fromHex("FEA109"))
+                label: LabelStyle(color: .fromHex("FFB001"))
             )
         )
 
@@ -277,7 +277,7 @@ final class UserMapShapesRecreationTests: XCTestCase {
             altitude: 0,
             style: PointStyle(
                 icon: .custom(type: .triangle, color: .fromHex("BFF394"), scale: 1.2),
-                label: LabelStyle(color: .fromHex("FEA109"))
+                label: LabelStyle(color: .fromHex("BFF394"))
             )
         )
 
diff --git a/Tests/ForeFlightKMLTests/UserMapShapesSampleIndividualTests.swift b/Tests/ForeFlightKMLTests/UserMapShapesSampleIndividualTests.swift
index e3f6e96..7bf522c 100644
--- a/Tests/ForeFlightKMLTests/UserMapShapesSampleIndividualTests.swift
+++ b/Tests/ForeFlightKMLTests/UserMapShapesSampleIndividualTests.swift
@@ -41,7 +41,6 @@ final class ExampleKMLRecreationTests: XCTestCase {
 
         let kml = builder.kmlString()
         XCTAssertTrue(kml.contains("<name>bpin</name>"))
-        print(kml)
         XCTAssertTrue(kml.contains("blue-pushpin.png"))
     }
 

From 3148b10b69235e05d9f5318fa3cac5f734dbf416 Mon Sep 17 00:00:00 2001
From: Dan Leedham <danleedham@googlemail.com>
Date: Wed, 17 Dec 2025 14:57:41 +0000
Subject: [PATCH 2/6] Linting

---
 .github/workflows/swiftlint.yml                               | 4 +---
 Sources/ForeFlightKML/ForeFlightKML+Convenience.swift         | 2 +-
 Sources/ForeFlightKML/ForeFlightKML.swift                     | 2 +-
 Sources/ForeFlightKML/Models/StyleManager.swift               | 2 +-
 Sources/ForeFlightKML/Styles/Geometry/PointStyle.swift        | 2 +-
 Sources/ForeFlightKML/Styles/IconStyle.swift                  | 2 +-
 Sources/ForeFlightKML/Styles/Style.swift                      | 2 +-
 Tests/ForeFlightKMLTests/ForeFlightKML+KMZTests.swift         | 4 +---
 .../StyleTests/Geometry/PointStyleTests.swift                 | 2 +-
 Tests/ForeFlightKMLTests/StyleTests/IconStyleTests.swift      | 2 +-
 10 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/swiftlint.yml b/.github/workflows/swiftlint.yml
index 9bd1d56..6bf9087 100644
--- a/.github/workflows/swiftlint.yml
+++ b/.github/workflows/swiftlint.yml
@@ -13,9 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v1
-      - name: GitHub Action for SwiftLint
-        uses: norio-nomura/action-swiftlint@3.2.1
       - name: GitHub Action for SwiftLint with --strict
         uses: norio-nomura/action-swiftlint@3.2.1
         with:
-          args: --strict
\ No newline at end of file
+          args: --fix --quiet
\ No newline at end of file
diff --git a/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift b/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift
index f0110e8..22abff0 100644
--- a/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift
+++ b/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift
@@ -291,7 +291,7 @@ extension ForeFlightKMLBuilder {
         let placemark = Placemark(name: name, geometry: segment, style: style)
         return addPlacemark(placemark)
     }
-    
+
     @discardableResult
     public func addLabel(
         _ text: String,
diff --git a/Sources/ForeFlightKML/ForeFlightKML.swift b/Sources/ForeFlightKML/ForeFlightKML.swift
index 3ec83e7..e391544 100644
--- a/Sources/ForeFlightKML/ForeFlightKML.swift
+++ b/Sources/ForeFlightKML/ForeFlightKML.swift
@@ -46,7 +46,7 @@ public final class ForeFlightKMLBuilder {
         }
         return self
     }
-    
+
     /// True if this document must be exported as KMZ to render correctly.
     var requiresKMZ: Bool {
         styleManager.requiresKMZ
diff --git a/Sources/ForeFlightKML/Models/StyleManager.swift b/Sources/ForeFlightKML/Models/StyleManager.swift
index de22251..fb3935a 100644
--- a/Sources/ForeFlightKML/Models/StyleManager.swift
+++ b/Sources/ForeFlightKML/Models/StyleManager.swift
@@ -46,7 +46,7 @@ internal class StyleManager {
             markAsReferenced(styleId)
         }
     }
-    
+
     /// True if any referenced style requires KMZ packaging.
     var requiresKMZ: Bool {
         referencedStyleIds.contains { id in
diff --git a/Sources/ForeFlightKML/Styles/Geometry/PointStyle.swift b/Sources/ForeFlightKML/Styles/Geometry/PointStyle.swift
index e648e6f..21b79b0 100644
--- a/Sources/ForeFlightKML/Styles/Geometry/PointStyle.swift
+++ b/Sources/ForeFlightKML/Styles/Geometry/PointStyle.swift
@@ -24,7 +24,7 @@ public struct PointStyle: KMLStyle {
     public func id() -> String {
         return styleId
     }
-    
+
     public var requiresKMZ: Bool {
         icon.requiresKMZ
     }
diff --git a/Sources/ForeFlightKML/Styles/IconStyle.swift b/Sources/ForeFlightKML/Styles/IconStyle.swift
index 9da0ed2..85df0fc 100644
--- a/Sources/ForeFlightKML/Styles/IconStyle.swift
+++ b/Sources/ForeFlightKML/Styles/IconStyle.swift
@@ -60,7 +60,7 @@ public struct IconStyle: KMLSubStyle {
     func iconHref() -> String {
         return iconHrefValue
     }
-    
+
     /// True if this icon references a local resource and therefore
     /// requires KMZ packaging to render correctly in ForeFlight.
     var requiresKMZ: Bool {
diff --git a/Sources/ForeFlightKML/Styles/Style.swift b/Sources/ForeFlightKML/Styles/Style.swift
index 18660d8..a8604c5 100644
--- a/Sources/ForeFlightKML/Styles/Style.swift
+++ b/Sources/ForeFlightKML/Styles/Style.swift
@@ -19,7 +19,7 @@ internal struct Style: KMLStyle {
     public func id() -> String {
         return styleId
     }
-    
+
     var requiresKMZ: Bool {
         subStyles.contains {
             ($0 as? IconStyle)?.requiresKMZ == true
diff --git a/Tests/ForeFlightKMLTests/ForeFlightKML+KMZTests.swift b/Tests/ForeFlightKMLTests/ForeFlightKML+KMZTests.swift
index 266434b..15ace04 100644
--- a/Tests/ForeFlightKMLTests/ForeFlightKML+KMZTests.swift
+++ b/Tests/ForeFlightKMLTests/ForeFlightKML+KMZTests.swift
@@ -58,7 +58,7 @@ final class KMZPackagingTests: XCTestCase {
         try kmzData.write(to: url)
         return try Archive(url: url, accessMode: .read)
     }
-    
+
     func test_builderAddLabel() {
         let builder = ForeFlightKMLBuilder()
 
@@ -76,5 +76,3 @@ final class KMZPackagingTests: XCTestCase {
         }
     }
 }
-
-
diff --git a/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift b/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
index 88752f2..757f5c5 100644
--- a/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
+++ b/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
@@ -46,7 +46,7 @@ final class PointStylesTests: XCTestCase {
 
         XCTAssertNotEqual(style1.id(), style2.id())
     }
-    
+
     func test_pointStyle_requiresKMZ_followsIconStyle() {
         let s1 = PointStyle(icon: .transparentLocalPng(tint: .white))
         XCTAssertTrue(s1.requiresKMZ)
diff --git a/Tests/ForeFlightKMLTests/StyleTests/IconStyleTests.swift b/Tests/ForeFlightKMLTests/StyleTests/IconStyleTests.swift
index 9bb8e06..43401b7 100644
--- a/Tests/ForeFlightKMLTests/StyleTests/IconStyleTests.swift
+++ b/Tests/ForeFlightKMLTests/StyleTests/IconStyleTests.swift
@@ -52,7 +52,7 @@ final class IconStyleTests: XCTestCase {
         let kml2 = icon2.kmlString()
         XCTAssertTrue(kml2.contains("<scale>0.5</scale>"))
     }
-    
+
     func test_iconStyle_transparentLocalPng_requiresKMZ_true() {
         let icon = IconStyle.transparentLocalPng(tint: .white, scale: 1.0)
         XCTAssertTrue(icon.requiresKMZ)

From 27d26cb7d9b28c4c58330564d146038134826775 Mon Sep 17 00:00:00 2001
From: Dan Leedham <danleedham@googlemail.com>
Date: Wed, 17 Dec 2025 15:30:01 +0000
Subject: [PATCH 3/6] Throw error if KMZ required and build called

---
 README.md                                     | 39 +++++++------------
 .../ForeFlightKML+Convenience.swift           | 24 +++++-------
 Sources/ForeFlightKML/ForeFlightKML.swift     |  8 +++-
 3 files changed, 28 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
index 80dc333..37d24d0 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,6 @@
 
 This package provides a small, focused API for composing KML documents suitable for importing into ForeFlight as **User Map Shapes (KML)**. It intentionally avoids UI concerns — it gives you `String` KML output (or bytes) which your app can write to disk and share using the standard iOS share sheet.
     
----
 
 ## Quick highlights
 
@@ -13,7 +12,6 @@ This package provides a small, focused API for composing KML documents suitable
 - `ForeFlightKMLBuilder` collects placemarks and styles, emits a complete `kml` document string.
 - Lightweight — no UI code.
 
----
 
 ## Install
 
@@ -21,7 +19,6 @@ This package provides a small, focused API for composing KML documents suitable
 2. Enter the repository URL.
 3. Choose the `ForeFlightKML` package product and add it to your app target.
 
----
 
 ## Example Output 
 Using the example given on the [ForeFlight website](https://foreflight.com/support/user-map-shapes/) the below is generated using this Framework. 
@@ -30,27 +27,23 @@ See `/Tests/ForeFlightKMLTests/UserMapShapesSampleFullTest.swift`
 
 <img width="615" height="770" alt="Image" src="/docs/example-output.png" />
 
-## Minimal Quick Start
+## Quick Start
 
 ```swift
 import ForeFlightKML
-import Geodesy (we use this for Coordinate and relative positioniong)
+import Geodesy (used for coordinates)
 
-// Example: Airport Traffic Pattern
 let builder = ForeFlightKMLBuilder(documentName: "Airport with ATZ")
-
-// Runway centerline
 builder.addLine(
     name: "Runway 15-33", 
     coordinates: [Coordinate(latitude:, longitude:),Coordinate(latitude:, longitude:)],
     style: LineStyle(color: .black)
 )
 
-// Traffic Warning Area
 builder.addLineCircle(
     name: "Airport ATZ", 
     center: airportCenter, 
-    radiusMeters: 4630, // 2.5 nautical mile ATZ
+    radiusMeters: 4630,
     PolygonStyle(outlineColor: .black, fillColor: .warning.withAlpha(0.3))
 )
 
@@ -60,9 +53,8 @@ presentShareSheet(with: url)
 ```
 
 > **Note**: ForeFlight supports importing KML/KMZ files via the iOS share sheet. See ForeFlight's docs for exact import behavior.
----
 
-## API quick reference (important types)
+## API quick reference
 
 - `ForeFlightKMLBuilder` — builder for the KML document. Methods: `addPlacemark(_:)`, `kmlString()`.
 - `Placemark` — a Feature containing a geometry (must implement `KMLElement`). Optionally attach a `KMLStyle`.
@@ -70,36 +62,31 @@ presentShareSheet(with: url)
 - `Style` and substyles: `LineStyle`, `PolyStyle`, `IconStyle`, `LabelStyle`.
 - `KMLColor` — helper to create the aabbggrr color values used by KML.
 
-Full public API surface is visible in the package sources; the README examples show common usage patterns.
+### Export formats
+- `kml String` via `builder.build()`
+- `kml Data` via `builder.kmlData()`
+- `kmz Data` via `builder.buildKMZ()` 
+- KMZ (zipped KML) is required when using custom icons or using labelBadge (which uses a transparent .png under the hood). 
 
----
+Full public API surface is visible in the package sources.
 
 ## Notes, conventions and gotchas
 
+
 - **Coordinates order**: KML requires `longitude,latitude[,altitude]`. The public API accepts `Coordinate(latitude:..., longitude:...)` (from `Geodesy`) and the framework emits coordinates in the KML `lon,lat[,alt]` order.
 - **Units**: Distances (e.g. `LineCircle.radius`) are in **meters**.
 - **Angles/bearings**: bearings (for arc & circle generation) are interpreted in degrees (0..360). The bearing convention is clockwise from north.
 - **Altitude**: When you provide altitudes, the `AltitudeMode` is emitted (defaults to `.absolute` in most geometries).
 - **Styles**: `Style` generates a stable `id` when provided; otherwise a UUID-based id is generated. `ForeFlightKMLBuilder` will automatically register styles added via `Placemark`.
 
-### ForeFlight point label color (important)
-
-For Point placemarks:
-- LabelStyle.color is ignored
-- Label badge color is driven by IconStyle.color
-
 To create a label-only point with a colored badge:
 ```
-    builder.addLabel("Text", coordinate: .init(...), color: KMLColor)
+    builder.addLabel("Text", coordinate: .init(...), color: KMLColor?)
 ```
 
----
-
 ## Demo & tests
 
-The repo contains an `Example` app that demonstrates building shapes and the `Tests` folder with unit tests. Before publishing, ensure the example builds and the tests run in CI.
-
----
+The repo contains an `Example` app that demonstrates building shapes and the `Tests` folder with unit tests. 
 
 ## Contributing
 
diff --git a/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift b/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift
index 22abff0..0be0591 100644
--- a/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift
+++ b/Sources/ForeFlightKML/ForeFlightKML+Convenience.swift
@@ -292,6 +292,15 @@ extension ForeFlightKMLBuilder {
         return addPlacemark(placemark)
     }
 
+    /// Add a text-only label placemark at a coordinate.
+    /// This uses a transparent 1×1 icon to enable ForeFlight’s “badge” rendering, with the badge color driven by `IconStyle.color`.
+    /// - Important: Because this relies on a local icon asset, the output **must be exported as KMZ** (not plain KML) for the label to render correctly.
+    /// - Parameters:
+    ///   - text: Label text displayed in ForeFlight
+    ///   - coordinate: Geographic coordinate
+    ///   - altitude: Altitude in meters (optional)
+    ///   - color: Badge/background color for the label (default: white)
+    /// - Returns: Self for method chaining
     @discardableResult
     public func addLabel(
         _ text: String,
@@ -307,19 +316,4 @@ extension ForeFlightKMLBuilder {
         )
     }
 
-    @discardableResult
-    public func addLabel(
-        _ text: String,
-        latitude: Double,
-        longitude: Double,
-        altitude: Double? = nil,
-        color: KMLColor = .white
-    ) -> Self {
-        addLabel(
-            text,
-            coordinate: Coordinate(latitude: latitude, longitude: longitude),
-            altitude: altitude,
-            color: color
-        )
-    }
 }
diff --git a/Sources/ForeFlightKML/ForeFlightKML.swift b/Sources/ForeFlightKML/ForeFlightKML.swift
index e391544..445d6b2 100644
--- a/Sources/ForeFlightKML/ForeFlightKML.swift
+++ b/Sources/ForeFlightKML/ForeFlightKML.swift
@@ -48,7 +48,7 @@ public final class ForeFlightKMLBuilder {
     }
 
     /// True if this document must be exported as KMZ to render correctly.
-    var requiresKMZ: Bool {
+    public var requiresKMZ: Bool {
         styleManager.requiresKMZ
     }
 
@@ -57,7 +57,11 @@ public final class ForeFlightKMLBuilder {
     /// Generate the complete KML string for this document.
     /// This method can be called multiple times - it doesn't modify the builder state.
     /// - Returns: A complete KML document as a UTF-8 string ready for export to ForeFlight
-    public func build() -> String {
+    public func build() throws -> String {
+        guard !requiresKMZ else {
+            throw KMZExportError.kmzRequired
+        }
+
         return kmlString()
     }
 

From b24616e66c53953f1581d2c2f182875dba121c68 Mon Sep 17 00:00:00 2001
From: Dan Leedham <danleedham@googlemail.com>
Date: Wed, 17 Dec 2025 15:38:21 +0000
Subject: [PATCH 4/6] Update tests

---
 .../GeometryTests/PolygonAnnularSegmentTests.swift  |  2 +-
 .../StyleTests/Geometry/PointStyleTests.swift       | 13 ++++++++++---
 .../StyleTests/IconStyle+HiddenTests.swift          |  4 ++--
 .../UserMapShapesSampleFullTest.swift               |  2 +-
 4 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/Tests/ForeFlightKMLTests/GeometryTests/PolygonAnnularSegmentTests.swift b/Tests/ForeFlightKMLTests/GeometryTests/PolygonAnnularSegmentTests.swift
index c7ea25d..80a5c09 100644
--- a/Tests/ForeFlightKMLTests/GeometryTests/PolygonAnnularSegmentTests.swift
+++ b/Tests/ForeFlightKMLTests/GeometryTests/PolygonAnnularSegmentTests.swift
@@ -170,7 +170,7 @@ final class PolygonAnnularSegmentTests: XCTestCase {
             )
         }
 
-        let kml = builder.build()
+        let kml = try builder.build()
 
         XCTAssertTrue(kml.contains("<Document>"))
         let placemarkCount = kml.components(separatedBy: "<Placemark>").count - 1
diff --git a/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift b/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
index 757f5c5..c5262c3 100644
--- a/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
+++ b/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
@@ -60,15 +60,22 @@ final class PointStylesTests: XCTestCase {
         XCTAssertTrue(s.requiresKMZ)
     }
 
-    func test_addLabel_emitsTransparentHref_andIconColor() {
+    func test_addLabel_emitsTransparentHref_andIconColor() throws {
         let builder = ForeFlightKMLBuilder(documentName: "Test")
         builder.addLabel("Badge", coordinate: Coordinate(latitude: 51.0, longitude: -1.0), color: .warning)
-
-        let kml = builder.build()
+        let kml = builder.kmlString()
 
         XCTAssertTrue(kml.contains("<href>1x1.png</href>"))
         XCTAssertTrue(kml.contains("<IconStyle>"))
         XCTAssertTrue(kml.contains("<color>"), "Label badge must emit IconStyle color (drives ForeFlight badge)")
+        
+        do {
+            let _ = try builder.buildKMZ()
+        } catch {
+            XCTFail("buildKMZ() threw: \(error)")
+            return
+        }
+
     }
 
     func test_labelBadge_doesNotEmitLabelStyle() {
diff --git a/Tests/ForeFlightKMLTests/StyleTests/IconStyle+HiddenTests.swift b/Tests/ForeFlightKMLTests/StyleTests/IconStyle+HiddenTests.swift
index 315ad74..8b0f889 100644
--- a/Tests/ForeFlightKMLTests/StyleTests/IconStyle+HiddenTests.swift
+++ b/Tests/ForeFlightKMLTests/StyleTests/IconStyle+HiddenTests.swift
@@ -27,11 +27,11 @@ final class LabelOnlyTests: XCTestCase {
         XCTAssertTrue(kml.contains("</Style>"))
     }
 
-    func test_builderAddLabel_emitsPlacemarkNameAndHiddenIconScale() {
+    func test_builderAddLabel_emitsPlacemarkNameAndHiddenIconScale() throws {
         let builder = ForeFlightKMLBuilder()
 
         builder.addLabel("Label Warning", coordinate: .init(latitude: 51.2345, longitude: -1.2345), color: .warning)
-        let kml = builder.build()
+        let kml = try builder.build()
 
         XCTAssertTrue(kml.contains("<Placemark>"))
         XCTAssertTrue(kml.contains("<Style id=\"ps-"), "PointStyle should generate ps- style id by default")
diff --git a/Tests/ForeFlightKMLTests/UserMapShapesSampleFullTest.swift b/Tests/ForeFlightKMLTests/UserMapShapesSampleFullTest.swift
index 45911db..e350347 100644
--- a/Tests/ForeFlightKMLTests/UserMapShapesSampleFullTest.swift
+++ b/Tests/ForeFlightKMLTests/UserMapShapesSampleFullTest.swift
@@ -341,7 +341,7 @@ final class UserMapShapesRecreationTests: XCTestCase {
             )
         )
 
-        let kml = builder.build()
+        let kml = try builder.build()
         let tempDir = FileManager.default.temporaryDirectory
         let fileURL = tempDir.appendingPathComponent("FFIconTest_Generated.kml")
 

From 44044716a62dca8329a5a6f0e78dd9c6ff8d5477 Mon Sep 17 00:00:00 2001
From: Dan Leedham <danleedham@googlemail.com>
Date: Wed, 17 Dec 2025 15:39:07 +0000
Subject: [PATCH 5/6] Update readme

---
 README.md | 35 ++++++++++++++++++++++++++---------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 37d24d0..ba05f9c 100644
--- a/README.md
+++ b/README.md
@@ -12,9 +12,7 @@ This package provides a small, focused API for composing KML documents suitable
 - `ForeFlightKMLBuilder` collects placemarks and styles, emits a complete `kml` document string.
 - Lightweight — no UI code.
 
-
 ## Install
-
 1. In Xcode: **File › Add Packages...**
 2. Enter the repository URL.
 3. Choose the `ForeFlightKML` package product and add it to your app target.
@@ -54,20 +52,39 @@ presentShareSheet(with: url)
 
 > **Note**: ForeFlight supports importing KML/KMZ files via the iOS share sheet. See ForeFlight's docs for exact import behavior.
 
-## API quick reference
 
-- `ForeFlightKMLBuilder` — builder for the KML document. Methods: `addPlacemark(_:)`, `kmlString()`.
-- `Placemark` — a Feature containing a geometry (must implement `KMLElement`). Optionally attach a `KMLStyle`.
-- Geometry types: `Point`, `Line`, `LineCircle`, `LineSegment` (segment of a Circle), `Polygon`, `PolygonCircle` (filled circle), `PolygonSegment` (filled segment) `LinearRing`.
-- `Style` and substyles: `LineStyle`, `PolyStyle`, `IconStyle`, `LabelStyle`.
-- `KMLColor` — helper to create the aabbggrr color values used by KML.
 
-### Export formats
+## API Reference
+
+### KMLBuidler
+ `ForeFlightKMLBuilder` is the builder for the KML/KMZ document. 
+ - Document name can be set on `init` or with `setDocumentName()` 
+ - Elements can be manually added using `addPlacemark(_:)`
+ - The complete KML string is accessed by `builder.build()`
+
+### KMLBuilder Convenience Elements
+ - `addPoint` Add a point with style.
+ - `addLine` Add a line connecting multiple coordinates.
+ - `addLineCircle` Add a circular line (approximated by line segments).
+ - `addLineSegment` Add an arc segment line geometry.
+ - `addPolygon` Add a polygon with outer boundary and optional holes.
+ - `addPolygonCircle` Add a polygon with outer boundary and optional holes.
+ - `addPolygonSegment` Add a filled segment polygon (pie slice).
+ - `addPolygonAnnularSegment` Add a filled annular (ring) segment polygon.
+ - `addLabel` Add a text-only label placemark at a coordinate.
+
+### ForeflightKMLBuilder Export formats
 - `kml String` via `builder.build()`
 - `kml Data` via `builder.kmlData()`
 - `kmz Data` via `builder.buildKMZ()` 
 - KMZ (zipped KML) is required when using custom icons or using labelBadge (which uses a transparent .png under the hood). 
 
+### Underlying elements
+- `Placemark` — a Feature containing a geometry (must implement `KMLElement`). Optionally attach a `KMLStyle`.
+- Geometry types: `Point`, `Line`, `LineCircle`, `LineSegment` (segment of a Circle), `Polygon`, `PolygonCircle` (filled circle), `PolygonSegment` (filled segment) `LinearRing`.
+- `Style` and substyles: `LineStyle`, `PolyStyle`, `IconStyle`, `LabelStyle`.
+- `KMLColor` — helper to create the aabbggrr color values used by KML.
+
 Full public API surface is visible in the package sources.
 
 ## Notes, conventions and gotchas

From badb7aeeaf92fd1658827d5f11cf317a74d8369c Mon Sep 17 00:00:00 2001
From: Dan Leedham <danleedham@googlemail.com>
Date: Wed, 17 Dec 2025 15:39:41 +0000
Subject: [PATCH 6/6] Update PointStyleTests.swift

---
 .../StyleTests/Geometry/PointStyleTests.swift                 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift b/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
index c5262c3..7683582 100644
--- a/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
+++ b/Tests/ForeFlightKMLTests/StyleTests/Geometry/PointStyleTests.swift
@@ -68,9 +68,9 @@ final class PointStylesTests: XCTestCase {
         XCTAssertTrue(kml.contains("<href>1x1.png</href>"))
         XCTAssertTrue(kml.contains("<IconStyle>"))
         XCTAssertTrue(kml.contains("<color>"), "Label badge must emit IconStyle color (drives ForeFlight badge)")
-        
+
         do {
-            let _ = try builder.buildKMZ()
+            _ = try builder.buildKMZ()
         } catch {
             XCTFail("buildKMZ() threw: \(error)")
             return