From 49474033520d07adfa6fe54966793886ff6933e0 Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Thu, 30 Jul 2026 10:52:58 +0200
Subject: [PATCH 01/14] chore(deps): Add bwip-js for barcode generation

Changes:
- Add @bwip-js/browser ^4.11.2 as a direct dependency

The digital cards rework renders loyalty barcodes and QR codes in the browser,
and nothing in the tree could generate them: barcode-detector only reads.
Takes a range rather than an exact pin, since it has no security or data blast
radius.
---
 frontend/package.json   | 1 +
 frontend/pnpm-lock.yaml | 8 ++++++++
 2 files changed, 9 insertions(+)

diff --git a/frontend/package.json b/frontend/package.json
index ad9b15a6..45d1539e 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -12,6 +12,7 @@
     "email": "email dev --dir src/emails --port 3366"
   },
   "dependencies": {
+    "@bwip-js/browser": "^4.11.2",
     "@hookform/resolvers": "^5.2.2",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-collapsible": "^1.1.12",
diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml
index 34e9c23a..50365ffe 100644
--- a/frontend/pnpm-lock.yaml
+++ b/frontend/pnpm-lock.yaml
@@ -15,6 +15,9 @@ importers:
 
   .:
     dependencies:
+      '@bwip-js/browser':
+        specifier: ^4.11.2
+        version: 4.11.2
       '@hookform/resolvers':
         specifier: ^5.2.2
         version: 5.4.0(react-hook-form@7.81.0(react@19.2.8))
@@ -396,6 +399,9 @@ packages:
   '@borewit/text-codec@0.2.2':
     resolution: {integrity: sha512-DDaRehssg1aNrH4+2hnj1B7vnUGEjU6OIlyRdkMd0aUdIUvKXrJfXsy8LVtXAy7DRvYVluWbMspsRhz2lcW0mQ==}
 
+  '@bwip-js/browser@4.11.2':
+    resolution: {integrity: sha512-+6wZZY218c0Q6e9xjpESAs851ezWp8pZp2vS7WSjwX0GBOeGoT04NbvgHWPvtg4NIWXEIxoOgSBPnhmkFXhyNg==}
+
   '@clack/core@0.3.5':
     resolution: {integrity: sha512-5cfhQNH+1VQ2xLQlmzXMqUoiaH0lRBq9/CLW9lTyMbuKLC3+xEK01tHVvyut++mLOn5urSHmkm6I0Lg9MaJSTQ==}
 
@@ -5783,6 +5789,8 @@ snapshots:
 
   '@borewit/text-codec@0.2.2': {}
 
+  '@bwip-js/browser@4.11.2': {}
+
   '@clack/core@0.3.5':
     dependencies:
       picocolors: 1.1.1

From 2e96207fcd2d68e68c112fe06d924f7954109d93 Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Thu, 30 Jul 2026 10:53:10 +0200
Subject: [PATCH 02/14] feat(digital-cards): Add community store name
 suggestions

Changes:
- Add disscount.storeName package: entity, repository, DTO, normalizer, service, controller
- Expose GET /api/store-names returning visible suggestions ordered by usage

Free text store names users type on a card become suggestions for everyone else,
so the same shop does not accumulate under five spellings. The table carries no
user reference of any kind: the list is public, so attribution must not be
recoverable from it.

Notes:
- record() is REQUIRES_NEW deliberately. It is called from inside the card save
  transaction, and a concurrent insert colliding on the unique normalized_name
  would otherwise mark that transaction rollback only even when the exception is
  caught, failing the save. It swallows and logs instead, being best effort.
- hiddenAt rather than deletedAt: a hidden suggestion must keep occupying its
  normalized_name slot, or the next card save recreates it. The read filter ships
  now even though moderation does not, so adding it later cannot change what
  offline clients already see.
- usageCount is a monotonic submission count, never decremented, used only for
  ordering. A live card count would need decrements, orphan cleanup and a backfill.
- MIN_PUBLIC_USAGE is 1 so the group is not empty at launch. TODO to raise it to 2
  once there is volume, which is better for typo hygiene.
- Admin moderation (hide, restore, rename, merge) is a TODO on the entity, naming
  the columns and the requireAdmin-inside-the-service pattern it will need.
---
 .../dao/StoreNameSuggestionRepository.java    | 21 +++++
 .../storeName/domain/StoreNameSuggestion.java | 65 ++++++++++++++++
 .../storeName/dto/StoreNameSuggestionDto.java | 16 ++++
 .../storeName/rest/StoreNameController.java   | 31 ++++++++
 .../service/StoreNameNormalizer.java          | 38 +++++++++
 .../service/StoreNameSuggestionService.java   | 77 +++++++++++++++++++
 6 files changed, 248 insertions(+)
 create mode 100644 backend/src/main/java/disscount/storeName/dao/StoreNameSuggestionRepository.java
 create mode 100644 backend/src/main/java/disscount/storeName/domain/StoreNameSuggestion.java
 create mode 100644 backend/src/main/java/disscount/storeName/dto/StoreNameSuggestionDto.java
 create mode 100644 backend/src/main/java/disscount/storeName/rest/StoreNameController.java
 create mode 100644 backend/src/main/java/disscount/storeName/service/StoreNameNormalizer.java
 create mode 100644 backend/src/main/java/disscount/storeName/service/StoreNameSuggestionService.java

diff --git a/backend/src/main/java/disscount/storeName/dao/StoreNameSuggestionRepository.java b/backend/src/main/java/disscount/storeName/dao/StoreNameSuggestionRepository.java
new file mode 100644
index 00000000..8fbe9759
--- /dev/null
+++ b/backend/src/main/java/disscount/storeName/dao/StoreNameSuggestionRepository.java
@@ -0,0 +1,21 @@
+package disscount.storeName.dao;
+
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.stereotype.Repository;
+
+import disscount.storeName.domain.StoreNameSuggestion;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+@Repository
+public interface StoreNameSuggestionRepository extends JpaRepository<StoreNameSuggestion, UUID> {
+
+    Optional<StoreNameSuggestion> findByNormalizedName(String normalizedName);
+
+    @Query("SELECT s FROM StoreNameSuggestion s WHERE s.hiddenAt IS NULL AND s.usageCount >= :minUsage ORDER BY s.usageCount DESC, s.name ASC")
+    List<StoreNameSuggestion> findVisible(int minUsage, Pageable pageable);
+}
diff --git a/backend/src/main/java/disscount/storeName/domain/StoreNameSuggestion.java b/backend/src/main/java/disscount/storeName/domain/StoreNameSuggestion.java
new file mode 100644
index 00000000..2ece6347
--- /dev/null
+++ b/backend/src/main/java/disscount/storeName/domain/StoreNameSuggestion.java
@@ -0,0 +1,65 @@
+package disscount.storeName.domain;
+
+import jakarta.persistence.*;
+import lombok.*;
+
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+/**
+ * Community store-name vocabulary, offered to everyone in the card form's autocomplete.
+ * Deliberately carries no user reference of any kind: suggestions are public, so
+ * attribution must not be recoverable from this table.
+ */
+@Entity
+@Table(name = "store_name_suggestion")
+@Getter
+@Setter
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class StoreNameSuggestion {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    private UUID id;
+
+    // The display form as first submitted, trimmed and whitespace-collapsed.
+    @Column(name = "name", nullable = false, length = 60)
+    private String name;
+
+    // Dedupe key: lowercased, diacritics stripped. See StoreNameNormalizer.
+    @Column(name = "normalized_name", nullable = false, unique = true, length = 60)
+    private String normalizedName;
+
+    // Submission count, not a live card count: monotonic, never decremented on delete.
+    // Used only to order the suggestion list.
+    @Column(name = "usage_count", nullable = false)
+    @Builder.Default
+    private Integer usageCount = 0;
+
+    // Moderation hide, reversible. Not deletedAt: the row must survive so its
+    // normalized_name slot stays taken and the next card save does not recreate it.
+    // TODO(store-name-moderation): rename and merge add a nullable merged_into_id UUID
+    // plus admin PATCH endpoints guarded by userService.requireAdmin() inside the service.
+    @Column(name = "hidden_at")
+    private LocalDateTime hiddenAt;
+
+    @Column(name = "created_at", nullable = false, updatable = false)
+    private LocalDateTime createdAt;
+
+    @Column(name = "updated_at", nullable = false)
+    private LocalDateTime updatedAt;
+
+    @PrePersist
+    protected void onCreate() {
+        LocalDateTime now = LocalDateTime.now();
+        createdAt = now;
+        updatedAt = now;
+    }
+
+    @PreUpdate
+    protected void onUpdate() {
+        updatedAt = LocalDateTime.now();
+    }
+}
diff --git a/backend/src/main/java/disscount/storeName/dto/StoreNameSuggestionDto.java b/backend/src/main/java/disscount/storeName/dto/StoreNameSuggestionDto.java
new file mode 100644
index 00000000..8fec673b
--- /dev/null
+++ b/backend/src/main/java/disscount/storeName/dto/StoreNameSuggestionDto.java
@@ -0,0 +1,16 @@
+package disscount.storeName.dto;
+
+import lombok.Builder;
+import lombok.Data;
+
+/**
+ * No id is exposed: a client cannot act on a single suggestion, and the name is already
+ * unique, so it serves as a stable key.
+ */
+@Data
+@Builder
+public class StoreNameSuggestionDto {
+
+    private String name;
+    private Integer usageCount;
+}
diff --git a/backend/src/main/java/disscount/storeName/rest/StoreNameController.java b/backend/src/main/java/disscount/storeName/rest/StoreNameController.java
new file mode 100644
index 00000000..0f33b284
--- /dev/null
+++ b/backend/src/main/java/disscount/storeName/rest/StoreNameController.java
@@ -0,0 +1,31 @@
+package disscount.storeName.rest;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import disscount.storeName.dto.StoreNameSuggestionDto;
+import disscount.storeName.service.StoreNameSuggestionService;
+
+import java.util.List;
+
+@RestController
+@RequestMapping("/api/store-names")
+@RequiredArgsConstructor
+@Tag(name = "Store Names", description = "Community store name suggestions")
+public class StoreNameController {
+
+    private final StoreNameSuggestionService storeNameSuggestionService;
+
+    // The same list for everyone, so no current-user lookup: SecurityConfig's
+    // anyRequest().authenticated() is the only gate this needs.
+    @Operation(summary = "List community store name suggestions")
+    @GetMapping
+    public ResponseEntity<List<StoreNameSuggestionDto>> getStoreNames() {
+        return ResponseEntity.ok(storeNameSuggestionService.listVisible());
+    }
+}
diff --git a/backend/src/main/java/disscount/storeName/service/StoreNameNormalizer.java b/backend/src/main/java/disscount/storeName/service/StoreNameNormalizer.java
new file mode 100644
index 00000000..6d5cf0b4
--- /dev/null
+++ b/backend/src/main/java/disscount/storeName/service/StoreNameNormalizer.java
@@ -0,0 +1,38 @@
+package disscount.storeName.service;
+
+import java.text.Normalizer;
+import java.util.Locale;
+
+/**
+ * Dedupe key for community store names. Mirrors normalizeForSearch in the frontend's
+ * utils/strings.ts, so "Müller", "muller" and "MULLER  " collapse to one suggestion.
+ */
+public final class StoreNameNormalizer {
+
+    private static final Locale CROATIAN = Locale.forLanguageTag("hr");
+
+    private StoreNameNormalizer() {
+    }
+
+    public static String normalize(String raw) {
+        if (raw == null) {
+            return "";
+        }
+
+        String collapsed = raw.trim().replaceAll("\\s+", " ");
+
+        // NFD splits accents into combining marks that \p{M} then strips, but it leaves
+        // the Croatian đ alone, so that pair is mapped by hand.
+        String stripped = Normalizer.normalize(collapsed, Normalizer.Form.NFD)
+                .replaceAll("\\p{M}", "")
+                .replace("đ", "d")
+                .replace("Đ", "D");
+
+        return stripped.toLowerCase(CROATIAN);
+    }
+
+    /** The display form stored alongside the key: trimmed, inner whitespace collapsed. */
+    public static String toDisplayForm(String raw) {
+        return raw == null ? "" : raw.trim().replaceAll("\\s+", " ");
+    }
+}
diff --git a/backend/src/main/java/disscount/storeName/service/StoreNameSuggestionService.java b/backend/src/main/java/disscount/storeName/service/StoreNameSuggestionService.java
new file mode 100644
index 00000000..d723d07e
--- /dev/null
+++ b/backend/src/main/java/disscount/storeName/service/StoreNameSuggestionService.java
@@ -0,0 +1,77 @@
+package disscount.storeName.service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
+
+import disscount.storeName.dao.StoreNameSuggestionRepository;
+import disscount.storeName.domain.StoreNameSuggestion;
+import disscount.storeName.dto.StoreNameSuggestionDto;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class StoreNameSuggestionService {
+
+    // TODO(store-names): raise to 2 once there is enough volume, so a single typo does
+    // not reach everyone. 1 at launch, otherwise the suggestion group starts empty.
+    private static final int MIN_PUBLIC_USAGE = 1;
+
+    private static final int MAX_SUGGESTIONS = 200;
+
+    private static final int MAX_NAME_LENGTH = 60;
+
+    private final StoreNameSuggestionRepository storeNameSuggestionRepository;
+
+    /**
+     * Best-effort: recording a suggestion must never fail the card save that triggered it.
+     * REQUIRES_NEW is load-bearing, not stylistic. A concurrent insert on the unique
+     * normalized_name marks the *current* transaction rollback-only even when the
+     * exception is caught, so without its own transaction this would poison the caller.
+     */
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public void record(String rawName) {
+        String normalized = StoreNameNormalizer.normalize(rawName);
+        if (normalized.isBlank() || normalized.length() > MAX_NAME_LENGTH) {
+            return;
+        }
+
+        try {
+            StoreNameSuggestion suggestion = storeNameSuggestionRepository
+                    .findByNormalizedName(normalized)
+                    .orElse(null);
+
+            if (suggestion == null) {
+                storeNameSuggestionRepository.save(StoreNameSuggestion.builder()
+                        .name(StoreNameNormalizer.toDisplayForm(rawName))
+                        .normalizedName(normalized)
+                        .usageCount(1)
+                        .build());
+                return;
+            }
+
+            suggestion.setUsageCount(suggestion.getUsageCount() + 1);
+            storeNameSuggestionRepository.save(suggestion);
+        } catch (Exception e) {
+            log.warn("Could not record store name suggestion '{}'", normalized, e);
+        }
+    }
+
+    @Transactional(readOnly = true)
+    public List<StoreNameSuggestionDto> listVisible() {
+        return storeNameSuggestionRepository
+                .findVisible(MIN_PUBLIC_USAGE, PageRequest.of(0, MAX_SUGGESTIONS))
+                .stream()
+                .map(suggestion -> StoreNameSuggestionDto.builder()
+                        .name(suggestion.getName())
+                        .usageCount(suggestion.getUsageCount())
+                        .build())
+                .collect(Collectors.toList());
+    }
+}

From 89c9d84a80d01c8634507461cedf6662f00d24ec Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Thu, 30 Jul 2026 10:53:22 +0200
Subject: [PATCH 03/14] feat(digital-cards): Rebuild the digital card backend

Changes:
- Replace the disscount.digitalCard package: entity, repository, DTOs, service, controller
- Add store, colour, three base64 images, pinning and updatedAt to the card
- Expose POST, GET /me, PUT, DELETE plus PATCH /{id}/pin and /{id}/unpin
- Record a custom store name as a suggestion on create, and on update only when it changed

The previous entity carried a title, a free text type and a code, which was too
thin to build a wallet on: no store link, no images, no pinning, no updatedAt.

Notes:
- cardType and codeType are plain String columns, never @Enumerated. ddl-auto=update
  leaves a stale CHECK constraint behind when a vocabulary changes, which then 500s
  on write.
- chainCode is a nullable opaque string beside a free text storeName, mirroring
  PinnedStore's storeApiId and storeName denormalisation, so a card stays readable
  with no join and a shop outside the official list still works.
- Pin is its own verb rather than a PUT, which is a full replace and would ship all
  three base64 images back just to set a timestamp.
- Every id addressed method resolves through findActiveByIdAndUser, so ownership
  cannot be forgotten. Deliberately unlike NotificationController, which omits it.
- Images are TEXT columns with @Size caps on the request DTO, following User.image.
  Three at cap is roughly a 2.8 MB body and no server side ceiling is configured,
  so the client pre-checks the encoded length before sending.
- Read verified only: Maven must not run here, so please compile before pushing.
---
 .../dao/DigitalCardRepository.java            |   5 +-
 .../digitalCard/domain/DigitalCard.java       |  61 ++++++---
 .../digitalCard/dto/DigitalCardDto.java       |  22 ++--
 .../digitalCard/dto/DigitalCardRequest.java   |  46 +++++--
 .../rest/DigitalCardController.java           |  46 +++----
 .../service/DigitalCardService.java           | 119 ++++++++++++------
 6 files changed, 205 insertions(+), 94 deletions(-)

diff --git a/backend/src/main/java/disscount/digitalCard/dao/DigitalCardRepository.java b/backend/src/main/java/disscount/digitalCard/dao/DigitalCardRepository.java
index 17d15dc0..98d8bdd1 100644
--- a/backend/src/main/java/disscount/digitalCard/dao/DigitalCardRepository.java
+++ b/backend/src/main/java/disscount/digitalCard/dao/DigitalCardRepository.java
@@ -14,12 +14,9 @@
 @Repository
 public interface DigitalCardRepository extends JpaRepository<DigitalCard, UUID> {
 
-    @Query("SELECT dc FROM DigitalCard dc WHERE dc.user = :user AND dc.deletedAt IS NULL")
+    @Query("SELECT dc FROM DigitalCard dc WHERE dc.user = :user AND dc.deletedAt IS NULL ORDER BY dc.updatedAt DESC")
     List<DigitalCard> findActiveByUser(User user);
 
-    @Query("SELECT dc FROM DigitalCard dc WHERE dc.id = :id AND dc.deletedAt IS NULL")
-    Optional<DigitalCard> findActiveById(UUID id);
-
     @Query("SELECT dc FROM DigitalCard dc WHERE dc.id = :id AND dc.user = :user AND dc.deletedAt IS NULL")
     Optional<DigitalCard> findActiveByIdAndUser(UUID id, User user);
 }
diff --git a/backend/src/main/java/disscount/digitalCard/domain/DigitalCard.java b/backend/src/main/java/disscount/digitalCard/domain/DigitalCard.java
index b456db49..0b106952 100644
--- a/backend/src/main/java/disscount/digitalCard/domain/DigitalCard.java
+++ b/backend/src/main/java/disscount/digitalCard/domain/DigitalCard.java
@@ -1,7 +1,6 @@
 package disscount.digitalCard.domain;
 
 import jakarta.persistence.*;
-import jakarta.validation.constraints.NotBlank;
 import lombok.*;
 
 import java.time.LocalDateTime;
@@ -26,36 +25,66 @@ public class DigitalCard {
     @JoinColumn(name = "user_id", nullable = false)
     private User user;
 
-    @NotBlank(message = "Title is required")
-    @Column(nullable = false)
-    private String title;
+    @Column(name = "card_name", nullable = false)
+    private String cardName;
 
-    @NotBlank(message = "Type is required")
-    @Column(name = "type")
-    private String type;
+    // Plain String, never @Enumerated: ddl-auto=update leaves a stale CHECK constraint
+    // behind if the vocabulary ever changes. Values: loyalty | gift | membership | other.
+    @Column(name = "card_type", nullable = false, length = 16)
+    private String cardType;
 
-    @NotBlank(message = "Value is required")
-    @Column(nullable = false)
-    private String value;
+    @Column(name = "store_name", nullable = false)
+    private String storeName;
 
-    @NotBlank(message = "Code type is required")
-    @Column(name = "code_type", nullable = false)
+    // cijene-api chain code when the user picked an official chain; null for free text.
+    @Column(name = "chain_code", length = 40)
+    private String chainCode;
+
+    @Column(name = "code_value", nullable = false, length = 4096)
+    private String codeValue;
+
+    // Barcode Detection API format name (ean_13, qr_code, ...) or "unknown".
+    @Column(name = "code_type", nullable = false, length = 32)
     private String codeType;
 
-    @Column
-    private String color;
+    @Column(name = "card_color", nullable = false, length = 7)
+    private String cardColor;
+
+    @Column(name = "icon_image", columnDefinition = "TEXT")
+    private String iconImage;
+
+    @Column(name = "front_image", columnDefinition = "TEXT")
+    private String frontImage;
+
+    @Column(name = "back_image", columnDefinition = "TEXT")
+    private String backImage;
 
-    @Column(columnDefinition = "TEXT")
+    @Column(name = "note", length = 500)
     private String note;
 
+    // Null = not pinned, matching User's toggle timestamps. Pinning goes through
+    // @PreUpdate, so it counts as a change and bumps updatedAt.
+    @Column(name = "pinned_at")
+    private LocalDateTime pinnedAt;
+
     @Column(name = "created_at", nullable = false, updatable = false)
     private LocalDateTime createdAt;
 
+    @Column(name = "updated_at", nullable = false)
+    private LocalDateTime updatedAt;
+
     @Column(name = "deleted_at")
     private LocalDateTime deletedAt;
 
     @PrePersist
     protected void onCreate() {
-        createdAt = LocalDateTime.now();
+        LocalDateTime now = LocalDateTime.now();
+        createdAt = now;
+        updatedAt = now;
+    }
+
+    @PreUpdate
+    protected void onUpdate() {
+        updatedAt = LocalDateTime.now();
     }
 }
diff --git a/backend/src/main/java/disscount/digitalCard/dto/DigitalCardDto.java b/backend/src/main/java/disscount/digitalCard/dto/DigitalCardDto.java
index 7d4729f6..4e124706 100644
--- a/backend/src/main/java/disscount/digitalCard/dto/DigitalCardDto.java
+++ b/backend/src/main/java/disscount/digitalCard/dto/DigitalCardDto.java
@@ -1,25 +1,29 @@
 package disscount.digitalCard.dto;
 
-import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;
-import lombok.NoArgsConstructor;
 
 import java.time.LocalDateTime;
 import java.util.UUID;
 
 @Data
-@NoArgsConstructor
-@AllArgsConstructor
 @Builder
 public class DigitalCardDto {
-    
+
     private UUID id;
-    private String title;
-    private String value;
-    private String type;
+    private UUID userId;
+    private String cardName;
+    private String cardType;
+    private String storeName;
+    private String chainCode;
+    private String codeValue;
     private String codeType;
-    private String color;
+    private String cardColor;
+    private String iconImage;
+    private String frontImage;
+    private String backImage;
     private String note;
+    private LocalDateTime pinnedAt;
     private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
 }
diff --git a/backend/src/main/java/disscount/digitalCard/dto/DigitalCardRequest.java b/backend/src/main/java/disscount/digitalCard/dto/DigitalCardRequest.java
index ac620a82..a4aac9d4 100644
--- a/backend/src/main/java/disscount/digitalCard/dto/DigitalCardRequest.java
+++ b/backend/src/main/java/disscount/digitalCard/dto/DigitalCardRequest.java
@@ -1,23 +1,53 @@
 package disscount.digitalCard.dto;
 
 import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
 import lombok.Data;
 
 @Data
 public class DigitalCardRequest {
 
-    @NotBlank(message = "Title is required")
-    private String title;
+    @NotBlank(message = "Naziv kartice je obavezan")
+    @Size(min = 2, max = 60, message = "Naziv kartice mora imati između 2 i 60 znakova")
+    private String cardName;
 
-    @NotBlank(message = "Value is required")
-    private String value;
+    @NotBlank(message = "Tip kartice je obavezan")
+    @Pattern(regexp = "loyalty|gift|membership|other", message = "Neispravan tip kartice")
+    private String cardType;
 
-    @NotBlank(message = "Type is required")
-    private String type;
+    @NotBlank(message = "Naziv trgovine je obavezan")
+    @Size(min = 2, max = 60, message = "Naziv trgovine mora imati između 2 i 60 znakova")
+    private String storeName;
 
-    @NotBlank(message = "Code type is required")
+    @Size(max = 40, message = "Neispravna oznaka trgovine")
+    private String chainCode;
+
+    @NotBlank(message = "Kod kartice je obavezan")
+    @Size(max = 4096, message = "Kod kartice je predug")
+    private String codeValue;
+
+    // Barcode Detection API vocabulary, deliberately not pattern-constrained beyond
+    // length: a browser adding a format should not need a backend release.
+    @NotBlank(message = "Tip koda je obavezan")
+    @Size(max = 32, message = "Neispravan tip koda")
     private String codeType;
 
-    private String color;
+    @NotBlank(message = "Boja kartice je obavezna")
+    @Pattern(regexp = "#[0-9a-fA-F]{6}", message = "Neispravna boja kartice")
+    private String cardColor;
+
+    // Base64 data URIs. The client downscales the icon to 256px and the card faces to
+    // 1024px WebP, so these are abuse backstops rather than the real limits.
+    @Size(max = 400_000, message = "Ikona je prevelika")
+    private String iconImage;
+
+    @Size(max = 1_200_000, message = "Slika prednje strane je prevelika")
+    private String frontImage;
+
+    @Size(max = 1_200_000, message = "Slika stražnje strane je prevelika")
+    private String backImage;
+
+    @Size(max = 500, message = "Bilješka može imati najviše 500 znakova")
     private String note;
 }
diff --git a/backend/src/main/java/disscount/digitalCard/rest/DigitalCardController.java b/backend/src/main/java/disscount/digitalCard/rest/DigitalCardController.java
index 903b50ef..e1a34489 100644
--- a/backend/src/main/java/disscount/digitalCard/rest/DigitalCardController.java
+++ b/backend/src/main/java/disscount/digitalCard/rest/DigitalCardController.java
@@ -13,13 +13,12 @@
 import disscount.util.SecurityUtils;
 
 import java.util.List;
-import java.util.Map;
 import java.util.UUID;
 
 @RestController
 @RequestMapping("/api/digital-cards")
 @RequiredArgsConstructor
-@Tag(name = "Digital Cards", description = "Digital card management endpoints")
+@Tag(name = "Digital Cards", description = "Loyalty card wallet endpoints")
 public class DigitalCardController {
 
     private final DigitalCardService digitalCardService;
@@ -28,42 +27,47 @@ public class DigitalCardController {
     @PostMapping
     public ResponseEntity<DigitalCardDto> createCard(@Valid @RequestBody DigitalCardRequest request) {
         UUID userId = SecurityUtils.getCurrentUserId();
-        DigitalCardDto card = digitalCardService.createCard(userId, request);
-        return ResponseEntity.ok(card);
+        DigitalCardDto created = digitalCardService.createCard(userId, request);
+        return ResponseEntity.ok(created);
     }
 
-    @Operation(summary = "Get all digital cards for current user")
+    @Operation(summary = "Get current user's digital cards")
     @GetMapping("/me")
-    public ResponseEntity<List<DigitalCardDto>> getUserCards() {
+    public ResponseEntity<List<DigitalCardDto>> getCurrentUserCards() {
         UUID userId = SecurityUtils.getCurrentUserId();
         List<DigitalCardDto> cards = digitalCardService.getUserCards(userId);
         return ResponseEntity.ok(cards);
     }
 
-    @Operation(summary = "Get digital card by ID")
-    @GetMapping("/{id}")
-    public ResponseEntity<DigitalCardDto> getCardById(@PathVariable UUID id) {
-        UUID userId = SecurityUtils.getCurrentUserId();
-        return digitalCardService.getCardById(id, userId)
-            .map(ResponseEntity::ok)
-            .orElse(ResponseEntity.notFound().build());
-    }
-
     @Operation(summary = "Update digital card")
     @PutMapping("/{id}")
     public ResponseEntity<DigitalCardDto> updateCard(
             @PathVariable UUID id,
-            @RequestBody DigitalCardRequest request) {
+            @Valid @RequestBody DigitalCardRequest request) {
         UUID userId = SecurityUtils.getCurrentUserId();
-        DigitalCardDto updatedCard = digitalCardService.updateCard(id, userId, request);
-        return ResponseEntity.ok(updatedCard);
+        DigitalCardDto updated = digitalCardService.updateCard(id, userId, request);
+        return ResponseEntity.ok(updated);
     }
 
-    @Operation(summary = "Delete digital card (soft delete)")
+    @Operation(summary = "Delete digital card")
     @DeleteMapping("/{id}")
-    public ResponseEntity<Map<String, String>> deleteCard(@PathVariable UUID id) {
+    public ResponseEntity<Void> deleteCard(@PathVariable UUID id) {
         UUID userId = SecurityUtils.getCurrentUserId();
         digitalCardService.deleteCard(id, userId);
-        return ResponseEntity.ok(Map.of("message", "Card deleted successfully"));
+        return ResponseEntity.noContent().build();
+    }
+
+    @Operation(summary = "Pin digital card")
+    @PatchMapping("/{id}/pin")
+    public ResponseEntity<DigitalCardDto> pinCard(@PathVariable UUID id) {
+        UUID userId = SecurityUtils.getCurrentUserId();
+        return ResponseEntity.ok(digitalCardService.setPinned(id, userId, true));
+    }
+
+    @Operation(summary = "Unpin digital card")
+    @PatchMapping("/{id}/unpin")
+    public ResponseEntity<DigitalCardDto> unpinCard(@PathVariable UUID id) {
+        UUID userId = SecurityUtils.getCurrentUserId();
+        return ResponseEntity.ok(digitalCardService.setPinned(id, userId, false));
     }
 }
diff --git a/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java b/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
index 7245bb37..fc488ff5 100644
--- a/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
+++ b/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
@@ -10,13 +10,15 @@
 import disscount.digitalCard.dto.DigitalCardRequest;
 import disscount.exceptions.BadRequestException;
 import disscount.exceptions.UnauthorizedException;
+import disscount.storeName.service.StoreNameNormalizer;
+import disscount.storeName.service.StoreNameSuggestionService;
 import disscount.user.dao.UserRepository;
 import disscount.user.domain.User;
 
 import java.time.LocalDateTime;
 import java.util.List;
-import java.util.Optional;
 import java.util.UUID;
+import java.util.stream.Collectors;
 
 @Service
 @RequiredArgsConstructor
@@ -25,83 +27,128 @@ public class DigitalCardService {
 
     private final DigitalCardRepository digitalCardRepository;
     private final UserRepository userRepository;
+    private final StoreNameSuggestionService storeNameSuggestionService;
 
     public DigitalCardDto createCard(UUID userId, DigitalCardRequest request) {
-        User user = userRepository.findById(userId)
-                .orElseThrow(() -> new UnauthorizedException("User not found"));
+        User user = requireUser(userId);
 
         DigitalCard card = DigitalCard.builder()
                 .user(user)
-                .title(request.getTitle())
-                .value(request.getValue())
-                .type(request.getType())
+                .cardName(request.getCardName())
+                .cardType(request.getCardType())
+                .storeName(request.getStoreName())
+                .chainCode(request.getChainCode())
+                .codeValue(request.getCodeValue())
                 .codeType(request.getCodeType())
-                .color(request.getColor())
+                .cardColor(request.getCardColor())
+                .iconImage(request.getIconImage())
+                .frontImage(request.getFrontImage())
+                .backImage(request.getBackImage())
                 .note(request.getNote())
                 .build();
 
         card = digitalCardRepository.save(card);
+        recordStoreNameIfCustom(request.getChainCode(), request.getStoreName());
+
         return convertToDto(card);
     }
 
+    @Transactional(readOnly = true)
     public List<DigitalCardDto> getUserCards(UUID userId) {
-        User user = userRepository.findById(userId)
-                .orElseThrow(() -> new UnauthorizedException("User not found"));
+        User user = requireUser(userId);
 
         return digitalCardRepository.findActiveByUser(user)
                 .stream()
                 .map(this::convertToDto)
-                .toList();
-    }
-
-    public Optional<DigitalCardDto> getCardById(UUID cardId, UUID userId) {
-        User user = userRepository.findById(userId)
-                .orElseThrow(() -> new UnauthorizedException("User not found"));
-
-        return digitalCardRepository.findActiveByIdAndUser(cardId, user)
-                .map(this::convertToDto);
+                .collect(Collectors.toList());
     }
 
     public DigitalCardDto updateCard(UUID cardId, UUID userId, DigitalCardRequest request) {
-        User user = userRepository.findById(userId)
-                .orElseThrow(() -> new UnauthorizedException("User not found"));
+        User user = requireUser(userId);
+        DigitalCard card = requireCard(cardId, user);
 
-        DigitalCard card = digitalCardRepository.findActiveByIdAndUser(cardId, user)
-                .orElseThrow(() -> new BadRequestException("Card not found"));
+        String previousStoreName = card.getStoreName();
 
-        // Replace full resource (PUT semantics)
-        card.setTitle(request.getTitle());
-        card.setValue(request.getValue());
-        card.setType(request.getType());
+        card.setCardName(request.getCardName());
+        card.setCardType(request.getCardType());
+        card.setStoreName(request.getStoreName());
+        card.setChainCode(request.getChainCode());
+        card.setCodeValue(request.getCodeValue());
         card.setCodeType(request.getCodeType());
-        card.setColor(request.getColor());
+        card.setCardColor(request.getCardColor());
+        card.setIconImage(request.getIconImage());
+        card.setFrontImage(request.getFrontImage());
+        card.setBackImage(request.getBackImage());
         card.setNote(request.getNote());
 
         card = digitalCardRepository.save(card);
+
+        // Only a genuinely new name counts, so re-saving a card does not inflate its
+        // suggestion's usage count.
+        boolean nameChanged = !StoreNameNormalizer.normalize(previousStoreName)
+                .equals(StoreNameNormalizer.normalize(request.getStoreName()));
+        if (nameChanged) {
+            recordStoreNameIfCustom(request.getChainCode(), request.getStoreName());
+        }
+
         return convertToDto(card);
     }
 
     public void deleteCard(UUID cardId, UUID userId) {
-        User user = userRepository.findById(userId)
-                .orElseThrow(() -> new UnauthorizedException("User not found"));
-
-        DigitalCard card = digitalCardRepository.findActiveByIdAndUser(cardId, user)
-                .orElseThrow(() -> new BadRequestException("Card not found"));
+        User user = requireUser(userId);
+        DigitalCard card = requireCard(cardId, user);
 
         card.setDeletedAt(LocalDateTime.now());
         digitalCardRepository.save(card);
     }
 
+    public DigitalCardDto setPinned(UUID cardId, UUID userId, boolean pinned) {
+        User user = requireUser(userId);
+        DigitalCard card = requireCard(cardId, user);
+
+        card.setPinnedAt(pinned ? LocalDateTime.now() : null);
+        card = digitalCardRepository.save(card);
+
+        return convertToDto(card);
+    }
+
+    private User requireUser(UUID userId) {
+        return userRepository.findById(userId)
+                .orElseThrow(() -> new UnauthorizedException("User not found"));
+    }
+
+    /** Ownership is enforced by the query itself, so there is no separate check to forget. */
+    private DigitalCard requireCard(UUID cardId, User user) {
+        return digitalCardRepository.findActiveByIdAndUser(cardId, user)
+                .orElseThrow(() -> new BadRequestException("Digital card not found"));
+    }
+
+    // Official chains already have their own autocomplete group, so only free text is
+    // worth offering back to other users.
+    private void recordStoreNameIfCustom(String chainCode, String storeName) {
+        if (chainCode == null || chainCode.isBlank()) {
+            storeNameSuggestionService.record(storeName);
+        }
+    }
+
     private DigitalCardDto convertToDto(DigitalCard card) {
         return DigitalCardDto.builder()
                 .id(card.getId())
-                .title(card.getTitle())
-                .value(card.getValue())
-                .type(card.getType())
+                .userId(card.getUser().getId())
+                .cardName(card.getCardName())
+                .cardType(card.getCardType())
+                .storeName(card.getStoreName())
+                .chainCode(card.getChainCode())
+                .codeValue(card.getCodeValue())
                 .codeType(card.getCodeType())
-                .color(card.getColor())
+                .cardColor(card.getCardColor())
+                .iconImage(card.getIconImage())
+                .frontImage(card.getFrontImage())
+                .backImage(card.getBackImage())
                 .note(card.getNote())
+                .pinnedAt(card.getPinnedAt())
                 .createdAt(card.getCreatedAt())
+                .updatedAt(card.getUpdatedAt())
                 .build();
     }
 }

From ee93e3a3918dfbaaf4a47f1008afbb271b0086c1 Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Thu, 30 Jul 2026 10:53:35 +0200
Subject: [PATCH 04/14] feat(digital-cards): Add the card API layer and offline
 wiring

Changes:
- Add the shared card and code vocabularies in constants/card-codes.ts
- Add zod schemas for the card request, form and DTO, plus store name suggestions
- Add lib/api/digital-cards and lib/api/store-names service triplets
- Register both services in the api barrel
- Persist the digitalCards and storeNames query roots for offline reads
- Register create, update, delete and pin as replayable offline mutations

Offline is the point of the feature: a shop with no signal is exactly where a
loyalty card gets used, so reads are cached and writes queue and replay.

Notes:
- codeType stores the Barcode Detection API's own format names (ean_13, qr_code),
  which is precisely what the scanner returns, so a scan needs no translation on
  the way in and bwip-js encoder names stay a rendering detail.
- The vocabulary adds "unknown" for a card whose number has no barcode, and it
  doubles as the graceful landing spot when a symbology rejects a value.
- digitalCardFormSchema omits the three images: they live outside react-hook-form
  like the settings avatar, since base64 would blow the localStorage draft quota.
- setDigitalCardPinned is one function over the two backend verbs, so the offline
  registry needs one key instead of two.
- storeNames is cached too, otherwise the form's autocomplete is empty offline.
---
 frontend/src/constants/card-codes.ts          |  29 +++++
 frontend/src/lib/api/digital-cards/hooks.ts   |  63 +++++++++++
 frontend/src/lib/api/digital-cards/index.ts   | 105 +-----------------
 frontend/src/lib/api/digital-cards/queries.ts |  46 ++++++++
 frontend/src/lib/api/index.ts                 |   2 +
 frontend/src/lib/api/schemas/digital-card.ts  |  62 +++++++----
 frontend/src/lib/api/schemas/index.ts         |   1 +
 frontend/src/lib/api/schemas/store-name.ts    |   8 ++
 frontend/src/lib/api/store-names/hooks.ts     |  14 +++
 frontend/src/lib/api/store-names/index.ts     |   9 ++
 frontend/src/lib/api/store-names/queries.ts   |  10 ++
 frontend/src/lib/offline/cached-query-keys.ts |   1 +
 .../src/lib/offline/offline-mutation-keys.ts  |   4 +
 frontend/src/lib/offline/offline-mutations.ts |  34 ++++++
 14 files changed, 266 insertions(+), 122 deletions(-)
 create mode 100644 frontend/src/constants/card-codes.ts
 create mode 100644 frontend/src/lib/api/digital-cards/hooks.ts
 create mode 100644 frontend/src/lib/api/digital-cards/queries.ts
 create mode 100644 frontend/src/lib/api/schemas/store-name.ts
 create mode 100644 frontend/src/lib/api/store-names/hooks.ts
 create mode 100644 frontend/src/lib/api/store-names/index.ts
 create mode 100644 frontend/src/lib/api/store-names/queries.ts

diff --git a/frontend/src/constants/card-codes.ts b/frontend/src/constants/card-codes.ts
new file mode 100644
index 00000000..3c6cf17a
--- /dev/null
+++ b/frontend/src/constants/card-codes.ts
@@ -0,0 +1,29 @@
+import type { BarcodeFormat } from "barcode-detector";
+
+// Stored codeType vocabulary: the Barcode Detection API's own format names, which is
+// exactly what the scanner hands back, so a scan needs no translation on the way in.
+export const SCANNABLE_CODE_TYPES = [
+  "ean_13",
+  "ean_8",
+  "upc_a",
+  "upc_e",
+  "code_128",
+  "code_39",
+  "code_93",
+  "itf",
+  "codabar",
+  "qr_code",
+  "data_matrix",
+  "pdf417",
+  "aztec",
+] as const satisfies readonly BarcodeFormat[];
+
+// "unknown" is the escape hatch for a code we cannot draw: a membership number, or a
+// value the chosen symbology rejects. The card then prints the value large instead.
+export const CODE_TYPES = [...SCANNABLE_CODE_TYPES, "unknown"] as const;
+
+export type CodeType = (typeof CODE_TYPES)[number];
+
+export const CARD_TYPES = ["loyalty", "gift", "membership", "other"] as const;
+
+export type CardType = (typeof CARD_TYPES)[number];
diff --git a/frontend/src/lib/api/digital-cards/hooks.ts b/frontend/src/lib/api/digital-cards/hooks.ts
new file mode 100644
index 00000000..cb18f632
--- /dev/null
+++ b/frontend/src/lib/api/digital-cards/hooks.ts
@@ -0,0 +1,63 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+import { OFFLINE_MUTATION_KEYS } from "@/lib/offline/offline-mutation-keys";
+import { DigitalCardRequest, DigitalCardDto } from "@/lib/api/types";
+import {
+  createDigitalCard,
+  getCurrentUserDigitalCards,
+  updateDigitalCard,
+  deleteDigitalCard,
+  setDigitalCardPinned,
+} from "@/lib/api/digital-cards/queries";
+
+const CARDS_KEY = ["digitalCards"];
+
+export function useCreateDigitalCard() {
+  const queryClient = useQueryClient();
+  return useMutation<DigitalCardDto, Error, DigitalCardRequest>({
+    mutationKey: OFFLINE_MUTATION_KEYS.digitalCardCreate,
+    mutationFn: createDigitalCard,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: CARDS_KEY }),
+  });
+}
+
+export function useGetCurrentUserDigitalCards({
+  enabled = true,
+}: { enabled?: boolean } = {}) {
+  return useQuery<DigitalCardDto[], Error>({
+    queryKey: ["digitalCards", "me"],
+    queryFn: getCurrentUserDigitalCards,
+    enabled,
+  });
+}
+
+export function useUpdateDigitalCard() {
+  const queryClient = useQueryClient();
+  return useMutation<
+    DigitalCardDto,
+    Error,
+    { id: string; data: DigitalCardRequest }
+  >({
+    mutationKey: OFFLINE_MUTATION_KEYS.digitalCardUpdate,
+    mutationFn: ({ id, data }) => updateDigitalCard(id, data),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: CARDS_KEY }),
+  });
+}
+
+export function useDeleteDigitalCard() {
+  const queryClient = useQueryClient();
+  return useMutation<void, Error, string>({
+    mutationKey: OFFLINE_MUTATION_KEYS.digitalCardDelete,
+    mutationFn: deleteDigitalCard,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: CARDS_KEY }),
+  });
+}
+
+export function useSetDigitalCardPinned() {
+  const queryClient = useQueryClient();
+  return useMutation<DigitalCardDto, Error, { id: string; pinned: boolean }>({
+    mutationKey: OFFLINE_MUTATION_KEYS.digitalCardSetPinned,
+    mutationFn: ({ id, pinned }) => setDigitalCardPinned(id, pinned),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: CARDS_KEY }),
+  });
+}
diff --git a/frontend/src/lib/api/digital-cards/index.ts b/frontend/src/lib/api/digital-cards/index.ts
index 22558d1f..b1d2a8c1 100644
--- a/frontend/src/lib/api/digital-cards/index.ts
+++ b/frontend/src/lib/api/digital-cards/index.ts
@@ -1,104 +1,9 @@
-import { useMutation, useQuery } from "@tanstack/react-query";
-import apiClient from "@/lib/api/api-base";
-import {
-  DigitalCardRequest,
-  DigitalCardDto,
-  digitalCardRequestSchema,
-  digitalCardDtoSchema,
-} from "@/lib/api/types";
+import * as queries from "@/lib/api/digital-cards/queries";
+import * as hooks from "@/lib/api/digital-cards/hooks";
 
