Merge branch 'main' into fix-sac-by-tank-role

Author: mgoodness

docs/superpowers/plans/2026-04-28-media-source-extension-phase3a.md

@@ -0,0 +1,91 @@
+# Submersion Manifest — JSON v1
+
+A small JSON-shaped feed format that Submersion can subscribe to. Pair with
+the dive-photo workflow: paste the manifest URL into the photo picker's URL
+tab → Manifest mode, optionally subscribe, and Submersion will keep your
+dive photos in sync as the feed grows.
+
+## Top-level shape
+
+```json
+{
+  "version": 1,
+  "title": "Eric's Dive Photos",
+  "items": [ /* 0 or more entries */ ]
+}
+```
+
+Required: `version` (must be `1`) and `items` (array; may be empty).
+Optional: `title` (string).
+
+Unknown top-level fields are ignored — readers should be tolerant.
+
+## Item shape
+
+```json
+{
+  "id": "dive-2024-04-12-img-001",
+  "url": "https://photos.example.com/dive-001.jpg",
+  "thumbnailUrl": "https://photos.example.com/dive-001-thumb.jpg",
+  "takenAt": "2024-04-12T14:32:00Z",
+  "caption": "Yellowtail at the swim-through",
+  "mediaType": "photo",
+  "lat": 25.123,
+  "lon": -80.456,
+  "width": 4032,
+  "height": 3024,
+  "durationSeconds": null
+}
+```
+
+### Required item fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `url` | string | Direct URL to media bytes. HTTP(S) only. |
+
+### Optional item fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | string | Stable identifier. If omitted, Submersion derives `SHA-256(url + takenAt ?? '')` truncated to 32 hex chars. |
+| `takenAt` | RFC 3339 timestamp | If no offset is given, interpreted as UTC. |
+| `caption` | string | Free-form. Stored as `MediaItem.caption`. |
+| `thumbnailUrl` | string | Used for fast list previews. |
+| `mediaType` | `"photo"` or `"video"` | Hint; readers may still re-derive from `Content-Type`. |
+| `lat` | number | Decimal degrees. |
+| `lon` | number | Decimal degrees. |
+| `width` | integer | Pixels. |
+| `height` | integer | Pixels. |
+| `durationSeconds` | integer | For videos. |
+
+Unknown item fields are ignored.
+
+## Stable identity rules
+
+The `(subscriptionId, id)` pair is the stable key Submersion uses to detect
+new vs. removed vs. changed entries on subsequent polls. **Never reuse an
+`id` for a different photo**, and don't let it change across polls — both
+will produce duplicate or orphaned rows.
+
+## Polling expectations
+
+Submersion polls subscriptions at most once per `pollIntervalSeconds / 4`
+(or once per hour, whichever is smaller). Servers should support
+conditional GET (`ETag` and/or `Last-Modified`) to keep traffic minimal.
+
+## Minimum viable example
+
+```json
+{
+  "version": 1,
+  "items": [
+    { "url": "https://example.com/a.jpg" },
+    { "url": "https://example.com/b.jpg" }
+  ]
+}
+```
+
+This is valid: each entry will receive a SHA-derived `id`, and the
+`takenAt` fields will be filled in from EXIF after the eager fetch pipeline
+runs.

docs/superpowers/plans/2026-04-28-media-source-extension-phase3b.md

@@ -89,6 +89,7 @@ import 'package:submersion/features/settings/presentation/pages/insurance_edit_p
 import 'package:submersion/features/settings/presentation/pages/notes_edit_page.dart';
 import 'package:submersion/features/settings/presentation/pages/debug_log_viewer_page.dart';
 import 'package:submersion/features/media/presentation/pages/media_sources_page.dart';
+import 'package:submersion/features/media/presentation/pages/network_sources_page.dart';
 import 'package:submersion/features/settings/presentation/pages/section_appearance_page.dart';
 import 'package:submersion/features/transfer/presentation/pages/transfer_page.dart';
 import 'package:submersion/features/dive_types/presentation/pages/dive_types_page.dart';
