web_update_guard library

Keeps Flutter web users off stale cached builds.

Stamp the build with dart run web_update_guard stamp build/web, then run a WebUpdateGuard in the app and show an UpdateBanner or wrap the app in a WebUpdateListener. On non-web platforms everything is a no-op that reports UpdateState.unsupported.

Classes

ApplyUpdateOptions: What WebUpdateGuard.applyUpdate purges before reloading.
BuildInfo: Metadata about one deployed build, as written to version.json by the stamp CLI.
UpdateBanner: An inline banner that appears above child while a new build is available.
UpdateChecker: Anything that can report and apply web updates.
UpdateGuardPlatform: The browser operations WebUpdateGuard needs, behind an interface so the guard's logic can be unit-tested on the VM with a fake implementation.
UpdateStatus: An immutable snapshot of what an UpdateChecker knows.
WebUpdateGuard: Detects that a newer Flutter web build has been deployed and moves the tab onto it.
WebUpdateListener: Listens to an UpdateChecker and announces each newly deployed build via the nearest ScaffoldMessenger.

buildIdMetaName → const String: The name of the <meta> tag the stamp CLI injects into index.html.
cacheBustParam → const String: The query parameter the stamp CLI appends to cache-busted script URLs.
versionFetchNonceParam → const String: The query parameter WebUpdateGuard appends to version.json requests so that no intermediate cache can answer them.

buildTimeFromId(String buildId) → DateTime?: Extracts the UTC build time embedded in a build ID made by formatBuildId, or null when buildId has another format.
cacheBustedUrl(String url, Object nonce) → String: Returns url with a unique nonce query parameter (versionFetchNonceParam) added, preserving any existing parameters and fragment. Works for relative and absolute URLs.
formatBuildId(String contentHash, DateTime builtAt) → String: Formats a build ID from a hex contentHash and the build time.
isStampedBuildId(String buildId) → bool: Returns true when buildId has the format produced by formatBuildId.
isUpdateAvailable({required String? runningBuildId, required BuildInfo remote, ComparisonPolicy policy = ComparisonPolicy.anyDifference}) → bool: Decides whether remote should be treated as an update for a tab that is running runningBuildId.

UpdateAvailableCallback = void Function(BuildContext context, UpdateStatus status): Called by WebUpdateListener once per newly detected build.
UpdateBannerBuilder = Widget Function(BuildContext context, UpdateStatus status, VoidCallback onReload, VoidCallback onDismiss): Builds the widget UpdateBanner shows while an update is available.
UpdateMaterialBannerBuilder = MaterialBanner Function(BuildContext context, UpdateStatus status, VoidCallback onReload, VoidCallback onDismiss): Builds the MaterialBanner shown by WebUpdateListener.
UpdateSnackBarBuilder = SnackBar Function(BuildContext context, UpdateStatus status, VoidCallback onReload): Builds the SnackBar shown by WebUpdateListener.