Refine manage overlay: US/CAN state abbreviations, share-QR caption, and an escalating second menu with named-face labels

Two rounds of follow-up work on the manage-button overlay:

1. Location formatting: US/Canada now show abbreviated state/province
   ("CA", "ON") instead of the full name, other countries show the full
   country name, and each is its own line (was one line, now wraps to
   two) so longer international place names have more room without
   threatening to overlap the top-right QR box. The bottom-left share QR
   also gets a "SCAN TO DOWNLOAD" caption.

2. Escalating menu: pressing the manage button again while its overlay
   is already up adds a second level -- each Immich-identified person's
   name labeled next to their face in the photo (using Immich's own
   face recognition/People data, no detection/recognition added to this
   project). A third press exits immediately instead of waiting out the
   30s auto-revert timer. No new Immich API needed -- GET /api/faces
   already embeds a nullable person.name per face; new
   server/app/face_labels.py maps a named face's box into the final
   800x480 frame's pixel space (reusing crop-box math extracted from
   image_pipeline.py's face-aware cropping). Capped at 4 named faces,
   sized to a real firmware RAM budget: each label is its own malloc'd
   overlay region on the device, alongside the 4 fixed corner regions
   already in use. New GET /frame/face-labels returns a flattened
   fixed-slot JSON shape (not a real array) so firmware's existing
   flat-scalar parser can read it without needing an actual array
   parser. No persistent state needed for the escalation itself -- it's
   all local control flow within one continuous awake session
   (frame_client.c's run_management_menu()).

firmware/main/manage_qr_overlay.c

@@ -134,13 +134,21 @@ static esp_err_t render_qr_region(const char *payload, const char *line1, const
     return ESP_OK;
 }
 
-/* White-padded box with a single centered line of text -- used for the
- * top-left location and bottom-right date-taken labels. */
-static esp_err_t render_text_region(const char *text, overlay_corner_t corner, manage_overlay_region_t *out)
+/* White-padded box with one or two centered lines of text (line2 may be
+ * NULL) -- used for the top-left location (city + state/country, two
+ * lines rather than cramming both onto one to keep the box from
+ * threatening to overlap the top-right QR box) and the bottom-right
+ * date-taken label (one line). */
+static esp_err_t render_text_region(const char *line1, const char *line2, overlay_corner_t corner,
+                                     manage_overlay_region_t *out)
 {
-    int text_w = (int)strlen(text) * Font24.Width;
+    int w1 = (int)strlen(line1) * Font24.Width;
+    int w2 = line2 != NULL ? (int)strlen(line2) * Font24.Width : 0;
+    int text_w = w1 > w2 ? w1 : w2;
+    int text_h = Font24.Height + (line2 != NULL ? LINE_GAP + Font24.Height : 0);
+
     int w = text_w + PADDING * 2;
-    int h = Font24.Height + PADDING * 2;
+    int h = text_h + PADDING * 2;
     w += w % 2;
 
     int stride = w / 2;
@@ -148,7 +156,13 @@ static esp_err_t render_text_region(const char *text, overlay_corner_t corner, m
     ESP_RETURN_ON_FALSE(buf != NULL, ESP_ERR_NO_MEM, TAG, "Failed to allocate overlay region");
     memset(buf, (EPD_COLOR_WHITE << 4) | EPD_COLOR_WHITE, (size_t)stride * h);
 
-    epd_draw_text_centered_ex(buf, stride, w, h, &Font24, text, w / 2, PADDING);
+    int center_x = w / 2;
+    int y = PADDING;
+    epd_draw_text_centered_ex(buf, stride, w, h, &Font24, line1, center_x, y);
+    if (line2 != NULL) {
+        y += Font24.Height + LINE_GAP;
+        epd_draw_text_centered_ex(buf, stride, w, h, &Font24, line2, center_x, y);
+    }
 
     out->buf = buf;
     out->w = w;
@@ -157,6 +171,58 @@ static esp_err_t render_text_region(const char *text, overlay_corner_t corner, m
     return ESP_OK;
 }
 
+/* Deliberately tighter than PADDING (used for the fixed QR/text corner
+ * boxes) -- these labels sit right next to a face rather than needing
+ * generous QR-scanning margin, and there can be several of them
+ * simultaneously (see MANAGE_FACE_LABELS_MAX's memory-budget note in
+ * the header). */
+#define FACE_LABEL_PADDING 8
+#define FACE_LABEL_GAP 4 /* distance from the face's anchor point to the label box */
+
+/* White-padded single-line name label positioned near an arbitrary
+ * (anchor_x, anchor_y) face position, rather than a fixed corner --
+ * unlike the four corner regions (always in-bounds by construction),
+ * this needs real clamping since a face can be anywhere, including near
+ * an edge. Centered horizontally on the face, placed just below it by
+ * default, flipped above if there's no room below. */
+static esp_err_t render_face_label_region(const char *name, int anchor_x, int anchor_y, manage_overlay_region_t *out)
+{
+    int text_w = (int)strlen(name) * Font24.Width;
+    int w = text_w + FACE_LABEL_PADDING * 2;
+    int h = Font24.Height + FACE_LABEL_PADDING * 2;
+    w += w % 2;
+
+    int stride = w / 2;
+    uint8_t *buf = malloc((size_t)stride * h);
+    ESP_RETURN_ON_FALSE(buf != NULL, ESP_ERR_NO_MEM, TAG, "Failed to allocate overlay region");
+    memset(buf, (EPD_COLOR_WHITE << 4) | EPD_COLOR_WHITE, (size_t)stride * h);
+    epd_draw_text_centered_ex(buf, stride, w, h, &Font24, name, w / 2, FACE_LABEL_PADDING);
+
+    int x0 = anchor_x - w / 2;
+    int y0 = anchor_y + FACE_LABEL_GAP;
+    if (y0 + h > EPD_HEIGHT) {
+        y0 = anchor_y - FACE_LABEL_GAP - h; /* no room below -- place above the face instead */
+    }
+    if (x0 < 0) {
+        x0 = 0;
+    } else if (x0 + w > EPD_WIDTH) {
+        x0 = EPD_WIDTH - w;
+    }
+    if (y0 < 0) {
+        y0 = 0;
+    } else if (y0 + h > EPD_HEIGHT) {
+        y0 = EPD_HEIGHT - h;
+    }
+    x0 -= x0 % 2; /* keep byte-aligned (2px/byte) */
+
+    out->buf = buf;
+    out->w = w;
+    out->h = h;
+    out->x0 = x0;
+    out->y0 = y0;
+    return ESP_OK;
+}
+
 esp_err_t manage_overlay_render(const manage_overlay_content_t *content, manage_overlay_set_t *out)
 {
     out->count = 0;
@@ -168,21 +234,38 @@ esp_err_t manage_overlay_render(const manage_overlay_content_t *content, manage_
     }
     out->count++;
 
-    if (content->location != NULL && content->location[0] != '\0') {
-        if (render_text_region(content->location, CORNER_TOP_LEFT, &out->regions[out->count]) == ESP_OK) {
+    if (content->location_line1 != NULL && content->location_line1[0] != '\0') {
+        const char *line2 =
+            (content->location_line2 != NULL && content->location_line2[0] != '\0') ? content->location_line2 : NULL;
+        if (render_text_region(content->location_line1, line2, CORNER_TOP_LEFT, &out->regions[out->count]) ==
+            ESP_OK) {
             out->count++;
         }
     }
 
     if (content->taken_at != NULL && content->taken_at[0] != '\0') {
-        if (render_text_region(content->taken_at, CORNER_BOTTOM_RIGHT, &out->regions[out->count]) == ESP_OK) {
+        if (render_text_region(content->taken_at, NULL, CORNER_BOTTOM_RIGHT, &out->regions[out->count]) == ESP_OK) {
             out->count++;
         }
     }
 
     if (content->share_url != NULL && content->share_url[0] != '\0') {
-        if (render_qr_region(content->share_url, NULL, NULL, CORNER_BOTTOM_LEFT, &out->regions[out->count]) ==
-            ESP_OK) {
+        if (render_qr_region(content->share_url, "SCAN TO", "DOWNLOAD", CORNER_BOTTOM_LEFT,
+                              &out->regions[out->count]) == ESP_OK) {
+            out->count++;
+        }
+    }
+
+    int face_count = content->face_label_count;
+    if (face_count > MANAGE_FACE_LABELS_MAX) {
+        face_count = MANAGE_FACE_LABELS_MAX;
+    }
+    for (int i = 0; content->face_labels != NULL && i < face_count; i++) {
+        const manage_face_label_t *label = &content->face_labels[i];
+        if (label->name[0] == '\0') {
+            continue;
+        }
+        if (render_face_label_region(label->name, label->x, label->y, &out->regions[out->count]) == ESP_OK) {
             out->count++;
         }
     }