Spaces:

harshith99
/

ig-v1

Runtime error

harshith99 Claude Sonnet 4.6 commited on Jun 10

Commit

5c44de2

1 Parent(s): 23dabb1

UX: add guided tour, pipeline timing note

- tour.js: 6-step spotlight tour (upload → model → run → reimport → roulette → pipeline diagram); simulates tab navigation and temporarily reveals sub-tab-bar in demo mode; triggered by ▶ Take the tour button in FAQ
- Progress card: static timing note ("usually 5–10 min — may appear stuck") so users don't abandon a running job
- app.css: tour overlay/spotlight/tooltip styles + .progress-timing-note + .tour-cta-card/.btn-tour

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Files changed (5) hide show

CLAUDE.md +6 -3
README.md +2 -1
web/static/app.css +140 -0
web/static/tour.js +213 -0
web/templates/index.html +11 -1

CLAUDE.md CHANGED Viewed

@@ -32,9 +32,11 @@ pipeline/          shared core (used by CLI, Docker, web)
 web/app.py         FastAPI: pipeline, SSE progress, results browser, resolve_provider()
                    POST /import — KML or CSV re-import (no extraction, skip to tabs)
 web/static/        served at /static/ via FastAPI StaticFiles mount
-  app.css          all styles (~820 lines, no Jinja)
   app.js           all client JS (~1280 lines, no Jinja — reads config from body data-* attrs)
-web/templates/index.html  HTML skeleton only (~465 lines); Jinja vars passed to JS via
                    <body data-ollama-enabled data-client-geocode data-default-model
                          data-default-ollama-model>
 tests/             runnable scripts (NOT pytest) — see Conventions
@@ -58,7 +60,7 @@ The app has a **permanent two-level nav** visible from first page load:
                 └── [🎲 Roulette] [📋 Browse]  ← #sub-tab-bar, after data loads
 ```
-- **Extract tab** (`#top-panel-extract`): upload card, model picker, run button, progress card.
 - **Explore tab** (`#top-panel-explore`): import card at top; once data loads the import card hides
   and `#sub-tab-bar` appears with two sub-panels.
 - After extraction completes → `showTopTab('explore')` → `showSubTabBar(jobId)` → `showSubTab('roulette')` (auto-spins) + nudge toast.
@@ -83,6 +85,7 @@ Key JS functions:
 - `showSubTabBar(jobId)` — hides import card, reveals `#sub-tab-bar` + `#download-bar` inside Explore
 - `showSubTab(name)` — switches sub-panels (roulette / browse); auto-spins roulette on first visit
 - `updateTabBadges()` — sets badge counts and stat strip
 KML parser convention: folder nesting = country (outer) → city (inner); `<coordinates>` order is
 **lng,lat,alt**; description CDATA uses `"  ·  "` separator for category · cuisine · price.

 web/app.py         FastAPI: pipeline, SSE progress, results browser, resolve_provider()
                    POST /import — KML or CSV re-import (no extraction, skip to tabs)
 web/static/        served at /static/ via FastAPI StaticFiles mount
+  app.css          all styles (~1150 lines, no Jinja)
   app.js           all client JS (~1280 lines, no Jinja — reads config from body data-* attrs)
+  tour.js          guided tour (IIFE, ~210 lines); exposes window.startTour / window.endTour;
+                   requires app.js globals showTopTab, showSubTab, currentJobId
+web/templates/index.html  HTML skeleton only (~500 lines); Jinja vars passed to JS via
                    <body data-ollama-enabled data-client-geocode data-default-model
                          data-default-ollama-model>
 tests/             runnable scripts (NOT pytest) — see Conventions
                 └── [🎲 Roulette] [📋 Browse]  ← #sub-tab-bar, after data loads
 ```
+- **Extract tab** (`#top-panel-extract`): upload card, model picker, run button, progress card. The progress card includes a static `.progress-timing-note` ("usually 5–10 min — may appear stuck") so users don't abandon a running job.
 - **Explore tab** (`#top-panel-explore`): import card at top; once data loads the import card hides
   and `#sub-tab-bar` appears with two sub-panels.
 - After extraction completes → `showTopTab('explore')` → `showSubTabBar(jobId)` → `showSubTab('roulette')` (auto-spins) + nudge toast.
 - `showSubTabBar(jobId)` — hides import card, reveals `#sub-tab-bar` + `#download-bar` inside Explore
 - `showSubTab(name)` — switches sub-panels (roulette / browse); auto-spins roulette on first visit
 - `updateTabBadges()` — sets badge counts and stat strip