-/**
- * Create a new digital card
- */
-export async function createDigitalCard(
-  data: DigitalCardRequest,
-): Promise<DigitalCardDto> {
-  const validatedData = digitalCardRequestSchema.parse(data);
+export * from "@/lib/api/digital-cards/queries";
+export * from "@/lib/api/digital-cards/hooks";
 
-  const response = await apiClient.post<DigitalCardDto>(
-    "/api/digital-cards",
-    validatedData,
-  );
-
-  return digitalCardDtoSchema.parse(response.data);
-}
-
-/**
- * Get all digital cards for current user
- */
-export async function getUserDigitalCards(): Promise<DigitalCardDto[]> {
-  const response = await apiClient.get<DigitalCardDto[]>(
-    "/api/digital-cards/me",
-  );
-
-  return response.data.map((item) => digitalCardDtoSchema.parse(item));
-}
-
-/**
- * Update digital card
- */
-export async function updateDigitalCard(
-  id: string,
-  data: DigitalCardRequest,
-): Promise<DigitalCardDto> {
-  const validatedData = digitalCardRequestSchema.parse(data);
-
-  const response = await apiClient.put<DigitalCardDto>(
-    `/api/digital-cards/${id}`,
-    validatedData,
-  );
-
-  return digitalCardDtoSchema.parse(response.data);
-}
-
-/**
- * Delete digital card
- */
-export async function deleteDigitalCard(id: string): Promise<void> {
-  await apiClient.delete(`/api/digital-cards/${id}`);
-}
-
-// React Query hooks
-export function useCreateDigitalCard() {
-  return useMutation<DigitalCardDto, Error, DigitalCardRequest>({
-    mutationFn: createDigitalCard,
-  });
-}
-
-export function useGetUserDigitalCards({ enabled = true } = {}) {
-  return useQuery<DigitalCardDto[], Error>({
-    queryKey: ["digitalCards", "me"],
-    queryFn: getUserDigitalCards,
-    enabled,
-  });
-}
-
-export function useUpdateDigitalCard() {
-  return useMutation<
-    DigitalCardDto,
-    Error,
-    { id: string; data: DigitalCardRequest }
-  >({
-    mutationFn: ({ id, data }) => updateDigitalCard(id, data),
-  });
-}
-
-export function useDeleteDigitalCard() {
-  return useMutation<void, Error, string>({
-    mutationFn: deleteDigitalCard,
-  });
-}
-
-const digitalCardService = {
-  createDigitalCard,
-  getUserDigitalCards,
-  updateDigitalCard,
-  deleteDigitalCard,
-  // React Query hooks
-  useCreateDigitalCard,
-  useGetUserDigitalCards,
-  useUpdateDigitalCard,
-  useDeleteDigitalCard,
-};
+const digitalCardService = { ...queries, ...hooks };
 
 export default digitalCardService;
diff --git a/frontend/src/lib/api/digital-cards/queries.ts b/frontend/src/lib/api/digital-cards/queries.ts
new file mode 100644
index 00000000..1664d07c
--- /dev/null
+++ b/frontend/src/lib/api/digital-cards/queries.ts
@@ -0,0 +1,46 @@
+import apiClient from "@/lib/api/api-base";
+import { DigitalCardRequest, DigitalCardDto } from "@/lib/api/types";
+
+export async function createDigitalCard(
+  data: DigitalCardRequest,
+): Promise<DigitalCardDto> {
+  const response = await apiClient.post<DigitalCardDto>(
+    "/api/digital-cards",
+    data,
+  );
+  return response.data;
+}
+
+export async function getCurrentUserDigitalCards(): Promise<DigitalCardDto[]> {
+  const response = await apiClient.get<DigitalCardDto[]>(
+    "/api/digital-cards/me",
+  );
+  return response.data;
+}
+
+export async function updateDigitalCard(
+  id: string,
+  data: DigitalCardRequest,
+): Promise<DigitalCardDto> {
+  const response = await apiClient.put<DigitalCardDto>(
+    `/api/digital-cards/${id}`,
+    data,
+  );
+  return response.data;
+}
+
+export async function deleteDigitalCard(id: string): Promise<void> {
+  await apiClient.delete(`/api/digital-cards/${id}`);
+}
+
+// One function over two endpoints: pinning must not ship the card's images back, which
+// a full PUT would, so the backend keeps them as separate verbs.
+export async function setDigitalCardPinned(
+  id: string,
+  pinned: boolean,
+): Promise<DigitalCardDto> {
+  const response = await apiClient.patch<DigitalCardDto>(
+    `/api/digital-cards/${id}/${pinned ? "pin" : "unpin"}`,
+  );
+  return response.data;
+}
diff --git a/frontend/src/lib/api/index.ts b/frontend/src/lib/api/index.ts
index 693bc2bb..a5b8501c 100644
--- a/frontend/src/lib/api/index.ts
+++ b/frontend/src/lib/api/index.ts
@@ -3,6 +3,7 @@ import userService from "@/lib/api/users";
 import preferencesService from "@/lib/api/preferences";
 import shoppingListService from "@/lib/api/shopping-lists";
 import digitalCardService from "@/lib/api/digital-cards";
+import storeNameService from "@/lib/api/store-names";
 import watchlistService from "@/lib/api/watchlist";
 import adminService from "@/lib/api/admin";
 import contactService from "@/lib/api/contact";
