Merge branch 'main' into fix-sac-date-format

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

@@ -753,6 +753,21 @@ class DiveRepository {
   Future<void> updateDive(domain.Dive dive) async {
     try {
       _log.info('Updating dive: ${dive.id}');
+
+      // Validate that all tanks have non-empty IDs on update to prevent data loss
+      // (If a tank ID is empty, it would generate a new UUID and cause the old tank to be deleted)
+      final emptyTankIndices = dive.tanks
+          .asMap()
+          .entries
+          .where((e) => e.value.id.isEmpty)
+          .map((e) => e.key);
+      if (emptyTankIndices.isNotEmpty) {
+        throw ArgumentError(
+          'Cannot update dive: tank(s) at index(es) ${emptyTankIndices.join(', ')} '
+          'have empty IDs. All tanks must have valid IDs when updating a dive.',
+        );
+      }
+
       final now = DateTime.now().millisecondsSinceEpoch;
 
       await (_db.update(_db.dives)..where((t) => t.id.equals(dive.id))).write(
@@ -848,44 +863,90 @@ class DiveRepository {
         localUpdatedAt: now,
       );
 
-      // Update tanks: delete and re-insert
-      final existingTanks = await (_db.select(
+      // Update tanks:
+      // Try to match existing tanks by ID to do updates instead of delete+insert when possible,
+      // to preserve sync records and avoid unnecessary deletions/insertions in the sync engine.
+      // Delete tanks that are no longer present.
+      // This is more complex but should result in better sync behavior and performance when tanks
+      // are edited but not completely changed (which is more likely).
+
+      // Get existing tank IDs for this dive
+      final existingTankRows = await (_db.select(
         _db.diveTanks,
       )..where((t) => t.diveId.equals(dive.id))).get();
-      await (_db.delete(
-        _db.diveTanks,
-      )..where((t) => t.diveId.equals(dive.id))).go();
-      for (final tank in existingTanks) {
-        await _syncRepository.logDeletion(
-          entityType: 'diveTanks',
-          recordId: tank.id,
-        );
-      }
+      final existingTankIds = existingTankRows.map((t) => t.id).toSet();
+      final updatedTankIds = <String>{};
+
+      // Update or insert tanks
       for (final tank in dive.tanks) {
-        final tankId = tank.id.isNotEmpty ? tank.id : _uuid.v4();
-        await _db
-            .into(_db.diveTanks)
-            .insert(
-              DiveTanksCompanion(
-                id: Value(tankId),
-                diveId: Value(dive.id),
-                volume: Value(tank.volume),
-                workingPressure: Value(tank.workingPressure),
-                startPressure: Value(tank.startPressure),
-                endPressure: Value(tank.endPressure),
-                o2Percent: Value(tank.gasMix.o2),
-                hePercent: Value(tank.gasMix.he),
-                tankOrder: Value(tank.order),
-                tankRole: Value(tank.role.name),
-                tankMaterial: Value(tank.material?.name),
-                tankName: Value(tank.name),
-                presetName: Value(tank.presetName),
-              ),
-            );
-        await _syncRepository.markRecordPending(
+        // Tank ID is guaranteed to be non-empty by validation at start of method
+        final tankId = tank.id;
+        updatedTankIds.add(tankId);
+
+        if (existingTankIds.contains(tankId)) {
+          // Update existing tank
+          await (_db.update(
+            _db.diveTanks,
+          )..where((t) => t.id.equals(tankId))).write(
+            DiveTanksCompanion(
+              volume: Value(tank.volume),
+              workingPressure: Value(tank.workingPressure),
+              startPressure: Value(tank.startPressure),
+              endPressure: Value(tank.endPressure),
+              o2Percent: Value(tank.gasMix.o2),
+              hePercent: Value(tank.gasMix.he),
+              tankOrder: Value(tank.order),
+              tankRole: Value(tank.role.name),
+              tankMaterial: Value(tank.material?.name),
+              tankName: Value(tank.name),
+              presetName: Value(tank.presetName),
+            ),
+          );
+          // Log as pending update (assuming sync handles updates)
+          await _syncRepository.markRecordPending(
+            entityType: 'diveTanks',
+            recordId: tankId,
+            localUpdatedAt: now,
+          );
+        } else {
+          // Insert new tank
+          await _db
+              .into(_db.diveTanks)
+              .insert(
+                DiveTanksCompanion(
+                  id: Value(tankId),
+                  diveId: Value(dive.id),
+                  volume: Value(tank.volume),
+                  workingPressure: Value(tank.workingPressure),
+                  startPressure: Value(tank.startPressure),
+                  endPressure: Value(tank.endPressure),
+                  o2Percent: Value(tank.gasMix.o2),
+                  hePercent: Value(tank.gasMix.he),
+                  tankOrder: Value(tank.order),
+                  tankRole: Value(tank.role.name),
+                  tankMaterial: Value(tank.material?.name),
+                  tankName: Value(tank.name),
+                  presetName: Value(tank.presetName),
+                ),
+              );
+          await _syncRepository.markRecordPending(
+            entityType: 'diveTanks',
+            recordId: tankId,
+            localUpdatedAt: now,
+          );
+        }
+      }
+
+      // Delete tanks that are no longer present
+      // This will cascade to both tank_pressure_profiles and gas_switches for removed tanks
+      final tanksToDelete = existingTankIds.difference(updatedTankIds);
+      for (final tankId in tanksToDelete) {
+        await (_db.delete(
+          _db.diveTanks,
+        )..where((t) => t.id.equals(tankId))).go();
+        await _syncRepository.logDeletion(
           entityType: 'diveTanks',
           recordId: tankId,
-          localUpdatedAt: now,
         );
       }
 
@@ -2446,9 +2507,9 @@ class DiveRepository {
           : null,
       tanks: tankRows.map((t) {
         // Derive start/end pressure from profile data when available.
-        // Profile time-series from AI transmitters is the authoritative
-        // source, preferred over stored values (which may be stale or
-        // defaulted from a tank preset's working pressure).
+        // Profile time-series from AI transmitters is the fallback
+        // source, if values entered by the user are not available in the
+        // dive tanks table.
         final profilePoints = tankPressuresByTankId[t.id];
         final profileStartPressure =
             profilePoints != null && profilePoints.isNotEmpty
@@ -2464,8 +2525,8 @@ class DiveRepository {
           name: t.tankName,
           volume: t.volume,
           workingPressure: t.workingPressure,
-          startPressure: profileStartPressure ?? t.startPressure,
-          endPressure: profileEndPressure ?? t.endPressure,
+          startPressure: t.startPressure ?? profileStartPressure,
+          endPressure: t.endPressure ?? profileEndPressure,
           gasMix: domain.GasMix(o2: t.o2Percent, he: t.hePercent),
           role: TankRole.values.firstWhere(
             (r) => r.name == t.tankRole,