+- `startTour()` / `endTour()` — guided tour (defined in `tour.js`); works without data loaded by temporarily revealing the sub-tab-bar in demo mode and restoring state on exit. The FAQ tab has a `.tour-cta-card` with a `▶ Take the tour` button (`onclick="startTour()"`).
 KML parser convention: folder nesting = country (outer) → city (inner); `<coordinates>` order is
 **lng,lat,alt**; description CDATA uses `"  ·  "` separator for category · cuisine · price.

README.md CHANGED Viewed

@@ -307,8 +307,9 @@ The UI lets you:
   - **🗺 Explore** — for returning users; drop your `places_map.kml` or `places_full.csv` here to skip re-extraction entirely. Once data loads, two sub-tabs appear:
     - **🎲 Roulette** — auto-spins the moment you land on it; filter by category or location (accepts city name or country name); badge shows how many unvisited spots remain. Default after extraction
     - **📋 Browse** — stats bar, interactive Leaflet map, full-text search, filters, card grid, and KML / GeoJSON / CSV download buttons. Default after import
-  - **❓ FAQ** — system pipeline diagram, About The Belagurian, and answers to common questions
   - After extraction completes, the app automatically jumps to Explore → Roulette and spins immediately
 - **Preview pins on a map** — an in-app Leaflet/OpenStreetMap map renders every geocoded place so you can sanity-check for misplaced pins before exporting. Follows your active filters; pins link back to the original reel
 - **Filter and search** — text search by name/city, country, category, and cuisine dropdowns, multi-select price range chips, "missing pins" toggle, and a **🍴 Food only** toggle (on by default) that limits Browse and Roulette to food/drink places (Restaurant, Bar, Cafe, Bakery, Market) — all client-side with instant results
 - **Fix extractions inline** — click any field (name, city, state, category, cuisine, occasion) directly on the card to edit it; changes are saved to the CSV immediately

   - **🗺 Explore** — for returning users; drop your `places_map.kml` or `places_full.csv` here to skip re-extraction entirely. Once data loads, two sub-tabs appear:
     - **🎲 Roulette** — auto-spins the moment you land on it; filter by category or location (accepts city name or country name); badge shows how many unvisited spots remain. Default after extraction
     - **📋 Browse** — stats bar, interactive Leaflet map, full-text search, filters, card grid, and KML / GeoJSON / CSV download buttons. Default after import
+  - **❓ FAQ** — system pipeline diagram, About The Belagurian, and answers to common questions. Includes a **▶ Take the tour** button that runs a 6-step guided walkthrough of the full workflow (upload → model → run → re-import → roulette → pipeline diagram), with spotlight highlighting and simulated tab navigation
   - After extraction completes, the app automatically jumps to Explore → Roulette and spins immediately
+- **Pipeline timing note** — the progress card shows a persistent note ("usually 5–10 min — the bar may appear stuck during AI extraction") so users don't think the app is broken
 - **Preview pins on a map** — an in-app Leaflet/OpenStreetMap map renders every geocoded place so you can sanity-check for misplaced pins before exporting. Follows your active filters; pins link back to the original reel
 - **Filter and search** — text search by name/city, country, category, and cuisine dropdowns, multi-select price range chips, "missing pins" toggle, and a **🍴 Food only** toggle (on by default) that limits Browse and Roulette to food/drink places (Restaurant, Bar, Cafe, Bakery, Market) — all client-side with instant results
 - **Fix extractions inline** — click any field (name, city, state, category, cuisine, occasion) directly on the card to edit it; changes are saved to the CSV immediately

web/static/app.css CHANGED Viewed

@@ -1010,3 +1010,143 @@
     border-radius: 4px;
     padding: 1px 5px;
   }

     border-radius: 4px;
     padding: 1px 5px;
   }
