Feat: living-library merge polish (Phase 3)

- /import returns added_urls + kept; merge_rows now returns the added rows.
- Client tags freshly-merged places (row._isNew) → a "✨ New" card badge,
floats them to the top of Browse (stable, transient — resets on reload).
- Merge banner reports "N new · M already in your library".
- Import card gains a Merge/Replace radio (#import-mode), shown only when a
cached library exists; a zero-overlap merge still offers Replace inline.

Completes the living-library feature (Phases 1–3). Visual review at mobile +
desktop; tests/test_merge.py extended (added_urls/kept) and green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CLAUDE.md

@@ -100,7 +100,12 @@ existing library CSV) folds the uploaded file into it via `_merge_rows(existing,
 so user-owned `status`/edits are never overwritten; only new keys are appended. `no_overlap`
 flags "nothing matched" (likely wrong file → client offers Replace). Client (`importPlacesFile`,
 `{forceReplace}`) sends `merge_into` from `localStorage.savedLibrary` unless restoring. Pinned
-by `tests/test_merge.py` (CI guardrail).
+by `tests/test_merge.py` (CI guardrail). `/import` also returns `added_urls` + `kept`: the client
+tags those rows `row._isNew` → a `.new-badge` ("✨ New") in `makeCard`, floats them to the top in
+`applyFilters` (stable sort, transient — resets on reload), and the banner reads "N new · M already
+in your library". The import card's `#import-mode` Merge/Replace radio (shown by `_syncImportMode`
+only when a cached library exists) sets `forceReplace`; a zero-overlap merge also offers Replace
+inline.
 
 **`POST /upload` living-library cost-skip (Phase 2).** `/upload` also accepts `merge_into`
 (the cached library CSV). `_run_pipeline` writes it into the job dir as the seed `places_full.csv`

README.md

@@ -331,7 +331,7 @@ The UI lets you:
 - **Stats summary** — place count, countries covered, geocoded fraction, and API cost shown at the top of the Browse tab
 - **KML round-trip** — city and state are embedded in each Placemark's description so re-importing the KML preserves full location data (not just country)
 - **Remembers your library (this device)** — after a run, the app caches your places in the browser (`localStorage`) and keeps the copy in sync as you mark places visited, edit fields, or pin them. Come back later and a **📦 Restore your last library** card brings everything back — visited status, edits, and pins included — with no re-upload and no re-extraction. It's stored only on your device and never uploaded; clearing your browser data removes it, so the Download buttons remain your permanent backup. Edits are flushed to the cache when you switch away from or close the tab, so a change made right before leaving isn't lost
-- **Living library — imports merge, not replace** — when you already have a library loaded and drop another KML/CSV, it's **merged into** your library keyed on the Instagram link (keep-existing-wins): your visited status and manual edits are preserved and only genuinely new places are added ("N new places added"). If nothing in the file matches your library, you're offered the choice to replace instead. This is the foundation for incrementally growing one map over time
+- **Living library — imports merge, not replace** — when you already have a library loaded and drop another KML/CSV, it's **merged into** your library keyed on the Instagram link (keep-existing-wins): your visited status and manual edits are preserved and only genuinely new places are added. Freshly-added places get a **✨ New** badge and float to the top of Browse, and the banner reports "N new · M already in your library". A **Merge / Replace** control on the import card (shown when a library exists) lets you choose; if nothing in the file matches your library, you're offered Replace inline. This is the foundation for incrementally growing one map over time
 - **Re-export costs nothing for places you already have** — when you re-run Extract on a fuller export months later, the app sends your existing library along, so the pipeline **skips the AI call on posts already in your map** and only extracts genuinely new ones (your visited status and pins are kept). A 600-post re-export where 550 are already mapped only pays to extract the 50 new ones
 
 ### Web UI providers

TODO.md

@@ -45,8 +45,10 @@ The paid competitors (Someday Map, Rezz, ReelsMap, Drawer) are all closed, cloud
     so `_warm_start_from_csv` skips the LLM on known posts (`new_urls` excludes them; progress
     says "X already in your library, skipped"), then `_merge_rows` folds results back so
     nothing is lost. `tests/test_merge.py` proves known posts never reach `analyze_batch`.
