iOS Blog Feed Widget

ios/EXTENSIONS.md

@@ -0,0 +1,42 @@
+# iOS Extensions
+
+## Building extensions as a contributor
+
+Each iOS app extension (e.g. the Lichess widgets) is a separate Xcode target with its own bundle ID. For the extension to be installed on a device, that bundle ID must be registered in the Lichess Apple Developer account with a matching provisioning profile.
+
+As an external contributor you won't have access to that account, so `flutter run` will silently drop the extension from the bundle — you can add the app to your home screen but the widget won't appear in the widget catalog.
+
+### Testing locally
+
+You can still build and test extensions using your own Apple Developer account and iOS Simulator. A free account is enough for device testing.
+
+1. Open `ios/Runner.xcworkspace` in Xcode.
+2. Select the **Runner** target → **Signing & Capabilities** → set **Team** to your account and change the bundle ID to something you own (e.g. `com.yourname.lichess`).
+3. Do the same for the extension target (e.g. **LichessWidgetsExtension**), using a matching sub-ID (e.g. `com.yourname.lichess.widget`).
+4. Build and run from Xcode — the extension will be signed with your profile and work on your device.
+
+These changes are local only and should not be committed.
+
+### Merging new extensions
+
+When a PR that adds a new extension is ready to merge, a Lichess org member with Apple Developer access needs to:
+
+1. Register the new App ID (for the extension's bundle ID) in the Apple Developer portal.
+2. Create a provisioning profile for it.
+
+## Deploying extensions via fastlane
+
+Extensions have their own bundle ID (`org.lichess.mobileV2.<ExtensionName>`) and require a separate provisioning profile managed by `match`. The `Matchfile` and `Fastfile` list all extension bundle IDs alongside the main app.
+
+### Adding a new extension to the fastlane setup
+
+After registering the App ID in the developer portal (see above), run `match` once to create and store the provisioning profile:
+
+```sh
+cd ios
+bundle exec fastlane match appstore --app_identifier org.lichess.mobileV2.<ExtensionName>
+```
+
+This will generate the profile, push it to the certificates repo, and set the correct `PROVISIONING_PROFILE_SPECIFIER` in the Xcode project. After that, `fastlane beta` handles signing for all targets automatically — including in CI.
+
+Also add the new bundle ID to both `app_identifier` arrays in `fastlane/Matchfile` and the `sync_code_signing` call in `fastlane/Fastfile`.

ios/LichessWidgets/Blog Feed Widget/BlogFeedFetcher.swift

@@ -0,0 +1,70 @@
+import FeedKit
+import UIKit
+import WidgetKit
+internal import XMLKit
+
+struct BlogFeedFetcher {
+    static var nextUpdateDate: Date {
+        Calendar.current.date(byAdding: .hour, value: 1, to: .now)!
+    }
+
+    private func fetchThumbnail(urlString: String, spec: BlogThumbnailSpec) async -> Data? {
+        guard let url = URL(string: urlString),
+              let (data, _) = try? await URLSession.shared.data(from: url),
+              let source = UIImage(data: data)
+        else { return nil }
+        let scale = UITraitCollection.current.displayScale
+        let size = CGSize(width: spec.width * scale, height: spec.height * scale)
+        return await source.byPreparingThumbnail(ofSize: size)?.jpegData(compressionQuality: 0.85)
+    }
+
+    func fetchEntry(feed: BlogFeedChoice, username: String?, family: WidgetFamily) async -> BlogFeedEntry {
+        let (items, error) = await fetchFeed(feed: feed, username: username, family: family)
+        return BlogFeedEntry(date: .now, feed: feed, username: username, items: items, error: error)
+    }
+
+    private func fetchFeed(feed: BlogFeedChoice,
+                           username: String?,
+                           family: WidgetFamily) async -> (items: [BlogFeedItem], error: String?) {
+        guard let urlString = feed.feedURL(username: username) else {
+            return ([], "Enter a username in widget settings")
+        }
+        do {
+            guard case .atom(let atomFeed) = try await Feed(urlString: urlString) else {
+                return ([], "Unexpected feed format")
+            }
+            let thumbSpec = family.thumbnailSpec
+            let items = await withTaskGroup(of: (Int, BlogFeedItem).self) { group in
+                for (index, entry) in (atomFeed.entries ?? []).prefix(family.maxItems).enumerated() {
+                    group.addTask {
+                        let thumbData: Data? = if let thumbSpec,
+                                                  let thumbURL = entry.media?.thumbnails?.first?.attributes?.url {
+                            await fetchThumbnail(urlString: thumbURL, spec: thumbSpec)
+                        } else {
+                            nil
+                        }
+                        let entryURL = entry.links?
+                            .first(where: { $0.attributes?.rel == "alternate" })?
+                            .attributes?.href
+                            ?? entry.links?.first?.attributes?.href
+                        return (index, BlogFeedItem(
+                            id: entry.id ?? "\(index)",
+                            title: entry.title ?? "Untitled",
+                            url: entryURL,
+                            publishedDate: entry.published,
+                            author: entry.authors?.first?.name,
+                            thumbnailData: thumbData,
+                            thumbnailImageName: nil
+                        ))
+                    }
+                }
+                var results: [(Int, BlogFeedItem)] = []
+                for await result in group { results.append(result) }
+                return results.sorted { $0.0 < $1.0 }.map(\.1)
+            }
+            return (items, nil)
+        } catch {
+            return ([], error.localizedDescription)
+        }
+    }
+}

ios/LichessWidgets/Blog Feed Widget/BlogFeedPlaceholder.swift

@@ -0,0 +1,121 @@
+import Foundation
+import WidgetKit
+
+/// Static placeholder data shown in the widget gallery and while a widget loads.
+enum BlogFeedPlaceholder {
+    static func entry(feed: BlogFeedChoice, username: String? = nil, family: WidgetFamily) -> BlogFeedEntry {
+        BlogFeedEntry(
+            date: .now,
+            feed: feed,
+            username: username,
+            items: Array(items(for: feed).prefix(family.maxItems)),
+            error: nil
+        )
+    }
+
+    private static func items(for feed: BlogFeedChoice) -> [BlogFeedItem] {
+        switch feed {
+        case .officialBlog: return officialBlogItems
+        case .communityBlog: return communityBlogItems
+        case .userBlog: return userBlogItems
+        }
+    }
+
+    // MARK: Official Blog
+
+    private static let officialBlogItems: [BlogFeedItem] = [
+        BlogFeedItem(id: "1",
+                     title: "Lichess Mobile App Update",
+                     url: nil,
+                     publishedDate: daysAgo(1),
+                     author: nil,
+                     thumbnailData: nil,
+                     thumbnailImageName: "OfficialBlogPlaceholderImage1"),
+        BlogFeedItem(id: "2",
+                     title: "Queens' Online Chess Festival",
+                     url: nil,
+                     publishedDate: daysAgo(31),
+                     author: nil,
+                     thumbnailData: nil,
+                     thumbnailImageName: "OfficialBlogPlaceholderImage2"),
+        BlogFeedItem(id: "3",
+                     title: "Announcing the ChessMood 20/20 Grand Prix 2026",
+                     url: nil,
+                     publishedDate: daysAgo(35),
+                     author: nil,
+                     thumbnailData: nil,
+                     thumbnailImageName: "OfficialBlogPlaceholderImage3"),
+        BlogFeedItem(id: "4",
+                     title: "Streamer Arenas Announcement — February to July 2026",
+                     url: nil,
+                     publishedDate: daysAgo(39),
+                     author: nil,
+                     thumbnailData: nil,
+                     thumbnailImageName: "OfficialBlogPlaceholderImage4"),
+    ]
+
+    // MARK: Community Blog
+
+    private static let communityBlogItems: [BlogFeedItem] = [
+        BlogFeedItem(id: "1",
+                     title: "How To Analyse Your Game Like a 2000-Rated Player",
+                     url: nil,
+                     publishedDate: daysAgo(0),
+                     author: "VihaanRathodBhuj",
+                     thumbnailData: nil,
+                     thumbnailImageName: "CommunityBlogPlaceholderImage1"),
+        BlogFeedItem(id: "2",
+                     title: "What a Figure Skater Can Teach You About Chess Improvement",
+                     url: nil,
+                     publishedDate: daysAgo(0),
+                     author: "FM MattyDPerrine",
+                     thumbnailData: nil,
+                     thumbnailImageName: "CommunityBlogPlaceholderImage2"),
+        BlogFeedItem(id: "3", title: "Slow Growth in Chess: The Truth Most People Don't Want to Hear",
+                     url: nil, publishedDate: daysAgo(2),
+                     author: "IM nikhildixit",
+                     thumbnailData: nil,
+                     thumbnailImageName: "CommunityBlogPlaceholderImage3"),
+        BlogFeedItem(id: "4", title: "Everyone's favorite: A modern Kortchnoi seeking to change his history",
+                     url: nil,
+                     publishedDate: daysAgo(0),
+                     author: "FM Reynold9402",
+                     thumbnailData: nil,
+                     thumbnailImageName: "CommunityBlogPlaceholderImage4"),
+    ]
+
+    // MARK: User Blog
+
+    private static let userBlogItems: [BlogFeedItem] = [
+        BlogFeedItem(id: "1",
+                     title: "Did you know Lichess can do this? Opening Explorer and Tablebase",
+                     url: nil,
+                     publishedDate: daysAgo(2),
+                     author: nil,
+                     thumbnailData: nil,
+                     thumbnailImageName: "UserBlogPlaceholderImage1"),
+        BlogFeedItem(id: "2",
+                     title: "Annotated: Sicilian Accelerated Dragon Deep Dive",
+                     url: nil,
+                     publishedDate: daysAgo(7),
+                     author: nil,
+                     thumbnailData: nil, thumbnailImageName: "UserBlogPlaceholderImage2"),
+        BlogFeedItem(id: "3",
+                     title: "Tournament Report: City Open 2026",
+                     url: nil,
+                     publishedDate: daysAgo(14),
+                     author: nil,
+                     thumbnailData: nil, thumbnailImageName: "UserBlogPlaceholderImage3"),
+        BlogFeedItem(id: "4",
+                     title: "Endgame Studies I Recommend",
+                     url: nil,
+                     publishedDate: daysAgo(21),
+                     author: nil,
+                     thumbnailData: nil,
+                     thumbnailImageName: "UserBlogPlaceholderImage4"),
+    ]
+
+    private static func daysAgo(_ days: Int) -> Date? {
+        Calendar.current.date(byAdding: .day, value: -days, to: .now)
+    }
+}

ios/LichessWidgets/Blog Feed Widget/CommunityBlogWidget.swift

@@ -0,0 +1,17 @@
+import SwiftUI
+import WidgetKit
+
+struct CommunityBlogWidget: Widget {
+    let kind = "CommunityBlogWidget"
+
+    var body: some WidgetConfiguration {
+        StaticConfiguration(kind: kind,
+                            provider: GenericBlogFeedProvider(feed: .communityBlog)) { entry in
+            BlogFeedWidgetEntryView(entry: entry)
+                .containerBackground(.background, for: .widget)
+        }
+        .configurationDisplayName("Community Blog")
+        .description("Latest posts from the Lichess community blog.")
+        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
+    }
+}

ios/LichessWidgets/Blog Feed Widget/GenericBlogFeedProvider.swift

@@ -0,0 +1,30 @@
+import SwiftUI
+import WidgetKit
+
+struct GenericBlogFeedProvider: TimelineProvider {
+    let feed: BlogFeedChoice
+    private let fetcher = BlogFeedFetcher()
+
+    func placeholder(in context: Context) -> BlogFeedEntry {
+        BlogFeedPlaceholder.entry(feed: feed, family: context.family)
+    }
+
+    func getSnapshot(in context: Context, completion: @escaping (BlogFeedEntry) -> Void) {
+        if context.isPreview { completion(placeholder(in: context)); return }
+        Task {
+            completion(await fetcher.fetchEntry(feed: feed,
+                                                username: nil,
+                                                family: context.family))
+        }
+    }
+
+    func getTimeline(in context: Context, completion: @escaping (Timeline<BlogFeedEntry>) -> Void) {
+        Task {
+            let entry = await fetcher.fetchEntry(feed: feed,
+                                                 username: nil,
+                                                 family: context.family)
+            let nextUpdate = BlogFeedFetcher.nextUpdateDate
+            completion(Timeline(entries: [entry], policy: .after(nextUpdate)))
+        }
+    }
+}

ios/LichessWidgets/Blog Feed Widget/Model/BlogFeedChoice.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+enum BlogFeedChoice: String {
+    case officialBlog
+    case communityBlog
+    case userBlog
+
+    var displayName: String {
+        switch self {
+        case .officialBlog: return "Official Blog"
+        case .communityBlog: return "Community Blog"
+        case .userBlog: return "User Blog"
+        }
+    }
+
+    func feedURL(username: String?) -> String? {
+        switch self {
+        case .officialBlog: return "https://lichess.org/@/Lichess/blog.atom"
+        case .communityBlog: return "https://lichess.org/blog/community.atom"
+        case .userBlog:
+            guard let username, !username.isEmpty else { return nil }
+            return "https://lichess.org/@/\(username)/blog.atom"
+        }
+    }
+}

ios/LichessWidgets/Blog Feed Widget/Model/BlogFeedEntry.swift

@@ -0,0 +1,17 @@
+import WidgetKit
+
+struct BlogFeedEntry: TimelineEntry {
+    let date: Date
+    let feed: BlogFeedChoice
+    let username: String?
+    let items: [BlogFeedItem]
+    let error: String?
+
+    /// Display name for the widget header.
+    var headerTitle: String {
+        if feed == .userBlog, let username, !username.isEmpty {
+            return "@\(username)"
+        }
+        return feed.displayName
+    }
+}

ios/LichessWidgets/Blog Feed Widget/Model/BlogFeedItem.swift

@@ -0,0 +1,12 @@
+import Foundation
+
+struct BlogFeedItem: Identifiable {
+    let id: String
+    let title: String
+    let url: String?
+    let publishedDate: Date?
+    let author: String?
+    let thumbnailData: Data?
+    /// Asset catalog image name, used for static placeholder items only.
+    let thumbnailImageName: String?
+}

ios/LichessWidgets/Blog Feed Widget/Model/BlogThumbnailSpec.swift

@@ -0,0 +1,7 @@
+import Foundation
+
+struct BlogThumbnailSpec {
+    let width: CGFloat
+    let aspectRatio: CGFloat // height = width * aspectRatio
+    var height: CGFloat { width * aspectRatio }
+}

ios/LichessWidgets/Blog Feed Widget/OfficialBlogWidget.swift

@@ -0,0 +1,17 @@
+import SwiftUI
+import WidgetKit
+
+struct OfficialBlogWidget: Widget {
+    let kind = "OfficialBlogWidget"
+
+    var body: some WidgetConfiguration {
+        StaticConfiguration(kind: kind,
+                            provider: GenericBlogFeedProvider(feed: .officialBlog)) { entry in
+            BlogFeedWidgetEntryView(entry: entry)
+                .containerBackground(.background, for: .widget)
+        }
+        .configurationDisplayName("Official Blog")
+        .description("Latest posts from the Lichess official blog.")
+        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
+    }
+}

ios/LichessWidgets/Blog Feed Widget/UserBlogFeedProvider.swift

@@ -0,0 +1,24 @@
+import WidgetKit
+
+struct UserBlogFeedProvider: AppIntentTimelineProvider {
+    private let fetcher = BlogFeedFetcher()
+
+    func placeholder(in context: Context) -> BlogFeedEntry {
+        BlogFeedPlaceholder.entry(feed: .userBlog, username: "ChessNoob2009", family: context.family)
+    }
+
+    func snapshot(for configuration: UserBlogFeedIntent, in context: Context) async -> BlogFeedEntry {
+        if context.isPreview { return placeholder(in: context) }
+        return await fetcher.fetchEntry(feed: .userBlog,
+                                        username: configuration.username,
+                                        family: context.family)
+    }
+
+    func timeline(for configuration: UserBlogFeedIntent, in context: Context) async -> Timeline<BlogFeedEntry> {
+        let entry = await fetcher.fetchEntry(feed: .userBlog,
+                                             username: configuration.username,
+                                             family: context.family)
+        let nextUpdate = BlogFeedFetcher.nextUpdateDate
+        return Timeline(entries: [entry], policy: .after(nextUpdate))
+    }
+}