WidgetBridge/com.vocabloot.widgetbridge

Package-level declarations

WidgetBridge publishes a @Serializable payload plus WidgetAssets as an atomic generation and reads it back as a ResolvedFeed. Platform wiring: androidWidgetBridge / iosWidgetBridge. Helpers: WidgetImages and AssetBudget for images, WidgetRotation for hourly rotation shared with the Swift package. The Swift reader lives in Sources/WidgetBridge.

Types

AndroidWidgetFeedStorage

class AndroidWidgetFeedStorage(root: File) : WidgetFeedStorage

Generation folders under root; every promote and pointer write is an atomic rename.

AppWidgetRefreshNotifier

class AppWidgetRefreshNotifier(context: ERROR CLASS: Symbol not found for Context, receiverClass: Class<*>) : WidgetRefreshNotifier

Broadcasts ACTION_APPWIDGET_UPDATE to receiverClass for every placed widget. No Glance dependency.

AssetBudget

class AssetBudget(budgetBytes: Long = 8L * 1024 * 1024, maxDimension: Int = 512, maxBytes: Int = 2 * 1024 * 1024, encoder: (candidate: AssetCandidate, maxDimension: Int, maxBytes: Int) -> EncodedImage? = { c, dim, bytes -> WidgetImages.encode(c.sourcePath, c.format, dim, bytes) })

Greedy packer: encodes AssetCandidates in order until budgetBytes is spent; failures are skipped.

AssetCandidate

class AssetCandidate(val fileName: String, val sourcePath: String, val format: WidgetImageFormat)

EncodedImage

class EncodedImage(val bytes: ByteArray, val extension: String)

IosWidgetFeedStorage

class IosWidgetFeedStorage : WidgetFeedStorage

Generation folders inside the App Group container so the widget extension can read them.

NotificationCenterRefreshNotifier

class NotificationCenterRefreshNotifier : WidgetRefreshNotifier

PublishResult

sealed interface PublishResult

ResolvedFeed

class ResolvedFeed<T>

The generation a reader resolved: current, or the newest readable fallback.

WidgetAsset

class WidgetAsset(val fileName: String, val bytes: ByteArray)

An image (or any file) shipped inside a generation under assets/. fileName must satisfy isSafeName.

WidgetBridge

class WidgetBridge<T>(config: WidgetBridgeConfig, serializer: KSerializer<T>, storage: WidgetFeedStorage, notifier: WidgetRefreshNotifier, clock: () -> Long = { Clock.System.now().toEpochMilliseconds() })

Publishes a typed payload plus assets as an atomic generation and reads it back. Construct through androidWidgetBridge / iosWidgetBridge, or directly with a custom storage.

WidgetBridgeConfig

data class WidgetBridgeConfig(val schemaVersion: Int, val directoryName: String = "widgetbridge", val iosAppGroup: String? = null, val keepPrevious: Int = 1)

WidgetFeedStorage

interface WidgetFeedStorage

Platform filesystem operations for the generation-versioned export. Implement it yourself for a custom location; the defaults are AndroidWidgetFeedStorage and IosWidgetFeedStorage.

WidgetGeneration

class WidgetGeneration(val id: String, val directoryPath: String, val feedBytes: ByteArray)

One exported generation as found on disk.

WidgetImageFormat

enum WidgetImageFormat : Enum<WidgetImageFormat>

WidgetImages

actual object WidgetImages

expect object WidgetImages

Downsamples an image file for a widget. PNG keeps transparency (cutouts); JPEG for photos.

actual object WidgetImages

WidgetRefreshNotifier

fun interface WidgetRefreshNotifier

Tells the OS that a new generation is current so widgets redraw. Platform defaults exist; None for tests.

WidgetRotation

object WidgetRotation

Deterministic hourly rotation shared by Kotlin and Swift readers so both platforms show the same item.

Properties

WIDGET_BRIDGE_FEED_CHANGED

const val WIDGET_BRIDGE_FEED_CHANGED: String

Name observed by the Swift package's WidgetBridgeReloader, which calls WidgetCenter.reloadAllTimelines().

Functions

androidWidgetBridge

fun <T> androidWidgetBridge(context: ERROR CLASS: Symbol not found for Context, config: WidgetBridgeConfig, serializer: KSerializer<T>, receiverClass: Class<*>): WidgetBridge<T>

Default Android wiring: files-dir storage plus an app-widget update broadcast to receiverClass.

iosWidgetBridge

fun <T> iosWidgetBridge(config: WidgetBridgeConfig, serializer: KSerializer<T>): WidgetBridge<T>

Default iOS wiring: App Group storage plus a NotificationCenter post. Requires WidgetBridgeConfig.iosAppGroup.

isSafeName

fun isSafeName(value: String): Boolean

Letters, digits, -, _, .; never blank. Rejects path separators and traversal by construction.