-  - [ ] **Phase 3 — polish.** New-to-top sort + "new" card badge; an explicit
-    merge-vs-replace toggle on the import card; a dedup/merge report.
+  - [x] **Phase 3 — polish (done).** `/import` returns `added_urls`+`kept`; freshly-merged
+    places get a "✨ New" card badge and float to the top of Browse (transient); the banner
+    reports "N new · M already in your library"; the import card has a Merge/Replace radio
+    (`#import-mode`, shown when a library exists). Living-library feature complete.
 - [ ] **HF Spaces live deploy** — code-complete (see `deploy/hf-spaces/`); remaining step is the manual "create the Space + push" in `deploy/hf-spaces/SETUP.md`, then add the live URL to README.
 - [ ] **Offline / privacy-first map targets (GPX + docs)** — KML and GPX import into Organic Maps and OsmAnd: fully offline, no account, works abroad with no data plan.
 - [ ] **Close the mobile consumption loop (docs)** — document the last mile of opening a custom Google My Map in the Google Maps app and navigating to a pin.

tests/test_merge.py

@@ -83,7 +83,8 @@ incoming = [
 merged, added = _merge_rows(existing, incoming)
 by_url = {r.get("instagram_url"): r for r in merged if r.get("instagram_url")}
 
-check("added count is 1 (only ccc is new)", added == 1)
+check("added count is 1 (only ccc is new)", len(added) == 1)
+check("added rows expose the new url", added[0].get("instagram_url") == "https://instagram.com/p/ccc")
 check("merged length = 4 (3 existing + 1 new)", len(merged) == 4)
 check("keep-existing-wins: Ichiran stays visited", by_url["https://instagram.com/p/aaa"]["status"] == "visited")
 check("new post ccc present", "https://instagram.com/p/ccc" in by_url)
@@ -95,7 +96,7 @@ check("URL-less existing kept as visited",
 
 # Idempotency: merging the existing set into itself adds nothing
 _, added_self = _merge_rows(existing, existing)
-check("idempotent: re-merge adds 0", added_self == 0)
+check("idempotent: re-merge adds 0", len(added_self) == 0)
 
 # Key shape
 check("_merge_key uses url when present", _merge_key(existing[0]).startswith("url:"))
@@ -120,6 +121,9 @@ try:
         check("route merge: status 200", r.status_code == 200)
         check("route merge: merged flag true", body.get("merged") is True)
         check("route merge: added == 1", body.get("added") == 1)
+        check("route merge: added_urls lists the new post",
+              body.get("added_urls") == ["https://instagram.com/p/ccc"])
+        check("route merge: kept == 2 (aaa + the URL-less dup matched)", body.get("kept") == 2)
         check("route merge: total rows == 4", body.get("rows") == 4)
         check("route merge: no_overlap false (aaa matched)", body.get("no_overlap") is False)
 

web/app.py

@@ -826,12 +826,14 @@ def _merge_key(row: dict) -> str:
     return "nc:" + name + "|" + city
 
 
-def _merge_rows(existing: list[dict], incoming: list[dict]) -> tuple[list[dict], int]:
+def _merge_rows(existing: list[dict], incoming: list[dict]) -> tuple[list[dict], list[dict]]:
     """Fold incoming rows into existing, keyed on _merge_key — keep-existing-wins.
 
     Existing rows are never dropped or overwritten, so user-owned status and
     manual edits are preserved (the status-is-user-owned invariant). Only
-    genuinely new keys are appended. Returns (merged_rows, added_count).
+    genuinely new keys are appended. Returns (merged_rows, added_rows) where
+    added_rows is the list of incoming rows that were new (use len() for the
+    count, instagram_url for badging).
     """
     seen: set[str] = set()
     merged: list[dict] = []
@@ -840,13 +842,13 @@ def _merge_rows(existing: list[dict], incoming: list[dict]) -> tuple[list[dict],
         if k not in seen:
             seen.add(k)
             merged.append(row)
-    added = 0
+    added: list[dict] = []
     for row in incoming:
         k = _merge_key(row)
         if k not in seen:
             seen.add(k)
             merged.append(row)
-            added += 1
+            added.append(row)
     return merged, added
 
 
@@ -1234,6 +1236,8 @@ async def import_places(file: UploadFile = File(...),
     # library (keep-existing-wins) when one is supplied.
     incoming_count = len(rows)
     added = incoming_count
+    added_urls: list[str] = []
+    kept = 0
     merged = False
     no_overlap = False
     if merge_into:
@@ -1242,7 +1246,10 @@ async def import_places(file: UploadFile = File(...),
         except ValueError:
             existing = []
         if existing:
-            rows, added = _merge_rows(existing, rows)
+            rows, added_rows = _merge_rows(existing, rows)
+            added = len(added_rows)
+            added_urls = [r["instagram_url"] for r in added_rows if r.get("instagram_url")]
+            kept = incoming_count - added         # posts the file shared with the library
             merged = True
             no_overlap = added == incoming_count  # nothing matched → maybe wrong file
 
@@ -1268,7 +1275,8 @@ async def import_places(file: UploadFile = File(...),
     _persist_state(job_id, state)
 
     return {"job_id": job_id, "rows": len(rows), "pinned": pinned,
-            "added": added, "merged": merged, "no_overlap": no_overlap}
+            "added": added, "added_urls": added_urls, "kept": kept,
+            "merged": merged, "no_overlap": no_overlap}
 
 
 if __name__ == "__main__":

web/static/app.css

@@ -657,6 +657,25 @@
   .rest-card.status-closed   { opacity: 0.45; }
   .rest-card.status-closed .card-name { color: var(--muted); }
 
+  /* Freshly-merged "new" places */
+  .rest-card.is-new { border-color: var(--ig2); }
+  .new-badge {
+    position: absolute; top: 10px; right: 24px;
+    font-size: 0.62rem; font-weight: 700; letter-spacing: 0.3px;
+    padding: 2px 7px; border-radius: 100px;
+    background: linear-gradient(135deg, var(--ig1), var(--ig2));
+    color: #fff;
+  }
+
+  /* Import card: Merge vs Replace control (shown when a library exists) */
+  .import-mode {
+    margin-top: 12px; font-size: 0.82rem;
+    display: flex; flex-wrap: wrap; gap: 6px 14px; align-items: center;
+  }
+  .import-mode-label { width: 100%; color: var(--muted); }
+  .import-mode label { display: inline-flex; align-items: center; gap: 5px; cursor: pointer; color: var(--text); }
+  .import-mode input { accent-color: var(--ig1); }
+
   .card-name {
     font-size: 0.95rem; font-weight: 800;
     margin-bottom: 3px; padding-right: 20px;

web/static/app.js

@@ -147,7 +147,15 @@ async function importPlacesFile(file, statusEl, { forceReplace = false } = {}) {
   $('download-csv-btn').onclick = () => { window.location = '/download/' + data.job_id + '/csv'; };
   showSubTab('browse');
   await loadResults(data.job_id);
-  if (data.merged) _showMergeBanner(data, file);
+  if (data.merged) {
+    // Tag the freshly-added rows so Browse can badge them and float them to top.
+    if (data.added_urls && data.added_urls.length) {
+      const fresh = new Set(data.added_urls);
+      allRows.forEach(r => { if (fresh.has(r.instagram_url)) r._isNew = true; });
+      applyFilters();
+    }
+    _showMergeBanner(data, file);
+  }
   if (_clientGeocode) geocodeClientSide();
   return data.job_id;
 }
@@ -157,12 +165,13 @@ async function importPlacesFile(file, statusEl, { forceReplace = false } = {}) {
 function _showMergeBanner(data, file) {
   const banner = $('new-banner'), txt = $('new-banner-text');
   if (!banner || !txt) return;
-  const n = data.added;
+  const n = data.added, kept = data.kept || 0;
   if (data.no_overlap && n > 0) {
     txt.innerHTML = `Added <strong>${n}</strong> place${n === 1 ? '' : 's'} — none matched your existing library. `
       + `<a href="#" id="merge-replace-link">Replace instead?</a>`;
   } else if (n > 0) {
-    txt.textContent = `${n} new place${n === 1 ? '' : 's'} added to your library`;
+    const keptNote = kept ? ` · ${kept} already in your library` : '';
+    txt.textContent = `${n} new place${n === 1 ? '' : 's'} added${keptNote}`;
   } else {
     txt.textContent = 'No new places — everything in that file was already in your library';
   }
@@ -190,14 +199,25 @@ async function handleImportFile(f) {
   $('import-file-chosen').style.display = 'block';
   status.textContent = 'Importing…';
   status.classList.remove('error');
+  const modeEl = document.querySelector('input[name="import-mode"]:checked');
+  const forceReplace = modeEl ? modeEl.value === 'replace' : false;
   try {
-    await importPlacesFile(f, status);
+    await importPlacesFile(f, status, { forceReplace });
   } catch (err) {
     status.textContent = '⚠ ' + err.message;
     status.classList.add('error');
   }
 }
 
+// Show the Merge/Replace control on the import card only when a cached library
+// exists (otherwise an import is always a fresh start — nothing to merge into).
+function _syncImportMode() {
+  const el = $('import-mode');
+  if (!el) return;
+  const lib = _readSavedLibrary();
+  el.style.display = (lib && lib.csv) ? 'block' : 'none';
+}
+
 // ── Client-side library persistence (localStorage) ─────────────────────────
 // Cache the canonical CSV so a returning visitor restores their library without
 // re-uploading or re-extracting. Reconstruction-cache only: restore replays the
@@ -1106,6 +1126,11 @@ function applyFilters() {
   const ft = $('food-toggle');
   if (ft) ft.classList.toggle('active', filterState.foodOnly);
 
+  // Float just-merged "new" places to the top (stable; only after a merge).
+  if (allRows.some(r => r._isNew)) {
+    rows = [...rows].sort((a, b) => (b._isNew ? 1 : 0) - (a._isNew ? 1 : 0));
+  }
+
   renderGrid(rows);
   renderMap(rows);
   $('result-count').textContent = rows.length === allRows.length
@@ -1175,9 +1200,17 @@ function val(v) { return (!v || v === 'UNKNOWN') ? '' : v; }
 
 function makeCard(row) {
   const card = document.createElement('div');
-  card.className = 'rest-card' + (row.geocoded ? '' : ' missing-pin');
+  card.className = 'rest-card' + (row.geocoded ? '' : ' missing-pin') + (row._isNew ? ' is-new' : '');
   card.dataset.url = row.instagram_url;
 
+  // "New" badge — set on rows just added by a merge (transient, resets on reload)
+  if (row._isNew) {
+    const nb = document.createElement('div');
+    nb.className = 'new-badge';
+    nb.textContent = '✨ New';
+    card.appendChild(nb);
+  }
+
   // Pin badge
   const badge = document.createElement('div');
   badge.className = 'pin-badge ' + (row.geocoded ? 'pin-ok' : 'pin-missing');
@@ -1653,5 +1686,7 @@ $('feedback-submit').addEventListener('click', () => {
 });
 
 // ── Boot ───────────────────────────────────────────────────────────────────
-// Offer to restore a previously cached library (no live job → returning visitor).
+// Offer to restore a previously cached library (no live job → returning visitor),
+// and show the import card's Merge/Replace control when a library exists.
 maybeShowRestore();
+_syncImportMode();

web/templates/index.html

@@ -271,6 +271,11 @@
       <div class="drop-sub">places_map.kml · places_full.csv — click to browse</div>
       <div class="file-chosen" id="import-file-chosen"></div>
     </div>
+    <div class="import-mode" id="import-mode" style="display:none;">
+      <span class="import-mode-label">You already have a saved library:</span>
+      <label><input type="radio" name="import-mode" value="merge" checked> Merge in (keep status &amp; edits)</label>
+      <label><input type="radio" name="import-mode" value="replace"> Replace it</label>
+    </div>
     <div class="status-msg" id="import-status" style="margin-top:10px;"></div>
   </div>