+  /* ── Pipeline timing note ─────────────────────────────────── */
+  .progress-timing-note {
+    margin-top: 14px;
+    padding: 10px 13px;
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    font-size: 0.78rem;
+    color: var(--muted);
+    line-height: 1.55;
+  }
+  .progress-timing-note strong { color: var(--text); }
+  /* ── Tour overlay & spotlight ─────────────────────────────── */
+  #tour-overlay {
+    display: none;
+    position: fixed;
+    inset: 0;
+    z-index: 10000;
+    background: transparent;
+    pointer-events: all;
+  }
+  .tour-spotlight {
+    position: relative !important;
+    z-index: 10001 !important;
+    box-shadow: 0 0 0 4px var(--ig1), 0 0 0 9999px rgba(0,0,0,0.62) !important;
+    border-radius: 10px;
+  }
+  /* ── Tour tooltip ─────────────────────────────────────────── */
+  #tour-tooltip {
+    display: none;
+    position: fixed;
+    z-index: 10002;
+    flex-direction: column;
+    gap: 10px;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 14px;
+    box-shadow: 0 8px 32px rgba(0,0,0,0.45);
+    padding: 18px 20px 14px;
+    max-width: 320px;
+    min-width: 260px;
+    font-size: 0.88rem;
+    line-height: 1.5;
+  }
+  #tour-close {
+    position: absolute;
+    top: 10px; right: 12px;
+    background: none;
+    border: none;
+    cursor: pointer;
+    font-size: 1rem;
+    color: var(--muted);
+    padding: 2px 6px;
+    border-radius: 4px;
+    line-height: 1;
+  }
+  #tour-close:hover { background: var(--surface2); }
+  #tour-title {
+    font-weight: 700;
+    font-size: 0.95rem;
+    padding-right: 24px;
+    color: var(--text);
+  }
+  #tour-body { color: var(--muted); }
+  #tour-body code {
+    font-family: monospace;
+    font-size: 0.8rem;
+    color: var(--text);
+    background: var(--surface2);
+    padding: 1px 5px;
+    border-radius: 3px;
+  }
+  #tour-body strong, #tour-body em { color: var(--text); font-style: normal; }
+  #tour-footer {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-top: 4px;
+  }
+  #tour-counter { font-size: 0.75rem; color: var(--muted); }
+  #tour-btns    { display: flex; gap: 8px; }
+  #tour-back, #tour-next, #tour-finish {
+    font-size: 0.82rem;
+    padding: 5px 13px;
+    border-radius: 6px;
+    border: 1px solid var(--border);
+    cursor: pointer;
+    background: var(--surface2);
+    color: var(--text);
+    transition: background 0.15s;
+  }
+  #tour-back:hover { background: var(--border); }
+  #tour-next, #tour-finish {
+    background: var(--ig1);
+    color: #fff;
+    border-color: var(--ig1);
+  }
+  #tour-next:hover, #tour-finish:hover { filter: brightness(1.12); }
+  /* ── Take the tour button in FAQ ──────────────────────────── */
+  .tour-cta-card {
+    max-width: 640px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+    flex-wrap: wrap;
+  }
+  .tour-cta-card p {
+    font-size: 0.88rem;
+    color: var(--muted);
+    flex: 1;
+    min-width: 0;
+  }
+  .btn-tour {
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    gap: 7px;
+    padding: 9px 18px;
+    background: var(--ig1);
+    color: #fff;
+    border: none;
+    border-radius: 8px;
+    font-size: 0.88rem;
+    font-weight: 600;
+    cursor: pointer;
+    white-space: nowrap;
+    transition: filter 0.15s;
+  }
+  .btn-tour:hover { filter: brightness(1.12); }

web/static/tour.js ADDED Viewed

	@@ -0,0 +1,213 @@

