[desktop] Preserve Gift Card artwork and receiving state

Author: piatoss3612

lib/src/features/payment_links/models/vizor_payment_link.dart

@@ -9,6 +9,7 @@ class VizorPaymentLink {
     required this.birthdayHeight,
     required this.label,
     required this.createdAt,
+    this.artworkId,
   });
 
   static const scheme = 'vizor';
@@ -23,6 +24,7 @@ class VizorPaymentLink {
   final int birthdayHeight;
   final String label;
   final DateTime createdAt;
+  final String? artworkId;
 
   String encode() {
     final payload = <String, Object?>{
@@ -35,6 +37,10 @@ class VizorPaymentLink {
       'label': label.trim(),
       'createdAt': createdAt.toUtc().toIso8601String(),
     };
+    final normalizedArtworkId = artworkId?.trim();
+    if (normalizedArtworkId != null && normalizedArtworkId.isNotEmpty) {
+      payload['artworkId'] = normalizedArtworkId;
+    }
     final encoded = base64UrlEncode(utf8.encode(jsonEncode(payload)));
     return Uri(
       scheme: scheme,
@@ -83,6 +89,7 @@ class VizorPaymentLink {
     final label = _readString(payload, 'label');
     final createdAtRaw = _readString(payload, 'createdAt');
     final createdAt = DateTime.tryParse(createdAtRaw);
+    final artworkId = _readOptionalString(payload, 'artworkId');
 
     if (network.isEmpty) {
       throw const FormatException('Payment link network is missing.');
@@ -102,6 +109,10 @@ class VizorPaymentLink {
     if (createdAt == null) {
       throw const FormatException('Payment link timestamp is invalid.');
     }
+    if (artworkId != null &&
+        !RegExp(r'^[a-zA-Z0-9_-]{1,64}$').hasMatch(artworkId)) {
+      throw const FormatException('Payment link artwork is invalid.');
+    }
 
     return VizorPaymentLink(
       network: network,
@@ -111,6 +122,7 @@ class VizorPaymentLink {
       birthdayHeight: birthdayHeight,
       label: label,
       createdAt: createdAt,
+      artworkId: artworkId,
     );
   }
 
@@ -122,6 +134,16 @@ class VizorPaymentLink {
     return value.trim();
   }
 
+  static String? _readOptionalString(Map<String, Object?> payload, String key) {
+    final value = payload[key];
+    if (value == null) return null;
+    if (value is! String) {
+      throw FormatException('Payment link "$key" is invalid.');
+    }
+    final trimmed = value.trim();
+    return trimmed.isEmpty ? null : trimmed;
+  }
+
   static int _readInt(Map<String, Object?> payload, String key) {
     final value = payload[key];
     if (value is int) return value;

lib/src/features/payment_links/screens/payment_links_desktop_screen.dart

@@ -43,8 +43,8 @@ enum _PaymentLinksLocalPage {
 ///
 /// The presentation remains local to this screen, while all secret creation,
 /// recovery persistence, sync, and transaction work stays behind
-/// [PaymentLinkOperations]. Artwork and message are not protocol fields in the
-/// current v1 link, so received links intentionally render a generic card.
+/// [PaymentLinkOperations]. Artwork is an optional, backward-compatible v1
+/// field. The message remains local to the sender in the current protocol.
 class PaymentLinksDesktopScreen extends ConsumerStatefulWidget {
   const PaymentLinksDesktopScreen({super.key});
 
@@ -91,6 +91,7 @@ class _PaymentLinksDesktopScreenState
       PaymentLinkRedeemVisualState.paste;
   PaymentLinkCardsTab _activeCardsTab = PaymentLinkCardsTab.created;
   List<PaymentLinkRecoveryRecord> _recoveries = const [];
+  List<_ReceivedPaymentLinkRecord> _receivedCards = const [];
   VizorPaymentLink? _readyLink;
   VizorPaymentLink? _receivedLink;
   PaymentLinkRecoveryRecord? _reclaimCandidate;
@@ -169,6 +170,7 @@ class _PaymentLinksDesktopScreenState
     if (link == null || !mounted) return;
     setState(() {
       _receivedLink = link;
+      _rememberReceivedLink(link);
       _redeemState = PaymentLinkRedeemVisualState.paste;
       _page = _PaymentLinksLocalPage.received;
       _showHelp = false;
@@ -191,6 +193,45 @@ class _PaymentLinksDesktopScreenState
     }
   }
 
+  void _rememberReceivedLink(VizorPaymentLink link) {
+    final existingIndex = _receivedCards.indexWhere(
+      (record) => record.address == link.address,
+    );
+    final existing = existingIndex < 0 ? null : _receivedCards[existingIndex];
+    final status = existing?.status ?? _ReceivedPaymentLinkStatus.readyToClaim;
+    final updated = _ReceivedPaymentLinkRecord.fromLink(
+      link,
+      status: status,
+      retainClaimLink: status != _ReceivedPaymentLinkStatus.received,
+    );
+    final records = List<_ReceivedPaymentLinkRecord>.of(_receivedCards);
+    if (existingIndex >= 0) records.removeAt(existingIndex);
+    _receivedCards = [updated, ...records];
+  }
+
+  void _setReceivedCardStatus(
+    String address,
+    _ReceivedPaymentLinkStatus status, {
+    bool clearClaimLink = false,
+  }) {
+    _receivedCards = [
+      for (final record in _receivedCards)
+        if (record.address == address)
+          record.withStatus(status, clearClaimLink: clearClaimLink)
+        else
+          record,
+    ];
+  }
+
+  void _openReceivedCard(_ReceivedPaymentLinkRecord record) {
+    final link = record.claimLink;
+    if (link == null || _operationInProgress) return;
+    setState(() {
+      _receivedLink = link;
+      _page = _PaymentLinksLocalPage.received;
+    });
+  }
+
   bool get _hasPositiveAmount {
     final amount = parseZecAmount(_amountController.text);
     return amount != null && amount > BigInt.zero;
@@ -278,6 +319,7 @@ class _PaymentLinksDesktopScreenState
         _keystoneFundingRequest = _PaymentLinkKeystoneFundingRequest(
           amountZatoshi: amount,
           sourceAccountUuid: sourceAccountUuid,
+          artworkId: _selectedArtwork.protocolId,
         );
       });
       return;
@@ -290,6 +332,7 @@ class _PaymentLinksDesktopScreenState
           .createFundedLink(
             amountZatoshi: amount,
             sourceAccountUuid: sourceAccountUuid,
+            artworkId: _selectedArtwork.protocolId,
           );
       await _loadRecoveries(showError: false);
       if (!mounted) return;
@@ -386,6 +429,7 @@ class _PaymentLinksDesktopScreenState
       if (link == null || !mounted) return;
       setState(() {
         _receivedLink = link;
+        _rememberReceivedLink(link);
         _redeemState = PaymentLinkRedeemVisualState.paste;
         _page = _PaymentLinksLocalPage.received;
       });
@@ -409,17 +453,36 @@ class _PaymentLinksDesktopScreenState
   Future<void> _claimReceivedLink() async {
     final link = _receivedLink;
     if (link == null || _operationInProgress) return;
-    setState(() => _operationInProgress = true);
+    setState(() {
+      _operationInProgress = true;
+      _receivedLink = null;
+      _setReceivedCardStatus(
+        link.address,
+        _ReceivedPaymentLinkStatus.receiving,
+      );
+      _activeCardsTab = PaymentLinkCardsTab.received;
+      _page = _PaymentLinksLocalPage.home;
+      _showHelp = false;
+    });
     try {
       await ref.read(paymentLinkOperationsProvider).claimLink(link);
       if (!mounted) return;
       setState(() {
-        _receivedLink = null;
-        _page = _PaymentLinksLocalPage.home;
+        _setReceivedCardStatus(
+          link.address,
+          _ReceivedPaymentLinkStatus.received,
+          clearClaimLink: true,
+        );
       });
       showAppToast(context, 'Gift claimed');
     } catch (_) {
       if (mounted) {
+        setState(() {
+          _setReceivedCardStatus(
+            link.address,
+            _ReceivedPaymentLinkStatus.readyToClaim,
+          );
+        });
         _showError(
           'Gift Card claim failed. It may still be waiting for confirmation '
           'or may already be spent.',
@@ -489,6 +552,7 @@ class _PaymentLinksDesktopScreenState
                 child: PaymentLinkKeystoneSigningOverlay(
                   amountZatoshi: keystoneRequest.amountZatoshi,
                   sourceAccountUuid: keystoneRequest.sourceAccountUuid,
+                  artworkId: keystoneRequest.artworkId,
                   onCancel: _cancelKeystoneFunding,
                   onFundingBroadcast: _completeKeystoneFunding,
                 ),
@@ -539,7 +603,9 @@ class _PaymentLinksDesktopScreenState
   }
 
   Widget _buildHome() {
-    if (_recoveries.isNotEmpty) return _buildCardsList();
+    if (_recoveries.isNotEmpty || _receivedCards.isNotEmpty) {
+      return _buildCardsList();
+    }
     return PaymentLinksHomeDesktopView(
       illustration: Image.asset(
         'assets/illustrations/payment_links/payment_link_empty_card.png',
@@ -564,6 +630,8 @@ class _PaymentLinksDesktopScreenState
               )
               .map(_buildRecoveryRow)
               .toList()
+        : _receivedCards.isNotEmpty
+        ? _receivedCards.map(_buildReceivedRow).toList()
         : <Widget>[
             Padding(
               padding: const EdgeInsets.symmetric(vertical: AppSpacing.sm),
@@ -615,7 +683,7 @@ class _PaymentLinksDesktopScreenState
     return PaymentLinkCardListRow(
       key: ValueKey('payment_link_recovery_${record.link.address}'),
       thumbnail: Image.asset(
-        PaymentLinkCardArtwork.gift.assetPath,
+        PaymentLinkCardArtwork.fromProtocolId(record.link.artworkId).assetPath,
         fit: BoxFit.cover,
         excludeFromSemantics: true,
       ),
@@ -631,6 +699,30 @@ class _PaymentLinksDesktopScreenState
     );
   }
 
+  Widget _buildReceivedRow(_ReceivedPaymentLinkRecord record) {
+    final statusText = switch (record.status) {
+      _ReceivedPaymentLinkStatus.readyToClaim => 'Claim',
+      _ReceivedPaymentLinkStatus.receiving => 'Receiving',
+      _ReceivedPaymentLinkStatus.received => 'Received',
+    };
+    final canClaim =
+        record.status == _ReceivedPaymentLinkStatus.readyToClaim &&
+        record.claimLink != null &&
+        !_operationInProgress;
+    return PaymentLinkCardListRow(
+      key: ValueKey('payment_link_received_${record.address}'),
+      thumbnail: Image.asset(
+        PaymentLinkCardArtwork.fromProtocolId(record.artworkId).assetPath,
+        fit: BoxFit.cover,
+        excludeFromSemantics: true,
+      ),
+      amountText: '${formatZecAmount(record.amountZatoshi)} ZEC',
+      dateText: _formatCardDate(record.createdAt),
+      statusText: statusText,
+      onAction: canClaim ? () => _openReceivedCard(record) : null,
+    );
+  }
+
   Widget _buildAmount() {
     final maxAmountText = _maxAmountText;
     return PaymentLinkAmountDesktopView(
@@ -730,7 +822,7 @@ class _PaymentLinksDesktopScreenState
     if (link == null) return _buildHome();
     return PaymentLinkReceivedDesktopView(
       card: PaymentLinkGiftCard(
-        artwork: PaymentLinkCardArtwork.gift,
+        artwork: PaymentLinkCardArtwork.fromProtocolId(link.artworkId),
         amountText: formatZecAmount(link.amountZatoshi),
         showCaret: false,
       ),
@@ -804,8 +896,59 @@ class _PaymentLinkKeystoneFundingRequest {
   const _PaymentLinkKeystoneFundingRequest({
     required this.amountZatoshi,
     required this.sourceAccountUuid,
+    required this.artworkId,
   });
 
   final BigInt amountZatoshi;
   final String sourceAccountUuid;
+  final String artworkId;
+}
+
+enum _ReceivedPaymentLinkStatus { readyToClaim, receiving, received }
+
+class _ReceivedPaymentLinkRecord {
+  const _ReceivedPaymentLinkRecord({
+    required this.address,
+    required this.amountZatoshi,
+    required this.createdAt,
+    required this.artworkId,
+    required this.status,
+    required this.claimLink,
+  });
+
+  factory _ReceivedPaymentLinkRecord.fromLink(
+    VizorPaymentLink link, {
+    _ReceivedPaymentLinkStatus status = _ReceivedPaymentLinkStatus.readyToClaim,
+    bool retainClaimLink = true,
+  }) {
+    return _ReceivedPaymentLinkRecord(
+      address: link.address,
+      amountZatoshi: link.amountZatoshi,
+      createdAt: link.createdAt,
+      artworkId: link.artworkId,
+      status: status,
+      claimLink: retainClaimLink ? link : null,
+    );
+  }
+
+  final String address;
+  final BigInt amountZatoshi;
+  final DateTime createdAt;
+  final String? artworkId;
+  final _ReceivedPaymentLinkStatus status;
+  final VizorPaymentLink? claimLink;
+
+  _ReceivedPaymentLinkRecord withStatus(
+    _ReceivedPaymentLinkStatus nextStatus, {
+    bool clearClaimLink = false,
+  }) {
+    return _ReceivedPaymentLinkRecord(
+      address: address,
+      amountZatoshi: amountZatoshi,
+      createdAt: createdAt,
+      artworkId: artworkId,
+      status: nextStatus,
+      claimLink: clearClaimLink ? null : claimLink,
+    );
+  }
 }

lib/src/features/payment_links/services/payment_link_hardware_signing_service.dart

@@ -23,6 +23,7 @@ abstract interface class PaymentLinkHardwareSigningService {
   Future<PaymentLinkHardwarePcztDraft> createFundingPczt({
     required BigInt amountZatoshi,
     required String sourceAccountUuid,
+    String? artworkId,
   });
 
   Future<List<String>> encodeSigningUrParts({
@@ -80,10 +81,12 @@ class RustPaymentLinkHardwareSigningService
   Future<PaymentLinkHardwarePcztDraft> createFundingPczt({
     required BigInt amountZatoshi,
     required String sourceAccountUuid,
+    String? artworkId,
   }) async {
     final link = await _paymentLinkService.createFundingDraft(
       amountZatoshi: amountZatoshi,
       sourceAccountUuid: sourceAccountUuid,
+      artworkId: artworkId,
     );
     final sendFlowId =
         'payment-link-hw-${DateTime.now().microsecondsSinceEpoch}';