@@ -15,6 +16,7 @@ export {
   preferencesService,
   shoppingListService,
   digitalCardService,
+  storeNameService,
   watchlistService,
   adminService,
   contactService,
diff --git a/frontend/src/lib/api/schemas/digital-card.ts b/frontend/src/lib/api/schemas/digital-card.ts
index 9df4f58d..3195552e 100644
--- a/frontend/src/lib/api/schemas/digital-card.ts
+++ b/frontend/src/lib/api/schemas/digital-card.ts
@@ -1,41 +1,59 @@
 import { z } from "zod";
 
-// Digital Card schemas
+import { CARD_TYPES, CODE_TYPES } from "@/constants/card-codes";
+
 export const digitalCardRequestSchema = z.object({
-  title: z
+  cardName: z
     .string()
-    .min(1, "Naziv je obavezan")
-    .max(100, "Naziv može imati najviše 100 znakova"),
-  value: z
+    .trim()
+    .min(2, "Naziv kartice mora imati najmanje 2 znaka")
+    .max(60, "Naziv kartice može imati najviše 60 znakova"),
+  cardType: z.enum(CARD_TYPES, { message: "Odaberi tip kartice" }),
+  storeName: z
     .string()
-    .min(1, "Vrijednost je obavezna")
-    .max(500, "Vrijednost može imati najviše 500 znakova"),
-  type: z
+    .trim()
+    .min(2, "Naziv trgovine mora imati najmanje 2 znaka")
+    .max(60, "Naziv trgovine može imati najviše 60 znakova"),
+  chainCode: z.string().max(40).nullable(),
+  codeValue: z
     .string()
-    .min(1, "Tip je obavezan")
-    .max(50, "Tip može imati najviše 50 znakova"),
-  codeType: z
+    .trim()
+    .min(1, "Unesi ili skeniraj kod kartice")
+    .max(4096, "Kod kartice je predug"),
+  codeType: z.enum(CODE_TYPES, { message: "Odaberi tip koda" }),
+  cardColor: z.string().regex(/^#[0-9a-fA-F]{6}$/, "Neispravna boja kartice"),
+  iconImage: z.string().max(400_000, "Ikona je prevelika").nullable(),
+  frontImage: z
     .string()
-    .min(1, "Tip koda je obavezan")
-    .max(50, "Tip koda može imati najviše 50 znakova"),
-  color: z
+    .max(1_200_000, "Slika prednje strane je prevelika")
+    .nullable(),
+  backImage: z
     .string()
-    .regex(/^#[0-9A-Fa-f]{6}$/, "Boja mora biti u HEX formatu (#ffffff)")
-    .nullable()
-    .optional(),
+    .max(1_200_000, "Slika stražnje strane je prevelika")
+    .nullable(),
   note: z
     .string()
-    .max(500, "Napomena može imati najviše 500 znakova")
-    .nullable()
-    .optional(),
+    .trim()
+    .max(500, "Bilješka može imati najviše 500 znakova")
+    .nullable(),
+});
+
+// The three images live outside react-hook-form (see use-card-images.ts), so the form
+// validates a narrower shape and the submit hook merges them back in.
+export const digitalCardFormSchema = digitalCardRequestSchema.omit({
+  iconImage: true,
+  frontImage: true,
+  backImage: true,
 });
 
-// DTO schema extends request schema
 export const digitalCardDtoSchema = digitalCardRequestSchema.extend({
   id: z.string(),
+  userId: z.string(),
+  pinnedAt: z.string().nullable(),
   createdAt: z.string(),
+  updatedAt: z.string(),
 });
 
-// Type exports
 export type DigitalCardRequest = z.infer<typeof digitalCardRequestSchema>;
+export type DigitalCardFormData = z.infer<typeof digitalCardFormSchema>;
 export type DigitalCardDto = z.infer<typeof digitalCardDtoSchema>;
diff --git a/frontend/src/lib/api/schemas/index.ts b/frontend/src/lib/api/schemas/index.ts
index 455fe9c8..11bb4854 100644
--- a/frontend/src/lib/api/schemas/index.ts
+++ b/frontend/src/lib/api/schemas/index.ts
@@ -5,5 +5,6 @@ export * from "@/lib/api/schemas/digital-card";
 export * from "@/lib/api/schemas/shopping-list";
 export * from "@/lib/api/schemas/shopping-list-item";
 export * from "@/lib/api/schemas/preferences";
+export * from "@/lib/api/schemas/store-name";
 export * from "@/lib/api/schemas/notifications";
 export * from "@/lib/api/schemas/watchlist";
diff --git a/frontend/src/lib/api/schemas/store-name.ts b/frontend/src/lib/api/schemas/store-name.ts
new file mode 100644
index 00000000..a9fc8c64
--- /dev/null
+++ b/frontend/src/lib/api/schemas/store-name.ts
@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export const storeNameSuggestionSchema = z.object({
+  name: z.string(),
+  usageCount: z.number().int(),
+});
+
+export type StoreNameSuggestion = z.infer<typeof storeNameSuggestionSchema>;
diff --git a/frontend/src/lib/api/store-names/hooks.ts b/frontend/src/lib/api/store-names/hooks.ts
new file mode 100644
index 00000000..ca437d2f
--- /dev/null
+++ b/frontend/src/lib/api/store-names/hooks.ts
@@ -0,0 +1,14 @@
+import { useQuery } from "@tanstack/react-query";
+
+import { StoreNameSuggestion } from "@/lib/api/types";
+import { getStoreNameSuggestions } from "@/lib/api/store-names/queries";
+
+export function useGetStoreNameSuggestions({
+  enabled = true,
+}: { enabled?: boolean } = {}) {
+  return useQuery<StoreNameSuggestion[], Error>({
+    queryKey: ["storeNames", "suggestions"],
+    queryFn: getStoreNameSuggestions,
+    enabled,
+  });
+}
diff --git a/frontend/src/lib/api/store-names/index.ts b/frontend/src/lib/api/store-names/index.ts
new file mode 100644
index 00000000..b29079a0
--- /dev/null
+++ b/frontend/src/lib/api/store-names/index.ts
@@ -0,0 +1,9 @@
+import * as queries from "@/lib/api/store-names/queries";
+import * as hooks from "@/lib/api/store-names/hooks";
+
+export * from "@/lib/api/store-names/queries";
+export * from "@/lib/api/store-names/hooks";
+
+const storeNameService = { ...queries, ...hooks };
+
+export default storeNameService;
diff --git a/frontend/src/lib/api/store-names/queries.ts b/frontend/src/lib/api/store-names/queries.ts
new file mode 100644
index 00000000..2a259ea6
--- /dev/null
+++ b/frontend/src/lib/api/store-names/queries.ts
@@ -0,0 +1,10 @@
+import apiClient from "@/lib/api/api-base";
+import { StoreNameSuggestion } from "@/lib/api/types";
+
+export async function getStoreNameSuggestions(): Promise<
+  StoreNameSuggestion[]
+> {
+  const response =
+    await apiClient.get<StoreNameSuggestion[]>("/api/store-names");
+  return response.data;
+}
diff --git a/frontend/src/lib/offline/cached-query-keys.ts b/frontend/src/lib/offline/cached-query-keys.ts
index 6b24f7b7..5044941d 100644
--- a/frontend/src/lib/offline/cached-query-keys.ts
+++ b/frontend/src/lib/offline/cached-query-keys.ts
@@ -9,6 +9,7 @@ const PERSISTED_QUERY_KEY_PREFIXES = [
   "shoppingListItems",
   "watchlist",
   "digitalCards",
+  "storeNames", // community store-name suggestions, so the card form works offline
   "pinnedStores",
   "pinnedPlaces",
   "users", // current user profile (["users", "me"])
diff --git a/frontend/src/lib/offline/offline-mutation-keys.ts b/frontend/src/lib/offline/offline-mutation-keys.ts
index d1d8d75e..ad4671ef 100644
--- a/frontend/src/lib/offline/offline-mutation-keys.ts
+++ b/frontend/src/lib/offline/offline-mutation-keys.ts
@@ -11,6 +11,10 @@ export const OFFLINE_MUTATION_KEYS = {
   shoppingListItemDelete: ["shoppingLists", "items", "delete"],
   watchlistAdd: ["watchlist", "add"],
   watchlistRemove: ["watchlist", "remove"],
+  digitalCardCreate: ["digitalCards", "create"],
+  digitalCardUpdate: ["digitalCards", "update"],
+  digitalCardDelete: ["digitalCards", "delete"],
+  digitalCardSetPinned: ["digitalCards", "setPinned"],
 } as const satisfies Record<string, MutationKey>;
 
 const OFFLINE_MUTATION_KEY_HASHES = new Set(
diff --git a/frontend/src/lib/offline/offline-mutations.ts b/frontend/src/lib/offline/offline-mutations.ts
index 0f079875..79ec7af2 100644
--- a/frontend/src/lib/offline/offline-mutations.ts
+++ b/frontend/src/lib/offline/offline-mutations.ts
@@ -9,14 +9,22 @@ import {
   deleteShoppingListItem,
 } from "@/lib/api/shopping-lists";
 import { addToWatchlist, removeFromWatchlist } from "@/lib/api/watchlist";
+import {
+  createDigitalCard,
+  updateDigitalCard,
+  deleteDigitalCard,
+  setDigitalCardPinned,
+} from "@/lib/api/digital-cards";
 import type {
   ShoppingListRequest,
   ShoppingListItemRequest,
   WatchlistItemRequest,
+  DigitalCardRequest,
 } from "@/lib/api/types";
 import { OFFLINE_MUTATION_KEYS } from "@/lib/offline/offline-mutation-keys";
 
 const SHOPPING_LISTS_ME: QueryKey = ["shoppingLists", "me"];
+const DIGITAL_CARDS_ME: QueryKey = ["digitalCards", "me"];
 
 function listAndItemsKeys(listId: string): QueryKey[] {
   return [
@@ -101,4 +109,30 @@ export function registerOfflineMutationDefaults(queryClient: QueryClient) {
     (id: string) => removeFromWatchlist(id),
     () => [["watchlist"]],
   );
+
+  defineOfflineMutation(
+    OFFLINE_MUTATION_KEYS.digitalCardCreate,
+    (data: DigitalCardRequest) => createDigitalCard(data),
+    () => [DIGITAL_CARDS_ME],
+  );
+
+  defineOfflineMutation(
+    OFFLINE_MUTATION_KEYS.digitalCardUpdate,
+    ({ id, data }: { id: string; data: DigitalCardRequest }) =>
+      updateDigitalCard(id, data),
+    () => [DIGITAL_CARDS_ME],
+  );
+
+  defineOfflineMutation(
+    OFFLINE_MUTATION_KEYS.digitalCardDelete,
+    (id: string) => deleteDigitalCard(id),
+    () => [DIGITAL_CARDS_ME],
+  );
+
+  defineOfflineMutation(
+    OFFLINE_MUTATION_KEYS.digitalCardSetPinned,
+    ({ id, pinned }: { id: string; pinned: boolean }) =>
+      setDigitalCardPinned(id, pinned),
+    () => [DIGITAL_CARDS_ME],
+  );
 }

From 0a0c992c62f8692ed1210b8cd9089170a8bbcf2d Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Thu, 30 Jul 2026 10:53:48 +0200
Subject: [PATCH 05/14] feat(digital-cards): Add code, colour and icon
 rendering primitives

Changes:
- Map stored code types onto bwip-js encoders and Croatian labels
- Add generateCodeSvg, returning a result object rather than throwing
- Add the card colour system: swatches, a locked hue scale, chain brand colours, hue sort
- Add the six sort comparators with a pinned split and a Croatian tie break
- Add dominant colour extraction from an uploaded image
- Add CardCode and CardIcon, the two shared render pieces

Colour is locked to one saturation and lightness pair, so every hue a user can
reach stays legible under white text and the wallet reads as one designed set.

Notes:
- bwip-js does NOT tree shake. BWIPP is one generated blob, so importing thirteen
  encoders costs the same as importing all hundred: 844 KB raw, 210 KB gzipped,
  verified by finding unimported symbologies in the output. Webpack scopes it to
  the digital-cards route chunk, so no other page pays for it, and generateCodeSvg
  stays synchronous because a lazy import would only move the same download behind
  a loading state on a page where every tile draws a code.
- Codabar's export is rationalizedCodabar, and bcid must be the bwip name rather
  than the scanner's format string. Both were wrong first time round.
- includetext is off and the value line is our own HTML, which keeps user input out
  of the SVG string the panel injects.
- CardIcon resolves the chain logo at render time instead of copying it into the
  card, so it never goes stale and costs nothing in the payload or the offline cache.
- Greys sort last: hueFromHex reports them as neutral rather than as red.
---
 .../digital-cards/components/card-code.tsx    |  54 ++++++++
 .../digital-cards/components/card-icon.tsx    |  62 ++++++++++
 .../(user)/digital-cards/utils/card-colors.ts | 115 ++++++++++++++++++
 .../(user)/digital-cards/utils/card-labels.ts |  30 +++++
 .../digital-cards/utils/card-sorting.ts       |  96 +++++++++++++++
 .../digital-cards/utils/code-symbologies.ts   |  91 ++++++++++++++
 .../digital-cards/utils/generate-code-svg.ts  |  93 ++++++++++++++
 .../utils/browser/extract-dominant-color.ts   |  75 ++++++++++++
 8 files changed, 616 insertions(+)
 create mode 100644 frontend/src/app/(user)/digital-cards/components/card-code.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/card-icon.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/utils/card-colors.ts
 create mode 100644 frontend/src/app/(user)/digital-cards/utils/card-labels.ts
 create mode 100644 frontend/src/app/(user)/digital-cards/utils/card-sorting.ts
 create mode 100644 frontend/src/app/(user)/digital-cards/utils/code-symbologies.ts
 create mode 100644 frontend/src/app/(user)/digital-cards/utils/generate-code-svg.ts
 create mode 100644 frontend/src/utils/browser/extract-dominant-color.ts

diff --git a/frontend/src/app/(user)/digital-cards/components/card-code.tsx b/frontend/src/app/(user)/digital-cards/components/card-code.tsx
new file mode 100644
index 00000000..84f10109
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/card-code.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import { useMemo } from "react";
+
+import { cn } from "@/lib/utils";
+import type { CodeType } from "@/constants/card-codes";
+import { generateCodeSvg } from "@/app/(user)/digital-cards/utils/generate-code-svg";
+
+interface ICardCodeProps {
+  codeValue: string;
+  codeType: CodeType;
+  /** Shows the value under the code, which the checkout view wants and a tile does not. */
+  showValue?: boolean;
+  className?: string;
+}
+
+/**
+ * Renders the barcode or QR, or the plain value when the symbology cannot encode it. The
+ * fallback is a feature, not an error path: a membership number with no barcode is still a
+ * usable card, and the cashier can key it in.
+ */
+export default function CardCode({
+  codeValue,
+  codeType,
+  showValue = false,
+  className,
+}: ICardCodeProps) {
+  const result = useMemo(
+    () => generateCodeSvg(codeValue, codeType),
+    [codeValue, codeType],
+  );
+
+  return (
+    <div className={cn("flex w-full flex-col items-center gap-2", className)}>
+      {result.ok ? (
+        <div
+          className="w-full [&>svg]:h-auto [&>svg]:w-full"
+          // Safe by construction: includetext is off, so no user text reaches the SVG.
+          dangerouslySetInnerHTML={{ __html: result.svg }}
+        />
+      ) : (
+        <p className="w-full break-all text-center text-xl font-semibold tracking-widest tabular-nums text-black">
+          {codeValue}
+        </p>
+      )}
+
+      {showValue && result.ok && (
+        <p className="w-full break-all text-center text-sm tracking-wider tabular-nums text-black">
+          {codeValue}
+        </p>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/card-icon.tsx b/frontend/src/app/(user)/digital-cards/components/card-icon.tsx
new file mode 100644
index 00000000..e0c3bbac
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/card-icon.tsx
@@ -0,0 +1,62 @@
+"use client";
+
+import { CreditCard } from "lucide-react";
+
+import StoreChainLogo from "@/components/custom/store-chain/store-chain-logo";
+import { cn } from "@/lib/utils";
+import { getStoreInitials } from "@/app/(user)/digital-cards/utils/card-labels";
+
+interface ICardIconProps {
+  iconImage: string | null;
+  chainCode: string | null;
+  storeName: string;
+  className?: string;
+}
+
+/**
+ * The icon is resolved at render time rather than copied into the card on save: an official
+ * chain's logo stays current when the asset changes, and costs nothing in the payload.
+ */
+export default function CardIcon({
+  iconImage,
+  chainCode,
+  storeName,
+  className,
+}: ICardIconProps) {
+  const shell = cn(
+    "relative grid size-full place-items-center overflow-hidden rounded-full bg-white",
+    className,
+  );
+
+  if (iconImage) {
+    return (
+      <div className={shell}>
+        {/* A data URI, so next/image would only add a proxy hop. */}
+        <img src={iconImage} alt="" className="size-full object-contain p-1" />
+      </div>
+    );
+  }
+
+  if (chainCode) {
+    return (
+      <div className={shell}>
+        <StoreChainLogo chain={chainCode} fill sizes="96px" />
+      </div>
+    );
+  }
+
+  return (
+    <div className={shell}>
+      {storeName.trim() ? (
+        <span
+          aria-hidden="true"
+          className="text-lg font-semibold text-slate-700"
+        >
+          {getStoreInitials(storeName)}
+        </span>
+      ) : (
+        <CreditCard aria-hidden="true" className="size-1/2 text-slate-400" />
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/utils/card-colors.ts b/frontend/src/app/(user)/digital-cards/utils/card-colors.ts
new file mode 100644
index 00000000..8e3277ca
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/utils/card-colors.ts
@@ -0,0 +1,115 @@
+/**
+ * Card colours are locked to one saturation and lightness pair, so every hue the user can
+ * reach stays legible under white text and the wallet reads as one designed set. The hue
+ * slider and the swatches are therefore the same system: a swatch is just a hue stop.
+ */
+const CARD_SATURATION = 62;
+const CARD_LIGHTNESS = 42;
+
+export const DEFAULT_CARD_COLOR = "#64748b";
+
+// Neutrals cannot come from the hue formula, so they are listed as literals and sort last.
+export const NEUTRAL_CARD_COLORS = [
+  DEFAULT_CARD_COLOR,
+  "#334155",
+  "#1f2937",
+] as const;
+
+const SWATCH_HUES = [0, 20, 40, 55, 90, 150, 175, 200, 225, 265, 300, 330];
+
+export function hslToHex(hue: number, saturation: number, lightness: number) {
+  const l = lightness / 100;
+  const chroma = (1 - Math.abs(2 * l - 1)) * (saturation / 100);
+
+  const channel = (offset: number) => {
+    const k = (offset + hue / 30) % 12;
+    const value = l - (chroma / 2) * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+
+    return Math.round(255 * value)
+      .toString(16)
+      .padStart(2, "0");
+  };
+
+  return `#${channel(0)}${channel(8)}${channel(4)}`;
+}
+
+/** The hex a given hue produces, which is what both the slider and the swatches emit. */
+export function hexForHue(hue: number): string {
+  return hslToHex(hue, CARD_SATURATION, CARD_LIGHTNESS);
+}
+
+export const CARD_SWATCHES: string[] = [
+  ...SWATCH_HUES.map(hexForHue),
+  ...NEUTRAL_CARD_COLORS,
+];
+
+export function hexToRgb(hex: string): [number, number, number] {
+  const normalized = hex.replace("#", "");
+
+  return [
+    parseInt(normalized.slice(0, 2), 16),
+    parseInt(normalized.slice(2, 4), 16),
+    parseInt(normalized.slice(4, 6), 16),
+  ];
+}
+
+export interface IHueInfo {
+  hue: number;
+  /** Below this, a colour is a grey and has no meaningful hue to sort by. */
+  isNeutral: boolean;
+}
+
+export function hueFromHex(hex: string): IHueInfo {
+  const [r, g, b] = hexToRgb(hex).map((channel) => channel / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+
+  if (delta < 0.08) return { hue: 0, isNeutral: true };
+
+  let hue: number;
+  if (max === r) hue = ((g - b) / delta) % 6;
+  else if (max === g) hue = (b - r) / delta + 2;
+  else hue = (r - g) / delta + 4;
+
+  hue = Math.round(hue * 60);
+
+  return { hue: hue < 0 ? hue + 360 : hue, isNeutral: false };
+}
+
+/**
+ * Curated brand colours for the official chains, used to prefill a new card's colour.
+ * Deliberately hand-picked rather than sampled from the logo PNGs: several logos are
+ * mostly white, and a few brand reds are too light to carry white text.
+ */
+export const CHAIN_BRAND_COLORS: Record<string, string> = {
+  konzum: "#c8102e",
+  lidl: "#0050aa",
+  plodine: "#e2001a",
+  tommy: "#d81f26",
+  spar: "#007a33",
+  kaufland: "#e10915",
+  studenac: "#0a5c36",
+  eurospin: "#f47b20",
+  dm: "#00589c",
+  metro: "#003d7c",
+  ktc: "#0a6ebd",
+  ntl: "#1b5e20",
+  ribola: "#0072bc",
+  boso: "#c62828",
+  bure: "#8d6e63",
+  vrutak: "#2e7d32",
+  zabac: "#43a047",
+  roto: "#1565c0",
+  branka: "#ad1457",
+  brodokomerc: "#00695c",
+  gavranovic: "#b71c1c",
+  jadranka_trgovina: "#0277bd",
+  lorenco: "#6a1b9a",
+  stanic: "#37474f",
+  stridon: "#455a64",
+  trgocentar: "#ef6c00",
+  "trgovina-krk": "#0288d1",
+  djelo_vodice: "#00838f",
+  dukat: "#1976d2",
+};
diff --git a/frontend/src/app/(user)/digital-cards/utils/card-labels.ts b/frontend/src/app/(user)/digital-cards/utils/card-labels.ts
new file mode 100644
index 00000000..a62e239a
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/utils/card-labels.ts
@@ -0,0 +1,30 @@
+import type { CardType } from "@/constants/card-codes";
+
+const CARD_TYPE_LABELS: Record<CardType, string> = {
+  loyalty: "Kartica vjernosti",
+  gift: "Poklon kartica",
+  membership: "Članska kartica",
+  other: "Ostalo",
+};
+
+export function getCardTypeLabel(cardType: CardType): string {
+  return CARD_TYPE_LABELS[cardType];
+}
+
+export function getCardTypeOptions(): { value: CardType; label: string }[] {
+  return (Object.keys(CARD_TYPE_LABELS) as CardType[]).map((value) => ({
+    value,
+    label: CARD_TYPE_LABELS[value],
+  }));
+}
+
+/** Up to two letters, so a card with no icon and no chain logo still reads as itself. */
+export function getStoreInitials(storeName: string): string {
+  const words = storeName.trim().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return "?";
+
+  const initials =
+    words.length === 1 ? words[0].slice(0, 2) : `${words[0][0]}${words[1][0]}`;
+
+  return initials.toUpperCase();
+}
diff --git a/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts b/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts
new file mode 100644
index 00000000..47536f06
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts
@@ -0,0 +1,96 @@
+import type { DigitalCardDto } from "@/lib/api/types";
+import { compareHr } from "@/utils/strings";
+import type { CardType } from "@/constants/card-codes";
+import { hueFromHex } from "@/app/(user)/digital-cards/utils/card-colors";
+import { getCardTypeLabel } from "@/app/(user)/digital-cards/utils/card-labels";
+
+export const CARD_SORT_MODES = [
+  "cardName",
+  "storeName",
+  "cardType",
+  "updatedAt",
+  "createdAt",
+  "cardColor",
+] as const;
+
+export type CardSortMode = (typeof CARD_SORT_MODES)[number];
+
+export const DEFAULT_CARD_SORT: CardSortMode = "updatedAt";
+
+export function isCardSortMode(value: unknown): value is CardSortMode {
+  return (
+    typeof value === "string" &&
+    (CARD_SORT_MODES as readonly string[]).includes(value)
+  );
+}
+
+export const CARD_SORT_LABELS: Record<CardSortMode, string> = {
+  cardName: "Naziv kartice",
+  storeName: "Trgovina",
+  cardType: "Tip kartice",
+  updatedAt: "Nedavno uređeno",
+  createdAt: "Nedavno dodano",
+  cardColor: "Boja",
+};
+
+function byNewestFirst(a: string, b: string): number {
+  return b.localeCompare(a);
+}
+
+/** Greys have no hue, so they collect at the end instead of landing on red. */
+function compareColor(a: string, b: string): number {
+  const left = hueFromHex(a);
+  const right = hueFromHex(b);
+
+  if (left.isNeutral !== right.isNeutral) return left.isNeutral ? 1 : -1;
+  if (left.isNeutral && right.isNeutral) return a.localeCompare(b);
+  if (left.hue !== right.hue) return left.hue - right.hue;
+
+  // Same hue, different shade: keep identical colours adjacent.
+  return a.localeCompare(b);
+}
+
+function compareBy(mode: CardSortMode) {
+  return (a: DigitalCardDto, b: DigitalCardDto): number => {
+    switch (mode) {
+      case "cardName":
+        return compareHr(a.cardName, b.cardName);
+      case "storeName":
+        return compareHr(a.storeName, b.storeName);
+      case "cardType":
+        return compareHr(
+          getCardTypeLabel(a.cardType as CardType),
+          getCardTypeLabel(b.cardType as CardType),
+        );
+      case "updatedAt":
+        return byNewestFirst(a.updatedAt, b.updatedAt);
+      case "createdAt":
+        return byNewestFirst(a.createdAt, b.createdAt);
+      case "cardColor":
+        return compareColor(a.cardColor, b.cardColor);
+    }
+  };
+}
+
+export interface ISortedCardGroups {
+  pinned: DigitalCardDto[];
+  rest: DigitalCardDto[];
+}
+
+/**
+ * Pinned cards keep their own group at the top, but they are sorted by the same mode as
+ * the rest, so the chosen order still means something inside it.
+ */
+export function groupAndSortCards(
+  cards: DigitalCardDto[],
+  mode: CardSortMode,
+): ISortedCardGroups {
+  const compare = compareBy(mode);
+  const withTieBreak = (a: DigitalCardDto, b: DigitalCardDto) =>
+    compare(a, b) || compareHr(a.cardName, b.cardName);
+
+  return {
+    pinned: cards.filter((card) => card.pinnedAt).sort(withTieBreak),
+    rest: cards.filter((card) => !card.pinnedAt).sort(withTieBreak),
+  };
+}
diff --git a/frontend/src/app/(user)/digital-cards/utils/code-symbologies.ts b/frontend/src/app/(user)/digital-cards/utils/code-symbologies.ts
new file mode 100644
index 00000000..fe27ac33
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/utils/code-symbologies.ts
@@ -0,0 +1,91 @@
+import { CODE_TYPES, type CodeType } from "@/constants/card-codes";
+
+/**
+ * Barcode Detection API format name to the bwip-js encoder name. The scanner speaks the
+ * former and bwip-js the latter, so this map is the only place the two vocabularies meet.
+ */
+export const CODE_TYPE_TO_BCID: Record<Exclude<CodeType, "unknown">, string> = {
+  ean_13: "ean13",
+  ean_8: "ean8",
+  upc_a: "upca",
+  upc_e: "upce",
+  code_128: "code128",
+  code_39: "code39",
+  code_93: "code93",
+  itf: "interleaved2of5",
+  codabar: "codabar",
+  qr_code: "qrcode",
+  data_matrix: "datamatrix",
+  pdf417: "pdf417",
+  aztec: "azteccode",
+};
+
+const CODE_TYPE_LABELS: Record<CodeType, string> = {
+  ean_13: "EAN-13",
+  ean_8: "EAN-8",
+  upc_a: "UPC-A",
+  upc_e: "UPC-E",
+  code_128: "Code 128",
+  code_39: "Code 39",
+  code_93: "Code 93",
+  itf: "ITF (Interleaved 2 of 5)",
+  codabar: "Codabar",
+  qr_code: "QR kod",
+  data_matrix: "Data Matrix",
+  pdf417: "PDF417",
+  aztec: "Aztec",
+  unknown: "Samo broj/tekst",
+};
+
+// The handful worth surfacing first: what Croatian loyalty cards actually carry.
+const COMMON_CODE_TYPES: CodeType[] = [
+  "ean_13",
+  "ean_8",
+  "code_128",
+  "code_39",
+  "qr_code",
+  "upc_a",
+];
+
+export function getCodeTypeLabel(codeType: CodeType): string {
+  return CODE_TYPE_LABELS[codeType];
+}
+
+export interface ICodeTypeGroup {
+  label: string;
+  options: { value: CodeType; label: string }[];
+}
+
+/**
+ * One grouped list rather than a curated subset, so a scan that returns an unusual
+ * format still has a matching option instead of being silently dropped.
+ */
+export function getCodeTypeGroups(): ICodeTypeGroup[] {
+  const rest = CODE_TYPES.filter((type) => !COMMON_CODE_TYPES.includes(type));
+
+  return [
+    {
+      label: "Uobičajeni",
+      options: COMMON_CODE_TYPES.map((value) => ({
+        value,
+        label: CODE_TYPE_LABELS[value],
+      })),
+    },
+    {
+      label: "Ostali",
+      options: rest.map((value) => ({
+        value,
+        label: CODE_TYPE_LABELS[value],
+      })),
+    },
+  ];
+}
+
+/** Narrows an arbitrary scanner format string onto our stored vocabulary. */
+export function toCodeType(format: string | undefined): CodeType {
+  if (!format) return "unknown";
+
+  return (CODE_TYPES as readonly string[]).includes(format)
+    ? (format as CodeType)
+    : "unknown";
+}
diff --git a/frontend/src/app/(user)/digital-cards/utils/generate-code-svg.ts b/frontend/src/app/(user)/digital-cards/utils/generate-code-svg.ts
new file mode 100644
index 00000000..7313794e
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/utils/generate-code-svg.ts
@@ -0,0 +1,93 @@
+import {
+  drawingSVG,
+  ean13,
+  ean8,
+  upca,
+  upce,
+  code128,
+  code39,
+  code93,
+  interleaved2of5,
+  rationalizedCodabar,
+  qrcode,
+  datamatrix,
+  pdf417,
+  azteccode,
+  type RenderOptions,
+} from "@bwip-js/browser";
+
+import type { CodeType } from "@/constants/card-codes";
+import { CODE_TYPE_TO_BCID } from "@/app/(user)/digital-cards/utils/code-symbologies";
+
+type Encoder = (opts: RenderOptions, drawing: unknown) => string;
+
+// Named imports do NOT tree-shake: BWIPP is one generated blob, so any single encoder pulls
+// the whole table (measured at 844 KB raw, 210 KB gzipped). Webpack keeps that in the
+// digital-cards route chunk rather than a shared one, so no other page pays for it.
+// Kept synchronous on purpose: every card tile renders a code, so a lazy import would only
+// move the same download behind a loading state.
+const ENCODERS: Record<Exclude<CodeType, "unknown">, Encoder> = {
+  ean_13: ean13 as Encoder,
+  ean_8: ean8 as Encoder,
+  upc_a: upca as Encoder,
+  upc_e: upce as Encoder,
+  code_128: code128 as Encoder,
+  code_39: code39 as Encoder,
+  code_93: code93 as Encoder,
+  itf: interleaved2of5 as Encoder,
+  codabar: rationalizedCodabar as Encoder,
+  qr_code: qrcode as Encoder,
+  data_matrix: datamatrix as Encoder,
+  pdf417: pdf417 as Encoder,
+  aztec: azteccode as Encoder,
+};
+
+export type CodeSvgResult =
+  { ok: true; svg: string } | { ok: false; reason: "unsupported" | "invalid" };
+
+const TWO_DIMENSIONAL: CodeType[] = [
+  "qr_code",
+  "data_matrix",
+  "pdf417",
+  "aztec",
+];
+
+export function isTwoDimensional(codeType: CodeType): boolean {
+  return TWO_DIMENSIONAL.includes(codeType);
+}
+
+/**
+ * Never throws: bwip-js rejects a value that does not fit its symbology (an EAN-13 needs
+ * twelve digits), and the caller renders the plain value instead of a broken code.
+ */
+export function generateCodeSvg(
+  codeValue: string,
+  codeType: CodeType,
+): CodeSvgResult {
+  if (codeType === "unknown") return { ok: false, reason: "unsupported" };
+
+  const value = codeValue.trim();
+  if (!value) return { ok: false, reason: "invalid" };
+
+  try {
+    // includetext stays off so the human-readable line is our own HTML: it keeps user
+    // input out of the SVG string that the code panel injects.
+    const options: RenderOptions = {
+      bcid: CODE_TYPE_TO_BCID[codeType],
+      text: value,
+      includetext: false,
+      scale: 3,
+      paddingwidth: 0,
+      paddingheight: 0,
+    };
+
+    // A 2D symbology sizes itself; height on a 1D one is the bar height in millimetres.
+    if (!isTwoDimensional(codeType)) options.height = 14;
+
+    const svg = ENCODERS[codeType](options, drawingSVG());
+
+    return { ok: true, svg };
+  } catch {
+    return { ok: false, reason: "invalid" };
+  }
+}
diff --git a/frontend/src/utils/browser/extract-dominant-color.ts b/frontend/src/utils/browser/extract-dominant-color.ts
new file mode 100644
index 00000000..9d622acd
--- /dev/null
+++ b/frontend/src/utils/browser/extract-dominant-color.ts
@@ -0,0 +1,75 @@
+import {
+  hexForHue,
+  hueFromHex,
+} from "@/app/(user)/digital-cards/utils/card-colors";
+
+const SAMPLE_SIZE = 48;
+
+/**
+ * Best-effort dominant hue of an image, used to prefill a card's colour from its logo or
+ * photo. Returns null rather than guessing badly, and the caller keeps the current colour.
+ *
+ * Near-white, near-black and washed-out pixels are skipped: a card photo is mostly plastic
+ * whitespace, and letting that win would make every suggestion grey.
+ */
+export default async function extractDominantColor(
+  source: Blob,
+): Promise<string | null> {
+  try {
+    const bitmap = await createImageBitmap(source);
+    const canvas = document.createElement("canvas");
+    canvas.width = SAMPLE_SIZE;
+    canvas.height = SAMPLE_SIZE;
+
+    const context = canvas.getContext("2d", { willReadFrequently: true });
+    if (!context) return null;
+
+    context.drawImage(bitmap, 0, 0, SAMPLE_SIZE, SAMPLE_SIZE);
+    bitmap.close();
+
+    const { data } = context.getImageData(0, 0, SAMPLE_SIZE, SAMPLE_SIZE);
+    const buckets = new Map<number, number>();
+    const centre = SAMPLE_SIZE / 2;
+
+    for (let index = 0; index < data.length; index += 4) {
+      const [r, g, b, alpha] = [
+        data[index],
+        data[index + 1],
+        data[index + 2],
+        data[index + 3],
+      ];
+      if (alpha < 200) continue;
+
+      const max = Math.max(r, g, b);
+      const min = Math.min(r, g, b);
+      if (max > 240 || max < 24 || max - min < 28) continue;
+
+      const hex = `#${[r, g, b]
+        .map((channel) => channel.toString(16).padStart(2, "0"))
+        .join("")}`;
+      const { hue, isNeutral } = hueFromHex(hex);
+      if (isNeutral) continue;
+
+      // Weight the middle of the frame, where a logo usually sits.
+      const pixel = index / 4;
+      const x = pixel % SAMPLE_SIZE;
+      const y = Math.floor(pixel / SAMPLE_SIZE);
+      const distance = Math.hypot(x - centre, y - centre) / centre;
+      const weight = 1 + (1 - Math.min(distance, 1));
+
+      // 15 degree buckets, so one gradient does not split across many hues.
+      const bucket = Math.round(hue / 15) % 24;
+      buckets.set(bucket, (buckets.get(bucket) ?? 0) + weight);
+    }
+
+    if (buckets.size === 0) return null;
+
+    const [dominant] = [...buckets.entries()].sort((a, b) => b[1] - a[1])[0];
+
+    // Snap onto the card palette's fixed saturation and lightness, so an extracted colour
+    // is indistinguishable from a picked one and still passes contrast.
+    return hexForHue(dominant * 15);
+  } catch {
+    return null;
+  }
+}

From aa290408f9bb2b602c391b9748f3cdd8500155c3 Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Thu, 30 Jul 2026 10:54:15 +0200
Subject: [PATCH 06/14] feat(digital-cards): Add the card form and checkout
 modals

Changes:
- Register digital-card as a URL driven modal with new, edit and view actions
- Add the create and edit form: name, store autocomplete, type, code, colour, images, note
- Add scan to fill, which sets both the code and its detected type
- Add a live code preview that warns when the chosen symbology cannot encode the value
- Add three colour picker variants behind a temporary switcher
- Add the checkout modal: large high contrast code, card faces, pin, edit, delete
- Add useWakeLock, holding the screen on while a code is displayed

The two modals ship together because the entity outlet renders both, so splitting
them would leave it importing a module that does not exist yet.

Notes:
- View pushes to edit rather than swapping, so cancelling lands back on the card
  instead of the page, which is what closeModalUrl's history.back gives for free.
- The store field sets chainCode alongside storeName for an official chain and
  nulls it for free text, which is what gates the logo and the brand colour.
- Colour is suggested from the chain, then from an uploaded image, but only while
  the user has not touched the picker. A manual pick wins permanently.
- Images sit outside react-hook-form with their own dirty flag, folded into the
  shell's indicator. Drafts exclude the card code, so a number never reaches disk.
- Cards are read from the /me list rather than a by id endpoint, which is what makes
  a deep link work offline, and useCardImages adjusts state during render like
  use-lingering-target does, so an arriving card cannot flash the previous one's images.
- The picker switcher is deliberately temporary: two variants and the switcher get
  deleted once one is chosen.
---
 .../components/forms/card-image-slot.tsx      | 101 ++++++++++++
 .../components/forms/card-images-field.tsx    |  64 +++++++
 .../components/forms/card-name-field.tsx      |  33 ++++
 ...d-select-field.tsx => card-type-field.tsx} |  26 +--
 .../components/forms/code-field.tsx           |  82 +++++++++
 .../components/forms/code-preview.tsx         |  56 +++++++
 .../components/forms/code-type-field.tsx      |  63 +++++++
 .../forms/color-picker/card-color-field.tsx   |  64 +++++++
 .../color-picker/color-picker-honeycomb.tsx   |  97 +++++++++++
 .../color-picker-swatch-slider.tsx            |  25 +++
 .../color-picker/color-picker-swatches.tsx    |  50 ++++++
 .../color-picker/color-picker-switcher.tsx    |  46 ++++++
 .../forms/color-picker/hue-slider.tsx         |  40 +++++
 .../components/forms/digital-card-fields.tsx  | 123 --------------
 .../components/forms/digital-card-modal.tsx   | 156 ++++++++++++------
 .../components/forms/note-field.tsx           |  39 +++++
 .../components/forms/store-name-field.tsx     | 141 ++++++++++++++++
 .../components/forms/store-name-option.tsx    |  37 +++++
 .../components/forms/store-name-trigger.tsx   |  68 ++++++++
 .../components/pin-toggle-button.tsx          |  58 +++++++
 .../components/view/card-code-panel.tsx       |  50 ++++++
 .../components/view/card-detail-rows.tsx      |  35 ++++
 .../components/view/card-face-images.tsx      |  67 ++++++++
 .../components/view/card-view-actions.tsx     |  93 +++++++++++
 .../view/digital-card-view-modal.tsx          |  82 +++++++++
 .../digital-cards/hooks/use-card-images.ts    |  60 +++++++
 .../hooks/use-digital-card-modal.ts           |   8 +-
 .../digital-cards/hooks/use-digital-card.ts   |  33 ++++
 .../hooks/use-store-name-options.ts           |  58 +++++++
 .../modal-router/entity-modal-outlet.tsx      |  25 ++-
 frontend/src/hooks/use-wake-lock.ts           |  53 ++++++
 frontend/src/lib/modal/modal-registry.ts      |   5 +
 32 files changed, 1740 insertions(+), 198 deletions(-)
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/card-images-field.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/card-name-field.tsx
 rename frontend/src/app/(user)/digital-cards/components/forms/{digital-card-select-field.tsx => card-type-field.tsx} (64%)
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/code-field.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/code-preview.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/code-type-field.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/color-picker/card-color-field.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-honeycomb.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatch-slider.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatches.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-switcher.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/color-picker/hue-slider.tsx
 delete mode 100644 frontend/src/app/(user)/digital-cards/components/forms/digital-card-fields.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/note-field.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/store-name-field.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/store-name-option.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/forms/store-name-trigger.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/pin-toggle-button.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/view/card-detail-rows.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/view/card-face-images.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/view/card-view-actions.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/view/digital-card-view-modal.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/hooks/use-card-images.ts
 create mode 100644 frontend/src/app/(user)/digital-cards/hooks/use-digital-card.ts
 create mode 100644 frontend/src/app/(user)/digital-cards/hooks/use-store-name-options.ts
 create mode 100644 frontend/src/hooks/use-wake-lock.ts

diff --git a/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx b/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx
new file mode 100644
index 00000000..ef446ccd
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx
@@ -0,0 +1,101 @@
+"use client";
+
+import { ChangeEvent, useId } from "react";
+import { Camera } from "lucide-react";
+import { toast } from "sonner";
+
+import { cn } from "@/lib/utils";
+import resizeImageToWebp from "@/utils/browser/image";
+
+// Only guards decoding: the WebP re-encode below sets the stored size.
+const MAX_SOURCE_BYTES = 15 * 1024 * 1024;
+
+interface ICardImageSlotProps {
+  label: string;
+  value: string | null;
+  /** Long edge in pixels after the WebP re-encode. */
+  maxSize: number;
+  /** Character cap the backend enforces on the data URI. */
+  maxLength: number;
+  onChange: (value: string | null) => void;
+  onPicked?: (file: File) => void;
+  className?: string;
+}
+
+export default function CardImageSlot({
+  label,
+  value,
+  maxSize,
+  maxLength,
+  onChange,
+  onPicked,
+  className,
+}: ICardImageSlotProps) {
+  const inputId = useId();
+
+  async function handleChange(event: ChangeEvent<HTMLInputElement>) {
+    const file = event.target.files?.[0];
+    if (!file) return;
+
+    if (file.size > MAX_SOURCE_BYTES) {
+      toast.error("Slika je prevelika. Maksimalna veličina je 15 MB.");
+      return;
+    }
+
+    try {
+      const encoded = await resizeImageToWebp(file, maxSize);
+
+      // Catches the doomed request before it is sent: @Size counts characters and a data
+      // URI is ASCII, so the cap the backend applies is the same number.
+      if (encoded.length > maxLength) {
+        toast.error("Slika je prevelika, pokušaj s manjom fotografijom.");
+        return;
+      }
+
+      onChange(encoded);
+      onPicked?.(file);
+    } catch {
+      toast.error("Sliku nije moguće učitati, probaj JPG ili PNG.");
+    }
+  }
+
+  return (
+    <div className={cn("flex flex-col items-center gap-1", className)}>
+      <input
+        type="file"
+        accept="image/*"
+        onChange={handleChange}
+        className="hidden"
+        id={inputId}
+      />
+
+      <label
+        htmlFor={inputId}
+        aria-label={value ? `Promijeni ${label}` : `Dodaj ${label}`}
+        className="relative block aspect-3/2 w-full cursor-pointer overflow-hidden rounded-md border border-dashed bg-muted/40 transition hover:border-primary"
+      >
+        {value ? (
+          // A data URI, so next/image would only add a proxy hop.
+          // eslint-disable-next-line @next/next/no-img-element
+          <img src={value} alt="" className="size-full object-cover" />
+        ) : (
+          <span className="grid size-full place-items-center text-muted-foreground">
+            <Camera aria-hidden="true" className="size-5" />
+          </span>
+        )}
+      </label>
+
+      <span className="text-xs text-muted-foreground">{label}</span>
+
+      {value && (
+        <button
+          type="button"
+          onClick={() => onChange(null)}
+          className="cursor-pointer text-xs text-muted-foreground underline underline-offset-2 hover:text-destructive"
+        >
+          Ukloni
+        </button>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/card-images-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/card-images-field.tsx
new file mode 100644
index 00000000..3a141de6
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/card-images-field.tsx
@@ -0,0 +1,64 @@
+"use client";
+
+import CardImageSlot from "@/app/(user)/digital-cards/components/forms/card-image-slot";
+import type {
+  CardImageSlot as SlotName,
+  ICardImages,
+} from "@/app/(user)/digital-cards/hooks/use-card-images";
+
+interface ICardImagesFieldProps {
+  images: ICardImages;
+  onImageChange: (slot: SlotName, value: string | null) => void;
+  /** Fires for the icon and front slots, which can suggest the card's colour. */
+  onColorSource: (file: File) => void;
+}
+
+// The icon is a small medallion, so 256px is plenty. The card faces are the backup a
+// cashier reads off the screen, so they get four times the detail.
+const ICON_MAX_SIZE = 256;
+const FACE_MAX_SIZE = 1024;
+const ICON_MAX_LENGTH = 400_000;
+const FACE_MAX_LENGTH = 1_200_000;
+
+export default function CardImagesField({
+  images,
+  onImageChange,
+  onColorSource,
+}: ICardImagesFieldProps) {
+  return (
+    <div className="space-y-2">
+      <p className="text-sm font-medium">Slike kartice</p>
+
+      <div className="grid grid-cols-3 gap-3">
+        <CardImageSlot
+          label="Ikona"
+          value={images.iconImage}
+          maxSize={ICON_MAX_SIZE}
+          maxLength={ICON_MAX_LENGTH}
+          onChange={(value) => onImageChange("iconImage", value)}
+          onPicked={onColorSource}
+        />
+        <CardImageSlot
+          label="Prednja strana"
+          value={images.frontImage}
+          maxSize={FACE_MAX_SIZE}
+          maxLength={FACE_MAX_LENGTH}
+          onChange={(value) => onImageChange("frontImage", value)}
+          onPicked={onColorSource}
+        />
+        <CardImageSlot
+          label="Stražnja strana"
+          value={images.backImage}
+          maxSize={FACE_MAX_SIZE}
+          maxLength={FACE_MAX_LENGTH}
+          onChange={(value) => onImageChange("backImage", value)}
+        />
+      </div>
+
+      <p className="text-xs text-muted-foreground">
+        Slike prednje i stražnje strane su rezerva ako kod ne proradi na
+        blagajni.
+      </p>
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/card-name-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/card-name-field.tsx
new file mode 100644
index 00000000..edef4737
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/card-name-field.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+import { useFormContext } from "react-hook-form";
+
+import {
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
+import type { DigitalCardFormData } from "@/lib/api/types";
+
+export default function CardNameField() {
+  const form = useFormContext<DigitalCardFormData>();
+
+  return (
+    <FormField
+      control={form.control}
+      name="cardName"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>Naziv kartice</FormLabel>
+          <FormControl>
+            <Input {...field} autoFocus placeholder="npr. Konzum Multiplus" />
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-select-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/card-type-field.tsx
similarity index 64%
rename from frontend/src/app/(user)/digital-cards/components/forms/digital-card-select-field.tsx
rename to frontend/src/app/(user)/digital-cards/components/forms/card-type-field.tsx
index db8ef910..8edec43e 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-select-field.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/card-type-field.tsx
@@ -16,34 +16,24 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
-import type { DigitalCardRequest } from "@/lib/api/types";
+import type { DigitalCardFormData } from "@/lib/api/types";
+import { getCardTypeOptions } from "@/app/(user)/digital-cards/utils/card-labels";
 
-interface IDigitalCardSelectFieldProps {
-  name: "type" | "codeType";
-  label: string;
-  placeholder: string;
-  options: { value: string; label: string }[];
-}
-
-export default function DigitalCardSelectField({
-  name,
-  label,
-  placeholder,
-  options,
-}: IDigitalCardSelectFieldProps) {
-  const form = useFormContext<DigitalCardRequest>();
+export default function CardTypeField() {
+  const form = useFormContext<DigitalCardFormData>();
+  const options = getCardTypeOptions();
 
   return (
     <FormField
       control={form.control}
-      name={name}
+      name="cardType"
       render={({ field }) => (
         <FormItem>
-          <FormLabel>{label}</FormLabel>
+          <FormLabel>Tip kartice</FormLabel>
           <Select onValueChange={field.onChange} value={field.value}>
             <FormControl>
               <SelectTrigger className="w-full">
-                <SelectValue placeholder={placeholder} />
+                <SelectValue placeholder="Odaberi tip" />
               </SelectTrigger>
             </FormControl>
             <SelectContent>
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/code-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/code-field.tsx
new file mode 100644
index 00000000..34e2ef03
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/code-field.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import { useFormContext } from "react-hook-form";
+import { ScanBarcode } from "lucide-react";
+
+import {
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { useCameraScanner } from "@/context/scanner-context";
+import type { DigitalCardFormData } from "@/lib/api/types";
+import { toCodeType } from "@/app/(user)/digital-cards/utils/code-symbologies";
+
+export default function CodeField() {
+  const form = useFormContext<DigitalCardFormData>();
+  const { openScanner } = useCameraScanner();
+
+  // The "all" preset accepts every symbology a loyalty card might carry, unlike the
+  // product scanner which is locked to EAN.
+  function handleScan() {
+    openScanner({
+      preset: "all",
+      onScan: (code) => {
+        form.setValue("codeValue", code.rawValue, {
+          shouldDirty: true,
+          shouldValidate: true,
+        });
+        form.setValue("codeType", toCodeType(code.format), {
+          shouldDirty: true,
+          shouldValidate: true,
+        });
+      },
+    });
+  }
+
+  return (
+    <FormField
+      control={form.control}
+      name="codeValue"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>Broj ili kod kartice</FormLabel>
+          <div className="flex items-start gap-2">
+            <FormControl>
+              <Input {...field} inputMode="text" className="font-mono" />
+            </FormControl>
+
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  onClick={handleScan}
+                  aria-label="Skeniraj kod kartice"
+                  className="grid size-9 shrink-0 cursor-pointer place-items-center rounded-md border border-input bg-background text-muted-foreground transition hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+                >
+                  <ScanBarcode aria-hidden="true" className="size-4" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent className="px-2 py-1 text-xs">
+                Skeniraj kod kartice
+              </TooltipContent>
+            </Tooltip>
+          </div>
+          <FormDescription>
+            Skeniraj kod s kartice ili ga upiši ručno.
+          </FormDescription>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/code-preview.tsx b/frontend/src/app/(user)/digital-cards/components/forms/code-preview.tsx
new file mode 100644
index 00000000..210f0a8c
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/code-preview.tsx
@@ -0,0 +1,56 @@
+"use client";
+
+import { useFormContext } from "react-hook-form";
+import { TriangleAlert } from "lucide-react";
+
+import type { DigitalCardFormData } from "@/lib/api/types";
+import { generateCodeSvg } from "@/app/(user)/digital-cards/utils/generate-code-svg";
+
+/**
+ * Confirms the chosen symbology actually encodes the value before the card is saved, which
+ * is the whole reason codeType is user-editable: a wrong guess is invisible until a cashier
+ * cannot scan it.
+ */
+export default function CodePreview() {
+  const form = useFormContext<DigitalCardFormData>();
+  const codeValue = form.watch("codeValue");
+  const codeType = form.watch("codeType");
+
+  if (!codeValue?.trim()) return null;
+
+  const result = generateCodeSvg(codeValue, codeType);
+
+  return (
+    <div className="space-y-2">
+      <p className="text-sm font-medium">Prikaz koda</p>
+
+      <div className="grid min-h-24 place-items-center rounded-md border bg-white p-3">
+        {result.ok ? (
+          <div
+            className="w-full max-w-64 [&>svg]:h-auto [&>svg]:w-full"
+            // Safe by construction: includetext is off, so no user text reaches the SVG.
+            dangerouslySetInnerHTML={{ __html: result.svg }}
+          />
+        ) : (
+          <p className="break-all text-center text-lg font-semibold tracking-widest tabular-nums text-black">
+            {codeValue}
+          </p>
+        )}
+      </div>
+
+      {!result.ok && (
+        <p className="flex items-start gap-1.5 text-xs text-amber-700">
+          <TriangleAlert
+            aria-hidden="true"
+            className="mt-0.5 size-3.5 shrink-0"
+          />
+          <span>
+            {result.reason === "unsupported"
+              ? "Ovaj tip prikazuje samo broj, bez barkoda. Na blagajni pokaži broj ili sliku kartice."
+              : "Kod se ne može prikazati za odabrani tip. Probaj drugi tip koda ili provjeri broj."}
+          </span>
+        </p>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/code-type-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/code-type-field.tsx
new file mode 100644
index 00000000..e48f2ba4
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/code-type-field.tsx
@@ -0,0 +1,63 @@
+"use client";
+
+import { useFormContext } from "react-hook-form";
+
+import {
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@/components/ui/form";
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import type { DigitalCardFormData } from "@/lib/api/types";
+import { getCodeTypeGroups } from "@/app/(user)/digital-cards/utils/code-symbologies";
+
+export default function CodeTypeField() {
+  const form = useFormContext<DigitalCardFormData>();
+  const groups = getCodeTypeGroups();
+
+  return (
+    <FormField
+      control={form.control}
+      name="codeType"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>Tip koda</FormLabel>
+          <Select onValueChange={field.onChange} value={field.value}>
+            <FormControl>
+              <SelectTrigger className="w-full">
+                <SelectValue placeholder="Odaberi tip koda" />
+              </SelectTrigger>
+            </FormControl>
+            <SelectContent>
+              {groups.map((group) => (
+                <SelectGroup key={group.label}>
+                  <SelectLabel>{group.label}</SelectLabel>
+                  {group.options.map((option) => (
+                    <SelectItem key={option.value} value={option.value}>
+                      {option.label}
+                    </SelectItem>
+                  ))}
+                </SelectGroup>
+              ))}
+            </SelectContent>
+          </Select>
+          <FormDescription>
+            Provjeri prikaz koda ispod. Ako se ne prikazuje, probaj drugi tip.
+          </FormDescription>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/color-picker/card-color-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/card-color-field.tsx
new file mode 100644
index 00000000..4aa626b9
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/card-color-field.tsx
@@ -0,0 +1,64 @@
+"use client";
+
+import { useState } from "react";
+import { useFormContext } from "react-hook-form";
+
+import { FormDescription, FormLabel, FormMessage } from "@/components/ui/form";
+import type { DigitalCardFormData } from "@/lib/api/types";
+import ColorPickerHoneycomb from "@/app/(user)/digital-cards/components/forms/color-picker/color-picker-honeycomb";
+import ColorPickerSwatchSlider from "@/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatch-slider";
+import ColorPickerSwatches from "@/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatches";
+import ColorPickerSwitcher, {
+  type ColorPickerVariant,
+} from "@/app/(user)/digital-cards/components/forms/color-picker/color-picker-switcher";
+
+interface ICardColorFieldProps {
+  /** True once the user picks a colour, after which nothing auto-fills over them. */
+  isCustomized: boolean;
+  onCustomize: () => void;
+}
+
+export default function CardColorField({
+  isCustomized,
+  onCustomize,
+}: ICardColorFieldProps) {
+  const form = useFormContext<DigitalCardFormData>();
+  const [variant, setVariant] = useState<ColorPickerVariant>("swatch-slider");
+
+  const value = form.watch("cardColor");
+
+  function handleChange(hex: string) {
+    form.setValue("cardColor", hex, {
+      shouldDirty: true,
+      shouldValidate: true,
+    });
+    onCustomize();
+  }
+
+  return (
+    <div className="space-y-2">
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <FormLabel htmlFor={undefined}>Boja kartice</FormLabel>
+        <ColorPickerSwitcher value={variant} onChange={setVariant} />
+      </div>
+
+      {variant === "swatch-slider" && (
+        <ColorPickerSwatchSlider value={value} onChange={handleChange} />
+      )}
+      {variant === "honeycomb" && (
+        <ColorPickerHoneycomb value={value} onChange={handleChange} />
+      )}
+      {variant === "swatches" && (
+        <ColorPickerSwatches value={value} onChange={handleChange} />
+      )}
+
+      <FormDescription>
+        {isCustomized
+          ? "Boja pomaže da karticu prepoznaš na prvi pogled."
+          : "Boju predlažemo iz trgovine ili slike, a možeš je promijeniti."}
+      </FormDescription>
+
+      <FormMessage />
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-honeycomb.tsx b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-honeycomb.tsx
new file mode 100644
index 00000000..aafaaab4
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-honeycomb.tsx
@@ -0,0 +1,97 @@
+"use client";
+
+import { hslToHex } from "@/app/(user)/digital-cards/utils/card-colors";
+import { NEUTRAL_CARD_COLORS } from "@/app/(user)/digital-cards/utils/card-colors";
+import { cn } from "@/lib/utils";
+
+interface IColorPickerHoneycombProps {
+  value: string;
+  onChange: (hex: string) => void;
+}
+
+// Three rings of hues, saturation easing outward so the middle reads as the calm choice and
+// the rim as the bold one. Row lengths are what give the comb its stagger.
+const ROWS: { saturation: number; lightness: number; count: number }[] = [
+  { saturation: 38, lightness: 50, count: 7 },
+  { saturation: 62, lightness: 42, count: 8 },
+  { saturation: 78, lightness: 34, count: 7 },
+];
+
+const HEX_CLIP =
+  "polygon(50% 0%, 100% 25%, 100% 75%, 50% 100%, 0% 75%, 0% 25%)";
+
+/**
+ * Variant B: a honeycomb. Hexagons tessellate without gaps, so the palette reads as one
+ * surface rather than a grid of dots, and the shape itself is the memorable part.
+ */
+export default function ColorPickerHoneycomb({
+  value,
+  onChange,
+}: IColorPickerHoneycombProps) {
+  const selected = value.toLowerCase();
+
+  return (
+    <div
+      role="radiogroup"
+      aria-label="Boja kartice"
+      className="flex flex-col items-center gap-1"
+    >
+      {ROWS.map((row, rowIndex) => (
+        <div
+          key={rowIndex}
+          className="flex gap-1"
+          // Offset every other row by half a cell, which is what makes it a comb.
+          style={{ marginLeft: rowIndex % 2 === 1 ? "1.15rem" : undefined }}
+        >
+          {Array.from({ length: row.count }, (_, cellIndex) => {
+            const hue = Math.round((360 / row.count) * cellIndex);
+            const hex = hslToHex(hue, row.saturation, row.lightness);
+            const isSelected = hex.toLowerCase() === selected;
+
+            return (
+              <button
+                key={hex}
+                type="button"
+                role="radio"
+                aria-checked={isSelected}
+                aria-label={`Boja ${hex}`}
+                onClick={() => onChange(hex)}
+                style={{ backgroundColor: hex, clipPath: HEX_CLIP }}
+                className={cn(
+                  "size-9 cursor-pointer transition focus-visible:outline-none",
+                  isSelected
+                    ? "scale-110 ring-2 ring-foreground"
+                    : "hover:scale-105 focus-visible:scale-110",
+                )}
+              />
+            );
+          })}
+        </div>
+      ))}
+
+      <div className="mt-1 flex gap-1">
+        {NEUTRAL_CARD_COLORS.map((hex) => {
+          const isSelected = hex.toLowerCase() === selected;
+
+          return (
+            <button
+              key={hex}
+              type="button"
+              role="radio"
+              aria-checked={isSelected}
+              aria-label={`Boja ${hex}`}
+              onClick={() => onChange(hex)}
+              style={{ backgroundColor: hex, clipPath: HEX_CLIP }}
+              className={cn(
+                "size-9 cursor-pointer transition focus-visible:outline-none",
+                isSelected
+                  ? "scale-110 ring-2 ring-foreground"
+                  : "hover:scale-105 focus-visible:scale-110",
+              )}
+            />
+          );
+        })}
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatch-slider.tsx b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatch-slider.tsx
new file mode 100644
index 00000000..9ad8d2d2
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatch-slider.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import ColorPickerSwatches from "@/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatches";
+import HueSlider from "@/app/(user)/digital-cards/components/forms/color-picker/hue-slider";
+
+interface IColorPickerSwatchSliderProps {
+  value: string;
+  onChange: (hex: string) => void;
+}
+
+/**
+ * Variant A: one tap for the common case, one drag for anything in between. The swatches
+ * and the slider are the same scale, so tapping a swatch simply moves the handle.
+ */
+export default function ColorPickerSwatchSlider({
+  value,
+  onChange,
+}: IColorPickerSwatchSliderProps) {
+  return (
+    <div className="space-y-3">
+      <ColorPickerSwatches value={value} onChange={onChange} />
+      <HueSlider value={value} onChange={onChange} />
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatches.tsx b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatches.tsx
new file mode 100644
index 00000000..909b9ed0
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-swatches.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import { Check } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+import { CARD_SWATCHES } from "@/app/(user)/digital-cards/utils/card-colors";
+
+interface IColorPickerSwatchesProps {
+  value: string;
+  onChange: (hex: string) => void;
+  className?: string;
+}
+
+/** Variant C, the control condition: swatches only, nothing else to learn. */
+export default function ColorPickerSwatches({
+  value,
+  onChange,
+  className,
+}: IColorPickerSwatchesProps) {
+  return (
+    <div
+      role="radiogroup"
+      aria-label="Boja kartice"
+      className={cn("flex flex-wrap gap-2", className)}
+    >
+      {CARD_SWATCHES.map((hex) => {
+        const isSelected = hex.toLowerCase() === value.toLowerCase();
+
+        return (
+          <button
+            key={hex}
+            type="button"
+            role="radio"
+            aria-checked={isSelected}
+            aria-label={`Boja ${hex}`}
+            onClick={() => onChange(hex)}
+            style={{ backgroundColor: hex }}
+            className={cn(
+              "grid size-8 cursor-pointer place-items-center rounded-full text-white shadow-sm ring-1 ring-black/10 transition",
+              "hover:scale-110 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:outline-none",
+              isSelected && "ring-2 ring-foreground ring-offset-2",
+            )}
+          >
+            {isSelected && <Check aria-hidden="true" className="size-4" />}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-switcher.tsx b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-switcher.tsx
new file mode 100644
index 00000000..f1c1d32c
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/color-picker-switcher.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import { cn } from "@/lib/utils";
+
+export const COLOR_PICKER_VARIANTS = [
+  { id: "swatch-slider", label: "Paleta i nijansa" },
+  { id: "honeycomb", label: "Šesterokuti" },
+  { id: "swatches", label: "Samo paleta" },
+] as const;
+
+export type ColorPickerVariant = (typeof COLOR_PICKER_VARIANTS)[number]["id"];
+
+interface IColorPickerSwitcherProps {
+  value: ColorPickerVariant;
+  onChange: (variant: ColorPickerVariant) => void;
+}
+
+/**
+ * TODO(digital-cards): temporary. Three pickers ship side by side so the final one can be
+ * chosen from real use; delete this switcher and the two losing variants once it is picked.
+ */
+export default function ColorPickerSwitcher({
+  value,
+  onChange,
+}: IColorPickerSwitcherProps) {
+  return (
+    <div className="flex flex-wrap items-center gap-1 rounded-md bg-muted p-1">
+      {COLOR_PICKER_VARIANTS.map((variant) => (
+        <button
+          key={variant.id}
+          type="button"
+          aria-pressed={value === variant.id}
+          onClick={() => onChange(variant.id)}
+          className={cn(
+            "cursor-pointer rounded-sm px-2 py-1 text-xs transition focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none",
+            value === variant.id
+              ? "bg-background font-medium shadow-sm"
+              : "text-muted-foreground hover:text-foreground",
+          )}
+        >
+          {variant.label}
+        </button>
+      ))}
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/color-picker/hue-slider.tsx b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/hue-slider.tsx
new file mode 100644
index 00000000..0b7fd14d
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/hue-slider.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import {
+  hexForHue,
+  hueFromHex,
+} from "@/app/(user)/digital-cards/utils/card-colors";
+
+interface IHueSliderProps {
+  value: string;
+  onChange: (hex: string) => void;
+}
+
+const HUE_STOPS = [0, 60, 120, 180, 240, 300, 360]
+  .map((hue) => `${hexForHue(hue)} ${(hue / 360) * 100}%`)
+  .join(", ");
+
+/**
+ * A hue slider rather than a 2D area: saturation and lightness stay locked, so every colour
+ * it can produce is legible under white text, and one horizontal drag is the friendliest
+ * possible touch target.
+ */
+export default function HueSlider({ value, onChange }: IHueSliderProps) {
+  const { hue, isNeutral } = hueFromHex(value);
+
+  return (
+    <label className="block">
+      <span className="sr-only">Nijansa boje kartice</span>
+      <input
+        type="range"
+        min={0}
+        max={359}
+        step={1}
+        value={isNeutral ? 0 : hue}
+        onChange={(event) => onChange(hexForHue(Number(event.target.value)))}
+        className="h-6 w-full cursor-pointer appearance-none rounded-full border border-black/10 outline-none focus-visible:ring-2 focus-visible:ring-ring [&::-moz-range-thumb]:size-5 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:border-2 [&::-moz-range-thumb]:border-white [&::-moz-range-thumb]:bg-transparent [&::-moz-range-thumb]:shadow-md [&::-webkit-slider-thumb]:size-5 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:border-2 [&::-webkit-slider-thumb]:border-white [&::-webkit-slider-thumb]:shadow-md"
+        style={{ background: `linear-gradient(90deg, ${HUE_STOPS})` }}
+      />
+    </label>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-fields.tsx b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-fields.tsx
deleted file mode 100644
index cf37cf13..00000000
--- a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-fields.tsx
+++ /dev/null
@@ -1,123 +0,0 @@
-"use client";
-
-import { useFormContext } from "react-hook-form";
-
-import { Input } from "@/components/ui/input";
-import { Textarea } from "@/components/ui/textarea";
-import {
-  FormControl,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormMessage,
-  FormDescription,
-} from "@/components/ui/form";
-import DigitalCardSelectField from "@/app/(user)/digital-cards/components/forms/digital-card-select-field";
-import type { DigitalCardRequest } from "@/lib/api/types";
-
-const CARD_TYPES = [
-  { value: "loyalty", label: "Loyalty kartica" },
-  { value: "discount", label: "Popust kartica" },
-  { value: "membership", label: "Članstvo" },
-  { value: "gift", label: "Poklon kartica" },
-  { value: "other", label: "Ostalo" },
-];
-
-const CODE_TYPES = [
-  { value: "barcode", label: "Barkod" },
-  { value: "qr", label: "QR kod" },
-  { value: "number", label: "Broj" },
-  { value: "text", label: "Tekst" },
-];
-
-export default function DigitalCardFields() {
-  const form = useFormContext<DigitalCardRequest>();
-
-  return (
-    <>
-      <FormField
-        control={form.control}
-        name="title"
-        render={({ field }) => (
-          <FormItem>
-            <FormLabel>Naziv kartice</FormLabel>
-            <FormControl>
-              <Input {...field} autoFocus />
-            </FormControl>
-            <FormMessage />
-          </FormItem>
-        )}
-      />
-
-      <FormField
-        control={form.control}
-        name="value"
-        render={({ field }) => (
-          <FormItem>
-            <FormLabel>Vrijednost/Kod</FormLabel>
-            <FormControl>
-              <Input {...field} />
-            </FormControl>
-            <FormMessage />
-          </FormItem>
-        )}
-      />
-
-      <DigitalCardSelectField
-        name="type"
-        label="Tip kartice"
-        placeholder="Odaberi tip"
-        options={CARD_TYPES}
-      />
-
-      <DigitalCardSelectField
-        name="codeType"
-        label="Tip koda"
-        placeholder="Odaberi tip koda"
-        options={CODE_TYPES}
-      />
-
-      <FormField
-        control={form.control}
-        name="color"
-        render={({ field }) => (
-          <FormItem>
-            <FormLabel>Boja kartice</FormLabel>
-            <FormControl>
-              <Input
-                type="color"
-                {...field}
-                value={field.value || "#ffffff"}
-                className="h-16"
-              />
-            </FormControl>
-            <FormMessage />
-          </FormItem>
-        )}
-      />
-
-      <FormField
-        control={form.control}
-        name="note"
-        render={({ field }) => (
-          <FormItem>
-            <FormLabel>Napomena</FormLabel>
-            <FormControl>
-              <Textarea
-                placeholder="Unesi napomenu"
-                {...field}
-                value={field.value || ""}
-                maxLength={200}
-              />
-            </FormControl>
-            <FormDescription>
-              Dodatne informacije o tvojoj kartici (
-              {200 - (field.value?.length || 0)} preostalo).
-            </FormDescription>
-            <FormMessage />
-          </FormItem>
-        )}
-      />
-    </>
-  );
-}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
index 368caa8c..2cacd148 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
@@ -1,23 +1,39 @@
 "use client";
 
-import { useEffect } from "react";
+import { useEffect, useState } from "react";
 import { useForm } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";
-
 import { Save } from "lucide-react";
 
 import { ModalShell } from "@/components/custom/modal/modal-shell";
 import { Form } from "@/components/ui/form";
 import { Skeleton } from "@/components/ui/skeleton";
-import DigitalCardFields from "@/app/(user)/digital-cards/components/forms/digital-card-fields";
-import { useDigitalCardModal } from "@/app/(user)/digital-cards/hooks/use-digital-card-modal";
-import { digitalCardService } from "@/lib/api";
-import { DigitalCardRequest, digitalCardRequestSchema } from "@/lib/api/types";
 import { applyProblemToForm } from "@/lib/api/problem-details";
-import { closeModalUrl } from "@/lib/modal/modal-navigation";
+import {
+  digitalCardFormSchema,
+  type DigitalCardFormData,
+} from "@/lib/api/schemas/digital-card";
 import { takeModalError } from "@/lib/modal/modal-error-bus";
+import { closeModalUrl } from "@/lib/modal/modal-navigation";
 import { useFormDraft } from "@/hooks/use-form-draft";
 import { getFormDraft } from "@/utils/browser/local-storage";
+import extractDominantColor from "@/utils/browser/extract-dominant-color";
+import CardNameField from "@/app/(user)/digital-cards/components/forms/card-name-field";
+import CardTypeField from "@/app/(user)/digital-cards/components/forms/card-type-field";
+import CardImagesField from "@/app/(user)/digital-cards/components/forms/card-images-field";
+import CodeField from "@/app/(user)/digital-cards/components/forms/code-field";
+import CodePreview from "@/app/(user)/digital-cards/components/forms/code-preview";
+import CodeTypeField from "@/app/(user)/digital-cards/components/forms/code-type-field";
+import NoteField from "@/app/(user)/digital-cards/components/forms/note-field";
+import StoreNameField from "@/app/(user)/digital-cards/components/forms/store-name-field";
+import CardColorField from "@/app/(user)/digital-cards/components/forms/color-picker/card-color-field";
+import { useCardImages } from "@/app/(user)/digital-cards/hooks/use-card-images";
+import { useDigitalCard } from "@/app/(user)/digital-cards/hooks/use-digital-card";
+import { useDigitalCardModal } from "@/app/(user)/digital-cards/hooks/use-digital-card-modal";
+import {
+  CHAIN_BRAND_COLORS,
+  DEFAULT_CARD_COLOR,
+} from "@/app/(user)/digital-cards/utils/card-colors";
 
 interface IDigitalCardModalProps {
   open: boolean;
@@ -25,13 +41,15 @@ interface IDigitalCardModalProps {
   id?: string;
 }
 
-const EMPTY_VALUES: DigitalCardRequest = {
-  title: "",
-  value: "",
-  type: "loyalty",
-  codeType: "barcode",
-  color: undefined,
-  note: undefined,
+const EMPTY_VALUES: DigitalCardFormData = {
+  cardName: "",
+  cardType: "loyalty",
+  storeName: "",
+  chainCode: null,
+  codeValue: "",
+  codeType: "ean_13",
+  cardColor: DEFAULT_CARD_COLOR,
+  note: null,
 };
 
 export default function DigitalCardModal({
@@ -41,40 +59,49 @@ export default function DigitalCardModal({
 }: IDigitalCardModalProps) {
   const isEdit = action === "edit" && !!id;
 
-  // Cards have no by-id endpoint; the user's list query covers cold deep links.
-  const cardsQuery = digitalCardService.useGetUserDigitalCards({
+  const { card, isLoading, isError, notFound } = useDigitalCard(id, {
     enabled: isEdit,
   });
-  const digitalCard = isEdit
-    ? (cardsQuery.data?.find((card) => card.id === id) ?? null)
-    : null;
+  const digitalCard = isEdit ? card : null;
 
   const draftKey = isEdit ? `digital-card.edit.${id}` : "digital-card.new";
   const isReady = !isEdit || !!digitalCard;
 
-  const form = useForm<DigitalCardRequest>({
-    resolver: zodResolver(digitalCardRequestSchema),
+  const form = useForm<DigitalCardFormData>({
+    resolver: zodResolver(digitalCardFormSchema),
     mode: "onChange",
     defaultValues: EMPTY_VALUES,
   });
 
+  const {
+    images,
+    setImage,
+    resetImages,
+    isDirty: imagesDirty,
+  } = useCardImages(digitalCard);
+
+  // An existing card's colour is the user's own choice, so nothing may overwrite it.
+  const [colorCustomized, setColorCustomized] = useState(isEdit);
+
   // Draft precedence controls restore order; the isDirty guard is what stops a
   // reload from clobbering an in-progress edit.
   useEffect(() => {
     if (!digitalCard || form.formState.isDirty) return;
 
-    const base: DigitalCardRequest = {
-      title: digitalCard.title,
-      value: digitalCard.value,
-      type: digitalCard.type,
+    const base: DigitalCardFormData = {
+      cardName: digitalCard.cardName,
+      cardType: digitalCard.cardType,
+      storeName: digitalCard.storeName,
+      chainCode: digitalCard.chainCode,
+      codeValue: digitalCard.codeValue,
       codeType: digitalCard.codeType,
-      color: digitalCard.color,
+      cardColor: digitalCard.cardColor,
       note: digitalCard.note,
     };
     form.reset(base);
 
     const draft = getFormDraft(draftKey)?.values as
-      Partial<DigitalCardRequest> | undefined;
+      Partial<DigitalCardFormData> | undefined;
     if (draft && Object.keys(draft).length > 0) {
       form.reset({ ...base, ...draft }, { keepDefaultValues: true });
     }
@@ -84,10 +111,10 @@ export default function DigitalCardModal({
     draftKey,
     form,
     enabled: open && isReady,
-    // New cards auto-restore via the engine; edit modals merge the draft themselves below.
+    // New cards auto-restore via the engine; edit modals merge the draft themselves above.
     restore: !isEdit,
     // The card code is sensitive; never persist it to localStorage.
-    exclude: ["value"],
+    exclude: ["codeValue"],
   });
 
   // A failed optimistic save reopened this modal: surface the server error.
@@ -97,50 +124,60 @@ export default function DigitalCardModal({
     if (error) applyProblemToForm(error, form);
   }, [open, draftKey, form]);
 
-  const { onSubmit, isLoading } = useDigitalCardModal({
+  const { onSubmit, isLoading: isSaving } = useDigitalCardModal({
     digitalCard,
     draftKey,
   });
 
-  function handleSubmit(data: DigitalCardRequest) {
+  function suggestColor(hex: string) {
+    if (colorCustomized) return;
+    form.setValue("cardColor", hex, { shouldDirty: true });
+  }
+
+  async function handleColorSource(file: File) {
+    if (colorCustomized) return;
+    const extracted = await extractDominantColor(file);
+    if (extracted) suggestColor(extracted);
+  }
+
+  function handleSubmit(data: DigitalCardFormData) {
     flushDraft();
-    onSubmit(data);
+    onSubmit({ ...data, ...images });
   }
 
-  const loading = isEdit && !digitalCard && cardsQuery.isLoading;
-  const loadError = isEdit && !digitalCard && cardsQuery.isError;
-  const notFound =
-    isEdit && !digitalCard && !cardsQuery.isLoading && !cardsQuery.isError;
+  const loading = isEdit && isLoading;
 
   return (
     <ModalShell
       open={open}
       onOpenChange={(isOpen) => !isOpen && closeModalUrl()}
-      title={isEdit ? "Uredi digitalnu karticu" : "Nova digitalna kartica"}
+      title={isEdit ? "Uredi karticu" : "Nova digitalna kartica"}
       description="Spremi karticu vjernosti i imaj je uvijek pri ruci."
       srOnlyDescription
-      dirty={form.formState.isDirty}
+      size="lg"
+      dirty={form.formState.isDirty || imagesDirty}
       formId="digital-card-form"
       submitLabel={isEdit ? "Spremi" : "Stvori"}
       submitIcon={Save}
-      submitLoading={isLoading}
+      submitLoading={isSaving}
       submitDisabled={
-        !form.formState.isDirty ||
+        !(form.formState.isDirty || imagesDirty) ||
         !form.formState.isValid ||
         notFound ||
-        loadError
+        isError
       }
       cancelLabel="Odustani"
       resetLabel="Resetiraj"
-      resetDisabled={!form.formState.isDirty && !restored}
+      resetDisabled={!form.formState.isDirty && !imagesDirty && !restored}
       onReset={() => {
         clearDraft();
+        resetImages();
         form.reset();
       }}
     >
       {loading ? (
-        <Skeleton className="h-64 w-full" />
-      ) : loadError ? (
+        <Skeleton className="h-96 w-full" />
+      ) : isError ? (
         <p className="text-sm text-muted-foreground">
           Greška pri učitavanju kartice. Pokušaj ponovo.
         </p>
@@ -156,12 +193,39 @@ export default function DigitalCardModal({
             className="space-y-5"
           >
             {form.formState.errors.root && (
-              <div className="text-sm text-red-600 bg-red-50 border border-red-200 rounded-md p-3">
+              <div className="rounded-md border border-red-200 bg-red-50 p-3 text-sm text-red-600">
                 {form.formState.errors.root.message}
               </div>
             )}
 
-            <DigitalCardFields />
+            <CardNameField />
+
+            <StoreNameField
+              onChainSelected={(chainCode) => {
+                const brandColor = chainCode
+                  ? CHAIN_BRAND_COLORS[chainCode]
+                  : undefined;
+                if (brandColor) suggestColor(brandColor);
+              }}
+            />
+
+            <CardTypeField />
+            <CodeField />
+            <CodeTypeField />
+            <CodePreview />
+
+            <CardColorField
+              isCustomized={colorCustomized}
+              onCustomize={() => setColorCustomized(true)}
+            />
+
+            <CardImagesField
+              images={images}
+              onImageChange={setImage}
+              onColorSource={handleColorSource}
+            />
+
+            <NoteField />
           </form>
         </Form>
       )}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/note-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/note-field.tsx
new file mode 100644
index 00000000..0e32ab4e
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/note-field.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import { useFormContext } from "react-hook-form";
+
+import {
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@/components/ui/form";
+import { Textarea } from "@/components/ui/textarea";
+import type { DigitalCardFormData } from "@/lib/api/types";
+
+export default function NoteField() {
+  const form = useFormContext<DigitalCardFormData>();
+
+  return (
+    <FormField
+      control={form.control}
+      name="note"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>Bilješka</FormLabel>
+          <FormControl>
+            <Textarea
+              {...field}
+              value={field.value ?? ""}
+              onChange={(event) => field.onChange(event.target.value || null)}
+              rows={2}
+              placeholder="npr. kartica vrijedi i u Bosni"
+            />
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/store-name-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/store-name-field.tsx
new file mode 100644
index 00000000..31b260a1
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/store-name-field.tsx
@@ -0,0 +1,141 @@
+"use client";
+
+import { useState } from "react";
+import { useFormContext } from "react-hook-form";
+
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandList,
+} from "@/components/ui/command";
+import {
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@/components/ui/form";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import type { DigitalCardFormData } from "@/lib/api/types";
+import StoreNameOption from "@/app/(user)/digital-cards/components/forms/store-name-option";
+import StoreNameTrigger from "@/app/(user)/digital-cards/components/forms/store-name-trigger";
+import { useStoreNameOptions } from "@/app/(user)/digital-cards/hooks/use-store-name-options";
+
+interface IStoreNameFieldProps {
+  /** Fires only for an official chain, so the caller can offer its logo and brand colour. */
+  onChainSelected: (chainCode: string | null) => void;
+}
+
+export default function StoreNameField({
+  onChainSelected,
+}: IStoreNameFieldProps) {
+  const form = useFormContext<DigitalCardFormData>();
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState("");
+
+  const { officialOptions, suggestedOptions } = useStoreNameOptions({
+    enabled: open,
+  });
+
+  const chainCode = form.watch("chainCode");
+
+  function select(label: string, nextChainCode: string | null) {
+    form.setValue("storeName", label, {
+      shouldDirty: true,
+      shouldValidate: true,
+    });
+    form.setValue("chainCode", nextChainCode, { shouldDirty: true });
+    onChainSelected(nextChainCode);
+    setOpen(false);
+    setSearch("");
+  }
+
+  return (
+    <FormField
+      control={form.control}
+      name="storeName"
+      render={({ field }) => (
+        <FormItem className="flex flex-col">
+          <FormLabel>Trgovina</FormLabel>
+
+          <Popover open={open} onOpenChange={setOpen} modal={true}>
+            <PopoverTrigger asChild>
+              <FormControl>
+                <StoreNameTrigger
+                  open={open}
+                  storeName={field.value}
+                  chainCode={chainCode}
+                  onClear={() => select("", null)}
+                />
+              </FormControl>
+            </PopoverTrigger>
+
+            <PopoverContent className="w-sm max-w-[75dvw] p-0">
+              <Command>
+                <CommandInput
+                  placeholder="Pretraži trgovine ili upiši svoju..."
+                  value={search}
+                  onValueChange={setSearch}
+                />
+                <CommandList>
+                  <CommandEmpty>
+                    <p className="px-2 text-sm">
+                      Nema pronađene trgovine. Upiši naziv i odaberi ga ispod.
+                    </p>
+                  </CommandEmpty>
+
+                  {officialOptions.length > 0 && (
+                    <CommandGroup heading="Službene trgovine">
+                      {officialOptions.map((option) => (
+                        <StoreNameOption
+                          key={option.chainCode}
+                          option={option}
+                          isSelected={field.value === option.label}
+                          onSelect={() =>
+                            select(option.label, option.chainCode)
+                          }
+                        />
+                      ))}
+                    </CommandGroup>
+                  )}
+
+                  {suggestedOptions.length > 0 && (
+                    <CommandGroup heading="Ostalo">
+                      {suggestedOptions.map((option) => (
+                        <StoreNameOption
+                          key={option.label}
+                          option={option}
+                          isSelected={field.value === option.label}
+                          onSelect={() => select(option.label, null)}
+                        />
+                      ))}
+                    </CommandGroup>
+                  )}
+
+                  {/* Free entry is never blocked: a corner shop has no chain code. */}
+                  {search.trim().length >= 2 && (
+                    <CommandGroup heading="Nova trgovina">
+                      <StoreNameOption
+                        option={{ label: search.trim(), chainCode: null }}
+                        isSelected={false}
+                        onSelect={() => select(search.trim(), null)}
+                      />
+                    </CommandGroup>
+                  )}
+                </CommandList>
+              </Command>
+            </PopoverContent>
+          </Popover>
+
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/store-name-option.tsx b/frontend/src/app/(user)/digital-cards/components/forms/store-name-option.tsx
new file mode 100644
index 00000000..345fea9a
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/store-name-option.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import { Check, Store } from "lucide-react";
+
+import { CommandItem } from "@/components/ui/command";
+import StoreChainLogo from "@/components/custom/store-chain/store-chain-logo";
+import type { IStoreOption } from "@/app/(user)/digital-cards/hooks/use-store-name-options";
+
+interface IStoreNameOptionProps {
+  option: IStoreOption;
+  isSelected: boolean;
+  onSelect: () => void;
+}
+
+export default function StoreNameOption({
+  option,
+  isSelected,
+  onSelect,
+}: IStoreNameOptionProps) {
+  return (
+    <CommandItem value={option.label} onSelect={onSelect} className="gap-2">
+      <span className="grid size-6 shrink-0 place-items-center overflow-hidden rounded-sm">
+        {option.chainCode ? (
+          <StoreChainLogo chain={option.chainCode} width={24} height={24} />
+        ) : (
+          <Store aria-hidden="true" className="size-4 text-muted-foreground" />
+        )}
+      </span>
+
+      <span className="truncate">{option.label}</span>
+
+      {isSelected && (
+        <Check aria-hidden="true" className="ml-auto size-4 text-primary" />
+      )}
+    </CommandItem>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/store-name-trigger.tsx b/frontend/src/app/(user)/digital-cards/components/forms/store-name-trigger.tsx
new file mode 100644
index 00000000..df490b77
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/forms/store-name-trigger.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+import { ChevronsUpDown, Store, X } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import StoreChainLogo from "@/components/custom/store-chain/store-chain-logo";
+import { cn } from "@/lib/utils";
+
+interface IStoreNameTriggerProps {
+  open: boolean;
+  storeName: string;
+  chainCode: string | null;
+  onClear: () => void;
+}
+
+export default function StoreNameTrigger({
+  open,
+  storeName,
+  chainCode,
+  onClear,
+}: IStoreNameTriggerProps) {
+  return (
+    <div className="relative">
+      <Button
+        type="button"
+        variant="outline"
+        role="combobox"
+        aria-expanded={open}
+        className={cn(
+          "w-full justify-start gap-2 pr-14 font-normal",
+          !storeName && "text-muted-foreground",
+        )}
+      >
+        <span className="grid size-5 shrink-0 place-items-center overflow-hidden rounded-sm">
+          {chainCode ? (
+            <StoreChainLogo chain={chainCode} width={20} height={20} />
+          ) : (
+            <Store aria-hidden="true" className="size-4 opacity-60" />
+          )}
+        </span>
+
+        <span className="truncate">{storeName || "Odaberi trgovinu"}</span>
+      </Button>
+
+      <div className="absolute inset-y-0 right-2 flex items-center gap-1">
+        {storeName && (
+          <button
+            type="button"
+            // Stops the popover from opening: clearing is its own action, not a way in.
+            onClick={(event) => {
+              event.stopPropagation();
+              onClear();
+            }}
+            aria-label="Očisti trgovinu"
+            className="grid size-5 cursor-pointer place-items-center rounded-sm text-muted-foreground hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+          >
+            <X aria-hidden="true" className="size-3.5" />
+          </button>
+        )}
+
+        <ChevronsUpDown
+          aria-hidden="true"
+          className="size-4 shrink-0 opacity-50"
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/pin-toggle-button.tsx b/frontend/src/app/(user)/digital-cards/components/pin-toggle-button.tsx
new file mode 100644
index 00000000..820a971d
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/pin-toggle-button.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import { Pin, PinOff } from "lucide-react";
+import { toast } from "sonner";
+
+import { digitalCardService } from "@/lib/api";
+import { cn } from "@/lib/utils";
+import { problemMessage } from "@/lib/api/problem-details";
+import type { DigitalCardDto } from "@/lib/api/types";
+
+interface IPinToggleButtonProps {
+  card: DigitalCardDto;
+  /** On a tile the control hides until hover; in the modal it is always a visible action. */
+  revealOnHover?: boolean;
+  className?: string;
+}
+
+export default function PinToggleButton({
+  card,
+  revealOnHover = false,
+  className,
+}: IPinToggleButtonProps) {
+  const setPinned = digitalCardService.useSetDigitalCardPinned();
+  const isPinned = !!card.pinnedAt;
+
+  async function handleClick() {
+    try {
+      await setPinned.mutateAsync({ id: card.id, pinned: !isPinned });
+    } catch (error) {
+      toast.error(problemMessage(error, "Greška pri prikvačivanju kartice."));
+    }
+  }
+
+  const Icon = isPinned ? Pin : PinOff;
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      disabled={setPinned.isPending}
+      aria-pressed={isPinned}
+      aria-label={isPinned ? "Otkvači karticu" : "Prikvači karticu"}
+      className={cn(
+        "grid size-7 cursor-pointer place-items-center rounded-full bg-black/25 text-white backdrop-blur-sm transition",
+        "hover:bg-black/45 focus-visible:ring-2 focus-visible:ring-white focus-visible:outline-none",
+        "disabled:cursor-not-allowed disabled:opacity-60",
+        // Pinned state is permanent information; unpinned is an affordance, so it only
+        // appears on hover or once focused, and stays visible on touch where hover cannot.
+        revealOnHover &&
+          !isPinned &&
+          "opacity-0 group-hover:opacity-100 focus-visible:opacity-100 max-md:opacity-100",
+        className,
+      )}
+    >
+      <Icon aria-hidden="true" className="size-3.5" />
+    </button>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx b/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx
new file mode 100644
index 00000000..1a4a6ed4
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import { TriangleAlert } from "lucide-react";
+
+import type { CodeType } from "@/constants/card-codes";
+import CardCode from "@/app/(user)/digital-cards/components/card-code";
+import {
+  generateCodeSvg,
+  isTwoDimensional,
+} from "@/app/(user)/digital-cards/utils/generate-code-svg";
+
+interface ICardCodePanelProps {
+  codeValue: string;
+  codeType: CodeType;
+}
+
+/**
+ * Deliberately clinical: forced white, forced black, generous quiet zone and no theming.
+ * A scanner needs contrast, not styling, and a dark-mode panel would not read at all.
+ */
+export default function CardCodePanel({
+  codeValue,
+  codeType,
+}: ICardCodePanelProps) {
+  const result = generateCodeSvg(codeValue, codeType);
+  const twoDimensional = isTwoDimensional(codeType);
+
+  return (
+    <div className="space-y-2">
+      <div className="rounded-lg bg-white px-4 py-5 shadow-inner ring-1 ring-black/10">
+        <div className={twoDimensional ? "mx-auto max-w-56" : "w-full"}>
+          <CardCode codeValue={codeValue} codeType={codeType} showValue />
+        </div>
+      </div>
+
+      {!result.ok && (
+        <p className="flex items-start gap-1.5 text-xs text-amber-700">
+          <TriangleAlert
+            aria-hidden="true"
+            className="mt-0.5 size-3.5 shrink-0"
+          />
+          <span>
+            Kod se ne može prikazati za odabrani tip. Pokaži broj na blagajni
+            ili sliku kartice.
+          </span>
+        </p>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/view/card-detail-rows.tsx b/frontend/src/app/(user)/digital-cards/components/view/card-detail-rows.tsx
new file mode 100644
index 00000000..256a3ca6
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/view/card-detail-rows.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import { Badge } from "@/components/ui/badge";
+import StoreChainLogo from "@/components/custom/store-chain/store-chain-logo";
+import type { CardType } from "@/constants/card-codes";
+import type { DigitalCardDto } from "@/lib/api/types";
+import { getCardTypeLabel } from "@/app/(user)/digital-cards/utils/card-labels";
+
+interface ICardDetailRowsProps {
+  card: DigitalCardDto;
+}
+
+export default function CardDetailRows({ card }: ICardDetailRowsProps) {
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center gap-2">
+        {card.chainCode && (
+          <span className="grid size-6 shrink-0 place-items-center overflow-hidden rounded-sm">
+            <StoreChainLogo chain={card.chainCode} width={24} height={24} />
+          </span>
+        )}
+        <p className="text-sm text-muted-foreground">{card.storeName}</p>
+        <Badge variant="outline">
+          {getCardTypeLabel(card.cardType as CardType)}
+        </Badge>
+      </div>
+
+      {card.note && (
+        <p className="whitespace-pre-wrap rounded-md bg-muted/60 p-3 text-sm">
+          {card.note}
+        </p>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/view/card-face-images.tsx b/frontend/src/app/(user)/digital-cards/components/view/card-face-images.tsx
new file mode 100644
index 00000000..fab77d71
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/view/card-face-images.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import { useState } from "react";
+
+import { cn } from "@/lib/utils";
+
+interface ICardFaceImagesProps {
+  frontImage: string | null;
+  backImage: string | null;
+}
+
+interface IFace {
+  label: string;
+  src: string;
+}
+
+/** The backup a cashier reads when the generated code will not scan, so it must zoom. */
+export default function CardFaceImages({
+  frontImage,
+  backImage,
+}: ICardFaceImagesProps) {
+  const [zoomed, setZoomed] = useState<IFace | null>(null);
+
+  const faces: IFace[] = [
+    ...(frontImage ? [{ label: "Prednja strana", src: frontImage }] : []),
+    ...(backImage ? [{ label: "Stražnja strana", src: backImage }] : []),
+  ];
+
+  if (faces.length === 0) return null;
+
+  return (
+    <div className="space-y-2">
+      <p className="text-sm font-medium">Slike kartice</p>
+
+      <div className="grid grid-cols-2 gap-3">
+        {faces.map((face) => (
+          <button
+            key={face.label}
+            type="button"
+            onClick={() =>
+              setZoomed((current) =>
+                current?.label === face.label ? null : face,
+              )
+            }
+            aria-label={
+              zoomed?.label === face.label
+                ? `Smanji ${face.label}`
+                : `Povećaj ${face.label}`
+            }
+            className="cursor-pointer overflow-hidden rounded-md border transition hover:border-primary focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+          >
+            {/* A data URI, so next/image would only add a proxy hop. */}
+            {/* eslint-disable-next-line @next/next/no-img-element */}
+            <img
+              src={face.src}
+              alt={face.label}
+              className={cn(
+                "w-full object-cover transition-all",
+                zoomed?.label === face.label ? "aspect-auto" : "aspect-3/2",
+              )}
+            />
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/view/card-view-actions.tsx b/frontend/src/app/(user)/digital-cards/components/view/card-view-actions.tsx
new file mode 100644
index 00000000..b13c546a
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/view/card-view-actions.tsx
@@ -0,0 +1,93 @@
+"use client";
+
+import { useState } from "react";
+import { Pencil, Trash2 } from "lucide-react";
+import { onlineManager, useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import { ConfirmDialog } from "@/components/custom/modal/confirm-dialog";
+import PinToggleButton from "@/app/(user)/digital-cards/components/pin-toggle-button";
+import { digitalCardService } from "@/lib/api";
+import { problemMessage } from "@/lib/api/problem-details";
+import type { DigitalCardDto } from "@/lib/api/types";
+import { closeModalUrl, openModalUrl } from "@/lib/modal/modal-navigation";
+
+interface ICardViewActionsProps {
+  card: DigitalCardDto;
+}
+
+export default function CardViewActions({ card }: ICardViewActionsProps) {
+  const [confirmOpen, setConfirmOpen] = useState(false);
+  const queryClient = useQueryClient();
+  const deleteMutation = digitalCardService.useDeleteDigitalCard();
+
+  async function handleDelete() {
+    setConfirmOpen(false);
+    closeModalUrl();
+
+    if (!onlineManager.isOnline()) {
+      toast.info(
+        "Izvan si mreže - promjena će se sinkronizirati kad se vratiš na mrežu.",
+      );
+    }
+
+    try {
+      await deleteMutation.mutateAsync(card.id);
+      toast.success("Kartica je uspješno obrisana!");
+      await queryClient.invalidateQueries({ queryKey: ["digitalCards"] });
+    } catch (error) {
+      toast.error(problemMessage(error, "Greška pri brisanju kartice."));
+    }
+  }
+
+  return (
+    <>
+      <div className="flex flex-wrap items-center gap-2">
+        <PinToggleButton
+          card={card}
+          className="size-9 bg-muted text-foreground hover:bg-accent"
+        />
+
+        <Button
+          type="button"
+          variant="outline"
+          icon={Pencil}
+          iconPlacement="left"
+          // Pushed, not swapped, so closing the edit modal lands back on this card.
+          onClick={() =>
+            openModalUrl({
+              name: "digital-card",
+              action: "edit",
+              id: card.id,
+            })
+          }
+        >
+          Uredi
+        </Button>
+
+        <Button
+          type="button"
+          variant="destructive"
+          icon={Trash2}
+          iconPlacement="left"
+          onClick={() => setConfirmOpen(true)}
+          className="ml-auto"
+        >
+          Obriši
+        </Button>
+      </div>
+
+      <ConfirmDialog
+        isOpen={confirmOpen}
+        onOpenChange={setConfirmOpen}
+        title="Obriši karticu"
+        description={`Sigurno želiš obrisati karticu "${card.cardName}"? Ova akcija se ne može poništiti.`}
+        confirmLabel="Obriši"
+        variant="destructive"
+        onConfirm={handleDelete}
+        isLoading={deleteMutation.isPending}
+      />
+    </>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/view/digital-card-view-modal.tsx b/frontend/src/app/(user)/digital-cards/components/view/digital-card-view-modal.tsx
new file mode 100644
index 00000000..3d9fdc66
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/view/digital-card-view-modal.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import { ModalShell } from "@/components/custom/modal/modal-shell";
+import { Skeleton } from "@/components/ui/skeleton";
+import type { CodeType } from "@/constants/card-codes";
+import { closeModalUrl } from "@/lib/modal/modal-navigation";
+import { useWakeLock } from "@/hooks/use-wake-lock";
+import CardIcon from "@/app/(user)/digital-cards/components/card-icon";
+import CardCodePanel from "@/app/(user)/digital-cards/components/view/card-code-panel";
+import CardDetailRows from "@/app/(user)/digital-cards/components/view/card-detail-rows";
+import CardFaceImages from "@/app/(user)/digital-cards/components/view/card-face-images";
+import CardViewActions from "@/app/(user)/digital-cards/components/view/card-view-actions";
+import { useDigitalCard } from "@/app/(user)/digital-cards/hooks/use-digital-card";
+
+interface IDigitalCardViewModalProps {
+  open: boolean;
+  id: string;
+}
+
+export default function DigitalCardViewModal({
+  open,
+  id,
+}: IDigitalCardViewModalProps) {
+  const { card, isLoading, isError, notFound } = useDigitalCard(id, {
+    enabled: open,
+  });
+
+  // This modal exists to be held up at a till, so the screen must not dim mid-transaction.
+  useWakeLock(open && !!card);
+
+  return (
+    <ModalShell
+      open={open}
+      onOpenChange={(isOpen) => !isOpen && closeModalUrl()}
+      title={card?.cardName ?? "Kartica"}
+      description="Pokaži kod na blagajni."
+      srOnlyDescription
+      size="md"
+      headerExtra={
+        card ? (
+          <div
+            className="size-10 shrink-0 rounded-full ring-1 ring-black/10"
+            style={{ backgroundColor: card.cardColor }}
+          >
+            <CardIcon
+              iconImage={card.iconImage}
+              chainCode={card.chainCode}
+              storeName={card.storeName}
+            />
+          </div>
+        ) : undefined
+      }
+      footer={card ? <CardViewActions card={card} /> : undefined}
+    >
+      {isLoading ? (
+        <Skeleton className="h-64 w-full" />
+      ) : isError ? (
+        <p className="text-sm text-muted-foreground">
+          Greška pri učitavanju kartice. Pokušaj ponovo.
+        </p>
+      ) : notFound || !card ? (
+        <p className="text-sm text-muted-foreground">
+          Kartica nije pronađena. Možda je obrisana.
+        </p>
+      ) : (
+        <div className="space-y-4">
+          <CardDetailRows card={card} />
+
+          <CardCodePanel
+            codeValue={card.codeValue}
+            codeType={card.codeType as CodeType}
+          />
+
+          <CardFaceImages
+            frontImage={card.frontImage}
+            backImage={card.backImage}
+          />
+        </div>
+      )}
+    </ModalShell>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/hooks/use-card-images.ts b/frontend/src/app/(user)/digital-cards/hooks/use-card-images.ts
new file mode 100644
index 00000000..360fbc18
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/hooks/use-card-images.ts
@@ -0,0 +1,60 @@
+import { useCallback, useState } from "react";
+
+import type { DigitalCardDto } from "@/lib/api/types";
+
+export type CardImageSlot = "iconImage" | "frontImage" | "backImage";
+
+export interface ICardImages {
+  iconImage: string | null;
+  frontImage: string | null;
+  backImage: string | null;
+}
+
+const EMPTY_IMAGES: ICardImages = {
+  iconImage: null,
+  frontImage: null,
+  backImage: null,
+};
+
+function imagesOf(card: DigitalCardDto | null): ICardImages {
+  if (!card) return EMPTY_IMAGES;
+
+  return {
+    iconImage: card.iconImage,
+    frontImage: card.frontImage,
+    backImage: card.backImage,
+  };
+}
+
+/**
+ * The three base64 images live outside react-hook-form, like the settings avatar does:
+ * they would blow the localStorage draft quota and do not belong in dirty tracking. The
+ * modal merges them back in on submit and folds isDirty into its own dirty indicator.
+ */
+export function useCardImages(card: DigitalCardDto | null) {
+  const [images, setImages] = useState<ICardImages>(() => imagesOf(card));
+  const [isDirty, setIsDirty] = useState(false);
+  const [loadedId, setLoadedId] = useState<string | null>(card?.id ?? null);
+
+  // Adjusted during render rather than in an effect, the way use-lingering-target does it:
+  // an edit modal mounts before its card arrives, and a frame showing the previous card's
+  // images would be a real flash of the wrong data.
+  const cardId = card?.id ?? null;
+  if (cardId !== loadedId) {
+    setLoadedId(cardId);
+    setImages(imagesOf(card));
+    setIsDirty(false);
+  }
+
+  const setImage = useCallback((slot: CardImageSlot, value: string | null) => {
+    setImages((current) => ({ ...current, [slot]: value }));
+    setIsDirty(true);
+  }, []);
+
+  const resetImages = useCallback(() => {
+    setImages(imagesOf(card));
+    setIsDirty(false);
+  }, [card]);
+
+  return { images, setImage, resetImages, isDirty };
+}
diff --git a/frontend/src/app/(user)/digital-cards/hooks/use-digital-card-modal.ts b/frontend/src/app/(user)/digital-cards/hooks/use-digital-card-modal.ts
index 8cc70b2c..e8b0b218 100644
--- a/frontend/src/app/(user)/digital-cards/hooks/use-digital-card-modal.ts
+++ b/frontend/src/app/(user)/digital-cards/hooks/use-digital-card-modal.ts
@@ -21,11 +21,11 @@ export function useDigitalCardModal({
   const createMutation = digitalCardService.useCreateDigitalCard();
   const updateMutation = digitalCardService.useUpdateDigitalCard();
 
-  // Optimistic close: the modal closes immediately and reopens, with the draft
-  // still holding the values, only if the request fails.
+  // Optimistic close: the modal closes immediately and reopens only on failure.
   async function onSubmit(data: DigitalCardRequest) {
     closeModalUrl();
 
+    // A paused mutation resolves only on reconnect, so say so now.
     if (!onlineManager.isOnline()) {
       toast.info(
         "Izvan si mreže - promjena će se sinkronizirati kad se vratiš na mrežu.",
@@ -35,10 +35,10 @@ export function useDigitalCardModal({
     try {
       if (digitalCard) {
         await updateMutation.mutateAsync({ id: digitalCard.id, data });
-        toast.success("Digitalna kartica je uspješno ažurirana!");
+        toast.success("Kartica je uspješno ažurirana!");
       } else {
         await createMutation.mutateAsync(data);
-        toast.success("Digitalna kartica je uspješno kreirana!");
+        toast.success("Kartica je uspješno dodana!");
       }
 
       removeFormDraft(draftKey);
diff --git a/frontend/src/app/(user)/digital-cards/hooks/use-digital-card.ts b/frontend/src/app/(user)/digital-cards/hooks/use-digital-card.ts
new file mode 100644
index 00000000..23802227
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/hooks/use-digital-card.ts
@@ -0,0 +1,33 @@
+import { digitalCardService } from "@/lib/api";
+import type { DigitalCardDto } from "@/lib/api/types";
+
+interface IUseDigitalCardResult {
+  card: DigitalCardDto | null;
+  isLoading: boolean;
+  isError: boolean;
+  notFound: boolean;
+}
+
+/**
+ * Cards are read out of the user's own list rather than a by-id endpoint. That is what
+ * makes a deep link work offline: a by-id fetch has no cached entry to fall back on.
+ */
+export function useDigitalCard(
+  id: string | undefined,
+  { enabled = true }: { enabled?: boolean } = {},
+): IUseDigitalCardResult {
+  const cardsQuery = digitalCardService.useGetCurrentUserDigitalCards({
+    enabled: enabled && !!id,
+  });
+
+  const card = id
+    ? (cardsQuery.data?.find((item) => item.id === id) ?? null)
+    : null;
+
+  return {
+    card,
+    isLoading: !card && cardsQuery.isLoading,
+    isError: !card && cardsQuery.isError,
+    notFound: !!id && !card && !cardsQuery.isLoading && !cardsQuery.isError,
+  };
+}
diff --git a/frontend/src/app/(user)/digital-cards/hooks/use-store-name-options.ts b/frontend/src/app/(user)/digital-cards/hooks/use-store-name-options.ts
new file mode 100644
index 00000000..5c05ba3e
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/hooks/use-store-name-options.ts
@@ -0,0 +1,58 @@
+import { useMemo } from "react";
+
+import cijeneService from "@/lib/cijene-api";
+import { storeNameService } from "@/lib/api";
+import { getChainLabel } from "@/utils/labels";
+import { compareHr, normalizeForSearch } from "@/utils/strings";
+
+export interface IStoreOption {
+  /** The label shown and stored as storeName. */
+  label: string;
+  /** Set only for an official chain, which is what unlocks its logo and brand colour. */
+  chainCode: string | null;
+}
+
+interface IUseStoreNameOptionsResult {
+  officialOptions: IStoreOption[];
+  suggestedOptions: IStoreOption[];
+  isLoading: boolean;
+}
+
+export function useStoreNameOptions({
+  enabled = true,
+}: { enabled?: boolean } = {}): IUseStoreNameOptionsResult {
+  // Chain stats are public and cached for six hours, so they carry no enabled gate.
+  const chainsQuery = cijeneService.useGetChainStats();
+  const suggestionsQuery = storeNameService.useGetStoreNameSuggestions({
+    enabled,
+  });
+
+  const officialOptions = useMemo(() => {
+    const chains = chainsQuery.data?.chain_stats ?? [];
+
+    return chains
+      .map((chain) => ({
+        label: getChainLabel(chain.chain_code),
+        chainCode: chain.chain_code,
+      }))
+      .sort((a, b) => compareHr(a.label, b.label));
+  }, [chainsQuery.data]);
+
+  const suggestedOptions = useMemo(() => {
+    const officialKeys = new Set(
+      officialOptions.map((option) => normalizeForSearch(option.label)),
+    );
+
+    // The backend already orders by popularity, but a name that has since become an
+    // official chain would otherwise appear in both groups.
+    return (suggestionsQuery.data ?? [])
+      .filter((item) => !officialKeys.has(normalizeForSearch(item.name)))
+      .map((item) => ({ label: item.name, chainCode: null }));
+  }, [suggestionsQuery.data, officialOptions]);
+
+  return {
+    officialOptions,
+    suggestedOptions,
+    isLoading: chainsQuery.isLoading || suggestionsQuery.isLoading,
+  };
+}
diff --git a/frontend/src/components/custom/modal-router/entity-modal-outlet.tsx b/frontend/src/components/custom/modal-router/entity-modal-outlet.tsx
index 242c4d95..e0cf9f8f 100644
--- a/frontend/src/components/custom/modal-router/entity-modal-outlet.tsx
+++ b/frontend/src/components/custom/modal-router/entity-modal-outlet.tsx
@@ -15,6 +15,11 @@ const DigitalCardModal = dynamic(
     import("@/app/(user)/digital-cards/components/forms/digital-card-modal"),
   { ssr: false },
 );
+const DigitalCardViewModal = dynamic(
+  () =>
+    import("@/app/(user)/digital-cards/components/view/digital-card-view-modal"),
+  { ssr: false },
+);
 const AddToShoppingListModal = dynamic(
   () => import("@/app/products/components/forms/add-to-shopping-list-form"),
   { ssr: false },
@@ -54,19 +59,25 @@ export default function EntityModalOutlet({ target }: IEntityModalOutletProps) {
 
   switch (rendered.name) {
     case "shopping-list":
-    case "digital-card": {
-      const Modal =
-        rendered.name === "shopping-list"
-          ? ShoppingListModal
-          : DigitalCardModal;
       return (
-        <Modal
+        <ShoppingListModal
+          open={open}
+          action={rendered.action}
+          id={rendered.action === "edit" ? rendered.id : undefined}
+        />
+      );
+    case "digital-card":
+      // View is a separate modal rather than a mode of the form: it is a different job,
+      // reached by a different action, and shares only the card it reads.
+      return rendered.action === "view" ? (
+        <DigitalCardViewModal open={open} id={rendered.id} />
+      ) : (
+        <DigitalCardModal
           open={open}
           action={rendered.action}
           id={rendered.action === "edit" ? rendered.id : undefined}
         />
       );
-    }
     case "add-to-list":
       return <AddToShoppingListModal open={open} ean={rendered.ean} />;
     case "watchlist":
diff --git a/frontend/src/hooks/use-wake-lock.ts b/frontend/src/hooks/use-wake-lock.ts
new file mode 100644
index 00000000..0a712356
--- /dev/null
+++ b/frontend/src/hooks/use-wake-lock.ts
@@ -0,0 +1,53 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Holds the screen awake while enabled, for a barcode being shown to a cashier. Entirely
+ * best-effort: unsupported browsers, an insecure context and a low battery all reject the
+ * request, and none of that is worth telling the user about.
+ *
+ * There is no web API for screen brightness, so the code panel forces its own white
+ * background instead.
+ */
+export function useWakeLock(enabled: boolean) {
+  const sentinelRef = useRef<WakeLockSentinel | null>(null);
+
+  useEffect(() => {
+    if (!enabled || !("wakeLock" in navigator)) return;
+
+    let cancelled = false;
+
+    async function request() {
+      try {
+        const sentinel = await navigator.wakeLock.request("screen");
+        if (cancelled) {
+          await sentinel.release();
+          return;
+        }
+        sentinelRef.current = sentinel;
+      } catch {
+        // Nothing to recover: the screen simply dims as usual.
+      }
+    }
+
+    function release() {
+      sentinelRef.current?.release().catch(() => {});
+      sentinelRef.current = null;
+    }
+
+    // The browser drops the lock whenever the tab hides, so coming back has to retake it.
+    function handleVisibilityChange() {
+      if (document.visibilityState === "visible" && !sentinelRef.current) {
+        void request();
+      }
+    }
+
+    void request();
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+
+    return () => {
+      cancelled = true;
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      release();
+    };
+  }, [enabled]);
+}
diff --git a/frontend/src/lib/modal/modal-registry.ts b/frontend/src/lib/modal/modal-registry.ts
index d6719f60..ee25bc99 100644
--- a/frontend/src/lib/modal/modal-registry.ts
+++ b/frontend/src/lib/modal/modal-registry.ts
@@ -25,6 +25,7 @@ export type ModalTarget =
   | { name: "shopping-list"; action: "edit"; id: string }
   | { name: "digital-card"; action: "new" }
   | { name: "digital-card"; action: "edit"; id: string }
+  | { name: "digital-card"; action: "view"; id: string }
   | { name: "add-to-list"; ean: string }
   | { name: "product-actions"; ean: string }
   | { name: "watchlist"; ean: string; watchType?: WatchTypeParam };
@@ -70,9 +71,13 @@ export function parseModalParam(
     case "settings":
       return { name, tab: sub && isSettingsTab(sub) ? sub : "profil" };
     case "shopping-list":
+      if (sub === "new") return { name, action: "new" };
+      if (sub === "edit" && id) return { name, action: "edit", id };
+      return null;
     case "digital-card":
       if (sub === "new") return { name, action: "new" };
       if (sub === "edit" && id) return { name, action: "edit", id };
+      if (sub === "view" && id) return { name, action: "view", id };
       return null;
     case "add-to-list":
     case "product-actions":

From b2b522f7c4f3db221cd7bdd7e22e1b0a72a94df2 Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Thu, 30 Jul 2026 10:54:31 +0200
Subject: [PATCH 07/14] feat(digital-cards): Add the wallet page

Changes:
- Add the /digital-cards page and its client: auth gate, search, sort, empty state
- Add the card grid, two per row on mobile and three on desktop
- Add the card tile: a 1.5:1 plastic object that flips to its code on hover
- Add the pinned group, kept on top and separated by a divider
- Add the sort control over six modes, persisted per user
- Replace the old list row with the tile

The card is the feature, so it is drawn as a physical object rather than a table
row: a colour gradient with a specular band, a light catching top edge and a
raised icon medallion, which is what makes it scannable by eye in a wallet.

Notes:
- The tile is a div with a full bleed overlay button, not a wrapping button, so the
  pin toggle can sit above it without nesting interactive elements.
- Both controls live outside the flipping element, since a rotated button would be
  mirrored and unclickable, and the back face is aria-hidden because the code's real
  home is the detail modal that every input method can reach.
- motion-safe gates the transform itself, not just the transition, so reduced motion
  means no flip at all rather than an instant snap. Tailwind's hover variant already
  wraps in @media (hover: hover), so a tap never triggers it.
- codeValue is deliberately not searchable: the search term goes into ?q=, and a card
  number does not belong in a URL or in history.
- Sort persists as a bare string and is validated on read, following storeOptimizeMode.
- No list and grid toggle, unlike the old page. One visual grid is the whole point.
---
 .../components/card-face-back.tsx             |  39 +++++
 .../components/card-face-front.tsx            |  57 +++++++
 .../components/create-digital-card-button.tsx |  34 ++--
 .../components/digital-card-item.tsx          | 101 -----------
 .../components/digital-card-tile.tsx          |  40 +++++
 .../components/digital-cards-client.tsx       | 161 +++++++-----------
 .../components/digital-cards-empty.tsx        |  22 +++
 .../components/digital-cards-grid.tsx         |  54 ++++++
 .../components/digital-cards-sort-select.tsx  |  32 ++++
 .../hooks/use-digital-cards-sort.ts           |  29 ++++
 .../src/app/(user)/digital-cards/page.tsx     |   6 +-
 frontend/src/typings/local-storage.ts         |   1 +
 frontend/src/utils/browser/local-storage.ts   |   1 +
 .../utils/browser/storage/digital-cards.ts    |  13 ++
 14 files changed, 371 insertions(+), 219 deletions(-)
 create mode 100644 frontend/src/app/(user)/digital-cards/components/card-face-back.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/card-face-front.tsx
 delete mode 100644 frontend/src/app/(user)/digital-cards/components/digital-card-item.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/digital-card-tile.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/digital-cards-empty.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/digital-cards-grid.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/components/digital-cards-sort-select.tsx
 create mode 100644 frontend/src/app/(user)/digital-cards/hooks/use-digital-cards-sort.ts
 create mode 100644 frontend/src/utils/browser/storage/digital-cards.ts

diff --git a/frontend/src/app/(user)/digital-cards/components/card-face-back.tsx b/frontend/src/app/(user)/digital-cards/components/card-face-back.tsx
new file mode 100644
index 00000000..2a9deced
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/card-face-back.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import CardCode from "@/app/(user)/digital-cards/components/card-code";
+import type { CodeType } from "@/constants/card-codes";
+import type { DigitalCardDto } from "@/lib/api/types";
+
+interface ICardFaceBackProps {
+  card: DigitalCardDto;
+}
+
+/**
+ * Decorative quick access for a mouse, so it is hidden from assistive tech: the code's
+ * real home is the detail modal, which every input method can reach.
+ */
+export default function CardFaceBack({ card }: ICardFaceBackProps) {
+  return (
+    <div
+      aria-hidden="true"
+      className="absolute inset-0 overflow-hidden rounded-xl bg-white p-3 [backface-visibility:hidden] [transform:rotateY(180deg)]"
+      style={{
+        boxShadow: `inset 0 0 0 2px color-mix(in oklab, ${card.cardColor} 55%, white)`,
+      }}
+    >
+      {/* The magnetic stripe of the real thing, in the card's own colour. */}
+      <div
+        className="absolute inset-x-0 top-0 h-2.5"
+        style={{ backgroundColor: card.cardColor }}
+      />
+
+      <div className="grid size-full place-items-center pt-2">
+        <CardCode
+          codeValue={card.codeValue}
+          codeType={card.codeType as CodeType}
+          className="max-h-full [&_p]:text-sm"
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/card-face-front.tsx b/frontend/src/app/(user)/digital-cards/components/card-face-front.tsx
new file mode 100644
index 00000000..4b28a6dc
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/card-face-front.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import CardIcon from "@/app/(user)/digital-cards/components/card-icon";
+import type { DigitalCardDto } from "@/lib/api/types";
+import { formatDate } from "@/utils/strings";
+
+interface ICardFaceFrontProps {
+  card: DigitalCardDto;
+}
+
+/**
+ * Reads as a piece of plastic rather than a coloured div: a diagonal sheen band, a
+ * light-catching top edge and a raised medallion are what sell it at this size.
+ */
+export default function CardFaceFront({ card }: ICardFaceFrontProps) {
+  return (
+    <div
+      className="absolute inset-0 overflow-hidden rounded-xl [backface-visibility:hidden]"
+      style={{
+        background: `linear-gradient(140deg,
+          color-mix(in oklab, ${card.cardColor} 86%, white) 0%,
+          ${card.cardColor} 48%,
+          color-mix(in oklab, ${card.cardColor} 82%, black) 100%)`,
+        boxShadow:
+          "inset 0 1px 0 rgba(255,255,255,0.28), inset 0 -1px 0 rgba(0,0,0,0.18)",
+      }}
+    >
+      {/* Specular band, the detail that makes a flat fill look moulded. */}
+      <div
+        aria-hidden="true"
+        className="pointer-events-none absolute -inset-x-8 -top-1/3 h-2/3 rotate-[18deg] bg-linear-to-b from-white/22 to-transparent"
+      />
+
+      <div className="relative flex size-full flex-col items-center justify-center gap-1.5 p-3">
+        <div className="size-12 shrink-0 rounded-full ring-1 ring-black/10 shadow-md sm:size-14">
+          <CardIcon
+            iconImage={card.iconImage}
+            chainCode={card.chainCode}
+            storeName={card.storeName}
+          />
+        </div>
+
+        <p className="line-clamp-1 text-[0.7rem] font-semibold uppercase tracking-[0.14em] text-white/90 drop-shadow-sm">
+          {card.storeName}
+        </p>
+      </div>
+
+      <p className="absolute bottom-2 left-3 max-w-[62%] truncate text-xs font-semibold text-white drop-shadow-sm">
+        {card.cardName}
+      </p>
+
+      <p className="absolute bottom-2 right-3 text-[0.65rem] tabular-nums text-white/75">
+        {formatDate(card.updatedAt)}
+      </p>
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/create-digital-card-button.tsx b/frontend/src/app/(user)/digital-cards/components/create-digital-card-button.tsx
index 90e7f871..7a2bd285 100644
--- a/frontend/src/app/(user)/digital-cards/components/create-digital-card-button.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/create-digital-card-button.tsx
@@ -1,29 +1,23 @@
 "use client";
 
 import { Plus } from "lucide-react";
+
 import { Button } from "@/components/ui/button";
 import ResponsiveLabel from "@/components/custom/common/responsive-label";
+import { openModalUrl } from "@/lib/modal/modal-navigation";
 
-interface ICreateDigitalCardButtonProps {
-  onCreateClick: () => void;
-}
-
-export default function CreateDigitalCardButton({
-  onCreateClick,
-}: ICreateDigitalCardButtonProps) {
-  const buttonText = "Dodaj digitalnu karticu";
-
+export default function CreateDigitalCardButton() {
   return (
-    <>
-      <Button
-        type="button"
-        effect="expandIcon"
-        onClick={onCreateClick}
-        icon={Plus}
-        iconPlacement="left"
-      >
-        <ResponsiveLabel full={buttonText} short="Dodaj karticu" />
-      </Button>
-    </>
+    <Button
+      type="button"
+      variant="primary"
+      icon={Plus}
+      iconPlacement="left"
+      effect="shineHover"
+      // No aria-label: ResponsiveLabel already supplies the accessible name per breakpoint.
+      onClick={() => openModalUrl({ name: "digital-card", action: "new" })}
+    >
+      <ResponsiveLabel full="Dodaj digitalnu karticu" short="Dodaj karticu" />
+    </Button>
   );
 }
diff --git a/frontend/src/app/(user)/digital-cards/components/digital-card-item.tsx b/frontend/src/app/(user)/digital-cards/components/digital-card-item.tsx
deleted file mode 100644
index 3e099514..00000000
--- a/frontend/src/app/(user)/digital-cards/components/digital-card-item.tsx
+++ /dev/null
@@ -1,101 +0,0 @@
-"use client";
-
-import { DigitalCardDto } from "@/lib/api/types";
-import { Card } from "@/components/ui/card";
-import { Badge } from "@/components/ui/badge";
-import { Button } from "@/components/ui/button";
-import { MoreVertical, Edit, Trash2 } from "lucide-react";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
-import { digitalCardService } from "@/lib/api";
-import { toast } from "sonner";
-import { useQueryClient } from "@tanstack/react-query";
-import { formatDate } from "@/utils/strings";
-
-interface IDigitalCardItemProps {
-  digitalCard: DigitalCardDto;
-  handleEdit: (digitalCard: DigitalCardDto) => void;
-}
-
-export default function DigitalCardItem({
-  digitalCard,
-  handleEdit,
-}: IDigitalCardItemProps) {
-  const queryClient = useQueryClient();
-  const deleteDigitalCardMutation = digitalCardService.useDeleteDigitalCard();
-
-  async function handleDelete(d: DigitalCardDto) {
-    if (confirm(`Sigurno želiš obrisati karticu "${d.title}"?`)) {
-      deleteDigitalCardMutation.mutate(d.id, {
-        onSuccess: async () => {
-          toast.success("Kartica obrisana.");
-          await queryClient.invalidateQueries({
-            queryKey: ["digitalCards"],
-          });
-        },
-        onError: (error: Error) => {
-          toast.error("Greška prilikom brisanja: " + error.message);
-        },
-      });
-    }
-  }
-
-  return (
-    <Card className="p-4 hover:shadow-md transition-shadow">
-      <div className="flex items-start justify-between mb-3">
-        <div className="flex-1">
-          <h3 className="font-semibold text-lg text-pretty">
-            {digitalCard.title}
-          </h3>
-          <div className="flex items-center gap-2 mt-1">
-            <Badge variant="primary">{digitalCard.type}</Badge>
-            <Badge variant="outline">{digitalCard.codeType}</Badge>
-          </div>
-        </div>
-
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button variant="ghost" size="sm" className="h-8 w-8 p-0">
-              <MoreVertical className="h-4 w-4" />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end">
-            <DropdownMenuItem onClick={() => handleEdit(digitalCard)}>
-              <Edit className="h-4 w-4 mr-2" />
-              Uredi
-            </DropdownMenuItem>
-
-            <DropdownMenuItem
-              onClick={() => handleDelete(digitalCard)}
-              className="text-red-700"
-            >
-              <Trash2 className="h-4 w-4 mr-2" />
-              Obriši
-            </DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-
-      <div className="space-y-3">
-        <div
-          className="font-mono text-lg p-3 bg-gray-50 rounded border"
-          style={{ backgroundColor: digitalCard.color || undefined }}
-        >
-          {digitalCard.value}
-        </div>
-
-        {digitalCard.note && (
-          <p className="text-sm text-gray-600">{digitalCard.note}</p>
-        )}
-
-        <p className="text-xs text-gray-500">
-          Stvoreno {formatDate(digitalCard.createdAt)}
-        </p>
-      </div>
-    </Card>
-  );
-}
diff --git a/frontend/src/app/(user)/digital-cards/components/digital-card-tile.tsx b/frontend/src/app/(user)/digital-cards/components/digital-card-tile.tsx
new file mode 100644
index 00000000..51e780de
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/digital-card-tile.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import CardFaceBack from "@/app/(user)/digital-cards/components/card-face-back";
+import CardFaceFront from "@/app/(user)/digital-cards/components/card-face-front";
+import PinToggleButton from "@/app/(user)/digital-cards/components/pin-toggle-button";
+import { openModalUrl } from "@/lib/modal/modal-navigation";
+import type { DigitalCardDto } from "@/lib/api/types";
+
+interface IDigitalCardTileProps {
+  card: DigitalCardDto;
+}
+
+/**
+ * The open control is a full-bleed overlay button rather than a wrapping one, so the pin
+ * toggle can sit above it without nesting interactive elements. Both live outside the
+ * flipping element: a rotated button would be mirrored and unclickable.
+ */
+export default function DigitalCardTile({ card }: IDigitalCardTileProps) {
+  return (
+    <div className="group relative aspect-3/2 w-full [perspective:1200px]">
+      <div className="relative size-full rounded-xl shadow-md transition-shadow duration-500 [transform-style:preserve-3d] group-hover:shadow-xl motion-safe:transition-transform motion-safe:duration-500 motion-safe:md:group-hover:[transform:rotateY(180deg)]">
+        <CardFaceFront card={card} />
+        <CardFaceBack card={card} />
+      </div>
+
+      <button
+        type="button"
+        onClick={() =>
+          openModalUrl({ name: "digital-card", action: "view", id: card.id })
+        }
+        aria-label={`Otvori karticu ${card.cardName}`}
+        className="absolute inset-0 z-10 cursor-pointer rounded-xl focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:outline-none"
+      />
+
+      <div className="absolute right-2 top-2 z-20">
+        <PinToggleButton card={card} revealOnHover />
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/digital-cards-client.tsx b/frontend/src/app/(user)/digital-cards/components/digital-cards-client.tsx
index 98dfdeeb..0071b88b 100644
--- a/frontend/src/app/(user)/digital-cards/components/digital-cards-client.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/digital-cards-client.tsx
@@ -1,23 +1,23 @@
 "use client";
 
-import { Suspense } from "react";
+import { Suspense, useMemo } from "react";
 import { usePathname } from "next/navigation";
-import { Search, Plus, CreditCard } from "lucide-react";
-import { Button } from "@/components/ui/button";
+import { CreditCard, Search } from "lucide-react";
+
 import SearchBar from "@/components/custom/search/search-bar";
 import SearchBarSkeleton from "@/components/custom/search/search-bar-skeleton";
-import DigitalCardItem from "@/app/(user)/digital-cards/components/digital-card-item";
-import NoResults from "@/components/custom/common/no-results";
+import BlockLoadingSpinner from "@/components/custom/common/block-loading-spinner";
 import LoginRequired from "@/components/custom/common/login-required";
-import CreateDigitalCardButton from "@/app/(user)/digital-cards/components/create-digital-card-button";
-import { DigitalCardDto } from "@/lib/api/types";
-import { useViewMode } from "@/hooks/use-view-mode";
-import { filterByFields } from "@/utils/generic";
+import NoResults from "@/components/custom/common/no-results";
 import { digitalCardService } from "@/lib/api";
 import { useUser } from "@/context/user-context";
-import { AnimatedGroup } from "@/components/custom/animation/animated-group";
-import { openModalUrl } from "@/lib/modal/modal-navigation";
-import BlockLoadingSpinner from "@/components/custom/common/block-loading-spinner";
+import { filterByFields } from "@/utils/generic";
+import CreateDigitalCardButton from "@/app/(user)/digital-cards/components/create-digital-card-button";
+import DigitalCardsEmpty from "@/app/(user)/digital-cards/components/digital-cards-empty";
+import DigitalCardsGrid from "@/app/(user)/digital-cards/components/digital-cards-grid";
+import DigitalCardsSortSelect from "@/app/(user)/digital-cards/components/digital-cards-sort-select";
+import { useDigitalCardsSort } from "@/app/(user)/digital-cards/hooks/use-digital-cards-sort";
+import { groupAndSortCards } from "@/app/(user)/digital-cards/utils/card-sorting";
 
 interface IDigitalCardsClientProps {
   query: string;
@@ -27,111 +27,80 @@ export default function DigitalCardsClient({
   query,
 }: IDigitalCardsClientProps) {
   const pathname = usePathname();
-  const [viewMode] = useViewMode(pathname, "grid");
+  const [sort, setSort] = useDigitalCardsSort();
 
   const { isAuthenticated, isLoading: userLoading } = useUser();
-  const { data: digitalCards = [], isLoading } =
-    digitalCardService.useGetUserDigitalCards({ enabled: isAuthenticated });
+  const { data: cards = [], isLoading } =
+    digitalCardService.useGetCurrentUserDigitalCards({
+      enabled: isAuthenticated,
+    });
 
   const isUserLoading = userLoading || isLoading;
 
-  function handleEdit(digitalCard: DigitalCardDto) {
-    openModalUrl({ name: "digital-card", action: "edit", id: digitalCard.id });
-  }
-
-  function handleCreate() {
-    openModalUrl({ name: "digital-card", action: "new" });
-  }
-
-  const matchingDigitalCards = filterByFields(digitalCards, query, [
-    "title",
-    "type",
+  // codeValue is deliberately not searchable: a card number must never reach the ?q= URL.
+  const matchingCards = filterByFields(cards, query, [
+    "cardName",
+    "storeName",
     "note",
   ]);
 
+  const { pinned, rest } = useMemo(
+    () => groupAndSortCards(matchingCards, sort),
+    [matchingCards, sort],
+  );
+
   if (!userLoading && !isAuthenticated) {
     return (
       <LoginRequired
         title="Digitalne kartice"
-        description="Digitalne kartice ti omogućuju da sve svoje kartice vjernosti držiš na jednom mjestu, uvijek pri ruci."
+        description="Digitalne kartice ti omogućuju da sve kartice vjernosti nosiš u mobitelu i pokažeš ih na blagajni, bez interneta."
         icon={<CreditCard className="size-12 text-primary" />}
       />
     );
   }
 
   return (
-    <>
-      <div className="space-y-4">
-        <Suspense fallback={<SearchBarSkeleton submitButtonLocation="none" />}>
-          <SearchBar
-            placeholder="Pretraži digitalne kartice..."
-            searchRoute={pathname}
-            clearable={true}
-            submitButtonLocation="none"
-            autoSearch={true}
-            disabled={!isUserLoading && digitalCards.length === 0}
-          />
-        </Suspense>
+    <div className="space-y-4">
+      <Suspense fallback={<SearchBarSkeleton submitButtonLocation="none" />}>
+        <SearchBar
+          placeholder="Pretraži kartice..."
+          searchRoute={pathname}
+          clearable={true}
+          submitButtonLocation="none"
+          autoSearch={true}
+          disabled={!isUserLoading && cards.length === 0}
+        />
+      </Suspense>
 
-        <div className="flex items-center justify-between gap-4">
-          <h3>
-            {query.length > 0
-              ? `Rezultati pretrage za "${query}" (${matchingDigitalCards.length})`
-              : `Moje digitalne kartice${
-                  isUserLoading ? "" : ` (${matchingDigitalCards.length})`
-                }`}
-          </h3>
+      <div className="flex items-center justify-between gap-4">
+        <h3>
+          {query.length > 0
+            ? `Rezultati pretrage za "${query}" (${matchingCards.length})`
+            : `Moje kartice${
+                isUserLoading ? "" : ` (${matchingCards.length})`
+              }`}
+        </h3>
 
-          <CreateDigitalCardButton onCreateClick={handleCreate} />
-        </div>
-
-        {isUserLoading ? (
-          <div className="grid place-items-center">
-            <BlockLoadingSpinner />
-          </div>
-        ) : matchingDigitalCards.length > 0 ? (
-          <AnimatedGroup
-            className={
-              viewMode === "grid"
-                ? "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4"
-                : "space-y-4"
-            }
-            preset="fade"
-          >
-            {matchingDigitalCards.map((digitalCard) => (
-              <DigitalCardItem
-                key={digitalCard.id}
-                handleEdit={handleEdit}
-                digitalCard={digitalCard}
-              />
-            ))}
-          </AnimatedGroup>
-        ) : query ? (
-          <NoResults
-            icon={<Search className="size-12 text-gray-400 mx-auto mb-4" />}
-          />
-        ) : (
-          <div className="text-center py-12">
-            <CreditCard className="size-12 text-gray-400 mx-auto mb-4" />
-            <h3 className="text-lg font-semibold text-foreground mb-2">
-              Nema digitalnih kartica
-            </h3>
+        <CreateDigitalCardButton />
+      </div>
 
-            <p className="text-gray-600 mb-6">
-              Stvori svoju prvu digitalnu karticu…
-            </p>
+      {!isUserLoading && cards.length > 1 && (
+        <DigitalCardsSortSelect value={sort} onValueChange={setSort} />
+      )}
 
-            <Button
-              effect="shineHover"
-              icon={Plus}
-              iconPlacement="left"
-              onClick={handleCreate}
-            >
-              Dodaj digitalnu karticu
-            </Button>
-          </div>
-        )}
-      </div>
-    </>
+      {isUserLoading ? (
+        <div className="grid place-items-center">
+          <BlockLoadingSpinner />
+        </div>
+      ) : matchingCards.length > 0 ? (
+        <DigitalCardsGrid pinned={pinned} rest={rest} />
+      ) : query ? (
+        <NoResults
+          icon={<Search className="mx-auto mb-4 size-12 text-gray-400" />}
+        />
+      ) : (
+        <DigitalCardsEmpty />
+      )}
+    </div>
   );
 }
diff --git a/frontend/src/app/(user)/digital-cards/components/digital-cards-empty.tsx b/frontend/src/app/(user)/digital-cards/components/digital-cards-empty.tsx
new file mode 100644
index 00000000..16d2ab57
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/digital-cards-empty.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import { CreditCard } from "lucide-react";
+
+import CreateDigitalCardButton from "@/app/(user)/digital-cards/components/create-digital-card-button";
+
+export default function DigitalCardsEmpty() {
+  return (
+    <div className="flex flex-col items-center gap-3 rounded-lg border border-dashed p-8 text-center">
+      <CreditCard aria-hidden="true" className="size-10 text-primary" />
+
+      <h3 className="text-lg font-semibold">Još nemaš spremljenih kartica</h3>
+
+      <p className="max-w-sm text-sm text-muted-foreground">
+        Spremi kartice vjernosti koje već koristiš i imaj ih na blagajni bez
+        vađenja novčanika. Rade i bez interneta.
+      </p>
+
+      <CreateDigitalCardButton />
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/digital-cards-grid.tsx b/frontend/src/app/(user)/digital-cards/components/digital-cards-grid.tsx
new file mode 100644
index 00000000..6619b3c3
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/digital-cards-grid.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import { Pin } from "lucide-react";
+
+import { AnimatedGroup } from "@/components/custom/animation/animated-group";
+import DigitalCardTile from "@/app/(user)/digital-cards/components/digital-card-tile";
+import type { DigitalCardDto } from "@/lib/api/types";
+
+interface IDigitalCardsGridProps {
+  pinned: DigitalCardDto[];
+  rest: DigitalCardDto[];
+}
+
+const GRID_CLASSES = "grid grid-cols-2 gap-3 sm:gap-4 lg:grid-cols-3";
+
+export default function DigitalCardsGrid({
+  pinned,
+  rest,
+}: IDigitalCardsGridProps) {
+  return (
+    <div className="space-y-4">
+      {pinned.length > 0 && (
+        <section aria-label="Prikvačene kartice" className="space-y-2">
+          <h4 className="flex items-center gap-1.5 text-sm font-medium text-muted-foreground">
+            <Pin aria-hidden="true" className="size-3.5" />
+            Prikvačene
+          </h4>
+
+          <AnimatedGroup preset="fade" className={GRID_CLASSES}>
+            {pinned.map((card) => (
+              <DigitalCardTile key={card.id} card={card} />
+            ))}
+          </AnimatedGroup>
+        </section>
+      )}
+
+      {rest.length > 0 && (
+        <section
+          aria-label={pinned.length > 0 ? "Ostale kartice" : "Kartice"}
+          className="space-y-2"
+        >
+          {/* The divider only earns its place once there is something above it. */}
+          {pinned.length > 0 && <hr className="border-border" />}
+
+          <AnimatedGroup preset="fade" className={GRID_CLASSES}>
+            {rest.map((card) => (
+              <DigitalCardTile key={card.id} card={card} />
+            ))}
+          </AnimatedGroup>
+        </section>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/components/digital-cards-sort-select.tsx b/frontend/src/app/(user)/digital-cards/components/digital-cards-sort-select.tsx
new file mode 100644
index 00000000..b1dcee01
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/components/digital-cards-sort-select.tsx
@@ -0,0 +1,32 @@
+"use client";
+
+import LabeledSelect from "@/components/custom/common/labeled-select";
+import {
+  CARD_SORT_LABELS,
+  CARD_SORT_MODES,
+  type CardSortMode,
+} from "@/app/(user)/digital-cards/utils/card-sorting";
+
+interface IDigitalCardsSortSelectProps {
+  value: CardSortMode;
+  onValueChange: (value: CardSortMode) => void;
+}
+
+const OPTIONS = CARD_SORT_MODES.map((value) => ({
+  value,
+  label: CARD_SORT_LABELS[value],
+}));
+
+export default function DigitalCardsSortSelect({
+  value,
+  onValueChange,
+}: IDigitalCardsSortSelectProps) {
+  return (
+    <LabeledSelect
+      label="Sortiraj"
+      value={value}
+      onValueChange={onValueChange}
+      options={OPTIONS}
+    />
+  );
+}
diff --git a/frontend/src/app/(user)/digital-cards/hooks/use-digital-cards-sort.ts b/frontend/src/app/(user)/digital-cards/hooks/use-digital-cards-sort.ts
new file mode 100644
index 00000000..bd8f652c
--- /dev/null
+++ b/frontend/src/app/(user)/digital-cards/hooks/use-digital-cards-sort.ts
@@ -0,0 +1,29 @@
+import { useEffect, useState } from "react";
+
+import {
+  getDigitalCardSort,
+  setDigitalCardSort,
+} from "@/utils/browser/local-storage";
+import {
+  DEFAULT_CARD_SORT,
+  isCardSortMode,
+  type CardSortMode,
+} from "@/app/(user)/digital-cards/utils/card-sorting";
+
+/** Storage keeps a bare string, so the stored value is validated on the way back in. */
+export function useDigitalCardsSort() {
+  const [sort, setSort] = useState<CardSortMode>(DEFAULT_CARD_SORT);
+
+  // Hydrated after mount, so the server render and the first client render agree.
+  useEffect(() => {
+    const stored = getDigitalCardSort();
+    if (isCardSortMode(stored)) setSort(stored);
+  }, []);
+
+  function updateSort(mode: CardSortMode) {
+    setSort(mode);
+    setDigitalCardSort(mode);
+  }
+
+  return [sort, updateSort] as const;
+}
diff --git a/frontend/src/app/(user)/digital-cards/page.tsx b/frontend/src/app/(user)/digital-cards/page.tsx
index 134c840e..71d3b7b3 100644
--- a/frontend/src/app/(user)/digital-cards/page.tsx
+++ b/frontend/src/app/(user)/digital-cards/page.tsx
@@ -1,10 +1,12 @@
 import { Metadata } from "next";
+
 import DigitalCardsClient from "@/app/(user)/digital-cards/components/digital-cards-client";
 import { readSearchParam } from "@/utils/generic";
 
 export const metadata: Metadata = {
-  title: "Moje digitalne kartice",
-  description: "Pregled i upravljanje digitalnim karticama.",
+  title: "Digitalne kartice",
+  description:
+    "Sve kartice vjernosti na jednom mjestu, dostupne i bez interneta.",
 };
 
 export default async function DigitalCardsPage(
diff --git a/frontend/src/typings/local-storage.ts b/frontend/src/typings/local-storage.ts
index 6a7cc53e..2605d024 100644
--- a/frontend/src/typings/local-storage.ts
+++ b/frontend/src/typings/local-storage.ts
@@ -43,6 +43,7 @@ export interface IAppData {
   lastLoginMethod?: LoginMethod;
   installBannerDismissedAt?: number; // Epoch ms of last "install app" banner dismissal; re-shown after the snooze window
   storeOptimizeMode?: string; // Preferred store-list sort, shared across all shopping lists
+  digitalCardSort?: string; // Preferred card sort, shared across the whole wallet
   preferredCameraId?: string; // Manually chosen scanner camera; absent means auto-pick
   formDrafts?: Record<string, IFormDraft>; // Unsaved modal-form drafts keyed per modal
   [key: string]: unknown;
diff --git a/frontend/src/utils/browser/local-storage.ts b/frontend/src/utils/browser/local-storage.ts
index e266cc4f..4878ef50 100644
--- a/frontend/src/utils/browser/local-storage.ts
+++ b/frontend/src/utils/browser/local-storage.ts
@@ -3,6 +3,7 @@ export * from "@/utils/browser/storage/core";
 export * from "@/utils/browser/storage/view-mode";
 export * from "@/utils/browser/storage/products";
 export * from "@/utils/browser/storage/shopping-lists";
+export * from "@/utils/browser/storage/digital-cards";
 export * from "@/utils/browser/storage/auth";
 export * from "@/utils/browser/storage/scanner";
 export * from "@/utils/browser/storage/pwa";
diff --git a/frontend/src/utils/browser/storage/digital-cards.ts b/frontend/src/utils/browser/storage/digital-cards.ts
new file mode 100644
index 00000000..e901f82b
--- /dev/null
+++ b/frontend/src/utils/browser/storage/digital-cards.ts
@@ -0,0 +1,13 @@
+import { getAppStorage, setAppStorage } from "@/utils/browser/storage/core";
+
+/**
+ * Preferred card sort, shared across the whole wallet.
+ * Returns undefined when nothing is stored; the caller validates the value.
+ */
+export function getDigitalCardSort(): string | undefined {
+  return getAppStorage().digitalCardSort;
+}
+
+export function setDigitalCardSort(mode: string) {
+  setAppStorage({ digitalCardSort: mode });
+}

From 5eaac33bc6c23fd7cecf753716325c6fd84a1244 Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Thu, 30 Jul 2026 10:54:43 +0200
Subject: [PATCH 08/14] feat(digital-cards): Activate the nav, PWA shortcut and
 landing entries

Changes:
- Drop comingSoon from the Kartice navigation item, unlocking it for everyone
- Enable the bottom nav long press, which opens a new card
- Uncomment the landing feature card's link
- Add the digital-cards shortcut glyph to the icon generator and generate both tiles
- State the PWA shortcut order explicitly instead of inheriting it from the nav
- Add an onboarding v2 TODO to nudge saving cards during onboarding

These are the reservations the earlier deletion left behind, now filled in rather
than recreated, which is why the bottom bar keeps its five cells and its symmetry.

Notes:
- Android surfaces only three shortcuts (Chrome keeps the fourth for Site settings),
  so the order decides what a phone shows. It is now Skeniraj, Kartice, Popisi, with
  Pracenje fourth and desktop only. Scanning leads as the fastest path from launcher
  to a price, and cards earn second place as a till errand rather than a browse.
  That resolves the pick-the-final-three question in #127.
- The order is stated in pwa-shortcuts.ts rather than inherited from navigation.ts,
  where the sequence is about the sidebar: a reshuffle there would otherwise drop a
  shortcut off phones silently.
- Both icon tiles are required and differ: the maskable one stays full bleed because
  Android fills transparent corners, and the any one keeps the brand corner radius.
---
 .../brand/shortcuts/digital-cards-any.png     | Bin 0 -> 3356 bytes
 .../public/brand/shortcuts/digital-cards.png  | Bin 0 -> 2508 bytes
 frontend/scripts/generate-shortcut-icons.mjs  |   3 ++-
 frontend/src/app/(root)/data/features.ts      |   3 +--
 .../custom/bottom-nav/bottom-nav-items.ts     |   4 +--
 .../settings/onboarding/onboarding-steps.ts   |   2 ++
 frontend/src/constants/navigation.ts          |   2 --
 frontend/src/constants/pwa-shortcuts.ts       |  25 +++++++++++++++---
 8 files changed, 28 insertions(+), 11 deletions(-)
 create mode 100644 frontend/public/brand/shortcuts/digital-cards-any.png
 create mode 100644 frontend/public/brand/shortcuts/digital-cards.png

diff --git a/frontend/public/brand/shortcuts/digital-cards-any.png b/frontend/public/brand/shortcuts/digital-cards-any.png
new file mode 100644
index 0000000000000000000000000000000000000000..fd3d5562d65bc6e11c44e7c75ca58a97e1f765bb
GIT binary patch
literal 3356
zcmb_ec|4SD_rGQ^27_VjJVIGVH9|_sI+jXyA<M{;vW%@Bh0GuxOQgtdY{|ZqEs;SF
zdXm9Imh6?3bsDl{d2fEdf8YP!Kd$?}uJ83dpL6c>IrsOR7}F~Toa`d(002%SLp^io
zO+8ph1oSi?_hJPArg>9W*Yu`~3jjhXp^sWG!Tp3fHHWR9+Hjs#;S-ZKW-+^DL5{k@
zvw3u|h_PdqduL)pC*yryiN|01o^1J}onqTe;klCR`4vOCQIF%Qxa>@6Kko+xIZmds
zCVy)-Lr;kC#n$t4ZPf)ymArB^r4P^~T$&_%z8d1#CDtC}ys$LxmZ^g7yJ{_!g8!bY
z8ZLXs@~r8cSptiu^@&ZV<v@KQs^GNp<@X3YQ|G06`MYeZA`ACKlF#7W{>B)Y{wkz+
z(qq0@#+{VD*6$0FMRLEYpBZX<uv6cRm2TZ|jjciUvBpawG41;XMGfg}Xad63sWliq
z`fBv!(;GbZa>TxQ^V&!Eo$=42S#;gZB5xz>Dt_&`v&=2zir2ObD%me}bnAX%SP_a*
zL!uT9YemoC4x^mKlnyO;6tS)47w6|$r<ySf(I_aRY`%uJ0RS+~A1qj1u(>Ay91%u(
z+Ll3COW8!Pl&`{_CUCBv-WKU?H!ih?>d?{gU6}s$ay?z&-d#-BTbBLAryttdAI(R(
z#=IAB7AjbXT*}mS2(-`|Gz<Ut@8$E}O4+rw$Utvzdc{D_z`u9uo@qS)W}EZ5EYOY~
z`YE7yw|OOC;@x`6_)gBkz2yyBz@!YXo1(Q!H2-nu6#I_Y`j`1PZ2Nhv2isy1HvMO?
z1E%G|@xMJMW~y4~)RhpEkcpsUJkPJ=1z+Y<!i@VF<sRMPETlzuT(|ta1dCcS|8YaT
z8k_#D@_7O4H7RUHEl}VyMx3<{d}I-*jLo1_x7e5snD`{JtmXzO&AZ??YVu8Fy|C8r
z7&iSA<@2>Hxw%2gXFkN97N$vi$zAC;w;sF>6Y4&W=(6qiKl>S*L5sapo!`uYlTZ`>
zVr!;~&A95r2qRkz5?}y{Qo(MkVYkg+^|Xp5D)XGLPi&LG+F4&`$X4CJy9n&uki_*J
zp+8>g<V~l1oK3$F-t|ivw~}2N>$UfVeg9eHS{N6c=?@%pS*+`QyUy5NaK62(|Fzh5
zr`LylxAE23lgA3(Z@V=67R^z<X*#yUN#q1vM5l0z?5dN$ks3Fdd;%WvBVCM06?IHA
z>53%Nf2L^vx%aBPcr?5Sa*cQG<DCcDVWpTkCZ<1h5u%#CJ4V*;?sJGdplS(HwA((t
z3t*WR1c|GD&B9*l!}PfZMGrKb$w3D}%%m({5hPuMiO;ym3LU#@B1jTk@_?dMP>smo
z&Ip5Xy_O7G{OJ7ZCB<H8YN;ky9*GJR7A_Cd1bYT$1T9=2m(qyxdcXr=4v}!GR%#NN
zz9WVqNkhJBGEoAV5yTV$6*!qJK=3ta-@mAgLL$br5!Z~tFWWvOGs2G4CXNAOp;244
z1t_je5O|0-Euzc^Z^B6@)jLAQ%n&y*V8>Q!>j5bl8KEo#NZg1qD+H3n5(jwT03(5n
zX9F0*Q3-o^8}kTKXanG2r{V3!xXYx6Bsw2bhN`a>gkpyngl1L}TQv{bG4hZ|40ncm
zF-I1l5BQz75@|pbHiHv8F!K}PJ1{%L#d%=1BMuHu^gZpK0o~O3<KCX@7>#r5ZEKFZ
zW2P<3;@-o=gxfm!>wOwyj?=d`MS3^tt-fQqLLEbvvbm@ZUBr*k2&ewh5bJ_}oJK?H
zsbQaMhGrdo6+lCSeL-fl(}QovON(X@p`Vh<{%+y<4ZIeb4NT@_pACzu8h>TnZDD-b
zofVI90|LVi#ru;R!`~YV6w3s+a|YsmoIr0}E{9iFZJZofh-EhmHqnq-P9I^O&Z~5K
z;GFoPu>Q|I^YL>@+|<${c6)|Ft^Zb*<K4|ue%yF<a63J<aF|CmZhM%j4FRWtRmD^`
zXK=E#)#$dj-%0!_z&h|+w<9M_Y*<#`E--Y?t+*R?CBBw#Gpb@Y)Fdug-XDfb)G+Yx
zkc`*NJMw++;hSb>a?pz3$FH0mYYEF!0zs@5GmE)(iTDamYPLZY_xi=X-hwH?l~L)6
z;9b_dgxsCRb#;2qQGOEZ)CjN8a>1nT>~2%BgT@efc%Iz*VRlzv0VJ;PNaDslMOvjM
ztKypK=>t?x*LJB1Vj<l0$$c602s!3H-O=IW^xN--Q^;$gq%krRnR?H~VYa17kywuH
zQ%_${UcRj^2?P{%lD|rVXRtUn38Ifa_(GKeKj++;0qoJ~w56ZEY>{jd-a5=A_a30u
zCXgog&rci-2P-uG3!r64wLJDI(QKsuV~l5m^qBj*3%@AZI;c~a-5`vjFtAi96)=!Q
zgVZts7*Y^0J{Vbs{OFs;&ZZ6}HL=c%>?W>d<i*;!Ydq87F9C&JCj3t{FE$Q*e*X60
zyq3@^-Qr#>_0-nnrU_mF{IMc-QYI|f_jYrD{kTOEJ9vW>tSWuqd~CVIkOi#3X07Ui
zP_dxVz7DB%6Hf4{^zpJ|XH%Nz+^mMf<jlaT6>{{F758&(w-p!~Fq0hKu;~LdfWDe(
zq4c~x+!=0|iH7A0D^sN(vB<=}IDZ*j1~)NM;2;UiSHC*L35N^`2tC@Uz>NVIt+7ZX
zfb2xutnQ|PG%z5e2aphoto)~gnacd=v?N>$LiK&E#AN`KF*Y914x!;?|22<Lb{|fc
z{*PSKGr{lQIb3Ug<2`z<K~*O_<<6l!vVU#t8aEFcvJkGC)N$DjpLSG$s%YE&^Hrv*
z{({Ml!wTbmQzMNV*9>kITp7k|Ofn3oRqy2nybNkhVyBuUR3cGonY14iaR>RymzV7J
zw>i~QX)KNfbrn;Xm9yqB8_Pe*d&E0(mdL#z|FTMtMw{l1GiCWR0ox|B4gAnAkmprY
zoios4paAq$zuyQP$w<rU^FCV9bb)co(iH*i^5TiVIjh%U#a_EtJVxYx-!gvR@V15T
z9S|z%(JUP1R*ieHPAkxt0c9BqIul-bizW6Ko?jJzb9r1hiA!t5AYU%{*0paMvy(A+
z5TCOYYJX3|O!C%7iNkD8jMbrPIL!wu^oZm}{@8jWTM@b_JPMj+m91qNPjC$nQfS}S
zd!KB?1t0qe!!@mU`%kEhOSDWD%dbP?_NL@+dZStvk{Ub~<W=X>y%V5+@`mZllN}SQ
zQ@)GQkcyoG7EUzc1+x;${AeC`;h%zc3YPot?9SQ9S{_486fCh+Mpey(5U*L0U$2cF
z1p-=;axYNVm0%J$0`sA)rXA{ar!@LNczwAKq?|C$+yO~B(u7Qa6gs{u_fXM;p_&tg
zeZ~u2rV>bMZ8+H355PcD(T4diG<2g)xO{j&!+W6k)W$=pH?{Q%?}CXqyQm3gDZ$Qo
zYac}mdBC8CLOMY;0Hb(>{0|kFhX9co&LrJFUCl<lAcRJ^stGSD!A5-kpL`8d{@4>7
zfkE)Nj|`QULxc?VxoquNfppO0j2Bh}I^8}>xE#t8+~4x|dc&h6aD8sB)z1m{HG$}X
zU4u~hIZ=S8xZ%%oWE}KJGMT=8W0IS6Bs_wY2wsSyZtc-_?gO8iTqUTveiuIM!dvCV
ztQ;h?f3tA&huGeIQ?P>`_tuU;3(fPMYV@>Y{Dy57o|TGa(L$bmih8_TF1M8gTh*;L
zdSiw}6>p-<YiF|NHkfd!{Ho3{v`&Ixga9-OT{sQyBP$8`yBrx&&}0Aw@-v0pqbbci
z1O?)MUg*5oKTsfZHTn7+8PQZNT6kMo`8+0%X*!x9i4}PZmxvUbz)+mBlD3{lPAgce
zxVMENpur}byfsc6dU<L;8Eqfk;g6Ish;BQEZOW6Iqwt0+>>qi$N7E+c(%K}t<VzJx
zw`frkui&Y=NQqDHr%_ltD_#bL6L!4gVa=wF?yWJ=$+C;L_T(iSBl(A1Bnf);5#+n}
zt<{Qi`_y1K;{}Qs|CMvP^yi%Pa6E+}D36>QVZKl$M??${_9)mURp;$61&aD5+l}*`
zkXs6S>+I8BudtIdJu!ElLra@}z3+YOvJ0Maal~<th9%DO{XykW@%yZ|yTGYBr`FtQ
z5hEw?d|t}BHiv)74bLQ?^#Gbcr-R)lqAxh`t}BE@DdFR6`V(#XPcv?xU_88IJvg)f
zOl0R((Wd9PljqAh_oaud@q){%E%fDY?C&l2nffwuoknu%@z9J8jPO_VDs>3q{{e9s
B*)jkC

literal 0
HcmV?d00001

diff --git a/frontend/public/brand/shortcuts/digital-cards.png b/frontend/public/brand/shortcuts/digital-cards.png
new file mode 100644
index 0000000000000000000000000000000000000000..166f3c15c133280676b755ea84dfc37c8279a597
GIT binary patch
literal 2508
zcmc(h`#V%?8^@nDGgxFa;}8wI#vr6@C1ps)F>+{_lp@DOP6;(mX&e$Eswpbf<W!Q0
ziXprtqU~6_85JrDy<3ih2-$1R`$xP#tb5(pdY<q7-0Qy9_5G|gy5nBF6iEsIfVZ`=
zbVlxt=mm=-(YZfZ0szSLgoOqDgs(3EO4rV2H`rlLDZMi7b-C_}r|ytf(QpuRvSTEq
zI1(4s-W3a%oj7L(ewyEGzgH5FY8@n*|KXL&FKi-5RVu%X&q=wG{#fP+y?Z7;D$3(i
zjs$zO&WSKUlD}A`AhTE*MJcKApijT;Ci^~D?HIPvlOoSv(F@k;UR(dUpe=e=Jy-E>
z<Hx<Fuf>X<8#`SRGd-xg;5iX#t<<RaMc=+%+zR{3u1Y&va*8w-Lt-21`L)Q|(&r2B
z22H1ZJCOdThTEGkz$S5qjSTrO&M#Nh>1Z_kJa(}H?vco#z;aEidy9EDBne*P$2=Qi
z2_I@c2(J4RWA3PohRC{K=rIh>>t?i`$V>PISC-BHJ}x#g#@X<!{@phB@t18DeL@$n
z2hx0H25+{w2y^rU{=wasG)&6L7xnY_uS1>{9~sIi$V4T>Yz{{Nfc=hMP-U!h5CE{g
zt)<z4sJ!vp?I&Ga<S#5r2yiJ2xjKijxrEJf1!i$N7sWGg!diQL!f3dm#(-=a_#&$-
z`vOrc(Hdutv%sIt6_*N$e&_r#Jn+{OURjaDWXR;s(M{^PdWIJ~-2FeVlpX723Vz2o
zoSq;1v_9sDiY<Oe52>Sk1F*%*LjbZSM*?yq%-&B%VzL1sc;Wt{D8YIdZ$%i1e#-Jl
z98>{F941SnxjMQ!ycvh=Y&wdn*zI9777^x|B>*)#*8+>wtdjtk3|ce+i&ILNqM)*2
zTXj@$%L@@i$*;xf&XT4|3F~ul&ICXp<BG6oD{&YIvgSO3SU`=i?gdg*tCohA?&F~O
zC_r-wZ#36LSK&jd$WHnMsv^6mV38wh@KVT;VSkX&BTdk^X-ZN;dsIYa@O}!~<0l+8
z!5O=u1)G37ij7yGV6W1oFaVRx5se~QGzzw86iuR0_=!g0EgHqJXcU9wAIIT!g3n_D
z9yc<!mRbFE<wF0B!6Us?!3Z~#ch&Eq*{G{q3HQ|5uSSo9jt*{k(9jyYE#|E3^6#RY
zqbohyhqTtIOt0>}=c>g&H`n4fvIVEX>b<$HCPM98V_Zu9slu-MnBU$JJ2!g(<-XqP
zk|Fk7oE$IJr{epW$PhjMLW-E)<Kx$tiYAxb__y0!RVMmIM+6-^{EPE(Q;bQTK)A0k
z)xxB<^G1mh6#U->J%{nMjAsAwjk!<1)`ROi4^DSZp0Ho1IdJ8vuyg&)5nxawClK1$
ztHp2J9om)6!??a#ZjKDxe@y-QF4N;(S8_0hf^&MOD})TWiJ5?_rJc9c+uf7e3ml4m
z6=$lQUFtkM;|Qj!M!$cvk(v^Qx{bDmnhgXCD-MP0KDaer#f*1;$b74$E$w&4ZO2oL
zD}ToRq1vL$*6y2G)WW!>ric<Qr|!)%doj0OwsE9%Oiq#M|EwjhPIZJkQI<9uz*ssW
zoQ~084Geg0(w)dpS?Xw2_R$T^y&84Nr@}R>R|irVH_d)fp0o%FD^l_-78~k4VE==F
zpVTU=u#+^Yw=t+~eI`@==KZKWWvwx#mH_$i?&_NZW^s8Wh^<zD-Ycww-oGq^0pyCk
zK9{k8%g4G}q=Ii%L5&ncEMYN^_y<eI3$KbH7_kiCd&ey$IHC>e{W96@Ypb(9e$vPc
zM6xj1U~SNp^<ZQ(4g*sk5@|+Ia|6}(faANhx3{l8nh(VHY@5G7mq+x=Kw7ymvk$Du
znG8QN^;SXdBlgi6tWRkTk47`Je4B+QI@yOX)!{47)Uo|at=GnKI?(;g6n8%>hlyk=
z!$Xo4!TRfBV3iq>*5;H6CNjWK3x7@K8ruTW?56%lG{Ce0%bSzO?*}%A(EAJkh6YG8
z6eWlZtiXIC-au_n!gnAbP(aN%X-bj}rN(uo%FrarQwR|JM<XejuAh(XfgY(^0&|IS
zan*Mj-$5h@f{85Tp&4wTW(1I3<~YPbf(YiF|6i%i@M#wEA<C^7hU%Jn?Ga>0RO{si
z+_^Nn;<e}CV_bP@Y^fb7U3nxoYgcnz;o$G)h-do0`s3<6B)x?ExwP~phuQOsQ5GF0
z1AVgHZ;IzDN50PO11GC?->$Ac@AIOb|D-vtLv`3#@ecE9%WFjaWYJc*Emnh7W1v4^
zdVcT#W#Qo%<B$t8XYsubwe+8fGoH+lEqvn>(u(0li_bRH9>Syw16HA&oimK+UZamc
z0wXkEZ|~)tenwSTIP3}hJwW@djr)%VQ(~uM{w^5V60OZL+&>y$dB@a;beZ3<cg`Bv
zDVI8LtxEmTeC*WQtyJUBd8&`avd`GD+Z=;~J$<_ztzdH3#@L^(-I|vvGV?#Sqi%rO
zgmFLb&rTJB^>oB%=8b{**@Ix$_RvyBi}sf;FZpyUUO`Y2RZU?l%g~d$njNH4^7PKh
zp<+XQ_c0HnpB$>P8T`eX`=9C#{&0M4*~|4lzlgmi+|^h`&mI1%Hc)@u?uPl9a2_wV
z)>v?^{G0V{-;jxqQO1XhNs*T-ul+;n-Nh9?7bp}xck4F6w9$yR(^cXMZy=jM4vbRe
z9_suYk@J&9&QBLPKP+;7Es^uXBInmaoS*ZKb=8ZU%?WCBNtL$8Xd@K}iEl-`*pq;=
zKp<j7I!YO~2u{f%bTp3uNK8)BLvy48l9v)tjxbRbLH8xfoqlmKgdo*2c!VG`8_?bc
z&7@HtrlYcC&C96ZWMTrX1j-sppe1sl2C2&lwq!8`qvmuY5o|OGsDOluy@}FDp(kr_
zNGum&DO?7ia3Y8!F<cg14O76NpwdNEO@4-GcmI3i-g_cYiKw_c6+&T3L}knO#aA(m
Xy1>Eo{wGezKLxP0a<t@{dnNu0uV4%A

literal 0
HcmV?d00001

diff --git a/frontend/scripts/generate-shortcut-icons.mjs b/frontend/scripts/generate-shortcut-icons.mjs
index 8b5f0902..3f2e6ce4 100644
--- a/frontend/scripts/generate-shortcut-icons.mjs
+++ b/frontend/scripts/generate-shortcut-icons.mjs
@@ -8,7 +8,7 @@ import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { createElement } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
-import { Eye, ListChecks, ScanBarcode } from "lucide-react";
+import { CreditCard, Eye, ListChecks, ScanBarcode } from "lucide-react";
 import { GREEN } from "./lib/brand.mjs";
 import { ROOT } from "./lib/cart-source.mjs";
 import { SRGB } from "./lib/srgb.mjs";
@@ -28,6 +28,7 @@ const RADIUS = Math.round(SIZE * (96 / 512));
 // Keyed by navigation item id, since manifest.ts derives each src from it.
 const SHORTCUTS = {
   scan: ScanBarcode,
+  "digital-cards": CreditCard,
   "shopping-lists": ListChecks,
   watchlist: Eye,
 };
diff --git a/frontend/src/app/(root)/data/features.ts b/frontend/src/app/(root)/data/features.ts
index 9c926575..42276aa1 100644
--- a/frontend/src/app/(root)/data/features.ts
+++ b/frontend/src/app/(root)/data/features.ts
@@ -84,8 +84,7 @@ export const featureItems: IFeatureItem[] = [
     description:
       "Sve kartice trgovina u mobitelu - novčanik konačno na dijeti.",
     icon: CreditCard,
-    comingSoon: true,
-    // href: "/digital-cards",
+    href: "/digital-cards",
   },
   {
     title: "Bez interneta",
diff --git a/frontend/src/components/custom/bottom-nav/bottom-nav-items.ts b/frontend/src/components/custom/bottom-nav/bottom-nav-items.ts
index 51d151b5..09e44914 100644
--- a/frontend/src/components/custom/bottom-nav/bottom-nav-items.ts
+++ b/frontend/src/components/custom/bottom-nav/bottom-nav-items.ts
@@ -48,9 +48,7 @@ export const bottomNavItems: IBottomNavItem[] = [
   {
     item: findNavItem("digital-cards"),
     longPressTarget: { name: "digital-card", action: "new" },
-    // TODO: flip to true when digital cards ship. Wired now so the gesture
-    // plumbing never has to be revisited, but inert while the tab is a teaser.
-    longPressEnabled: false,
+    longPressEnabled: true,
   },
 ];
 
diff --git a/frontend/src/components/custom/settings/onboarding/onboarding-steps.ts b/frontend/src/components/custom/settings/onboarding/onboarding-steps.ts
index 38128bf7..4b460c7a 100644
--- a/frontend/src/components/custom/settings/onboarding/onboarding-steps.ts
+++ b/frontend/src/components/custom/settings/onboarding/onboarding-steps.ts
@@ -16,6 +16,8 @@ export interface IOnboardingStep {
 }
 
 // The middle steps ARE the settings tabs - same components, same form context.
+// TODO(onboarding-v2): add a step that nudges the user to save the loyalty cards they
+// already carry, seeded from the chains they pick in preferences. Suggest, never require.
 export const ONBOARDING_STEPS: IOnboardingStep[] = [
   {
     id: "welcome",
diff --git a/frontend/src/constants/navigation.ts b/frontend/src/constants/navigation.ts
index e73ce914..db7909f6 100644
--- a/frontend/src/constants/navigation.ts
+++ b/frontend/src/constants/navigation.ts
@@ -85,8 +85,6 @@ export const userNavItems: INavigationItem[] = [
     shortLabel: "Kartice",
     icon: CreditCard,
     shortcutDescription: "Otvori svoje digitalne kartice",
-    // TODO(#127): generate its PWA shortcut icon before dropping this flag.
-    comingSoon: true,
 
     showInHeader: true,
   },
diff --git a/frontend/src/constants/pwa-shortcuts.ts b/frontend/src/constants/pwa-shortcuts.ts
index 7ceb2fc5..9d2152e4 100644
--- a/frontend/src/constants/pwa-shortcuts.ts
+++ b/frontend/src/constants/pwa-shortcuts.ts
@@ -32,8 +32,24 @@ const scanShortcut: Shortcut = {
 };
 
 // Android shows 3 of these (Chrome keeps a fourth slot for its own "Site
-// settings"), so order is what decides what a phone actually surfaces.
-// Scanning leads: it is the fastest path from launcher to a price.
+// settings"), so order is what decides what a phone actually surfaces. Stated
+// explicitly rather than inherited from navigation.ts, where the ordering is about
+// the sidebar and a reshuffle there would silently drop a shortcut from phones.
+// Scanning leads (fastest path from launcher to a price), then the two the till
+// needs. Praćenje is fourth: it is a browsing destination, not a two-tap errand.
+const PWA_SHORTCUT_ORDER = [
+  "scan",
+  "digital-cards",
+  "shopping-lists",
+  "watchlist",
+];
+
+function shortcutRank(id: string): number {
+  const index = PWA_SHORTCUT_ORDER.indexOf(id);
+
+  return index === -1 ? PWA_SHORTCUT_ORDER.length : index;
+}
+
 export const pwaShortcuts: Shortcut[] = [
   scanShortcut,
   ...userNavItems
@@ -44,5 +60,8 @@ export const pwaShortcuts: Shortcut[] = [
       description: item.shortcutDescription,
       url: item.href,
       icons: shortcutIcons(item.id),
-    })),
+      id: item.id,
+    }))
+    .sort((a, b) => shortcutRank(a.id) - shortcutRank(b.id))
+    .map(({ id: _id, ...shortcut }) => shortcut),
 ];

From 511b8a709503ae3c03f3d6f4f4fb5b6f3b6eba5f Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Fri, 31 Jul 2026 01:56:53 +0200
Subject: [PATCH 09/14] fix(digital-cards): Keep the card code out of storage
 but alive across a retry

Changes:
- Add modal-retry-bus, an in-memory sibling of modal-error-bus with the same TTL
- Stash the submitted code when an optimistic save fails, and restore it on reopen
- Drop any draft still holding a card code under the old or current field name

Two halves of one rule: never on disk, fine in memory until the submit settles.

A failed save reopened the modal with the code field empty, because the draft
deliberately excludes it, and the edit path then re-seeded the code from the server
record, so a resubmit could silently write the old number back. Separately, drafts
written by earlier builds still hold a card number under the old "value" key, and
the manual draft merge reads localStorage directly, bypassing the exclusion.

Closes #54.

Notes:
- The whole draft key is deleted rather than sanitised field by field, since its shape
  comes from a build we no longer have.
- The stash is memory only, so it dies with the tab and is dropped the moment the
  retry reads it, which keeps the code off disk in every path.
---
 .../components/forms/digital-card-modal.tsx   | 29 +++++++++++++++--
 .../hooks/use-digital-card-modal.ts           |  4 +++
 frontend/src/lib/modal/modal-retry-bus.ts     | 32 +++++++++++++++++++
 3 files changed, 63 insertions(+), 2 deletions(-)
 create mode 100644 frontend/src/lib/modal/modal-retry-bus.ts

diff --git a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
index 2cacd148..23c74fe0 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
@@ -14,9 +14,10 @@ import {
   type DigitalCardFormData,
 } from "@/lib/api/schemas/digital-card";
 import { takeModalError } from "@/lib/modal/modal-error-bus";
+import { takeModalValues } from "@/lib/modal/modal-retry-bus";
 import { closeModalUrl } from "@/lib/modal/modal-navigation";
 import { useFormDraft } from "@/hooks/use-form-draft";
-import { getFormDraft } from "@/utils/browser/local-storage";
+import { getFormDraft, removeFormDraft } from "@/utils/browser/local-storage";
 import extractDominantColor from "@/utils/browser/extract-dominant-color";
 import CardNameField from "@/app/(user)/digital-cards/components/forms/card-name-field";
 import CardTypeField from "@/app/(user)/digital-cards/components/forms/card-type-field";
@@ -41,6 +42,16 @@ interface IDigitalCardModalProps {
   id?: string;
 }
 
+// Drafts written before the code was excluded still hold a card number under the old
+// "value" field. Deleting the whole key is safer than trusting the shape of a draft
+// written by a build we no longer have.
+function dropLegacyDraft(draftKey: string): void {
+  const draft = getFormDraft(draftKey)?.values;
+  if (draft && ("value" in draft || "codeValue" in draft)) {
+    removeFormDraft(draftKey);
+  }
+}
+
 const EMPTY_VALUES: DigitalCardFormData = {
   cardName: "",
   cardType: "loyalty",
@@ -85,6 +96,10 @@ export default function DigitalCardModal({
 
   // Draft precedence controls restore order; the isDirty guard is what stops a
   // reload from clobbering an in-progress edit.
+  useEffect(() => {
+    dropLegacyDraft(draftKey);
+  }, [draftKey]);
+
   useEffect(() => {
     if (!digitalCard || form.formState.isDirty) return;
 
@@ -117,11 +132,21 @@ export default function DigitalCardModal({
     exclude: ["codeValue"],
   });
 
-  // A failed optimistic save reopened this modal: surface the server error.
+  // A failed optimistic save reopened this modal: surface the server error and give back
+  // the code the user typed, which the draft deliberately never kept.
   useEffect(() => {
     if (!open) return;
+
     const error = takeModalError(draftKey);
     if (error) applyProblemToForm(error, form);
+
+    const retry = takeModalValues(draftKey);
+    if (typeof retry?.codeValue === "string") {
+      form.setValue("codeValue", retry.codeValue, {
+        shouldDirty: true,
+        shouldValidate: true,
+      });
+    }
   }, [open, draftKey, form]);
 
   const { onSubmit, isLoading: isSaving } = useDigitalCardModal({
diff --git a/frontend/src/app/(user)/digital-cards/hooks/use-digital-card-modal.ts b/frontend/src/app/(user)/digital-cards/hooks/use-digital-card-modal.ts
index e8b0b218..a4abc06f 100644
--- a/frontend/src/app/(user)/digital-cards/hooks/use-digital-card-modal.ts
+++ b/frontend/src/app/(user)/digital-cards/hooks/use-digital-card-modal.ts
@@ -4,6 +4,7 @@ import { toast } from "sonner";
 import { digitalCardService } from "@/lib/api";
 import type { DigitalCardDto, DigitalCardRequest } from "@/lib/api/types";
 import { stashModalError } from "@/lib/modal/modal-error-bus";
+import { stashModalValues } from "@/lib/modal/modal-retry-bus";
 import { closeModalUrl, openModalUrl } from "@/lib/modal/modal-navigation";
 import { removeFormDraft } from "@/utils/browser/local-storage";
 
@@ -45,6 +46,9 @@ export function useDigitalCardModal({
       await queryClient.invalidateQueries({ queryKey: ["digitalCards"] });
     } catch (error) {
       stashModalError(draftKey, error);
+      // The code is excluded from the draft, so without this the retry would come back
+      // empty and silently resubmit the old server value. Memory only, never disk.
+      stashModalValues(draftKey, { codeValue: data.codeValue });
       openModalUrl(
         digitalCard
           ? { name: "digital-card", action: "edit", id: digitalCard.id }
diff --git a/frontend/src/lib/modal/modal-retry-bus.ts b/frontend/src/lib/modal/modal-retry-bus.ts
new file mode 100644
index 00000000..e0cbc77c
--- /dev/null
+++ b/frontend/src/lib/modal/modal-retry-bus.ts
@@ -0,0 +1,32 @@
+// Sibling of modal-error-bus: a failed save parks the field values that must survive the
+// remount but must never reach localStorage, such as a loyalty card number. In memory only,
+// so it dies with the tab, and it is dropped the moment the retry reads it.
+const STASH_TTL_MS = 60_000;
+
+interface IStashedValues {
+  values: Record<string, unknown>;
+  expiresAt: number;
+}
+
+const stash = new Map<string, IStashedValues>();
+
+export function stashModalValues(
+  key: string,
+  values: Record<string, unknown>,
+): void {
+  // Abandoned flows never call takeModalValues; evict expired entries so the map stays bounded.
+  const now = Date.now();
+  for (const [existingKey, entry] of stash) {
+    if (entry.expiresAt <= now) stash.delete(existingKey);
+  }
+  stash.set(key, { values, expiresAt: now + STASH_TTL_MS });
+}
+
+export function takeModalValues(
+  key: string,
+): Record<string, unknown> | undefined {
+  const entry = stash.get(key);
+  stash.delete(key);
+  if (!entry || entry.expiresAt <= Date.now()) return undefined;
+  return entry.values;
+}

From 1b24bb84825d701ff9630c99870d7d48b7ea39b2 Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Wed, 5 Aug 2026 20:14:50 +0200
Subject: [PATCH 10/14] fix(digital-cards): Adopt the UTC clock and key the
 card modals per card

Changes:
- Stamp every digital card and store name suggestion timestamp through Timestamps.nowUtc()
- Key the card form and view modals by card id in the entity outlet

Both follow conventions that landed on dev while this branch was open.

The UTC rule is the one AGENTS.md now states: the columns carry no offset, so a
bare LocalDateTime.now() lets the container's zone leak into the wire format, and
the frontend reads these back as UTC. The merge applied it to deleteCard but left
setPinned and the whole storeName package behind.

The keying is the same fix add-to-list carries. The outlet stays mounted between
openings, and this form's draft merge bails out while the form is dirty, so
editing one card, closing, then opening another would have shown the first card's
edits under the second card's title.
---
 .../disscount/digitalCard/service/DigitalCardService.java  | 2 +-
 .../disscount/storeName/domain/StoreNameSuggestion.java    | 6 ++++--
 .../components/custom/modal-router/entity-modal-outlet.tsx | 7 ++++++-
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java b/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
index 77e71069..1e49d769 100644
--- a/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
+++ b/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
@@ -106,7 +106,7 @@ public DigitalCardDto setPinned(UUID cardId, UUID userId, boolean pinned) {
         User user = requireUser(userId);
         DigitalCard card = requireCard(cardId, user);
 
-        card.setPinnedAt(pinned ? LocalDateTime.now() : null);
+        card.setPinnedAt(pinned ? Timestamps.nowUtc() : null);
         card = digitalCardRepository.save(card);
 
         return convertToDto(card);
diff --git a/backend/src/main/java/disscount/storeName/domain/StoreNameSuggestion.java b/backend/src/main/java/disscount/storeName/domain/StoreNameSuggestion.java
index 2ece6347..5b654709 100644
--- a/backend/src/main/java/disscount/storeName/domain/StoreNameSuggestion.java
+++ b/backend/src/main/java/disscount/storeName/domain/StoreNameSuggestion.java
@@ -6,6 +6,8 @@
 import java.time.LocalDateTime;
 import java.util.UUID;
 
+import disscount.util.Timestamps;
+
 /**
  * Community store-name vocabulary, offered to everyone in the card form's autocomplete.
  * Deliberately carries no user reference of any kind: suggestions are public, so
@@ -53,13 +55,13 @@ public class StoreNameSuggestion {
 
     @PrePersist
     protected void onCreate() {
-        LocalDateTime now = LocalDateTime.now();
+        LocalDateTime now = Timestamps.nowUtc();
         createdAt = now;
         updatedAt = now;
     }
 
     @PreUpdate
     protected void onUpdate() {
-        updatedAt = LocalDateTime.now();
+        updatedAt = Timestamps.nowUtc();
     }
 }
diff --git a/frontend/src/components/custom/modal-router/entity-modal-outlet.tsx b/frontend/src/components/custom/modal-router/entity-modal-outlet.tsx
index 29a69ef7..e814e012 100644
--- a/frontend/src/components/custom/modal-router/entity-modal-outlet.tsx
+++ b/frontend/src/components/custom/modal-router/entity-modal-outlet.tsx
@@ -69,10 +69,15 @@ export default function EntityModalOutlet({ target }: IEntityModalOutletProps) {
     case "digital-card":
       // View is a separate modal rather than a mode of the form: it is a different job,
       // reached by a different action, and shares only the card it reads.
+      //
+      // Keyed per card for the same reason add-to-list is: the outlet stays mounted
+      // between openings, and the form's draft merge bails out while it is dirty, so a
+      // reused instance would show card A's edits under card B's title.
       return rendered.action === "view" ? (
-        <DigitalCardViewModal open={open} id={rendered.id} />
+        <DigitalCardViewModal key={rendered.id} open={open} id={rendered.id} />
       ) : (
         <DigitalCardModal
+          key={rendered.action === "edit" ? rendered.id : "new"}
           open={open}
           action={rendered.action}
           id={rendered.action === "edit" ? rendered.id : undefined}

From 753714a8aff1decea846af30c10e60ccfd39869d Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Wed, 5 Aug 2026 20:17:54 +0200
Subject: [PATCH 11/14] fix(digital-cards): Apply the review findings on the
 card surfaces

Changes:
- Clear the file input after reading it, so the same file can be picked again
- Restore the colour suggestion rule when the form is reset
- Name the failing action correctly when unpinning
- Take the card type as the wire's plain string, falling back instead of rendering undefined
- Encode the checkout code once per render, and use Stream.toList on the backend

Picking a photo, removing it, then picking the same file again did nothing,
because the input still held the old value and fired no change event. Resetting a
new card left colourCustomized true, so chain and image suggestions stayed off for
the rest of the session.
---
 .../digitalCard/service/DigitalCardService.java          | 3 +--
 .../storeName/service/StoreNameSuggestionService.java    | 3 +--
 .../digital-cards/components/forms/card-image-slot.tsx   | 3 +++
 .../components/forms/digital-card-modal.tsx              | 2 ++
 .../digital-cards/components/pin-toggle-button.tsx       | 9 ++++++++-
 .../digital-cards/components/view/card-code-panel.tsx    | 9 +++++++--
 .../digital-cards/components/view/card-detail-rows.tsx   | 5 +----
 .../src/app/(user)/digital-cards/utils/card-labels.ts    | 8 ++++++--
 .../src/app/(user)/digital-cards/utils/card-sorting.ts   | 5 ++---
 9 files changed, 31 insertions(+), 16 deletions(-)

diff --git a/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java b/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
index 1e49d769..d255fdd2 100644
--- a/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
+++ b/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
@@ -18,7 +18,6 @@
 
 import java.util.List;
 import java.util.UUID;
-import java.util.stream.Collectors;
 
 @Service
 @RequiredArgsConstructor
@@ -60,7 +59,7 @@ public List<DigitalCardDto> getUserCards(UUID userId) {
         return digitalCardRepository.findActiveByUser(user)
                 .stream()
                 .map(this::convertToDto)
-                .collect(Collectors.toList());
+                .toList();
     }
 
     public DigitalCardDto updateCard(UUID cardId, UUID userId, DigitalCardRequest request) {
diff --git a/backend/src/main/java/disscount/storeName/service/StoreNameSuggestionService.java b/backend/src/main/java/disscount/storeName/service/StoreNameSuggestionService.java
index d723d07e..ebff9ba5 100644
--- a/backend/src/main/java/disscount/storeName/service/StoreNameSuggestionService.java
+++ b/backend/src/main/java/disscount/storeName/service/StoreNameSuggestionService.java
@@ -12,7 +12,6 @@
 import disscount.storeName.dto.StoreNameSuggestionDto;
 
 import java.util.List;
-import java.util.stream.Collectors;
 
 @Slf4j
 @Service
@@ -72,6 +71,6 @@ public List<StoreNameSuggestionDto> listVisible() {
                         .name(suggestion.getName())
                         .usageCount(suggestion.getUsageCount())
                         .build())
-                .collect(Collectors.toList());
+                .toList();
     }
 }
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx b/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx
index ef446ccd..4dcddc6e 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx
@@ -35,6 +35,9 @@ export default function CardImageSlot({
 
   async function handleChange(event: ChangeEvent<HTMLInputElement>) {
     const file = event.target.files?.[0];
+    // Clearing it now means picking the same file again still fires onChange, which it
+    // would not after a remove or a rejected upload.
+    event.currentTarget.value = "";
     if (!file) return;
 
     if (file.size > MAX_SOURCE_BYTES) {
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
index 23c74fe0..c87a03d7 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
@@ -198,6 +198,8 @@ export default function DigitalCardModal({
         clearDraft();
         resetImages();
         form.reset();
+        // Back to a blank card, so the chain and image suggestions become welcome again.
+        setColorCustomized(isEdit);
       }}
     >
       {loading ? (
diff --git a/frontend/src/app/(user)/digital-cards/components/pin-toggle-button.tsx b/frontend/src/app/(user)/digital-cards/components/pin-toggle-button.tsx
index 820a971d..f13fcd6d 100644
--- a/frontend/src/app/(user)/digital-cards/components/pin-toggle-button.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/pin-toggle-button.tsx
@@ -27,7 +27,14 @@ export default function PinToggleButton({
     try {
       await setPinned.mutateAsync({ id: card.id, pinned: !isPinned });
     } catch (error) {
-      toast.error(problemMessage(error, "Greška pri prikvačivanju kartice."));
+      toast.error(
+        problemMessage(
+          error,
+          isPinned
+            ? "Greška pri otkvačivanju kartice."
+            : "Greška pri prikvačivanju kartice.",
+        ),
+      );
     }
   }
 
diff --git a/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx b/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx
index 1a4a6ed4..f97b9210 100644
--- a/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx
@@ -1,5 +1,6 @@
 "use client";
 
+import { useMemo } from "react";
 import { TriangleAlert } from "lucide-react";
 
 import type { CodeType } from "@/constants/card-codes";
@@ -22,7 +23,11 @@ export default function CardCodePanel({
   codeValue,
   codeType,
 }: ICardCodePanelProps) {
-  const result = generateCodeSvg(codeValue, codeType);
+  // Only to decide whether the warning shows; CardCode memoizes its own encode.
+  const isRenderable = useMemo(
+    () => generateCodeSvg(codeValue, codeType).ok,
+    [codeValue, codeType],
+  );
   const twoDimensional = isTwoDimensional(codeType);
 
   return (
@@ -33,7 +38,7 @@ export default function CardCodePanel({
         </div>
       </div>
 
-      {!result.ok && (
+      {!isRenderable && (
         <p className="flex items-start gap-1.5 text-xs text-amber-700">
           <TriangleAlert
             aria-hidden="true"
diff --git a/frontend/src/app/(user)/digital-cards/components/view/card-detail-rows.tsx b/frontend/src/app/(user)/digital-cards/components/view/card-detail-rows.tsx
index 256a3ca6..f9da9dbf 100644
--- a/frontend/src/app/(user)/digital-cards/components/view/card-detail-rows.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/view/card-detail-rows.tsx
@@ -2,7 +2,6 @@
 
 import { Badge } from "@/components/ui/badge";
 import StoreChainLogo from "@/components/custom/store-chain/store-chain-logo";
-import type { CardType } from "@/constants/card-codes";
 import type { DigitalCardDto } from "@/lib/api/types";
 import { getCardTypeLabel } from "@/app/(user)/digital-cards/utils/card-labels";
 
@@ -20,9 +19,7 @@ export default function CardDetailRows({ card }: ICardDetailRowsProps) {
           </span>
         )}
         <p className="text-sm text-muted-foreground">{card.storeName}</p>
-        <Badge variant="outline">
-          {getCardTypeLabel(card.cardType as CardType)}
-        </Badge>
+        <Badge variant="outline">{getCardTypeLabel(card.cardType)}</Badge>
       </div>
 
       {card.note && (
diff --git a/frontend/src/app/(user)/digital-cards/utils/card-labels.ts b/frontend/src/app/(user)/digital-cards/utils/card-labels.ts
index a62e239a..894875d3 100644
--- a/frontend/src/app/(user)/digital-cards/utils/card-labels.ts
+++ b/frontend/src/app/(user)/digital-cards/utils/card-labels.ts
@@ -7,8 +7,12 @@ const CARD_TYPE_LABELS: Record<CardType, string> = {
   other: "Ostalo",
 };
 
-export function getCardTypeLabel(cardType: CardType): string {
-  return CARD_TYPE_LABELS[cardType];
+/**
+ * Takes the DTO's plain string rather than the union: the value comes off the wire, so a
+ * backend that gains a type before the frontend does would otherwise render "undefined".
+ */
+export function getCardTypeLabel(cardType: string): string {
+  return CARD_TYPE_LABELS[cardType as CardType] ?? CARD_TYPE_LABELS.other;
 }
 
 export function getCardTypeOptions(): { value: CardType; label: string }[] {
diff --git a/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts b/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts
index 47536f06..3ebef63d 100644
--- a/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts
+++ b/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts
@@ -1,6 +1,5 @@
 import type { DigitalCardDto } from "@/lib/api/types";
 import { compareHr } from "@/utils/strings";
-import type { CardType } from "@/constants/card-codes";
 import { hueFromHex } from "@/app/(user)/digital-cards/utils/card-colors";
 import { getCardTypeLabel } from "@/app/(user)/digital-cards/utils/card-labels";
 
@@ -59,8 +58,8 @@ function compareBy(mode: CardSortMode) {
         return compareHr(a.storeName, b.storeName);
       case "cardType":
         return compareHr(
-          getCardTypeLabel(a.cardType as CardType),
-          getCardTypeLabel(b.cardType as CardType),
+          getCardTypeLabel(a.cardType),
+          getCardTypeLabel(b.cardType),
         );
       case "updatedAt":
         return byNewestFirst(a.updatedAt, b.updatedAt);

From 6130c557dc1008392a82b6ca4282a6656cadde03 Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Fri, 7 Aug 2026 12:19:30 +0200
Subject: [PATCH 12/14] fix(digital-cards): Make card text legible and adopt
 the newer conventions

Changes:
- Choose card text colour per card by luminance, and darken the hues no ink could carry
- Route every card query key through a keys.ts registry, matching the other domains
- Report a replayed card write that fails, which previously reverted in silence
- Sample the compressed image for the colour suggestion instead of decoding the original again
- Move to useWatch, shared loading labels, a copy button for the card number and theme tokens
- Add the noindex header for /digital-cards

The contrast claim in card-colors.ts was simply wrong: locking saturation and
lightness does not make white text legible, because yellow and green are far
brighter than blue at the same lightness. Hue 55 sat near 2.7:1 against a 4.5:1
minimum, and several chain brand colours were no better. Ink is now chosen per
card, which covers the freeform slider and the brand map together, and a band
around cyan where neither ink reached 4.5 is darkened until one does. Worst case
across all 360 hues is now 4.52.

Notes:
- foregroundFor and the contrast helpers sit above hexForHue on purpose: CARD_SWATCHES
  calls it at module scope, so a const declared later would be read in its dead zone.
- The four literal bg-white surfaces now say why they are literal. A scanner reads
  contrast, so a dark-mode barcode panel would not scan.
- convertToDto stays private, with a note. The mapper split on shopping lists exists to
  stop an owner view and a shared view drifting, and a card has one viewer.
- mvn -B verify passes. It proves compilation and packaging only: there is still no
  backend test suite.
---
 .../service/DigitalCardService.java           |  3 +
 frontend/next.config.ts                       |  6 ++
 .../components/card-face-back.tsx             |  6 +-
 .../components/card-face-front.tsx            | 39 ++++++--
 .../components/digital-cards-client.tsx       | 13 ++-
 .../components/digital-cards-sort-select.tsx  |  3 +
 .../components/forms/card-image-slot.tsx      |  5 +-
 .../components/forms/card-images-field.tsx    |  2 +-
 .../components/forms/code-preview.tsx         |  7 +-
 .../forms/color-picker/card-color-field.tsx   |  4 +-
 .../components/forms/digital-card-modal.tsx   | 17 +++-
 .../components/forms/store-name-field.tsx     |  6 +-
 .../components/view/card-code-panel.tsx       | 12 +++
 .../components/view/card-view-actions.tsx     |  5 +-
 .../view/digital-card-view-modal.tsx          |  6 +-
 .../hooks/use-digital-cards-sort.ts           |  3 +
 .../hooks/use-store-name-options.ts           |  2 +-
 .../(user)/digital-cards/utils/card-colors.ts | 89 ++++++++++++++++---
 .../digital-cards/utils/card-sorting.ts       |  5 ++
 frontend/src/lib/api/digital-cards/hooks.ts   | 12 ++-
 .../utils/browser/extract-dominant-color.ts   | 16 +++-
 21 files changed, 209 insertions(+), 52 deletions(-)

diff --git a/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java b/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
index d255fdd2..f542f06d 100644
--- a/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
+++ b/backend/src/main/java/disscount/digitalCard/service/DigitalCardService.java
@@ -130,6 +130,9 @@ private void recordStoreNameIfCustom(String chainCode, String storeName) {
         }
     }
 
+    // Kept private rather than extracted into a @Component mapper the way shopping lists
+    // did: that split exists so an owner view and a shared view cannot drift on what they
+    // expose, and a card has exactly one viewer. Extract it the day cards gain a second.
     private DigitalCardDto convertToDto(DigitalCard card) {
         return DigitalCardDto.builder()
                 .id(card.getId())
diff --git a/frontend/next.config.ts b/frontend/next.config.ts
index d770eb32..6084289d 100644
--- a/frontend/next.config.ts
+++ b/frontend/next.config.ts
@@ -93,6 +93,12 @@ const nextConfig: NextConfig = {
         source: "/shopping-lists/:path*",
         headers: [{ key: "X-Robots-Tag", value: "noindex, nofollow" }],
       },
+      {
+        // Same belt and braces for the wallet, which holds loyalty card numbers and so
+        // has even less business in an index than a shopping list does.
+        source: "/digital-cards/:path*",
+        headers: [{ key: "X-Robots-Tag", value: "noindex, nofollow" }],
+      },
     ];
   },
 };
diff --git a/frontend/src/app/(user)/digital-cards/components/card-face-back.tsx b/frontend/src/app/(user)/digital-cards/components/card-face-back.tsx
index 2a9deced..25833e4e 100644
--- a/frontend/src/app/(user)/digital-cards/components/card-face-back.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/card-face-back.tsx
@@ -1,7 +1,6 @@
 "use client";
 
 import CardCode from "@/app/(user)/digital-cards/components/card-code";
-import type { CodeType } from "@/constants/card-codes";
 import type { DigitalCardDto } from "@/lib/api/types";
 
 interface ICardFaceBackProps {
@@ -11,6 +10,9 @@ interface ICardFaceBackProps {
 /**
  * Decorative quick access for a mouse, so it is hidden from assistive tech: the code's
  * real home is the detail modal, which every input method can reach.
+ *
+ * The white face is literal rather than a theme token: a scanner reads contrast, so a
+ * dark-mode card back would not scan.
  */
 export default function CardFaceBack({ card }: ICardFaceBackProps) {
   return (
@@ -30,7 +32,7 @@ export default function CardFaceBack({ card }: ICardFaceBackProps) {
       <div className="grid size-full place-items-center pt-2">
         <CardCode
           codeValue={card.codeValue}
-          codeType={card.codeType as CodeType}
+          codeType={card.codeType}
           className="max-h-full [&_p]:text-sm"
         />
       </div>
diff --git a/frontend/src/app/(user)/digital-cards/components/card-face-front.tsx b/frontend/src/app/(user)/digital-cards/components/card-face-front.tsx
index 4b28a6dc..d467dfea 100644
--- a/frontend/src/app/(user)/digital-cards/components/card-face-front.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/card-face-front.tsx
@@ -1,8 +1,13 @@
 "use client";
 
 import CardIcon from "@/app/(user)/digital-cards/components/card-icon";
+import { cn } from "@/lib/utils";
 import type { DigitalCardDto } from "@/lib/api/types";
 import { formatDate } from "@/utils/strings";
+import {
+  CARD_INK_LIGHT,
+  foregroundFor,
+} from "@/app/(user)/digital-cards/utils/card-colors";
 
 interface ICardFaceFrontProps {
   card: DigitalCardDto;
@@ -13,10 +18,16 @@ interface ICardFaceFrontProps {
  * light-catching top edge and a raised medallion are what sell it at this size.
  */
 export default function CardFaceFront({ card }: ICardFaceFrontProps) {
+  // A yellow or a light brand colour cannot carry white text, so the ink follows the
+  // background rather than the palette promising it never happens.
+  const ink = foregroundFor(card.cardColor);
+  const isLightInk = ink === CARD_INK_LIGHT;
+
   return (
     <div
       className="absolute inset-0 overflow-hidden rounded-xl [backface-visibility:hidden]"
       style={{
+        color: ink,
         background: `linear-gradient(140deg,
           color-mix(in oklab, ${card.cardColor} 86%, white) 0%,
           ${card.cardColor} 48%,
@@ -25,10 +36,14 @@ export default function CardFaceFront({ card }: ICardFaceFrontProps) {
           "inset 0 1px 0 rgba(255,255,255,0.28), inset 0 -1px 0 rgba(0,0,0,0.18)",
       }}
     >
-      {/* Specular band, the detail that makes a flat fill look moulded. */}
+      {/* Specular band, the detail that makes a flat fill look moulded. On a light card
+          it reads as glare rather than sheen, so it softens. */}
       <div
         aria-hidden="true"
-        className="pointer-events-none absolute -inset-x-8 -top-1/3 h-2/3 rotate-[18deg] bg-linear-to-b from-white/22 to-transparent"
+        className={cn(
+          "pointer-events-none absolute -inset-x-8 -top-1/3 h-2/3 rotate-[18deg] bg-linear-to-b to-transparent",
+          isLightInk ? "from-white/22" : "from-white/10",
+        )}
       />
 
       <div className="relative flex size-full flex-col items-center justify-center gap-1.5 p-3">
@@ -40,16 +55,30 @@ export default function CardFaceFront({ card }: ICardFaceFrontProps) {
           />
         </div>
 
-        <p className="line-clamp-1 text-[0.7rem] font-semibold uppercase tracking-[0.14em] text-white/90 drop-shadow-sm">
+        <p
+          className={cn(
+            "line-clamp-1 text-[0.7rem] font-semibold uppercase tracking-[0.14em]",
+            isLightInk && "drop-shadow-sm",
+          )}
+          style={{ opacity: 0.9 }}
+        >
           {card.storeName}
         </p>
       </div>
 
-      <p className="absolute bottom-2 left-3 max-w-[62%] truncate text-xs font-semibold text-white drop-shadow-sm">
+      <p
+        className={cn(
+          "absolute bottom-2 left-3 max-w-[62%] truncate text-xs font-semibold",
+          isLightInk && "drop-shadow-sm",
+        )}
+      >
         {card.cardName}
       </p>
 
-      <p className="absolute bottom-2 right-3 text-[0.65rem] tabular-nums text-white/75">
+      <p
+        className="absolute bottom-2 right-3 text-[0.65rem] tabular-nums"
+        style={{ opacity: 0.75 }}
+      >
         {formatDate(card.updatedAt)}
       </p>
     </div>
diff --git a/frontend/src/app/(user)/digital-cards/components/digital-cards-client.tsx b/frontend/src/app/(user)/digital-cards/components/digital-cards-client.tsx
index 0071b88b..4ba68964 100644
--- a/frontend/src/app/(user)/digital-cards/components/digital-cards-client.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/digital-cards-client.tsx
@@ -84,9 +84,12 @@ export default function DigitalCardsClient({
         <CreateDigitalCardButton />
       </div>
 
-      {!isUserLoading && cards.length > 1 && (
-        <DigitalCardsSortSelect value={sort} onValueChange={setSort} />
-      )}
+      {/* Always mounted, so the control does not appear and vanish under the user. */}
+      <DigitalCardsSortSelect
+        value={sort}
+        onValueChange={setSort}
+        disabled={isUserLoading || cards.length < 2}
+      />
 
       {isUserLoading ? (
         <div className="grid place-items-center">
@@ -96,7 +99,9 @@ export default function DigitalCardsClient({
         <DigitalCardsGrid pinned={pinned} rest={rest} />
       ) : query ? (
         <NoResults
-          icon={<Search className="mx-auto mb-4 size-12 text-gray-400" />}
+          icon={
+            <Search className="mx-auto mb-4 size-12 text-muted-foreground" />
+          }
         />
       ) : (
         <DigitalCardsEmpty />
diff --git a/frontend/src/app/(user)/digital-cards/components/digital-cards-sort-select.tsx b/frontend/src/app/(user)/digital-cards/components/digital-cards-sort-select.tsx
index b1dcee01..76c30f1f 100644
--- a/frontend/src/app/(user)/digital-cards/components/digital-cards-sort-select.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/digital-cards-sort-select.tsx
@@ -10,6 +10,7 @@ import {
 interface IDigitalCardsSortSelectProps {
   value: CardSortMode;
   onValueChange: (value: CardSortMode) => void;
+  disabled?: boolean;
 }
 
 const OPTIONS = CARD_SORT_MODES.map((value) => ({
@@ -20,6 +21,7 @@ const OPTIONS = CARD_SORT_MODES.map((value) => ({
 export default function DigitalCardsSortSelect({
   value,
   onValueChange,
+  disabled,
 }: IDigitalCardsSortSelectProps) {
   return (
     <LabeledSelect
@@ -27,6 +29,7 @@ export default function DigitalCardsSortSelect({
       value={value}
       onValueChange={onValueChange}
       options={OPTIONS}
+      disabled={disabled}
     />
   );
 }
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx b/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx
index 4dcddc6e..791cada0 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/card-image-slot.tsx
@@ -18,7 +18,8 @@ interface ICardImageSlotProps {
   /** Character cap the backend enforces on the data URI. */
   maxLength: number;
   onChange: (value: string | null) => void;
-  onPicked?: (file: File) => void;
+  /** The compressed result, not the original file: the colour sampler reuses this decode. */
+  onPicked?: (encoded: string) => void;
   className?: string;
 }
 
@@ -56,7 +57,7 @@ export default function CardImageSlot({
       }
 
       onChange(encoded);
-      onPicked?.(file);
+      onPicked?.(encoded);
     } catch {
       toast.error("Sliku nije moguće učitati, probaj JPG ili PNG.");
     }
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/card-images-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/card-images-field.tsx
index 3a141de6..f2c946dc 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/card-images-field.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/card-images-field.tsx
@@ -10,7 +10,7 @@ interface ICardImagesFieldProps {
   images: ICardImages;
   onImageChange: (slot: SlotName, value: string | null) => void;
   /** Fires for the icon and front slots, which can suggest the card's colour. */
-  onColorSource: (file: File) => void;
+  onColorSource: (encoded: string) => void;
 }
 
 // The icon is a small medallion, so 256px is plenty. The card faces are the backup a
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/code-preview.tsx b/frontend/src/app/(user)/digital-cards/components/forms/code-preview.tsx
index 210f0a8c..841aaff1 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/code-preview.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/code-preview.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useFormContext } from "react-hook-form";
+import { useFormContext, useWatch } from "react-hook-form";
 import { TriangleAlert } from "lucide-react";
 
 import type { DigitalCardFormData } from "@/lib/api/types";
@@ -13,8 +13,8 @@ import { generateCodeSvg } from "@/app/(user)/digital-cards/utils/generate-code-
  */
 export default function CodePreview() {
   const form = useFormContext<DigitalCardFormData>();
-  const codeValue = form.watch("codeValue");
-  const codeType = form.watch("codeType");
+  const codeValue = useWatch({ control: form.control, name: "codeValue" });
+  const codeType = useWatch({ control: form.control, name: "codeType" });
 
   if (!codeValue?.trim()) return null;
 
@@ -24,6 +24,7 @@ export default function CodePreview() {
     <div className="space-y-2">
       <p className="text-sm font-medium">Prikaz koda</p>
 
+      {/* bg-white is literal on purpose: it shows what a scanner will actually see. */}
       <div className="grid min-h-24 place-items-center rounded-md border bg-white p-3">
         {result.ok ? (
           <div
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/color-picker/card-color-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/card-color-field.tsx
index 4aa626b9..ad3abd01 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/color-picker/card-color-field.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/color-picker/card-color-field.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useState } from "react";
-import { useFormContext } from "react-hook-form";
+import { useFormContext, useWatch } from "react-hook-form";
 
 import { FormDescription, FormLabel, FormMessage } from "@/components/ui/form";
 import type { DigitalCardFormData } from "@/lib/api/types";
@@ -25,7 +25,7 @@ export default function CardColorField({
   const form = useFormContext<DigitalCardFormData>();
   const [variant, setVariant] = useState<ColorPickerVariant>("swatch-slider");
 
-  const value = form.watch("cardColor");
+  const value = useWatch({ control: form.control, name: "cardColor" });
 
   function handleChange(hex: string) {
     form.setValue("cardColor", hex, {
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
index c87a03d7..4312f881 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
@@ -18,6 +18,7 @@ import { takeModalValues } from "@/lib/modal/modal-retry-bus";
 import { closeModalUrl } from "@/lib/modal/modal-navigation";
 import { useFormDraft } from "@/hooks/use-form-draft";
 import { getFormDraft, removeFormDraft } from "@/utils/browser/local-storage";
+import { LOADING_LABELS } from "@/constants/loading-labels";
 import extractDominantColor from "@/utils/browser/extract-dominant-color";
 import CardNameField from "@/app/(user)/digital-cards/components/forms/card-name-field";
 import CardTypeField from "@/app/(user)/digital-cards/components/forms/card-type-field";
@@ -159,9 +160,9 @@ export default function DigitalCardModal({
     form.setValue("cardColor", hex, { shouldDirty: true });
   }
 
-  async function handleColorSource(file: File) {
+  async function handleColorSource(encoded: string) {
     if (colorCustomized) return;
-    const extracted = await extractDominantColor(file);
+    const extracted = await extractDominantColor(encoded);
     if (extracted) suggestColor(extracted);
   }
 
@@ -182,7 +183,17 @@ export default function DigitalCardModal({
       size="lg"
       dirty={form.formState.isDirty || imagesDirty}
       formId="digital-card-form"
-      submitLabel={isEdit ? "Spremi" : "Stvori"}
+      // The label carries the pending state: the spinner alone says something is
+      // happening, not what.
+      submitLabel={
+        isSaving
+          ? isEdit
+            ? LOADING_LABELS.saving
+            : LOADING_LABELS.creating
+          : isEdit
+            ? "Spremi"
+            : "Stvori"
+      }
       submitIcon={Save}
       submitLoading={isSaving}
       submitDisabled={
diff --git a/frontend/src/app/(user)/digital-cards/components/forms/store-name-field.tsx b/frontend/src/app/(user)/digital-cards/components/forms/store-name-field.tsx
index 31b260a1..30b6ce5b 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/store-name-field.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/store-name-field.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useState } from "react";
-import { useFormContext } from "react-hook-form";
+import { useFormContext, useWatch } from "react-hook-form";
 
 import {
   Command,
@@ -25,7 +25,7 @@ import {
 import type { DigitalCardFormData } from "@/lib/api/types";
 import StoreNameOption from "@/app/(user)/digital-cards/components/forms/store-name-option";
 import StoreNameTrigger from "@/app/(user)/digital-cards/components/forms/store-name-trigger";
-import { useStoreNameOptions } from "@/app/(user)/digital-cards/hooks/use-store-name-options";
+import useStoreNameOptions from "@/app/(user)/digital-cards/hooks/use-store-name-options";
 
 interface IStoreNameFieldProps {
   /** Fires only for an official chain, so the caller can offer its logo and brand colour. */
@@ -43,7 +43,7 @@ export default function StoreNameField({
     enabled: open,
   });
 
-  const chainCode = form.watch("chainCode");
+  const chainCode = useWatch({ control: form.control, name: "chainCode" });
 
   function select(label: string, nextChainCode: string | null) {
     form.setValue("storeName", label, {
diff --git a/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx b/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx
index f97b9210..12586b9b 100644
--- a/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/view/card-code-panel.tsx
@@ -4,6 +4,7 @@ import { useMemo } from "react";
 import { TriangleAlert } from "lucide-react";
 
 import type { CodeType } from "@/constants/card-codes";
+import CopyButton from "@/components/custom/common/copy-button";
 import CardCode from "@/app/(user)/digital-cards/components/card-code";
 import {
   generateCodeSvg,
@@ -32,12 +33,23 @@ export default function CardCodePanel({
 
   return (
     <div className="space-y-2">
+      {/* bg-white is literal on purpose: a dark-mode panel would not scan at the till. */}
       <div className="rounded-lg bg-white px-4 py-5 shadow-inner ring-1 ring-black/10">
         <div className={twoDimensional ? "mx-auto max-w-56" : "w-full"}>
           <CardCode codeValue={codeValue} codeType={codeType} showValue />
         </div>
       </div>
 
+      {/* A cashier sometimes has to key the number in, and reading it off a screen is
+          where digits get transposed. */}
+      <div className="flex justify-center">
+        <CopyButton
+          value={codeValue}
+          label="Kopiraj broj kartice"
+          successMessage="Broj kartice je kopiran!"
+        />
+      </div>
+
       {!isRenderable && (
         <p className="flex items-start gap-1.5 text-xs text-amber-700">
           <TriangleAlert
diff --git a/frontend/src/app/(user)/digital-cards/components/view/card-view-actions.tsx b/frontend/src/app/(user)/digital-cards/components/view/card-view-actions.tsx
index 9bb708ea..a84e9b76 100644
--- a/frontend/src/app/(user)/digital-cards/components/view/card-view-actions.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/view/card-view-actions.tsx
@@ -13,6 +13,7 @@ import { DIGITAL_CARD_QUERY_KEYS } from "@/lib/api/digital-cards/keys";
 import { problemMessage } from "@/lib/api/problem-details";
 import type { DigitalCardDto } from "@/lib/api/types";
 import { closeModalUrl, openModalUrl } from "@/lib/modal/modal-navigation";
+import { LOADING_LABELS } from "@/constants/loading-labels";
 
 interface ICardViewActionsProps {
   card: DigitalCardDto;
@@ -86,7 +87,9 @@ export default function CardViewActions({ card }: ICardViewActionsProps) {
         onOpenChange={setConfirmOpen}
         title="Obriši karticu"
         description={`Sigurno želiš obrisati karticu "${card.cardName}"? Ova akcija se ne može poništiti.`}
-        confirmLabel="Obriši"
+        confirmLabel={
+          deleteMutation.isPending ? LOADING_LABELS.deleting : "Obriši"
+        }
         variant="destructive"
         onConfirm={handleDelete}
         isLoading={deleteMutation.isPending}
diff --git a/frontend/src/app/(user)/digital-cards/components/view/digital-card-view-modal.tsx b/frontend/src/app/(user)/digital-cards/components/view/digital-card-view-modal.tsx
index 3d9fdc66..34cf3bf8 100644
--- a/frontend/src/app/(user)/digital-cards/components/view/digital-card-view-modal.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/view/digital-card-view-modal.tsx
@@ -2,7 +2,6 @@
 
 import { ModalShell } from "@/components/custom/modal/modal-shell";
 import { Skeleton } from "@/components/ui/skeleton";
-import type { CodeType } from "@/constants/card-codes";
 import { closeModalUrl } from "@/lib/modal/modal-navigation";
 import { useWakeLock } from "@/hooks/use-wake-lock";
 import CardIcon from "@/app/(user)/digital-cards/components/card-icon";
@@ -66,10 +65,7 @@ export default function DigitalCardViewModal({
         <div className="space-y-4">
           <CardDetailRows card={card} />
 
-          <CardCodePanel
-            codeValue={card.codeValue}
-            codeType={card.codeType as CodeType}
-          />
+          <CardCodePanel codeValue={card.codeValue} codeType={card.codeType} />
 
           <CardFaceImages
             frontImage={card.frontImage}
diff --git a/frontend/src/app/(user)/digital-cards/hooks/use-digital-cards-sort.ts b/frontend/src/app/(user)/digital-cards/hooks/use-digital-cards-sort.ts
index bd8f652c..2985644a 100644
--- a/frontend/src/app/(user)/digital-cards/hooks/use-digital-cards-sort.ts
+++ b/frontend/src/app/(user)/digital-cards/hooks/use-digital-cards-sort.ts
@@ -17,6 +17,9 @@ export function useDigitalCardsSort() {
   // Hydrated after mount, so the server render and the first client render agree.
   useEffect(() => {
     const stored = getDigitalCardSort();
+    // Not derivable during render: localStorage does not exist on the server, so the
+    // first client render has to match the server's default before correcting itself.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     if (isCardSortMode(stored)) setSort(stored);
   }, []);
 
diff --git a/frontend/src/app/(user)/digital-cards/hooks/use-store-name-options.ts b/frontend/src/app/(user)/digital-cards/hooks/use-store-name-options.ts
index 5c05ba3e..09ffd5d9 100644
--- a/frontend/src/app/(user)/digital-cards/hooks/use-store-name-options.ts
+++ b/frontend/src/app/(user)/digital-cards/hooks/use-store-name-options.ts
@@ -18,7 +18,7 @@ interface IUseStoreNameOptionsResult {
   isLoading: boolean;
 }
 
-export function useStoreNameOptions({
+export default function useStoreNameOptions({
   enabled = true,
 }: { enabled?: boolean } = {}): IUseStoreNameOptionsResult {
   // Chain stats are public and cached for six hours, so they carry no enabled gate.
diff --git a/frontend/src/app/(user)/digital-cards/utils/card-colors.ts b/frontend/src/app/(user)/digital-cards/utils/card-colors.ts
index 8e3277ca..94484953 100644
--- a/frontend/src/app/(user)/digital-cards/utils/card-colors.ts
+++ b/frontend/src/app/(user)/digital-cards/utils/card-colors.ts
@@ -1,7 +1,12 @@
 /**
- * Card colours are locked to one saturation and lightness pair, so every hue the user can
- * reach stays legible under white text and the wallet reads as one designed set. The hue
- * slider and the swatches are therefore the same system: a swatch is just a hue stop.
+ * Card colours are locked to one saturation and lightness pair, so the wallet reads as one
+ * designed set. The hue slider and the swatches are therefore the same system: a swatch is
+ * just a hue stop.
+ *
+ * Locking them does NOT make white text legible everywhere. Yellow and green sit far
+ * brighter than blue at the same lightness, so hue 55 lands near 2.7:1 against white
+ * against a 4.5:1 minimum. Text colour is chosen per card by foregroundFor() instead,
+ * which also covers the chain brand colours, several of which are lighter still.
  */
 const CARD_SATURATION = 62;
 const CARD_LIGHTNESS = 42;
@@ -33,16 +38,6 @@ export function hslToHex(hue: number, saturation: number, lightness: number) {
   return `#${channel(0)}${channel(8)}${channel(4)}`;
 }
 
-/** The hex a given hue produces, which is what both the slider and the swatches emit. */
-export function hexForHue(hue: number): string {
-  return hslToHex(hue, CARD_SATURATION, CARD_LIGHTNESS);
-}
-
-export const CARD_SWATCHES: string[] = [
-  ...SWATCH_HUES.map(hexForHue),
-  ...NEUTRAL_CARD_COLORS,
-];
-
 export function hexToRgb(hex: string): [number, number, number] {
   const normalized = hex.replace("#", "");
 
@@ -53,6 +48,74 @@ export function hexToRgb(hex: string): [number, number, number] {
   ];
 }
 
+/** Ink for a coloured card, dark enough to clear 4.5:1 wherever white cannot. */
+export const CARD_INK_LIGHT = "#ffffff";
+export const CARD_INK_DARK = "#1c1917";
+
+/** Any card colour must clear this against whichever ink foregroundFor picks. */
+const MIN_CONTRAST = 4.5;
+const LIGHTNESS_STEP = 2;
+const MIN_LIGHTNESS = 20;
+
+function channelLuminance(channel: number): number {
+  const c = channel / 255;
+
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+/** WCAG relative luminance, the basis of every contrast ratio below. */
+export function relativeLuminance(hex: string): number {
+  const [r, g, b] = hexToRgb(hex).map(channelLuminance);
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+export function contrastRatio(a: string, b: string): number {
+  const [lighter, darker] = [relativeLuminance(a), relativeLuminance(b)].sort(
+    (x, y) => y - x,
+  );
+
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * The readable ink for a given card colour. Picks whichever of the two clears 4.5:1 by
+ * more, so a freeform hue and a curated brand colour are both covered by one rule rather
+ * than by trusting the palette.
+ */
+export function foregroundFor(background: string): string {
+  return contrastRatio(background, CARD_INK_LIGHT) >=
+    contrastRatio(background, CARD_INK_DARK)
+    ? CARD_INK_LIGHT
+    : CARD_INK_DARK;
+}
+
+/**
+ * The hex a given hue produces, which is what both the slider and the swatches emit.
+ *
+ * Most hues are legible at the base lightness under one ink or the other, but a band
+ * around cyan (hue 200 or so) sits in a dead zone where neither clears 4.5. Darkening
+ * only ever raises contrast against white, so those hues step down until one ink works.
+ * In practice that is a two point drop on a handful of hues, invisible beside them.
+ */
+export function hexForHue(hue: number): string {
+  for (
+    let lightness = CARD_LIGHTNESS;
+    lightness > MIN_LIGHTNESS;
+    lightness -= LIGHTNESS_STEP
+  ) {
+    const hex = hslToHex(hue, CARD_SATURATION, lightness);
+    if (contrastRatio(hex, foregroundFor(hex)) >= MIN_CONTRAST) return hex;
+  }
+
+  return hslToHex(hue, CARD_SATURATION, MIN_LIGHTNESS);
+}
+
+export const CARD_SWATCHES: string[] = [
+  ...SWATCH_HUES.map(hexForHue),
+  ...NEUTRAL_CARD_COLORS,
+];
+
 export interface IHueInfo {
   hue: number;
   /** Below this, a colour is a grey and has no meaningful hue to sort by. */
diff --git a/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts b/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts
index 3ebef63d..1c29bc5d 100644
--- a/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts
+++ b/frontend/src/app/(user)/digital-cards/utils/card-sorting.ts
@@ -32,6 +32,11 @@ export const CARD_SORT_LABELS: Record<CardSortMode, string> = {
   cardColor: "Boja",
 };
 
+/**
+ * Compared as strings, not parsed dates. The server sends ISO-8601, which already sorts
+ * chronologically byte by byte, so this cannot produce the NaN that date arithmetic can
+ * when a timestamp is malformed.
+ */
 function byNewestFirst(a: string, b: string): number {
   return b.localeCompare(a);
 }
diff --git a/frontend/src/lib/api/digital-cards/hooks.ts b/frontend/src/lib/api/digital-cards/hooks.ts
index 0ac71e90..3861a2ff 100644
--- a/frontend/src/lib/api/digital-cards/hooks.ts
+++ b/frontend/src/lib/api/digital-cards/hooks.ts
@@ -16,7 +16,8 @@ export function useCreateDigitalCard() {
   return useMutation<DigitalCardDto, Error, DigitalCardRequest>({
     mutationKey: OFFLINE_MUTATION_KEYS.digitalCardCreate,
     mutationFn: createDigitalCard,
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: DIGITAL_CARD_QUERY_KEYS.all }),
+    onSuccess: () =>
+      queryClient.invalidateQueries({ queryKey: DIGITAL_CARD_QUERY_KEYS.all }),
   });
 }
 
@@ -39,7 +40,8 @@ export function useUpdateDigitalCard() {
   >({
     mutationKey: OFFLINE_MUTATION_KEYS.digitalCardUpdate,
     mutationFn: ({ id, data }) => updateDigitalCard(id, data),
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: DIGITAL_CARD_QUERY_KEYS.all }),
+    onSuccess: () =>
+      queryClient.invalidateQueries({ queryKey: DIGITAL_CARD_QUERY_KEYS.all }),
   });
 }
 
@@ -48,7 +50,8 @@ export function useDeleteDigitalCard() {
   return useMutation<void, Error, string>({
     mutationKey: OFFLINE_MUTATION_KEYS.digitalCardDelete,
     mutationFn: deleteDigitalCard,
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: DIGITAL_CARD_QUERY_KEYS.all }),
+    onSuccess: () =>
+      queryClient.invalidateQueries({ queryKey: DIGITAL_CARD_QUERY_KEYS.all }),
   });
 }
 
@@ -57,6 +60,7 @@ export function useSetDigitalCardPinned() {
   return useMutation<DigitalCardDto, Error, { id: string; pinned: boolean }>({
     mutationKey: OFFLINE_MUTATION_KEYS.digitalCardSetPinned,
     mutationFn: ({ id, pinned }) => setDigitalCardPinned(id, pinned),
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: DIGITAL_CARD_QUERY_KEYS.all }),
+    onSuccess: () =>
+      queryClient.invalidateQueries({ queryKey: DIGITAL_CARD_QUERY_KEYS.all }),
   });
 }
diff --git a/frontend/src/utils/browser/extract-dominant-color.ts b/frontend/src/utils/browser/extract-dominant-color.ts
index 9d622acd..dad20fb1 100644
--- a/frontend/src/utils/browser/extract-dominant-color.ts
+++ b/frontend/src/utils/browser/extract-dominant-color.ts
@@ -13,10 +13,17 @@ const SAMPLE_SIZE = 48;
  * whitespace, and letting that win would make every suggestion grey.
  */
 export default async function extractDominantColor(
-  source: Blob,
+  source: Blob | string,
 ): Promise<string | null> {
+  let bitmap: ImageBitmap | null = null;
+
   try {
-    const bitmap = await createImageBitmap(source);
+    // A data URI is the already-downscaled WebP the compressor produced, so sampling it
+    // avoids decoding a multi-megapixel original a second time.
+    const blob =
+      typeof source === "string" ? await (await fetch(source)).blob() : source;
+
+    bitmap = await createImageBitmap(blob);
     const canvas = document.createElement("canvas");
     canvas.width = SAMPLE_SIZE;
     canvas.height = SAMPLE_SIZE;
@@ -25,7 +32,6 @@ export default async function extractDominantColor(
     if (!context) return null;
 
     context.drawImage(bitmap, 0, 0, SAMPLE_SIZE, SAMPLE_SIZE);
-    bitmap.close();
 
     const { data } = context.getImageData(0, 0, SAMPLE_SIZE, SAMPLE_SIZE);
     const buckets = new Map<number, number>();
@@ -71,5 +77,9 @@ export default async function extractDominantColor(
     return hexForHue(dominant * 15);
   } catch {
     return null;
+  } finally {
+    // Drawing and getImageData can both throw, and an unclosed bitmap holds its decoded
+    // pixels until GC gets round to it.
+    bitmap?.close();
   }
 }

From 5411c366e11ad1e5562da6e2861c8a6c5b243f3e Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Fri, 7 Aug 2026 12:22:26 +0200
Subject: [PATCH 13/14] docs(digital-cards): Document the wallet and correct
 what the rework invalidated

Changes:
- Add docs/DIGITAL-CARDS.md and index it in docs/README.md
- Correct the digital-cards lines in STATE-PERSISTENCE, PWA, MOBILE-NAV, SEARCH and LANDING

The new doc covers the data model, the code vocabulary and why it matches the
scanner's, the store autocomplete and its community half, the contrast rule, the
image pipeline, and the four-step offline write registration.

Corrections, all of them things the rework made untrue:
- The card code is excluded from drafts as `codeValue`, not `value`, and now
  survives a failed save through modal-retry-bus rather than being lost.
- digital-cards-client no longer consumes useViewMode, so products-client is its
  only remaining consumer.
- The PWA wake-lock TODO is done, `storeNames` joined the persistence whitelist,
  and the shortcut top three are now decided.
- The Kartice long press is live and the cell is no longer admin-only.
- The card search filters cardName, storeName and note.
- Digitalne kartice left the landing page's coming-soon list.

Checked and left alone: AUTH, BRAND, DEPLOYMENT, SHARING, SUPPORT, none of which
mention digital cards.
---
 docs/DIGITAL-CARDS.md     | 324 ++++++++++++++++++++++++++++++++++++++
 docs/LANDING.md           |   2 +-
 docs/MOBILE-NAV.md        |  18 +--
 docs/PWA.md               |   6 +-
 docs/README.md            |   1 +
 docs/SEARCH.md            |   2 +-
 docs/STATE-PERSISTENCE.md |   6 +-
 7 files changed, 342 insertions(+), 17 deletions(-)
 create mode 100644 docs/DIGITAL-CARDS.md

diff --git a/docs/DIGITAL-CARDS.md b/docs/DIGITAL-CARDS.md
new file mode 100644
index 00000000..a40b4fe9
--- /dev/null
+++ b/docs/DIGITAL-CARDS.md
@@ -0,0 +1,324 @@
+# Disscount: Digital Cards (Digitalne kartice)
+
+The loyalty-card wallet. A user saves the plastic cards they already carry, and the app renders the barcode or QR on demand so the card can be scanned straight off the phone at the till.
+
+Two things shape every decision in here:
+
+1. **It is used in a shop.** Often in a basement with no signal, at a till, with someone waiting. So it works offline, it opens fast, and the code panel is built for a scanner rather than for looks.
+2. **A card number is a secret.** It never reaches localStorage, never reaches a URL, and never reaches a search parameter.
+
+## Table of contents
+
+1. [Quick reference](#1-quick-reference)
+2. [How a card flows through the system](#2-how-a-card-flows-through-the-system)
+3. [The data model](#3-the-data-model)
+4. [Codes: scanning in, drawing out](#4-codes-scanning-in-drawing-out)
+5. [Stores: official chains and community names](#5-stores-official-chains-and-community-names)
+6. [Colour and contrast](#6-colour-and-contrast)
+7. [Images](#7-images)
+8. [Offline](#8-offline)
+9. [Key files](#9-key-files)
+10. [Libraries](#10-libraries)
+11. [What is automatic vs manual](#11-what-is-automatic-vs-manual)
+12. [Gotchas and lessons learned](#12-gotchas-and-lessons-learned)
+13. [Future improvements and TODOs](#13-future-improvements-and-todos)
+
+---
+
+## 1. Quick reference
+
+| Thing             | Value                                                           |
+| ----------------- | --------------------------------------------------------------- |
+| Route             | `/digital-cards`, protected, in `PROTECTED_ROUTE_PREFIXES`      |
+| Backend base path | `/api/digital-cards`, plus `/api/store-names`                   |
+| Query key root    | `digitalCards`, persisted offline. Suggestions use `storeNames` |
+| Modals            | `?modal=digital-card/new`, `/edit&id=`, `/view&id=`             |
+| Barcode renderer  | `@bwip-js/browser`, synchronous, SVG                            |
+| Scanner preset    | `all`, unlike products which lock to EAN                        |
+| Bottom nav        | Fifth cell, long press opens a new card                         |
+| PWA shortcut      | Second of three on Android, after Skeniraj                      |
+
+---
+
+## 2. How a card flows through the system
+
+```mermaid
+flowchart TD
+    A[User taps Dodaj karticu] --> B[digital-card-modal]
+    B --> C{How is the code entered?}
+    C -->|Scanner icon| D[useCameraScanner preset all]
+    C -->|Typed| E[codeValue field]
+    D --> F[rawValue + format]
+    F --> G[toCodeType maps format to our vocabulary]
+    E --> H
+    G --> H[code-preview draws it live]
+    H --> I{bwip-js can encode it?}
+    I -->|Yes| J[SVG preview]
+    I -->|No| K[Large-print value + warning]
+    B --> L[Submit]
+    L --> M[Modal closes immediately]
+    M --> N{Online?}
+    N -->|Yes| O[POST /api/digital-cards]
+    N -->|No| P[Mutation pauses in the offline queue]
+    P -->|Reconnect| O
+    O --> Q[Card appears in the grid]
+    Q --> R[Tap a tile]
+    R --> S[View modal: big code, wake lock on]
+```
+
+The submit path is worth understanding because it is not the obvious one. The modal **closes before the request finishes**. If the write then fails, the error is parked in `modal-error-bus`, the modal reopens, and the error is applied to the form. This is the same pattern shopping lists use, and it is why the wallet feels instant.
+
+---
+
+## 3. The data model
+
+Backend entity `disscount.digitalCard.domain.DigitalCard`, table `digital_card`.
+
+| Column                      | Type                   | Notes                                                                      |
+| --------------------------- | ---------------------- | -------------------------------------------------------------------------- |
+| `id`                        | UUID                   |                                                                            |
+| `user_id`                   | UUID FK                | Lazy `@ManyToOne` to `app_user`                                            |
+| `card_name`                 | varchar                | What the user calls it                                                     |
+| `card_type`                 | varchar(16)            | `loyalty` / `gift` / `membership` / `other`. A plain String, never an enum |
+| `store_name`                | varchar                | Free text, always set                                                      |
+| `chain_code`                | varchar(40), nullable  | Set only when an official chain was picked                                 |
+| `code_value`                | varchar(4096)          | The card number                                                            |
+| `code_type`                 | varchar(32)            | Barcode Detection API format name, or `unknown`                            |
+| `card_color`                | varchar(7)             | `#rrggbb`                                                                  |
+| `icon_image`                | TEXT, nullable         | base64 data URI                                                            |
+| `front_image`               | TEXT, nullable         | base64 data URI                                                            |
+| `back_image`                | TEXT, nullable         | base64 data URI                                                            |
+| `note`                      | varchar(500), nullable |                                                                            |
+| `pinned_at`                 | timestamp, nullable    | Null means not pinned                                                      |
+| `created_at` / `updated_at` | timestamp              | Stamped through `Timestamps.nowUtc()`                                      |
+| `deleted_at`                | timestamp, nullable    | Soft delete                                                                |
+
+**Why `card_type` is a String and not an enum.** The backend runs `ddl-auto=update`, which never drops anything. Turning a column into a Java enum makes Hibernate add a CHECK constraint; changing the vocabulary later leaves the old constraint behind, and every write that uses a new value fails with a 500. Same reasoning applies to `code_type`, which additionally must accept whatever a browser's Barcode Detection API decides to return, without needing a backend release.
+
+**Why `pinned_at` is a timestamp and not a boolean.** It matches the rest of the codebase (`User`'s notification toggles, `ContactMessage.readAt`), and it records _when_, which a boolean throws away.
+
+**Ownership.** Every id-addressed method goes through `findActiveByIdAndUser(cardId, user)`, so the ownership check is the query itself and cannot be forgotten in a service method. Do not copy `NotificationController`, which omits it.
+
+---
+
+## 4. Codes: scanning in, drawing out
+
+### The vocabulary
+
+`codeType` stores the **Barcode Detection API's own format names**: `ean_13`, `qr_code`, `code_128`, and so on. This is deliberate. The scanner already hands back exactly these strings, so a scan needs no translation on the way in.
+
+There is one extra value, `unknown`, labelled **"Samo broj/tekst"** in the UI. It covers two cases: a membership number that has no barcode at all, and a value the chosen symbology cannot encode. Both render as large high-contrast text instead.
+
+### Scanning
+
+`useCameraScanner().openScanner({ preset: "all", onScan })` from `context/scanner-context.tsx`. The `all` preset accepts QR, Aztec, Codabar, Code 39/93/128, Data Matrix, ITF and PDF417 on top of the retail EAN/UPC formats. Products lock to `product` (EAN only); a loyalty card can carry anything.
+
+`onScan` fills `codeValue` **and** `codeType` in one go, then the preview redraws.
+
+### Drawing
+
+`utils/generate-code-svg.ts` wraps `@bwip-js/browser`.
+
+```ts
+generateCodeSvg(codeValue, codeType);
+// -> { ok: true, svg } | { ok: false, reason: "unsupported" | "invalid" }
+```
+
+It **never throws**. bwip-js rejects a value that does not fit its symbology (an EAN-13 needs twelve digits plus a checksum), and that is a normal thing for a user to do, not an exception. The caller renders the plain value instead.
+
+Two details worth keeping:
+
+- `includetext: false`. The human-readable line is our own HTML, which keeps user input out of the SVG string that gets injected with `dangerouslySetInnerHTML`.
+- `CODE_TYPE_TO_BCID` maps our stored names to bwip-js encoder names. They are not the same: `itf` becomes `interleaved2of5`, `aztec` becomes `azteccode`, and `codabar` becomes `rationalizedCodabar`.
+
+---
+
+## 5. Stores: official chains and community names
+
+A card carries **both** `storeName` (free text, always) and `chainCode` (nullable). Picking an official chain sets both; typing free text clears `chainCode`.
+
+The autocomplete has two groups:
+
+| Group             | Source                                                                 |
+| ----------------- | ---------------------------------------------------------------------- |
+| Službene trgovine | `cijeneService.useGetChainStats()`, labelled through `getChainLabel()` |
+| Ostalo            | `GET /api/store-names`, the community suggestions                      |
+
+### Community store names
+
+When a user saves a card with free text and no chain code, that name is recorded in `store_name_suggestion` and offered to everyone else. The aim is to stop the same corner shop accumulating under five spellings.
+
+The table **carries no user reference of any kind**. The list is public, so attribution must not be recoverable from it.
+
+`normalized_name` is the dedupe key: lowercased, diacritics stripped, `đ` mapped to `d`, via `StoreNameNormalizer`, mirroring the frontend's `normalizeForSearch`.
+
+`usage_count` is a **monotonic submission count**, not a live count of cards using the name. It is never decremented on delete. It only orders the list, and a live count would need decrements, orphan cleanup and a backfill for no visible gain.
+
+---
+
+## 6. Colour and contrast
+
+Every card has a colour, and the colour backs text, so contrast is a correctness problem rather than a styling one.
+
+Colours are generated at one fixed saturation and lightness, so the wallet reads as one designed set. **That alone does not make white text legible.** Yellow and green are far brighter than blue at the same lightness: hue 55 lands near `#aea229`, which is about 2.7:1 against white, well under the 4.5:1 minimum. Several curated chain brand colours are just as light.
+
+Two rules fix it together:
+
+1. **`foregroundFor(hex)`** picks white or a dark ink per card, whichever wins on contrast. This covers the freeform hue slider and the brand colour map with one rule.
+2. **`hexForHue(hue)`** darkens a hue until one of the two inks clears 4.5:1. A band around cyan sits in a dead zone where neither ink passes at the base lightness; those hues step down a couple of points. Worst case across all 360 hues is 4.52:1.
+
+The colour is suggested, in this order, and only until the user touches the picker:
+
+1. The chain's brand colour, from `CHAIN_BRAND_COLORS`.
+2. The dominant colour of an uploaded icon or front image, from `extractDominantColor`.
+
+A manual pick wins permanently. Resetting the form restores the suggestions.
+
+---
+
+## 7. Images
+
+Three optional base64 images: `iconImage` (256px), `frontImage` and `backImage` (1024px). The card faces are the backup when a generated code will not scan, so the cashier can read the number or barcode off the photo.
+
+All three go through **`resizeImageToWebp`**, the same compressor the settings avatar uses. Nothing here rolls its own. EXIF orientation is handled for free, because `createImageBitmap` applies it by default, which matters when the photo came from a phone held in portrait.
+
+Images live **outside react-hook-form** in `use-card-images.ts`, exactly like the settings avatar field, for two reasons: a base64 image would blow the localStorage draft quota, and it does not belong in dirty tracking. The modal merges them back in on submit and folds their dirty flag into the shell's indicator.
+
+The colour sampler receives the **compressed output**, not the original file. Passing the original meant decoding a possibly 12-megapixel photo a second time, right after the compressor had already decoded it.
+
+---
+
+## 8. Offline
+
+Offline is the whole point, so both halves are wired.
+
+**Reads.** `digitalCards` and `storeNames` are in `PERSISTED_QUERY_KEY_PREFIXES` in `lib/offline/cached-query-keys.ts`, so the wallet and the autocomplete survive a reload with no signal.
+
+**Writes.** Four mutations are registered in `lib/offline/offline-mutations.ts` so a reload can replay them: create, update, delete and pin. Each needs four things kept in sync, and missing one fails quietly:
+
+1. A key in `OFFLINE_MUTATION_KEYS`.
+2. That key as `mutationKey` on the hook.
+3. A `defineOfflineMutation` registration with the raw query function.
+4. The raw query function exported from `lib/api/digital-cards`.
+
+Create, update and pin also pass an `onError` handler. A reload loses the `onError` given at `mutate()` time, and those three have no modal left to show an error in, so without it a failed replay reverted in silence. Delete does not pass one, because its only caller already toasts.
+
+There is **no `GET /api/digital-cards/{id}`**. The view and edit modals select the card out of the `["digitalCards", "me"]` cache through `useDigitalCard(id)`. This is what makes a deep link work offline: a by-id fetch would have no cache entry to fall back on.
+
+---
+
+## 9. Key files
+
+### Frontend, feature
+
+| Path                                                    | Role                                                      |
+| ------------------------------------------------------- | --------------------------------------------------------- |
+| `app/(user)/digital-cards/page.tsx`                     | Server component, reads `?q=`                             |
+| `components/digital-cards-client.tsx`                   | Auth gate, search, sort, the three body states            |
+| `components/digital-card-tile.tsx`                      | The 3:2 tile, flip container, overlay open button         |
+| `components/card-face-front.tsx` / `card-face-back.tsx` | The two faces                                             |
+| `components/card-code.tsx`                              | Renders the SVG or the large-print fallback               |
+| `components/card-icon.tsx`                              | Icon fallback chain: image, chain logo, initials, generic |
+| `components/forms/digital-card-modal.tsx`               | Create and edit, drafts, retry, colour suggestions        |
+| `components/forms/store-name-field.tsx`                 | The grouped autocomplete                                  |
+| `components/forms/code-field.tsx`                       | Input plus the scanner button                             |
+| `components/forms/color-picker/`                        | Three variants behind a temporary switcher                |
+| `components/view/digital-card-view-modal.tsx`           | The till view, holds the wake lock                        |
+| `components/view/card-code-panel.tsx`                   | Forced-white high-contrast code panel                     |
+| `utils/card-colors.ts`                                  | Palette, brand map, contrast helpers                      |
+| `utils/generate-code-svg.ts`                            | The bwip-js boundary                                      |
+| `utils/card-sorting.ts`                                 | Six comparators plus the pinned split                     |
+| `hooks/use-card-images.ts`                              | The three images, outside RHF                             |
+
+### Frontend, shared
+
+| Path                                                  | Role                                                |
+| ----------------------------------------------------- | --------------------------------------------------- |
+| `constants/card-codes.ts`                             | `CARD_TYPES`, `CODE_TYPES`, `SCANNABLE_CODE_TYPES`  |
+| `lib/api/digital-cards/{keys,queries,hooks,index}.ts` | Service layer                                       |
+| `lib/api/store-names/`                                | Suggestion service                                  |
+| `lib/modal/modal-retry-bus.ts`                        | In-memory stash for values that must not touch disk |
+| `hooks/use-wake-lock.ts`                              | Screen wake lock, shared                            |
+| `utils/browser/extract-dominant-color.ts`             | Dominant hue of an image                            |
+| `utils/browser/image.ts`                              | `resizeImageToWebp`, shared with the avatar         |
+
+### Backend
+
+| Path                                                    | Role                                               |
+| ------------------------------------------------------- | -------------------------------------------------- |
+| `disscount/digitalCard/domain/DigitalCard.java`         | Entity                                             |
+| `disscount/digitalCard/dao/DigitalCardRepository.java`  | `findActiveBy...` JPQL                             |
+| `disscount/digitalCard/service/DigitalCardService.java` | CRUD, pin, suggestion recording                    |
+| `disscount/digitalCard/rest/DigitalCardController.java` | `/api/digital-cards`                               |
+| `disscount/storeName/`                                  | Suggestion entity, normalizer, service, controller |
+
+---
+
+## 10. Libraries
+
+| Library                    | Version          | Used for                                     |
+| -------------------------- | ---------------- | -------------------------------------------- |
+| `@bwip-js/browser`         | `^4.11.2`        | Drawing barcodes and QR as SVG               |
+| `@yudiel/react-qr-scanner` | `^2.6.0`         | The camera scanner                           |
+| `barcode-detector`         | `^3.2.1`         | Format names and the still-image decode path |
+| `react-hook-form`          | `^7.68.0`        | The card form                                |
+| `zod`                      | `^4.1.13`        | Request, form and DTO schemas                |
+| `@tanstack/react-query`    | `^5.90.12`       | Caching and the offline mutation queue       |
+| `motion`                   | `^12.23.26`      | The staggered grid reveal                    |
+| Spring Boot                | `3.1.0`, Java 21 | Backend                                      |
+
+No colour picker library. The picker is swatches plus a styled range input, roughly forty lines, and adding one would have been more code than writing it.
+
+---
+
+## 11. What is automatic vs manual
+
+| Concern                | Automatic                                      | Manual                                             |
+| ---------------------- | ---------------------------------------------- | -------------------------------------------------- |
+| Chain list             | Pulled from the price API and cached six hours | Adding a logo PNG to `public/store-chains/`        |
+| Chain brand colour     | Suggested on pick                              | Curating `CHAIN_BRAND_COLORS` by hand              |
+| Card colour legibility | `foregroundFor` picks the ink per card         | Nothing                                            |
+| Code type after a scan | Filled from the detected format                | Correcting it if the scanner guessed wrong         |
+| Offline reads          | Persisted by the key allowlist                 | Adding a new query root to that allowlist          |
+| Offline writes         | Replayed on reconnect                          | The four-step registration per mutation            |
+| Community store names  | Recorded on save, offered to everyone          | Moderation, which does not exist yet               |
+| PWA shortcut           | Emitted from the nav item                      | Generating the icon PNGs and picking the top three |
+| Schema changes         | `ddl-auto=update` adds columns                 | Dropping or renaming anything, by hand, in SQL     |
+
+---
+
+## 12. Gotchas and lessons learned
+
+**bwip-js does not tree shake.** The docs say per-symbology imports keep the bundle small. They do not: BWIPP is one generated blob, so importing thirteen encoders costs the same as importing all hundred. Measured at 844 KB raw, 210 KB gzipped, confirmed by finding unimported symbologies in the build output. Webpack does scope it to the `/digital-cards` route chunk, so no other page pays for it. `generateCodeSvg` is deliberately synchronous, because every tile draws a code and a lazy import would only move the same download behind a loading state.
+
+**Codabar's export is `rationalizedCodabar`.** And the `bcid` option must be the bwip-js encoder name, not the scanner's format string. Both were wrong first time and only the compiler caught the first one.
+
+**Module-scope constants have a dead zone.** `CARD_SWATCHES` calls `hexForHue` while the module is still evaluating, and `hexForHue` now needs the ink constants. A `const` declared below would be read in its temporal dead zone and throw at import time, taking the whole page with it. Contrast helpers therefore sit **above** `hexForHue` in `card-colors.ts`, and moving them will break the page rather than fail a test.
+
+**The entity outlet stays mounted between openings.** So a modal reached twice with different ids reuses the instance. The card form's draft merge bails out while the form is dirty, which meant editing card A, closing, then opening card B showed A's edits under B's title. Both card modals are keyed by id in `entity-modal-outlet.tsx`. Add-to-list and watchlist carry the same fix for the same reason.
+
+**A card code must never reach disk, but must survive a retry.** These pull in opposite directions. The rule that reconciles them: never on disk, fine in memory until the submit settles. `codeValue` is in `useFormDraft`'s `exclude`, and a failed optimistic save stashes it in `modal-retry-bus`, an in-memory sibling of the error bus that dies with the tab. Drafts written by older builds are deleted outright rather than sanitised, because their shape came from a build we no longer have.
+
+**A card code must never reach a URL either.** The page search filters on `cardName`, `storeName` and `note` only. Adding `codeValue` would put card numbers into `?q=`, into history, and into anything that reads either.
+
+**`ddl-auto=update` never drops anything.** Production still held the pre-rework `digital_card` table, whose columns did not match. It had to be dropped by hand before deploying, or the new schema would have merged into the stale columns and the new `NOT NULL` columns would have failed against existing rows.
+
+**Recording a store name must not poison the card save.** `StoreNameSuggestionService.record()` runs inside the card-save transaction. A concurrent insert colliding on the unique `normalized_name` marks that transaction rollback-only **even when the exception is caught**, so the card save would fail for an unrelated reason. `@Transactional(propagation = REQUIRES_NEW)` gives it its own transaction, and it swallows and logs. It is called from a different bean, which is what makes the proxy apply the annotation at all: a self-invocation would silently skip it.
+
+**The specular sheen is not decoration.** A flat coloured div does not read as a card. The diagonal band, the light-catching top edge and the raised icon medallion are what sell it at tile size, and the band softens on light cards where it would otherwise read as glare.
+
+**Reduced motion has to gate the transform, not just the transition.** Gating only the transition leaves a reduced-motion user with an instant snap to the flipped state, which is worse than no flip. Tailwind's `hover:` variant already wraps in `@media (hover: hover)`, so a tap never triggers the flip on touch.
+
+---
+
+## 13. Future improvements and TODOs
+
+- [ ] **Pick one colour picker.** Three variants ship behind a temporary switcher (`color-picker-switcher.tsx`, labelled privremeno) so they can be compared in the running app. Deleting the two losers and the switcher is a follow-up.
+- [ ] **Migrate to the newer data-fetching conventions.** Digital cards is the last domain still on `useGetCurrentUserDigitalCards` rather than `queryOptions()` descriptors, `useAuthedQuery` and `AsyncSection`, and it has no colocated skeletons or `loading.tsx`. Blocked on the loading-system PR landing.
+- [ ] **Moderate community store names.** The entity already carries `hidden_at` for it. Admin needs to list, hide, restore, rename and merge, following `AdminContactController`, with `requireAdmin` called inside the service rather than the controller. A `merged_into_id` column comes with it.
+- [ ] **Raise `MIN_PUBLIC_USAGE` to 2.** It is 1 so the suggestion group is not empty at launch. Two is better for typo hygiene once there is volume.
+- [ ] **Onboarding v2 should nudge saving a card**, seeded from the chains the user pins in preferences. Suggest, never require. TODO sits in `onboarding-steps.ts`.
+- [ ] **Consider scrubbing card codes from Sentry.** Share tokens already have `scrub-share-token.ts` because they are secrets; a card code is a secret in the same way. Needs a look at whether one can actually reach a breadcrumb first.
+- [ ] **Export and import cards**, so a phone change does not mean retyping the wallet.
+- [ ] **Loyalty prices.** The long game: if the chains ever expose them, a card links a user to the prices that only apply with it, which then reaches the product card, the shopping list total and the best-store calculation.
+- [ ] **`GET /api/digital-cards/{id}`** if a card ever needs to be reachable by someone who is not its owner. Today the absence is a feature, not a gap.
diff --git a/docs/LANDING.md b/docs/LANDING.md
index 8f96885f..52772551 100644
--- a/docs/LANDING.md
+++ b/docs/LANDING.md
@@ -267,7 +267,7 @@ The exact chain count is never hardcoded. The number of covered retail chains gr
 
 ## Future improvements and TODOs
 
-- Wire the remaining coming-soon feature cards (Analiza potrošnje, Digitalne kartice, Karta trgovina) once their pages ship, by uncommenting the `href` in `features.ts` and dropping `comingSoon`.
+- Wire the remaining coming-soon feature cards (Analiza potrošnje, Karta trgovina) once their pages ship, by uncommenting the `href` in `features.ts` and dropping `comingSoon`.
 - Move `ScrollReveal` and `StaggerChildren` out of `components/ui/` (AGENTS.md reserves that folder for unedited shadcn primitives) into `components/custom/` (e.g. an `animation/` folder) with default exports, matching the convention for hand-written components.
 - Consider an FAQ-driven long-tail SEO expansion and a real testimonials/social-proof section once there is content for it.
 - The landing is Croatian-only; if the app adds `next-intl`, the landing copy in the `data/*` files is the natural first surface to translate.
diff --git a/docs/MOBILE-NAV.md b/docs/MOBILE-NAV.md
index 77a080f5..56312a94 100644
--- a/docs/MOBILE-NAV.md
+++ b/docs/MOBILE-NAV.md
@@ -126,7 +126,7 @@ A locked cell is a `disabled` button in `text-muted-foreground/70`, so it takes
 Two things worth knowing:
 
 - This runs **against** Apple's Human Interface Guidelines, which are emphatic that a tab must never be disabled (in iOS 26 `UITabBarItem.isEnabled` has no effect at all). Consistency with the app's other two navigations won, since a bar that walks you into a teaser page the header refuses to open is the more confusing inconsistency.
-- The admin escape exists so `/digital-cards`, which is a working page carrying the badge only until barcode rendering lands, stays reachable from a phone.
+- The admin escape was there so `/digital-cards` stayed reachable while it carried the coming-soon badge. The page has since shipped and dropped the flag, so the escape no longer applies to it.
 
 The same rule now applies to `HeaderNavItem`, which previously blocked coming-soon items for admins too. Note that the escape is unreachable there today: `HeaderNav` swaps the whole list for a single dashboard link whenever `canAccessDashboard` is true, which covers every admin. It is there for consistency and for whenever that layout changes.
 
@@ -445,14 +445,14 @@ A sheet can also decline the field: `ProductsSheet` withholds `initialFocusRef`
 
 Long press is strictly an **accelerator**, never the only way to reach something. Every target is a `?modal=` URL that a visible, tappable control also reaches, which is what keeps it keyboard and screen-reader accessible.
 
-| Gesture                  | On `/products/<ean>`       | Everywhere else            | Enabled?                                                |
-| ------------------------ | -------------------------- | -------------------------- | ------------------------------------------------------- |
-| Hold **Karta**           | store preferences          | store preferences          | admins only, until the map drops `comingSoon`           |
-| Hold **Praćenje**        | `?modal=watchlist&ean=…`   | nothing                    | yes                                                     |
-| Hold the **centre cell** | the barcode scanner        | the barcode scanner        | yes                                                     |
-| Hold **Popisi**          | `?modal=add-to-list&ean=…` | `?modal=shopping-list/new` | yes                                                     |
-| Hold **Kartice**         | `?modal=digital-card/new`  | `?modal=digital-card/new`  | wired, off until digital cards ship, cell locked anyway |
-| Hold a **product card**  | the quick-actions sheet    | the quick-actions sheet    | yes                                                     |
+| Gesture                  | On `/products/<ean>`       | Everywhere else            | Enabled?                                      |
+| ------------------------ | -------------------------- | -------------------------- | --------------------------------------------- |
+| Hold **Karta**           | store preferences          | store preferences          | admins only, until the map drops `comingSoon` |
+| Hold **Praćenje**        | `?modal=watchlist&ean=…`   | nothing                    | yes                                           |
+| Hold the **centre cell** | the barcode scanner        | the barcode scanner        | yes                                           |
+| Hold **Popisi**          | `?modal=add-to-list&ean=…` | `?modal=shopping-list/new` | yes                                           |
+| Hold **Kartice**         | `?modal=digital-card/new`  | `?modal=digital-card/new`  | live                                          |
+| Hold a **product card**  | the quick-actions sheet    | the quick-actions sheet    | yes                                           |
 
 ### Targets that depend on the route
 
diff --git a/docs/PWA.md b/docs/PWA.md
index 15bf668d..f700b750 100644
--- a/docs/PWA.md
+++ b/docs/PWA.md
@@ -184,7 +184,7 @@ The masked one has to stay full bleed. Chrome hands a maskable icon to Android a
 
 **Skeniraj has no route of its own.** The scanner is imperative (`context/scanner-context.tsx`), so the shortcut points at `/?scan=1` and `components/custom/pwa/scan-shortcut.tsx` picks the flag up, strips it from the URL with `replaceState` before opening the camera (so a refresh or a back navigation does not reopen it), and routes the scanned code through `useProductNavigation`.
 
-Adding Karta and Digitalne kartice once they ship is tracked in [#127](https://github.com/OffCrazyFreak/Disscount/issues/127), which is really a "pick the final three" decision rather than an append.
+Digitalne kartice has since shipped and taken the second slot, so Android now shows Skeniraj, Kartice and Popisi, with Praćenje fourth and desktop only. The order is stated explicitly in `constants/pwa-shortcuts.ts` rather than inherited from `navigation.ts`, where a reshuffle would silently drop a shortcut off phones. Karta is still open in [#127](https://github.com/OffCrazyFreak/Disscount/issues/127).
 
 ### The install UX (`src/components/custom/pwa/`)
 
@@ -266,7 +266,7 @@ flowchart LR
 - `react-query-provider.tsx` uses `PersistQueryClientProvider`. The `QueryClient` sets a default `gcTime` equal to the persister `maxAge` (7 days), so entries are not garbage-collected out of memory before they can be restored from disk.
 - `persister.ts` builds a `createAsyncStoragePersister` backed by `idb-keyval` (IndexedDB, larger and safer than localStorage). `maxAge` 7 days, `buster` `"3"` (bump to invalidate all persisted caches after a breaking data-shape change; `"2"` was the `ShoppingListDto` reshape for sharing, `"3"` the move to a per-identity key).
 - `cache-identity.ts` scopes the IndexedDB entry to the signed-in account (`disscount-react-query-cache:<userId>`, or `:anon`). Before this there was one browser-wide blob shared by every account on a device, with a destructive purge as the only defence, which is why a shared list could not be persisted at all. The identity is mirrored in localStorage because the persister has to pick a key synchronously at boot, before the session resolves.
-- `cached-query-keys.ts` is the **whitelist**: only successful queries whose top-level key is in `cijene`, `shoppingLists`, `shoppingListItems`, `sharedShoppingList`, `watchlist`, `digitalCards`, `pinnedStores`, `pinnedPlaces`, or `users` are persisted. Keys under `cijene/prices` have a narrower allowlist: only `cijene/prices/product` is persisted, while every other `cijene/prices/*` key is excluded. Bulk product-list results under `cijene/prices/search`, for example, stay in the in-memory React Query cache and the bounded service-worker cache instead of accumulating in IndexedDB as searches and facets change. Canonical single-product price keys remain persisted for product-detail offline reads. Everything else (for example admin data) is never written to disk. Coming-soon features carry `TODO(offline)` markers here to be added when they ship.
+- `cached-query-keys.ts` is the **whitelist**: only successful queries whose top-level key is in `cijene`, `shoppingLists`, `shoppingListItems`, `sharedShoppingList`, `watchlist`, `digitalCards`, `storeNames`, `pinnedStores`, `pinnedPlaces`, or `users` are persisted. Keys under `cijene/prices` have a narrower allowlist: only `cijene/prices/product` is persisted, while every other `cijene/prices/*` key is excluded. Bulk product-list results under `cijene/prices/search`, for example, stay in the in-memory React Query cache and the bounded service-worker cache instead of accumulating in IndexedDB as searches and facets change. Canonical single-product price keys remain persisted for product-detail offline reads. Everything else (for example admin data) is never written to disk. Coming-soon features carry `TODO(offline)` markers here to be added when they ship.
 - `purge.ts` (`purgeOfflineCache`) removes user-specific queries from the in-memory cache, wipes the persisted snapshot, and deletes the `shared-list-pages`, `cijene-api` and `others` service worker buckets, matched by exact name rather than by substring so a bucket like `pages-rsc` is never caught by accident, guarded so a failed clear never blocks logout. Public `cijene` queries remain in memory and are persisted again on the next successful save, while in-flight cancellation is scoped to user-specific queries so logging out cannot abort a public price fetch. `user-context.tsx` calls it on **any change of identity**, which covers explicit logout, session expiry, a revoked cookie, sign-out in another tab, and one account replacing another. It deliberately does **not** fire merely because there is no session: that condition is true on every page load for a visitor who never logs in, and firing there wiped their queued offline writes on the next boot with no error and nothing left to replay.
 
 ### 5c. Offline UX
@@ -471,7 +471,7 @@ Read from `frontend/package.json`.
 
 - [ ] **App Badging API** (`navigator.setAppBadge`) for unread notifications on the installed icon.
 - [ ] **Service-worker "update available" prompt** (a toast when a new worker is waiting), which also fixes the "hard-refresh after deploy" gotcha in [`DEPLOYMENT.md`](DEPLOYMENT.md).
-- [ ] **Screen Wake Lock + max brightness** while showing a loyalty-card barcode (for the digital-cards rewrite).
+- [x] **Screen Wake Lock** while showing a loyalty-card barcode, in `hooks/use-wake-lock.ts`, held by the card view modal. There is no web API for brightness, so the code panel forces its own white background instead.
 - [ ] **Web Share** (outgoing) and **Share Target** (incoming) for products and lists.
 - [ ] **Native Barcode Detection** as a fast path on Android, keeping `@yudiel/react-qr-scanner` as the universal fallback.
 - [ ] **Real manifest screenshots** to replace the branded placeholder cards.
diff --git a/docs/README.md b/docs/README.md
index 5bdeaa18..cefbad9c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -11,4 +11,5 @@ Reference documentation for Disscount. Each file is a standalone deep-dive into
 - [SEARCH.md](SEARCH.md) - the shared matcher, diacritic folding, ranking, Croatian collation, and why there is no search library.
 - [LANDING.md](LANDING.md) - landing page composition, server-vs-client rendering, SEO, fonts.
 - [BRAND.md](BRAND.md) - brand image system (logo, favicon, PWA icons, splash screens, social kit).
+- [DIGITAL-CARDS.md](DIGITAL-CARDS.md) - the loyalty card wallet: code scanning and drawing, store autocomplete, colour contrast, offline.
 - [SUPPORT.md](SUPPORT.md) - Ko-fi support flow, GitHub funding links, and future recognition rules.
diff --git a/docs/SEARCH.md b/docs/SEARCH.md
index 652088f5..fce3dc6d 100644
--- a/docs/SEARCH.md
+++ b/docs/SEARCH.md
@@ -121,7 +121,7 @@ Calling `localeCompare` with no locale collates them as plain `c`, `s`, `z`, whi
 | Add to shopping list                                   | `app/products/components/forms/shopping-list-selector.tsx`       | list title via `keywords`           |
 | Updates / blog                                         | `app/updates/page.tsx`                                           | title, excerpt, content             |
 | Suggestions                                            | `app/suggestions/components/suggestions-client.tsx`              | suggestion fields                   |
-| Digital cards                                          | `app/(user)/digital-cards/components/digital-cards-client.tsx`   | title, type, note                   |
+| Digital cards                                          | `app/(user)/digital-cards/components/digital-cards-client.tsx`   | cardName, storeName, note           |
 | Shopping lists index                                   | `app/(user)/shopping-lists/components/shopping-lists-client.tsx` | title                               |
 | Watchlist                                              | `app/(user)/watchlist/hooks/use-watchlist-data.ts`               | product name, brand                 |
 | Watchlist suggestions                                  | `app/(user)/watchlist/hooks/use-watchlist-suggestions.ts`        | product name, brand                 |
diff --git a/docs/STATE-PERSISTENCE.md b/docs/STATE-PERSISTENCE.md
index 2c98723c..d7a72caa 100644
--- a/docs/STATE-PERSISTENCE.md
+++ b/docs/STATE-PERSISTENCE.md
@@ -125,7 +125,7 @@ Forms wired to drafts:
 | Watchlist item modal      | `watchlist-item-modal.tsx` | restore handled by the hook; one number per watch mode, `watchType` excluded |
 | Add to shopping list      | `use-add-to-list-form.ts`  | restore handled by the hook                                                  |
 | Shopping list create/edit | `shopping-list-modal.tsx`  | prefill-then-merge (`restore: false`)                                        |
-| Digital card create/edit  | `digital-card-modal.tsx`   | prefill-then-merge; also feeds scan-to-fill                                  |
+| Digital card create/edit  | `digital-card-modal.tsx`   | prefill-then-merge; `codeValue` excluded, retried through `modal-retry-bus`  |
 | Settings and onboarding   | `settings-modal-host.tsx`  | one shared draft, cleared after a successful save and onboarding completion  |
 | Contact                   | `contact-modal.tsx`        | prefill from profile, then merge draft on top                                |
 
@@ -255,7 +255,7 @@ The URL and localStorage layers use only browser-native APIs; there is no extra
 
 - **New-entity modals auto-restore; edit modals merge the draft themselves.** The shopping-list and digital-card modals pass `restore: !isEdit`: a brand-new list or card is rehydrated by the hook (its own effect re-runs when the draft key changes), while an edit modal loads its base record first and merges the draft on top with `restore: false` (draft wins). The contact modal is prefill-then-merge (`restore: false`). Letting the hook auto-restore an edit modal would double-reset and fight the prefill.
 
-- **Never draft passwords, base64 images, or card codes.** Pass them in `exclude`. Passwords must not touch disk, a base64 avatar would blow the localStorage quota, and the digital-card code (`value`) is excluded so a card number never persists. The avatar field lives outside forms and drafts entirely for this reason.
+- **Never draft passwords, base64 images, or card codes.** Pass them in `exclude`. Passwords must not touch disk, a base64 avatar would blow the localStorage quota, and the digital-card code (`codeValue`) is excluded so a card number never persists. Because that also means a failed save would come back without it, the in-flight code is stashed in `lib/modal/modal-retry-bus.ts`, an in-memory sibling of the error bus that dies with the tab: never on disk, fine in memory until the submit settles. The avatar field lives outside forms and drafts entirely for this reason.
 
 - **Old drafts are type-guarded on restore.** If a field's type changed since a draft was written (for example a number where the field is now a string), the restore skips it so a stale draft cannot poison validation. Keys the form no longer has at all are skipped too, so renaming or splitting a field cannot strand a dead entry for the rest of the TTL.
 
@@ -273,7 +273,7 @@ The URL and localStorage layers use only browser-native APIs; there is no extra
 
 - **localStorage preferences are per-device and are NOT purged on logout.** The IndexedDB data cache and the scoped service worker buckets are wiped when the identity changes. Preferences like view mode or the install-banner snooze are intentionally device-level and survive a logout.
 
-- **`viewModes` is wired but never written yet.** `useViewMode` returns `[mode, setMode]`, and both consumers (`products-client.tsx`, `digital-cards-client.tsx`) destructure the mode alone, because `ViewSwitcher` is parked behind [issue #61](https://github.com/OffCrazyFreak/Disscount/issues/61). So the key exists in the storage shape and in the hook, but nothing writes it and every list renders its default. Unparking the switcher means taking the setter at both call sites. Read the hook's own comment before changing it: the storage read is deliberately deferred to an effect, because `getViewMode` returns the default when there is no `window`, so seeding state from it directly would be a hydration mismatch.
+- **`viewModes` is wired but never written yet.** `useViewMode` returns `[mode, setMode]`, and its one consumer (`products-client.tsx`) destructures the mode alone, because `ViewSwitcher` is parked behind [issue #61](https://github.com/OffCrazyFreak/Disscount/issues/61). So the key exists in the storage shape and in the hook, but nothing writes it and every list renders its default. Unparking the switcher means taking the setter at both call sites. Read the hook's own comment before changing it: the storage read is deliberately deferred to an effect, because `getViewMode` returns the default when there is no `window`, so seeding state from it directly would be a hydration mismatch.
 
 ---
 

From 7f68588b71dba28b63e7ba3c9778580e9c990aae Mon Sep 17 00:00:00 2001
From: CrazyFreak <44674613+OffCrazyFreak@users.noreply.github.com>
Date: Fri, 7 Aug 2026 18:16:45 +0200
Subject: [PATCH 14/14] fix(digital-cards): Follow dev's offline error and
 draft conventions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Changes:
- Move the card write handlers into lib/offline/card-write-failed.ts, mirroring the list pair
- Report a failed write from the hook as well as the replay default, and drop the duplicate call-site toasts
- Silence a replayed delete that 404s, since the card being gone is the desired end state
- Strip only the code field from a legacy draft instead of the whole key
- Match the imperative validation copy the zod schemas moved to

Registering a handler only as a replay default was half a fix. A hook-level
onError replaces the default rather than running beside it, so a live failure
reported through whichever of the two happened to be attached, while the call
sites toasted a second time on top. The handler now sits in both places, and the
call sites only catch to keep the rejection from going unhandled.

Notes:
- Dropping the whole draft key took the user's half-typed name and note with the
  card number. removeFormDraftField, new on dev, removes just the sensitive field
  and carries the original savedAt so the rest keeps its own 24h clock.
- The backend validation copy is deliberately not changed: the imperative sweep was
  frontend-only, and UserRequest still reads "mora imati između", so the DTOs match
  their own side.
---
 .../components/forms/digital-card-modal.tsx   | 21 ++++++++++---------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
index 4312f881..f1b2e1db 100644
--- a/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
+++ b/frontend/src/app/(user)/digital-cards/components/forms/digital-card-modal.tsx
@@ -17,7 +17,10 @@ import { takeModalError } from "@/lib/modal/modal-error-bus";
 import { takeModalValues } from "@/lib/modal/modal-retry-bus";
 import { closeModalUrl } from "@/lib/modal/modal-navigation";
 import { useFormDraft } from "@/hooks/use-form-draft";
-import { getFormDraft, removeFormDraft } from "@/utils/browser/local-storage";
+import {
+  getFormDraft,
+  removeFormDraftField,
+} from "@/utils/browser/local-storage";
 import { LOADING_LABELS } from "@/constants/loading-labels";
 import extractDominantColor from "@/utils/browser/extract-dominant-color";
 import CardNameField from "@/app/(user)/digital-cards/components/forms/card-name-field";
@@ -43,14 +46,12 @@ interface IDigitalCardModalProps {
   id?: string;
 }
 
-// Drafts written before the code was excluded still hold a card number under the old
-// "value" field. Deleting the whole key is safer than trusting the shape of a draft
-// written by a build we no longer have.
-function dropLegacyDraft(draftKey: string): void {
-  const draft = getFormDraft(draftKey)?.values;
-  if (draft && ("value" in draft || "codeValue" in draft)) {
-    removeFormDraft(draftKey);
-  }
+// Drafts written before the code was excluded still hold a card number, under the old
+// "value" field or the current one. Only those fields go: the rest of a half-finished
+// card is the user's work and there is no reason to throw it away with them.
+function dropLegacyCode(draftKey: string): void {
+  removeFormDraftField(draftKey, "value");
+  removeFormDraftField(draftKey, "codeValue");
 }
 
 const EMPTY_VALUES: DigitalCardFormData = {
@@ -98,7 +99,7 @@ export default function DigitalCardModal({
   // Draft precedence controls restore order; the isDirty guard is what stops a
   // reload from clobbering an in-progress edit.
   useEffect(() => {
-    dropLegacyDraft(draftKey);
+    dropLegacyCode(draftKey);
   }, [draftKey]);
 
   useEffect(() => {