+// Guided tour — triggered by "Take the tour" button in FAQ tab.
+// Requires app.js globals: showTopTab, showSubTab, currentJobId.
+(function () {
+  let _step    = -1;
+  let _overlay = null;
+  let _tooltip = null;
+  let _spotlit = null;
+  // Explore state before demo mode (we temporarily show sub-tab-bar)
+  let _savedState = null;
+  function _saveExploreState() {
+    return {
+      subTabBar:  document.getElementById('sub-tab-bar').style.display,
+      importCard: document.getElementById('import-card').style.display,
+    };
+  }
+  function _restoreExploreState() {
+    if (!_savedState) return;
+    document.getElementById('sub-tab-bar').style.display  = _savedState.subTabBar;
+    document.getElementById('import-card').style.display  = _savedState.importCard;
+    _savedState = null;
+  }
+  // ── Step definitions ───────────────────────────────────────────────────────
+  const STEPS = [
+    {
+      id: 'upload-card',
+      pre() { showTopTab('extract'); },
+      title: '📂 Upload your export',
+      body:  'Drop your Instagram ZIP or <code>saved_posts.json</code> here. No unzipping needed — the ZIP works as-is.',
+    },
+    {
+      id: 'model-card',
+      title: '🤖 Choose your AI',
+      body:  '<strong>Claude API</strong> is fast (bring your Anthropic key). <strong>Ollama</strong> is free and fully local. <strong>Free chatbot</strong> needs no API key — paste posts into ChatGPT or Claude.ai.',
+    },
+    {
+      id: 'run-btn-wrap',
+      title: '🚀 Extract & geocode',
+      body:  'Hit <em>Extract places</em>. AI reads captions, OpenStreetMap geocodes each place, and a KML file is built — ready to import into Google My Maps.',
+    },
+    {
+      id: 'import-card',
+      pre() {
+        if (_savedState) {
+          // Restore before we navigate back to import card
+          const st = _savedState;
+          _savedState = null;
+          document.getElementById('sub-tab-bar').style.display  = st.subTabBar;
+          document.getElementById('import-card').style.display  = st.importCard;
+        }
+        showTopTab('explore');
+      },
+      title: '📁 Re-import a previous run',
+      body:  'Already have a <code>places_map.kml</code> or <code>places_full.csv</code>? Drop it here to skip extraction and jump straight to browsing — no re-running needed.',
+    },
+    {
+      id: 'roulette-section',
+      pre() {
+        if (!_savedState) _savedState = _saveExploreState();
+        document.getElementById('import-card').style.display = 'none';
+        document.getElementById('sub-tab-bar').style.display = 'block';
+        showSubTab('roulette');
+      },
+      title: '🎲 Place Roulette',
+      body:  "Can't decide where to go? Spin the wheel for a random pick from your saved places. Filter by city, distance, or category.",
+    },
+    {
+      id: 'faq-pipeline-card',
+      pre() {
+        if (_savedState && !currentJobId) _restoreExploreState();
+        showTopTab('faq');
+      },
+      title: '🔍 Everything runs local-first',
+      body:  'Pre-filter → AI extraction → Nominatim geocoding → KML / GeoJSON / CSV export. Your Instagram data never leaves your device (except the AI call you pick).',
+      last: true,
+    },
+  ];
+  // ── DOM setup ──────────────────────────────────────────────────────────────
+  function _ensureDOM() {
+    if (_overlay) return;
+    _overlay = document.createElement('div');
+    _overlay.id = 'tour-overlay';
+    document.body.appendChild(_overlay);
+    _overlay.addEventListener('click', endTour);
+    _tooltip = document.createElement('div');
+    _tooltip.id = 'tour-tooltip';
+    _tooltip.innerHTML =
+      '<button id="tour-close" title="Exit tour">✕</button>' +
+      '<div id="tour-title"></div>' +
+      '<div id="tour-body"></div>' +
+      '<div id="tour-footer">' +
+        '<span id="tour-counter"></span>' +
+        '<div id="tour-btns">' +
+          '<button id="tour-back">← Back</button>' +
+          '<button id="tour-next">Next →</button>' +
+          '<button id="tour-finish">Finish ✓</button>' +
+        '</div>' +
+      '</div>';
+    document.body.appendChild(_tooltip);
+    document.getElementById('tour-close').addEventListener('click', endTour);
+    document.getElementById('tour-back').addEventListener('click', () => goToStep(_step - 1));
+    document.getElementById('tour-next').addEventListener('click', () => goToStep(_step + 1));
+    document.getElementById('tour-finish').addEventListener('click', endTour);
+  }
+  // ── Spotlight ──────────────────────────────────────────────────────────────
+  function _applySpotlight(el) {
+    _clearSpotlight();
+    _spotlit = el;
+    el.classList.add('tour-spotlight');
+  }
+  function _clearSpotlight() {
+    if (_spotlit) { _spotlit.classList.remove('tour-spotlight'); _spotlit = null; }
+  }
+  // ── Tooltip positioning ────────────────────────────────────────────────────
+  function _positionTooltip(el) {
+    const tt = _tooltip;
+    tt.style.visibility = 'hidden';
+    tt.style.display    = 'flex';
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        const rect   = el.getBoundingClientRect();
+        const ttH    = tt.offsetHeight;
+        const ttW    = tt.offsetWidth;
+        const vW     = window.innerWidth;
+        const vH     = window.innerHeight;
+        const GAP    = 14;
+        const EDGE   = 12;
+        let top, left;
+        if (rect.bottom + GAP + ttH <= vH - EDGE) {
+          // Below target
+          top  = rect.bottom + GAP;
+          left = rect.left + rect.width / 2 - ttW / 2;
+        } else if (rect.top - GAP - ttH >= EDGE) {
+          // Above target
+          top  = rect.top - ttH - GAP;
+          left = rect.left + rect.width / 2 - ttW / 2;
+        } else {
+          // Centre of viewport
+          top  = (vH - ttH) / 2;
+          left = (vW - ttW) / 2;
+        }
+        left = Math.max(EDGE, Math.min(left, vW - ttW - EDGE));
+        top  = Math.max(EDGE, Math.min(top,  vH - ttH - EDGE));
+        tt.style.top        = top  + 'px';
+        tt.style.left       = left + 'px';
+        tt.style.visibility = 'visible';
+      });
+    });
+  }
+  // ── Navigation ─────────────────────────────────────────────────────────────
+  function goToStep(n) {
+    if (n < 0 || n >= STEPS.length) return;
+    _step = n;
+    const s = STEPS[n];
+    if (s.pre) s.pre();
+    const el = document.getElementById(s.id);
+    if (!el) return;
+    el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    setTimeout(() => {
+      _applySpotlight(el);
+      _overlay.style.display = 'block';
+      document.getElementById('tour-title').textContent = s.title;
+      document.getElementById('tour-body').innerHTML    = s.body;
+      document.getElementById('tour-counter').textContent = (n + 1) + ' / ' + STEPS.length;
+      document.getElementById('tour-back').style.display   = n === 0       ? 'none' : '';
+      document.getElementById('tour-next').style.display   = s.last        ? 'none' : '';
+      document.getElementById('tour-finish').style.display = s.last        ? ''     : 'none';
+      _positionTooltip(el);
+    }, 280);
+  }
+  // ── Public API ─────────────────────────────────────────────────────────────
+  function startTour() {
+    _ensureDOM();
+    _savedState = null;
+    goToStep(0);
+  }
+  function endTour() {
+    _clearSpotlight();
+    if (_overlay) _overlay.style.display = 'none';
+    if (_tooltip) _tooltip.style.display = 'none';
+    if (_savedState && !currentJobId) _restoreExploreState();
+    _step = -1;
+  }
+  window.startTour = startTour;
+  window.endTour   = endTour;
+})();