@@ -859,6 +860,13 @@ final appRouterProvider = Provider<GoRouter>((ref) {
                 path: 'media-sources',
                 name: 'mediaSources',
                 builder: (context, state) => const MediaSourcesPage(),
+                routes: [
+                  GoRoute(
+                    path: 'network-sources',
+                    name: 'networkSources',
+                    builder: (context, state) => const NetworkSourcesPage(),
+                  ),
+                ],
               ),
               GoRoute(
                 path: 'diver-profile',

docs/superpowers/plans/2026-04-28-media-source-extension-phase3c.md

@@ -0,0 +1,66 @@
+/// Wall-clock-UTC date utilities.
+///
+/// Submersion treats dive-computer-style timestamps as wall-clock-UTC: the
+/// digits the user sees on their dive computer face are stored verbatim as
+/// the components of a `DateTime.utc(...)`. This file centralizes the two
+/// flavors of "convert an external timestamp into wall-clock-UTC" used
+/// throughout the media import pipeline:
+///
+/// * [parseExternalDateAsWallClockUtc] — parse an ISO-8601-ish string,
+///   honoring an explicit zone designator if present and otherwise
+///   reinterpreting offset-less wall-clock components as UTC.
+/// * [asWallClockUtc] — reinterpret a local `DateTime`'s components as
+///   UTC verbatim, used for filesystem mtimes that arrive in local time
+///   but should match wall-clock-UTC dive times.
+library;
+
+/// Matches a trailing `Z` or `+hh:mm` / `-hh:mm` / `+hhmm` / `-hhmm` offset
+/// on an ISO-8601 timestamp. Used to detect "no offset given" so we can
+/// reinterpret as UTC rather than shifting from local time.
+final RegExp _isoOffset = RegExp(r'(Z|[+\-]\d{2}:?\d{2})$');
+
+/// Parses an ISO-8601-ish date string and returns it as a UTC `DateTime`,
+/// applying the codebase's wall-clock-as-UTC convention.
+///
+/// If [raw] carries a timezone designator (Z or ±HH:MM / ±HHMM), the
+/// returned DateTime represents the same absolute moment in UTC
+/// (`DateTime.parse(raw).toUtc()`).
+///
+/// If [raw] lacks a timezone designator, the wall-clock components are
+/// REINTERPRETED as UTC — i.e. `"2024-04-12T14:32:00"` returns
+/// `DateTime.utc(2024, 4, 12, 14, 32, 0)`. This matches how dive
+/// computers store time (no timezone metadata; the digits ARE the dive's
+/// wall clock) and how Submersion persists `takenAt` for matching.
+///
+/// Returns null when the string is unparseable.
+DateTime? parseExternalDateAsWallClockUtc(String raw) {
+  final parsed = DateTime.tryParse(raw);
+  if (parsed == null) return null;
+  if (parsed.isUtc) return parsed;
+  if (_isoOffset.hasMatch(raw)) return parsed.toUtc();
+  return DateTime.utc(
+    parsed.year,
+    parsed.month,
+    parsed.day,
+    parsed.hour,
+    parsed.minute,
+    parsed.second,
+    parsed.millisecond,
+  );
+}
+
+/// Reinterprets a local `DateTime`'s wall-clock components as UTC.
+///
+/// Used for filesystem mtimes (`File.lastModifiedSync()` returns local)
+/// when we want to treat the digits as wall-clock-UTC for matching.
+/// Example: an mtime of `2024-04-12 14:32 EDT` becomes
+/// `DateTime.utc(2024, 4, 12, 14, 32, 0)` — NOT shifted by the offset.
+DateTime asWallClockUtc(DateTime local) => DateTime.utc(
+  local.year,
+  local.month,
+  local.day,
+  local.hour,
+  local.minute,
+  local.second,
+  local.millisecond,
+);

docs/superpowers/specs/manifest_json_v1.md

@@ -0,0 +1,63 @@
+// Adapted from plan
+// `docs/superpowers/plans/2026-04-28-media-source-extension-phase3a.md`
+// Task 16. Constants for the network media cache caps surfaced as
+// `cached_network_image` (memory) + `flutter_cache_manager` (disk) limits.
+//
+// Phase 3c will surface these as user-editable Settings; for Phase 3a
+// they live as `const`s here and are applied at app boot via
+// [applyMediaCacheCaps].
+//
+// Deviations from the plan:
+//
+// - The plan asks for "500 MB disk + 75 MB memory caps" configured via
+//   `DefaultCacheManager`-style configuration. `flutter_cache_manager`
+//   3.4.1 only exposes `maxNrOfCacheObjects` (object count) on its `Config`
+//   class — there is no public API to express a byte-size cap on the disk
+//   cache, and `DefaultCacheManager` is a singleton constructed with the
+//   default `Config` we cannot mutate after the fact. The byte cap is
+//   therefore declared as a constant for now and not wired to disk in 3a;
+//   Phase 3c is expected to introduce a custom `BaseCacheManager` subclass
+//   passed via `CachedNetworkImage(cacheManager: ...)` that honours the
+//   byte budget directly. See `kDiskCacheCapBytes` doc comment.
+// - Memory cap is wired today via [PaintingBinding.instance.imageCache]
+//   because `cached_network_image` resolves through the global Flutter
+//   image cache, so the byte cap is honoured immediately for in-RAM
+//   decoded images.
+
+import 'package:flutter/painting.dart';
+
+/// Target on-disk LRU budget for cached remote media (500 MB).
+///
+/// Phase 3a: declarative only. `flutter_cache_manager` 3.4.1 only exposes
+/// an object-count cap (`maxNrOfCacheObjects`); a real byte budget needs
+/// a custom `BaseCacheManager` subclass which Phase 3c will introduce
+/// alongside the Settings UI for adjusting these caps.
+const int kDiskCacheCapBytes = 500 * 1024 * 1024;
+
+/// Live in-memory decoded-image budget (75 MB), applied to
+/// [PaintingBinding.imageCache] at app boot via [applyMediaCacheCaps].
+const int kMemoryCacheCapBytes = 75 * 1024 * 1024;
+
+/// Heuristic upper bound on the number of decoded images held in memory
+/// at once. The Flutter image cache enforces both this object count
+/// *and* [kMemoryCacheCapBytes]; the count guard exists so a stream of
+/// tiny thumbnails cannot blow past expectations even though each frame
+/// is well under the byte cap.
+const int kMemoryCacheCapObjects = 200;
+
+/// Applies [kMemoryCacheCapBytes] / [kMemoryCacheCapObjects] to the
+/// global Flutter [PaintingBinding.imageCache] at app boot.
+///
+/// Disk-side caps ([kDiskCacheCapBytes]) are *not* wired here — see the
+/// constant's doc comment. Idempotent; safe to call multiple times.
+//
+// Configures global Flutter image cache; exercised at app boot by
+// `MediaSourcesApp.bootstrap()` in Phase 3c.
+// coverage:ignore-start
+void applyMediaCacheCaps() {
+  final cache = PaintingBinding.instance.imageCache;
+  cache.maximumSizeBytes = kMemoryCacheCapBytes;
+  cache.maximumSize = kMemoryCacheCapObjects;
+}
+
+// coverage:ignore-end