web/templates/index.html CHANGED Viewed

@@ -205,6 +205,9 @@
       </div>
     </div>
     <div class="status-msg" id="status-msg"></div>
   </div>
 </div><!-- /top-panel-extract -->
@@ -378,8 +381,14 @@
 <!-- ══ FAQ / About panel ═══════════════════════════════════════ -->
 <div class="top-panel" id="top-panel-faq">
   <!-- System diagram -->
-  <div class="card" style="max-width:640px;">
     <p class="card-title">How it works</p>
     <div class="pipeline-diagram">
       <div class="pipe-node">
@@ -488,5 +497,6 @@
 <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
         integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin=""></script>
 <script src="/static/app.js"></script>
 </body>
 </html>

       </div>
     </div>
     <div class="status-msg" id="status-msg"></div>
+    <p class="progress-timing-note">
+      <strong>⏱ This usually takes 5–10 min.</strong> The progress bar may appear stuck while the AI reads your captions in bulk — it's still running. Keep this tab open.
+    </p>
   </div>
 </div><!-- /top-panel-extract -->
 <!-- ══ FAQ / About panel ═══════════════════════════════════════ -->
 <div class="top-panel" id="top-panel-faq">
+  <!-- Tour CTA -->
+  <div class="card tour-cta-card">
+    <p>New here? Take a 60-second walkthrough of the full workflow — upload, extract, roulette, and browse.</p>
+    <button class="btn-tour" onclick="startTour()">▶ Take the tour</button>
+  </div>
   <!-- System diagram -->
+  <div class="card" id="faq-pipeline-card" style="max-width:640px;">
     <p class="card-title">How it works</p>
     <div class="pipeline-diagram">
       <div class="pipe-node">
 <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
         integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo=" crossorigin=""></script>
 <script src="/static/app.js"></script>
+<script src="/static/tour.js"></script>
 </body>
 </html>